diff --git a/.github/ISSUE_TEMPLATE/config.yml b/.github/ISSUE_TEMPLATE/config.yml index 08d72ae9..764e08ea 100644 --- a/.github/ISSUE_TEMPLATE/config.yml +++ b/.github/ISSUE_TEMPLATE/config.yml @@ -1,5 +1,8 @@ blank_issues_enabled: true contact_links: + - name: Support Hub - Ongoing Help and Q&A + url: https://github.com/Community-Access/support + about: Post-workshop support, troubleshooting, and alumni discussion live in the open support hub. - name: "Student Opt-In for GIT Going with GitHub" url: https://community-access.org/git-going-with-github/REGISTER.html about: Self-serve opt-in workflow (GitHub issue form with automated confirmation and waitlist handling). @@ -17,4 +20,4 @@ contact_links: about: Full workshop guide - start here if you are new to this repository. - name: Discussion Forum - Questions, Introductions, Ideas url: https://github.com/community-access/git-going-with-github/discussions - about: Ask questions, connect with other participants, and share ideas before, during, and after the workshop. + about: Workshop repository discussions for curriculum and event operations. diff --git a/.github/ISSUE_TEMPLATE/workshop-registration.yml b/.github/ISSUE_TEMPLATE/workshop-registration.yml index c759d1e2..d6937b0f 100644 --- a/.github/ISSUE_TEMPLATE/workshop-registration.yml +++ b/.github/ISSUE_TEMPLATE/workshop-registration.yml @@ -85,6 +85,6 @@ body: 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. + **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, use the support hub: [Community-Access/support](https://github.com/Community-Access/support). Welcome aboard. You belong here. diff --git a/.github/README.md b/.github/README.md index dcc2684d..fe59954f 100644 --- a/.github/README.md +++ b/.github/README.md @@ -80,6 +80,7 @@ The Classroom model equivalents live in [learning-room/.github/workflows/](../le ## Quick Links - [Workshop Deployment Guide](../classroom/README.md) -- full setup using GitHub Classroom +- [Support Hub](https://github.com/Community-Access/support) -- post-workshop support and async Q&A - [Template Repository Content](../learning-room/.github/) -- automation that runs in each student's repo - [Student Guide](../learning-room/.github/STUDENT_GUIDE.md) -- how students interact with Aria bot - [Challenge Progression Config](data/challenge-progression.json) -- level and badge definitions diff --git a/.github/workflows/registration.yml b/.github/workflows/registration.yml index 01d3b0b0..6536b38b 100644 --- a/.github/workflows/registration.yml +++ b/.github/workflows/registration.yml @@ -65,7 +65,7 @@ jobs: 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.` + Questions? [File a support issue](https://github.com/Community-Access/support/issues) in the support hub.` }); await github.rest.issues.addLabels({ @@ -132,7 +132,7 @@ jobs: 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.` + Questions? [File a support issue](https://github.com/Community-Access/support/issues) in the support hub.` }); await github.rest.issues.addLabels({ @@ -246,7 +246,9 @@ jobs: ${classroomSection} - If you have any questions, [file an issue](https://github.com/community-access/git-going-with-github/issues) in the workshop repository. + If you have any questions, use the support hub: + - Issues: https://github.com/Community-Access/support/issues + - Discussions: https://github.com/Community-Access/support/discussions See you at the workshop!` }); diff --git a/CONTRIBUTING.md b/CONTRIBUTING.md index 263a53df..0c9f6c4b 100644 --- a/CONTRIBUTING.md +++ b/CONTRIBUTING.md @@ -1,3 +1,5 @@ + +**Table: Keyboard shortcut for focusing search in different screen readers** # Contributing to This Workshop Repository Thank you for helping improve this workshop. Whether you are a participant who found a typo, someone who wants to add a new exercise, or an educator adapting these materials for your own community - your contribution is meaningful and welcome. diff --git a/GO-LIVE-QA-GUIDE.md b/GO-LIVE-QA-GUIDE.md index 16ceae68..f74079a7 100644 --- a/GO-LIVE-QA-GUIDE.md +++ b/GO-LIVE-QA-GUIDE.md @@ -16,6 +16,8 @@ Do not mark a cohort ready until all required items in this section are complete - [ ] 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). +- [ ] Support Hub is provisioned and publicly accessible at `Community-Access/support`. +- [ ] Registration confirmation and help pathways route support requests to Support Hub issues/discussions. - [ ] Registration issue form template and labels are configured (`workshop-registration.yml`, `registration`, `duplicate`, `waitlist`). - [ ] 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. @@ -47,6 +49,7 @@ No-go conditions: - 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. +- Support channel links point to deprecated destinations and not to `support`. ## Source Of Truth @@ -60,6 +63,7 @@ The following table lists each release artifact and the document that controls i | 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) | +| Support hub operations | [admin/SUPPORT_HUB_OPERATIONS.md](admin/SUPPORT_HUB_OPERATIONS.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) | diff --git a/README.md b/README.md index b0b4e125..ff81689e 100644 --- a/README.md +++ b/README.md @@ -13,7 +13,8 @@ License: CC BY 4.0 | [Site](https://community-access.org/git-going-with-github/) | **Workshop site** | [community-access.org/git-going-with-github](https://community-access.org/git-going-with-github/) | | **Registration** | [Student opt-in and waitlist workflow](https://community-access.org/git-going-with-github/REGISTER.html) | | **Discussions** | [Join the conversation](https://github.com/community-access/git-going-with-github/discussions) | -| **Support** | [File an issue](https://github.com/community-access/git-going-with-github/issues) | +| **Support hub** | [Community-Access/support](https://github.com/Community-Access/support) | +| **Curriculum issues** | [File an issue in this repository](https://github.com/community-access/git-going-with-github/issues) | | **Dates** | May 21, 2026 & May 22, 2026 | | **Facilitators** | Jeff Bishop and Michael Babcock | @@ -93,6 +94,14 @@ All documentation lives in the `docs/` folder. If you are new, start with [Get G Facilitators preparing a cohort should use the [Go-Live QA Guide](GO-LIVE-QA-GUIDE.md) as the release gate before sharing Classroom invite links. +## Post-Workshop Support + +After the workshop, use the open support repository for questions, troubleshooting, and alumni discussion: + +- [Community-Access/support](https://github.com/Community-Access/support) + +Use this repository for curriculum and platform changes only. + ## Your Challenges diff --git a/REGISTER.md b/REGISTER.md index 3cfcb15f..806acbde 100644 --- a/REGISTER.md +++ b/REGISTER.md @@ -1,6 +1,6 @@ # 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) +[Back to Home](https://community-access.org/git-going-with-github/) | [Support Hub](https://github.com/Community-Access/support) | [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 @@ -33,7 +33,7 @@ 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) +- [File a support issue](https://github.com/Community-Access/support/issues) +- [Join Support Hub Discussions](https://github.com/Community-Access/support/discussions) *A [Community Access](https://community-access.org) initiative.* diff --git a/SECURITY.md b/SECURITY.md index e510f78d..b606bf9b 100644 --- a/SECURITY.md +++ b/SECURITY.md @@ -4,6 +4,9 @@ This repository contains **educational curriculum and documentation only** - no production software, application servers, or APIs. There are no versioned software releases to patch. + +**Table: Supported content types and their source** + | Content | Supported | |---------|-----------| | Curriculum documentation (docs/) | Current main branch | diff --git a/admin/ANNOUNCEMENT.md b/admin/ANNOUNCEMENT.md index a37a1af7..c82c4bec 100644 --- a/admin/ANNOUNCEMENT.md +++ b/admin/ANNOUNCEMENT.md @@ -1,6 +1,6 @@ # GIT Going with GitHub -[License: CC BY 4.0](https://creativecommons.org/licenses/by/4.0/) | [View Site](https://community-access.org/git-going-with-github/) | [Full Curriculum](https://community-access.org/git-going-with-github/docs/course-guide.html) | [Discussion Forum](https://github.com/community-access/git-going-with-github/discussions) +[License: CC BY 4.0](https://creativecommons.org/licenses/by/4.0/) | [View Site](https://community-access.org/git-going-with-github/) | [Full Curriculum](https://community-access.org/git-going-with-github/docs/course-guide.html) | [Support Hub](https://github.com/Community-Access/support) ## You Belong in Open Source. Let Us Show You the Door. @@ -26,7 +26,7 @@ Sponsored by [Community Access](https://community-access.org) in partnership wit > **Want to join a future cohort?** Use the [**Student Opt-In page**](https://community-access.org/git-going-with-github/REGISTER.html). It feeds directly into our automated registration and waitlist workflow. -> **Join the conversation!** Have a question before the workshop? Want to connect with other participants? Head to our [**Discussion Forum**](https://github.com/community-access/git-going-with-github/discussions) - introduce yourself, ask questions, and start building your network before Day 1. +> **Join the conversation!** Have a question before the workshop? Want to connect with other participants? Head to our [**Support Hub Discussions**](https://github.com/Community-Access/support/discussions) - introduce yourself, ask questions, and start building your network before Day 1. > **Already registered?** Complete the [**Pre-Workshop Setup Guide**](https://community-access.org/git-going-with-github/docs/00-pre-workshop-setup.html) before the workshop. It walks you through every step - GitHub account, screen reader configuration, [VS Code](https://code.visualstudio.com/), and [GitHub Copilot](https://github.com/features/copilot) - with instructions for NVDA, JAWS, and VoiceOver. Get set up early so Day 1 starts with learning, not troubleshooting. @@ -236,8 +236,8 @@ No. The workshop, all software, and all materials are free. ## Questions? -- **Discussion Forum:** [Join the conversation](https://github.com/community-access/git-going-with-github/discussions) - ask questions, connect with fellow participants, and share ideas -- **File an issue:** [workshop repository](https://github.com/community-access/git-going-with-github/issues) - yes, even before the workshop starts. That counts as practice. +- **Support Hub Discussions:** [Join the conversation](https://github.com/Community-Access/support/discussions) - ask questions, connect with fellow participants, and share ideas +- **File a support issue:** [support repository](https://github.com/Community-Access/support/issues) - yes, even before the workshop starts. That counts as practice. - **Community:** [GitHub Accessibility Discussions](https://github.com/orgs/community/discussions/categories/accessibility) diff --git a/admin/FACILITATOR_GUIDE.md b/admin/FACILITATOR_GUIDE.md index cd0967bb..1756aab8 100644 --- a/admin/FACILITATOR_GUIDE.md +++ b/admin/FACILITATOR_GUIDE.md @@ -591,7 +591,7 @@ Give students concrete next steps: > "Here's what we suggest next: > 1. **Contribute to open source** — Find a repo you love and look for 'good first issue' > 2. **Use what you learned** — GitHub is real infrastructure; keep using it -> 3. **Join our alumni community** — [Slack/Discord/channel] — ask questions, share wins +> 3. **Join our alumni community** — [Community-Access/support](https://github.com/Community-Access/support) — ask questions, share wins > 4. **Build something** — Use GitHub as your project portfolio" #### Share Resources @@ -599,7 +599,7 @@ Give students concrete next steps: Point to: - [CONTRIBUTING.md](../CONTRIBUTING.md) — How to contribute to open source - [docs/](../docs/) — All the reference guides -- Alumni community link +- Support Hub: [Community-Access/support](https://github.com/Community-Access/support) - Your contact info for questions #### Thank You Note @@ -644,12 +644,13 @@ Point to: - What accessibility issues appeared? - What challenges took longer than expected? - [ ] Invite students to alumni community - - Slack / Discord / GitHub Discussions channel + - Support Hub: https://github.com/Community-Access/support - Encourage them to stay in touch and help future students ### Weeks 2+ - [ ] Monitor alumni community + - Watch new issues/discussions in Support Hub and respond within 24 to 48 hours - Answer questions - Celebrate project shares - Offer 1:1 mentorship if interested @@ -684,7 +685,7 @@ Point to: **"My internet cut out / I lost the call"** → GitHub Classroom doesn't require the call — work continues -→ Post updates in GitHub Discussions or email +→ Post updates in Support Hub Discussions or email → Students can continue async For more, see [FACILITATOR_CLASSROOM_TROUBLESHOOTING.md](FACILITATOR_CLASSROOM_TROUBLESHOOTING.md) @@ -742,7 +743,7 @@ Subject: Your GitHub Workshop Starts Tomorrow! > > **Keep learning:** > - Check out [CONTRIBUTING.md](../CONTRIBUTING.md) for contributing to open source -> - Join our alumni community: [LINK] +> - Join our alumni community: https://github.com/Community-Access/support > - Email if you have any GitHub questions — we're here > > Great work, and keep building! diff --git a/admin/LEARNING-ROOM-E2E-QA-RUNBOOK.md b/admin/LEARNING-ROOM-E2E-QA-RUNBOOK.md index 4eb253c6..fe7e5bcc 100644 --- a/admin/LEARNING-ROOM-E2E-QA-RUNBOOK.md +++ b/admin/LEARNING-ROOM-E2E-QA-RUNBOOK.md @@ -33,7 +33,8 @@ Out of scope: ## Canonical Source Files Used by This Runbook -The following table lists the source files this runbook consolidates. + +**Table: Source files consolidated by this runbook** | Area | Source file | |---|---| @@ -48,41 +49,48 @@ The following table lists the source files this runbook consolidates. | 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) | +| Support hub operations | [SUPPORT_HUB_OPERATIONS.md](SUPPORT_HUB_OPERATIONS.md) | + +**Table: QA validation checkpoints for registration and classroom automation** +**Table: Student journey checkpoints and expected artifacts** +**Table: Label color and purpose for registration automation** +**Table: Screen reader options for workshop setup** +**Table: Accessibility improvements for screen reader users** ## Required Accounts, Access, and Tools Complete this section before Phase 1. -- Facilitator admin account 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. +- Facilitator admin account (`accesswatch`) with Owner access to both `Community-Access` and `Community-Access-Classroom`. +- Dedicated non-admin test student account for acceptance and full challenge walkthrough. This must be a separate GitHub account that is not an owner or member of either organization. +- Access to [classroom.github.com](https://classroom.github.com) while signed in as `accesswatch`. +- Access to repository settings for `Community-Access/git-going-with-github` (secrets and variables). - Local clone of this repository with PowerShell available. -- GitHub CLI (`gh`) installed and authenticated for optional verification commands. +- GitHub CLI (`gh`) installed and authenticated as `accesswatch` for optional verification commands. ### Critical Precondition Gates (No-Go if any fail) Complete all items below before any cohort launch actions. -- [ ] Facilitator account 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. +- [ ] Facilitator account `accesswatch` can access both organizations: + - [ ] `Community-Access` (the workshop and code repository organization) + - [ ] `Community-Access-Classroom` (the GitHub Classroom organization where student repos are created) +- [ ] `accesswatch` has a verified email address on its GitHub account and can create and edit Classroom assignments at [classroom.github.com](https://classroom.github.com). - [ ] 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 +- [x] `gh auth status` succeeds for `accesswatch` in local terminal. +- [x] Template repository exists and is set as template repo: + - [x] `Community-Access/learning-room-template` +- [x] Template repository Actions settings allow required automation behavior: + - [x] Actions enabled + - [x] `GITHUB_TOKEN` default workflow permissions include write where required + - [x] `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. + - [ ] Secret `CLASSROOM_ORG_ADMIN_TOKEN` is set in `Community-Access/git-going-with-github` + - [ ] Variables `CLASSROOM_ORG`, `CLASSROOM_DAY1_ASSIGNMENT_URL`, `CLASSROOM_DAY2_ASSIGNMENT_URL` are set in `Community-Access/git-going-with-github` +- [x] Registration entry configuration exists and is valid: + - [x] Issue form template `workshop-registration.yml` exists + - [x] Required labels exist: `registration`, `duplicate`, `waitlist` +- [ ] While signed in as `accesswatch`, opening [classroom.github.com](https://classroom.github.com) shows the `Community-Access-Classroom` classroom organization. If any precondition fails, stop and resolve before proceeding. @@ -92,13 +100,17 @@ 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: +You are performing all steps below as `accesswatch`. If you are currently signed in to GitHub as a different account, sign out first and sign in as `accesswatch` before continuing. + +1. Go to [github.com](https://github.com) and confirm the top-right avatar shows `accesswatch`. +2. Open the avatar menu, then select **Your organizations**. +3. Confirm both of the following organizations appear in the list: + - `Community-Access` -- the main workshop repository organization + - `Community-Access-Classroom` -- the GitHub Classroom organization where student repos are created + - If either is missing, do not proceed. Contact the org owner to ensure `accesswatch` has Owner-level membership in both. +4. Click into `Community-Access` and open the **Settings** tab. Confirm you can see the full settings sidebar (Members, Actions, Secrets, etc.). If Settings is not visible, `accesswatch` does not have Owner access and you cannot proceed. +5. Click into `Community-Access-Classroom` and open its **Settings** tab. Confirm the same. +6. Optional CLI verification from the local repository root: ```powershell gh auth status -h github.com @@ -106,28 +118,101 @@ gh repo view Community-Access/git-going-with-github gh repo view Community-Access/learning-room-template ``` +Expected output: each `gh repo view` command should return repository metadata without an error. If you see "Could not resolve to a Repository", `accesswatch` does not have the required access. + +Why this matters: + +- All downstream setup steps operate against `Community-Access/git-going-with-github` and `Community-Access-Classroom`. If the account does not have Owner access to both, secrets, variables, and classroom automation cannot be configured. + +#### A.1 Create GitHub Classroom assignments + +Do this before section B. You need both assignment URLs in hand before you can fill in the repository variables. + +You must be signed in to GitHub as `accesswatch` for the following steps. + +1. Go to [classroom.github.com](https://classroom.github.com). +2. You will see a list of classrooms. Select the classroom named for this cohort that is linked to the `Community-Access-Classroom` organization. The organization name appears below the classroom name on the card. + - If no classroom exists yet, select **New classroom**, then choose `Community-Access-Classroom` as the organization. Name the classroom using the format `Git Going - [Cohort Name] - [Month Year]` (for example, `Git Going - May 2026`). +3. Inside the classroom, select **New assignment**. +4. Create the Day 1 assignment: + - **Title**: `You Belong Here` + - **Individual or group**: Individual + - **Repository visibility**: Private + - **Template repository**: `Community-Access/learning-room-template` (search for it by name in the template field) + - **Grant students admin access**: No + - **Enable feedback pull requests**: Yes + - Paste the Day 1 assignment description from [classroom/assignment-day1-you-belong-here.md](../classroom/assignment-day1-you-belong-here.md) + - Add autograding from [admin/classroom/autograding-setup.md](classroom/autograding-setup.md) -- Day 1 requires exactly 4 tests totaling 50 points + - Select **Create assignment** +5. After saving, the assignment page shows an invite link at the top labeled something like **Invite link**. It will be in the format `https://classroom.github.com/a/`. Copy this full URL and paste it somewhere safe (for example, a scratch notepad). This is your `CLASSROOM_DAY1_ASSIGNMENT_URL`. +6. Repeat for the Day 2 assignment: + - **Title**: `You Can Build This` + - Same base settings as Day 1 + - Paste description from [classroom/assignment-day2-you-can-build-this.md](../classroom/assignment-day2-you-can-build-this.md) + - Add Day 2 autograding: exactly 6 tests totaling 75 points + - Copy the resulting invite URL. This is your `CLASSROOM_DAY2_ASSIGNMENT_URL`. +7. Keep both URLs available. You will paste them into repository variables in section B step 4. + Why this matters: -- All downstream setup fails if the facilitator identity is not correctly scoped. +- The repository variables `CLASSROOM_DAY1_ASSIGNMENT_URL` and `CLASSROOM_DAY2_ASSIGNMENT_URL` cannot be filled in until the assignments exist and their invite URLs are known. The short code in the URL is unique to each assignment and is not predictable in advance. #### 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. +You must be signed in as `accesswatch` for all steps in this section. + +**Step B.1 -- Generate the personal access token (PAT)** + +The `CLASSROOM_ORG_ADMIN_TOKEN` secret must be a GitHub personal access token generated by `accesswatch` (or another Owner-level account for `Community-Access-Classroom`). This token is what allows the registration workflow to invite students to the `Community-Access-Classroom` organization automatically. + +1. While signed in as `accesswatch`, go to [github.com/settings/tokens](https://github.com/settings/tokens). +2. Select **Generate new token**, then select **Generate new token (classic)**. + - Do not use fine-grained tokens for this purpose. The `admin:org` scope is only available on classic tokens. +3. In the **Note** field enter a descriptive name such as `Community-Access registration automation`. +4. In the **Expiration** field, set a date that covers your cohort timeline plus a buffer (for example, 90 days). +5. Under **Select scopes**, check `admin:org`. This is the only scope required. It gives the token permission to list and create organization invitations for `Community-Access-Classroom`. +6. Scroll to the bottom and select **Generate token**. +7. GitHub will display the token exactly once immediately after generation. It begins with `ghp_`. Copy it now and paste it somewhere safe (a local scratch notepad, not a repository file). You will not be able to view it again. +8. Do not close the token page until you have completed section B.2 and confirmed the secret was saved. + +**Step B.2 -- Add the token as a repository secret** + +1. Go to [github.com/Community-Access/git-going-with-github/settings/secrets/actions](https://github.com/Community-Access/git-going-with-github/settings/secrets/actions). +2. Select **New repository secret**. +3. In the **Name** field, enter exactly: `CLASSROOM_ORG_ADMIN_TOKEN` + - Capitalization and underscores must match exactly. +4. In the **Secret** field, paste the token you copied in step B.1. +5. Select **Add secret**. +6. Re-open the secret entry and confirm the name shows `CLASSROOM_ORG_ADMIN_TOKEN`. GitHub does not display the value again, but confirming the name is correct is sufficient. + +**Step B.3 -- Add the repository variables** + +1. At the same settings page, select the **Variables** tab (next to Secrets). +2. Select **New repository variable** for each of the following. Add them one at a time. + + Variable 1: + - **Name**: `CLASSROOM_ORG` + - **Value**: `Community-Access-Classroom` + - This is the exact GitHub organization name where students are invited. The capitalization and hyphens must match exactly. + + Variable 2: + - **Name**: `CLASSROOM_DAY1_ASSIGNMENT_URL` + - **Value**: paste the Day 1 invite URL you copied in section A.1 step 5 (format: `https://classroom.github.com/a/`) + + Variable 3: + - **Name**: `CLASSROOM_DAY2_ASSIGNMENT_URL` + - **Value**: paste the Day 2 invite URL you copied in section A.1 step 6 (format: `https://classroom.github.com/a/`) + +3. After adding all three, re-open each variable entry and confirm: + - The name is exactly as listed above (no typos, no extra characters). + - The value has no leading or trailing spaces. Paste into a plain text editor first if you are unsure, and trim whitespace before re-pasting. +4. Run one registration test and confirm welcome comment contains assignment links. Why this matters: -- These values drive invite and assignment-link injection in registration responses. +- These values drive invite and assignment-link injection in registration responses. A single typo in the org name or a trailing space in a variable value will silently break automation without a clear error message. #### C. Configure template repository Actions permissions @@ -353,32 +438,73 @@ Pass criteria: 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. +The fastest path is `Initialize-WorkshopSetup.ps1`, which sets the secret, all three variables, verifies labels, and runs template prep in a single command. See the setup script section below. + +**Using the setup script (recommended):** + +```powershell +scripts/classroom/Initialize-WorkshopSetup.ps1 -AdminPAT ghp_yourTokenHere +``` + +The script will: +- Prompt you if the PAT is missing or invalid +- Resolve Day 1 and Day 2 assignment URLs automatically from the GitHub Classroom API (if assignments exist in the `GIT Going with Github` classroom) +- Set `CLASSROOM_ORG_ADMIN_TOKEN` secret and all three variables in `Community-Access/git-going-with-github` +- Verify all three required labels exist, creating any that are missing +- Confirm read-back values have no leading or trailing spaces +- Run `Prepare-LearningRoomTemplate.ps1` and `Test-LearningRoomTemplate.ps1` unless skipped + +**If running manually instead:** + +1. Generate a classic PAT with `admin:org` scope at [github.com/settings/tokens](https://github.com/settings/tokens) (see section B of the setup steps above for exact steps). +2. Go to [github.com/Community-Access/git-going-with-github/settings/secrets/actions](https://github.com/Community-Access/git-going-with-github/settings/secrets/actions). +3. Create secret `CLASSROOM_ORG_ADMIN_TOKEN` with the PAT value. +4. On the Variables tab, create: + - `CLASSROOM_ORG` = `Community-Access-Classroom` + - `CLASSROOM_DAY1_ASSIGNMENT_URL` = invite URL from assignment A.1 step 5 + - `CLASSROOM_DAY2_ASSIGNMENT_URL` = invite URL from assignment A.1 step 6 +5. Re-open each value and verify no leading or trailing spaces. Pass criteria: - Secret and variables are present with correct values. +- `Initialize-WorkshopSetup.ps1` reported no failures, or manual verification confirms all 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. +Goal: validate the deployed registration system and site are working before manual QA begins. -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. +Use `Test-RegistrationPage.ps1` to run this check. The script validates the Pages site, the REGISTER page, the issue form template, required labels, and workflow state. With `-RunLiveTest` it also submits a real test registration issue, waits for the workflow, and verifies the welcome comment. + +**Static checks only (site, config, labels, workflow state):** + +```powershell +scripts/classroom/Test-RegistrationPage.ps1 +``` + +**Full live end-to-end test including issue submission:** + +```powershell +scripts/classroom/Test-RegistrationPage.ps1 -RunLiveTest +``` + +What the script checks: + +1. HTTP GET to `https://community-access.org/git-going-with-github/` returns 200. +2. HTTP GET to `https://community-access.org/git-going-with-github/REGISTER` returns 200 and contains expected content. +3. `workshop-registration.yml` exists in `.github/ISSUE_TEMPLATE/`. +4. Labels `registration`, `duplicate`, and `waitlist` exist. +5. `registration.yml` workflow is active and has a recent successful run. +6. (Live test only) Test issue is submitted, workflow completes, welcome comment posts with assignment links, `registration` label is applied. + +Cleanup limitation: the test issue is closed and locked by the script. It **cannot be deleted via the GitHub API**. If deletion is needed, a repository admin must delete it manually from the Issues tab after this run. Pass criteria: -- Registration workflow executes successfully end to end. -- Output comment/labels match deployed configuration. +- `Test-RegistrationPage.ps1` exits with no failures. +- Live test (if run) confirms workflow executes end to end. +- Output comment and labels match deployed configuration. ## Phase 1 - Registration System QA (Admin Side) @@ -393,22 +519,36 @@ Pass criteria: - Registration link opens correctly. - Registration issue title is prefilled with `[REGISTER]`. - Public visibility warning is present. +- Support links point to `Community-Access/support` issues/discussions. + +### Step 1.1 Verify support hub onboarding path + +1. Open `Community-Access/support` and confirm Issues and Discussions are enabled. +2. Confirm at least one pinned onboarding discussion or Start Here guidance exists. +3. Open a test support issue using a template and confirm labels apply correctly. + +Pass criteria: + +- Support hub is reachable and public. +- Onboarding path is discoverable for students. +- Template-driven support issue flow works. ### 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. +If `Initialize-WorkshopSetup.ps1` was run successfully in Phase 0, this step is already complete. Re-verify with: -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. +```powershell +gh secret list -R Community-Access/git-going-with-github +gh variable list -R Community-Access/git-going-with-github +``` + +Expected output: `CLASSROOM_ORG_ADMIN_TOKEN` appears in secrets, and `CLASSROOM_ORG`, `CLASSROOM_DAY1_ASSIGNMENT_URL`, `CLASSROOM_DAY2_ASSIGNMENT_URL` appear in variables. + +If any are missing, run `Initialize-WorkshopSetup.ps1` again or follow the manual steps in section B of the setup instructions. For full reference, see [REGISTRATION-QUICKSTART.md](REGISTRATION-QUICKSTART.md) and [REGISTRATION-ADMIN.md](REGISTRATION-ADMIN.md). Pass criteria: -- Secret exists and is scoped correctly. -- All 3 variables exist and values are correct. +- `CLASSROOM_ORG_ADMIN_TOKEN` secret is present. +- All 3 variables are present with correct values and no leading or trailing spaces. ### Step 3. Execute registration happy-path test @@ -557,63 +697,113 @@ Use full end-to-end mode when preparing major cohort launches or after significa ### Step 10. Create classroom and import roster -Use [classroom/README.md](../classroom/README.md) Steps 1 and 2. +GitHub Classroom assignment creation has **no write API**. All classroom creation and assignment setup must be done through the browser at [classroom.github.com](https://classroom.github.com) while signed in as `accesswatch`. + +Note: a classroom already exists for this repository (`GIT Going with Github`, classroom id 322783, linked to `Community-Access-Classroom`). Unless starting a completely new classroom, skip classroom creation and go directly to assignment creation in Steps 11 and 12. + +**If you do need a new classroom:** + +1. Go to [classroom.github.com](https://classroom.github.com) as `accesswatch`. +2. Select **New classroom** and choose `Community-Access-Classroom` as the organization. +3. Name it `Git Going - [Cohort Name] - [Month Year]` (for example, `Git Going - May 2026`). +4. Import roster from [classroom/roster-template.csv](../classroom/roster-template.csv) on the Roster tab. +5. Add `accesswatch-student` to the roster as the test student. -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. +**To verify the existing classroom is accessible:** + +```powershell +gh api /classrooms --jq '.[] | {id, name, url}' +``` Pass criteria: -- Classroom exists and is accessible to facilitators. -- Roster import succeeds with expected usernames. +- Classroom exists in `Community-Access-Classroom` and is accessible to `accesswatch`. +- Roster includes `accesswatch-student` (or the designated test student username). ### 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). +See section A.1 of the setup steps above for full navigation instructions. + +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) for the exact title, description, and autograding entries. + +**To check if the Day 1 assignment already exists:** + +```powershell +gh api /classrooms/322783/assignments --jq '.[] | {id, title, invite_link}' +``` + +If the assignment exists and its `invite_link` is already in the `CLASSROOM_DAY1_ASSIGNMENT_URL` variable, skip to Step 12. + +**If creating from scratch:** -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. +1. Go to [classroom.github.com](https://classroom.github.com) as `accesswatch` and open the `GIT Going with Github` classroom. +2. Select **New assignment**. +3. Title: `You Belong Here` (exact match required) +4. Type: Individual, Visibility: Private +5. Template: `Community-Access/learning-room-template` +6. Grant students admin access: No +7. Enable feedback pull requests: Yes +8. Paste description from [classroom/assignment-day1-you-belong-here.md](../classroom/assignment-day1-you-belong-here.md) +9. Add autograding from [admin/classroom/autograding-setup.md](classroom/autograding-setup.md) -- Day 1 requires exactly 4 tests totaling 50 points +10. Save and copy the invite URL from the assignment page +11. If `Initialize-WorkshopSetup.ps1` has not been run yet, paste the URL into `CLASSROOM_DAY1_ASSIGNMENT_URL`. If it has been run, re-run it to pick up the new URL automatically. 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. +- Day 1 assignment exists with title `You Belong Here`. +- Test count is 4, total points is 50. +- Feedback pull request is enabled. +- `CLASSROOM_DAY1_ASSIGNMENT_URL` variable matches the assignment invite link. ### 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). +Same process as Step 11. Check first whether it already exists: + +```powershell +gh api /classrooms/322783/assignments --jq '.[] | {id, title, invite_link}' +``` + +If the assignment exists and its `invite_link` is already in `CLASSROOM_DAY2_ASSIGNMENT_URL`, skip ahead. + +**If creating from scratch:** -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. +1. In the `GIT Going with Github` classroom, select **New assignment**. +2. Title: `You Can Build This` (exact match required) +3. Apply same base settings as Day 1 (individual, private, no admin access, feedback PR enabled) +4. Template: `Community-Access/learning-room-template` +5. Paste description from [classroom/assignment-day2-you-can-build-this.md](../classroom/assignment-day2-you-can-build-this.md) +6. Add Day 2 autograding from [admin/classroom/autograding-setup.md](classroom/autograding-setup.md) -- 6 tests totaling 75 points +7. Save and copy the invite URL +8. Update `CLASSROOM_DAY2_ASSIGNMENT_URL` or re-run `Initialize-WorkshopSetup.ps1` to pick it up automatically 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. +- Day 2 assignment exists with title `You Can Build This`. +- Test count is 6, total points is 75. +- Feedback pull request is enabled. +- `CLASSROOM_DAY2_ASSIGNMENT_URL` variable matches the assignment invite link. ### 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. +If `Initialize-WorkshopSetup.ps1` was run after the assignments were created, the variables are already set. Verify with: + +```powershell +gh variable list -R Community-Access/git-going-with-github +``` + +If either URL variable is missing or stale, re-run the setup script. It will resolve URLs directly from the Classroom API: + +```powershell +scripts/classroom/Initialize-WorkshopSetup.ps1 -AdminPAT ghp_yourTokenHere -SkipTemplatePrepare -SkipTemplateValidate +``` + +Then re-run the registration live test to confirm both URLs appear in the welcome comment: + +```powershell +scripts/classroom/Test-RegistrationPage.ps1 -RunLiveTest +``` Pass criteria: -- Registration confirmation comment now includes both assignment URLs. +- `CLASSROOM_DAY1_ASSIGNMENT_URL` and `CLASSROOM_DAY2_ASSIGNMENT_URL` are set and match assignment invite links. +- Registration confirmation comment includes both assignment URLs. +- `Test-RegistrationPage.ps1 -RunLiveTest` exits with no failures. ## Phase 4 - Test Student Acceptance and Seeding (Bridge from Admin to Student) @@ -633,20 +823,34 @@ Pass criteria: ### Step 15. Seed initial challenges and peer simulation -Run commands from repository root. +The test student account is `accesswatch-student`. GitHub Classroom generates repository names from the assignment slug and the student username. For the default assignment titles, the repository names will be: + +- Day 1: `Community-Access-Classroom/you-belong-here-accesswatch-student` +- Day 2: `Community-Access-Classroom/you-can-build-this-accesswatch-student` + +Confirm the exact repository names first: + +```powershell +gh repo list Community-Access-Classroom --json name --jq '.[].name' | Select-String accesswatch-student +``` + +Then seed (replace repository slugs with the confirmed names if different): ```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 +$day1 = 'Community-Access-Classroom/you-belong-here-accesswatch-student' +$day2 = 'Community-Access-Classroom/you-can-build-this-accesswatch-student' + +scripts/classroom/Seed-LearningRoomChallenge.ps1 -Repository $day1 -Challenge 1 -Assignee accesswatch-student +scripts/classroom/Seed-PeerSimulation.ps1 -Repository $day1 -StudentUsername accesswatch-student +scripts/classroom/Seed-LearningRoomChallenge.ps1 -Repository $day2 -Challenge 10 -Assignee accesswatch-student +scripts/classroom/Seed-PeerSimulation.ps1 -Repository $day2 -StudentUsername accesswatch-student ``` -If you use different repository names, replace values accordingly. +Alternatively, if `Initialize-WorkshopSetup.ps1` is run after `accesswatch-student` has accepted both invites, it will detect the repos and seed them automatically. Pass criteria: -- Challenge 1 appears in Day 1 repo. -- Challenge 10 appears in Day 2 repo. +- Challenge 1 issue appears in Day 1 repo assigned to `accesswatch-student`. +- Challenge 10 issue appears in Day 2 repo assigned to `accesswatch-student`. - Peer simulation issues and PR exist in both repos. ## Phase 5 - Curriculum Content QA (Walk every required chapter and appendix) @@ -1336,4 +1540,82 @@ Release Decision: 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 +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. + +## Script Reference + +The following scripts in `scripts/classroom/` are used by this runbook. Run each with `-?` or read the `.SYNOPSIS` block for full parameter documentation. + +| Script | Purpose | Automated | +|---|---|---| +| `Initialize-WorkshopSetup.ps1` | Set PAT secret, variables, labels; sync and validate template; seed test student challenges | All steps except PAT generation (browser required) | +| `Archive-CohortData.ps1` | Export cohort issues, roster, and discussions to `git-going-student-success`; reset source repo | Export and archive are automated; roster reset may require PR due branch rules | +| `Delete-RegistrationIssues.ps1` | Delete registration/duplicate/waitlist issues via GraphQL mutation | Fully automated when user has repo admin and `repo` token scope | +| `Delete-RegistrationIssues-v2.js` | Experimental Playwright UI deleter for issue cleanup | Partially automated; UI selector fragility makes this fallback-only | +| `Test-RegistrationPage.ps1` | Validate Pages site, REGISTER page, issue form, labels, workflow, and live registration flow | All steps; test issue cleanup is close+lock only (see below) | +| `Prepare-LearningRoomTemplate.ps1` | Sync `learning-room/` source into `Community-Access/learning-room-template` | Fully automated | +| `Test-LearningRoomTemplate.ps1` | Create smoke repo from template, validate file inventory and workflow dispatch | Fully automated | +| `Seed-LearningRoomChallenge.ps1` | Seed a specific challenge issue in a student repository | Fully automated | +| `Seed-PeerSimulation.ps1` | Seed peer simulation issues and PR in a student repository | Fully automated | +| `Restore-LearningRoomFiles.ps1` | Restore baseline files into a student repo via recovery branch and PR | Fully automated | +| `Invoke-LearningRoomEndToEndTest.ps1` | Full end-to-end scripted QA harness | Fully automated | +| `Reset-SupportHubEnvironment.ps1` | Rebuild support hub repository labels, settings, and baseline support automation | Fully automated | + +## GitHub API Limitations + +The following actions cannot be performed via any GitHub API and require manual browser-based action. These are hard platform constraints, not gaps in the scripts. + +| Action | Why it cannot be automated | Manual path | +|---|---|---| +| Creating a Classroom assignment | No write endpoint exists in the GitHub Classroom REST API (confirmed: only GET endpoints are documented and available) | [classroom.github.com](https://classroom.github.com) as `accesswatch` | +| Deleting issues via REST API | GitHub REST API has no DELETE endpoint for issues | Use `scripts/classroom/Delete-RegistrationIssues.ps1` (GraphQL mutation path), or UI fallback | +| Deleting or moving discussions | GraphQL discussion mutations do not include delete or move operations | Discussions tab in GitHub UI -> each thread -> "..." -> Delete | +| Generating a personal access token | PAT generation requires browser authentication by design | [github.com/settings/tokens](https://github.com/settings/tokens) as `accesswatch` | + +## Pre-Cohort Cleanup Procedure + +Run this procedure after each cohort completes, before starting QA for the next cohort. + +### Archive previous cohort data + +```powershell +# Replace the slug with the cohort being archived (format: YYYY-MM-description) +scripts/classroom/Archive-CohortData.ps1 -CohortSlug 2026-03-march-cohort +``` + +What this does: + +1. Exports all registration/duplicate/waitlist issues (with comments) to JSON and CSV. +2. Exports the current `student-roster.json`. +3. Exports discussions to JSON. +4. Pushes the archive to `Community-Access/git-going-student-success` under `admin/cohorts//`. +5. Closes and locks all registration issues in the source repository. +6. Resets `student-roster.json` to the blank template. + +Use `-WhatIf` to preview without making changes: + +```powershell +scripts/classroom/Archive-CohortData.ps1 -CohortSlug 2026-03-march-cohort -WhatIf +``` + +After the script completes, two manual cleanup steps are required (API limitation): + +1. **Delete registration issues** -- use the GraphQL cleanup script (recommended): + +```powershell +scripts/classroom/Delete-RegistrationIssues.ps1 +``` + +2. **Delete discussions** -- discussions still require manual deletion: + `https://github.com/Community-Access/git-going-with-github/discussions` + +Archive destination: `https://github.com/Community-Access/git-going-student-success/tree/main/admin/cohorts//` + +### Current Progress Snapshot (2026-05-08) + +- [x] Registration issues archived to `git-going-student-success`. +- [x] Registration issues deleted from source repository (count now 0). +- [x] Discussions deleted from source repository (count now 0). +- [x] Learning Room template sync PR merged: `Community-Access/learning-room-template#11`. +- [ ] Registration secret and variable values set for next cohort (`CLASSROOM_ORG_ADMIN_TOKEN`, `CLASSROOM_ORG`, `CLASSROOM_DAY1_ASSIGNMENT_URL`, `CLASSROOM_DAY2_ASSIGNMENT_URL`). +- [ ] Day 1 and Day 2 classroom assignments created for next cohort. \ No newline at end of file diff --git a/admin/PODCASTS.md b/admin/PODCASTS.md index dde3f722..f810357d 100644 --- a/admin/PODCASTS.md +++ b/admin/PODCASTS.md @@ -106,7 +106,7 @@ Based on: [Course Guide](docs/course-guide.md) **Jamie:** What do you want them to do when the plan breaks? -**Alex:** This is where Getting Help becomes real: if you get stuck at any point during the workshop, these resources are always available. That matters in practice: Open an issue on this repository describing what you tried, what happened, and what you expected. +**Alex:** This is where Getting Help becomes real: if you get stuck at any point during the workshop, these resources are always available. That matters in practice: Use the support hub at https://github.com/Community-Access/support and open a support issue describing what you tried, what happened, and what you expected. **Alex:** That connects to another useful point. Keep the learner anchored in Workshop at a Glance. Start with Chapter 00: Pre-Workshop Setup. A good GitHub workflow is like a well-run meeting: everyone knows the topic, the next action, and who has the floor. @@ -1103,7 +1103,7 @@ Based on: [Chapter 0: Pre-Workshop Setup](docs/00-pre-workshop-setup.md) **Alex:** Start with Getting Help Before the Event: If you cannot complete any step in this guide before the workshop. The next useful detail is this: Every setup issue we can solve before Day 1 means more time for learning on the day. -**Alex:** First, file an issue - community-access/git-going-with-github - we will help you get set up. Then, file an issue in this repository - describe exactly what step you are on and what is not working. After that, join the GitHub Accessibility Discussions - GitHub Community Accessibility Discussions - the community is helpful and welcoming. Think of it as a rail line: each stop confirms you are still on the right route before the next one. +**Alex:** First, open a setup support issue in Community-Access/support/issues so maintainers can triage quickly. Then, join Community-Access/support/discussions and read the pinned Start Here guidance before posting follow-up questions. After that, if you need broader platform input, join GitHub Community Accessibility Discussions. Think of it as a rail line: each stop confirms you are still on the right route before the next one. --- diff --git a/admin/README.md b/admin/README.md index a39e896d..3a327c7e 100644 --- a/admin/README.md +++ b/admin/README.md @@ -19,6 +19,7 @@ This folder contains all administrative and facilitator documentation for runnin ### Supporting Guides - **[FACILITATOR_CHALLENGES.md](FACILITATOR_CHALLENGES.md)** - Managing the challenge system - **[FACILITATOR_ASSESSMENT.md](FACILITATOR_ASSESSMENT.md)** - Assessment and grading rubric +- **[SUPPORT_HUB_OPERATIONS.md](SUPPORT_HUB_OPERATIONS.md)** - Post-workshop support hub governance and triage model --- diff --git a/admin/REGISTER.md b/admin/REGISTER.md index b244a7b9..89acbede 100644 --- a/admin/REGISTER.md +++ b/admin/REGISTER.md @@ -1,6 +1,6 @@ # 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) +[Back to Home](https://community-access.org/git-going-with-github/) | [Support Hub](https://github.com/Community-Access/support) | [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 @@ -39,13 +39,13 @@ This page is a fast, self-serve opt-in workflow. Students can opt in directly fr 1. Check your issue for the automated confirmation or waitlist comment. 2. Complete the [Pre-Workshop Setup Guide](https://community-access.org/git-going-with-github/docs/00-pre-workshop-setup.html). -3. Introduce yourself in the [Discussion Forum](https://github.com/community-access/git-going-with-github/discussions). +3. Introduce yourself in [Support Hub Discussions](https://github.com/Community-Access/support/discussions). ## Need help? Questions or access issues are welcome. -- [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) +- [File a support issue](https://github.com/Community-Access/support/issues) +- [Join Support Hub Discussions](https://github.com/Community-Access/support/discussions) *A [Community Access](https://community-access.org) initiative.* diff --git a/admin/REGISTRATION-QUICKSTART.md b/admin/REGISTRATION-QUICKSTART.md index 36ecc258..75e047c4 100644 --- a/admin/REGISTRATION-QUICKSTART.md +++ b/admin/REGISTRATION-QUICKSTART.md @@ -65,6 +65,14 @@ If anything behaves unexpectedly, disable classroom API automation without stopp The registration workflow will continue standard confirmation, capacity checks, and CSV export. +## Full Support Reset (When Needed) + +If support environment drift is detected, rebuild support hub baseline: + +```powershell +scripts/classroom/Reset-SupportHubEnvironment.ps1 +``` + ## Day-Of Operations 1. Keep [REGISTRATION-ADMIN.md](REGISTRATION-ADMIN.md) open. diff --git a/admin/SUPPORT_HUB_OPERATIONS.md b/admin/SUPPORT_HUB_OPERATIONS.md new file mode 100644 index 00000000..43f5fe2d --- /dev/null +++ b/admin/SUPPORT_HUB_OPERATIONS.md @@ -0,0 +1,112 @@ +# Support Hub Operations + +This guide defines how we run the open, post-workshop support repository for GIT Going with GitHub. + +## Canonical Support Repository + +- Repository name: `Community-Access/support` +- Repository URL: +- Repository visibility: Public +- Primary purpose: post-workshop support, async Q&A, troubleshooting, and alumni collaboration + +This repository does not replace curriculum source repositories. It routes support traffic away from curriculum maintenance and keeps student support visible and searchable. + +## Student Onboarding Model (Rich Path) + +Use this onboarding flow for every new cohort: + +1. Share Support Hub URL in registration confirmation and Day 2 close-out. +2. Ask students to read pinned Start Here content in Discussions. +3. Ask students to post one introduction in Discussions and one support request using templates if blocked. +4. Point students to labels and categories so they can self-route requests. + +Onboarding success criteria: + +- Students can explain the difference between support issues and discussions. +- Students can open a support issue with reproducible steps. +- Students can find and follow a resolved discussion thread. + +## What Belongs In Support Hub + +Use Support Hub for: + +- Student setup and access questions +- Post-workshop troubleshooting questions +- Accessibility workflow questions +- Alumni sharing and follow-up help +- Requests for clarification in workshop docs + +Do not use Support Hub for: + +- Direct edits to workshop curriculum content +- Template workflow code changes +- Security disclosures + +Routing: + +- Curriculum and content changes: +- Learning Room template changes: +- Security reports: follow [../SECURITY.md](../SECURITY.md) + +## Recommended Support Taxonomy + +### Discussions categories + +- `Q&A` +- `Troubleshooting` +- `Success Stories` +- `Announcements` +- `Office Hours` + +### Labels + +- `needs-triage` +- `setup` +- `classroom` +- `accessibility` +- `copilot` +- `resolved` +- `escalated` + +## Response Standards + +- First response target: 24 to 48 hours +- Triage cadence during active cohorts: daily +- Triage cadence off-cycle: 3 times per week + +## Moderator Playbook + +1. Acknowledge the question and restate the goal. +2. Provide one clear next action. +3. Link to the exact workshop doc section when relevant. +4. Ask for diagnostics only if needed. +5. Mark `resolved` when the user confirms or the path is complete. + +## Privacy And Safety Rules + +- Do not request personal data in public issues/discussions. +- Never ask users to post tokens, secrets, or private repository URLs publicly. +- For sensitive account problems, move to private facilitator contact. + +## Integration Checklist + +- [ ] `REGISTER.md` and registration workflow comments point to Support Hub. +- [ ] Facilitator guides reference Support Hub as the alumni channel. +- [ ] `docs/21-next-steps.md` points learners to Support Hub. +- [ ] Go-live checklist includes Support Hub readiness. +- [ ] Podcast scripts/transcripts reference Support Hub as the default help path. + +## Reset And Rebuild (From Scratch) + +If the support environment drifts or needs a hard reset, run: + +```powershell +scripts/classroom/Reset-SupportHubEnvironment.ps1 +``` + +This script re-applies repository baseline setup: + +- Repository existence and visibility +- Issues and Discussions enabled +- Support label taxonomy +- Baseline support files and bot workflows diff --git a/admin/qa-bundle/.github/ISSUE_TEMPLATE/workshop-registration.yml b/admin/qa-bundle/.github/ISSUE_TEMPLATE/workshop-registration.yml index c759d1e2..d6937b0f 100644 --- a/admin/qa-bundle/.github/ISSUE_TEMPLATE/workshop-registration.yml +++ b/admin/qa-bundle/.github/ISSUE_TEMPLATE/workshop-registration.yml @@ -85,6 +85,6 @@ body: 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. + **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, use the support hub: [Community-Access/support](https://github.com/Community-Access/support). Welcome aboard. You belong here. diff --git a/admin/qa-bundle/.github/workflows/registration.yml b/admin/qa-bundle/.github/workflows/registration.yml index 01d3b0b0..6536b38b 100644 --- a/admin/qa-bundle/.github/workflows/registration.yml +++ b/admin/qa-bundle/.github/workflows/registration.yml @@ -65,7 +65,7 @@ jobs: 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.` + Questions? [File a support issue](https://github.com/Community-Access/support/issues) in the support hub.` }); await github.rest.issues.addLabels({ @@ -132,7 +132,7 @@ jobs: 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.` + Questions? [File a support issue](https://github.com/Community-Access/support/issues) in the support hub.` }); await github.rest.issues.addLabels({ @@ -246,7 +246,9 @@ jobs: ${classroomSection} - If you have any questions, [file an issue](https://github.com/community-access/git-going-with-github/issues) in the workshop repository. + If you have any questions, use the support hub: + - Issues: https://github.com/Community-Access/support/issues + - Discussions: https://github.com/Community-Access/support/discussions See you at the workshop!` }); diff --git a/admin/qa-bundle/GO-LIVE-QA-GUIDE.md b/admin/qa-bundle/GO-LIVE-QA-GUIDE.md index 52492775..5d5b86f9 100644 --- a/admin/qa-bundle/GO-LIVE-QA-GUIDE.md +++ b/admin/qa-bundle/GO-LIVE-QA-GUIDE.md @@ -14,6 +14,8 @@ Do not mark a cohort ready until all required items in this section are complete - [ ] 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). +- [ ] Support Hub is provisioned and publicly accessible at `Community-Access/support`. +- [ ] Registration confirmation and help pathways route support requests to Support Hub issues/discussions. - [ ] Registration issue form template and labels are configured (`workshop-registration.yml`, `registration`, `duplicate`, `waitlist`). - [ ] 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. @@ -47,6 +49,7 @@ The following table lists each release artifact and the document that controls i | 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) | +| Support hub operations | [admin/SUPPORT_HUB_OPERATIONS.md](admin/SUPPORT_HUB_OPERATIONS.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) | diff --git a/admin/qa-bundle/REGISTER.md b/admin/qa-bundle/REGISTER.md index 3cfcb15f..806acbde 100644 --- a/admin/qa-bundle/REGISTER.md +++ b/admin/qa-bundle/REGISTER.md @@ -1,6 +1,6 @@ # 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) +[Back to Home](https://community-access.org/git-going-with-github/) | [Support Hub](https://github.com/Community-Access/support) | [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 @@ -33,7 +33,7 @@ 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) +- [File a support issue](https://github.com/Community-Access/support/issues) +- [Join Support Hub Discussions](https://github.com/Community-Access/support/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 index 196ceca0..6ec23841 100644 --- a/admin/qa-bundle/admin/LEARNING-ROOM-E2E-QA-RUNBOOK.html +++ b/admin/qa-bundle/admin/LEARNING-ROOM-E2E-QA-RUNBOOK.html @@ -97,90 +97,174 @@

Canonical Source Files Used by This Runbook

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.
    • +
  • Facilitator admin account (accesswatch) with Owner access to both Community-Access and Community-Access-Classroom.
    • +
  • Dedicated non-admin test student account for acceptance and full challenge walkthrough. This must be a separate GitHub account that is not an owner or member of either organization.
    • +
  • Access to classroom.github.com while signed in as accesswatch.
    • +
  • Access to repository settings for Community-Access/git-going-with-github (secrets and variables).
  • Local clone of this repository with PowerShell available.
    • -
  • GitHub CLI (gh) installed and authenticated for optional verification commands.
    • +
  • GitHub CLI (gh) installed and authenticated as accesswatch for optional verification commands.

Critical Precondition Gates (No-Go if any fail)

Complete all items below before any cohort launch actions.

    -
  • Facilitator account can access both organizations involved in operations:
      -
    • Community-Access
      • -
    • Community-Access-Classroom (or your classroom org)
      • +
    • Facilitator account accesswatch can access both organizations:
        +
      • Community-Access (the workshop and code repository organization)
        • +
      • Community-Access-Classroom (the GitHub Classroom organization where student repos are created)
      • -
    • Facilitator account has verified email and can create/edit Classroom assignments.
      • +
    • accesswatch has a verified email address on its GitHub account and can create and edit Classroom assignments at classroom.github.com.
    • Dedicated non-admin test student account exists and can accept invites.
      • -
    • gh auth status succeeds for facilitator account in local terminal.
      • -
    • Template repository exists and is set as template repo:
        -
      • Community-Access/learning-room-template
        • +
      • gh auth status succeeds for accesswatch in local terminal.
        • +
      • Template repository exists and is set as template repo:
          +
        • Community-Access/learning-room-template
        • -
      • Template repository Actions settings allow required automation behavior:
          -
        • Actions enabled
          • -
        • GITHUB_TOKEN default workflow permissions include write where required
          • -
        • Allow GitHub Actions to create and approve pull requests enabled
          • +
        • 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
            • +
          • Secret CLASSROOM_ORG_ADMIN_TOKEN is set in Community-Access/git-going-with-github
            • +
          • Variables CLASSROOM_ORG, CLASSROOM_DAY1_ASSIGNMENT_URL, CLASSROOM_DAY2_ASSIGNMENT_URL are set in Community-Access/git-going-with-github
          • -
        • Registration entry configuration exists and is valid:
            -
          • Issue form template workshop-registration.yml exists
            • -
          • Required labels exist: registration, duplicate, waitlist
            • +
          • 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.
            • +
          • While signed in as accesswatch, opening classroom.github.com shows the Community-Access-Classroom classroom organization.

          If any precondition fails, stop and resolve before proceeding.

          Exact Setup Steps for Keys, Permissions, Settings, and Template Currency

          Use this section when you need literal setup steps (not only validation checks).

          A. Confirm facilitator account and organization access

          +

          You are performing all steps below as accesswatch. If you are currently signed in to GitHub as a different account, sign out first and sign in as accesswatch before continuing.

            -
          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)
              • +
            • Go to github.com and confirm the top-right avatar shows accesswatch.
              • +
            • Open the avatar menu, then select Your organizations.
              • +
            • Confirm both of the following organizations appear in the list:
                +
              • Community-Access -- the main workshop repository organization
                • +
              • Community-Access-Classroom -- the GitHub Classroom organization where student repos are created
                • +
              • If either is missing, do not proceed. Contact the org owner to ensure accesswatch has Owner-level membership in both.
              • -
            • Open both org pages and confirm you can view repositories and settings areas you are expected to manage.
              • -
            • Optional CLI verification from repository root:
              • +
            • Click into Community-Access and open the Settings tab. Confirm you can see the full settings sidebar (Members, Actions, Secrets, etc.). If Settings is not visible, accesswatch does not have Owner access and you cannot proceed.
              • +
            • Click into Community-Access-Classroom and open its Settings tab. Confirm the same.
              • +
            • Optional CLI verification from the local repository root:
          gh auth status -h github.com
 gh repo view Community-Access/git-going-with-github
 gh repo view Community-Access/learning-room-template
          +

          Expected output: each gh repo view command should return repository metadata without an error. If you see "Could not resolve to a Repository", accesswatch does not have the required access.

          Why this matters:

            -
          • All downstream setup fails if the facilitator identity is not correctly scoped.
            • +
          • All downstream setup steps operate against Community-Access/git-going-with-github and Community-Access-Classroom. If the account does not have Owner access to both, secrets, variables, and classroom automation cannot be configured.
            • +
          +

          A.1 Create GitHub Classroom assignments

          +

          Do this before section B. You need both assignment URLs in hand before you can fill in the repository variables.

          +

          You must be signed in to GitHub as accesswatch for the following steps.

          +
            +
          1. Go to classroom.github.com.
            2. +
          2. You will see a list of classrooms. Select the classroom named for this cohort that is linked to the Community-Access-Classroom organization. The organization name appears below the classroom name on the card.
              +
            • If no classroom exists yet, select New classroom, then choose Community-Access-Classroom as the organization. Name the classroom using the format Git Going - [Cohort Name] - [Month Year] (for example, Git Going - May 2026).
              • +
            +
            3. +
          3. Inside the classroom, select New assignment.
            4. +
          4. Create the Day 1 assignment:
              +
            • Title: You Belong Here
              • +
            • Individual or group: Individual
              • +
            • Repository visibility: Private
              • +
            • Template repository: Community-Access/learning-room-template (search for it by name in the template field)
              • +
            • Grant students admin access: No
              • +
            • Enable feedback pull requests: Yes
              • +
            • Paste the Day 1 assignment description from classroom/assignment-day1-you-belong-here.md
              • +
            • Add autograding from admin/classroom/autograding-setup.md -- Day 1 requires exactly 4 tests totaling 50 points
              • +
            • Select Create assignment
              • +
            +
            5. +
          5. After saving, the assignment page shows an invite link at the top labeled something like Invite link. It will be in the format https://classroom.github.com/a/<short-code>. Copy this full URL and paste it somewhere safe (for example, a scratch notepad). This is your CLASSROOM_DAY1_ASSIGNMENT_URL.
            6. +
          6. Repeat for the Day 2 assignment:
              +
            • Title: You Can Build This
              • +
            • Same base settings as Day 1
              • +
            • Paste description from classroom/assignment-day2-you-can-build-this.md
              • +
            • Add Day 2 autograding: exactly 6 tests totaling 75 points
              • +
            • Copy the resulting invite URL. This is your CLASSROOM_DAY2_ASSIGNMENT_URL.
              • +
            +
            7. +
          7. Keep both URLs available. You will paste them into repository variables in section B step 4.
            8. +
          +

          Why this matters:

          +
            +
          • The repository variables CLASSROOM_DAY1_ASSIGNMENT_URL and CLASSROOM_DAY2_ASSIGNMENT_URL cannot be filled in until the assignments exist and their invite URLs are known. The short code in the URL is unique to each assignment and is not predictable in advance.

          B. Configure registration automation key and variables

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

          +

          You must be signed in as accesswatch for all steps in this section.

          +

          Step B.1 -- Generate the personal access token (PAT)

          +

          The CLASSROOM_ORG_ADMIN_TOKEN secret must be a GitHub personal access token generated by accesswatch (or another Owner-level account for Community-Access-Classroom). This token is what allows the registration workflow to invite students to the Community-Access-Classroom organization automatically.

            -
          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
              • +
            • While signed in as accesswatch, go to github.com/settings/tokens.
              • +
            • Select Generate new token, then select Generate new token (classic).
                +
              • Do not use fine-grained tokens for this purpose. The admin:org scope is only available on classic tokens.
              • -
            • Open the Variables tab and create or update variables:
                -
              • CLASSROOM_ORG
                • -
              • CLASSROOM_DAY1_ASSIGNMENT_URL
                • -
              • CLASSROOM_DAY2_ASSIGNMENT_URL
                • +
              • In the Note field enter a descriptive name such as Community-Access registration automation.
                • +
              • In the Expiration field, set a date that covers your cohort timeline plus a buffer (for example, 90 days).
                • +
              • Under Select scopes, check admin:org. This is the only scope required. It gives the token permission to list and create organization invitations for Community-Access-Classroom.
                • +
              • Scroll to the bottom and select Generate token.
                • +
              • GitHub will display the token exactly once immediately after generation. It begins with ghp_. Copy it now and paste it somewhere safe (a local scratch notepad, not a repository file). You will not be able to view it again.
                • +
              • Do not close the token page until you have completed section B.2 and confirmed the secret was saved.
                • +
          +

          Step B.2 -- Add the token as a repository secret

          +
            +
          1. Go to github.com/Community-Access/git-going-with-github/settings/secrets/actions.
            2. +
          2. Select New repository secret.
            3. +
          3. In the Name field, enter exactly: CLASSROOM_ORG_ADMIN_TOKEN
              +
            • Capitalization and underscores must match exactly.
            4. -
          4. Re-open each entry and confirm values have no leading or trailing spaces.
            5. -
          5. Run one registration test and confirm welcome comment contains assignment links when variables are set.
            6. +
          6. In the Secret field, paste the token you copied in step B.1.
            7. +
          7. Select Add secret.
            8. +
          8. Re-open the secret entry and confirm the name shows CLASSROOM_ORG_ADMIN_TOKEN. GitHub does not display the value again, but confirming the name is correct is sufficient.
            9. +
          +

          Step B.3 -- Add the repository variables

          +
            +

          1. At the same settings page, select the Variables tab (next to Secrets).

            +
            2. +

          2. Select New repository variable for each of the following. Add them one at a time.

            +

            Variable 1:

            +
              +
            • Name: CLASSROOM_ORG
              • +
            • Value: Community-Access-Classroom
              • +
            • This is the exact GitHub organization name where students are invited. The capitalization and hyphens must match exactly.
              • +
            +

            Variable 2:

            +
              +
            • Name: CLASSROOM_DAY1_ASSIGNMENT_URL
              • +
            • Value: paste the Day 1 invite URL you copied in section A.1 step 5 (format: https://classroom.github.com/a/<short-code>)
              • +
            +

            Variable 3:

            +
              +
            • Name: CLASSROOM_DAY2_ASSIGNMENT_URL
              • +
            • Value: paste the Day 2 invite URL you copied in section A.1 step 6 (format: https://classroom.github.com/a/<short-code>)
              • +
            +
            3. +

          3. After adding all three, re-open each variable entry and confirm:

            +
              +
            • The name is exactly as listed above (no typos, no extra characters).
              • +
            • The value has no leading or trailing spaces. Paste into a plain text editor first if you are unsure, and trim whitespace before re-pasting.
              • +
            +
            4. +

          4. Run one registration test and confirm welcome comment contains assignment links.

            +

          Why this matters:

            -
          • These values drive invite and assignment-link injection in registration responses.
            • +
          • These values drive invite and assignment-link injection in registration responses. A single typo in the org name or a trailing space in a variable value will silently break automation without a clear error message.

          C. Configure template repository Actions permissions

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

          @@ -498,15 +582,28 @@

          Step 0.1 Deploy registration issue form and workflow prerequisites

        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
            • +

            The fastest path is Initialize-WorkshopSetup.ps1, which sets the secret, all three variables, verifies labels, and runs template prep in a single command. See the setup script section below.

            +

            Using the setup script (recommended):

            +
            scripts/classroom/Initialize-WorkshopSetup.ps1 -AdminPAT ghp_yourTokenHere
+
            +

            The script will:

            +
              +
            • Prompt you if the PAT is missing or invalid
              • +
            • Resolve Day 1 and Day 2 assignment URLs automatically from the GitHub Classroom API (if assignments exist in the GIT Going with Github classroom)
              • +
            • Set CLASSROOM_ORG_ADMIN_TOKEN secret and all three variables in Community-Access/git-going-with-github
              • +
            • Verify all three required labels exist, creating any that are missing
              • +
            • Confirm read-back values have no leading or trailing spaces
              • +
            • Run Prepare-LearningRoomTemplate.ps1 and Test-LearningRoomTemplate.ps1 unless skipped
            - -
          • In repository settings, configure variables:
              -
            • CLASSROOM_ORG
              • -
            • CLASSROOM_DAY1_ASSIGNMENT_URL
              • -
            • CLASSROOM_DAY2_ASSIGNMENT_URL
              • +

              If running manually instead:

              +
                +
              1. Generate a classic PAT with admin:org scope at github.com/settings/tokens (see section B of the setup steps above for exact steps).
                2. +
              2. Go to github.com/Community-Access/git-going-with-github/settings/secrets/actions.
                3. +
              3. Create secret CLASSROOM_ORG_ADMIN_TOKEN with the PAT value.
                4. +
              4. On the Variables tab, create:
                  +
                • CLASSROOM_ORG = Community-Access-Classroom
                  • +
                • CLASSROOM_DAY1_ASSIGNMENT_URL = invite URL from assignment A.1 step 5
                  • +
                • CLASSROOM_DAY2_ASSIGNMENT_URL = invite URL from assignment A.1 step 6
              5. Re-open each value and verify no leading or trailing spaces.
                6. @@ -514,20 +611,33 @@

                Step 0.2 Deploy optional registration-to-classroom automation settings

                Pass criteria:

                • Secret and variables are present with correct values.
                  • +
                • Initialize-WorkshopSetup.ps1 reported no failures, or manual verification confirms all 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.

                +

                Goal: validate the deployed registration system and site are working before manual QA begins.

                +

                Use Test-RegistrationPage.ps1 to run this check. The script validates the Pages site, the REGISTER page, the issue form template, required labels, and workflow state. With -RunLiveTest it also submits a real test registration issue, waits for the workflow, and verifies the welcome comment.

                +

                Static checks only (site, config, labels, workflow state):

                +
                scripts/classroom/Test-RegistrationPage.ps1
+
                +

                Full live end-to-end test including issue submission:

                +
                scripts/classroom/Test-RegistrationPage.ps1 -RunLiveTest
+
                +

                What the script checks:

                  -
                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. +
                5. HTTP GET to https://community-access.org/git-going-with-github/ returns 200.
                  6. +
                6. HTTP GET to https://community-access.org/git-going-with-github/REGISTER returns 200 and contains expected content.
                  7. +
                7. workshop-registration.yml exists in .github/ISSUE_TEMPLATE/.
                  8. +
                8. Labels registration, duplicate, and waitlist exist.
                  9. +
                9. registration.yml workflow is active and has a recent successful run.
                  10. +
                10. (Live test only) Test issue is submitted, workflow completes, welcome comment posts with assignment links, registration label is applied.
                +

                Cleanup limitation: the test issue is closed and locked by the script. It cannot be deleted via the GitHub API. If deletion is needed, a repository admin must delete it manually from the Issues tab after this run.

                Pass criteria:

                  -
                • Registration workflow executes successfully end to end.
                  • -
                • Output comment/labels match deployed configuration.
                  • +
                • Test-RegistrationPage.ps1 exits with no failures.
                  • +
                • Live test (if run) confirms workflow executes end to end.
                  • +
                • Output comment and labels match deployed configuration.

                Phase 1 - Registration System QA (Admin Side)

                Step 1. Verify public registration entry path

                @@ -544,22 +654,16 @@

                Step 1. Verify public registration entry path

              6. 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. -
            +

            If Initialize-WorkshopSetup.ps1 was run successfully in Phase 0, this step is already complete. Re-verify with:

            +
            gh secret list -R Community-Access/git-going-with-github
+gh variable list -R Community-Access/git-going-with-github
+
            +

            Expected output: CLASSROOM_ORG_ADMIN_TOKEN appears in secrets, and CLASSROOM_ORG, CLASSROOM_DAY1_ASSIGNMENT_URL, CLASSROOM_DAY2_ASSIGNMENT_URL appear in variables.

            +

            If any are missing, run Initialize-WorkshopSetup.ps1 again or follow the manual steps in section B of the setup instructions. For full reference, see REGISTRATION-QUICKSTART.md and REGISTRATION-ADMIN.md.

            Pass criteria:

              -
            • Secret exists and is scoped correctly.
              • -
            • All 3 variables exist and values are correct.
              • +
            • CLASSROOM_ORG_ADMIN_TOKEN secret is present.
              • +
            • All 3 variables are present with correct values and no leading or trailing spaces.

            Step 3. Execute registration happy-path test

            Use the non-admin test student account.

            @@ -696,67 +800,90 @@

            Step 9. Optional comprehensive harness check

            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. -
            +

            GitHub Classroom assignment creation has no write API. All classroom creation and assignment setup must be done through the browser at classroom.github.com while signed in as accesswatch.

            +

            Note: a classroom already exists for this repository (GIT Going with Github, classroom id 322783, linked to Community-Access-Classroom). Unless starting a completely new classroom, skip classroom creation and go directly to assignment creation in Steps 11 and 12.

            +

            If you do need a new classroom:

            +
              +
            1. Go to classroom.github.com as accesswatch.
              2. +
            2. Select New classroom and choose Community-Access-Classroom as the organization.
              3. +
            3. Name it Git Going - [Cohort Name] - [Month Year] (for example, Git Going - May 2026).
              4. +
            4. Import roster from classroom/roster-template.csv on the Roster tab.
              5. +
            5. Add accesswatch-student to the roster as the test student.
              6. +
            +

            To verify the existing classroom is accessible:

            +
            gh api /classrooms --jq '.[] | {id, name, url}'
+

            Pass criteria:

              -
            • Classroom exists and is accessible to facilitators.
              • -
            • Roster import succeeds with expected usernames.
              • +
            • Classroom exists in Community-Access-Classroom and is accessible to accesswatch.
              • +
            • Roster includes accesswatch-student (or the designated test student username).

            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. +

              See section A.1 of the setup steps above for full navigation instructions.

              +

              Use classroom/assignment-day1-you-belong-here.md and admin/classroom/day1-assignment-copy-paste.md for the exact title, description, and autograding entries.

              +

              To check if the Day 1 assignment already exists:

              +
              gh api /classrooms/322783/assignments --jq '.[] | {id, title, invite_link}'
+
              +

              If the assignment exists and its invite_link is already in the CLASSROOM_DAY1_ASSIGNMENT_URL variable, skip to Step 12.

              +

              If creating from scratch:

              +
                +
              1. Go to classroom.github.com as accesswatch and open the GIT Going with Github classroom.
                2. +
              2. Select New assignment.
                3. +
              3. Title: You Belong Here (exact match required)
                4. +
              4. Type: Individual, Visibility: Private
                5. +
              5. Template: Community-Access/learning-room-template
                6. +
              6. Grant students admin access: No
                7. +
              7. Enable feedback pull requests: Yes
                8. +
              8. Paste description from classroom/assignment-day1-you-belong-here.md
                9. +
              9. Add autograding from admin/classroom/autograding-setup.md -- Day 1 requires exactly 4 tests totaling 50 points
                10. +
              10. Save and copy the invite URL from the assignment page
                11. +
              11. If Initialize-WorkshopSetup.ps1 has not been run yet, paste the URL into CLASSROOM_DAY1_ASSIGNMENT_URL. If it has been run, re-run it to pick up the new URL automatically.

              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.
                • +
              • Day 1 assignment exists with title You Belong Here.
                • +
              • Test count is 4, total points is 50.
                • +
              • Feedback pull request is enabled.
                • +
              • CLASSROOM_DAY1_ASSIGNMENT_URL variable matches the assignment invite link.

              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. +

                Same process as Step 11. Check first whether it already exists:

                +
                gh api /classrooms/322783/assignments --jq '.[] | {id, title, invite_link}'
+
                +

                If the assignment exists and its invite_link is already in CLASSROOM_DAY2_ASSIGNMENT_URL, skip ahead.

                +

                If creating from scratch:

                +
                  +
                1. In the GIT Going with Github classroom, select New assignment.
                  2. +
                2. Title: You Can Build This (exact match required)
                  3. +
                3. Apply same base settings as Day 1 (individual, private, no admin access, feedback PR enabled)
                  4. +
                4. Template: Community-Access/learning-room-template
                  5. +
                5. Paste description from classroom/assignment-day2-you-can-build-this.md
                  6. +
                6. Add Day 2 autograding from admin/classroom/autograding-setup.md -- 6 tests totaling 75 points
                  7. +
                7. Save and copy the invite URL
                  8. +
                8. Update CLASSROOM_DAY2_ASSIGNMENT_URL or re-run Initialize-WorkshopSetup.ps1 to pick it up automatically

                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.
                  • +
                • Day 2 assignment exists with title You Can Build This.
                  • +
                • Test count is 6, total points is 75.
                  • +
                • Feedback pull request is enabled.
                  • +
                • CLASSROOM_DAY2_ASSIGNMENT_URL variable matches the assignment invite link.

                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. -
                +

                If Initialize-WorkshopSetup.ps1 was run after the assignments were created, the variables are already set. Verify with:

                +
                gh variable list -R Community-Access/git-going-with-github
+
                +

                If either URL variable is missing or stale, re-run the setup script. It will resolve URLs directly from the Classroom API:

                +
                scripts/classroom/Initialize-WorkshopSetup.ps1 -AdminPAT ghp_yourTokenHere -SkipTemplatePrepare -SkipTemplateValidate
+
                +

                Then re-run the registration live test to confirm both URLs appear in the welcome comment:

                +
                scripts/classroom/Test-RegistrationPage.ps1 -RunLiveTest
+

                Pass criteria:

                  -
                • Registration confirmation comment now includes both assignment URLs.
                  • +
                • CLASSROOM_DAY1_ASSIGNMENT_URL and CLASSROOM_DAY2_ASSIGNMENT_URL are set and match assignment invite links.
                  • +
                • Registration confirmation comment includes both assignment URLs.
                  • +
                • Test-RegistrationPage.ps1 -RunLiveTest exits with no failures.

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

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

                @@ -774,17 +901,28 @@

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

              7. 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
+
          The test student account is accesswatch-student. GitHub Classroom generates repository names from the assignment slug and the student username. For the default assignment titles, the repository names will be:
          
+
            
+
          • Day 1: Community-Access-Classroom/you-belong-here-accesswatch-student
            • 
+
          • Day 2: Community-Access-Classroom/you-can-build-this-accesswatch-student
            • 
+
          
+
          Confirm the exact repository names first:
          
+
          gh repo list Community-Access-Classroom --json name --jq '.[].name' | Select-String accesswatch-student
 
          
-
          If you use different repository names, replace values accordingly.
          
+
          Then seed (replace repository slugs with the confirmed names if different):
          
+
          $day1 = 'Community-Access-Classroom/you-belong-here-accesswatch-student'
+$day2 = 'Community-Access-Classroom/you-can-build-this-accesswatch-student'
+
+scripts/classroom/Seed-LearningRoomChallenge.ps1 -Repository $day1 -Challenge 1 -Assignee accesswatch-student
+scripts/classroom/Seed-PeerSimulation.ps1 -Repository $day1 -StudentUsername accesswatch-student
+scripts/classroom/Seed-LearningRoomChallenge.ps1 -Repository $day2 -Challenge 10 -Assignee accesswatch-student
+scripts/classroom/Seed-PeerSimulation.ps1 -Repository $day2 -StudentUsername accesswatch-student
+
          
+
          Alternatively, if Initialize-WorkshopSetup.ps1 is run after accesswatch-student has accepted both invites, it will detect the repos and seed them automatically.
          
 
          Pass criteria:
          
 
            
-
          • Challenge 1 appears in Day 1 repo.
            • 
-
          • Challenge 10 appears in Day 2 repo.
            • 
+
          • Challenge 1 issue appears in Day 1 repo assigned to accesswatch-student.
            • 
+
          • Challenge 10 issue appears in Day 2 repo assigned to accesswatch-student.
            • 
 
          • Peer simulation issues and PR exist in both repos.
            • 
 
          
 
          Phase 5 - Curriculum Content QA (Walk every required chapter and appendix)
          
@@ -1885,6 +2023,141 @@ 
          Completion Output Template (Copy into QA Issue)
          
 
          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.
          
+
          Script Reference
          
+
          The following scripts in scripts/classroom/ are used by this runbook. Run each with -? or read the .SYNOPSIS block for full parameter documentation.
          
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
          ScriptPurposeAutomated
          Initialize-WorkshopSetup.ps1Set PAT secret, variables, labels; sync and validate template; seed test student challengesAll steps except PAT generation (browser required)
          Archive-CohortData.ps1Export cohort issues, roster, and discussions to git-going-student-success; reset source repoExport and archive are automated; roster reset may require PR due branch rules
          Delete-RegistrationIssues.ps1Delete registration/duplicate/waitlist issues via GraphQL mutationFully automated when user has repo admin and repo token scope
          Delete-RegistrationIssues-v2.jsExperimental Playwright UI deleter for issue cleanupPartially automated; UI selector fragility makes this fallback-only
          Test-RegistrationPage.ps1Validate Pages site, REGISTER page, issue form, labels, workflow, and live registration flowAll steps; test issue cleanup is close+lock only (see below)
          Prepare-LearningRoomTemplate.ps1Sync learning-room/ source into Community-Access/learning-room-templateFully automated
          Test-LearningRoomTemplate.ps1Create smoke repo from template, validate file inventory and workflow dispatchFully automated
          Seed-LearningRoomChallenge.ps1Seed a specific challenge issue in a student repositoryFully automated
          Seed-PeerSimulation.ps1Seed peer simulation issues and PR in a student repositoryFully automated
          Restore-LearningRoomFiles.ps1Restore baseline files into a student repo via recovery branch and PRFully automated
          Invoke-LearningRoomEndToEndTest.ps1Full end-to-end scripted QA harnessFully automated
          
+
          GitHub API Limitations
          
+
          The following actions cannot be performed via any GitHub API and require manual browser-based action. These are hard platform constraints, not gaps in the scripts.
          
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
          ActionWhy it cannot be automatedManual path
          Creating a Classroom assignmentNo write endpoint exists in the GitHub Classroom REST API (confirmed: only GET endpoints are documented and available)classroom.github.com as accesswatch
          Deleting issues via REST APIGitHub REST API has no DELETE endpoint for issuesUse scripts/classroom/Delete-RegistrationIssues.ps1 (GraphQL mutation path), or UI fallback
          Deleting or moving discussionsGraphQL discussion mutations do not include delete or move operationsDiscussions tab in GitHub UI -> each thread -> "..." -> Delete
          Generating a personal access tokenPAT generation requires browser authentication by designgithub.com/settings/tokens as accesswatch
          
+
          Pre-Cohort Cleanup Procedure
          
+
          Run this procedure after each cohort completes, before starting QA for the next cohort.
          
+
          Archive previous cohort data
          
+
          # Replace the slug with the cohort being archived (format: YYYY-MM-description)
+scripts/classroom/Archive-CohortData.ps1 -CohortSlug 2026-03-march-cohort
+
          
+
          What this does:
          
+
            
+
          1. Exports all registration/duplicate/waitlist issues (with comments) to JSON and CSV.
            2. 
+
          2. Exports the current student-roster.json.
            3. 
+
          3. Exports discussions to JSON.
            4. 
+
          4. Pushes the archive to Community-Access/git-going-student-success under admin/cohorts/<CohortSlug>/.
            5. 
+
          5. Closes and locks all registration issues in the source repository.
            6. 
+
          6. Resets student-roster.json to the blank template.
            7. 
+
          
+
          Use -WhatIf to preview without making changes:
          
+
          scripts/classroom/Archive-CohortData.ps1 -CohortSlug 2026-03-march-cohort -WhatIf
+
          
+
          After the script completes, two manual cleanup steps are required (API limitation):
          
+
            
+
          1. Delete registration issues -- use the GraphQL cleanup script (recommended):
            2. 
+
          
+
          scripts/classroom/Delete-RegistrationIssues.ps1
+
          
+
            
+
          1. Delete discussions -- discussions still require manual deletion:
+https://github.com/Community-Access/git-going-with-github/discussions
            2. 
+
          
+
          Archive destination: https://github.com/Community-Access/git-going-student-success/tree/main/admin/cohorts/<CohortSlug>/
          
+
          Current Progress Snapshot (2026-05-08)
          
+
            
+
          •  Registration issues archived to git-going-student-success.
            • 
+
          •  Registration issues deleted from source repository (count now 0).
            • 
+
          •  Discussions deleted from source repository (count now 0).
            • 
+
          •  Learning Room template sync PR merged: Community-Access/learning-room-template#11.
            • 
+
          •  Registration secret and variable values set for next cohort (CLASSROOM_ORG_ADMIN_TOKEN, CLASSROOM_ORG, CLASSROOM_DAY1_ASSIGNMENT_URL, CLASSROOM_DAY2_ASSIGNMENT_URL).
            • 
+
          •  Day 1 and Day 2 classroom assignments created for next cohort.
            • 
+
          
 
 
 
\ 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
index 4eb253c6..f51cb2ac 100644
--- a/admin/qa-bundle/admin/LEARNING-ROOM-E2E-QA-RUNBOOK.md
+++ b/admin/qa-bundle/admin/LEARNING-ROOM-E2E-QA-RUNBOOK.md
@@ -48,41 +48,46 @@ The following table lists the source files this runbook consolidates.
 | 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) |
+| Support hub operations | [SUPPORT_HUB_OPERATIONS.md](SUPPORT_HUB_OPERATIONS.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.
+- Facilitator admin account (`accesswatch`) with Owner access to both `Community-Access` and `Community-Access-Classroom`.
+- Dedicated non-admin test student account for acceptance and full challenge walkthrough. This must be a separate GitHub account that is not an owner or member of either organization.
+- Access to [classroom.github.com](https://classroom.github.com) while signed in as `accesswatch`.
+- Access to repository settings for `Community-Access/git-going-with-github` (secrets and variables).
 - Local clone of this repository with PowerShell available.
-- GitHub CLI (`gh`) installed and authenticated for optional verification commands.
+- GitHub CLI (`gh`) installed and authenticated as `accesswatch` for optional verification commands.
 
 ### Critical Precondition Gates (No-Go if any fail)
 
 Complete all items below before any cohort launch actions.
 
-- [ ] Facilitator account 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.
+- [ ] Facilitator account `accesswatch` can access both organizations:
+   - [ ] `Community-Access` (the workshop and code repository organization)
+   - [ ] `Community-Access-Classroom` (the GitHub Classroom organization where student repos are created)
+- [ ] `accesswatch` has a verified email address on its GitHub account and can create and edit Classroom assignments at [classroom.github.com](https://classroom.github.com).
 - [ ] 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
+- [x] `gh auth status` succeeds for `accesswatch` in local terminal.
+- [x] Template repository exists and is set as template repo:
+   - [x] `Community-Access/learning-room-template`
+- [x] Template repository Actions settings allow required automation behavior:
+   - [x] Actions enabled
+   - [x] `GITHUB_TOKEN` default workflow permissions include write where required
+   - [x] `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.
+   - [ ] Secret `CLASSROOM_ORG_ADMIN_TOKEN` is set in `Community-Access/git-going-with-github`
+   - [ ] Variables `CLASSROOM_ORG`, `CLASSROOM_DAY1_ASSIGNMENT_URL`, `CLASSROOM_DAY2_ASSIGNMENT_URL` are set in `Community-Access/git-going-with-github`
+- [x] Registration entry configuration exists and is valid:
+   - [x] Issue form template `workshop-registration.yml` exists
+   - [x] Required labels exist: `registration`, `duplicate`, `waitlist`
+- [ ] Support hub is ready for student onboarding:
+   - [ ] `Community-Access/support` is public and reachable
+   - [ ] Issues and Discussions are enabled
+   - [ ] Support labels and templates are present
+- [ ] While signed in as `accesswatch`, opening [classroom.github.com](https://classroom.github.com) shows the `Community-Access-Classroom` classroom organization.
 
 If any precondition fails, stop and resolve before proceeding.
 
@@ -92,13 +97,17 @@ 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:
+You are performing all steps below as `accesswatch`. If you are currently signed in to GitHub as a different account, sign out first and sign in as `accesswatch` before continuing.
+
+1. Go to [github.com](https://github.com) and confirm the top-right avatar shows `accesswatch`.
+2. Open the avatar menu, then select **Your organizations**.
+3. Confirm both of the following organizations appear in the list:
+   - `Community-Access` -- the main workshop repository organization
+   - `Community-Access-Classroom` -- the GitHub Classroom organization where student repos are created
+   - If either is missing, do not proceed. Contact the org owner to ensure `accesswatch` has Owner-level membership in both.
+4. Click into `Community-Access` and open the **Settings** tab. Confirm you can see the full settings sidebar (Members, Actions, Secrets, etc.). If Settings is not visible, `accesswatch` does not have Owner access and you cannot proceed.
+5. Click into `Community-Access-Classroom` and open its **Settings** tab. Confirm the same.
+6. Optional CLI verification from the local repository root:
 
 ```powershell
 gh auth status -h github.com
@@ -106,28 +115,101 @@ gh repo view Community-Access/git-going-with-github
 gh repo view Community-Access/learning-room-template
 ```
 
+Expected output: each `gh repo view` command should return repository metadata without an error. If you see "Could not resolve to a Repository", `accesswatch` does not have the required access.
+
 Why this matters:
 
-- All downstream setup fails if the facilitator identity is not correctly scoped.
+- All downstream setup steps operate against `Community-Access/git-going-with-github` and `Community-Access-Classroom`. If the account does not have Owner access to both, secrets, variables, and classroom automation cannot be configured.
+
+#### A.1 Create GitHub Classroom assignments
+
+Do this before section B. You need both assignment URLs in hand before you can fill in the repository variables.
+
+You must be signed in to GitHub as `accesswatch` for the following steps.
+
+1. Go to [classroom.github.com](https://classroom.github.com).
+2. You will see a list of classrooms. Select the classroom named for this cohort that is linked to the `Community-Access-Classroom` organization. The organization name appears below the classroom name on the card.
+   - If no classroom exists yet, select **New classroom**, then choose `Community-Access-Classroom` as the organization. Name the classroom using the format `Git Going - [Cohort Name] - [Month Year]` (for example, `Git Going - May 2026`).
+3. Inside the classroom, select **New assignment**.
+4. Create the Day 1 assignment:
+   - **Title**: `You Belong Here`
+   - **Individual or group**: Individual
+   - **Repository visibility**: Private
+   - **Template repository**: `Community-Access/learning-room-template` (search for it by name in the template field)
+   - **Grant students admin access**: No
+   - **Enable feedback pull requests**: Yes
+   - Paste the Day 1 assignment description from [classroom/assignment-day1-you-belong-here.md](../classroom/assignment-day1-you-belong-here.md)
+   - Add autograding from [admin/classroom/autograding-setup.md](classroom/autograding-setup.md) -- Day 1 requires exactly 4 tests totaling 50 points
+   - Select **Create assignment**
+5. After saving, the assignment page shows an invite link at the top labeled something like **Invite link**. It will be in the format `https://classroom.github.com/a/`. Copy this full URL and paste it somewhere safe (for example, a scratch notepad). This is your `CLASSROOM_DAY1_ASSIGNMENT_URL`.
+6. Repeat for the Day 2 assignment:
+   - **Title**: `You Can Build This`
+   - Same base settings as Day 1
+   - Paste description from [classroom/assignment-day2-you-can-build-this.md](../classroom/assignment-day2-you-can-build-this.md)
+   - Add Day 2 autograding: exactly 6 tests totaling 75 points
+   - Copy the resulting invite URL. This is your `CLASSROOM_DAY2_ASSIGNMENT_URL`.
+7. Keep both URLs available. You will paste them into repository variables in section B step 4.
+
+Why this matters:
+
+- The repository variables `CLASSROOM_DAY1_ASSIGNMENT_URL` and `CLASSROOM_DAY2_ASSIGNMENT_URL` cannot be filled in until the assignments exist and their invite URLs are known. The short code in the URL is unique to each assignment and is not predictable in advance.
 
 #### 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.
+You must be signed in as `accesswatch` for all steps in this section.
+
+**Step B.1 -- Generate the personal access token (PAT)**
+
+The `CLASSROOM_ORG_ADMIN_TOKEN` secret must be a GitHub personal access token generated by `accesswatch` (or another Owner-level account for `Community-Access-Classroom`). This token is what allows the registration workflow to invite students to the `Community-Access-Classroom` organization automatically.
+
+1. While signed in as `accesswatch`, go to [github.com/settings/tokens](https://github.com/settings/tokens).
+2. Select **Generate new token**, then select **Generate new token (classic)**.
+   - Do not use fine-grained tokens for this purpose. The `admin:org` scope is only available on classic tokens.
+3. In the **Note** field enter a descriptive name such as `Community-Access registration automation`.
+4. In the **Expiration** field, set a date that covers your cohort timeline plus a buffer (for example, 90 days).
+5. Under **Select scopes**, check `admin:org`. This is the only scope required. It gives the token permission to list and create organization invitations for `Community-Access-Classroom`.
+6. Scroll to the bottom and select **Generate token**.
+7. GitHub will display the token exactly once immediately after generation. It begins with `ghp_`. Copy it now and paste it somewhere safe (a local scratch notepad, not a repository file). You will not be able to view it again.
+8. Do not close the token page until you have completed section B.2 and confirmed the secret was saved.
+
+**Step B.2 -- Add the token as a repository secret**
+
+1. Go to [github.com/Community-Access/git-going-with-github/settings/secrets/actions](https://github.com/Community-Access/git-going-with-github/settings/secrets/actions).
+2. Select **New repository secret**.
+3. In the **Name** field, enter exactly: `CLASSROOM_ORG_ADMIN_TOKEN`
+   - Capitalization and underscores must match exactly.
+4. In the **Secret** field, paste the token you copied in step B.1.
+5. Select **Add secret**.
+6. Re-open the secret entry and confirm the name shows `CLASSROOM_ORG_ADMIN_TOKEN`. GitHub does not display the value again, but confirming the name is correct is sufficient.
+
+**Step B.3 -- Add the repository variables**
+
+1. At the same settings page, select the **Variables** tab (next to Secrets).
+2. Select **New repository variable** for each of the following. Add them one at a time.
+
+   Variable 1:
+   - **Name**: `CLASSROOM_ORG`
+   - **Value**: `Community-Access-Classroom`
+   - This is the exact GitHub organization name where students are invited. The capitalization and hyphens must match exactly.
+
+   Variable 2:
+   - **Name**: `CLASSROOM_DAY1_ASSIGNMENT_URL`
+   - **Value**: paste the Day 1 invite URL you copied in section A.1 step 5 (format: `https://classroom.github.com/a/`)
+
+   Variable 3:
+   - **Name**: `CLASSROOM_DAY2_ASSIGNMENT_URL`
+   - **Value**: paste the Day 2 invite URL you copied in section A.1 step 6 (format: `https://classroom.github.com/a/`)
+
+3. After adding all three, re-open each variable entry and confirm:
+   - The name is exactly as listed above (no typos, no extra characters).
+   - The value has no leading or trailing spaces. Paste into a plain text editor first if you are unsure, and trim whitespace before re-pasting.
+4. Run one registration test and confirm welcome comment contains assignment links.
 
 Why this matters:
 
-- These values drive invite and assignment-link injection in registration responses.
+- These values drive invite and assignment-link injection in registration responses. A single typo in the org name or a trailing space in a variable value will silently break automation without a clear error message.
 
 #### C. Configure template repository Actions permissions
 
@@ -353,32 +435,73 @@ Pass criteria:
 
 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.
+The fastest path is `Initialize-WorkshopSetup.ps1`, which sets the secret, all three variables, verifies labels, and runs template prep in a single command. See the setup script section below.
+
+**Using the setup script (recommended):**
+
+```powershell
+scripts/classroom/Initialize-WorkshopSetup.ps1 -AdminPAT ghp_yourTokenHere
+```
+
+The script will:
+- Prompt you if the PAT is missing or invalid
+- Resolve Day 1 and Day 2 assignment URLs automatically from the GitHub Classroom API (if assignments exist in the `GIT Going with Github` classroom)
+- Set `CLASSROOM_ORG_ADMIN_TOKEN` secret and all three variables in `Community-Access/git-going-with-github`
+- Verify all three required labels exist, creating any that are missing
+- Confirm read-back values have no leading or trailing spaces
+- Run `Prepare-LearningRoomTemplate.ps1` and `Test-LearningRoomTemplate.ps1` unless skipped
+
+**If running manually instead:**
+
+1. Generate a classic PAT with `admin:org` scope at [github.com/settings/tokens](https://github.com/settings/tokens) (see section B of the setup steps above for exact steps).
+2. Go to [github.com/Community-Access/git-going-with-github/settings/secrets/actions](https://github.com/Community-Access/git-going-with-github/settings/secrets/actions).
+3. Create secret `CLASSROOM_ORG_ADMIN_TOKEN` with the PAT value.
+4. On the Variables tab, create:
+   - `CLASSROOM_ORG` = `Community-Access-Classroom`
+   - `CLASSROOM_DAY1_ASSIGNMENT_URL` = invite URL from assignment A.1 step 5
+   - `CLASSROOM_DAY2_ASSIGNMENT_URL` = invite URL from assignment A.1 step 6
+5. Re-open each value and verify no leading or trailing spaces.
 
 Pass criteria:
 
 - Secret and variables are present with correct values.
+- `Initialize-WorkshopSetup.ps1` reported no failures, or manual verification confirms all 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.
+Goal: validate the deployed registration system and site are working before manual QA begins.
+
+Use `Test-RegistrationPage.ps1` to run this check. The script validates the Pages site, the REGISTER page, the issue form template, required labels, and workflow state. With `-RunLiveTest` it also submits a real test registration issue, waits for the workflow, and verifies the welcome comment.
+
+**Static checks only (site, config, labels, workflow state):**
+
+```powershell
+scripts/classroom/Test-RegistrationPage.ps1
+```
+
+**Full live end-to-end test including issue submission:**
+
+```powershell
+scripts/classroom/Test-RegistrationPage.ps1 -RunLiveTest
+```
+
+What the script checks:
+
+1. HTTP GET to `https://community-access.org/git-going-with-github/` returns 200.
+2. HTTP GET to `https://community-access.org/git-going-with-github/REGISTER` returns 200 and contains expected content.
+3. `workshop-registration.yml` exists in `.github/ISSUE_TEMPLATE/`.
+4. Labels `registration`, `duplicate`, and `waitlist` exist.
+5. `registration.yml` workflow is active and has a recent successful run.
+6. (Live test only) Test issue is submitted, workflow completes, welcome comment posts with assignment links, `registration` label is applied.
 
-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.
+Cleanup limitation: the test issue is closed and locked by the script. It **cannot be deleted via the GitHub API**. If deletion is needed, a repository admin must delete it manually from the Issues tab after this run.
 
 Pass criteria:
 
-- Registration workflow executes successfully end to end.
-- Output comment/labels match deployed configuration.
+- `Test-RegistrationPage.ps1` exits with no failures.
+- Live test (if run) confirms workflow executes end to end.
+- Output comment and labels match deployed configuration.
 
 ## Phase 1 - Registration System QA (Admin Side)
 
@@ -393,22 +516,36 @@ Pass criteria:
 - Registration link opens correctly.
 - Registration issue title is prefilled with `[REGISTER]`.
 - Public visibility warning is present.
+- Support links point to `Community-Access/support` issues/discussions.
+
+### Step 1.1 Verify support hub onboarding path
+
+1. Open `Community-Access/support` and confirm Issues and Discussions are enabled.
+2. Confirm pinned Start Here onboarding guidance exists in Discussions.
+3. Open a test support issue using a template and confirm triage labels apply.
+
+Pass criteria:
+
+- Support hub is reachable and public.
+- Onboarding path is discoverable for students.
+- Template-driven support issue flow works.
 
 ### 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.
+If `Initialize-WorkshopSetup.ps1` was run successfully in Phase 0, this step is already complete. Re-verify with:
+
+```powershell
+gh secret list -R Community-Access/git-going-with-github
+gh variable list -R Community-Access/git-going-with-github
+```
 
-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.
+Expected output: `CLASSROOM_ORG_ADMIN_TOKEN` appears in secrets, and `CLASSROOM_ORG`, `CLASSROOM_DAY1_ASSIGNMENT_URL`, `CLASSROOM_DAY2_ASSIGNMENT_URL` appear in variables.
+
+If any are missing, run `Initialize-WorkshopSetup.ps1` again or follow the manual steps in section B of the setup instructions. For full reference, see [REGISTRATION-QUICKSTART.md](REGISTRATION-QUICKSTART.md) and [REGISTRATION-ADMIN.md](REGISTRATION-ADMIN.md).
 
 Pass criteria:
-- Secret exists and is scoped correctly.
-- All 3 variables exist and values are correct.
+- `CLASSROOM_ORG_ADMIN_TOKEN` secret is present.
+- All 3 variables are present with correct values and no leading or trailing spaces.
 
 ### Step 3. Execute registration happy-path test
 
@@ -557,63 +694,113 @@ Use full end-to-end mode when preparing major cohort launches or after significa
 
 ### Step 10. Create classroom and import roster
 
-Use [classroom/README.md](../classroom/README.md) Steps 1 and 2.
+GitHub Classroom assignment creation has **no write API**. All classroom creation and assignment setup must be done through the browser at [classroom.github.com](https://classroom.github.com) while signed in as `accesswatch`.
+
+Note: a classroom already exists for this repository (`GIT Going with Github`, classroom id 322783, linked to `Community-Access-Classroom`). Unless starting a completely new classroom, skip classroom creation and go directly to assignment creation in Steps 11 and 12.
 
-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.
+**If you do need a new classroom:**
+
+1. Go to [classroom.github.com](https://classroom.github.com) as `accesswatch`.
+2. Select **New classroom** and choose `Community-Access-Classroom` as the organization.
+3. Name it `Git Going - [Cohort Name] - [Month Year]` (for example, `Git Going - May 2026`).
+4. Import roster from [classroom/roster-template.csv](../classroom/roster-template.csv) on the Roster tab.
+5. Add `accesswatch-student` to the roster as the test student.
+
+**To verify the existing classroom is accessible:**
+
+```powershell
+gh api /classrooms --jq '.[] | {id, name, url}'
+```
 
 Pass criteria:
-- Classroom exists and is accessible to facilitators.
-- Roster import succeeds with expected usernames.
+- Classroom exists in `Community-Access-Classroom` and is accessible to `accesswatch`.
+- Roster includes `accesswatch-student` (or the designated test student username).
 
 ### 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).
+See section A.1 of the setup steps above for full navigation instructions.
+
+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) for the exact title, description, and autograding entries.
+
+**To check if the Day 1 assignment already exists:**
+
+```powershell
+gh api /classrooms/322783/assignments --jq '.[] | {id, title, invite_link}'
+```
+
+If the assignment exists and its `invite_link` is already in the `CLASSROOM_DAY1_ASSIGNMENT_URL` variable, skip to Step 12.
 
-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.
+**If creating from scratch:**
+
+1. Go to [classroom.github.com](https://classroom.github.com) as `accesswatch` and open the `GIT Going with Github` classroom.
+2. Select **New assignment**.
+3. Title: `You Belong Here` (exact match required)
+4. Type: Individual, Visibility: Private
+5. Template: `Community-Access/learning-room-template`
+6. Grant students admin access: No
+7. Enable feedback pull requests: Yes
+8. Paste description from [classroom/assignment-day1-you-belong-here.md](../classroom/assignment-day1-you-belong-here.md)
+9. Add autograding from [admin/classroom/autograding-setup.md](classroom/autograding-setup.md) -- Day 1 requires exactly 4 tests totaling 50 points
+10. Save and copy the invite URL from the assignment page
+11. If `Initialize-WorkshopSetup.ps1` has not been run yet, paste the URL into `CLASSROOM_DAY1_ASSIGNMENT_URL`. If it has been run, re-run it to pick up the new URL automatically.
 
 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.
+- Day 1 assignment exists with title `You Belong Here`.
+- Test count is 4, total points is 50.
+- Feedback pull request is enabled.
+- `CLASSROOM_DAY1_ASSIGNMENT_URL` variable matches the assignment invite link.
 
 ### 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).
+Same process as Step 11. Check first whether it already exists:
+
+```powershell
+gh api /classrooms/322783/assignments --jq '.[] | {id, title, invite_link}'
+```
+
+If the assignment exists and its `invite_link` is already in `CLASSROOM_DAY2_ASSIGNMENT_URL`, skip ahead.
 
-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.
+**If creating from scratch:**
+
+1. In the `GIT Going with Github` classroom, select **New assignment**.
+2. Title: `You Can Build This` (exact match required)
+3. Apply same base settings as Day 1 (individual, private, no admin access, feedback PR enabled)
+4. Template: `Community-Access/learning-room-template`
+5. Paste description from [classroom/assignment-day2-you-can-build-this.md](../classroom/assignment-day2-you-can-build-this.md)
+6. Add Day 2 autograding from [admin/classroom/autograding-setup.md](classroom/autograding-setup.md) -- 6 tests totaling 75 points
+7. Save and copy the invite URL
+8. Update `CLASSROOM_DAY2_ASSIGNMENT_URL` or re-run `Initialize-WorkshopSetup.ps1` to pick it up automatically
 
 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.
+- Day 2 assignment exists with title `You Can Build This`.
+- Test count is 6, total points is 75.
+- Feedback pull request is enabled.
+- `CLASSROOM_DAY2_ASSIGNMENT_URL` variable matches the assignment invite link.
 
 ### 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.
+If `Initialize-WorkshopSetup.ps1` was run after the assignments were created, the variables are already set. Verify with:
+
+```powershell
+gh variable list -R Community-Access/git-going-with-github
+```
+
+If either URL variable is missing or stale, re-run the setup script. It will resolve URLs directly from the Classroom API:
+
+```powershell
+scripts/classroom/Initialize-WorkshopSetup.ps1 -AdminPAT ghp_yourTokenHere -SkipTemplatePrepare -SkipTemplateValidate
+```
+
+Then re-run the registration live test to confirm both URLs appear in the welcome comment:
+
+```powershell
+scripts/classroom/Test-RegistrationPage.ps1 -RunLiveTest
+```
 
 Pass criteria:
-- Registration confirmation comment now includes both assignment URLs.
+- `CLASSROOM_DAY1_ASSIGNMENT_URL` and `CLASSROOM_DAY2_ASSIGNMENT_URL` are set and match assignment invite links.
+- Registration confirmation comment includes both assignment URLs.
+- `Test-RegistrationPage.ps1 -RunLiveTest` exits with no failures.
 
 ## Phase 4 - Test Student Acceptance and Seeding (Bridge from Admin to Student)
 
@@ -633,20 +820,34 @@ Pass criteria:
 
 ### Step 15. Seed initial challenges and peer simulation
 
-Run commands from repository root.
+The test student account is `accesswatch-student`. GitHub Classroom generates repository names from the assignment slug and the student username. For the default assignment titles, the repository names will be:
+
+- Day 1: `Community-Access-Classroom/you-belong-here-accesswatch-student`
+- Day 2: `Community-Access-Classroom/you-can-build-this-accesswatch-student`
+
+Confirm the exact repository names first:
+
+```powershell
+gh repo list Community-Access-Classroom --json name --jq '.[].name' | Select-String accesswatch-student
+```
+
+Then seed (replace repository slugs with the confirmed names if different):
 
 ```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
+$day1 = 'Community-Access-Classroom/you-belong-here-accesswatch-student'
+$day2 = 'Community-Access-Classroom/you-can-build-this-accesswatch-student'
+
+scripts/classroom/Seed-LearningRoomChallenge.ps1 -Repository $day1 -Challenge 1 -Assignee accesswatch-student
+scripts/classroom/Seed-PeerSimulation.ps1 -Repository $day1 -StudentUsername accesswatch-student
+scripts/classroom/Seed-LearningRoomChallenge.ps1 -Repository $day2 -Challenge 10 -Assignee accesswatch-student
+scripts/classroom/Seed-PeerSimulation.ps1 -Repository $day2 -StudentUsername accesswatch-student
 ```
 
-If you use different repository names, replace values accordingly.
+Alternatively, if `Initialize-WorkshopSetup.ps1` is run after `accesswatch-student` has accepted both invites, it will detect the repos and seed them automatically.
 
 Pass criteria:
-- Challenge 1 appears in Day 1 repo.
-- Challenge 10 appears in Day 2 repo.
+- Challenge 1 issue appears in Day 1 repo assigned to `accesswatch-student`.
+- Challenge 10 issue appears in Day 2 repo assigned to `accesswatch-student`.
 - Peer simulation issues and PR exist in both repos.
 
 ## Phase 5 - Curriculum Content QA (Walk every required chapter and appendix)
@@ -1336,4 +1537,82 @@ Release Decision:
 
 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
+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.
+
+## Script Reference
+
+The following scripts in `scripts/classroom/` are used by this runbook. Run each with `-?` or read the `.SYNOPSIS` block for full parameter documentation.
+
+| Script | Purpose | Automated |
+|---|---|---|
+| `Initialize-WorkshopSetup.ps1` | Set PAT secret, variables, labels; sync and validate template; seed test student challenges | All steps except PAT generation (browser required) |
+| `Archive-CohortData.ps1` | Export cohort issues, roster, and discussions to `git-going-student-success`; reset source repo | Export and archive are automated; roster reset may require PR due branch rules |
+| `Delete-RegistrationIssues.ps1` | Delete registration/duplicate/waitlist issues via GraphQL mutation | Fully automated when user has repo admin and `repo` token scope |
+| `Delete-RegistrationIssues-v2.js` | Experimental Playwright UI deleter for issue cleanup | Partially automated; UI selector fragility makes this fallback-only |
+| `Test-RegistrationPage.ps1` | Validate Pages site, REGISTER page, issue form, labels, workflow, and live registration flow | All steps; test issue cleanup is close+lock only (see below) |
+| `Prepare-LearningRoomTemplate.ps1` | Sync `learning-room/` source into `Community-Access/learning-room-template` | Fully automated |
+| `Test-LearningRoomTemplate.ps1` | Create smoke repo from template, validate file inventory and workflow dispatch | Fully automated |
+| `Seed-LearningRoomChallenge.ps1` | Seed a specific challenge issue in a student repository | Fully automated |
+| `Seed-PeerSimulation.ps1` | Seed peer simulation issues and PR in a student repository | Fully automated |
+| `Restore-LearningRoomFiles.ps1` | Restore baseline files into a student repo via recovery branch and PR | Fully automated |
+| `Invoke-LearningRoomEndToEndTest.ps1` | Full end-to-end scripted QA harness | Fully automated |
+| `Reset-SupportHubEnvironment.ps1` | Rebuild support hub repository labels, settings, and baseline support automation | Fully automated |
+
+## GitHub API Limitations
+
+The following actions cannot be performed via any GitHub API and require manual browser-based action. These are hard platform constraints, not gaps in the scripts.
+
+| Action | Why it cannot be automated | Manual path |
+|---|---|---|
+| Creating a Classroom assignment | No write endpoint exists in the GitHub Classroom REST API (confirmed: only GET endpoints are documented and available) | [classroom.github.com](https://classroom.github.com) as `accesswatch` |
+| Deleting issues via REST API | GitHub REST API has no DELETE endpoint for issues | Use `scripts/classroom/Delete-RegistrationIssues.ps1` (GraphQL mutation path), or UI fallback |
+| Deleting or moving discussions | GraphQL discussion mutations do not include delete or move operations | Discussions tab in GitHub UI -> each thread -> "..." -> Delete |
+| Generating a personal access token | PAT generation requires browser authentication by design | [github.com/settings/tokens](https://github.com/settings/tokens) as `accesswatch` |
+
+## Pre-Cohort Cleanup Procedure
+
+Run this procedure after each cohort completes, before starting QA for the next cohort.
+
+### Archive previous cohort data
+
+```powershell
+# Replace the slug with the cohort being archived (format: YYYY-MM-description)
+scripts/classroom/Archive-CohortData.ps1 -CohortSlug 2026-03-march-cohort
+```
+
+What this does:
+
+1. Exports all registration/duplicate/waitlist issues (with comments) to JSON and CSV.
+2. Exports the current `student-roster.json`.
+3. Exports discussions to JSON.
+4. Pushes the archive to `Community-Access/git-going-student-success` under `admin/cohorts//`.
+5. Closes and locks all registration issues in the source repository.
+6. Resets `student-roster.json` to the blank template.
+
+Use `-WhatIf` to preview without making changes:
+
+```powershell
+scripts/classroom/Archive-CohortData.ps1 -CohortSlug 2026-03-march-cohort -WhatIf
+```
+
+After the script completes, two manual cleanup steps are required (API limitation):
+
+1. **Delete registration issues** -- use the GraphQL cleanup script (recommended):
+
+```powershell
+scripts/classroom/Delete-RegistrationIssues.ps1
+```
+
+2. **Delete discussions** -- discussions still require manual deletion:
+   `https://github.com/Community-Access/git-going-with-github/discussions`
+
+Archive destination: `https://github.com/Community-Access/git-going-student-success/tree/main/admin/cohorts//`
+
+### Current Progress Snapshot (2026-05-08)
+
+- [x] Registration issues archived to `git-going-student-success`.
+- [x] Registration issues deleted from source repository (count now 0).
+- [x] Discussions deleted from source repository (count now 0).
+- [x] Learning Room template sync PR merged: `Community-Access/learning-room-template#11`.
+- [ ] Registration secret and variable values set for next cohort (`CLASSROOM_ORG_ADMIN_TOKEN`, `CLASSROOM_ORG`, `CLASSROOM_DAY1_ASSIGNMENT_URL`, `CLASSROOM_DAY2_ASSIGNMENT_URL`).
+- [ ] Day 1 and Day 2 classroom assignments created for next cohort.
\ No newline at end of file
diff --git a/admin/qa-bundle/admin/REGISTRATION-QUICKSTART.md b/admin/qa-bundle/admin/REGISTRATION-QUICKSTART.md
index 36ecc258..75e047c4 100644
--- a/admin/qa-bundle/admin/REGISTRATION-QUICKSTART.md
+++ b/admin/qa-bundle/admin/REGISTRATION-QUICKSTART.md
@@ -65,6 +65,14 @@ If anything behaves unexpectedly, disable classroom API automation without stopp
 
 The registration workflow will continue standard confirmation, capacity checks, and CSV export.
 
+## Full Support Reset (When Needed)
+
+If support environment drift is detected, rebuild support hub baseline:
+
+```powershell
+scripts/classroom/Reset-SupportHubEnvironment.ps1
+```
+
 ## Day-Of Operations
 
 1. Keep [REGISTRATION-ADMIN.md](REGISTRATION-ADMIN.md) open.
diff --git a/admin/qa-bundle/docs/00-pre-workshop-setup.md b/admin/qa-bundle/docs/00-pre-workshop-setup.md
index 8fc1b569..ed391a93 100644
--- a/admin/qa-bundle/docs/00-pre-workshop-setup.md
+++ b/admin/qa-bundle/docs/00-pre-workshop-setup.md
@@ -10,7 +10,7 @@
 
 > **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.
+> **Please complete this guide at least one day before the workshop.** If you run into any issues, use the support hub at [Community-Access/support](https://github.com/Community-Access/support) 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.
 
@@ -961,15 +961,15 @@ We are not covering Git commands in this workshop. If you want to learn Git, the
 | 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. |
+| Everything else | File a support issue at [Community-Access/support/issues](https://github.com/Community-Access/support/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
+1. **File a setup support issue** - [Community-Access/support/issues](https://github.com/Community-Access/support/issues) - we will help you get set up
+2. **Join Support Hub Discussions** - [Community-Access/support/discussions](https://github.com/Community-Access/support/discussions) - read pinned Start Here guidance and ask follow-up questions
 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.
diff --git a/admin/qa-bundle/docs/21-next-steps.md b/admin/qa-bundle/docs/21-next-steps.md
index 185f4faf..739d1e63 100644
--- a/admin/qa-bundle/docs/21-next-steps.md
+++ b/admin/qa-bundle/docs/21-next-steps.md
@@ -215,7 +215,7 @@ Each course takes 15 to 60 minutes.
 ### Community Access
 
 - [Community Access on GitHub](https://github.com/Community-Access) -- The organization behind this workshop. Watch the repositories for updates.
-- Workshop facilitators are available for questions after the event. Post on the learning-room repository or the git-going-with-github repository.
+- For post-workshop questions, troubleshooting, and alumni conversation, use the open support hub: [Community-Access/support](https://github.com/Community-Access/support).
 
 ### Open source contribution
 
@@ -284,7 +284,7 @@ You have already practiced every step of this workflow. This is the real thing.
 | Git error you have not seen before | Copy the exact error text and search for it. [Pro Git](https://git-scm.com/book/en/v2) and Stack Overflow's [git tag](https://stackoverflow.com/questions/tagged/git) cover nearly every scenario. |
 | VS Code extension not working | Check the extension's page in the marketplace for known issues. Try disabling and re-enabling it. |
 | Want to contribute but do not know where to start | Search for `good first issue` labels on projects that interest you. See [Section 4: Continued Learning Roadmap](#4-continued-learning-roadmap). |
-| Need help from the community | Post in [GitHub Community Accessibility Discussions](https://github.com/orgs/community/discussions/categories/accessibility) or file an issue in the workshop repo. |
+| Need help from the community | Post in [Support Hub Discussions](https://github.com/Community-Access/support/discussions) or file a [support issue](https://github.com/Community-Access/support/issues). |
 
 
 ## 8. Final Words
diff --git a/admin/qa-bundle/docs/appendix-u-discussions-and-gists.md b/admin/qa-bundle/docs/appendix-u-discussions-and-gists.md
index b0e1266e..c74857ce 100644
--- a/admin/qa-bundle/docs/appendix-u-discussions-and-gists.md
+++ b/admin/qa-bundle/docs/appendix-u-discussions-and-gists.md
@@ -18,6 +18,20 @@
 
 > GitHub Discussions is a built-in community forum for repositories and organizations. It's where open-ended conversations live - questions, ideas, announcements, polls, and community Q&A - separate from the action-oriented world of issues and pull requests.
 
+### Support Hub Onboarding (Recommended For Workshop Alumni)
+
+For ongoing support after the workshop, use:
+
+- Support hub home: [Community-Access/support](https://github.com/Community-Access/support)
+- Q&A and community discussion: [Support Hub Discussions](https://github.com/Community-Access/support/discussions)
+- Trackable support requests: [Support Hub Issues](https://github.com/Community-Access/support/issues)
+
+Suggested first steps for students:
+
+1. Read the pinned Start Here resources in Discussions.
+2. Search existing discussions before opening a new support thread.
+3. Use issue templates for setup blockers or accessibility blockers so maintainers can help faster.
+
 ### Learning Cards: GitHub Discussions
 
 
          
diff --git a/admin/qa-bundle/docs/course-guide.md b/admin/qa-bundle/docs/course-guide.md
index 9851c095..5df5e628 100644
--- a/admin/qa-bundle/docs/course-guide.md
+++ b/admin/qa-bundle/docs/course-guide.md
@@ -221,7 +221,7 @@ If you get stuck at any point during the workshop, these resources are always av
 | [Screen Reader Cheat Sheet](appendix-b-screen-reader-cheatsheet.md) | Navigation commands | When you need a screen reader shortcut |
 | [Resources](appendix-x-resources.md) | External links and documentation | When you want to learn more about a topic |
 
-**Still stuck?** Open an issue on this repository describing what you tried, what happened, and what you expected. Include your screen reader and operating system.
+**Still stuck?** Open a support issue at https://github.com/Community-Access/support/issues describing what you tried, what happened, and what you expected. Include your screen reader and operating system.
 
 
 ## Workshop at a Glance
diff --git a/classroom/README.md b/classroom/README.md
index e3644364..26389176 100644
--- a/classroom/README.md
+++ b/classroom/README.md
@@ -386,6 +386,7 @@ Follow the [teardown-checklist.md](teardown-checklist.md) for complete post-work
 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
+4. **Route ongoing learner support** to [Community-Access/support](https://github.com/Community-Access/support)
 
 ---
 
@@ -449,3 +450,4 @@ See [teardown-checklist.md](teardown-checklist.md) for the complete post-worksho
 - [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
+- [Support Hub Operations](../admin/SUPPORT_HUB_OPERATIONS.md) -- operating model for async support after the workshop
diff --git a/docs/00-pre-workshop-setup.md b/docs/00-pre-workshop-setup.md
index 8fc1b569..883a516a 100644
--- a/docs/00-pre-workshop-setup.md
+++ b/docs/00-pre-workshop-setup.md
@@ -1,3 +1,7 @@
+
+**Table: Screen reader options for workshop setup**
+
+**Table: Accessibility improvements for screen reader users**
 # 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.
@@ -10,7 +14,7 @@
 
 > **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.
+> **Please complete this guide at least one day before the workshop.** If you run into any issues, use the support hub at [Community-Access/support](https://github.com/Community-Access/support) 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.
 
@@ -175,7 +179,7 @@ That is it. No tokens to generate, no keys to create, no strings to paste. If yo
 
 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.
+If you run into any authentication issues before the workshop, open a support issue at [Community-Access/support/issues](https://github.com/Community-Access/support/issues) or contact the workshop organizers directly.
 
 ### Learning Cards: Create Your GitHub Account
 
@@ -961,15 +965,15 @@ We are not covering Git commands in this workshop. If you want to learn Git, the
 | 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. |
+| Everything else | File a support issue at [Community-Access/support/issues](https://github.com/Community-Access/support/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
+1. **File a setup support issue** - [Community-Access/support/issues](https://github.com/Community-Access/support/issues) - we will help you get set up
+2. **Join Support Hub Discussions** - [Community-Access/support/discussions](https://github.com/Community-Access/support/discussions) - read pinned Start Here guidance and ask follow-up questions
 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.
diff --git a/docs/21-next-steps.md b/docs/21-next-steps.md
index 185f4faf..739d1e63 100644
--- a/docs/21-next-steps.md
+++ b/docs/21-next-steps.md
@@ -215,7 +215,7 @@ Each course takes 15 to 60 minutes.
 ### Community Access
 
 - [Community Access on GitHub](https://github.com/Community-Access) -- The organization behind this workshop. Watch the repositories for updates.
-- Workshop facilitators are available for questions after the event. Post on the learning-room repository or the git-going-with-github repository.
+- For post-workshop questions, troubleshooting, and alumni conversation, use the open support hub: [Community-Access/support](https://github.com/Community-Access/support).
 
 ### Open source contribution
 
@@ -284,7 +284,7 @@ You have already practiced every step of this workflow. This is the real thing.
 | Git error you have not seen before | Copy the exact error text and search for it. [Pro Git](https://git-scm.com/book/en/v2) and Stack Overflow's [git tag](https://stackoverflow.com/questions/tagged/git) cover nearly every scenario. |
 | VS Code extension not working | Check the extension's page in the marketplace for known issues. Try disabling and re-enabling it. |
 | Want to contribute but do not know where to start | Search for `good first issue` labels on projects that interest you. See [Section 4: Continued Learning Roadmap](#4-continued-learning-roadmap). |
-| Need help from the community | Post in [GitHub Community Accessibility Discussions](https://github.com/orgs/community/discussions/categories/accessibility) or file an issue in the workshop repo. |
+| Need help from the community | Post in [Support Hub Discussions](https://github.com/Community-Access/support/discussions) or file a [support issue](https://github.com/Community-Access/support/issues). |
 
 
 ## 8. Final Words
diff --git a/docs/appendix-u-discussions-and-gists.md b/docs/appendix-u-discussions-and-gists.md
index b0e1266e..c74857ce 100644
--- a/docs/appendix-u-discussions-and-gists.md
+++ b/docs/appendix-u-discussions-and-gists.md
@@ -18,6 +18,20 @@
 
 > GitHub Discussions is a built-in community forum for repositories and organizations. It's where open-ended conversations live - questions, ideas, announcements, polls, and community Q&A - separate from the action-oriented world of issues and pull requests.
 
+### Support Hub Onboarding (Recommended For Workshop Alumni)
+
+For ongoing support after the workshop, use:
+
+- Support hub home: [Community-Access/support](https://github.com/Community-Access/support)
+- Q&A and community discussion: [Support Hub Discussions](https://github.com/Community-Access/support/discussions)
+- Trackable support requests: [Support Hub Issues](https://github.com/Community-Access/support/issues)
+
+Suggested first steps for students:
+
+1. Read the pinned Start Here resources in Discussions.
+2. Search existing discussions before opening a new support thread.
+3. Use issue templates for setup blockers or accessibility blockers so maintainers can help faster.
+
 ### Learning Cards: GitHub Discussions
 
 
          
diff --git a/docs/course-guide.md b/docs/course-guide.md
index 9851c095..5df5e628 100644
--- a/docs/course-guide.md
+++ b/docs/course-guide.md
@@ -221,7 +221,7 @@ If you get stuck at any point during the workshop, these resources are always av
 | [Screen Reader Cheat Sheet](appendix-b-screen-reader-cheatsheet.md) | Navigation commands | When you need a screen reader shortcut |
 | [Resources](appendix-x-resources.md) | External links and documentation | When you want to learn more about a topic |
 
-**Still stuck?** Open an issue on this repository describing what you tried, what happened, and what you expected. Include your screen reader and operating system.
+**Still stuck?** Open a support issue at https://github.com/Community-Access/support/issues describing what you tried, what happened, and what you expected. Include your screen reader and operating system.
 
 
 ## Workshop at a Glance
diff --git a/html/CONTRIBUTING.html b/html/CONTRIBUTING.html
index d7d72434..54bc333a 100644
--- a/html/CONTRIBUTING.html
+++ b/html/CONTRIBUTING.html
@@ -58,7 +58,8 @@
     
   
   
          
-    
          Contributing to This Workshop Repository
          
+    
          Table: Keyboard shortcut for focusing search in different screen readers
          
+
          Contributing to This Workshop Repository
          
 
          Thank you for helping improve this workshop. Whether you are a participant who found a typo, someone who wants to add a new exercise, or an educator adapting these materials for your own community - your contribution is meaningful and welcome.
          
 
          This guide covers contributing to this workshop learning repository. For contributing to Accessibility Agents itself (the project you work on during Day 2), see Accessibility Agents' CONTRIBUTING.md.
          
 
          Table of Contents
          
diff --git a/html/GO-LIVE-QA-GUIDE.html b/html/GO-LIVE-QA-GUIDE.html
index e9bc5c8b..1505d4a2 100644
--- a/html/GO-LIVE-QA-GUIDE.html
+++ b/html/GO-LIVE-QA-GUIDE.html
@@ -60,6 +60,7 @@
   
          
     
          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.
          
+
          For end-to-end execution details, use admin/LEARNING-ROOM-E2E-QA-RUNBOOK.md as the operator procedure. This guide is the release gate summary; the runbook is the required execution playbook.
          
 
          The goal is simple: a facilitator should be able to create a classroom, seed test repositories, complete every challenge path, validate every generated artifact, and know exactly what remains before students arrive.
          
 
          Release Decision
          
 
          Do not mark a cohort ready until all required items in this section are complete.
          
@@ -69,6 +70,14 @@ 
          Release Decision
          
 
        2.  Podcast catalog validation passes.
          3. 
 
        3.  RSS feed validation passes for the current audio state.
          4. 
 
        4.  Git diff whitespace check has no actual whitespace or conflict-marker errors.
          5. 
+
        5.  Registration deployment gate completed (issue form template, workflow enablement, required labels, and optional classroom automation settings).
          6. 
+
        6.  Support Hub is provisioned and publicly accessible at Community-Access/support.
          7. 
+
        7.  Registration confirmation and help pathways route support requests to Support Hub issues/discussions.
          8. 
+
        8.  Registration issue form template and labels are configured (workshop-registration.yml, registration, duplicate, waitlist).
          9. 
+
        9.  Learning Room source has been synced to Community-Access/learning-room-template and merged to main (or validated as no-change).
          10. 
+
        10.  Template smoke validation from Community-Access/learning-room-template succeeded before assignment publishing.
          11. 
+
        11.  Template freshness proof confirms smoke repo content matches latest merged template sync changes.
          12. 
+
        12.  Smoke repo confirms all required workflow files are present (PR validation, content validation, progression, skills progression, and all autograders).
          13. 
 
        13.  Day 1 Classroom assignment has been created from the current Learning Room template.
          14. 
 
        14.  Day 2 Classroom assignment has been created from the current Learning Room template.
          15. 
 
        15.  A test student account accepted the Day 1 invite and received a private repository.
          16. 
@@ -80,8 +89,23 @@ 
          Release Decision
          
 
        16.  Autograding runs and reports results in GitHub Classroom.
          17. 
 
        17.  Peer simulation artifacts can be seeded and used for review practice.
          18. 
 
        18.  Human testers completed the Day 1, Day 2, bonus, accessibility, and content-review passes below.
          19. 
+
        19.  Challenge tracking log includes explicit status and evidence for Challenges 1-16 and Bonus A-E.
          20. 
+
        20.  Challenge reliability matrix includes happy path, failure path, and recovery evidence for each challenge family.
          21. 
+
        21.  Runbook Phase 8 required checklist is complete in admin/LEARNING-ROOM-E2E-QA-RUNBOOK.md.
          22. 
+
        22.  Student recovery Level 2 restore test is completed and evidenced with branch and PR links.
          23. 
+
        23.  All in-scope automation workflows and facilitator scripts were validated with expected behavior and evidence.
          24. 
+
        24.  Local non-podcast readiness evidence is recorded in admin/qa-readiness.
          25. 
 
        25.  All blocking findings have a fix, owner, or written release exception.
          26.
      +

      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.
        • +
      • Support channel links point to deprecated destinations and not to support.
        • +

      Source Of Truth

      The following table lists each release artifact and the document that controls it.

      @@ -100,6 +124,10 @@

      Source Of Truth

      + + + + @@ -112,6 +140,10 @@

      Source Of Truth

      + + + + @@ -154,6 +186,7 @@

      Phase 1: Local Repository Health

    • 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.

      +

      Required evidence destination for local readiness: 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/html/README.html b/html/README.html index e277bbb4..6041f14a 100644 --- a/html/README.html +++ b/html/README.html @@ -85,8 +85,12 @@

        A Workshop by Join the conversation

      - - + + + + + + @@ -167,6 +171,12 @@

      The Journey Arc

      How to Read These Docs

      All documentation lives in the docs/ folder. If you are new, start with Get Going with GitHub. It explains the GitHub Classroom assignment link, your private Learning Room repository, the first challenge issue, how evidence works, and how to choose the tool path that fits you.

      Facilitators preparing a cohort should use the Go-Live QA Guide as the release gate before sharing Classroom invite links.

      +

      Post-Workshop Support

      +

      After the workshop, use the open support repository for questions, troubleshooting, and alumni discussion:

      + +

      Use this repository for curriculum and platform changes only.

      Your Challenges

      16 challenges guide you through the workshop, plus 5 bonus challenges for those who finish early.

      Open the Issues tab of the Learning Room repository and look for challenge issue templates matching each chapter. The Challenge Hub has the full list with instructions, evidence requirements, and links.

      diff --git a/html/REGISTER.html b/html/REGISTER.html index 3ee543db..f19345ea 100644 --- a/html/REGISTER.html +++ b/html/REGISTER.html @@ -59,7 +59,7 @@

      Student Opt-In

      -

      Back to Home | Discussion Forum | Pre-Workshop Setup Guide

      +

      Back to Home | Support Hub | Pre-Workshop Setup Guide

      Join the next GIT Going with GitHub cohort

      This page provides a fast, self-serve opt-in workflow for students.

      admin/classroom/README.md
      End-to-end operator runbook (registration to completion, podcast excluded)admin/LEARNING-ROOM-E2E-QA-RUNBOOK.md
      Human challenge walkthrough classroom/HUMAN_TEST_MATRIX.md
      admin/FACILITATOR_GUIDE.md
      Support hub operationsadmin/SUPPORT_HUB_OPERATIONS.md
      Student challenge hub docs/CHALLENGES.md
      SupportFile an issueSupport hubCommunity-Access/support
      Curriculum issuesFile an issue in this repository
      Dates
      @@ -105,8 +105,8 @@

      Important note

      Registration issues are public because this repository is public.

      Need help?

      A Community Access initiative.

      diff --git a/html/SECURITY.html b/html/SECURITY.html index 3f8e45ce..83bd1f46 100644 --- a/html/SECURITY.html +++ b/html/SECURITY.html @@ -61,6 +61,7 @@

      Security Policy

      Supported Versions

      This repository contains educational curriculum and documentation only - no production software, application servers, or APIs. There are no versioned software releases to patch.

      +

      Table: Supported content types and their source

      diff --git a/html/admin/ANNOUNCEMENT.html b/html/admin/ANNOUNCEMENT.html index 5b29c20f..5922ced9 100644 --- a/html/admin/ANNOUNCEMENT.html +++ b/html/admin/ANNOUNCEMENT.html @@ -59,7 +59,7 @@

      GIT Going with GitHub

      -

      License: CC BY 4.0 | View Site | Full Curriculum | Discussion Forum

      +

      License: CC BY 4.0 | View Site | Full Curriculum | Support Hub

      You Belong in Open Source. Let Us Show You the Door.

      Note: Workshop content is being actively refined before the workshop. Students should expect updates to materials leading up to and during the course.

      @@ -107,7 +107,7 @@

      Student Opt-In page. It feeds directly into our automated registration and waitlist workflow.

      -

      Join the conversation! Have a question before the workshop? Want to connect with other participants? Head to our Discussion Forum - introduce yourself, ask questions, and start building your network before Day 1.

      +

      Join the conversation! Have a question before the workshop? Want to connect with other participants? Head to our Support Hub Discussions - introduce yourself, ask questions, and start building your network before Day 1.

      Already registered? Complete the Pre-Workshop Setup Guide before the workshop. It walks you through every step - GitHub account, screen reader configuration, VS Code, and GitHub Copilot - with instructions for NVDA, JAWS, and VoiceOver. Get set up early so Day 1 starts with learning, not troubleshooting.

      @@ -357,8 +357,8 @@

      Frequently Asked Questions

      No. The workshop, all software, and all materials are free.

      Questions?

      Share This Event

      diff --git a/html/admin/FACILITATOR_GUIDE.html b/html/admin/FACILITATOR_GUIDE.html index bacd16ae..1531bbe6 100644 --- a/html/admin/FACILITATOR_GUIDE.html +++ b/html/admin/FACILITATOR_GUIDE.html @@ -660,7 +660,7 @@

      Next Steps Guidance

      1. Contribute to open source — Find a repo you love and look for 'good first issue'
      2. Use what you learned — GitHub is real infrastructure; keep using it
        3. -
      3. Join our alumni community — [Slack/Discord/channel] — ask questions, share wins
        4. +
      4. Join our alumni community — Community-Access/support — ask questions, share wins
      5. Build something — Use GitHub as your project portfolio"
      @@ -669,7 +669,7 @@

      Share Resources

      Thank You Note

      @@ -725,7 +725,7 @@

      Days 4-7

    • Invite students to alumni community
      • @@ -733,6 +733,7 @@

      Days 4-7

      Weeks 2+

      • Monitor alumni community
          +
        • Watch new issues/discussions in Support Hub and respond within 24 to 48 hours
        • Answer questions
        • Celebrate project shares
        • Offer 1:1 mentorship if interested
          • @@ -764,7 +765,7 @@

          During Workshop

          → Have them try again

          "My internet cut out / I lost the call" → GitHub Classroom doesn't require the call — work continues -→ Post updates in GitHub Discussions or email +→ Post updates in Support Hub Discussions or email → Students can continue async

          For more, see FACILITATOR_CLASSROOM_TROUBLESHOOTING.md

          @@ -808,7 +809,7 @@

          Appendix A: Facilitator

          Keep learning:

          Great work, and keep building!

          diff --git a/html/admin/LEARNING-ROOM-E2E-QA-RUNBOOK.html b/html/admin/LEARNING-ROOM-E2E-QA-RUNBOOK.html new file mode 100644 index 00000000..44e809fe --- /dev/null +++ b/html/admin/LEARNING-ROOM-E2E-QA-RUNBOOK.html @@ -0,0 +1,2233 @@ + + + + + + + Learning Room End-to-End QA Runbook (Registration to Student Completion) - GIT Going with GitHub + + + + + + + + +
          +

          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

          +

          Table: Source files consolidated by this runbook

          +

      + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + +
      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
      Support hub operationsSUPPORT_HUB_OPERATIONS.md
      +

      Table: QA validation checkpoints for registration and classroom automation +Table: Student journey checkpoints and expected artifacts +Table: Label color and purpose for registration automation +Table: Screen reader options for workshop setup +Table: Accessibility improvements for screen reader users

      +

      Required Accounts, Access, and Tools

      +

      Complete this section before Phase 1.

      +
        +
      • Facilitator admin account (accesswatch) with Owner access to both Community-Access and Community-Access-Classroom.
        • +
      • Dedicated non-admin test student account for acceptance and full challenge walkthrough. This must be a separate GitHub account that is not an owner or member of either organization.
        • +
      • Access to classroom.github.com while signed in as accesswatch.
        • +
      • Access to repository settings for Community-Access/git-going-with-github (secrets and variables).
        • +
      • Local clone of this repository with PowerShell available.
        • +
      • GitHub CLI (gh) installed and authenticated as accesswatch for optional verification commands.
        • +
      +

      Critical Precondition Gates (No-Go if any fail)

      +

      Complete all items below before any cohort launch actions.

      +
        +
      • Facilitator account accesswatch can access both organizations:
          +
        • Community-Access (the workshop and code repository organization)
          • +
        • Community-Access-Classroom (the GitHub Classroom organization where student repos are created)
          • +
        +
        • +
      • accesswatch has a verified email address on its GitHub account and can create and edit Classroom assignments at classroom.github.com.
        • +
      • Dedicated non-admin test student account exists and can accept invites.
        • +
      • gh auth status succeeds for accesswatch in local terminal.
        • +
      • Template repository exists and is set as template repo:
          +
        • Community-Access/learning-room-template
          • +
        +
        • +
      • Template repository Actions settings allow required automation behavior:
          +
        • Actions enabled
          • +
        • GITHUB_TOKEN default workflow permissions include write where required
          • +
        • Allow GitHub Actions to create and approve pull requests enabled
          • +
        +
        • +
      • Registration automation settings are correct when using registration-to-classroom handoff:
          +
        • Secret CLASSROOM_ORG_ADMIN_TOKEN is set in Community-Access/git-going-with-github
          • +
        • Variables CLASSROOM_ORG, CLASSROOM_DAY1_ASSIGNMENT_URL, CLASSROOM_DAY2_ASSIGNMENT_URL are set in Community-Access/git-going-with-github
          • +
        +
        • +
      • Registration entry configuration exists and is valid:
          +
        • Issue form template workshop-registration.yml exists
          • +
        • Required labels exist: registration, duplicate, waitlist
          • +
        +
        • +
      • While signed in as accesswatch, opening classroom.github.com shows the Community-Access-Classroom classroom organization.
        • +
      +

      If any precondition fails, stop and resolve before proceeding.

      +

      Exact Setup Steps for Keys, Permissions, Settings, and Template Currency

      +

      Use this section when you need literal setup steps (not only validation checks).

      +

      A. Confirm facilitator account and organization access

      +

      You are performing all steps below as accesswatch. If you are currently signed in to GitHub as a different account, sign out first and sign in as accesswatch before continuing.

      +
        +
      1. Go to github.com and confirm the top-right avatar shows accesswatch.
        2. +
      2. Open the avatar menu, then select Your organizations.
        3. +
      3. Confirm both of the following organizations appear in the list:
          +
        • Community-Access -- the main workshop repository organization
          • +
        • Community-Access-Classroom -- the GitHub Classroom organization where student repos are created
          • +
        • If either is missing, do not proceed. Contact the org owner to ensure accesswatch has Owner-level membership in both.
          • +
        +
        4. +
      4. Click into Community-Access and open the Settings tab. Confirm you can see the full settings sidebar (Members, Actions, Secrets, etc.). If Settings is not visible, accesswatch does not have Owner access and you cannot proceed.
        5. +
      5. Click into Community-Access-Classroom and open its Settings tab. Confirm the same.
        6. +
      6. Optional CLI verification from the local repository root:
        7. +
      +
      gh auth status -h github.com
+gh repo view Community-Access/git-going-with-github
+gh repo view Community-Access/learning-room-template
      +

      Expected output: each gh repo view command should return repository metadata without an error. If you see "Could not resolve to a Repository", accesswatch does not have the required access.

      +

      Why this matters:

      +
        +
      • All downstream setup steps operate against Community-Access/git-going-with-github and Community-Access-Classroom. If the account does not have Owner access to both, secrets, variables, and classroom automation cannot be configured.
        • +
      +

      A.1 Create GitHub Classroom assignments

      +

      Do this before section B. You need both assignment URLs in hand before you can fill in the repository variables.

      +

      You must be signed in to GitHub as accesswatch for the following steps.

      +
        +
      1. Go to classroom.github.com.
        2. +
      2. You will see a list of classrooms. Select the classroom named for this cohort that is linked to the Community-Access-Classroom organization. The organization name appears below the classroom name on the card.
          +
        • If no classroom exists yet, select New classroom, then choose Community-Access-Classroom as the organization. Name the classroom using the format Git Going - [Cohort Name] - [Month Year] (for example, Git Going - May 2026).
          • +
        +
        3. +
      3. Inside the classroom, select New assignment.
        4. +
      4. Create the Day 1 assignment:
          +
        • Title: You Belong Here
          • +
        • Individual or group: Individual
          • +
        • Repository visibility: Private
          • +
        • Template repository: Community-Access/learning-room-template (search for it by name in the template field)
          • +
        • Grant students admin access: No
          • +
        • Enable feedback pull requests: Yes
          • +
        • Paste the Day 1 assignment description from classroom/assignment-day1-you-belong-here.md
          • +
        • Add autograding from admin/classroom/autograding-setup.md -- Day 1 requires exactly 4 tests totaling 50 points
          • +
        • Select Create assignment
          • +
        +
        5. +
      5. After saving, the assignment page shows an invite link at the top labeled something like Invite link. It will be in the format https://classroom.github.com/a/<short-code>. Copy this full URL and paste it somewhere safe (for example, a scratch notepad). This is your CLASSROOM_DAY1_ASSIGNMENT_URL.
        6. +
      6. Repeat for the Day 2 assignment:
          +
        • Title: You Can Build This
          • +
        • Same base settings as Day 1
          • +
        • Paste description from classroom/assignment-day2-you-can-build-this.md
          • +
        • Add Day 2 autograding: exactly 6 tests totaling 75 points
          • +
        • Copy the resulting invite URL. This is your CLASSROOM_DAY2_ASSIGNMENT_URL.
          • +
        +
        7. +
      7. Keep both URLs available. You will paste them into repository variables in section B step 4.
        8. +
      +

      Why this matters:

      +
        +
      • The repository variables CLASSROOM_DAY1_ASSIGNMENT_URL and CLASSROOM_DAY2_ASSIGNMENT_URL cannot be filled in until the assignments exist and their invite URLs are known. The short code in the URL is unique to each assignment and is not predictable in advance.
        • +
      +

      B. Configure registration automation key and variables

      +

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

      +

      You must be signed in as accesswatch for all steps in this section.

      +

      Step B.1 -- Generate the personal access token (PAT)

      +

      The CLASSROOM_ORG_ADMIN_TOKEN secret must be a GitHub personal access token generated by accesswatch (or another Owner-level account for Community-Access-Classroom). This token is what allows the registration workflow to invite students to the Community-Access-Classroom organization automatically.

      +
        +
      1. While signed in as accesswatch, go to github.com/settings/tokens.
        2. +
      2. Select Generate new token, then select Generate new token (classic).
          +
        • Do not use fine-grained tokens for this purpose. The admin:org scope is only available on classic tokens.
          • +
        +
        3. +
      3. In the Note field enter a descriptive name such as Community-Access registration automation.
        4. +
      4. In the Expiration field, set a date that covers your cohort timeline plus a buffer (for example, 90 days).
        5. +
      5. Under Select scopes, check admin:org. This is the only scope required. It gives the token permission to list and create organization invitations for Community-Access-Classroom.
        6. +
      6. Scroll to the bottom and select Generate token.
        7. +
      7. GitHub will display the token exactly once immediately after generation. It begins with ghp_. Copy it now and paste it somewhere safe (a local scratch notepad, not a repository file). You will not be able to view it again.
        8. +
      8. Do not close the token page until you have completed section B.2 and confirmed the secret was saved.
        9. +
      +

      Step B.2 -- Add the token as a repository secret

      +
        +
      1. Go to github.com/Community-Access/git-going-with-github/settings/secrets/actions.
        2. +
      2. Select New repository secret.
        3. +
      3. In the Name field, enter exactly: CLASSROOM_ORG_ADMIN_TOKEN
          +
        • Capitalization and underscores must match exactly.
          • +
        +
        4. +
      4. In the Secret field, paste the token you copied in step B.1.
        5. +
      5. Select Add secret.
        6. +
      6. Re-open the secret entry and confirm the name shows CLASSROOM_ORG_ADMIN_TOKEN. GitHub does not display the value again, but confirming the name is correct is sufficient.
        7. +
      +

      Step B.3 -- Add the repository variables

      +
        +
      1. At the same settings page, select the Variables tab (next to Secrets).
        2. +

      2. Select New repository variable for each of the following. Add them one at a time.

        +

        Variable 1:

        +
          +
        • Name: CLASSROOM_ORG
          • +
        • Value: Community-Access-Classroom
          • +
        • This is the exact GitHub organization name where students are invited. The capitalization and hyphens must match exactly.
          • +
        +

        Variable 2:

        +
          +
        • Name: CLASSROOM_DAY1_ASSIGNMENT_URL
          • +
        • Value: paste the Day 1 invite URL you copied in section A.1 step 5 (format: https://classroom.github.com/a/<short-code>)
          • +
        +

        Variable 3:

        +
          +
        • Name: CLASSROOM_DAY2_ASSIGNMENT_URL
          • +
        • Value: paste the Day 2 invite URL you copied in section A.1 step 6 (format: https://classroom.github.com/a/<short-code>)
          • +
        +
        3. +

      3. After adding all three, re-open each variable entry and confirm:

        +
          +
        • The name is exactly as listed above (no typos, no extra characters).
          • +
        • The value has no leading or trailing spaces. Paste into a plain text editor first if you are unsure, and trim whitespace before re-pasting.
          • +
        +
        4. +
      4. Run one registration test and confirm welcome comment contains assignment links.
        5. +
      +

      Why this matters:

      +
        +
      • These values drive invite and assignment-link injection in registration responses. A single typo in the org name or a trailing space in a variable value will silently break automation without a clear error message.
        • +
      +

      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.

      +

      The fastest path is Initialize-WorkshopSetup.ps1, which sets the secret, all three variables, verifies labels, and runs template prep in a single command. See the setup script section below.

      +

      Using the setup script (recommended):

      +
      scripts/classroom/Initialize-WorkshopSetup.ps1 -AdminPAT ghp_yourTokenHere
      +

      The script will:

      +
        +
      • Prompt you if the PAT is missing or invalid
        • +
      • Resolve Day 1 and Day 2 assignment URLs automatically from the GitHub Classroom API (if assignments exist in the GIT Going with Github classroom)
        • +
      • Set CLASSROOM_ORG_ADMIN_TOKEN secret and all three variables in Community-Access/git-going-with-github
        • +
      • Verify all three required labels exist, creating any that are missing
        • +
      • Confirm read-back values have no leading or trailing spaces
        • +
      • Run Prepare-LearningRoomTemplate.ps1 and Test-LearningRoomTemplate.ps1 unless skipped
        • +
      +

      If running manually instead:

      +
        +
      1. Generate a classic PAT with admin:org scope at github.com/settings/tokens (see section B of the setup steps above for exact steps).
        2. +
      2. Go to github.com/Community-Access/git-going-with-github/settings/secrets/actions.
        3. +
      3. Create secret CLASSROOM_ORG_ADMIN_TOKEN with the PAT value.
        4. +
      4. On the Variables tab, create:
          +
        • CLASSROOM_ORG = Community-Access-Classroom
          • +
        • CLASSROOM_DAY1_ASSIGNMENT_URL = invite URL from assignment A.1 step 5
          • +
        • CLASSROOM_DAY2_ASSIGNMENT_URL = invite URL from assignment A.1 step 6
          • +
        +
        5. +
      5. Re-open each value and verify no leading or trailing spaces.
        6. +
      +

      Pass criteria:

      +
        +
      • Secret and variables are present with correct values.
        • +
      • Initialize-WorkshopSetup.ps1 reported no failures, or manual verification confirms all values.
        • +
      • Configuration aligns with REGISTRATION-ADMIN.md.
        • +
      +

      Step 0.3 Registration deployment smoke check

      +

      Goal: validate the deployed registration system and site are working before manual QA begins.

      +

      Use Test-RegistrationPage.ps1 to run this check. The script validates the Pages site, the REGISTER page, the issue form template, required labels, and workflow state. With -RunLiveTest it also submits a real test registration issue, waits for the workflow, and verifies the welcome comment.

      +

      Static checks only (site, config, labels, workflow state):

      +
      scripts/classroom/Test-RegistrationPage.ps1
      +

      Full live end-to-end test including issue submission:

      +
      scripts/classroom/Test-RegistrationPage.ps1 -RunLiveTest
      +

      What the script checks:

      +
        +
      1. HTTP GET to https://community-access.org/git-going-with-github/ returns 200.
        2. +
      2. HTTP GET to https://community-access.org/git-going-with-github/REGISTER returns 200 and contains expected content.
        3. +
      3. workshop-registration.yml exists in .github/ISSUE_TEMPLATE/.
        4. +
      4. Labels registration, duplicate, and waitlist exist.
        5. +
      5. registration.yml workflow is active and has a recent successful run.
        6. +
      6. (Live test only) Test issue is submitted, workflow completes, welcome comment posts with assignment links, registration label is applied.
        7. +
      +

      Cleanup limitation: the test issue is closed and locked by the script. It cannot be deleted via the GitHub API. If deletion is needed, a repository admin must delete it manually from the Issues tab after this run.

      +

      Pass criteria:

      +
        +
      • Test-RegistrationPage.ps1 exits with no failures.
        • +
      • Live test (if run) confirms workflow executes end to end.
        • +
      • Output comment and 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.
        • +
      • Support links point to Community-Access/support issues/discussions.
        • +
      +

      Step 1.1 Verify support hub onboarding path

      +
        +
      1. Open Community-Access/support and confirm Issues and Discussions are enabled.
        2. +
      2. Confirm at least one pinned onboarding discussion or Start Here guidance exists.
        3. +
      3. Open a test support issue using a template and confirm labels apply correctly.
        4. +
      +

      Pass criteria:

      +
        +
      • Support hub is reachable and public.
        • +
      • Onboarding path is discoverable for students.
        • +
      • Template-driven support issue flow works.
        • +
      +

      Step 2. Configure registration automation for classroom handoff

      +

      If Initialize-WorkshopSetup.ps1 was run successfully in Phase 0, this step is already complete. Re-verify with:

      +
      gh secret list -R Community-Access/git-going-with-github
+gh variable list -R Community-Access/git-going-with-github
      +

      Expected output: CLASSROOM_ORG_ADMIN_TOKEN appears in secrets, and CLASSROOM_ORG, CLASSROOM_DAY1_ASSIGNMENT_URL, CLASSROOM_DAY2_ASSIGNMENT_URL appear in variables.

      +

      If any are missing, run Initialize-WorkshopSetup.ps1 again or follow the manual steps in section B of the setup instructions. For full reference, see REGISTRATION-QUICKSTART.md and REGISTRATION-ADMIN.md.

      +

      Pass criteria:

      +
        +
      • CLASSROOM_ORG_ADMIN_TOKEN secret is present.
        • +
      • All 3 variables are present with correct values and no leading or trailing spaces.
        • +
      +

      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

      +

      GitHub Classroom assignment creation has no write API. All classroom creation and assignment setup must be done through the browser at classroom.github.com while signed in as accesswatch.

      +

      Note: a classroom already exists for this repository (GIT Going with Github, classroom id 322783, linked to Community-Access-Classroom). Unless starting a completely new classroom, skip classroom creation and go directly to assignment creation in Steps 11 and 12.

      +

      If you do need a new classroom:

      +
        +
      1. Go to classroom.github.com as accesswatch.
        2. +
      2. Select New classroom and choose Community-Access-Classroom as the organization.
        3. +
      3. Name it Git Going - [Cohort Name] - [Month Year] (for example, Git Going - May 2026).
        4. +
      4. Import roster from classroom/roster-template.csv on the Roster tab.
        5. +
      5. Add accesswatch-student to the roster as the test student.
        6. +
      +

      To verify the existing classroom is accessible:

      +
      gh api /classrooms --jq '.[] | {id, name, url}'
      +

      Pass criteria:

      +
        +
      • Classroom exists in Community-Access-Classroom and is accessible to accesswatch.
        • +
      • Roster includes accesswatch-student (or the designated test student username).
        • +
      +

      Step 11. Create Day 1 assignment exactly

      +

      See section A.1 of the setup steps above for full navigation instructions.

      +

      Use classroom/assignment-day1-you-belong-here.md and admin/classroom/day1-assignment-copy-paste.md for the exact title, description, and autograding entries.

      +

      To check if the Day 1 assignment already exists:

      +
      gh api /classrooms/322783/assignments --jq '.[] | {id, title, invite_link}'
      +

      If the assignment exists and its invite_link is already in the CLASSROOM_DAY1_ASSIGNMENT_URL variable, skip to Step 12.

      +

      If creating from scratch:

      +
        +
      1. Go to classroom.github.com as accesswatch and open the GIT Going with Github classroom.
        2. +
      2. Select New assignment.
        3. +
      3. Title: You Belong Here (exact match required)
        4. +
      4. Type: Individual, Visibility: Private
        5. +
      5. Template: Community-Access/learning-room-template
        6. +
      6. Grant students admin access: No
        7. +
      7. Enable feedback pull requests: Yes
        8. +
      8. Paste description from classroom/assignment-day1-you-belong-here.md
        9. +
      9. Add autograding from admin/classroom/autograding-setup.md -- Day 1 requires exactly 4 tests totaling 50 points
        10. +
      10. Save and copy the invite URL from the assignment page
        11. +
      11. If Initialize-WorkshopSetup.ps1 has not been run yet, paste the URL into CLASSROOM_DAY1_ASSIGNMENT_URL. If it has been run, re-run it to pick up the new URL automatically.
        12. +
      +

      Pass criteria:

      +
        +
      • Day 1 assignment exists with title You Belong Here.
        • +
      • Test count is 4, total points is 50.
        • +
      • Feedback pull request is enabled.
        • +
      • CLASSROOM_DAY1_ASSIGNMENT_URL variable matches the assignment invite link.
        • +
      +

      Step 12. Create Day 2 assignment exactly

      +

      Same process as Step 11. Check first whether it already exists:

      +
      gh api /classrooms/322783/assignments --jq '.[] | {id, title, invite_link}'
      +

      If the assignment exists and its invite_link is already in CLASSROOM_DAY2_ASSIGNMENT_URL, skip ahead.

      +

      If creating from scratch:

      +
        +
      1. In the GIT Going with Github classroom, select New assignment.
        2. +
      2. Title: You Can Build This (exact match required)
        3. +
      3. Apply same base settings as Day 1 (individual, private, no admin access, feedback PR enabled)
        4. +
      4. Template: Community-Access/learning-room-template
        5. +
      5. Paste description from classroom/assignment-day2-you-can-build-this.md
        6. +
      6. Add Day 2 autograding from admin/classroom/autograding-setup.md -- 6 tests totaling 75 points
        7. +
      7. Save and copy the invite URL
        8. +
      8. Update CLASSROOM_DAY2_ASSIGNMENT_URL or re-run Initialize-WorkshopSetup.ps1 to pick it up automatically
        9. +
      +

      Pass criteria:

      +
        +
      • Day 2 assignment exists with title You Can Build This.
        • +
      • Test count is 6, total points is 75.
        • +
      • Feedback pull request is enabled.
        • +
      • CLASSROOM_DAY2_ASSIGNMENT_URL variable matches the assignment invite link.
        • +
      +

      Step 13. Connect assignment URLs back to registration automation

      +

      If Initialize-WorkshopSetup.ps1 was run after the assignments were created, the variables are already set. Verify with:

      +
      gh variable list -R Community-Access/git-going-with-github
      +

      If either URL variable is missing or stale, re-run the setup script. It will resolve URLs directly from the Classroom API:

      +
      scripts/classroom/Initialize-WorkshopSetup.ps1 -AdminPAT ghp_yourTokenHere -SkipTemplatePrepare -SkipTemplateValidate
      +

      Then re-run the registration live test to confirm both URLs appear in the welcome comment:

      +
      scripts/classroom/Test-RegistrationPage.ps1 -RunLiveTest
      +

      Pass criteria:

      +
        +
      • CLASSROOM_DAY1_ASSIGNMENT_URL and CLASSROOM_DAY2_ASSIGNMENT_URL are set and match assignment invite links.
        • +
      • Registration confirmation comment includes both assignment URLs.
        • +
      • Test-RegistrationPage.ps1 -RunLiveTest exits with no failures.
        • +
      +

      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

      +

      The test student account is accesswatch-student. GitHub Classroom generates repository names from the assignment slug and the student username. For the default assignment titles, the repository names will be:

      +
        +
      • Day 1: Community-Access-Classroom/you-belong-here-accesswatch-student
        • +
      • Day 2: Community-Access-Classroom/you-can-build-this-accesswatch-student
        • +
      +

      Confirm the exact repository names first:

      +
      gh repo list Community-Access-Classroom --json name --jq '.[].name' | Select-String accesswatch-student
      +

      Then seed (replace repository slugs with the confirmed names if different):

      +
      $day1 = 'Community-Access-Classroom/you-belong-here-accesswatch-student'
+$day2 = 'Community-Access-Classroom/you-can-build-this-accesswatch-student'
+
+scripts/classroom/Seed-LearningRoomChallenge.ps1 -Repository $day1 -Challenge 1 -Assignee accesswatch-student
+scripts/classroom/Seed-PeerSimulation.ps1 -Repository $day1 -StudentUsername accesswatch-student
+scripts/classroom/Seed-LearningRoomChallenge.ps1 -Repository $day2 -Challenge 10 -Assignee accesswatch-student
+scripts/classroom/Seed-PeerSimulation.ps1 -Repository $day2 -StudentUsername accesswatch-student
      +

      Alternatively, if Initialize-WorkshopSetup.ps1 is run after accesswatch-student has accepted both invites, it will detect the repos and seed them automatically.

      +

      Pass criteria:

      +
        +
      • Challenge 1 issue appears in Day 1 repo assigned to accesswatch-student.
        • +
      • Challenge 10 issue appears in Day 2 repo assigned to accesswatch-student.
        • +
      • 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.

      +

      Script Reference

      +

      The following scripts in scripts/classroom/ are used by this runbook. Run each with -? or read the .SYNOPSIS block for full parameter documentation.

      + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + +
      ScriptPurposeAutomated
      Initialize-WorkshopSetup.ps1Set PAT secret, variables, labels; sync and validate template; seed test student challengesAll steps except PAT generation (browser required)
      Archive-CohortData.ps1Export cohort issues, roster, and discussions to git-going-student-success; reset source repoExport and archive are automated; roster reset may require PR due branch rules
      Delete-RegistrationIssues.ps1Delete registration/duplicate/waitlist issues via GraphQL mutationFully automated when user has repo admin and repo token scope
      Delete-RegistrationIssues-v2.jsExperimental Playwright UI deleter for issue cleanupPartially automated; UI selector fragility makes this fallback-only
      Test-RegistrationPage.ps1Validate Pages site, REGISTER page, issue form, labels, workflow, and live registration flowAll steps; test issue cleanup is close+lock only (see below)
      Prepare-LearningRoomTemplate.ps1Sync learning-room/ source into Community-Access/learning-room-templateFully automated
      Test-LearningRoomTemplate.ps1Create smoke repo from template, validate file inventory and workflow dispatchFully automated
      Seed-LearningRoomChallenge.ps1Seed a specific challenge issue in a student repositoryFully automated
      Seed-PeerSimulation.ps1Seed peer simulation issues and PR in a student repositoryFully automated
      Restore-LearningRoomFiles.ps1Restore baseline files into a student repo via recovery branch and PRFully automated
      Invoke-LearningRoomEndToEndTest.ps1Full end-to-end scripted QA harnessFully automated
      Reset-SupportHubEnvironment.ps1Rebuild support hub repository labels, settings, and baseline support automationFully automated
      +

      GitHub API Limitations

      +

      The following actions cannot be performed via any GitHub API and require manual browser-based action. These are hard platform constraints, not gaps in the scripts.

      + + + + + + + + + + + + + + + + + + + + + + + + + + + + +
      ActionWhy it cannot be automatedManual path
      Creating a Classroom assignmentNo write endpoint exists in the GitHub Classroom REST API (confirmed: only GET endpoints are documented and available)classroom.github.com as accesswatch
      Deleting issues via REST APIGitHub REST API has no DELETE endpoint for issuesUse scripts/classroom/Delete-RegistrationIssues.ps1 (GraphQL mutation path), or UI fallback
      Deleting or moving discussionsGraphQL discussion mutations do not include delete or move operationsDiscussions tab in GitHub UI -> each thread -> "..." -> Delete
      Generating a personal access tokenPAT generation requires browser authentication by designgithub.com/settings/tokens as accesswatch
      +

      Pre-Cohort Cleanup Procedure

      +

      Run this procedure after each cohort completes, before starting QA for the next cohort.

      +

      Archive previous cohort data

      +
      # Replace the slug with the cohort being archived (format: YYYY-MM-description)
+scripts/classroom/Archive-CohortData.ps1 -CohortSlug 2026-03-march-cohort
      +

      What this does:

      +
        +
      1. Exports all registration/duplicate/waitlist issues (with comments) to JSON and CSV.
        2. +
      2. Exports the current student-roster.json.
        3. +
      3. Exports discussions to JSON.
        4. +
      4. Pushes the archive to Community-Access/git-going-student-success under admin/cohorts/<CohortSlug>/.
        5. +
      5. Closes and locks all registration issues in the source repository.
        6. +
      6. Resets student-roster.json to the blank template.
        7. +
      +

      Use -WhatIf to preview without making changes:

      +
      scripts/classroom/Archive-CohortData.ps1 -CohortSlug 2026-03-march-cohort -WhatIf
      +

      After the script completes, two manual cleanup steps are required (API limitation):

      +
        +
      1. Delete registration issues -- use the GraphQL cleanup script (recommended):
        2. +
      +
      scripts/classroom/Delete-RegistrationIssues.ps1
      +
        +
      1. Delete discussions -- discussions still require manual deletion: +https://github.com/Community-Access/git-going-with-github/discussions
        2. +
      +

      Archive destination: https://github.com/Community-Access/git-going-student-success/tree/main/admin/cohorts/<CohortSlug>/

      +

      Current Progress Snapshot (2026-05-08)

      +
        +
      • Registration issues archived to git-going-student-success.
        • +
      • Registration issues deleted from source repository (count now 0).
        • +
      • Discussions deleted from source repository (count now 0).
        • +
      • Learning Room template sync PR merged: Community-Access/learning-room-template#11.
        • +
      • Registration secret and variable values set for next cohort (CLASSROOM_ORG_ADMIN_TOKEN, CLASSROOM_ORG, CLASSROOM_DAY1_ASSIGNMENT_URL, CLASSROOM_DAY2_ASSIGNMENT_URL).
        • +
      • Day 1 and Day 2 classroom assignments created for next cohort.
        • +
      + + + + + + diff --git a/html/admin/PODCASTS.html b/html/admin/PODCASTS.html index 905ef215..0aab79b4 100644 --- a/html/admin/PODCASTS.html +++ b/html/admin/PODCASTS.html @@ -60,22 +60,27 @@

      Podcasts

      Git Going with GitHub - Audio Series

      -

      Listen to companion audio episodes for every chapter and appendix in this workshop. Each episode is a standalone teaching conversation between hosts Alex and Jamie, written so learners can understand the concepts even before opening the chapter. Every episode includes a full transcript below the player.

      +

      Listen to the workshop as one end-to-end path. Companion lessons, Challenge Coach episodes, and reference material are interleaved so learners can hear the concept, practice it, and then keep moving through the course. Every episode includes a full transcript below the player.

      Subscribe: Add the podcast RSS feed to your preferred podcast app - Apple Podcasts, Spotify, Overcast, or any RSS reader.

      Transcripts: Every episode includes a complete, readable transcript. Expand the "Read Transcript" section below any episode to follow along or search the conversation.

      How to Use These Episodes

        -
      • Before a chapter: Listen to build the mental model before diving into the exercises.
        • -
      • After a chapter: Listen to reinforce the concepts and catch anything you missed.
        • -
      • On the go: Episodes are 8-18 minutes each. Listen during commutes, walks, or breaks.
        • +
      • Follow the path: Listen in order when you want the full workshop experience.
        • +
      • Practice in place: Challenge Coach episodes appear near the chapters that prepare you for that task.
        • +
      • Use references when needed: Appendix and reference episodes are placed near the moments where they help most.
      -

      Day 1: GitHub Foundations

      -

      Episode 0: Welcome to Git Going with GitHub

      +

      Start Here

      +

      1. Episode 0: Welcome to Git Going with GitHub

      A tour of the workshop structure, the two-day arc, and what you will accomplish.

      Based on: Course Guide

      -

      Audio and transcript are being regenerated for this episode.

      + + +

      Download Episode 0 (MP3)

      Read Transcript - Episode 0: Welcome to Git Going with GitHub @@ -114,7 +119,7 @@

      Transcript

      Alex: Hold that next to this. Here is the plain-English version of Exercises at a Glance. The workshop includes structured exercises across the curriculum. Put another way, every exercise is designed to be completed in 1-5 minutes, is impossible to fail, and follows the same pattern: Try It - You're done when - What success feels like.

      Jamie: What do you want them to do when the plan breaks?

      -

      Alex: This is where Getting Help becomes real: if you get stuck at any point during the workshop, these resources are always available. That matters in practice: Open an issue on this repository describing what you tried, what happened, and what you expected.

      +

      Alex: This is where Getting Help becomes real: if you get stuck at any point during the workshop, these resources are always available. That matters in practice: Use the support hub at https://github.com/Community-Access/support and open a support issue describing what you tried, what happened, and what you expected.

      Alex: That connects to another useful point. Keep the learner anchored in Workshop at a Glance. Start with Chapter 00: Pre-Workshop Setup. A good GitHub workflow is like a well-run meeting: everyone knows the topic, the next action, and who has the floor.

      Jamie: What is the one idea that makes the next few steps less mysterious?

      Alex: The reason What This Guide Does matters is that this workshop is designed so you are never left guessing what comes next. That gives the learner a simple foothold: the goal is to build confidence one checkable step at a time.

      @@ -159,10 +164,204 @@

      Transcript

      -

      Episode 1: Pre-Workshop Setup

      +

      2. Episode 18: Glossary of Terms

      +

      Comprehensive glossary: Git, GitHub, open source, and accessibility terminology.

      +

      Based on: Appendix A: Glossary of Terms

      +

      Audio and transcript are being regenerated for this episode.

      +
      +Read Transcript - Episode 18: Glossary of Terms + +

      Transcript

      +

      Alex: This is Git Going with GitHub, episode 18: Glossary of Terms. I am Alex. By the end of this episode, Glossary of Terms should feel less like a wall of GitHub words and more like a set of moves you can trust.

      +

      Jamie: And I am Jamie. I am here for the practical questions: what should I listen for, what can go wrong, and what is the next calm move?

      +
      +

      Alex: Today we are working on this: Comprehensive glossary: Git, GitHub, open source, and accessibility terminology. I want the learner to leave with a mental map, not just a remembered path through buttons.

      +

      Jamie: So the goal is understanding first, then action, then confirmation.

      +

      Alex: Right. We are building a rhythm: orient yourself, take one intentional action, then verify what changed before moving on.

      +
      +

      Jamie: Okay, set the room for us. What are we walking into?

      +

      Alex: Start with Every Term You Need for Open Source Contribution: This glossary is your reference for the entire two-day workshop. The next useful detail is this: When you hear a term you don't recognize - check here first.

      +

      Alex: The next layer is this. Start with Learning Cards: Navigating the Glossary. There is something to understand, something to try, and something that proves the try worked.

      +

      Alex: The practical anchors are these. Press H to jump between term headings (h3 level) within each category section. Use the Elements List (NVDA+F7 or Insert+F6) to see all terms at once and type a few letters to filter. Jump to "Alphabetical Quick Reference" at the bottom for a flat A-Z lookup table. Each term is a bold h3 heading -- increase zoom and scan headings to browse terms quickly. The alphabetical table at the bottom works well at high zoom since each row is self-contained. Use Ctrl+F in your browser to search for any term by name.

      +

      Jamie: What is the one idea that makes the next few steps less mysterious?

      +

      Alex: This is where Repository (Repo) becomes real: a repository is the container for an entire project. That matters in practice: It holds all the project's files, folders, documentation, and the complete history of every change ever made.

      +
      +

      Alex: Now bring the learner back to the room. Keep the learner anchored in Organization (Org). An organization is a group account on GitHub that multiple people can belong to. This is the part to say slowly: Open source projects typically live inside an organization rather than under a personal account.

      +

      Jamie: What would you say to someone who is already bracing for this to be too much?

      +

      Alex: The reason Fork matters is that a fork is a personal copy of someone else's repository, living in your own GitHub account. That gives the learner a simple foothold: when you fork a repo, you get all its files and history.

      +

      Alex: The useful habit is simple: orient first, act second, verify third. That pause before acting is part of the work.

      +

      Alex: That matters because of the next idea. Start with Remote: A remote is a connection to a repository hosted elsewhere (usually on GitHub). The next useful detail is this: Your local Git repository can have multiple remotes. Think of it like entering a new building: first you find the lobby, then the room, then the door you actually need.

      +

      Alex: On the ground, that means a few things. origin - your fork on GitHub. upstream - the original repository you forked from.

      +
      +

      Jamie: What is the safe way to learn from that example?

      +

      Alex: Start with To see your remotes. There is something to understand, something to try, and something that proves the try worked.

      +

      Alex: Treat examples as spoken recipes, not decorations. You may hear something like git remote -v. Read the command, understand what it changes, then run it only when the repository state matches the lesson.

      +

      Jamie: What should happen before anyone copies and runs it?

      +

      Alex: Start with To add a remote. There is something to understand, something to try, and something that proves the try worked.

      +

      Alex: Treat examples as spoken recipes, not decorations. You may hear something like git remote add upstream https://github.com/original-owner/repo.git. Read the command, understand what it changes, then run it only when the repository state matches the lesson.

      +

      Jamie: Where do you want a learner to place their attention here?

      +

      Alex: Keep the learner anchored in Origin. origin is the default name Git gives to the remote repository you cloned from. This is the part to say slowly: When you clone your fork, origin points to your fork on GitHub.

      +
      +

      Alex: Before the learner moves on. The reason.gitignore matters is that.gitignore is a special file in the root of your repository that tells Git which files or folders to ignore - meaning Git will not track or commit them. The interface gets friendlier when it stops being a wall of controls and starts being a set of named places.

      +

      Jamie: Give me the version that sounds like an instructor, not a manual.

      +

      Alex: Start with Why use.gitignore? There is something to understand, something to try, and something that proves the try worked.

      +

      Alex: A few details make that real. Prevent committing temporary files (.DS Store, Thumbs.db). Ignore build outputs (dist/, build/, node modules/). Keep secrets out of Git (.env files, API keys, credentials). Avoid committing IDE-specific files (.vscode/,.idea/).

      +

      Jamie: What should they understand before typing anything?

      +

      Alex: Here is the plain-English version of Example.gitignore.gitignore only ignores untracked files. Put another way, if you already committed a file, you must remove it from Git's tracking first.

      +

      Alex: Treat examples as spoken recipes, not decorations. You may hear something like git rm --cached filename. Read the command, understand what it changes, then run it only when the repository state matches the lesson.

      +
      +

      Jamie: How do you keep commands from becoming magic words?

      +

      Alex: This is where Clone becomes real: cloning copies a repository from GitHub to your local computer so you can work with it in VS Code or your preferred editor. That matters in practice: When you clone, you get all the files and the complete history.

      +

      Alex: Treat examples as spoken recipes, not decorations. You may hear something like git clone https://github.com/your-username/repo-name.git. Read the command, understand what it changes, then run it only when the repository state matches the lesson.

      +

      Alex: That connects to another useful point. Keep the learner anchored in Branch. A branch is a separate line of development inside a repository. This is the part to say slowly: The main branch (often called main or master) holds the stable, released version of the project. A good GitHub workflow is like a well-run meeting: everyone knows the topic, the next action, and who has the floor.

      +

      Alex: A solid Git habit is to know which branch you are on, what changed, and what confirmation you expect before you run the next command.

      +

      Jamie: If I am listening before the workshop starts, what should settle in my mind first?

      +

      Alex: Start with Common branch names. There is something to understand, something to try, and something that proves the try worked.

      +

      Alex: The parts worth keeping in working memory are these. main - the primary, stable branch. develop - integration branch (not all projects have this). feature/my-new-thing - convention for feature branches. fix/broken-button - convention for bug fix branches. docs/update-readme - convention for documentation-only branches.

      +
      +

      Jamie: Let's pause on Commit. What should a learner take away from it?

      +

      Alex: Start with Commit: A commit is a saved snapshot of your changes at a moment in time. The next useful detail is this: Good commit messages are in the imperative mood: "Fix typo in README" not "Fixed typo" or "Fixing typo.".

      +

      Alex: Here is what that changes in practice. A message describing what changed and why. A unique SHA hash (a fingerprint like a1b2c3d). The author and timestamp. The changes (additions and deletions to files).

      +

      Alex: Treat examples as spoken recipes, not decorations. You may hear something like Fix broken link in accessibility guide; The link to the NVDA download page was using an outdated URL.; Updated to the current direct download page.; Fixes 42. Read the command, understand what it changes, then run it only when the repository state matches the lesson.

      +

      Jamie: Let's pause on Diff. What should a learner take away from it?

      +

      Alex: Here is the plain-English version of Diff. A diff (short for difference) shows what changed between two versions of a file. Put another way, lines that were added are shown in green (with a + prefix).

      +

      Alex: A solid pull request habit is to separate three questions: what changed, why it changed, and what still needs review. That keeps the conversation useful instead of noisy.

      +

      Alex: Keep the thread going. This is where Issue becomes real: an issue is a discussion item in a GitHub repository. That matters in practice: Every issue gets a sequential number (like 42) and can have labels, assignees, milestones, and comments. The workshop is closer to rehearsal than lecture. You hear the move, try the move, and then check what changed.

      +

      Alex: The room should hear these as checkpoints. Reporting bugs. Requesting features or improvements. Asking questions. Discussing ideas.

      +

      Alex: A solid issue habit is to read the title, the body, and the timeline before acting. You are listening for the requested action, the missing evidence, and the person who needs a response.

      +
      +

      Jamie: Let's pause on Pull Request (PR). What should a learner take away from it?

      +

      Alex: Keep the learner anchored in Pull Request (PR). A pull request is a proposal to merge changes from one branch into another. This is the part to say slowly: When you have finished working on your fork or feature branch, you open a PR to say "here is my work - please review it and consider merging it.".

      +

      Alex: These are the details that keep the idea from floating away. Which branch you want to merge into which target branch. The diff (all changes you made). A description of what you changed and why. Discussion threads and reviews from others.

      +

      Alex: Another way to ground it. The reason Code Review matters is that code review is the process of one or more collaborators reading and providing feedback on a PR before it is merged. That gives the learner a simple foothold: good code reviews are kind, specific, and constructive.

      +

      Alex: That becomes easier when you listen for these cues. Comment - leave a note on a line (not a formal verdict). Approve - signal that they are happy with the changes. Request Changes - indicate that specific things need to be addressed before merging.

      +

      Jamie: Let's pause on Merge. What should a learner take away from it?

      +

      Alex: Start with Merge: Merging is combining changes from one branch into another. The next useful detail is this: When a PR is approved, a maintainer merges it.

      +
      +

      Alex: This is the part worth saying out loud. Here is the plain-English version of Merge Conflict. A merge conflict happens when two branches have both changed the same part of the same file in different ways. Put another way, Git doesn't know which version to keep, so it pauses and asks you to resolve it manually. It is like learning a transit route. The names of the stops matter because they tell you whether you are still going the right direction.

      +

      Jamie: Let's pause on Upstream. What should a learner take away from it?

      +

      Alex: This is where Upstream becomes real: upstream refers to the original repository that you forked from. That matters in practice: When the upstream project has new changes that you want to bring into your fork, you "sync" your fork with upstream.

      +

      Alex: Here is the practical turn. Keep the learner anchored in Label. Labels are colored tags applied to issues and PRs to categorize them.

      +

      Alex: For a learner, the useful signals are these. bug - something isn't working. enhancement - new feature or request. documentation - documentation-only change. good first issue - good for newcomers (look for this when finding your first contribution!). help wanted - maintainers want community help. accessibility - accessibility-related.

      +

      Alex: A solid project habit is to treat metadata as decision support. Labels, status, assignees, and notifications tell you what kind of attention the work needs.

      +
      +

      Jamie: Let's pause on Milestone. What should a learner take away from it?

      +

      Alex: The reason Milestone matters is that a milestone groups issues and PRs toward a goal or deadline. That gives the learner a simple foothold: for example: "v2.0 Release" or "Hackathon Day 1." Milestones show progress as a percentage of closed versus open items.

      +

      Alex: This is where the talk moves from concept to action. Start with Project (GitHub Projects): A GitHub Project is a flexible board for tracking work. The next useful detail is this: It can show issues and PRs in table view, board view (kanban), or roadmap view. Think of it like entering a new building: first you find the lobby, then the room, then the door you actually need.

      +

      Jamie: Let's pause on Maintainer. What should a learner take away from it?

      +

      Alex: Here is the plain-English version of Maintainer. A maintainer is someone with write or admin access to a repository. Put another way, maintainers review PRs, triage issues, manage releases, and make decisions about the project's direction.

      +
      +

      Alex: Hold that next to this. This is where Contributor becomes real: anyone who contributes to an open source project is a contributor. That matters in practice: Contributing includes code, documentation, design, testing, translation, issue triage, and community support.

      +

      Jamie: Let's pause on Triage. What should a learner take away from it?

      +

      Alex: Keep the learner anchored in Triage. Triaging issues means reviewing new issues to categorize them, add labels, assign them, close duplicates, and communicate with the reporter. This is the part to say slowly: Triage is an important contribution that doesn't require coding skills.

      +

      Alex: Keep the teaching thread moving. The reason Collaborator matters is that a collaborator is someone who has been explicitly granted write access to a repository. That gives the learner a simple foothold: collaborators can commit directly to the repo without forking (though good practice is still to use branches and PRs). The interface gets friendlier when it stops being a wall of controls and starts being a set of named places.

      +
      +

      Jamie: Let's pause on Part 4: Common Abbreviations and Slang. What should a learner take away from it?

      +

      Alex: Start with Common Abbreviations and Slang: These abbreviations appear frequently in GitHub comments, PR descriptions, and commit messages.

      +

      Jamie: Let's pause on HEAD. What should a learner take away from it?

      +

      Alex: Here is the plain-English version of HEAD. HEAD is Git's way of saying "where you are right now." It's a pointer to the current commit on the current branch. Put another way, you'll see HEAD referenced in commands like.

      +

      Alex: That shows up in the workshop in a few specific ways. When you're on main, HEAD points to the latest commit on main. When you switch branches, HEAD moves to that branch. HEAD^ or HEAD 1 means "the commit before HEAD".

      +

      Alex: Treat examples as spoken recipes, not decorations. You may hear something like git reset HEAD 1 Undo the last commit; git diff HEAD Show uncommitted changes. Read the command, understand what it changes, then run it only when the repository state matches the lesson.

      +

      Jamie: Let's pause on Detached HEAD. What should a learner take away from it?

      +

      Alex: This is where Detached HEAD becomes real: a "detached HEAD" occurs when you check out a specific commit instead of a branch. That matters in practice: You're no longer "on" a branch - just looking at a snapshot in time.

      +
      +

      Jamie: Let's pause on Why it happens. What should a learner take away from it?

      +

      Alex: Start with Why it happens. There is something to understand, something to try, and something that proves the try worked.

      +

      Alex: Treat examples as spoken recipes, not decorations. You may hear something like git checkout a1b2c3d Checking out a commit directly. Read the command, understand what it changes, then run it only when the repository state matches the lesson.

      +

      Jamie: Let's pause on What this means. What should a learner take away from it?

      +

      Alex: Start with What this means. There is something to understand, something to try, and something that proves the try worked.

      +

      Alex: The practical takeaway is this. Any commits you make won't belong to any branch. If you switch branches, those commits become "orphaned".

      +

      Jamie: Let's pause on How to fix it. What should a learner take away from it?

      +

      Alex: Start with How to fix it: If you made commits in detached HEAD state and want to keep them. The next useful detail is this: Git will warn you verbosely when entering detached HEAD state.

      +

      Alex: Treat examples as spoken recipes, not decorations. You may hear something like git branch new-branch-name Creates a branch from your current position; git checkout new-branch-name. Read the command, understand what it changes, then run it only when the repository state matches the lesson.

      +
      +

      Jamie: Let's pause on Stash. What should a learner take away from it?

      +

      Alex: Here is the plain-English version of Stash. git stash temporarily saves your uncommitted changes and reverts your working directory to a clean state. Put another way, it's useful when you need to switch branches but aren't ready to commit.

      +

      Jamie: Let's pause on Common workflow. What should a learner take away from it?

      +

      Alex: Start with Common workflow. There is something to understand, something to try, and something that proves the try worked.

      +

      Alex: Treat examples as spoken recipes, not decorations. You may hear something like You're working on branch A; git stash Save your changes temporarily; git checkout main Switch to main; Do something on main.; git checkout branch-a Switch back; git stash pop Restore your changes. Read the command, understand what it changes, then run it only when the repository state matches the lesson.

      +

      Jamie: What stays the same when the tool changes?

      +

      Alex: Keep the learner anchored in Stash commands. Use case: "I need to quickly switch branches to check something, but I'm in the middle of work I'm not ready to commit.".

      +

      Alex: The practical takeaway is this. git stash - save changes. git stash list - see what's stashed. git stash pop - restore and remove from stash. git stash apply - restore but keep in stash. git stash drop - delete a stash.

      +
      +

      Alex: Keep the teaching thread moving. The reason Rebase matters is that rebasing is an alternative to merging. That gives the learner a simple foothold: instead of creating a merge commit, rebase moves (replays) your commits on top of another branch.

      +

      Jamie: Let's pause on When to use rebase. What should a learner take away from it?

      +

      Alex: Start with When to use rebase. There is something to understand, something to try, and something that proves the try worked.

      +

      Alex: The practical takeaway is this. Keep a linear project history. Clean up your branch before submitting a PR. Incorporate upstream changes into your feature branch.

      +

      Alex: Keep the teaching thread moving. Start with When NOT to rebase. There is something to understand, something to try, and something that proves the try worked.

      +

      Alex: The practical takeaway is this. Shared branches (never rebase main or public branches). After pushing to GitHub (unless you're comfortable force pushing).

      +
      +

      Jamie: Let's pause on Basic rebase workflow. What should a learner take away from it?

      +

      Alex: This is where Basic rebase workflow becomes real: rebase conflicts are resolved the same way as merge conflicts (edit file, remove markers, git add, git rebase --continue).

      +

      Alex: Treat examples as spoken recipes, not decorations. You may hear something like git checkout feature-branch; git rebase main; Fix any conflicts; git push --force-with-lease See Force Push below. Read the command, understand what it changes, then run it only when the repository state matches the lesson.

      +

      Jamie: Let's pause on Cherry-Pick. What should a learner take away from it?

      +

      Alex: Keep the learner anchored in Cherry-Pick. Cherry-picking applies a single commit from one branch onto another. This is the part to say slowly: Use case: You made a bug fix on the wrong branch and want to apply it to main without merging the whole branch.

      +

      Alex: Treat examples as spoken recipes, not decorations. You may hear something like git checkout main; git cherry-pick a1b2c3d Apply commit a1b2c3d to main. Read the command, understand what it changes, then run it only when the repository state matches the lesson.

      +

      Jamie: Let's pause on When to use. What should a learner take away from it?

      +

      Alex: The reason When to use matters is that warning: Cherry-picking duplicates commits (creates a new commit with the same changes). That gives the learner a simple foothold: avoid cherry-picking commits that are part of an active feature branch - it causes confusion.

      +

      Alex: The practical takeaway is this. Extract a single fix from a larger feature branch. Backport a bug fix to an older release branch. Undo a commit on one branch but keep it on another.

      +
      +

      Jamie: Let's pause on Fetch vs Pull. What should a learner take away from it?

      +

      Alex: Start with Fetch vs Pull: git fetch downloads changes from a remote repository but doesn't merge them into your current branch. The next useful detail is this: It updates your local copy of remote branches (like origin/main or upstream/main) without touching your working files. Think of it like entering a new building: first you find the lobby, then the room, then the door you actually need.

      +

      Alex: Treat examples as spoken recipes, not decorations. You may hear something like git fetch origin Download updates from origin. git pull origin main Fetch + merge origin/main into current branch. Read the command, understand what it changes, then run it only when the repository state matches the lesson.

      +

      Jamie: Let's pause on When to use fetch. What should a learner take away from it?

      +

      Alex: Start with When to use fetch. There is something to understand, something to try, and something that proves the try worked.

      +

      Alex: The practical takeaway is this. You want to see what changed without committing to merging. You want to review changes before integrating them. You're syncing upstream and want to inspect first.

      +

      Alex: Keep the teaching thread moving. This is where When to use pull becomes real: best practice for collaboration: Use fetch first, review with git log origin/main, then decide to merge or rebase.

      +

      Alex: The practical takeaway is this. You know you want the latest changes merged immediately. You're working alone on a branch.

      +
      +

      Jamie: Let's pause on Force Push. What should a learner take away from it?

      +

      Alex: Keep the learner anchored in Force Push. Force pushing (git push --force or git push -f) overwrites the remote branch with your local version, replacing its history. This is the part to say slowly: This is dangerous because it can delete commits that others have based work on.

      +

      Alex: Keep the teaching thread moving. Start with When force push is okay. There is something to understand, something to try, and something that proves the try worked.

      +

      Alex: The practical takeaway is this. Your own feature branch that no one else is working on. After rebasing to clean up history before merging a PR.

      +

      Jamie: Let's pause on When force push is NEVER okay. What should a learner take away from it?

      +

      Alex: Start with When force push is NEVER okay. There is something to understand, something to try, and something that proves the try worked.

      +

      Alex: The practical takeaway is this. The main branch. Shared branches where others have based work on your commits. Public branches with collaborators.

      +
      +

      Jamie: Let's pause on Safer alternative: --force-with-lease. What should a learner take away from it?

      +

      Alex: Here is the plain-English version of Safer alternative: --force-with-lease. --force-with-lease only force pushes if no one else has pushed to the remote branch since you last fetched. Put another way, if someone pushed changes, the command fails and warns you.

      +

      Alex: Treat examples as spoken recipes, not decorations. You may hear something like git push --force-with-lease origin feature-branch. Read the command, understand what it changes, then run it only when the repository state matches the lesson.

      +

      Jamie: Let's pause on Why force push is needed after rebase. What should a learner take away from it?

      +

      Alex: This is where Why force push is needed after rebase becomes real: when you rebase, Git rewrites commit history. That matters in practice: The remote branch and your local branch now have conflicting histories.

      +

      Alex: Keep the teaching thread moving. Keep the learner anchored in SHA / Hash. Every commit, file, and tree in Git is identified by a SHA hash - a 40-character string of letters and numbers (e.g., a1b2c3d4e5f6.). This is the part to say slowly: the learner will see shortened versions like a1b2c3d in the GitHub UI. A good GitHub workflow is like a well-run meeting: everyone knows the topic, the next action, and who has the floor.

      +
      +

      Jamie: Let's pause on Tag / Release. What should a learner take away from it?

      +

      Alex: The reason Tag / Release matters is that a tag marks a specific commit as significant - usually a version release like v1.0.0. That gives the learner a simple foothold: tags are permanent references (unlike branches, which move with each new commit).

      +

      Alex: Keep the teaching thread moving. Start with Actions / Workflow / CI/CD: GitHub Actions is an automation platform built into GitHub. The next useful detail is this: Workflows are automated scripts (written in YAML) that run in response to events - like a PR being opened or code being pushed.

      +

      Jamie: Let's pause on Status Check. What should a learner take away from it?

      +

      Alex: Here is the plain-English version of Status Check. A status check is the result of an automated test or workflow run on a PR. Put another way, maintainers often require status checks to pass before merging.

      +

      Alex: The practical takeaway is this. Green checkmark - all checks passed. Red X - one or more checks failed. Yellow dot - checks are still running.

      +
      +

      Alex: Keep the teaching thread moving. This is where Webhook becomes real: a webhook is an automated notification that GitHub sends to another service when something happens (a push, a PR opened, etc.). That matters in practice: Webhooks power integrations with tools like Slack, project management systems, and CI services. The workshop is closer to rehearsal than lecture. You hear the move, try the move, and then check what changed.

      +

      Jamie: Let's pause on GitHub Discussions. What should a learner take away from it?

      +

      Alex: Keep the learner anchored in GitHub Discussions. Discussions are a threaded forum built into GitHub, separate from Issues. This is the part to say slowly: They are used for open-ended conversation, Q&A, and community announcements.

      +

      Alex: Keep the teaching thread moving. The reason Profile matters is that your GitHub profile is your public identity. That gives the learner a simple foothold: it shows your name, bio, location, repositories, contribution activity (the green squares), and pinned projects.

      +
      +

      Jamie: Let's pause on GitHub Copilot. What should a learner take away from it?

      +

      Alex: Start with GitHub Copilot: GitHub Copilot is an AI-powered coding assistant. The next useful detail is this: It suggests code, documentation, and commit messages.

      +

      Alex: Keep the teaching thread moving. Here is the plain-English version of Community Files. Every healthy open source project has these files in the root of the repository. It is like learning a transit route. The names of the stops matter because they tell you whether you are still going the right direction.

      +

      Jamie: Let's pause on Learning Cards: Alphabetical Quick Reference. What should a learner take away from it?

      +

      Alex: Start with Learning Cards: Alphabetical Quick Reference. There is something to understand, something to try, and something that proves the try worked.

      +

      Alex: The practical takeaway is this. Press T to jump to the table, then use Ctrl+Alt+Arrow keys to navigate rows and columns. Each row has two cells: Term and Definition -- column headers are announced on first entry. For longer definitions, the table keeps them concise; see the full entry above for details. This table is designed for quick lookups -- each row fits on a single line at most zoom levels. If the table wraps awkwardly, try reducing zoom slightly or switching to a wider window. Bold term names in the left column create a visible scan line.

      +
      +

      Alex: Keep the teaching thread moving. Keep the learner anchored in Alphabetical Quick Reference. Next: Appendix B: Screen Reader Cheat Sheet Teaching chapter: Chapter 02: Understanding GitHub.

      +
      +

      Jamie: What should people carry with them after this?

      +

      Alex: Carry the map. Know what page or tool you are in, know which action you are taking, and know what confirmation should follow. If the confirmation is missing, pause. That pause is not wasted time; it is professional judgment.

      +

      Jamie: That is a better way to say it than just follow the steps.

      +

      Alex: Right. Steps matter, but understanding wins. That is episode 18. Next in the series is episode 19, where we keep building the same contributor muscles.

      +
      + +
      +

      3. Episode 1: Pre-Workshop Setup

      Creating your GitHub account, installing Git and VS Code, configuring your screen reader.

      Based on: Chapter 0: Pre-Workshop Setup

      -

      Audio and transcript are being regenerated for this episode.

      + + +

      Download Episode 1 (MP3)

      Read Transcript - Episode 1: Pre-Workshop Setup @@ -426,7 +625,7 @@

      Transcript

      Alex: The practical takeaway is this. Git Handbook. Pro Git book (free). GitHub Skills: Introduction to GitHub.

      Jamie: Let's pause on Getting Help Before the Event. What should a learner take away from it?

      Alex: Start with Getting Help Before the Event: If you cannot complete any step in this guide before the workshop. The next useful detail is this: Every setup issue we can solve before Day 1 means more time for learning on the day.

      -

      Alex: First, file an issue - community-access/git-going-with-github - we will help you get set up. Then, file an issue in this repository - describe exactly what step you are on and what is not working. After that, join the GitHub Accessibility Discussions - GitHub Community Accessibility Discussions - the community is helpful and welcoming. Think of it as a rail line: each stop confirms you are still on the right route before the next one.

      +

      Alex: First, open a setup support issue in Community-Access/support/issues so maintainers can triage quickly. Then, join Community-Access/support/discussions and read the pinned Start Here guidance before posting follow-up questions. After that, if you need broader platform input, join GitHub Community Accessibility Discussions. Think of it as a rail line: each stop confirms you are still on the right route before the next one.

      Jamie: What should people carry with them after this?

      Alex: Carry the map. Know what page or tool you are in, know which action you are taking, and know what confirmation should follow. If the confirmation is missing, pause. That pause is not wasted time; it is professional judgment.

      @@ -435,55 +634,190 @@

      Transcript

      -

      Episode 2: Understanding GitHub on the Web

      -

      How GitHub organizes its web pages, heading structure, landmarks, and keyboard shortcuts.

      -

      Based on: Chapter 2: Understanding GitHub on the Web

      +

      4. Episode 44: Choose Your Tools

      +

      A guided tour of browser GitHub, github.dev, VS Code, GitHub Desktop, and the CLI.

      +

      Based on: Chapter 1: Choose Your Tools

      Audio and transcript are being regenerated for this episode.

      -Read Transcript - Episode 2: Understanding GitHub on the Web +Read Transcript - Episode 44: Choose Your Tools

      Transcript

      -

      Alex: This is Git Going with GitHub, episode 2: Understanding GitHub on the Web. I am Alex. By the end of this episode, Understanding GitHub on the Web should feel less like a wall of GitHub words and more like a set of moves you can trust.

      -

      Jamie: And I am Jamie. I am here for the practical questions: what should I listen for, what can go wrong, and what is the next calm move?

      +

      Alex: Welcome to Git Going with GitHub, episode 44: Choose Your Tools. I am Alex. Today we are going to make Choose Your Tools something you can explain, practice, and recover from when the interface surprises you.

      +

      Jamie: And I am Jamie. I will be the voice of the learner who is willing to ask, what is this for, where am I, and how do I know I did it right?

      -

      Alex: Today we are working on this: How GitHub organizes its web pages, heading structure, landmarks, and keyboard shortcuts. I want the learner to leave with a mental map, not just a remembered path through buttons.

      -

      Jamie: So the goal is understanding first, then action, then confirmation.

      -

      Alex: Right. We are building a rhythm: orient yourself, take one intentional action, then verify what changed before moving on.

      +

      Alex: The big idea today: A guided tour of browser GitHub, github.dev, VS Code, GitHub Desktop, and the CLI. We will name the concept, explain why it matters, practice the move, and point out the checks that tell you the work is real.

      +

      Jamie: So the episode should work even if someone has not read the chapter yet.

      +

      Alex: Exactly. The transcript has to stand on its own. It can point toward practice, but it should teach the concept right here in the conversation.

      Jamie: Okay, set the room for us. What are we walking into?

      -

      Alex: Start with How GitHub Is Organized, and How to Orient Yourself on Every Page: Read this before navigating GitHub for the first time. The next useful detail is this: the lesson is the mental model that makes every subsequent guide easier.

      -

      Alex: The next layer is this. Here is the plain-English version of 1. GitHub's Three-Level Structure. GitHub is not a single page or a single kind of page. Put another way, it is three nested levels, and understanding which level you are on changes how you navigate. It is like learning a transit route. The names of the stops matter because they tell you whether you are still going the right direction.

      -

      Jamie: What is the one idea that makes the next few steps less mysterious?

      -

      Alex: This is where 2. What Is Always on Every GitHub Page becomes real: no matter where you navigate on GitHub, the same global navigation bar is at the top of every page. That matters in practice: Understanding its landmark structure means you always have a fixed orientation point.

      +

      Alex: Start with 1. Why This Matters: There is no single "right" way to use GitHub. The next useful detail is this: Some switch between all of them depending on the task.

      +

      Alex: The next layer is this. Here is the plain-English version of 2. The Five Paths. The following table summarizes all five environments at a glance. Put another way, read through the summaries first, then explore the sections that interest you. It is like learning a transit route. The names of the stops matter because they tell you whether you are still going the right direction.

      +

      Jamie: What stays the same when the tool changes?

      +

      Alex: This is where 3. Path 1: GitHub.com (Browser) becomes real: what it is: The GitHub website at github.com. That matters in practice: Every repository, issue, pull request, and setting lives here.

      -

      Alex: Now bring the learner back to the room. Keep the learner anchored in The Global Navigation Bar (always present). Visually, the top bar contains (left to right). This is the part to say slowly: Screen reader landmark: All of these live inside the landmark labeled "Navigation Menu".

      -

      Alex: A solid pull request habit is to separate three questions: what changed, why it changed, and what still needs review. That keeps the conversation useful instead of noisy.

      +

      Alex: Now bring the learner back to the room. Start with What you can do here. There is something to understand, something to try, and something that proves the try worked.

      +

      Alex: For a learner, the useful signals are these. 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.

      Jamie: What would you say to someone who is already bracing for this to be too much?

      -

      Alex: The reason Secondary navigation (repository pages only) matters is that when you are inside a repository, a second navigation bar appears below the global bar. That gives the learner a simple foothold: this contains the repository's tabs: Code, Issues, Pull requests, Actions, Projects, Wiki, Security, Insights, and Settings.

      -

      Alex: A solid navigation habit is to prove where you are before activating controls. Headings, landmarks, and the address bar are not trivia; they are your map.

      -

      Alex: That matters because of the next idea. Start with Learning Cards: What Is Always on Every GitHub Page. There is something to understand, something to try, and something that proves the try worked.

      -

      Alex: On the ground, that means a few things. 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. 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.

      +

      Alex: Start with What you cannot do here. There is something to understand, something to try, and something that proves the try worked.

      +

      Alex: The parts worth keeping in working memory are these. Run code or tests locally. Use a full-featured code editor with extensions. Make offline changes.

      Alex: The useful habit is simple: orient first, act second, verify third. That pause before acting is part of the work.

      +

      Alex: That matters because of the next idea. Start with Screen reader experience: GitHub.com has strong screen reader support. The next useful detail is this: Every page uses ARIA landmarks, headings follow a consistent hierarchy, and keyboard shortcuts are available for most actions. Think of it like entering a new building: first you find the lobby, then the room, then the door you actually need.

      +

      Alex: A solid navigation habit is to prove where you are before activating controls. Headings, landmarks, and the address bar are not trivia; they are your map.

      -

      Jamie: If I am listening before the workshop starts, what should settle in my mind first?

      -

      Alex: Here is the plain-English version of 3. How to Tell Where You Are. Three signals tell you exactly where you are on GitHub, without needing to see the visual layout.

      -

      Alex: This is where the talk moves from concept to action. This is where Signal 1: The URL becomes real: GitHub URLs are readable descriptions of your location. That matters in practice: Your browser's address bar is always reachable with Alt+D (Windows) or Cmd+L (Mac).

      -

      Jamie: What stays the same when the tool changes?

      -

      Alex: Keep the learner anchored in Signal 2: The browser tab title. GitHub formats page titles consistently.

      +

      Jamie: How would you walk the room through that step by step?

      +

      Alex: Here is the plain-English version of Low vision experience. GitHub supports light and dark themes, high contrast themes, and responds to your operating system's contrast preferences. Put another way, GitHub's layout adapts to browser zoom up to 400% without horizontal scrolling on most pages.

      +

      Alex: First, go to github.com/settings/appearance. Then, choose from Light, Dark, Light high contrast, or Dark high contrast. After that, or select "Sync with system" to follow your OS setting. Treat it like a recipe: do not add the next ingredient until the previous one is actually in the bowl.

      +

      Alex: This is where the talk moves from concept to action. Start with Learning Cards: GitHub.com (Browser). There is something to understand, something to try, and something that proves the try worked.

      +

      Alex: The room should hear these as checkpoints. 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. 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.

      +

      Jamie: What is the common workflow underneath the different interfaces?

      +

      Alex: Keep the learner anchored in 4. Path 2: github.dev (Browser-Based Editor). What it is: A VS Code editor that runs entirely in your browser. This is the part to say slowly: Open any repository by pressing the.

      -

      Alex: Before the learner moves on. The reason Signal 3: The first H1 heading matters is that press 1 (in Browse Mode) on any GitHub page to jump to the first H1 heading. That gives the learner a simple foothold: what you hear tells you what type of page you are on. The interface gets friendlier when it stops being a wall of controls and starts being a set of named places.

      +

      Alex: Before the learner moves on. Start with What you can do here. There is something to understand, something to try, and something that proves the try worked.

      +

      Alex: That becomes easier when you listen for these cues. 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.

      Jamie: Give me the version that sounds like an instructor, not a manual.

      -

      Alex: Start with Page Type 1: Repository Home (Code Tab): This is the central hub of any project. The next useful detail is this: It is where you find the file tree, the README, branch information, and links to all other parts of the repository.

      -

      Alex: Hold that next to this. Start with What to expect. There is something to understand, something to try, and something that proves the try worked.

      -

      Alex: The practical anchors are these. 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.

      -
      -

      Jamie: Where do you want a learner to place their attention here?

      -

      Alex: This is where Page Type 2: Issues List becomes real: a searchable, filterable list of all issues in the repository.

      -

      Alex: A solid issue habit is to read the title, the body, and the timeline before acting. You are listening for the requested action, the missing evidence, and the person who needs a response.

      -

      Alex: That connects to another useful point. Start with What to expect. There is something to understand, something to try, and something that proves the try worked.

      -

      Alex: For a learner, the useful signals are these. 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".

      -

      Jamie: Let's pause on Page Type 3: Issue Detail. What should a learner take away from it?

      -

      Alex: The reason Page Type 3: Issue Detail matters is that the full view of a single issue: the original report, all comments, labels, assignees, and the timeline.

      +

      Alex: A few details make that real. 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.

      +

      Alex: Hold that next to this. Here is the plain-English version of Screen reader experience. github.dev is VS Code running in the browser, so the same keyboard navigation and screen reader support applies. Put another way, the command palette (Ctrl+Shift+P or Cmd+Shift+P) is available, and all editor keybindings work.

      +
      +

      Jamie: If I am listening before the workshop starts, what should settle in my mind first?

      +

      Alex: This is where When to use github.dev over GitHub.com becomes real: 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. That matters in practice: For single-file edits, the pencil icon on GitHub.com is simpler.

      +

      Alex: That connects to another useful point. Keep the learner anchored in 5. Path 3: VS Code (Desktop). What it is: Visual Studio Code is a free desktop code editor from Microsoft. This is the part to say slowly: It has built-in Git support, an integrated terminal, thousands of extensions, and GitHub Copilot included. A good GitHub workflow is like a well-run meeting: everyone knows the topic, the next action, and who has the floor.

      +

      Jamie: What is the one idea that makes the next few steps less mysterious?

      +

      Alex: Start with What you can do here. There is something to understand, something to try, and something that proves the try worked.

      +

      Alex: On the ground, that means a few things. 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).

      +
      +

      Alex: Here is the practical turn. Start with What you cannot do here (without extensions). There is something to understand, something to try, and something that proves the try worked.

      +

      Alex: Here is what that changes in practice. Manage GitHub issues and pull requests directly (install the GitHub Pull Requests extension for this). View repository insights or settings (use GitHub.com for that).

      +

      Jamie: Where do you want a learner to place their attention here?

      +

      Alex: Here is the plain-English version of Screen reader experience. VS Code has a dedicated accessibility mode that activates automatically when a screen reader is detected. Put another way, deep dive: Chapter 11 covers the VS Code interface in detail.

      +

      Alex: These are the details that keep the idea from floating away. 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.

      +

      Alex: Keep the thread going. This is where Low vision experience becomes real: VS Code supports high contrast themes, custom zoom levels (Ctrl+= to zoom in, Ctrl+- to zoom out), and configurable font sizes. That matters in practice: 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. The workshop is closer to rehearsal than lecture. You hear the move, try the move, and then check what changed.

      +
      +

      Jamie: There are a lot of tools in play. How do we keep that from feeling like a contest?

      +

      Alex: Start with Learning Cards: VS Code (Desktop). There is something to understand, something to try, and something that proves the try worked.

      +

      Alex: The practical anchors are these. 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. 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.

      +

      Alex: Another way to ground it. The reason 6. Path 4: GitHub Desktop matters is that what it is: A desktop application that provides a graphical interface for Git operations. That gives the learner a simple foothold: instead of typing git commit in a terminal, you use buttons, lists, and visual diffs.

      +

      Jamie: Let's pause on What you can do here. What should a learner take away from it?

      +

      Alex: That shows up in the workshop in a few specific ways. 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).

      +
      +

      Alex: This is the part worth saying out loud. Start with What you cannot do here. There is something to understand, something to try, and something that proves the try worked.

      +

      Alex: The practical takeaway is this. 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.

      +

      Jamie: Let's pause on Screen reader experience. What should a learner take away from it?

      +

      Alex: This is where Screen reader experience becomes real: GitHub Desktop uses Electron and provides basic screen reader support. That matters in practice: Branch switching, commit history, and file lists are navigable.

      +

      Alex: Keep the teaching thread moving. Keep the learner anchored in 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. This is the part to say slowly: It is a good stepping stone between the GitHub.com web editor and the full VS Code workflow.

      +
      +

      Jamie: Let's pause on 7. Path 5: GitHub CLI. What should a learner take away from it?

      +

      Alex: The reason 7. Path 5: GitHub CLI matters is that what it is: A command-line tool called gh that brings GitHub features to your terminal. That gives the learner a simple foothold: it handles authentication, issue management, pull request workflows, and repository operations -- directly from the command line.

      +

      Alex: Keep the teaching thread moving. Start with What you can do here. There is something to understand, something to try, and something that proves the try worked.

      +

      Alex: The practical takeaway is this. 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.

      +

      Jamie: Let's pause on What you cannot do here. What should a learner take away from it?

      +

      Alex: The practical takeaway is this. 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).

      +
      +

      Alex: Keep the teaching thread moving. This is where Screen reader experience becomes real: the GitHub CLI is a text-based tool running in a terminal. That matters in practice: Screen reader users read its output directly as plain text -- no landmarks, headings, or ARIA to worry about.

      +

      Jamie: Let's pause on When to choose GitHub CLI. What should a learner take away from it?

      +

      Alex: Keep the learner anchored in When to choose GitHub CLI. Choose the CLI if you are comfortable in a terminal and want fast, scriptable access to GitHub features. This is the part to say slowly: It pairs well with VS Code's integrated terminal, giving you the best of both worlds.

      +

      Alex: Keep the teaching thread moving. Start with Learning Cards: GitHub CLI. There is something to understand, something to try, and something that proves the try worked.

      +

      Alex: The practical takeaway is this. 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. 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.

      +
      +

      Jamie: What is the pre-flight check here?

      +

      Alex: Start with 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.

      +

      Alex: Keep the teaching thread moving. Here is the plain-English version of Day 2 recommendation. On Day 2, you work with Git locally. Put another way, most students add VS Code (Path 3) at this point.

      +

      Jamie: Let's pause on Switching paths is normal. What should a learner take away from it?

      +

      Alex: This is where Switching paths is normal becomes real: the learner will likely use more than one tool during the workshop. That matters in practice: The workshop chapters always tell you which tool to use for each step.

      +

      Alex: The practical takeaway is this. 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.

      +
      +

      Alex: Keep the teaching thread moving. Start with Learning Cards: Which Path Should I Start With? There is something to understand, something to try, and something that proves the try worked.

      +

      Alex: The practical takeaway is this. 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. 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.

      +

      Jamie: What should the learner prove to themselves after each small task?

      +

      Alex: The reason 9. Your First Confidence Exercise matters is that this exercise takes approximately five minutes. That gives the learner a simple foothold: it verifies your tool is working and builds your confidence before Day 1 begins.

      +

      Alex: Keep the teaching thread moving. Start with The task: Open the public workshop curriculum repository and find the README file.

      +
      +

      Jamie: What does the learner do first, second, and then after that?

      +

      Alex: Start with Path 1: GitHub.com. There is something to understand, something to try, and something that proves the try worked.

      +

      Alex: First, go to github.com/Community-Access/git-going-with-github. Then, the README is displayed below the file list on the repository's home page. After that, screen reader users: press H to navigate headings. The README's first heading announces the repository name. Finally, you are done when you can read the first paragraph of the README. Treat it like a recipe: do not add the next ingredient until the previous one is actually in the bowl.

      +

      Jamie: Turn that into a path someone can follow.

      +

      Alex: Start with Path 2: github.dev. There is something to understand, something to try, and something that proves the try worked.

      +

      Alex: First, go to github.dev/Community-Access/git-going-with-github. Then, the file explorer opens on the left. Press Ctrl+Shift+E (or Cmd+Shift+E) to focus it. After that, navigate to README.md and press Enter to open it in a tab. Finally, you are done when the file content appears in the editor. It is a checklist, but a meaningful one: every item creates evidence that the next step is safe.

      +

      Jamie: What is the ordered workflow?

      +

      Alex: Start with Path 3: VS Code (if set up). There is something to understand, something to try, and something that proves the try worked.

      +

      Alex: First, open VS Code. Then, open the command palette: Ctrl+Shift+P (or Cmd+Shift+P). After that, type "Git: Clone" and press Enter. Finally, paste the URL: https://github.com/Community-Access/git-going-with-github.git. It is like walking a hallway with named doors: read the sign, enter the right room, then confirm where you landed.

      +

      Jamie: Give me the sequence, because order matters here.

      +

      Alex: First, choose a folder to clone into and wait for the download. Then, when it finishes, VS Code offers to open the repository. Accept. After that, open the file explorer (Ctrl+Shift+E) and select README.md. Finally, you are done when the file content appears in the editor. The rhythm is simple: orient, act, verify, then continue.

      +
      +

      Jamie: Let's pause on Path 4: GitHub Desktop. What should a learner take away from it?

      +

      Alex: Start with Path 4: GitHub Desktop. There is something to understand, something to try, and something that proves the try worked.

      +

      Alex: First, open GitHub Desktop. Then, go to File, then Clone repository (or press Ctrl+Shift+O). After that, paste the URL: https://github.com/Community-Access/git-going-with-github.git. Finally, choose a local path and click Clone. The rhythm is simple: orient, act, verify, then continue.

      +

      Jamie: Before we leave Path 4: GitHub Desktop, what is the practical point?

      +

      Alex: First, once cloned, the repository appears in GitHub Desktop. Click "Open in Visual Studio Code" (or your preferred editor) to read the README. Think of it as a rail line: each stop confirms you are still on the right route before the next one.

      +

      Jamie: Let's pause on Path 5: GitHub CLI. What should a learner take away from it?

      +

      Alex: Start with Path 5: GitHub CLI. There is something to understand, something to try, and something that proves the try worked.

      +

      Alex: First, open your terminal. Then, open the README in your preferred way. After that, you are done when you can read the first paragraph. Think of it as a rail line: each stop confirms you are still on the right route before the next one.

      +

      Alex: Treat examples as spoken recipes, not decorations. You may hear something like gh repo clone Community-Access/git-going-with-github; cd learning-room. cat README.md print to terminal; code README.md open in VS Code. Read the command, understand what it changes, then run it only when the repository state matches the lesson.

      +

      Alex: Keep the teaching thread moving. Here is the plain-English version of What success looks like. You opened a real repository and found a real file. Put another way, that is the core action of this entire workshop -- everything else builds on it. It is like learning a transit route. The names of the stops matter because they tell you whether you are still going the right direction.

      +
      +

      Jamie: How should someone ask for help in a way that gets them unstuck faster?

      +

      Alex: This is where 10. If You Get Stuck becomes real: next Step: Start your learning journey with Chapter 02: Understanding GitHub. That matters in practice: Next: Chapter 02: Understanding GitHub Back: Chapter 00: Pre-Workshop Setup Related appendices: Appendix H: GitHub Desktop Appendix I: GitHub CLI Appendix J: Codespaces.

      +
      +

      Jamie: What should people carry with them after this?

      +

      Alex: Carry the map. Know what page or tool you are in, know which action you are taking, and know what confirmation should follow. If the confirmation is missing, pause. That pause is not wasted time; it is professional judgment.

      +

      Jamie: That is a better way to say it than just follow the steps.

      +

      Alex: Right. Steps matter, but understanding wins. That is episode 44. Next in the series is episode 45, where we keep building the same contributor muscles.

      +
      + +
      +

      5. Episode 2: Understanding GitHub on the Web

      +

      How GitHub organizes its web pages, heading structure, landmarks, and keyboard shortcuts.

      +

      Based on: Chapter 2: Understanding GitHub on the Web

      + + +

      Download Episode 2 (MP3)

      +
      +Read Transcript - Episode 2: Understanding GitHub on the Web + +

      Transcript

      +

      Alex: This is Git Going with GitHub, episode 2: Understanding GitHub on the Web. I am Alex. By the end of this episode, Understanding GitHub on the Web should feel less like a wall of GitHub words and more like a set of moves you can trust.

      +

      Jamie: And I am Jamie. I am here for the practical questions: what should I listen for, what can go wrong, and what is the next calm move?

      +
      +

      Alex: Today we are working on this: How GitHub organizes its web pages, heading structure, landmarks, and keyboard shortcuts. I want the learner to leave with a mental map, not just a remembered path through buttons.

      +

      Jamie: So the goal is understanding first, then action, then confirmation.

      +

      Alex: Right. We are building a rhythm: orient yourself, take one intentional action, then verify what changed before moving on.

      +
      +

      Jamie: Okay, set the room for us. What are we walking into?

      +

      Alex: Start with How GitHub Is Organized, and How to Orient Yourself on Every Page: Read this before navigating GitHub for the first time. The next useful detail is this: the lesson is the mental model that makes every subsequent guide easier.

      +

      Alex: The next layer is this. Here is the plain-English version of 1. GitHub's Three-Level Structure. GitHub is not a single page or a single kind of page. Put another way, it is three nested levels, and understanding which level you are on changes how you navigate. It is like learning a transit route. The names of the stops matter because they tell you whether you are still going the right direction.

      +

      Jamie: What is the one idea that makes the next few steps less mysterious?

      +

      Alex: This is where 2. What Is Always on Every GitHub Page becomes real: no matter where you navigate on GitHub, the same global navigation bar is at the top of every page. That matters in practice: Understanding its landmark structure means you always have a fixed orientation point.

      +
      +

      Alex: Now bring the learner back to the room. Keep the learner anchored in The Global Navigation Bar (always present). Visually, the top bar contains (left to right). This is the part to say slowly: Screen reader landmark: All of these live inside the landmark labeled "Navigation Menu".

      +

      Alex: A solid pull request habit is to separate three questions: what changed, why it changed, and what still needs review. That keeps the conversation useful instead of noisy.

      +

      Jamie: What would you say to someone who is already bracing for this to be too much?

      +

      Alex: The reason Secondary navigation (repository pages only) matters is that when you are inside a repository, a second navigation bar appears below the global bar. That gives the learner a simple foothold: this contains the repository's tabs: Code, Issues, Pull requests, Actions, Projects, Wiki, Security, Insights, and Settings.

      +

      Alex: A solid navigation habit is to prove where you are before activating controls. Headings, landmarks, and the address bar are not trivia; they are your map.

      +

      Alex: That matters because of the next idea. Start with Learning Cards: What Is Always on Every GitHub Page. There is something to understand, something to try, and something that proves the try worked.

      +

      Alex: On the ground, that means a few things. 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. 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.

      +

      Alex: The useful habit is simple: orient first, act second, verify third. That pause before acting is part of the work.

      +
      +

      Jamie: If I am listening before the workshop starts, what should settle in my mind first?

      +

      Alex: Here is the plain-English version of 3. How to Tell Where You Are. Three signals tell you exactly where you are on GitHub, without needing to see the visual layout.

      +

      Alex: This is where the talk moves from concept to action. This is where Signal 1: The URL becomes real: GitHub URLs are readable descriptions of your location. That matters in practice: Your browser's address bar is always reachable with Alt+D (Windows) or Cmd+L (Mac).

      +

      Jamie: What stays the same when the tool changes?

      +

      Alex: Keep the learner anchored in Signal 2: The browser tab title. GitHub formats page titles consistently.

      +
      +

      Alex: Before the learner moves on. The reason Signal 3: The first H1 heading matters is that press 1 (in Browse Mode) on any GitHub page to jump to the first H1 heading. That gives the learner a simple foothold: what you hear tells you what type of page you are on. The interface gets friendlier when it stops being a wall of controls and starts being a set of named places.

      +

      Jamie: Give me the version that sounds like an instructor, not a manual.

      +

      Alex: Start with Page Type 1: Repository Home (Code Tab): This is the central hub of any project. The next useful detail is this: It is where you find the file tree, the README, branch information, and links to all other parts of the repository.

      +

      Alex: Hold that next to this. Start with What to expect. There is something to understand, something to try, and something that proves the try worked.

      +

      Alex: The practical anchors are these. 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.

      +
      +

      Jamie: Where do you want a learner to place their attention here?

      +

      Alex: This is where Page Type 2: Issues List becomes real: a searchable, filterable list of all issues in the repository.

      +

      Alex: A solid issue habit is to read the title, the body, and the timeline before acting. You are listening for the requested action, the missing evidence, and the person who needs a response.

      +

      Alex: That connects to another useful point. Start with What to expect. There is something to understand, something to try, and something that proves the try worked.

      +

      Alex: For a learner, the useful signals are these. 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".

      +

      Jamie: Let's pause on Page Type 3: Issue Detail. What should a learner take away from it?

      +

      Alex: The reason Page Type 3: Issue Detail matters is that the full view of a single issue: the original report, all comments, labels, assignees, and the timeline.

      Alex: Here is the practical turn. Start with What to expect. There is something to understand, something to try, and something that proves the try worked.

      Alex: Here is what that changes in practice. 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.

      @@ -556,10 +890,135 @@

      Transcript

      -

      Episode 3: Navigating Repositories

      +

      6. Episode 19: Screen Reader Cheat Sheet

      +

      NVDA, JAWS, and VoiceOver commands for GitHub and VS Code.

      +

      Based on: Appendix B: Screen Reader Cheat Sheet

      +

      Audio and transcript are being regenerated for this episode.

      +
      +Read Transcript - Episode 19: Screen Reader Cheat Sheet + +

      Transcript

      +

      Alex: Welcome to episode 19 of Git Going with GitHub: Screen Reader Cheat Sheet. I am Alex, and today we are teaching this topic as a conversation you can carry into the workshop, not as a page you have to memorize.

      +

      Jamie: And I am Jamie. I will keep pulling the lesson back to real learners, real repositories, and the evidence that proves the work happened.

      +
      +

      Alex: The lesson focus is NVDA, JAWS, and VoiceOver commands for GitHub and VS Code. We will treat every step as a teachable decision, because that is what makes the skill portable.

      +

      Jamie: So we should explain the why clearly enough that the steps make sense when the learner meets them later.

      +

      Alex: That is it. If a listener only has audio right now, they should still get the complete concept and know what evidence would prove success.

      +
      +

      Jamie: Okay, set the room for us. What are we walking into?

      +

      Alex: Start with GitHub Navigation with NVDA, JAWS, and VoiceOver: How to use this sheet: Keep it open in a second window or print it. The next useful detail is this: Commands are organized by task so you can find what you need quickly while you work.

      +

      Alex: A solid navigation habit is to prove where you are before activating controls. Headings, landmarks, and the address bar are not trivia; they are your map.

      +

      Alex: The next layer is this. Start with Learning Cards: Using This Cheat Sheet. There is something to understand, something to try, and something that proves the try worked.

      +

      Alex: The practical anchors are these. Use heading navigation (H key) to jump between task categories -- each section is an h2 heading. Open the Elements List (NVDA+F7 or Insert+F6) and switch to the Headings tab to see all sections at once. Tables list commands in the left column and actions in the right -- use Ctrl+Alt+Arrow keys to navigate. Keep this open in a second browser tab or print it for side-by-side reference while working. Command tables are compact -- increase zoom to 150-200% and the two-column layout stays readable. Key names are in backtick code formatting which gives them a distinct visual border.

      +

      Jamie: What is the one idea that makes the next few steps less mysterious?

      +

      Alex: This is where Screen Reader Mode Basics becomes real: before navigating GitHub, understand the two fundamental modes that all screen readers use on the web.

      +
      +

      Alex: Now bring the learner back to the room. Keep the learner anchored in Browse Mode (also called Virtual Cursor / Reading Mode). This is your primary mode for reading and navigating pages. This is the part to say slowly: The screen reader intercepts keystrokes and uses them as navigation commands - for example, pressing H jumps to the next heading rather than typing the letter H.

      +

      Jamie: What would you say to someone who is already bracing for this to be too much?

      +

      Alex: The reason Focus Mode (also called Forms or Application Mode) matters is that this mode is for typing and interacting with form fields, text areas, buttons, and interactive widgets. That gives the learner a simple foothold: your keystrokes go directly to the web page instead of being captured by the screen reader.

      +

      Alex: The useful habit is simple: orient first, act second, verify third. That pause before acting is part of the work.

      +

      Alex: That matters because of the next idea. Start with Quick Navigation Keys (Browse Mode): These single-key shortcuts work in Browse Mode (NVDA and JAWS). The next useful detail is this: VoiceOver users with Quick Nav enabled use the same keys. Think of it like entering a new building: first you find the lobby, then the room, then the door you actually need.

      +
      +

      Jamie: There are a lot of tools in play. How do we keep that from feeling like a contest?

      +

      Alex: Here is the plain-English version of Heading Navigation - Your Most-Used Tool. GitHub structures pages with headings. Put another way, jumping between headings is the fastest way to navigate.

      +

      Alex: This is where the talk moves from concept to action. This is where Landmark Navigation - Jump Between Page Regions becomes real: landmarks are named regions of a page (navigation, main content, sidebar, etc.).

      +

      Jamie: Where do you want a learner to place their attention here?

      +

      Alex: Keep the learner anchored in The Elements List - Your Navigation Superpower. This is one of the most powerful tools for navigating complex pages. This is the part to say slowly: It opens a dialog listing all headings, links, buttons, form fields, or landmarks on the page.

      +
      +

      Jamie: What is the ordered workflow?

      +

      Alex: Start with How to use it. There is something to understand, something to try, and something that proves the try worked.

      +

      Alex: First, press the keyboard shortcut above. Then, navigate between the tabs (Headings, Links, etc.) with Tab or arrow keys. After that, type to filter the list (e.g., type "new issue" to find the New Issue button). Finally, press Enter to jump to the item on the page. The rhythm is simple: orient, act, verify, then continue.

      +

      Jamie: What should someone listen for when a lesson offers more than one tool path?

      +

      Alex: Start with Per-Screen-Reader Command Reference: A compact reference organized by screen reader. The next useful detail is this: For task-based navigation guides (navigating a PR, leaving a comment, etc.), see the sections below.

      +

      Alex: Hold that next to this. Here is the plain-English version of VoiceOver (macOS). The VO modifier key is Control+Option (abbreviated VO). Put another way, rotor navigation: Open with VO+U, use ←/→ to switch between element types (Headings, Links, Form Controls, Tables, Landmarks), and ↑/↓ to navigate within a type.

      +
      +

      Jamie: If I am listening before the workshop starts, what should settle in my mind first?

      +

      Alex: Start with Learning Cards: Task-Based Navigation. There is something to understand, something to try, and something that proves the try worked.

      +

      Alex: That shows up in the workshop in a few specific ways. The sections below are organized by GitHub page type -- jump to the page you are currently on. Each table shows Goal in the left column and Key Sequence in the right -- read left-to-right per row. Practice one page's commands at a time rather than memorizing everything at once. Each page section has a compact table -- at high zoom, the two-column layout reads naturally. Key sequences are shown in backtick formatting for clear visual distinction from descriptions. Open the matching GitHub page side by side and try each key sequence as you read.

      +

      Alex: That connects to another useful point. Keep the learner anchored in Checking and Enabling Feature Previews. GitHub Feature Previews are opt-in UI improvements. This is the part to say slowly: For screen reader users, two are especially important: New Issues Experience and New Files Changed Experience. A good GitHub workflow is like a well-run meeting: everyone knows the topic, the next action, and who has the floor.

      +

      Alex: A solid pull request habit is to separate three questions: what changed, why it changed, and what still needs review. That keeps the conversation useful instead of noisy.

      +

      Jamie: Give me the version that sounds like an instructor, not a manual.

      +

      Alex: The reason VoiceOver (macOS) matters is that see Pre-Workshop Setup, Step 4 for full details on what each feature enables and why it matters for screen reader users.

      +
      +

      Jamie: Give me the sequence, because order matters here.

      +

      Alex: Start with Entering text in GitHub (Focus Mode required). There is something to understand, something to try, and something that proves the try worked.

      +

      Alex: On the ground, that means a few things. NVDA: Insert+Space. JAWS: Insert+Z (or it switches automatically). VoiceOver: VO+Shift+Down to interact with the text area. JAWS: Insert+Z. VoiceOver: VO+Shift+Up to stop interacting.

      +

      Alex: First, navigate to the text field using Browse Mode: F or E for edit fields, Tab for any interactive element. Then, switch to Focus Mode. After that, type your content. Finally, return to Browse Mode when done typing. Think of it as a rail line: each stop confirms you are still on the right route before the next one.

      +

      Jamie: Let's pause on Markdown formatting shortcuts in GitHub text areas. What should a learner take away from it?

      +

      Alex: Here is the plain-English version of Markdown formatting shortcuts in GitHub text areas. These work while in Focus Mode inside a GitHub text area.

      +

      Alex: Keep the thread going. This is where Dropdown Menus and Flyouts becomes real: GitHub uses popup flyout menus for labels, assignees, reviewers, and branch selection. The workshop is closer to rehearsal than lecture. You hear the move, try the move, and then check what changed.

      +
      +

      Jamie: What is the safe way to learn from that example?

      +

      Alex: Start with VoiceOver users. There is something to understand, something to try, and something that proves the try worked.

      +

      Alex: Treat examples as spoken recipes, not decorations. You may hear something like Step 1: Navigate to the button with Tab or VO+Right; Step 2: Activate with VO+Space; Step 3: VO+Down to enter the flyout; Step 4: VO+Right/Left to navigate items; Step 5: VO+Space to select, Esc to close. Read the command, understand what it changes, then run it only when the repository state matches the lesson.

      +

      Alex: Another way to ground it. The reason GitHub Built-In Keyboard Shortcuts matters is that GitHub has a dedicated keyboard shortcut system built into every page. That gives the learner a simple foothold: these are completely separate from your screen reader's navigation keys - they are JavaScript-powered shortcuts that trigger GitHub actions directly without using the mouse.

      +

      Jamie: Let's pause on Using GitHub shortcuts alongside a screen reader. What should a learner take away from it?

      +

      Alex: Start with Using GitHub shortcuts alongside a screen reader: The key issue: when your screen reader is in Browse Mode, it intercepts keystrokes before they reach the page. The next useful detail is this: GitHub's shortcut system relies on the page receiving the keystroke directly.

      +
      +

      Jamie: How do you keep commands from becoming magic words?

      +

      Alex: Start with Practical sequence for G shortcuts. There is something to understand, something to try, and something that proves the try worked.

      +

      Alex: Treat examples as spoken recipes, not decorations. You may hear something like Step 1: Press NVDA+Space (or Insert+Z in JAWS) - enter Focus Mode; Step 2: Press G, pause half a second; Step 3: Press the second key (I, P, A, etc.); Step 4: Press NVDA+Space to return to Browse Mode on the new page. Read the command, understand what it changes, then run it only when the repository state matches the lesson.

      +

      Jamie: Let's pause on Discover shortcuts on any page - The? Key. What should a learner take away from it?

      +

      Alex: This is where Discover shortcuts on any page - The? Key becomes real: start here every time you're on an unfamiliar GitHub page. That matters in practice: key opens GitHub's built-in keyboard shortcut help dialog.

      +

      Alex: Here is the practical turn. Keep the learner anchored in Reading the shortcut dialog with a screen reader. The dialog is a standard ARIA modal (role="dialog"). This is the part to say slowly: When it opens, browser focus moves inside it automatically.

      +

      Alex: For a learner, the useful signals are these. It is context-aware - the shortcuts shown change based on your current page. It is always current - GitHub automatically updates it when they add new shortcuts. The dialog is divided into sections: Site-wide, Source code browsing, Issues, Pull requests, Notifications, etc. - only sections relevant to the current page appear. You do not need to be in Focus Mode to open it -? works from Browse Mode.

      +
      +

      Jamie: Let's pause on Repository navigation - on any repository page. What should a learner take away from it?

      +

      Alex: The reason Repository navigation - on any repository page matters is that and: These open github.dev, which is VS Code running inside your browser - same keyboard shortcuts, same screen reader mode. That gives the learner a simple foothold: opens a new tab so you keep your current GitHub page.

      +

      Alex: Before the learner moves on. Start with Issue and pull request lists: These shortcuts work on the Issues list page and the Pull Requests list page. Think of it like entering a new building: first you find the lobby, then the room, then the door you actually need.

      +

      Alex: A solid issue habit is to read the title, the body, and the timeline before acting. You are listening for the requested action, the missing evidence, and the person who needs a response.

      +

      Jamie: Let's pause on Issue and pull request detail pages. What should a learner take away from it?

      +

      Alex: Here is the plain-English version of Issue and pull request detail pages. When viewing an open issue or pull request. Put another way, tip for R - quote a specific part of a comment: In Browse Mode, select the text you want to quote by holding Shift and pressing arrow keys.

      +
      +

      Alex: This is the part worth saying out loud. This is where Comments - inside any text area (Focus Mode required) becomes real: these shortcuts work while typing in any GitHub comment or description field. That matters in practice: The most important one: Ctrl+Enter submits a comment from inside the text area - you do not have to Tab to the Submit button and press Enter.

      +

      Jamie: Let's pause on Notifications page. What should a learner take away from it?

      +

      Alex: Keep the learner anchored in Notifications page. On your Notifications page (github.com/notifications).

      +

      Alex: A solid project habit is to treat metadata as decision support. Labels, status, assignees, and notifications tell you what kind of attention the work needs.

      +

      Alex: Keep the teaching thread moving. The reason GitHub Actions matters is that on any Actions page in a repository. The interface gets friendlier when it stops being a wall of controls and starts being a set of named places.

      +
      +

      Jamie: Let's pause on Projects (board and table view). What should a learner take away from it?

      +

      Alex: Start with Projects (board and table view): Keep the official reference handy: github.com/keyboard-shortcuts - and press? The next useful detail is this: on any GitHub page for the context-specific subset.

      +

      Alex: Keep the teaching thread moving. Start with "The page doesn't match the instructions". There is something to understand, something to try, and something that proves the try worked.

      +

      Alex: The parts worth keeping in working memory are these. Solution: Maximize your browser window. GitHub's layout changes at smaller widths, and landmarks/headings may appear in different positions. Full-screen or maximized window gives the most consistent experience.

      +

      Jamie: Let's pause on "I'm hearing too much or navigating too slowly". What should a learner take away from it?

      +

      Alex: Start with "I'm hearing too much or navigating too slowly". There is something to understand, something to try, and something that proves the try worked.

      +

      Alex: Here is what that changes in practice. Disable hovercards in GitHub Accessibility Settings (see Pre-Workshop Setup). Adjust your screen reader verbosity settings. Use NVDA+F7 / VO+U to get a filtered list rather than tabbing through everything. NVDA reads GitHub too slowly: In NVDA Settings → Browse Mode → increase "Maximum number of characters on one line" to 10000. This prevents NVDA from pausing to wrap long lines.

      +
      +

      Alex: Keep the teaching thread moving. Start with "I pressed H but it's typing the letter H". There is something to understand, something to try, and something that proves the try worked.

      +

      Alex: The room should hear these as checkpoints. You are in Focus Mode - press NVDA+Space (or JAWS+Z) to return to Browse Mode. In Browse Mode, H is a navigation key, not a typing key.

      +

      Jamie: Let's pause on "I can't find the comment box". What should a learner take away from it?

      +

      Alex: Start with "I can't find the comment box". There is something to understand, something to try, and something that proves the try worked.

      +

      Alex: These are the details that keep the idea from floating away. Use D to navigate to the "Add a comment" landmark. Then E or F to jump to the edit field. Switch to Focus Mode before typing.

      +

      Alex: Keep the teaching thread moving. Start with "The diff/code area is hard to navigate". There is something to understand, something to try, and something that proves the try worked.

      +

      Alex: That becomes easier when you listen for these cues. The Files Changed tab requires Focus Mode to navigate the diff table. Use NVDA+Space to enter Focus Mode, then use arrow keys. Use Ctrl+Alt+Arrow keys to move between table cells.

      +
      +

      Jamie: Let's pause on Official Screen Reader Resources. What should a learner take away from it?

      +

      Alex: Start with Official Screen Reader Resources. There is something to understand, something to try, and something that proves the try worked.

      +

      Alex: A few details make that real. GitHub Repos Screen Reader Guide. GitHub Issues Screen Reader Guide. GitHub Pull Requests Screen Reader Guide. GitHub Copilot in VS Code Screen Reader Guide. GitHub Accessibility Settings Docs. GitHub Keyboard Shortcuts Reference.

      +

      Alex: Keep the teaching thread moving. This is where Keyboard Shortcuts in Other Appendices becomes real: this cheat sheet covers GitHub web navigation and screen reader commands. That matters in practice: Additional keyboard shortcuts for specific tools are documented in. The workshop is closer to rehearsal than lecture. You hear the move, try the move, and then check what changed.

      +

      Jamie: Let's pause on Screen Reader Compatibility Notes. What should a learner take away from it?

      +

      Alex: Keep the learner anchored in Screen Reader Compatibility Notes. The commands in this cheat sheet have been written for and tested with the following screen readers.

      +
      +

      Jamie: How would you walk the room through that step by step?

      +

      Alex: The reason If a command doesn't work as described matters is that next: Appendix C: Markdown Reference Back: Appendix A: Glossary Teaching chapter: Chapter 02: Understanding GitHub.

      +

      Alex: First, check that you are in the correct mode (Browse Mode vs. Focus Mode). Then, verify your screen reader version - older versions may use different key assignments. After that, check GitHub's own shortcut dialog (? key) for the current page's shortcuts. Finally, see Troubleshooting above for common fixes. The rhythm is simple: orient, act, verify, then continue.

      +
      +

      Jamie: What should people carry with them after this?

      +

      Alex: Carry the map. Know what page or tool you are in, know which action you are taking, and know what confirmation should follow. If the confirmation is missing, pause. That pause is not wasted time; it is professional judgment.

      +

      Jamie: That is a better way to say it than just follow the steps.

      +

      Alex: Right. Steps matter, but understanding wins. That is episode 19. Next in the series is episode 20, where we keep building the same contributor muscles.

      +
      + +
      +

      7. Episode 3: Navigating Repositories

      Exploring a repository: tabs, files, README, branches, and commit history.

      Based on: Chapter 3: Navigating Repositories

      -

      Audio and transcript are being regenerated for this episode.

      + + +

      Download Episode 3 (MP3)

      Read Transcript - Episode 3: Navigating Repositories @@ -754,10 +1213,15 @@

      Transcript

      -

      Episode 4: The Learning Room

      +

      8. Episode 4: The Learning Room

      Your shared practice environment: challenges, PR workflow, bot feedback, peer review.

      Based on: Chapter 4: The Learning Room

      -

      Audio and transcript are being regenerated for this episode.

      + + +

      Download Episode 4 (MP3)

      Read Transcript - Episode 4: The Learning Room @@ -971,6054 +1435,5320 @@

      Transcript

      -

      Episode 5: Working with Issues

      -

      Filing, searching, filtering, commenting on, and managing GitHub issues.

      -

      Based on: Chapter 5: Working with Issues

      +

      9. Challenge 01: Find Your Way Around

      +

      Repository orientation, headings, tabs, file tree navigation, and confidence in the Learning Room.

      +

      Practice focus: Day 1 foundation

      Audio and transcript are being regenerated for this episode.

      -Read Transcript - Episode 5: Working with Issues +Read Transcript - Challenge 01: Find Your Way Around

      Transcript

      -

      Alex: Welcome back to Git Going with GitHub. This is episode 5: Working with Issues. I am Alex, and today we are turning Working with Issues from a list of instructions into a working mental model.

      -

      Jamie: And I am Jamie. I will stop us whenever the instructions sound simple on paper but might feel different with a keyboard and screen reader.

      +

      Alex: This is Challenge Coach for Find Your Way Around. I am Alex, and we are going to teach the move before asking you to prove it.

      +

      Jamie: And I am Jamie. I will translate the challenge into the practical questions learners actually have while doing it.

      -

      Alex: Filing, searching, filtering, commenting on, and managing GitHub issues. That is the surface description. Underneath it, we are building judgment: where to focus, what to ignore, and how to verify the result.

      -

      Jamie: So we are not using the audio as a shortcut around learning. We are using it to make the learning easier to enter.

      -

      Alex: Yes. A good audio lesson gives someone enough context to try the work with confidence, even before they open the written material.

      +

      Alex: Repository orientation, headings, tabs, file tree navigation, and confidence in the Learning Room. That is the task layer. The teaching layer is understanding why the move belongs in a contributor workflow.

      +

      Jamie: So evidence is not just proof for the facilitator. It is part of how the learner understands the workflow.

      +

      Alex: Right. A good challenge produces something inspectable: a comment, issue, branch, commit, pull request, review, or clear note about what happened.

      -

      Jamie: Okay, set the room for us. What are we walking into?

      -

      Alex: Start with Filing, Managing, and Participating in GitHub Issues: Issues are where open source collaboration begins. The next useful detail is this: everything from finding the right issue to file a perfect bug report - all with your keyboard and screen reader.

      -

      Alex: A solid issue habit is to read the title, the body, and the timeline before acting. You are listening for the requested action, the missing evidence, and the person who needs a response.

      -

      Alex: The next layer is this. Here is the plain-English version of Workshop Recommendation (Chapter 5 / Challenges 2-3). Chapter 5 is the first issue-based challenge chapter with short, confidence-building tasks. Put another way, it supports Challenge 2 (File Your First Issue) and Challenge 3 (Join the Conversation). It is like learning a transit route. The names of the stops matter because they tell you whether you are still going the right direction.

      -

      Alex: The practical anchors are these. There are 2 core challenges plus one optional extension. Each challenge should take under 10 minutes. The evidence is issue comments and issue metadata. The pattern is claim - act - confirm.

      +

      Jamie: What makes this practice feel low-stakes but still real?

      +

      Alex: Start with Challenge 1: Find Your Way Around: What you will do: Explore the learning-room repository like a scavenger hunt. The next useful detail is this: Find the tabs, navigate the file tree, read the README, and locate key files.

      +

      Jamie: How would you walk the room through that step by step?

      +

      Alex: Here is the plain-English version of Scavenger hunt checklist. You do not need to complete them in order. Put another way, for each item, write a short sentence about what you found." placeholder. It is like learning a transit route. The names of the stops matter because they tell you whether you are still going the right direction.

      +

      Alex: The practical anchors are these. [ ] Find the Code tab and count how many files are in the root of the repository. [ ] Open the Issues tab and find an open issue. [ ] Navigate to docs/welcome.md and read the first paragraph. [ ] Find the repository description (hint: it is near the top of the Code tab).

      +

      Alex: First, I found files in the root of the repository. Then, the open issue I found was titled " ". After that, the first paragraph of welcome.md says. Finally, the repository description is. Treat it like a recipe: do not add the next ingredient until the previous one is actually in the bowl.

      Jamie: What does the learner do first, second, and then after that?

      -

      Alex: This is where Chapter 5 Challenge Set becomes real: chapter 5 focuses on issue skills. That matters in practice: You do NOT need to create a branch or edit any files for these challenges.

      -

      Alex: First, create your first issue - file a new issue with a clear title and description. Then, comment and @mention - leave a comment on a classmate's issue and tag them with an @mention. After that, optional extension: Add a sub-issue - break a larger issue into smaller, trackable pieces if your repository has sub-issues enabled. It is a checklist, but a meaningful one: every item creates evidence that the next step is safe.

      +

      Alex: First, the README says this workshop is for. Then, the About section shows. It is a checklist, but a meaningful one: every item creates evidence that the next step is safe.

      +

      Jamie: What is the one idea that makes the next few steps less mysterious?

      +

      Alex: This is where Peer simulation check becomes real: after you submit your evidence, open the Peer Simulation: Welcome Link Needs Context issue in this repository and leave an encouraging comment or reaction. That matters in practice: If your facilitator gave you access to a real buddy repository, you may use your buddy's issue instead.

      -

      Jamie: Turn that into a path someone can follow.

      -

      Alex: Keep the learner anchored in Challenge 2 Step-by-Step: Create Your First Issue. File a new issue in your Learning Room repository with a specific title and a meaningful description. This is the part to say slowly: Issues are the prompts that wake up AI.

      -

      Alex: For a learner, the useful signals are these. "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". What the problem is or what content is missing.

      -

      Alex: First, open your Learning Room repository in your browser. Then, navigate to the Issues tab (press G then I to jump there with keyboard shortcuts, or find the "Issues" link in the repository navigation). After that, activate the New issue button. Finally, if a template picker appears, select Open a blank issue (or choose a template if one fits). It is like walking a hallway with named doors: read the sign, enter the right room, then confirm where you landed.

      -

      Jamie: What is the ordered workflow?

      -

      Alex: First, in the Title field, type a clear, specific title (at least 12 characters). Then, in the Body field, write a meaningful description (at least 80 characters). After that, activate Submit new issue. Finally, copy the issue URL or note the issue number (for example, 150). You will reference this later. The rhythm is simple: orient, act, verify, then continue.

      -

      Jamie: Give me the sequence, because order matters here.

      -

      Alex: The reason Challenge 4.2 Step-by-Step: Comment and @Mention matters is that leave a comment on another student's issue and use an @mention to notify them. That gives the learner a simple foothold: the Issues tab of your Learning Room repository on GitHub.com.

      -

      Alex: The parts worth keeping in working memory are these. "@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.".

      -

      Alex: First, open the Issues tab in your Learning Room repository. Then, find an issue created by a classmate (look for issues from Challenge 4.1, or browse recent open issues). After that, open the issue by activating its title link. Finally, read the issue description to understand what they reported. The rhythm is simple: orient, act, verify, then continue.

      -

      Jamie: How would you walk the room through that step by step?

      -

      Alex: First, scroll to the comment box at the bottom of the issue. Then, write a helpful comment that @mentions the issue author by username. After that, activate the Comment button (or press Ctrl+Enter). Think of it as a rail line: each stop confirms you are still on the right route before the next one.

      +

      Alex: Now bring the learner back to the room. Start with Code tab. There is something to understand, something to try, and something that proves the try worked.

      +

      Alex: For a learner, the useful signals are these. The root of the repository contains files like README.md, docs/, and.github/. The file count varies as the repository evolves -- any reasonable count is correct.

      +

      Jamie: What would you say to someone who is already bracing for this to be too much?

      +

      Alex: Start with Issues tab. There is something to understand, something to try, and something that proves the try worked.

      +

      Alex: The parts worth keeping in working memory are these. You should have found at least one open issue. If no issues were open, noting that the tab exists is sufficient.

      +

      Alex: A solid issue habit is to read the title, the body, and the timeline before acting. You are listening for the requested action, the missing evidence, and the person who needs a response.

      +

      Alex: That matters because of the next idea. Start with docs/welcome.md. There is something to understand, something to try, and something that proves the try worked.

      +

      Alex: On the ground, that means a few things. The first paragraph introduces the learning room and what students will do. You may have noticed TODO comments -- those are intentionally left for Challenge 2.

      Alex: The useful habit is simple: orient first, act second, verify third. That pause before acting is part of the work.

      -

      Jamie: Let's pause on Challenge 4.3 Step-by-Step: Add a Sub-Issue. What should a learner take away from it?

      -

      Alex: Start with Challenge 4.3 Step-by-Step: Add a Sub-Issue: Break a larger issue into smaller, trackable pieces using GitHub's sub-issue feature. The next useful detail is this: the issue you created in Challenge 4.1 (or any open issue you have permission to edit). Think of it like entering a new building: first you find the lobby, then the room, then the door you actually need.

      -

      Alex: On the ground, that means a few things. Sub-issue: "Add alt text to welcome banner image". Sub-issue: "Fix heading hierarchy in Getting Started section".

      -

      Alex: First, open the issue you created in Challenge 4.1. Then, 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. After that, activate Add sub-issue and choose Create new sub-issue. Finally, 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". Think of it as a rail line: each stop confirms you are still on the right route before the next one.

      -

      Jamie: Before we leave Challenge 4.3 Step-by-Step: Add a Sub-Issue, what is the practical point?

      -

      Alex: First, add a short description and activate Create. Then, the sub-issue now appears nested under the parent issue with a progress indicator. Treat it like a recipe: do not add the next ingredient until the previous one is actually in the bowl.

      -
      -

      Jamie: What should the learner prove to themselves after each small task?

      -

      Alex: Here is the plain-English version of 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. Put another way, replace [number] with the actual issue numbers.

      -

      Alex: This is where the talk moves from concept to action. Start with Expected Outcomes. There is something to understand, something to try, and something that proves the try worked.

      -

      Alex: The room should hear these as checkpoints. 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.

      -

      Jamie: Let's pause on If You Get Stuck. What should a learner take away from it?

      -

      Alex: Start with If You Get Stuck. There is something to understand, something to try, and something that proves the try worked.

      -

      Alex: First, can't find a classmate's issue? Filter the Issues tab by is:open and look for recent ones. Then, @mention not working? Make sure you type @ immediately followed by the username with no space. After that, sub-issue option not visible? Ask a facilitator - the feature may need to be enabled for the repository. Finally, still stuck? Ask a facilitator for a direct issue link. It is like walking a hallway with named doors: read the sign, enter the right room, then confirm where you landed.

      -

      Jamie: Before we leave If You Get Stuck, what is the practical point?

      -

      Alex: First, finished but not sure you did it right? Compare your work against the Challenge 2 reference solution or the Challenge 3 reference solution. The rhythm is simple: orient, act, verify, then continue.

      -

      Alex: Before the learner moves on. The reason Learning Moment matters is that issues are collaborative spaces, not just task lists. That gives the learner a simple foothold: an @mention tells someone "I need your attention here." Sub-issues turn vague tasks into clear checklists. The interface gets friendlier when it stops being a wall of controls and starts being a set of named places.

      -

      Jamie: Let's pause on Learning Pattern Used in This Chapter. What should a learner take away from it?

      -

      Alex: Start with Learning Pattern Used in This Chapter. There is something to understand, something to try, and something that proves the try worked.

      -

      Alex: First, start with a small, safe action (create an issue). Then, practice communication in public issue threads (@mention a peer). After that, organize work into smaller pieces (sub-issues). Finally, leave clear evidence in the issue timeline. Think of it as a rail line: each stop confirms you are still on the right route before the next one.

      -

      Jamie: Before we leave Learning Pattern Used in This Chapter, what is the practical point?

      -

      Alex: First, build momentum for file editing and PR work in Chapter 6. Treat it like a recipe: do not add the next ingredient until the previous one is actually in the bowl.

      -

      Alex: Hold that next to this. Here is the plain-English version of About Learning Cards in This Chapter. This chapter provides learning cards: expandable blocks that offer perspective-specific guidance for different ways of working. Put another way, not every card appears at every step.

      +

      Jamie: Okay, set the room for us. What are we walking into?

      +

      Alex: Start with Repository description and README. There is something to understand, something to try, and something that proves the try worked.

      +

      Alex: Here is what that changes in practice. The description appears at the top of the Code tab, below the repository name. The README renders automatically below the file list.

      +

      Alex: This is where the talk moves from concept to action. Start with Alternate approaches. There is something to understand, something to try, and something that proves the try worked.

      +

      Alex: The room should hear these as checkpoints. github.com: Click each tab in the top navigation bar. github.dev: press the period key on any repo page to open the web editor, then use the Explorer sidebar. VS Code with GitHub extension: Use the GitHub Repositories extension to browse remotely. GitHub CLI: gh repo view Community-Access/git-going-with-github --web opens the repo in a browser.

      +

      Alex: A solid pull request habit is to separate three questions: what changed, why it changed, and what still needs review. That keeps the conversation useful instead of noisy.

      +

      Jamie: Where do you want a learner to place their attention here?

      +

      Alex: Keep the learner anchored in What matters. The learning objective is familiarity with repository navigation, not memorizing exact file counts. This is the part to say slowly: If you explored the tabs and found the key files, you completed this challenge.

      -

      Jamie: What should they understand before typing anything?

      -

      Alex: This is where Local Git Alternative: Working from Your Clone becomes real: if you cloned the learning-room in Block 0 and prefer working locally. That matters in practice: During Block 0 you cloned the Learning Room repository to your computer.

      -

      Alex: Treat examples as spoken recipes, not decorations. You may hear something like cd /Documents/learning-room or wherever you cloned it; git status should show "On branch main". 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. Read the command, understand what it changes, then run it only when the repository state matches the lesson.

      -

      Alex: A solid Git habit is to know which branch you are on, what changed, and what confirmation you expect before you run the next command.

      -

      Alex: That connects to another useful point. Keep the learner anchored in What Is a GitHub Issue? An issue is a discussion thread attached to a repository. This is the part to say slowly: Every issue has a number ( 42), a state (Open or Closed), a title, a description, and a comment thread. A good GitHub workflow is like a well-run meeting: everyone knows the topic, the next action, and who has the floor.

      -

      Alex: Here is what that changes in practice. 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".

      -

      Jamie: Let's pause on From a repository page. What should a learner take away from it?

      -

      Alex: The reason From a repository page matters is that click the Issues tab in the repository navigation bar below the repository name. That gives the learner a simple foothold: the tab shows the open issue count (e.g., "Issues · 14").

      -

      Alex: First, press D to navigate to the "Repository navigation" landmark. Then, press K or Tab to move through the tab links. After that, find "Issues" - it will be announced with the count: "Issues, 14 open". Finally, press Enter to open the Issues tab. The rhythm is simple: orient, act, verify, then continue.

      -

      Jamie: Before we leave From a repository page, what is the practical point?

      -

      Alex: First, vO+U → Landmarks → navigate to "Repository navigation". Then, vO+Right or Quick Nav K to move through tab links. After that, find "Issues" - VoiceOver announces the count: "Issues 14". Finally, vO+Space to activate the Issues tab. Think of it as a rail line: each stop confirms you are still on the right route before the next one.

      -

      Alex: Treat examples as spoken recipes, not decorations. You may hear something like gh issue list. gh issue list --label "good first issue"; gh issue list --assignee @me; gh issue list --state closed. Read the command, understand what it changes, then run it only when the repository state matches the lesson.

      +

      Alex: Before the learner moves on. The reason How GitHub Is Organized, and How to Orient Yourself on Every Page matters is that read this before navigating GitHub for the first time. That gives the learner a simple foothold: the lesson is the mental model that makes every subsequent guide easier. The interface gets friendlier when it stops being a wall of controls and starts being a set of named places.

      +

      Jamie: Give me the version that sounds like an instructor, not a manual.

      +

      Alex: Start with 1. GitHub's Three-Level Structure: GitHub is not a single page or a single kind of page. The next useful detail is this: It is three nested levels, and understanding which level you are on changes how you navigate.

      +

      Alex: Hold that next to this. Here is the plain-English version of 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. Put another way, understanding its landmark structure means you always have a fixed orientation point.

      -

      Alex: Here is the practical turn. Start with Direct URL: Navigate directly: https://github.com/[owner]/[repo]/issues.

      -

      Jamie: What would you say to someone who is already bracing for this to be too much?

      -

      Alex: Start with Learning Cards: Navigating to the Issues List. There is something to understand, something to try, and something that proves the try worked.

      -

      Alex: These are the details that keep the idea from floating away. 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. 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.

      -

      Alex: Keep the thread going. This is where Page structure becomes real: 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. That matters in practice: This is often faster than tabbing through many elements and helps you understand the full page structure before diving in. The workshop is closer to rehearsal than lecture. You hear the move, try the move, and then check what changed.

      +

      Jamie: If I am listening before the workshop starts, what should settle in my mind first?

      +

      Alex: This is where The Global Navigation Bar (always present) becomes real: visually, the top bar contains (left to right). That matters in practice: Screen reader landmark: All of these live inside the landmark labeled "Navigation Menu".

      +

      Alex: That connects to another useful point. Keep the learner anchored in Secondary navigation (repository pages only). When you are inside a repository, a second navigation bar appears below the global bar. This is the part to say slowly: This contains the repository's tabs: Code, Issues, Pull requests, Actions, Projects, Wiki, Security, Insights, and Settings. A good GitHub workflow is like a well-run meeting: everyone knows the topic, the next action, and who has the floor.

      +

      Alex: A solid navigation habit is to prove where you are before activating controls. Headings, landmarks, and the address bar are not trivia; they are your map.

      +

      Jamie: Let's pause on Learning Cards: What Is Always on Every GitHub Page. What should a learner take away from it?

      +

      Alex: Start with Learning Cards: What Is Always on Every GitHub Page. There is something to understand, something to try, and something that proves the try worked.

      +

      Alex: These are the details that keep the idea from floating away. 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. 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.

      -

      Jamie: Let's pause on How to read the issue list. What should a learner take away from it?

      -

      Alex: Keep the learner anchored in How to read the issue list. The issues list shows each issue as a row with its title, labels, number, assignee avatars, and comment count. This is the part to say slowly: Closed issues show a purple merged/closed badge.

      -

      Alex: That becomes easier when you listen for these cues. 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.

      -

      Alex: First, press D to reach the "Search Results List" landmark. Then, press 3 (h3) to navigate by issue titles - each issue title is an h3 link. After that, press I to move between list items if you want more detail per item. Finally, press Enter on a title to open that issue. It is like walking a hallway with named doors: read the sign, enter the right room, then confirm where you landed.

      -

      Jamie: Before we leave How to read the issue list, what is the practical point?

      -

      Alex: First, vO+U → Landmarks → navigate to "Search Results List". Then, vO+Down to read through items. After that, h (with Quick Nav on) or VO+U → Headings to jump by issue title. The rhythm is simple: orient, act, verify, then continue.

      -

      Alex: Another way to ground it. The reason What is announced per issue matters is that when you navigate to an issue in the list, your screen reader will announce (in some order).

      -

      Alex: A few details make that real. 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").

      -

      Jamie: What is the one idea that makes the next few steps less mysterious?

      -

      Alex: Start with Learning Cards: The Issues List Page. There is something to understand, something to try, and something that proves the try worked.

      -

      Alex: That shows up in the workshop in a few specific ways. 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. 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.

      +

      Alex: Here is the practical turn. Start with 3. How to Tell Where You Are: Three signals tell you exactly where you are on GitHub, without needing to see the visual layout.

      +

      Jamie: Let's pause on Signal 1: The URL. What should a learner take away from it?

      +

      Alex: Here is the plain-English version of Signal 1: The URL. GitHub URLs are readable descriptions of your location. Put another way, your browser's address bar is always reachable with Alt+D (Windows) or Cmd+L (Mac).

      +

      Alex: Keep the thread going. This is where Signal 2: The browser tab title becomes real: GitHub formats page titles consistently. The workshop is closer to rehearsal than lecture. You hear the move, try the move, and then check what changed.

      -

      Alex: This is the part worth saying out loud. Here is the plain-English version of Filtering and Searching Issues. Filtering lets you narrow the list to find the right issue quickly. It is like learning a transit route. The names of the stops matter because they tell you whether you are still going the right direction.

      -

      Jamie: Let's pause on Using the search/filter bar. What should a learner take away from it?

      -

      Alex: Start with Using the search/filter bar. There is something to understand, something to try, and something that proves the try worked.

      -

      Alex: First, press F or E to jump to the filter input field (or navigate from the landmark). Then, switch to Focus Mode (NVDA+Space / Insert+Z) if not already in it. After that, type your filter or search query. Finally, press Enter to apply. It is a checklist, but a meaningful one: every item creates evidence that the next step is safe.

      -

      Jamie: Let's pause on Using the filter buttons. What should a learner take away from it?

      -

      Alex: Keep the learner anchored in Using the filter buttons. Above the issue list, there is an actions toolbar with filter buttons for Labels, Milestones, Assignees, etc. This is the part to say slowly: The filter buttons do not indicate the current filter state.

      -

      Alex: The practical takeaway is this. 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.

      -

      Alex: First, press Tab from the search bar (or Shift+Tab from the issue list) to reach the actions toolbar. Then, press ←/→ to move between toolbar options (Label, Milestone, Assignee, Sort). After that, press Enter to open the selected dropdown. Finally, use ↑/↓ to navigate options in the dropdown. It is like walking a hallway with named doors: read the sign, enter the right room, then confirm where you landed.

      -

      Jamie: Before we leave Using the filter buttons, what is the practical point?

      -

      Alex: First, press Enter or Space to select. Then, press Escape to close (filter applies immediately). After that, tab forward from the search bar to reach the filter buttons, or use Quick Nav to find them. Finally, vO+Left/Right to move between Label, Milestone, Assignee, Sort buttons. The rhythm is simple: orient, act, verify, then continue.

      -

      Alex: Treat examples as spoken recipes, not decorations. You may hear something like 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". Read the command, understand what it changes, then run it only when the repository state matches the lesson.

      +

      Jamie: Let's pause on Signal 3: The first H1 heading. What should a learner take away from it?

      +

      Alex: Keep the learner anchored in Signal 3: The first H1 heading. Press 1 (in Browse Mode) on any GitHub page to jump to the first H1 heading. This is the part to say slowly: What you hear tells you what type of page you are on.

      +

      Alex: Another way to ground it. The reason Page Type 1: Repository Home (Code Tab) matters is that this is the central hub of any project. That gives the learner a simple foothold: it is where you find the file tree, the README, branch information, and links to all other parts of the repository.

      +

      Jamie: Let's pause on What to expect. What should a learner take away from it?

      +

      Alex: Start with What to expect. There is something to understand, something to try, and something that proves the try worked.

      +

      Alex: A few details make that real. 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.

      -

      Jamie: If I am listening before the workshop starts, what should settle in my mind first?

      -

      Alex: The reason Open vs Closed filter matters is that the two state links "Open" and "Closed" appear near the top of the issue list. That gives the learner a simple foothold: press K to navigate links until you find them, or look for them as buttons near the search bar.

      -

      Alex: Now bring the learner back to the room. Start with Learning Cards: Filtering and Searching Issues. There is something to understand, something to try, and something that proves the try worked.

      -

      Alex: The practical takeaway is this. 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. 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.

      -

      Jamie: Where do you want a learner to place their attention here?

      -

      Alex: Here is the plain-English version of Landing on an issue page. When you open an issue, the page structure is.

      +

      Alex: This is the part worth saying out loud. Here is the plain-English version of Page Type 2: Issues List. A searchable, filterable list of all issues in the repository. It is like learning a transit route. The names of the stops matter because they tell you whether you are still going the right direction.

      +

      Jamie: Before we leave What to expect, what is the practical point?

      +

      Alex: That shows up in the workshop in a few specific ways. 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".

      +

      Alex: The next layer is this. Keep the learner anchored in Page Type 3: Issue Detail. The full view of a single issue: the original report, all comments, labels, assignees, and the timeline.

      -

      Jamie: Let's pause on Reading the issue description. What should a learner take away from it?

      -

      Alex: This is where Reading the issue description becomes real: browse Mode recommended: The issue detail page is primarily text-based. That matters in practice: Stay in Browse Mode (not Focus Mode) for reading - it gives you full heading (H), section (D), and link (K) navigation throughout the page.

      -

      Alex: First, press 2 to reach the "Description" heading. Then, press ↓ to read the content line by line,. After that, use NVDA+↓ (NVDA say all) to have it read continuously. It is a checklist, but a meaningful one: every item creates evidence that the next step is safe.

      -

      Alex: Treat examples as spoken recipes, not decorations. You may hear something like 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. Read the command, understand what it changes, then run it only when the repository state matches the lesson.

      -

      Jamie: Give me the version that sounds like an instructor, not a manual.

      -

      Alex: Keep the learner anchored in Reading comments and activity. Each comment in the thread is marked as an h3. This is the part to say slowly: Other timeline events (label added, PR linked, issue closed) appear between comments in the activity stream.

      -

      Alex: The practical takeaway is this. Commenter's username. Timestamp ("2 days ago"). Body text. Reactions (if any - announced as a button with an emoji and count).

      -

      Alex: That matters because of the next idea. Start with Learning Cards: Reading an Issue. There is something to understand, something to try, and something that proves the try worked.

      -

      Alex: The practical takeaway is this. 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. 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.

      +

      Jamie: What is the teaching move inside What to expect?

      +

      Alex: That becomes easier when you listen for these cues. 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.

      +

      Alex: Keep the teaching thread moving. Start with 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. Think of it like entering a new building: first you find the lobby, then the room, then the door you actually need.

      +

      Jamie: If someone only remembers one thing from What to expect, what should it be?

      +

      Alex: The practical takeaway is this. 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.

      -

      Jamie: Let's pause on Step-by-step. What should a learner take away from it?

      -

      Alex: Start with Step-by-step: To close the issue while commenting: click the arrow on the Close issue button and choose Close with comment. The next useful detail is this: Low vision users (zoom, high contrast).

      -

      Alex: First, scroll to the bottom of the issue page. Then, click in the Leave a comment text area. After that, type your comment (Markdown is supported - use the toolbar buttons above the text for bold, italic, code, etc.). Finally, optionally click Preview to see how it will render. Think of it as a rail line: each stop confirms you are still on the right route before the next one.

      -

      Jamie: Before we leave Step-by-step, what is the practical point?

      -

      Alex: First, click the green Comment button to post. Then, scroll to the bottom to find the Leave a comment text area. At 200%+ zoom, this may require significant scrolling past the timeline. After that, the text area expands as you type. The formatting toolbar above it (bold, italic, code, etc.) wraps at high zoom but remains functional. Finally, the Preview tab next to Write lets you check Markdown rendering before posting. Treat it like a recipe: do not add the next ingredient until the previous one is actually in the bowl.

      -

      Alex: Treat examples as spoken recipes, not decorations. You may hear something like 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.". Read the command, understand what it changes, then run it only when the repository state matches the lesson.

      -

      Alex: Keep the teaching thread moving. Here is the plain-English version of Markdown formatting while typing. These keyboard shortcuts work inside the text area (Focus Mode).

      -

      Jamie: Let's pause on GitHub shortcuts for the Issues pages. What should a learner take away from it?

      -

      Alex: This is where GitHub shortcuts for the Issues pages becomes real: these are the GitHub built-in shortcuts for working with issues. That matters in practice: Enable Focus Mode first (NVDA: NVDA+Space, JAWS: Insert+Z) before using single-key shortcuts.

      +

      Alex: Keep the teaching thread moving. This is where Page Type 5: Your Personal Feed and Profile becomes real: your personal home (github.com) shows activity from repositories you follow. That matters in practice: Your profile (github.com/username) shows your contribution graph, pinned repos, and bio.

      +

      Jamie: Let's pause on What to expect on your feed. What should a learner take away from it?

      +

      Alex: Start with What to expect on your feed. There is something to understand, something to try, and something that proves the try worked.

      +

      Alex: The practical takeaway is this. A "For you" activity stream - recent activity from repos you watch. A sidebar of suggested repositories and topics.

      +

      Alex: Keep the teaching thread moving. Start with What to expect on your profile. There is something to understand, something to try, and something that proves the try worked.

      +

      Alex: The practical takeaway is this. 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.

      -

      Alex: Keep the teaching thread moving. Keep the learner anchored in On the Issues list page. Shortcut note: For G I, press G, release it, then press I (two sequential key presses, not simultaneous). A good GitHub workflow is like a well-run meeting: everyone knows the topic, the next action, and who has the floor.

      -

      Jamie: Let's pause on On an open issue. What should a learner take away from it?

      -

      Alex: The reason On an open issue matters is that r to quote is a power move: Select any text in a comment while in Browse Mode (Shift+Arrow to select), then press R. That gives the learner a simple foothold: GitHub puts the quoted text in the comment box as a Markdown blockquote.

      -

      Alex: First, navigate to your comment (3 to jump to comments). Then, find the "." (ellipsis) menu button near your comment. After that, press Enter on "Edit" from that menu. Finally, the comment turns into a text area - switch to Focus Mode. The rhythm is simple: orient, act, verify, then continue.

      -

      Jamie: Before we leave On an open issue, what is the practical point?

      -

      Alex: First, make your changes. Then, tab to "Update comment" button → Enter. Think of it as a rail line: each stop confirms you are still on the right route before the next one.

      -

      Alex: Keep the teaching thread moving. Start with Learning Cards: Leaving a Comment. There is something to understand, something to try, and something that proves the try worked.

      -

      Alex: The practical takeaway is this. 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. 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.

      +

      Jamie: Let's pause on Learning Cards: The Five Key Page Types. What should a learner take away from it?

      +

      Alex: Start with Learning Cards: The Five Key Page Types. There is something to understand, something to try, and something that proves the try worked.

      +

      Alex: The practical takeaway is this. 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. 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.

      +

      Alex: Keep the teaching thread moving. Here is the plain-English version of 5. Visual Map of a Repository Page. See also: Appendix A: Glossary defines every term used in this course. Put another way, appendix B: Screen Reader Cheat Sheet has quick-reference keyboard shortcuts for navigating headings and landmarks.

      +

      Jamie: Let's pause on Description. What should a learner take away from it?

      +

      Alex: This is where Description becomes real: a repository home page is laid out from top to bottom as follows. That matters in practice: The Global Navigation bar (landmark: "Navigation Menu") contains the GitHub logo, Search, Copilot, Pull Requests, Issues, Notifications bell, and your avatar.

      -

      Jamie: Let's pause on Navigating to New Issue. What should a learner take away from it?

      -

      Alex: Here is the plain-English version of Navigating to New Issue. From the Issues list page, click the green New issue button in the top-right of the issue list. Put another way, 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.

      -

      Alex: The practical takeaway is this. 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.

      -

      Alex: First, press K to navigate links and find the "New issue" button/link. Then, press Enter. After that, 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. Finally, quick Nav B or VO+U → Buttons to find the "New issue" button. Treat it like a recipe: do not add the next ingredient until the previous one is actually in the bowl.

      -

      Jamie: Before we leave Navigating to New Issue, what is the practical point?

      -

      Alex: First, vO+Space to activate it. Then, 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. It is a checklist, but a meaningful one: every item creates evidence that the next step is safe.

      -

      Alex: Keep the teaching thread moving. This is where Filling Out the Issue Form becomes real: the issue form has these fields (order may vary depending on the template). The workshop is closer to rehearsal than lecture. You hear the move, try the move, and then check what changed.

      -

      Jamie: Let's pause on Title field. What should a learner take away from it?

      -

      Alex: Start with Title field. There is something to understand, something to try, and something that proves the try worked.

      -

      Alex: First, find the Title input field (F or by landmark). Then, focus Mode → type a clear, specific title. After that, good title: "Screen reader announces wrong element count on Issues list with 50+ items". Finally, bad title: "Bug with screen reader". It is like walking a hallway with named doors: read the sign, enter the right room, then confirm where you landed.

      +

      Alex: Keep the teaching thread moving. Keep the learner anchored in Screen reader navigation of this page. Press 1 to hear "owner/repo-name" (the H1, confirms you are on the right repo). This is the part to say slowly: Press D to hear "Navigation Menu," then D again for "Repository navigation," then D again for "Main" (the file tree area). A good GitHub workflow is like a well-run meeting: everyone knows the topic, the next action, and who has the floor.

      +

      Jamie: What is the ordered workflow?

      +

      Alex: The reason 6. Screen Reader Orientation Sequence matters is that do this every time you land on a new GitHub page. That gives the learner a simple foothold: it takes about 10 seconds once you are practiced.

      +

      Alex: The practical takeaway is this. 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).

      +

      Alex: First, browser tab title - tells you the page type and repo context. Then, global nav bar (top strip) - GitHub logo, search box, bells/icons. After that, repo tabs (below global nav, visible only inside a repo) - Code, Issues, Pull Requests, etc. Finally, h1 heading - tells you exactly what page you're on (repo name / "Issues" / issue title / PR title). The rhythm is simple: orient, act, verify, then continue.

      +

      Jamie: Give me the sequence, because order matters here.

      +

      Alex: First, main content area - file tree, issue list, PR diff, etc. Think of it as a rail line: each stop confirms you are still on the right route before the next one.

      +

      Alex: Keep the teaching thread moving. Start with Learning Cards: Screen Reader Orientation Sequence. There is something to understand, something to try, and something that proves the try worked.

      +

      Alex: The practical takeaway is this. 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. 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.

      -

      Jamie: Let's pause on Description / Body field. What should a learner take away from it?

      -

      Alex: Start with Description / Body field. There is something to understand, something to try, and something that proves the try worked.

      -

      Alex: First, tab to the body text area. Then, focus Mode → type using the Markdown template provided. After that, if no template, use this structure. The rhythm is simple: orient, act, verify, then continue.

      -

      Alex: Treat examples as spoken recipes, not decorations. You may hear something like 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. Read the command, understand what it changes, then run it only when the repository state matches the lesson.

      -

      Jamie: Let's pause on Assigning labels from the sidebar. What should a learner take away from it?

      -

      Alex: Start with Assigning labels from the sidebar: See also: Chapter 09: Labels, Milestones, and Projects covers the full label and milestone system. The next useful detail is this: While the form is open, the sidebar has dropdowns for Labels, Assignees, and Milestone.

      -

      Alex: First, tab away from the text area (or press Escape to leave Focus Mode). Then, navigate to the sidebar - press H to find "Labels" heading. After that, press Enter on the Labels gear/button. Finally, dropdown opens → ↑/↓ to navigate labels. Think of it as a rail line: each stop confirms you are still on the right route before the next one.

      -

      Jamie: Before we leave Assigning labels from the sidebar, what is the practical point?

      -

      Alex: First, enter to select/deselect. Then, escape to close (selections save automatically). After that, vO+Shift+Up to stop interacting with the text area. Finally, vO+U → Headings to find the "Labels" heading in the sidebar. Treat it like a recipe: do not add the next ingredient until the previous one is actually in the bowl.

      -

      Alex: A solid project habit is to treat metadata as decision support. Labels, status, assignees, and notifications tell you what kind of attention the work needs.

      -

      Jamie: Let's pause on Submitting the issue. What should a learner take away from it?

      -

      Alex: Here is the plain-English version of Submitting the issue. GitHub CLI (gh) alternative - filing a new issue. Put another way, create an issue from your terminal. It is like learning a transit route. The names of the stops matter because they tell you whether you are still going the right direction.

      -

      Alex: First, tab to "Submit new issue" button. Then, press Enter. Treat it like a recipe: do not add the next ingredient until the previous one is actually in the bowl.

      -

      Alex: Treat examples as spoken recipes, not decorations. You may hear something like 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. Read the command, understand what it changes, then run it only when the repository state matches the lesson.

      +

      Jamie: Let's pause on 7. Landmark Structure by Page Type. What should a learner take away from it?

      +

      Alex: Here is the plain-English version of 7. Landmark Structure by Page Type. Each GitHub page type has a consistent landmark pattern. Put another way, knowing the pattern means you can skip steps 2 and 3 above for familiar pages.

      +

      Alex: Keep the teaching thread moving. This is where 8. GitHub's Heading Hierarchy in Practice becomes real: GitHub uses a predictable heading structure. That matters in practice: Learning this pattern means you can navigate any page by heading level alone. The workshop is closer to rehearsal than lecture. You hear the move, try the move, and then check what changed.

      +

      Jamie: Let's pause on Pull request detail - Files Changed tab. What should a learner take away from it?

      +

      Alex: Keep the learner anchored in Pull request detail - Files Changed tab. 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.

      -

      Jamie: Let's pause on Learning Cards: Filing a New Issue. What should a learner take away from it?

      -

      Alex: Start with Learning Cards: Filing a New Issue. There is something to understand, something to try, and something that proves the try worked.

      -

      Alex: The practical takeaway is this. 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. 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.

      -

      Jamie: Let's pause on Tool Cards: File a New Issue. What should a learner take away from it?

      -

      Alex: Keep the learner anchored in Tool Cards: File a New Issue. github.dev (web editor): Not available -- issues are managed through the repository's Issues tab, not the code editor. This is the part to say slowly: VS Code Desktop (GitHub Pull Requests extension).

      -

      Alex: First, navigate to the repository's Issues tab (or press G then I). Then, click New issue, choose a template or blank issue. After that, fill in the title and description, then click Submit new issue. Finally, open the GitHub panel in the sidebar. It is like walking a hallway with named doors: read the sign, enter the right room, then confirm where you landed.

      -

      Jamie: Before we leave Tool Cards: File a New Issue, what is the practical point?

      -

      Alex: First, under Issues, click the + icon to create a new issue. Then, fill in the title and body, then click Create. The rhythm is simple: orient, act, verify, then continue.

      -

      Alex: Treat examples as spoken recipes, not decorations. You may hear something like gh issue create --title "Your title" --body "Description here"; Or interactively:; gh issue create. Read the command, understand what it changes, then run it only when the repository state matches the lesson.

      -

      Jamie: Let's pause on Cross-Referencing Issues. What should a learner take away from it?

      -

      Alex: The reason Cross-Referencing Issues matters is that linking issues and PRs to each other creates a trail of context that helps everyone understand the project's history.

      +

      Alex: Keep the teaching thread moving. Start with Learning Cards: GitHub's Heading Hierarchy. There is something to understand, something to try, and something that proves the try worked.

      +

      Alex: The practical takeaway is this. 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. 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.

      +

      Jamie: Let's pause on 9. How GitHub's Layout Changes by Viewport. What should a learner take away from it?

      +

      Alex: Start with 9. How GitHub's Layout Changes by Viewport: GitHub is a responsive web application. The next useful detail is this: The layout shifts at different screen widths, and this affects what landmarks and headings you encounter.

      +

      Alex: Keep the teaching thread moving. Start with At full desktop width (1200px+). There is something to understand, something to try, and something that proves the try worked.

      +

      Alex: The practical takeaway is this. File tree and sidebar are visible alongside the main content. The full repository tab bar is visible. All landmark regions described above are present.

      -

      Alex: Keep the teaching thread moving. Start with 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. Think of it like entering a new building: first you find the lobby, then the room, then the door you actually need.

      -

      Jamie: Let's pause on Mentioning another issue in a comment. What should a learner take away from it?

      -

      Alex: Here is the plain-English version of Mentioning another issue in a comment. Simply type followed by a number anywhere in a comment body. Put another way, GitHub autocompletes with a dropdown of matching issues and PRs.

      -

      Alex: Keep the teaching thread moving. This is where Cross-repo references becomes real: owner/repo 42 - references issue 42 in a different repository.

      +

      Jamie: Let's pause on At tablet width (768-1199px). What should a learner take away from it?

      +

      Alex: Start with At tablet width (768-1199px). There is something to understand, something to try, and something that proves the try worked.

      +

      Alex: The practical takeaway is this. 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.

      +

      Alex: Keep the teaching thread moving. Keep the learner anchored in At mobile width (below 768px). Consistent experience recommendation: Use your browser maximized or at full desktop width during this workshop. This is the part to say slowly: GitHub's landmark and heading structure is most consistent at desktop width.

      +

      Alex: The practical takeaway is this. 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.

      +

      Jamie: Turn that into a path someone can follow.

      +

      Alex: The reason 10. The Mental Model - Building Your Internal Map matters is that after your first day of using GitHub, you will have an internal map. That gives the learner a simple foothold: here is what that map should look like.

      +

      Alex: First, press 1 - hear the H1 - know what floor you are on. Then, press D - hear the landmarks - know what rooms are available. After that, press NVDA+F7 - see the full outline - know what's in the room. The rhythm is simple: orient, act, verify, then continue.

      -

      Jamie: Let's pause on Learning Cards: Cross-Referencing Issues. What should a learner take away from it?

      -

      Alex: Start with Learning Cards: Cross-Referencing Issues. There is something to understand, something to try, and something that proves the try worked.

      -

      Alex: The practical takeaway is this. 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. 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.

      -

      Alex: Keep the teaching thread moving. The reason Sub-Issues - Parent and Child Relationships matters is that sub-issues (released 2025) let you nest issues inside a parent issue to break large work into tracked pieces. That gives the learner a simple foothold: a "parent" issue contains a list of child issues; each child is a full issue with its own discussion, labels, and assignees. The interface gets friendlier when it stops being a wall of controls and starts being a set of named places.

      -

      Jamie: Can you translate that into plain choices?

      -

      Alex: Start with When to Use Sub-Issues. There is something to understand, something to try, and something that proves the try worked.

      -

      Alex: Use the comparison to make a decision, not to recite a table. The main contrasts are: Large feature broken down means Parent: "Redesign navigation"; Children: "Keyboard nav," "Screen reader nav," "Mobile nav". Epic tracking means Parent: "WCAG 2.1 AA compliance"; Children: one issue per failing criterion. Release milestone means Parent: "v2.0 release"; Children: every required PR/fix.

      +

      Alex: Keep the teaching thread moving. Start with Learning Cards: Building Your Internal Map. There is something to understand, something to try, and something that proves the try worked.

      +

      Alex: The practical takeaway is this. 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. 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.

      +

      Jamie: Let's pause on Try It: The 60-Second Orientation. What should a learner take away from it?

      +

      Alex: Here is the plain-English version of Try It: The 60-Second Orientation. Time: 1 minute What you need: A browser with your screen reader running. Put another way, open any GitHub repository - try github.com/community-access/accessibility-agents - and prove to yourself that the mental model works.

      +

      Alex: First, press 1 - your screen reader announces the repo name. You know where you are. Then, press D - you hear the first landmark. Press D again to hear the next one. You now know the rooms on this floor. After that, press 2 - you jump to the first section heading. Press 2 again to scan the page structure. Finally, press H three times - you're moving through headings at any level. You're reading the outline. Treat it like a recipe: do not add the next ingredient until the previous one is actually in the bowl.

      +

      Alex: Keep the teaching thread moving. This is where Day 2 Amplifier becomes real: once you have this mental model solid, the Accessibility Agents make more sense. That matters in practice: 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.

      -

      Alex: Keep the teaching thread moving. Here is the plain-English version of Creating a Sub-Issue. The sub-issues section is announced as a region. Put another way, after linking, the child issue appears as a list item with a checkbox showing its open/closed state.

      -

      Jamie: Let's pause on Reading Sub-Issues on a Parent Issue. What should a learner take away from it?

      -

      Alex: This is where Reading Sub-Issues on a Parent Issue becomes real: progress indicator: The parent issue shows a completion bar (e.g., "3 of 7 completed") based on how many child issues are closed. That matters in practice: Screen readers announce this as a progress region.

      -

      Alex: Keep the teaching thread moving. Keep the learner anchored in Viewing a Child Issue's Parent. Every child issue shows a "Parent issue" link near the top of the page (above the description). This is the part to say slowly: Navigate with H or links (K) to find it. A good GitHub workflow is like a well-run meeting: everyone knows the topic, the next action, and who has the floor.

      +

      Jamie: Let's pause on A Screen Reader Guide to GitHub Repositories. What should a learner take away from it?

      +

      Alex: Keep the learner anchored in A Screen Reader Guide to GitHub Repositories. everything you need to explore a GitHub repository using your keyboard and screen reader. This is the part to say slowly: 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.

      +

      Alex: Keep the teaching thread moving. The reason Workshop Recommendation (Chapter 3) matters is that chapter 3 is a confidence-building orientation chapter. The interface gets friendlier when it stops being a wall of controls and starts being a set of named places.

      +

      Alex: The practical takeaway is this. There are none. Automation check: none. Why: this chapter teaches navigation foundations that are practiced in later issue and PR chapters.

      +

      Jamie: Let's pause on Safety-First Learning Pattern. What should a learner take away from it?

      +

      Alex: Start with Safety-First Learning Pattern: Use this sequence before moving to graded chapters.

      +

      Alex: First, learn the page structure (heading, landmarks, tabs). Then, practice orientation (1, D, heading list). After that, confirm readiness with a peer or facilitator. Finally, move to Chapter 4 for Learning Room orientation, then Chapter 5 for issue-based, traceable challenges. Think of it as a rail line: each stop confirms you are still on the right route before the next one.

      -

      Jamie: Let's pause on Sub-Issues vs. Task Lists. What should a learner take away from it?

      -

      Alex: The reason Sub-Issues vs. Task Lists matters is that if you are working on a feature that requires multiple PRs or involves several team members, ask the maintainer to create a parent issue. That gives the learner a simple foothold: you can then claim individual child issues without one person owning the whole feature.

      -

      Alex: Keep the teaching thread moving. Start with Learning Cards: Sub-Issues. There is something to understand, something to try, and something that proves the try worked.

      -

      Alex: The practical takeaway is this. 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. 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.

      -

      Jamie: Let's pause on Closing an issue. What should a learner take away from it?

      -

      Alex: Here is the plain-English version of Closing an issue. Scroll to the bottom of the issue page. Put another way, click the Close issue button next to the comment box.

      -

      Alex: First, 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. Then, button approach: Tab to the "Close issue" button (at the bottom of the page, near the comment box) and press Enter. After that, optionally leave a closing comment first. Finally, 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. Treat it like a recipe: do not add the next ingredient until the previous one is actually in the bowl.

      -

      Jamie: Before we leave Closing an issue, what is the practical point?

      -

      Alex: First, button approach: Quick Nav B or Tab to find the "Close issue" button, then VO+Space. It is a checklist, but a meaningful one: every item creates evidence that the next step is safe.

      -

      Alex: Treat examples as spoken recipes, not decorations. You may hear something like 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. Read the command, understand what it changes, then run it only when the repository state matches the lesson.

      +

      Alex: Keep the teaching thread moving. Here is the plain-English version of About Learning Cards in This Chapter. This chapter provides learning cards: expandable blocks that offer perspective-specific guidance for different ways of working. Put another way, not every card appears at every step.

      +

      Jamie: Let's pause on What Is a Repository Page? What should a learner take away from it?

      +

      Alex: This is where What Is a Repository Page? becomes real: 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). That matters in practice: This page has several distinct regions.

      +

      Alex: Keep the teaching thread moving. Keep the learner anchored in Description. The repository home page is organized from top to bottom as follows. This is the part to say slowly: The Navigation bar (GitHub global nav) contains the avatar menu, Notifications, and search. A good GitHub workflow is like a well-run meeting: everyone knows the topic, the next action, and who has the floor.

      -

      Alex: Keep the teaching thread moving. This is where Reopening a closed issue becomes real: if an issue is Closed, the "Close issue" button becomes "Reopen issue" - navigate and activate to reopen. The workshop is closer to rehearsal than lecture. You hear the move, try the move, and then check what changed.

      -

      Jamie: Let's pause on Assigning an issue. What should a learner take away from it?

      -

      Alex: Keep the learner anchored in Assigning an issue. GitHub CLI (gh) alternative - assigning and labeling. This is the part to say slowly: Manage assignments and labels from your terminal.

      -

      Alex: First, navigate to "Assignees" heading (3 or H). Then, activate the gear/plus button. After that, type a username in the search field. Finally, select from the dropdown. It is like walking a hallway with named doors: read the sign, enter the right room, then confirm where you landed.

      -

      Alex: Treat examples as spoken recipes, not decorations. You may hear something like 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". Read the command, understand what it changes, then run it only when the repository state matches the lesson.

      -

      Jamie: Let's pause on Changing labels. What should a learner take away from it?

      -

      Alex: Start with Changing labels. There is something to understand, something to try, and something that proves the try worked.

      -

      Alex: First, navigate to "Labels" heading. Then, activate the gear button. After that, select/deselect labels from the dropdown. Finally, press Escape to save. The rhythm is simple: orient, act, verify, then continue.

      +

      Jamie: Let's pause on Landing on a Repository - What to Expect. What should a learner take away from it?

      +

      Alex: The reason Landing on a Repository - What to Expect matters is that when you first navigate to a repo URL.

      +

      Alex: First, the page title is announced with the format: owner/repo-name: Short description - GitHub. Then, first heading (1 key) will navigate to the repo name: "owner/repo-name". After that, the tab bar is a landmark labeled "Repository navigation". The rhythm is simple: orient, act, verify, then continue.

      +

      Jamie: What should happen before anyone copies and runs it?

      +

      Alex: Start with Orientation sequence (do this on every new repo): 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. The next useful detail is this: Within each landmark, press H or 2 to navigate subsections - most are organized under heading level 2.

      +

      Alex: Treat examples as spoken recipes, not decorations. You may hear something like 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. Read the command, understand what it changes, then run it only when the repository state matches the lesson.

      +

      Jamie: Let's pause on Navigating the Repository Tabs. What should a learner take away from it?

      +

      Alex: Here is the plain-English version of 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). Put another way, not all tabs appear on every repository - Discussions, Wiki, and Projects must be enabled by the repository owner.

      -

      Jamie: Let's pause on Transferring or deleting an issue. What should a learner take away from it?

      -

      Alex: Start with Transferring or deleting an issue: Available from the "." (ellipsis) button at the top of the issue - navigate buttons with B to find it.

      -

      Alex: Keep the teaching thread moving. Start with Learning Cards: Managing Issues. There is something to understand, something to try, and something that proves the try worked.

      -

      Alex: The practical takeaway is this. 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. 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.

      -

      Jamie: Let's pause on The "good first issue" Label - Your Entry Point. What should a learner take away from it?

      -

      Alex: This is where The "good first issue" Label - Your Entry Point becomes real: when looking for your first open source contribution. That matters in practice: Remember: It's respectful to ask before starting.

      -

      Alex: First, navigate to any project's Issues tab. Then, filter by label: type is:open label:"good first issue" in the search. After that, read through issues until you find one in your area of interest. Finally, comment on the issue: "Hi, I'd like to work on this. Can I be assigned?". It is a checklist, but a meaningful one: every item creates evidence that the next step is safe.

      -

      Jamie: Before we leave The "good first issue" Label - Your Entry Point, what is the practical point?

      -

      Alex: First, wait for a maintainer to respond and assign you before starting work. It is like walking a hallway with named doors: read the sign, enter the right room, then confirm where you landed.

      +

      Jamie: Let's pause on How to reach the tabs. What should a learner take away from it?

      +

      Alex: This is where How to reach the tabs becomes real: the tab bar is visible just below the repository name. That matters in practice: Click the tab you want - Code, Issues, Pull requests, etc. The workshop is closer to rehearsal than lecture. You hear the move, try the move, and then check what changed.

      +

      Alex: The practical takeaway is this. 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.

      +

      Alex: First, press D to jump to the "Repository navigation" landmark. Then, press K or Tab to navigate between the tab links. After that, vO+U → Landmarks rotor → navigate to "Repository navigation". Finally, vO+Right to move through items in the landmark. It is a checklist, but a meaningful one: every item creates evidence that the next step is safe.

      +

      Jamie: Let's pause on Reading the tab labels. What should a learner take away from it?

      +

      Alex: Keep the learner anchored in 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.".

      +

      Alex: A solid project habit is to treat metadata as decision support. Labels, status, assignees, and notifications tell you what kind of attention the work needs.

      +

      Alex: Keep the teaching thread moving. The reason The Files Table matters is that see also: Appendix B: Screen Reader Cheat Sheet lists the keyboard shortcuts for navigating repository file trees. That gives the learner a simple foothold: the files table is the core of the Code tab - it shows every file and folder in the repo.

      -

      Alex: Keep the teaching thread moving. Start with Learning Cards: The "good first issue" Label. There is something to understand, something to try, and something that proves the try worked.

      -

      Alex: The practical takeaway is this. 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. 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.

      -

      Jamie: Let's pause on Accessibility-Specific Issue Writing Tips. What should a learner take away from it?

      -

      Alex: The reason Accessibility-Specific Issue Writing Tips matters is that when filing accessibility bugs, these details help maintainers reproduce and fix the problem.

      -

      Alex: First, screen reader and version - "NVDA 2025.3.3" not just "screen reader". Then, oS and version - "Windows 11 22H2". After that, browser and version - "Chrome 124.0.6367.82". Finally, GitHub interface - "Modern experience (default since Jan 2026)" or "Classic experience (opted out)". The rhythm is simple: orient, act, verify, then continue.

      -

      Jamie: Before we leave Accessibility-Specific Issue Writing Tips, what is the practical point?

      -

      Alex: First, what was announced - quote the exact text your screen reader spoke. Then, what should have been announced - describe the expected behavior. After that, aRIA issue if known - e.g., "The button has no accessible name". Finally, steps to reproduce - numbered, step-by-step. Think of it as a rail line: each stop confirms you are still on the right route before the next one.

      -

      Alex: Keep the teaching thread moving. Start with Example of a well-filed accessibility issue. There is something to understand, something to try, and something that proves the try worked.

      +

      Jamie: Let's pause on Reaching the files table. What should a learner take away from it?

      +

      Alex: Start with Reaching the files table: 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. The next useful detail is this: It's visible immediately below the branch selector.

      +

      Alex: The practical takeaway is this. 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.

      +

      Alex: First, name - file or folder name. Then, message - the most recent commit message that changed this file. After that, age - how long ago that commit happened. Think of it as a rail line: each stop confirms you are still on the right route before the next one.

      +

      Alex: Keep the teaching thread moving. Here is the plain-English version of 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. Put another way, for example: "docs/ Add accessibility guide 3 days ago". It is like learning a transit route. The names of the stops matter because they tell you whether you are still going the right direction.

      +

      Jamie: Let's pause on Folder vs file. What should a learner take away from it?

      +

      Alex: Start with Folder vs file. There is something to understand, something to try, and something that proves the try worked.

      +

      Alex: The practical takeaway is this. 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.

      -

      Jamie: Let's pause on Learning Cards: Accessibility-Specific Issue Writing. What should a learner take away from it?

      -

      Alex: Start with Learning Cards: Accessibility-Specific Issue Writing. There is something to understand, something to try, and something that proves the try worked.

      -

      Alex: The practical takeaway is this. 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. 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.

      -

      Alex: Keep the teaching thread moving. This is where Writing Effective Issues becomes real: see also: Appendix N: Advanced Search covers search qualifiers to find existing issues before filing a new one. That matters in practice: 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.

      -

      Jamie: Let's pause on Bug Report Structure. What should a learner take away from it?

      -

      Alex: Keep the learner anchored in Bug Report Structure. A strong bug report answers five questions. This is the part to say slowly: Use this template every time you report something broken.

      +

      Alex: Keep the teaching thread moving. Start with Learning Cards: The Files Table. There is something to understand, something to try, and something that proves the try worked.

      +

      Alex: The practical takeaway is this. 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. 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.

      +

      Jamie: Let's pause on The Branch Selector. What should a learner take away from it?

      +

      Alex: The reason The Branch Selector matters is that the branch selector button sits just above the files table. That gives the learner a simple foothold: it lets you switch which branch you are viewing.

      +

      Jamie: Let's pause on How to open the branch selector. What should a learner take away from it?

      +

      Alex: Start with How to open the branch selector: Mouse users see the current branch name as a button with a dropdown arrow (e.g., main ▼) just above the file table. The next useful detail is this: Type to filter branches, then click a branch name to switch. Think of it like entering a new building: first you find the lobby, then the room, then the door you actually need.

      +

      Alex: The practical takeaway is this. 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.

      +

      Alex: First, after reaching the repository navigation landmark, press B to navigate to buttons. Then, the branch button reads: "[branch-name] branch" (e.g., "main branch"). After that, press Enter to open the dropdown. Finally, tab to the branch button (it will be labeled with the current branch name). Think of it as a rail line: each stop confirms you are still on the right route before the next one.

      +

      Jamie: Before we leave How to open the branch selector, what is the practical point?

      +

      Alex: First, vO+Space to open. Treat it like a recipe: do not add the next ingredient until the previous one is actually in the bowl.

      -

      Jamie: Let's pause on Feature Request Structure. What should a learner take away from it?

      -

      Alex: The reason Feature Request Structure matters is that feature requests work best when they focus on the problem before jumping to the solution. That gives the learner a simple foothold: 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. The interface gets friendlier when it stops being a wall of controls and starts being a set of named places.

      -

      Alex: First, problem statement -- Describe the pain point. What are you trying to do, and why is it hard or impossible right now? Then, proposed solution -- Your best idea for fixing the problem. Be specific enough to discuss, but hold it loosely. After that, alternatives considered -- Other approaches you thought about and why they fell short. This shows you have done your homework. Finally, who benefits -- Name the audience. "Screen reader users navigating large repositories" is more compelling than "everyone.". The rhythm is simple: orient, act, verify, then continue.

      -

      Jamie: Let's pause on General Issue Writing Principles. What should a learner take away from it?

      -

      Alex: Start with General Issue Writing Principles: These rules apply to every issue -- bugs, features, questions, and everything in between. The next useful detail is this: If you discovered two bugs during the same session, file two separate issues.

      -

      Alex: Keep the teaching thread moving. Here is the plain-English version of Before and After: A Vague Issue vs. a Clear Issue. I tried clicking and nothing happened. Put another way, the maintainer has to ask: What doesn't work?

      +

      Jamie: Let's pause on Inside the branch dropdown. What should a learner take away from it?

      +

      Alex: Here is the plain-English version of Inside the branch dropdown. 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. Put another way, VoiceOver: After activating the button, VO+Down to interact with the dropdown → VO+Right to navigate items.

      +

      Jamie: Let's pause on Switching to a tag. What should a learner take away from it?

      +

      Alex: This is where Switching to a tag becomes real: tags mark specific releases or versions. That matters in practice: The branch dropdown also provides tag navigation.

      +

      Alex: First, open the branch button (same steps as above). Then, inside the dropdown, navigate to the tabs control at the top (reads as "Branches tab" and "Tags tab"). After that, use ←/→ to switch to the Tags tab. Finally, tab to move to the tags list. It is a checklist, but a meaningful one: every item creates evidence that the next step is safe.

      +

      Jamie: Before we leave Switching to a tag, what is the practical point?

      +

      Alex: First, navigate with ↑/↓ and press Enter to select a tag. It is like walking a hallway with named doors: read the sign, enter the right room, then confirm where you landed.

      +

      Jamie: Let's pause on Cloning a Repository. What should a learner take away from it?

      +

      Alex: Keep the learner anchored in Cloning a Repository. Cloning copies the repository to your local machine so you can work with it in VS Code or the terminal. This is the part to say slowly: Alternative: Tab further to find Download ZIP if you want a one-time copy without Git.

      +

      Alex: First, on the repository's main page (Code tab), find and click the green Code button above the file table. Then, a popover opens showing HTTPS, SSH, and GitHub CLI tabs. After that, click the HTTPS tab (default) and click the copy icon next to the URL. Finally, open your terminal, cd to where you want the folder, and run git clone. It is like walking a hallway with named doors: read the sign, enter the right room, then confirm where you landed.

      +

      Jamie: Before we leave Cloning a Repository, what is the practical point?

      +

      Alex: First, alternatively, click Download ZIP to get a one-time archive without Git. Then, press 1 or Shift+1 to navigate to the repository h1 heading. After that, press B to navigate to the next button - look for the "Code" button. Finally, press Enter or Space to open the Code flyout panel. The rhythm is simple: orient, act, verify, then continue.

      +

      Alex: Treat examples as spoken recipes, not decorations. You may hear something like 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. Read the command, understand what it changes, then run it only when the repository state matches the lesson.

      -

      Jamie: Let's pause on Learning Cards: Writing Effective Issues. What should a learner take away from it?

      -

      Alex: Start with Learning Cards: Writing Effective Issues. There is something to understand, something to try, and something that proves the try worked.

      -

      Alex: The practical takeaway is this. 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. 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.

      -

      Jamie: Let's pause on Try It: File Your First Issue. What should a learner take away from it?

      -

      Alex: Keep the learner anchored in Try It: File Your First Issue. Time: 3 minutes What you need: Browser, signed in to GitHub. This is the part to say slowly: Go to the Learning Room repository and file a real issue. A good GitHub workflow is like a well-run meeting: everyone knows the topic, the next action, and who has the floor.

      -

      Alex: First, navigate to the Issues tab (press G then I in Focus Mode). Then, find and activate the "New issue" button (K to links, or Tab to it). After that, in the title field, type: "Introduce myself - [Your Name]". Finally, in the description, write 2-3 sentences: who you are, what screen reader you use, and one thing you're hoping to learn today. It is like walking a hallway with named doors: read the sign, enter the right room, then confirm where you landed.

      -

      Jamie: Before we leave Try It: File Your First Issue, what is the practical point?

      -

      Alex: First, press Ctrl+Enter to submit (or Tab to the Submit button and press Enter). The rhythm is simple: orient, act, verify, then continue.

      -

      Jamie: Let's pause on Learning Cards: Filing Your First Issue. What should a learner take away from it?

      -

      Alex: The reason Learning Cards: Filing Your First Issue matters is that day 2 Amplifier - Accessibility Agents: @issue-tracker File, read, comment on, and triage real issues manually before using any agent. That gives the learner a simple foothold: 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.

      -

      Alex: The practical takeaway is this. 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. 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.

      +

      Jamie: How do you keep commands from becoming magic words?

      +

      Alex: The reason Or with standard Git matters is that setup: Install the GitHub CLI from cli.github.com and authenticate with gh auth login. The interface gets friendlier when it stops being a wall of controls and starts being a set of named places.

      +

      Alex: Treat examples as spoken recipes, not decorations. You may hear something like git clone https://github.com/community-access/git-going-with-github.git; cd git-going-with-github. Read the command, understand what it changes, then run it only when the repository state matches the lesson.

      +

      Jamie: Let's pause on Learning Cards: Cloning a Repository. What should a learner take away from it?

      +

      Alex: Start with Learning Cards: Cloning a Repository. There is something to understand, something to try, and something that proves the try worked.

      +

      Alex: The practical takeaway is this. 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. 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.

      +

      Jamie: Let's pause on Tool Cards: Clone a Repository. What should a learner take away from it?

      +

      Alex: Here is the plain-English version of Tool Cards: Clone a Repository. github.dev (web editor): No clone needed. Put another way, press the period key on any repository page to open it in the browser-based editor instantly.

      +

      Alex: First, click the green Code button above the file table. Then, copy the HTTPS URL. After that, you will paste this into your local tool of choice below. Finally, press Ctrl+Shift+P, type Git: Clone, press Enter. Treat it like a recipe: do not add the next ingredient until the previous one is actually in the bowl.

      +

      Jamie: Before we leave Tool Cards: Clone a Repository, what is the practical point?

      +

      Alex: First, paste the HTTPS URL and choose a local folder. Then, click Open when prompted. After that, file Clone Repository (or Ctrl+Shift+O). Finally, paste the URL or select from your GitHub account list. It is a checklist, but a meaningful one: every item creates evidence that the next step is safe.

      +

      Alex: Treat examples as spoken recipes, not decorations. You may hear something like git clone https://github.com/owner/repo.git; cd repo. Read the command, understand what it changes, then run it only when the repository state matches the lesson.

      -

      Jamie: What should people carry with them after this?

      -

      Alex: Carry the map. Know what page or tool you are in, know which action you are taking, and know what confirmation should follow. If the confirmation is missing, pause. That pause is not wasted time; it is professional judgment.

      -

      Jamie: That is a better way to say it than just follow the steps.

      -

      Alex: Right. Steps matter, but understanding wins. That is episode 5. Next in the series is episode 6, where we keep building the same contributor muscles.

      -
      - +

      Jamie: Let's pause on Fork vs. Clone vs. Branch - What Is the Difference? What should a learner take away from it?

      +

      Alex: This is where Fork vs. Clone vs. Branch - What Is the Difference? becomes real: these three concepts are related but serve different purposes. That matters in practice: Students often confuse them, so here is a side-by-side comparison.

      +

      Alex: Keep the teaching thread moving. Start with Learning Cards: Fork vs. Clone vs. Branch. There is something to understand, something to try, and something that proves the try worked.

      +

      Alex: The practical takeaway is this. 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. 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.

      +

      Jamie: Let's pause on Watching, Starring, and Forking. What should a learner take away from it?

      +

      Alex: The reason Watching, Starring, and Forking matters is that these three actions let you follow, bookmark, or copy a repository.

      -

      Episode 6: Working with Pull Requests

      -

      Creating, reviewing, commenting on, and merging pull requests.

      -

      Based on: Chapter 6: Working with Pull Requests

      -

      Audio and transcript are being regenerated for this episode.

      -
      -Read Transcript - Episode 6: Working with Pull Requests - -

      Transcript

      -

      Alex: This is Git Going with GitHub, episode 6: Working with Pull Requests. I am Alex. By the end of this episode, Working with Pull Requests should feel less like a wall of GitHub words and more like a set of moves you can trust.

      -

      Jamie: And I am Jamie. I am here for the practical questions: what should I listen for, what can go wrong, and what is the next calm move?

      +

      Jamie: Let's pause on Watching (subscribe to notifications). What should a learner take away from it?

      +

      Alex: Start with Watching (subscribe to notifications): The Watch, Star, and Fork buttons are at the top-right of the repository page, just below the global navigation bar. The next useful detail is this: Click Watch to open a dropdown of subscription options: Participating and @mentions, All Activity, or Ignore.

      +

      Alex: First, press L to navigate through list items to reach the Main landmark. Then, continue pressing L until you find the Watch button (reads as "Watch this repository"). After that, press Enter to open the subscription submenu. Finally, press ↑/↓ to browse options: Participating, All Activity, Ignore, Custom. Think of it as a rail line: each stop confirms you are still on the right route before the next one.

      +

      Jamie: Before we leave Watching (subscribe to notifications), what is the practical point?

      +

      Alex: First, press Enter to confirm. Then, 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. Treat it like a recipe: do not add the next ingredient until the previous one is actually in the bowl.

      +

      Jamie: Let's pause on Forking (create your own copy). What should a learner take away from it?

      +

      Alex: Here is the plain-English version of Forking (create your own copy). Click the Fork button (top-right, next to Watch and Star). Put another way, a page opens asking you to choose the owner and repository name for your fork.

      +

      Alex: First, press L to navigate list items in the Main landmark. Then, press I to navigate individual list items until you find "Fork your own copy". After that, press Enter to start the fork workflow. Finally, the fork creation page lets you choose the owner and repository name. Treat it like a recipe: do not add the next ingredient until the previous one is actually in the bowl.

      +

      Jamie: Before we leave Forking (create your own copy), what is the practical point?

      +

      Alex: First, tab to "Create fork" and press Enter. It is a checklist, but a meaningful one: every item creates evidence that the next step is safe.

      +

      Jamie: Let's pause on Starring (bookmarking). What should a learner take away from it?

      +

      Alex: This is where Starring (bookmarking) becomes real: the button changes to Starred with a filled star icon to confirm. That matters in practice: 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. The workshop is closer to rehearsal than lecture. You hear the move, try the move, and then check what changed.

      +

      Alex: First, press L to navigate list items in the Main landmark. Then, press I to navigate individual list items until you find "Star this repository". After that, press Enter or Space to star. Finally, the button text changes to "Unstar" on the next focus. It is a checklist, but a meaningful one: every item creates evidence that the next step is safe.

      -

      Alex: Today we are working on this: Creating, reviewing, commenting on, and merging pull requests. I want the learner to leave with a mental map, not just a remembered path through buttons.

      -

      Jamie: So the goal is understanding first, then action, then confirmation.

      -

      Alex: Right. We are building a rhythm: orient yourself, take one intentional action, then verify what changed before moving on.

      +

      Jamie: Let's pause on Viewing a Single File. What should a learner take away from it?

      +

      Alex: Keep the learner anchored in 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).

      +

      Alex: Keep the teaching thread moving. The reason Reading a Markdown file (like README.md) matters is that the README renders with full heading structure.

      +

      Alex: The practical takeaway is this. H - navigate headings within the README. T - find any tables. L - find lists. K - navigate links.

      +

      Jamie: Let's pause on Reading a code file. What should a learner take away from it?

      +

      Alex: Start with Reading a code file: Code files render as a table where each row is one line of code.

      -

      Jamie: Okay, set the room for us. What are we walking into?

      -

      Alex: Start with Creating, Reviewing, and Merging Pull Requests with a Screen Reader: See also: Chapter 15: Code Review covers the full review workflow including multi-file diffs and suggested changes. The next useful detail is this: Pull requests are where your work becomes a contribution.

      -

      Alex: A solid pull request habit is to separate three questions: what changed, why it changed, and what still needs review. That keeps the conversation useful instead of noisy.

      -

      Alex: The next layer is this. Here is the plain-English version of Workshop Recommendation (Chapter 6). Chapter 6 is the first PR-validated chapter where students convert issue work into merge-ready contributions. It is like learning a transit route. The names of the stops matter because they tell you whether you are still going the right direction.

      -

      Alex: The practical anchors are these. There are 3. Each challenge should take under 10 minutes each. The evidence is PR metadata, bot checks, and merged issue linkage. The pattern is small change - linked PR - green checks.

      -

      Jamie: What does the learner do first, second, and then after that?

      -

      Alex: This is where Chapter 6 Challenge Set becomes real: this is the first chapter where you edit files and create branches. That matters in practice: 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.

      -

      Alex: First, create one small branch change - edit a practice file on a new branch. Then, open a linked PR - use the PR template and include Closes XX. After that, pass required checks - respond to bot feedback until all required checks pass. It is a checklist, but a meaningful one: every item creates evidence that the next step is safe.

      +

      Alex: Keep the teaching thread moving. Here is the plain-English version of The file action buttons. Above the file content, there are buttons. It is like learning a transit route. The names of the stops matter because they tell you whether you are still going the right direction.

      +

      Alex: The practical takeaway is this. 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).

      +

      Jamie: Let's pause on How to reach these buttons. What should a learner take away from it?

      +

      Alex: This is where How to reach these buttons becomes real: press B from within the file area, OR use D to navigate to the "Repository files navigation" landmark.

      +

      Jamie: Let's pause on Editing a file. What should a learner take away from it?

      +

      Alex: Keep the learner anchored in Editing a file. Switch back to Browse Mode after step 6 (NVDA+Space) to use Shift+Tab more reliably to reach the commit button.

      +

      Alex: First, open the file you want to edit. Then, click the pencil icon (Edit file) in the top-right of the file content area. After that, the file opens in a web editor - click in the content area and edit. Finally, when done, scroll down to "Commit changes", type a commit message, and click the green Commit changes button. It is like walking a hallway with named doors: read the sign, enter the right room, then confirm where you landed.

      +

      Jamie: Before we leave Editing a file, what is the practical point?

      +

      Alex: First, choose "Commit directly to main" (or your branch) and confirm. Then, press K to navigate links until you find the "Edit file" link (may be labeled with a pencil icon description). After that, press Enter to activate the link - the page opens in edit mode with a code editor textarea. Finally, switch to Focus Mode: press NVDA+Space (NVDA) or Insert+Z (JAWS). The rhythm is simple: orient, act, verify, then continue.

      -

      Jamie: Turn that into a path someone can follow.

      -

      Alex: Keep the learner anchored in Challenge 6.1 Step-by-Step: Create One Small Branch Change. Edit one of the practice files and save your change on a new branch. This is the part to say slowly: your Learning Room repository on GitHub.com, using the web editor.

      -

      Alex: For a learner, the useful signals are these. 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. 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.

      -

      Alex: First, 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). Then, open the file and activate the pencil icon (Edit this file) button. After that, the file opens in the web editor. Make your change. For. Finally, keep your change small and focused. Edit only what the issue asks for. It is like walking a hallway with named doors: read the sign, enter the right room, then confirm where you landed.

      -

      Jamie: What is the ordered workflow?

      -

      Alex: First, after editing, activate the Commit changes button (green button above the editor). Then, a dialog appears. In the Branch name field, type: fix/yourname-issueXX (replace yourname with your GitHub username, and XX with the issue number). After that, select Create a new branch for this commit and start a pull request. Finally, activate Propose changes. The rhythm is simple: orient, act, verify, then continue.

      -

      Alex: A solid Git habit is to know which branch you are on, what changed, and what confirmation you expect before you run the next command.

      -

      Jamie: Give me the sequence, because order matters here.

      -

      Alex: The reason Challenge 6.2 Step-by-Step: Open a Linked PR matters is that AI agents do not just deploy code directly; they submit pull requests. That gives the learner a simple foothold: learning to edit a file, format it in Markdown, and review a PR today prepares you to audit and approve AI-generated changes tomorrow.

      -

      Alex: The parts worth keeping in working memory are these. "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". A summary of what you changed and why (at least 50 characters).

      -

      Alex: First, in the Title field, write a short description of your change. Then, in the Body field, use the PR template if one is provided. Make sure to. After that, verify the base branch is main and the compare branch is your fix/yourname-issueXX branch. Finally, activate the Create pull request button. The rhythm is simple: orient, act, verify, then continue.

      -

      Jamie: How would you walk the room through that step by step?

      -

      Alex: Start with Challenge 6.3 Step-by-Step: Pass Required Checks: Read bot feedback, fix any issues it finds, and get all required checks to pass. The next useful detail is this: the Conversation tab of your open pull request. Think of it like entering a new building: first you find the lobby, then the room, then the door you actually need.

      -

      Alex: On the ground, that means a few things. 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.

      -

      Alex: First, wait approximately 30 seconds after opening the PR. The bot posts a validation comment. Then, read the bot comment carefully. It checks. After that, if the bot reports failures. Finally, repeat step 3 until all required checks show a green checkmark. Think of it as a rail line: each stop confirms you are still on the right route before the next one.

      -

      Jamie: Let's pause on Challenge 6.3 Step-by-Step: Pass Required Checks. What should a learner take away from it?

      -

      Alex: First, when all checks pass, request a review from a peer or the facilitator. Treat it like a recipe: do not add the next ingredient until the previous one is actually in the bowl.

      -

      Alex: The useful habit is simple: orient first, act second, verify third. That pause before acting is part of the work.

      +

      Jamie: Let's pause on Learning Cards: Viewing a Single File. What should a learner take away from it?

      +

      Alex: Start with Learning Cards: Viewing a Single File. There is something to understand, something to try, and something that proves the try worked.

      +

      Alex: The practical takeaway is this. 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. 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.

      +

      Alex: Keep the teaching thread moving. Start with The Blame View: Blame shows you who changed each line of a file, in what commit, and when. The next useful detail is this: It is useful for tracing why a particular change was made. Think of it like entering a new building: first you find the lobby, then the room, then the door you actually need.

      +

      Jamie: Let's pause on Navigating Blame. What should a learner take away from it?

      +

      Alex: Start with Navigating Blame. There is something to understand, something to try, and something that proves the try worked.

      +

      Alex: First, from a file page, activate the "Blame" button. Then, the page reloads in Blame view. After that, the content is a table: left column = commit info (who, when, message), right column = the line of code. Treat it like a recipe: do not add the next ingredient until the previous one is actually in the bowl.

      -

      Jamie: If I am listening before the workshop starts, what should settle in my mind first?

      -

      Alex: Start with Expected Outcomes. There is something to understand, something to try, and something that proves the try worked.

      -

      Alex: Here is what that changes in practice. Student opens a focused PR that maps to one issue. Student uses Closes XX correctly. Student can interpret bot feedback and improve the PR.

      -

      Jamie: Let's pause on If You Get Stuck. What should a learner take away from it?

      -

      Alex: Start with If You Get Stuck. There is something to understand, something to try, and something that proves the try worked.

      -

      Alex: First, confirm your PR includes Closes XX in title or body. Then, check that changed files are only in learning-room/. After that, open the bot validation comment and resolve one required check at a time. Finally, if checks still fail, ask for peer or facilitator review with the exact error message. It is a checklist, but a meaningful one: every item creates evidence that the next step is safe.

      -

      Jamie: Before we leave If You Get Stuck, what is the practical point?

      -

      Alex: First, finished but not sure you did it right? Compare your work against the Challenge 6 reference solution. It is like walking a hallway with named doors: read the sign, enter the right room, then confirm where you landed.

      -

      Jamie: What is the one idea that makes the next few steps less mysterious?

      -

      Alex: Keep the learner anchored in Learning Moment. A great PR is small, linked to an issue, and easy to review. This is the part to say slowly: Faster feedback builds confidence and momentum.

      +

      Alex: Keep the teaching thread moving. Start with Commit History. There is something to understand, something to try, and something that proves the try worked.

      +

      Alex: The practical takeaway is this. 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.

      +

      Jamie: What should they understand before typing anything?

      +

      Alex: Start with Reading the Commits List Page. There is something to understand, something to try, and something that proves the try worked.

      +

      Alex: Treat examples as spoken recipes, not decorations. You may hear something like 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. Read the command, understand what it changes, then run it only when the repository state matches the lesson.

      +

      Alex: Keep the teaching thread moving. Start with Reading a Commit Page. There is something to understand, something to try, and something that proves the try worked.

      +

      Alex: The practical takeaway is this. The commit message (heading). Author and date. Parent commit link. A diff for every file changed.

      -

      Alex: Before the learner moves on. Start with Why this feels achievable. There is something to understand, something to try, and something that proves the try worked.

      -

      Alex: That becomes easier when you listen for these cues. Scope is intentionally small. Feedback is immediate and specific. Success is visible (green checks + closed issue).

      -

      Jamie: What would you say to someone who is already bracing for this to be too much?

      -

      Alex: Start with About Learning Cards in This Chapter: This chapter provides learning cards: expandable blocks that offer perspective-specific guidance for different ways of working. The next useful detail is this: Not every card appears at every step.

      -

      Jamie: What should happen before anyone copies and runs it?

      -

      Alex: Here is the plain-English version of Local Git Alternative: The Full Branch-Edit-PR Workflow. If you cloned the learning-room in Block 0 and prefer working locally. Put another way, the web editor workflow (pencil button, "Propose changes") is the primary path taught in this chapter.

      -

      Alex: Treat examples as spoken recipes, not decorations. You may hear something like cd /Documents/learning-room; git checkout main; git pull origin main; git checkout -b fix/welcome-todos. code docs/welcome.md. Read the command, understand what it changes, then run it only when the repository state matches the lesson.

      +

      Jamie: Let's pause on Searching for a File. What should a learner take away from it?

      +

      Alex: Start with Searching for a File: The "Go to file" shortcut is extremely useful when you know what you are looking for.

      +

      Jamie: Let's pause on How to use Go to File. What should a learner take away from it?

      +

      Alex: Here is the plain-English version of How to use Go to File. GitHub keyboard shortcut: T - opens the Go to File dialog. Put another way, screen reader conflict warning: T normally means "next table" in NVDA/JAWS Browse Mode.

      +

      Alex: The practical takeaway is this. If hovercards are off, no navigation penalty - just navigate normally. 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.

      +

      Alex: First, make sure you are on the Code tab of a repository. Then, 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". After that, type the filename or partial path. Finally, results appear as a dropdown - use ↓ to navigate, Enter to open. Treat it like a recipe: do not add the next ingredient until the previous one is actually in the bowl.

      +

      Jamie: Let's pause on Learning Cards: Searching for a File. What should a learner take away from it?

      +

      Alex: Start with Learning Cards: Searching for a File. There is something to understand, something to try, and something that proves the try worked.

      +

      Alex: The practical takeaway is this. 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. 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.

      -

      Jamie: Where do you want a learner to place their attention here?

      -

      Alex: This is where What Is a Pull Request? becomes real: a pull request (PR) is a proposal to merge changes from one branch into another. That matters in practice.you open a PR to request that those changes be merged into the target branch (usually main).

      -

      Alex: That shows up in the workshop in a few specific ways. Edited a file directly on GitHub (web editor). Made changes in your fork. Made changes on a feature branch. What changed - a diff of every file.

      -

      Jamie: Let's pause on Navigating to Pull Requests. What should a learner take away from it?

      -

      Alex: Keep the learner anchored in Navigating to Pull Requests. Global pull requests dashboard: GitHub now shows a global pull requests page at github.com/pulls listing all open PRs across every repository you have access to. This is the part to say slowly: 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). A good GitHub workflow is like a well-run meeting: everyone knows the topic, the next action, and who has the floor.

      -

      Alex: The room should hear these as checkpoints. 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.

      -

      Alex: First, d → "Repository navigation" landmark. Then, k to navigate tabs → "Pull requests, [N] open". After that, enter to open. Finally, vO+U → Landmarks → navigate to "Repository navigation". It is like walking a hallway with named doors: read the sign, enter the right room, then confirm where you landed.

      -

      Jamie: Before we leave Navigating to Pull Requests, what is the practical point?

      -

      Alex: First, quick Nav K or VO+Right to navigate tabs → "Pull requests". Then, vO+Space to open. The rhythm is simple: orient, act, verify, then continue.

      -

      Jamie: What is the safe way to learn from that example?

      -

      Alex: The reason From a PR notification matters is that if you received a notification about a PR, follow the notification link directly to the PR page. That gives the learner a simple foothold: list and view pull requests from your terminal.

      -

      Alex: Treat examples as spoken recipes, not decorations. You may hear something like 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. Read the command, understand what it changes, then run it only when the repository state matches the lesson.

      +

      Alex: Keep the teaching thread moving. Keep the learner anchored in GitHub Shortcuts for Repository Navigation - Spotlight. These are the GitHub built-in shortcuts you will use most on repository pages. This is the part to say slowly: They work by sending keystrokes directly to GitHub's JavaScript, so enable Focus Mode first (NVDA: NVDA+Space, JAWS: Insert+Z). A good GitHub workflow is like a well-run meeting: everyone knows the topic, the next action, and who has the floor.

      +

      Alex: The practical takeaway is this. About - the repo description and topics. Releases - recent published releases. Packages - Docker/npm packages attached to the repo. Contributors - the top contributors.

      +

      Jamie: Let's pause on Navigating the sidebar. What should a learner take away from it?

      +

      Alex: The reason Navigating the sidebar matters is that the sidebar content is inside the "Main" landmark, after the files table and README. That gives the learner a simple foothold: after the README, press H or 2 to reach "About" and the sidebar section headings.

      +

      Jamie: Let's pause on The Repository About Section. What should a learner take away from it?

      +

      Alex: Start with The Repository About Section: Quick way to check the project description, website link, and topics.

      +

      Alex: First, press D to walk through landmarks. Then, look for a heading "About" in the sidebar. After that, 2 or H to jump to that "About" heading. Finally, then ↓ to read the description, URL, and topics. Think of it as a rail line: each stop confirms you are still on the right route before the next one.

      -

      Alex: Here is the practical turn. Start with Learning Cards: Navigating to Pull Requests. There is something to understand, something to try, and something that proves the try worked.

      -

      Alex: These are the details that keep the idea from floating away. 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. 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.

      -

      Jamie: Give me the version that sounds like an instructor, not a manual.

      -

      Alex: Here is the plain-English version of The Pull Request List Page. The PR list works identically to the Issues list. Put another way, for screen reader users, - PR list semantics: The PR list does not have individual ARIA item containers with per-item semantics.

      -

      Alex: A few details make that real. 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.

      -

      Jamie: Let's pause on Navigating the PR Tab Bar. What should a learner take away from it?

      -

      Alex: This is where Navigating the PR Tab Bar becomes real: the Conversation, Commits, and Files changed tabs are in a "Pull request navigation tabs" landmark. That matters in practice: The three tabs - Conversation, Commits, and Files changed - appear just below the PR title. The workshop is closer to rehearsal than lecture. You hear the move, try the move, and then check what changed.

      -

      Alex: The practical takeaway is this. 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.

      -

      Alex: First, press D → navigate to "Pull request navigation tabs". Then, press ← or → arrow keys to move between tab options. After that, press Enter to activate a tab. Finally, vO+U → Landmarks → "Pull request navigation tabs". It is a checklist, but a meaningful one: every item creates evidence that the next step is safe.

      -

      Jamie: Before we leave Navigating the PR Tab Bar, what is the practical point?

      -

      Alex: First, vO+Right to move between tabs. Then, vO+Space to activate. It is like walking a hallway with named doors: read the sign, enter the right room, then confirm where you landed.

      +

      Jamie: Let's pause on Scenario A: "I want to find out what this project does". What should a learner take away from it?

      +

      Alex: Start with Scenario A: "I want to find out what this project does". There is something to understand, something to try, and something that proves the try worked.

      +

      Alex: First, navigate to the repo URL. Then, press 1 - hear the repo name. After that, ↓ - read the description (announced as a paragraph after the heading). Finally, navigate to README: D → "Repository files navigation" → H within the README. Treat it like a recipe: do not add the next ingredient until the previous one is actually in the bowl.

      +

      Jamie: Let's pause on Scenario B: "I want to find a good file to edit". What should a learner take away from it?

      +

      Alex: Start with Scenario B: "I want to find a good file to edit". There is something to understand, something to try, and something that proves the try worked.

      +

      Alex: First, open the files table with T. Then, navigate rows with Ctrl+Alt+↓. After that, move right with Ctrl+Alt+→ to read the commit message (what's been changing recently). Finally, when found, press Enter on the Name column to open the file. It is a checklist, but a meaningful one: every item creates evidence that the next step is safe.

      +

      Jamie: Let's pause on Scenario C: "I want to know who has been working on this file recently". What should a learner take away from it?

      +

      Alex: Start with Scenario C: "I want to know who has been working on this file recently". There is something to understand, something to try, and something that proves the try worked.

      +

      Alex: First, open the file. Then, activate the "Blame" button (B from the Repository files navigation landmark). After that, navigate the blame table to see authors. It is like walking a hallway with named doors: read the sign, enter the right room, then confirm where you landed.

      -

      Jamie: Let's pause on PR Description. What should a learner take away from it?

      -

      Alex: Start with PR Description. There is something to understand, something to try, and something that proves the try worked.

      -

      Alex: First, 2 → navigate to "Description" h2 heading. Then, ↓ to read the description. After that, markdown renders as semantic HTML - headings, lists, code blocks are fully accessible. It is like walking a hallway with named doors: read the sign, enter the right room, then confirm where you landed.

      -

      Jamie: Let's pause on Status Checks Section. What should a learner take away from it?

      -

      Alex: The reason Status Checks Section matters is that below the description, the status checks summary shows whether automated tests passed. That gives the learner a simple foothold: status checks appear as a coloured banner below the PR description - green tick for passed, red X for failed, yellow spinner for running.

      -

      Alex: The practical takeaway is this. "All checks have passed" / "Some checks failed" / "Checks pending". A "Show all checks" button or link.

      -

      Alex: First, press H or 2 to find the "Checks" or "Status checks" heading. Then, press K to navigate links for individual check names. After that, press Enter on a check to see its details. Finally, quick Nav H or VO+Cmd+H to jump to the "Checks" or "Status checks" heading. The rhythm is simple: orient, act, verify, then continue.

      -

      Jamie: Before we leave Status Checks Section, what is the practical point?

      -

      Alex: First, quick Nav K to navigate check name links. Then, vO+Space on a check to see its details. Think of it as a rail line: each stop confirms you are still on the right route before the next one.

      -

      Jamie: Let's pause on Review Comments. What should a learner take away from it?

      -

      Alex: Start with Review Comments: Each review comment thread is an h3.

      -

      Alex: The practical takeaway is this. 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.

      +

      Jamie: Let's pause on Scenario D: "I want to understand what changed in the last release". What should a learner take away from it?

      +

      Alex: Start with Scenario D: "I want to understand what changed in the last release". There is something to understand, something to try, and something that proves the try worked.

      +

      Alex: First, navigate to the sidebar "Releases" section (H or 2). Then, activate the latest release link. After that, read the release notes (rendered Markdown with headings and lists). The rhythm is simple: orient, act, verify, then continue.

      +

      Jamie: Let's pause on Scenario E: "I want to contribute - where do I start?". What should a learner take away from it?

      +

      Alex: Start with Scenario E: "I want to contribute - where do I start?". There is something to understand, something to try, and something that proves the try worked.

      +

      Alex: First, navigate to the Code tab. Then, look for CONTRIBUTING.md in the files table. After that, open it and read the contributing guidelines. Finally, then go to Issues tab and filter by good first issue. Think of it as a rail line: each stop confirms you are still on the right route before the next one.

      +

      Jamie: Let's pause on Try It: The Five-Tab Tour. What should a learner take away from it?

      +

      Alex: Here is the plain-English version of Try It: The Five-Tab Tour. Time: 3 minutes What you need: Browser with screen reader, signed in to GitHub. Put another way, navigate to the Accessibility Agents repository and do this. It is like learning a transit route. The names of the stops matter because they tell you whether you are still going the right direction.

      +

      Alex: First, code tab - Press D to the "Repository navigation" landmark, then K to find "Code". Press Enter. You're on the file list. Then, issues tab - Press G then I (Focus Mode first: NVDA+Space). How many open issues are there? Press 3 to jump through issue titles. After that, pull Requests tab - Press G then P. Are there any open PRs? Finally, 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. Treat it like a recipe: do not add the next ingredient until the previous one is actually in the bowl.

      +

      Jamie: Before we leave Try It: The Five-Tab Tour, what is the practical point?

      +

      Alex: First, read the README - Press 1 to find the page title, then 2 to scan sections. It is a checklist, but a meaningful one: every item creates evidence that the next step is safe.

      -

      Jamie: Let's pause on Resolving conversations. What should a learner take away from it?

      -

      Alex: Here is the plain-English version of Resolving conversations. When a review comment has been addressed, you can mark the conversation as resolved. Put another way, resolved conversations are still accessible - they collapse but can be expanded again. It is like learning a transit route. The names of the stops matter because they tell you whether you are still going the right direction.

      -

      Alex: First, navigate to the conversation thread (3 to jump between comment headings). Then, tab to the end of the thread to find the "Resolve conversation" button. After that, press Enter to mark it resolved. Finally, the conversation collapses and shows as "Resolved". Treat it like a recipe: do not add the next ingredient until the previous one is actually in the bowl.

      -

      Jamie: Let's pause on Learning Cards: Reading the Conversation Tab. What should a learner take away from it?

      -

      Alex: Start with Learning Cards: Reading the Conversation Tab. There is something to understand, something to try, and something that proves the try worked.

      -

      Alex: The practical takeaway is this. 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. 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.

      -

      Jamie: Let's pause on Reading the Checks Tab. What should a learner take away from it?

      -

      Alex: Keep the learner anchored in Reading the Checks Tab. The Checks tab shows the status of automated tests, CI workflows, and other verification processes running on your PR. This is the part to say slowly: It helps you verify whether your changes pass all required tests before merging.

      -

      Alex: The practical takeaway is this. Navigate through the check steps with K or Tab. Activate a step for more details.

      -

      Alex: First, navigate to the "Pull request tabs" landmark (D). Then, navigate between tab links (K or Tab) and activate "Checks". After that, press D to jump to the "check suites" section - this moves focus to the collapsed details button of the first check. Finally, press B or Tab to navigate between check buttons; each button is labeled with the check's name. It is like walking a hallway with named doors: read the sign, enter the right room, then confirm where you landed.

      -

      Jamie: Before we leave Reading the Checks Tab, what is the practical point?

      -

      Alex: First, press Enter or Space to expand a check and reveal its logs. Then, for a summary view: press D to navigate to the "check run summary" section. After that, vO+U - Landmarks - "Pull request tabs" - activate "Checks". Finally, vO+U - Landmarks - navigate to "check suites" section. The rhythm is simple: orient, act, verify, then continue.

      +

      Jamie: Let's pause on What Is the Learning Room? What should a learner take away from it?

      +

      Alex: This is where What Is the Learning Room? becomes real: the Learning Room is your own private GitHub repository for the workshop. That matters in practice: When you accept the GitHub Classroom assignment in Block 0, GitHub copies the Community-Access/learning-room-template repository into the workshop classroom organization as the workshop organization/learning-room-your username.

      +

      Alex: Keep the teaching thread moving. Keep the learner anchored in Why a Per-Student Repo? GitHub Classroom gives each participant their own repository for three reasons. This is the part to say slowly: 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.

      +

      Alex: The practical takeaway is this. 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.

      +

      Jamie: Let's pause on Step-by-Step: Accept Your Classroom Assignment and Open Your Repo. What should a learner take away from it?

      +

      Alex: The reason Step-by-Step: Accept Your Classroom Assignment and Open Your Repo matters is that this is the very first hands-on step of Day 1. That gives the learner a simple foothold: by the end of this walkthrough you will have your own Learning Room repository on GitHub and your first challenge issue waiting for you.

      -

      Jamie: Let's pause on Learning Cards: Reading the Checks Tab. What should a learner take away from it?

      -

      Alex: Start with Learning Cards: Reading the Checks Tab. There is something to understand, something to try, and something that proves the try worked.

      -

      Alex: The practical takeaway is this. 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. 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.

      -

      Alex: Now bring the learner back to the room. Start with Reading the Files Changed Tab: the learner will read diffs - the before/after state of every file that changed. The next useful detail is this: This guide uses GitHub's improved Files Changed experience. Think of it like entering a new building: first you find the lobby, then the room, then the door you actually need.

      -

      Jamie: Let's pause on File Tree (left panel). What should a learner take away from it?

      -

      Alex: Here is the plain-English version of File Tree (left panel). The file tree lists every changed file. Put another way, use it to jump directly to a specific file's diff.

      -

      Alex: The practical takeaway is this. 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.

      -

      Alex: First, d → navigate to "File tree" region. Then, ↑/↓ to navigate the file list. After that, enter to jump to that file's diff. Finally, vO+U → Landmarks → navigate to "File tree" region. Treat it like a recipe: do not add the next ingredient until the previous one is actually in the bowl.

      -

      Jamie: Before we leave File Tree (left panel), what is the practical point?

      -

      Alex: First, vO+Down to move through the file list. Then, vO+Space to jump to that file's diff. It is a checklist, but a meaningful one: every item creates evidence that the next step is safe.

      +

      Jamie: Let's pause on 1. Open the assignment link. What should a learner take away from it?

      +

      Alex: Start with 1. Open the assignment link. There is something to understand, something to try, and something that proves the try worked.

      +

      Alex: First, in the same browser where you are signed into GitHub, open the Day 1 assignment link the facilitator shared. Then, 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"). After that, if the page asks you to authorize GitHub Classroom to access your GitHub account, activate Authorize GitHub Classroom. This is a one-time step. Think of it as a rail line: each stop confirms you are still on the right route before the next one.

      +

      Jamie: Let's pause on 2. Identify yourself (if asked). What should a learner take away from it?

      +

      Alex: Here is the plain-English version of 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.

      +

      Alex: First, 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. Then, activate the link or button next to your name. After that, 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. Treat it like a recipe: do not add the next ingredient until the previous one is actually in the bowl.

      +

      Jamie: Let's pause on 3. Accept the assignment. What should a learner take away from it?

      +

      Alex: This is where 3. Accept the assignment becomes real: the status page does not auto-announce when the repo is ready. That matters in practice: Use Browse mode and press K to step through links until you hear your repository link, or refresh the page until it appears.

      +

      Alex: First, you now see a screen with a button that says Accept this assignment (or just Accept the assignment ). Activate it. Then, 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. After that, 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/the workshop organization/learning-room-your username. It is a checklist, but a meaningful one: every item creates evidence that the next step is safe.

      -

      Alex: That matters because of the next idea. Start with The Diff for a File. There is something to understand, something to try, and something that proves the try worked.

      -

      Alex: The practical takeaway is this. 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.

      -

      Jamie: Let's pause on Lines in a diff are read as. What should a learner take away from it?

      -

      Alex: Start with Lines in a diff are read as. There is something to understand, something to try, and something that proves the try worked.

      -

      Alex: The practical takeaway is this. + Added line - line that was added. Removed line - line that was removed. Context line - unchanged line shown for context.

      -

      Jamie: Let's pause on Navigating the diff with a screen reader. What should a learner take away from it?

      -

      Alex: The reason Navigating the diff with a screen reader matters is that each file's diff shows added lines in green and removed lines in red. That gives the learner a simple foothold: scroll the page to read through changes. The interface gets friendlier when it stops being a wall of controls and starts being a set of named places.

      -

      Alex: The practical takeaway is this. 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.

      -

      Alex: First, t to jump to the next diff table. Then, switch to Focus Mode: Insert+Space (NVDA) or Insert+Z (JAWS). After that, ctrl+Alt+↓ to move down one row (next diff line), Ctrl+Alt+↑ to move up. Finally, ctrl+Alt+→ to read across columns (line number change type content). The rhythm is simple: orient, act, verify, then continue.

      -

      Jamie: Before we leave Navigating the diff with a screen reader, what is the practical point?

      -

      Alex: First, the screen reader reads: "+ Add accessible name to submit button". Then, collapsed sections contain unchanged code. Focus the expand/disclosure control and activate it (Enter or Space) to reveal the hidden lines. After that, t or VO+U → Tables → select the diff table. Finally, vO+Shift+Down to enter the table. Think of it as a rail line: each stop confirms you are still on the right route before the next one.

      +

      Jamie: Let's pause on 4. Open your new repository. What should a learner take away from it?

      +

      Alex: Start with 4. Open your new repository. There is something to understand, something to try, and something that proves the try worked.

      +

      Alex: The practical takeaway is this. The repo name in the heading matches learning-room-your username. 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.

      +

      Alex: First, activate the link to your repository. You land on the standard GitHub repo page for the workshop organization/learning-room-your username. Then, verify three things on this page. After that, bookmark this page. You will return here for every Day 1 challenge. It is like walking a hallway with named doors: read the sign, enter the right room, then confirm where you landed.

      +

      Jamie: Let's pause on 5. Find your first challenge issue. What should a learner take away from it?

      +

      Alex: The reason 5. Find your first challenge issue matters is that when your Learning Room repo is ready, Challenge 1 appears as a GitHub issue in your repo. That gives the learner a simple foothold: the facilitators prepare this by running the Student Progression Bot after students accept the Classroom assignment. The interface gets friendlier when it stops being a wall of controls and starts being a set of named places.

      +

      Alex: First, from your repository page, navigate to the Issues tab. Keyboard shortcut: press G then I. Then, 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]). After that, open Challenge 1. Read the issue body -- it tells you what to do, where to find evidence, and how to submit completion. The rhythm is simple: orient, act, verify, then continue.

      +

      Jamie: Let's pause on 6. Confirm Aria can talk to you. What should a learner take away from it?

      +

      Alex: Start with 6. Confirm Aria can talk to you: The PR validation bot, Aria, posts educational feedback whenever you open a pull request. The next useful detail is this: 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 ).

      -

      Jamie: Let's pause on Placing an inline comment on a diff line. What should a learner take away from it?

      -

      Alex: Start with Placing an inline comment on a diff line: Hover over any line in the diff - a blue + button appears on the left margin. The next useful detail is this: Click it to open a comment box for that line.

      -

      Alex: The practical takeaway is this. 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.

      -

      Alex: First, navigate to the specific line in the diff (using the table navigation above). Then, while focused on that line, a comment button appears - press Enter or Space to activate it. After that, a comment box opens below the line. Finally, focus Mode → type your comment. Think of it as a rail line: each stop confirms you are still on the right route before the next one.

      -

      Jamie: Before we leave Placing an inline comment on a diff line, what is the practical point?

      -

      Alex: First, tab to Add single comment button (instant comment) OR Start a review (to batch comments). Treat it like a recipe: do not add the next ingredient until the previous one is actually in the bowl.

      -

      Jamie: Let's pause on Multi-line comment (Windows). What should a learner take away from it?

      -

      Alex: Here is the plain-English version of Multi-line comment (Windows). Screen reader users (VoiceOver - macOS).

      -

      Alex: First, focus the first line you want to comment on. Then, press Shift+↓ to extend the selection to additional lines. After that, a comment button appears - activate it. Finally, the comment applies to the full range of selected lines. Treat it like a recipe: do not add the next ingredient until the previous one is actually in the bowl.

      -

      Jamie: Before we leave Multi-line comment (Windows), what is the practical point?

      -

      Alex: First, navigate to the specific line in the diff (using the table navigation above). Then, while focused on that line, VO+Space on the comment button that appears. After that, a comment box opens below the line. Finally, vO+Shift+Down to interact with the text area, then type your comment. It is a checklist, but a meaningful one: every item creates evidence that the next step is safe.

      -

      Jamie: Let's pause on Multi-line comment (macOS). What should a learner take away from it?

      -

      Alex: Start with Multi-line comment (macOS). There is something to understand, something to try, and something that proves the try worked.

      -

      Alex: First, focus the first line and Shift+↓ to extend the selection. Then, vO+Space on the comment button that appears. After that, the comment applies to the full range of selected lines. It is a checklist, but a meaningful one: every item creates evidence that the next step is safe.

      +

      Alex: Keep the teaching thread moving. Here is the plain-English version of Workshop Recommendation (Chapter 4). Chapter 4 is a system orientation chapter.

      +

      Alex: The practical takeaway is this. There are 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.

      +

      Jamie: Let's pause on Readiness Checkpoint. What should a learner take away from it?

      +

      Alex: This is where Readiness Checkpoint becomes real: before starting Chapter 5 challenges, you should be able to.

      +

      Alex: First, find docs/CHALLENGES.md in your Learning Room repository. Then, explain the flow: issue - branch - pull request - review - merge. After that, identify where Aria bot feedback appears on a PR (the Conversation tab). It is a checklist, but a meaningful one: every item creates evidence that the next step is safe.

      +

      Alex: Keep the teaching thread moving. Keep the learner anchored in Two Tracks That Reinforce Each Other. Throughout Day 1 you work on two parallel learning tracks, both in your own account. A good GitHub workflow is like a well-run meeting: everyone knows the topic, the next action, and who has the floor.

      -

      Alex: Hold that next to this. Keep the learner anchored in Viewing comments within the diff. Inline comments appear as expandable threads within the diff table. This is the part to say slowly: Navigate to them with 3 (they are h3 headings). A good GitHub workflow is like a well-run meeting: everyone knows the topic, the next action, and who has the floor.

      -

      Jamie: Let's pause on Learning Cards: Reading the Files Changed Tab. What should a learner take away from it?

      -

      Alex: Start with Learning Cards: Reading the Files Changed Tab. There is something to understand, something to try, and something that proves the try worked.

      -

      Alex: The practical takeaway is this. 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. 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.

      -

      Jamie: Let's pause on Tool Cards: Open a Pull Request. What should a learner take away from it?

      -

      Alex: Start with Tool Cards: Open a Pull Request: VS Code Desktop (GitHub Pull Requests extension).

      -

      Alex: First, push your branch, then click the Compare & pull request banner (or go to Pull requests New pull request ). Then, set base branch to main, compare branch to yours. After that, fill in the title and description, then click Create pull request. Finally, after committing changes, click the Source Control icon. Think of it as a rail line: each stop confirms you are still on the right route before the next one.

      -

      Jamie: Before we leave Tool Cards: Open a Pull Request, what is the practical point?

      -

      Alex: First, click Create Pull Request in the Source Control panel header. Then, fill in details and submit. After that, press Ctrl+Shift+P, type GitHub Pull Requests: Create Pull Request. Finally, select base and compare branches. Treat it like a recipe: do not add the next ingredient until the previous one is actually in the bowl.

      -

      Alex: Treat examples as spoken recipes, not decorations. You may hear something like git push -u origin your-branch; gh pr create --title "Your title" --body "Description". Read the command, understand what it changes, then run it only when the repository state matches the lesson.

      +

      Jamie: Let's pause on Track 1: GitHub Skills Modules (Optional Self-Paced Practice). What should a learner take away from it?

      +

      Alex: The reason Track 1: GitHub Skills Modules (Optional Self-Paced Practice) matters is that 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.

      +

      Alex: The practical takeaway is this. Introduction to GitHub - Create branch, open PR, merge. Communicate Using Markdown - Write headings, links, code, tables. Review Pull Requests - Comment, approve, suggest changes.

      +

      Alex: Keep the teaching thread moving. Start with Track 2: Your Learning Room Repository (Required Workshop Track). There is something to understand, something to try, and something that proves the try worked.

      +

      Alex: The practical takeaway is this. 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).

      +

      Jamie: How should someone choose between those options?

      +

      Alex: Start with How the Two Tracks Compare. There is something to understand, something to try, and something that proves the try worked.

      +

      Alex: Use the comparison to make a decision, not to recite a table. The main contrasts are: GitHub Skills (optional) means Your Learning Room (required). Create a branch in a Skills repo means Create a branch in your Learning Room. Open a PR means Open a PR.

      -

      Jamie: Let's pause on From the web editor workflow (editing a file on GitHub). What should a learner take away from it?

      -

      Alex: Start with From the web editor workflow (editing a file on GitHub). There is something to understand, something to try, and something that proves the try worked.

      -

      Alex: First, you edited a file → GitHub showed a "Propose changes" form. Then, you named your branch and activated "Propose changes". After that, GitHub redirected you to the "Open a pull request" page. Treat it like a recipe: do not add the next ingredient until the previous one is actually in the bowl.

      -

      Jamie: Let's pause on From a fork or feature branch. What should a learner take away from it?

      -

      Alex: This is where From a fork or feature branch becomes real: screen reader users (NVDA / JAWS - Windows). That matters in practice: Screen reader users (VoiceOver - macOS). The workshop is closer to rehearsal than lecture. You hear the move, try the move, and then check what changed.

      -

      Alex: First, navigate to the repository on GitHub. Then, if you recently pushed, a yellow banner "Compare & pull request" appears at the top - click it. After that, if no banner appears: click the Pull requests tab → click the green New pull request button. Finally, use the branch dropdowns to choose your base branch (what to merge into) and your compare branch (your changes). It is a checklist, but a meaningful one: every item creates evidence that the next step is safe.

      -

      Jamie: Before we leave From a fork or feature branch, what is the practical point?

      -

      Alex: First, click Create pull request. Then, navigate to the repository. After that, a "Compare & pull request" banner may appear (if you recently pushed) - activate it. Finally, oR: Navigate to Pull Requests tab → "New pull request". It is like walking a hallway with named doors: read the sign, enter the right room, then confirm where you landed.

      -

      Jamie: What should they understand before typing anything?

      -

      Alex: Keep the learner anchored in Description field. Copilot can write your PR description: If your account has Copilot access, a "Copilot actions" button appears in the description toolbar. This is the part to say slowly: 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.

      -

      Alex: Treat examples as spoken recipes, not decorations. You may hear something like Step 1: Tab to the body text area; Step 2: Focus Mode → type using the PR template (if provided). 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 for the dismiss control; Related Issues; Closes 42; Testing; - Tested with NVDA + Chrome on Windows 11; -. Read the command, understand what it changes, then run it only when the repository state matches the lesson.

      +

      Alex: Keep the teaching thread moving. Start with Learning Cards: Two Tracks, One Account. There is something to understand, something to try, and something that proves the try worked.

      +

      Alex: The practical takeaway is this. 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. 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.

      +

      Jamie: Let's pause on Your Learning Room Folder Structure. What should a learner take away from it?

      +

      Alex: Keep the learner anchored in 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.

      +

      Alex: The practical takeaway is this. 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.

      +

      Alex: Keep the teaching thread moving. The reason Your Practice Branch matters is that in your own Learning Room repository, you decide what branches to create. That gives the learner a simple foothold: the Day 1 challenge sequence asks you to work on a single feature branch named after yourself.

      +

      Alex: The practical takeaway is this. 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.

      -

      Jamie: Let's pause on Setting a Draft PR. What should a learner take away from it?

      -

      Alex: The reason Setting a Draft PR matters is that if your work is not finished, open as a Draft.

      -

      Alex: First, after filling in the form, find the dropdown arrow next to "Create pull request". Then, select "Create draft pull request". After that, this signals to reviewers that it is not ready for formal review yet. The rhythm is simple: orient, act, verify, then continue.

      -

      Jamie: Let's pause on Draft Pull Requests - Full Lifecycle. What should a learner take away from it?

      -

      Alex: Start with Draft Pull Requests - Full Lifecycle: A draft pull request is a PR explicitly marked as a work in progress. The next useful detail is this: It is visible to the team, can receive comments, and runs CI - but is blocked from being merged until you mark it ready.

      -

      Alex: Another way to ground it. Start with When to use a draft. There is something to understand, something to try, and something that proves the try worked.

      -

      Alex: The practical takeaway is this. You want to show your approach and get early feedback before finishing. You need CI to run but don't want accidental merges. You are working across multiple days and want your progress visible. You want to pair with a collaborator on the work.

      +

      Jamie: Let's pause on Why you create a separate branch. What should a learner take away from it?

      +

      Alex: Start with Why you create a separate branch. There is something to understand, something to try, and something that proves the try worked.

      +

      Alex: The practical takeaway is this. 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.

      +

      Jamie: Let's pause on How to use your branch. What should a learner take away from it?

      +

      Alex: Here is the plain-English version of How to use your branch. The Day 1 challenges (4 onward) walk you through creating and using your branch on GitHub.com. Put another way, once you start working locally in Chapter 14, the same branch is what you check out. It is like learning a transit route. The names of the stops matter because they tell you whether you are still going the right direction.

      +

      Alex: First, create the branch on GitHub.com (Challenge 4) or locally with git checkout -b learn/ from main. Then, make your changes and commit them to the branch. After that, push the branch to GitHub if you created it locally. Finally, open a pull request from learn/ - main (Challenge 6). Treat it like a recipe: do not add the next ingredient until the previous one is actually in the bowl.

      +

      Alex: Treat examples as spoken recipes, not decorations. You may hear something like git checkout learn/. Read the command, understand what it changes, then run it only when the repository state matches the lesson.

      +

      Jamie: Let's pause on Learning Cards: Your Practice Branch. What should a learner take away from it?

      +

      Alex: Start with Learning Cards: Your Practice Branch. There is something to understand, something to try, and something that proves the try worked.

      +

      Alex: The practical takeaway is this. 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. 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.

      -

      Jamie: Let's pause on What a draft PR does differently. What should a learner take away from it?

      -

      Alex: Start with What a draft PR does differently. There is something to understand, something to try, and something that proves the try worked.

      -

      Alex: The practical takeaway is this. The merge button is disabled - even an authorized maintainer cannot merge a draft. The PR header shows a grey "Draft" badge instead of the green "Open" badge. Reviewers are not auto-notified (no review requests are sent until ready). CI workflows still run normally.

      -

      Jamie: Let's pause on Mark a draft ready for review. What should a learner take away from it?

      -

      Alex: Start with Mark a draft ready for review. There is something to understand, something to try, and something that proves the try worked.

      -

      Alex: First, open the PR. Then, navigate to the "Reviewers" sidebar or scroll to bottom of the Conversation tab. After that, find and activate the "Ready for review" button. Finally, the draft badge changes to "Open" and reviewers are notified. It is like walking a hallway with named doors: read the sign, enter the right room, then confirm where you landed.

      -

      Jamie: Let's pause on Convert an open PR to draft (after opening). What should a learner take away from it?

      -

      Alex: The reason Convert an open PR to draft (after opening) matters is that GitHub CLI (gh) alternative - draft PR lifecycle. That gives the learner a simple foothold: manage draft PRs from your terminal.

      -

      Alex: First, in the right sidebar, find the "Reviewers" section. Then, look for the "Convert to draft" link (below the review status). After that, confirm in the dialog - this removes merge eligibility until you mark it ready again. The rhythm is simple: orient, act, verify, then continue.

      -

      Alex: Treat examples as spoken recipes, not decorations. You may hear something like Create a draft PR; gh pr create --draft --title "WIP: Add carousel keyboard nav"; Mark a draft ready for review; gh pr ready 42; Check PR status (shows draft state); gh pr view 42; List only draft PRs; gh pr list --draft. Read the command, understand what it changes, then run it only when the repository state matches the lesson.

      +

      Jamie: Let's pause on Tool Cards: Switch to Your Practice Branch. What should a learner take away from it?

      +

      Alex: Start with Tool Cards: Switch to Your Practice Branch. There is something to understand, something to try, and something that proves the try worked.

      +

      Alex: First, on the repository page, click the branch selector dropdown (shows "main"). Then, type learn to filter, then select learn/. After that, click the branch name in the bottom-left status bar. Finally, select your learn/ branch from the list. It is like walking a hallway with named doors: read the sign, enter the right room, then confirm where you landed.

      +

      Jamie: Before we leave Tool Cards: Switch to Your Practice Branch, what is the practical point?

      +

      Alex: First, click the branch name in the bottom-left status bar (or press Ctrl+Shift+P then type Git: Checkout to ). Then, select origin/learn/ from the branch list. After that, click the Current Branch dropdown at the top. The rhythm is simple: orient, act, verify, then continue.

      +

      Jamie: Let's pause on The Practice Files: What You Will Work On. What should a learner take away from it?

      +

      Alex: The reason The Practice Files: What You Will Work On matters is that see also: Appendix C: Markdown Reference covers all Markdown syntax with accessible examples -- you will need it for editing these files. That gives the learner a simple foothold: the docs/ folder contains three practice files with intentional issues.

      +

      Alex: Keep the teaching thread moving. Start with docs/welcome.md - Introduction to Open Source Contribution: This file introduces newcomers to open source. The next useful detail is this: It has three [TODO] sections where content is missing. Think of it like entering a new building: first you find the lobby, then the room, then the door you actually need.

      -

      Alex: That connects to another useful point. Start with Learning Cards: Opening a Pull Request. There is something to understand, something to try, and something that proves the try worked.

      -

      Alex: The practical takeaway is this. After editing a file on GitHub, the "Propose changes" form has a branch name field and a commit message field; press Tab to move between them. On the "Open a pull request" page, press F to jump to the Title field; Tab moves to the Description text area. Press Ctrl+Enter from inside the description text area to submit the PR without finding the Create button. The "Compare & pull request" yellow banner appears at the top of the repo after a recent push; at high zoom it may span the full width of the page. The branch comparison dropdowns (base and compare) use small text; zoom in on the area above the diff preview to read them. Draft PR: look for the dropdown arrow next to the green "Create pull request" button to switch to "Create draft pull request".

      -

      Jamie: Let's pause on Requesting reviewers. What should a learner take away from it?

      -

      Alex: Here is the plain-English version of Requesting reviewers. From the sidebar Reviewers section. Put another way, why some reviews are requested automatically: A file called CODEOWNERS in many repositories maps file paths to specific people or teams.

      -

      Alex: First, navigate to "Reviewers" heading (3 or H). Then, activate the gear button. After that, type a username in the search field. Finally, select from the dropdown. Treat it like a recipe: do not add the next ingredient until the previous one is actually in the bowl.

      -

      Jamie: Before we leave Requesting reviewers, what is the practical point?

      -

      Alex: First, escape to save. It is a checklist, but a meaningful one: every item creates evidence that the next step is safe.

      -

      Alex: Keep the thread going. This is where Submitting a Review becomes real: when you are asked to review a PR, you have three options.

      -

      Alex: The practical takeaway is this. Comment - leave feedback without a verdict; does not block merging. Approve - signal you are satisfied; often required before merge. Request changes - indicate changes must be addressed; blocks merge until resolved.

      +

      Jamie: Let's pause on [TODO] 1 - "Who Can Contribute?" section. What should a learner take away from it?

      +

      Alex: Here is the plain-English version of [TODO] 1 - "Who Can Contribute?" section. [TODO: Add a paragraph explaining that contributors come from all backgrounds, skill levels, and countries. Put another way, emphasize that using assistive technology is not a barrier to contribution - in fact, AT users bring a perspective that improves projects for everyone.].

      +

      Alex: Keep the teaching thread moving. This is where [TODO] 2 - "Finding Something to Work On" section becomes real: [TODO: Add two or three sentences about how to read an issue to decide if it is right for you. That matters in practice: What questions should you ask yourself?

      +

      Jamie: Let's pause on [TODO] 3 - "After Your Contribution Is Merged" section. What should a learner take away from it?

      +

      Alex: Keep the learner anchored in [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.]. This is the part to say slowly: It also has a broken internal link that needs to be found and fixed.

      -

      Jamie: What does someone need before they touch the keyboard?

      -

      Alex: Keep the learner anchored in Starting a review. On the Files Changed tab, when you add inline comments, choose "Start a review" instead of "Add single comment." This batches all your comments into one review submission.

      -

      Jamie: Let's pause on Completing and submitting a review. What should a learner take away from it?

      -

      Alex: The reason Completing and submitting a review matters is that after adding your inline comments via "Start a review," you must submit the review to notify the PR author. That gives the learner a simple foothold: the review is pending until you submit it. The interface gets friendlier when it stops being a wall of controls and starts being a set of named places.

      -

      Alex: The practical takeaway is this. The button may scroll off-screen to the right. Use horizontal scrolling or press Tab from the page top to cycle through focusable elements until you reach it. When clicked, a popover appears with a summary text area and three radio buttons ( Comment, Approve, Request changes ). At 200%+ zoom, the popover may extend below the visible viewport. Scroll down within the popover to see the Submit review button. The radio buttons are standard HTML radio buttons. In Windows High Contrast mode, the selected radio button uses the system highlight color. Keyboard shortcut: If the button is hard to find visually, press Ctrl+Shift+Enter from within any review comment text area to open the submit review dialog directly.

      -

      Alex: First, look for the Finish your review button in the top-right area of the Files Changed tab (it shows the number of pending comments). Then, click it - a popover appears with a summary text area and three radio buttons: Comment, Approve, Request changes. After that, optionally type a summary comment. Finally, select your verdict by clicking the radio button. The rhythm is simple: orient, act, verify, then continue.

      -

      Jamie: Before we leave Completing and submitting a review, what is the practical point?

      -

      Alex: First, click Submit review. Then, press 1 to go to the h1 (PR title). After that, press B (or Tab) to navigate to the "Submit review" button and activate it (Enter/Space). Finally, a "Submit review" dialog/panel appears. Think of it as a rail line: each stop confirms you are still on the right route before the next one.

      -

      Alex: Treat examples as spoken recipes, not decorations. You may hear something like View the PR diff in your terminal; gh pr diff 42; Approve a PR; gh pr review 42 --approve; Approve with a comment; gh pr review 42 --approve --body "Looks good - heading hierarchy is correct."; Request changes; gh pr review 42 --request-changes --body "The alt. Read the command, understand what it changes, then run it only when the repository state matches the lesson.

      -

      Jamie: Let's pause on GitHub shortcuts for pull requests. What should a learner take away from it?

      -

      Alex: Start with GitHub shortcuts for pull requests: These are the GitHub built-in shortcuts for PR pages. The next useful detail is this: Enable Focus Mode first (NVDA: NVDA+Space, JAWS: Insert+Z) before using single-key shortcuts.

      +

      Alex: Keep the teaching thread moving. The reason docs/keyboard-shortcuts.md - Screen Reader Shortcut Reference matters is that this is a comprehensive reference with tables for NVDA, JAWS, and VoiceOver shortcuts. That gives the learner a simple foothold: it contains intentional errors in some shortcut references that students need to find and fix. The interface gets friendlier when it stops being a wall of controls and starts being a set of named places.

      +

      Alex: The practical takeaway is this. 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.

      +

      Jamie: What is the pre-flight check here?

      +

      Alex: Start with 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. The next useful detail is this: It contains broken links that point to incorrect URLs and incomplete steps.

      +

      Alex: The practical takeaway is this. 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.

      +

      Alex: Keep the teaching thread moving. Here is the plain-English version of docs/CHALLENGES.md - Your Challenge Menu. This file lists all 21 challenges organized by progression level. Put another way, each challenge lists the file(s) to edit, estimated time, skills practiced, and success criteria.

      -

      Alex: This is where the talk moves from concept to action. Here is the plain-English version of On the PR list page. Shortcut note: For G P, press G, release it, then press P (two sequential key presses, not simultaneous).

      -

      Jamie: Let's pause on On the Files Changed tab. What should a learner take away from it?

      -

      Alex: This is where On the Files Changed tab becomes real: for the full shortcut system, see Screen Reader Cheat Sheet - GitHub Shortcuts section.

      -

      Alex: This is the part worth saying out loud. Start with Learning Cards: Submitting a Review. There is something to understand, something to try, and something that proves the try worked.

      -

      Alex: The practical takeaway is this. The review verdict controls are inside a popover triggered by the "Finish your review" button; press 1 to return to the h1 (PR title), then B or Tab forward to find the button -- it is easy to miss because it is not a landmark. Inside the popover, Tab past the summary text area to reach a radio group labeled "Review Event"; use Up/Down Arrow to switch between Comment, Approve, and Request Changes. Shortcut: press Ctrl+Shift+Enter from any review comment text area to open the submit review dialog directly, bypassing the search for the button. The "Finish your review" button sits in the top-right corner of the Files Changed tab with a small badge showing your pending comment count; at 200%+ zoom it may scroll off-screen to the right. Inside the submit popover, the three radio buttons (Comment, Approve, Request changes) are small standard HTML radios; zoom in on the popover area or use Tab to step between them. After submitting, your review verdict appears as a colored banner in the Conversation timeline: green for Approve, red for Request Changes, grey for Comment.

      +

      Jamie: How do these exercises create confidence instead of pressure?

      +

      Alex: This is where Bonus Challenges becomes real: five bonus challenges (A through E) are available for students who finish faster. That matters in practice: These include an accessibility audit, mentoring a peer, cross-repository contribution, creating a custom workflow, and documentation improvement.

      +

      Jamie: Let's pause on Student A (working on Challenge 3: Complete Welcome Guide). What should a learner take away from it?

      +

      Alex: Keep the learner anchored in Student A (working on Challenge 3: Complete Welcome Guide). Visibility: The PR immediately appears in the repo's Pull Requests tab. A good GitHub workflow is like a well-run meeting: everyone knows the topic, the next action, and who has the floor.

      +

      Alex: First, finds their assigned issue (Issues tab → filter Assignee:@me). Then, opens docs/welcome.md and edits the three [TODO] sections. After that, commits to a new branch: fix/studentA-issue12. Finally, opens a pull request with description. It is like walking a hallway with named doors: read the sign, enter the right room, then confirm where you landed.

      +

      Jamie: Before we leave Student A (working on Challenge 3: Complete Welcome Guide), what is the practical point?

      +

      Alex: First, submits the PR. The rhythm is simple: orient, act, verify, then continue.

      +

      Jamie: Let's pause on Bot (.github/workflows/learning-room-pr-bot.yml). What should a learner take away from it?

      +

      Alex: The reason Bot (.github/workflows/learning-room-pr-bot.yml) matters is that visibility: The bot comment appears in your PR. That gives the learner a simple foothold: you see it; the facilitators see it; nobody else does unless they have been added as a collaborator on your repo.

      +

      Alex: The practical takeaway is this. Runs within 30 seconds. 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).

      -

      Jamie: Let's pause on Suggested Changes. What should a learner take away from it?

      -

      Alex: The reason Suggested Changes matters is that a suggested change is a special form of inline review comment where the reviewer proposes exact replacement text. That gives the learner a simple foothold: the PR author can apply the suggestion directly from GitHub - no copy-paste or separate commit needed.

      -

      Jamie: Let's pause on As a reviewer - inserting a suggestion. What should a learner take away from it?

      -

      Alex: Start with As a reviewer - inserting a suggestion: The suggestion block is plain Markdown text in the comment editor. The next useful detail is this: (Three backticks, the word suggestion, Enter, your text, Enter, three backticks.).

      -

      Alex: First, on the Files Changed tab, navigate to the line you want to propose a change. Then, activate the line comment button for that line (the + that appears on hover, or Tab to navigate to it). After that, in the comment text area that opens, press Ctrl+G (Windows) or Cmd+G (Mac). Finally, GitHub wraps a suggestion block around the current line content. Think of it as a rail line: each stop confirms you are still on the right route before the next one.

      -

      Jamie: Before we leave As a reviewer - inserting a suggestion, what is the practical point?

      -

      Alex: First, edit the text inside the suggestion block to show your proposed change. Then, add context above the block if helpful: "This makes the alt text more descriptive:". After that, submit as part of your review ("Start a review" → batch with other comments). Treat it like a recipe: do not add the next ingredient until the previous one is actually in the bowl.

      -

      Jamie: Let's pause on As an author - applying a suggestion. What should a learner take away from it?

      -

      Alex: Start with As an author - applying a suggestion. There is something to understand, something to try, and something that proves the try worked.

      -

      Alex: First, open the PR Conversation or Files Changed tab. Then, navigate to the inline comment containing a suggestion (it shows a diff-style preview). After that, find and activate the "Apply suggestion" button below the suggestion block. Finally, GitHub creates a commit automatically that applies the change - no file editing required. Treat it like a recipe: do not add the next ingredient until the previous one is actually in the bowl.

      -

      Jamie: Before we leave As an author - applying a suggestion, what is the practical point?

      -

      Alex: First, the conversation thread is marked as resolved. It is a checklist, but a meaningful one: every item creates evidence that the next step is safe.

      +

      Jamie: Let's pause on Step 3: Peer Review (Facilitator-Arranged). What should a learner take away from it?

      +

      Alex: Start with 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. The next useful detail is this: 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.

      +

      Alex: First, the facilitators (Jeff and Michael) pair you with another participant. Then, they add each of you as a collaborator on the other's Learning Room repo. After that, each of you receives a notification: "You have been added as a collaborator.". Finally, you can now read the other person's PRs, leave comments, request changes, and approve. Think of it as a rail line: each stop confirms you are still on the right route before the next one.

      +

      Jamie: Before we leave Step 3: Peer Review (Facilitator-Arranged), what is the practical point?

      +

      Alex: First, 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. Treat it like a recipe: do not add the next ingredient until the previous one is actually in the bowl.

      +

      Jamie: Let's pause on Visibility. What should a learner take away from it?

      +

      Alex: Start with Visibility. There is something to understand, something to try, and something that proves the try worked.

      +

      Alex: The practical takeaway is this. 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.

      +

      Jamie: Let's pause on Your assigned peer reviewer (when one is paired with you). What should a learner take away from it?

      +

      Alex: Start with Your assigned peer reviewer (when one is paired with you). There is something to understand, something to try, and something that proves the try worked.

      +

      Alex: The practical takeaway is this. 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. 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.".

      +

      Alex: First, receives notification: "PR review requested". Then, navigates to the PR in your Learning Room repo (they have collaborator access). After that, leaves review comments. Finally, submits review: Approve (or Request Changes if a [TODO] marker was missed). It is a checklist, but a meaningful one: every item creates evidence that the next step is safe.

      -

      Jamie: Let's pause on Batching multiple suggestions into one commit. What should a learner take away from it?

      -

      Alex: Start with Batching multiple suggestions into one commit. There is something to understand, something to try, and something that proves the try worked.

      -

      Alex: First, for each suggestion you want to apply, activate "Add suggestion to batch" instead of "Apply suggestion". Then, after selecting all suggestions, activate the "Commit suggestions" button that appears at the top. After that, GitHub applies all batched suggestions in a single commit. It is a checklist, but a meaningful one: every item creates evidence that the next step is safe.

      -

      Jamie: Let's pause on When to use suggestions vs. comments. What should a learner take away from it?

      -

      Alex: Start with When to use suggestions vs. comments. There is something to understand, something to try, and something that proves the try worked.

      -

      Alex: The practical takeaway is this. Use a suggestion when you know the exact text that would fix the issue. Use a plain comment when the change requires judgment from the author (e.g., "this alt text isn't descriptive - can you describe what the image shows?"). A summary text area for overall comments. Radio buttons for Comment / Approve / Request changes.

      -

      Alex: First, after adding all your inline comments, navigate to the review summary button. Then, on Files Changed tab: find the "Review changes" button (B to navigate buttons). After that, press Enter to open the review dialog. Finally, a panel opens. It is like walking a hallway with named doors: read the sign, enter the right room, then confirm where you landed.

      -

      Jamie: Before we leave When to use suggestions vs. comments, what is the practical point?

      -

      Alex: First, switch to Focus Mode → type your summary comment. Then, navigate to the radio buttons with arrow keys → select your verdict. After that, tab to "Submit review" button → Enter. The rhythm is simple: orient, act, verify, then continue.

      -

      Alex: Keep the teaching thread moving. Start with Learning Cards: Suggested Changes. There is something to understand, something to try, and something that proves the try worked.

      -

      Alex: The practical takeaway is this. To insert a suggestion block, press Ctrl+G (Windows) or Cmd+G (Mac) in the comment text area; the screen reader announces the inserted fence -- arrow down to edit the text between the backtick lines. Alternatively type the block manually: three backticks, the word suggestion, Enter, your replacement text, Enter, three backticks -- this avoids relying on the keyboard shortcut. As a PR author, navigate to a suggestion comment with 3, then Tab to the "Apply suggestion" button; GitHub commits the change automatically with no file editing required. Suggestion blocks render as a mini inline diff: the original line in red/pink background and your proposed replacement in green background; in high-contrast mode these use system diff colors. The "Apply suggestion" button is small and sits below the suggestion diff preview; zoom into the comment area to find it, or Tab from the suggestion text to reach it. When batching multiple suggestions, a floating "Commit suggestions" bar appears at the top of the page; at high zoom scroll up or press Home to find it.

      +

      Jamie: Before we leave Visibility, what is the practical point?

      +

      Alex: The practical takeaway is this. 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.

      +

      Jamie: Let's pause on You (PR author). What should a learner take away from it?

      +

      Alex: Start with You (PR author). There is something to understand, something to try, and something that proves the try worked.

      +

      Alex: First, read Aria's feedback and any human review. Then, talks to the reviewer if something is unclear. After that, makes changes based on feedback. Finally, pushes new commits to the same branch. The rhythm is simple: orient, act, verify, then continue.

      +

      Jamie: Before we leave You (PR author), what is the practical point?

      +

      Alex: First, re-addresses the feedback. Think of it as a rail line: each stop confirms you are still on the right route before the next one.

      +

      Jamie: What is the teaching move inside Visibility?

      +

      Alex: The practical takeaway is this. 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.

      -

      Jamie: How do you keep commands from becoming magic words?

      -

      Alex: Start with Understanding Merge Options (for Maintainers): When a PR is approved and checks pass, a maintainer can merge it. The next useful detail is this: The merge button section appears at the bottom of the Conversation tab.

      -

      Alex: Treat examples as spoken recipes, not decorations. You may hear something like Merge with default strategy (merge commit); gh pr merge 42; Squash and merge; gh pr merge 42 --squash; Rebase and merge; gh pr merge 42 --rebase; Delete the branch after merging; gh pr merge 42 --squash --delete-branch; Enable auto-merge (merges when checks. Read the command, understand what it changes, then run it only when the repository state matches the lesson.

      -

      Alex: Keep the teaching thread moving. Here is the plain-English version of After a PR is merged. for screen reader users, - deleting the branch after merge: Navigate to the "Add a comment" section (D), then press Shift+B to navigate backwards to the "Delete branch" button and activate it. Put another way, this keeps your repository clean by removing the now-merged feature branch. It is like learning a transit route. The names of the stops matter because they tell you whether you are still going the right direction.

      -

      Alex: The practical takeaway is this. The PR status badge changes to "Merged" (purple). The source branch can be deleted - a "Delete branch" button appears. Any linked issues with Closes N in the description are automatically closed.

      -

      Jamie: Let's pause on Auto-Merge - Merging When You Can't Wait Around. What should a learner take away from it?

      -

      Alex: This is where Auto-Merge - Merging When You Can't Wait Around becomes real: auto-merge lets you pre-authorize a PR to merge automatically the moment all branch protection requirements are satisfied - required reviews approved, all status checks passing, and the branch up to date.

      -

      Alex: The practical takeaway is this. You've addressed all review comments and are waiting for CI to finish. A maintainer has approved the PR but a required check is still running. You're in a different time zone from the reviewers.

      +

      Alex: Keep the teaching thread moving. Start with When the review is approved (or you decide to self-merge). There is something to understand, something to try, and something that proves the try worked.

      +

      Alex: The practical takeaway is this. You merge the PR (button becomes available). PR closes, shows "merged".

      +

      Jamie: What should the learner prove to themselves after each small task?

      +

      Alex: Start with Progression Bot Posts the Next Challenge. There is something to understand, something to try, and something that proves the try worked.

      +

      Alex: The practical takeaway is this. 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.

      +

      Alex: Keep the teaching thread moving. Start with Visibility. There is something to understand, something to try, and something that proves the try worked.

      +

      Alex: The practical takeaway is this. 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.

      -

      Alex: Keep the teaching thread moving. Start with What happens next. There is something to understand, something to try, and something that proves the try worked.

      -

      Alex: The practical takeaway is this. The PR merge box changes to show "Auto-merge enabled - merge will happen automatically". When the last required check passes (or last required review arrives), GitHub merges the PR silently. You receive a notification: "Your PR was automatically merged". If a reviewer requests changes after auto-merge is enabled, auto-merge is automatically cancelled (a new approval is required before it re-enables).

      -

      Jamie: Let's pause on Cancelling Auto-Merge. What should a learner take away from it?

      -

      Alex: The reason Cancelling Auto-Merge matters is that auto-merge is only available if the repository administrator has enabled it in Settings → General. That gives the learner a simple foothold: many open source repos have it on; some do not.

      -

      Alex: Treat examples as spoken recipes, not decorations. You may hear something like Merge box → Tab → "Disable auto-merge" button → Enter. Read the command, understand what it changes, then run it only when the repository state matches the lesson.

      -

      Alex: Keep the teaching thread moving. Start with Scenario A: "I want to review an assigned PR": Example: You are assigned to review a PR titled "Add missing NVDA shortcut to keyboard-shortcuts.md." The PR modifies docs/keyboard-shortcuts.md in the Learning Room repository and references Challenge 2. Think of it like entering a new building: first you find the lobby, then the room, then the door you actually need.

      +

      Jamie: Let's pause on Learning Cards: How PR Sharing Works. What should a learner take away from it?

      +

      Alex: Start with Learning Cards: How PR Sharing Works. There is something to understand, something to try, and something that proves the try worked.

      +

      Alex: The practical takeaway is this. 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. 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.

      +

      Alex: Keep the teaching thread moving. Start with The Learning Automation System: When you open a PR in the Learning Room, you get three types of feedback. Think of it like entering a new building: first you find the lobby, then the room, then the door you actually need.

      +

      Jamie: Let's pause on Type 1: Automated Bot Feedback (30 seconds). What should a learner take away from it?

      +

      Alex: Start with Type 1: Automated Bot Feedback (30 seconds). There is something to understand, something to try, and something that proves the try worked.

      +

      Alex: The practical takeaway is this. 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.

      -

      Jamie: Let's pause on Scenario B: "I want to respond to review feedback on my PR". What should a learner take away from it?

      -

      Alex: Here is the plain-English version of Scenario B: "I want to respond to review feedback on my PR". Example: Your PR for Challenge 3 (Complete Welcome Guide) received a review comment: "The [TODO] about evaluating issues is good, but the paragraph could mention checking if the issue is already assigned." The validation bot also flagged a link text issue.

      -

      Alex: Keep the teaching thread moving. This is where Writing PR Descriptions That Get Reviewed becomes real: see also: Appendix C: Markdown Reference for formatting your PR description with headings, lists, and task lists. That matters in practice: A pull request is only as useful as its description.

      -

      Jamie: Let's pause on What Reviewers Look For. What should a learner take away from it?

      -

      Alex: Keep the learner anchored in What Reviewers Look For. When a reviewer opens your PR, they are asking four questions before they ever look at the diff. This is the part to say slowly: If your description answers all four, the reviewer can jump straight into the code with context.

      -

      Alex: First, why does this change exist? -- What problem does it solve, or what goal does it advance? Then, what is the scope? -- Which files changed, and roughly how big is the change? After that, how was it tested? -- Did you verify that the change works, and how? Finally, what should I pay attention to? -- Are there tricky parts, trade-offs, or areas where you want a second opinion? It is like walking a hallway with named doors: read the sign, enter the right room, then confirm where you landed.

      +

      Alex: Keep the teaching thread moving. Start with Type 2: Peer Reviewer Feedback (15-60 minutes). There is something to understand, something to try, and something that proves the try worked.

      +

      Alex: The practical takeaway is this. Human judgment on content. Creative suggestions. Encouragement and mentorship. Understanding of context. Can approve, request changes, or comment.

      +

      Jamie: Let's pause on Type 3: Progress Tracking (on merge). What should a learner take away from it?

      +

      Alex: Keep the learner anchored in Type 3: Progress Tracking (on merge). Together: Instant technical feedback + human mentorship + visible progress.

      +

      Alex: The practical takeaway is this. Skill badges (Markdown Master, Accessibility Advocate). Level progression (Beginner → Intermediate → Advanced → Expert). Milestone celebrations (1st, 5th, 10th PR). Motivational comments.

      +

      Jamie: Let's pause on Study Groups (Optional). What should a learner take away from it?

      +

      Alex: The reason Study Groups (Optional) matters is that 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. The interface gets friendlier when it stops being a wall of controls and starts being a set of named places.

      +

      Alex: First, group Issue Thread - Private communication space for your group. Then, shared Review Responsibility - You review each other's work. After that, collaborative Challenges - Optional group exercises. Finally, peer Support - Tag each other with questions. The rhythm is simple: orient, act, verify, then continue.

      -

      Alex: Keep the teaching thread moving. The reason The Closes XX Pattern matters is that GitHub recognizes special keywords in PR descriptions that automatically close linked issues when the PR merges. That gives the learner a simple foothold: you do not need to close issues by hand -- just include the right keyword followed by the issue number. The interface gets friendlier when it stops being a wall of controls and starts being a set of named places.

      -

      Jamie: What is the pre-flight check here?

      -

      Alex: Start with Before/After Structure: One of the most effective patterns for PR descriptions is showing the state before your change and the state after. The next useful detail is this: This gives the reviewer an instant mental model of what changed without reading the diff line by line.

      -

      Alex: Keep the teaching thread moving. Here is the plain-English version of A PR Description Template. Here is a template you can copy into your PR descriptions. Put another way, not every section applies to every PR, but filling in even a few sentences per section makes a meaningful difference.

      +

      Jamie: Can you translate that into plain choices?

      +

      Alex: Start with Key Differences: Skills Module vs. Your Learning Room. There is something to understand, something to try, and something that proves the try worked.

      +

      Alex: Use the comparison to make a decision, not to recite a table. The main contrasts are: GitHub Skills (Your Account) means Your Learning Room (Classroom). Your personal copy of a Skills repo means Your private copy of learning-room-template. Mona (GitHub) means Aria (PR validation) and the Student Progression bot.

      +

      Alex: Keep the teaching thread moving. Here is the plain-English version of 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. Put another way, here is how to find the PRs they want you to look at.

      +

      Jamie: Let's pause on Finding PRs to Review. What should a learner take away from it?

      +

      Alex: This is where Finding PRs to Review becomes real: screen reader users (VoiceOver - macOS).

      +

      Alex: First, go to your peer's Learning Room repo (the URL the facilitators sent you, or open it from your GitHub Notifications inbox). Then, click the Pull Requests tab. After that, click the Filters dropdown - "Review requested" - your username. Finally, click any PR title to open it. It is a checklist, but a meaningful one: every item creates evidence that the next step is safe.

      +

      Alex: Treat examples as spoken recipes, not decorations. You may hear something like 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. 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. Read the command, understand what it changes, then run it only when the repository state matches the lesson.

      -

      Jamie: Let's pause on Common Description Mistakes. What should a learner take away from it?

      -

      Alex: This is where Common Description Mistakes becomes real: even experienced contributors make these mistakes. That matters in practice: Knowing what to avoid is half the battle.

      -

      Alex: Keep the teaching thread moving. Keep the learner anchored in Good vs. Bad: Side by Side. No context, no linked issue, no explanation of what file or what was wrong with it. This is the part to say slowly: A reviewer seeing this has to open the diff, figure out which file changed, read every line, and guess at the intent. A good GitHub workflow is like a well-run meeting: everyone knows the topic, the next action, and who has the floor.

      -

      Jamie: Let's pause on Learning Cards: Writing PR Descriptions That Get Reviewed. What should a learner take away from it?

      -

      Alex: Start with Learning Cards: Writing PR Descriptions That Get Reviewed. There is something to understand, something to try, and something that proves the try worked.

      -

      Alex: The practical takeaway is this. Use Markdown headings ( ) in your description (Summary, Changes, Related Issues, Testing) so reviewers can press H to jump between sections. Type Closes followed by the issue number to auto-close the linked issue on merge; GitHub autocompletes when you type. Press Ctrl+Shift+P in the description text area to toggle between Write and Preview modes; Preview renders your Markdown so you can check structure before submitting. Use the Preview tab to verify your Markdown renders correctly; headings, bullet lists, and code blocks are easier to proofread in rendered form. Keep bullet points short (one line each) so the description is scannable at high zoom without excessive horizontal scrolling. When including screenshots, add alt text in the Markdown image syntax: so every reader gets the same information.

      +

      Alex: Keep the teaching thread moving. Keep the learner anchored in Reading a PR You're Assigned To. Screen reader users (VoiceOver - macOS). A good GitHub workflow is like a well-run meeting: everyone knows the topic, the next action, and who has the floor.

      +

      Alex: The practical takeaway is this. 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.

      +

      Jamie: Let's pause on Leaving a Review. What should a learner take away from it?

      +

      Alex: The reason Leaving a Review matters is that screen reader users (VoiceOver - macOS).

      +

      Alex: First, scroll to the comment box on the Conversation tab. Then, type your review comment. After that, click "Review Changes" (top-right of the Files Changed tab, or at the bottom of the PR page). Finally, select your review type: Comment / Approve / Request changes. The rhythm is simple: orient, act, verify, then continue.

      +

      Jamie: Before we leave Leaving a Review, what is the practical point?

      +

      Alex: First, click "Submit review". Think of it as a rail line: each stop confirms you are still on the right route before the next one.

      +

      Alex: Treat examples as spoken recipes, not decorations. You may hear something like 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". Read the command, understand what it changes, then run it only when the repository state matches the lesson.

      +

      Jamie: Let's pause on Responding to Feedback. What should a learner take away from it?

      +

      Alex: Start with Responding to Feedback: Screen reader users (VoiceOver - macOS).

      +

      Alex: First, open your PR (Pull Requests tab → click your PR). Then, read all comments and bot feedback. After that, click in the comment box to reply. Finally, push your fixes to the same branch. Think of it as a rail line: each stop confirms you are still on the right route before the next one.

      +

      Jamie: Before we leave Responding to Feedback, what is the practical point?

      +

      Alex: First, comment: "Updates pushed, ready for review". Treat it like a recipe: do not add the next ingredient until the previous one is actually in the bowl.

      +

      Alex: Treat examples as spoken recipes, not decorations. You may hear something like 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". Read the command, understand what it changes, then run it only when the repository state matches the lesson.

      -

      Jamie: Let's pause on Try It: Read a Real Pull Request. What should a learner take away from it?

      -

      Alex: Start with Try It: Read a Real Pull Request: Time: 3 minutes What you need: Browser, signed in to GitHub. The next useful detail is this: Go to the Learning Room repository's Pull Requests tab and find any open or recently closed PR.

      -

      Alex: First, navigate to Pull Requests (G then P in Focus Mode). Then, open the first PR in the list (press Enter on its title). After that, read the description - press 2 to jump to the first section heading, then arrow down to read. Look for: which file was changed (docs/welcome.md, docs/keyboard-shortcuts.md, or docs/setup-guide.md)? Which challenge was this PR solving? Does the description. Finally, check the conversation - press 3 to jump between comments. Read what the validation bot reported - did the bot find any accessibility issues like broken headings or non-descriptive links? How did the author respond? Think of it as a rail line: each stop confirms you are still on the right route before the next one.

      -

      Jamie: Before we leave Try It: Read a Real Pull Request, what is the practical point?

      -

      Alex: First, look at the diff - press D to the "Pull request tabs" landmark, then navigate to "Files changed" and press Enter. Press H to scan the changed file headings. If the PR touched docs/welcome.md, you should see + lines where the [TODO] sections were filled in. If. Treat it like a recipe: do not add the next ingredient until the previous one is actually in the bowl.

      +

      Jamie: Let's pause on Learning Cards: Tips for PR Sharing. What should a learner take away from it?

      +

      Alex: Start with Learning Cards: Tips for PR Sharing. There is something to understand, something to try, and something that proves the try worked.

      +

      Alex: The practical takeaway is this. 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. 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.

      +

      Alex: Keep the teaching thread moving. This is where "Can I see other students' PRs?" becomes real: not inside their Learning Room repos -- those are private to each student. That matters in practice: You can see other participants' work in two ways. The workshop is closer to rehearsal than lecture. You hear the move, try the move, and then check what changed.

      +

      Alex: The practical takeaway is this. 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.

      +

      Jamie: Let's pause on "What if I don't agree with my assigned reviewer?". What should a learner take away from it?

      +

      Alex: Keep the learner anchored in "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. This is the part to say slowly: You can request additional reviewers manually.

      -

      Jamie: What should people carry with them after this?

      -

      Alex: Carry the map. Know what page or tool you are in, know which action you are taking, and know what confirmation should follow. If the confirmation is missing, pause. That pause is not wasted time; it is professional judgment.

      -

      Jamie: That is a better way to say it than just follow the steps.

      -

      Alex: Right. Steps matter, but understanding wins. That is episode 6. Next in the series is episode 7, where we keep building the same contributor muscles.

      +

      Alex: Keep the teaching thread moving. The reason "Will my PR get lost when everyone is working at once?" matters is that your repo is your own; you only see your own PRs. That gives the learner a simple foothold: Aria's feedback is on your PR alone, and any peer reviewer is specifically assigned to you.

      +

      Jamie: Let's pause on "Can I comment on someone else's PR?". What should a learner take away from it?

      +

      Alex: Start with "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. The next useful detail is this: On the public accessibility-agents repo, anyone can comment on any open PR.

      +

      Alex: Keep the teaching thread moving. Here is the plain-English version of "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. It is like learning a transit route. The names of the stops matter because they tell you whether you are still going the right direction.

      +
      +

      Jamie: Let's pause on "Can I work with a friend?". What should a learner take away from it?

      +

      Alex: This is where "Can I work with a friend?" becomes real: 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.

      +

      Alex: Keep the teaching thread moving. Keep the learner anchored in "How long does review take?". When pairings happen during a workshop block, typically 15-60 minutes. This is the part to say slowly: If a reviewer is slow, the facilitators can step in or assign someone else.

      +

      Jamie: Let's pause on "What if bot feedback is wrong?". What should a learner take away from it?

      +

      Alex: The reason "What if bot feedback is wrong?" matters is that Aria is intentionally educational, not punitive -- if you disagree with a check, the facilitators can override it. That gives the learner a simple foothold: Aria is not perfect, which is exactly why human review still matters.

      +
      +

      Alex: Keep the teaching thread moving. Start with "Do I need to complete every challenge?": The Learning Room has challenges for all skill levels. The next useful detail is this: You can pick what interests you, complete at your pace, and continue after the workshop -- your repo stays yours. Think of it like entering a new building: first you find the lobby, then the room, then the door you actually need.

      +

      Jamie: Let's pause on Celebration: You're Contributing. What should a learner take away from it?

      +

      Alex: Here is the plain-English version of Celebration: You're Contributing. Every PR you open and merge in the Learning Room is a real contribution. Put another way, you found something to improve You made a meaningful change You received feedback (technical + human) You incorporated suggestions You merged your work.

      +
      +

      Jamie: What is the final checkpoint?

      +

      Alex: You should be able to point to the evidence, explain the action, and describe what you would do next if this were a real open source project. If you can teach the move back, you have learned it.

      +

      Jamie: And if they get stuck?

      +

      Alex: Read the latest message, not the loudest worry. Check the issue, the branch, the pull request, the status check, or the bot comment. Then ask for help with those facts in hand. That is how professionals collaborate.

      -

      Episode 7: Merge Conflicts Are Not Scary

      -

      Why conflicts happen, how to read conflict markers, and resolving them confidently.

      -

      Based on: Chapter 7: Merge Conflicts Are Not Scary

      -

      Audio and transcript are being regenerated for this episode.

      +

      Day 1: Issues and Collaboration

      +

      10. Episode 5: Working with Issues

      +

      Filing, searching, filtering, commenting on, and managing GitHub issues.

      +

      Based on: Chapter 5: Working with Issues

      + + +

      Download Episode 5 (MP3)

      -Read Transcript - Episode 7: Merge Conflicts Are Not Scary +Read Transcript - Episode 5: Working with Issues

      Transcript

      -

      Alex: Welcome to episode 7 of Git Going with GitHub: Merge Conflicts Are Not Scary. I am Alex, and today we are teaching this topic as a conversation you can carry into the workshop, not as a page you have to memorize.

      -

      Jamie: And I am Jamie. I will keep pulling the lesson back to real learners, real repositories, and the evidence that proves the work happened.

      +

      Alex: Welcome back to Git Going with GitHub. This is episode 5: Working with Issues. I am Alex, and today we are turning Working with Issues from a list of instructions into a working mental model.

      +

      Jamie: And I am Jamie. I will stop us whenever the instructions sound simple on paper but might feel different with a keyboard and screen reader.

      -

      Alex: The lesson focus is Why conflicts happen, how to read conflict markers, and resolving them confidently. We will treat every step as a teachable decision, because that is what makes the skill portable.

      -

      Jamie: So we should explain the why clearly enough that the steps make sense when the learner meets them later.

      -

      Alex: That is it. If a listener only has audio right now, they should still get the complete concept and know what evidence would prove success.

      +

      Alex: Filing, searching, filtering, commenting on, and managing GitHub issues. That is the surface description. Underneath it, we are building judgment: where to focus, what to ignore, and how to verify the result.

      +

      Jamie: So we are not using the audio as a shortcut around learning. We are using it to make the learning easier to enter.

      +

      Alex: Yes. A good audio lesson gives someone enough context to try the work with confidence, even before they open the written material.

      Jamie: Okay, set the room for us. What are we walking into?

      -

      Alex: Start with Understanding, Preventing, and Resolving Conflicts: Merge conflicts sound intimidating but are a normal, manageable part of collaborative development. The next useful detail is this: This guide explains what conflicts are, how to read conflict markers, and how to resolve them - step by step.

      -

      Alex: A solid pull request habit is to separate three questions: what changed, why it changed, and what still needs review. That keeps the conversation useful instead of noisy.

      -

      Alex: The next layer is this. Here is the plain-English version of Workshop Recommendation (Chapter 7). Chapter 7 uses one controlled practice challenge so students can learn conflict resolution without high-pressure scenarios. It is like learning a transit route. The names of the stops matter because they tell you whether you are still going the right direction.

      -

      Alex: The practical anchors are these. There are 1. Time: under 10 minutes. The evidence is issue-linked PR and completion comment. The pattern is observe, resolve, verify.

      +

      Alex: Start with Filing, Managing, and Participating in GitHub Issues: Issues are where open source collaboration begins. The next useful detail is this: everything from finding the right issue to file a perfect bug report - all with your keyboard and screen reader.

      +

      Alex: A solid issue habit is to read the title, the body, and the timeline before acting. You are listening for the requested action, the missing evidence, and the person who needs a response.

      +

      Alex: The next layer is this. Here is the plain-English version of Workshop Recommendation (Chapter 5 / Challenges 2-3). Chapter 5 is the first issue-based challenge chapter with short, confidence-building tasks. Put another way, it supports Challenge 2 (File Your First Issue) and Challenge 3 (Join the Conversation). It is like learning a transit route. The names of the stops matter because they tell you whether you are still going the right direction.

      +

      Alex: The practical anchors are these. There are 2 core challenges plus one optional extension. Each challenge should take under 10 minutes. The evidence is issue comments and issue metadata. The pattern is claim - act - confirm.

      Jamie: What does the learner do first, second, and then after that?

      -

      Alex: This is where Chapter 7 Challenge Set becomes real: use a short-lived feature branch: fix/yourname-issueXX (for example, fix/maria-issue48). That matters in practice: The same pattern you used in Chapter 6.

      -

      Alex: First, resolve conflict markers - identify and clean up conflict markers in a practice file, then open a linked PR. It is a checklist, but a meaningful one: every item creates evidence that the next step is safe.

      +

      Alex: This is where Chapter 5 Challenge Set becomes real: chapter 5 focuses on issue skills. That matters in practice: You do NOT need to create a branch or edit any files for these challenges.

      +

      Alex: First, create your first issue - file a new issue with a clear title and description. Then, comment and @mention - leave a comment on a classmate's issue and tag them with an @mention. After that, optional extension: Add a sub-issue - break a larger issue into smaller, trackable pieces if your repository has sub-issues enabled. It is a checklist, but a meaningful one: every item creates evidence that the next step is safe.

      Jamie: Turn that into a path someone can follow.

      -

      Alex: Keep the learner anchored in Challenge 7.1 Step-by-Step: Resolve Conflict Markers. Identify the three types of conflict markers in a practice file, decide which content to keep, remove the markers, and submit a clean PR. This is the part to say slowly: Sometimes an AI agent will confidently generate code that conflicts with human-written code.

      -

      Alex: For a learner, the useful signals are these. Keep only your version,. Keep only their version,. Combine both versions into one clean paragraph. The <<<<<<< HEAD line (or similar).

      -

      Alex: First, open the practice file specified in your challenge issue. Then, search the file for <<<<<<<. This is the start marker - it shows where the conflict begins. After that, read the content between <<<<<<< and =======. This is your version (the current branch). Finally, read the content between ======= and. This is their version (the incoming branch). It is like walking a hallway with named doors: read the sign, enter the right room, then confirm where you landed.

      +

      Alex: Keep the learner anchored in Challenge 2 Step-by-Step: Create Your First Issue. File a new issue in your Learning Room repository with a specific title and a meaningful description. This is the part to say slowly: Issues are the prompts that wake up AI.

      +

      Alex: For a learner, the useful signals are these. "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". What the problem is or what content is missing.

      +

      Alex: First, open your Learning Room repository in your browser. Then, navigate to the Issues tab (press G then I to jump there with keyboard shortcuts, or find the "Issues" link in the repository navigation). After that, activate the New issue button. Finally, if a template picker appears, select Open a blank issue (or choose a template if one fits). It is like walking a hallway with named doors: read the sign, enter the right room, then confirm where you landed.

      Jamie: What is the ordered workflow?

      -

      Alex: First, decide which content to keep. Then, delete all three marker lines. After that, review the file to confirm no marker lines remain. Search for <<<<<<< again - there should be zero results. Finally, commit your changes on a branch named fix/yourname-issueXX. The rhythm is simple: orient, act, verify, then continue.

      -

      Jamie: What makes this practice feel low-stakes but still real?

      -

      Alex: The reason Completing Chapter 7: Submit Your Evidence matters is that when your PR is open and passing checks, post a comment on your assigned Chapter 7 challenge issue.

      +

      Alex: First, in the Title field, type a clear, specific title (at least 12 characters). Then, in the Body field, write a meaningful description (at least 80 characters). After that, activate Submit new issue. Finally, copy the issue URL or note the issue number (for example, 150). You will reference this later. The rhythm is simple: orient, act, verify, then continue.

      +

      Jamie: Give me the sequence, because order matters here.

      +

      Alex: The reason Challenge 4.2 Step-by-Step: Comment and @Mention matters is that leave a comment on another student's issue and use an @mention to notify them. That gives the learner a simple foothold: the Issues tab of your Learning Room repository on GitHub.com.

      +

      Alex: The parts worth keeping in working memory are these. "@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.".

      +

      Alex: First, open the Issues tab in your Learning Room repository. Then, find an issue created by a classmate (look for issues from Challenge 4.1, or browse recent open issues). After that, open the issue by activating its title link. Finally, read the issue description to understand what they reported. The rhythm is simple: orient, act, verify, then continue.

      +

      Jamie: How would you walk the room through that step by step?

      +

      Alex: First, scroll to the comment box at the bottom of the issue. Then, write a helpful comment that @mentions the issue author by username. After that, activate the Comment button (or press Ctrl+Enter). Think of it as a rail line: each stop confirms you are still on the right route before the next one.

      Alex: The useful habit is simple: orient first, act second, verify third. That pause before acting is part of the work.

      -

      Alex: That matters because of the next idea. Start with Expected Outcomes. There is something to understand, something to try, and something that proves the try worked.

      -

      Alex: On the ground, that means a few things. Student can identify the three conflict marker lines ( ) immediately. Student can read both sides of a conflict and make an intentional content decision. Student can remove all markers and submit a clean, issue-linked PR.

      +

      Jamie: Let's pause on Challenge 4.3 Step-by-Step: Add a Sub-Issue. What should a learner take away from it?

      +

      Alex: Start with Challenge 4.3 Step-by-Step: Add a Sub-Issue: Break a larger issue into smaller, trackable pieces using GitHub's sub-issue feature. The next useful detail is this: the issue you created in Challenge 4.1 (or any open issue you have permission to edit). Think of it like entering a new building: first you find the lobby, then the room, then the door you actually need.

      +

      Alex: On the ground, that means a few things. Sub-issue: "Add alt text to welcome banner image". Sub-issue: "Fix heading hierarchy in Getting Started section".

      +

      Alex: First, open the issue you created in Challenge 4.1. Then, 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. After that, activate Add sub-issue and choose Create new sub-issue. Finally, 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". Think of it as a rail line: each stop confirms you are still on the right route before the next one.

      +

      Jamie: Before we leave Challenge 4.3 Step-by-Step: Add a Sub-Issue, what is the practical point?

      +

      Alex: First, add a short description and activate Create. Then, the sub-issue now appears nested under the parent issue with a progress indicator. Treat it like a recipe: do not add the next ingredient until the previous one is actually in the bowl.

      -

      Jamie: How would you walk the room through that step by step?

      +

      Jamie: What should the learner prove to themselves after each small task?

      +

      Alex: Here is the plain-English version of 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. Put another way, replace [number] with the actual issue numbers.

      +

      Alex: This is where the talk moves from concept to action. Start with Expected Outcomes. There is something to understand, something to try, and something that proves the try worked.

      +

      Alex: The room should hear these as checkpoints. 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.

      +

      Jamie: Let's pause on If You Get Stuck. What should a learner take away from it?

      Alex: Start with If You Get Stuck. There is something to understand, something to try, and something that proves the try worked.

      -

      Alex: First, can't find the markers? Use Ctrl+F and search for <<<<<<< - they are always in sets of three. Then, not sure which side to keep? Read both versions aloud. Pick the one that is clearer, or combine them. After that, accidentally deleted too much? Undo with Ctrl+Z and start the section over. Finally, pR bot says content is wrong? Double-check that zero marker lines remain - search for. Treat it like a recipe: do not add the next ingredient until the previous one is actually in the bowl.

      -

      Jamie: Give me the sequence, because order matters here.

      -

      Alex: First, ask facilitator to sanity-check your final content before opening the PR. Then, finished but not sure you did it right? Compare your work against the Challenge 7 reference solution. It is a checklist, but a meaningful one: every item creates evidence that the next step is safe.

      -

      Alex: This is where the talk moves from concept to action. This is where Learning Moment becomes real: they are a normal collaboration checkpoint and a chance to make an intentional content decision. That matters in practice: In real open source projects, conflicts happen whenever two people edit near the same lines.

      +

      Alex: First, can't find a classmate's issue? Filter the Issues tab by is:open and look for recent ones. Then, @mention not working? Make sure you type @ immediately followed by the username with no space. After that, sub-issue option not visible? Ask a facilitator - the feature may need to be enabled for the repository. Finally, still stuck? Ask a facilitator for a direct issue link. It is like walking a hallway with named doors: read the sign, enter the right room, then confirm where you landed.

      +

      Jamie: Before we leave If You Get Stuck, what is the practical point?

      +

      Alex: First, finished but not sure you did it right? Compare your work against the Challenge 2 reference solution or the Challenge 3 reference solution. The rhythm is simple: orient, act, verify, then continue.

      +
      +

      Alex: Before the learner moves on. The reason Learning Moment matters is that issues are collaborative spaces, not just task lists. That gives the learner a simple foothold: an @mention tells someone "I need your attention here." Sub-issues turn vague tasks into clear checklists. The interface gets friendlier when it stops being a wall of controls and starts being a set of named places.

      Jamie: Let's pause on Learning Pattern Used in This Chapter. What should a learner take away from it?

      Alex: Start with Learning Pattern Used in This Chapter. There is something to understand, something to try, and something that proves the try worked.

      -

      Alex: First, start with a controlled, safe conflict (practice file with known markers). Then, learn to read the conflict structure (your version vs. their version). After that, make a deliberate content decision (not just deleting randomly). Finally, submit clean evidence through the PR workflow. It is like walking a hallway with named doors: read the sign, enter the right room, then confirm where you landed.

      +

      Alex: First, start with a small, safe action (create an issue). Then, practice communication in public issue threads (@mention a peer). After that, organize work into smaller pieces (sub-issues). Finally, leave clear evidence in the issue timeline. Think of it as a rail line: each stop confirms you are still on the right route before the next one.

      Jamie: Before we leave Learning Pattern Used in This Chapter, what is the practical point?

      -

      Alex: First, build confidence for real conflicts in future contributions. The rhythm is simple: orient, act, verify, then continue.

      +

      Alex: First, build momentum for file editing and PR work in Chapter 6. Treat it like a recipe: do not add the next ingredient until the previous one is actually in the bowl.

      +

      Alex: Hold that next to this. Here is the plain-English version of About Learning Cards in This Chapter. This chapter provides learning cards: expandable blocks that offer perspective-specific guidance for different ways of working. Put another way, not every card appears at every step.

      -

      Alex: Before the learner moves on. The reason About Learning Cards in This Chapter matters is that this chapter provides learning cards: expandable blocks that offer perspective-specific guidance for different ways of working. That gives the learner a simple foothold: not every card appears at every step. The interface gets friendlier when it stops being a wall of controls and starts being a set of named places.

      -

      Jamie: What is the safe way to learn from that example?

      -

      Alex: Start with Local Git Alternative: Resolving Conflicts from Your Terminal: If you cloned the learning-room in Block 0 and prefer resolving conflicts locally. The next useful detail is this: The GitHub web conflict editor works well and is the primary method taught in this chapter.

      -

      Alex: A few details make that real. Keep the version you want (or combine both). Delete all three marker lines ( ). Save the file.

      -

      Alex: Treat examples as spoken recipes, not decorations. You may hear something like cd /Documents/learning-room; git checkout main; git pull origin main; git checkout your-branch-name; git merge main. code docs/welcome.md or your preferred editor. Read the command, understand what it changes, then run it only when the repository state matches the lesson.

      +

      Jamie: What should they understand before typing anything?

      +

      Alex: This is where Local Git Alternative: Working from Your Clone becomes real: if you cloned the learning-room in Block 0 and prefer working locally. That matters in practice: During Block 0 you cloned the Learning Room repository to your computer.

      +

      Alex: Treat examples as spoken recipes, not decorations. You may hear something like cd /Documents/learning-room or wherever you cloned it; git status should show "On branch main". 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. Read the command, understand what it changes, then run it only when the repository state matches the lesson.

      Alex: A solid Git habit is to know which branch you are on, what changed, and what confirmation you expect before you run the next command.

      -

      Alex: Hold that next to this. Here is the plain-English version of What Is a Merge Conflict? A merge conflict occurs when two people have both changed the same part of the same file in different ways, and Git cannot automatically decide which version is correct. Put another way, Git can merge changes automatically when they touch different parts of a file.

      -

      Alex: That shows up in the workshop in a few specific ways. Person A changed line 12 to say "Submit form". Person B changed line 12 to say "Send message". Git asks: which one do you want to keep?

      -
      -

      Jamie: If I am listening before the workshop starts, what should settle in my mind first?

      -

      Alex: This is where How to Prevent Conflicts (Prevention is Easier Than Resolution) becomes real: avoiding conflicts in the first place saves time and reduces stress. That matters in practice: Here are the most effective strategies.

      -

      Alex: That connects to another useful point. Keep the learner anchored in 1. Keep your branches short-lived. A branch that lives for 3 days has far fewer conflicts than one that lives for 3 weeks. A good GitHub workflow is like a well-run meeting: everyone knows the topic, the next action, and who has the floor.

      -

      Alex: The parts worth keeping in working memory are these. Target: 1-3 days from branch to merge. If a feature takes longer, break it into smaller PRs.

      -

      Jamie: What should happen before anyone copies and runs it?

      -

      Alex: The reason 2. Sync with main frequently matters is that the longer your branch diverges from main, the more likely conflicts become. That gives the learner a simple foothold: best practice: Sync daily if main is active.

      -

      Alex: Treat examples as spoken recipes, not decorations. You may hear something like From your feature branch; git fetch origin; git merge origin/main; Or: git rebase origin/main (if comfortable with rebasing). Read the command, understand what it changes, then run it only when the repository state matches the lesson.

      +

      Alex: That connects to another useful point. Keep the learner anchored in What Is a GitHub Issue? An issue is a discussion thread attached to a repository. This is the part to say slowly: Every issue has a number ( 42), a state (Open or Closed), a title, a description, and a comment thread. A good GitHub workflow is like a well-run meeting: everyone knows the topic, the next action, and who has the floor.

      +

      Alex: Here is what that changes in practice. 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".

      +

      Jamie: Let's pause on From a repository page. What should a learner take away from it?

      +

      Alex: The reason From a repository page matters is that click the Issues tab in the repository navigation bar below the repository name. That gives the learner a simple foothold: the tab shows the open issue count (e.g., "Issues · 14").

      +

      Alex: First, press D to navigate to the "Repository navigation" landmark. Then, press K or Tab to move through the tab links. After that, find "Issues" - it will be announced with the count: "Issues, 14 open". Finally, press Enter to open the Issues tab. The rhythm is simple: orient, act, verify, then continue.

      +

      Jamie: Before we leave From a repository page, what is the practical point?

      +

      Alex: First, vO+U → Landmarks → navigate to "Repository navigation". Then, vO+Right or Quick Nav K to move through tab links. After that, find "Issues" - VoiceOver announces the count: "Issues 14". Finally, vO+Space to activate the Issues tab. Think of it as a rail line: each stop confirms you are still on the right route before the next one.

      +

      Alex: Treat examples as spoken recipes, not decorations. You may hear something like gh issue list. gh issue list --label "good first issue"; gh issue list --assignee @me; gh issue list --state closed. Read the command, understand what it changes, then run it only when the repository state matches the lesson.

      -

      Alex: Here is the practical turn. Start with 3. Communicate with your team: Let others know what files you're working on. The next useful detail is this: "Heads up: I'm working on the [TODO] sections in docs/welcome.md for Challenge 3.

      +

      Alex: Here is the practical turn. Start with Direct URL: Navigate directly: https://github.com/[owner]/[repo]/issues.

      Jamie: What would you say to someone who is already bracing for this to be too much?

      -

      Alex: Here is the plain-English version of 4. Avoid mass reformatting. Running a formatter on an entire file creates conflicts with anyone else editing that file.

      -

      Alex: Here is what that changes in practice. Do it in a separate PR before functional changes. Announce it to the team. Merge it quickly so everyone can sync.

      -

      Jamie: How do you keep commands from becoming magic words?

      -

      Alex: This is where 5. Pull before you push becomes real: always fetch and merge (or pull) before pushing your changes. That matters in practice: This catches conflicts locally where they're easier to resolve. The workshop is closer to rehearsal than lecture. You hear the move, try the move, and then check what changed.

      -

      Alex: Treat examples as spoken recipes, not decorations. You may hear something like git pull origin main Sync your local main; git checkout your-branch; git merge main Merge main into your branch; git push Now push. Read the command, understand what it changes, then run it only when the repository state matches the lesson.

      +

      Alex: Start with Learning Cards: Navigating to the Issues List. There is something to understand, something to try, and something that proves the try worked.

      +

      Alex: These are the details that keep the idea from floating away. 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. 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.

      +

      Alex: Keep the thread going. This is where Page structure becomes real: 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. That matters in practice: This is often faster than tabbing through many elements and helps you understand the full page structure before diving in. The workshop is closer to rehearsal than lecture. You hear the move, try the move, and then check what changed.

      +

      Jamie: Let's pause on How to read the issue list. What should a learner take away from it?

      +

      Alex: Keep the learner anchored in How to read the issue list. The issues list shows each issue as a row with its title, labels, number, assignee avatars, and comment count. This is the part to say slowly: Closed issues show a purple merged/closed badge.

      +

      Alex: That becomes easier when you listen for these cues. 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.

      +

      Alex: First, press D to reach the "Search Results List" landmark. Then, press 3 (h3) to navigate by issue titles - each issue title is an h3 link. After that, press I to move between list items if you want more detail per item. Finally, press Enter on a title to open that issue. It is like walking a hallway with named doors: read the sign, enter the right room, then confirm where you landed.

      +

      Jamie: Before we leave How to read the issue list, what is the practical point?

      +

      Alex: First, vO+U → Landmarks → navigate to "Search Results List". Then, vO+Down to read through items. After that, h (with Quick Nav on) or VO+U → Headings to jump by issue title. The rhythm is simple: orient, act, verify, then continue.

      +

      Alex: Another way to ground it. The reason What is announced per issue matters is that when you navigate to an issue in the list, your screen reader will announce (in some order).

      +

      Alex: A few details make that real. 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").

      Jamie: What is the one idea that makes the next few steps less mysterious?

      -

      Alex: Keep the learner anchored in 6. Work on separate files when possible. If multiple people are working simultaneously, divide tasks by files or modules rather than everyone touching the same code.

      -

      Alex: Another way to ground it. The reason 7. Keep PRs small matters is that a 50-file PR will almost certainly conflict with something. That gives the learner a simple foothold: a 5-file PR merges quickly and cleanly.

      -

      Jamie: Where do you want a learner to place their attention here?

      -

      Alex: Start with 8. Use Draft PRs for early visibility: Open your PR as a draft while still working. The next useful detail is this: Others can see what you're changing and avoid overlapping work.

      +

      Alex: Start with Learning Cards: The Issues List Page. There is something to understand, something to try, and something that proves the try worked.

      +

      Alex: That shows up in the workshop in a few specific ways. 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. 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.

      -

      Alex: This is the part worth saying out loud. Start with Learning Cards: How to Prevent Conflicts. There is something to understand, something to try, and something that proves the try worked.

      -

      Alex: The room should hear these as checkpoints. Before starting work, run git pull origin main in VS Code's terminal ( Ctrl+ `) to sync your branch; this prevents conflicts from stale branches. On GitHub, check the PR's merge status section by pressing D toward the bottom of the Conversation tab; "This branch has conflicts" warns you before you waste review time. Use issue comments to announce which files you are editing; press D to the "Add a comment" landmark on the issue and type your coordination message. The "Update branch" button on a PR appears near the merge section at the bottom of the Conversation tab; it has a white-on-green style when available. When multiple students are editing the same file, GitHub shows a yellow conflict banner; zoom in on the merge area to check for it before requesting review. Draft PRs show a grey "Draft" badge in the PR list; opening drafts early gives teammates visibility into which files you are changing.

      -

      Jamie: What should they understand before typing anything?

      -

      Alex: This is where Advanced Prevention: Understanding Fast-Forward Merges becomes real: when your branch is perfectly up to date with main and adds new commits on top, GitHub can do a "fast-forward" merge - main simply moves forward to your latest commit. That matters in practice: How to achieve this: Rebase your branch on main right before merging.

      -

      Alex: Treat examples as spoken recipes, not decorations. You may hear something like git checkout your-branch; git fetch origin; git rebase origin/main; git push --force-with-lease See warning below about force pushing. Read the command, understand what it changes, then run it only when the repository state matches the lesson.

      -

      Alex: Now bring the learner back to the room. Keep the learner anchored in When Conflicts Are Actually Good. Conflicts indicate that multiple people are actively improving the project. This is the part to say slowly: In a healthy, collaborative environment, occasional conflicts are normal and manageable.

      -

      Alex: These are the details that keep the idea from floating away. You're the only contributor (less review, less learning). PRs are moving too slowly (stagnation). People are avoiding working on important files (technical debt).

      +

      Alex: This is the part worth saying out loud. Here is the plain-English version of Filtering and Searching Issues. Filtering lets you narrow the list to find the right issue quickly. It is like learning a transit route. The names of the stops matter because they tell you whether you are still going the right direction.

      +

      Jamie: Let's pause on Using the search/filter bar. What should a learner take away from it?

      +

      Alex: Start with Using the search/filter bar. There is something to understand, something to try, and something that proves the try worked.

      +

      Alex: First, press F or E to jump to the filter input field (or navigate from the landmark). Then, switch to Focus Mode (NVDA+Space / Insert+Z) if not already in it. After that, type your filter or search query. Finally, press Enter to apply. It is a checklist, but a meaningful one: every item creates evidence that the next step is safe.

      +

      Jamie: Let's pause on Using the filter buttons. What should a learner take away from it?

      +

      Alex: Keep the learner anchored in Using the filter buttons. Above the issue list, there is an actions toolbar with filter buttons for Labels, Milestones, Assignees, etc. This is the part to say slowly: The filter buttons do not indicate the current filter state.

      +

      Alex: The practical takeaway is this. 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.

      +

      Alex: First, press Tab from the search bar (or Shift+Tab from the issue list) to reach the actions toolbar. Then, press ←/→ to move between toolbar options (Label, Milestone, Assignee, Sort). After that, press Enter to open the selected dropdown. Finally, use ↑/↓ to navigate options in the dropdown. It is like walking a hallway with named doors: read the sign, enter the right room, then confirm where you landed.

      +

      Jamie: Before we leave Using the filter buttons, what is the practical point?

      +

      Alex: First, press Enter or Space to select. Then, press Escape to close (filter applies immediately). After that, tab forward from the search bar to reach the filter buttons, or use Quick Nav to find them. Finally, vO+Left/Right to move between Label, Milestone, Assignee, Sort buttons. The rhythm is simple: orient, act, verify, then continue.

      +

      Alex: Treat examples as spoken recipes, not decorations. You may hear something like 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". Read the command, understand what it changes, then run it only when the repository state matches the lesson.

      -

      Jamie: Let's pause on Tool Cards: Resolve a Merge Conflict. What should a learner take away from it?

      -

      Alex: The reason Tool Cards: Resolve a Merge Conflict matters is that when a PR has a merge conflict, you will see this message on the Conversation tab, near the merge section. That gives the learner a simple foothold: "This branch has conflicts that must be resolved".

      -

      Alex: That becomes easier when you listen for these cues. The banner uses a yellow or orange background. In Windows High Contrast mode, it renders with the system alert color so it remains visible. The Resolve conflicts button is a standard link-style button. If it is hard to target at high zoom, use Tab to reach it after the merge status section and press Enter. If the button does not appear, you may lack write access to the repository. Ask the PR author or a maintainer for help.

      -

      Alex: First, on the PR page, click Resolve conflicts if the button is available. Then, edit the file in the web editor to remove conflict markers. After that, click Mark as resolved, then Commit merge. Finally, open the PR's branch by pressing. on the repository page. The rhythm is simple: orient, act, verify, then continue.

      -

      Jamie: Before we leave Tool Cards: Resolve a Merge Conflict, what is the practical point?

      -

      Alex: First, open the conflicting file -- conflict markers are highlighted in the editor. Then, edit to resolve, commit via Source Control panel. After that, pull the latest changes: git pull origin main. Finally, VS Code highlights conflicts with Accept Current / Accept Incoming / Accept Both buttons. Think of it as a rail line: each stop confirms you are still on the right route before the next one.

      -

      Alex: Treat examples as spoken recipes, not decorations. You may hear something like git merge main; Edit conflicting files to remove; git add resolved-file.md; git commit -m "resolve merge conflict". Read the command, understand what it changes, then run it only when the repository state matches the lesson.

      -

      Alex: Keep the thread going. Start with Conflict Markers - What They Mean: When conflict markers appear in a file, your editor is showing you both versions of the conflicted content so you can choose. Think of it like entering a new building: first you find the lobby, then the room, then the door you actually need.

      -

      Jamie: Give me the version that sounds like an instructor, not a manual.

      -

      Alex: Start with Breakdown. There is something to understand, something to try, and something that proves the try worked.

      -

      Alex: The practical takeaway is this. <<<<<<< HEAD - the start of YOUR version (HEAD = "the branch you are currently on"). ======= - the dividing line between the two versions. branch-name - the end of the INCOMING version (from the branch being merged in).

      +

      Jamie: If I am listening before the workshop starts, what should settle in my mind first?

      +

      Alex: The reason Open vs Closed filter matters is that the two state links "Open" and "Closed" appear near the top of the issue list. That gives the learner a simple foothold: press K to navigate links until you find them, or look for them as buttons near the search bar.

      +

      Alex: Now bring the learner back to the room. Start with Learning Cards: Filtering and Searching Issues. There is something to understand, something to try, and something that proves the try worked.

      +

      Alex: The practical takeaway is this. 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. 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.

      +

      Jamie: Where do you want a learner to place their attention here?

      +

      Alex: Here is the plain-English version of Landing on an issue page. When you open an issue, the page structure is.

      -

      Jamie: Let's pause on After two students both added a shortcut to the same table row. What should a learner take away from it?

      -

      Alex: Start with After two students both added a shortcut to the same table row. There is something to understand, something to try, and something that proves the try worked.

      -

      Alex: Treat examples as spoken recipes, not decorations. You may hear something like add-nvda-shortcut. Read the command, understand what it changes, then run it only when the repository state matches the lesson.

      -

      Jamie: Let's pause on Resolution options. What should a learner take away from it?

      -

      Alex: Start with Resolution options. There is something to understand, something to try, and something that proves the try worked.

      -

      Alex: First, keep your version: add only Insert+F5. Then, keep their version: add only Insert+F7. After that, keep both rows: add both shortcuts to the table (often the right answer when two students added different valid shortcuts). It is like walking a hallway with named doors: read the sign, enter the right room, then confirm where you landed.

      -

      Alex: Keep the teaching thread moving. Start with Learning Cards: Conflict Markers. There is something to understand, something to try, and something that proves the try worked.

      -

      Alex: The practical takeaway is this. Conflict markers are three lines: branch-name; your screen reader may spell out each character individually. Everything between is the INCOMING version. After resolving, search the file for <<<< using Ctrl+F to verify no markers remain; any leftover markers will break the file. In GitHub's conflict editor, each version is highlighted with a different background color (typically green for yours, blue for incoming); high-contrast themes use bolder system colors. The three marker lines ( ) span the full width of the editor; look for rows that contain only repeated symbols. After resolving, zoom in on the edited area and confirm the marker lines are completely deleted, not just partially removed.

      +

      Jamie: Let's pause on Reading the issue description. What should a learner take away from it?

      +

      Alex: This is where Reading the issue description becomes real: browse Mode recommended: The issue detail page is primarily text-based. That matters in practice: Stay in Browse Mode (not Focus Mode) for reading - it gives you full heading (H), section (D), and link (K) navigation throughout the page.

      +

      Alex: First, press 2 to reach the "Description" heading. Then, press ↓ to read the content line by line,. After that, use NVDA+↓ (NVDA say all) to have it read continuously. It is a checklist, but a meaningful one: every item creates evidence that the next step is safe.

      +

      Alex: Treat examples as spoken recipes, not decorations. You may hear something like 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. Read the command, understand what it changes, then run it only when the repository state matches the lesson.

      +

      Jamie: Give me the version that sounds like an instructor, not a manual.

      +

      Alex: Keep the learner anchored in Reading comments and activity. Each comment in the thread is marked as an h3. This is the part to say slowly: Other timeline events (label added, PR linked, issue closed) appear between comments in the activity stream.

      +

      Alex: The practical takeaway is this. Commenter's username. Timestamp ("2 days ago"). Body text. Reactions (if any - announced as a button with an emoji and count).

      +

      Alex: That matters because of the next idea. Start with Learning Cards: Reading an Issue. There is something to understand, something to try, and something that proves the try worked.

      +

      Alex: The practical takeaway is this. 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. 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.

      -

      Jamie: Let's pause on Resolving Conflicts on GitHub (Web Editor). What should a learner take away from it?

      -

      Alex: Start with Resolving Conflicts on GitHub (Web Editor): GitHub has a built-in conflict editor that you can use without any local tools.

      -

      Jamie: Let's pause on Step-by-step: GitHub Conflict Editor. What should a learner take away from it?

      -

      Alex: Here is the plain-English version of Step-by-step: GitHub Conflict Editor. Low vision users (zoom, high contrast). Put another way, increase your browser's minimum font size (Settings, Appearance, Font size) for a more comfortable editing experience in the conflict editor.

      -

      Alex: The practical takeaway is this. <<<<<<< HEAD marks the start of your version. ======= is the dividing line. branch-name marks the end of the incoming version.

      -

      Alex: First, click Resolve conflicts on the PR Conversation tab. Then, GitHub opens a full-page text editor showing each conflicted file. After that, the conflict markers are highlighted - everything between is the incoming version. Finally, edit the content directly: delete the lines you don't want, including the three marker lines ( ). Treat it like a recipe: do not add the next ingredient until the previous one is actually in the bowl.

      -

      Jamie: Before we leave Step-by-step: GitHub Conflict Editor, what is the practical point?

      -

      Alex: First, when the file looks correct, click Mark as resolved (top-right of the file). Then, if there are multiple conflicted files, a file list on the left lets you jump between them. After that, after all files are resolved, click Commit merge. Finally, open the conflict editor from the Resolve conflicts button on the PR Conversation tab. It is a checklist, but a meaningful one: every item creates evidence that the next step is safe.

      -

      Jamie: Let's pause on What it looks like in the editor. What should a learner take away from it?

      -

      Alex: This is where What it looks like in the editor becomes real: when the conflict editor opens, your screen reader will announce a text editor. That matters in practice: In Focus Mode, navigate with arrow keys.

      +

      Jamie: Let's pause on Step-by-step. What should a learner take away from it?

      +

      Alex: Start with Step-by-step: To close the issue while commenting: click the arrow on the Close issue button and choose Close with comment. The next useful detail is this: Low vision users (zoom, high contrast).

      +

      Alex: First, scroll to the bottom of the issue page. Then, click in the Leave a comment text area. After that, type your comment (Markdown is supported - use the toolbar buttons above the text for bold, italic, code, etc.). Finally, optionally click Preview to see how it will render. Think of it as a rail line: each stop confirms you are still on the right route before the next one.

      +

      Jamie: Before we leave Step-by-step, what is the practical point?

      +

      Alex: First, click the green Comment button to post. Then, scroll to the bottom to find the Leave a comment text area. At 200%+ zoom, this may require significant scrolling past the timeline. After that, the text area expands as you type. The formatting toolbar above it (bold, italic, code, etc.) wraps at high zoom but remains functional. Finally, the Preview tab next to Write lets you check Markdown rendering before posting. Treat it like a recipe: do not add the next ingredient until the previous one is actually in the bowl.

      +

      Alex: Treat examples as spoken recipes, not decorations. You may hear something like 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.". Read the command, understand what it changes, then run it only when the repository state matches the lesson.

      +

      Alex: Keep the teaching thread moving. Here is the plain-English version of Markdown formatting while typing. These keyboard shortcuts work inside the text area (Focus Mode).

      +

      Jamie: Let's pause on GitHub shortcuts for the Issues pages. What should a learner take away from it?

      +

      Alex: This is where GitHub shortcuts for the Issues pages becomes real: these are the GitHub built-in shortcuts for working with issues. That matters in practice: Enable Focus Mode first (NVDA: NVDA+Space, JAWS: Insert+Z) before using single-key shortcuts.

      -

      Alex: Keep the teaching thread moving. Start with Learning Cards: Resolving Conflicts on GitHub. There is something to understand, something to try, and something that proves the try worked.

      -

      Alex: The practical takeaway is this. 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. 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.

      -

      Jamie: Where is the promise of the workshop, underneath all the logistics?

      -

      Alex: The reason Resolving Conflicts in VS Code (Day 2) matters is that see also: Appendix E: Advanced Git covers rebase, cherry-pick, and other advanced conflict resolution strategies. That gives the learner a simple foothold: VS Code has excellent merge conflict tooling with full screen reader support.

      -

      Jamie: Let's pause on VS Code merge conflict actions. What should a learner take away from it?

      -

      Alex: Start with VS Code merge conflict actions: When your cursor is on a conflict region, VS Code shows CodeLens action links above the conflict block in the editor. The next useful detail is this: The conflict markers disappear and your chosen content remains.

      -

      Alex: The practical takeaway is this. 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.

      -

      Alex: First, open the conflicted file. Then, press ↓ to navigate to a conflict marker (<<<<<<<). After that, the CodeLens links appear above - press Tab to reach them. Finally, press Enter on your chosen action. Think of it as a rail line: each stop confirms you are still on the right route before the next one.

      -

      Jamie: Before we leave VS Code merge conflict actions, what is the practical point?

      -

      Alex: First, save the file (Ctrl+S). Then, stage the resolved file: Ctrl+Shift+G → find the file → Stage changes. After that, commit the merge. Finally, vO+Down or arrow keys to navigate to a conflict marker (<<<<<<<). Treat it like a recipe: do not add the next ingredient until the previous one is actually in the bowl.

      +

      Alex: Keep the teaching thread moving. Keep the learner anchored in On the Issues list page. Shortcut note: For G I, press G, release it, then press I (two sequential key presses, not simultaneous). A good GitHub workflow is like a well-run meeting: everyone knows the topic, the next action, and who has the floor.

      +

      Jamie: Let's pause on On an open issue. What should a learner take away from it?

      +

      Alex: The reason On an open issue matters is that r to quote is a power move: Select any text in a comment while in Browse Mode (Shift+Arrow to select), then press R. That gives the learner a simple foothold: GitHub puts the quoted text in the comment box as a Markdown blockquote.

      +

      Alex: First, navigate to your comment (3 to jump to comments). Then, find the "." (ellipsis) menu button near your comment. After that, press Enter on "Edit" from that menu. Finally, the comment turns into a text area - switch to Focus Mode. The rhythm is simple: orient, act, verify, then continue.

      +

      Jamie: Before we leave On an open issue, what is the practical point?

      +

      Alex: First, make your changes. Then, tab to "Update comment" button → Enter. Think of it as a rail line: each stop confirms you are still on the right route before the next one.

      +

      Alex: Keep the teaching thread moving. Start with Learning Cards: Leaving a Comment. There is something to understand, something to try, and something that proves the try worked.

      +

      Alex: The practical takeaway is this. 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. 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.

      -

      Jamie: Let's pause on Ask for help - it's normal. What should a learner take away from it?

      -

      Alex: Here is the plain-English version of Ask for help - it's normal. If you are unsure which version to keep.

      -

      Alex: First, 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?". Then, tag the PR author or a maintainer with @username. Treat it like a recipe: do not add the next ingredient until the previous one is actually in the bowl.

      -

      Jamie: Let's pause on Abandon and start fresh (nuclear option). What should a learner take away from it?

      -

      Alex: This is where Abandon and start fresh (nuclear option) becomes real: if a conflict is severe (the branch diverged a lot from main). That matters in practice: This is legitimate - not a failure. The workshop is closer to rehearsal than lecture. You hear the move, try the move, and then check what changed.

      -

      Alex: First, close the PR without merging. Then, start a new branch from the latest main. After that, apply only your intended changes to the new branch. Finally, open a new PR. It is a checklist, but a meaningful one: every item creates evidence that the next step is safe.

      -

      Jamie: How should someone ask for help in a way that gets them unstuck faster?

      -

      Alex: Start with Learning Cards: When You Feel Stuck. There is something to understand, something to try, and something that proves the try worked.

      -

      Alex: The practical takeaway is this. 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. 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.

      +

      Jamie: Let's pause on Navigating to New Issue. What should a learner take away from it?

      +

      Alex: Here is the plain-English version of Navigating to New Issue. From the Issues list page, click the green New issue button in the top-right of the issue list. Put another way, 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.

      +

      Alex: The practical takeaway is this. 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.

      +

      Alex: First, press K to navigate links and find the "New issue" button/link. Then, press Enter. After that, 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. Finally, quick Nav B or VO+U → Buttons to find the "New issue" button. Treat it like a recipe: do not add the next ingredient until the previous one is actually in the bowl.

      +

      Jamie: Before we leave Navigating to New Issue, what is the practical point?

      +

      Alex: First, vO+Space to activate it. Then, 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. It is a checklist, but a meaningful one: every item creates evidence that the next step is safe.

      +

      Alex: Keep the teaching thread moving. This is where Filling Out the Issue Form becomes real: the issue form has these fields (order may vary depending on the template). The workshop is closer to rehearsal than lecture. You hear the move, try the move, and then check what changed.

      +

      Jamie: Let's pause on Title field. What should a learner take away from it?

      +

      Alex: Start with Title field. There is something to understand, something to try, and something that proves the try worked.

      +

      Alex: First, find the Title input field (F or by landmark). Then, focus Mode → type a clear, specific title. After that, good title: "Screen reader announces wrong element count on Issues list with 50+ items". Finally, bad title: "Bug with screen reader". It is like walking a hallway with named doors: read the sign, enter the right room, then confirm where you landed.

      -

      Jamie: Let's pause on Reading a Conflict Message from Git (Command Line Reference). What should a learner take away from it?

      -

      Alex: The reason Reading a Conflict Message from Git (Command Line Reference) matters is that if you work locally, git merge or git pull will say. That gives the learner a simple foothold: the conflict markers are inserted into the file by Git - open the file and follow the steps above.

      -

      Alex: Treat examples as spoken recipes, not decorations. You may hear something like 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,. 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. Read the command, understand what it changes, then run it only when the repository state matches the lesson.

      -

      Jamie: Let's pause on Try It: Read a Conflict (Without Fear). What should a learner take away from it?

      -

      Alex: Start with Try It: Read a Conflict (Without Fear): Time: 2 minutes What you need: Any text editor or just read below. The next useful detail is this: The goal is not to resolve it - just to understand what you're hearing.

      -

      Alex: First, what does your branch say? (The text between <<<<<<< HEAD and =======). Then, what does the other branch say? (The text between ======= and ). After that, which version would you keep, and why? Think of it as a rail line: each stop confirms you are still on the right route before the next one.

      +

      Jamie: Let's pause on Description / Body field. What should a learner take away from it?

      +

      Alex: Start with Description / Body field. There is something to understand, something to try, and something that proves the try worked.

      +

      Alex: First, tab to the body text area. Then, focus Mode → type using the Markdown template provided. After that, if no template, use this structure. The rhythm is simple: orient, act, verify, then continue.

      +

      Alex: Treat examples as spoken recipes, not decorations. You may hear something like 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. Read the command, understand what it changes, then run it only when the repository state matches the lesson.

      +

      Jamie: Let's pause on Assigning labels from the sidebar. What should a learner take away from it?

      +

      Alex: Start with Assigning labels from the sidebar: See also: Chapter 09: Labels, Milestones, and Projects covers the full label and milestone system. The next useful detail is this: While the form is open, the sidebar has dropdowns for Labels, Assignees, and Milestone.

      +

      Alex: First, tab away from the text area (or press Escape to leave Focus Mode). Then, navigate to the sidebar - press H to find "Labels" heading. After that, press Enter on the Labels gear/button. Finally, dropdown opens → ↑/↓ to navigate labels. Think of it as a rail line: each stop confirms you are still on the right route before the next one.

      +

      Jamie: Before we leave Assigning labels from the sidebar, what is the practical point?

      +

      Alex: First, enter to select/deselect. Then, escape to close (selections save automatically). After that, vO+Shift+Up to stop interacting with the text area. Finally, vO+U → Headings to find the "Labels" heading in the sidebar. Treat it like a recipe: do not add the next ingredient until the previous one is actually in the bowl.

      +

      Alex: A solid project habit is to treat metadata as decision support. Labels, status, assignees, and notifications tell you what kind of attention the work needs.

      +

      Jamie: Let's pause on Submitting the issue. What should a learner take away from it?

      +

      Alex: Here is the plain-English version of Submitting the issue. GitHub CLI (gh) alternative - filing a new issue. Put another way, create an issue from your terminal. It is like learning a transit route. The names of the stops matter because they tell you whether you are still going the right direction.

      +

      Alex: First, tab to "Submit new issue" button. Then, press Enter. Treat it like a recipe: do not add the next ingredient until the previous one is actually in the bowl.

      +

      Alex: Treat examples as spoken recipes, not decorations. You may hear something like 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. Read the command, understand what it changes, then run it only when the repository state matches the lesson.

      -

      Jamie: What should people carry with them after this?

      -

      Alex: Carry the map. Know what page or tool you are in, know which action you are taking, and know what confirmation should follow. If the confirmation is missing, pause. That pause is not wasted time; it is professional judgment.

      -

      Jamie: That is a better way to say it than just follow the steps.

      -

      Alex: Right. Steps matter, but understanding wins. That is episode 7. Next in the series is episode 8, where we keep building the same contributor muscles.

      -
      - +

      Jamie: Let's pause on Learning Cards: Filing a New Issue. What should a learner take away from it?

      +

      Alex: Start with Learning Cards: Filing a New Issue. There is something to understand, something to try, and something that proves the try worked.

      +

      Alex: The practical takeaway is this. 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. 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.

      +

      Jamie: Let's pause on Tool Cards: File a New Issue. What should a learner take away from it?

      +

      Alex: Keep the learner anchored in Tool Cards: File a New Issue. github.dev (web editor): Not available -- issues are managed through the repository's Issues tab, not the code editor. This is the part to say slowly: VS Code Desktop (GitHub Pull Requests extension).

      +

      Alex: First, navigate to the repository's Issues tab (or press G then I). Then, click New issue, choose a template or blank issue. After that, fill in the title and description, then click Submit new issue. Finally, open the GitHub panel in the sidebar. It is like walking a hallway with named doors: read the sign, enter the right room, then confirm where you landed.

      +

      Jamie: Before we leave Tool Cards: File a New Issue, what is the practical point?

      +

      Alex: First, under Issues, click the + icon to create a new issue. Then, fill in the title and body, then click Create. The rhythm is simple: orient, act, verify, then continue.

      +

      Alex: Treat examples as spoken recipes, not decorations. You may hear something like gh issue create --title "Your title" --body "Description here"; Or interactively:; gh issue create. Read the command, understand what it changes, then run it only when the repository state matches the lesson.

      +

      Jamie: Let's pause on Cross-Referencing Issues. What should a learner take away from it?

      +

      Alex: The reason Cross-Referencing Issues matters is that linking issues and PRs to each other creates a trail of context that helps everyone understand the project's history.

      -

      Episode 8: Open Source Culture and Etiquette

      -

      Communication norms, code review etiquette, inclusive language, and asking questions.

      -

      Based on: Chapter 8: Open Source Culture and Etiquette

      -

      Audio and transcript are being regenerated for this episode.

      -
      -Read Transcript - Episode 8: Open Source Culture and Etiquette - -

      Transcript

      -

      Alex: Welcome to Git Going with GitHub, episode 8: Open Source Culture and Etiquette. I am Alex. Today we are going to make Open Source Culture and Etiquette something you can explain, practice, and recover from when the interface surprises you.

      -

      Jamie: And I am Jamie. I will be the voice of the learner who is willing to ask, what is this for, where am I, and how do I know I did it right?

      +

      Alex: Keep the teaching thread moving. Start with 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. Think of it like entering a new building: first you find the lobby, then the room, then the door you actually need.

      +

      Jamie: Let's pause on Mentioning another issue in a comment. What should a learner take away from it?

      +

      Alex: Here is the plain-English version of Mentioning another issue in a comment. Simply type followed by a number anywhere in a comment body. Put another way, GitHub autocompletes with a dropdown of matching issues and PRs.

      +

      Alex: Keep the teaching thread moving. This is where Cross-repo references becomes real: owner/repo 42 - references issue 42 in a different repository.

      -

      Alex: The big idea today: Communication norms, code review etiquette, inclusive language, and asking questions. We will name the concept, explain why it matters, practice the move, and point out the checks that tell you the work is real.

      -

      Jamie: So the episode should work even if someone has not read the chapter yet.

      -

      Alex: Exactly. The transcript has to stand on its own. It can point toward practice, but it should teach the concept right here in the conversation.

      +

      Jamie: Let's pause on Learning Cards: Cross-Referencing Issues. What should a learner take away from it?

      +

      Alex: Start with Learning Cards: Cross-Referencing Issues. There is something to understand, something to try, and something that proves the try worked.

      +

      Alex: The practical takeaway is this. 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. 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.

      +

      Alex: Keep the teaching thread moving. The reason Sub-Issues - Parent and Child Relationships matters is that sub-issues (released 2025) let you nest issues inside a parent issue to break large work into tracked pieces. That gives the learner a simple foothold: a "parent" issue contains a list of child issues; each child is a full issue with its own discussion, labels, and assignees. The interface gets friendlier when it stops being a wall of controls and starts being a set of named places.

      +

      Jamie: Can you translate that into plain choices?

      +

      Alex: Start with When to Use Sub-Issues. There is something to understand, something to try, and something that proves the try worked.

      +

      Alex: Use the comparison to make a decision, not to recite a table. The main contrasts are: Large feature broken down means Parent: "Redesign navigation"; Children: "Keyboard nav," "Screen reader nav," "Mobile nav". Epic tracking means Parent: "WCAG 2.1 AA compliance"; Children: one issue per failing criterion. Release milestone means Parent: "v2.0 release"; Children: every required PR/fix.

      -

      Jamie: Okay, set the room for us. What are we walking into?

      -

      Alex: Start with How to Be an Effective and Respectful Open Source Contributor: Technical skills get your code into a project. The next useful detail is this: Communication skills keep you welcomed in the community.

      -

      Alex: The next layer is this. Here is the plain-English version of Workshop Recommendation (Chapter 8). Chapter 8 is a communication and culture chapter. It is like learning a transit route. The names of the stops matter because they tell you whether you are still going the right direction.

      -

      Alex: The practical anchors are these. There are 1 guided reflection (no bot grading). Automation check: none - communication quality is too subjective for fair automated scoring. The evidence is structured reflection comment on your assigned challenge issue. The pattern is read, reflect, commit to one behavior.

      -

      Jamie: What does the learner do first, second, and then after that?

      -

      Alex: Start with Chapter 8 Challenge Set. There is something to understand, something to try, and something that proves the try worked.

      -

      Alex: First, guided reflection - read the chapter, then post a short reflection comment committing to three specific collaboration behaviors. It is a checklist, but a meaningful one: every item creates evidence that the next step is safe.

      +

      Alex: Keep the teaching thread moving. Here is the plain-English version of Creating a Sub-Issue. The sub-issues section is announced as a region. Put another way, after linking, the child issue appears as a list item with a checkbox showing its open/closed state.

      +

      Jamie: Let's pause on Reading Sub-Issues on a Parent Issue. What should a learner take away from it?

      +

      Alex: This is where Reading Sub-Issues on a Parent Issue becomes real: progress indicator: The parent issue shows a completion bar (e.g., "3 of 7 completed") based on how many child issues are closed. That matters in practice: Screen readers announce this as a progress region.

      +

      Alex: Keep the teaching thread moving. Keep the learner anchored in Viewing a Child Issue's Parent. Every child issue shows a "Parent issue" link near the top of the page (above the description). This is the part to say slowly: Navigate with H or links (K) to find it. A good GitHub workflow is like a well-run meeting: everyone knows the topic, the next action, and who has the floor.

      -

      Jamie: Turn that into a path someone can follow.

      -

      Alex: Keep the learner anchored in Challenge 8.1 Step-by-Step: Guided Reflection. Identify three concrete communication behaviors you will practice during the rest of the workshop. This is the part to say slowly: your assigned Chapter 8 challenge issue in your Learning Room repository on GitHub.com.

      -

      Alex: For a learner, the useful signals are these. 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.".

      -

      Alex: First, read through the chapter content below, paying attention to the sections on GitHub Flow, constructive feedback, and asking for help. Then, as you read, think about one situation from Day 1 where communication helped (or could have helped) you. After that, open your assigned Chapter 8 challenge issue (the one titled "Chapter 8.1: Guided Reflection (@yourname)"). Finally, scroll to the comment box at the bottom of the issue. It is like walking a hallway with named doors: read the sign, enter the right room, then confirm where you landed.

      -

      Jamie: What is the ordered workflow?

      -

      Alex: First, post a reflection comment using this format. Then, for each prompt, write one specific, actionable sentence - not a vague goal. After that, activate the Comment button (or press Ctrl+Enter). The rhythm is simple: orient, act, verify, then continue.

      -

      Jamie: What makes this practice feel low-stakes but still real?

      -

      Alex: The reason Completing Chapter 8: Submit Your Evidence matters is that the reflection comment itself is your evidence. That gives the learner a simple foothold: the facilitator reviews your comment for specificity.

      -

      Alex: The useful habit is simple: orient first, act second, verify third. That pause before acting is part of the work.

      -

      Alex: That matters because of the next idea. Start with Expected Outcomes. There is something to understand, something to try, and something that proves the try worked.

      -

      Alex: On the ground, that means a few things. 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.

      +

      Jamie: Let's pause on Sub-Issues vs. Task Lists. What should a learner take away from it?

      +

      Alex: The reason Sub-Issues vs. Task Lists matters is that if you are working on a feature that requires multiple PRs or involves several team members, ask the maintainer to create a parent issue. That gives the learner a simple foothold: you can then claim individual child issues without one person owning the whole feature.

      +

      Alex: Keep the teaching thread moving. Start with Learning Cards: Sub-Issues. There is something to understand, something to try, and something that proves the try worked.

      +

      Alex: The practical takeaway is this. 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. 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.

      +

      Jamie: Let's pause on Closing an issue. What should a learner take away from it?

      +

      Alex: Here is the plain-English version of Closing an issue. Scroll to the bottom of the issue page. Put another way, click the Close issue button next to the comment box.

      +

      Alex: First, 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. Then, button approach: Tab to the "Close issue" button (at the bottom of the page, near the comment box) and press Enter. After that, optionally leave a closing comment first. Finally, 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. Treat it like a recipe: do not add the next ingredient until the previous one is actually in the bowl.

      +

      Jamie: Before we leave Closing an issue, what is the practical point?

      +

      Alex: First, button approach: Quick Nav B or Tab to find the "Close issue" button, then VO+Space. It is a checklist, but a meaningful one: every item creates evidence that the next step is safe.

      +

      Alex: Treat examples as spoken recipes, not decorations. You may hear something like 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. Read the command, understand what it changes, then run it only when the repository state matches the lesson.

      -

      Jamie: How would you walk the room through that step by step?

      -

      Alex: Start with If You Get Stuck. There is something to understand, something to try, and something that proves the try worked.

      -

      Alex: First, use one simple sentence per prompt - do not overthink it. Then, focus on one real behavior you can start doing today, not an abstract principle. After that, if writing feels hard, draft bullet points first in a text editor, then paste into the comment. Finally, look at the "Giving Feedback" and "Asking for Help" sections in this chapter for concrete examples. Treat it like a recipe: do not add the next ingredient until the previous one is actually in the bowl.

      -

      Jamie: Give me the sequence, because order matters here.

      -

      Alex: First, ask facilitator for one example response and adapt it to your own words. Then, finished but not sure you did it right? Compare your work against the Challenge 8 reference solution. It is a checklist, but a meaningful one: every item creates evidence that the next step is safe.

      -

      Alex: This is where the talk moves from concept to action. This is where Learning Moment becomes real: technical quality and communication quality work together. That matters in practice: Respectful, clear communication helps good code get merged faster.

      -

      Jamie: Let's pause on Learning Pattern Used in This Chapter. What should a learner take away from it?

      -

      Alex: Start with Learning Pattern Used in This Chapter. There is something to understand, something to try, and something that proves the try worked.

      -

      Alex: First, read and absorb community norms (not just rules, but reasons). Then, reflect on personal experience (what worked, what was hard). After that, commit to specific behaviors in writing (public accountability). Finally, apply those behaviors in upcoming chapters (reviews, comments, PRs). It is like walking a hallway with named doors: read the sign, enter the right room, then confirm where you landed.

      +

      Alex: Keep the teaching thread moving. This is where Reopening a closed issue becomes real: if an issue is Closed, the "Close issue" button becomes "Reopen issue" - navigate and activate to reopen. The workshop is closer to rehearsal than lecture. You hear the move, try the move, and then check what changed.

      +

      Jamie: Let's pause on Assigning an issue. What should a learner take away from it?

      +

      Alex: Keep the learner anchored in Assigning an issue. GitHub CLI (gh) alternative - assigning and labeling. This is the part to say slowly: Manage assignments and labels from your terminal.

      +

      Alex: First, navigate to "Assignees" heading (3 or H). Then, activate the gear/plus button. After that, type a username in the search field. Finally, select from the dropdown. It is like walking a hallway with named doors: read the sign, enter the right room, then confirm where you landed.

      +

      Alex: Treat examples as spoken recipes, not decorations. You may hear something like 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". Read the command, understand what it changes, then run it only when the repository state matches the lesson.

      +

      Jamie: Let's pause on Changing labels. What should a learner take away from it?

      +

      Alex: Start with Changing labels. There is something to understand, something to try, and something that proves the try worked.

      +

      Alex: First, navigate to "Labels" heading. Then, activate the gear button. After that, select/deselect labels from the dropdown. Finally, press Escape to save. The rhythm is simple: orient, act, verify, then continue.

      -

      Alex: Before the learner moves on. The reason GitHub Flow - The Standard Contribution Workflow matters is that before diving into communication norms, it helps to understand the workflow that gives all of those conversations their context. That gives the learner a simple foothold: GitHub Flow is the lightweight branching model recommended for open source contribution. The interface gets friendlier when it stops being a wall of controls and starts being a set of named places.

      -

      Jamie: What would you say to someone who is already bracing for this to be too much?

      -

      Alex: Start with Why This Model Works. There is something to understand, something to try, and something that proves the try worked.

      -

      Alex: A few details make that real. 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.

      -

      Alex: Hold that next to this. Here is the plain-English version of GitHub Flow vs Git Flow. You may encounter "Git Flow" (sometimes written "GitFlow") in older projects or enterprise environments. Put another way, this section explains what Git Flow is, how it differs from GitHub Flow, and why this workshop teaches GitHub Flow.

      -

      Alex: A solid Git habit is to know which branch you are on, what changed, and what confirmation you expect before you run the next command.

      +

      Jamie: Let's pause on Transferring or deleting an issue. What should a learner take away from it?

      +

      Alex: Start with Transferring or deleting an issue: Available from the "." (ellipsis) button at the top of the issue - navigate buttons with B to find it.

      +

      Alex: Keep the teaching thread moving. Start with Learning Cards: Managing Issues. There is something to understand, something to try, and something that proves the try worked.

      +

      Alex: The practical takeaway is this. 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. 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.

      +

      Jamie: Let's pause on The "good first issue" Label - Your Entry Point. What should a learner take away from it?

      +

      Alex: This is where The "good first issue" Label - Your Entry Point becomes real: when looking for your first open source contribution. That matters in practice: Remember: It's respectful to ask before starting.

      +

      Alex: First, navigate to any project's Issues tab. Then, filter by label: type is:open label:"good first issue" in the search. After that, read through issues until you find one in your area of interest. Finally, comment on the issue: "Hi, I'd like to work on this. Can I be assigned?". It is a checklist, but a meaningful one: every item creates evidence that the next step is safe.

      +

      Jamie: Before we leave The "good first issue" Label - Your Entry Point, what is the practical point?

      +

      Alex: First, wait for a maintainer to respond and assign you before starting work. It is like walking a hallway with named doors: read the sign, enter the right room, then confirm where you landed.

      -

      Jamie: If I am listening before the workshop starts, what should settle in my mind first?

      -

      Alex: This is where What Git Flow Is becomes real: Git Flow is a branching model published by Vincent Driessen in 2010. That matters in practice: It was designed for teams that ship versioned releases on a schedule (desktop software, mobile apps, embedded systems).

      -

      Jamie: Let's pause on How the Git Flow Cycle Works. What should a learner take away from it?

      -

      Alex: Start with How the Git Flow Cycle Works. There is something to understand, something to try, and something that proves the try worked.

      -

      Alex: First, developers branch feature/my-feature off develop and work there. Then, completed features merge back into develop via pull request. After that, when develop has enough features for a release, a release/1.2.0 branch is created. Finally, the release branch gets final testing, bug fixes, and version number updates. It is like walking a hallway with named doors: read the sign, enter the right room, then confirm where you landed.

      -

      Jamie: Before we leave How the Git Flow Cycle Works, what is the practical point?

      -

      Alex: First, the release branch merges into main (tagged with the version) and back into develop. Then, if a critical bug is found in production, a hotfix/ branch is created from main, fixed, and merged into both main and develop. The rhythm is simple: orient, act, verify, then continue.

      -

      Jamie: What is the one idea that makes the next few steps less mysterious?

      -

      Alex: The reason How GitHub Flow Differs matters is that the following table compares GitHub Flow and Git Flow across key dimensions.

      -

      Alex: A solid pull request habit is to separate three questions: what changed, why it changed, and what still needs review. That keeps the conversation useful instead of noisy.

      +

      Alex: Keep the teaching thread moving. Start with Learning Cards: The "good first issue" Label. There is something to understand, something to try, and something that proves the try worked.

      +

      Alex: The practical takeaway is this. 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. 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.

      +

      Jamie: Let's pause on Accessibility-Specific Issue Writing Tips. What should a learner take away from it?

      +

      Alex: The reason Accessibility-Specific Issue Writing Tips matters is that when filing accessibility bugs, these details help maintainers reproduce and fix the problem.

      +

      Alex: First, screen reader and version - "NVDA 2025.3.3" not just "screen reader". Then, oS and version - "Windows 11 22H2". After that, browser and version - "Chrome 124.0.6367.82". Finally, GitHub interface - "Modern experience (default since Jan 2026)" or "Classic experience (opted out)". The rhythm is simple: orient, act, verify, then continue.

      +

      Jamie: Before we leave Accessibility-Specific Issue Writing Tips, what is the practical point?

      +

      Alex: First, what was announced - quote the exact text your screen reader spoke. Then, what should have been announced - describe the expected behavior. After that, aRIA issue if known - e.g., "The button has no accessible name". Finally, steps to reproduce - numbered, step-by-step. Think of it as a rail line: each stop confirms you are still on the right route before the next one.

      +

      Alex: Keep the teaching thread moving. Start with Example of a well-filed accessibility issue. There is something to understand, something to try, and something that proves the try worked.

      -

      Alex: Here is the practical turn. Start with When You Might See Git Flow. There is something to understand, something to try, and something that proves the try worked.

      -

      Alex: Here is what that changes in practice. 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.

      -

      Jamie: What belongs in the live room, and what can wait until after?

      -

      Alex: Here is the plain-English version of 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. Put another way, it is what GitHub itself uses and what most modern open source projects follow.

      -

      Alex: Keep the thread going. This is where The Unwritten Rule: One Thing Per Branch becomes real: a branch and its PR should do one thing. That matters in practice: If you are fixing a broken link and you notice a typo nearby, fix the typo in a separate branch and PR. The workshop is closer to rehearsal than lecture. You hear the move, try the move, and then check what changed.

      +

      Jamie: Let's pause on Learning Cards: Accessibility-Specific Issue Writing. What should a learner take away from it?

      +

      Alex: Start with Learning Cards: Accessibility-Specific Issue Writing. There is something to understand, something to try, and something that proves the try worked.

      +

      Alex: The practical takeaway is this. 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. 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.

      +

      Alex: Keep the teaching thread moving. This is where Writing Effective Issues becomes real: see also: Appendix N: Advanced Search covers search qualifiers to find existing issues before filing a new one. That matters in practice: 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.

      +

      Jamie: Let's pause on Bug Report Structure. What should a learner take away from it?

      +

      Alex: Keep the learner anchored in Bug Report Structure. A strong bug report answers five questions. This is the part to say slowly: Use this template every time you report something broken.

      -

      Jamie: Where do you want a learner to place their attention here?

      -

      Alex: Start with Learning Cards: GitHub Flow. There is something to understand, something to try, and something that proves the try worked.

      -

      Alex: These are the details that keep the idea from floating away. 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). 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.

      -

      Alex: Another way to ground it. The reason Keeping Your Fork Up to Date matters is that when you fork a repository, you get a snapshot of the project at that moment. That gives the learner a simple foothold: the original repository (called "upstream") continues to evolve.

      -

      Jamie: Give me the version that sounds like an instructor, not a manual.

      -

      Alex: Start with Why Sync Your Fork? There is something to understand, something to try, and something that proves the try worked.

      -

      Alex: That shows up in the workshop in a few specific ways. 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.

      +

      Jamie: Let's pause on Feature Request Structure. What should a learner take away from it?

      +

      Alex: The reason Feature Request Structure matters is that feature requests work best when they focus on the problem before jumping to the solution. That gives the learner a simple foothold: 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. The interface gets friendlier when it stops being a wall of controls and starts being a set of named places.

      +

      Alex: First, problem statement -- Describe the pain point. What are you trying to do, and why is it hard or impossible right now? Then, proposed solution -- Your best idea for fixing the problem. Be specific enough to discuss, but hold it loosely. After that, alternatives considered -- Other approaches you thought about and why they fell short. This shows you have done your homework. Finally, who benefits -- Name the audience. "Screen reader users navigating large repositories" is more compelling than "everyone.". The rhythm is simple: orient, act, verify, then continue.

      +

      Jamie: Let's pause on General Issue Writing Principles. What should a learner take away from it?

      +

      Alex: Start with General Issue Writing Principles: These rules apply to every issue -- bugs, features, questions, and everything in between. The next useful detail is this: If you discovered two bugs during the same session, file two separate issues.

      +

      Alex: Keep the teaching thread moving. Here is the plain-English version of Before and After: A Vague Issue vs. a Clear Issue. I tried clicking and nothing happened. Put another way, the maintainer has to ask: What doesn't work?

      -

      Jamie: Let's pause on Method 1: GitHub Web Interface (Easiest). What should a learner take away from it?

      -

      Alex: Here is the plain-English version of Method 1: GitHub Web Interface (Easiest). GitHub merges the upstream changes into your fork automatically. Put another way, screen reader users (NVDA / JAWS / VoiceOver). It is like learning a transit route. The names of the stops matter because they tell you whether you are still going the right direction.

      -

      Alex: First, navigate to your fork's main page: github.com/your-username/repo-name. Then, look for the sync indicator: "This branch is X commits behind upstream/main". After that, click the "Sync fork" button. Finally, click "Update branch". Treat it like a recipe: do not add the next ingredient until the previous one is actually in the bowl.

      -

      Jamie: Before we leave Method 1: GitHub Web Interface (Easiest), what is the practical point?

      -

      Alex: First, the sync button appears in the landmark that contains the branch selector. Then, press D to cycle through landmarks until you reach that region. After that, press B to cycle buttons until you hear "Sync fork" → press Enter. Finally, a dialog or page update presents "Update branch" - activate it. It is a checklist, but a meaningful one: every item creates evidence that the next step is safe.

      -

      Jamie: What should someone listen for when a lesson offers more than one tool path?

      -

      Alex: This is where Method 2: Git Command Line (VS Code Terminal) becomes real: if you're working locally in VS Code.

      -

      Jamie: What should happen before anyone copies and runs it?

      -

      Alex: Start with One-time setup - add the upstream remote. There is something to understand, something to try, and something that proves the try worked.

      -

      Alex: Treat examples as spoken recipes, not decorations. You may hear something like git remote add upstream https://github.com/original-owner/repo-name.git; git remote -v Verify it was added. Read the command, understand what it changes, then run it only when the repository state matches the lesson.

      +

      Jamie: Let's pause on Learning Cards: Writing Effective Issues. What should a learner take away from it?

      +

      Alex: Start with Learning Cards: Writing Effective Issues. There is something to understand, something to try, and something that proves the try worked.

      +

      Alex: The practical takeaway is this. 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. 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.

      +

      Jamie: Let's pause on Try It: File Your First Issue. What should a learner take away from it?

      +

      Alex: Keep the learner anchored in Try It: File Your First Issue. Time: 3 minutes What you need: Browser, signed in to GitHub. This is the part to say slowly: Go to the Learning Room repository and file a real issue. A good GitHub workflow is like a well-run meeting: everyone knows the topic, the next action, and who has the floor.

      +

      Alex: First, navigate to the Issues tab (press G then I in Focus Mode). Then, find and activate the "New issue" button (K to links, or Tab to it). After that, in the title field, type: "Introduce myself - [Your Name]". Finally, in the description, write 2-3 sentences: who you are, what screen reader you use, and one thing you're hoping to learn today. It is like walking a hallway with named doors: read the sign, enter the right room, then confirm where you landed.

      +

      Jamie: Before we leave Try It: File Your First Issue, what is the practical point?

      +

      Alex: First, press Ctrl+Enter to submit (or Tab to the Submit button and press Enter). The rhythm is simple: orient, act, verify, then continue.

      +

      Jamie: Let's pause on Learning Cards: Filing Your First Issue. What should a learner take away from it?

      +

      Alex: The reason Learning Cards: Filing Your First Issue matters is that day 2 Amplifier - Accessibility Agents: @issue-tracker File, read, comment on, and triage real issues manually before using any agent. That gives the learner a simple foothold: 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.

      +

      Alex: The practical takeaway is this. 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. 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.

      -

      Jamie: What should they understand before typing anything?

      -

      Alex: Start with Sync process. There is something to understand, something to try, and something that proves the try worked.

      -

      Alex: Treat examples as spoken recipes, not decorations. You may hear something like 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. Read the command, understand what it changes, then run it only when the repository state matches the lesson.

      -

      Alex: Now bring the learner back to the room. Start with When to sync. There is something to understand, something to try, and something that proves the try worked.

      -

      Alex: The room should hear these as checkpoints. 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).

      -

      Jamie: Let's pause on Method 3: GitHub Desktop. What should a learner take away from it?

      -

      Alex: Start with Method 3: GitHub Desktop. There is something to understand, something to try, and something that proves the try worked.

      -

      Alex: First, open GitHub Desktop. Then, select Repository → Pull to get your fork's latest. After that, select Branch → Merge into Current Branch. Finally, choose upstream/main. Treat it like a recipe: do not add the next ingredient until the previous one is actually in the bowl.

      -

      Jamie: Before we leave Method 3: GitHub Desktop, what is the practical point?

      -

      Alex: First, push the changes to your fork on GitHub. It is a checklist, but a meaningful one: every item creates evidence that the next step is safe.

      +

      Jamie: What should people carry with them after this?

      +

      Alex: Carry the map. Know what page or tool you are in, know which action you are taking, and know what confirmation should follow. If the confirmation is missing, pause. That pause is not wasted time; it is professional judgment.

      +

      Jamie: That is a better way to say it than just follow the steps.

      +

      Alex: Right. Steps matter, but understanding wins. That is episode 5. Next in the series is episode 6, where we keep building the same contributor muscles.

      +
      +
      -

      Alex: This is the part worth saying out loud. Start with Learning Cards: Keeping Your Fork Up to Date. There is something to understand, something to try, and something that proves the try worked.

      -

      Alex: That becomes easier when you listen for these cues. 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. 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.

      -

      Jamie: Let's pause on Writing Good Commit Messages. What should a learner take away from it?

      -

      Alex: Keep the learner anchored in Writing Good Commit Messages. Every commit you make includes a message describing what changed. This is the part to say slowly: Good commit messages make project history understandable months or years later.

      -

      Alex: That connects to another useful point. The reason The First Line (Required) matters is that this is the commit summary that appears in logs and GitHub's commit list. That gives the learner a simple foothold: think of it as an email subject line. The interface gets friendlier when it stops being a wall of controls and starts being a set of named places.

      -

      Alex: The parts worth keeping in working memory are these. fix: - bug fix. feat: - new feature. docs: - documentation only. style: - formatting, no code change.

      +

      11. Challenge 02: File Your First Issue

      +

      Finding a TODO, creating a clear issue, and explaining what needs to change.

      +

      Practice focus: Day 1 foundation

      +

      Audio and transcript are being regenerated for this episode.

      +
      +Read Transcript - Challenge 02: File Your First Issue + +

      Transcript

      +

      Alex: Welcome back to Challenge Coach. Today we are taking on File Your First Issue, one careful step at a time.

      +

      Jamie: And I am Jamie. I am listening for the confusing parts: where to start, what to submit, and how to tell whether it worked.

      -

      Jamie: What is the safe way to learn from that example?

      -

      Alex: Start with The Body (Optional): If the summary isn't enough, add a body explaining. The next useful detail is this: Leave a blank line between the summary and the body.

      -

      Alex: The practical takeaway is this. Why you made the change (more important than what). What trade-offs you considered. How the change affects behavior.

      -

      Alex: Treat examples as spoken recipes, not decorations. You may hear something like 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. Read the command, understand what it changes, then run it only when the repository state matches the lesson.

      -

      Alex: Keep the teaching thread moving. Here is the plain-English version of The Footer (Optional). When the commit is merged, GitHub automatically closes linked issues.

      -

      Jamie: Let's pause on Atomic Commits. What should a learner take away from it?

      -

      Alex: This is where Atomic Commits becomes real: each commit should represent one logical change. That matters in practice: Don't bundle unrelated fixes into a single commit.

      +

      Alex: In this challenge, the learner is practicing finding a TODO, creating a clear issue, and explaining what needs to change. The point is not to rush. The point is to leave a clear trace of good work.

      +

      Jamie: So we should name what success sounds like before the learner starts clicking or typing.

      +

      Alex: Yes. When the checkpoint is clear, the learner can tell the difference between being stuck and simply not being finished yet.

      -

      Alex: Keep the teaching thread moving. Start with Common mistakes to avoid. There is something to understand, something to try, and something that proves the try worked.

      -

      Alex: The practical takeaway is this. "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.

      -

      Jamie: How do you keep commands from becoming magic words?

      -

      Alex: The reason Good commit messages in practice matters is that when you make a habit of writing good commit messages, you build trust. That gives the learner a simple foothold: maintainers see that you care about the project's long-term health, not just your immediate contribution.

      -

      Alex: Treat examples as spoken recipes, not decorations. You may hear something like 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. Read the command, understand what it changes, then run it only when the repository state matches the lesson.

      -

      Alex: Keep the teaching thread moving. Start with Learning Cards: Writing Good Commit Messages. There is something to understand, something to try, and something that proves the try worked.

      -

      Alex: The practical takeaway is this. 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. 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.

      +

      Jamie: What makes this practice feel low-stakes but still real?

      +

      Alex: Start with Challenge 2: File Your First Issue: What you will do: Find a TODO comment in docs/welcome.md, then file an issue describing the problem with a clear title and description.

      +

      Alex: A solid issue habit is to read the title, the body, and the timeline before acting. You are listening for the requested action, the missing evidence, and the person who needs a response.

      +

      Jamie: How would you walk the room through that step by step?

      +

      Alex: Start with Instructions. There is something to understand, something to try, and something that proves the try worked.

      +

      Alex: The practical anchors are these. What needs to change. Where the problem is (file name and what section). Why it matters.

      +

      Alex: First, open docs/welcome.md and look for a line that contains TODO -- this marks something that needs fixing. Then, go to the Issues tab and select New issue. After that, write a clear, descriptive title (not just "Fix TODO"). Finally, in the description, explain. Treat it like a recipe: do not add the next ingredient until the previous one is actually in the bowl.

      +

      Jamie: What is the one idea that makes the next few steps less mysterious?

      +

      Alex: This is where What makes a good issue title? becomes real: I found a TODO in docs/welcome.md that said.

      -

      Jamie: Let's pause on The Nature of Open Source Communication. What should a learner take away from it?

      -

      Alex: Here is the plain-English version of The Nature of Open Source Communication. Open source collaboration happens primarily in writing, asynchronously, in public. Put another way, understanding these three characteristics shapes everything about how we communicate.

      -

      Alex: Keep the teaching thread moving. Start with In writing. There is something to understand, something to try, and something that proves the try worked.

      -

      Alex: The practical takeaway is this. 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.".

      -

      Jamie: Let's pause on Asynchronously. What should a learner take away from it?

      -

      Alex: Start with Asynchronously. There is something to understand, something to try, and something that proves the try worked.

      -

      Alex: The practical takeaway is this. 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.

      +

      Alex: Now bring the learner back to the room. Keep the learner anchored in Peer simulation check. Open the Peer Simulation: Welcome Link Needs Context issue and leave a comment: Is the title clear? This is the part to say slowly: Would you know what needs fixing just from reading the title?

      +

      Jamie: What would you say to someone who is already bracing for this to be too much?

      +

      Alex: The reason Example 1: Bug report style matters is that in docs/welcome.md, line 15, there is a TODO comment that says "add link to workshop schedule." This placeholder should be replaced with an actual link so students can find the schedule.

      +

      Alex: The useful habit is simple: orient first, act second, verify third. That pause before acting is part of the work.

      +

      Alex: That matters because of the next idea. Start with Example 2: Feature request style: The welcome document covers what students will do but does not mention accessibility features. The next useful detail is this: A short section pointing students to screen reader shortcuts and keyboard navigation would help everyone start on equal footing. Think of it like entering a new building: first you find the lobby, then the room, then the door you actually need.

      -

      Alex: Keep the teaching thread moving. Start with In public. There is something to understand, something to try, and something that proves the try worked.

      -

      Alex: The practical takeaway is this. 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.

      -

      Jamie: What do you want them to do when the plan breaks?

      -

      Alex: Start with The Anatomy of Helpful Feedback: Whether commenting on an issue, reviewing a PR, or responding to a question, effective feedback has a structure.

      -

      Alex: Keep the teaching thread moving. Here is the plain-English version of 1. Acknowledge what's working. Before identifying problems, name what is good. Put another way, this is not flattery - it is accuracy. It is like learning a transit route. The names of the stops matter because they tell you whether you are still going the right direction.

      +

      Jamie: Okay, set the room for us. What are we walking into?

      +

      Alex: Start with What makes a good issue. There is something to understand, something to try, and something that proves the try worked.

      +

      Alex: Here is what that changes in practice. Clear title: Someone scanning the issue list can understand the topic without opening it. Enough context: Another person could find and understand the problem from your description alone. Reproducible location: File name and line number (if relevant) so the fix is easy to find.

      +

      Alex: This is where the talk moves from concept to action. This is where Alternate approaches becomes real: both bug reports and feature suggestions are valid for this challenge. That matters in practice: The key is writing clearly enough that a stranger could act on your issue.

      +

      Alex: A solid pull request habit is to separate three questions: what changed, why it changed, and what still needs review. That keeps the conversation useful instead of noisy.

      +

      Jamie: Where do you want a learner to place their attention here?

      +

      Alex: Keep the learner anchored in Filing, Managing, and Participating in GitHub Issues. Issues are where open source collaboration begins. This is the part to say slowly: everything from finding the right issue to file a perfect bug report - all with your keyboard and screen reader.

      -

      Jamie: Let's pause on 2. Identify the specific concern. What should a learner take away from it?

      -

      Alex: This is where 2. Identify the specific concern becomes real: "This code is inaccessible." "This button has no accessible name - aria-label or visible text is needed for screen readers to announce its purpose.".

      -

      Alex: Keep the teaching thread moving. Keep the learner anchored in 3. Explain why it matters. Context turns a complaint into a lesson. This is the part to say slowly: It also respects the contributor - they deserve to understand, not just comply.

      -

      Jamie: Let's pause on 4. Suggest a path forward (when you can). What should a learner take away from it?

      -

      Alex: The reason 4. Suggest a path forward (when you can) matters is that if you have an idea for a solution, offer it as a suggestion, not a mandate. That gives the learner a simple foothold: "Something like aria-label='Close navigation menu' would work well here.

      +

      Alex: Before the learner moves on. The reason Workshop Recommendation (Chapter 5 / Challenges 2-3) matters is that chapter 5 is the first issue-based challenge chapter with short, confidence-building tasks. That gives the learner a simple foothold: it supports Challenge 2 (File Your First Issue) and Challenge 3 (Join the Conversation). The interface gets friendlier when it stops being a wall of controls and starts being a set of named places.

      +

      Alex: That becomes easier when you listen for these cues. There are 2 core challenges plus one optional extension. Each challenge should take under 10 minutes. The evidence is issue comments and issue metadata. The pattern is claim - act - confirm.

      +

      Jamie: Give me the sequence, because order matters here.

      +

      Alex: Start with Chapter 5 Challenge Set: Chapter 5 focuses on issue skills. The next useful detail is this: You do NOT need to create a branch or edit any files for these challenges.

      +

      Alex: First, create your first issue - file a new issue with a clear title and description. Then, comment and @mention - leave a comment on a classmate's issue and tag them with an @mention. After that, optional extension: Add a sub-issue - break a larger issue into smaller, trackable pieces if your repository has sub-issues enabled. Think of it as a rail line: each stop confirms you are still on the right route before the next one.

      +

      Jamie: What does the learner do first, second, and then after that?

      +

      Alex: Here is the plain-English version of Challenge 2 Step-by-Step: Create Your First Issue. File a new issue in your Learning Room repository with a specific title and a meaningful description. Put another way, issues are the prompts that wake up AI.

      +

      Alex: That shows up in the workshop in a few specific ways. "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". What the problem is or what content is missing.

      +

      Alex: First, open your Learning Room repository in your browser. Then, navigate to the Issues tab (press G then I to jump there with keyboard shortcuts, or find the "Issues" link in the repository navigation). After that, activate the New issue button. Finally, if a template picker appears, select Open a blank issue (or choose a template if one fits). Treat it like a recipe: do not add the next ingredient until the previous one is actually in the bowl.

      +

      Jamie: Turn that into a path someone can follow.

      +

      Alex: First, in the Title field, type a clear, specific title (at least 12 characters). Then, in the Body field, write a meaningful description (at least 80 characters). After that, activate Submit new issue. Finally, copy the issue URL or note the issue number (for example, 150). You will reference this later. It is a checklist, but a meaningful one: every item creates evidence that the next step is safe.

      -

      Alex: Keep the teaching thread moving. Start with 5. Signal the weight of the concern: Help contributors understand what is a blocker versus a preference. Think of it like entering a new building: first you find the lobby, then the room, then the door you actually need.

      -

      Alex: The practical takeaway is this. 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.

      -

      Jamie: Let's pause on Prefer "we" or describe the code, not the person. What should a learner take away from it?

      -

      Alex: Here is the plain-English version of 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.".

      -

      Alex: Keep the teaching thread moving. This is where Use tentative language for uncertainty becomes real: "This will crash on mobile." "I think this might cause issues on mobile - have you tested with a narrower viewport?".

      +

      Jamie: What is the ordered workflow?

      +

      Alex: This is where Challenge 4.2 Step-by-Step: Comment and @Mention becomes real: leave a comment on another student's issue and use an @mention to notify them. That matters in practice: the Issues tab of your Learning Room repository on GitHub.com.

      +

      Alex: For a learner, the useful signals are these. "@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.".

      +

      Alex: First, open the Issues tab in your Learning Room repository. Then, find an issue created by a classmate (look for issues from Challenge 4.1, or browse recent open issues). After that, open the issue by activating its title link. Finally, read the issue description to understand what they reported. It is a checklist, but a meaningful one: every item creates evidence that the next step is safe.

      +

      Jamie: Let's pause on Challenge 4.2 Step-by-Step: Comment and @Mention. What should a learner take away from it?

      +

      Alex: First, scroll to the comment box at the bottom of the issue. Then, write a helpful comment that @mentions the issue author by username. After that, activate the Comment button (or press Ctrl+Enter). It is like walking a hallway with named doors: read the sign, enter the right room, then confirm where you landed.

      +

      Jamie: Let's pause on Challenge 4.3 Step-by-Step: Add a Sub-Issue. What should a learner take away from it?

      +

      Alex: Keep the learner anchored in Challenge 4.3 Step-by-Step: Add a Sub-Issue. Break a larger issue into smaller, trackable pieces using GitHub's sub-issue feature. This is the part to say slowly: the issue you created in Challenge 4.1 (or any open issue you have permission to edit). A good GitHub workflow is like a well-run meeting: everyone knows the topic, the next action, and who has the floor.

      +

      Alex: The parts worth keeping in working memory are these. Sub-issue: "Add alt text to welcome banner image". Sub-issue: "Fix heading hierarchy in Getting Started section".

      +

      Alex: First, open the issue you created in Challenge 4.1. Then, 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. After that, activate Add sub-issue and choose Create new sub-issue. Finally, 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". It is like walking a hallway with named doors: read the sign, enter the right room, then confirm where you landed.

      +

      Jamie: Before we leave Challenge 4.3 Step-by-Step: Add a Sub-Issue, what is the practical point?

      +

      Alex: First, add a short description and activate Create. Then, the sub-issue now appears nested under the parent issue with a progress indicator. The rhythm is simple: orient, act, verify, then continue.

      +

      Jamie: What should the learner prove to themselves after each small task?

      +

      Alex: The reason Completing Chapter 4: Submit Your Evidence matters is that 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. That gives the learner a simple foothold: replace [number] with the actual issue numbers.

      -

      Jamie: Let's pause on Acknowledge cultural and language diversity. What should a learner take away from it?

      -

      Alex: Keep the learner anchored in Acknowledge cultural and language diversity. When reading someone's comment: Assume good intent unless there is clear evidence otherwise. This is the part to say slowly: When writing: Choose plain words over clever ones.

      -

      Alex: The practical takeaway is this. 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.

      -

      Alex: Keep the teaching thread moving. The reason Avoid urgency markers unless genuinely urgent matters is that "I need this fixed ASAP" "This is blocking our release scheduled for next Friday - is there capacity to look at it this week?". The interface gets friendlier when it stops being a wall of controls and starts being a set of named places.

      -

      Jamie: Let's pause on Keep comments focused. What should a learner take away from it?

      -

      Alex: Start with Keep comments focused: Each comment should address one concern. The next useful detail is this: If you have three issues, leave three comments - unless they are closely related.

      +

      Alex: Here is the practical turn. Start with Expected Outcomes. There is something to understand, something to try, and something that proves the try worked.

      +

      Alex: On the ground, that means a few things. 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.

      +

      Jamie: Let's pause on If You Get Stuck. What should a learner take away from it?

      +

      Alex: Start with If You Get Stuck. There is something to understand, something to try, and something that proves the try worked.

      +

      Alex: First, can't find a classmate's issue? Filter the Issues tab by is:open and look for recent ones. Then, @mention not working? Make sure you type @ immediately followed by the username with no space. After that, sub-issue option not visible? Ask a facilitator - the feature may need to be enabled for the repository. Finally, still stuck? Ask a facilitator for a direct issue link. Treat it like a recipe: do not add the next ingredient until the previous one is actually in the bowl.

      +

      Jamie: Before we leave If You Get Stuck, what is the practical point?

      +

      Alex: First, finished but not sure you did it right? Compare your work against the Challenge 2 reference solution or the Challenge 3 reference solution. It is a checklist, but a meaningful one: every item creates evidence that the next step is safe.

      +

      Alex: Keep the thread going. This is where Learning Moment becomes real: issues are collaborative spaces, not just task lists. That matters in practice: An @mention tells someone "I need your attention here." Sub-issues turn vague tasks into clear checklists. The workshop is closer to rehearsal than lecture. You hear the move, try the move, and then check what changed.

      -

      Alex: Keep the teaching thread moving. Here is the plain-English version of Don't leave comments unresolved. If you asked a question and got an answer, respond. Put another way, "Thanks, that makes sense" or resolving the conversation thread signals that the thread is complete.

      -

      Jamie: Let's pause on Resolving conversations. What should a learner take away from it?

      -

      Alex: This is where Resolving conversations becomes real: on a PR, conversations (inline comment threads) can be "resolved" once addressed. That matters in practice: The author of the change and the reviewer can both resolve them.

      -

      Alex: Keep the teaching thread moving. Keep the learner anchored in 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. This is the part to say slowly: A reaction on an existing comment is enough. A good GitHub workflow is like a well-run meeting: everyone knows the topic, the next action, and who has the floor.

      +

      Jamie: Let's pause on Learning Pattern Used in This Chapter. What should a learner take away from it?

      +

      Alex: Start with Learning Pattern Used in This Chapter. There is something to understand, something to try, and something that proves the try worked.

      +

      Alex: First, start with a small, safe action (create an issue). Then, practice communication in public issue threads (@mention a peer). After that, organize work into smaller pieces (sub-issues). Finally, leave clear evidence in the issue timeline. It is like walking a hallway with named doors: read the sign, enter the right room, then confirm where you landed.

      +

      Jamie: Before we leave Learning Pattern Used in This Chapter, what is the practical point?

      +

      Alex: First, build momentum for file editing and PR work in Chapter 6. The rhythm is simple: orient, act, verify, then continue.

      +

      Alex: Another way to ground it. The reason About Learning Cards in This Chapter matters is that this chapter provides learning cards: expandable blocks that offer perspective-specific guidance for different ways of working. That gives the learner a simple foothold: not every card appears at every step.

      +

      Jamie: What should they understand before typing anything?

      +

      Alex: Start with Local Git Alternative: Working from Your Clone: If you cloned the learning-room in Block 0 and prefer working locally. The next useful detail is this: During Block 0 you cloned the Learning Room repository to your computer.

      +

      Alex: Treat examples as spoken recipes, not decorations. You may hear something like cd /Documents/learning-room or wherever you cloned it; git status should show "On branch main". 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. Read the command, understand what it changes, then run it only when the repository state matches the lesson.

      +

      Alex: A solid Git habit is to know which branch you are on, what changed, and what confirmation you expect before you run the next command.

      -

      Jamie: Let's pause on Reactions. What should a learner take away from it?

      -

      Alex: The reason Reactions matters is that GitHub reactions () are an efficient way to express agreement, appreciation, or concern without adding noise to a thread.

      -

      Alex: Keep the teaching thread moving. Start with 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. The next useful detail is this: This is a significant accessibility win for anyone who types the same comments repeatedly during triage, reviews, or issue management.

      -

      Jamie: Let's pause on Common uses. What should a learner take away from it?

      -

      Alex: Start with Common uses. There is something to understand, something to try, and something that proves the try worked.

      -

      Alex: The practical takeaway is this. "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.

      +

      Alex: This is the part worth saying out loud. Here is the plain-English version of What Is a GitHub Issue? An issue is a discussion thread attached to a repository. Put another way, every issue has a number ( 42), a state (Open or Closed), a title, a description, and a comment thread. It is like learning a transit route. The names of the stops matter because they tell you whether you are still going the right direction.

      +

      Alex: The room should hear these as checkpoints. 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".

      +

      Jamie: Let's pause on From a repository page. What should a learner take away from it?

      +

      Alex: This is where From a repository page becomes real: click the Issues tab in the repository navigation bar below the repository name. That matters in practice: The tab shows the open issue count (e.g., "Issues · 14").

      +

      Alex: First, press D to navigate to the "Repository navigation" landmark. Then, press K or Tab to move through the tab links. After that, find "Issues" - it will be announced with the count: "Issues, 14 open". Finally, press Enter to open the Issues tab. It is a checklist, but a meaningful one: every item creates evidence that the next step is safe.

      +

      Jamie: Before we leave From a repository page, what is the practical point?

      +

      Alex: First, vO+U → Landmarks → navigate to "Repository navigation". Then, vO+Right or Quick Nav K to move through tab links. After that, find "Issues" - VoiceOver announces the count: "Issues 14". Finally, vO+Space to activate the Issues tab. It is like walking a hallway with named doors: read the sign, enter the right room, then confirm where you landed.

      +

      Alex: Treat examples as spoken recipes, not decorations. You may hear something like gh issue list. gh issue list --label "good first issue"; gh issue list --assignee @me; gh issue list --state closed. Read the command, understand what it changes, then run it only when the repository state matches the lesson.

      +

      Alex: The next layer is this. Keep the learner anchored in Direct URL. Navigate directly: https://github.com/[owner]/[repo]/issues.

      -

      Jamie: Let's pause on Creating a Saved Reply. What should a learner take away from it?

      -

      Alex: Start with Creating a Saved Reply. There is something to understand, something to try, and something that proves the try worked.

      -

      Alex: First, navigate to github.com/settings/replies. Then, activate "Add a saved reply". After that, give it a title (e.g., "Good first issue claim") - this is what you search. Finally, type the full reply text in the body (Markdown is supported). It is a checklist, but a meaningful one: every item creates evidence that the next step is safe.

      -

      Jamie: Let's pause on Using a Saved Reply in a comment. What should a learner take away from it?

      -

      Alex: Start with Using a Saved Reply in a comment. There is something to understand, something to try, and something that proves the try worked.

      -

      Alex: First, navigate to any comment text area. Then, activate the Saved Replies button (the speech bubble icon in the comment toolbar, or press Ctrl+. if enabled). After that, a dropdown appears showing your saved replies - type to filter by title. Finally, select the reply - it inserts into the text area. It is like walking a hallway with named doors: read the sign, enter the right room, then confirm where you landed.

      -

      Jamie: Before we leave Using a Saved Reply in a comment, what is the practical point?

      -

      Alex: First, edit as needed before submitting. The rhythm is simple: orient, act, verify, then continue.

      -

      Alex: Keep the teaching thread moving. The reason Screen reader path matters is that limit: GitHub allows up to 100 saved replies per account.

      -

      Alex: A solid navigation habit is to prove where you are before activating controls. Headings, landmarks, and the address bar are not trivia; they are your map.

      +

      Jamie: If I am listening before the workshop starts, what should settle in my mind first?

      +

      Alex: Start with Learning Cards: Navigating to the Issues List. There is something to understand, something to try, and something that proves the try worked.

      +

      Alex: These are the details that keep the idea from floating away. 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. 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.

      +

      Alex: Hold that next to this. Start with Page structure: 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. The next useful detail is this: This is often faster than tabbing through many elements and helps you understand the full page structure before diving in. Think of it like entering a new building: first you find the lobby, then the room, then the door you actually need.

      +

      Jamie: Let's pause on How to read the issue list. What should a learner take away from it?

      +

      Alex: Here is the plain-English version of How to read the issue list. The issues list shows each issue as a row with its title, labels, number, assignee avatars, and comment count. Put another way, closed issues show a purple merged/closed badge.

      +

      Alex: A few details make that real. 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.

      +

      Alex: First, press D to reach the "Search Results List" landmark. Then, press 3 (h3) to navigate by issue titles - each issue title is an h3 link. After that, press I to move between list items if you want more detail per item. Finally, press Enter on a title to open that issue. Treat it like a recipe: do not add the next ingredient until the previous one is actually in the bowl.

      +

      Jamie: Before we leave How to read the issue list, what is the practical point?

      +

      Alex: First, vO+U → Landmarks → navigate to "Search Results List". Then, vO+Down to read through items. After that, h (with Quick Nav on) or VO+U → Headings to jump by issue title. It is a checklist, but a meaningful one: every item creates evidence that the next step is safe.

      -

      Jamie: Let's pause on Learning Cards: Commenting Etiquette. What should a learner take away from it?

      -

      Alex: Start with Learning Cards: Commenting Etiquette. There is something to understand, something to try, and something that proves the try worked.

      -

      Alex: The practical takeaway is this. 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. 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.

      -

      Alex: Keep the teaching thread moving. Here is the plain-English version of 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.". It is like learning a transit route. The names of the stops matter because they tell you whether you are still going the right direction.

      -

      Jamie: Let's pause on Don't gatekeep knowledge. What should a learner take away from it?

      -

      Alex: This is where Don't gatekeep knowledge becomes real: if a contributor makes a mistake because they didn't know something, explain the concept.

      +

      Alex: That connects to another useful point. This is where What is announced per issue becomes real: when you navigate to an issue in the list, your screen reader will announce (in some order).

      +

      Alex: The practical takeaway is this. 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").

      +

      Jamie: Give me the version that sounds like an instructor, not a manual.

      +

      Alex: Start with Learning Cards: The Issues List Page. There is something to understand, something to try, and something that proves the try worked.

      +

      Alex: The practical takeaway is this. 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. 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.

      +

      Alex: Keep the teaching thread moving. The reason Filtering and Searching Issues matters is that filtering lets you narrow the list to find the right issue quickly. The interface gets friendlier when it stops being a wall of controls and starts being a set of named places.

      -

      Alex: Keep the teaching thread moving. Keep the learner anchored in Ask questions instead of making demands. "Change this to use aria-label." "What do you think about using aria-label here instead? This is the part to say slowly: Screen readers would then announce the button's purpose directly.".

      -

      Jamie: Let's pause on Distinguish opinion from requirement. What should a learner take away from it?

      -

      Alex: The reason Distinguish opinion from requirement matters is that if something is your stylistic preference but NOT a bug or correctness issue, say so. That gives the learner a simple foothold: "The current implementation is correct.

      -

      Alex: Keep the teaching thread moving. Start with 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! Think of it like entering a new building: first you find the lobby, then the room, then the door you actually need.

      +

      Jamie: Let's pause on Using the search/filter bar. What should a learner take away from it?

      +

      Alex: Start with Using the search/filter bar. There is something to understand, something to try, and something that proves the try worked.

      +

      Alex: First, press F or E to jump to the filter input field (or navigate from the landmark). Then, switch to Focus Mode (NVDA+Space / Insert+Z) if not already in it. After that, type your filter or search query. Finally, press Enter to apply. Think of it as a rail line: each stop confirms you are still on the right route before the next one.

      +

      Jamie: Let's pause on Using the filter buttons. What should a learner take away from it?

      +

      Alex: Here is the plain-English version of Using the filter buttons. Above the issue list, there is an actions toolbar with filter buttons for Labels, Milestones, Assignees, etc. Put another way, the filter buttons do not indicate the current filter state.

      +

      Alex: The practical takeaway is this. 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.

      +

      Alex: First, press Tab from the search bar (or Shift+Tab from the issue list) to reach the actions toolbar. Then, press ←/→ to move between toolbar options (Label, Milestone, Assignee, Sort). After that, press Enter to open the selected dropdown. Finally, use ↑/↓ to navigate options in the dropdown. Treat it like a recipe: do not add the next ingredient until the previous one is actually in the bowl.

      +

      Jamie: Before we leave Using the filter buttons, what is the practical point?

      +

      Alex: First, press Enter or Space to select. Then, press Escape to close (filter applies immediately). After that, tab forward from the search bar to reach the filter buttons, or use Quick Nav to find them. Finally, vO+Left/Right to move between Label, Milestone, Assignee, Sort buttons. It is a checklist, but a meaningful one: every item creates evidence that the next step is safe.

      +

      Alex: Treat examples as spoken recipes, not decorations. You may hear something like 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". Read the command, understand what it changes, then run it only when the repository state matches the lesson.

      +

      Jamie: Let's pause on Open vs Closed filter. What should a learner take away from it?

      +

      Alex: This is where Open vs Closed filter becomes real: the two state links "Open" and "Closed" appear near the top of the issue list. That matters in practice: Press K to navigate links until you find them, or look for them as buttons near the search bar.

      -

      Jamie: Let's pause on Say thank you. What should a learner take away from it?

      -

      Alex: Here is the plain-English version of Say thank you. When someone takes time to review your work, acknowledge it - even if you disagree with some feedback. Put another way, "Thanks so much for the thorough review!

      -

      Alex: Keep the teaching thread moving. This is where Don't take feedback personally becomes real: code review is about the code, not your worth as a person or developer. That matters in practice: Even the most senior contributors receive change requests.

      -

      Jamie: Let's pause on Explain your choices. What should a learner take away from it?

      -

      Alex: Keep the learner anchored in Explain your choices. If you are keeping your implementation despite feedback, explain why. This is the part to say slowly: "I considered aria-label here, but I went with a visually-hidden instead because it allows translators to localize the text more easily.

      +

      Alex: Keep the teaching thread moving. Start with Learning Cards: Filtering and Searching Issues. There is something to understand, something to try, and something that proves the try worked.

      +

      Alex: The practical takeaway is this. 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. 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.

      +

      Jamie: Let's pause on Landing on an issue page. What should a learner take away from it?

      +

      Alex: The reason Landing on an issue page matters is that when you open an issue, the page structure is.

      +

      Jamie: Let's pause on Reading the issue description. What should a learner take away from it?

      +

      Alex: Start with Reading the issue description: Browse Mode recommended: The issue detail page is primarily text-based. The next useful detail is this: Stay in Browse Mode (not Focus Mode) for reading - it gives you full heading (H), section (D), and link (K) navigation throughout the page.

      +

      Alex: First, press 2 to reach the "Description" heading. Then, press ↓ to read the content line by line,. After that, use NVDA+↓ (NVDA say all) to have it read continuously. Think of it as a rail line: each stop confirms you are still on the right route before the next one.

      +

      Alex: Treat examples as spoken recipes, not decorations. You may hear something like 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. Read the command, understand what it changes, then run it only when the repository state matches the lesson.

      -

      Alex: Keep the teaching thread moving. The reason Surface blockers early matters is that don't wait until you have finished a 500-line PR to mention that you weren't sure about the approach. The interface gets friendlier when it stops being a wall of controls and starts being a set of named places.

      -

      Jamie: Let's pause on Inclusive Commenting for Accessibility Issues. What should a learner take away from it?

      -

      Alex: Start with Inclusive Commenting for Accessibility Issues: When filing or discussing accessibility bugs, additional context helps.

      -

      Alex: The practical takeaway is this. 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.

      -

      Alex: A solid issue habit is to read the title, the body, and the timeline before acting. You are listening for the requested action, the missing evidence, and the person who needs a response.

      -

      Jamie: Let's pause on The "Good First Issue" Social Contract. What should a learner take away from it?

      -

      Alex: Here is the plain-English version of The "Good First Issue" Social Contract. When a maintainer labels an issue good first issue, they are. Put another way, when you take a good first issue, your responsibilities.

      -

      Alex: The practical takeaway is this. Investing time - good first issues require extra documentation and mentorship. Signaling welcome - they want to support a new contributor.

      -

      Alex: First, comment to claim it - "Hi, I'd like to work on this. Can I be assigned?". Then, wait for assignment - do not start until assigned; two people working in parallel wastes everyone's time. After that, 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?". Finally, 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?". Treat it like a recipe: do not add the next ingredient until the previous one is actually in the bowl.

      -

      Jamie: Before we leave The "Good First Issue" Social Contract, what is the practical point?

      -

      Alex: First, don't disappear - if you claim an issue, see it through or explicitly hand it back. It is a checklist, but a meaningful one: every item creates evidence that the next step is safe.

      +

      Jamie: Let's pause on Reading comments and activity. What should a learner take away from it?

      +

      Alex: Here is the plain-English version of Reading comments and activity. Each comment in the thread is marked as an h3. Put another way, other timeline events (label added, PR linked, issue closed) appear between comments in the activity stream.

      +

      Alex: The practical takeaway is this. Commenter's username. Timestamp ("2 days ago"). Body text. Reactions (if any - announced as a button with an emoji and count).

      +

      Alex: Keep the teaching thread moving. Start with Learning Cards: Reading an Issue. There is something to understand, something to try, and something that proves the try worked.

      +

      Alex: The practical takeaway is this. 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. 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.

      +

      Jamie: Let's pause on Step-by-step. What should a learner take away from it?

      +

      Alex: Keep the learner anchored in Step-by-step. To close the issue while commenting: click the arrow on the Close issue button and choose Close with comment. This is the part to say slowly: Low vision users (zoom, high contrast).

      +

      Alex: First, scroll to the bottom of the issue page. Then, click in the Leave a comment text area. After that, type your comment (Markdown is supported - use the toolbar buttons above the text for bold, italic, code, etc.). Finally, optionally click Preview to see how it will render. It is like walking a hallway with named doors: read the sign, enter the right room, then confirm where you landed.

      +

      Jamie: Before we leave Step-by-step, what is the practical point?

      +

      Alex: First, click the green Comment button to post. Then, scroll to the bottom to find the Leave a comment text area. At 200%+ zoom, this may require significant scrolling past the timeline. After that, the text area expands as you type. The formatting toolbar above it (bold, italic, code, etc.) wraps at high zoom but remains functional. Finally, the Preview tab next to Write lets you check Markdown rendering before posting. The rhythm is simple: orient, act, verify, then continue.

      +

      Alex: Treat examples as spoken recipes, not decorations. You may hear something like 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.". Read the command, understand what it changes, then run it only when the repository state matches the lesson.

      -

      Jamie: Let's pause on When you receive harsh feedback. What should a learner take away from it?

      -

      Alex: Start with When you receive harsh feedback. There is something to understand, something to try, and something that proves the try worked.

      -

      Alex: First, take a breath before responding - there is no urgency; the thread will wait. Then, look for the valid concern underneath the harsh words. After that, respond to the concern, not the tone. Finally, if the behavior crosses into harassment, report it via the "." button on the comment → "Report". It is a checklist, but a meaningful one: every item creates evidence that the next step is safe.

      -

      Jamie: Let's pause on When you disagree with a decision. What should a learner take away from it?

      -

      Alex: Start with When you disagree with a decision. There is something to understand, something to try, and something that proves the try worked.

      -

      Alex: First, make your case once, clearly and with evidence. Then, accept that the maintainer has the final say in their project. After that, if you strongly disagree, you can fork the project and take it in a different direction - this is legitimate in open source. It is like walking a hallway with named doors: read the sign, enter the right room, then confirm where you landed.

      -

      Jamie: Let's pause on When someone is rude to you. What should a learner take away from it?

      -

      Alex: Start with When someone is rude to you. There is something to understand, something to try, and something that proves the try worked.

      -

      Alex: First, you do not have to engage. Then, 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.". After that, report via GitHub's reporting tools if the behavior is abusive. The rhythm is simple: orient, act, verify, then continue.

      +

      Alex: Keep the teaching thread moving. The reason Markdown formatting while typing matters is that these keyboard shortcuts work inside the text area (Focus Mode).

      +

      Jamie: Let's pause on GitHub shortcuts for the Issues pages. What should a learner take away from it?

      +

      Alex: Start with GitHub shortcuts for the Issues pages: These are the GitHub built-in shortcuts for working with issues. The next useful detail is this: Enable Focus Mode first (NVDA: NVDA+Space, JAWS: Insert+Z) before using single-key shortcuts.

      +

      Alex: Keep the teaching thread moving. Here is the plain-English version of On the Issues list page. Shortcut note: For G I, press G, release it, then press I (two sequential key presses, not simultaneous). It is like learning a transit route. The names of the stops matter because they tell you whether you are still going the right direction.

      -

      Jamie: Let's pause on When you accidentally caused offense. What should a learner take away from it?

      -

      Alex: Start with When you accidentally caused offense. There is something to understand, something to try, and something that proves the try worked.

      -

      Alex: First, acknowledge it directly: "I can see how that came across as dismissive - that wasn't my intention.". Then, do not over-explain or defend excessively. After that, adjust going forward. Think of it as a rail line: each stop confirms you are still on the right route before the next one.

      -

      Jamie: Let's pause on Writing Your First README. What should a learner take away from it?

      -

      Alex: Here is the plain-English version of Writing Your First README. See also: Appendix W: GitHub Pages for publishing your README as a website. Put another way, a README is the front door of your project.

      -

      Alex: Keep the teaching thread moving. This is where What belongs in a README becomes real: every README should answer these questions, roughly in this order. That matters in practice: 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. The workshop is closer to rehearsal than lecture. You hear the move, try the move, and then check what changed.

      +

      Jamie: Let's pause on On an open issue. What should a learner take away from it?

      +

      Alex: This is where On an open issue becomes real: r to quote is a power move: Select any text in a comment while in Browse Mode (Shift+Arrow to select), then press R. That matters in practice: GitHub puts the quoted text in the comment box as a Markdown blockquote.

      +

      Alex: First, navigate to your comment (3 to jump to comments). Then, find the "." (ellipsis) menu button near your comment. After that, press Enter on "Edit" from that menu. Finally, the comment turns into a text area - switch to Focus Mode. It is a checklist, but a meaningful one: every item creates evidence that the next step is safe.

      +

      Jamie: Before we leave On an open issue, what is the practical point?

      +

      Alex: First, make your changes. Then, tab to "Update comment" button → Enter. It is like walking a hallway with named doors: read the sign, enter the right room, then confirm where you landed.

      +

      Alex: Keep the teaching thread moving. Start with Learning Cards: Leaving a Comment. There is something to understand, something to try, and something that proves the try worked.

      +

      Alex: The practical takeaway is this. 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. 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.

      +

      Jamie: Let's pause on Navigating to New Issue. What should a learner take away from it?

      +

      Alex: The reason Navigating to New Issue matters is that from the Issues list page, click the green New issue button in the top-right of the issue list. That gives the learner a simple foothold: 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.

      +

      Alex: The practical takeaway is this. 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.

      +

      Alex: First, press K to navigate links and find the "New issue" button/link. Then, press Enter. After that, 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. Finally, quick Nav B or VO+U → Buttons to find the "New issue" button. The rhythm is simple: orient, act, verify, then continue.

      +

      Jamie: Before we leave Navigating to New Issue, what is the practical point?

      +

      Alex: First, vO+Space to activate it. Then, 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. Think of it as a rail line: each stop confirms you are still on the right route before the next one.

      -

      Jamie: Let's pause on Accessibility in READMEs. What should a learner take away from it?

      -

      Alex: Keep the learner anchored in Accessibility in READMEs. Your README is a web page -- GitHub renders it as HTML. This is the part to say slowly: That means the same accessibility rules apply.

      -

      Alex: The practical takeaway is this. Alt text for images and badges. A badge that says is invisible to screen readers. Write 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 -- not Click here.

      -

      Alex: Keep the teaching thread moving. The reason Good README vs. bad README matters is that bad: A single paragraph that says "This is my project. That gives the learner a simple foothold: run it with npm start." No headings, no license, no description of what the project does.

      -

      Jamie: Let's pause on Learning Cards: Writing Your First README. What should a learner take away from it?

      -

      Alex: Start with Learning Cards: Writing Your First README. There is something to understand, something to try, and something that proves the try worked.

      -

      Alex: The practical takeaway is this. 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: rather than an empty that reads as "image" with no context. Use real Markdown link text (installation guide) instead of bare URLs, so your screen reader announces the destination rather than spelling out a long URL. 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.

      +

      Alex: Keep the teaching thread moving. Start with Filling Out the Issue Form: The issue form has these fields (order may vary depending on the template). Think of it like entering a new building: first you find the lobby, then the room, then the door you actually need.

      +

      Jamie: Let's pause on Title field. What should a learner take away from it?

      +

      Alex: Start with Title field. There is something to understand, something to try, and something that proves the try worked.

      +

      Alex: First, find the Title input field (F or by landmark). Then, focus Mode → type a clear, specific title. After that, good title: "Screen reader announces wrong element count on Issues list with 50+ items". Finally, bad title: "Bug with screen reader". Treat it like a recipe: do not add the next ingredient until the previous one is actually in the bowl.

      +

      Jamie: Let's pause on Description / Body field. What should a learner take away from it?

      +

      Alex: Start with Description / Body field. There is something to understand, something to try, and something that proves the try worked.

      +

      Alex: First, tab to the body text area. Then, focus Mode → type using the Markdown template provided. After that, if no template, use this structure. It is a checklist, but a meaningful one: every item creates evidence that the next step is safe.

      +

      Alex: Treat examples as spoken recipes, not decorations. You may hear something like 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. Read the command, understand what it changes, then run it only when the repository state matches the lesson.

      -

      Alex: Keep the teaching thread moving. Here is the plain-English version of Community Health Files. Community health files tell contributors how your project operates before they write a single line of code. Put another way, 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. It is like learning a transit route. The names of the stops matter because they tell you whether you are still going the right direction.

      -

      Jamie: Let's pause on CONTRIBUTING.md. What should a learner take away from it?

      -

      Alex: This is where CONTRIBUTING.md becomes real: this file answers the question every newcomer asks: "How do I help?" A good CONTRIBUTING.md covers. That matters in practice: A sentence like "We are glad you are here" costs nothing and signals that newcomers are expected, not tolerated.

      -

      Alex: The practical takeaway is this. 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.

      -

      Alex: Keep the teaching thread moving. Keep the learner anchored in CODE OF CONDUCT.md. A code of conduct sets the social contract for your project. This is the part to say slowly: Without one, "acceptable behavior" is whatever each participant assumes it is -- and those assumptions vary widely.

      -

      Alex: The practical takeaway is this. 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.

      +

      Jamie: Let's pause on Assigning labels from the sidebar. What should a learner take away from it?

      +

      Alex: Keep the learner anchored in Assigning labels from the sidebar. See also: Chapter 09: Labels, Milestones, and Projects covers the full label and milestone system. This is the part to say slowly: While the form is open, the sidebar has dropdowns for Labels, Assignees, and Milestone.

      +

      Alex: First, tab away from the text area (or press Escape to leave Focus Mode). Then, navigate to the sidebar - press H to find "Labels" heading. After that, press Enter on the Labels gear/button. Finally, dropdown opens → ↑/↓ to navigate labels. It is like walking a hallway with named doors: read the sign, enter the right room, then confirm where you landed.

      +

      Jamie: Before we leave Assigning labels from the sidebar, what is the practical point?

      +

      Alex: First, enter to select/deselect. Then, escape to close (selections save automatically). After that, vO+Shift+Up to stop interacting with the text area. Finally, vO+U → Headings to find the "Labels" heading in the sidebar. The rhythm is simple: orient, act, verify, then continue.

      +

      Alex: A solid project habit is to treat metadata as decision support. Labels, status, assignees, and notifications tell you what kind of attention the work needs.

      +

      Jamie: Let's pause on Submitting the issue. What should a learner take away from it?

      +

      Alex: The reason Submitting the issue matters is that GitHub CLI (gh) alternative - filing a new issue. That gives the learner a simple foothold: create an issue from your terminal. The interface gets friendlier when it stops being a wall of controls and starts being a set of named places.

      +

      Alex: First, tab to "Submit new issue" button. Then, press Enter. The rhythm is simple: orient, act, verify, then continue.

      +

      Alex: Treat examples as spoken recipes, not decorations. You may hear something like 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. Read the command, understand what it changes, then run it only when the repository state matches the lesson.

      +

      Jamie: Let's pause on Learning Cards: Filing a New Issue. What should a learner take away from it?

      +

      Alex: Start with Learning Cards: Filing a New Issue. There is something to understand, something to try, and something that proves the try worked.

      +

      Alex: The practical takeaway is this. 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. 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.

      -

      Jamie: Let's pause on SECURITY.md. What should a learner take away from it?

      -

      Alex: The reason SECURITY.md matters is that see also: Appendix F: Git Security and Appendix P: Security Features for security best practices. That gives the learner a simple foothold: if someone discovers a vulnerability in your project, you do not want them to file a public issue.

      -

      Alex: The practical takeaway is this. 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.

      -

      Alex: Keep the teaching thread moving. Start with 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. The next useful detail is this: Adding a LICENSE file is a one-time step that makes your project genuinely open source. Think of it like entering a new building: first you find the lobby, then the room, then the door you actually need.

      -

      Jamie: Let's pause on Finding these files on GitHub. What should a learner take away from it?

      -

      Alex: Here is the plain-English version of Finding these files on GitHub. Navigate to any repository and click Insights then Community Standards. Put another way, GitHub shows a checklist of which community health files are present and links to add any that are missing.

      +

      Jamie: Let's pause on Tool Cards: File a New Issue. What should a learner take away from it?

      +

      Alex: Here is the plain-English version of Tool Cards: File a New Issue. github.dev (web editor): Not available -- issues are managed through the repository's Issues tab, not the code editor. Put another way, VS Code Desktop (GitHub Pull Requests extension).

      +

      Alex: First, navigate to the repository's Issues tab (or press G then I). Then, click New issue, choose a template or blank issue. After that, fill in the title and description, then click Submit new issue. Finally, open the GitHub panel in the sidebar. Treat it like a recipe: do not add the next ingredient until the previous one is actually in the bowl.

      +

      Jamie: Before we leave Tool Cards: File a New Issue, what is the practical point?

      +

      Alex: First, under Issues, click the + icon to create a new issue. Then, fill in the title and body, then click Create. It is a checklist, but a meaningful one: every item creates evidence that the next step is safe.

      +

      Alex: Treat examples as spoken recipes, not decorations. You may hear something like gh issue create --title "Your title" --body "Description here"; Or interactively:; gh issue create. Read the command, understand what it changes, then run it only when the repository state matches the lesson.

      +

      Jamie: Let's pause on Cross-Referencing Issues. What should a learner take away from it?

      +

      Alex: This is where Cross-Referencing Issues becomes real: linking issues and PRs to each other creates a trail of context that helps everyone understand the project's history.

      +

      Alex: Keep the teaching thread moving. Keep the learner anchored in 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. A good GitHub workflow is like a well-run meeting: everyone knows the topic, the next action, and who has the floor.

      -

      Alex: Keep the teaching thread moving. Start with Learning Cards: Community Health Files. There is something to understand, something to try, and something that proves the try worked.

      -

      Alex: The practical takeaway is this. 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. 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.

      -

      Jamie: How should someone choose between those options?

      -

      Alex: Keep the learner anchored in When to Use Different Communication Channels. GitHub Discussions are separate from Issues. This is the part to say slowly: Use Discussions for: "What do people think about X approach?" and Issues for: "The X button is broken.".

      -

      Alex: Use the comparison to make a decision, not to recite a table. The main contrasts are: PR comment means Feedback on a specific code change. PR review means Formal verdict (approve/request changes) with consolidated feedback. Discussion means Open-ended conversation, proposals, community Q&A.

      -

      Jamie: Let's pause on Try It: Rewrite One Comment. What should a learner take away from it?

      -

      Alex: The reason Try It: Rewrite One Comment matters is that time: 2 minutes What you need: Just your brain. That gives the learner a simple foothold: read this code review comment and rewrite it to be constructive. The interface gets friendlier when it stops being a wall of controls and starts being a set of named places.

      -

      Alex: First, what you noticed. Then, why it matters. After that, what you suggest. Finally, why the suggestion helps. The rhythm is simple: orient, act, verify, then continue.

      -

      Jamie: Before we leave Try It: Rewrite One Comment, what is the practical point?

      -

      Alex: First, encouragement. Think of it as a rail line: each stop confirms you are still on the right route before the next one.

      +

      Jamie: Let's pause on Mentioning another issue in a comment. What should a learner take away from it?

      +

      Alex: The reason Mentioning another issue in a comment matters is that simply type followed by a number anywhere in a comment body. That gives the learner a simple foothold: GitHub autocompletes with a dropdown of matching issues and PRs.

      +

      Alex: Keep the teaching thread moving. Start with Cross-repo references: owner/repo 42 - references issue 42 in a different repository.

      +

      Jamie: Let's pause on Learning Cards: Cross-Referencing Issues. What should a learner take away from it?

      +

      Alex: Start with Learning Cards: Cross-Referencing Issues. There is something to understand, something to try, and something that proves the try worked.

      +

      Alex: The practical takeaway is this. 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. 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.

      -

      Jamie: Let's pause on Contributing to Open Source. What should a learner take away from it?

      -

      Alex: Start with Contributing to Open Source: This section was previously Appendix T. The next useful detail is this: It is now part of the teaching narrative.

      -

      Alex: Keep the teaching thread moving. Here is the plain-English version of A Guide for First-Time Contributors. You do not need to be a professional developer to contribute to open source. Put another way, documentation, accessibility improvements, and bug reports are among the most valuable contributions any project can receive.

      -

      Jamie: Let's pause on 1. What Is Open Source? What should a learner take away from it?

      -

      Alex: This is where 1. What Is Open Source? becomes real: open source software is software whose source code is publicly available. That matters in practice: Anyone can read it, use it, and - in most cases - contribute to it.

      -

      Alex: The practical takeaway is this. 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.

      +

      Alex: Keep the teaching thread moving. This is where Sub-Issues - Parent and Child Relationships becomes real: sub-issues (released 2025) let you nest issues inside a parent issue to break large work into tracked pieces. That matters in practice: A "parent" issue contains a list of child issues; each child is a full issue with its own discussion, labels, and assignees. The workshop is closer to rehearsal than lecture. You hear the move, try the move, and then check what changed.

      +

      Jamie: Can you translate that into plain choices?

      +

      Alex: Start with When to Use Sub-Issues. There is something to understand, something to try, and something that proves the try worked.

      +

      Alex: Use the comparison to make a decision, not to recite a table. The main contrasts are: Large feature broken down means Parent: "Redesign navigation"; Children: "Keyboard nav," "Screen reader nav," "Mobile nav". Epic tracking means Parent: "WCAG 2.1 AA compliance"; Children: one issue per failing criterion. Release milestone means Parent: "v2.0 release"; Children: every required PR/fix.

      +

      Alex: Keep the teaching thread moving. The reason Creating a Sub-Issue matters is that the sub-issues section is announced as a region. That gives the learner a simple foothold: after linking, the child issue appears as a list item with a checkbox showing its open/closed state.

      -

      Alex: Keep the teaching thread moving. Keep the learner anchored in 2. Who Can Contribute? Contributors come from all backgrounds, skill levels, and countries. This is the part to say slowly: 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. A good GitHub workflow is like a well-run meeting: everyone knows the topic, the next action, and who has the floor.

      -

      Jamie: Let's pause on 3. What Makes a Good First Contribution? What should a learner take away from it?

      -

      Alex: Start with 3. What Makes a Good First Contribution? There is something to understand, something to try, and something that proves the try worked.

      -

      Alex: The practical takeaway is this. 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.

      -

      Alex: Keep the teaching thread moving. Start with Signs a contribution is too large for a first attempt: A well-executed small contribution is far more valuable than a large contribution that cannot be merged because it is out of scope.

      -

      Alex: The practical takeaway is this. 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.

      +

      Jamie: Let's pause on Reading Sub-Issues on a Parent Issue. What should a learner take away from it?

      +

      Alex: Start with Reading Sub-Issues on a Parent Issue: Progress indicator: The parent issue shows a completion bar (e.g., "3 of 7 completed") based on how many child issues are closed. The next useful detail is this: Screen readers announce this as a progress region.

      +

      Alex: Keep the teaching thread moving. Here is the plain-English version of Viewing a Child Issue's Parent. Every child issue shows a "Parent issue" link near the top of the page (above the description). Put another way, navigate with H or links (K) to find it. It is like learning a transit route. The names of the stops matter because they tell you whether you are still going the right direction.

      +

      Jamie: Let's pause on Sub-Issues vs. Task Lists. What should a learner take away from it?

      +

      Alex: This is where Sub-Issues vs. Task Lists becomes real: if you are working on a feature that requires multiple PRs or involves several team members, ask the maintainer to create a parent issue. That matters in practice: You can then claim individual child issues without one person owning the whole feature.

      -

      Jamie: Let's pause on 4. Finding Something to Work On. What should a learner take away from it?

      -

      Alex: Here is the plain-English version of 4. Finding Something to Work On. Most open source projects label issues that are suitable for new contributors. Put another way, how to search: On any GitHub repository, go to Issues → filter by label.

      -

      Alex: Keep the teaching thread moving. Start with Learning Cards: Finding Something to Work On. There is something to understand, something to try, and something that proves the try worked.

      -

      Alex: The practical takeaway is this. 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. 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.

      -

      Jamie: What is the pre-flight check here?

      -

      Alex: Keep the learner anchored in 5. Reading an Issue Before You Start. Before commenting "I'll take this" on an issue, ask yourself. This is the part to say slowly: 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.

      -

      Alex: The practical takeaway is this. 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.

      +

      Alex: Keep the teaching thread moving. Start with Learning Cards: Sub-Issues. There is something to understand, something to try, and something that proves the try worked.

      +

      Alex: The practical takeaway is this. 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. 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.

      +

      Jamie: Let's pause on Closing an issue. What should a learner take away from it?

      +

      Alex: The reason Closing an issue matters is that scroll to the bottom of the issue page. That gives the learner a simple foothold: click the Close issue button next to the comment box.

      +

      Alex: First, 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. Then, button approach: Tab to the "Close issue" button (at the bottom of the page, near the comment box) and press Enter. After that, optionally leave a closing comment first. Finally, 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. The rhythm is simple: orient, act, verify, then continue.

      +

      Jamie: Before we leave Closing an issue, what is the practical point?

      +

      Alex: First, button approach: Quick Nav B or Tab to find the "Close issue" button, then VO+Space. Think of it as a rail line: each stop confirms you are still on the right route before the next one.

      +

      Alex: Treat examples as spoken recipes, not decorations. You may hear something like 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. Read the command, understand what it changes, then run it only when the repository state matches the lesson.

      +

      Alex: Keep the teaching thread moving. Start with Reopening a closed issue: If an issue is Closed, the "Close issue" button becomes "Reopen issue" - navigate and activate to reopen. Think of it like entering a new building: first you find the lobby, then the room, then the door you actually need.

      -

      Jamie: Let's pause on Tool Cards: Fork, Clone, and Contribute. What should a learner take away from it?

      -

      Alex: Start with Tool Cards: Fork, Clone, and Contribute. There is something to understand, something to try, and something that proves the try worked.

      -

      Alex: First, click Fork on the repository page, then Create fork. Then, edit files directly in your fork's web interface. After that, click Contribute Open pull request to submit back to the original. Finally, fork the repo on github.com first. The rhythm is simple: orient, act, verify, then continue.

      -

      Jamie: Before we leave Tool Cards: Fork, Clone, and Contribute, what is the practical point?

      -

      Alex: First, navigate to your fork and press. to open in the web editor. Then, edit, commit, and create a PR from the Source Control panel. After that, fork on github.com, then clone your fork: Ctrl+Shift+P Git: Clone. Finally, create a branch, make edits, commit and push. Think of it as a rail line: each stop confirms you are still on the right route before the next one.

      -

      Alex: Treat examples as spoken recipes, not decorations. You may hear something like 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. Read the command, understand what it changes, then run it only when the repository state matches the lesson.

      -

      Jamie: Let's pause on The Basic Workflow. What should a learner take away from it?

      -

      Alex: Start with The Basic Workflow. There is something to understand, something to try, and something that proves the try worked.

      -

      Alex: First, fork the repository - creates your own copy on GitHub. Then, clone your fork to your computer (or open a Codespace - see Appendix N). After that, create a branch - name it something descriptive: fix/broken-link-setup-guide. Finally, make your change - edit the file, save, verify. Think of it as a rail line: each stop confirms you are still on the right route before the next one.

      -

      Jamie: Before we leave The Basic Workflow, what is the practical point?

      -

      Alex: First, commit with a clear message - "Fix broken link in setup-guide.md line 34". Then, push to your fork. After that, open a pull request from your branch to the original repository's default branch. Finally, respond to review feedback - maintainers may ask for changes; this is normal and not a rejection. Treat it like a recipe: do not add the next ingredient until the previous one is actually in the bowl.

      -

      Alex: Keep the teaching thread moving. Here is the plain-English version of Writing a Good PR Description. Example: Fixed a broken link on line 34 of setup-guide.md. Put another way, the link pointed to /docs/old-setup which no longer exists. It is like learning a transit route. The names of the stops matter because they tell you whether you are still going the right direction.

      -

      Alex: The practical takeaway is this. What did you change? Why was the change needed? How did you verify it works?

      +

      Jamie: Let's pause on Assigning an issue. What should a learner take away from it?

      +

      Alex: Here is the plain-English version of Assigning an issue. GitHub CLI (gh) alternative - assigning and labeling. Put another way, manage assignments and labels from your terminal.

      +

      Alex: First, navigate to "Assignees" heading (3 or H). Then, activate the gear/plus button. After that, type a username in the search field. Finally, select from the dropdown. Treat it like a recipe: do not add the next ingredient until the previous one is actually in the bowl.

      +

      Alex: Treat examples as spoken recipes, not decorations. You may hear something like 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". Read the command, understand what it changes, then run it only when the repository state matches the lesson.

      +

      Jamie: Let's pause on Changing labels. What should a learner take away from it?

      +

      Alex: Start with Changing labels. There is something to understand, something to try, and something that proves the try worked.

      +

      Alex: First, navigate to "Labels" heading. Then, activate the gear button. After that, select/deselect labels from the dropdown. Finally, press Escape to save. It is a checklist, but a meaningful one: every item creates evidence that the next step is safe.

      +

      Jamie: Let's pause on Transferring or deleting an issue. What should a learner take away from it?

      +

      Alex: Keep the learner anchored in Transferring or deleting an issue. Available from the "." (ellipsis) button at the top of the issue - navigate buttons with B to find it.

      -

      Jamie: How should someone ask for help in a way that gets them unstuck faster?

      -

      Alex: This is where 7. Getting Help becomes real: it is always acceptable to ask a question on an issue or pull request. That matters in practice: 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.

      -

      Alex: The practical takeaway is this. 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.

      -

      Alex: Keep the teaching thread moving. Keep the learner anchored in 8. After Your Contribution Is Merged. This matters for your GitHub profile. This is the part to say slowly: 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.

      -

      Alex: The practical takeaway is this. 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.

      -

      Jamie: Let's pause on 9. Building a Contribution Habit. What should a learner take away from it?

      -

      Alex: The reason 9. Building a Contribution Habit matters is that the hardest part of open source contribution is starting. That gives the learner a simple foothold: 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.

      +

      Alex: Keep the teaching thread moving. Start with Learning Cards: Managing Issues. There is something to understand, something to try, and something that proves the try worked.

      +

      Alex: The practical takeaway is this. 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. 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.

      +

      Jamie: Let's pause on The "good first issue" Label - Your Entry Point. What should a learner take away from it?

      +

      Alex: Start with The "good first issue" Label - Your Entry Point: When looking for your first open source contribution. The next useful detail is this: Remember: It's respectful to ask before starting.

      +

      Alex: First, navigate to any project's Issues tab. Then, filter by label: type is:open label:"good first issue" in the search. After that, read through issues until you find one in your area of interest. Finally, comment on the issue: "Hi, I'd like to work on this. Can I be assigned?". Think of it as a rail line: each stop confirms you are still on the right route before the next one.

      +

      Jamie: Before we leave The "good first issue" Label - Your Entry Point, what is the practical point?

      +

      Alex: First, wait for a maintainer to respond and assign you before starting work. Treat it like a recipe: do not add the next ingredient until the previous one is actually in the bowl.

      +

      Alex: Keep the teaching thread moving. Start with Learning Cards: The "good first issue" Label. There is something to understand, something to try, and something that proves the try worked.

      +

      Alex: The practical takeaway is this. 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. 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.

      -

      Alex: Keep the teaching thread moving. Start with Practical habits: Challenge Time: Complete Challenge 8: The Culture Layer in the Challenge Hub, then advance to Chapter 09: Labels, Milestones and Projects. The next useful detail is this: Next: Chapter 09: Labels, Milestones, and Projects Back: Chapter 07: Merge Conflicts Related appendices: Appendix M: Accessibility Standards Appendix F: Git Security Appendix O: Branch Protection. Think of it like entering a new building: first you find the lobby, then the room, then the door you actually need.

      -

      Alex: The practical takeaway is this. 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.

      +

      Jamie: Let's pause on Accessibility-Specific Issue Writing Tips. What should a learner take away from it?

      +

      Alex: This is where Accessibility-Specific Issue Writing Tips becomes real: when filing accessibility bugs, these details help maintainers reproduce and fix the problem.

      +

      Alex: First, screen reader and version - "NVDA 2025.3.3" not just "screen reader". Then, oS and version - "Windows 11 22H2". After that, browser and version - "Chrome 124.0.6367.82". Finally, GitHub interface - "Modern experience (default since Jan 2026)" or "Classic experience (opted out)". It is a checklist, but a meaningful one: every item creates evidence that the next step is safe.

      +

      Jamie: Before we leave Accessibility-Specific Issue Writing Tips, what is the practical point?

      +

      Alex: First, what was announced - quote the exact text your screen reader spoke. Then, what should have been announced - describe the expected behavior. After that, aRIA issue if known - e.g., "The button has no accessible name". Finally, steps to reproduce - numbered, step-by-step. It is like walking a hallway with named doors: read the sign, enter the right room, then confirm where you landed.

      +

      Alex: Keep the teaching thread moving. Start with Example of a well-filed accessibility issue. There is something to understand, something to try, and something that proves the try worked.

      +

      Jamie: Let's pause on Learning Cards: Accessibility-Specific Issue Writing. What should a learner take away from it?

      +

      Alex: Start with Learning Cards: Accessibility-Specific Issue Writing. There is something to understand, something to try, and something that proves the try worked.

      +

      Alex: The practical takeaway is this. 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. 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.

      -

      Jamie: What should people carry with them after this?

      -

      Alex: Carry the map. Know what page or tool you are in, know which action you are taking, and know what confirmation should follow. If the confirmation is missing, pause. That pause is not wasted time; it is professional judgment.

      -

      Jamie: That is a better way to say it than just follow the steps.

      -

      Alex: Right. Steps matter, but understanding wins. That is episode 8. Next in the series is episode 9, where we keep building the same contributor muscles.

      -
      - +

      Alex: Keep the teaching thread moving. Start with Writing Effective Issues: See also: Appendix N: Advanced Search covers search qualifiers to find existing issues before filing a new one. The next useful detail is this: 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.

      +

      Jamie: Let's pause on Bug Report Structure. What should a learner take away from it?

      +

      Alex: Here is the plain-English version of Bug Report Structure. A strong bug report answers five questions. Put another way, use this template every time you report something broken.

      +

      Jamie: Let's pause on Feature Request Structure. What should a learner take away from it?

      +

      Alex: This is where Feature Request Structure becomes real: feature requests work best when they focus on the problem before jumping to the solution. That matters in practice: 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. The workshop is closer to rehearsal than lecture. You hear the move, try the move, and then check what changed.

      +

      Alex: First, problem statement -- Describe the pain point. What are you trying to do, and why is it hard or impossible right now? Then, proposed solution -- Your best idea for fixing the problem. Be specific enough to discuss, but hold it loosely. After that, alternatives considered -- Other approaches you thought about and why they fell short. This shows you have done your homework. Finally, who benefits -- Name the audience. "Screen reader users navigating large repositories" is more compelling than "everyone.". It is a checklist, but a meaningful one: every item creates evidence that the next step is safe.

      -

      Episode 9: Labels, Milestones, and Projects

      -

      Organizing and tracking work with labels, milestones, and GitHub Projects.

      -

      Based on: Chapter 9: Labels, Milestones, and Projects

      +

      Jamie: Let's pause on General Issue Writing Principles. What should a learner take away from it?

      +

      Alex: Keep the learner anchored in General Issue Writing Principles. These rules apply to every issue -- bugs, features, questions, and everything in between. This is the part to say slowly: If you discovered two bugs during the same session, file two separate issues.

      +

      Alex: Keep the teaching thread moving. The reason Before and After: A Vague Issue vs. a Clear Issue matters is that I tried clicking and nothing happened. That gives the learner a simple foothold: the maintainer has to ask: What doesn't work?

      +

      Jamie: Let's pause on Learning Cards: Writing Effective Issues. What should a learner take away from it?

      +

      Alex: Start with Learning Cards: Writing Effective Issues. There is something to understand, something to try, and something that proves the try worked.

      +

      Alex: The practical takeaway is this. 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. 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.

      +
      +

      Jamie: Let's pause on Try It: File Your First Issue. What should a learner take away from it?

      +

      Alex: Here is the plain-English version of Try It: File Your First Issue. Time: 3 minutes What you need: Browser, signed in to GitHub. Put another way, go to the Learning Room repository and file a real issue. It is like learning a transit route. The names of the stops matter because they tell you whether you are still going the right direction.

      +

      Alex: First, navigate to the Issues tab (press G then I in Focus Mode). Then, find and activate the "New issue" button (K to links, or Tab to it). After that, in the title field, type: "Introduce myself - [Your Name]". Finally, in the description, write 2-3 sentences: who you are, what screen reader you use, and one thing you're hoping to learn today. Treat it like a recipe: do not add the next ingredient until the previous one is actually in the bowl.

      +

      Jamie: Before we leave Try It: File Your First Issue, what is the practical point?

      +

      Alex: First, press Ctrl+Enter to submit (or Tab to the Submit button and press Enter). It is a checklist, but a meaningful one: every item creates evidence that the next step is safe.

      +

      Jamie: Let's pause on Learning Cards: Filing Your First Issue. What should a learner take away from it?

      +

      Alex: This is where Learning Cards: Filing Your First Issue becomes real: day 2 Amplifier - Accessibility Agents: @issue-tracker File, read, comment on, and triage real issues manually before using any agent. That matters in practice: 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.

      +

      Alex: The practical takeaway is this. 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. 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.

      +
      +

      Jamie: What is the final checkpoint?

      +

      Alex: You should be able to point to the evidence, explain the action, and describe what you would do next if this were a real open source project. If you can teach the move back, you have learned it.

      +

      Jamie: And if they get stuck?

      +

      Alex: Read the latest message, not the loudest worry. Check the issue, the branch, the pull request, the status check, or the bot comment. Then ask for help with those facts in hand. That is how professionals collaborate.

      + + +
      +

      12. Challenge 03: Join the Conversation

      +

      Comments, mentions, reactions, and constructive peer communication.

      +

      Practice focus: Day 1 foundation

      Audio and transcript are being regenerated for this episode.

      -Read Transcript - Episode 9: Labels, Milestones, and Projects +Read Transcript - Challenge 03: Join the Conversation

      Transcript

      -

      Alex: Welcome back to Git Going with GitHub. This is episode 9: Labels, Milestones, and Projects. I am Alex, and today we are turning Labels, Milestones, and Projects from a list of instructions into a working mental model.

      -

      Jamie: And I am Jamie. I will stop us whenever the instructions sound simple on paper but might feel different with a keyboard and screen reader.

      -
      -

      Alex: Organizing and tracking work with labels, milestones, and GitHub Projects. That is the surface description. Underneath it, we are building judgment: where to focus, what to ignore, and how to verify the result.

      -

      Jamie: So we are not using the audio as a shortcut around learning. We are using it to make the learning easier to enter.

      -

      Alex: Yes. A good audio lesson gives someone enough context to try the work with confidence, even before they open the written material.

      +

      Alex: You are listening to Challenge Coach: Join the Conversation. I am Alex, and this is the calm walkthrough before the hands-on work.

      +

      Jamie: And I am Jamie. I will make sure we teach the skill instead of just reading the checklist aloud.

      -

      Jamie: Okay, set the room for us. What are we walking into?

      -

      Alex: Start with Organizing Work and Cross-Referencing on GitHub: Labels, milestones, and projects are the organizational layer of GitHub. The next useful detail is this: They turn a chaotic list of issues into a structured, navigable, prioritized body of work.

      -

      Alex: The next layer is this. Here is the plain-English version of Workshop Recommendation (Chapter 9). Chapter 9 is a guided triage chapter focused on organization skills. It is like learning a transit route. The names of the stops matter because they tell you whether you are still going the right direction.

      -

      Alex: The practical anchors are these. There are 1 guided challenge. Automation check: none by default. The evidence is structured issue comment in assigned challenge issue. The pattern is inspect, classify, explain.

      -

      Jamie: What does the learner do first, second, and then after that?

      -

      Alex: Start with Chapter 9 Challenge Set. There is something to understand, something to try, and something that proves the try worked.

      -

      Alex: First, post a triage recommendation - read an issue, recommend labels/milestone/project placement, and explain your reasoning. It is a checklist, but a meaningful one: every item creates evidence that the next step is safe.

      +

      Alex: The focus is Comments, mentions, reactions, and constructive peer communication. We will explain the concept, the action, the evidence, and the most common recovery path.

      +

      Jamie: So the learner needs the why, the move, and the checkpoint all in the same mental pocket.

      +

      Alex: That is the teaching shape: understand the concept, do the smallest real action, then verify the result before moving on.

      -

      Jamie: Turn that into a path someone can follow.

      -

      Alex: Keep the learner anchored in Challenge 9.1 Step-by-Step: Triage Recommendation Comment. Read the details of a Learning Room issue and post a structured triage recommendation that a maintainer could act on immediately. This is the part to say slowly: Labels and issue states are how we wake up agents.

      -

      Alex: For a learner, the useful signals are these. 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?

      -

      Alex: First, open the Issues tab in your Learning Room repository. Then, find any open issue that does not already have labels applied (or pick one your facilitator assigns). After that, read the issue title and full description carefully. Note. Finally, open your assigned Chapter 9 challenge issue (the one titled "Chapter 9.1: Triage Recommendation (@yourname)"). It is like walking a hallway with named doors: read the sign, enter the right room, then confirm where you landed.

      -

      Jamie: What is the ordered workflow?

      -

      Alex: First, scroll to the comment box and post a triage recommendation using this format. Then, if you have write access to the repository, apply the recommended labels and milestone directly on the issue you triaged. After that, activate the Comment button. The rhythm is simple: orient, act, verify, then continue.

      Jamie: What makes this practice feel low-stakes but still real?

      -

      Alex: The reason Completing Chapter 9: Submit Your Evidence matters is that your triage recommendation comment is your evidence. That gives the learner a simple foothold: close your Chapter 9 challenge issue when done.

      -

      Alex: The useful habit is simple: orient first, act second, verify third. That pause before acting is part of the work.

      -

      Alex: That matters because of the next idea. Start with Expected Outcomes. There is something to understand, something to try, and something that proves the try worked.

      -

      Alex: On the ground, that means a few things. 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.

      -
      +

      Alex: Start with Challenge 3: Join the Conversation: What you will do: Practice GitHub's collaboration features by commenting on a peer-simulation issue, using @mentions, and adding reactions.

      Jamie: How would you walk the room through that step by step?

      -

      Alex: Start with If You Get Stuck. There is something to understand, something to try, and something that proves the try worked.

      -

      Alex: First, not sure which label to pick? Start with just one: documentation, bug, or accessibility. You can always add more. Then, milestone is unclear? Write none and explain why - that is a valid triage decision. After that, project board is unknown? Write Needs Triage - that is the correct default. Finally, 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"). Treat it like a recipe: do not add the next ingredient until the previous one is actually in the bowl.

      -

      Jamie: Give me the sequence, because order matters here.

      -

      Alex: First, ask facilitator to review your one-sentence reason before posting. It is a checklist, but a meaningful one: every item creates evidence that the next step is safe.

      -

      Alex: This is where the talk moves from concept to action. This is where Learning Moment becomes real: triage is about clarity, not authority. That matters in practice: You do not need maintainer permissions to help organize work.

      -

      Jamie: Let's pause on Learning Pattern Used in This Chapter. What should a learner take away from it?

      -

      Alex: Start with Learning Pattern Used in This Chapter. There is something to understand, something to try, and something that proves the try worked.

      -

      Alex: First, inspect an issue carefully before acting (read before you write). Then, classify work using a consistent vocabulary (labels, milestones). After that, explain your reasoning in writing (one-sentence justification). Finally, build triage instincts that transfer to any open source project. It is like walking a hallway with named doors: read the sign, enter the right room, then confirm where you landed.

      -
      -

      Alex: Before the learner moves on. The reason What Are Labels? matters is that labels are colored tags applied to issues and pull requests. That gives the learner a simple foothold: they communicate at a glance what category, priority, or status an item belongs to. The interface gets friendlier when it stops being a wall of controls and starts being a set of named places.

      -

      Alex: A solid project habit is to treat metadata as decision support. Labels, status, assignees, and notifications tell you what kind of attention the work needs.

      -

      Jamie: Let's pause on Navigating to the Labels Page. What should a learner take away from it?

      -

      Alex: Start with Navigating to the Labels Page: 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 next useful detail is this: The Labels page shows every label with its colour, name, and description.

      -

      Alex: First, navigate to the Issues tab. Then, press K to find the "Labels" link (near the "Milestones" link in the toolbar). After that, press Enter. Finally, quick Nav K to find the "Labels" link (near the "Milestones" link in the toolbar). Think of it as a rail line: each stop confirms you are still on the right route before the next one.

      -

      Jamie: Before we leave Navigating to the Labels Page, what is the practical point?

      -

      Alex: First, vO+Space to activate. Treat it like a recipe: do not add the next ingredient until the previous one is actually in the bowl.

      -

      Alex: Treat examples as spoken recipes, not decorations. You may hear something like List all labels with descriptions; gh label list; List labels in a specific format; gh label list --json name,description. Read the command, understand what it changes, then run it only when the repository state matches the lesson.

      -

      Jamie: Let's pause on Tool Cards: Apply a Label. What should a learner take away from it?

      -

      Alex: Here is the plain-English version of Tool Cards: Apply a Label. github.dev (web editor): Not available -- labels are managed on the issue/PR page, not in the code editor. Put another way, VS Code Desktop (GitHub Pull Requests extension).

      -

      Alex: First, open the issue or PR. Then, in the right sidebar, click the gear icon next to Labels. After that, select labels from the dropdown, then click outside to apply. Finally, open the issue in the GitHub sidebar panel. Treat it like a recipe: do not add the next ingredient until the previous one is actually in the bowl.

      -

      Jamie: Before we leave Tool Cards: Apply a Label, what is the practical point?

      -

      Alex: First, click the label area to add or remove labels. Then, navigate to the sidebar → press H or 3 to find the "Labels" heading. After that, activate the Labels gear/edit button (B until you hear "Labels" button → Enter). Finally, dropdown opens showing all available labels: use ↑/↓ to navigate. It is a checklist, but a meaningful one: every item creates evidence that the next step is safe.

      -

      Alex: Treat examples as spoken recipes, not decorations. You may hear something like gh issue edit 42 --add-label "accessibility,good first issue"; gh pr edit 15 --add-label "documentation". 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. Read the command, understand what it changes, then run it only when the repository state matches the lesson.

      -
      -

      Jamie: What should they understand before typing anything?

      -

      Alex: This is where Filtering Issues by Label becomes real: screen reader users (NVDA / JAWS - Windows). That matters in practice: Option A - Filter bar: Press F → type is:open label:accessibility → Enter.

      -

      Alex: That shows up in the workshop in a few specific ways. 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.

      -

      Alex: Treat examples as spoken recipes, not decorations. You may hear something like 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. Read the command, understand what it changes, then run it only when the repository state matches the lesson.

      -

      Alex: A solid issue habit is to read the title, the body, and the timeline before acting. You are listening for the requested action, the missing evidence, and the person who needs a response.

      -

      Jamie: Let's pause on Creating a New Label. What should a learner take away from it?

      -

      Alex: Keep the learner anchored in Creating a New Label. GitHub CLI (gh) alternative - creating labels. This is the part to say slowly: Accessibility note for color: Labels have color, but they also have a text name and description - the color is supplementary information. A good GitHub workflow is like a well-run meeting: everyone knows the topic, the next action, and who has the floor.

      -

      Alex: First, navigate to Issues → Labels page. Then, tab to "New label" button → Enter. After that, fill in: Label name (F for form field), Color (use the color picker or hex code), Description. Finally, tab to "Create label" button → Enter. It is like walking a hallway with named doors: read the sign, enter the right room, then confirm where you landed.

      -

      Alex: Treat examples as spoken recipes, not decorations. You may hear something like 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". Read the command, understand what it changes, then run it only when the repository state matches the lesson.

      +

      Alex: Start with Instructions. There is something to understand, something to try, and something that proves the try worked.

      +

      Alex: The practical anchors are these. Confirm you can reproduce the problem they described. Suggest an approach to fix it. Ask a clarifying question.

      +

      Alex: First, open the Peer Simulation: Welcome Link Needs Context issue in this repository. If your facilitator gave you access to a real buddy repository, you may use your buddy's Challenge 2 issue instead. Then, leave a meaningful comment on their issue. Ideas. After that, use an @mention in your comment. For the simulation, mention @aria-bot. For a real buddy repository, mention your buddy's username. Finally, add a reaction to the original issue. Treat it like a recipe: do not add the next ingredient until the previous one is actually in the bowl.

      Jamie: What is the one idea that makes the next few steps less mysterious?

      -

      Alex: Start with Learning Cards: Labels. There is something to understand, something to try, and something that proves the try worked.

      -

      Alex: The parts worth keeping in working memory are these. 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. 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.

      -
      -

      Alex: Here is the practical turn. Start with What Are Milestones?: Milestones group issues and PRs toward a shared goal or deadline. The next useful detail is this: Think of a milestone as a sprint, a version release, or an event (like "Hackathon Day 1 Deliverables").

      -

      Alex: Here is what that changes in practice. A title and optional description. An optional due date. A progress bar (percentage of closed issues vs total).

      -

      Jamie: Let's pause on Navigating to Milestones. What should a learner take away from it?

      -

      Alex: Start with Navigating to Milestones. There is something to understand, something to try, and something that proves the try worked.

      -

      Alex: First, press K to find the "Milestones" link → Enter. Then, you see a list of milestones, each with its title, progress, and due date. Treat it like a recipe: do not add the next ingredient until the previous one is actually in the bowl.

      -

      Alex: Keep the thread going. This is where Reading a milestone becomes real: each milestone is announced as a heading + progress information. The workshop is closer to rehearsal than lecture. You hear the move, try the move, and then check what changed.

      -

      Alex: The room should hear these as checkpoints. "Hackathon Day 1 Deliverables, 3 of 8 issues closed, due April 20".

      -
      -

      Jamie: Let's pause on Opening a Milestone. What should a learner take away from it?

      -

      Alex: Start with Opening a Milestone. There is something to understand, something to try, and something that proves the try worked.

      -

      Alex: First, press 3 to navigate milestone titles (they are h3 links). Then, press Enter to open a milestone. After that, the milestone detail page shows all issues and PRs belonging to it. Finally, navigate the list with 3 (issue titles) or I (list items). It is like walking a hallway with named doors: read the sign, enter the right room, then confirm where you landed.

      -

      Jamie: Let's pause on Adding an Issue to a Milestone. What should a learner take away from it?

      -

      Alex: The reason Adding an Issue to a Milestone matters is that from the open issue, find the Milestone section in the right sidebar and click the gear icon. That gives the learner a simple foothold: a dropdown lists available milestones - click one to assign it.

      -

      Alex: First, navigate to the sidebar → "Milestone" heading (H or 3). Then, activate the Milestone gear button. After that, select a milestone from the dropdown (↑/↓ → Enter). Finally, esc to close. The rhythm is simple: orient, act, verify, then continue.

      -

      Jamie: Before we leave Adding an Issue to a Milestone, what is the practical point?

      -

      Alex: First, quick Nav H or VO+Cmd+H to find the "Milestone" heading in the sidebar. Then, quick Nav B to find and activate the Milestone gear button (VO+Space). After that, select a milestone from the dropdown (VO+Down or arrow keys → VO+Space). Think of it as a rail line: each stop confirms you are still on the right route before the next one.

      -

      Alex: Treat examples as spoken recipes, not decorations. You may hear something like 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". gh api repos/{owner}/{repo}/milestones -f title="Hackathon Day 1" -f description="Day 1 deliverables". Read the command, understand what it changes, then run it only when the repository state matches the lesson.

      -

      Jamie: Let's pause on Creating a Milestone. What should a learner take away from it?

      -

      Alex: Start with Creating a Milestone: Due date field note: The date field may render as a date picker. The next useful detail is this: Screen readers handle date pickers inconsistently - typing the date is most reliable across browsers.

      -

      Alex: A few details make that real. 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.

      -

      Alex: First, navigate to Milestones page. Then, tab to "New milestone" button → Enter. After that, fill in: Title, Description, Due date (optional). Finally, tab to "Create milestone" → Enter. Think of it as a rail line: each stop confirms you are still on the right route before the next one.

      +

      Alex: This is where Good commenting tips becomes real: I commented on the peer-simulation issue about.

      +

      Alex: That shows up in the workshop in a few specific ways. Be specific ("I found the same TODO on line 12" is better than "I agree"). Be encouraging ("Great find!" is always welcome). Be constructive (suggest, do not just criticize).

      -

      Alex: This is the part worth saying out loud. Start with Learning Cards: Milestones. There is something to understand, something to try, and something that proves the try worked.

      -

      Alex: These are the details that keep the idea from floating away. 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. 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.

      +

      Alex: Now bring the learner back to the room. Keep the learner anchored in Peer simulation check. If your facilitator gave you a real buddy, check whether they commented on your issue and reply. This is the part to say slowly: Otherwise, reply to Aria or to your own peer-simulation comment with one follow-up thought.

      Jamie: What would you say to someone who is already bracing for this to be too much?

      -

      Alex: This is where Cross-References becomes real: cross-references are links between issues, PRs, and commits. That matters in practice: GitHub automatically renders 42 as a link to issue or PR 42.

      -

      Jamie: Let's pause on Typing a Cross-Reference. What should a learner take away from it?

      -

      Alex: Keep the learner anchored in Typing a Cross-Reference. Inside any comment or PR description text area (Focus Mode).

      -

      Alex: First, type - a live-search dropdown appears. Then, continue typing the issue number or title fragment. After that, use ↓ to navigate the dropdown → Enter to select. Finally, the 42 link is inserted automatically. It is like walking a hallway with named doors: read the sign, enter the right room, then confirm where you landed.

      -

      Jamie: Before we leave Typing a Cross-Reference, what is the practical point?

      -

      Alex: First, type @ followed by a username. Then, a dropdown of suggestions appears. After that, ↓ to navigate → Enter to select. The rhythm is simple: orient, act, verify, then continue.

      +

      Alex: The reason Your comment (on a buddy's issue) matters is that good catch on the missing link in welcome.md! That gives the learner a simple foothold: @maria-student Have you also noticed the TODO on line 28?

      +

      Alex: A solid issue habit is to read the title, the body, and the timeline before acting. You are listening for the requested action, the missing evidence, and the person who needs a response.

      +

      Alex: That matters because of the next idea. Start with Buddy's reply: @your-username Thanks for pointing that out! The next useful detail is this: Let me update my issue description to cover both TODOs. Think of it like entering a new building: first you find the lobby, then the room, then the door you actually need.

      +

      Alex: The useful habit is simple: orient first, act second, verify third. That pause before acting is part of the work.

      -

      Jamie: If I am listening before the workshop starts, what should settle in my mind first?

      -

      Alex: The reason When the "Closes" Keyword Fires matters is that the Closes 42 keyword must appear in. That gives the learner a simple foothold: it does not fire from comments on the PR.

      -

      Alex: That becomes easier when you listen for these cues. The PR description (body text). A commit message pushed to the default branch.

      -

      Alex: Now bring the learner back to the room. Start with Learning Cards: Cross-References. There is something to understand, something to try, and something that proves the try worked.

      -

      Alex: The practical takeaway is this. 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. 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.

      -

      Jamie: Where do you want a learner to place their attention here?

      -

      Alex: Here is the plain-English version of GitHub Projects. See also: Appendix R: Projects Deep Dive covers advanced project board configuration, custom fields, and automation.

      +

      Jamie: Okay, set the room for us. What are we walking into?

      +

      Alex: Start with What makes a good comment. There is something to understand, something to try, and something that proves the try worked.

      +

      Alex: Here is what that changes in practice. Specific reference: Mention what you are responding to (line numbers, file names). Constructive tone: Add information or ask questions rather than just agreeing. @mention: Tag the person you are talking to so they get notified. Actionable: Your comment helps move the conversation forward.

      +

      Alex: This is where the talk moves from concept to action. Start with Alternate approaches. There is something to understand, something to try, and something that proves the try worked.

      +

      Alex: The room should hear these as checkpoints. Comment on an issue someone else filed. Reply to a comment on your own issue. Ask a clarifying question about someone else's proposed change.

      Alex: A solid pull request habit is to separate three questions: what changed, why it changed, and what still needs review. That keeps the conversation useful instead of noisy.

      +

      Jamie: Where do you want a learner to place their attention here?

      +

      Alex: Keep the learner anchored in What matters. The learning objective is participating in asynchronous collaboration. This is the part to say slowly: A single thoughtful comment with an @mention is sufficient evidence.

      -

      Alex: Another way to ground it. This is where What Is a GitHub Project? becomes real: GitHub Projects is a built-in project management tool. That matters in practice: It can display issues and PRs from across multiple repositories in one view.

      -

      Jamie: Let's pause on Finding a Project. What should a learner take away from it?

      -

      Alex: Keep the learner anchored in Finding a Project. From an organization page or repository.

      -

      Alex: First, navigate to the "Projects" tab. Then, press 3 to navigate project titles (they are h3 links). After that, enter to open a project. It is like walking a hallway with named doors: read the sign, enter the right room, then confirm where you landed.

      -

      Alex: Hold that next to this. The reason What is announced per row matters is that "Add keyboard navigation to carousel Status: In Progress Assignee: username Priority: High". The interface gets friendlier when it stops being a wall of controls and starts being a set of named places.

      -
      -

      Jamie: What is the safe way to learn from that example?

      -

      Alex: Start with Navigating a Project - Board View. There is something to understand, something to try, and something that proves the try worked.

      -

      Alex: Treat examples as spoken recipes, not decorations. You may hear something like 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. Read the command, understand what it changes, then run it only when the repository state matches the lesson.

      -

      Jamie: Let's pause on Adding an Issue to a Project. What should a learner take away from it?

      -

      Alex: Start with Adding an Issue to a Project. There is something to understand, something to try, and something that proves the try worked.

      -

      Alex: First, navigate to the sidebar "Projects" section (H or 3). Then, activate the Projects gear button. After that, select the project from the dropdown. Finally, activate "Add item" button at the bottom of a column/table. Treat it like a recipe: do not add the next ingredient until the previous one is actually in the bowl.

      -

      Jamie: Before we leave Adding an Issue to a Project, what is the practical point?

      -

      Alex: First, type to search for existing issues. Then, select the issue → it's added to the project. It is a checklist, but a meaningful one: every item creates evidence that the next step is safe.

      -

      Jamie: Give me the version that sounds like an instructor, not a manual.

      -

      Alex: Start with Learning Cards: GitHub Projects. There is something to understand, something to try, and something that proves the try worked.

      -

      Alex: The practical takeaway is this. 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. 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.

      -
      -

      Alex: That connects to another useful point. Keep the learner anchored in Practical Organization Strategy for the Hackathon. Here is a recommended structure for your Learning Room sandbox project. A good GitHub workflow is like a well-run meeting: everyone knows the topic, the next action, and who has the floor.

      -

      Jamie: Let's pause on Try It: Label and Link. What should a learner take away from it?

      -

      Alex: The reason Try It: Label and Link matters is that time: 2 minutes What you need: Browser, signed in to GitHub. That gives the learner a simple foothold: go to the Learning Room repository and do two things.

      -

      Alex: First, 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. Then, 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. The rhythm is simple: orient, act, verify, then continue.

      -
      -

      Jamie: What should people carry with them after this?

      -

      Alex: Carry the map. Know what page or tool you are in, know which action you are taking, and know what confirmation should follow. If the confirmation is missing, pause. That pause is not wasted time; it is professional judgment.

      -

      Jamie: That is a better way to say it than just follow the steps.

      -

      Alex: Right. Steps matter, but understanding wins. That is episode 9. Next in the series is episode 10, where we keep building the same contributor muscles.

      -
      - -
      -

      Episode 10: Notifications and Mentions

      -

      Managing your notification inbox, @mentions, and strategies for avoiding overload.

      -

      Based on: Chapter 10: Notifications and Mentions

      -

      Audio and transcript are being regenerated for this episode.

      -
      -Read Transcript - Episode 10: Notifications and Mentions - -

      Transcript

      -

      Alex: This is Git Going with GitHub, episode 10: Notifications and Mentions. I am Alex. By the end of this episode, Notifications and Mentions should feel less like a wall of GitHub words and more like a set of moves you can trust.

      -

      Jamie: And I am Jamie. I am here for the practical questions: what should I listen for, what can go wrong, and what is the next calm move?

      -
      -

      Alex: Today we are working on this: Managing your notification inbox, @mentions, and strategies for avoiding overload. I want the learner to leave with a mental map, not just a remembered path through buttons.

      -

      Jamie: So the goal is understanding first, then action, then confirmation.

      -

      Alex: Right. We are building a rhythm: orient yourself, take one intentional action, then verify what changed before moving on.

      -
      -

      Jamie: Okay, set the room for us. What are we walking into?

      -

      Alex: Start with Managing Your GitHub Notification Inbox: See also: Appendix V: GitHub Mobile for managing notifications on your phone. The next useful detail is this: GitHub notifications are how GitHub tells you when something needs your attention.

      -

      Alex: A solid project habit is to treat metadata as decision support. Labels, status, assignees, and notifications tell you what kind of attention the work needs.

      -

      Alex: The next layer is this. Here is the plain-English version of Workshop Recommendation (Chapter 10). For this workshop, Chapter 10 is a guided practice chapter, not a graded automation chapter. It is like learning a transit route. The names of the stops matter because they tell you whether you are still going the right direction.

      -

      Alex: The practical anchors are these. There are 1 guided walkthrough. Automation check: none - notification settings are account-level and cannot be validated by the Learning Room PR bot. The evidence is structured completion comment on your assigned challenge issue. The pattern is configure, filter, act.

      +

      Alex: Before the learner moves on. The reason Filing, Managing, and Participating in GitHub Issues matters is that issues are where open source collaboration begins. That gives the learner a simple foothold: everything from finding the right issue to file a perfect bug report - all with your keyboard and screen reader. The interface gets friendlier when it stops being a wall of controls and starts being a set of named places.

      +

      Jamie: How should they picture the shape of the workshop?

      +

      Alex: Start with Workshop Recommendation (Chapter 5 / Challenges 2-3): Chapter 5 is the first issue-based challenge chapter with short, confidence-building tasks. The next useful detail is this: It supports Challenge 2 (File Your First Issue) and Challenge 3 (Join the Conversation).

      +

      Alex: A few details make that real. There are 2 core challenges plus one optional extension. Each challenge should take under 10 minutes. The evidence is issue comments and issue metadata. The pattern is claim - act - confirm.

      Jamie: What does the learner do first, second, and then after that?

      -

      Alex: Start with Chapter 10 Challenge Set. There is something to understand, something to try, and something that proves the try worked.

      -

      Alex: First, configure notifications and practice inbox management - set your watch level, use filters to find relevant notifications, and perform one inbox action. It is a checklist, but a meaningful one: every item creates evidence that the next step is safe.

      +

      Alex: Here is the plain-English version of Chapter 5 Challenge Set. Chapter 5 focuses on issue skills. Put another way, you do NOT need to create a branch or edit any files for these challenges.

      +

      Alex: First, create your first issue - file a new issue with a clear title and description. Then, comment and @mention - leave a comment on a classmate's issue and tag them with an @mention. After that, optional extension: Add a sub-issue - break a larger issue into smaller, trackable pieces if your repository has sub-issues enabled. Treat it like a recipe: do not add the next ingredient until the previous one is actually in the bowl.

      Jamie: Turn that into a path someone can follow.

      -

      Alex: Keep the learner anchored in Challenge 10.1 Step-by-Step: Notification Inbox Walkthrough. Set up a useful notification workflow so you can keep up with reviews, mentions, and assignments without inbox overload. This is the part to say slowly: the GitHub.com notifications page and your Learning Room repository settings.

      -

      Alex: For a learner, the useful signals are these. Press M to mute the thread (you will not receive future updates),. Press E to mark done (removes it from inbox but you can still get future updates).

      -

      Alex: First, open your Learning Room repository on GitHub.com. Then, find the Watch button near the top-right of the repository page (next to Star and Fork). After that, 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. Finally, open the notifications inbox by navigating to https://github.com/notifications (or activate the bell icon in the GitHub header). It is like walking a hallway with named doors: read the sign, enter the right room, then confirm where you landed.

      +

      Alex: This is where Challenge 2 Step-by-Step: Create Your First Issue becomes real: file a new issue in your Learning Room repository with a specific title and a meaningful description. That matters in practice: Issues are the prompts that wake up AI.

      +

      Alex: For a learner, the useful signals are these. "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". What the problem is or what content is missing.

      +

      Alex: First, open your Learning Room repository in your browser. Then, navigate to the Issues tab (press G then I to jump there with keyboard shortcuts, or find the "Issues" link in the repository navigation). After that, activate the New issue button. Finally, if a template picker appears, select Open a blank issue (or choose a template if one fits). It is a checklist, but a meaningful one: every item creates evidence that the next step is safe.

      Jamie: What is the ordered workflow?

      -

      Alex: First, in the notification filters, activate the Review requested filter. This shows only notifications where someone has asked you to review their PR. Then, clear that filter and activate the Assigned filter. This shows notifications for issues and PRs assigned to you. After that, open one notification by activating its title link. Read it briefly, then navigate back to the inbox. Finally, perform one inbox action on a non-critical notification thread. The rhythm is simple: orient, act, verify, then continue.

      -

      Jamie: What makes this practice feel low-stakes but still real?

      -

      Alex: The reason Completing Chapter 10: Submit Your Evidence matters is that open your assigned Chapter 10 challenge issue and post a completion comment. That gives the learner a simple foothold: close your Chapter 10 challenge issue when done.

      -

      Alex: The useful habit is simple: orient first, act second, verify third. That pause before acting is part of the work.

      -

      Alex: That matters because of the next idea. Start with Expected Outcomes. There is something to understand, something to try, and something that proves the try worked.

      -

      Alex: On the ground, that means a few things. 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.

      +

      Alex: First, in the Title field, type a clear, specific title (at least 12 characters). Then, in the Body field, write a meaningful description (at least 80 characters). After that, activate Submit new issue. Finally, copy the issue URL or note the issue number (for example, 150). You will reference this later. It is like walking a hallway with named doors: read the sign, enter the right room, then confirm where you landed.

      +

      Jamie: Give me the sequence, because order matters here.

      +

      Alex: Keep the learner anchored in Challenge 4.2 Step-by-Step: Comment and @Mention. Leave a comment on another student's issue and use an @mention to notify them. This is the part to say slowly: the Issues tab of your Learning Room repository on GitHub.com. A good GitHub workflow is like a well-run meeting: everyone knows the topic, the next action, and who has the floor.

      +

      Alex: The parts worth keeping in working memory are these. "@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.".

      +

      Alex: First, open the Issues tab in your Learning Room repository. Then, find an issue created by a classmate (look for issues from Challenge 4.1, or browse recent open issues). After that, open the issue by activating its title link. Finally, read the issue description to understand what they reported. It is like walking a hallway with named doors: read the sign, enter the right room, then confirm where you landed.

      +

      Jamie: Let's pause on Challenge 4.2 Step-by-Step: Comment and @Mention. What should a learner take away from it?

      +

      Alex: First, scroll to the comment box at the bottom of the issue. Then, write a helpful comment that @mentions the issue author by username. After that, activate the Comment button (or press Ctrl+Enter). The rhythm is simple: orient, act, verify, then continue.

      +

      Jamie: Let's pause on Challenge 4.3 Step-by-Step: Add a Sub-Issue. What should a learner take away from it?

      +

      Alex: The reason Challenge 4.3 Step-by-Step: Add a Sub-Issue matters is that break a larger issue into smaller, trackable pieces using GitHub's sub-issue feature. That gives the learner a simple foothold: the issue you created in Challenge 4.1 (or any open issue you have permission to edit).

      +

      Alex: On the ground, that means a few things. Sub-issue: "Add alt text to welcome banner image". Sub-issue: "Fix heading hierarchy in Getting Started section".

      +

      Alex: First, open the issue you created in Challenge 4.1. Then, 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. After that, activate Add sub-issue and choose Create new sub-issue. Finally, 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". The rhythm is simple: orient, act, verify, then continue.

      +

      Jamie: Before we leave Challenge 4.3 Step-by-Step: Add a Sub-Issue, what is the practical point?

      +

      Alex: First, add a short description and activate Create. Then, the sub-issue now appears nested under the parent issue with a progress indicator. Think of it as a rail line: each stop confirms you are still on the right route before the next one.

      -

      Jamie: How would you walk the room through that step by step?

      +

      Alex: Here is the practical turn. Start with 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. The next useful detail is this: Replace [number] with the actual issue numbers.

      +

      Jamie: Give me the version that sounds like an instructor, not a manual.

      +

      Alex: Start with Expected Outcomes. There is something to understand, something to try, and something that proves the try worked.

      +

      Alex: These are the details that keep the idea from floating away. 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.

      +

      Jamie: Let's pause on If You Get Stuck. What should a learner take away from it?

      Alex: Start with If You Get Stuck. There is something to understand, something to try, and something that proves the try worked.

      -

      Alex: First, can't find the Watch button? It is near the top-right of the repository page, in the same row as Star and Fork. Then, 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. After that, 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. Finally, filters not showing results? Clear all filters first (click the X next to each active filter), then apply one filter at a time. Treat it like a recipe: do not add the next ingredient until the previous one is actually in the bowl.

      -

      Jamie: Give me the sequence, because order matters here.

      -

      Alex: First, ask facilitator to model one inbox action live, then repeat the steps yourself. Then, finished but not sure you did it right? Compare your work against the Challenge 9 reference solution. It is a checklist, but a meaningful one: every item creates evidence that the next step is safe.

      -

      Alex: This is where the talk moves from concept to action. This is where Learning Moment becomes real: notification management protects focus. That matters in practice: You can stay responsive to your team without drowning in updates.

      +

      Alex: First, can't find a classmate's issue? Filter the Issues tab by is:open and look for recent ones. Then, @mention not working? Make sure you type @ immediately followed by the username with no space. After that, sub-issue option not visible? Ask a facilitator - the feature may need to be enabled for the repository. Finally, still stuck? Ask a facilitator for a direct issue link. It is a checklist, but a meaningful one: every item creates evidence that the next step is safe.

      +

      Jamie: Before we leave If You Get Stuck, what is the practical point?

      +

      Alex: First, finished but not sure you did it right? Compare your work against the Challenge 2 reference solution or the Challenge 3 reference solution. It is like walking a hallway with named doors: read the sign, enter the right room, then confirm where you landed.

      +
      +

      Jamie: If I am listening before the workshop starts, what should settle in my mind first?

      +

      Alex: Keep the learner anchored in Learning Moment. Issues are collaborative spaces, not just task lists. This is the part to say slowly: An @mention tells someone "I need your attention here." Sub-issues turn vague tasks into clear checklists.

      Jamie: Let's pause on Learning Pattern Used in This Chapter. What should a learner take away from it?

      Alex: Start with Learning Pattern Used in This Chapter. There is something to understand, something to try, and something that proves the try worked.

      -

      Alex: First, configure settings proactively (watch level) before work generates noise. Then, use filters to find signal in noise (review requests, assignments). After that, take decisive action on each notification (mute, done, or respond). Finally, build a daily routine that keeps your inbox manageable. It is like walking a hallway with named doors: read the sign, enter the right room, then confirm where you landed.

      +

      Alex: First, start with a small, safe action (create an issue). Then, practice communication in public issue threads (@mention a peer). After that, organize work into smaller pieces (sub-issues). Finally, leave clear evidence in the issue timeline. The rhythm is simple: orient, act, verify, then continue.

      +

      Jamie: Before we leave Learning Pattern Used in This Chapter, what is the practical point?

      +

      Alex: First, build momentum for file editing and PR work in Chapter 6. Think of it as a rail line: each stop confirms you are still on the right route before the next one.

      +

      Jamie: Let's pause on About Learning Cards in This Chapter. What should a learner take away from it?

      +

      Alex: Start with About Learning Cards in This Chapter: This chapter provides learning cards: expandable blocks that offer perspective-specific guidance for different ways of working. The next useful detail is this: Not every card appears at every step.

      -

      Alex: Before the learner moves on. The reason What Generates a Notification? matters is that GitHub sends you a notification when. The interface gets friendlier when it stops being a wall of controls and starts being a set of named places.

      -

      Jamie: What would you say to someone who is already bracing for this to be too much?

      -

      Alex: Start with Notification Subscription Levels: For each repository, you choose how many notifications to receive.

      -

      Jamie: Let's pause on Changing your watch settings for a repo. What should a learner take away from it?

      -

      Alex: Here is the plain-English version of Changing your watch settings for a repo. At the top of any repository page, find the Watch button (near Star and Fork). Put another way, click it to open a dropdown with levels: Participating and @mentions, All Activity, Custom, and Ignore.

      -

      Alex: First, find the Watch button in the repo header (B to navigate buttons → find "Watch [N]" or "Unwatch" button). Then, press Enter to open the dropdown. After that, press ↑/↓ to navigate the subscription options. Finally, press Enter to select your preferred level. Treat it like a recipe: do not add the next ingredient until the previous one is actually in the bowl.

      -

      Jamie: Before we leave Changing your watch settings for a repo, what is the practical point?

      -

      Alex: First, the button label updates to confirm your choice. Then, quick Nav B to find the Watch button in the repo header (listen for "Watch" or "Unwatch"). After that, vO+Space to open the dropdown. Finally, vO+Down or arrow keys to navigate subscription options. It is a checklist, but a meaningful one: every item creates evidence that the next step is safe.

      -
      -

      Jamie: Let's pause on Tool Cards: Manage Notifications. What should a learner take away from it?

      -

      Alex: This is where Tool Cards: Manage Notifications becomes real: VS Code Desktop (GitHub Pull Requests extension). That matters in practice: GitHub Desktop: GitHub Desktop does not manage notifications.

      -

      Alex: First, go to github.com/notifications (or press G then N). Then, use E to mark done, I to mark read/unread, Shift+M to mute a thread. After that, the Notifications view in the GitHub sidebar shows items needing attention. Finally, click a notification to open the related issue or PR directly in VS Code. It is a checklist, but a meaningful one: every item creates evidence that the next step is safe.

      -

      Alex: Treat examples as spoken recipes, not decorations. You may hear something like 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. 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. Read the command, understand what it changes, then run it only when the repository state matches the lesson.

      -

      Jamie: Let's pause on Navigating the notification list. What should a learner take away from it?

      -

      Alex: Keep the learner anchored in Navigating the notification list. The inbox shows notifications grouped by date (Today, Yesterday, This week, Older). This is the part to say slowly: Each row shows the repository, the issue or PR title, the event type, and the time. A good GitHub workflow is like a well-run meeting: everyone knows the topic, the next action, and who has the floor.

      -

      Alex: First, d → main content landmark. Then, h to navigate group headings (Today / Yesterday / This week / Older). After that, tab through individual notifications - each row announces: repo name, issue/PR title, event type, time. Finally, enter to open the notification (goes to the issue/PR page). It is like walking a hallway with named doors: read the sign, enter the right room, then confirm where you landed.

      -

      Jamie: Before we leave Navigating the notification list, what is the practical point?

      -

      Alex: First, vO+U → Main → navigate to notification list. Then, vO+Down to move through notifications. After that, vO+Space to open a notification. The rhythm is simple: orient, act, verify, then continue.

      -

      Jamie: What is the one idea that makes the next few steps less mysterious?

      -

      Alex: The reason What is announced per notification matters is that "microsoft/vscode - Add keyboard shortcut for accessible view - @username mentioned you - 2 hours ago". That gives the learner a simple foothold: components: repo/org thread title event type timestamp.

      +

      Jamie: How do you keep commands from becoming magic words?

      +

      Alex: Here is the plain-English version of Local Git Alternative: Working from Your Clone. If you cloned the learning-room in Block 0 and prefer working locally. Put another way, during Block 0 you cloned the Learning Room repository to your computer. It is like learning a transit route. The names of the stops matter because they tell you whether you are still going the right direction.

      +

      Alex: Treat examples as spoken recipes, not decorations. You may hear something like cd /Documents/learning-room or wherever you cloned it; git status should show "On branch main". 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. Read the command, understand what it changes, then run it only when the repository state matches the lesson.

      +

      Alex: A solid Git habit is to know which branch you are on, what changed, and what confirmation you expect before you run the next command.

      +

      Jamie: Let's pause on What Is a GitHub Issue? What should a learner take away from it?

      +

      Alex: This is where What Is a GitHub Issue? becomes real: an issue is a discussion thread attached to a repository. That matters in practice: Every issue has a number ( 42), a state (Open or Closed), a title, a description, and a comment thread.

      +

      Alex: That becomes easier when you listen for these cues. 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".

      +

      Jamie: Let's pause on From a repository page. What should a learner take away from it?

      +

      Alex: Keep the learner anchored in From a repository page. Click the Issues tab in the repository navigation bar below the repository name. This is the part to say slowly: The tab shows the open issue count (e.g., "Issues · 14").

      +

      Alex: First, press D to navigate to the "Repository navigation" landmark. Then, press K or Tab to move through the tab links. After that, find "Issues" - it will be announced with the count: "Issues, 14 open". Finally, press Enter to open the Issues tab. It is like walking a hallway with named doors: read the sign, enter the right room, then confirm where you landed.

      +

      Jamie: Before we leave From a repository page, what is the practical point?

      +

      Alex: First, vO+U → Landmarks → navigate to "Repository navigation". Then, vO+Right or Quick Nav K to move through tab links. After that, find "Issues" - VoiceOver announces the count: "Issues 14". Finally, vO+Space to activate the Issues tab. The rhythm is simple: orient, act, verify, then continue.

      +

      Alex: Treat examples as spoken recipes, not decorations. You may hear something like gh issue list. gh issue list --label "good first issue"; gh issue list --assignee @me; gh issue list --state closed. Read the command, understand what it changes, then run it only when the repository state matches the lesson.

      -

      Alex: Here is the practical turn. Start with Learning Cards: The Notifications Inbox. There is something to understand, something to try, and something that proves the try worked.

      -

      Alex: Here is what that changes in practice. 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. 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.

      -

      Jamie: Give me the version that sounds like an instructor, not a manual.

      -

      Alex: Here is the plain-English version of Inbox Actions - Keyboard Shortcuts. These shortcuts work when a notification is focused in the inbox. Put another way, these are GitHub's own keyboard shortcuts.

      -

      Alex: A solid navigation habit is to prove where you are before activating controls. Headings, landmarks, and the address bar are not trivia; they are your map.

      -

      Alex: Keep the thread going. This is where Filtering the Inbox becomes real: the left sidebar has quick filters. The workshop is closer to rehearsal than lecture. You hear the move, try the move, and then check what changed.

      +

      Jamie: Let's pause on Direct URL. What should a learner take away from it?

      +

      Alex: The reason Direct URL matters is that navigate directly: https://github.com/[owner]/[repo]/issues.

      +

      Alex: Keep the thread going. Start with Learning Cards: Navigating to the Issues List. There is something to understand, something to try, and something that proves the try worked.

      +

      Alex: The practical takeaway is this. 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. 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.

      +

      Jamie: Let's pause on Page structure. What should a learner take away from it?

      +

      Alex: Here is the plain-English version of Page structure. 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. Put another way, this is often faster than tabbing through many elements and helps you understand the full page structure before diving in.

      -

      Jamie: Let's pause on Filtering by repository or organization. What should a learner take away from it?

      -

      Alex: Keep the learner anchored in Filtering by repository or organization. At the top of the notification list there is a filter/search field. This is the part to say slowly: Click the filter/search box at the top of the notification list and type a repository or organization name.

      -

      Alex: First, press F or E to reach the filter input. Then, focus Mode → type repo name or org name. After that, results filter in real time. Finally, press Esc to clear the filter. It is like walking a hallway with named doors: read the sign, enter the right room, then confirm where you landed.

      -

      Jamie: Before we leave Filtering by repository or organization, what is the practical point?

      -

      Alex: First, quick Nav F to reach the filter input. Then, vO+Shift+Down to interact → type repo or org name. After that, press Esc to clear the filter and VO+Shift+Up to stop interacting. The rhythm is simple: orient, act, verify, then continue.

      -

      Jamie: Let's pause on The "mark all as done" workflow. What should a learner take away from it?

      -

      Alex: The reason The "mark all as done" workflow matters is that after a busy day or coming back from time away, clear your inbox methodically.

      -

      Alex: First, open Notifications inbox. Then, tab to "Mark all as done" button → Enter (clears everything at once). After that, then use the "Done" filter to retrieve any you want to revisit. The rhythm is simple: orient, act, verify, then continue.

      -

      Jamie: Let's pause on Muting a noisy thread. What should a learner take away from it?

      -

      Alex: Start with Muting a noisy thread: If a thread generates too many notifications. The next useful detail is this: Screen reader users (NVDA / JAWS - Windows).

      -

      Alex: First, open the issue or PR page. Then, in the right sidebar, scroll to the Notifications section. After that, click Unsubscribe - you will stop receiving notifications from this thread. Finally, alternatively, from the inbox: hover over the notification row and click the mute icon (or the … menu). Think of it as a rail line: each stop confirms you are still on the right route before the next one.

      -

      Jamie: Before we leave Muting a noisy thread, what is the practical point?

      -

      Alex: First, open the notification. Then, on the issue/PR page, navigate the sidebar to the Notifications section (H or D). After that, activate the Unsubscribe button. Finally, or from the inbox: focus the notification → press M to mute. Treat it like a recipe: do not add the next ingredient until the previous one is actually in the bowl.

      +

      Jamie: Let's pause on How to read the issue list. What should a learner take away from it?

      +

      Alex: This is where How to read the issue list becomes real: the issues list shows each issue as a row with its title, labels, number, assignee avatars, and comment count. That matters in practice: Closed issues show a purple merged/closed badge.

      +

      Alex: The practical takeaway is this. 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.

      +

      Alex: First, press D to reach the "Search Results List" landmark. Then, press 3 (h3) to navigate by issue titles - each issue title is an h3 link. After that, press I to move between list items if you want more detail per item. Finally, press Enter on a title to open that issue. It is a checklist, but a meaningful one: every item creates evidence that the next step is safe.

      +

      Jamie: Before we leave How to read the issue list, what is the practical point?

      +

      Alex: First, vO+U → Landmarks → navigate to "Search Results List". Then, vO+Down to read through items. After that, h (with Quick Nav on) or VO+U → Headings to jump by issue title. It is like walking a hallway with named doors: read the sign, enter the right room, then confirm where you landed.

      +

      Jamie: Let's pause on What is announced per issue. What should a learner take away from it?

      +

      Alex: Keep the learner anchored in What is announced per issue. When you navigate to an issue in the list, your screen reader will announce (in some order).

      +

      Alex: The practical takeaway is this. 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").

      +

      Alex: Another way to ground it. Start with Learning Cards: The Issues List Page. There is something to understand, something to try, and something that proves the try worked.

      +

      Alex: The practical takeaway is this. 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. 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.

      -

      Jamie: Let's pause on Dealing with @mentions you didn't expect. What should a learner take away from it?

      -

      Alex: Here is the plain-English version of Dealing with @mentions you didn't expect. If you were @mentioned in an unfamiliar thread. It is like learning a transit route. The names of the stops matter because they tell you whether you are still going the right direction.

      -

      Alex: First, read the thread for context before responding. Then, 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. After that, unsubscribe after reading if you don't need to stay in the loop. Treat it like a recipe: do not add the next ingredient until the previous one is actually in the bowl.

      -

      Jamie: If I am listening before the workshop starts, what should settle in my mind first?

      -

      Alex: Start with Learning Cards: Managing Notifications at Scale. There is something to understand, something to try, and something that proves the try worked.

      -

      Alex: That shows up in the workshop in a few specific ways. 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. 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.

      -

      Alex: That connects to another useful point. Keep the learner anchored in Notification Settings - Per Your Account. Global notification preferences are at https://github.com/settings/notifications.

      +

      Jamie: Let's pause on Filtering and Searching Issues. What should a learner take away from it?

      +

      Alex: Start with Filtering and Searching Issues: Filtering lets you narrow the list to find the right issue quickly.

      +

      Jamie: Let's pause on Using the search/filter bar. What should a learner take away from it?

      +

      Alex: Start with Using the search/filter bar. There is something to understand, something to try, and something that proves the try worked.

      +

      Alex: First, press F or E to jump to the filter input field (or navigate from the landmark). Then, switch to Focus Mode (NVDA+Space / Insert+Z) if not already in it. After that, type your filter or search query. Finally, press Enter to apply. Treat it like a recipe: do not add the next ingredient until the previous one is actually in the bowl.

      +

      Jamie: Let's pause on Using the filter buttons. What should a learner take away from it?

      +

      Alex: This is where Using the filter buttons becomes real: above the issue list, there is an actions toolbar with filter buttons for Labels, Milestones, Assignees, etc. That matters in practice: The filter buttons do not indicate the current filter state.

      +

      Alex: The practical takeaway is this. 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.

      +

      Alex: First, press Tab from the search bar (or Shift+Tab from the issue list) to reach the actions toolbar. Then, press ←/→ to move between toolbar options (Label, Milestone, Assignee, Sort). After that, press Enter to open the selected dropdown. Finally, use ↑/↓ to navigate options in the dropdown. It is a checklist, but a meaningful one: every item creates evidence that the next step is safe.

      +

      Jamie: Before we leave Using the filter buttons, what is the practical point?

      +

      Alex: First, press Enter or Space to select. Then, press Escape to close (filter applies immediately). After that, tab forward from the search bar to reach the filter buttons, or use Quick Nav to find them. Finally, vO+Left/Right to move between Label, Milestone, Assignee, Sort buttons. It is like walking a hallway with named doors: read the sign, enter the right room, then confirm where you landed.

      +

      Alex: Treat examples as spoken recipes, not decorations. You may hear something like 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". Read the command, understand what it changes, then run it only when the repository state matches the lesson.

      -

      Jamie: Where do you want a learner to place their attention here?

      -

      Alex: The reason Starring vs. Watching - What Is the Difference? matters is that new contributors often confuse these two. That gives the learner a simple foothold: they appear next to each other on every repository page and do completely different things.

      -

      Alex: A solid pull request habit is to separate three questions: what changed, why it changed, and what still needs review. That keeps the conversation useful instead of noisy.

      -

      Alex: Now bring the learner back to the room. Start with Starring a Repository: Starring is GitHub's equivalent of a bookmark + public endorsement. The next useful detail is this: The star count on a repository is a community signal of popularity. Think of it like entering a new building: first you find the lobby, then the room, then the door you actually need.

      -

      Jamie: Let's pause on Common Mistake: Accidental Watching. What should a learner take away from it?

      -

      Alex: Here is the plain-English version of 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. Put another way, 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.

      +

      Alex: Hold that next to this. Keep the learner anchored in Open vs Closed filter. The two state links "Open" and "Closed" appear near the top of the issue list. This is the part to say slowly: Press K to navigate links until you find them, or look for them as buttons near the search bar. A good GitHub workflow is like a well-run meeting: everyone knows the topic, the next action, and who has the floor.

      +

      Jamie: Let's pause on Learning Cards: Filtering and Searching Issues. What should a learner take away from it?

      +

      Alex: Start with Learning Cards: Filtering and Searching Issues. There is something to understand, something to try, and something that proves the try worked.

      +

      Alex: The practical takeaway is this. 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. 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.

      +

      Alex: That connects to another useful point. Start with Landing on an issue page: When you open an issue, the page structure is.

      -

      Alex: Another way to ground it. This is where How to silence a repository you accidentally over-subscribed to becomes real: this immediately reduces notifications from that repository to only threads you personally participated in.

      -

      Jamie: Let's pause on Learning Cards: Starring vs. Watching. What should a learner take away from it?

      -

      Alex: Start with Learning Cards: Starring vs. Watching. There is something to understand, something to try, and something that proves the try worked.

      -

      Alex: These are the details that keep the idea from floating away. 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. 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.

      -

      Alex: This is the part worth saying out loud. Start with NVDA. There is something to understand, something to try, and something that proves the try worked.

      -

      Alex: That becomes easier when you listen for these cues. 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.

      +

      Jamie: Let's pause on Reading the issue description. What should a learner take away from it?

      +

      Alex: Here is the plain-English version of Reading the issue description. Browse Mode recommended: The issue detail page is primarily text-based. Put another way, stay in Browse Mode (not Focus Mode) for reading - it gives you full heading (H), section (D), and link (K) navigation throughout the page.

      +

      Alex: First, press 2 to reach the "Description" heading. Then, press ↓ to read the content line by line,. After that, use NVDA+↓ (NVDA say all) to have it read continuously. Treat it like a recipe: do not add the next ingredient until the previous one is actually in the bowl.

      +

      Alex: Treat examples as spoken recipes, not decorations. You may hear something like 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. Read the command, understand what it changes, then run it only when the repository state matches the lesson.

      +

      Alex: This is the part worth saying out loud. This is where Reading comments and activity becomes real: each comment in the thread is marked as an h3. That matters in practice: Other timeline events (label added, PR linked, issue closed) appear between comments in the activity stream. The workshop is closer to rehearsal than lecture. You hear the move, try the move, and then check what changed.

      +

      Alex: The practical takeaway is this. Commenter's username. Timestamp ("2 days ago"). Body text. Reactions (if any - announced as a button with an emoji and count).

      +

      Jamie: Let's pause on Learning Cards: Reading an Issue. What should a learner take away from it?

      +

      Alex: Start with Learning Cards: Reading an Issue. There is something to understand, something to try, and something that proves the try worked.

      +

      Alex: The practical takeaway is this. 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. 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.

      -

      Jamie: Let's pause on JAWS. What should a learner take away from it?

      -

      Alex: Start with JAWS. There is something to understand, something to try, and something that proves the try worked.

      -

      Alex: A few details make that real. 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.

      -

      Alex: Hold that next to this. Start with VoiceOver. There is something to understand, something to try, and something that proves the try worked.

      -

      Alex: The parts worth keeping in working memory are these. 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.

      -

      Jamie: Let's pause on The GitHub Mobile App - A Reference Note. What should a learner take away from it?

      -

      Alex: This is where The GitHub Mobile App - A Reference Note becomes real: GitHub has an iOS and Android app that supports push notifications. That matters in practice: While the app itself is not covered as a primary tool in this workshop, it is worth knowing.

      -

      Alex: The room should hear these as checkpoints. 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.

      +

      Jamie: Let's pause on Step-by-step. What should a learner take away from it?

      +

      Alex: The reason Step-by-step matters is that to close the issue while commenting: click the arrow on the Close issue button and choose Close with comment. That gives the learner a simple foothold: low vision users (zoom, high contrast).

      +

      Alex: First, scroll to the bottom of the issue page. Then, click in the Leave a comment text area. After that, type your comment (Markdown is supported - use the toolbar buttons above the text for bold, italic, code, etc.). Finally, optionally click Preview to see how it will render. The rhythm is simple: orient, act, verify, then continue.

      +

      Jamie: Before we leave Step-by-step, what is the practical point?

      +

      Alex: First, click the green Comment button to post. Then, scroll to the bottom to find the Leave a comment text area. At 200%+ zoom, this may require significant scrolling past the timeline. After that, the text area expands as you type. The formatting toolbar above it (bold, italic, code, etc.) wraps at high zoom but remains functional. Finally, the Preview tab next to Write lets you check Markdown rendering before posting. Think of it as a rail line: each stop confirms you are still on the right route before the next one.

      +

      Alex: Treat examples as spoken recipes, not decorations. You may hear something like 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.". Read the command, understand what it changes, then run it only when the repository state matches the lesson.

      +

      Jamie: Let's pause on Markdown formatting while typing. What should a learner take away from it?

      +

      Alex: Start with Markdown formatting while typing: These keyboard shortcuts work inside the text area (Focus Mode).

      +

      Alex: The next layer is this. Here is the plain-English version of GitHub shortcuts for the Issues pages. These are the GitHub built-in shortcuts for working with issues. Put another way, enable Focus Mode first (NVDA: NVDA+Space, JAWS: Insert+Z) before using single-key shortcuts. It is like learning a transit route. The names of the stops matter because they tell you whether you are still going the right direction.

      -

      Jamie: Let's pause on Try It: Tame Your Inbox. What should a learner take away from it?

      -

      Alex: Keep the learner anchored in Try It: Tame Your Inbox. Time: 2 minutes What you need: Browser, signed in to GitHub. This is the part to say slowly: Go to github.com/notifications and practice. A good GitHub workflow is like a well-run meeting: everyone knows the topic, the next action, and who has the floor.

      -

      Alex: First, scan your inbox - Press H and Tab to navigate through notifications. Each one shows the repo name, type (issue/PR), and title. Then, mark one as done - Find a notification you've already read. Press E to mark it as done. It disappears from the list. After that, 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. It is like walking a hallway with named doors: read the sign, enter the right room, then confirm where you landed.

      -

      Jamie: Let's pause on What You Accomplished Today. What should a learner take away from it?

      -

      Alex: The reason What You Accomplished Today matters is that day 1 is complete -- and you did a lot. That gives the learner a simple foothold: here is every skill you practiced, mapped to the chapter where you learned it and the evidence you created along the way.

      -

      Alex: Keep the teaching thread moving. Start with 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. The next useful detail is this: You navigated a complex platform, created real contributions, and collaborated with other people in a shared codebase.

      +

      Jamie: Let's pause on On the Issues list page. What should a learner take away from it?

      +

      Alex: This is where On the Issues list page becomes real: shortcut note: For G I, press G, release it, then press I (two sequential key presses, not simultaneous).

      +

      Jamie: Let's pause on On an open issue. What should a learner take away from it?

      +

      Alex: Keep the learner anchored in On an open issue. R to quote is a power move: Select any text in a comment while in Browse Mode (Shift+Arrow to select), then press R. This is the part to say slowly: GitHub puts the quoted text in the comment box as a Markdown blockquote.

      +

      Alex: First, navigate to your comment (3 to jump to comments). Then, find the "." (ellipsis) menu button near your comment. After that, press Enter on "Edit" from that menu. Finally, the comment turns into a text area - switch to Focus Mode. It is like walking a hallway with named doors: read the sign, enter the right room, then confirm where you landed.

      +

      Jamie: Before we leave On an open issue, what is the practical point?

      +

      Alex: First, make your changes. Then, tab to "Update comment" button → Enter. The rhythm is simple: orient, act, verify, then continue.

      +

      Jamie: Let's pause on Learning Cards: Leaving a Comment. What should a learner take away from it?

      +

      Alex: Start with Learning Cards: Leaving a Comment. There is something to understand, something to try, and something that proves the try worked.

      +

      Alex: The practical takeaway is this. 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. 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.

      -

      Jamie: Let's pause on Confidence Check. What should a learner take away from it?

      -

      Alex: Here is the plain-English version of Confidence Check. Before you close your laptop, take two minutes to answer these questions in your Chapter 10 challenge issue. Put another way, there are no wrong answers -- this is for you.

      -

      Alex: First, which chapter felt the most natural to you? Which one do you want to revisit? Then, can you explain what a pull request does to someone who has never used GitHub? After that, if you saw a merge conflict right now, would you know where to start? Finally, what is one thing you want to try on GitHub this week that you did not get to today? Treat it like a recipe: do not add the next ingredient until the previous one is actually in the bowl.

      -

      Alex: Keep the teaching thread moving. This is where Your Challenge Progress becomes real: look at how many challenge issues you completed today. That matters in practice: Each one represents a skill you did not just read about -- you practiced it, posted evidence, and moved on. The workshop is closer to rehearsal than lecture. You hear the move, try the move, and then check what changed.

      -

      Jamie: Let's pause on Learning Cards: What You Accomplished Today. What should a learner take away from it?

      -

      Alex: Start with Learning Cards: What You Accomplished Today. There is something to understand, something to try, and something that proves the try worked.

      -

      Alex: The practical takeaway is this. 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. 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.

      +

      Jamie: Let's pause on Navigating to New Issue. What should a learner take away from it?

      +

      Alex: Start with Navigating to New Issue: From the Issues list page, click the green New issue button in the top-right of the issue list. The next useful detail is this: 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. Think of it like entering a new building: first you find the lobby, then the room, then the door you actually need.

      +

      Alex: The practical takeaway is this. 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.

      +

      Alex: First, press K to navigate links and find the "New issue" button/link. Then, press Enter. After that, 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. Finally, quick Nav B or VO+U → Buttons to find the "New issue" button. Think of it as a rail line: each stop confirms you are still on the right route before the next one.

      +

      Jamie: Before we leave Navigating to New Issue, what is the practical point?

      +

      Alex: First, vO+Space to activate it. Then, 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. Treat it like a recipe: do not add the next ingredient until the previous one is actually in the bowl.

      +

      Jamie: Let's pause on Filling Out the Issue Form. What should a learner take away from it?

      +

      Alex: Here is the plain-English version of Filling Out the Issue Form. The issue form has these fields (order may vary depending on the template).

      +

      Jamie: Let's pause on Title field. What should a learner take away from it?

      +

      Alex: Start with Title field. There is something to understand, something to try, and something that proves the try worked.

      +

      Alex: First, find the Title input field (F or by landmark). Then, focus Mode → type a clear, specific title. After that, good title: "Screen reader announces wrong element count on Issues list with 50+ items". Finally, bad title: "Bug with screen reader". It is a checklist, but a meaningful one: every item creates evidence that the next step is safe.

      -

      Alex: Keep the teaching thread moving. The reason What Day 2 Adds matters is that see also: Chapter 11: VS Code Interface is where Day 2 begins -- have VS Code installed and ready. That gives the learner a simple foothold: on Day 1, you worked entirely on GitHub.com.

      -

      Jamie: Let's pause on Between Days. What should a learner take away from it?

      -

      Alex: Start with 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. The next useful detail is this: GitHub Skills courses use bot-driven feedback inside pull requests.

      -

      Alex: First, explore your notification settings. Now that you understand how notifications work, visit github.com/settings/notifications and customize your email and web preferences. There is no wrong configuration -- just find what feels manageable. Then, 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. After that, try a GitHub Skills course. GitHub Skills 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 for the full list of recommended courses. Think of it as a rail line: each stop confirms you are still on the right route before the next one.

      -

      Alex: Keep the teaching thread moving. Here is the plain-English version of You Already Know More Than You Think. Think about where you started this morning. Put another way, 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. It is like learning a transit route. The names of the stops matter because they tell you whether you are still going the right direction.

      +

      Jamie: Let's pause on Description / Body field. What should a learner take away from it?

      +

      Alex: Start with Description / Body field. There is something to understand, something to try, and something that proves the try worked.

      +

      Alex: First, tab to the body text area. Then, focus Mode → type using the Markdown template provided. After that, if no template, use this structure. It is like walking a hallway with named doors: read the sign, enter the right room, then confirm where you landed.

      +

      Alex: Treat examples as spoken recipes, not decorations. You may hear something like 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. Read the command, understand what it changes, then run it only when the repository state matches the lesson.

      +

      Jamie: Let's pause on Assigning labels from the sidebar. What should a learner take away from it?

      +

      Alex: The reason Assigning labels from the sidebar matters is that see also: Chapter 09: Labels, Milestones, and Projects covers the full label and milestone system. That gives the learner a simple foothold: while the form is open, the sidebar has dropdowns for Labels, Assignees, and Milestone. The interface gets friendlier when it stops being a wall of controls and starts being a set of named places.

      +

      Alex: First, tab away from the text area (or press Escape to leave Focus Mode). Then, navigate to the sidebar - press H to find "Labels" heading. After that, press Enter on the Labels gear/button. Finally, dropdown opens → ↑/↓ to navigate labels. The rhythm is simple: orient, act, verify, then continue.

      +

      Jamie: Before we leave Assigning labels from the sidebar, what is the practical point?

      +

      Alex: First, enter to select/deselect. Then, escape to close (selections save automatically). After that, vO+Shift+Up to stop interacting with the text area. Finally, vO+U → Headings to find the "Labels" heading in the sidebar. Think of it as a rail line: each stop confirms you are still on the right route before the next one.

      +

      Alex: A solid project habit is to treat metadata as decision support. Labels, status, assignees, and notifications tell you what kind of attention the work needs.

      +

      Jamie: Let's pause on Submitting the issue. What should a learner take away from it?

      +

      Alex: Start with Submitting the issue: GitHub CLI (gh) alternative - filing a new issue. The next useful detail is this: Create an issue from your terminal.

      +

      Alex: First, tab to "Submit new issue" button. Then, press Enter. Think of it as a rail line: each stop confirms you are still on the right route before the next one.

      +

      Alex: Treat examples as spoken recipes, not decorations. You may hear something like 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. Read the command, understand what it changes, then run it only when the repository state matches the lesson.

      -

      Jamie: What should people carry with them after this?

      -

      Alex: Carry the map. Know what page or tool you are in, know which action you are taking, and know what confirmation should follow. If the confirmation is missing, pause. That pause is not wasted time; it is professional judgment.

      -

      Jamie: That is a better way to say it than just follow the steps.

      -

      Alex: Right. Steps matter, but understanding wins. That is episode 10. Next in the series is episode 11, where we keep building the same contributor muscles.

      -
      - +

      Alex: Keep the teaching thread moving. Start with Learning Cards: Filing a New Issue. There is something to understand, something to try, and something that proves the try worked.

      +

      Alex: The practical takeaway is this. 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. 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.

      +

      Jamie: Let's pause on Tool Cards: File a New Issue. What should a learner take away from it?

      +

      Alex: This is where Tool Cards: File a New Issue becomes real: github.dev (web editor): Not available -- issues are managed through the repository's Issues tab, not the code editor. That matters in practice: VS Code Desktop (GitHub Pull Requests extension).

      +

      Alex: First, navigate to the repository's Issues tab (or press G then I). Then, click New issue, choose a template or blank issue. After that, fill in the title and description, then click Submit new issue. Finally, open the GitHub panel in the sidebar. It is a checklist, but a meaningful one: every item creates evidence that the next step is safe.

      +

      Jamie: Before we leave Tool Cards: File a New Issue, what is the practical point?

      +

      Alex: First, under Issues, click the + icon to create a new issue. Then, fill in the title and body, then click Create. It is like walking a hallway with named doors: read the sign, enter the right room, then confirm where you landed.

      +

      Alex: Treat examples as spoken recipes, not decorations. You may hear something like gh issue create --title "Your title" --body "Description here"; Or interactively:; gh issue create. Read the command, understand what it changes, then run it only when the repository state matches the lesson.

      +

      Alex: Keep the teaching thread moving. Keep the learner anchored in Cross-Referencing Issues. Linking issues and PRs to each other creates a trail of context that helps everyone understand the project's history. A good GitHub workflow is like a well-run meeting: everyone knows the topic, the next action, and who has the floor.

      -

      Day 2: VS Code and Accessibility Agents

      -

      Episode 11: VS Code Setup and Accessibility

      -

      Screen reader mode, Command Palette, sidebar navigation, and accessibility settings.

      -

      Based on: Chapter 11: VS Code Setup and Accessibility

      -

      Audio and transcript are being regenerated for this episode.

      -
      -Read Transcript - Episode 11: VS Code Setup and Accessibility - -

      Transcript

      -

      Alex: Welcome to episode 11 of Git Going with GitHub: VS Code Setup and Accessibility. I am Alex, and today we are teaching this topic as a conversation you can carry into the workshop, not as a page you have to memorize.

      -

      Jamie: And I am Jamie. I will keep pulling the lesson back to real learners, real repositories, and the evidence that proves the work happened.

      +

      Jamie: Let's pause on Closing keywords in PR descriptions or issue comments. What should a learner take away from it?

      +

      Alex: The reason Closing keywords in PR descriptions or issue comments matters is that when you type these phrases in a PR description or comment (followed by an issue number), GitHub creates a connection.

      +

      Alex: Keep the teaching thread moving. Start with Mentioning another issue in a comment: Simply type followed by a number anywhere in a comment body. The next useful detail is this: GitHub autocompletes with a dropdown of matching issues and PRs.

      +

      Jamie: Let's pause on Cross-repo references. What should a learner take away from it?

      +

      Alex: Here is the plain-English version of Cross-repo references. owner/repo 42 - references issue 42 in a different repository.

      -

      Alex: The lesson focus is Screen reader mode, Command Palette, sidebar navigation, and accessibility settings. We will treat every step as a teachable decision, because that is what makes the skill portable.

      -

      Jamie: So we should explain the why clearly enough that the steps make sense when the learner meets them later.

      -

      Alex: That is it. If a listener only has audio right now, they should still get the complete concept and know what evidence would prove success.

      +

      Alex: Keep the teaching thread moving. Start with Learning Cards: Cross-Referencing Issues. There is something to understand, something to try, and something that proves the try worked.

      +

      Alex: The practical takeaway is this. 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. 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.

      +

      Jamie: Let's pause on Sub-Issues - Parent and Child Relationships. What should a learner take away from it?

      +

      Alex: Keep the learner anchored in 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. This is the part to say slowly: A "parent" issue contains a list of child issues; each child is a full issue with its own discussion, labels, and assignees.

      +

      Jamie: What is the judgment call here?

      +

      Alex: Start with When to Use Sub-Issues. There is something to understand, something to try, and something that proves the try worked.

      +

      Alex: Use the comparison to make a decision, not to recite a table. The main contrasts are: Large feature broken down means Parent: "Redesign navigation"; Children: "Keyboard nav," "Screen reader nav," "Mobile nav". Epic tracking means Parent: "WCAG 2.1 AA compliance"; Children: one issue per failing criterion. Release milestone means Parent: "v2.0 release"; Children: every required PR/fix.

      -

      Jamie: Okay, set the room for us. What are we walking into?

      -

      Alex: Start with 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. The next useful detail is this: 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.

      -

      Alex: The next layer is this. Here is the plain-English version of Workshop Recommendation (Chapter 11). For this workshop, Chapter 11 is a guided setup chapter with a lightweight completion practice. It is like learning a transit route. The names of the stops matter because they tell you whether you are still going the right direction.

      -

      Alex: The practical anchors are these. There are 1 guided walkthrough. Automation check: none - setup state is local/account-level and cannot be validated by the Learning Room PR bot. The evidence is structured completion comment on your assigned challenge issue. The pattern is open, configure, navigate, verify.

      -

      Jamie: What does the learner do first, second, and then after that?

      -

      Alex: Start with Chapter 11 Practice Set. There is something to understand, something to try, and something that proves the try worked.

      -

      Alex: First, 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. It is a checklist, but a meaningful one: every item creates evidence that the next step is safe.

      -

      Alex: A solid pull request habit is to separate three questions: what changed, why it changed, and what still needs review. That keeps the conversation useful instead of noisy.

      +

      Jamie: Let's pause on Creating a Sub-Issue. What should a learner take away from it?

      +

      Alex: Start with Creating a Sub-Issue: The sub-issues section is announced as a region. The next useful detail is this: After linking, the child issue appears as a list item with a checkbox showing its open/closed state.

      +

      Alex: Keep the teaching thread moving. Here is the plain-English version of Reading Sub-Issues on a Parent Issue. Progress indicator: The parent issue shows a completion bar (e.g., "3 of 7 completed") based on how many child issues are closed. Put another way, screen readers announce this as a progress region. It is like learning a transit route. The names of the stops matter because they tell you whether you are still going the right direction.

      +

      Jamie: Let's pause on Viewing a Child Issue's Parent. What should a learner take away from it?

      +

      Alex: This is where Viewing a Child Issue's Parent becomes real: every child issue shows a "Parent issue" link near the top of the page (above the description). That matters in practice: Navigate with H or links (K) to find it.

      -

      Jamie: Turn that into a path someone can follow.

      -

      Alex: Keep the learner anchored in Practice 11.1 Step-by-Step: VS Code Accessibility Baseline. 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. This is the part to say slowly: github.dev (VS Code in the browser) or desktop VS Code if you installed it in Block 0.

      -

      Alex: For a learner, the useful signals are these. 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.

      -

      Alex: First, open your Learning Room repository on GitHub.com. Then, 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. After that, enable screen reader mode. Finally, open the Explorer panel with Ctrl+Shift+E (Mac: Cmd+Shift+E). Your screen reader should announce the file tree. It is like walking a hallway with named doors: read the sign, enter the right room, then confirm where you landed.

      -

      Jamie: What is the ordered workflow?

      -

      Alex: First, navigate to and open README.md from the file tree. Use arrow keys to move through files and Enter to open. Then, 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. After that, 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. Finally, 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. The rhythm is simple: orient, act, verify, then continue.

      -

      Jamie: What should they understand before typing anything?

      -

      Alex: The reason Completing Chapter 11: Submit Your Evidence matters is that return to GitHub.com, open the assigned setup or Day 2 readiness issue, and post a completion comment. That gives the learner a simple foothold: if any step was "no," add a note explaining where you got stuck so the facilitator can help.

      -

      Alex: Treat examples as spoken recipes, not decorations. You may hear something like 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. Read the command, understand what it changes, then run it only when the repository state matches the lesson.

      -

      Alex: The useful habit is simple: orient first, act second, verify third. That pause before acting is part of the work.

      -

      Alex: That matters because of the next idea. Start with Expected Outcomes. There is something to understand, something to try, and something that proves the try worked.

      -

      Alex: On the ground, that means a few things. 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).

      +

      Alex: Keep the teaching thread moving. Keep the learner anchored in Sub-Issues vs. Task Lists. If you are working on a feature that requires multiple PRs or involves several team members, ask the maintainer to create a parent issue. This is the part to say slowly: You can then claim individual child issues without one person owning the whole feature.

      +

      Jamie: Let's pause on Learning Cards: Sub-Issues. What should a learner take away from it?

      +

      Alex: Start with Learning Cards: Sub-Issues. There is something to understand, something to try, and something that proves the try worked.

      +

      Alex: The practical takeaway is this. 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. 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.

      +

      Jamie: Let's pause on Closing an issue. What should a learner take away from it?

      +

      Alex: Start with Closing an issue: Scroll to the bottom of the issue page. The next useful detail is this: Click the Close issue button next to the comment box. Think of it like entering a new building: first you find the lobby, then the room, then the door you actually need.

      +

      Alex: First, 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. Then, button approach: Tab to the "Close issue" button (at the bottom of the page, near the comment box) and press Enter. After that, optionally leave a closing comment first. Finally, 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. Think of it as a rail line: each stop confirms you are still on the right route before the next one.

      +

      Jamie: Before we leave Closing an issue, what is the practical point?

      +

      Alex: First, button approach: Quick Nav B or Tab to find the "Close issue" button, then VO+Space. Treat it like a recipe: do not add the next ingredient until the previous one is actually in the bowl.

      +

      Alex: Treat examples as spoken recipes, not decorations. You may hear something like 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. Read the command, understand what it changes, then run it only when the repository state matches the lesson.

      -

      Jamie: How would you walk the room through that step by step?

      -

      Alex: Start with If You Get Stuck. There is something to understand, something to try, and something that proves the try worked.

      -

      Alex: First, 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. Then, screen reader mode toggle did not announce anything? Open Command Palette (Ctrl+Shift+P) and type Screen Reader to find the toggle manually. After that, explorer panel is empty? VS Code may still be loading the repository. Wait 5-10 seconds and press Ctrl+Shift+E again. Finally, on Mac with VoiceOver, navigation feels wrong? Run Toggle Screen Reader Accessibility Mode from Command Palette. VoiceOver sometimes needs the explicit toggle. Treat it like a recipe: do not add the next ingredient until the previous one is actually in the bowl.

      -

      Jamie: Give me the sequence, because order matters here.

      -

      Alex: First, cannot find the Accounts button? Open Command Palette and type Accounts to manage sign-in from there. Then, Copilot not showing in the status bar? github.dev does not support Copilot - you need desktop VS Code or a Codespace. After that, 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. Finally, ask facilitator for a side-by-side demo and repeat the same steps. It is a checklist, but a meaningful one: every item creates evidence that the next step is safe.

      -

      Alex: This is where the talk moves from concept to action. This is where Learning Moment becomes real: tool setup is part of contribution skill. That matters in practice: A stable, accessible editor reduces stress and increases contribution quality.

      -

      Jamie: Let's pause on Learning Pattern Used in This Chapter. What should a learner take away from it?

      -

      Alex: Start with Learning Pattern Used in This Chapter. There is something to understand, something to try, and something that proves the try worked.

      -

      Alex: First, open the tool in the simplest way possible (. key for github.dev). Then, sign in and verify your identity and tools are ready (Accounts, Copilot). After that, configure accessibility before doing any work (screen reader mode first). Finally, verify each navigation surface works with your assistive technology. It is like walking a hallway with named doors: read the sign, enter the right room, then confirm where you landed.

      -

      Jamie: Before we leave Learning Pattern Used in This Chapter, what is the practical point?

      -

      Alex: First, record what worked and what didn't (evidence comment). The rhythm is simple: orient, act, verify, then continue.

      -
      -

      Alex: Before the learner moves on. The reason 1. Why VS Code for Open Source Contribution matters is that GitHub's browser interface is excellent for reviewing, discussing, and triaging. That gives the learner a simple foothold: for Markdown contributions (which is most of what 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. The interface gets friendlier when it stops being a wall of controls and starts being a set of named places.

      -

      Jamie: What should someone listen for when a lesson offers more than one tool path?

      -

      Alex: Start with Learning Cards: Why VS Code. There is something to understand, something to try, and something that proves the try worked.

      -

      Alex: A few details make that real. 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. 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.

      -

      Alex: Hold that next to this. Here is the plain-English version of Before you install anything: try VS Code right now in your browser. GitHub provides a web-based version of VS Code called github.dev. Put another way, it runs entirely in your browser with zero installation.

      +

      Jamie: Let's pause on Reopening a closed issue. What should a learner take away from it?

      +

      Alex: Here is the plain-English version of Reopening a closed issue. If an issue is Closed, the "Close issue" button becomes "Reopen issue" - navigate and activate to reopen.

      +

      Jamie: Let's pause on Assigning an issue. What should a learner take away from it?

      +

      Alex: This is where Assigning an issue becomes real: GitHub CLI (gh) alternative - assigning and labeling. That matters in practice: Manage assignments and labels from your terminal.

      +

      Alex: First, navigate to "Assignees" heading (3 or H). Then, activate the gear/plus button. After that, type a username in the search field. Finally, select from the dropdown. It is a checklist, but a meaningful one: every item creates evidence that the next step is safe.

      +

      Alex: Treat examples as spoken recipes, not decorations. You may hear something like 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". Read the command, understand what it changes, then run it only when the repository state matches the lesson.

      +

      Jamie: Let's pause on Changing labels. What should a learner take away from it?

      +

      Alex: Start with Changing labels. There is something to understand, something to try, and something that proves the try worked.

      +

      Alex: First, navigate to "Labels" heading. Then, activate the gear button. After that, select/deselect labels from the dropdown. Finally, press Escape to save. It is like walking a hallway with named doors: read the sign, enter the right room, then confirm where you landed.

      -

      Jamie: Let's pause on Method 1: The Period Key Shortcut (Fastest). What should a learner take away from it?

      -

      Alex: Start with Method 1: The Period Key Shortcut (Fastest). There is something to understand, something to try, and something that proves the try worked.

      -

      Alex: First, press. (period key - just the period, no modifier keys). Then, the page transforms into VS Code. After that, you are now editing in github.dev. Finally, the URL changes to github.dev/owner/repo. It is a checklist, but a meaningful one: every item creates evidence that the next step is safe.

      -

      Jamie: Before we leave Method 1: The Period Key Shortcut (Fastest), what is the practical point?

      -

      Alex: First, screen reader mode works exactly as it does in desktop VS Code (toggle with Shift+Alt+F1). It is like walking a hallway with named doors: read the sign, enter the right room, then confirm where you landed.

      -

      Alex: That connects to another useful point. Keep the learner anchored in Where it works. The period key shortcut is a single keypress - no modifier keys. This is the part to say slowly: It is GitHub's universal "open this in VS Code" command. A good GitHub workflow is like a well-run meeting: everyone knows the topic, the next action, and who has the floor.

      -

      Alex: The parts worth keeping in working memory are these. Repository home pages. File view pages. Pull request pages. Any branch or commit view.

      -

      Jamie: What is the one idea that makes the next few steps less mysterious?

      -

      Alex: The reason Method 2: Direct URL matters is that change the domain in any GitHub URL.

      -

      Alex: Here is what that changes in practice. github.com/owner/repo becomes github.dev/owner/repo. Works for any branch, file, or commit URL.

      +

      Alex: Keep the teaching thread moving. The reason Transferring or deleting an issue matters is that available from the "." (ellipsis) button at the top of the issue - navigate buttons with B to find it. The interface gets friendlier when it stops being a wall of controls and starts being a set of named places.

      +

      Jamie: Let's pause on Learning Cards: Managing Issues. What should a learner take away from it?

      +

      Alex: Start with Learning Cards: Managing Issues. There is something to understand, something to try, and something that proves the try worked.

      +

      Alex: The practical takeaway is this. 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. 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.

      +

      Jamie: Let's pause on The "good first issue" Label - Your Entry Point. What should a learner take away from it?

      +

      Alex: Here is the plain-English version of The "good first issue" Label - Your Entry Point. When looking for your first open source contribution. Put another way, remember: It's respectful to ask before starting.

      +

      Alex: First, navigate to any project's Issues tab. Then, filter by label: type is:open label:"good first issue" in the search. After that, read through issues until you find one in your area of interest. Finally, comment on the issue: "Hi, I'd like to work on this. Can I be assigned?". Treat it like a recipe: do not add the next ingredient until the previous one is actually in the bowl.

      +

      Jamie: Before we leave The "good first issue" Label - Your Entry Point, what is the practical point?

      +

      Alex: First, wait for a maintainer to respond and assign you before starting work. It is a checklist, but a meaningful one: every item creates evidence that the next step is safe.

      -

      Jamie: Let's pause on Method 3: From the Repository Page. What should a learner take away from it?

      -

      Alex: Start with Method 3: From the Repository Page: Screen reader users (NVDA / JAWS / VoiceOver).

      -

      Alex: First, click the green Code button on any repository page. Then, in the dropdown, click Open with github.dev. After that, navigate to the Code button (press B or Tab until you hear "Code, button" or similar). Finally, press Enter to open the dropdown menu. Think of it as a rail line: each stop confirms you are still on the right route before the next one.

      -

      Jamie: Before we leave Method 3: From the Repository Page, what is the practical point?

      -

      Alex: First, press Down Arrow to reach "Open with github.dev". Then, press Enter. Treat it like a recipe: do not add the next ingredient until the previous one is actually in the bowl.

      -

      Jamie: What would you say to someone who is already bracing for this to be too much?

      -

      Alex: Here is the plain-English version of What You Get in github.dev. Everything in the list below works exactly like desktop VS Code.

      -

      Alex: The room should hear these as checkpoints. Full text editor with syntax highlighting. All VS Code keyboard shortcuts (see Section 11: Keyboard Shortcuts Editor and Appendix M). 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.

      -

      Alex: Keep the thread going. This is where What github.dev Does NOT Have becomes real: these limitations are why desktop VS Code exists. That matters in practice: github.dev is for quick edits and reading code. The workshop is closer to rehearsal than lecture. You hear the move, try the move, and then check what changed.

      -

      Alex: These are the details that keep the idea from floating away. 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.

      +

      Jamie: Let's pause on Learning Cards: The "good first issue" Label. What should a learner take away from it?

      +

      Alex: Start with Learning Cards: The "good first issue" Label. There is something to understand, something to try, and something that proves the try worked.

      +

      Alex: The practical takeaway is this. 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. 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.

      +

      Jamie: Let's pause on Accessibility-Specific Issue Writing Tips. What should a learner take away from it?

      +

      Alex: Keep the learner anchored in Accessibility-Specific Issue Writing Tips. When filing accessibility bugs, these details help maintainers reproduce and fix the problem. A good GitHub workflow is like a well-run meeting: everyone knows the topic, the next action, and who has the floor.

      +

      Alex: First, screen reader and version - "NVDA 2025.3.3" not just "screen reader". Then, oS and version - "Windows 11 22H2". After that, browser and version - "Chrome 124.0.6367.82". Finally, GitHub interface - "Modern experience (default since Jan 2026)" or "Classic experience (opted out)". It is like walking a hallway with named doors: read the sign, enter the right room, then confirm where you landed.

      +

      Jamie: Before we leave Accessibility-Specific Issue Writing Tips, what is the practical point?

      +

      Alex: First, what was announced - quote the exact text your screen reader spoke. Then, what should have been announced - describe the expected behavior. After that, aRIA issue if known - e.g., "The button has no accessible name". Finally, steps to reproduce - numbered, step-by-step. The rhythm is simple: orient, act, verify, then continue.

      +

      Jamie: Let's pause on Example of a well-filed accessibility issue. What should a learner take away from it?

      +

      Alex: Start with Example of a well-filed accessibility issue. There is something to understand, something to try, and something that proves the try worked.

      -

      Jamie: Where does the workshop stop being a tour and start becoming contribution?

      -

      Alex: Keep the learner anchored in Why github.dev Matters for This Workshop. You spend Day 1 in the GitHub browser interface. This is the part to say slowly: You spend Day 2 in desktop VS Code.

      -

      Alex: That becomes easier when you listen for these cues. 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.

      -

      Alex: Another way to ground it. Start with Use github.dev when. There is something to understand, something to try, and something that proves the try worked.

      -

      Alex: That shows up in the workshop in a few specific ways. 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.

      -

      Jamie: What stays the same when the tool changes?

      -

      Alex: Start with Use desktop VS Code when. There is something to understand, something to try, and something that proves the try worked.

      -

      Alex: The practical takeaway is this. 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.

      +

      Alex: Keep the teaching thread moving. Start with Learning Cards: Accessibility-Specific Issue Writing. There is something to understand, something to try, and something that proves the try worked.

      +

      Alex: The practical takeaway is this. 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. 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.

      +

      Jamie: Let's pause on Writing Effective Issues. What should a learner take away from it?

      +

      Alex: Here is the plain-English version of Writing Effective Issues. See also: Appendix N: Advanced Search covers search qualifiers to find existing issues before filing a new one. Put another way, 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.

      +

      Alex: Keep the teaching thread moving. This is where Bug Report Structure becomes real: a strong bug report answers five questions. That matters in practice: Use this template every time you report something broken. The workshop is closer to rehearsal than lecture. You hear the move, try the move, and then check what changed.

      -

      Jamie: Let's pause on Activate screen reader mode immediately. What should a learner take away from it?

      -

      Alex: Start with Activate screen reader mode immediately. There is something to understand, something to try, and something that proves the try worked.

      -

      Alex: First, press the period key on any GitHub repository to open github.dev. Then, press Shift+Alt+F1 (Mac: Shift+Option+F1) to enable screen reader mode. After that, VS Code announces "Screen reader optimized". Treat it like a recipe: do not add the next ingredient until the previous one is actually in the bowl.

      -

      Alex: A solid navigation habit is to prove where you are before activating controls. Headings, landmarks, and the address bar are not trivia; they are your map.

      -

      Jamie: Give me the version that sounds like an instructor, not a manual.

      -

      Alex: Start with What changes. There is something to understand, something to try, and something that proves the try worked.

      -

      Alex: The practical takeaway is this. 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.

      -

      Alex: Now bring the learner back to the room. Start with Navigation. There is something to understand, something to try, and something that proves the try worked.

      -

      Alex: The practical takeaway is this. 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.

      +

      Jamie: Let's pause on Feature Request Structure. What should a learner take away from it?

      +

      Alex: Keep the learner anchored in Feature Request Structure. Feature requests work best when they focus on the problem before jumping to the solution. This is the part to say slowly: 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.

      +

      Alex: First, problem statement -- Describe the pain point. What are you trying to do, and why is it hard or impossible right now? Then, proposed solution -- Your best idea for fixing the problem. Be specific enough to discuss, but hold it loosely. After that, alternatives considered -- Other approaches you thought about and why they fell short. This shows you have done your homework. Finally, who benefits -- Name the audience. "Screen reader users navigating large repositories" is more compelling than "everyone.". It is like walking a hallway with named doors: read the sign, enter the right room, then confirm where you landed.

      +

      Alex: Keep the teaching thread moving. The reason General Issue Writing Principles matters is that these rules apply to every issue -- bugs, features, questions, and everything in between. That gives the learner a simple foothold: if you discovered two bugs during the same session, file two separate issues.

      +

      Jamie: What does someone need before they touch the keyboard?

      +

      Alex: Start with Before and After: A Vague Issue vs. a Clear Issue: I tried clicking and nothing happened. The next useful detail is this: The maintainer has to ask: What doesn't work?

      -

      Jamie: If I am listening before the workshop starts, what should settle in my mind first?

      -

      Alex: Start with NVDA/JAWS users. There is something to understand, something to try, and something that proves the try worked.

      -

      Alex: The practical takeaway is this. 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.

      -

      Alex: Here is the practical turn. Start with VoiceOver users. There is something to understand, something to try, and something that proves the try worked.

      -

      Alex: The practical takeaway is this. 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.).

      -

      Jamie: Where do you want a learner to place their attention here?

      -

      Alex: Start with Learning Cards: github.dev. There is something to understand, something to try, and something that proves the try worked.

      -

      Alex: The practical takeaway is this. 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. 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.

      +

      Alex: Keep the teaching thread moving. Start with Learning Cards: Writing Effective Issues. There is something to understand, something to try, and something that proves the try worked.

      +

      Alex: The practical takeaway is this. 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. 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.

      +

      Jamie: Let's pause on Try It: File Your First Issue. What should a learner take away from it?

      +

      Alex: This is where Try It: File Your First Issue becomes real: time: 3 minutes What you need: Browser, signed in to GitHub. That matters in practice: Go to the Learning Room repository and file a real issue.

      +

      Alex: First, navigate to the Issues tab (press G then I in Focus Mode). Then, find and activate the "New issue" button (K to links, or Tab to it). After that, in the title field, type: "Introduce myself - [Your Name]". Finally, in the description, write 2-3 sentences: who you are, what screen reader you use, and one thing you're hoping to learn today. It is a checklist, but a meaningful one: every item creates evidence that the next step is safe.

      +

      Jamie: Before we leave Try It: File Your First Issue, what is the practical point?

      +

      Alex: First, press Ctrl+Enter to submit (or Tab to the Submit button and press Enter). It is like walking a hallway with named doors: read the sign, enter the right room, then confirm where you landed.

      +

      Alex: Keep the teaching thread moving. Keep the learner anchored in Learning Cards: Filing Your First Issue. Day 2 Amplifier - Accessibility Agents: @issue-tracker File, read, comment on, and triage real issues manually before using any agent. This is the part to say slowly: 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.

      +

      Alex: The practical takeaway is this. 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. 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.

      -

      Jamie: Let's pause on Try It Right Now. What should a learner take away from it?

      -

      Alex: This is where Try It Right Now becomes real: before reading the rest of this guide. That matters in practice: The desktop version in the rest of this guide is the same experience - with Copilot, agents, and a terminal added.

      -

      Alex: First, open your Learning Room repository in your browser. Then, press. (period key). After that, github.dev opens. Finally, press Shift+Alt+F1 (Mac: Shift+Option+F1) to enable screen reader mode. It is a checklist, but a meaningful one: every item creates evidence that the next step is safe.

      -

      Jamie: Before we leave Try It Right Now, what is the practical point?

      -

      Alex: First, press Ctrl+Shift+E (Mac: Cmd+Shift+E) to open the Explorer. Then, navigate to README.md and press Enter. After that, press Ctrl+Home (Mac: Cmd+Up) to go to the top of the file. Finally, press Ctrl+Shift+O (Mac: Cmd+Shift+O) to see the outline (all headings). It is like walking a hallway with named doors: read the sign, enter the right room, then confirm where you landed.

      -

      Jamie: How do we make tool choice feel like access, not pressure?

      -

      Alex: Keep the learner anchored in 3. Screen Reader Mode in VS Code. See also: Chapter 12: VS Code Accessibility goes deeper into accessibility features, Accessible View, and signal customization. This is the part to say slowly: If you use NVDA, JAWS, VoiceOver, or another screen reader, read this section before continuing.

      -

      Alex: This is the part worth saying out loud. The reason Verify it is active matters is that open Settings (Ctrl+, - Mac: Cmd+,) then search for accessibility support then confirm it shows on (not auto). The interface gets friendlier when it stops being a wall of controls and starts being a set of named places.

      +

      Jamie: Let's pause on How to Be an Effective and Respectful Open Source Contributor. What should a learner take away from it?

      +

      Alex: The reason How to Be an Effective and Respectful Open Source Contributor matters is that technical skills get your code into a project. That gives the learner a simple foothold: communication skills keep you welcomed in the community.

      +

      Alex: Keep the teaching thread moving. Start with Workshop Recommendation (Chapter 8): Chapter 8 is a communication and culture chapter. Think of it like entering a new building: first you find the lobby, then the room, then the door you actually need.

      +

      Alex: The practical takeaway is this. There are 1 guided reflection (no bot grading). Automation check: none - communication quality is too subjective for fair automated scoring. The evidence is structured reflection comment on your assigned challenge issue. The pattern is read, reflect, commit to one behavior.

      +

      Jamie: Let's pause on Chapter 8 Challenge Set. What should a learner take away from it?

      +

      Alex: Start with Chapter 8 Challenge Set. There is something to understand, something to try, and something that proves the try worked.

      +

      Alex: First, guided reflection - read the chapter, then post a short reflection comment committing to three specific collaboration behaviors. Treat it like a recipe: do not add the next ingredient until the previous one is actually in the bowl.

      -

      Jamie: Let's pause on NVDA-Specific Settings for VS Code. What should a learner take away from it?

      -

      Alex: Start with NVDA-Specific Settings for VS Code. There is something to understand, something to try, and something that proves the try worked.

      -

      Alex: First, open NVDA Menu then Preferences then Settings then Browse Mode. Then, set "Maximum length of text on a single line" to 10000 (prevents truncation in long lines). After that, under Object Presentation: set "Report tooltip delay" to off. Finally, recommended: use NVDA + Google Chrome for the integrated browser panels. Think of it as a rail line: each stop confirms you are still on the right route before the next one.

      -

      Jamie: Let's pause on JAWS-Specific Settings for VS Code. What should a learner take away from it?

      -

      Alex: Start with JAWS-Specific Settings for VS Code. There is something to understand, something to try, and something that proves the try worked.

      -

      Alex: First, JAWS should detect VS Code automatically and switch to PC Cursor mode for the editor. Then, if the editor feels unresponsive, press Insert+Z to toggle virtual cursor off. After that, for the integrated terminal: use Insert+Z to enter forms/PC mode, then interact with the terminal. Treat it like a recipe: do not add the next ingredient until the previous one is actually in the bowl.

      -

      Jamie: Let's pause on VoiceOver-Specific Settings for VS Code (macOS). What should a learner take away from it?

      -

      Alex: Start with VoiceOver-Specific Settings for VS Code (macOS). There is something to understand, something to try, and something that proves the try worked.

      -

      Alex: First, open VS Code then Shift+Alt+F1 (Mac: Shift+Option+F1) to confirm screen reader mode. Then, in VoiceOver Utility: Verbosity then set "Punctuation" to "All" for reading code. After that, use Quick Nav OFF (Left+Right Arrow) when inside the editor - standard cursor navigation is more predictable. Finally, use VO+Shift+Down to interact with the editor, VO+Shift+Up to stop interacting. It is a checklist, but a meaningful one: every item creates evidence that the next step is safe.

      +

      Jamie: Let's pause on Challenge 8.1 Step-by-Step: Guided Reflection. What should a learner take away from it?

      +

      Alex: This is where Challenge 8.1 Step-by-Step: Guided Reflection becomes real: identify three concrete communication behaviors you will practice during the rest of the workshop. That matters in practice: your assigned Chapter 8 challenge issue in your Learning Room repository on GitHub.com.

      +

      Alex: The practical takeaway is this. 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.".

      +

      Alex: First, read through the chapter content below, paying attention to the sections on GitHub Flow, constructive feedback, and asking for help. Then, as you read, think about one situation from Day 1 where communication helped (or could have helped) you. After that, open your assigned Chapter 8 challenge issue (the one titled "Chapter 8.1: Guided Reflection (@yourname)"). Finally, scroll to the comment box at the bottom of the issue. It is a checklist, but a meaningful one: every item creates evidence that the next step is safe.

      +

      Jamie: Before we leave Challenge 8.1 Step-by-Step: Guided Reflection, what is the practical point?

      +

      Alex: First, post a reflection comment using this format. Then, for each prompt, write one specific, actionable sentence - not a vague goal. After that, activate the Comment button (or press Ctrl+Enter). It is like walking a hallway with named doors: read the sign, enter the right room, then confirm where you landed.

      +

      Jamie: How do these exercises create confidence instead of pressure?

      +

      Alex: Keep the learner anchored in Completing Chapter 8: Submit Your Evidence. The reflection comment itself is your evidence. This is the part to say slowly: The facilitator reviews your comment for specificity.

      +

      Alex: Keep the teaching thread moving. Start with Expected Outcomes. There is something to understand, something to try, and something that proves the try worked.

      +

      Alex: The practical takeaway is this. 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.

      -

      Alex: Keep the teaching thread moving. Start with Learning Cards: Screen Reader Mode. There is something to understand, something to try, and something that proves the try worked.

      -

      Alex: The practical takeaway is this. 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. 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.

      -

      Jamie: There are a lot of tools in play. How do we keep that from feeling like a contest?

      -

      Alex: The reason 4. The VS Code Interface Tour matters is that before diving into individual features, here is how VS Code is organized. That gives the learner a simple foothold: every area is reachable by keyboard.

      -

      Alex: Keep the teaching thread moving. Start with The Five Major Regions: Text description of the layout above: VS Code has five major regions arranged in a grid. The next useful detail is this: The Menu Bar spans the full width across the top.

      +

      Jamie: What is the teaching move inside If You Get Stuck?

      +

      Alex: First, use one simple sentence per prompt - do not overthink it. Then, focus on one real behavior you can start doing today, not an abstract principle. After that, if writing feels hard, draft bullet points first in a text editor, then paste into the comment. Finally, look at the "Giving Feedback" and "Asking for Help" sections in this chapter for concrete examples. Think of it as a rail line: each stop confirms you are still on the right route before the next one.

      +

      Jamie: If someone only remembers one thing from If You Get Stuck, what should it be?

      +

      Alex: First, ask facilitator for one example response and adapt it to your own words. Then, finished but not sure you did it right? Compare your work against the Challenge 8 reference solution. Treat it like a recipe: do not add the next ingredient until the previous one is actually in the bowl.

      +

      Alex: Keep the teaching thread moving. Here is the plain-English version of Learning Moment. Technical quality and communication quality work together. Put another way, respectful, clear communication helps good code get merged faster.

      +

      Jamie: What is the teaching move inside Learning Pattern Used in This Chapter?

      +

      Alex: First, read and absorb community norms (not just rules, but reasons). Then, reflect on personal experience (what worked, what was hard). After that, commit to specific behaviors in writing (public accountability). Finally, apply those behaviors in upcoming chapters (reviews, comments, PRs). It is a checklist, but a meaningful one: every item creates evidence that the next step is safe.

      -

      Jamie: Let's pause on Navigating Between Regions. What should a learner take away from it?

      -

      Alex: Here is the plain-English version of Navigating Between Regions. Key insight: Press F6 repeatedly to cycle focus through the major regions: Sidebar, Editor, Panel, Status Bar, and back. Put another way, this is the universal "where am I, take me somewhere else" key in VS Code.

      -

      Alex: Keep the teaching thread moving. This is where Learning Cards: Finding Your Way Around VS Code becomes real: screen reader users (NVDA / JAWS / VoiceOver). The workshop is closer to rehearsal than lecture. You hear the move, try the move, and then check what changed.

      -

      Alex: The practical takeaway is this. 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. Ctrl+= / Ctrl+- to zoom the entire VS Code window (all UI elements scale).

      -

      Jamie: Let's pause on 5. The Accounts Button and GitHub Sign-In. What should a learner take away from it?

      -

      Alex: Keep the learner anchored in 5. The Accounts Button and GitHub Sign-In. See also: Chapter 14: Git in Practice covers the full Git workflow in VS Code including the Source Control panel. This is the part to say slowly: The Accounts button sits at the bottom of the Activity Bar (the vertical icon strip on the left side of VS Code).

      +

      Alex: Keep the teaching thread moving. Keep the learner anchored in 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. This is the part to say slowly: GitHub Flow is the lightweight branching model recommended for open source contribution. A good GitHub workflow is like a well-run meeting: everyone knows the topic, the next action, and who has the floor.

      +

      Jamie: Let's pause on Why This Model Works. What should a learner take away from it?

      +

      Alex: Start with Why This Model Works. There is something to understand, something to try, and something that proves the try worked.

      +

      Alex: The practical takeaway is this. 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.

      +

      Alex: Keep the teaching thread moving. Start with GitHub Flow vs Git Flow: You may encounter "Git Flow" (sometimes written "GitFlow") in older projects or enterprise environments. The next useful detail is this: This section explains what Git Flow is, how it differs from GitHub Flow, and why this workshop teaches GitHub Flow.

      -

      Alex: Keep the teaching thread moving. Start with Why Sign In Matters. There is something to understand, something to try, and something that proves the try worked.

      -

      Alex: The practical takeaway is this. 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.

      -

      Jamie: Let's pause on From the Accounts Button. What should a learner take away from it?

      -

      Alex: Start with From the Accounts Button. There is something to understand, something to try, and something that proves the try worked.

      -

      Alex: First, press F6 until you hear the Activity Bar, then arrow down to the Accounts button (it is at the very bottom of the bar). Then, press Enter to open the Accounts menu. After that, select "Sign in with GitHub to use GitHub Copilot" (or a similar prompt). Finally, a browser window opens for GitHub OAuth authorization. Think of it as a rail line: each stop confirms you are still on the right route before the next one.

      -

      Jamie: Before we leave From the Accounts Button, what is the practical point?

      -

      Alex: First, authorize VS Code, then return to the editor. Then, your screen reader announces your GitHub username in the Accounts button. Treat it like a recipe: do not add the next ingredient until the previous one is actually in the bowl.

      -

      Jamie: Let's pause on From the Command Palette. What should a learner take away from it?

      -

      Alex: Start with From the Command Palette. There is something to understand, something to try, and something that proves the try worked.

      -

      Alex: First, press Ctrl+Shift+P then type sign in. Then, select "GitHub: Sign In". After that, complete the browser OAuth flow and return to VS Code. Treat it like a recipe: do not add the next ingredient until the previous one is actually in the bowl.

      +

      Jamie: Let's pause on What Git Flow Is. What should a learner take away from it?

      +

      Alex: Here is the plain-English version of What Git Flow Is. Git Flow is a branching model published by Vincent Driessen in 2010. Put another way, it was designed for teams that ship versioned releases on a schedule (desktop software, mobile apps, embedded systems).

      +

      Jamie: Let's pause on How the Git Flow Cycle Works. What should a learner take away from it?

      +

      Alex: Start with How the Git Flow Cycle Works. There is something to understand, something to try, and something that proves the try worked.

      +

      Alex: First, developers branch feature/my-feature off develop and work there. Then, completed features merge back into develop via pull request. After that, when develop has enough features for a release, a release/1.2.0 branch is created. Finally, the release branch gets final testing, bug fixes, and version number updates. It is a checklist, but a meaningful one: every item creates evidence that the next step is safe.

      +

      Jamie: Before we leave How the Git Flow Cycle Works, what is the practical point?

      +

      Alex: First, the release branch merges into main (tagged with the version) and back into develop. Then, if a critical bug is found in production, a hotfix/ branch is created from main, fixed, and merged into both main and develop. It is like walking a hallway with named doors: read the sign, enter the right room, then confirm where you landed.

      +

      Jamie: Let's pause on How GitHub Flow Differs. What should a learner take away from it?

      +

      Alex: Keep the learner anchored in How GitHub Flow Differs. The following table compares GitHub Flow and Git Flow across key dimensions.

      -

      Jamie: Let's pause on Verifying You Are Signed In. What should a learner take away from it?

      -

      Alex: Start with Verifying You Are Signed In. There is something to understand, something to try, and something that proves the try worked.

      -

      Alex: The practical takeaway is this. 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.

      -

      Alex: Keep the teaching thread moving. Start with Learning Cards: GitHub Sign-In. There is something to understand, something to try, and something that proves the try worked.

      -

      Alex: The practical takeaway is this. 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. 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.

      -

      Jamie: Let's pause on 6. Verifying GitHub Copilot Status. What should a learner take away from it?

      -

      Alex: The reason 6. Verifying GitHub Copilot Status matters is that GitHub Copilot is your AI pair programmer. That gives the learner a simple foothold: before starting any contribution work, confirm it is active and responding.

      +

      Alex: Keep the teaching thread moving. Start with When You Might See Git Flow. There is something to understand, something to try, and something that proves the try worked.

      +

      Alex: The practical takeaway is this. 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.

      +

      Jamie: Zoom out for a second. What kind of journey is this?

      +

      Alex: Start with 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. The next useful detail is this: It is what GitHub itself uses and what most modern open source projects follow.

      +

      Alex: Keep the teaching thread moving. Here is the plain-English version of The Unwritten Rule: One Thing Per Branch. A branch and its PR should do one thing. Put another way, if you are fixing a broken link and you notice a typo nearby, fix the typo in a separate branch and PR. It is like learning a transit route. The names of the stops matter because they tell you whether you are still going the right direction.

      -

      Alex: Keep the teaching thread moving. Start with Status Bar Indicator: The Copilot icon appears in the Status Bar at the bottom-right of the VS Code window. Think of it like entering a new building: first you find the lobby, then the room, then the door you actually need.

      -

      Jamie: Let's pause on Command Palette Check. What should a learner take away from it?

      -

      Alex: Start with Command Palette Check. There is something to understand, something to try, and something that proves the try worked.

      -

      Alex: First, press Ctrl+Shift+P. Then, type GitHub Copilot: Status. After that, the output shows whether Copilot is signed in, active, or has errors. Treat it like a recipe: do not add the next ingredient until the previous one is actually in the bowl.

      -

      Jamie: Let's pause on Quick Test. What should a learner take away from it?

      -

      Alex: Start with Quick Test. There is something to understand, something to try, and something that proves the try worked.

      -

      Alex: First, open any.md file in the editor. Then, start typing a sentence (for example, Getting Started with). After that, if Copilot is active, a gray ghost-text suggestion appears after a brief pause. Finally, press Tab to accept or Escape to dismiss. It is a checklist, but a meaningful one: every item creates evidence that the next step is safe.

      +

      Jamie: Let's pause on Learning Cards: GitHub Flow. What should a learner take away from it?

      +

      Alex: Start with Learning Cards: GitHub Flow. There is something to understand, something to try, and something that proves the try worked.

      +

      Alex: The practical takeaway is this. 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). 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.

      +

      Alex: Keep the teaching thread moving. Keep the learner anchored in Keeping Your Fork Up to Date. When you fork a repository, you get a snapshot of the project at that moment. This is the part to say slowly: The original repository (called "upstream") continues to evolve.

      +

      Jamie: Let's pause on Why Sync Your Fork? What should a learner take away from it?

      +

      Alex: Start with Why Sync Your Fork? There is something to understand, something to try, and something that proves the try worked.

      +

      Alex: The practical takeaway is this. 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.

      -

      Jamie: Let's pause on Learning Cards: Copilot Status. What should a learner take away from it?

      -

      Alex: Start with Learning Cards: Copilot Status. There is something to understand, something to try, and something that proves the try worked.

      -

      Alex: The practical takeaway is this. 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. 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.

      -

      Alex: Keep the teaching thread moving. The reason 7. The Status Bar matters is that the Status Bar is the thin strip at the bottom of the VS Code window. That gives the learner a simple foothold: it provides real-time information about your workspace, file, and active tools. The interface gets friendlier when it stops being a wall of controls and starts being a set of named places.

      -

      Jamie: Let's pause on Navigating the Status Bar with a Keyboard. What should a learner take away from it?

      -

      Alex: Start with Navigating the Status Bar with a Keyboard. There is something to understand, something to try, and something that proves the try worked.

      -

      Alex: First, press F6 until your screen reader announces the Status Bar. Then, use Tab to move between items from left to right. After that, press Enter on any item to activate it (open a picker, toggle a setting, etc.). Finally, press Escape to return to the editor. Think of it as a rail line: each stop confirms you are still on the right route before the next one.

      +

      Jamie: Let's pause on Method 1: GitHub Web Interface (Easiest). What should a learner take away from it?

      +

      Alex: Start with Method 1: GitHub Web Interface (Easiest): GitHub merges the upstream changes into your fork automatically. The next useful detail is this: Screen reader users (NVDA / JAWS / VoiceOver). Think of it like entering a new building: first you find the lobby, then the room, then the door you actually need.

      +

      Alex: First, navigate to your fork's main page: github.com/your-username/repo-name. Then, look for the sync indicator: "This branch is X commits behind upstream/main". After that, click the "Sync fork" button. Finally, click "Update branch". Think of it as a rail line: each stop confirms you are still on the right route before the next one.

      +

      Jamie: Before we leave Method 1: GitHub Web Interface (Easiest), what is the practical point?

      +

      Alex: First, the sync button appears in the landmark that contains the branch selector. Then, press D to cycle through landmarks until you reach that region. After that, press B to cycle buttons until you hear "Sync fork" → press Enter. Finally, a dialog or page update presents "Update branch" - activate it. Treat it like a recipe: do not add the next ingredient until the previous one is actually in the bowl.

      +

      Jamie: What should someone listen for when a lesson offers more than one tool path?

      +

      Alex: Here is the plain-English version of Method 2: Git Command Line (VS Code Terminal). If you're working locally in VS Code.

      +

      Jamie: What should happen before anyone copies and runs it?

      +

      Alex: Start with One-time setup - add the upstream remote. There is something to understand, something to try, and something that proves the try worked.

      +

      Alex: Treat examples as spoken recipes, not decorations. You may hear something like git remote add upstream https://github.com/original-owner/repo-name.git; git remote -v Verify it was added. Read the command, understand what it changes, then run it only when the repository state matches the lesson.

      -

      Alex: Keep the teaching thread moving. Start with Learning Cards: Status Bar. There is something to understand, something to try, and something that proves the try worked.

      -

      Alex: The practical takeaway is this. 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. 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).

      -

      Jamie: Let's pause on 8. The Menu Bar. What should a learner take away from it?

      -

      Alex: This is where 8. The Menu Bar becomes real: the Menu Bar runs along the top of the VS Code window and provides structured access to every command category.

      -

      Alex: Keep the teaching thread moving. Start with Learning Cards: Menu Bar. There is something to understand, something to try, and something that proves the try worked.

      -

      Alex: The practical takeaway is this. 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. The Menu Bar respects your zoom level - increase window zoom for larger text.

      +

      Jamie: What should they understand before typing anything?

      +

      Alex: Start with Sync process. There is something to understand, something to try, and something that proves the try worked.

      +

      Alex: Treat examples as spoken recipes, not decorations. You may hear something like 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. Read the command, understand what it changes, then run it only when the repository state matches the lesson.

      +

      Alex: Keep the teaching thread moving. Start with When to sync. There is something to understand, something to try, and something that proves the try worked.

      +

      Alex: The practical takeaway is this. 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).

      +

      Jamie: Let's pause on Method 3: GitHub Desktop. What should a learner take away from it?

      +

      Alex: Start with Method 3: GitHub Desktop. There is something to understand, something to try, and something that proves the try worked.

      +

      Alex: First, open GitHub Desktop. Then, select Repository → Pull to get your fork's latest. After that, select Branch → Merge into Current Branch. Finally, choose upstream/main. Think of it as a rail line: each stop confirms you are still on the right route before the next one.

      +

      Jamie: Before we leave Method 3: GitHub Desktop, what is the practical point?

      +

      Alex: First, push the changes to your fork on GitHub. Treat it like a recipe: do not add the next ingredient until the previous one is actually in the bowl.

      -

      Jamie: Let's pause on 9. Settings Sync. What should a learner take away from it?

      -

      Alex: The reason 9. Settings Sync matters is that settings Sync synchronizes your VS Code configuration across multiple machines and between desktop VS Code and github.dev. That gives the learner a simple foothold: when you sign in and enable sync, your settings, keyboard shortcuts, extensions, UI state, and profiles travel with you.

      -

      Jamie: Let's pause on Enabling Settings Sync. What should a learner take away from it?

      -

      Alex: Start with Enabling Settings Sync. There is something to understand, something to try, and something that proves the try worked.

      -

      Alex: First, open the Accounts button (Activity Bar, bottom-left) or press Ctrl+Shift+P then type Settings Sync: Turn On. Then, sign in with your GitHub account (or Microsoft account). After that, select which categories to sync (recommended: sync everything). Finally, VS Code syncs immediately and on every subsequent change. Think of it as a rail line: each stop confirms you are still on the right route before the next one.

      -

      Jamie: Let's pause on Conflict Resolution. What should a learner take away from it?

      -

      Alex: Here is the plain-English version of Conflict Resolution. If settings differ between machines, VS Code shows a merge editor where you choose which version to keep. Put another way, this is similar to a Git merge conflict but for settings.

      +

      Alex: Keep the teaching thread moving. Start with Learning Cards: Keeping Your Fork Up to Date. There is something to understand, something to try, and something that proves the try worked.

      +

      Alex: The practical takeaway is this. 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. 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.

      +

      Jamie: Let's pause on Writing Good Commit Messages. What should a learner take away from it?

      +

      Alex: This is where Writing Good Commit Messages becomes real: every commit you make includes a message describing what changed. That matters in practice: Good commit messages make project history understandable months or years later.

      +

      Alex: Keep the teaching thread moving. Keep the learner anchored in The First Line (Required). This is the commit summary that appears in logs and GitHub's commit list. This is the part to say slowly: Think of it as an email subject line. A good GitHub workflow is like a well-run meeting: everyone knows the topic, the next action, and who has the floor.

      +

      Alex: The practical takeaway is this. fix: - bug fix. feat: - new feature. docs: - documentation only. style: - formatting, no code change.

      -

      Alex: Keep the teaching thread moving. Start with Learning Cards: Settings Sync. There is something to understand, something to try, and something that proves the try worked.

      -

      Alex: The practical takeaway is this. 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). 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).

      -

      Jamie: Let's pause on Profiles. What should a learner take away from it?

      -

      Alex: Keep the learner anchored in Profiles. VS Code Profiles let you create named collections of settings, extensions, keyboard shortcuts, snippets, tasks, and UI state. This is the part to say slowly: Each profile is independent - switching profiles changes your entire VS Code configuration instantly.

      -

      Alex: Keep the teaching thread moving. The reason Creating a Profile matters is that when creating a profile, you choose what to. That gives the learner a simple foothold: you can start from the current configuration, an empty profile, or an existing profile template.

      -

      Alex: The practical takeaway is this. Settings - editor preferences, accessibility options, theme. Keyboard Shortcuts - all custom keybindings. Extensions - which extensions are installed and enabled. Snippets - code snippet definitions.

      +

      Jamie: What is the safe way to learn from that example?

      +

      Alex: The reason The Body (Optional) matters is that if the summary isn't enough, add a body explaining. That gives the learner a simple foothold: leave a blank line between the summary and the body.

      +

      Alex: The practical takeaway is this. Why you made the change (more important than what). What trade-offs you considered. How the change affects behavior.

      +

      Alex: Treat examples as spoken recipes, not decorations. You may hear something like 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. Read the command, understand what it changes, then run it only when the repository state matches the lesson.

      +

      Alex: Keep the teaching thread moving. Start with The Footer (Optional): When the commit is merged, GitHub automatically closes linked issues.

      +

      Jamie: Let's pause on Atomic Commits. What should a learner take away from it?

      +

      Alex: Here is the plain-English version of Atomic Commits. Each commit should represent one logical change. Put another way, don't bundle unrelated fixes into a single commit.

      -

      Jamie: Let's pause on Switching Profiles. What should a learner take away from it?

      -

      Alex: Start with Switching Profiles: The active profile name appears in the VS Code title bar and Status Bar so you always know which configuration is active.

      -

      Alex: Keep the teaching thread moving. Here is the plain-English version of Workshop Profile Recommendations. Create these profiles before the workshop. It is like learning a transit route. The names of the stops matter because they tell you whether you are still going the right direction.

      -

      Jamie: Let's pause on Exporting and Sharing Profiles. What should a learner take away from it?

      -

      Alex: This is where Exporting and Sharing Profiles becomes real: profiles can be exported and shared. That matters in practice: To import: Ctrl+Shift+P then Profiles: Import Profile and paste the gist URL or select the file.

      -

      Alex: First, ctrl+Shift+P then type Profiles: Export Profile. Then, choose what to include (settings, extensions, etc.). After that, export as a GitHub gist (shareable link) or a local file. Finally, share the link or file with others. It is a checklist, but a meaningful one: every item creates evidence that the next step is safe.

      +

      Alex: Keep the teaching thread moving. Start with Common mistakes to avoid. There is something to understand, something to try, and something that proves the try worked.

      +

      Alex: The practical takeaway is this. "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.

      +

      Jamie: Let's pause on Good commit messages in practice. What should a learner take away from it?

      +

      Alex: Keep the learner anchored in Good commit messages in practice. When you make a habit of writing good commit messages, you build trust. This is the part to say slowly: Maintainers see that you care about the project's long-term health, not just your immediate contribution.

      +

      Alex: Treat examples as spoken recipes, not decorations. You may hear something like 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. Read the command, understand what it changes, then run it only when the repository state matches the lesson.

      +

      Alex: Keep the teaching thread moving. Start with Learning Cards: Writing Good Commit Messages. There is something to understand, something to try, and something that proves the try worked.

      +

      Alex: The practical takeaway is this. 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. 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.

      -

      Alex: Keep the teaching thread moving. Keep the learner anchored in Profiles and Settings Sync. Profiles sync across machines through Settings Sync. This is the part to say slowly: 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.

      -

      Jamie: Let's pause on Learning Cards: Profiles. What should a learner take away from it?

      -

      Alex: Start with Learning Cards: Profiles. There is something to understand, something to try, and something that proves the try worked.

      -

      Alex: The practical takeaway is this. 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. 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.

      -

      Alex: Keep the teaching thread moving. Start with 10. The Settings Editor: The Settings Editor is where you customize VS Code. The next useful detail is this: There are two views: the graphical settings UI and the raw settings.json file. Think of it like entering a new building: first you find the lobby, then the room, then the door you actually need.

      +

      Jamie: Let's pause on The Nature of Open Source Communication. What should a learner take away from it?

      +

      Alex: Start with The Nature of Open Source Communication: Open source collaboration happens primarily in writing, asynchronously, in public. The next useful detail is this: Understanding these three characteristics shapes everything about how we communicate.

      +

      Alex: Keep the teaching thread moving. Start with In writing. There is something to understand, something to try, and something that proves the try worked.

      +

      Alex: The practical takeaway is this. 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.".

      +

      Jamie: Let's pause on Asynchronously. What should a learner take away from it?

      +

      Alex: Start with Asynchronously. There is something to understand, something to try, and something that proves the try worked.

      +

      Alex: The practical takeaway is this. 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.

      -

      Jamie: Let's pause on Navigating the Settings Editor. What should a learner take away from it?

      -

      Alex: Here is the plain-English version of Navigating the Settings Editor. The graphical Settings UI has a search box at the top. Put another way, type any keyword and the settings list filters instantly.

      -

      Alex: Keep the teaching thread moving. Start with Learning Cards: Settings Editor. There is something to understand, something to try, and something that proves the try worked.

      -

      Alex: The practical takeaway is this. 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. 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).

      -

      Jamie: Let's pause on 11. The Keyboard Shortcuts Editor. What should a learner take away from it?

      -

      Alex: Keep the learner anchored in 11. The Keyboard Shortcuts Editor. The Keyboard Shortcuts Editor lets you view, search, and customize every keyboard shortcut in VS Code.

      +

      Alex: Keep the teaching thread moving. Start with In public. There is something to understand, something to try, and something that proves the try worked.

      +

      Alex: The practical takeaway is this. 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.

      +

      Jamie: What do you want them to do when the plan breaks?

      +

      Alex: The reason The Anatomy of Helpful Feedback matters is that whether commenting on an issue, reviewing a PR, or responding to a question, effective feedback has a structure.

      +

      Alex: Keep the teaching thread moving. Start with 1. Acknowledge what's working: Before identifying problems, name what is good. The next useful detail is this: This is not flattery - it is accuracy. Think of it like entering a new building: first you find the lobby, then the room, then the door you actually need.

      -

      Alex: Keep the teaching thread moving. The reason Searching for Shortcuts matters is that the editor has a search box that supports. The interface gets friendlier when it stops being a wall of controls and starts being a set of named places.

      -

      Alex: The practical takeaway is this. 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.

      -

      Jamie: Let's pause on Customizing a Shortcut. What should a learner take away from it?

      -

      Alex: Start with Customizing a Shortcut. There is something to understand, something to try, and something that proves the try worked.

      -

      Alex: First, find the command in the list. Then, double-click the keybinding column (or press Enter on the row, then Enter again on the keybinding). After that, press your desired key combination. Finally, press Enter to confirm. Think of it as a rail line: each stop confirms you are still on the right route before the next one.

      -

      Alex: Keep the teaching thread moving. Here is the plain-English version of Learning Cards: Keyboard Shortcuts Editor. Next: Chapter 12: VS Code Accessibility Back: Chapter 10: Notifications and Day 1 Close Related appendices: Appendix G: VS Code Reference Appendix B: Screen Reader Cheat Sheet.

      -

      Alex: The practical takeaway is this. 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. search for accessibility to find all accessibility-related shortcuts at once. 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.

      +

      Jamie: Let's pause on 2. Identify the specific concern. What should a learner take away from it?

      +

      Alex: Here is the plain-English version of 2. Identify the specific concern. "This code is inaccessible." "This button has no accessible name - aria-label or visible text is needed for screen readers to announce its purpose.".

      +

      Alex: Keep the teaching thread moving. This is where 3. Explain why it matters becomes real: context turns a complaint into a lesson. That matters in practice: It also respects the contributor - they deserve to understand, not just comply.

      +

      Jamie: Let's pause on 4. Suggest a path forward (when you can). What should a learner take away from it?

      +

      Alex: Keep the learner anchored in 4. Suggest a path forward (when you can). If you have an idea for a solution, offer it as a suggestion, not a mandate. This is the part to say slowly: "Something like aria-label='Close navigation menu' would work well here.

      -

      Jamie: What should people carry with them after this?

      -

      Alex: Carry the map. Know what page or tool you are in, know which action you are taking, and know what confirmation should follow. If the confirmation is missing, pause. That pause is not wasted time; it is professional judgment.

      -

      Jamie: That is a better way to say it than just follow the steps.

      -

      Alex: Right. Steps matter, but understanding wins. That is episode 11. Next in the series is episode 12, where we keep building the same contributor muscles.

      -
      - +

      Alex: Keep the teaching thread moving. The reason 5. Signal the weight of the concern matters is that help contributors understand what is a blocker versus a preference. The interface gets friendlier when it stops being a wall of controls and starts being a set of named places.

      +

      Alex: The practical takeaway is this. 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.

      +

      Jamie: Let's pause on Prefer "we" or describe the code, not the person. What should a learner take away from it?

      +

      Alex: Start with 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.".

      +

      Alex: Keep the teaching thread moving. Here is the plain-English version of 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?".

      -

      Episode 12: Git and Source Control in VS Code

      -

      Cloning, branching, staging, committing, pushing, and pulling from VS Code.

      -

      Based on: Chapter 14: Git and Source Control in VS Code

      -

      Audio and transcript are being regenerated for this episode.

      -
      -Read Transcript - Episode 12: Git and Source Control in VS Code - -

      Transcript

      -

      Alex: Welcome to Git Going with GitHub, episode 12: Git and Source Control in VS Code. I am Alex. Today we are going to make Git and Source Control in VS Code something you can explain, practice, and recover from when the interface surprises you.

      -

      Jamie: And I am Jamie. I will be the voice of the learner who is willing to ask, what is this for, where am I, and how do I know I did it right?

      +

      Jamie: Let's pause on Acknowledge cultural and language diversity. What should a learner take away from it?

      +

      Alex: This is where Acknowledge cultural and language diversity becomes real: when reading someone's comment: Assume good intent unless there is clear evidence otherwise. That matters in practice: When writing: Choose plain words over clever ones.

      +

      Alex: The practical takeaway is this. 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.

      +

      Alex: Keep the teaching thread moving. Keep the learner anchored in 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?". A good GitHub workflow is like a well-run meeting: everyone knows the topic, the next action, and who has the floor.

      +

      Jamie: Let's pause on Keep comments focused. What should a learner take away from it?

      +

      Alex: The reason Keep comments focused matters is that each comment should address one concern. That gives the learner a simple foothold: if you have three issues, leave three comments - unless they are closely related.

      -

      Alex: The big idea today: Cloning, branching, staging, committing, pushing, and pulling from VS Code. We will name the concept, explain why it matters, practice the move, and point out the checks that tell you the work is real.

      -

      Jamie: So the episode should work even if someone has not read the chapter yet.

      -

      Alex: Exactly. The transcript has to stand on its own. It can point toward practice, but it should teach the concept right here in the conversation.

      +

      Alex: Keep the teaching thread moving. Start with Don't leave comments unresolved: If you asked a question and got an answer, respond. The next useful detail is this: "Thanks, that makes sense" or resolving the conversation thread signals that the thread is complete.

      +

      Jamie: Let's pause on Resolving conversations. What should a learner take away from it?

      +

      Alex: Here is the plain-English version of Resolving conversations. On a PR, conversations (inline comment threads) can be "resolved" once addressed. Put another way, the author of the change and the reviewer can both resolve them.

      +

      Alex: Keep the teaching thread moving. This is where Do not "pile on" becomes real: if five people already said the same thing about an issue, you don't need to add a sixth comment saying the same thing. That matters in practice: A reaction on an existing comment is enough. The workshop is closer to rehearsal than lecture. You hear the move, try the move, and then check what changed.

      -

      Jamie: Okay, set the room for us. What are we walking into?

      -

      Alex: Start with 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. The next useful detail is this: Prerequisites: VS Code Setup & Accessibility Basics, Working with Pull Requests, Merge Conflicts Mac keyboard shortcuts: Throughout this chapter, all Ctrl+ shortcuts use Cmd+ on Mac, and Alt+ shortcuts use Option+.

      -

      Alex: A solid Git habit is to know which branch you are on, what changed, and what confirmation you expect before you run the next command.

      -

      Alex: The next layer is this. Here is the plain-English version of Workshop Recommendation (Chapter 14 / Challenge 10). Chapter 14 is the first local Git workflow chapter with hands-on repository management. Put another way, it supports Challenge 10: Go Local. It is like learning a transit route. The names of the stops matter because they tell you whether you are still going the right direction.

      -

      Alex: The practical anchors are these. There are 3. Each challenge should take under 10 minutes each. The evidence is PR metadata, branch names, and committed changes. The pattern is clone, branch, edit, commit, push, PR.

      -

      Jamie: What does the learner do first, second, and then after that?

      -

      Alex: Start with Challenge 10 Practice Set. There is something to understand, something to try, and something that proves the try worked.

      -

      Alex: First, clone your Learning Room repository - clone your private Learning Room repo to your local machine using VS Code. Then, 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. After that, 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. It is a checklist, but a meaningful one: every item creates evidence that the next step is safe.

      -

      Alex: A solid pull request habit is to separate three questions: what changed, why it changed, and what still needs review. That keeps the conversation useful instead of noisy.

      +

      Jamie: Let's pause on Reactions. What should a learner take away from it?

      +

      Alex: Keep the learner anchored in Reactions. GitHub reactions () are an efficient way to express agreement, appreciation, or concern without adding noise to a thread.

      +

      Alex: Keep the teaching thread moving. The reason Saved Replies - Your Accessibility Win matters is that GitHub lets you save frequently used responses as Saved Replies - reusable text snippets you can insert into any comment box with a few keystrokes. That gives the learner a simple foothold: this is a significant accessibility win for anyone who types the same comments repeatedly during triage, reviews, or issue management.

      +

      Jamie: Let's pause on Common uses. What should a learner take away from it?

      +

      Alex: Start with Common uses. There is something to understand, something to try, and something that proves the try worked.

      +

      Alex: The practical takeaway is this. "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.

      -

      Jamie: Turn that into a path someone can follow.

      -

      Alex: Keep the learner anchored in Practice 10.1 Step-by-Step: Clone Your Learning Room Repository. Get a local copy of your Learning Room repository on your machine using VS Code. This is the part to say slowly: VS Code desktop (or github.dev if you cannot install desktop VS Code).

      -

      Alex: First, open VS Code. If no folder is open, you should see the Welcome tab. Then, open the Command Palette: Ctrl+Shift+P (Mac: Cmd+Shift+P). After that, type git clone and select Git: Clone. Finally, VS Code asks for a repository URL. Paste your Learning Room repo URL (it looks like https://github.com/the workshop organization/learning-room-your username.git). You can copy this from the green Code button on your repo's GitHub page. It is like walking a hallway with named doors: read the sign, enter the right room, then confirm where you landed.

      -

      Jamie: What is the ordered workflow?

      -

      Alex: First, press Enter. Then, 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. After that, VS Code clones the repository. When it finishes, a notification appears asking "Would you like to open the cloned repository?" Activate Open. Finally, 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. The rhythm is simple: orient, act, verify, then continue.

      -

      Jamie: Give me the sequence, because order matters here.

      -

      Alex: The reason Practice 10.2 Step-by-Step: Create a Branch and Commit matters is that see also: Chapter 13: How Git Works explains the three areas (working directory, staging, repository) that make commits meaningful. That gives the learner a simple foothold: check out (or create) a properly named branch, edit a file, stage the change, and commit with a clear message.

      -

      Alex: First, open the Command Palette: Ctrl+Shift+P (Mac: Cmd+Shift+P). Then, 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/your username. If the branch does not exist yet, type git create branch and select Git: Create Branch. After that, 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. Finally, 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). The rhythm is simple: orient, act, verify, then continue.

      -

      Jamie: How would you walk the room through that step by step?

      -

      Alex: First, 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). Then, 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.". After that, 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.". Finally, 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. Think of it as a rail line: each stop confirms you are still on the right route before the next one.

      -

      Jamie: Let's pause on Practice 10.3 Step-by-Step: Push and Open a Linked PR. What should a learner take away from it?

      -

      Alex: Start with Practice 10.3 Step-by-Step: Push and Open a Linked PR: Push your branch to GitHub and open a PR in your Learning Room repo that references your challenge issue. The next useful detail is this: VS Code (for the push) and GitHub.com (for the PR). Think of it like entering a new building: first you find the lobby, then the room, then the door you actually need.

      -

      Alex: First, open the Command Palette: Ctrl+Shift+P (Mac: Cmd+Shift+P). Then, 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. After that, 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. Finally, open your browser and navigate to your Learning Room repository on GitHub. Think of it as a rail line: each stop confirms you are still on the right route before the next one.

      -

      Jamie: Before we leave Practice 10.3 Step-by-Step: Push and Open a Linked PR, what is the practical point?

      -

      Alex: First, GitHub usually shows a yellow banner: "yourname recently pushed to learn/yourname." Activate the Compare & pull request button in that banner. Then, 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/your username branch. After that, in the PR title, write a descriptive title (for example: "docs: improve welcome.md introduction"). Finally, 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. Treat it like a recipe: do not add the next ingredient until the previous one is actually in the bowl.

      +

      Jamie: Let's pause on Creating a Saved Reply. What should a learner take away from it?

      +

      Alex: Start with Creating a Saved Reply. There is something to understand, something to try, and something that proves the try worked.

      +

      Alex: First, navigate to github.com/settings/replies. Then, activate "Add a saved reply". After that, give it a title (e.g., "Good first issue claim") - this is what you search. Finally, type the full reply text in the body (Markdown is supported). Treat it like a recipe: do not add the next ingredient until the previous one is actually in the bowl.

      +

      Jamie: Let's pause on Using a Saved Reply in a comment. What should a learner take away from it?

      +

      Alex: Start with Using a Saved Reply in a comment. There is something to understand, something to try, and something that proves the try worked.

      +

      Alex: First, navigate to any comment text area. Then, activate the Saved Replies button (the speech bubble icon in the comment toolbar, or press Ctrl+. if enabled). After that, a dropdown appears showing your saved replies - type to filter by title. Finally, select the reply - it inserts into the text area. It is a checklist, but a meaningful one: every item creates evidence that the next step is safe.

      +

      Jamie: Before we leave Using a Saved Reply in a comment, what is the practical point?

      +

      Alex: First, edit as needed before submitting. It is like walking a hallway with named doors: read the sign, enter the right room, then confirm where you landed.

      +

      Alex: Keep the teaching thread moving. Keep the learner anchored in Screen reader path. Limit: GitHub allows up to 100 saved replies per account.

      -

      Jamie: What should the learner prove to themselves after each small task?

      -

      Alex: Here is the plain-English version of Completing Challenge 10: Submit Your Evidence. Open your assigned Challenge 10 issue in your Learning Room repo and post a completion comment. Put another way, close your Challenge 10 issue when your branch is pushed and the PR is open.

      -

      Alex: The useful habit is simple: orient first, act second, verify third. That pause before acting is part of the work.

      -

      Alex: This is where the talk moves from concept to action. Start with Expected Outcomes. There is something to understand, something to try, and something that proves the try worked.

      -

      Alex: The room should hear these as checkpoints. 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.

      -

      Jamie: Let's pause on If You Get Stuck. What should a learner take away from it?

      -

      Alex: Keep the learner anchored in If You Get Stuck. Continue learning: The GitHub Skills course Introduction to Git walks through commits, branches, and merges in an interactive, self-paced format. This is the part to say slowly: See Appendix Z for the full catalog.

      -

      Alex: First, command Palette does not open? Confirm you are in VS Code (not the browser) and press Ctrl+Shift+P (Mac: Cmd+Shift+P). Then, source Control panel is empty? You may not have saved your file yet. Press Ctrl+S to save, then check again. After that, 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. Finally, branch name wrong? Open Command Palette, run Git: Rename Branch. to fix it before pushing. It is like walking a hallway with named doors: read the sign, enter the right room, then confirm where you landed.

      -

      Jamie: Before we leave If You Get Stuck, what is the practical point?

      -

      Alex: First, cannot find the "Compare & pull request" banner on GitHub? Navigate to Pull requests tab and create the PR manually (step 6 above). Then, 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. After that, ask facilitator to verify your clone location, branch name, and help with one push. Finally, finished but not sure you did it right? Compare your work against the Challenge 10 reference solution. The rhythm is simple: orient, act, verify, then continue.

      +

      Jamie: Let's pause on Learning Cards: Commenting Etiquette. What should a learner take away from it?

      +

      Alex: Start with Learning Cards: Commenting Etiquette. There is something to understand, something to try, and something that proves the try worked.

      +

      Alex: The practical takeaway is this. 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. 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.

      +

      Alex: Keep the teaching thread moving. Start with 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.". Think of it like entering a new building: first you find the lobby, then the room, then the door you actually need.

      +

      Jamie: Let's pause on Don't gatekeep knowledge. What should a learner take away from it?

      +

      Alex: Here is the plain-English version of Don't gatekeep knowledge. If a contributor makes a mistake because they didn't know something, explain the concept.

      -

      Alex: Before the learner moves on. The reason Learning Moment matters is that local Git operations give you full control and immediate feedback. That gives the learner a simple foothold: you can see your changes, review them, and fix mistakes before they reach GitHub. The interface gets friendlier when it stops being a wall of controls and starts being a set of named places.

      -

      Jamie: Let's pause on Learning Pattern Used in This Chapter. What should a learner take away from it?

      -

      Alex: Start with Learning Pattern Used in This Chapter. There is something to understand, something to try, and something that proves the try worked.

      -

      Alex: First, clone once to get a local copy of the project. Then, branch before editing (never work directly on main). After that, make small, focused edits with clear commit messages. Finally, push and open a PR that links to an issue for traceability. Think of it as a rail line: each stop confirms you are still on the right route before the next one.

      -

      Jamie: Before we leave Learning Pattern Used in This Chapter, what is the practical point?

      -

      Alex: First, verify each step before moving to the next. Treat it like a recipe: do not add the next ingredient until the previous one is actually in the bowl.

      -

      Alex: Hold that next to this. Here is the plain-English version of About Learning Cards. Throughout this chapter, each major operation includes learning cards - expandable sections showing how to accomplish the same task from multiple perspectives. Put another way, open the card that matches how you work.

      +

      Alex: Keep the teaching thread moving. This is where Ask questions instead of making demands becomes real: "Change this to use aria-label." "What do you think about using aria-label here instead? That matters in practice: Screen readers would then announce the button's purpose directly.".

      +

      Jamie: Let's pause on Distinguish opinion from requirement. What should a learner take away from it?

      +

      Alex: Keep the learner anchored in Distinguish opinion from requirement. If something is your stylistic preference but NOT a bug or correctness issue, say so. This is the part to say slowly: "The current implementation is correct.

      +

      Alex: Keep the teaching thread moving. The reason Approve explicitly matters is that 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! The interface gets friendlier when it stops being a wall of controls and starts being a set of named places.

      -

      Jamie: Let's pause on Tool Cards: Clone a Repository (Day 2). What should a learner take away from it?

      -

      Alex: This is where Tool Cards: Clone a Repository (Day 2) becomes real: VS Code Desktop (primary for Day 2). That matters in practice: github.dev (web editor): No clone needed.

      -

      Alex: First, ctrl+Shift+P Git: Clone paste the HTTPS URL choose a folder Open. Then, file Clone Repository paste URL or select from your account Clone. It is a checklist, but a meaningful one: every item creates evidence that the next step is safe.

      -

      Alex: Treat examples as spoken recipes, not decorations. You may hear something like git clone https://github.com/owner/repo.git && cd repo. gh repo clone owner/repo && cd repo. Read the command, understand what it changes, then run it only when the repository state matches the lesson.

      -

      Jamie: Let's pause on Method 1: Command Palette (Recommended for Screen Readers). What should a learner take away from it?

      -

      Alex: Start with Method 1: Command Palette (Recommended for Screen Readers). There is something to understand, something to try, and something that proves the try worked.

      -

      Alex: First, open Command Palette: Ctrl+Shift+P (Mac: Cmd+Shift+P). Then, type "git clone". After that, select "Git: Clone". Finally, paste the repository URL (example: https://github.com/community-access/accessibility-agents.git). It is like walking a hallway with named doors: read the sign, enter the right room, then confirm where you landed.

      -

      Jamie: Before we leave Method 1: Command Palette (Recommended for Screen Readers), what is the practical point?

      -

      Alex: First, press Enter. Then, choose a local folder where the repository should be cloned. After that, VS Code asks: "Would you like to open the cloned repository?" - select "Open". The rhythm is simple: orient, act, verify, then continue.

      -

      Alex: A solid navigation habit is to prove where you are before activating controls. Headings, landmarks, and the address bar are not trivia; they are your map.

      -

      Jamie: What is the one idea that makes the next few steps less mysterious?

      -

      Alex: Start with Screen reader navigation. There is something to understand, something to try, and something that proves the try worked.

      -

      Alex: The parts worth keeping in working memory are these. 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.

      +

      Jamie: Let's pause on Say thank you. What should a learner take away from it?

      +

      Alex: Start with Say thank you: When someone takes time to review your work, acknowledge it - even if you disagree with some feedback. The next useful detail is this: "Thanks so much for the thorough review!

      +

      Alex: Keep the teaching thread moving. Here is the plain-English version of Don't take feedback personally. Code review is about the code, not your worth as a person or developer. Put another way, even the most senior contributors receive change requests.

      +

      Jamie: Let's pause on Explain your choices. What should a learner take away from it?

      +

      Alex: This is where Explain your choices becomes real: if you are keeping your implementation despite feedback, explain why. That matters in practice: "I considered aria-label here, but I went with a visually-hidden instead because it allows translators to localize the text more easily.

      -

      Jamie: Let's pause on Method 2: Start Page Clone Button. What should a learner take away from it?

      -

      Alex: Start with Method 2: Start Page Clone Button: The Start page is keyboard-accessible. The next useful detail is this: Tab to navigate between "New File," "Open Folder," and "Clone Repository" buttons.

      -

      Alex: First, open VS Code (no folder open). Then, the Start page appears. After that, navigate to "Clone Git Repository" button - press Enter. Finally, paste repository URL → Enter. Think of it as a rail line: each stop confirms you are still on the right route before the next one.

      -

      Jamie: Before we leave Method 2: Start Page Clone Button, what is the practical point?

      -

      Alex: First, choose destination folder. Then, open when prompted. Treat it like a recipe: do not add the next ingredient until the previous one is actually in the bowl.

      -

      Jamie: Let's pause on Method 3: From GitHub.com. What should a learner take away from it?

      -

      Alex: Start with Method 3: From GitHub.com. There is something to understand, something to try, and something that proves the try worked.

      -

      Alex: First, on any GitHub repository page, click the green "Code" button. Then, copy the HTTPS URL (recommended) or SSH URL. After that, open VS Code → Ctrl+Shift+P (Mac: Cmd+Shift+P) → "Git: Clone". Finally, paste URL → Enter. Treat it like a recipe: do not add the next ingredient until the previous one is actually in the bowl.

      -

      Jamie: Before we leave Method 3: From GitHub.com, what is the practical point?

      -

      Alex: First, choose destination → Open. It is a checklist, but a meaningful one: every item creates evidence that the next step is safe.

      -

      Jamie: Let's pause on Learning Cards: Cloning a Repository. What should a learner take away from it?

      -

      Alex: This is where Learning Cards: Cloning a Repository becomes real: low vision users (zoom, high contrast). That matters in practice: Cloning works the same as the Command Palette method above. The workshop is closer to rehearsal than lecture. You hear the move, try the move, and then check what changed.

      -

      Alex: First, 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. Then, 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. After that, 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. Finally, 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. It is a checklist, but a meaningful one: every item creates evidence that the next step is safe.

      -

      Jamie: Before we leave Learning Cards: Cloning a Repository, what is the practical point?

      -

      Alex: First, navigate to the repository on GitHub.com. Then, press. (period) to open github.dev - a browser-based VS Code editor. After that, the full repository opens in an editor with file tree, search, and editing. Finally, changes are committed directly to GitHub from the browser. It is like walking a hallway with named doors: read the sign, enter the right room, then confirm where you landed.

      -

      Alex: Treat examples as spoken recipes, not decorations. You may hear something like 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. Read the command, understand what it changes, then run it only when the repository state matches the lesson.

      +

      Alex: Keep the teaching thread moving. Keep the learner anchored in Surface blockers early. Don't wait until you have finished a 500-line PR to mention that you weren't sure about the approach. A good GitHub workflow is like a well-run meeting: everyone knows the topic, the next action, and who has the floor.

      +

      Jamie: Let's pause on Inclusive Commenting for Accessibility Issues. What should a learner take away from it?

      +

      Alex: The reason Inclusive Commenting for Accessibility Issues matters is that when filing or discussing accessibility bugs, additional context helps.

      +

      Alex: The practical takeaway is this. 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.

      +

      Jamie: Let's pause on The "Good First Issue" Social Contract. What should a learner take away from it?

      +

      Alex: Start with The "Good First Issue" Social Contract: When a maintainer labels an issue good first issue, they are. The next useful detail is this: When you take a good first issue, your responsibilities.

      +

      Alex: The practical takeaway is this. Investing time - good first issues require extra documentation and mentorship. Signaling welcome - they want to support a new contributor.

      +

      Alex: First, comment to claim it - "Hi, I'd like to work on this. Can I be assigned?". Then, wait for assignment - do not start until assigned; two people working in parallel wastes everyone's time. After that, 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?". Finally, 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?". Think of it as a rail line: each stop confirms you are still on the right route before the next one.

      +

      Jamie: Before we leave The "Good First Issue" Social Contract, what is the practical point?

      +

      Alex: First, don't disappear - if you claim an issue, see it through or explicitly hand it back. Treat it like a recipe: do not add the next ingredient until the previous one is actually in the bowl.

      -

      Jamie: Why is the evidence prompt part of the teaching, not just grading?

      -

      Alex: Keep the learner anchored in 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. This is the part to say slowly: Repository URL: https://github.com/community-access/vscode-sci-fi-themes.git.

      -

      Alex: These are the details that keep the idea from floating away. 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.

      -

      Alex: Another way to ground it. Start with Why Clone This? There is something to understand, something to try, and something that proves the try worked.

      -

      Alex: That becomes easier when you listen for these cues. 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!

      -

      Jamie: Let's pause on Quick Start. What should a learner take away from it?

      -

      Alex: Start with Quick Start: See CLONE-THIS-REPO.md in that repo for full instructions. The next useful detail is this: If you prefer not to clone locally, you can work entirely on GitHub.com.

      -

      Alex: First, clone: Ctrl+Shift+P → "Git: Clone" → paste URL above → Enter. Then, choose a destination folder and open when prompted. After that, navigate to the themes/ folder and pick a.json file (star-trek, hitchhikers, or star-wars). Finally, copy the chat.agent.thinking.phrases setting into your VS Code settings.json. Think of it as a rail line: each stop confirms you are still on the right route before the next one.

      -

      Jamie: Before we leave Quick Start, what is the practical point?

      -

      Alex: First, reload VS Code: Ctrl+Shift+P → "Developer: Reload Window". Then, open Copilot Chat (Ctrl+Shift+I) and ask a question--watch your custom phrases appear! After that, navigate to the repository on GitHub. Finally, click any file to view it, then click the pencil icon (Edit) to modify it directly in the browser. Treat it like a recipe: do not add the next ingredient until the previous one is actually in the bowl.

      -

      Alex: Treat examples as spoken recipes, not decorations. You may hear something like 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. Read the command, understand what it changes, then run it only when the repository state matches the lesson.

      +

      Jamie: Let's pause on When you receive harsh feedback. What should a learner take away from it?

      +

      Alex: Start with When you receive harsh feedback. There is something to understand, something to try, and something that proves the try worked.

      +

      Alex: First, take a breath before responding - there is no urgency; the thread will wait. Then, look for the valid concern underneath the harsh words. After that, respond to the concern, not the tone. Finally, if the behavior crosses into harassment, report it via the "." button on the comment → "Report". Treat it like a recipe: do not add the next ingredient until the previous one is actually in the bowl.

      +

      Jamie: Let's pause on When you disagree with a decision. What should a learner take away from it?

      +

      Alex: Start with When you disagree with a decision. There is something to understand, something to try, and something that proves the try worked.

      +

      Alex: First, make your case once, clearly and with evidence. Then, accept that the maintainer has the final say in their project. After that, if you strongly disagree, you can fork the project and take it in a different direction - this is legitimate in open source. It is a checklist, but a meaningful one: every item creates evidence that the next step is safe.

      +

      Jamie: Let's pause on When someone is rude to you. What should a learner take away from it?

      +

      Alex: Start with When someone is rude to you. There is something to understand, something to try, and something that proves the try worked.

      +

      Alex: First, you do not have to engage. Then, 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.". After that, report via GitHub's reporting tools if the behavior is abusive. It is like walking a hallway with named doors: read the sign, enter the right room, then confirm where you landed.

      -

      Alex: This is the part worth saying out loud. Here is the plain-English version of 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. Put another way, this section provides a complete screen reader walkthrough of every interactive element. It is like learning a transit route. The names of the stops matter because they tell you whether you are still going the right direction.

      -

      Jamie: What would you say to someone who is already bracing for this to be too much?

      -

      Alex: This is where Opening the Source Control Panel becomes real: shortcut: Ctrl+Shift+G (Mac: Cmd+Shift+G).

      -

      Alex: That connects to another useful point. Start with What opens. There is something to understand, something to try, and something that proves the try worked.

      -

      Alex: For a learner, the useful signals are these. 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).

      +

      Jamie: Let's pause on When you accidentally caused offense. What should a learner take away from it?

      +

      Alex: Start with When you accidentally caused offense. There is something to understand, something to try, and something that proves the try worked.

      +

      Alex: First, acknowledge it directly: "I can see how that came across as dismissive - that wasn't my intention.". Then, do not over-explain or defend excessively. After that, adjust going forward. The rhythm is simple: orient, act, verify, then continue.

      +

      Jamie: Let's pause on Writing Your First README. What should a learner take away from it?

      +

      Alex: Start with Writing Your First README: See also: Appendix W: GitHub Pages for publishing your README as a website. The next useful detail is this: A README is the front door of your project.

      +

      Alex: Keep the teaching thread moving. Here is the plain-English version of What belongs in a README. Every README should answer these questions, roughly in this order. Put another way, 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. It is like learning a transit route. The names of the stops matter because they tell you whether you are still going the right direction.

      -

      Jamie: Let's pause on Panel structure from top to bottom. What should a learner take away from it?

      -

      Alex: Start with Panel structure from top to bottom. There is something to understand, something to try, and something that proves the try worked.

      -

      Alex: On the ground, that means a few things. Branch name displayed (example: "main" or "feature/add-documentation"). View/More Actions button (three dots menu). Type your commit message here. Announced as "Source Control Input, edit, multi-line". Shortcut: Ctrl+Enter (Mac: Cmd+Enter) when focused in the message input. Lists all modified files not yet staged.

      -

      Alex: First, source Control title bar (heading level 2). Then, commit message input (multi-line text field). After that, commit button (or "Publish Branch" if this is a new branch). Finally, changes section (collapsible tree). The rhythm is simple: orient, act, verify, then continue.

      -

      Jamie: Before we leave Panel structure from top to bottom, what is the practical point?

      -

      Alex: First, staged Changes section (collapsible tree). Then, merge Changes section (appears only during a merge). Think of it as a rail line: each stop confirms you are still on the right route before the next one.

      -

      Alex: Now bring the learner back to the room. Start with NVDA/JAWS. There is something to understand, something to try, and something that proves the try worked.

      -

      Alex: Here is what that changes in practice. 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).

      -

      Jamie: Where do you want a learner to place their attention here?

      -

      Alex: Here is the plain-English version of VoiceOver. Key point: The Source Control panel is not a standard file tree. Put another way, it's a specialized Git status view.

      -

      Alex: A few details make that real. Navigate with VO+Arrow keys. VO+Space to activate (open diff or stage/unstage). The panel is announced as a "group" containing lists.

      +

      Jamie: Let's pause on Accessibility in READMEs. What should a learner take away from it?

      +

      Alex: This is where Accessibility in READMEs becomes real: your README is a web page -- GitHub renders it as HTML. That matters in practice: That means the same accessibility rules apply.

      +

      Alex: The practical takeaway is this. Alt text for images and badges. A badge that says is invisible to screen readers. Write 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 -- not Click here.

      +

      Alex: Keep the teaching thread moving. Keep the learner anchored in Good README vs. bad README. Bad: A single paragraph that says "This is my project. This is the part to say slowly: Run it with npm start." No headings, no license, no description of what the project does.

      +

      Jamie: Let's pause on Learning Cards: Writing Your First README. What should a learner take away from it?

      +

      Alex: Start with Learning Cards: Writing Your First README. There is something to understand, something to try, and something that proves the try worked.

      +

      Alex: The practical takeaway is this. 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: rather than an empty that reads as "image" with no context. Use real Markdown link text (installation guide) instead of bare URLs, so your screen reader announces the destination rather than spelling out a long URL. 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.

      -

      Alex: That matters because of the next idea. This is where What Each File Shows becomes real: when a file appears in the Changes or Staged Changes list, VS Code shows a status letter. That matters in practice: Screen reader announcement: "docs/GUIDE.md, Modified" or "README.md, Added".

      -

      Jamie: Give me the version that sounds like an instructor, not a manual.

      -

      Alex: Keep the learner anchored in Context Menu Actions (Right-Click or Shift+F10). When focused on any file in the Source Control panel. This is the part to say slowly: Use Shift+F10 to open the context menu.

      -

      Jamie: Let's pause on Learning Cards: Source Control Panel. What should a learner take away from it?

      -

      Alex: The reason Learning Cards: Source Control Panel matters is that low vision users (zoom, high contrast). That gives the learner a simple foothold: the Source Control panel adapts well to zoom and high contrast settings. The interface gets friendlier when it stops being a wall of controls and starts being a set of named places.

      -

      Alex: First, 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. Then, 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. After that, 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). Finally, 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. The rhythm is simple: orient, act, verify, then continue.

      -

      Jamie: Before we leave Learning Cards: Source Control Panel, what is the practical point?

      -

      Alex: First, 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. Think of it as a rail line: each stop confirms you are still on the right route before the next one.

      -

      Alex: Treat examples as spoken recipes, not decorations. You may hear something like 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. Read the command, understand what it changes, then run it only when the repository state matches the lesson.

      -
      -

      Jamie: If I am listening before the workshop starts, what should settle in my mind first?

      -

      Alex: Start with 3. Branch Management: Branches are how you organize work in Git. The next useful detail is this: Every repository starts with a main or master branch.

      -

      Jamie: Let's pause on Where it's shown. What should a learner take away from it?

      -

      Alex: Start with Where it's shown. There is something to understand, something to try, and something that proves the try worked.

      -

      Alex: First, bottom-left corner of VS Code (status bar) - visual users see it immediately. Then, source Control panel title bar. After that, command Palette: Ctrl+Shift+P (Mac: Cmd+Shift+P) → "Git: Show Git Output". Treat it like a recipe: do not add the next ingredient until the previous one is actually in the bowl.

      -

      Jamie: Let's pause on Keyboard access to status bar. What should a learner take away from it?

      -

      Alex: This is where Keyboard access to status bar becomes real: visual users: You can also click the branch name in the bottom-left status bar to open the branch picker directly.

      -

      Alex: That shows up in the workshop in a few specific ways. The status bar is not in the standard keyboard navigation flow. Use the Command Palette for branch operations instead.

      +

      Alex: Keep the teaching thread moving. Start with Community Health Files: Community health files tell contributors how your project operates before they write a single line of code. The next useful detail is this: 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. Think of it like entering a new building: first you find the lobby, then the room, then the door you actually need.

      +

      Jamie: Let's pause on CONTRIBUTING.md. What should a learner take away from it?

      +

      Alex: Here is the plain-English version of CONTRIBUTING.md. This file answers the question every newcomer asks: "How do I help?" A good CONTRIBUTING.md covers. Put another way, a sentence like "We are glad you are here" costs nothing and signals that newcomers are expected, not tolerated.

      +

      Alex: The practical takeaway is this. 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.

      +

      Alex: Keep the teaching thread moving. This is where CODE OF CONDUCT.md becomes real: a code of conduct sets the social contract for your project. That matters in practice: Without one, "acceptable behavior" is whatever each participant assumes it is -- and those assumptions vary widely.

      +

      Alex: The practical takeaway is this. 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.

      -

      Jamie: Let's pause on Command Palette method (recommended). What should a learner take away from it?

      -

      Alex: Start with Command Palette method (recommended). There is something to understand, something to try, and something that proves the try worked.

      -

      Alex: The practical takeaway is this. Creates the branch. Switches to it automatically. Your working files stay exactly as they were.

      -

      Alex: First, ctrl+Shift+P (Mac: Cmd+Shift+P). Then, type "git create branch". After that, select "Git: Create Branch.". Finally, type the new branch name (example: feature/improve-docs). It is like walking a hallway with named doors: read the sign, enter the right room, then confirm where you landed.

      -

      Jamie: Before we leave Command Palette method (recommended), what is the practical point?

      -

      Alex: First, press Enter. The rhythm is simple: orient, act, verify, then continue.

      -

      Jamie: Let's pause on Naming conventions. What should a learner take away from it?

      -

      Alex: The reason Naming conventions matters is that web alternative (github.com) - branch management. That gives the learner a simple foothold: create and switch branches without leaving your browser.

      -

      Alex: The practical takeaway is this. Use lowercase with hyphens: feature/add-timeline-guide. Avoid spaces and special characters. Be descriptive: fix/heading-hierarchy not fix1.

      -

      Alex: First, on the repository page, click the branch dropdown (shows "main" by default). Then, type a new branch name in the search field. After that, click "Create branch: your-branch-name from main". Finally, GitHub switches to the new branch immediately. The rhythm is simple: orient, act, verify, then continue.

      -

      Jamie: Before we leave Naming conventions, what is the practical point?

      -

      Alex: First, any file edits you make in the browser will be on this branch. Think of it as a rail line: each stop confirms you are still on the right route before the next one.

      -

      Alex: Treat examples as spoken recipes, not decorations. You may hear something like 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. Read the command, understand what it changes, then run it only when the repository state matches the lesson.

      -

      Jamie: Let's pause on Command Palette method. What should a learner take away from it?

      -

      Alex: Start with Command Palette method: Screen reader announcement: "Branch: main" or "Branch: feature/add-timeline-guide".

      -

      Alex: First, ctrl+Shift+P (Mac: Cmd+Shift+P). Then, type "git checkout". After that, select "Git: Checkout to.". Finally, a list of all branches appears. Think of it as a rail line: each stop confirms you are still on the right route before the next one.

      -

      Jamie: Before we leave Command Palette method, what is the practical point?

      -

      Alex: First, up/Down Arrow to navigate. Then, enter to switch. Treat it like a recipe: do not add the next ingredient until the previous one is actually in the bowl.

      +

      Jamie: Let's pause on SECURITY.md. What should a learner take away from it?

      +

      Alex: Keep the learner anchored in SECURITY.md. See also: Appendix F: Git Security and Appendix P: Security Features for security best practices. This is the part to say slowly: If someone discovers a vulnerability in your project, you do not want them to file a public issue.

      +

      Alex: The practical takeaway is this. 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.

      +

      Alex: Keep the teaching thread moving. The reason LICENSE matters is that 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. That gives the learner a simple foothold: adding a LICENSE file is a one-time step that makes your project genuinely open source. The interface gets friendlier when it stops being a wall of controls and starts being a set of named places.

      +

      Jamie: Let's pause on Finding these files on GitHub. What should a learner take away from it?

      +

      Alex: Start with Finding these files on GitHub: Navigate to any repository and click Insights then Community Standards. The next useful detail is this: GitHub shows a checklist of which community health files are present and links to add any that are missing.

      -

      Jamie: Let's pause on What happens when you switch. What should a learner take away from it?

      -

      Alex: Start with What happens when you switch. There is something to understand, something to try, and something that proves the try worked.

      -

      Alex: The practical takeaway is this. 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).

      -

      Jamie: Let's pause on After your PR is merged, you can delete the branch. What should a learner take away from it?

      -

      Alex: This is where After your PR is merged, you can delete the branch becomes real: you cannot delete the branch you're currently on. The workshop is closer to rehearsal than lecture. You hear the move, try the move, and then check what changed.

      -

      Alex: First, ctrl+Shift+P (Mac: Cmd+Shift+P). Then, type "git delete branch". After that, select "Git: Delete Branch.". Finally, choose the branch to delete from the list. It is a checklist, but a meaningful one: every item creates evidence that the next step is safe.

      -

      Jamie: What is the safe way to learn from that example?

      -

      Alex: Keep the learner anchored in Viewing All Branches. Command: Ctrl+Shift+P → "Git: Show Git Output" → Branch list appears. This is the part to say slowly: Alternative: Use the integrated terminal.

      -

      Alex: Treat examples as spoken recipes, not decorations. You may hear something like git branch Local branches only; git branch -a All branches (including remote). Read the command, understand what it changes, then run it only when the repository state matches the lesson.

      +

      Alex: Keep the teaching thread moving. Start with Learning Cards: Community Health Files. There is something to understand, something to try, and something that proves the try worked.

      +

      Alex: The practical takeaway is this. 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. 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.

      +

      Jamie: How should someone choose between those options?

      +

      Alex: This is where When to Use Different Communication Channels becomes real: GitHub Discussions are separate from Issues. That matters in practice: Use Discussions for: "What do people think about X approach?" and Issues for: "The X button is broken.".

      +

      Alex: Use the comparison to make a decision, not to recite a table. The main contrasts are: PR comment means Feedback on a specific code change. PR review means Formal verdict (approve/request changes) with consolidated feedback. Discussion means Open-ended conversation, proposals, community Q&A.

      +

      Jamie: Let's pause on Try It: Rewrite One Comment. What should a learner take away from it?

      +

      Alex: Keep the learner anchored in Try It: Rewrite One Comment. Time: 2 minutes What you need: Just your brain. This is the part to say slowly: Read this code review comment and rewrite it to be constructive. A good GitHub workflow is like a well-run meeting: everyone knows the topic, the next action, and who has the floor.

      +

      Alex: First, what you noticed. Then, why it matters. After that, what you suggest. Finally, why the suggestion helps. It is like walking a hallway with named doors: read the sign, enter the right room, then confirm where you landed.

      +

      Jamie: Before we leave Try It: Rewrite One Comment, what is the practical point?

      +

      Alex: First, encouragement. The rhythm is simple: orient, act, verify, then continue.

      -

      Jamie: Let's pause on Learning Cards: Branch Management. What should a learner take away from it?

      -

      Alex: The reason Learning Cards: Branch Management matters is that low vision users (zoom, high contrast). That gives the learner a simple foothold: screen reader users (NVDA / JAWS on Windows).

      -

      Alex: First, 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. Then, 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. After that, 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. The rhythm is simple: orient, act, verify, then continue.

      -

      Jamie: Let's pause on Creating a branch. What should a learner take away from it?

      -

      Alex: Start with Creating a branch. There is something to understand, something to try, and something that proves the try worked.

      -

      Alex: First, press Ctrl+Shift+P to open the Command Palette. Then, type "git create branch" - NVDA/JAWS announces results as you type. After that, press Enter on "Git: Create Branch.". Finally, the input focus moves to a text field - type your branch name (e.g., feature/add-docs). Think of it as a rail line: each stop confirms you are still on the right route before the next one.

      -

      Jamie: Before we leave Creating a branch, what is the practical point?

      -

      Alex: First, press Enter - VS Code creates and switches to the branch. Then, NVDA/JAWS announces the new branch name in the status bar notification. Treat it like a recipe: do not add the next ingredient until the previous one is actually in the bowl.

      -

      Jamie: Let's pause on Switching branches. What should a learner take away from it?

      -

      Alex: Start with Switching branches. There is something to understand, something to try, and something that proves the try worked.

      -

      Alex: First, press Ctrl+Shift+P, type "git checkout". Then, select "Git: Checkout to.". After that, a list of branches appears - navigate with Up/Down Arrow. Finally, each item is announced as the branch name (e.g., "main", "feature/add-docs"). Treat it like a recipe: do not add the next ingredient until the previous one is actually in the bowl.

      -

      Jamie: Before we leave Switching branches, what is the practical point?

      -

      Alex: First, press Enter to switch. Then, VS Code reloads files for that branch - you hear a status bar update. It is a checklist, but a meaningful one: every item creates evidence that the next step is safe.

      +

      Jamie: Let's pause on Contributing to Open Source. What should a learner take away from it?

      +

      Alex: The reason Contributing to Open Source matters is that this section was previously Appendix T. That gives the learner a simple foothold: it is now part of the teaching narrative.

      +

      Alex: Keep the teaching thread moving. Start with A Guide for First-Time Contributors: You do not need to be a professional developer to contribute to open source. The next useful detail is this: Documentation, accessibility improvements, and bug reports are among the most valuable contributions any project can receive.

      +

      Jamie: Let's pause on 1. What Is Open Source? What should a learner take away from it?

      +

      Alex: Here is the plain-English version of 1. What Is Open Source? Open source software is software whose source code is publicly available. Put another way, anyone can read it, use it, and - in most cases - contribute to it.

      +

      Alex: The practical takeaway is this. 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.

      -

      Jamie: Let's pause on Deleting a branch. What should a learner take away from it?

      -

      Alex: This is where Deleting a branch becomes real: screen reader users (VoiceOver on macOS).

      -

      Alex: First, switch to a different branch first (you cannot delete the branch you are on). Then, press Ctrl+Shift+P, type "git delete branch". After that, select "Git: Delete Branch.". Finally, navigate the list to find the branch to delete, press Enter. It is a checklist, but a meaningful one: every item creates evidence that the next step is safe.

      -

      Jamie: What is the teaching move inside Creating a branch?

      -

      Alex: First, press Cmd+Shift+P to open the Command Palette. Then, type "git create branch" - VoiceOver announces filtered results. After that, press Return on "Git: Create Branch.". Finally, type the branch name in the input field. It is like walking a hallway with named doors: read the sign, enter the right room, then confirm where you landed.

      -

      Jamie: If someone only remembers one thing from Creating a branch, what should it be?

      -

      Alex: First, press Return to create and switch. The rhythm is simple: orient, act, verify, then continue.

      -

      Jamie: What is the teaching move inside Switching branches?

      -

      Alex: First, press Cmd+Shift+P, type "git checkout". Then, select "Git: Checkout to.". After that, use VO+Down Arrow to navigate the branch list. Finally, press Return to switch. The rhythm is simple: orient, act, verify, then continue.

      +

      Alex: Keep the teaching thread moving. This is where 2. Who Can Contribute? becomes real: contributors come from all backgrounds, skill levels, and countries. That matters in practice: 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. The workshop is closer to rehearsal than lecture. You hear the move, try the move, and then check what changed.

      +

      Jamie: Let's pause on 3. What Makes a Good First Contribution? What should a learner take away from it?

      +

      Alex: Start with 3. What Makes a Good First Contribution? There is something to understand, something to try, and something that proves the try worked.

      +

      Alex: The practical takeaway is this. 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.

      +

      Alex: Keep the teaching thread moving. The reason Signs a contribution is too large for a first attempt matters is that a well-executed small contribution is far more valuable than a large contribution that cannot be merged because it is out of scope.

      +

      Alex: The practical takeaway is this. 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.

      -

      Jamie: Let's pause on Getting the current branch name. What should a learner take away from it?

      -

      Alex: Start with Getting the current branch name: Create and switch branches without leaving your browser. The next useful detail is this: Manage branches from your terminal. Think of it like entering a new building: first you find the lobby, then the room, then the door you actually need.

      -

      Alex: First, press VO+M to move to the menu bar, then VO+Right Arrow to the status bar area. Then, or use the Command Palette: Cmd+Shift+P then type "Git: Show Git Output" - the output pane includes the current branch. After that, on the repository page, find the branch dropdown button (shows "main" by default) - it is above the file table. Finally, click or activate the dropdown. Think of it as a rail line: each stop confirms you are still on the right route before the next one.

      -

      Jamie: Before we leave Getting the current branch name, what is the practical point?

      -

      Alex: First, type a new branch name in the search field. Then, click "Create branch: your-branch-name from main" when it appears. After that, GitHub switches to the new branch immediately. Finally, any file edits in the browser will be on this branch. Treat it like a recipe: do not add the next ingredient until the previous one is actually in the bowl.

      -

      Alex: Treat examples as spoken recipes, not decorations. You may hear something like 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. 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'. Read the command, understand what it changes, then run it only when the repository state matches the lesson.

      -

      Jamie: Let's pause on 4. Staging Changes - Files, Lines, and Chunks. What should a learner take away from it?

      -

      Alex: Here is the plain-English version of 4. Staging Changes - Files, Lines, and Chunks. This lets you commit only part of your work, leaving the rest for a later commit.

      -

      Alex: First, stage the changes you want to include. Then, commit those staged changes. Treat it like a recipe: do not add the next ingredient until the previous one is actually in the bowl.

      -

      Jamie: Let's pause on Staging an Entire File. What should a learner take away from it?

      -

      Alex: This is where Staging an Entire File becomes real: low vision users (zoom, high contrast). That matters in practice: Screen reader users (NVDA / JAWS / VoiceOver).

      -

      Alex: The practical takeaway is this. 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.

      -

      Alex: First, open Source Control: Ctrl+Shift+G (Mac: Cmd+Shift+G). Then, hover over a file in the "Changes" list - a + icon appears to its right. After that, click the + to stage that file. Finally, or right-click a file → "Stage Changes". It is a checklist, but a meaningful one: every item creates evidence that the next step is safe.

      -

      Jamie: Before we leave Staging an Entire File, what is the practical point?

      -

      Alex: First, at high zoom, the + (stage), undo (discard), and open file icons may be small. Instead of hovering. Then, 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. After that, in high contrast themes, staged files show a distinct background or border in the Staged Changes section. Finally, navigate to the file in the "Changes" list. It is like walking a hallway with named doors: read the sign, enter the right room, then confirm where you landed.

      +

      Jamie: Let's pause on 4. Finding Something to Work On. What should a learner take away from it?

      +

      Alex: Start with 4. Finding Something to Work On: Most open source projects label issues that are suitable for new contributors. The next useful detail is this: How to search: On any GitHub repository, go to Issues → filter by label.

      +

      Alex: Keep the teaching thread moving. Start with Learning Cards: Finding Something to Work On. There is something to understand, something to try, and something that proves the try worked.

      +

      Alex: The practical takeaway is this. 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. 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.

      +

      Jamie: What is the pre-flight check here?

      +

      Alex: This is where 5. Reading an Issue Before You Start becomes real: before commenting "I'll take this" on an issue, ask yourself. That matters in practice: 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.

      +

      Alex: The practical takeaway is this. 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.

      -

      Jamie: Let's pause on Alternative (keyboard shortcut). What should a learner take away from it?

      -

      Alex: Start with Alternative (keyboard shortcut). There is something to understand, something to try, and something that proves the try worked.

      -

      Alex: The practical takeaway is this. Focus the file → press Space.

      -

      Alex: Keep the thread going. Start with Alternative (context menu). There is something to understand, something to try, and something that proves the try worked.

      -

      Alex: The practical takeaway is this. Focus the file → press Shift+F10 (Mac: Ctrl+Return) → select "Stage Changes".

      -

      Jamie: Let's pause on What happens. What should a learner take away from it?

      -

      Alex: Start with What happens. There is something to understand, something to try, and something that proves the try worked.

      -

      Alex: The practical takeaway is this. The file moves from "Changes" → "Staged Changes". A green "A" or "M" indicator appears.

      +

      Jamie: Let's pause on Tool Cards: Fork, Clone, and Contribute. What should a learner take away from it?

      +

      Alex: Start with Tool Cards: Fork, Clone, and Contribute. There is something to understand, something to try, and something that proves the try worked.

      +

      Alex: First, click Fork on the repository page, then Create fork. Then, edit files directly in your fork's web interface. After that, click Contribute Open pull request to submit back to the original. Finally, fork the repo on github.com first. It is like walking a hallway with named doors: read the sign, enter the right room, then confirm where you landed.

      +

      Jamie: Before we leave Tool Cards: Fork, Clone, and Contribute, what is the practical point?

      +

      Alex: First, navigate to your fork and press. to open in the web editor. Then, edit, commit, and create a PR from the Source Control panel. After that, fork on github.com, then clone your fork: Ctrl+Shift+P Git: Clone. Finally, create a branch, make edits, commit and push. The rhythm is simple: orient, act, verify, then continue.

      +

      Alex: Treat examples as spoken recipes, not decorations. You may hear something like 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. Read the command, understand what it changes, then run it only when the repository state matches the lesson.

      +

      Jamie: Let's pause on The Basic Workflow. What should a learner take away from it?

      +

      Alex: Start with The Basic Workflow. There is something to understand, something to try, and something that proves the try worked.

      +

      Alex: First, fork the repository - creates your own copy on GitHub. Then, clone your fork to your computer (or open a Codespace - see Appendix N). After that, create a branch - name it something descriptive: fix/broken-link-setup-guide. Finally, make your change - edit the file, save, verify. The rhythm is simple: orient, act, verify, then continue.

      +

      Jamie: Before we leave The Basic Workflow, what is the practical point?

      +

      Alex: First, commit with a clear message - "Fix broken link in setup-guide.md line 34". Then, push to your fork. After that, open a pull request from your branch to the original repository's default branch. Finally, respond to review feedback - maintainers may ask for changes; this is normal and not a rejection. Think of it as a rail line: each stop confirms you are still on the right route before the next one.

      +

      Alex: Keep the teaching thread moving. Start with Writing a Good PR Description: Example: Fixed a broken link on line 34 of setup-guide.md. The next useful detail is this: The link pointed to /docs/old-setup which no longer exists. Think of it like entering a new building: first you find the lobby, then the room, then the door you actually need.

      +

      Alex: The practical takeaway is this. What did you change? Why was the change needed? How did you verify it works?

      -

      Jamie: Let's pause on Staging Multiple Files at Once. What should a learner take away from it?

      -

      Alex: Here is the plain-English version of Staging Multiple Files at Once. All modified files move to "Staged Changes.".

      -

      Alex: First, ctrl+Shift+G (Mac: Cmd+Shift+G) to open Source Control. Then, navigate to the "Changes" section heading. After that, press Shift+F10 (Mac: Ctrl+Return) to open context menu on the section itself. Finally, select "Stage All Changes". Treat it like a recipe: do not add the next ingredient until the previous one is actually in the bowl.

      -

      Jamie: Let's pause on Staging Individual Lines or Chunks. What should a learner take away from it?

      -

      Alex: This is where Staging Individual Lines or Chunks becomes real: this is one of Git's most powerful features: You can stage only specific lines of a file, leaving other changes unstaged.

      -

      Jamie: Let's pause on Workflow. What should a learner take away from it?

      -

      Alex: Keep the learner anchored in Workflow. Result: Only those lines are staged. This is the part to say slowly: The rest of the file remains in "Changes.". A good GitHub workflow is like a well-run meeting: everyone knows the topic, the next action, and who has the floor.

      -

      Alex: First, open Source Control: Ctrl+Shift+G (Mac: Cmd+Shift+G). Then, navigate to a file in "Changes". After that, press Enter to open the diff view. Finally, the diff shows your changes side-by-side or inline. It is like walking a hallway with named doors: read the sign, enter the right room, then confirm where you landed.

      -

      Jamie: Before we leave Workflow, what is the practical point?

      -

      Alex: First, navigate to a changed line (use Arrow keys or F7 for next hunk). Then, press Shift+F10 (Mac: Ctrl+Return) to open context menu. After that, select "Stage Selected Lines". The rhythm is simple: orient, act, verify, then continue.

      +

      Jamie: How should someone ask for help in a way that gets them unstuck faster?

      +

      Alex: Here is the plain-English version of 7. Getting Help. It is always acceptable to ask a question on an issue or pull request. Put another way, 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.

      +

      Alex: The practical takeaway is this. 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.

      +

      Alex: Keep the teaching thread moving. This is where 8. After Your Contribution Is Merged becomes real: this matters for your GitHub profile. That matters in practice: 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.

      +

      Alex: The practical takeaway is this. 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.

      +

      Jamie: Let's pause on 9. Building a Contribution Habit. What should a learner take away from it?

      +

      Alex: Keep the learner anchored in 9. Building a Contribution Habit. The hardest part of open source contribution is starting. This is the part to say slowly: 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.

      -

      Jamie: Let's pause on Use case for this workshop. What should a learner take away from it?

      -

      Alex: The reason Use case for this workshop matters is that in the diff view, press Alt+H to see Accessible Help for diff-specific keyboard shortcuts. That gives the learner a simple foothold: web alternative (github.com) - editing files.

      -

      Alex: The practical takeaway is this. 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".

      -

      Alex: First, click the pencil icon on any file to open the web editor. Then, make your changes. After that, click "Commit changes" - GitHub creates the commit directly. Finally, choose to commit to the current branch or create a new branch and PR. The rhythm is simple: orient, act, verify, then continue.

      -

      Alex: Treat examples as spoken recipes, not decorations. You may hear something like 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. Read the command, understand what it changes, then run it only when the repository state matches the lesson.

      -

      Jamie: Let's pause on Reverse the process. What should a learner take away from it?

      -

      Alex: Start with Reverse the process. There is something to understand, something to try, and something that proves the try worked.

      -

      Alex: First, focus the file in "Staged Changes". Then, press Ctrl+Enter (Mac: Cmd+Enter) or Space. After that, file moves back to "Changes". Think of it as a rail line: each stop confirms you are still on the right route before the next one.

      -

      Jamie: Let's pause on Learning Cards: Staging Changes. What should a learner take away from it?

      -

      Alex: Start with Learning Cards: Staging Changes. There is something to understand, something to try, and something that proves the try worked.

      -

      Alex: The practical takeaway is this. 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. 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.

      +

      Alex: Keep the teaching thread moving. The reason Practical habits matters is that challenge Time: Complete Challenge 8: The Culture Layer in the Challenge Hub, then advance to Chapter 09: Labels, Milestones and Projects. That gives the learner a simple foothold: next: Chapter 09: Labels, Milestones, and Projects Back: Chapter 07: Merge Conflicts Related appendices: Appendix M: Accessibility Standards Appendix F: Git Security Appendix O: Branch Protection. The interface gets friendlier when it stops being a wall of controls and starts being a set of named places.

      +

      Alex: The practical takeaway is this. 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.

      -

      Jamie: Let's pause on Standard process. What should a learner take away from it?

      -

      Alex: Start with Standard process. There is something to understand, something to try, and something that proves the try worked.

      -

      Alex: First, open Source Control: Ctrl+Shift+G (Mac: Cmd+Shift+G). Then, stage changes (see Section 4). After that, focus the commit message input (usually Tab or Shift+Tab to reach it). Finally, type your commit message. It is a checklist, but a meaningful one: every item creates evidence that the next step is safe.

      -

      Jamie: Before we leave Standard process, what is the practical point?

      -

      Alex: First, press Ctrl+Enter (Mac: Cmd+Enter) to commit. It is like walking a hallway with named doors: read the sign, enter the right room, then confirm where you landed.

      -

      Jamie: Let's pause on Learning Cards: Committing. What should a learner take away from it?

      -

      Alex: Keep the learner anchored in Learning Cards: Committing. Low vision users (zoom, high contrast).

      -

      Alex: First, open Source Control (Ctrl+Shift+G). Then, stage your files (click the + icon next to each file, or click Stage All Changes above the Changes section header). After that, click in the "Message" text area at the top of the Source Control panel. Finally, type your commit message. It is like walking a hallway with named doors: read the sign, enter the right room, then confirm where you landed.

      -

      Jamie: Before we leave Learning Cards: Committing, what is the practical point?

      -

      Alex: First, click the Commit button (checkmark icon) or press Ctrl+Enter. Then, 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. After that, 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. Finally, 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. The rhythm is simple: orient, act, verify, then continue.

      -

      Alex: Here is the practical turn. Start with NVDA/JAWS. There is something to understand, something to try, and something that proves the try worked.

      -

      Alex: The practical takeaway is this. 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).

      +

      Jamie: What is the final checkpoint?

      +

      Alex: You should be able to point to the evidence, explain the action, and describe what you would do next if this were a real open source project. If you can teach the move back, you have learned it.

      +

      Jamie: And if they get stuck?

      +

      Alex: Read the latest message, not the loudest worry. Check the issue, the branch, the pull request, the status check, or the bot comment. Then ask for help with those facts in hand. That is how professionals collaborate.

      +
      +
      -

      Jamie: Let's pause on VoiceOver. What should a learner take away from it?

      -

      Alex: Start with VoiceOver. There is something to understand, something to try, and something that proves the try worked.

      -

      Alex: The practical takeaway is this. 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.

      -

      Alex: Keep the teaching thread moving. Here is the plain-English version of Writing Good Commit Messages. See Culture & Etiquette: Writing Good Commit Messages for format guidance. It is like learning a transit route. The names of the stops matter because they tell you whether you are still going the right direction.

      -

      Jamie: What should happen before anyone copies and runs it?

      -

      Alex: This is where Format becomes real: common types: feat:, fix:, docs:, style:, refactor:, test:, chore.

      -

      Alex: The practical takeaway is this. First line: type + colon + short summary (50 characters max). Blank line. Optional body: detailed explanation. Optional footer: "Fixes 123" to link to issue.

      -

      Alex: Treat examples as spoken recipes, not decorations. You may hear something like 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. Read the command, understand what it changes, then run it only when the repository state matches the lesson.

      +

      13. Episode 22: GitHub Flavored Markdown

      +

      Markdown syntax, GitHub extensions, and writing accessible documentation.

      +

      Based on: Appendix C: GitHub Flavored Markdown

      +

      Audio and transcript are being regenerated for this episode.

      +
      +Read Transcript - Episode 22: GitHub Flavored Markdown + +

      Transcript

      +

      Alex: This is Git Going with GitHub, episode 22: GitHub Flavored Markdown. I am Alex. By the end of this episode, GitHub Flavored Markdown should feel less like a wall of GitHub words and more like a set of moves you can trust.

      +

      Jamie: And I am Jamie. I am here for the practical questions: what should I listen for, what can go wrong, and what is the next calm move?

      -

      Alex: Keep the teaching thread moving. Start with What Happens After Commit. There is something to understand, something to try, and something that proves the try worked.

      -

      Alex: The practical takeaway is this. 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).

      -

      Jamie: Let's pause on 6. Push and Pull Operations. What should a learner take away from it?

      -

      Alex: The reason 6. Push and Pull Operations matters is that push sends your local commits to GitHub. That gives the learner a simple foothold: pull downloads new commits from GitHub to your local repository.

      -

      Jamie: Let's pause on After committing locally. What should a learner take away from it?

      -

      Alex: Start with After committing locally. There is something to understand, something to try, and something that proves the try worked.

      -

      Alex: First, open Source Control: Ctrl+Shift+G (Mac: Cmd+Shift+G). Then, look for the "Publish Branch" button (if this is a new branch) or "Sync Changes" button. After that, press Enter on that button. Think of it as a rail line: each stop confirms you are still on the right route before the next one.

      +

      Alex: Today we are working on this: Markdown syntax, GitHub extensions, and writing accessible documentation. I want the learner to leave with a mental map, not just a remembered path through buttons.

      +

      Jamie: So the goal is understanding first, then action, then confirmation.

      +

      Alex: Right. We are building a rhythm: orient yourself, take one intentional action, then verify what changed before moving on.

      -

      Jamie: Let's pause on Alternative: Command Palette. What should a learner take away from it?

      -

      Alex: Start with Alternative: Command Palette. There is something to understand, something to try, and something that proves the try worked.

      -

      Alex: First, ctrl+Shift+P (Mac: Cmd+Shift+P). Then, type "git push". After that, select "Git: Push". Finally, VS Code pushes your commits to GitHub. Treat it like a recipe: do not add the next ingredient until the previous one is actually in the bowl.

      -

      Jamie: Let's pause on Learning Cards: Push and Pull. What should a learner take away from it?

      -

      Alex: This is where Learning Cards: Push and Pull becomes real: low vision users (zoom, high contrast). That matters in practice: Screen reader users (NVDA / JAWS on Windows).

      -

      Alex: First, 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. Then, 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. After that, 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. Finally, 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. It is a checklist, but a meaningful one: every item creates evidence that the next step is safe.

      -

      Jamie: Let's pause on Pushing. What should a learner take away from it?

      -

      Alex: Start with Pushing. There is something to understand, something to try, and something that proves the try worked.

      -

      Alex: First, after committing, press Ctrl+Shift+P, type "git push", select "Git: Push". Then, NVDA/JAWS announces "Pushing." in the status bar. After that, on success, a notification appears: "Successfully pushed" - if using NVDA, check NVDA+N to read recent notifications. Finally, for a new branch (first push), use "Git: Publish Branch" instead - this sets up the upstream tracking. It is like walking a hallway with named doors: read the sign, enter the right room, then confirm where you landed.

      +

      Jamie: Okay, set the room for us. What are we walking into?

      +

      Alex: Start with From First Paragraph to Polished Repository - Everything You Need to Know: Whether you have never written a single line of Markdown or you already know the basics and want to master the GitHub-specific extensions, this guide takes you from zero to confident. The next useful detail is this: We start with what Markdown is and why it matters, walk through every foundational element with examples, and then cover the GitHub Flavored Markdown (GFM) features you will encounter in real repositories - alert blocks, Mermaid diagrams, math, footnotes, and.

      +

      Jamie: How would you walk the room through that step by step?

      +

      Alex: Start with Markdown Foundations. There is something to understand, something to try, and something that proves the try worked.

      +

      Alex: First, what Is Markdown? Then, where You Will Use Markdown in This Workshop. After that, how to Practice as You Read. Finally, paragraphs and Line Breaks. Treat it like a recipe: do not add the next ingredient until the previous one is actually in the bowl.

      +

      Jamie: What does the learner do first, second, and then after that?

      +

      Alex: First, headings. Then, emphasis - Bold, Italic, and Bold Italic. After that, strikethrough. Finally, lists - Ordered and Unordered. It is a checklist, but a meaningful one: every item creates evidence that the next step is safe.

      +

      Jamie: Turn that into a path someone can follow.

      +

      Alex: Start with GitHub Flavored Markdown (GFM). There is something to understand, something to try, and something that proves the try worked.

      +

      Alex: First, what Is GitHub Flavored Markdown? Then, alert and Callout Blocks. After that, collapsible Sections with Details and Summary. Finally, task List Checkboxes. It is a checklist, but a meaningful one: every item creates evidence that the next step is safe.

      +

      Jamie: What is the ordered workflow?

      +

      Alex: First, syntax Highlighting in Fenced Code Blocks. Then, mermaid Diagrams. After that, math Expressions with LaTeX. Finally, footnotes. It is like walking a hallway with named doors: read the sign, enter the right room, then confirm where you landed.

      -

      Jamie: Let's pause on Pulling. What should a learner take away from it?

      -

      Alex: Start with Pulling. There is something to understand, something to try, and something that proves the try worked.

      -

      Alex: First, press Ctrl+Shift+P, type "git pull", select "Git: Pull". Then, NVDA/JAWS announces "Pulling." then the status changes. After that, if there are conflicts, the Source Control panel shows a "Merge Changes" section - navigate there with Ctrl+Shift+G then Down Arrow. The rhythm is simple: orient, act, verify, then continue.

      -

      Jamie: Let's pause on Checking sync status. What should a learner take away from it?

      -

      Alex: Start with Checking sync status: Screen reader users (VoiceOver on macOS).

      -

      Alex: First, press Ctrl+Shift+P, type "Git: Show Git Output". Then, the output pane opens with push/pull log messages in plain text. After that, use Up/Down Arrow to read line by line. Think of it as a rail line: each stop confirms you are still on the right route before the next one.

      -

      Jamie: Before we leave Pushing, what is the practical point?

      -

      Alex: First, press Cmd+Shift+P, type "git push", select "Git: Push". Then, VoiceOver announces progress from the status bar. After that, on success, a notification toast appears - press VO+F3 to read the latest notification. Treat it like a recipe: do not add the next ingredient until the previous one is actually in the bowl.

      +

      Jamie: Give me the sequence, because order matters here.

      +

      Alex: Start with Putting It All Together. There is something to understand, something to try, and something that proves the try worked.

      +

      Alex: First, screen Reader Behavior Summary. Then, accessible Markdown Authoring Checklist. After that, common Mistakes and How to Fix Them. Finally, your First Real Markdown Document - Guided Exercise. It is like walking a hallway with named doors: read the sign, enter the right room, then confirm where you landed.

      +

      Jamie: Let's pause on Part 3 - Putting It All Together. What should a learner take away from it?

      +

      Alex: First, quick-Reference Card. The rhythm is simple: orient, act, verify, then continue.

      +

      Jamie: What would you say to someone who is already bracing for this to be too much?

      +

      Alex: Start with Learning Cards: Using This Markdown Reference. There is something to understand, something to try, and something that proves the try worked.

      +

      Alex: The parts worth keeping in working memory are these. Use heading navigation (H key) to jump between numbered sections -- each topic is an h2 heading. Every section shows raw Markdown first, then rendered output, then screen reader behavior notes. The Table of Contents at the top has anchor links -- activate any link to jump directly to that section. Code blocks show the raw Markdown to type -- increase zoom and the monospace font stays readable. Each section follows the same pattern: explanation, raw code, rendered result, and accessibility notes. Use Ctrl+F to search for a specific Markdown element (e.g., search "table" or "heading").

      +

      Alex: The useful habit is simple: orient first, act second, verify third. That pause before acting is part of the work.

      +

      Alex: That matters because of the next idea. Start with 1. What Is Markdown?: Markdown is a lightweight way to format plain text so it renders as rich, structured content - headings, bold text, links, lists, code blocks, tables, and more. The next useful detail is this: You write in a plain text file using simple punctuation characters, and a Markdown processor converts those characters into formatted output. Think of it like entering a new building: first you find the lobby, then the room, then the door you actually need.

      -

      Jamie: Before we leave Pulling, what is the practical point?

      -

      Alex: First, press Cmd+Shift+P, type "git pull", select "Git: Pull". Then, VoiceOver announces when the pull completes. After that, if conflicts exist, navigate to Source Control (Cmd+Shift+G) and review the Merge Changes section. It is a checklist, but a meaningful one: every item creates evidence that the next step is safe.

      -

      Jamie: How do you keep commands from becoming magic words?

      -

      Alex: Keep the learner anchored in Screen reader feedback. Git CLI alternative - push and pull. This is the part to say slowly: Web alternative (github.com) - push and pull. A good GitHub workflow is like a well-run meeting: everyone knows the topic, the next action, and who has the floor.

      -

      Alex: The practical takeaway is this. 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).

      -

      Alex: Treat examples as spoken recipes, not decorations. You may hear something like 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. Read the command, understand what it changes, then run it only when the repository state matches the lesson.

      -

      Jamie: Let's pause on What to do if push fails. What should a learner take away from it?

      -

      Alex: Start with What to do if push fails. There is something to understand, something to try, and something that proves the try worked.

      -

      Alex: The practical takeaway is this. 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). Error: "Rejected - non-fast-forward" → Someone else pushed changes; you need to pull first.

      +

      Jamie: If I am listening before the workshop starts, what should settle in my mind first?

      +

      Alex: Here is the plain-English version of A brief history. John Gruber created Markdown in 2004 with the goal of making a format that is "as easy to read and write as plain text." Since then, Markdown has become the default writing format.

      +

      Alex: Here is what that changes in practice. GitHub (README files, issues, pull requests, comments, wikis, discussions). Stack Overflow and many developer forums. Static site generators (Jekyll, Hugo, Gatsby). Note-taking apps (Obsidian, Notion, Bear). Documentation systems (MkDocs, Docusaurus, Read the Docs). Chat platforms (Slack, Discord, Microsoft Teams).

      +

      Alex: This is where the talk moves from concept to action. This is where Markdown versus HTML becomes real: markdown converts to HTML behind the scenes. That matters in practice: When you write bold, GitHub converts it to bold.

      +

      Jamie: What is the one idea that makes the next few steps less mysterious?

      +

      Alex: Keep the learner anchored in What gets rendered and what stays raw. When you view a.md file on GitHub, GitHub renders it automatically. This is the part to say slowly: When you edit that file, you see the raw Markdown.

      -

      Alex: Keep the teaching thread moving. Start with When to pull. There is something to understand, something to try, and something that proves the try worked.

      -

      Alex: The practical takeaway is this. Before you start work each day. When GitHub shows your branch is behind the remote. When preparing to merge a PR.

      -

      Jamie: Let's pause on How to pull. What should a learner take away from it?

      -

      Alex: Here is the plain-English version of How to pull. If there are conflicts: See Section 9.

      -

      Alex: First, ctrl+Shift+P (Mac: Cmd+Shift+P). Then, type "git pull". After that, select "Git: Pull". Finally, VS Code fetches and merges remote changes. Treat it like a recipe: do not add the next ingredient until the previous one is actually in the bowl.

      -

      Alex: Keep the teaching thread moving. Start with Auto-fetch setting. There is something to understand, something to try, and something that proves the try worked.

      -

      Alex: The practical takeaway is this. VS Code can check for remote changes automatically every few minutes. Enable: Settings (Ctrl+, - Mac: Cmd+,) → search "git autofetch" → set to true.

      +

      Alex: Before the learner moves on. The reason 2. Where You Will Use Markdown in This Workshop matters is that markdown is not just one tool in this workshop - it is the thread that connects everything you do. That gives the learner a simple foothold: here is every place you will write or read Markdown during the two days. The interface gets friendlier when it stops being a wall of controls and starts being a set of named places.

      +

      Jamie: How should they picture the shape of the workshop?

      +

      Alex: Start with Day 1 - GitHub Foundations (Browser): The following table lists every Day 1 activity where Markdown is used.

      +

      Alex: Hold that next to this. Here is the plain-English version of Day 2 - VS Code and Accessibility Agents. The following table lists every Day 2 activity where Markdown is used.

      -

      Jamie: Let's pause on Syncing Your Fork with the Upstream Repository. What should a learner take away from it?

      -

      Alex: Keep the learner anchored in 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. This is the part to say slowly: Keeping your fork current prevents merge conflicts and ensures you're working with the latest code.

      -

      Jamie: Let's pause on The GitHub "Sync fork" Button (Quickest Method). What should a learner take away from it?

      -

      Alex: The reason The GitHub "Sync fork" Button (Quickest Method) matters is that for straightforward updates, GitHub has a built-in sync button.

      -

      Alex: First, navigate to your fork on GitHub. Then, on the repository page, look for the "This branch is N commits behind owner/repo:main" notice. After that, activate the "Sync fork" button next to it. Finally, GitHub automatically merges upstream changes into your fork's default branch. The rhythm is simple: orient, act, verify, then continue.

      -

      Jamie: Before we leave The GitHub "Sync fork" Button (Quickest Method), what is the practical point?

      -

      Alex: First, then pull those changes to your local clone: Git: Pull from the Command Palette. Think of it as a rail line: each stop confirms you are still on the right route before the next one.

      -

      Jamie: Let's pause on Screen reader path. What should a learner take away from it?

      -

      Alex: Start with Screen reader path: Limitation: The GitHub sync button only syncs the default branch. The next useful detail is this: For other branches, use the git method below.

      +

      Jamie: Where do you want a learner to place their attention here?

      +

      Alex: This is where Learning Room connection becomes real: in the Learning Room repository, every challenge description, every welcome file, and every piece of documentation is Markdown. That matters in practice: When you fix a broken link in docs/welcome.md for Challenge 1, you are editing Markdown.

      +

      Alex: That connects to another useful point. Keep the learner anchored in 3. How to Practice as You Read. The best way to learn Markdown is to type it yourself. This is the part to say slowly: Here are three ways to practice as you read this guide. A good GitHub workflow is like a well-run meeting: everyone knows the topic, the next action, and who has the floor.

      +

      Alex: A solid pull request habit is to separate three questions: what changed, why it changed, and what still needs review. That keeps the conversation useful instead of noisy.

      +

      Jamie: Let's pause on Option 1 - GitHub Issue (recommended for Day 1). What should a learner take away from it?

      +

      Alex: The reason Option 1 - GitHub Issue (recommended for Day 1) matters is that the Write and Preview tabs are announced as tab buttons. That gives the learner a simple foothold: press Enter on "Preview" to switch.

      +

      Alex: First, go to any repository where you have write access (the Learning Room works). Then, click New Issue. After that, type Markdown in the issue body. Finally, click the Preview tab to see the rendered result. The rhythm is simple: orient, act, verify, then continue.

      +

      Jamie: Before we leave Option 1 - GitHub Issue (recommended for Day 1), what is the practical point?

      +

      Alex: First, switch back to Write to keep editing. Then, you do not need to submit the issue - the Preview tab is your sandbox. Think of it as a rail line: each stop confirms you are still on the right route before the next one.

      +

      Alex: A solid issue habit is to read the title, the body, and the timeline before acting. You are listening for the requested action, the missing evidence, and the person who needs a response.

      -

      Jamie: What should they understand before typing anything?

      -

      Alex: Here is the plain-English version of Adding the Upstream Remote (One-Time Setup). To sync locally using git, you first configure the upstream remote. Put another way, this only needs to be done once per clone. It is like learning a transit route. The names of the stops matter because they tell you whether you are still going the right direction.

      -

      Alex: Treat examples as spoken recipes, not decorations. You may hear something like 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. Read the command, understand what it changes, then run it only when the repository state matches the lesson.

      -

      Jamie: Let's pause on Example for Accessibility Agents. What should a learner take away from it?

      -

      Alex: Start with Example for Accessibility Agents. There is something to understand, something to try, and something that proves the try worked.

      -

      Alex: Treat examples as spoken recipes, not decorations. You may hear something like git remote add upstream https://github.com/community-access/accessibility-agents.git. Read the command, understand what it changes, then run it only when the repository state matches the lesson.

      -

      Jamie: Let's pause on Fetching and Merging Upstream Changes. What should a learner take away from it?

      -

      Alex: Keep the learner anchored in Fetching and Merging Upstream Changes. Once your upstream remote is configured.

      -

      Alex: Treat examples as spoken recipes, not decorations. You may hear something like 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. Read the command, understand what it changes, then run it only when the repository state matches the lesson.

      +

      Jamie: Let's pause on Option 2 - Any.md file in VS Code (recommended for Day 2). What should a learner take away from it?

      +

      Alex: Start with Option 2 - Any.md file in VS Code (recommended for Day 2). There is something to understand, something to try, and something that proves the try worked.

      +

      Alex: First, create a new file: Ctrl+N, then save it as practice.md. Then, type your Markdown in the editor. After that, press Ctrl+Shift+V to open the rendered Markdown preview in a new tab. Finally, the preview updates live as you type. Think of it as a rail line: each stop confirms you are still on the right route before the next one.

      +

      Jamie: Let's pause on Option 3 - GitHub Gist. What should a learner take away from it?

      +

      Alex: Start with Option 3 - GitHub Gist. There is something to understand, something to try, and something that proves the try worked.

      +

      Alex: First, go to gist.github.com. Then, name your file practice.md. After that, type Markdown in the content area. Finally, click Create secret gist (only you can see it). Treat it like a recipe: do not add the next ingredient until the previous one is actually in the bowl.

      +

      Jamie: Before we leave Option 3 - GitHub Gist, what is the practical point?

      +

      Alex: First, view the rendered result. It is a checklist, but a meaningful one: every item creates evidence that the next step is safe.

      +

      Alex: Keep the thread going. This is where 4. Paragraphs and Line Breaks becomes real: this is the most fundamental element in Markdown, and it trips up almost everyone at first. The workshop is closer to rehearsal than lecture. You hear the move, try the move, and then check what changed.

      -

      Jamie: Let's pause on When Conflicts Occur During Sync. What should a learner take away from it?

      -

      Alex: The reason When Conflicts Occur During Sync matters is that see also: Chapter 07: Merge Conflicts for a dedicated walkthrough of conflict resolution. That gives the learner a simple foothold: if you've made changes to the same files the upstream has changed, merge conflicts can occur during sync.

      -

      Alex: Keep the teaching thread moving. Start with 7. Discarding Changes: Discarding = permanently deleting your local edits. The next useful detail is this: The file reverts to the state of the last commit. Think of it like entering a new building: first you find the lobby, then the room, then the door you actually need.

      -

      Jamie: Let's pause on When to Discard. What should a learner take away from it?

      -

      Alex: Start with When to Discard. There is something to understand, something to try, and something that proves the try worked.

      -

      Alex: The practical takeaway is this. You made experimental changes and they didn't work. You want to start over from the last commit. You accidentally edited the wrong file.

      +

      Jamie: Give me the version that sounds like an instructor, not a manual.

      +

      Alex: Keep the learner anchored in Paragraphs. A paragraph is one or more lines of text separated by a blank line (an empty line with nothing on it). This is the part to say slowly: If you do not leave a blank line between two blocks of text, Markdown treats them as one continuous paragraph.

      +

      Alex: Another way to ground it. The reason Line breaks within a paragraph matters is that sometimes you want to go to a new line without starting a whole new paragraph - for example, in an address or a poem. That gives the learner a simple foothold: to create a line break (a in HTML), end a line with two or more spaces and then press Enter.

      +

      Jamie: Let's pause on Common mistake - no blank line between paragraphs. What should a learner take away from it?

      +

      Alex: Start with Common mistake - no blank line between paragraphs: What renders (wrong): Both lines merge into one paragraph. The next useful detail is this: Fix: Add a blank line between them.

      -

      Jamie: Let's pause on Single file. What should a learner take away from it?

      -

      Alex: Start with Single file. There is something to understand, something to try, and something that proves the try worked.

      -

      Alex: First, open Source Control: Ctrl+Shift+G. Then, navigate to the file in "Changes". After that, press Shift+F10 for context menu. Finally, select "Discard Changes". It is a checklist, but a meaningful one: every item creates evidence that the next step is safe.

      -

      Jamie: Before we leave Single file, what is the practical point?

      -

      Alex: First, confirm in the warning dialog (VS Code will ask "Are you sure?"). It is like walking a hallway with named doors: read the sign, enter the right room, then confirm where you landed.

      -

      Jamie: Let's pause on All changes. What should a learner take away from it?

      -

      Alex: Keep the learner anchored in All changes. Screen reader warning: VS Code shows a modal confirmation dialog. This is the part to say slowly: Navigate with Tab, select "Discard" or "Cancel" with Enter.

      -

      Alex: First, ctrl+Shift+G. Then, navigate to the "Changes" section heading. After that, shift+F10 for context menu. Finally, select "Discard All Changes". It is like walking a hallway with named doors: read the sign, enter the right room, then confirm where you landed.

      -

      Jamie: Before we leave All changes, what is the practical point?

      -

      Alex: First, confirm (this affects every modified file). The rhythm is simple: orient, act, verify, then continue.

      -

      Jamie: Let's pause on Learning Cards: Discarding Changes. What should a learner take away from it?

      -

      Alex: The reason Learning Cards: Discarding Changes matters is that low vision users (zoom, high contrast). That gives the learner a simple foothold: screen reader users (NVDA / JAWS on Windows). The interface gets friendlier when it stops being a wall of controls and starts being a set of named places.

      -

      Alex: First, 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.". Then, 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. After that, for "Discard All Changes", right-click the "Changes" section heading to get the context menu. Finally, 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"). The rhythm is simple: orient, act, verify, then continue.

      +

      Alex: This is the part worth saying out loud. Here is the plain-English version of 5. Headings. Headings create the structure of your document. Put another way, they are how screen readers navigate, how tables of contents are built, and how readers scan for the section they need. It is like learning a transit route. The names of the stops matter because they tell you whether you are still going the right direction.

      +

      Alex: A solid navigation habit is to prove where you are before activating controls. Headings, landmarks, and the address bar are not trivia; they are your map.

      +

      Jamie: Let's pause on Syntax. What should a learner take away from it?

      +

      Alex: This is where Syntax becomes real: add one to six characters at the start of a line, followed by a space, then the heading text. That matters in practice: The number of characters determines the heading level.

      +

      Jamie: Let's pause on Rules for accessible headings. What should a learner take away from it?

      +

      Alex: Keep the learner anchored in Rules for accessible headings. Screen readers let you navigate by heading level. This is the part to say slowly: In NVDA and JAWS, pressing H moves to the next heading.

      +

      Alex: First, one H1 per document. The heading is your document title. Every document gets exactly one. Then, never skip levels. Go from to, never from to. Skipping levels breaks the document outline for screen reader users who navigate by heading. After that, make headings descriptive. A heading of "Section 3" tells a screen reader user nothing. A heading of "Creating Your First Pull Request" tells them exactly what the section covers. Finally, do not use bold as a heading substitute. Writing My Section on its own line looks like a heading visually, but it is not a heading in the document structure. Screen reader users navigating by heading (H key in Browse Mode) will never find it. It is like walking a hallway with named doors: read the sign, enter the right room, then confirm where you landed.

      -

      Jamie: What is the teaching move inside Single file?

      -

      Alex: First, press Ctrl+Shift+G to open Source Control. Then, navigate to the file in the Changes section with Down Arrow. After that, press Shift+F10 to open the context menu. Finally, navigate to "Discard Changes" with Down Arrow, press Enter. Think of it as a rail line: each stop confirms you are still on the right route before the next one.

      -

      Jamie: If someone only remembers one thing from Single file, what should it be?

      -

      Alex: First, a confirmation dialog appears - NVDA announces "Are you sure you want to discard changes" or similar. Then, press Tab to navigate between "Discard" and "Cancel", press Enter on your choice. Treat it like a recipe: do not add the next ingredient until the previous one is actually in the bowl.

      -

      Jamie: Let's pause on All files. What should a learner take away from it?

      -

      Alex: Here is the plain-English version of All files. Screen reader users (VoiceOver on macOS). Put another way, discard changes from your terminal.

      -

      Alex: First, navigate to the "Changes" section heading (announced as "Changes, expanded, N items"). Then, press Shift+F10, select "Discard All Changes". After that, confirm in the dialog. Finally, press Cmd+Shift+G to open Source Control. Treat it like a recipe: do not add the next ingredient until the previous one is actually in the bowl.

      -

      Jamie: Before we leave All files, what is the practical point?

      -

      Alex: First, use VO+Arrow keys to navigate to the file. Then, press VO+Shift+M to open the context menu (or Ctrl+Return). After that, navigate to "Discard Changes", press VO+Space. Finally, in the confirmation dialog, use VO+Right Arrow to reach the buttons, VO+Space to activate. It is a checklist, but a meaningful one: every item creates evidence that the next step is safe.

      -

      Alex: Treat examples as spoken recipes, not decorations. You may hear something like 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. Read the command, understand what it changes, then run it only when the repository state matches the lesson.

      -

      Jamie: Let's pause on Safer Alternative: Stash Instead of Discard. What should a learner take away from it?

      -

      Alex: This is where Safer Alternative: Stash Instead of Discard becomes real: if you're not sure whether you'll need these changes later, use stash (Section 10) instead of discard. That matters in practice: Stash saves your changes temporarily without committing them.

      +

      Jamie: Let's pause on Alternative heading syntax (not recommended). What should a learner take away from it?

      +

      Alex: The reason Alternative heading syntax (not recommended) matters is that markdown also supports "setext" headings where you underline text with = or - characters. That gives the learner a simple foothold: this only works for levels 1 and 2, and it is harder to scan visually in raw Markdown.

      +

      Alex: Now bring the learner back to the room. Start with 6. Emphasis - Bold, Italic, and Bold Italic: Emphasis changes how text is read by screen readers - it is not just visual. The next useful detail is this: When text is bold or italic, well-configured screen readers can announce emphasis changes, giving the listener additional context about importance. Think of it like entering a new building: first you find the lobby, then the room, then the door you actually need.

      +

      Jamie: Let's pause on Bold. What should a learner take away from it?

      +

      Alex: Here is the plain-English version of Bold. Wrap text in two asterisks or two underscores on each side. Put another way, this is bold text using underscores.

      -

      Alex: Keep the teaching thread moving. Keep the learner anchored in 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 the part to say slowly: This is different from discarding changes - it permanently removes the file from the repository history going forward. A good GitHub workflow is like a well-run meeting: everyone knows the topic, the next action, and who has the floor.

      -

      Jamie: Let's pause on How to use. What should a learner take away from it?

      -

      Alex: The reason How to use matters is that the file is staged for deletion - you still need to commit to record the removal.

      -

      Alex: First, open the file you want to remove in the editor. Then, ctrl+Shift+P (Mac: Cmd+Shift+P). After that, type "Git: Delete". Finally, confirm the deletion. The rhythm is simple: orient, act, verify, then continue.

      -

      Alex: Keep the teaching thread moving. Start with When to use Git Delete vs. just deleting the file. There is something to understand, something to try, and something that proves the try worked.

      -

      Alex: The practical takeaway is this. 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.

      +

      Alex: The next layer is this. This is where Italic becomes real: wrap text in one asterisk or one underscore on each side. That matters in practice: This is italic text using asterisks.

      +

      Jamie: Let's pause on Bold and italic combined. What should a learner take away from it?

      +

      Alex: Keep the learner anchored in Bold and italic combined. Wrap text in three asterisks on each side.

      +

      Jamie: What decision is this helping them make?

      +

      Alex: The reason When to use emphasis matters is that the following table provides guidance on when to use each type of emphasis. That gives the learner a simple foothold: NVDA can announce emphasis changes if the user enables "Report font attributes" (under Speech settings). The interface gets friendlier when it stops being a wall of controls and starts being a set of named places.

      +

      Alex: Use the comparison to make a decision, not to recite a table. The main contrasts are: Key terms, important warnings, UI element names means "Click the Submit button". Book or document titles, introducing new terms, gentle emphasis means "See the Contributing Guide for details". Bold italic means Extremely rare - critical warnings only means " Do not force push to the main branch ".

      -

      Jamie: Let's pause on Learning Cards: Deleting a File from the Repository. What should a learner take away from it?

      -

      Alex: Here is the plain-English version of Learning Cards: Deleting a File from the Repository. Alternatively: Ctrl+Shift+P then "Git: Delete" removes the file and stages the deletion in one step. Put another way, low vision users (zoom, high contrast).

      -

      Alex: First, right-click the file in the Explorer panel (Ctrl+Shift+E). Then, select "Delete" to delete from your file system. After that, the file appears in Source Control (Ctrl+Shift+G) under Changes with a "D" (deleted) status. Finally, stage and commit the deletion to record it in Git. Treat it like a recipe: do not add the next ingredient until the previous one is actually in the bowl.

      -

      Jamie: Before we leave Learning Cards: Deleting a File from the Repository, what is the practical point?

      -

      Alex: First, 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. Then, 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. After that, stage and commit as normal. Finally, open the file you want to remove in the editor. It is a checklist, but a meaningful one: every item creates evidence that the next step is safe.

      -

      Alex: Treat examples as spoken recipes, not decorations. You may hear something like 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. Read the command, understand what it changes, then run it only when the repository state matches the lesson.

      -

      Alex: Keep the teaching thread moving. This is where 8. Timeline View - File History and Blame becomes real: the Timeline view shows the Git history of the currently open file: every commit that touched this file, who made it, and when. The workshop is closer to rehearsal than lecture. You hear the move, try the move, and then check what changed.

      -

      Jamie: Let's pause on Method 1: Explorer Sidebar. What should a learner take away from it?

      -

      Alex: Start with Method 1: Explorer Sidebar. There is something to understand, something to try, and something that proves the try worked.

      -

      Alex: First, open Explorer: Ctrl+Shift+E. Then, at the bottom of the Explorer, there's a "Timeline" section. After that, tab or Arrow to navigate into Timeline. Finally, the list shows all commits affecting the currently open file. It is like walking a hallway with named doors: read the sign, enter the right room, then confirm where you landed.

      +

      Jamie: Let's pause on Emphasis inside words. What should a learner take away from it?

      +

      Alex: Start with Emphasis inside words: Underscores do not (in most Markdown processors including GitHub). The next useful detail is this: Use asterisks when you need emphasis inside a word (rare, but it comes up in technical documentation).

      +

      Alex: Here is the practical turn. Here is the plain-English version of 7. Strikethrough. Strikethrough text shows deleted or outdated content with a line through it. Put another way, wrap text in two tildes on each side.

      +

      Jamie: Let's pause on 8. Lists - Ordered and Unordered. What should a learner take away from it?

      +

      Alex: This is where 8. Lists - Ordered and Unordered becomes real: lists are one of the most common elements in GitHub documentation. That matters in practice: Issue descriptions, PR checklists, README instructions, step-by-step guides - they all use lists.

      -

      Jamie: Let's pause on Method 2: Command Palette. What should a learner take away from it?

      -

      Alex: Start with Method 2: Command Palette. There is something to understand, something to try, and something that proves the try worked.

      -

      Alex: First, open a file in the editor. Then, ctrl+Shift+P. After that, type "timeline". Finally, select "View: Show Timeline". The rhythm is simple: orient, act, verify, then continue.

      -

      Jamie: Let's pause on What Timeline Shows. What should a learner take away from it?

      -

      Alex: Start with What Timeline Shows: Screen reader announcement: "docs: add Timeline Guide, Jeff, 2 days ago".

      -

      Alex: The practical takeaway is this. Commit message (first line). Author name. Relative time (example: "3 days ago" or "2 hours ago"). Commit hash (short form, like a3f2b9c).

      -

      Jamie: Let's pause on Viewing a Commit's Changes. What should a learner take away from it?

      -

      Alex: Here is the plain-English version of Viewing a Commit's Changes. This is incredibly useful for understanding. It is like learning a transit route. The names of the stops matter because they tell you whether you are still going the right direction.

      -

      Alex: The practical takeaway is this. When a particular line was added. Why a section was removed. What the file looked like at any point in history.

      -

      Alex: First, navigate to a commit in the Timeline list. Then, press Enter. After that, a diff view opens showing what changed in that specific commit. Treat it like a recipe: do not add the next ingredient until the previous one is actually in the bowl.

      +

      Alex: Keep the teaching thread moving. Keep the learner anchored in Unordered lists (bullet points). Start each line with a dash (-), asterisk ( ), or plus sign (+) followed by a space. This is the part to say slowly: They are the most common convention on GitHub and visually distinct from the asterisks used for bold and italic. A good GitHub workflow is like a well-run meeting: everyone knows the topic, the next action, and who has the floor.

      +

      Alex: For a learner, the useful signals are these. First item. Second item. Third item.

      +

      Jamie: Let's pause on Ordered lists (numbered). What should a learner take away from it?

      +

      Alex: The reason Ordered lists (numbered) matters is that start each line with a number followed by a period and a space.

      +

      Alex: First, clone the repository. Then, create a new branch. After that, make your changes. Finally, open a pull request. The rhythm is simple: orient, act, verify, then continue.

      +

      Alex: Keep the teaching thread moving. Start with A helpful trick - Markdown renumbers for you: Here is something that surprises most new users. The next useful detail is this: In Markdown, the actual numbers you type do not matter for the rendered output.

      -

      Jamie: Let's pause on Git Blame - Line-by-Line History. What should a learner take away from it?

      -

      Alex: This is where Git Blame - Line-by-Line History becomes real: Git Blame shows who last modified each line of the file.

      -

      Jamie: Let's pause on How to access. What should a learner take away from it?

      -

      Alex: Start with How to access. There is something to understand, something to try, and something that proves the try worked.

      -

      Alex: First, open a file in the editor. Then, ctrl+Shift+P. After that, type "git blame". Finally, select "Git: Toggle Blame". It is like walking a hallway with named doors: read the sign, enter the right room, then confirm where you landed.

      -

      Jamie: Let's pause on What appears. What should a learner take away from it?

      -

      Alex: Start with What appears. There is something to understand, something to try, and something that proves the try worked.

      -

      Alex: The practical takeaway is this. Inline annotations next to every line (visually). Hover over a line to see commit details.

      +

      Jamie: What does someone need before they touch the keyboard?

      +

      Alex: Here is the plain-English version of Starting an ordered list at a specific number. If you need a list to start at a number other than 1, use that number for the first item. Put another way, all subsequent items are numbered sequentially from there.

      +

      Alex: Keep the teaching thread moving. This is where 9. Nested Lists and Mixed Lists becomes real: lists can contain other lists, creating an indented hierarchy. That matters in practice: This is essential for complex instructions, outlines, and project structures. The workshop is closer to rehearsal than lecture. You hear the move, try the move, and then check what changed.

      +

      Jamie: What is the safe way to learn from that example?

      +

      Alex: Keep the learner anchored in Nesting unordered lists. Indent the nested items by two or four spaces (GitHub accepts either, but four is most reliable).

      +

      Alex: These are the details that keep the idea from floating away. Accessibility testing tools. Screen readers. NVDA (Windows, free). JAWS (Windows, commercial). VoiceOver (macOS and iOS, built-in). Browser extensions.

      +

      Alex: Treat examples as spoken recipes, not decorations. You may hear something like Accessibility testing tools; - Screen readers; - NVDA (Windows, free); - JAWS (Windows, commercial); - VoiceOver (macOS and iOS, built-in); - Browser extensions; - axe DevTools; - WAVE; - Documentation tools; - Markdown editors; - Static site generators. Read the command, understand what it changes, then run it only when the repository state matches the lesson.

      -

      Alex: Keep the teaching thread moving. Start with For screen reader users: Useful blame settings (add to.vscode/settings.json or user Settings). Think of it like entering a new building: first you find the lobby, then the room, then the door you actually need.

      -

      Alex: The practical takeaway is this. 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.

      -

      Jamie: Let's pause on Learning Cards: Timeline and History. What should a learner take away from it?

      -

      Alex: Here is the plain-English version of Learning Cards: Timeline and History. Low vision users (zoom, high contrast). Put another way, screen reader users (NVDA / JAWS on Windows).

      -

      Alex: First, 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. Then, 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. After that, 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. Finally, 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. Treat it like a recipe: do not add the next ingredient until the previous one is actually in the bowl.

      -

      Jamie: Let's pause on Opening Timeline. What should a learner take away from it?

      -

      Alex: Start with Opening Timeline. There is something to understand, something to try, and something that proves the try worked.

      -

      Alex: First, press Ctrl+Shift+E to open Explorer. Then, press Tab repeatedly or Down Arrow to navigate past the file tree to the "Timeline" section. After that, press Right Arrow to expand it if collapsed. Finally, navigate commit entries with Up/Down Arrow. It is a checklist, but a meaningful one: every item creates evidence that the next step is safe.

      -

      Jamie: Before we leave Opening Timeline, what is the practical point?

      -

      Alex: First, each entry is announced as: "commit message, author, time" (e.g., "docs: add Timeline Guide, Jeff, 2 days ago"). Then, press Enter on any entry to open its diff view. It is like walking a hallway with named doors: read the sign, enter the right room, then confirm where you landed.

      +

      Alex: Keep the teaching thread moving. The reason Nesting ordered lists matters is that the same indentation principle applies to numbered lists.

      +

      Jamie: Let's pause on Mixing ordered and unordered lists. What should a learner take away from it?

      +

      Alex: Start with Mixing ordered and unordered lists: You can nest an unordered list inside an ordered list and vice versa.

      +

      Jamie: How do you keep commands from becoming magic words?

      +

      Alex: Here is the plain-English version of Adding content inside list items. List items can contain paragraphs, code blocks, and other elements. Put another way, indent the content to align with the list item text (typically four spaces). It is like learning a transit route. The names of the stops matter because they tell you whether you are still going the right direction.

      +

      Alex: Treat examples as spoken recipes, not decorations. You may hear something like Clone the repository; Open your terminal and run the following command. Read the command, understand what it changes, then run it only when the repository state matches the lesson.

      -

      Jamie: Let's pause on Reading a diff with screen reader. What should a learner take away from it?

      -

      Alex: Start with Reading a diff with screen reader. There is something to understand, something to try, and something that proves the try worked.

      -

      Alex: First, in the diff view, press Alt+F2 to open the Accessible Diff Viewer. Then, the Accessible Diff Viewer presents changes as a text list: each line shows + (added), - (removed), or unchanged. After that, navigate with Up/Down Arrow to read each line. Finally, press Escape to close the Accessible Diff Viewer. It is like walking a hallway with named doors: read the sign, enter the right room, then confirm where you landed.

      -

      Jamie: Let's pause on Git Blame. What should a learner take away from it?

      -

      Alex: The reason Git Blame matters is that screen reader users (VoiceOver on macOS). The interface gets friendlier when it stops being a wall of controls and starts being a set of named places.

      -

      Alex: First, open a file, press Ctrl+Shift+P, type "Git: Toggle Blame". Then, blame annotations appear inline - NVDA reads them when navigating lines. After that, to reduce noise, disable blame (repeat the toggle command) and use Timeline instead. The rhythm is simple: orient, act, verify, then continue.

      -

      Jamie: What is the teaching move inside Opening Timeline?

      -

      Alex: First, press Cmd+Shift+E to open Explorer. Then, use VO+Down Arrow to navigate below the file tree to the Timeline section. After that, press VO+Space to expand if collapsed. Finally, navigate entries with VO+Down Arrow. Think of it as a rail line: each stop confirms you are still on the right route before the next one.

      -

      Jamie: If someone only remembers one thing from Opening Timeline, what should it be?

      -

      Alex: First, press VO+Space on a commit to open its diff. Treat it like a recipe: do not add the next ingredient until the previous one is actually in the bowl.

      +

      Jamie: Let's pause on 10. Links. What should a learner take away from it?

      +

      Alex: This is where 10. Links becomes real: links are how you connect documents, reference issues, point to external resources, and cite sources. That matters in practice: Getting links right is critical for accessibility - links with bad text are one of the most common accessibility failures in documentation.

      +

      Alex: Keep the teaching thread moving. Keep the learner anchored in Basic link syntax. Wrap the visible link text in square brackets, followed immediately by the URL in parentheses.

      +

      Jamie: Let's pause on Links with title text. What should a learner take away from it?

      +

      Alex: The reason Links with title text matters is that add a title in quotes after the URL. That gives the learner a simple foothold: the title appears as a tooltip on hover.

      -

      Jamie: Let's pause on Accessible Diff Viewer. What should a learner take away from it?

      -

      Alex: Here is the plain-English version of Accessible Diff Viewer. Screen reader advantage: git log --oneline and git blame produce clean, columnar text output. Put another way, read line by line with arrow keys in the terminal.

      -

      Alex: First, in any diff view, press Option+F2 to open the Accessible Diff Viewer. Then, read changes line by line with VO+Down Arrow. After that, press Escape to close. Treat it like a recipe: do not add the next ingredient until the previous one is actually in the bowl.

      -

      Alex: Treat examples as spoken recipes, not decorations. You may hear something like 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. 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. Read the command, understand what it changes, then run it only when the repository state matches the lesson.

      -

      Jamie: What should someone listen for when a lesson offers more than one tool path?

      -

      Alex: This is where 9. Resolving Merge Conflicts in VS Code becomes real: merge conflicts happen when two people edit the same lines of a file. That matters in practice: Git can't decide which version to keep, so it asks you to choose.

      -

      Alex: Keep the teaching thread moving. Keep the learner anchored in How VS Code Displays Conflicts. When you open a file with conflicts, you see something like. This is the part to say slowly: VS Code adds buttons above each conflict (visually). A good GitHub workflow is like a well-run meeting: everyone knows the topic, the next action, and who has the floor.

      -

      Alex: The practical takeaway is this. "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).

      +

      Alex: Keep the teaching thread moving. Start with Writing accessible link text: This is one of the most important accessibility skills in Markdown authoring. The next useful detail is this: Screen reader users often navigate by pulling up a list of all links on a page (NVDA: NVDA+F7 then select Links; JAWS: Insert+F7). Think of it like entering a new building: first you find the lobby, then the room, then the door you actually need.

      +

      Jamie: Let's pause on Reference-style links. What should a learner take away from it?

      +

      Alex: Here is the plain-English version of Reference-style links. For documents with many links, reference-style links keep the text readable by separating the URL from the prose. Put another way, you define the link target once at the bottom of the document.

      +

      Alex: Keep the teaching thread moving. This is where Relative links within a repository becomes real: when linking to other files in the same repository, use relative paths instead of full URLs. That matters in practice: This way, links work on any fork or branch.

      -

      Jamie: Let's pause on Screen Reader Workflow for Resolving Conflicts. What should a learner take away from it?

      -

      Alex: The reason Screen Reader Workflow for Resolving Conflicts matters is that the buttons are NOT accessible via keyboard.

      -

      Alex: The practical takeaway is this. <<<<<<< marks the start. ======= separates the two versions. marks the end. The section between <<<<<<< and ======= is your current branch (HEAD). The section between ======= and is the incoming branch (the branch you're merging). Delete the conflict markers ( ).

      -

      Alex: First, identify the conflict markers. Then, read both versions. After that, decide what to keep. Finally, stage the resolved file. The rhythm is simple: orient, act, verify, then continue.

      -

      Jamie: Before we leave Screen Reader Workflow for Resolving Conflicts, what is the practical point?

      -

      Alex: First, commit the merge. Think of it as a rail line: each stop confirms you are still on the right route before the next one.

      -

      Jamie: Let's pause on Using Accessible Diff for Conflict Review. What should a learner take away from it?

      -

      Alex: Start with Using Accessible Diff for Conflict Review: Better approach: Use the Accessible Diff Viewer (F7) to navigate conflict hunks systematically.

      -

      Alex: First, open the conflicted file. Then, press F7 to jump to the first conflict hunk. After that, press Alt+F2 to open Accessible View. Finally, read both versions clearly. Think of it as a rail line: each stop confirms you are still on the right route before the next one.

      -

      Jamie: Before we leave Using Accessible Diff for Conflict Review, what is the practical point?

      -

      Alex: First, press Escape to return to editor. Then, manually edit to resolve. After that, press F7 to jump to the next conflict. Finally, repeat until all conflicts resolved. Treat it like a recipe: do not add the next ingredient until the previous one is actually in the bowl.

      -

      Jamie: Let's pause on Aborting a Merge. What should a learner take away from it?

      -

      Alex: Here is the plain-English version of Aborting a Merge. If you want to cancel the merge and go back to before you started. Put another way, everything returns to the pre-merge state.

      -

      Alex: First, ctrl+Shift+P. Then, type "git abort". After that, select "Git: Abort Merge". Treat it like a recipe: do not add the next ingredient until the previous one is actually in the bowl.

      +

      Jamie: Let's pause on Email links. What should a learner take away from it?

      +

      Alex: Keep the learner anchored in Email links. The angle brackets tell Markdown to create a mailto: link.

      +

      Alex: Keep the teaching thread moving. The reason Autolinked URLs matters is that GitHub automatically converts full URLs in your text into clickable links, but always prefer explicit descriptive links in prose. That gives the learner a simple foothold: bare URLs should only appear in reference sections or code examples. The interface gets friendlier when it stops being a wall of controls and starts being a set of named places.

      +

      Jamie: Let's pause on Learning Cards: Links. What should a learner take away from it?

      +

      Alex: Start with Learning Cards: Links. There is something to understand, something to try, and something that proves the try worked.

      +

      Alex: A few details make that real. Pull up a links list (NVDA: NVDA+F7 then Links tab; JAWS: Insert+F7) to audit your document -- every link must make sense without its surrounding sentence. Reference-style links ([text][ref]) produce identical HTML to inline links -- screen readers announce them the same way, so choose whichever keeps your source readable. Relative links to other repo files (e.g., Setup) work on any fork or branch -- prefer them over full URLs for internal documentation. Links render as blue underlined text by default -- if your GitHub theme reduces underline visibility, rely on the color difference or hover state to identify links. Long URLs in link text are hard to read at high zoom; always use descriptive text like Contributing Guide instead of pasting the raw URL. The title attribute (text in quotes after the URL) appears as a tooltip on hover -- useful at high magnification but do not put essential information only there.

      -

      Alex: Keep the teaching thread moving. Start with Learning Cards: Resolving Merge Conflicts. There is something to understand, something to try, and something that proves the try worked.

      -

      Alex: The practical takeaway is this. 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. 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.

      -

      Jamie: Let's pause on 10. Stash Management. What should a learner take away from it?

      -

      Alex: Keep the learner anchored in 10. Stash Management. Stash temporarily saves your uncommitted changes so you can switch branches or pull updates without committing half-finished work.

      -

      Alex: Keep the teaching thread moving. Start with When to Use Stash. There is something to understand, something to try, and something that proves the try worked.

      -

      Alex: The practical takeaway is this. 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.

      +

      Alex: Keep the teaching thread moving. Here is the plain-English version of 11. Images. Images in Markdown use a syntax similar to links, with an exclamation mark (!) at the beginning.

      +

      Jamie: Before we leave Syntax, what is the practical point?

      +

      Alex: This is where Syntax becomes real: the text inside the square brackets is the alt text - the description that screen readers read aloud instead of displaying the image. That matters in practice: This is the single most important accessibility attribute for images.

      +

      Alex: Keep the teaching thread moving. Keep the learner anchored in Writing good alt text. The following table provides guidance on alt text for different types of images. A good GitHub workflow is like a well-run meeting: everyone knows the topic, the next action, and who has the floor.

      -

      Jamie: Let's pause on Method 1: Command Palette. What should a learner take away from it?

      -

      Alex: Start with Method 1: Command Palette. There is something to understand, something to try, and something that proves the try worked.

      -

      Alex: First, ctrl+Shift+P. Then, type "git stash". After that, select "Git: Stash". Finally, optionally type a stash message (helps you remember what's in it). Think of it as a rail line: each stop confirms you are still on the right route before the next one.

      -

      Alex: Keep the teaching thread moving. Start with What happens. There is something to understand, something to try, and something that proves the try worked.

      -

      Alex: The practical takeaway is this. 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.

      -

      Jamie: Let's pause on Command Palette. What should a learner take away from it?

      -

      Alex: Start with Command Palette. There is something to understand, something to try, and something that proves the try worked.

      -

      Alex: First, ctrl+Shift+P. Then, type "git stash list". After that, select "Git: Show Stash". It is a checklist, but a meaningful one: every item creates evidence that the next step is safe.

      +

      Jamie: Let's pause on Image with a link. What should a learner take away from it?

      +

      Alex: The reason Image with a link matters is that to make an image clickable, wrap the image syntax inside a link.

      +

      Alex: Keep the teaching thread moving. Start with When to use details blocks for complex images: If an image contains complex information (like an architecture diagram or a data visualization), provide a full text description in a collapsible block. The next useful detail is this: Screen readers announce images as "graphic" followed by the alt text.

      +

      Jamie: Let's pause on Learning Cards: Images. What should a learner take away from it?

      +

      Alex: Start with Learning Cards: Images. There is something to understand, something to try, and something that proves the try worked.

      +

      Alex: The room should hear these as checkpoints. Alt text is read aloud as the only representation of the image -- write it to answer "what information does this image convey?" not just "what does it look like?". For decorative images, use empty alt text ( ) so the screen reader skips them entirely rather than announcing the filename. Complex images (architecture diagrams, charts) need a full text description in a block below the image -- expand it to read the complete information. Images render at their original size by default -- use browser or VS Code zoom to enlarge them, and ensure alt text is present in case the image becomes too pixelated. Screenshots with small text are the hardest images to read at high magnification -- request that contributors use cropped, focused screenshots instead of full-screen captures. The alt text is invisible in the rendered view but visible in the raw Markdown source -- switch to the source view to verify alt text exists on all images.

      -

      Jamie: Let's pause on Alternative: Integrated Terminal. What should a learner take away from it?

      -

      Alex: Start with Alternative: Integrated Terminal. There is something to understand, something to try, and something that proves the try worked.

      -

      Alex: Treat examples as spoken recipes, not decorations. You may hear something like git stash list. Read the command, understand what it changes, then run it only when the repository state matches the lesson.

      -

      Jamie: Let's pause on To restore your stashed changes. What should a learner take away from it?

      -

      Alex: Start with To restore your stashed changes. There is something to understand, something to try, and something that proves the try worked.

      -

      Alex: First, ctrl+Shift+P. Then, type "git stash apply". After that, select "Git: Apply Latest Stash". The rhythm is simple: orient, act, verify, then continue.

      -

      Jamie: Let's pause on Or to apply a specific stash. What should a learner take away from it?

      -

      Alex: Start with Or to apply a specific stash. There is something to understand, something to try, and something that proves the try worked.

      -

      Alex: First, ctrl+Shift+P. Then, type "git stash pop". After that, select "Git: Pop Stash.". Finally, choose which stash from the list. Think of it as a rail line: each stop confirms you are still on the right route before the next one.

      +

      Alex: Keep the teaching thread moving. This is where 12. Blockquotes becomes real: blockquotes are used for callouts, important notes, cited text, and instructor guidance throughout this course. That matters in practice: Start each line with a character followed by a space. The workshop is closer to rehearsal than lecture. You hear the move, try the move, and then check what changed.

      +

      Jamie: Let's pause on Basic blockquote. What should a learner take away from it?

      +

      Alex: Keep the learner anchored in Basic blockquote. It is used to highlight important information or to quote someone else's text.

      +

      Alex: Keep the teaching thread moving. The reason Multi-paragraph blockquotes matters is that add a on the blank lines between paragraphs to keep them inside the blockquote.

      -

      Jamie: Let's pause on Difference between Apply and Pop. What should a learner take away from it?

      -

      Alex: Start with Difference between Apply and Pop. There is something to understand, something to try, and something that proves the try worked.

      -

      Alex: The practical takeaway is this. Apply: restores changes and keeps the stash (you can apply it again later). Pop: restores changes and deletes the stash.

      -

      Jamie: Let's pause on Dropping a Stash. What should a learner take away from it?

      -

      Alex: This is where Dropping a Stash becomes real: if you no longer need what's in a stash.

      -

      Alex: First, ctrl+Shift+P. Then, type "git stash drop". After that, select "Git: Drop Stash.". Finally, choose which stash to delete. It is a checklist, but a meaningful one: every item creates evidence that the next step is safe.

      -

      Jamie: Let's pause on Learning Cards: Stash Management. What should a learner take away from it?

      -

      Alex: Keep the learner anchored in Learning Cards: Stash Management. If the Stashes section is not visible, use the Command Palette: Ctrl+Shift+P then type "git stash" to access all stash commands. This is the part to say slowly: Low vision users (zoom, high contrast).

      -

      Alex: First, open Source Control: Ctrl+Shift+G. Then, in the Source Control panel, there may be a "Stashes" section below Staged Changes (visible when stashes exist). After that, click a stash to see what it contains. Finally, right-click a stash to Apply, Pop, or Drop it. It is like walking a hallway with named doors: read the sign, enter the right room, then confirm where you landed.

      -

      Jamie: Before we leave Learning Cards: Stash Management, what is the practical point?

      -

      Alex: First, 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. Then, 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. After that, after applying a stash, your files reappear in the Changes section of Source Control. Check the file count to confirm. The rhythm is simple: orient, act, verify, then continue.

      +

      Jamie: Let's pause on Blockquotes with other elements. What should a learner take away from it?

      +

      Alex: Start with Blockquotes with other elements: Blockquotes can contain any Markdown element - headings, lists, code, bold, links. The next useful detail is this: Screen readers announce the beginning and end of a blockquote.

      +

      Alex: Keep the teaching thread moving. Here is the plain-English version of How we use blockquotes in this course. Throughout this workshop, blockquotes serve specific purposes. It is like learning a transit route. The names of the stops matter because they tell you whether you are still going the right direction.

      +

      Alex: The practical anchors are these. Screen reader notes: Tips specific to assistive technology users. Learning Room connections: How the current topic connects to the practice repo. Important warnings: Critical information that could prevent errors. Instructor guidance: Notes from the facilitator about pacing or approach.

      +

      Jamie: Let's pause on 13. Inline Code and Code Blocks. What should a learner take away from it?

      +

      Alex: This is where 13. Inline Code and Code Blocks becomes real: code formatting is essential on GitHub. That matters in practice: the learner will use it for command-line instructions, file names, configuration values, keyboard shortcuts, and actual source code.

      -

      Jamie: Let's pause on Creating a stash. What should a learner take away from it?

      -

      Alex: Start with Creating a stash. There is something to understand, something to try, and something that proves the try worked.

      -

      Alex: First, press Ctrl+Shift+P, type "git stash". Then, select "Git: Stash" - NVDA announces the result. After that, an input appears asking for a stash message - type something descriptive (e.g., "WIP: documentation changes for Timeline section"). Finally, press Enter - your changes disappear from Source Control and are saved in the stash. The rhythm is simple: orient, act, verify, then continue.

      -

      Jamie: Before we leave Creating a stash, what is the practical point?

      -

      Alex: First, NVDA announces the Source Control panel update (file counts drop to 0). Think of it as a rail line: each stop confirms you are still on the right route before the next one.

      -

      Jamie: Let's pause on Applying a stash. What should a learner take away from it?

      -

      Alex: Start with Applying a stash. There is something to understand, something to try, and something that proves the try worked.

      -

      Alex: First, press Ctrl+Shift+P, type "git stash pop". Then, select "Git: Pop Stash.". After that, a list of stashes appears - navigate with Up/Down Arrow. Finally, each item is announced with the stash message you wrote. Think of it as a rail line: each stop confirms you are still on the right route before the next one.

      -

      Jamie: Before we leave Applying a stash, what is the practical point?

      -

      Alex: First, press Enter to apply and delete the stash. Then, your changes reappear in the Changes section. Treat it like a recipe: do not add the next ingredient until the previous one is actually in the bowl.

      -

      Jamie: Let's pause on Viewing stashes. What should a learner take away from it?

      -

      Alex: Here is the plain-English version of Viewing stashes. Screen reader users (VoiceOver on macOS). Put another way, GitHub.com does not have a stash feature.

      -

      Alex: First, press Ctrl+Shift+P, type "git stash list". Then, or in the terminal: type git stash list and read the output line by line. After that, press Cmd+Shift+P, type "git stash". Finally, select "Git: Stash" and provide a message. Treat it like a recipe: do not add the next ingredient until the previous one is actually in the bowl.

      -

      Jamie: Before we leave Viewing stashes, what is the practical point?

      -

      Alex: First, press Return. Then, to apply: Cmd+Shift+P, type "git stash pop", select from the list with VO+Down Arrow, press Return. After that, create a draft commit on a temporary branch. Finally, or use GitHub Codespaces (which runs a full VS Code environment in the browser and supports git stash in the terminal). It is a checklist, but a meaningful one: every item creates evidence that the next step is safe.

      -

      Alex: Treat examples as spoken recipes, not decorations. You may hear something like 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. Read the command, understand what it changes, then run it only when the repository state matches the lesson.

      +

      Jamie: What should happen before anyone copies and runs it?

      +

      Alex: Keep the learner anchored in Inline code. Wrap text in single backticks ( `) to format it as code within a sentence. This is the part to say slowly: Run git status to see which files have changed.

      +

      Alex: On the ground, that means a few things. Command names: git clone, npm install. File names: README.md, CONTRIBUTING.md. Keyboard shortcuts: Ctrl+C, Alt+Tab. Variable or function names: userName, getElementById().

      +

      Alex: Treat examples as spoken recipes, not decorations. You may hear something like Run git status to see which files have changed.; The configuration file is package.json.; Press Ctrl+Shift+P to open the Command Palette. Read the command, understand what it changes, then run it only when the repository state matches the lesson.

      +

      Jamie: Let's pause on Code blocks (fenced). What should a learner take away from it?

      +

      Alex: The reason Code blocks (fenced) matters is that for multi-line code, wrap it in triple backticks ( ` ) on their own lines. That gives the learner a simple foothold: all formatting is preserved exactly.

      +

      Alex: Keep the teaching thread moving. Start with Code blocks with syntax highlighting: Add a language identifier right after the opening triple backticks to enable syntax highlighting. The next useful detail is this: def greet(name: str) - str: """Return a greeting for the given name.""" return f"Hello, {name}! Think of it like entering a new building: first you find the lobby, then the room, then the door you actually need.

      -

      Jamie: What do you want them to do when the plan breaks?

      -

      Alex: This is where 10b. Emergency Recovery - git reflog becomes real: 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. That matters in practice: It is the most underused recovery tool in Git.

      -

      Jamie: What decision is this helping them make?

      -

      Alex: Start with When to Use Reflog. There is something to understand, something to try, and something that proves the try worked.

      -

      Alex: Use the comparison to make a decision, not to recite a table. The main contrasts are: Scenario means What happened means Reflog solution. Deleted a branch by mistake means git branch -D feature/x means Find the last commit SHA from reflog → recreate branch. git reset --hard lost commits means Moved HEAD to older commit means Find the SHA before the reset → reset back to it.

      -

      Jamie: Let's pause on Reading the Reflog in VS Code Terminal. What should a learner take away from it?

      -

      Alex: The reason Reading the Reflog in VS Code Terminal matters is that run this in the integrated terminal (Ctrl+Backtick). That gives the learner a simple foothold: the output is plain text - read line by line with ↓.

      -

      Alex: Treat examples as spoken recipes, not decorations. You may hear something like git reflog. Read the command, understand what it changes, then run it only when the repository state matches the lesson.

      +

      Jamie: Let's pause on Showing diffs in code blocks. What should a learner take away from it?

      +

      Alex: Here is the plain-English version of Showing diffs in code blocks. The diff language identifier highlights additions and removals. Put another way, + new line that was added unchanged context line.

      +

      Alex: That becomes easier when you listen for these cues. old line that was removed.

      +

      Alex: Keep the teaching thread moving. This is where Code blocks inside list items becomes real: indent the code block to align with the list item text.

      +

      Jamie: Let's pause on How to show literal backticks. What should a learner take away from it?

      +

      Alex: Keep the learner anchored in How to show literal backticks. If your code contains backticks, use more backticks for the fence. This is the part to say slowly: Use four backticks to wrap content that contains triple backticks.

      -

      Jamie: Let's pause on If you need to restore a commit that has been lost. What should a learner take away from it?

      -

      Alex: Start with If you need to restore a commit that has been lost: 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.

      -

      Alex: Treat examples as spoken recipes, not decorations. You may hear something like 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. Read the command, understand what it changes, then run it only when the repository state matches the lesson.

      -

      Jamie: Let's pause on Recovering a Deleted Branch. What should a learner take away from it?

      -

      Alex: Start with Recovering a Deleted Branch. There is something to understand, something to try, and something that proves the try worked.

      -

      Alex: Treat examples as spoken recipes, not decorations. You may hear something like 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. Read the command, understand what it changes, then run it only when the repository state matches the lesson.

      -

      Alex: Keep the teaching thread moving. This is where Why Reflog Is Local-Only becomes real: reflog records are stored in your local.git/ directory and are not pushed to GitHub. That matters in practice: 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. The workshop is closer to rehearsal than lecture. You hear the move, try the move, and then check what changed.

      +

      Alex: Keep the teaching thread moving. The reason 14. Horizontal Rules matters is that a horizontal rule creates a thematic break between sections - a visual line across the page. That gives the learner a simple foothold: use three or more dashes, asterisks, or underscores on a line by themselves. The interface gets friendlier when it stops being a wall of controls and starts being a set of named places.

      +

      Jamie: Let's pause on 15. Escaping Special Characters. What should a learner take away from it?

      +

      Alex: Start with 15. Escaping Special Characters: Many characters have special meaning in Markdown. The next useful detail is this: If you want to display them as literal characters instead, put a backslash () before them.

      +

      Alex: Keep the teaching thread moving. Here is the plain-English version of Characters that can be escaped. The following table lists every character that can be escaped in Markdown.

      -

      Jamie: How should someone ask for help in a way that gets them unstuck faster?

      -

      Alex: Start with Learning Cards: Emergency Recovery. There is something to understand, something to try, and something that proves the try worked.

      -

      Alex: The practical takeaway is this. 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. 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.

      -

      Alex: Keep the teaching thread moving. The reason 11. Alternative Git Interfaces matters is that VS Code's Source Control panel is one way to use Git. That gives the learner a simple foothold: these alternatives exist for different workflows.

      -

      Jamie: What stays the same when the tool changes?

      -

      Alex: Start with GitHub Desktop. There is something to understand, something to try, and something that proves the try worked.

      -

      Alex: The practical takeaway is this. Graphical Git client. Download: 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.

      +

      Jamie: Let's pause on Examples. What should a learner take away from it?

      +

      Alex: This is where Examples becomes real: this asterisk is literal: \ not bold\ This hash is literal: \ not a heading Show a pipe character: .

      +

      Alex: Keep the teaching thread moving. Keep the learner anchored in 16. Tables. Tables organize data into rows and columns. This is the part to say slowly: They are used extensively on GitHub for comparison charts, reference data, settings documentation, and checklists. A good GitHub workflow is like a well-run meeting: everyone knows the topic, the next action, and who has the floor.

      +

      Jamie: What should they understand before typing anything?

      +

      Alex: Start with Basic table syntax. There is something to understand, something to try, and something that proves the try worked.

      +

      Alex: Treat examples as spoken recipes, not decorations. You may hear something like Name Role Platform; --- --- ---; NVDA Screen reader Windows; JAWS Screen reader Windows; VoiceOver Screen reader macOS / iOS; TalkBack Screen reader Android. Read the command, understand what it changes, then run it only when the repository state matches the lesson.

      -

      Alex: Keep the teaching thread moving. Start with GitHub CLI (gh). There is something to understand, something to try, and something that proves the try worked.

      -

      Alex: The practical takeaway is this. 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).

      -

      Jamie: Let's pause on Common commands. What should a learner take away from it?

      -

      Alex: This is where Common commands becomes real: see Culture & Etiquette for more gh examples.

      -

      Alex: Treat examples as spoken recipes, not decorations. You may hear something like 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. Read the command, understand what it changes, then run it only when the repository state matches the lesson.

      -

      Alex: Keep the teaching thread moving. Start with Git CLI (Terminal). There is something to understand, something to try, and something that proves the try worked.

      -

      Alex: The practical takeaway is this. The standard Git command-line interface. Included with VS Code (integrated terminal: Ctrl+Backtick).

      +

      Alex: Keep the teaching thread moving. Start with How table syntax works. There is something to understand, something to try, and something that proves the try worked.

      +

      Alex: That shows up in the workshop in a few specific ways. The first row is always the header row. The second row contains dashes (---) that separate the header from the data. You need at least three dashes per column. Each subsequent row is a data row. Columns are separated by pipe characters ( ). Leading and trailing pipes are optional but recommended for readability.

      +

      Jamie: Let's pause on Column alignment. What should a learner take away from it?

      +

      Alex: Here is the plain-English version of Column alignment. Add colons (:) to the separator row to control text alignment.

      +

      Alex: The practical takeaway is this.:--- = left aligned (default).:---: = center aligned. ---: = right aligned.

      +

      Alex: Keep the teaching thread moving. This is where Formatting inside table cells becomes real: you can use inline formatting within table cells. The workshop is closer to rehearsal than lecture. You hear the move, try the move, and then check what changed.

      -

      Jamie: Before we leave Common commands, what is the practical point?

      -

      Alex: The reason Common commands matters is that terminal output is plain text - more predictable than GUI elements for some operations.

      -

      Alex: Treat examples as spoken recipes, not decorations. You may hear something like 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. Read the command, understand what it changes, then run it only when the repository state matches the lesson.

      -

      Jamie: Let's pause on Try It: Clone, Branch, Commit. What should a learner take away from it?

      -

      Alex: Start with Try It: Clone, Branch, Commit: Time: 5 minutes What you need: VS Code with Git configured. The next useful detail is this: Do the complete Git workflow once, start to finish. Think of it like entering a new building: first you find the lobby, then the room, then the door you actually need.

      -

      Alex: First, 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. Then, 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. After that, 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. Finally, stage - Press Ctrl+Shift+G to open Source Control. Navigate to your changed file and press Enter to stage it (or use the + button). Think of it as a rail line: each stop confirms you are still on the right route before the next one.

      -

      Jamie: Before we leave Try It: Clone, Branch, Commit, what is the practical point?

      -

      Alex: First, commit - Tab to the message input, type feat: add new thinking phrase, press Ctrl+Enter. Then, push - Press Ctrl+Shift+P → Git: Push. Treat it like a recipe: do not add the next ingredient until the previous one is actually in the bowl.

      +

      Jamie: Let's pause on Accessibility considerations for tables. What should a learner take away from it?

      +

      Alex: Keep the learner anchored in Accessibility considerations for tables. Screen readers navigate tables with Ctrl+Alt+Arrow keys (NVDA and JAWS). This is the part to say slowly: Ctrl+Alt+Right moves to the next column.

      +

      Alex: First, always include a description before the table. Add a one-sentence summary immediately above the table explaining what it contains. Screen reader users hear the table structure (rows and columns) but benefit from knowing what the table is about before entering. Then, keep tables simple. Tables with more than 5-6 columns become difficult to navigate with a screen reader. Consider splitting wide tables into multiple narrower tables. After that, use tables for data, not layout. If you are using a table just to arrange content side by side, use a list instead. Finally, make the header row descriptive. The header cell is announced before each data cell when navigating by column, so "Platform" is better than "Col 3". It is like walking a hallway with named doors: read the sign, enter the right room, then confirm where you landed.

      +

      Alex: Keep the teaching thread moving. The reason When not to use a table matters is that if your "table" has only two columns where the first is a label and the second is a value, consider using a definition-style list or bold labels instead. That gives the learner a simple foothold: this is often easier to read with a screen reader than a two-column table.

      +

      Jamie: Let's pause on Learning Cards: Tables. What should a learner take away from it?

      +

      Alex: Start with Learning Cards: Tables. There is something to understand, something to try, and something that proves the try worked.

      +

      Alex: The practical takeaway is this. Navigate tables with Ctrl+Alt+Arrow keys (NVDA/JAWS) -- Right moves to the next column, Down to the next row; the column header is announced each time you change columns. Enter table mode automatically when your screen reader encounters a table -- press T in browse mode to jump to the next table on the page. Before the table structure, listen for the description sentence the author should place above it -- this tells you what data the table contains before you enter cell-by-cell navigation. Wide tables (6+ columns) may require horizontal scrolling at high zoom -- if the table overflows, scroll right to see truncated columns or view the raw Markdown source instead. Column alignment (left, center, right) is controlled by colons in the separator row -- at high magnification, right-aligned numbers are easier to compare than left-aligned ones. If a table is hard to read at your zoom level, try narrowing the browser window -- GitHub will sometimes reflow content or add a horizontal scrollbar.

      -

      Jamie: What should people carry with them after this?

      -

      Alex: Carry the map. Know what page or tool you are in, know which action you are taking, and know what confirmation should follow. If the confirmation is missing, pause. That pause is not wasted time; it is professional judgment.

      -

      Jamie: That is a better way to say it than just follow the steps.

      -

      Alex: Right. Steps matter, but understanding wins. That is episode 12. Next in the series is episode 13, where we keep building the same contributor muscles.

      -
      - +

      Alex: Keep the teaching thread moving. Start with Learning Cards: GitHub Flavored Markdown. There is something to understand, something to try, and something that proves the try worked.

      +

      Alex: The practical takeaway is this. GFM features (sections 17-27) work only on GitHub -- your screen reader behavior notes are in each section. Alert blocks (section 18) render as blockquotes with a type prefix -- listen for "Note," "Warning," etc. Task list checkboxes (section 20) are announced as "checkbox checked" or "checkbox not checked". Alert blocks use color-coded left borders (blue for Note, yellow for Warning, red for Caution) -- the text label also identifies the type. Mermaid diagrams (section 22) are visual only on GitHub -- the raw code block is always readable. Use GitHub's Preview tab when writing to confirm your GFM renders correctly before submitting.

      +

      Jamie: Let's pause on 17. What Is GitHub Flavored Markdown? What should a learner take away from it?

      +

      Alex: This is where 17. What Is GitHub Flavored Markdown? becomes real: GitHub Flavored Markdown (GFM) is GitHub's own superset of standard Markdown. That matters in practice: It takes everything from the CommonMark specification (the modern standard for Markdown) and adds features specifically designed for software collaboration: tables, task lists, strikethrough, autolinked references, alert blocks, Mermaid diagrams, math.

      +

      Alex: Keep the teaching thread moving. Keep the learner anchored in Where GFM works. The following table shows where GFM is supported.

      -

      Episode 13: The GitHub Pull Requests Extension

      -

      Viewing, creating, reviewing, and merging PRs from inside VS Code.

      -

      Based on: Chapter 15: The GitHub Pull Requests Extension

      -

      Audio and transcript are being regenerated for this episode.

      -
      -Read Transcript - Episode 13: The GitHub Pull Requests Extension - -

      Transcript

      -

      Alex: Welcome back to Git Going with GitHub. This is episode 13: The GitHub Pull Requests Extension. I am Alex, and today we are turning The GitHub Pull Requests Extension from a list of instructions into a working mental model.

      -

      Jamie: And I am Jamie. I will stop us whenever the instructions sound simple on paper but might feel different with a keyboard and screen reader.

      +

      Jamie: Let's pause on 18. Alert and Callout Blocks. What should a learner take away from it?

      +

      Alex: The reason 18. Alert and Callout Blocks matters is that GitHub introduced alert blocks in 2023. That gives the learner a simple foothold: they render as colored, bordered callout boxes - great for emphasizing warnings, tips, or critical information.

      +

      Jamie: Let's pause on How to write them. What should a learner take away from it?

      +

      Alex: Start with How to write them. There is something to understand, something to try, and something that proves the try worked.

      +

      Alex: First, start a blockquote. Then, the first line must be exactly [!TYPE] where TYPE is one of: NOTE, TIP, IMPORTANT, WARNING, CAUTION. After that, all subsequent lines start with and a space, just like a regular blockquote. Finally, you can include any Markdown inside the alert: lists, code, links, bold. Think of it as a rail line: each stop confirms you are still on the right route before the next one.

      +

      Jamie: Let's pause on Choosing the right alert type. What should a learner take away from it?

      +

      Alex: Here is the plain-English version of Choosing the right alert type. The following table describes each alert type and when to use it.

      -

      Alex: Viewing, creating, reviewing, and merging PRs from inside VS Code. That is the surface description. Underneath it, we are building judgment: where to focus, what to ignore, and how to verify the result.

      -

      Jamie: So we are not using the audio as a shortcut around learning. We are using it to make the learning easier to enter.

      -

      Alex: Yes. A good audio lesson gives someone enough context to try the work with confidence, even before they open the written material.

      +

      Alex: Keep the teaching thread moving. This is where Screen Reader Behavior becomes real: alert blocks render as elements with an SVG icon and a strong heading.

      +

      Alex: The practical takeaway is this. NVDA/JAWS: announces blockquote role, then reads the type label ("Note", "Warning") then the content. VoiceOver: reads the type as bold text then the content. The colored icon is decorative (aria-hidden); it does not add information beyond the type label.

      +

      Jamie: Let's pause on 19. Collapsible Sections with Details and Summary. What should a learner take away from it?

      +

      Alex: Keep the learner anchored in 19. Collapsible Sections with Details and Summary. The and HTML elements create collapsible sections. This is the part to say slowly: They are one of the most useful tools for keeping long documents, issue reports, and PRs manageable - hiding optional content until the reader chooses to expand it.

      +

      Jamie: Let's pause on Important formatting rules. What should a learner take away from it?

      +

      Alex: Start with Important formatting rules. There is something to understand, something to try, and something that proves the try worked.

      +

      Alex: First, blank line after. Put a blank line between the closing tag and your Markdown content. Without it, Markdown formatting inside may not render. Then, blank line before. Same principle at the end. After that, the text should be descriptive - it is the only thing visible when collapsed. The rhythm is simple: orient, act, verify, then continue.

      -

      Jamie: Okay, set the room for us. What are we walking into?

      -

      Alex: Start with The GitHub Pull Requests Extension: See also: Appendix G: VS Code Reference for the complete list of GitHub Pull Requests extension keyboard shortcuts.

      -

      Alex: A solid pull request habit is to separate three questions: what changed, why it changed, and what still needs review. That keeps the conversation useful instead of noisy.

      -

      Alex: The next layer is this. Here is the plain-English version of 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,. Put another way, prerequisites: Working with Pull Requests, Git & Source Control in VS Code Mac keyboard shortcuts: Throughout this chapter, all Ctrl+ shortcuts use Cmd+ on Mac, and Alt+ shortcuts use Option+ on Mac. It is like learning a transit route. The names of the stops matter because they tell you whether you are still going the right direction.

      -

      Jamie: What should feel predictable before the first live session starts?

      -

      Alex: This is where Workshop Recommendation (Chapter 15, Part 1) becomes real: chapter 15, Part 1 introduces the GitHub Pull Requests extension for managing PRs directly from VS Code.

      -

      Alex: That shows up in the workshop in a few specific ways. There are 2 guided challenges. Automation check: none (extension installation and review state are account-local). The evidence is issue comment with confirmation of actions completed. The pattern is install, check out, review, comment.

      +

      Jamie: Zoom out for a second. What kind of journey is this?

      +

      Alex: Start with Real-world uses in this workshop: The following list describes common uses for collapsible sections.

      +

      Alex: The practical takeaway is this. Bug reports in issues: Collapse the full stack trace so the issue body stays readable. Long configuration blocks: Let readers expand the full YAML only if they need it. Exercise solutions: Collapse the answer so learners try the exercise first. Screen reader guidance blocks: Throughout this course, some sections collapse detailed assistive technology instructions so sighted users see a cleaner page while screen reader users can easily expand them. Meeting notes: Collapse detailed minutes while showing the summary.

      +

      Jamie: Let's pause on Details sections that start open. What should a learner take away from it?

      +

      Alex: Here is the plain-English version of Details sections that start open. Add the open attribute to have the section expanded by default.

      +

      Alex: Treat examples as spoken recipes, not decorations. You may hear something like; Currently known issues; - Checkbox toggle requires Focus Mode in NVDA; - Alert blocks do not render in email notifications. Read the command, understand what it changes, then run it only when the repository state matches the lesson.

      +

      Jamie: Let's pause on Screen Reader Behavior. What should a learner take away from it?

      +

      Alex: This is where Screen Reader Behavior becomes real: the element renders as a disclosure widget. That matters in practice: After expanding: The content is immediately readable.

      +

      Alex: The practical takeaway is this. NVDA: announces "button collapsed" for the - press Enter or Space to expand. JAWS: announces "collapsed" - press Enter on the summary to expand. VoiceOver: announces "collapsed, button" - press VO+Space to activate.

      -

      Jamie: Turn that into a path someone can follow.

      -

      Alex: Start with Chapter 15, Part 1 Practice Set. There is something to understand, something to try, and something that proves the try worked.

      -

      Alex: First, install the GitHub Pull Requests extension - add the extension to VS Code and sign in with your GitHub account. Then, check out a PR and post a review comment - download a PR branch locally, read the diff, and post one constructive review comment. It is like walking a hallway with named doors: read the sign, enter the right room, then confirm where you landed.

      -

      Jamie: What is the ordered workflow?

      -

      Alex: The reason Practice 15.1 Step-by-Step: Install the Extension matters is that install the GitHub Pull Requests and Issues extension and authenticate with your GitHub account. That gives the learner a simple foothold: VS Code desktop with your Learning Room repository open.

      -

      Alex: First, open the Extensions sidebar: Ctrl+Shift+X (Mac: Cmd+Shift+X). Then, your screen reader announces "Extensions: Marketplace." The search box has focus. After that, type GitHub Pull Requests in the search box and press Enter. Finally, navigate down the results list. Select GitHub Pull Requests (publisher: GitHub). The rhythm is simple: orient, act, verify, then continue.

      -

      Jamie: Give me the sequence, because order matters here.

      -

      Alex: First, activate the Install button. VS Code installs the extension and may show a notification. Then, after installation, VS Code prompts you to sign in. Activate Sign in to GitHub. After that, a browser window opens for GitHub OAuth. Approve the authorization and return to VS Code. Finally, verify: open the Explorer sidebar (Ctrl+Shift+E). You should now see a GitHub section in the sidebar showing Pull Requests and Issues. Think of it as a rail line: each stop confirms you are still on the right route before the next one.

      -

      Jamie: How would you walk the room through that step by step?

      -

      Alex: Start with Practice 15.2 Step-by-Step: Check Out a PR and Post a Comment: Check out someone else's PR branch locally, read the diff in VS Code, and post one constructive review comment. The next useful detail is this: VS Code with the GitHub Pull Requests extension installed. Think of it like entering a new building: first you find the lobby, then the room, then the door you actually need.

      -

      Alex: First, open the Command Palette: Ctrl+Shift+P (Mac: Cmd+Shift+P). Then, type GitHub Pull Requests: Focus on Pull Requests View and select it. The Pull Requests panel opens. After that, navigate the list of open PRs. Find one that is not yours (a classmate's PR from Chapter 6, 7, or 14). Finally, 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. Think of it as a rail line: each stop confirms you are still on the right route before the next one.

      -

      Jamie: What does the learner do first, second, and then after that?

      -

      Alex: First, open the Command Palette again and run GitHub Pull Requests: Open Changed Files. This shows the list of files the PR changed. Then, open one changed file. VS Code opens the Diff Editor showing old content on the left and new content on the right. After that, 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). Finally, find one specific thing to comment on: a typo, an unclear sentence, a missing step, or something the author did well. Treat it like a recipe: do not add the next ingredient until the previous one is actually in the bowl.

      +

      Alex: Keep the teaching thread moving. Start with Learning Cards: Collapsible Sections. There is something to understand, something to try, and something that proves the try worked.

      +

      Alex: The practical takeaway is this. The element is announced as a button -- press Enter or Space to toggle between collapsed and expanded; listen for "collapsed" or "expanded" state announcements. After expanding, the content is immediately available -- arrow down to read it; no page reload or focus change occurs. Nested blocks (details inside details) work but add complexity -- each level is an independent toggle button; keep nesting to one level deep for predictable navigation. The summary text is the only visible element when collapsed -- it appears as a disclosure triangle ( ) with text; zoom in to ensure the triangle and text are both readable. Expanded content appears inline below the summary -- at high zoom it flows naturally with the rest of the page content. The open attribute forces a section to start expanded -- useful when the content is important enough that most readers should see it by default.

      +

      Jamie: Let's pause on 20. Task List Checkboxes. What should a learner take away from it?

      +

      Alex: The reason 20. Task List Checkboxes matters is that task lists in GitHub issues and PRs render as real interactive checkboxes. That gives the learner a simple foothold: anyone with write access to the repository can check and uncheck them directly in the rendered view without editing the Markdown.

      +

      Jamie: What is the teaching move inside Syntax?

      +

      Alex: Start with Syntax. There is something to understand, something to try, and something that proves the try worked.

      +

      Alex: Treat examples as spoken recipes, not decorations. You may hear something like [x] Color contrast verified (4.5:1 minimum for body text); - [x] Keyboard navigation tested; - [ ] Screen reader tested with NVDA; - [ ] Screen reader tested with JAWS; - [ ] Screen reader tested with VoiceOver; - [ ] Alt text provided for all images; - [ ]. Read the command, understand what it changes, then run it only when the repository state matches the lesson.

      -

      Jamie: What should the learner prove to themselves after each small task?

      -

      Alex: Here is the plain-English version of Completing Chapter 15, Part 1: Submit Your Evidence. Open your assigned setup or review practice issue and post a completion comment. Put another way, close your Chapter 12 challenge issues when done.

      -

      Alex: The useful habit is simple: orient first, act second, verify third. That pause before acting is part of the work.

      -

      Alex: This is where the talk moves from concept to action. Start with Expected Outcomes. There is something to understand, something to try, and something that proves the try worked.

      -

      Alex: The room should hear these as checkpoints. 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.

      -

      Jamie: Let's pause on If You Get Stuck. What should a learner take away from it?

      -

      Alex: Keep the learner anchored in If You Get Stuck. Continue learning: The GitHub Skills course Review Pull Requests practices approving, requesting changes, and using suggestions in an interactive format. This is the part to say slowly: See Appendix Z for the full catalog.

      -

      Alex: First, extension does not install? Reload VS Code: Ctrl+Shift+P, then run Developer: Reload Window. Then, oAuth sign-in fails? Verify your GitHub account is active in the browser first, close VS Code, reopen, and retry. After that, pR list is empty? Switch to "All Open" view in the GitHub Pull Requests panel. Finally, checkout fails? Confirm you have write access to the repository. If not, use the read-only GitHub.com fallback. It is like walking a hallway with named doors: read the sign, enter the right room, then confirm where you landed.

      -

      Jamie: Before we leave If You Get Stuck, what is the practical point?

      -

      Alex: First, diff Editor is hard to navigate? Press F7 for the Accessible Diff Viewer mode, which is purpose-built for screen readers. Then, cannot find the Add Comment command? Use Command Palette and search for GitHub Pull Requests: Add Comment. After that, ask facilitator to help verify the GitHub PR panel and model one review comment. Finally, finished but not sure you did it right? Compare your work against the Challenge 11 reference solution. The rhythm is simple: orient, act, verify, then continue.

      +

      Jamie: Before we leave How to write them, what is the practical point?

      +

      Alex: First, start with a list item marker (-,, or +) and a space. Then, add [x] for a checked box or [ ] (with a space inside) for an unchecked box. After that, add a space, then the task description. Finally, the description should be meaningful - "Test NVDA" is better than "Item 3". Treat it like a recipe: do not add the next ingredient until the previous one is actually in the bowl.

      +

      Alex: Keep the teaching thread moving. Start with What makes task lists special on GitHub. There is something to understand, something to try, and something that proves the try worked.

      +

      Alex: The practical takeaway is this. Progress tracking: In issues, GitHub shows a progress bar: "2 of 7 tasks completed". Click to check: In the rendered view, users with triage or write permissions can click to toggle checkboxes without editing the comment. Linked issues: You can reference issues in a task: - [ ] Fix 42 - the task shows the issue title and its open/closed state. PR templates: Task lists in PR templates create checklists that authors fill out before requesting review.

      +

      Jamie: Let's pause on Example - pull request checklist. What should a learner take away from it?

      +

      Alex: Start with Example - pull request checklist. There is something to understand, something to try, and something that proves the try worked.

      +

      Alex: Treat examples as spoken recipes, not decorations. You may hear something like Pre-review checklist; - [x] Changes are limited to the files listed in the issue; - [x] All new images have descriptive alt text; - [ ] Screen reader tested the changes with NVDA; - [ ] No heading levels are skipped; - [ ] All links use descriptive text (not. Read the command, understand what it changes, then run it only when the repository state matches the lesson.

      -

      Alex: Before the learner moves on. The reason Learning Moment matters is that reviewing others' work refines your own standards and builds community trust. That gives the learner a simple foothold: the comment you just wrote helps another student learn - and you learn by articulating what makes documentation clear. The interface gets friendlier when it stops being a wall of controls and starts being a set of named places.

      -

      Jamie: Let's pause on Learning Pattern Used in This Chapter. What should a learner take away from it?

      -

      Alex: Start with Learning Pattern Used in This Chapter. There is something to understand, something to try, and something that proves the try worked.

      -

      Alex: First, install and configure the tool before starting the task. Then, practice on someone else's work first (reviewing is safer than authoring). After that, use accessibility tools (F7 Accessible Diff Viewer) to navigate efficiently. Finally, write specific, constructive feedback (not just "looks good"). Think of it as a rail line: each stop confirms you are still on the right route before the next one.

      -

      Alex: Hold that next to this. Here is the plain-English version of 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.

      +

      Alex: Keep the teaching thread moving. The reason Screen Reader Interaction matters is that in Browse Mode, checkboxes are read as checkbox, not checked or checkbox, checked.

      +

      Alex: The practical takeaway is this. NVDA: Press NVDA+Space to enter Focus Mode, then Tab to find the checkbox, then Space to toggle it. JAWS: Tab to the checkbox, then Space to toggle. VoiceOver: VO+Space on the checkbox element.

      +

      Jamie: Let's pause on 21. Syntax Highlighting in Fenced Code Blocks. What should a learner take away from it?

      +

      Alex: Start with 21. Syntax Highlighting in Fenced Code Blocks: We covered basic code blocks in Section 13. The next useful detail is this: This section covers the GitHub-specific syntax highlighting that makes code blocks more readable for sighted users.

      +

      Alex: Keep the teaching thread moving. Here is the plain-English version of How it works. Add a language identifier right after the opening triple backticks. Put another way, GitHub uses Linguist to apply syntax highlighting with appropriate colors for keywords, strings, comments, and other language constructs. It is like learning a transit route. The names of the stops matter because they tell you whether you are still going the right direction.

      -

      Jamie: Let's pause on Method 1: Extensions Sidebar. What should a learner take away from it?

      -

      Alex: Start with Method 1: Extensions Sidebar. There is something to understand, something to try, and something that proves the try worked.

      -

      Alex: First, open Extensions sidebar: Ctrl+Shift+X (Mac: Cmd+Shift+X). Then, type "GitHub Pull Requests" in the search box. After that, find "GitHub Pull Requests and Issues" (publisher: GitHub). Finally, navigate to the extension in the results list. It is a checklist, but a meaningful one: every item creates evidence that the next step is safe.

      -

      Jamie: Before we leave Method 1: Extensions Sidebar, what is the practical point?

      -

      Alex: First, press Enter to open the extension detail page. Then, tab to "Install" button → press Enter. It is like walking a hallway with named doors: read the sign, enter the right room, then confirm where you landed.

      -

      Jamie: Let's pause on Method 2: Command Palette. What should a learner take away from it?

      -

      Alex: Keep the learner anchored in Method 2: Command Palette. The Extensions sidebar is a tree view. This is the part to say slowly: Use Up/Down Arrow to navigate, Enter to open an extension's detail page. A good GitHub workflow is like a well-run meeting: everyone knows the topic, the next action, and who has the floor.

      -

      Alex: First, ctrl+Shift+P. Then, type "install extensions". After that, select "Extensions: Install Extensions". Finally, search for "GitHub Pull Requests". It is like walking a hallway with named doors: read the sign, enter the right room, then confirm where you landed.

      -

      Jamie: Before we leave Method 2: Command Palette, what is the practical point?

      -

      Alex: First, install "GitHub Pull Requests and Issues". The rhythm is simple: orient, act, verify, then continue.

      -

      Jamie: Let's pause on Signing In to GitHub. What should a learner take away from it?

      -

      Alex: The reason Signing In to GitHub matters is that after installation, VS Code prompts you to sign in.

      -

      Alex: First, a notification appears: "Sign in to GitHub to use Pull Requests". Then, navigate to the notification (Alt+N / Mac: Option+N, or status bar navigation). After that, select "Sign in". Finally, VS Code opens your browser for GitHub OAuth authentication. The rhythm is simple: orient, act, verify, then continue.

      -

      Jamie: Before we leave Signing In to GitHub, what is the practical point?

      -

      Alex: First, authorize VS Code in the browser. Then, return to VS Code - you're now signed in. Think of it as a rail line: each stop confirms you are still on the right route before the next one.

      +

      Jamie: Let's pause on Complete list of commonly used language identifiers. What should a learner take away from it?

      +

      Alex: This is where Complete list of commonly used language identifiers becomes real: the following table lists the language identifiers you are most likely to use. That matters in practice: If no language is specified, the code block renders as plain monospaced text with no highlighting.

      +

      Alex: Keep the teaching thread moving. Keep the learner anchored in Screen Reader Note. Syntax highlighting is visual only - screen readers read the code text without announcing color changes. This is the part to say slowly: The code block itself is announced as a code region.

      +

      Jamie: Let's pause on 22. Mermaid Diagrams. What should a learner take away from it?

      +

      Alex: The reason 22. Mermaid Diagrams matters is that GitHub renders Mermaid.js diagrams inline when you use a mermaid fenced code block. That gives the learner a simple foothold: they are common in READMEs, PRs, and documentation to illustrate architecture, flows, and relationships.

      -

      Alex: Here is the practical turn. Start with Verify sign-in. There is something to understand, something to try, and something that proves the try worked.

      -

      Alex: On the ground, that means a few things. 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.

      -

      Jamie: What would you say to someone who is already bracing for this to be too much?

      -

      Alex: Start with What the Extension Adds. There is something to understand, something to try, and something that proves the try worked.

      -

      Alex: Here is what that changes in practice. 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.

      -

      Alex: Keep the thread going. Start with Learning Cards: Installing the PR Extension. There is something to understand, something to try, and something that proves the try worked.

      -

      Alex: These are the details that keep the idea from floating away. 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". 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.

      +

      Alex: Keep the teaching thread moving. Start with Syntax: flowchart LR A[Fork repo] -- B[Clone locally] B -- C[Create branch] C -- D[Make changes] D -- E[Push branch] E -- F[Open PR] F -- G{Review passed?} G -- Yes -- H[Merge] G -- No -- D. Think of it like entering a new building: first you find the lobby, then the room, then the door you actually need.

      +

      Jamie: Let's pause on Common diagram types. What should a learner take away from it?

      +

      Alex: Here is the plain-English version of Common diagram types. The following table lists the Mermaid diagram types you are most likely to encounter on GitHub.

      +

      Alex: Keep the teaching thread moving. This is where Accessibility limitation - critical becomes real: mermaid diagrams render as SVG images. That matters in practice: GitHub does not auto-generate alt text for them.

      -

      Jamie: Let's pause on Method 1: Activity Bar. What should a learner take away from it?

      -

      Alex: Keep the learner anchored in Method 1: Activity Bar. Click the GitHub logo icon in the Activity Bar (the vertical strip of icons on the far left). This is the part to say slowly: The GitHub Pull Requests panel opens.

      -

      Alex: That becomes easier when you listen for these cues. "Pull Requests". "Issues".

      -

      Alex: First, the Activity Bar is not always reachable by Tab from the editor. Then, use Ctrl+Shift+P (Mac: Cmd+Shift+P) → type "GitHub Pull Requests: View Pull Request" or "Focus on Pull Requests View" → press Enter. After that, alternatively press Ctrl+Shift+G (Mac: Cmd+Shift+G) to open Source Control, then Tab until you reach the Activity Bar icon strip. Finally, navigate to the repository on GitHub.com. It is like walking a hallway with named doors: read the sign, enter the right room, then confirm where you landed.

      -

      Jamie: Before we leave Method 1: Activity Bar, what is the practical point?

      -

      Alex: First, click the Pull requests tab. Then, click any PR title to view its conversation, commits, and changed files. After that, use the Files changed tab to review diffs. The rhythm is simple: orient, act, verify, then continue.

      -

      Alex: Treat examples as spoken recipes, not decorations. You may hear something like 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". Read the command, understand what it changes, then run it only when the repository state matches the lesson.

      -

      Jamie: Let's pause on Method 2: Explorer Section. What should a learner take away from it?

      -

      Alex: Start with Method 2: Explorer Section. There is something to understand, something to try, and something that proves the try worked.

      -

      Alex: First, open Explorer: Ctrl+Shift+E (Mac: Cmd+Shift+E). Then, navigate with Arrow keys to find the "GitHub Pull Requests" section. After that, expand it with Right Arrow. The rhythm is simple: orient, act, verify, then continue.

      -

      Jamie: What is the one idea that makes the next few steps less mysterious?

      -

      Alex: Start with Description: The GitHub Pull Requests panel has two top-level sections. The next useful detail is this: "My Pull Requests" contains four filters: Assigned to Me, Created by Me, Waiting for my Review, and All Open.

      +

      Jamie: Let's pause on How to make Mermaid diagrams accessible. What should a learner take away from it?

      +

      Alex: Keep the learner anchored in How to make Mermaid diagrams accessible. Example - accessible Mermaid usage. This is the part to say slowly: flowchart LR Fork -- Clone -- Branch -- Commit -- Push -- PR -- Review -- Merge.

      +

      Alex: First, write a text description before the diagram that conveys all the same information. Then, optionally, duplicate the information as a numbered list or table. After that, consider wrapping the Mermaid source in a block if the text description is sufficient. It is like walking a hallway with named doors: read the sign, enter the right room, then confirm where you landed.

      +

      Alex: Keep the teaching thread moving. The reason 23. Math Expressions with LaTeX matters is that GitHub renders LaTeX math expressions using MathJax. That gives the learner a simple foothold: this is common in data science, research, and algorithm documentation. The interface gets friendlier when it stops being a wall of controls and starts being a set of named places.

      +

      Jamie: Let's pause on Inline math. What should a learner take away from it?

      +

      Alex: Start with Inline math: Use single $ delimiters for math within a sentence. The next useful detail is this: Renders as: The formula is $e = mc^2$ where $c$ is the speed of light.

      -

      Alex: This is the part worth saying out loud. Here is the plain-English version of Screen reader announcement example. "Pull Request 42: Add Timeline Guide, opened by jeffb, 2 days ago, 3 files changed". It is like learning a transit route. The names of the stops matter because they tell you whether you are still going the right direction.

      -

      Alex: A solid navigation habit is to prove where you are before activating controls. Headings, landmarks, and the address bar are not trivia; they are your map.

      -

      Jamie: Give me the version that sounds like an instructor, not a manual.

      -

      Alex: Start with By status. There is something to understand, something to try, and something that proves the try worked.

      -

      Alex: For a learner, the useful signals are these. "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.

      -

      Alex: That connects to another useful point. Keep the learner anchored in By repository. The tree organizes PRs by repository.

      +

      Alex: Keep the teaching thread moving. Here is the plain-English version of Block math. Use $$ delimiters for display-style (centered, larger) math on their own lines.

      +

      Jamie: Let's pause on Common LaTeX patterns. What should a learner take away from it?

      +

      Alex: This is where Common LaTeX patterns becomes real: the following table shows some LaTeX patterns you might encounter.

      +

      Alex: Keep the teaching thread moving. Keep the learner anchored in Screen Reader Note. Math expressions rendered by MathJax include aria-label attributes with the spoken form of the equation. This is the part to say slowly: Screen readers should announce the math correctly, but accuracy varies. A good GitHub workflow is like a well-run meeting: everyone knows the topic, the next action, and who has the floor.

      +

      Alex: The practical takeaway is this. NVDA with Firefox or Chrome: reads MathML fairly well. JAWS: reads the aria-label text. VoiceOver: reads the aria-label text.

      -

      Jamie: Let's pause on Viewing PR Details. What should a learner take away from it?

      -

      Alex: The reason Viewing PR Details matters is that a PR detail view opens in the editor area showing.

      -

      Alex: The parts worth keeping in working memory are these. 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).

      -

      Alex: First, navigate to a PR in the tree. Then, press Enter. The rhythm is simple: orient, act, verify, then continue.

      -

      Alex: Now bring the learner back to the room. Start with Screen reader experience. There is something to understand, something to try, and something that proves the try worked.

      -

      Alex: A few details make that real. 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.

      -

      Jamie: Where do you want a learner to place their attention here?

      -

      Alex: Here is the plain-English version of 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.

      +

      Jamie: Let's pause on 24. Footnotes. What should a learner take away from it?

      +

      Alex: The reason 24. Footnotes matters is that GitHub supports Markdown footnotes, which render as superscript numbers that link to references at the bottom of the document. That gives the learner a simple foothold: they are useful for citations, additional context, and references that would interrupt the flow of the main text.

      +

      Jamie: Let's pause on How they work. What should a learner take away from it?

      +

      Alex: Start with How they work. There is something to understand, something to try, and something that proves the try worked.

      +

      Alex: First, in your text, add [^identifier] where you want the footnote reference to appear. Then, anywhere in the document (typically at the bottom), define the footnote with [^identifier]: Your footnote text. After that, GitHub renders the reference as a superscript number that links to the definition. Finally, the definition includes a back-link that returns to the reference location. Think of it as a rail line: each stop confirms you are still on the right route before the next one.

      +

      Jamie: Let's pause on Footnote identifiers. What should a learner take away from it?

      +

      Alex: Start with Footnote identifiers. There is something to understand, something to try, and something that proves the try worked.

      +

      Alex: The practical takeaway is this. You can use numbers: [^1], [^2], [^3]. You can use descriptive names: [^webaim-survey], [^wcag-reference]. Descriptive names make the raw Markdown more readable but render as sequential numbers.

      -

      Alex: That matters because of the next idea. Start with Why Check Out a PR. There is something to understand, something to try, and something that proves the try worked.

      -

      Alex: The practical anchors are these. 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.

      -

      Jamie: Let's pause on Method 1: From the PR Detail View. What should a learner take away from it?

      -

      Alex: Start with Method 1: From the PR Detail View. There is something to understand, something to try, and something that proves the try worked.

      -

      Alex: The practical takeaway is this. Downloads the branch. Switches your local repository to that branch. Opens the changed files in the editor.

      -

      Alex: First, open a PR (see Section 2). Then, in the PR detail view, navigate to "Checkout" button. After that, press Enter. It is like walking a hallway with named doors: read the sign, enter the right room, then confirm where you landed.

      -

      Jamie: Let's pause on Method 2: From the PR Tree. What should a learner take away from it?

      -

      Alex: Start with Method 2: From the PR Tree. There is something to understand, something to try, and something that proves the try worked.

      -

      Alex: First, navigate to the PR in the GitHub Pull Requests tree. Then, press Shift+F10 (Mac: Ctrl+Return) to open context menu. After that, select "Checkout Pull Request". The rhythm is simple: orient, act, verify, then continue.

      +

      Alex: Keep the teaching thread moving. This is where Multi-line footnotes becomes real: indent continuation lines with two spaces. The workshop is closer to rehearsal than lecture. You hear the move, try the move, and then check what changed.

      +

      Jamie: Before we leave Screen Reader Behavior, what is the practical point?

      +

      Alex: Start with Screen Reader Behavior. There is something to understand, something to try, and something that proves the try worked.

      +

      Alex: The practical takeaway is this. The footnote reference is a link ( element) announcing its number. NVDA: "superscript, 1, link". JAWS: "link, 1". VoiceOver: "link, footnote 1". The back-link at the definition reads "return to footnote reference". Activating the footnote link jumps focus to the definition; activating the back-link returns focus to the original location.

      +

      Alex: Keep the teaching thread moving. The reason 25. Linked Heading Anchors and Tables of Contents matters is that every heading in a GitHub Markdown file automatically gets an anchor ID. That gives the learner a simple foothold: you can link to any heading from anywhere - within the same document, from another file, or from an issue or PR.

      -

      Jamie: Let's pause on Method 3: Command Palette. What should a learner take away from it?

      -

      Alex: Start with Method 3: Command Palette: After checkout, the bottom-left status bar shows the branch name (example: "jeffb/add-timeline-guide"). The next useful detail is this: Your local files now match that branch.

      -

      Alex: First, ctrl+Shift+P (Mac: Cmd+Shift+P). Then, type "GitHub Pull Requests: Checkout". After that, select "GitHub Pull Requests: Checkout Pull Request". Finally, choose the PR from the list. Think of it as a rail line: each stop confirms you are still on the right route before the next one.

      -

      Jamie: Let's pause on Returning to Your Original Branch. What should a learner take away from it?

      -

      Alex: Start with Returning to Your Original Branch. There is something to understand, something to try, and something that proves the try worked.

      -

      Alex: First, ctrl+Shift+P (Mac: Cmd+Shift+P). Then, type "git checkout". After that, select "Git: Checkout to.". Finally, choose your original branch (usually main or your feature branch). Treat it like a recipe: do not add the next ingredient until the previous one is actually in the bowl.

      -

      Alex: A solid Git habit is to know which branch you are on, what changed, and what confirmation you expect before you run the next command.

      -

      Jamie: If I am listening before the workshop starts, what should settle in my mind first?

      -

      Alex: Start with Learning Cards: Checking Out a PR. There is something to understand, something to try, and something that proves the try worked.

      -

      Alex: The practical takeaway is this. 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. 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.

      +

      Jamie: Let's pause on How GitHub generates anchor IDs. What should a learner take away from it?

      +

      Alex: Start with How GitHub generates anchor IDs: GitHub converts the heading text to an anchor ID. The next useful detail is this: The following table shows example headings and their generated anchors.

      +

      Alex: First, converting to lowercase. Then, replacing spaces with hyphens. After that, removing most punctuation (except hyphens). Finally, removing leading and trailing whitespace. Think of it as a rail line: each stop confirms you are still on the right route before the next one.

      +

      Alex: Keep the teaching thread moving. Here is the plain-English version of Building a table of contents. You can build a manual table of contents using heading anchor links. It is like learning a transit route. The names of the stops matter because they tell you whether you are still going the right direction.

      +

      Jamie: Let's pause on Duplicate headings. What should a learner take away from it?

      +

      Alex: This is where Duplicate headings becomes real: if a document has two headings with the same text, GitHub appends -1, -2, and so on to the duplicate anchors. That matters in practice: Best practice: Avoid duplicate heading text.

      -

      Alex: Another way to ground it. Keep the learner anchored in 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. A good GitHub workflow is like a well-run meeting: everyone knows the topic, the next action, and who has the floor.

      -

      Jamie: Let's pause on In the PR detail view. What should a learner take away from it?

      -

      Alex: Start with In the PR detail view. There is something to understand, something to try, and something that proves the try worked.

      -

      Alex: First, scroll down to "Files Changed" section. Then, each file is a link. After that, navigate with Arrow keys. Finally, press Enter on a file to open its diff view. The rhythm is simple: orient, act, verify, then continue.

      -

      Alex: Keep the teaching thread moving. Start with Screen reader announcement: "docs/11-vscode-interface.md, 42 additions, 3 deletions".

      +

      Jamie: Let's pause on Finding the anchor for any heading. What should a learner take away from it?

      +

      Alex: Start with Finding the anchor for any heading. There is something to understand, something to try, and something that proves the try worked.

      +

      Alex: First, mouse users: On GitHub, hover over any heading - a chain link icon appears to the left. Click it to update the URL with the anchor. Then, screen reader users: Navigate to the heading, then Tab once. A link button appears. Activate it and the URL in the address bar updates to show the anchor. After that, keyboard (GitHub shortcut): There is no direct shortcut, but you can copy the heading text, convert it to the anchor format mentally, and type it in the URL. It is like walking a hallway with named doors: read the sign, enter the right room, then confirm where you landed.

      +

      Jamie: Let's pause on 26. Autolinked References - Issues, PRs, Commits, and Users. What should a learner take away from it?

      +

      Alex: The reason 26. Autolinked References - Issues, PRs, Commits, and Users matters is that one of GitHub's most powerful features is automatic linking. That gives the learner a simple foothold: when you type certain patterns in any Markdown field on GitHub, they automatically become clickable links.

      +

      Alex: Keep the teaching thread moving. Start with Issue and pull request references: The following table shows how to reference issues and pull requests. Think of it like entering a new building: first you find the lobby, then the room, then the door you actually need.

      -

      Jamie: Let's pause on Understanding the Diff View. What should a learner take away from it?

      -

      Alex: Here is the plain-English version of Understanding the Diff View. When you open a file from "Files Changed".

      -

      Alex: Keep the teaching thread moving. Start with Split view mode (default). There is something to understand, something to try, and something that proves the try worked.

      -

      Alex: The practical takeaway is this. Left side: original file (before changes). Right side: modified file (after changes). Changed lines highlighted (added = green, removed = red).

      -

      Jamie: Let's pause on Inline view mode. What should a learner take away from it?

      -

      Alex: Start with Inline view mode. There is something to understand, something to try, and something that proves the try worked.

      -

      Alex: The practical takeaway is this. Single editor. Removed lines shown with - prefix. Added lines shown with + prefix.

      +

      Jamie: Let's pause on User and team mentions. What should a learner take away from it?

      +

      Alex: Here is the plain-English version of User and team mentions. The following table shows how to mention users and teams.

      +

      Alex: Keep the teaching thread moving. This is where Commit references becomes real: the following table shows how to reference specific commits.

      +

      Alex: A solid Git habit is to know which branch you are on, what changed, and what confirmation you expect before you run the next command.

      +

      Jamie: Let's pause on Closing keywords in pull requests. What should a learner take away from it?

      +

      Alex: Keep the learner anchored in Closing keywords in pull requests. When you include certain keywords followed by an issue reference in a PR description, merging the PR automatically closes the referenced issue. This is the part to say slowly: All of these keywords work: close, closes, closed, fix, fixes, fixed, resolve, resolves, resolved.

      -

      Alex: Keep the teaching thread moving. Start with To toggle between views. There is something to understand, something to try, and something that proves the try worked.

      -

      Alex: The practical takeaway is this. Command Palette: Ctrl+Shift+P (Mac: Cmd+Shift+P) → "Diff: Toggle Inline View".

      -

      Jamie: Let's pause on Recommended workflow for screen reader users. What should a learner take away from it?

      -

      Alex: Start with Recommended workflow for screen reader users. There is something to understand, something to try, and something that proves the try worked.

      -

      Alex: The practical takeaway is this. Unchanged lines (for context). Removed lines (prefixed with -). Added lines (prefixed with +).

      -

      Alex: First, open a changed file from the PR detail view. Then, press F7 to jump to the first diff hunk. After that, press Alt+F2 (Mac: Option+F2) to open Accessible View. Finally, read the hunk content. Think of it as a rail line: each stop confirms you are still on the right route before the next one.

      -

      Jamie: Before we leave Recommended workflow for screen reader users, what is the practical point?

      -

      Alex: First, press Escape to close Accessible View. Then, press F7 to jump to the next hunk. After that, repeat until all hunks reviewed. Treat it like a recipe: do not add the next ingredient until the previous one is actually in the bowl.

      -

      Alex: Keep the teaching thread moving. Here is the plain-English version of 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. Put another way, previously, deleted code could only be read, not selected. It is like learning a transit route. The names of the stops matter because they tell you whether you are still going the right direction.

      +

      Alex: Keep the teaching thread moving. The reason URL autolinking matters is that GitHub automatically converts full URLs into clickable links. That gives the learner a simple foothold: accessibility note: While autolinked URLs work, they create poor link text for screen readers (the entire URL is read character by character). The interface gets friendlier when it stops being a wall of controls and starts being a set of named places.

      +

      Jamie: Let's pause on 27. HTML in Markdown. What should a learner take away from it?

      +

      Alex: Start with 27. HTML in Markdown: GitHub allows a subset of HTML in Markdown files. The next useful detail is this: This is useful for semantic elements that do not have Markdown equivalents, advanced layout needs, and accessibility improvements.

      +

      Jamie: Let's pause on Keyboard key visualization. What should a learner take away from it?

      +

      Alex: Here is the plain-English version of Keyboard key visualization. The element renders text in a key-cap style box. Put another way, press NVDA + Space to toggle Focus Mode.

      +

      Alex: Treat examples as spoken recipes, not decorations. You may hear something like Press Ctrl + C to copy.; Press NVDA + Space to toggle Focus Mode. Read the command, understand what it changes, then run it only when the repository state matches the lesson.

      -

      Jamie: Let's pause on Flagging Issues During Review. What should a learner take away from it?

      -

      Alex: This is where Flagging Issues During Review becomes real: start Review saves your comments as a draft until you submit the full review (see Section 7).

      -

      Alex: First, navigate to the specific line in the diff. Then, press Shift+F10 (Mac: Ctrl+Return) for context menu. After that, select "Add Comment". Finally, type your comment in the input that appears. It is a checklist, but a meaningful one: every item creates evidence that the next step is safe.

      -

      Jamie: Before we leave Flagging Issues During Review, what is the practical point?

      -

      Alex: First, choose "Single Comment" or "Start Review". It is like walking a hallway with named doors: read the sign, enter the right room, then confirm where you landed.

      -

      Alex: A solid issue habit is to read the title, the body, and the timeline before acting. You are listening for the requested action, the missing evidence, and the person who needs a response.

      -

      Alex: Keep the teaching thread moving. Start with Learning Cards: Reviewing Pull Requests in VS Code. There is something to understand, something to try, and something that proves the try worked.

      -

      Alex: The practical takeaway is this. 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. 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.

      -

      Jamie: Let's pause on Tool Cards: Create a Pull Request (from your editor). What should a learner take away from it?

      -

      Alex: The reason Tool Cards: Create a Pull Request (from your editor) matters is that VS Code Desktop (primary for Day 2). That gives the learner a simple foothold: after you've pushed commits to a feature branch, you can create a PR without leaving VS Code.

      -

      Alex: First, ctrl+Shift+P GitHub Pull Requests: Create Pull Request. Then, fill in the title, description, and base branch. After that, click Create. Finally, push your branch, then click the Compare & pull request banner on the repo page. The rhythm is simple: orient, act, verify, then continue.

      -

      Jamie: Before we leave Tool Cards: Create a Pull Request (from your editor), what is the practical point?

      -

      Alex: First, fill in the form and click Create pull request. Then, after pushing, click Create Pull Request -- this opens gitub.com with the form pre-filled. Think of it as a rail line: each stop confirms you are still on the right route before the next one.

      -

      Alex: Treat examples as spoken recipes, not decorations. You may hear something like git push -u origin your-branch; gh pr create --title "Title" --body "Description". Read the command, understand what it changes, then run it only when the repository state matches the lesson.

      +

      Jamie: Let's pause on Hidden comments. What should a learner take away from it?

      +

      Alex: This is where Hidden comments becomes real: hidden comments are useful for notes to yourself or other contributors that should not be visible to readers.

      +

      Alex: Keep the teaching thread moving. Keep the learner anchored in Allowed HTML elements on GitHub. GitHub whitelists specific HTML elements for security. This is the part to say slowly: The following table lists the most useful allowed elements. A good GitHub workflow is like a well-run meeting: everyone knows the topic, the next action, and who has the floor.

      +

      Jamie: Let's pause on Disallowed HTML on GitHub. What should a learner take away from it?

      +

      Alex: The reason Disallowed HTML on GitHub matters is that GitHub strips these elements for security.

      +

      Alex: The practical takeaway is this. No JavaScript execution. No arbitrary CSS. No embedded content. No form elements (except task list checkboxes). No input fields. Event attributes like onclick, onload.

      -

      Jamie: Let's pause on Prerequisites. What should a learner take away from it?

      -

      Alex: Start with Prerequisites. There is something to understand, something to try, and something that proves the try worked.

      -

      Alex: First, you've created a branch (see Git & Source Control: Branch Management). Then, you've made commits. After that, you've pushed the branch to GitHub (Ctrl+Shift+P / Mac: Cmd+Shift+P → "Git: Push"). Think of it as a rail line: each stop confirms you are still on the right route before the next one.

      -

      Jamie: Let's pause on Method 1: Command Palette (Recommended). What should a learner take away from it?

      -

      Alex: Start with Method 1: Command Palette (Recommended). There is something to understand, something to try, and something that proves the try worked.

      -

      Alex: First, ctrl+Shift+P (Mac: Cmd+Shift+P). Then, type "GitHub Pull Requests: Create". After that, select "GitHub Pull Requests: Create Pull Request". Finally, a form opens in the editor. Treat it like a recipe: do not add the next ingredient until the previous one is actually in the bowl.

      -

      Jamie: Let's pause on Method 2: Source Control Panel. What should a learner take away from it?

      -

      Alex: Start with Method 2: Source Control Panel. There is something to understand, something to try, and something that proves the try worked.

      -

      Alex: First, open Source Control: Ctrl+Shift+G (Mac: Cmd+Shift+G). Then, after pushing, a "Create Pull Request" button appears. After that, press Enter on that button. It is a checklist, but a meaningful one: every item creates evidence that the next step is safe.

      +

      Alex: Keep the teaching thread moving. Start with 28. Screen Reader Behavior Summary: This table consolidates how every Markdown element behaves with screen readers. The next useful detail is this: Use it as a quick reference when choosing how to format your content.

      +

      Jamie: Let's pause on 29. Accessible Markdown Authoring Checklist. What should a learner take away from it?

      +

      Alex: Here is the plain-English version of 29. Accessible Markdown Authoring Checklist. Use this checklist every time you write a Markdown file, issue, or PR description. Put another way, it covers the accessibility requirements that make your content work for everyone.

      +

      Alex: Keep the teaching thread moving. Start with Structure. There is something to understand, something to try, and something that proves the try worked.

      +

      Alex: The practical takeaway is this. [ ] One H1 heading per document, used as the title. [ ] Heading levels never skip (no jumping from H2 to H4). [ ] Headings are descriptive (not "Section 1" or "Untitled"). [ ] Long documents have a table of contents with anchor links.

      -

      Jamie: Let's pause on Method 3: GitHub Panel. What should a learner take away from it?

      -

      Alex: Start with Method 3: GitHub Panel. There is something to understand, something to try, and something that proves the try worked.

      -

      Alex: First, open GitHub view (Activity Bar → GitHub icon). Then, right-click your branch in the tree. After that, select "Create Pull Request". It is like walking a hallway with named doors: read the sign, enter the right room, then confirm where you landed.

      -

      Alex: Keep the teaching thread moving. Start with Title (required). There is something to understand, something to try, and something that proves the try worked.

      -

      Alex: The practical takeaway is this. Auto-filled with your most recent commit message. Edit to make it descriptive (example: "Add Timeline View documentation").

      -

      Jamie: Let's pause on Description (optional but recommended). What should a learner take away from it?

      -

      Alex: Start with Description (optional but recommended). There is something to understand, something to try, and something that proves the try worked.

      -

      Alex: The practical takeaway is this. 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.

      +

      Jamie: Let's pause on Text and emphasis. What should a learner take away from it?

      +

      Alex: Start with Text and emphasis. There is something to understand, something to try, and something that proves the try worked.

      +

      Alex: The practical takeaway is this. [ ] Bold marks genuinely important content, not just visual styling. [ ] Bold text is not used as a substitute for headings. [ ] Strikethrough text has surrounding context explaining the change.

      +

      Alex: Keep the teaching thread moving. Start with Links. There is something to understand, something to try, and something that proves the try worked.

      +

      Alex: The practical takeaway is this. [ ] Every link has descriptive text (never "click here," "here," "read more," or "link"). [ ] No bare URLs in prose (always use descriptive text). [ ] Multiple links on the same page have unique text if they point to different destinations. [ ] Relative links used for files within the same repository.

      +

      Jamie: Let's pause on Images. What should a learner take away from it?

      +

      Alex: Start with Images. There is something to understand, something to try, and something that proves the try worked.

      +

      Alex: The practical takeaway is this. [ ] Every informative image has descriptive alt text. [ ] Alt text is not a filename (screenshot.png) or generic (image, photo). [ ] Complex images (charts, diagrams) have a detailed text description in a block. [ ] Decorative images have empty alt text.

      -

      Alex: Keep the teaching thread moving. Start with Base branch (target). There is something to understand, something to try, and something that proves the try worked.

      -

      Alex: The practical takeaway is this. Usually main or develop. This is the branch your changes will merge into.

      -

      Jamie: Let's pause on Compare branch (source). What should a learner take away from it?

      -

      Alex: Start with Compare branch (source). There is something to understand, something to try, and something that proves the try worked.

      -

      Alex: The practical takeaway is this. Your feature branch (auto-selected). This is the branch with your changes.

      -

      Alex: Keep the teaching thread moving. Start with Reviewers (optional). There is something to understand, something to try, and something that proves the try worked.

      -

      Alex: The practical takeaway is this. Select people to review your PR. Navigate the list with Arrow keys.

      +

      Alex: Keep the teaching thread moving. Start with Lists and tables. There is something to understand, something to try, and something that proves the try worked.

      +

      Alex: The practical takeaway is this. [ ] Lists use the correct type: ordered for sequential steps, unordered for non-sequential items. [ ] Tables have a text description immediately before them. [ ] Tables have descriptive header cells. [ ] Tables have fewer than 7 columns (split wide tables). [ ] Tables are used for data, not layout.

      +

      Jamie: Let's pause on Code. What should a learner take away from it?

      +

      Alex: Start with Code. There is something to understand, something to try, and something that proves the try worked.

      +

      Alex: The practical takeaway is this. [ ] Fenced code blocks have a language identifier. [ ] Inline code used for commands, file names, and values. [ ] Code examples are complete enough to understand without the visual highlighting.

      +

      Alex: Keep the teaching thread moving. Start with GFM features. There is something to understand, something to try, and something that proves the try worked.

      +

      Alex: The practical takeaway is this. [ ] Mermaid diagrams have a text equivalent. [ ] Alert block type matches the urgency of the content. [ ] summary text clearly describes what is inside. [ ] Task list items have descriptive labels. [ ] Complex math expressions have plain English descriptions.

      -

      Jamie: Let's pause on Labels (optional). What should a learner take away from it?

      -

      Alex: Start with Labels (optional). There is something to understand, something to try, and something that proves the try worked.

      -

      Alex: The practical takeaway is this. Add labels like documentation, accessibility, good-first-issue.

      -

      Alex: Keep the teaching thread moving. Start with Milestone (optional). There is something to understand, something to try, and something that proves the try worked.

      -

      Alex: The practical takeaway is this. Link the PR to a project milestone.

      -

      Jamie: Let's pause on Draft PR checkbox. What should a learner take away from it?

      -

      Alex: Start with Draft PR checkbox. There is something to understand, something to try, and something that proves the try worked.

      -

      Alex: The practical takeaway is this. Check this if the PR is not ready for review yet. Unchecked = "Ready for review".

      +

      Jamie: Let's pause on General. What should a learner take away from it?

      +

      Alex: Start with General. There is something to understand, something to try, and something that proves the try worked.

      +

      Alex: The practical takeaway is this. [ ] Color is never the only way information is conveyed. [ ] No information is communicated only through visual position or layout. [ ] Content makes sense when read linearly, top to bottom.

      +

      Alex: Keep the teaching thread moving. Start with 30. Common Mistakes and How to Fix Them: This section covers the errors we see most often in workshop participants' Markdown. The next useful detail is this: Each one includes what goes wrong, why it matters, and how to fix it. Think of it like entering a new building: first you find the lobby, then the room, then the door you actually need.

      +

      Jamie: Let's pause on Mistake 1 - Forgetting the blank line between paragraphs. What should a learner take away from it?

      +

      Alex: Here is the plain-English version of Mistake 1 - Forgetting the blank line between paragraphs. What it produces: One merged paragraph. Put another way, fix: Add a blank line between paragraphs.

      -

      Alex: Keep the teaching thread moving. Start with Screen reader navigation. There is something to understand, something to try, and something that proves the try worked.

      -

      Alex: The practical takeaway is this. All fields are standard form inputs. Tab to move between fields. Use Arrow keys in dropdowns (reviewers, labels, milestones).

      -

      Jamie: Let's pause on Submitting the PR. What should a learner take away from it?

      -

      Alex: Keep the learner anchored in Submitting the PR. VS Code creates the PR on GitHub and shows a success message. This is the part to say slowly: The PR link appears in the notification - click it to open the PR on GitHub, or open it in the GitHub Pull Requests panel.

      -

      Alex: First, review all fields. Then, tab to "Create" button. After that, press Enter. Finally, navigate to the repository on GitHub. It is like walking a hallway with named doors: read the sign, enter the right room, then confirm where you landed.

      -

      Jamie: Before we leave Submitting the PR, what is the practical point?

      -

      Alex: First, if you recently pushed, a yellow banner "Compare & pull request" appears - click it. Then, otherwise: click Pull requests tab, then New pull request, then select your branch. After that, fill in the title and description. Finally, click Create pull request. The rhythm is simple: orient, act, verify, then continue.

      -

      Alex: Treat examples as spoken recipes, not decorations. You may hear something like 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. Read the command, understand what it changes, then run it only when the repository state matches the lesson.

      -

      Alex: Keep the teaching thread moving. Start with Learning Cards: Creating a Pull Request. There is something to understand, something to try, and something that proves the try worked.

      -

      Alex: The practical takeaway is this. 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. 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.

      +

      Alex: Keep the teaching thread moving. This is where Mistake 2 - Skipping heading levels becomes real: why it matters: Screen reader users navigating by heading level will miss entire sections. That matters in practice: Jumping from H1 to H4 means H2 and H3 navigation finds nothing.

      +

      Jamie: Let's pause on Mistake 3 - Generic link text. What should a learner take away from it?

      +

      Alex: Keep the learner anchored in Mistake 3 - Generic link text. Why it matters: A screen reader user scanning the links list hears "here" - with no context about where the link goes. This is the part to say slowly: Fix: For more information, read the GitHub Documentation.

      +

      Alex: Keep the teaching thread moving. The reason Mistake 4 - Missing alt text on images matters is that why it matters: Screen reader users have no idea what the image shows. That gives the learner a simple foothold: some screen readers announce the filename, which is not helpful. The interface gets friendlier when it stops being a wall of controls and starts being a set of named places.

      -

      Jamie: Let's pause on 6. Pull Request Description Templates. What should a learner take away from it?

      -

      Alex: Start with 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.

      -

      Alex: Keep the teaching thread moving. Here is the plain-English version of Where Templates Are Stored. When you create a PR in VS Code, the extension automatically loads the template into the description field. It is like learning a transit route. The names of the stops matter because they tell you whether you are still going the right direction.

      -

      Alex: The practical takeaway is this.github/pull request template.md (root).github/PULL REQUEST TEMPLATE.md.github/PULL REQUEST TEMPLATE/ (folder with multiple templates). docs/pull request template.md.

      -

      Jamie: What is the safe way to learn from that example?

      -

      Alex: Start with Example PR Template. There is something to understand, something to try, and something that proves the try worked.

      -

      Alex: Treat examples as spoken recipes, not decorations. You may hear something like 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,. Read the command, understand what it changes, then run it only when the repository state matches the lesson.

      +

      Jamie: Let's pause on Mistake 5 - Using bold instead of headings. What should a learner take away from it?

      +

      Alex: Start with Mistake 5 - Using bold instead of headings: Why it matters: Visually, this looks like a heading. The next useful detail is this: But screen reader users navigating with H will never find it.

      +

      Alex: Keep the teaching thread moving. Here is the plain-English version of Mistake 6 - No description before a table. Why it matters: A screen reader user enters the table without knowing what data it contains. Put another way, they hear "table, 2 columns, 3 rows" but not what the table is about.

      +

      Jamie: Let's pause on Mistake 7 - Code block without a language identifier. What should a learner take away from it?

      +

      Alex: This is where Mistake 7 - Code block without a language identifier becomes real: why it matters: Without the language identifier, sighted users lose the visual benefit of syntax highlighting, and tools that process Markdown lose metadata about the content. That matters in practice: Fix: Always add the language: `python.

      -

      Jamie: Let's pause on Screen reader workflow. What should a learner take away from it?

      -

      Alex: Keep the learner anchored in Screen reader workflow. Keyboard tip: Use Ctrl+F (Mac: Cmd+F) to jump to each <!-- placeholder, fill it in, then F3 to jump to the next one.

      -

      Alex: First, create PR (Method 1-3 from Section 5). Then, the description field is pre-filled with the template. After that, navigate through the template with Arrow keys. Finally, replace each `` with your content. It is like walking a hallway with named doors: read the sign, enter the right room, then confirm where you landed.

      -

      Jamie: Before we leave Screen reader workflow, what is the practical point?

      -

      Alex: First, check checkboxes by typing x between the brackets: - [x]. The rhythm is simple: orient, act, verify, then continue.

      -

      Jamie: Let's pause on 7. Commenting and Requesting Changes. What should a learner take away from it?

      -

      Alex: Start with 7. Commenting and Requesting Changes. There is something to understand, something to try, and something that proves the try worked.

      -

      Alex: The practical takeaway is this. Leave inline comments on specific lines. Request changes before the PR can be merged. Approve the PR. Submit general feedback.

      -

      Jamie: Let's pause on Adding an Inline Comment. What should a learner take away from it?

      -

      Alex: Start with Adding an Inline Comment. There is something to understand, something to try, and something that proves the try worked.

      -

      Alex: First, open a file from the PR's "Files Changed" list. Then, navigate to the line you want to comment on. After that, press Shift+F10 (Mac: Ctrl+Return) to open context menu. Finally, select "Add Comment". Think of it as a rail line: each stop confirms you are still on the right route before the next one.

      -

      Jamie: Before we leave Adding an Inline Comment, what is the practical point?

      -

      Alex: First, type your comment. Then, choose "Add Single Comment" (posts immediately) or "Start Review" (saves as a draft). Treat it like a recipe: do not add the next ingredient until the previous one is actually in the bowl.

      +

      Alex: Keep the teaching thread moving. Keep the learner anchored in Mistake 8 - Inconsistent list markers. Why it matters: While most processors render this as one list, some treat different markers as separate lists, creating unexpected spacing and structure. This is the part to say slowly: Fix: Pick one marker and use it consistently. A good GitHub workflow is like a well-run meeting: everyone knows the topic, the next action, and who has the floor.

      +

      Jamie: Let's pause on Mistake 9 - Mermaid diagram without a text equivalent. What should a learner take away from it?

      +

      Alex: The reason Mistake 9 - Mermaid diagram without a text equivalent matters is that why it matters: Screen reader users cannot access the visual diagram. That gives the learner a simple foothold: they hear nothing or a generic SVG container message.

      +

      Alex: Keep the teaching thread moving. Start with Mistake 10 - Alert block with wrong type: Why it matters: CAUTION (red) implies irreversible harm. The next useful detail is this: A suggestion to try a different approach is, at most, a TIP (green) or a NOTE (blue).

      -

      Jamie: Let's pause on Comment format tips. What should a learner take away from it?

      -

      Alex: Start with Comment format tips. There is something to understand, something to try, and something that proves the try worked.

      -

      Alex: The practical takeaway is this. Be specific: "This heading should be H3, not H2". Provide context: "Screen readers announce this as 'list with 1 item' - should be a paragraph instead". Suggest a fix: "Consider rewording to: 'Click the button to save'".

      -

      Jamie: Let's pause on If you have multiple comments to make, use "Start Review". What should a learner take away from it?

      -

      Alex: Start with If you have multiple comments to make, use "Start Review". There is something to understand, something to try, and something that proves the try worked.

      -

      Alex: First, add your first inline comment → select "Start Review". Then, continue adding comments to other lines. After that, all comments are saved as drafts (not visible to others yet). It is a checklist, but a meaningful one: every item creates evidence that the next step is safe.

      -

      Jamie: Let's pause on Submitting Your Review. What should a learner take away from it?

      -

      Alex: Keep the learner anchored in Submitting Your Review. The review type selector is a radio button group. This is the part to say slowly: Use Arrow keys to choose, Enter to confirm.

      -

      Alex: The practical takeaway is this. Comment - general feedback, no approval decision. Approve - PR looks good, ready to merge. Request Changes - issues must be fixed before merging.

      -

      Alex: First, ctrl+Shift+P (Mac: Cmd+Shift+P). Then, type "GitHub Pull Requests: Submit Review". After that, select "GitHub Pull Requests: Finish Review". Finally, choose review type. It is like walking a hallway with named doors: read the sign, enter the right room, then confirm where you landed.

      -

      Jamie: Before we leave Submitting Your Review, what is the practical point?

      -

      Alex: First, optionally add a summary comment. Then, press Enter to submit. The rhythm is simple: orient, act, verify, then continue.

      +

      Jamie: What makes this practice feel low-stakes but still real?

      +

      Alex: Here is the plain-English version of 31. Your First Real Markdown Document - Guided Exercise. In this exercise, you will create a Markdown document that uses most of the elements covered in this guide. Put another way, this is structured as a hands-on exercise that you can do during the workshop.

      +

      Jamie: Let's pause on Setup. What should a learner take away from it?

      +

      Alex: Start with Setup. There is something to understand, something to try, and something that proves the try worked.

      +

      Alex: First, open any repository where you have write access. Then, click New Issue (or create a new.md file in VS Code). After that, you will write a mini profile document about yourself. It is a checklist, but a meaningful one: every item creates evidence that the next step is safe.

      +

      Jamie: Let's pause on Step 1 - Add a heading and introduction. What should a learner take away from it?

      +

      Alex: Keep the learner anchored in Step 1 - Add a heading and introduction. Type the following, replacing the placeholder text with your own information. This is the part to say slowly: Use the Preview tab (or Ctrl+Shift+V in VS Code) to verify the heading renders as a large title.

      +

      Alex: Treat examples as spoken recipes, not decorations. You may hear something like About Me; Hi! My name is [your name] and I am participating in the; GIT Going with GitHub workshop. Read the command, understand what it changes, then run it only when the repository state matches the lesson.

      -

      Jamie: Let's pause on What Happens After Submission. What should a learner take away from it?

      -

      Alex: The reason What Happens After Submission matters is that web alternative (github.com) - reviewing. That gives the learner a simple foothold: see Accessible Code Review for detailed screen reader steps. The interface gets friendlier when it stops being a wall of controls and starts being a set of named places.

      -

      Alex: The practical takeaway is this. All your draft comments post to GitHub. The PR author receives a notification. Your review status appears on the PR (Approved / Changes Requested / Commented). If you requested changes, the PR cannot merge until you approve it.

      -

      Alex: First, open the PR and click the Files changed tab. Then, read through each file's diff. After that, click the blue + button on any line to add an inline comment. Finally, choose Start a review to batch comments. The rhythm is simple: orient, act, verify, then continue.

      -

      Jamie: Before we leave What Happens After Submission, what is the practical point?

      -

      Alex: First, click Review changes (top right) to select Comment / Approve / Request changes. Then, click Submit review. Think of it as a rail line: each stop confirms you are still on the right route before the next one.

      -

      Alex: Treat examples as spoken recipes, not decorations. You may hear something like View the PR diff in your terminal; gh pr diff 42; Approve; gh pr review 42 --approve --body "Looks good."; Request changes; gh pr review 42 --request-changes --body "Heading hierarchy needs fixing."; Comment-only (no verdict); gh pr review 42 --comment --body. Read the command, understand what it changes, then run it only when the repository state matches the lesson.

      -

      Jamie: Let's pause on Learning Cards: Commenting and Requesting Changes. What should a learner take away from it?

      -

      Alex: Start with Learning Cards: Commenting and Requesting Changes. There is something to understand, something to try, and something that proves the try worked.

      -

      Alex: The practical takeaway is this. In a diff view, navigate to a line and press Shift+F10 for the context menu, then select "Add Comment" to leave inline feedback. Choose "Start Review" instead of "Single Comment" to batch multiple comments before submitting them all at once. When submitting a review, use Ctrl+Shift+P then "GitHub Pull Requests: Submit Review" and choose Approve, Request Changes, or Comment. Inline comments appear as expandable banners within the diff view -- look for the text input box that opens below the target line. The review submission dialog has radio buttons for Approve, Request Changes, and Comment with clear labels. Increase diff view font size with Ctrl+= so line numbers and change annotations are easier to read.

      -

      Alex: Keep the teaching thread moving. Here is the plain-English version of 8. Merging Pull Requests. Who can merge: Repository maintainers, or contributors with write access.

      -
      -

      Jamie: Let's pause on Prerequisites for Merging. What should a learner take away from it?

      -

      Alex: This is where Prerequisites for Merging becomes real: changing the base branch: If the PR was opened against the wrong base branch, you can change it from the PR detail view in VS Code. That matters in practice: Scroll to the base branch field in the PR detail view and activate the dropdown to select a different target branch.

      -

      Alex: First, all required reviews are approved. Then, all CI checks pass (green checkmarks). After that, no merge conflicts exist. Finally, branch is up to date with base branch (main). It is a checklist, but a meaningful one: every item creates evidence that the next step is safe.

      -

      Jamie: Let's pause on Method 1: PR Detail View. What should a learner take away from it?

      -

      Alex: Start with Method 1: PR Detail View. There is something to understand, something to try, and something that proves the try worked.

      -

      Alex: First, open the PR in VS Code. Then, scroll to the bottom of the PR detail view. After that, find "Merge Pull Request" button. Finally, press Enter. It is like walking a hallway with named doors: read the sign, enter the right room, then confirm where you landed.

      -

      Jamie: Before we leave Method 1: PR Detail View, what is the practical point?

      -

      Alex: First, choose merge type (see below). The rhythm is simple: orient, act, verify, then continue.

      -

      Jamie: What is the teaching move inside Method 2: Command Palette?

      -

      Alex: Start with Method 2: Command Palette. There is something to understand, something to try, and something that proves the try worked.

      -

      Alex: First, ctrl+Shift+P (Mac: Cmd+Shift+P). Then, type "GitHub Pull Requests: Merge". After that, select "GitHub Pull Requests: Merge Pull Request". Finally, choose the PR from the list. The rhythm is simple: orient, act, verify, then continue.

      -

      Jamie: If someone only remembers one thing from Method 2: Command Palette, what should it be?

      -

      Alex: First, select merge type. Think of it as a rail line: each stop confirms you are still on the right route before the next one.

      +

      Alex: Keep the teaching thread moving. The reason Step 2 - Add a section with a list matters is that verify the numbered list renders correctly.

      +

      Jamie: Let's pause on Step 3 - Add emphasis and inline code. What should a learner take away from it?

      +

      Alex: Start with Step 3 - Add emphasis and inline code: Check that bold, italic, and inline code all render as expected.

      +

      Alex: Treat examples as spoken recipes, not decorations. You may hear something like My Setup; I use NVDA on Windows with Firefox. My terminal is; PowerShell and I am learning git commands. Read the command, understand what it changes, then run it only when the repository state matches the lesson.

      +

      Jamie: Let's pause on Step 5 - Add a table. What should a learner take away from it?

      +

      Alex: Start with Step 5 - Add a table. There is something to understand, something to try, and something that proves the try worked.

      +

      Alex: Treat examples as spoken recipes, not decorations. You may hear something like Tools I Use; The following table lists the tools I use daily.; Tool Purpose Platform; --- --- ---; NVDA Screen reader Windows; Firefox Web browser Windows; VS Code Code editor Windows. Read the command, understand what it changes, then run it only when the repository state matches the lesson.

      -

      Alex: Keep the teaching thread moving. Start with Merge Types: The merge type selector is a dropdown or radio group. The next useful detail is this: Navigate with Arrow keys, confirm with Enter.

      -

      Jamie: Let's pause on Which merge type to use. What should a learner take away from it?

      -

      Alex: Start with Which merge type to use. There is something to understand, something to try, and something that proves the try worked.

      -

      Alex: The practical takeaway is this. Check the repository's CONTRIBUTING.md for guidance. If unsure, use Merge Commit (the default and safest option).

      -

      Jamie: Let's pause on After Merging. What should a learner take away from it?

      -

      Alex: Start with After Merging. There is something to understand, something to try, and something that proves the try worked.

      -

      Alex: First, the PR closes automatically. Then, the feature branch can be deleted (VS Code prompts: "Delete branch?"). After that, recommended: switch back to main and pull the merged changes. It is a checklist, but a meaningful one: every item creates evidence that the next step is safe.

      +

      Jamie: Let's pause on Step 7 - Add a collapsible section. What should a learner take away from it?

      +

      Alex: Start with Step 7 - Add a collapsible section. There is something to understand, something to try, and something that proves the try worked.

      +

      Alex: Treat examples as spoken recipes, not decorations. You may hear something like Additional Notes;; My accessibility testing experience; I have been using a screen reader for three years. I have tested; web applications with NVDA and I am learning how to contribute; accessibility bug reports to open source projects. Read the command, understand what it changes, then run it only when the repository state matches the lesson.

      +

      Alex: Keep the teaching thread moving. Keep the learner anchored in You are done when. You just wrote a Markdown document that uses headings, paragraphs, emphasis, inline code, links, blockquotes, tables, task lists, and collapsible sections. This is the part to say slowly: Every one of these skills transfers directly to issues, pull requests, and documentation in this workshop.

      +

      Alex: The practical takeaway is this. Your document renders with a clear heading hierarchy (H1, H2). Bold and italic text render correctly. The numbered list shows sequential numbers. The link is clickable.

      +

      Jamie: Let's pause on Learning Cards: Quick-Reference Card. What should a learner take away from it?

      +

      Alex: Start with Learning Cards: Quick-Reference Card. There is something to understand, something to try, and something that proves the try worked.

      +

      Alex: The practical takeaway is this. This card shows raw Markdown syntax in code blocks -- read each block to hear the exact characters to type. Keep this section bookmarked as a daily reference when writing issues, PRs, and comments. Each code block is labeled by format type (headings, lists, links, etc.) in the heading above it. The card uses large monospace code blocks -- increase zoom and each syntax example stays on one or two lines. Print this section or save it as a separate file for quick side-by-side reference while writing. Syntax characters (,, -, []) are visually distinct in the code font.

      -

      Jamie: What should happen before anyone copies and runs it?

      -

      Alex: Keep the learner anchored in Switching to main and pulling. (Mac users: use Cmd+Shift+P instead of Ctrl+Shift+P).

      -

      Alex: Treat examples as spoken recipes, not decorations. You may hear something like Ctrl+Shift+P → "Git: Checkout to." → select "main"; Ctrl+Shift+P → "Git: Pull". Read the command, understand what it changes, then run it only when the repository state matches the lesson.

      -

      Jamie: Let's pause on Deleting the Feature Branch. What should a learner take away from it?

      -

      Alex: The reason Deleting the Feature Branch matters is that after merging, the feature branch is no longer needed. That gives the learner a simple foothold: web alternative (github.com) - merging.

      -

      Alex: First, ctrl+Shift+P (Mac: Cmd+Shift+P). Then, type "git delete branch". After that, select "Git: Delete Branch.". Finally, choose the merged branch. The rhythm is simple: orient, act, verify, then continue.

      -

      Jamie: Before we leave Deleting the Feature Branch, what is the practical point?

      -

      Alex: First, open the PR's Conversation tab. Then, scroll to the merge button at the bottom. After that, click the dropdown arrow to choose a merge strategy (Squash, Rebase, or Merge commit). Finally, click Merge pull request, then Confirm merge. Think of it as a rail line: each stop confirms you are still on the right route before the next one.

      -

      Alex: Treat examples as spoken recipes, not decorations. You may hear something like Merge with default strategy; gh pr merge 42; Squash and merge, then delete the branch; gh pr merge 42 --squash --delete-branch; Enable auto-merge (merges when checks pass); gh pr merge 42 --auto --squash. Read the command, understand what it changes, then run it only when the repository state matches the lesson.

      -

      Jamie: Let's pause on Learning Cards: Merging Pull Requests. What should a learner take away from it?

      -

      Alex: Start with Learning Cards: Merging Pull Requests. There is something to understand, something to try, and something that proves the try worked.

      -

      Alex: The practical takeaway is this. The merge type selector (Merge Commit, Squash, Rebase) is announced as a dropdown or radio group -- use Arrow keys to move between options and Enter to confirm; if unsure, choose Merge Commit (the default and safest option). After merging, VS Code prompts "Delete branch?" as a notification -- press Alt+N to focus the notification and Enter to confirm, then run Ctrl+Shift+P then "Git: Checkout to" and select main to return to your default branch. Confirm the merge succeeded by pressing F6 to reach the Status Bar and verifying it now reads main instead of the feature branch name. The merge button at the bottom of the PR detail view includes a dropdown arrow for selecting merge type -- at high zoom, widen the editor pane so the button label and dropdown are not truncated. After merging, the PR detail view header changes from "Open" (green badge) to "Merged" (purple badge) -- verify this colour/label change before deleting the branch. When switching back to main, the branch name in the bottom-left Status Bar updates immediately -- confirm it reads main before pulling new changes with Ctrl+Shift+P then "Git: Pull".

      +

      Alex: Keep the teaching thread moving. Start with 32. Quick-Reference Card: It shows the raw Markdown for every element covered in this guide. Think of it like entering a new building: first you find the lobby, then the room, then the door you actually need.

      +

      Jamie: Let's pause on HTML in Markdown. What should a learner take away from it?

      +

      Alex: Start with HTML in Markdown. There is something to understand, something to try, and something that proves the try worked.

      +

      Alex: Treat examples as spoken recipes, not decorations. You may hear something like Press Ctrl + C to copy.; H 2 O; x 2; Line one Line two. Read the command, understand what it changes, then run it only when the repository state matches the lesson.

      +

      Alex: Keep the teaching thread moving. This is where Mermaid diagram (with accessible text) becomes real: next: Appendix D: Git Authentication Back: Appendix B: Screen Reader Cheat Sheet Teaching chapter: Chapter 06: Working with Pull Requests.

      -

      Alex: Keep the teaching thread moving. Here is the plain-English version of "No pull requests found". Issue: The GitHub Pull Requests panel is empty. It is like learning a transit route. The names of the stops matter because they tell you whether you are still going the right direction.

      -

      Jamie: Let's pause on Solutions. What should a learner take away from it?

      -

      Alex: Start with Solutions. There is something to understand, something to try, and something that proves the try worked.

      -

      Alex: First, verify you're signed in: Ctrl+Shift+P (Mac: Cmd+Shift+P) → "GitHub Pull Requests: Sign in". Then, check you have a folder open containing a Git repository. After that, refresh the panel: Ctrl+Shift+P (Mac: Cmd+Shift+P) → "GitHub Pull Requests: Refresh Pull Requests List". It is a checklist, but a meaningful one: every item creates evidence that the next step is safe.

      -

      Jamie: Before we leave Solutions, what is the practical point?

      -

      Alex: First, verify you've pushed your branch: Ctrl+Shift+P (Mac: Cmd+Shift+P) → "Git: Push". Then, check you have write access to the repository. After that, ensure your branch is ahead of the base branch (has new commits). It is like walking a hallway with named doors: read the sign, enter the right room, then confirm where you landed.

      +

      Jamie: What should people carry with them after this?

      +

      Alex: Carry the map. Know what page or tool you are in, know which action you are taking, and know what confirmation should follow. If the confirmation is missing, pause. That pause is not wasted time; it is professional judgment.

      +

      Jamie: That is a better way to say it than just follow the steps.

      +

      Alex: Right. Steps matter, but understanding wins. That is episode 22. Next in the series is episode 23, where we keep building the same contributor muscles.

      +
      +
      -

      Jamie: Let's pause on "Authentication failed". What should a learner take away from it?

      -

      Alex: The reason "Authentication failed" matters is that issue: VS Code can't connect to GitHub.

      -

      Jamie: What is the teaching move inside Solutions?

      -

      Alex: First, sign out and sign back in: Ctrl+Shift+P (Mac: Cmd+Shift+P) → "GitHub Pull Requests: Sign out" → then sign in again. Then, check your GitHub Personal Access Token (see Appendix D: Git Authentication). After that, verify network connection. Think of it as a rail line: each stop confirms you are still on the right route before the next one.

      -

      Jamie: Let's pause on Try It: Review a PR from VS Code. What should a learner take away from it?

      -

      Alex: Here is the plain-English version of Try It: Review a PR from VS Code. Time: 3 minutes What you need: VS Code with GitHub Pull Requests extension installed and signed in. Put another way, you just reviewed a pull request entirely from VS Code.

      -

      Alex: First, open the PR view - Press Ctrl+Shift+P → type Pull Requests: Focus on GitHub Pull Requests View → Enter. Then, find a PR - Navigate the tree with arrow keys. Expand a PR to see its changed files. After that, open a diff - Press Enter on a changed file. The diff editor opens. Finally, use the Accessible Diff Viewer - Press F7 to jump to the first change. Your screen reader announces what was added or removed. Press F7 again to move to the next change. Treat it like a recipe: do not add the next ingredient until the previous one is actually in the bowl.

      -

      Jamie: Before we leave Try It: Review a PR from VS Code, what is the practical point?

      -

      Alex: First, leave a comment - Position your cursor on a line you want to comment on, then press Ctrl+Shift+P → Pull Request: Add Comment on Current Diff Line. Type a brief, constructive comment and submit. It is a checklist, but a meaningful one: every item creates evidence that the next step is safe.

      +

      14. Episode 23: GitHub Gists

      +

      Lightweight code sharing: creating, editing, forking, and embedding Gists.

      +

      Based on: Appendix U: GitHub Gists

      +

      Audio and transcript are being regenerated for this episode.

      +
      +Read Transcript - Episode 23: GitHub Gists + +

      Transcript

      +

      Alex: Welcome to episode 23 of Git Going with GitHub: GitHub Gists. I am Alex, and today we are teaching this topic as a conversation you can carry into the workshop, not as a page you have to memorize.

      +

      Jamie: And I am Jamie. I will keep pulling the lesson back to real learners, real repositories, and the evidence that proves the work happened.

      -

      Alex: Keep the teaching thread moving. This is where Conducting Pull Request Reviews with a Screen Reader becomes real: this guide is focused entirely on the reviewer experience - navigating diffs, reading changes, leaving comments, and submitting a review - using only your keyboard and screen reader. That matters in practice: For the full pull request lifecycle (opening PRs, merge options, conflict resolution), see Working with Pull Requests.

      -

      Jamie: Where does the workshop stop being a tour and start becoming contribution?

      -

      Alex: Keep the learner anchored in Workshop Recommendation (Chapter 15 / Challenge 12). Chapter 15 is the code review chapter focused on practicing constructive feedback. This is the part to say slowly: It supports Challenge 12: Review Like a Pro.

      -

      Alex: The practical takeaway is this. There are 2 guided challenges. Automation check: none (review quality is subjective and human-focused). The evidence is issue comment with summary of review and feedback posted. The pattern is navigate diff, comment on specifics, submit verdict.

      -

      Jamie: Let's pause on Challenge 12 Practice Set. What should a learner take away from it?

      -

      Alex: Start with Challenge 12 Practice Set. There is something to understand, something to try, and something that proves the try worked.

      -

      Alex: First, review a practice PR and leave 2-3 inline comments - read the diff line by line, find specific items to comment on, and post constructive feedback. Then, submit a formal review verdict - complete your review by choosing approve, request changes, or comment only. The rhythm is simple: orient, act, verify, then continue.

      +

      Alex: The lesson focus is Lightweight code sharing: creating, editing, forking, and embedding Gists. We will treat every step as a teachable decision, because that is what makes the skill portable.

      +

      Jamie: So we should explain the why clearly enough that the steps make sense when the learner meets them later.

      +

      Alex: That is it. If a listener only has audio right now, they should still get the complete concept and know what evidence would prove success.

      -

      Jamie: Let's pause on Practice 12.1 Step-by-Step: Review a PR and Leave Inline Comments. What should a learner take away from it?

      -

      Alex: Start with Practice 12.1 Step-by-Step: Review a PR and Leave Inline Comments: Navigate a PR diff using screen reader-friendly tools and post 2-3 specific, constructive inline comments. The next useful detail is this: GitHub.com (Files changed tab of a PR) or VS Code with the GitHub Pull Requests extension.

      -

      Alex: The practical takeaway is this. On GitHub.com: Use heading navigation to jump between files (H in NVDA). Each file header is a heading. Within a file, use arrow keys to move line by line. In VS Code: Press F7 to open the Accessible Diff Viewer (see Chapter 15, Part 1). Use F7/Shift+F7 to move between changes. Typos or grammar issues. Unclear headings or link text.

      -

      Alex: First, open your Learning Room repository on GitHub.com and navigate to the Pull requests tab. Then, find a classmate's open PR (from Chapter 6, 7, or 14). Open it. After that, activate the Files changed tab. This shows the diff - lines added in green, lines removed in red. Finally, navigate the diff. Think of it as a rail line: each stop confirms you are still on the right route before the next one.

      -

      Jamie: Before we leave Practice 12.1 Step-by-Step: Review a PR and Leave Inline Comments, what is the practical point?

      -

      Alex: First, read through the changes carefully. Look. Then, to leave an inline comment on GitHub.com: activate the + button that appears to the left of a line number when you hover or Tab to it. (Screen reader users: this button may be announced as "Add a comment to this line.") Type your comment in the text box that. After that, post 2-3 inline comments. Each comment should be. Finally, examples of good inline comments. Treat it like a recipe: do not add the next ingredient until the previous one is actually in the bowl.

      -

      Jamie: Let's pause on Practice 12.2 Step-by-Step: Submit a Formal Review Verdict. What should a learner take away from it?

      -

      Alex: Here is the plain-English version of Practice 12.2 Step-by-Step: Submit a Formal Review Verdict. Complete your review by selecting a verdict that tells the author what action to take next. Put another way, GitHub.com (the same PR you reviewed in 14.1).

      -

      Alex: The practical takeaway is this. Comment - general feedback, no explicit approval or rejection. Approve - you think the PR is ready to merge. Request changes - you found something that should be fixed before merging. If the PR has clear documentation with only minor suggestions, choose Approve.

      -

      Alex: First, after posting your inline comments, scroll to the top of the Files changed tab. Then, activate the Review changes button (at the top-right of the files changed area, or use heading navigation). After that, a dropdown opens with three options. Finally, choose the verdict that matches your review. Treat it like a recipe: do not add the next ingredient until the previous one is actually in the bowl.

      -

      Jamie: Before we leave Practice 12.2 Step-by-Step: Submit a Formal Review Verdict, what is the practical point?

      -

      Alex: First, write a brief summary in the review body (1-2 sentences). Example: "Clear improvement to the shortcut table. Two minor suggestions for link text clarity.". Then, activate Submit review. It is a checklist, but a meaningful one: every item creates evidence that the next step is safe.

      -

      Jamie: What makes this practice feel low-stakes but still real?

      -

      Alex: This is where Completing Challenge 12: Submit Your Evidence becomes real: open your assigned Challenge 12 issue and post a completion comment. That matters in practice: Close your Challenge 12 issue when done.

      +

      Jamie: Okay, set the room for us. What are we walking into?

      +

      Alex: Start with Forum-Style Conversations Beyond Issues and Pull Requests: GitHub Discussions is a built-in community forum for repositories and organizations. The next useful detail is this: It's where open-ended conversations live - questions, ideas, announcements, polls, and community Q&A - separate from the action-oriented world of issues and pull requests.

      +

      Alex: A solid issue habit is to read the title, the body, and the timeline before acting. You are listening for the requested action, the missing evidence, and the person who needs a response.

      +

      Alex: The next layer is this. Start with Learning Cards: GitHub Discussions. There is something to understand, something to try, and something that proves the try worked.

      +

      Alex: The practical anchors are these. The Discussions tab is in the repository's main navigation bar alongside Code, Issues, and Pull Requests -- press T to navigate tab items or K to find the "Discussions" link. Inside a discussion, replies are article elements -- in NVDA press A to jump between replies; in JAWS use A as well. The reply editor uses the same behavior as issue comments -- enter Focus Mode to type, then press Ctrl+Enter to submit. Discussion categories appear as a sidebar panel on the left or right depending on viewport width -- look for the category list with item counts. Answered discussions in the Q&A category display a green "Answered" badge next to the title, with the accepted answer pinned to the top. Polls show percentage bars next to each option after you vote -- the bars use color fill to indicate proportion.

      +

      Jamie: Can you translate that into plain choices?

      +

      Alex: This is where 1. Discussions vs. Issues: When to Use Which becomes real: not every conversation belongs in an issue. That matters in practice: GitHub Discussions exists for the conversations that don't fit.

      +

      Alex: Use the comparison to make a decision, not to recite a table. The main contrasts are: Use Issues When means Use Discussions When. You found a bug means You have a question about how something works. You want to request a specific feature means You want to brainstorm ideas before filing a feature request.

      -

      Alex: Keep the teaching thread moving. Start with Expected Outcomes. There is something to understand, something to try, and something that proves the try worked.

      -

      Alex: The practical takeaway is this. Student can navigate PR diffs with a screen reader. Student can post inline comments on specific lines of a diff. Student can write constructive, specific feedback that helps the author improve. Student can submit a formal review verdict.

      -

      Jamie: What is the teaching move inside If You Get Stuck?

      -

      Alex: The reason If You Get Stuck matters is that continue learning: The GitHub Skills courses Review Pull Requests and Code Review with GitHub Copilot cover review workflows and AI-assisted code review. That gives the learner a simple foothold: see Appendix Z for the full catalog.

      -

      Alex: First, files Changed tab will not open? Reload the PR page and retry. Make sure you are on the PR page, not the issue page. Then, cannot find the inline comment button? Tab through the line controls in the diff. The button may be announced as "Add a comment" or have a + label. If you cannot find it, use the "Review changes" button at the top to add a general comment instead. After that, not sure what to comment on? Focus on clarity: is every heading descriptive? Is every link meaningful? Are steps complete? Are keyboard shortcuts correct? Finally, review verdict button not working? Make sure you have at least one comment or have written summary text. Try reloading the page. The rhythm is simple: orient, act, verify, then continue.

      -

      Jamie: If someone only remembers one thing from If You Get Stuck, what should it be?

      -

      Alex: First, submitting the review fails? Check that you are not in draft mode and have at least read access to the repo. Then, ask facilitator to model one inline comment and one verdict submission. After that, finished but not sure you did it right? Compare your work against the Challenge 12 reference solution. Think of it as a rail line: each stop confirms you are still on the right route before the next one.

      -

      Alex: Keep the teaching thread moving. Start with Learning Moment: Specific, kind feedback helps authors improve and builds trust in the community. The next useful detail is this: Every comment you write is practice for the professional code review you will do on real projects.

      +

      Alex: Now bring the learner back to the room. Start with Common Discussions categories you'll encounter. There is something to understand, something to try, and something that proves the try worked.

      +

      Alex: For a learner, the useful signals are these. Q&A - Support questions and answers (one answer can be marked correct). Ideas - Feature brainstorming before a formal feature request. Announcements - Maintainer posts about releases, breaking changes, roadmaps. General - Everything else. Show and Tell - Community members showing what they built.

      +

      Jamie: What is the ordered workflow?

      +

      Alex: The reason From a Repository matters is that if the tab is missing: Discussions is an opt-in feature. That gives the learner a simple foothold: the repository maintainer must enable it in Settings.

      +

      Alex: First, navigate to the repository. Then, there is a Discussions tab in the main navigation (alongside Code, Issues, Pull Requests, Actions, Projects). After that, press T to navigate tab items, or K to navigate links and find "Discussions". Finally, press Enter to open. The rhythm is simple: orient, act, verify, then continue.

      +

      Alex: The useful habit is simple: orient first, act second, verify third. That pause before acting is part of the work.

      +

      Jamie: Give me the sequence, because order matters here.

      +

      Alex: Start with From an Organization: Large organizations can have organization-level Discussions separate from any individual repository. Think of it like entering a new building: first you find the lobby, then the room, then the door you actually need.

      +

      Alex: First, navigate to the organization page. Then, look for the Discussions tab at the organization level. After that, these are community-wide conversations, not repo-specific. Think of it as a rail line: each stop confirms you are still on the right route before the next one.

      -

      Jamie: Before we leave Learning Pattern Used in This Chapter, what is the practical point?

      -

      Alex: First, read the full diff before commenting (understand the author's intent first). Then, find specific items to comment on (lines, phrases, missing steps). After that, write comments that help, not just criticize (suggest improvements, note what works). Finally, choose a verdict that matches the substance of your feedback. Treat it like a recipe: do not add the next ingredient until the previous one is actually in the bowl.

      -

      Jamie: What is the teaching move inside Learning Pattern Used in This Chapter?

      -

      Alex: First, summarize your overall impression in 1-2 sentences. It is a checklist, but a meaningful one: every item creates evidence that the next step is safe.

      -

      Alex: Keep the teaching thread moving. This is where Before starting this chapter, verify you have completed becomes real: estimated time for this chapter: 1 hour (including exercises). The workshop is closer to rehearsal than lecture. You hear the move, try the move, and then check what changed.

      -

      Alex: The practical takeaway is this. [ ] Chapter 6: Working with Pull Requests - Understand PR structure, diffs, and comment workflows. [ ] Chapter 13: GitHub Copilot - VS Code installed and configured. [ ] Screen Reader Setup - NVDA, JAWS, or VoiceOver installed and ready to use. [ ] Access to at least one pull request to review (your own fork or a practice repo).

      -

      Jamie: Let's pause on Two Environments for Code Review. What should a learner take away from it?

      -

      Alex: Keep the learner anchored in Two Environments for Code Review. You can review pull requests in two places - each with different strengths. This is the part to say slowly: Both environments give you full keyboard and screen reader access.

      +

      Jamie: If I am listening before the workshop starts, what should settle in my mind first?

      +

      Alex: Here is the plain-English version of 3. Discussion Categories. The Discussions home page is organized by category. Put another way, each category is a section with its own heading.

      +

      Alex: This is where the talk moves from concept to action. Start with The side panel (left or right depending on view width) shows. There is something to understand, something to try, and something that proves the try worked.

      +

      Alex: The room should hear these as checkpoints. All categories with item counts. Pin/announcements section at top. Most active discussions. Tags (if the repo uses them).

      +

      Jamie: Turn that into a path someone can follow.

      +

      Alex: Start with 4. Creating a Discussion. There is something to understand, something to try, and something that proves the try worked.

      +

      Alex: These are the details that keep the idea from floating away. Title - Clear and searchable. "How do I use the daily-briefing agent?" not "Help". Body - Use Markdown. Same editor as issues. For Q&A category: phrase the title as a question.

      +

      Alex: First, from the Discussions tab, activate "New discussion" button. Then, select a category (required - affects which fields appear). After that, fill in. Finally, activate "Start discussion". It is like walking a hallway with named doors: read the sign, enter the right room, then confirm where you landed.

      -

      Jamie: What should they understand before typing anything?

      -

      Alex: The reason About Learning Cards in This Chapter matters is that each review step includes expandable learning cards for different interaction styles. That gives the learner a simple foothold: open the one that matches how you work.

      -

      Alex: Treat examples as spoken recipes, not decorations. You may hear something like View the full PR diff in your terminal; gh pr diff 42; View PR details (description, status, checks); gh pr view 42; Checkout the PR branch locally for testing; gh pr checkout 42; Approve the PR; gh pr review 42 --approve --body "Heading hierarchy looks. Read the command, understand what it changes, then run it only when the repository state matches the lesson.

      -

      Jamie: Let's pause on Good News: Modern Interface is Default. What should a learner take away from it?

      -

      Alex: Start with Good News: Modern Interface is Default: As of January 2026, GitHub's improved Files Changed experience is enabled by default. The next useful detail is this: The instructions below assume you have the modern interface (which you do).

      -

      Jamie: Let's pause on Step 1: Reach the Files Changed Tab. What should a learner take away from it?

      -

      Alex: Here is the plain-English version of Step 1: Reach the Files Changed Tab. Click the Files changed tab at the top of the PR page. Put another way, the tab label shows the number of changed files (e.g., "Files changed 4"). It is like learning a transit route. The names of the stops matter because they tell you whether you are still going the right direction.

      -

      Alex: First, the PR tabs (Conversation, Commits, Checks, Files changed) are across the top of the PR page. At high zoom they may wrap to multiple lines. Then, the Files changed tab includes a badge with the number of changed files. This badge uses text (not colour alone) so it is visible in all themes. After that, after clicking Files changed, the diff page loads. At high zoom, the file tree panel on the left may collapse automatically. Click the file tree toggle (a small panel icon) or press T to toggle it back. Finally, added lines use a green background; removed lines use red. In high contrast browser settings (Windows: Settings Accessibility Contrast themes), these colours map to strong border indicators. Treat it like a recipe: do not add the next ingredient until the previous one is actually in the bowl.

      -

      Jamie: Before we leave Step 1: Reach the Files Changed Tab, what is the practical point?

      -

      Alex: First, use Ctrl++ to zoom the browser if the diff text is too small, and Ctrl+- to zoom out. It is a checklist, but a meaningful one: every item creates evidence that the next step is safe.

      -

      Alex: Treat examples as spoken recipes, not decorations. You may hear something like Press D → navigate to "Pull request navigation tabs" landmark; Press → or Tab → find "Files changed" link → Enter. Read the command, understand what it changes, then run it only when the repository state matches the lesson.

      +

      Alex: Before the learner moves on. The reason Screen reader path matters is that before posting a question: Search existing discussions first. That gives the learner a simple foothold: use the search bar at the top of the Discussions page or GitHub's global search with repo:owner/name in:discussions. The interface gets friendlier when it stops being a wall of controls and starts being a set of named places.

      +

      Alex: A solid navigation habit is to prove where you are before activating controls. Headings, landmarks, and the address bar are not trivia; they are your map.

      +

      Jamie: What would you say to someone who is already bracing for this to be too much?

      +

      Alex: Start with Learning Cards: Creating a Discussion. There is something to understand, something to try, and something that proves the try worked.

      +

      Alex: A few details make that real. Tab to the "New discussion" button from the Discussions tab, then press Enter -- the form loads with a category selector first; arrow through categories and press Enter to select. The title field comes after the category selector -- type a clear, searchable title; for Q&A category, phrase it as a question so it reads naturally in search results. The body editor is the same as the issue comment editor -- enter Focus Mode to type, use Markdown formatting, and press Ctrl+Enter to submit the discussion. The category selector appears as a list or grid of labeled options -- each category has a name and description; zoom in to read the descriptions and pick the right one. The title and body fields stack vertically in a single-column layout -- the form is the same width as the main content area, making it easy to scan at high zoom. After creating a discussion, a green success banner appears at the top -- scroll up if you do not see confirmation at your current zoom position.

      +

      Alex: Hold that next to this. Here is the plain-English version of Reading a Discussion. A discussion page is structured similarly to an issue.

      +

      Alex: That shows up in the workshop in a few specific ways. The original post at the top. Replies in chronological order. An "Answered" reply pinned to the top (Q&A category only). A reply editor at the bottom.

      -

      Jamie: Let's pause on Step 2: Use the File Tree to Orient Yourself. What should a learner take away from it?

      -

      Alex: This is where Step 2: Use the File Tree to Orient Yourself becomes real: the file tree panel lists every changed file. That matters in practice: Before reading any diff, scan this list to understand the scope of the PR.

      -

      Jamie: Let's pause on What to listen for / look for. What should a learner take away from it?

      -

      Alex: Keep the learner anchored in What to listen for / look for. Low vision users (zoom, high contrast).

      -

      Alex: The practical takeaway is this. How many files changed? Which areas of the codebase are affected? Are there unexpected files (generated files, lock files, configuration changes)?

      -

      Alex: First, the file tree shows each filename with a colour-coded bar indicating lines added (green) and removed (red). In high contrast mode, these bars may be less visible - the +N / -N text badge next to each file is the reliable indicator. Then, at high zoom, long file paths truncate. Hover over a truncated name to see the full path in a tooltip. After that, if the file tree panel is too narrow at high zoom, drag its right edge to widen it, or toggle it off and use heading navigation (H key) to move between file diffs. It is like walking a hallway with named doors: read the sign, enter the right room, then confirm where you landed.

      -

      Jamie: How do you keep commands from becoming magic words?

      -

      Alex: The reason Step 3: Navigate Between File Diffs matters is that each changed file in the main area is an h3 heading containing the filename. That gives the learner a simple foothold: scroll through the page or click a filename in the file tree on the left.

      -

      Alex: Treat examples as spoken recipes, not decorations. You may hear something like Press 3 to jump file-by-file through the diff; Listen for: "learning-room/docs/keyboard-shortcuts.md - collapsed" or "expanded"; Press Enter or Space to expand a collapsed file. Quick Nav H or VO+Cmd+H to jump file-by-file through the diff; Listen for: "learning-room/docs/keyboard-shortcuts.md - collapsed" or "expanded"; VO+Space to expand a collapsed file. Read the command, understand what it changes, then run it only when the repository state matches the lesson.

      +

      Jamie: What does the learner do first, second, and then after that?

      +

      Alex: Start with Replying to a Discussion. There is something to understand, something to try, and something that proves the try worked.

      +

      Alex: First, navigate to the bottom of the page (or use the "Reply" button on a specific comment). Then, the reply text area behaves identically to issue comments. After that, focus Mode → type your reply. Finally, ctrl+Enter to submit. It is a checklist, but a meaningful one: every item creates evidence that the next step is safe.

      +

      Alex: That connects to another useful point. Keep the learner anchored in Replying to a Specific Comment (Nested Reply). Each comment has a Reply button below it. A good GitHub workflow is like a well-run meeting: everyone knows the topic, the next action, and who has the floor.

      +

      Jamie: What is the one idea that makes the next few steps less mysterious?

      +

      Alex: The reason Upvoting matters is that instead of leaving "+1" comments, use the thumbs-up reaction on the original post or replies. That gives the learner a simple foothold: many maintainers sort discussion responses by upvotes to prioritize most-needed answers.

      -

      Jamie: Let's pause on Step 4: Read a Diff. What should a learner take away from it?

      -

      Alex: Start with Step 4: Read a Diff: Low vision users (zoom, high contrast). The next useful detail is this: Screen reader users - VoiceOver (macOS). Think of it like entering a new building: first you find the lobby, then the room, then the door you actually need.

      -

      Alex: The practical takeaway is this. Green highlighted lines (with a +) = lines added. Red highlighted lines (with a -) = lines removed. Plain/white lines = unchanged context. Use Ctrl+F to search within the page for specific text in the diff.

      -

      Alex: First, colour is not the only indicator. Every added line has a + character in the gutter; every removed line has a -. These text characters are reliable regardless of colour settings. Then, at high zoom, long lines of code wrap. The +/- gutter character stays at the beginning of the first line, so look left to determine the change type. After that, use Ctrl+F (browser find) to search for specific text across the entire diff page. Finally, if the diff is split view (side by side), it may be very wide at high zoom. Switch to unified diff mode: click the gear icon in the Files Changed toolbar and select "Unified" - this shows old and new in a single column. Think of it as a rail line: each stop confirms you are still on the right route before the next one.

      -

      Jamie: Before we leave Step 4: Read a Diff, what is the practical point?

      -

      Alex: First, high contrast themes in Windows (Settings Accessibility Contrast themes) make the +/- lines use bold border patterns instead of subtle colour shading. Treat it like a recipe: do not add the next ingredient until the previous one is actually in the bowl.

      -

      Alex: Treat examples as spoken recipes, not decorations. You may hear something like Press T to jump to the diff table then Insert+Space (Focus Mode); Press Down Arrow to move through lines one at a time; Press Ctrl+Alt+Right Arrow to read across columns: line number, change type, code content. Press T to jump to the diff table then Insert+Z (Virtual PC Cursor off); Press Down Arrow to move through lines; Press Ctrl+Alt+Right Arrow for column-by-column reading. Read the command, understand what it changes, then run it only when the repository state matches the lesson.

      -

      Jamie: Let's pause on What each line announces / shows. What should a learner take away from it?

      -

      Alex: Here is the plain-English version of What each line announces / shows. If the code on a line is very long, the screen reader will read the full line. Put another way, for minified or generated files, consider collapsing the file in the tree and skipping it.

      -

      Alex: The practical takeaway is this. Added lines: "+ [code content]" - or announced as "inserted". Removed lines: "- [code content]" - or announced as "deleted". Context lines: code without a + or -.

      -

      Jamie: Let's pause on Step 5: Place an Inline Comment. What should a learner take away from it?

      -

      Alex: This is where Step 5: Place an Inline Comment becomes real: when you have a specific observation about a particular line, place an inline comment directly on it. That matters in practice: Screen reader users (VoiceOver - macOS).

      -

      Alex: First, hover your mouse over a line in the diff - a blue + (comment) button appears on the left. Then, click it to open the inline comment box. After that, type your comment. Finally, click "Start a review" (not "Add single comment" - see note below). It is a checklist, but a meaningful one: every item creates evidence that the next step is safe.

      +

      Alex: Here is the practical turn. Start with 6. Marking an Answer: In the Q&A category, one reply can be marked as the accepted answer. The next useful detail is this: This is similar to Stack Overflow's "accepted answer" mechanic.

      +

      Jamie: How would you walk the room through that step by step?

      +

      Alex: Here is the plain-English version of To mark an answer (as the discussion author). Why it matters: Marked answers make Q&A discussions into searchable documentation. Put another way, anyone who searches for the same question later immediately sees the correct answer without reading the whole thread.

      +

      Alex: First, navigate to the reply you want to mark as the answer. Then, look for the "Mark as answer" button below the reply. After that, activate it - the reply is pinned to the top and the discussion shows a green "Answered" badge. Treat it like a recipe: do not add the next ingredient until the previous one is actually in the bowl.

      +

      Alex: Keep the thread going. This is where 7. Polls becomes real: some discussion categories support embedded polls. That matters in practice: A poll lets you gather structured vote data from the community. The workshop is closer to rehearsal than lecture. You hear the move, try the move, and then check what changed.

      -

      Jamie: Let's pause on Placing a multi-line comment. What should a learner take away from it?

      -

      Alex: Keep the learner anchored in Placing a multi-line comment. Click and drag across multiple line numbers in the diff gutter to select a range. This is the part to say slowly: A comment button appears for the selected range.

      -

      Jamie: Let's pause on Step 6: Read Existing Comments and Threads. What should a learner take away from it?

      -

      Alex: The reason Step 6: Read Existing Comments and Threads matters is that inline comments from other reviewers appear as h3 headings within the diff table. That gives the learner a simple foothold: each thread shows: reviewer username, comment body, replies, a "Reply" link and resolution button. The interface gets friendlier when it stops being a wall of controls and starts being a set of named places.

      -

      Alex: Treat examples as spoken recipes, not decorations. You may hear something like Tab to the "Resolve conversation" button → Enter. Tab to the "Resolve conversation" button → VO+Space. Read the command, understand what it changes, then run it only when the repository state matches the lesson.

      -

      Jamie: Let's pause on Step 7: Submit Your Review. What should a learner take away from it?

      -

      Alex: Start with Step 7: Submit Your Review: Screen reader users (VoiceOver - macOS).

      -

      Alex: First, click the "Review changes" button (top-right of the Files Changed page or bottom of the PR). Then, a dialog opens with a summary text area and three radio buttons: Comment / Approve / Request changes. After that, optionally type an overall summary in the text area. Finally, select your verdict. Think of it as a rail line: each stop confirms you are still on the right route before the next one.

      -

      Jamie: Before we leave Step 7: Submit Your Review, what is the practical point?

      -

      Alex: First, click "Submit review". Treat it like a recipe: do not add the next ingredient until the previous one is actually in the bowl.

      +

      Jamie: Let's pause on Creating a poll. What should a learner take away from it?

      +

      Alex: Start with Creating a poll. There is something to understand, something to try, and something that proves the try worked.

      +

      Alex: First, when creating a discussion, look for the "Add a poll" option below the body editor. Then, type each poll option (up to 8 options). After that, set poll duration (optional). Finally, submit the discussion - the poll appears inline. It is like walking a hallway with named doors: read the sign, enter the right room, then confirm where you landed.

      +

      Alex: Another way to ground it. The reason Voting in a poll matters is that poll results: After voting, percentages appear next to each option. That gives the learner a simple foothold: screen readers announce the count and percentage per option.

      +

      Jamie: Where do you want a learner to place their attention here?

      +

      Alex: Start with NVDA note. There is something to understand, something to try, and something that proves the try worked.

      +

      Alex: The parts worth keeping in working memory are these. Browse mode (NVDA+Space) to read the discussion. Enter application mode for the reply editor. Discussion replies are elements - NVDA announces "article" as you navigate with H.

      -

      Jamie: Let's pause on Step 8: Re-request Review (for Authors). What should a learner take away from it?

      -

      Alex: Here is the plain-English version of Step 8: Re-request Review (for Authors). After you address review comments on your own PR. Put another way, look in the right sidebar for the Reviewers section.

      -

      Alex: Treat examples as spoken recipes, not decorations. You may hear something like Step 1: From your PR's Conversation tab, Quick Nav H or VO+Cmd+H to find the "Reviewers" heading in the sidebar; Step 2: Tab or Quick Nav B to find the re-request icon ("Re-request review") next to the reviewer's name; Step 3: VO+Space to activate - this. Read the command, understand what it changes, then run it only when the repository state matches the lesson.

      -

      Jamie: Let's pause on Learning Cards: Reviewing on GitHub.com. What should a learner take away from it?

      -

      Alex: Start with Learning Cards: Reviewing on GitHub.com. There is something to understand, something to try, and something that proves the try worked.

      -

      Alex: The practical takeaway is this. In the Files Changed tab, press T to jump to the diff table, then use Focus Mode (Insert+Space in NVDA, Insert+Z in JAWS) and Down Arrow to read line by line -- each added line starts with + and each removed line with -. To place an inline comment, navigate to the target line and press Tab or B to find the "Add a comment to this line" button; after typing your comment, choose "Start a review" (not "Add single comment") to batch all feedback into one notification. Submit your full review by pressing B repeatedly to find the "Review changes" button; the dialog contains a radio group (Comment / Approve / Request changes) navigable with Arrow keys, then Tab to "Submit review". Switch from split diff to unified diff (gear icon in the Files Changed toolbar then select "Unified") to show old and new code in a single column -- much easier to follow at high zoom than two side-by-side panes. The blue + comment button appears in the line gutter on hover; at high zoom it may be small -- use Ctrl++ to increase browser zoom and look just left of the line number column. The "Review changes" dialog uses clearly labeled radio buttons for the three verdict types; each label includes a brief description, and the currently selected option has a filled circle indicator visible in all themes.

      -

      Alex: Keep the teaching thread moving. Keep the learner anchored in Reviewing in VS Code with the Accessible Diff Viewer. When you check out a branch locally, VS Code's diff editor offers the Accessible Diff Viewer - a purpose-built, line-by-line reading mode designed specifically for screen readers. A good GitHub workflow is like a well-run meeting: everyone knows the topic, the next action, and who has the floor.

      +

      Alex: This is the part worth saying out loud. Start with JAWS note. There is something to understand, something to try, and something that proves the try worked.

      +

      Alex: On the ground, that means a few things. A key navigates elements - useful for jumping between replies. Use Forms Mode for the reply editor.

      +

      Jamie: Give me the version that sounds like an instructor, not a manual.

      +

      Alex: Start with VoiceOver note. There is something to understand, something to try, and something that proves the try worked.

      +

      Alex: Here is what that changes in practice. VO+Right to read through content. VO+Command+L to list all links (useful for navigating many replies quickly). VO+Space on the reply field to enter interaction mode.

      +

      Alex: That matters because of the next idea. Keep the learner anchored in 9. Organization-Level Discussions. Some organizations enable Discussions at the organization level, separate from any repository. This is the part to say slowly: These work identically to repository discussions but span the whole organization.

      +

      Alex: That becomes easier when you listen for these cues. Org-wide announcements. Community introductions ("Introduce yourself" pinned thread). Cross-repo feature brainstorming. Community spotlights and events.

      -

      Jamie: Let's pause on Opening a Diff in VS Code. What should a learner take away from it?

      -

      Alex: The reason Opening a Diff in VS Code matters is that if you have the GitHub Pull Requests extension. That gives the learner a simple foothold: without the extension, any git diff operation also opens the diff editor.

      -

      Alex: First, open the GitHub Pull Requests view (Explorer sidebar or Ctrl+Shift+P → "GitHub Pull Requests: View Pull Request"). Then, find the PR and open it - changed files appear in the file tree. After that, navigate to any file in the tree and press Enter to open its diff view. The rhythm is simple: orient, act, verify, then continue.

      -

      Jamie: Let's pause on Learning Cards: VS Code Code Review. What should a learner take away from it?

      -

      Alex: Start with Learning Cards: VS Code Code Review: Low vision users (zoom, high contrast). The next useful detail is this: VS Code's diff editor works well at high zoom.

      -

      Alex: First, split view vs. inline: By default, VS Code shows diffs in a split (side-by-side) view. At high zoom this can be very cramped. Switch to inline mode: Ctrl+Shift+P then type "Toggle Inline View" in any diff editor. Inline mode shows old and new code in a single. Then, colour indicators: Added lines have a green gutter bar; removed lines have a red gutter bar. In high contrast themes, these use heavy solid borders that are visible even at extreme zoom levels. After that, change navigation: Press F7 to jump to the next change and Shift+F7 for the previous. Each change is highlighted with a visible focus box that moves with your position - much easier than scrolling at high zoom. Finally, minimap in diff view: The minimap (right edge) shows an overview of changes as coloured blocks. At high zoom the minimap may be too small to be useful - disable it via Settings if it adds visual noise. Think of it as a rail line: each stop confirms you are still on the right route before the next one.

      -

      Jamie: Before we leave Learning Cards: VS Code Code Review, what is the practical point?

      -

      Alex: First, font size for diffs: Diff editors use your configured editor font size (editor.fontSize). Increase this in Settings (Ctrl+,) if the diff text is too small at your zoom level. Then, comment highlight: When you add a comment through the GitHub PR extension, the commented line gets a distinct background. In high contrast themes this is a solid colour band. Treat it like a recipe: do not add the next ingredient until the previous one is actually in the bowl.

      -

      Jamie: Let's pause on Opening the PR for review. What should a learner take away from it?

      -

      Alex: Start with Opening the PR for review. There is something to understand, something to try, and something that proves the try worked.

      -

      Alex: First, press Ctrl+Shift+P, type "GitHub Pull Requests: View Pull Request". Then, the PR tree appears in the sidebar - navigate with Down Arrow. After that, each changed file is announced with its name and change summary. Finally, press Enter on a file to open its diff editor. Treat it like a recipe: do not add the next ingredient until the previous one is actually in the bowl.

      -

      Jamie: Before we leave Opening the PR for review, what is the practical point?

      -

      Alex: First, the diff editor opens with the standard VS Code diff layout. It is a checklist, but a meaningful one: every item creates evidence that the next step is safe.

      +

      Jamie: Let's pause on 10. Accessibility Agents: What's Different Here. What should a learner take away from it?

      +

      Alex: The reason 10. Accessibility Agents: What's Different Here matters is that accessibility Agents prompts currently operate on issues, PRs, and code - not directly on Discussions. That gives the learner a simple foothold: if you want to respond to a discussion using Accessibility Agents.

      +

      Alex: First, copy the discussion URL or content. Then, use /issue-reply with the content pasted in: the agent will draft a thoughtful, accessible response. After that, paste the result back into the discussion reply editor. The rhythm is simple: orient, act, verify, then continue.

      +

      Alex: A solid pull request habit is to separate three questions: what changed, why it changed, and what still needs review. That keeps the conversation useful instead of noisy.

      +

      Alex: Keep the teaching thread moving. Start with Shareable Code Snippets and Notes: Gists are a simple way to share code snippets, notes, or small files without creating a full repository. The next useful detail is this: Think of them as lightweight, version-controlled pastebins. Think of it like entering a new building: first you find the lobby, then the room, then the door you actually need.

      +

      Jamie: Let's pause on Learning Cards: GitHub Gists. What should a learner take away from it?

      +

      Alex: Start with Learning Cards: GitHub Gists. There is something to understand, something to try, and something that proves the try worked.

      +

      Alex: The practical takeaway is this. On the Gist creation page at gist.github.com, press D to jump to the main landmark, then F to navigate form fields: Description, Filename, Content, and Visibility buttons. Your Gists page lists each gist as an H2 heading with its description -- press 2 or H to jump between gists. Gists are full Git repositories -- you can clone them with git clone and edit locally using your usual screen reader workflow in VS Code. Gist pages use syntax highlighting matching GitHub's current theme -- switch between light and dark mode for comfortable reading. Public and secret gists look identical on the page; the only difference is the URL visibility -- check the "Create secret gist" or "Create public gist" button label before submitting. The revision history link appears at the top of any gist -- click "Revisions" to see a diff view of every edit.

      -

      Jamie: Let's pause on Using the Accessible Diff Viewer. What should a learner take away from it?

      -

      Alex: Start with Using the Accessible Diff Viewer. There is something to understand, something to try, and something that proves the try worked.

      -

      Alex: First, in the diff editor, press F7 to open the Accessible Diff Viewer. Then, NVDA announces: "Changed lines X to Y in filename, Change 1 of N". After that, the viewer shows each change with "Removed:" and "Added:" labels. Finally, press F7 to move to the next change, Shift+F7 for previous. It is a checklist, but a meaningful one: every item creates evidence that the next step is safe.

      -

      Jamie: Before we leave Using the Accessible Diff Viewer, what is the practical point?

      -

      Alex: First, press Escape when done to close the viewer. It is like walking a hallway with named doors: read the sign, enter the right room, then confirm where you landed.

      -

      Jamie: Let's pause on Placing a comment. What should a learner take away from it?

      -

      Alex: Keep the learner anchored in Placing a comment. Screen reader users (VoiceOver on macOS).

      -

      Alex: First, navigate to the line you want to comment on in the diff. Then, press Ctrl+Shift+P, type "GitHub Pull Requests: Add Comment". After that, a text area opens below the line - NVDA announces the input focus. Finally, type your comment. It is like walking a hallway with named doors: read the sign, enter the right room, then confirm where you landed.

      -

      Jamie: Before we leave Placing a comment, what is the practical point?

      -

      Alex: First, press Tab to the Submit button, then Enter. The rhythm is simple: orient, act, verify, then continue.

      -

      Jamie: Let's pause on Opening the PR. What should a learner take away from it?

      -

      Alex: Start with Opening the PR. There is something to understand, something to try, and something that proves the try worked.

      -

      Alex: First, press Cmd+Shift+P, type "GitHub Pull Requests: View Pull Request". Then, navigate the PR tree with VO+Down Arrow. After that, press Return on a file to open its diff. The rhythm is simple: orient, act, verify, then continue.

      +

      Alex: Keep the teaching thread moving. This is where What Is a Gist? becomes real: a Gist is a Git repository that holds a single file or a small collection of files. That matters in practice: Anyone with the URL can view a secret Gist.

      +

      Alex: The practical takeaway is this. Has its own URL (e.g., gist.github.com/username/a1b2c3d4). Is version-controlled (you can see edit history). Can be public (anyone can see) or secret (only people with the link can see). Supports Markdown rendering.

      +

      Jamie: How should someone choose between those options?

      +

      Alex: Start with When to Use a Gist vs a Repository. There is something to understand, something to try, and something that proves the try worked.

      +

      Alex: Use the comparison to make a decision, not to recite a table. The main contrasts are: Use a Gist When. means Use a Repository When. Sharing a single code snippet means Building a full project. Posting configuration examples means Collaborating with multiple people.

      +

      Jamie: Let's pause on Via GitHub Web Interface. What should a learner take away from it?

      +

      Alex: Start with Via GitHub Web Interface. There is something to understand, something to try, and something that proves the try worked.

      +

      Alex: The practical takeaway is this. Select "Create public gist" for openly shareable content. Select "Create secret gist" for link-only sharing.

      +

      Alex: First, navigate to gist.github.com. Then, gist description: A short title (e.g., "NVDA configuration for GitHub"). After that, filename: Name your file with extension (e.g., nvda-config.txt, script.py, notes.md). Finally, content: Paste or type your code/text. The rhythm is simple: orient, act, verify, then continue.

      +

      Jamie: Before we leave Via GitHub Web Interface, what is the practical point?

      +

      Alex: First, visibility. Then, the Gist is created with a unique URL you can share. Think of it as a rail line: each stop confirms you are still on the right route before the next one.

      -

      Jamie: Let's pause on Accessible Diff Viewer. What should a learner take away from it?

      -

      Alex: Start with Accessible Diff Viewer. There is something to understand, something to try, and something that proves the try worked.

      -

      Alex: First, press F7 in the diff editor. Then, VoiceOver announces each change with clear "Removed" and "Added" labels. After that, navigate with F7/Shift+F7. Finally, press Escape to close. Think of it as a rail line: each stop confirms you are still on the right route before the next one.

      -

      Jamie: Let's pause on Comment placement. What should a learner take away from it?

      -

      Alex: Start with Comment placement. There is something to understand, something to try, and something that proves the try worked.

      -

      Alex: First, press Cmd+Shift+P, type "GitHub Pull Requests: Add Comment". Then, vO+Shift+Down Arrow to interact with the comment text area. After that, type your comment. Finally, vO+Shift+Up Arrow to stop interacting, then Tab to Submit. Treat it like a recipe: do not add the next ingredient until the previous one is actually in the bowl.

      -

      Jamie: Let's pause on Using the Accessible Diff Viewer (F7). What should a learner take away from it?

      -

      Alex: This is where Using the Accessible Diff Viewer (F7) becomes real: the Accessible Diff Viewer reads each change as a structured block. That matters in practice: This example is from a real Learning Room scenario: a contributor fixing the heading hierarchy in docs/keyboard-shortcuts.md by changing a level-4 heading to level-3, which is exactly what you look for when reviewing Challenge 2 PRs.

      -

      Alex: Treat examples as spoken recipes, not decorations. You may hear something like "Changed lines 14 to 14 in docs/keyboard-shortcuts.md; [Change 1 of 3]; Removed:; NVDA Single-Key Navigation; Added:; NVDA Single-Key Navigation". Read the command, understand what it changes, then run it only when the repository state matches the lesson.

      +

      Jamie: Let's pause on Screen reader navigation. What should a learner take away from it?

      +

      Alex: Start with Screen reader navigation. There is something to understand, something to try, and something that proves the try worked.

      +

      Alex: The practical takeaway is this. D to cycle landmarks to "Main". F to navigate form fields. Tab through: Description → Filename → Content textbox → Visibility buttons.

      +

      Jamie: Let's pause on Adding Multiple Files to a Gist. What should a learner take away from it?

      +

      Alex: Here is the plain-English version of Adding Multiple Files to a Gist. You can add multiple files to a single Gist. Put another way, use case: Share related config files together (e.g.,.vscode/settings.json +.vscode/keybindings.json).

      +

      Alex: First, after typing the first filename and content, select "Add file" (button below the editor). Then, repeat for each additional file. After that, create the Gist. Treat it like a recipe: do not add the next ingredient until the previous one is actually in the bowl.

      +

      Jamie: Let's pause on Learning Cards: Creating a Gist. What should a learner take away from it?

      +

      Alex: Start with Learning Cards: Creating a Gist. There is something to understand, something to try, and something that proves the try worked.

      +

      Alex: The practical takeaway is this. On the Gist creation page at gist.github.com, press D to jump to the main landmark, then F to navigate form fields in order: Description, Filename, Content textarea, and visibility buttons. The visibility selector is a split button -- the main button creates a public gist; Tab to the dropdown arrow next to it and press Enter to reveal the "Create secret gist" option. Each filename field has a corresponding content textarea directly below it -- after filling one file, Tab to the "Add file" button to add another file to the same gist. The Gist editor uses the same syntax highlighting as regular GitHub files -- your current theme applies; increase font size in browser zoom for comfortable editing. The split button for public vs. secret visibility is at the bottom of the form -- the two options look nearly identical; read the button label carefully ("Create public gist" vs. "Create secret gist") before clicking. The "Add file" button appears below the first file editor as a small text link -- zoom in to find it; each additional file gets its own filename field and content textarea.

      -

      Alex: Keep the teaching thread moving. Start with Navigation. There is something to understand, something to try, and something that proves the try worked.

      -

      Alex: The practical takeaway is this. F7 - jump to next change (next hunk). Shift+F7 - jump to previous change. Alt+F2 - open VS Code's Accessible View for additional context on the current item. Escape - close the Accessible Diff Viewer.

      -

      Jamie: Let's pause on What makes this better than the raw diff editor. What should a learner take away from it?

      -

      Alex: Start with What makes this better than the raw diff editor. There is something to understand, something to try, and something that proves the try worked.

      -

      Alex: The practical takeaway is this. Each change is announced as a discrete unit with clear "Removed:" and "Added:" labels. You hear the change number of total changes ("Change 3 of 12"). No table navigation required - purpose-built for sequential listening. Works with all three major screen readers without any special configuration.

      -

      Alex: Keep the teaching thread moving. Start with Placing Comments in VS Code (GitHub PR Extension): From the diff editor with the GitHub PR extension. The next useful detail is this: Comments placed in VS Code sync to GitHub - they appear in the PR's Files Changed tab and the author receives the same notification. Think of it like entering a new building: first you find the lobby, then the room, then the door you actually need.

      +

      Jamie: Let's pause on Editing a Gist. What should a learner take away from it?

      +

      Alex: Keep the learner anchored in Editing a Gist. Click "Revisions" to see the full edit history. A good GitHub workflow is like a well-run meeting: everyone knows the topic, the next action, and who has the floor.

      +

      Alex: First, navigate to your Gist's URL. Then, select "Edit" (button in the top-right). After that, make your changes. Finally, select "Update public gist" or "Update secret gist". It is like walking a hallway with named doors: read the sign, enter the right room, then confirm where you landed.

      +

      Jamie: Let's pause on Embedding a Gist. What should a learner take away from it?

      +

      Alex: The reason Embedding a Gist matters is that you can embed Gists in web pages, blog posts, or documentation. That gives the learner a simple foothold: GitHub renders it as a formatted code block with syntax highlighting and a link back to the Gist.

      +

      Jamie: What should happen before anyone copies and runs it?

      +

      Alex: Start with Cloning a Gist: Make changes locally, commit, and push just like a normal repo.

      +

      Alex: Treat examples as spoken recipes, not decorations. You may hear something like git clone https://gist.github.com/username/gist-id.git. Read the command, understand what it changes, then run it only when the repository state matches the lesson.

      -

      Jamie: Let's pause on The Anatomy of a Useful Review Comment. What should a learner take away from it?

      -

      Alex: Here is the plain-English version of The Anatomy of a Useful Review Comment. A comment that helps the author is.

      -

      Alex: First, specific - link to the exact line and name the pattern you see. Then, educational - say why something matters, not just what to change. After that, graduated - signal whether this is blocking, or a preference. Treat it like a recipe: do not add the next ingredient until the previous one is actually in the bowl.

      -

      Alex: Keep the teaching thread moving. This is where Blocking example (reviewing a PR for docs/keyboard-shortcuts.md) becomes real: "The heading on line 34 uses (level 4) directly after (level 2), skipping heading level 3. That matters in practice: Screen reader users who navigate by heading level will miss any content between those two levels.

      -

      Jamie: Let's pause on Non-blocking (nit) example (reviewing a PR for docs/welcome.md). What should a learner take away from it?

      -

      Alex: Keep the learner anchored in Non-blocking (nit) example (reviewing a PR for docs/welcome.md). "nit: The link text in the 'Getting Help' section reads 'click here for more information.' Screen reader users who navigate links out of context will hear only 'click here' with no destination. This is the part to say slowly: Consider 'See the accessibility setup guide' instead.

      +

      Jamie: Let's pause on Forking a Gist. What should a learner take away from it?

      +

      Alex: Here is the plain-English version of Forking a Gist. You can fork someone else's Gist to create your own copy. Put another way, use case: Someone shares a useful script, you fork it, and customize it for your needs.

      +

      Alex: First, view the Gist. Then, select "Fork" in the top-right. After that, GitHub creates a new Gist under your account. Treat it like a recipe: do not add the next ingredient until the previous one is actually in the bowl.

      +

      Alex: Keep the teaching thread moving. This is where Finding Your Gists becomes real: your Gists page: gist.github.com/your-username. That matters in practice: All your public and secret Gists are listed here. The workshop is closer to rehearsal than lecture. You hear the move, try the move, and then check what changed.

      +

      Alex: The practical takeaway is this. Search your Gists by filename or content. Star Gists you want to reference later. Delete old Gists.

      +

      Jamie: Before we leave Screen reader navigation, what is the practical point?

      +

      Alex: The practical takeaway is this. Each Gist appears as a heading (H2) with its description. Press 2 or H to jump between Gists. Each Gist has links: "Edit," "Delete," "Star," "Embed".

      -

      Alex: Keep the teaching thread moving. The reason Question example (reviewing a PR for docs/setup-guide.md) matters is that "The PR description says this fixes broken links in the setup guide, but the link on line 12 still points to /docs/old-setup. That gives the learner a simple foothold: am I reading the diff correctly, or was this link intentionally left? The interface gets friendlier when it stops being a wall of controls and starts being a set of named places.

      -

      Jamie: Let's pause on Prefixes That Set Expectations. What should a learner take away from it?

      -

      Alex: Start with Prefixes That Set Expectations: Using shorthand prefixes helps authors parse many comments quickly.

      -

      Alex: Keep the teaching thread moving. Here is the plain-English version of How Many Comments Is Too Many? There is no hard limit, but quantity without prioritization is noise. Put another way, if you have 15 comments, make clear which 2-3 are blocking.

      +

      Alex: Keep the teaching thread moving. The reason Discovering Public Gists matters is that browse trending Gists: gist.github.com/discover.

      +

      Alex: The practical takeaway is this. Useful scripts and utilities. Configuration examples. Code snippets for learning.

      +

      Jamie: Let's pause on Gist Comments. What should a learner take away from it?

      +

      Alex: Start with Gist Comments: Anyone with a GitHub account can leave a comment, making Gists useful.

      +

      Alex: The practical takeaway is this. Asking questions about a snippet. Suggesting improvements. Discussing implementation details.

      +

      Jamie: Let's pause on To add a comment. What should a learner take away from it?

      +

      Alex: Start with To add a comment. There is something to understand, something to try, and something that proves the try worked.

      +

      Alex: First, scroll to the bottom of the Gist page. Then, f to navigate form fields → Find the comment textarea. After that, type your comment (Markdown supported). Finally, ctrl+Enter or activate "Comment" button. Treat it like a recipe: do not add the next ingredient until the previous one is actually in the bowl.

      -

      Jamie: Let's pause on "I want to verify the PR only changes what it claims". What should a learner take away from it?

      -

      Alex: This is where "I want to verify the PR only changes what it claims" becomes real: example: A PR says "Challenge 2: Add NVDA shortcut" but the file tree shows changes to both docs/keyboard-shortcuts.md and docs/welcome.md.

      -

      Alex: Keep the teaching thread moving. Keep the learner anchored in "I want to find all changes to one specific section". Example: A PR for Challenge 3 modified docs/welcome.md. This is the part to say slowly: You want to verify the [TODO] in the "Who Can Contribute?" section was filled in correctly. A good GitHub workflow is like a well-run meeting: everyone knows the topic, the next action, and who has the floor.

      -

      Jamie: Why is the evidence prompt part of the teaching, not just grading?

      -

      Alex: The reason Exercises matters is that these exercises use the files in learning-room/docs/ in this repository. That gives the learner a simple foothold: all examples involve documentation changes - no code required.

      +

      Jamie: Let's pause on Public Gists. What should a learner take away from it?

      +

      Alex: Start with Public Gists. There is something to understand, something to try, and something that proves the try worked.

      +

      Alex: The practical takeaway is this. Appear on your profile. Are indexed by search engines. Anyone can view, fork, and comment.

      +

      Alex: Keep the teaching thread moving. Start with Secret Gists. There is something to understand, something to try, and something that proves the try worked.

      +

      Alex: The practical takeaway is this. Do not appear on your profile. Are not indexed by search engines. Anyone with the URL can view. Still version-controlled and can be starred.

      +

      Jamie: Let's pause on Never put sensitive data in Gists. What should a learner take away from it?

      +

      Alex: The reason Never put sensitive data in Gists matters is that if you accidentally post sensitive data.

      +

      Alex: The practical takeaway is this. Passwords or API keys. Personal identifying information. Proprietary code you don't have permission to share.

      +

      Alex: First, delete the Gist immediately. Then, revoke/regenerate any exposed credentials. After that, remember: Forks and clones may still exist. The rhythm is simple: orient, act, verify, then continue.

      -

      Alex: Keep the teaching thread moving. Start with Exercise A - Complete a Web Review: Scenario: A contributor has submitted a pull request titled "Add screen reader tips to the setup guide." The PR modifies learning-room/docs/setup-guide.md. The next useful detail is this: Your job is to review it before it merges.

      -

      Jamie: Let's pause on Step 1: Navigate to the Pull Request. What should a learner take away from it?

      -

      Alex: Here is the plain-English version of Step 1: Navigate to the Pull Request. How to know you're in the right place.

      -

      Alex: The practical takeaway is this. The PR title is visible at the top. You see a description box with text about what this PR does. You see tabs labeled "Conversation," "Commits," "Files Changed". Use Ctrl+F to search the PR list for "screen reader tips". Or ask in the workshop Slack - someone can share the exact URL.

      -

      Alex: First, open GitHub in your browser and navigate to the workshop repository (github.com/[your-fork]/[workshop-repo] or community-access/accessibility-agents). Then, click the Pull Requests tab (top navigation). After that, look for a PR titled "Add screen reader tips to the setup guide" - click it to open. Finally, you should now see the PR page with sections: Conversation, Commits, Files Changed. Treat it like a recipe: do not add the next ingredient until the previous one is actually in the bowl.

      -

      Jamie: Let's pause on Step 2: Read the PR Description. What should a learner take away from it?

      -

      Alex: Start with Step 2: Read the PR Description. There is something to understand, something to try, and something that proves the try worked.

      -

      Alex: The practical takeaway is this. Does the PR author explain what file changed? (should mention setup-guide.md). Does it explain why? (should mention "improve accessibility" or "add tips"). Is it clear enough that a reviewer can understand the goal without reading the diff? You can answer: "This PR adds [specific content] to [specific file] because [clear reason]". Example: "This PR adds screen reader usage tips to the setup guide because new users need accessibility guidance".

      -

      Alex: First, you are currently on the Conversation tab. Then, read the PR description (the text immediately under the PR title). After that, look for: "What does this PR change?" and "Why does it change it?". Finally, with screen reader: Navigate to the description with D (NVDA) or press Ctrl+Option+Up (VoiceOver) to find main landmarks, then read the content region. It is a checklist, but a meaningful one: every item creates evidence that the next step is safe.

      +

      Jamie: How do you keep commands from becoming magic words?

      +

      Alex: Start with 1. Sharing Screen Reader Config: Share the Gist URL with other screen reader users. Think of it like entering a new building: first you find the lobby, then the room, then the door you actually need.

      +

      Alex: Treat examples as spoken recipes, not decorations. You may hear something like Filename: nvda-github-config.txt; Content:; NVDA Settings for GitHub Web Navigation; - Browse Mode: Use screen layout (enabled); - Verbosity: Most punctuation; - Rate: 65%; - Keyboard shortcuts: Use standard GitHub shortcuts (G+I, G+P, etc.). Read the command, understand what it changes, then run it only when the repository state matches the lesson.

      +

      Jamie: Let's pause on 2. Quick Markdown Note. What should a learner take away from it?

      +

      Alex: Here is the plain-English version of 2. Quick Markdown Note. Reference it later or share with workshop participants.

      +

      Alex: Keep the teaching thread moving. This is where 3. Code Snippet for a StackOverflow Answer becomes real: when answering questions, paste your code as a Gist and link to it. That matters in practice: Readers get syntax highlighting, version history, and the ability to fork your solution.

      -

      Jamie: Let's pause on Step 3: Navigate to "Files Changed". What should a learner take away from it?

      -

      Alex: Start with Step 3: Navigate to "Files Changed". There is something to understand, something to try, and something that proves the try worked.

      -

      Alex: The practical takeaway is this. A section showing the file name setup-guide.md with a small badge showing "+20 −0" (20 lines added, 0 lines removed). Below it, the diff with removed lines (preceded by −) and added lines (preceded by +). Scroll up to see if there are other files. For this exercise, only setup-guide.md should be changed. If you see other files, confirm they are not modified (the badge should show "+0 −0" or no changes).

      -

      Alex: First, click the Files Changed tab (top of the PR page, to the right of "Commits"). Then, you are now viewing the diff. After that, with keyboard (all screen readers): Press T to jump to the diff table. The page focuses on the file comparison area. It is like walking a hallway with named doors: read the sign, enter the right room, then confirm where you landed.

      -

      Jamie: Let's pause on Step 4: Activate Focus Mode for Better Diff Reading. What should a learner take away from it?

      -

      Alex: The reason Step 4: Activate Focus Mode for Better Diff Reading matters is that with screen reader (once in Focus Mode).

      -

      Alex: The practical takeaway is this. The page simplifies: sidebars disappear. Only the diff is visible - easier for screen reader navigation and less cognitive load. The diff is now the main content area. NVDA/JAWS: Press T to jump to the diff table. VoiceOver: Navigate with VO+Right Arrow to find the table/content region. Read through the changes: ↓ arrow moves to each line.

      -

      Alex: First, look for a button labeled "Focus Mode" or an icon (usually at the top right of the diff area). Then, with keyboard: Press F to toggle Focus Mode (may need to be in the diff area first). After that, with mouse: Click the Focus Mode button/icon. The rhythm is simple: orient, act, verify, then continue.

      -

      Jamie: Let's pause on Step 5: Find the Heading Hierarchy Issue. What should a learner take away from it?

      -

      Alex: Start with Step 5: Find the Heading Hierarchy Issue. There is something to understand, something to try, and something that proves the try worked.

      -

      Alex: The practical takeaway is this. Screen reader users navigate documents by heading level: 1 → 2 → 3 → 4. A skip from to breaks that navigation. When a user presses "jump to heading level 3," they'll find none, wondering if content is missing. You found the line with that violates hierarchy. You can say the line number and what heading text appears there. You understand why this is an accessibility problem.

      -

      Alex: First, read through the entire diff line by line. Pay special attention to lines starting. Then, you are looking for: a line with (four hashes, heading level 4) that comes directly after a (two hashes, heading level 2). After that, when you find it, note the exact line number shown in the diff. Think of it as a rail line: each stop confirms you are still on the right route before the next one.

      +

      Jamie: What decision is this helping them make?

      +

      Alex: Start with Gists vs GitHub Repositories - Quick Comparison. There is something to understand, something to try, and something that proves the try worked.

      +

      Alex: Use the comparison to make a decision, not to recite a table. The main contrasts are: Comments means Yes (on issues/PRs).

      +

      Jamie: Let's pause on Deleting a Gist. What should a learner take away from it?

      +

      Alex: The reason Deleting a Gist matters is that next: Appendix V: GitHub Mobile Back: Appendix T: Community and Social Teaching chapter: Chapter 08: Open Source Culture. The interface gets friendlier when it stops being a wall of controls and starts being a set of named places.

      +

      Alex: First, navigate to the Gist. Then, select "Edit". After that, select "Delete" (top-right, after Edit button). Finally, confirm deletion. The rhythm is simple: orient, act, verify, then continue.

      -

      Jamie: Let's pause on Step 6: Place a Blocking Review Comment on the Heading. What should a learner take away from it?

      -

      Alex: Here is the plain-English version of Step 6: Place a Blocking Review Comment on the Heading. If the comment button doesn't appear. It is like learning a transit route. The names of the stops matter because they tell you whether you are still going the right direction.

      -

      Alex: The practical takeaway is this. Your comment appears in the thread under that line. The PR author sees it and can make the fix. Make sure you're hovering over the line number area (left side of the line). Try refreshing the page and trying again. Or use the "Add a reply" field at the bottom of the PR and mention the line number manually.

      -

      Alex: First, find the diff line with the problematic heading. Then, hover your mouse over the line number on the left side of that line (or if using keyboard, navigate to that line in the table). After that, a button should appear (or press the Add Comment hotkey - usually C in GitHub). Finally, click it or press Enter to open a comment box. Treat it like a recipe: do not add the next ingredient until the previous one is actually in the bowl.

      -

      Jamie: Before we leave Step 6: Place a Blocking Review Comment on the Heading, what is the practical point?

      -

      Alex: First, press Space, then explain. Then, click the Comment button (or press Ctrl+Enter for keyboard submit). It is a checklist, but a meaningful one: every item creates evidence that the next step is safe.

      -

      Jamie: Let's pause on Step 7: Find the Link Text Issue. What should a learner take away from it?

      -

      Alex: Start with Step 7: Find the Link Text Issue. There is something to understand, something to try, and something that proves the try worked.

      -

      Alex: The practical takeaway is this. Screen reader users can ask their reader to "list all links on this page" - they hear only the link text. If the text is "click here," they have no context about where it goes. Descriptive link text is WCAG 2.4.4 (Link Purpose). You found a link with non-descriptive text. You can explain why "click here" is bad and what would be better.

      -

      Alex: First, continue reading the diff (from where you left off). Then, look for a line containing link text that reads "click here" or "click here for more information". After that, note the line number. It is a checklist, but a meaningful one: every item creates evidence that the next step is safe.

      -

      Jamie: Let's pause on Step 8: Place a Comment on the Link. What should a learner take away from it?

      -

      Alex: Keep the learner anchored in Step 8: Place a Comment on the Link. nit: means "nice-to-have improvement" (not blocking, but good to fix).

      -

      Alex: First, find the line in the diff with the problematic link. Then, hover over the line number and click to open a comment box (or press C). After that, click Comment or press Ctrl+Enter. It is like walking a hallway with named doors: read the sign, enter the right room, then confirm where you landed.

      +

      Jamie: What should people carry with them after this?

      +

      Alex: Carry the map. Know what page or tool you are in, know which action you are taking, and know what confirmation should follow. If the confirmation is missing, pause. That pause is not wasted time; it is professional judgment.

      +

      Jamie: That is a better way to say it than just follow the steps.

      +

      Alex: Right. Steps matter, but understanding wins. That is episode 23. Next in the series is episode 24, where we keep building the same contributor muscles.

      +
      +
      -

      Jamie: Let's pause on Step 9: Submit Your Review. What should a learner take away from it?

      -

      Alex: Start with Step 9: Submit Your Review. There is something to understand, something to try, and something that proves the try worked.

      -

      Alex: The practical takeaway is this. Comment - provide feedback but don't block (for minor notes). Approve - the PR is ready to merge. Request changes - this PR cannot merge until changes are made. Your review is submitted. The PR author gets a notification. The PR shows your review with the two comments.

      -

      Alex: First, look for a button labeled "Review changes" (usually at the top right of the page or bottom of comments). Then, click it (or navigate with keyboard and press Enter). After that, a dialog appears with options. Finally, select "Request changes" (you found two things to fix). The rhythm is simple: orient, act, verify, then continue.

      -

      Jamie: Before we leave Step 9: Submit Your Review, what is the practical point?

      -

      Alex: First, in the summary field, write: Found 2 accessibility issues that must be fixed before merging. Then, click "Submit review". Think of it as a rail line: each stop confirms you are still on the right route before the next one.

      -

      Jamie: Let's pause on Reflect on This Exercise. What should a learner take away from it?

      -

      Alex: Start with Reflect on This Exercise: Keep your answers - you'll need them for Chapter 16's Accessibility Agents exercise to compare manual review with agent-assisted review. Think of it like entering a new building: first you find the lobby, then the room, then the door you actually need.

      -

      Alex: First, did heading-level navigation help? When you were looking for the issue, was it easier to navigate by heading level (1-6) than to scan every line? Then, would you have caught this without the exercise prompt? If you were a real reviewer not specifically looking for heading issues, would the diff have been obvious? After that, why does screen reader navigation matter? In one sentence, explain why a screen reader user's ability to jump through heading levels is important for this document. Think of it as a rail line: each stop confirms you are still on the right route before the next one.

      -

      Jamie: What stays the same when the tool changes?

      -

      Alex: Here is the plain-English version of Exercise B - Use the VS Code Accessible Diff Viewer. Scenario: Review the same pull request from Exercise A, this time entirely in VS Code. Put another way, you'll compare the browser experience with the VS Code experience.

      +

      15. Episode 24: GitHub Discussions

      +

      Forum-style conversations, Q&A, polls, and navigation with screen readers.

      +

      Based on: Appendix U: GitHub Discussions

      +

      Audio and transcript are being regenerated for this episode.

      +
      +Read Transcript - Episode 24: GitHub Discussions + +

      Transcript

      +

      Alex: Welcome to Git Going with GitHub, episode 24: GitHub Discussions. I am Alex. Today we are going to make GitHub Discussions something you can explain, practice, and recover from when the interface surprises you.

      +

      Jamie: And I am Jamie. I will be the voice of the learner who is willing to ask, what is this for, where am I, and how do I know I did it right?

      -

      Alex: Keep the teaching thread moving. Start with Prerequisites. There is something to understand, something to try, and something that proves the try worked.

      -

      Alex: The practical takeaway is this. VS Code must be installed on your machine. The GitHub Pull Requests extension must be installed (see Chapter 12 for installation). You must be signed into GitHub from VS Code (use Ctrl+Shift+P → "GitHub: Sign in").

      -

      Jamie: Let's pause on Step 1: Open the GitHub Pull Requests Extension. What should a learner take away from it?

      -

      Alex: Start with Step 1: Open the GitHub Pull Requests Extension. There is something to understand, something to try, and something that proves the try worked.

      -

      Alex: The practical takeaway is this. With mouse: Click the Extensions icon on the left sidebar (looks like four squares). The extension is listed as active. It mentions: "Review and manage GitHub pull requests and issues".

      -

      Alex: First, open VS Code. Then, with keyboard (all screen readers): Press Ctrl+Shift+X to open the Extensions sidebar. After that, search for "GitHub Pull Requests". Finally, if it's not installed, click Install. It is like walking a hallway with named doors: read the sign, enter the right room, then confirm where you landed.

      -

      Jamie: Before we leave Step 1: Open the GitHub Pull Requests Extension, what is the practical point?

      -

      Alex: First, if it is installed, click GitHub Pull Requests to view its details. The rhythm is simple: orient, act, verify, then continue.

      -

      Jamie: Let's pause on Step 2: Open the Pull Requests Sidebar. What should a learner take away from it?

      -

      Alex: Start with Step 2: Open the Pull Requests Sidebar. There is something to understand, something to try, and something that proves the try worked.

      -

      Alex: The practical takeaway is this. With keyboard: The icon may not be keyboard-reachable directly; instead go to Step 3. VS Code opens a new editor tab for this PR. Below the PR title, you see a "Changes" section listing modified files. You should see setup-guide.md in the changes list. Use Ctrl+Shift+P → search GitHub Pull Requests: Open Pull Request. Paste the PR URL: https://github.com/[owner]/[repo]/pull/[number].

      -

      Alex: First, look for a GitHub-themed icon on the left sidebar (circle with octocat logo) - click it. Then, a sidebar appears showing open pull requests on repositories you have access to. After that, find the PR titled "Add screen reader tips to the setup guide" - it should appear in a list. Finally, click it to open. The rhythm is simple: orient, act, verify, then continue.

      +

      Alex: The big idea today: Forum-style conversations, Q&A, polls, and navigation with screen readers. We will name the concept, explain why it matters, practice the move, and point out the checks that tell you the work is real.

      +

      Jamie: So the episode should work even if someone has not read the chapter yet.

      +

      Alex: Exactly. The transcript has to stand on its own. It can point toward practice, but it should teach the concept right here in the conversation.

      -

      Jamie: Let's pause on Step 3: View the File Changes. What should a learner take away from it?

      -

      Alex: Start with Step 3: View the File Changes. There is something to understand, something to try, and something that proves the try worked.

      -

      Alex: The practical takeaway is this. A diff editor opens showing two columns. Left: the original file (before changes). Right: the new file (after changes). Different colors show added (green), removed (red), and modified (blue) lines. The file name appears at the top: setup-guide.md. NVDA/JAWS: The editor announces "Diff Editor - setup-guide.md".

      -

      Alex: First, in the Changes section, locate setup-guide.md. Then, click on the filename to open it. Think of it as a rail line: each stop confirms you are still on the right route before the next one.

      -

      Jamie: Let's pause on Step 4: Access the Accessible Diff Viewer. What should a learner take away from it?

      -

      Alex: Here is the plain-English version of Step 4: Access the Accessible Diff Viewer. If the Accessible Diff Viewer doesn't open.

      -

      Alex: The practical takeaway is this. With mouse: Look for a button or menu option labeled "Accessible View" or "Open Accessible Diff". If no button is visible, try Alt+F2 (VS Code Accessible View toggle). A new panel opens at the bottom of VS Code. The panel announces each change one at a time. Changes appear in text format with labels: "Added: " and "Removed: ". The panel is read-only (you read the changes, you don't edit here).

      -

      Alex: First, with keyboard: Press F7 to open the Accessible Diff Viewer. Treat it like a recipe: do not add the next ingredient until the previous one is actually in the bowl.

      -

      Jamie: Let's pause on Step 5: Listen to and Understand the First Change. What should a learner take away from it?

      -

      Alex: Start with Step 5: Listen to and Understand the First Change. There is something to understand, something to try, and something that proves the try worked.

      -

      Alex: The practical takeaway is this. NVDA/JAWS: The Accessible Diff Viewer announces "Removed:" and "Added:" labels, followed by the line content. VoiceOver: The announcement may be similar; listen for "removed" and "added" keywords.

      -

      Alex: First, the first change is automatically announced when you open the Accessible Diff Viewer. Then, let your screen reader read it completely - don't interrupt. After that, write down the exact text announced. Finally, press the Down arrow to move to the next change. It is a checklist, but a meaningful one: every item creates evidence that the next step is safe.

      +

      Jamie: Okay, set the room for us. What are we walking into?

      +

      Alex: Start with Forum-Style Conversations Beyond Issues and Pull Requests: GitHub Discussions is a built-in community forum for repositories and organizations. The next useful detail is this: It's where open-ended conversations live - questions, ideas, announcements, polls, and community Q&A - separate from the action-oriented world of issues and pull requests.

      +

      Alex: A solid issue habit is to read the title, the body, and the timeline before acting. You are listening for the requested action, the missing evidence, and the person who needs a response.

      +

      Alex: The next layer is this. Start with Learning Cards: GitHub Discussions. There is something to understand, something to try, and something that proves the try worked.

      +

      Alex: The practical anchors are these. The Discussions tab is in the repository's main navigation bar alongside Code, Issues, and Pull Requests -- press T to navigate tab items or K to find the "Discussions" link. Inside a discussion, replies are article elements -- in NVDA press A to jump between replies; in JAWS use A as well. The reply editor uses the same behavior as issue comments -- enter Focus Mode to type, then press Ctrl+Enter to submit. Discussion categories appear as a sidebar panel on the left or right depending on viewport width -- look for the category list with item counts. Answered discussions in the Q&A category display a green "Answered" badge next to the title, with the accepted answer pinned to the top. Polls show percentage bars next to each option after you vote -- the bars use color fill to indicate proportion.

      +

      Jamie: Can you translate that into plain choices?

      +

      Alex: This is where 1. Discussions vs. Issues: When to Use Which becomes real: not every conversation belongs in an issue. That matters in practice: GitHub Discussions exists for the conversations that don't fit.

      +

      Alex: Use the comparison to make a decision, not to recite a table. The main contrasts are: Use Issues When means Use Discussions When. You found a bug means You have a question about how something works. You want to request a specific feature means You want to brainstorm ideas before filing a feature request.

      -

      Jamie: Let's pause on Step 6: Find the Heading Hierarchy Issue. What should a learner take away from it?

      -

      Alex: Start with Step 6: Find the Heading Hierarchy Issue. There is something to understand, something to try, and something that proves the try worked.

      -

      Alex: The practical takeaway is this. Four hashes ( ) indicate a level 4 heading. In the diff, you're looking for it appearing after a level 2 heading ( ). This creates the hierarchy skip you caught in Exercise A. You found the explanation in the Accessible Diff Viewer's format. You can explain: "The added line with directly follows a, skipping level 3". The Accessible Diff Viewer made this pattern clearer than scanning raw + characters.

      -

      Alex: First, continue pressing Down arrow to move through changes. Then, listen carefully for a change involving headings (lines starting with ). After that, specifically, listen for: "Added: " (four hashes). Finally, when you hear this, stop and write it down. It is like walking a hallway with named doors: read the sign, enter the right room, then confirm where you landed.

      -

      Jamie: Let's pause on Step 7: Locate the Heading Line and Add an Inline Comment. What should a learner take away from it?

      -

      Alex: Start with Step 7: Locate the Heading Line and Add an Inline Comment. There is something to understand, something to try, and something that proves the try worked.

      -

      Alex: The practical takeaway is this. Use Ctrl+F to open Find. Search for to locate it quickly. Press Enter to jump to it. With keyboard: The comment button may appear on the current line; navigate to it and press Enter. A comment box opens. You can type your comment.

      -

      Alex: First, once you identified the problematic heading in the Accessible Diff Viewer, close the Accessible Diff Viewer (press F7 again or Alt+F2). Then, you're back in the regular Diff Editor. After that, find the line with the problematic heading. Finally, close Find (Escape). The rhythm is simple: orient, act, verify, then continue.

      -

      Jamie: Before we leave Step 7: Locate the Heading Line and Add an Inline Comment, what is the practical point?

      -

      Alex: First, place your cursor on that line. Then, right-click and select "Add Comment" or press the Comment icon that appears on the left margin. Think of it as a rail line: each stop confirms you are still on the right route before the next one.

      -

      Jamie: Let's pause on Step 8: Write Your Accessible Diff Comment. What should a learner take away from it?

      -

      Alex: Start with Step 8: Write Your Accessible Diff Comment: Why mention the Accessible Diff Viewer?

      -

      Alex: The practical takeaway is this. It shows that the tool itself helps you see the issue. It documents how you caught the problem (useful for learning).

      -

      Alex: First, in the comment box, type. Then, press Ctrl+Enter or click Comment to submit. Think of it as a rail line: each stop confirms you are still on the right route before the next one.

      +

      Alex: Now bring the learner back to the room. Start with Common Discussions categories you'll encounter. There is something to understand, something to try, and something that proves the try worked.

      +

      Alex: For a learner, the useful signals are these. Q&A - Support questions and answers (one answer can be marked correct). Ideas - Feature brainstorming before a formal feature request. Announcements - Maintainer posts about releases, breaking changes, roadmaps. General - Everything else. Show and Tell - Community members showing what they built.

      +

      Jamie: What is the ordered workflow?

      +

      Alex: The reason From a Repository matters is that if the tab is missing: Discussions is an opt-in feature. That gives the learner a simple foothold: the repository maintainer must enable it in Settings.

      +

      Alex: First, navigate to the repository. Then, there is a Discussions tab in the main navigation (alongside Code, Issues, Pull Requests, Actions, Projects). After that, press T to navigate tab items, or K to navigate links and find "Discussions". Finally, press Enter to open. The rhythm is simple: orient, act, verify, then continue.

      +

      Alex: The useful habit is simple: orient first, act second, verify third. That pause before acting is part of the work.

      +

      Jamie: Give me the sequence, because order matters here.

      +

      Alex: Start with From an Organization: Large organizations can have organization-level Discussions separate from any individual repository. Think of it like entering a new building: first you find the lobby, then the room, then the door you actually need.

      +

      Alex: First, navigate to the organization page. Then, look for the Discussions tab at the organization level. After that, these are community-wide conversations, not repo-specific. Think of it as a rail line: each stop confirms you are still on the right route before the next one.

      -

      Jamie: Let's pause on Step 9: Create a GitHub Pull Request Comment. What should a learner take away from it?

      -

      Alex: Here is the plain-English version of Step 9: Create a GitHub Pull Request Comment. Now you've reviewed the same PR in.

      -

      Alex: First, browser (Exercise A): You spot-checked line numbers manually. Then, VS Code (Exercise B): The Diff Editor plus Accessible Diff Viewer announced changes. After that, go to GitHub in your browser and open the same PR. Finally, scroll to the bottom and leave a comment in the Conversation tab. Treat it like a recipe: do not add the next ingredient until the previous one is actually in the bowl.

      -

      Jamie: Before we leave Step 9: Create a GitHub Pull Request Comment, what is the practical point?

      -

      Alex: First, click Comment. It is a checklist, but a meaningful one: every item creates evidence that the next step is safe.

      -

      Jamie: Before we leave Reflect on This Exercise, what is the practical point?

      -

      Alex: This is where Reflect on This Exercise becomes real: after completing Steps 1-9, answer. That matters in practice: In Chapter 16, you'll compare these manual reviews with the @pr-review agent's suggested changes. The workshop is closer to rehearsal than lecture. You hear the move, try the move, and then check what changed.

      -

      Alex: First, announcement clarity: Did the "Added:" and "Removed:" labels from the Accessible Diff Viewer help you follow changes faster than reading + and − prefixes in the browser? Then, navigation pattern: Which tool required less back-and-forth clicking/tabbing to understand each change? After that, when would you use each? In one sentence: describe a type of PR where you'd prefer to use each tool. It is a checklist, but a meaningful one: every item creates evidence that the next step is safe.

      -

      Jamie: How do these exercises create confidence instead of pressure?

      -

      Alex: Keep the learner anchored in Exercise C - Compare and Reflect. Your Mission: Synthesize what you learned from the manual code reviews (Exercises A & B) and document your findings. This is the part to say slowly: What You'll Learn: Which tools work best for different scenarios, and how your manual review skills prepare you to use AI agents effectively.

      +

      Jamie: If I am listening before the workshop starts, what should settle in my mind first?

      +

      Alex: Here is the plain-English version of 3. Discussion Categories. The Discussions home page is organized by category. Put another way, each category is a section with its own heading.

      +

      Alex: This is where the talk moves from concept to action. Start with The side panel (left or right depending on view width) shows. There is something to understand, something to try, and something that proves the try worked.

      +

      Alex: The room should hear these as checkpoints. All categories with item counts. Pin/announcements section at top. Most active discussions. Tags (if the repo uses them).

      +

      Jamie: Turn that into a path someone can follow.

      +

      Alex: Start with 4. Creating a Discussion. There is something to understand, something to try, and something that proves the try worked.

      +

      Alex: These are the details that keep the idea from floating away. Title - Clear and searchable. "How do I use the daily-briefing agent?" not "Help". Body - Use Markdown. Same editor as issues. For Q&A category: phrase the title as a question.

      +

      Alex: First, from the Discussions tab, activate "New discussion" button. Then, select a category (required - affects which fields appear). After that, fill in. Finally, activate "Start discussion". It is like walking a hallway with named doors: read the sign, enter the right room, then confirm where you landed.

      -

      Alex: Keep the teaching thread moving. The reason Step 1: Gather Your Data matters is that before writing your reflection, collect all the information you gathered. That gives the learner a simple foothold: write these down (in a text editor, on paper, or mentally) - you'll reference them in Steps 2-4.

      -

      Alex: The practical takeaway is this. Which line number had the heading hierarchy skip? Which line number had the link text issue? How many steps did it take to find each issue? Did you use screen reader commands or visual scanning more?

      -

      Jamie: Let's pause on Step 2: Navigate to the PR and Leave Your Reflection Comment. What should a learner take away from it?

      -

      Alex: Start with Step 2: Navigate to the PR and Leave Your Reflection Comment. There is something to understand, something to try, and something that proves the try worked.

      -

      Alex: The practical takeaway is this. A text editing area with formatting options (Bold, Italic, Link, etc.). A Comment button below the text area.

      -

      Alex: First, go to GitHub in your browser. Then, open the same PR ("Add screen reader tips to the setup guide"). After that, scroll to the Conversation tab. Finally, scroll all the way down to the comment box at the bottom (labeled "Leave a comment" or "Add a comment"). Think of it as a rail line: each stop confirms you are still on the right route before the next one.

      -

      Jamie: Before we leave Step 2: Navigate to the PR and Leave Your Reflection Comment, what is the practical point?

      -

      Alex: First, click in the comment box. Treat it like a recipe: do not add the next ingredient until the previous one is actually in the bowl.

      -

      Alex: Keep the teaching thread moving. Here is the plain-English version of Step 3: Write Your Comparison. Type your response to these three questions. Put another way, be specific - reference exact tools, steps, and what you discovered. It is like learning a transit route. The names of the stops matter because they tell you whether you are still going the right direction.

      +

      Alex: Before the learner moves on. The reason Screen reader path matters is that before posting a question: Search existing discussions first. That gives the learner a simple foothold: use the search bar at the top of the Discussions page or GitHub's global search with repo:owner/name in:discussions. The interface gets friendlier when it stops being a wall of controls and starts being a set of named places.

      +

      Alex: A solid navigation habit is to prove where you are before activating controls. Headings, landmarks, and the address bar are not trivia; they are your map.

      +

      Jamie: What would you say to someone who is already bracing for this to be too much?

      +

      Alex: Start with Learning Cards: Creating a Discussion. There is something to understand, something to try, and something that proves the try worked.

      +

      Alex: A few details make that real. Tab to the "New discussion" button from the Discussions tab, then press Enter -- the form loads with a category selector first; arrow through categories and press Enter to select. The title field comes after the category selector -- type a clear, searchable title; for Q&A category, phrase it as a question so it reads naturally in search results. The body editor is the same as the issue comment editor -- enter Focus Mode to type, use Markdown formatting, and press Ctrl+Enter to submit the discussion. The category selector appears as a list or grid of labeled options -- each category has a name and description; zoom in to read the descriptions and pick the right one. The title and body fields stack vertically in a single-column layout -- the form is the same width as the main content area, making it easy to scan at high zoom. After creating a discussion, a green success banner appears at the top -- scroll up if you do not see confirmation at your current zoom position.

      +

      Alex: Hold that next to this. Here is the plain-English version of Reading a Discussion. A discussion page is structured similarly to an issue.

      +

      Alex: That shows up in the workshop in a few specific ways. The original post at the top. Replies in chronological order. An "Answered" reply pinned to the top (Q&A category only). A reply editor at the bottom.

      -

      Jamie: Let's pause on Step 4: Review Your Comment. What should a learner take away from it?

      -

      Alex: Start with Step 4: Review Your Comment. There is something to understand, something to try, and something that proves the try worked.

      -

      Alex: The practical takeaway is this. Is it clear which tool I preferred? Did I explain why with concrete examples? Am I describing the real-world impact accurately? Would someone else reading this understand how I caught the issue?

      -

      Alex: First, before submitting, re-read your comment using your screen reader or by reading aloud. Then, ask yourself. After that, make any corrections needed. Finally, do not submit yet - continue to Step 5. It is a checklist, but a meaningful one: every item creates evidence that the next step is safe.

      -

      Jamie: Let's pause on Step 5: Submit Your Reflection. What should a learner take away from it?

      -

      Alex: Start with Step 5: Submit Your Reflection. There is something to understand, something to try, and something that proves the try worked.

      -

      Alex: The practical takeaway is this. Your comment is now visible on the PR. Other reviewers can see your comparison. You have completed the three-part exercise series. Your comment appears on the PR thread. It includes all three reflections. The PR author and other reviewers can see your thought process.

      -

      Alex: First, locate the Comment button at the bottom right of the comment box. Then, with keyboard: Press Tab until the Comment button is focused, then Enter. After that, with mouse: Click the Comment button. Finally, your comment is submitted and appears on the PR page. It is like walking a hallway with named doors: read the sign, enter the right room, then confirm where you landed.

      -

      Jamie: Let's pause on Step 6: Checkpoint - Validate Your Learning. What should a learner take away from it?

      -

      Alex: The reason Step 6: Checkpoint - Validate Your Learning matters is that before moving forward, verify you understand. That gives the learner a simple foothold: if you can answer all three, you're ready for the next chapter.

      -

      Alex: The practical takeaway is this. Expected answer: Something like "Screen readers let users navigate by heading level (pressing 3 jumps to H3), so skipping a level makes users think content is missing.". Expected answer: e.g., "Browser: finding context in discussions. VS Code: linear reading of changes.". Expected answer: Something like "Open the document in a browser, use screen reader heading navigation, and confirm I can reach all levels (H2, H3, H4).".

      -

      Alex: First, heading Hierarchy: Can you explain in one sentence why a → skip breaks screen reader navigation? Then, tool Strengths: For each tool you used, name one task it made easier. After that, real-World Testing: How would you test the heading issue in the published document (not the PR diff)? The rhythm is simple: orient, act, verify, then continue.

      +

      Jamie: What does the learner do first, second, and then after that?

      +

      Alex: Start with Replying to a Discussion. There is something to understand, something to try, and something that proves the try worked.

      +

      Alex: First, navigate to the bottom of the page (or use the "Reply" button on a specific comment). Then, the reply text area behaves identically to issue comments. After that, focus Mode → type your reply. Finally, ctrl+Enter to submit. It is a checklist, but a meaningful one: every item creates evidence that the next step is safe.

      +

      Alex: That connects to another useful point. Keep the learner anchored in Replying to a Specific Comment (Nested Reply). Each comment has a Reply button below it. A good GitHub workflow is like a well-run meeting: everyone knows the topic, the next action, and who has the floor.

      +

      Jamie: What is the one idea that makes the next few steps less mysterious?

      +

      Alex: The reason Upvoting matters is that instead of leaving "+1" comments, use the thumbs-up reaction on the original post or replies. That gives the learner a simple foothold: many maintainers sort discussion responses by upvotes to prioritize most-needed answers.

      -

      Alex: Keep the teaching thread moving. Start with Using GitHub Copilot to Understand Code Changes: Reviewing code is about understanding what changed, why it changed, and whether the change is safe and correct. The next useful detail is this: GitHub Copilot can help you gather and understand information about code changes - especially when diffs are large, complex, or involve unfamiliar frameworks. Think of it like entering a new building: first you find the lobby, then the room, then the door you actually need.

      -

      Jamie: Let's pause on When to Use Copilot During Code Review. What should a learner take away from it?

      -

      Alex: Here is the plain-English version of When to Use Copilot During Code Review. Copilot is most useful for answering these questions.

      -

      Alex: First, "What does this code do?" - you're reading unfamiliar syntax or a framework you don't know well. Then, "Why might this change break something?" - you need to understand dependencies or side effects. After that, "Is this pattern safe?" - you want to verify that the approach follows best practices. Finally, "What would be a better way to write this?" - you're looking for alternatives to suggest. Treat it like a recipe: do not add the next ingredient until the previous one is actually in the bowl.

      -

      Jamie: Before we leave When to Use Copilot During Code Review, what is the practical point?

      -

      Alex: First, "Does this match the PR's description?" - the change seems to do more (or less) than claimed. It is a checklist, but a meaningful one: every item creates evidence that the next step is safe.

      -

      Jamie: Let's pause on In VS Code with an Open Diff. What should a learner take away from it?

      -

      Alex: Start with In VS Code with an Open Diff. There is something to understand, something to try, and something that proves the try worked.

      -

      Alex: First, open the PR using the GitHub Pull Requests extension (see Part 2). Then, open the diff for any file. After that, select a block of code that confuses you (highlight it). Finally, open Copilot Chat: Ctrl+Shift+I. It is a checklist, but a meaningful one: every item creates evidence that the next step is safe.

      -

      Jamie: Before we leave In VS Code with an Open Diff, what is the practical point?

      -

      Alex: First, Copilot reads the selected code and answers in the chat. It is like walking a hallway with named doors: read the sign, enter the right room, then confirm where you landed.

      +

      Alex: Here is the practical turn. Start with 6. Marking an Answer: In the Q&A category, one reply can be marked as the accepted answer. The next useful detail is this: This is similar to Stack Overflow's "accepted answer" mechanic.

      +

      Jamie: How would you walk the room through that step by step?

      +

      Alex: Here is the plain-English version of To mark an answer (as the discussion author). Why it matters: Marked answers make Q&A discussions into searchable documentation. Put another way, anyone who searches for the same question later immediately sees the correct answer without reading the whole thread.

      +

      Alex: First, navigate to the reply you want to mark as the answer. Then, look for the "Mark as answer" button below the reply. After that, activate it - the reply is pinned to the top and the discussion shows a green "Answered" badge. Treat it like a recipe: do not add the next ingredient until the previous one is actually in the bowl.

      +

      Alex: Keep the thread going. This is where 7. Polls becomes real: some discussion categories support embedded polls. That matters in practice: A poll lets you gather structured vote data from the community. The workshop is closer to rehearsal than lecture. You hear the move, try the move, and then check what changed.

      -

      Jamie: Let's pause on On GitHub.com (Web Interface). What should a learner take away from it?

      -

      Alex: Keep the learner anchored in On GitHub.com (Web Interface). Another option: Use the GitHub Copilot inline suggestions on GitHub.com.

      -

      Alex: The practical takeaway is this. Some GitHub PRs show Copilot insights directly in the diff (as of early 2026). If you see a lightbulb icon, click it to see Copilot's suggestion about that line.

      -

      Alex: First, open the PR's Files Changed tab. Then, focus on a line or section you want to understand better. After that, in VS Code Copilot Chat (not in the browser - Copilot Chat doesn't work directly in browser diffs yet). Finally, copy the confusing code, paste it into chat, and ask Copilot to explain. It is like walking a hallway with named doors: read the sign, enter the right room, then confirm where you landed.

      -

      Alex: Keep the teaching thread moving. The reason Copilot Limitations During Review (Critical to Know) matters is that this is why manual review is essential: You have context (project history, team decisions, user impact) that Copilot does not. That gives the learner a simple foothold: use Copilot to understand, then use your judgment to decide. The interface gets friendlier when it stops being a wall of controls and starts being a set of named places.

      -

      Alex: The practical takeaway is this. See the whole project - it sees only what you show it (the selected diff, not the context of the entire codebase). Verify correctness - it can explain what code does, but not whether it's correct for your specific use case. Understand intent - it reads the code, not the author's mind or the PR description. Catch all risks - it can spot common patterns, but not edge cases unique to your project.

      -

      Jamie: Let's pause on Best Practices. What should a learner take away from it?

      -

      Alex: Start with Best Practices. There is something to understand, something to try, and something that proves the try worked.

      -

      Alex: First, read the diff manually first - you spot the big picture before asking Copilot details. Then, ask Copilot specific questions - not "review this code" but "does this regex handle Unicode?". After that, fact-check Copilot's answers - it can be confidently wrong, especially about frameworks or domains it has less training data. Finally, combine Copilot with manual analysis - ask Copilot to explain, then verify by checking the PR description or looking for related files. Think of it as a rail line: each stop confirms you are still on the right route before the next one.

      -

      Jamie: Before we leave Best Practices, what is the practical point?

      -

      Alex: First, use Copilot to draft comments - type Draft a comment about [issue] for this PR and edit Copilot's suggestion to match your tone. Treat it like a recipe: do not add the next ingredient until the previous one is actually in the bowl.

      +

      Jamie: Let's pause on Creating a poll. What should a learner take away from it?

      +

      Alex: Start with Creating a poll. There is something to understand, something to try, and something that proves the try worked.

      +

      Alex: First, when creating a discussion, look for the "Add a poll" option below the body editor. Then, type each poll option (up to 8 options). After that, set poll duration (optional). Finally, submit the discussion - the poll appears inline. It is like walking a hallway with named doors: read the sign, enter the right room, then confirm where you landed.

      +

      Alex: Another way to ground it. The reason Voting in a poll matters is that poll results: After voting, percentages appear next to each option. That gives the learner a simple foothold: screen readers announce the count and percentage per option.

      +

      Jamie: Where do you want a learner to place their attention here?

      +

      Alex: Start with NVDA note. There is something to understand, something to try, and something that proves the try worked.

      +

      Alex: The parts worth keeping in working memory are these. Browse mode (NVDA+Space) to read the discussion. Enter application mode for the reply editor. Discussion replies are elements - NVDA announces "article" as you navigate with H.

      -

      Alex: Keep the teaching thread moving. Here is the plain-English version of What Comes Next. Your manual code review skills - identifying heading issues, catching link text problems, understanding screen reader navigation, gathering information with Copilot - are the foundation for understanding automated review. Put another way, in Chapter 16 (Accessibility Agents), you'll meet a full team of agents designed to amplify these skills.

      -

      Jamie: Let's pause on Part 4: The Reviewer's Craft. What should a learner take away from it?

      -

      Alex: This is where The Reviewer's Craft becomes real: parts 1 through 3 taught you the mechanics -- how to read diffs, leave comments, and use Copilot to understand unfamiliar code. That matters in practice: This part covers something equally important: how to think like a reviewer.

      -

      Alex: Keep the teaching thread moving. Keep the learner anchored in What to Look for in a Review. Every PR is different, but most reviews benefit from scanning across these five categories. This is the part to say slowly: You do not need to check every category exhaustively on every PR. A good GitHub workflow is like a well-run meeting: everyone knows the topic, the next action, and who has the floor.

      +

      Alex: This is the part worth saying out loud. Start with JAWS note. There is something to understand, something to try, and something that proves the try worked.

      +

      Alex: On the ground, that means a few things. A key navigates elements - useful for jumping between replies. Use Forms Mode for the reply editor.

      +

      Jamie: Give me the version that sounds like an instructor, not a manual.

      +

      Alex: Start with VoiceOver note. There is something to understand, something to try, and something that proves the try worked.

      +

      Alex: Here is what that changes in practice. VO+Right to read through content. VO+Command+L to list all links (useful for navigating many replies quickly). VO+Space on the reply field to enter interaction mode.

      +

      Alex: That matters because of the next idea. Keep the learner anchored in 9. Organization-Level Discussions. Some organizations enable Discussions at the organization level, separate from any repository. This is the part to say slowly: These work identically to repository discussions but span the whole organization.

      +

      Alex: That becomes easier when you listen for these cues. Org-wide announcements. Community introductions ("Introduce yourself" pinned thread). Cross-repo feature brainstorming. Community spotlights and events.

      -

      Jamie: Let's pause on The Three Review Actions. What should a learner take away from it?

      -

      Alex: The reason The Three Review Actions matters is that when you submit a review on GitHub, you choose one of three actions. That gives the learner a simple foothold: picking the right one matters because it signals your intent to the author and to anyone else watching the PR.

      -

      Alex: First, did you find a bug, security issue, or broken test? -- Request Changes. Then, does the code do something different from what the description says? -- Request Changes. After that, does everything work, with maybe a few style nits? -- Approve (mention the nits in a comment). Finally, do you have questions or optional suggestions? -- Comment. The rhythm is simple: orient, act, verify, then continue.

      -

      Alex: Keep the teaching thread moving. Start with Writing Constructive Feedback: The way you phrase feedback determines whether the author feels supported or attacked. The next useful detail is this: Before pointing out problems, acknowledge something the author did well.

      -

      Jamie: Let's pause on The Reviewer's Checklist. What should a learner take away from it?

      -

      Alex: Here is the plain-English version of The Reviewer's Checklist. Run through this list mentally (or copy it into your notes) for every PR you review.

      -

      Alex: The practical takeaway is this. [ ] I read the PR description before reading the code. [ ] The code does what the description says it does. [ ] The change does not include unrelated modifications. [ ] Variable and function names are clear. [ ] I checked for accessibility: labels, headings, keyboard reach, contrast. [ ] I verified no existing behavior is broken by the change.

      +

      Jamie: Let's pause on 10. Accessibility Agents: What's Different Here. What should a learner take away from it?

      +

      Alex: The reason 10. Accessibility Agents: What's Different Here matters is that accessibility Agents prompts currently operate on issues, PRs, and code - not directly on Discussions. That gives the learner a simple foothold: if you want to respond to a discussion using Accessibility Agents.

      +

      Alex: First, copy the discussion URL or content. Then, use /issue-reply with the content pasted in: the agent will draft a thoughtful, accessible response. After that, paste the result back into the discussion reply editor. The rhythm is simple: orient, act, verify, then continue.

      +

      Alex: A solid pull request habit is to separate three questions: what changed, why it changed, and what still needs review. That keeps the conversation useful instead of noisy.

      +

      Alex: Keep the teaching thread moving. Start with Shareable Code Snippets and Notes: Gists are a simple way to share code snippets, notes, or small files without creating a full repository. The next useful detail is this: Think of them as lightweight, version-controlled pastebins. Think of it like entering a new building: first you find the lobby, then the room, then the door you actually need.

      +

      Jamie: Let's pause on Learning Cards: GitHub Gists. What should a learner take away from it?

      +

      Alex: Start with Learning Cards: GitHub Gists. There is something to understand, something to try, and something that proves the try worked.

      +

      Alex: The practical takeaway is this. On the Gist creation page at gist.github.com, press D to jump to the main landmark, then F to navigate form fields: Description, Filename, Content, and Visibility buttons. Your Gists page lists each gist as an H2 heading with its description -- press 2 or H to jump between gists. Gists are full Git repositories -- you can clone them with git clone and edit locally using your usual screen reader workflow in VS Code. Gist pages use syntax highlighting matching GitHub's current theme -- switch between light and dark mode for comfortable reading. Public and secret gists look identical on the page; the only difference is the URL visibility -- check the "Create secret gist" or "Create public gist" button label before submitting. The revision history link appears at the top of any gist -- click "Revisions" to see a diff view of every edit.

      -

      Alex: Keep the teaching thread moving. This is where Reviewing as a Learning Tool becomes real: reviewing is not just a gate to keep bad code out. That matters in practice: It is one of the fastest ways to grow as a developer. The workshop is closer to rehearsal than lecture. You hear the move, try the move, and then check what changed.

      -

      Jamie: Let's pause on Learning Cards: The Reviewer's Craft. What should a learner take away from it?

      -

      Alex: Start with Learning Cards: The Reviewer's Craft. There is something to understand, something to try, and something that proves the try worked.

      -

      Alex: The practical takeaway is this. Jump between changed hunks in a diff with Alt+F5 (next change) and Shift+Alt+F5 (previous change) to scan for scope creep efficiently. Use Alt+F2 (Accessible View) on a Copilot-generated review summary to read the full text with arrow keys before posting. When leaving feedback, mention specific line numbers ("Line 42 skips from h2 to h4") so the author can navigate directly with Ctrl+G. The three review actions (Approve, Request Changes, Comment) are shown as clearly labeled radio buttons in the review submission form. Use the reviewer checklist in this section as a mental framework -- copy it into your notes and check items off as you review each PR. The diff view uses green and red backgrounds for added/removed lines; pair with a High Contrast theme if these colors are hard to distinguish.

      -

      Alex: Keep the teaching thread moving. The reason Day 2 Teaser: The Full Accessibility Agents Review Ecosystem matters is that chapter 16 shows you how to leverage 50+ specialized agents to make your reviews faster, more consistent, and more thorough - while staying in full control of what you post.

      +

      Alex: Keep the teaching thread moving. This is where What Is a Gist? becomes real: a Gist is a Git repository that holds a single file or a small collection of files. That matters in practice: Anyone with the URL can view a secret Gist.

      +

      Alex: The practical takeaway is this. Has its own URL (e.g., gist.github.com/username/a1b2c3d4). Is version-controlled (you can see edit history). Can be public (anyone can see) or secret (only people with the link can see). Supports Markdown rendering.

      +

      Jamie: How should someone choose between those options?

      +

      Alex: Start with When to Use a Gist vs a Repository. There is something to understand, something to try, and something that proves the try worked.

      +

      Alex: Use the comparison to make a decision, not to recite a table. The main contrasts are: Use a Gist When. means Use a Repository When. Sharing a single code snippet means Building a full project. Posting configuration examples means Collaborating with multiple people.

      +

      Jamie: Let's pause on Via GitHub Web Interface. What should a learner take away from it?

      +

      Alex: Start with Via GitHub Web Interface. There is something to understand, something to try, and something that proves the try worked.

      +

      Alex: The practical takeaway is this. Select "Create public gist" for openly shareable content. Select "Create secret gist" for link-only sharing.

      +

      Alex: First, navigate to gist.github.com. Then, gist description: A short title (e.g., "NVDA configuration for GitHub"). After that, filename: Name your file with extension (e.g., nvda-config.txt, script.py, notes.md). Finally, content: Paste or type your code/text. The rhythm is simple: orient, act, verify, then continue.

      +

      Jamie: Before we leave Via GitHub Web Interface, what is the practical point?

      +

      Alex: First, visibility. Then, the Gist is created with a unique URL you can share. Think of it as a rail line: each stop confirms you are still on the right route before the next one.

      -

      Jamie: What do you want them to do when the plan breaks?

      -

      Alex: Start with The Agents That Help With Code Review: Accessibility Review Agents (when code affects UI/UX).

      -

      Alex: The practical takeaway is this. @pr-review - Generates a full-draft PR review with line-numbered diff maps, risk assessment, before/after snapshots, and suggested inline comments. You edit and post it under your name. @pr-author-checklist - Before you even submit your PR, use this to verify you haven't missed setup steps, accessibility checks, or documentation. @insiders-a11y-tracker - Monitors your PR for accessibility-sensitive changes: WCAG violations, heading hierarchy issues, link text quality, keyboard navigation impacts. @developer-hub - Orchestrates explanations for unfamiliar code, patterns, or frameworks you're reviewing. @python-specialist - If your PR contains Python code, this agent explains patterns, spots accessibility issues, and suggests improvements. @wxpython-specialist - For desktop GUI code, helps verify accessible widget patterns and focus management.

      -

      Jamie: Let's pause on How It Works. What should a learner take away from it?

      -

      Alex: Start with How It Works. There is something to understand, something to try, and something that proves the try worked.

      -

      Alex: First, review manually first (you just did this with Exercises A, B, C). Then, run an agent - @pr-review review PR 14 generates a draft in seconds. After that, edit the agent's draft - you add context, remove noise, correct errors. Finally, post your review - it now has both AI efficiency and your human judgment. Treat it like a recipe: do not add the next ingredient until the previous one is actually in the bowl.

      -

      Jamie: Before we leave How It Works, what is the practical point?

      -

      Alex: First, the agent tracks impact - @insiders-a11y-tracker monitors whether your accessibility feedback was addressed. It is a checklist, but a meaningful one: every item creates evidence that the next step is safe.

      -

      Jamie: Let's pause on The Principle: Skill First, Agent Second. What should a learner take away from it?

      -

      Alex: This is where The Principle: Skill First, Agent Second becomes real: why do this manually before using agents? That matters in practice: Manual reviews teach you what to look for.

      -

      Alex: The practical takeaway is this. You understand what the agent is doing (you did it manually). You evaluate the agent's output critically (you know what right looks like). You add judgment the agent lacks (context, intent, team decisions). You verify the agent didn't miss anything important.

      +

      Jamie: Let's pause on Screen reader navigation. What should a learner take away from it?

      +

      Alex: Start with Screen reader navigation. There is something to understand, something to try, and something that proves the try worked.

      +

      Alex: The practical takeaway is this. D to cycle landmarks to "Main". F to navigate form fields. Tab through: Description → Filename → Content textbox → Visibility buttons.

      +

      Jamie: Let's pause on Adding Multiple Files to a Gist. What should a learner take away from it?

      +

      Alex: Here is the plain-English version of Adding Multiple Files to a Gist. You can add multiple files to a single Gist. Put another way, use case: Share related config files together (e.g.,.vscode/settings.json +.vscode/keybindings.json).

      +

      Alex: First, after typing the first filename and content, select "Add file" (button below the editor). Then, repeat for each additional file. After that, create the Gist. Treat it like a recipe: do not add the next ingredient until the previous one is actually in the bowl.

      +

      Jamie: Let's pause on Learning Cards: Creating a Gist. What should a learner take away from it?

      +

      Alex: Start with Learning Cards: Creating a Gist. There is something to understand, something to try, and something that proves the try worked.

      +

      Alex: The practical takeaway is this. On the Gist creation page at gist.github.com, press D to jump to the main landmark, then F to navigate form fields in order: Description, Filename, Content textarea, and visibility buttons. The visibility selector is a split button -- the main button creates a public gist; Tab to the dropdown arrow next to it and press Enter to reveal the "Create secret gist" option. Each filename field has a corresponding content textarea directly below it -- after filling one file, Tab to the "Add file" button to add another file to the same gist. The Gist editor uses the same syntax highlighting as regular GitHub files -- your current theme applies; increase font size in browser zoom for comfortable editing. The split button for public vs. secret visibility is at the bottom of the form -- the two options look nearly identical; read the button label carefully ("Create public gist" vs. "Create secret gist") before clicking. The "Add file" button appears below the first file editor as a small text link -- zoom in to find it; each additional file gets its own filename field and content textarea.

      -

      Jamie: Let's pause on A Real Example: The Flow. What should a learner take away from it?

      -

      Alex: Keep the learner anchored in A Real Example: The Flow. Manual Review (your work in part 1-2). This is the part to say slowly: Agent-Assisted Review (what you'll do in Chapter 19).

      -

      Alex: The practical takeaway is this. Read diff, identify heading hierarchy skip. Write comment explaining why it matters. Submit your verdict.

      -

      Alex: First, run: @pr-review review PR 14. Then, agent generates a draft review covering the heading skip, link text, and 5 other issues. After that, you read the draft and notice: "the agent's explanation of the heading skip is good, but it missed that the link text on line 23 is still vague. Let me add that.". Finally, you post the agent's review + your additions. It is like walking a hallway with named doors: read the sign, enter the right room, then confirm where you landed.

      -

      Jamie: Before we leave A Real Example: The Flow, what is the practical point?

      -

      Alex: First, next time you review a similar PR, the agent works faster because it learned from your feedback. The rhythm is simple: orient, act, verify, then continue.

      +

      Jamie: Let's pause on Editing a Gist. What should a learner take away from it?

      +

      Alex: Keep the learner anchored in Editing a Gist. Click "Revisions" to see the full edit history. A good GitHub workflow is like a well-run meeting: everyone knows the topic, the next action, and who has the floor.

      +

      Alex: First, navigate to your Gist's URL. Then, select "Edit" (button in the top-right). After that, make your changes. Finally, select "Update public gist" or "Update secret gist". It is like walking a hallway with named doors: read the sign, enter the right room, then confirm where you landed.

      +

      Jamie: Let's pause on Embedding a Gist. What should a learner take away from it?

      +

      Alex: The reason Embedding a Gist matters is that you can embed Gists in web pages, blog posts, or documentation. That gives the learner a simple foothold: GitHub renders it as a formatted code block with syntax highlighting and a link back to the Gist.

      +

      Jamie: What should happen before anyone copies and runs it?

      +

      Alex: Start with Cloning a Gist: Make changes locally, commit, and push just like a normal repo.

      +

      Alex: Treat examples as spoken recipes, not decorations. You may hear something like git clone https://gist.github.com/username/gist-id.git. Read the command, understand what it changes, then run it only when the repository state matches the lesson.

      +
      +

      Jamie: Let's pause on Forking a Gist. What should a learner take away from it?

      +

      Alex: Here is the plain-English version of Forking a Gist. You can fork someone else's Gist to create your own copy. Put another way, use case: Someone shares a useful script, you fork it, and customize it for your needs.

      +

      Alex: First, view the Gist. Then, select "Fork" in the top-right. After that, GitHub creates a new Gist under your account. Treat it like a recipe: do not add the next ingredient until the previous one is actually in the bowl.

      +

      Alex: Keep the teaching thread moving. This is where Finding Your Gists becomes real: your Gists page: gist.github.com/your-username. That matters in practice: All your public and secret Gists are listed here. The workshop is closer to rehearsal than lecture. You hear the move, try the move, and then check what changed.

      +

      Alex: The practical takeaway is this. Search your Gists by filename or content. Star Gists you want to reference later. Delete old Gists.

      +

      Jamie: Before we leave Screen reader navigation, what is the practical point?

      +

      Alex: The practical takeaway is this. Each Gist appears as a heading (H2) with its description. Press 2 or H to jump between Gists. Each Gist has links: "Edit," "Delete," "Star," "Embed".

      +
      +

      Alex: Keep the teaching thread moving. The reason Discovering Public Gists matters is that browse trending Gists: gist.github.com/discover.

      +

      Alex: The practical takeaway is this. Useful scripts and utilities. Configuration examples. Code snippets for learning.

      +

      Jamie: Let's pause on Gist Comments. What should a learner take away from it?

      +

      Alex: Start with Gist Comments: Anyone with a GitHub account can leave a comment, making Gists useful.

      +

      Alex: The practical takeaway is this. Asking questions about a snippet. Suggesting improvements. Discussing implementation details.

      +

      Jamie: Let's pause on To add a comment. What should a learner take away from it?

      +

      Alex: Start with To add a comment. There is something to understand, something to try, and something that proves the try worked.

      +

      Alex: First, scroll to the bottom of the Gist page. Then, f to navigate form fields → Find the comment textarea. After that, type your comment (Markdown supported). Finally, ctrl+Enter or activate "Comment" button. Treat it like a recipe: do not add the next ingredient until the previous one is actually in the bowl.

      +
      +

      Jamie: Let's pause on Public Gists. What should a learner take away from it?

      +

      Alex: Start with Public Gists. There is something to understand, something to try, and something that proves the try worked.

      +

      Alex: The practical takeaway is this. Appear on your profile. Are indexed by search engines. Anyone can view, fork, and comment.

      +

      Alex: Keep the teaching thread moving. Start with Secret Gists. There is something to understand, something to try, and something that proves the try worked.

      +

      Alex: The practical takeaway is this. Do not appear on your profile. Are not indexed by search engines. Anyone with the URL can view. Still version-controlled and can be starred.

      +

      Jamie: Let's pause on Never put sensitive data in Gists. What should a learner take away from it?

      +

      Alex: The reason Never put sensitive data in Gists matters is that if you accidentally post sensitive data.

      +

      Alex: The practical takeaway is this. Passwords or API keys. Personal identifying information. Proprietary code you don't have permission to share.

      +

      Alex: First, delete the Gist immediately. Then, revoke/regenerate any exposed credentials. After that, remember: Forks and clones may still exist. The rhythm is simple: orient, act, verify, then continue.

      +
      +

      Jamie: How do you keep commands from becoming magic words?

      +

      Alex: Start with 1. Sharing Screen Reader Config: Share the Gist URL with other screen reader users. Think of it like entering a new building: first you find the lobby, then the room, then the door you actually need.

      +

      Alex: Treat examples as spoken recipes, not decorations. You may hear something like Filename: nvda-github-config.txt; Content:; NVDA Settings for GitHub Web Navigation; - Browse Mode: Use screen layout (enabled); - Verbosity: Most punctuation; - Rate: 65%; - Keyboard shortcuts: Use standard GitHub shortcuts (G+I, G+P, etc.). Read the command, understand what it changes, then run it only when the repository state matches the lesson.

      +

      Jamie: Let's pause on 2. Quick Markdown Note. What should a learner take away from it?

      +

      Alex: Here is the plain-English version of 2. Quick Markdown Note. Reference it later or share with workshop participants.

      +

      Alex: Keep the teaching thread moving. This is where 3. Code Snippet for a StackOverflow Answer becomes real: when answering questions, paste your code as a Gist and link to it. That matters in practice: Readers get syntax highlighting, version history, and the ability to fork your solution.

      +
      +

      Jamie: What decision is this helping them make?

      +

      Alex: Start with Gists vs GitHub Repositories - Quick Comparison. There is something to understand, something to try, and something that proves the try worked.

      +

      Alex: Use the comparison to make a decision, not to recite a table. The main contrasts are: Comments means Yes (on issues/PRs).

      +

      Jamie: Let's pause on Deleting a Gist. What should a learner take away from it?

      +

      Alex: The reason Deleting a Gist matters is that next: Appendix V: GitHub Mobile Back: Appendix T: Community and Social Teaching chapter: Chapter 08: Open Source Culture. The interface gets friendlier when it stops being a wall of controls and starts being a set of named places.

      +

      Alex: First, navigate to the Gist. Then, select "Edit". After that, select "Delete" (top-right, after Edit button). Finally, confirm deletion. The rhythm is simple: orient, act, verify, then continue.

      Jamie: What should people carry with them after this?

      Alex: Carry the map. Know what page or tool you are in, know which action you are taking, and know what confirmation should follow. If the confirmation is missing, pause. That pause is not wasted time; it is professional judgment.

      Jamie: That is a better way to say it than just follow the steps.

      -

      Alex: Right. Steps matter, but understanding wins. That is episode 13. Next in the series is episode 14, where we keep building the same contributor muscles.

      +

      Alex: Right. Steps matter, but understanding wins. That is episode 24. Next in the series is episode 25, where we keep building the same contributor muscles.

      -

      Episode 14: GitHub Copilot

      -

      Inline suggestions, Copilot Chat, prompting strategies, and custom instructions.

      -

      Based on: Chapter 16: GitHub Copilot

      -

      Audio and transcript are being regenerated for this episode.

      +

      Day 1: Pull Requests and Merge Day

      +

      16. Episode 6: Working with Pull Requests

      +

      Creating, reviewing, commenting on, and merging pull requests.

      +

      Based on: Chapter 6: Working with Pull Requests

      + + +

      Download Episode 6 (MP3)

      -Read Transcript - Episode 14: GitHub Copilot +Read Transcript - Episode 6: Working with Pull Requests

      Transcript

      -

      Alex: This is Git Going with GitHub, episode 14: GitHub Copilot. I am Alex. By the end of this episode, GitHub Copilot should feel less like a wall of GitHub words and more like a set of moves you can trust.

      +

      Alex: This is Git Going with GitHub, episode 6: Working with Pull Requests. I am Alex. By the end of this episode, Working with Pull Requests should feel less like a wall of GitHub words and more like a set of moves you can trust.

      Jamie: And I am Jamie. I am here for the practical questions: what should I listen for, what can go wrong, and what is the next calm move?

      -

      Alex: Today we are working on this: Inline suggestions, Copilot Chat, prompting strategies, and custom instructions. I want the learner to leave with a mental map, not just a remembered path through buttons.

      +

      Alex: Today we are working on this: Creating, reviewing, commenting on, and merging pull requests. I want the learner to leave with a mental map, not just a remembered path through buttons.

      Jamie: So the goal is understanding first, then action, then confirmation.

      Alex: Right. We are building a rhythm: orient yourself, take one intentional action, then verify what changed before moving on.

      -

      Jamie: There are a lot of tools in play. How do we keep that from feeling like a contest?

      -

      Alex: Start with AI-Powered Code Assistance in VS Code: Day 2, Block 2-3 Material This guide covers GitHub Copilot: inline code suggestions, Copilot Chat (conversational assistance), custom instructions vs custom agents, effective prompting for non-code contributions, and using Accessible View to read AI-generated. The next useful detail is this: Use the official guides as companion references.

      -

      Alex: The next layer is this. Here is the plain-English version of Workshop Recommendation (Chapter 16 / Challenge 13). Free to use: GitHub Copilot Free tier is included with all GitHub accounts at no cost. Put another way, this workshop uses only the free tier. It is like learning a transit route. The names of the stops matter because they tell you whether you are still going the right direction.

      -

      Alex: The practical anchors are these. There are 3 guided challenges. Automation check: none (tool configuration is account-local and account-specific). The evidence is issue comment with checklist of completed actions. The pattern is install, prompt, apply, reflect.

      +

      Jamie: Okay, set the room for us. What are we walking into?

      +

      Alex: Start with Creating, Reviewing, and Merging Pull Requests with a Screen Reader: See also: Chapter 15: Code Review covers the full review workflow including multi-file diffs and suggested changes. The next useful detail is this: Pull requests are where your work becomes a contribution.

      +

      Alex: A solid pull request habit is to separate three questions: what changed, why it changed, and what still needs review. That keeps the conversation useful instead of noisy.

      +

      Alex: The next layer is this. Here is the plain-English version of Workshop Recommendation (Chapter 6). Chapter 6 is the first PR-validated chapter where students convert issue work into merge-ready contributions. It is like learning a transit route. The names of the stops matter because they tell you whether you are still going the right direction.

      +

      Alex: The practical anchors are these. There are 3. Each challenge should take under 10 minutes each. The evidence is PR metadata, bot checks, and merged issue linkage. The pattern is small change - linked PR - green checks.

      Jamie: What does the learner do first, second, and then after that?

      -

      Alex: Start with Challenge 13 Set. There is something to understand, something to try, and something that proves the try worked.

      -

      Alex: First, sign in to GitHub Copilot - authenticate with GitHub (VS Code 1.116+ has Copilot built in; no extension install needed). Then, ask Copilot to explain a codebase - clone the sci-fi themes repo and use Copilot Chat to understand it. After that, ask Copilot to create something new - prompt Copilot to generate a custom theme and apply it. It is a checklist, but a meaningful one: every item creates evidence that the next step is safe.

      +

      Alex: This is where Chapter 6 Challenge Set becomes real: this is the first chapter where you edit files and create branches. That matters in practice: 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.

      +

      Alex: First, create one small branch change - edit a practice file on a new branch. Then, open a linked PR - use the PR template and include Closes XX. After that, pass required checks - respond to bot feedback until all required checks pass. It is a checklist, but a meaningful one: every item creates evidence that the next step is safe.

      Jamie: Turn that into a path someone can follow.

      -

      Alex: Keep the learner anchored in Challenge 13.1 Step-by-Step: Sign In to Copilot. Sign in to GitHub Copilot and verify it responds to prompts. This is the part to say slowly: VS Code desktop with your Learning Room repository open.

      -

      Alex: First, (Older VS Code only) Open the Extensions sidebar: Ctrl+Shift+X (Mac: Cmd+Shift+X). Then, (Older VS Code only) Type GitHub Copilot in the search box and press Enter. After that, (Older VS Code only) Find GitHub Copilot (publisher: GitHub) in the results. Activate Install. Finally, (Older VS Code only) VS Code may also install GitHub Copilot Chat automatically. If not, search for it separately and install it. It is like walking a hallway with named doors: read the sign, enter the right room, then confirm where you landed.

      +

      Alex: Keep the learner anchored in Challenge 6.1 Step-by-Step: Create One Small Branch Change. Edit one of the practice files and save your change on a new branch. This is the part to say slowly: your Learning Room repository on GitHub.com, using the web editor.

      +

      Alex: For a learner, the useful signals are these. 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. 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.

      +

      Alex: First, 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). Then, open the file and activate the pencil icon (Edit this file) button. After that, the file opens in the web editor. Make your change. For. Finally, keep your change small and focused. Edit only what the issue asks for. It is like walking a hallway with named doors: read the sign, enter the right room, then confirm where you landed.

      Jamie: What is the ordered workflow?

      -

      Alex: First, sign in when prompted: activate Sign in to GitHub and complete the OAuth flow in your browser. Then, verify Copilot is active: open Copilot Chat with Ctrl+Shift+I (Mac: Cmd+Shift+I). Type Hello, are you working? and press Enter. Copilot should respond. The rhythm is simple: orient, act, verify, then continue.

      +

      Alex: First, after editing, activate the Commit changes button (green button above the editor). Then, a dialog appears. In the Branch name field, type: fix/yourname-issueXX (replace yourname with your GitHub username, and XX with the issue number). After that, select Create a new branch for this commit and start a pull request. Finally, activate Propose changes. The rhythm is simple: orient, act, verify, then continue.

      +

      Alex: A solid Git habit is to know which branch you are on, what changed, and what confirmation you expect before you run the next command.

      Jamie: Give me the sequence, because order matters here.

      -

      Alex: The reason Challenge 13.2 Step-by-Step: Explain a Codebase matters is that use Copilot Chat to understand an unfamiliar repository by asking targeted questions. That gives the learner a simple foothold: VS Code with the sci-fi themes repository cloned.

      -

      Alex: First, open the Command Palette: Ctrl+Shift+P (Mac: Cmd+Shift+P). Then, run Git: Clone and paste: https://github.com/community-access/vscode-sci-fi-themes.git. After that, open the cloned repository when VS Code prompts. Finally, open Copilot Chat: Ctrl+Shift+I (Mac: Cmd+Shift+I). The rhythm is simple: orient, act, verify, then continue.

      +

      Alex: The reason Challenge 6.2 Step-by-Step: Open a Linked PR matters is that AI agents do not just deploy code directly; they submit pull requests. That gives the learner a simple foothold: learning to edit a file, format it in Markdown, and review a PR today prepares you to audit and approve AI-generated changes tomorrow.

      +

      Alex: The parts worth keeping in working memory are these. "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". A summary of what you changed and why (at least 50 characters).

      +

      Alex: First, in the Title field, write a short description of your change. Then, in the Body field, use the PR template if one is provided. Make sure to. After that, verify the base branch is main and the compare branch is your fix/yourname-issueXX branch. Finally, activate the Create pull request button. The rhythm is simple: orient, act, verify, then continue.

      Jamie: How would you walk the room through that step by step?

      -

      Alex: First, ask Copilot: "What does the chat.agent.thinking.phrases setting do in VS Code?". Then, read the response. Use Alt+F2 (Accessible View) if needed to read the full text. After that, ask a follow-up: "How do I apply one of these themes to my settings.json?". Finally, follow Copilot's instructions to apply one theme to your settings.json file. Think of it as a rail line: each stop confirms you are still on the right route before the next one.

      +

      Alex: Start with Challenge 6.3 Step-by-Step: Pass Required Checks: Read bot feedback, fix any issues it finds, and get all required checks to pass. The next useful detail is this: the Conversation tab of your open pull request. Think of it like entering a new building: first you find the lobby, then the room, then the door you actually need.

      +

      Alex: On the ground, that means a few things. 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.

      +

      Alex: First, wait approximately 30 seconds after opening the PR. The bot posts a validation comment. Then, read the bot comment carefully. It checks. After that, if the bot reports failures. Finally, repeat step 3 until all required checks show a green checkmark. Think of it as a rail line: each stop confirms you are still on the right route before the next one.

      +

      Jamie: Let's pause on Challenge 6.3 Step-by-Step: Pass Required Checks. What should a learner take away from it?

      +

      Alex: First, when all checks pass, request a review from a peer or the facilitator. Treat it like a recipe: do not add the next ingredient until the previous one is actually in the bowl.

      Alex: The useful habit is simple: orient first, act second, verify third. That pause before acting is part of the work.

      -

      Jamie: Let's pause on Challenge 13.3 Step-by-Step: Create Something New. What should a learner take away from it?

      -

      Alex: Start with Challenge 13.3 Step-by-Step: Create Something New: Use Copilot as a creative collaborator to generate a custom config and apply it. The next useful detail is this: VS Code with Copilot Chat open. Think of it like entering a new building: first you find the lobby, then the room, then the door you actually need.

      -

      Alex: First, open Copilot Chat: Ctrl+Shift+I (Mac: Cmd+Shift+I). Then, type a creative prompt: "Create a custom GitHub Copilot thinking phrases theme for [your favorite universe - Dune, Marvel, Studio Ghibli, Star Trek, etc.]". After that, read Copilot's generated theme. It should include an array of themed phrases. Finally, copy the generated content: select all text in the Copilot response, then Ctrl+C (Mac: Cmd+C). Think of it as a rail line: each stop confirms you are still on the right route before the next one.

      -

      Jamie: Before we leave Challenge 13.3 Step-by-Step: Create Something New, what is the practical point?

      -

      Alex: First, open your settings.json: Command Palette, then Preferences: Open User Settings (JSON). Then, paste the theme configuration into your settings. After that, save with Ctrl+S and reload VS Code: Command Palette, then Developer: Reload Window. Finally, test your new theme by asking Copilot a question and watching the thinking phrases. Treat it like a recipe: do not add the next ingredient until the previous one is actually in the bowl.

      -

      Jamie: What should the learner prove to themselves after each small task?

      -

      Alex: Here is the plain-English version of Completing Challenge 13: Submit Your Evidence. Open your assigned Challenge 13 issue and post a completion comment. Put another way, close your Challenge 13 issue when done.

      -

      Alex: This is where the talk moves from concept to action. Start with Expected Outcomes. There is something to understand, something to try, and something that proves the try worked.

      -

      Alex: The room should hear these as checkpoints. Student can install and authenticate GitHub Copilot Chat. Student can ask Copilot effective questions about code and settings. Student can use Copilot's output to customize their development environment. Student understands Copilot as a tool to explain and create, not just autocomplete.

      +

      Jamie: If I am listening before the workshop starts, what should settle in my mind first?

      +

      Alex: Start with Expected Outcomes. There is something to understand, something to try, and something that proves the try worked.

      +

      Alex: Here is what that changes in practice. Student opens a focused PR that maps to one issue. Student uses Closes XX correctly. Student can interpret bot feedback and improve the PR.

      Jamie: Let's pause on If You Get Stuck. What should a learner take away from it?

      -

      Alex: Keep the learner anchored in If You Get Stuck. Continue learning: The GitHub Skills courses Getting Started with GitHub Copilot and Customize Your GitHub Copilot Experience cover Copilot setup, prompting, and personalization. This is the part to say slowly: See Appendix Z for the full catalog.

      -

      Alex: First, extension installation fails? Reload VS Code: Ctrl+Shift+P, then Developer: Reload Window. Then, oAuth sign-in fails? Verify your GitHub account is active in the browser first, close VS Code and retry. After that, chat panel does not open? Try Ctrl+Shift+I (Mac: Cmd+Shift+I). If still nothing, check that the Copilot Chat extension is installed (not just the base Copilot extension). Finally, Copilot seems unresponsive? Click the model selector at the bottom of Chat panel and confirm you are signed in. It is like walking a hallway with named doors: read the sign, enter the right room, then confirm where you landed.

      +

      Alex: Start with If You Get Stuck. There is something to understand, something to try, and something that proves the try worked.

      +

      Alex: First, confirm your PR includes Closes XX in title or body. Then, check that changed files are only in learning-room/. After that, open the bot validation comment and resolve one required check at a time. Finally, if checks still fail, ask for peer or facilitator review with the exact error message. It is a checklist, but a meaningful one: every item creates evidence that the next step is safe.

      Jamie: Before we leave If You Get Stuck, what is the practical point?

      -

      Alex: First, cannot copy from Copilot response? Use Alt+F2 (Accessible View) to get the text in a copyable buffer. Then, ask facilitator to verify Copilot is activated and show you one example prompt. After that, finished but not sure you did it right? Compare your work against the Challenge 13 reference solution. The rhythm is simple: orient, act, verify, then continue.

      +

      Alex: First, finished but not sure you did it right? Compare your work against the Challenge 6 reference solution. It is like walking a hallway with named doors: read the sign, enter the right room, then confirm where you landed.

      +

      Jamie: What is the one idea that makes the next few steps less mysterious?

      +

      Alex: Keep the learner anchored in Learning Moment. A great PR is small, linked to an issue, and easy to review. This is the part to say slowly: Faster feedback builds confidence and momentum.

      -

      Alex: Before the learner moves on. The reason Learning Moment matters is that using Copilot as a brainstorming partner helps you write documentation that others can actually understand. That gives the learner a simple foothold: the prompting skill you practiced here - asking specific questions, iterating on responses, applying results - transfers to every AI tool you will use in your career. The interface gets friendlier when it stops being a wall of controls and starts being a set of named places.

      -

      Jamie: Let's pause on Learning Pattern Used in This Chapter. What should a learner take away from it?

      -

      Alex: Start with Learning Pattern Used in This Chapter. There is something to understand, something to try, and something that proves the try worked.

      -

      Alex: First, install the tool and verify it works before starting the task. Then, use the tool to explore and understand (ask questions, read responses). After that, use the tool to create something new (generate, customize, apply). Finally, reflect on when the tool helped and when your own judgment was better. Think of it as a rail line: each stop confirms you are still on the right route before the next one.

      -

      Alex: Hold that next to this. Here is the plain-English version of About Learning Cards in This Chapter. Throughout this chapter, look for expandable "learning cards" that show how to accomplish each task from different perspectives. Put another way, not every section has every card - only the cards that add meaningful guidance for that topic are included.

      +

      Alex: Before the learner moves on. Start with Why this feels achievable. There is something to understand, something to try, and something that proves the try worked.

      +

      Alex: That becomes easier when you listen for these cues. Scope is intentionally small. Feedback is immediate and specific. Success is visible (green checks + closed issue).

      +

      Jamie: What would you say to someone who is already bracing for this to be too much?

      +

      Alex: Start with About Learning Cards in This Chapter: This chapter provides learning cards: expandable blocks that offer perspective-specific guidance for different ways of working. The next useful detail is this: Not every card appears at every step.

      +

      Jamie: What should happen before anyone copies and runs it?

      +

      Alex: Here is the plain-English version of Local Git Alternative: The Full Branch-Edit-PR Workflow. If you cloned the learning-room in Block 0 and prefer working locally. Put another way, the web editor workflow (pencil button, "Propose changes") is the primary path taught in this chapter.

      +

      Alex: Treat examples as spoken recipes, not decorations. You may hear something like cd /Documents/learning-room; git checkout main; git pull origin main; git checkout -b fix/welcome-todos. code docs/welcome.md. Read the command, understand what it changes, then run it only when the repository state matches the lesson.

      -

      Jamie: Okay, set the room for us. What are we walking into?

      -

      Alex: This is where 1. What is GitHub Copilot becomes real: GitHub Copilot is an AI pair programmer that suggests code and text completions as you type. That matters in practice: For this workshop: Copilot helps with Markdown documentation, issue triage, PR descriptions, and commit messages - not just code.

      -

      Alex: That shows up in the workshop in a few specific ways. Complete lines of code or documentation. Generate entire functions or sections of text from comments. Answer questions about code in your workspace. Explain complex code in plain language.

      -

      Jamie: Let's pause on Installation Steps. What should a learner take away from it?

      -

      Alex: Keep the learner anchored in Installation Steps. One extension, all features: GitHub Copilot Chat is now the single all-in-one extension. This is the part to say slowly: It provides inline code suggestions, the Chat panel (Ctrl+Shift+I / Mac: Cmd+Shift+I), inline chat (Ctrl+I / Mac: Cmd+I), and all agent features. A good GitHub workflow is like a well-run meeting: everyone knows the topic, the next action, and who has the floor.

      -

      Alex: First, open Extensions sidebar: Ctrl+Shift+X (Mac: Cmd+Shift+X). Then, search for "GitHub Copilot Chat". After that, find GitHub Copilot Chat (publisher: GitHub). Finally, press Enter to open the extension detail page. It is like walking a hallway with named doors: read the sign, enter the right room, then confirm where you landed.

      -

      Jamie: Before we leave Installation Steps, what is the practical point?

      -

      Alex: First, tab to "Install" button → press Enter. Then, wait for installation to complete. The rhythm is simple: orient, act, verify, then continue.

      -

      Jamie: Let's pause on Signing In. What should a learner take away from it?

      -

      Alex: Start with Signing In. There is something to understand, something to try, and something that proves the try worked.

      -

      Alex: First, VS Code prompts: "Sign in to use GitHub Copilot". Then, navigate to the notification or click the Copilot icon in the status bar. After that, select "Sign in to GitHub". Finally, your browser opens for GitHub authentication. The rhythm is simple: orient, act, verify, then continue.

      -

      Jamie: Before we leave Signing In, what is the practical point?

      -

      Alex: First, authorize the Copilot extension. Then, return to VS Code. Think of it as a rail line: each stop confirms you are still on the right route before the next one.

      -
      -

      Alex: Here is the practical turn. Start with Verify activation. There is something to understand, something to try, and something that proves the try worked.

      -

      Alex: On the ground, that means a few things. Bottom-right status bar shows Copilot icon (looks like <). Icon should be active (not grayed out). If grayed out, click it to sign in.

      -

      Jamie: Let's pause on Command Palette. What should a learner take away from it?

      -

      Alex: Start with Command Palette. There is something to understand, something to try, and something that proves the try worked.

      -

      Alex: First, ctrl+Shift+P (Mac: Cmd+Shift+P). Then, type "Copilot: Check Status". After that, select it to see your subscription tier (Free, Pro, Enterprise). Treat it like a recipe: do not add the next ingredient until the previous one is actually in the bowl.

      -

      Alex: Keep the thread going. This is where Free tier includes becomes real: billing note: GitHub Copilot plan details are evolving. That matters in practice: Facilitators will provide current guidance at the workshop. The workshop is closer to rehearsal than lecture. You hear the move, try the move, and then check what changed.

      -

      Alex: These are the details that keep the idea from floating away. Completions and multi-line suggestions. Copilot Chat. Limited monthly usage (usually sufficient for documentation work).

      -
      -

      Jamie: If I am listening before the workshop starts, what should settle in my mind first?

      -

      Alex: Keep the learner anchored in 3. Inline Suggestions - Ghost Text Completions. Copilot suggests completions as you type, displayed as gray "ghost text" after your cursor. This is the part to say slowly: In screen reader mode, VS Code announces suggestions rather than showing them visually.

      -

      Jamie: Let's pause on While typing. What should a learner take away from it?

      -

      Alex: The reason While typing matters is that the suggestion appears as gray "ghost text" after your cursor - a preview of what Copilot thinks you want to type next. That gives the learner a simple foothold: it's there but not inserted; press Tab to accept it or Escape to dismiss.

      -

      Alex: That becomes easier when you listen for these cues. Increase ghost text contrast: Open Settings (Ctrl+,), search editorGhostText, then customize editor.ghostText.foreground in your color theme to a darker shade such as 555555. Use Accessible View instead: Press Alt+F2 when a suggestion appears. The suggestion text renders at your configured font size in a separate pane, making it far easier to read at 200%+ zoom. Word-by-word acceptance (Ctrl+Right Arrow) lets you watch each word appear at full contrast before deciding whether to continue. High Contrast themes do not automatically restyle ghost text. The color customization above is the most reliable fix.

      -

      Alex: First, Copilot analyzes your context (file content, cursor position, nearby files). Then, generates a suggestion. After that, presents the suggestion. The rhythm is simple: orient, act, verify, then continue.

      -

      Jamie: What is the one idea that makes the next few steps less mysterious?

      -

      Alex: Start with Navigating the full Suggestions Panel (Ctrl+Enter): Pressing Ctrl+Enter opens a separate side-by-side tab showing up to 10 alternative suggestions. The next useful detail is this: Alt+F2 on a single suggestion is usually faster.

      -

      Alex: A few details make that real. Switch to your screen reader's browse/virtual mode when the panel opens (NVDA: Insert+Space to toggle off Application mode; JAWS: this may happen automatically). Use heading keys (H in NVDA/JAWS browse mode) to navigate between each suggestion -- each suggestion is announced as a heading. Each suggestion is followed by an Accept button -- navigate to it with Tab or B (button key) and press Enter to insert it at your cursor position. Press Escape or close the tab to dismiss without accepting.

      -
      -

      Alex: This is the part worth saying out loud. Start with Accepting word-by-word (Ctrl+Right Arrow / Mac: Cmd+Right Arrow) is particularly useful when. There is something to understand, something to try, and something that proves the try worked.

      -

      Alex: For a learner, the useful signals are these. The suggestion starts correctly but you want to finish differently. You want to review the suggestion incrementally. You're learning and want to see how Copilot structures responses.

      -

      Jamie: What would you say to someone who is already bracing for this to be too much?

      -

      Alex: This is where Reading Suggestions with Screen Readers becomes real: visual users: If Copilot's ghost text is getting in the way, skip to "Disabling Inline Suggestions" below. That matters in practice: Screen reader users - tuning announcement verbosity.

      -

      Alex: A solid navigation habit is to prove where you are before activating controls. Headings, landmarks, and the address bar are not trivia; they are your map.

      -

      Jamie: Let's pause on NVDA. What should a learner take away from it?

      -

      Alex: Start with NVDA. There is something to understand, something to try, and something that proves the try worked.

      -

      Alex: First, NVDA Menu → Preferences → Settings → Presentation. Then, find "Report dynamic content changes". After that, reduce verbosity level or set specific delays. It is like walking a hallway with named doors: read the sign, enter the right room, then confirm where you landed.

      -
      -

      Jamie: Let's pause on JAWS. What should a learner take away from it?

      -

      Alex: Start with JAWS. There is something to understand, something to try, and something that proves the try worked.

      -

      Alex: First, settings Center → HTML/PDF/Accessibility. Then, adjust "Auto Forms Mode" and "ARIA Live Region" settings. The rhythm is simple: orient, act, verify, then continue.

      -

      Jamie: Let's pause on VoiceOver. What should a learner take away from it?

      -

      Alex: Start with VoiceOver. There is something to understand, something to try, and something that proves the try worked.

      -

      Alex: First, VoiceOver Utility → Verbosity. Then, reduce "Announcements" level. Think of it as a rail line: each stop confirms you are still on the right route before the next one.

      Jamie: Where do you want a learner to place their attention here?

      -

      Alex: Here is the plain-English version of Alternative: Use Accessible View. Press Alt+F2 (Mac: Option+F2) when a suggestion appears to read it in the Accessible View (full text, no streaming).

      +

      Alex: This is where What Is a Pull Request? becomes real: a pull request (PR) is a proposal to merge changes from one branch into another. That matters in practice.you open a PR to request that those changes be merged into the target branch (usually main).

      +

      Alex: That shows up in the workshop in a few specific ways. Edited a file directly on GitHub (web editor). Made changes in your fork. Made changes on a feature branch. What changed - a diff of every file.

      +

      Jamie: Let's pause on Navigating to Pull Requests. What should a learner take away from it?

      +

      Alex: Keep the learner anchored in Navigating to Pull Requests. Global pull requests dashboard: GitHub now shows a global pull requests page at github.com/pulls listing all open PRs across every repository you have access to. This is the part to say slowly: 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). A good GitHub workflow is like a well-run meeting: everyone knows the topic, the next action, and who has the floor.

      +

      Alex: The room should hear these as checkpoints. 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.

      +

      Alex: First, d → "Repository navigation" landmark. Then, k to navigate tabs → "Pull requests, [N] open". After that, enter to open. Finally, vO+U → Landmarks → navigate to "Repository navigation". It is like walking a hallway with named doors: read the sign, enter the right room, then confirm where you landed.

      +

      Jamie: Before we leave Navigating to Pull Requests, what is the practical point?

      +

      Alex: First, quick Nav K or VO+Right to navigate tabs → "Pull requests". Then, vO+Space to open. The rhythm is simple: orient, act, verify, then continue.

      +

      Jamie: What is the safe way to learn from that example?

      +

      Alex: The reason From a PR notification matters is that if you received a notification about a PR, follow the notification link directly to the PR page. That gives the learner a simple foothold: list and view pull requests from your terminal.

      +

      Alex: Treat examples as spoken recipes, not decorations. You may hear something like 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. Read the command, understand what it changes, then run it only when the repository state matches the lesson.

      -

      Alex: That matters because of the next idea. This is where Prompting Through Comments becomes real: Copilot reads inline comments as instructions. That matters in practice: Type this comment, press Enter, and Copilot drafts content based on your instruction.

      -

      Alex: A solid pull request habit is to separate three questions: what changed, why it changed, and what still needs review. That keeps the conversation useful instead of noisy.

      +

      Alex: Here is the practical turn. Start with Learning Cards: Navigating to Pull Requests. There is something to understand, something to try, and something that proves the try worked.

      +

      Alex: These are the details that keep the idea from floating away. 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. 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.

      Jamie: Give me the version that sounds like an instructor, not a manual.

      -

      Alex: Start with Temporarily disable for current language. There is something to understand, something to try, and something that proves the try worked.

      -

      Alex: The parts worth keeping in working memory are these. Click the Copilot icon in the status bar (bottom-right < icon). Select "Disable Completions for [language]".

      -

      Alex: Another way to ground it. The reason Permanently disable completions matters is that the Copilot status bar icon ( <) can be tiny at standard DPI. That gives the learner a simple foothold: use the Command Palette approach instead. The interface gets friendlier when it stops being a wall of controls and starts being a set of named places.

      -

      Alex: Here is what that changes in practice. Open Settings: Ctrl+, (Mac: Cmd+,) → search "Copilot enable" → uncheck "Enable Inline Suggestions". Ctrl+Shift+P → type "Copilot: Toggle Completions" → press Enter. This toggles inline suggestions on/off without needing to find a small icon.

      +

      Alex: Here is the plain-English version of The Pull Request List Page. The PR list works identically to the Issues list. Put another way, for screen reader users, - PR list semantics: The PR list does not have individual ARIA item containers with per-item semantics.

      +

      Alex: A few details make that real. 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.

      +

      Jamie: Let's pause on Navigating the PR Tab Bar. What should a learner take away from it?

      +

      Alex: This is where Navigating the PR Tab Bar becomes real: the Conversation, Commits, and Files changed tabs are in a "Pull request navigation tabs" landmark. That matters in practice: The three tabs - Conversation, Commits, and Files changed - appear just below the PR title. The workshop is closer to rehearsal than lecture. You hear the move, try the move, and then check what changed.

      +

      Alex: The practical takeaway is this. 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.

      +

      Alex: First, press D → navigate to "Pull request navigation tabs". Then, press ← or → arrow keys to move between tab options. After that, press Enter to activate a tab. Finally, vO+U → Landmarks → "Pull request navigation tabs". It is a checklist, but a meaningful one: every item creates evidence that the next step is safe.

      +

      Jamie: Before we leave Navigating the PR Tab Bar, what is the practical point?

      +

      Alex: First, vO+Right to move between tabs. Then, vO+Space to activate. It is like walking a hallway with named doors: read the sign, enter the right room, then confirm where you landed.

      -

      Jamie: How should a learner choose a tool without feeling judged by the choice?

      -

      Alex: Start with Temporarily disable via Command Palette. There is something to understand, something to try, and something that proves the try worked.

      -

      Alex: The practical takeaway is this. 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).

      -

      Alex: That connects to another useful point. Start with Permanently disable via Settings. There is something to understand, something to try, and something that proves the try worked.

      -

      Alex: The practical takeaway is this. Ctrl+, (Mac: Cmd+,) → search "inline suggestions" → toggle off "GitHub Copilot: Enable Inline Completions".

      -

      Jamie: Let's pause on Learning Cards: Inline Suggestions. What should a learner take away from it?

      -

      Alex: Start with Learning Cards: Inline Suggestions. There is something to understand, something to try, and something that proves the try worked.

      -

      Alex: The practical takeaway is this. 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. 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.

      +

      Jamie: Let's pause on PR Description. What should a learner take away from it?

      +

      Alex: Start with PR Description. There is something to understand, something to try, and something that proves the try worked.

      +

      Alex: First, 2 → navigate to "Description" h2 heading. Then, ↓ to read the description. After that, markdown renders as semantic HTML - headings, lists, code blocks are fully accessible. It is like walking a hallway with named doors: read the sign, enter the right room, then confirm where you landed.

      +

      Jamie: Let's pause on Status Checks Section. What should a learner take away from it?

      +

      Alex: The reason Status Checks Section matters is that below the description, the status checks summary shows whether automated tests passed. That gives the learner a simple foothold: status checks appear as a coloured banner below the PR description - green tick for passed, red X for failed, yellow spinner for running.

      +

      Alex: The practical takeaway is this. "All checks have passed" / "Some checks failed" / "Checks pending". A "Show all checks" button or link.

      +

      Alex: First, press H or 2 to find the "Checks" or "Status checks" heading. Then, press K to navigate links for individual check names. After that, press Enter on a check to see its details. Finally, quick Nav H or VO+Cmd+H to jump to the "Checks" or "Status checks" heading. The rhythm is simple: orient, act, verify, then continue.

      +

      Jamie: Before we leave Status Checks Section, what is the practical point?

      +

      Alex: First, quick Nav K to navigate check name links. Then, vO+Space on a check to see its details. Think of it as a rail line: each stop confirms you are still on the right route before the next one.

      +

      Jamie: Let's pause on Review Comments. What should a learner take away from it?

      +

      Alex: Start with Review Comments: Each review comment thread is an h3.

      +

      Alex: The practical takeaway is this. 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.

      -

      Alex: Now bring the learner back to the room. Keep the learner anchored in 4. GitHub Copilot Chat - Conversational Assistance. See also: Appendix K: Copilot Reference has the complete slash command and chat variable reference. This is the part to say slowly: Copilot Chat is a full conversation interface where you ask questions, request explanations, and have content drafted. A good GitHub workflow is like a well-run meeting: everyone knows the topic, the next action, and who has the floor.

      -

      Jamie: What is the safe way to learn from that example?

      -

      Alex: The reason Opening Copilot Chat matters is that primary panel: Ctrl+Shift+I (Mac: Cmd+Shift+I). That gives the learner a simple foothold: opens the Chat panel on the right side of VS Code.

      -

      Alex: The practical takeaway is this. 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.

      -

      Alex: Treat examples as spoken recipes, not decorations. You may hear something like gh extension install github/gh-copilot. gh copilot suggest "How do I squash the last 3 commits?". Read the command, understand what it changes, then run it only when the repository state matches the lesson.

      -

      Alex: Keep the teaching thread moving. Start with Chat Modes: Copilot Chat has four modes, selected from a dropdown at the bottom of the Chat input area. The next useful detail is this: Each mode changes how Copilot interprets your request and what it can do.

      +

      Jamie: Let's pause on Resolving conversations. What should a learner take away from it?

      +

      Alex: Here is the plain-English version of Resolving conversations. When a review comment has been addressed, you can mark the conversation as resolved. Put another way, resolved conversations are still accessible - they collapse but can be expanded again. It is like learning a transit route. The names of the stops matter because they tell you whether you are still going the right direction.

      +

      Alex: First, navigate to the conversation thread (3 to jump between comment headings). Then, tab to the end of the thread to find the "Resolve conversation" button. After that, press Enter to mark it resolved. Finally, the conversation collapses and shows as "Resolved". Treat it like a recipe: do not add the next ingredient until the previous one is actually in the bowl.

      +

      Jamie: Let's pause on Learning Cards: Reading the Conversation Tab. What should a learner take away from it?

      +

      Alex: Start with Learning Cards: Reading the Conversation Tab. There is something to understand, something to try, and something that proves the try worked.

      +

      Alex: The practical takeaway is this. 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. 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.

      +

      Jamie: Let's pause on Reading the Checks Tab. What should a learner take away from it?

      +

      Alex: Keep the learner anchored in Reading the Checks Tab. The Checks tab shows the status of automated tests, CI workflows, and other verification processes running on your PR. This is the part to say slowly: It helps you verify whether your changes pass all required tests before merging.

      +

      Alex: The practical takeaway is this. Navigate through the check steps with K or Tab. Activate a step for more details.

      +

      Alex: First, navigate to the "Pull request tabs" landmark (D). Then, navigate between tab links (K or Tab) and activate "Checks". After that, press D to jump to the "check suites" section - this moves focus to the collapsed details button of the first check. Finally, press B or Tab to navigate between check buttons; each button is labeled with the check's name. It is like walking a hallway with named doors: read the sign, enter the right room, then confirm where you landed.

      +

      Jamie: Before we leave Reading the Checks Tab, what is the practical point?

      +

      Alex: First, press Enter or Space to expand a check and reveal its logs. Then, for a summary view: press D to navigate to the "check run summary" section. After that, vO+U - Landmarks - "Pull request tabs" - activate "Checks". Finally, vO+U - Landmarks - navigate to "check suites" section. The rhythm is simple: orient, act, verify, then continue.

      -

      Jamie: Let's pause on Switching modes. What should a learner take away from it?

      -

      Alex: Here is the plain-English version of Switching modes. 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. Put another way, agent mode is powerful but works best once you're comfortable reviewing its output.

      -

      Alex: The practical takeaway is this. 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.

      -

      Alex: Keep the teaching thread moving. This is where Choosing a Model becomes real: Copilot gives you access to AI models from OpenAI, Anthropic (Claude), Google (Gemini), xAI (Grok), and others. That matters in practice: 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"). The workshop is closer to rehearsal than lecture. You hear the move, try the move, and then check what changed.

      -

      Jamie: Let's pause on Quick guidance. What should a learner take away from it?

      -

      Alex: Keep the learner anchored in Quick guidance. Model availability changes frequently. This is the part to say slowly: Facilitators will provide current guidance at the workshop.

      -

      Alex: The practical takeaway is this. 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.

      +

      Jamie: Let's pause on Learning Cards: Reading the Checks Tab. What should a learner take away from it?

      +

      Alex: Start with Learning Cards: Reading the Checks Tab. There is something to understand, something to try, and something that proves the try worked.

      +

      Alex: The practical takeaway is this. 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. 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.

      +

      Alex: Now bring the learner back to the room. Start with Reading the Files Changed Tab: the learner will read diffs - the before/after state of every file that changed. The next useful detail is this: This guide uses GitHub's improved Files Changed experience. Think of it like entering a new building: first you find the lobby, then the room, then the door you actually need.

      +

      Jamie: Let's pause on File Tree (left panel). What should a learner take away from it?

      +

      Alex: Here is the plain-English version of File Tree (left panel). The file tree lists every changed file. Put another way, use it to jump directly to a specific file's diff.

      +

      Alex: The practical takeaway is this. 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.

      +

      Alex: First, d → navigate to "File tree" region. Then, ↑/↓ to navigate the file list. After that, enter to jump to that file's diff. Finally, vO+U → Landmarks → navigate to "File tree" region. Treat it like a recipe: do not add the next ingredient until the previous one is actually in the bowl.

      +

      Jamie: Before we leave File Tree (left panel), what is the practical point?

      +

      Alex: First, vO+Down to move through the file list. Then, vO+Space to jump to that file's diff. It is a checklist, but a meaningful one: every item creates evidence that the next step is safe.

      -

      Jamie: Let's pause on Panel layout (top to bottom). What should a learner take away from it?

      -

      Alex: Start with Panel layout (top to bottom). There is something to understand, something to try, and something that proves the try worked.

      -

      Alex: The practical takeaway is this. Type your prompt here. Press Ctrl+Enter (Mac: Cmd+Enter) or Enter to send. Choose which AI model to use (GPT-4, Claude, etc.). Some models better for code, others for prose. Shows your previous prompts and Copilot's responses. Navigate with Up/Down Arrow.

      -

      Alex: First, chat input field (multi-line text area). Then, model selector dropdown. After that, conversation history. Finally, action buttons. The rhythm is simple: orient, act, verify, then continue.

      -

      Jamie: Let's pause on NVDA/JAWS. What should a learner take away from it?

      -

      Alex: Start with NVDA/JAWS. There is something to understand, something to try, and something that proves the try worked.

      -

      Alex: The practical takeaway is this. 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.

      -

      Alex: Keep the teaching thread moving. Start with VoiceOver. There is something to understand, something to try, and something that proves the try worked.

      -

      Alex: The practical takeaway is this. 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.

      +

      Alex: That matters because of the next idea. Start with The Diff for a File. There is something to understand, something to try, and something that proves the try worked.

      +

      Alex: The practical takeaway is this. 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.

      +

      Jamie: Let's pause on Lines in a diff are read as. What should a learner take away from it?

      +

      Alex: Start with Lines in a diff are read as. There is something to understand, something to try, and something that proves the try worked.

      +

      Alex: The practical takeaway is this. + Added line - line that was added. Removed line - line that was removed. Context line - unchanged line shown for context.

      +

      Jamie: Let's pause on Navigating the diff with a screen reader. What should a learner take away from it?

      +

      Alex: The reason Navigating the diff with a screen reader matters is that each file's diff shows added lines in green and removed lines in red. That gives the learner a simple foothold: scroll the page to read through changes. The interface gets friendlier when it stops being a wall of controls and starts being a set of named places.

      +

      Alex: The practical takeaway is this. 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.

      +

      Alex: First, t to jump to the next diff table. Then, switch to Focus Mode: Insert+Space (NVDA) or Insert+Z (JAWS). After that, ctrl+Alt+↓ to move down one row (next diff line), Ctrl+Alt+↑ to move up. Finally, ctrl+Alt+→ to read across columns (line number change type content). The rhythm is simple: orient, act, verify, then continue.

      +

      Jamie: Before we leave Navigating the diff with a screen reader, what is the practical point?

      +

      Alex: First, the screen reader reads: "+ Add accessible name to submit button". Then, collapsed sections contain unchanged code. Focus the expand/disclosure control and activate it (Enter or Space) to reveal the hidden lines. After that, t or VO+U → Tables → select the diff table. Finally, vO+Shift+Down to enter the table. Think of it as a rail line: each stop confirms you are still on the right route before the next one.

      -

      Jamie: What stays the same when the tool changes?

      -

      Alex: This is where Using Slash Commands becomes real: type / in Copilot Chat to see available commands.

      -

      Jamie: Let's pause on Example. What should a learner take away from it?

      -

      Alex: Start with Example. There is something to understand, something to try, and something that proves the try worked.

      -

      Alex: First, select a block of complex Markdown. Then, open Chat: Ctrl+Shift+I (Mac: Cmd+Shift+I). After that, type /explain. Finally, Copilot explains the structure and purpose. It is like walking a hallway with named doors: read the sign, enter the right room, then confirm where you landed.

      -

      Jamie: Let's pause on Built-in Actions via Command Palette. What should a learner take away from it?

      -

      Alex: The reason Built-in Actions via Command Palette matters is that Copilot registers actions directly in the Command Palette. That gives the learner a simple foothold: this provides a discoverable way to use Copilot without remembering slash commands or keyboard shortcuts.

      -

      Alex: First, open Command Palette: F1 or Ctrl+Shift+P (Mac: Cmd+Shift+P). Then, type copilot. After that, browse the list of available actions. The rhythm is simple: orient, act, verify, then continue.

      +

      Jamie: Let's pause on Placing an inline comment on a diff line. What should a learner take away from it?

      +

      Alex: Start with Placing an inline comment on a diff line: Hover over any line in the diff - a blue + button appears on the left margin. The next useful detail is this: Click it to open a comment box for that line.

      +

      Alex: The practical takeaway is this. 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.

      +

      Alex: First, navigate to the specific line in the diff (using the table navigation above). Then, while focused on that line, a comment button appears - press Enter or Space to activate it. After that, a comment box opens below the line. Finally, focus Mode → type your comment. Think of it as a rail line: each stop confirms you are still on the right route before the next one.

      +

      Jamie: Before we leave Placing an inline comment on a diff line, what is the practical point?

      +

      Alex: First, tab to Add single comment button (instant comment) OR Start a review (to batch comments). Treat it like a recipe: do not add the next ingredient until the previous one is actually in the bowl.

      +

      Jamie: Let's pause on Multi-line comment (Windows). What should a learner take away from it?

      +

      Alex: Here is the plain-English version of Multi-line comment (Windows). Screen reader users (VoiceOver - macOS).

      +

      Alex: First, focus the first line you want to comment on. Then, press Shift+↓ to extend the selection to additional lines. After that, a comment button appears - activate it. Finally, the comment applies to the full range of selected lines. Treat it like a recipe: do not add the next ingredient until the previous one is actually in the bowl.

      +

      Jamie: Before we leave Multi-line comment (Windows), what is the practical point?

      +

      Alex: First, navigate to the specific line in the diff (using the table navigation above). Then, while focused on that line, VO+Space on the comment button that appears. After that, a comment box opens below the line. Finally, vO+Shift+Down to interact with the text area, then type your comment. It is a checklist, but a meaningful one: every item creates evidence that the next step is safe.

      +

      Jamie: Let's pause on Multi-line comment (macOS). What should a learner take away from it?

      +

      Alex: Start with Multi-line comment (macOS). There is something to understand, something to try, and something that proves the try worked.

      +

      Alex: First, focus the first line and Shift+↓ to extend the selection. Then, vO+Space on the comment button that appears. After that, the comment applies to the full range of selected lines. It is a checklist, but a meaningful one: every item creates evidence that the next step is safe.

      -

      Alex: Keep the teaching thread moving. Start with Learning Cards: Copilot Chat. There is something to understand, something to try, and something that proves the try worked.

      -

      Alex: The practical takeaway is this. 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?"). 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.

      -

      Jamie: Let's pause on 5. Copilot Edits -- Making Multi-File Changes. What should a learner take away from it?

      -

      Alex: Here is the plain-English version of 5. Copilot Edits -- Making Multi-File Changes. As of VS Code 1.118 (April 2026), the separate Edit chat mode is being merged into Agent mode. Put another way, agent mode now supports the same working-set diff workflow that Edit mode provided.

      -

      Alex: The practical takeaway is this. 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.

      -

      Jamie: Let's pause on How to use Copilot Edits. What should a learner take away from it?

      -

      Alex: This is where How to use Copilot Edits becomes real: Copilot Edits shows you the full diff first.

      -

      Alex: The practical takeaway is this. Click "Add Files." above the chat input,. Type in the chat input and select a file from the picker,. Right-click a file in the Explorer and choose "Add File to Copilot Edits".

      -

      Alex: First, open Copilot Chat: Ctrl+Shift+I (Mac: Cmd+Shift+I). Then, at the bottom of the Chat panel, click the mode dropdown and select Edit. After that, add files to your working set -- these are the files Copilot is allowed to edit. Finally, 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". It is a checklist, but a meaningful one: every item creates evidence that the next step is safe.

      -

      Jamie: Before we leave How to use Copilot Edits, what is the practical point?

      -

      Alex: First, press Enter -- Copilot shows a diff of proposed changes in each file. Then, review the changes: use Accept or Reject on individual files, or Accept All / Reject All. It is like walking a hallway with named doors: read the sign, enter the right room, then confirm where you landed.

      +

      Alex: Hold that next to this. Keep the learner anchored in Viewing comments within the diff. Inline comments appear as expandable threads within the diff table. This is the part to say slowly: Navigate to them with 3 (they are h3 headings). A good GitHub workflow is like a well-run meeting: everyone knows the topic, the next action, and who has the floor.

      +

      Jamie: Let's pause on Learning Cards: Reading the Files Changed Tab. What should a learner take away from it?

      +

      Alex: Start with Learning Cards: Reading the Files Changed Tab. There is something to understand, something to try, and something that proves the try worked.

      +

      Alex: The practical takeaway is this. 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. 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.

      +

      Jamie: Let's pause on Tool Cards: Open a Pull Request. What should a learner take away from it?

      +

      Alex: Start with Tool Cards: Open a Pull Request: VS Code Desktop (GitHub Pull Requests extension).

      +

      Alex: First, push your branch, then click the Compare & pull request banner (or go to Pull requests New pull request ). Then, set base branch to main, compare branch to yours. After that, fill in the title and description, then click Create pull request. Finally, after committing changes, click the Source Control icon. Think of it as a rail line: each stop confirms you are still on the right route before the next one.

      +

      Jamie: Before we leave Tool Cards: Open a Pull Request, what is the practical point?

      +

      Alex: First, click Create Pull Request in the Source Control panel header. Then, fill in details and submit. After that, press Ctrl+Shift+P, type GitHub Pull Requests: Create Pull Request. Finally, select base and compare branches. Treat it like a recipe: do not add the next ingredient until the previous one is actually in the bowl.

      +

      Alex: Treat examples as spoken recipes, not decorations. You may hear something like git push -u origin your-branch; gh pr create --title "Your title" --body "Description". Read the command, understand what it changes, then run it only when the repository state matches the lesson.

      -

      Jamie: Let's pause on Navigating the diff with a screen reader. What should a learner take away from it?

      -

      Alex: Start with Navigating the diff with a screen reader. There is something to understand, something to try, and something that proves the try worked.

      -

      Alex: The practical takeaway is this. 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.

      -

      Alex: Keep the teaching thread moving. Start with Working set tips. There is something to understand, something to try, and something that proves the try worked.

      -

      Alex: The practical takeaway is this. 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.

      -

      Jamie: Let's pause on Learning Cards: Copilot Edits. What should a learner take away from it?

      -

      Alex: Start with Learning Cards: Copilot Edits. There is something to understand, something to try, and something that proves the try worked.

      -

      Alex: The practical takeaway is this. 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. 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.

      +

      Jamie: Let's pause on From the web editor workflow (editing a file on GitHub). What should a learner take away from it?

      +

      Alex: Start with From the web editor workflow (editing a file on GitHub). There is something to understand, something to try, and something that proves the try worked.

      +

      Alex: First, you edited a file → GitHub showed a "Propose changes" form. Then, you named your branch and activated "Propose changes". After that, GitHub redirected you to the "Open a pull request" page. Treat it like a recipe: do not add the next ingredient until the previous one is actually in the bowl.

      +

      Jamie: Let's pause on From a fork or feature branch. What should a learner take away from it?

      +

      Alex: This is where From a fork or feature branch becomes real: screen reader users (NVDA / JAWS - Windows). That matters in practice: Screen reader users (VoiceOver - macOS). The workshop is closer to rehearsal than lecture. You hear the move, try the move, and then check what changed.

      +

      Alex: First, navigate to the repository on GitHub. Then, if you recently pushed, a yellow banner "Compare & pull request" appears at the top - click it. After that, if no banner appears: click the Pull requests tab → click the green New pull request button. Finally, use the branch dropdowns to choose your base branch (what to merge into) and your compare branch (your changes). It is a checklist, but a meaningful one: every item creates evidence that the next step is safe.

      +

      Jamie: Before we leave From a fork or feature branch, what is the practical point?

      +

      Alex: First, click Create pull request. Then, navigate to the repository. After that, a "Compare & pull request" banner may appear (if you recently pushed) - activate it. Finally, oR: Navigate to Pull Requests tab → "New pull request". It is like walking a hallway with named doors: read the sign, enter the right room, then confirm where you landed.

      +

      Jamie: What should they understand before typing anything?

      +

      Alex: Keep the learner anchored in Description field. Copilot can write your PR description: If your account has Copilot access, a "Copilot actions" button appears in the description toolbar. This is the part to say slowly: 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.

      +

      Alex: Treat examples as spoken recipes, not decorations. You may hear something like Step 1: Tab to the body text area; Step 2: Focus Mode → type using the PR template (if provided). 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 for the dismiss control; Related Issues; Closes 42; Testing; - Tested with NVDA + Chrome on Windows 11; -. Read the command, understand what it changes, then run it only when the repository state matches the lesson.

      -

      Alex: Keep the teaching thread moving. Here is the plain-English version of 6. Agent Mode -- Let Copilot Drive. See also: Chapter 19: Accessibility Agents and Chapter 20: Build Your Agent for creating your own Copilot agent. Put another way, agent mode is the most autonomous way to use Copilot.

      -

      Alex: The practical takeaway is this. 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.

      -

      Jamie: Let's pause on How to use Agent mode. What should a learner take away from it?

      -

      Alex: Start with How to use Agent mode. There is something to understand, something to try, and something that proves the try worked.

      -

      Alex: First, open Copilot Chat: Ctrl+Shift+I (Mac: Cmd+Shift+I). Then, select Agent from the mode dropdown at the bottom of the Chat panel. After that, 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". Finally, Copilot begins working -- it shows each step it's taking and asks for approval before running terminal commands. It is a checklist, but a meaningful one: every item creates evidence that the next step is safe.

      -

      Jamie: Before we leave How to use Agent mode, what is the practical point?

      -

      Alex: First, watch the progress in the Chat panel; review any proposed changes in the editor. It is like walking a hallway with named doors: read the sign, enter the right room, then confirm where you landed.

      -

      Alex: Keep the teaching thread moving. Keep the learner anchored in 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. This is the part to say slowly: When Copilot pauses for approval, focus moves to the approval dialog in the Chat panel. A good GitHub workflow is like a well-run meeting: everyone knows the topic, the next action, and who has the floor.

      -

      Alex: The practical takeaway is this. Allow -- run this command once. Allow Always -- always allow this command type without asking again (use carefully). Cancel -- stop and don't run it.

      +

      Jamie: Let's pause on Setting a Draft PR. What should a learner take away from it?

      +

      Alex: The reason Setting a Draft PR matters is that if your work is not finished, open as a Draft.

      +

      Alex: First, after filling in the form, find the dropdown arrow next to "Create pull request". Then, select "Create draft pull request". After that, this signals to reviewers that it is not ready for formal review yet. The rhythm is simple: orient, act, verify, then continue.

      +

      Jamie: Let's pause on Draft Pull Requests - Full Lifecycle. What should a learner take away from it?

      +

      Alex: Start with Draft Pull Requests - Full Lifecycle: A draft pull request is a PR explicitly marked as a work in progress. The next useful detail is this: It is visible to the team, can receive comments, and runs CI - but is blocked from being merged until you mark it ready.

      +

      Alex: Another way to ground it. Start with When to use a draft. There is something to understand, something to try, and something that proves the try worked.

      +

      Alex: The practical takeaway is this. You want to show your approach and get early feedback before finishing. You need CI to run but don't want accidental merges. You are working across multiple days and want your progress visible. You want to pair with a collaborator on the work.

      -

      Jamie: Let's pause on Learning Cards: Agent Mode. What should a learner take away from it?

      -

      Alex: Start with Learning Cards: Agent Mode. There is something to understand, something to try, and something that proves the try worked.

      -

      Alex: The practical takeaway is this. 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. 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.

      -

      Alex: Keep the teaching thread moving. Start with 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. The next useful detail is this: Unlike regular inline suggestions that complete what you're currently typing, NES looks ahead to related edits elsewhere in the file.

      -

      Jamie: Let's pause on Turning on Next Edit Suggestions. What should a learner take away from it?

      -

      Alex: Start with Turning on Next Edit Suggestions. There is something to understand, something to try, and something that proves the try worked.

      -

      Alex: First, open Settings: Ctrl+, (Mac: Cmd+,). Then, search for nextEditSuggestions. After that, enable "GitHub Copilot: Next Edit Suggestions". Treat it like a recipe: do not add the next ingredient until the previous one is actually in the bowl.

      +

      Jamie: Let's pause on What a draft PR does differently. What should a learner take away from it?

      +

      Alex: Start with What a draft PR does differently. There is something to understand, something to try, and something that proves the try worked.

      +

      Alex: The practical takeaway is this. The merge button is disabled - even an authorized maintainer cannot merge a draft. The PR header shows a grey "Draft" badge instead of the green "Open" badge. Reviewers are not auto-notified (no review requests are sent until ready). CI workflows still run normally.

      +

      Jamie: Let's pause on Mark a draft ready for review. What should a learner take away from it?

      +

      Alex: Start with Mark a draft ready for review. There is something to understand, something to try, and something that proves the try worked.

      +

      Alex: First, open the PR. Then, navigate to the "Reviewers" sidebar or scroll to bottom of the Conversation tab. After that, find and activate the "Ready for review" button. Finally, the draft badge changes to "Open" and reviewers are notified. It is like walking a hallway with named doors: read the sign, enter the right room, then confirm where you landed.

      +

      Jamie: Let's pause on Convert an open PR to draft (after opening). What should a learner take away from it?

      +

      Alex: The reason Convert an open PR to draft (after opening) matters is that GitHub CLI (gh) alternative - draft PR lifecycle. That gives the learner a simple foothold: manage draft PRs from your terminal.

      +

      Alex: First, in the right sidebar, find the "Reviewers" section. Then, look for the "Convert to draft" link (below the review status). After that, confirm in the dialog - this removes merge eligibility until you mark it ready again. The rhythm is simple: orient, act, verify, then continue.

      +

      Alex: Treat examples as spoken recipes, not decorations. You may hear something like Create a draft PR; gh pr create --draft --title "WIP: Add carousel keyboard nav"; Mark a draft ready for review; gh pr ready 42; Check PR status (shows draft state); gh pr view 42; List only draft PRs; gh pr list --draft. Read the command, understand what it changes, then run it only when the repository state matches the lesson.

      -

      Alex: Keep the teaching thread moving. This is where How it works in practice becomes real: nES is announced as an inline suggestion at the predicted location. That matters in practice: With screen reader optimized mode on (Shift+Alt+F1), VS Code announces when a next edit suggestion is available. The workshop is closer to rehearsal than lecture. You hear the move, try the move, and then check what changed.

      -

      Alex: The practical takeaway is this. 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.

      -

      Jamie: Let's pause on 8. Copilot on GitHub.com. What should a learner take away from it?

      -

      Alex: Keep the learner anchored in 8. Copilot on GitHub.com. You don't need VS Code to use Copilot. This is the part to say slowly: GitHub.com has Copilot built directly into the website -- useful for quick questions, reviewing code in the browser, drafting PR descriptions, and more.

      -

      Jamie: Let's pause on Opening Copilot Chat on GitHub.com. What should a learner take away from it?

      -

      Alex: The reason Opening Copilot Chat on GitHub.com matters is that Copilot on GitHub.com has context about your repositories, issues, PRs, and code -- you can reference them directly.

      -

      Alex: First, go to github.com -- you must be signed in. Then, look for the Copilot icon (a circle with dot pattern) in the top navigation bar. After that, click it (or press? then select Copilot from the command palette) to open the chat panel. Finally, type your question and press Enter. The rhythm is simple: orient, act, verify, then continue.

      +

      Alex: That connects to another useful point. Start with Learning Cards: Opening a Pull Request. There is something to understand, something to try, and something that proves the try worked.

      +

      Alex: The practical takeaway is this. After editing a file on GitHub, the "Propose changes" form has a branch name field and a commit message field; press Tab to move between them. On the "Open a pull request" page, press F to jump to the Title field; Tab moves to the Description text area. Press Ctrl+Enter from inside the description text area to submit the PR without finding the Create button. The "Compare & pull request" yellow banner appears at the top of the repo after a recent push; at high zoom it may span the full width of the page. The branch comparison dropdowns (base and compare) use small text; zoom in on the area above the diff preview to read them. Draft PR: look for the dropdown arrow next to the green "Create pull request" button to switch to "Create draft pull request".

      +

      Jamie: Let's pause on Requesting reviewers. What should a learner take away from it?

      +

      Alex: Here is the plain-English version of Requesting reviewers. From the sidebar Reviewers section. Put another way, why some reviews are requested automatically: A file called CODEOWNERS in many repositories maps file paths to specific people or teams.

      +

      Alex: First, navigate to "Reviewers" heading (3 or H). Then, activate the gear button. After that, type a username in the search field. Finally, select from the dropdown. Treat it like a recipe: do not add the next ingredient until the previous one is actually in the bowl.

      +

      Jamie: Before we leave Requesting reviewers, what is the practical point?

      +

      Alex: First, escape to save. It is a checklist, but a meaningful one: every item creates evidence that the next step is safe.

      +

      Alex: Keep the thread going. This is where Submitting a Review becomes real: when you are asked to review a PR, you have three options.

      +

      Alex: The practical takeaway is this. Comment - leave feedback without a verdict; does not block merging. Approve - signal you are satisfied; often required before merge. Request changes - indicate changes must be addressed; blocks merge until resolved.

      -

      Jamie: Let's pause on Copilot for Pull Request Summaries. What should a learner take away from it?

      -

      Alex: Start with Copilot for Pull Request Summaries: When you open a pull request on GitHub.com, Copilot can generate a description for you automatically. The next useful detail is this: Copilot-generated PR descriptions are usually a solid first draft.

      -

      Alex: First, start creating a new pull request: go to your branch and select "Compare & pull request". Then, in the PR form, look for the Copilot icon next to the description field. After that, click it -- Copilot reads your commits and diff and writes a draft description. Finally, review and edit the draft -- it typically includes what changed and why. Think of it as a rail line: each stop confirms you are still on the right route before the next one.

      -

      Jamie: Before we leave Copilot for Pull Request Summaries, what is the practical point?

      -

      Alex: First, submit the PR. Treat it like a recipe: do not add the next ingredient until the previous one is actually in the bowl.

      -

      Alex: Keep the teaching thread moving. Here is the plain-English version of Copilot for Code Review on GitHub.com. Maintainers can use Copilot to review pull requests on GitHub.com. Put another way, as a contributor, you may see Copilot-authored review comments on your PR -- they look like regular review comments but are labelled "Copilot". It is like learning a transit route. The names of the stops matter because they tell you whether you are still going the right direction.

      -

      Alex: The practical takeaway is this. 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.

      -

      Jamie: Let's pause on Learning Cards: Copilot on GitHub.com. What should a learner take away from it?

      -

      Alex: Start with Learning Cards: Copilot on GitHub.com. There is something to understand, something to try, and something that proves the try worked.

      -

      Alex: The practical takeaway is this. 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. 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.

      -
      -

      Alex: Keep the teaching thread moving. Keep the learner anchored in 9. Effective Prompting for Documentation Work. Copilot works best with clear, specific prompts. This is the part to say slowly: The more context you provide, the better the response.

      -

      Jamie: What should they understand before typing anything?

      -

      Alex: Start with Good prompt. There is something to understand, something to try, and something that proves the try worked.

      -

      Alex: Treat examples as spoken recipes, not decorations. You may hear something like 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. Read the command, understand what it changes, then run it only when the repository state matches the lesson.

      -

      Jamie: Let's pause on What makes it good. What should a learner take away from it?

      -

      Alex: Start with What makes it good. There is something to understand, something to try, and something that proves the try worked.

      -

      Alex: First, specific scope: "3-paragraph section". Then, clear topic: "navigate the VS Code Explorer sidebar". After that, target audience: "screen reader users" who "never used VS Code". Finally, required details: "keyboard shortcuts for NVDA and JAWS". Think of it as a rail line: each stop confirms you are still on the right route before the next one.

      -

      Jamie: Before we leave What makes it good, what is the practical point?

      -

      Alex: First, format guidance: "headings and bullet points". Treat it like a recipe: do not add the next ingredient until the previous one is actually in the bowl.

      -
      -

      Jamie: What should happen before anyone copies and runs it?

      -

      Alex: Start with Pattern 2: Generate with Constraints. There is something to understand, something to try, and something that proves the try worked.

      -

      Alex: Treat examples as spoken recipes, not decorations. You may hear something like 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. Read the command, understand what it changes, then run it only when the repository state matches the lesson.

      -

      Alex: Keep the teaching thread moving. This is where Iterating on Responses becomes real: Copilot's first response is a draft.

      -

      Jamie: How do you keep commands from becoming magic words?

      -

      Alex: Keep the learner anchored in Follow-up prompts. Copilot remembers the conversation context - just say what to change.

      -

      Alex: Treat examples as spoken recipes, not decorations. You may hear something like 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. Read the command, understand what it changes, then run it only when the repository state matches the lesson.

      -
      -

      Alex: Keep the teaching thread moving. Start with Learning Cards: Effective Prompting. There is something to understand, something to try, and something that proves the try worked.

      -

      Alex: The practical takeaway is this. 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. 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.

      -

      Jamie: Let's pause on 10. Custom Instructions vs Custom Agents. What should a learner take away from it?

      -

      Alex: Start with 10. Custom Instructions vs Custom Agents: Two distinct tools shape how Copilot behaves. The next useful detail is this: Understanding the difference is critical for working with Accessibility Agents (see Chapter 16: Accessibility Agents).

      -

      Alex: Keep the teaching thread moving. Here is the plain-English version of Custom Instructions. File.github/copilot-instructions.md. Put another way, purpose: Always-on background guidance for every Copilot interaction.

      -
      -

      Jamie: Let's pause on What they do. What should a learner take away from it?

      -

      Alex: Start with What they do. There is something to understand, something to try, and something that proves the try worked.

      -

      Alex: The practical takeaway is this. Apply to all code suggestions automatically. Set project-wide standards. Influence tone and style. Provide context about your project's conventions.

      -

      Jamie: Let's pause on Example.github/copilot-instructions.md. What should a learner take away from it?

      -

      Alex: Keep the learner anchored in Example.github/copilot-instructions.md. When active: Every time Copilot generates a suggestion (inline or in Chat). A good GitHub workflow is like a well-run meeting: everyone knows the topic, the next action, and who has the floor.

      -

      Alex: Treat examples as spoken recipes, not decorations. You may hear something like 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. Read the command, understand what it changes, then run it only when the repository state matches the lesson.

      -

      Jamie: Let's pause on Custom Agents. What should a learner take away from it?

      -

      Alex: The reason Custom Agents matters is that files.github/agents/[name].agent.md. That gives the learner a simple foothold: purpose: On-demand, focused workflows that you deliberately invoke.

      -
      -

      Alex: Keep the teaching thread moving. Start with What they do. There is something to understand, something to try, and something that proves the try worked.

      -

      Alex: The practical takeaway is this. Perform specific, repeatable tasks. Can access specific tools (GitHub API, file system, terminal). Generate structured output (reports, reviews, analysis). Execute multi-step workflows.

      -

      Jamie: Let's pause on Example agent names. What should a learner take away from it?

      -

      Alex: Here is the plain-English version of Example agent names. When active: Only when you type @agent-name in Copilot Chat. Put another way, see Chapter 16: Accessibility Agents for complete agent documentation.

      -

      Alex: The practical takeaway is this. @daily-briefing - Summarize repository activity. @issue-tracker - Find and prioritize issues. @pr-review - Generate PR review documentation. @analytics - Team contribution metrics.

      -

      Jamie: What decision is this helping them make?

      -

      Alex: Start with Comparison Table. There is something to understand, something to try, and something that proves the try worked.

      -

      Alex: Use the comparison to make a decision, not to recite a table. The main contrasts are: Custom Instructions means Custom Agent. When active means Background - every interaction means On-demand - you type @agent-name. Defined in means.github/copilot-instructions.md means.github/agents/[name].agent.md.

      -
      -

      Jamie: Let's pause on Using Both Together. What should a learner take away from it?

      -

      Alex: Keep the learner anchored in Using Both Together. Custom instructions ensure Copilot follows your accessibility standards on every suggestion. This is the part to say slowly: Custom agents handle specific workflows like auditing, issue tracking, or automated remediation.

      -

      Jamie: Let's pause on Example workflow. What should a learner take away from it?

      -

      Alex: Start with Example workflow. There is something to understand, something to try, and something that proves the try worked.

      -

      Alex: First, your.github/copilot-instructions.md says: "Always check heading hierarchy in Markdown". Then, you invoke @insiders-a11y-tracker to scan recent changes. After that, the agent finds a heading skip (H1 → H3). Finally, you ask Copilot Chat to fix it: "Fix the heading hierarchy in this file". The rhythm is simple: orient, act, verify, then continue.

      -

      Jamie: Before we leave Example workflow, what is the practical point?

      -

      Alex: First, Copilot's fix follows your custom instructions (uses semantic HTML, adds ARIA where needed). Think of it as a rail line: each stop confirms you are still on the right route before the next one.

      -

      Jamie: Let's pause on Writing Accessibility-Focused Custom Instructions. What should a learner take away from it?

      -

      Alex: Start with Writing Accessibility-Focused Custom Instructions: Source: accessibility.github.com/documentation/guide/copilot-instructions/. The next useful detail is this: Custom instructions can be set at three levels.

      -
      -

      Jamie: Let's pause on Do's - What Makes Instructions Effective. What should a learner take away from it?

      -

      Alex: Here is the plain-English version of Do's - What Makes Instructions Effective. Use normative language: MUST, MUST NOT, SHOULD, SHOULD NOT. Put another way, most language models respond well to normative language. It is like learning a transit route. The names of the stops matter because they tell you whether you are still going the right direction.

      -

      Alex: Treat examples as spoken recipes, not decorations. You may hear something like 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. Read the command, understand what it changes, then run it only when the repository state matches the lesson.

      -

      Jamie: Let's pause on Focus on team-specific standards, not generic principles. What should a learner take away from it?

      -

      Alex: This is where Focus on team-specific standards, not generic principles becomes real: tell it what your team does specifically.

      -

      Alex: Keep the teaching thread moving. Keep the learner anchored in Use lists and checklists to structure instructions. Lists provide clear guardrails - Copilot follows them step by step.

      -
      -

      Jamie: Let's pause on Reference and enforce your design system. What should a learner take away from it?

      -

      Alex: The reason Reference and enforce your design system matters is that document which components to use and which are deprecated. That gives the learner a simple foothold: design systems evolve - keep instructions current.

      -

      Alex: Keep the teaching thread moving. Start with Don'ts - Common Instruction Mistakes: Copilot is already trained on WCAG. The next useful detail is this: Pasting the full text wastes context space and dilutes your specific instructions. Think of it like entering a new building: first you find the lobby, then the room, then the door you actually need.

      -

      Jamie: Let's pause on Additional Guidance. What should a learner take away from it?

      -

      Alex: Here is the plain-English version of Additional Guidance. Role-based prompting - You can give Copilot a persona to shape how it responds. Put another way, be specific about skills and responsibilities; avoid broad personas that may introduce unintended assumptions.

      -
      -

      Alex: Keep the teaching thread moving. This is where Accessibility Resources for Custom Instructions becomes real: these resources can help you write better accessibility-focused custom instructions and evaluate Copilot's output.

      -

      Alex: The practical takeaway is this. A11y LLM Evaluation Report - GitHub's own evaluation of how well LLMs handle accessibility tasks, with practical benchmarks: Accessibility LLM Evaluation. 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. Markdown Accessibility Review Guidelines - A practical guide for reviewing Markdown output for accessibility, useful as a reference when writing documentation-focused instructions: Markdown Accessibility.

      -

      Jamie: Let's pause on 11. Using Accessible View with Copilot Responses. What should a learner take away from it?

      -

      Alex: Keep the learner anchored in 11. Using Accessible View with Copilot Responses. Copilot Chat responses stream in token by token. This is the part to say slowly: This is visually nice but can fragment screen reader announcements.

      -

      Alex: Keep the teaching thread moving. Start with Without Accessible View. There is something to understand, something to try, and something that proves the try worked.

      -

      Alex: The practical takeaway is this. 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.

      +

      Jamie: What does someone need before they touch the keyboard?

      +

      Alex: Keep the learner anchored in Starting a review. On the Files Changed tab, when you add inline comments, choose "Start a review" instead of "Add single comment." This batches all your comments into one review submission.

      +

      Jamie: Let's pause on Completing and submitting a review. What should a learner take away from it?

      +

      Alex: The reason Completing and submitting a review matters is that after adding your inline comments via "Start a review," you must submit the review to notify the PR author. That gives the learner a simple foothold: the review is pending until you submit it. The interface gets friendlier when it stops being a wall of controls and starts being a set of named places.

      +

      Alex: The practical takeaway is this. The button may scroll off-screen to the right. Use horizontal scrolling or press Tab from the page top to cycle through focusable elements until you reach it. When clicked, a popover appears with a summary text area and three radio buttons ( Comment, Approve, Request changes ). At 200%+ zoom, the popover may extend below the visible viewport. Scroll down within the popover to see the Submit review button. The radio buttons are standard HTML radio buttons. In Windows High Contrast mode, the selected radio button uses the system highlight color. Keyboard shortcut: If the button is hard to find visually, press Ctrl+Shift+Enter from within any review comment text area to open the submit review dialog directly.

      +

      Alex: First, look for the Finish your review button in the top-right area of the Files Changed tab (it shows the number of pending comments). Then, click it - a popover appears with a summary text area and three radio buttons: Comment, Approve, Request changes. After that, optionally type a summary comment. Finally, select your verdict by clicking the radio button. The rhythm is simple: orient, act, verify, then continue.

      +

      Jamie: Before we leave Completing and submitting a review, what is the practical point?

      +

      Alex: First, click Submit review. Then, press 1 to go to the h1 (PR title). After that, press B (or Tab) to navigate to the "Submit review" button and activate it (Enter/Space). Finally, a "Submit review" dialog/panel appears. Think of it as a rail line: each stop confirms you are still on the right route before the next one.

      +

      Alex: Treat examples as spoken recipes, not decorations. You may hear something like View the PR diff in your terminal; gh pr diff 42; Approve a PR; gh pr review 42 --approve; Approve with a comment; gh pr review 42 --approve --body "Looks good - heading hierarchy is correct."; Request changes; gh pr review 42 --request-changes --body "The alt. Read the command, understand what it changes, then run it only when the repository state matches the lesson.

      +

      Jamie: Let's pause on GitHub shortcuts for pull requests. What should a learner take away from it?

      +

      Alex: Start with GitHub shortcuts for pull requests: These are the GitHub built-in shortcuts for PR pages. The next useful detail is this: Enable Focus Mode first (NVDA: NVDA+Space, JAWS: Insert+Z) before using single-key shortcuts.

      -

      Jamie: Let's pause on With Accessible View (Alt+F2 / Mac: Option+F2). What should a learner take away from it?

      -

      Alex: Start with With Accessible View (Alt+F2 / Mac: Option+F2). There is something to understand, something to try, and something that proves the try worked.

      -

      Alex: The practical takeaway is this. 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.

      -

      Jamie: Let's pause on Every time you ask Copilot something. What should a learner take away from it?

      -

      Alex: Here is the plain-English version of Every time you ask Copilot something. VS Code December 2025 update: The Accessible View now updates dynamically as responses stream in. Put another way, 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.

      -

      Alex: First, type your prompt in Chat input. Then, press Ctrl+Enter (Mac: Cmd+Enter) to send. After that, press Alt+F2 (Mac: Option+F2) to open Accessible View - you can open it immediately after sending, before the response finishes. Finally, follow along as the response streams in the Accessible View in real-time. Treat it like a recipe: do not add the next ingredient until the previous one is actually in the bowl.

      -

      Jamie: Before we leave Every time you ask Copilot something, what is the practical point?

      -

      Alex: First, read or re-read any section with Arrow keys. Then, press Escape to close Accessible View and return to Chat. It is a checklist, but a meaningful one: every item creates evidence that the next step is safe.

      -

      Jamie: Let's pause on Benefits. What should a learner take away from it?

      -

      Alex: Start with Benefits. There is something to understand, something to try, and something that proves the try worked.

      -

      Alex: The practical takeaway is this. Follow responses live without waiting. Navigate and re-read at your own pace. Code blocks and lists are properly structured. Headings are announced correctly.

      +

      Alex: This is where the talk moves from concept to action. Here is the plain-English version of On the PR list page. Shortcut note: For G P, press G, release it, then press P (two sequential key presses, not simultaneous).

      +

      Jamie: Let's pause on On the Files Changed tab. What should a learner take away from it?

      +

      Alex: This is where On the Files Changed tab becomes real: for the full shortcut system, see Screen Reader Cheat Sheet - GitHub Shortcuts section.

      +

      Alex: This is the part worth saying out loud. Start with Learning Cards: Submitting a Review. There is something to understand, something to try, and something that proves the try worked.

      +

      Alex: The practical takeaway is this. The review verdict controls are inside a popover triggered by the "Finish your review" button; press 1 to return to the h1 (PR title), then B or Tab forward to find the button -- it is easy to miss because it is not a landmark. Inside the popover, Tab past the summary text area to reach a radio group labeled "Review Event"; use Up/Down Arrow to switch between Comment, Approve, and Request Changes. Shortcut: press Ctrl+Shift+Enter from any review comment text area to open the submit review dialog directly, bypassing the search for the button. The "Finish your review" button sits in the top-right corner of the Files Changed tab with a small badge showing your pending comment count; at 200%+ zoom it may scroll off-screen to the right. Inside the submit popover, the three radio buttons (Comment, Approve, Request changes) are small standard HTML radios; zoom in on the popover area or use Tab to step between them. After submitting, your review verdict appears as a colored banner in the Conversation timeline: green for Approve, red for Request Changes, grey for Comment.

      -

      Jamie: Let's pause on When a suggestion appears. What should a learner take away from it?

      -

      Alex: Keep the learner anchored in When a suggestion appears. 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 part to say slowly: This is the recommended workflow for screen reader users. A good GitHub workflow is like a well-run meeting: everyone knows the topic, the next action, and who has the floor.

      -

      Alex: First, don't accept it immediately. Then, press Alt+F2 (Mac: Option+F2). After that, accessible View shows: "Suggestion: [full text of the suggestion]". Finally, read it completely. It is like walking a hallway with named doors: read the sign, enter the right room, then confirm where you landed.

      -

      Jamie: Before we leave When a suggestion appears, what is the practical point?

      -

      Alex: First, to insert the suggestion at your cursor: press Ctrl+/ (Mac: Cmd+/). Then, to close without inserting: press Escape, then Tab to accept or Escape to reject. The rhythm is simple: orient, act, verify, then continue.

      -

      Jamie: Let's pause on Code Blocks in Accessible View. What should a learner take away from it?

      -

      Alex: The reason Code Blocks in Accessible View matters is that when Copilot suggests code or Markdown.

      -

      Alex: Keep the teaching thread moving. Start with In Accessible View: NVDA/JAWS: Use Arrow keys to read line by line. The next useful detail is this: Use Ctrl+Home to jump to the start.

      -

      Alex: The practical takeaway is this. 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.

      +

      Jamie: Let's pause on Suggested Changes. What should a learner take away from it?

      +

      Alex: The reason Suggested Changes matters is that a suggested change is a special form of inline review comment where the reviewer proposes exact replacement text. That gives the learner a simple foothold: the PR author can apply the suggestion directly from GitHub - no copy-paste or separate commit needed.

      +

      Jamie: Let's pause on As a reviewer - inserting a suggestion. What should a learner take away from it?

      +

      Alex: Start with As a reviewer - inserting a suggestion: The suggestion block is plain Markdown text in the comment editor. The next useful detail is this: (Three backticks, the word suggestion, Enter, your text, Enter, three backticks.).

      +

      Alex: First, on the Files Changed tab, navigate to the line you want to propose a change. Then, activate the line comment button for that line (the + that appears on hover, or Tab to navigate to it). After that, in the comment text area that opens, press Ctrl+G (Windows) or Cmd+G (Mac). Finally, GitHub wraps a suggestion block around the current line content. Think of it as a rail line: each stop confirms you are still on the right route before the next one.

      +

      Jamie: Before we leave As a reviewer - inserting a suggestion, what is the practical point?

      +

      Alex: First, edit the text inside the suggestion block to show your proposed change. Then, add context above the block if helpful: "This makes the alt text more descriptive:". After that, submit as part of your review ("Start a review" → batch with other comments). Treat it like a recipe: do not add the next ingredient until the previous one is actually in the bowl.

      +

      Jamie: Let's pause on As an author - applying a suggestion. What should a learner take away from it?

      +

      Alex: Start with As an author - applying a suggestion. There is something to understand, something to try, and something that proves the try worked.

      +

      Alex: First, open the PR Conversation or Files Changed tab. Then, navigate to the inline comment containing a suggestion (it shows a diff-style preview). After that, find and activate the "Apply suggestion" button below the suggestion block. Finally, GitHub creates a commit automatically that applies the change - no file editing required. Treat it like a recipe: do not add the next ingredient until the previous one is actually in the bowl.

      +

      Jamie: Before we leave As an author - applying a suggestion, what is the practical point?

      +

      Alex: First, the conversation thread is marked as resolved. It is a checklist, but a meaningful one: every item creates evidence that the next step is safe.

      -

      Jamie: Let's pause on Learning Cards: Using Accessible View with Copilot Responses. What should a learner take away from it?

      -

      Alex: Start with Learning Cards: Using Accessible View with Copilot Responses. There is something to understand, something to try, and something that proves the try worked.

      -

      Alex: The practical takeaway is this. 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. 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.

      -

      Alex: Keep the teaching thread moving. This is where GitHub.com Shortcuts (Not VS Code) becomes real: these shortcuts work on GitHub.com in your browser, not inside VS Code. That matters in practice: Students sometimes confuse them with Copilot shortcuts because they involve similar key combinations. The workshop is closer to rehearsal than lecture. You hear the move, try the move, and then check what changed.

      -

      Jamie: Let's pause on Video Tutorials (Screen Reader Demonstrations). What should a learner take away from it?

      -

      Alex: Keep the learner anchored in Video Tutorials (Screen Reader Demonstrations). GitHub's accessibility team has published screen reader walkthroughs for each major Copilot feature. This is the part to say slowly: These are sourced from the official GitHub Accessibility guide for Copilot in VS Code.

      -

      Alex: The practical takeaway is this. Inline suggestions with a screen reader - accepting, rejecting, and reviewing ghost text suggestions with NVDA. Inline chat with a screen reader - using Ctrl+I to edit code in place with screen reader feedback. Chat view with a screen reader - navigating the Chat panel, reading responses, and using Accessible View. Built-in actions with a screen reader - running Copilot commands from the Command Palette.

      +

      Jamie: Let's pause on Batching multiple suggestions into one commit. What should a learner take away from it?

      +

      Alex: Start with Batching multiple suggestions into one commit. There is something to understand, something to try, and something that proves the try worked.

      +

      Alex: First, for each suggestion you want to apply, activate "Add suggestion to batch" instead of "Apply suggestion". Then, after selecting all suggestions, activate the "Commit suggestions" button that appears at the top. After that, GitHub applies all batched suggestions in a single commit. It is a checklist, but a meaningful one: every item creates evidence that the next step is safe.

      +

      Jamie: Let's pause on When to use suggestions vs. comments. What should a learner take away from it?

      +

      Alex: Start with When to use suggestions vs. comments. There is something to understand, something to try, and something that proves the try worked.

      +

      Alex: The practical takeaway is this. Use a suggestion when you know the exact text that would fix the issue. Use a plain comment when the change requires judgment from the author (e.g., "this alt text isn't descriptive - can you describe what the image shows?"). A summary text area for overall comments. Radio buttons for Comment / Approve / Request changes.

      +

      Alex: First, after adding all your inline comments, navigate to the review summary button. Then, on Files Changed tab: find the "Review changes" button (B to navigate buttons). After that, press Enter to open the review dialog. Finally, a panel opens. It is like walking a hallway with named doors: read the sign, enter the right room, then confirm where you landed.

      +

      Jamie: Before we leave When to use suggestions vs. comments, what is the practical point?

      +

      Alex: First, switch to Focus Mode → type your summary comment. Then, navigate to the radio buttons with arrow keys → select your verdict. After that, tab to "Submit review" button → Enter. The rhythm is simple: orient, act, verify, then continue.

      +

      Alex: Keep the teaching thread moving. Start with Learning Cards: Suggested Changes. There is something to understand, something to try, and something that proves the try worked.

      +

      Alex: The practical takeaway is this. To insert a suggestion block, press Ctrl+G (Windows) or Cmd+G (Mac) in the comment text area; the screen reader announces the inserted fence -- arrow down to edit the text between the backtick lines. Alternatively type the block manually: three backticks, the word suggestion, Enter, your replacement text, Enter, three backticks -- this avoids relying on the keyboard shortcut. As a PR author, navigate to a suggestion comment with 3, then Tab to the "Apply suggestion" button; GitHub commits the change automatically with no file editing required. Suggestion blocks render as a mini inline diff: the original line in red/pink background and your proposed replacement in green background; in high-contrast mode these use system diff colors. The "Apply suggestion" button is small and sits below the suggestion diff preview; zoom into the comment area to find it, or Tab from the suggestion text to reach it. When batching multiple suggestions, a floating "Commit suggestions" bar appears at the top of the page; at high zoom scroll up or press Home to find it.

      -

      Alex: Keep the teaching thread moving. The reason 13. Critically Evaluating AI Output matters is that Copilot is fast, fluent, and frequently wrong. That gives the learner a simple foothold: 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.

      -

      Jamie: Let's pause on When to Trust Copilot. What should a learner take away from it?

      -

      Alex: Start with When to Trust Copilot: Copilot is at its best when it is generating code that thousands of developers have written before. The next useful detail is this: You can generally trust suggestions that fall into these categories.

      -

      Alex: The practical takeaway is this. 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.

      -

      Alex: Keep the teaching thread moving. Here is the plain-English version of When to Verify. Some suggestions look correct at first glance but carry hidden risks. Put another way, always read these carefully before accepting. It is like learning a transit route. The names of the stops matter because they tell you whether you are still going the right direction.

      -

      Alex: The practical takeaway is this. 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.

      +

      Jamie: How do you keep commands from becoming magic words?

      +

      Alex: Start with Understanding Merge Options (for Maintainers): When a PR is approved and checks pass, a maintainer can merge it. The next useful detail is this: The merge button section appears at the bottom of the Conversation tab.

      +

      Alex: Treat examples as spoken recipes, not decorations. You may hear something like Merge with default strategy (merge commit); gh pr merge 42; Squash and merge; gh pr merge 42 --squash; Rebase and merge; gh pr merge 42 --rebase; Delete the branch after merging; gh pr merge 42 --squash --delete-branch; Enable auto-merge (merges when checks. Read the command, understand what it changes, then run it only when the repository state matches the lesson.

      +

      Alex: Keep the teaching thread moving. Here is the plain-English version of After a PR is merged. for screen reader users, - deleting the branch after merge: Navigate to the "Add a comment" section (D), then press Shift+B to navigate backwards to the "Delete branch" button and activate it. Put another way, this keeps your repository clean by removing the now-merged feature branch. It is like learning a transit route. The names of the stops matter because they tell you whether you are still going the right direction.

      +

      Alex: The practical takeaway is this. The PR status badge changes to "Merged" (purple). The source branch can be deleted - a "Delete branch" button appears. Any linked issues with Closes N in the description are automatically closed.

      +

      Jamie: Let's pause on Auto-Merge - Merging When You Can't Wait Around. What should a learner take away from it?

      +

      Alex: This is where Auto-Merge - Merging When You Can't Wait Around becomes real: auto-merge lets you pre-authorize a PR to merge automatically the moment all branch protection requirements are satisfied - required reviews approved, all status checks passing, and the branch up to date.

      +

      Alex: The practical takeaway is this. You've addressed all review comments and are waiting for CI to finish. A maintainer has approved the PR but a required check is still running. You're in a different time zone from the reviewers.

      -

      Jamie: Let's pause on When to Reject. What should a learner take away from it?

      -

      Alex: This is where When to Reject becomes real: delete the suggestion and write the code yourself when you see any of these. That matters in practice: If you are not sure whether a suggestion falls into this category, verify it.

      -

      Alex: The practical takeaway is this. 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.

      -

      Alex: Keep the teaching thread moving. Keep the learner anchored in Common Failure Modes. The table below shows the kinds of mistakes Copilot makes most often. This is the part to say slowly: Recognizing these patterns helps you catch problems before they reach a reviewer.

      -

      Jamie: Let's pause on The Verification Checklist. What should a learner take away from it?

      -

      Alex: The reason The Verification Checklist matters is that before you accept any non-trivial Copilot suggestion, run through these steps. That gives the learner a simple foothold: keep the Problems panel open (Ctrl+Shift+M) while you work with Copilot.

      -

      Alex: First, does it compile or run? -- Accept the suggestion, save the file, and check for errors in the Problems panel (Ctrl+Shift+M). Then, does it do what I asked? -- Read the code and confirm it matches your intent, not just your prompt. After that, 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. Finally, does it match the project's conventions? -- Check naming, formatting, file organization, and error handling against the existing codebase. The rhythm is simple: orient, act, verify, then continue.

      -

      Jamie: Before we leave The Verification Checklist, what is the practical point?

      -

      Alex: First, did I check any URLs or references it generated? -- Open every link, verify every package name, confirm every API endpoint. Then, would this pass an accessibility review? -- Run it through the checks described below. Think of it as a rail line: each stop confirms you are still on the right route before the next one.

      +

      Alex: Keep the teaching thread moving. Start with What happens next. There is something to understand, something to try, and something that proves the try worked.

      +

      Alex: The practical takeaway is this. The PR merge box changes to show "Auto-merge enabled - merge will happen automatically". When the last required check passes (or last required review arrives), GitHub merges the PR silently. You receive a notification: "Your PR was automatically merged". If a reviewer requests changes after auto-merge is enabled, auto-merge is automatically cancelled (a new approval is required before it re-enables).

      +

      Jamie: Let's pause on Cancelling Auto-Merge. What should a learner take away from it?

      +

      Alex: The reason Cancelling Auto-Merge matters is that auto-merge is only available if the repository administrator has enabled it in Settings → General. That gives the learner a simple foothold: many open source repos have it on; some do not.

      +

      Alex: Treat examples as spoken recipes, not decorations. You may hear something like Merge box → Tab → "Disable auto-merge" button → Enter. Read the command, understand what it changes, then run it only when the repository state matches the lesson.

      +

      Alex: Keep the teaching thread moving. Start with Scenario A: "I want to review an assigned PR": Example: You are assigned to review a PR titled "Add missing NVDA shortcut to keyboard-shortcuts.md." The PR modifies docs/keyboard-shortcuts.md in the Learning Room repository and references Challenge 2. Think of it like entering a new building: first you find the lobby, then the room, then the door you actually need.

      -

      Alex: Keep the teaching thread moving. Start with Accessibility-Specific Concerns: Copilot generates HTML and UI code based on what it has seen -- and much of the web is inaccessible. The next useful detail is this: Watch for these problems in any suggestion that touches the user interface. Think of it like entering a new building: first you find the lobby, then the room, then the door you actually need.

      -

      Alex: The practical takeaway is this. 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.

      -

      Jamie: Let's pause on The Right Mental Model. What should a learner take away from it?

      -

      Alex: Here is the plain-English version of The Right Mental Model. Think of Copilot as a fast typist who has read a lot of code. Put another way, it can reproduce patterns it has seen before, and it can combine those patterns in new ways.

      -

      Alex: The practical takeaway is this. 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.

      -

      Alex: Keep the teaching thread moving. Start with Learning Cards: Critically Evaluating AI Output. There is something to understand, something to try, and something that proves the try worked.

      -

      Alex: The practical takeaway is this. 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. 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.

      +

      Jamie: Let's pause on Scenario B: "I want to respond to review feedback on my PR". What should a learner take away from it?

      +

      Alex: Here is the plain-English version of Scenario B: "I want to respond to review feedback on my PR". Example: Your PR for Challenge 3 (Complete Welcome Guide) received a review comment: "The [TODO] about evaluating issues is good, but the paragraph could mention checking if the issue is already assigned." The validation bot also flagged a link text issue.

      +

      Alex: Keep the teaching thread moving. This is where Writing PR Descriptions That Get Reviewed becomes real: see also: Appendix C: Markdown Reference for formatting your PR description with headings, lists, and task lists. That matters in practice: A pull request is only as useful as its description.

      +

      Jamie: Let's pause on What Reviewers Look For. What should a learner take away from it?

      +

      Alex: Keep the learner anchored in What Reviewers Look For. When a reviewer opens your PR, they are asking four questions before they ever look at the diff. This is the part to say slowly: If your description answers all four, the reviewer can jump straight into the code with context.

      +

      Alex: First, why does this change exist? -- What problem does it solve, or what goal does it advance? Then, what is the scope? -- Which files changed, and roughly how big is the change? After that, how was it tested? -- Did you verify that the change works, and how? Finally, what should I pay attention to? -- Are there tricky parts, trade-offs, or areas where you want a second opinion? It is like walking a hallway with named doors: read the sign, enter the right room, then confirm where you landed.

      -

      Jamie: Let's pause on Copilot Not Suggesting Anything. What should a learner take away from it?

      -

      Alex: Keep the learner anchored in Copilot Not Suggesting Anything. Issue: No suggestions appear as you type.

      -

      Jamie: Let's pause on Solutions. What should a learner take away from it?

      -

      Alex: Start with Solutions. There is something to understand, something to try, and something that proves the try worked.

      -

      Alex: First, check Copilot is active: status bar icon should not be grayed out. Then, click the Copilot icon → verify "Completions enabled". After that, check subscription status: Ctrl+Shift+P → "Copilot: Check Status". Finally, restart VS Code. The rhythm is simple: orient, act, verify, then continue.

      -

      Jamie: Before we leave Solutions, what is the practical point?

      -

      Alex: First, sign out and sign back in: Ctrl+Shift+P → "Copilot: Sign Out". Think of it as a rail line: each stop confirms you are still on the right route before the next one.

      -

      Jamie: Let's pause on Suggestions Are Too Frequent/Distracting. What should a learner take away from it?

      -

      Alex: Start with Suggestions Are Too Frequent/Distracting: Issue: Constant interruptions from suggestions.

      +

      Alex: Keep the teaching thread moving. The reason The Closes XX Pattern matters is that GitHub recognizes special keywords in PR descriptions that automatically close linked issues when the PR merges. That gives the learner a simple foothold: you do not need to close issues by hand -- just include the right keyword followed by the issue number. The interface gets friendlier when it stops being a wall of controls and starts being a set of named places.

      +

      Jamie: What is the pre-flight check here?

      +

      Alex: Start with Before/After Structure: One of the most effective patterns for PR descriptions is showing the state before your change and the state after. The next useful detail is this: This gives the reviewer an instant mental model of what changed without reading the diff line by line.

      +

      Alex: Keep the teaching thread moving. Here is the plain-English version of A PR Description Template. Here is a template you can copy into your PR descriptions. Put another way, not every section applies to every PR, but filling in even a few sentences per section makes a meaningful difference.

      -

      Jamie: What is the teaching move inside Solutions?

      -

      Alex: First, use word-by-word acceptance: Ctrl+Right Arrow. Then, reduce screen reader verbosity (see Section 3). After that, use Accessible View (Alt+F2) to review suggestions without live announcements. Finally, disable inline suggestions temporarily: Copilot icon → "Disable Completions". Treat it like a recipe: do not add the next ingredient until the previous one is actually in the bowl.

      -

      Jamie: Let's pause on Chat Responses Not Announced. What should a learner take away from it?

      -

      Alex: This is where Chat Responses Not Announced becomes real: issue: Screen reader silent when Copilot responds.

      -

      Jamie: If someone only remembers one thing from Solutions, what should it be?

      -

      Alex: First, wait for response to complete, then press Alt+F2 for Accessible View. Then, check ARIA live region settings in your screen reader. After that, navigate manually to the response area with Tab or Arrow keys. Finally, use Quick Chat (Ctrl+Shift+Alt+I) instead of panel chat. It is like walking a hallway with named doors: read the sign, enter the right room, then confirm where you landed.

      +

      Jamie: Let's pause on Common Description Mistakes. What should a learner take away from it?

      +

      Alex: This is where Common Description Mistakes becomes real: even experienced contributors make these mistakes. That matters in practice: Knowing what to avoid is half the battle.

      +

      Alex: Keep the teaching thread moving. Keep the learner anchored in Good vs. Bad: Side by Side. No context, no linked issue, no explanation of what file or what was wrong with it. This is the part to say slowly: A reviewer seeing this has to open the diff, figure out which file changed, read every line, and guess at the intent. A good GitHub workflow is like a well-run meeting: everyone knows the topic, the next action, and who has the floor.

      +

      Jamie: Let's pause on Learning Cards: Writing PR Descriptions That Get Reviewed. What should a learner take away from it?

      +

      Alex: Start with Learning Cards: Writing PR Descriptions That Get Reviewed. There is something to understand, something to try, and something that proves the try worked.

      +

      Alex: The practical takeaway is this. Use Markdown headings ( ) in your description (Summary, Changes, Related Issues, Testing) so reviewers can press H to jump between sections. Type Closes followed by the issue number to auto-close the linked issue on merge; GitHub autocompletes when you type. Press Ctrl+Shift+P in the description text area to toggle between Write and Preview modes; Preview renders your Markdown so you can check structure before submitting. Use the Preview tab to verify your Markdown renders correctly; headings, bullet lists, and code blocks are easier to proofread in rendered form. Keep bullet points short (one line each) so the description is scannable at high zoom without excessive horizontal scrolling. When including screenshots, add alt text in the Markdown image syntax: so every reader gets the same information.

      -

      Jamie: Let's pause on "Copilot Subscription Required". What should a learner take away from it?

      -

      Alex: The reason "Copilot Subscription Required" matters is that issue: Extension installed but asks for subscription.

      -

      Jamie: Let's pause on Solutions. What should a learner take away from it?

      -

      Alex: First, sign in to GitHub: Copilot icon → "Sign in". Then, verify GitHub account has Copilot access (free tier or paid). After that, check github.com/settings/copilot for subscription status. Finally, free tier users: ensure you haven't exceeded monthly limits. Think of it as a rail line: each stop confirms you are still on the right route before the next one.

      -

      Jamie: Let's pause on Try It: Your First Copilot Conversation. What should a learner take away from it?

      -

      Alex: Here is the plain-English version of Try It: Your First Copilot Conversation. Time: 3 minutes What you need: VS Code with Copilot Chat extension installed. Put another way, you just had a conversation with an AI about your codebase.

      -

      Alex: First, open Copilot Chat - Press Ctrl+Shift+I (Mac: Cmd+Shift+I). Your screen reader announces the chat panel. Then, ask a question - Type: What does the CONTRIBUTING.md file in this repository say about how to submit a pull request? Press Enter. After that, 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. Finally, try a follow-up - Type: Summarize that in 3 bullet points and press Enter. Copilot remembers the context from your first question. Treat it like a recipe: do not add the next ingredient until the previous one is actually in the bowl.

      +

      Jamie: Let's pause on Try It: Read a Real Pull Request. What should a learner take away from it?

      +

      Alex: Start with Try It: Read a Real Pull Request: Time: 3 minutes What you need: Browser, signed in to GitHub. The next useful detail is this: Go to the Learning Room repository's Pull Requests tab and find any open or recently closed PR.

      +

      Alex: First, navigate to Pull Requests (G then P in Focus Mode). Then, open the first PR in the list (press Enter on its title). After that, read the description - press 2 to jump to the first section heading, then arrow down to read. Look for: which file was changed (docs/welcome.md, docs/keyboard-shortcuts.md, or docs/setup-guide.md)? Which challenge was this PR solving? Does the description. Finally, check the conversation - press 3 to jump between comments. Read what the validation bot reported - did the bot find any accessibility issues like broken headings or non-descriptive links? How did the author respond? Think of it as a rail line: each stop confirms you are still on the right route before the next one.

      +

      Jamie: Before we leave Try It: Read a Real Pull Request, what is the practical point?

      +

      Alex: First, look at the diff - press D to the "Pull request tabs" landmark, then navigate to "Files changed" and press Enter. Press H to scan the changed file headings. If the PR touched docs/welcome.md, you should see + lines where the [TODO] sections were filled in. If. Treat it like a recipe: do not add the next ingredient until the previous one is actually in the bowl.

      Jamie: What should people carry with them after this?

      Alex: Carry the map. Know what page or tool you are in, know which action you are taking, and know what confirmation should follow. If the confirmation is missing, pause. That pause is not wasted time; it is professional judgment.

      Jamie: That is a better way to say it than just follow the steps.

      -

      Alex: Right. Steps matter, but understanding wins. That is episode 14. Next in the series is episode 15, where we keep building the same contributor muscles.

      +

      Alex: Right. Steps matter, but understanding wins. That is episode 6. Next in the series is episode 7, where we keep building the same contributor muscles.

      -

      Episode 15: Accessible Code Review

      -

      Navigating diffs with a screen reader, reviewing PRs in browser and VS Code.

      -

      Based on: Chapter 15: Accessible Code Review

      +

      17. Challenge 04: Branch Out

      +

      Creating a safe working branch and understanding why branches protect main.

      +

      Practice focus: Day 1 contribution

      Audio and transcript are being regenerated for this episode.

      -Read Transcript - Episode 15: Accessible Code Review +Read Transcript - Challenge 04: Branch Out

      Transcript

      -

      Alex: Welcome to episode 15 of Git Going with GitHub: Accessible Code Review. I am Alex, and today we are teaching this topic as a conversation you can carry into the workshop, not as a page you have to memorize.

      -

      Jamie: And I am Jamie. I will keep pulling the lesson back to real learners, real repositories, and the evidence that proves the work happened.

      +

      Alex: Welcome to Challenge Coach: Branch Out. I am Alex. Before you do the task, we are going to make the skill feel concrete enough to practice.

      +

      Jamie: And I am Jamie. I will keep asking what the learner should do, what evidence counts, and how to recover if the page does something unexpected.

      -

      Alex: The lesson focus is Navigating diffs with a screen reader, reviewing PRs in browser and VS Code. We will treat every step as a teachable decision, because that is what makes the skill portable.

      -

      Jamie: So we should explain the why clearly enough that the steps make sense when the learner meets them later.

      -

      Alex: That is it. If a listener only has audio right now, they should still get the complete concept and know what evidence would prove success.

      +

      Alex: The skill focus is Creating a safe working branch and understanding why branches protect main. This is rehearsal for real contribution, so the evidence matters because it proves the move happened.

      +

      Jamie: So the challenge has to leave the learner with both confidence and a trail of evidence.

      +

      Alex: Exactly. Evidence is not busywork. It is how a learner, a facilitator, and a future maintainer can understand what changed and why.

      -

      Jamie: Okay, set the room for us. What are we walking into?

      -

      Alex: Start with The GitHub Pull Requests Extension: See also: Appendix G: VS Code Reference for the complete list of GitHub Pull Requests extension keyboard shortcuts.

      -

      Alex: A solid pull request habit is to separate three questions: what changed, why it changed, and what still needs review. That keeps the conversation useful instead of noisy.

      -

      Alex: The next layer is this. Here is the plain-English version of 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,. Put another way, prerequisites: Working with Pull Requests, Git & Source Control in VS Code Mac keyboard shortcuts: Throughout this chapter, all Ctrl+ shortcuts use Cmd+ on Mac, and Alt+ shortcuts use Option+ on Mac. It is like learning a transit route. The names of the stops matter because they tell you whether you are still going the right direction.

      -

      Jamie: What should feel predictable before the first live session starts?

      -

      Alex: This is where Workshop Recommendation (Chapter 15, Part 1) becomes real: chapter 15, Part 1 introduces the GitHub Pull Requests extension for managing PRs directly from VS Code.

      -

      Alex: That shows up in the workshop in a few specific ways. There are 2 guided challenges. Automation check: none (extension installation and review state are account-local). The evidence is issue comment with confirmation of actions completed. The pattern is install, check out, review, comment.

      +

      Jamie: What makes this practice feel low-stakes but still real?

      +

      Alex: Start with Challenge 4: Branch Out: What you will do: Create a personal branch named learn/YOUR-USERNAME where you will make your Day 1 changes.

      +

      Alex: A solid Git habit is to know which branch you are on, what changed, and what confirmation you expect before you run the next command.

      +

      Jamie: How would you walk the room through that step by step?

      +

      Alex: Start with Instructions. There is something to understand, something to try, and something that proves the try worked.

      +

      Alex: First, make sure you are on the Code tab of the learning-room repository. Then, find the branch dropdown (it shows "main" by default). After that, type learn/YOUR-USERNAME (replace YOUR-USERNAME with your actual GitHub username). Finally, select Create branch: learn/YOUR-USERNAME from main. Treat it like a recipe: do not add the next ingredient until the previous one is actually in the bowl.

      +

      Jamie: What is the one idea that makes the next few steps less mysterious?

      +

      Alex: This is where Branch naming convention becomes real: your branch name must follow this pattern: learn/ followed by your GitHub username. That matters in practice: This naming convention helps facilitators and automation identify your work.

      +

      Alex: That shows up in the workshop in a few specific ways. learn/octocat. learn/mona-lisa. learn/student42.

      -

      Jamie: Turn that into a path someone can follow.

      -

      Alex: Start with Chapter 15, Part 1 Practice Set. There is something to understand, something to try, and something that proves the try worked.

      -

      Alex: First, install the GitHub Pull Requests extension - add the extension to VS Code and sign in with your GitHub account. Then, check out a PR and post a review comment - download a PR branch locally, read the diff, and post one constructive review comment. It is like walking a hallway with named doors: read the sign, enter the right room, then confirm where you landed.

      +

      Alex: Now bring the learner back to the room. Keep the learner anchored in Peer simulation check. Open the peer-simulation PR and notice its branch name. This is the part to say slowly: If you have a real buddy, ask whether they created their branch and help them find the branch dropdown if they are stuck.

      Jamie: What is the ordered workflow?

      -

      Alex: The reason Practice 15.1 Step-by-Step: Install the Extension matters is that install the GitHub Pull Requests and Issues extension and authenticate with your GitHub account. That gives the learner a simple foothold: VS Code desktop with your Learning Room repository open.

      -

      Alex: First, open the Extensions sidebar: Ctrl+Shift+X (Mac: Cmd+Shift+X). Then, your screen reader announces "Extensions: Marketplace." The search box has focus. After that, type GitHub Pull Requests in the search box and press Enter. Finally, navigate down the results list. Select GitHub Pull Requests (publisher: GitHub). The rhythm is simple: orient, act, verify, then continue.

      -

      Jamie: Give me the sequence, because order matters here.

      -

      Alex: First, activate the Install button. VS Code installs the extension and may show a notification. Then, after installation, VS Code prompts you to sign in. Activate Sign in to GitHub. After that, a browser window opens for GitHub OAuth. Approve the authorization and return to VS Code. Finally, verify: open the Explorer sidebar (Ctrl+Shift+E). You should now see a GitHub section in the sidebar showing Pull Requests and Issues. Think of it as a rail line: each stop confirms you are still on the right route before the next one.

      -

      Jamie: How would you walk the room through that step by step?

      -

      Alex: Start with Practice 15.2 Step-by-Step: Check Out a PR and Post a Comment: Check out someone else's PR branch locally, read the diff in VS Code, and post one constructive review comment. The next useful detail is this: VS Code with the GitHub Pull Requests extension installed. Think of it like entering a new building: first you find the lobby, then the room, then the door you actually need.

      -

      Alex: First, open the Command Palette: Ctrl+Shift+P (Mac: Cmd+Shift+P). Then, type GitHub Pull Requests: Focus on Pull Requests View and select it. The Pull Requests panel opens. After that, navigate the list of open PRs. Find one that is not yours (a classmate's PR from Chapter 6, 7, or 14). Finally, 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. Think of it as a rail line: each stop confirms you are still on the right route before the next one.

      -

      Jamie: What does the learner do first, second, and then after that?

      -

      Alex: First, open the Command Palette again and run GitHub Pull Requests: Open Changed Files. This shows the list of files the PR changed. Then, open one changed file. VS Code opens the Diff Editor showing old content on the left and new content on the right. After that, 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). Finally, find one specific thing to comment on: a typo, an unclear sentence, a missing step, or something the author did well. Treat it like a recipe: do not add the next ingredient until the previous one is actually in the bowl.

      -
      -

      Jamie: What should the learner prove to themselves after each small task?

      -

      Alex: Here is the plain-English version of Completing Chapter 15, Part 1: Submit Your Evidence. Open your assigned setup or review practice issue and post a completion comment. Put another way, close your Chapter 12 challenge issues when done.

      +

      Alex: The reason On github.com matters is that you can switch to it using the same dropdown.

      +

      Alex: First, go to the repository's Code tab. Then, click the branch dropdown (it says "main"). After that, type a new branch name like fix/welcome-todo. Finally, click "Create branch: fix/welcome-todo from main". The rhythm is simple: orient, act, verify, then continue.

      Alex: The useful habit is simple: orient first, act second, verify third. That pause before acting is part of the work.

      -

      Alex: This is where the talk moves from concept to action. Start with Expected Outcomes. There is something to understand, something to try, and something that proves the try worked.

      -

      Alex: The room should hear these as checkpoints. 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.

      -

      Jamie: Let's pause on If You Get Stuck. What should a learner take away from it?

      -

      Alex: Keep the learner anchored in If You Get Stuck. Continue learning: The GitHub Skills course Review Pull Requests practices approving, requesting changes, and using suggestions in an interactive format. This is the part to say slowly: See Appendix Z for the full catalog.

      -

      Alex: First, extension does not install? Reload VS Code: Ctrl+Shift+P, then run Developer: Reload Window. Then, oAuth sign-in fails? Verify your GitHub account is active in the browser first, close VS Code, reopen, and retry. After that, pR list is empty? Switch to "All Open" view in the GitHub Pull Requests panel. Finally, checkout fails? Confirm you have write access to the repository. If not, use the read-only GitHub.com fallback. It is like walking a hallway with named doors: read the sign, enter the right room, then confirm where you landed.

      -

      Jamie: Before we leave If You Get Stuck, what is the practical point?

      -

      Alex: First, diff Editor is hard to navigate? Press F7 for the Accessible Diff Viewer mode, which is purpose-built for screen readers. Then, cannot find the Add Comment command? Use Command Palette and search for GitHub Pull Requests: Add Comment. After that, ask facilitator to help verify the GitHub PR panel and model one review comment. Finally, finished but not sure you did it right? Compare your work against the Challenge 11 reference solution. The rhythm is simple: orient, act, verify, then continue.

      -
      -

      Alex: Before the learner moves on. The reason Learning Moment matters is that reviewing others' work refines your own standards and builds community trust. That gives the learner a simple foothold: the comment you just wrote helps another student learn - and you learn by articulating what makes documentation clear. The interface gets friendlier when it stops being a wall of controls and starts being a set of named places.

      -

      Jamie: Let's pause on Learning Pattern Used in This Chapter. What should a learner take away from it?

      -

      Alex: Start with Learning Pattern Used in This Chapter. There is something to understand, something to try, and something that proves the try worked.

      -

      Alex: First, install and configure the tool before starting the task. Then, practice on someone else's work first (reviewing is safer than authoring). After that, use accessibility tools (F7 Accessible Diff Viewer) to navigate efficiently. Finally, write specific, constructive feedback (not just "looks good"). Think of it as a rail line: each stop confirms you are still on the right route before the next one.

      -

      Alex: Hold that next to this. Here is the plain-English version of 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.

      +

      Jamie: How do you keep commands from becoming magic words?

      +

      Alex: Start with In VS Code (with Git): Or use the Source Control sidebar: click the branch name in the bottom-left status bar, then select "Create new branch.". Think of it like entering a new building: first you find the lobby, then the room, then the door you actually need.

      +

      Alex: Treat examples as spoken recipes, not decorations. You may hear something like git checkout -b fix/welcome-todo. Read the command, understand what it changes, then run it only when the repository state matches the lesson.

      -

      Jamie: Let's pause on Method 1: Extensions Sidebar. What should a learner take away from it?

      -

      Alex: Start with Method 1: Extensions Sidebar. There is something to understand, something to try, and something that proves the try worked.

      -

      Alex: First, open Extensions sidebar: Ctrl+Shift+X (Mac: Cmd+Shift+X). Then, type "GitHub Pull Requests" in the search box. After that, find "GitHub Pull Requests and Issues" (publisher: GitHub). Finally, navigate to the extension in the results list. It is a checklist, but a meaningful one: every item creates evidence that the next step is safe.

      -

      Jamie: Before we leave Method 1: Extensions Sidebar, what is the practical point?

      -

      Alex: First, press Enter to open the extension detail page. Then, tab to "Install" button → press Enter. It is like walking a hallway with named doors: read the sign, enter the right room, then confirm where you landed.

      -

      Jamie: Let's pause on Method 2: Command Palette. What should a learner take away from it?

      -

      Alex: Keep the learner anchored in Method 2: Command Palette. The Extensions sidebar is a tree view. This is the part to say slowly: Use Up/Down Arrow to navigate, Enter to open an extension's detail page. A good GitHub workflow is like a well-run meeting: everyone knows the topic, the next action, and who has the floor.

      -

      Alex: First, ctrl+Shift+P. Then, type "install extensions". After that, select "Extensions: Install Extensions". Finally, search for "GitHub Pull Requests". It is like walking a hallway with named doors: read the sign, enter the right room, then confirm where you landed.

      -

      Jamie: Before we leave Method 2: Command Palette, what is the practical point?

      -

      Alex: First, install "GitHub Pull Requests and Issues". The rhythm is simple: orient, act, verify, then continue.

      -

      Jamie: Let's pause on Signing In to GitHub. What should a learner take away from it?

      -

      Alex: The reason Signing In to GitHub matters is that after installation, VS Code prompts you to sign in.

      -

      Alex: First, a notification appears: "Sign in to GitHub to use Pull Requests". Then, navigate to the notification (Alt+N / Mac: Option+N, or status bar navigation). After that, select "Sign in". Finally, VS Code opens your browser for GitHub OAuth authentication. The rhythm is simple: orient, act, verify, then continue.

      -

      Jamie: Before we leave Signing In to GitHub, what is the practical point?

      -

      Alex: First, authorize VS Code in the browser. Then, return to VS Code - you're now signed in. Think of it as a rail line: each stop confirms you are still on the right route before the next one.

      +

      Jamie: What does the learner do first, second, and then after that?

      +

      Alex: Start with In GitHub Desktop. There is something to understand, something to try, and something that proves the try worked.

      +

      Alex: First, click the Current Branch dropdown. Then, click "New Branch". After that, enter the name fix/welcome-todo. Finally, confirm it is based on main. Treat it like a recipe: do not add the next ingredient until the previous one is actually in the bowl.

      +

      Jamie: What should happen before anyone copies and runs it?

      +

      Alex: Start with With GitHub CLI. There is something to understand, something to try, and something that proves the try worked.

      +

      Alex: Treat examples as spoken recipes, not decorations. You may hear something like gh repo clone the workshop organization/learning-room-your username; cd learning-room; git checkout -b fix/welcome-todo. Read the command, understand what it changes, then run it only when the repository state matches the lesson.

      +

      Jamie: Where do you want a learner to place their attention here?

      +

      Alex: Keep the learner anchored in Branch naming. Good branch names are short and descriptive. This is the part to say slowly: The convention type/description is common but not required.

      +

      Alex: These are the details that keep the idea from floating away. fix/welcome-todo -- fixing a TODO in welcome.md. feature/add-schedule-link -- adding a new link. docs/update-readme -- documentation change.

      -

      Alex: Here is the practical turn. Start with Verify sign-in. There is something to understand, something to try, and something that proves the try worked.

      -

      Alex: On the ground, that means a few things. 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.

      +

      Alex: Before the learner moves on. The reason What matters matters is that the learning objective is understanding that branches let you work in isolation without affecting main. That gives the learner a simple foothold: if you created any branch with any name, you completed this challenge. The interface gets friendlier when it stops being a wall of controls and starts being a set of named places.

      Jamie: What would you say to someone who is already bracing for this to be too much?

      -

      Alex: Start with What the Extension Adds. There is something to understand, something to try, and something that proves the try worked.

      -

      Alex: Here is what that changes in practice. 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.

      -

      Alex: Keep the thread going. Start with Learning Cards: Installing the PR Extension. There is something to understand, something to try, and something that proves the try worked.

      -

      Alex: These are the details that keep the idea from floating away. 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". 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.

      -
      -

      Jamie: Let's pause on Method 1: Activity Bar. What should a learner take away from it?

      -

      Alex: Keep the learner anchored in Method 1: Activity Bar. Click the GitHub logo icon in the Activity Bar (the vertical strip of icons on the far left). This is the part to say slowly: The GitHub Pull Requests panel opens.

      -

      Alex: That becomes easier when you listen for these cues. "Pull Requests". "Issues".

      -

      Alex: First, the Activity Bar is not always reachable by Tab from the editor. Then, use Ctrl+Shift+P (Mac: Cmd+Shift+P) → type "GitHub Pull Requests: View Pull Request" or "Focus on Pull Requests View" → press Enter. After that, alternatively press Ctrl+Shift+G (Mac: Cmd+Shift+G) to open Source Control, then Tab until you reach the Activity Bar icon strip. Finally, navigate to the repository on GitHub.com. It is like walking a hallway with named doors: read the sign, enter the right room, then confirm where you landed.

      -

      Jamie: Before we leave Method 1: Activity Bar, what is the practical point?

      -

      Alex: First, click the Pull requests tab. Then, click any PR title to view its conversation, commits, and changed files. After that, use the Files changed tab to review diffs. The rhythm is simple: orient, act, verify, then continue.

      -

      Alex: Treat examples as spoken recipes, not decorations. You may hear something like 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". Read the command, understand what it changes, then run it only when the repository state matches the lesson.

      -

      Jamie: Let's pause on Method 2: Explorer Section. What should a learner take away from it?

      -

      Alex: Start with Method 2: Explorer Section. There is something to understand, something to try, and something that proves the try worked.

      -

      Alex: First, open Explorer: Ctrl+Shift+E (Mac: Cmd+Shift+E). Then, navigate with Arrow keys to find the "GitHub Pull Requests" section. After that, expand it with Right Arrow. The rhythm is simple: orient, act, verify, then continue.

      -

      Jamie: What is the one idea that makes the next few steps less mysterious?

      -

      Alex: Start with Description: The GitHub Pull Requests panel has two top-level sections. The next useful detail is this: "My Pull Requests" contains four filters: Assigned to Me, Created by Me, Waiting for my Review, and All Open.

      -
      -

      Alex: This is the part worth saying out loud. Here is the plain-English version of Screen reader announcement example. "Pull Request 42: Add Timeline Guide, opened by jeffb, 2 days ago, 3 files changed". It is like learning a transit route. The names of the stops matter because they tell you whether you are still going the right direction.

      -

      Alex: A solid navigation habit is to prove where you are before activating controls. Headings, landmarks, and the address bar are not trivia; they are your map.

      -

      Jamie: Give me the version that sounds like an instructor, not a manual.

      -

      Alex: Start with By status. There is something to understand, something to try, and something that proves the try worked.

      -

      Alex: For a learner, the useful signals are these. "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.

      -

      Alex: That connects to another useful point. Keep the learner anchored in By repository. The tree organizes PRs by repository.

      +

      Alex: Start with What Is the Learning Room?: The Learning Room is your own private GitHub repository for the workshop. The next useful detail is this: When you accept the GitHub Classroom assignment in Block 0, GitHub copies the Community-Access/learning-room-template repository into the workshop classroom organization as the workshop organization/learning-room-your username.

      +

      Alex: Hold that next to this. Here is the plain-English version of Why a Per-Student Repo? GitHub Classroom gives each participant their own repository for three reasons. Put another way, 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.

      +

      Alex: The practical anchors are these. 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.

      -

      Jamie: Let's pause on Viewing PR Details. What should a learner take away from it?

      -

      Alex: The reason Viewing PR Details matters is that a PR detail view opens in the editor area showing.

      -

      Alex: The parts worth keeping in working memory are these. 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).

      -

      Alex: First, navigate to a PR in the tree. Then, press Enter. The rhythm is simple: orient, act, verify, then continue.

      -

      Alex: Now bring the learner back to the room. Start with Screen reader experience. There is something to understand, something to try, and something that proves the try worked.

      -

      Alex: A few details make that real. 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.

      -

      Jamie: Where do you want a learner to place their attention here?

      -

      Alex: Here is the plain-English version of 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.

      +

      Jamie: Okay, set the room for us. What are we walking into?

      +

      Alex: This is where Step-by-Step: Accept Your Classroom Assignment and Open Your Repo becomes real: this is the very first hands-on step of Day 1. That matters in practice: By the end of this walkthrough you will have your own Learning Room repository on GitHub and your first challenge issue waiting for you.

      +

      Jamie: Turn that into a path someone can follow.

      +

      Alex: Start with 1. Open the assignment link. There is something to understand, something to try, and something that proves the try worked.

      +

      Alex: First, in the same browser where you are signed into GitHub, open the Day 1 assignment link the facilitator shared. Then, 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"). After that, if the page asks you to authorize GitHub Classroom to access your GitHub account, activate Authorize GitHub Classroom. This is a one-time step. It is like walking a hallway with named doors: read the sign, enter the right room, then confirm where you landed.

      +

      Jamie: Give me the sequence, because order matters here.

      +

      Alex: The reason 2. Identify yourself (if asked) matters is that GitHub Classroom may ask you to pick your name from a roster so the facilitators can match your GitHub username to the registration list.

      +

      Alex: First, 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. Then, activate the link or button next to your name. After that, 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. The rhythm is simple: orient, act, verify, then continue.

      -

      Alex: That matters because of the next idea. Start with Why Check Out a PR. There is something to understand, something to try, and something that proves the try worked.

      -

      Alex: The practical anchors are these. 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.

      -

      Jamie: Let's pause on Method 1: From the PR Detail View. What should a learner take away from it?

      -

      Alex: Start with Method 1: From the PR Detail View. There is something to understand, something to try, and something that proves the try worked.

      -

      Alex: The practical takeaway is this. Downloads the branch. Switches your local repository to that branch. Opens the changed files in the editor.

      -

      Alex: First, open a PR (see Section 2). Then, in the PR detail view, navigate to "Checkout" button. After that, press Enter. It is like walking a hallway with named doors: read the sign, enter the right room, then confirm where you landed.

      -

      Jamie: Let's pause on Method 2: From the PR Tree. What should a learner take away from it?

      -

      Alex: Start with Method 2: From the PR Tree. There is something to understand, something to try, and something that proves the try worked.

      -

      Alex: First, navigate to the PR in the GitHub Pull Requests tree. Then, press Shift+F10 (Mac: Ctrl+Return) to open context menu. After that, select "Checkout Pull Request". The rhythm is simple: orient, act, verify, then continue.

      +

      Jamie: Let's pause on 3. Accept the assignment. What should a learner take away from it?

      +

      Alex: Start with 3. Accept the assignment: The status page does not auto-announce when the repo is ready. The next useful detail is this: Use Browse mode and press K to step through links until you hear your repository link, or refresh the page until it appears.

      +

      Alex: First, you now see a screen with a button that says Accept this assignment (or just Accept the assignment ). Activate it. Then, 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. After that, 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/the workshop organization/learning-room-your username. Think of it as a rail line: each stop confirms you are still on the right route before the next one.

      +

      Jamie: Let's pause on 4. Open your new repository. What should a learner take away from it?

      +

      Alex: Start with 4. Open your new repository. There is something to understand, something to try, and something that proves the try worked.

      +

      Alex: Here is what that changes in practice. The repo name in the heading matches learning-room-your username. 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.

      +

      Alex: First, activate the link to your repository. You land on the standard GitHub repo page for the workshop organization/learning-room-your username. Then, verify three things on this page. After that, bookmark this page. You will return here for every Day 1 challenge. Treat it like a recipe: do not add the next ingredient until the previous one is actually in the bowl.

      +

      Jamie: Let's pause on 5. Find your first challenge issue. What should a learner take away from it?

      +

      Alex: This is where 5. Find your first challenge issue becomes real: when your Learning Room repo is ready, Challenge 1 appears as a GitHub issue in your repo. That matters in practice: The facilitators prepare this by running the Student Progression Bot after students accept the Classroom assignment. The workshop is closer to rehearsal than lecture. You hear the move, try the move, and then check what changed.

      +

      Alex: First, from your repository page, navigate to the Issues tab. Keyboard shortcut: press G then I. Then, 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]). After that, open Challenge 1. Read the issue body -- it tells you what to do, where to find evidence, and how to submit completion. It is a checklist, but a meaningful one: every item creates evidence that the next step is safe.

      +

      Alex: A solid issue habit is to read the title, the body, and the timeline before acting. You are listening for the requested action, the missing evidence, and the person who needs a response.

      -

      Jamie: Let's pause on Method 3: Command Palette. What should a learner take away from it?

      -

      Alex: Start with Method 3: Command Palette: After checkout, the bottom-left status bar shows the branch name (example: "jeffb/add-timeline-guide"). The next useful detail is this: Your local files now match that branch.

      -

      Alex: First, ctrl+Shift+P (Mac: Cmd+Shift+P). Then, type "GitHub Pull Requests: Checkout". After that, select "GitHub Pull Requests: Checkout Pull Request". Finally, choose the PR from the list. Think of it as a rail line: each stop confirms you are still on the right route before the next one.

      -

      Jamie: Let's pause on Returning to Your Original Branch. What should a learner take away from it?

      -

      Alex: Start with Returning to Your Original Branch. There is something to understand, something to try, and something that proves the try worked.

      -

      Alex: First, ctrl+Shift+P (Mac: Cmd+Shift+P). Then, type "git checkout". After that, select "Git: Checkout to.". Finally, choose your original branch (usually main or your feature branch). Treat it like a recipe: do not add the next ingredient until the previous one is actually in the bowl.

      -

      Alex: A solid Git habit is to know which branch you are on, what changed, and what confirmation you expect before you run the next command.

      Jamie: If I am listening before the workshop starts, what should settle in my mind first?

      -

      Alex: Start with Learning Cards: Checking Out a PR. There is something to understand, something to try, and something that proves the try worked.

      -

      Alex: The practical takeaway is this. 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. 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.

      +

      Alex: Keep the learner anchored in 6. Confirm Aria can talk to you. The PR validation bot, Aria, posts educational feedback whenever you open a pull request. This is the part to say slowly: 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 ).

      +

      Alex: Another way to ground it. The reason Workshop Recommendation (Chapter 4) matters is that chapter 4 is a system orientation chapter.

      +

      Alex: That becomes easier when you listen for these cues. There are 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.

      +

      Jamie: Let's pause on Readiness Checkpoint. What should a learner take away from it?

      +

      Alex: Start with Readiness Checkpoint: Before starting Chapter 5 challenges, you should be able to.

      +

      Alex: First, find docs/CHALLENGES.md in your Learning Room repository. Then, explain the flow: issue - branch - pull request - review - merge. After that, identify where Aria bot feedback appears on a PR (the Conversation tab). Think of it as a rail line: each stop confirms you are still on the right route before the next one.

      -

      Alex: Another way to ground it. Keep the learner anchored in 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. A good GitHub workflow is like a well-run meeting: everyone knows the topic, the next action, and who has the floor.

      -

      Jamie: Let's pause on In the PR detail view. What should a learner take away from it?

      -

      Alex: Start with In the PR detail view. There is something to understand, something to try, and something that proves the try worked.

      -

      Alex: First, scroll down to "Files Changed" section. Then, each file is a link. After that, navigate with Arrow keys. Finally, press Enter on a file to open its diff view. The rhythm is simple: orient, act, verify, then continue.

      -

      Alex: Keep the teaching thread moving. Start with Screen reader announcement: "docs/11-vscode-interface.md, 42 additions, 3 deletions".

      +

      Alex: This is the part worth saying out loud. Here is the plain-English version of Two Tracks That Reinforce Each Other. Throughout Day 1 you work on two parallel learning tracks, both in your own account. It is like learning a transit route. The names of the stops matter because they tell you whether you are still going the right direction.

      +

      Jamie: Give me the version that sounds like an instructor, not a manual.

      +

      Alex: This is where Track 1: GitHub Skills Modules (Optional Self-Paced Practice) becomes real: 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.

      +

      Alex: For a learner, the useful signals are these. Introduction to GitHub - Create branch, open PR, merge. Communicate Using Markdown - Write headings, links, code, tables. Review Pull Requests - Comment, approve, suggest changes.

      +

      Alex: A solid pull request habit is to separate three questions: what changed, why it changed, and what still needs review. That keeps the conversation useful instead of noisy.

      +

      Alex: The next layer is this. Start with Track 2: Your Learning Room Repository (Required Workshop Track). There is something to understand, something to try, and something that proves the try worked.

      +

      Alex: The parts worth keeping in working memory are these. 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).

      -

      Jamie: Let's pause on Understanding the Diff View. What should a learner take away from it?

      -

      Alex: Here is the plain-English version of Understanding the Diff View. When you open a file from "Files Changed".

      -

      Alex: Keep the teaching thread moving. Start with Split view mode (default). There is something to understand, something to try, and something that proves the try worked.

      -

      Alex: The practical takeaway is this. Left side: original file (before changes). Right side: modified file (after changes). Changed lines highlighted (added = green, removed = red).

      -

      Jamie: Let's pause on Inline view mode. What should a learner take away from it?

      -

      Alex: Start with Inline view mode. There is something to understand, something to try, and something that proves the try worked.

      -

      Alex: The practical takeaway is this. Single editor. Removed lines shown with - prefix. Added lines shown with + prefix.

      +

      Jamie: How should someone choose between those options?

      +

      Alex: Start with How the Two Tracks Compare. There is something to understand, something to try, and something that proves the try worked.

      +

      Alex: Use the comparison to make a decision, not to recite a table. The main contrasts are: GitHub Skills (optional) means Your Learning Room (required). Create a branch in a Skills repo means Create a branch in your Learning Room. Open a PR means Open a PR.

      +

      Alex: Here is the practical turn. Start with Learning Cards: Two Tracks, One Account. There is something to understand, something to try, and something that proves the try worked.

      +

      Alex: On the ground, that means a few things. 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. 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.

      +

      Jamie: Let's pause on Your Learning Room Folder Structure. What should a learner take away from it?

      +

      Alex: Here is the plain-English version of 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.

      +

      Alex: The room should hear these as checkpoints. 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.

      -

      Alex: Keep the teaching thread moving. Start with To toggle between views. There is something to understand, something to try, and something that proves the try worked.

      -

      Alex: The practical takeaway is this. Command Palette: Ctrl+Shift+P (Mac: Cmd+Shift+P) → "Diff: Toggle Inline View".

      -

      Jamie: Let's pause on Recommended workflow for screen reader users. What should a learner take away from it?

      -

      Alex: Start with Recommended workflow for screen reader users. There is something to understand, something to try, and something that proves the try worked.

      -

      Alex: The practical takeaway is this. Unchanged lines (for context). Removed lines (prefixed with -). Added lines (prefixed with +).

      -

      Alex: First, open a changed file from the PR detail view. Then, press F7 to jump to the first diff hunk. After that, press Alt+F2 (Mac: Option+F2) to open Accessible View. Finally, read the hunk content. Think of it as a rail line: each stop confirms you are still on the right route before the next one.

      -

      Jamie: Before we leave Recommended workflow for screen reader users, what is the practical point?

      -

      Alex: First, press Escape to close Accessible View. Then, press F7 to jump to the next hunk. After that, repeat until all hunks reviewed. Treat it like a recipe: do not add the next ingredient until the previous one is actually in the bowl.

      -

      Alex: Keep the teaching thread moving. Here is the plain-English version of 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. Put another way, previously, deleted code could only be read, not selected. It is like learning a transit route. The names of the stops matter because they tell you whether you are still going the right direction.

      +

      Alex: That matters because of the next idea. This is where Your Practice Branch becomes real: in your own Learning Room repository, you decide what branches to create. That matters in practice: The Day 1 challenge sequence asks you to work on a single feature branch named after yourself.

      +

      Alex: A few details make that real. 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.

      +

      Jamie: Let's pause on Why you create a separate branch. What should a learner take away from it?

      +

      Alex: Start with Why you create a separate branch. There is something to understand, something to try, and something that proves the try worked.

      +

      Alex: The practical takeaway is this. 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.

      +

      Jamie: Let's pause on How to use your branch. What should a learner take away from it?

      +

      Alex: The reason How to use your branch matters is that the Day 1 challenges (4 onward) walk you through creating and using your branch on GitHub.com. That gives the learner a simple foothold: once you start working locally in Chapter 14, the same branch is what you check out. The interface gets friendlier when it stops being a wall of controls and starts being a set of named places.

      +

      Alex: First, create the branch on GitHub.com (Challenge 4) or locally with git checkout -b learn/ from main. Then, make your changes and commit them to the branch. After that, push the branch to GitHub if you created it locally. Finally, open a pull request from learn/ - main (Challenge 6). The rhythm is simple: orient, act, verify, then continue.

      +

      Alex: Treat examples as spoken recipes, not decorations. You may hear something like git checkout learn/. Read the command, understand what it changes, then run it only when the repository state matches the lesson.

      -

      Jamie: Let's pause on Flagging Issues During Review. What should a learner take away from it?

      -

      Alex: This is where Flagging Issues During Review becomes real: start Review saves your comments as a draft until you submit the full review (see Section 7).

      -

      Alex: First, navigate to the specific line in the diff. Then, press Shift+F10 (Mac: Ctrl+Return) for context menu. After that, select "Add Comment". Finally, type your comment in the input that appears. It is a checklist, but a meaningful one: every item creates evidence that the next step is safe.

      -

      Jamie: Before we leave Flagging Issues During Review, what is the practical point?

      -

      Alex: First, choose "Single Comment" or "Start Review". It is like walking a hallway with named doors: read the sign, enter the right room, then confirm where you landed.

      -

      Alex: A solid issue habit is to read the title, the body, and the timeline before acting. You are listening for the requested action, the missing evidence, and the person who needs a response.

      -

      Alex: Keep the teaching thread moving. Start with Learning Cards: Reviewing Pull Requests in VS Code. There is something to understand, something to try, and something that proves the try worked.

      -

      Alex: The practical takeaway is this. 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. 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.

      -

      Jamie: Let's pause on Tool Cards: Create a Pull Request (from your editor). What should a learner take away from it?

      -

      Alex: The reason Tool Cards: Create a Pull Request (from your editor) matters is that VS Code Desktop (primary for Day 2). That gives the learner a simple foothold: after you've pushed commits to a feature branch, you can create a PR without leaving VS Code.

      -

      Alex: First, ctrl+Shift+P GitHub Pull Requests: Create Pull Request. Then, fill in the title, description, and base branch. After that, click Create. Finally, push your branch, then click the Compare & pull request banner on the repo page. The rhythm is simple: orient, act, verify, then continue.

      -

      Jamie: Before we leave Tool Cards: Create a Pull Request (from your editor), what is the practical point?

      -

      Alex: First, fill in the form and click Create pull request. Then, after pushing, click Create Pull Request -- this opens gitub.com with the form pre-filled. Think of it as a rail line: each stop confirms you are still on the right route before the next one.

      -

      Alex: Treat examples as spoken recipes, not decorations. You may hear something like git push -u origin your-branch; gh pr create --title "Title" --body "Description". Read the command, understand what it changes, then run it only when the repository state matches the lesson.

      +

      Jamie: Let's pause on Learning Cards: Your Practice Branch. What should a learner take away from it?

      +

      Alex: Start with Learning Cards: Your Practice Branch. There is something to understand, something to try, and something that proves the try worked.

      +

      Alex: The practical takeaway is this. 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. 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.

      +

      Jamie: Let's pause on Tool Cards: Switch to Your Practice Branch. What should a learner take away from it?

      +

      Alex: Start with Tool Cards: Switch to Your Practice Branch. There is something to understand, something to try, and something that proves the try worked.

      +

      Alex: First, on the repository page, click the branch selector dropdown (shows "main"). Then, type learn to filter, then select learn/. After that, click the branch name in the bottom-left status bar. Finally, select your learn/ branch from the list. Treat it like a recipe: do not add the next ingredient until the previous one is actually in the bowl.

      +

      Jamie: Before we leave Tool Cards: Switch to Your Practice Branch, what is the practical point?

      +

      Alex: First, click the branch name in the bottom-left status bar (or press Ctrl+Shift+P then type Git: Checkout to ). Then, select origin/learn/ from the branch list. After that, click the Current Branch dropdown at the top. It is a checklist, but a meaningful one: every item creates evidence that the next step is safe.

      +

      Jamie: Let's pause on The Practice Files: What You Will Work On. What should a learner take away from it?

      +

      Alex: This is where The Practice Files: What You Will Work On becomes real: see also: Appendix C: Markdown Reference covers all Markdown syntax with accessible examples -- you will need it for editing these files. That matters in practice: The docs/ folder contains three practice files with intentional issues.

      -

      Jamie: Let's pause on Prerequisites. What should a learner take away from it?

      -

      Alex: Start with Prerequisites. There is something to understand, something to try, and something that proves the try worked.

      -

      Alex: First, you've created a branch (see Git & Source Control: Branch Management). Then, you've made commits. After that, you've pushed the branch to GitHub (Ctrl+Shift+P / Mac: Cmd+Shift+P → "Git: Push"). Think of it as a rail line: each stop confirms you are still on the right route before the next one.

      -

      Jamie: Let's pause on Method 1: Command Palette (Recommended). What should a learner take away from it?

      -

      Alex: Start with Method 1: Command Palette (Recommended). There is something to understand, something to try, and something that proves the try worked.

      -

      Alex: First, ctrl+Shift+P (Mac: Cmd+Shift+P). Then, type "GitHub Pull Requests: Create". After that, select "GitHub Pull Requests: Create Pull Request". Finally, a form opens in the editor. Treat it like a recipe: do not add the next ingredient until the previous one is actually in the bowl.

      -

      Jamie: Let's pause on Method 2: Source Control Panel. What should a learner take away from it?

      -

      Alex: Start with Method 2: Source Control Panel. There is something to understand, something to try, and something that proves the try worked.

      -

      Alex: First, open Source Control: Ctrl+Shift+G (Mac: Cmd+Shift+G). Then, after pushing, a "Create Pull Request" button appears. After that, press Enter on that button. It is a checklist, but a meaningful one: every item creates evidence that the next step is safe.

      +

      Alex: That connects to another useful point. Keep the learner anchored in docs/welcome.md - Introduction to Open Source Contribution. This file introduces newcomers to open source. This is the part to say slowly: It has three [TODO] sections where content is missing. A good GitHub workflow is like a well-run meeting: everyone knows the topic, the next action, and who has the floor.

      +

      Jamie: Let's pause on [TODO] 1 - "Who Can Contribute?" section. What should a learner take away from it?

      +

      Alex: The reason [TODO] 1 - "Who Can Contribute?" section matters is that [TODO: Add a paragraph explaining that contributors come from all backgrounds, skill levels, and countries. That gives the learner a simple foothold: emphasize that using assistive technology is not a barrier to contribution - in fact, AT users bring a perspective that improves projects for everyone.].

      +

      Alex: Keep the thread going. Start with [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. The next useful detail is this: What questions should you ask yourself?

      -

      Jamie: Let's pause on Method 3: GitHub Panel. What should a learner take away from it?

      -

      Alex: Start with Method 3: GitHub Panel. There is something to understand, something to try, and something that proves the try worked.

      -

      Alex: First, open GitHub view (Activity Bar → GitHub icon). Then, right-click your branch in the tree. After that, select "Create Pull Request". It is like walking a hallway with named doors: read the sign, enter the right room, then confirm where you landed.

      -

      Alex: Keep the teaching thread moving. Start with Title (required). There is something to understand, something to try, and something that proves the try worked.

      -

      Alex: The practical takeaway is this. Auto-filled with your most recent commit message. Edit to make it descriptive (example: "Add Timeline View documentation").

      -

      Jamie: Let's pause on Description (optional but recommended). What should a learner take away from it?

      -

      Alex: Start with Description (optional but recommended). There is something to understand, something to try, and something that proves the try worked.

      -

      Alex: The practical takeaway is this. 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.

      +

      Jamie: Let's pause on [TODO] 3 - "After Your Contribution Is Merged" section. What should a learner take away from it?

      +

      Alex: Here is the plain-English version of [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.]. Put another way, it also has a broken internal link that needs to be found and fixed.

      +

      Alex: This is where the talk moves from concept to action. This is where docs/keyboard-shortcuts.md - Screen Reader Shortcut Reference becomes real: this is a comprehensive reference with tables for NVDA, JAWS, and VoiceOver shortcuts. That matters in practice: It contains intentional errors in some shortcut references that students need to find and fix. The workshop is closer to rehearsal than lecture. You hear the move, try the move, and then check what changed.

      +

      Alex: The practical takeaway is this. 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.

      +

      Alex: A solid navigation habit is to prove where you are before activating controls. Headings, landmarks, and the address bar are not trivia; they are your map.

      +

      Jamie: What is the pre-flight check here?

      +

      Alex: Keep the learner anchored in 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. This is the part to say slowly: It contains broken links that point to incorrect URLs and incomplete steps.

      +

      Alex: The practical takeaway is this. 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.

      -

      Alex: Keep the teaching thread moving. Start with Base branch (target). There is something to understand, something to try, and something that proves the try worked.

      -

      Alex: The practical takeaway is this. Usually main or develop. This is the branch your changes will merge into.

      -

      Jamie: Let's pause on Compare branch (source). What should a learner take away from it?

      -

      Alex: Start with Compare branch (source). There is something to understand, something to try, and something that proves the try worked.

      -

      Alex: The practical takeaway is this. Your feature branch (auto-selected). This is the branch with your changes.

      -

      Alex: Keep the teaching thread moving. Start with Reviewers (optional). There is something to understand, something to try, and something that proves the try worked.

      -

      Alex: The practical takeaway is this. Select people to review your PR. Navigate the list with Arrow keys.

      +

      Alex: Keep the teaching thread moving. The reason docs/CHALLENGES.md - Your Challenge Menu matters is that this file lists all 21 challenges organized by progression level. That gives the learner a simple foothold: each challenge lists the file(s) to edit, estimated time, skills practiced, and success criteria.

      +

      Jamie: How do these exercises create confidence instead of pressure?

      +

      Alex: Start with Bonus Challenges: Five bonus challenges (A through E) are available for students who finish faster. The next useful detail is this: These include an accessibility audit, mentoring a peer, cross-repository contribution, creating a custom workflow, and documentation improvement.

      +

      Jamie: Let's pause on Student A (working on Challenge 3: Complete Welcome Guide). What should a learner take away from it?

      +

      Alex: Here is the plain-English version of Student A (working on Challenge 3: Complete Welcome Guide). Visibility: The PR immediately appears in the repo's Pull Requests tab. It is like learning a transit route. The names of the stops matter because they tell you whether you are still going the right direction.

      +

      Alex: First, finds their assigned issue (Issues tab → filter Assignee:@me). Then, opens docs/welcome.md and edits the three [TODO] sections. After that, commits to a new branch: fix/studentA-issue12. Finally, opens a pull request with description. Treat it like a recipe: do not add the next ingredient until the previous one is actually in the bowl.

      +

      Jamie: Before we leave Student A (working on Challenge 3: Complete Welcome Guide), what is the practical point?

      +

      Alex: First, submits the PR. It is a checklist, but a meaningful one: every item creates evidence that the next step is safe.

      -

      Jamie: Let's pause on Labels (optional). What should a learner take away from it?

      -

      Alex: Start with Labels (optional). There is something to understand, something to try, and something that proves the try worked.

      -

      Alex: The practical takeaway is this. Add labels like documentation, accessibility, good-first-issue.

      -

      Alex: Keep the teaching thread moving. Start with Milestone (optional). There is something to understand, something to try, and something that proves the try worked.

      -

      Alex: The practical takeaway is this. Link the PR to a project milestone.

      -

      Jamie: Let's pause on Draft PR checkbox. What should a learner take away from it?

      -

      Alex: Start with Draft PR checkbox. There is something to understand, something to try, and something that proves the try worked.

      -

      Alex: The practical takeaway is this. Check this if the PR is not ready for review yet. Unchecked = "Ready for review".

      +

      Jamie: Let's pause on Bot (.github/workflows/learning-room-pr-bot.yml). What should a learner take away from it?

      +

      Alex: This is where Bot (.github/workflows/learning-room-pr-bot.yml) becomes real: visibility: The bot comment appears in your PR. That matters in practice: You see it; the facilitators see it; nobody else does unless they have been added as a collaborator on your repo.

      +

      Alex: The practical takeaway is this. Runs within 30 seconds. 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).

      +

      Jamie: Let's pause on Step 3: Peer Review (Facilitator-Arranged). What should a learner take away from it?

      +

      Alex: Keep the learner anchored in 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. This is the part to say slowly: 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.

      +

      Alex: First, the facilitators (Jeff and Michael) pair you with another participant. Then, they add each of you as a collaborator on the other's Learning Room repo. After that, each of you receives a notification: "You have been added as a collaborator.". Finally, you can now read the other person's PRs, leave comments, request changes, and approve. It is like walking a hallway with named doors: read the sign, enter the right room, then confirm where you landed.

      +

      Jamie: Before we leave Step 3: Peer Review (Facilitator-Arranged), what is the practical point?

      +

      Alex: First, 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. The rhythm is simple: orient, act, verify, then continue.

      +

      Jamie: Let's pause on Visibility. What should a learner take away from it?

      +

      Alex: Start with Visibility. There is something to understand, something to try, and something that proves the try worked.

      +

      Alex: The practical takeaway is this. 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.

      -

      Alex: Keep the teaching thread moving. Start with Screen reader navigation. There is something to understand, something to try, and something that proves the try worked.

      -

      Alex: The practical takeaway is this. All fields are standard form inputs. Tab to move between fields. Use Arrow keys in dropdowns (reviewers, labels, milestones).

      -

      Jamie: Let's pause on Submitting the PR. What should a learner take away from it?

      -

      Alex: Keep the learner anchored in Submitting the PR. VS Code creates the PR on GitHub and shows a success message. This is the part to say slowly: The PR link appears in the notification - click it to open the PR on GitHub, or open it in the GitHub Pull Requests panel.

      -

      Alex: First, review all fields. Then, tab to "Create" button. After that, press Enter. Finally, navigate to the repository on GitHub. It is like walking a hallway with named doors: read the sign, enter the right room, then confirm where you landed.

      -

      Jamie: Before we leave Submitting the PR, what is the practical point?

      -

      Alex: First, if you recently pushed, a yellow banner "Compare & pull request" appears - click it. Then, otherwise: click Pull requests tab, then New pull request, then select your branch. After that, fill in the title and description. Finally, click Create pull request. The rhythm is simple: orient, act, verify, then continue.

      -

      Alex: Treat examples as spoken recipes, not decorations. You may hear something like 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. Read the command, understand what it changes, then run it only when the repository state matches the lesson.

      -

      Alex: Keep the teaching thread moving. Start with Learning Cards: Creating a Pull Request. There is something to understand, something to try, and something that proves the try worked.

      -

      Alex: The practical takeaway is this. 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. 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.

      +

      Jamie: Let's pause on Your assigned peer reviewer (when one is paired with you). What should a learner take away from it?

      +

      Alex: Start with Your assigned peer reviewer (when one is paired with you). There is something to understand, something to try, and something that proves the try worked.

      +

      Alex: The practical takeaway is this. 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. 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.".

      +

      Alex: First, receives notification: "PR review requested". Then, navigates to the PR in your Learning Room repo (they have collaborator access). After that, leaves review comments. Finally, submits review: Approve (or Request Changes if a [TODO] marker was missed). Think of it as a rail line: each stop confirms you are still on the right route before the next one.

      +

      Jamie: Before we leave Visibility, what is the practical point?

      +

      Alex: The practical takeaway is this. 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.

      +

      Jamie: Let's pause on You (PR author). What should a learner take away from it?

      +

      Alex: Start with You (PR author). There is something to understand, something to try, and something that proves the try worked.

      +

      Alex: First, read Aria's feedback and any human review. Then, talks to the reviewer if something is unclear. After that, makes changes based on feedback. Finally, pushes new commits to the same branch. It is a checklist, but a meaningful one: every item creates evidence that the next step is safe.

      +

      Jamie: Before we leave You (PR author), what is the practical point?

      +

      Alex: First, re-addresses the feedback. It is like walking a hallway with named doors: read the sign, enter the right room, then confirm where you landed.

      -

      Jamie: Let's pause on 6. Pull Request Description Templates. What should a learner take away from it?

      -

      Alex: Start with 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.

      -

      Alex: Keep the teaching thread moving. Here is the plain-English version of Where Templates Are Stored. When you create a PR in VS Code, the extension automatically loads the template into the description field. It is like learning a transit route. The names of the stops matter because they tell you whether you are still going the right direction.

      -

      Alex: The practical takeaway is this.github/pull request template.md (root).github/PULL REQUEST TEMPLATE.md.github/PULL REQUEST TEMPLATE/ (folder with multiple templates). docs/pull request template.md.

      -

      Jamie: What is the safe way to learn from that example?

      -

      Alex: Start with Example PR Template. There is something to understand, something to try, and something that proves the try worked.

      -

      Alex: Treat examples as spoken recipes, not decorations. You may hear something like 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,. Read the command, understand what it changes, then run it only when the repository state matches the lesson.

      +

      Jamie: What is the teaching move inside Visibility?

      +

      Alex: The practical takeaway is this. 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.

      +

      Alex: Keep the teaching thread moving. Start with When the review is approved (or you decide to self-merge). There is something to understand, something to try, and something that proves the try worked.

      +

      Alex: The practical takeaway is this. You merge the PR (button becomes available). PR closes, shows "merged".

      +

      Jamie: What should the learner prove to themselves after each small task?

      +

      Alex: Start with Progression Bot Posts the Next Challenge. There is something to understand, something to try, and something that proves the try worked.

      +

      Alex: The practical takeaway is this. 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.

      -

      Jamie: Let's pause on Screen reader workflow. What should a learner take away from it?

      -

      Alex: Keep the learner anchored in Screen reader workflow. Keyboard tip: Use Ctrl+F (Mac: Cmd+F) to jump to each <!-- placeholder, fill it in, then F3 to jump to the next one.

      -

      Alex: First, create PR (Method 1-3 from Section 5). Then, the description field is pre-filled with the template. After that, navigate through the template with Arrow keys. Finally, replace each `` with your content. It is like walking a hallway with named doors: read the sign, enter the right room, then confirm where you landed.

      -

      Jamie: Before we leave Screen reader workflow, what is the practical point?

      -

      Alex: First, check checkboxes by typing x between the brackets: - [x]. The rhythm is simple: orient, act, verify, then continue.

      -

      Jamie: Let's pause on 7. Commenting and Requesting Changes. What should a learner take away from it?

      -

      Alex: Start with 7. Commenting and Requesting Changes. There is something to understand, something to try, and something that proves the try worked.

      -

      Alex: The practical takeaway is this. Leave inline comments on specific lines. Request changes before the PR can be merged. Approve the PR. Submit general feedback.

      -

      Jamie: Let's pause on Adding an Inline Comment. What should a learner take away from it?

      -

      Alex: Start with Adding an Inline Comment. There is something to understand, something to try, and something that proves the try worked.

      -

      Alex: First, open a file from the PR's "Files Changed" list. Then, navigate to the line you want to comment on. After that, press Shift+F10 (Mac: Ctrl+Return) to open context menu. Finally, select "Add Comment". Think of it as a rail line: each stop confirms you are still on the right route before the next one.

      -

      Jamie: Before we leave Adding an Inline Comment, what is the practical point?

      -

      Alex: First, type your comment. Then, choose "Add Single Comment" (posts immediately) or "Start Review" (saves as a draft). Treat it like a recipe: do not add the next ingredient until the previous one is actually in the bowl.

      +

      Alex: Keep the teaching thread moving. Start with Visibility. There is something to understand, something to try, and something that proves the try worked.

      +

      Alex: The practical takeaway is this. 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.

      +

      Jamie: Let's pause on Learning Cards: How PR Sharing Works. What should a learner take away from it?

      +

      Alex: Start with Learning Cards: How PR Sharing Works. There is something to understand, something to try, and something that proves the try worked.

      +

      Alex: The practical takeaway is this. 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. 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.

      +

      Alex: Keep the teaching thread moving. Keep the learner anchored in The Learning Automation System. When you open a PR in the Learning Room, you get three types of feedback. A good GitHub workflow is like a well-run meeting: everyone knows the topic, the next action, and who has the floor.

      -

      Jamie: Let's pause on Comment format tips. What should a learner take away from it?

      -

      Alex: Start with Comment format tips. There is something to understand, something to try, and something that proves the try worked.

      -

      Alex: The practical takeaway is this. Be specific: "This heading should be H3, not H2". Provide context: "Screen readers announce this as 'list with 1 item' - should be a paragraph instead". Suggest a fix: "Consider rewording to: 'Click the button to save'".

      -

      Jamie: Let's pause on If you have multiple comments to make, use "Start Review". What should a learner take away from it?

      -

      Alex: Start with If you have multiple comments to make, use "Start Review". There is something to understand, something to try, and something that proves the try worked.

      -

      Alex: First, add your first inline comment → select "Start Review". Then, continue adding comments to other lines. After that, all comments are saved as drafts (not visible to others yet). It is a checklist, but a meaningful one: every item creates evidence that the next step is safe.

      -

      Jamie: Let's pause on Submitting Your Review. What should a learner take away from it?

      -

      Alex: Keep the learner anchored in Submitting Your Review. The review type selector is a radio button group. This is the part to say slowly: Use Arrow keys to choose, Enter to confirm.

      -

      Alex: The practical takeaway is this. Comment - general feedback, no approval decision. Approve - PR looks good, ready to merge. Request Changes - issues must be fixed before merging.

      -

      Alex: First, ctrl+Shift+P (Mac: Cmd+Shift+P). Then, type "GitHub Pull Requests: Submit Review". After that, select "GitHub Pull Requests: Finish Review". Finally, choose review type. It is like walking a hallway with named doors: read the sign, enter the right room, then confirm where you landed.

      -

      Jamie: Before we leave Submitting Your Review, what is the practical point?

      -

      Alex: First, optionally add a summary comment. Then, press Enter to submit. The rhythm is simple: orient, act, verify, then continue.

      +

      Jamie: Let's pause on Type 1: Automated Bot Feedback (30 seconds). What should a learner take away from it?

      +

      Alex: Start with Type 1: Automated Bot Feedback (30 seconds). There is something to understand, something to try, and something that proves the try worked.

      +

      Alex: The practical takeaway is this. 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.

      +

      Alex: Keep the teaching thread moving. Start with Type 2: Peer Reviewer Feedback (15-60 minutes). There is something to understand, something to try, and something that proves the try worked.

      +

      Alex: The practical takeaway is this. Human judgment on content. Creative suggestions. Encouragement and mentorship. Understanding of context. Can approve, request changes, or comment.

      +

      Jamie: Let's pause on Type 3: Progress Tracking (on merge). What should a learner take away from it?

      +

      Alex: Here is the plain-English version of Type 3: Progress Tracking (on merge). Together: Instant technical feedback + human mentorship + visible progress.

      +

      Alex: The practical takeaway is this. Skill badges (Markdown Master, Accessibility Advocate). Level progression (Beginner → Intermediate → Advanced → Expert). Milestone celebrations (1st, 5th, 10th PR). Motivational comments.

      -

      Jamie: Let's pause on What Happens After Submission. What should a learner take away from it?

      -

      Alex: The reason What Happens After Submission matters is that web alternative (github.com) - reviewing. That gives the learner a simple foothold: see Accessible Code Review for detailed screen reader steps. The interface gets friendlier when it stops being a wall of controls and starts being a set of named places.

      -

      Alex: The practical takeaway is this. All your draft comments post to GitHub. The PR author receives a notification. Your review status appears on the PR (Approved / Changes Requested / Commented). If you requested changes, the PR cannot merge until you approve it.

      -

      Alex: First, open the PR and click the Files changed tab. Then, read through each file's diff. After that, click the blue + button on any line to add an inline comment. Finally, choose Start a review to batch comments. The rhythm is simple: orient, act, verify, then continue.

      -

      Jamie: Before we leave What Happens After Submission, what is the practical point?

      -

      Alex: First, click Review changes (top right) to select Comment / Approve / Request changes. Then, click Submit review. Think of it as a rail line: each stop confirms you are still on the right route before the next one.

      -

      Alex: Treat examples as spoken recipes, not decorations. You may hear something like View the PR diff in your terminal; gh pr diff 42; Approve; gh pr review 42 --approve --body "Looks good."; Request changes; gh pr review 42 --request-changes --body "Heading hierarchy needs fixing."; Comment-only (no verdict); gh pr review 42 --comment --body. Read the command, understand what it changes, then run it only when the repository state matches the lesson.

      -

      Jamie: Let's pause on Learning Cards: Commenting and Requesting Changes. What should a learner take away from it?

      -

      Alex: Start with Learning Cards: Commenting and Requesting Changes. There is something to understand, something to try, and something that proves the try worked.

      -

      Alex: The practical takeaway is this. In a diff view, navigate to a line and press Shift+F10 for the context menu, then select "Add Comment" to leave inline feedback. Choose "Start Review" instead of "Single Comment" to batch multiple comments before submitting them all at once. When submitting a review, use Ctrl+Shift+P then "GitHub Pull Requests: Submit Review" and choose Approve, Request Changes, or Comment. Inline comments appear as expandable banners within the diff view -- look for the text input box that opens below the target line. The review submission dialog has radio buttons for Approve, Request Changes, and Comment with clear labels. Increase diff view font size with Ctrl+= so line numbers and change annotations are easier to read.

      -

      Alex: Keep the teaching thread moving. Here is the plain-English version of 8. Merging Pull Requests. Who can merge: Repository maintainers, or contributors with write access.

      +

      Jamie: Let's pause on Study Groups (Optional). What should a learner take away from it?

      +

      Alex: This is where Study Groups (Optional) becomes real: 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. The workshop is closer to rehearsal than lecture. You hear the move, try the move, and then check what changed.

      +

      Alex: First, group Issue Thread - Private communication space for your group. Then, shared Review Responsibility - You review each other's work. After that, collaborative Challenges - Optional group exercises. Finally, peer Support - Tag each other with questions. It is a checklist, but a meaningful one: every item creates evidence that the next step is safe.

      +

      Jamie: Can you translate that into plain choices?

      +

      Alex: Start with Key Differences: Skills Module vs. Your Learning Room. There is something to understand, something to try, and something that proves the try worked.

      +

      Alex: Use the comparison to make a decision, not to recite a table. The main contrasts are: GitHub Skills (Your Account) means Your Learning Room (Classroom). Your personal copy of a Skills repo means Your private copy of learning-room-template. Mona (GitHub) means Aria (PR validation) and the Student Progression bot.

      +

      Alex: Keep the teaching thread moving. The reason Tips for Reviewing a Peer's PR matters is that 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. That gives the learner a simple foothold: here is how to find the PRs they want you to look at.

      -

      Jamie: Let's pause on Prerequisites for Merging. What should a learner take away from it?

      -

      Alex: This is where Prerequisites for Merging becomes real: changing the base branch: If the PR was opened against the wrong base branch, you can change it from the PR detail view in VS Code. That matters in practice: Scroll to the base branch field in the PR detail view and activate the dropdown to select a different target branch.

      -

      Alex: First, all required reviews are approved. Then, all CI checks pass (green checkmarks). After that, no merge conflicts exist. Finally, branch is up to date with base branch (main). It is a checklist, but a meaningful one: every item creates evidence that the next step is safe.

      -

      Jamie: Let's pause on Method 1: PR Detail View. What should a learner take away from it?

      -

      Alex: Start with Method 1: PR Detail View. There is something to understand, something to try, and something that proves the try worked.

      -

      Alex: First, open the PR in VS Code. Then, scroll to the bottom of the PR detail view. After that, find "Merge Pull Request" button. Finally, press Enter. It is like walking a hallway with named doors: read the sign, enter the right room, then confirm where you landed.

      -

      Jamie: Before we leave Method 1: PR Detail View, what is the practical point?

      -

      Alex: First, choose merge type (see below). The rhythm is simple: orient, act, verify, then continue.

      -

      Jamie: What is the teaching move inside Method 2: Command Palette?

      -

      Alex: Start with Method 2: Command Palette. There is something to understand, something to try, and something that proves the try worked.

      -

      Alex: First, ctrl+Shift+P (Mac: Cmd+Shift+P). Then, type "GitHub Pull Requests: Merge". After that, select "GitHub Pull Requests: Merge Pull Request". Finally, choose the PR from the list. The rhythm is simple: orient, act, verify, then continue.

      -

      Jamie: If someone only remembers one thing from Method 2: Command Palette, what should it be?

      -

      Alex: First, select merge type. Think of it as a rail line: each stop confirms you are still on the right route before the next one.

      +

      Jamie: Let's pause on Finding PRs to Review. What should a learner take away from it?

      +

      Alex: Start with Finding PRs to Review: Screen reader users (VoiceOver - macOS).

      +

      Alex: First, go to your peer's Learning Room repo (the URL the facilitators sent you, or open it from your GitHub Notifications inbox). Then, click the Pull Requests tab. After that, click the Filters dropdown - "Review requested" - your username. Finally, click any PR title to open it. Think of it as a rail line: each stop confirms you are still on the right route before the next one.

      +

      Alex: Treat examples as spoken recipes, not decorations. You may hear something like 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. 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. Read the command, understand what it changes, then run it only when the repository state matches the lesson.

      +

      Alex: Keep the teaching thread moving. Here is the plain-English version of Reading a PR You're Assigned To. Screen reader users (VoiceOver - macOS). It is like learning a transit route. The names of the stops matter because they tell you whether you are still going the right direction.

      +

      Alex: The practical takeaway is this. 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.

      +

      Jamie: Let's pause on Leaving a Review. What should a learner take away from it?

      +

      Alex: This is where Leaving a Review becomes real: screen reader users (VoiceOver - macOS).

      +

      Alex: First, scroll to the comment box on the Conversation tab. Then, type your review comment. After that, click "Review Changes" (top-right of the Files Changed tab, or at the bottom of the PR page). Finally, select your review type: Comment / Approve / Request changes. It is a checklist, but a meaningful one: every item creates evidence that the next step is safe.

      +

      Jamie: Before we leave Leaving a Review, what is the practical point?

      +

      Alex: First, click "Submit review". It is like walking a hallway with named doors: read the sign, enter the right room, then confirm where you landed.

      +

      Alex: Treat examples as spoken recipes, not decorations. You may hear something like 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". Read the command, understand what it changes, then run it only when the repository state matches the lesson.

      -

      Alex: Keep the teaching thread moving. Start with Merge Types: The merge type selector is a dropdown or radio group. The next useful detail is this: Navigate with Arrow keys, confirm with Enter.

      -

      Jamie: Let's pause on Which merge type to use. What should a learner take away from it?

      -

      Alex: Start with Which merge type to use. There is something to understand, something to try, and something that proves the try worked.

      -

      Alex: The practical takeaway is this. Check the repository's CONTRIBUTING.md for guidance. If unsure, use Merge Commit (the default and safest option).

      -

      Jamie: Let's pause on After Merging. What should a learner take away from it?

      -

      Alex: Start with After Merging. There is something to understand, something to try, and something that proves the try worked.

      -

      Alex: First, the PR closes automatically. Then, the feature branch can be deleted (VS Code prompts: "Delete branch?"). After that, recommended: switch back to main and pull the merged changes. It is a checklist, but a meaningful one: every item creates evidence that the next step is safe.

      +

      Jamie: Let's pause on Responding to Feedback. What should a learner take away from it?

      +

      Alex: Keep the learner anchored in Responding to Feedback. Screen reader users (VoiceOver - macOS).

      +

      Alex: First, open your PR (Pull Requests tab → click your PR). Then, read all comments and bot feedback. After that, click in the comment box to reply. Finally, push your fixes to the same branch. It is like walking a hallway with named doors: read the sign, enter the right room, then confirm where you landed.

      +

      Jamie: Before we leave Responding to Feedback, what is the practical point?

      +

      Alex: First, comment: "Updates pushed, ready for review". The rhythm is simple: orient, act, verify, then continue.

      +

      Alex: Treat examples as spoken recipes, not decorations. You may hear something like 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". Read the command, understand what it changes, then run it only when the repository state matches the lesson.

      +

      Jamie: Let's pause on Learning Cards: Tips for PR Sharing. What should a learner take away from it?

      +

      Alex: Start with Learning Cards: Tips for PR Sharing. There is something to understand, something to try, and something that proves the try worked.

      +

      Alex: The practical takeaway is this. 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. 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.

      +

      Alex: Keep the teaching thread moving. Start with "Can I see other students' PRs?": Not inside their Learning Room repos -- those are private to each student. The next useful detail is this: You can see other participants' work in two ways. Think of it like entering a new building: first you find the lobby, then the room, then the door you actually need.

      +

      Alex: The practical takeaway is this. 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.

      -

      Jamie: What should happen before anyone copies and runs it?

      -

      Alex: Keep the learner anchored in Switching to main and pulling. (Mac users: use Cmd+Shift+P instead of Ctrl+Shift+P).

      -

      Alex: Treat examples as spoken recipes, not decorations. You may hear something like Ctrl+Shift+P → "Git: Checkout to." → select "main"; Ctrl+Shift+P → "Git: Pull". Read the command, understand what it changes, then run it only when the repository state matches the lesson.

      -

      Jamie: Let's pause on Deleting the Feature Branch. What should a learner take away from it?

      -

      Alex: The reason Deleting the Feature Branch matters is that after merging, the feature branch is no longer needed. That gives the learner a simple foothold: web alternative (github.com) - merging.

      -

      Alex: First, ctrl+Shift+P (Mac: Cmd+Shift+P). Then, type "git delete branch". After that, select "Git: Delete Branch.". Finally, choose the merged branch. The rhythm is simple: orient, act, verify, then continue.

      -

      Jamie: Before we leave Deleting the Feature Branch, what is the practical point?

      -

      Alex: First, open the PR's Conversation tab. Then, scroll to the merge button at the bottom. After that, click the dropdown arrow to choose a merge strategy (Squash, Rebase, or Merge commit). Finally, click Merge pull request, then Confirm merge. Think of it as a rail line: each stop confirms you are still on the right route before the next one.

      -

      Alex: Treat examples as spoken recipes, not decorations. You may hear something like Merge with default strategy; gh pr merge 42; Squash and merge, then delete the branch; gh pr merge 42 --squash --delete-branch; Enable auto-merge (merges when checks pass); gh pr merge 42 --auto --squash. Read the command, understand what it changes, then run it only when the repository state matches the lesson.

      -

      Jamie: Let's pause on Learning Cards: Merging Pull Requests. What should a learner take away from it?

      -

      Alex: Start with Learning Cards: Merging Pull Requests. There is something to understand, something to try, and something that proves the try worked.

      -

      Alex: The practical takeaway is this. The merge type selector (Merge Commit, Squash, Rebase) is announced as a dropdown or radio group -- use Arrow keys to move between options and Enter to confirm; if unsure, choose Merge Commit (the default and safest option). After merging, VS Code prompts "Delete branch?" as a notification -- press Alt+N to focus the notification and Enter to confirm, then run Ctrl+Shift+P then "Git: Checkout to" and select main to return to your default branch. Confirm the merge succeeded by pressing F6 to reach the Status Bar and verifying it now reads main instead of the feature branch name. The merge button at the bottom of the PR detail view includes a dropdown arrow for selecting merge type -- at high zoom, widen the editor pane so the button label and dropdown are not truncated. After merging, the PR detail view header changes from "Open" (green badge) to "Merged" (purple badge) -- verify this colour/label change before deleting the branch. When switching back to main, the branch name in the bottom-left Status Bar updates immediately -- confirm it reads main before pulling new changes with Ctrl+Shift+P then "Git: Pull".

      +

      Jamie: Let's pause on "What if I don't agree with my assigned reviewer?". What should a learner take away from it?

      +

      Alex: Here is the plain-English version of "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. Put another way, you can request additional reviewers manually.

      +

      Alex: Keep the teaching thread moving. This is where "Will my PR get lost when everyone is working at once?" becomes real: your repo is your own; you only see your own PRs. That matters in practice: Aria's feedback is on your PR alone, and any peer reviewer is specifically assigned to you.

      +

      Jamie: Let's pause on "Can I comment on someone else's PR?". What should a learner take away from it?

      +

      Alex: Keep the learner anchored in "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. This is the part to say slowly: On the public accessibility-agents repo, anyone can comment on any open PR.

      -

      Alex: Keep the teaching thread moving. Here is the plain-English version of "No pull requests found". Issue: The GitHub Pull Requests panel is empty. It is like learning a transit route. The names of the stops matter because they tell you whether you are still going the right direction.

      -

      Jamie: Let's pause on Solutions. What should a learner take away from it?

      -

      Alex: Start with Solutions. There is something to understand, something to try, and something that proves the try worked.

      -

      Alex: First, verify you're signed in: Ctrl+Shift+P (Mac: Cmd+Shift+P) → "GitHub Pull Requests: Sign in". Then, check you have a folder open containing a Git repository. After that, refresh the panel: Ctrl+Shift+P (Mac: Cmd+Shift+P) → "GitHub Pull Requests: Refresh Pull Requests List". It is a checklist, but a meaningful one: every item creates evidence that the next step is safe.

      -

      Jamie: Before we leave Solutions, what is the practical point?

      -

      Alex: First, verify you've pushed your branch: Ctrl+Shift+P (Mac: Cmd+Shift+P) → "Git: Push". Then, check you have write access to the repository. After that, ensure your branch is ahead of the base branch (has new commits). It is like walking a hallway with named doors: read the sign, enter the right room, then confirm where you landed.

      +

      Alex: Keep the teaching thread moving. The reason "What if my reviewer doesn't respond?" matters is that mention them directly in a PR comment: "@name, any thoughts on the changes I pushed?" Or ask a facilitator to follow up. The interface gets friendlier when it stops being a wall of controls and starts being a set of named places.

      +

      Jamie: Let's pause on "Can I work with a friend?". What should a learner take away from it?

      +

      Alex: Start with "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.

      +

      Alex: Keep the teaching thread moving. Here is the plain-English version of "How long does review take?". When pairings happen during a workshop block, typically 15-60 minutes. Put another way, if a reviewer is slow, the facilitators can step in or assign someone else.

      -

      Jamie: Let's pause on "Authentication failed". What should a learner take away from it?

      -

      Alex: The reason "Authentication failed" matters is that issue: VS Code can't connect to GitHub.

      -

      Jamie: What is the teaching move inside Solutions?

      -

      Alex: First, sign out and sign back in: Ctrl+Shift+P (Mac: Cmd+Shift+P) → "GitHub Pull Requests: Sign out" → then sign in again. Then, check your GitHub Personal Access Token (see Appendix D: Git Authentication). After that, verify network connection. Think of it as a rail line: each stop confirms you are still on the right route before the next one.

      -

      Jamie: Let's pause on Try It: Review a PR from VS Code. What should a learner take away from it?

      -

      Alex: Here is the plain-English version of Try It: Review a PR from VS Code. Time: 3 minutes What you need: VS Code with GitHub Pull Requests extension installed and signed in. Put another way, you just reviewed a pull request entirely from VS Code.

      -

      Alex: First, open the PR view - Press Ctrl+Shift+P → type Pull Requests: Focus on GitHub Pull Requests View → Enter. Then, find a PR - Navigate the tree with arrow keys. Expand a PR to see its changed files. After that, open a diff - Press Enter on a changed file. The diff editor opens. Finally, use the Accessible Diff Viewer - Press F7 to jump to the first change. Your screen reader announces what was added or removed. Press F7 again to move to the next change. Treat it like a recipe: do not add the next ingredient until the previous one is actually in the bowl.

      -

      Jamie: Before we leave Try It: Review a PR from VS Code, what is the practical point?

      -

      Alex: First, leave a comment - Position your cursor on a line you want to comment on, then press Ctrl+Shift+P → Pull Request: Add Comment on Current Diff Line. Type a brief, constructive comment and submit. It is a checklist, but a meaningful one: every item creates evidence that the next step is safe.

      +

      Jamie: Let's pause on "What if bot feedback is wrong?". What should a learner take away from it?

      +

      Alex: This is where "What if bot feedback is wrong?" becomes real: Aria is intentionally educational, not punitive -- if you disagree with a check, the facilitators can override it. That matters in practice: Aria is not perfect, which is exactly why human review still matters.

      +

      Alex: Keep the teaching thread moving. Keep the learner anchored in "Do I need to complete every challenge?". The Learning Room has challenges for all skill levels. This is the part to say slowly: You can pick what interests you, complete at your pace, and continue after the workshop -- your repo stays yours. A good GitHub workflow is like a well-run meeting: everyone knows the topic, the next action, and who has the floor.

      +

      Jamie: Let's pause on Celebration: You're Contributing. What should a learner take away from it?

      +

      Alex: The reason Celebration: You're Contributing matters is that every PR you open and merge in the Learning Room is a real contribution. That gives the learner a simple foothold: you found something to improve You made a meaningful change You received feedback (technical + human) You incorporated suggestions You merged your work.

      -

      Alex: Keep the teaching thread moving. This is where Conducting Pull Request Reviews with a Screen Reader becomes real: this guide is focused entirely on the reviewer experience - navigating diffs, reading changes, leaving comments, and submitting a review - using only your keyboard and screen reader. That matters in practice: For the full pull request lifecycle (opening PRs, merge options, conflict resolution), see Working with Pull Requests.

      -

      Jamie: Where does the workshop stop being a tour and start becoming contribution?

      -

      Alex: Keep the learner anchored in Workshop Recommendation (Chapter 15 / Challenge 12). Chapter 15 is the code review chapter focused on practicing constructive feedback. This is the part to say slowly: It supports Challenge 12: Review Like a Pro.

      -

      Alex: The practical takeaway is this. There are 2 guided challenges. Automation check: none (review quality is subjective and human-focused). The evidence is issue comment with summary of review and feedback posted. The pattern is navigate diff, comment on specifics, submit verdict.

      -

      Jamie: Let's pause on Challenge 12 Practice Set. What should a learner take away from it?

      -

      Alex: Start with Challenge 12 Practice Set. There is something to understand, something to try, and something that proves the try worked.

      -

      Alex: First, review a practice PR and leave 2-3 inline comments - read the diff line by line, find specific items to comment on, and post constructive feedback. Then, submit a formal review verdict - complete your review by choosing approve, request changes, or comment only. The rhythm is simple: orient, act, verify, then continue.

      +

      Alex: Keep the teaching thread moving. Start with Creating, Reviewing, and Merging Pull Requests with a Screen Reader: See also: Chapter 15: Code Review covers the full review workflow including multi-file diffs and suggested changes. The next useful detail is this: Pull requests are where your work becomes a contribution.

      +

      Jamie: What belongs in the live room, and what can wait until after?

      +

      Alex: Here is the plain-English version of Workshop Recommendation (Chapter 6). Chapter 6 is the first PR-validated chapter where students convert issue work into merge-ready contributions.

      +

      Alex: The practical takeaway is this. There are 3. Each challenge should take under 10 minutes each. The evidence is PR metadata, bot checks, and merged issue linkage. The pattern is small change - linked PR - green checks.

      +

      Jamie: Let's pause on Chapter 6 Challenge Set. What should a learner take away from it?

      +

      Alex: This is where Chapter 6 Challenge Set becomes real: this is the first chapter where you edit files and create branches. That matters in practice: 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. The workshop is closer to rehearsal than lecture. You hear the move, try the move, and then check what changed.

      +

      Alex: First, create one small branch change - edit a practice file on a new branch. Then, open a linked PR - use the PR template and include Closes XX. After that, pass required checks - respond to bot feedback until all required checks pass. It is a checklist, but a meaningful one: every item creates evidence that the next step is safe.

      -

      Jamie: Let's pause on Practice 12.1 Step-by-Step: Review a PR and Leave Inline Comments. What should a learner take away from it?

      -

      Alex: Start with Practice 12.1 Step-by-Step: Review a PR and Leave Inline Comments: Navigate a PR diff using screen reader-friendly tools and post 2-3 specific, constructive inline comments. The next useful detail is this: GitHub.com (Files changed tab of a PR) or VS Code with the GitHub Pull Requests extension.

      -

      Alex: The practical takeaway is this. On GitHub.com: Use heading navigation to jump between files (H in NVDA). Each file header is a heading. Within a file, use arrow keys to move line by line. In VS Code: Press F7 to open the Accessible Diff Viewer (see Chapter 15, Part 1). Use F7/Shift+F7 to move between changes. Typos or grammar issues. Unclear headings or link text.

      -

      Alex: First, open your Learning Room repository on GitHub.com and navigate to the Pull requests tab. Then, find a classmate's open PR (from Chapter 6, 7, or 14). Open it. After that, activate the Files changed tab. This shows the diff - lines added in green, lines removed in red. Finally, navigate the diff. Think of it as a rail line: each stop confirms you are still on the right route before the next one.

      -

      Jamie: Before we leave Practice 12.1 Step-by-Step: Review a PR and Leave Inline Comments, what is the practical point?

      -

      Alex: First, read through the changes carefully. Look. Then, to leave an inline comment on GitHub.com: activate the + button that appears to the left of a line number when you hover or Tab to it. (Screen reader users: this button may be announced as "Add a comment to this line.") Type your comment in the text box that. After that, post 2-3 inline comments. Each comment should be. Finally, examples of good inline comments. Treat it like a recipe: do not add the next ingredient until the previous one is actually in the bowl.

      -

      Jamie: Let's pause on Practice 12.2 Step-by-Step: Submit a Formal Review Verdict. What should a learner take away from it?

      -

      Alex: Here is the plain-English version of Practice 12.2 Step-by-Step: Submit a Formal Review Verdict. Complete your review by selecting a verdict that tells the author what action to take next. Put another way, GitHub.com (the same PR you reviewed in 14.1).

      -

      Alex: The practical takeaway is this. Comment - general feedback, no explicit approval or rejection. Approve - you think the PR is ready to merge. Request changes - you found something that should be fixed before merging. If the PR has clear documentation with only minor suggestions, choose Approve.

      -

      Alex: First, after posting your inline comments, scroll to the top of the Files changed tab. Then, activate the Review changes button (at the top-right of the files changed area, or use heading navigation). After that, a dropdown opens with three options. Finally, choose the verdict that matches your review. Treat it like a recipe: do not add the next ingredient until the previous one is actually in the bowl.

      -

      Jamie: Before we leave Practice 12.2 Step-by-Step: Submit a Formal Review Verdict, what is the practical point?

      -

      Alex: First, write a brief summary in the review body (1-2 sentences). Example: "Clear improvement to the shortcut table. Two minor suggestions for link text clarity.". Then, activate Submit review. It is a checklist, but a meaningful one: every item creates evidence that the next step is safe.

      -

      Jamie: What makes this practice feel low-stakes but still real?

      -

      Alex: This is where Completing Challenge 12: Submit Your Evidence becomes real: open your assigned Challenge 12 issue and post a completion comment. That matters in practice: Close your Challenge 12 issue when done.

      +

      Jamie: Let's pause on Challenge 6.1 Step-by-Step: Create One Small Branch Change. What should a learner take away from it?

      +

      Alex: Keep the learner anchored in Challenge 6.1 Step-by-Step: Create One Small Branch Change. Edit one of the practice files and save your change on a new branch. This is the part to say slowly: your Learning Room repository on GitHub.com, using the web editor.

      +

      Alex: The practical takeaway is this. 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. 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.

      +

      Alex: First, 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). Then, open the file and activate the pencil icon (Edit this file) button. After that, the file opens in the web editor. Make your change. For. Finally, keep your change small and focused. Edit only what the issue asks for. It is like walking a hallway with named doors: read the sign, enter the right room, then confirm where you landed.

      +

      Jamie: Before we leave Challenge 6.1 Step-by-Step: Create One Small Branch Change, what is the practical point?

      +

      Alex: First, after editing, activate the Commit changes button (green button above the editor). Then, a dialog appears. In the Branch name field, type: fix/yourname-issueXX (replace yourname with your GitHub username, and XX with the issue number). After that, select Create a new branch for this commit and start a pull request. Finally, activate Propose changes. The rhythm is simple: orient, act, verify, then continue.

      +

      Jamie: Let's pause on Challenge 6.2 Step-by-Step: Open a Linked PR. What should a learner take away from it?

      +

      Alex: The reason Challenge 6.2 Step-by-Step: Open a Linked PR matters is that AI agents do not just deploy code directly; they submit pull requests. That gives the learner a simple foothold: learning to edit a file, format it in Markdown, and review a PR today prepares you to audit and approve AI-generated changes tomorrow.

      +

      Alex: The practical takeaway is this. "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". A summary of what you changed and why (at least 50 characters).

      +

      Alex: First, in the Title field, write a short description of your change. Then, in the Body field, use the PR template if one is provided. Make sure to. After that, verify the base branch is main and the compare branch is your fix/yourname-issueXX branch. Finally, activate the Create pull request button. The rhythm is simple: orient, act, verify, then continue.

      +

      Jamie: Let's pause on Challenge 6.3 Step-by-Step: Pass Required Checks. What should a learner take away from it?

      +

      Alex: Start with Challenge 6.3 Step-by-Step: Pass Required Checks: Read bot feedback, fix any issues it finds, and get all required checks to pass. The next useful detail is this: the Conversation tab of your open pull request.

      +

      Alex: The practical takeaway is this. 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.

      +

      Alex: First, wait approximately 30 seconds after opening the PR. The bot posts a validation comment. Then, read the bot comment carefully. It checks. After that, if the bot reports failures. Finally, repeat step 3 until all required checks show a green checkmark. Think of it as a rail line: each stop confirms you are still on the right route before the next one.

      +

      Jamie: Before we leave Challenge 6.3 Step-by-Step: Pass Required Checks, what is the practical point?

      +

      Alex: First, when all checks pass, request a review from a peer or the facilitator. Treat it like a recipe: do not add the next ingredient until the previous one is actually in the bowl.

      Alex: Keep the teaching thread moving. Start with Expected Outcomes. There is something to understand, something to try, and something that proves the try worked.

      -

      Alex: The practical takeaway is this. Student can navigate PR diffs with a screen reader. Student can post inline comments on specific lines of a diff. Student can write constructive, specific feedback that helps the author improve. Student can submit a formal review verdict.

      -

      Jamie: What is the teaching move inside If You Get Stuck?

      -

      Alex: The reason If You Get Stuck matters is that continue learning: The GitHub Skills courses Review Pull Requests and Code Review with GitHub Copilot cover review workflows and AI-assisted code review. That gives the learner a simple foothold: see Appendix Z for the full catalog.

      -

      Alex: First, files Changed tab will not open? Reload the PR page and retry. Make sure you are on the PR page, not the issue page. Then, cannot find the inline comment button? Tab through the line controls in the diff. The button may be announced as "Add a comment" or have a + label. If you cannot find it, use the "Review changes" button at the top to add a general comment instead. After that, not sure what to comment on? Focus on clarity: is every heading descriptive? Is every link meaningful? Are steps complete? Are keyboard shortcuts correct? Finally, review verdict button not working? Make sure you have at least one comment or have written summary text. Try reloading the page. The rhythm is simple: orient, act, verify, then continue.

      -

      Jamie: If someone only remembers one thing from If You Get Stuck, what should it be?

      -

      Alex: First, submitting the review fails? Check that you are not in draft mode and have at least read access to the repo. Then, ask facilitator to model one inline comment and one verdict submission. After that, finished but not sure you did it right? Compare your work against the Challenge 12 reference solution. Think of it as a rail line: each stop confirms you are still on the right route before the next one.

      -

      Alex: Keep the teaching thread moving. Start with Learning Moment: Specific, kind feedback helps authors improve and builds trust in the community. The next useful detail is this: Every comment you write is practice for the professional code review you will do on real projects.

      +

      Alex: The practical takeaway is this. Student opens a focused PR that maps to one issue. Student uses Closes XX correctly. Student can interpret bot feedback and improve the PR.

      +

      Jamie: Let's pause on If You Get Stuck. What should a learner take away from it?

      +

      Alex: Start with If You Get Stuck. There is something to understand, something to try, and something that proves the try worked.

      +

      Alex: First, confirm your PR includes Closes XX in title or body. Then, check that changed files are only in learning-room/. After that, open the bot validation comment and resolve one required check at a time. Finally, if checks still fail, ask for peer or facilitator review with the exact error message. It is a checklist, but a meaningful one: every item creates evidence that the next step is safe.

      +

      Jamie: Before we leave If You Get Stuck, what is the practical point?

      +

      Alex: First, finished but not sure you did it right? Compare your work against the Challenge 6 reference solution. It is like walking a hallway with named doors: read the sign, enter the right room, then confirm where you landed.

      +

      Alex: Keep the teaching thread moving. Keep the learner anchored in Learning Moment. A great PR is small, linked to an issue, and easy to review. This is the part to say slowly: Faster feedback builds confidence and momentum.

      -

      Jamie: Before we leave Learning Pattern Used in This Chapter, what is the practical point?

      -

      Alex: First, read the full diff before commenting (understand the author's intent first). Then, find specific items to comment on (lines, phrases, missing steps). After that, write comments that help, not just criticize (suggest improvements, note what works). Finally, choose a verdict that matches the substance of your feedback. Treat it like a recipe: do not add the next ingredient until the previous one is actually in the bowl.

      -

      Jamie: What is the teaching move inside Learning Pattern Used in This Chapter?

      -

      Alex: First, summarize your overall impression in 1-2 sentences. It is a checklist, but a meaningful one: every item creates evidence that the next step is safe.

      -

      Alex: Keep the teaching thread moving. This is where Before starting this chapter, verify you have completed becomes real: estimated time for this chapter: 1 hour (including exercises). The workshop is closer to rehearsal than lecture. You hear the move, try the move, and then check what changed.

      -

      Alex: The practical takeaway is this. [ ] Chapter 6: Working with Pull Requests - Understand PR structure, diffs, and comment workflows. [ ] Chapter 13: GitHub Copilot - VS Code installed and configured. [ ] Screen Reader Setup - NVDA, JAWS, or VoiceOver installed and ready to use. [ ] Access to at least one pull request to review (your own fork or a practice repo).

      -

      Jamie: Let's pause on Two Environments for Code Review. What should a learner take away from it?

      -

      Alex: Keep the learner anchored in Two Environments for Code Review. You can review pull requests in two places - each with different strengths. This is the part to say slowly: Both environments give you full keyboard and screen reader access.

      +

      Jamie: Let's pause on Why this feels achievable. What should a learner take away from it?

      +

      Alex: Start with Why this feels achievable. There is something to understand, something to try, and something that proves the try worked.

      +

      Alex: The practical takeaway is this. Scope is intentionally small. Feedback is immediate and specific. Success is visible (green checks + closed issue).

      +

      Alex: Keep the teaching thread moving. Start with About Learning Cards in This Chapter: This chapter provides learning cards: expandable blocks that offer perspective-specific guidance for different ways of working. The next useful detail is this: Not every card appears at every step. Think of it like entering a new building: first you find the lobby, then the room, then the door you actually need.

      +

      Jamie: What is the safe way to learn from that example?

      +

      Alex: Here is the plain-English version of Local Git Alternative: The Full Branch-Edit-PR Workflow. If you cloned the learning-room in Block 0 and prefer working locally. Put another way, the web editor workflow (pencil button, "Propose changes") is the primary path taught in this chapter.

      +

      Alex: Treat examples as spoken recipes, not decorations. You may hear something like cd /Documents/learning-room; git checkout main; git pull origin main; git checkout -b fix/welcome-todos. code docs/welcome.md. Read the command, understand what it changes, then run it only when the repository state matches the lesson.

      +

      Alex: Keep the teaching thread moving. This is where What Is a Pull Request? becomes real: a pull request (PR) is a proposal to merge changes from one branch into another. That matters in practice.you open a PR to request that those changes be merged into the target branch (usually main).

      +

      Alex: The practical takeaway is this. Edited a file directly on GitHub (web editor). Made changes in your fork. Made changes on a feature branch. What changed - a diff of every file.

      +

      Jamie: Let's pause on Navigating to Pull Requests. What should a learner take away from it?

      +

      Alex: Keep the learner anchored in Navigating to Pull Requests. Global pull requests dashboard: GitHub now shows a global pull requests page at github.com/pulls listing all open PRs across every repository you have access to. This is the part to say slowly: 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).

      +

      Alex: The practical takeaway is this. 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.

      +

      Alex: First, d → "Repository navigation" landmark. Then, k to navigate tabs → "Pull requests, [N] open". After that, enter to open. Finally, vO+U → Landmarks → navigate to "Repository navigation". It is like walking a hallway with named doors: read the sign, enter the right room, then confirm where you landed.

      +

      Jamie: Before we leave Navigating to Pull Requests, what is the practical point?

      +

      Alex: First, quick Nav K or VO+Right to navigate tabs → "Pull requests". Then, vO+Space to open. The rhythm is simple: orient, act, verify, then continue.

      Jamie: What should they understand before typing anything?

      -

      Alex: The reason About Learning Cards in This Chapter matters is that each review step includes expandable learning cards for different interaction styles. That gives the learner a simple foothold: open the one that matches how you work.

      -

      Alex: Treat examples as spoken recipes, not decorations. You may hear something like View the full PR diff in your terminal; gh pr diff 42; View PR details (description, status, checks); gh pr view 42; Checkout the PR branch locally for testing; gh pr checkout 42; Approve the PR; gh pr review 42 --approve --body "Heading hierarchy looks. Read the command, understand what it changes, then run it only when the repository state matches the lesson.

      -

      Jamie: Let's pause on Good News: Modern Interface is Default. What should a learner take away from it?

      -

      Alex: Start with Good News: Modern Interface is Default: As of January 2026, GitHub's improved Files Changed experience is enabled by default. The next useful detail is this: The instructions below assume you have the modern interface (which you do).

      -

      Jamie: Let's pause on Step 1: Reach the Files Changed Tab. What should a learner take away from it?

      -

      Alex: Here is the plain-English version of Step 1: Reach the Files Changed Tab. Click the Files changed tab at the top of the PR page. Put another way, the tab label shows the number of changed files (e.g., "Files changed 4"). It is like learning a transit route. The names of the stops matter because they tell you whether you are still going the right direction.

      -

      Alex: First, the PR tabs (Conversation, Commits, Checks, Files changed) are across the top of the PR page. At high zoom they may wrap to multiple lines. Then, the Files changed tab includes a badge with the number of changed files. This badge uses text (not colour alone) so it is visible in all themes. After that, after clicking Files changed, the diff page loads. At high zoom, the file tree panel on the left may collapse automatically. Click the file tree toggle (a small panel icon) or press T to toggle it back. Finally, added lines use a green background; removed lines use red. In high contrast browser settings (Windows: Settings Accessibility Contrast themes), these colours map to strong border indicators. Treat it like a recipe: do not add the next ingredient until the previous one is actually in the bowl.

      -

      Jamie: Before we leave Step 1: Reach the Files Changed Tab, what is the practical point?

      -

      Alex: First, use Ctrl++ to zoom the browser if the diff text is too small, and Ctrl+- to zoom out. It is a checklist, but a meaningful one: every item creates evidence that the next step is safe.

      -

      Alex: Treat examples as spoken recipes, not decorations. You may hear something like Press D → navigate to "Pull request navigation tabs" landmark; Press → or Tab → find "Files changed" link → Enter. Read the command, understand what it changes, then run it only when the repository state matches the lesson.

      -
      -

      Jamie: Let's pause on Step 2: Use the File Tree to Orient Yourself. What should a learner take away from it?

      -

      Alex: This is where Step 2: Use the File Tree to Orient Yourself becomes real: the file tree panel lists every changed file. That matters in practice: Before reading any diff, scan this list to understand the scope of the PR.

      -

      Jamie: Let's pause on What to listen for / look for. What should a learner take away from it?

      -

      Alex: Keep the learner anchored in What to listen for / look for. Low vision users (zoom, high contrast).

      -

      Alex: The practical takeaway is this. How many files changed? Which areas of the codebase are affected? Are there unexpected files (generated files, lock files, configuration changes)?

      -

      Alex: First, the file tree shows each filename with a colour-coded bar indicating lines added (green) and removed (red). In high contrast mode, these bars may be less visible - the +N / -N text badge next to each file is the reliable indicator. Then, at high zoom, long file paths truncate. Hover over a truncated name to see the full path in a tooltip. After that, if the file tree panel is too narrow at high zoom, drag its right edge to widen it, or toggle it off and use heading navigation (H key) to move between file diffs. It is like walking a hallway with named doors: read the sign, enter the right room, then confirm where you landed.

      -

      Jamie: How do you keep commands from becoming magic words?

      -

      Alex: The reason Step 3: Navigate Between File Diffs matters is that each changed file in the main area is an h3 heading containing the filename. That gives the learner a simple foothold: scroll through the page or click a filename in the file tree on the left.

      -

      Alex: Treat examples as spoken recipes, not decorations. You may hear something like Press 3 to jump file-by-file through the diff; Listen for: "learning-room/docs/keyboard-shortcuts.md - collapsed" or "expanded"; Press Enter or Space to expand a collapsed file. Quick Nav H or VO+Cmd+H to jump file-by-file through the diff; Listen for: "learning-room/docs/keyboard-shortcuts.md - collapsed" or "expanded"; VO+Space to expand a collapsed file. Read the command, understand what it changes, then run it only when the repository state matches the lesson.

      +

      Alex: The reason From a PR notification matters is that if you received a notification about a PR, follow the notification link directly to the PR page. That gives the learner a simple foothold: list and view pull requests from your terminal. The interface gets friendlier when it stops being a wall of controls and starts being a set of named places.

      +

      Alex: Treat examples as spoken recipes, not decorations. You may hear something like 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. Read the command, understand what it changes, then run it only when the repository state matches the lesson.

      -

      Jamie: Let's pause on Step 4: Read a Diff. What should a learner take away from it?

      -

      Alex: Start with Step 4: Read a Diff: Low vision users (zoom, high contrast). The next useful detail is this: Screen reader users - VoiceOver (macOS). Think of it like entering a new building: first you find the lobby, then the room, then the door you actually need.

      -

      Alex: The practical takeaway is this. Green highlighted lines (with a +) = lines added. Red highlighted lines (with a -) = lines removed. Plain/white lines = unchanged context. Use Ctrl+F to search within the page for specific text in the diff.

      -

      Alex: First, colour is not the only indicator. Every added line has a + character in the gutter; every removed line has a -. These text characters are reliable regardless of colour settings. Then, at high zoom, long lines of code wrap. The +/- gutter character stays at the beginning of the first line, so look left to determine the change type. After that, use Ctrl+F (browser find) to search for specific text across the entire diff page. Finally, if the diff is split view (side by side), it may be very wide at high zoom. Switch to unified diff mode: click the gear icon in the Files Changed toolbar and select "Unified" - this shows old and new in a single column. Think of it as a rail line: each stop confirms you are still on the right route before the next one.

      -

      Jamie: Before we leave Step 4: Read a Diff, what is the practical point?

      -

      Alex: First, high contrast themes in Windows (Settings Accessibility Contrast themes) make the +/- lines use bold border patterns instead of subtle colour shading. Treat it like a recipe: do not add the next ingredient until the previous one is actually in the bowl.

      -

      Alex: Treat examples as spoken recipes, not decorations. You may hear something like Press T to jump to the diff table then Insert+Space (Focus Mode); Press Down Arrow to move through lines one at a time; Press Ctrl+Alt+Right Arrow to read across columns: line number, change type, code content. Press T to jump to the diff table then Insert+Z (Virtual PC Cursor off); Press Down Arrow to move through lines; Press Ctrl+Alt+Right Arrow for column-by-column reading. Read the command, understand what it changes, then run it only when the repository state matches the lesson.

      -

      Jamie: Let's pause on What each line announces / shows. What should a learner take away from it?

      -

      Alex: Here is the plain-English version of What each line announces / shows. If the code on a line is very long, the screen reader will read the full line. Put another way, for minified or generated files, consider collapsing the file in the tree and skipping it.

      -

      Alex: The practical takeaway is this. Added lines: "+ [code content]" - or announced as "inserted". Removed lines: "- [code content]" - or announced as "deleted". Context lines: code without a + or -.

      -

      Jamie: Let's pause on Step 5: Place an Inline Comment. What should a learner take away from it?

      -

      Alex: This is where Step 5: Place an Inline Comment becomes real: when you have a specific observation about a particular line, place an inline comment directly on it. That matters in practice: Screen reader users (VoiceOver - macOS).

      -

      Alex: First, hover your mouse over a line in the diff - a blue + (comment) button appears on the left. Then, click it to open the inline comment box. After that, type your comment. Finally, click "Start a review" (not "Add single comment" - see note below). It is a checklist, but a meaningful one: every item creates evidence that the next step is safe.

      +

      Jamie: Let's pause on Learning Cards: Navigating to Pull Requests. What should a learner take away from it?

      +

      Alex: Start with Learning Cards: Navigating to Pull Requests. There is something to understand, something to try, and something that proves the try worked.

      +

      Alex: The practical takeaway is this. 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. 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.

      +

      Alex: Keep the teaching thread moving. Here is the plain-English version of The Pull Request List Page. The PR list works identically to the Issues list. Put another way, for screen reader users, - PR list semantics: The PR list does not have individual ARIA item containers with per-item semantics.

      +

      Alex: The practical takeaway is this. 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.

      +

      Jamie: Let's pause on Navigating the PR Tab Bar. What should a learner take away from it?

      +

      Alex: This is where Navigating the PR Tab Bar becomes real: the Conversation, Commits, and Files changed tabs are in a "Pull request navigation tabs" landmark. That matters in practice: The three tabs - Conversation, Commits, and Files changed - appear just below the PR title.

      +

      Alex: The practical takeaway is this. 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.

      +

      Alex: First, press D → navigate to "Pull request navigation tabs". Then, press ← or → arrow keys to move between tab options. After that, press Enter to activate a tab. Finally, vO+U → Landmarks → "Pull request navigation tabs". It is a checklist, but a meaningful one: every item creates evidence that the next step is safe.

      +

      Jamie: Before we leave Navigating the PR Tab Bar, what is the practical point?

      +

      Alex: First, vO+Right to move between tabs. Then, vO+Space to activate. It is like walking a hallway with named doors: read the sign, enter the right room, then confirm where you landed.

      -

      Jamie: Let's pause on Placing a multi-line comment. What should a learner take away from it?

      -

      Alex: Keep the learner anchored in Placing a multi-line comment. Click and drag across multiple line numbers in the diff gutter to select a range. This is the part to say slowly: A comment button appears for the selected range.

      -

      Jamie: Let's pause on Step 6: Read Existing Comments and Threads. What should a learner take away from it?

      -

      Alex: The reason Step 6: Read Existing Comments and Threads matters is that inline comments from other reviewers appear as h3 headings within the diff table. That gives the learner a simple foothold: each thread shows: reviewer username, comment body, replies, a "Reply" link and resolution button. The interface gets friendlier when it stops being a wall of controls and starts being a set of named places.

      -

      Alex: Treat examples as spoken recipes, not decorations. You may hear something like Tab to the "Resolve conversation" button → Enter. Tab to the "Resolve conversation" button → VO+Space. Read the command, understand what it changes, then run it only when the repository state matches the lesson.

      -

      Jamie: Let's pause on Step 7: Submit Your Review. What should a learner take away from it?

      -

      Alex: Start with Step 7: Submit Your Review: Screen reader users (VoiceOver - macOS).

      -

      Alex: First, click the "Review changes" button (top-right of the Files Changed page or bottom of the PR). Then, a dialog opens with a summary text area and three radio buttons: Comment / Approve / Request changes. After that, optionally type an overall summary in the text area. Finally, select your verdict. Think of it as a rail line: each stop confirms you are still on the right route before the next one.

      -

      Jamie: Before we leave Step 7: Submit Your Review, what is the practical point?

      -

      Alex: First, click "Submit review". Treat it like a recipe: do not add the next ingredient until the previous one is actually in the bowl.

      +

      Jamie: Let's pause on PR Description. What should a learner take away from it?

      +

      Alex: Start with PR Description. There is something to understand, something to try, and something that proves the try worked.

      +

      Alex: First, 2 → navigate to "Description" h2 heading. Then, ↓ to read the description. After that, markdown renders as semantic HTML - headings, lists, code blocks are fully accessible. It is like walking a hallway with named doors: read the sign, enter the right room, then confirm where you landed.

      +

      Jamie: Let's pause on Status Checks Section. What should a learner take away from it?

      +

      Alex: The reason Status Checks Section matters is that below the description, the status checks summary shows whether automated tests passed. That gives the learner a simple foothold: status checks appear as a coloured banner below the PR description - green tick for passed, red X for failed, yellow spinner for running.

      +

      Alex: The practical takeaway is this. "All checks have passed" / "Some checks failed" / "Checks pending". A "Show all checks" button or link.

      +

      Alex: First, press H or 2 to find the "Checks" or "Status checks" heading. Then, press K to navigate links for individual check names. After that, press Enter on a check to see its details. Finally, quick Nav H or VO+Cmd+H to jump to the "Checks" or "Status checks" heading. The rhythm is simple: orient, act, verify, then continue.

      +

      Jamie: Before we leave Status Checks Section, what is the practical point?

      +

      Alex: First, quick Nav K to navigate check name links. Then, vO+Space on a check to see its details. Think of it as a rail line: each stop confirms you are still on the right route before the next one.

      +

      Alex: Keep the teaching thread moving. Start with Review Comments: Each review comment thread is an h3.

      +

      Alex: The practical takeaway is this. 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.

      -

      Jamie: Let's pause on Step 8: Re-request Review (for Authors). What should a learner take away from it?

      -

      Alex: Here is the plain-English version of Step 8: Re-request Review (for Authors). After you address review comments on your own PR. Put another way, look in the right sidebar for the Reviewers section.

      -

      Alex: Treat examples as spoken recipes, not decorations. You may hear something like Step 1: From your PR's Conversation tab, Quick Nav H or VO+Cmd+H to find the "Reviewers" heading in the sidebar; Step 2: Tab or Quick Nav B to find the re-request icon ("Re-request review") next to the reviewer's name; Step 3: VO+Space to activate - this. Read the command, understand what it changes, then run it only when the repository state matches the lesson.

      -

      Jamie: Let's pause on Learning Cards: Reviewing on GitHub.com. What should a learner take away from it?

      -

      Alex: Start with Learning Cards: Reviewing on GitHub.com. There is something to understand, something to try, and something that proves the try worked.

      -

      Alex: The practical takeaway is this. In the Files Changed tab, press T to jump to the diff table, then use Focus Mode (Insert+Space in NVDA, Insert+Z in JAWS) and Down Arrow to read line by line -- each added line starts with + and each removed line with -. To place an inline comment, navigate to the target line and press Tab or B to find the "Add a comment to this line" button; after typing your comment, choose "Start a review" (not "Add single comment") to batch all feedback into one notification. Submit your full review by pressing B repeatedly to find the "Review changes" button; the dialog contains a radio group (Comment / Approve / Request changes) navigable with Arrow keys, then Tab to "Submit review". Switch from split diff to unified diff (gear icon in the Files Changed toolbar then select "Unified") to show old and new code in a single column -- much easier to follow at high zoom than two side-by-side panes. The blue + comment button appears in the line gutter on hover; at high zoom it may be small -- use Ctrl++ to increase browser zoom and look just left of the line number column. The "Review changes" dialog uses clearly labeled radio buttons for the three verdict types; each label includes a brief description, and the currently selected option has a filled circle indicator visible in all themes.

      -

      Alex: Keep the teaching thread moving. Keep the learner anchored in Reviewing in VS Code with the Accessible Diff Viewer. When you check out a branch locally, VS Code's diff editor offers the Accessible Diff Viewer - a purpose-built, line-by-line reading mode designed specifically for screen readers. A good GitHub workflow is like a well-run meeting: everyone knows the topic, the next action, and who has the floor.

      +

      Jamie: Let's pause on Resolving conversations. What should a learner take away from it?

      +

      Alex: Here is the plain-English version of Resolving conversations. When a review comment has been addressed, you can mark the conversation as resolved. Put another way, resolved conversations are still accessible - they collapse but can be expanded again.

      +

      Alex: First, navigate to the conversation thread (3 to jump between comment headings). Then, tab to the end of the thread to find the "Resolve conversation" button. After that, press Enter to mark it resolved. Finally, the conversation collapses and shows as "Resolved". Treat it like a recipe: do not add the next ingredient until the previous one is actually in the bowl.

      +

      Alex: Keep the teaching thread moving. Start with Learning Cards: Reading the Conversation Tab. There is something to understand, something to try, and something that proves the try worked.

      +

      Alex: The practical takeaway is this. 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. 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.

      +

      Jamie: Let's pause on Reading the Checks Tab. What should a learner take away from it?

      +

      Alex: Keep the learner anchored in Reading the Checks Tab. The Checks tab shows the status of automated tests, CI workflows, and other verification processes running on your PR. This is the part to say slowly: It helps you verify whether your changes pass all required tests before merging.

      +

      Alex: The practical takeaway is this. Navigate through the check steps with K or Tab. Activate a step for more details.

      +

      Alex: First, navigate to the "Pull request tabs" landmark (D). Then, navigate between tab links (K or Tab) and activate "Checks". After that, press D to jump to the "check suites" section - this moves focus to the collapsed details button of the first check. Finally, press B or Tab to navigate between check buttons; each button is labeled with the check's name. It is like walking a hallway with named doors: read the sign, enter the right room, then confirm where you landed.

      +

      Jamie: Before we leave Reading the Checks Tab, what is the practical point?

      +

      Alex: First, press Enter or Space to expand a check and reveal its logs. Then, for a summary view: press D to navigate to the "check run summary" section. After that, vO+U - Landmarks - "Pull request tabs" - activate "Checks". Finally, vO+U - Landmarks - navigate to "check suites" section. The rhythm is simple: orient, act, verify, then continue.

      -

      Jamie: Let's pause on Opening a Diff in VS Code. What should a learner take away from it?

      -

      Alex: The reason Opening a Diff in VS Code matters is that if you have the GitHub Pull Requests extension. That gives the learner a simple foothold: without the extension, any git diff operation also opens the diff editor.

      -

      Alex: First, open the GitHub Pull Requests view (Explorer sidebar or Ctrl+Shift+P → "GitHub Pull Requests: View Pull Request"). Then, find the PR and open it - changed files appear in the file tree. After that, navigate to any file in the tree and press Enter to open its diff view. The rhythm is simple: orient, act, verify, then continue.

      -

      Jamie: Let's pause on Learning Cards: VS Code Code Review. What should a learner take away from it?

      -

      Alex: Start with Learning Cards: VS Code Code Review: Low vision users (zoom, high contrast). The next useful detail is this: VS Code's diff editor works well at high zoom.

      -

      Alex: First, split view vs. inline: By default, VS Code shows diffs in a split (side-by-side) view. At high zoom this can be very cramped. Switch to inline mode: Ctrl+Shift+P then type "Toggle Inline View" in any diff editor. Inline mode shows old and new code in a single. Then, colour indicators: Added lines have a green gutter bar; removed lines have a red gutter bar. In high contrast themes, these use heavy solid borders that are visible even at extreme zoom levels. After that, change navigation: Press F7 to jump to the next change and Shift+F7 for the previous. Each change is highlighted with a visible focus box that moves with your position - much easier than scrolling at high zoom. Finally, minimap in diff view: The minimap (right edge) shows an overview of changes as coloured blocks. At high zoom the minimap may be too small to be useful - disable it via Settings if it adds visual noise. Think of it as a rail line: each stop confirms you are still on the right route before the next one.

      -

      Jamie: Before we leave Learning Cards: VS Code Code Review, what is the practical point?

      -

      Alex: First, font size for diffs: Diff editors use your configured editor font size (editor.fontSize). Increase this in Settings (Ctrl+,) if the diff text is too small at your zoom level. Then, comment highlight: When you add a comment through the GitHub PR extension, the commented line gets a distinct background. In high contrast themes this is a solid colour band. Treat it like a recipe: do not add the next ingredient until the previous one is actually in the bowl.

      -

      Jamie: Let's pause on Opening the PR for review. What should a learner take away from it?

      -

      Alex: Start with Opening the PR for review. There is something to understand, something to try, and something that proves the try worked.

      -

      Alex: First, press Ctrl+Shift+P, type "GitHub Pull Requests: View Pull Request". Then, the PR tree appears in the sidebar - navigate with Down Arrow. After that, each changed file is announced with its name and change summary. Finally, press Enter on a file to open its diff editor. Treat it like a recipe: do not add the next ingredient until the previous one is actually in the bowl.

      -

      Jamie: Before we leave Opening the PR for review, what is the practical point?

      -

      Alex: First, the diff editor opens with the standard VS Code diff layout. It is a checklist, but a meaningful one: every item creates evidence that the next step is safe.

      +

      Alex: Keep the teaching thread moving. Start with Learning Cards: Reading the Checks Tab. There is something to understand, something to try, and something that proves the try worked.

      +

      Alex: The practical takeaway is this. 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. 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.

      +

      Jamie: Let's pause on Reading the Files Changed Tab. What should a learner take away from it?

      +

      Alex: Start with Reading the Files Changed Tab: the learner will read diffs - the before/after state of every file that changed. The next useful detail is this: This guide uses GitHub's improved Files Changed experience.

      +

      Jamie: Let's pause on File Tree (left panel). What should a learner take away from it?

      +

      Alex: Here is the plain-English version of File Tree (left panel). The file tree lists every changed file. Put another way, use it to jump directly to a specific file's diff. It is like learning a transit route. The names of the stops matter because they tell you whether you are still going the right direction.

      +

      Alex: The practical takeaway is this. 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.

      +

      Alex: First, d → navigate to "File tree" region. Then, ↑/↓ to navigate the file list. After that, enter to jump to that file's diff. Finally, vO+U → Landmarks → navigate to "File tree" region. Treat it like a recipe: do not add the next ingredient until the previous one is actually in the bowl.

      +

      Jamie: Before we leave File Tree (left panel), what is the practical point?

      +

      Alex: First, vO+Down to move through the file list. Then, vO+Space to jump to that file's diff. It is a checklist, but a meaningful one: every item creates evidence that the next step is safe.

      -

      Jamie: Let's pause on Using the Accessible Diff Viewer. What should a learner take away from it?

      -

      Alex: Start with Using the Accessible Diff Viewer. There is something to understand, something to try, and something that proves the try worked.

      -

      Alex: First, in the diff editor, press F7 to open the Accessible Diff Viewer. Then, NVDA announces: "Changed lines X to Y in filename, Change 1 of N". After that, the viewer shows each change with "Removed:" and "Added:" labels. Finally, press F7 to move to the next change, Shift+F7 for previous. It is a checklist, but a meaningful one: every item creates evidence that the next step is safe.

      -

      Jamie: Before we leave Using the Accessible Diff Viewer, what is the practical point?

      -

      Alex: First, press Escape when done to close the viewer. It is like walking a hallway with named doors: read the sign, enter the right room, then confirm where you landed.

      -

      Jamie: Let's pause on Placing a comment. What should a learner take away from it?

      -

      Alex: Keep the learner anchored in Placing a comment. Screen reader users (VoiceOver on macOS).

      -

      Alex: First, navigate to the line you want to comment on in the diff. Then, press Ctrl+Shift+P, type "GitHub Pull Requests: Add Comment". After that, a text area opens below the line - NVDA announces the input focus. Finally, type your comment. It is like walking a hallway with named doors: read the sign, enter the right room, then confirm where you landed.

      -

      Jamie: Before we leave Placing a comment, what is the practical point?

      -

      Alex: First, press Tab to the Submit button, then Enter. The rhythm is simple: orient, act, verify, then continue.

      -

      Jamie: Let's pause on Opening the PR. What should a learner take away from it?

      -

      Alex: Start with Opening the PR. There is something to understand, something to try, and something that proves the try worked.

      -

      Alex: First, press Cmd+Shift+P, type "GitHub Pull Requests: View Pull Request". Then, navigate the PR tree with VO+Down Arrow. After that, press Return on a file to open its diff. The rhythm is simple: orient, act, verify, then continue.

      +

      Jamie: Let's pause on The Diff for a File. What should a learner take away from it?

      +

      Alex: Start with The Diff for a File. There is something to understand, something to try, and something that proves the try worked.

      +

      Alex: The practical takeaway is this. 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.

      +

      Alex: Keep the teaching thread moving. Start with Lines in a diff are read as. There is something to understand, something to try, and something that proves the try worked.

      +

      Alex: The practical takeaway is this. + Added line - line that was added. Removed line - line that was removed. Context line - unchanged line shown for context.

      +

      Jamie: Let's pause on Navigating the diff with a screen reader. What should a learner take away from it?

      +

      Alex: The reason Navigating the diff with a screen reader matters is that each file's diff shows added lines in green and removed lines in red. That gives the learner a simple foothold: scroll the page to read through changes.

      +

      Alex: The practical takeaway is this. 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.

      +

      Alex: First, t to jump to the next diff table. Then, switch to Focus Mode: Insert+Space (NVDA) or Insert+Z (JAWS). After that, ctrl+Alt+↓ to move down one row (next diff line), Ctrl+Alt+↑ to move up. Finally, ctrl+Alt+→ to read across columns (line number change type content). The rhythm is simple: orient, act, verify, then continue.

      +

      Jamie: Before we leave Navigating the diff with a screen reader, what is the practical point?

      +

      Alex: First, the screen reader reads: "+ Add accessible name to submit button". Then, collapsed sections contain unchanged code. Focus the expand/disclosure control and activate it (Enter or Space) to reveal the hidden lines. After that, t or VO+U → Tables → select the diff table. Finally, vO+Shift+Down to enter the table. Think of it as a rail line: each stop confirms you are still on the right route before the next one.

      -

      Jamie: Let's pause on Accessible Diff Viewer. What should a learner take away from it?

      -

      Alex: Start with Accessible Diff Viewer. There is something to understand, something to try, and something that proves the try worked.

      -

      Alex: First, press F7 in the diff editor. Then, VoiceOver announces each change with clear "Removed" and "Added" labels. After that, navigate with F7/Shift+F7. Finally, press Escape to close. Think of it as a rail line: each stop confirms you are still on the right route before the next one.

      -

      Jamie: Let's pause on Comment placement. What should a learner take away from it?

      -

      Alex: Start with Comment placement. There is something to understand, something to try, and something that proves the try worked.

      -

      Alex: First, press Cmd+Shift+P, type "GitHub Pull Requests: Add Comment". Then, vO+Shift+Down Arrow to interact with the comment text area. After that, type your comment. Finally, vO+Shift+Up Arrow to stop interacting, then Tab to Submit. Treat it like a recipe: do not add the next ingredient until the previous one is actually in the bowl.

      -

      Jamie: Let's pause on Using the Accessible Diff Viewer (F7). What should a learner take away from it?

      -

      Alex: This is where Using the Accessible Diff Viewer (F7) becomes real: the Accessible Diff Viewer reads each change as a structured block. That matters in practice: This example is from a real Learning Room scenario: a contributor fixing the heading hierarchy in docs/keyboard-shortcuts.md by changing a level-4 heading to level-3, which is exactly what you look for when reviewing Challenge 2 PRs.

      -

      Alex: Treat examples as spoken recipes, not decorations. You may hear something like "Changed lines 14 to 14 in docs/keyboard-shortcuts.md; [Change 1 of 3]; Removed:; NVDA Single-Key Navigation; Added:; NVDA Single-Key Navigation". Read the command, understand what it changes, then run it only when the repository state matches the lesson.

      +

      Jamie: Let's pause on Placing an inline comment on a diff line. What should a learner take away from it?

      +

      Alex: Start with Placing an inline comment on a diff line: Hover over any line in the diff - a blue + button appears on the left margin. The next useful detail is this: Click it to open a comment box for that line. Think of it like entering a new building: first you find the lobby, then the room, then the door you actually need.

      +

      Alex: The practical takeaway is this. 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.

      +

      Alex: First, navigate to the specific line in the diff (using the table navigation above). Then, while focused on that line, a comment button appears - press Enter or Space to activate it. After that, a comment box opens below the line. Finally, focus Mode → type your comment. Think of it as a rail line: each stop confirms you are still on the right route before the next one.

      +

      Jamie: Before we leave Placing an inline comment on a diff line, what is the practical point?

      +

      Alex: First, tab to Add single comment button (instant comment) OR Start a review (to batch comments). Treat it like a recipe: do not add the next ingredient until the previous one is actually in the bowl.

      +

      Jamie: Let's pause on Multi-line comment (Windows). What should a learner take away from it?

      +

      Alex: Here is the plain-English version of Multi-line comment (Windows). Screen reader users (VoiceOver - macOS).

      +

      Alex: First, focus the first line you want to comment on. Then, press Shift+↓ to extend the selection to additional lines. After that, a comment button appears - activate it. Finally, the comment applies to the full range of selected lines. Treat it like a recipe: do not add the next ingredient until the previous one is actually in the bowl.

      +

      Jamie: Before we leave Multi-line comment (Windows), what is the practical point?

      +

      Alex: First, navigate to the specific line in the diff (using the table navigation above). Then, while focused on that line, VO+Space on the comment button that appears. After that, a comment box opens below the line. Finally, vO+Shift+Down to interact with the text area, then type your comment. It is a checklist, but a meaningful one: every item creates evidence that the next step is safe.

      +

      Jamie: Let's pause on Multi-line comment (macOS). What should a learner take away from it?

      +

      Alex: Start with Multi-line comment (macOS). There is something to understand, something to try, and something that proves the try worked.

      +

      Alex: First, focus the first line and Shift+↓ to extend the selection. Then, vO+Space on the comment button that appears. After that, the comment applies to the full range of selected lines. It is a checklist, but a meaningful one: every item creates evidence that the next step is safe.

      -

      Alex: Keep the teaching thread moving. Start with Navigation. There is something to understand, something to try, and something that proves the try worked.

      -

      Alex: The practical takeaway is this. F7 - jump to next change (next hunk). Shift+F7 - jump to previous change. Alt+F2 - open VS Code's Accessible View for additional context on the current item. Escape - close the Accessible Diff Viewer.

      -

      Jamie: Let's pause on What makes this better than the raw diff editor. What should a learner take away from it?

      -

      Alex: Start with What makes this better than the raw diff editor. There is something to understand, something to try, and something that proves the try worked.

      -

      Alex: The practical takeaway is this. Each change is announced as a discrete unit with clear "Removed:" and "Added:" labels. You hear the change number of total changes ("Change 3 of 12"). No table navigation required - purpose-built for sequential listening. Works with all three major screen readers without any special configuration.

      -

      Alex: Keep the teaching thread moving. Start with Placing Comments in VS Code (GitHub PR Extension): From the diff editor with the GitHub PR extension. The next useful detail is this: Comments placed in VS Code sync to GitHub - they appear in the PR's Files Changed tab and the author receives the same notification. Think of it like entering a new building: first you find the lobby, then the room, then the door you actually need.

      +

      Jamie: Let's pause on Viewing comments within the diff. What should a learner take away from it?

      +

      Alex: Keep the learner anchored in Viewing comments within the diff. Inline comments appear as expandable threads within the diff table. This is the part to say slowly: Navigate to them with 3 (they are h3 headings).

      +

      Alex: Keep the teaching thread moving. Start with Learning Cards: Reading the Files Changed Tab. There is something to understand, something to try, and something that proves the try worked.

      +

      Alex: The practical takeaway is this. 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. 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.

      +

      Jamie: Let's pause on Tool Cards: Open a Pull Request. What should a learner take away from it?

      +

      Alex: Start with Tool Cards: Open a Pull Request: VS Code Desktop (GitHub Pull Requests extension).

      +

      Alex: First, push your branch, then click the Compare & pull request banner (or go to Pull requests New pull request ). Then, set base branch to main, compare branch to yours. After that, fill in the title and description, then click Create pull request. Finally, after committing changes, click the Source Control icon. Think of it as a rail line: each stop confirms you are still on the right route before the next one.

      +

      Jamie: Before we leave Tool Cards: Open a Pull Request, what is the practical point?

      +

      Alex: First, click Create Pull Request in the Source Control panel header. Then, fill in details and submit. After that, press Ctrl+Shift+P, type GitHub Pull Requests: Create Pull Request. Finally, select base and compare branches. Treat it like a recipe: do not add the next ingredient until the previous one is actually in the bowl.

      +

      Alex: Treat examples as spoken recipes, not decorations. You may hear something like git push -u origin your-branch; gh pr create --title "Your title" --body "Description". Read the command, understand what it changes, then run it only when the repository state matches the lesson.

      -

      Jamie: Let's pause on The Anatomy of a Useful Review Comment. What should a learner take away from it?

      -

      Alex: Here is the plain-English version of The Anatomy of a Useful Review Comment. A comment that helps the author is.

      -

      Alex: First, specific - link to the exact line and name the pattern you see. Then, educational - say why something matters, not just what to change. After that, graduated - signal whether this is blocking, or a preference. Treat it like a recipe: do not add the next ingredient until the previous one is actually in the bowl.

      -

      Alex: Keep the teaching thread moving. This is where Blocking example (reviewing a PR for docs/keyboard-shortcuts.md) becomes real: "The heading on line 34 uses (level 4) directly after (level 2), skipping heading level 3. That matters in practice: Screen reader users who navigate by heading level will miss any content between those two levels.

      -

      Jamie: Let's pause on Non-blocking (nit) example (reviewing a PR for docs/welcome.md). What should a learner take away from it?

      -

      Alex: Keep the learner anchored in Non-blocking (nit) example (reviewing a PR for docs/welcome.md). "nit: The link text in the 'Getting Help' section reads 'click here for more information.' Screen reader users who navigate links out of context will hear only 'click here' with no destination. This is the part to say slowly: Consider 'See the accessibility setup guide' instead.

      +

      Jamie: Let's pause on From the web editor workflow (editing a file on GitHub). What should a learner take away from it?

      +

      Alex: Start with From the web editor workflow (editing a file on GitHub). There is something to understand, something to try, and something that proves the try worked.

      +

      Alex: First, you edited a file → GitHub showed a "Propose changes" form. Then, you named your branch and activated "Propose changes". After that, GitHub redirected you to the "Open a pull request" page. Treat it like a recipe: do not add the next ingredient until the previous one is actually in the bowl.

      +

      Jamie: Let's pause on From a fork or feature branch. What should a learner take away from it?

      +

      Alex: This is where From a fork or feature branch becomes real: screen reader users (NVDA / JAWS - Windows). That matters in practice: Screen reader users (VoiceOver - macOS).

      +

      Alex: First, navigate to the repository on GitHub. Then, if you recently pushed, a yellow banner "Compare & pull request" appears at the top - click it. After that, if no banner appears: click the Pull requests tab → click the green New pull request button. Finally, use the branch dropdowns to choose your base branch (what to merge into) and your compare branch (your changes). It is a checklist, but a meaningful one: every item creates evidence that the next step is safe.

      +

      Jamie: Before we leave From a fork or feature branch, what is the practical point?

      +

      Alex: First, click Create pull request. Then, navigate to the repository. After that, a "Compare & pull request" banner may appear (if you recently pushed) - activate it. Finally, oR: Navigate to Pull Requests tab → "New pull request". It is like walking a hallway with named doors: read the sign, enter the right room, then confirm where you landed.

      +

      Jamie: Let's pause on Description field. What should a learner take away from it?

      +

      Alex: Keep the learner anchored in Description field. Copilot can write your PR description: If your account has Copilot access, a "Copilot actions" button appears in the description toolbar. This is the part to say slowly: 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. A good GitHub workflow is like a well-run meeting: everyone knows the topic, the next action, and who has the floor.

      +

      Alex: Treat examples as spoken recipes, not decorations. You may hear something like Step 1: Tab to the body text area; Step 2: Focus Mode → type using the PR template (if provided). 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 for the dismiss control; Related Issues; Closes 42; Testing; - Tested with NVDA + Chrome on Windows 11; -. Read the command, understand what it changes, then run it only when the repository state matches the lesson.

      -

      Alex: Keep the teaching thread moving. The reason Question example (reviewing a PR for docs/setup-guide.md) matters is that "The PR description says this fixes broken links in the setup guide, but the link on line 12 still points to /docs/old-setup. That gives the learner a simple foothold: am I reading the diff correctly, or was this link intentionally left? The interface gets friendlier when it stops being a wall of controls and starts being a set of named places.

      -

      Jamie: Let's pause on Prefixes That Set Expectations. What should a learner take away from it?

      -

      Alex: Start with Prefixes That Set Expectations: Using shorthand prefixes helps authors parse many comments quickly.

      -

      Alex: Keep the teaching thread moving. Here is the plain-English version of How Many Comments Is Too Many? There is no hard limit, but quantity without prioritization is noise. Put another way, if you have 15 comments, make clear which 2-3 are blocking.

      +

      Jamie: Let's pause on Setting a Draft PR. What should a learner take away from it?

      +

      Alex: The reason Setting a Draft PR matters is that if your work is not finished, open as a Draft.

      +

      Alex: First, after filling in the form, find the dropdown arrow next to "Create pull request". Then, select "Create draft pull request". After that, this signals to reviewers that it is not ready for formal review yet. The rhythm is simple: orient, act, verify, then continue.

      +

      Alex: Keep the teaching thread moving. Start with Draft Pull Requests - Full Lifecycle: A draft pull request is a PR explicitly marked as a work in progress. The next useful detail is this: It is visible to the team, can receive comments, and runs CI - but is blocked from being merged until you mark it ready.

      +

      Jamie: Let's pause on When to use a draft. What should a learner take away from it?

      +

      Alex: Start with When to use a draft. There is something to understand, something to try, and something that proves the try worked.

      +

      Alex: The practical takeaway is this. You want to show your approach and get early feedback before finishing. You need CI to run but don't want accidental merges. You are working across multiple days and want your progress visible. You want to pair with a collaborator on the work.

      -

      Jamie: Let's pause on "I want to verify the PR only changes what it claims". What should a learner take away from it?

      -

      Alex: This is where "I want to verify the PR only changes what it claims" becomes real: example: A PR says "Challenge 2: Add NVDA shortcut" but the file tree shows changes to both docs/keyboard-shortcuts.md and docs/welcome.md.

      -

      Alex: Keep the teaching thread moving. Keep the learner anchored in "I want to find all changes to one specific section". Example: A PR for Challenge 3 modified docs/welcome.md. This is the part to say slowly: You want to verify the [TODO] in the "Who Can Contribute?" section was filled in correctly. A good GitHub workflow is like a well-run meeting: everyone knows the topic, the next action, and who has the floor.

      -

      Jamie: Why is the evidence prompt part of the teaching, not just grading?

      -

      Alex: The reason Exercises matters is that these exercises use the files in learning-room/docs/ in this repository. That gives the learner a simple foothold: all examples involve documentation changes - no code required.

      +

      Alex: Keep the teaching thread moving. Start with What a draft PR does differently. There is something to understand, something to try, and something that proves the try worked.

      +

      Alex: The practical takeaway is this. The merge button is disabled - even an authorized maintainer cannot merge a draft. The PR header shows a grey "Draft" badge instead of the green "Open" badge. Reviewers are not auto-notified (no review requests are sent until ready). CI workflows still run normally.

      +

      Jamie: Let's pause on Mark a draft ready for review. What should a learner take away from it?

      +

      Alex: Start with Mark a draft ready for review. There is something to understand, something to try, and something that proves the try worked.

      +

      Alex: First, open the PR. Then, navigate to the "Reviewers" sidebar or scroll to bottom of the Conversation tab. After that, find and activate the "Ready for review" button. Finally, the draft badge changes to "Open" and reviewers are notified. It is like walking a hallway with named doors: read the sign, enter the right room, then confirm where you landed.

      +

      Jamie: Let's pause on Convert an open PR to draft (after opening). What should a learner take away from it?

      +

      Alex: The reason Convert an open PR to draft (after opening) matters is that GitHub CLI (gh) alternative - draft PR lifecycle. That gives the learner a simple foothold: manage draft PRs from your terminal.

      +

      Alex: First, in the right sidebar, find the "Reviewers" section. Then, look for the "Convert to draft" link (below the review status). After that, confirm in the dialog - this removes merge eligibility until you mark it ready again. The rhythm is simple: orient, act, verify, then continue.

      +

      Alex: Treat examples as spoken recipes, not decorations. You may hear something like Create a draft PR; gh pr create --draft --title "WIP: Add carousel keyboard nav"; Mark a draft ready for review; gh pr ready 42; Check PR status (shows draft state); gh pr view 42; List only draft PRs; gh pr list --draft. Read the command, understand what it changes, then run it only when the repository state matches the lesson.

      -

      Alex: Keep the teaching thread moving. Start with Exercise A - Complete a Web Review: Scenario: A contributor has submitted a pull request titled "Add screen reader tips to the setup guide." The PR modifies learning-room/docs/setup-guide.md. The next useful detail is this: Your job is to review it before it merges.

      -

      Jamie: Let's pause on Step 1: Navigate to the Pull Request. What should a learner take away from it?

      -

      Alex: Here is the plain-English version of Step 1: Navigate to the Pull Request. How to know you're in the right place.

      -

      Alex: The practical takeaway is this. The PR title is visible at the top. You see a description box with text about what this PR does. You see tabs labeled "Conversation," "Commits," "Files Changed". Use Ctrl+F to search the PR list for "screen reader tips". Or ask in the workshop Slack - someone can share the exact URL.

      -

      Alex: First, open GitHub in your browser and navigate to the workshop repository (github.com/[your-fork]/[workshop-repo] or community-access/accessibility-agents). Then, click the Pull Requests tab (top navigation). After that, look for a PR titled "Add screen reader tips to the setup guide" - click it to open. Finally, you should now see the PR page with sections: Conversation, Commits, Files Changed. Treat it like a recipe: do not add the next ingredient until the previous one is actually in the bowl.

      -

      Jamie: Let's pause on Step 2: Read the PR Description. What should a learner take away from it?

      -

      Alex: Start with Step 2: Read the PR Description. There is something to understand, something to try, and something that proves the try worked.

      -

      Alex: The practical takeaway is this. Does the PR author explain what file changed? (should mention setup-guide.md). Does it explain why? (should mention "improve accessibility" or "add tips"). Is it clear enough that a reviewer can understand the goal without reading the diff? You can answer: "This PR adds [specific content] to [specific file] because [clear reason]". Example: "This PR adds screen reader usage tips to the setup guide because new users need accessibility guidance".

      -

      Alex: First, you are currently on the Conversation tab. Then, read the PR description (the text immediately under the PR title). After that, look for: "What does this PR change?" and "Why does it change it?". Finally, with screen reader: Navigate to the description with D (NVDA) or press Ctrl+Option+Up (VoiceOver) to find main landmarks, then read the content region. It is a checklist, but a meaningful one: every item creates evidence that the next step is safe.

      +

      Jamie: Let's pause on Learning Cards: Opening a Pull Request. What should a learner take away from it?

      +

      Alex: Start with Learning Cards: Opening a Pull Request. There is something to understand, something to try, and something that proves the try worked.

      +

      Alex: The practical takeaway is this. After editing a file on GitHub, the "Propose changes" form has a branch name field and a commit message field; press Tab to move between them. On the "Open a pull request" page, press F to jump to the Title field; Tab moves to the Description text area. Press Ctrl+Enter from inside the description text area to submit the PR without finding the Create button. The "Compare & pull request" yellow banner appears at the top of the repo after a recent push; at high zoom it may span the full width of the page. The branch comparison dropdowns (base and compare) use small text; zoom in on the area above the diff preview to read them. Draft PR: look for the dropdown arrow next to the green "Create pull request" button to switch to "Create draft pull request".

      +

      Jamie: Let's pause on Requesting reviewers. What should a learner take away from it?

      +

      Alex: Here is the plain-English version of Requesting reviewers. From the sidebar Reviewers section. Put another way, why some reviews are requested automatically: A file called CODEOWNERS in many repositories maps file paths to specific people or teams. It is like learning a transit route. The names of the stops matter because they tell you whether you are still going the right direction.

      +

      Alex: First, navigate to "Reviewers" heading (3 or H). Then, activate the gear button. After that, type a username in the search field. Finally, select from the dropdown. Treat it like a recipe: do not add the next ingredient until the previous one is actually in the bowl.

      +

      Jamie: Before we leave Requesting reviewers, what is the practical point?

      +

      Alex: First, escape to save. It is a checklist, but a meaningful one: every item creates evidence that the next step is safe.

      +

      Jamie: Let's pause on Submitting a Review. What should a learner take away from it?

      +

      Alex: This is where Submitting a Review becomes real: when you are asked to review a PR, you have three options.

      +

      Alex: The practical takeaway is this. Comment - leave feedback without a verdict; does not block merging. Approve - signal you are satisfied; often required before merge. Request changes - indicate changes must be addressed; blocks merge until resolved.

      -

      Jamie: Let's pause on Step 3: Navigate to "Files Changed". What should a learner take away from it?

      -

      Alex: Start with Step 3: Navigate to "Files Changed". There is something to understand, something to try, and something that proves the try worked.

      -

      Alex: The practical takeaway is this. A section showing the file name setup-guide.md with a small badge showing "+20 −0" (20 lines added, 0 lines removed). Below it, the diff with removed lines (preceded by −) and added lines (preceded by +). Scroll up to see if there are other files. For this exercise, only setup-guide.md should be changed. If you see other files, confirm they are not modified (the badge should show "+0 −0" or no changes).

      -

      Alex: First, click the Files Changed tab (top of the PR page, to the right of "Commits"). Then, you are now viewing the diff. After that, with keyboard (all screen readers): Press T to jump to the diff table. The page focuses on the file comparison area. It is like walking a hallway with named doors: read the sign, enter the right room, then confirm where you landed.

      -

      Jamie: Let's pause on Step 4: Activate Focus Mode for Better Diff Reading. What should a learner take away from it?

      -

      Alex: The reason Step 4: Activate Focus Mode for Better Diff Reading matters is that with screen reader (once in Focus Mode).

      -

      Alex: The practical takeaway is this. The page simplifies: sidebars disappear. Only the diff is visible - easier for screen reader navigation and less cognitive load. The diff is now the main content area. NVDA/JAWS: Press T to jump to the diff table. VoiceOver: Navigate with VO+Right Arrow to find the table/content region. Read through the changes: ↓ arrow moves to each line.

      -

      Alex: First, look for a button labeled "Focus Mode" or an icon (usually at the top right of the diff area). Then, with keyboard: Press F to toggle Focus Mode (may need to be in the diff area first). After that, with mouse: Click the Focus Mode button/icon. The rhythm is simple: orient, act, verify, then continue.

      -

      Jamie: Let's pause on Step 5: Find the Heading Hierarchy Issue. What should a learner take away from it?

      -

      Alex: Start with Step 5: Find the Heading Hierarchy Issue. There is something to understand, something to try, and something that proves the try worked.

      -

      Alex: The practical takeaway is this. Screen reader users navigate documents by heading level: 1 → 2 → 3 → 4. A skip from to breaks that navigation. When a user presses "jump to heading level 3," they'll find none, wondering if content is missing. You found the line with that violates hierarchy. You can say the line number and what heading text appears there. You understand why this is an accessibility problem.

      -

      Alex: First, read through the entire diff line by line. Pay special attention to lines starting. Then, you are looking for: a line with (four hashes, heading level 4) that comes directly after a (two hashes, heading level 2). After that, when you find it, note the exact line number shown in the diff. Think of it as a rail line: each stop confirms you are still on the right route before the next one.

      -
      -

      Jamie: Let's pause on Step 6: Place a Blocking Review Comment on the Heading. What should a learner take away from it?

      -

      Alex: Here is the plain-English version of Step 6: Place a Blocking Review Comment on the Heading. If the comment button doesn't appear. It is like learning a transit route. The names of the stops matter because they tell you whether you are still going the right direction.

      -

      Alex: The practical takeaway is this. Your comment appears in the thread under that line. The PR author sees it and can make the fix. Make sure you're hovering over the line number area (left side of the line). Try refreshing the page and trying again. Or use the "Add a reply" field at the bottom of the PR and mention the line number manually.

      -

      Alex: First, find the diff line with the problematic heading. Then, hover your mouse over the line number on the left side of that line (or if using keyboard, navigate to that line in the table). After that, a button should appear (or press the Add Comment hotkey - usually C in GitHub). Finally, click it or press Enter to open a comment box. Treat it like a recipe: do not add the next ingredient until the previous one is actually in the bowl.

      -

      Jamie: Before we leave Step 6: Place a Blocking Review Comment on the Heading, what is the practical point?

      -

      Alex: First, press Space, then explain. Then, click the Comment button (or press Ctrl+Enter for keyboard submit). It is a checklist, but a meaningful one: every item creates evidence that the next step is safe.

      -

      Jamie: Let's pause on Step 7: Find the Link Text Issue. What should a learner take away from it?

      -

      Alex: Start with Step 7: Find the Link Text Issue. There is something to understand, something to try, and something that proves the try worked.

      -

      Alex: The practical takeaway is this. Screen reader users can ask their reader to "list all links on this page" - they hear only the link text. If the text is "click here," they have no context about where it goes. Descriptive link text is WCAG 2.4.4 (Link Purpose). You found a link with non-descriptive text. You can explain why "click here" is bad and what would be better.

      -

      Alex: First, continue reading the diff (from where you left off). Then, look for a line containing link text that reads "click here" or "click here for more information". After that, note the line number. It is a checklist, but a meaningful one: every item creates evidence that the next step is safe.

      -

      Jamie: Let's pause on Step 8: Place a Comment on the Link. What should a learner take away from it?

      -

      Alex: Keep the learner anchored in Step 8: Place a Comment on the Link. nit: means "nice-to-have improvement" (not blocking, but good to fix).

      -

      Alex: First, find the line in the diff with the problematic link. Then, hover over the line number and click to open a comment box (or press C). After that, click Comment or press Ctrl+Enter. It is like walking a hallway with named doors: read the sign, enter the right room, then confirm where you landed.

      -
      -

      Jamie: Let's pause on Step 9: Submit Your Review. What should a learner take away from it?

      -

      Alex: Start with Step 9: Submit Your Review. There is something to understand, something to try, and something that proves the try worked.

      -

      Alex: The practical takeaway is this. Comment - provide feedback but don't block (for minor notes). Approve - the PR is ready to merge. Request changes - this PR cannot merge until changes are made. Your review is submitted. The PR author gets a notification. The PR shows your review with the two comments.

      -

      Alex: First, look for a button labeled "Review changes" (usually at the top right of the page or bottom of comments). Then, click it (or navigate with keyboard and press Enter). After that, a dialog appears with options. Finally, select "Request changes" (you found two things to fix). The rhythm is simple: orient, act, verify, then continue.

      -

      Jamie: Before we leave Step 9: Submit Your Review, what is the practical point?

      -

      Alex: First, in the summary field, write: Found 2 accessibility issues that must be fixed before merging. Then, click "Submit review". Think of it as a rail line: each stop confirms you are still on the right route before the next one.

      -

      Jamie: Let's pause on Reflect on This Exercise. What should a learner take away from it?

      -

      Alex: Start with Reflect on This Exercise: Keep your answers - you'll need them for Chapter 16's Accessibility Agents exercise to compare manual review with agent-assisted review. Think of it like entering a new building: first you find the lobby, then the room, then the door you actually need.

      -

      Alex: First, did heading-level navigation help? When you were looking for the issue, was it easier to navigate by heading level (1-6) than to scan every line? Then, would you have caught this without the exercise prompt? If you were a real reviewer not specifically looking for heading issues, would the diff have been obvious? After that, why does screen reader navigation matter? In one sentence, explain why a screen reader user's ability to jump through heading levels is important for this document. Think of it as a rail line: each stop confirms you are still on the right route before the next one.

      -

      Jamie: What stays the same when the tool changes?

      -

      Alex: Here is the plain-English version of Exercise B - Use the VS Code Accessible Diff Viewer. Scenario: Review the same pull request from Exercise A, this time entirely in VS Code. Put another way, you'll compare the browser experience with the VS Code experience.

      -
      -

      Alex: Keep the teaching thread moving. Start with Prerequisites. There is something to understand, something to try, and something that proves the try worked.

      -

      Alex: The practical takeaway is this. VS Code must be installed on your machine. The GitHub Pull Requests extension must be installed (see Chapter 12 for installation). You must be signed into GitHub from VS Code (use Ctrl+Shift+P → "GitHub: Sign in").

      -

      Jamie: Let's pause on Step 1: Open the GitHub Pull Requests Extension. What should a learner take away from it?

      -

      Alex: Start with Step 1: Open the GitHub Pull Requests Extension. There is something to understand, something to try, and something that proves the try worked.

      -

      Alex: The practical takeaway is this. With mouse: Click the Extensions icon on the left sidebar (looks like four squares). The extension is listed as active. It mentions: "Review and manage GitHub pull requests and issues".

      -

      Alex: First, open VS Code. Then, with keyboard (all screen readers): Press Ctrl+Shift+X to open the Extensions sidebar. After that, search for "GitHub Pull Requests". Finally, if it's not installed, click Install. It is like walking a hallway with named doors: read the sign, enter the right room, then confirm where you landed.

      -

      Jamie: Before we leave Step 1: Open the GitHub Pull Requests Extension, what is the practical point?

      -

      Alex: First, if it is installed, click GitHub Pull Requests to view its details. The rhythm is simple: orient, act, verify, then continue.

      -

      Jamie: Let's pause on Step 2: Open the Pull Requests Sidebar. What should a learner take away from it?

      -

      Alex: Start with Step 2: Open the Pull Requests Sidebar. There is something to understand, something to try, and something that proves the try worked.

      -

      Alex: The practical takeaway is this. With keyboard: The icon may not be keyboard-reachable directly; instead go to Step 3. VS Code opens a new editor tab for this PR. Below the PR title, you see a "Changes" section listing modified files. You should see setup-guide.md in the changes list. Use Ctrl+Shift+P → search GitHub Pull Requests: Open Pull Request. Paste the PR URL: https://github.com/[owner]/[repo]/pull/[number].

      -

      Alex: First, look for a GitHub-themed icon on the left sidebar (circle with octocat logo) - click it. Then, a sidebar appears showing open pull requests on repositories you have access to. After that, find the PR titled "Add screen reader tips to the setup guide" - it should appear in a list. Finally, click it to open. The rhythm is simple: orient, act, verify, then continue.

      -
      -

      Jamie: Let's pause on Step 3: View the File Changes. What should a learner take away from it?

      -

      Alex: Start with Step 3: View the File Changes. There is something to understand, something to try, and something that proves the try worked.

      -

      Alex: The practical takeaway is this. A diff editor opens showing two columns. Left: the original file (before changes). Right: the new file (after changes). Different colors show added (green), removed (red), and modified (blue) lines. The file name appears at the top: setup-guide.md. NVDA/JAWS: The editor announces "Diff Editor - setup-guide.md".

      -

      Alex: First, in the Changes section, locate setup-guide.md. Then, click on the filename to open it. Think of it as a rail line: each stop confirms you are still on the right route before the next one.

      -

      Jamie: Let's pause on Step 4: Access the Accessible Diff Viewer. What should a learner take away from it?

      -

      Alex: Here is the plain-English version of Step 4: Access the Accessible Diff Viewer. If the Accessible Diff Viewer doesn't open.

      -

      Alex: The practical takeaway is this. With mouse: Look for a button or menu option labeled "Accessible View" or "Open Accessible Diff". If no button is visible, try Alt+F2 (VS Code Accessible View toggle). A new panel opens at the bottom of VS Code. The panel announces each change one at a time. Changes appear in text format with labels: "Added: " and "Removed: ". The panel is read-only (you read the changes, you don't edit here).

      -

      Alex: First, with keyboard: Press F7 to open the Accessible Diff Viewer. Treat it like a recipe: do not add the next ingredient until the previous one is actually in the bowl.

      -

      Jamie: Let's pause on Step 5: Listen to and Understand the First Change. What should a learner take away from it?

      -

      Alex: Start with Step 5: Listen to and Understand the First Change. There is something to understand, something to try, and something that proves the try worked.

      -

      Alex: The practical takeaway is this. NVDA/JAWS: The Accessible Diff Viewer announces "Removed:" and "Added:" labels, followed by the line content. VoiceOver: The announcement may be similar; listen for "removed" and "added" keywords.

      -

      Alex: First, the first change is automatically announced when you open the Accessible Diff Viewer. Then, let your screen reader read it completely - don't interrupt. After that, write down the exact text announced. Finally, press the Down arrow to move to the next change. It is a checklist, but a meaningful one: every item creates evidence that the next step is safe.

      -
      -

      Jamie: Let's pause on Step 6: Find the Heading Hierarchy Issue. What should a learner take away from it?

      -

      Alex: Start with Step 6: Find the Heading Hierarchy Issue. There is something to understand, something to try, and something that proves the try worked.

      -

      Alex: The practical takeaway is this. Four hashes ( ) indicate a level 4 heading. In the diff, you're looking for it appearing after a level 2 heading ( ). This creates the hierarchy skip you caught in Exercise A. You found the explanation in the Accessible Diff Viewer's format. You can explain: "The added line with directly follows a, skipping level 3". The Accessible Diff Viewer made this pattern clearer than scanning raw + characters.

      -

      Alex: First, continue pressing Down arrow to move through changes. Then, listen carefully for a change involving headings (lines starting with ). After that, specifically, listen for: "Added: " (four hashes). Finally, when you hear this, stop and write it down. It is like walking a hallway with named doors: read the sign, enter the right room, then confirm where you landed.

      -

      Jamie: Let's pause on Step 7: Locate the Heading Line and Add an Inline Comment. What should a learner take away from it?

      -

      Alex: Start with Step 7: Locate the Heading Line and Add an Inline Comment. There is something to understand, something to try, and something that proves the try worked.

      -

      Alex: The practical takeaway is this. Use Ctrl+F to open Find. Search for to locate it quickly. Press Enter to jump to it. With keyboard: The comment button may appear on the current line; navigate to it and press Enter. A comment box opens. You can type your comment.

      -

      Alex: First, once you identified the problematic heading in the Accessible Diff Viewer, close the Accessible Diff Viewer (press F7 again or Alt+F2). Then, you're back in the regular Diff Editor. After that, find the line with the problematic heading. Finally, close Find (Escape). The rhythm is simple: orient, act, verify, then continue.

      -

      Jamie: Before we leave Step 7: Locate the Heading Line and Add an Inline Comment, what is the practical point?

      -

      Alex: First, place your cursor on that line. Then, right-click and select "Add Comment" or press the Comment icon that appears on the left margin. Think of it as a rail line: each stop confirms you are still on the right route before the next one.

      -

      Jamie: Let's pause on Step 8: Write Your Accessible Diff Comment. What should a learner take away from it?

      -

      Alex: Start with Step 8: Write Your Accessible Diff Comment: Why mention the Accessible Diff Viewer?

      -

      Alex: The practical takeaway is this. It shows that the tool itself helps you see the issue. It documents how you caught the problem (useful for learning).

      -

      Alex: First, in the comment box, type. Then, press Ctrl+Enter or click Comment to submit. Think of it as a rail line: each stop confirms you are still on the right route before the next one.

      -
      -

      Jamie: Let's pause on Step 9: Create a GitHub Pull Request Comment. What should a learner take away from it?

      -

      Alex: Here is the plain-English version of Step 9: Create a GitHub Pull Request Comment. Now you've reviewed the same PR in.

      -

      Alex: First, browser (Exercise A): You spot-checked line numbers manually. Then, VS Code (Exercise B): The Diff Editor plus Accessible Diff Viewer announced changes. After that, go to GitHub in your browser and open the same PR. Finally, scroll to the bottom and leave a comment in the Conversation tab. Treat it like a recipe: do not add the next ingredient until the previous one is actually in the bowl.

      -

      Jamie: Before we leave Step 9: Create a GitHub Pull Request Comment, what is the practical point?

      -

      Alex: First, click Comment. It is a checklist, but a meaningful one: every item creates evidence that the next step is safe.

      -

      Jamie: Before we leave Reflect on This Exercise, what is the practical point?

      -

      Alex: This is where Reflect on This Exercise becomes real: after completing Steps 1-9, answer. That matters in practice: In Chapter 16, you'll compare these manual reviews with the @pr-review agent's suggested changes. The workshop is closer to rehearsal than lecture. You hear the move, try the move, and then check what changed.

      -

      Alex: First, announcement clarity: Did the "Added:" and "Removed:" labels from the Accessible Diff Viewer help you follow changes faster than reading + and − prefixes in the browser? Then, navigation pattern: Which tool required less back-and-forth clicking/tabbing to understand each change? After that, when would you use each? In one sentence: describe a type of PR where you'd prefer to use each tool. It is a checklist, but a meaningful one: every item creates evidence that the next step is safe.

      -

      Jamie: How do these exercises create confidence instead of pressure?

      -

      Alex: Keep the learner anchored in Exercise C - Compare and Reflect. Your Mission: Synthesize what you learned from the manual code reviews (Exercises A & B) and document your findings. This is the part to say slowly: What You'll Learn: Which tools work best for different scenarios, and how your manual review skills prepare you to use AI agents effectively.

      +

      Alex: Keep the teaching thread moving. Keep the learner anchored in Starting a review. On the Files Changed tab, when you add inline comments, choose "Start a review" instead of "Add single comment." This batches all your comments into one review submission.

      +

      Jamie: Let's pause on Completing and submitting a review. What should a learner take away from it?

      +

      Alex: The reason Completing and submitting a review matters is that after adding your inline comments via "Start a review," you must submit the review to notify the PR author. That gives the learner a simple foothold: the review is pending until you submit it.

      +

      Alex: The practical takeaway is this. The button may scroll off-screen to the right. Use horizontal scrolling or press Tab from the page top to cycle through focusable elements until you reach it. When clicked, a popover appears with a summary text area and three radio buttons ( Comment, Approve, Request changes ). At 200%+ zoom, the popover may extend below the visible viewport. Scroll down within the popover to see the Submit review button. The radio buttons are standard HTML radio buttons. In Windows High Contrast mode, the selected radio button uses the system highlight color. Keyboard shortcut: If the button is hard to find visually, press Ctrl+Shift+Enter from within any review comment text area to open the submit review dialog directly.

      +

      Alex: First, look for the Finish your review button in the top-right area of the Files Changed tab (it shows the number of pending comments). Then, click it - a popover appears with a summary text area and three radio buttons: Comment, Approve, Request changes. After that, optionally type a summary comment. Finally, select your verdict by clicking the radio button. The rhythm is simple: orient, act, verify, then continue.

      +

      Jamie: Before we leave Completing and submitting a review, what is the practical point?

      +

      Alex: First, click Submit review. Then, press 1 to go to the h1 (PR title). After that, press B (or Tab) to navigate to the "Submit review" button and activate it (Enter/Space). Finally, a "Submit review" dialog/panel appears. Think of it as a rail line: each stop confirms you are still on the right route before the next one.

      +

      Alex: Treat examples as spoken recipes, not decorations. You may hear something like View the PR diff in your terminal; gh pr diff 42; Approve a PR; gh pr review 42 --approve; Approve with a comment; gh pr review 42 --approve --body "Looks good - heading hierarchy is correct."; Request changes; gh pr review 42 --request-changes --body "The alt. Read the command, understand what it changes, then run it only when the repository state matches the lesson.

      +

      Alex: Keep the teaching thread moving. Start with GitHub shortcuts for pull requests: These are the GitHub built-in shortcuts for PR pages. The next useful detail is this: Enable Focus Mode first (NVDA: NVDA+Space, JAWS: Insert+Z) before using single-key shortcuts. Think of it like entering a new building: first you find the lobby, then the room, then the door you actually need.

      -

      Alex: Keep the teaching thread moving. The reason Step 1: Gather Your Data matters is that before writing your reflection, collect all the information you gathered. That gives the learner a simple foothold: write these down (in a text editor, on paper, or mentally) - you'll reference them in Steps 2-4.

      -

      Alex: The practical takeaway is this. Which line number had the heading hierarchy skip? Which line number had the link text issue? How many steps did it take to find each issue? Did you use screen reader commands or visual scanning more?

      -

      Jamie: Let's pause on Step 2: Navigate to the PR and Leave Your Reflection Comment. What should a learner take away from it?

      -

      Alex: Start with Step 2: Navigate to the PR and Leave Your Reflection Comment. There is something to understand, something to try, and something that proves the try worked.

      -

      Alex: The practical takeaway is this. A text editing area with formatting options (Bold, Italic, Link, etc.). A Comment button below the text area.

      -

      Alex: First, go to GitHub in your browser. Then, open the same PR ("Add screen reader tips to the setup guide"). After that, scroll to the Conversation tab. Finally, scroll all the way down to the comment box at the bottom (labeled "Leave a comment" or "Add a comment"). Think of it as a rail line: each stop confirms you are still on the right route before the next one.

      -

      Jamie: Before we leave Step 2: Navigate to the PR and Leave Your Reflection Comment, what is the practical point?

      -

      Alex: First, click in the comment box. Treat it like a recipe: do not add the next ingredient until the previous one is actually in the bowl.

      -

      Alex: Keep the teaching thread moving. Here is the plain-English version of Step 3: Write Your Comparison. Type your response to these three questions. Put another way, be specific - reference exact tools, steps, and what you discovered. It is like learning a transit route. The names of the stops matter because they tell you whether you are still going the right direction.

      +

      Jamie: Let's pause on On the PR list page. What should a learner take away from it?

      +

      Alex: Here is the plain-English version of On the PR list page. Shortcut note: For G P, press G, release it, then press P (two sequential key presses, not simultaneous).

      +

      Alex: Keep the teaching thread moving. This is where On the Files Changed tab becomes real: for the full shortcut system, see Screen Reader Cheat Sheet - GitHub Shortcuts section.

      +

      Jamie: Let's pause on Learning Cards: Submitting a Review. What should a learner take away from it?

      +

      Alex: Start with Learning Cards: Submitting a Review. There is something to understand, something to try, and something that proves the try worked.

      +

      Alex: The practical takeaway is this. The review verdict controls are inside a popover triggered by the "Finish your review" button; press 1 to return to the h1 (PR title), then B or Tab forward to find the button -- it is easy to miss because it is not a landmark. Inside the popover, Tab past the summary text area to reach a radio group labeled "Review Event"; use Up/Down Arrow to switch between Comment, Approve, and Request Changes. Shortcut: press Ctrl+Shift+Enter from any review comment text area to open the submit review dialog directly, bypassing the search for the button. The "Finish your review" button sits in the top-right corner of the Files Changed tab with a small badge showing your pending comment count; at 200%+ zoom it may scroll off-screen to the right. Inside the submit popover, the three radio buttons (Comment, Approve, Request changes) are small standard HTML radios; zoom in on the popover area or use Tab to step between them. After submitting, your review verdict appears as a colored banner in the Conversation timeline: green for Approve, red for Request Changes, grey for Comment.

      -

      Jamie: Let's pause on Step 4: Review Your Comment. What should a learner take away from it?

      -

      Alex: Start with Step 4: Review Your Comment. There is something to understand, something to try, and something that proves the try worked.

      -

      Alex: The practical takeaway is this. Is it clear which tool I preferred? Did I explain why with concrete examples? Am I describing the real-world impact accurately? Would someone else reading this understand how I caught the issue?

      -

      Alex: First, before submitting, re-read your comment using your screen reader or by reading aloud. Then, ask yourself. After that, make any corrections needed. Finally, do not submit yet - continue to Step 5. It is a checklist, but a meaningful one: every item creates evidence that the next step is safe.

      -

      Jamie: Let's pause on Step 5: Submit Your Reflection. What should a learner take away from it?

      -

      Alex: Start with Step 5: Submit Your Reflection. There is something to understand, something to try, and something that proves the try worked.

      -

      Alex: The practical takeaway is this. Your comment is now visible on the PR. Other reviewers can see your comparison. You have completed the three-part exercise series. Your comment appears on the PR thread. It includes all three reflections. The PR author and other reviewers can see your thought process.

      -

      Alex: First, locate the Comment button at the bottom right of the comment box. Then, with keyboard: Press Tab until the Comment button is focused, then Enter. After that, with mouse: Click the Comment button. Finally, your comment is submitted and appears on the PR page. It is like walking a hallway with named doors: read the sign, enter the right room, then confirm where you landed.

      -

      Jamie: Let's pause on Step 6: Checkpoint - Validate Your Learning. What should a learner take away from it?

      -

      Alex: The reason Step 6: Checkpoint - Validate Your Learning matters is that before moving forward, verify you understand. That gives the learner a simple foothold: if you can answer all three, you're ready for the next chapter.

      -

      Alex: The practical takeaway is this. Expected answer: Something like "Screen readers let users navigate by heading level (pressing 3 jumps to H3), so skipping a level makes users think content is missing.". Expected answer: e.g., "Browser: finding context in discussions. VS Code: linear reading of changes.". Expected answer: Something like "Open the document in a browser, use screen reader heading navigation, and confirm I can reach all levels (H2, H3, H4).".

      -

      Alex: First, heading Hierarchy: Can you explain in one sentence why a → skip breaks screen reader navigation? Then, tool Strengths: For each tool you used, name one task it made easier. After that, real-World Testing: How would you test the heading issue in the published document (not the PR diff)? The rhythm is simple: orient, act, verify, then continue.

      +

      Alex: Keep the teaching thread moving. The reason Suggested Changes matters is that a suggested change is a special form of inline review comment where the reviewer proposes exact replacement text. That gives the learner a simple foothold: the PR author can apply the suggestion directly from GitHub - no copy-paste or separate commit needed. The interface gets friendlier when it stops being a wall of controls and starts being a set of named places.

      +

      Jamie: Let's pause on As a reviewer - inserting a suggestion. What should a learner take away from it?

      +

      Alex: Start with As a reviewer - inserting a suggestion: The suggestion block is plain Markdown text in the comment editor. The next useful detail is this: (Three backticks, the word suggestion, Enter, your text, Enter, three backticks.).

      +

      Alex: First, on the Files Changed tab, navigate to the line you want to propose a change. Then, activate the line comment button for that line (the + that appears on hover, or Tab to navigate to it). After that, in the comment text area that opens, press Ctrl+G (Windows) or Cmd+G (Mac). Finally, GitHub wraps a suggestion block around the current line content. Think of it as a rail line: each stop confirms you are still on the right route before the next one.

      +

      Jamie: Before we leave As a reviewer - inserting a suggestion, what is the practical point?

      +

      Alex: First, edit the text inside the suggestion block to show your proposed change. Then, add context above the block if helpful: "This makes the alt text more descriptive:". After that, submit as part of your review ("Start a review" → batch with other comments). Treat it like a recipe: do not add the next ingredient until the previous one is actually in the bowl.

      +

      Jamie: Let's pause on As an author - applying a suggestion. What should a learner take away from it?

      +

      Alex: Start with As an author - applying a suggestion. There is something to understand, something to try, and something that proves the try worked.

      +

      Alex: First, open the PR Conversation or Files Changed tab. Then, navigate to the inline comment containing a suggestion (it shows a diff-style preview). After that, find and activate the "Apply suggestion" button below the suggestion block. Finally, GitHub creates a commit automatically that applies the change - no file editing required. Treat it like a recipe: do not add the next ingredient until the previous one is actually in the bowl.

      +

      Jamie: Before we leave As an author - applying a suggestion, what is the practical point?

      +

      Alex: First, the conversation thread is marked as resolved. It is a checklist, but a meaningful one: every item creates evidence that the next step is safe.

      -

      Alex: Keep the teaching thread moving. Start with Using GitHub Copilot to Understand Code Changes: Reviewing code is about understanding what changed, why it changed, and whether the change is safe and correct. The next useful detail is this: GitHub Copilot can help you gather and understand information about code changes - especially when diffs are large, complex, or involve unfamiliar frameworks. Think of it like entering a new building: first you find the lobby, then the room, then the door you actually need.

      -

      Jamie: Let's pause on When to Use Copilot During Code Review. What should a learner take away from it?

      -

      Alex: Here is the plain-English version of When to Use Copilot During Code Review. Copilot is most useful for answering these questions.

      -

      Alex: First, "What does this code do?" - you're reading unfamiliar syntax or a framework you don't know well. Then, "Why might this change break something?" - you need to understand dependencies or side effects. After that, "Is this pattern safe?" - you want to verify that the approach follows best practices. Finally, "What would be a better way to write this?" - you're looking for alternatives to suggest. Treat it like a recipe: do not add the next ingredient until the previous one is actually in the bowl.

      -

      Jamie: Before we leave When to Use Copilot During Code Review, what is the practical point?

      -

      Alex: First, "Does this match the PR's description?" - the change seems to do more (or less) than claimed. It is a checklist, but a meaningful one: every item creates evidence that the next step is safe.

      -

      Jamie: Let's pause on In VS Code with an Open Diff. What should a learner take away from it?

      -

      Alex: Start with In VS Code with an Open Diff. There is something to understand, something to try, and something that proves the try worked.

      -

      Alex: First, open the PR using the GitHub Pull Requests extension (see Part 2). Then, open the diff for any file. After that, select a block of code that confuses you (highlight it). Finally, open Copilot Chat: Ctrl+Shift+I. It is a checklist, but a meaningful one: every item creates evidence that the next step is safe.

      -

      Jamie: Before we leave In VS Code with an Open Diff, what is the practical point?

      -

      Alex: First, Copilot reads the selected code and answers in the chat. It is like walking a hallway with named doors: read the sign, enter the right room, then confirm where you landed.

      +

      Jamie: Let's pause on Batching multiple suggestions into one commit. What should a learner take away from it?

      +

      Alex: Start with Batching multiple suggestions into one commit. There is something to understand, something to try, and something that proves the try worked.

      +

      Alex: First, for each suggestion you want to apply, activate "Add suggestion to batch" instead of "Apply suggestion". Then, after selecting all suggestions, activate the "Commit suggestions" button that appears at the top. After that, GitHub applies all batched suggestions in a single commit. It is a checklist, but a meaningful one: every item creates evidence that the next step is safe.

      +

      Jamie: Let's pause on When to use suggestions vs. comments. What should a learner take away from it?

      +

      Alex: Start with When to use suggestions vs. comments. There is something to understand, something to try, and something that proves the try worked.

      +

      Alex: The practical takeaway is this. Use a suggestion when you know the exact text that would fix the issue. Use a plain comment when the change requires judgment from the author (e.g., "this alt text isn't descriptive - can you describe what the image shows?"). A summary text area for overall comments. Radio buttons for Comment / Approve / Request changes.

      +

      Alex: First, after adding all your inline comments, navigate to the review summary button. Then, on Files Changed tab: find the "Review changes" button (B to navigate buttons). After that, press Enter to open the review dialog. Finally, a panel opens. It is like walking a hallway with named doors: read the sign, enter the right room, then confirm where you landed.

      +

      Jamie: Before we leave When to use suggestions vs. comments, what is the practical point?

      +

      Alex: First, switch to Focus Mode → type your summary comment. Then, navigate to the radio buttons with arrow keys → select your verdict. After that, tab to "Submit review" button → Enter. The rhythm is simple: orient, act, verify, then continue.

      +

      Jamie: Let's pause on Learning Cards: Suggested Changes. What should a learner take away from it?

      +

      Alex: Start with Learning Cards: Suggested Changes. There is something to understand, something to try, and something that proves the try worked.

      +

      Alex: The practical takeaway is this. To insert a suggestion block, press Ctrl+G (Windows) or Cmd+G (Mac) in the comment text area; the screen reader announces the inserted fence -- arrow down to edit the text between the backtick lines. Alternatively type the block manually: three backticks, the word suggestion, Enter, your replacement text, Enter, three backticks -- this avoids relying on the keyboard shortcut. As a PR author, navigate to a suggestion comment with 3, then Tab to the "Apply suggestion" button; GitHub commits the change automatically with no file editing required. Suggestion blocks render as a mini inline diff: the original line in red/pink background and your proposed replacement in green background; in high-contrast mode these use system diff colors. The "Apply suggestion" button is small and sits below the suggestion diff preview; zoom into the comment area to find it, or Tab from the suggestion text to reach it. When batching multiple suggestions, a floating "Commit suggestions" bar appears at the top of the page; at high zoom scroll up or press Home to find it.

      -

      Jamie: Let's pause on On GitHub.com (Web Interface). What should a learner take away from it?

      -

      Alex: Keep the learner anchored in On GitHub.com (Web Interface). Another option: Use the GitHub Copilot inline suggestions on GitHub.com.

      -

      Alex: The practical takeaway is this. Some GitHub PRs show Copilot insights directly in the diff (as of early 2026). If you see a lightbulb icon, click it to see Copilot's suggestion about that line.

      -

      Alex: First, open the PR's Files Changed tab. Then, focus on a line or section you want to understand better. After that, in VS Code Copilot Chat (not in the browser - Copilot Chat doesn't work directly in browser diffs yet). Finally, copy the confusing code, paste it into chat, and ask Copilot to explain. It is like walking a hallway with named doors: read the sign, enter the right room, then confirm where you landed.

      -

      Alex: Keep the teaching thread moving. The reason Copilot Limitations During Review (Critical to Know) matters is that this is why manual review is essential: You have context (project history, team decisions, user impact) that Copilot does not. That gives the learner a simple foothold: use Copilot to understand, then use your judgment to decide. The interface gets friendlier when it stops being a wall of controls and starts being a set of named places.

      -

      Alex: The practical takeaway is this. See the whole project - it sees only what you show it (the selected diff, not the context of the entire codebase). Verify correctness - it can explain what code does, but not whether it's correct for your specific use case. Understand intent - it reads the code, not the author's mind or the PR description. Catch all risks - it can spot common patterns, but not edge cases unique to your project.

      -

      Jamie: Let's pause on Best Practices. What should a learner take away from it?

      -

      Alex: Start with Best Practices. There is something to understand, something to try, and something that proves the try worked.

      -

      Alex: First, read the diff manually first - you spot the big picture before asking Copilot details. Then, ask Copilot specific questions - not "review this code" but "does this regex handle Unicode?". After that, fact-check Copilot's answers - it can be confidently wrong, especially about frameworks or domains it has less training data. Finally, combine Copilot with manual analysis - ask Copilot to explain, then verify by checking the PR description or looking for related files. Think of it as a rail line: each stop confirms you are still on the right route before the next one.

      -

      Jamie: Before we leave Best Practices, what is the practical point?

      -

      Alex: First, use Copilot to draft comments - type Draft a comment about [issue] for this PR and edit Copilot's suggestion to match your tone. Treat it like a recipe: do not add the next ingredient until the previous one is actually in the bowl.

      +

      Jamie: Let's pause on Understanding Merge Options (for Maintainers). What should a learner take away from it?

      +

      Alex: Start with Understanding Merge Options (for Maintainers): When a PR is approved and checks pass, a maintainer can merge it. The next useful detail is this: The merge button section appears at the bottom of the Conversation tab.

      +

      Alex: Treat examples as spoken recipes, not decorations. You may hear something like Merge with default strategy (merge commit); gh pr merge 42; Squash and merge; gh pr merge 42 --squash; Rebase and merge; gh pr merge 42 --rebase; Delete the branch after merging; gh pr merge 42 --squash --delete-branch; Enable auto-merge (merges when checks. Read the command, understand what it changes, then run it only when the repository state matches the lesson.

      +

      Jamie: Let's pause on After a PR is merged. What should a learner take away from it?

      +

      Alex: Here is the plain-English version of After a PR is merged. for screen reader users, - deleting the branch after merge: Navigate to the "Add a comment" section (D), then press Shift+B to navigate backwards to the "Delete branch" button and activate it. Put another way, this keeps your repository clean by removing the now-merged feature branch.

      +

      Alex: The practical takeaway is this. The PR status badge changes to "Merged" (purple). The source branch can be deleted - a "Delete branch" button appears. Any linked issues with Closes N in the description are automatically closed.

      +

      Alex: Keep the teaching thread moving. This is where Auto-Merge - Merging When You Can't Wait Around becomes real: auto-merge lets you pre-authorize a PR to merge automatically the moment all branch protection requirements are satisfied - required reviews approved, all status checks passing, and the branch up to date. The workshop is closer to rehearsal than lecture. You hear the move, try the move, and then check what changed.

      +

      Alex: The practical takeaway is this. You've addressed all review comments and are waiting for CI to finish. A maintainer has approved the PR but a required check is still running. You're in a different time zone from the reviewers.

      -

      Alex: Keep the teaching thread moving. Here is the plain-English version of What Comes Next. Your manual code review skills - identifying heading issues, catching link text problems, understanding screen reader navigation, gathering information with Copilot - are the foundation for understanding automated review. Put another way, in Chapter 16 (Accessibility Agents), you'll meet a full team of agents designed to amplify these skills.

      -

      Jamie: Let's pause on Part 4: The Reviewer's Craft. What should a learner take away from it?

      -

      Alex: This is where The Reviewer's Craft becomes real: parts 1 through 3 taught you the mechanics -- how to read diffs, leave comments, and use Copilot to understand unfamiliar code. That matters in practice: This part covers something equally important: how to think like a reviewer.

      -

      Alex: Keep the teaching thread moving. Keep the learner anchored in What to Look for in a Review. Every PR is different, but most reviews benefit from scanning across these five categories. This is the part to say slowly: You do not need to check every category exhaustively on every PR. A good GitHub workflow is like a well-run meeting: everyone knows the topic, the next action, and who has the floor.

      +

      Jamie: Let's pause on What happens next. What should a learner take away from it?

      +

      Alex: Start with What happens next. There is something to understand, something to try, and something that proves the try worked.

      +

      Alex: The practical takeaway is this. The PR merge box changes to show "Auto-merge enabled - merge will happen automatically". When the last required check passes (or last required review arrives), GitHub merges the PR silently. You receive a notification: "Your PR was automatically merged". If a reviewer requests changes after auto-merge is enabled, auto-merge is automatically cancelled (a new approval is required before it re-enables).

      +

      Jamie: Let's pause on Cancelling Auto-Merge. What should a learner take away from it?

      +

      Alex: The reason Cancelling Auto-Merge matters is that auto-merge is only available if the repository administrator has enabled it in Settings → General. That gives the learner a simple foothold: many open source repos have it on; some do not.

      +

      Alex: Treat examples as spoken recipes, not decorations. You may hear something like Merge box → Tab → "Disable auto-merge" button → Enter. Read the command, understand what it changes, then run it only when the repository state matches the lesson.

      +

      Jamie: Let's pause on Scenario A: "I want to review an assigned PR". What should a learner take away from it?

      +

      Alex: Start with Scenario A: "I want to review an assigned PR": Example: You are assigned to review a PR titled "Add missing NVDA shortcut to keyboard-shortcuts.md." The PR modifies docs/keyboard-shortcuts.md in the Learning Room repository and references Challenge 2.

      -

      Jamie: Let's pause on The Three Review Actions. What should a learner take away from it?

      -

      Alex: The reason The Three Review Actions matters is that when you submit a review on GitHub, you choose one of three actions. That gives the learner a simple foothold: picking the right one matters because it signals your intent to the author and to anyone else watching the PR.

      -

      Alex: First, did you find a bug, security issue, or broken test? -- Request Changes. Then, does the code do something different from what the description says? -- Request Changes. After that, does everything work, with maybe a few style nits? -- Approve (mention the nits in a comment). Finally, do you have questions or optional suggestions? -- Comment. The rhythm is simple: orient, act, verify, then continue.

      -

      Alex: Keep the teaching thread moving. Start with Writing Constructive Feedback: The way you phrase feedback determines whether the author feels supported or attacked. The next useful detail is this: Before pointing out problems, acknowledge something the author did well.

      -

      Jamie: Let's pause on The Reviewer's Checklist. What should a learner take away from it?

      -

      Alex: Here is the plain-English version of The Reviewer's Checklist. Run through this list mentally (or copy it into your notes) for every PR you review.

      -

      Alex: The practical takeaway is this. [ ] I read the PR description before reading the code. [ ] The code does what the description says it does. [ ] The change does not include unrelated modifications. [ ] Variable and function names are clear. [ ] I checked for accessibility: labels, headings, keyboard reach, contrast. [ ] I verified no existing behavior is broken by the change.

      +

      Alex: Keep the teaching thread moving. Here is the plain-English version of Scenario B: "I want to respond to review feedback on my PR". Example: Your PR for Challenge 3 (Complete Welcome Guide) received a review comment: "The [TODO] about evaluating issues is good, but the paragraph could mention checking if the issue is already assigned." The validation bot also flagged a link text issue. It is like learning a transit route. The names of the stops matter because they tell you whether you are still going the right direction.

      +

      Jamie: Let's pause on Writing PR Descriptions That Get Reviewed. What should a learner take away from it?

      +

      Alex: This is where Writing PR Descriptions That Get Reviewed becomes real: see also: Appendix C: Markdown Reference for formatting your PR description with headings, lists, and task lists. That matters in practice: A pull request is only as useful as its description.

      +

      Jamie: Let's pause on What Reviewers Look For. What should a learner take away from it?

      +

      Alex: Keep the learner anchored in What Reviewers Look For. When a reviewer opens your PR, they are asking four questions before they ever look at the diff. This is the part to say slowly: If your description answers all four, the reviewer can jump straight into the code with context.

      +

      Alex: First, why does this change exist? -- What problem does it solve, or what goal does it advance? Then, what is the scope? -- Which files changed, and roughly how big is the change? After that, how was it tested? -- Did you verify that the change works, and how? Finally, what should I pay attention to? -- Are there tricky parts, trade-offs, or areas where you want a second opinion? It is like walking a hallway with named doors: read the sign, enter the right room, then confirm where you landed.

      -

      Alex: Keep the teaching thread moving. This is where Reviewing as a Learning Tool becomes real: reviewing is not just a gate to keep bad code out. That matters in practice: It is one of the fastest ways to grow as a developer. The workshop is closer to rehearsal than lecture. You hear the move, try the move, and then check what changed.

      -

      Jamie: Let's pause on Learning Cards: The Reviewer's Craft. What should a learner take away from it?

      -

      Alex: Start with Learning Cards: The Reviewer's Craft. There is something to understand, something to try, and something that proves the try worked.

      -

      Alex: The practical takeaway is this. Jump between changed hunks in a diff with Alt+F5 (next change) and Shift+Alt+F5 (previous change) to scan for scope creep efficiently. Use Alt+F2 (Accessible View) on a Copilot-generated review summary to read the full text with arrow keys before posting. When leaving feedback, mention specific line numbers ("Line 42 skips from h2 to h4") so the author can navigate directly with Ctrl+G. The three review actions (Approve, Request Changes, Comment) are shown as clearly labeled radio buttons in the review submission form. Use the reviewer checklist in this section as a mental framework -- copy it into your notes and check items off as you review each PR. The diff view uses green and red backgrounds for added/removed lines; pair with a High Contrast theme if these colors are hard to distinguish.

      -

      Alex: Keep the teaching thread moving. The reason Day 2 Teaser: The Full Accessibility Agents Review Ecosystem matters is that chapter 16 shows you how to leverage 50+ specialized agents to make your reviews faster, more consistent, and more thorough - while staying in full control of what you post.

      +

      Jamie: Let's pause on The Closes XX Pattern. What should a learner take away from it?

      +

      Alex: The reason The Closes XX Pattern matters is that GitHub recognizes special keywords in PR descriptions that automatically close linked issues when the PR merges. That gives the learner a simple foothold: you do not need to close issues by hand -- just include the right keyword followed by the issue number.

      +

      Alex: Keep the teaching thread moving. Start with Before/After Structure: One of the most effective patterns for PR descriptions is showing the state before your change and the state after. The next useful detail is this: This gives the reviewer an instant mental model of what changed without reading the diff line by line. Think of it like entering a new building: first you find the lobby, then the room, then the door you actually need.

      +

      Jamie: Let's pause on A PR Description Template. What should a learner take away from it?

      +

      Alex: Here is the plain-English version of A PR Description Template. Here is a template you can copy into your PR descriptions. Put another way, not every section applies to every PR, but filling in even a few sentences per section makes a meaningful difference.

      -

      Jamie: What do you want them to do when the plan breaks?

      -

      Alex: Start with The Agents That Help With Code Review: Accessibility Review Agents (when code affects UI/UX).

      -

      Alex: The practical takeaway is this. @pr-review - Generates a full-draft PR review with line-numbered diff maps, risk assessment, before/after snapshots, and suggested inline comments. You edit and post it under your name. @pr-author-checklist - Before you even submit your PR, use this to verify you haven't missed setup steps, accessibility checks, or documentation. @insiders-a11y-tracker - Monitors your PR for accessibility-sensitive changes: WCAG violations, heading hierarchy issues, link text quality, keyboard navigation impacts. @developer-hub - Orchestrates explanations for unfamiliar code, patterns, or frameworks you're reviewing. @python-specialist - If your PR contains Python code, this agent explains patterns, spots accessibility issues, and suggests improvements. @wxpython-specialist - For desktop GUI code, helps verify accessible widget patterns and focus management.

      -

      Jamie: Let's pause on How It Works. What should a learner take away from it?

      -

      Alex: Start with How It Works. There is something to understand, something to try, and something that proves the try worked.

      -

      Alex: First, review manually first (you just did this with Exercises A, B, C). Then, run an agent - @pr-review review PR 14 generates a draft in seconds. After that, edit the agent's draft - you add context, remove noise, correct errors. Finally, post your review - it now has both AI efficiency and your human judgment. Treat it like a recipe: do not add the next ingredient until the previous one is actually in the bowl.

      -

      Jamie: Before we leave How It Works, what is the practical point?

      -

      Alex: First, the agent tracks impact - @insiders-a11y-tracker monitors whether your accessibility feedback was addressed. It is a checklist, but a meaningful one: every item creates evidence that the next step is safe.

      -

      Jamie: Let's pause on The Principle: Skill First, Agent Second. What should a learner take away from it?

      -

      Alex: This is where The Principle: Skill First, Agent Second becomes real: why do this manually before using agents? That matters in practice: Manual reviews teach you what to look for.

      -

      Alex: The practical takeaway is this. You understand what the agent is doing (you did it manually). You evaluate the agent's output critically (you know what right looks like). You add judgment the agent lacks (context, intent, team decisions). You verify the agent didn't miss anything important.

      +

      Alex: Keep the teaching thread moving. This is where Common Description Mistakes becomes real: even experienced contributors make these mistakes. That matters in practice: Knowing what to avoid is half the battle.

      +

      Jamie: Let's pause on Good vs. Bad: Side by Side. What should a learner take away from it?

      +

      Alex: Keep the learner anchored in Good vs. Bad: Side by Side. No context, no linked issue, no explanation of what file or what was wrong with it. This is the part to say slowly: A reviewer seeing this has to open the diff, figure out which file changed, read every line, and guess at the intent.

      +

      Alex: Keep the teaching thread moving. Start with Learning Cards: Writing PR Descriptions That Get Reviewed. There is something to understand, something to try, and something that proves the try worked.

      +

      Alex: The practical takeaway is this. Use Markdown headings ( ) in your description (Summary, Changes, Related Issues, Testing) so reviewers can press H to jump between sections. Type Closes followed by the issue number to auto-close the linked issue on merge; GitHub autocompletes when you type. Press Ctrl+Shift+P in the description text area to toggle between Write and Preview modes; Preview renders your Markdown so you can check structure before submitting. Use the Preview tab to verify your Markdown renders correctly; headings, bullet lists, and code blocks are easier to proofread in rendered form. Keep bullet points short (one line each) so the description is scannable at high zoom without excessive horizontal scrolling. When including screenshots, add alt text in the Markdown image syntax: so every reader gets the same information.

      -

      Jamie: Let's pause on A Real Example: The Flow. What should a learner take away from it?

      -

      Alex: Keep the learner anchored in A Real Example: The Flow. Manual Review (your work in part 1-2). This is the part to say slowly: Agent-Assisted Review (what you'll do in Chapter 19).

      -

      Alex: The practical takeaway is this. Read diff, identify heading hierarchy skip. Write comment explaining why it matters. Submit your verdict.

      -

      Alex: First, run: @pr-review review PR 14. Then, agent generates a draft review covering the heading skip, link text, and 5 other issues. After that, you read the draft and notice: "the agent's explanation of the heading skip is good, but it missed that the link text on line 23 is still vague. Let me add that.". Finally, you post the agent's review + your additions. It is like walking a hallway with named doors: read the sign, enter the right room, then confirm where you landed.

      -

      Jamie: Before we leave A Real Example: The Flow, what is the practical point?

      -

      Alex: First, next time you review a similar PR, the agent works faster because it learned from your feedback. The rhythm is simple: orient, act, verify, then continue.

      +

      Jamie: Let's pause on Try It: Read a Real Pull Request. What should a learner take away from it?

      +

      Alex: Start with Try It: Read a Real Pull Request: Time: 3 minutes What you need: Browser, signed in to GitHub. The next useful detail is this: Go to the Learning Room repository's Pull Requests tab and find any open or recently closed PR.

      +

      Alex: First, navigate to Pull Requests (G then P in Focus Mode). Then, open the first PR in the list (press Enter on its title). After that, read the description - press 2 to jump to the first section heading, then arrow down to read. Look for: which file was changed (docs/welcome.md, docs/keyboard-shortcuts.md, or docs/setup-guide.md)? Which challenge was this PR solving? Does the description. Finally, check the conversation - press 3 to jump between comments. Read what the validation bot reported - did the bot find any accessibility issues like broken headings or non-descriptive links? How did the author respond? Think of it as a rail line: each stop confirms you are still on the right route before the next one.

      +

      Jamie: Before we leave Try It: Read a Real Pull Request, what is the practical point?

      +

      Alex: First, look at the diff - press D to the "Pull request tabs" landmark, then navigate to "Files changed" and press Enter. Press H to scan the changed file headings. If the PR touched docs/welcome.md, you should see + lines where the [TODO] sections were filled in. If. Treat it like a recipe: do not add the next ingredient until the previous one is actually in the bowl.

      -

      Jamie: What should people carry with them after this?

      -

      Alex: Carry the map. Know what page or tool you are in, know which action you are taking, and know what confirmation should follow. If the confirmation is missing, pause. That pause is not wasted time; it is professional judgment.

      -

      Jamie: That is a better way to say it than just follow the steps.

      -

      Alex: Right. Steps matter, but understanding wins. That is episode 15. Next in the series is episode 16, where we keep building the same contributor muscles.

      +

      Jamie: What is the final checkpoint?

      +

      Alex: You should be able to point to the evidence, explain the action, and describe what you would do next if this were a real open source project. If you can teach the move back, you have learned it.

      +

      Jamie: And if they get stuck?

      +

      Alex: Read the latest message, not the loudest worry. Check the issue, the branch, the pull request, the status check, or the bot comment. Then ask for help with those facts in hand. That is how professionals collaborate.

      -

      Episode 16: Issue Templates

      -

      Creating YAML-based issue templates for bug reports, features, and custom forms.

      -

      Based on: Chapter 17: Issue Templates

      +

      18. Challenge 05: Make Your Mark

      +

      Editing a file, writing a useful commit message, and connecting a change to an issue.

      +

      Practice focus: Day 1 contribution

      Audio and transcript are being regenerated for this episode.

      -Read Transcript - Episode 16: Issue Templates +Read Transcript - Challenge 05: Make Your Mark

      Transcript

      -

      Alex: Welcome to Git Going with GitHub, episode 16: Issue Templates. I am Alex. Today we are going to make Issue Templates something you can explain, practice, and recover from when the interface surprises you.

      -

      Jamie: And I am Jamie. I will be the voice of the learner who is willing to ask, what is this for, where am I, and how do I know I did it right?

      -
      -

      Alex: The big idea today: Creating YAML-based issue templates for bug reports, features, and custom forms. We will name the concept, explain why it matters, practice the move, and point out the checks that tell you the work is real.

      -

      Jamie: So the episode should work even if someone has not read the chapter yet.

      -

      Alex: Exactly. The transcript has to stand on its own. It can point toward practice, but it should teach the concept right here in the conversation.

      +

      Alex: This is Challenge Coach for Make Your Mark. I am Alex, and we are going to teach the move before asking you to prove it.

      +

      Jamie: And I am Jamie. I will translate the challenge into the practical questions learners actually have while doing it.

      -

      Jamie: Okay, set the room for us. What are we walking into?

      -

      Alex: Start with Structuring Contributions for Clarity and Quality: Issue templates turn a blank text box into a guided form. The next useful detail is this: They help contributors provide the information maintainers need, reduce back-and-forth, and make every issue immediately actionable.

      -

      Alex: The next layer is this. Here is the plain-English version of Before starting this chapter, verify you have completed. Day 2 Amplifier: In Chapter 19 (Accessibility Agents), you'll use @template-builder to automate template creation. Put another way, complete this chapter first, then come back to Chapter 19. It is like learning a transit route. The names of the stops matter because they tell you whether you are still going the right direction.

      -

      Alex: The practical anchors are these. [ ] Chapter 4: Working with Issues - 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). [ ] Chapter 16: GitHub Copilot - Optional but helpful for generating template variations.

      -

      Jamie: What should feel predictable before the first live session starts?

      -

      Alex: This is where Workshop Recommendation (Chapter 17 / Challenge 14) becomes real: chapter 17 is a template design and implementation chapter focused on structuring contributions with a concrete, familiar example. That matters in practice: It supports Challenge 14: Template Remix.

      -

      Alex: That shows up in the workshop in a few specific ways. There are 2-3 guided challenges (+ 1 optional). Automation check: none (template structure quality is design-focused). The evidence is issue comment or PR with template remixed or created. The pattern is analyze, remix, create, test.

      +

      Alex: Editing a file, writing a useful commit message, and connecting a change to an issue. That is the task layer. The teaching layer is understanding why the move belongs in a contributor workflow.

      +

      Jamie: So evidence is not just proof for the facilitator. It is part of how the learner understands the workflow.

      +

      Alex: Right. A good challenge produces something inspectable: a comment, issue, branch, commit, pull request, review, or clear note about what happened.

      -

      Jamie: Turn that into a path someone can follow.

      -

      Alex: Start with Challenge 14 Set. There is something to understand, something to try, and something that proves the try worked.

      -

      Alex: First, analyze the registration template - understand how the template you already filled out works. Then, remix the registration template - adapt it for a new use case (bug report, event, research). After that, create a Markdown template (optional) - build a Markdown-based template from scratch. Finally, test in the template chooser (optional) - verify your template appears and works. It is like walking a hallway with named doors: read the sign, enter the right room, then confirm where you landed.

      -

      Jamie: What is the ordered workflow?

      -

      Alex: The reason Challenge 14.1 Step-by-Step: Analyze the Registration Template matters is that understand how professional YAML form templates work by examining the one you filled out to register for this workshop. That gives the learner a simple foothold: GitHub.com - reading the template file in the git-going-with-github repository.

      -

      Alex: The parts worth keeping in working memory are these. 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.

      -

      Alex: First, open the template file on GitHub.com (use the link above). Then, read the YAML frontmatter (top 5 lines) and identify. After that, read the field types in the body section. Note the four types used. Finally, for each field, identify the metadata. The rhythm is simple: orient, act, verify, then continue.

      -

      Jamie: Give me the sequence, because order matters here.

      -

      Alex: First, search the file for "accessible" - notice the description mentions that all fields work with screen readers. This is professional template thinking. Then, 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. Think of it as a rail line: each stop confirms you are still on the right route before the next one.

      -

      Alex: The useful habit is simple: orient first, act second, verify third. That pause before acting is part of the work.

      +

      Jamie: What makes this practice feel low-stakes but still real?

      +

      Alex: Start with Challenge 5: Make Your Mark: What you will do: Edit docs/welcome.md on your branch to fix the TODO you found in Challenge 2, then commit with a meaningful message.

      Jamie: How would you walk the room through that step by step?

      -

      Alex: Start with Challenge 14.2 Step-by-Step: Remix the Registration Template: Adapt the registration template for a different use case while keeping the same YAML structure. The next useful detail is this: VS Code with a repository where you have write access (your fork or personal repo), or github.dev. Think of it like entering a new building: first you find the lobby, then the room, then the door you actually need.

      -

      Alex: On the ground, that means a few things. Source.github/ISSUE TEMPLATE/workshop-registration.yml. Remix sample: learning-room/docs/samples/challenge-14-registration-remix-example.yml. Keep: the YAML skeleton (name, description, title, labels, body). Keep: field structure (type, id, attributes, validations).

      -

      Alex: First, pick a new context for your template (for example: bug report, event attendance, product research, accessibility audit request). Then, copy the registration template file to a new file.github/ISSUE TEMPLATE/my-template.yml. After that, change the name and description in the frontmatter to match your new context. Finally, change the title prefix (for example: [Bug Report]: or [Event]: ). Think of it as a rail line: each stop confirms you are still on the right route before the next one.

      +

      Alex: Start with Instructions. There is something to understand, something to try, and something that proves the try worked.

      +

      Alex: First, make sure you are on your learn/YOUR-USERNAME branch (check the branch dropdown). Then, navigate to docs/welcome.md. After that, select the pencil icon (Edit this file) to open the editor. Finally, find the TODO and replace it with real content. Treat it like a recipe: do not add the next ingredient until the previous one is actually in the bowl.

      Jamie: What does the learner do first, second, and then after that?

      -

      Alex: First, change the labels to appropriate labels for your use case. Then, replace each field's label, description, placeholder, and options to match your new context. After that, decide which fields should be required: true and which can be optional. Finally, validate your YAML syntax: copy the file contents to yamllint.com and fix any errors. Treat it like a recipe: do not add the next ingredient until the previous one is actually in the bowl.

      -
      -

      Jamie: Let's pause on Challenge 14.3 (Optional) Step-by-Step: Create a Markdown Template. What should a learner take away from it?

      -

      Alex: Here is the plain-English version of Challenge 14.3 (Optional) Step-by-Step: Create a Markdown Template. Create a Markdown-based template to compare the two template formats. Put another way, VS Code with a repository where you have write access.

      -

      Alex: First, create a new file.github/ISSUE TEMPLATE/my-markdown-template.md. Then, add the Markdown template frontmatter at the top. After that, markdown templates use about instead of description (unlike YAML form templates). Finally, below the frontmatter, add 3-4 sections with HTML comment instructions. Treat it like a recipe: do not add the next ingredient until the previous one is actually in the bowl.

      -

      Jamie: Before we leave Challenge 14.3 (Optional) Step-by-Step: Create a Markdown Template, what is the practical point?

      -

      Alex: First, commit and push. It is a checklist, but a meaningful one: every item creates evidence that the next step is safe.

      -

      Jamie: Let's pause on Challenge 14.4 (Optional): Test in the Template Chooser. What should a learner take away from it?

      -

      Alex: This is where Challenge 14.4 (Optional): Test in the Template Chooser becomes real: you are done when: Your template works and appears in the GitHub template picker.

      -

      Alex: First, navigate to your test repository on GitHub.com. Then, activate New Issue. After that, verify your template appears in the template chooser. Finally, activate Get started on your template and file a test issue. It is a checklist, but a meaningful one: every item creates evidence that the next step is safe.

      -

      Jamie: What makes this practice feel low-stakes but still real?

      -

      Alex: Keep the learner anchored in Completing Challenge 14: Submit Your Evidence. Open your assigned Challenge 14 issue and post a completion comment. This is the part to say slowly: Close your Challenge 14 issue when done.

      -
      -

      Alex: Before the learner moves on. Start with Expected Overall Outcomes. There is something to understand, something to try, and something that proves the try worked.

      -

      Alex: That becomes easier when you listen for these cues. 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.

      -

      Jamie: Let's pause on If You Get Stuck. What should a learner take away from it?

      -

      Alex: Start with If You Get Stuck: Continue learning: The GitHub Skills course Introduction to Repository Management covers templates and contributor settings in an interactive format. The next useful detail is this: See Appendix Z for the full catalog.

      -

      Alex: First, cannot find the registration template? Look in.github/ISSUE TEMPLATE/workshop-registration.yml in the git-going-with-github repository. Then, 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. After that, yAML not parsing? Compare with the remix sample in learning-room/docs/samples/challenge-14-registration-remix-example.yml and check indentation. Finally, 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. Think of it as a rail line: each stop confirms you are still on the right route before the next one.

      -

      Jamie: Before we leave If You Get Stuck, what is the practical point?

      -

      Alex: First, 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. Then, remix approach feels overwhelming? Start by changing just the field labels and descriptions. Do not change the structure yet. After that, ask facilitator to review your template and suggest improvements. Finally, finished but not sure you did it right? Compare your work against the Challenge 14 reference solution. Treat it like a recipe: do not add the next ingredient until the previous one is actually in the bowl.

      -

      Alex: Hold that next to this. Here is the plain-English version of Learning Moment. They do not restrict expert contributors - they guide newcomers. Put another way, a template that takes 2 minutes to understand saves 30 minutes of back-and-forth questions later.

      -
      -

      Jamie: Let's pause on Learning Pattern Used in This Chapter. What should a learner take away from it?

      -

      Alex: Start with Learning Pattern Used in This Chapter. There is something to understand, something to try, and something that proves the try worked.

      -

      Alex: First, analyze an existing, working example before building your own. Then, remix by changing content while keeping structure (safe, fast iteration). After that, create from scratch only after you understand the pattern (Markdown template). Finally, test the result in the real environment (template chooser). It is a checklist, but a meaningful one: every item creates evidence that the next step is safe.

      -

      Alex: That connects to another useful point. Keep the learner anchored in 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. A good GitHub workflow is like a well-run meeting: everyone knows the topic, the next action, and who has the floor.

      -

      Alex: For a learner, the useful signals are these. Instructions explaining what information is needed. Section headers guiding them through the report. Checkboxes for conditions to verify. Placeholder text showing the expected format.

      -

      Alex: A solid issue habit is to read the title, the body, and the timeline before acting. You are listening for the requested action, the missing evidence, and the person who needs a response.

      +

      Alex: First, write a meaningful commit message that explains what you changed and why. Then, commit directly to your branch. It is a checklist, but a meaningful one: every item creates evidence that the next step is safe.

      Jamie: What is the one idea that makes the next few steps less mysterious?

      -

      Alex: The reason Why they matter for accessibility projects matters is that accessibility bugs require specific context that general bug templates often omit. That gives the learner a simple foothold: without this context, maintainers ask follow-up questions - which delays the fix and uses everyone's time.

      -

      Alex: Here is what that changes in practice. Which screen reader and version? Which browser and version? Which operating system? Which WCAG success criterion is affected?

      -

      Alex: A solid pull request habit is to separate three questions: what changed, why it changed, and what still needs review. That keeps the conversation useful instead of noisy.

      +

      Alex: This is where What makes a good commit message? becomes real: a good commit message answers: What did I change and why? That matters in practice: My commit message was: "." I changed the TODO to say.

      +

      Alex: A solid Git habit is to know which branch you are on, what changed, and what confirmation you expect before you run the next command.

      -

      Alex: Here is the practical turn. Start with 2. How Templates Work on GitHub: Templates live in a specific folder in your repository.

      +

      Alex: Now bring the learner back to the room. Keep the learner anchored in Peer simulation check. Compare your commit message with the peer-simulation PR title and commit message. This is the part to say slowly: Can you tell what changed just from reading it?

      Jamie: What would you say to someone who is already bracing for this to be too much?

      -

      Alex: Here is the plain-English version of Description. Templates live inside your-repo/.github/. Put another way, 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).

      -

      Alex: Keep the thread going. This is where Example config.yml becomes real: with blank issues enabled: false, the "Open a blank issue" link disappears from the template chooser. That matters in practice: Contributors must use one of your structured templates or one of the contact links. The workshop is closer to rehearsal than lecture. You hear the move, try the move, and then check what changed.

      +

      Alex: Start with What makes a good commit message. There is something to understand, something to try, and something that proves the try worked.

      +

      Alex: The parts worth keeping in working memory are these. First line: Short summary (50 characters or less is ideal), starts with the type of change. Blank line: Separates summary from body. Body (optional): Explains what changed and why.

      +

      Alex: That matters because of the next idea. Start with Simpler alternatives that are also fine: The more structured format is a convention, not a requirement. Think of it like entering a new building: first you find the lobby, then the room, then the door you actually need.

      +

      Alex: The useful habit is simple: orient first, act second, verify third. That pause before acting is part of the work.

      -

      Jamie: If I am listening before the workshop starts, what should settle in my mind first?

      -

      Alex: Start with Learning Cards: How Templates Work on GitHub. There is something to understand, something to try, and something that proves the try worked.

      -

      Alex: These are the details that keep the idea from floating away. 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. 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.

      -

      Jamie: Let's pause on 3. Navigating the Template Picker. What should a learner take away from it?

      -

      Alex: The reason 3. Navigating the Template Picker matters is that when a repository has multiple templates, GitHub shows a template chooser page before the issue editor. That gives the learner a simple foothold: screen reader users - NVDA / JAWS (Windows).

      -

      Alex: First, click the Issues tab on any repository. Then, click the New issue button. After that, the template chooser page loads - templates appear as cards with a title, description, and "Get started" button. Finally, click "Get started" on the template you want. The rhythm is simple: orient, act, verify, then continue.

      -

      Jamie: Before we leave 3. Navigating the Template Picker, what is the practical point?

      -

      Alex: First, the issue editor opens with that template's content pre-filled. Then, navigate to the Issues tab (press T from the repository tabs landmark). After that, activate "New issue" button. Finally, the template chooser page loads. Think of it as a rail line: each stop confirms you are still on the right route before the next one.

      +

      Jamie: Okay, set the room for us. What are we walking into?

      +

      Alex: Start with Alternate approaches. There is something to understand, something to try, and something that proves the try worked.

      +

      Alex: Here is what that changes in practice. github.com: Click the pencil icon on the file, make the edit, fill in the commit message at the bottom. github.dev: Press. to open the editor, edit the file, use the Source Control sidebar to commit. VS Code: Edit locally, stage with git add, commit with git commit. GitHub Desktop: Edit in your preferred editor, return to Desktop, write the message, click Commit.

      +

      Alex: A solid pull request habit is to separate three questions: what changed, why it changed, and what still needs review. That keeps the conversation useful instead of noisy.

      +

      Alex: This is where the talk moves from concept to action. This is where What matters becomes real: the learning objective is making a meaningful change and describing it in a commit message. That matters in practice: Any clear edit with any descriptive message is a success.

      Jamie: Where do you want a learner to place their attention here?

      -

      Alex: Start with Bypassing the Chooser: If you want to file an issue without using a template.

      -

      Alex: A few details make that real. Scroll past all templates to the bottom of the chooser page. Activate "Open a blank issue".

      -
      -

      Alex: This is the part worth saying out loud. Start with Learning Cards: Navigating the Template Picker. There is something to understand, something to try, and something that proves the try worked.

      -

      Alex: The room should hear these as checkpoints. 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. 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.

      -

      Jamie: Let's pause on 4. The Accessibility Agents Issue Templates. What should a learner take away from it?

      -

      Alex: This is where 4. The Accessibility Agents Issue Templates becomes real: accessibility Agents uses templates to structure contributions. That matters in practice: Navigate to.github/ISSUE TEMPLATE/ in the repository to read them.

      -

      Alex: First, click the Code tab on the repository. Then, click the.github folder in the file listing. After that, click ISSUE TEMPLATE. Finally, you'll see the template files - click any to read it. It is a checklist, but a meaningful one: every item creates evidence that the next step is safe.

      -

      Jamie: Before we leave 4. The Accessibility Agents Issue Templates, what is the practical point?

      -

      Alex: First, open the Code tab. Then, use Ctrl+Alt+Down/Up (NVDA/JAWS) or VO+Arrow (VoiceOver) in the files table to reach the.github folder. After that, activate the folder. Finally, activate ISSUE TEMPLATE. It is like walking a hallway with named doors: read the sign, enter the right room, then confirm where you landed.

      -

      Alex: Now bring the learner back to the room. Keep the learner anchored in 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").

      -

      Alex: The practical takeaway is this. Frontmatter (between --- delimiters): name, about, title, labels, assignees.

      +

      Alex: Keep the learner anchored in What Is the Learning Room? The Learning Room is your own private GitHub repository for the workshop. This is the part to say slowly: When you accept the GitHub Classroom assignment in Block 0, GitHub copies the Community-Access/learning-room-template repository into the workshop classroom organization as the workshop organization/learning-room-your username.

      +

      Alex: Before the learner moves on. The reason Why a Per-Student Repo? matters is that GitHub Classroom gives each participant their own repository for three reasons. That gives the learner a simple foothold: 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 interface gets friendlier when it stops being a wall of controls and starts being a set of named places.

      +

      Alex: That becomes easier when you listen for these cues. 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.

      Jamie: Give me the version that sounds like an instructor, not a manual.

      -

      Alex: The reason Example frontmatter matters is that the about text appears in the template chooser. That gives the learner a simple foothold: the title pre-fills the issue title field (the contributor replaces the placeholder).

      -

      Jamie: Let's pause on Tool Cards: Create an Issue Template. What should a learner take away from it?

      -

      Alex: Start with Tool Cards: Create an Issue Template. There is something to understand, something to try, and something that proves the try worked.

      -

      Alex: First, go to Settings General (scroll to Features section) Set up templates. Then, choose a starter template or create a blank one. After that, edit the template content and click Propose changes to commit. Finally, create the file.github/ISSUE TEMPLATE/your-template.md (or.yml for form-based). Think of it as a rail line: each stop confirms you are still on the right route before the next one.

      -

      Jamie: Before we leave Tool Cards: Create an Issue Template, what is the practical point?

      -

      Alex: First, add YAML frontmatter (name, description, title, labels) and body content. Then, commit and push. Treat it like a recipe: do not add the next ingredient until the previous one is actually in the bowl.

      -

      Alex: Treat examples as spoken recipes, not decorations. You may hear something like 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. Read the command, understand what it changes, then run it only when the repository state matches the lesson.

      -

      Jamie: Let's pause on Choosing Between Markdown and YAML Templates. What should a learner take away from it?

      -

      Alex: Here is the plain-English version of Choosing Between Markdown and YAML Templates. See also: Appendix Q: GitHub Actions covers how templates connect to automated workflows. Put another way, before creating a template, decide which format best suits your needs.

      -
      -

      Alex: That matters because of the next idea. Start with Use Markdown templates when. There is something to understand, something to try, and something that proves the try worked.

      -

      Alex: The practical takeaway is this. 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.

      -

      Jamie: Let's pause on Use YAML form templates when. What should a learner take away from it?

      -

      Alex: Keep the learner anchored in Use YAML form templates when. For accessibility projects: YAML form templates are strongly recommended. This is the part to say slowly: Accessibility bug reports require specific context (screen reader, browser, OS, version numbers) that Markdown templates rely on contributors to remember.

      -

      Alex: The practical takeaway is this. 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.

      -

      Alex: This is where the talk moves from concept to action. The reason Markdown Template Structure matters is that a Markdown template consists of two parts. That gives the learner a simple foothold: yAML Frontmatter (between --- delimiters). The interface gets friendlier when it stops being a wall of controls and starts being a set of named places.

      +

      Alex: Start with Step-by-Step: Accept Your Classroom Assignment and Open Your Repo: This is the very first hands-on step of Day 1. The next useful detail is this: By the end of this walkthrough you will have your own Learning Room repository on GitHub and your first challenge issue waiting for you.

      +

      Jamie: Turn that into a path someone can follow.

      +

      Alex: Start with 1. Open the assignment link. There is something to understand, something to try, and something that proves the try worked.

      +

      Alex: First, in the same browser where you are signed into GitHub, open the Day 1 assignment link the facilitator shared. Then, 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"). After that, if the page asks you to authorize GitHub Classroom to access your GitHub account, activate Authorize GitHub Classroom. This is a one-time step. Treat it like a recipe: do not add the next ingredient until the previous one is actually in the bowl.

      -

      Jamie: What is the safe way to learn from that example?

      -

      Alex: Start with 2. Markdown Body: The template content that pre-fills the issue editor.

      -

      Alex: Treat examples as spoken recipes, not decorations. You may hear something like 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. Read the command, understand what it changes, then run it only when the repository state matches the lesson.

      -

      Alex: Another way to ground it. Start with Markdown template tips. There is something to understand, something to try, and something that proves the try worked.

      -

      Alex: The practical takeaway is this. 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.

      -

      Jamie: Let's pause on Complete Markdown Template Example. What should a learner take away from it?

      -

      Alex: This is where Complete Markdown Template Example becomes real: here's a complete accessibility bug report template in Markdown format. That matters in practice: Save this as.github/ISSUE TEMPLATE/accessibility-bug-simple.md.

      +

      Jamie: What is the ordered workflow?

      +

      Alex: This is where 2. Identify yourself (if asked) becomes real: GitHub Classroom may ask you to pick your name from a roster so the facilitators can match your GitHub username to the registration list.

      +

      Alex: First, 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. Then, activate the link or button next to your name. After that, 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. It is a checklist, but a meaningful one: every item creates evidence that the next step is safe.

      +

      Jamie: Give me the sequence, because order matters here.

      +

      Alex: Keep the learner anchored in 3. Accept the assignment. The status page does not auto-announce when the repo is ready. This is the part to say slowly: Use Browse mode and press K to step through links until you hear your repository link, or refresh the page until it appears. A good GitHub workflow is like a well-run meeting: everyone knows the topic, the next action, and who has the floor.

      +

      Alex: First, you now see a screen with a button that says Accept this assignment (or just Accept the assignment ). Activate it. Then, 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. After that, 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/the workshop organization/learning-room-your username. It is like walking a hallway with named doors: read the sign, enter the right room, then confirm where you landed.

      +

      Jamie: Let's pause on 4. Open your new repository. What should a learner take away from it?

      +

      Alex: Start with 4. Open your new repository. There is something to understand, something to try, and something that proves the try worked.

      +

      Alex: On the ground, that means a few things. The repo name in the heading matches learning-room-your username. 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.

      +

      Alex: First, activate the link to your repository. You land on the standard GitHub repo page for the workshop organization/learning-room-your username. Then, verify three things on this page. After that, bookmark this page. You will return here for every Day 1 challenge. The rhythm is simple: orient, act, verify, then continue.

      -

      Alex: Keep the teaching thread moving. Start with When to use this Markdown version instead of YAML. There is something to understand, something to try, and something that proves the try worked.

      -

      Alex: The practical takeaway is this. 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.

      -

      Jamie: Let's pause on Markdown template accessibility considerations. What should a learner take away from it?

      -

      Alex: Start with Markdown template accessibility considerations. There is something to understand, something to try, and something that proves the try worked.

      -

      Alex: The practical takeaway is this. 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.

      -

      Jamie: Let's pause on Creating Markdown Templates: The Manual Workflow (Browser). What should a learner take away from it?

      -

      Alex: Start with Creating Markdown Templates: The Manual Workflow (Browser): Screen reader users (NVDA / JAWS / VoiceOver). The next useful detail is this: Alternative: Navigate directly to.github/ISSUE TEMPLATE/ → activate the "+" button → "Create new file".

      -

      Alex: The practical takeaway is this. Template name: what appears in the chooser heading. About: the description in the chooser. Template content: the Markdown body.

      -

      Alex: First, navigate to your fork of accessibility-agents on GitHub. Then, click the Settings tab. After that, scroll to the "Features" section → click the checkmark next to "Issues" → click "Set up templates". Finally, or navigate directly to.github/ISSUE TEMPLATE/ in your fork → click the + button → "Create new file". Think of it as a rail line: each stop confirms you are still on the right route before the next one.

      -

      Jamie: Before we leave Creating Markdown Templates: The Manual Workflow (Browser), what is the practical point?

      -

      Alex: First, GitHub opens a template editor. Fill in the template name, about description, and body. Then, GitHub auto-populates the filename - you can change it. After that, click "Propose changes" → create a PR to add the template. Finally, go to the Settings tab (press T from the tabs landmark, then navigate to "Settings"). Treat it like a recipe: do not add the next ingredient until the previous one is actually in the bowl.

      +

      Jamie: Let's pause on 5. Find your first challenge issue. What should a learner take away from it?

      +

      Alex: Start with 5. Find your first challenge issue: When your Learning Room repo is ready, Challenge 1 appears as a GitHub issue in your repo. The next useful detail is this: The facilitators prepare this by running the Student Progression Bot after students accept the Classroom assignment.

      +

      Alex: First, from your repository page, navigate to the Issues tab. Keyboard shortcut: press G then I. Then, 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]). After that, open Challenge 1. Read the issue body -- it tells you what to do, where to find evidence, and how to submit completion. Think of it as a rail line: each stop confirms you are still on the right route before the next one.

      +

      Alex: A solid issue habit is to read the title, the body, and the timeline before acting. You are listening for the requested action, the missing evidence, and the person who needs a response.

      +

      Jamie: If I am listening before the workshop starts, what should settle in my mind first?

      +

      Alex: Here is the plain-English version of 6. Confirm Aria can talk to you. The PR validation bot, Aria, posts educational feedback whenever you open a pull request. Put another way, 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 ).

      +

      Alex: Keep the thread going. This is where Workshop Recommendation (Chapter 4) becomes real: chapter 4 is a system orientation chapter. The workshop is closer to rehearsal than lecture. You hear the move, try the move, and then check what changed.

      +

      Alex: The room should hear these as checkpoints. There are 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.

      -

      Jamie: Let's pause on Creating Markdown Templates: The VS Code Workflow. What should a learner take away from it?

      -

      Alex: Start with Creating Markdown Templates: The VS Code Workflow. There is something to understand, something to try, and something that proves the try worked.

      -

      Alex: First, open your accessibility-agents fork in VS Code. Then, navigate in Explorer to.github/ISSUE TEMPLATE/. After that, create a new file: Ctrl+N → save as your-template-name.md in that folder. Finally, add frontmatter first (between --- delimiters), then the body. Treat it like a recipe: do not add the next ingredient until the previous one is actually in the bowl.

      -

      Jamie: Before we leave Creating Markdown Templates: The VS Code Workflow, what is the practical point?

      -

      Alex: First, commit and push: open Source Control (Ctrl+Shift+G) → stage → commit → push. It is a checklist, but a meaningful one: every item creates evidence that the next step is safe.

      -

      Alex: Keep the teaching thread moving. Start with File naming conventions. There is something to understand, something to try, and something that proves the try worked.

      -

      Alex: The practical takeaway is this. Use lowercase with hyphens: accessibility-bug.md, feature-request.md. Be descriptive: security-vulnerability.md is better than security.md. Avoid spaces in filenames.

      -

      Jamie: Let's pause on Learning Cards: Creating a New Template. What should a learner take away from it?

      -

      Alex: Start with Learning Cards: Creating a New Template. There is something to understand, something to try, and something that proves the try worked.

      -

      Alex: The practical takeaway is this. 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. 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.

      +

      Jamie: Let's pause on Readiness Checkpoint. What should a learner take away from it?

      +

      Alex: Keep the learner anchored in Readiness Checkpoint. Before starting Chapter 5 challenges, you should be able to.

      +

      Alex: First, find docs/CHALLENGES.md in your Learning Room repository. Then, explain the flow: issue - branch - pull request - review - merge. After that, identify where Aria bot feedback appears on a PR (the Conversation tab). It is like walking a hallway with named doors: read the sign, enter the right room, then confirm where you landed.

      +

      Alex: Another way to ground it. The reason Two Tracks That Reinforce Each Other matters is that throughout Day 1 you work on two parallel learning tracks, both in your own account.

      +

      Jamie: Let's pause on Track 1: GitHub Skills Modules (Optional Self-Paced Practice). What should a learner take away from it?

      +

      Alex: Start with Track 1: GitHub Skills Modules (Optional Self-Paced Practice): 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.

      +

      Alex: A few details make that real. Introduction to GitHub - Create branch, open PR, merge. Communicate Using Markdown - Write headings, links, code, tables. Review Pull Requests - Comment, approve, suggest changes.

      -

      Alex: Keep the teaching thread moving. The reason 6. YAML Form-Based Templates matters is that yAML templates create a proper form interface - labeled fields, dropdowns, checkboxes - rather than a pre-filled text editor. That gives the learner a simple foothold: this is the preferred format for modern GitHub projects, especially those focused on accessibility.

      -

      Jamie: Let's pause on Why YAML Forms Are Better for Accessibility. What should a learner take away from it?

      -

      Alex: Start with Why YAML Forms Are Better for Accessibility: Explicit labels: Each field has a label: that screen readers announce. The next useful detail is this: In Markdown templates, users must infer structure from headings and placeholder text.

      -

      Alex: Keep the teaching thread moving. Here is the plain-English version of YAML Template Structure. A YAML form template consists of several parts. It is like learning a transit route. The names of the stops matter because they tell you whether you are still going the right direction.

      +

      Alex: This is the part worth saying out loud. Start with Track 2: Your Learning Room Repository (Required Workshop Track). There is something to understand, something to try, and something that proves the try worked.

      +

      Alex: The practical anchors are these. 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).

      +

      Jamie: Can you translate that into plain choices?

      +

      Alex: Start with How the Two Tracks Compare. There is something to understand, something to try, and something that proves the try worked.

      +

      Alex: Use the comparison to make a decision, not to recite a table. The main contrasts are: GitHub Skills (optional) means Your Learning Room (required). Create a branch in a Skills repo means Create a branch in your Learning Room. Open a PR means Open a PR.

      +

      Alex: The next layer is this. Start with Learning Cards: Two Tracks, One Account. There is something to understand, something to try, and something that proves the try worked.

      +

      Alex: For a learner, the useful signals are these. 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. 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.

      -

      Jamie: Let's pause on Top-level keys. What should a learner take away from it?

      -

      Alex: Start with Top-level keys. There is something to understand, something to try, and something that proves the try worked.

      -

      Alex: The practical takeaway is this. 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).

      -

      Alex: Keep the teaching thread moving. Keep the learner anchored in YAML Field Types Reference. GitHub supports several field types in YAML form templates. This is the part to say slowly: Each has specific attributes and uses.

      -

      Jamie: Let's pause on 1. markdown - Instructional Text. What should a learner take away from it?

      -

      Alex: The reason 1. markdown - Instructional Text matters is that displays formatted Markdown content. That gives the learner a simple foothold: use for instructions, warnings, or explanations.

      -

      Alex: The practical takeaway is this. value (required): Markdown content to display. Use for multi-line text.

      +

      Jamie: Let's pause on Your Learning Room Folder Structure. What should a learner take away from it?

      +

      Alex: The reason Your Learning Room Folder Structure matters is that 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.

      +

      Alex: These are the details that keep the idea from floating away. 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.

      +

      Alex: Here is the practical turn. Start with Your Practice Branch: In your own Learning Room repository, you decide what branches to create. The next useful detail is this: The Day 1 challenge sequence asks you to work on a single feature branch named after yourself. Think of it like entering a new building: first you find the lobby, then the room, then the door you actually need.

      +

      Alex: That shows up in the workshop in a few specific ways. 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.

      +

      Jamie: Let's pause on Why you create a separate branch. What should a learner take away from it?

      +

      Alex: Start with Why you create a separate branch. There is something to understand, something to try, and something that proves the try worked.

      +

      Alex: The practical takeaway is this. 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.

      -

      Alex: Keep the teaching thread moving. Start with 2. input - Single-line Text Field: Best for short answers like version numbers, URLs, or names. The next useful detail is this: Screen reader announcement: "Version Number, required, edit text, Which version of the software are you using?". Think of it like entering a new building: first you find the lobby, then the room, then the door you actually need.

      -

      Alex: The practical takeaway is this. label (required): Field label, announced by screen readers. description (optional): Help text below the label. placeholder (optional): Placeholder text inside the field. required (boolean): Whether the field must be filled.

      -

      Jamie: Let's pause on 3. textarea - Multi-line Text Area. What should a learner take away from it?

      -

      Alex: Here is the plain-English version of 3. textarea - Multi-line Text Area. Best for descriptions, reproduction steps, code snippets, or any long-form content. Put another way, accessibility tip: Use placeholder for examples, value for pre-filled template text that contributors should edit.

      -

      Alex: The practical takeaway is this. label (required): Field label. description (optional): Help text. placeholder (optional): Placeholder text (multi-line with ). value (optional): Pre-filled content (multi-line with ).

      -

      Jamie: Let's pause on 4. dropdown - Select Menu. What should a learner take away from it?

      -

      Alex: This is where 4. dropdown - Select Menu becomes real: a dropdown menu with predefined options. That matters in practice: Best for bounded answer spaces like OS, browser, or severity.

      -

      Alex: The practical takeaway is this. label (required):Field label. description (optional): Help text. options (required): Array of choices (strings). multiple (boolean, default false): Whether user can select multiple options.

      -

      Alex: First, field is announced as "Browser, required, combo box". Then, press Down Arrow or Alt+Down to expand the dropdown. After that, up/Down Arrow to navigate options. Finally, screen reader announces each option. It is a checklist, but a meaningful one: every item creates evidence that the next step is safe.

      -

      Jamie: Before we leave 4. dropdown - Select Menu, what is the practical point?

      -

      Alex: First, enter or Space to select. It is like walking a hallway with named doors: read the sign, enter the right room, then confirm where you landed.

      +

      Jamie: Let's pause on How to use your branch. What should a learner take away from it?

      +

      Alex: This is where How to use your branch becomes real: the Day 1 challenges (4 onward) walk you through creating and using your branch on GitHub.com. That matters in practice: Once you start working locally in Chapter 14, the same branch is what you check out.

      +

      Alex: First, create the branch on GitHub.com (Challenge 4) or locally with git checkout -b learn/ from main. Then, make your changes and commit them to the branch. After that, push the branch to GitHub if you created it locally. Finally, open a pull request from learn/ - main (Challenge 6). It is a checklist, but a meaningful one: every item creates evidence that the next step is safe.

      +

      Alex: Treat examples as spoken recipes, not decorations. You may hear something like git checkout learn/. Read the command, understand what it changes, then run it only when the repository state matches the lesson.

      +

      Jamie: Let's pause on Learning Cards: Your Practice Branch. What should a learner take away from it?

      +

      Alex: Start with Learning Cards: Your Practice Branch. There is something to understand, something to try, and something that proves the try worked.

      +

      Alex: The practical takeaway is this. 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. 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.

      +

      Jamie: Let's pause on Tool Cards: Switch to Your Practice Branch. What should a learner take away from it?

      +

      Alex: Start with Tool Cards: Switch to Your Practice Branch. There is something to understand, something to try, and something that proves the try worked.

      +

      Alex: First, on the repository page, click the branch selector dropdown (shows "main"). Then, type learn to filter, then select learn/. After that, click the branch name in the bottom-left status bar. Finally, select your learn/ branch from the list. The rhythm is simple: orient, act, verify, then continue.

      +

      Jamie: Before we leave Tool Cards: Switch to Your Practice Branch, what is the practical point?

      +

      Alex: First, click the branch name in the bottom-left status bar (or press Ctrl+Shift+P then type Git: Checkout to ). Then, select origin/learn/ from the branch list. After that, click the Current Branch dropdown at the top. Think of it as a rail line: each stop confirms you are still on the right route before the next one.

      -

      Jamie: Let's pause on 5. checkboxes - Checkbox Group. What should a learner take away from it?

      -

      Alex: Keep the learner anchored in 5. checkboxes - Checkbox Group. Contributors can select multiple options or use as a verification checklist. This is the part to say slowly: No top-level validation - validation is per-checkbox in options.

      -

      Alex: The practical takeaway is this. label (required): Group label. description (optional): Group description. options (required): Array of checkbox objects. label (required): Checkbox label (what the user sees).

      -

      Alex: First, group label announced: "Before Submitting, Please verify these items". Then, each checkbox announced as "I searched for existing issues, checkbox, not checked, required". After that, screen reader users can check each box with Space. It is like walking a hallway with named doors: read the sign, enter the right room, then confirm where you landed.

      -

      Alex: Keep the teaching thread moving. Start with Choosing the right field type. There is something to understand, something to try, and something that proves the try worked.

      -

      Alex: The practical takeaway is this. 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.

      -

      Jamie: Let's pause on Learning Cards: YAML Form Templates. What should a learner take away from it?

      -

      Alex: Start with Learning Cards: YAML Form Templates. There is something to understand, something to try, and something that proves the try worked.

      -

      Alex: The practical takeaway is this. 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. 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.

      +

      Jamie: Let's pause on The Practice Files: What You Will Work On. What should a learner take away from it?

      +

      Alex: Start with The Practice Files: What You Will Work On: See also: Appendix C: Markdown Reference covers all Markdown syntax with accessible examples -- you will need it for editing these files. The next useful detail is this: The docs/ folder contains three practice files with intentional issues.

      +

      Alex: Hold that next to this. Here is the plain-English version of docs/welcome.md - Introduction to Open Source Contribution. This file introduces newcomers to open source. Put another way, it has three [TODO] sections where content is missing.

      +

      Jamie: Let's pause on [TODO] 1 - "Who Can Contribute?" section. What should a learner take away from it?

      +

      Alex: This is where [TODO] 1 - "Who Can Contribute?" section becomes real: [TODO: Add a paragraph explaining that contributors come from all backgrounds, skill levels, and countries. That matters in practice: Emphasize that using assistive technology is not a barrier to contribution - in fact, AT users bring a perspective that improves projects for everyone.].

      -

      Alex: Keep the teaching thread moving. Here is the plain-English version of 7. Building an Accessibility Bug Report Template. the learner will create a YAML form template specifically for accessibility bug reports in accessibility-agents.

      -

      Jamie: Let's pause on Full Template. What should a learner take away from it?

      -

      Alex: This is where Full Template becomes real: save this as.github/ISSUE TEMPLATE/accessibility-bug.yml in your fork.

      -

      Alex: Keep the teaching thread moving. Keep the learner anchored in What Makes This Template Accessible. This template is itself an accessibility contribution. A good GitHub workflow is like a well-run meeting: everyone knows the topic, the next action, and who has the floor.

      -

      Alex: The practical takeaway is this. 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.

      +

      Alex: That connects to another useful point. Keep the learner anchored in [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. This is the part to say slowly: What questions should you ask yourself? A good GitHub workflow is like a well-run meeting: everyone knows the topic, the next action, and who has the floor.

      +

      Jamie: Let's pause on [TODO] 3 - "After Your Contribution Is Merged" section. What should a learner take away from it?

      +

      Alex: The reason [TODO] 3 - "After Your Contribution Is Merged" section matters is that [TODO: Add a sentence or two about what this means for someone's GitHub profile and open source portfolio.]. That gives the learner a simple foothold: it also has a broken internal link that needs to be found and fixed.

      +

      Alex: Keep the teaching thread moving. Start with docs/keyboard-shortcuts.md - Screen Reader Shortcut Reference: This is a comprehensive reference with tables for NVDA, JAWS, and VoiceOver shortcuts. The next useful detail is this: It contains intentional errors in some shortcut references that students need to find and fix.

      +

      Alex: The practical takeaway is this. 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.

      +

      Alex: A solid navigation habit is to prove where you are before activating controls. Headings, landmarks, and the address bar are not trivia; they are your map.

      -

      Jamie: Let's pause on A Second Template: Feature Request Form. What should a learner take away from it?

      -

      Alex: The reason A Second Template: Feature Request Form matters is that the bug report template above is specific to accessibility issues. That gives the learner a simple foothold: once you understand the pattern, you can create templates for any contribution type.

      -

      Alex: Keep the teaching thread moving. Start with Designing Templates for Your Own Projects: When designing templates for a project you maintain, use these principles. The next useful detail is this: Ask for the minimum that makes the report actionable.

      -

      Jamie: Let's pause on Learning Cards: Building an Accessibility Bug Report Template. What should a learner take away from it?

      -

      Alex: Start with Learning Cards: Building an Accessibility Bug Report Template. There is something to understand, something to try, and something that proves the try worked.

      -

      Alex: The practical takeaway is this. 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. 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.

      +

      Jamie: What does someone need before they touch the keyboard?

      +

      Alex: Here is the plain-English version of 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. Put another way, it contains broken links that point to incorrect URLs and incomplete steps.

      +

      Alex: The practical takeaway is this. 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.

      +

      Alex: Keep the teaching thread moving. This is where docs/CHALLENGES.md - Your Challenge Menu becomes real: this file lists all 21 challenges organized by progression level. That matters in practice: Each challenge lists the file(s) to edit, estimated time, skills practiced, and success criteria. The workshop is closer to rehearsal than lecture. You hear the move, try the move, and then check what changed.

      +

      Jamie: What should the learner prove to themselves after each small task?

      +

      Alex: Keep the learner anchored in Bonus Challenges. Five bonus challenges (A through E) are available for students who finish faster. This is the part to say slowly: These include an accessibility audit, mentoring a peer, cross-repository contribution, creating a custom workflow, and documentation improvement.

      -

      Alex: Keep the teaching thread moving. This is where 8. Pull Request Templates becomes real: a pull request template appears as the default body of every new PR in your repository. That matters in practice: File location.github/pull request template.md (singular - only one PR template per repo). The workshop is closer to rehearsal than lecture. You hear the move, try the move, and then check what changed.

      -

      Jamie: What should happen before anyone copies and runs it?

      -

      Alex: Keep the learner anchored in Reading the Accessibility Agents PR Template. Open.github/pull request template.md in VS Code. This is the part to say slowly: the learner will see the standard sections the project expects.

      -

      Alex: Treat examples as spoken recipes, not decorations. You may hear something like 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. Read the command, understand what it changes, then run it only when the repository state matches the lesson.

      -

      Alex: Keep the teaching thread moving. Start with Learning Cards: Pull Request Templates. There is something to understand, something to try, and something that proves the try worked.

      -

      Alex: The practical takeaway is this. 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. 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.

      +

      Jamie: Let's pause on Student A (working on Challenge 3: Complete Welcome Guide). What should a learner take away from it?

      +

      Alex: The reason Student A (working on Challenge 3: Complete Welcome Guide) matters is that visibility: The PR immediately appears in the repo's Pull Requests tab.

      +

      Alex: First, finds their assigned issue (Issues tab → filter Assignee:@me). Then, opens docs/welcome.md and edits the three [TODO] sections. After that, commits to a new branch: fix/studentA-issue12. Finally, opens a pull request with description. The rhythm is simple: orient, act, verify, then continue.

      +

      Jamie: Before we leave Student A (working on Challenge 3: Complete Welcome Guide), what is the practical point?

      +

      Alex: First, submits the PR. Think of it as a rail line: each stop confirms you are still on the right route before the next one.

      +

      Jamie: Let's pause on Bot (.github/workflows/learning-room-pr-bot.yml). What should a learner take away from it?

      +

      Alex: Start with Bot (.github/workflows/learning-room-pr-bot.yml): Visibility: The bot comment appears in your PR. The next useful detail is this: You see it; the facilitators see it; nobody else does unless they have been added as a collaborator on your repo.

      +

      Alex: The practical takeaway is this. Runs within 30 seconds. 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).

      +

      Jamie: Let's pause on Step 3: Peer Review (Facilitator-Arranged). What should a learner take away from it?

      +

      Alex: Here is the plain-English version of 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. Put another way, 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. It is like learning a transit route. The names of the stops matter because they tell you whether you are still going the right direction.

      +

      Alex: First, the facilitators (Jeff and Michael) pair you with another participant. Then, they add each of you as a collaborator on the other's Learning Room repo. After that, each of you receives a notification: "You have been added as a collaborator.". Finally, you can now read the other person's PRs, leave comments, request changes, and approve. Treat it like a recipe: do not add the next ingredient until the previous one is actually in the bowl.

      +

      Jamie: Before we leave Step 3: Peer Review (Facilitator-Arranged), what is the practical point?

      +

      Alex: First, 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. It is a checklist, but a meaningful one: every item creates evidence that the next step is safe.

      -

      Jamie: Let's pause on Learning Cards: Hands-On Activity. What should a learner take away from it?

      -

      Alex: Start with Learning Cards: Hands-On Activity. There is something to understand, something to try, and something that proves the try worked.

      -

      Alex: The practical takeaway is this. 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. 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.

      -

      Alex: Keep the teaching thread moving. Here is the plain-English version of Exercise A - Use an Existing Template. Your Mission: File your first issue using a structured template. Put another way, you'll experience the template as an end-user, which teaches you what good template design feels like. It is like learning a transit route. The names of the stops matter because they tell you whether you are still going the right direction.

      -

      Jamie: Let's pause on Step 1: Navigate to the Accessibility Agents Issues Section. What should a learner take away from it?

      -

      Alex: Start with Step 1: Navigate to the Accessibility Agents Issues Section. There is something to understand, something to try, and something that proves the try worked.

      -

      Alex: The practical takeaway is this. A tab labeled "Issues" (currently active). A list of open/closed issues below. A large green button labeled "New issue" on the right side. Go directly to: https://github.com/community-access/accessibility-agents/issues/new. This opens the issue template chooser.

      -

      Alex: First, open GitHub in your browser. Then, navigate to the community-access/accessibility-agents repository (or your fork). After that, click the Issues tab (top navigation, between Pull Requests and Discussions). Finally, you should see a list of existing issues. It is a checklist, but a meaningful one: every item creates evidence that the next step is safe.

      -

      Jamie: Before we leave Step 1: Navigate to the Accessibility Agents Issues Section, what is the practical point?

      -

      Alex: First, click the "New issue" button. It is like walking a hallway with named doors: read the sign, enter the right room, then confirm where you landed.

      +

      Jamie: Let's pause on Visibility. What should a learner take away from it?

      +

      Alex: Start with Visibility. There is something to understand, something to try, and something that proves the try worked.

      +

      Alex: The practical takeaway is this. 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.

      +

      Jamie: Let's pause on Your assigned peer reviewer (when one is paired with you). What should a learner take away from it?

      +

      Alex: Start with Your assigned peer reviewer (when one is paired with you). There is something to understand, something to try, and something that proves the try worked.

      +

      Alex: The practical takeaway is this. 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. 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.".

      +

      Alex: First, receives notification: "PR review requested". Then, navigates to the PR in your Learning Room repo (they have collaborator access). After that, leaves review comments. Finally, submits review: Approve (or Request Changes if a [TODO] marker was missed). It is like walking a hallway with named doors: read the sign, enter the right room, then confirm where you landed.

      +

      Jamie: Before we leave Visibility, what is the practical point?

      +

      Alex: The practical takeaway is this. 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.

      -

      Jamie: Let's pause on Step 2: View the Template Chooser with Your Screen Reader. What should a learner take away from it?

      -

      Alex: Start with Step 2: View the Template Chooser with Your Screen Reader. There is something to understand, something to try, and something that proves the try worked.

      -

      Alex: The practical takeaway is this. 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. Template 1: [name] - [description]. Template 2: [name] - [description]. And so on. Is each template name announced clearly?

      -

      Alex: First, you should now see a Template Chooser page. Then, the page displays available templates as buttons or links. After that, with screen reader: Navigate through the templates. Finally, count the templates and read their descriptions aloud (or write them down). It is like walking a hallway with named doors: read the sign, enter the right room, then confirm where you landed.

      -

      Alex: A solid navigation habit is to prove where you are before activating controls. Headings, landmarks, and the address bar are not trivia; they are your map.

      -

      Jamie: Let's pause on Step 3: Select a Template. What should a learner take away from it?

      -

      Alex: Start with Step 3: Select a Template. There is something to understand, something to try, and something that proves the try worked.

      -

      Alex: The practical takeaway is this. The issue form opens. You see a form with labeled fields. Each field is pre-filled with helpful prompts or instructions. Choose "Blank Issue" or the most general template. You'll learn what an unstructured issue looks like (which teaches the value of templates).

      -

      Alex: First, 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). Then, click it (or press Enter if focused with keyboard). The rhythm is simple: orient, act, verify, then continue.

      -

      Jamie: Let's pause on Step 4: Navigate the Form Fields. What should a learner take away from it?

      -

      Alex: Start with Step 4: Navigate the Form Fields. There is something to understand, something to try, and something that proves the try worked.

      -

      Alex: The practical takeaway is this. 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. 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"). Field: [name] - Required? [Yes/No].

      -

      Alex: First, the issue form is now open. Then, navigate through all visible fields using your screen reader or by tabbing. After that, for each field, note. Finally, write down at least 3 fields and whether each is required. Think of it as a rail line: each stop confirms you are still on the right route before the next one.

      +

      Jamie: Let's pause on You (PR author). What should a learner take away from it?

      +

      Alex: Start with You (PR author). There is something to understand, something to try, and something that proves the try worked.

      +

      Alex: First, read Aria's feedback and any human review. Then, talks to the reviewer if something is unclear. After that, makes changes based on feedback. Finally, pushes new commits to the same branch. Think of it as a rail line: each stop confirms you are still on the right route before the next one.

      +

      Jamie: Before we leave You (PR author), what is the practical point?

      +

      Alex: First, re-addresses the feedback. Treat it like a recipe: do not add the next ingredient until the previous one is actually in the bowl.

      +

      Jamie: What is the teaching move inside Visibility?

      +

      Alex: The practical takeaway is this. 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.

      +

      Alex: Keep the teaching thread moving. Start with When the review is approved (or you decide to self-merge). There is something to understand, something to try, and something that proves the try worked.

      +

      Alex: The practical takeaway is this. You merge the PR (button becomes available). PR closes, shows "merged".

      -

      Jamie: Let's pause on Step 5: Fill In the Form. What should a learner take away from it?

      -

      Alex: Start with Step 5: Fill In the Form. There is something to understand, something to try, and something that proves the try worked.

      -

      Alex: The practical takeaway is this. Example: If the template asks "Screen Reader," select "NVDA". If it asks "Steps to reproduce," write 2-3 specific steps. 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).

      -

      Alex: First, fill in at least 3 fields with realistic content based on an issue you identified on Day 1. Then, for required fields marked with: Fill them in completely. After that, for optional fields: Choose at least one and fill it in (so you test optional fields). Finally, don't worry about filling in every field - the point is to test the form. Treat it like a recipe: do not add the next ingredient until the previous one is actually in the bowl.

      -

      Jamie: Let's pause on Step 6: Preview the Issue Before Submitting. What should a learner take away from it?

      -

      Alex: Start with Step 6: Preview the Issue Before Submitting. There is something to understand, something to try, and something that proves the try worked.

      -

      Alex: The practical takeaway is this. 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. 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?

      -

      Alex: First, look for a Preview tab or button (usually near the top of the form, next to "Write" or "Markdown"). Then, click it (or press the hotkey shown). After that, a preview pane appears showing how the issue will look when published. It is a checklist, but a meaningful one: every item creates evidence that the next step is safe.

      -

      Jamie: Let's pause on Step 7: Submit the Issue. What should a learner take away from it?

      -

      Alex: Start with Step 7: Submit the Issue. There is something to understand, something to try, and something that proves the try worked.

      -

      Alex: The practical takeaway is this. 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.

      -

      Alex: First, once you're satisfied with the preview, go back to the "Write" tab. Then, locate the green "New issue" button (usually at the bottom of the form). After that, with keyboard: Press Tab until the button is focused, then Enter. Finally, with mouse: Click the button. It is like walking a hallway with named doors: read the sign, enter the right room, then confirm where you landed.

      -

      Jamie: Before we leave Step 7: Submit the Issue, what is the practical point?

      -

      Alex: First, the issue is submitted and you see the new issue page with your content. The rhythm is simple: orient, act, verify, then continue.

      +

      Jamie: How do these exercises create confidence instead of pressure?

      +

      Alex: Start with Progression Bot Posts the Next Challenge. There is something to understand, something to try, and something that proves the try worked.

      +

      Alex: The practical takeaway is this. 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.

      +

      Alex: Keep the teaching thread moving. Start with Visibility. There is something to understand, something to try, and something that proves the try worked.

      +

      Alex: The practical takeaway is this. 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.

      +

      Jamie: Let's pause on Learning Cards: How PR Sharing Works. What should a learner take away from it?

      +

      Alex: Start with Learning Cards: How PR Sharing Works. There is something to understand, something to try, and something that proves the try worked.

      +

      Alex: The practical takeaway is this. 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. 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.

      -

      Jamie: Let's pause on Step 8: Checkpoint - Reflect on the Template. What should a learner take away from it?

      -

      Alex: The reason Step 8: Checkpoint - Reflect on the Template matters is that you'll use them in Exercise D when you design your own template. The interface gets friendlier when it stops being a wall of controls and starts being a set of named places.

      -

      Alex: First, template Clarity: Did the template guide you toward providing useful information, or did fields feel confusing or unnecessary? Then, screen Reader Accessibility: Were all field labels announced clearly? Did you encounter any accessibility barriers? After that, required vs Optional: Was it obvious which fields were required? If you skipped an optional field, would you have known it was optional? Finally, context Helpfulness: Did the placeholder text or help text under each field make you understand what information to provide? The rhythm is simple: orient, act, verify, then continue.

      -

      Jamie: What should the learner prove to themselves after each small task?

      -

      Alex: Start with 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. The next useful detail is this: This teaches you the file structure and gives you hands-on experience with YAML syntax.

      -

      Alex: The practical takeaway is this. You have already read Section 7 thoroughly (Building an Accessibility Bug Report Template). You have a fork of accessibility-agents (created on Day 1). VS Code is installed on your machine. Git is installed and configure with your GitHub credentials.

      -

      Jamie: Let's pause on Step 1: Clone Your Fork to Your Machine. What should a learner take away from it?

      -

      Alex: Here is the plain-English version of Step 1: Clone Your Fork to Your Machine. (Or wherever you keep code projects). Put another way, replace [YOUR-USERNAME] with your actual GitHub username.

      -

      Alex: The practical takeaway is this. 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. "Repository not found" → Make sure your GitHub username is correct.

      -

      Alex: First, open a terminal (PowerShell on Windows, Terminal on macOS/Linux). Then, navigate to a folder where you want to store the project. After that, clone your fork. Finally, wait for the clone to complete (should take 10-30 seconds). Treat it like a recipe: do not add the next ingredient until the previous one is actually in the bowl.

      -

      Jamie: Before we leave Step 1: Clone Your Fork to Your Machine, what is the practical point?

      -

      Alex: First, navigate into the folder. It is a checklist, but a meaningful one: every item creates evidence that the next step is safe.

      -

      Alex: Treat examples as spoken recipes, not decorations. You may hear something like cd /projects. git clone https://github.com/[YOUR-USERNAME]/accessibility-agents.git. Read the command, understand what it changes, then run it only when the repository state matches the lesson.

      +

      Alex: Keep the teaching thread moving. Here is the plain-English version of The Learning Automation System. When you open a PR in the Learning Room, you get three types of feedback.

      +

      Jamie: Let's pause on Type 1: Automated Bot Feedback (30 seconds). What should a learner take away from it?

      +

      Alex: Start with Type 1: Automated Bot Feedback (30 seconds). There is something to understand, something to try, and something that proves the try worked.

      +

      Alex: The practical takeaway is this. 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.

      +

      Alex: Keep the teaching thread moving. Start with Type 2: Peer Reviewer Feedback (15-60 minutes). There is something to understand, something to try, and something that proves the try worked.

      +

      Alex: The practical takeaway is this. Human judgment on content. Creative suggestions. Encouragement and mentorship. Understanding of context. Can approve, request changes, or comment.

      -

      Jamie: Let's pause on Step 2: Open Your Fork in VS Code. What should a learner take away from it?

      -

      Alex: Start with Step 2: Open Your Fork in VS Code. There is something to understand, something to try, and something that proves the try worked.

      -

      Alex: The practical takeaway is this. VS Code opens a new window. The left sidebar shows the folder structure of accessibility-agents. At the top, you see the folder name: accessibility-agents. Use VS Code's File menu: File → Open Folder → navigate to your accessibility-agents folder.

      -

      Alex: First, from the terminal, while in your accessibility-agents folder, type. Then, press Enter. After that, VS Code opens with your fork loaded. It is a checklist, but a meaningful one: every item creates evidence that the next step is safe.

      -

      Jamie: Let's pause on Step 3: Navigate to the Templates Folder. What should a learner take away from it?

      -

      Alex: Start with Step 3: Navigate to the Templates Folder. There is something to understand, something to try, and something that proves the try worked.

      -

      Alex: The practical takeaway is this. 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. Right-click on the.github folder and select New Folder. Name it ISSUE TEMPLATE.

      -

      Alex: First, in VS Code's file tree (left sidebar), expand the.github folder. Then, inside, find and expand the ISSUE TEMPLATE folder. After that, you should see existing template files (like bug-report-template.yml or similar). It is like walking a hallway with named doors: read the sign, enter the right room, then confirm where you landed.

      -

      Jamie: Let's pause on Step 4: Create a New Template File. What should a learner take away from it?

      -

      Alex: Start with Step 4: Create a New Template File. There is something to understand, something to try, and something that proves the try worked.

      -

      Alex: The practical takeaway is this. A new, empty file opens in the editor. The cursor is ready for you to start typing.

      -

      Alex: First, right-click on the ISSUE TEMPLATE folder. Then, select New File. After that, name it: accessibility-bug.yml (exactly this name). Finally, press Enter. The rhythm is simple: orient, act, verify, then continue.

      +

      Jamie: Let's pause on Type 3: Progress Tracking (on merge). What should a learner take away from it?

      +

      Alex: The reason Type 3: Progress Tracking (on merge) matters is that together: Instant technical feedback + human mentorship + visible progress.

      +

      Alex: The practical takeaway is this. Skill badges (Markdown Master, Accessibility Advocate). Level progression (Beginner → Intermediate → Advanced → Expert). Milestone celebrations (1st, 5th, 10th PR). Motivational comments.

      +

      Jamie: Let's pause on Study Groups (Optional). What should a learner take away from it?

      +

      Alex: Start with 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.

      +

      Alex: First, group Issue Thread - Private communication space for your group. Then, shared Review Responsibility - You review each other's work. After that, collaborative Challenges - Optional group exercises. Finally, peer Support - Tag each other with questions. Think of it as a rail line: each stop confirms you are still on the right route before the next one.

      +

      Jamie: How should someone choose between those options?

      +

      Alex: Start with Key Differences: Skills Module vs. Your Learning Room. There is something to understand, something to try, and something that proves the try worked.

      +

      Alex: Use the comparison to make a decision, not to recite a table. The main contrasts are: GitHub Skills (Your Account) means Your Learning Room (Classroom). Your personal copy of a Skills repo means Your private copy of learning-room-template. Mona (GitHub) means Aria (PR validation) and the Student Progression bot.

      -

      Jamie: Let's pause on Step 5: Copy the Accessibility Template YAML. What should a learner take away from it?

      -

      Alex: Start with Step 5: Copy the Accessibility Template YAML. There is something to understand, something to try, and something that proves the try worked.

      -

      Alex: The practical takeaway is this. 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).

      -

      Alex: First, go to Chapter 17, Section 7 in this curriculum. Then, find the complete YAML template code block (starting with name: and ending with the last field). After that, select all the YAML code (use Ctrl+A on the webpage or manually select). Finally, copy it (Ctrl+C). Think of it as a rail line: each stop confirms you are still on the right route before the next one.

      -

      Jamie: Before we leave Step 5: Copy the Accessibility Template YAML, what is the practical point?

      -

      Alex: First, go back to VS Code. Then, paste it into your new accessibility-bug.yml file (Ctrl+V). Treat it like a recipe: do not add the next ingredient until the previous one is actually in the bowl.

      -

      Jamie: Let's pause on Step 6: Verify the YAML Syntax. What should a learner take away from it?

      -

      Alex: Start with Step 6: Verify the YAML Syntax. There is something to understand, something to try, and something that proves the try worked.

      -

      Alex: The practical takeaway is this. 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. Your YAML syntax is correct!

      -

      Alex: First, save the file (Ctrl+S). Then, look at the bottom right of VS Code - you may see some notifications. After that, check if VS Code shows any red squiggly lines (indicating syntax errors). Finally, hover over the error to see what VS Code suggests. Treat it like a recipe: do not add the next ingredient until the previous one is actually in the bowl.

      -

      Jamie: Before we leave Step 6: Verify the YAML Syntax, what is the practical point?

      -

      Alex: First, compare your file with Section 7's template - look for extra/missing spaces or colons. Then, make corrections and save again. It is a checklist, but a meaningful one: every item creates evidence that the next step is safe.

      -

      Jamie: Let's pause on Step 7: Create a Branch and Commit. What should a learner take away from it?

      -

      Alex: Start with Step 7: Create a Branch and Commit. There is something to understand, something to try, and something that proves the try worked.

      -

      Alex: The practical takeaway is this. Git uploads your branch to GitHub. You're ready to test the template in the next step. "Not a git repository" → Make sure you opened the accessibility-agents folder in VS Code. "Permission denied" → Make sure you authenticated with GitHub (see Prerequisites).

      -

      Alex: First, open the terminal in VS Code: Terminal → New Terminal (or Ctrl+ ` on Windows). Then, you should be in the accessibility-agents folder already. After that, create a new branch for this change. Finally, add the file to git. It is a checklist, but a meaningful one: every item creates evidence that the next step is safe.

      -

      Jamie: Before we leave Step 7: Create a Branch and Commit, what is the practical point?

      -

      Alex: First, commit with a message. Then, push to your fork. It is like walking a hallway with named doors: read the sign, enter the right room, then confirm where you landed.

      -

      Alex: Treat examples as spoken recipes, not decorations. You may hear something like git checkout -b feat/add-accessibility-template. git add.github/ISSUE TEMPLATE/accessibility-bug.yml. Read the command, understand what it changes, then run it only when the repository state matches the lesson.

      -

      Alex: A solid Git habit is to know which branch you are on, what changed, and what confirmation you expect before you run the next command.

      +

      Alex: Keep the teaching thread moving. This is where Tips for Reviewing a Peer's PR becomes real: 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. That matters in practice: Here is how to find the PRs they want you to look at. The workshop is closer to rehearsal than lecture. You hear the move, try the move, and then check what changed.

      +

      Jamie: Let's pause on Finding PRs to Review. What should a learner take away from it?

      +

      Alex: Keep the learner anchored in Finding PRs to Review. Screen reader users (VoiceOver - macOS).

      +

      Alex: First, go to your peer's Learning Room repo (the URL the facilitators sent you, or open it from your GitHub Notifications inbox). Then, click the Pull Requests tab. After that, click the Filters dropdown - "Review requested" - your username. Finally, click any PR title to open it. It is like walking a hallway with named doors: read the sign, enter the right room, then confirm where you landed.

      +

      Alex: Treat examples as spoken recipes, not decorations. You may hear something like 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. 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. Read the command, understand what it changes, then run it only when the repository state matches the lesson.

      +

      Alex: Keep the teaching thread moving. The reason Reading a PR You're Assigned To matters is that screen reader users (VoiceOver - macOS).

      +

      Alex: The practical takeaway is this. 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.

      -

      Jamie: Let's pause on Step 8: Test the Template in GitHub Web. What should a learner take away from it?

      -

      Alex: Start with Step 8: Test the Template in GitHub Web. There is something to understand, something to try, and something that proves the try worked.

      -

      Alex: The practical takeaway is this. 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. Go back to the main repository page (code tab). Refresh the browser (Ctrl+Shift+R for hard refresh).

      -

      Alex: First, open GitHub in your browser. Then, go to your fork: https://github.com/[YOUR-USERNAME]/accessibility-agents. After that, you should see a notification or purple bar saying "Compare & pull request" (your new branch). Finally, but instead of opening a PR, click the Issues tab. It is like walking a hallway with named doors: read the sign, enter the right room, then confirm where you landed.

      -

      Jamie: Before we leave Step 8: Test the Template in GitHub Web, what is the practical point?

      -

      Alex: First, click New issue. Then, you should now see your new template in the chooser: "Accessibility Bug Report". After that, click it to open the form. The rhythm is simple: orient, act, verify, then continue.

      -

      Jamie: Let's pause on Step 9: Test with Your Screen Reader. What should a learner take away from it?

      -

      Alex: The reason Step 9: Test with Your Screen Reader matters is that record your findings - you'll use this for Exercise D.

      -

      Alex: The practical takeaway is this. Is the label announced clearly? Is it obvious whether the field is required? Do dropdowns announce their options correctly? Are descriptions/help text announced? Did you encounter any accessibility barriers? Would a screen reader user find this template easy to use?

      -

      Alex: First, with screen reader activated: Navigate through the template form using your reader's commands. Then, for each field, note. The rhythm is simple: orient, act, verify, then continue.

      -

      Jamie: Let's pause on Step 10: Merge Your Branch (Optional). What should a learner take away from it?

      -

      Alex: Start with Step 10: Merge Your Branch (Optional). There is something to understand, something to try, and something that proves the try worked.

      -

      Alex: The practical takeaway is this. Go to your fork on GitHub. You should see a "Compare & pull request" button. Click it. It shows the template is finalized and tested. If you continue working on this fork, the template is ready for everyone who clones it.

      -

      Alex: First, open an PR for your branch. Then, add a title: feat: add accessibility bug report template. After that, add a description: This template guides contributors to report accessibility issues with clear fields for screen reader type, browser, and WCAG criteria. Finally, click Create pull request. Think of it as a rail line: each stop confirms you are still on the right route before the next one.

      -

      Jamie: Before we leave Step 10: Merge Your Branch (Optional), what is the practical point?

      -

      Alex: First, review your PR (using skills from Chapter 14!). Then, if satisfied, click Merge pull request to merge it into your fork's main branch. Treat it like a recipe: do not add the next ingredient until the previous one is actually in the bowl.

      +

      Jamie: Let's pause on Leaving a Review. What should a learner take away from it?

      +

      Alex: Start with Leaving a Review: Screen reader users (VoiceOver - macOS).

      +

      Alex: First, scroll to the comment box on the Conversation tab. Then, type your review comment. After that, click "Review Changes" (top-right of the Files Changed tab, or at the bottom of the PR page). Finally, select your review type: Comment / Approve / Request changes. Think of it as a rail line: each stop confirms you are still on the right route before the next one.

      +

      Jamie: Before we leave Leaving a Review, what is the practical point?

      +

      Alex: First, click "Submit review". Treat it like a recipe: do not add the next ingredient until the previous one is actually in the bowl.

      +

      Alex: Treat examples as spoken recipes, not decorations. You may hear something like 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". Read the command, understand what it changes, then run it only when the repository state matches the lesson.

      +

      Jamie: Let's pause on Responding to Feedback. What should a learner take away from it?

      +

      Alex: Here is the plain-English version of Responding to Feedback. Screen reader users (VoiceOver - macOS). It is like learning a transit route. The names of the stops matter because they tell you whether you are still going the right direction.

      +

      Alex: First, open your PR (Pull Requests tab → click your PR). Then, read all comments and bot feedback. After that, click in the comment box to reply. Finally, push your fixes to the same branch. Treat it like a recipe: do not add the next ingredient until the previous one is actually in the bowl.

      +

      Jamie: Before we leave Responding to Feedback, what is the practical point?

      +

      Alex: First, comment: "Updates pushed, ready for review". It is a checklist, but a meaningful one: every item creates evidence that the next step is safe.

      +

      Alex: Treat examples as spoken recipes, not decorations. You may hear something like 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". Read the command, understand what it changes, then run it only when the repository state matches the lesson.

      +

      Jamie: Let's pause on Learning Cards: Tips for PR Sharing. What should a learner take away from it?

      +

      Alex: Start with Learning Cards: Tips for PR Sharing. There is something to understand, something to try, and something that proves the try worked.

      +

      Alex: The practical takeaway is this. 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. 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.

      -

      Jamie: Let's pause on Checkpoint. What should a learner take away from it?

      -

      Alex: Here is the plain-English version of Checkpoint. After completing Steps 1-9, verify. It is like learning a transit route. The names of the stops matter because they tell you whether you are still going the right direction.

      -

      Alex: First, you created a file named accessibility-bug.yml in.github/ISSUE TEMPLATE/. Then, the file contains valid YAML (no red squiggles in VS Code). After that, the template is visible when you click "New issue" in your fork. Finally, you tested it with your screen reader and noted any issues. Treat it like a recipe: do not add the next ingredient until the previous one is actually in the bowl.

      -

      Jamie: Why is the evidence prompt part of the teaching, not just grading?

      -

      Alex: This is where Exercise C - Submit It Upstream becomes real: your Mission: Contribute your tested template to the upstream community-access/accessibility-agents repository. That matters in practice: This is a real open source contribution!

      -

      Alex: The practical takeaway is this. 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.

      -

      Jamie: Let's pause on Step 1: Verify Your Template is Ready. What should a learner take away from it?

      -

      Alex: Keep the learner anchored in Step 1: Verify Your Template is Ready. Before submitting upstream, make sure your template is production-ready.

      -

      Alex: The practical takeaway is this. All fields display correctly. No broken formatting. Dropdowns work properly. Required fields are marked. The template is clean, no error messages. Every field is functional.

      -

      Alex: First, go to your fork on GitHub. Then, click Issues → New issue. After that, verify your template appears and is named "Accessibility Bug Report". Finally, open it and fill it out once more to confirm. It is like walking a hallway with named doors: read the sign, enter the right room, then confirm where you landed.

      -

      Jamie: Before we leave Step 1: Verify Your Template is Ready, what is the practical point?

      -

      Alex: First, don't submit this test issue - just close the tab. The rhythm is simple: orient, act, verify, then continue.

      +

      Alex: Keep the teaching thread moving. Keep the learner anchored in "Can I see other students' PRs?". Not inside their Learning Room repos -- those are private to each student. This is the part to say slowly: You can see other participants' work in two ways.

      +

      Alex: The practical takeaway is this. 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.

      +

      Jamie: Let's pause on "What if I don't agree with my assigned reviewer?". What should a learner take away from it?

      +

      Alex: The reason "What if I don't agree with my assigned reviewer?" matters is that when the facilitators pair you for peer review, the pairing is a starting point, not a mandate. That gives the learner a simple foothold: you can request additional reviewers manually.

      +

      Alex: Keep the teaching thread moving. Start with "Will my PR get lost when everyone is working at once?": Your repo is your own; you only see your own PRs. The next useful detail is this: Aria's feedback is on your PR alone, and any peer reviewer is specifically assigned to you. Think of it like entering a new building: first you find the lobby, then the room, then the door you actually need.

      -

      Jamie: Let's pause on Step 2: Create the Pull Request. What should a learner take away from it?

      -

      Alex: Start with Step 2: Create the Pull Request. There is something to understand, something to try, and something that proves the try worked.

      -

      Alex: The practical takeaway is this. Click the Code tab. Click the branches dropdown. Select your branch (feat/add-accessibility-template). Click "New pull request" to the right. Base: community-access/accessibility-agents / main (the upstream repo). Head: [your-username]/accessibility-agents / feat/add-accessibility-template (your fork/branch).

      -

      Alex: First, stay on your fork's GitHub page. Then, you should see a "Compare & pull request" button (or look for your feature branch). After that, if that button doesn't appear. Finally, a PR creation page opens showing. The rhythm is simple: orient, act, verify, then continue.

      -

      Jamie: Before we leave Step 2: Create the Pull Request, what is the practical point?

      -

      Alex: First, confirm this is correct - you're sending your branch to the upstream repository. Think of it as a rail line: each stop confirms you are still on the right route before the next one.

      -

      Jamie: How do you keep commands from becoming magic words?

      -

      Alex: Start with Step 3: Write Your PR Title and Description: Write a clear description that explains what you're contributing. Think of it like entering a new building: first you find the lobby, then the room, then the door you actually need.

      -

      Alex: Treat examples as spoken recipes, not decorations. You may hear something like 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. Read the command, understand what it changes, then run it only when the repository state matches the lesson.

      -

      Jamie: Let's pause on What to do. What should a learner take away from it?

      -

      Alex: Start with What to do. There is something to understand, something to try, and something that proves the try worked.

      -

      Alex: The practical takeaway is this. 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?

      -

      Alex: First, copy the template above into the description field. Then, edit it with your actual testing experience. After that, keep it concise but thorough. Treat it like a recipe: do not add the next ingredient until the previous one is actually in the bowl.

      +

      Jamie: Let's pause on "Can I comment on someone else's PR?". What should a learner take away from it?

      +

      Alex: Here is the plain-English version of "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. Put another way, on the public accessibility-agents repo, anyone can comment on any open PR.

      +

      Alex: Keep the teaching thread moving. This is where "What if my reviewer doesn't respond?" becomes real: mention them directly in a PR comment: "@name, any thoughts on the changes I pushed?" Or ask a facilitator to follow up.

      +

      Jamie: Let's pause on "Can I work with a friend?". What should a learner take away from it?

      +

      Alex: Keep the learner anchored in "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.

      -

      Jamie: Let's pause on Step 4: Review Your PR Before Submitting. What should a learner take away from it?

      -

      Alex: Start with Step 4: Review Your PR Before Submitting. There is something to understand, something to try, and something that proves the try worked.

      -

      Alex: The practical takeaway is this. Is the title clear about what you're adding? Does the description explain the value of this template? Are all checkmarks (``) and formatting visible?

      -

      Alex: First, scroll down and preview your PR description as it will appear. Then, using your screen reader, read through it. After that, make any corrections needed. Finally, do not submit yet - continue to Step 5. It is a checklist, but a meaningful one: every item creates evidence that the next step is safe.

      -

      Jamie: Let's pause on Step 5: Submit the PR. What should a learner take away from it?

      -

      Alex: Start with Step 5: Submit the PR. There is something to understand, something to try, and something that proves the try worked.

      -

      Alex: The practical takeaway is this. 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. Your PR appears in the upstream repository's PR list. You see comments from maintainers (positive feedback = great sign!).

      -

      Alex: First, click the green "Create pull request" button. Then, your PR is now submitted to the upstream repository. After that, you see a confirmation page showing your new PR number (e.g., " 42"). Finally, GitHub may automatically assign reviewers or run CI checks. It is like walking a hallway with named doors: read the sign, enter the right room, then confirm where you landed.

      -

      Jamie: Let's pause on Step 6: Respond to Feedback. What should a learner take away from it?

      -

      Alex: Start with Step 6: Respond to Feedback. There is something to understand, something to try, and something that proves the try worked.

      -

      Alex: The practical takeaway is this. Go back to your fork in VS Code. Edit the accessibility-bug.yml file accordingly. Commit and push. Your changes automatically appear in the PR (linked to the branch). You can leave a polite comment: "Friendly ping - is there anything else needed from my end?".

      -

      Alex: First, read their feedback carefully using your screen reader. Then, understand what changes they're requesting (or what they're praising!). After that, if changes are needed. Finally, leave a reply comment on the PR. The rhythm is simple: orient, act, verify, then continue.

      -

      Jamie: Before we leave Step 6: Respond to Feedback, what is the practical point?

      -

      Alex: First, click Reply. Think of it as a rail line: each stop confirms you are still on the right route before the next one.

      -

      Alex: Treat examples as spoken recipes, not decorations. You may hear something like git add.github/ISSUE TEMPLATE/accessibility-bug.yml; git commit -m "Address feedback from maintainers: [brief description]"; git push origin feat/add-accessibility-template. Read the command, understand what it changes, then run it only when the repository state matches the lesson.

      +

      Alex: Keep the teaching thread moving. The reason "How long does review take?" matters is that when pairings happen during a workshop block, typically 15-60 minutes. That gives the learner a simple foothold: if a reviewer is slow, the facilitators can step in or assign someone else. The interface gets friendlier when it stops being a wall of controls and starts being a set of named places.

      +

      Jamie: Let's pause on "What if bot feedback is wrong?". What should a learner take away from it?

      +

      Alex: Start with "What if bot feedback is wrong?": Aria is intentionally educational, not punitive -- if you disagree with a check, the facilitators can override it. The next useful detail is this: Aria is not perfect, which is exactly why human review still matters.

      +

      Alex: Keep the teaching thread moving. Here is the plain-English version of "Do I need to complete every challenge?". The Learning Room has challenges for all skill levels. Put another way, you can pick what interests you, complete at your pace, and continue after the workshop -- your repo stays yours.

      -

      Jamie: Let's pause on Step 7: Celebrate Your Contribution. What should a learner take away from it?

      -

      Alex: Start with Step 7: Celebrate Your Contribution: -Write down: "I contributed [template name] to an open source project".

      -

      Alex: The practical takeaway is this. Take a screenshot of your merged PR. This is valuable experience for your resume and for learning how open source collaboration works.

      -

      Alex: First, you'll see the PR status change to "Merged". Then, your template is now part of the community-access/accessibility-agents repository. After that, everyone who forks that repo will get your template. Finally, you can claim this as a real open source contribution. Think of it as a rail line: each stop confirms you are still on the right route before the next one.

      -

      Jamie: Before we leave Checkpoint, what is the practical point?

      -

      Alex: Here is the plain-English version of Checkpoint. After completing Steps 1-7, verify.

      -

      Alex: The practical takeaway is this. 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?

      -

      Alex: First, you created a PR to the upstream repository. Then, your PR includes a clear description of what you're contributing. After that, your template is the only change in the PR (one file). Finally, you addressed any feedback from maintainers. Treat it like a recipe: do not add the next ingredient until the previous one is actually in the bowl.

      -

      Jamie: What is the teaching move inside Checkpoint?

      -

      Alex: First, your PR was merged (or is waiting for merge). It is a checklist, but a meaningful one: every item creates evidence that the next step is safe.

      -

      Jamie: How do these exercises create confidence instead of pressure?

      -

      Alex: This is where Exercise D - Design a Template for Your Own Project becomes real: your Mission: Apply everything you've learned to design a template for a repository you own, maintain, or plan to create. That matters in practice: What You'll Learn: How to make design decisions about required vs.

      +

      Jamie: Let's pause on Celebration: You're Contributing. What should a learner take away from it?

      +

      Alex: This is where Celebration: You're Contributing becomes real: every PR you open and merge in the Learning Room is a real contribution. That matters in practice: You found something to improve You made a meaningful change You received feedback (technical + human) You incorporated suggestions You merged your work.

      +

      Alex: Keep the teaching thread moving. Keep the learner anchored in Creating, Reviewing, and Merging Pull Requests with a Screen Reader. See also: Chapter 15: Code Review covers the full review workflow including multi-file diffs and suggested changes. This is the part to say slowly: Pull requests are where your work becomes a contribution. A good GitHub workflow is like a well-run meeting: everyone knows the topic, the next action, and who has the floor.

      +

      Jamie: Where is the promise of the workshop, underneath all the logistics?

      +

      Alex: The reason Workshop Recommendation (Chapter 6) matters is that chapter 6 is the first PR-validated chapter where students convert issue work into merge-ready contributions.

      +

      Alex: The practical takeaway is this. There are 3. Each challenge should take under 10 minutes each. The evidence is PR metadata, bot checks, and merged issue linkage. The pattern is small change - linked PR - green checks.

      -

      Jamie: Let's pause on Part 1: Choose Your Project. What should a learner take away from it?

      -

      Alex: Start with Choose Your Project. There is something to understand, something to try, and something that proves the try worked.

      -

      Alex: The practical takeaway is this. 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. You have a specific project in mind (not generic). You can articulate why you care about it.

      -

      Alex: First, think of a repository you have a personal connection to. Then, write down the project name and briefly why chose it. It is like walking a hallway with named doors: read the sign, enter the right room, then confirm where you landed.

      -

      Jamie: Let's pause on Part 2: Identify Issue Patterns. What should a learner take away from it?

      -

      Alex: The reason Identify Issue Patterns matters is that your task: Study the issues your project receives (or would receive) to understand what information is most valuable. That gives the learner a simple foothold: if your project doesn't exist yet or has no issues.

      -

      Alex: The practical takeaway is this. 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? Bug reports?

      -

      Alex: First, open your issue list in GitHub. Then, read the last 5-10 issues (or all open issues if fewer). After that, for each issue, ask yourself. Finally, write down 3-5 patterns. The rhythm is simple: orient, act, verify, then continue.

      -

      Jamie: Before we leave Part 2: Identify Issue Patterns, what is the practical point?

      -

      Alex: First, think about the type of issues you'd want to receive. Then, for each type, ask: "If someone reported this issue, what would I need to know?". After that, write down. Think of it as a rail line: each stop confirms you are still on the right route before the next one.

      -

      Jamie: Let's pause on Part 3: Design Your Required Fields. What should a learner take away from it?

      -

      Alex: Start with Design Your Required Fields: Your task: List the fields you absolutely need to understand an issue. The next useful detail is this: Rule: Keep required fields minimal.

      -

      Alex: The practical takeaway is this. You have 2-4 required fields. Each has a clear reason (not arbitrary). You can explain to someone why each field is required.

      -

      Alex: First, create a table. Then, for each issue type from Part 2, add 2-4 required fields. After that, write down at least 2 required fields. Think of it as a rail line: each stop confirms you are still on the right route before the next one.

      +

      Jamie: Let's pause on Chapter 6 Challenge Set. What should a learner take away from it?

      +

      Alex: Start with Chapter 6 Challenge Set: This is the first chapter where you edit files and create branches. The next useful detail is this: 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.

      +

      Alex: First, create one small branch change - edit a practice file on a new branch. Then, open a linked PR - use the PR template and include Closes XX. After that, pass required checks - respond to bot feedback until all required checks pass. Think of it as a rail line: each stop confirms you are still on the right route before the next one.

      +

      Jamie: Let's pause on Challenge 6.1 Step-by-Step: Create One Small Branch Change. What should a learner take away from it?

      +

      Alex: Here is the plain-English version of Challenge 6.1 Step-by-Step: Create One Small Branch Change. Edit one of the practice files and save your change on a new branch. Put another way, your Learning Room repository on GitHub.com, using the web editor.

      +

      Alex: The practical takeaway is this. 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. 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.

      +

      Alex: First, 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). Then, open the file and activate the pencil icon (Edit this file) button. After that, the file opens in the web editor. Make your change. For. Finally, keep your change small and focused. Edit only what the issue asks for. Treat it like a recipe: do not add the next ingredient until the previous one is actually in the bowl.

      +

      Jamie: Before we leave Challenge 6.1 Step-by-Step: Create One Small Branch Change, what is the practical point?

      +

      Alex: First, after editing, activate the Commit changes button (green button above the editor). Then, a dialog appears. In the Branch name field, type: fix/yourname-issueXX (replace yourname with your GitHub username, and XX with the issue number). After that, select Create a new branch for this commit and start a pull request. Finally, activate Propose changes. It is a checklist, but a meaningful one: every item creates evidence that the next step is safe.

      +

      Jamie: Let's pause on Challenge 6.2 Step-by-Step: Open a Linked PR. What should a learner take away from it?

      +

      Alex: This is where Challenge 6.2 Step-by-Step: Open a Linked PR becomes real: AI agents do not just deploy code directly; they submit pull requests. That matters in practice: Learning to edit a file, format it in Markdown, and review a PR today prepares you to audit and approve AI-generated changes tomorrow. The workshop is closer to rehearsal than lecture. You hear the move, try the move, and then check what changed.

      +

      Alex: The practical takeaway is this. "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". A summary of what you changed and why (at least 50 characters).

      +

      Alex: First, in the Title field, write a short description of your change. Then, in the Body field, use the PR template if one is provided. Make sure to. After that, verify the base branch is main and the compare branch is your fix/yourname-issueXX branch. Finally, activate the Create pull request button. It is a checklist, but a meaningful one: every item creates evidence that the next step is safe.

      -

      Jamie: Let's pause on Part 4: Design Your Optional Fields. What should a learner take away from it?

      -

      Alex: Here is the plain-English version of Design Your Optional Fields. Your task: Add optional fields that would be helpful but aren't blocking.

      -

      Alex: The practical takeaway is this. Information that's helpful but you could triage without it. Information that helps you prioritize or assign the issue. Information that provides missing context. Environment details (CPU, RAM, versions of dependencies). Screenshots or links. Workarounds the reporter has found.

      -

      Alex: First, brainstorm nice-to-have information. Then, example optional fields for a bug report. After that, write down at least 2 optional fields. Finally, for each field, decide. Treat it like a recipe: do not add the next ingredient until the previous one is actually in the bowl.

      -

      Jamie: Let's pause on Part 5: Write Field Placeholders and Help Text. What should a learner take away from it?

      -

      Alex: This is where Write Field Placeholders and Help Text becomes real: your task: For each field, write helpful placeholder or description text that guides the reporter. That matters in practice: For each required and optional field, draft. The workshop is closer to rehearsal than lecture. You hear the move, try the move, and then check what changed.

      -

      Alex: The practical takeaway is this. 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.

      -

      Alex: First, field label (the visible name). Then, description (short help text). After that, placeholder (example of what to type, for input/textarea fields). It is a checklist, but a meaningful one: every item creates evidence that the next step is safe.

      -

      Jamie: Let's pause on Part 6: Test Your Template Locally. What should a learner take away from it?

      -

      Alex: Keep the learner anchored in Test Your Template Locally. Your task: Create a draft YAML template file and test it with your screen reader.

      -

      Alex: The practical takeaway is this. Start with the frontmatter (name:, description:, title:, labels:). Add your fields in the body: section. Use appropriate field types (input, textarea, dropdown, checkboxes). Name it: [your-project-name]-template.yml. Save it to your desktop or a projects folder. Is the YAML syntax correct? (no red squiggles).

      -

      Alex: First, create a text file with your template in YAML format. Use Section 6 as a template. Then, save it locally (not yet in GitHub). After that, open it in VS Code and check. Finally, test the structure. It is like walking a hallway with named doors: read the sign, enter the right room, then confirm where you landed.

      -

      Jamie: Before we leave Part 6: Test Your Template Locally, what is the practical point?

      -

      Alex: First, with your screen reader. The rhythm is simple: orient, act, verify, then continue.

      +

      Jamie: Let's pause on Challenge 6.3 Step-by-Step: Pass Required Checks. What should a learner take away from it?

      +

      Alex: Keep the learner anchored in Challenge 6.3 Step-by-Step: Pass Required Checks. Read bot feedback, fix any issues it finds, and get all required checks to pass. This is the part to say slowly: the Conversation tab of your open pull request.

      +

      Alex: The practical takeaway is this. 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.

      +

      Alex: First, wait approximately 30 seconds after opening the PR. The bot posts a validation comment. Then, read the bot comment carefully. It checks. After that, if the bot reports failures. Finally, repeat step 3 until all required checks show a green checkmark. It is like walking a hallway with named doors: read the sign, enter the right room, then confirm where you landed.

      +

      Jamie: Before we leave Challenge 6.3 Step-by-Step: Pass Required Checks, what is the practical point?

      +

      Alex: First, when all checks pass, request a review from a peer or the facilitator. The rhythm is simple: orient, act, verify, then continue.

      +

      Alex: Keep the teaching thread moving. Start with Expected Outcomes. There is something to understand, something to try, and something that proves the try worked.

      +

      Alex: The practical takeaway is this. Student opens a focused PR that maps to one issue. Student uses Closes XX correctly. Student can interpret bot feedback and improve the PR.

      +

      Jamie: Let's pause on If You Get Stuck. What should a learner take away from it?

      +

      Alex: Start with If You Get Stuck. There is something to understand, something to try, and something that proves the try worked.

      +

      Alex: First, confirm your PR includes Closes XX in title or body. Then, check that changed files are only in learning-room/. After that, open the bot validation comment and resolve one required check at a time. Finally, if checks still fail, ask for peer or facilitator review with the exact error message. Think of it as a rail line: each stop confirms you are still on the right route before the next one.

      +

      Jamie: Before we leave If You Get Stuck, what is the practical point?

      +

      Alex: First, finished but not sure you did it right? Compare your work against the Challenge 6 reference solution. Treat it like a recipe: do not add the next ingredient until the previous one is actually in the bowl.

      -

      Jamie: Let's pause on Part 7: (Optional) Deploy to GitHub and Test with a Friend. What should a learner take away from it?

      -

      Alex: The reason (Optional) Deploy to GitHub and Test with a Friend matters is that your task: Upload your template to a GitHub repository and test it with a colleague or friend. That gives the learner a simple foothold: this is optional but powerful - real user testing is the best validation.

      -

      Alex: The practical takeaway is this. Create a test branch in a personal repo. Add your template file to.github/ISSUE TEMPLATE/. Push the branch. "Could you try filing an issue using this template?".

      -

      Alex: First, upload your template to a test repository. Then, ask a colleague or friend. After that, collect feedback. Finally, refine your template based on their feedback. The rhythm is simple: orient, act, verify, then continue.

      -

      Jamie: Let's pause on Part 8: Reflect on Your Template Design. What should a learner take away from it?

      -

      Alex: Start with Reflect on Your Template Design: Your task: Document what you learned from this exercise.

      -

      Alex: The practical takeaway is this. 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.

      -

      Alex: First, decision-making: Which field did you debate including? Why did you finally decide yes or no? Then, trade-offs: You can't ask for everything without overwhelming reporters. What information did you choose not to ask for? Why? After that, iteration: If you had user feedback (from Part 7), what did you learn? Finally, real-world readiness: Would you actually deploy this template to a real project? Think of it as a rail line: each stop confirms you are still on the right route before the next one.

      -

      Alex: Keep the teaching thread moving. Here is the plain-English version of Checkpoint. After completing Parts 1-8, you have. Put another way, you now understand the thinking that separates "a blank text box" from "structured, actionable contributions.". It is like learning a transit route. The names of the stops matter because they tell you whether you are still going the right direction.

      -

      Alex: The practical takeaway is this. Chosen a specific project to design. Identified issue patterns and common questions. Designed required fields (minimal, crucial information). Designed optional fields (helpful but not blocking).

      +

      Alex: Keep the teaching thread moving. Here is the plain-English version of Learning Moment. A great PR is small, linked to an issue, and easy to review. Put another way, faster feedback builds confidence and momentum. It is like learning a transit route. The names of the stops matter because they tell you whether you are still going the right direction.

      +

      Jamie: Let's pause on Why this feels achievable. What should a learner take away from it?

      +

      Alex: Start with Why this feels achievable. There is something to understand, something to try, and something that proves the try worked.

      +

      Alex: The practical takeaway is this. Scope is intentionally small. Feedback is immediate and specific. Success is visible (green checks + closed issue).

      +

      Alex: Keep the teaching thread moving. Keep the learner anchored in About Learning Cards in This Chapter. This chapter provides learning cards: expandable blocks that offer perspective-specific guidance for different ways of working. This is the part to say slowly: Not every card appears at every step.

      -

      Jamie: Let's pause on You've Completed the Template Exercises. What should a learner take away from it?

      -

      Alex: This is where You've Completed the Template Exercises becomes real: 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. That matters in practice: The agent generates YAML; you decide what questions to ask.

      -

      Alex: First, understand templates from the user perspective (Exercise A). Then, can create and deploy templates yourself (Exercise B). After that, know how to contribute upstream (Exercise C). Finally, can design templates with real thinking behind them (Exercise D). It is a checklist, but a meaningful one: every item creates evidence that the next step is safe.

      -

      Alex: Keep the teaching thread moving. Keep the learner anchored in 10. Day 2 Amplifier: The Template Builder Agent. Everything you just learned - field types, YAML structure, accessibility testing - is core GitHub knowledge. This is the part to say slowly: Now see how Accessibility Agents amplifies it.

      -

      Jamie: What stays the same when the tool changes?

      -

      Alex: The reason In VS Code matters is that then you copy, paste to.github/ISSUE TEMPLATE/your-template.yml, commit, and done.

      +

      Jamie: What should they understand before typing anything?

      +

      Alex: The reason Local Git Alternative: The Full Branch-Edit-PR Workflow matters is that if you cloned the learning-room in Block 0 and prefer working locally. That gives the learner a simple foothold: the web editor workflow (pencil button, "Propose changes") is the primary path taught in this chapter.

      +

      Alex: Treat examples as spoken recipes, not decorations. You may hear something like cd /Documents/learning-room; git checkout main; git pull origin main; git checkout -b fix/welcome-todos. code docs/welcome.md. Read the command, understand what it changes, then run it only when the repository state matches the lesson.

      +

      Alex: Keep the teaching thread moving. Start with What Is a Pull Request?: A pull request (PR) is a proposal to merge changes from one branch into another. The next useful detail is this.you open a PR to request that those changes be merged into the target branch (usually main). Think of it like entering a new building: first you find the lobby, then the room, then the door you actually need.

      +

      Alex: The practical takeaway is this. Edited a file directly on GitHub (web editor). Made changes in your fork. Made changes on a feature branch. What changed - a diff of every file.

      +

      Jamie: Let's pause on Navigating to Pull Requests. What should a learner take away from it?

      +

      Alex: Here is the plain-English version of Navigating to Pull Requests. Global pull requests dashboard: GitHub now shows a global pull requests page at github.com/pulls listing all open PRs across every repository you have access to. Put another way, 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).

      +

      Alex: The practical takeaway is this. 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.

      +

      Alex: First, d → "Repository navigation" landmark. Then, k to navigate tabs → "Pull requests, [N] open". After that, enter to open. Finally, vO+U → Landmarks → navigate to "Repository navigation". Treat it like a recipe: do not add the next ingredient until the previous one is actually in the bowl.

      +

      Jamie: Before we leave Navigating to Pull Requests, what is the practical point?

      +

      Alex: First, quick Nav K or VO+Right to navigate tabs → "Pull requests". Then, vO+Space to open. It is a checklist, but a meaningful one: every item creates evidence that the next step is safe.

      -

      Alex: Keep the teaching thread moving. Start with Why It Matters: The Template Builder does not teach you to design templates - Section 5 taught you that. The next useful detail is this: It automates the mechanical part: translating your decisions into working YAML. Think of it like entering a new building: first you find the lobby, then the room, then the door you actually need.

      -

      Jamie: Let's pause on Using the Template Builder. What should a learner take away from it?

      -

      Alex: Here is the plain-English version of Using the Template Builder. Next: Chapter 18: Fork and Contribute Back: Chapter 16: GitHub Copilot Related appendices: Appendix Q: GitHub Actions Appendix C: Markdown Reference.

      +

      Jamie: What should happen before anyone copies and runs it?

      +

      Alex: This is where From a PR notification becomes real: if you received a notification about a PR, follow the notification link directly to the PR page. That matters in practice: List and view pull requests from your terminal.

      +

      Alex: Treat examples as spoken recipes, not decorations. You may hear something like 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. Read the command, understand what it changes, then run it only when the repository state matches the lesson.

      +

      Jamie: Let's pause on Learning Cards: Navigating to Pull Requests. What should a learner take away from it?

      +

      Alex: Start with Learning Cards: Navigating to Pull Requests. There is something to understand, something to try, and something that proves the try worked.

      +

      Alex: The practical takeaway is this. 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. 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.

      +

      Alex: Keep the teaching thread moving. The reason The Pull Request List Page matters is that the PR list works identically to the Issues list. That gives the learner a simple foothold: for screen reader users, - PR list semantics: The PR list does not have individual ARIA item containers with per-item semantics. The interface gets friendlier when it stops being a wall of controls and starts being a set of named places.

      +

      Alex: The practical takeaway is this. 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.

      -

      Jamie: What should people carry with them after this?

      -

      Alex: Carry the map. Know what page or tool you are in, know which action you are taking, and know what confirmation should follow. If the confirmation is missing, pause. That pause is not wasted time; it is professional judgment.

      -

      Jamie: That is a better way to say it than just follow the steps.

      -

      Alex: Right. Steps matter, but understanding wins. That is episode 16. Next in the series is episode 17, where we keep building the same contributor muscles.

      -
      - +

      Jamie: Let's pause on Navigating the PR Tab Bar. What should a learner take away from it?

      +

      Alex: Start with Navigating the PR Tab Bar: The Conversation, Commits, and Files changed tabs are in a "Pull request navigation tabs" landmark. The next useful detail is this: The three tabs - Conversation, Commits, and Files changed - appear just below the PR title.

      +

      Alex: The practical takeaway is this. 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.

      +

      Alex: First, press D → navigate to "Pull request navigation tabs". Then, press ← or → arrow keys to move between tab options. After that, press Enter to activate a tab. Finally, vO+U → Landmarks → "Pull request navigation tabs". Think of it as a rail line: each stop confirms you are still on the right route before the next one.

      +

      Jamie: Before we leave Navigating the PR Tab Bar, what is the practical point?

      +

      Alex: First, vO+Right to move between tabs. Then, vO+Space to activate. Treat it like a recipe: do not add the next ingredient until the previous one is actually in the bowl.

      +

      Jamie: Let's pause on PR Description. What should a learner take away from it?

      +

      Alex: Start with PR Description. There is something to understand, something to try, and something that proves the try worked.

      +

      Alex: First, 2 → navigate to "Description" h2 heading. Then, ↓ to read the description. After that, markdown renders as semantic HTML - headings, lists, code blocks are fully accessible. Treat it like a recipe: do not add the next ingredient until the previous one is actually in the bowl.

      +

      Jamie: Let's pause on Status Checks Section. What should a learner take away from it?

      +

      Alex: This is where Status Checks Section becomes real: below the description, the status checks summary shows whether automated tests passed. That matters in practice: Status checks appear as a coloured banner below the PR description - green tick for passed, red X for failed, yellow spinner for running.

      +

      Alex: The practical takeaway is this. "All checks have passed" / "Some checks failed" / "Checks pending". A "Show all checks" button or link.

      +

      Alex: First, press H or 2 to find the "Checks" or "Status checks" heading. Then, press K to navigate links for individual check names. After that, press Enter on a check to see its details. Finally, quick Nav H or VO+Cmd+H to jump to the "Checks" or "Status checks" heading. It is a checklist, but a meaningful one: every item creates evidence that the next step is safe.

      +

      Jamie: Before we leave Status Checks Section, what is the practical point?

      +

      Alex: First, quick Nav K to navigate check name links. Then, vO+Space on a check to see its details. It is like walking a hallway with named doors: read the sign, enter the right room, then confirm where you landed.

      -

      Episode 17: Accessibility Agents

      -

      55 agents across 3 teams and 5 platforms, 54+ slash commands, custom agents, and agentic accessibility workflows.

      -

      Based on: Chapter 19: Accessibility Agents

      -

      Audio and transcript are being regenerated for this episode.

      -
      -Read Transcript - Episode 17: Accessibility Agents - -

      Transcript

      -

      Alex: Welcome back to Git Going with GitHub. This is episode 17: Accessibility Agents. I am Alex, and today we are turning Accessibility Agents from a list of instructions into a working mental model.

      -

      Jamie: And I am Jamie. I will stop us whenever the instructions sound simple on paper but might feel different with a keyboard and screen reader.

      +

      Alex: Keep the teaching thread moving. Keep the learner anchored in Review Comments. Each review comment thread is an h3. A good GitHub workflow is like a well-run meeting: everyone knows the topic, the next action, and who has the floor.

      +

      Alex: The practical takeaway is this. 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.

      +

      Jamie: Let's pause on Resolving conversations. What should a learner take away from it?

      +

      Alex: The reason Resolving conversations matters is that when a review comment has been addressed, you can mark the conversation as resolved. That gives the learner a simple foothold: resolved conversations are still accessible - they collapse but can be expanded again.

      +

      Alex: First, navigate to the conversation thread (3 to jump between comment headings). Then, tab to the end of the thread to find the "Resolve conversation" button. After that, press Enter to mark it resolved. Finally, the conversation collapses and shows as "Resolved". The rhythm is simple: orient, act, verify, then continue.

      +

      Alex: Keep the teaching thread moving. Start with Learning Cards: Reading the Conversation Tab. There is something to understand, something to try, and something that proves the try worked.

      +

      Alex: The practical takeaway is this. 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. 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.

      -

      Alex: 55 agents across 3 teams and 5 platforms, 54+ slash commands, custom agents, and agentic accessibility workflows. That is the surface description. Underneath it, we are building judgment: where to focus, what to ignore, and how to verify the result.

      -

      Jamie: So we are not using the audio as a shortcut around learning. We are using it to make the learning easier to enter.

      -

      Alex: Yes. A good audio lesson gives someone enough context to try the work with confidence, even before they open the written material.

      +

      Jamie: Let's pause on Reading the Checks Tab. What should a learner take away from it?

      +

      Alex: Here is the plain-English version of Reading the Checks Tab. The Checks tab shows the status of automated tests, CI workflows, and other verification processes running on your PR. Put another way, it helps you verify whether your changes pass all required tests before merging.

      +

      Alex: The practical takeaway is this. Navigate through the check steps with K or Tab. Activate a step for more details.

      +

      Alex: First, navigate to the "Pull request tabs" landmark (D). Then, navigate between tab links (K or Tab) and activate "Checks". After that, press D to jump to the "check suites" section - this moves focus to the collapsed details button of the first check. Finally, press B or Tab to navigate between check buttons; each button is labeled with the check's name. Treat it like a recipe: do not add the next ingredient until the previous one is actually in the bowl.

      +

      Jamie: Before we leave Reading the Checks Tab, what is the practical point?

      +

      Alex: First, press Enter or Space to expand a check and reveal its logs. Then, for a summary view: press D to navigate to the "check run summary" section. After that, vO+U - Landmarks - "Pull request tabs" - activate "Checks". Finally, vO+U - Landmarks - navigate to "check suites" section. It is a checklist, but a meaningful one: every item creates evidence that the next step is safe.

      +

      Alex: Keep the teaching thread moving. Start with Learning Cards: Reading the Checks Tab. There is something to understand, something to try, and something that proves the try worked.

      +

      Alex: The practical takeaway is this. 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. 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.

      +

      Jamie: Let's pause on Reading the Files Changed Tab. What should a learner take away from it?

      +

      Alex: Keep the learner anchored in Reading the Files Changed Tab. the learner will read diffs - the before/after state of every file that changed. This is the part to say slowly: This guide uses GitHub's improved Files Changed experience.

      -

      Jamie: Okay, set the room for us. What are we walking into?

      -

      Alex: Start with 55 AI Agents Across 3 Teams and 5 Platforms: Day 2, Block 3 Material Before you read this guide: Accessibility Agents is a growing open source ecosystem: 55 AI-powered agents organized into three teams (Accessibility, GitHub Workflow, and Developer Tools), running on five platforms (GitHub Copilot,. The next useful detail is this: This chapter introduces the full landscape.

      -

      Alex: The next layer is this. Start with Core Prerequisites (Required for All Agents). There is something to understand, something to try, and something that proves the try worked.

      -

      Alex: The practical anchors are these. [ ] Chapter 0: Pre-Workshop Setup - Git, VS Code, and GitHub account. [ ] Chapter 16: GitHub Copilot - GitHub Copilot Chat installed and working. [ ] GitHub Copilot access (Copilot Free tier is enough for this workshop). [ ].github/agents/ folder exists in your repository (or will create custom agents).

      -

      Alex: A solid pull request habit is to separate three questions: what changed, why it changed, and what still needs review. That keeps the conversation useful instead of noisy.

      -

      Jamie: What is the one idea that makes the next few steps less mysterious?

      -

      Alex: This is where Agent Prerequisites (The "Skill First" Principle) becomes real: every agent automates a skill you should already know by hand. That matters in practice: Before using any agent, verify you have done the corresponding manual work.

      +

      Jamie: Let's pause on File Tree (left panel). What should a learner take away from it?

      +

      Alex: The reason File Tree (left panel) matters is that the file tree lists every changed file. That gives the learner a simple foothold: use it to jump directly to a specific file's diff.

      +

      Alex: The practical takeaway is this. 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.

      +

      Alex: First, d → navigate to "File tree" region. Then, ↑/↓ to navigate the file list. After that, enter to jump to that file's diff. Finally, vO+U → Landmarks → navigate to "File tree" region. The rhythm is simple: orient, act, verify, then continue.

      +

      Jamie: Before we leave File Tree (left panel), what is the practical point?

      +

      Alex: First, vO+Down to move through the file list. Then, vO+Space to jump to that file's diff. Think of it as a rail line: each stop confirms you are still on the right route before the next one.

      +

      Jamie: Let's pause on The Diff for a File. What should a learner take away from it?

      +

      Alex: Start with The Diff for a File. There is something to understand, something to try, and something that proves the try worked.

      +

      Alex: The practical takeaway is this. 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.

      +

      Alex: Keep the teaching thread moving. Start with Lines in a diff are read as. There is something to understand, something to try, and something that proves the try worked.

      +

      Alex: The practical takeaway is this. + Added line - line that was added. Removed line - line that was removed. Context line - unchanged line shown for context.

      -

      Alex: Now bring the learner back to the room. Keep the learner anchored in Workshop Recommendation (Chapter 19 / Challenge 15). Chapter 19 is the agent exploration and hands-on validation chapter - where students match agents to skills they already have and learn how to trust, evaluate, and improve AI-powered workflow automation. This is the part to say slowly: It supports Challenge 15: Meet the Agents.

      -

      Alex: For a learner, the useful signals are these. There are 3 guided + 1-2 optional contribution challenges. Automation check: none (agent output requires human judgment before use). The evidence is issue comment showing agent output and your evaluation of it. The pattern is explore, validate, read internals, optionally contribute.

      -

      Jamie: What is the ordered workflow?

      -

      Alex: Start with Challenge 15 Set. There is something to understand, something to try, and something that proves the try worked.

      -

      Alex: First, agent Discovery Mapping - identify 3-5 agents that match skills you already have from Day 1. Then, agent Skill Validation - run one agent and evaluate its output against your manual experience. After that, agent Instructions Deep Dive - read one agent's source file and assess what it can and cannot do. Finally, improve an Existing Agent (optional hackathon) - find a gap in an agent's instructions and fix it via PR. The rhythm is simple: orient, act, verify, then continue.

      -

      Jamie: Give me the sequence, because order matters here.

      -

      Alex: First, propose a New Agent (optional hackathon) - file an issue proposing an agent for an uncovered workflow. Think of it as a rail line: each stop confirms you are still on the right route before the next one.

      -

      Alex: The useful habit is simple: orient first, act second, verify third. That pause before acting is part of the work.

      -

      Jamie: How would you walk the room through that step by step?

      -

      Alex: Start with Challenge 15.1 Step-by-Step: Agent Discovery Mapping: Map your Day 1 manual skills to specific agents in the ecosystem so you know which agents you are ready to use. The next useful detail is this: GitHub.com - the accessibility-agents repository and your assigned Challenge 15 issue. Think of it like entering a new building: first you find the lobby, then the room, then the door you actually need.

      -

      Alex: On the ground, that means a few things. @daily-briefing (maps to repository and issue awareness from Chapters 2-4). @issue-tracker (maps to Chapter 4 issue workflow). @pr-review (maps to Chapter 6 and Chapter 14 review workflow). Example: You filed issues manually (Ch 4) - you can use @issue-tracker.

      -

      Alex: First, fork the accessibility-agents repository on GitHub.com. Then, open the repository and navigate to Section 3 of the README (or this chapter's Section 3 below) to see the full list of 55 agents organized by team. After that, read through the agent names and descriptions. For each one, ask yourself: "Have I done this task manually during the workshop?". Finally, identify 3-5 agents that match workflows you already practiced. Think of it as a rail line: each stop confirms you are still on the right route before the next one.

      -

      Jamie: What does the learner do first, second, and then after that?

      -

      Alex: First, open your assigned Challenge 15 issue. Then, post a discovery mapping comment using this format. Treat it like a recipe: do not add the next ingredient until the previous one is actually in the bowl.

      +

      Jamie: Let's pause on Navigating the diff with a screen reader. What should a learner take away from it?

      +

      Alex: This is where Navigating the diff with a screen reader becomes real: each file's diff shows added lines in green and removed lines in red. That matters in practice: Scroll the page to read through changes.

      +

      Alex: The practical takeaway is this. 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.

      +

      Alex: First, t to jump to the next diff table. Then, switch to Focus Mode: Insert+Space (NVDA) or Insert+Z (JAWS). After that, ctrl+Alt+↓ to move down one row (next diff line), Ctrl+Alt+↑ to move up. Finally, ctrl+Alt+→ to read across columns (line number change type content). It is a checklist, but a meaningful one: every item creates evidence that the next step is safe.

      +

      Jamie: Before we leave Navigating the diff with a screen reader, what is the practical point?

      +

      Alex: First, the screen reader reads: "+ Add accessible name to submit button". Then, collapsed sections contain unchanged code. Focus the expand/disclosure control and activate it (Enter or Space) to reveal the hidden lines. After that, t or VO+U → Tables → select the diff table. Finally, vO+Shift+Down to enter the table. It is like walking a hallway with named doors: read the sign, enter the right room, then confirm where you landed.

      +

      Jamie: Let's pause on Placing an inline comment on a diff line. What should a learner take away from it?

      +

      Alex: Keep the learner anchored in Placing an inline comment on a diff line. Hover over any line in the diff - a blue + button appears on the left margin. This is the part to say slowly: Click it to open a comment box for that line.

      +

      Alex: The practical takeaway is this. 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.

      +

      Alex: First, navigate to the specific line in the diff (using the table navigation above). Then, while focused on that line, a comment button appears - press Enter or Space to activate it. After that, a comment box opens below the line. Finally, focus Mode → type your comment. It is like walking a hallway with named doors: read the sign, enter the right room, then confirm where you landed.

      +

      Jamie: Before we leave Placing an inline comment on a diff line, what is the practical point?

      +

      Alex: First, tab to Add single comment button (instant comment) OR Start a review (to batch comments). The rhythm is simple: orient, act, verify, then continue.

      +

      Jamie: Let's pause on Multi-line comment (Windows). What should a learner take away from it?

      +

      Alex: The reason Multi-line comment (Windows) matters is that screen reader users (VoiceOver - macOS).

      +

      Alex: First, focus the first line you want to comment on. Then, press Shift+↓ to extend the selection to additional lines. After that, a comment button appears - activate it. Finally, the comment applies to the full range of selected lines. The rhythm is simple: orient, act, verify, then continue.

      +

      Jamie: Before we leave Multi-line comment (Windows), what is the practical point?

      +

      Alex: First, navigate to the specific line in the diff (using the table navigation above). Then, while focused on that line, VO+Space on the comment button that appears. After that, a comment box opens below the line. Finally, vO+Shift+Down to interact with the text area, then type your comment. Think of it as a rail line: each stop confirms you are still on the right route before the next one.

      -

      Jamie: Turn that into a path someone can follow.

      -

      Alex: Here is the plain-English version of Challenge 15.2 Step-by-Step: Agent Skill Validation. Run one agent, read its output, and evaluate whether it matches your manual experience. Put another way, VS Code with the accessibility-agents repository cloned and Copilot Chat open.

      -

      Alex: Here is what that changes in practice. @daily-briefing morning briefing. @issue-tracker find open issues labeled good-first-issue in accessibility-agents. @pr-review show open PRs in accessibility-agents.

      -

      Alex: First, clone your fork of accessibility-agents to VS Code (or open it in github.dev). Then, open Copilot Chat: Ctrl+Shift+I (Mac: Cmd+Shift+I). After that, choose one agent from your discovery list. If unsure, start with @daily-briefing or @issue-tracker. Finally, run it with a simple prompt. Treat it like a recipe: do not add the next ingredient until the previous one is actually in the bowl.

      -

      Jamie: Let's pause on Challenge 15.2 Step-by-Step: Agent Skill Validation. What should a learner take away from it?

      -

      Alex: First, read the agent's output carefully. Take a moment to think about what you expected. Then, open your assigned Challenge 15 issue and post an evaluation comment. It is a checklist, but a meaningful one: every item creates evidence that the next step is safe.

      -

      Jamie: Let's pause on Challenge 15.3 Step-by-Step: Agent Instructions Deep Dive. What should a learner take away from it?

      -

      Alex: This is where Challenge 15.3 Step-by-Step: Agent Instructions Deep Dive becomes real: read one agent's source file to understand what instructions it follows, what tools it can use, and what mistakes it could make. That matters in practice: VS Code or GitHub.com - reading files in the accessibility-agents repository.

      -

      Alex: The room should hear these as checkpoints. What is this agent trying to do? (its purpose). What tools does it have access to? (tool permissions). What constraints or guardrails are in the instructions?

      -

      Alex: First, in the accessibility-agents repository, navigate to the.github/ folder (or wherever agent definition files are stored). Then, open one.agent.md or.prompt.md file for an agent you used or are curious about. After that, read the file and identify. Finally, think critically: could this agent make a mistake? What kind? It is a checklist, but a meaningful one: every item creates evidence that the next step is safe.

      -

      Jamie: Before we leave Challenge 15.3 Step-by-Step: Agent Instructions Deep Dive, what is the practical point?

      -

      Alex: First, open your assigned Challenge 15 issue and post your analysis. It is like walking a hallway with named doors: read the sign, enter the right room, then confirm where you landed.

      -

      Jamie: Where do you want a learner to place their attention here?

      -

      Alex: Keep the learner anchored in Optional Extensions 15.4-15.5 (Hackathon). Extension 15.4: Improve an Existing Agent (45 min). This is the part to say slowly: Extension 15.5: Propose a New Agent (60 min).

      -

      Alex: These are the details that keep the idea from floating away. Find an agent whose instructions have a gap (use Section 6 suggestions or file an issue). Fork the repo, edit the agent's.agent.md file. Get a facilitator review. Open a PR with your improvement.

      +

      Jamie: Let's pause on Multi-line comment (macOS). What should a learner take away from it?

      +

      Alex: Start with Multi-line comment (macOS). There is something to understand, something to try, and something that proves the try worked.

      +

      Alex: First, focus the first line and Shift+↓ to extend the selection. Then, vO+Space on the comment button that appears. After that, the comment applies to the full range of selected lines. Think of it as a rail line: each stop confirms you are still on the right route before the next one.

      +

      Jamie: Let's pause on Viewing comments within the diff. What should a learner take away from it?

      +

      Alex: Here is the plain-English version of Viewing comments within the diff. Inline comments appear as expandable threads within the diff table. Put another way, navigate to them with 3 (they are h3 headings).

      +

      Alex: Keep the teaching thread moving. Start with Learning Cards: Reading the Files Changed Tab. There is something to understand, something to try, and something that proves the try worked.

      +

      Alex: The practical takeaway is this. 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. 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.

      -

      Alex: Before the learner moves on. The reason Completing Challenge 15: Submit Your Evidence matters is that your evidence is the Challenge 15 issue comments for 15.1, 15.2, and 15.3. That gives the learner a simple foothold: for optional extensions, your PR or proposal issue is the evidence. The interface gets friendlier when it stops being a wall of controls and starts being a set of named places.

      -

      Jamie: What would you say to someone who is already bracing for this to be too much?

      -

      Alex: Start with Expected Outcomes. There is something to understand, something to try, and something that proves the try worked.

      -

      Alex: A few details make that real. Student can map personal Day 1 skills to specific agents in the ecosystem. Student understands the Skill First, Agent Second principle and can articulate why agent output requires human judgment. Student can read agent instructions and evaluate what an agent can and cannot do. Student has used at least one agent and verified it against manual skills. (Optional) Student has contributed to the accessibility-agents ecosystem with a fix, improvement, or proposal.

      -

      Jamie: Let's pause on If You Get Stuck. What should a learner take away from it?

      -

      Alex: Here is the plain-English version of If You Get Stuck. Continue learning: The GitHub Skills courses Build Applications with Copilot Agent Mode and Expand Your Team with Copilot explore agent-powered development workflows. Put another way, see Appendix Z for the full catalog.

      -

      Alex: First, cannot find an agent that matches your skills? Start with @daily-briefing or @issue-tracker - those build directly on Chapter 2-5 material. If you have not done those manual steps yet, go back to those chapters first. Then, agent output does not make sense? That is the right response. Paste the output in an issue comment along with your confusion. That is valuable feedback - the agent may need better instructions or guardrails. After that, cannot access the agents in Copilot Chat? Verify: Is Copilot Chat extension installed (not just base Copilot)? Are you signed in to GitHub in VS Code? Does.github/agents/ folder exist in your cloned repository? Finally, repository will not clone? Use the terminal: git clone https://github.com/[your-username]/accessibility-agents.git then open the folder in VS Code. Treat it like a recipe: do not add the next ingredient until the previous one is actually in the bowl.

      -

      Jamie: Before we leave If You Get Stuck, what is the practical point?

      -

      Alex: First, ask facilitator to show them what agent you wanted to run, what output you got, and what you expected. Then, finished but not sure you did it right? Compare your work against the Challenge 15 reference solution. It is a checklist, but a meaningful one: every item creates evidence that the next step is safe.

      +

      Jamie: Let's pause on Tool Cards: Open a Pull Request. What should a learner take away from it?

      +

      Alex: Keep the learner anchored in Tool Cards: Open a Pull Request. VS Code Desktop (GitHub Pull Requests extension).

      +

      Alex: First, push your branch, then click the Compare & pull request banner (or go to Pull requests New pull request ). Then, set base branch to main, compare branch to yours. After that, fill in the title and description, then click Create pull request. Finally, after committing changes, click the Source Control icon. It is like walking a hallway with named doors: read the sign, enter the right room, then confirm where you landed.

      +

      Jamie: Before we leave Tool Cards: Open a Pull Request, what is the practical point?

      +

      Alex: First, click Create Pull Request in the Source Control panel header. Then, fill in details and submit. After that, press Ctrl+Shift+P, type GitHub Pull Requests: Create Pull Request. Finally, select base and compare branches. The rhythm is simple: orient, act, verify, then continue.

      +

      Alex: Treat examples as spoken recipes, not decorations. You may hear something like git push -u origin your-branch; gh pr create --title "Your title" --body "Description". Read the command, understand what it changes, then run it only when the repository state matches the lesson.

      +

      Jamie: Let's pause on From the web editor workflow (editing a file on GitHub). What should a learner take away from it?

      +

      Alex: Start with From the web editor workflow (editing a file on GitHub). There is something to understand, something to try, and something that proves the try worked.

      +

      Alex: First, you edited a file → GitHub showed a "Propose changes" form. Then, you named your branch and activated "Propose changes". After that, GitHub redirected you to the "Open a pull request" page. The rhythm is simple: orient, act, verify, then continue.

      +

      Jamie: Let's pause on From a fork or feature branch. What should a learner take away from it?

      +

      Alex: Start with From a fork or feature branch: Screen reader users (NVDA / JAWS - Windows). The next useful detail is this: Screen reader users (VoiceOver - macOS).

      +

      Alex: First, navigate to the repository on GitHub. Then, if you recently pushed, a yellow banner "Compare & pull request" appears at the top - click it. After that, if no banner appears: click the Pull requests tab → click the green New pull request button. Finally, use the branch dropdowns to choose your base branch (what to merge into) and your compare branch (your changes). Think of it as a rail line: each stop confirms you are still on the right route before the next one.

      +

      Jamie: Before we leave From a fork or feature branch, what is the practical point?

      +

      Alex: First, click Create pull request. Then, navigate to the repository. After that, a "Compare & pull request" banner may appear (if you recently pushed) - activate it. Finally, oR: Navigate to Pull Requests tab → "New pull request". Treat it like a recipe: do not add the next ingredient until the previous one is actually in the bowl.

      -

      Jamie: If I am listening before the workshop starts, what should settle in my mind first?

      -

      Alex: This is where Learning Moment becomes real: the 55 agents exist because someone did the manual work first, then automated the repetitive parts. That matters in practice: As you explore agents, you are not just learning tools - you are learning what automation looks like when it is built on real expertise and real constraints.

      -

      Jamie: Let's pause on Learning Pattern Used in This Chapter. What should a learner take away from it?

      -

      Alex: Start with Learning Pattern Used in This Chapter. There is something to understand, something to try, and something that proves the try worked.

      -

      Alex: First, map your existing skills to available tools (discovery before action). Then, run one tool and evaluate its output critically (trust but verify). After that, read the source to understand capabilities and limits (internals matter). Finally, contribute improvements based on your evaluation (close the feedback loop). It is like walking a hallway with named doors: read the sign, enter the right room, then confirm where you landed.

      -

      Jamie: Give me the version that sounds like an instructor, not a manual.

      -

      Alex: The reason Capstone: Share Your Feedback (The Most Important Task!) matters is that you have now explored the full agent ecosystem, completed the workshop, and have valuable perspective on what worked, what confused you, and what we should improve for the next cohort. That gives the learner a simple foothold: your feedback directly shapes the future of this project.

      +

      Jamie: How do you keep commands from becoming magic words?

      +

      Alex: Here is the plain-English version of Description field. Copilot can write your PR description: If your account has Copilot access, a "Copilot actions" button appears in the description toolbar. Put another way, 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.

      +

      Alex: Treat examples as spoken recipes, not decorations. You may hear something like Step 1: Tab to the body text area; Step 2: Focus Mode → type using the PR template (if provided). 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 for the dismiss control; Related Issues; Closes 42; Testing; - Tested with NVDA + Chrome on Windows 11; -. Read the command, understand what it changes, then run it only when the repository state matches the lesson.

      +

      Jamie: Let's pause on Setting a Draft PR. What should a learner take away from it?

      +

      Alex: This is where Setting a Draft PR becomes real: if your work is not finished, open as a Draft.

      +

      Alex: First, after filling in the form, find the dropdown arrow next to "Create pull request". Then, select "Create draft pull request". After that, this signals to reviewers that it is not ready for formal review yet. It is a checklist, but a meaningful one: every item creates evidence that the next step is safe.

      +

      Alex: Keep the teaching thread moving. Keep the learner anchored in Draft Pull Requests - Full Lifecycle. A draft pull request is a PR explicitly marked as a work in progress. This is the part to say slowly: It is visible to the team, can receive comments, and runs CI - but is blocked from being merged until you mark it ready. A good GitHub workflow is like a well-run meeting: everyone knows the topic, the next action, and who has the floor.

      -

      Alex: Here is the practical turn. Start with Submit Workshop Feedback: Use the Workshop Feedback form to share. The next useful detail is this: Answer as much or as little as you're comfortable sharing.

      -

      Alex: That becomes easier when you listen for these cues. Which agents stood out? (Most useful or surprising). Which agents confused you? (What would make them better). Was the chapter progression logical? (Did earlier chapters prepare you for later ones). Accessibility experience (If applicable - did any assistive technology work/fail?).

      -

      Jamie: Let's pause on 1. The Principle: Skill First, Agent Second. What should a learner take away from it?

      -

      Alex: Here is the plain-English version of 1. The Principle: Skill First, Agent Second. Accessibility Agents is not a way to skip learning GitHub. Put another way, it is a way to amplify skills you have already built through deliberate practice.

      -

      Alex: That shows up in the workshop in a few specific ways. Verify that the agent's output is correct. Catch when the agent misses context that only you have. Edit the agent's drafts into something worth posting under your name. Know when the agent is confidently wrong.

      -

      Alex: Keep the thread going. This is where Every agent has a manual prerequisite. If you have not done the corresponding skill by hand, the agent is not ready for you yet - and you are not ready for it becomes real: this applies across all three teams and all 55 agents. That matters in practice: Before running any agent, the facilitator asks the same question. The workshop is closer to rehearsal than lecture. You hear the move, try the move, and then check what changed.

      -

      Alex: The parts worth keeping in working memory are these. GitHub Workflow agents automate repository navigation, issue triage, PR review, and contribution analytics - skills you practiced on Day 1. Accessibility agents automate WCAG auditing, contrast checking, keyboard navigation review, and document scanning - knowledge from your accessibility training and the standards in Appendix C. Developer Tools agents automate accessible coding patterns for Python, wxPython, and desktop applications - skills from your development experience.

      +

      Jamie: Let's pause on When to use a draft. What should a learner take away from it?

      +

      Alex: Start with When to use a draft. There is something to understand, something to try, and something that proves the try worked.

      +

      Alex: The practical takeaway is this. You want to show your approach and get early feedback before finishing. You need CI to run but don't want accidental merges. You are working across multiple days and want your progress visible. You want to pair with a collaborator on the work.

      +

      Alex: Keep the teaching thread moving. Start with What a draft PR does differently. There is something to understand, something to try, and something that proves the try worked.

      +

      Alex: The practical takeaway is this. The merge button is disabled - even an authorized maintainer cannot merge a draft. The PR header shows a grey "Draft" badge instead of the green "Open" badge. Reviewers are not auto-notified (no review requests are sent until ready). CI workflows still run normally.

      +

      Jamie: Let's pause on Mark a draft ready for review. What should a learner take away from it?

      +

      Alex: Start with Mark a draft ready for review. There is something to understand, something to try, and something that proves the try worked.

      +

      Alex: First, open the PR. Then, navigate to the "Reviewers" sidebar or scroll to bottom of the Conversation tab. After that, find and activate the "Ready for review" button. Finally, the draft badge changes to "Open" and reviewers are notified. Treat it like a recipe: do not add the next ingredient until the previous one is actually in the bowl.

      -

      Jamie: Let's pause on Learning Cards: Skill First, Agent Second. What should a learner take away from it?

      -

      Alex: Start with Learning Cards: Skill First, Agent Second. There is something to understand, something to try, and something that proves the try worked.

      -

      Alex: The practical takeaway is this. Before using any agent, verify you can do the task manually -- for @daily-briefing, confirm you can navigate Issues and PRs on GitHub.com with keyboard shortcuts (j/k to move, Enter to open). Agent output appears in Copilot Chat -- press Alt+F2 to open Accessible View and read the full response with arrow keys before acting on it. If an agent produces something you do not understand, stop and learn the manual skill first from the relevant chapter. Agent responses appear in the Copilot Chat panel -- drag the panel wider or use Alt+F2 (Accessible View) for a larger, cleaner reading pane. Each agent's instructions are in a.agent.md file you can open in VS Code and read at your preferred zoom level before invoking the agent. The agent ecosystem table in Section 3 uses standard Markdown tables that scale with your editor font size.

      -

      Alex: Another way to ground it. The reason Quick Install (One Command) matters is that accessibility Agents now ships with a one-liner installer that sets up all 55 agents for your platform.

      -

      Jamie: What should they understand before typing anything?

      -

      Alex: Start with macOS / Linux. There is something to understand, something to try, and something that proves the try worked.

      -

      Alex: Treat examples as spoken recipes, not decorations. You may hear something like curl -fsSL https://raw.githubusercontent.com/Community-Access/accessibility-agents/main/install.sh bash. Read the command, understand what it changes, then run it only when the repository state matches the lesson.

      +

      Jamie: Let's pause on Convert an open PR to draft (after opening). What should a learner take away from it?

      +

      Alex: This is where Convert an open PR to draft (after opening) becomes real: GitHub CLI (gh) alternative - draft PR lifecycle. That matters in practice: Manage draft PRs from your terminal. The workshop is closer to rehearsal than lecture. You hear the move, try the move, and then check what changed.

      +

      Alex: First, in the right sidebar, find the "Reviewers" section. Then, look for the "Convert to draft" link (below the review status). After that, confirm in the dialog - this removes merge eligibility until you mark it ready again. It is a checklist, but a meaningful one: every item creates evidence that the next step is safe.

      +

      Alex: Treat examples as spoken recipes, not decorations. You may hear something like Create a draft PR; gh pr create --draft --title "WIP: Add carousel keyboard nav"; Mark a draft ready for review; gh pr ready 42; Check PR status (shows draft state); gh pr view 42; List only draft PRs; gh pr list --draft. Read the command, understand what it changes, then run it only when the repository state matches the lesson.

      +

      Jamie: Let's pause on Learning Cards: Opening a Pull Request. What should a learner take away from it?

      +

      Alex: Start with Learning Cards: Opening a Pull Request. There is something to understand, something to try, and something that proves the try worked.

      +

      Alex: The practical takeaway is this. After editing a file on GitHub, the "Propose changes" form has a branch name field and a commit message field; press Tab to move between them. On the "Open a pull request" page, press F to jump to the Title field; Tab moves to the Description text area. Press Ctrl+Enter from inside the description text area to submit the PR without finding the Create button. The "Compare & pull request" yellow banner appears at the top of the repo after a recent push; at high zoom it may span the full width of the page. The branch comparison dropdowns (base and compare) use small text; zoom in on the area above the diff preview to read them. Draft PR: look for the dropdown arrow next to the green "Create pull request" button to switch to "Create draft pull request".

      +

      Jamie: Let's pause on Requesting reviewers. What should a learner take away from it?

      +

      Alex: The reason Requesting reviewers matters is that from the sidebar Reviewers section. That gives the learner a simple foothold: why some reviews are requested automatically: A file called CODEOWNERS in many repositories maps file paths to specific people or teams.

      +

      Alex: First, navigate to "Reviewers" heading (3 or H). Then, activate the gear button. After that, type a username in the search field. Finally, select from the dropdown. The rhythm is simple: orient, act, verify, then continue.

      +

      Jamie: Before we leave Requesting reviewers, what is the practical point?

      +

      Alex: First, escape to save. Think of it as a rail line: each stop confirms you are still on the right route before the next one.

      -

      Alex: This is the part worth saying out loud. Here is the plain-English version of Windows (PowerShell). The installer detects which AI tools you have installed (VS Code with Copilot, Claude Code, Gemini CLI, Claude Desktop, Codex CLI) and configures the appropriate agent files for each platform. Put another way, to uninstall, run the corresponding uninstall script from the repository. It is like learning a transit route. The names of the stops matter because they tell you whether you are still going the right direction.

      -

      Jamie: Let's pause on Workshop Setup (Fork and Clone). What should a learner take away from it?

      -

      Alex: This is where Workshop Setup (Fork and Clone) becomes real: for the workshop, you will also fork and clone the repository so you can make contributions. That matters in practice: If Copilot Chat works, the agents work.

      -

      Alex: First, fork accessibility-agents to your GitHub account (you did this on Day 1 or Day 2 morning). Then, clone your fork. After that, open in VS Code: navigate to the folder and run code. (or File, then Open Folder). Finally, open Copilot Chat: Ctrl+Shift+I. It is a checklist, but a meaningful one: every item creates evidence that the next step is safe.

      -

      Jamie: Before we leave Workshop Setup (Fork and Clone), what is the practical point?

      -

      Alex: First, test: type @daily-briefing morning briefing and press Enter. It is like walking a hallway with named doors: read the sign, enter the right room, then confirm where you landed.

      -

      Alex: Treat examples as spoken recipes, not decorations. You may hear something like git clone https://github.com/[your-username]/accessibility-agents.git. Read the command, understand what it changes, then run it only when the repository state matches the lesson.

      -

      Alex: That connects to another useful point. Start with Prerequisites. There is something to understand, something to try, and something that proves the try worked.

      -

      Alex: The practical takeaway is this. GitHub Copilot Chat extension installed (see GitHub Copilot: Installation). Signed in to GitHub via VS Code. A workspace open containing.github/agents/ folder with.agent.md files.

      +

      Jamie: Let's pause on Submitting a Review. What should a learner take away from it?

      +

      Alex: Start with Submitting a Review: When you are asked to review a PR, you have three options.

      +

      Alex: The practical takeaway is this. Comment - leave feedback without a verdict; does not block merging. Approve - signal you are satisfied; often required before merge. Request changes - indicate changes must be addressed; blocks merge until resolved.

      +

      Alex: Keep the teaching thread moving. Here is the plain-English version of Starting a review. On the Files Changed tab, when you add inline comments, choose "Start a review" instead of "Add single comment." This batches all your comments into one review submission. It is like learning a transit route. The names of the stops matter because they tell you whether you are still going the right direction.

      +

      Jamie: Let's pause on Completing and submitting a review. What should a learner take away from it?

      +

      Alex: This is where Completing and submitting a review becomes real: after adding your inline comments via "Start a review," you must submit the review to notify the PR author. That matters in practice: The review is pending until you submit it.

      +

      Alex: The practical takeaway is this. The button may scroll off-screen to the right. Use horizontal scrolling or press Tab from the page top to cycle through focusable elements until you reach it. When clicked, a popover appears with a summary text area and three radio buttons ( Comment, Approve, Request changes ). At 200%+ zoom, the popover may extend below the visible viewport. Scroll down within the popover to see the Submit review button. The radio buttons are standard HTML radio buttons. In Windows High Contrast mode, the selected radio button uses the system highlight color. Keyboard shortcut: If the button is hard to find visually, press Ctrl+Shift+Enter from within any review comment text area to open the submit review dialog directly.

      +

      Alex: First, look for the Finish your review button in the top-right area of the Files Changed tab (it shows the number of pending comments). Then, click it - a popover appears with a summary text area and three radio buttons: Comment, Approve, Request changes. After that, optionally type a summary comment. Finally, select your verdict by clicking the radio button. It is a checklist, but a meaningful one: every item creates evidence that the next step is safe.

      +

      Jamie: Before we leave Completing and submitting a review, what is the practical point?

      +

      Alex: First, click Submit review. Then, press 1 to go to the h1 (PR title). After that, press B (or Tab) to navigate to the "Submit review" button and activate it (Enter/Space). Finally, a "Submit review" dialog/panel appears. It is like walking a hallway with named doors: read the sign, enter the right room, then confirm where you landed.

      +

      Alex: Treat examples as spoken recipes, not decorations. You may hear something like View the PR diff in your terminal; gh pr diff 42; Approve a PR; gh pr review 42 --approve; Approve with a comment; gh pr review 42 --approve --body "Looks good - heading hierarchy is correct."; Request changes; gh pr review 42 --request-changes --body "The alt. Read the command, understand what it changes, then run it only when the repository state matches the lesson.

      -

      Jamie: Let's pause on How Agents Are Discovered. What should a learner take away from it?

      -

      Alex: The reason How Agents Are Discovered matters is that when you type @ in Copilot Chat, VS Code scans. That gives the learner a simple foothold: the Accessibility Agents ecosystem installs agents appropriate to each platform.

      -

      Alex: First,.github/agents/.agent.md in your current workspace. Then, any agents installed globally on your machine. After that, agents defined by extensions. The rhythm is simple: orient, act, verify, then continue.

      -

      Alex: That matters because of the next idea. Start with Optional: Personalize Your Instance: Open preferences.md in VS Code and edit. The next useful detail is this: Commit preferences.md to your fork. Think of it like entering a new building: first you find the lobby, then the room, then the door you actually need.

      -

      Jamie: Let's pause on How Agents Travel with Your Repo. What should a learner take away from it?

      -

      Alex: Here is the plain-English version of How Agents Travel with Your Repo. When you fork accessibility-agents, the.github/agents/ folder comes with it.

      -

      Alex: The practical takeaway is this. Any collaborator who clones your fork gets all 55 agents automatically. You can customize agents for your specific project by editing the.agent.md files in your fork. Any project can have agents - create a.github/agents/ folder in any repository and add.agent.md files using the same pattern. The one-liner installer can also set up agents globally, so they are available in every workspace you open.

      +

      Alex: Keep the teaching thread moving. Keep the learner anchored in GitHub shortcuts for pull requests. These are the GitHub built-in shortcuts for PR pages. This is the part to say slowly: Enable Focus Mode first (NVDA: NVDA+Space, JAWS: Insert+Z) before using single-key shortcuts.

      +

      Jamie: Let's pause on On the PR list page. What should a learner take away from it?

      +

      Alex: The reason On the PR list page matters is that shortcut note: For G P, press G, release it, then press P (two sequential key presses, not simultaneous).

      +

      Alex: Keep the teaching thread moving. Start with On the Files Changed tab: For the full shortcut system, see Screen Reader Cheat Sheet - GitHub Shortcuts section. Think of it like entering a new building: first you find the lobby, then the room, then the door you actually need.

      -

      Alex: This is where the talk moves from concept to action. This is where Invoking Agents on GitHub.com becomes real: accessibility Agents agents run in VS Code. That matters in practice: But the same.agent.md files can also be invoked directly on GitHub.com - no VS Code, no local clone required.

      -

      Jamie: Let's pause on Option 1: Copilot Chat with Task mode. What should a learner take away from it?

      -

      Alex: Keep the learner anchored in Option 1: Copilot Chat with Task mode. Screen reader users (NVDA / JAWS / VoiceOver).

      -

      Alex: First, open Copilot Chat on GitHub.com (icon in the top-right navigation bar). Then, click Task in the mode picker. After that, optionally click the agent picker to select a custom agent. Finally, type your request and click Send. It is like walking a hallway with named doors: read the sign, enter the right room, then confirm where you landed.

      -

      Jamie: Before we leave Option 1: Copilot Chat with Task mode, what is the practical point?

      -

      Alex: First, Copilot analyzes the task and can create a branch and open a PR automatically. Then, open Copilot Chat on GitHub.com (navigate to icon in top-right navigation → Enter). After that, the mode picker (Task vs Chat) is a set of radio buttons - navigate with Arrow keys to select "Task". Finally, the agent picker is a listbox - Up/Down Arrow to navigate, Enter to select. The rhythm is simple: orient, act, verify, then continue.

      -

      Jamie: Let's pause on Option 2: Assign an issue to Copilot. What should a learner take away from it?

      -

      Alex: The reason Option 2: Assign an issue to Copilot matters is that screen reader users (NVDA / JAWS / VoiceOver). That gives the learner a simple foothold: this is the bridge to Section 6 (The Cloud Extension). The interface gets friendlier when it stops being a wall of controls and starts being a set of named places.

      -

      Alex: First, open any issue (or create a new one describing the task). Then, in the Assignees sidebar section, click the gear icon. After that, in the dropdown, click Copilot as the assignee. Finally, a dialog opens - optionally provide additional instructions and select a custom agent. The rhythm is simple: orient, act, verify, then continue.

      -

      Jamie: Before we leave Option 2: Assign an issue to Copilot, what is the practical point?

      -

      Alex: First, click Assign to confirm. Then, open any issue in the repository. After that, press B to navigate to the Assignees gear button → Enter to open the popup. Finally, navigate the popup with Arrow keys → find "Copilot" → Enter to select. Think of it as a rail line: each stop confirms you are still on the right route before the next one.

      -

      Alex: A solid issue habit is to read the title, the body, and the timeline before acting. You are listening for the requested action, the missing evidence, and the person who needs a response.

      +

      Jamie: Let's pause on Learning Cards: Submitting a Review. What should a learner take away from it?

      +

      Alex: Start with Learning Cards: Submitting a Review. There is something to understand, something to try, and something that proves the try worked.

      +

      Alex: The practical takeaway is this. The review verdict controls are inside a popover triggered by the "Finish your review" button; press 1 to return to the h1 (PR title), then B or Tab forward to find the button -- it is easy to miss because it is not a landmark. Inside the popover, Tab past the summary text area to reach a radio group labeled "Review Event"; use Up/Down Arrow to switch between Comment, Approve, and Request Changes. Shortcut: press Ctrl+Shift+Enter from any review comment text area to open the submit review dialog directly, bypassing the search for the button. The "Finish your review" button sits in the top-right corner of the Files Changed tab with a small badge showing your pending comment count; at 200%+ zoom it may scroll off-screen to the right. Inside the submit popover, the three radio buttons (Comment, Approve, Request changes) are small standard HTML radios; zoom in on the popover area or use Tab to step between them. After submitting, your review verdict appears as a colored banner in the Conversation timeline: green for Approve, red for Request Changes, grey for Comment.

      +

      Alex: Keep the teaching thread moving. This is where Suggested Changes becomes real: a suggested change is a special form of inline review comment where the reviewer proposes exact replacement text. That matters in practice: The PR author can apply the suggestion directly from GitHub - no copy-paste or separate commit needed.

      +

      Jamie: Let's pause on As a reviewer - inserting a suggestion. What should a learner take away from it?

      +

      Alex: Keep the learner anchored in As a reviewer - inserting a suggestion. The suggestion block is plain Markdown text in the comment editor. This is the part to say slowly: (Three backticks, the word suggestion, Enter, your text, Enter, three backticks.).

      +

      Alex: First, on the Files Changed tab, navigate to the line you want to propose a change. Then, activate the line comment button for that line (the + that appears on hover, or Tab to navigate to it). After that, in the comment text area that opens, press Ctrl+G (Windows) or Cmd+G (Mac). Finally, GitHub wraps a suggestion block around the current line content. It is like walking a hallway with named doors: read the sign, enter the right room, then confirm where you landed.

      +

      Jamie: Before we leave As a reviewer - inserting a suggestion, what is the practical point?

      +

      Alex: First, edit the text inside the suggestion block to show your proposed change. Then, add context above the block if helpful: "This makes the alt text more descriptive:". After that, submit as part of your review ("Start a review" → batch with other comments). The rhythm is simple: orient, act, verify, then continue.

      -

      Jamie: There are a lot of tools in play. How do we keep that from feeling like a contest?

      -

      Alex: Start with Copilot on GitHub.com - Browser-Native Features: Beyond assigning Copilot to issues and using Task mode in Chat, GitHub.com now has several standalone Copilot features built directly into the web interface. The next useful detail is this: These work entirely in your browser - no VS Code, no local clone needed.

      -

      Alex: Hold that next to this. Here is the plain-English version of Copilot PR Summary. On any open pull request, GitHub adds a "Summarize" button in the PR description area. Put another way, selecting it generates a plain-language summary of what the PR changes, why, and what reviewers should focus on.

      -

      Jamie: Let's pause on Copilot PR Review. What should a learner take away from it?

      -

      Alex: This is where Copilot PR Review becomes real: on open PRs you have write access to review, a "Review" button (or Copilot icon) appears in the Files changed tab. That matters in practice: Copilot generates inline review comments across the diff.

      +

      Jamie: Let's pause on As an author - applying a suggestion. What should a learner take away from it?

      +

      Alex: Start with As an author - applying a suggestion. There is something to understand, something to try, and something that proves the try worked.

      +

      Alex: First, open the PR Conversation or Files Changed tab. Then, navigate to the inline comment containing a suggestion (it shows a diff-style preview). After that, find and activate the "Apply suggestion" button below the suggestion block. Finally, GitHub creates a commit automatically that applies the change - no file editing required. The rhythm is simple: orient, act, verify, then continue.

      +

      Jamie: Before we leave As an author - applying a suggestion, what is the practical point?

      +

      Alex: First, the conversation thread is marked as resolved. Think of it as a rail line: each stop confirms you are still on the right route before the next one.

      +

      Jamie: Let's pause on Batching multiple suggestions into one commit. What should a learner take away from it?

      +

      Alex: Start with Batching multiple suggestions into one commit. There is something to understand, something to try, and something that proves the try worked.

      +

      Alex: First, for each suggestion you want to apply, activate "Add suggestion to batch" instead of "Apply suggestion". Then, after selecting all suggestions, activate the "Commit suggestions" button that appears at the top. After that, GitHub applies all batched suggestions in a single commit. Think of it as a rail line: each stop confirms you are still on the right route before the next one.

      +

      Jamie: Let's pause on When to use suggestions vs. comments. What should a learner take away from it?

      +

      Alex: Start with When to use suggestions vs. comments. There is something to understand, something to try, and something that proves the try worked.

      +

      Alex: The practical takeaway is this. Use a suggestion when you know the exact text that would fix the issue. Use a plain comment when the change requires judgment from the author (e.g., "this alt text isn't descriptive - can you describe what the image shows?"). A summary text area for overall comments. Radio buttons for Comment / Approve / Request changes.

      +

      Alex: First, after adding all your inline comments, navigate to the review summary button. Then, on Files Changed tab: find the "Review changes" button (B to navigate buttons). After that, press Enter to open the review dialog. Finally, a panel opens. Treat it like a recipe: do not add the next ingredient until the previous one is actually in the bowl.

      +

      Jamie: Before we leave When to use suggestions vs. comments, what is the practical point?

      +

      Alex: First, switch to Focus Mode → type your summary comment. Then, navigate to the radio buttons with arrow keys → select your verdict. After that, tab to "Submit review" button → Enter. It is a checklist, but a meaningful one: every item creates evidence that the next step is safe.

      -

      Alex: Keep the teaching thread moving. Keep the learner anchored in Copilot in Issues. On any issue page, Copilot adds sidebar buttons that appear once the page loads. This is the part to say slowly: Look in the right sidebar on any issue page for a Copilot section with "Explain" and "Suggest fix" buttons. A good GitHub workflow is like a well-run meeting: everyone knows the topic, the next action, and who has the floor.

      -

      Alex: The practical takeaway is this. "Explain this issue" - generates a plain-language explanation of a complex technical issue. "Suggest fix" - proposes an approach to resolving the issue (opens a task/PR workflow).

      -

      Jamie: Let's pause on GitHub Models - Free AI Playground. What should a learner take away from it?

      -

      Alex: The reason GitHub Models - Free AI Playground matters is that github.com/marketplace/models is a free playground where you can test AI models (OpenAI GPT-4o, Meta Llama 3, Mistral, Phi-4 Mini, and others) directly in your browser. That gives the learner a simple foothold: why it matters for Accessibility Agents: When you build custom agents and prompts, you can test your system prompts and prompt templates in GitHub Models before adding them to your.prompt.md files - rapid iteration without burning API credits.

      -

      Alex: The practical takeaway is this. Send prompts to any listed model and compare responses side by side. Adjust parameters (temperature, max tokens) without any setup. Use the code sample generator to get API code for your chosen model. All free with a GitHub account (rate-limited for free tier).

      -

      Alex: Keep the teaching thread moving. Start with Copilot-Drafted Release Notes: When creating a release (Releases tab → Draft a new release), GitHub provides a "Generate release notes" button. The next useful detail is this: It scans merged PRs since the last release and drafts categorized release notes automatically.

      +

      Jamie: Let's pause on Learning Cards: Suggested Changes. What should a learner take away from it?

      +

      Alex: Start with Learning Cards: Suggested Changes. There is something to understand, something to try, and something that proves the try worked.

      +

      Alex: The practical takeaway is this. To insert a suggestion block, press Ctrl+G (Windows) or Cmd+G (Mac) in the comment text area; the screen reader announces the inserted fence -- arrow down to edit the text between the backtick lines. Alternatively type the block manually: three backticks, the word suggestion, Enter, your replacement text, Enter, three backticks -- this avoids relying on the keyboard shortcut. As a PR author, navigate to a suggestion comment with 3, then Tab to the "Apply suggestion" button; GitHub commits the change automatically with no file editing required. Suggestion blocks render as a mini inline diff: the original line in red/pink background and your proposed replacement in green background; in high-contrast mode these use system diff colors. The "Apply suggestion" button is small and sits below the suggestion diff preview; zoom into the comment area to find it, or Tab from the suggestion text to reach it. When batching multiple suggestions, a floating "Commit suggestions" bar appears at the top of the page; at high zoom scroll up or press Home to find it.

      +

      Jamie: What is the safe way to learn from that example?

      +

      Alex: Keep the learner anchored in Understanding Merge Options (for Maintainers). When a PR is approved and checks pass, a maintainer can merge it. This is the part to say slowly: The merge button section appears at the bottom of the Conversation tab. A good GitHub workflow is like a well-run meeting: everyone knows the topic, the next action, and who has the floor.

      +

      Alex: Treat examples as spoken recipes, not decorations. You may hear something like Merge with default strategy (merge commit); gh pr merge 42; Squash and merge; gh pr merge 42 --squash; Rebase and merge; gh pr merge 42 --rebase; Delete the branch after merging; gh pr merge 42 --squash --delete-branch; Enable auto-merge (merges when checks. Read the command, understand what it changes, then run it only when the repository state matches the lesson.

      +

      Jamie: Let's pause on After a PR is merged. What should a learner take away from it?

      +

      Alex: The reason After a PR is merged matters is that for screen reader users, - deleting the branch after merge: Navigate to the "Add a comment" section (D), then press Shift+B to navigate backwards to the "Delete branch" button and activate it. That gives the learner a simple foothold: this keeps your repository clean by removing the now-merged feature branch.

      +

      Alex: The practical takeaway is this. The PR status badge changes to "Merged" (purple). The source branch can be deleted - a "Delete branch" button appears. Any linked issues with Closes N in the description are automatically closed.

      -

      Jamie: What does someone need before they touch the keyboard?

      -

      Alex: Start with Learning Cards: Setup and Configuration. There is something to understand, something to try, and something that proves the try worked.

      -

      Alex: The practical takeaway is this. Run the installer command in the VS Code terminal (Ctrl+) -- it announces progress as it copies agent files to.github/agents/`. After installation, press Ctrl+Shift+E to open the Explorer and navigate to.github/agents/ to verify agent files are present. Edit.github/agents/preferences.md to configure your username, repositories, and notification preferences -- it is a standard Markdown file. The installer creates files in.github/agents/ and.github/prompts/ -- verify in the Explorer sidebar that these folders appeared. Open preferences.md in the editor to set your configuration -- use Ctrl+= to zoom if the YAML frontmatter is hard to read. Agent files use.agent.md extension -- they appear alongside regular Markdown files in the Explorer but are distinguished by their extension.

      -

      Alex: Keep the teaching thread moving. This is where 3. The Ecosystem: 55 Agents, 3 Teams, 5 Platforms becomes real: accessibility Agents is an ecosystem of 55 specialized agents organized into three teams, each addressing a different dimension of accessible software development. That matters in practice: Browse all three teams below, then choose the agents that match your current skills and interests. The workshop is closer to rehearsal than lecture. You hear the move, try the move, and then check what changed.

      -

      Jamie: Let's pause on Team 1: Accessibility (26 agents). What should a learner take away from it?

      -

      Alex: Keep the learner anchored in Team 1: Accessibility (26 agents). These agents audit, fix, and enforce accessibility across web, document, and mobile platforms.

      +

      Alex: Keep the teaching thread moving. Start with Auto-Merge - Merging When You Can't Wait Around: Auto-merge lets you pre-authorize a PR to merge automatically the moment all branch protection requirements are satisfied - required reviews approved, all status checks passing, and the branch up to date.

      +

      Alex: The practical takeaway is this. You've addressed all review comments and are waiting for CI to finish. A maintainer has approved the PR but a required check is still running. You're in a different time zone from the reviewers.

      +

      Jamie: Let's pause on What happens next. What should a learner take away from it?

      +

      Alex: Start with What happens next. There is something to understand, something to try, and something that proves the try worked.

      +

      Alex: The practical takeaway is this. The PR merge box changes to show "Auto-merge enabled - merge will happen automatically". When the last required check passes (or last required review arrives), GitHub merges the PR silently. You receive a notification: "Your PR was automatically merged". If a reviewer requests changes after auto-merge is enabled, auto-merge is automatically cancelled (a new approval is required before it re-enables).

      +

      Jamie: Let's pause on Cancelling Auto-Merge. What should a learner take away from it?

      +

      Alex: This is where Cancelling Auto-Merge becomes real: auto-merge is only available if the repository administrator has enabled it in Settings → General. That matters in practice: Many open source repos have it on; some do not. The workshop is closer to rehearsal than lecture. You hear the move, try the move, and then check what changed.

      +

      Alex: Treat examples as spoken recipes, not decorations. You may hear something like Merge box → Tab → "Disable auto-merge" button → Enter. Read the command, understand what it changes, then run it only when the repository state matches the lesson.

      -

      Alex: Keep the teaching thread moving. The reason Team 2: GitHub Workflow (12 agents) matters is that these agents automate GitHub operations - issue triage, PR review, contribution analytics, and repository management.

      -

      Jamie: What should someone listen for when a lesson offers more than one tool path?

      -

      Alex: Start with Team 3: Developer Tools (6 agents): These agents support accessible application development across desktop and cross-platform frameworks.

      -

      Alex: Keep the teaching thread moving. Here is the plain-English version of Beyond Agents: The Supporting Ecosystem. The 55 agents are backed by additional resources in the repository. It is like learning a transit route. The names of the stops matter because they tell you whether you are still going the right direction.

      +

      Jamie: Let's pause on Scenario A: "I want to review an assigned PR". What should a learner take away from it?

      +

      Alex: Keep the learner anchored in Scenario A: "I want to review an assigned PR". Example: You are assigned to review a PR titled "Add missing NVDA shortcut to keyboard-shortcuts.md." The PR modifies docs/keyboard-shortcuts.md in the Learning Room repository and references Challenge 2.

      +

      Alex: Keep the teaching thread moving. The reason Scenario B: "I want to respond to review feedback on my PR" matters is that example: Your PR for Challenge 3 (Complete Welcome Guide) received a review comment: "The [TODO] about evaluating issues is good, but the paragraph could mention checking if the issue is already assigned." The validation bot also flagged a link text issue.

      +

      Jamie: Let's pause on Writing PR Descriptions That Get Reviewed. What should a learner take away from it?

      +

      Alex: Start with Writing PR Descriptions That Get Reviewed: See also: Appendix C: Markdown Reference for formatting your PR description with headings, lists, and task lists. The next useful detail is this: A pull request is only as useful as its description.

      -

      Jamie: Let's pause on Hook-Based Enforcement (Claude Code). What should a learner take away from it?

      -

      Alex: This is where Hook-Based Enforcement (Claude Code) becomes real: on Claude Code, Accessibility Agents includes a hook system that enforces accessibility standards automatically. That matters in practice: This means accessibility enforcement happens whether or not the developer remembers to ask for it.

      -

      Alex: First, proactive detection hook - scans every file edit for accessibility regressions before they are committed. Then, edit gate hook - blocks commits that introduce WCAG violations until they are fixed. After that, session marker hook - tracks which accessibility checks have run during the current session. It is a checklist, but a meaningful one: every item creates evidence that the next step is safe.

      -

      Alex: Keep the teaching thread moving. Keep the learner anchored in What Would You Build? This is the question that matters most. This is the part to say slowly: The 55 agents that exist today were built by contributors who saw a gap and filled it.

      -

      Alex: The practical takeaway is this. "Why is there no agent for [framework] accessibility patterns?". "I spend 30 minutes on [task] every week - could an agent do the repetitive part?". "This agent is good but it misses [specific edge case] - I could improve those instructions". "Mobile native accessibility testing has no agent coverage yet - I could start one".

      -

      Jamie: Let's pause on The contribution paths are. What should a learner take away from it?

      -

      Alex: The reason The contribution paths are matters is that see the Accessibility Agents CONTRIBUTING guide for detailed instructions on each path.

      -

      Alex: First, report an agent gap - file an issue describing what is missing and why it matters. Then, improve existing agent instructions - make an agent smarter about edge cases it misses. After that, add framework-specific patterns - teach agents about React, Vue, Angular, Svelte, or other framework accessibility patterns. Finally, fix installer issues - improve the one-liner scripts for different OS configurations. The rhythm is simple: orient, act, verify, then continue.

      -

      Jamie: Before we leave The contribution paths are, what is the practical point?

      -

      Alex: First, write documentation - help others understand how to use and contribute to agents. Think of it as a rail line: each stop confirms you are still on the right route before the next one.

      +

      Jamie: Let's pause on What Reviewers Look For. What should a learner take away from it?

      +

      Alex: Here is the plain-English version of What Reviewers Look For. When a reviewer opens your PR, they are asking four questions before they ever look at the diff. Put another way, if your description answers all four, the reviewer can jump straight into the code with context. It is like learning a transit route. The names of the stops matter because they tell you whether you are still going the right direction.

      +

      Alex: First, why does this change exist? -- What problem does it solve, or what goal does it advance? Then, what is the scope? -- Which files changed, and roughly how big is the change? After that, how was it tested? -- Did you verify that the change works, and how? Finally, what should I pay attention to? -- Are there tricky parts, trade-offs, or areas where you want a second opinion? Treat it like a recipe: do not add the next ingredient until the previous one is actually in the bowl.

      +

      Jamie: Let's pause on The Closes XX Pattern. What should a learner take away from it?

      +

      Alex: This is where The Closes XX Pattern becomes real: GitHub recognizes special keywords in PR descriptions that automatically close linked issues when the PR merges. That matters in practice: You do not need to close issues by hand -- just include the right keyword followed by the issue number.

      +

      Alex: Keep the teaching thread moving. Keep the learner anchored in Before/After Structure. One of the most effective patterns for PR descriptions is showing the state before your change and the state after. This is the part to say slowly: This gives the reviewer an instant mental model of what changed without reading the diff line by line.

      -

      Alex: Keep the teaching thread moving. Start with Roadmap: What Is Coming Next: Your contribution could be the next item that ships. The next useful detail is this: Every agent started as one person's idea and one pull request. Think of it like entering a new building: first you find the lobby, then the room, then the door you actually need.

      -

      Alex: The practical takeaway is this. Mobile native agents - agents specialized for iOS (VoiceOver) and Android (TalkBack) native app accessibility. Anthropic Connectors listing - making agents discoverable through the Anthropic marketplace. veraPDF integration - automated PDF/UA validation for the PDF accessibility agent. Document remediation agents - agents that fix accessibility issues in documents, not just find them.

      -

      Jamie: Let's pause on Learning Cards: The Agent Ecosystem. What should a learner take away from it?

      -

      Alex: Start with Learning Cards: The Agent Ecosystem. There is something to understand, something to try, and something that proves the try worked.

      -

      Alex: The practical takeaway is this. The three team tables use standard Markdown table format -- navigate with T (NVDA/JAWS) to jump between tables, then Arrow keys to read cells. Agent names start with @ -- type @ followed by the agent name in Copilot Chat to invoke it (e.g., @daily-briefing). Use Ctrl+Shift+O (symbol outline) in any agent file to navigate between its YAML frontmatter sections (Purpose, Responsibilities, Guardrails). The agent tables are dense -- use Ctrl+= to increase font size or open the file in Markdown Preview (Ctrl+Shift+V) for cleaner rendering. Each team has a distinct table: Team 1 (Accessibility, 26 agents), Team 2 (GitHub Workflow, 15 agents), Team 3 (Developer Tools, 14 agents). Agent files in.github/agents/ have descriptive filenames that match the @agent-name -- browse them in the Explorer to find specific agents.

      -

      Alex: Keep the teaching thread moving. This is where 4. Agents in Detail - Hands-On Reference becomes real: this section walks through several agents in depth so you can see how they work, what they produce, and how to evaluate their output. That matters in practice: These examples use GitHub Workflow agents because they build directly on Day 1 skills - but the same patterns apply to every agent in the ecosystem.

      +

      Jamie: Let's pause on A PR Description Template. What should a learner take away from it?

      +

      Alex: The reason A PR Description Template matters is that here is a template you can copy into your PR descriptions. That gives the learner a simple foothold: not every section applies to every PR, but filling in even a few sentences per section makes a meaningful difference.

      +

      Alex: Keep the teaching thread moving. Start with Common Description Mistakes: Even experienced contributors make these mistakes. The next useful detail is this: Knowing what to avoid is half the battle. Think of it like entering a new building: first you find the lobby, then the room, then the door you actually need.

      +

      Jamie: Let's pause on Good vs. Bad: Side by Side. What should a learner take away from it?

      +

      Alex: Here is the plain-English version of Good vs. Bad: Side by Side. No context, no linked issue, no explanation of what file or what was wrong with it. Put another way, a reviewer seeing this has to open the diff, figure out which file changed, read every line, and guess at the intent.

      -

      Jamie: Let's pause on Two Types of Agents. What should a learner take away from it?

      -

      Alex: Keep the learner anchored in Two Types of Agents. Before diving in, it helps to know that custom agents fall into two categories - this distinction affects what tool permissions they need and what they can do. This is the part to say slowly: Informational agents search, analyze, and report.

      -

      Alex: Keep the teaching thread moving. The reason Agent 1: @daily-briefing - Morning Briefing matters is that file.github/agents/daily-briefing.agent.md. That gives the learner a simple foothold: before you run this agent: You should have manually navigated a repository's Issues tab, read your GitHub Notifications page, understood what a pull request waiting for review looks like, and know the difference between subscribed and participating. The interface gets friendlier when it stops being a wall of controls and starts being a set of named places.

      -

      Jamie: Let's pause on What it does. What should a learner take away from it?

      -

      Alex: Start with What it does: Sweeps every repository you have access to and builds a prioritized dashboard.

      -

      Alex: The practical takeaway is this. Issues opened in the last 24 hours. Pull requests waiting for your review. CI failures on your branches. Security and Dependabot alerts. Community reactions to your recent comments.

      +

      Alex: Keep the teaching thread moving. Start with Learning Cards: Writing PR Descriptions That Get Reviewed. There is something to understand, something to try, and something that proves the try worked.

      +

      Alex: The practical takeaway is this. Use Markdown headings ( ) in your description (Summary, Changes, Related Issues, Testing) so reviewers can press H to jump between sections. Type Closes followed by the issue number to auto-close the linked issue on merge; GitHub autocompletes when you type. Press Ctrl+Shift+P in the description text area to toggle between Write and Preview modes; Preview renders your Markdown so you can check structure before submitting. Use the Preview tab to verify your Markdown renders correctly; headings, bullet lists, and code blocks are easier to proofread in rendered form. Keep bullet points short (one line each) so the description is scannable at high zoom without excessive horizontal scrolling. When including screenshots, add alt text in the Markdown image syntax: so every reader gets the same information.

      +

      Jamie: Let's pause on Try It: Read a Real Pull Request. What should a learner take away from it?

      +

      Alex: Keep the learner anchored in Try It: Read a Real Pull Request. Time: 3 minutes What you need: Browser, signed in to GitHub. This is the part to say slowly: Go to the Learning Room repository's Pull Requests tab and find any open or recently closed PR.

      +

      Alex: First, navigate to Pull Requests (G then P in Focus Mode). Then, open the first PR in the list (press Enter on its title). After that, read the description - press 2 to jump to the first section heading, then arrow down to read. Look for: which file was changed (docs/welcome.md, docs/keyboard-shortcuts.md, or docs/setup-guide.md)? Which challenge was this PR solving? Does the description. Finally, check the conversation - press 3 to jump between comments. Read what the validation bot reported - did the bot find any accessibility issues like broken headings or non-descriptive links? How did the author respond? It is like walking a hallway with named doors: read the sign, enter the right room, then confirm where you landed.

      +

      Jamie: Before we leave Try It: Read a Real Pull Request, what is the practical point?

      +

      Alex: First, look at the diff - press D to the "Pull request tabs" landmark, then navigate to "Files changed" and press Enter. Press H to scan the changed file headings. If the PR touched docs/welcome.md, you should see + lines where the [TODO] sections were filled in. If. The rhythm is simple: orient, act, verify, then continue.

      -

      Alex: Keep the teaching thread moving. Here is the plain-English version of Example commands. The briefing output uses heading level 2 for each section. Put another way, use H key (NVDA/JAWS virtual mode) or VO+Command+H (VoiceOver) to jump between: Open Issues, Review Requests, CI Status, Security Alerts, Community Activity.

      -

      Jamie: Let's pause on Agent 2: @issue-tracker - Issue Management. What should a learner take away from it?

      -

      Alex: This is where Agent 2: @issue-tracker - Issue Management becomes real: file.github/agents/issue-tracker.agent.md. That matters in practice: Before you run this agent: You should have filed at least one issue using the full manual process - writing a title, description, and reproduction steps; applying labels and a milestone; and reading at least five existing issues to understand what a.

      -

      Alex: Keep the teaching thread moving. Keep the learner anchored in What it does. Finds, prioritizes, and helps you manage issues across all your repositories. A good GitHub workflow is like a well-run meeting: everyone knows the topic, the next action, and who has the floor.

      -

      Alex: The practical takeaway is this. Cross-repository priority scoring with community sentiment. Batch-reply capability (draft replies to multiple issues at once). Saved search support. Release-awareness (flags issues that affect upcoming releases).

      +

      Jamie: What is the final checkpoint?

      +

      Alex: You should be able to point to the evidence, explain the action, and describe what you would do next if this were a real open source project. If you can teach the move back, you have learned it.

      +

      Jamie: And if they get stuck?

      +

      Alex: Read the latest message, not the loudest worry. Check the issue, the branch, the pull request, the status check, or the bot comment. Then ask for help with those facts in hand. That is how professionals collaborate.

      +
      +
      -

      Jamie: How should a learner choose a tool without feeling judged by the choice?

      -

      Alex: The reason Example commands matters is that the agent can draft a reply. That gives the learner a simple foothold: you review the tone against the Culture & Etiquette guide before posting.

      -

      Jamie: What should happen before anyone copies and runs it?

      -

      Alex: Start with Output example. There is something to understand, something to try, and something that proves the try worked.

      -

      Alex: Treat examples as spoken recipes, not decorations. You may hear something like Open Issues Labeled "good-first-issue"; High Priority; - 45 [accessibility-agents] Add NVDA-specific navigation tips (3 comments, opened 5 days ago); - Priority Score: 8/10 (high community interest, clear scope, no assignee); - Recommended for: First-time. Read the command, understand what it changes, then run it only when the repository state matches the lesson.

      -

      Jamie: Let's pause on Agent 3: @pr-review - Pull Request Review. What should a learner take away from it?

      -

      Alex: Here is the plain-English version of Agent 3: @pr-review - Pull Request Review. File.github/agents/pr-review.agent.md. Put another way, before you run this agent: You should have manually reviewed at least one pull request diff in the GitHub browser interface - navigating the Files Changed tab with your screen reader, reading added and removed lines, leaving at least one inline comment, and.

      +

      19. Challenge 06: Open Your First Pull Request

      +

      Opening a pull request, comparing branches, and using closing keywords.

      +

      Practice focus: Day 1 contribution

      +

      Audio and transcript are being regenerated for this episode.

      +
      +Read Transcript - Challenge 06: Open Your First Pull Request + +

      Transcript

      +

      Alex: Welcome back to Challenge Coach. Today we are taking on Open Your First Pull Request, one careful step at a time.

      +

      Jamie: And I am Jamie. I am listening for the confusing parts: where to start, what to submit, and how to tell whether it worked.

      -

      Alex: Keep the teaching thread moving. This is where What it does becomes real: generates full review documents for pull requests. The workshop is closer to rehearsal than lecture. You hear the move, try the move, and then check what changed.

      -

      Alex: The practical takeaway is this. Line-numbered diffs with change maps. Risk assessment (what could break, what is high-impact). Before-and-after snapshots. CI results and test coverage information. Suggested inline review comments with line number references.

      -

      Jamie: How do we make tool choice feel like access, not pressure?

      -

      Alex: Keep the learner anchored in Example commands. Critical rule: Read the agent's review. This is the part to say slowly: The agent produces a starting point - it does not know the project's history, the contributor's background, or the community's implicit standards the way you do.

      -

      Jamie: How do you keep commands from becoming magic words?

      -

      Alex: Treat examples as spoken recipes, not decorations. You may hear something like PR Review: 14 - Improve screen reader navigation guide; Summary; This PR adds 3 new sections to the screen reader navigation guide and updates 2 existing sections with NVDA-specific keyboard shortcuts.; Files Changed: 1; Lines Added: 127; Lines Removed: 18. Read the command, understand what it changes, then run it only when the repository state matches the lesson.

      +

      Alex: In this challenge, the learner is practicing opening a pull request, comparing branches, and using closing keywords. The point is not to rush. The point is to leave a clear trace of good work.

      +

      Jamie: So we should name what success sounds like before the learner starts clicking or typing.

      +

      Alex: Yes. When the checkpoint is clear, the learner can tell the difference between being stuck and simply not being finished yet.

      -

      Jamie: Let's pause on Agent 4: @analytics - Team Analytics. What should a learner take away from it?

      -

      Alex: Start with Agent 4: @analytics - Team Analytics: File.github/agents/analytics.agent.md. The next useful detail is this: Before you run this agent: You should have explored the Insights tab of at least one repository - looked at the contribution graph, understood what commit frequency means, and thought about what "high-churn files" implies for a project's stability.

      -

      Alex: Keep the teaching thread moving. Here is the plain-English version of What it does. Surfaces team contribution patterns, velocity metrics, and bottleneck detection. It is like learning a transit route. The names of the stops matter because they tell you whether you are still going the right direction.

      -

      Alex: The practical takeaway is this. Contribution velocity over time. Review turnaround time by reviewer. Code hotspot detection (files with the most churn). Workload distribution across contributors.

      -

      Jamie: What stays the same when the tool changes?

      -

      Alex: This is where Example commands becomes real: accessibility use case: After Day 2's contribution wave, run @analytics team velocity in accessibility-agents today to see the hackathon's collective output. That matters in practice: A moment of real-time team celebration.

      +

      Jamie: What makes this practice feel low-stakes but still real?

      +

      Alex: Start with Challenge 6: Open Your First Pull Request: What you will do: Open a pull request from your learn/YOUR-USERNAME branch to main, connecting it to the issue you filed in Challenge 2.

      +

      Alex: A solid pull request habit is to separate three questions: what changed, why it changed, and what still needs review. That keeps the conversation useful instead of noisy.

      +

      Jamie: How would you walk the room through that step by step?

      +

      Alex: Start with Instructions. There is something to understand, something to try, and something that proves the try worked.

      +

      Alex: First, go to the Pull requests tab. Then, select New pull request. After that, set base to main and compare to learn/YOUR-USERNAME. Finally, write a descriptive PR title. Treat it like a recipe: do not add the next ingredient until the previous one is actually in the bowl.

      +

      Jamie: What does the learner do first, second, and then after that?

      +

      Alex: First, in the PR description, include Closes XX (replace XX with your Challenge 2 issue number). This automatically links and closes the issue when the PR is merged. Then, submit the pull request. It is a checklist, but a meaningful one: every item creates evidence that the next step is safe.

      +

      Jamie: What is the one idea that makes the next few steps less mysterious?

      +

      Alex: This is where PR description template becomes real: use this structure for your PR description.

      -

      Alex: Keep the teaching thread moving. Keep the learner anchored in Agent 5: @insiders-a11y-tracker - Accessibility Change Monitoring. File.github/agents/insiders-a11y-tracker.agent.md. This is the part to say slowly: Before you run this agent: You should have filed at least one accessibility bug report using the workshop's issue template, applied a WCAG label to an issue, and manually reviewed a Markdown file for heading hierarchy - knowing what H1 means, what H2 means,.

      -

      Jamie: Before we leave What it does, what is the practical point?

      -

      Alex: The reason What it does matters is that monitors accessibility-sensitive changes across configured repositories.

      -

      Alex: The practical takeaway is this. WCAG/ARIA cross-referenced change tracking. Flags changes to keyboard navigation, ARIA attributes, focus management, color usage. Monitors for heading hierarchy violations in Markdown. Tracks link text quality (flags bare URLs, non-descriptive labels).

      -

      Alex: Keep the teaching thread moving. Start with Example commands: Day 2 workflow: Run this before submitting any PR. The next useful detail is this: If the agent flags an issue, fix it before requesting review - not after. Think of it like entering a new building: first you find the lobby, then the room, then the door you actually need.

      +

      Alex: Now bring the learner back to the room. Keep the learner anchored in The magic of Closes XX. When you write Closes 12 in a PR description, GitHub automatically. This is the part to say slowly: This is one of GitHub's most powerful workflow features.

      +

      Alex: For a learner, the useful signals are these. Links the PR to issue 12. Closes issue 12 when the PR is merged.

      +

      Jamie: What would you say to someone who is already bracing for this to be too much?

      +

      Alex: The reason Peer simulation check matters is that find the Peer Simulation: Improve contribution guidance PR and leave an encouraging comment. That gives the learner a simple foothold: if you have access to a real buddy's PR, you may comment there too.

      +

      Alex: The useful habit is simple: orient first, act second, verify third. That pause before acting is part of the work.

      +

      Alex: That matters because of the next idea. Start with Example PR. There is something to understand, something to try, and something that proves the try worked.

      -

      Jamie: Let's pause on Agent 6: @template-builder - Interactive Issue Template Wizard. What should a learner take away from it?

      -

      Alex: Here is the plain-English version of Agent 6: @template-builder - Interactive Issue Template Wizard. File.github/agents/template-builder.agent.md. Put another way, before you run this agent: You should have read Issue Templates thoroughly - understanding YAML field types, creating a template manually (Exercise B), and designing your own template (Exercise D).

      -

      Alex: Keep the teaching thread moving. This is where What it does becomes real: an interactive wizard that guides you through building GitHub issue templates step-by-step using VS Code's Ask Questions feature. That matters in practice: Instead of writing YAML syntax, answer simple questions and the agent generates production-ready templates.

      -

      Jamie: What is the common workflow underneath the different interfaces?

      -

      Alex: Keep the learner anchored in Example commands. Manual YAML template creation takes 15-20 minutes and is error-prone. This is the part to say slowly: The Template Builder generates correct, tested templates in 2-3 minutes via guided questions.

      +

      Jamie: Okay, set the room for us. What are we walking into?

      +

      Alex: Start with Title. There is something to understand, something to try, and something that proves the try worked.

      +

      Alex: Here is what that changes in practice. Describes the change clearly: someone reading just the title understands what happened. Short enough to scan in a list.

      +

      Alex: This is where the talk moves from concept to action. Start with Body. There is something to understand, something to try, and something that proves the try worked.

      +

      Alex: The room should hear these as checkpoints. What: Summarizes the change. Why: Explains the motivation. Closes N: Links to the issue this PR resolves -- GitHub automatically closes the issue when the PR merges.

      +

      Jamie: Where do you want a learner to place their attention here?

      +

      Alex: Keep the learner anchored in Linked issue. The Closes 3 line creates a two-way link. This is the part to say slowly: The issue shows "referenced by PR 5" and the PR shows "Closes 3." When the PR merges, issue 3 closes automatically.

      +

      Alex: A solid issue habit is to read the title, the body, and the timeline before acting. You are listening for the requested action, the missing evidence, and the person who needs a response.

      -

      Alex: Keep the teaching thread moving. The reason 5. Slash Commands and Prompts matters is that the repository includes 54+ slash commands defined as.prompt.md files in.github/prompts/. That gives the learner a simple foothold: type / in Copilot Chat to see the full command menu. The interface gets friendlier when it stops being a wall of controls and starts being a set of named places.

      -

      Jamie: How should they picture the shape of the workshop?

      -

      Alex: Start with Workshop Slash Command Quick Reference: The commands listed below are the ones most relevant to this workshop. The next useful detail is this: The full repository contains 54+ commands covering accessibility auditing, document scanning, framework-specific checks, and more.

      -

      Alex: Keep the teaching thread moving. Here is the plain-English version of Reading Slash Command Definitions. Each /command corresponds to a.prompt.md file in.github/prompts/. Put another way, open any of them in VS Code to read what instructions it gives Copilot.

      +

      Alex: Before the learner moves on. The reason Passing checks matters is that if the repository has automated checks (the PR validation bot), a green checkmark appears. That gives the learner a simple foothold: if checks fail, read the bot's feedback comment for specific guidance. The interface gets friendlier when it stops being a wall of controls and starts being a set of named places.

      +

      Jamie: Give me the version that sounds like an instructor, not a manual.

      +

      Alex: Start with Alternate linking syntax. There is something to understand, something to try, and something that proves the try worked.

      +

      Alex: A few details make that real. Closes 3. Resolves 3.

      +

      Alex: Hold that next to this. Here is the plain-English version of What matters. The learning objective is connecting a change (PR) to a reason (issue) through GitHub's linking system. Put another way, if your PR has a clear title, a description, and references an issue number, you completed this challenge.

      -

      Jamie: Let's pause on Example: /a11y-update. What should a learner take away from it?

      -

      Alex: This is where Example: /a11y-update becomes real: file.github/prompts/a11y-update.prompt.md. That matters in practice: This is how you learn to write your own.

      -

      Alex: Keep the teaching thread moving. Start with Learning Cards: Slash Commands and Prompts. There is something to understand, something to try, and something that proves the try worked.

      -

      Alex: The practical takeaway is this. Type / in Copilot Chat to see all available slash commands -- your screen reader announces each command name as you arrow through the list. Slash commands are defined in.github/prompts/ as.prompt.md files -- open them in the Explorer to read what each command does before using it. Create your own command by copying an existing.prompt.md file, renaming it, and editing the instructions -- no code required. The / command menu appears as a dropdown list in Copilot Chat -- it scales with VS Code's font and zoom settings. Each command has a short description visible in the dropdown; use Ctrl+= to zoom if the text is too small. Open the.prompt.md file in the editor to read the full command definition at your preferred zoom level.

      -

      Jamie: Let's pause on 6. Contributing to the Ecosystem. What should a learner take away from it?

      -

      Alex: The reason 6. Contributing to the Ecosystem matters is that the 55 Accessibility Agents and 54+ slash commands are starting points. That gives the learner a simple foothold: the.agent.md format is open - you can create your own agents for any repeatable workflow, and contribute them back to the project.

      +

      Jamie: If I am listening before the workshop starts, what should settle in my mind first?

      +

      Alex: This is where Creating, Reviewing, and Merging Pull Requests with a Screen Reader becomes real: see also: Chapter 15: Code Review covers the full review workflow including multi-file diffs and suggested changes. That matters in practice: Pull requests are where your work becomes a contribution.

      +

      Alex: That connects to another useful point. Keep the learner anchored in Workshop Recommendation (Chapter 6). Chapter 6 is the first PR-validated chapter where students convert issue work into merge-ready contributions. A good GitHub workflow is like a well-run meeting: everyone knows the topic, the next action, and who has the floor.

      +

      Alex: The parts worth keeping in working memory are these. There are 3. Each challenge should take under 10 minutes each. The evidence is PR metadata, bot checks, and merged issue linkage. The pattern is small change - linked PR - green checks.

      +

      Jamie: What is the ordered workflow?

      +

      Alex: The reason Chapter 6 Challenge Set matters is that this is the first chapter where you edit files and create branches. That gives the learner a simple foothold: 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.

      +

      Alex: First, create one small branch change - edit a practice file on a new branch. Then, open a linked PR - use the PR template and include Closes XX. After that, pass required checks - respond to bot feedback until all required checks pass. The rhythm is simple: orient, act, verify, then continue.

      -

      Alex: Keep the teaching thread moving. Start with Two Types of Custom Agents: Informational agents - conversational; search, analyze, and present results. The next useful detail is this: Task-oriented agents - active; edit files, run commands, submit PRs.

      -

      Alex: The practical takeaway is this. Perform GitHub searches with predefined scopes and filters. Present results in specific structured formats. Query GitHub API tools to answer questions. Execute external tools (linters, test suites, axe-core).

      -

      Jamie: Let's pause on Agent File Structure. What should a learner take away from it?

      -

      Alex: Here is the plain-English version of Agent File Structure. See also: Appendix L: Agents Reference has the complete agent.md format specification and examples. Put another way, every.agent.md file has two parts: YAML frontmatter (metadata) and a system prompt (markdown body).

      -

      Alex: Keep the teaching thread moving. This is where Frontmatter fields becomes real: restricting tool access is a security best practice - only grant what the agent actually needs. The workshop is closer to rehearsal than lecture. You hear the move, try the move, and then check what changed.

      +

      Jamie: Give me the sequence, because order matters here.

      +

      Alex: Start with Challenge 6.1 Step-by-Step: Create One Small Branch Change: Edit one of the practice files and save your change on a new branch. The next useful detail is this: your Learning Room repository on GitHub.com, using the web editor.

      +

      Alex: On the ground, that means a few things. 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. 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.

      +

      Alex: First, 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). Then, open the file and activate the pencil icon (Edit this file) button. After that, the file opens in the web editor. Make your change. For. Finally, keep your change small and focused. Edit only what the issue asks for. Think of it as a rail line: each stop confirms you are still on the right route before the next one.

      +

      Jamie: Turn that into a path someone can follow.

      +

      Alex: First, after editing, activate the Commit changes button (green button above the editor). Then, a dialog appears. In the Branch name field, type: fix/yourname-issueXX (replace yourname with your GitHub username, and XX with the issue number). After that, select Create a new branch for this commit and start a pull request. Finally, activate Propose changes. Treat it like a recipe: do not add the next ingredient until the previous one is actually in the bowl.

      +

      Alex: A solid Git habit is to know which branch you are on, what changed, and what confirmation you expect before you run the next command.

      +

      Jamie: Let's pause on Challenge 6.2 Step-by-Step: Open a Linked PR. What should a learner take away from it?

      +

      Alex: Here is the plain-English version of Challenge 6.2 Step-by-Step: Open a Linked PR. AI agents do not just deploy code directly; they submit pull requests. Put another way, learning to edit a file, format it in Markdown, and review a PR today prepares you to audit and approve AI-generated changes tomorrow.

      +

      Alex: These are the details that keep the idea from floating away. "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". A summary of what you changed and why (at least 50 characters).

      +

      Alex: First, in the Title field, write a short description of your change. Then, in the Body field, use the PR template if one is provided. Make sure to. After that, verify the base branch is main and the compare branch is your fix/yourname-issueXX branch. Finally, activate the Create pull request button. Treat it like a recipe: do not add the next ingredient until the previous one is actually in the bowl.

      +

      Jamie: Let's pause on Challenge 6.3 Step-by-Step: Pass Required Checks. What should a learner take away from it?

      +

      Alex: This is where Challenge 6.3 Step-by-Step: Pass Required Checks becomes real: read bot feedback, fix any issues it finds, and get all required checks to pass. That matters in practice: the Conversation tab of your open pull request. The workshop is closer to rehearsal than lecture. You hear the move, try the move, and then check what changed.

      +

      Alex: That becomes easier when you listen for these cues. 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.

      +

      Alex: First, wait approximately 30 seconds after opening the PR. The bot posts a validation comment. Then, read the bot comment carefully. It checks. After that, if the bot reports failures. Finally, repeat step 3 until all required checks show a green checkmark. It is a checklist, but a meaningful one: every item creates evidence that the next step is safe.

      +

      Jamie: Before we leave Challenge 6.3 Step-by-Step: Pass Required Checks, what is the practical point?

      +

      Alex: First, when all checks pass, request a review from a peer or the facilitator. It is like walking a hallway with named doors: read the sign, enter the right room, then confirm where you landed.

      -

      Jamie: Let's pause on Example: Informational Agent - @insiders-a11y-tracker. What should a learner take away from it?

      -

      Alex: Keep the learner anchored in Example: Informational Agent - @insiders-a11y-tracker. This agent monitors VS Code Insiders releases for accessibility improvements. This is the part to say slowly: It searches the microsoft/vscode repository using predefined GitHub query syntax, so you never have to remember the exact filter parameters.

      -

      Jamie: Let's pause on Use it. What should a learner take away from it?

      -

      Alex: The reason Use it matters is that prerequisite: GitHub MCP server installed (github.com/github/github-mcp-server).

      -

      Alex: First, select @insiders-a11y-tracker from the agent picker. Then, ask: what shipped this month? or any keyboard navigation improvements in January? After that, the agent searches with repo:microsoft/vscode is:closed milestone:"[Month] [Year]" label:accessibility label:insiders-released and returns formatted results. The rhythm is simple: orient, act, verify, then continue.

      -

      Jamie: Let's pause on Example: Task-Oriented Agent - The Markdown Accessibility Assistant. What should a learner take away from it?

      -

      Alex: Start with Example: Task-Oriented Agent - The Markdown Accessibility Assistant: The GitHub Accessibility team published a complete walkthrough for building a Markdown Accessibility Assistant - a task-oriented agent that reviews Markdown files for accessibility issues and makes direct fixes. The next useful detail is this: This agent is the automated version of the accessibility review skills you built during Day 1.

      -

      Alex: The practical takeaway is this. Runs markdownlint-cli2 to catch structural problems (heading skips, bare URLs, missing blank lines). Reviews link text for descriptiveness. Flags missing or inadequate alt text and waits for your approval before changing it (alt text requires human judgment). Fixes heading hierarchy, list structure, and bare URL formatting directly.

      +

      Jamie: Let's pause on Expected Outcomes. What should a learner take away from it?

      +

      Alex: Start with Expected Outcomes. There is something to understand, something to try, and something that proves the try worked.

      +

      Alex: The practical anchors are these. Student opens a focused PR that maps to one issue. Student uses Closes XX correctly. Student can interpret bot feedback and improve the PR.

      +

      Jamie: Let's pause on If You Get Stuck. What should a learner take away from it?

      +

      Alex: Start with If You Get Stuck. There is something to understand, something to try, and something that proves the try worked.

      +

      Alex: First, confirm your PR includes Closes XX in title or body. Then, check that changed files are only in learning-room/. After that, open the bot validation comment and resolve one required check at a time. Finally, if checks still fail, ask for peer or facilitator review with the exact error message. The rhythm is simple: orient, act, verify, then continue.

      +

      Jamie: Before we leave If You Get Stuck, what is the practical point?

      +

      Alex: First, finished but not sure you did it right? Compare your work against the Challenge 6 reference solution. Think of it as a rail line: each stop confirms you are still on the right route before the next one.

      +

      Jamie: Let's pause on Learning Moment. What should a learner take away from it?

      +

      Alex: Start with Learning Moment: A great PR is small, linked to an issue, and easy to review. The next useful detail is this: Faster feedback builds confidence and momentum.

      -

      Alex: Keep the teaching thread moving. Here is the plain-English version of Key Pattern: Tiered Decision-Making. This tiered approach - automate what can be objectively evaluated, flag what needs human judgment - is the right model for any accessibility agent. Put another way, it maximizes the agent's value while keeping humans in control of decisions that require context. It is like learning a transit route. The names of the stops matter because they tell you whether you are still going the right direction.

      -

      Jamie: Let's pause on Required Prerequisites for the Markdown Accessibility Assistant. What should a learner take away from it?

      -

      Alex: Start with Required Prerequisites for the Markdown Accessibility Assistant. There is something to understand, something to try, and something that proves the try worked.

      -

      Alex: The practical takeaway is this. GitHub MCP server installed and configured (github.com/github/github-mcp-server). Node.js installed (for npx markdownlint-cli2).

      -

      Jamie: Let's pause on From VS Code. What should a learner take away from it?

      -

      Alex: Start with From VS Code. There is something to understand, something to try, and something that proves the try worked.

      -

      Alex: First, open Copilot Chat (Ctrl+Shift+I / Cmd+Shift+I on macOS). Then, in the Chat input toolbar, select the Set Agent button. After that, select your custom agent from the agent picker. Finally, type your request - the agent executes in your local workspace. It is like walking a hallway with named doors: read the sign, enter the right room, then confirm where you landed.

      +

      Alex: This is the part worth saying out loud. Start with Why this feels achievable. There is something to understand, something to try, and something that proves the try worked.

      +

      Alex: That shows up in the workshop in a few specific ways. Scope is intentionally small. Feedback is immediate and specific. Success is visible (green checks + closed issue).

      +

      Jamie: Let's pause on About Learning Cards in This Chapter. What should a learner take away from it?

      +

      Alex: This is where About Learning Cards in This Chapter becomes real: this chapter provides learning cards: expandable blocks that offer perspective-specific guidance for different ways of working. That matters in practice: Not every card appears at every step.

      +

      Jamie: What should happen before anyone copies and runs it?

      +

      Alex: Keep the learner anchored in Local Git Alternative: The Full Branch-Edit-PR Workflow. If you cloned the learning-room in Block 0 and prefer working locally. This is the part to say slowly: The web editor workflow (pencil button, "Propose changes") is the primary path taught in this chapter.

      +

      Alex: Treat examples as spoken recipes, not decorations. You may hear something like cd /Documents/learning-room; git checkout main; git pull origin main; git checkout -b fix/welcome-todos. code docs/welcome.md. Read the command, understand what it changes, then run it only when the repository state matches the lesson.

      -

      Jamie: Let's pause on From GitHub.com (Task mode). What should a learner take away from it?

      -

      Alex: Start with From GitHub.com (Task mode). There is something to understand, something to try, and something that proves the try worked.

      -

      Alex: First, open Copilot Chat on GitHub.com. Then, select Task from the mode picker. After that, optionally select a custom agent from the agent picker. Finally, submit your request - the agent can create a PR automatically. The rhythm is simple: orient, act, verify, then continue.

      -

      Jamie: Let's pause on From an issue (Issue Assignment). What should a learner take away from it?

      -

      Alex: Start with From an issue (Issue Assignment). There is something to understand, something to try, and something that proves the try worked.

      -

      Alex: First, open any issue → Assignees → assign Copilot. Then, in the dialog, optionally select a custom agent. After that, select Assign - Copilot creates a branch, makes changes, and opens a PR. Think of it as a rail line: each stop confirms you are still on the right route before the next one.

      -

      Jamie: What is the pre-flight check here?

      -

      Alex: Here is the plain-English version of Environment Setup for GitHub (Cloud Agents). When agents run on GitHub (not locally), they may need additional tools. Put another way, create a workflow file at.github/workflows/copilot-setup-steps.yml with a single job named copilot-setup-steps.

      +

      Jamie: Let's pause on What Is a Pull Request? What should a learner take away from it?

      +

      Alex: The reason What Is a Pull Request? matters is that a pull request (PR) is a proposal to merge changes from one branch into another. That gives the learner a simple foothold.you open a PR to request that those changes be merged into the target branch (usually main).

      +

      Alex: The practical takeaway is this. Edited a file directly on GitHub (web editor). Made changes in your fork. Made changes on a feature branch. What changed - a diff of every file.

      +

      Jamie: Let's pause on Navigating to Pull Requests. What should a learner take away from it?

      +

      Alex: Start with Navigating to Pull Requests: Global pull requests dashboard: GitHub now shows a global pull requests page at github.com/pulls listing all open PRs across every repository you have access to. The next useful detail is this: 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). Think of it like entering a new building: first you find the lobby, then the room, then the door you actually need.

      +

      Alex: The practical takeaway is this. 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.

      +

      Alex: First, d → "Repository navigation" landmark. Then, k to navigate tabs → "Pull requests, [N] open". After that, enter to open. Finally, vO+U → Landmarks → navigate to "Repository navigation". Think of it as a rail line: each stop confirms you are still on the right route before the next one.

      +

      Jamie: Before we leave Navigating to Pull Requests, what is the practical point?

      +

      Alex: First, quick Nav K or VO+Right to navigate tabs → "Pull requests". Then, vO+Space to open. Treat it like a recipe: do not add the next ingredient until the previous one is actually in the bowl.

      +

      Jamie: What is the safe way to learn from that example?

      +

      Alex: Here is the plain-English version of From a PR notification. If you received a notification about a PR, follow the notification link directly to the PR page. Put another way, list and view pull requests from your terminal.

      +

      Alex: Treat examples as spoken recipes, not decorations. You may hear something like 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. Read the command, understand what it changes, then run it only when the repository state matches the lesson.

      -

      Jamie: Let's pause on To Create Your Own Agent. What should a learner take away from it?

      -

      Alex: Start with To Create Your Own Agent. There is something to understand, something to try, and something that proves the try worked.

      -

      Alex: First, create.github/agents/your-agent-name.agent.md. Then, write YAML frontmatter (name, description, tools). After that, write the system prompt - identity, capabilities, domain knowledge, behavioral rules, output format. Finally, save and reload VS Code (Ctrl+Shift+P → "Reload Window"). It is a checklist, but a meaningful one: every item creates evidence that the next step is safe.

      -

      Jamie: Before we leave To Create Your Own Agent, what is the practical point?

      -

      Alex: First, type @your-agent-name in Copilot Chat. It is like walking a hallway with named doors: read the sign, enter the right room, then confirm where you landed.

      -

      Jamie: What makes this practice feel low-stakes but still real?

      -

      Alex: Keep the learner anchored in Exercise: Extend the Template Builder Agent. You've built templates manually (Chapters 15-16) and seen them in action. This is the part to say slowly: Now see how to harness AI to generate templates interactively, and learn to customize agents for your own projects.

      -

      Alex: The practical takeaway is this. Complete Chapters 15-16 (especially Exercise D - designing your own template). VS Code is installed and GitHub Copilot is active. You have forked accessibility-agents to your GitHub account. You have cloned your fork locally: git clone https://github.com/[your-username]/accessibility-agents.git.

      -

      Jamie: Let's pause on Exercise 1: Generate a Template with the Agent. What should a learner take away from it?

      -

      Alex: The reason Exercise 1: Generate a Template with the Agent matters is that your Mission: Use the @template-builder agent to generate an accessibility bug report template interactively. That gives the learner a simple foothold: you'll experience the agent as an end-user and see what production-ready agent output looks like. The interface gets friendlier when it stops being a wall of controls and starts being a set of named places.

      -

      Alex: The practical takeaway is this. Left sidebar showing.github/, docs/, learning-room/, README.md, etc. The status bar at the bottom shows your current git branch (probably main). Alternative: Use menu: View → Copilot Chat. Copilot is now ready to receive instructions.

      -

      Alex: First, open VS Code. Then, file → Open Folder → select your locally cloned accessibility-agents folder. After that, the folder tree appears on the left showing the repository structure. Finally, verify you're in the right place: The folder name should be accessibility-agents at the top of the sidebar. The rhythm is simple: orient, act, verify, then continue.

      -

      Jamie: Before we leave Exercise 1: Generate a Template with the Agent, what is the practical point?

      -

      Alex: First, keyboard shortcut: Press Ctrl+Shift+I (Windows/Linux) or Cmd+Shift+I (macOS). Then, a chat panel opens on the right side of VS Code. After that, at the top, you see "Copilot Chat" and probably a text input at the bottom saying "Ask Copilot.". Finally, click in the chat input box (bottom of Copilot Chat panel). Think of it as a rail line: each stop confirms you are still on the right route before the next one.

      -

      Alex: Treat examples as spoken recipes, not decorations. You may hear something like Q: Template name?; A: Accessibility Bug Report; Q: What's it for?; A: Report screen reader and keyboard navigation issues; Q: First field name?; A: Screen Reader; Q: Field type?; A: dropdown; Q: Dropdown options? (comma-separated); A: NVDA, JAWS, VoiceOver,. Read the command, understand what it changes, then run it only when the repository state matches the lesson.

      +

      Alex: Keep the thread going. Start with Learning Cards: Navigating to Pull Requests. There is something to understand, something to try, and something that proves the try worked.

      +

      Alex: The practical takeaway is this. 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. 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.

      +

      Jamie: Let's pause on The Pull Request List Page. What should a learner take away from it?

      +

      Alex: Keep the learner anchored in The Pull Request List Page. The PR list works identically to the Issues list. This is the part to say slowly: for screen reader users, - PR list semantics: The PR list does not have individual ARIA item containers with per-item semantics.

      +

      Alex: The practical takeaway is this. 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.

      +

      Jamie: Let's pause on Navigating the PR Tab Bar. What should a learner take away from it?

      +

      Alex: The reason Navigating the PR Tab Bar matters is that the Conversation, Commits, and Files changed tabs are in a "Pull request navigation tabs" landmark. That gives the learner a simple foothold: the three tabs - Conversation, Commits, and Files changed - appear just below the PR title. The interface gets friendlier when it stops being a wall of controls and starts being a set of named places.

      +

      Alex: The practical takeaway is this. 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.

      +

      Alex: First, press D → navigate to "Pull request navigation tabs". Then, press ← or → arrow keys to move between tab options. After that, press Enter to activate a tab. Finally, vO+U → Landmarks → "Pull request navigation tabs". The rhythm is simple: orient, act, verify, then continue.

      +

      Jamie: Before we leave Navigating the PR Tab Bar, what is the practical point?

      +

      Alex: First, vO+Right to move between tabs. Then, vO+Space to activate. Think of it as a rail line: each stop confirms you are still on the right route before the next one.

      -

      Jamie: Let's pause on Exercise 2: Extend the Agent for Your Project. What should a learner take away from it?

      -

      Alex: Start with Exercise 2: Extend the Agent for Your Project: Your Mission: Customize the Template Builder agent to recognize and guide a Security Vulnerability Report template. The next useful detail is this: This teaches you how to tailor agents for project-specific needs.

      -

      Alex: The practical takeaway is this. The file starts with YAML frontmatter (name, description, topics). Below that, sections like " How to Use", " Pre-Built Workflow". Search for the text "Pre-Built Workflow: Guided Accessibility Template".

      -

      Alex: First, in VS Code, navigate to.github/agents/. Then, file: template-builder.agent.md. After that, double-click to open it in the editor. Finally, you see the agent's instructions in Markdown format. Think of it as a rail line: each stop confirms you are still on the right route before the next one.

      -

      Jamie: Before we leave Exercise 2: Extend the Agent for Your Project, what is the practical point?

      -

      Alex: First, use Ctrl+F to open Find. Then, search for: Pre-Built Workflow. After that, press Enter to jump to the first match. Finally, you should land on the "Pre-Built Workflow: Guided Accessibility Template" section. Treat it like a recipe: do not add the next ingredient until the previous one is actually in the bowl.

      -

      Jamie: Let's pause on What you're adding. What should a learner take away from it?

      -

      Alex: Here is the plain-English version of What you're adding. If the agent doesn't recognize your new workflow.

      -

      Alex: The practical takeaway is this. A clear label for the new workflow. Instructions on how to invoke it. Pre-defined fields that make sense for security reports. Specific options for severity and vulnerability type. The agent recognizes your new workflow. Next time you invoke @template-builder with "create security template", it will follow your new guidance.

      -

      Alex: First, save the file: Ctrl+S. Then, you should see no error messages. After that, the agent file now includes your new Pre-Built Workflow. Finally, open Copilot Chat again: Ctrl+Shift+I. Treat it like a recipe: do not add the next ingredient until the previous one is actually in the bowl.

      -

      Jamie: Before we leave What you're adding, what is the practical point?

      -

      Alex: First, press Enter. Then, the agent should now ask vulnerability-specific questions. After that, commit your agent change. Finally, the extended agent is now in your fork. It is a checklist, but a meaningful one: every item creates evidence that the next step is safe.

      -

      Alex: Treat examples as spoken recipes, not decorations. You may hear something like git add.github/agents/template-builder.agent.md; git commit -m "feat: add security vulnerability template workflow to template-builder agent"; git push origin main. Read the command, understand what it changes, then run it only when the repository state matches the lesson.

      -

      Jamie: Let's pause on Exercise 3: Iterative Refinement with Agents. What should a learner take away from it?

      -

      Alex: This is where Exercise 3: Iterative Refinement with Agents becomes real: your Mission: Generate a template, then ask the agent to modify it incrementally. That matters in practice: This teaches you the iterative pattern that scales to all agent-assisted workflows.

      -

      Alex: The practical takeaway is this. Running a complete template generation (same as Exercise 1). The agent modifies the YAML it generated. The new checkbox appears in the YAML with proper formatting and indentation. It doesn't regenerate from scratch - just adds your change.

      -

      Alex: First, in Copilot Chat, type: @template-builder create a feature request template. Then, answer the agent's questions to build a feature request form. After that, let the agent generate the YAML. Finally, copy it to a file.github/ISSUE TEMPLATE/feature-request.yml. It is a checklist, but a meaningful one: every item creates evidence that the next step is safe.

      -

      Jamie: Before we leave Exercise 3: Iterative Refinement with Agents, what is the practical point?

      -

      Alex: First, once the template is generated, while still in the same chat conversation, ask. Then, the agent regenerates the YAML with your new checkbox added in the right place (usually as required field pre-validation). After that, follow up. Finally, the agent modifies the textarea field's attributes to enable code highlighting. It is like walking a hallway with named doors: read the sign, enter the right room, then confirm where you landed.

      +

      Jamie: Let's pause on PR Description. What should a learner take away from it?

      +

      Alex: Start with PR Description. There is something to understand, something to try, and something that proves the try worked.

      +

      Alex: First, 2 → navigate to "Description" h2 heading. Then, ↓ to read the description. After that, markdown renders as semantic HTML - headings, lists, code blocks are fully accessible. Think of it as a rail line: each stop confirms you are still on the right route before the next one.

      +

      Jamie: Let's pause on Status Checks Section. What should a learner take away from it?

      +

      Alex: Here is the plain-English version of Status Checks Section. Below the description, the status checks summary shows whether automated tests passed. Put another way, status checks appear as a coloured banner below the PR description - green tick for passed, red X for failed, yellow spinner for running.

      +

      Alex: The practical takeaway is this. "All checks have passed" / "Some checks failed" / "Checks pending". A "Show all checks" button or link.

      +

      Alex: First, press H or 2 to find the "Checks" or "Status checks" heading. Then, press K to navigate links for individual check names. After that, press Enter on a check to see its details. Finally, quick Nav H or VO+Cmd+H to jump to the "Checks" or "Status checks" heading. Treat it like a recipe: do not add the next ingredient until the previous one is actually in the bowl.

      +

      Jamie: Before we leave Status Checks Section, what is the practical point?

      +

      Alex: First, quick Nav K to navigate check name links. Then, vO+Space on a check to see its details. It is a checklist, but a meaningful one: every item creates evidence that the next step is safe.

      +

      Jamie: Let's pause on Review Comments. What should a learner take away from it?

      +

      Alex: This is where Review Comments becomes real: each review comment thread is an h3.

      +

      Alex: The practical takeaway is this. 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.

      -

      Jamie: Let's pause on What Comes Next. What should a learner take away from it?

      -

      Alex: Keep the learner anchored in What Comes Next. Your next step: explore the broader ecosystem. This is the part to say slowly: That is Accessibility Agents' promise: not to replace your thinking, but to amplify your skills across all 55 agents - and to grow through the contributions of everyone who uses it. A good GitHub workflow is like a well-run meeting: everyone knows the topic, the next action, and who has the floor.

      -

      Alex: The practical takeaway is this. Browse the full agent list - which agents solve problems you face regularly? Try an Accessibility team agent: @contrast-master check this page or @alt-text-headings review this file. Try a Developer Tools agent: @python-specialist review this module for accessibility or @desktop-a11y-specialist audit this dialog. Think about what is missing: what agent would you build if you could?

      -

      Alex: First, generated a template using an agent (Exercise 1). Then, customized an agent for your domain (Exercise 2). After that, refined iteratively with agent help (Exercise 3). It is like walking a hallway with named doors: read the sign, enter the right room, then confirm where you landed.

      -

      Jamie: Let's pause on Learning Cards: Contributing to the Ecosystem. What should a learner take away from it?

      -

      Alex: Start with Learning Cards: Contributing to the Ecosystem. There is something to understand, something to try, and something that proves the try worked.

      -

      Alex: The practical takeaway is this. Agent.agent.md files use YAML frontmatter at the top (between --- delimiters) followed by Markdown body; in VS Code, use Ctrl+G to jump to line 1 and arrow through the frontmatter fields (name, description, tools) before reading the body instructions. When writing your own.agent.md, use VS Code's Outline view (Ctrl+Shift+O) to verify that your Markdown headings (Purpose, Capabilities, Responsibilities) are correctly nested -- malformed headings will not appear in the outline. Before submitting a PR with a new agent file, run the file through a YAML linter (install the YAML extension, or use yamllint from the terminal) -- frontmatter syntax errors silently break agent registration. YAML frontmatter fields are densely packed with colons and quotes; increase your editor font size or use a monospaced font with wide character spacing so name:, description:, and tools: are clearly distinct. The.agent.md files in the agents/ directory follow a consistent structure -- use the file explorer's icon theme or file nesting feature to visually group agent files separately from regular documentation. When reviewing existing agents for contribution ideas, use VS Code's split editor to place the agent file and the README side by side so you can cross-reference the agent's instructions with its documented capabilities.

      -

      Alex: Keep the teaching thread moving. Start with 7. The Bigger Picture: Teams, Orchestration, and Beyond VS Code: The 55 agents are not 55 independent tools. The next useful detail is this: They are organized into three teams that work together, and several orchestrator agents exist specifically to coordinate multi-agent workflows.

      +

      Jamie: Let's pause on Resolving conversations. What should a learner take away from it?

      +

      Alex: Keep the learner anchored in Resolving conversations. When a review comment has been addressed, you can mark the conversation as resolved. This is the part to say slowly: Resolved conversations are still accessible - they collapse but can be expanded again. A good GitHub workflow is like a well-run meeting: everyone knows the topic, the next action, and who has the floor.

      +

      Alex: First, navigate to the conversation thread (3 to jump between comment headings). Then, tab to the end of the thread to find the "Resolve conversation" button. After that, press Enter to mark it resolved. Finally, the conversation collapses and shows as "Resolved". It is like walking a hallway with named doors: read the sign, enter the right room, then confirm where you landed.

      +

      Jamie: Let's pause on Learning Cards: Reading the Conversation Tab. What should a learner take away from it?

      +

      Alex: Start with Learning Cards: Reading the Conversation Tab. There is something to understand, something to try, and something that proves the try worked.

      +

      Alex: The practical takeaway is this. 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. 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.

      +

      Jamie: Let's pause on Reading the Checks Tab. What should a learner take away from it?

      +

      Alex: Start with Reading the Checks Tab: The Checks tab shows the status of automated tests, CI workflows, and other verification processes running on your PR. The next useful detail is this: It helps you verify whether your changes pass all required tests before merging.

      +

      Alex: The practical takeaway is this. Navigate through the check steps with K or Tab. Activate a step for more details.

      +

      Alex: First, navigate to the "Pull request tabs" landmark (D). Then, navigate between tab links (K or Tab) and activate "Checks". After that, press D to jump to the "check suites" section - this moves focus to the collapsed details button of the first check. Finally, press B or Tab to navigate between check buttons; each button is labeled with the check's name. Think of it as a rail line: each stop confirms you are still on the right route before the next one.

      +

      Jamie: Before we leave Reading the Checks Tab, what is the practical point?

      +

      Alex: First, press Enter or Space to expand a check and reveal its logs. Then, for a summary view: press D to navigate to the "check run summary" section. After that, vO+U - Landmarks - "Pull request tabs" - activate "Checks". Finally, vO+U - Landmarks - navigate to "check suites" section. Treat it like a recipe: do not add the next ingredient until the previous one is actually in the bowl.

      -

      Jamie: Let's pause on How the Three Teams Connect. What should a learner take away from it?

      -

      Alex: Here is the plain-English version of How the Three Teams Connect. In practice, a single task often spans multiple teams. Put another way, no single agent covers the entire workflow.

      -

      Alex: The practical takeaway is this. You ask @daily-briefing (GitHub Workflow) for your morning report. It flags a PR that changes ARIA attributes. You ask @pr-review (GitHub Workflow) to generate a structured review of that PR. The review notes potential accessibility impact. You invoke @aria-specialist (Accessibility) to deep-check the ARIA changes. It identifies a missing aria-expanded state on a disclosure widget. You fix the issue using patterns from @desktop-a11y-specialist (Developer Tools) if it is a desktop application, or directly in the HTML if it is a web project.

      -

      Alex: Keep the teaching thread moving. Start with Learning Cards: Teams and Orchestration. There is something to understand, something to try, and something that proves the try worked.

      -

      Alex: The practical takeaway is this. Orchestrator agents like @accessibility-lead coordinate multi-agent workflows -- invoke one and it delegates to specialists, announcing which agent it is calling. Multi-agent output appears in sequence in Copilot Chat -- press Alt+F2 after each response to read it in Accessible View before the next agent responds. The three teams are GitHub Workflow (what happened), Accessibility (is it correct), and Developer Tools (fix it) -- choose your entry point based on your current task. Orchestrator responses can be long -- use Accessible View (Alt+F2) or widen the Chat panel to read comfortably at high zoom. The workflow diagrams in this section are described in text -- no visual-only content is required to understand the agent coordination pattern. Each team's agents are listed in the tables in Section 3 -- refer back there to find the right specialist agent.

      -

      Jamie: Let's pause on Orchestrator Agents. What should a learner take away from it?

      -

      Alex: Keep the learner anchored in Orchestrator Agents. Four agents are specifically designed to coordinate others. This is the part to say slowly: You do not need to use orchestrators to get value from individual agents.

      +

      Jamie: Let's pause on Learning Cards: Reading the Checks Tab. What should a learner take away from it?

      +

      Alex: Start with Learning Cards: Reading the Checks Tab. There is something to understand, something to try, and something that proves the try worked.

      +

      Alex: The practical takeaway is this. 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. 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.

      +

      Alex: Here is the practical turn. This is where Reading the Files Changed Tab becomes real: the learner will read diffs - the before/after state of every file that changed. That matters in practice: This guide uses GitHub's improved Files Changed experience. The workshop is closer to rehearsal than lecture. You hear the move, try the move, and then check what changed.

      +

      Jamie: Let's pause on File Tree (left panel). What should a learner take away from it?

      +

      Alex: Keep the learner anchored in File Tree (left panel). The file tree lists every changed file. This is the part to say slowly: Use it to jump directly to a specific file's diff.

      +

      Alex: The practical takeaway is this. 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.

      +

      Alex: First, d → navigate to "File tree" region. Then, ↑/↓ to navigate the file list. After that, enter to jump to that file's diff. Finally, vO+U → Landmarks → navigate to "File tree" region. It is like walking a hallway with named doors: read the sign, enter the right room, then confirm where you landed.

      +

      Jamie: Before we leave File Tree (left panel), what is the practical point?

      +

      Alex: First, vO+Down to move through the file list. Then, vO+Space to jump to that file's diff. The rhythm is simple: orient, act, verify, then continue.

      -

      Alex: Keep the teaching thread moving. The reason High-Impact Agents to Try First matters is that rather than exploring all 55 agents at once, start with the ones that deliver immediate value based on Day 1 skills you already have.

      -

      Jamie: Let's pause on Slash Commands That Save the Most Time. What should a learner take away from it?

      -

      Alex: Start with Slash Commands That Save the Most Time: These commands work without invoking a full agent - type them directly in Copilot Chat. The next useful detail is this: The full list of 54+ commands is in Appendix L, and Episode 39 walks through all of them with examples.

      -

      Alex: The practical takeaway is this. /my-issues and /my-prs - Instant dashboard of your open work across all repos. /review-pr 14 - Full AI-generated review with inline suggestions, replacing manual line-by-line reading. /triage 22 - Label, priority, and assignment suggestions for any new issue. /daily-briefing - Morning snapshot of repository activity, PRs needing review, and stale issues.

      -

      Alex: Keep the teaching thread moving. Here is the plain-English version of Running Agents Beyond VS Code. Accessibility Agents' agents run on your machine, in your editor, when you ask for them. Put another way, the same Markdown-authored pattern extends further. It is like learning a transit route. The names of the stops matter because they tell you whether you are still going the right direction.

      +

      Alex: Another way to ground it. Start with The Diff for a File. There is something to understand, something to try, and something that proves the try worked.

      +

      Alex: The practical takeaway is this. 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.

      +

      Jamie: Let's pause on Lines in a diff are read as. What should a learner take away from it?

      +

      Alex: Start with Lines in a diff are read as. There is something to understand, something to try, and something that proves the try worked.

      +

      Alex: The practical takeaway is this. + Added line - line that was added. Removed line - line that was removed. Context line - unchanged line shown for context.

      +

      Jamie: Let's pause on Navigating the diff with a screen reader. What should a learner take away from it?

      +

      Alex: Here is the plain-English version of Navigating the diff with a screen reader. Each file's diff shows added lines in green and removed lines in red. Put another way, scroll the page to read through changes. It is like learning a transit route. The names of the stops matter because they tell you whether you are still going the right direction.

      +

      Alex: The practical takeaway is this. 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.

      +

      Alex: First, t to jump to the next diff table. Then, switch to Focus Mode: Insert+Space (NVDA) or Insert+Z (JAWS). After that, ctrl+Alt+↓ to move down one row (next diff line), Ctrl+Alt+↑ to move up. Finally, ctrl+Alt+→ to read across columns (line number change type content). Treat it like a recipe: do not add the next ingredient until the previous one is actually in the bowl.

      +

      Jamie: Before we leave Navigating the diff with a screen reader, what is the practical point?

      +

      Alex: First, the screen reader reads: "+ Add accessible name to submit button". Then, collapsed sections contain unchanged code. Focus the expand/disclosure control and activate it (Enter or Space) to reveal the hidden lines. After that, t or VO+U → Tables → select the diff table. Finally, vO+Shift+Down to enter the table. It is a checklist, but a meaningful one: every item creates evidence that the next step is safe.

      -

      Jamie: Let's pause on Scope 1: Your Editor (Accessibility Agents). What should a learner take away from it?

      -

      Alex: Start with Scope 1: Your Editor (Accessibility Agents). There is something to understand, something to try, and something that proves the try worked.

      -

      Alex: The practical takeaway is this. File lives in.github/agents/[name].agent.md in your workspace. Triggered by: You, when you type @[agent-name] in Copilot Chat. Runs on: Your machine, using your Copilot subscription. Reaches: Every repository your GitHub account has access to. Scale: All 55 agents available when the workspace is open.

      -

      Alex: Keep the teaching thread moving. Keep the learner anchored in Scope 2: Your Repository (Travels with Forks). When you fork accessibility-agents, all 55 agents come with it. This is the part to say slowly: You can edit them for your project's context.

      -

      Alex: The practical takeaway is this. File lives in.github/agents/[name].agent.md in the repo. Triggered by: Any contributor who has Copilot and opens the repo as a VS Code workspace. Runs on: Their machine, using their Copilot subscription. Reaches: Their GitHub account's repositories.

      -

      Jamie: Let's pause on Scope 3: The Cloud (GitHub Agentic Workflows). What should a learner take away from it?

      -

      Alex: The reason Scope 3: The Cloud (GitHub Agentic Workflows) matters is that the workflow runs whether or not anyone is watching - when an issue is opened at 3am, the agentic response fires. That gives the learner a simple foothold: the link between Accessibility Agents and Agentic Workflows: Both use Markdown-authored instructions.

      -

      Alex: The practical takeaway is this. File lives in.github/workflows/[name].md (same folder as standard Actions YAML). Triggered by: Any GitHub event - issues: opened, pull request: created, schedule. Runs on: GitHub Actions infrastructure, serverlessly. Reaches: The repository where the workflow is defined.

      +

      Jamie: Let's pause on Placing an inline comment on a diff line. What should a learner take away from it?

      +

      Alex: This is where Placing an inline comment on a diff line becomes real: hover over any line in the diff - a blue + button appears on the left margin. That matters in practice: Click it to open a comment box for that line.

      +

      Alex: The practical takeaway is this. 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.

      +

      Alex: First, navigate to the specific line in the diff (using the table navigation above). Then, while focused on that line, a comment button appears - press Enter or Space to activate it. After that, a comment box opens below the line. Finally, focus Mode → type your comment. It is a checklist, but a meaningful one: every item creates evidence that the next step is safe.

      +

      Jamie: Before we leave Placing an inline comment on a diff line, what is the practical point?

      +

      Alex: First, tab to Add single comment button (instant comment) OR Start a review (to batch comments). It is like walking a hallway with named doors: read the sign, enter the right room, then confirm where you landed.

      +

      Jamie: Let's pause on Multi-line comment (Windows). What should a learner take away from it?

      +

      Alex: Keep the learner anchored in Multi-line comment (Windows). Screen reader users (VoiceOver - macOS).

      +

      Alex: First, focus the first line you want to comment on. Then, press Shift+↓ to extend the selection to additional lines. After that, a comment button appears - activate it. Finally, the comment applies to the full range of selected lines. It is like walking a hallway with named doors: read the sign, enter the right room, then confirm where you landed.

      +

      Jamie: Before we leave Multi-line comment (Windows), what is the practical point?

      +

      Alex: First, navigate to the specific line in the diff (using the table navigation above). Then, while focused on that line, VO+Space on the comment button that appears. After that, a comment box opens below the line. Finally, vO+Shift+Down to interact with the text area, then type your comment. The rhythm is simple: orient, act, verify, then continue.

      +

      Jamie: Let's pause on Multi-line comment (macOS). What should a learner take away from it?

      +

      Alex: Start with Multi-line comment (macOS). There is something to understand, something to try, and something that proves the try worked.

      +

      Alex: First, focus the first line and Shift+↓ to extend the selection. Then, vO+Space on the comment button that appears. After that, the comment applies to the full range of selected lines. The rhythm is simple: orient, act, verify, then continue.

      -

      Alex: Keep the teaching thread moving. Start with Go Deeper: For full documentation on every agent, all 54+ slash commands, customization formats, and troubleshooting, see Appendix L: Accessibility Agents Reference. The next useful detail is this: For the audio version, listen to Episode 39: Accessibility Agents - Complete Reference. Think of it like entering a new building: first you find the lobby, then the room, then the door you actually need.

      -

      Jamie: Let's pause on Example: Auto-triage accessibility issues. What should a learner take away from it?

      -

      Alex: Here is the plain-English version of Example: Auto-triage accessibility issues. File.github/workflows/auto-triage-a11y.md. Put another way, this runs automatically on every new issue.

      -

      Alex: Keep the teaching thread moving. This is where 8. GitHub Desktop, GitHub CLI, and Copilot CLI becomes real: these tools are not required for this workshop, but are worth knowing as options for different workflows.

      +

      Alex: The next layer is this. Start with Viewing comments within the diff: Inline comments appear as expandable threads within the diff table. The next useful detail is this: Navigate to them with 3 (they are h3 headings). Think of it like entering a new building: first you find the lobby, then the room, then the door you actually need.

      +

      Jamie: Let's pause on Learning Cards: Reading the Files Changed Tab. What should a learner take away from it?

      +

      Alex: Start with Learning Cards: Reading the Files Changed Tab. There is something to understand, something to try, and something that proves the try worked.

      +

      Alex: The practical takeaway is this. 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. 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.

      +

      Jamie: Let's pause on Tool Cards: Open a Pull Request. What should a learner take away from it?

      +

      Alex: This is where Tool Cards: Open a Pull Request becomes real: VS Code Desktop (GitHub Pull Requests extension).

      +

      Alex: First, push your branch, then click the Compare & pull request banner (or go to Pull requests New pull request ). Then, set base branch to main, compare branch to yours. After that, fill in the title and description, then click Create pull request. Finally, after committing changes, click the Source Control icon. It is a checklist, but a meaningful one: every item creates evidence that the next step is safe.

      +

      Jamie: Before we leave Tool Cards: Open a Pull Request, what is the practical point?

      +

      Alex: First, click Create Pull Request in the Source Control panel header. Then, fill in details and submit. After that, press Ctrl+Shift+P, type GitHub Pull Requests: Create Pull Request. Finally, select base and compare branches. It is like walking a hallway with named doors: read the sign, enter the right room, then confirm where you landed.

      +

      Alex: Treat examples as spoken recipes, not decorations. You may hear something like git push -u origin your-branch; gh pr create --title "Your title" --body "Description". Read the command, understand what it changes, then run it only when the repository state matches the lesson.

      -

      Jamie: Let's pause on GitHub Desktop. What should a learner take away from it?

      -

      Alex: Keep the learner anchored in GitHub Desktop. A graphical Git application with an accessible interface. This is the part to say slowly: When to use: If command-line Git feels overwhelming, GitHub Desktop provides a GUI alternative.

      -

      Alex: The practical takeaway is this. Download: desktop.github.com. Useful for: Visual diff review, simpler branch management. Screen reader support: Partial - keyboard navigation works for core flows.

      -

      Alex: Keep the teaching thread moving. The reason GitHub CLI (gh) matters is that a command-line interface for GitHub operations. The interface gets friendlier when it stops being a wall of controls and starts being a set of named places.

      -

      Jamie: What is the safe way to learn from that example?

      -

      Alex: Start with Authenticate. There is something to understand, something to try, and something that proves the try worked.

      -

      Alex: Treat examples as spoken recipes, not decorations. You may hear something like gh auth login. Read the command, understand what it changes, then run it only when the repository state matches the lesson.

      +

      Jamie: Let's pause on From the web editor workflow (editing a file on GitHub). What should a learner take away from it?

      +

      Alex: Start with From the web editor workflow (editing a file on GitHub). There is something to understand, something to try, and something that proves the try worked.

      +

      Alex: First, you edited a file → GitHub showed a "Propose changes" form. Then, you named your branch and activated "Propose changes". After that, GitHub redirected you to the "Open a pull request" page. It is like walking a hallway with named doors: read the sign, enter the right room, then confirm where you landed.

      +

      Jamie: Let's pause on From a fork or feature branch. What should a learner take away from it?

      +

      Alex: The reason From a fork or feature branch matters is that screen reader users (NVDA / JAWS - Windows). That gives the learner a simple foothold: screen reader users (VoiceOver - macOS). The interface gets friendlier when it stops being a wall of controls and starts being a set of named places.

      +

      Alex: First, navigate to the repository on GitHub. Then, if you recently pushed, a yellow banner "Compare & pull request" appears at the top - click it. After that, if no banner appears: click the Pull requests tab → click the green New pull request button. Finally, use the branch dropdowns to choose your base branch (what to merge into) and your compare branch (your changes). The rhythm is simple: orient, act, verify, then continue.

      +

      Jamie: Before we leave From a fork or feature branch, what is the practical point?

      +

      Alex: First, click Create pull request. Then, navigate to the repository. After that, a "Compare & pull request" banner may appear (if you recently pushed) - activate it. Finally, oR: Navigate to Pull Requests tab → "New pull request". Think of it as a rail line: each stop confirms you are still on the right route before the next one.

      +

      Jamie: What should they understand before typing anything?

      +

      Alex: Start with Description field: Copilot can write your PR description: If your account has Copilot access, a "Copilot actions" button appears in the description toolbar. The next useful detail is this: 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.

      +

      Alex: Treat examples as spoken recipes, not decorations. You may hear something like Step 1: Tab to the body text area; Step 2: Focus Mode → type using the PR template (if provided). 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 for the dismiss control; Related Issues; Closes 42; Testing; - Tested with NVDA + Chrome on Windows 11; -. Read the command, understand what it changes, then run it only when the repository state matches the lesson.

      -

      Jamie: Let's pause on Common commands. What should a learner take away from it?

      -

      Alex: Here is the plain-English version of Common commands. Screen reader advantage: gh output is plain text with no dynamic regions - more predictable than the browser for certain operations.

      -

      Alex: Treat examples as spoken recipes, not decorations. You may hear something like gh issue list List issues in current repo; gh issue view 42 Read issue 42; gh pr list List pull requests; gh pr view 14 Read PR 14; gh pr create Create a new PR interactively; gh pr merge 14 Merge PR 14; gh repo clone owner/repo Clone a repository; gh repo. Read the command, understand what it changes, then run it only when the repository state matches the lesson.

      -

      Jamie: Let's pause on GitHub Copilot CLI (gh copilot). What should a learner take away from it?

      -

      Alex: This is where GitHub Copilot CLI (gh copilot) becomes real: an extension that adds Copilot to the terminal.

      -

      Jamie: Let's pause on Install. What should a learner take away from it?

      -

      Alex: Start with Install. There is something to understand, something to try, and something that proves the try worked.

      -

      Alex: Treat examples as spoken recipes, not decorations. You may hear something like gh extension install github/gh-copilot. Read the command, understand what it changes, then run it only when the repository state matches the lesson.

      +

      Jamie: Let's pause on Setting a Draft PR. What should a learner take away from it?

      +

      Alex: Here is the plain-English version of Setting a Draft PR. If your work is not finished, open as a Draft.

      +

      Alex: First, after filling in the form, find the dropdown arrow next to "Create pull request". Then, select "Create draft pull request". After that, this signals to reviewers that it is not ready for formal review yet. Treat it like a recipe: do not add the next ingredient until the previous one is actually in the bowl.

      +

      Jamie: Let's pause on Draft Pull Requests - Full Lifecycle. What should a learner take away from it?

      +

      Alex: This is where Draft Pull Requests - Full Lifecycle becomes real: a draft pull request is a PR explicitly marked as a work in progress. That matters in practice: It is visible to the team, can receive comments, and runs CI - but is blocked from being merged until you mark it ready.

      +

      Alex: Keep the teaching thread moving. Start with When to use a draft. There is something to understand, something to try, and something that proves the try worked.

      +

      Alex: The practical takeaway is this. You want to show your approach and get early feedback before finishing. You need CI to run but don't want accidental merges. You are working across multiple days and want your progress visible. You want to pair with a collaborator on the work.

      -

      Jamie: Let's pause on Commands. What should a learner take away from it?

      -

      Alex: The reason Commands matters is that use case: When you know what you want to do but are unsure of the exact git command syntax.

      -

      Alex: Treat examples as spoken recipes, not decorations. You may hear something like Ask Copilot to explain a command; gh copilot explain "git rebase -i HEAD 3"; Ask Copilot to suggest a command; gh copilot suggest "undo my last commit but keep the changes"; Ask Copilot to write a shell script; gh copilot suggest "create a script that finds. Read the command, understand what it changes, then run it only when the repository state matches the lesson.

      -

      Jamie: Let's pause on Example session. What should a learner take away from it?

      -

      Alex: Start with Example session. There is something to understand, something to try, and something that proves the try worked.

      -

      Alex: Treat examples as spoken recipes, not decorations. You may hear something like $ gh copilot suggest "show me all commits from last week"; Suggestion: git log --since="1 week ago" --oneline; Run this command? (Y/n). Read the command, understand what it changes, then run it only when the repository state matches the lesson.

      -

      Jamie: Let's pause on Learning Cards: GitHub Desktop, GitHub CLI, and Copilot CLI. What should a learner take away from it?

      -

      Alex: Start with Learning Cards: GitHub Desktop, GitHub CLI, and Copilot CLI. There is something to understand, something to try, and something that proves the try worked.

      -

      Alex: The practical takeaway is this. GitHub Desktop is a native application -- on Windows it uses UI Automation, not a browser DOM; your screen reader's object navigation (NVDA: Insert+Numpad) rather than browse mode is the correct approach for navigating its interface. GitHub CLI (gh) is entirely terminal-based; all output is plain text that your screen reader reads line by line -- pipe verbose output through head -20 or Select-Object -First 20 to avoid overwhelming your speech buffer. Copilot CLI (gh copilot suggest and gh copilot explain) presents interactive prompts in the terminal; listen for the "Run this command? (Y/n)" confirmation before pressing Enter to avoid executing unreviewed commands. GitHub Desktop inherits your Windows display scaling -- if text appears small, increase system-level scaling (Settings Display Scale) rather than looking for an in-app zoom option. Terminal output from gh and gh copilot uses your terminal's font and color settings; configure your terminal profile (Windows Terminal settings or iTerm2 preferences) with a high-contrast color scheme and large font for comfortable reading. Copilot CLI suggestions appear as plain text in the terminal, not in a styled panel -- they are easy to miss among other output; look for the indented suggestion block immediately after your prompt.

      +

      Jamie: Let's pause on What a draft PR does differently. What should a learner take away from it?

      +

      Alex: Start with What a draft PR does differently. There is something to understand, something to try, and something that proves the try worked.

      +

      Alex: The practical takeaway is this. The merge button is disabled - even an authorized maintainer cannot merge a draft. The PR header shows a grey "Draft" badge instead of the green "Open" badge. Reviewers are not auto-notified (no review requests are sent until ready). CI workflows still run normally.

      +

      Jamie: Let's pause on Mark a draft ready for review. What should a learner take away from it?

      +

      Alex: Start with Mark a draft ready for review. There is something to understand, something to try, and something that proves the try worked.

      +

      Alex: First, open the PR. Then, navigate to the "Reviewers" sidebar or scroll to bottom of the Conversation tab. After that, find and activate the "Ready for review" button. Finally, the draft badge changes to "Open" and reviewers are notified. Think of it as a rail line: each stop confirms you are still on the right route before the next one.

      +

      Jamie: Let's pause on Convert an open PR to draft (after opening). What should a learner take away from it?

      +

      Alex: Here is the plain-English version of Convert an open PR to draft (after opening). GitHub CLI (gh) alternative - draft PR lifecycle. Put another way, manage draft PRs from your terminal.

      +

      Alex: First, in the right sidebar, find the "Reviewers" section. Then, look for the "Convert to draft" link (below the review status). After that, confirm in the dialog - this removes merge eligibility until you mark it ready again. Treat it like a recipe: do not add the next ingredient until the previous one is actually in the bowl.

      +

      Alex: Treat examples as spoken recipes, not decorations. You may hear something like Create a draft PR; gh pr create --draft --title "WIP: Add carousel keyboard nav"; Mark a draft ready for review; gh pr ready 42; Check PR status (shows draft state); gh pr view 42; List only draft PRs; gh pr list --draft. Read the command, understand what it changes, then run it only when the repository state matches the lesson.

      -

      Alex: Keep the teaching thread moving. This is where "Agent not found" becomes real: issue: Typing @agent-name shows "No agent found.". The workshop is closer to rehearsal than lecture. You hear the move, try the move, and then check what changed.

      -

      Jamie: Let's pause on Solutions. What should a learner take away from it?

      -

      Alex: Start with Solutions. There is something to understand, something to try, and something that proves the try worked.

      -

      Alex: First, verify.github/agents/[name].agent.md exists in your workspace. Then, reload VS Code window: Ctrl+Shift+P → "Reload Window". After that, check file naming: must end with.agent.md. Finally, verify YAML frontmatter is valid (no syntax errors). It is like walking a hallway with named doors: read the sign, enter the right room, then confirm where you landed.

      -

      Alex: Keep the teaching thread moving. The reason Agent produces incorrect output matters is that issue: Agent's response is wrong or misses context.

      +

      Alex: Keep the teaching thread moving. Start with Learning Cards: Opening a Pull Request. There is something to understand, something to try, and something that proves the try worked.

      +

      Alex: The practical takeaway is this. After editing a file on GitHub, the "Propose changes" form has a branch name field and a commit message field; press Tab to move between them. On the "Open a pull request" page, press F to jump to the Title field; Tab moves to the Description text area. Press Ctrl+Enter from inside the description text area to submit the PR without finding the Create button. The "Compare & pull request" yellow banner appears at the top of the repo after a recent push; at high zoom it may span the full width of the page. The branch comparison dropdowns (base and compare) use small text; zoom in on the area above the diff preview to read them. Draft PR: look for the dropdown arrow next to the green "Create pull request" button to switch to "Create draft pull request".

      +

      Jamie: Let's pause on Requesting reviewers. What should a learner take away from it?

      +

      Alex: Keep the learner anchored in Requesting reviewers. From the sidebar Reviewers section. This is the part to say slowly: Why some reviews are requested automatically: A file called CODEOWNERS in many repositories maps file paths to specific people or teams.

      +

      Alex: First, navigate to "Reviewers" heading (3 or H). Then, activate the gear button. After that, type a username in the search field. Finally, select from the dropdown. It is like walking a hallway with named doors: read the sign, enter the right room, then confirm where you landed.

      +

      Jamie: Before we leave Requesting reviewers, what is the practical point?

      +

      Alex: First, escape to save. The rhythm is simple: orient, act, verify, then continue.

      +

      Alex: Keep the teaching thread moving. The reason Submitting a Review matters is that when you are asked to review a PR, you have three options.

      +

      Alex: The practical takeaway is this. Comment - leave feedback without a verdict; does not block merging. Approve - signal you are satisfied; often required before merge. Request changes - indicate changes must be addressed; blocks merge until resolved.

      -

      Jamie: Before we leave Solutions, what is the practical point?

      -

      Alex: First, provide more context in your prompt: Be specific about what you need. Then, use @ mentions: Reference specific files or selections (@filename.md, selection). After that, check the agent's prerequisites: Did you do the manual work first? Finally, review the agent's instructions: Open.github/agents/[name].agent.md and read what it's supposed to do. Think of it as a rail line: each stop confirms you are still on the right route before the next one.

      -

      Alex: Keep the teaching thread moving. Here is the plain-English version of Slash command doesn't work. Issue: /command shows "Command not found.". It is like learning a transit route. The names of the stops matter because they tell you whether you are still going the right direction.

      -

      Jamie: What is the teaching move inside Solutions?

      -

      Alex: This is where Solutions becomes real: next: Chapter 20: Build Your Agent Back: Chapter 18: Fork and Contribute Related appendices: Appendix L: Agents Reference Appendix K: Copilot Reference.

      -

      Alex: First, verify.github/prompts/[name].md exists. Then, reload window: Ctrl+Shift+P → "Reload Window". After that, check file naming: must be a.md file in.github/prompts/. Finally, try typing the full command name (autocomplete may be incomplete). It is a checklist, but a meaningful one: every item creates evidence that the next step is safe.

      +

      Jamie: What does someone need before they touch the keyboard?

      +

      Alex: Start with Starting a review: On the Files Changed tab, when you add inline comments, choose "Start a review" instead of "Add single comment." This batches all your comments into one review submission.

      +

      Jamie: Let's pause on Completing and submitting a review. What should a learner take away from it?

      +

      Alex: Here is the plain-English version of Completing and submitting a review. After adding your inline comments via "Start a review," you must submit the review to notify the PR author. Put another way, the review is pending until you submit it. It is like learning a transit route. The names of the stops matter because they tell you whether you are still going the right direction.

      +

      Alex: The practical takeaway is this. The button may scroll off-screen to the right. Use horizontal scrolling or press Tab from the page top to cycle through focusable elements until you reach it. When clicked, a popover appears with a summary text area and three radio buttons ( Comment, Approve, Request changes ). At 200%+ zoom, the popover may extend below the visible viewport. Scroll down within the popover to see the Submit review button. The radio buttons are standard HTML radio buttons. In Windows High Contrast mode, the selected radio button uses the system highlight color. Keyboard shortcut: If the button is hard to find visually, press Ctrl+Shift+Enter from within any review comment text area to open the submit review dialog directly.

      +

      Alex: First, look for the Finish your review button in the top-right area of the Files Changed tab (it shows the number of pending comments). Then, click it - a popover appears with a summary text area and three radio buttons: Comment, Approve, Request changes. After that, optionally type a summary comment. Finally, select your verdict by clicking the radio button. Treat it like a recipe: do not add the next ingredient until the previous one is actually in the bowl.

      +

      Jamie: Before we leave Completing and submitting a review, what is the practical point?

      +

      Alex: First, click Submit review. Then, press 1 to go to the h1 (PR title). After that, press B (or Tab) to navigate to the "Submit review" button and activate it (Enter/Space). Finally, a "Submit review" dialog/panel appears. It is a checklist, but a meaningful one: every item creates evidence that the next step is safe.

      +

      Alex: Treat examples as spoken recipes, not decorations. You may hear something like View the PR diff in your terminal; gh pr diff 42; Approve a PR; gh pr review 42 --approve; Approve with a comment; gh pr review 42 --approve --body "Looks good - heading hierarchy is correct."; Request changes; gh pr review 42 --request-changes --body "The alt. Read the command, understand what it changes, then run it only when the repository state matches the lesson.

      +

      Jamie: Let's pause on GitHub shortcuts for pull requests. What should a learner take away from it?

      +

      Alex: This is where GitHub shortcuts for pull requests becomes real: these are the GitHub built-in shortcuts for PR pages. That matters in practice: Enable Focus Mode first (NVDA: NVDA+Space, JAWS: Insert+Z) before using single-key shortcuts.

      -

      Jamie: What should people carry with them after this?

      -

      Alex: Carry the map. Know what page or tool you are in, know which action you are taking, and know what confirmation should follow. If the confirmation is missing, pause. That pause is not wasted time; it is professional judgment.

      -

      Jamie: That is a better way to say it than just follow the steps.

      -

      Alex: Right. Steps matter, but understanding wins. That is episode 17. Next in the series is episode 18, where we keep building the same contributor muscles.

      +

      Alex: Keep the teaching thread moving. Keep the learner anchored in On the PR list page. Shortcut note: For G P, press G, release it, then press P (two sequential key presses, not simultaneous).

      +

      Jamie: Let's pause on On the Files Changed tab. What should a learner take away from it?

      +

      Alex: The reason On the Files Changed tab matters is that for the full shortcut system, see Screen Reader Cheat Sheet - GitHub Shortcuts section.

      +

      Alex: Keep the teaching thread moving. Start with Learning Cards: Submitting a Review. There is something to understand, something to try, and something that proves the try worked.

      +

      Alex: The practical takeaway is this. The review verdict controls are inside a popover triggered by the "Finish your review" button; press 1 to return to the h1 (PR title), then B or Tab forward to find the button -- it is easy to miss because it is not a landmark. Inside the popover, Tab past the summary text area to reach a radio group labeled "Review Event"; use Up/Down Arrow to switch between Comment, Approve, and Request Changes. Shortcut: press Ctrl+Shift+Enter from any review comment text area to open the submit review dialog directly, bypassing the search for the button. The "Finish your review" button sits in the top-right corner of the Files Changed tab with a small badge showing your pending comment count; at 200%+ zoom it may scroll off-screen to the right. Inside the submit popover, the three radio buttons (Comment, Approve, Request changes) are small standard HTML radios; zoom in on the popover area or use Tab to step between them. After submitting, your review verdict appears as a colored banner in the Conversation timeline: green for Approve, red for Request Changes, grey for Comment.

      +
      +

      Jamie: Let's pause on Suggested Changes. What should a learner take away from it?

      +

      Alex: Here is the plain-English version of Suggested Changes. A suggested change is a special form of inline review comment where the reviewer proposes exact replacement text. Put another way, the PR author can apply the suggestion directly from GitHub - no copy-paste or separate commit needed.

      +

      Jamie: Let's pause on As a reviewer - inserting a suggestion. What should a learner take away from it?

      +

      Alex: This is where As a reviewer - inserting a suggestion becomes real: the suggestion block is plain Markdown text in the comment editor. That matters in practice: (Three backticks, the word suggestion, Enter, your text, Enter, three backticks.).

      +

      Alex: First, on the Files Changed tab, navigate to the line you want to propose a change. Then, activate the line comment button for that line (the + that appears on hover, or Tab to navigate to it). After that, in the comment text area that opens, press Ctrl+G (Windows) or Cmd+G (Mac). Finally, GitHub wraps a suggestion block around the current line content. It is a checklist, but a meaningful one: every item creates evidence that the next step is safe.

      +

      Jamie: Before we leave As a reviewer - inserting a suggestion, what is the practical point?

      +

      Alex: First, edit the text inside the suggestion block to show your proposed change. Then, add context above the block if helpful: "This makes the alt text more descriptive:". After that, submit as part of your review ("Start a review" → batch with other comments). It is like walking a hallway with named doors: read the sign, enter the right room, then confirm where you landed.

      +

      Jamie: Let's pause on As an author - applying a suggestion. What should a learner take away from it?

      +

      Alex: Start with As an author - applying a suggestion. There is something to understand, something to try, and something that proves the try worked.

      +

      Alex: First, open the PR Conversation or Files Changed tab. Then, navigate to the inline comment containing a suggestion (it shows a diff-style preview). After that, find and activate the "Apply suggestion" button below the suggestion block. Finally, GitHub creates a commit automatically that applies the change - no file editing required. It is like walking a hallway with named doors: read the sign, enter the right room, then confirm where you landed.

      +

      Jamie: Before we leave As an author - applying a suggestion, what is the practical point?

      +

      Alex: First, the conversation thread is marked as resolved. The rhythm is simple: orient, act, verify, then continue.

      +
      +

      Jamie: Let's pause on Batching multiple suggestions into one commit. What should a learner take away from it?

      +

      Alex: Start with Batching multiple suggestions into one commit. There is something to understand, something to try, and something that proves the try worked.

      +

      Alex: First, for each suggestion you want to apply, activate "Add suggestion to batch" instead of "Apply suggestion". Then, after selecting all suggestions, activate the "Commit suggestions" button that appears at the top. After that, GitHub applies all batched suggestions in a single commit. The rhythm is simple: orient, act, verify, then continue.

      +

      Jamie: Let's pause on When to use suggestions vs. comments. What should a learner take away from it?

      +

      Alex: Start with When to use suggestions vs. comments. There is something to understand, something to try, and something that proves the try worked.

      +

      Alex: The practical takeaway is this. Use a suggestion when you know the exact text that would fix the issue. Use a plain comment when the change requires judgment from the author (e.g., "this alt text isn't descriptive - can you describe what the image shows?"). A summary text area for overall comments. Radio buttons for Comment / Approve / Request changes.

      +

      Alex: First, after adding all your inline comments, navigate to the review summary button. Then, on Files Changed tab: find the "Review changes" button (B to navigate buttons). After that, press Enter to open the review dialog. Finally, a panel opens. Think of it as a rail line: each stop confirms you are still on the right route before the next one.

      +

      Jamie: Before we leave When to use suggestions vs. comments, what is the practical point?

      +

      Alex: First, switch to Focus Mode → type your summary comment. Then, navigate to the radio buttons with arrow keys → select your verdict. After that, tab to "Submit review" button → Enter. Treat it like a recipe: do not add the next ingredient until the previous one is actually in the bowl.

      +

      Alex: Keep the teaching thread moving. Start with Learning Cards: Suggested Changes. There is something to understand, something to try, and something that proves the try worked.

      +

      Alex: The practical takeaway is this. To insert a suggestion block, press Ctrl+G (Windows) or Cmd+G (Mac) in the comment text area; the screen reader announces the inserted fence -- arrow down to edit the text between the backtick lines. Alternatively type the block manually: three backticks, the word suggestion, Enter, your replacement text, Enter, three backticks -- this avoids relying on the keyboard shortcut. As a PR author, navigate to a suggestion comment with 3, then Tab to the "Apply suggestion" button; GitHub commits the change automatically with no file editing required. Suggestion blocks render as a mini inline diff: the original line in red/pink background and your proposed replacement in green background; in high-contrast mode these use system diff colors. The "Apply suggestion" button is small and sits below the suggestion diff preview; zoom into the comment area to find it, or Tab from the suggestion text to reach it. When batching multiple suggestions, a floating "Commit suggestions" bar appears at the top of the page; at high zoom scroll up or press Home to find it.

      +
      +

      Jamie: How do you keep commands from becoming magic words?

      +

      Alex: This is where Understanding Merge Options (for Maintainers) becomes real: when a PR is approved and checks pass, a maintainer can merge it. That matters in practice: The merge button section appears at the bottom of the Conversation tab.

      +

      Alex: Treat examples as spoken recipes, not decorations. You may hear something like Merge with default strategy (merge commit); gh pr merge 42; Squash and merge; gh pr merge 42 --squash; Rebase and merge; gh pr merge 42 --rebase; Delete the branch after merging; gh pr merge 42 --squash --delete-branch; Enable auto-merge (merges when checks. Read the command, understand what it changes, then run it only when the repository state matches the lesson.

      +

      Alex: Keep the teaching thread moving. Keep the learner anchored in After a PR is merged. for screen reader users, - deleting the branch after merge: Navigate to the "Add a comment" section (D), then press Shift+B to navigate backwards to the "Delete branch" button and activate it. This is the part to say slowly: This keeps your repository clean by removing the now-merged feature branch. A good GitHub workflow is like a well-run meeting: everyone knows the topic, the next action, and who has the floor.

      +

      Alex: The practical takeaway is this. The PR status badge changes to "Merged" (purple). The source branch can be deleted - a "Delete branch" button appears. Any linked issues with Closes N in the description are automatically closed.

      +

      Jamie: Let's pause on Auto-Merge - Merging When You Can't Wait Around. What should a learner take away from it?

      +

      Alex: The reason Auto-Merge - Merging When You Can't Wait Around matters is that auto-merge lets you pre-authorize a PR to merge automatically the moment all branch protection requirements are satisfied - required reviews approved, all status checks passing, and the branch up to date.

      +

      Alex: The practical takeaway is this. You've addressed all review comments and are waiting for CI to finish. A maintainer has approved the PR but a required check is still running. You're in a different time zone from the reviewers.

      +
      +

      Alex: Keep the teaching thread moving. Start with What happens next. There is something to understand, something to try, and something that proves the try worked.

      +

      Alex: The practical takeaway is this. The PR merge box changes to show "Auto-merge enabled - merge will happen automatically". When the last required check passes (or last required review arrives), GitHub merges the PR silently. You receive a notification: "Your PR was automatically merged". If a reviewer requests changes after auto-merge is enabled, auto-merge is automatically cancelled (a new approval is required before it re-enables).

      +

      Jamie: Let's pause on Cancelling Auto-Merge. What should a learner take away from it?

      +

      Alex: Here is the plain-English version of Cancelling Auto-Merge. Auto-merge is only available if the repository administrator has enabled it in Settings → General. Put another way, many open source repos have it on; some do not.

      +

      Alex: Treat examples as spoken recipes, not decorations. You may hear something like Merge box → Tab → "Disable auto-merge" button → Enter. Read the command, understand what it changes, then run it only when the repository state matches the lesson.

      +

      Alex: Keep the teaching thread moving. This is where Scenario A: "I want to review an assigned PR" becomes real: example: You are assigned to review a PR titled "Add missing NVDA shortcut to keyboard-shortcuts.md." The PR modifies docs/keyboard-shortcuts.md in the Learning Room repository and references Challenge 2. The workshop is closer to rehearsal than lecture. You hear the move, try the move, and then check what changed.

      +
      +

      Jamie: Let's pause on Scenario B: "I want to respond to review feedback on my PR". What should a learner take away from it?

      +

      Alex: Keep the learner anchored in Scenario B: "I want to respond to review feedback on my PR". Example: Your PR for Challenge 3 (Complete Welcome Guide) received a review comment: "The [TODO] about evaluating issues is good, but the paragraph could mention checking if the issue is already assigned." The validation bot also flagged a link text issue.

      +

      Alex: Keep the teaching thread moving. The reason Writing PR Descriptions That Get Reviewed matters is that see also: Appendix C: Markdown Reference for formatting your PR description with headings, lists, and task lists. That gives the learner a simple foothold: a pull request is only as useful as its description.

      +

      Jamie: Let's pause on What Reviewers Look For. What should a learner take away from it?

      +

      Alex: Start with What Reviewers Look For: When a reviewer opens your PR, they are asking four questions before they ever look at the diff. The next useful detail is this: If your description answers all four, the reviewer can jump straight into the code with context.

      +

      Alex: First, why does this change exist? -- What problem does it solve, or what goal does it advance? Then, what is the scope? -- Which files changed, and roughly how big is the change? After that, how was it tested? -- Did you verify that the change works, and how? Finally, what should I pay attention to? -- Are there tricky parts, trade-offs, or areas where you want a second opinion? Think of it as a rail line: each stop confirms you are still on the right route before the next one.

      +
      +

      Alex: Keep the teaching thread moving. Here is the plain-English version of The Closes XX Pattern. GitHub recognizes special keywords in PR descriptions that automatically close linked issues when the PR merges. Put another way, you do not need to close issues by hand -- just include the right keyword followed by the issue number. It is like learning a transit route. The names of the stops matter because they tell you whether you are still going the right direction.

      +

      Jamie: What is the pre-flight check here?

      +

      Alex: This is where Before/After Structure becomes real: one of the most effective patterns for PR descriptions is showing the state before your change and the state after. That matters in practice: This gives the reviewer an instant mental model of what changed without reading the diff line by line.

      +

      Alex: Keep the teaching thread moving. Keep the learner anchored in A PR Description Template. Here is a template you can copy into your PR descriptions. This is the part to say slowly: Not every section applies to every PR, but filling in even a few sentences per section makes a meaningful difference.

      +
      +

      Jamie: Let's pause on Common Description Mistakes. What should a learner take away from it?

      +

      Alex: The reason Common Description Mistakes matters is that even experienced contributors make these mistakes. That gives the learner a simple foothold: knowing what to avoid is half the battle.

      +

      Alex: Keep the teaching thread moving. Start with Good vs. Bad: Side by Side: No context, no linked issue, no explanation of what file or what was wrong with it. The next useful detail is this: A reviewer seeing this has to open the diff, figure out which file changed, read every line, and guess at the intent. Think of it like entering a new building: first you find the lobby, then the room, then the door you actually need.

      +

      Jamie: Let's pause on Learning Cards: Writing PR Descriptions That Get Reviewed. What should a learner take away from it?

      +

      Alex: Start with Learning Cards: Writing PR Descriptions That Get Reviewed. There is something to understand, something to try, and something that proves the try worked.

      +

      Alex: The practical takeaway is this. Use Markdown headings ( ) in your description (Summary, Changes, Related Issues, Testing) so reviewers can press H to jump between sections. Type Closes followed by the issue number to auto-close the linked issue on merge; GitHub autocompletes when you type. Press Ctrl+Shift+P in the description text area to toggle between Write and Preview modes; Preview renders your Markdown so you can check structure before submitting. Use the Preview tab to verify your Markdown renders correctly; headings, bullet lists, and code blocks are easier to proofread in rendered form. Keep bullet points short (one line each) so the description is scannable at high zoom without excessive horizontal scrolling. When including screenshots, add alt text in the Markdown image syntax: so every reader gets the same information.

      +
      +

      Jamie: Let's pause on Try It: Read a Real Pull Request. What should a learner take away from it?

      +

      Alex: This is where Try It: Read a Real Pull Request becomes real: time: 3 minutes What you need: Browser, signed in to GitHub. That matters in practice: Go to the Learning Room repository's Pull Requests tab and find any open or recently closed PR.

      +

      Alex: First, navigate to Pull Requests (G then P in Focus Mode). Then, open the first PR in the list (press Enter on its title). After that, read the description - press 2 to jump to the first section heading, then arrow down to read. Look for: which file was changed (docs/welcome.md, docs/keyboard-shortcuts.md, or docs/setup-guide.md)? Which challenge was this PR solving? Does the description. Finally, check the conversation - press 3 to jump between comments. Read what the validation bot reported - did the bot find any accessibility issues like broken headings or non-descriptive links? How did the author respond? It is a checklist, but a meaningful one: every item creates evidence that the next step is safe.

      +

      Jamie: Before we leave Try It: Read a Real Pull Request, what is the practical point?

      +

      Alex: First, look at the diff - press D to the "Pull request tabs" landmark, then navigate to "Files changed" and press Enter. Press H to scan the changed file headings. If the PR touched docs/welcome.md, you should see + lines where the [TODO] sections were filled in. If. It is like walking a hallway with named doors: read the sign, enter the right room, then confirm where you landed.

      +
      +

      Jamie: What is the final checkpoint?

      +

      Alex: You should be able to point to the evidence, explain the action, and describe what you would do next if this were a real open source project. If you can teach the move back, you have learned it.

      +

      Jamie: And if they get stuck?

      +

      Alex: Read the latest message, not the loudest worry. Check the issue, the branch, the pull request, the status check, or the bot comment. Then ask for help with those facts in hand. That is how professionals collaborate.

      -

      Appendices

      -

      Episode 18: Glossary of Terms

      -

      Comprehensive glossary: Git, GitHub, open source, and accessibility terminology.

      -

      Based on: Appendix A: Glossary of Terms

      -

      Audio and transcript are being regenerated for this episode.

      +

      20. Episode 7: Merge Conflicts Are Not Scary

      +

      Why conflicts happen, how to read conflict markers, and resolving them confidently.

      +

      Based on: Chapter 7: Merge Conflicts Are Not Scary

      + + +

      Download Episode 7 (MP3)

      -Read Transcript - Episode 18: Glossary of Terms +Read Transcript - Episode 7: Merge Conflicts Are Not Scary

      Transcript

      -

      Alex: This is Git Going with GitHub, episode 18: Glossary of Terms. I am Alex. By the end of this episode, Glossary of Terms should feel less like a wall of GitHub words and more like a set of moves you can trust.

      -

      Jamie: And I am Jamie. I am here for the practical questions: what should I listen for, what can go wrong, and what is the next calm move?

      +

      Alex: Welcome to episode 7 of Git Going with GitHub: Merge Conflicts Are Not Scary. I am Alex, and today we are teaching this topic as a conversation you can carry into the workshop, not as a page you have to memorize.

      +

      Jamie: And I am Jamie. I will keep pulling the lesson back to real learners, real repositories, and the evidence that proves the work happened.

      -

      Alex: Today we are working on this: Comprehensive glossary: Git, GitHub, open source, and accessibility terminology. I want the learner to leave with a mental map, not just a remembered path through buttons.

      -

      Jamie: So the goal is understanding first, then action, then confirmation.

      -

      Alex: Right. We are building a rhythm: orient yourself, take one intentional action, then verify what changed before moving on.

      +

      Alex: The lesson focus is Why conflicts happen, how to read conflict markers, and resolving them confidently. We will treat every step as a teachable decision, because that is what makes the skill portable.

      +

      Jamie: So we should explain the why clearly enough that the steps make sense when the learner meets them later.

      +

      Alex: That is it. If a listener only has audio right now, they should still get the complete concept and know what evidence would prove success.

      Jamie: Okay, set the room for us. What are we walking into?

      -

      Alex: Start with Every Term You Need for Open Source Contribution: This glossary is your reference for the entire two-day workshop. The next useful detail is this: When you hear a term you don't recognize - check here first.

      -

      Alex: The next layer is this. Start with Learning Cards: Navigating the Glossary. There is something to understand, something to try, and something that proves the try worked.

      -

      Alex: The practical anchors are these. Press H to jump between term headings (h3 level) within each category section. Use the Elements List (NVDA+F7 or Insert+F6) to see all terms at once and type a few letters to filter. Jump to "Alphabetical Quick Reference" at the bottom for a flat A-Z lookup table. Each term is a bold h3 heading -- increase zoom and scan headings to browse terms quickly. The alphabetical table at the bottom works well at high zoom since each row is self-contained. Use Ctrl+F in your browser to search for any term by name.

      -

      Jamie: What is the one idea that makes the next few steps less mysterious?

      -

      Alex: This is where Repository (Repo) becomes real: a repository is the container for an entire project. That matters in practice: It holds all the project's files, folders, documentation, and the complete history of every change ever made.

      +

      Alex: Start with Understanding, Preventing, and Resolving Conflicts: Merge conflicts sound intimidating but are a normal, manageable part of collaborative development. The next useful detail is this: This guide explains what conflicts are, how to read conflict markers, and how to resolve them - step by step.

      +

      Alex: A solid pull request habit is to separate three questions: what changed, why it changed, and what still needs review. That keeps the conversation useful instead of noisy.

      +

      Alex: The next layer is this. Here is the plain-English version of Workshop Recommendation (Chapter 7). Chapter 7 uses one controlled practice challenge so students can learn conflict resolution without high-pressure scenarios. It is like learning a transit route. The names of the stops matter because they tell you whether you are still going the right direction.

      +

      Alex: The practical anchors are these. There are 1. Time: under 10 minutes. The evidence is issue-linked PR and completion comment. The pattern is observe, resolve, verify.

      +

      Jamie: What does the learner do first, second, and then after that?

      +

      Alex: This is where Chapter 7 Challenge Set becomes real: use a short-lived feature branch: fix/yourname-issueXX (for example, fix/maria-issue48). That matters in practice: The same pattern you used in Chapter 6.

      +

      Alex: First, resolve conflict markers - identify and clean up conflict markers in a practice file, then open a linked PR. It is a checklist, but a meaningful one: every item creates evidence that the next step is safe.

      -

      Alex: Now bring the learner back to the room. Keep the learner anchored in Organization (Org). An organization is a group account on GitHub that multiple people can belong to. This is the part to say slowly: Open source projects typically live inside an organization rather than under a personal account.

      -

      Jamie: What would you say to someone who is already bracing for this to be too much?

      -

      Alex: The reason Fork matters is that a fork is a personal copy of someone else's repository, living in your own GitHub account. That gives the learner a simple foothold: when you fork a repo, you get all its files and history.

      +

      Jamie: Turn that into a path someone can follow.

      +

      Alex: Keep the learner anchored in Challenge 7.1 Step-by-Step: Resolve Conflict Markers. Identify the three types of conflict markers in a practice file, decide which content to keep, remove the markers, and submit a clean PR. This is the part to say slowly: Sometimes an AI agent will confidently generate code that conflicts with human-written code.

      +

      Alex: For a learner, the useful signals are these. Keep only your version,. Keep only their version,. Combine both versions into one clean paragraph. The <<<<<<< HEAD line (or similar).

      +

      Alex: First, open the practice file specified in your challenge issue. Then, search the file for <<<<<<<. This is the start marker - it shows where the conflict begins. After that, read the content between <<<<<<< and =======. This is your version (the current branch). Finally, read the content between ======= and. This is their version (the incoming branch). It is like walking a hallway with named doors: read the sign, enter the right room, then confirm where you landed.

      +

      Jamie: What is the ordered workflow?

      +

      Alex: First, decide which content to keep. Then, delete all three marker lines. After that, review the file to confirm no marker lines remain. Search for <<<<<<< again - there should be zero results. Finally, commit your changes on a branch named fix/yourname-issueXX. The rhythm is simple: orient, act, verify, then continue.

      +

      Jamie: What makes this practice feel low-stakes but still real?

      +

      Alex: The reason Completing Chapter 7: Submit Your Evidence matters is that when your PR is open and passing checks, post a comment on your assigned Chapter 7 challenge issue.

      Alex: The useful habit is simple: orient first, act second, verify third. That pause before acting is part of the work.

      -

      Alex: That matters because of the next idea. Start with Remote: A remote is a connection to a repository hosted elsewhere (usually on GitHub). The next useful detail is this: Your local Git repository can have multiple remotes. Think of it like entering a new building: first you find the lobby, then the room, then the door you actually need.

      -

      Alex: On the ground, that means a few things. origin - your fork on GitHub. upstream - the original repository you forked from.

      +

      Alex: That matters because of the next idea. Start with Expected Outcomes. There is something to understand, something to try, and something that proves the try worked.

      +

      Alex: On the ground, that means a few things. Student can identify the three conflict marker lines ( ) immediately. Student can read both sides of a conflict and make an intentional content decision. Student can remove all markers and submit a clean, issue-linked PR.

      +
      +

      Jamie: How would you walk the room through that step by step?

      +

      Alex: Start with If You Get Stuck. There is something to understand, something to try, and something that proves the try worked.

      +

      Alex: First, can't find the markers? Use Ctrl+F and search for <<<<<<< - they are always in sets of three. Then, not sure which side to keep? Read both versions aloud. Pick the one that is clearer, or combine them. After that, accidentally deleted too much? Undo with Ctrl+Z and start the section over. Finally, pR bot says content is wrong? Double-check that zero marker lines remain - search for. Treat it like a recipe: do not add the next ingredient until the previous one is actually in the bowl.

      +

      Jamie: Give me the sequence, because order matters here.

      +

      Alex: First, ask facilitator to sanity-check your final content before opening the PR. Then, finished but not sure you did it right? Compare your work against the Challenge 7 reference solution. It is a checklist, but a meaningful one: every item creates evidence that the next step is safe.

      +

      Alex: This is where the talk moves from concept to action. This is where Learning Moment becomes real: they are a normal collaboration checkpoint and a chance to make an intentional content decision. That matters in practice: In real open source projects, conflicts happen whenever two people edit near the same lines.

      +

      Jamie: Let's pause on Learning Pattern Used in This Chapter. What should a learner take away from it?

      +

      Alex: Start with Learning Pattern Used in This Chapter. There is something to understand, something to try, and something that proves the try worked.

      +

      Alex: First, start with a controlled, safe conflict (practice file with known markers). Then, learn to read the conflict structure (your version vs. their version). After that, make a deliberate content decision (not just deleting randomly). Finally, submit clean evidence through the PR workflow. It is like walking a hallway with named doors: read the sign, enter the right room, then confirm where you landed.

      +

      Jamie: Before we leave Learning Pattern Used in This Chapter, what is the practical point?

      +

      Alex: First, build confidence for real conflicts in future contributions. The rhythm is simple: orient, act, verify, then continue.

      +

      Alex: Before the learner moves on. The reason About Learning Cards in This Chapter matters is that this chapter provides learning cards: expandable blocks that offer perspective-specific guidance for different ways of working. That gives the learner a simple foothold: not every card appears at every step. The interface gets friendlier when it stops being a wall of controls and starts being a set of named places.

      Jamie: What is the safe way to learn from that example?

      -

      Alex: Start with To see your remotes. There is something to understand, something to try, and something that proves the try worked.

      -

      Alex: Treat examples as spoken recipes, not decorations. You may hear something like git remote -v. Read the command, understand what it changes, then run it only when the repository state matches the lesson.

      +

      Alex: Start with Local Git Alternative: Resolving Conflicts from Your Terminal: If you cloned the learning-room in Block 0 and prefer resolving conflicts locally. The next useful detail is this: The GitHub web conflict editor works well and is the primary method taught in this chapter.

      +

      Alex: A few details make that real. Keep the version you want (or combine both). Delete all three marker lines ( ). Save the file.

      +

      Alex: Treat examples as spoken recipes, not decorations. You may hear something like cd /Documents/learning-room; git checkout main; git pull origin main; git checkout your-branch-name; git merge main. code docs/welcome.md or your preferred editor. Read the command, understand what it changes, then run it only when the repository state matches the lesson.

      +

      Alex: A solid Git habit is to know which branch you are on, what changed, and what confirmation you expect before you run the next command.

      +

      Alex: Hold that next to this. Here is the plain-English version of What Is a Merge Conflict? A merge conflict occurs when two people have both changed the same part of the same file in different ways, and Git cannot automatically decide which version is correct. Put another way, Git can merge changes automatically when they touch different parts of a file.

      +

      Alex: That shows up in the workshop in a few specific ways. Person A changed line 12 to say "Submit form". Person B changed line 12 to say "Send message". Git asks: which one do you want to keep?

      +
      +

      Jamie: If I am listening before the workshop starts, what should settle in my mind first?

      +

      Alex: This is where How to Prevent Conflicts (Prevention is Easier Than Resolution) becomes real: avoiding conflicts in the first place saves time and reduces stress. That matters in practice: Here are the most effective strategies.

      +

      Alex: That connects to another useful point. Keep the learner anchored in 1. Keep your branches short-lived. A branch that lives for 3 days has far fewer conflicts than one that lives for 3 weeks. A good GitHub workflow is like a well-run meeting: everyone knows the topic, the next action, and who has the floor.

      +

      Alex: The parts worth keeping in working memory are these. Target: 1-3 days from branch to merge. If a feature takes longer, break it into smaller PRs.

      Jamie: What should happen before anyone copies and runs it?

      -

      Alex: Start with To add a remote. There is something to understand, something to try, and something that proves the try worked.

      -

      Alex: Treat examples as spoken recipes, not decorations. You may hear something like git remote add upstream https://github.com/original-owner/repo.git. Read the command, understand what it changes, then run it only when the repository state matches the lesson.

      +

      Alex: The reason 2. Sync with main frequently matters is that the longer your branch diverges from main, the more likely conflicts become. That gives the learner a simple foothold: best practice: Sync daily if main is active.

      +

      Alex: Treat examples as spoken recipes, not decorations. You may hear something like From your feature branch; git fetch origin; git merge origin/main; Or: git rebase origin/main (if comfortable with rebasing). Read the command, understand what it changes, then run it only when the repository state matches the lesson.

      +
      +

      Alex: Here is the practical turn. Start with 3. Communicate with your team: Let others know what files you're working on. The next useful detail is this: "Heads up: I'm working on the [TODO] sections in docs/welcome.md for Challenge 3.

      +

      Jamie: What would you say to someone who is already bracing for this to be too much?

      +

      Alex: Here is the plain-English version of 4. Avoid mass reformatting. Running a formatter on an entire file creates conflicts with anyone else editing that file.

      +

      Alex: Here is what that changes in practice. Do it in a separate PR before functional changes. Announce it to the team. Merge it quickly so everyone can sync.

      +

      Jamie: How do you keep commands from becoming magic words?

      +

      Alex: This is where 5. Pull before you push becomes real: always fetch and merge (or pull) before pushing your changes. That matters in practice: This catches conflicts locally where they're easier to resolve. The workshop is closer to rehearsal than lecture. You hear the move, try the move, and then check what changed.

      +

      Alex: Treat examples as spoken recipes, not decorations. You may hear something like git pull origin main Sync your local main; git checkout your-branch; git merge main Merge main into your branch; git push Now push. Read the command, understand what it changes, then run it only when the repository state matches the lesson.

      +
      +

      Jamie: What is the one idea that makes the next few steps less mysterious?

      +

      Alex: Keep the learner anchored in 6. Work on separate files when possible. If multiple people are working simultaneously, divide tasks by files or modules rather than everyone touching the same code.

      +

      Alex: Another way to ground it. The reason 7. Keep PRs small matters is that a 50-file PR will almost certainly conflict with something. That gives the learner a simple foothold: a 5-file PR merges quickly and cleanly.

      Jamie: Where do you want a learner to place their attention here?

      -

      Alex: Keep the learner anchored in Origin. origin is the default name Git gives to the remote repository you cloned from. This is the part to say slowly: When you clone your fork, origin points to your fork on GitHub.

      +

      Alex: Start with 8. Use Draft PRs for early visibility: Open your PR as a draft while still working. The next useful detail is this: Others can see what you're changing and avoid overlapping work.

      -

      Alex: Before the learner moves on. The reason.gitignore matters is that.gitignore is a special file in the root of your repository that tells Git which files or folders to ignore - meaning Git will not track or commit them. The interface gets friendlier when it stops being a wall of controls and starts being a set of named places.

      -

      Jamie: Give me the version that sounds like an instructor, not a manual.

      -

      Alex: Start with Why use.gitignore? There is something to understand, something to try, and something that proves the try worked.

      -

      Alex: A few details make that real. Prevent committing temporary files (.DS Store, Thumbs.db). Ignore build outputs (dist/, build/, node modules/). Keep secrets out of Git (.env files, API keys, credentials). Avoid committing IDE-specific files (.vscode/,.idea/).

      +

      Alex: This is the part worth saying out loud. Start with Learning Cards: How to Prevent Conflicts. There is something to understand, something to try, and something that proves the try worked.

      +

      Alex: The room should hear these as checkpoints. Before starting work, run git pull origin main in VS Code's terminal ( Ctrl+ `) to sync your branch; this prevents conflicts from stale branches. On GitHub, check the PR's merge status section by pressing D toward the bottom of the Conversation tab; "This branch has conflicts" warns you before you waste review time. Use issue comments to announce which files you are editing; press D to the "Add a comment" landmark on the issue and type your coordination message. The "Update branch" button on a PR appears near the merge section at the bottom of the Conversation tab; it has a white-on-green style when available. When multiple students are editing the same file, GitHub shows a yellow conflict banner; zoom in on the merge area to check for it before requesting review. Draft PRs show a grey "Draft" badge in the PR list; opening drafts early gives teammates visibility into which files you are changing.

      Jamie: What should they understand before typing anything?

      -

      Alex: Here is the plain-English version of Example.gitignore.gitignore only ignores untracked files. Put another way, if you already committed a file, you must remove it from Git's tracking first.

      -

      Alex: Treat examples as spoken recipes, not decorations. You may hear something like git rm --cached filename. Read the command, understand what it changes, then run it only when the repository state matches the lesson.

      -
      -

      Jamie: How do you keep commands from becoming magic words?

      -

      Alex: This is where Clone becomes real: cloning copies a repository from GitHub to your local computer so you can work with it in VS Code or your preferred editor. That matters in practice: When you clone, you get all the files and the complete history.

      -

      Alex: Treat examples as spoken recipes, not decorations. You may hear something like git clone https://github.com/your-username/repo-name.git. Read the command, understand what it changes, then run it only when the repository state matches the lesson.

      -

      Alex: That connects to another useful point. Keep the learner anchored in Branch. A branch is a separate line of development inside a repository. This is the part to say slowly: The main branch (often called main or master) holds the stable, released version of the project. A good GitHub workflow is like a well-run meeting: everyone knows the topic, the next action, and who has the floor.

      -

      Alex: A solid Git habit is to know which branch you are on, what changed, and what confirmation you expect before you run the next command.

      -

      Jamie: If I am listening before the workshop starts, what should settle in my mind first?

      -

      Alex: Start with Common branch names. There is something to understand, something to try, and something that proves the try worked.

      -

      Alex: The parts worth keeping in working memory are these. main - the primary, stable branch. develop - integration branch (not all projects have this). feature/my-new-thing - convention for feature branches. fix/broken-button - convention for bug fix branches. docs/update-readme - convention for documentation-only branches.

      +

      Alex: This is where Advanced Prevention: Understanding Fast-Forward Merges becomes real: when your branch is perfectly up to date with main and adds new commits on top, GitHub can do a "fast-forward" merge - main simply moves forward to your latest commit. That matters in practice: How to achieve this: Rebase your branch on main right before merging.

      +

      Alex: Treat examples as spoken recipes, not decorations. You may hear something like git checkout your-branch; git fetch origin; git rebase origin/main; git push --force-with-lease See warning below about force pushing. Read the command, understand what it changes, then run it only when the repository state matches the lesson.

      +

      Alex: Now bring the learner back to the room. Keep the learner anchored in When Conflicts Are Actually Good. Conflicts indicate that multiple people are actively improving the project. This is the part to say slowly: In a healthy, collaborative environment, occasional conflicts are normal and manageable.

      +

      Alex: These are the details that keep the idea from floating away. You're the only contributor (less review, less learning). PRs are moving too slowly (stagnation). People are avoiding working on important files (technical debt).

      -

      Jamie: Let's pause on Commit. What should a learner take away from it?

      -

      Alex: Start with Commit: A commit is a saved snapshot of your changes at a moment in time. The next useful detail is this: Good commit messages are in the imperative mood: "Fix typo in README" not "Fixed typo" or "Fixing typo.".

      -

      Alex: Here is what that changes in practice. A message describing what changed and why. A unique SHA hash (a fingerprint like a1b2c3d). The author and timestamp. The changes (additions and deletions to files).

      -

      Alex: Treat examples as spoken recipes, not decorations. You may hear something like Fix broken link in accessibility guide; The link to the NVDA download page was using an outdated URL.; Updated to the current direct download page.; Fixes 42. Read the command, understand what it changes, then run it only when the repository state matches the lesson.

      -

      Jamie: Let's pause on Diff. What should a learner take away from it?

      -

      Alex: Here is the plain-English version of Diff. A diff (short for difference) shows what changed between two versions of a file. Put another way, lines that were added are shown in green (with a + prefix).

      -

      Alex: A solid pull request habit is to separate three questions: what changed, why it changed, and what still needs review. That keeps the conversation useful instead of noisy.

      -

      Alex: Keep the thread going. This is where Issue becomes real: an issue is a discussion item in a GitHub repository. That matters in practice: Every issue gets a sequential number (like 42) and can have labels, assignees, milestones, and comments. The workshop is closer to rehearsal than lecture. You hear the move, try the move, and then check what changed.

      -

      Alex: The room should hear these as checkpoints. Reporting bugs. Requesting features or improvements. Asking questions. Discussing ideas.

      -

      Alex: A solid issue habit is to read the title, the body, and the timeline before acting. You are listening for the requested action, the missing evidence, and the person who needs a response.

      -
      -

      Jamie: Let's pause on Pull Request (PR). What should a learner take away from it?

      -

      Alex: Keep the learner anchored in Pull Request (PR). A pull request is a proposal to merge changes from one branch into another. This is the part to say slowly: When you have finished working on your fork or feature branch, you open a PR to say "here is my work - please review it and consider merging it.".

      -

      Alex: These are the details that keep the idea from floating away. Which branch you want to merge into which target branch. The diff (all changes you made). A description of what you changed and why. Discussion threads and reviews from others.

      -

      Alex: Another way to ground it. The reason Code Review matters is that code review is the process of one or more collaborators reading and providing feedback on a PR before it is merged. That gives the learner a simple foothold: good code reviews are kind, specific, and constructive.

      -

      Alex: That becomes easier when you listen for these cues. Comment - leave a note on a line (not a formal verdict). Approve - signal that they are happy with the changes. Request Changes - indicate that specific things need to be addressed before merging.

      -

      Jamie: Let's pause on Merge. What should a learner take away from it?

      -

      Alex: Start with Merge: Merging is combining changes from one branch into another. The next useful detail is this: When a PR is approved, a maintainer merges it.

      -
      -

      Alex: This is the part worth saying out loud. Here is the plain-English version of Merge Conflict. A merge conflict happens when two branches have both changed the same part of the same file in different ways. Put another way, Git doesn't know which version to keep, so it pauses and asks you to resolve it manually. It is like learning a transit route. The names of the stops matter because they tell you whether you are still going the right direction.

      -

      Jamie: Let's pause on Upstream. What should a learner take away from it?

      -

      Alex: This is where Upstream becomes real: upstream refers to the original repository that you forked from. That matters in practice: When the upstream project has new changes that you want to bring into your fork, you "sync" your fork with upstream.

      -

      Alex: Here is the practical turn. Keep the learner anchored in Label. Labels are colored tags applied to issues and PRs to categorize them.

      -

      Alex: For a learner, the useful signals are these. bug - something isn't working. enhancement - new feature or request. documentation - documentation-only change. good first issue - good for newcomers (look for this when finding your first contribution!). help wanted - maintainers want community help. accessibility - accessibility-related.

      -

      Alex: A solid project habit is to treat metadata as decision support. Labels, status, assignees, and notifications tell you what kind of attention the work needs.

      -
      -

      Jamie: Let's pause on Milestone. What should a learner take away from it?

      -

      Alex: The reason Milestone matters is that a milestone groups issues and PRs toward a goal or deadline. That gives the learner a simple foothold: for example: "v2.0 Release" or "Hackathon Day 1." Milestones show progress as a percentage of closed versus open items.

      -

      Alex: This is where the talk moves from concept to action. Start with Project (GitHub Projects): A GitHub Project is a flexible board for tracking work. The next useful detail is this: It can show issues and PRs in table view, board view (kanban), or roadmap view. Think of it like entering a new building: first you find the lobby, then the room, then the door you actually need.

      -

      Jamie: Let's pause on Maintainer. What should a learner take away from it?

      -

      Alex: Here is the plain-English version of Maintainer. A maintainer is someone with write or admin access to a repository. Put another way, maintainers review PRs, triage issues, manage releases, and make decisions about the project's direction.

      -
      -

      Alex: Hold that next to this. This is where Contributor becomes real: anyone who contributes to an open source project is a contributor. That matters in practice: Contributing includes code, documentation, design, testing, translation, issue triage, and community support.

      -

      Jamie: Let's pause on Triage. What should a learner take away from it?

      -

      Alex: Keep the learner anchored in Triage. Triaging issues means reviewing new issues to categorize them, add labels, assign them, close duplicates, and communicate with the reporter. This is the part to say slowly: Triage is an important contribution that doesn't require coding skills.

      -

      Alex: Keep the teaching thread moving. The reason Collaborator matters is that a collaborator is someone who has been explicitly granted write access to a repository. That gives the learner a simple foothold: collaborators can commit directly to the repo without forking (though good practice is still to use branches and PRs). The interface gets friendlier when it stops being a wall of controls and starts being a set of named places.

      -
      -

      Jamie: Let's pause on Part 4: Common Abbreviations and Slang. What should a learner take away from it?

      -

      Alex: Start with Common Abbreviations and Slang: These abbreviations appear frequently in GitHub comments, PR descriptions, and commit messages.

      -

      Jamie: Let's pause on HEAD. What should a learner take away from it?

      -

      Alex: Here is the plain-English version of HEAD. HEAD is Git's way of saying "where you are right now." It's a pointer to the current commit on the current branch. Put another way, you'll see HEAD referenced in commands like.

      -

      Alex: That shows up in the workshop in a few specific ways. When you're on main, HEAD points to the latest commit on main. When you switch branches, HEAD moves to that branch. HEAD^ or HEAD 1 means "the commit before HEAD".

      -

      Alex: Treat examples as spoken recipes, not decorations. You may hear something like git reset HEAD 1 Undo the last commit; git diff HEAD Show uncommitted changes. Read the command, understand what it changes, then run it only when the repository state matches the lesson.

      -

      Jamie: Let's pause on Detached HEAD. What should a learner take away from it?

      -

      Alex: This is where Detached HEAD becomes real: a "detached HEAD" occurs when you check out a specific commit instead of a branch. That matters in practice: You're no longer "on" a branch - just looking at a snapshot in time.

      -
      -

      Jamie: Let's pause on Why it happens. What should a learner take away from it?

      -

      Alex: Start with Why it happens. There is something to understand, something to try, and something that proves the try worked.

      -

      Alex: Treat examples as spoken recipes, not decorations. You may hear something like git checkout a1b2c3d Checking out a commit directly. Read the command, understand what it changes, then run it only when the repository state matches the lesson.

      -

      Jamie: Let's pause on What this means. What should a learner take away from it?

      -

      Alex: Start with What this means. There is something to understand, something to try, and something that proves the try worked.

      -

      Alex: The practical takeaway is this. Any commits you make won't belong to any branch. If you switch branches, those commits become "orphaned".

      -

      Jamie: Let's pause on How to fix it. What should a learner take away from it?

      -

      Alex: Start with How to fix it: If you made commits in detached HEAD state and want to keep them. The next useful detail is this: Git will warn you verbosely when entering detached HEAD state.

      -

      Alex: Treat examples as spoken recipes, not decorations. You may hear something like git branch new-branch-name Creates a branch from your current position; git checkout new-branch-name. Read the command, understand what it changes, then run it only when the repository state matches the lesson.

      -
      -

      Jamie: Let's pause on Stash. What should a learner take away from it?

      -

      Alex: Here is the plain-English version of Stash. git stash temporarily saves your uncommitted changes and reverts your working directory to a clean state. Put another way, it's useful when you need to switch branches but aren't ready to commit.

      -

      Jamie: Let's pause on Common workflow. What should a learner take away from it?

      -

      Alex: Start with Common workflow. There is something to understand, something to try, and something that proves the try worked.

      -

      Alex: Treat examples as spoken recipes, not decorations. You may hear something like You're working on branch A; git stash Save your changes temporarily; git checkout main Switch to main; Do something on main.; git checkout branch-a Switch back; git stash pop Restore your changes. Read the command, understand what it changes, then run it only when the repository state matches the lesson.

      -

      Jamie: What stays the same when the tool changes?

      -

      Alex: Keep the learner anchored in Stash commands. Use case: "I need to quickly switch branches to check something, but I'm in the middle of work I'm not ready to commit.".

      -

      Alex: The practical takeaway is this. git stash - save changes. git stash list - see what's stashed. git stash pop - restore and remove from stash. git stash apply - restore but keep in stash. git stash drop - delete a stash.

      -
      -

      Alex: Keep the teaching thread moving. The reason Rebase matters is that rebasing is an alternative to merging. That gives the learner a simple foothold: instead of creating a merge commit, rebase moves (replays) your commits on top of another branch.

      -

      Jamie: Let's pause on When to use rebase. What should a learner take away from it?

      -

      Alex: Start with When to use rebase. There is something to understand, something to try, and something that proves the try worked.

      -

      Alex: The practical takeaway is this. Keep a linear project history. Clean up your branch before submitting a PR. Incorporate upstream changes into your feature branch.

      -

      Alex: Keep the teaching thread moving. Start with When NOT to rebase. There is something to understand, something to try, and something that proves the try worked.

      -

      Alex: The practical takeaway is this. Shared branches (never rebase main or public branches). After pushing to GitHub (unless you're comfortable force pushing).

      -
      -

      Jamie: Let's pause on Basic rebase workflow. What should a learner take away from it?

      -

      Alex: This is where Basic rebase workflow becomes real: rebase conflicts are resolved the same way as merge conflicts (edit file, remove markers, git add, git rebase --continue).

      -

      Alex: Treat examples as spoken recipes, not decorations. You may hear something like git checkout feature-branch; git rebase main; Fix any conflicts; git push --force-with-lease See Force Push below. Read the command, understand what it changes, then run it only when the repository state matches the lesson.

      -

      Jamie: Let's pause on Cherry-Pick. What should a learner take away from it?

      -

      Alex: Keep the learner anchored in Cherry-Pick. Cherry-picking applies a single commit from one branch onto another. This is the part to say slowly: Use case: You made a bug fix on the wrong branch and want to apply it to main without merging the whole branch.

      -

      Alex: Treat examples as spoken recipes, not decorations. You may hear something like git checkout main; git cherry-pick a1b2c3d Apply commit a1b2c3d to main. Read the command, understand what it changes, then run it only when the repository state matches the lesson.

      -

      Jamie: Let's pause on When to use. What should a learner take away from it?

      -

      Alex: The reason When to use matters is that warning: Cherry-picking duplicates commits (creates a new commit with the same changes). That gives the learner a simple foothold: avoid cherry-picking commits that are part of an active feature branch - it causes confusion.

      -

      Alex: The practical takeaway is this. Extract a single fix from a larger feature branch. Backport a bug fix to an older release branch. Undo a commit on one branch but keep it on another.

      -
      -

      Jamie: Let's pause on Fetch vs Pull. What should a learner take away from it?

      -

      Alex: Start with Fetch vs Pull: git fetch downloads changes from a remote repository but doesn't merge them into your current branch. The next useful detail is this: It updates your local copy of remote branches (like origin/main or upstream/main) without touching your working files. Think of it like entering a new building: first you find the lobby, then the room, then the door you actually need.

      -

      Alex: Treat examples as spoken recipes, not decorations. You may hear something like git fetch origin Download updates from origin. git pull origin main Fetch + merge origin/main into current branch. Read the command, understand what it changes, then run it only when the repository state matches the lesson.

      -

      Jamie: Let's pause on When to use fetch. What should a learner take away from it?

      -

      Alex: Start with When to use fetch. There is something to understand, something to try, and something that proves the try worked.

      -

      Alex: The practical takeaway is this. You want to see what changed without committing to merging. You want to review changes before integrating them. You're syncing upstream and want to inspect first.

      -

      Alex: Keep the teaching thread moving. This is where When to use pull becomes real: best practice for collaboration: Use fetch first, review with git log origin/main, then decide to merge or rebase.

      -

      Alex: The practical takeaway is this. You know you want the latest changes merged immediately. You're working alone on a branch.

      -
      -

      Jamie: Let's pause on Force Push. What should a learner take away from it?

      -

      Alex: Keep the learner anchored in Force Push. Force pushing (git push --force or git push -f) overwrites the remote branch with your local version, replacing its history. This is the part to say slowly: This is dangerous because it can delete commits that others have based work on.

      -

      Alex: Keep the teaching thread moving. Start with When force push is okay. There is something to understand, something to try, and something that proves the try worked.

      -

      Alex: The practical takeaway is this. Your own feature branch that no one else is working on. After rebasing to clean up history before merging a PR.

      -

      Jamie: Let's pause on When force push is NEVER okay. What should a learner take away from it?

      -

      Alex: Start with When force push is NEVER okay. There is something to understand, something to try, and something that proves the try worked.

      -

      Alex: The practical takeaway is this. The main branch. Shared branches where others have based work on your commits. Public branches with collaborators.

      +

      Jamie: Let's pause on Tool Cards: Resolve a Merge Conflict. What should a learner take away from it?

      +

      Alex: The reason Tool Cards: Resolve a Merge Conflict matters is that when a PR has a merge conflict, you will see this message on the Conversation tab, near the merge section. That gives the learner a simple foothold: "This branch has conflicts that must be resolved".

      +

      Alex: That becomes easier when you listen for these cues. The banner uses a yellow or orange background. In Windows High Contrast mode, it renders with the system alert color so it remains visible. The Resolve conflicts button is a standard link-style button. If it is hard to target at high zoom, use Tab to reach it after the merge status section and press Enter. If the button does not appear, you may lack write access to the repository. Ask the PR author or a maintainer for help.

      +

      Alex: First, on the PR page, click Resolve conflicts if the button is available. Then, edit the file in the web editor to remove conflict markers. After that, click Mark as resolved, then Commit merge. Finally, open the PR's branch by pressing. on the repository page. The rhythm is simple: orient, act, verify, then continue.

      +

      Jamie: Before we leave Tool Cards: Resolve a Merge Conflict, what is the practical point?

      +

      Alex: First, open the conflicting file -- conflict markers are highlighted in the editor. Then, edit to resolve, commit via Source Control panel. After that, pull the latest changes: git pull origin main. Finally, VS Code highlights conflicts with Accept Current / Accept Incoming / Accept Both buttons. Think of it as a rail line: each stop confirms you are still on the right route before the next one.

      +

      Alex: Treat examples as spoken recipes, not decorations. You may hear something like git merge main; Edit conflicting files to remove; git add resolved-file.md; git commit -m "resolve merge conflict". Read the command, understand what it changes, then run it only when the repository state matches the lesson.

      +

      Alex: Keep the thread going. Start with Conflict Markers - What They Mean: When conflict markers appear in a file, your editor is showing you both versions of the conflicted content so you can choose. Think of it like entering a new building: first you find the lobby, then the room, then the door you actually need.

      +

      Jamie: Give me the version that sounds like an instructor, not a manual.

      +

      Alex: Start with Breakdown. There is something to understand, something to try, and something that proves the try worked.

      +

      Alex: The practical takeaway is this. <<<<<<< HEAD - the start of YOUR version (HEAD = "the branch you are currently on"). ======= - the dividing line between the two versions. branch-name - the end of the INCOMING version (from the branch being merged in).

      -

      Jamie: Let's pause on Safer alternative: --force-with-lease. What should a learner take away from it?

      -

      Alex: Here is the plain-English version of Safer alternative: --force-with-lease. --force-with-lease only force pushes if no one else has pushed to the remote branch since you last fetched. Put another way, if someone pushed changes, the command fails and warns you.

      -

      Alex: Treat examples as spoken recipes, not decorations. You may hear something like git push --force-with-lease origin feature-branch. Read the command, understand what it changes, then run it only when the repository state matches the lesson.

      -

      Jamie: Let's pause on Why force push is needed after rebase. What should a learner take away from it?

      -

      Alex: This is where Why force push is needed after rebase becomes real: when you rebase, Git rewrites commit history. That matters in practice: The remote branch and your local branch now have conflicting histories.

      -

      Alex: Keep the teaching thread moving. Keep the learner anchored in SHA / Hash. Every commit, file, and tree in Git is identified by a SHA hash - a 40-character string of letters and numbers (e.g., a1b2c3d4e5f6.). This is the part to say slowly: the learner will see shortened versions like a1b2c3d in the GitHub UI. A good GitHub workflow is like a well-run meeting: everyone knows the topic, the next action, and who has the floor.

      +

      Jamie: Let's pause on After two students both added a shortcut to the same table row. What should a learner take away from it?

      +

      Alex: Start with After two students both added a shortcut to the same table row. There is something to understand, something to try, and something that proves the try worked.

      +

      Alex: Treat examples as spoken recipes, not decorations. You may hear something like add-nvda-shortcut. Read the command, understand what it changes, then run it only when the repository state matches the lesson.

      +

      Jamie: Let's pause on Resolution options. What should a learner take away from it?

      +

      Alex: Start with Resolution options. There is something to understand, something to try, and something that proves the try worked.

      +

      Alex: First, keep your version: add only Insert+F5. Then, keep their version: add only Insert+F7. After that, keep both rows: add both shortcuts to the table (often the right answer when two students added different valid shortcuts). It is like walking a hallway with named doors: read the sign, enter the right room, then confirm where you landed.

      +

      Alex: Keep the teaching thread moving. Start with Learning Cards: Conflict Markers. There is something to understand, something to try, and something that proves the try worked.

      +

      Alex: The practical takeaway is this. Conflict markers are three lines: branch-name; your screen reader may spell out each character individually. Everything between is the INCOMING version. After resolving, search the file for <<<< using Ctrl+F to verify no markers remain; any leftover markers will break the file. In GitHub's conflict editor, each version is highlighted with a different background color (typically green for yours, blue for incoming); high-contrast themes use bolder system colors. The three marker lines ( ) span the full width of the editor; look for rows that contain only repeated symbols. After resolving, zoom in on the edited area and confirm the marker lines are completely deleted, not just partially removed.

      -

      Jamie: Let's pause on Tag / Release. What should a learner take away from it?

      -

      Alex: The reason Tag / Release matters is that a tag marks a specific commit as significant - usually a version release like v1.0.0. That gives the learner a simple foothold: tags are permanent references (unlike branches, which move with each new commit).

      -

      Alex: Keep the teaching thread moving. Start with Actions / Workflow / CI/CD: GitHub Actions is an automation platform built into GitHub. The next useful detail is this: Workflows are automated scripts (written in YAML) that run in response to events - like a PR being opened or code being pushed.

      -

      Jamie: Let's pause on Status Check. What should a learner take away from it?

      -

      Alex: Here is the plain-English version of Status Check. A status check is the result of an automated test or workflow run on a PR. Put another way, maintainers often require status checks to pass before merging.

      -

      Alex: The practical takeaway is this. Green checkmark - all checks passed. Red X - one or more checks failed. Yellow dot - checks are still running.

      +

      Jamie: Let's pause on Resolving Conflicts on GitHub (Web Editor). What should a learner take away from it?

      +

      Alex: Start with Resolving Conflicts on GitHub (Web Editor): GitHub has a built-in conflict editor that you can use without any local tools.

      +

      Jamie: Let's pause on Step-by-step: GitHub Conflict Editor. What should a learner take away from it?

      +

      Alex: Here is the plain-English version of Step-by-step: GitHub Conflict Editor. Low vision users (zoom, high contrast). Put another way, increase your browser's minimum font size (Settings, Appearance, Font size) for a more comfortable editing experience in the conflict editor.

      +

      Alex: The practical takeaway is this. <<<<<<< HEAD marks the start of your version. ======= is the dividing line. branch-name marks the end of the incoming version.

      +

      Alex: First, click Resolve conflicts on the PR Conversation tab. Then, GitHub opens a full-page text editor showing each conflicted file. After that, the conflict markers are highlighted - everything between is the incoming version. Finally, edit the content directly: delete the lines you don't want, including the three marker lines ( ). Treat it like a recipe: do not add the next ingredient until the previous one is actually in the bowl.

      +

      Jamie: Before we leave Step-by-step: GitHub Conflict Editor, what is the practical point?

      +

      Alex: First, when the file looks correct, click Mark as resolved (top-right of the file). Then, if there are multiple conflicted files, a file list on the left lets you jump between them. After that, after all files are resolved, click Commit merge. Finally, open the conflict editor from the Resolve conflicts button on the PR Conversation tab. It is a checklist, but a meaningful one: every item creates evidence that the next step is safe.

      +

      Jamie: Let's pause on What it looks like in the editor. What should a learner take away from it?

      +

      Alex: This is where What it looks like in the editor becomes real: when the conflict editor opens, your screen reader will announce a text editor. That matters in practice: In Focus Mode, navigate with arrow keys.

      -

      Alex: Keep the teaching thread moving. This is where Webhook becomes real: a webhook is an automated notification that GitHub sends to another service when something happens (a push, a PR opened, etc.). That matters in practice: Webhooks power integrations with tools like Slack, project management systems, and CI services. The workshop is closer to rehearsal than lecture. You hear the move, try the move, and then check what changed.

      -

      Jamie: Let's pause on GitHub Discussions. What should a learner take away from it?

      -

      Alex: Keep the learner anchored in GitHub Discussions. Discussions are a threaded forum built into GitHub, separate from Issues. This is the part to say slowly: They are used for open-ended conversation, Q&A, and community announcements.

      -

      Alex: Keep the teaching thread moving. The reason Profile matters is that your GitHub profile is your public identity. That gives the learner a simple foothold: it shows your name, bio, location, repositories, contribution activity (the green squares), and pinned projects.

      +

      Alex: Keep the teaching thread moving. Start with Learning Cards: Resolving Conflicts on GitHub. There is something to understand, something to try, and something that proves the try worked.

      +

      Alex: The practical takeaway is this. 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. 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.

      +

      Jamie: Where is the promise of the workshop, underneath all the logistics?

      +

      Alex: The reason Resolving Conflicts in VS Code (Day 2) matters is that see also: Appendix E: Advanced Git covers rebase, cherry-pick, and other advanced conflict resolution strategies. That gives the learner a simple foothold: VS Code has excellent merge conflict tooling with full screen reader support.

      +

      Jamie: Let's pause on VS Code merge conflict actions. What should a learner take away from it?

      +

      Alex: Start with VS Code merge conflict actions: When your cursor is on a conflict region, VS Code shows CodeLens action links above the conflict block in the editor. The next useful detail is this: The conflict markers disappear and your chosen content remains.

      +

      Alex: The practical takeaway is this. 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.

      +

      Alex: First, open the conflicted file. Then, press ↓ to navigate to a conflict marker (<<<<<<<). After that, the CodeLens links appear above - press Tab to reach them. Finally, press Enter on your chosen action. Think of it as a rail line: each stop confirms you are still on the right route before the next one.

      +

      Jamie: Before we leave VS Code merge conflict actions, what is the practical point?

      +

      Alex: First, save the file (Ctrl+S). Then, stage the resolved file: Ctrl+Shift+G → find the file → Stage changes. After that, commit the merge. Finally, vO+Down or arrow keys to navigate to a conflict marker (<<<<<<<). Treat it like a recipe: do not add the next ingredient until the previous one is actually in the bowl.

      -

      Jamie: Let's pause on GitHub Copilot. What should a learner take away from it?

      -

      Alex: Start with GitHub Copilot: GitHub Copilot is an AI-powered coding assistant. The next useful detail is this: It suggests code, documentation, and commit messages.

      -

      Alex: Keep the teaching thread moving. Here is the plain-English version of Community Files. Every healthy open source project has these files in the root of the repository. It is like learning a transit route. The names of the stops matter because they tell you whether you are still going the right direction.

      -

      Jamie: Let's pause on Learning Cards: Alphabetical Quick Reference. What should a learner take away from it?

      -

      Alex: Start with Learning Cards: Alphabetical Quick Reference. There is something to understand, something to try, and something that proves the try worked.

      -

      Alex: The practical takeaway is this. Press T to jump to the table, then use Ctrl+Alt+Arrow keys to navigate rows and columns. Each row has two cells: Term and Definition -- column headers are announced on first entry. For longer definitions, the table keeps them concise; see the full entry above for details. This table is designed for quick lookups -- each row fits on a single line at most zoom levels. If the table wraps awkwardly, try reducing zoom slightly or switching to a wider window. Bold term names in the left column create a visible scan line.

      +

      Jamie: Let's pause on Ask for help - it's normal. What should a learner take away from it?

      +

      Alex: Here is the plain-English version of Ask for help - it's normal. If you are unsure which version to keep.

      +

      Alex: First, 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?". Then, tag the PR author or a maintainer with @username. Treat it like a recipe: do not add the next ingredient until the previous one is actually in the bowl.

      +

      Jamie: Let's pause on Abandon and start fresh (nuclear option). What should a learner take away from it?

      +

      Alex: This is where Abandon and start fresh (nuclear option) becomes real: if a conflict is severe (the branch diverged a lot from main). That matters in practice: This is legitimate - not a failure. The workshop is closer to rehearsal than lecture. You hear the move, try the move, and then check what changed.

      +

      Alex: First, close the PR without merging. Then, start a new branch from the latest main. After that, apply only your intended changes to the new branch. Finally, open a new PR. It is a checklist, but a meaningful one: every item creates evidence that the next step is safe.

      +

      Jamie: How should someone ask for help in a way that gets them unstuck faster?

      +

      Alex: Start with Learning Cards: When You Feel Stuck. There is something to understand, something to try, and something that proves the try worked.

      +

      Alex: The practical takeaway is this. 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. 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.

      -

      Alex: Keep the teaching thread moving. Keep the learner anchored in Alphabetical Quick Reference. Next: Appendix B: Screen Reader Cheat Sheet Teaching chapter: Chapter 02: Understanding GitHub.

      +

      Jamie: Let's pause on Reading a Conflict Message from Git (Command Line Reference). What should a learner take away from it?

      +

      Alex: The reason Reading a Conflict Message from Git (Command Line Reference) matters is that if you work locally, git merge or git pull will say. That gives the learner a simple foothold: the conflict markers are inserted into the file by Git - open the file and follow the steps above.

      +

      Alex: Treat examples as spoken recipes, not decorations. You may hear something like 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,. 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. Read the command, understand what it changes, then run it only when the repository state matches the lesson.

      +

      Jamie: Let's pause on Try It: Read a Conflict (Without Fear). What should a learner take away from it?

      +

      Alex: Start with Try It: Read a Conflict (Without Fear): Time: 2 minutes What you need: Any text editor or just read below. The next useful detail is this: The goal is not to resolve it - just to understand what you're hearing.

      +

      Alex: First, what does your branch say? (The text between <<<<<<< HEAD and =======). Then, what does the other branch say? (The text between ======= and ). After that, which version would you keep, and why? Think of it as a rail line: each stop confirms you are still on the right route before the next one.

      Jamie: What should people carry with them after this?

      Alex: Carry the map. Know what page or tool you are in, know which action you are taking, and know what confirmation should follow. If the confirmation is missing, pause. That pause is not wasted time; it is professional judgment.

      Jamie: That is a better way to say it than just follow the steps.

      -

      Alex: Right. Steps matter, but understanding wins. That is episode 18. Next in the series is episode 19, where we keep building the same contributor muscles.

      +

      Alex: Right. Steps matter, but understanding wins. That is episode 7. Next in the series is episode 8, where we keep building the same contributor muscles.

      -

      Episode 19: Screen Reader Cheat Sheet

      -

      NVDA, JAWS, and VoiceOver commands for GitHub and VS Code.

      -

      Based on: Appendix B: Screen Reader Cheat Sheet

      +

      21. Challenge 07: Survive a Merge Conflict

      +

      Reading conflict markers, choosing content, deleting markers, and committing a resolution.

      +

      Practice focus: Day 1 stretch

      Audio and transcript are being regenerated for this episode.

      -Read Transcript - Episode 19: Screen Reader Cheat Sheet +Read Transcript - Challenge 07: Survive a Merge Conflict

      Transcript

      -

      Alex: Welcome to episode 19 of Git Going with GitHub: Screen Reader Cheat Sheet. I am Alex, and today we are teaching this topic as a conversation you can carry into the workshop, not as a page you have to memorize.

      -

      Jamie: And I am Jamie. I will keep pulling the lesson back to real learners, real repositories, and the evidence that proves the work happened.

      +

      Alex: You are listening to Challenge Coach: Survive a Merge Conflict. I am Alex, and this is the calm walkthrough before the hands-on work.

      +

      Jamie: And I am Jamie. I will make sure we teach the skill instead of just reading the checklist aloud.

      -

      Alex: The lesson focus is NVDA, JAWS, and VoiceOver commands for GitHub and VS Code. We will treat every step as a teachable decision, because that is what makes the skill portable.

      -

      Jamie: So we should explain the why clearly enough that the steps make sense when the learner meets them later.

      -

      Alex: That is it. If a listener only has audio right now, they should still get the complete concept and know what evidence would prove success.

      +

      Alex: The focus is Reading conflict markers, choosing content, deleting markers, and committing a resolution. We will explain the concept, the action, the evidence, and the most common recovery path.

      +

      Jamie: So the learner needs the why, the move, and the checkpoint all in the same mental pocket.

      +

      Alex: That is the teaching shape: understand the concept, do the smallest real action, then verify the result before moving on.

      -

      Jamie: Okay, set the room for us. What are we walking into?

      -

      Alex: Start with GitHub Navigation with NVDA, JAWS, and VoiceOver: How to use this sheet: Keep it open in a second window or print it. The next useful detail is this: Commands are organized by task so you can find what you need quickly while you work.

      -

      Alex: A solid navigation habit is to prove where you are before activating controls. Headings, landmarks, and the address bar are not trivia; they are your map.

      -

      Alex: The next layer is this. Start with Learning Cards: Using This Cheat Sheet. There is something to understand, something to try, and something that proves the try worked.

      -

      Alex: The practical anchors are these. Use heading navigation (H key) to jump between task categories -- each section is an h2 heading. Open the Elements List (NVDA+F7 or Insert+F6) and switch to the Headings tab to see all sections at once. Tables list commands in the left column and actions in the right -- use Ctrl+Alt+Arrow keys to navigate. Keep this open in a second browser tab or print it for side-by-side reference while working. Command tables are compact -- increase zoom to 150-200% and the two-column layout stays readable. Key names are in backtick code formatting which gives them a distinct visual border.

      -

      Jamie: What is the one idea that makes the next few steps less mysterious?

      -

      Alex: This is where Screen Reader Mode Basics becomes real: before navigating GitHub, understand the two fundamental modes that all screen readers use on the web.

      +

      Jamie: What makes this practice feel low-stakes but still real?

      +

      Alex: Start with Challenge 7: Survive a Merge Conflict: What you will do: Your facilitator will trigger a merge conflict in your PR. The next useful detail is this: the learner will resolve it by editing the file, removing conflict markers, and keeping the right content.

      +

      Alex: A solid Git habit is to know which branch you are on, what changed, and what confirmation you expect before you run the next command.

      +

      Alex: The next layer is this. Here is the plain-English version of What are conflict markers? When Git cannot automatically merge changes, it inserts markers like this. Put another way, your job: decide what the final version should look like, then delete all three marker lines ( ). It is like learning a transit route. The names of the stops matter because they tell you whether you are still going the right direction.

      +

      Jamie: What does the learner do first, second, and then after that?

      +

      Alex: This is where Instructions becomes real: autograded: The autograder will check that no conflict markers remain in your file and that the file has meaningful content.

      +

      Alex: First, wait for your facilitator to trigger the conflict (they will tell you when). Then, open your PR -- you will see a message about conflicts. After that, select Resolve conflicts (or edit the file directly on your branch). Finally, find the conflict markers in the file. It is a checklist, but a meaningful one: every item creates evidence that the next step is safe.

      +

      Jamie: Turn that into a path someone can follow.

      +

      Alex: First, decide which content to keep (or combine both). Then, delete all conflict marker lines. After that, commit the resolution. It is like walking a hallway with named doors: read the sign, enter the right room, then confirm where you landed.

      -

      Alex: Now bring the learner back to the room. Keep the learner anchored in Browse Mode (also called Virtual Cursor / Reading Mode). This is your primary mode for reading and navigating pages. This is the part to say slowly: The screen reader intercepts keystrokes and uses them as navigation commands - for example, pressing H jumps to the next heading rather than typing the letter H.

      +

      Alex: Now bring the learner back to the room. Keep the learner anchored in Peer simulation check. Compare your resolution with the facilitator's conflict seed or with a real buddy if you have access. This is the part to say slowly: It is OK if two valid resolutions keep different wording.

      Jamie: What would you say to someone who is already bracing for this to be too much?

      -

      Alex: The reason Focus Mode (also called Forms or Application Mode) matters is that this mode is for typing and interacting with form fields, text areas, buttons, and interactive widgets. That gives the learner a simple foothold: your keystrokes go directly to the web page instead of being captured by the screen reader.

      +

      Alex: The reason What conflict markers look like matters is that when Git cannot automatically merge two changes to the same lines, it inserts markers.

      Alex: The useful habit is simple: orient first, act second, verify third. That pause before acting is part of the work.

      -

      Alex: That matters because of the next idea. Start with Quick Navigation Keys (Browse Mode): These single-key shortcuts work in Browse Mode (NVDA and JAWS). The next useful detail is this: VoiceOver users with Quick Nav enabled use the same keys. Think of it like entering a new building: first you find the lobby, then the room, then the door you actually need.

      -
      -

      Jamie: There are a lot of tools in play. How do we keep that from feeling like a contest?

      -

      Alex: Here is the plain-English version of Heading Navigation - Your Most-Used Tool. GitHub structures pages with headings. Put another way, jumping between headings is the fastest way to navigate.

      -

      Alex: This is where the talk moves from concept to action. This is where Landmark Navigation - Jump Between Page Regions becomes real: landmarks are named regions of a page (navigation, main content, sidebar, etc.).

      -

      Jamie: Where do you want a learner to place their attention here?

      -

      Alex: Keep the learner anchored in The Elements List - Your Navigation Superpower. This is one of the most powerful tools for navigating complex pages. This is the part to say slowly: It opens a dialog listing all headings, links, buttons, form fields, or landmarks on the page.

      +

      Alex: That matters because of the next idea. Start with The three sections. There is something to understand, something to try, and something that proves the try worked.

      +

      Alex: On the ground, that means a few things. Between <<<<<<< HEAD and =======: The version on the branch you are merging INTO (usually main). Between ======= and: The version on YOUR branch. The marker lines themselves: Must be deleted -- they are not content.

      +

      Jamie: How would you walk the room through that step by step?

      +

      Alex: Here is the plain-English version of Decision process. The choice depends on which version is better for the project.

      +

      Alex: First, keep yours: Delete the HEAD section and all markers, keep your changes. Then, keep theirs: Delete your section and all markers, keep the HEAD version. After that, combine both: Write new text that incorporates ideas from both versions, delete all markers. Treat it like a recipe: do not add the next ingredient until the previous one is actually in the bowl.

      +

      Alex: A solid pull request habit is to separate three questions: what changed, why it changed, and what still needs review. That keeps the conversation useful instead of noisy.

      Jamie: What is the ordered workflow?

      -

      Alex: Start with How to use it. There is something to understand, something to try, and something that proves the try worked.

      -

      Alex: First, press the keyboard shortcut above. Then, navigate between the tabs (Headings, Links, etc.) with Tab or arrow keys. After that, type to filter the list (e.g., type "new issue" to find the New Issue button). Finally, press Enter to jump to the item on the page. The rhythm is simple: orient, act, verify, then continue.

      -

      Jamie: What should someone listen for when a lesson offers more than one tool path?

      -

      Alex: Start with Per-Screen-Reader Command Reference: A compact reference organized by screen reader. The next useful detail is this: For task-based navigation guides (navigating a PR, leaving a comment, etc.), see the sections below.

      -

      Alex: Hold that next to this. Here is the plain-English version of VoiceOver (macOS). The VO modifier key is Control+Option (abbreviated VO). Put another way, rotor navigation: Open with VO+U, use ←/→ to switch between element types (Headings, Links, Form Controls, Tables, Landmarks), and ↑/↓ to navigate within a type.

      +

      Alex: This is where On github.com becomes real: GitHub offers a conflict editor directly in the browser.

      +

      Alex: First, click "Resolve conflicts" on the PR page. Then, the editor highlights conflicting sections. After that, edit the file to remove markers and keep the content you want. Finally, click "Mark as resolved" then "Commit merge". It is a checklist, but a meaningful one: every item creates evidence that the next step is safe.

      +

      Jamie: What stays the same when the tool changes?

      +

      Alex: Keep the learner anchored in In VS Code. VS Code highlights conflicts and offers clickable options above each conflict.

      +

      Alex: These are the details that keep the idea from floating away. "Accept Current Change" (HEAD version). "Accept Incoming Change" (your version). "Accept Both Changes" (keeps both, you edit after).

      -

      Jamie: If I am listening before the workshop starts, what should settle in my mind first?

      -

      Alex: Start with Learning Cards: Task-Based Navigation. There is something to understand, something to try, and something that proves the try worked.

      -

      Alex: That shows up in the workshop in a few specific ways. The sections below are organized by GitHub page type -- jump to the page you are currently on. Each table shows Goal in the left column and Key Sequence in the right -- read left-to-right per row. Practice one page's commands at a time rather than memorizing everything at once. Each page section has a compact table -- at high zoom, the two-column layout reads naturally. Key sequences are shown in backtick formatting for clear visual distinction from descriptions. Open the matching GitHub page side by side and try each key sequence as you read.

      -

      Alex: That connects to another useful point. Keep the learner anchored in Checking and Enabling Feature Previews. GitHub Feature Previews are opt-in UI improvements. This is the part to say slowly: For screen reader users, two are especially important: New Issues Experience and New Files Changed Experience. A good GitHub workflow is like a well-run meeting: everyone knows the topic, the next action, and who has the floor.

      -

      Alex: A solid pull request habit is to separate three questions: what changed, why it changed, and what still needs review. That keeps the conversation useful instead of noisy.

      +

      Alex: Before the learner moves on. The reason What matters matters is that the learning objective is understanding that conflicts are normal and resolvable. That gives the learner a simple foothold: if you removed all conflict markers and the file makes sense, you completed this challenge. The interface gets friendlier when it stops being a wall of controls and starts being a set of named places.

      Jamie: Give me the version that sounds like an instructor, not a manual.

      -

      Alex: The reason VoiceOver (macOS) matters is that see Pre-Workshop Setup, Step 4 for full details on what each feature enables and why it matters for screen reader users.

      +

      Alex: Start with Understanding, Preventing, and Resolving Conflicts: Merge conflicts sound intimidating but are a normal, manageable part of collaborative development. The next useful detail is this: This guide explains what conflicts are, how to read conflict markers, and how to resolve them - step by step.

      +

      Alex: Hold that next to this. Here is the plain-English version of Workshop Recommendation (Chapter 7). Chapter 7 uses one controlled practice challenge so students can learn conflict resolution without high-pressure scenarios.

      +

      Alex: The practical anchors are these. There are 1. Time: under 10 minutes. The evidence is issue-linked PR and completion comment. The pattern is observe, resolve, verify.

      Jamie: Give me the sequence, because order matters here.

      -

      Alex: Start with Entering text in GitHub (Focus Mode required). There is something to understand, something to try, and something that proves the try worked.

      -

      Alex: On the ground, that means a few things. NVDA: Insert+Space. JAWS: Insert+Z (or it switches automatically). VoiceOver: VO+Shift+Down to interact with the text area. JAWS: Insert+Z. VoiceOver: VO+Shift+Up to stop interacting.

      -

      Alex: First, navigate to the text field using Browse Mode: F or E for edit fields, Tab for any interactive element. Then, switch to Focus Mode. After that, type your content. Finally, return to Browse Mode when done typing. Think of it as a rail line: each stop confirms you are still on the right route before the next one.

      -

      Jamie: Let's pause on Markdown formatting shortcuts in GitHub text areas. What should a learner take away from it?

      -

      Alex: Here is the plain-English version of Markdown formatting shortcuts in GitHub text areas. These work while in Focus Mode inside a GitHub text area.

      -

      Alex: Keep the thread going. This is where Dropdown Menus and Flyouts becomes real: GitHub uses popup flyout menus for labels, assignees, reviewers, and branch selection. The workshop is closer to rehearsal than lecture. You hear the move, try the move, and then check what changed.

      -
      -

      Jamie: What is the safe way to learn from that example?

      -

      Alex: Start with VoiceOver users. There is something to understand, something to try, and something that proves the try worked.

      -

      Alex: Treat examples as spoken recipes, not decorations. You may hear something like Step 1: Navigate to the button with Tab or VO+Right; Step 2: Activate with VO+Space; Step 3: VO+Down to enter the flyout; Step 4: VO+Right/Left to navigate items; Step 5: VO+Space to select, Esc to close. Read the command, understand what it changes, then run it only when the repository state matches the lesson.

      -

      Alex: Another way to ground it. The reason GitHub Built-In Keyboard Shortcuts matters is that GitHub has a dedicated keyboard shortcut system built into every page. That gives the learner a simple foothold: these are completely separate from your screen reader's navigation keys - they are JavaScript-powered shortcuts that trigger GitHub actions directly without using the mouse.

      -

      Jamie: Let's pause on Using GitHub shortcuts alongside a screen reader. What should a learner take away from it?

      -

      Alex: Start with Using GitHub shortcuts alongside a screen reader: The key issue: when your screen reader is in Browse Mode, it intercepts keystrokes before they reach the page. The next useful detail is this: GitHub's shortcut system relies on the page receiving the keystroke directly.

      +

      Alex: This is where Chapter 7 Challenge Set becomes real: use a short-lived feature branch: fix/yourname-issueXX (for example, fix/maria-issue48). That matters in practice: The same pattern you used in Chapter 6.

      +

      Alex: First, resolve conflict markers - identify and clean up conflict markers in a practice file, then open a linked PR. It is a checklist, but a meaningful one: every item creates evidence that the next step is safe.

      +

      Jamie: Let's pause on Challenge 7.1 Step-by-Step: Resolve Conflict Markers. What should a learner take away from it?

      +

      Alex: Keep the learner anchored in Challenge 7.1 Step-by-Step: Resolve Conflict Markers. Identify the three types of conflict markers in a practice file, decide which content to keep, remove the markers, and submit a clean PR. This is the part to say slowly: Sometimes an AI agent will confidently generate code that conflicts with human-written code. A good GitHub workflow is like a well-run meeting: everyone knows the topic, the next action, and who has the floor.

      +

      Alex: For a learner, the useful signals are these. Keep only your version,. Keep only their version,. Combine both versions into one clean paragraph. The <<<<<<< HEAD line (or similar).

      +

      Alex: First, open the practice file specified in your challenge issue. Then, search the file for <<<<<<<. This is the start marker - it shows where the conflict begins. After that, read the content between <<<<<<< and =======. This is your version (the current branch). Finally, read the content between ======= and. This is their version (the incoming branch). It is like walking a hallway with named doors: read the sign, enter the right room, then confirm where you landed.

      +

      Jamie: Before we leave Challenge 7.1 Step-by-Step: Resolve Conflict Markers, what is the practical point?

      +

      Alex: First, decide which content to keep. Then, delete all three marker lines. After that, review the file to confirm no marker lines remain. Search for <<<<<<< again - there should be zero results. Finally, commit your changes on a branch named fix/yourname-issueXX. The rhythm is simple: orient, act, verify, then continue.

      +

      Jamie: What should the learner prove to themselves after each small task?

      +

      Alex: The reason Completing Chapter 7: Submit Your Evidence matters is that when your PR is open and passing checks, post a comment on your assigned Chapter 7 challenge issue.

      +
      +

      Alex: Here is the practical turn. Start with Expected Outcomes. There is something to understand, something to try, and something that proves the try worked.

      +

      Alex: Here is what that changes in practice. Student can identify the three conflict marker lines ( ) immediately. Student can read both sides of a conflict and make an intentional content decision. Student can remove all markers and submit a clean, issue-linked PR.

      +

      Jamie: Let's pause on If You Get Stuck. What should a learner take away from it?

      +

      Alex: Start with If You Get Stuck. There is something to understand, something to try, and something that proves the try worked.

      +

      Alex: First, can't find the markers? Use Ctrl+F and search for <<<<<<< - they are always in sets of three. Then, not sure which side to keep? Read both versions aloud. Pick the one that is clearer, or combine them. After that, accidentally deleted too much? Undo with Ctrl+Z and start the section over. Finally, pR bot says content is wrong? Double-check that zero marker lines remain - search for. Treat it like a recipe: do not add the next ingredient until the previous one is actually in the bowl.

      +

      Jamie: Before we leave If You Get Stuck, what is the practical point?

      +

      Alex: First, ask facilitator to sanity-check your final content before opening the PR. Then, finished but not sure you did it right? Compare your work against the Challenge 7 reference solution. It is a checklist, but a meaningful one: every item creates evidence that the next step is safe.

      +

      Alex: Keep the thread going. This is where Learning Moment becomes real: they are a normal collaboration checkpoint and a chance to make an intentional content decision. That matters in practice: In real open source projects, conflicts happen whenever two people edit near the same lines. The workshop is closer to rehearsal than lecture. You hear the move, try the move, and then check what changed.

      +
      +

      Jamie: Let's pause on Learning Pattern Used in This Chapter. What should a learner take away from it?

      +

      Alex: Start with Learning Pattern Used in This Chapter. There is something to understand, something to try, and something that proves the try worked.

      +

      Alex: First, start with a controlled, safe conflict (practice file with known markers). Then, learn to read the conflict structure (your version vs. their version). After that, make a deliberate content decision (not just deleting randomly). Finally, submit clean evidence through the PR workflow. It is like walking a hallway with named doors: read the sign, enter the right room, then confirm where you landed.

      +

      Jamie: Before we leave Learning Pattern Used in This Chapter, what is the practical point?

      +

      Alex: First, build confidence for real conflicts in future contributions. The rhythm is simple: orient, act, verify, then continue.

      +

      Alex: Another way to ground it. The reason About Learning Cards in This Chapter matters is that this chapter provides learning cards: expandable blocks that offer perspective-specific guidance for different ways of working. That gives the learner a simple foothold: not every card appears at every step.

      +

      Jamie: What should they understand before typing anything?

      +

      Alex: Start with Local Git Alternative: Resolving Conflicts from Your Terminal: If you cloned the learning-room in Block 0 and prefer resolving conflicts locally. The next useful detail is this: The GitHub web conflict editor works well and is the primary method taught in this chapter.

      +

      Alex: A few details make that real. Keep the version you want (or combine both). Delete all three marker lines ( ). Save the file.

      +

      Alex: Treat examples as spoken recipes, not decorations. You may hear something like cd /Documents/learning-room; git checkout main; git pull origin main; git checkout your-branch-name; git merge main. code docs/welcome.md or your preferred editor. Read the command, understand what it changes, then run it only when the repository state matches the lesson.

      +
      +

      Alex: This is the part worth saying out loud. Here is the plain-English version of What Is a Merge Conflict? A merge conflict occurs when two people have both changed the same part of the same file in different ways, and Git cannot automatically decide which version is correct. Put another way, Git can merge changes automatically when they touch different parts of a file. It is like learning a transit route. The names of the stops matter because they tell you whether you are still going the right direction.

      +

      Alex: That shows up in the workshop in a few specific ways. Person A changed line 12 to say "Submit form". Person B changed line 12 to say "Send message". Git asks: which one do you want to keep?

      +

      Jamie: Okay, set the room for us. What are we walking into?

      +

      Alex: This is where How to Prevent Conflicts (Prevention is Easier Than Resolution) becomes real: avoiding conflicts in the first place saves time and reduces stress. That matters in practice: Here are the most effective strategies.

      +

      Alex: That connects to another useful point. Keep the learner anchored in 1. Keep your branches short-lived. A branch that lives for 3 days has far fewer conflicts than one that lives for 3 weeks.

      +

      Alex: The parts worth keeping in working memory are these. Target: 1-3 days from branch to merge. If a feature takes longer, break it into smaller PRs.

      Jamie: How do you keep commands from becoming magic words?

      -

      Alex: Start with Practical sequence for G shortcuts. There is something to understand, something to try, and something that proves the try worked.

      -

      Alex: Treat examples as spoken recipes, not decorations. You may hear something like Step 1: Press NVDA+Space (or Insert+Z in JAWS) - enter Focus Mode; Step 2: Press G, pause half a second; Step 3: Press the second key (I, P, A, etc.); Step 4: Press NVDA+Space to return to Browse Mode on the new page. Read the command, understand what it changes, then run it only when the repository state matches the lesson.

      -

      Jamie: Let's pause on Discover shortcuts on any page - The? Key. What should a learner take away from it?

      -

      Alex: This is where Discover shortcuts on any page - The? Key becomes real: start here every time you're on an unfamiliar GitHub page. That matters in practice: key opens GitHub's built-in keyboard shortcut help dialog.

      -

      Alex: Here is the practical turn. Keep the learner anchored in Reading the shortcut dialog with a screen reader. The dialog is a standard ARIA modal (role="dialog"). This is the part to say slowly: When it opens, browser focus moves inside it automatically.

      -

      Alex: For a learner, the useful signals are these. It is context-aware - the shortcuts shown change based on your current page. It is always current - GitHub automatically updates it when they add new shortcuts. The dialog is divided into sections: Site-wide, Source code browsing, Issues, Pull requests, Notifications, etc. - only sections relevant to the current page appear. You do not need to be in Focus Mode to open it -? works from Browse Mode.

      +

      Alex: The reason 2. Sync with main frequently matters is that the longer your branch diverges from main, the more likely conflicts become. That gives the learner a simple foothold: best practice: Sync daily if main is active.

      +

      Alex: Treat examples as spoken recipes, not decorations. You may hear something like From your feature branch; git fetch origin; git merge origin/main; Or: git rebase origin/main (if comfortable with rebasing). Read the command, understand what it changes, then run it only when the repository state matches the lesson.

      +

      Alex: This is where the talk moves from concept to action. Start with 3. Communicate with your team: Let others know what files you're working on. The next useful detail is this: "Heads up: I'm working on the [TODO] sections in docs/welcome.md for Challenge 3. Think of it like entering a new building: first you find the lobby, then the room, then the door you actually need.

      +

      Jamie: What is the one idea that makes the next few steps less mysterious?

      +

      Alex: Here is the plain-English version of 4. Avoid mass reformatting. Running a formatter on an entire file creates conflicts with anyone else editing that file.

      +

      Alex: The room should hear these as checkpoints. Do it in a separate PR before functional changes. Announce it to the team. Merge it quickly so everyone can sync.

      -

      Jamie: Let's pause on Repository navigation - on any repository page. What should a learner take away from it?

      -

      Alex: The reason Repository navigation - on any repository page matters is that and: These open github.dev, which is VS Code running inside your browser - same keyboard shortcuts, same screen reader mode. That gives the learner a simple foothold: opens a new tab so you keep your current GitHub page.

      -

      Alex: Before the learner moves on. Start with Issue and pull request lists: These shortcuts work on the Issues list page and the Pull Requests list page. Think of it like entering a new building: first you find the lobby, then the room, then the door you actually need.

      -

      Alex: A solid issue habit is to read the title, the body, and the timeline before acting. You are listening for the requested action, the missing evidence, and the person who needs a response.

      -

      Jamie: Let's pause on Issue and pull request detail pages. What should a learner take away from it?

      -

      Alex: Here is the plain-English version of Issue and pull request detail pages. When viewing an open issue or pull request. Put another way, tip for R - quote a specific part of a comment: In Browse Mode, select the text you want to quote by holding Shift and pressing arrow keys.

      +

      Jamie: What should happen before anyone copies and runs it?

      +

      Alex: This is where 5. Pull before you push becomes real: always fetch and merge (or pull) before pushing your changes. That matters in practice: This catches conflicts locally where they're easier to resolve.

      +

      Alex: Treat examples as spoken recipes, not decorations. You may hear something like git pull origin main Sync your local main; git checkout your-branch; git merge main Merge main into your branch; git push Now push. Read the command, understand what it changes, then run it only when the repository state matches the lesson.

      +

      Jamie: If I am listening before the workshop starts, what should settle in my mind first?

      +

      Alex: Keep the learner anchored in 6. Work on separate files when possible. If multiple people are working simultaneously, divide tasks by files or modules rather than everyone touching the same code.

      +

      Alex: Keep the teaching thread moving. The reason 7. Keep PRs small matters is that a 50-file PR will almost certainly conflict with something. That gives the learner a simple foothold: a 5-file PR merges quickly and cleanly. The interface gets friendlier when it stops being a wall of controls and starts being a set of named places.

      -

      Alex: This is the part worth saying out loud. This is where Comments - inside any text area (Focus Mode required) becomes real: these shortcuts work while typing in any GitHub comment or description field. That matters in practice: The most important one: Ctrl+Enter submits a comment from inside the text area - you do not have to Tab to the Submit button and press Enter.

      -

      Jamie: Let's pause on Notifications page. What should a learner take away from it?

      -

      Alex: Keep the learner anchored in Notifications page. On your Notifications page (github.com/notifications).

      -

      Alex: A solid project habit is to treat metadata as decision support. Labels, status, assignees, and notifications tell you what kind of attention the work needs.

      -

      Alex: Keep the teaching thread moving. The reason GitHub Actions matters is that on any Actions page in a repository. The interface gets friendlier when it stops being a wall of controls and starts being a set of named places.

      +

      Jamie: Where do you want a learner to place their attention here?

      +

      Alex: Start with 8. Use Draft PRs for early visibility: Open your PR as a draft while still working. The next useful detail is this: Others can see what you're changing and avoid overlapping work.

      +

      Alex: Keep the teaching thread moving. Start with Learning Cards: How to Prevent Conflicts. There is something to understand, something to try, and something that proves the try worked.

      +

      Alex: That becomes easier when you listen for these cues. Before starting work, run git pull origin main in VS Code's terminal ( Ctrl+ `) to sync your branch; this prevents conflicts from stale branches. On GitHub, check the PR's merge status section by pressing D toward the bottom of the Conversation tab; "This branch has conflicts" warns you before you waste review time. Use issue comments to announce which files you are editing; press D to the "Add a comment" landmark on the issue and type your coordination message. The "Update branch" button on a PR appears near the merge section at the bottom of the Conversation tab; it has a white-on-green style when available. When multiple students are editing the same file, GitHub shows a yellow conflict banner; zoom in on the merge area to check for it before requesting review. Draft PRs show a grey "Draft" badge in the PR list; opening drafts early gives teammates visibility into which files you are changing.

      +

      Jamie: What is the safe way to learn from that example?

      +

      Alex: This is where Advanced Prevention: Understanding Fast-Forward Merges becomes real: when your branch is perfectly up to date with main and adds new commits on top, GitHub can do a "fast-forward" merge - main simply moves forward to your latest commit. That matters in practice: How to achieve this: Rebase your branch on main right before merging.

      +

      Alex: Treat examples as spoken recipes, not decorations. You may hear something like git checkout your-branch; git fetch origin; git rebase origin/main; git push --force-with-lease See warning below about force pushing. Read the command, understand what it changes, then run it only when the repository state matches the lesson.

      -

      Jamie: Let's pause on Projects (board and table view). What should a learner take away from it?

      -

      Alex: Start with Projects (board and table view): Keep the official reference handy: github.com/keyboard-shortcuts - and press? The next useful detail is this: on any GitHub page for the context-specific subset.

      -

      Alex: Keep the teaching thread moving. Start with "The page doesn't match the instructions". There is something to understand, something to try, and something that proves the try worked.

      -

      Alex: The parts worth keeping in working memory are these. Solution: Maximize your browser window. GitHub's layout changes at smaller widths, and landmarks/headings may appear in different positions. Full-screen or maximized window gives the most consistent experience.

      -

      Jamie: Let's pause on "I'm hearing too much or navigating too slowly". What should a learner take away from it?

      -

      Alex: Start with "I'm hearing too much or navigating too slowly". There is something to understand, something to try, and something that proves the try worked.

      -

      Alex: Here is what that changes in practice. Disable hovercards in GitHub Accessibility Settings (see Pre-Workshop Setup). Adjust your screen reader verbosity settings. Use NVDA+F7 / VO+U to get a filtered list rather than tabbing through everything. NVDA reads GitHub too slowly: In NVDA Settings → Browse Mode → increase "Maximum number of characters on one line" to 10000. This prevents NVDA from pausing to wrap long lines.

      +

      Alex: Keep the teaching thread moving. Keep the learner anchored in When Conflicts Are Actually Good. Conflicts indicate that multiple people are actively improving the project. This is the part to say slowly: In a healthy, collaborative environment, occasional conflicts are normal and manageable. A good GitHub workflow is like a well-run meeting: everyone knows the topic, the next action, and who has the floor.

      +

      Alex: The practical takeaway is this. You're the only contributor (less review, less learning). PRs are moving too slowly (stagnation). People are avoiding working on important files (technical debt).

      +

      Jamie: Let's pause on Tool Cards: Resolve a Merge Conflict. What should a learner take away from it?

      +

      Alex: The reason Tool Cards: Resolve a Merge Conflict matters is that when a PR has a merge conflict, you will see this message on the Conversation tab, near the merge section. That gives the learner a simple foothold: "This branch has conflicts that must be resolved".

      +

      Alex: The practical takeaway is this. The banner uses a yellow or orange background. In Windows High Contrast mode, it renders with the system alert color so it remains visible. The Resolve conflicts button is a standard link-style button. If it is hard to target at high zoom, use Tab to reach it after the merge status section and press Enter. If the button does not appear, you may lack write access to the repository. Ask the PR author or a maintainer for help.

      +

      Alex: First, on the PR page, click Resolve conflicts if the button is available. Then, edit the file in the web editor to remove conflict markers. After that, click Mark as resolved, then Commit merge. Finally, open the PR's branch by pressing. on the repository page. The rhythm is simple: orient, act, verify, then continue.

      +

      Jamie: Before we leave Tool Cards: Resolve a Merge Conflict, what is the practical point?

      +

      Alex: First, open the conflicting file -- conflict markers are highlighted in the editor. Then, edit to resolve, commit via Source Control panel. After that, pull the latest changes: git pull origin main. Finally, VS Code highlights conflicts with Accept Current / Accept Incoming / Accept Both buttons. Think of it as a rail line: each stop confirms you are still on the right route before the next one.

      +

      Alex: Treat examples as spoken recipes, not decorations. You may hear something like git merge main; Edit conflicting files to remove; git add resolved-file.md; git commit -m "resolve merge conflict". Read the command, understand what it changes, then run it only when the repository state matches the lesson.

      +

      Alex: Keep the teaching thread moving. Start with Conflict Markers - What They Mean: When conflict markers appear in a file, your editor is showing you both versions of the conflicted content so you can choose.

      -

      Alex: Keep the teaching thread moving. Start with "I pressed H but it's typing the letter H". There is something to understand, something to try, and something that proves the try worked.

      -

      Alex: The room should hear these as checkpoints. You are in Focus Mode - press NVDA+Space (or JAWS+Z) to return to Browse Mode. In Browse Mode, H is a navigation key, not a typing key.

      -

      Jamie: Let's pause on "I can't find the comment box". What should a learner take away from it?

      -

      Alex: Start with "I can't find the comment box". There is something to understand, something to try, and something that proves the try worked.

      -

      Alex: These are the details that keep the idea from floating away. Use D to navigate to the "Add a comment" landmark. Then E or F to jump to the edit field. Switch to Focus Mode before typing.

      -

      Alex: Keep the teaching thread moving. Start with "The diff/code area is hard to navigate". There is something to understand, something to try, and something that proves the try worked.

      -

      Alex: That becomes easier when you listen for these cues. The Files Changed tab requires Focus Mode to navigate the diff table. Use NVDA+Space to enter Focus Mode, then use arrow keys. Use Ctrl+Alt+Arrow keys to move between table cells.

      +

      Jamie: Let's pause on Breakdown. What should a learner take away from it?

      +

      Alex: Start with Breakdown. There is something to understand, something to try, and something that proves the try worked.

      +

      Alex: The practical takeaway is this. <<<<<<< HEAD - the start of YOUR version (HEAD = "the branch you are currently on"). ======= - the dividing line between the two versions. branch-name - the end of the INCOMING version (from the branch being merged in).

      +

      Jamie: Let's pause on After two students both added a shortcut to the same table row. What should a learner take away from it?

      +

      Alex: Start with After two students both added a shortcut to the same table row. There is something to understand, something to try, and something that proves the try worked.

      +

      Alex: Treat examples as spoken recipes, not decorations. You may hear something like add-nvda-shortcut. Read the command, understand what it changes, then run it only when the repository state matches the lesson.

      +

      Jamie: Let's pause on Resolution options. What should a learner take away from it?

      +

      Alex: Start with Resolution options. There is something to understand, something to try, and something that proves the try worked.

      +

      Alex: First, keep your version: add only Insert+F5. Then, keep their version: add only Insert+F7. After that, keep both rows: add both shortcuts to the table (often the right answer when two students added different valid shortcuts). It is like walking a hallway with named doors: read the sign, enter the right room, then confirm where you landed.

      -

      Jamie: Let's pause on Official Screen Reader Resources. What should a learner take away from it?

      -

      Alex: Start with Official Screen Reader Resources. There is something to understand, something to try, and something that proves the try worked.

      -

      Alex: A few details make that real. GitHub Repos Screen Reader Guide. GitHub Issues Screen Reader Guide. GitHub Pull Requests Screen Reader Guide. GitHub Copilot in VS Code Screen Reader Guide. GitHub Accessibility Settings Docs. GitHub Keyboard Shortcuts Reference.

      -

      Alex: Keep the teaching thread moving. This is where Keyboard Shortcuts in Other Appendices becomes real: this cheat sheet covers GitHub web navigation and screen reader commands. That matters in practice: Additional keyboard shortcuts for specific tools are documented in. The workshop is closer to rehearsal than lecture. You hear the move, try the move, and then check what changed.

      -

      Jamie: Let's pause on Screen Reader Compatibility Notes. What should a learner take away from it?

      -

      Alex: Keep the learner anchored in Screen Reader Compatibility Notes. The commands in this cheat sheet have been written for and tested with the following screen readers.

      +

      Alex: Keep the teaching thread moving. Start with Learning Cards: Conflict Markers. There is something to understand, something to try, and something that proves the try worked.

      +

      Alex: The practical takeaway is this. Conflict markers are three lines: branch-name; your screen reader may spell out each character individually. Everything between is the INCOMING version. After resolving, search the file for <<<< using Ctrl+F to verify no markers remain; any leftover markers will break the file. In GitHub's conflict editor, each version is highlighted with a different background color (typically green for yours, blue for incoming); high-contrast themes use bolder system colors. The three marker lines ( ) span the full width of the editor; look for rows that contain only repeated symbols. After resolving, zoom in on the edited area and confirm the marker lines are completely deleted, not just partially removed.

      +

      Jamie: Let's pause on Resolving Conflicts on GitHub (Web Editor). What should a learner take away from it?

      +

      Alex: Start with Resolving Conflicts on GitHub (Web Editor): GitHub has a built-in conflict editor that you can use without any local tools.

      +

      Jamie: Let's pause on Step-by-step: GitHub Conflict Editor. What should a learner take away from it?

      +

      Alex: Here is the plain-English version of Step-by-step: GitHub Conflict Editor. Low vision users (zoom, high contrast). Put another way, increase your browser's minimum font size (Settings, Appearance, Font size) for a more comfortable editing experience in the conflict editor. It is like learning a transit route. The names of the stops matter because they tell you whether you are still going the right direction.

      +

      Alex: The practical takeaway is this. <<<<<<< HEAD marks the start of your version. ======= is the dividing line. branch-name marks the end of the incoming version.

      +

      Alex: First, click Resolve conflicts on the PR Conversation tab. Then, GitHub opens a full-page text editor showing each conflicted file. After that, the conflict markers are highlighted - everything between is the incoming version. Finally, edit the content directly: delete the lines you don't want, including the three marker lines ( ). Treat it like a recipe: do not add the next ingredient until the previous one is actually in the bowl.

      +

      Jamie: Before we leave Step-by-step: GitHub Conflict Editor, what is the practical point?

      +

      Alex: First, when the file looks correct, click Mark as resolved (top-right of the file). Then, if there are multiple conflicted files, a file list on the left lets you jump between them. After that, after all files are resolved, click Commit merge. Finally, open the conflict editor from the Resolve conflicts button on the PR Conversation tab. It is a checklist, but a meaningful one: every item creates evidence that the next step is safe.

      -

      Jamie: How would you walk the room through that step by step?

      -

      Alex: The reason If a command doesn't work as described matters is that next: Appendix C: Markdown Reference Back: Appendix A: Glossary Teaching chapter: Chapter 02: Understanding GitHub.

      -

      Alex: First, check that you are in the correct mode (Browse Mode vs. Focus Mode). Then, verify your screen reader version - older versions may use different key assignments. After that, check GitHub's own shortcut dialog (? key) for the current page's shortcuts. Finally, see Troubleshooting above for common fixes. The rhythm is simple: orient, act, verify, then continue.

      +

      Jamie: Let's pause on What it looks like in the editor. What should a learner take away from it?

      +

      Alex: This is where What it looks like in the editor becomes real: when the conflict editor opens, your screen reader will announce a text editor. That matters in practice: In Focus Mode, navigate with arrow keys.

      +

      Alex: Keep the teaching thread moving. Start with Learning Cards: Resolving Conflicts on GitHub. There is something to understand, something to try, and something that proves the try worked.

      +

      Alex: The practical takeaway is this. 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. 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.

      +

      Jamie: Where is the promise of the workshop, underneath all the logistics?

      +

      Alex: The reason Resolving Conflicts in VS Code (Day 2) matters is that see also: Appendix E: Advanced Git covers rebase, cherry-pick, and other advanced conflict resolution strategies. That gives the learner a simple foothold: VS Code has excellent merge conflict tooling with full screen reader support.

      -

      Jamie: What should people carry with them after this?

      -

      Alex: Carry the map. Know what page or tool you are in, know which action you are taking, and know what confirmation should follow. If the confirmation is missing, pause. That pause is not wasted time; it is professional judgment.

      -

      Jamie: That is a better way to say it than just follow the steps.

      -

      Alex: Right. Steps matter, but understanding wins. That is episode 19. Next in the series is episode 20, where we keep building the same contributor muscles.

      +

      Jamie: Let's pause on VS Code merge conflict actions. What should a learner take away from it?

      +

      Alex: Start with VS Code merge conflict actions: When your cursor is on a conflict region, VS Code shows CodeLens action links above the conflict block in the editor. The next useful detail is this: The conflict markers disappear and your chosen content remains. Think of it like entering a new building: first you find the lobby, then the room, then the door you actually need.

      +

      Alex: The practical takeaway is this. 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.

      +

      Alex: First, open the conflicted file. Then, press ↓ to navigate to a conflict marker (<<<<<<<). After that, the CodeLens links appear above - press Tab to reach them. Finally, press Enter on your chosen action. Think of it as a rail line: each stop confirms you are still on the right route before the next one.

      +

      Jamie: Before we leave VS Code merge conflict actions, what is the practical point?

      +

      Alex: First, save the file (Ctrl+S). Then, stage the resolved file: Ctrl+Shift+G → find the file → Stage changes. After that, commit the merge. Finally, vO+Down or arrow keys to navigate to a conflict marker (<<<<<<<). Treat it like a recipe: do not add the next ingredient until the previous one is actually in the bowl.

      +

      Jamie: Let's pause on Ask for help - it's normal. What should a learner take away from it?

      +

      Alex: Here is the plain-English version of Ask for help - it's normal. If you are unsure which version to keep.

      +

      Alex: First, 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?". Then, tag the PR author or a maintainer with @username. Treat it like a recipe: do not add the next ingredient until the previous one is actually in the bowl.

      +

      Jamie: Let's pause on Abandon and start fresh (nuclear option). What should a learner take away from it?

      +

      Alex: This is where Abandon and start fresh (nuclear option) becomes real: if a conflict is severe (the branch diverged a lot from main). That matters in practice: This is legitimate - not a failure.

      +

      Alex: First, close the PR without merging. Then, start a new branch from the latest main. After that, apply only your intended changes to the new branch. Finally, open a new PR. It is a checklist, but a meaningful one: every item creates evidence that the next step is safe.

      +
      +

      Jamie: What do you want them to do when the plan breaks?

      +

      Alex: Start with Learning Cards: When You Feel Stuck. There is something to understand, something to try, and something that proves the try worked.

      +

      Alex: The practical takeaway is this. 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. 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.

      +

      Jamie: Let's pause on Reading a Conflict Message from Git (Command Line Reference). What should a learner take away from it?

      +

      Alex: The reason Reading a Conflict Message from Git (Command Line Reference) matters is that if you work locally, git merge or git pull will say. That gives the learner a simple foothold: the conflict markers are inserted into the file by Git - open the file and follow the steps above. The interface gets friendlier when it stops being a wall of controls and starts being a set of named places.

      +

      Alex: Treat examples as spoken recipes, not decorations. You may hear something like 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,. 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. Read the command, understand what it changes, then run it only when the repository state matches the lesson.

      +

      Jamie: Let's pause on Try It: Read a Conflict (Without Fear). What should a learner take away from it?

      +

      Alex: Start with Try It: Read a Conflict (Without Fear): Time: 2 minutes What you need: Any text editor or just read below. The next useful detail is this: The goal is not to resolve it - just to understand what you're hearing.

      +

      Alex: First, what does your branch say? (The text between <<<<<<< HEAD and =======). Then, what does the other branch say? (The text between ======= and ). After that, which version would you keep, and why? Think of it as a rail line: each stop confirms you are still on the right route before the next one.

      +
      +

      Jamie: What is the final checkpoint?

      +

      Alex: You should be able to point to the evidence, explain the action, and describe what you would do next if this were a real open source project. If you can teach the move back, you have learned it.

      +

      Jamie: And if they get stuck?

      +

      Alex: Read the latest message, not the loudest worry. Check the issue, the branch, the pull request, the status check, or the bot comment. Then ask for help with those facts in hand. That is how professionals collaborate.

      -

      Episode 20: Accessibility Standards Reference

      -

      WCAG 2.2, ARIA roles, and the PR accessibility checklist.

      -

      Based on: Appendix M: Accessibility Standards Reference

      -

      Audio and transcript are being regenerated for this episode.

      +

      22. Episode 8: Open Source Culture and Etiquette

      +

      Communication norms, code review etiquette, inclusive language, and asking questions.

      +

      Based on: Chapter 8: Open Source Culture and Etiquette

      + + +

      Download Episode 8 (MP3)

      -Read Transcript - Episode 20: Accessibility Standards Reference +Read Transcript - Episode 8: Open Source Culture and Etiquette

      Transcript

      -

      Alex: Welcome to Git Going with GitHub, episode 20: Accessibility Standards Reference. I am Alex. Today we are going to make Accessibility Standards Reference something you can explain, practice, and recover from when the interface surprises you.

      +

      Alex: Welcome to Git Going with GitHub, episode 8: Open Source Culture and Etiquette. I am Alex. Today we are going to make Open Source Culture and Etiquette something you can explain, practice, and recover from when the interface surprises you.

      Jamie: And I am Jamie. I will be the voice of the learner who is willing to ask, what is this for, where am I, and how do I know I did it right?

      -

      Alex: The big idea today: WCAG 2.2, ARIA roles, and the PR accessibility checklist. We will name the concept, explain why it matters, practice the move, and point out the checks that tell you the work is real.

      +

      Alex: The big idea today: Communication norms, code review etiquette, inclusive language, and asking questions. We will name the concept, explain why it matters, practice the move, and point out the checks that tell you the work is real.

      Jamie: So the episode should work even if someone has not read the chapter yet.

      Alex: Exactly. The transcript has to stand on its own. It can point toward practice, but it should teach the concept right here in the conversation.

      Jamie: Okay, set the room for us. What are we walking into?

      -

      Alex: Start with WCAG, ARIA, and What They Mean for Your Contributions: This appendix gives you a working understanding of the accessibility standards that govern the web, GitHub's interface, and the projects you will contribute to. The next useful detail is this: You do not need to memorize these - use this as a lookup when a PR review mentions a specific standard or success criterion.

      -

      Alex: The next layer is this. Here is the plain-English version of 1. WCAG 2.2 - The Four Principles. WCAG (Web Content Accessibility Guidelines) is organized around four principles, often abbreviated POUR. Put another way, every WCAG success criterion belongs to one of these four principles. It is like learning a transit route. The names of the stops matter because they tell you whether you are still going the right direction.

      -

      Alex: A solid pull request habit is to separate three questions: what changed, why it changed, and what still needs review. That keeps the conversation useful instead of noisy.

      -

      Jamie: What is the one idea that makes the next few steps less mysterious?

      -

      Alex: Start with Learning Cards: WCAG Overview. There is something to understand, something to try, and something that proves the try worked.

      -

      Alex: That shows up in the workshop in a few specific ways. WCAG is organized around four principles: Perceivable, Operable, Understandable, Robust (POUR) -- use this mnemonic when reviewing any PR. Most projects target WCAG 2.2 AA -- when a reviewer cites a criterion number like 1.4.3, search the tables in Section 3 of this appendix. The WCAG Quick Reference (Section 10) is a filterable web page -- use your screen reader's find command to jump to any criterion number. The tables in this appendix use pipe-delimited Markdown -- increase your editor font size or use a Markdown preview for cleaner column alignment. WCAG 1.4.3 (contrast) and 1.4.11 (non-text contrast) are the criteria most relevant to your daily experience -- bookmark them. When checking contrast ratios, use the WebAIM Contrast Checker link in Section 10 with your browser zoom set to your preferred level.

      +

      Alex: Start with How to Be an Effective and Respectful Open Source Contributor: Technical skills get your code into a project. The next useful detail is this: Communication skills keep you welcomed in the community.

      +

      Alex: The next layer is this. Here is the plain-English version of Workshop Recommendation (Chapter 8). Chapter 8 is a communication and culture chapter. It is like learning a transit route. The names of the stops matter because they tell you whether you are still going the right direction.

      +

      Alex: The practical anchors are these. There are 1 guided reflection (no bot grading). Automation check: none - communication quality is too subjective for fair automated scoring. The evidence is structured reflection comment on your assigned challenge issue. The pattern is read, reflect, commit to one behavior.

      +

      Jamie: What does the learner do first, second, and then after that?

      +

      Alex: Start with Chapter 8 Challenge Set. There is something to understand, something to try, and something that proves the try worked.

      +

      Alex: First, guided reflection - read the chapter, then post a short reflection comment committing to three specific collaboration behaviors. It is a checklist, but a meaningful one: every item creates evidence that the next step is safe.

      -

      Alex: Now bring the learner back to the room. Keep the learner anchored in 2. Conformance Levels: A, AA, AAA. Most open source projects, and GitHub itself, target WCAG 2.2 AA compliance. This is the part to say slowly: When you file an accessibility bug or review a PR, AA is the standard to reference.

      -

      Jamie: What would you say to someone who is already bracing for this to be too much?

      -

      Alex: The reason 3. Key Success Criteria for Web Contributions matters is that these are the criteria you will most commonly encounter when contributing to web projects or reviewing GitHub interface changes.

      +

      Jamie: Turn that into a path someone can follow.

      +

      Alex: Keep the learner anchored in Challenge 8.1 Step-by-Step: Guided Reflection. Identify three concrete communication behaviors you will practice during the rest of the workshop. This is the part to say slowly: your assigned Chapter 8 challenge issue in your Learning Room repository on GitHub.com.

      +

      Alex: For a learner, the useful signals are these. 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.".

      +

      Alex: First, read through the chapter content below, paying attention to the sections on GitHub Flow, constructive feedback, and asking for help. Then, as you read, think about one situation from Day 1 where communication helped (or could have helped) you. After that, open your assigned Chapter 8 challenge issue (the one titled "Chapter 8.1: Guided Reflection (@yourname)"). Finally, scroll to the comment box at the bottom of the issue. It is like walking a hallway with named doors: read the sign, enter the right room, then confirm where you landed.

      +

      Jamie: What is the ordered workflow?

      +

      Alex: First, post a reflection comment using this format. Then, for each prompt, write one specific, actionable sentence - not a vague goal. After that, activate the Comment button (or press Ctrl+Enter). The rhythm is simple: orient, act, verify, then continue.

      +

      Jamie: What makes this practice feel low-stakes but still real?

      +

      Alex: The reason Completing Chapter 8: Submit Your Evidence matters is that the reflection comment itself is your evidence. That gives the learner a simple foothold: the facilitator reviews your comment for specificity.

      Alex: The useful habit is simple: orient first, act second, verify third. That pause before acting is part of the work.

      -

      Alex: That matters because of the next idea. Start with 4. ARIA - Roles, States, and Properties: WAI-ARIA (Accessible Rich Internet Applications) fills the gap between what HTML natively expresses and what complex interactive widgets require. Think of it like entering a new building: first you find the lobby, then the room, then the door you actually need.

      +

      Alex: That matters because of the next idea. Start with Expected Outcomes. There is something to understand, something to try, and something that proves the try worked.

      +

      Alex: On the ground, that means a few things. 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.

      Jamie: How would you walk the room through that step by step?

      -

      Alex: Start with Important rules. There is something to understand, something to try, and something that proves the try worked.

      -

      Alex: First, don't use ARIA if native HTML suffices. A is already a button - adding role="button" to a is only needed when HTML semantics cannot be used. Then, all interactive ARIA widgets must be keyboard operable. Adding role="button" means you must also handle Enter and Space keypresses in JavaScript. After that, aRIA only affects the accessibility tree. It does not add visual styling or behavior - it only changes what assistive technologies announce. Treat it like a recipe: do not add the next ingredient until the previous one is actually in the bowl.

      -

      Alex: This is where the talk moves from concept to action. This is where 5. ARIA Landmark Roles becomes real: landmarks let screen reader users jump directly to major sections of a page. That matters in practice: GitHub uses these extensively; screen reader users navigate between them with D (NVDA/JAWS) or the Rotor (VoiceOver).

      -

      Alex: A solid navigation habit is to prove where you are before activating controls. Headings, landmarks, and the address bar are not trivia; they are your map.

      -

      Jamie: Where do you want a learner to place their attention here?

      -

      Alex: Keep the learner anchored in Live Region (status announcements). Use aria-live="assertive" only for urgent interruptions (errors). This is the part to say slowly: Use "polite" for non-urgent status updates.

      +

      Alex: Start with If You Get Stuck. There is something to understand, something to try, and something that proves the try worked.

      +

      Alex: First, use one simple sentence per prompt - do not overthink it. Then, focus on one real behavior you can start doing today, not an abstract principle. After that, if writing feels hard, draft bullet points first in a text editor, then paste into the comment. Finally, look at the "Giving Feedback" and "Asking for Help" sections in this chapter for concrete examples. Treat it like a recipe: do not add the next ingredient until the previous one is actually in the bowl.

      +

      Jamie: Give me the sequence, because order matters here.

      +

      Alex: First, ask facilitator for one example response and adapt it to your own words. Then, finished but not sure you did it right? Compare your work against the Challenge 8 reference solution. It is a checklist, but a meaningful one: every item creates evidence that the next step is safe.

      +

      Alex: This is where the talk moves from concept to action. This is where Learning Moment becomes real: technical quality and communication quality work together. That matters in practice: Respectful, clear communication helps good code get merged faster.

      +

      Jamie: Let's pause on Learning Pattern Used in This Chapter. What should a learner take away from it?

      +

      Alex: Start with Learning Pattern Used in This Chapter. There is something to understand, something to try, and something that proves the try worked.

      +

      Alex: First, read and absorb community norms (not just rules, but reasons). Then, reflect on personal experience (what worked, what was hard). After that, commit to specific behaviors in writing (public accountability). Finally, apply those behaviors in upcoming chapters (reviews, comments, PRs). It is like walking a hallway with named doors: read the sign, enter the right room, then confirm where you landed.

      -

      Alex: Before the learner moves on. The reason Expandable Section matters is that when expanded: set aria-expanded="true" and remove the hidden attribute. The interface gets friendlier when it stops being a wall of controls and starts being a set of named places.

      -

      Jamie: Give me the version that sounds like an instructor, not a manual.

      -

      Alex: Start with 7. How Standards Apply to GitHub Contributions: When you contribute to an open source project on GitHub, you will encounter accessibility in several contexts.

      -

      Alex: Hold that next to this. Here is the plain-English version of Filing an Accessibility Bug. Reference the specific WCAG criterion. Put another way, bad: "The button isn't accessible." Good: "The 'Subscribe' button has no visible focus indicator, failing WCAG 2.4.7 Focus Visible (Level AA).

      +

      Alex: Before the learner moves on. The reason GitHub Flow - The Standard Contribution Workflow matters is that before diving into communication norms, it helps to understand the workflow that gives all of those conversations their context. That gives the learner a simple foothold: GitHub Flow is the lightweight branching model recommended for open source contribution. The interface gets friendlier when it stops being a wall of controls and starts being a set of named places.

      +

      Jamie: What would you say to someone who is already bracing for this to be too much?

      +

      Alex: Start with Why This Model Works. There is something to understand, something to try, and something that proves the try worked.

      +

      Alex: A few details make that real. 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.

      +

      Alex: Hold that next to this. Here is the plain-English version of GitHub Flow vs Git Flow. You may encounter "Git Flow" (sometimes written "GitFlow") in older projects or enterprise environments. Put another way, this section explains what Git Flow is, how it differs from GitHub Flow, and why this workshop teaches GitHub Flow.

      +

      Alex: A solid Git habit is to know which branch you are on, what changed, and what confirmation you expect before you run the next command.

      Jamie: If I am listening before the workshop starts, what should settle in my mind first?

      -

      Alex: This is where Reviewing a PR for Accessibility becomes real: checklist for any PR that touches HTML or UI.

      -

      Alex: For a learner, the useful signals are these. Do new images have alt attributes? Do new interactive elements work with keyboard only? Do new form fields have associated elements? Are any new color-only indicators present? Does new dynamic content use aria-live if it updates without a page load?

      -

      Alex: That connects to another useful point. Keep the learner anchored in Writing Accessible Documentation. Documentation in Markdown is converted to HTML. A good GitHub workflow is like a well-run meeting: everyone knows the topic, the next action, and who has the floor.

      -

      Alex: The parts worth keeping in working memory are these. Use heading levels in order (don't skip from H1 to H3). Write descriptive link text (not "click here"). Add alt text to images. Use actual lists (- or 1.) rather than faking them with symbols.

      -

      Jamie: What is the ordered workflow?

      -

      Alex: Start with Manual Testing (catches the rest). There is something to understand, something to try, and something that proves the try worked.

      -

      Alex: First, keyboard-only navigation - unplug your mouse; can you do everything? Then, screen reader walkthrough - navigate the feature with NVDA, JAWS, or VoiceOver. After that, 200% zoom - does content reflow without horizontal scrolling? Finally, high contrast mode - Windows High Contrast or macOS Increase Contrast; are all elements still visible? The rhythm is simple: orient, act, verify, then continue.

      -

      Jamie: Give me the sequence, because order matters here.

      -

      Alex: First, disable CSS - does the content still make sense in reading order? Think of it as a rail line: each stop confirms you are still on the right route before the next one.

      +

      Alex: This is where What Git Flow Is becomes real: Git Flow is a branching model published by Vincent Driessen in 2010. That matters in practice: It was designed for teams that ship versioned releases on a schedule (desktop software, mobile apps, embedded systems).

      +

      Jamie: Let's pause on How the Git Flow Cycle Works. What should a learner take away from it?

      +

      Alex: Start with How the Git Flow Cycle Works. There is something to understand, something to try, and something that proves the try worked.

      +

      Alex: First, developers branch feature/my-feature off develop and work there. Then, completed features merge back into develop via pull request. After that, when develop has enough features for a release, a release/1.2.0 branch is created. Finally, the release branch gets final testing, bug fixes, and version number updates. It is like walking a hallway with named doors: read the sign, enter the right room, then confirm where you landed.

      +

      Jamie: Before we leave How the Git Flow Cycle Works, what is the practical point?

      +

      Alex: First, the release branch merges into main (tagged with the version) and back into develop. Then, if a critical bug is found in production, a hotfix/ branch is created from main, fixed, and merged into both main and develop. The rhythm is simple: orient, act, verify, then continue.

      +

      Jamie: What is the one idea that makes the next few steps less mysterious?

      +

      Alex: The reason How GitHub Flow Differs matters is that the following table compares GitHub Flow and Git Flow across key dimensions.

      +

      Alex: A solid pull request habit is to separate three questions: what changed, why it changed, and what still needs review. That keeps the conversation useful instead of noisy.

      -

      Alex: Here is the practical turn. Start with Learning Cards: Testing Against Standards. There is something to understand, something to try, and something that proves the try worked.

      -

      Alex: On the ground, that means a few things. You are the manual test -- automated tools catch only 30-40% of issues; your screen reader walkthrough catches the rest. Install the axe DevTools browser extension (Section 8 table) and run it on any page; results are announced as a list of violations with WCAG criterion references. When doing a keyboard-only navigation test, press Tab repeatedly and listen -- every interactive element should announce its name and role. The 200% zoom test (item 3) mirrors your daily experience -- if content breaks at 200%, file a bug citing WCAG 1.4.4 Resize Text. Windows High Contrast mode test (item 4) is one click: Settings, Accessibility, Contrast themes -- switch and check that all UI elements remain visible. The WAVE browser extension overlays icons on the page showing errors and warnings -- zoom in to read the small annotation labels.

      -

      Jamie: Let's pause on 10. Official References. What should a learner take away from it?

      -

      Alex: Here is the plain-English version of 10. Official References. Next: Appendix N: Advanced Search Back: Appendix L: Agents Reference Teaching chapter: Chapter 08: Open Source Culture.

      +

      Alex: Here is the practical turn. Start with When You Might See Git Flow. There is something to understand, something to try, and something that proves the try worked.

      +

      Alex: Here is what that changes in practice. 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.

      +

      Jamie: What belongs in the live room, and what can wait until after?

      +

      Alex: Here is the plain-English version of 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. Put another way, it is what GitHub itself uses and what most modern open source projects follow.

      +

      Alex: Keep the thread going. This is where The Unwritten Rule: One Thing Per Branch becomes real: a branch and its PR should do one thing. That matters in practice: If you are fixing a broken link and you notice a typo nearby, fix the typo in a separate branch and PR. The workshop is closer to rehearsal than lecture. You hear the move, try the move, and then check what changed.

      -

      Jamie: What should people carry with them after this?

      -

      Alex: Carry the map. Know what page or tool you are in, know which action you are taking, and know what confirmation should follow. If the confirmation is missing, pause. That pause is not wasted time; it is professional judgment.

      -

      Jamie: That is a better way to say it than just follow the steps.

      -

      Alex: Right. Steps matter, but understanding wins. That is episode 20. Next in the series is episode 21, where we keep building the same contributor muscles.

      -
      - -
      -

      Episode 21: Git Authentication

      -

      Personal access tokens, SSH keys, credential storage, and commit signing.

      -

      Based on: Appendix D: Git Authentication

      -

      Audio and transcript are being regenerated for this episode.

      -
      -Read Transcript - Episode 21: Git Authentication - -

      Transcript

      -

      Alex: Welcome back to Git Going with GitHub. This is episode 21: Git Authentication. I am Alex, and today we are turning Git Authentication from a list of instructions into a working mental model.

      -

      Jamie: And I am Jamie. I will stop us whenever the instructions sound simple on paper but might feel different with a keyboard and screen reader.

      -
      -

      Alex: Personal access tokens, SSH keys, credential storage, and commit signing. That is the surface description. Underneath it, we are building judgment: where to focus, what to ignore, and how to verify the result.

      -

      Jamie: So we are not using the audio as a shortcut around learning. We are using it to make the learning easier to enter.

      -

      Alex: Yes. A good audio lesson gives someone enough context to try the work with confidence, even before they open the written material.

      -
      -

      Jamie: Okay, set the room for us. What are we walking into?

      -

      Alex: Start with SSH Keys & Personal Access Tokens: Audience: This appendix is for contributors who need to configure Git authentication for push access. The next useful detail is this: If you're working entirely through the GitHub web interface or GitHub Desktop, you can skip this.

      -

      Alex: The next layer is this. Start with Learning Cards: Using This Authentication Reference. There is something to understand, something to try, and something that proves the try worked.

      -

      Alex: The practical anchors are these. This appendix has two main paths: Personal Access Token (recommended) and SSH Keys -- jump to your chosen method via heading navigation. Step-by-step instructions are numbered lists -- your screen reader announces "1 of 8," etc. to track progress. The Troubleshooting section near the bottom covers the error messages you are most likely to encounter. Command-line examples are in code blocks with high contrast -- increase zoom to read them comfortably. Each method (PAT vs SSH) is a separate section with its own step-by-step flow. The "Do not" lists use bold text to highlight security warnings.

      -

      Jamie: What is the one idea that makes the next few steps less mysterious?

      -

      Alex: This is where When You Need Authentication becomes real: GitHub requires authentication when you.

      -

      Alex: That shows up in the workshop in a few specific ways. Push commits to a repository. Clone a private repository. Access organization repositories with specific permissions. Clone public repositories. View public repositories on GitHub.com. Read issues and pull requests.

      -
      -

      Alex: Now bring the learner back to the room. Keep the learner anchored in Personal Access Token (PAT). A Personal Access Token is a password-like string you generate on GitHub and use instead of your account password when Git asks for credentials.

      -

      Jamie: What would you say to someone who is already bracing for this to be too much?

      -

      Alex: Start with Pros. There is something to understand, something to try, and something that proves the try worked.

      -

      Alex: The parts worth keeping in working memory are these. Works on all operating systems. Easy to set up for screen reader users (no command line required). Can be scoped to specific permissions. Easy to revoke if compromised.

      -

      Alex: A solid pull request habit is to separate three questions: what changed, why it changed, and what still needs review. That keeps the conversation useful instead of noisy.

      -

      Alex: That matters because of the next idea. Start with Cons. There is something to understand, something to try, and something that proves the try worked.

      -

      Alex: On the ground, that means a few things. You have to store it securely. Expires after a set time (you must regenerate).

      -

      Alex: The useful habit is simple: orient first, act second, verify third. That pause before acting is part of the work.

      -
      -

      Jamie: If I am listening before the workshop starts, what should settle in my mind first?

      -

      Alex: Here is the plain-English version of SSH Keys. You generate a key pair on your computer (public + private), upload the public key to GitHub, and Git uses the private key to prove your identity.

      -

      Alex: This is where the talk moves from concept to action. Start with Pros. There is something to understand, something to try, and something that proves the try worked.

      -

      Alex: The room should hear these as checkpoints. Once set up, works automatically (no password prompts). More secure than tokens. Never expires.

      Jamie: Where do you want a learner to place their attention here?

      -

      Alex: Start with Cons. There is something to understand, something to try, and something that proves the try worked.

      -

      Alex: These are the details that keep the idea from floating away. Requires command-line setup (less accessible for some screen reader users). Slightly more complex initial configuration.

      -
      -

      Alex: Before the learner moves on. The reason Creating a Personal Access Token (Recommended for This Workshop) matters is that why this method: It's screen reader accessible through the GitHub web interface, and you can complete it without command-line Git configuration. The interface gets friendlier when it stops being a wall of controls and starts being a set of named places.

      -

      Jamie: Give me the sequence, because order matters here.

      -

      Alex: Start with Step 1: Generate the Token: The token appears as a long string in a text field. The next useful detail is this: Select all (Ctrl+A), copy (Ctrl+C), and paste it into a secure note or password manager.

      -

      Alex: A few details make that real. repo - Full control of private repositories (includes public repo access). workflow - Update GitHub Actions workflows (if you'll work with Actions).

      -

      Alex: First, navigate to github.com/settings/tokens. Then, select "Tokens (classic)" from the left sidebar. After that, activate "Generate new token" → Select "Generate new token (classic)". Finally, give it a descriptive name in the Note field: "Workshop Laptop Token". Think of it as a rail line: each stop confirms you are still on the right route before the next one.

      -

      Jamie: How would you walk the room through that step by step?

      -

      Alex: First, set expiration: 30 days or 60 days (recommended for temporary workshop use). Then, select scopes. After that, scroll down and activate "Generate token". Finally, cRITICAL: Copy the token immediately - you cannot see it again. Treat it like a recipe: do not add the next ingredient until the previous one is actually in the bowl.

      -

      Alex: Hold that next to this. Start with Options. There is something to understand, something to try, and something that proves the try worked.

      -

      Alex: For a learner, the useful signals are these. Password manager (1Password, Bitwarden, LastPass) - best option. Encrypted note in your operating system's secure notes. Plain text file in an encrypted folder (temporary only).

      -
      +

      Alex: Start with Learning Cards: GitHub Flow. There is something to understand, something to try, and something that proves the try worked.

      +

      Alex: These are the details that keep the idea from floating away. 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). 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.

      +

      Alex: Another way to ground it. The reason Keeping Your Fork Up to Date matters is that when you fork a repository, you get a snapshot of the project at that moment. That gives the learner a simple foothold: the original repository (called "upstream") continues to evolve.

      Jamie: Give me the version that sounds like an instructor, not a manual.

      -

      Alex: Start with Do not. There is something to understand, something to try, and something that proves the try worked.

      -

      Alex: Here is what that changes in practice. Paste it into a document you sync to cloud storage unencrypted. Email it to yourself. Save it in a public GitHub file.

      -

      Jamie: How do you keep commands from becoming magic words?

      -

      Alex: Keep the learner anchored in Step 3: Use It. The next time Git asks for your password (when you push, pull from a private repo, or clone a private repo). This is the part to say slowly: Windows Git Credential Manager: Windows will remember this token automatically after your first use. A good GitHub workflow is like a well-run meeting: everyone knows the topic, the next action, and who has the floor.

      -

      Alex: Treat examples as spoken recipes, not decorations. You may hear something like git config --global credential.helper cache. Read the command, understand what it changes, then run it only when the repository state matches the lesson.

      -

      Jamie: Let's pause on Setting Up SSH Keys (Alternative Method). What should a learner take away from it?

      -

      Alex: The reason Setting Up SSH Keys (Alternative Method) matters is that if you prefer SSH and are comfortable with terminal commands.

      +

      Alex: Start with Why Sync Your Fork? There is something to understand, something to try, and something that proves the try worked.

      +

      Alex: That shows up in the workshop in a few specific ways. 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.

      +
      +

      Jamie: Let's pause on Method 1: GitHub Web Interface (Easiest). What should a learner take away from it?

      +

      Alex: Here is the plain-English version of Method 1: GitHub Web Interface (Easiest). GitHub merges the upstream changes into your fork automatically. Put another way, screen reader users (NVDA / JAWS / VoiceOver). It is like learning a transit route. The names of the stops matter because they tell you whether you are still going the right direction.

      +

      Alex: First, navigate to your fork's main page: github.com/your-username/repo-name. Then, look for the sync indicator: "This branch is X commits behind upstream/main". After that, click the "Sync fork" button. Finally, click "Update branch". Treat it like a recipe: do not add the next ingredient until the previous one is actually in the bowl.

      +

      Jamie: Before we leave Method 1: GitHub Web Interface (Easiest), what is the practical point?

      +

      Alex: First, the sync button appears in the landmark that contains the branch selector. Then, press D to cycle through landmarks until you reach that region. After that, press B to cycle buttons until you hear "Sync fork" → press Enter. Finally, a dialog or page update presents "Update branch" - activate it. It is a checklist, but a meaningful one: every item creates evidence that the next step is safe.

      +

      Jamie: What should someone listen for when a lesson offers more than one tool path?

      +

      Alex: This is where Method 2: Git Command Line (VS Code Terminal) becomes real: if you're working locally in VS Code.

      +

      Jamie: What should happen before anyone copies and runs it?

      +

      Alex: Start with One-time setup - add the upstream remote. There is something to understand, something to try, and something that proves the try worked.

      +

      Alex: Treat examples as spoken recipes, not decorations. You may hear something like git remote add upstream https://github.com/original-owner/repo-name.git; git remote -v Verify it was added. Read the command, understand what it changes, then run it only when the repository state matches the lesson.

      -

      Alex: Here is the practical turn. Start with Step 1: Check If You Already Have a Key: Look for files named id rsa.pub, id ed25519.pub, or similar. The next useful detail is this: If you see these, you already have a key.

      Jamie: What should they understand before typing anything?

      -

      Alex: Here is the plain-English version of Step 2: Generate a New SSH Key. Git will print output showing where the key was saved. Put another way, it generates two files: id ed25519 (private) and id ed25519.pub (public).

      -

      Alex: That becomes easier when you listen for these cues. Press Enter to accept the default file location. Enter a passphrase (optional but recommended).

      -

      Alex: Treat examples as spoken recipes, not decorations. You may hear something like ssh-keygen -t ed25519 -C "your-email@example.com". Read the command, understand what it changes, then run it only when the repository state matches the lesson.

      -

      Jamie: What does the learner do first, second, and then after that?

      -

      Alex: Start with Step 4: Add to GitHub. There is something to understand, something to try, and something that proves the try worked.

      -

      Alex: First, navigate to github.com/settings/keys. Then, select "New SSH key". After that, key type: Authentication Key. Finally, key: Paste your public key (should start with ssh-ed25519 or ssh-rsa). It is a checklist, but a meaningful one: every item creates evidence that the next step is safe.

      -

      Jamie: Turn that into a path someone can follow.

      -

      Alex: First, select "Add SSH key". Then, confirm with your password or 2FA code. It is like walking a hallway with named doors: read the sign, enter the right room, then confirm where you landed.

      +

      Alex: Start with Sync process. There is something to understand, something to try, and something that proves the try worked.

      +

      Alex: Treat examples as spoken recipes, not decorations. You may hear something like 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. Read the command, understand what it changes, then run it only when the repository state matches the lesson.

      +

      Alex: Now bring the learner back to the room. Start with When to sync. There is something to understand, something to try, and something that proves the try worked.

      +

      Alex: The room should hear these as checkpoints. 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).

      +

      Jamie: Let's pause on Method 3: GitHub Desktop. What should a learner take away from it?

      +

      Alex: Start with Method 3: GitHub Desktop. There is something to understand, something to try, and something that proves the try worked.

      +

      Alex: First, open GitHub Desktop. Then, select Repository → Pull to get your fork's latest. After that, select Branch → Merge into Current Branch. Finally, choose upstream/main. Treat it like a recipe: do not add the next ingredient until the previous one is actually in the bowl.

      +

      Jamie: Before we leave Method 3: GitHub Desktop, what is the practical point?

      +

      Alex: First, push the changes to your fork on GitHub. It is a checklist, but a meaningful one: every item creates evidence that the next step is safe.

      +
      +

      Alex: This is the part worth saying out loud. Start with Learning Cards: Keeping Your Fork Up to Date. There is something to understand, something to try, and something that proves the try worked.

      +

      Alex: That becomes easier when you listen for these cues. 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. 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.

      +

      Jamie: Let's pause on Writing Good Commit Messages. What should a learner take away from it?

      +

      Alex: Keep the learner anchored in Writing Good Commit Messages. Every commit you make includes a message describing what changed. This is the part to say slowly: Good commit messages make project history understandable months or years later.

      +

      Alex: That connects to another useful point. The reason The First Line (Required) matters is that this is the commit summary that appears in logs and GitHub's commit list. That gives the learner a simple foothold: think of it as an email subject line. The interface gets friendlier when it stops being a wall of controls and starts being a set of named places.

      +

      Alex: The parts worth keeping in working memory are these. fix: - bug fix. feat: - new feature. docs: - documentation only. style: - formatting, no code change.

      Jamie: What is the safe way to learn from that example?

      -

      Alex: Start with Step 5: Test the Connection. There is something to understand, something to try, and something that proves the try worked.

      -

      Alex: Treat examples as spoken recipes, not decorations. You may hear something like ssh -T git@github.com. Read the command, understand what it changes, then run it only when the repository state matches the lesson.

      -

      Jamie: What should happen before anyone copies and runs it?

      -

      Alex: The reason Step 6: Use SSH URLs matters is that when cloning or adding remotes, use SSH URLs instead of HTTPS.

      -

      Alex: Treat examples as spoken recipes, not decorations. You may hear something like SSH format; git@github.com:owner/repo.git; Instead of HTTPS; https://github.com/owner/repo.git. Read the command, understand what it changes, then run it only when the repository state matches the lesson.

      -

      Jamie: Let's pause on Switching Between HTTPS and SSH. What should a learner take away from it?

      -

      Alex: Start with Switching Between HTTPS and SSH: If you cloned with HTTPS but want to use SSH (or vice versa), update the remote.

      +

      Alex: Start with The Body (Optional): If the summary isn't enough, add a body explaining. The next useful detail is this: Leave a blank line between the summary and the body.

      +

      Alex: The practical takeaway is this. Why you made the change (more important than what). What trade-offs you considered. How the change affects behavior.

      +

      Alex: Treat examples as spoken recipes, not decorations. You may hear something like 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. Read the command, understand what it changes, then run it only when the repository state matches the lesson.

      +

      Alex: Keep the teaching thread moving. Here is the plain-English version of The Footer (Optional). When the commit is merged, GitHub automatically closes linked issues.

      +

      Jamie: Let's pause on Atomic Commits. What should a learner take away from it?

      +

      Alex: This is where Atomic Commits becomes real: each commit should represent one logical change. That matters in practice: Don't bundle unrelated fixes into a single commit.

      -

      Jamie: Let's pause on Check your current remote. What should a learner take away from it?

      -

      Alex: Start with Check your current remote. There is something to understand, something to try, and something that proves the try worked.

      -

      Alex: Treat examples as spoken recipes, not decorations. You may hear something like git remote -v. Read the command, understand what it changes, then run it only when the repository state matches the lesson.

      -

      Jamie: Let's pause on Switch to SSH. What should a learner take away from it?

      -

      Alex: Start with Switch to SSH. There is something to understand, something to try, and something that proves the try worked.

      -

      Alex: Treat examples as spoken recipes, not decorations. You may hear something like git remote set-url origin git@github.com:your-username/repo.git. Read the command, understand what it changes, then run it only when the repository state matches the lesson.

      -

      Jamie: Let's pause on Switch to HTTPS. What should a learner take away from it?

      -

      Alex: Start with Switch to HTTPS. There is something to understand, something to try, and something that proves the try worked.

      -

      Alex: Treat examples as spoken recipes, not decorations. You may hear something like git remote set-url origin https://github.com/your-username/repo.git. Read the command, understand what it changes, then run it only when the repository state matches the lesson.

      +

      Alex: Keep the teaching thread moving. Start with Common mistakes to avoid. There is something to understand, something to try, and something that proves the try worked.

      +

      Alex: The practical takeaway is this. "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.

      +

      Jamie: How do you keep commands from becoming magic words?

      +

      Alex: The reason Good commit messages in practice matters is that when you make a habit of writing good commit messages, you build trust. That gives the learner a simple foothold: maintainers see that you care about the project's long-term health, not just your immediate contribution.

      +

      Alex: Treat examples as spoken recipes, not decorations. You may hear something like 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. Read the command, understand what it changes, then run it only when the repository state matches the lesson.

      +

      Alex: Keep the teaching thread moving. Start with Learning Cards: Writing Good Commit Messages. There is something to understand, something to try, and something that proves the try worked.

      +

      Alex: The practical takeaway is this. 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. 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.

      +

      Jamie: Let's pause on The Nature of Open Source Communication. What should a learner take away from it?

      +

      Alex: Here is the plain-English version of The Nature of Open Source Communication. Open source collaboration happens primarily in writing, asynchronously, in public. Put another way, understanding these three characteristics shapes everything about how we communicate.

      +

      Alex: Keep the teaching thread moving. Start with In writing. There is something to understand, something to try, and something that proves the try worked.

      +

      Alex: The practical takeaway is this. 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.".

      +

      Jamie: Let's pause on Asynchronously. What should a learner take away from it?

      +

      Alex: Start with Asynchronously. There is something to understand, something to try, and something that proves the try worked.

      +

      Alex: The practical takeaway is this. 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.

      +
      +

      Alex: Keep the teaching thread moving. Start with In public. There is something to understand, something to try, and something that proves the try worked.

      +

      Alex: The practical takeaway is this. 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.

      Jamie: What do you want them to do when the plan breaks?

      -

      Alex: Start with Learning Cards: Troubleshooting Authentication. There is something to understand, something to try, and something that proves the try worked.

      -

      Alex: The practical takeaway is this. Each troubleshooting entry starts with the error message in quotes as an h3 heading -- press 3 to jump between errors. Solutions include terminal commands in code blocks -- switch to Focus Mode before copying them. If your error is not listed here, search the GitHub Docs authentication troubleshooting page. Error messages are displayed as bold h3 headings for easy visual scanning. Solution steps are numbered and include code blocks you can copy directly. If terminal output is hard to read, paste commands into VS Code's integrated terminal which respects your theme settings.

      -

      Alex: Keep the thread going. Start with "Authentication failed" when pushing: Problem: Your token expired or is incorrect. Think of it like entering a new building: first you find the lobby, then the room, then the door you actually need.

      -

      Jamie: Let's pause on Solution. What should a learner take away from it?

      -

      Alex: Start with Solution. There is something to understand, something to try, and something that proves the try worked.

      -

      Alex: The practical takeaway is this. Generate a new PAT. Clear your credential cache (Windows: Credential Manager; macOS: Keychain; Linux: git credential-cache exit). Try pushing again - Git will ask for credentials.

      +

      Alex: Start with The Anatomy of Helpful Feedback: Whether commenting on an issue, reviewing a PR, or responding to a question, effective feedback has a structure.

      +

      Alex: Keep the teaching thread moving. Here is the plain-English version of 1. Acknowledge what's working. Before identifying problems, name what is good. Put another way, this is not flattery - it is accuracy. It is like learning a transit route. The names of the stops matter because they tell you whether you are still going the right direction.

      -

      Alex: Another way to ground it. This is where "Permission denied (publickey)" becomes real: problem: SSH key not properly set up.

      -

      Jamie: Before we leave Solution, what is the practical point?

      -

      Alex: The practical takeaway is this. Verify your key is added to GitHub: github.com/settings/keys. Check SSH agent is running: ssh-add -l. Add your key to the agent: ssh-add /.ssh/id ed25519.

      -

      Alex: This is the part worth saying out loud. The reason "Host key verification failed" matters is that problem: SSH doesn't recognize GitHub's host key. The interface gets friendlier when it stops being a wall of controls and starts being a set of named places.

      +

      Jamie: Let's pause on 2. Identify the specific concern. What should a learner take away from it?

      +

      Alex: This is where 2. Identify the specific concern becomes real: "This code is inaccessible." "This button has no accessible name - aria-label or visible text is needed for screen readers to announce its purpose.".

      +

      Alex: Keep the teaching thread moving. Keep the learner anchored in 3. Explain why it matters. Context turns a complaint into a lesson. This is the part to say slowly: It also respects the contributor - they deserve to understand, not just comply.

      +

      Jamie: Let's pause on 4. Suggest a path forward (when you can). What should a learner take away from it?

      +

      Alex: The reason 4. Suggest a path forward (when you can) matters is that if you have an idea for a solution, offer it as a suggestion, not a mandate. That gives the learner a simple foothold: "Something like aria-label='Close navigation menu' would work well here.

      -

      Jamie: What is the teaching move inside Solution?

      -

      Alex: Treat examples as spoken recipes, not decorations. You may hear something like ssh-keyscan github.com /.ssh/known hosts. Read the command, understand what it changes, then run it only when the repository state matches the lesson.

      -

      Jamie: What is the ordered workflow?

      -

      Alex: Start with Security Best Practices. There is something to understand, something to try, and something that proves the try worked.

      -

      Alex: First, never share your private key or PAT - treat them like passwords. Then, use scoped PATs - only grant the minimum permissions needed. After that, set expiration dates on PATs - regenerate periodically. Finally, use a passphrase on SSH keys - adds another layer of security. Treat it like a recipe: do not add the next ingredient until the previous one is actually in the bowl.

      -

      Jamie: Let's pause on Security Best Practices. What should a learner take away from it?

      -

      Alex: First, revoke old tokens when you're done with a project or device. Then, don't commit tokens or keys to Git - use.gitignore for config files. It is a checklist, but a meaningful one: every item creates evidence that the next step is safe.

      -

      Jamie: Let's pause on Commit Signing - Verified Badges and Vigilant Mode. What should a learner take away from it?

      -

      Alex: This is where Commit Signing - Verified Badges and Vigilant Mode becomes real: when you push commits to GitHub, each commit shows a small badge: Verified or Unverified. That matters in practice: This badge tells anyone viewing the commit history whether the commit was cryptographically signed - proving it came from you and was not tampered with.

      -

      Alex: A solid Git habit is to know which branch you are on, what changed, and what confirmation you expect before you run the next command.

      +

      Alex: Keep the teaching thread moving. Start with 5. Signal the weight of the concern: Help contributors understand what is a blocker versus a preference. Think of it like entering a new building: first you find the lobby, then the room, then the door you actually need.

      +

      Alex: The practical takeaway is this. 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.

      +

      Jamie: Let's pause on Prefer "we" or describe the code, not the person. What should a learner take away from it?

      +

      Alex: Here is the plain-English version of 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.".

      +

      Alex: Keep the teaching thread moving. This is where Use tentative language for uncertainty becomes real: "This will crash on mobile." "I think this might cause issues on mobile - have you tested with a narrower viewport?".

      -

      Alex: That connects to another useful point. Keep the learner anchored in Why It Matters. Open source maintainers increasingly require signed commits before merging. This is the part to say slowly: Some repositories enforce this with branch protection rules. A good GitHub workflow is like a well-run meeting: everyone knows the topic, the next action, and who has the floor.

      -

      Jamie: Let's pause on SSH Signing (simpler - reuses your existing SSH key). What should a learner take away from it?

      -

      Alex: The reason SSH Signing (simpler - reuses your existing SSH key) matters is that if you already have an SSH key set up for authentication, you can use it for signing too. That gives the learner a simple foothold: step 1: Configure Git to use SSH for signing.

      -

      Alex: First, navigate to github.com/settings/ssh. Then, select "New SSH key". After that, change "Key type" to "Signing Key" (not Authentication Key). Finally, paste your public key and save. The rhythm is simple: orient, act, verify, then continue.

      -

      Alex: Treat examples as spoken recipes, not decorations. You may hear something like git config --global gpg.format ssh; git config --global user.signingkey /.ssh/id ed25519.pub; git config --global commit.gpgsign true. Read the command, understand what it changes, then run it only when the repository state matches the lesson.

      -

      Jamie: Let's pause on GPG Signing (traditional method). What should a learner take away from it?

      -

      Alex: Start with GPG Signing (traditional method). There is something to understand, something to try, and something that proves the try worked.

      -

      Alex: Treat examples as spoken recipes, not decorations. You may hear something like gpg --full-generate-key; Choose: RSA and RSA, 4096 bits, never expires; Enter your GitHub email address when prompted. Read the command, understand what it changes, then run it only when the repository state matches the lesson.

      +

      Jamie: Let's pause on Acknowledge cultural and language diversity. What should a learner take away from it?

      +

      Alex: Keep the learner anchored in Acknowledge cultural and language diversity. When reading someone's comment: Assume good intent unless there is clear evidence otherwise. This is the part to say slowly: When writing: Choose plain words over clever ones.

      +

      Alex: The practical takeaway is this. 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.

      +

      Alex: Keep the teaching thread moving. The reason Avoid urgency markers unless genuinely urgent matters is that "I need this fixed ASAP" "This is blocking our release scheduled for next Friday - is there capacity to look at it this week?". The interface gets friendlier when it stops being a wall of controls and starts being a set of named places.

      +

      Jamie: Let's pause on Keep comments focused. What should a learner take away from it?

      +

      Alex: Start with Keep comments focused: Each comment should address one concern. The next useful detail is this: If you have three issues, leave three comments - unless they are closely related.

      -

      Jamie: Let's pause on Step 4: Add to GitHub. What should a learner take away from it?

      -

      Alex: First, navigate to github.com/settings/gpg-keys. Then, select "New GPG key" → paste the exported public key. Treat it like a recipe: do not add the next ingredient until the previous one is actually in the bowl.

      -

      Jamie: Let's pause on Step 5: Configure Git to sign all commits. What should a learner take away from it?

      -

      Alex: Start with Step 5: Configure Git to sign all commits. There is something to understand, something to try, and something that proves the try worked.

      -

      Alex: Treat examples as spoken recipes, not decorations. You may hear something like git config --global user.signingkey YOUR KEY ID; git config --global commit.gpgsign true. Read the command, understand what it changes, then run it only when the repository state matches the lesson.

      -

      Jamie: Let's pause on Vigilant Mode. What should a learner take away from it?

      -

      Alex: Keep the learner anchored in Vigilant Mode. GitHub has an optional setting called Vigilant Mode (in Settings → SSH and GPG Keys → Vigilant mode). This is the part to say slowly: When enabled, GitHub marks all commits from your account as "Unverified" unless they are signed - even commits that were previously shown without a badge.

      +

      Alex: Keep the teaching thread moving. Here is the plain-English version of Don't leave comments unresolved. If you asked a question and got an answer, respond. Put another way, "Thanks, that makes sense" or resolving the conversation thread signals that the thread is complete.

      +

      Jamie: Let's pause on Resolving conversations. What should a learner take away from it?

      +

      Alex: This is where Resolving conversations becomes real: on a PR, conversations (inline comment threads) can be "resolved" once addressed. That matters in practice: The author of the change and the reviewer can both resolve them.

      +

      Alex: Keep the teaching thread moving. Keep the learner anchored in 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. This is the part to say slowly: A reaction on an existing comment is enough. A good GitHub workflow is like a well-run meeting: everyone knows the topic, the next action, and who has the floor.

      -

      Alex: Keep the teaching thread moving. Start with Why some maintainers enable Vigilant Mode. There is something to understand, something to try, and something that proves the try worked.

      -

      Alex: The practical takeaway is this. It makes tampered or spoofed commits immediately obvious. It signals that the repository cares about commit provenance.

      -

      Jamie: Let's pause on What you see as a contributor. What should a learner take away from it?

      -

      Alex: Start with What you see as a contributor. There is something to understand, something to try, and something that proves the try worked.

      -

      Alex: The practical takeaway is this. Every unsigned commit you push will show a yellow "Unverified" badge. This is a visual signal - commits can still be pushed, but maintainers may block the merge.

      -

      Alex: Keep the teaching thread moving. Here is the plain-English version of To read verification badges with a screen reader. Workshop recommendation: SSH signing is simpler to set up than GPG and reuses your existing key. Put another way, if you have 10 minutes, configure it before Day 2 - every commit you push to accessibility-agents will show as Verified. It is like learning a transit route. The names of the stops matter because they tell you whether you are still going the right direction.

      -

      Alex: The practical takeaway is this. Navigate to the repository's commit history (Code tab → Commits link). Each commit row contains either "Verified" or "Unverified" as a badge element. NVDA/JAWS: the badge is inside the commit row; use ↓ to read through each row and the badge text is read inline. VoiceOver: use VO+Right through the commit row; the badge is read as a button with the text "Verified" (clicking it shows the certificate).

      -

      Alex: A solid navigation habit is to prove where you are before activating controls. Headings, landmarks, and the address bar are not trivia; they are your map.

      +

      Jamie: Let's pause on Reactions. What should a learner take away from it?

      +

      Alex: The reason Reactions matters is that GitHub reactions () are an efficient way to express agreement, appreciation, or concern without adding noise to a thread.

      +

      Alex: Keep the teaching thread moving. Start with 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. The next useful detail is this: This is a significant accessibility win for anyone who types the same comments repeatedly during triage, reviews, or issue management.

      +

      Jamie: Let's pause on Common uses. What should a learner take away from it?

      +

      Alex: Start with Common uses. There is something to understand, something to try, and something that proves the try worked.

      +

      Alex: The practical takeaway is this. "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.

      -

      Jamie: Let's pause on Recommended approach. What should a learner take away from it?

      -

      Alex: This is where Recommended approach becomes real: sSH keys are great for long-term use, but PATs are faster to set up and more accessible for screen reader users during a time-constrained workshop. That matters in practice: Next: Appendix E: Advanced Git Back: Appendix C: Markdown Reference Teaching chapter: Chapter 00: Pre-Workshop Setup.

      -

      Alex: First, generate a Personal Access Token with 30-day expiration. Then, scope: repo and workflow. After that, store it in your password manager. Finally, use it when VS Code or Git asks for a password. It is a checklist, but a meaningful one: every item creates evidence that the next step is safe.

      +

      Jamie: Let's pause on Creating a Saved Reply. What should a learner take away from it?

      +

      Alex: Start with Creating a Saved Reply. There is something to understand, something to try, and something that proves the try worked.

      +

      Alex: First, navigate to github.com/settings/replies. Then, activate "Add a saved reply". After that, give it a title (e.g., "Good first issue claim") - this is what you search. Finally, type the full reply text in the body (Markdown is supported). It is a checklist, but a meaningful one: every item creates evidence that the next step is safe.

      +

      Jamie: Let's pause on Using a Saved Reply in a comment. What should a learner take away from it?

      +

      Alex: Start with Using a Saved Reply in a comment. There is something to understand, something to try, and something that proves the try worked.

      +

      Alex: First, navigate to any comment text area. Then, activate the Saved Replies button (the speech bubble icon in the comment toolbar, or press Ctrl+. if enabled). After that, a dropdown appears showing your saved replies - type to filter by title. Finally, select the reply - it inserts into the text area. It is like walking a hallway with named doors: read the sign, enter the right room, then confirm where you landed.

      +

      Jamie: Before we leave Using a Saved Reply in a comment, what is the practical point?

      +

      Alex: First, edit as needed before submitting. The rhythm is simple: orient, act, verify, then continue.

      +

      Alex: Keep the teaching thread moving. The reason Screen reader path matters is that limit: GitHub allows up to 100 saved replies per account.

      +

      Alex: A solid navigation habit is to prove where you are before activating controls. Headings, landmarks, and the address bar are not trivia; they are your map.

      -

      Jamie: What should people carry with them after this?

      -

      Alex: Carry the map. Know what page or tool you are in, know which action you are taking, and know what confirmation should follow. If the confirmation is missing, pause. That pause is not wasted time; it is professional judgment.

      -

      Jamie: That is a better way to say it than just follow the steps.

      -

      Alex: Right. Steps matter, but understanding wins. That is episode 21. Next in the series is episode 22, where we keep building the same contributor muscles.

      -
      - +

      Jamie: Let's pause on Learning Cards: Commenting Etiquette. What should a learner take away from it?

      +

      Alex: Start with Learning Cards: Commenting Etiquette. There is something to understand, something to try, and something that proves the try worked.

      +

      Alex: The practical takeaway is this. 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. 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.

      +

      Alex: Keep the teaching thread moving. Here is the plain-English version of 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.". It is like learning a transit route. The names of the stops matter because they tell you whether you are still going the right direction.

      +

      Jamie: Let's pause on Don't gatekeep knowledge. What should a learner take away from it?

      +

      Alex: This is where Don't gatekeep knowledge becomes real: if a contributor makes a mistake because they didn't know something, explain the concept.

      -

      Episode 22: GitHub Flavored Markdown

      -

      Markdown syntax, GitHub extensions, and writing accessible documentation.

      -

      Based on: Appendix C: GitHub Flavored Markdown

      -

      Audio and transcript are being regenerated for this episode.

      -
      -Read Transcript - Episode 22: GitHub Flavored Markdown - -

      Transcript

      -

      Alex: This is Git Going with GitHub, episode 22: GitHub Flavored Markdown. I am Alex. By the end of this episode, GitHub Flavored Markdown should feel less like a wall of GitHub words and more like a set of moves you can trust.

      -

      Jamie: And I am Jamie. I am here for the practical questions: what should I listen for, what can go wrong, and what is the next calm move?

      +

      Alex: Keep the teaching thread moving. Keep the learner anchored in Ask questions instead of making demands. "Change this to use aria-label." "What do you think about using aria-label here instead? This is the part to say slowly: Screen readers would then announce the button's purpose directly.".

      +

      Jamie: Let's pause on Distinguish opinion from requirement. What should a learner take away from it?

      +

      Alex: The reason Distinguish opinion from requirement matters is that if something is your stylistic preference but NOT a bug or correctness issue, say so. That gives the learner a simple foothold: "The current implementation is correct.

      +

      Alex: Keep the teaching thread moving. Start with 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! Think of it like entering a new building: first you find the lobby, then the room, then the door you actually need.

      -

      Alex: Today we are working on this: Markdown syntax, GitHub extensions, and writing accessible documentation. I want the learner to leave with a mental map, not just a remembered path through buttons.

      -

      Jamie: So the goal is understanding first, then action, then confirmation.

      -

      Alex: Right. We are building a rhythm: orient yourself, take one intentional action, then verify what changed before moving on.

      +

      Jamie: Let's pause on Say thank you. What should a learner take away from it?

      +

      Alex: Here is the plain-English version of Say thank you. When someone takes time to review your work, acknowledge it - even if you disagree with some feedback. Put another way, "Thanks so much for the thorough review!

      +

      Alex: Keep the teaching thread moving. This is where Don't take feedback personally becomes real: code review is about the code, not your worth as a person or developer. That matters in practice: Even the most senior contributors receive change requests.

      +

      Jamie: Let's pause on Explain your choices. What should a learner take away from it?

      +

      Alex: Keep the learner anchored in Explain your choices. If you are keeping your implementation despite feedback, explain why. This is the part to say slowly: "I considered aria-label here, but I went with a visually-hidden instead because it allows translators to localize the text more easily.

      -

      Jamie: Okay, set the room for us. What are we walking into?

      -

      Alex: Start with From First Paragraph to Polished Repository - Everything You Need to Know: Whether you have never written a single line of Markdown or you already know the basics and want to master the GitHub-specific extensions, this guide takes you from zero to confident. The next useful detail is this: We start with what Markdown is and why it matters, walk through every foundational element with examples, and then cover the GitHub Flavored Markdown (GFM) features you will encounter in real repositories - alert blocks, Mermaid diagrams, math, footnotes, and.

      -

      Jamie: How would you walk the room through that step by step?

      -

      Alex: Start with Markdown Foundations. There is something to understand, something to try, and something that proves the try worked.

      -

      Alex: First, what Is Markdown? Then, where You Will Use Markdown in This Workshop. After that, how to Practice as You Read. Finally, paragraphs and Line Breaks. Treat it like a recipe: do not add the next ingredient until the previous one is actually in the bowl.

      -

      Jamie: What does the learner do first, second, and then after that?

      -

      Alex: First, headings. Then, emphasis - Bold, Italic, and Bold Italic. After that, strikethrough. Finally, lists - Ordered and Unordered. It is a checklist, but a meaningful one: every item creates evidence that the next step is safe.

      -

      Jamie: Turn that into a path someone can follow.

      -

      Alex: Start with GitHub Flavored Markdown (GFM). There is something to understand, something to try, and something that proves the try worked.

      -

      Alex: First, what Is GitHub Flavored Markdown? Then, alert and Callout Blocks. After that, collapsible Sections with Details and Summary. Finally, task List Checkboxes. It is a checklist, but a meaningful one: every item creates evidence that the next step is safe.

      -

      Jamie: What is the ordered workflow?

      -

      Alex: First, syntax Highlighting in Fenced Code Blocks. Then, mermaid Diagrams. After that, math Expressions with LaTeX. Finally, footnotes. It is like walking a hallway with named doors: read the sign, enter the right room, then confirm where you landed.

      +

      Alex: Keep the teaching thread moving. The reason Surface blockers early matters is that don't wait until you have finished a 500-line PR to mention that you weren't sure about the approach. The interface gets friendlier when it stops being a wall of controls and starts being a set of named places.

      +

      Jamie: Let's pause on Inclusive Commenting for Accessibility Issues. What should a learner take away from it?

      +

      Alex: Start with Inclusive Commenting for Accessibility Issues: When filing or discussing accessibility bugs, additional context helps.

      +

      Alex: The practical takeaway is this. 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.

      +

      Alex: A solid issue habit is to read the title, the body, and the timeline before acting. You are listening for the requested action, the missing evidence, and the person who needs a response.

      +

      Jamie: Let's pause on The "Good First Issue" Social Contract. What should a learner take away from it?

      +

      Alex: Here is the plain-English version of The "Good First Issue" Social Contract. When a maintainer labels an issue good first issue, they are. Put another way, when you take a good first issue, your responsibilities.

      +

      Alex: The practical takeaway is this. Investing time - good first issues require extra documentation and mentorship. Signaling welcome - they want to support a new contributor.

      +

      Alex: First, comment to claim it - "Hi, I'd like to work on this. Can I be assigned?". Then, wait for assignment - do not start until assigned; two people working in parallel wastes everyone's time. After that, 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?". Finally, 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?". Treat it like a recipe: do not add the next ingredient until the previous one is actually in the bowl.

      +

      Jamie: Before we leave The "Good First Issue" Social Contract, what is the practical point?

      +

      Alex: First, don't disappear - if you claim an issue, see it through or explicitly hand it back. It is a checklist, but a meaningful one: every item creates evidence that the next step is safe.

      -

      Jamie: Give me the sequence, because order matters here.

      -

      Alex: Start with Putting It All Together. There is something to understand, something to try, and something that proves the try worked.

      -

      Alex: First, screen Reader Behavior Summary. Then, accessible Markdown Authoring Checklist. After that, common Mistakes and How to Fix Them. Finally, your First Real Markdown Document - Guided Exercise. It is like walking a hallway with named doors: read the sign, enter the right room, then confirm where you landed.

      -

      Jamie: Let's pause on Part 3 - Putting It All Together. What should a learner take away from it?

      -

      Alex: First, quick-Reference Card. The rhythm is simple: orient, act, verify, then continue.

      -

      Jamie: What would you say to someone who is already bracing for this to be too much?

      -

      Alex: Start with Learning Cards: Using This Markdown Reference. There is something to understand, something to try, and something that proves the try worked.

      -

      Alex: The parts worth keeping in working memory are these. Use heading navigation (H key) to jump between numbered sections -- each topic is an h2 heading. Every section shows raw Markdown first, then rendered output, then screen reader behavior notes. The Table of Contents at the top has anchor links -- activate any link to jump directly to that section. Code blocks show the raw Markdown to type -- increase zoom and the monospace font stays readable. Each section follows the same pattern: explanation, raw code, rendered result, and accessibility notes. Use Ctrl+F to search for a specific Markdown element (e.g., search "table" or "heading").

      -

      Alex: The useful habit is simple: orient first, act second, verify third. That pause before acting is part of the work.

      -

      Alex: That matters because of the next idea. Start with 1. What Is Markdown?: Markdown is a lightweight way to format plain text so it renders as rich, structured content - headings, bold text, links, lists, code blocks, tables, and more. The next useful detail is this: You write in a plain text file using simple punctuation characters, and a Markdown processor converts those characters into formatted output. Think of it like entering a new building: first you find the lobby, then the room, then the door you actually need.

      +

      Jamie: Let's pause on When you receive harsh feedback. What should a learner take away from it?

      +

      Alex: Start with When you receive harsh feedback. There is something to understand, something to try, and something that proves the try worked.

      +

      Alex: First, take a breath before responding - there is no urgency; the thread will wait. Then, look for the valid concern underneath the harsh words. After that, respond to the concern, not the tone. Finally, if the behavior crosses into harassment, report it via the "." button on the comment → "Report". It is a checklist, but a meaningful one: every item creates evidence that the next step is safe.

      +

      Jamie: Let's pause on When you disagree with a decision. What should a learner take away from it?

      +

      Alex: Start with When you disagree with a decision. There is something to understand, something to try, and something that proves the try worked.

      +

      Alex: First, make your case once, clearly and with evidence. Then, accept that the maintainer has the final say in their project. After that, if you strongly disagree, you can fork the project and take it in a different direction - this is legitimate in open source. It is like walking a hallway with named doors: read the sign, enter the right room, then confirm where you landed.

      +

      Jamie: Let's pause on When someone is rude to you. What should a learner take away from it?

      +

      Alex: Start with When someone is rude to you. There is something to understand, something to try, and something that proves the try worked.

      +

      Alex: First, you do not have to engage. Then, 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.". After that, report via GitHub's reporting tools if the behavior is abusive. The rhythm is simple: orient, act, verify, then continue.

      -

      Jamie: If I am listening before the workshop starts, what should settle in my mind first?

      -

      Alex: Here is the plain-English version of A brief history. John Gruber created Markdown in 2004 with the goal of making a format that is "as easy to read and write as plain text." Since then, Markdown has become the default writing format.

      -

      Alex: Here is what that changes in practice. GitHub (README files, issues, pull requests, comments, wikis, discussions). Stack Overflow and many developer forums. Static site generators (Jekyll, Hugo, Gatsby). Note-taking apps (Obsidian, Notion, Bear). Documentation systems (MkDocs, Docusaurus, Read the Docs). Chat platforms (Slack, Discord, Microsoft Teams).

      -

      Alex: This is where the talk moves from concept to action. This is where Markdown versus HTML becomes real: markdown converts to HTML behind the scenes. That matters in practice: When you write bold, GitHub converts it to bold.

      -

      Jamie: What is the one idea that makes the next few steps less mysterious?

      -

      Alex: Keep the learner anchored in What gets rendered and what stays raw. When you view a.md file on GitHub, GitHub renders it automatically. This is the part to say slowly: When you edit that file, you see the raw Markdown.

      +

      Jamie: Let's pause on When you accidentally caused offense. What should a learner take away from it?

      +

      Alex: Start with When you accidentally caused offense. There is something to understand, something to try, and something that proves the try worked.

      +

      Alex: First, acknowledge it directly: "I can see how that came across as dismissive - that wasn't my intention.". Then, do not over-explain or defend excessively. After that, adjust going forward. Think of it as a rail line: each stop confirms you are still on the right route before the next one.

      +

      Jamie: Let's pause on Writing Your First README. What should a learner take away from it?

      +

      Alex: Here is the plain-English version of Writing Your First README. See also: Appendix W: GitHub Pages for publishing your README as a website. Put another way, a README is the front door of your project.

      +

      Alex: Keep the teaching thread moving. This is where What belongs in a README becomes real: every README should answer these questions, roughly in this order. That matters in practice: 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. The workshop is closer to rehearsal than lecture. You hear the move, try the move, and then check what changed.

      -

      Alex: Before the learner moves on. The reason 2. Where You Will Use Markdown in This Workshop matters is that markdown is not just one tool in this workshop - it is the thread that connects everything you do. That gives the learner a simple foothold: here is every place you will write or read Markdown during the two days. The interface gets friendlier when it stops being a wall of controls and starts being a set of named places.

      -

      Jamie: How should they picture the shape of the workshop?

      -

      Alex: Start with Day 1 - GitHub Foundations (Browser): The following table lists every Day 1 activity where Markdown is used.

      -

      Alex: Hold that next to this. Here is the plain-English version of Day 2 - VS Code and Accessibility Agents. The following table lists every Day 2 activity where Markdown is used.

      +

      Jamie: Let's pause on Accessibility in READMEs. What should a learner take away from it?

      +

      Alex: Keep the learner anchored in Accessibility in READMEs. Your README is a web page -- GitHub renders it as HTML. This is the part to say slowly: That means the same accessibility rules apply.

      +

      Alex: The practical takeaway is this. Alt text for images and badges. A badge that says is invisible to screen readers. Write 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 -- not Click here.

      +

      Alex: Keep the teaching thread moving. The reason Good README vs. bad README matters is that bad: A single paragraph that says "This is my project. That gives the learner a simple foothold: run it with npm start." No headings, no license, no description of what the project does.

      +

      Jamie: Let's pause on Learning Cards: Writing Your First README. What should a learner take away from it?

      +

      Alex: Start with Learning Cards: Writing Your First README. There is something to understand, something to try, and something that proves the try worked.

      +

      Alex: The practical takeaway is this. 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: rather than an empty that reads as "image" with no context. Use real Markdown link text (installation guide) instead of bare URLs, so your screen reader announces the destination rather than spelling out a long URL. 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.

      -

      Jamie: Where do you want a learner to place their attention here?

      -

      Alex: This is where Learning Room connection becomes real: in the Learning Room repository, every challenge description, every welcome file, and every piece of documentation is Markdown. That matters in practice: When you fix a broken link in docs/welcome.md for Challenge 1, you are editing Markdown.

      -

      Alex: That connects to another useful point. Keep the learner anchored in 3. How to Practice as You Read. The best way to learn Markdown is to type it yourself. This is the part to say slowly: Here are three ways to practice as you read this guide. A good GitHub workflow is like a well-run meeting: everyone knows the topic, the next action, and who has the floor.

      -

      Alex: A solid pull request habit is to separate three questions: what changed, why it changed, and what still needs review. That keeps the conversation useful instead of noisy.

      -

      Jamie: Let's pause on Option 1 - GitHub Issue (recommended for Day 1). What should a learner take away from it?

      -

      Alex: The reason Option 1 - GitHub Issue (recommended for Day 1) matters is that the Write and Preview tabs are announced as tab buttons. That gives the learner a simple foothold: press Enter on "Preview" to switch.

      -

      Alex: First, go to any repository where you have write access (the Learning Room works). Then, click New Issue. After that, type Markdown in the issue body. Finally, click the Preview tab to see the rendered result. The rhythm is simple: orient, act, verify, then continue.

      -

      Jamie: Before we leave Option 1 - GitHub Issue (recommended for Day 1), what is the practical point?

      -

      Alex: First, switch back to Write to keep editing. Then, you do not need to submit the issue - the Preview tab is your sandbox. Think of it as a rail line: each stop confirms you are still on the right route before the next one.

      -

      Alex: A solid issue habit is to read the title, the body, and the timeline before acting. You are listening for the requested action, the missing evidence, and the person who needs a response.

      +

      Alex: Keep the teaching thread moving. Here is the plain-English version of Community Health Files. Community health files tell contributors how your project operates before they write a single line of code. Put another way, 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. It is like learning a transit route. The names of the stops matter because they tell you whether you are still going the right direction.

      +

      Jamie: Let's pause on CONTRIBUTING.md. What should a learner take away from it?

      +

      Alex: This is where CONTRIBUTING.md becomes real: this file answers the question every newcomer asks: "How do I help?" A good CONTRIBUTING.md covers. That matters in practice: A sentence like "We are glad you are here" costs nothing and signals that newcomers are expected, not tolerated.

      +

      Alex: The practical takeaway is this. 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.

      +

      Alex: Keep the teaching thread moving. Keep the learner anchored in CODE OF CONDUCT.md. A code of conduct sets the social contract for your project. This is the part to say slowly: Without one, "acceptable behavior" is whatever each participant assumes it is -- and those assumptions vary widely.

      +

      Alex: The practical takeaway is this. 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.

      -

      Jamie: Let's pause on Option 2 - Any.md file in VS Code (recommended for Day 2). What should a learner take away from it?

      -

      Alex: Start with Option 2 - Any.md file in VS Code (recommended for Day 2). There is something to understand, something to try, and something that proves the try worked.

      -

      Alex: First, create a new file: Ctrl+N, then save it as practice.md. Then, type your Markdown in the editor. After that, press Ctrl+Shift+V to open the rendered Markdown preview in a new tab. Finally, the preview updates live as you type. Think of it as a rail line: each stop confirms you are still on the right route before the next one.

      -

      Jamie: Let's pause on Option 3 - GitHub Gist. What should a learner take away from it?

      -

      Alex: Start with Option 3 - GitHub Gist. There is something to understand, something to try, and something that proves the try worked.

      -

      Alex: First, go to gist.github.com. Then, name your file practice.md. After that, type Markdown in the content area. Finally, click Create secret gist (only you can see it). Treat it like a recipe: do not add the next ingredient until the previous one is actually in the bowl.

      -

      Jamie: Before we leave Option 3 - GitHub Gist, what is the practical point?

      -

      Alex: First, view the rendered result. It is a checklist, but a meaningful one: every item creates evidence that the next step is safe.

      -

      Alex: Keep the thread going. This is where 4. Paragraphs and Line Breaks becomes real: this is the most fundamental element in Markdown, and it trips up almost everyone at first. The workshop is closer to rehearsal than lecture. You hear the move, try the move, and then check what changed.

      +

      Jamie: Let's pause on SECURITY.md. What should a learner take away from it?

      +

      Alex: The reason SECURITY.md matters is that see also: Appendix F: Git Security and Appendix P: Security Features for security best practices. That gives the learner a simple foothold: if someone discovers a vulnerability in your project, you do not want them to file a public issue.

      +

      Alex: The practical takeaway is this. 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.

      +

      Alex: Keep the teaching thread moving. Start with 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. The next useful detail is this: Adding a LICENSE file is a one-time step that makes your project genuinely open source. Think of it like entering a new building: first you find the lobby, then the room, then the door you actually need.

      +

      Jamie: Let's pause on Finding these files on GitHub. What should a learner take away from it?

      +

      Alex: Here is the plain-English version of Finding these files on GitHub. Navigate to any repository and click Insights then Community Standards. Put another way, GitHub shows a checklist of which community health files are present and links to add any that are missing.

      -

      Jamie: Give me the version that sounds like an instructor, not a manual.

      -

      Alex: Keep the learner anchored in Paragraphs. A paragraph is one or more lines of text separated by a blank line (an empty line with nothing on it). This is the part to say slowly: If you do not leave a blank line between two blocks of text, Markdown treats them as one continuous paragraph.

      -

      Alex: Another way to ground it. The reason Line breaks within a paragraph matters is that sometimes you want to go to a new line without starting a whole new paragraph - for example, in an address or a poem. That gives the learner a simple foothold: to create a line break (a in HTML), end a line with two or more spaces and then press Enter.

      -

      Jamie: Let's pause on Common mistake - no blank line between paragraphs. What should a learner take away from it?

      -

      Alex: Start with Common mistake - no blank line between paragraphs: What renders (wrong): Both lines merge into one paragraph. The next useful detail is this: Fix: Add a blank line between them.

      +

      Alex: Keep the teaching thread moving. Start with Learning Cards: Community Health Files. There is something to understand, something to try, and something that proves the try worked.

      +

      Alex: The practical takeaway is this. 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. 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.

      +

      Jamie: How should someone choose between those options?

      +

      Alex: Keep the learner anchored in When to Use Different Communication Channels. GitHub Discussions are separate from Issues. This is the part to say slowly: Use Discussions for: "What do people think about X approach?" and Issues for: "The X button is broken.".

      +

      Alex: Use the comparison to make a decision, not to recite a table. The main contrasts are: PR comment means Feedback on a specific code change. PR review means Formal verdict (approve/request changes) with consolidated feedback. Discussion means Open-ended conversation, proposals, community Q&A.

      +

      Jamie: Let's pause on Try It: Rewrite One Comment. What should a learner take away from it?

      +

      Alex: The reason Try It: Rewrite One Comment matters is that time: 2 minutes What you need: Just your brain. That gives the learner a simple foothold: read this code review comment and rewrite it to be constructive. The interface gets friendlier when it stops being a wall of controls and starts being a set of named places.

      +

      Alex: First, what you noticed. Then, why it matters. After that, what you suggest. Finally, why the suggestion helps. The rhythm is simple: orient, act, verify, then continue.

      +

      Jamie: Before we leave Try It: Rewrite One Comment, what is the practical point?

      +

      Alex: First, encouragement. Think of it as a rail line: each stop confirms you are still on the right route before the next one.

      -

      Alex: This is the part worth saying out loud. Here is the plain-English version of 5. Headings. Headings create the structure of your document. Put another way, they are how screen readers navigate, how tables of contents are built, and how readers scan for the section they need. It is like learning a transit route. The names of the stops matter because they tell you whether you are still going the right direction.

      -

      Alex: A solid navigation habit is to prove where you are before activating controls. Headings, landmarks, and the address bar are not trivia; they are your map.

      -

      Jamie: Let's pause on Syntax. What should a learner take away from it?

      -

      Alex: This is where Syntax becomes real: add one to six characters at the start of a line, followed by a space, then the heading text. That matters in practice: The number of characters determines the heading level.

      -

      Jamie: Let's pause on Rules for accessible headings. What should a learner take away from it?

      -

      Alex: Keep the learner anchored in Rules for accessible headings. Screen readers let you navigate by heading level. This is the part to say slowly: In NVDA and JAWS, pressing H moves to the next heading.

      -

      Alex: First, one H1 per document. The heading is your document title. Every document gets exactly one. Then, never skip levels. Go from to, never from to. Skipping levels breaks the document outline for screen reader users who navigate by heading. After that, make headings descriptive. A heading of "Section 3" tells a screen reader user nothing. A heading of "Creating Your First Pull Request" tells them exactly what the section covers. Finally, do not use bold as a heading substitute. Writing My Section on its own line looks like a heading visually, but it is not a heading in the document structure. Screen reader users navigating by heading (H key in Browse Mode) will never find it. It is like walking a hallway with named doors: read the sign, enter the right room, then confirm where you landed.

      +

      Jamie: Let's pause on Contributing to Open Source. What should a learner take away from it?

      +

      Alex: Start with Contributing to Open Source: This section was previously Appendix T. The next useful detail is this: It is now part of the teaching narrative.

      +

      Alex: Keep the teaching thread moving. Here is the plain-English version of A Guide for First-Time Contributors. You do not need to be a professional developer to contribute to open source. Put another way, documentation, accessibility improvements, and bug reports are among the most valuable contributions any project can receive.

      +

      Jamie: Let's pause on 1. What Is Open Source? What should a learner take away from it?

      +

      Alex: This is where 1. What Is Open Source? becomes real: open source software is software whose source code is publicly available. That matters in practice: Anyone can read it, use it, and - in most cases - contribute to it.

      +

      Alex: The practical takeaway is this. 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.

      -

      Jamie: Let's pause on Alternative heading syntax (not recommended). What should a learner take away from it?

      -

      Alex: The reason Alternative heading syntax (not recommended) matters is that markdown also supports "setext" headings where you underline text with = or - characters. That gives the learner a simple foothold: this only works for levels 1 and 2, and it is harder to scan visually in raw Markdown.

      -

      Alex: Now bring the learner back to the room. Start with 6. Emphasis - Bold, Italic, and Bold Italic: Emphasis changes how text is read by screen readers - it is not just visual. The next useful detail is this: When text is bold or italic, well-configured screen readers can announce emphasis changes, giving the listener additional context about importance. Think of it like entering a new building: first you find the lobby, then the room, then the door you actually need.

      -

      Jamie: Let's pause on Bold. What should a learner take away from it?

      -

      Alex: Here is the plain-English version of Bold. Wrap text in two asterisks or two underscores on each side. Put another way, this is bold text using underscores.

      +

      Alex: Keep the teaching thread moving. Keep the learner anchored in 2. Who Can Contribute? Contributors come from all backgrounds, skill levels, and countries. This is the part to say slowly: 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. A good GitHub workflow is like a well-run meeting: everyone knows the topic, the next action, and who has the floor.

      +

      Jamie: Let's pause on 3. What Makes a Good First Contribution? What should a learner take away from it?

      +

      Alex: Start with 3. What Makes a Good First Contribution? There is something to understand, something to try, and something that proves the try worked.

      +

      Alex: The practical takeaway is this. 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.

      +

      Alex: Keep the teaching thread moving. Start with Signs a contribution is too large for a first attempt: A well-executed small contribution is far more valuable than a large contribution that cannot be merged because it is out of scope.

      +

      Alex: The practical takeaway is this. 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.

      -

      Alex: The next layer is this. This is where Italic becomes real: wrap text in one asterisk or one underscore on each side. That matters in practice: This is italic text using asterisks.

      -

      Jamie: Let's pause on Bold and italic combined. What should a learner take away from it?

      -

      Alex: Keep the learner anchored in Bold and italic combined. Wrap text in three asterisks on each side.

      -

      Jamie: What decision is this helping them make?

      -

      Alex: The reason When to use emphasis matters is that the following table provides guidance on when to use each type of emphasis. That gives the learner a simple foothold: NVDA can announce emphasis changes if the user enables "Report font attributes" (under Speech settings). The interface gets friendlier when it stops being a wall of controls and starts being a set of named places.

      -

      Alex: Use the comparison to make a decision, not to recite a table. The main contrasts are: Key terms, important warnings, UI element names means "Click the Submit button". Book or document titles, introducing new terms, gentle emphasis means "See the Contributing Guide for details". Bold italic means Extremely rare - critical warnings only means " Do not force push to the main branch ".

      +

      Jamie: Let's pause on 4. Finding Something to Work On. What should a learner take away from it?

      +

      Alex: Here is the plain-English version of 4. Finding Something to Work On. Most open source projects label issues that are suitable for new contributors. Put another way, how to search: On any GitHub repository, go to Issues → filter by label.

      +

      Alex: Keep the teaching thread moving. Start with Learning Cards: Finding Something to Work On. There is something to understand, something to try, and something that proves the try worked.

      +

      Alex: The practical takeaway is this. 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. 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.

      +

      Jamie: What is the pre-flight check here?

      +

      Alex: Keep the learner anchored in 5. Reading an Issue Before You Start. Before commenting "I'll take this" on an issue, ask yourself. This is the part to say slowly: 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.

      +

      Alex: The practical takeaway is this. 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.

      -

      Jamie: Let's pause on Emphasis inside words. What should a learner take away from it?

      -

      Alex: Start with Emphasis inside words: Underscores do not (in most Markdown processors including GitHub). The next useful detail is this: Use asterisks when you need emphasis inside a word (rare, but it comes up in technical documentation).

      -

      Alex: Here is the practical turn. Here is the plain-English version of 7. Strikethrough. Strikethrough text shows deleted or outdated content with a line through it. Put another way, wrap text in two tildes on each side.

      -

      Jamie: Let's pause on 8. Lists - Ordered and Unordered. What should a learner take away from it?

      -

      Alex: This is where 8. Lists - Ordered and Unordered becomes real: lists are one of the most common elements in GitHub documentation. That matters in practice: Issue descriptions, PR checklists, README instructions, step-by-step guides - they all use lists.

      +

      Jamie: Let's pause on Tool Cards: Fork, Clone, and Contribute. What should a learner take away from it?

      +

      Alex: Start with Tool Cards: Fork, Clone, and Contribute. There is something to understand, something to try, and something that proves the try worked.

      +

      Alex: First, click Fork on the repository page, then Create fork. Then, edit files directly in your fork's web interface. After that, click Contribute Open pull request to submit back to the original. Finally, fork the repo on github.com first. The rhythm is simple: orient, act, verify, then continue.

      +

      Jamie: Before we leave Tool Cards: Fork, Clone, and Contribute, what is the practical point?

      +

      Alex: First, navigate to your fork and press. to open in the web editor. Then, edit, commit, and create a PR from the Source Control panel. After that, fork on github.com, then clone your fork: Ctrl+Shift+P Git: Clone. Finally, create a branch, make edits, commit and push. Think of it as a rail line: each stop confirms you are still on the right route before the next one.

      +

      Alex: Treat examples as spoken recipes, not decorations. You may hear something like 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. Read the command, understand what it changes, then run it only when the repository state matches the lesson.

      +

      Jamie: Let's pause on The Basic Workflow. What should a learner take away from it?

      +

      Alex: Start with The Basic Workflow. There is something to understand, something to try, and something that proves the try worked.

      +

      Alex: First, fork the repository - creates your own copy on GitHub. Then, clone your fork to your computer (or open a Codespace - see Appendix N). After that, create a branch - name it something descriptive: fix/broken-link-setup-guide. Finally, make your change - edit the file, save, verify. Think of it as a rail line: each stop confirms you are still on the right route before the next one.

      +

      Jamie: Before we leave The Basic Workflow, what is the practical point?

      +

      Alex: First, commit with a clear message - "Fix broken link in setup-guide.md line 34". Then, push to your fork. After that, open a pull request from your branch to the original repository's default branch. Finally, respond to review feedback - maintainers may ask for changes; this is normal and not a rejection. Treat it like a recipe: do not add the next ingredient until the previous one is actually in the bowl.

      +

      Alex: Keep the teaching thread moving. Here is the plain-English version of Writing a Good PR Description. Example: Fixed a broken link on line 34 of setup-guide.md. Put another way, the link pointed to /docs/old-setup which no longer exists. It is like learning a transit route. The names of the stops matter because they tell you whether you are still going the right direction.

      +

      Alex: The practical takeaway is this. What did you change? Why was the change needed? How did you verify it works?

      -

      Alex: Keep the teaching thread moving. Keep the learner anchored in Unordered lists (bullet points). Start each line with a dash (-), asterisk ( ), or plus sign (+) followed by a space. This is the part to say slowly: They are the most common convention on GitHub and visually distinct from the asterisks used for bold and italic. A good GitHub workflow is like a well-run meeting: everyone knows the topic, the next action, and who has the floor.

      -

      Alex: For a learner, the useful signals are these. First item. Second item. Third item.

      -

      Jamie: Let's pause on Ordered lists (numbered). What should a learner take away from it?

      -

      Alex: The reason Ordered lists (numbered) matters is that start each line with a number followed by a period and a space.

      -

      Alex: First, clone the repository. Then, create a new branch. After that, make your changes. Finally, open a pull request. The rhythm is simple: orient, act, verify, then continue.

      -

      Alex: Keep the teaching thread moving. Start with A helpful trick - Markdown renumbers for you: Here is something that surprises most new users. The next useful detail is this: In Markdown, the actual numbers you type do not matter for the rendered output.

      +

      Jamie: How should someone ask for help in a way that gets them unstuck faster?

      +

      Alex: This is where 7. Getting Help becomes real: it is always acceptable to ask a question on an issue or pull request. That matters in practice: 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.

      +

      Alex: The practical takeaway is this. 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.

      +

      Alex: Keep the teaching thread moving. Keep the learner anchored in 8. After Your Contribution Is Merged. This matters for your GitHub profile. This is the part to say slowly: 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.

      +

      Alex: The practical takeaway is this. 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.

      +

      Jamie: Let's pause on 9. Building a Contribution Habit. What should a learner take away from it?

      +

      Alex: The reason 9. Building a Contribution Habit matters is that the hardest part of open source contribution is starting. That gives the learner a simple foothold: 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.

      -

      Jamie: What does someone need before they touch the keyboard?

      -

      Alex: Here is the plain-English version of Starting an ordered list at a specific number. If you need a list to start at a number other than 1, use that number for the first item. Put another way, all subsequent items are numbered sequentially from there.

      -

      Alex: Keep the teaching thread moving. This is where 9. Nested Lists and Mixed Lists becomes real: lists can contain other lists, creating an indented hierarchy. That matters in practice: This is essential for complex instructions, outlines, and project structures. The workshop is closer to rehearsal than lecture. You hear the move, try the move, and then check what changed.

      -

      Jamie: What is the safe way to learn from that example?

      -

      Alex: Keep the learner anchored in Nesting unordered lists. Indent the nested items by two or four spaces (GitHub accepts either, but four is most reliable).

      -

      Alex: These are the details that keep the idea from floating away. Accessibility testing tools. Screen readers. NVDA (Windows, free). JAWS (Windows, commercial). VoiceOver (macOS and iOS, built-in). Browser extensions.

      -

      Alex: Treat examples as spoken recipes, not decorations. You may hear something like Accessibility testing tools; - Screen readers; - NVDA (Windows, free); - JAWS (Windows, commercial); - VoiceOver (macOS and iOS, built-in); - Browser extensions; - axe DevTools; - WAVE; - Documentation tools; - Markdown editors; - Static site generators. Read the command, understand what it changes, then run it only when the repository state matches the lesson.

      +

      Alex: Keep the teaching thread moving. Start with Practical habits: Challenge Time: Complete Challenge 8: The Culture Layer in the Challenge Hub, then advance to Chapter 09: Labels, Milestones and Projects. The next useful detail is this: Next: Chapter 09: Labels, Milestones, and Projects Back: Chapter 07: Merge Conflicts Related appendices: Appendix M: Accessibility Standards Appendix F: Git Security Appendix O: Branch Protection. Think of it like entering a new building: first you find the lobby, then the room, then the door you actually need.

      +

      Alex: The practical takeaway is this. 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.

      -

      Alex: Keep the teaching thread moving. The reason Nesting ordered lists matters is that the same indentation principle applies to numbered lists.

      -

      Jamie: Let's pause on Mixing ordered and unordered lists. What should a learner take away from it?

      -

      Alex: Start with Mixing ordered and unordered lists: You can nest an unordered list inside an ordered list and vice versa.

      -

      Jamie: How do you keep commands from becoming magic words?

      -

      Alex: Here is the plain-English version of Adding content inside list items. List items can contain paragraphs, code blocks, and other elements. Put another way, indent the content to align with the list item text (typically four spaces). It is like learning a transit route. The names of the stops matter because they tell you whether you are still going the right direction.

      -

      Alex: Treat examples as spoken recipes, not decorations. You may hear something like Clone the repository; Open your terminal and run the following command. Read the command, understand what it changes, then run it only when the repository state matches the lesson.

      +

      Jamie: What should people carry with them after this?

      +

      Alex: Carry the map. Know what page or tool you are in, know which action you are taking, and know what confirmation should follow. If the confirmation is missing, pause. That pause is not wasted time; it is professional judgment.

      +

      Jamie: That is a better way to say it than just follow the steps.

      +

      Alex: Right. Steps matter, but understanding wins. That is episode 8. Next in the series is episode 9, where we keep building the same contributor muscles.

      +
      +
      -

      Jamie: Let's pause on 10. Links. What should a learner take away from it?

      -

      Alex: This is where 10. Links becomes real: links are how you connect documents, reference issues, point to external resources, and cite sources. That matters in practice: Getting links right is critical for accessibility - links with bad text are one of the most common accessibility failures in documentation.

      -

      Alex: Keep the teaching thread moving. Keep the learner anchored in Basic link syntax. Wrap the visible link text in square brackets, followed immediately by the URL in parentheses.

      -

      Jamie: Let's pause on Links with title text. What should a learner take away from it?

      -

      Alex: The reason Links with title text matters is that add a title in quotes after the URL. That gives the learner a simple foothold: the title appears as a tooltip on hover.

      +

      23. Challenge 08: The Culture Layer

      +

      Reflection, community norms, issue triage, labels, and respectful communication.

      +

      Practice focus: Day 1 stretch

      +

      Audio and transcript are being regenerated for this episode.

      +
      +Read Transcript - Challenge 08: The Culture Layer + +

      Transcript

      +

      Alex: Welcome to Challenge Coach: The Culture Layer. I am Alex. Before you do the task, we are going to make the skill feel concrete enough to practice.

      +

      Jamie: And I am Jamie. I will keep asking what the learner should do, what evidence counts, and how to recover if the page does something unexpected.

      -

      Alex: Keep the teaching thread moving. Start with Writing accessible link text: This is one of the most important accessibility skills in Markdown authoring. The next useful detail is this: Screen reader users often navigate by pulling up a list of all links on a page (NVDA: NVDA+F7 then select Links; JAWS: Insert+F7). Think of it like entering a new building: first you find the lobby, then the room, then the door you actually need.

      -

      Jamie: Let's pause on Reference-style links. What should a learner take away from it?

      -

      Alex: Here is the plain-English version of Reference-style links. For documents with many links, reference-style links keep the text readable by separating the URL from the prose. Put another way, you define the link target once at the bottom of the document.

      -

      Alex: Keep the teaching thread moving. This is where Relative links within a repository becomes real: when linking to other files in the same repository, use relative paths instead of full URLs. That matters in practice: This way, links work on any fork or branch.

      +

      Alex: The skill focus is Reflection, community norms, issue triage, labels, and respectful communication. This is rehearsal for real contribution, so the evidence matters because it proves the move happened.

      +

      Jamie: So the challenge has to leave the learner with both confidence and a trail of evidence.

      +

      Alex: Exactly. Evidence is not busywork. It is how a learner, a facilitator, and a future maintainer can understand what changed and why.

      -

      Jamie: Let's pause on Email links. What should a learner take away from it?

      -

      Alex: Keep the learner anchored in Email links. The angle brackets tell Markdown to create a mailto: link.

      -

      Alex: Keep the teaching thread moving. The reason Autolinked URLs matters is that GitHub automatically converts full URLs in your text into clickable links, but always prefer explicit descriptive links in prose. That gives the learner a simple foothold: bare URLs should only appear in reference sections or code examples. The interface gets friendlier when it stops being a wall of controls and starts being a set of named places.

      -

      Jamie: Let's pause on Learning Cards: Links. What should a learner take away from it?

      -

      Alex: Start with Learning Cards: Links. There is something to understand, something to try, and something that proves the try worked.

      -

      Alex: A few details make that real. Pull up a links list (NVDA: NVDA+F7 then Links tab; JAWS: Insert+F7) to audit your document -- every link must make sense without its surrounding sentence. Reference-style links ([text][ref]) produce identical HTML to inline links -- screen readers announce them the same way, so choose whichever keeps your source readable. Relative links to other repo files (e.g., Setup) work on any fork or branch -- prefer them over full URLs for internal documentation. Links render as blue underlined text by default -- if your GitHub theme reduces underline visibility, rely on the color difference or hover state to identify links. Long URLs in link text are hard to read at high zoom; always use descriptive text like Contributing Guide instead of pasting the raw URL. The title attribute (text in quotes after the URL) appears as a tooltip on hover -- useful at high magnification but do not put essential information only there.

      +

      Jamie: What makes this practice feel low-stakes but still real?

      +

      Alex: Start with Challenge 8: The Culture Layer: What you will do: Reflect on what makes open source communities welcoming, then practice triaging an issue by adding labels.

      +

      Alex: The next layer is this. Here is the plain-English version of Reflection. Think about your experience so far in this workshop. Put another way, answer one or more of these questions. It is like learning a transit route. The names of the stops matter because they tell you whether you are still going the right direction.

      +

      Alex: The practical anchors are these. What made you feel welcome when you arrived? What would make the learning-room more accessible or inclusive? What is one thing you learned from a peer-simulation issue, PR, or classmate today?

      +

      Jamie: What does the learner do first, second, and then after that?

      +

      Alex: This is where Triage an issue becomes real: I triaged issue XX by adding the label " ".

      +

      Alex: That shows up in the workshop in a few specific ways. bug -- something is broken. enhancement -- a suggestion for improvement. documentation -- related to docs. good first issue -- easy for newcomers.

      +

      Alex: First, go to the Issues tab and find an open issue. The peer-simulation issue is a good choice; if you have real buddy access, you may use a classmate's issue. Then, add at least one label that describes the issue. Some options. After that, if you think the issue needs a specific person's attention, leave a comment tagging them. It is a checklist, but a meaningful one: every item creates evidence that the next step is safe.

      +

      Alex: A solid issue habit is to read the title, the body, and the timeline before acting. You are listening for the requested action, the missing evidence, and the person who needs a response.

      -

      Alex: Keep the teaching thread moving. Here is the plain-English version of 11. Images. Images in Markdown use a syntax similar to links, with an exclamation mark (!) at the beginning.

      -

      Jamie: Before we leave Syntax, what is the practical point?

      -

      Alex: This is where Syntax becomes real: the text inside the square brackets is the alt text - the description that screen readers read aloud instead of displaying the image. That matters in practice: This is the single most important accessibility attribute for images.

      -

      Alex: Keep the teaching thread moving. Keep the learner anchored in Writing good alt text. The following table provides guidance on alt text for different types of images. A good GitHub workflow is like a well-run meeting: everyone knows the topic, the next action, and who has the floor.

      +

      Alex: Now bring the learner back to the room. Keep the learner anchored in Peer simulation check. Share your reflection in the peer-simulation issue or with your buddy if you have one. This is the part to say slowly: Different perspectives make the community richer.

      +

      Jamie: What would you say to someone who is already bracing for this to be too much?

      +

      Alex: The reason Example reflection comment matters is that reading the CODE OF CONDUCT.md and CONTRIBUTING.md files helped me understand that open source projects are communities, not just code. That gives the learner a simple foothold: the contributing guide made it clear that you do not need to be an expert to participate -- filing a good issue is a contribution.

      +

      Alex: The useful habit is simple: orient first, act second, verify third. That pause before acting is part of the work.

      +

      Alex: That matters because of the next idea. Start with Example triage recommendation: If your challenge asked you to evaluate an issue and recommend a label. The next useful detail is this: Issue: "The welcome page loads slowly on mobile" Recommended label: bug Justification: This describes unexpected behavior (slow loading) that affects the user experience. Think of it like entering a new building: first you find the lobby, then the room, then the door you actually need.

      -

      Jamie: Let's pause on Image with a link. What should a learner take away from it?

      -

      Alex: The reason Image with a link matters is that to make an image clickable, wrap the image syntax inside a link.

      -

      Alex: Keep the teaching thread moving. Start with When to use details blocks for complex images: If an image contains complex information (like an architecture diagram or a data visualization), provide a full text description in a collapsible block. The next useful detail is this: Screen readers announce images as "graphic" followed by the alt text.

      -

      Jamie: Let's pause on Learning Cards: Images. What should a learner take away from it?

      -

      Alex: Start with Learning Cards: Images. There is something to understand, something to try, and something that proves the try worked.

      -

      Alex: The room should hear these as checkpoints. Alt text is read aloud as the only representation of the image -- write it to answer "what information does this image convey?" not just "what does it look like?". For decorative images, use empty alt text ( ) so the screen reader skips them entirely rather than announcing the filename. Complex images (architecture diagrams, charts) need a full text description in a block below the image -- expand it to read the complete information. Images render at their original size by default -- use browser or VS Code zoom to enlarge them, and ensure alt text is present in case the image becomes too pixelated. Screenshots with small text are the hardest images to read at high magnification -- request that contributors use cropped, focused screenshots instead of full-screen captures. The alt text is invisible in the rendered view but visible in the raw Markdown source -- switch to the source view to verify alt text exists on all images.

      +

      Jamie: Okay, set the room for us. What are we walking into?

      +

      Alex: Start with Alternate approaches. There is something to understand, something to try, and something that proves the try worked.

      +

      Alex: Here is what that changes in practice. Focus on CODE OF CONDUCT.md and what it means for inclusive collaboration. Focus on CONTRIBUTING.md and what you learned about the contribution process. Compare this project's guidelines to another open source project you have seen.

      +

      Alex: A solid pull request habit is to separate three questions: what changed, why it changed, and what still needs review. That keeps the conversation useful instead of noisy.

      +

      Alex: This is where the talk moves from concept to action. This is where What matters becomes real: the learning objective is understanding that open source has cultural norms, not just technical ones. That matters in practice: Any thoughtful reflection that shows engagement with the governance and contribution documents is a success.

      +

      Jamie: What is the one idea that makes the next few steps less mysterious?

      +

      Alex: Keep the learner anchored in How to Be an Effective and Respectful Open Source Contributor. Technical skills get your code into a project. This is the part to say slowly: Communication skills keep you welcomed in the community.

      -

      Alex: Keep the teaching thread moving. This is where 12. Blockquotes becomes real: blockquotes are used for callouts, important notes, cited text, and instructor guidance throughout this course. That matters in practice: Start each line with a character followed by a space. The workshop is closer to rehearsal than lecture. You hear the move, try the move, and then check what changed.

      -

      Jamie: Let's pause on Basic blockquote. What should a learner take away from it?

      -

      Alex: Keep the learner anchored in Basic blockquote. It is used to highlight important information or to quote someone else's text.

      -

      Alex: Keep the teaching thread moving. The reason Multi-paragraph blockquotes matters is that add a on the blank lines between paragraphs to keep them inside the blockquote.

      -
      -

      Jamie: Let's pause on Blockquotes with other elements. What should a learner take away from it?

      -

      Alex: Start with Blockquotes with other elements: Blockquotes can contain any Markdown element - headings, lists, code, bold, links. The next useful detail is this: Screen readers announce the beginning and end of a blockquote.

      -

      Alex: Keep the teaching thread moving. Here is the plain-English version of How we use blockquotes in this course. Throughout this workshop, blockquotes serve specific purposes. It is like learning a transit route. The names of the stops matter because they tell you whether you are still going the right direction.

      -

      Alex: The practical anchors are these. Screen reader notes: Tips specific to assistive technology users. Learning Room connections: How the current topic connects to the practice repo. Important warnings: Critical information that could prevent errors. Instructor guidance: Notes from the facilitator about pacing or approach.

      -

      Jamie: Let's pause on 13. Inline Code and Code Blocks. What should a learner take away from it?

      -

      Alex: This is where 13. Inline Code and Code Blocks becomes real: code formatting is essential on GitHub. That matters in practice: the learner will use it for command-line instructions, file names, configuration values, keyboard shortcuts, and actual source code.

      +

      Alex: Before the learner moves on. The reason Workshop Recommendation (Chapter 8) matters is that chapter 8 is a communication and culture chapter. The interface gets friendlier when it stops being a wall of controls and starts being a set of named places.

      +

      Alex: That becomes easier when you listen for these cues. There are 1 guided reflection (no bot grading). Automation check: none - communication quality is too subjective for fair automated scoring. The evidence is structured reflection comment on your assigned challenge issue. The pattern is read, reflect, commit to one behavior.

      +

      Jamie: Give me the sequence, because order matters here.

      +

      Alex: Start with Chapter 8 Challenge Set. There is something to understand, something to try, and something that proves the try worked.

      +

      Alex: First, guided reflection - read the chapter, then post a short reflection comment committing to three specific collaboration behaviors. Think of it as a rail line: each stop confirms you are still on the right route before the next one.

      +

      Jamie: How would you walk the room through that step by step?

      +

      Alex: Here is the plain-English version of Challenge 8.1 Step-by-Step: Guided Reflection. Identify three concrete communication behaviors you will practice during the rest of the workshop. Put another way, your assigned Chapter 8 challenge issue in your Learning Room repository on GitHub.com.

      +

      Alex: For a learner, the useful signals are these. 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.".

      +

      Alex: First, read through the chapter content below, paying attention to the sections on GitHub Flow, constructive feedback, and asking for help. Then, as you read, think about one situation from Day 1 where communication helped (or could have helped) you. After that, open your assigned Chapter 8 challenge issue (the one titled "Chapter 8.1: Guided Reflection (@yourname)"). Finally, scroll to the comment box at the bottom of the issue. Treat it like a recipe: do not add the next ingredient until the previous one is actually in the bowl.

      +

      Jamie: Turn that into a path someone can follow.

      +

      Alex: First, post a reflection comment using this format. Then, for each prompt, write one specific, actionable sentence - not a vague goal. After that, activate the Comment button (or press Ctrl+Enter). It is a checklist, but a meaningful one: every item creates evidence that the next step is safe.

      -

      Jamie: What should happen before anyone copies and runs it?

      -

      Alex: Keep the learner anchored in Inline code. Wrap text in single backticks ( `) to format it as code within a sentence. This is the part to say slowly: Run git status to see which files have changed.

      -

      Alex: On the ground, that means a few things. Command names: git clone, npm install. File names: README.md, CONTRIBUTING.md. Keyboard shortcuts: Ctrl+C, Alt+Tab. Variable or function names: userName, getElementById().

      -

      Alex: Treat examples as spoken recipes, not decorations. You may hear something like Run git status to see which files have changed.; The configuration file is package.json.; Press Ctrl+Shift+P to open the Command Palette. Read the command, understand what it changes, then run it only when the repository state matches the lesson.

      -

      Jamie: Let's pause on Code blocks (fenced). What should a learner take away from it?

      -

      Alex: The reason Code blocks (fenced) matters is that for multi-line code, wrap it in triple backticks ( ` ) on their own lines. That gives the learner a simple foothold: all formatting is preserved exactly.

      -

      Alex: Keep the teaching thread moving. Start with Code blocks with syntax highlighting: Add a language identifier right after the opening triple backticks to enable syntax highlighting. The next useful detail is this: def greet(name: str) - str: """Return a greeting for the given name.""" return f"Hello, {name}! Think of it like entering a new building: first you find the lobby, then the room, then the door you actually need.

      +

      Jamie: How do these exercises create confidence instead of pressure?

      +

      Alex: This is where Completing Chapter 8: Submit Your Evidence becomes real: the reflection comment itself is your evidence. That matters in practice: The facilitator reviews your comment for specificity.

      +

      Alex: That connects to another useful point. Start with Expected Outcomes. There is something to understand, something to try, and something that proves the try worked.

      +

      Alex: The parts worth keeping in working memory are these. 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.

      +

      Jamie: What is the ordered workflow?

      +

      Alex: Start with If You Get Stuck. There is something to understand, something to try, and something that proves the try worked.

      +

      Alex: First, use one simple sentence per prompt - do not overthink it. Then, focus on one real behavior you can start doing today, not an abstract principle. After that, if writing feels hard, draft bullet points first in a text editor, then paste into the comment. Finally, look at the "Giving Feedback" and "Asking for Help" sections in this chapter for concrete examples. The rhythm is simple: orient, act, verify, then continue.

      +

      Jamie: Let's pause on If You Get Stuck. What should a learner take away from it?

      +

      Alex: First, ask facilitator for one example response and adapt it to your own words. Then, finished but not sure you did it right? Compare your work against the Challenge 8 reference solution. Think of it as a rail line: each stop confirms you are still on the right route before the next one.

      -

      Jamie: Let's pause on Showing diffs in code blocks. What should a learner take away from it?

      -

      Alex: Here is the plain-English version of Showing diffs in code blocks. The diff language identifier highlights additions and removals. Put another way, + new line that was added unchanged context line.

      -

      Alex: That becomes easier when you listen for these cues. old line that was removed.

      -

      Alex: Keep the teaching thread moving. This is where Code blocks inside list items becomes real: indent the code block to align with the list item text.

      -

      Jamie: Let's pause on How to show literal backticks. What should a learner take away from it?

      -

      Alex: Keep the learner anchored in How to show literal backticks. If your code contains backticks, use more backticks for the fence. This is the part to say slowly: Use four backticks to wrap content that contains triple backticks.

      +

      Alex: Here is the practical turn. Start with Learning Moment: Technical quality and communication quality work together. The next useful detail is this: Respectful, clear communication helps good code get merged faster.

      +

      Jamie: Let's pause on Learning Pattern Used in This Chapter. What should a learner take away from it?

      +

      Alex: Start with Learning Pattern Used in This Chapter. There is something to understand, something to try, and something that proves the try worked.

      +

      Alex: First, read and absorb community norms (not just rules, but reasons). Then, reflect on personal experience (what worked, what was hard). After that, commit to specific behaviors in writing (public accountability). Finally, apply those behaviors in upcoming chapters (reviews, comments, PRs). Treat it like a recipe: do not add the next ingredient until the previous one is actually in the bowl.

      +

      Alex: Keep the thread going. This is where GitHub Flow - The Standard Contribution Workflow becomes real: before diving into communication norms, it helps to understand the workflow that gives all of those conversations their context. That matters in practice: GitHub Flow is the lightweight branching model recommended for open source contribution. The workshop is closer to rehearsal than lecture. You hear the move, try the move, and then check what changed.

      -

      Alex: Keep the teaching thread moving. The reason 14. Horizontal Rules matters is that a horizontal rule creates a thematic break between sections - a visual line across the page. That gives the learner a simple foothold: use three or more dashes, asterisks, or underscores on a line by themselves. The interface gets friendlier when it stops being a wall of controls and starts being a set of named places.

      -

      Jamie: Let's pause on 15. Escaping Special Characters. What should a learner take away from it?

      -

      Alex: Start with 15. Escaping Special Characters: Many characters have special meaning in Markdown. The next useful detail is this: If you want to display them as literal characters instead, put a backslash () before them.

      -

      Alex: Keep the teaching thread moving. Here is the plain-English version of Characters that can be escaped. The following table lists every character that can be escaped in Markdown.

      +

      Jamie: If I am listening before the workshop starts, what should settle in my mind first?

      +

      Alex: Start with Why This Model Works. There is something to understand, something to try, and something that proves the try worked.

      +

      Alex: These are the details that keep the idea from floating away. 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.

      +

      Alex: Another way to ground it. The reason GitHub Flow vs Git Flow matters is that you may encounter "Git Flow" (sometimes written "GitFlow") in older projects or enterprise environments. That gives the learner a simple foothold: this section explains what Git Flow is, how it differs from GitHub Flow, and why this workshop teaches GitHub Flow.

      +

      Alex: A solid Git habit is to know which branch you are on, what changed, and what confirmation you expect before you run the next command.

      +

      Jamie: Where do you want a learner to place their attention here?

      +

      Alex: Start with What Git Flow Is: Git Flow is a branching model published by Vincent Driessen in 2010. The next useful detail is this: It was designed for teams that ship versioned releases on a schedule (desktop software, mobile apps, embedded systems).

      -

      Jamie: Let's pause on Examples. What should a learner take away from it?

      -

      Alex: This is where Examples becomes real: this asterisk is literal: \ not bold\ This hash is literal: \ not a heading Show a pipe character: .

      -

      Alex: Keep the teaching thread moving. Keep the learner anchored in 16. Tables. Tables organize data into rows and columns. This is the part to say slowly: They are used extensively on GitHub for comparison charts, reference data, settings documentation, and checklists. A good GitHub workflow is like a well-run meeting: everyone knows the topic, the next action, and who has the floor.

      -

      Jamie: What should they understand before typing anything?

      -

      Alex: Start with Basic table syntax. There is something to understand, something to try, and something that proves the try worked.

      -

      Alex: Treat examples as spoken recipes, not decorations. You may hear something like Name Role Platform; --- --- ---; NVDA Screen reader Windows; JAWS Screen reader Windows; VoiceOver Screen reader macOS / iOS; TalkBack Screen reader Android. Read the command, understand what it changes, then run it only when the repository state matches the lesson.

      +

      Jamie: Let's pause on How the Git Flow Cycle Works. What should a learner take away from it?

      +

      Alex: Start with How the Git Flow Cycle Works. There is something to understand, something to try, and something that proves the try worked.

      +

      Alex: First, developers branch feature/my-feature off develop and work there. Then, completed features merge back into develop via pull request. After that, when develop has enough features for a release, a release/1.2.0 branch is created. Finally, the release branch gets final testing, bug fixes, and version number updates. Treat it like a recipe: do not add the next ingredient until the previous one is actually in the bowl.

      +

      Jamie: Before we leave How the Git Flow Cycle Works, what is the practical point?

      +

      Alex: First, the release branch merges into main (tagged with the version) and back into develop. Then, if a critical bug is found in production, a hotfix/ branch is created from main, fixed, and merged into both main and develop. It is a checklist, but a meaningful one: every item creates evidence that the next step is safe.

      +

      Jamie: Give me the version that sounds like an instructor, not a manual.

      +

      Alex: This is where How GitHub Flow Differs becomes real: the following table compares GitHub Flow and Git Flow across key dimensions.

      +

      Alex: This is the part worth saying out loud. Start with When You Might See Git Flow. There is something to understand, something to try, and something that proves the try worked.

      +

      Alex: On the ground, that means a few things. 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.

      -

      Alex: Keep the teaching thread moving. Start with How table syntax works. There is something to understand, something to try, and something that proves the try worked.

      -

      Alex: That shows up in the workshop in a few specific ways. The first row is always the header row. The second row contains dashes (---) that separate the header from the data. You need at least three dashes per column. Each subsequent row is a data row. Columns are separated by pipe characters ( ). Leading and trailing pipes are optional but recommended for readability.

      -

      Jamie: Let's pause on Column alignment. What should a learner take away from it?

      -

      Alex: Here is the plain-English version of Column alignment. Add colons (:) to the separator row to control text alignment.

      -

      Alex: The practical takeaway is this.:--- = left aligned (default).:---: = center aligned. ---: = right aligned.

      -

      Alex: Keep the teaching thread moving. This is where Formatting inside table cells becomes real: you can use inline formatting within table cells. The workshop is closer to rehearsal than lecture. You hear the move, try the move, and then check what changed.

      +

      Jamie: Where is the promise of the workshop, underneath all the logistics?

      +

      Alex: The reason Why This Workshop Uses GitHub Flow matters is that for open source contribution - especially at a hackathon or when contributing to web-based projects - GitHub Flow is what you want. That gives the learner a simple foothold: it is what GitHub itself uses and what most modern open source projects follow.

      +

      Alex: Hold that next to this. Start with The Unwritten Rule: One Thing Per Branch: A branch and its PR should do one thing. The next useful detail is this: If you are fixing a broken link and you notice a typo nearby, fix the typo in a separate branch and PR. Think of it like entering a new building: first you find the lobby, then the room, then the door you actually need.

      +

      Jamie: Let's pause on Learning Cards: GitHub Flow. What should a learner take away from it?

      +

      Alex: Start with Learning Cards: GitHub Flow. There is something to understand, something to try, and something that proves the try worked.

      +

      Alex: The room should hear these as checkpoints. 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). 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.

      -

      Jamie: Let's pause on Accessibility considerations for tables. What should a learner take away from it?

      -

      Alex: Keep the learner anchored in Accessibility considerations for tables. Screen readers navigate tables with Ctrl+Alt+Arrow keys (NVDA and JAWS). This is the part to say slowly: Ctrl+Alt+Right moves to the next column.

      -

      Alex: First, always include a description before the table. Add a one-sentence summary immediately above the table explaining what it contains. Screen reader users hear the table structure (rows and columns) but benefit from knowing what the table is about before entering. Then, keep tables simple. Tables with more than 5-6 columns become difficult to navigate with a screen reader. Consider splitting wide tables into multiple narrower tables. After that, use tables for data, not layout. If you are using a table just to arrange content side by side, use a list instead. Finally, make the header row descriptive. The header cell is announced before each data cell when navigating by column, so "Platform" is better than "Col 3". It is like walking a hallway with named doors: read the sign, enter the right room, then confirm where you landed.

      -

      Alex: Keep the teaching thread moving. The reason When not to use a table matters is that if your "table" has only two columns where the first is a label and the second is a value, consider using a definition-style list or bold labels instead. That gives the learner a simple foothold: this is often easier to read with a screen reader than a two-column table.

      -

      Jamie: Let's pause on Learning Cards: Tables. What should a learner take away from it?

      -

      Alex: Start with Learning Cards: Tables. There is something to understand, something to try, and something that proves the try worked.

      -

      Alex: The practical takeaway is this. Navigate tables with Ctrl+Alt+Arrow keys (NVDA/JAWS) -- Right moves to the next column, Down to the next row; the column header is announced each time you change columns. Enter table mode automatically when your screen reader encounters a table -- press T in browse mode to jump to the next table on the page. Before the table structure, listen for the description sentence the author should place above it -- this tells you what data the table contains before you enter cell-by-cell navigation. Wide tables (6+ columns) may require horizontal scrolling at high zoom -- if the table overflows, scroll right to see truncated columns or view the raw Markdown source instead. Column alignment (left, center, right) is controlled by colons in the separator row -- at high magnification, right-aligned numbers are easier to compare than left-aligned ones. If a table is hard to read at your zoom level, try narrowing the browser window -- GitHub will sometimes reflow content or add a horizontal scrollbar.

      +

      Alex: Keep the teaching thread moving. This is where Keeping Your Fork Up to Date becomes real: when you fork a repository, you get a snapshot of the project at that moment. That matters in practice: The original repository (called "upstream") continues to evolve.

      +

      Jamie: Let's pause on Why Sync Your Fork? What should a learner take away from it?

      +

      Alex: Start with Why Sync Your Fork? There is something to understand, something to try, and something that proves the try worked.

      +

      Alex: A few details make that real. 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.

      +

      Jamie: Let's pause on Method 1: GitHub Web Interface (Easiest). What should a learner take away from it?

      +

      Alex: The reason Method 1: GitHub Web Interface (Easiest) matters is that GitHub merges the upstream changes into your fork automatically. That gives the learner a simple foothold: screen reader users (NVDA / JAWS / VoiceOver). The interface gets friendlier when it stops being a wall of controls and starts being a set of named places.

      +

      Alex: First, navigate to your fork's main page: github.com/your-username/repo-name. Then, look for the sync indicator: "This branch is X commits behind upstream/main". After that, click the "Sync fork" button. Finally, click "Update branch". The rhythm is simple: orient, act, verify, then continue.

      +

      Jamie: Before we leave Method 1: GitHub Web Interface (Easiest), what is the practical point?

      +

      Alex: First, the sync button appears in the landmark that contains the branch selector. Then, press D to cycle through landmarks until you reach that region. After that, press B to cycle buttons until you hear "Sync fork" → press Enter. Finally, a dialog or page update presents "Update branch" - activate it. Think of it as a rail line: each stop confirms you are still on the right route before the next one.

      -

      Alex: Keep the teaching thread moving. Start with Learning Cards: GitHub Flavored Markdown. There is something to understand, something to try, and something that proves the try worked.

      -

      Alex: The practical takeaway is this. GFM features (sections 17-27) work only on GitHub -- your screen reader behavior notes are in each section. Alert blocks (section 18) render as blockquotes with a type prefix -- listen for "Note," "Warning," etc. Task list checkboxes (section 20) are announced as "checkbox checked" or "checkbox not checked". Alert blocks use color-coded left borders (blue for Note, yellow for Warning, red for Caution) -- the text label also identifies the type. Mermaid diagrams (section 22) are visual only on GitHub -- the raw code block is always readable. Use GitHub's Preview tab when writing to confirm your GFM renders correctly before submitting.

      -

      Jamie: Let's pause on 17. What Is GitHub Flavored Markdown? What should a learner take away from it?

      -

      Alex: This is where 17. What Is GitHub Flavored Markdown? becomes real: GitHub Flavored Markdown (GFM) is GitHub's own superset of standard Markdown. That matters in practice: It takes everything from the CommonMark specification (the modern standard for Markdown) and adds features specifically designed for software collaboration: tables, task lists, strikethrough, autolinked references, alert blocks, Mermaid diagrams, math.

      -

      Alex: Keep the teaching thread moving. Keep the learner anchored in Where GFM works. The following table shows where GFM is supported.

      +

      Jamie: There are a lot of tools in play. How do we keep that from feeling like a contest?

      +

      Alex: Start with Method 2: Git Command Line (VS Code Terminal): If you're working locally in VS Code.

      +

      Jamie: What should happen before anyone copies and runs it?

      +

      Alex: Start with One-time setup - add the upstream remote. There is something to understand, something to try, and something that proves the try worked.

      +

      Alex: Treat examples as spoken recipes, not decorations. You may hear something like git remote add upstream https://github.com/original-owner/repo-name.git; git remote -v Verify it was added. Read the command, understand what it changes, then run it only when the repository state matches the lesson.

      +

      Jamie: What should they understand before typing anything?

      +

      Alex: Start with Sync process. There is something to understand, something to try, and something that proves the try worked.

      +

      Alex: Treat examples as spoken recipes, not decorations. You may hear something like 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. Read the command, understand what it changes, then run it only when the repository state matches the lesson.

      -

      Jamie: Let's pause on 18. Alert and Callout Blocks. What should a learner take away from it?

      -

      Alex: The reason 18. Alert and Callout Blocks matters is that GitHub introduced alert blocks in 2023. That gives the learner a simple foothold: they render as colored, bordered callout boxes - great for emphasizing warnings, tips, or critical information.

      -

      Jamie: Let's pause on How to write them. What should a learner take away from it?

      -

      Alex: Start with How to write them. There is something to understand, something to try, and something that proves the try worked.

      -

      Alex: First, start a blockquote. Then, the first line must be exactly [!TYPE] where TYPE is one of: NOTE, TIP, IMPORTANT, WARNING, CAUTION. After that, all subsequent lines start with and a space, just like a regular blockquote. Finally, you can include any Markdown inside the alert: lists, code, links, bold. Think of it as a rail line: each stop confirms you are still on the right route before the next one.

      -

      Jamie: Let's pause on Choosing the right alert type. What should a learner take away from it?

      -

      Alex: Here is the plain-English version of Choosing the right alert type. The following table describes each alert type and when to use it.

      +

      Alex: Keep the teaching thread moving. Start with When to sync. There is something to understand, something to try, and something that proves the try worked.

      +

      Alex: The practical takeaway is this. 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).

      +

      Jamie: Let's pause on Method 3: GitHub Desktop. What should a learner take away from it?

      +

      Alex: Start with Method 3: GitHub Desktop. There is something to understand, something to try, and something that proves the try worked.

      +

      Alex: First, open GitHub Desktop. Then, select Repository → Pull to get your fork's latest. After that, select Branch → Merge into Current Branch. Finally, choose upstream/main. The rhythm is simple: orient, act, verify, then continue.

      +

      Jamie: Before we leave Method 3: GitHub Desktop, what is the practical point?

      +

      Alex: First, push the changes to your fork on GitHub. Think of it as a rail line: each stop confirms you are still on the right route before the next one.

      +

      Alex: Keep the teaching thread moving. Start with Learning Cards: Keeping Your Fork Up to Date. There is something to understand, something to try, and something that proves the try worked.

      +

      Alex: The practical takeaway is this. 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. 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.

      -

      Alex: Keep the teaching thread moving. This is where Screen Reader Behavior becomes real: alert blocks render as elements with an SVG icon and a strong heading.

      -

      Alex: The practical takeaway is this. NVDA/JAWS: announces blockquote role, then reads the type label ("Note", "Warning") then the content. VoiceOver: reads the type as bold text then the content. The colored icon is decorative (aria-hidden); it does not add information beyond the type label.

      -

      Jamie: Let's pause on 19. Collapsible Sections with Details and Summary. What should a learner take away from it?

      -

      Alex: Keep the learner anchored in 19. Collapsible Sections with Details and Summary. The and HTML elements create collapsible sections. This is the part to say slowly: They are one of the most useful tools for keeping long documents, issue reports, and PRs manageable - hiding optional content until the reader chooses to expand it.

      -

      Jamie: Let's pause on Important formatting rules. What should a learner take away from it?

      -

      Alex: Start with Important formatting rules. There is something to understand, something to try, and something that proves the try worked.

      -

      Alex: First, blank line after. Put a blank line between the closing tag and your Markdown content. Without it, Markdown formatting inside may not render. Then, blank line before. Same principle at the end. After that, the text should be descriptive - it is the only thing visible when collapsed. The rhythm is simple: orient, act, verify, then continue.

      +

      Jamie: Let's pause on Writing Good Commit Messages. What should a learner take away from it?

      +

      Alex: Here is the plain-English version of Writing Good Commit Messages. Every commit you make includes a message describing what changed. Put another way, good commit messages make project history understandable months or years later.

      +

      Alex: Keep the teaching thread moving. This is where The First Line (Required) becomes real: this is the commit summary that appears in logs and GitHub's commit list. That matters in practice: Think of it as an email subject line. The workshop is closer to rehearsal than lecture. You hear the move, try the move, and then check what changed.

      +

      Alex: The practical takeaway is this. fix: - bug fix. feat: - new feature. docs: - documentation only. style: - formatting, no code change.

      +

      Jamie: What is the safe way to learn from that example?

      +

      Alex: Keep the learner anchored in The Body (Optional). If the summary isn't enough, add a body explaining. This is the part to say slowly: Leave a blank line between the summary and the body.

      +

      Alex: The practical takeaway is this. Why you made the change (more important than what). What trade-offs you considered. How the change affects behavior.

      +

      Alex: Treat examples as spoken recipes, not decorations. You may hear something like 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. Read the command, understand what it changes, then run it only when the repository state matches the lesson.

      -

      Jamie: Zoom out for a second. What kind of journey is this?

      -

      Alex: Start with Real-world uses in this workshop: The following list describes common uses for collapsible sections.

      -

      Alex: The practical takeaway is this. Bug reports in issues: Collapse the full stack trace so the issue body stays readable. Long configuration blocks: Let readers expand the full YAML only if they need it. Exercise solutions: Collapse the answer so learners try the exercise first. Screen reader guidance blocks: Throughout this course, some sections collapse detailed assistive technology instructions so sighted users see a cleaner page while screen reader users can easily expand them. Meeting notes: Collapse detailed minutes while showing the summary.

      -

      Jamie: Let's pause on Details sections that start open. What should a learner take away from it?

      -

      Alex: Here is the plain-English version of Details sections that start open. Add the open attribute to have the section expanded by default.

      -

      Alex: Treat examples as spoken recipes, not decorations. You may hear something like; Currently known issues; - Checkbox toggle requires Focus Mode in NVDA; - Alert blocks do not render in email notifications. Read the command, understand what it changes, then run it only when the repository state matches the lesson.

      -

      Jamie: Let's pause on Screen Reader Behavior. What should a learner take away from it?

      -

      Alex: This is where Screen Reader Behavior becomes real: the element renders as a disclosure widget. That matters in practice: After expanding: The content is immediately readable.

      -

      Alex: The practical takeaway is this. NVDA: announces "button collapsed" for the - press Enter or Space to expand. JAWS: announces "collapsed" - press Enter on the summary to expand. VoiceOver: announces "collapsed, button" - press VO+Space to activate.

      +

      Alex: Keep the teaching thread moving. The reason The Footer (Optional) matters is that when the commit is merged, GitHub automatically closes linked issues.

      +

      Jamie: Let's pause on Atomic Commits. What should a learner take away from it?

      +

      Alex: Start with Atomic Commits: Each commit should represent one logical change. The next useful detail is this: Don't bundle unrelated fixes into a single commit.

      +

      Alex: Keep the teaching thread moving. Start with Common mistakes to avoid. There is something to understand, something to try, and something that proves the try worked.

      +

      Alex: The practical takeaway is this. "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.

      -

      Alex: Keep the teaching thread moving. Start with Learning Cards: Collapsible Sections. There is something to understand, something to try, and something that proves the try worked.

      -

      Alex: The practical takeaway is this. The element is announced as a button -- press Enter or Space to toggle between collapsed and expanded; listen for "collapsed" or "expanded" state announcements. After expanding, the content is immediately available -- arrow down to read it; no page reload or focus change occurs. Nested blocks (details inside details) work but add complexity -- each level is an independent toggle button; keep nesting to one level deep for predictable navigation. The summary text is the only visible element when collapsed -- it appears as a disclosure triangle ( ) with text; zoom in to ensure the triangle and text are both readable. Expanded content appears inline below the summary -- at high zoom it flows naturally with the rest of the page content. The open attribute forces a section to start expanded -- useful when the content is important enough that most readers should see it by default.

      -

      Jamie: Let's pause on 20. Task List Checkboxes. What should a learner take away from it?

      -

      Alex: The reason 20. Task List Checkboxes matters is that task lists in GitHub issues and PRs render as real interactive checkboxes. That gives the learner a simple foothold: anyone with write access to the repository can check and uncheck them directly in the rendered view without editing the Markdown.

      -

      Jamie: What is the teaching move inside Syntax?

      -

      Alex: Start with Syntax. There is something to understand, something to try, and something that proves the try worked.

      -

      Alex: Treat examples as spoken recipes, not decorations. You may hear something like [x] Color contrast verified (4.5:1 minimum for body text); - [x] Keyboard navigation tested; - [ ] Screen reader tested with NVDA; - [ ] Screen reader tested with JAWS; - [ ] Screen reader tested with VoiceOver; - [ ] Alt text provided for all images; - [ ]. Read the command, understand what it changes, then run it only when the repository state matches the lesson.

      +

      Jamie: How do you keep commands from becoming magic words?

      +

      Alex: This is where Good commit messages in practice becomes real: when you make a habit of writing good commit messages, you build trust. That matters in practice: Maintainers see that you care about the project's long-term health, not just your immediate contribution.

      +

      Alex: Treat examples as spoken recipes, not decorations. You may hear something like 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. Read the command, understand what it changes, then run it only when the repository state matches the lesson.

      +

      Alex: Keep the teaching thread moving. Start with Learning Cards: Writing Good Commit Messages. There is something to understand, something to try, and something that proves the try worked.

      +

      Alex: The practical takeaway is this. 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. 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.

      +

      Jamie: Let's pause on The Nature of Open Source Communication. What should a learner take away from it?

      +

      Alex: The reason The Nature of Open Source Communication matters is that open source collaboration happens primarily in writing, asynchronously, in public. That gives the learner a simple foothold: understanding these three characteristics shapes everything about how we communicate.

      -

      Jamie: Before we leave How to write them, what is the practical point?

      -

      Alex: First, start with a list item marker (-,, or +) and a space. Then, add [x] for a checked box or [ ] (with a space inside) for an unchecked box. After that, add a space, then the task description. Finally, the description should be meaningful - "Test NVDA" is better than "Item 3". Treat it like a recipe: do not add the next ingredient until the previous one is actually in the bowl.

      -

      Alex: Keep the teaching thread moving. Start with What makes task lists special on GitHub. There is something to understand, something to try, and something that proves the try worked.

      -

      Alex: The practical takeaway is this. Progress tracking: In issues, GitHub shows a progress bar: "2 of 7 tasks completed". Click to check: In the rendered view, users with triage or write permissions can click to toggle checkboxes without editing the comment. Linked issues: You can reference issues in a task: - [ ] Fix 42 - the task shows the issue title and its open/closed state. PR templates: Task lists in PR templates create checklists that authors fill out before requesting review.

      -

      Jamie: Let's pause on Example - pull request checklist. What should a learner take away from it?

      -

      Alex: Start with Example - pull request checklist. There is something to understand, something to try, and something that proves the try worked.

      -

      Alex: Treat examples as spoken recipes, not decorations. You may hear something like Pre-review checklist; - [x] Changes are limited to the files listed in the issue; - [x] All new images have descriptive alt text; - [ ] Screen reader tested the changes with NVDA; - [ ] No heading levels are skipped; - [ ] All links use descriptive text (not. Read the command, understand what it changes, then run it only when the repository state matches the lesson.

      +

      Alex: Keep the teaching thread moving. Start with In writing. There is something to understand, something to try, and something that proves the try worked.

      +

      Alex: The practical takeaway is this. 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.".

      +

      Jamie: Let's pause on Asynchronously. What should a learner take away from it?

      +

      Alex: Start with Asynchronously. There is something to understand, something to try, and something that proves the try worked.

      +

      Alex: The practical takeaway is this. 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.

      +

      Alex: Keep the teaching thread moving. Start with In public. There is something to understand, something to try, and something that proves the try worked.

      +

      Alex: The practical takeaway is this. 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.

      -

      Alex: Keep the teaching thread moving. The reason Screen Reader Interaction matters is that in Browse Mode, checkboxes are read as checkbox, not checked or checkbox, checked.

      -

      Alex: The practical takeaway is this. NVDA: Press NVDA+Space to enter Focus Mode, then Tab to find the checkbox, then Space to toggle it. JAWS: Tab to the checkbox, then Space to toggle. VoiceOver: VO+Space on the checkbox element.

      -

      Jamie: Let's pause on 21. Syntax Highlighting in Fenced Code Blocks. What should a learner take away from it?

      -

      Alex: Start with 21. Syntax Highlighting in Fenced Code Blocks: We covered basic code blocks in Section 13. The next useful detail is this: This section covers the GitHub-specific syntax highlighting that makes code blocks more readable for sighted users.

      -

      Alex: Keep the teaching thread moving. Here is the plain-English version of How it works. Add a language identifier right after the opening triple backticks. Put another way, GitHub uses Linguist to apply syntax highlighting with appropriate colors for keywords, strings, comments, and other language constructs. It is like learning a transit route. The names of the stops matter because they tell you whether you are still going the right direction.

      +

      Jamie: What do you want them to do when the plan breaks?

      +

      Alex: Keep the learner anchored in The Anatomy of Helpful Feedback. Whether commenting on an issue, reviewing a PR, or responding to a question, effective feedback has a structure.

      +

      Alex: Keep the teaching thread moving. The reason 1. Acknowledge what's working matters is that before identifying problems, name what is good. That gives the learner a simple foothold: this is not flattery - it is accuracy. The interface gets friendlier when it stops being a wall of controls and starts being a set of named places.

      +

      Jamie: Let's pause on 2. Identify the specific concern. What should a learner take away from it?

      +

      Alex: Start with 2. Identify the specific concern: "This code is inaccessible." "This button has no accessible name - aria-label or visible text is needed for screen readers to announce its purpose.".

      -

      Jamie: Let's pause on Complete list of commonly used language identifiers. What should a learner take away from it?

      -

      Alex: This is where Complete list of commonly used language identifiers becomes real: the following table lists the language identifiers you are most likely to use. That matters in practice: If no language is specified, the code block renders as plain monospaced text with no highlighting.

      -

      Alex: Keep the teaching thread moving. Keep the learner anchored in Screen Reader Note. Syntax highlighting is visual only - screen readers read the code text without announcing color changes. This is the part to say slowly: The code block itself is announced as a code region.

      -

      Jamie: Let's pause on 22. Mermaid Diagrams. What should a learner take away from it?

      -

      Alex: The reason 22. Mermaid Diagrams matters is that GitHub renders Mermaid.js diagrams inline when you use a mermaid fenced code block. That gives the learner a simple foothold: they are common in READMEs, PRs, and documentation to illustrate architecture, flows, and relationships.

      +

      Alex: Keep the teaching thread moving. Here is the plain-English version of 3. Explain why it matters. Context turns a complaint into a lesson. Put another way, it also respects the contributor - they deserve to understand, not just comply.

      +

      Jamie: Let's pause on 4. Suggest a path forward (when you can). What should a learner take away from it?

      +

      Alex: This is where 4. Suggest a path forward (when you can) becomes real: if you have an idea for a solution, offer it as a suggestion, not a mandate. That matters in practice: "Something like aria-label='Close navigation menu' would work well here.

      +

      Alex: Keep the teaching thread moving. Keep the learner anchored in 5. Signal the weight of the concern. Help contributors understand what is a blocker versus a preference. A good GitHub workflow is like a well-run meeting: everyone knows the topic, the next action, and who has the floor.

      +

      Alex: The practical takeaway is this. 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.

      -

      Alex: Keep the teaching thread moving. Start with Syntax: flowchart LR A[Fork repo] -- B[Clone locally] B -- C[Create branch] C -- D[Make changes] D -- E[Push branch] E -- F[Open PR] F -- G{Review passed?} G -- Yes -- H[Merge] G -- No -- D. Think of it like entering a new building: first you find the lobby, then the room, then the door you actually need.

      -

      Jamie: Let's pause on Common diagram types. What should a learner take away from it?

      -

      Alex: Here is the plain-English version of Common diagram types. The following table lists the Mermaid diagram types you are most likely to encounter on GitHub.

      -

      Alex: Keep the teaching thread moving. This is where Accessibility limitation - critical becomes real: mermaid diagrams render as SVG images. That matters in practice: GitHub does not auto-generate alt text for them.

      +

      Jamie: Let's pause on Prefer "we" or describe the code, not the person. What should a learner take away from it?

      +

      Alex: The reason Prefer "we" or describe the code, not the person matters is that "You made an error here." "There's an error here." or "This line does X but we need Y.".

      +

      Alex: Keep the teaching thread moving. Start with 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?".

      +

      Jamie: Let's pause on Acknowledge cultural and language diversity. What should a learner take away from it?

      +

      Alex: Here is the plain-English version of Acknowledge cultural and language diversity. When reading someone's comment: Assume good intent unless there is clear evidence otherwise. Put another way, when writing: Choose plain words over clever ones.

      +

      Alex: The practical takeaway is this. 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.

      -

      Jamie: Let's pause on How to make Mermaid diagrams accessible. What should a learner take away from it?

      -

      Alex: Keep the learner anchored in How to make Mermaid diagrams accessible. Example - accessible Mermaid usage. This is the part to say slowly: flowchart LR Fork -- Clone -- Branch -- Commit -- Push -- PR -- Review -- Merge.

      -

      Alex: First, write a text description before the diagram that conveys all the same information. Then, optionally, duplicate the information as a numbered list or table. After that, consider wrapping the Mermaid source in a block if the text description is sufficient. It is like walking a hallway with named doors: read the sign, enter the right room, then confirm where you landed.

      -

      Alex: Keep the teaching thread moving. The reason 23. Math Expressions with LaTeX matters is that GitHub renders LaTeX math expressions using MathJax. That gives the learner a simple foothold: this is common in data science, research, and algorithm documentation. The interface gets friendlier when it stops being a wall of controls and starts being a set of named places.

      -

      Jamie: Let's pause on Inline math. What should a learner take away from it?

      -

      Alex: Start with Inline math: Use single $ delimiters for math within a sentence. The next useful detail is this: Renders as: The formula is $e = mc^2$ where $c$ is the speed of light.

      +

      Alex: Keep the teaching thread moving. This is where Avoid urgency markers unless genuinely urgent becomes real: "I need this fixed ASAP" "This is blocking our release scheduled for next Friday - is there capacity to look at it this week?". The workshop is closer to rehearsal than lecture. You hear the move, try the move, and then check what changed.

      +

      Jamie: Let's pause on Keep comments focused. What should a learner take away from it?

      +

      Alex: Keep the learner anchored in Keep comments focused. Each comment should address one concern. This is the part to say slowly: If you have three issues, leave three comments - unless they are closely related.

      +

      Alex: Keep the teaching thread moving. The reason Don't leave comments unresolved matters is that if you asked a question and got an answer, respond. That gives the learner a simple foothold: "Thanks, that makes sense" or resolving the conversation thread signals that the thread is complete.

      -

      Alex: Keep the teaching thread moving. Here is the plain-English version of Block math. Use $$ delimiters for display-style (centered, larger) math on their own lines.

      -

      Jamie: Let's pause on Common LaTeX patterns. What should a learner take away from it?

      -

      Alex: This is where Common LaTeX patterns becomes real: the following table shows some LaTeX patterns you might encounter.

      -

      Alex: Keep the teaching thread moving. Keep the learner anchored in Screen Reader Note. Math expressions rendered by MathJax include aria-label attributes with the spoken form of the equation. This is the part to say slowly: Screen readers should announce the math correctly, but accuracy varies. A good GitHub workflow is like a well-run meeting: everyone knows the topic, the next action, and who has the floor.

      -

      Alex: The practical takeaway is this. NVDA with Firefox or Chrome: reads MathML fairly well. JAWS: reads the aria-label text. VoiceOver: reads the aria-label text.

      +

      Jamie: Let's pause on Resolving conversations. What should a learner take away from it?

      +

      Alex: Start with Resolving conversations: On a PR, conversations (inline comment threads) can be "resolved" once addressed. The next useful detail is this: The author of the change and the reviewer can both resolve them.

      +

      Alex: Keep the teaching thread moving. Here is the plain-English version of 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. Put another way, a reaction on an existing comment is enough. It is like learning a transit route. The names of the stops matter because they tell you whether you are still going the right direction.

      +

      Jamie: Let's pause on Reactions. What should a learner take away from it?

      +

      Alex: This is where Reactions becomes real: GitHub reactions () are an efficient way to express agreement, appreciation, or concern without adding noise to a thread.

      -

      Jamie: Let's pause on 24. Footnotes. What should a learner take away from it?

      -

      Alex: The reason 24. Footnotes matters is that GitHub supports Markdown footnotes, which render as superscript numbers that link to references at the bottom of the document. That gives the learner a simple foothold: they are useful for citations, additional context, and references that would interrupt the flow of the main text.

      -

      Jamie: Let's pause on How they work. What should a learner take away from it?

      -

      Alex: Start with How they work. There is something to understand, something to try, and something that proves the try worked.

      -

      Alex: First, in your text, add [^identifier] where you want the footnote reference to appear. Then, anywhere in the document (typically at the bottom), define the footnote with [^identifier]: Your footnote text. After that, GitHub renders the reference as a superscript number that links to the definition. Finally, the definition includes a back-link that returns to the reference location. Think of it as a rail line: each stop confirms you are still on the right route before the next one.

      -

      Jamie: Let's pause on Footnote identifiers. What should a learner take away from it?

      -

      Alex: Start with Footnote identifiers. There is something to understand, something to try, and something that proves the try worked.

      -

      Alex: The practical takeaway is this. You can use numbers: [^1], [^2], [^3]. You can use descriptive names: [^webaim-survey], [^wcag-reference]. Descriptive names make the raw Markdown more readable but render as sequential numbers.

      +

      Alex: Keep the teaching thread moving. Keep the learner anchored in 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 the part to say slowly: This is a significant accessibility win for anyone who types the same comments repeatedly during triage, reviews, or issue management.

      +

      Jamie: Let's pause on Common uses. What should a learner take away from it?

      +

      Alex: Start with Common uses. There is something to understand, something to try, and something that proves the try worked.

      +

      Alex: The practical takeaway is this. "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.

      +

      Jamie: Let's pause on Creating a Saved Reply. What should a learner take away from it?

      +

      Alex: Start with Creating a Saved Reply. There is something to understand, something to try, and something that proves the try worked.

      +

      Alex: First, navigate to github.com/settings/replies. Then, activate "Add a saved reply". After that, give it a title (e.g., "Good first issue claim") - this is what you search. Finally, type the full reply text in the body (Markdown is supported). Think of it as a rail line: each stop confirms you are still on the right route before the next one.

      -

      Alex: Keep the teaching thread moving. This is where Multi-line footnotes becomes real: indent continuation lines with two spaces. The workshop is closer to rehearsal than lecture. You hear the move, try the move, and then check what changed.

      -

      Jamie: Before we leave Screen Reader Behavior, what is the practical point?

      -

      Alex: Start with Screen Reader Behavior. There is something to understand, something to try, and something that proves the try worked.

      -

      Alex: The practical takeaway is this. The footnote reference is a link ( element) announcing its number. NVDA: "superscript, 1, link". JAWS: "link, 1". VoiceOver: "link, footnote 1". The back-link at the definition reads "return to footnote reference". Activating the footnote link jumps focus to the definition; activating the back-link returns focus to the original location.

      -

      Alex: Keep the teaching thread moving. The reason 25. Linked Heading Anchors and Tables of Contents matters is that every heading in a GitHub Markdown file automatically gets an anchor ID. That gives the learner a simple foothold: you can link to any heading from anywhere - within the same document, from another file, or from an issue or PR.

      +

      Jamie: Let's pause on Using a Saved Reply in a comment. What should a learner take away from it?

      +

      Alex: Start with Using a Saved Reply in a comment. There is something to understand, something to try, and something that proves the try worked.

      +

      Alex: First, navigate to any comment text area. Then, activate the Saved Replies button (the speech bubble icon in the comment toolbar, or press Ctrl+. if enabled). After that, a dropdown appears showing your saved replies - type to filter by title. Finally, select the reply - it inserts into the text area. Treat it like a recipe: do not add the next ingredient until the previous one is actually in the bowl.

      +

      Jamie: Before we leave Using a Saved Reply in a comment, what is the practical point?

      +

      Alex: First, edit as needed before submitting. It is a checklist, but a meaningful one: every item creates evidence that the next step is safe.

      +

      Alex: Keep the teaching thread moving. This is where Screen reader path becomes real: limit: GitHub allows up to 100 saved replies per account.

      +

      Alex: A solid navigation habit is to prove where you are before activating controls. Headings, landmarks, and the address bar are not trivia; they are your map.

      +

      Jamie: Let's pause on Learning Cards: Commenting Etiquette. What should a learner take away from it?

      +

      Alex: Start with Learning Cards: Commenting Etiquette. There is something to understand, something to try, and something that proves the try worked.

      +

      Alex: The practical takeaway is this. 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. 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.

      -

      Jamie: Let's pause on How GitHub generates anchor IDs. What should a learner take away from it?

      -

      Alex: Start with How GitHub generates anchor IDs: GitHub converts the heading text to an anchor ID. The next useful detail is this: The following table shows example headings and their generated anchors.

      -

      Alex: First, converting to lowercase. Then, replacing spaces with hyphens. After that, removing most punctuation (except hyphens). Finally, removing leading and trailing whitespace. Think of it as a rail line: each stop confirms you are still on the right route before the next one.

      -

      Alex: Keep the teaching thread moving. Here is the plain-English version of Building a table of contents. You can build a manual table of contents using heading anchor links. It is like learning a transit route. The names of the stops matter because they tell you whether you are still going the right direction.

      -

      Jamie: Let's pause on Duplicate headings. What should a learner take away from it?

      -

      Alex: This is where Duplicate headings becomes real: if a document has two headings with the same text, GitHub appends -1, -2, and so on to the duplicate anchors. That matters in practice: Best practice: Avoid duplicate heading text.

      +

      Alex: Keep the teaching thread moving. The reason Review the code, not the person matters is that "You clearly don't understand accessibility." "This implementation doesn't account for keyboard navigation - here's how to add it.". The interface gets friendlier when it stops being a wall of controls and starts being a set of named places.

      +

      Jamie: Let's pause on Don't gatekeep knowledge. What should a learner take away from it?

      +

      Alex: Start with Don't gatekeep knowledge: If a contributor makes a mistake because they didn't know something, explain the concept.

      +

      Alex: Keep the teaching thread moving. Here is the plain-English version of Ask questions instead of making demands. "Change this to use aria-label." "What do you think about using aria-label here instead? Put another way, screen readers would then announce the button's purpose directly.".

      -

      Jamie: Let's pause on Finding the anchor for any heading. What should a learner take away from it?

      -

      Alex: Start with Finding the anchor for any heading. There is something to understand, something to try, and something that proves the try worked.

      -

      Alex: First, mouse users: On GitHub, hover over any heading - a chain link icon appears to the left. Click it to update the URL with the anchor. Then, screen reader users: Navigate to the heading, then Tab once. A link button appears. Activate it and the URL in the address bar updates to show the anchor. After that, keyboard (GitHub shortcut): There is no direct shortcut, but you can copy the heading text, convert it to the anchor format mentally, and type it in the URL. It is like walking a hallway with named doors: read the sign, enter the right room, then confirm where you landed.

      -

      Jamie: Let's pause on 26. Autolinked References - Issues, PRs, Commits, and Users. What should a learner take away from it?

      -

      Alex: The reason 26. Autolinked References - Issues, PRs, Commits, and Users matters is that one of GitHub's most powerful features is automatic linking. That gives the learner a simple foothold: when you type certain patterns in any Markdown field on GitHub, they automatically become clickable links.

      -

      Alex: Keep the teaching thread moving. Start with Issue and pull request references: The following table shows how to reference issues and pull requests. Think of it like entering a new building: first you find the lobby, then the room, then the door you actually need.

      +

      Jamie: Let's pause on Distinguish opinion from requirement. What should a learner take away from it?

      +

      Alex: This is where Distinguish opinion from requirement becomes real: if something is your stylistic preference but NOT a bug or correctness issue, say so. That matters in practice: "The current implementation is correct.

      +

      Alex: Keep the teaching thread moving. Keep the learner anchored in 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! A good GitHub workflow is like a well-run meeting: everyone knows the topic, the next action, and who has the floor.

      +

      Jamie: Let's pause on Say thank you. What should a learner take away from it?

      +

      Alex: The reason Say thank you matters is that when someone takes time to review your work, acknowledge it - even if you disagree with some feedback. That gives the learner a simple foothold: "Thanks so much for the thorough review!

      -

      Jamie: Let's pause on User and team mentions. What should a learner take away from it?

      -

      Alex: Here is the plain-English version of User and team mentions. The following table shows how to mention users and teams.

      -

      Alex: Keep the teaching thread moving. This is where Commit references becomes real: the following table shows how to reference specific commits.

      -

      Alex: A solid Git habit is to know which branch you are on, what changed, and what confirmation you expect before you run the next command.

      -

      Jamie: Let's pause on Closing keywords in pull requests. What should a learner take away from it?

      -

      Alex: Keep the learner anchored in Closing keywords in pull requests. When you include certain keywords followed by an issue reference in a PR description, merging the PR automatically closes the referenced issue. This is the part to say slowly: All of these keywords work: close, closes, closed, fix, fixes, fixed, resolve, resolves, resolved.

      +

      Alex: Keep the teaching thread moving. Start with Don't take feedback personally: Code review is about the code, not your worth as a person or developer. The next useful detail is this: Even the most senior contributors receive change requests.

      +

      Jamie: Let's pause on Explain your choices. What should a learner take away from it?

      +

      Alex: Here is the plain-English version of Explain your choices. If you are keeping your implementation despite feedback, explain why. Put another way, "I considered aria-label here, but I went with a visually-hidden instead because it allows translators to localize the text more easily.

      +

      Alex: Keep the teaching thread moving. This is where Surface blockers early becomes real: don't wait until you have finished a 500-line PR to mention that you weren't sure about the approach. The workshop is closer to rehearsal than lecture. You hear the move, try the move, and then check what changed.

      -

      Alex: Keep the teaching thread moving. The reason URL autolinking matters is that GitHub automatically converts full URLs into clickable links. That gives the learner a simple foothold: accessibility note: While autolinked URLs work, they create poor link text for screen readers (the entire URL is read character by character). The interface gets friendlier when it stops being a wall of controls and starts being a set of named places.

      -

      Jamie: Let's pause on 27. HTML in Markdown. What should a learner take away from it?

      -

      Alex: Start with 27. HTML in Markdown: GitHub allows a subset of HTML in Markdown files. The next useful detail is this: This is useful for semantic elements that do not have Markdown equivalents, advanced layout needs, and accessibility improvements.

      -

      Jamie: Let's pause on Keyboard key visualization. What should a learner take away from it?

      -

      Alex: Here is the plain-English version of Keyboard key visualization. The element renders text in a key-cap style box. Put another way, press NVDA + Space to toggle Focus Mode.

      -

      Alex: Treat examples as spoken recipes, not decorations. You may hear something like Press Ctrl + C to copy.; Press NVDA + Space to toggle Focus Mode. Read the command, understand what it changes, then run it only when the repository state matches the lesson.

      +

      Jamie: Let's pause on Inclusive Commenting for Accessibility Issues. What should a learner take away from it?

      +

      Alex: Keep the learner anchored in Inclusive Commenting for Accessibility Issues. When filing or discussing accessibility bugs, additional context helps.

      +

      Alex: The practical takeaway is this. 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.

      +

      Jamie: Let's pause on The "Good First Issue" Social Contract. What should a learner take away from it?

      +

      Alex: The reason The "Good First Issue" Social Contract matters is that when a maintainer labels an issue good first issue, they are. That gives the learner a simple foothold: when you take a good first issue, your responsibilities.

      +

      Alex: The practical takeaway is this. Investing time - good first issues require extra documentation and mentorship. Signaling welcome - they want to support a new contributor.

      +

      Alex: First, comment to claim it - "Hi, I'd like to work on this. Can I be assigned?". Then, wait for assignment - do not start until assigned; two people working in parallel wastes everyone's time. After that, 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?". Finally, 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?". The rhythm is simple: orient, act, verify, then continue.

      +

      Jamie: Before we leave The "Good First Issue" Social Contract, what is the practical point?

      +

      Alex: First, don't disappear - if you claim an issue, see it through or explicitly hand it back. Think of it as a rail line: each stop confirms you are still on the right route before the next one.

      +

      Jamie: Let's pause on When you receive harsh feedback. What should a learner take away from it?

      +

      Alex: Start with When you receive harsh feedback. There is something to understand, something to try, and something that proves the try worked.

      +

      Alex: First, take a breath before responding - there is no urgency; the thread will wait. Then, look for the valid concern underneath the harsh words. After that, respond to the concern, not the tone. Finally, if the behavior crosses into harassment, report it via the "." button on the comment → "Report". Think of it as a rail line: each stop confirms you are still on the right route before the next one.

      -

      Jamie: Let's pause on Hidden comments. What should a learner take away from it?

      -

      Alex: This is where Hidden comments becomes real: hidden comments are useful for notes to yourself or other contributors that should not be visible to readers.

      -

      Alex: Keep the teaching thread moving. Keep the learner anchored in Allowed HTML elements on GitHub. GitHub whitelists specific HTML elements for security. This is the part to say slowly: The following table lists the most useful allowed elements. A good GitHub workflow is like a well-run meeting: everyone knows the topic, the next action, and who has the floor.

      -

      Jamie: Let's pause on Disallowed HTML on GitHub. What should a learner take away from it?

      -

      Alex: The reason Disallowed HTML on GitHub matters is that GitHub strips these elements for security.

      -

      Alex: The practical takeaway is this. No JavaScript execution. No arbitrary CSS. No embedded content. No form elements (except task list checkboxes). No input fields. Event attributes like onclick, onload.

      +

      Jamie: Let's pause on When you disagree with a decision. What should a learner take away from it?

      +

      Alex: Start with When you disagree with a decision. There is something to understand, something to try, and something that proves the try worked.

      +

      Alex: First, make your case once, clearly and with evidence. Then, accept that the maintainer has the final say in their project. After that, if you strongly disagree, you can fork the project and take it in a different direction - this is legitimate in open source. Treat it like a recipe: do not add the next ingredient until the previous one is actually in the bowl.

      +

      Jamie: Let's pause on When someone is rude to you. What should a learner take away from it?

      +

      Alex: Start with When someone is rude to you. There is something to understand, something to try, and something that proves the try worked.

      +

      Alex: First, you do not have to engage. Then, 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.". After that, report via GitHub's reporting tools if the behavior is abusive. It is a checklist, but a meaningful one: every item creates evidence that the next step is safe.

      +

      Jamie: Let's pause on When you accidentally caused offense. What should a learner take away from it?

      +

      Alex: Start with When you accidentally caused offense. There is something to understand, something to try, and something that proves the try worked.

      +

      Alex: First, acknowledge it directly: "I can see how that came across as dismissive - that wasn't my intention.". Then, do not over-explain or defend excessively. After that, adjust going forward. It is like walking a hallway with named doors: read the sign, enter the right room, then confirm where you landed.

      -

      Alex: Keep the teaching thread moving. Start with 28. Screen Reader Behavior Summary: This table consolidates how every Markdown element behaves with screen readers. The next useful detail is this: Use it as a quick reference when choosing how to format your content.

      -

      Jamie: Let's pause on 29. Accessible Markdown Authoring Checklist. What should a learner take away from it?

      -

      Alex: Here is the plain-English version of 29. Accessible Markdown Authoring Checklist. Use this checklist every time you write a Markdown file, issue, or PR description. Put another way, it covers the accessibility requirements that make your content work for everyone.

      -

      Alex: Keep the teaching thread moving. Start with Structure. There is something to understand, something to try, and something that proves the try worked.

      -

      Alex: The practical takeaway is this. [ ] One H1 heading per document, used as the title. [ ] Heading levels never skip (no jumping from H2 to H4). [ ] Headings are descriptive (not "Section 1" or "Untitled"). [ ] Long documents have a table of contents with anchor links.

      +

      Jamie: Let's pause on Writing Your First README. What should a learner take away from it?

      +

      Alex: The reason Writing Your First README matters is that see also: Appendix W: GitHub Pages for publishing your README as a website. That gives the learner a simple foothold: a README is the front door of your project.

      +

      Alex: Keep the teaching thread moving. Start with What belongs in a README: Every README should answer these questions, roughly in this order. The next useful detail is this: 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. Think of it like entering a new building: first you find the lobby, then the room, then the door you actually need.

      +

      Jamie: Let's pause on Accessibility in READMEs. What should a learner take away from it?

      +

      Alex: Here is the plain-English version of Accessibility in READMEs. Your README is a web page -- GitHub renders it as HTML. Put another way, that means the same accessibility rules apply.

      +

      Alex: The practical takeaway is this. Alt text for images and badges. A badge that says is invisible to screen readers. Write 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 -- not Click here.

      -

      Jamie: Let's pause on Text and emphasis. What should a learner take away from it?

      -

      Alex: Start with Text and emphasis. There is something to understand, something to try, and something that proves the try worked.

      -

      Alex: The practical takeaway is this. [ ] Bold marks genuinely important content, not just visual styling. [ ] Bold text is not used as a substitute for headings. [ ] Strikethrough text has surrounding context explaining the change.

      -

      Alex: Keep the teaching thread moving. Start with Links. There is something to understand, something to try, and something that proves the try worked.

      -

      Alex: The practical takeaway is this. [ ] Every link has descriptive text (never "click here," "here," "read more," or "link"). [ ] No bare URLs in prose (always use descriptive text). [ ] Multiple links on the same page have unique text if they point to different destinations. [ ] Relative links used for files within the same repository.

      -

      Jamie: Let's pause on Images. What should a learner take away from it?

      -

      Alex: Start with Images. There is something to understand, something to try, and something that proves the try worked.

      -

      Alex: The practical takeaway is this. [ ] Every informative image has descriptive alt text. [ ] Alt text is not a filename (screenshot.png) or generic (image, photo). [ ] Complex images (charts, diagrams) have a detailed text description in a block. [ ] Decorative images have empty alt text.

      +

      Alex: Keep the teaching thread moving. This is where Good README vs. bad README becomes real: bad: A single paragraph that says "This is my project. That matters in practice: Run it with npm start." No headings, no license, no description of what the project does.

      +

      Jamie: Let's pause on Learning Cards: Writing Your First README. What should a learner take away from it?

      +

      Alex: Start with Learning Cards: Writing Your First README. There is something to understand, something to try, and something that proves the try worked.

      +

      Alex: The practical takeaway is this. 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: rather than an empty that reads as "image" with no context. Use real Markdown link text (installation guide) instead of bare URLs, so your screen reader announces the destination rather than spelling out a long URL. 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.

      +

      Alex: Keep the teaching thread moving. The reason Community Health Files matters is that community health files tell contributors how your project operates before they write a single line of code. That gives the learner a simple foothold: 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. The interface gets friendlier when it stops being a wall of controls and starts being a set of named places.

      -

      Alex: Keep the teaching thread moving. Start with Lists and tables. There is something to understand, something to try, and something that proves the try worked.

      -

      Alex: The practical takeaway is this. [ ] Lists use the correct type: ordered for sequential steps, unordered for non-sequential items. [ ] Tables have a text description immediately before them. [ ] Tables have descriptive header cells. [ ] Tables have fewer than 7 columns (split wide tables). [ ] Tables are used for data, not layout.

      -

      Jamie: Let's pause on Code. What should a learner take away from it?

      -

      Alex: Start with Code. There is something to understand, something to try, and something that proves the try worked.

      -

      Alex: The practical takeaway is this. [ ] Fenced code blocks have a language identifier. [ ] Inline code used for commands, file names, and values. [ ] Code examples are complete enough to understand without the visual highlighting.

      -

      Alex: Keep the teaching thread moving. Start with GFM features. There is something to understand, something to try, and something that proves the try worked.

      -

      Alex: The practical takeaway is this. [ ] Mermaid diagrams have a text equivalent. [ ] Alert block type matches the urgency of the content. [ ] summary text clearly describes what is inside. [ ] Task list items have descriptive labels. [ ] Complex math expressions have plain English descriptions.

      +

      Jamie: Let's pause on CONTRIBUTING.md. What should a learner take away from it?

      +

      Alex: Start with CONTRIBUTING.md: This file answers the question every newcomer asks: "How do I help?" A good CONTRIBUTING.md covers. The next useful detail is this: A sentence like "We are glad you are here" costs nothing and signals that newcomers are expected, not tolerated.

      +

      Alex: The practical takeaway is this. 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.

      +

      Alex: Keep the teaching thread moving. Here is the plain-English version of CODE OF CONDUCT.md. A code of conduct sets the social contract for your project. Put another way, without one, "acceptable behavior" is whatever each participant assumes it is -- and those assumptions vary widely.

      +

      Alex: The practical takeaway is this. 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.

      +

      Jamie: Let's pause on SECURITY.md. What should a learner take away from it?

      +

      Alex: This is where SECURITY.md becomes real: see also: Appendix F: Git Security and Appendix P: Security Features for security best practices. That matters in practice: If someone discovers a vulnerability in your project, you do not want them to file a public issue.

      +

      Alex: The practical takeaway is this. 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.

      -

      Jamie: Let's pause on General. What should a learner take away from it?

      -

      Alex: Start with General. There is something to understand, something to try, and something that proves the try worked.

      -

      Alex: The practical takeaway is this. [ ] Color is never the only way information is conveyed. [ ] No information is communicated only through visual position or layout. [ ] Content makes sense when read linearly, top to bottom.

      -

      Alex: Keep the teaching thread moving. Start with 30. Common Mistakes and How to Fix Them: This section covers the errors we see most often in workshop participants' Markdown. The next useful detail is this: Each one includes what goes wrong, why it matters, and how to fix it. Think of it like entering a new building: first you find the lobby, then the room, then the door you actually need.

      -

      Jamie: Let's pause on Mistake 1 - Forgetting the blank line between paragraphs. What should a learner take away from it?

      -

      Alex: Here is the plain-English version of Mistake 1 - Forgetting the blank line between paragraphs. What it produces: One merged paragraph. Put another way, fix: Add a blank line between paragraphs.

      +

      Alex: Keep the teaching thread moving. Keep the learner anchored in 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. This is the part to say slowly: Adding a LICENSE file is a one-time step that makes your project genuinely open source. A good GitHub workflow is like a well-run meeting: everyone knows the topic, the next action, and who has the floor.

      +

      Jamie: Let's pause on Finding these files on GitHub. What should a learner take away from it?

      +

      Alex: The reason Finding these files on GitHub matters is that navigate to any repository and click Insights then Community Standards. That gives the learner a simple foothold: GitHub shows a checklist of which community health files are present and links to add any that are missing.

      +

      Alex: Keep the teaching thread moving. Start with Learning Cards: Community Health Files. There is something to understand, something to try, and something that proves the try worked.

      +

      Alex: The practical takeaway is this. 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. 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.

      -

      Alex: Keep the teaching thread moving. This is where Mistake 2 - Skipping heading levels becomes real: why it matters: Screen reader users navigating by heading level will miss entire sections. That matters in practice: Jumping from H1 to H4 means H2 and H3 navigation finds nothing.

      -

      Jamie: Let's pause on Mistake 3 - Generic link text. What should a learner take away from it?

      -

      Alex: Keep the learner anchored in Mistake 3 - Generic link text. Why it matters: A screen reader user scanning the links list hears "here" - with no context about where the link goes. This is the part to say slowly: Fix: For more information, read the GitHub Documentation.

      -

      Alex: Keep the teaching thread moving. The reason Mistake 4 - Missing alt text on images matters is that why it matters: Screen reader users have no idea what the image shows. That gives the learner a simple foothold: some screen readers announce the filename, which is not helpful. The interface gets friendlier when it stops being a wall of controls and starts being a set of named places.

      +

      Jamie: How should someone choose between those options?

      +

      Alex: Here is the plain-English version of When to Use Different Communication Channels. GitHub Discussions are separate from Issues. Put another way, use Discussions for: "What do people think about X approach?" and Issues for: "The X button is broken.".

      +

      Alex: Use the comparison to make a decision, not to recite a table. The main contrasts are: PR comment means Feedback on a specific code change. PR review means Formal verdict (approve/request changes) with consolidated feedback. Discussion means Open-ended conversation, proposals, community Q&A.

      +

      Jamie: Let's pause on Try It: Rewrite One Comment. What should a learner take away from it?

      +

      Alex: This is where Try It: Rewrite One Comment becomes real: time: 2 minutes What you need: Just your brain. That matters in practice: Read this code review comment and rewrite it to be constructive. The workshop is closer to rehearsal than lecture. You hear the move, try the move, and then check what changed.

      +

      Alex: First, what you noticed. Then, why it matters. After that, what you suggest. Finally, why the suggestion helps. It is a checklist, but a meaningful one: every item creates evidence that the next step is safe.

      +

      Jamie: Before we leave Try It: Rewrite One Comment, what is the practical point?

      +

      Alex: First, encouragement. It is like walking a hallway with named doors: read the sign, enter the right room, then confirm where you landed.

      +

      Jamie: Let's pause on Contributing to Open Source. What should a learner take away from it?

      +

      Alex: Keep the learner anchored in Contributing to Open Source. This section was previously Appendix T. This is the part to say slowly: It is now part of the teaching narrative.

      -

      Jamie: Let's pause on Mistake 5 - Using bold instead of headings. What should a learner take away from it?

      -

      Alex: Start with Mistake 5 - Using bold instead of headings: Why it matters: Visually, this looks like a heading. The next useful detail is this: But screen reader users navigating with H will never find it.

      -

      Alex: Keep the teaching thread moving. Here is the plain-English version of Mistake 6 - No description before a table. Why it matters: A screen reader user enters the table without knowing what data it contains. Put another way, they hear "table, 2 columns, 3 rows" but not what the table is about.

      -

      Jamie: Let's pause on Mistake 7 - Code block without a language identifier. What should a learner take away from it?

      -

      Alex: This is where Mistake 7 - Code block without a language identifier becomes real: why it matters: Without the language identifier, sighted users lose the visual benefit of syntax highlighting, and tools that process Markdown lose metadata about the content. That matters in practice: Fix: Always add the language: `python.

      +

      Alex: Keep the teaching thread moving. The reason A Guide for First-Time Contributors matters is that you do not need to be a professional developer to contribute to open source. That gives the learner a simple foothold: documentation, accessibility improvements, and bug reports are among the most valuable contributions any project can receive.

      +

      Jamie: Let's pause on 1. What Is Open Source? What should a learner take away from it?

      +

      Alex: Start with 1. What Is Open Source?: Open source software is software whose source code is publicly available. The next useful detail is this: Anyone can read it, use it, and - in most cases - contribute to it.

      +

      Alex: The practical takeaway is this. 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.

      +

      Alex: Keep the teaching thread moving. Here is the plain-English version of 2. Who Can Contribute? Contributors come from all backgrounds, skill levels, and countries. Put another way, 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. It is like learning a transit route. The names of the stops matter because they tell you whether you are still going the right direction.

      -

      Alex: Keep the teaching thread moving. Keep the learner anchored in Mistake 8 - Inconsistent list markers. Why it matters: While most processors render this as one list, some treat different markers as separate lists, creating unexpected spacing and structure. This is the part to say slowly: Fix: Pick one marker and use it consistently. A good GitHub workflow is like a well-run meeting: everyone knows the topic, the next action, and who has the floor.

      -

      Jamie: Let's pause on Mistake 9 - Mermaid diagram without a text equivalent. What should a learner take away from it?

      -

      Alex: The reason Mistake 9 - Mermaid diagram without a text equivalent matters is that why it matters: Screen reader users cannot access the visual diagram. That gives the learner a simple foothold: they hear nothing or a generic SVG container message.

      -

      Alex: Keep the teaching thread moving. Start with Mistake 10 - Alert block with wrong type: Why it matters: CAUTION (red) implies irreversible harm. The next useful detail is this: A suggestion to try a different approach is, at most, a TIP (green) or a NOTE (blue).

      +

      Jamie: Let's pause on 3. What Makes a Good First Contribution? What should a learner take away from it?

      +

      Alex: Start with 3. What Makes a Good First Contribution? There is something to understand, something to try, and something that proves the try worked.

      +

      Alex: The practical takeaway is this. 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.

      +

      Alex: Keep the teaching thread moving. Keep the learner anchored in Signs a contribution is too large for a first attempt. A well-executed small contribution is far more valuable than a large contribution that cannot be merged because it is out of scope.

      +

      Alex: The practical takeaway is this. 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.

      +

      Jamie: Let's pause on 4. Finding Something to Work On. What should a learner take away from it?

      +

      Alex: The reason 4. Finding Something to Work On matters is that most open source projects label issues that are suitable for new contributors. That gives the learner a simple foothold: how to search: On any GitHub repository, go to Issues → filter by label.

      -

      Jamie: What makes this practice feel low-stakes but still real?

      -

      Alex: Here is the plain-English version of 31. Your First Real Markdown Document - Guided Exercise. In this exercise, you will create a Markdown document that uses most of the elements covered in this guide. Put another way, this is structured as a hands-on exercise that you can do during the workshop.

      -

      Jamie: Let's pause on Setup. What should a learner take away from it?

      -

      Alex: Start with Setup. There is something to understand, something to try, and something that proves the try worked.

      -

      Alex: First, open any repository where you have write access. Then, click New Issue (or create a new.md file in VS Code). After that, you will write a mini profile document about yourself. It is a checklist, but a meaningful one: every item creates evidence that the next step is safe.

      -

      Jamie: Let's pause on Step 1 - Add a heading and introduction. What should a learner take away from it?

      -

      Alex: Keep the learner anchored in Step 1 - Add a heading and introduction. Type the following, replacing the placeholder text with your own information. This is the part to say slowly: Use the Preview tab (or Ctrl+Shift+V in VS Code) to verify the heading renders as a large title.

      -

      Alex: Treat examples as spoken recipes, not decorations. You may hear something like About Me; Hi! My name is [your name] and I am participating in the; GIT Going with GitHub workshop. Read the command, understand what it changes, then run it only when the repository state matches the lesson.

      +

      Alex: Keep the teaching thread moving. Start with Learning Cards: Finding Something to Work On. There is something to understand, something to try, and something that proves the try worked.

      +

      Alex: The practical takeaway is this. 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. 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.

      +

      Jamie: What is the pre-flight check here?

      +

      Alex: Here is the plain-English version of 5. Reading an Issue Before You Start. Before commenting "I'll take this" on an issue, ask yourself. Put another way, 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.

      +

      Alex: The practical takeaway is this. 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.

      +

      Jamie: Let's pause on Tool Cards: Fork, Clone, and Contribute. What should a learner take away from it?

      +

      Alex: Start with Tool Cards: Fork, Clone, and Contribute. There is something to understand, something to try, and something that proves the try worked.

      +

      Alex: First, click Fork on the repository page, then Create fork. Then, edit files directly in your fork's web interface. After that, click Contribute Open pull request to submit back to the original. Finally, fork the repo on github.com first. It is a checklist, but a meaningful one: every item creates evidence that the next step is safe.

      +

      Jamie: Before we leave Tool Cards: Fork, Clone, and Contribute, what is the practical point?

      +

      Alex: First, navigate to your fork and press. to open in the web editor. Then, edit, commit, and create a PR from the Source Control panel. After that, fork on github.com, then clone your fork: Ctrl+Shift+P Git: Clone. Finally, create a branch, make edits, commit and push. It is like walking a hallway with named doors: read the sign, enter the right room, then confirm where you landed.

      +

      Alex: Treat examples as spoken recipes, not decorations. You may hear something like 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. Read the command, understand what it changes, then run it only when the repository state matches the lesson.

      -

      Alex: Keep the teaching thread moving. The reason Step 2 - Add a section with a list matters is that verify the numbered list renders correctly.

      -

      Jamie: Let's pause on Step 3 - Add emphasis and inline code. What should a learner take away from it?

      -

      Alex: Start with Step 3 - Add emphasis and inline code: Check that bold, italic, and inline code all render as expected.

      -

      Alex: Treat examples as spoken recipes, not decorations. You may hear something like My Setup; I use NVDA on Windows with Firefox. My terminal is; PowerShell and I am learning git commands. Read the command, understand what it changes, then run it only when the repository state matches the lesson.

      -

      Jamie: Let's pause on Step 5 - Add a table. What should a learner take away from it?

      -

      Alex: Start with Step 5 - Add a table. There is something to understand, something to try, and something that proves the try worked.

      -

      Alex: Treat examples as spoken recipes, not decorations. You may hear something like Tools I Use; The following table lists the tools I use daily.; Tool Purpose Platform; --- --- ---; NVDA Screen reader Windows; Firefox Web browser Windows; VS Code Code editor Windows. Read the command, understand what it changes, then run it only when the repository state matches the lesson.

      +

      Jamie: Let's pause on The Basic Workflow. What should a learner take away from it?

      +

      Alex: Start with The Basic Workflow. There is something to understand, something to try, and something that proves the try worked.

      +

      Alex: First, fork the repository - creates your own copy on GitHub. Then, clone your fork to your computer (or open a Codespace - see Appendix N). After that, create a branch - name it something descriptive: fix/broken-link-setup-guide. Finally, make your change - edit the file, save, verify. It is like walking a hallway with named doors: read the sign, enter the right room, then confirm where you landed.

      +

      Jamie: Before we leave The Basic Workflow, what is the practical point?

      +

      Alex: First, commit with a clear message - "Fix broken link in setup-guide.md line 34". Then, push to your fork. After that, open a pull request from your branch to the original repository's default branch. Finally, respond to review feedback - maintainers may ask for changes; this is normal and not a rejection. The rhythm is simple: orient, act, verify, then continue.

      +

      Alex: Keep the teaching thread moving. The reason Writing a Good PR Description matters is that example: Fixed a broken link on line 34 of setup-guide.md. That gives the learner a simple foothold: the link pointed to /docs/old-setup which no longer exists. The interface gets friendlier when it stops being a wall of controls and starts being a set of named places.

      +

      Alex: The practical takeaway is this. What did you change? Why was the change needed? How did you verify it works?

      +

      Jamie: How should someone ask for help in a way that gets them unstuck faster?

      +

      Alex: Start with 7. Getting Help: It is always acceptable to ask a question on an issue or pull request. The next useful detail is this: 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.

      +

      Alex: The practical takeaway is this. 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.

      -

      Jamie: Let's pause on Step 7 - Add a collapsible section. What should a learner take away from it?

      -

      Alex: Start with Step 7 - Add a collapsible section. There is something to understand, something to try, and something that proves the try worked.

      -

      Alex: Treat examples as spoken recipes, not decorations. You may hear something like Additional Notes;; My accessibility testing experience; I have been using a screen reader for three years. I have tested; web applications with NVDA and I am learning how to contribute; accessibility bug reports to open source projects. Read the command, understand what it changes, then run it only when the repository state matches the lesson.

      -

      Alex: Keep the teaching thread moving. Keep the learner anchored in You are done when. You just wrote a Markdown document that uses headings, paragraphs, emphasis, inline code, links, blockquotes, tables, task lists, and collapsible sections. This is the part to say slowly: Every one of these skills transfers directly to issues, pull requests, and documentation in this workshop.

      -

      Alex: The practical takeaway is this. Your document renders with a clear heading hierarchy (H1, H2). Bold and italic text render correctly. The numbered list shows sequential numbers. The link is clickable.

      -

      Jamie: Let's pause on Learning Cards: Quick-Reference Card. What should a learner take away from it?

      -

      Alex: Start with Learning Cards: Quick-Reference Card. There is something to understand, something to try, and something that proves the try worked.

      -

      Alex: The practical takeaway is this. This card shows raw Markdown syntax in code blocks -- read each block to hear the exact characters to type. Keep this section bookmarked as a daily reference when writing issues, PRs, and comments. Each code block is labeled by format type (headings, lists, links, etc.) in the heading above it. The card uses large monospace code blocks -- increase zoom and each syntax example stays on one or two lines. Print this section or save it as a separate file for quick side-by-side reference while writing. Syntax characters (,, -, []) are visually distinct in the code font.

      +

      Alex: Keep the teaching thread moving. Here is the plain-English version of 8. After Your Contribution Is Merged. This matters for your GitHub profile. Put another way, 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.

      +

      Alex: The practical takeaway is this. 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.

      +

      Jamie: Let's pause on 9. Building a Contribution Habit. What should a learner take away from it?

      +

      Alex: This is where 9. Building a Contribution Habit becomes real: the hardest part of open source contribution is starting. That matters in practice: 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.

      +

      Alex: Keep the teaching thread moving. Keep the learner anchored in Practical habits. Challenge Time: Complete Challenge 8: The Culture Layer in the Challenge Hub, then advance to Chapter 09: Labels, Milestones and Projects. This is the part to say slowly: Next: Chapter 09: Labels, Milestones, and Projects Back: Chapter 07: Merge Conflicts Related appendices: Appendix M: Accessibility Standards Appendix F: Git Security Appendix O: Branch Protection. A good GitHub workflow is like a well-run meeting: everyone knows the topic, the next action, and who has the floor.

      +

      Alex: The practical takeaway is this. 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.

      -

      Alex: Keep the teaching thread moving. Start with 32. Quick-Reference Card: It shows the raw Markdown for every element covered in this guide. Think of it like entering a new building: first you find the lobby, then the room, then the door you actually need.

      -

      Jamie: Let's pause on HTML in Markdown. What should a learner take away from it?

      -

      Alex: Start with HTML in Markdown. There is something to understand, something to try, and something that proves the try worked.

      -

      Alex: Treat examples as spoken recipes, not decorations. You may hear something like Press Ctrl + C to copy.; H 2 O; x 2; Line one Line two. Read the command, understand what it changes, then run it only when the repository state matches the lesson.

      -

      Alex: Keep the teaching thread moving. This is where Mermaid diagram (with accessible text) becomes real: next: Appendix D: Git Authentication Back: Appendix B: Screen Reader Cheat Sheet Teaching chapter: Chapter 06: Working with Pull Requests.

      +

      Jamie: Let's pause on Organizing Work and Cross-Referencing on GitHub. What should a learner take away from it?

      +

      Alex: The reason Organizing Work and Cross-Referencing on GitHub matters is that labels, milestones, and projects are the organizational layer of GitHub. That gives the learner a simple foothold: they turn a chaotic list of issues into a structured, navigable, prioritized body of work.

      +

      Alex: Keep the teaching thread moving. Start with Workshop Recommendation (Chapter 9): Chapter 9 is a guided triage chapter focused on organization skills.

      +

      Alex: The practical takeaway is this. There are 1 guided challenge. Automation check: none by default. The evidence is structured issue comment in assigned challenge issue. The pattern is inspect, classify, explain.

      +

      Jamie: Let's pause on Chapter 9 Challenge Set. What should a learner take away from it?

      +

      Alex: Start with Chapter 9 Challenge Set. There is something to understand, something to try, and something that proves the try worked.

      +

      Alex: First, post a triage recommendation - read an issue, recommend labels/milestone/project placement, and explain your reasoning. Treat it like a recipe: do not add the next ingredient until the previous one is actually in the bowl.

      -

      Jamie: What should people carry with them after this?

      -

      Alex: Carry the map. Know what page or tool you are in, know which action you are taking, and know what confirmation should follow. If the confirmation is missing, pause. That pause is not wasted time; it is professional judgment.

      -

      Jamie: That is a better way to say it than just follow the steps.

      -

      Alex: Right. Steps matter, but understanding wins. That is episode 22. Next in the series is episode 23, where we keep building the same contributor muscles.

      -
      - +

      Jamie: Let's pause on Challenge 9.1 Step-by-Step: Triage Recommendation Comment. What should a learner take away from it?

      +

      Alex: This is where Challenge 9.1 Step-by-Step: Triage Recommendation Comment becomes real: read the details of a Learning Room issue and post a structured triage recommendation that a maintainer could act on immediately. That matters in practice: Labels and issue states are how we wake up agents. The workshop is closer to rehearsal than lecture. You hear the move, try the move, and then check what changed.

      +

      Alex: The practical takeaway is this. 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?

      +

      Alex: First, open the Issues tab in your Learning Room repository. Then, find any open issue that does not already have labels applied (or pick one your facilitator assigns). After that, read the issue title and full description carefully. Note. Finally, open your assigned Chapter 9 challenge issue (the one titled "Chapter 9.1: Triage Recommendation (@yourname)"). It is a checklist, but a meaningful one: every item creates evidence that the next step is safe.

      +

      Jamie: Before we leave Challenge 9.1 Step-by-Step: Triage Recommendation Comment, what is the practical point?

      +

      Alex: First, scroll to the comment box and post a triage recommendation using this format. Then, if you have write access to the repository, apply the recommended labels and milestone directly on the issue you triaged. After that, activate the Comment button. It is like walking a hallway with named doors: read the sign, enter the right room, then confirm where you landed.

      +

      Jamie: What should the learner prove to themselves after each small task?

      +

      Alex: Keep the learner anchored in Completing Chapter 9: Submit Your Evidence. Your triage recommendation comment is your evidence. This is the part to say slowly: Close your Chapter 9 challenge issue when done.

      +

      Alex: Keep the teaching thread moving. Start with Expected Outcomes. There is something to understand, something to try, and something that proves the try worked.

      +

      Alex: The practical takeaway is this. 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.

      -

      Episode 23: GitHub Gists

      -

      Lightweight code sharing: creating, editing, forking, and embedding Gists.

      -

      Based on: Appendix U: GitHub Gists

      -

      Audio and transcript are being regenerated for this episode.

      -
      -Read Transcript - Episode 23: GitHub Gists - -

      Transcript

      -

      Alex: Welcome to episode 23 of Git Going with GitHub: GitHub Gists. I am Alex, and today we are teaching this topic as a conversation you can carry into the workshop, not as a page you have to memorize.

      -

      Jamie: And I am Jamie. I will keep pulling the lesson back to real learners, real repositories, and the evidence that proves the work happened.

      +

      Jamie: Before we leave If You Get Stuck, what is the practical point?

      +

      Alex: First, not sure which label to pick? Start with just one: documentation, bug, or accessibility. You can always add more. Then, milestone is unclear? Write none and explain why - that is a valid triage decision. After that, project board is unknown? Write Needs Triage - that is the correct default. Finally, 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"). Think of it as a rail line: each stop confirms you are still on the right route before the next one.

      +

      Jamie: What is the teaching move inside If You Get Stuck?

      +

      Alex: First, ask facilitator to review your one-sentence reason before posting. Treat it like a recipe: do not add the next ingredient until the previous one is actually in the bowl.

      +

      Alex: Keep the teaching thread moving. Here is the plain-English version of Learning Moment. Triage is about clarity, not authority. Put another way, you do not need maintainer permissions to help organize work. It is like learning a transit route. The names of the stops matter because they tell you whether you are still going the right direction.

      +

      Jamie: Before we leave Learning Pattern Used in This Chapter, what is the practical point?

      +

      Alex: First, inspect an issue carefully before acting (read before you write). Then, classify work using a consistent vocabulary (labels, milestones). After that, explain your reasoning in writing (one-sentence justification). Finally, build triage instincts that transfer to any open source project. It is a checklist, but a meaningful one: every item creates evidence that the next step is safe.

      -

      Alex: The lesson focus is Lightweight code sharing: creating, editing, forking, and embedding Gists. We will treat every step as a teachable decision, because that is what makes the skill portable.

      -

      Jamie: So we should explain the why clearly enough that the steps make sense when the learner meets them later.

      -

      Alex: That is it. If a listener only has audio right now, they should still get the complete concept and know what evidence would prove success.

      -
      -

      Jamie: Okay, set the room for us. What are we walking into?

      -

      Alex: Start with Forum-Style Conversations Beyond Issues and Pull Requests: GitHub Discussions is a built-in community forum for repositories and organizations. The next useful detail is this: It's where open-ended conversations live - questions, ideas, announcements, polls, and community Q&A - separate from the action-oriented world of issues and pull requests.

      -

      Alex: A solid issue habit is to read the title, the body, and the timeline before acting. You are listening for the requested action, the missing evidence, and the person who needs a response.

      -

      Alex: The next layer is this. Start with Learning Cards: GitHub Discussions. There is something to understand, something to try, and something that proves the try worked.

      -

      Alex: The practical anchors are these. The Discussions tab is in the repository's main navigation bar alongside Code, Issues, and Pull Requests -- press T to navigate tab items or K to find the "Discussions" link. Inside a discussion, replies are article elements -- in NVDA press A to jump between replies; in JAWS use A as well. The reply editor uses the same behavior as issue comments -- enter Focus Mode to type, then press Ctrl+Enter to submit. Discussion categories appear as a sidebar panel on the left or right depending on viewport width -- look for the category list with item counts. Answered discussions in the Q&A category display a green "Answered" badge next to the title, with the accepted answer pinned to the top. Polls show percentage bars next to each option after you vote -- the bars use color fill to indicate proportion.

      -

      Jamie: Can you translate that into plain choices?

      -

      Alex: This is where 1. Discussions vs. Issues: When to Use Which becomes real: not every conversation belongs in an issue. That matters in practice: GitHub Discussions exists for the conversations that don't fit.

      -

      Alex: Use the comparison to make a decision, not to recite a table. The main contrasts are: Use Issues When means Use Discussions When. You found a bug means You have a question about how something works. You want to request a specific feature means You want to brainstorm ideas before filing a feature request.

      -
      -

      Alex: Now bring the learner back to the room. Start with Common Discussions categories you'll encounter. There is something to understand, something to try, and something that proves the try worked.

      -

      Alex: For a learner, the useful signals are these. Q&A - Support questions and answers (one answer can be marked correct). Ideas - Feature brainstorming before a formal feature request. Announcements - Maintainer posts about releases, breaking changes, roadmaps. General - Everything else. Show and Tell - Community members showing what they built.

      -

      Jamie: What is the ordered workflow?

      -

      Alex: The reason From a Repository matters is that if the tab is missing: Discussions is an opt-in feature. That gives the learner a simple foothold: the repository maintainer must enable it in Settings.

      -

      Alex: First, navigate to the repository. Then, there is a Discussions tab in the main navigation (alongside Code, Issues, Pull Requests, Actions, Projects). After that, press T to navigate tab items, or K to navigate links and find "Discussions". Finally, press Enter to open. The rhythm is simple: orient, act, verify, then continue.

      -

      Alex: The useful habit is simple: orient first, act second, verify third. That pause before acting is part of the work.

      -

      Jamie: Give me the sequence, because order matters here.

      -

      Alex: Start with From an Organization: Large organizations can have organization-level Discussions separate from any individual repository. Think of it like entering a new building: first you find the lobby, then the room, then the door you actually need.

      -

      Alex: First, navigate to the organization page. Then, look for the Discussions tab at the organization level. After that, these are community-wide conversations, not repo-specific. Think of it as a rail line: each stop confirms you are still on the right route before the next one.

      -
      -

      Jamie: If I am listening before the workshop starts, what should settle in my mind first?

      -

      Alex: Here is the plain-English version of 3. Discussion Categories. The Discussions home page is organized by category. Put another way, each category is a section with its own heading.

      -

      Alex: This is where the talk moves from concept to action. Start with The side panel (left or right depending on view width) shows. There is something to understand, something to try, and something that proves the try worked.

      -

      Alex: The room should hear these as checkpoints. All categories with item counts. Pin/announcements section at top. Most active discussions. Tags (if the repo uses them).

      -

      Jamie: Turn that into a path someone can follow.

      -

      Alex: Start with 4. Creating a Discussion. There is something to understand, something to try, and something that proves the try worked.

      -

      Alex: These are the details that keep the idea from floating away. Title - Clear and searchable. "How do I use the daily-briefing agent?" not "Help". Body - Use Markdown. Same editor as issues. For Q&A category: phrase the title as a question.

      -

      Alex: First, from the Discussions tab, activate "New discussion" button. Then, select a category (required - affects which fields appear). After that, fill in. Finally, activate "Start discussion". It is like walking a hallway with named doors: read the sign, enter the right room, then confirm where you landed.

      -
      -

      Alex: Before the learner moves on. The reason Screen reader path matters is that before posting a question: Search existing discussions first. That gives the learner a simple foothold: use the search bar at the top of the Discussions page or GitHub's global search with repo:owner/name in:discussions. The interface gets friendlier when it stops being a wall of controls and starts being a set of named places.

      -

      Alex: A solid navigation habit is to prove where you are before activating controls. Headings, landmarks, and the address bar are not trivia; they are your map.

      -

      Jamie: What would you say to someone who is already bracing for this to be too much?

      -

      Alex: Start with Learning Cards: Creating a Discussion. There is something to understand, something to try, and something that proves the try worked.

      -

      Alex: A few details make that real. Tab to the "New discussion" button from the Discussions tab, then press Enter -- the form loads with a category selector first; arrow through categories and press Enter to select. The title field comes after the category selector -- type a clear, searchable title; for Q&A category, phrase it as a question so it reads naturally in search results. The body editor is the same as the issue comment editor -- enter Focus Mode to type, use Markdown formatting, and press Ctrl+Enter to submit the discussion. The category selector appears as a list or grid of labeled options -- each category has a name and description; zoom in to read the descriptions and pick the right one. The title and body fields stack vertically in a single-column layout -- the form is the same width as the main content area, making it easy to scan at high zoom. After creating a discussion, a green success banner appears at the top -- scroll up if you do not see confirmation at your current zoom position.

      -

      Alex: Hold that next to this. Here is the plain-English version of Reading a Discussion. A discussion page is structured similarly to an issue.

      -

      Alex: That shows up in the workshop in a few specific ways. The original post at the top. Replies in chronological order. An "Answered" reply pinned to the top (Q&A category only). A reply editor at the bottom.

      -
      -

      Jamie: What does the learner do first, second, and then after that?

      -

      Alex: Start with Replying to a Discussion. There is something to understand, something to try, and something that proves the try worked.

      -

      Alex: First, navigate to the bottom of the page (or use the "Reply" button on a specific comment). Then, the reply text area behaves identically to issue comments. After that, focus Mode → type your reply. Finally, ctrl+Enter to submit. It is a checklist, but a meaningful one: every item creates evidence that the next step is safe.

      -

      Alex: That connects to another useful point. Keep the learner anchored in Replying to a Specific Comment (Nested Reply). Each comment has a Reply button below it. A good GitHub workflow is like a well-run meeting: everyone knows the topic, the next action, and who has the floor.

      -

      Jamie: What is the one idea that makes the next few steps less mysterious?

      -

      Alex: The reason Upvoting matters is that instead of leaving "+1" comments, use the thumbs-up reaction on the original post or replies. That gives the learner a simple foothold: many maintainers sort discussion responses by upvotes to prioritize most-needed answers.

      -
      -

      Alex: Here is the practical turn. Start with 6. Marking an Answer: In the Q&A category, one reply can be marked as the accepted answer. The next useful detail is this: This is similar to Stack Overflow's "accepted answer" mechanic.

      -

      Jamie: How would you walk the room through that step by step?

      -

      Alex: Here is the plain-English version of To mark an answer (as the discussion author). Why it matters: Marked answers make Q&A discussions into searchable documentation. Put another way, anyone who searches for the same question later immediately sees the correct answer without reading the whole thread.

      -

      Alex: First, navigate to the reply you want to mark as the answer. Then, look for the "Mark as answer" button below the reply. After that, activate it - the reply is pinned to the top and the discussion shows a green "Answered" badge. Treat it like a recipe: do not add the next ingredient until the previous one is actually in the bowl.

      -

      Alex: Keep the thread going. This is where 7. Polls becomes real: some discussion categories support embedded polls. That matters in practice: A poll lets you gather structured vote data from the community. The workshop is closer to rehearsal than lecture. You hear the move, try the move, and then check what changed.

      -
      -

      Jamie: Let's pause on Creating a poll. What should a learner take away from it?

      -

      Alex: Start with Creating a poll. There is something to understand, something to try, and something that proves the try worked.

      -

      Alex: First, when creating a discussion, look for the "Add a poll" option below the body editor. Then, type each poll option (up to 8 options). After that, set poll duration (optional). Finally, submit the discussion - the poll appears inline. It is like walking a hallway with named doors: read the sign, enter the right room, then confirm where you landed.

      -

      Alex: Another way to ground it. The reason Voting in a poll matters is that poll results: After voting, percentages appear next to each option. That gives the learner a simple foothold: screen readers announce the count and percentage per option.

      -

      Jamie: Where do you want a learner to place their attention here?

      -

      Alex: Start with NVDA note. There is something to understand, something to try, and something that proves the try worked.

      -

      Alex: The parts worth keeping in working memory are these. Browse mode (NVDA+Space) to read the discussion. Enter application mode for the reply editor. Discussion replies are elements - NVDA announces "article" as you navigate with H.

      -
      -

      Alex: This is the part worth saying out loud. Start with JAWS note. There is something to understand, something to try, and something that proves the try worked.

      -

      Alex: On the ground, that means a few things. A key navigates elements - useful for jumping between replies. Use Forms Mode for the reply editor.

      -

      Jamie: Give me the version that sounds like an instructor, not a manual.

      -

      Alex: Start with VoiceOver note. There is something to understand, something to try, and something that proves the try worked.

      -

      Alex: Here is what that changes in practice. VO+Right to read through content. VO+Command+L to list all links (useful for navigating many replies quickly). VO+Space on the reply field to enter interaction mode.

      -

      Alex: That matters because of the next idea. Keep the learner anchored in 9. Organization-Level Discussions. Some organizations enable Discussions at the organization level, separate from any repository. This is the part to say slowly: These work identically to repository discussions but span the whole organization.

      -

      Alex: That becomes easier when you listen for these cues. Org-wide announcements. Community introductions ("Introduce yourself" pinned thread). Cross-repo feature brainstorming. Community spotlights and events.

      -
      -

      Jamie: Let's pause on 10. Accessibility Agents: What's Different Here. What should a learner take away from it?

      -

      Alex: The reason 10. Accessibility Agents: What's Different Here matters is that accessibility Agents prompts currently operate on issues, PRs, and code - not directly on Discussions. That gives the learner a simple foothold: if you want to respond to a discussion using Accessibility Agents.

      -

      Alex: First, copy the discussion URL or content. Then, use /issue-reply with the content pasted in: the agent will draft a thoughtful, accessible response. After that, paste the result back into the discussion reply editor. The rhythm is simple: orient, act, verify, then continue.

      -

      Alex: A solid pull request habit is to separate three questions: what changed, why it changed, and what still needs review. That keeps the conversation useful instead of noisy.

      -

      Alex: Keep the teaching thread moving. Start with Shareable Code Snippets and Notes: Gists are a simple way to share code snippets, notes, or small files without creating a full repository. The next useful detail is this: Think of them as lightweight, version-controlled pastebins. Think of it like entering a new building: first you find the lobby, then the room, then the door you actually need.

      -

      Jamie: Let's pause on Learning Cards: GitHub Gists. What should a learner take away from it?

      -

      Alex: Start with Learning Cards: GitHub Gists. There is something to understand, something to try, and something that proves the try worked.

      -

      Alex: The practical takeaway is this. On the Gist creation page at gist.github.com, press D to jump to the main landmark, then F to navigate form fields: Description, Filename, Content, and Visibility buttons. Your Gists page lists each gist as an H2 heading with its description -- press 2 or H to jump between gists. Gists are full Git repositories -- you can clone them with git clone and edit locally using your usual screen reader workflow in VS Code. Gist pages use syntax highlighting matching GitHub's current theme -- switch between light and dark mode for comfortable reading. Public and secret gists look identical on the page; the only difference is the URL visibility -- check the "Create secret gist" or "Create public gist" button label before submitting. The revision history link appears at the top of any gist -- click "Revisions" to see a diff view of every edit.

      +

      Alex: Keep the teaching thread moving. Keep the learner anchored in What Are Labels? Labels are colored tags applied to issues and pull requests. This is the part to say slowly: They communicate at a glance what category, priority, or status an item belongs to.

      +

      Jamie: Let's pause on Navigating to the Labels Page. What should a learner take away from it?

      +

      Alex: The reason Navigating to the Labels Page matters is that go to the Issues tab, then click the Labels link/button (it's in the filter toolbar above the issue list, next to Milestones). That gives the learner a simple foothold: the Labels page shows every label with its colour, name, and description.

      +

      Alex: First, navigate to the Issues tab. Then, press K to find the "Labels" link (near the "Milestones" link in the toolbar). After that, press Enter. Finally, quick Nav K to find the "Labels" link (near the "Milestones" link in the toolbar). The rhythm is simple: orient, act, verify, then continue.

      +

      Jamie: Before we leave Navigating to the Labels Page, what is the practical point?

      +

      Alex: First, vO+Space to activate. Think of it as a rail line: each stop confirms you are still on the right route before the next one.

      +

      Alex: Treat examples as spoken recipes, not decorations. You may hear something like List all labels with descriptions; gh label list; List labels in a specific format; gh label list --json name,description. Read the command, understand what it changes, then run it only when the repository state matches the lesson.

      +

      Jamie: Let's pause on Tool Cards: Apply a Label. What should a learner take away from it?

      +

      Alex: Start with Tool Cards: Apply a Label: github.dev (web editor): Not available -- labels are managed on the issue/PR page, not in the code editor. The next useful detail is this: VS Code Desktop (GitHub Pull Requests extension). Think of it like entering a new building: first you find the lobby, then the room, then the door you actually need.

      +

      Alex: First, open the issue or PR. Then, in the right sidebar, click the gear icon next to Labels. After that, select labels from the dropdown, then click outside to apply. Finally, open the issue in the GitHub sidebar panel. Think of it as a rail line: each stop confirms you are still on the right route before the next one.

      +

      Jamie: Before we leave Tool Cards: Apply a Label, what is the practical point?

      +

      Alex: First, click the label area to add or remove labels. Then, navigate to the sidebar → press H or 3 to find the "Labels" heading. After that, activate the Labels gear/edit button (B until you hear "Labels" button → Enter). Finally, dropdown opens showing all available labels: use ↑/↓ to navigate. Treat it like a recipe: do not add the next ingredient until the previous one is actually in the bowl.

      +

      Alex: Treat examples as spoken recipes, not decorations. You may hear something like gh issue edit 42 --add-label "accessibility,good first issue"; gh pr edit 15 --add-label "documentation". 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. Read the command, understand what it changes, then run it only when the repository state matches the lesson.

      -

      Alex: Keep the teaching thread moving. This is where What Is a Gist? becomes real: a Gist is a Git repository that holds a single file or a small collection of files. That matters in practice: Anyone with the URL can view a secret Gist.

      -

      Alex: The practical takeaway is this. Has its own URL (e.g., gist.github.com/username/a1b2c3d4). Is version-controlled (you can see edit history). Can be public (anyone can see) or secret (only people with the link can see). Supports Markdown rendering.

      -

      Jamie: How should someone choose between those options?

      -

      Alex: Start with When to Use a Gist vs a Repository. There is something to understand, something to try, and something that proves the try worked.

      -

      Alex: Use the comparison to make a decision, not to recite a table. The main contrasts are: Use a Gist When. means Use a Repository When. Sharing a single code snippet means Building a full project. Posting configuration examples means Collaborating with multiple people.

      -

      Jamie: Let's pause on Via GitHub Web Interface. What should a learner take away from it?

      -

      Alex: Start with Via GitHub Web Interface. There is something to understand, something to try, and something that proves the try worked.

      -

      Alex: The practical takeaway is this. Select "Create public gist" for openly shareable content. Select "Create secret gist" for link-only sharing.

      -

      Alex: First, navigate to gist.github.com. Then, gist description: A short title (e.g., "NVDA configuration for GitHub"). After that, filename: Name your file with extension (e.g., nvda-config.txt, script.py, notes.md). Finally, content: Paste or type your code/text. The rhythm is simple: orient, act, verify, then continue.

      -

      Jamie: Before we leave Via GitHub Web Interface, what is the practical point?

      -

      Alex: First, visibility. Then, the Gist is created with a unique URL you can share. Think of it as a rail line: each stop confirms you are still on the right route before the next one.

      +

      Jamie: Let's pause on Filtering Issues by Label. What should a learner take away from it?

      +

      Alex: Here is the plain-English version of Filtering Issues by Label. Screen reader users (NVDA / JAWS - Windows). Put another way, option A - Filter bar: Press F → type is:open label:accessibility → Enter.

      +

      Alex: The practical takeaway is this. 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.

      +

      Alex: Treat examples as spoken recipes, not decorations. You may hear something like 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. Read the command, understand what it changes, then run it only when the repository state matches the lesson.

      +

      Jamie: Let's pause on Creating a New Label. What should a learner take away from it?

      +

      Alex: This is where Creating a New Label becomes real: GitHub CLI (gh) alternative - creating labels. That matters in practice: Accessibility note for color: Labels have color, but they also have a text name and description - the color is supplementary information.

      +

      Alex: First, navigate to Issues → Labels page. Then, tab to "New label" button → Enter. After that, fill in: Label name (F for form field), Color (use the color picker or hex code), Description. Finally, tab to "Create label" button → Enter. It is a checklist, but a meaningful one: every item creates evidence that the next step is safe.

      +

      Alex: Treat examples as spoken recipes, not decorations. You may hear something like 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". Read the command, understand what it changes, then run it only when the repository state matches the lesson.

      +

      Jamie: Let's pause on Learning Cards: Labels. What should a learner take away from it?

      +

      Alex: Start with Learning Cards: Labels. There is something to understand, something to try, and something that proves the try worked.

      +

      Alex: The practical takeaway is this. 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. 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.

      -

      Jamie: Let's pause on Screen reader navigation. What should a learner take away from it?

      -

      Alex: Start with Screen reader navigation. There is something to understand, something to try, and something that proves the try worked.

      -

      Alex: The practical takeaway is this. D to cycle landmarks to "Main". F to navigate form fields. Tab through: Description → Filename → Content textbox → Visibility buttons.

      -

      Jamie: Let's pause on Adding Multiple Files to a Gist. What should a learner take away from it?

      -

      Alex: Here is the plain-English version of Adding Multiple Files to a Gist. You can add multiple files to a single Gist. Put another way, use case: Share related config files together (e.g.,.vscode/settings.json +.vscode/keybindings.json).

      -

      Alex: First, after typing the first filename and content, select "Add file" (button below the editor). Then, repeat for each additional file. After that, create the Gist. Treat it like a recipe: do not add the next ingredient until the previous one is actually in the bowl.

      -

      Jamie: Let's pause on Learning Cards: Creating a Gist. What should a learner take away from it?

      -

      Alex: Start with Learning Cards: Creating a Gist. There is something to understand, something to try, and something that proves the try worked.

      -

      Alex: The practical takeaway is this. On the Gist creation page at gist.github.com, press D to jump to the main landmark, then F to navigate form fields in order: Description, Filename, Content textarea, and visibility buttons. The visibility selector is a split button -- the main button creates a public gist; Tab to the dropdown arrow next to it and press Enter to reveal the "Create secret gist" option. Each filename field has a corresponding content textarea directly below it -- after filling one file, Tab to the "Add file" button to add another file to the same gist. The Gist editor uses the same syntax highlighting as regular GitHub files -- your current theme applies; increase font size in browser zoom for comfortable editing. The split button for public vs. secret visibility is at the bottom of the form -- the two options look nearly identical; read the button label carefully ("Create public gist" vs. "Create secret gist") before clicking. The "Add file" button appears below the first file editor as a small text link -- zoom in to find it; each additional file gets its own filename field and content textarea.

      +

      Alex: Keep the teaching thread moving. The reason What Are Milestones? matters is that milestones group issues and PRs toward a shared goal or deadline. That gives the learner a simple foothold: think of a milestone as a sprint, a version release, or an event (like "Hackathon Day 1 Deliverables"). The interface gets friendlier when it stops being a wall of controls and starts being a set of named places.

      +

      Alex: The practical takeaway is this. A title and optional description. An optional due date. A progress bar (percentage of closed issues vs total).

      +

      Jamie: Let's pause on Navigating to Milestones. What should a learner take away from it?

      +

      Alex: Start with Navigating to Milestones. There is something to understand, something to try, and something that proves the try worked.

      +

      Alex: First, press K to find the "Milestones" link → Enter. Then, you see a list of milestones, each with its title, progress, and due date. Think of it as a rail line: each stop confirms you are still on the right route before the next one.

      +

      Alex: Keep the teaching thread moving. Here is the plain-English version of Reading a milestone. Each milestone is announced as a heading + progress information.

      +

      Alex: The practical takeaway is this. "Hackathon Day 1 Deliverables, 3 of 8 issues closed, due April 20".

      -

      Jamie: Let's pause on Editing a Gist. What should a learner take away from it?

      -

      Alex: Keep the learner anchored in Editing a Gist. Click "Revisions" to see the full edit history. A good GitHub workflow is like a well-run meeting: everyone knows the topic, the next action, and who has the floor.

      -

      Alex: First, navigate to your Gist's URL. Then, select "Edit" (button in the top-right). After that, make your changes. Finally, select "Update public gist" or "Update secret gist". It is like walking a hallway with named doors: read the sign, enter the right room, then confirm where you landed.

      -

      Jamie: Let's pause on Embedding a Gist. What should a learner take away from it?

      -

      Alex: The reason Embedding a Gist matters is that you can embed Gists in web pages, blog posts, or documentation. That gives the learner a simple foothold: GitHub renders it as a formatted code block with syntax highlighting and a link back to the Gist.

      -

      Jamie: What should happen before anyone copies and runs it?

      -

      Alex: Start with Cloning a Gist: Make changes locally, commit, and push just like a normal repo.

      -

      Alex: Treat examples as spoken recipes, not decorations. You may hear something like git clone https://gist.github.com/username/gist-id.git. Read the command, understand what it changes, then run it only when the repository state matches the lesson.

      +

      Jamie: Let's pause on Opening a Milestone. What should a learner take away from it?

      +

      Alex: Start with Opening a Milestone. There is something to understand, something to try, and something that proves the try worked.

      +

      Alex: First, press 3 to navigate milestone titles (they are h3 links). Then, press Enter to open a milestone. After that, the milestone detail page shows all issues and PRs belonging to it. Finally, navigate the list with 3 (issue titles) or I (list items). It is a checklist, but a meaningful one: every item creates evidence that the next step is safe.

      +

      Jamie: Let's pause on Adding an Issue to a Milestone. What should a learner take away from it?

      +

      Alex: Keep the learner anchored in Adding an Issue to a Milestone. From the open issue, find the Milestone section in the right sidebar and click the gear icon. This is the part to say slowly: A dropdown lists available milestones - click one to assign it. A good GitHub workflow is like a well-run meeting: everyone knows the topic, the next action, and who has the floor.

      +

      Alex: First, navigate to the sidebar → "Milestone" heading (H or 3). Then, activate the Milestone gear button. After that, select a milestone from the dropdown (↑/↓ → Enter). Finally, esc to close. It is like walking a hallway with named doors: read the sign, enter the right room, then confirm where you landed.

      +

      Jamie: Before we leave Adding an Issue to a Milestone, what is the practical point?

      +

      Alex: First, quick Nav H or VO+Cmd+H to find the "Milestone" heading in the sidebar. Then, quick Nav B to find and activate the Milestone gear button (VO+Space). After that, select a milestone from the dropdown (VO+Down or arrow keys → VO+Space). The rhythm is simple: orient, act, verify, then continue.

      +

      Alex: Treat examples as spoken recipes, not decorations. You may hear something like 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". gh api repos/{owner}/{repo}/milestones -f title="Hackathon Day 1" -f description="Day 1 deliverables". Read the command, understand what it changes, then run it only when the repository state matches the lesson.

      +

      Jamie: Let's pause on Creating a Milestone. What should a learner take away from it?

      +

      Alex: The reason Creating a Milestone matters is that due date field note: The date field may render as a date picker. That gives the learner a simple foothold: screen readers handle date pickers inconsistently - typing the date is most reliable across browsers.

      +

      Alex: The practical takeaway is this. 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.

      +

      Alex: First, navigate to Milestones page. Then, tab to "New milestone" button → Enter. After that, fill in: Title, Description, Due date (optional). Finally, tab to "Create milestone" → Enter. The rhythm is simple: orient, act, verify, then continue.

      -

      Jamie: Let's pause on Forking a Gist. What should a learner take away from it?

      -

      Alex: Here is the plain-English version of Forking a Gist. You can fork someone else's Gist to create your own copy. Put another way, use case: Someone shares a useful script, you fork it, and customize it for your needs.

      -

      Alex: First, view the Gist. Then, select "Fork" in the top-right. After that, GitHub creates a new Gist under your account. Treat it like a recipe: do not add the next ingredient until the previous one is actually in the bowl.

      -

      Alex: Keep the teaching thread moving. This is where Finding Your Gists becomes real: your Gists page: gist.github.com/your-username. That matters in practice: All your public and secret Gists are listed here. The workshop is closer to rehearsal than lecture. You hear the move, try the move, and then check what changed.

      -

      Alex: The practical takeaway is this. Search your Gists by filename or content. Star Gists you want to reference later. Delete old Gists.

      -

      Jamie: Before we leave Screen reader navigation, what is the practical point?

      -

      Alex: The practical takeaway is this. Each Gist appears as a heading (H2) with its description. Press 2 or H to jump between Gists. Each Gist has links: "Edit," "Delete," "Star," "Embed".

      +

      Alex: Keep the teaching thread moving. Start with Learning Cards: Milestones. There is something to understand, something to try, and something that proves the try worked.

      +

      Alex: The practical takeaway is this. 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. 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.

      +

      Jamie: Let's pause on Cross-References. What should a learner take away from it?

      +

      Alex: Here is the plain-English version of Cross-References. Cross-references are links between issues, PRs, and commits. Put another way, GitHub automatically renders 42 as a link to issue or PR 42.

      +

      Jamie: Let's pause on Typing a Cross-Reference. What should a learner take away from it?

      +

      Alex: This is where Typing a Cross-Reference becomes real: inside any comment or PR description text area (Focus Mode). The workshop is closer to rehearsal than lecture. You hear the move, try the move, and then check what changed.

      +

      Alex: First, type - a live-search dropdown appears. Then, continue typing the issue number or title fragment. After that, use ↓ to navigate the dropdown → Enter to select. Finally, the 42 link is inserted automatically. It is a checklist, but a meaningful one: every item creates evidence that the next step is safe.

      +

      Jamie: Before we leave Typing a Cross-Reference, what is the practical point?

      +

      Alex: First, type @ followed by a username. Then, a dropdown of suggestions appears. After that, ↓ to navigate → Enter to select. It is like walking a hallway with named doors: read the sign, enter the right room, then confirm where you landed.

      -

      Alex: Keep the teaching thread moving. The reason Discovering Public Gists matters is that browse trending Gists: gist.github.com/discover.

      -

      Alex: The practical takeaway is this. Useful scripts and utilities. Configuration examples. Code snippets for learning.

      -

      Jamie: Let's pause on Gist Comments. What should a learner take away from it?

      -

      Alex: Start with Gist Comments: Anyone with a GitHub account can leave a comment, making Gists useful.

      -

      Alex: The practical takeaway is this. Asking questions about a snippet. Suggesting improvements. Discussing implementation details.

      -

      Jamie: Let's pause on To add a comment. What should a learner take away from it?

      -

      Alex: Start with To add a comment. There is something to understand, something to try, and something that proves the try worked.

      -

      Alex: First, scroll to the bottom of the Gist page. Then, f to navigate form fields → Find the comment textarea. After that, type your comment (Markdown supported). Finally, ctrl+Enter or activate "Comment" button. Treat it like a recipe: do not add the next ingredient until the previous one is actually in the bowl.

      +

      Jamie: Let's pause on When the "Closes" Keyword Fires. What should a learner take away from it?

      +

      Alex: Keep the learner anchored in When the "Closes" Keyword Fires. The Closes 42 keyword must appear in. This is the part to say slowly: It does not fire from comments on the PR.

      +

      Alex: The practical takeaway is this. The PR description (body text). A commit message pushed to the default branch.

      +

      Alex: Keep the teaching thread moving. Start with Learning Cards: Cross-References. There is something to understand, something to try, and something that proves the try worked.

      +

      Alex: The practical takeaway is this. 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. 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.

      +

      Jamie: Let's pause on GitHub Projects. What should a learner take away from it?

      +

      Alex: Start with GitHub Projects: See also: Appendix R: Projects Deep Dive covers advanced project board configuration, custom fields, and automation.

      -

      Jamie: Let's pause on Public Gists. What should a learner take away from it?

      -

      Alex: Start with Public Gists. There is something to understand, something to try, and something that proves the try worked.

      -

      Alex: The practical takeaway is this. Appear on your profile. Are indexed by search engines. Anyone can view, fork, and comment.

      -

      Alex: Keep the teaching thread moving. Start with Secret Gists. There is something to understand, something to try, and something that proves the try worked.

      -

      Alex: The practical takeaway is this. Do not appear on your profile. Are not indexed by search engines. Anyone with the URL can view. Still version-controlled and can be starred.

      -

      Jamie: Let's pause on Never put sensitive data in Gists. What should a learner take away from it?

      -

      Alex: The reason Never put sensitive data in Gists matters is that if you accidentally post sensitive data.

      -

      Alex: The practical takeaway is this. Passwords or API keys. Personal identifying information. Proprietary code you don't have permission to share.

      -

      Alex: First, delete the Gist immediately. Then, revoke/regenerate any exposed credentials. After that, remember: Forks and clones may still exist. The rhythm is simple: orient, act, verify, then continue.

      +

      Alex: Keep the teaching thread moving. Here is the plain-English version of What Is a GitHub Project? GitHub Projects is a built-in project management tool. Put another way, it can display issues and PRs from across multiple repositories in one view. It is like learning a transit route. The names of the stops matter because they tell you whether you are still going the right direction.

      +

      Jamie: Let's pause on Finding a Project. What should a learner take away from it?

      +

      Alex: This is where Finding a Project becomes real: from an organization page or repository.

      +

      Alex: First, navigate to the "Projects" tab. Then, press 3 to navigate project titles (they are h3 links). After that, enter to open a project. It is a checklist, but a meaningful one: every item creates evidence that the next step is safe.

      +

      Alex: Keep the teaching thread moving. Keep the learner anchored in What is announced per row. "Add keyboard navigation to carousel Status: In Progress Assignee: username Priority: High".

      -

      Jamie: How do you keep commands from becoming magic words?

      -

      Alex: Start with 1. Sharing Screen Reader Config: Share the Gist URL with other screen reader users. Think of it like entering a new building: first you find the lobby, then the room, then the door you actually need.

      -

      Alex: Treat examples as spoken recipes, not decorations. You may hear something like Filename: nvda-github-config.txt; Content:; NVDA Settings for GitHub Web Navigation; - Browse Mode: Use screen layout (enabled); - Verbosity: Most punctuation; - Rate: 65%; - Keyboard shortcuts: Use standard GitHub shortcuts (G+I, G+P, etc.). Read the command, understand what it changes, then run it only when the repository state matches the lesson.

      -

      Jamie: Let's pause on 2. Quick Markdown Note. What should a learner take away from it?

      -

      Alex: Here is the plain-English version of 2. Quick Markdown Note. Reference it later or share with workshop participants.

      -

      Alex: Keep the teaching thread moving. This is where 3. Code Snippet for a StackOverflow Answer becomes real: when answering questions, paste your code as a Gist and link to it. That matters in practice: Readers get syntax highlighting, version history, and the ability to fork your solution.

      +

      Jamie: Let's pause on Navigating a Project - Board View. What should a learner take away from it?

      +

      Alex: Start with Navigating a Project - Board View. There is something to understand, something to try, and something that proves the try worked.

      +

      Alex: Treat examples as spoken recipes, not decorations. You may hear something like 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. Read the command, understand what it changes, then run it only when the repository state matches the lesson.

      +

      Jamie: Let's pause on Adding an Issue to a Project. What should a learner take away from it?

      +

      Alex: Start with Adding an Issue to a Project. There is something to understand, something to try, and something that proves the try worked.

      +

      Alex: First, navigate to the sidebar "Projects" section (H or 3). Then, activate the Projects gear button. After that, select the project from the dropdown. Finally, activate "Add item" button at the bottom of a column/table. Think of it as a rail line: each stop confirms you are still on the right route before the next one.

      +

      Jamie: Before we leave Adding an Issue to a Project, what is the practical point?

      +

      Alex: First, type to search for existing issues. Then, select the issue → it's added to the project. Treat it like a recipe: do not add the next ingredient until the previous one is actually in the bowl.

      +

      Jamie: Let's pause on Learning Cards: GitHub Projects. What should a learner take away from it?

      +

      Alex: Start with Learning Cards: GitHub Projects. There is something to understand, something to try, and something that proves the try worked.

      +

      Alex: The practical takeaway is this. 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. 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.

      -

      Jamie: What decision is this helping them make?

      -

      Alex: Start with Gists vs GitHub Repositories - Quick Comparison. There is something to understand, something to try, and something that proves the try worked.

      -

      Alex: Use the comparison to make a decision, not to recite a table. The main contrasts are: Comments means Yes (on issues/PRs).

      -

      Jamie: Let's pause on Deleting a Gist. What should a learner take away from it?

      -

      Alex: The reason Deleting a Gist matters is that next: Appendix V: GitHub Mobile Back: Appendix T: Community and Social Teaching chapter: Chapter 08: Open Source Culture. The interface gets friendlier when it stops being a wall of controls and starts being a set of named places.

      -

      Alex: First, navigate to the Gist. Then, select "Edit". After that, select "Delete" (top-right, after Edit button). Finally, confirm deletion. The rhythm is simple: orient, act, verify, then continue.

      +

      Alex: Keep the teaching thread moving. This is where Practical Organization Strategy for the Hackathon becomes real: here is a recommended structure for your Learning Room sandbox project.

      +

      Jamie: Let's pause on Try It: Label and Link. What should a learner take away from it?

      +

      Alex: Keep the learner anchored in Try It: Label and Link. Time: 2 minutes What you need: Browser, signed in to GitHub. This is the part to say slowly: Go to the Learning Room repository and do two things.

      +

      Alex: First, 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. Then, 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. It is like walking a hallway with named doors: read the sign, enter the right room, then confirm where you landed.

      -

      Jamie: What should people carry with them after this?

      -

      Alex: Carry the map. Know what page or tool you are in, know which action you are taking, and know what confirmation should follow. If the confirmation is missing, pause. That pause is not wasted time; it is professional judgment.

      -

      Jamie: That is a better way to say it than just follow the steps.

      -

      Alex: Right. Steps matter, but understanding wins. That is episode 23. Next in the series is episode 24, where we keep building the same contributor muscles.

      +

      Jamie: What is the final checkpoint?

      +

      Alex: You should be able to point to the evidence, explain the action, and describe what you would do next if this were a real open source project. If you can teach the move back, you have learned it.

      +

      Jamie: And if they get stuck?

      +

      Alex: Read the latest message, not the loudest worry. Check the issue, the branch, the pull request, the status check, or the bot comment. Then ask for help with those facts in hand. That is how professionals collaborate.

      -

      Episode 24: GitHub Discussions

      -

      Forum-style conversations, Q&A, polls, and navigation with screen readers.

      -

      Based on: Appendix U: GitHub Discussions

      -

      Audio and transcript are being regenerated for this episode.

      +

      24. Episode 9: Labels, Milestones, and Projects

      +

      Organizing and tracking work with labels, milestones, and GitHub Projects.

      +

      Based on: Chapter 9: Labels, Milestones, and Projects

      + + +

      Download Episode 9 (MP3)

      -Read Transcript - Episode 24: GitHub Discussions +Read Transcript - Episode 9: Labels, Milestones, and Projects

      Transcript

      -

      Alex: Welcome to Git Going with GitHub, episode 24: GitHub Discussions. I am Alex. Today we are going to make GitHub Discussions something you can explain, practice, and recover from when the interface surprises you.

      -

      Jamie: And I am Jamie. I will be the voice of the learner who is willing to ask, what is this for, where am I, and how do I know I did it right?

      +

      Alex: Welcome back to Git Going with GitHub. This is episode 9: Labels, Milestones, and Projects. I am Alex, and today we are turning Labels, Milestones, and Projects from a list of instructions into a working mental model.

      +

      Jamie: And I am Jamie. I will stop us whenever the instructions sound simple on paper but might feel different with a keyboard and screen reader.

      -

      Alex: The big idea today: Forum-style conversations, Q&A, polls, and navigation with screen readers. We will name the concept, explain why it matters, practice the move, and point out the checks that tell you the work is real.

      -

      Jamie: So the episode should work even if someone has not read the chapter yet.

      -

      Alex: Exactly. The transcript has to stand on its own. It can point toward practice, but it should teach the concept right here in the conversation.

      +

      Alex: Organizing and tracking work with labels, milestones, and GitHub Projects. That is the surface description. Underneath it, we are building judgment: where to focus, what to ignore, and how to verify the result.

      +

      Jamie: So we are not using the audio as a shortcut around learning. We are using it to make the learning easier to enter.

      +

      Alex: Yes. A good audio lesson gives someone enough context to try the work with confidence, even before they open the written material.

      Jamie: Okay, set the room for us. What are we walking into?

      -

      Alex: Start with Forum-Style Conversations Beyond Issues and Pull Requests: GitHub Discussions is a built-in community forum for repositories and organizations. The next useful detail is this: It's where open-ended conversations live - questions, ideas, announcements, polls, and community Q&A - separate from the action-oriented world of issues and pull requests.

      -

      Alex: A solid issue habit is to read the title, the body, and the timeline before acting. You are listening for the requested action, the missing evidence, and the person who needs a response.

      -

      Alex: The next layer is this. Start with Learning Cards: GitHub Discussions. There is something to understand, something to try, and something that proves the try worked.

      -

      Alex: The practical anchors are these. The Discussions tab is in the repository's main navigation bar alongside Code, Issues, and Pull Requests -- press T to navigate tab items or K to find the "Discussions" link. Inside a discussion, replies are article elements -- in NVDA press A to jump between replies; in JAWS use A as well. The reply editor uses the same behavior as issue comments -- enter Focus Mode to type, then press Ctrl+Enter to submit. Discussion categories appear as a sidebar panel on the left or right depending on viewport width -- look for the category list with item counts. Answered discussions in the Q&A category display a green "Answered" badge next to the title, with the accepted answer pinned to the top. Polls show percentage bars next to each option after you vote -- the bars use color fill to indicate proportion.

      -

      Jamie: Can you translate that into plain choices?

      -

      Alex: This is where 1. Discussions vs. Issues: When to Use Which becomes real: not every conversation belongs in an issue. That matters in practice: GitHub Discussions exists for the conversations that don't fit.

      -

      Alex: Use the comparison to make a decision, not to recite a table. The main contrasts are: Use Issues When means Use Discussions When. You found a bug means You have a question about how something works. You want to request a specific feature means You want to brainstorm ideas before filing a feature request.

      -
      -

      Alex: Now bring the learner back to the room. Start with Common Discussions categories you'll encounter. There is something to understand, something to try, and something that proves the try worked.

      -

      Alex: For a learner, the useful signals are these. Q&A - Support questions and answers (one answer can be marked correct). Ideas - Feature brainstorming before a formal feature request. Announcements - Maintainer posts about releases, breaking changes, roadmaps. General - Everything else. Show and Tell - Community members showing what they built.

      +

      Alex: Start with Organizing Work and Cross-Referencing on GitHub: Labels, milestones, and projects are the organizational layer of GitHub. The next useful detail is this: They turn a chaotic list of issues into a structured, navigable, prioritized body of work.

      +

      Alex: The next layer is this. Here is the plain-English version of Workshop Recommendation (Chapter 9). Chapter 9 is a guided triage chapter focused on organization skills. It is like learning a transit route. The names of the stops matter because they tell you whether you are still going the right direction.

      +

      Alex: The practical anchors are these. There are 1 guided challenge. Automation check: none by default. The evidence is structured issue comment in assigned challenge issue. The pattern is inspect, classify, explain.

      +

      Jamie: What does the learner do first, second, and then after that?

      +

      Alex: Start with Chapter 9 Challenge Set. There is something to understand, something to try, and something that proves the try worked.

      +

      Alex: First, post a triage recommendation - read an issue, recommend labels/milestone/project placement, and explain your reasoning. It is a checklist, but a meaningful one: every item creates evidence that the next step is safe.

      +
      +

      Jamie: Turn that into a path someone can follow.

      +

      Alex: Keep the learner anchored in Challenge 9.1 Step-by-Step: Triage Recommendation Comment. Read the details of a Learning Room issue and post a structured triage recommendation that a maintainer could act on immediately. This is the part to say slowly: Labels and issue states are how we wake up agents.

      +

      Alex: For a learner, the useful signals are these. 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?

      +

      Alex: First, open the Issues tab in your Learning Room repository. Then, find any open issue that does not already have labels applied (or pick one your facilitator assigns). After that, read the issue title and full description carefully. Note. Finally, open your assigned Chapter 9 challenge issue (the one titled "Chapter 9.1: Triage Recommendation (@yourname)"). It is like walking a hallway with named doors: read the sign, enter the right room, then confirm where you landed.

      Jamie: What is the ordered workflow?

      -

      Alex: The reason From a Repository matters is that if the tab is missing: Discussions is an opt-in feature. That gives the learner a simple foothold: the repository maintainer must enable it in Settings.

      -

      Alex: First, navigate to the repository. Then, there is a Discussions tab in the main navigation (alongside Code, Issues, Pull Requests, Actions, Projects). After that, press T to navigate tab items, or K to navigate links and find "Discussions". Finally, press Enter to open. The rhythm is simple: orient, act, verify, then continue.

      +

      Alex: First, scroll to the comment box and post a triage recommendation using this format. Then, if you have write access to the repository, apply the recommended labels and milestone directly on the issue you triaged. After that, activate the Comment button. The rhythm is simple: orient, act, verify, then continue.

      +

      Jamie: What makes this practice feel low-stakes but still real?

      +

      Alex: The reason Completing Chapter 9: Submit Your Evidence matters is that your triage recommendation comment is your evidence. That gives the learner a simple foothold: close your Chapter 9 challenge issue when done.

      Alex: The useful habit is simple: orient first, act second, verify third. That pause before acting is part of the work.

      -

      Jamie: Give me the sequence, because order matters here.

      -

      Alex: Start with From an Organization: Large organizations can have organization-level Discussions separate from any individual repository. Think of it like entering a new building: first you find the lobby, then the room, then the door you actually need.

      -

      Alex: First, navigate to the organization page. Then, look for the Discussions tab at the organization level. After that, these are community-wide conversations, not repo-specific. Think of it as a rail line: each stop confirms you are still on the right route before the next one.

      +

      Alex: That matters because of the next idea. Start with Expected Outcomes. There is something to understand, something to try, and something that proves the try worked.

      +

      Alex: On the ground, that means a few things. 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.

      -

      Jamie: If I am listening before the workshop starts, what should settle in my mind first?

      -

      Alex: Here is the plain-English version of 3. Discussion Categories. The Discussions home page is organized by category. Put another way, each category is a section with its own heading.

      -

      Alex: This is where the talk moves from concept to action. Start with The side panel (left or right depending on view width) shows. There is something to understand, something to try, and something that proves the try worked.

      -

      Alex: The room should hear these as checkpoints. All categories with item counts. Pin/announcements section at top. Most active discussions. Tags (if the repo uses them).

      -

      Jamie: Turn that into a path someone can follow.

      -

      Alex: Start with 4. Creating a Discussion. There is something to understand, something to try, and something that proves the try worked.

      -

      Alex: These are the details that keep the idea from floating away. Title - Clear and searchable. "How do I use the daily-briefing agent?" not "Help". Body - Use Markdown. Same editor as issues. For Q&A category: phrase the title as a question.

      -

      Alex: First, from the Discussions tab, activate "New discussion" button. Then, select a category (required - affects which fields appear). After that, fill in. Finally, activate "Start discussion". It is like walking a hallway with named doors: read the sign, enter the right room, then confirm where you landed.

      +

      Jamie: How would you walk the room through that step by step?

      +

      Alex: Start with If You Get Stuck. There is something to understand, something to try, and something that proves the try worked.

      +

      Alex: First, not sure which label to pick? Start with just one: documentation, bug, or accessibility. You can always add more. Then, milestone is unclear? Write none and explain why - that is a valid triage decision. After that, project board is unknown? Write Needs Triage - that is the correct default. Finally, 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"). Treat it like a recipe: do not add the next ingredient until the previous one is actually in the bowl.

      +

      Jamie: Give me the sequence, because order matters here.

      +

      Alex: First, ask facilitator to review your one-sentence reason before posting. It is a checklist, but a meaningful one: every item creates evidence that the next step is safe.

      +

      Alex: This is where the talk moves from concept to action. This is where Learning Moment becomes real: triage is about clarity, not authority. That matters in practice: You do not need maintainer permissions to help organize work.

      +

      Jamie: Let's pause on Learning Pattern Used in This Chapter. What should a learner take away from it?

      +

      Alex: Start with Learning Pattern Used in This Chapter. There is something to understand, something to try, and something that proves the try worked.

      +

      Alex: First, inspect an issue carefully before acting (read before you write). Then, classify work using a consistent vocabulary (labels, milestones). After that, explain your reasoning in writing (one-sentence justification). Finally, build triage instincts that transfer to any open source project. It is like walking a hallway with named doors: read the sign, enter the right room, then confirm where you landed.

      -

      Alex: Before the learner moves on. The reason Screen reader path matters is that before posting a question: Search existing discussions first. That gives the learner a simple foothold: use the search bar at the top of the Discussions page or GitHub's global search with repo:owner/name in:discussions. The interface gets friendlier when it stops being a wall of controls and starts being a set of named places.

      -

      Alex: A solid navigation habit is to prove where you are before activating controls. Headings, landmarks, and the address bar are not trivia; they are your map.

      -

      Jamie: What would you say to someone who is already bracing for this to be too much?

      -

      Alex: Start with Learning Cards: Creating a Discussion. There is something to understand, something to try, and something that proves the try worked.

      -

      Alex: A few details make that real. Tab to the "New discussion" button from the Discussions tab, then press Enter -- the form loads with a category selector first; arrow through categories and press Enter to select. The title field comes after the category selector -- type a clear, searchable title; for Q&A category, phrase it as a question so it reads naturally in search results. The body editor is the same as the issue comment editor -- enter Focus Mode to type, use Markdown formatting, and press Ctrl+Enter to submit the discussion. The category selector appears as a list or grid of labeled options -- each category has a name and description; zoom in to read the descriptions and pick the right one. The title and body fields stack vertically in a single-column layout -- the form is the same width as the main content area, making it easy to scan at high zoom. After creating a discussion, a green success banner appears at the top -- scroll up if you do not see confirmation at your current zoom position.

      -

      Alex: Hold that next to this. Here is the plain-English version of Reading a Discussion. A discussion page is structured similarly to an issue.

      -

      Alex: That shows up in the workshop in a few specific ways. The original post at the top. Replies in chronological order. An "Answered" reply pinned to the top (Q&A category only). A reply editor at the bottom.

      +

      Alex: Before the learner moves on. The reason What Are Labels? matters is that labels are colored tags applied to issues and pull requests. That gives the learner a simple foothold: they communicate at a glance what category, priority, or status an item belongs to. The interface gets friendlier when it stops being a wall of controls and starts being a set of named places.

      +

      Alex: A solid project habit is to treat metadata as decision support. Labels, status, assignees, and notifications tell you what kind of attention the work needs.

      +

      Jamie: Let's pause on Navigating to the Labels Page. What should a learner take away from it?

      +

      Alex: Start with Navigating to the Labels Page: 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 next useful detail is this: The Labels page shows every label with its colour, name, and description.

      +

      Alex: First, navigate to the Issues tab. Then, press K to find the "Labels" link (near the "Milestones" link in the toolbar). After that, press Enter. Finally, quick Nav K to find the "Labels" link (near the "Milestones" link in the toolbar). Think of it as a rail line: each stop confirms you are still on the right route before the next one.

      +

      Jamie: Before we leave Navigating to the Labels Page, what is the practical point?

      +

      Alex: First, vO+Space to activate. Treat it like a recipe: do not add the next ingredient until the previous one is actually in the bowl.

      +

      Alex: Treat examples as spoken recipes, not decorations. You may hear something like List all labels with descriptions; gh label list; List labels in a specific format; gh label list --json name,description. Read the command, understand what it changes, then run it only when the repository state matches the lesson.

      +

      Jamie: Let's pause on Tool Cards: Apply a Label. What should a learner take away from it?

      +

      Alex: Here is the plain-English version of Tool Cards: Apply a Label. github.dev (web editor): Not available -- labels are managed on the issue/PR page, not in the code editor. Put another way, VS Code Desktop (GitHub Pull Requests extension).

      +

      Alex: First, open the issue or PR. Then, in the right sidebar, click the gear icon next to Labels. After that, select labels from the dropdown, then click outside to apply. Finally, open the issue in the GitHub sidebar panel. Treat it like a recipe: do not add the next ingredient until the previous one is actually in the bowl.

      +

      Jamie: Before we leave Tool Cards: Apply a Label, what is the practical point?

      +

      Alex: First, click the label area to add or remove labels. Then, navigate to the sidebar → press H or 3 to find the "Labels" heading. After that, activate the Labels gear/edit button (B until you hear "Labels" button → Enter). Finally, dropdown opens showing all available labels: use ↑/↓ to navigate. It is a checklist, but a meaningful one: every item creates evidence that the next step is safe.

      +

      Alex: Treat examples as spoken recipes, not decorations. You may hear something like gh issue edit 42 --add-label "accessibility,good first issue"; gh pr edit 15 --add-label "documentation". 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. Read the command, understand what it changes, then run it only when the repository state matches the lesson.

      -

      Jamie: What does the learner do first, second, and then after that?

      -

      Alex: Start with Replying to a Discussion. There is something to understand, something to try, and something that proves the try worked.

      -

      Alex: First, navigate to the bottom of the page (or use the "Reply" button on a specific comment). Then, the reply text area behaves identically to issue comments. After that, focus Mode → type your reply. Finally, ctrl+Enter to submit. It is a checklist, but a meaningful one: every item creates evidence that the next step is safe.

      -

      Alex: That connects to another useful point. Keep the learner anchored in Replying to a Specific Comment (Nested Reply). Each comment has a Reply button below it. A good GitHub workflow is like a well-run meeting: everyone knows the topic, the next action, and who has the floor.

      +

      Jamie: What should they understand before typing anything?

      +

      Alex: This is where Filtering Issues by Label becomes real: screen reader users (NVDA / JAWS - Windows). That matters in practice: Option A - Filter bar: Press F → type is:open label:accessibility → Enter.

      +

      Alex: That shows up in the workshop in a few specific ways. 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.

      +

      Alex: Treat examples as spoken recipes, not decorations. You may hear something like 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. Read the command, understand what it changes, then run it only when the repository state matches the lesson.

      +

      Alex: A solid issue habit is to read the title, the body, and the timeline before acting. You are listening for the requested action, the missing evidence, and the person who needs a response.

      +

      Jamie: Let's pause on Creating a New Label. What should a learner take away from it?

      +

      Alex: Keep the learner anchored in Creating a New Label. GitHub CLI (gh) alternative - creating labels. This is the part to say slowly: Accessibility note for color: Labels have color, but they also have a text name and description - the color is supplementary information. A good GitHub workflow is like a well-run meeting: everyone knows the topic, the next action, and who has the floor.

      +

      Alex: First, navigate to Issues → Labels page. Then, tab to "New label" button → Enter. After that, fill in: Label name (F for form field), Color (use the color picker or hex code), Description. Finally, tab to "Create label" button → Enter. It is like walking a hallway with named doors: read the sign, enter the right room, then confirm where you landed.

      +

      Alex: Treat examples as spoken recipes, not decorations. You may hear something like 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". Read the command, understand what it changes, then run it only when the repository state matches the lesson.

      Jamie: What is the one idea that makes the next few steps less mysterious?

      -

      Alex: The reason Upvoting matters is that instead of leaving "+1" comments, use the thumbs-up reaction on the original post or replies. That gives the learner a simple foothold: many maintainers sort discussion responses by upvotes to prioritize most-needed answers.

      +

      Alex: Start with Learning Cards: Labels. There is something to understand, something to try, and something that proves the try worked.

      +

      Alex: The parts worth keeping in working memory are these. 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. 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.

      -

      Alex: Here is the practical turn. Start with 6. Marking an Answer: In the Q&A category, one reply can be marked as the accepted answer. The next useful detail is this: This is similar to Stack Overflow's "accepted answer" mechanic.

      -

      Jamie: How would you walk the room through that step by step?

      -

      Alex: Here is the plain-English version of To mark an answer (as the discussion author). Why it matters: Marked answers make Q&A discussions into searchable documentation. Put another way, anyone who searches for the same question later immediately sees the correct answer without reading the whole thread.

      -

      Alex: First, navigate to the reply you want to mark as the answer. Then, look for the "Mark as answer" button below the reply. After that, activate it - the reply is pinned to the top and the discussion shows a green "Answered" badge. Treat it like a recipe: do not add the next ingredient until the previous one is actually in the bowl.

      -

      Alex: Keep the thread going. This is where 7. Polls becomes real: some discussion categories support embedded polls. That matters in practice: A poll lets you gather structured vote data from the community. The workshop is closer to rehearsal than lecture. You hear the move, try the move, and then check what changed.

      +

      Alex: Here is the practical turn. Start with What Are Milestones?: Milestones group issues and PRs toward a shared goal or deadline. The next useful detail is this: Think of a milestone as a sprint, a version release, or an event (like "Hackathon Day 1 Deliverables").

      +

      Alex: Here is what that changes in practice. A title and optional description. An optional due date. A progress bar (percentage of closed issues vs total).

      +

      Jamie: Let's pause on Navigating to Milestones. What should a learner take away from it?

      +

      Alex: Start with Navigating to Milestones. There is something to understand, something to try, and something that proves the try worked.

      +

      Alex: First, press K to find the "Milestones" link → Enter. Then, you see a list of milestones, each with its title, progress, and due date. Treat it like a recipe: do not add the next ingredient until the previous one is actually in the bowl.

      +

      Alex: Keep the thread going. This is where Reading a milestone becomes real: each milestone is announced as a heading + progress information. The workshop is closer to rehearsal than lecture. You hear the move, try the move, and then check what changed.

      +

      Alex: The room should hear these as checkpoints. "Hackathon Day 1 Deliverables, 3 of 8 issues closed, due April 20".

      -

      Jamie: Let's pause on Creating a poll. What should a learner take away from it?

      -

      Alex: Start with Creating a poll. There is something to understand, something to try, and something that proves the try worked.

      -

      Alex: First, when creating a discussion, look for the "Add a poll" option below the body editor. Then, type each poll option (up to 8 options). After that, set poll duration (optional). Finally, submit the discussion - the poll appears inline. It is like walking a hallway with named doors: read the sign, enter the right room, then confirm where you landed.

      -

      Alex: Another way to ground it. The reason Voting in a poll matters is that poll results: After voting, percentages appear next to each option. That gives the learner a simple foothold: screen readers announce the count and percentage per option.

      -

      Jamie: Where do you want a learner to place their attention here?

      -

      Alex: Start with NVDA note. There is something to understand, something to try, and something that proves the try worked.

      -

      Alex: The parts worth keeping in working memory are these. Browse mode (NVDA+Space) to read the discussion. Enter application mode for the reply editor. Discussion replies are elements - NVDA announces "article" as you navigate with H.

      +

      Jamie: Let's pause on Opening a Milestone. What should a learner take away from it?

      +

      Alex: Start with Opening a Milestone. There is something to understand, something to try, and something that proves the try worked.

      +

      Alex: First, press 3 to navigate milestone titles (they are h3 links). Then, press Enter to open a milestone. After that, the milestone detail page shows all issues and PRs belonging to it. Finally, navigate the list with 3 (issue titles) or I (list items). It is like walking a hallway with named doors: read the sign, enter the right room, then confirm where you landed.

      +

      Jamie: Let's pause on Adding an Issue to a Milestone. What should a learner take away from it?

      +

      Alex: The reason Adding an Issue to a Milestone matters is that from the open issue, find the Milestone section in the right sidebar and click the gear icon. That gives the learner a simple foothold: a dropdown lists available milestones - click one to assign it.

      +

      Alex: First, navigate to the sidebar → "Milestone" heading (H or 3). Then, activate the Milestone gear button. After that, select a milestone from the dropdown (↑/↓ → Enter). Finally, esc to close. The rhythm is simple: orient, act, verify, then continue.

      +

      Jamie: Before we leave Adding an Issue to a Milestone, what is the practical point?

      +

      Alex: First, quick Nav H or VO+Cmd+H to find the "Milestone" heading in the sidebar. Then, quick Nav B to find and activate the Milestone gear button (VO+Space). After that, select a milestone from the dropdown (VO+Down or arrow keys → VO+Space). Think of it as a rail line: each stop confirms you are still on the right route before the next one.

      +

      Alex: Treat examples as spoken recipes, not decorations. You may hear something like 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". gh api repos/{owner}/{repo}/milestones -f title="Hackathon Day 1" -f description="Day 1 deliverables". Read the command, understand what it changes, then run it only when the repository state matches the lesson.

      +

      Jamie: Let's pause on Creating a Milestone. What should a learner take away from it?

      +

      Alex: Start with Creating a Milestone: Due date field note: The date field may render as a date picker. The next useful detail is this: Screen readers handle date pickers inconsistently - typing the date is most reliable across browsers.

      +

      Alex: A few details make that real. 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.

      +

      Alex: First, navigate to Milestones page. Then, tab to "New milestone" button → Enter. After that, fill in: Title, Description, Due date (optional). Finally, tab to "Create milestone" → Enter. Think of it as a rail line: each stop confirms you are still on the right route before the next one.

      -

      Alex: This is the part worth saying out loud. Start with JAWS note. There is something to understand, something to try, and something that proves the try worked.

      -

      Alex: On the ground, that means a few things. A key navigates elements - useful for jumping between replies. Use Forms Mode for the reply editor.

      -

      Jamie: Give me the version that sounds like an instructor, not a manual.

      -

      Alex: Start with VoiceOver note. There is something to understand, something to try, and something that proves the try worked.

      -

      Alex: Here is what that changes in practice. VO+Right to read through content. VO+Command+L to list all links (useful for navigating many replies quickly). VO+Space on the reply field to enter interaction mode.

      -

      Alex: That matters because of the next idea. Keep the learner anchored in 9. Organization-Level Discussions. Some organizations enable Discussions at the organization level, separate from any repository. This is the part to say slowly: These work identically to repository discussions but span the whole organization.

      -

      Alex: That becomes easier when you listen for these cues. Org-wide announcements. Community introductions ("Introduce yourself" pinned thread). Cross-repo feature brainstorming. Community spotlights and events.

      +

      Alex: This is the part worth saying out loud. Start with Learning Cards: Milestones. There is something to understand, something to try, and something that proves the try worked.

      +

      Alex: These are the details that keep the idea from floating away. 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. 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.

      +

      Jamie: What would you say to someone who is already bracing for this to be too much?

      +

      Alex: This is where Cross-References becomes real: cross-references are links between issues, PRs, and commits. That matters in practice: GitHub automatically renders 42 as a link to issue or PR 42.

      +

      Jamie: Let's pause on Typing a Cross-Reference. What should a learner take away from it?

      +

      Alex: Keep the learner anchored in Typing a Cross-Reference. Inside any comment or PR description text area (Focus Mode).

      +

      Alex: First, type - a live-search dropdown appears. Then, continue typing the issue number or title fragment. After that, use ↓ to navigate the dropdown → Enter to select. Finally, the 42 link is inserted automatically. It is like walking a hallway with named doors: read the sign, enter the right room, then confirm where you landed.

      +

      Jamie: Before we leave Typing a Cross-Reference, what is the practical point?

      +

      Alex: First, type @ followed by a username. Then, a dropdown of suggestions appears. After that, ↓ to navigate → Enter to select. The rhythm is simple: orient, act, verify, then continue.

      -

      Jamie: Let's pause on 10. Accessibility Agents: What's Different Here. What should a learner take away from it?

      -

      Alex: The reason 10. Accessibility Agents: What's Different Here matters is that accessibility Agents prompts currently operate on issues, PRs, and code - not directly on Discussions. That gives the learner a simple foothold: if you want to respond to a discussion using Accessibility Agents.

      -

      Alex: First, copy the discussion URL or content. Then, use /issue-reply with the content pasted in: the agent will draft a thoughtful, accessible response. After that, paste the result back into the discussion reply editor. The rhythm is simple: orient, act, verify, then continue.

      +

      Jamie: If I am listening before the workshop starts, what should settle in my mind first?

      +

      Alex: The reason When the "Closes" Keyword Fires matters is that the Closes 42 keyword must appear in. That gives the learner a simple foothold: it does not fire from comments on the PR.

      +

      Alex: That becomes easier when you listen for these cues. The PR description (body text). A commit message pushed to the default branch.

      +

      Alex: Now bring the learner back to the room. Start with Learning Cards: Cross-References. There is something to understand, something to try, and something that proves the try worked.

      +

      Alex: The practical takeaway is this. 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. 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.

      +

      Jamie: Where do you want a learner to place their attention here?

      +

      Alex: Here is the plain-English version of GitHub Projects. See also: Appendix R: Projects Deep Dive covers advanced project board configuration, custom fields, and automation.

      Alex: A solid pull request habit is to separate three questions: what changed, why it changed, and what still needs review. That keeps the conversation useful instead of noisy.

      -

      Alex: Keep the teaching thread moving. Start with Shareable Code Snippets and Notes: Gists are a simple way to share code snippets, notes, or small files without creating a full repository. The next useful detail is this: Think of them as lightweight, version-controlled pastebins. Think of it like entering a new building: first you find the lobby, then the room, then the door you actually need.

      -

      Jamie: Let's pause on Learning Cards: GitHub Gists. What should a learner take away from it?

      -

      Alex: Start with Learning Cards: GitHub Gists. There is something to understand, something to try, and something that proves the try worked.

      -

      Alex: The practical takeaway is this. On the Gist creation page at gist.github.com, press D to jump to the main landmark, then F to navigate form fields: Description, Filename, Content, and Visibility buttons. Your Gists page lists each gist as an H2 heading with its description -- press 2 or H to jump between gists. Gists are full Git repositories -- you can clone them with git clone and edit locally using your usual screen reader workflow in VS Code. Gist pages use syntax highlighting matching GitHub's current theme -- switch between light and dark mode for comfortable reading. Public and secret gists look identical on the page; the only difference is the URL visibility -- check the "Create secret gist" or "Create public gist" button label before submitting. The revision history link appears at the top of any gist -- click "Revisions" to see a diff view of every edit.

      -
      -

      Alex: Keep the teaching thread moving. This is where What Is a Gist? becomes real: a Gist is a Git repository that holds a single file or a small collection of files. That matters in practice: Anyone with the URL can view a secret Gist.

      -

      Alex: The practical takeaway is this. Has its own URL (e.g., gist.github.com/username/a1b2c3d4). Is version-controlled (you can see edit history). Can be public (anyone can see) or secret (only people with the link can see). Supports Markdown rendering.

      -

      Jamie: How should someone choose between those options?

      -

      Alex: Start with When to Use a Gist vs a Repository. There is something to understand, something to try, and something that proves the try worked.

      -

      Alex: Use the comparison to make a decision, not to recite a table. The main contrasts are: Use a Gist When. means Use a Repository When. Sharing a single code snippet means Building a full project. Posting configuration examples means Collaborating with multiple people.

      -

      Jamie: Let's pause on Via GitHub Web Interface. What should a learner take away from it?

      -

      Alex: Start with Via GitHub Web Interface. There is something to understand, something to try, and something that proves the try worked.

      -

      Alex: The practical takeaway is this. Select "Create public gist" for openly shareable content. Select "Create secret gist" for link-only sharing.

      -

      Alex: First, navigate to gist.github.com. Then, gist description: A short title (e.g., "NVDA configuration for GitHub"). After that, filename: Name your file with extension (e.g., nvda-config.txt, script.py, notes.md). Finally, content: Paste or type your code/text. The rhythm is simple: orient, act, verify, then continue.

      -

      Jamie: Before we leave Via GitHub Web Interface, what is the practical point?

      -

      Alex: First, visibility. Then, the Gist is created with a unique URL you can share. Think of it as a rail line: each stop confirms you are still on the right route before the next one.

      -
      -

      Jamie: Let's pause on Screen reader navigation. What should a learner take away from it?

      -

      Alex: Start with Screen reader navigation. There is something to understand, something to try, and something that proves the try worked.

      -

      Alex: The practical takeaway is this. D to cycle landmarks to "Main". F to navigate form fields. Tab through: Description → Filename → Content textbox → Visibility buttons.

      -

      Jamie: Let's pause on Adding Multiple Files to a Gist. What should a learner take away from it?

      -

      Alex: Here is the plain-English version of Adding Multiple Files to a Gist. You can add multiple files to a single Gist. Put another way, use case: Share related config files together (e.g.,.vscode/settings.json +.vscode/keybindings.json).

      -

      Alex: First, after typing the first filename and content, select "Add file" (button below the editor). Then, repeat for each additional file. After that, create the Gist. Treat it like a recipe: do not add the next ingredient until the previous one is actually in the bowl.

      -

      Jamie: Let's pause on Learning Cards: Creating a Gist. What should a learner take away from it?

      -

      Alex: Start with Learning Cards: Creating a Gist. There is something to understand, something to try, and something that proves the try worked.

      -

      Alex: The practical takeaway is this. On the Gist creation page at gist.github.com, press D to jump to the main landmark, then F to navigate form fields in order: Description, Filename, Content textarea, and visibility buttons. The visibility selector is a split button -- the main button creates a public gist; Tab to the dropdown arrow next to it and press Enter to reveal the "Create secret gist" option. Each filename field has a corresponding content textarea directly below it -- after filling one file, Tab to the "Add file" button to add another file to the same gist. The Gist editor uses the same syntax highlighting as regular GitHub files -- your current theme applies; increase font size in browser zoom for comfortable editing. The split button for public vs. secret visibility is at the bottom of the form -- the two options look nearly identical; read the button label carefully ("Create public gist" vs. "Create secret gist") before clicking. The "Add file" button appears below the first file editor as a small text link -- zoom in to find it; each additional file gets its own filename field and content textarea.

      -

      Jamie: Let's pause on Editing a Gist. What should a learner take away from it?

      -

      Alex: Keep the learner anchored in Editing a Gist. Click "Revisions" to see the full edit history. A good GitHub workflow is like a well-run meeting: everyone knows the topic, the next action, and who has the floor.

      -

      Alex: First, navigate to your Gist's URL. Then, select "Edit" (button in the top-right). After that, make your changes. Finally, select "Update public gist" or "Update secret gist". It is like walking a hallway with named doors: read the sign, enter the right room, then confirm where you landed.

      -

      Jamie: Let's pause on Embedding a Gist. What should a learner take away from it?

      -

      Alex: The reason Embedding a Gist matters is that you can embed Gists in web pages, blog posts, or documentation. That gives the learner a simple foothold: GitHub renders it as a formatted code block with syntax highlighting and a link back to the Gist.

      -

      Jamie: What should happen before anyone copies and runs it?

      -

      Alex: Start with Cloning a Gist: Make changes locally, commit, and push just like a normal repo.

      -

      Alex: Treat examples as spoken recipes, not decorations. You may hear something like git clone https://gist.github.com/username/gist-id.git. Read the command, understand what it changes, then run it only when the repository state matches the lesson.

      -
      -

      Jamie: Let's pause on Forking a Gist. What should a learner take away from it?

      -

      Alex: Here is the plain-English version of Forking a Gist. You can fork someone else's Gist to create your own copy. Put another way, use case: Someone shares a useful script, you fork it, and customize it for your needs.

      -

      Alex: First, view the Gist. Then, select "Fork" in the top-right. After that, GitHub creates a new Gist under your account. Treat it like a recipe: do not add the next ingredient until the previous one is actually in the bowl.

      -

      Alex: Keep the teaching thread moving. This is where Finding Your Gists becomes real: your Gists page: gist.github.com/your-username. That matters in practice: All your public and secret Gists are listed here. The workshop is closer to rehearsal than lecture. You hear the move, try the move, and then check what changed.

      -

      Alex: The practical takeaway is this. Search your Gists by filename or content. Star Gists you want to reference later. Delete old Gists.

      -

      Jamie: Before we leave Screen reader navigation, what is the practical point?

      -

      Alex: The practical takeaway is this. Each Gist appears as a heading (H2) with its description. Press 2 or H to jump between Gists. Each Gist has links: "Edit," "Delete," "Star," "Embed".

      -
      -

      Alex: Keep the teaching thread moving. The reason Discovering Public Gists matters is that browse trending Gists: gist.github.com/discover.

      -

      Alex: The practical takeaway is this. Useful scripts and utilities. Configuration examples. Code snippets for learning.

      -

      Jamie: Let's pause on Gist Comments. What should a learner take away from it?

      -

      Alex: Start with Gist Comments: Anyone with a GitHub account can leave a comment, making Gists useful.

      -

      Alex: The practical takeaway is this. Asking questions about a snippet. Suggesting improvements. Discussing implementation details.

      -

      Jamie: Let's pause on To add a comment. What should a learner take away from it?

      -

      Alex: Start with To add a comment. There is something to understand, something to try, and something that proves the try worked.

      -

      Alex: First, scroll to the bottom of the Gist page. Then, f to navigate form fields → Find the comment textarea. After that, type your comment (Markdown supported). Finally, ctrl+Enter or activate "Comment" button. Treat it like a recipe: do not add the next ingredient until the previous one is actually in the bowl.

      -
      -

      Jamie: Let's pause on Public Gists. What should a learner take away from it?

      -

      Alex: Start with Public Gists. There is something to understand, something to try, and something that proves the try worked.

      -

      Alex: The practical takeaway is this. Appear on your profile. Are indexed by search engines. Anyone can view, fork, and comment.

      -

      Alex: Keep the teaching thread moving. Start with Secret Gists. There is something to understand, something to try, and something that proves the try worked.

      -

      Alex: The practical takeaway is this. Do not appear on your profile. Are not indexed by search engines. Anyone with the URL can view. Still version-controlled and can be starred.

      -

      Jamie: Let's pause on Never put sensitive data in Gists. What should a learner take away from it?

      -

      Alex: The reason Never put sensitive data in Gists matters is that if you accidentally post sensitive data.

      -

      Alex: The practical takeaway is this. Passwords or API keys. Personal identifying information. Proprietary code you don't have permission to share.

      -

      Alex: First, delete the Gist immediately. Then, revoke/regenerate any exposed credentials. After that, remember: Forks and clones may still exist. The rhythm is simple: orient, act, verify, then continue.

      +

      Alex: Another way to ground it. This is where What Is a GitHub Project? becomes real: GitHub Projects is a built-in project management tool. That matters in practice: It can display issues and PRs from across multiple repositories in one view.

      +

      Jamie: Let's pause on Finding a Project. What should a learner take away from it?

      +

      Alex: Keep the learner anchored in Finding a Project. From an organization page or repository.

      +

      Alex: First, navigate to the "Projects" tab. Then, press 3 to navigate project titles (they are h3 links). After that, enter to open a project. It is like walking a hallway with named doors: read the sign, enter the right room, then confirm where you landed.

      +

      Alex: Hold that next to this. The reason What is announced per row matters is that "Add keyboard navigation to carousel Status: In Progress Assignee: username Priority: High". The interface gets friendlier when it stops being a wall of controls and starts being a set of named places.

      -

      Jamie: How do you keep commands from becoming magic words?

      -

      Alex: Start with 1. Sharing Screen Reader Config: Share the Gist URL with other screen reader users. Think of it like entering a new building: first you find the lobby, then the room, then the door you actually need.

      -

      Alex: Treat examples as spoken recipes, not decorations. You may hear something like Filename: nvda-github-config.txt; Content:; NVDA Settings for GitHub Web Navigation; - Browse Mode: Use screen layout (enabled); - Verbosity: Most punctuation; - Rate: 65%; - Keyboard shortcuts: Use standard GitHub shortcuts (G+I, G+P, etc.). Read the command, understand what it changes, then run it only when the repository state matches the lesson.

      -

      Jamie: Let's pause on 2. Quick Markdown Note. What should a learner take away from it?

      -

      Alex: Here is the plain-English version of 2. Quick Markdown Note. Reference it later or share with workshop participants.

      -

      Alex: Keep the teaching thread moving. This is where 3. Code Snippet for a StackOverflow Answer becomes real: when answering questions, paste your code as a Gist and link to it. That matters in practice: Readers get syntax highlighting, version history, and the ability to fork your solution.

      +

      Jamie: What is the safe way to learn from that example?

      +

      Alex: Start with Navigating a Project - Board View. There is something to understand, something to try, and something that proves the try worked.

      +

      Alex: Treat examples as spoken recipes, not decorations. You may hear something like 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. Read the command, understand what it changes, then run it only when the repository state matches the lesson.

      +

      Jamie: Let's pause on Adding an Issue to a Project. What should a learner take away from it?

      +

      Alex: Start with Adding an Issue to a Project. There is something to understand, something to try, and something that proves the try worked.

      +

      Alex: First, navigate to the sidebar "Projects" section (H or 3). Then, activate the Projects gear button. After that, select the project from the dropdown. Finally, activate "Add item" button at the bottom of a column/table. Treat it like a recipe: do not add the next ingredient until the previous one is actually in the bowl.

      +

      Jamie: Before we leave Adding an Issue to a Project, what is the practical point?

      +

      Alex: First, type to search for existing issues. Then, select the issue → it's added to the project. It is a checklist, but a meaningful one: every item creates evidence that the next step is safe.

      +

      Jamie: Give me the version that sounds like an instructor, not a manual.

      +

      Alex: Start with Learning Cards: GitHub Projects. There is something to understand, something to try, and something that proves the try worked.

      +

      Alex: The practical takeaway is this. 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. 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.

      -

      Jamie: What decision is this helping them make?

      -

      Alex: Start with Gists vs GitHub Repositories - Quick Comparison. There is something to understand, something to try, and something that proves the try worked.

      -

      Alex: Use the comparison to make a decision, not to recite a table. The main contrasts are: Comments means Yes (on issues/PRs).

      -

      Jamie: Let's pause on Deleting a Gist. What should a learner take away from it?

      -

      Alex: The reason Deleting a Gist matters is that next: Appendix V: GitHub Mobile Back: Appendix T: Community and Social Teaching chapter: Chapter 08: Open Source Culture. The interface gets friendlier when it stops being a wall of controls and starts being a set of named places.

      -

      Alex: First, navigate to the Gist. Then, select "Edit". After that, select "Delete" (top-right, after Edit button). Finally, confirm deletion. The rhythm is simple: orient, act, verify, then continue.

      +

      Alex: That connects to another useful point. Keep the learner anchored in Practical Organization Strategy for the Hackathon. Here is a recommended structure for your Learning Room sandbox project. A good GitHub workflow is like a well-run meeting: everyone knows the topic, the next action, and who has the floor.

      +

      Jamie: Let's pause on Try It: Label and Link. What should a learner take away from it?

      +

      Alex: The reason Try It: Label and Link matters is that time: 2 minutes What you need: Browser, signed in to GitHub. That gives the learner a simple foothold: go to the Learning Room repository and do two things.

      +

      Alex: First, 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. Then, 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. The rhythm is simple: orient, act, verify, then continue.

      Jamie: What should people carry with them after this?

      Alex: Carry the map. Know what page or tool you are in, know which action you are taking, and know what confirmation should follow. If the confirmation is missing, pause. That pause is not wasted time; it is professional judgment.

      Jamie: That is a better way to say it than just follow the steps.

      -

      Alex: Right. Steps matter, but understanding wins. That is episode 24. Next in the series is episode 25, where we keep building the same contributor muscles.

      +

      Alex: Right. Steps matter, but understanding wins. That is episode 9. Next in the series is episode 10, where we keep building the same contributor muscles.

      -

      Episode 25: Releases, Tags, and Insights

      -

      Semantic versioning, GitHub Releases, and repository analytics.

      -

      Based on: Appendix S: Releases, Tags, and Insights

      +

      25. Episode 26: GitHub Projects Deep Dive

      +

      Project boards, table and roadmap views, custom fields, cross-repo management.

      +

      Based on: Appendix R: GitHub Projects Deep Dive

      Audio and transcript are being regenerated for this episode.

      -Read Transcript - Episode 25: Releases, Tags, and Insights +Read Transcript - Episode 26: GitHub Projects Deep Dive

      Transcript

      -

      Alex: Welcome back to Git Going with GitHub. This is episode 25: Releases, Tags, and Insights. I am Alex, and today we are turning Releases, Tags, and Insights from a list of instructions into a working mental model.

      -

      Jamie: And I am Jamie. I will stop us whenever the instructions sound simple on paper but might feel different with a keyboard and screen reader.

      +

      Alex: This is Git Going with GitHub, episode 26: GitHub Projects Deep Dive. I am Alex. By the end of this episode, GitHub Projects Deep Dive should feel less like a wall of GitHub words and more like a set of moves you can trust.

      +

      Jamie: And I am Jamie. I am here for the practical questions: what should I listen for, what can go wrong, and what is the next calm move?

      -

      Alex: Semantic versioning, GitHub Releases, and repository analytics. That is the surface description. Underneath it, we are building judgment: where to focus, what to ignore, and how to verify the result.

      -

      Jamie: So we are not using the audio as a shortcut around learning. We are using it to make the learning easier to enter.

      -

      Alex: Yes. A good audio lesson gives someone enough context to try the work with confidence, even before they open the written material.

      -
      -

      Jamie: Okay, set the room for us. What are we walking into?

      -

      Alex: Start with Understanding Versioned Releases and Repository Activity: Two things help you understand a repository's health and your place in it: releases (the versioned snapshots your contributions land in) and insights (the activity metrics that show how a project grows).

      -

      Jamie: How would you walk the room through that step by step?

      -

      Alex: Start with Releases and Tags. There is something to understand, something to try, and something that proves the try worked.

      -

      Alex: First, what Is a Release? Then, releases vs. Tags vs. Branches. After that, navigating Releases on GitHub. Finally, understanding Version Numbers. Treat it like a recipe: do not add the next ingredient until the previous one is actually in the bowl.

      -

      Jamie: What does the learner do first, second, and then after that?

      -

      Alex: First, reading Release Notes. Then, for Maintainers: Creating a Release. After that, draft and Pre-Release States. Finally, accessibility Agents: /draft-release. It is a checklist, but a meaningful one: every item creates evidence that the next step is safe.

      -

      Jamie: Turn that into a path someone can follow.

      -

      Alex: Start with Repository Insights. There is something to understand, something to try, and something that proves the try worked.

      -

      Alex: First, what Is the Insights Tab? Then, navigating to Insights. After that, pulse - Recent Activity Summary. Finally, contributors - Who Builds the Project. It is a checklist, but a meaningful one: every item creates evidence that the next step is safe.

      -

      Jamie: What is the ordered workflow?

      -

      Alex: First, traffic - Who Visits the Repo. Then, commits and Code Frequency. After that, dependency Graph. Finally, network and Forks. It is like walking a hallway with named doors: read the sign, enter the right room, then confirm where you landed.

      -
      -

      Alex: Now bring the learner back to the room. Keep the learner anchored in 1. What Is a Release? A release is a named snapshot of a repository at a specific point in history, packaged and published for users. This is the part to say slowly: For software projects, a release typically includes.

      -

      Alex: For a learner, the useful signals are these. A version number (e.g., v2.1.0). Release notes explaining what changed. Links to download the compiled or packaged software (if applicable). Source code archives (automatically generated by GitHub).

      -

      Jamie: What would you say to someone who is already bracing for this to be too much?

      -

      Alex: The reason 2. Releases vs. Tags vs. Branches matters is that these three concepts are closely related.

      -

      Alex: A solid Git habit is to know which branch you are on, what changed, and what confirmation you expect before you run the next command.

      -

      Alex: That matters because of the next idea. Start with The relationship. There is something to understand, something to try, and something that proves the try worked.

      -

      Alex: On the ground, that means a few things. Every release is backed by a tag. A tag without a release is just a version marker in the git history. GitHub automatically creates a tag when you create a release.

      -

      Alex: The useful habit is simple: orient first, act second, verify third. That pause before acting is part of the work.

      -
      -

      Jamie: Give me the sequence, because order matters here.

      -

      Alex: Start with Finding the Releases Page. There is something to understand, something to try, and something that proves the try worked.

      -

      Alex: First, look on the right sidebar for a "Releases" section showing the latest release. Then, activate "Releases" or the version link to go to the full releases page. After that, alternatively: navigate to github.com/owner/repo/releases. Treat it like a recipe: do not add the next ingredient until the previous one is actually in the bowl.

      -

      Alex: This is where the talk moves from concept to action. This is where The Releases List Page becomes real: each release appears as a section.

      -

      Alex: The room should hear these as checkpoints. The release title (usually the version number). A badge: "Latest" (most recent stable), "Pre-release", or nothing (older release). Publication date. The tag name. Release notes (the main body). Asset downloads (if included).

      -

      Jamie: What is the one idea that makes the next few steps less mysterious?

      -

      Alex: Start with Learning Cards: Navigating Releases. There is something to understand, something to try, and something that proves the try worked.

      -

      Alex: These are the details that keep the idea from floating away. On the repository home page, press H or 3 to find the "Releases" heading in the right sidebar, then K to the version link -- Enter opens the latest release directly. On the Releases list page, each release is a heading -- use 2 or 3 to jump between releases and arrow down to read the notes inline. The "Latest" badge appears next to the most recent stable release -- listen for it to distinguish stable releases from pre-releases or older versions. The Releases link on the repo home page sits in the right sidebar -- at high zoom the sidebar may collapse below the main content; scroll down to find it. Release notes use Markdown headings (Breaking Changes, New Features, Bug Fixes) -- zoom in and scan the bold section labels for quick triage. The green "Latest" badge next to the newest stable release is small -- zoom to 150%+ to spot it among the release list entries.

      -
      -

      Alex: Before the learner moves on. The reason 4. Understanding Version Numbers matters is that most projects follow Semantic Versioning (semver): MAJOR.MINOR.PATCH. The interface gets friendlier when it stops being a wall of controls and starts being a set of named places.

      -

      Jamie: Give me the version that sounds like an instructor, not a manual.

      -

      Alex: Start with Examples: Pre-release suffixes (not part of semver core, but common).

      -

      Alex: A few details make that real. v2.0.0 → major release, breaking changes possible. v2.1.0 → new features added. v2.1.3 → three bug fixes since v2.1.0. v2.1.0-alpha.1 → early preview, may be unstable. v2.1.0-beta.2 → feature-complete but still testing. v2.1.0-rc.1 → release candidate, nearly final.

      -

      Jamie: What should happen before anyone copies and runs it?

      -

      Alex: Here is the plain-English version of 5. Reading Release Notes. Release notes document what changed. Put another way, high-quality release notes categorize changes.

      -

      Alex: Treat examples as spoken recipes, not decorations. You may hear something like What's New in v2.1.0; Breaking Changes; - The preferences.md format has changed - see the migration guide; New Features; - Added /project-status command ( 42, @alice); - Added /onboard-repo command ( 38, @bob); Bug Fixes; - Fixed keyboard navigation in the. Read the command, understand what it changes, then run it only when the repository state matches the lesson.

      -
      -

      Jamie: If I am listening before the workshop starts, what should settle in my mind first?

      -

      Alex: This is where 6. For Maintainers: Creating a Release becomes real: this section is relevant if you become a maintainer or contribute to a project that asks you to prepare releases.

      -

      Jamie: Let's pause on Creating a Release from the GitHub UI. What should a learner take away from it?

      -

      Alex: Start with Creating a Release from the GitHub UI. There is something to understand, something to try, and something that proves the try worked.

      -

      Alex: First, navigate to github.com/owner/repo/releases/new. Then, choose a tag: Type a new version tag (e.g., v2.1.0) - GitHub will create it on publish, or select an existing tag if you already created one. After that, choose a target branch: The branch the tag will be applied to (usually main). Finally, release title: Usually the same as the tag (e.g., v2.1.0). It is like walking a hallway with named doors: read the sign, enter the right room, then confirm where you landed.

      -

      Jamie: Before we leave Creating a Release from the GitHub UI, what is the practical point?

      -

      Alex: First, release notes: Write manually, or click "Generate release notes" - GitHub auto-generates from merged PR titles since the last release. Then, assets: Optionally attach compiled binaries or other files. After that, pre-release toggle: Mark as pre-release if it's alpha/beta. Finally, draft toggle: Save as draft to prepare without publishing immediately. The rhythm is simple: orient, act, verify, then continue.

      -

      Jamie: Where do you want a learner to place their attention here?

      -

      Alex: The reason Using Accessibility Agents for Release Notes matters is that the /draft-release command generates structured release notes automatically from your merged PRs - much faster and more consistent than writing them manually.

      -
      -

      Alex: Here is the practical turn. Start with Learning Cards: Creating a Release. There is something to understand, something to try, and something that proves the try worked.

      -

      Alex: Here is what that changes in practice. The release creation form at github.com/owner/repo/releases/new has several fields -- Tab through them in order: tag selector (combobox), target branch, title input, release notes textarea, asset upload, pre-release checkbox, draft checkbox, and publish button. The tag selector is a combobox -- type a new version tag (e.g., v2.1.0) and the option to create it appears; arrow down and press Enter to select. The "Generate release notes" button auto-fills the textarea with merged PR titles -- after clicking it, arrow through the generated notes to verify accuracy before publishing. The release creation page uses a single-column form layout -- zoom in and the form fields stack vertically for easy scanning. The "Pre-release" and "Draft" checkboxes are at the bottom of the form, below the release notes editor -- scroll past the potentially long textarea to find them. The "Generate release notes" button is a small link-style button near the release notes textarea -- look for it above or beside the text area at high magnification.

      -

      Jamie: Let's pause on 7. Draft and Pre-Release States. What should a learner take away from it?

      -

      Alex: Here is the plain-English version of 7. Draft and Pre-Release States. Draft release: Saved but not published. Put another way, only visible to repository collaborators.

      -

      Alex: A solid pull request habit is to separate three questions: what changed, why it changed, and what still needs review. That keeps the conversation useful instead of noisy.

      -

      Alex: Keep the thread going. This is where 8. Accessibility Agents: /draft-release becomes real: the /draft-release command automates release note generation from your merged pull requests. The workshop is closer to rehearsal than lecture. You hear the move, try the move, and then check what changed.

      -
      -

      Jamie: Let's pause on What it produces. What should a learner take away from it?

      -

      Alex: Start with What it produces. There is something to understand, something to try, and something that proves the try worked.

      -

      Alex: That becomes easier when you listen for these cues. Auto-categorized changes: Breaking Changes, Features, Bug Fixes, Dependencies. Each PR listed with number, title, and author. A full changelog link. Markdown formatted and ready to paste into GitHub's release editor.

      -

      Jamie: What should they understand before typing anything?

      -

      Alex: The reason Example output matters is that see also: The /release-prep command runs a complete pre-release checklist (milestone status, open PRs, CI health, security, and then generates release notes) - useful when preparing a release from scratch rather than just generating notes.

      -

      Alex: Treat examples as spoken recipes, not decorations. You may hear something like v2.1.0; New Features; - Add /project-status command ( 42, @alice); - Add /onboard-repo for first-time repo scanning ( 38, @bob); Bug Fixes; - Fix keyboard navigation in triage workflow ( 51, @charlie); - Correct screen reader announcement for merged PRs ( 48,. Read the command, understand what it changes, then run it only when the repository state matches the lesson.

      -

      Jamie: Let's pause on 9. What Is the Insights Tab? What should a learner take away from it?

      -

      Alex: Start with 9. What Is the Insights Tab?: The Insights tab shows quantitative activity data for a repository. The next useful detail is this: It is primarily read-only and chart-heavy - but all underlying data is also presented in tables that screen readers can navigate.

      -
      -

      Alex: This is the part worth saying out loud. Start with Who can see Insights. There is something to understand, something to try, and something that proves the try worked.

      -

      Alex: The practical anchors are these. Anyone can see Insights on a public repository. Private repository Insights require collaborator access.

      -

      Jamie: Let's pause on What Insights does NOT show. What should a learner take away from it?

      -

      Alex: Start with What Insights does NOT show. There is something to understand, something to try, and something that proves the try worked.

      -

      Alex: That shows up in the workshop in a few specific ways. Individual user data in detail (e.g., lines per commit per person). Real-time data (most views update daily or weekly). Code quality scores.

      -

      Jamie: Let's pause on 10. Navigating to Insights. What should a learner take away from it?

      -

      Alex: Start with 10. Navigating to Insights. There is something to understand, something to try, and something that proves the try worked.

      -

      Alex: First, navigate to the repository's main tab bar. Then, find and select the Insights tab. After that, the Insights sub-navigation has multiple views listed on the left (or top on smaller screens). It is like walking a hallway with named doors: read the sign, enter the right room, then confirm where you landed.

      -
      -

      Jamie: Let's pause on 11. Pulse - Recent Activity Summary. What should a learner take away from it?

      -

      Alex: The reason 11. Pulse - Recent Activity Summary matters is that pulse is the Insights landing page. That gives the learner a simple foothold: it summarizes activity in a chosen time period (last 24 hours, 7 days, or 30 days).

      -

      Alex: The parts worth keeping in working memory are these. Open issues / Closed issues - net change in the time period. Open pull requests / Merged pull requests / Closed pull requests - with counts. Authors: N contributors pushed M commits to N branches. A list of merged PRs (each linked to the PR).

      -

      Alex: Another way to ground it. Start with What it tells you as a contributor. There is something to understand, something to try, and something that proves the try worked.

      -

      Alex: The practical takeaway is this. Is this project actively maintained? (Are PRs being merged regularly?). Is there a backlog? (Many open issues vs. few closures). Is the maintainer responsive? (Time between PR open and merge).

      -

      Jamie: Let's pause on Learning Cards: Pulse (Recent Activity Summary). What should a learner take away from it?

      -

      Alex: Start with Learning Cards: Pulse (Recent Activity Summary). There is something to understand, something to try, and something that proves the try worked.

      -

      Alex: The practical takeaway is this. Pulse is the Insights landing page -- after entering the Insights tab, you land here; use 2 to jump between section headings (Merged PRs, Opened Issues, etc.). Each section lists linked PR or issue titles -- press 3 to jump between individual items, or K to navigate the links directly. Use the time period selector (last 24 hours, 7 days, 30 days) at the top to scope the summary -- Tab to it and select with arrow keys. Pulse displays activity counts in large numbers at the top of the page -- zoom in to read the open/closed/merged totals. The merged PR and opened issue lists below the summary use standard link formatting -- increase font size to scan titles comfortably. The time period toggle (24h, 7d, 30d) sits near the top -- it can be small at default zoom; look for the underlined active period indicator.

      -
      -

      Alex: Hold that next to this. This is where 12. Contributors - Who Builds the Project becomes real: the Contributors view shows a bar chart of commits over time, with each contributor represented by a different color. That matters in practice: Below the chart is a sortable table.

      -

      Jamie: Let's pause on The table (accessible). What should a learner take away from it?

      -

      Alex: Start with The table (accessible). There is something to understand, something to try, and something that proves the try worked.

      -

      Alex: The practical takeaway is this. Username. Number of commits (with a link to filtered commit history). Additions (lines added). Deletions (lines removed). Sorted by total commits by default.

      -

      Alex: The next layer is this. Start with Why this matters as a new contributor. There is something to understand, something to try, and something that proves the try worked.

      -

      Alex: The practical takeaway is this. You can see how active top contributors are. After your first merged PR, your name appears here (with your commits). You can link to your section (github.com/owner/repo/graphs/contributors) as proof of contribution.

      -
      -

      Jamie: Let's pause on Screen reader. What should a learner take away from it?

      -

      Alex: Start with Screen reader: The chart is a canvas graphic - not directly readable. The next useful detail is this: The table below it is fully accessible.

      -

      Alex: A solid navigation habit is to prove where you are before activating controls. Headings, landmarks, and the address bar are not trivia; they are your map.

      -

      Alex: That connects to another useful point. Start with Learning Cards: Contributors. There is something to understand, something to try, and something that proves the try worked.

      -

      Alex: The practical takeaway is this. The contributor chart is a canvas graphic that screen readers cannot access -- skip it and navigate to the data table below with T (next table) which contains the same information in accessible form. The table has sortable column headers (Commits, Additions, Deletions) -- Tab to a header and press Enter to sort; the table reloads with the new sort order. Each contributor's username is a link to their filtered commit list -- activate it to see every commit that person made to this repository. The bar chart uses color to distinguish contributors -- the table below provides the same data as text; zoom in on the table if the chart colors are hard to differentiate. Sorting by Commits (default) puts top contributors first -- at high zoom, the table may require horizontal scrolling to see the Additions and Deletions columns. After your first merged PR, your username appears in this table -- link to it (github.com/owner/repo/graphs/contributors) as proof of contribution in your portfolio.

      -

      Jamie: Let's pause on 13. Traffic - Who Visits the Repo. What should a learner take away from it?

      -

      Alex: This is where 13. Traffic - Who Visits the Repo becomes real: traffic shows who is viewing and cloning the repository. That matters in practice: Available only to repository owners and collaborators with push access.

      -
      -

      Alex: Keep the teaching thread moving. Start with Why this matters. There is something to understand, something to try, and something that proves the try worked.

      -

      Alex: The practical takeaway is this. If the README is the most-viewed file, documentation improvements have high impact. If traffic spiked when a blog post linked the repo, that's a good signal for community growth.

      -

      Jamie: Let's pause on 14. Commits and Code Frequency. What should a learner take away from it?

      -

      Alex: The reason 14. Commits and Code Frequency matters is that commits shows commit frequency over the past year, by week. That gives the learner a simple foothold: code Frequency shows additions and deletions per week as an area chart.

      -

      Alex: The practical takeaway is this. Active development periods (many commits). Dormant periods (no commits) - a project with 6+ months of inactivity may be unmaintained. Release sprints (burst of commits before a release tag). Heavy refactoring.

      -

      Alex: Keep the teaching thread moving. Start with 15. Dependency Graph: Dependents - repositories that depend on this one - is the "used by" count you see on the right sidebar of popular packages.

      -

      Alex: The practical takeaway is this. What your project depends on (libraries, packages). What depends on your project (if others import your repo).

      -
      -

      Jamie: Let's pause on Enabling/viewing. What should a learner take away from it?

      -

      Alex: Here is the plain-English version of Enabling/viewing. Why it matters for security: The dependency graph feeds Dependabot. Put another way, if a vulnerability is found in a library, Dependabot uses this graph to identify which repos use the affected version and opens automated PRs to update them.

      -

      Alex: The practical takeaway is this. Settings → Security & Analysis → Dependency graph → Enable. Navigate to Insights → Dependency graph.

      -

      Alex: Keep the teaching thread moving. This is where 16. Network and Forks becomes real: the Network view shows a graphical branch/fork network - who has forked the repo, what branches exist, and how they diverge. That matters in practice: The network graph is a canvas visualization not accessible to screen readers. The workshop is closer to rehearsal than lecture. You hear the move, try the move, and then check what changed.

      -

      Jamie: Let's pause on 17. Community Standards. What should a learner take away from it?

      -

      Alex: Keep the learner anchored in 17. Community Standards. The Community Standards view (found in the Insights sidebar or in the main repository homepage's "Recommended" sidebar section) shows a checklist of community health files. This is the part to say slowly: A fully green checklist signals a well-maintained project.

      -
      -

      Jamie: How do you keep commands from becoming magic words?

      -

      Alex: Start with Screen reader. There is something to understand, something to try, and something that proves the try worked.

      -

      Alex: Treat examples as spoken recipes, not decorations. You may hear something like H / 2 → "Community Standards" section heading; Tab → Each checklist item (links to add missing files). Read the command, understand what it changes, then run it only when the repository state matches the lesson.

      -

      Jamie: Let's pause on Comparing two releases (the Changelog). What should a learner take away from it?

      -

      Alex: Start with Comparing two releases (the Changelog): The compare URL (/compare/v1.0.0.v2.0.0) shows a diff of all commits and merged PRs between two tags.

      -

      Alex: Keep the teaching thread moving. Here is the plain-English version of Charts and graphs - general strategy. Most Insights charts are canvas or SVG visuals. Put another way, they announce as "image" or "graphic" to screen readers. It is like learning a transit route. The names of the stops matter because they tell you whether you are still going the right direction.

      -
      -

      Jamie: Let's pause on 19. Accessibility Agents: /my-stats and /team-dashboard. What should a learner take away from it?

      -

      Alex: This is where 19. Accessibility Agents: /my-stats and /team-dashboard becomes real: instead of navigating GitHub's chart-heavy Insights UI, Accessibility Agents provides two commands that deliver the same data in text form directly in VS Code.

      -

      Alex: Keep the teaching thread moving. Keep the learner anchored in /my-stats. Shows your personal contribution statistics across all tracked repos.

      -

      Alex: The practical takeaway is this. PRs opened and merged. Issues filed and closed. Reviews conducted. Commits pushed. Compare to previous period.

      -

      Jamie: Let's pause on /team-dashboard. What should a learner take away from it?

      -

      Alex: The reason /team-dashboard matters is that shows team-wide activity across tracked repos - who contributed what, response times, review coverage. That gives the learner a simple foothold: next: Appendix T: Community and Social Back: Appendix R: Projects Deep Dive Teaching chapter: Chapter 08: Open Source Culture.

      -

      Alex: The practical takeaway is this. Per-person contribution summary. Review coverage (how many PRs got reviews). Open issues by assignee. CI health across team repos.

      -
      -

      Jamie: What should people carry with them after this?

      -

      Alex: Carry the map. Know what page or tool you are in, know which action you are taking, and know what confirmation should follow. If the confirmation is missing, pause. That pause is not wasted time; it is professional judgment.

      -

      Jamie: That is a better way to say it than just follow the steps.

      -

      Alex: Right. Steps matter, but understanding wins. That is episode 25. Next in the series is episode 26, where we keep building the same contributor muscles.

      -
      - -
      -

      Episode 26: GitHub Projects Deep Dive

      -

      Project boards, table and roadmap views, custom fields, cross-repo management.

      -

      Based on: Appendix R: GitHub Projects Deep Dive

      -

      Audio and transcript are being regenerated for this episode.

      -
      -Read Transcript - Episode 26: GitHub Projects Deep Dive - -

      Transcript

      -

      Alex: This is Git Going with GitHub, episode 26: GitHub Projects Deep Dive. I am Alex. By the end of this episode, GitHub Projects Deep Dive should feel less like a wall of GitHub words and more like a set of moves you can trust.

      -

      Jamie: And I am Jamie. I am here for the practical questions: what should I listen for, what can go wrong, and what is the next calm move?

      -
      -

      Alex: Today we are working on this: Project boards, table and roadmap views, custom fields, cross-repo management. I want the learner to leave with a mental map, not just a remembered path through buttons.

      -

      Jamie: So the goal is understanding first, then action, then confirmation.

      -

      Alex: Right. We are building a rhythm: orient yourself, take one intentional action, then verify what changed before moving on.

      +

      Alex: Today we are working on this: Project boards, table and roadmap views, custom fields, cross-repo management. I want the learner to leave with a mental map, not just a remembered path through buttons.

      +

      Jamie: So the goal is understanding first, then action, then confirmation.

      +

      Alex: Right. We are building a rhythm: orient yourself, take one intentional action, then verify what changed before moving on.

      Jamie: Okay, set the room for us. What are we walking into?

      Alex: Start with Boards, Tables, Roadmaps, Automations, and Accessible Navigation: GitHub Projects is GitHub's built-in project management system. The next useful detail is this: It connects issues and pull requests from one or more repositories into a living, filterable view that your whole team can see and act on.

      @@ -7172,7 +6902,7 @@

      Transcript

      - +

      GitHub search query language, qualifiers, and filtering for issues, PRs, and code.

      Based on: Appendix N: Advanced Search

      Audio and transcript are being regenerated for this episode.

      @@ -7220,4978 +6950,5547 @@

      Transcript

      -

      Episode 28: Branch Protection and Rulesets

      -

      Required reviews, status checks, rulesets, and diagnosing blocked merges.

      -

      Based on: Appendix O: Branch Protection and Rulesets

      -

      Audio and transcript are being regenerated for this episode.

      +

      27. Episode 10: Notifications and Mentions

      +

      Managing your notification inbox, @mentions, and strategies for avoiding overload.

      +

      Based on: Chapter 10: Notifications and Mentions

      + + +

      Download Episode 10 (MP3)

      -Read Transcript - Episode 28: Branch Protection and Rulesets +Read Transcript - Episode 10: Notifications and Mentions

      Transcript

      -

      Alex: Welcome to Git Going with GitHub, episode 28: Branch Protection and Rulesets. I am Alex. Today we are going to make Branch Protection and Rulesets something you can explain, practice, and recover from when the interface surprises you.

      -

      Jamie: And I am Jamie. I will be the voice of the learner who is willing to ask, what is this for, where am I, and how do I know I did it right?

      +

      Alex: This is Git Going with GitHub, episode 10: Notifications and Mentions. I am Alex. By the end of this episode, Notifications and Mentions should feel less like a wall of GitHub words and more like a set of moves you can trust.

      +

      Jamie: And I am Jamie. I am here for the practical questions: what should I listen for, what can go wrong, and what is the next calm move?

      -

      Alex: The big idea today: Required reviews, status checks, rulesets, and diagnosing blocked merges. We will name the concept, explain why it matters, practice the move, and point out the checks that tell you the work is real.

      -

      Jamie: So the episode should work even if someone has not read the chapter yet.

      -

      Alex: Exactly. The transcript has to stand on its own. It can point toward practice, but it should teach the concept right here in the conversation.

      +

      Alex: Today we are working on this: Managing your notification inbox, @mentions, and strategies for avoiding overload. I want the learner to leave with a mental map, not just a remembered path through buttons.

      +

      Jamie: So the goal is understanding first, then action, then confirmation.

      +

      Alex: Right. We are building a rhythm: orient yourself, take one intentional action, then verify what changed before moving on.

      Jamie: Okay, set the room for us. What are we walking into?

      -

      Alex: Start with How Merging Rules Work and Why Your PR May Be Blocked: Who this is for: Contributors who have submitted a PR and are wondering why it cannot be merged yet, as well as workshop facilitators who configure branch protection for practice repositories.

      -

      Alex: A solid pull request habit is to separate three questions: what changed, why it changed, and what still needs review. That keeps the conversation useful instead of noisy.

      -

      Jamie: How would you walk the room through that step by step?

      -

      Alex: Start with Quick Navigation. There is something to understand, something to try, and something that proves the try worked.

      -

      Alex: First, what Branch Protection Does. Then, common Branch Protection Rules. After that, repository Rulesets - The Modern Approach. Finally, why Your PR Cannot Be Merged - Diagnosis Guide. Treat it like a recipe: do not add the next ingredient until the previous one is actually in the bowl.

      +

      Alex: Start with Managing Your GitHub Notification Inbox: See also: Appendix V: GitHub Mobile for managing notifications on your phone. The next useful detail is this: GitHub notifications are how GitHub tells you when something needs your attention.

      +

      Alex: A solid project habit is to treat metadata as decision support. Labels, status, assignees, and notifications tell you what kind of attention the work needs.

      +

      Alex: The next layer is this. Here is the plain-English version of Workshop Recommendation (Chapter 10). For this workshop, Chapter 10 is a guided practice chapter, not a graded automation chapter. It is like learning a transit route. The names of the stops matter because they tell you whether you are still going the right direction.

      +

      Alex: The practical anchors are these. There are 1 guided walkthrough. Automation check: none - notification settings are account-level and cannot be validated by the Learning Room PR bot. The evidence is structured completion comment on your assigned challenge issue. The pattern is configure, filter, act.

      Jamie: What does the learner do first, second, and then after that?

      -

      Alex: First, navigating the Merge Box with a Screen Reader. Then, status Checks - What They Are and What They Mean. After that, who Can Configure Branch Protection. Finally, workshop Repository Configuration Reference. It is a checklist, but a meaningful one: every item creates evidence that the next step is safe.

      -

      Alex: A solid navigation habit is to prove where you are before activating controls. Headings, landmarks, and the address bar are not trivia; they are your map.

      -

      Jamie: What is the one idea that makes the next few steps less mysterious?

      -

      Alex: This is where 1. What Branch Protection Does becomes real: a branch protection rule is a set of requirements that must be satisfied before a PR can be merged into a specific branch (typically main). That matters in practice: Think of branch protection as the quality gate for a repository's primary branch.

      -

      Alex: That shows up in the workshop in a few specific ways. Require that code is reviewed before it enters the default branch. Require that automated tests pass before merging. Prevent direct pushes to main without a PR. Ensure the branch is up-to-date before merging.

      +

      Alex: Start with Chapter 10 Challenge Set. There is something to understand, something to try, and something that proves the try worked.

      +

      Alex: First, configure notifications and practice inbox management - set your watch level, use filters to find relevant notifications, and perform one inbox action. It is a checklist, but a meaningful one: every item creates evidence that the next step is safe.

      -

      Alex: Now bring the learner back to the room. Start with Learning Cards: What Branch Protection Does. There is something to understand, something to try, and something that proves the try worked.

      -

      Alex: For a learner, the useful signals are these. The merge box at the bottom of every PR page is where branch protection surfaces its requirements -- press End to jump to the bottom, then use H to find the merge heading. Each requirement is announced as a status line: "1 review required," "Some checks haven't completed yet," etc. -- listen for these before attempting to merge. If the Merge button says "disabled" or "grayed out," branch protection is blocking -- the status lines immediately above explain exactly what is needed. The merge box uses green (ready), yellow (pending), and red (blocked) indicators -- zoom in on the merge area to read the text labels next to each colored icon. The "Update branch" button appears as a secondary button above the merge button when your PR is behind main -- it can be easy to miss at high zoom. Required checks show checkmark or X icons that are small at default size -- browser zoom to 150%+ makes the pass/fail status easier to distinguish.

      -

      Jamie: What would you say to someone who is already bracing for this to be too much?

      -

      Alex: The reason Required Reviews matters is that the maintainer requires a minimum number of approving reviews before the PR can be merged. That gives the learner a simple foothold: example: "Require 1 approving review".

      -

      Alex: The parts worth keeping in working memory are these. Your PR shows a "1 review required" notice in the merge box. If a reviewer requests changes, their approval is revoked - you need at least one new approval after your latest push. After you push new commits, re-request review from the original reviewer.

      -

      Alex: That matters because of the next idea. Start with Required Status Checks: Automated workflows (GitHub Actions or third-party CI) must complete successfully before merging is allowed. Think of it like entering a new building: first you find the lobby, then the room, then the door you actually need.

      +

      Jamie: Turn that into a path someone can follow.

      +

      Alex: Keep the learner anchored in Challenge 10.1 Step-by-Step: Notification Inbox Walkthrough. Set up a useful notification workflow so you can keep up with reviews, mentions, and assignments without inbox overload. This is the part to say slowly: the GitHub.com notifications page and your Learning Room repository settings.

      +

      Alex: For a learner, the useful signals are these. Press M to mute the thread (you will not receive future updates),. Press E to mark done (removes it from inbox but you can still get future updates).

      +

      Alex: First, open your Learning Room repository on GitHub.com. Then, find the Watch button near the top-right of the repository page (next to Star and Fork). After that, 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. Finally, open the notifications inbox by navigating to https://github.com/notifications (or activate the bell icon in the GitHub header). It is like walking a hallway with named doors: read the sign, enter the right room, then confirm where you landed.

      +

      Jamie: What is the ordered workflow?

      +

      Alex: First, in the notification filters, activate the Review requested filter. This shows only notifications where someone has asked you to review their PR. Then, clear that filter and activate the Assigned filter. This shows notifications for issues and PRs assigned to you. After that, open one notification by activating its title link. Read it briefly, then navigate back to the inbox. Finally, perform one inbox action on a non-critical notification thread. The rhythm is simple: orient, act, verify, then continue.

      +

      Jamie: What makes this practice feel low-stakes but still real?

      +

      Alex: The reason Completing Chapter 10: Submit Your Evidence matters is that open your assigned Chapter 10 challenge issue and post a completion comment. That gives the learner a simple foothold: close your Chapter 10 challenge issue when done.

      Alex: The useful habit is simple: orient first, act second, verify third. That pause before acting is part of the work.

      +

      Alex: That matters because of the next idea. Start with Expected Outcomes. There is something to understand, something to try, and something that proves the try worked.

      +

      Alex: On the ground, that means a few things. 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.

      -

      Jamie: If I am listening before the workshop starts, what should settle in my mind first?

      -

      Alex: Here is the plain-English version of Example checks you may see. What "Required" means: The merge button is grayed out (or shows an error) until all required checks show a green checkmark. Put another way, a failing or pending check blocks the merge.

      -

      Alex: Here is what that changes in practice. ci / build - compiles the code. ci / test - runs the test suite. lint - code style checks. accessibility-check - automated accessibility scanning.

      -

      Alex: This is where the talk moves from concept to action. This is where Require Branches to Be Up to Date becomes real: before merging, your PR branch must include all changes from main. That matters in practice: This prevents merge conflicts from being introduced silently.

      -

      Alex: The room should hear these as checkpoints. The merge box shows: "This branch is out of date with the base branch". Button: "Update branch" - merges current main into your branch. Alternative: Rebase your branch (only if the maintainer permits rebase merges).

      -

      Alex: A solid Git habit is to know which branch you are on, what changed, and what confirmation you expect before you run the next command.

      -

      Jamie: Where do you want a learner to place their attention here?

      -

      Alex: Keep the learner anchored in Require Signed Commits. All commits in the PR must have a Verified badge (see Appendix D: Git Authentication). This is the part to say slowly: If your commits are unverified, the PR cannot be merged until you re-commit with signing enabled.

      -
      -

      Alex: Before the learner moves on. The reason Require Linear History matters is that only squash merges or rebase merges are permitted - no merge commits. That gives the learner a simple foothold: this keeps the commit history linear and readable. The interface gets friendlier when it stops being a wall of controls and starts being a set of named places.

      -

      Jamie: Give me the version that sounds like an instructor, not a manual.

      -

      Alex: Start with Lock Branch: A locked branch cannot receive any merges - it is effectively read-only. The next useful detail is this: This is sometimes used for archived repositories or during release freezes.

      -

      Alex: Hold that next to this. Here is the plain-English version of 3. Repository Rulesets - The Modern Approach. Repository Rulesets (introduced in late 2023) are the next generation of branch protection. Put another way, they extend branch protection rules.

      -

      Alex: The practical anchors are these. Organization-level rules - apply across all repos in an org from one place. Bypass lists - specific users or roles can be exempted from rules (e.g., release bots). Target multiple branches - one ruleset can target a pattern like release/ or v. Violation insights - audit log of when rules were bypassed and by whom.

      +

      Jamie: How would you walk the room through that step by step?

      +

      Alex: Start with If You Get Stuck. There is something to understand, something to try, and something that proves the try worked.

      +

      Alex: First, can't find the Watch button? It is near the top-right of the repository page, in the same row as Star and Fork. Then, 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. After that, 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. Finally, filters not showing results? Clear all filters first (click the X next to each active filter), then apply one filter at a time. Treat it like a recipe: do not add the next ingredient until the previous one is actually in the bowl.

      +

      Jamie: Give me the sequence, because order matters here.

      +

      Alex: First, ask facilitator to model one inbox action live, then repeat the steps yourself. Then, finished but not sure you did it right? Compare your work against the Challenge 9 reference solution. It is a checklist, but a meaningful one: every item creates evidence that the next step is safe.

      +

      Alex: This is where the talk moves from concept to action. This is where Learning Moment becomes real: notification management protects focus. That matters in practice: You can stay responsive to your team without drowning in updates.

      +

      Jamie: Let's pause on Learning Pattern Used in This Chapter. What should a learner take away from it?

      +

      Alex: Start with Learning Pattern Used in This Chapter. There is something to understand, something to try, and something that proves the try worked.

      +

      Alex: First, configure settings proactively (watch level) before work generates noise. Then, use filters to find signal in noise (review requests, assignments). After that, take decisive action on each notification (mute, done, or respond). Finally, build a daily routine that keeps your inbox manageable. It is like walking a hallway with named doors: read the sign, enter the right room, then confirm where you landed.

      -

      Jamie: Let's pause on Rulesets vs. Branch Protection Rules. What should a learner take away from it?

      -

      Alex: This is where Rulesets vs. Branch Protection Rules becomes real: most repositories you encounter still use classic branch protection rules. That matters in practice: Rulesets will become more common as maintainers migrate.

      -

      Jamie: How do you keep commands from becoming magic words?

      -

      Alex: Keep the learner anchored in Finding and Reading Rulesets. If you want to understand why certain rules apply to a branch. This is the part to say slowly: Alternatively, PR merge box messages describe which rules are blocking - you don't need admin access to understand what's required. A good GitHub workflow is like a well-run meeting: everyone knows the topic, the next action, and who has the floor.

      -

      Alex: Treat examples as spoken recipes, not decorations. You may hear something like Repository → Insights tab → Rulesets (if you have access - contributors usually don't); Or: Repository → Settings → Rules → Rulesets (admin only). Read the command, understand what it changes, then run it only when the repository state matches the lesson.

      -

      Jamie: Let's pause on 4. Why Your PR Cannot Be Merged - Diagnosis Guide. What should a learner take away from it?

      -

      Alex: The reason 4. Why Your PR Cannot Be Merged - Diagnosis Guide matters is that when you open a PR and the merge button is grayed out or shows an error, the merge box tells you exactly what needs to happen.

      +

      Alex: Before the learner moves on. The reason What Generates a Notification? matters is that GitHub sends you a notification when. The interface gets friendlier when it stops being a wall of controls and starts being a set of named places.

      +

      Jamie: What would you say to someone who is already bracing for this to be too much?

      +

      Alex: Start with Notification Subscription Levels: For each repository, you choose how many notifications to receive.

      +

      Jamie: Let's pause on Changing your watch settings for a repo. What should a learner take away from it?

      +

      Alex: Here is the plain-English version of Changing your watch settings for a repo. At the top of any repository page, find the Watch button (near Star and Fork). Put another way, click it to open a dropdown with levels: Participating and @mentions, All Activity, Custom, and Ignore.

      +

      Alex: First, find the Watch button in the repo header (B to navigate buttons → find "Watch [N]" or "Unwatch" button). Then, press Enter to open the dropdown. After that, press ↑/↓ to navigate the subscription options. Finally, press Enter to select your preferred level. Treat it like a recipe: do not add the next ingredient until the previous one is actually in the bowl.

      +

      Jamie: Before we leave Changing your watch settings for a repo, what is the practical point?

      +

      Alex: First, the button label updates to confirm your choice. Then, quick Nav B to find the Watch button in the repo header (listen for "Watch" or "Unwatch"). After that, vO+Space to open the dropdown. Finally, vO+Down or arrow keys to navigate subscription options. It is a checklist, but a meaningful one: every item creates evidence that the next step is safe.

      -

      Alex: Here is the practical turn. Start with "X review required / X reviews required": What it means: The required number of approvals hasn't been reached yet.

      -

      Jamie: Turn that into a path someone can follow.

      -

      Alex: Start with What to do. There is something to understand, something to try, and something that proves the try worked.

      -

      Alex: First, request review from a codeowner or maintainer (right sidebar → Reviewers → request). Then, check if any reviews exist but requested changes - those count against you. After that, wait for the reviewer to submit their review. Finally, respond to requested changes by pushing new commits, then re-requesting review. Treat it like a recipe: do not add the next ingredient until the previous one is actually in the bowl.

      -

      Alex: Keep the thread going. This is where "Some checks haven't completed yet" or "Some checks were not successful" becomes real: what it means: A required status check is pending or failing. The workshop is closer to rehearsal than lecture. You hear the move, try the move, and then check what changed.

      +

      Jamie: Let's pause on Tool Cards: Manage Notifications. What should a learner take away from it?

      +

      Alex: This is where Tool Cards: Manage Notifications becomes real: VS Code Desktop (GitHub Pull Requests extension). That matters in practice: GitHub Desktop: GitHub Desktop does not manage notifications.

      +

      Alex: First, go to github.com/notifications (or press G then N). Then, use E to mark done, I to mark read/unread, Shift+M to mute a thread. After that, the Notifications view in the GitHub sidebar shows items needing attention. Finally, click a notification to open the related issue or PR directly in VS Code. It is a checklist, but a meaningful one: every item creates evidence that the next step is safe.

      +

      Alex: Treat examples as spoken recipes, not decorations. You may hear something like 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. 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. Read the command, understand what it changes, then run it only when the repository state matches the lesson.

      +

      Jamie: Let's pause on Navigating the notification list. What should a learner take away from it?

      +

      Alex: Keep the learner anchored in Navigating the notification list. The inbox shows notifications grouped by date (Today, Yesterday, This week, Older). This is the part to say slowly: Each row shows the repository, the issue or PR title, the event type, and the time. A good GitHub workflow is like a well-run meeting: everyone knows the topic, the next action, and who has the floor.

      +

      Alex: First, d → main content landmark. Then, h to navigate group headings (Today / Yesterday / This week / Older). After that, tab through individual notifications - each row announces: repo name, issue/PR title, event type, time. Finally, enter to open the notification (goes to the issue/PR page). It is like walking a hallway with named doors: read the sign, enter the right room, then confirm where you landed.

      +

      Jamie: Before we leave Navigating the notification list, what is the practical point?

      +

      Alex: First, vO+U → Main → navigate to notification list. Then, vO+Down to move through notifications. After that, vO+Space to open a notification. The rhythm is simple: orient, act, verify, then continue.

      +

      Jamie: What is the one idea that makes the next few steps less mysterious?

      +

      Alex: The reason What is announced per notification matters is that "microsoft/vscode - Add keyboard shortcut for accessible view - @username mentioned you - 2 hours ago". That gives the learner a simple foothold: components: repo/org thread title event type timestamp.

      -

      Jamie: What is the ordered workflow?

      -

      Alex: Keep the learner anchored in What to do. If checks pass on main but fail on your PR: The issue is specific to your changes. This is the part to say slowly: If checks are stuck "in progress" for over 30 minutes: The workflow runner may have an issue - contact the maintainer.

      -

      Alex: First, scroll down to the merge box - expand "Show all checks". Then, find the failing check → click "Details" to see the full log. After that, fix the underlying issue (test failure, lint error, build error) in your branch. Finally, push new commits - checks re-run automatically. It is like walking a hallway with named doors: read the sign, enter the right room, then confirm where you landed.

      -

      Jamie: Give me the sequence, because order matters here.

      -

      Alex: First, wait for checks to complete (typically 1-5 minutes for most CI). The rhythm is simple: orient, act, verify, then continue.

      -

      Alex: Another way to ground it. The reason "This branch is out of date with the base branch" matters is that what it means: New commits were pushed to main after you created your PR branch. That gives the learner a simple foothold: the maintainer requires everything to be current.

      -

      Jamie: Let's pause on What to do. What should a learner take away from it?

      -

      Alex: A few details make that real. Click "Update branch" in the merge box - GitHub does a merge commit from main into your branch. Or locally: git fetch upstream && git rebase upstream/main then force-push (only if you are comfortable with rebase).

      +

      Alex: Here is the practical turn. Start with Learning Cards: The Notifications Inbox. There is something to understand, something to try, and something that proves the try worked.

      +

      Alex: Here is what that changes in practice. 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. 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.

      +

      Jamie: Give me the version that sounds like an instructor, not a manual.

      +

      Alex: Here is the plain-English version of Inbox Actions - Keyboard Shortcuts. These shortcuts work when a notification is focused in the inbox. Put another way, these are GitHub's own keyboard shortcuts.

      +

      Alex: A solid navigation habit is to prove where you are before activating controls. Headings, landmarks, and the address bar are not trivia; they are your map.

      +

      Alex: Keep the thread going. This is where Filtering the Inbox becomes real: the left sidebar has quick filters. The workshop is closer to rehearsal than lecture. You hear the move, try the move, and then check what changed.

      -

      Alex: This is the part worth saying out loud. Here is the plain-English version of "Commits must have verified signatures". What it means: Branch protection requires signed commits (see Appendix D: Git Authentication). It is like learning a transit route. The names of the stops matter because they tell you whether you are still going the right direction.

      -

      Jamie: Before we leave What to do, what is the practical point?

      -

      Alex: First, enable commit signing locally before making more commits. Then, for existing unsigned commits, you need to rebase-rewrite them - this is advanced; ask the maintainer if there is a workaround. It is a checklist, but a meaningful one: every item creates evidence that the next step is safe.

      -

      Alex: The next layer is this. Keep the learner anchored in "Merging is blocked". What it means: A ruleset or branch protection has explicitly blocked merging for a reason not covered by other messages. This is the part to say slowly: Check the PR for a pinned comment from the mergeable status check or a GitHub Actions check that posts a comment explaining the block.

      -
      -

      Jamie: Let's pause on Learning Cards: Why Your PR Cannot Be Merged. What should a learner take away from it?

      -

      Alex: Start with Learning Cards: Why Your PR Cannot Be Merged. There is something to understand, something to try, and something that proves the try worked.

      -

      Alex: On the ground, that means a few things. Navigate to the merge box (End key, then H key to find "Merge" heading) and read each status line with arrow keys -- the messages tell you exactly what action to take. When a check fails, Tab to the "Details" link next to the failing check name and press Enter to open the log -- use Ctrl+F to search for "error" or "failed". After pushing a fix, the checks re-run automatically -- return to the PR page and listen for the status to change from "pending" to "passed". Failed checks show a red X icon that can be tiny -- zoom to 150%+ and look for the word "failing" or "failed" next to each check name. The "Update branch" button (for out-of-date PRs) is a secondary action that blends in at low zoom -- look for it directly above the main merge button. The Details link next to each check opens a log page with monospace text -- increase your editor or browser font size before reading long CI logs.

      -

      Alex: That connects to another useful point. Start with 5. Navigating the Merge Box with a Screen Reader: The merge box lives at the bottom of every PR page. The next useful detail is this: With a screen reader, navigating to it efficiently is important. Think of it like entering a new building: first you find the lobby, then the room, then the door you actually need.

      -

      Jamie: Let's pause on Reading Check Details. What should a learner take away from it?

      -

      Alex: Here is the plain-English version of Reading Check Details. The check log is a text-heavy page in a pre-formatted block.

      -
      -

      Alex: Keep the teaching thread moving. This is where 6. Status Checks - What They Are and What They Mean becomes real: status checks come from two sources.

      -

      Jamie: Let's pause on GitHub Actions Status Checks. What should a learner take away from it?

      -

      Alex: Keep the learner anchored in GitHub Actions Status Checks. Defined in.github/workflows/.yml in the repository. This is the part to say slowly: Each job: in a workflow file becomes a status check.

      -

      Alex: Keep the teaching thread moving. The reason Third-Party Status Checks matters is that services like Netlify, Vercel, Codecov, and Snyk post status checks via the GitHub API. That gives the learner a simple foothold: the learner will recognize them by their app name prefix (e.g., netlify/deploy-preview - Deploy Preview ready). The interface gets friendlier when it stops being a wall of controls and starts being a set of named places.

      -
      -

      Jamie: Let's pause on 7. Who Can Configure Branch Protection. What should a learner take away from it?

      -

      Alex: Start with 7. Who Can Configure Branch Protection: As a workshop participant, you are typically a contributor to the main community-access/accessibility-agents repo and an admin of your own fork. The next useful detail is this: On your fork, you can configure branch protection however you like - including disabling it entirely for practice purposes.

      -

      Alex: Keep the teaching thread moving. Here is the plain-English version of 8. Workshop Repository Configuration Reference. The community-access/accessibility-agents repository uses the following branch protection configuration on main. Put another way, your personal fork of accessibility-agents has no branch protection by default.

      -

      Jamie: Let's pause on Related Resources. What should a learner take away from it?

      -

      Alex: This is where Related Resources becomes real: next: Appendix P: Security Features Back: Appendix N: Advanced Search Teaching chapter: Chapter 08: Open Source Culture.

      -

      Alex: These are the details that keep the idea from floating away. Appendix D - Git Authentication and Commit Signing. Appendix Q - GitHub Actions Workflows. Appendix L - GitHub Security Features.

      -
      -

      Jamie: What should people carry with them after this?

      -

      Alex: Carry the map. Know what page or tool you are in, know which action you are taking, and know what confirmation should follow. If the confirmation is missing, pause. That pause is not wasted time; it is professional judgment.

      -

      Jamie: That is a better way to say it than just follow the steps.

      -

      Alex: Right. Steps matter, but understanding wins. That is episode 28. Next in the series is episode 29, where we keep building the same contributor muscles.

      -
      - -
      -

      Episode 29: GitHub Security Features

      -

      Dependabot, secret scanning, code scanning, and private security advisories.

      -

      Based on: Appendix P: GitHub Security Features

      -

      Audio and transcript are being regenerated for this episode.

      -
      -Read Transcript - Episode 29: GitHub Security Features - -

      Transcript

      -

      Alex: Welcome back to Git Going with GitHub. This is episode 29: GitHub Security Features. I am Alex, and today we are turning GitHub Security Features from a list of instructions into a working mental model.

      -

      Jamie: And I am Jamie. I will stop us whenever the instructions sound simple on paper but might feel different with a keyboard and screen reader.

      -
      -

      Alex: Dependabot, secret scanning, code scanning, and private security advisories. That is the surface description. Underneath it, we are building judgment: where to focus, what to ignore, and how to verify the result.

      -

      Jamie: So we are not using the audio as a shortcut around learning. We are using it to make the learning easier to enter.

      -

      Alex: Yes. A good audio lesson gives someone enough context to try the work with confidence, even before they open the written material.

      -
      -

      Jamie: Okay, set the room for us. What are we walking into?

      -

      Alex: Start with Dependabot, Secret Scanning, Code Scanning, and Private Advisories: Who this is for: Anyone contributing to open source repositories needs to understand how GitHub protects code and what security alerts mean. The next useful detail is this: This appendix explains the GitHub Security and quality tab, how to interpret and respond to alerts, and how to responsibly report vulnerabilities - including in community-access/accessibility-agents.

      -

      Alex: A solid pull request habit is to separate three questions: what changed, why it changed, and what still needs review. That keeps the conversation useful instead of noisy.

      -

      Jamie: How would you walk the room through that step by step?

      -

      Alex: Start with Quick Navigation. There is something to understand, something to try, and something that proves the try worked.

      -

      Alex: First, the Security and quality tab - What It Contains. Then, dependabot - Automated Dependency Updates. After that, secret Scanning - Preventing Credential Leaks. Finally, code Scanning and CodeQL. Treat it like a recipe: do not add the next ingredient until the previous one is actually in the bowl.

      -

      Jamie: What does the learner do first, second, and then after that?

      -

      Alex: First, private Vulnerability Reporting. Then, the SECURITY.md File. After that, software Bill of Materials (SBOM). Finally, screen Reader Navigation of the Security and quality tab. It is a checklist, but a meaningful one: every item creates evidence that the next step is safe.

      -

      Alex: A solid navigation habit is to prove where you are before activating controls. Headings, landmarks, and the address bar are not trivia; they are your map.

      -

      Jamie: What is the one idea that makes the next few steps less mysterious?

      -

      Alex: This is where 1. The Security and quality tab - What It Contains becomes real: every GitHub repository has a Security and quality tab in its navigation bar. That matters in practice: What you see there depends on whether you are a contributor with elevated access or a public viewer.

      -
      -

      Alex: Now bring the learner back to the room. Start with Public viewers see. There is something to understand, something to try, and something that proves the try worked.

      -

      Alex: For a learner, the useful signals are these. Security policy (if the repo has a SECURITY.md). The private vulnerability reporting form (if enabled by the maintainer).

      -

      Jamie: What would you say to someone who is already bracing for this to be too much?

      -

      Alex: Start with Contributors with write or admin access see. There is something to understand, something to try, and something that proves the try worked.

      -

      Alex: The parts worth keeping in working memory are these. Dependabot alerts. Secret scanning alerts. Code scanning alerts. Security advisories. The ability to manage security settings.

      -

      Alex: The useful habit is simple: orient first, act second, verify third. That pause before acting is part of the work.

      -

      Alex: That matters because of the next idea. Start with Learning Cards: The Security and quality tab. There is something to understand, something to try, and something that proves the try worked.

      -

      Alex: On the ground, that means a few things. Use G then S (GitHub keyboard shortcut) to jump directly to the Security and quality tab from any repo page -- much faster than Tab-navigating the full nav bar. The Security and quality tab content varies by your access level -- public viewers see only the security policy and vulnerability reporting form; contributors with write access see alerts. Dependabot alerts, secret scanning alerts, and code scanning alerts are each a separate link inside the Security and quality tab -- use K to navigate between them. The Security and quality tab link sits in the repository's top navigation bar alongside Code, Issues, PRs, and Actions -- zoom in if the tab labels are small. Alert severity badges (Critical, High, Medium, Low) use colored labels -- each badge also includes the severity word, so color is not the only indicator. If the Security and quality tab shows "No alerts," that is good news -- look for the green shield icon next to the tab name as confirmation.

      +

      Jamie: Let's pause on Filtering by repository or organization. What should a learner take away from it?

      +

      Alex: Keep the learner anchored in Filtering by repository or organization. At the top of the notification list there is a filter/search field. This is the part to say slowly: Click the filter/search box at the top of the notification list and type a repository or organization name.

      +

      Alex: First, press F or E to reach the filter input. Then, focus Mode → type repo name or org name. After that, results filter in real time. Finally, press Esc to clear the filter. It is like walking a hallway with named doors: read the sign, enter the right room, then confirm where you landed.

      +

      Jamie: Before we leave Filtering by repository or organization, what is the practical point?

      +

      Alex: First, quick Nav F to reach the filter input. Then, vO+Shift+Down to interact → type repo or org name. After that, press Esc to clear the filter and VO+Shift+Up to stop interacting. The rhythm is simple: orient, act, verify, then continue.

      +

      Jamie: Let's pause on The "mark all as done" workflow. What should a learner take away from it?

      +

      Alex: The reason The "mark all as done" workflow matters is that after a busy day or coming back from time away, clear your inbox methodically.

      +

      Alex: First, open Notifications inbox. Then, tab to "Mark all as done" button → Enter (clears everything at once). After that, then use the "Done" filter to retrieve any you want to revisit. The rhythm is simple: orient, act, verify, then continue.

      +

      Jamie: Let's pause on Muting a noisy thread. What should a learner take away from it?

      +

      Alex: Start with Muting a noisy thread: If a thread generates too many notifications. The next useful detail is this: Screen reader users (NVDA / JAWS - Windows).

      +

      Alex: First, open the issue or PR page. Then, in the right sidebar, scroll to the Notifications section. After that, click Unsubscribe - you will stop receiving notifications from this thread. Finally, alternatively, from the inbox: hover over the notification row and click the mute icon (or the … menu). Think of it as a rail line: each stop confirms you are still on the right route before the next one.

      +

      Jamie: Before we leave Muting a noisy thread, what is the practical point?

      +

      Alex: First, open the notification. Then, on the issue/PR page, navigate the sidebar to the Notifications section (H or D). After that, activate the Unsubscribe button. Finally, or from the inbox: focus the notification → press M to mute. Treat it like a recipe: do not add the next ingredient until the previous one is actually in the bowl.

      +

      Jamie: Let's pause on Dealing with @mentions you didn't expect. What should a learner take away from it?

      +

      Alex: Here is the plain-English version of Dealing with @mentions you didn't expect. If you were @mentioned in an unfamiliar thread. It is like learning a transit route. The names of the stops matter because they tell you whether you are still going the right direction.

      +

      Alex: First, read the thread for context before responding. Then, 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. After that, unsubscribe after reading if you don't need to stay in the loop. Treat it like a recipe: do not add the next ingredient until the previous one is actually in the bowl.

      Jamie: If I am listening before the workshop starts, what should settle in my mind first?

      -

      Alex: Here is the plain-English version of 2. Dependabot - Automated Dependency Updates. Dependabot is GitHub's automated dependency monitoring and update system.

      -

      Alex: This is where the talk moves from concept to action. This is where Dependabot Alerts becomes real: when a known security vulnerability (CVE - Common Vulnerability and Exposure) is discovered in a package your project depends on, GitHub creates a Dependabot alert.

      -

      Jamie: Turn that into a path someone can follow.

      -

      Alex: Start with What to do as a contributor when you see an alert. There is something to understand, something to try, and something that proves the try worked.

      -

      Alex: First, read the advisory to understand the vulnerability scope. Then, check whether the project actually uses the vulnerable code path. After that, the fix is almost always: update the dependency to the fixed version. Finally, dependabot Security Updates may have already opened a PR - check the PRs tab. It is like walking a hallway with named doors: read the sign, enter the right room, then confirm where you landed.

      -
      -

      Alex: Before the learner moves on. The reason Dependabot Security Updates matters is that if enabled, Dependabot automatically opens a PR to update the vulnerable dependency. That gives the learner a simple foothold: as a contributor with access, reviewing and merging these Dependabot PRs is a high-value, low-risk way to contribute. The interface gets friendlier when it stops being a wall of controls and starts being a set of named places.

      -

      Jamie: Give me the version that sounds like an instructor, not a manual.

      -

      Alex: Start with Dependabot Version Updates: Beyond security fixes, Dependabot can be configured to open PRs keeping all dependencies at their latest versions (not just security fixes). The next useful detail is this: This is configured in.github/dependabot.yml.

      -

      Alex: Hold that next to this. Here is the plain-English version of 3. Secret Scanning - Preventing Credential Leaks. Secret scanning detects if you accidentally commit tokens, API keys, passwords, or other credentials to a repository.

      +

      Alex: Start with Learning Cards: Managing Notifications at Scale. There is something to understand, something to try, and something that proves the try worked.

      +

      Alex: That shows up in the workshop in a few specific ways. 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. 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.

      +

      Alex: That connects to another useful point. Keep the learner anchored in Notification Settings - Per Your Account. Global notification preferences are at https://github.com/settings/notifications.

      Jamie: Where do you want a learner to place their attention here?

      -

      Alex: This is where Push Protection (Real-Time Prevention) becomes real: push Protection intercepts a git push before it reaches GitHub and blocks it if it detects a known secret pattern.

      -

      Jamie: What is the ordered workflow?

      -

      Alex: Keep the learner anchored in What to do. Best practice: Use environment variables for secrets, never hardcode them. A good GitHub workflow is like a well-run meeting: everyone knows the topic, the next action, and who has the floor.

      -

      Alex: First, remove the secret from the file immediately. Then, rotate the exposed credential (GitHub will automatically revoke detected GitHub tokens). After that, if it was a false positive, you can bypass with justification - but investigate first. It is like walking a hallway with named doors: read the sign, enter the right room, then confirm where you landed.

      -

      Jamie: Let's pause on Secret Scanning Alerts. What should a learner take away from it?

      -

      Alex: The reason Secret Scanning Alerts matters is that for public repositories, GitHub scans all existing commits and creates alerts for any detected secrets. That gives the learner a simple foothold: these appear in Security → Secret scanning.

      +

      Alex: The reason Starring vs. Watching - What Is the Difference? matters is that new contributors often confuse these two. That gives the learner a simple foothold: they appear next to each other on every repository page and do completely different things.

      +

      Alex: A solid pull request habit is to separate three questions: what changed, why it changed, and what still needs review. That keeps the conversation useful instead of noisy.

      +

      Alex: Now bring the learner back to the room. Start with Starring a Repository: Starring is GitHub's equivalent of a bookmark + public endorsement. The next useful detail is this: The star count on a repository is a community signal of popularity. Think of it like entering a new building: first you find the lobby, then the room, then the door you actually need.

      +

      Jamie: Let's pause on Common Mistake: Accidental Watching. What should a learner take away from it?

      +

      Alex: Here is the plain-English version of 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. Put another way, 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.

      -

      Alex: Here is the practical turn. Start with Learning Cards: Secret Scanning. There is something to understand, something to try, and something that proves the try worked.

      -

      Alex: Here is what that changes in practice. If your git push is blocked with "GH013: Repository rule violations found," the terminal output lists the exact file, line number, and secret type -- read the error lines carefully. After removing the secret from your code, use environment variables instead (process.env.GITHUB TOKEN) -- your screen reader will confirm the variable name in the code. Secret scanning alerts appear under Security and quality tab, Secret scanning -- navigate with T to reach the alert table, then arrow keys to read each row. Push Protection error messages appear in your terminal with red text -- increase terminal font size to read the file path, line number, and secret type clearly. The secret scanning alert list in the Security and quality tab uses a table layout -- zoom in to read the Secret type and Location columns. Environment variable names in code (like process.env.GITHUB TOKEN) are easier to spot when syntax highlighting is enabled in your editor theme.

      -

      Jamie: Let's pause on 4. Code Scanning and CodeQL. What should a learner take away from it?

      -

      Alex: Here is the plain-English version of 4. Code Scanning and CodeQL. Code scanning uses static analysis to find security vulnerabilities in the code itself (not dependencies). Put another way, GitHub's built-in tool is CodeQL, which understands the code's logic and can detect.

      -

      Alex: The room should hear these as checkpoints. SQL injection risks. Cross-site scripting (XSS) vulnerabilities. Path traversal issues. Insecure cryptography usage.

      -

      Alex: Keep the thread going. This is where Reading a Code Scanning Alert becomes real: as a contributor: Code scanning alerts are excellent, well-scoped contribution opportunities. That matters in practice: Each alert shows you the exact file, line, and the data flow causing the issue. The workshop is closer to rehearsal than lecture. You hear the move, try the move, and then check what changed.

      +

      Alex: Another way to ground it. This is where How to silence a repository you accidentally over-subscribed to becomes real: this immediately reduces notifications from that repository to only threads you personally participated in.

      +

      Jamie: Let's pause on Learning Cards: Starring vs. Watching. What should a learner take away from it?

      +

      Alex: Start with Learning Cards: Starring vs. Watching. There is something to understand, something to try, and something that proves the try worked.

      +

      Alex: These are the details that keep the idea from floating away. 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. 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.

      +

      Alex: This is the part worth saying out loud. Start with NVDA. There is something to understand, something to try, and something that proves the try worked.

      +

      Alex: That becomes easier when you listen for these cues. 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.

      -

      Jamie: Let's pause on Where to Find Code Scanning Alerts. What should a learner take away from it?

      -

      Alex: Keep the learner anchored in Where to Find Code Scanning Alerts. Security and quality tab → Code scanning → filter by severity, rule, or file.

      -

      Alex: Another way to ground it. The reason 5. Private Vulnerability Reporting matters is that when you discover a security vulnerability in a project, never report it as a public issue. That gives the learner a simple foothold: a public issue immediately broadcasts the vulnerability to anyone who could exploit it.

      -

      Jamie: Give me the sequence, because order matters here.

      -

      Alex: Start with How to Submit a Private Report. There is something to understand, something to try, and something that proves the try worked.

      -

      Alex: A few details make that real. Severity: Your assessment. Affected versions: Which versions are vulnerable. CVSS score: Optional - the Common Vulnerability Scoring System rating.

      -

      Alex: First, navigate to the repository's Security and quality tab. Then, select "Report a vulnerability" (this button only appears if the maintainer has enabled private reporting). After that, fill in the form. Finally, submit - only the maintainers see your report. Think of it as a rail line: each stop confirms you are still on the right route before the next one.

      +

      Jamie: Let's pause on JAWS. What should a learner take away from it?

      +

      Alex: Start with JAWS. There is something to understand, something to try, and something that proves the try worked.

      +

      Alex: A few details make that real. 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.

      +

      Alex: Hold that next to this. Start with VoiceOver. There is something to understand, something to try, and something that proves the try worked.

      +

      Alex: The parts worth keeping in working memory are these. 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.

      +

      Jamie: Let's pause on The GitHub Mobile App - A Reference Note. What should a learner take away from it?

      +

      Alex: This is where The GitHub Mobile App - A Reference Note becomes real: GitHub has an iOS and Android app that supports push notifications. That matters in practice: While the app itself is not covered as a primary tool in this workshop, it is worth knowing.

      +

      Alex: The room should hear these as checkpoints. 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.

      -

      Jamie: Let's pause on The Responsible Disclosure Process. What should a learner take away from it?

      -

      Alex: Start with The Responsible Disclosure Process. There is something to understand, something to try, and something that proves the try worked.

      -

      Alex: First, maintainers acknowledge your report (typically within 1-7 days for active projects). Then, they may ask follow-up questions in the private advisory thread. After that, they develop and test a fix. Finally, they request a CVE (Common Vulnerability and Exposure) number from GitHub. Treat it like a recipe: do not add the next ingredient until the previous one is actually in the bowl.

      -

      Jamie: Before we leave The Responsible Disclosure Process, what is the practical point?

      -

      Alex: First, they publish a new release with the fix. Then, they publish a public security advisory - you may be credited as the reporter. After that, the CVE is published publicly (usually 90 days after report or after the fix is released). It is a checklist, but a meaningful one: every item creates evidence that the next step is safe.

      -

      Jamie: Let's pause on What If the Maintainer Doesn't Respond? What should a learner take away from it?

      -

      Alex: This is where What If the Maintainer Doesn't Respond? becomes real: if a maintainer doesn't respond within a reasonable time (30-90 days is the standard window).

      -

      Alex: First, send a follow-up in the private advisory thread. Then, contact GitHub directly if the issue is critical (GitHub can assist with coordinated disclosure). After that, follow the project's SECURITY.md for their stated disclosure policy. It is a checklist, but a meaningful one: every item creates evidence that the next step is safe.

      -

      Alex: The next layer is this. Keep the learner anchored in 6. The SECURITY.md File. A SECURITY.md file at the repository root defines the project's security policy. This is the part to say slowly: accessibility-agents's security policy: community-access/accessibility-agents has a SECURITY.md that points to GitHub's private advisory form.

      -

      Alex: These are the details that keep the idea from floating away. Supported versions: Which versions receive security patches. Reporting instructions: How to report a vulnerability (email, private advisory form, etc.). Response timeline: How quickly maintainers aim to respond. Disclosure policy: When the project will publish a fix publicly.

      +

      Jamie: Let's pause on Try It: Tame Your Inbox. What should a learner take away from it?

      +

      Alex: Keep the learner anchored in Try It: Tame Your Inbox. Time: 2 minutes What you need: Browser, signed in to GitHub. This is the part to say slowly: Go to github.com/notifications and practice. A good GitHub workflow is like a well-run meeting: everyone knows the topic, the next action, and who has the floor.

      +

      Alex: First, scan your inbox - Press H and Tab to navigate through notifications. Each one shows the repo name, type (issue/PR), and title. Then, mark one as done - Find a notification you've already read. Press E to mark it as done. It disappears from the list. After that, 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. It is like walking a hallway with named doors: read the sign, enter the right room, then confirm where you landed.

      +

      Jamie: Let's pause on What You Accomplished Today. What should a learner take away from it?

      +

      Alex: The reason What You Accomplished Today matters is that day 1 is complete -- and you did a lot. That gives the learner a simple foothold: here is every skill you practiced, mapped to the chapter where you learned it and the evidence you created along the way.

      +

      Alex: Keep the teaching thread moving. Start with 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. The next useful detail is this: You navigated a complex platform, created real contributions, and collaborated with other people in a shared codebase.

      -

      Jamie: Let's pause on Navigating to a Repository's SECURITY.md. What should a learner take away from it?

      -

      Alex: Start with Navigating to a Repository's SECURITY.md. There is something to understand, something to try, and something that proves the try worked.

      -

      Alex: First, security and quality tab → Policies section → "Security policy" link. Then, or directly: https://github.com/owner/repo/security/policy. The rhythm is simple: orient, act, verify, then continue.

      -

      Alex: Treat examples as spoken recipes, not decorations. You may hear something like Security and quality tab → H → "Policy" heading → Link: "Security policy" → Enter. Read the command, understand what it changes, then run it only when the repository state matches the lesson.

      -

      Alex: This is the part worth saying out loud. Start with 7. Software Bill of Materials (SBOM): An SBOM is a machine-readable inventory of every component (libraries, packages, dependencies) in a software project. The next useful detail is this: It is increasingly required by enterprise and government organizations for supply chain security compliance. Think of it like entering a new building: first you find the lobby, then the room, then the door you actually need.

      -

      Jamie: Let's pause on Exporting an SBOM from GitHub. What should a learner take away from it?

      -

      Alex: Start with Exporting an SBOM from GitHub. There is something to understand, something to try, and something that proves the try worked.

      -

      Alex: That becomes easier when you listen for these cues. Your organization requires SBOM documentation before adopting an open source dependency. You're auditing a project's complete dependency chain. You want to identify license compatibility for a commercial product.

      -

      Alex: First, navigate to the repository's Insights tab. Then, select "Dependency graph". After that, select "Export SBOM" button (top right of the Dependency graph page). Finally, GitHub generates a SPDX-format JSON file listing all dependencies with their versions and licenses. Treat it like a recipe: do not add the next ingredient until the previous one is actually in the bowl.

      +

      Jamie: Let's pause on Confidence Check. What should a learner take away from it?

      +

      Alex: Here is the plain-English version of Confidence Check. Before you close your laptop, take two minutes to answer these questions in your Chapter 10 challenge issue. Put another way, there are no wrong answers -- this is for you.

      +

      Alex: First, which chapter felt the most natural to you? Which one do you want to revisit? Then, can you explain what a pull request does to someone who has never used GitHub? After that, if you saw a merge conflict right now, would you know where to start? Finally, what is one thing you want to try on GitHub this week that you did not get to today? Treat it like a recipe: do not add the next ingredient until the previous one is actually in the bowl.

      +

      Alex: Keep the teaching thread moving. This is where Your Challenge Progress becomes real: look at how many challenge issues you completed today. That matters in practice: Each one represents a skill you did not just read about -- you practiced it, posted evidence, and moved on. The workshop is closer to rehearsal than lecture. You hear the move, try the move, and then check what changed.

      +

      Jamie: Let's pause on Learning Cards: What You Accomplished Today. What should a learner take away from it?

      +

      Alex: Start with Learning Cards: What You Accomplished Today. There is something to understand, something to try, and something that proves the try worked.

      +

      Alex: The practical takeaway is this. 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. 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.

      -

      Alex: That connects to another useful point. This is where 9. Security and Accessibility Agents becomes real: accessibility Agents' /security-dashboard slash command gives you a quick security overview without visiting the Security and quality tab in the browser.

      -

      Jamie: Let's pause on Sample output. What should a learner take away from it?

      -

      Alex: Keep the learner anchored in Sample output. Next: Appendix Q: GitHub Actions Back: Appendix O: Branch Protection Teaching chapter: Chapter 08: Open Source Culture.

      +

      Alex: Keep the teaching thread moving. The reason What Day 2 Adds matters is that see also: Chapter 11: VS Code Interface is where Day 2 begins -- have VS Code installed and ready. That gives the learner a simple foothold: on Day 1, you worked entirely on GitHub.com.

      +

      Jamie: Let's pause on Between Days. What should a learner take away from it?

      +

      Alex: Start with 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. The next useful detail is this: GitHub Skills courses use bot-driven feedback inside pull requests.

      +

      Alex: First, explore your notification settings. Now that you understand how notifications work, visit github.com/settings/notifications and customize your email and web preferences. There is no wrong configuration -- just find what feels manageable. Then, 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. After that, try a GitHub Skills course. GitHub Skills 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 for the full list of recommended courses. Think of it as a rail line: each stop confirms you are still on the right route before the next one.

      +

      Alex: Keep the teaching thread moving. Here is the plain-English version of You Already Know More Than You Think. Think about where you started this morning. Put another way, 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. It is like learning a transit route. The names of the stops matter because they tell you whether you are still going the right direction.

      Jamie: What should people carry with them after this?

      Alex: Carry the map. Know what page or tool you are in, know which action you are taking, and know what confirmation should follow. If the confirmation is missing, pause. That pause is not wasted time; it is professional judgment.

      Jamie: That is a better way to say it than just follow the steps.

      -

      Alex: Right. Steps matter, but understanding wins. That is episode 29. Next in the series is episode 30, where we keep building the same contributor muscles.

      +

      Alex: Right. Steps matter, but understanding wins. That is episode 10. Next in the series is episode 11, where we keep building the same contributor muscles.

      -

      Episode 30: VS Code Accessibility Reference

      -

      Complete accessibility settings, audio signals, diff viewer, and screen reader configs.

      -

      Based on: Appendix G: VS Code Accessibility Reference

      +

      28. Challenge 09: Merge Day

      +

      Final PR readiness, review signals, merging, and verifying linked issue closure.

      +

      Practice focus: Day 1 stretch

      Audio and transcript are being regenerated for this episode.

      -Read Transcript - Episode 30: VS Code Accessibility Reference +Read Transcript - Challenge 09: Merge Day

      Transcript

      -

      Alex: This is Git Going with GitHub, episode 30: VS Code Accessibility Reference. I am Alex. By the end of this episode, VS Code Accessibility Reference should feel less like a wall of GitHub words and more like a set of moves you can trust.

      -

      Jamie: And I am Jamie. I am here for the practical questions: what should I listen for, what can go wrong, and what is the next calm move?

      +

      Alex: This is Challenge Coach for Merge Day. I am Alex, and we are going to teach the move before asking you to prove it.

      +

      Jamie: And I am Jamie. I will translate the challenge into the practical questions learners actually have while doing it.

      -

      Alex: Today we are working on this: Complete accessibility settings, audio signals, diff viewer, and screen reader configs. I want the learner to leave with a mental map, not just a remembered path through buttons.

      -

      Jamie: So the goal is understanding first, then action, then confirmation.

      -

      Alex: Right. We are building a rhythm: orient yourself, take one intentional action, then verify what changed before moving on.

      +

      Alex: Final PR readiness, review signals, merging, and verifying linked issue closure. That is the task layer. The teaching layer is understanding why the move belongs in a contributor workflow.

      +

      Jamie: So evidence is not just proof for the facilitator. It is part of how the learner understands the workflow.

      +

      Alex: Right. A good challenge produces something inspectable: a comment, issue, branch, commit, pull request, review, or clear note about what happened.

      -

      Jamie: Okay, set the room for us. What are we walking into?

      -

      Alex: Start with Complete Technical Reference for Screen Reader Users: Purpose: This appendix provides comprehensive technical documentation for all VS Code accessibility features, settings, and keyboard shortcuts. The next useful detail is this: The main chapters cover essentials; this appendix is your complete reference manual.

      -

      Alex: A solid navigation habit is to prove where you are before activating controls. Headings, landmarks, and the address bar are not trivia; they are your map.

      -

      Alex: The next layer is this. Start with Learning Cards: VS Code Accessibility Reference Overview. There is something to understand, something to try, and something that proves the try worked.

      -

      Alex: The practical anchors are these. This appendix is your lookup manual -- use Ctrl+G (Go to Line) or Ctrl+Shift+O (Go to Symbol) to jump directly to a setting name. Every table is structured with headers; use T in browse mode to jump between tables, then arrow through rows. Bookmark this file in VS Code (Ctrl+K Ctrl+K) so you can return instantly when you need a setting path. Increase editor font size (Ctrl+=) before scanning the long settings tables -- column values are easier to compare at larger sizes. Use the Minimap (if sighted enough) or breadcrumbs bar to orient within this large reference file. High-contrast themes make the table grid lines and code spans easier to distinguish from body text.

      -

      Jamie: What is the one idea that makes the next few steps less mysterious?

      -

      Alex: This is where 1. Complete Accessibility Settings Reference becomes real: all settings can be accessed via Settings UI (Ctrl+,) or by editing settings.json directly (Ctrl+Shift+P → "Open User Settings JSON").

      +

      Jamie: What makes this practice feel low-stakes but still real?

      +

      Alex: Start with Challenge 9: Merge Day: What you will do: Get your Day 1 PR merged into main, verify your changes appear, and celebrate completing Day 1.

      +

      Alex: A solid Git habit is to know which branch you are on, what changed, and what confirmation you expect before you run the next command.

      +

      Alex: The next layer is this. Here is the plain-English version of Merge checklist. Before merging, verify everything is ready. It is like learning a transit route. The names of the stops matter because they tell you whether you are still going the right direction.

      +

      Alex: The practical anchors are these. [ ] Your PR has no merge conflicts (if it does, resolve them first -- see Challenge 7). [ ] Your PR links to your issue with Closes XX. [ ] Your commit message is meaningful. [ ] You have reviewed your own changes one last time.

      +

      Jamie: What does the learner do first, second, and then after that?

      +

      Alex: Start with Instructions. There is something to understand, something to try, and something that proves the try worked.

      +

      Alex: First, open your PR on the Pull requests tab. Then, if all checks pass (green checkmarks), you are ready to merge. After that, select Merge pull request (your facilitator may handle this step). Finally, after the merge, go to the Code tab and verify your changes appear on the main branch. It is a checklist, but a meaningful one: every item creates evidence that the next step is safe.

      +

      Jamie: Turn that into a path someone can follow.

      +

      Alex: First, check that your linked issue was automatically closed. It is like walking a hallway with named doors: read the sign, enter the right room, then confirm where you landed.

      -

      Alex: Now bring the learner back to the room. Keep the learner anchored in 2. Audio Cues - All Options. Audio cues provide non-verbal feedback through sound. This is the part to say slowly: Each cue can be configured independently.

      +

      Alex: Now bring the learner back to the room. Keep the learner anchored in Day 1 celebration. Take a moment to appreciate what you accomplished.

      +

      Alex: For a learner, the useful signals are these. You navigated a real GitHub repository. You filed an issue and had a conversation. You created a branch, made changes, and opened a pull request. You survived a merge conflict. You contributed to an open source community.

      Jamie: What would you say to someone who is already bracing for this to be too much?

      -

      Alex: The reason Accessing Audio Cue Settings matters is that settings UI: Ctrl+, → search "audio cue". That gives the learner a simple foothold: settings.json: Edit directly (see Section 7).

      +

      Alex: The reason Peer simulation check matters is that leave a wrap-up comment on the peer-simulation issue or PR. That gives the learner a simple foothold: if you have real buddy access, congratulate your buddy on completing Day 1.

      Alex: The useful habit is simple: orient first, act second, verify third. That pause before acting is part of the work.

      Jamie: Give me the sequence, because order matters here.

      -

      Alex: Start with Customizing Signal Sounds: Advanced feature: You can replace default sounds with custom audio files. Think of it like entering a new building: first you find the lobby, then the room, then the door you actually need.

      -

      Alex: First, ctrl+Shift+P → "Preferences: Open User Settings (JSON)". Then, add custom sound paths. Think of it as a rail line: each stop confirms you are still on the right route before the next one.

      +

      Alex: Start with What happens at merge: When your PR from Challenge 6 (or a later challenge) is approved and merged. Think of it like entering a new building: first you find the lobby, then the room, then the door you actually need.

      +

      Alex: First, the "Merge pull request" button turns green. Then, after clicking it, your branch's commits appear on main. After that, the linked issue (from Closes N) automatically closes. Finally, the PR status changes to "Merged" with a purple icon. Think of it as a rail line: each stop confirms you are still on the right route before the next one.

      -

      Jamie: If I am listening before the workshop starts, what should settle in my mind first?

      -

      Alex: Start with Sound file requirements. There is something to understand, something to try, and something that proves the try worked.

      -

      Alex: Here is what that changes in practice. Format: WAV, MP3, or OGG. Duration: Keep under 2 seconds. Volume: Normalize to avoid clipping.

      -

      Alex: This is where the talk moves from concept to action. This is where 3. Accessible Diff Viewer - Complete Guide becomes real: the Accessible Diff Viewer presents file diffs as a structured, line-by-line list instead of a visual side-by-side view.

      +

      Jamie: What should the learner prove to themselves after each small task?

      +

      Alex: Here is the plain-English version of Example evidence. Your Day 1 recap evidence might.

      +

      Alex: This is where the talk moves from concept to action. Start with Alternate approaches. There is something to understand, something to try, and something that proves the try worked.

      +

      Alex: The room should hear these as checkpoints. Post your recap as a comment on your challenge issue. Share a summary in the workshop discussion channel. Write a short reflection in a new file on your branch.

      Alex: A solid pull request habit is to separate three questions: what changed, why it changed, and what still needs review. That keeps the conversation useful instead of noisy.

      -

      Jamie: Where do you want a learner to place their attention here?

      -

      Alex: Start with When to Use Accessible Diff Viewer. There is something to understand, something to try, and something that proves the try worked.

      -

      Alex: These are the details that keep the idea from floating away. Reviewing pull request changes. Resolving merge conflicts. Comparing file versions (Timeline view). Reviewing Copilot-generated edits. Any time you need to understand what changed in a file.

      +

      Jamie: What is the one idea that makes the next few steps less mysterious?

      +

      Alex: Keep the learner anchored in What matters. The learning objective is completing the Day 1 loop: issue to branch to commit to PR to merge. This is the part to say slowly: If you merged at least one PR and can articulate what you learned, you completed this challenge.

      -

      Alex: Before the learner moves on. The reason Top-level structure matters is that the Accessible Diff Viewer starts with a header showing the file path and change summary. That gives the learner a simple foothold: it then shows each hunk (changed section) in order. The interface gets friendlier when it stops being a wall of controls and starts being a set of named places.

      +

      Alex: Before the learner moves on. The reason Creating, Reviewing, and Merging Pull Requests with a Screen Reader matters is that see also: Chapter 15: Code Review covers the full review workflow including multi-file diffs and suggested changes. That gives the learner a simple foothold: pull requests are where your work becomes a contribution. The interface gets friendlier when it stops being a wall of controls and starts being a set of named places.

      +

      Jamie: How should they picture the shape of the workshop?

      +

      Alex: Start with Workshop Recommendation (Chapter 6): Chapter 6 is the first PR-validated chapter where students convert issue work into merge-ready contributions.

      +

      Alex: A few details make that real. There are 3. Each challenge should take under 10 minutes each. The evidence is PR metadata, bot checks, and merged issue linkage. The pattern is small change - linked PR - green checks.

      Jamie: How would you walk the room through that step by step?

      -

      Alex: Start with NVDA/JAWS. There is something to understand, something to try, and something that proves the try worked.

      -

      Alex: First, open diff: Enter on file in Source Control, or F7 in an open diff. Then, alt+F2 to open Accessible Diff Viewer. After that, navigate with Up/Down Arrow (line by line). Finally, use H key to jump between hunks (each hunk has a heading). Think of it as a rail line: each stop confirms you are still on the right route before the next one.

      -

      Jamie: What does the learner do first, second, and then after that?

      -

      Alex: First, escape to close and return to editor. Treat it like a recipe: do not add the next ingredient until the previous one is actually in the bowl.

      -

      Jamie: Turn that into a path someone can follow.

      -

      Alex: Start with VoiceOver. There is something to understand, something to try, and something that proves the try worked.

      -

      Alex: First, vO+Arrow to navigate to diff file → VO+Space to open. Then, option+F2 for Accessible Diff Viewer. After that, vO+Arrow keys to navigate lines. Finally, vO+Command+H to jump between hunk headings. Treat it like a recipe: do not add the next ingredient until the previous one is actually in the bowl.

      -

      Jamie: What is the ordered workflow?

      -

      Alex: First, escape to close. It is a checklist, but a meaningful one: every item creates evidence that the next step is safe.

      -
      -

      Jamie: Give me the version that sounds like an instructor, not a manual.

      -

      Alex: This is where Understanding Context Lines becomes real: the diff shows 3 unchanged lines before and after each change for context. That matters in practice: These are announced as "Unchanged: [content]".

      -

      Jamie: How do you keep commands from becoming magic words?

      -

      Alex: Keep the learner anchored in Example. The unchanged lines help you understand where in the file the change occurred. A good GitHub workflow is like a well-run meeting: everyone knows the topic, the next action, and who has the floor.

      -

      Alex: Treat examples as spoken recipes, not decorations. You may hear something like Hunk 1 of 3 - lines 42-48; Unchanged: Screen Reader Setup; Unchanged:; - Removed: This guide covers NVDA only.; + Added: This guide covers NVDA, JAWS, and VoiceOver.; Unchanged:; Unchanged: Installing NVDA. Read the command, understand what it changes, then run it only when the repository state matches the lesson.

      -

      Jamie: Let's pause on Inline view (recommended for screen readers). What should a learner take away from it?

      -

      Alex: Start with Inline view (recommended for screen readers). There is something to understand, something to try, and something that proves the try worked.

      -

      Alex: The parts worth keeping in working memory are these. All changes in a single editor. Removed lines followed by added lines. Easier to navigate with screen reader reading commands.

      +

      Alex: Here is the plain-English version of Chapter 6 Challenge Set. This is the first chapter where you edit files and create branches. Put another way, 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.

      +

      Alex: First, create one small branch change - edit a practice file on a new branch. Then, open a linked PR - use the PR template and include Closes XX. After that, pass required checks - respond to bot feedback until all required checks pass. Treat it like a recipe: do not add the next ingredient until the previous one is actually in the bowl.

      -

      Alex: Here is the practical turn. Start with Side-by-side view (default, visual). There is something to understand, something to try, and something that proves the try worked.

      -

      Alex: On the ground, that means a few things. Left panel: original file. Right panel: modified file. Requires navigating between panels.

      -

      Jamie: Let's pause on To switch to inline view. What should a learner take away from it?

      -

      Alex: Start with To switch to inline view. There is something to understand, something to try, and something that proves the try worked.

      -

      Alex: First, open Settings: Ctrl+,. Then, search: "diffEditor.renderSideBySide". After that, uncheck the box (or set to false in settings.json). Treat it like a recipe: do not add the next ingredient until the previous one is actually in the bowl.

      -

      Alex: Keep the thread going. Start with Learning Cards: Accessible Diff Viewer. There is something to understand, something to try, and something that proves the try worked.

      -

      Alex: The room should hear these as checkpoints. Press F7 in any diff editor to jump to the first changed hunk -- then F7 / Shift+F7 to move between hunks. Use Alt+F2 (Accessible View) to read the full diff in a structured, non-streaming pane with proper line prefixes. Switch to inline diff view (diffEditor.renderSideBySide: false) so all changes appear in one editor instead of two panels. Inline diff view places removed and added lines back-to-back with color-coded backgrounds -- increase font size for easier scanning. Enable accessibility.signals.diffLineInserted and diffLineDeleted for audio feedback as you arrow through changed lines. Zoom the diff editor independently with Ctrl+= if the surrounding UI is already at a comfortable size.

      -
      -

      Jamie: Let's pause on Recommended NVDA settings. What should a learner take away from it?

      -

      Alex: Start with Recommended NVDA settings. There is something to understand, something to try, and something that proves the try worked.

      -

      Alex: That becomes easier when you listen for these cues. NVDA Menu → Preferences → Settings → Browse Mode. "Maximum length of text on a single line": 10000. "Automatic focus mode for focus changes": Checked. "Automatic focus mode for caret movement": Unchecked. "Report tooltips": Unchecked (reduces interruptions; use Alt+F2 instead). "Report notifications": Checked.

      -

      Alex: First, browse Mode settings. Then, object Presentation. After that, speech settings. Finally, input Composition. It is like walking a hallway with named doors: read the sign, enter the right room, then confirm where you landed.

      -

      Alex: Another way to ground it. Start with NVDA add-ons for VS Code. There is something to understand, something to try, and something that proves the try worked.

      -

      Alex: A few details make that real. Focus Highlight - shows focus location visually (helpful for sighted trainers). IndentNav - navigate by indentation level (useful for Python, YAML).

      -

      Jamie: Let's pause on Recommended JAWS settings. What should a learner take away from it?

      -

      Alex: Start with Recommended JAWS settings. There is something to understand, something to try, and something that proves the try worked.

      -

      Alex: That shows up in the workshop in a few specific ways. "Auto Forms Mode": Checked. "ARIA Live Region Verbosity": Polite or Assertive (depending on preference). "Report tooltip text": Unchecked (use Alt+F2 instead). "Punctuation Level": Most (for code). "Speak Long Lines Continuously": Yes. "Blank Line Announcement": Tone (less verbose than speech).

      -

      Alex: First, settings Center → HTML/PDF/Accessibility. Then, settings Center → Reading. After that, settings Center → Text Processing. Think of it as a rail line: each stop confirms you are still on the right route before the next one.

      +

      Jamie: What is the ordered workflow?

      +

      Alex: This is where Challenge 6.1 Step-by-Step: Create One Small Branch Change becomes real: edit one of the practice files and save your change on a new branch. That matters in practice: your Learning Room repository on GitHub.com, using the web editor.

      +

      Alex: That shows up in the workshop in a few specific ways. 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. 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.

      +

      Alex: First, 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). Then, open the file and activate the pencil icon (Edit this file) button. After that, the file opens in the web editor. Make your change. For. Finally, keep your change small and focused. Edit only what the issue asks for. It is a checklist, but a meaningful one: every item creates evidence that the next step is safe.

      +

      Jamie: Let's pause on Challenge 6.1 Step-by-Step: Create One Small Branch Change. What should a learner take away from it?

      +

      Alex: First, after editing, activate the Commit changes button (green button above the editor). Then, a dialog appears. In the Branch name field, type: fix/yourname-issueXX (replace yourname with your GitHub username, and XX with the issue number). After that, select Create a new branch for this commit and start a pull request. Finally, activate Propose changes. It is like walking a hallway with named doors: read the sign, enter the right room, then confirm where you landed.

      +

      Jamie: Let's pause on Challenge 6.2 Step-by-Step: Open a Linked PR. What should a learner take away from it?

      +

      Alex: Keep the learner anchored in Challenge 6.2 Step-by-Step: Open a Linked PR. AI agents do not just deploy code directly; they submit pull requests. This is the part to say slowly: Learning to edit a file, format it in Markdown, and review a PR today prepares you to audit and approve AI-generated changes tomorrow. A good GitHub workflow is like a well-run meeting: everyone knows the topic, the next action, and who has the floor.

      +

      Alex: The parts worth keeping in working memory are these. "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". A summary of what you changed and why (at least 50 characters).

      +

      Alex: First, in the Title field, write a short description of your change. Then, in the Body field, use the PR template if one is provided. Make sure to. After that, verify the base branch is main and the compare branch is your fix/yourname-issueXX branch. Finally, activate the Create pull request button. It is like walking a hallway with named doors: read the sign, enter the right room, then confirm where you landed.

      +

      Jamie: Let's pause on Challenge 6.3 Step-by-Step: Pass Required Checks. What should a learner take away from it?

      +

      Alex: The reason Challenge 6.3 Step-by-Step: Pass Required Checks matters is that read bot feedback, fix any issues it finds, and get all required checks to pass. That gives the learner a simple foothold: the Conversation tab of your open pull request.

      +

      Alex: On the ground, that means a few things. 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.

      +

      Alex: First, wait approximately 30 seconds after opening the PR. The bot posts a validation comment. Then, read the bot comment carefully. It checks. After that, if the bot reports failures. Finally, repeat step 3 until all required checks show a green checkmark. The rhythm is simple: orient, act, verify, then continue.

      +

      Jamie: Before we leave Challenge 6.3 Step-by-Step: Pass Required Checks, what is the practical point?

      +

      Alex: First, when all checks pass, request a review from a peer or the facilitator. Think of it as a rail line: each stop confirms you are still on the right route before the next one.

      -

      Alex: This is the part worth saying out loud. Here is the plain-English version of JAWS scripts for VS Code. Custom JAWS scripts exist for VS Code. Put another way, check: jaws-vscode-scripts (GitHub) for community-maintained scripts. It is like learning a transit route. The names of the stops matter because they tell you whether you are still going the right direction.

      -

      Jamie: Let's pause on Recommended VoiceOver Utility settings. What should a learner take away from it?

      -

      Alex: Start with Recommended VoiceOver Utility settings. There is something to understand, something to try, and something that proves the try worked.

      -

      Alex: For a learner, the useful signals are these. "Punctuation": All (for code and Markdown). "Capitalization": Speak cap (useful for acronyms and code). "Reading Units": Set to sentenceboundary for prose, word for code. "Content Changes": On (for live regions like Copilot Chat). "Status Messages": On. "Quick Nav": OFF when inside editor (use Left+Right Arrow to toggle).

      -

      Alex: First, verbosity → Text. Then, verbosity → Announcements. After that, navigation. It is a checklist, but a meaningful one: every item creates evidence that the next step is safe.

      -

      Alex: That connects to another useful point. Keep the learner anchored in Quick Nav navigation (when enabled). Quick Nav should be OFF when editing text (conflicts with text navigation).

      +

      Alex: Here is the practical turn. Start with Expected Outcomes. There is something to understand, something to try, and something that proves the try worked.

      +

      Alex: Here is what that changes in practice. Student opens a focused PR that maps to one issue. Student uses Closes XX correctly. Student can interpret bot feedback and improve the PR.

      +

      Jamie: Let's pause on If You Get Stuck. What should a learner take away from it?

      +

      Alex: Start with If You Get Stuck. There is something to understand, something to try, and something that proves the try worked.

      +

      Alex: First, confirm your PR includes Closes XX in title or body. Then, check that changed files are only in learning-room/. After that, open the bot validation comment and resolve one required check at a time. Finally, if checks still fail, ask for peer or facilitator review with the exact error message. Treat it like a recipe: do not add the next ingredient until the previous one is actually in the bowl.

      +

      Jamie: Before we leave If You Get Stuck, what is the practical point?

      +

      Alex: First, finished but not sure you did it right? Compare your work against the Challenge 6 reference solution. It is a checklist, but a meaningful one: every item creates evidence that the next step is safe.

      +

      Alex: Keep the thread going. This is where Learning Moment becomes real: a great PR is small, linked to an issue, and easy to review. That matters in practice: Faster feedback builds confidence and momentum. The workshop is closer to rehearsal than lecture. You hear the move, try the move, and then check what changed.

      -

      Jamie: Let's pause on 5. Complete Keyboard Shortcuts. What should a learner take away from it?

      -

      Alex: The reason 5. Complete Keyboard Shortcuts matters is that for screen reader navigation shortcuts when using GitHub in a browser (NVDA, JAWS, VoiceOver), see Appendix B - Screen Reader Cheat Sheet.

      -

      Alex: That matters because of the next idea. Start with 6. Accessibility Signals Types and Customization: Accessibility signals are events that trigger announcements or audio cues. The next useful detail is this: Beyond audio cues, VS Code has verbal announcements for various events. Think of it like entering a new building: first you find the lobby, then the room, then the door you actually need.

      -

      Jamie: Let's pause on Announcement Verbosity Settings. What should a learner take away from it?

      -

      Alex: Here is the plain-English version of Announcement Verbosity Settings. Control how much information VS Code announces. Put another way, verbose: Announces full context and details minimal: Announces only essential information off: No automatic announcements (use Accessible View manually).

      +

      Jamie: Okay, set the room for us. What are we walking into?

      +

      Alex: Start with Why this feels achievable. There is something to understand, something to try, and something that proves the try worked.

      +

      Alex: These are the details that keep the idea from floating away. Scope is intentionally small. Feedback is immediate and specific. Success is visible (green checks + closed issue).

      +

      Alex: Another way to ground it. The reason About Learning Cards in This Chapter matters is that this chapter provides learning cards: expandable blocks that offer perspective-specific guidance for different ways of working. That gives the learner a simple foothold: not every card appears at every step.

      +

      Jamie: What should they understand before typing anything?

      +

      Alex: Start with Local Git Alternative: The Full Branch-Edit-PR Workflow: If you cloned the learning-room in Block 0 and prefer working locally. The next useful detail is this: The web editor workflow (pencil button, "Propose changes") is the primary path taught in this chapter.

      +

      Alex: Treat examples as spoken recipes, not decorations. You may hear something like cd /Documents/learning-room; git checkout main; git pull origin main; git checkout -b fix/welcome-todos. code docs/welcome.md. Read the command, understand what it changes, then run it only when the repository state matches the lesson.

      -

      Alex: Hold that next to this. This is where Custom Announcement Timing becomes real: control when and how often announcements occur.

      -

      Jamie: Let's pause on Signal Priorities. What should a learner take away from it?

      -

      Alex: Keep the learner anchored in Signal Priorities. When multiple signals occur simultaneously, VS Code prioritizes them. This is the part to say slowly: This prevents overlapping announcements.

      -

      Alex: First, errors (highest priority) - always announced. Then, warnings - announced after errors. After that, completions - announced if no errors/warnings. Finally, focus changes - announced last. It is like walking a hallway with named doors: read the sign, enter the right room, then confirm where you landed.

      -

      Alex: Keep the teaching thread moving. Start with Learning Cards: Accessibility Signals. There is something to understand, something to try, and something that proves the try worked.

      -

      Alex: The practical takeaway is this. Start with auto for most signals -- they play only when screen reader mode is active, keeping things quiet otherwise. The lineHasError and taskFailed signals are the highest-value audio cues; enable these first. Use accessibility.signals.volume (0-100) to balance signal volume against your screen reader speech. Audio cues supplement visual indicators you might miss -- enable lineHasWarning and lineHasError for sounds on the current line. The save and format signals confirm file operations completed without needing to check the status bar visually. Pair audio cues with high-contrast gutter icons for a dual-channel (sight + sound) feedback loop.

      +

      Alex: This is the part worth saying out loud. Here is the plain-English version of What Is a Pull Request? A pull request (PR) is a proposal to merge changes from one branch into another. Put another way,.you open a PR to request that those changes be merged into the target branch (usually main). It is like learning a transit route. The names of the stops matter because they tell you whether you are still going the right direction.

      +

      Alex: That becomes easier when you listen for these cues. Edited a file directly on GitHub (web editor). Made changes in your fork. Made changes on a feature branch. What changed - a diff of every file.

      +

      Jamie: Let's pause on Navigating to Pull Requests. What should a learner take away from it?

      +

      Alex: This is where Navigating to Pull Requests becomes real: global pull requests dashboard: GitHub now shows a global pull requests page at github.com/pulls listing all open PRs across every repository you have access to. That matters in practice: 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).

      +

      Alex: The practical takeaway is this. 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.

      +

      Alex: First, d → "Repository navigation" landmark. Then, k to navigate tabs → "Pull requests, [N] open". After that, enter to open. Finally, vO+U → Landmarks → navigate to "Repository navigation". It is a checklist, but a meaningful one: every item creates evidence that the next step is safe.

      +

      Jamie: Before we leave Navigating to Pull Requests, what is the practical point?

      +

      Alex: First, quick Nav K or VO+Right to navigate tabs → "Pull requests". Then, vO+Space to open. It is like walking a hallway with named doors: read the sign, enter the right room, then confirm where you landed.

      +

      Jamie: What should happen before anyone copies and runs it?

      +

      Alex: Keep the learner anchored in From a PR notification. If you received a notification about a PR, follow the notification link directly to the PR page. This is the part to say slowly: List and view pull requests from your terminal.

      +

      Alex: Treat examples as spoken recipes, not decorations. You may hear something like 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. Read the command, understand what it changes, then run it only when the repository state matches the lesson.

      -

      Jamie: Let's pause on 7. Settings.json Configuration Examples. What should a learner take away from it?

      -

      Alex: Start with 7. Settings.json Configuration Examples: The configuration examples below are JSON blocks you paste into your settings.json file. The next useful detail is this: To apply a complete set at once, consider using VS Code Profiles -- named configuration bundles that let you switch your entire setup instantly.

      -

      Alex: Keep the teaching thread moving. Here is the plain-English version of For users working heavily with GitHub Copilot. The github.copilot.enable object controls which file types get Copilot suggestions.

      -

      Jamie: Let's pause on Paste this into your settings.json for a balanced screen reader profile. What should a learner take away from it?

      -

      Alex: This is where Paste this into your settings.json for a balanced screen reader profile becomes real: next: Appendix H: GitHub Desktop Back: Appendix F: Git Security Teaching chapter: Chapter 11: VS Code Interface.

      +

      Jamie: If I am listening before the workshop starts, what should settle in my mind first?

      +

      Alex: Start with Learning Cards: Navigating to Pull Requests. There is something to understand, something to try, and something that proves the try worked.

      +

      Alex: The practical takeaway is this. 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. 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.

      +

      Alex: That matters because of the next idea. Start with The Pull Request List Page: The PR list works identically to the Issues list. The next useful detail is this: for screen reader users, - PR list semantics: The PR list does not have individual ARIA item containers with per-item semantics. Think of it like entering a new building: first you find the lobby, then the room, then the door you actually need.

      +

      Alex: The practical takeaway is this. 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.

      +

      Jamie: Let's pause on Navigating the PR Tab Bar. What should a learner take away from it?

      +

      Alex: Here is the plain-English version of Navigating the PR Tab Bar. The Conversation, Commits, and Files changed tabs are in a "Pull request navigation tabs" landmark. Put another way, the three tabs - Conversation, Commits, and Files changed - appear just below the PR title.

      +

      Alex: The practical takeaway is this. 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.

      +

      Alex: First, press D → navigate to "Pull request navigation tabs". Then, press ← or → arrow keys to move between tab options. After that, press Enter to activate a tab. Finally, vO+U → Landmarks → "Pull request navigation tabs". Treat it like a recipe: do not add the next ingredient until the previous one is actually in the bowl.

      +

      Jamie: Before we leave Navigating the PR Tab Bar, what is the practical point?

      +

      Alex: First, vO+Right to move between tabs. Then, vO+Space to activate. It is a checklist, but a meaningful one: every item creates evidence that the next step is safe.

      -

      Jamie: What should people carry with them after this?

      -

      Alex: Carry the map. Know what page or tool you are in, know which action you are taking, and know what confirmation should follow. If the confirmation is missing, pause. That pause is not wasted time; it is professional judgment.

      -

      Jamie: That is a better way to say it than just follow the steps.

      -

      Alex: Right. Steps matter, but understanding wins. That is episode 30. Next in the series is episode 31, where we keep building the same contributor muscles.

      -
      - +

      Jamie: Let's pause on PR Description. What should a learner take away from it?

      +

      Alex: Start with PR Description. There is something to understand, something to try, and something that proves the try worked.

      +

      Alex: First, 2 → navigate to "Description" h2 heading. Then, ↓ to read the description. After that, markdown renders as semantic HTML - headings, lists, code blocks are fully accessible. It is a checklist, but a meaningful one: every item creates evidence that the next step is safe.

      +

      Jamie: Let's pause on Status Checks Section. What should a learner take away from it?

      +

      Alex: Keep the learner anchored in Status Checks Section. Below the description, the status checks summary shows whether automated tests passed. This is the part to say slowly: Status checks appear as a coloured banner below the PR description - green tick for passed, red X for failed, yellow spinner for running.

      +

      Alex: The practical takeaway is this. "All checks have passed" / "Some checks failed" / "Checks pending". A "Show all checks" button or link.

      +

      Alex: First, press H or 2 to find the "Checks" or "Status checks" heading. Then, press K to navigate links for individual check names. After that, press Enter on a check to see its details. Finally, quick Nav H or VO+Cmd+H to jump to the "Checks" or "Status checks" heading. It is like walking a hallway with named doors: read the sign, enter the right room, then confirm where you landed.

      +

      Jamie: Before we leave Status Checks Section, what is the practical point?

      +

      Alex: First, quick Nav K to navigate check name links. Then, vO+Space on a check to see its details. The rhythm is simple: orient, act, verify, then continue.

      +

      Alex: Hold that next to this. The reason Review Comments matters is that each review comment thread is an h3. The interface gets friendlier when it stops being a wall of controls and starts being a set of named places.

      +

      Alex: The practical takeaway is this. 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.

      -

      Episode 31: GitHub Codespaces

      -

      Cloud dev environments, accessibility setup, and screen reader usage.

      -

      Based on: Appendix J: GitHub Codespaces

      -

      Audio and transcript are being regenerated for this episode.

      -
      -Read Transcript - Episode 31: GitHub Codespaces - -

      Transcript

      -

      Alex: Welcome to episode 31 of Git Going with GitHub: GitHub Codespaces. I am Alex, and today we are teaching this topic as a conversation you can carry into the workshop, not as a page you have to memorize.

      -

      Jamie: And I am Jamie. I will keep pulling the lesson back to real learners, real repositories, and the evidence that proves the work happened.

      +

      Jamie: Let's pause on Resolving conversations. What should a learner take away from it?

      +

      Alex: Start with Resolving conversations: When a review comment has been addressed, you can mark the conversation as resolved. The next useful detail is this: Resolved conversations are still accessible - they collapse but can be expanded again.

      +

      Alex: First, navigate to the conversation thread (3 to jump between comment headings). Then, tab to the end of the thread to find the "Resolve conversation" button. After that, press Enter to mark it resolved. Finally, the conversation collapses and shows as "Resolved". Think of it as a rail line: each stop confirms you are still on the right route before the next one.

      +

      Alex: That connects to another useful point. Start with Learning Cards: Reading the Conversation Tab. There is something to understand, something to try, and something that proves the try worked.

      +

      Alex: The practical takeaway is this. 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. 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.

      +

      Jamie: Let's pause on Reading the Checks Tab. What should a learner take away from it?

      +

      Alex: This is where Reading the Checks Tab becomes real: the Checks tab shows the status of automated tests, CI workflows, and other verification processes running on your PR. That matters in practice: It helps you verify whether your changes pass all required tests before merging.

      +

      Alex: The practical takeaway is this. Navigate through the check steps with K or Tab. Activate a step for more details.

      +

      Alex: First, navigate to the "Pull request tabs" landmark (D). Then, navigate between tab links (K or Tab) and activate "Checks". After that, press D to jump to the "check suites" section - this moves focus to the collapsed details button of the first check. Finally, press B or Tab to navigate between check buttons; each button is labeled with the check's name. It is a checklist, but a meaningful one: every item creates evidence that the next step is safe.

      +

      Jamie: Before we leave Reading the Checks Tab, what is the practical point?

      +

      Alex: First, press Enter or Space to expand a check and reveal its logs. Then, for a summary view: press D to navigate to the "check run summary" section. After that, vO+U - Landmarks - "Pull request tabs" - activate "Checks". Finally, vO+U - Landmarks - navigate to "check suites" section. It is like walking a hallway with named doors: read the sign, enter the right room, then confirm where you landed.

      -

      Alex: The lesson focus is Cloud dev environments, accessibility setup, and screen reader usage. We will treat every step as a teachable decision, because that is what makes the skill portable.

      -

      Jamie: So we should explain the why clearly enough that the steps make sense when the learner meets them later.

      -

      Alex: That is it. If a listener only has audio right now, they should still get the complete concept and know what evidence would prove success.

      +

      Alex: Keep the teaching thread moving. Start with Learning Cards: Reading the Checks Tab. There is something to understand, something to try, and something that proves the try worked.

      +

      Alex: The practical takeaway is this. 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. 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.

      +

      Jamie: Give me the version that sounds like an instructor, not a manual.

      +

      Alex: The reason Reading the Files Changed Tab matters is that the learner will read diffs - the before/after state of every file that changed. That gives the learner a simple foothold: this guide uses GitHub's improved Files Changed experience.

      +

      Jamie: Let's pause on File Tree (left panel). What should a learner take away from it?

      +

      Alex: Start with File Tree (left panel): The file tree lists every changed file. The next useful detail is this: Use it to jump directly to a specific file's diff.

      +

      Alex: The practical takeaway is this. 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.

      +

      Alex: First, d → navigate to "File tree" region. Then, ↑/↓ to navigate the file list. After that, enter to jump to that file's diff. Finally, vO+U → Landmarks → navigate to "File tree" region. Think of it as a rail line: each stop confirms you are still on the right route before the next one.

      +

      Jamie: Before we leave File Tree (left panel), what is the practical point?

      +

      Alex: First, vO+Down to move through the file list. Then, vO+Space to jump to that file's diff. Treat it like a recipe: do not add the next ingredient until the previous one is actually in the bowl.

      -

      Jamie: Okay, set the room for us. What are we walking into?

      -

      Alex: Start with Cloud Development Environments - Accessibility Guide: GitHub Codespaces gives you a full VS Code development environment in your browser or connected to your local VS Code, running on a cloud machine. The next useful detail is this: For screen reader users, this means a consistent, pre-configured environment with no local setup required.

      -

      Alex: The next layer is this. Here is the plain-English version of 1. What Is GitHub Codespaces? A Codespace is a cloud-hosted development environment. Put another way, when you open one, GitHub provisions a virtual machine, clones your repository into it, and connects it to a VS Code interface - either in your browser or via your local VS Code Desktop. It is like learning a transit route. The names of the stops matter because they tell you whether you are still going the right direction.

      -

      Jamie: What is the one idea that makes the next few steps less mysterious?

      -

      Alex: This is where Why this matters for accessibility becomes real: free tier: GitHub provides a monthly free allowance of Codespace hours for personal accounts. That matters in practice: Workshop usage typically falls well within the free tier.

      -

      Alex: That shows up in the workshop in a few specific ways. No local installation of tools, compilers, or language runtimes required. Your screen reader and OS settings stay on your machine; only the editor runs in the cloud. VS Code's full accessibility features (audio cues, screen reader optimized mode, diff viewer) are available. The environment is identical for every workshop participant - facilitators can reproduce issues reliably.

      +

      Jamie: Where do you want a learner to place their attention here?

      +

      Alex: Start with The Diff for a File. There is something to understand, something to try, and something that proves the try worked.

      +

      Alex: The practical takeaway is this. 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.

      +

      Alex: Keep the teaching thread moving. Start with Lines in a diff are read as. There is something to understand, something to try, and something that proves the try worked.

      +

      Alex: The practical takeaway is this. + Added line - line that was added. Removed line - line that was removed. Context line - unchanged line shown for context.

      +

      Jamie: Let's pause on Navigating the diff with a screen reader. What should a learner take away from it?

      +

      Alex: Keep the learner anchored in Navigating the diff with a screen reader. Each file's diff shows added lines in green and removed lines in red. This is the part to say slowly: Scroll the page to read through changes.

      +

      Alex: The practical takeaway is this. 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.

      +

      Alex: First, t to jump to the next diff table. Then, switch to Focus Mode: Insert+Space (NVDA) or Insert+Z (JAWS). After that, ctrl+Alt+↓ to move down one row (next diff line), Ctrl+Alt+↑ to move up. Finally, ctrl+Alt+→ to read across columns (line number change type content). It is like walking a hallway with named doors: read the sign, enter the right room, then confirm where you landed.

      +

      Jamie: Before we leave Navigating the diff with a screen reader, what is the practical point?

      +

      Alex: First, the screen reader reads: "+ Add accessible name to submit button". Then, collapsed sections contain unchanged code. Focus the expand/disclosure control and activate it (Enter or Space) to reveal the hidden lines. After that, t or VO+U → Tables → select the diff table. Finally, vO+Shift+Down to enter the table. The rhythm is simple: orient, act, verify, then continue.

      -

      Alex: Now bring the learner back to the room. Start with Learning Cards: Cloud Editors Overview. There is something to understand, something to try, and something that proves the try worked.

      -

      Alex: For a learner, the useful signals are these. Codespaces gives you a full VS Code interface with terminal access -- your screen reader and OS settings stay on your local machine. The browser-based editor activates screen reader optimized mode automatically if your OS signals a screen reader is running. Connect a Codespace to your local VS Code Desktop (via the Codespaces extension) for the most familiar screen reader experience. Settings Sync carries your font size, theme, and zoom preferences from local VS Code into Codespaces automatically. The browser-based editor supports Ctrl+= / Ctrl+- zoom just like desktop VS Code. Use a high-contrast VS Code theme -- it applies identically in the cloud editor.

      -

      Jamie: What is the ordered workflow?

      -

      Alex: Start with From a Repository Page. There is something to understand, something to try, and something that proves the try worked.

      -

      Alex: First, navigate to the repository on GitHub. Then, press the Code button (keyboard shortcut: there is no direct shortcut - Tab to the button). After that, in the panel that opens, choose the Codespaces tab. Finally, activate Create codespace on main (or your branch name). The rhythm is simple: orient, act, verify, then continue.

      -

      Jamie: Give me the sequence, because order matters here.

      -

      Alex: First, the Codespace opens in a new browser tab after provisioning (typically 30-60 seconds). Think of it as a rail line: each stop confirms you are still on the right route before the next one.

      -

      Alex: The useful habit is simple: orient first, act second, verify third. That pause before acting is part of the work.

      -

      Jamie: How would you walk the room through that step by step?

      -

      Alex: Start with From the Codespaces Dashboard. There is something to understand, something to try, and something that proves the try worked.

      -

      Alex: First, go to github.com/codespaces. Then, activate New codespace. After that, use the search field to find your repository. Finally, choose a branch, machine type, and region. Think of it as a rail line: each stop confirms you are still on the right route before the next one.

      -

      Jamie: What does the learner do first, second, and then after that?

      -

      Alex: First, activate Create codespace. Treat it like a recipe: do not add the next ingredient until the previous one is actually in the bowl.

      +

      Jamie: Let's pause on Placing an inline comment on a diff line. What should a learner take away from it?

      +

      Alex: The reason Placing an inline comment on a diff line matters is that hover over any line in the diff - a blue + button appears on the left margin. That gives the learner a simple foothold: click it to open a comment box for that line.

      +

      Alex: The practical takeaway is this. 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.

      +

      Alex: First, navigate to the specific line in the diff (using the table navigation above). Then, while focused on that line, a comment button appears - press Enter or Space to activate it. After that, a comment box opens below the line. Finally, focus Mode → type your comment. The rhythm is simple: orient, act, verify, then continue.

      +

      Jamie: Before we leave Placing an inline comment on a diff line, what is the practical point?

      +

      Alex: First, tab to Add single comment button (instant comment) OR Start a review (to batch comments). Think of it as a rail line: each stop confirms you are still on the right route before the next one.

      +

      Jamie: Let's pause on Multi-line comment (Windows). What should a learner take away from it?

      +

      Alex: Start with Multi-line comment (Windows): Screen reader users (VoiceOver - macOS).

      +

      Alex: First, focus the first line you want to comment on. Then, press Shift+↓ to extend the selection to additional lines. After that, a comment button appears - activate it. Finally, the comment applies to the full range of selected lines. Think of it as a rail line: each stop confirms you are still on the right route before the next one.

      +

      Jamie: Before we leave Multi-line comment (Windows), what is the practical point?

      +

      Alex: First, navigate to the specific line in the diff (using the table navigation above). Then, while focused on that line, VO+Space on the comment button that appears. After that, a comment box opens below the line. Finally, vO+Shift+Down to interact with the text area, then type your comment. Treat it like a recipe: do not add the next ingredient until the previous one is actually in the bowl.

      +

      Jamie: Let's pause on Multi-line comment (macOS). What should a learner take away from it?

      +

      Alex: Start with Multi-line comment (macOS). There is something to understand, something to try, and something that proves the try worked.

      +

      Alex: First, focus the first line and Shift+↓ to extend the selection. Then, vO+Space on the comment button that appears. After that, the comment applies to the full range of selected lines. Treat it like a recipe: do not add the next ingredient until the previous one is actually in the bowl.

      -

      Jamie: If I am listening before the workshop starts, what should settle in my mind first?

      -

      Alex: Here is the plain-English version of Machine Types. For workshop exercises, the default 2-core machine is sufficient.

      -

      Alex: This is where the talk moves from concept to action. This is where Browser (VS Code for the Web) becomes real: the Codespace opens directly in your browser as a fully functional VS Code interface.

      -

      Alex: The room should hear these as checkpoints. Works in Chrome, Edge, Firefox, and Safari. Screen reader support varies slightly by browser - Chrome and Edge have the most consistent behavior with NVDA and JAWS. No installation needed. Some VS Code extensions are not available in the browser version.

      -

      Jamie: Turn that into a path someone can follow.

      -

      Alex: Keep the learner anchored in Local VS Code Desktop. If you prefer your local VS Code setup with your extensions and settings. This is the part to say slowly: When connected via local VS Code, your screen reader interacts with your local VS Code installation - all your familiar settings apply.

      -

      Alex: First, install the GitHub Codespaces extension in VS Code. Then, sign in to GitHub in VS Code. After that, open the Command Palette (Ctrl+Shift+P / Cmd+Shift+P). Finally, run Codespaces: Connect to Codespace. It is like walking a hallway with named doors: read the sign, enter the right room, then confirm where you landed.

      -

      Jamie: Let's pause on Local VS Code Desktop. What should a learner take away from it?

      -

      Alex: First, select an existing Codespace or create a new one. The rhythm is simple: orient, act, verify, then continue.

      +

      Jamie: Let's pause on Viewing comments within the diff. What should a learner take away from it?

      +

      Alex: This is where Viewing comments within the diff becomes real: inline comments appear as expandable threads within the diff table. That matters in practice: Navigate to them with 3 (they are h3 headings).

      +

      Alex: Keep the teaching thread moving. Start with Learning Cards: Reading the Files Changed Tab. There is something to understand, something to try, and something that proves the try worked.

      +

      Alex: The practical takeaway is this. 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. 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.

      +

      Jamie: Let's pause on Tool Cards: Open a Pull Request. What should a learner take away from it?

      +

      Alex: The reason Tool Cards: Open a Pull Request matters is that VS Code Desktop (GitHub Pull Requests extension).

      +

      Alex: First, push your branch, then click the Compare & pull request banner (or go to Pull requests New pull request ). Then, set base branch to main, compare branch to yours. After that, fill in the title and description, then click Create pull request. Finally, after committing changes, click the Source Control icon. The rhythm is simple: orient, act, verify, then continue.

      +

      Jamie: Before we leave Tool Cards: Open a Pull Request, what is the practical point?

      +

      Alex: First, click Create Pull Request in the Source Control panel header. Then, fill in details and submit. After that, press Ctrl+Shift+P, type GitHub Pull Requests: Create Pull Request. Finally, select base and compare branches. Think of it as a rail line: each stop confirms you are still on the right route before the next one.

      +

      Alex: Treat examples as spoken recipes, not decorations. You may hear something like git push -u origin your-branch; gh pr create --title "Your title" --body "Description". Read the command, understand what it changes, then run it only when the repository state matches the lesson.

      -

      Jamie: Let's pause on Screen Reader Optimized Mode. What should a learner take away from it?

      -

      Alex: The reason Screen Reader Optimized Mode matters is that when VS Code detects a screen reader, it automatically activates Screen Reader Optimized mode. That gives the learner a simple foothold: you can verify or toggle it manually. The interface gets friendlier when it stops being a wall of controls and starts being a set of named places.

      -

      Alex: That becomes easier when you listen for these cues. The editor reads content line by line instead of character by character. Diff views are rendered as accessible text comparisons. Inline suggestions from Copilot are announced on a keypress rather than automatically.

      -

      Alex: First, open the Command Palette (Ctrl+Shift+P). Then, search for Toggle Screen Reader Accessibility Mode. After that, press Enter to activate. The rhythm is simple: orient, act, verify, then continue.

      -

      Alex: A solid navigation habit is to prove where you are before activating controls. Headings, landmarks, and the address bar are not trivia; they are your map.

      -

      Jamie: What would you say to someone who is already bracing for this to be too much?

      -

      Alex: Start with Audio Cues: VS Code in Codespaces supports the same audio cues as the desktop version. The next useful detail is this: Enable audio cues via Settings → search for "audio cues" or run Help: List Audio Cues from the Command Palette.

      -

      Alex: Hold that next to this. Here is the plain-English version of Terminal Accessibility. The integrated terminal in a Codespace is a standard terminal.

      -

      Alex: The practical anchors are these. Screen readers read terminal output in NVDA and JAWS using their document/browse mode after output arrives. In NVDA: Switch to Browse Mode to read static terminal output, then back to Focus Mode to type. VS Code also has Accessible View (Alt+F2 when cursor is in the terminal) which renders terminal output in a navigable buffer.

      +

      Jamie: Let's pause on From the web editor workflow (editing a file on GitHub). What should a learner take away from it?

      +

      Alex: Start with From the web editor workflow (editing a file on GitHub). There is something to understand, something to try, and something that proves the try worked.

      +

      Alex: First, you edited a file → GitHub showed a "Propose changes" form. Then, you named your branch and activated "Propose changes". After that, GitHub redirected you to the "Open a pull request" page. Think of it as a rail line: each stop confirms you are still on the right route before the next one.

      +

      Jamie: Let's pause on From a fork or feature branch. What should a learner take away from it?

      +

      Alex: Here is the plain-English version of From a fork or feature branch. Screen reader users (NVDA / JAWS - Windows). Put another way, screen reader users (VoiceOver - macOS).

      +

      Alex: First, navigate to the repository on GitHub. Then, if you recently pushed, a yellow banner "Compare & pull request" appears at the top - click it. After that, if no banner appears: click the Pull requests tab → click the green New pull request button. Finally, use the branch dropdowns to choose your base branch (what to merge into) and your compare branch (your changes). Treat it like a recipe: do not add the next ingredient until the previous one is actually in the bowl.

      +

      Jamie: Before we leave From a fork or feature branch, what is the practical point?

      +

      Alex: First, click Create pull request. Then, navigate to the repository. After that, a "Compare & pull request" banner may appear (if you recently pushed) - activate it. Finally, oR: Navigate to Pull Requests tab → "New pull request". It is a checklist, but a meaningful one: every item creates evidence that the next step is safe.

      +

      Jamie: How do you keep commands from becoming magic words?

      +

      Alex: This is where Description field becomes real: Copilot can write your PR description: If your account has Copilot access, a "Copilot actions" button appears in the description toolbar. That matters in practice: 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.

      +

      Alex: Treat examples as spoken recipes, not decorations. You may hear something like Step 1: Tab to the body text area; Step 2: Focus Mode → type using the PR template (if provided). 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 for the dismiss control; Related Issues; Closes 42; Testing; - Tested with NVDA + Chrome on Windows 11; -. Read the command, understand what it changes, then run it only when the repository state matches the lesson.

      -

      Jamie: Where do you want a learner to place their attention here?

      -

      Alex: Start with Learning Cards: Codespace Accessibility. There is something to understand, something to try, and something that proves the try worked.

      -

      Alex: The parts worth keeping in working memory are these. Screen Reader Optimized mode activates automatically -- verify with Command Palette Ctrl+Shift+P then "Toggle Screen Reader Accessibility Mode". Audio cues (error, warning, task completed, Copilot suggestion) work identically in Codespaces and desktop VS Code. In NVDA, switch to Browse Mode to read terminal output, then Focus Mode to type -- same pattern as local VS Code. All VS Code zoom and theme settings apply in the browser-based Codespace -- Ctrl+= increases editor font size. Audio cues for errors and Copilot suggestions supplement visual indicators you might miss at lower zoom levels. Chrome and Edge provide the most consistent rendering of the Codespace UI at high zoom and magnification levels.

      -

      Alex: That connects to another useful point. Keep the learner anchored in NVDA. No special NVDA profile is required for Codespaces in the browser. This is the part to say slowly: The same settings recommended in Appendix B apply. A good GitHub workflow is like a well-run meeting: everyone knows the topic, the next action, and who has the floor.

      -

      Alex: On the ground, that means a few things. Ensure Browse Mode is on for reading, Focus Mode for typing. Set maximum line length to 10000 in NVDA Settings → Browse Mode. In Chrome or Edge, NVDA's Browse Mode detection is generally reliable.

      -

      Jamie: Give me the version that sounds like an instructor, not a manual.

      -

      Alex: Start with JAWS. There is something to understand, something to try, and something that proves the try worked.

      -

      Alex: Here is what that changes in practice. Use Virtual Cursor for reading page content. Switch to PC Cursor (Insert+Z or Num Pad Plus) when inside the editor and writing code. JAWS works best with the Codespace in Chrome or Edge.

      +

      Jamie: Let's pause on Setting a Draft PR. What should a learner take away from it?

      +

      Alex: Keep the learner anchored in Setting a Draft PR. If your work is not finished, open as a Draft.

      +

      Alex: First, after filling in the form, find the dropdown arrow next to "Create pull request". Then, select "Create draft pull request". After that, this signals to reviewers that it is not ready for formal review yet. It is like walking a hallway with named doors: read the sign, enter the right room, then confirm where you landed.

      +

      Alex: Keep the teaching thread moving. The reason Draft Pull Requests - Full Lifecycle matters is that a draft pull request is a PR explicitly marked as a work in progress. That gives the learner a simple foothold: it is visible to the team, can receive comments, and runs CI - but is blocked from being merged until you mark it ready. The interface gets friendlier when it stops being a wall of controls and starts being a set of named places.

      +

      Jamie: Let's pause on When to use a draft. What should a learner take away from it?

      +

      Alex: Start with When to use a draft. There is something to understand, something to try, and something that proves the try worked.

      +

      Alex: The practical takeaway is this. You want to show your approach and get early feedback before finishing. You need CI to run but don't want accidental merges. You are working across multiple days and want your progress visible. You want to pair with a collaborator on the work.

      -

      Alex: Here is the practical turn. Start with VoiceOver (macOS). There is something to understand, something to try, and something that proves the try worked.

      -

      Alex: These are the details that keep the idea from floating away. Use Quick Nav (Left+Right arrows) for moving through the VS Code interface. The Rotor (VO+U) surfaces VS Code's landmark regions. If text in the editor is not reading fluently, ensure Screen Reader Optimized mode is active (see above).

      -

      Jamie: Let's pause on 6. Keyboard Shortcuts in Codespaces. What should a learner take away from it?

      -

      Alex: Here is the plain-English version of 6. Keyboard Shortcuts in Codespaces. Codespaces uses standard VS Code keyboard shortcuts. Put another way, the most important ones for workshop exercises.

      -

      Jamie: Let's pause on Stopping a Codespace. What should a learner take away from it?

      -

      Alex: This is where Stopping a Codespace becomes real: codespaces automatically stop after a period of inactivity (default: 30 minutes). That matters in practice: Stopped Codespaces retain your files and changes. The workshop is closer to rehearsal than lecture. You hear the move, try the move, and then check what changed.

      -

      Alex: First, go to github.com/codespaces. Then, find your Codespace in the list. After that, activate the … menu next to it. Finally, choose Stop codespace. It is a checklist, but a meaningful one: every item creates evidence that the next step is safe.

      +

      Alex: Keep the teaching thread moving. Start with What a draft PR does differently. There is something to understand, something to try, and something that proves the try worked.

      +

      Alex: The practical takeaway is this. The merge button is disabled - even an authorized maintainer cannot merge a draft. The PR header shows a grey "Draft" badge instead of the green "Open" badge. Reviewers are not auto-notified (no review requests are sent until ready). CI workflows still run normally.

      +

      Jamie: Let's pause on Mark a draft ready for review. What should a learner take away from it?

      +

      Alex: Start with Mark a draft ready for review. There is something to understand, something to try, and something that proves the try worked.

      +

      Alex: First, open the PR. Then, navigate to the "Reviewers" sidebar or scroll to bottom of the Conversation tab. After that, find and activate the "Ready for review" button. Finally, the draft badge changes to "Open" and reviewers are notified. It is a checklist, but a meaningful one: every item creates evidence that the next step is safe.

      +

      Jamie: Let's pause on Convert an open PR to draft (after opening). What should a learner take away from it?

      +

      Alex: Keep the learner anchored in Convert an open PR to draft (after opening). GitHub CLI (gh) alternative - draft PR lifecycle. This is the part to say slowly: Manage draft PRs from your terminal. A good GitHub workflow is like a well-run meeting: everyone knows the topic, the next action, and who has the floor.

      +

      Alex: First, in the right sidebar, find the "Reviewers" section. Then, look for the "Convert to draft" link (below the review status). After that, confirm in the dialog - this removes merge eligibility until you mark it ready again. It is like walking a hallway with named doors: read the sign, enter the right room, then confirm where you landed.

      +

      Alex: Treat examples as spoken recipes, not decorations. You may hear something like Create a draft PR; gh pr create --draft --title "WIP: Add carousel keyboard nav"; Mark a draft ready for review; gh pr ready 42; Check PR status (shows draft state); gh pr view 42; List only draft PRs; gh pr list --draft. Read the command, understand what it changes, then run it only when the repository state matches the lesson.

      -

      Jamie: Let's pause on Deleting a Codespace. What should a learner take away from it?

      -

      Alex: Keep the learner anchored in Deleting a Codespace. Deleting a Codespace removes any uncommitted or unpushed changes permanently. This is the part to say slowly: Always commit and push your work before deleting.

      -

      Alex: First, go to github.com/codespaces. Then, activate the … menu next to the Codespace. After that, choose Delete. It is like walking a hallway with named doors: read the sign, enter the right room, then confirm where you landed.

      -

      Jamie: Let's pause on Resuming a Codespace. What should a learner take away from it?

      -

      Alex: Start with Resuming a Codespace. There is something to understand, something to try, and something that proves the try worked.

      -

      Alex: First, go to github.com/codespaces. Then, find your stopped Codespace. After that, activate Open in … to resume it in the browser or in VS Code Desktop. The rhythm is simple: orient, act, verify, then continue.

      -

      Jamie: Let's pause on 8. Dotfiles and Persistent Configuration. What should a learner take away from it?

      -

      Alex: Start with 8. Dotfiles and Persistent Configuration: If you have a repository named dotfiles on your GitHub account, Codespaces will automatically apply it when provisioning new environments. The next useful detail is this: To set up dotfiles: create a repository named dotfiles and add an install.sh script.

      -

      Alex: A few details make that real. Setting your preferred shell (bash, zsh, fish). Adding shell aliases and functions. Pre-installing command-line tools.

      +

      Jamie: Let's pause on Learning Cards: Opening a Pull Request. What should a learner take away from it?

      +

      Alex: Start with Learning Cards: Opening a Pull Request. There is something to understand, something to try, and something that proves the try worked.

      +

      Alex: The practical takeaway is this. After editing a file on GitHub, the "Propose changes" form has a branch name field and a commit message field; press Tab to move between them. On the "Open a pull request" page, press F to jump to the Title field; Tab moves to the Description text area. Press Ctrl+Enter from inside the description text area to submit the PR without finding the Create button. The "Compare & pull request" yellow banner appears at the top of the repo after a recent push; at high zoom it may span the full width of the page. The branch comparison dropdowns (base and compare) use small text; zoom in on the area above the diff preview to read them. Draft PR: look for the dropdown arrow next to the green "Create pull request" button to switch to "Create draft pull request".

      +

      Jamie: Let's pause on Requesting reviewers. What should a learner take away from it?

      +

      Alex: Start with Requesting reviewers: From the sidebar Reviewers section. The next useful detail is this: Why some reviews are requested automatically: A file called CODEOWNERS in many repositories maps file paths to specific people or teams.

      +

      Alex: First, navigate to "Reviewers" heading (3 or H). Then, activate the gear button. After that, type a username in the search field. Finally, select from the dropdown. Think of it as a rail line: each stop confirms you are still on the right route before the next one.

      +

      Jamie: Before we leave Requesting reviewers, what is the practical point?

      +

      Alex: First, escape to save. Treat it like a recipe: do not add the next ingredient until the previous one is actually in the bowl.

      +

      Jamie: Let's pause on Submitting a Review. What should a learner take away from it?

      +

      Alex: Here is the plain-English version of Submitting a Review. When you are asked to review a PR, you have three options.

      +

      Alex: The practical takeaway is this. Comment - leave feedback without a verdict; does not block merging. Approve - signal you are satisfied; often required before merge. Request changes - indicate changes must be addressed; blocks merge until resolved.

      -

      Alex: This is the part worth saying out loud. Here is the plain-English version of 9. Codespaces vs GitHub.dev. For workshop exercises that involve running scripts or tests, use Codespaces. Put another way, for quickly browsing or editing a file, GitHub.dev is faster to open. It is like learning a transit route. The names of the stops matter because they tell you whether you are still going the right direction.

      -

      Jamie: Let's pause on Learning Cards: Choosing Your Cloud Editor. What should a learner take away from it?

      -

      Alex: Start with Learning Cards: Choosing Your Cloud Editor. There is something to understand, something to try, and something that proves the try worked.

      -

      Alex: The practical takeaway is this. GitHub.dev has no terminal -- choose Codespaces when you need to run commands, and github.dev for quick file edits. Both editors support screen reader mode, but Codespaces gives you the full terminal Accessible View (Alt+F2) that github.dev lacks. press the period key on any repo page for github.dev; use the Codespaces dashboard at github.com/codespaces for a full environment. GitHub.dev loads instantly with your synced VS Code theme -- good for quick high-contrast reading of source files. Codespaces takes 30-60 seconds to provision but gives you terminal, builds, and the same zoom/theme settings. Both editors scale with browser zoom (Ctrl+=) in addition to VS Code's own font-size settings.

      -

      Alex: That matters because of the next idea. Keep the learner anchored in The Codespace takes a long time to open. Provisioning a new Codespace can take up to 90 seconds. This is the part to say slowly: If it hangs beyond that, refresh the browser tab and try again.

      +

      Alex: Keep the teaching thread moving. This is where Starting a review becomes real: on the Files Changed tab, when you add inline comments, choose "Start a review" instead of "Add single comment." This batches all your comments into one review submission. The workshop is closer to rehearsal than lecture. You hear the move, try the move, and then check what changed.

      +

      Jamie: Let's pause on Completing and submitting a review. What should a learner take away from it?

      +

      Alex: Keep the learner anchored in Completing and submitting a review. After adding your inline comments via "Start a review," you must submit the review to notify the PR author. This is the part to say slowly: The review is pending until you submit it.

      +

      Alex: The practical takeaway is this. The button may scroll off-screen to the right. Use horizontal scrolling or press Tab from the page top to cycle through focusable elements until you reach it. When clicked, a popover appears with a summary text area and three radio buttons ( Comment, Approve, Request changes ). At 200%+ zoom, the popover may extend below the visible viewport. Scroll down within the popover to see the Submit review button. The radio buttons are standard HTML radio buttons. In Windows High Contrast mode, the selected radio button uses the system highlight color. Keyboard shortcut: If the button is hard to find visually, press Ctrl+Shift+Enter from within any review comment text area to open the submit review dialog directly.

      +

      Alex: First, look for the Finish your review button in the top-right area of the Files Changed tab (it shows the number of pending comments). Then, click it - a popover appears with a summary text area and three radio buttons: Comment, Approve, Request changes. After that, optionally type a summary comment. Finally, select your verdict by clicking the radio button. It is like walking a hallway with named doors: read the sign, enter the right room, then confirm where you landed.

      +

      Jamie: Before we leave Completing and submitting a review, what is the practical point?

      +

      Alex: First, click Submit review. Then, press 1 to go to the h1 (PR title). After that, press B (or Tab) to navigate to the "Submit review" button and activate it (Enter/Space). Finally, a "Submit review" dialog/panel appears. The rhythm is simple: orient, act, verify, then continue.

      +

      Alex: Treat examples as spoken recipes, not decorations. You may hear something like View the PR diff in your terminal; gh pr diff 42; Approve a PR; gh pr review 42 --approve; Approve with a comment; gh pr review 42 --approve --body "Looks good - heading hierarchy is correct."; Request changes; gh pr review 42 --request-changes --body "The alt. Read the command, understand what it changes, then run it only when the repository state matches the lesson.

      +

      Alex: Keep the teaching thread moving. The reason GitHub shortcuts for pull requests matters is that these are the GitHub built-in shortcuts for PR pages. That gives the learner a simple foothold: enable Focus Mode first (NVDA: NVDA+Space, JAWS: Insert+Z) before using single-key shortcuts.

      -

      Jamie: Let's pause on Screen reader stops reading after I switch to the terminal. What should a learner take away from it?

      -

      Alex: The reason Screen reader stops reading after I switch to the terminal matters is that switch to Browse Mode (NVDA: Insert+Space; JAWS: Insert+Z) to read the terminal output, then return to Focus Mode to type your next command.

      -

      Alex: Keep the thread going. Start with Audio cues are not working in the browser: Some browsers mute audio by default for new tabs. The next useful detail is this: Check your browser's site permissions to ensure audio is allowed for github.dev or the Codespace URL. Think of it like entering a new building: first you find the lobby, then the room, then the door you actually need.

      -

      Jamie: Let's pause on Extensions I rely on locally are not available. What should a learner take away from it?

      -

      Alex: Here is the plain-English version of Extensions I rely on locally are not available. Some extensions are not compatible with the browser-based VS Code. Put another way, connect to the Codespace via VS Code Desktop instead (see Section 3) to access your full extension library.

      +

      Jamie: Let's pause on On the PR list page. What should a learner take away from it?

      +

      Alex: Start with On the PR list page: Shortcut note: For G P, press G, release it, then press P (two sequential key presses, not simultaneous).

      +

      Alex: Keep the teaching thread moving. Here is the plain-English version of On the Files Changed tab. For the full shortcut system, see Screen Reader Cheat Sheet - GitHub Shortcuts section. It is like learning a transit route. The names of the stops matter because they tell you whether you are still going the right direction.

      +

      Jamie: Let's pause on Learning Cards: Submitting a Review. What should a learner take away from it?

      +

      Alex: Start with Learning Cards: Submitting a Review. There is something to understand, something to try, and something that proves the try worked.

      +

      Alex: The practical takeaway is this. The review verdict controls are inside a popover triggered by the "Finish your review" button; press 1 to return to the h1 (PR title), then B or Tab forward to find the button -- it is easy to miss because it is not a landmark. Inside the popover, Tab past the summary text area to reach a radio group labeled "Review Event"; use Up/Down Arrow to switch between Comment, Approve, and Request Changes. Shortcut: press Ctrl+Shift+Enter from any review comment text area to open the submit review dialog directly, bypassing the search for the button. The "Finish your review" button sits in the top-right corner of the Files Changed tab with a small badge showing your pending comment count; at 200%+ zoom it may scroll off-screen to the right. Inside the submit popover, the three radio buttons (Comment, Approve, Request changes) are small standard HTML radios; zoom in on the popover area or use Tab to step between them. After submitting, your review verdict appears as a colored banner in the Conversation timeline: green for Approve, red for Request Changes, grey for Comment.

      -

      Alex: Another way to ground it. This is where I accidentally deleted my Codespace before pushing becomes real: if the branch exists on GitHub, you can create a new Codespace from it. That matters in practice: Uncommitted changes in a deleted Codespace cannot be recovered.

      -

      Jamie: Let's pause on My changes are not showing in GitHub after committing. What should a learner take away from it?

      -

      Alex: Keep the learner anchored in My changes are not showing in GitHub after committing. You may have committed but not pushed. This is the part to say slowly: In the Source Control panel, look for the Sync Changes or Push button.

      -

      Alex: A solid Git habit is to know which branch you are on, what changed, and what confirmation you expect before you run the next command.

      +

      Alex: Keep the teaching thread moving. Keep the learner anchored in Suggested Changes. A suggested change is a special form of inline review comment where the reviewer proposes exact replacement text. This is the part to say slowly: The PR author can apply the suggestion directly from GitHub - no copy-paste or separate commit needed.

      +

      Jamie: Let's pause on As a reviewer - inserting a suggestion. What should a learner take away from it?

      +

      Alex: The reason As a reviewer - inserting a suggestion matters is that the suggestion block is plain Markdown text in the comment editor. That gives the learner a simple foothold: (Three backticks, the word suggestion, Enter, your text, Enter, three backticks.).

      +

      Alex: First, on the Files Changed tab, navigate to the line you want to propose a change. Then, activate the line comment button for that line (the + that appears on hover, or Tab to navigate to it). After that, in the comment text area that opens, press Ctrl+G (Windows) or Cmd+G (Mac). Finally, GitHub wraps a suggestion block around the current line content. The rhythm is simple: orient, act, verify, then continue.

      +

      Jamie: Before we leave As a reviewer - inserting a suggestion, what is the practical point?

      +

      Alex: First, edit the text inside the suggestion block to show your proposed change. Then, add context above the block if helpful: "This makes the alt text more descriptive:". After that, submit as part of your review ("Start a review" → batch with other comments). Think of it as a rail line: each stop confirms you are still on the right route before the next one.

      +

      Jamie: Let's pause on As an author - applying a suggestion. What should a learner take away from it?

      +

      Alex: Start with As an author - applying a suggestion. There is something to understand, something to try, and something that proves the try worked.

      +

      Alex: First, open the PR Conversation or Files Changed tab. Then, navigate to the inline comment containing a suggestion (it shows a diff-style preview). After that, find and activate the "Apply suggestion" button below the suggestion block. Finally, GitHub creates a commit automatically that applies the change - no file editing required. Think of it as a rail line: each stop confirms you are still on the right route before the next one.

      +

      Jamie: Before we leave As an author - applying a suggestion, what is the practical point?

      +

      Alex: First, the conversation thread is marked as resolved. Treat it like a recipe: do not add the next ingredient until the previous one is actually in the bowl.

      -

      Jamie: What should people carry with them after this?

      -

      Alex: Carry the map. Know what page or tool you are in, know which action you are taking, and know what confirmation should follow. If the confirmation is missing, pause. That pause is not wasted time; it is professional judgment.

      -

      Jamie: That is a better way to say it than just follow the steps.

      -

      Alex: Right. Steps matter, but understanding wins. That is episode 31. Next in the series is episode 32, where we keep building the same contributor muscles.

      -
      - +

      Jamie: Let's pause on Batching multiple suggestions into one commit. What should a learner take away from it?

      +

      Alex: Start with Batching multiple suggestions into one commit. There is something to understand, something to try, and something that proves the try worked.

      +

      Alex: First, for each suggestion you want to apply, activate "Add suggestion to batch" instead of "Apply suggestion". Then, after selecting all suggestions, activate the "Commit suggestions" button that appears at the top. After that, GitHub applies all batched suggestions in a single commit. Treat it like a recipe: do not add the next ingredient until the previous one is actually in the bowl.

      +

      Jamie: Let's pause on When to use suggestions vs. comments. What should a learner take away from it?

      +

      Alex: Start with When to use suggestions vs. comments. There is something to understand, something to try, and something that proves the try worked.

      +

      Alex: The practical takeaway is this. Use a suggestion when you know the exact text that would fix the issue. Use a plain comment when the change requires judgment from the author (e.g., "this alt text isn't descriptive - can you describe what the image shows?"). A summary text area for overall comments. Radio buttons for Comment / Approve / Request changes.

      +

      Alex: First, after adding all your inline comments, navigate to the review summary button. Then, on Files Changed tab: find the "Review changes" button (B to navigate buttons). After that, press Enter to open the review dialog. Finally, a panel opens. It is a checklist, but a meaningful one: every item creates evidence that the next step is safe.

      +

      Jamie: Before we leave When to use suggestions vs. comments, what is the practical point?

      +

      Alex: First, switch to Focus Mode → type your summary comment. Then, navigate to the radio buttons with arrow keys → select your verdict. After that, tab to "Submit review" button → Enter. It is like walking a hallway with named doors: read the sign, enter the right room, then confirm where you landed.

      +

      Jamie: Let's pause on Learning Cards: Suggested Changes. What should a learner take away from it?

      +

      Alex: Start with Learning Cards: Suggested Changes. There is something to understand, something to try, and something that proves the try worked.

      +

      Alex: The practical takeaway is this. To insert a suggestion block, press Ctrl+G (Windows) or Cmd+G (Mac) in the comment text area; the screen reader announces the inserted fence -- arrow down to edit the text between the backtick lines. Alternatively type the block manually: three backticks, the word suggestion, Enter, your replacement text, Enter, three backticks -- this avoids relying on the keyboard shortcut. As a PR author, navigate to a suggestion comment with 3, then Tab to the "Apply suggestion" button; GitHub commits the change automatically with no file editing required. Suggestion blocks render as a mini inline diff: the original line in red/pink background and your proposed replacement in green background; in high-contrast mode these use system diff colors. The "Apply suggestion" button is small and sits below the suggestion diff preview; zoom into the comment area to find it, or Tab from the suggestion text to reach it. When batching multiple suggestions, a floating "Commit suggestions" bar appears at the top of the page; at high zoom scroll up or press Home to find it.

      -

      Episode 32: GitHub Mobile

      -

      VoiceOver and TalkBack guide for iOS and Android GitHub apps.

      -

      Based on: Appendix V: GitHub Mobile

      -

      Audio and transcript are being regenerated for this episode.

      -
      -Read Transcript - Episode 32: GitHub Mobile - -

      Transcript

      -

      Alex: Welcome to Git Going with GitHub, episode 32: GitHub Mobile. I am Alex. Today we are going to make GitHub Mobile something you can explain, practice, and recover from when the interface surprises you.

      -

      Jamie: And I am Jamie. I will be the voice of the learner who is willing to ask, what is this for, where am I, and how do I know I did it right?

      +

      Jamie: What is the safe way to learn from that example?

      +

      Alex: The reason Understanding Merge Options (for Maintainers) matters is that when a PR is approved and checks pass, a maintainer can merge it. That gives the learner a simple foothold: the merge button section appears at the bottom of the Conversation tab. The interface gets friendlier when it stops being a wall of controls and starts being a set of named places.

      +

      Alex: Treat examples as spoken recipes, not decorations. You may hear something like Merge with default strategy (merge commit); gh pr merge 42; Squash and merge; gh pr merge 42 --squash; Rebase and merge; gh pr merge 42 --rebase; Delete the branch after merging; gh pr merge 42 --squash --delete-branch; Enable auto-merge (merges when checks. Read the command, understand what it changes, then run it only when the repository state matches the lesson.

      +

      Jamie: Let's pause on After a PR is merged. What should a learner take away from it?

      +

      Alex: Start with After a PR is merged: for screen reader users, - deleting the branch after merge: Navigate to the "Add a comment" section (D), then press Shift+B to navigate backwards to the "Delete branch" button and activate it. The next useful detail is this: This keeps your repository clean by removing the now-merged feature branch.

      +

      Alex: The practical takeaway is this. The PR status badge changes to "Merged" (purple). The source branch can be deleted - a "Delete branch" button appears. Any linked issues with Closes N in the description are automatically closed.

      +

      Alex: Keep the teaching thread moving. Here is the plain-English version of Auto-Merge - Merging When You Can't Wait Around. Auto-merge lets you pre-authorize a PR to merge automatically the moment all branch protection requirements are satisfied - required reviews approved, all status checks passing, and the branch up to date.

      +

      Alex: The practical takeaway is this. You've addressed all review comments and are waiting for CI to finish. A maintainer has approved the PR but a required check is still running. You're in a different time zone from the reviewers.

      -

      Alex: The big idea today: VoiceOver and TalkBack guide for iOS and Android GitHub apps. We will name the concept, explain why it matters, practice the move, and point out the checks that tell you the work is real.

      -

      Jamie: So the episode should work even if someone has not read the chapter yet.

      -

      Alex: Exactly. The transcript has to stand on its own. It can point toward practice, but it should teach the concept right here in the conversation.

      +

      Jamie: Let's pause on What happens next. What should a learner take away from it?

      +

      Alex: Start with What happens next. There is something to understand, something to try, and something that proves the try worked.

      +

      Alex: The practical takeaway is this. The PR merge box changes to show "Auto-merge enabled - merge will happen automatically". When the last required check passes (or last required review arrives), GitHub merges the PR silently. You receive a notification: "Your PR was automatically merged". If a reviewer requests changes after auto-merge is enabled, auto-merge is automatically cancelled (a new approval is required before it re-enables).

      +

      Jamie: Let's pause on Cancelling Auto-Merge. What should a learner take away from it?

      +

      Alex: Keep the learner anchored in Cancelling Auto-Merge. Auto-merge is only available if the repository administrator has enabled it in Settings → General. This is the part to say slowly: Many open source repos have it on; some do not. A good GitHub workflow is like a well-run meeting: everyone knows the topic, the next action, and who has the floor.

      +

      Alex: Treat examples as spoken recipes, not decorations. You may hear something like Merge box → Tab → "Disable auto-merge" button → Enter. Read the command, understand what it changes, then run it only when the repository state matches the lesson.

      +

      Jamie: Let's pause on Scenario A: "I want to review an assigned PR". What should a learner take away from it?

      +

      Alex: The reason Scenario A: "I want to review an assigned PR" matters is that example: You are assigned to review a PR titled "Add missing NVDA shortcut to keyboard-shortcuts.md." The PR modifies docs/keyboard-shortcuts.md in the Learning Room repository and references Challenge 2.

      -

      Jamie: Okay, set the room for us. What are we walking into?

      -

      Alex: Start with Accessibility Guide for iOS and Android: GitHub Mobile brings issues, pull requests, notifications, and code review to your iPhone, iPad, or Android device. The next useful detail is this: This appendix covers setup, VoiceOver and TalkBack usage, and the tasks best suited to mobile.

      -

      Alex: The next layer is this. Start with Learning Cards: GitHub Mobile Overview. There is something to understand, something to try, and something that proves the try worked.

      -

      Alex: The practical anchors are these. GitHub Mobile supports VoiceOver (iOS) and TalkBack (Android) natively -- swipe right to move through elements, double-tap to activate. The app uses five bottom tabs (Home, Notifications, Explore, Pull Requests, Profile) -- swipe left or right along the bottom tab bar to switch between them. Use the VoiceOver Rotor (two-finger twist) set to Headings to jump between sections within an issue or PR description. GitHub Mobile supports dynamic text sizing on both iOS and Android -- increase your system font size and the app respects it. Dark mode is available in the app settings and follows your system preference -- use it to reduce glare on OLED screens. The simplified diff view in Files Changed shows additions and removals as text only, without the two-column table layout used on desktop.

      -

      Jamie: What is the one idea that makes the next few steps less mysterious?

      -

      Alex: This is where 1. Installing GitHub Mobile becomes real: after installing, sign in with your GitHub account. That matters in practice: Enable notifications when prompted - these are essential for staying on top of PR reviews and issue activity without constantly checking the web.

      +

      Alex: Keep the teaching thread moving. Start with Scenario B: "I want to respond to review feedback on my PR": Example: Your PR for Challenge 3 (Complete Welcome Guide) received a review comment: "The [TODO] about evaluating issues is good, but the paragraph could mention checking if the issue is already assigned." The validation bot also flagged a link text issue.

      +

      Jamie: Let's pause on Writing PR Descriptions That Get Reviewed. What should a learner take away from it?

      +

      Alex: Here is the plain-English version of Writing PR Descriptions That Get Reviewed. See also: Appendix C: Markdown Reference for formatting your PR description with headings, lists, and task lists. Put another way, a pull request is only as useful as its description.

      +

      Jamie: Let's pause on What Reviewers Look For. What should a learner take away from it?

      +

      Alex: This is where What Reviewers Look For becomes real: when a reviewer opens your PR, they are asking four questions before they ever look at the diff. That matters in practice: If your description answers all four, the reviewer can jump straight into the code with context. The workshop is closer to rehearsal than lecture. You hear the move, try the move, and then check what changed.

      +

      Alex: First, why does this change exist? -- What problem does it solve, or what goal does it advance? Then, what is the scope? -- Which files changed, and roughly how big is the change? After that, how was it tested? -- Did you verify that the change works, and how? Finally, what should I pay attention to? -- Are there tricky parts, trade-offs, or areas where you want a second opinion? It is a checklist, but a meaningful one: every item creates evidence that the next step is safe.

      -

      Alex: Now bring the learner back to the room. Keep the learner anchored in 2. Getting Around the App. GitHub Mobile is organized into five main tabs at the bottom of the screen. This is the part to say slowly: Navigate between tabs with a single tap (or swipe on iOS with VoiceOver active).

      -

      Jamie: What would you say to someone who is already bracing for this to be too much?

      -

      Alex: Start with Enabling VoiceOver. There is something to understand, something to try, and something that proves the try worked.

      -

      Alex: The parts worth keeping in working memory are these. Triple-click the side button (iPhone X and later) or triple-click the Home button to toggle VoiceOver. Or: Settings → Accessibility → VoiceOver → toggle on.

      -

      Alex: The useful habit is simple: orient first, act second, verify third. That pause before acting is part of the work.

      -

      Alex: That matters because of the next idea. Start with Rotor in GitHub Mobile: Open the Rotor by rotating two fingers on the screen as if turning a dial. The next useful detail is this: Useful rotor settings for GitHub Mobile. Think of it like entering a new building: first you find the lobby, then the room, then the door you actually need.

      -

      Alex: On the ground, that means a few things. Headings - jump between section headings on an issue or PR description. Links - navigate to linked issues, commits, or external URLs. Form Controls - jump to input fields when writing a comment. Actions - available actions for the focused element (assign, label, close).

      +

      Jamie: Let's pause on The Closes XX Pattern. What should a learner take away from it?

      +

      Alex: Keep the learner anchored in The Closes XX Pattern. GitHub recognizes special keywords in PR descriptions that automatically close linked issues when the PR merges. This is the part to say slowly: You do not need to close issues by hand -- just include the right keyword followed by the issue number.

      +

      Alex: Keep the teaching thread moving. The reason Before/After Structure matters is that one of the most effective patterns for PR descriptions is showing the state before your change and the state after. That gives the learner a simple foothold: this gives the reviewer an instant mental model of what changed without reading the diff line by line.

      +

      Jamie: Let's pause on A PR Description Template. What should a learner take away from it?

      +

      Alex: Start with A PR Description Template: Here is a template you can copy into your PR descriptions. The next useful detail is this: Not every section applies to every PR, but filling in even a few sentences per section makes a meaningful difference.

      -

      Jamie: How would you walk the room through that step by step?

      -

      Alex: Start with Writing Comments with VoiceOver. There is something to understand, something to try, and something that proves the try worked.

      -

      Alex: First, navigate to the comment field (swipe to it or use Rotor → Form Controls). Then, double tap to activate and open the keyboard. After that, type your comment; VoiceOver announces each character. Finally, when done, swipe to the Comment button and double tap to submit. Treat it like a recipe: do not add the next ingredient until the previous one is actually in the bowl.

      -

      Alex: This is where the talk moves from concept to action. Start with Enabling TalkBack. There is something to understand, something to try, and something that proves the try worked.

      -

      Alex: The room should hear these as checkpoints. Settings → Accessibility → TalkBack → toggle on. Or: hold both volume keys for three seconds (if the shortcut is enabled).

      -

      Jamie: Where do you want a learner to place their attention here?

      -

      Alex: Keep the learner anchored in TalkBack Menu. Tap with three fingers (or swipe down then right) to open the TalkBack menu.

      -

      Alex: These are the details that keep the idea from floating away. Change the reading granularity (character, word, line, paragraph). Activate reading controls. Copy text.

      +

      Alex: Keep the teaching thread moving. Here is the plain-English version of Common Description Mistakes. Even experienced contributors make these mistakes. Put another way, knowing what to avoid is half the battle. It is like learning a transit route. The names of the stops matter because they tell you whether you are still going the right direction.

      +

      Jamie: Let's pause on Good vs. Bad: Side by Side. What should a learner take away from it?

      +

      Alex: This is where Good vs. Bad: Side by Side becomes real: no context, no linked issue, no explanation of what file or what was wrong with it. That matters in practice: A reviewer seeing this has to open the diff, figure out which file changed, read every line, and guess at the intent.

      +

      Alex: Keep the teaching thread moving. Start with Learning Cards: Writing PR Descriptions That Get Reviewed. There is something to understand, something to try, and something that proves the try worked.

      +

      Alex: The practical takeaway is this. Use Markdown headings ( ) in your description (Summary, Changes, Related Issues, Testing) so reviewers can press H to jump between sections. Type Closes followed by the issue number to auto-close the linked issue on merge; GitHub autocompletes when you type. Press Ctrl+Shift+P in the description text area to toggle between Write and Preview modes; Preview renders your Markdown so you can check structure before submitting. Use the Preview tab to verify your Markdown renders correctly; headings, bullet lists, and code blocks are easier to proofread in rendered form. Keep bullet points short (one line each) so the description is scannable at high zoom without excessive horizontal scrolling. When including screenshots, add alt text in the Markdown image syntax: so every reader gets the same information.

      -

      Jamie: What is the ordered workflow?

      -

      Alex: Start with Writing Comments with TalkBack. There is something to understand, something to try, and something that proves the try worked.

      -

      Alex: First, locate the comment field - TalkBack announces "Edit text, double tap to edit". Then, double tap to enter the field. After that, use the on-screen keyboard or dictation to type. Finally, locate the Comment button and double tap to submit. The rhythm is simple: orient, act, verify, then continue.

      -

      Jamie: Give me the version that sounds like an instructor, not a manual.

      -

      Alex: Start with 5. Working with Notifications: GitHub Mobile's Notifications tab is one of its strongest features for AT users - it surfaces all activity in a clean, linear list that is much easier to navigate than the GitHub web notifications page.

      +

      Jamie: Let's pause on Try It: Read a Real Pull Request. What should a learner take away from it?

      +

      Alex: The reason Try It: Read a Real Pull Request matters is that time: 3 minutes What you need: Browser, signed in to GitHub. That gives the learner a simple foothold: go to the Learning Room repository's Pull Requests tab and find any open or recently closed PR.

      +

      Alex: First, navigate to Pull Requests (G then P in Focus Mode). Then, open the first PR in the list (press Enter on its title). After that, read the description - press 2 to jump to the first section heading, then arrow down to read. Look for: which file was changed (docs/welcome.md, docs/keyboard-shortcuts.md, or docs/setup-guide.md)? Which challenge was this PR solving? Does the description. Finally, check the conversation - press 3 to jump between comments. Read what the validation bot reported - did the bot find any accessibility issues like broken headings or non-descriptive links? How did the author respond? The rhythm is simple: orient, act, verify, then continue.

      +

      Jamie: Before we leave Try It: Read a Real Pull Request, what is the practical point?

      +

      Alex: First, look at the diff - press D to the "Pull request tabs" landmark, then navigate to "Files changed" and press Enter. Press H to scan the changed file headings. If the PR touched docs/welcome.md, you should see + lines where the [TODO] sections were filled in. If. Think of it as a rail line: each stop confirms you are still on the right route before the next one.

      +

      Alex: Keep the teaching thread moving. Start with Managing Your GitHub Notification Inbox: See also: Appendix V: GitHub Mobile for managing notifications on your phone. The next useful detail is this: GitHub notifications are how GitHub tells you when something needs your attention. Think of it like entering a new building: first you find the lobby, then the room, then the door you actually need.

      Alex: A solid project habit is to treat metadata as decision support. Labels, status, assignees, and notifications tell you what kind of attention the work needs.

      -

      Alex: Hold that next to this. Start with Learning Cards: Mobile Notifications. There is something to understand, something to try, and something that proves the try worked.

      -

      Alex: That shows up in the workshop in a few specific ways. The Notifications tab presents a linear list that is more accessible than the web version -- swipe right through items one by one to hear each notification's context. Filter controls are accessible form elements at the top -- navigate to the filter icon, activate it, then swipe through filter options (Type, Repository, Reason). Swipe actions (left to archive, right to mark done) work with VoiceOver custom actions -- use the VoiceOver Actions rotor item on each notification. Notifications are displayed as a vertical list with the repository name, notification type, and title on each row -- text is sized according to your system accessibility settings. The filter panel overlays on top of the list -- look for the funnel icon in the top-right corner of the Notifications tab. Unread notifications appear with a blue dot indicator on the left edge of each row.

      +

      Jamie: What belongs in the live room, and what can wait until after?

      +

      Alex: Here is the plain-English version of Workshop Recommendation (Chapter 10). For this workshop, Chapter 10 is a guided practice chapter, not a graded automation chapter.

      +

      Alex: The practical takeaway is this. There are 1 guided walkthrough. Automation check: none - notification settings are account-level and cannot be validated by the Learning Room PR bot. The evidence is structured completion comment on your assigned challenge issue. The pattern is configure, filter, act.

      -

      Jamie: If I am listening before the workshop starts, what should settle in my mind first?

      -

      Alex: Start with Inbox Management. There is something to understand, something to try, and something that proves the try worked.

      -

      Alex: For a learner, the useful signals are these. Swipe left on a notification to reveal quick actions: Mark as read, Archive, Unsubscribe. Swipe right to mark as done. Tap a notification to open the full issue or PR.

      -

      Alex: That connects to another useful point. Keep the learner anchored in Filtering Notifications. Use the filter icon at the top right to filter. This is the part to say slowly: With VoiceOver or TalkBack, the filter controls are accessible form elements. A good GitHub workflow is like a well-run meeting: everyone knows the topic, the next action, and who has the floor.

      -

      Alex: Here is what that changes in practice. Type (Issues, PRs, Releases, etc.). Repository. Reason (you were @mentioned, a review was requested, etc.).

      -

      Jamie: Let's pause on 6. Reviewing Pull Requests. What should a learner take away from it?

      -

      Alex: The reason 6. Reviewing Pull Requests matters is that mobile is well suited for quick PR reviews - approving straightforward changes, leaving a comment, or checking CI status while away from your desk.

      -

      Alex: A solid pull request habit is to separate three questions: what changed, why it changed, and what still needs review. That keeps the conversation useful instead of noisy.

      +

      Jamie: Let's pause on Chapter 10 Challenge Set. What should a learner take away from it?

      +

      Alex: Start with Chapter 10 Challenge Set. There is something to understand, something to try, and something that proves the try worked.

      +

      Alex: First, configure notifications and practice inbox management - set your watch level, use filters to find relevant notifications, and perform one inbox action. It is a checklist, but a meaningful one: every item creates evidence that the next step is safe.

      +

      Jamie: Let's pause on Challenge 10.1 Step-by-Step: Notification Inbox Walkthrough. What should a learner take away from it?

      +

      Alex: Keep the learner anchored in Challenge 10.1 Step-by-Step: Notification Inbox Walkthrough. Set up a useful notification workflow so you can keep up with reviews, mentions, and assignments without inbox overload. This is the part to say slowly: the GitHub.com notifications page and your Learning Room repository settings.

      +

      Alex: The practical takeaway is this. Press M to mute the thread (you will not receive future updates),. Press E to mark done (removes it from inbox but you can still get future updates).

      +

      Alex: First, open your Learning Room repository on GitHub.com. Then, find the Watch button near the top-right of the repository page (next to Star and Fork). After that, 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. Finally, open the notifications inbox by navigating to https://github.com/notifications (or activate the bell icon in the GitHub header). It is like walking a hallway with named doors: read the sign, enter the right room, then confirm where you landed.

      +

      Jamie: Before we leave Challenge 10.1 Step-by-Step: Notification Inbox Walkthrough, what is the practical point?

      +

      Alex: First, in the notification filters, activate the Review requested filter. This shows only notifications where someone has asked you to review their PR. Then, clear that filter and activate the Assigned filter. This shows notifications for issues and PRs assigned to you. After that, open one notification by activating its title link. Read it briefly, then navigate back to the inbox. Finally, perform one inbox action on a non-critical notification thread. The rhythm is simple: orient, act, verify, then continue.

      +

      Alex: Keep the teaching thread moving. The reason Completing Chapter 10: Submit Your Evidence matters is that open your assigned Chapter 10 challenge issue and post a completion comment. That gives the learner a simple foothold: close your Chapter 10 challenge issue when done. The interface gets friendlier when it stops being a wall of controls and starts being a set of named places.

      -

      Alex: Here is the practical turn. Start with Navigating a PR: When you open a pull request, the screen is divided into sections. The next useful detail is this: VoiceOver and TalkBack announce these as headings.

      -

      Alex: That becomes easier when you listen for these cues. Description - the PR body with any images or checklists. Commits - individual commits in this PR. Files changed - a simplified diff view. Checks - CI/CD status.

      -

      Jamie: What does the learner do first, second, and then after that?

      -

      Alex: Start with Leaving a Review. There is something to understand, something to try, and something that proves the try worked.

      -

      Alex: First, scroll to or navigate to the Review changes button. Then, double tap to open the review panel. After that, choose Approve, Request changes, or Comment. Finally, add an optional comment in the text field. Treat it like a recipe: do not add the next ingredient until the previous one is actually in the bowl.

      -

      Jamie: Turn that into a path someone can follow.

      -

      Alex: First, activate Submit review. It is a checklist, but a meaningful one: every item creates evidence that the next step is safe.

      -

      Alex: Keep the thread going. This is where Viewing Diffs becomes real: the Files Changed tab shows a simplified diff - additions and removals are text-only (no table layout). That matters in practice: Each changed line is announced as "Added: [content]" or "Removed: [content]", which is generally more accessible than the web diff table on small screens. The workshop is closer to rehearsal than lecture. You hear the move, try the move, and then check what changed.

      +

      Jamie: Let's pause on Expected Outcomes. What should a learner take away from it?

      +

      Alex: Start with Expected Outcomes. There is something to understand, something to try, and something that proves the try worked.

      +

      Alex: The practical takeaway is this. 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.

      +

      Jamie: What is the teaching move inside If You Get Stuck?

      +

      Alex: First, can't find the Watch button? It is near the top-right of the repository page, in the same row as Star and Fork. Then, 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. After that, 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. Finally, filters not showing results? Clear all filters first (click the X next to each active filter), then apply one filter at a time. Treat it like a recipe: do not add the next ingredient until the previous one is actually in the bowl.

      +

      Jamie: If someone only remembers one thing from If You Get Stuck, what should it be?

      +

      Alex: First, ask facilitator to model one inbox action live, then repeat the steps yourself. Then, finished but not sure you did it right? Compare your work against the Challenge 9 reference solution. It is a checklist, but a meaningful one: every item creates evidence that the next step is safe.

      +

      Jamie: Let's pause on Learning Moment. What should a learner take away from it?

      +

      Alex: This is where Learning Moment becomes real: notification management protects focus. That matters in practice: You can stay responsive to your team without drowning in updates.

      -

      Jamie: Give me the sequence, because order matters here.

      -

      Alex: Start with Filing an Issue. There is something to understand, something to try, and something that proves the try worked.

      -

      Alex: First, navigate to the repository. Then, tap Issues → the + button or New Issue. After that, fill in the title and body. Finally, optionally assign labels, assignees, and milestone - each is a tappable field. It is like walking a hallway with named doors: read the sign, enter the right room, then confirm where you landed.

      -

      Jamie: Let's pause on Filing an Issue. What should a learner take away from it?

      -

      Alex: First, tap Submit. The rhythm is simple: orient, act, verify, then continue.

      -

      Alex: A solid issue habit is to read the title, the body, and the timeline before acting. You are listening for the requested action, the missing evidence, and the person who needs a response.

      -

      Alex: Another way to ground it. Start with Finding Your Issues. There is something to understand, something to try, and something that proves the try worked.

      -

      Alex: A few details make that real. Pull Requests tab → Created by you or Assigned to you filters. For issues: Home feed shows recent activity; or navigate to a specific repository → Issues → filter by Assignee, Label, or Author.

      -

      Jamie: What stays the same when the tool changes?

      -

      Alex: Start with 8. What Mobile Does Well vs. Desktop: Best use of GitHub Mobile: notification triage, quick approvals and comments, catching up on activity between sessions. The next useful detail is this: For writing substantial code, descriptions, or reviewing complex diffs, use the web or VS Code.

      +

      Jamie: Let's pause on Learning Pattern Used in This Chapter. What should a learner take away from it?

      +

      Alex: Start with Learning Pattern Used in This Chapter. There is something to understand, something to try, and something that proves the try worked.

      +

      Alex: First, configure settings proactively (watch level) before work generates noise. Then, use filters to find signal in noise (review requests, assignments). After that, take decisive action on each notification (mute, done, or respond). Finally, build a daily routine that keeps your inbox manageable. It is like walking a hallway with named doors: read the sign, enter the right room, then confirm where you landed.

      +

      Jamie: Let's pause on What Generates a Notification? What should a learner take away from it?

      +

      Alex: The reason What Generates a Notification? matters is that GitHub sends you a notification when.

      +

      Alex: Keep the teaching thread moving. Start with Notification Subscription Levels: For each repository, you choose how many notifications to receive.

      -

      Alex: This is the part worth saying out loud. Here is the plain-English version of VoiceOver skips some PR descriptions. Long PR descriptions with images, tables, or embedded videos may not read cleanly. Put another way, open the PR in Safari instead - tap the … menu → Open in Browser. It is like learning a transit route. The names of the stops matter because they tell you whether you are still going the right direction.

      -

      Jamie: Let's pause on TalkBack does not announce new notifications badge. What should a learner take away from it?

      -

      Alex: This is where TalkBack does not announce new notifications badge becomes real: the badge count on the Notifications tab updates live but may not be announced. That matters in practice: Navigate directly to the Notifications tab to get the current count read aloud.

      -

      Alex: Before the learner moves on. Keep the learner anchored in The keyboard covers the comment field. Usual iOS/Android behavior - scroll up slightly after the keyboard appears, or rotate to landscape mode to gain more visible space.

      -

      Alex: A solid navigation habit is to prove where you are before activating controls. Headings, landmarks, and the address bar are not trivia; they are your map.

      +

      Jamie: Let's pause on Changing your watch settings for a repo. What should a learner take away from it?

      +

      Alex: Here is the plain-English version of Changing your watch settings for a repo. At the top of any repository page, find the Watch button (near Star and Fork). Put another way, click it to open a dropdown with levels: Participating and @mentions, All Activity, Custom, and Ignore.

      +

      Alex: First, find the Watch button in the repo header (B to navigate buttons → find "Watch [N]" or "Unwatch" button). Then, press Enter to open the dropdown. After that, press ↑/↓ to navigate the subscription options. Finally, press Enter to select your preferred level. Treat it like a recipe: do not add the next ingredient until the previous one is actually in the bowl.

      +

      Jamie: Before we leave Changing your watch settings for a repo, what is the practical point?

      +

      Alex: First, the button label updates to confirm your choice. Then, quick Nav B to find the Watch button in the repo header (listen for "Watch" or "Unwatch"). After that, vO+Space to open the dropdown. Finally, vO+Down or arrow keys to navigate subscription options. It is a checklist, but a meaningful one: every item creates evidence that the next step is safe.

      +

      Jamie: Let's pause on Tool Cards: Manage Notifications. What should a learner take away from it?

      +

      Alex: This is where Tool Cards: Manage Notifications becomes real: VS Code Desktop (GitHub Pull Requests extension). That matters in practice: GitHub Desktop: GitHub Desktop does not manage notifications. The workshop is closer to rehearsal than lecture. You hear the move, try the move, and then check what changed.

      +

      Alex: First, go to github.com/notifications (or press G then N). Then, use E to mark done, I to mark read/unread, Shift+M to mute a thread. After that, the Notifications view in the GitHub sidebar shows items needing attention. Finally, click a notification to open the related issue or PR directly in VS Code. It is a checklist, but a meaningful one: every item creates evidence that the next step is safe.

      +

      Alex: Treat examples as spoken recipes, not decorations. You may hear something like 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. 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. Read the command, understand what it changes, then run it only when the repository state matches the lesson.

      +

      Jamie: Let's pause on Navigating the notification list. What should a learner take away from it?

      +

      Alex: Keep the learner anchored in Navigating the notification list. The inbox shows notifications grouped by date (Today, Yesterday, This week, Older). This is the part to say slowly: Each row shows the repository, the issue or PR title, the event type, and the time.

      +

      Alex: First, d → main content landmark. Then, h to navigate group headings (Today / Yesterday / This week / Older). After that, tab through individual notifications - each row announces: repo name, issue/PR title, event type, time. Finally, enter to open the notification (goes to the issue/PR page). It is like walking a hallway with named doors: read the sign, enter the right room, then confirm where you landed.

      +

      Jamie: Before we leave Navigating the notification list, what is the practical point?

      +

      Alex: First, vO+U → Main → navigate to notification list. Then, vO+Down to move through notifications. After that, vO+Space to open a notification. The rhythm is simple: orient, act, verify, then continue.

      -

      Jamie: Let's pause on Can't find the Submit button after writing a review. What should a learner take away from it?

      -

      Alex: The reason Can't find the Submit button after writing a review matters is that scroll down past the text field; buttons are below the keyboard dismiss area. That gives the learner a simple foothold: on iOS, tap elsewhere to dismiss the keyboard first, then scroll to Submit.

      -

      Alex: Keep the teaching thread moving. Start with GitHub Mobile crashes or freezes: If the problem persists, sign out and back in via Profile → Settings → Sign out. The next useful detail is this: Next: Appendix W: GitHub Pages Back: Appendix U: Discussions and Gists Teaching chapter: Chapter 05: Working with Issues. Think of it like entering a new building: first you find the lobby, then the room, then the door you actually need.

      +

      Alex: Keep the teaching thread moving. The reason What is announced per notification matters is that "microsoft/vscode - Add keyboard shortcut for accessible view - @username mentioned you - 2 hours ago". That gives the learner a simple foothold: components: repo/org thread title event type timestamp.

      +

      Jamie: Let's pause on Learning Cards: The Notifications Inbox. What should a learner take away from it?

      +

      Alex: Start with Learning Cards: The Notifications Inbox. There is something to understand, something to try, and something that proves the try worked.

      +

      Alex: The practical takeaway is this. 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. 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.

      +

      Alex: Keep the teaching thread moving. Here is the plain-English version of Inbox Actions - Keyboard Shortcuts. These shortcuts work when a notification is focused in the inbox. Put another way, these are GitHub's own keyboard shortcuts. It is like learning a transit route. The names of the stops matter because they tell you whether you are still going the right direction.

      +

      Alex: A solid navigation habit is to prove where you are before activating controls. Headings, landmarks, and the address bar are not trivia; they are your map.

      -

      Jamie: What should people carry with them after this?

      -

      Alex: Carry the map. Know what page or tool you are in, know which action you are taking, and know what confirmation should follow. If the confirmation is missing, pause. That pause is not wasted time; it is professional judgment.

      -

      Jamie: That is a better way to say it than just follow the steps.

      -

      Alex: Right. Steps matter, but understanding wins. That is episode 32. Next in the series is episode 33, where we keep building the same contributor muscles.

      -
      - +

      Jamie: Let's pause on Filtering the Inbox. What should a learner take away from it?

      +

      Alex: This is where Filtering the Inbox becomes real: the left sidebar has quick filters.

      +

      Jamie: Let's pause on Filtering by repository or organization. What should a learner take away from it?

      +

      Alex: Keep the learner anchored in Filtering by repository or organization. At the top of the notification list there is a filter/search field. This is the part to say slowly: Click the filter/search box at the top of the notification list and type a repository or organization name.

      +

      Alex: First, press F or E to reach the filter input. Then, focus Mode → type repo name or org name. After that, results filter in real time. Finally, press Esc to clear the filter. It is like walking a hallway with named doors: read the sign, enter the right room, then confirm where you landed.

      +

      Jamie: Before we leave Filtering by repository or organization, what is the practical point?

      +

      Alex: First, quick Nav F to reach the filter input. Then, vO+Shift+Down to interact → type repo or org name. After that, press Esc to clear the filter and VO+Shift+Up to stop interacting. The rhythm is simple: orient, act, verify, then continue.

      +

      Jamie: Let's pause on The "mark all as done" workflow. What should a learner take away from it?

      +

      Alex: The reason The "mark all as done" workflow matters is that after a busy day or coming back from time away, clear your inbox methodically.

      +

      Alex: First, open Notifications inbox. Then, tab to "Mark all as done" button → Enter (clears everything at once). After that, then use the "Done" filter to retrieve any you want to revisit. The rhythm is simple: orient, act, verify, then continue.

      -

      Episode 33: Publishing with GitHub Pages

      -

      Free static site hosting, custom domains, HTTPS, and accessibility.

      -

      Based on: Appendix W: Publishing with GitHub Pages

      -

      Audio and transcript are being regenerated for this episode.

      -
      -Read Transcript - Episode 33: Publishing with GitHub Pages - -

      Transcript

      -

      Alex: Welcome back to Git Going with GitHub. This is episode 33: Publishing with GitHub Pages. I am Alex, and today we are turning Publishing with GitHub Pages from a list of instructions into a working mental model.

      -

      Jamie: And I am Jamie. I will stop us whenever the instructions sound simple on paper but might feel different with a keyboard and screen reader.

      -
      -

      Alex: Free static site hosting, custom domains, HTTPS, and accessibility. That is the surface description. Underneath it, we are building judgment: where to focus, what to ignore, and how to verify the result.

      -

      Jamie: So we are not using the audio as a shortcut around learning. We are using it to make the learning easier to enter.

      -

      Alex: Yes. A good audio lesson gives someone enough context to try the work with confidence, even before they open the written material.

      -
      -

      Jamie: Okay, set the room for us. What are we walking into?

      -

      Alex: Start with How to Deploy a Static Website Directly from Your Repository: GitHub Pages lets you publish a static website straight from a GitHub repository - no server, no hosting bill, no deployment pipeline required for simple sites. The next useful detail is this: This appendix explains how to enable it, what it can publish, and how to ensure the published site meets the same accessibility standards as your source code.

      -

      Alex: The next layer is this. Start with Learning Cards: GitHub Pages Overview. There is something to understand, something to try, and something that proves the try worked.

      -

      Alex: The practical anchors are these. The Pages settings are under Settings (gear icon in repository navigation) then "Pages" in the left sidebar under the "Code and automation" group heading. Branch and folder selectors in the Pages settings are standard select elements -- navigate with arrow keys to choose your publishing source. After deployment, the published URL appears as a link at the top of the Pages settings page. GitHub Pages settings use the same layout as other repository settings -- look for the "Pages" link in the left sidebar after clicking Settings. The deployment status indicator shows a green checkmark for successful deployments and a red X for failures. Published sites inherit no special styling from GitHub -- ensure your site's CSS provides adequate contrast and font sizing.

      -

      Jamie: What is the one idea that makes the next few steps less mysterious?

      -

      Alex: This is where 1. What GitHub Pages Is becomes real: GitHub Pages is a static site hosting service built into GitHub. That matters in practice: It serves files directly from a branch or folder in your repository at a URL of the form.

      -
      -

      Alex: Now bring the learner back to the room. Start with What it is good for. There is something to understand, something to try, and something that proves the try worked.

      -

      Alex: For a learner, the useful signals are these. Documentation sites. Workshop materials (like this project). Project landing pages. Personal portfolios. Simple blogs via Jekyll.

      -

      Jamie: What is the ordered workflow?

      -

      Alex: The reason Step-by-step (GitHub.com) matters is that GitHub will build and deploy within a minute or two. That gives the learner a simple foothold: the URL appears at the top of the Pages settings once the first deployment succeeds.

      -

      Alex: The parts worth keeping in working memory are these. Deploy from a branch - serve files directly from a branch/folder. GitHub Actions - use a workflow to build and deploy. Select the branch (e.g. main or master). Select the folder: / (root) or /docs.

      -

      Alex: First, go to the repository on GitHub.com. Then, click Settings (the gear icon in the top navigation). After that, in the left sidebar, scroll to Code and automation and click Pages. Finally, under Build and deployment, choose your publishing source. The rhythm is simple: orient, act, verify, then continue.

      -

      Jamie: Give me the sequence, because order matters here.

      -

      Alex: First, if using "Deploy from a branch". Then, click Save. Think of it as a rail line: each stop confirms you are still on the right route before the next one.

      -

      Alex: The useful habit is simple: orient first, act second, verify third. That pause before acting is part of the work.

      -

      Alex: That matters because of the next idea. Start with Screen reader navigation for the Pages settings page. There is something to understand, something to try, and something that proves the try worked.

      -

      Alex: On the ground, that means a few things. The Settings tab is a link in the repository's top navigation bar. It has the accessible name "Settings". The Pages option in the left sidebar is a link under the "Code and automation" group heading. The branch and folder dropdowns are standard elements - navigate with arrow keys.

      -

      Alex: A solid navigation habit is to prove where you are before activating controls. Headings, landmarks, and the address bar are not trivia; they are your map.

      -
      -

      Jamie: If I am listening before the workshop starts, what should settle in my mind first?

      -

      Alex: Here is the plain-English version of Deploy from a branch. GitHub reads files directly from a branch. Put another way, best practice: Use /docs to isolate the published content from source files, especially for projects with build pipelines where the output lives in a specific folder.

      -

      Alex: A solid Git habit is to know which branch you are on, what changed, and what confirmation you expect before you run the next command.

      -

      Jamie: What does the learner do first, second, and then after that?

      -

      Alex: This is where GitHub Actions becomes real: use a workflow (YAML file in.github/workflows/) to build your site before publishing. That matters in practice: A basic workflow for this project would.

      -

      Alex: The room should hear these as checkpoints. Your source is Markdown and you need a build step (e.g. this project's scripts/build-html.js). You are using a static site generator like Jekyll, Hugo, or Eleventy. You want to run accessibility tests in CI before publishing.

      -

      Alex: First, check out the repository. Then, run node scripts/build-html.js. After that, upload the html/ folder as the Pages artifact. It is a checklist, but a meaningful one: every item creates evidence that the next step is safe.

      -

      Jamie: Where do you want a learner to place their attention here?

      -

      Alex: Keep the learner anchored in 4. The html/ Folder in This Project. This project has a pre-built HTML mirror of all Markdown content in the html/ folder, generated by scripts/build-html.js. This is the part to say slowly: To publish this as a GitHub Pages site.

      -

      Alex: A solid pull request habit is to separate three questions: what changed, why it changed, and what still needs review. That keeps the conversation useful instead of noisy.

      -
      -

      Alex: Before the learner moves on. The reason Option A: Manual publishing from html/ folder matters is that because GitHub Pages only supports / (root) or /docs as folder sources, and this project's output is in html/, you have two options. The interface gets friendlier when it stops being a wall of controls and starts being a set of named places.

      -

      Jamie: What is the safe way to learn from that example?

      -

      Alex: Start with Option A1 - Copy html/ contents to docs/: Then set Pages source to branch master, folder /docs.

      -

      Alex: Treat examples as spoken recipes, not decorations. You may hear something like Copy the html/ output into docs/ for GitHub Pages; cp -r html/ docs/; git add docs/; git commit -m "Publish HTML output to docs/ for GitHub Pages"; git push. Read the command, understand what it changes, then run it only when the repository state matches the lesson.

      -

      Jamie: What should happen before anyone copies and runs it?

      -

      Alex: Here is the plain-English version of Option A2 - Rename html/ to docs/. If the project does not already use docs/ for Markdown sources, you could rename the output folder. Put another way, this project uses docs/ for Markdown source files, so this would conflict.

      -

      Alex: Treat examples as spoken recipes, not decorations. You may hear something like Update the build script output path first, then; git mv html/ docs/; git commit -m "Rename html/ to docs/ for GitHub Pages compatibility"; git push. Read the command, understand what it changes, then run it only when the repository state matches the lesson.

      +

      Jamie: Let's pause on Muting a noisy thread. What should a learner take away from it?

      +

      Alex: Start with Muting a noisy thread: If a thread generates too many notifications. The next useful detail is this: Screen reader users (NVDA / JAWS - Windows). Think of it like entering a new building: first you find the lobby, then the room, then the door you actually need.

      +

      Alex: First, open the issue or PR page. Then, in the right sidebar, scroll to the Notifications section. After that, click Unsubscribe - you will stop receiving notifications from this thread. Finally, alternatively, from the inbox: hover over the notification row and click the mute icon (or the … menu). Think of it as a rail line: each stop confirms you are still on the right route before the next one.

      +

      Jamie: Before we leave Muting a noisy thread, what is the practical point?

      +

      Alex: First, open the notification. Then, on the issue/PR page, navigate the sidebar to the Notifications section (H or D). After that, activate the Unsubscribe button. Finally, or from the inbox: focus the notification → press M to mute. Treat it like a recipe: do not add the next ingredient until the previous one is actually in the bowl.

      +

      Jamie: Let's pause on Dealing with @mentions you didn't expect. What should a learner take away from it?

      +

      Alex: Here is the plain-English version of Dealing with @mentions you didn't expect. If you were @mentioned in an unfamiliar thread.

      +

      Alex: First, read the thread for context before responding. Then, 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. After that, unsubscribe after reading if you don't need to stay in the loop. Treat it like a recipe: do not add the next ingredient until the previous one is actually in the bowl.

      +

      Alex: Keep the teaching thread moving. Start with Learning Cards: Managing Notifications at Scale. There is something to understand, something to try, and something that proves the try worked.

      +

      Alex: The practical takeaway is this. 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. 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.

      -

      Jamie: What would you say to someone who is already bracing for this to be too much?

      -

      Alex: This is where Option B: GitHub Actions workflow becomes real: this workflow triggers on every push to master, rebuilds the HTML, and deploys the html/ folder.

      -

      Alex: That connects to another useful point. Keep the learner anchored in 5. Custom Domains. GitHub Pages supports custom domains (e.g. This is the part to say slowly: learning.community-access.org instead of community-access.github.io/Learning-Room). A good GitHub workflow is like a well-run meeting: everyone knows the topic, the next action, and who has the floor.

      -

      Jamie: How would you walk the room through that step by step?

      -

      Alex: Start with Setting up a custom domain. There is something to understand, something to try, and something that proves the try worked.

      -

      Alex: First, in repository Settings → Pages, enter your domain in the Custom domain field and click Save. Then, GitHub creates a CNAME file in the repository root containing your domain name. After that, at your DNS provider, create the appropriate records. The rhythm is simple: orient, act, verify, then continue.

      +

      Jamie: Let's pause on Notification Settings - Per Your Account. What should a learner take away from it?

      +

      Alex: Keep the learner anchored in Notification Settings - Per Your Account. Global notification preferences are at https://github.com/settings/notifications.

      +

      Alex: Keep the teaching thread moving. The reason Starring vs. Watching - What Is the Difference? matters is that new contributors often confuse these two. That gives the learner a simple foothold: they appear next to each other on every repository page and do completely different things. The interface gets friendlier when it stops being a wall of controls and starts being a set of named places.

      +

      Jamie: Let's pause on Starring a Repository. What should a learner take away from it?

      +

      Alex: Start with Starring a Repository: Starring is GitHub's equivalent of a bookmark + public endorsement. The next useful detail is this: The star count on a repository is a community signal of popularity.

      -

      Alex: Here is the practical turn. Start with GitHub's current A record IPs for apex domains: DNS changes can take up to 48 hours to propagate. The next useful detail is this: GitHub Pages checks and verifies the domain automatically once DNS is configured.

      -

      Jamie: Give me the version that sounds like an instructor, not a manual.

      -

      Alex: Here is the plain-English version of Domain verification. To prevent domain takeover attacks, GitHub recommends verifying your custom domain in your account or organization settings (Settings → Pages → Add a domain). Put another way, this prevents others from claiming your domain for their GitHub Pages if you temporarily remove it.

      -

      Jamie: Turn that into a path someone can follow.

      -

      Alex: This is where 6. HTTPS and Security becomes real: GitHub Pages enforces HTTPS automatically for github.io subdomains. That matters in practice: Never store secrets, API keys, or private data in a GitHub Pages repository. The workshop is closer to rehearsal than lecture. You hear the move, try the move, and then check what changed.

      -

      Alex: First, after DNS propagates, check Enforce HTTPS in Pages settings. Then, GitHub Pages uses Let's Encrypt to provision a certificate automatically. After that, enforcing HTTPS redirects all HTTP traffic to HTTPS. It is a checklist, but a meaningful one: every item creates evidence that the next step is safe.

      +

      Alex: Keep the teaching thread moving. Here is the plain-English version of 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. Put another way, 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.

      +

      Jamie: Let's pause on How to silence a repository you accidentally over-subscribed to. What should a learner take away from it?

      +

      Alex: This is where How to silence a repository you accidentally over-subscribed to becomes real: this immediately reduces notifications from that repository to only threads you personally participated in.

      +

      Alex: Keep the teaching thread moving. Start with Learning Cards: Starring vs. Watching. There is something to understand, something to try, and something that proves the try worked.

      +

      Alex: The practical takeaway is this. 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. 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.

      -

      Jamie: Let's pause on 7. Accessibility Considerations for Published Sites. What should a learner take away from it?

      -

      Alex: Keep the learner anchored in 7. Accessibility Considerations for Published Sites. Publishing a site does not automatically make it accessible. This is the part to say slowly: Consider the following for the published HTML output.

      -

      Alex: Another way to ground it. Start with Learning Cards: Accessibility of Published Sites. There is something to understand, something to try, and something that proves the try worked.

      -

      Alex: That becomes easier when you listen for these cues. Verify that published HTML pages include a skip-to-content link as the first focusable element -- press Tab once after the page loads to check. Confirm the page has a descriptive title element and a single H1 heading -- these are announced first when the page opens. Test that all internal navigation links work and land on the correct heading or section. Run an automated contrast checker (axe, WAVE) on published pages after any CSS changes to confirm text remains readable. Test the published site at 200% browser zoom to verify layouts do not break or hide content. If the site uses a custom theme, verify it works in both forced-colors mode (Windows High Contrast) and standard mode.

      -

      Jamie: Let's pause on Navigation and landmarks. What should a learner take away from it?

      -

      Alex: Start with Navigation and landmarks: The HTML generated by scripts/build-html.js converts Markdown headings and structure to HTML.

      -

      Alex: A few details make that real. A landmark wrapping the primary content. Logical heading hierarchy (H1 → H2 → H3). A page that reflects the document topic.

      +

      Jamie: Let's pause on NVDA. What should a learner take away from it?

      +

      Alex: Start with NVDA. There is something to understand, something to try, and something that proves the try worked.

      +

      Alex: The practical takeaway is this. 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.

      +

      Alex: Keep the teaching thread moving. Start with JAWS. There is something to understand, something to try, and something that proves the try worked.

      +

      Alex: The practical takeaway is this. 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.

      +

      Jamie: Let's pause on VoiceOver. What should a learner take away from it?

      +

      Alex: Start with VoiceOver. There is something to understand, something to try, and something that proves the try worked.

      +

      Alex: The practical takeaway is this. 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.

      -

      Alex: This is the part worth saying out loud. Here is the plain-English version of Skip navigation. For sites with repeated navigation on every page, add a skip link as the first element in. It is like learning a transit route. The names of the stops matter because they tell you whether you are still going the right direction.

      -

      Jamie: Let's pause on Focus management for single-page navigation. What should a learner take away from it?

      -

      Alex: This is where Focus management for single-page navigation becomes real: if the site uses JavaScript to load content without full page reloads, manage focus explicitly when content changes. That matters in practice: Move focus to the new or a wrapper with tabindex="-1" after navigation.

      -

      Alex: Keep the thread going. Keep the learner anchored in Image alt text. All images in published pages should have appropriate alt attributes. This is the part to say slowly: Decorative images should use alt="" (empty, not missing) to be skipped by screen readers.

      +

      Alex: Keep the teaching thread moving. This is where The GitHub Mobile App - A Reference Note becomes real: GitHub has an iOS and Android app that supports push notifications. That matters in practice: While the app itself is not covered as a primary tool in this workshop, it is worth knowing. The workshop is closer to rehearsal than lecture. You hear the move, try the move, and then check what changed.

      +

      Alex: The practical takeaway is this. 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.

      +

      Jamie: Let's pause on Try It: Tame Your Inbox. What should a learner take away from it?

      +

      Alex: Keep the learner anchored in Try It: Tame Your Inbox. Time: 2 minutes What you need: Browser, signed in to GitHub. This is the part to say slowly: Go to github.com/notifications and practice.

      +

      Alex: First, scan your inbox - Press H and Tab to navigate through notifications. Each one shows the repo name, type (issue/PR), and title. Then, mark one as done - Find a notification you've already read. Press E to mark it as done. It disappears from the list. After that, 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. It is like walking a hallway with named doors: read the sign, enter the right room, then confirm where you landed.

      +

      Alex: Keep the teaching thread moving. The reason What You Accomplished Today matters is that day 1 is complete -- and you did a lot. That gives the learner a simple foothold: here is every skill you practiced, mapped to the chapter where you learned it and the evidence you created along the way.

      -

      Jamie: Let's pause on Color contrast. What should a learner take away from it?

      -

      Alex: The reason Color contrast matters is that run the published pages through an automated checker (axe, WAVE) after changes to the stylesheet to verify contrast ratios remain compliant.

      -

      Alex: This is where the talk moves from concept to action. Start with Testing the published site: After deployment, test the live URL rather than only local files. The next useful detail is this: mixed content, broken relative links, missing files) only appear when served from a web server. Think of it like entering a new building: first you find the lobby, then the room, then the door you actually need.

      -

      Jamie: Let's pause on Recommended post-deployment checks. What should a learner take away from it?

      -

      Alex: Start with Recommended post-deployment checks. There is something to understand, something to try, and something that proves the try worked.

      -

      Alex: First, navigate all pages keyboard-only. Then, run axe DevTools on the index page and at least one content page. After that, verify no broken links with a link checker (e.g. W3C Link Checker). Finally, test with a screen reader announcement of the page title. Treat it like a recipe: do not add the next ingredient until the previous one is actually in the bowl.

      +

      Jamie: Let's pause on If This Was Your First Time. What should a learner take away from it?

      +

      Alex: Start with 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. The next useful detail is this: You navigated a complex platform, created real contributions, and collaborated with other people in a shared codebase.

      +

      Jamie: Let's pause on Confidence Check. What should a learner take away from it?

      +

      Alex: Here is the plain-English version of Confidence Check. Before you close your laptop, take two minutes to answer these questions in your Chapter 10 challenge issue. Put another way, there are no wrong answers -- this is for you. It is like learning a transit route. The names of the stops matter because they tell you whether you are still going the right direction.

      +

      Alex: First, which chapter felt the most natural to you? Which one do you want to revisit? Then, can you explain what a pull request does to someone who has never used GitHub? After that, if you saw a merge conflict right now, would you know where to start? Finally, what is one thing you want to try on GitHub this week that you did not get to today? Treat it like a recipe: do not add the next ingredient until the previous one is actually in the bowl.

      +

      Jamie: Why is the evidence prompt part of the teaching, not just grading?

      +

      Alex: This is where Your Challenge Progress becomes real: look at how many challenge issues you completed today. That matters in practice: Each one represents a skill you did not just read about -- you practiced it, posted evidence, and moved on.

      -

      Alex: Hold that next to this. This is where 8. GitHub Actions and Continuous Deployment becomes real: using the Actions workflow described in Section 4 means every push to master automatically rebuilds and redeploys the site.

      -

      Jamie: Let's pause on Adding automated accessibility checks to the workflow. What should a learner take away from it?

      -

      Alex: Keep the learner anchored in Adding automated accessibility checks to the workflow. Extend the workflow to fail the build if accessibility violations are found. This is the part to say slowly: This uses the axe-core CLI to scan the built index page.

      -

      Alex: Keep the teaching thread moving. Start with Site not updating after a push. There is something to understand, something to try, and something that proves the try worked.

      -

      Alex: That shows up in the workshop in a few specific ways. Check the Actions tab for a failed deploy workflow. Check Settings → Pages - the most recent deployment timestamp should match your push. Hard-refresh the browser (Ctrl+F5 / Cmd+Shift+R) to bypass the cache. DNS TTL caching can delay custom domain updates up to the TTL value (often 1 hour).

      +

      Alex: Keep the teaching thread moving. Start with Learning Cards: What You Accomplished Today. There is something to understand, something to try, and something that proves the try worked.

      +

      Alex: The practical takeaway is this. 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. 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.

      +

      Jamie: Where is the promise of the workshop, underneath all the logistics?

      +

      Alex: The reason What Day 2 Adds matters is that see also: Chapter 11: VS Code Interface is where Day 2 begins -- have VS Code installed and ready. That gives the learner a simple foothold: on Day 1, you worked entirely on GitHub.com.

      +

      Jamie: Let's pause on Between Days. What should a learner take away from it?

      +

      Alex: Start with 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. The next useful detail is this: GitHub Skills courses use bot-driven feedback inside pull requests. Think of it like entering a new building: first you find the lobby, then the room, then the door you actually need.

      +

      Alex: First, explore your notification settings. Now that you understand how notifications work, visit github.com/settings/notifications and customize your email and web preferences. There is no wrong configuration -- just find what feels manageable. Then, 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. After that, try a GitHub Skills course. GitHub Skills 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 for the full list of recommended courses. Think of it as a rail line: each stop confirms you are still on the right route before the next one.

      -

      Jamie: Let's pause on 404 on all pages except index. What should a learner take away from it?

      -

      Alex: Start with 404 on all pages except index: This usually indicates a base URL mismatch. The next useful detail is this: If your site is at https://user.github.io/my-repo/, all relative asset and link paths must account for the /my-repo/ path prefix.

      -

      Alex: Keep the teaching thread moving. Start with HTTPS certificate not provisioning. There is something to understand, something to try, and something that proves the try worked.

      -

      Alex: Here is what that changes in practice. Verify DNS records are correctly set. Ensure the domain is not proxied through a CDN (e.g. Cloudflare orange-cloud) - GitHub Pages needs to see the DNS record directly to provision the cert. Allow up to 24 hours after correct DNS propagation.

      -

      Jamie: Let's pause on Screen reader announces wrong page title. What should a learner take away from it?

      -

      Alex: This is where Screen reader announces wrong page title becomes real: the published element is set during the HTML build step. That matters in practice: Update the template in scripts/build-html.js to ensure each page has a unique, descriptive title.

      +

      Jamie: Let's pause on You Already Know More Than You Think. What should a learner take away from it?

      +

      Alex: Here is the plain-English version of You Already Know More Than You Think. Think about where you started this morning. Put another way, 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.

      -

      Jamie: What should people carry with them after this?

      -

      Alex: Carry the map. Know what page or tool you are in, know which action you are taking, and know what confirmation should follow. If the confirmation is missing, pause. That pause is not wasted time; it is professional judgment.

      -

      Jamie: That is a better way to say it than just follow the steps.

      -

      Alex: Right. Steps matter, but understanding wins. That is episode 33. Next in the series is episode 34, where we keep building the same contributor muscles.

      +

      Jamie: What is the final checkpoint?

      +

      Alex: You should be able to point to the evidence, explain the action, and describe what you would do next if this were a real open source project. If you can teach the move back, you have learned it.

      +

      Jamie: And if they get stuck?

      +

      Alex: Read the latest message, not the loudest worry. Check the issue, the branch, the pull request, the status check, or the bot comment. Then ask for help with those facts in hand. That is how professionals collaborate.

      -

      Episode 34: GitHub Actions and Workflows

      -

      Workflow YAML structure, CI/CD, automation, and the Actions marketplace.

      -

      Based on: Appendix Q: GitHub Actions and Workflows

      +

      29. Challenge bonus-d: Notifications

      +

      Notification hygiene, mentions, subscriptions, and avoiding overload.

      +

      Practice focus: Bonus

      Audio and transcript are being regenerated for this episode.

      -Read Transcript - Episode 34: GitHub Actions and Workflows +Read Transcript - Challenge bonus-d: Notifications

      Transcript

      -

      Alex: This is Git Going with GitHub, episode 34: GitHub Actions and Workflows. I am Alex. By the end of this episode, GitHub Actions and Workflows should feel less like a wall of GitHub words and more like a set of moves you can trust.

      -

      Jamie: And I am Jamie. I am here for the practical questions: what should I listen for, what can go wrong, and what is the next calm move?

      +

      Alex: Welcome to Challenge Coach: Notifications. I am Alex. Before you do the task, we are going to make the skill feel concrete enough to practice.

      +

      Jamie: And I am Jamie. I will keep asking what the learner should do, what evidence counts, and how to recover if the page does something unexpected.

      -

      Alex: Today we are working on this: Workflow YAML structure, CI/CD, automation, and the Actions marketplace. I want the learner to leave with a mental map, not just a remembered path through buttons.

      -

      Jamie: So the goal is understanding first, then action, then confirmation.

      -

      Alex: Right. We are building a rhythm: orient yourself, take one intentional action, then verify what changed before moving on.

      +

      Alex: The skill focus is Notification hygiene, mentions, subscriptions, and avoiding overload. This is rehearsal for real contribution, so the evidence matters because it proves the move happened.

      +

      Jamie: So the challenge has to leave the learner with both confidence and a trail of evidence.

      +

      Alex: Exactly. Evidence is not busywork. It is how a learner, a facilitator, and a future maintainer can understand what changed and why.

      Jamie: Okay, set the room for us. What are we walking into?

      -

      Alex: Start with Understanding Automation in Open Source Repositories: Why this matters for you: Every time you open a pull request on a real open source project, automated processes will run. The next useful detail is this: Understanding what they are, what they mean, and what to do when they fail is essential to being a confident contributor.

      -

      Alex: The next layer is this. Here is the plain-English version of 1. What Is GitHub Actions? GitHub Actions is GitHub's built-in automation system. Put another way, it lets repository maintainers define automated tasks that run in response to things that happen in the repository - like someone opening a pull request, pushing a commit, or filing an issue. It is like learning a transit route. The names of the stops matter because they tell you whether you are still going the right direction.

      -

      Jamie: What is the one idea that makes the next few steps less mysterious?

      -

      Alex: Start with Learning Cards: What Is GitHub Actions. There is something to understand, something to try, and something that proves the try worked.

      -

      Alex: That shows up in the workshop in a few specific ways. Workflow files live in.github/workflows/ -- use T (Go to file) on any repo page to search for.yml files in that directory. The Actions tab is in the repository navigation landmark -- press D (NVDA/JAWS) to jump between landmarks and find it. You do not need to write YAML to contribute -- your job is to read the status check results on your PR and fix any issues they flag. The Actions tab icon (a play-button triangle) sits in the repo's top navigation bar -- zoom in if the icon-only display is hard to read; the word "Actions" appears next to it. Workflow YAML files use indentation-sensitive syntax -- increase your editor font size and enable visible whitespace to distinguish nesting levels. Status check results on your PR use small colored icons (green checkmark, red X, yellow spinner) -- zoom to 150%+ to read the text labels beside them.

      +

      Alex: Start with Bonus D: Notification Mastery: For students who: Want to practice inbox management and notification configuration. The next useful detail is this: What you will do: Configure your GitHub notification settings for a productive workflow, then demonstrate your setup.

      +

      Alex: A solid project habit is to treat metadata as decision support. Labels, status, assignees, and notifications tell you what kind of attention the work needs.

      +

      Alex: The next layer is this. Here is the plain-English version of Notification configuration checklist. Go to github.com/settings/notifications and configure. It is like learning a transit route. The names of the stops matter because they tell you whether you are still going the right direction.

      +

      Alex: The practical anchors are these. [ ] Email notifications: Choose which events trigger emails. [ ] Web notifications: Configure the notification inbox on GitHub.com. [ ] Watching: Review which repositories you are watching and adjust. [ ] Custom routing: If you have multiple email addresses, set up routing rules. [ ] GitHub Mobile: If you use the mobile app, configure push notification preferences.

      +

      Jamie: What does the learner do first, second, and then after that?

      +

      Alex: This is where Demonstrate your setup becomes real: after configuring, answer these questions. That matters in practice: I am watching repositories because.

      +

      Alex: First, how will you know when someone requests your review? Then, how will you avoid being overwhelmed by notifications from busy repositories? After that, what is your strategy for the GitHub notification inbox (read all, triage, filter)? It is a checklist, but a meaningful one: every item creates evidence that the next step is safe.

      -

      Alex: Now bring the learner back to the room. Keep the learner anchored in 3. Where Workflows Live in a Repository. Workflow files live in a specific, mandatory location.

      +

      Alex: Now bring the learner back to the room. Keep the learner anchored in Before: Default settings. With default settings, GitHub sends email notifications. This is the part to say slowly: Most people start ignoring all GitHub emails.

      +

      Alex: For a learner, the useful signals are these. Every issue and PR in every repository you watch. Every comment on any thread you have participated in. Every CI status update.

      Jamie: What would you say to someone who is already bracing for this to be too much?

      -

      Alex: The reason Description matters is that workflow files live at your-repository/.github/workflows/. That gives the learner a simple foothold: example files include: ci.yml (runs tests on every push or PR), lint.yml (checks code style), a11y-scan.yml (accessibility scanning), and deploy.yml (deploys the site when code merges to main).

      -

      Alex: The parts worth keeping in working memory are these. On GitHub.com: The file browser shows it - use T (go to file) or navigate the file table with Ctrl+Alt+Arrow keys. In VS Code: It appears in the Explorer panel - enable "Show Hidden Files" if needed.

      +

      Alex: Start with Notification settings (github.com/settings/notifications). There is something to understand, something to try, and something that proves the try worked.

      +

      Alex: The parts worth keeping in working memory are these. Participating: Email ON, Web ON -- you want to know when someone replies to your conversations. Watching: Email OFF, Web ON -- browse these when you have time, not in your inbox. GitHub Actions: Email OFF for successful runs, Email ON for failed runs only.

      +

      Alex: That matters because of the next idea. Start with Repository watching. There is something to understand, something to try, and something that proves the try worked.

      +

      Alex: On the ground, that means a few things. Repositories you actively contribute to: Watch (all activity). Repositories you read occasionally: Custom (issues and PRs only). Repositories you finished with: Unwatch.

      Alex: The useful habit is simple: orient first, act second, verify third. That pause before acting is part of the work.

      -

      Jamie: How do you keep commands from becoming magic words?

      -

      Alex: Start with 4. The Anatomy of a Workflow File: Here is a simple, real workflow file. The next useful detail is this: You do not need to write this, but you should be able to read it. Think of it like entering a new building: first you find the lobby, then the room, then the door you actually need.

      -

      Alex: Treat examples as spoken recipes, not decorations. You may hear something like.github/workflows/ci.yml; name: CI The display name shown in the Actions tab; on: What triggers this workflow; push:; branches: [main] Run when code is pushed to main; pull request: Run when a PR is opened or updated; branches: [main]; jobs:; test: The job. Read the command, understand what it changes, then run it only when the repository state matches the lesson.

      Jamie: If I am listening before the workshop starts, what should settle in my mind first?

      -

      Alex: Here is the plain-English version of 5. What Triggers a Workflow. The most common triggers you will encounter as a contributor. Put another way, the most important one for you: pull request - this is what triggers checks on your PR.

      -

      Alex: This is where the talk moves from concept to action. This is where 6. Understanding Status Checks on Pull Requests becomes real: when you open a pull request on a repo that uses GitHub Actions, you will see a section near the bottom of the Conversation tab called checks or status checks.

      -

      Alex: A solid pull request habit is to separate three questions: what changed, why it changed, and what still needs review. That keeps the conversation useful instead of noisy.

      -

      Jamie: Turn that into a path someone can follow.

      -

      Alex: Start with NVDA / JAWS (browse mode). There is something to understand, something to try, and something that proves the try worked.

      -

      Alex: First, open the pull request Conversation tab. Then, navigate to the section heading for "checks" using H or 2. After that, each check result is announced as a link or button with its name and status. Finally, press Enter on a failed check to expand its details. It is like walking a hallway with named doors: read the sign, enter the right room, then confirm where you landed.

      +

      Alex: Start with Custom routing (if you use multiple emails). There is something to understand, something to try, and something that proves the try worked.

      +

      Alex: Here is what that changes in practice. Route Community-Access organization notifications to your workshop email. Route personal project notifications to your personal email.

      +

      Alex: This is where the talk moves from concept to action. Start with Key decisions explained. There is something to understand, something to try, and something that proves the try worked.

      +

      Alex: The room should hear these as checkpoints. Why email off for watching: You can check the notification bell on github.com when you choose. Email notifications for watched repos create constant interruption for low-priority updates. Why Actions failures only: A green checkmark in the PR is enough. You only need an email when something breaks. Why unwatch finished repos: Your notification feed stays relevant to current work.

      +

      Jamie: What is the one idea that makes the next few steps less mysterious?

      +

      Alex: Keep the learner anchored in What matters. The learning objective is intentional notification management. This is the part to say slowly: If you changed at least one setting from the default and can explain why that change reduces noise while keeping you informed about what matters, you completed this bonus.

      -

      Jamie: What is the ordered workflow?

      -

      Alex: Start with VoiceOver (macOS, Safari). There is something to understand, something to try, and something that proves the try worked.

      -

      Alex: First, use VO+U to open the Rotor. Then, select "Headings" and navigate to the checks section. After that, use VO+Arrow to read through check results. Finally, activate a check link with VO+Space. The rhythm is simple: orient, act, verify, then continue.

      -

      Jamie: Give me the version that sounds like an instructor, not a manual.

      -

      Alex: Start with Required vs. non-required checks. There is something to understand, something to try, and something that proves the try worked.

      -

      Alex: A few details make that real. Required checks must pass before a PR can be merged. A maintainer configures which checks are required in Branch Protection Rules. Non-required checks are informational - a failure shown in grey/yellow usually won't block a merge. If you're not sure whether a check is required, look for the phrase "Required" next to the check name.

      -

      Alex: Hold that next to this. Start with Learning Cards: Understanding Status Checks. There is something to understand, something to try, and something that proves the try worked.

      -

      Alex: The practical anchors are these. Status checks live near the bottom of the PR Conversation tab -- press H or 2 to jump to the checks section heading, then arrow down through each result. Each check is announced with its name and status ("CI / test -- passed" or "lint -- failed") -- press Enter on a failing check to open its details. The word "Required" appears after required checks -- listen for it to distinguish must-pass checks from informational ones. Status icons use green (passed), red (failed), yellow (running), and grey (skipped) -- each icon also has a text label, so color is not the only indicator. At high zoom levels, the checks section may appear below the fold -- scroll past the PR description and comments to find it above the merge button. Click "Details" next to any check to open the full log -- the log page uses monospace text, so increase font size for readability.

      +

      Alex: Before the learner moves on. The reason Managing Your GitHub Notification Inbox matters is that see also: Appendix V: GitHub Mobile for managing notifications on your phone. That gives the learner a simple foothold: GitHub notifications are how GitHub tells you when something needs your attention. The interface gets friendlier when it stops being a wall of controls and starts being a set of named places.

      +

      Jamie: How should they picture the shape of the workshop?

      +

      Alex: Start with Workshop Recommendation (Chapter 10): For this workshop, Chapter 10 is a guided practice chapter, not a graded automation chapter.

      +

      Alex: A few details make that real. There are 1 guided walkthrough. Automation check: none - notification settings are account-level and cannot be validated by the Learning Room PR bot. The evidence is structured completion comment on your assigned challenge issue. The pattern is configure, filter, act.

      +

      Jamie: How would you walk the room through that step by step?

      +

      Alex: Start with Chapter 10 Challenge Set. There is something to understand, something to try, and something that proves the try worked.

      +

      Alex: First, configure notifications and practice inbox management - set your watch level, use filters to find relevant notifications, and perform one inbox action. Treat it like a recipe: do not add the next ingredient until the previous one is actually in the bowl.

      +

      Jamie: Turn that into a path someone can follow.

      +

      Alex: This is where Challenge 10.1 Step-by-Step: Notification Inbox Walkthrough becomes real: set up a useful notification workflow so you can keep up with reviews, mentions, and assignments without inbox overload. That matters in practice: the GitHub.com notifications page and your Learning Room repository settings.

      +

      Alex: That shows up in the workshop in a few specific ways. Press M to mute the thread (you will not receive future updates),. Press E to mark done (removes it from inbox but you can still get future updates).

      +

      Alex: First, open your Learning Room repository on GitHub.com. Then, find the Watch button near the top-right of the repository page (next to Star and Fork). After that, 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. Finally, open the notifications inbox by navigating to https://github.com/notifications (or activate the bell icon in the GitHub header). It is a checklist, but a meaningful one: every item creates evidence that the next step is safe.

      +

      Jamie: What is the ordered workflow?

      +

      Alex: First, in the notification filters, activate the Review requested filter. This shows only notifications where someone has asked you to review their PR. Then, clear that filter and activate the Assigned filter. This shows notifications for issues and PRs assigned to you. After that, open one notification by activating its title link. Read it briefly, then navigate back to the inbox. Finally, perform one inbox action on a non-critical notification thread. It is like walking a hallway with named doors: read the sign, enter the right room, then confirm where you landed.

      +

      Alex: That connects to another useful point. Keep the learner anchored in Completing Chapter 10: Submit Your Evidence. Open your assigned Chapter 10 challenge issue and post a completion comment. This is the part to say slowly: Close your Chapter 10 challenge issue when done. A good GitHub workflow is like a well-run meeting: everyone knows the topic, the next action, and who has the floor.

      Jamie: Where do you want a learner to place their attention here?

      -

      Alex: This is where 7. Reading the Actions Tab with a Screen Reader becomes real: the Actions tab of a repository shows the history of all workflow runs. That matters in practice: You can use it to see what ran, what failed, and why.

      -

      Alex: A solid navigation habit is to prove where you are before activating controls. Headings, landmarks, and the address bar are not trivia; they are your map.

      +

      Alex: Start with Expected Outcomes. There is something to understand, something to try, and something that proves the try worked.

      +

      Alex: These are the details that keep the idea from floating away. 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.

      +

      Jamie: Give me the sequence, because order matters here.

      -

      Alex: Start with Getting to the Actions tab. There is something to understand, something to try, and something that proves the try worked.

      -

      Alex: First, open the repository. Then, navigate to the "Repository navigation" landmark (D on NVDA/JAWS). After that, find the "Actions" tab link and activate it (Enter). It is like walking a hallway with named doors: read the sign, enter the right room, then confirm where you landed.

      -

      Jamie: What is the safe way to learn from that example?

      -

      Alex: Start with Navigating workflow runs (NVDA/JAWS browse mode). There is something to understand, something to try, and something that proves the try worked.

      -

      Alex: Treat examples as spoken recipes, not decorations. You may hear something like Key Action; H Jump between section headings; 3 Jump between workflow run headings (they are h3); Tab Move between interactive elements (links, buttons); Enter Open a workflow run to see details. Read the command, understand what it changes, then run it only when the repository state matches the lesson.

      +

      Alex: Start with If You Get Stuck. There is something to understand, something to try, and something that proves the try worked.

      +

      Alex: First, can't find the Watch button? It is near the top-right of the repository page, in the same row as Star and Fork. Then, 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. After that, 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. Finally, filters not showing results? Clear all filters first (click the X next to each active filter), then apply one filter at a time. Think of it as a rail line: each stop confirms you are still on the right route before the next one.

      +

      Jamie: Let's pause on If You Get Stuck. What should a learner take away from it?

      +

      Alex: First, ask facilitator to model one inbox action live, then repeat the steps yourself. Then, finished but not sure you did it right? Compare your work against the Challenge 9 reference solution. Treat it like a recipe: do not add the next ingredient until the previous one is actually in the bowl.

      +

      Jamie: Give me the version that sounds like an instructor, not a manual.

      +

      Alex: Here is the plain-English version of Learning Moment. Notification management protects focus. Put another way, you can stay responsive to your team without drowning in updates.

      +

      Jamie: Let's pause on Learning Pattern Used in This Chapter. What should a learner take away from it?

      +

      Alex: Start with Learning Pattern Used in This Chapter. There is something to understand, something to try, and something that proves the try worked.

      +

      Alex: First, configure settings proactively (watch level) before work generates noise. Then, use filters to find signal in noise (review requests, assignments). After that, take decisive action on each notification (mute, done, or respond). Finally, build a daily routine that keeps your inbox manageable. It is a checklist, but a meaningful one: every item creates evidence that the next step is safe.

      -

      Jamie: How would you walk the room through that step by step?

      -

      Alex: Start with Reading a run's details: When you open a workflow run, you see. The next useful detail is this: Use your screen reader's search (NVDA+Ctrl+F, JAWS: Insert+F, VO+F) to search for "error" or "failed" to jump directly to the problem.

      -

      Alex: On the ground, that means a few things. Job names listed on the left (or in a sidebar). Steps listed within each job. Green checkmarks (passed) or red X marks (failed) next to each step.

      -

      Alex: First, navigate to the failed step. Then, activate it to expand the log output. After that, the log is a large text area - switch to focus mode to read it. Finally, look for lines containing Error:, FAILED, exit code, or AssertionError. Think of it as a rail line: each stop confirms you are still on the right route before the next one.

      -

      Jamie: Let's pause on 8. Common Workflows You Will Encounter. What should a learner take away from it?

      -

      Alex: Here is the plain-English version of 8. Common Workflows You Will Encounter. As you contribute to open source repositories, you will see these types of workflows regularly.

      -

      Alex: Keep the thread going. This is where Continuous Integration (CI) becomes real: what it does: Runs the project's test suite automatically every time code changes. That matters in practice: What you see: A check called "CI", "Tests", "Build", or similar. The workshop is closer to rehearsal than lecture. You hear the move, try the move, and then check what changed.

      +

      Jamie: Let's pause on What Generates a Notification? What should a learner take away from it?

      +

      Alex: Keep the learner anchored in What Generates a Notification? GitHub sends you a notification when.

      +

      Alex: Another way to ground it. The reason Notification Subscription Levels matters is that for each repository, you choose how many notifications to receive.

      +

      Jamie: Let's pause on Changing your watch settings for a repo. What should a learner take away from it?

      +

      Alex: Start with Changing your watch settings for a repo: At the top of any repository page, find the Watch button (near Star and Fork). The next useful detail is this: Click it to open a dropdown with levels: Participating and @mentions, All Activity, Custom, and Ignore.

      +

      Alex: First, find the Watch button in the repo header (B to navigate buttons → find "Watch [N]" or "Unwatch" button). Then, press Enter to open the dropdown. After that, press ↑/↓ to navigate the subscription options. Finally, press Enter to select your preferred level. Think of it as a rail line: each stop confirms you are still on the right route before the next one.

      +

      Jamie: Before we leave Changing your watch settings for a repo, what is the practical point?

      +

      Alex: First, the button label updates to confirm your choice. Then, quick Nav B to find the Watch button in the repo header (listen for "Watch" or "Unwatch"). After that, vO+Space to open the dropdown. Finally, vO+Down or arrow keys to navigate subscription options. Treat it like a recipe: do not add the next ingredient until the previous one is actually in the bowl.

      -

      Jamie: Let's pause on Linting / Code Style. What should a learner take away from it?

      -

      Alex: Keep the learner anchored in Linting / Code Style. What it does: Checks that code follows the project's formatting and style rules - things like indentation, line length, or consistent import ordering. This is the part to say slowly: What you see: A check called "Lint", "ESLint", "Prettier", "Flake8", or similar.

      -

      Alex: Another way to ground it. The reason Spelling / Documentation Checks matters is that what it does: Checks documentation files for spelling errors, broken links, or formatting issues. That gives the learner a simple foothold: what you see: A check called "Spell Check", "markdownlint", "Link Check", or similar.

      -

      Jamie: Let's pause on Accessibility Scanning. What should a learner take away from it?

      -

      Alex: Start with Accessibility Scanning: What it does: Runs automated accessibility checks against HTML output or component libraries to catch WCAG violations. The next useful detail is this: What you see: A check called "a11y", "Accessibility", "axe", "pa11y", or similar.

      +

      Jamie: Let's pause on Tool Cards: Manage Notifications. What should a learner take away from it?

      +

      Alex: Here is the plain-English version of Tool Cards: Manage Notifications. VS Code Desktop (GitHub Pull Requests extension). Put another way, GitHub Desktop: GitHub Desktop does not manage notifications. It is like learning a transit route. The names of the stops matter because they tell you whether you are still going the right direction.

      +

      Alex: First, go to github.com/notifications (or press G then N). Then, use E to mark done, I to mark read/unread, Shift+M to mute a thread. After that, the Notifications view in the GitHub sidebar shows items needing attention. Finally, click a notification to open the related issue or PR directly in VS Code. Treat it like a recipe: do not add the next ingredient until the previous one is actually in the bowl.

      +

      Alex: Treat examples as spoken recipes, not decorations. You may hear something like 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. 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. Read the command, understand what it changes, then run it only when the repository state matches the lesson.

      +

      Jamie: Let's pause on Navigating the notification list. What should a learner take away from it?

      +

      Alex: This is where Navigating the notification list becomes real: the inbox shows notifications grouped by date (Today, Yesterday, This week, Older). That matters in practice: Each row shows the repository, the issue or PR title, the event type, and the time.

      +

      Alex: First, d → main content landmark. Then, h to navigate group headings (Today / Yesterday / This week / Older). After that, tab through individual notifications - each row announces: repo name, issue/PR title, event type, time. Finally, enter to open the notification (goes to the issue/PR page). It is a checklist, but a meaningful one: every item creates evidence that the next step is safe.

      +

      Jamie: Before we leave Navigating the notification list, what is the practical point?

      +

      Alex: First, vO+U → Main → navigate to notification list. Then, vO+Down to move through notifications. After that, vO+Space to open a notification. It is like walking a hallway with named doors: read the sign, enter the right room, then confirm where you landed.

      +

      Alex: Here is the practical turn. Keep the learner anchored in What is announced per notification. "microsoft/vscode - Add keyboard shortcut for accessible view - @username mentioned you - 2 hours ago". This is the part to say slowly: Components: repo/org thread title event type timestamp.

      -

      Alex: This is the part worth saying out loud. Here is the plain-English version of Security Scanning. What it does: Scans for known vulnerabilities in dependencies or exposed secrets. Put another way, what you see: A check called "CodeQL", "Dependabot", "Snyk", or similar. It is like learning a transit route. The names of the stops matter because they tell you whether you are still going the right direction.

      -

      Jamie: Let's pause on Deployment / Preview Builds. What should a learner take away from it?

      -

      Alex: This is where Deployment / Preview Builds becomes real: what it does: Builds and deploys a preview version of a website or app from your PR branch. That matters in practice: What you see: A bot comment on your PR with a preview URL, and a check called "Deploy", "Netlify", "Vercel", "GitHub Pages", or similar.

      -

      Alex: That connects to another useful point. Keep the learner anchored in Step 1: Don't panic. A failing check is information, not a judgment. This is the part to say slowly: It is the system telling you something specific needs attention.

      +

      Jamie: Let's pause on Learning Cards: The Notifications Inbox. What should a learner take away from it?

      +

      Alex: Start with Learning Cards: The Notifications Inbox. There is something to understand, something to try, and something that proves the try worked.

      +

      Alex: That becomes easier when you listen for these cues. 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. 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.

      +

      Alex: Keep the thread going. Start with Inbox Actions - Keyboard Shortcuts: These shortcuts work when a notification is focused in the inbox. The next useful detail is this: These are GitHub's own keyboard shortcuts. Think of it like entering a new building: first you find the lobby, then the room, then the door you actually need.

      +

      Alex: A solid navigation habit is to prove where you are before activating controls. Headings, landmarks, and the address bar are not trivia; they are your map.

      +

      Jamie: Let's pause on Filtering the Inbox. What should a learner take away from it?

      +

      Alex: Here is the plain-English version of Filtering the Inbox. The left sidebar has quick filters.

      -

      Jamie: What does the learner do first, second, and then after that?

      -

      Alex: Start with Step 2: Navigate to the failed check. There is something to understand, something to try, and something that proves the try worked.

      -

      Alex: First, scroll down to the checks section (press D to reach the "Checks" region if using a screen reader). Then, find the failing check (red X). After that, press Enter on "Details" (or the check name itself) to open the workflow run. The rhythm is simple: orient, act, verify, then continue.

      -

      Jamie: Let's pause on Step 3: Find the failing step. What should a learner take away from it?

      -

      Alex: Start with Step 3: Find the failing step. There is something to understand, something to try, and something that proves the try worked.

      -

      Alex: First, look for the step with the red X marker. Then, press Enter or Space to expand the log output. Think of it as a rail line: each stop confirms you are still on the right route before the next one.

      -

      Jamie: Let's pause on Step 4: Read the error message. What should a learner take away from it?

      -

      Alex: Start with Step 4: Read the error message. There is something to understand, something to try, and something that proves the try worked.

      -

      Alex: Here is what that changes in practice. Error: - describes what went wrong. FAILED or FAIL - test failure summary. File name and line number - where exactly the problem is. exit code 1 (or non-zero) - the command failed.

      +

      Jamie: Let's pause on Filtering by repository or organization. What should a learner take away from it?

      +

      Alex: This is where Filtering by repository or organization becomes real: at the top of the notification list there is a filter/search field. That matters in practice: Click the filter/search box at the top of the notification list and type a repository or organization name.

      +

      Alex: First, press F or E to reach the filter input. Then, focus Mode → type repo name or org name. After that, results filter in real time. Finally, press Esc to clear the filter. It is a checklist, but a meaningful one: every item creates evidence that the next step is safe.

      +

      Jamie: Before we leave Filtering by repository or organization, what is the practical point?

      +

      Alex: First, quick Nav F to reach the filter input. Then, vO+Shift+Down to interact → type repo or org name. After that, press Esc to clear the filter and VO+Shift+Up to stop interacting. It is like walking a hallway with named doors: read the sign, enter the right room, then confirm where you landed.

      +

      Jamie: Let's pause on The "mark all as done" workflow. What should a learner take away from it?

      +

      Alex: Keep the learner anchored in The "mark all as done" workflow. After a busy day or coming back from time away, clear your inbox methodically.

      +

      Alex: First, open Notifications inbox. Then, tab to "Mark all as done" button → Enter (clears everything at once). After that, then use the "Done" filter to retrieve any you want to revisit. It is like walking a hallway with named doors: read the sign, enter the right room, then confirm where you landed.

      +

      Jamie: Let's pause on Muting a noisy thread. What should a learner take away from it?

      +

      Alex: The reason Muting a noisy thread matters is that if a thread generates too many notifications. That gives the learner a simple foothold: screen reader users (NVDA / JAWS - Windows). The interface gets friendlier when it stops being a wall of controls and starts being a set of named places.

      +

      Alex: First, open the issue or PR page. Then, in the right sidebar, scroll to the Notifications section. After that, click Unsubscribe - you will stop receiving notifications from this thread. Finally, alternatively, from the inbox: hover over the notification row and click the mute icon (or the … menu). The rhythm is simple: orient, act, verify, then continue.

      +

      Jamie: Before we leave Muting a noisy thread, what is the practical point?

      +

      Alex: First, open the notification. Then, on the issue/PR page, navigate the sidebar to the Notifications section (H or D). After that, activate the Unsubscribe button. Finally, or from the inbox: focus the notification → press M to mute. Think of it as a rail line: each stop confirms you are still on the right route before the next one.

      -

      Alex: That matters because of the next idea. Start with Step 5: Fix the issue locally (or in the web editor). There is something to understand, something to try, and something that proves the try worked.

      -

      Alex: The room should hear these as checkpoints. Test failure: Understand what the test expects and whether your change broke something intentional. Lint failure: Run the project's format/lint command, or manually fix the flagged lines. Spell check failure: Fix the typo noted in the log. Accessibility failure: Fix the specific a11y violation described (missing alt text, contrast issue, etc.).

      -

      Alex: A solid issue habit is to read the title, the body, and the timeline before acting. You are listening for the requested action, the missing evidence, and the person who needs a response.

      -

      Jamie: Let's pause on Step 6: Commit and push the fix. What should a learner take away from it?

      -

      Alex: Start with Step 6: Commit and push the fix. There is something to understand, something to try, and something that proves the try worked.

      -

      Alex: These are the details that keep the idea from floating away. The workflow will automatically re-run when you push new commits to the branch. No need to close and re-open the PR.

      -

      Alex: A solid Git habit is to know which branch you are on, what changed, and what confirmation you expect before you run the next command.

      -

      Alex: Before the learner moves on. The reason Step 7: If you're stuck matters is that it is completely acceptable to comment on your PR. That gives the learner a simple foothold: "The CI check is failing on [step name]. The interface gets friendlier when it stops being a wall of controls and starts being a set of named places.

      +

      Jamie: Let's pause on Dealing with @mentions you didn't expect. What should a learner take away from it?

      +

      Alex: Start with Dealing with @mentions you didn't expect: If you were @mentioned in an unfamiliar thread.

      +

      Alex: First, read the thread for context before responding. Then, 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. After that, unsubscribe after reading if you don't need to stay in the loop. Think of it as a rail line: each stop confirms you are still on the right route before the next one.

      +

      Alex: This is the part worth saying out loud. Start with Learning Cards: Managing Notifications at Scale. There is something to understand, something to try, and something that proves the try worked.

      +

      Alex: The practical takeaway is this. 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. 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.

      +

      Jamie: Let's pause on Notification Settings - Per Your Account. What should a learner take away from it?

      +

      Alex: This is where Notification Settings - Per Your Account becomes real: global notification preferences are at https://github.com/settings/notifications.

      -

      Jamie: Let's pause on Learning Cards: What To Do When a Check Fails. What should a learner take away from it?

      -

      Alex: Start with Learning Cards: What To Do When a Check Fails. There is something to understand, something to try, and something that proves the try worked.

      -

      Alex: For a learner, the useful signals are these. From the failing check's Details link, the log page has a sidebar listing job steps -- the failed step has focus or is announced as "failed"; expand it to read the error. Use your screen reader's find command (NVDA+Ctrl+F, JAWS: Insert+F) to search the log for "Error:" or "FAILED" -- this skips hundreds of passing log lines. After pushing a fix, return to the PR page -- checks re-run automatically and the status updates from red X to yellow spinner to green checkmark. CI log pages can be very long with small monospace text -- use Ctrl+F in your browser to search for "Error" or "FAIL" rather than scrolling through everything. The failing step is marked with a red X icon in the left sidebar of the log page -- zoom in to identify it, then click to expand only that step. If you cannot read the log comfortably, copy the error text and paste it into your editor at a larger font size.

      -

      Alex: Here is the practical turn. Here is the plain-English version of Why some workflows need your approval. If you are contributing to a repository for the first time, GitHub may hold your workflow runs for approval. Put another way, "Workflows aren't being run on this pull request.

      -

      Jamie: Let's pause on What you should never do. What should a learner take away from it?

      -

      Alex: Start with What you should never do. There is something to understand, something to try, and something that proves the try worked.

      -

      Alex: That becomes easier when you listen for these cues. Never change workflow files to bypass checks (e.g., deleting tests to make them pass). Never add secrets or credentials to workflow files or code. Never approve a workflow run on someone else's PR unless you have reviewed the code.

      +

      Alex: Hold that next to this. Keep the learner anchored in Starring vs. Watching - What Is the Difference? New contributors often confuse these two. This is the part to say slowly: They appear next to each other on every repository page and do completely different things. A good GitHub workflow is like a well-run meeting: everyone knows the topic, the next action, and who has the floor.

      +

      Alex: A solid pull request habit is to separate three questions: what changed, why it changed, and what still needs review. That keeps the conversation useful instead of noisy.

      +

      Jamie: Let's pause on Starring a Repository. What should a learner take away from it?

      +

      Alex: The reason Starring a Repository matters is that starring is GitHub's equivalent of a bookmark + public endorsement. That gives the learner a simple foothold: the star count on a repository is a community signal of popularity.

      +

      Alex: Keep the teaching thread moving. Start with 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. The next useful detail is this: 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.

      -

      Alex: Keep the teaching thread moving. Keep the learner anchored in Dependabot. Dependabot is an automated bot built into GitHub that creates pull requests to update outdated or vulnerable dependencies. This is the part to say slowly: the learner will see PRs in a repository from a user called dependabot[bot]. A good GitHub workflow is like a well-run meeting: everyone knows the topic, the next action, and who has the floor.

      -

      Jamie: Let's pause on 11. Accessibility-Focused Workflows. What should a learner take away from it?

      -

      Alex: The reason 11. Accessibility-Focused Workflows matters is that this is relevant to our event specifically. That gives the learner a simple foothold: the open source accessibility community actively uses GitHub Actions to automatically catch accessibility regressions - meaning, to ensure that new code does not introduce new accessibility barriers.

      -

      Alex: Keep the teaching thread moving. Start with GitHub's Accessibility Scanner Action: GitHub itself has open-sourced an AI-powered Accessibility Scanner that can be added to a repository. The next useful detail is this: It uses AI to find, file, and help fix accessibility bugs using GitHub Copilot.

      +

      Jamie: Let's pause on How to silence a repository you accidentally over-subscribed to. What should a learner take away from it?

      +

      Alex: Here is the plain-English version of How to silence a repository you accidentally over-subscribed to. This immediately reduces notifications from that repository to only threads you personally participated in.

      +

      Alex: Keep the teaching thread moving. Start with Learning Cards: Starring vs. Watching. There is something to understand, something to try, and something that proves the try worked.

      +

      Alex: The practical takeaway is this. 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. 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.

      +

      Jamie: Let's pause on NVDA. What should a learner take away from it?

      +

      Alex: Start with NVDA. There is something to understand, something to try, and something that proves the try worked.

      +

      Alex: The practical takeaway is this. 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.

      -

      Jamie: There are a lot of tools in play. How do we keep that from feeling like a contest?

      -

      Alex: Here is the plain-English version of What these tools catch (and what they do not). Automated tools catch approximately 30-40% of accessibility issues - things like missing alt attributes, insufficient color contrast ratios, or unlabeled form fields. Put another way, the remaining issues require human testing, especially with actual assistive technology like your screen reader.

      -

      Alex: Keep the teaching thread moving. This is where Preparing the Environment for GitHub-Hosted Agents becomes real: when custom agents run on GitHub.com - triggered by an issue assignment or a Copilot Chat task - they need any external tools pre-installed before they start working. That matters in practice: GitHub recognizes a special setup workflow for this: a workflow file with a single job named copilot-setup-steps. The workshop is closer to rehearsal than lecture. You hear the move, try the move, and then check what changed.

      -

      Jamie: Let's pause on Activity: Explore a Workflow in This Repository. What should a learner take away from it?

      -

      Alex: Keep the learner anchored in Activity: Explore a Workflow in This Repository. Practice navigating the Actions tab and reading a workflow file using your screen reader.

      +

      Alex: Keep the teaching thread moving. Start with JAWS. There is something to understand, something to try, and something that proves the try worked.

      +

      Alex: The practical takeaway is this. 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.

      +

      Jamie: Let's pause on VoiceOver. What should a learner take away from it?

      +

      Alex: Start with VoiceOver. There is something to understand, something to try, and something that proves the try worked.

      +

      Alex: The practical takeaway is this. 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.

      +

      Alex: Keep the teaching thread moving. Here is the plain-English version of The GitHub Mobile App - A Reference Note. GitHub has an iOS and Android app that supports push notifications. Put another way, while the app itself is not covered as a primary tool in this workshop, it is worth knowing. It is like learning a transit route. The names of the stops matter because they tell you whether you are still going the right direction.

      +

      Alex: The practical takeaway is this. 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.

      -

      Jamie: Let's pause on Steps. What should a learner take away from it?

      -

      Alex: Start with Steps. There is something to understand, something to try, and something that proves the try worked.

      -

      Alex: The practical takeaway is this. What event triggers it. What OS it runs on. How many steps it has. What the last step does.

      -

      Alex: First, navigate to your Learning Room repository on GitHub. Then, go to the Actions tab (in the Repository navigation landmark). After that, use 3 (NVDA/JAWS) or the Headings rotor (VoiceOver) to navigate the list of workflow runs. Finally, open the most recent run. The rhythm is simple: orient, act, verify, then continue.

      -

      Jamie: Before we leave Steps, what is the practical point?

      -

      Alex: First, find any failed step and expand its log. Then, navigate to the.github/workflows/ folder via the Code tab. After that, open a workflow.yml file. Finally, read through the file and identify. Think of it as a rail line: each stop confirms you are still on the right route before the next one.

      -

      Jamie: Let's pause on Discussion questions. What should a learner take away from it?

      -

      Alex: Start with Discussion questions. There is something to understand, something to try, and something that proves the try worked.

      -

      Alex: The practical takeaway is this. What would happen if you opened a PR and the "Accessibility Scan" check failed? Where would you look to find out what accessibility violation was detected? If you disagreed with a failing lint check, what would be the appropriate way to raise that with a maintainer?

      -

      Alex: Keep the teaching thread moving. Here is the plain-English version of 13. What We Are NOT Covering (And Where to Learn More). This workshop covers what you need as a contributor. Put another way, we are intentionally not diving into. It is like learning a transit route. The names of the stops matter because they tell you whether you are still going the right direction.

      -

      Alex: The practical takeaway is this. Writing workflow files from scratch. Setting up self-hosted runners. Creating custom Actions. Advanced workflow patterns (matrix builds, reusable workflows, environments).

      +

      Jamie: Let's pause on Try It: Tame Your Inbox. What should a learner take away from it?

      +

      Alex: This is where Try It: Tame Your Inbox becomes real: time: 2 minutes What you need: Browser, signed in to GitHub. That matters in practice: Go to github.com/notifications and practice.

      +

      Alex: First, scan your inbox - Press H and Tab to navigate through notifications. Each one shows the repo name, type (issue/PR), and title. Then, mark one as done - Find a notification you've already read. Press E to mark it as done. It disappears from the list. After that, 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. It is a checklist, but a meaningful one: every item creates evidence that the next step is safe.

      +

      Alex: Keep the teaching thread moving. Keep the learner anchored in What You Accomplished Today. Day 1 is complete -- and you did a lot. This is the part to say slowly: Here is every skill you practiced, mapped to the chapter where you learned it and the evidence you created along the way.

      +

      Jamie: Let's pause on If This Was Your First Time. What should a learner take away from it?

      +

      Alex: The reason If This Was Your First Time matters is that 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. That gives the learner a simple foothold: you navigated a complex platform, created real contributions, and collaborated with other people in a shared codebase.

      -

      Jamie: Let's pause on Summary. What should a learner take away from it?

      -

      Alex: This is where Summary becomes real: day 2 Bridge - From Actions to Agentic Workflows Understand standard YAML workflow files before engaging with agentic workflows. That matters in practice: GitHub Agentic Workflows are not a separate technology - they are the next layer on top of what you learned here.

      +

      Jamie: Let's pause on Confidence Check. What should a learner take away from it?

      +

      Alex: Start with Confidence Check: Before you close your laptop, take two minutes to answer these questions in your Chapter 10 challenge issue. The next useful detail is this: There are no wrong answers -- this is for you. Think of it like entering a new building: first you find the lobby, then the room, then the door you actually need.

      +

      Alex: First, which chapter felt the most natural to you? Which one do you want to revisit? Then, can you explain what a pull request does to someone who has never used GitHub? After that, if you saw a merge conflict right now, would you know where to start? Finally, what is one thing you want to try on GitHub this week that you did not get to today? Think of it as a rail line: each stop confirms you are still on the right route before the next one.

      +

      Jamie: What should the learner prove to themselves after each small task?

      +

      Alex: Here is the plain-English version of Your Challenge Progress. Look at how many challenge issues you completed today. Put another way, each one represents a skill you did not just read about -- you practiced it, posted evidence, and moved on.

      +

      Alex: Keep the teaching thread moving. Start with Learning Cards: What You Accomplished Today. There is something to understand, something to try, and something that proves the try worked.

      +

      Alex: The practical takeaway is this. 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. 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.

      -

      Jamie: What should people carry with them after this?

      -

      Alex: Carry the map. Know what page or tool you are in, know which action you are taking, and know what confirmation should follow. If the confirmation is missing, pause. That pause is not wasted time; it is professional judgment.

      -

      Jamie: That is a better way to say it than just follow the steps.

      -

      Alex: Right. Steps matter, but understanding wins. That is episode 34. Next in the series is episode 35, where we keep building the same contributor muscles.

      +

      Jamie: Where does the workshop stop being a tour and start becoming contribution?

      +

      Alex: Keep the learner anchored in What Day 2 Adds. See also: Chapter 11: VS Code Interface is where Day 2 begins -- have VS Code installed and ready. This is the part to say slowly: On Day 1, you worked entirely on GitHub.com.

      +

      Jamie: Let's pause on Between Days. What should a learner take away from it?

      +

      Alex: The reason Between Days matters is that if your workshop has a gap between Day 1 and Day 2, here are three optional things you can do to stay sharp. That gives the learner a simple foothold: GitHub Skills courses use bot-driven feedback inside pull requests. The interface gets friendlier when it stops being a wall of controls and starts being a set of named places.

      +

      Alex: First, explore your notification settings. Now that you understand how notifications work, visit github.com/settings/notifications and customize your email and web preferences. There is no wrong configuration -- just find what feels manageable. Then, 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. After that, try a GitHub Skills course. GitHub Skills 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 for the full list of recommended courses. The rhythm is simple: orient, act, verify, then continue.

      +

      Jamie: Let's pause on You Already Know More Than You Think. What should a learner take away from it?

      +

      Alex: Start with You Already Know More Than You Think: Think about where you started this morning. The next useful detail is this: 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.

      +
      +

      Jamie: What is the final checkpoint?

      +

      Alex: You should be able to point to the evidence, explain the action, and describe what you would do next if this were a real open source project. If you can teach the move back, you have learned it.

      +

      Jamie: And if they get stuck?

      +

      Alex: Read the latest message, not the loudest worry. Check the issue, the branch, the pull request, the status check, or the bot comment. Then ask for help with those facts in hand. That is how professionals collaborate.

      -

      Episode 35: Profile, Sponsors, and Wikis

      -

      Profile README, GitHub Sponsors, and repository Wikis.

      -

      Based on: Appendix T: Profile, Sponsors, and Wikis

      -

      Audio and transcript are being regenerated for this episode.

      +

      Day 2: Local Workflow

      +

      30. Episode 11: VS Code Setup and Accessibility

      +

      Screen reader mode, Command Palette, sidebar navigation, and accessibility settings.

      +

      Based on: Chapter 11: VS Code Setup and Accessibility

      + + +

      Download Episode 11 (MP3)

      -Read Transcript - Episode 35: Profile, Sponsors, and Wikis +Read Transcript - Episode 11: VS Code Setup and Accessibility

      Transcript

      -

      Alex: Welcome to episode 35 of Git Going with GitHub: Profile, Sponsors, and Wikis. I am Alex, and today we are teaching this topic as a conversation you can carry into the workshop, not as a page you have to memorize.

      +

      Alex: Welcome to episode 11 of Git Going with GitHub: VS Code Setup and Accessibility. I am Alex, and today we are teaching this topic as a conversation you can carry into the workshop, not as a page you have to memorize.

      Jamie: And I am Jamie. I will keep pulling the lesson back to real learners, real repositories, and the evidence that proves the work happened.

      -

      Alex: The lesson focus is Profile README, GitHub Sponsors, and repository Wikis. We will treat every step as a teachable decision, because that is what makes the skill portable.

      +

      Alex: The lesson focus is Screen reader mode, Command Palette, sidebar navigation, and accessibility settings. We will treat every step as a teachable decision, because that is what makes the skill portable.

      Jamie: So we should explain the why clearly enough that the steps make sense when the learner meets them later.

      Alex: That is it. If a listener only has audio right now, they should still get the complete concept and know what evidence would prove success.

      Jamie: Okay, set the room for us. What are we walking into?

      -

      Alex: Start with Building Your Community Presence on GitHub: This appendix covers three community-facing GitHub features: your profile README (how the world sees you), GitHub Sponsors (financially supporting the people whose work you depend on), and GitHub Wikis (community-editable documentation inside a repository).

      +

      Alex: Start with 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. The next useful detail is this: 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.

      +

      Alex: The next layer is this. Here is the plain-English version of Workshop Recommendation (Chapter 11). For this workshop, Chapter 11 is a guided setup chapter with a lightweight completion practice. It is like learning a transit route. The names of the stops matter because they tell you whether you are still going the right direction.

      +

      Alex: The practical anchors are these. There are 1 guided walkthrough. Automation check: none - setup state is local/account-level and cannot be validated by the Learning Room PR bot. The evidence is structured completion comment on your assigned challenge issue. The pattern is open, configure, navigate, verify.

      +

      Jamie: What does the learner do first, second, and then after that?

      +

      Alex: Start with Chapter 11 Practice Set. There is something to understand, something to try, and something that proves the try worked.

      +

      Alex: First, 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. It is a checklist, but a meaningful one: every item creates evidence that the next step is safe.

      Alex: A solid pull request habit is to separate three questions: what changed, why it changed, and what still needs review. That keeps the conversation useful instead of noisy.

      -

      Alex: The next layer is this. Start with Learning Cards: Profiles, Sponsors, and Wikis. There is something to understand, something to try, and something that proves the try worked.

      -

      Alex: The practical anchors are these. Your profile README is announced as regular page content when someone visits your profile -- use headings for structure so visitors can navigate with H. The Sponsor button on a profile or repo is a standard button element -- press B to cycle through buttons until you hear "Sponsor". Wiki pages are read in browse mode like any other GitHub Markdown page -- use heading navigation to jump between sections. Profile READMEs respect GitHub's dark and light themes -- test yours in both modes to confirm text remains readable. The Sponsor button uses a heart icon with a pink/magenta accent -- look near the repo name or profile photo area. Wiki sidebar navigation appears on the right side of the page with links to all wiki pages.

      -

      Jamie: What is the one idea that makes the next few steps less mysterious?

      -

      Alex: This is where The Special Profile README becomes real: GitHub has a hidden feature: if you create a repository named exactly your-username/your-username (e.g., janesmith/janesmith), the README in that repo appears on your GitHub profile page. That matters in practice: It's a custom introduction visible to anyone who visits your profile.

      Jamie: Turn that into a path someone can follow.

      -

      Alex: Start with Creating Your Profile README. There is something to understand, something to try, and something that proves the try worked.

      -

      Alex: First, create a new repository. Then, name it exactly your-username (match your GitHub username exactly, case-sensitive). After that, make it public. Finally, initialize with a README. It is like walking a hallway with named doors: read the sign, enter the right room, then confirm where you landed.

      +

      Alex: Keep the learner anchored in Practice 11.1 Step-by-Step: VS Code Accessibility Baseline. 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. This is the part to say slowly: github.dev (VS Code in the browser) or desktop VS Code if you installed it in Block 0.

      +

      Alex: For a learner, the useful signals are these. 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.

      +

      Alex: First, open your Learning Room repository on GitHub.com. Then, 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. After that, enable screen reader mode. Finally, open the Explorer panel with Ctrl+Shift+E (Mac: Cmd+Shift+E). Your screen reader should announce the file tree. It is like walking a hallway with named doors: read the sign, enter the right room, then confirm where you landed.

      Jamie: What is the ordered workflow?

      -

      Alex: First, edit the README with whatever you want to show on your profile. The rhythm is simple: orient, act, verify, then continue.

      -

      Jamie: What would you say to someone who is already bracing for this to be too much?

      -

      Alex: Start with What to include. There is something to understand, something to try, and something that proves the try worked.

      -

      Alex: The parts worth keeping in working memory are these. Introduction: Who you are, what you work on. Current focus: What projects or technologies you're learning. Skills: Languages, frameworks, tools (optional). How to reach you: Email, LinkedIn, personal site. Fun facts: Hobbies, interests (optional-keeps it human).

      +

      Alex: First, navigate to and open README.md from the file tree. Use arrow keys to move through files and Enter to open. Then, 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. After that, 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. Finally, 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. The rhythm is simple: orient, act, verify, then continue.

      +

      Jamie: What should they understand before typing anything?

      +

      Alex: The reason Completing Chapter 11: Submit Your Evidence matters is that return to GitHub.com, open the assigned setup or Day 2 readiness issue, and post a completion comment. That gives the learner a simple foothold: if any step was "no," add a note explaining where you got stuck so the facilitator can help.

      +

      Alex: Treat examples as spoken recipes, not decorations. You may hear something like 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. Read the command, understand what it changes, then run it only when the repository state matches the lesson.

      Alex: The useful habit is simple: orient first, act second, verify third. That pause before acting is part of the work.

      -

      Jamie: How do you keep commands from becoming magic words?

      -

      Alex: Start with Example profile README. There is something to understand, something to try, and something that proves the try worked.

      -

      Alex: Treat examples as spoken recipes, not decorations. You may hear something like Hi, I'm Jane Smith; I'm an accessibility advocate and open source contributor focused on making the web more inclusive.; Current focus; - Contributing to NVDA documentation; - Building accessible React components; - Learning TypeScript; Skills; - JavaScript,. Read the command, understand what it changes, then run it only when the repository state matches the lesson.

      -
      -

      Jamie: If I am listening before the workshop starts, what should settle in my mind first?

      -

      Alex: Here is the plain-English version of Profile README Best Practices. Keep it concise - visitors skim, not read Update occasionally - a README from 2019 looks stale Be authentic - people connect with real humans, not buzzwords Include links - make it easy to learn more or get in touch. Put another way, avoid excessive badges - 50 skill badges is visual clutter and screen reader noise Skip auto-generated stats - "commits per day" widgets are often inaccessible Don't overthink it - a simple paragraph is better than nothing.

      -

      Alex: This is where the talk moves from concept to action. Start with Screen Reader Considerations. There is something to understand, something to try, and something that proves the try worked.

      -

      Alex: The room should hear these as checkpoints. Use headings ( ) for structure. Provide alt text for any images. Avoid ASCII art - screen readers read it character by character (annoying). Test your README with a screen reader before publishing.

      -

      Alex: A solid navigation habit is to prove where you are before activating controls. Headings, landmarks, and the address bar are not trivia; they are your map.

      -

      Jamie: Where do you want a learner to place their attention here?

      -

      Alex: Start with Pinned repositories (up to 6). There is something to understand, something to try, and something that proves the try worked.

      -

      Alex: These are the details that keep the idea from floating away. Highlight your best work on your profile. Navigate to your profile → Select "Customize your pins". Choose which repos appear first.

      -
      -

      Alex: Before the learner moves on. Start with Contribution graph. There is something to understand, something to try, and something that proves the try worked.

      -

      Alex: That becomes easier when you listen for these cues. Shows your GitHub activity over the past year. Green squares indicate days with commits, PRs, issues, etc. Cannot be customized but reflects consistent contribution.

      -

      Jamie: Give me the version that sounds like an instructor, not a manual.

      -

      Alex: Start with Status. There is something to understand, something to try, and something that proves the try worked.

      -

      Alex: A few details make that real. Set a temporary status message (e.g., "On vacation until March 15"). Navigate to your profile → Select the smile icon → Set status.

      -

      Alex: Hold that next to this. Here is the plain-English version of What Is GitHub Sponsors? GitHub Sponsors lets you financially support developers and projects you depend on.

      +

      Alex: That matters because of the next idea. Start with Expected Outcomes. There is something to understand, something to try, and something that proves the try worked.

      +

      Alex: On the ground, that means a few things. 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).

      -

      Jamie: Let's pause on How it works. What should a learner take away from it?

      -

      Alex: Start with How it works. There is something to understand, something to try, and something that proves the try worked.

      -

      Alex: That shows up in the workshop in a few specific ways. Developers/projects create a Sponsors profile. You choose a monthly sponsorship tier ($5, $10, $25/month, etc.). Your payment goes directly to the developer (GitHub takes no fees).

      -

      Alex: That connects to another useful point. Start with Why Sponsor? There is something to understand, something to try, and something that proves the try worked.

      -

      Alex: For a learner, the useful signals are these. Sustainability: Many open source maintainers volunteer their time. Sponsorships help them keep projects alive. Gratitude: If a project saved you hours of work, sponsorship is a way to say thanks. Priority support: Some maintainers offer sponsor-only Discord access, early releases, or prioritized bug fixes.

      -

      Jamie: Give me the sequence, because order matters here.

      -

      Alex: Start with How to Sponsor. There is something to understand, something to try, and something that proves the try worked.

      -

      Alex: First, navigate to a user or repository's GitHub page. Then, look for the "Sponsor" button (heart icon). After that, choose a tier or custom amount. Finally, select payment method (credit card or PayPal). The rhythm is simple: orient, act, verify, then continue.

      Jamie: How would you walk the room through that step by step?

      -

      Alex: First, GitHub sends a receipt; your sponsorship appears on your profile (optionally publicly). Think of it as a rail line: each stop confirms you are still on the right route before the next one.

      -
      -

      Alex: Here is the practical turn. Start with Screen reader navigation. There is something to understand, something to try, and something that proves the try worked.

      -

      Alex: On the ground, that means a few things. The Sponsor button appears near the profile photo or repo name. Press B to cycle through buttons on the page until you hear "Sponsor".

      -

      Jamie: What does the learner do first, second, and then after that?

      -

      Alex: Here is the plain-English version of Can I Receive Sponsorships? If you maintain an open source project or contribute regularly. Put another way, many accessibility advocates successfully use Sponsors to fund their work improving assistive technology and inclusive design.

      -

      Alex: First, navigate to github.com/sponsors. Then, select "Join the waitlist" or "Set up sponsors". After that, connect a payment method (Stripe or bank account). Finally, create sponsor tiers with descriptions. Treat it like a recipe: do not add the next ingredient until the previous one is actually in the bowl.

      -

      Jamie: Let's pause on Can I Receive Sponsorships? What should a learner take away from it?

      -

      Alex: First, promote your Sponsors page to your audience. It is a checklist, but a meaningful one: every item creates evidence that the next step is safe.

      -

      Alex: Keep the thread going. This is where What Is a GitHub Wiki? becomes real: every repository can have a wiki - a space for documentation separate from the code. That matters in practice: It's lightweight and Markdown-based. The workshop is closer to rehearsal than lecture. You hear the move, try the move, and then check what changed.

      +

      Alex: Start with If You Get Stuck. There is something to understand, something to try, and something that proves the try worked.

      +

      Alex: First, 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. Then, screen reader mode toggle did not announce anything? Open Command Palette (Ctrl+Shift+P) and type Screen Reader to find the toggle manually. After that, explorer panel is empty? VS Code may still be loading the repository. Wait 5-10 seconds and press Ctrl+Shift+E again. Finally, on Mac with VoiceOver, navigation feels wrong? Run Toggle Screen Reader Accessibility Mode from Command Palette. VoiceOver sometimes needs the explicit toggle. Treat it like a recipe: do not add the next ingredient until the previous one is actually in the bowl.

      +

      Jamie: Give me the sequence, because order matters here.

      +

      Alex: First, cannot find the Accounts button? Open Command Palette and type Accounts to manage sign-in from there. Then, Copilot not showing in the status bar? github.dev does not support Copilot - you need desktop VS Code or a Codespace. After that, 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. Finally, ask facilitator for a side-by-side demo and repeat the same steps. It is a checklist, but a meaningful one: every item creates evidence that the next step is safe.

      +

      Alex: This is where the talk moves from concept to action. This is where Learning Moment becomes real: tool setup is part of contribution skill. That matters in practice: A stable, accessible editor reduces stress and increases contribution quality.

      +

      Jamie: Let's pause on Learning Pattern Used in This Chapter. What should a learner take away from it?

      +

      Alex: Start with Learning Pattern Used in This Chapter. There is something to understand, something to try, and something that proves the try worked.

      +

      Alex: First, open the tool in the simplest way possible (. key for github.dev). Then, sign in and verify your identity and tools are ready (Accounts, Copilot). After that, configure accessibility before doing any work (screen reader mode first). Finally, verify each navigation surface works with your assistive technology. It is like walking a hallway with named doors: read the sign, enter the right room, then confirm where you landed.

      +

      Jamie: Before we leave Learning Pattern Used in This Chapter, what is the practical point?

      +

      Alex: First, record what worked and what didn't (evidence comment). The rhythm is simple: orient, act, verify, then continue.

      -

      Jamie: Let's pause on When to use a wiki. What should a learner take away from it?

      -

      Alex: Start with When to use a wiki. There is something to understand, something to try, and something that proves the try worked.

      -

      Alex: Here is what that changes in practice. Multi-page documentation (tutorials, guides, FAQs). Community-editable docs (wikis can be editable by anyone). Knowledge that doesn't belong in README (too long, too specific).

      -

      Alex: Another way to ground it. Start with When NOT to use a wiki. There is something to understand, something to try, and something that proves the try worked.

      -

      Alex: The practical takeaway is this. Your project already uses GitHub Pages or external docs. Documentation needs to be version-controlled with code (wikis are separate Git repos). You want full control (wikis are less customizable than Pages).

      -

      Jamie: Let's pause on Accessing a Repo's Wiki. What should a learner take away from it?

      -

      Alex: Start with Accessing a Repo's Wiki. There is something to understand, something to try, and something that proves the try worked.

      -

      Alex: First, navigate to the repository. Then, select the "Wiki" tab. After that, if no wiki exists, you'll see "Create the first page". Think of it as a rail line: each stop confirms you are still on the right route before the next one.

      +

      Alex: Before the learner moves on. The reason 1. Why VS Code for Open Source Contribution matters is that GitHub's browser interface is excellent for reviewing, discussing, and triaging. That gives the learner a simple foothold: for Markdown contributions (which is most of what 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. The interface gets friendlier when it stops being a wall of controls and starts being a set of named places.

      +

      Jamie: What should someone listen for when a lesson offers more than one tool path?

      +

      Alex: Start with Learning Cards: Why VS Code. There is something to understand, something to try, and something that proves the try worked.

      +

      Alex: A few details make that real. 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. 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.

      +

      Alex: Hold that next to this. Here is the plain-English version of Before you install anything: try VS Code right now in your browser. GitHub provides a web-based version of VS Code called github.dev. Put another way, it runs entirely in your browser with zero installation.

      -

      Jamie: Let's pause on Creating Wiki Pages. What should a learner take away from it?

      -

      Alex: Here is the plain-English version of Creating Wiki Pages. Wiki pages automatically appear in a sidebar for navigation. It is like learning a transit route. The names of the stops matter because they tell you whether you are still going the right direction.

      -

      Alex: First, go to the Wiki tab. Then, select "New page". After that, add a title and content (Markdown). Finally, select "Save". Treat it like a recipe: do not add the next ingredient until the previous one is actually in the bowl.

      -

      Jamie: Let's pause on Wiki Accessibility. What should a learner take away from it?

      -

      Alex: This is where Wiki Accessibility becomes real: return to: Resources Appendix S - Organizations and Templates Appendix G - GitHub Discussions Appendix T - Contributing to Open Source Appendix A - Glossary.

      -

      Alex: The practical takeaway is this. GitHub's wiki editor is the same as the issue/PR comment editor. All Markdown features work (headings, lists, links, code blocks). Use proper heading hierarchy (, ) for screen reader navigation. Link between wiki pages: [[Page Title]]. Screen reader caveat: Wiki pages are a separate Git repository. Any changes pushed directly to the wiki's git remote are not tracked by the main repository's branch protection - meaning no PR review process applies. Treat wikis as community-editable.

      -

      Alex: Now bring the learner back to the room. Start with Learning Cards: Organizations and Templates. There is something to understand, something to try, and something that proves the try worked.

      -

      Alex: The practical takeaway is this. The "Use this template" button is near the "Code" button at the top of a template repository -- press B to navigate buttons until you hear it. Organization profiles list repositories and members under heading sections -- use H to jump between People, Repositories, and Projects. Repository visibility (Public, Private, Internal) is announced as a badge near the repository name heading. Template repositories show a green "Use this template" button prominently near the top -- it replaces or sits alongside the Fork button. Organization pages use the same layout as personal profiles but with team-oriented sections. Archived repositories display a yellow warning banner across the top of the page.

      +

      Jamie: Let's pause on Method 1: The Period Key Shortcut (Fastest). What should a learner take away from it?

      +

      Alex: Start with Method 1: The Period Key Shortcut (Fastest). There is something to understand, something to try, and something that proves the try worked.

      +

      Alex: First, press. (period key - just the period, no modifier keys). Then, the page transforms into VS Code. After that, you are now editing in github.dev. Finally, the URL changes to github.dev/owner/repo. It is a checklist, but a meaningful one: every item creates evidence that the next step is safe.

      +

      Jamie: Before we leave Method 1: The Period Key Shortcut (Fastest), what is the practical point?

      +

      Alex: First, screen reader mode works exactly as it does in desktop VS Code (toggle with Shift+Alt+F1). It is like walking a hallway with named doors: read the sign, enter the right room, then confirm where you landed.

      +

      Alex: That connects to another useful point. Keep the learner anchored in Where it works. The period key shortcut is a single keypress - no modifier keys. This is the part to say slowly: It is GitHub's universal "open this in VS Code" command. A good GitHub workflow is like a well-run meeting: everyone knows the topic, the next action, and who has the floor.

      +

      Alex: The parts worth keeping in working memory are these. Repository home pages. File view pages. Pull request pages. Any branch or commit view.

      +

      Jamie: What is the one idea that makes the next few steps less mysterious?

      +

      Alex: The reason Method 2: Direct URL matters is that change the domain in any GitHub URL.

      +

      Alex: Here is what that changes in practice. github.com/owner/repo becomes github.dev/owner/repo. Works for any branch, file, or commit URL.

      -

      Jamie: How should someone choose between those options?

      -

      Alex: The reason Template vs. Fork - Which One? matters is that these are two very different actions that both appear near the "Code" button. That gives the learner a simple foothold: GitHub Skills courses use "Use this template" - you start fresh with the course scaffold but your copy has no upstream connection.

      -

      Alex: Use the comparison to make a decision, not to recite a table. The main contrasts are: Use when. means What you get. Contributing back to the original project means Full git history; your changes can be PRed upstream. Use this template means Starting a new project based on the structure means Clean git history; no connection to the original repo.

      -

      Jamie: Let's pause on Creating a Template Repository. What should a learner take away from it?

      -

      Alex: Start with Creating a Template Repository: Maintainers can mark any repository as a template. Think of it like entering a new building: first you find the lobby, then the room, then the door you actually need.

      -

      Alex: First, navigate to the repository's Settings tab. Then, scroll to the "General" section → find the "Template repository" checkbox. After that, check it and save. Finally, the repository now shows a "Use this template" button instead of (or alongside) "Fork". Think of it as a rail line: each stop confirms you are still on the right route before the next one.

      -

      Jamie: Let's pause on Using a Template Repository. What should a learner take away from it?

      -

      Alex: Start with Using a Template Repository. There is something to understand, something to try, and something that proves the try worked.

      -

      Alex: First, navigate to the template repository. Then, select "Use this template" button (near the top, next to "Code"). After that, select "Create a new repository". Finally, name your new repository, choose visibility, and confirm. Treat it like a recipe: do not add the next ingredient until the previous one is actually in the bowl.

      -

      Jamie: Before we leave Using a Template Repository, what is the practical point?

      -

      Alex: First, GitHub creates a new repository with the template's files but no commit history. It is a checklist, but a meaningful one: every item creates evidence that the next step is safe.

      +

      Jamie: Let's pause on Method 3: From the Repository Page. What should a learner take away from it?

      +

      Alex: Start with Method 3: From the Repository Page: Screen reader users (NVDA / JAWS / VoiceOver).

      +

      Alex: First, click the green Code button on any repository page. Then, in the dropdown, click Open with github.dev. After that, navigate to the Code button (press B or Tab until you hear "Code, button" or similar). Finally, press Enter to open the dropdown menu. Think of it as a rail line: each stop confirms you are still on the right route before the next one.

      +

      Jamie: Before we leave Method 3: From the Repository Page, what is the practical point?

      +

      Alex: First, press Down Arrow to reach "Open with github.dev". Then, press Enter. Treat it like a recipe: do not add the next ingredient until the previous one is actually in the bowl.

      +

      Jamie: What would you say to someone who is already bracing for this to be too much?

      +

      Alex: Here is the plain-English version of What You Get in github.dev. Everything in the list below works exactly like desktop VS Code.

      +

      Alex: The room should hear these as checkpoints. Full text editor with syntax highlighting. All VS Code keyboard shortcuts (see Section 11: Keyboard Shortcuts Editor and Appendix M). 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.

      +

      Alex: Keep the thread going. This is where What github.dev Does NOT Have becomes real: these limitations are why desktop VS Code exists. That matters in practice: github.dev is for quick edits and reading code. The workshop is closer to rehearsal than lecture. You hear the move, try the move, and then check what changed.

      +

      Alex: These are the details that keep the idea from floating away. 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.

      -

      Jamie: What should happen before anyone copies and runs it?

      -

      Alex: Start with Screen reader path. There is something to understand, something to try, and something that proves the try worked.

      -

      Alex: Treat examples as spoken recipes, not decorations. You may hear something like B → navigate buttons → find "Use this template" → Enter; ↓ → "Create a new repository" from the dropdown → Enter. Read the command, understand what it changes, then run it only when the repository state matches the lesson.

      -

      Jamie: Let's pause on What Is an Organization? What should a learner take away from it?

      -

      Alex: Keep the learner anchored in What Is an Organization? A GitHub organization is an account that multiple people share. This is the part to say slowly: Instead of github.com/username/repo, organization repos live at github.com/org-name/repo.

      -

      Jamie: Let's pause on Joining an Organization. What should a learner take away from it?

      -

      Alex: The reason Joining an Organization matters is that maintainers can invite you to join. That gives the learner a simple foothold: you can also be a public contributor to an org repo without being a member - you fork the repo and submit PRs without needing an invitation. The interface gets friendlier when it stops being a wall of controls and starts being a set of named places.

      -

      Alex: First, you receive an email + GitHub notification. Then, navigate to github.com/settings/organizations to accept. After that, or click the link in the invitation email. The rhythm is simple: orient, act, verify, then continue.

      +

      Jamie: Where does the workshop stop being a tour and start becoming contribution?

      +

      Alex: Keep the learner anchored in Why github.dev Matters for This Workshop. You spend Day 1 in the GitHub browser interface. This is the part to say slowly: You spend Day 2 in desktop VS Code.

      +

      Alex: That becomes easier when you listen for these cues. 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.

      +

      Alex: Another way to ground it. Start with Use github.dev when. There is something to understand, something to try, and something that proves the try worked.

      +

      Alex: That shows up in the workshop in a few specific ways. 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.

      +

      Jamie: What stays the same when the tool changes?

      +

      Alex: Start with Use desktop VS Code when. There is something to understand, something to try, and something that proves the try worked.

      +

      Alex: The practical takeaway is this. 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.

      -

      Jamie: Let's pause on Organization Membership Visibility. What should a learner take away from it?

      -

      Alex: Start with Organization Membership Visibility. There is something to understand, something to try, and something that proves the try worked.

      -

      Alex: The practical takeaway is this. By default, your org membership is private (only you and org owners can see it). You can set it to public in your organization membership settings. Public membership appears on your GitHub profile under "Organizations". For community-access: if you become a member, set your membership public to show your contribution publicly on your profile.

      -

      Alex: This is the part worth saying out loud. Here is the plain-English version of Teams Inside Organizations. Organizations can create teams (e.g., @community-access/accessibility-reviewers). Put another way, when you see a team mentioned in a PR or issue, that @mention notifies everyone on that team.

      -

      Jamie: Let's pause on Navigating an Organization Profile Page. What should a learner take away from it?

      -

      Alex: This is where Navigating an Organization Profile Page becomes real: organization-level Projects (like the community-access project board) appear in the org's Projects tab, not inside any single repository.

      +

      Jamie: Let's pause on Activate screen reader mode immediately. What should a learner take away from it?

      +

      Alex: Start with Activate screen reader mode immediately. There is something to understand, something to try, and something that proves the try worked.

      +

      Alex: First, press the period key on any GitHub repository to open github.dev. Then, press Shift+Alt+F1 (Mac: Shift+Option+F1) to enable screen reader mode. After that, VS Code announces "Screen reader optimized". Treat it like a recipe: do not add the next ingredient until the previous one is actually in the bowl.

      +

      Alex: A solid navigation habit is to prove where you are before activating controls. Headings, landmarks, and the address bar are not trivia; they are your map.

      +

      Jamie: Give me the version that sounds like an instructor, not a manual.

      +

      Alex: Start with What changes. There is something to understand, something to try, and something that proves the try worked.

      +

      Alex: The practical takeaway is this. 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.

      +

      Alex: Now bring the learner back to the room. Start with Navigation. There is something to understand, something to try, and something that proves the try worked.

      +

      Alex: The practical takeaway is this. 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.

      -

      Alex: That matters because of the next idea. Keep the learner anchored in Repository Settings - What Contributors Need to Know. You may not have Settings access to most repositories (that requires maintainer role). This is the part to say slowly: But knowing what's there helps you understand why a repository behaves the way it does. A good GitHub workflow is like a well-run meeting: everyone knows the topic, the next action, and who has the floor.

      -

      Jamie: Let's pause on Repository Visibility. What should a learner take away from it?

      -

      Alex: The reason Repository Visibility matters is that the repository's visibility label appears on its page. That gives the learner a simple foothold: screen readers: the visibility badge is usually near the repo name heading (H1).

      -

      Alex: Keep the teaching thread moving. Start with Archived Repositories: When a maintainer archives a repository, it becomes read-only. The next useful detail is this: If you find a repo you planned to contribute to is archived, look for a fork or successor project.

      -

      Alex: The practical takeaway is this. No new issues, PRs, or comments can be created. Existing content is fully preserved and viewable. The UI shows a yellow banner: "This repository has been archived by the owner.". Screen readers: NVDA/JAWS will read this banner when you navigate to the top of the page with Ctrl+Home.

      +

      Jamie: If I am listening before the workshop starts, what should settle in my mind first?

      +

      Alex: Start with NVDA/JAWS users. There is something to understand, something to try, and something that proves the try worked.

      +

      Alex: The practical takeaway is this. 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.

      +

      Alex: Here is the practical turn. Start with VoiceOver users. There is something to understand, something to try, and something that proves the try worked.

      +

      Alex: The practical takeaway is this. 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.).

      +

      Jamie: Where do you want a learner to place their attention here?

      +

      Alex: Start with Learning Cards: github.dev. There is something to understand, something to try, and something that proves the try worked.

      +

      Alex: The practical takeaway is this. 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. 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.

      -

      Jamie: Let's pause on Repository Topics. What should a learner take away from it?

      -

      Alex: Here is the plain-English version of Repository Topics. Topics are keyword tags on a repository (e.g., accessibility, screen-reader, open-source). Put another way, they appear as colored chips on the repository home page and improve discoverability in GitHub search.

      -

      Alex: The practical takeaway is this. As a contributor: Topics tell you what the project is about at a glance. As a maintainer: Add topics in Settings → General → Topics section to improve search ranking. Screen reader: Topics are links in the "About" sidebar section; use B (next button) or Links list to reach them.

      -

      Alex: Keep the teaching thread moving. This is where Default Branch Name becomes real: the default branch is the one all PRs target by default. That matters in practice: Modern projects use main; older projects may use master or another name. The workshop is closer to rehearsal than lecture. You hear the move, try the move, and then check what changed.

      -

      Alex: A solid Git habit is to know which branch you are on, what changed, and what confirmation you expect before you run the next command.

      -

      Jamie: Let's pause on GitHub Is More Than a Code Host -- It's a Community. What should a learner take away from it?

      -

      Alex: Keep the learner anchored in GitHub Is More Than a Code Host -- It's a Community. Who this is for: You have learned the basics of GitHub and want to know how to use it as a social platform -- discovering interesting projects, following developers whose work you admire, and building a presence in the open source community. This is the part to say slowly: This appendix covers the social layer of GitHub that most tutorials skip entirely.

      +

      Jamie: Let's pause on Try It Right Now. What should a learner take away from it?

      +

      Alex: This is where Try It Right Now becomes real: before reading the rest of this guide. That matters in practice: The desktop version in the rest of this guide is the same experience - with Copilot, agents, and a terminal added.

      +

      Alex: First, open your Learning Room repository in your browser. Then, press. (period key). After that, github.dev opens. Finally, press Shift+Alt+F1 (Mac: Shift+Option+F1) to enable screen reader mode. It is a checklist, but a meaningful one: every item creates evidence that the next step is safe.

      +

      Jamie: Before we leave Try It Right Now, what is the practical point?

      +

      Alex: First, press Ctrl+Shift+E (Mac: Cmd+Shift+E) to open the Explorer. Then, navigate to README.md and press Enter. After that, press Ctrl+Home (Mac: Cmd+Up) to go to the top of the file. Finally, press Ctrl+Shift+O (Mac: Cmd+Shift+O) to see the outline (all headings). It is like walking a hallway with named doors: read the sign, enter the right room, then confirm where you landed.

      +

      Jamie: How do we make tool choice feel like access, not pressure?

      +

      Alex: Keep the learner anchored in 3. Screen Reader Mode in VS Code. See also: Chapter 12: VS Code Accessibility goes deeper into accessibility features, Accessible View, and signal customization. This is the part to say slowly: If you use NVDA, JAWS, VoiceOver, or another screen reader, read this section before continuing.

      +

      Alex: This is the part worth saying out loud. The reason Verify it is active matters is that open Settings (Ctrl+, - Mac: Cmd+,) then search for accessibility support then confirm it shows on (not auto). The interface gets friendlier when it stops being a wall of controls and starts being a set of named places.

      -

      Alex: Keep the teaching thread moving. Start with Learning Cards: Social Features. There is something to understand, something to try, and something that proves the try worked.

      -

      Alex: The practical takeaway is this. The Star button is announced as "Star this repository" or "Unstar this repository" -- press B to find it in the repository header area. The Follow button on a user profile is announced as "Follow [username]" -- Tab forward from the avatar and bio to reach it. On the Explore and Trending pages, each repository entry is a heading with a link -- use H or 3 to jump between entries. Star and Watch buttons sit side by side in the repository header with distinct icons (star and eye) -- both show counts next to them. Your contribution graph uses green intensity to show activity levels -- enable high-contrast theme if the color differences are hard to distinguish. The Trending page lists repositories in a numbered vertical list with star counts and daily gain on the right side.

      -

      Jamie: Let's pause on What a star is. What should a learner take away from it?

      -

      Alex: Start with What a star is: A star is GitHub's version of a bookmark combined with a "like." When you star a repository.

      -

      Alex: The practical takeaway is this. It saves to your starred list at github.com/username?tab=stars -- easy to find later. It signals to the maintainer that their work is valued. It contributes to the project's star count, which helps others discover it. It may appear in your followers' feeds.

      -

      Alex: Keep the teaching thread moving. Here is the plain-English version of Why star count matters to projects. Star counts are a social proof signal -- developers browsing for tools often sort by stars to find well-regarded projects. Put another way, a project going from 10 stars to 1,000 stars can dramatically change how many contributors it attracts. It is like learning a transit route. The names of the stops matter because they tell you whether you are still going the right direction.

      +

      Jamie: Let's pause on NVDA-Specific Settings for VS Code. What should a learner take away from it?

      +

      Alex: Start with NVDA-Specific Settings for VS Code. There is something to understand, something to try, and something that proves the try worked.

      +

      Alex: First, open NVDA Menu then Preferences then Settings then Browse Mode. Then, set "Maximum length of text on a single line" to 10000 (prevents truncation in long lines). After that, under Object Presentation: set "Report tooltip delay" to off. Finally, recommended: use NVDA + Google Chrome for the integrated browser panels. Think of it as a rail line: each stop confirms you are still on the right route before the next one.

      +

      Jamie: Let's pause on JAWS-Specific Settings for VS Code. What should a learner take away from it?

      +

      Alex: Start with JAWS-Specific Settings for VS Code. There is something to understand, something to try, and something that proves the try worked.

      +

      Alex: First, JAWS should detect VS Code automatically and switch to PC Cursor mode for the editor. Then, if the editor feels unresponsive, press Insert+Z to toggle virtual cursor off. After that, for the integrated terminal: use Insert+Z to enter forms/PC mode, then interact with the terminal. Treat it like a recipe: do not add the next ingredient until the previous one is actually in the bowl.

      +

      Jamie: Let's pause on VoiceOver-Specific Settings for VS Code (macOS). What should a learner take away from it?

      +

      Alex: Start with VoiceOver-Specific Settings for VS Code (macOS). There is something to understand, something to try, and something that proves the try worked.

      +

      Alex: First, open VS Code then Shift+Alt+F1 (Mac: Shift+Option+F1) to confirm screen reader mode. Then, in VoiceOver Utility: Verbosity then set "Punctuation" to "All" for reading code. After that, use Quick Nav OFF (Left+Right Arrow) when inside the editor - standard cursor navigation is more predictable. Finally, use VO+Shift+Down to interact with the editor, VO+Shift+Up to stop interacting. It is a checklist, but a meaningful one: every item creates evidence that the next step is safe.

      -

      Jamie: Let's pause on GitHub.com. What should a learner take away from it?

      -

      Alex: This is where GitHub.com becomes real: on any repository page, the Star button is in the top-right area of the repository header, next to Fork.

      -

      Alex: The practical takeaway is this. Click Star to star the repository -- the button changes to Starred with a filled star icon. Click the dropdown arrow next to Star to choose a List to organize it into (see Section 8). Click Starred to unstar.

      -

      Alex: Keep the teaching thread moving. Keep the learner anchored in Keyboard shortcut. On a repository page, press g then s to toggle the star.

      -

      Jamie: Let's pause on Screen reader navigation. What should a learner take away from it?

      -

      Alex: Start with Screen reader navigation. There is something to understand, something to try, and something that proves the try worked.

      -

      Alex: The practical takeaway is this. NVDA/JAWS: The Star button is in the page region after the repository title heading. Navigate by button (B) or Tab to find it. It's announced as "Star this repository" or "Unstar this repository.". VoiceOver: VO+Command+J to jump to buttons, or Tab through the header area. The button label changes between "Star" and "Starred.".

      +

      Alex: Keep the teaching thread moving. Start with Learning Cards: Screen Reader Mode. There is something to understand, something to try, and something that proves the try worked.

      +

      Alex: The practical takeaway is this. 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. 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.

      +

      Jamie: There are a lot of tools in play. How do we keep that from feeling like a contest?

      +

      Alex: The reason 4. The VS Code Interface Tour matters is that before diving into individual features, here is how VS Code is organized. That gives the learner a simple foothold: every area is reachable by keyboard.

      +

      Alex: Keep the teaching thread moving. Start with The Five Major Regions: Text description of the layout above: VS Code has five major regions arranged in a grid. The next useful detail is this: The Menu Bar spans the full width across the top.

      -

      Jamie: What is the safe way to learn from that example?

      -

      Alex: Start with GitHub CLI. There is something to understand, something to try, and something that proves the try worked.

      -

      Alex: Treat examples as spoken recipes, not decorations. You may hear something like Star a repository; gh api user/starred/owner/repo --method PUT; Unstar a repository; gh api user/starred/owner/repo --method DELETE; List your starred repositories; gh api user/starred --jq '.[].full name'; Check if you've starred a repo; gh api. Read the command, understand what it changes, then run it only when the repository state matches the lesson.

      -

      Jamie: Let's pause on Viewing your stars. What should a learner take away from it?

      -

      Alex: Here is the plain-English version of Viewing your stars. Go to github.com/username?tab=stars -- or click your avatar → Your stars. Put another way, you'll see all your starred repositories sorted by most recently starred.

      -

      Alex: Keep the teaching thread moving. Start with Learning Cards: Stars. There is something to understand, something to try, and something that proves the try worked.

      -

      Alex: The practical takeaway is this. The Star button is in the repository header area -- press B to navigate buttons until you hear "Star this repository" (or "Unstar this repository" if already starred); press Enter to toggle. The keyboard shortcut g then s on any repository page toggles the star without needing to navigate to the button. Your starred repos are listed at github.com/username?tab=stars -- each entry is a heading with the repo name as a link; use H to jump between starred repos. The Star button shows a star icon with a count next to it in the repository header -- at high zoom, the button may wrap below the repo name; look for the star icon near Fork and Watch. When you star a repo, the button changes from an outline star to a filled star with the label "Starred" -- the visual change is subtle; confirm by re-reading the button text. The dropdown arrow next to Star lets you add the repo to a List -- look for a small triangle icon to the right of the Star button at high magnification.

      +

      Jamie: Let's pause on Navigating Between Regions. What should a learner take away from it?

      +

      Alex: Here is the plain-English version of Navigating Between Regions. Key insight: Press F6 repeatedly to cycle focus through the major regions: Sidebar, Editor, Panel, Status Bar, and back. Put another way, this is the universal "where am I, take me somewhere else" key in VS Code.

      +

      Alex: Keep the teaching thread moving. This is where Learning Cards: Finding Your Way Around VS Code becomes real: screen reader users (NVDA / JAWS / VoiceOver). The workshop is closer to rehearsal than lecture. You hear the move, try the move, and then check what changed.

      +

      Alex: The practical takeaway is this. 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. Ctrl+= / Ctrl+- to zoom the entire VS Code window (all UI elements scale).

      +

      Jamie: Let's pause on 5. The Accounts Button and GitHub Sign-In. What should a learner take away from it?

      +

      Alex: Keep the learner anchored in 5. The Accounts Button and GitHub Sign-In. See also: Chapter 14: Git in Practice covers the full Git workflow in VS Code including the Source Control panel. This is the part to say slowly: The Accounts button sits at the bottom of the Activity Bar (the vertical icon strip on the left side of VS Code).

      -

      Jamie: Let's pause on What watching does. What should a learner take away from it?

      -

      Alex: Keep the learner anchored in What watching does. When you watch a repository, GitHub sends you notifications about activity in it -- new issues, pull requests, releases, and more. This is the part to say slowly: Unlike stars (which are passive bookmarks), watching is active -- you're opting into the conversation.

      -

      Alex: Keep the teaching thread moving. The reason Watch levels matters is that GitHub gives you granular control over how much you hear from a repo. The interface gets friendlier when it stops being a wall of controls and starts being a set of named places.

      -

      Jamie: Let's pause on How to watch a repository. What should a learner take away from it?

      -

      Alex: Start with How to watch a repository: On any repository page, the Watch button is next to the Star button in the header. The next useful detail is this: For most repositories you contribute to, "Participating and @mentions" is the right level -- you hear about threads you're in without inbox overload.

      -

      Alex: First, click Watch to open the dropdown. Then, choose your notification level. After that, the button updates to show your current setting. Think of it as a rail line: each stop confirms you are still on the right route before the next one.

      +

      Alex: Keep the teaching thread moving. Start with Why Sign In Matters. There is something to understand, something to try, and something that proves the try worked.

      +

      Alex: The practical takeaway is this. 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.

      +

      Jamie: Let's pause on From the Accounts Button. What should a learner take away from it?

      +

      Alex: Start with From the Accounts Button. There is something to understand, something to try, and something that proves the try worked.

      +

      Alex: First, press F6 until you hear the Activity Bar, then arrow down to the Accounts button (it is at the very bottom of the bar). Then, press Enter to open the Accounts menu. After that, select "Sign in with GitHub to use GitHub Copilot" (or a similar prompt). Finally, a browser window opens for GitHub OAuth authorization. Think of it as a rail line: each stop confirms you are still on the right route before the next one.

      +

      Jamie: Before we leave From the Accounts Button, what is the practical point?

      +

      Alex: First, authorize VS Code, then return to the editor. Then, your screen reader announces your GitHub username in the Accounts button. Treat it like a recipe: do not add the next ingredient until the previous one is actually in the bowl.

      +

      Jamie: Let's pause on From the Command Palette. What should a learner take away from it?

      +

      Alex: Start with From the Command Palette. There is something to understand, something to try, and something that proves the try worked.

      +

      Alex: First, press Ctrl+Shift+P then type sign in. Then, select "GitHub: Sign In". After that, complete the browser OAuth flow and return to VS Code. Treat it like a recipe: do not add the next ingredient until the previous one is actually in the bowl.

      -

      Jamie: What should they understand before typing anything?

      -

      Alex: Treat examples as spoken recipes, not decorations. You may hear something like Watch a repository (all activity); gh api repos/owner/repo/subscription --method PUT --field subscribed=true; Watch releases only (requires GitHub.com -- not available via API alone); Use the web UI for granular watch levels; Ignore a repository; gh api. Read the command, understand what it changes, then run it only when the repository state matches the lesson.

      -

      Jamie: Let's pause on Learning Cards: Watching Repositories. What should a learner take away from it?

      -

      Alex: Start with Learning Cards: Watching Repositories. There is something to understand, something to try, and something that proves the try worked.

      -

      Alex: The practical takeaway is this. The Watch button is next to the Star button in the repository header -- press B to navigate buttons until you hear "Watch" or a watch level label; press Enter to open the dropdown. The watch level dropdown presents radio-style options (Not watching, Participating, All Activity, Releases only, Ignore) -- arrow through them and press Enter to select. "Participating and @mentions" is the recommended default for repos you contribute to -- it notifies you only for threads you are in or mentioned in, avoiding inbox overload. The Watch button shows an eye icon with a dropdown arrow and a count of watchers -- at high zoom, look for it immediately to the left of the Star button in the repository header. The dropdown menu lists five watch levels vertically with radio indicators -- the currently selected level has a filled radio dot or checkmark next to it. "Releases only" is the best choice for tools and dependencies you use but do not contribute to -- it sends one notification per release instead of every issue and PR.

      -

      Alex: Keep the teaching thread moving. Keep the learner anchored in What following does. When you follow a developer on GitHub. This is the part to say slowly: Following is one-way (like Twitter/X) -- they don't need to follow you back. A good GitHub workflow is like a well-run meeting: everyone knows the topic, the next action, and who has the floor.

      -

      Alex: The practical takeaway is this. Their public activity appears in your home feed. You see when they star a repository, create a new repo, or get a new follower. They receive a notification that you followed them. You appear in their followers list.

      +

      Jamie: Let's pause on Verifying You Are Signed In. What should a learner take away from it?

      +

      Alex: Start with Verifying You Are Signed In. There is something to understand, something to try, and something that proves the try worked.

      +

      Alex: The practical takeaway is this. 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.

      +

      Alex: Keep the teaching thread moving. Start with Learning Cards: GitHub Sign-In. There is something to understand, something to try, and something that proves the try worked.

      +

      Alex: The practical takeaway is this. 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. 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.

      +

      Jamie: Let's pause on 6. Verifying GitHub Copilot Status. What should a learner take away from it?

      +

      Alex: The reason 6. Verifying GitHub Copilot Status matters is that GitHub Copilot is your AI pair programmer. That gives the learner a simple foothold: before starting any contribution work, confirm it is active and responding.

      -

      Jamie: Let's pause on Who to follow. What should a learner take away from it?

      -

      Alex: The reason Who to follow matters is that start with people whose work you already use.

      -

      Alex: The practical takeaway is this. Maintainers of tools and libraries you use daily. Authors of blog posts or talks that helped you learn. Developers in accessibility, open source, or your tech stack. Visiting the Contributors tab of a repository you love: github.com/owner/repo/graphs/contributors. Checking who opened issues or PRs you found valuable. Looking at who your existing follows follow.

      -

      Alex: Keep the teaching thread moving. Start with How to follow someone: On any user profile page (github.com/username), click the Follow button below their avatar. The next useful detail is this: To unfollow: click Following → it changes back to Follow.

      -

      Jamie: Before we leave Screen reader navigation, what is the practical point?

      -

      Alex: The practical takeaway is this. Navigate to the profile page. The Follow/Following button is near the top of the page, below the avatar and bio. NVDA/JAWS: press B to jump to buttons; the button is labelled "Follow [username]". VoiceOver: Tab to the button or use VO+Command+J.

      +

      Alex: Keep the teaching thread moving. Start with Status Bar Indicator: The Copilot icon appears in the Status Bar at the bottom-right of the VS Code window. Think of it like entering a new building: first you find the lobby, then the room, then the door you actually need.

      +

      Jamie: Let's pause on Command Palette Check. What should a learner take away from it?

      +

      Alex: Start with Command Palette Check. There is something to understand, something to try, and something that proves the try worked.

      +

      Alex: First, press Ctrl+Shift+P. Then, type GitHub Copilot: Status. After that, the output shows whether Copilot is signed in, active, or has errors. Treat it like a recipe: do not add the next ingredient until the previous one is actually in the bowl.

      +

      Jamie: Let's pause on Quick Test. What should a learner take away from it?

      +

      Alex: Start with Quick Test. There is something to understand, something to try, and something that proves the try worked.

      +

      Alex: First, open any.md file in the editor. Then, start typing a sentence (for example, Getting Started with). After that, if Copilot is active, a gray ghost-text suggestion appears after a brief pause. Finally, press Tab to accept or Escape to dismiss. It is a checklist, but a meaningful one: every item creates evidence that the next step is safe.

      -

      Jamie: Let's pause on GitHub CLI. What should a learner take away from it?

      -

      Alex: Treat examples as spoken recipes, not decorations. You may hear something like Follow a user; gh api user/following/username --method PUT; Unfollow a user; gh api user/following/username --method DELETE; List who you're following; gh api user/following --jq '.[].login'; List your followers; gh api user/followers --jq '.[].login'; Check. Read the command, understand what it changes, then run it only when the repository state matches the lesson.

      -

      Jamie: Let's pause on Viewing someone's profile. What should a learner take away from it?

      -

      Alex: Keep the learner anchored in Viewing someone's profile. The contribution graph is a visual calendar that screen readers may announce as a table or grid. This is the part to say slowly: Navigate with arrow keys to read individual day entries -- each cell describes the date and number of contributions.

      -

      Alex: The practical takeaway is this. Pinned repositories -- the 6 repos they've chosen to highlight. Contribution graph -- a visual grid of their activity over the past year (green squares = more activity). Recent activity -- PRs opened, issues commented on, repos starred. Repositories -- all their public repos.

      -

      Alex: Keep the teaching thread moving. The reason 4. Your Home Feed -- What You See When You Log In matters is that when you go to github.com while logged in, your home feed shows activity from people and repositories you follow or watch.

      +

      Jamie: Let's pause on Learning Cards: Copilot Status. What should a learner take away from it?

      +

      Alex: Start with Learning Cards: Copilot Status. There is something to understand, something to try, and something that proves the try worked.

      +

      Alex: The practical takeaway is this. 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. 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.

      +

      Alex: Keep the teaching thread moving. The reason 7. The Status Bar matters is that the Status Bar is the thin strip at the bottom of the VS Code window. That gives the learner a simple foothold: it provides real-time information about your workspace, file, and active tools. The interface gets friendlier when it stops being a wall of controls and starts being a set of named places.

      +

      Jamie: Let's pause on Navigating the Status Bar with a Keyboard. What should a learner take away from it?

      +

      Alex: Start with Navigating the Status Bar with a Keyboard. There is something to understand, something to try, and something that proves the try worked.

      +

      Alex: First, press F6 until your screen reader announces the Status Bar. Then, use Tab to move between items from left to right. After that, press Enter on any item to activate it (open a picker, toggle a setting, etc.). Finally, press Escape to return to the editor. Think of it as a rail line: each stop confirms you are still on the right route before the next one.

      -

      Jamie: Let's pause on What appears in your feed. What should a learner take away from it?

      -

      Alex: Start with What appears in your feed. There is something to understand, something to try, and something that proves the try worked.

      -

      Alex: The practical takeaway is this. Repositories starred by people you follow -- "Jane starred awesome-accessibility". New repositories created by people you follow. Releases from repositories you watch. Public activity from people you follow (PRs opened, issues commented on). "For you" recommendations -- GitHub suggests repos and people based on your activity.

      -

      Alex: Keep the teaching thread moving. Here is the plain-English version of Your feed is a discovery tool. One of the best ways to find new interesting projects is to follow a few active developers in your area of interest and watch what they star. Put another way, if 5 people you respect all starred the same new tool this week, it's probably worth a look. It is like learning a transit route. The names of the stops matter because they tell you whether you are still going the right direction.

      -

      Jamie: Let's pause on Customising your feed. What should a learner take away from it?

      -

      Alex: This is where Customising your feed becomes real: there's no fine-grained feed filter -- you control the feed by controlling who you follow and what you watch. That matters in practice: Unfollow noisy accounts, follow more focused ones.

      +

      Alex: Keep the teaching thread moving. Start with Learning Cards: Status Bar. There is something to understand, something to try, and something that proves the try worked.

      +

      Alex: The practical takeaway is this. 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. 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).

      +

      Jamie: Let's pause on 8. The Menu Bar. What should a learner take away from it?

      +

      Alex: This is where 8. The Menu Bar becomes real: the Menu Bar runs along the top of the VS Code window and provides structured access to every command category.

      +

      Alex: Keep the teaching thread moving. Start with Learning Cards: Menu Bar. There is something to understand, something to try, and something that proves the try worked.

      +

      Alex: The practical takeaway is this. 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. The Menu Bar respects your zoom level - increase window zoom for larger text.

      -

      Alex: Keep the teaching thread moving. Keep the learner anchored in 5. GitHub Explore -- Discovering New Projects. GitHub Explore at github.com/explore is the discovery hub -- curated collections, trending repos, and personalised recommendations.

      -

      Jamie: Let's pause on What Explore shows. What should a learner take away from it?

      -

      Alex: Start with What Explore shows. There is something to understand, something to try, and something that proves the try worked.

      -

      Alex: The practical takeaway is this. Trending -- most-starred repos this week (see Section 6). Topics -- browse by subject area (see Section 7). Collections -- curated lists of thematically related repos (e.g., "Tools for Open Source", "Accessibility Projects"). "For you" personalised recommendations -- based on your stars, follows, and language preferences.

      -

      Jamie: Let's pause on Navigating Explore with a screen reader. What should a learner take away from it?

      -

      Alex: Start with Navigating Explore with a screen reader. There is something to understand, something to try, and something that proves the try worked.

      -

      Alex: First, go to github.com/explore. Then, the page uses landmark regions -- jump to main to skip navigation. After that, collections and trending repos are listed as article/heading groups. Finally, use heading navigation (H) to jump between sections. Think of it as a rail line: each stop confirms you are still on the right route before the next one.

      -

      Jamie: Before we leave Navigating Explore with a screen reader, what is the practical point?

      -

      Alex: First, each repo entry has a heading (repo name as a link), language badge, star count, and description. Treat it like a recipe: do not add the next ingredient until the previous one is actually in the bowl.

      +

      Jamie: Let's pause on 9. Settings Sync. What should a learner take away from it?

      +

      Alex: The reason 9. Settings Sync matters is that settings Sync synchronizes your VS Code configuration across multiple machines and between desktop VS Code and github.dev. That gives the learner a simple foothold: when you sign in and enable sync, your settings, keyboard shortcuts, extensions, UI state, and profiles travel with you.

      +

      Jamie: Let's pause on Enabling Settings Sync. What should a learner take away from it?

      +

      Alex: Start with Enabling Settings Sync. There is something to understand, something to try, and something that proves the try worked.

      +

      Alex: First, open the Accounts button (Activity Bar, bottom-left) or press Ctrl+Shift+P then type Settings Sync: Turn On. Then, sign in with your GitHub account (or Microsoft account). After that, select which categories to sync (recommended: sync everything). Finally, VS Code syncs immediately and on every subsequent change. Think of it as a rail line: each stop confirms you are still on the right route before the next one.

      +

      Jamie: Let's pause on Conflict Resolution. What should a learner take away from it?

      +

      Alex: Here is the plain-English version of Conflict Resolution. If settings differ between machines, VS Code shows a merge editor where you choose which version to keep. Put another way, this is similar to a Git merge conflict but for settings.

      -

      Jamie: Let's pause on 6. Trending -- What's Popular Right Now. What should a learner take away from it?

      -

      Alex: Here is the plain-English version of 6. Trending -- What's Popular Right Now. GitHub Trending at github.com/trending shows repositories gaining the most stars over a time period. Put another way, it's one of the best places to discover new tools before everyone else knows about them.

      -

      Alex: Keep the teaching thread moving. This is where Filtering trending becomes real: use the dropdowns at the top of the page to filter.

      -

      Jamie: Let's pause on Trending developers. What should a learner take away from it?

      -

      Alex: Keep the learner anchored in Trending developers. Switch to github.com/trending/developers to see which developers are gaining the most followers -- another great way to find people to follow.

      +

      Alex: Keep the teaching thread moving. Start with Learning Cards: Settings Sync. There is something to understand, something to try, and something that proves the try worked.

      +

      Alex: The practical takeaway is this. 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). 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).

      +

      Jamie: Let's pause on Profiles. What should a learner take away from it?

      +

      Alex: Keep the learner anchored in Profiles. VS Code Profiles let you create named collections of settings, extensions, keyboard shortcuts, snippets, tasks, and UI state. This is the part to say slowly: Each profile is independent - switching profiles changes your entire VS Code configuration instantly.

      +

      Alex: Keep the teaching thread moving. The reason Creating a Profile matters is that when creating a profile, you choose what to. That gives the learner a simple foothold: you can start from the current configuration, an empty profile, or an existing profile template.

      +

      Alex: The practical takeaway is this. Settings - editor preferences, accessibility options, theme. Keyboard Shortcuts - all custom keybindings. Extensions - which extensions are installed and enabled. Snippets - code snippet definitions.

      -

      Jamie: Before we leave GitHub CLI, what is the practical point?

      -

      Alex: Treat examples as spoken recipes, not decorations. You may hear something like Trending repos aren't in the official API, but you can get recently starred popular repos:; gh search repos --sort stars --order desc --limit 20 --language markdown; Trending in a specific language; gh search repos --sort stars --order desc --limit 20. Read the command, understand what it changes, then run it only when the repository state matches the lesson.

      -

      Jamie: Let's pause on 7. Topics -- Finding Projects by Category. What should a learner take away from it?

      -

      Alex: Start with 7. Topics -- Finding Projects by Category: Every repository can be tagged with topics -- keywords like accessibility, screen-reader, wcag, python, machine-learning. The next useful detail is this: Topics are how maintainers categorise their work so others can discover it.

      -

      Alex: Keep the teaching thread moving. Here is the plain-English version of Browsing topics. Click any topic tag on a repository page to see all repos tagged with that topic.

      +

      Jamie: Let's pause on Switching Profiles. What should a learner take away from it?

      +

      Alex: Start with Switching Profiles: The active profile name appears in the VS Code title bar and Status Bar so you always know which configuration is active.

      +

      Alex: Keep the teaching thread moving. Here is the plain-English version of Workshop Profile Recommendations. Create these profiles before the workshop. It is like learning a transit route. The names of the stops matter because they tell you whether you are still going the right direction.

      +

      Jamie: Let's pause on Exporting and Sharing Profiles. What should a learner take away from it?

      +

      Alex: This is where Exporting and Sharing Profiles becomes real: profiles can be exported and shared. That matters in practice: To import: Ctrl+Shift+P then Profiles: Import Profile and paste the gist URL or select the file.

      +

      Alex: First, ctrl+Shift+P then type Profiles: Export Profile. Then, choose what to include (settings, extensions, etc.). After that, export as a GitHub gist (shareable link) or a local file. Finally, share the link or file with others. It is a checklist, but a meaningful one: every item creates evidence that the next step is safe.

      -

      Jamie: What is the teaching move inside GitHub CLI?

      -

      Alex: Treat examples as spoken recipes, not decorations. You may hear something like Search for repos with a specific topic; gh search repos --topic accessibility --limit 20; gh search repos --topic screen-reader --stars " 50"; Add a topic to your own repository; gh api repos/owner/repo/topics --method PUT --field names[]="accessibility". Read the command, understand what it changes, then run it only when the repository state matches the lesson.

      -

      Alex: Keep the teaching thread moving. Keep the learner anchored in 8. GitHub Lists -- Organizing Your Stars. Lists let you group your starred repositories into named collections -- like playlists for code. This is the part to say slowly: Instead of one big pile of stars, you can have "Accessibility Tools," "Learning Resources," "Projects I Contribute To," etc. A good GitHub workflow is like a well-run meeting: everyone knows the topic, the next action, and who has the floor.

      -

      Jamie: Let's pause on Creating a list. What should a learner take away from it?

      -

      Alex: Start with Creating a list. There is something to understand, something to try, and something that proves the try worked.

      -

      Alex: First, go to your stars: github.com/username?tab=stars. Then, select "Create list" (top right of the stars page). After that, give it a name and optional description. Finally, select "Create". The rhythm is simple: orient, act, verify, then continue.

      -

      Jamie: Before we leave Creating a list, what is the practical point?

      -

      Alex: First, on a repo page, click the dropdown arrow next to the Star button. Then, select "Create a list" or add to an existing list. Think of it as a rail line: each stop confirms you are still on the right route before the next one.

      +

      Alex: Keep the teaching thread moving. Keep the learner anchored in Profiles and Settings Sync. Profiles sync across machines through Settings Sync. This is the part to say slowly: 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.

      +

      Jamie: Let's pause on Learning Cards: Profiles. What should a learner take away from it?

      +

      Alex: Start with Learning Cards: Profiles. There is something to understand, something to try, and something that proves the try worked.

      +

      Alex: The practical takeaway is this. 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. 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.

      +

      Alex: Keep the teaching thread moving. Start with 10. The Settings Editor: The Settings Editor is where you customize VS Code. The next useful detail is this: There are two views: the graphical settings UI and the raw settings.json file. Think of it like entering a new building: first you find the lobby, then the room, then the door you actually need.

      -

      Alex: Keep the teaching thread moving. Start with Adding repos to lists. There is something to understand, something to try, and something that proves the try worked.

      -

      Alex: The practical takeaway is this. From any repo page: Star dropdown → check the list name. From your stars page: click the list icon on any starred repo row.

      -

      Jamie: Let's pause on Viewing and sharing lists. What should a learner take away from it?

      -

      Alex: Here is the plain-English version of Viewing and sharing lists. Your lists are public at github.com/username?tab=stars -- anyone can browse them. Put another way, this is useful for sharing curated resources with your community.

      -

      Jamie: If someone only remembers one thing from GitHub CLI, what should it be?

      -

      Alex: Treat examples as spoken recipes, not decorations. You may hear something like Lists are managed through the GitHub web interface only; You can view stars via CLI:; gh api user/starred --jq '.[] {name.full name, description.description}' head -20. Read the command, understand what it changes, then run it only when the repository state matches the lesson.

      +

      Jamie: Let's pause on Navigating the Settings Editor. What should a learner take away from it?

      +

      Alex: Here is the plain-English version of Navigating the Settings Editor. The graphical Settings UI has a search box at the top. Put another way, type any keyword and the settings list filters instantly.

      +

      Alex: Keep the teaching thread moving. Start with Learning Cards: Settings Editor. There is something to understand, something to try, and something that proves the try worked.

      +

      Alex: The practical takeaway is this. 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. 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).

      +

      Jamie: Let's pause on 11. The Keyboard Shortcuts Editor. What should a learner take away from it?

      +

      Alex: Keep the learner anchored in 11. The Keyboard Shortcuts Editor. The Keyboard Shortcuts Editor lets you view, search, and customize every keyboard shortcut in VS Code.

      -

      Jamie: Let's pause on 9. Finding Accessible and Inclusive Projects. What should a learner take away from it?

      -

      Alex: Keep the learner anchored in 9. Finding Accessible and Inclusive Projects. If you're specifically looking for projects that welcome contributors with disabilities, or that focus on accessibility work, here are the best ways to find them.

      -

      Jamie: Let's pause on Search strategies. What should a learner take away from it?

      -

      Alex: Start with Search strategies. There is something to understand, something to try, and something that proves the try worked.

      -

      Alex: The practical takeaway is this. github.com/topics/accessibility. github.com/topics/wcag. github.com/topics/screen-reader.

      -

      Alex: Treat examples as spoken recipes, not decorations. You may hear something like Search for accessibility-focused repos; gh search repos "accessibility" --topic a11y --stars " 100"; Find repos with good first issues in accessibility; gh search issues "accessibility" --label "good first issue" --state open; Find issues tagged both. Read the command, understand what it changes, then run it only when the repository state matches the lesson.

      -

      Jamie: Let's pause on Organisations to follow. What should a learner take away from it?

      -

      Alex: Start with Organisations to follow: GitHub organisations are collections of repos grouped by a team or company. The next useful detail is this: You can follow an org to get notified of their public activity.

      -

      Alex: The practical takeaway is this. github.com/Community-Access -- the organisation behind this workshop. Search for org:github accessibility to find GitHub's own accessibility work. Many assistive technology companies have open source components on GitHub -- search for your AT provider.

      -
      -

      Alex: Keep the teaching thread moving. Here is the plain-English version of Looking at who your community follows. If you follow someone doing accessibility work, browse their stars and their following list -- this is one of the fastest ways to discover the accessibility community on GitHub. It is like learning a transit route. The names of the stops matter because they tell you whether you are still going the right direction.

      -

      Jamie: Let's pause on 10. Building Your Own Presence. What should a learner take away from it?

      -

      Alex: This is where 10. Building Your Own Presence becomes real: being visible on GitHub matters when you want to collaborate with others, get hired, or establish yourself as a contributor.

      -

      Alex: Keep the teaching thread moving. Keep the learner anchored in Your contribution graph. The green grid on your profile shows your public contribution activity over the past year. This is the part to say slowly: Contributions to private repos only appear as grey squares unless the repo is made public later.

      -

      Alex: The practical takeaway is this. Push commits to a public repo. Open, comment on, or close issues or PRs in a public repo. Review a PR in a public repo.

      -
      -

      Jamie: Let's pause on Pinning repositories. What should a learner take away from it?

      -

      Alex: The reason Pinning repositories matters is that pin up to 6 repositories (your own or repos you've contributed to) on your profile.

      -

      Alex: First, go to your profile (github.com/username). Then, select "Customize your pins" above the pinned repos section. After that, check up to 6 repos to pin -- prioritise your best work and most active contributions. The rhythm is simple: orient, act, verify, then continue.

      -

      Alex: Keep the teaching thread moving. Start with Your profile README: Create a special repository named exactly the same as your username (github.com/username/username) and its README.md will appear at the top of your profile page. The next useful detail is this: This is your chance to introduce yourself, list your skills, and share what you're working on. Think of it like entering a new building: first you find the lobby, then the room, then the door you actually need.

      -

      Jamie: Let's pause on Activity tips. What should a learner take away from it?

      -

      Alex: Start with Activity tips. There is something to understand, something to try, and something that proves the try worked.

      -

      Alex: The practical takeaway is this. Comment thoughtfully on issues -- even "I can reproduce this on Windows 11 with NVDA" is a valued contribution that shows on your profile. Star generously -- it signals your interests and others see it in their feeds. Follow people in your area -- they often follow back, growing your network organically.

      -
      -

      Jamie: Let's pause on 11. The GitHub CLI for Social Features. What should a learner take away from it?

      -

      Alex: Start with 11. The GitHub CLI for Social Features. There is something to understand, something to try, and something that proves the try worked.

      -

      Alex: Treat examples as spoken recipes, not decorations. You may hear something like --- Following ---; gh api user/following/username --method PUT Follow someone; gh api user/following/username --method DELETE Unfollow; gh api user/following --jq '.[].login' List who you follow; gh api user/followers --jq '.[].login' List your followers; ---. Read the command, understand what it changes, then run it only when the repository state matches the lesson.

      -

      Jamie: Let's pause on Following a user. What should a learner take away from it?

      -

      Alex: Start with Following a user. There is something to understand, something to try, and something that proves the try worked.

      -

      Alex: First, navigate to github.com/username. Then, press H to jump through headings to find the user's name at the top. After that, tab forward -- the Follow/Following button is within the first few interactive elements after the avatar/bio area. Finally, press Enter or Space to follow; the button label updates to "Following [username]". It is like walking a hallway with named doors: read the sign, enter the right room, then confirm where you landed.

      -

      Jamie: Let's pause on Starring a repository. What should a learner take away from it?

      -

      Alex: Start with Starring a repository. There is something to understand, something to try, and something that proves the try worked.

      -

      Alex: First, navigate to any repository page. Then, the Star button is in the repository header, near the Fork button. After that, press B (NVDA/JAWS) to navigate by button, or Tab through the header. Finally, the button is announced as "Star this repository" or "Unstar this repository". The rhythm is simple: orient, act, verify, then continue.

      -

      Jamie: Before we leave Starring a repository, what is the practical point?

      -

      Alex: First, after starring, the button label changes and a count updates. Think of it as a rail line: each stop confirms you are still on the right route before the next one.

      -
      -

      Jamie: Let's pause on Browsing your stars. What should a learner take away from it?

      -

      Alex: Start with Browsing your stars. There is something to understand, something to try, and something that proves the try worked.

      -

      Alex: First, go to github.com/username?tab=stars. Then, jump to main landmark to skip navigation. After that, each starred repo is a heading (H3) with a link -- navigate with H or 3. Finally, below each heading: description text, language, star count, and list controls. Think of it as a rail line: each stop confirms you are still on the right route before the next one.

      -

      Jamie: Let's pause on Exploring topics. What should a learner take away from it?

      -

      Alex: Start with Exploring topics. There is something to understand, something to try, and something that proves the try worked.

      -

      Alex: First, go to github.com/topics/accessibility (or any topic). Then, jump to main landmark. After that, repos are listed as article regions with H3 headings. Finally, each entry has: repo name (link), owner, description, language, star count, and a Star button. Treat it like a recipe: do not add the next ingredient until the previous one is actually in the bowl.

      -

      Jamie: Let's pause on GitHub Explore and Trending. What should a learner take away from it?

      -

      Alex: This is where GitHub Explore and Trending becomes real: next: Appendix U: Discussions and Gists Back: Appendix S: Releases and Insights Teaching chapter: Chapter 08: Open Source Culture.

      -

      Alex: First, go to github.com/explore or github.com/trending. Then, use H to navigate between sections and repo entries. After that, trending page has language and time period filter dropdowns near the top -- Tab to find them. Finally, each trending repo row has: rank position, repo name (link), description, star count, and "Stars today" count. It is a checklist, but a meaningful one: every item creates evidence that the next step is safe.

      +

      Alex: Keep the teaching thread moving. The reason Searching for Shortcuts matters is that the editor has a search box that supports. The interface gets friendlier when it stops being a wall of controls and starts being a set of named places.

      +

      Alex: The practical takeaway is this. 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.

      +

      Jamie: Let's pause on Customizing a Shortcut. What should a learner take away from it?

      +

      Alex: Start with Customizing a Shortcut. There is something to understand, something to try, and something that proves the try worked.

      +

      Alex: First, find the command in the list. Then, double-click the keybinding column (or press Enter on the row, then Enter again on the keybinding). After that, press your desired key combination. Finally, press Enter to confirm. Think of it as a rail line: each stop confirms you are still on the right route before the next one.

      +

      Alex: Keep the teaching thread moving. Here is the plain-English version of Learning Cards: Keyboard Shortcuts Editor. Next: Chapter 12: VS Code Accessibility Back: Chapter 10: Notifications and Day 1 Close Related appendices: Appendix G: VS Code Reference Appendix B: Screen Reader Cheat Sheet.

      +

      Alex: The practical takeaway is this. 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. search for accessibility to find all accessibility-related shortcuts at once. 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.

      Jamie: What should people carry with them after this?

      Alex: Carry the map. Know what page or tool you are in, know which action you are taking, and know what confirmation should follow. If the confirmation is missing, pause. That pause is not wasted time; it is professional judgment.

      Jamie: That is a better way to say it than just follow the steps.

      -

      Alex: Right. Steps matter, but understanding wins. That is episode 35. Next in the series is episode 36, where we keep building the same contributor muscles.

      +

      Alex: Right. Steps matter, but understanding wins. That is episode 11. Next in the series is episode 12, where we keep building the same contributor muscles.

      -

      Episode 36: Organizations and Templates

      -

      GitHub Organizations, repository templates, visibility, and archiving.

      -

      Based on: Appendix T: Organizations and Templates

      +

      31. Episode 45: VS Code Accessibility Deep Dive

      +

      Keyboard navigation, accessible views, terminal access, signals, speech, and Copilot accessibility in VS Code.

      +

      Based on: Chapter 12: VS Code Accessibility Deep Dive

      Audio and transcript are being regenerated for this episode.

      -Read Transcript - Episode 36: Organizations and Templates +Read Transcript - Episode 45: VS Code Accessibility Deep Dive

      Transcript

      -

      Alex: Welcome to Git Going with GitHub, episode 36: Organizations and Templates. I am Alex. Today we are going to make Organizations and Templates something you can explain, practice, and recover from when the interface surprises you.

      -

      Jamie: And I am Jamie. I will be the voice of the learner who is willing to ask, what is this for, where am I, and how do I know I did it right?

      +

      Alex: Welcome back to Git Going with GitHub. This is episode 45: VS Code Accessibility Deep Dive. I am Alex, and today we are turning VS Code Accessibility Deep Dive from a list of instructions into a working mental model.

      +

      Jamie: And I am Jamie. I will stop us whenever the instructions sound simple on paper but might feel different with a keyboard and screen reader.

      -

      Alex: The big idea today: GitHub Organizations, repository templates, visibility, and archiving. We will name the concept, explain why it matters, practice the move, and point out the checks that tell you the work is real.

      -

      Jamie: So the episode should work even if someone has not read the chapter yet.

      -

      Alex: Exactly. The transcript has to stand on its own. It can point toward practice, but it should teach the concept right here in the conversation.

      +

      Alex: Keyboard navigation, accessible views, terminal access, signals, speech, and Copilot accessibility in VS Code. That is the surface description. Underneath it, we are building judgment: where to focus, what to ignore, and how to verify the result.

      +

      Jamie: So we are not using the audio as a shortcut around learning. We are using it to make the learning easier to enter.

      +

      Alex: Yes. A good audio lesson gives someone enough context to try the work with confidence, even before they open the written material.

      Jamie: Okay, set the room for us. What are we walking into?

      -

      Alex: Start with Building Your Community Presence on GitHub: This appendix covers three community-facing GitHub features: your profile README (how the world sees you), GitHub Sponsors (financially supporting the people whose work you depend on), and GitHub Wikis (community-editable documentation inside a repository).

      -

      Alex: A solid pull request habit is to separate three questions: what changed, why it changed, and what still needs review. That keeps the conversation useful instead of noisy.

      -

      Alex: The next layer is this. Start with Learning Cards: Profiles, Sponsors, and Wikis. There is something to understand, something to try, and something that proves the try worked.

      -

      Alex: The practical anchors are these. Your profile README is announced as regular page content when someone visits your profile -- use headings for structure so visitors can navigate with H. The Sponsor button on a profile or repo is a standard button element -- press B to cycle through buttons until you hear "Sponsor". Wiki pages are read in browse mode like any other GitHub Markdown page -- use heading navigation to jump between sections. Profile READMEs respect GitHub's dark and light themes -- test yours in both modes to confirm text remains readable. The Sponsor button uses a heart icon with a pink/magenta accent -- look near the repo name or profile photo area. Wiki sidebar navigation appears on the right side of the page with links to all wiki pages.

      +

      Alex: Start with Accessibility Features for Power Users: Challenge 10: Go Local depends on the accessibility features covered in this chapter. The next useful detail is this: Configure these settings before your first local commit.

      +

      Alex: The next layer is this. Here is the plain-English version of Panels and Areas. Mac users: Substitute Cmd for Ctrl and Option for Alt in all shortcuts below. It is like learning a transit route. The names of the stops matter because they tell you whether you are still going the right direction.

      Jamie: What is the one idea that makes the next few steps less mysterious?

      -

      Alex: This is where The Special Profile README becomes real: GitHub has a hidden feature: if you create a repository named exactly your-username/your-username (e.g., janesmith/janesmith), the README in that repo appears on your GitHub profile page. That matters in practice: It's a custom introduction visible to anyone who visits your profile.

      +

      Alex: This is where Find in Current File (Ctrl+F) becomes real: when the Find widget opens, three toggle buttons refine what matches.

      -

      Jamie: Turn that into a path someone can follow.

      -

      Alex: Start with Creating Your Profile README. There is something to understand, something to try, and something that proves the try worked.

      -

      Alex: First, create a new repository. Then, name it exactly your-username (match your GitHub username exactly, case-sensitive). After that, make it public. Finally, initialize with a README. It is like walking a hallway with named doors: read the sign, enter the right room, then confirm where you landed.

      -

      Jamie: What is the ordered workflow?

      -

      Alex: First, edit the README with whatever you want to show on your profile. The rhythm is simple: orient, act, verify, then continue.

      +

      Alex: Now bring the learner back to the room. Keep the learner anchored in Screen reader interactions inside the Find widget. Replace (Ctrl+H): Opens the Find widget with a second input for the replacement text.

      +

      Alex: For a learner, the useful signals are these. 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. Ctrl+Shift+1 - replace the current match. Ctrl+Alt+Enter - replace all matches at once.

      +

      Alex: A solid navigation habit is to prove where you are before activating controls. Headings, landmarks, and the address bar are not trivia; they are your map.

      Jamie: What would you say to someone who is already bracing for this to be too much?

      -

      Alex: Start with What to include. There is something to understand, something to try, and something that proves the try worked.

      -

      Alex: The parts worth keeping in working memory are these. Introduction: Who you are, what you work on. Current focus: What projects or technologies you're learning. Skills: Languages, frameworks, tools (optional). How to reach you: Email, LinkedIn, personal site. Fun facts: Hobbies, interests (optional-keeps it human).

      +

      Alex: The reason Global Search Across the Workspace (Ctrl+Shift+F) matters is that the global Search panel has a rich filtering system - all keyboard-accessible.

      Alex: The useful habit is simple: orient first, act second, verify third. That pause before acting is part of the work.

      -

      Jamie: How do you keep commands from becoming magic words?

      -

      Alex: Start with Example profile README. There is something to understand, something to try, and something that proves the try worked.

      -

      Alex: Treat examples as spoken recipes, not decorations. You may hear something like Hi, I'm Jane Smith; I'm an accessibility advocate and open source contributor focused on making the web more inclusive.; Current focus; - Contributing to NVDA documentation; - Building accessible React components; - Learning TypeScript; Skills; - JavaScript,. Read the command, understand what it changes, then run it only when the repository state matches the lesson.

      +

      Jamie: Give me the sequence, because order matters here.

      +

      Alex: Start with Type-to-Filter in Tree Views: In the Explorer file tree and the Source Control changes list, type characters to narrow visible items. Think of it like entering a new building: first you find the lobby, then the room, then the door you actually need.

      +

      Alex: First, focus the Explorer (Ctrl+Shift+E). Then, start typing a filename - a filter input appears at the bottom of the tree. After that, the tree instantly narrows to matching files. Finally, press Escape to clear the filter and restore full view. Think of it as a rail line: each stop confirms you are still on the right route before the next one.

      Jamie: If I am listening before the workshop starts, what should settle in my mind first?

      -

      Alex: Here is the plain-English version of Profile README Best Practices. Keep it concise - visitors skim, not read Update occasionally - a README from 2019 looks stale Be authentic - people connect with real humans, not buzzwords Include links - make it easy to learn more or get in touch. Put another way, avoid excessive badges - 50 skill badges is visual clutter and screen reader noise Skip auto-generated stats - "commits per day" widgets are often inaccessible Don't overthink it - a simple paragraph is better than nothing.

      -

      Alex: This is where the talk moves from concept to action. Start with Screen Reader Considerations. There is something to understand, something to try, and something that proves the try worked.

      -

      Alex: The room should hear these as checkpoints. Use headings ( ) for structure. Provide alt text for any images. Avoid ASCII art - screen readers read it character by character (annoying). Test your README with a screen reader before publishing.

      -

      Alex: A solid navigation habit is to prove where you are before activating controls. Headings, landmarks, and the address bar are not trivia; they are your map.

      +

      Alex: Here is the plain-English version of Go to Symbol with Inline Filtering (Ctrl+Shift+O). In any Markdown file, Ctrl+Shift+O opens a symbol picker populated by every heading. Put another way, type to narrow the list, then press Enter to jump.

      +

      Alex: This is where the talk moves from concept to action. Start with Learning Cards: Keyboard Navigation and Find. There is something to understand, something to try, and something that proves the try worked.

      +

      Alex: The room should hear these as checkpoints. 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. 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.

      Jamie: Where do you want a learner to place their attention here?

      -

      Alex: Start with Pinned repositories (up to 6). There is something to understand, something to try, and something that proves the try worked.

      -

      Alex: These are the details that keep the idea from floating away. Highlight your best work on your profile. Navigate to your profile → Select "Customize your pins". Choose which repos appear first.

      +

      Alex: Keep the learner anchored in 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.

      +

      Alex: A solid pull request habit is to separate three questions: what changed, why it changed, and what still needs review. That keeps the conversation useful instead of noisy.

      -

      Alex: Before the learner moves on. Start with Contribution graph. There is something to understand, something to try, and something that proves the try worked.

      -

      Alex: That becomes easier when you listen for these cues. Shows your GitHub activity over the past year. Green squares indicate days with commits, PRs, issues, etc. Cannot be customized but reflects consistent contribution.

      +

      Alex: Before the learner moves on. Start with Opening the Problems Panel. There is something to understand, something to try, and something that proves the try worked.

      +

      Alex: That becomes easier when you listen for these cues. 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).

      Jamie: Give me the version that sounds like an instructor, not a manual.

      -

      Alex: Start with Status. There is something to understand, something to try, and something that proves the try worked.

      -

      Alex: A few details make that real. Set a temporary status message (e.g., "On vacation until March 15"). Navigate to your profile → Select the smile icon → Set status.

      -

      Alex: Hold that next to this. Here is the plain-English version of What Is GitHub Sponsors? GitHub Sponsors lets you financially support developers and projects you depend on.

      -
      -

      Jamie: Let's pause on How it works. What should a learner take away from it?

      -

      Alex: Start with How it works. There is something to understand, something to try, and something that proves the try worked.

      -

      Alex: That shows up in the workshop in a few specific ways. Developers/projects create a Sponsors profile. You choose a monthly sponsorship tier ($5, $10, $25/month, etc.). Your payment goes directly to the developer (GitHub takes no fees).

      -

      Alex: That connects to another useful point. Start with Why Sponsor? There is something to understand, something to try, and something that proves the try worked.

      -

      Alex: For a learner, the useful signals are these. Sustainability: Many open source maintainers volunteer their time. Sponsorships help them keep projects alive. Gratitude: If a project saved you hours of work, sponsorship is a way to say thanks. Priority support: Some maintainers offer sponsor-only Discord access, early releases, or prioritized bug fixes.

      -

      Jamie: Give me the sequence, because order matters here.

      -

      Alex: Start with How to Sponsor. There is something to understand, something to try, and something that proves the try worked.

      -

      Alex: First, navigate to a user or repository's GitHub page. Then, look for the "Sponsor" button (heart icon). After that, choose a tier or custom amount. Finally, select payment method (credit card or PayPal). The rhythm is simple: orient, act, verify, then continue.

      -

      Jamie: How would you walk the room through that step by step?

      -

      Alex: First, GitHub sends a receipt; your sponsorship appears on your profile (optionally publicly). Think of it as a rail line: each stop confirms you are still on the right route before the next one.

      -
      -

      Alex: Here is the practical turn. Start with Screen reader navigation. There is something to understand, something to try, and something that proves the try worked.

      -

      Alex: On the ground, that means a few things. The Sponsor button appears near the profile photo or repo name. Press B to cycle through buttons on the page until you hear "Sponsor".

      -

      Jamie: What does the learner do first, second, and then after that?

      -

      Alex: Here is the plain-English version of Can I Receive Sponsorships? If you maintain an open source project or contribute regularly. Put another way, many accessibility advocates successfully use Sponsors to fund their work improving assistive technology and inclusive design.

      -

      Alex: First, navigate to github.com/sponsors. Then, select "Join the waitlist" or "Set up sponsors". After that, connect a payment method (Stripe or bank account). Finally, create sponsor tiers with descriptions. Treat it like a recipe: do not add the next ingredient until the previous one is actually in the bowl.

      -

      Jamie: Let's pause on Can I Receive Sponsorships? What should a learner take away from it?

      -

      Alex: First, promote your Sponsors page to your audience. It is a checklist, but a meaningful one: every item creates evidence that the next step is safe.

      -

      Alex: Keep the thread going. This is where What Is a GitHub Wiki? becomes real: every repository can have a wiki - a space for documentation separate from the code. That matters in practice: It's lightweight and Markdown-based. The workshop is closer to rehearsal than lecture. You hear the move, try the move, and then check what changed.

      +

      Alex: Start with Understanding Problem Entries. There is something to understand, something to try, and something that proves the try worked.

      +

      Alex: A few details make that real. 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.

      +

      Alex: Hold that next to this. Start with Learning Cards: Problems Panel. There is something to understand, something to try, and something that proves the try worked.

      +

      Alex: The practical anchors are these. 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. Problems are color-coded: red for errors, yellow for warnings, blue for info.

      -

      Jamie: Let's pause on When to use a wiki. What should a learner take away from it?

      -

      Alex: Start with When to use a wiki. There is something to understand, something to try, and something that proves the try worked.

      -

      Alex: Here is what that changes in practice. Multi-page documentation (tutorials, guides, FAQs). Community-editable docs (wikis can be editable by anyone). Knowledge that doesn't belong in README (too long, too specific).

      -

      Alex: Another way to ground it. Start with When NOT to use a wiki. There is something to understand, something to try, and something that proves the try worked.

      -

      Alex: The practical takeaway is this. Your project already uses GitHub Pages or external docs. Documentation needs to be version-controlled with code (wikis are separate Git repos). You want full control (wikis are less customizable than Pages).

      -

      Jamie: Let's pause on Accessing a Repo's Wiki. What should a learner take away from it?

      -

      Alex: Start with Accessing a Repo's Wiki. There is something to understand, something to try, and something that proves the try worked.

      -

      Alex: First, navigate to the repository. Then, select the "Wiki" tab. After that, if no wiki exists, you'll see "Create the first page". Think of it as a rail line: each stop confirms you are still on the right route before the next one.

      +

      Jamie: Let's pause on 14. The Terminal. What should a learner take away from it?

      +

      Alex: This is where 14. The Terminal becomes real: VS Code includes a fully featured integrated terminal. That matters in practice: You can run shell commands, Git operations, and scripts without leaving the editor.

      +

      Alex: That connects to another useful point. Keep the learner anchored in Terminal Shell Integration. VS Code's shell integration enhances the terminal. This is the part to say slowly: Enable Terminal IntelliSense: Settings (Ctrl+,) then search terminal.integrated.suggest.enabled then set to on. A good GitHub workflow is like a well-run meeting: everyone knows the topic, the next action, and who has the floor.

      +

      Alex: The parts worth keeping in working memory are these. 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.

      +

      Jamie: Let's pause on Learning Cards: Terminal. What should a learner take away from it?

      +

      Alex: Start with Learning Cards: Terminal. There is something to understand, something to try, and something that proves the try worked.

      +

      Alex: On the ground, that means a few things. 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. VS Code enforces a minimum contrast ratio (4.5:1 by default) for terminal text.

      -

      Jamie: Let's pause on Creating Wiki Pages. What should a learner take away from it?

      -

      Alex: Here is the plain-English version of Creating Wiki Pages. Wiki pages automatically appear in a sidebar for navigation. It is like learning a transit route. The names of the stops matter because they tell you whether you are still going the right direction.

      -

      Alex: First, go to the Wiki tab. Then, select "New page". After that, add a title and content (Markdown). Finally, select "Save". Treat it like a recipe: do not add the next ingredient until the previous one is actually in the bowl.

      -

      Jamie: Let's pause on Wiki Accessibility. What should a learner take away from it?

      -

      Alex: This is where Wiki Accessibility becomes real: return to: Resources Appendix S - Organizations and Templates Appendix G - GitHub Discussions Appendix T - Contributing to Open Source Appendix A - Glossary.

      -

      Alex: The practical takeaway is this. GitHub's wiki editor is the same as the issue/PR comment editor. All Markdown features work (headings, lists, links, code blocks). Use proper heading hierarchy (, ) for screen reader navigation. Link between wiki pages: [[Page Title]]. Screen reader caveat: Wiki pages are a separate Git repository. Any changes pushed directly to the wiki's git remote are not tracked by the main repository's branch protection - meaning no PR review process applies. Treat wikis as community-editable.

      -

      Alex: Now bring the learner back to the room. Start with Learning Cards: Organizations and Templates. There is something to understand, something to try, and something that proves the try worked.

      -

      Alex: The practical takeaway is this. The "Use this template" button is near the "Code" button at the top of a template repository -- press B to navigate buttons until you hear it. Organization profiles list repositories and members under heading sections -- use H to jump between People, Repositories, and Projects. Repository visibility (Public, Private, Internal) is announced as a badge near the repository name heading. Template repositories show a green "Use this template" button prominently near the top -- it replaces or sits alongside the Fork button. Organization pages use the same layout as personal profiles but with team-oriented sections. Archived repositories display a yellow warning banner across the top of the page.

      +

      Alex: Here is the practical turn. Start with 15. Copilot Chat Window: The Copilot Chat window (Ctrl+Shift+I) is your conversational AI assistant within VS Code. The next useful detail is this: It can answer questions, generate code, explain code, fix problems, and help with documentation.

      +

      Jamie: Let's pause on Chat Modes. What should a learner take away from it?

      +

      Alex: Here is the plain-English version of Chat Modes. Switch modes using the mode picker at the top of the Chat view, or use keyboard shortcuts.

      +

      Alex: Here is what that changes in practice. workbench.action.chat.openAsk - Ask mode. workbench.action.chat.openEdit - Edit mode. workbench.action.chat.openAgent - Agent mode.

      +

      Alex: Keep the thread going. This is where Using Chat Participants becomes real: type @ in the chat input to see available participants. The workshop is closer to rehearsal than lecture. You hear the move, try the move, and then check what changed.

      +

      Alex: These are the details that keep the idea from floating away. @workspace - Ask questions about your entire codebase. @vscode - Ask about VS Code settings and features. @terminal - Run commands or explain terminal output.

      -

      Jamie: How should someone choose between those options?

      -

      Alex: The reason Template vs. Fork - Which One? matters is that these are two very different actions that both appear near the "Code" button. That gives the learner a simple foothold: GitHub Skills courses use "Use this template" - you start fresh with the course scaffold but your copy has no upstream connection.

      -

      Alex: Use the comparison to make a decision, not to recite a table. The main contrasts are: Use when. means What you get. Contributing back to the original project means Full git history; your changes can be PRed upstream. Use this template means Starting a new project based on the structure means Clean git history; no connection to the original repo.

      -

      Jamie: Let's pause on Creating a Template Repository. What should a learner take away from it?

      -

      Alex: Start with Creating a Template Repository: Maintainers can mark any repository as a template. Think of it like entering a new building: first you find the lobby, then the room, then the door you actually need.

      -

      Alex: First, navigate to the repository's Settings tab. Then, scroll to the "General" section → find the "Template repository" checkbox. After that, check it and save. Finally, the repository now shows a "Use this template" button instead of (or alongside) "Fork". Think of it as a rail line: each stop confirms you are still on the right route before the next one.

      -

      Jamie: Let's pause on Using a Template Repository. What should a learner take away from it?

      -

      Alex: Start with Using a Template Repository. There is something to understand, something to try, and something that proves the try worked.

      -

      Alex: First, navigate to the template repository. Then, select "Use this template" button (near the top, next to "Code"). After that, select "Create a new repository". Finally, name your new repository, choose visibility, and confirm. Treat it like a recipe: do not add the next ingredient until the previous one is actually in the bowl.

      -

      Jamie: Before we leave Using a Template Repository, what is the practical point?

      -

      Alex: First, GitHub creates a new repository with the template's files but no commit history. It is a checklist, but a meaningful one: every item creates evidence that the next step is safe.

      +

      Jamie: Let's pause on Learning Cards: Copilot Chat. What should a learner take away from it?

      +

      Alex: Start with Learning Cards: Copilot Chat. There is something to understand, something to try, and something that proves the try worked.

      +

      Alex: That shows up in the workshop in a few specific ways. 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. The Chat view appears in the sidebar and respects your zoom level and font settings.

      +

      Alex: Another way to ground it. The reason Agent Mode: Question Carousel and Terminal Focus matters is that 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. That gives the learner a simple foothold: the carousel shows what the terminal is asking and lets you respond without switching focus to the terminal manually.

      +

      Jamie: What do you want them to do when the plan breaks?

      +

      Alex: Start with 16. Accessible Help, Accessible View, and Accessible Diff: See also: Appendix G: VS Code Reference has a complete keyboard shortcut reference for all VS Code accessibility features. The next useful detail is this: 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.

      +

      Alex: This is the part worth saying out loud. Here is the plain-English version of 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. Put another way, accessible Help surfaces those commands in a plain-text, fully readable dialog, tailored to exactly where your focus is right now. It is like learning a transit route. The names of the stops matter because they tell you whether you are still going the right direction.

      +

      Jamie: How should someone ask for help in a way that gets them unstuck faster?

      +

      Alex: This is where How to open Accessible Help becomes real: the dialog is announced with a heading and a complete list of keyboard shortcuts for that specific widget. That matters in practice: Press Escape to dismiss and return focus to where you were.

      Jamie: What should happen before anyone copies and runs it?

      -

      Alex: Start with Screen reader path. There is something to understand, something to try, and something that proves the try worked.

      -

      Alex: Treat examples as spoken recipes, not decorations. You may hear something like B → navigate buttons → find "Use this template" → Enter; ↓ → "Create a new repository" from the dropdown → Enter. Read the command, understand what it changes, then run it only when the repository state matches the lesson.

      -

      Jamie: Let's pause on What Is an Organization? What should a learner take away from it?

      -

      Alex: Keep the learner anchored in What Is an Organization? A GitHub organization is an account that multiple people share. This is the part to say slowly: Instead of github.com/username/repo, organization repos live at github.com/org-name/repo.

      -

      Jamie: Let's pause on Joining an Organization. What should a learner take away from it?

      -

      Alex: The reason Joining an Organization matters is that maintainers can invite you to join. That gives the learner a simple foothold: you can also be a public contributor to an org repo without being a member - you fork the repo and submit PRs without needing an invitation. The interface gets friendlier when it stops being a wall of controls and starts being a set of named places.

      -

      Alex: First, you receive an email + GitHub notification. Then, navigate to github.com/settings/organizations to accept. After that, or click the link in the invitation email. The rhythm is simple: orient, act, verify, then continue.

      +

      Alex: Keep the learner anchored in Example output when pressing Alt+H in the editor. Use Accessible Help as your first action whenever you land somewhere new in VS Code.

      +

      Alex: Treat examples as spoken recipes, not decorations. You may hear something like 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. Read the command, understand what it changes, then run it only when the repository state matches the lesson.

      -

      Jamie: Let's pause on Organization Membership Visibility. What should a learner take away from it?

      -

      Alex: Start with Organization Membership Visibility. There is something to understand, something to try, and something that proves the try worked.

      -

      Alex: The practical takeaway is this. By default, your org membership is private (only you and org owners can see it). You can set it to public in your organization membership settings. Public membership appears on your GitHub profile under "Organizations". For community-access: if you become a member, set your membership public to show your contribution publicly on your profile.

      -

      Alex: This is the part worth saying out loud. Here is the plain-English version of Teams Inside Organizations. Organizations can create teams (e.g., @community-access/accessibility-reviewers). Put another way, when you see a team mentioned in a PR or issue, that @mention notifies everyone on that team.

      -

      Jamie: Let's pause on Navigating an Organization Profile Page. What should a learner take away from it?

      -

      Alex: This is where Navigating an Organization Profile Page becomes real: organization-level Projects (like the community-access project board) appear in the org's Projects tab, not inside any single repository.

      +

      Jamie: Let's pause on 16.2 Accessible View - Reading Dynamic and Streamed Content. What should a learner take away from it?

      +

      Alex: The reason 16.2 Accessible View - Reading Dynamic and Streamed Content matters is that 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.

      +

      Jamie: How would you walk the room through that step by step?

      +

      Alex: Start with Recommended workflow for Copilot Chat. There is something to understand, something to try, and something that proves the try worked.

      +

      Alex: First, type your prompt in the Chat input. Then, wait for the response to finish (NVDA: live region announcements stop; JAWS: typing indicator disappears; VoiceOver: busy state clears). After that, press Alt+F2 - Accessible View opens with the complete response. Finally, navigate with Up/Down Arrow through the response. Think of it as a rail line: each stop confirms you are still on the right route before the next one.

      +

      Jamie: What does the learner do first, second, and then after that?

      +

      Alex: First, press Escape to return to the chat input. Treat it like a recipe: do not add the next ingredient until the previous one is actually in the bowl.

      +

      Jamie: Turn that into a path someone can follow.

      +

      Alex: Start with Recommended workflow for hover documentation. There is something to understand, something to try, and something that proves the try worked.

      +

      Alex: First, navigate to a symbol or link with keyboard. Then, press Ctrl+K I to trigger hover programmatically (no mouse needed). After that, press Alt+F2 to open Accessible View with the full hover content. Finally, press Escape to dismiss. Treat it like a recipe: do not add the next ingredient until the previous one is actually in the bowl.

      -

      Alex: That matters because of the next idea. Keep the learner anchored in Repository Settings - What Contributors Need to Know. You may not have Settings access to most repositories (that requires maintainer role). This is the part to say slowly: But knowing what's there helps you understand why a repository behaves the way it does. A good GitHub workflow is like a well-run meeting: everyone knows the topic, the next action, and who has the floor.

      -

      Jamie: Let's pause on Repository Visibility. What should a learner take away from it?

      -

      Alex: The reason Repository Visibility matters is that the repository's visibility label appears on its page. That gives the learner a simple foothold: screen readers: the visibility badge is usually near the repo name heading (H1).

      -

      Alex: Keep the teaching thread moving. Start with Archived Repositories: When a maintainer archives a repository, it becomes read-only. The next useful detail is this: If you find a repo you planned to contribute to is archived, look for a fork or successor project.

      -

      Alex: The practical takeaway is this. No new issues, PRs, or comments can be created. Existing content is fully preserved and viewable. The UI shows a yellow banner: "This repository has been archived by the owner.". Screen readers: NVDA/JAWS will read this banner when you navigate to the top of the page with Ctrl+Home.

      +

      Alex: That matters because of the next idea. This is where 16.3 Accessible Diff Viewer - Reading Changes Without Visual Scanning becomes real: 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. That matters in practice: For screen reader users, tracking which lines changed and how can be difficult without a structured reading mode.

      +

      Jamie: What should they understand before typing anything?

      +

      Alex: Keep the learner anchored in What the Accessible Diff Viewer announces. For each hunk (a block of related changes), the viewer announces. This is the part to say slowly: This gives you the complete picture of what changed, in reading order, without visual diff scanning.

      +

      Alex: The practical takeaway is this. The hunk number and total hunk count (Hunk 2 of 5). The line range affected. Each line, prefixed with its change type.

      +

      Alex: Treat examples as spoken recipes, not decorations. You may hear something like 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. Read the command, understand what it changes, then run it only when the repository state matches the lesson.

      +

      Alex: Keep the teaching thread moving. Start with Practical uses during this workshop. There is something to understand, something to try, and something that proves the try worked.

      +

      Alex: The practical takeaway is this. 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.

      -

      Jamie: Let's pause on Repository Topics. What should a learner take away from it?

      -

      Alex: Here is the plain-English version of Repository Topics. Topics are keyword tags on a repository (e.g., accessibility, screen-reader, open-source). Put another way, they appear as colored chips on the repository home page and improve discoverability in GitHub search.

      -

      Alex: The practical takeaway is this. As a contributor: Topics tell you what the project is about at a glance. As a maintainer: Add topics in Settings → General → Topics section to improve search ranking. Screen reader: Topics are links in the "About" sidebar section; use B (next button) or Links list to reach them.

      -

      Alex: Keep the teaching thread moving. This is where Default Branch Name becomes real: the default branch is the one all PRs target by default. That matters in practice: Modern projects use main; older projects may use master or another name. The workshop is closer to rehearsal than lecture. You hear the move, try the move, and then check what changed.

      -

      Alex: A solid Git habit is to know which branch you are on, what changed, and what confirmation you expect before you run the next command.

      -

      Jamie: Let's pause on GitHub Is More Than a Code Host -- It's a Community. What should a learner take away from it?

      -

      Alex: Keep the learner anchored in GitHub Is More Than a Code Host -- It's a Community. Who this is for: You have learned the basics of GitHub and want to know how to use it as a social platform -- discovering interesting projects, following developers whose work you admire, and building a presence in the open source community. This is the part to say slowly: This appendix covers the social layer of GitHub that most tutorials skip entirely.

      +

      Jamie: Let's pause on Audio cues for diffs. What should a learner take away from it?

      +

      Alex: Start with 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). The next useful detail is this: You receive change-type information through sound before the line text is announced.

      +

      Alex: Keep the teaching thread moving. Start with Learning Cards: Accessible Help, View, and Diff. There is something to understand, something to try, and something that proves the try worked.

      +

      Alex: The practical takeaway is this. 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. 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.

      +

      Jamie: Let's pause on 17. Accessibility Signals. What should a learner take away from it?

      +

      Alex: This is where 17. Accessibility Signals becomes real: 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. That matters in practice: Signals replaced the older "Audio Cues" system (deprecated since VS Code 1.85) and are significantly more powerful.

      -

      Alex: Keep the teaching thread moving. Start with Learning Cards: Social Features. There is something to understand, something to try, and something that proves the try worked.

      -

      Alex: The practical takeaway is this. The Star button is announced as "Star this repository" or "Unstar this repository" -- press B to find it in the repository header area. The Follow button on a user profile is announced as "Follow [username]" -- Tab forward from the avatar and bio to reach it. On the Explore and Trending pages, each repository entry is a heading with a link -- use H or 3 to jump between entries. Star and Watch buttons sit side by side in the repository header with distinct icons (star and eye) -- both show counts next to them. Your contribution graph uses green intensity to show activity levels -- enable high-contrast theme if the color differences are hard to distinguish. The Trending page lists repositories in a numbered vertical list with star counts and daily gain on the right side.

      -

      Jamie: Let's pause on What a star is. What should a learner take away from it?

      -

      Alex: Start with What a star is: A star is GitHub's version of a bookmark combined with a "like." When you star a repository.

      -

      Alex: The practical takeaway is this. It saves to your starred list at github.com/username?tab=stars -- easy to find later. It signals to the maintainer that their work is valued. It contributes to the project's star count, which helps others discover it. It may appear in your followers' feeds.

      -

      Alex: Keep the teaching thread moving. Here is the plain-English version of Why star count matters to projects. Star counts are a social proof signal -- developers browsing for tools often sort by stars to find well-regarded projects. Put another way, a project going from 10 stars to 1,000 stars can dramatically change how many contributors it attracts. It is like learning a transit route. The names of the stops matter because they tell you whether you are still going the right direction.

      +

      Alex: Keep the teaching thread moving. Keep the learner anchored in How Signals Work: The Dual-Channel Architecture. Every accessibility signal has two independent channels that you control separately. This is the part to say slowly: Each channel accepts one of these values. A good GitHub workflow is like a well-run meeting: everyone knows the topic, the next action, and who has the floor.

      +

      Jamie: What should someone listen for when a lesson offers more than one tool path?

      +

      Alex: The reason Discovering Signals: The Two Essential Commands matters is that 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. That gives the learner a simple foothold: these are the fastest way to configure signals.

      +

      Alex: Keep the teaching thread moving. Start with Volume Control: Control signal volume independently from your system volume. The next useful detail is this: Set this in Settings (Ctrl+,) by searching "signal volume" or add it to settings.json.

      -

      Jamie: Let's pause on GitHub.com. What should a learner take away from it?

      -

      Alex: This is where GitHub.com becomes real: on any repository page, the Star button is in the top-right area of the repository header, next to Fork.

      -

      Alex: The practical takeaway is this. Click Star to star the repository -- the button changes to Starred with a filled star icon. Click the dropdown arrow next to Star to choose a List to organize it into (see Section 8). Click Starred to unstar.

      -

      Alex: Keep the teaching thread moving. Keep the learner anchored in Keyboard shortcut. On a repository page, press g then s to toggle the star.

      -

      Jamie: Let's pause on Screen reader navigation. What should a learner take away from it?

      -

      Alex: Start with Screen reader navigation. There is something to understand, something to try, and something that proves the try worked.

      -

      Alex: The practical takeaway is this. NVDA/JAWS: The Star button is in the page region after the repository title heading. Navigate by button (B) or Tab to find it. It's announced as "Star this repository" or "Unstar this repository.". VoiceOver: VO+Command+J to jump to buttons, or Tab through the header area. The button label changes between "Star" and "Starred.".

      +

      Jamie: Let's pause on Complete Signal Reference. What should a learner take away from it?

      +

      Alex: Here is the plain-English version of Complete Signal Reference. VS Code registers 30+ accessibility signals organized into categories. Put another way, the tables below list every signal, its setting key, the sound it plays, and whether it supports announcements.

      +

      Alex: Keep the teaching thread moving. This is where Editor Signals becomes real: these fire when your cursor moves to a line or position with a specific marker. That matters in practice: Line vs Position signals: The lineHasError signal fires once when your cursor enters the line. The workshop is closer to rehearsal than lecture. You hear the move, try the move, and then check what changed.

      +

      Jamie: Let's pause on Diff Signals. What should a learner take away from it?

      +

      Alex: Keep the learner anchored in Diff Signals. These fire when navigating changes in the diff editor or reviewing pull requests. This is the part to say slowly: These are critical for pull request review.

      -

      Jamie: What is the safe way to learn from that example?

      -

      Alex: Start with GitHub CLI. There is something to understand, something to try, and something that proves the try worked.

      -

      Alex: Treat examples as spoken recipes, not decorations. You may hear something like Star a repository; gh api user/starred/owner/repo --method PUT; Unstar a repository; gh api user/starred/owner/repo --method DELETE; List your starred repositories; gh api user/starred --jq '.[].full name'; Check if you've starred a repo; gh api. Read the command, understand what it changes, then run it only when the repository state matches the lesson.

      -

      Jamie: Let's pause on Viewing your stars. What should a learner take away from it?

      -

      Alex: Here is the plain-English version of Viewing your stars. Go to github.com/username?tab=stars -- or click your avatar → Your stars. Put another way, you'll see all your starred repositories sorted by most recently starred.

      -

      Alex: Keep the teaching thread moving. Start with Learning Cards: Stars. There is something to understand, something to try, and something that proves the try worked.

      -

      Alex: The practical takeaway is this. The Star button is in the repository header area -- press B to navigate buttons until you hear "Star this repository" (or "Unstar this repository" if already starred); press Enter to toggle. The keyboard shortcut g then s on any repository page toggles the star without needing to navigate to the button. Your starred repos are listed at github.com/username?tab=stars -- each entry is a heading with the repo name as a link; use H to jump between starred repos. The Star button shows a star icon with a count next to it in the repository header -- at high zoom, the button may wrap below the repo name; look for the star icon near Fork and Watch. When you star a repo, the button changes from an outline star to a filled star with the label "Starred" -- the visual change is subtle; confirm by re-reading the button text. The dropdown arrow next to Star lets you add the repo to a List -- look for a small triangle icon to the right of the Star button at high magnification.

      -
      -

      Jamie: Let's pause on What watching does. What should a learner take away from it?

      -

      Alex: Keep the learner anchored in What watching does. When you watch a repository, GitHub sends you notifications about activity in it -- new issues, pull requests, releases, and more. This is the part to say slowly: Unlike stars (which are passive bookmarks), watching is active -- you're opting into the conversation.

      -

      Alex: Keep the teaching thread moving. The reason Watch levels matters is that GitHub gives you granular control over how much you hear from a repo. The interface gets friendlier when it stops being a wall of controls and starts being a set of named places.

      -

      Jamie: Let's pause on How to watch a repository. What should a learner take away from it?

      -

      Alex: Start with How to watch a repository: On any repository page, the Watch button is next to the Star button in the header. The next useful detail is this: For most repositories you contribute to, "Participating and @mentions" is the right level -- you hear about threads you're in without inbox overload.

      -

      Alex: First, click Watch to open the dropdown. Then, choose your notification level. After that, the button updates to show your current setting. Think of it as a rail line: each stop confirms you are still on the right route before the next one.

      -
      -

      Jamie: What should they understand before typing anything?

      -

      Alex: Treat examples as spoken recipes, not decorations. You may hear something like Watch a repository (all activity); gh api repos/owner/repo/subscription --method PUT --field subscribed=true; Watch releases only (requires GitHub.com -- not available via API alone); Use the web UI for granular watch levels; Ignore a repository; gh api. Read the command, understand what it changes, then run it only when the repository state matches the lesson.

      -

      Jamie: Let's pause on Learning Cards: Watching Repositories. What should a learner take away from it?

      -

      Alex: Start with Learning Cards: Watching Repositories. There is something to understand, something to try, and something that proves the try worked.

      -

      Alex: The practical takeaway is this. The Watch button is next to the Star button in the repository header -- press B to navigate buttons until you hear "Watch" or a watch level label; press Enter to open the dropdown. The watch level dropdown presents radio-style options (Not watching, Participating, All Activity, Releases only, Ignore) -- arrow through them and press Enter to select. "Participating and @mentions" is the recommended default for repos you contribute to -- it notifies you only for threads you are in or mentioned in, avoiding inbox overload. The Watch button shows an eye icon with a dropdown arrow and a count of watchers -- at high zoom, look for it immediately to the left of the Star button in the repository header. The dropdown menu lists five watch levels vertically with radio indicators -- the currently selected level has a filled radio dot or checkmark next to it. "Releases only" is the best choice for tools and dependencies you use but do not contribute to -- it sends one notification per release instead of every issue and PR.

      -

      Alex: Keep the teaching thread moving. Keep the learner anchored in What following does. When you follow a developer on GitHub. This is the part to say slowly: Following is one-way (like Twitter/X) -- they don't need to follow you back. A good GitHub workflow is like a well-run meeting: everyone knows the topic, the next action, and who has the floor.

      -

      Alex: The practical takeaway is this. Their public activity appears in your home feed. You see when they star a repository, create a new repo, or get a new follower. They receive a notification that you followed them. You appear in their followers list.

      -
      -

      Jamie: Let's pause on Who to follow. What should a learner take away from it?

      -

      Alex: The reason Who to follow matters is that start with people whose work you already use.

      -

      Alex: The practical takeaway is this. Maintainers of tools and libraries you use daily. Authors of blog posts or talks that helped you learn. Developers in accessibility, open source, or your tech stack. Visiting the Contributors tab of a repository you love: github.com/owner/repo/graphs/contributors. Checking who opened issues or PRs you found valuable. Looking at who your existing follows follow.

      -

      Alex: Keep the teaching thread moving. Start with How to follow someone: On any user profile page (github.com/username), click the Follow button below their avatar. The next useful detail is this: To unfollow: click Following → it changes back to Follow.

      -

      Jamie: Before we leave Screen reader navigation, what is the practical point?

      -

      Alex: The practical takeaway is this. Navigate to the profile page. The Follow/Following button is near the top of the page, below the avatar and bio. NVDA/JAWS: press B to jump to buttons; the button is labelled "Follow [username]". VoiceOver: Tab to the button or use VO+Command+J.

      -
      -

      Jamie: Let's pause on GitHub CLI. What should a learner take away from it?

      -

      Alex: Treat examples as spoken recipes, not decorations. You may hear something like Follow a user; gh api user/following/username --method PUT; Unfollow a user; gh api user/following/username --method DELETE; List who you're following; gh api user/following --jq '.[].login'; List your followers; gh api user/followers --jq '.[].login'; Check. Read the command, understand what it changes, then run it only when the repository state matches the lesson.

      -

      Jamie: Let's pause on Viewing someone's profile. What should a learner take away from it?

      -

      Alex: Keep the learner anchored in Viewing someone's profile. The contribution graph is a visual calendar that screen readers may announce as a table or grid. This is the part to say slowly: Navigate with arrow keys to read individual day entries -- each cell describes the date and number of contributions.

      -

      Alex: The practical takeaway is this. Pinned repositories -- the 6 repos they've chosen to highlight. Contribution graph -- a visual grid of their activity over the past year (green squares = more activity). Recent activity -- PRs opened, issues commented on, repos starred. Repositories -- all their public repos.

      -

      Alex: Keep the teaching thread moving. The reason 4. Your Home Feed -- What You See When You Log In matters is that when you go to github.com while logged in, your home feed shows activity from people and repositories you follow or watch.

      -
      -

      Jamie: Let's pause on What appears in your feed. What should a learner take away from it?

      -

      Alex: Start with What appears in your feed. There is something to understand, something to try, and something that proves the try worked.

      -

      Alex: The practical takeaway is this. Repositories starred by people you follow -- "Jane starred awesome-accessibility". New repositories created by people you follow. Releases from repositories you watch. Public activity from people you follow (PRs opened, issues commented on). "For you" recommendations -- GitHub suggests repos and people based on your activity.

      -

      Alex: Keep the teaching thread moving. Here is the plain-English version of Your feed is a discovery tool. One of the best ways to find new interesting projects is to follow a few active developers in your area of interest and watch what they star. Put another way, if 5 people you respect all starred the same new tool this week, it's probably worth a look. It is like learning a transit route. The names of the stops matter because they tell you whether you are still going the right direction.

      -

      Jamie: Let's pause on Customising your feed. What should a learner take away from it?

      -

      Alex: This is where Customising your feed becomes real: there's no fine-grained feed filter -- you control the feed by controlling who you follow and what you watch. That matters in practice: Unfollow noisy accounts, follow more focused ones.

      -
      -

      Alex: Keep the teaching thread moving. Keep the learner anchored in 5. GitHub Explore -- Discovering New Projects. GitHub Explore at github.com/explore is the discovery hub -- curated collections, trending repos, and personalised recommendations.

      -

      Jamie: Let's pause on What Explore shows. What should a learner take away from it?

      -

      Alex: Start with What Explore shows. There is something to understand, something to try, and something that proves the try worked.

      -

      Alex: The practical takeaway is this. Trending -- most-starred repos this week (see Section 6). Topics -- browse by subject area (see Section 7). Collections -- curated lists of thematically related repos (e.g., "Tools for Open Source", "Accessibility Projects"). "For you" personalised recommendations -- based on your stars, follows, and language preferences.

      -

      Jamie: Let's pause on Navigating Explore with a screen reader. What should a learner take away from it?

      -

      Alex: Start with Navigating Explore with a screen reader. There is something to understand, something to try, and something that proves the try worked.

      -

      Alex: First, go to github.com/explore. Then, the page uses landmark regions -- jump to main to skip navigation. After that, collections and trending repos are listed as article/heading groups. Finally, use heading navigation (H) to jump between sections. Think of it as a rail line: each stop confirms you are still on the right route before the next one.

      -

      Jamie: Before we leave Navigating Explore with a screen reader, what is the practical point?

      -

      Alex: First, each repo entry has a heading (repo name as a link), language badge, star count, and description. Treat it like a recipe: do not add the next ingredient until the previous one is actually in the bowl.

      -
      -

      Jamie: Let's pause on 6. Trending -- What's Popular Right Now. What should a learner take away from it?

      -

      Alex: Here is the plain-English version of 6. Trending -- What's Popular Right Now. GitHub Trending at github.com/trending shows repositories gaining the most stars over a time period. Put another way, it's one of the best places to discover new tools before everyone else knows about them.

      -

      Alex: Keep the teaching thread moving. This is where Filtering trending becomes real: use the dropdowns at the top of the page to filter.

      -

      Jamie: Let's pause on Trending developers. What should a learner take away from it?

      -

      Alex: Keep the learner anchored in Trending developers. Switch to github.com/trending/developers to see which developers are gaining the most followers -- another great way to find people to follow.

      +

      Alex: Keep the teaching thread moving. The reason Terminal Signals matters is that enable taskCompleted and taskFailed immediately. That gives the learner a simple foothold: when you run git push or npm test in the terminal, you hear whether it succeeded without switching back to the terminal panel.

      +

      Jamie: Let's pause on Chat and Copilot Signals. What should a learner take away from it?

      +

      Alex: Start with Chat and Copilot Signals: chatResponseReceived plays a randomly chosen variant each time (responseReceived1 through responseReceived4). The next useful detail is this: This prevents habituation -- your brain stays alert to the signal instead of filtering it out after hearing the same sound repeatedly.

      +

      Alex: Keep the teaching thread moving. Here is the plain-English version of Editor Action Signals. These fire on user-triggered actions and use the "userGesture" value to distinguish manual saves from auto-saves. Put another way, set these to "userGesture" rather than "on" if auto-save is enabled, to avoid a sound on every keystroke pause. It is like learning a transit route. The names of the stops matter because they tell you whether you are still going the right direction.

      -

      Jamie: Before we leave GitHub CLI, what is the practical point?

      -

      Alex: Treat examples as spoken recipes, not decorations. You may hear something like Trending repos aren't in the official API, but you can get recently starred popular repos:; gh search repos --sort stars --order desc --limit 20 --language markdown; Trending in a specific language; gh search repos --sort stars --order desc --limit 20. Read the command, understand what it changes, then run it only when the repository state matches the lesson.

      -

      Jamie: Let's pause on 7. Topics -- Finding Projects by Category. What should a learner take away from it?

      -

      Alex: Start with 7. Topics -- Finding Projects by Category: Every repository can be tagged with topics -- keywords like accessibility, screen-reader, wcag, python, machine-learning. The next useful detail is this: Topics are how maintainers categorise their work so others can discover it.

      -

      Alex: Keep the teaching thread moving. Here is the plain-English version of Browsing topics. Click any topic tag on a repository page to see all repos tagged with that topic.

      +

      Jamie: Let's pause on Debounce Settings for Position Signals. What should a learner take away from it?

      +

      Alex: This is where Debounce Settings for Position Signals becomes real: 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. That matters in practice: VS Code debounces these by default.

      +

      Alex: Keep the teaching thread moving. Keep the learner anchored in Recommended Workshop Profile. Add this to your VS Code settings.json (Ctrl+Shift+P then "Preferences: Open User Settings (JSON)"). This is the part to say slowly: This profile enables core sounds for everyone and sets announcements to auto so they activate only when a screen reader is detected.

      +

      Alex: The practical takeaway is this. 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.

      +

      Jamie: Let's pause on Migrating from Legacy Audio Cues. What should a learner take away from it?

      +

      Alex: The reason Migrating from Legacy Audio Cues matters is that if you previously configured the older audioCues. That gives the learner a simple foothold: settings (deprecated since VS Code 1.85), VS Code automatically maps them to the new accessibility.signals.

      -

      Jamie: What is the teaching move inside GitHub CLI?

      -

      Alex: Treat examples as spoken recipes, not decorations. You may hear something like Search for repos with a specific topic; gh search repos --topic accessibility --limit 20; gh search repos --topic screen-reader --stars " 50"; Add a topic to your own repository; gh api repos/owner/repo/topics --method PUT --field names[]="accessibility". Read the command, understand what it changes, then run it only when the repository state matches the lesson.

      -

      Alex: Keep the teaching thread moving. Keep the learner anchored in 8. GitHub Lists -- Organizing Your Stars. Lists let you group your starred repositories into named collections -- like playlists for code. This is the part to say slowly: Instead of one big pile of stars, you can have "Accessibility Tools," "Learning Resources," "Projects I Contribute To," etc. A good GitHub workflow is like a well-run meeting: everyone knows the topic, the next action, and who has the floor.

      -

      Jamie: Let's pause on Creating a list. What should a learner take away from it?

      -

      Alex: Start with Creating a list. There is something to understand, something to try, and something that proves the try worked.

      -

      Alex: First, go to your stars: github.com/username?tab=stars. Then, select "Create list" (top right of the stars page). After that, give it a name and optional description. Finally, select "Create". The rhythm is simple: orient, act, verify, then continue.

      -

      Jamie: Before we leave Creating a list, what is the practical point?

      -

      Alex: First, on a repo page, click the dropdown arrow next to the Star button. Then, select "Create a list" or add to an existing list. Think of it as a rail line: each stop confirms you are still on the right route before the next one.

      +

      Alex: Keep the teaching thread moving. Start with Learning Cards: Accessibility Signals. There is something to understand, something to try, and something that proves the try worked.

      +

      Alex: The practical takeaway is this. 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. 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.

      +

      Jamie: How do we make tool choice feel like access, not pressure?

      +

      Alex: Here is the plain-English version of 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. Put another way, all voice processing happens locally on your machine - no audio data is sent to any online service.

      +

      Jamie: What is the ordered workflow?

      +

      Alex: This is where Installing VS Code Speech becomes real: after installation, a microphone icon appears in all Chat input fields and new voice commands become available in the Command Palette. That matters in practice: Microphone permissions: On macOS, go to System Settings, Privacy and Security, Microphone, and confirm Visual Studio Code is enabled.

      +

      Alex: First, open Extensions: Ctrl+Shift+X (Mac: Cmd+Shift+X). Then, search for VS Code Speech. After that, find VS Code Speech (publisher: Microsoft, identifier: ms-vscode.vscode-speech). Finally, press Enter to open the extension detail page, then Tab to "Install" and press Enter. It is a checklist, but a meaningful one: every item creates evidence that the next step is safe.

      -

      Alex: Keep the teaching thread moving. Start with Adding repos to lists. There is something to understand, something to try, and something that proves the try worked.

      -

      Alex: The practical takeaway is this. From any repo page: Star dropdown → check the list name. From your stars page: click the list icon on any starred repo row.

      -

      Jamie: Let's pause on Viewing and sharing lists. What should a learner take away from it?

      -

      Alex: Here is the plain-English version of Viewing and sharing lists. Your lists are public at github.com/username?tab=stars -- anyone can browse them. Put another way, this is useful for sharing curated resources with your community.

      -

      Jamie: If someone only remembers one thing from GitHub CLI, what should it be?

      -

      Alex: Treat examples as spoken recipes, not decorations. You may hear something like Lists are managed through the GitHub web interface only; You can view stars via CLI:; gh api user/starred --jq '.[] {name.full name, description.description}' head -20. Read the command, understand what it changes, then run it only when the repository state matches the lesson.

      +

      Jamie: Let's pause on Editor Dictation - Type with Your Voice. What should a learner take away from it?

      +

      Alex: Keep the learner anchored in Editor Dictation - Type with Your Voice. Editor dictation lets you speak and have your words appear as text wherever your cursor is. This is the part to say slowly: This works in the code editor, the SCM commit input box, and the comments field when reviewing pull requests.

      +

      Alex: The practical takeaway is this. 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.

      +

      Alex: Keep the teaching thread moving. The reason Voice in Copilot Chat - Talk to Copilot matters is that instead of typing prompts, you can speak them. That gives the learner a simple foothold: this works in the Chat panel, inline chat, and quick chat. The interface gets friendlier when it stops being a wall of controls and starts being a set of named places.

      +

      Alex: The practical takeaway is this. 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.

      +

      Jamie: Let's pause on Text-to-Speech - Listen to Chat Responses. What should a learner take away from it?

      +

      Alex: Start with Text-to-Speech - Listen to Chat Responses: VS Code Speech can read Copilot Chat responses aloud. The next useful detail is this: Each chat response shows a speaker icon you can activate to hear that specific response.

      -

      Jamie: Let's pause on 9. Finding Accessible and Inclusive Projects. What should a learner take away from it?

      -

      Alex: Keep the learner anchored in 9. Finding Accessible and Inclusive Projects. If you're specifically looking for projects that welcome contributors with disabilities, or that focus on accessibility work, here are the best ways to find them.

      -

      Jamie: Let's pause on Search strategies. What should a learner take away from it?

      -

      Alex: Start with Search strategies. There is something to understand, something to try, and something that proves the try worked.

      -

      Alex: The practical takeaway is this. github.com/topics/accessibility. github.com/topics/wcag. github.com/topics/screen-reader.

      -

      Alex: Treat examples as spoken recipes, not decorations. You may hear something like Search for accessibility-focused repos; gh search repos "accessibility" --topic a11y --stars " 100"; Find repos with good first issues in accessibility; gh search issues "accessibility" --label "good first issue" --state open; Find issues tagged both. Read the command, understand what it changes, then run it only when the repository state matches the lesson.

      -

      Jamie: Let's pause on Organisations to follow. What should a learner take away from it?

      -

      Alex: Start with Organisations to follow: GitHub organisations are collections of repos grouped by a team or company. The next useful detail is this: You can follow an org to get notified of their public activity.

      -

      Alex: The practical takeaway is this. github.com/Community-Access -- the organisation behind this workshop. Search for org:github accessibility to find GitHub's own accessibility work. Many assistive technology companies have open source components on GitHub -- search for your AT provider.

      +

      Jamie: Let's pause on Automatic read-aloud after voice input. What should a learner take away from it?

      +

      Alex: Here is the plain-English version of 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.

      +

      Alex: First, you speak a question using voice chat. Then, Copilot responds in text. After that, the response is automatically read aloud. Finally, to stop playback mid-sentence, press Escape or activate the stop icon. Treat it like a recipe: do not add the next ingredient until the previous one is actually in the bowl.

      +

      Jamie: Let's pause on Manual read-aloud for any response. What should a learner take away from it?

      +

      Alex: This is where Manual read-aloud for any response becomes real: even without autoSynthesize, every Chat response has a speaker icon. That matters in practice: Activate it to hear that specific response read aloud.

      +

      Alex: The practical takeaway is this. 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.

      +

      Alex: Keep the teaching thread moving. Keep the learner anchored in "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. This is the part to say slowly: 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. A good GitHub workflow is like a well-run meeting: everyone knows the topic, the next action, and who has the floor.

      -

      Alex: Keep the teaching thread moving. Here is the plain-English version of Looking at who your community follows. If you follow someone doing accessibility work, browse their stars and their following list -- this is one of the fastest ways to discover the accessibility community on GitHub. It is like learning a transit route. The names of the stops matter because they tell you whether you are still going the right direction.

      -

      Jamie: Let's pause on 10. Building Your Own Presence. What should a learner take away from it?

      -

      Alex: This is where 10. Building Your Own Presence becomes real: being visible on GitHub matters when you want to collaborate with others, get hired, or establish yourself as a contributor.

      -

      Alex: Keep the teaching thread moving. Keep the learner anchored in Your contribution graph. The green grid on your profile shows your public contribution activity over the past year. This is the part to say slowly: Contributions to private repos only appear as grey squares unless the repo is made public later.

      -

      Alex: The practical takeaway is this. Push commits to a public repo. Open, comment on, or close issues or PRs in a public repo. Review a PR in a public repo.

      +

      Jamie: Let's pause on Language Configuration. What should a learner take away from it?

      +

      Alex: The reason Language Configuration matters is that VS Code Speech supports 26 languages. That gives the learner a simple foothold: by default it matches your VS Code display language.

      +

      Jamie: How do you keep commands from becoming magic words?

      +

      Alex: Start with Custom Keybindings for Voice: You can assign your own shortcuts for voice commands. The next useful detail is this: Open the Keyboard Shortcuts editor (Ctrl+K Ctrl+S) and search for "voice" or "dictation".

      +

      Alex: Treat examples as spoken recipes, not decorations. You may hear something like [; {; "key": "ctrl+u",; "command": "workbench.action.chat.startVoiceChat",; "when": "!voiceChatInProgress"; },; {; "key": "ctrl+u",; "command": "workbench.action.chat.stopListeningAndSubmit",; "when": "voiceChatInProgress"; },; {; "key": "ctrl+d",; "command". Read the command, understand what it changes, then run it only when the repository state matches the lesson.

      +

      Jamie: Let's pause on Supported Platforms. What should a learner take away from it?

      +

      Alex: Here is the plain-English version of Supported Platforms. On Linux, the extension requires the ALSA shared library (libasound). Put another way, install it with sudo apt install libasound2 on Debian/Ubuntu if it is not already present.

      -

      Jamie: Let's pause on Pinning repositories. What should a learner take away from it?

      -

      Alex: The reason Pinning repositories matters is that pin up to 6 repositories (your own or repos you've contributed to) on your profile.

      -

      Alex: First, go to your profile (github.com/username). Then, select "Customize your pins" above the pinned repos section. After that, check up to 6 repos to pin -- prioritise your best work and most active contributions. The rhythm is simple: orient, act, verify, then continue.

      -

      Alex: Keep the teaching thread moving. Start with Your profile README: Create a special repository named exactly the same as your username (github.com/username/username) and its README.md will appear at the top of your profile page. The next useful detail is this: This is your chance to introduce yourself, list your skills, and share what you're working on. Think of it like entering a new building: first you find the lobby, then the room, then the door you actually need.

      -

      Jamie: Let's pause on Activity tips. What should a learner take away from it?

      -

      Alex: Start with Activity tips. There is something to understand, something to try, and something that proves the try worked.

      -

      Alex: The practical takeaway is this. Comment thoughtfully on issues -- even "I can reproduce this on Windows 11 with NVDA" is a valued contribution that shows on your profile. Star generously -- it signals your interests and others see it in their feeds. Follow people in your area -- they often follow back, growing your network organically.

      +

      Alex: Keep the teaching thread moving. This is where 19. Markdown Authoring in VS Code becomes real: you write Markdown in nearly every challenge of this workshop -- issue descriptions, pull request bodies, README updates, and agent files. That matters in practice: 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. The workshop is closer to rehearsal than lecture. You hear the move, try the move, and then check what changed.

      +

      Jamie: Let's pause on Markdown Preview. What should a learner take away from it?

      +

      Alex: Keep the learner anchored in Markdown Preview. VS Code includes a live Markdown preview so you can see rendered output alongside your source. This is the part to say slowly: The preview pane renders HTML, so your screen reader announces headings, links, and list items using their semantic roles.

      +

      Alex: The practical takeaway is this. 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.

      +

      Jamie: Let's pause on The markdownlint Extension. What should a learner take away from it?

      +

      Alex: The reason The markdownlint Extension matters is that the markdownlint extension (identifier: DavidAnson.vscode-markdownlint) catches common Markdown mistakes as you type, the same way a spell checker catches typos. That gives the learner a simple foothold: once installed, problems appear as wavy underlines in the editor and as entries in the Problems panel (Ctrl+Shift+M).

      +

      Alex: The practical takeaway is this. 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.

      +

      Alex: First, open Extensions: Ctrl+Shift+X (Mac: Cmd+Shift+X). Then, search for markdownlint. After that, install the one by David Anson. The rhythm is simple: orient, act, verify, then continue.

      -

      Jamie: Let's pause on 11. The GitHub CLI for Social Features. What should a learner take away from it?

      -

      Alex: Start with 11. The GitHub CLI for Social Features. There is something to understand, something to try, and something that proves the try worked.

      -

      Alex: Treat examples as spoken recipes, not decorations. You may hear something like --- Following ---; gh api user/following/username --method PUT Follow someone; gh api user/following/username --method DELETE Unfollow; gh api user/following --jq '.[].login' List who you follow; gh api user/followers --jq '.[].login' List your followers; ---. Read the command, understand what it changes, then run it only when the repository state matches the lesson.

      -

      Jamie: Let's pause on Following a user. What should a learner take away from it?

      -

      Alex: Start with Following a user. There is something to understand, something to try, and something that proves the try worked.

      -

      Alex: First, navigate to github.com/username. Then, press H to jump through headings to find the user's name at the top. After that, tab forward -- the Follow/Following button is within the first few interactive elements after the avatar/bio area. Finally, press Enter or Space to follow; the button label updates to "Following [username]". It is like walking a hallway with named doors: read the sign, enter the right room, then confirm where you landed.

      -

      Jamie: Let's pause on Starring a repository. What should a learner take away from it?

      -

      Alex: Start with Starring a repository. There is something to understand, something to try, and something that proves the try worked.

      -

      Alex: First, navigate to any repository page. Then, the Star button is in the repository header, near the Fork button. After that, press B (NVDA/JAWS) to navigate by button, or Tab through the header. Finally, the button is announced as "Star this repository" or "Unstar this repository". The rhythm is simple: orient, act, verify, then continue.

      -

      Jamie: Before we leave Starring a repository, what is the practical point?

      -

      Alex: First, after starring, the button label changes and a count updates. Think of it as a rail line: each stop confirms you are still on the right route before the next one.

      +

      Jamie: Let's pause on Outline View for Headings. What should a learner take away from it?

      +

      Alex: Start with 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. The next useful detail is this: 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.

      +

      Alex: The practical takeaway is this. 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.

      +

      Alex: Keep the teaching thread moving. Here is the plain-English version of Copilot Markdown Assistance. If you have GitHub Copilot enabled (see Chapter 16), it can help with Markdown authoring directly in the editor. Put another way, these features save time when you are writing issue descriptions or pull request bodies during the workshop challenges. It is like learning a transit route. The names of the stops matter because they tell you whether you are still going the right direction.

      +

      Alex: The practical takeaway is this. 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, 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.

      +

      Jamie: What should feel predictable before the first live session starts?

      +

      Alex: This is where Why This Matters for the Workshop becomes real: students write Markdown in every single challenge -- from the very first issue you file in Chapter 5 to the agent file you create in Chapter 20. That matters in practice: Markdown is also how you write pull request descriptions (Chapter 6) and README files.

      -

      Jamie: Let's pause on Browsing your stars. What should a learner take away from it?

      -

      Alex: Start with Browsing your stars. There is something to understand, something to try, and something that proves the try worked.

      -

      Alex: First, go to github.com/username?tab=stars. Then, jump to main landmark to skip navigation. After that, each starred repo is a heading (H3) with a link -- navigate with H or 3. Finally, below each heading: description text, language, star count, and list controls. Think of it as a rail line: each stop confirms you are still on the right route before the next one.

      -

      Jamie: Let's pause on Exploring topics. What should a learner take away from it?

      -

      Alex: Start with Exploring topics. There is something to understand, something to try, and something that proves the try worked.

      -

      Alex: First, go to github.com/topics/accessibility (or any topic). Then, jump to main landmark. After that, repos are listed as article regions with H3 headings. Finally, each entry has: repo name (link), owner, description, language, star count, and a Star button. Treat it like a recipe: do not add the next ingredient until the previous one is actually in the bowl.

      -

      Jamie: Let's pause on GitHub Explore and Trending. What should a learner take away from it?

      -

      Alex: This is where GitHub Explore and Trending becomes real: next: Appendix U: Discussions and Gists Back: Appendix S: Releases and Insights Teaching chapter: Chapter 08: Open Source Culture.

      -

      Alex: First, go to github.com/explore or github.com/trending. Then, use H to navigate between sections and repo entries. After that, trending page has language and time period filter dropdowns near the top -- Tab to find them. Finally, each trending repo row has: rank position, repo name (link), description, star count, and "Stars today" count. It is a checklist, but a meaningful one: every item creates evidence that the next step is safe.

      +

      Alex: Keep the teaching thread moving. Keep the learner anchored in If You Get Stuck. Next: Chapter 13: How Git Works Back: Chapter 11: VS Code Interface Related appendices: Appendix G: VS Code Reference.

      Jamie: What should people carry with them after this?

      Alex: Carry the map. Know what page or tool you are in, know which action you are taking, and know what confirmation should follow. If the confirmation is missing, pause. That pause is not wasted time; it is professional judgment.

      Jamie: That is a better way to say it than just follow the steps.

      -

      Alex: Right. Steps matter, but understanding wins. That is episode 36. Next in the series is episode 37, where we keep building the same contributor muscles.

      +

      Alex: Right. Steps matter, but understanding wins. That is episode 45. Next in the series is episode 46, where we keep building the same contributor muscles.

      -

      Day 1: GitHub Foundations

      -

      Episode 37: Contributing to Open Source

      -

      Finding issues, scoping contributions, the fork-to-PR workflow, and building habits.

      -

      Based on: Chapter 8: Contributing to Open Source

      +

      32. Episode 21: Git Authentication

      +

      Personal access tokens, SSH keys, credential storage, and commit signing.

      +

      Based on: Appendix D: Git Authentication

      Audio and transcript are being regenerated for this episode.

      -Read Transcript - Episode 37: Contributing to Open Source +Read Transcript - Episode 21: Git Authentication

      Transcript

      -

      Alex: Welcome back to Git Going with GitHub. This is episode 37: Contributing to Open Source. I am Alex, and today we are turning Contributing to Open Source from a list of instructions into a working mental model.

      +

      Alex: Welcome back to Git Going with GitHub. This is episode 21: Git Authentication. I am Alex, and today we are turning Git Authentication from a list of instructions into a working mental model.

      Jamie: And I am Jamie. I will stop us whenever the instructions sound simple on paper but might feel different with a keyboard and screen reader.

      -

      Alex: Finding issues, scoping contributions, the fork-to-PR workflow, and building habits. That is the surface description. Underneath it, we are building judgment: where to focus, what to ignore, and how to verify the result.

      +

      Alex: Personal access tokens, SSH keys, credential storage, and commit signing. That is the surface description. Underneath it, we are building judgment: where to focus, what to ignore, and how to verify the result.

      Jamie: So we are not using the audio as a shortcut around learning. We are using it to make the learning easier to enter.

      Alex: Yes. A good audio lesson gives someone enough context to try the work with confidence, even before they open the written material.

      Jamie: Okay, set the room for us. What are we walking into?

      -

      Alex: Start with How to Be an Effective and Respectful Open Source Contributor: Technical skills get your code into a project. The next useful detail is this: Communication skills keep you welcomed in the community.

      -

      Alex: The next layer is this. Here is the plain-English version of Workshop Recommendation (Chapter 8). Chapter 8 is a communication and culture chapter. It is like learning a transit route. The names of the stops matter because they tell you whether you are still going the right direction.

      -

      Alex: The practical anchors are these. There are 1 guided reflection (no bot grading). Automation check: none - communication quality is too subjective for fair automated scoring. The evidence is structured reflection comment on your assigned challenge issue. The pattern is read, reflect, commit to one behavior.

      -

      Jamie: What does the learner do first, second, and then after that?

      -

      Alex: Start with Chapter 8 Challenge Set. There is something to understand, something to try, and something that proves the try worked.

      -

      Alex: First, guided reflection - read the chapter, then post a short reflection comment committing to three specific collaboration behaviors. It is a checklist, but a meaningful one: every item creates evidence that the next step is safe.

      -
      -

      Jamie: Turn that into a path someone can follow.

      -

      Alex: Keep the learner anchored in Challenge 8.1 Step-by-Step: Guided Reflection. Identify three concrete communication behaviors you will practice during the rest of the workshop. This is the part to say slowly: your assigned Chapter 8 challenge issue in your Learning Room repository on GitHub.com.

      -

      Alex: For a learner, the useful signals are these. 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.".

      -

      Alex: First, read through the chapter content below, paying attention to the sections on GitHub Flow, constructive feedback, and asking for help. Then, as you read, think about one situation from Day 1 where communication helped (or could have helped) you. After that, open your assigned Chapter 8 challenge issue (the one titled "Chapter 8.1: Guided Reflection (@yourname)"). Finally, scroll to the comment box at the bottom of the issue. It is like walking a hallway with named doors: read the sign, enter the right room, then confirm where you landed.

      -

      Jamie: What is the ordered workflow?

      -

      Alex: First, post a reflection comment using this format. Then, for each prompt, write one specific, actionable sentence - not a vague goal. After that, activate the Comment button (or press Ctrl+Enter). The rhythm is simple: orient, act, verify, then continue.

      -

      Jamie: What makes this practice feel low-stakes but still real?

      -

      Alex: The reason Completing Chapter 8: Submit Your Evidence matters is that the reflection comment itself is your evidence. That gives the learner a simple foothold: the facilitator reviews your comment for specificity.

      -

      Alex: The useful habit is simple: orient first, act second, verify third. That pause before acting is part of the work.

      -

      Alex: That matters because of the next idea. Start with Expected Outcomes. There is something to understand, something to try, and something that proves the try worked.

      -

      Alex: On the ground, that means a few things. 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.

      -
      -

      Jamie: How would you walk the room through that step by step?

      -

      Alex: Start with If You Get Stuck. There is something to understand, something to try, and something that proves the try worked.

      -

      Alex: First, use one simple sentence per prompt - do not overthink it. Then, focus on one real behavior you can start doing today, not an abstract principle. After that, if writing feels hard, draft bullet points first in a text editor, then paste into the comment. Finally, look at the "Giving Feedback" and "Asking for Help" sections in this chapter for concrete examples. Treat it like a recipe: do not add the next ingredient until the previous one is actually in the bowl.

      -

      Jamie: Give me the sequence, because order matters here.

      -

      Alex: First, ask facilitator for one example response and adapt it to your own words. Then, finished but not sure you did it right? Compare your work against the Challenge 8 reference solution. It is a checklist, but a meaningful one: every item creates evidence that the next step is safe.

      -

      Alex: This is where the talk moves from concept to action. This is where Learning Moment becomes real: technical quality and communication quality work together. That matters in practice: Respectful, clear communication helps good code get merged faster.

      -

      Jamie: Let's pause on Learning Pattern Used in This Chapter. What should a learner take away from it?

      -

      Alex: Start with Learning Pattern Used in This Chapter. There is something to understand, something to try, and something that proves the try worked.

      -

      Alex: First, read and absorb community norms (not just rules, but reasons). Then, reflect on personal experience (what worked, what was hard). After that, commit to specific behaviors in writing (public accountability). Finally, apply those behaviors in upcoming chapters (reviews, comments, PRs). It is like walking a hallway with named doors: read the sign, enter the right room, then confirm where you landed.

      +

      Alex: Start with SSH Keys & Personal Access Tokens: Audience: This appendix is for contributors who need to configure Git authentication for push access. The next useful detail is this: If you're working entirely through the GitHub web interface or GitHub Desktop, you can skip this.

      +

      Alex: The next layer is this. Start with Learning Cards: Using This Authentication Reference. There is something to understand, something to try, and something that proves the try worked.

      +

      Alex: The practical anchors are these. This appendix has two main paths: Personal Access Token (recommended) and SSH Keys -- jump to your chosen method via heading navigation. Step-by-step instructions are numbered lists -- your screen reader announces "1 of 8," etc. to track progress. The Troubleshooting section near the bottom covers the error messages you are most likely to encounter. Command-line examples are in code blocks with high contrast -- increase zoom to read them comfortably. Each method (PAT vs SSH) is a separate section with its own step-by-step flow. The "Do not" lists use bold text to highlight security warnings.

      +

      Jamie: What is the one idea that makes the next few steps less mysterious?

      +

      Alex: This is where When You Need Authentication becomes real: GitHub requires authentication when you.

      +

      Alex: That shows up in the workshop in a few specific ways. Push commits to a repository. Clone a private repository. Access organization repositories with specific permissions. Clone public repositories. View public repositories on GitHub.com. Read issues and pull requests.

      -

      Alex: Before the learner moves on. The reason GitHub Flow - The Standard Contribution Workflow matters is that before diving into communication norms, it helps to understand the workflow that gives all of those conversations their context. That gives the learner a simple foothold: GitHub Flow is the lightweight branching model recommended for open source contribution. The interface gets friendlier when it stops being a wall of controls and starts being a set of named places.

      +

      Alex: Now bring the learner back to the room. Keep the learner anchored in Personal Access Token (PAT). A Personal Access Token is a password-like string you generate on GitHub and use instead of your account password when Git asks for credentials.

      Jamie: What would you say to someone who is already bracing for this to be too much?

      -

      Alex: Start with Why This Model Works. There is something to understand, something to try, and something that proves the try worked.

      -

      Alex: A few details make that real. 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.

      -

      Alex: Hold that next to this. Here is the plain-English version of GitHub Flow vs Git Flow. You may encounter "Git Flow" (sometimes written "GitFlow") in older projects or enterprise environments. Put another way, this section explains what Git Flow is, how it differs from GitHub Flow, and why this workshop teaches GitHub Flow.

      -

      Alex: A solid Git habit is to know which branch you are on, what changed, and what confirmation you expect before you run the next command.

      -
      -

      Jamie: If I am listening before the workshop starts, what should settle in my mind first?

      -

      Alex: This is where What Git Flow Is becomes real: Git Flow is a branching model published by Vincent Driessen in 2010. That matters in practice: It was designed for teams that ship versioned releases on a schedule (desktop software, mobile apps, embedded systems).

      -

      Jamie: Let's pause on How the Git Flow Cycle Works. What should a learner take away from it?

      -

      Alex: Start with How the Git Flow Cycle Works. There is something to understand, something to try, and something that proves the try worked.

      -

      Alex: First, developers branch feature/my-feature off develop and work there. Then, completed features merge back into develop via pull request. After that, when develop has enough features for a release, a release/1.2.0 branch is created. Finally, the release branch gets final testing, bug fixes, and version number updates. It is like walking a hallway with named doors: read the sign, enter the right room, then confirm where you landed.

      -

      Jamie: Before we leave How the Git Flow Cycle Works, what is the practical point?

      -

      Alex: First, the release branch merges into main (tagged with the version) and back into develop. Then, if a critical bug is found in production, a hotfix/ branch is created from main, fixed, and merged into both main and develop. The rhythm is simple: orient, act, verify, then continue.

      -

      Jamie: What is the one idea that makes the next few steps less mysterious?

      -

      Alex: The reason How GitHub Flow Differs matters is that the following table compares GitHub Flow and Git Flow across key dimensions.

      +

      Alex: Start with Pros. There is something to understand, something to try, and something that proves the try worked.

      +

      Alex: The parts worth keeping in working memory are these. Works on all operating systems. Easy to set up for screen reader users (no command line required). Can be scoped to specific permissions. Easy to revoke if compromised.

      Alex: A solid pull request habit is to separate three questions: what changed, why it changed, and what still needs review. That keeps the conversation useful instead of noisy.

      +

      Alex: That matters because of the next idea. Start with Cons. There is something to understand, something to try, and something that proves the try worked.

      +

      Alex: On the ground, that means a few things. You have to store it securely. Expires after a set time (you must regenerate).

      +

      Alex: The useful habit is simple: orient first, act second, verify third. That pause before acting is part of the work.

      -

      Alex: Here is the practical turn. Start with When You Might See Git Flow. There is something to understand, something to try, and something that proves the try worked.

      -

      Alex: Here is what that changes in practice. 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.

      -

      Jamie: What belongs in the live room, and what can wait until after?

      -

      Alex: Here is the plain-English version of 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. Put another way, it is what GitHub itself uses and what most modern open source projects follow.

      -

      Alex: Keep the thread going. This is where The Unwritten Rule: One Thing Per Branch becomes real: a branch and its PR should do one thing. That matters in practice: If you are fixing a broken link and you notice a typo nearby, fix the typo in a separate branch and PR. The workshop is closer to rehearsal than lecture. You hear the move, try the move, and then check what changed.

      -
      +

      Jamie: If I am listening before the workshop starts, what should settle in my mind first?

      +

      Alex: Here is the plain-English version of SSH Keys. You generate a key pair on your computer (public + private), upload the public key to GitHub, and Git uses the private key to prove your identity.

      +

      Alex: This is where the talk moves from concept to action. Start with Pros. There is something to understand, something to try, and something that proves the try worked.

      +

      Alex: The room should hear these as checkpoints. Once set up, works automatically (no password prompts). More secure than tokens. Never expires.

      Jamie: Where do you want a learner to place their attention here?

      -

      Alex: Start with Learning Cards: GitHub Flow. There is something to understand, something to try, and something that proves the try worked.

      -

      Alex: These are the details that keep the idea from floating away. 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). 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.

      -

      Alex: Another way to ground it. The reason Keeping Your Fork Up to Date matters is that when you fork a repository, you get a snapshot of the project at that moment. That gives the learner a simple foothold: the original repository (called "upstream") continues to evolve.

      -

      Jamie: Give me the version that sounds like an instructor, not a manual.

      -

      Alex: Start with Why Sync Your Fork? There is something to understand, something to try, and something that proves the try worked.

      -

      Alex: That shows up in the workshop in a few specific ways. 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.

      +

      Alex: Start with Cons. There is something to understand, something to try, and something that proves the try worked.

      +

      Alex: These are the details that keep the idea from floating away. Requires command-line setup (less accessible for some screen reader users). Slightly more complex initial configuration.

      -

      Jamie: Let's pause on Method 1: GitHub Web Interface (Easiest). What should a learner take away from it?

      -

      Alex: Here is the plain-English version of Method 1: GitHub Web Interface (Easiest). GitHub merges the upstream changes into your fork automatically. Put another way, screen reader users (NVDA / JAWS / VoiceOver). It is like learning a transit route. The names of the stops matter because they tell you whether you are still going the right direction.

      -

      Alex: First, navigate to your fork's main page: github.com/your-username/repo-name. Then, look for the sync indicator: "This branch is X commits behind upstream/main". After that, click the "Sync fork" button. Finally, click "Update branch". Treat it like a recipe: do not add the next ingredient until the previous one is actually in the bowl.

      -

      Jamie: Before we leave Method 1: GitHub Web Interface (Easiest), what is the practical point?

      -

      Alex: First, the sync button appears in the landmark that contains the branch selector. Then, press D to cycle through landmarks until you reach that region. After that, press B to cycle buttons until you hear "Sync fork" → press Enter. Finally, a dialog or page update presents "Update branch" - activate it. It is a checklist, but a meaningful one: every item creates evidence that the next step is safe.

      -

      Jamie: What should someone listen for when a lesson offers more than one tool path?

      -

      Alex: This is where Method 2: Git Command Line (VS Code Terminal) becomes real: if you're working locally in VS Code.

      -

      Jamie: What should happen before anyone copies and runs it?

      -

      Alex: Start with One-time setup - add the upstream remote. There is something to understand, something to try, and something that proves the try worked.

      -

      Alex: Treat examples as spoken recipes, not decorations. You may hear something like git remote add upstream https://github.com/original-owner/repo-name.git; git remote -v Verify it was added. Read the command, understand what it changes, then run it only when the repository state matches the lesson.

      +

      Alex: Before the learner moves on. The reason Creating a Personal Access Token (Recommended for This Workshop) matters is that why this method: It's screen reader accessible through the GitHub web interface, and you can complete it without command-line Git configuration. The interface gets friendlier when it stops being a wall of controls and starts being a set of named places.

      +

      Jamie: Give me the sequence, because order matters here.

      +

      Alex: Start with Step 1: Generate the Token: The token appears as a long string in a text field. The next useful detail is this: Select all (Ctrl+A), copy (Ctrl+C), and paste it into a secure note or password manager.

      +

      Alex: A few details make that real. repo - Full control of private repositories (includes public repo access). workflow - Update GitHub Actions workflows (if you'll work with Actions).

      +

      Alex: First, navigate to github.com/settings/tokens. Then, select "Tokens (classic)" from the left sidebar. After that, activate "Generate new token" → Select "Generate new token (classic)". Finally, give it a descriptive name in the Note field: "Workshop Laptop Token". Think of it as a rail line: each stop confirms you are still on the right route before the next one.

      +

      Jamie: How would you walk the room through that step by step?

      +

      Alex: First, set expiration: 30 days or 60 days (recommended for temporary workshop use). Then, select scopes. After that, scroll down and activate "Generate token". Finally, cRITICAL: Copy the token immediately - you cannot see it again. Treat it like a recipe: do not add the next ingredient until the previous one is actually in the bowl.

      +

      Alex: Hold that next to this. Start with Options. There is something to understand, something to try, and something that proves the try worked.

      +

      Alex: For a learner, the useful signals are these. Password manager (1Password, Bitwarden, LastPass) - best option. Encrypted note in your operating system's secure notes. Plain text file in an encrypted folder (temporary only).

      -

      Jamie: What should they understand before typing anything?

      -

      Alex: Start with Sync process. There is something to understand, something to try, and something that proves the try worked.

      -

      Alex: Treat examples as spoken recipes, not decorations. You may hear something like 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. Read the command, understand what it changes, then run it only when the repository state matches the lesson.

      -

      Alex: Now bring the learner back to the room. Start with When to sync. There is something to understand, something to try, and something that proves the try worked.

      -

      Alex: The room should hear these as checkpoints. 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).

      -

      Jamie: Let's pause on Method 3: GitHub Desktop. What should a learner take away from it?

      -

      Alex: Start with Method 3: GitHub Desktop. There is something to understand, something to try, and something that proves the try worked.

      -

      Alex: First, open GitHub Desktop. Then, select Repository → Pull to get your fork's latest. After that, select Branch → Merge into Current Branch. Finally, choose upstream/main. Treat it like a recipe: do not add the next ingredient until the previous one is actually in the bowl.

      -

      Jamie: Before we leave Method 3: GitHub Desktop, what is the practical point?

      -

      Alex: First, push the changes to your fork on GitHub. It is a checklist, but a meaningful one: every item creates evidence that the next step is safe.

      +

      Jamie: Give me the version that sounds like an instructor, not a manual.

      +

      Alex: Start with Do not. There is something to understand, something to try, and something that proves the try worked.

      +

      Alex: Here is what that changes in practice. Paste it into a document you sync to cloud storage unencrypted. Email it to yourself. Save it in a public GitHub file.

      +

      Jamie: How do you keep commands from becoming magic words?

      +

      Alex: Keep the learner anchored in Step 3: Use It. The next time Git asks for your password (when you push, pull from a private repo, or clone a private repo). This is the part to say slowly: Windows Git Credential Manager: Windows will remember this token automatically after your first use. A good GitHub workflow is like a well-run meeting: everyone knows the topic, the next action, and who has the floor.

      +

      Alex: Treat examples as spoken recipes, not decorations. You may hear something like git config --global credential.helper cache. Read the command, understand what it changes, then run it only when the repository state matches the lesson.

      +

      Jamie: Let's pause on Setting Up SSH Keys (Alternative Method). What should a learner take away from it?

      +

      Alex: The reason Setting Up SSH Keys (Alternative Method) matters is that if you prefer SSH and are comfortable with terminal commands.

      -

      Alex: This is the part worth saying out loud. Start with Learning Cards: Keeping Your Fork Up to Date. There is something to understand, something to try, and something that proves the try worked.

      -

      Alex: That becomes easier when you listen for these cues. 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. 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.

      -

      Jamie: Let's pause on Writing Good Commit Messages. What should a learner take away from it?

      -

      Alex: Keep the learner anchored in Writing Good Commit Messages. Every commit you make includes a message describing what changed. This is the part to say slowly: Good commit messages make project history understandable months or years later.

      -

      Alex: That connects to another useful point. The reason The First Line (Required) matters is that this is the commit summary that appears in logs and GitHub's commit list. That gives the learner a simple foothold: think of it as an email subject line. The interface gets friendlier when it stops being a wall of controls and starts being a set of named places.

      -

      Alex: The parts worth keeping in working memory are these. fix: - bug fix. feat: - new feature. docs: - documentation only. style: - formatting, no code change.

      +

      Alex: Here is the practical turn. Start with Step 1: Check If You Already Have a Key: Look for files named id rsa.pub, id ed25519.pub, or similar. The next useful detail is this: If you see these, you already have a key.

      +

      Jamie: What should they understand before typing anything?

      +

      Alex: Here is the plain-English version of Step 2: Generate a New SSH Key. Git will print output showing where the key was saved. Put another way, it generates two files: id ed25519 (private) and id ed25519.pub (public).

      +

      Alex: That becomes easier when you listen for these cues. Press Enter to accept the default file location. Enter a passphrase (optional but recommended).

      +

      Alex: Treat examples as spoken recipes, not decorations. You may hear something like ssh-keygen -t ed25519 -C "your-email@example.com". Read the command, understand what it changes, then run it only when the repository state matches the lesson.

      +

      Jamie: What does the learner do first, second, and then after that?

      +

      Alex: Start with Step 4: Add to GitHub. There is something to understand, something to try, and something that proves the try worked.

      +

      Alex: First, navigate to github.com/settings/keys. Then, select "New SSH key". After that, key type: Authentication Key. Finally, key: Paste your public key (should start with ssh-ed25519 or ssh-rsa). It is a checklist, but a meaningful one: every item creates evidence that the next step is safe.

      +

      Jamie: Turn that into a path someone can follow.

      +

      Alex: First, select "Add SSH key". Then, confirm with your password or 2FA code. It is like walking a hallway with named doors: read the sign, enter the right room, then confirm where you landed.

      Jamie: What is the safe way to learn from that example?

      -

      Alex: Start with The Body (Optional): If the summary isn't enough, add a body explaining. The next useful detail is this: Leave a blank line between the summary and the body.

      -

      Alex: The practical takeaway is this. Why you made the change (more important than what). What trade-offs you considered. How the change affects behavior.

      -

      Alex: Treat examples as spoken recipes, not decorations. You may hear something like 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. Read the command, understand what it changes, then run it only when the repository state matches the lesson.

      -

      Alex: Keep the teaching thread moving. Here is the plain-English version of The Footer (Optional). When the commit is merged, GitHub automatically closes linked issues.

      -

      Jamie: Let's pause on Atomic Commits. What should a learner take away from it?

      -

      Alex: This is where Atomic Commits becomes real: each commit should represent one logical change. That matters in practice: Don't bundle unrelated fixes into a single commit.

      -
      -

      Alex: Keep the teaching thread moving. Start with Common mistakes to avoid. There is something to understand, something to try, and something that proves the try worked.

      -

      Alex: The practical takeaway is this. "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.

      -

      Jamie: How do you keep commands from becoming magic words?

      -

      Alex: The reason Good commit messages in practice matters is that when you make a habit of writing good commit messages, you build trust. That gives the learner a simple foothold: maintainers see that you care about the project's long-term health, not just your immediate contribution.

      -

      Alex: Treat examples as spoken recipes, not decorations. You may hear something like 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. Read the command, understand what it changes, then run it only when the repository state matches the lesson.

      -

      Alex: Keep the teaching thread moving. Start with Learning Cards: Writing Good Commit Messages. There is something to understand, something to try, and something that proves the try worked.

      -

      Alex: The practical takeaway is this. 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. 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.

      +

      Alex: Start with Step 5: Test the Connection. There is something to understand, something to try, and something that proves the try worked.

      +

      Alex: Treat examples as spoken recipes, not decorations. You may hear something like ssh -T git@github.com. Read the command, understand what it changes, then run it only when the repository state matches the lesson.

      +

      Jamie: What should happen before anyone copies and runs it?

      +

      Alex: The reason Step 6: Use SSH URLs matters is that when cloning or adding remotes, use SSH URLs instead of HTTPS.

      +

      Alex: Treat examples as spoken recipes, not decorations. You may hear something like SSH format; git@github.com:owner/repo.git; Instead of HTTPS; https://github.com/owner/repo.git. Read the command, understand what it changes, then run it only when the repository state matches the lesson.

      +

      Jamie: Let's pause on Switching Between HTTPS and SSH. What should a learner take away from it?

      +

      Alex: Start with Switching Between HTTPS and SSH: If you cloned with HTTPS but want to use SSH (or vice versa), update the remote.

      -

      Jamie: Let's pause on The Nature of Open Source Communication. What should a learner take away from it?

      -

      Alex: Here is the plain-English version of The Nature of Open Source Communication. Open source collaboration happens primarily in writing, asynchronously, in public. Put another way, understanding these three characteristics shapes everything about how we communicate.

      -

      Alex: Keep the teaching thread moving. Start with In writing. There is something to understand, something to try, and something that proves the try worked.

      -

      Alex: The practical takeaway is this. 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.".

      -

      Jamie: Let's pause on Asynchronously. What should a learner take away from it?

      -

      Alex: Start with Asynchronously. There is something to understand, something to try, and something that proves the try worked.

      -

      Alex: The practical takeaway is this. 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.

      +

      Jamie: Let's pause on Check your current remote. What should a learner take away from it?

      +

      Alex: Start with Check your current remote. There is something to understand, something to try, and something that proves the try worked.

      +

      Alex: Treat examples as spoken recipes, not decorations. You may hear something like git remote -v. Read the command, understand what it changes, then run it only when the repository state matches the lesson.

      +

      Jamie: Let's pause on Switch to SSH. What should a learner take away from it?

      +

      Alex: Start with Switch to SSH. There is something to understand, something to try, and something that proves the try worked.

      +

      Alex: Treat examples as spoken recipes, not decorations. You may hear something like git remote set-url origin git@github.com:your-username/repo.git. Read the command, understand what it changes, then run it only when the repository state matches the lesson.

      +

      Jamie: Let's pause on Switch to HTTPS. What should a learner take away from it?

      +

      Alex: Start with Switch to HTTPS. There is something to understand, something to try, and something that proves the try worked.

      +

      Alex: Treat examples as spoken recipes, not decorations. You may hear something like git remote set-url origin https://github.com/your-username/repo.git. Read the command, understand what it changes, then run it only when the repository state matches the lesson.

      -

      Alex: Keep the teaching thread moving. Start with In public. There is something to understand, something to try, and something that proves the try worked.

      -

      Alex: The practical takeaway is this. 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.

      Jamie: What do you want them to do when the plan breaks?

      -

      Alex: Start with The Anatomy of Helpful Feedback: Whether commenting on an issue, reviewing a PR, or responding to a question, effective feedback has a structure.

      -

      Alex: Keep the teaching thread moving. Here is the plain-English version of 1. Acknowledge what's working. Before identifying problems, name what is good. Put another way, this is not flattery - it is accuracy. It is like learning a transit route. The names of the stops matter because they tell you whether you are still going the right direction.

      -
      -

      Jamie: Let's pause on 2. Identify the specific concern. What should a learner take away from it?

      -

      Alex: This is where 2. Identify the specific concern becomes real: "This code is inaccessible." "This button has no accessible name - aria-label or visible text is needed for screen readers to announce its purpose.".

      -

      Alex: Keep the teaching thread moving. Keep the learner anchored in 3. Explain why it matters. Context turns a complaint into a lesson. This is the part to say slowly: It also respects the contributor - they deserve to understand, not just comply.

      -

      Jamie: Let's pause on 4. Suggest a path forward (when you can). What should a learner take away from it?

      -

      Alex: The reason 4. Suggest a path forward (when you can) matters is that if you have an idea for a solution, offer it as a suggestion, not a mandate. That gives the learner a simple foothold: "Something like aria-label='Close navigation menu' would work well here.

      +

      Alex: Start with Learning Cards: Troubleshooting Authentication. There is something to understand, something to try, and something that proves the try worked.

      +

      Alex: The practical takeaway is this. Each troubleshooting entry starts with the error message in quotes as an h3 heading -- press 3 to jump between errors. Solutions include terminal commands in code blocks -- switch to Focus Mode before copying them. If your error is not listed here, search the GitHub Docs authentication troubleshooting page. Error messages are displayed as bold h3 headings for easy visual scanning. Solution steps are numbered and include code blocks you can copy directly. If terminal output is hard to read, paste commands into VS Code's integrated terminal which respects your theme settings.

      +

      Alex: Keep the thread going. Start with "Authentication failed" when pushing: Problem: Your token expired or is incorrect. Think of it like entering a new building: first you find the lobby, then the room, then the door you actually need.

      +

      Jamie: Let's pause on Solution. What should a learner take away from it?

      +

      Alex: Start with Solution. There is something to understand, something to try, and something that proves the try worked.

      +

      Alex: The practical takeaway is this. Generate a new PAT. Clear your credential cache (Windows: Credential Manager; macOS: Keychain; Linux: git credential-cache exit). Try pushing again - Git will ask for credentials.

      -

      Alex: Keep the teaching thread moving. Start with 5. Signal the weight of the concern: Help contributors understand what is a blocker versus a preference. Think of it like entering a new building: first you find the lobby, then the room, then the door you actually need.

      -

      Alex: The practical takeaway is this. 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.

      -

      Jamie: Let's pause on Prefer "we" or describe the code, not the person. What should a learner take away from it?

      -

      Alex: Here is the plain-English version of 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.".

      -

      Alex: Keep the teaching thread moving. This is where Use tentative language for uncertainty becomes real: "This will crash on mobile." "I think this might cause issues on mobile - have you tested with a narrower viewport?".

      +

      Alex: Another way to ground it. This is where "Permission denied (publickey)" becomes real: problem: SSH key not properly set up.

      +

      Jamie: Before we leave Solution, what is the practical point?

      +

      Alex: The practical takeaway is this. Verify your key is added to GitHub: github.com/settings/keys. Check SSH agent is running: ssh-add -l. Add your key to the agent: ssh-add /.ssh/id ed25519.

      +

      Alex: This is the part worth saying out loud. The reason "Host key verification failed" matters is that problem: SSH doesn't recognize GitHub's host key. The interface gets friendlier when it stops being a wall of controls and starts being a set of named places.

      -

      Jamie: Let's pause on Acknowledge cultural and language diversity. What should a learner take away from it?

      -

      Alex: Keep the learner anchored in Acknowledge cultural and language diversity. When reading someone's comment: Assume good intent unless there is clear evidence otherwise. This is the part to say slowly: When writing: Choose plain words over clever ones.

      -

      Alex: The practical takeaway is this. 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.

      -

      Alex: Keep the teaching thread moving. The reason Avoid urgency markers unless genuinely urgent matters is that "I need this fixed ASAP" "This is blocking our release scheduled for next Friday - is there capacity to look at it this week?". The interface gets friendlier when it stops being a wall of controls and starts being a set of named places.

      -

      Jamie: Let's pause on Keep comments focused. What should a learner take away from it?

      -

      Alex: Start with Keep comments focused: Each comment should address one concern. The next useful detail is this: If you have three issues, leave three comments - unless they are closely related.

      +

      Jamie: What is the teaching move inside Solution?

      +

      Alex: Treat examples as spoken recipes, not decorations. You may hear something like ssh-keyscan github.com /.ssh/known hosts. Read the command, understand what it changes, then run it only when the repository state matches the lesson.

      +

      Jamie: What is the ordered workflow?

      +

      Alex: Start with Security Best Practices. There is something to understand, something to try, and something that proves the try worked.

      +

      Alex: First, never share your private key or PAT - treat them like passwords. Then, use scoped PATs - only grant the minimum permissions needed. After that, set expiration dates on PATs - regenerate periodically. Finally, use a passphrase on SSH keys - adds another layer of security. Treat it like a recipe: do not add the next ingredient until the previous one is actually in the bowl.

      +

      Jamie: Let's pause on Security Best Practices. What should a learner take away from it?

      +

      Alex: First, revoke old tokens when you're done with a project or device. Then, don't commit tokens or keys to Git - use.gitignore for config files. It is a checklist, but a meaningful one: every item creates evidence that the next step is safe.

      +

      Jamie: Let's pause on Commit Signing - Verified Badges and Vigilant Mode. What should a learner take away from it?

      +

      Alex: This is where Commit Signing - Verified Badges and Vigilant Mode becomes real: when you push commits to GitHub, each commit shows a small badge: Verified or Unverified. That matters in practice: This badge tells anyone viewing the commit history whether the commit was cryptographically signed - proving it came from you and was not tampered with.

      +

      Alex: A solid Git habit is to know which branch you are on, what changed, and what confirmation you expect before you run the next command.

      -

      Alex: Keep the teaching thread moving. Here is the plain-English version of Don't leave comments unresolved. If you asked a question and got an answer, respond. Put another way, "Thanks, that makes sense" or resolving the conversation thread signals that the thread is complete.

      -

      Jamie: Let's pause on Resolving conversations. What should a learner take away from it?

      -

      Alex: This is where Resolving conversations becomes real: on a PR, conversations (inline comment threads) can be "resolved" once addressed. That matters in practice: The author of the change and the reviewer can both resolve them.

      -

      Alex: Keep the teaching thread moving. Keep the learner anchored in 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. This is the part to say slowly: A reaction on an existing comment is enough. A good GitHub workflow is like a well-run meeting: everyone knows the topic, the next action, and who has the floor.

      +

      Alex: That connects to another useful point. Keep the learner anchored in Why It Matters. Open source maintainers increasingly require signed commits before merging. This is the part to say slowly: Some repositories enforce this with branch protection rules. A good GitHub workflow is like a well-run meeting: everyone knows the topic, the next action, and who has the floor.

      +

      Jamie: Let's pause on SSH Signing (simpler - reuses your existing SSH key). What should a learner take away from it?

      +

      Alex: The reason SSH Signing (simpler - reuses your existing SSH key) matters is that if you already have an SSH key set up for authentication, you can use it for signing too. That gives the learner a simple foothold: step 1: Configure Git to use SSH for signing.

      +

      Alex: First, navigate to github.com/settings/ssh. Then, select "New SSH key". After that, change "Key type" to "Signing Key" (not Authentication Key). Finally, paste your public key and save. The rhythm is simple: orient, act, verify, then continue.

      +

      Alex: Treat examples as spoken recipes, not decorations. You may hear something like git config --global gpg.format ssh; git config --global user.signingkey /.ssh/id ed25519.pub; git config --global commit.gpgsign true. Read the command, understand what it changes, then run it only when the repository state matches the lesson.

      +

      Jamie: Let's pause on GPG Signing (traditional method). What should a learner take away from it?

      +

      Alex: Start with GPG Signing (traditional method). There is something to understand, something to try, and something that proves the try worked.

      +

      Alex: Treat examples as spoken recipes, not decorations. You may hear something like gpg --full-generate-key; Choose: RSA and RSA, 4096 bits, never expires; Enter your GitHub email address when prompted. Read the command, understand what it changes, then run it only when the repository state matches the lesson.

      -

      Jamie: Let's pause on Reactions. What should a learner take away from it?

      -

      Alex: The reason Reactions matters is that GitHub reactions () are an efficient way to express agreement, appreciation, or concern without adding noise to a thread.

      -

      Alex: Keep the teaching thread moving. Start with 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. The next useful detail is this: This is a significant accessibility win for anyone who types the same comments repeatedly during triage, reviews, or issue management.

      -

      Jamie: Let's pause on Common uses. What should a learner take away from it?

      -

      Alex: Start with Common uses. There is something to understand, something to try, and something that proves the try worked.

      -

      Alex: The practical takeaway is this. "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.

      +

      Jamie: Let's pause on Step 4: Add to GitHub. What should a learner take away from it?

      +

      Alex: First, navigate to github.com/settings/gpg-keys. Then, select "New GPG key" → paste the exported public key. Treat it like a recipe: do not add the next ingredient until the previous one is actually in the bowl.

      +

      Jamie: Let's pause on Step 5: Configure Git to sign all commits. What should a learner take away from it?

      +

      Alex: Start with Step 5: Configure Git to sign all commits. There is something to understand, something to try, and something that proves the try worked.

      +

      Alex: Treat examples as spoken recipes, not decorations. You may hear something like git config --global user.signingkey YOUR KEY ID; git config --global commit.gpgsign true. Read the command, understand what it changes, then run it only when the repository state matches the lesson.

      +

      Jamie: Let's pause on Vigilant Mode. What should a learner take away from it?

      +

      Alex: Keep the learner anchored in Vigilant Mode. GitHub has an optional setting called Vigilant Mode (in Settings → SSH and GPG Keys → Vigilant mode). This is the part to say slowly: When enabled, GitHub marks all commits from your account as "Unverified" unless they are signed - even commits that were previously shown without a badge.

      -

      Jamie: Let's pause on Creating a Saved Reply. What should a learner take away from it?

      -

      Alex: Start with Creating a Saved Reply. There is something to understand, something to try, and something that proves the try worked.

      -

      Alex: First, navigate to github.com/settings/replies. Then, activate "Add a saved reply". After that, give it a title (e.g., "Good first issue claim") - this is what you search. Finally, type the full reply text in the body (Markdown is supported). It is a checklist, but a meaningful one: every item creates evidence that the next step is safe.

      -

      Jamie: Let's pause on Using a Saved Reply in a comment. What should a learner take away from it?

      -

      Alex: Start with Using a Saved Reply in a comment. There is something to understand, something to try, and something that proves the try worked.

      -

      Alex: First, navigate to any comment text area. Then, activate the Saved Replies button (the speech bubble icon in the comment toolbar, or press Ctrl+. if enabled). After that, a dropdown appears showing your saved replies - type to filter by title. Finally, select the reply - it inserts into the text area. It is like walking a hallway with named doors: read the sign, enter the right room, then confirm where you landed.

      -

      Jamie: Before we leave Using a Saved Reply in a comment, what is the practical point?

      -

      Alex: First, edit as needed before submitting. The rhythm is simple: orient, act, verify, then continue.

      -

      Alex: Keep the teaching thread moving. The reason Screen reader path matters is that limit: GitHub allows up to 100 saved replies per account.

      +

      Alex: Keep the teaching thread moving. Start with Why some maintainers enable Vigilant Mode. There is something to understand, something to try, and something that proves the try worked.

      +

      Alex: The practical takeaway is this. It makes tampered or spoofed commits immediately obvious. It signals that the repository cares about commit provenance.

      +

      Jamie: Let's pause on What you see as a contributor. What should a learner take away from it?

      +

      Alex: Start with What you see as a contributor. There is something to understand, something to try, and something that proves the try worked.

      +

      Alex: The practical takeaway is this. Every unsigned commit you push will show a yellow "Unverified" badge. This is a visual signal - commits can still be pushed, but maintainers may block the merge.

      +

      Alex: Keep the teaching thread moving. Here is the plain-English version of To read verification badges with a screen reader. Workshop recommendation: SSH signing is simpler to set up than GPG and reuses your existing key. Put another way, if you have 10 minutes, configure it before Day 2 - every commit you push to accessibility-agents will show as Verified. It is like learning a transit route. The names of the stops matter because they tell you whether you are still going the right direction.

      +

      Alex: The practical takeaway is this. Navigate to the repository's commit history (Code tab → Commits link). Each commit row contains either "Verified" or "Unverified" as a badge element. NVDA/JAWS: the badge is inside the commit row; use ↓ to read through each row and the badge text is read inline. VoiceOver: use VO+Right through the commit row; the badge is read as a button with the text "Verified" (clicking it shows the certificate).

      Alex: A solid navigation habit is to prove where you are before activating controls. Headings, landmarks, and the address bar are not trivia; they are your map.

      -

      Jamie: Let's pause on Learning Cards: Commenting Etiquette. What should a learner take away from it?

      -

      Alex: Start with Learning Cards: Commenting Etiquette. There is something to understand, something to try, and something that proves the try worked.

      -

      Alex: The practical takeaway is this. 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. 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.

      -

      Alex: Keep the teaching thread moving. Here is the plain-English version of 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.". It is like learning a transit route. The names of the stops matter because they tell you whether you are still going the right direction.

      -

      Jamie: Let's pause on Don't gatekeep knowledge. What should a learner take away from it?

      -

      Alex: This is where Don't gatekeep knowledge becomes real: if a contributor makes a mistake because they didn't know something, explain the concept.

      -
      -

      Alex: Keep the teaching thread moving. Keep the learner anchored in Ask questions instead of making demands. "Change this to use aria-label." "What do you think about using aria-label here instead? This is the part to say slowly: Screen readers would then announce the button's purpose directly.".

      -

      Jamie: Let's pause on Distinguish opinion from requirement. What should a learner take away from it?

      -

      Alex: The reason Distinguish opinion from requirement matters is that if something is your stylistic preference but NOT a bug or correctness issue, say so. That gives the learner a simple foothold: "The current implementation is correct.

      -

      Alex: Keep the teaching thread moving. Start with 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! Think of it like entering a new building: first you find the lobby, then the room, then the door you actually need.

      +

      Jamie: Let's pause on Recommended approach. What should a learner take away from it?

      +

      Alex: This is where Recommended approach becomes real: sSH keys are great for long-term use, but PATs are faster to set up and more accessible for screen reader users during a time-constrained workshop. That matters in practice: Next: Appendix E: Advanced Git Back: Appendix C: Markdown Reference Teaching chapter: Chapter 00: Pre-Workshop Setup.

      +

      Alex: First, generate a Personal Access Token with 30-day expiration. Then, scope: repo and workflow. After that, store it in your password manager. Finally, use it when VS Code or Git asks for a password. It is a checklist, but a meaningful one: every item creates evidence that the next step is safe.

      -

      Jamie: Let's pause on Say thank you. What should a learner take away from it?

      -

      Alex: Here is the plain-English version of Say thank you. When someone takes time to review your work, acknowledge it - even if you disagree with some feedback. Put another way, "Thanks so much for the thorough review!

      -

      Alex: Keep the teaching thread moving. This is where Don't take feedback personally becomes real: code review is about the code, not your worth as a person or developer. That matters in practice: Even the most senior contributors receive change requests.

      -

      Jamie: Let's pause on Explain your choices. What should a learner take away from it?

      -

      Alex: Keep the learner anchored in Explain your choices. If you are keeping your implementation despite feedback, explain why. This is the part to say slowly: "I considered aria-label here, but I went with a visually-hidden instead because it allows translators to localize the text more easily.

      +

      Jamie: What should people carry with them after this?

      +

      Alex: Carry the map. Know what page or tool you are in, know which action you are taking, and know what confirmation should follow. If the confirmation is missing, pause. That pause is not wasted time; it is professional judgment.

      +

      Jamie: That is a better way to say it than just follow the steps.

      +

      Alex: Right. Steps matter, but understanding wins. That is episode 21. Next in the series is episode 22, where we keep building the same contributor muscles.

      +
      +
      -

      Alex: Keep the teaching thread moving. The reason Surface blockers early matters is that don't wait until you have finished a 500-line PR to mention that you weren't sure about the approach. The interface gets friendlier when it stops being a wall of controls and starts being a set of named places.

      -

      Jamie: Let's pause on Inclusive Commenting for Accessibility Issues. What should a learner take away from it?

      -

      Alex: Start with Inclusive Commenting for Accessibility Issues: When filing or discussing accessibility bugs, additional context helps.

      -

      Alex: The practical takeaway is this. 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.

      -

      Alex: A solid issue habit is to read the title, the body, and the timeline before acting. You are listening for the requested action, the missing evidence, and the person who needs a response.

      -

      Jamie: Let's pause on The "Good First Issue" Social Contract. What should a learner take away from it?

      -

      Alex: Here is the plain-English version of The "Good First Issue" Social Contract. When a maintainer labels an issue good first issue, they are. Put another way, when you take a good first issue, your responsibilities.

      -

      Alex: The practical takeaway is this. Investing time - good first issues require extra documentation and mentorship. Signaling welcome - they want to support a new contributor.

      -

      Alex: First, comment to claim it - "Hi, I'd like to work on this. Can I be assigned?". Then, wait for assignment - do not start until assigned; two people working in parallel wastes everyone's time. After that, 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?". Finally, 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?". Treat it like a recipe: do not add the next ingredient until the previous one is actually in the bowl.

      -

      Jamie: Before we leave The "Good First Issue" Social Contract, what is the practical point?

      -

      Alex: First, don't disappear - if you claim an issue, see it through or explicitly hand it back. It is a checklist, but a meaningful one: every item creates evidence that the next step is safe.

      +

      33. Episode 46: How Git Works: The Mental Model

      +

      Commits, branches, staging, local versus remote, push, pull, fetch, and why conflicts happen.

      +

      Based on: Chapter 13: How Git Works: The Mental Model

      +

      Audio and transcript are being regenerated for this episode.

      +
      +Read Transcript - Episode 46: How Git Works: The Mental Model + +

      Transcript

      +

      Alex: This is Git Going with GitHub, episode 46: How Git Works: The Mental Model. I am Alex. By the end of this episode, How Git Works: The Mental Model should feel less like a wall of GitHub words and more like a set of moves you can trust.

      +

      Jamie: And I am Jamie. I am here for the practical questions: what should I listen for, what can go wrong, and what is the next calm move?

      -

      Jamie: Let's pause on When you receive harsh feedback. What should a learner take away from it?

      -

      Alex: Start with When you receive harsh feedback. There is something to understand, something to try, and something that proves the try worked.

      -

      Alex: First, take a breath before responding - there is no urgency; the thread will wait. Then, look for the valid concern underneath the harsh words. After that, respond to the concern, not the tone. Finally, if the behavior crosses into harassment, report it via the "." button on the comment → "Report". It is a checklist, but a meaningful one: every item creates evidence that the next step is safe.

      -

      Jamie: Let's pause on When you disagree with a decision. What should a learner take away from it?

      -

      Alex: Start with When you disagree with a decision. There is something to understand, something to try, and something that proves the try worked.

      -

      Alex: First, make your case once, clearly and with evidence. Then, accept that the maintainer has the final say in their project. After that, if you strongly disagree, you can fork the project and take it in a different direction - this is legitimate in open source. It is like walking a hallway with named doors: read the sign, enter the right room, then confirm where you landed.

      -

      Jamie: Let's pause on When someone is rude to you. What should a learner take away from it?

      -

      Alex: Start with When someone is rude to you. There is something to understand, something to try, and something that proves the try worked.

      -

      Alex: First, you do not have to engage. Then, 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.". After that, report via GitHub's reporting tools if the behavior is abusive. The rhythm is simple: orient, act, verify, then continue.

      +

      Alex: Today we are working on this: Commits, branches, staging, local versus remote, push, pull, fetch, and why conflicts happen. I want the learner to leave with a mental map, not just a remembered path through buttons.

      +

      Jamie: So the goal is understanding first, then action, then confirmation.

      +

      Alex: Right. We are building a rhythm: orient yourself, take one intentional action, then verify what changed before moving on.

      -

      Jamie: Let's pause on When you accidentally caused offense. What should a learner take away from it?

      -

      Alex: Start with When you accidentally caused offense. There is something to understand, something to try, and something that proves the try worked.

      -

      Alex: First, acknowledge it directly: "I can see how that came across as dismissive - that wasn't my intention.". Then, do not over-explain or defend excessively. After that, adjust going forward. Think of it as a rail line: each stop confirms you are still on the right route before the next one.

      -

      Jamie: Let's pause on Writing Your First README. What should a learner take away from it?

      -

      Alex: Here is the plain-English version of Writing Your First README. See also: Appendix W: GitHub Pages for publishing your README as a website. Put another way, a README is the front door of your project.

      -

      Alex: Keep the teaching thread moving. This is where What belongs in a README becomes real: every README should answer these questions, roughly in this order. That matters in practice: 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. The workshop is closer to rehearsal than lecture. You hear the move, try the move, and then check what changed.

      +

      Jamie: Okay, set the room for us. What are we walking into?

      +

      Alex: Start with 1. Why a Mental Model Matters: On Day 1, you edited files on GitHub.com using the web editor. The next useful detail is this: GitHub handled Git for you behind the scenes -- creating commits, managing branches, and tracking changes.

      +

      Alex: The next layer is this. Here is the plain-English version of 2. The Three Areas: Working Directory, Staging Area, Repository. Git organizes your work into three areas. Put another way, understanding these three areas is the single most important concept in this chapter. It is like learning a transit route. The names of the stops matter because they tell you whether you are still going the right direction.

      +

      Jamie: What is the one idea that makes the next few steps less mysterious?

      +

      Alex: This is where Working directory becomes real: the working directory is the folder on your computer where the files live. That matters in practice: When you open a project in VS Code, everything you see in the file explorer is the working directory.

      -

      Jamie: Let's pause on Accessibility in READMEs. What should a learner take away from it?

      -

      Alex: Keep the learner anchored in Accessibility in READMEs. Your README is a web page -- GitHub renders it as HTML. This is the part to say slowly: That means the same accessibility rules apply.

      -

      Alex: The practical takeaway is this. Alt text for images and badges. A badge that says is invisible to screen readers. Write 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 -- not Click here.

      -

      Alex: Keep the teaching thread moving. The reason Good README vs. bad README matters is that bad: A single paragraph that says "This is my project. That gives the learner a simple foothold: run it with npm start." No headings, no license, no description of what the project does.

      -

      Jamie: Let's pause on Learning Cards: Writing Your First README. What should a learner take away from it?

      -

      Alex: Start with Learning Cards: Writing Your First README. There is something to understand, something to try, and something that proves the try worked.

      -

      Alex: The practical takeaway is this. 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: rather than an empty that reads as "image" with no context. Use real Markdown link text (installation guide) instead of bare URLs, so your screen reader announces the destination rather than spelling out a long URL. 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.

      +

      Alex: Now bring the learner back to the room. Keep the learner anchored in Staging area (also called the index). The staging area is a holding zone. This is the part to say slowly: When you are happy with a change in the working directory, you add it to the staging area.

      +

      Jamie: What would you say to someone who is already bracing for this to be too much?

      +

      Alex: The reason Repository (the.git folder) matters is that the repository is Git's permanent record. That gives the learner a simple foothold: 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.

      +

      Alex: A solid Git habit is to know which branch you are on, what changed, and what confirmation you expect before you run the next command.

      +

      Jamie: Give me the sequence, because order matters here.

      +

      Alex: Start with How the three areas connect: Many visual Git tutorials use diagrams with arrows to show this flow. The next useful detail is this: The text description above and the three-step sequence are the same information without requiring a visual representation. Think of it like entering a new building: first you find the lobby, then the room, then the door you actually need.

      +

      Alex: First, edit files in the working directory. Then, stage the changes you want to keep (add to the staging area). After that, commit the staged changes (save to the repository). Think of it as a rail line: each stop confirms you are still on the right route before the next one.

      +

      Alex: The useful habit is simple: orient first, act second, verify third. That pause before acting is part of the work.

      -

      Alex: Keep the teaching thread moving. Here is the plain-English version of Community Health Files. Community health files tell contributors how your project operates before they write a single line of code. Put another way, 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. It is like learning a transit route. The names of the stops matter because they tell you whether you are still going the right direction.

      -

      Jamie: Let's pause on CONTRIBUTING.md. What should a learner take away from it?

      -

      Alex: This is where CONTRIBUTING.md becomes real: this file answers the question every newcomer asks: "How do I help?" A good CONTRIBUTING.md covers. That matters in practice: A sentence like "We are glad you are here" costs nothing and signals that newcomers are expected, not tolerated.

      -

      Alex: The practical takeaway is this. 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.

      -

      Alex: Keep the teaching thread moving. Keep the learner anchored in CODE OF CONDUCT.md. A code of conduct sets the social contract for your project. This is the part to say slowly: Without one, "acceptable behavior" is whatever each participant assumes it is -- and those assumptions vary widely.

      -

      Alex: The practical takeaway is this. 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.

      +

      Jamie: If I am listening before the workshop starts, what should settle in my mind first?

      +

      Alex: Here is the plain-English version of An analogy: packing a box. Think of it like packing a box to mail. Put another way, 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).

      +

      Alex: Here is what that changes in practice. 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.

      +

      Alex: This is where the talk moves from concept to action. Start with Learning Cards: The Three Areas. There is something to understand, something to try, and something that proves the try worked.

      +

      Alex: The room should hear these as checkpoints. 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. 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.

      +

      Jamie: Where do you want a learner to place their attention here?

      +

      Alex: Keep the learner anchored in 3. What Is a Commit? A commit is a snapshot of your project at a specific moment in time. This is the part to say slowly: It is not a diff (a list of changes).

      -

      Jamie: Let's pause on SECURITY.md. What should a learner take away from it?

      -

      Alex: The reason SECURITY.md matters is that see also: Appendix F: Git Security and Appendix P: Security Features for security best practices. That gives the learner a simple foothold: if someone discovers a vulnerability in your project, you do not want them to file a public issue.

      -

      Alex: The practical takeaway is this. 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.

      -

      Alex: Keep the teaching thread moving. Start with 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. The next useful detail is this: Adding a LICENSE file is a one-time step that makes your project genuinely open source. Think of it like entering a new building: first you find the lobby, then the room, then the door you actually need.

      -

      Jamie: Let's pause on Finding these files on GitHub. What should a learner take away from it?

      -

      Alex: Here is the plain-English version of Finding these files on GitHub. Navigate to any repository and click Insights then Community Standards. Put another way, GitHub shows a checklist of which community health files are present and links to add any that are missing.

      +

      Alex: Before the learner moves on. The reason Commit IDs (hashes) matters is that every commit gets a unique identifier -- a 40-character string called a SHA hash. That gives the learner a simple foothold: in practice, you usually see only the first 7 characters: a1b2c3d. The interface gets friendlier when it stops being a wall of controls and starts being a set of named places.

      +

      Jamie: Give me the version that sounds like an instructor, not a manual.

      +

      Alex: Start with Commits are permanent (mostly): Once a commit is made, it is part of the repository's history. The next useful detail is this: You can make new commits that undo the changes, but the original commit still exists in the timeline.

      +

      Alex: Hold that next to this. Start with Learning Cards: Commits. There is something to understand, something to try, and something that proves the try worked.

      +

      Alex: The practical anchors are these. 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. 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.

      -

      Alex: Keep the teaching thread moving. Start with Learning Cards: Community Health Files. There is something to understand, something to try, and something that proves the try worked.

      -

      Alex: The practical takeaway is this. 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. 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.

      -

      Jamie: How should someone choose between those options?

      -

      Alex: Keep the learner anchored in When to Use Different Communication Channels. GitHub Discussions are separate from Issues. This is the part to say slowly: Use Discussions for: "What do people think about X approach?" and Issues for: "The X button is broken.".

      -

      Alex: Use the comparison to make a decision, not to recite a table. The main contrasts are: PR comment means Feedback on a specific code change. PR review means Formal verdict (approve/request changes) with consolidated feedback. Discussion means Open-ended conversation, proposals, community Q&A.

      -

      Jamie: Let's pause on Try It: Rewrite One Comment. What should a learner take away from it?

      -

      Alex: The reason Try It: Rewrite One Comment matters is that time: 2 minutes What you need: Just your brain. That gives the learner a simple foothold: read this code review comment and rewrite it to be constructive. The interface gets friendlier when it stops being a wall of controls and starts being a set of named places.

      -

      Alex: First, what you noticed. Then, why it matters. After that, what you suggest. Finally, why the suggestion helps. The rhythm is simple: orient, act, verify, then continue.

      -

      Jamie: Before we leave Try It: Rewrite One Comment, what is the practical point?

      -

      Alex: First, encouragement. Think of it as a rail line: each stop confirms you are still on the right route before the next one.

      +

      Jamie: Let's pause on 4. What Is a Branch? What should a learner take away from it?

      +

      Alex: This is where 4. What Is a Branch? becomes real: see also: Chapter 14: Git in Practice shows how to create and switch branches hands-on in VS Code. That matters in practice: A branch is a name that points to a specific commit.

      +

      Alex: That connects to another useful point. Keep the learner anchored in The default branch: main. Every repository has a default branch, usually called main. This is the part to say slowly: 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. A good GitHub workflow is like a well-run meeting: everyone knows the topic, the next action, and who has the floor.

      +

      Jamie: Let's pause on Creating a branch. What should a learner take away from it?

      +

      Alex: The reason Creating a branch matters is that when you create a new branch, Git creates a new pointer that starts at the same commit you are currently on. That gives the learner a simple foothold: both branches point to the same commit.

      -

      Jamie: Let's pause on Contributing to Open Source. What should a learner take away from it?

      -

      Alex: Start with Contributing to Open Source: This section was previously Appendix T. The next useful detail is this: It is now part of the teaching narrative.

      -

      Alex: Keep the teaching thread moving. Here is the plain-English version of A Guide for First-Time Contributors. You do not need to be a professional developer to contribute to open source. Put another way, documentation, accessibility improvements, and bug reports are among the most valuable contributions any project can receive.

      -

      Jamie: Let's pause on 1. What Is Open Source? What should a learner take away from it?

      -

      Alex: This is where 1. What Is Open Source? becomes real: open source software is software whose source code is publicly available. That matters in practice: Anyone can read it, use it, and - in most cases - contribute to it.

      -

      Alex: The practical takeaway is this. 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.

      +

      Alex: Here is the practical turn. Start with 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 next useful detail is this: The main pointer stays where it was.

      +

      Jamie: Let's pause on HEAD: which branch are you on? What should a learner take away from it?

      +

      Alex: Here is the plain-English version of HEAD: which branch are you on? Git uses a special pointer called HEAD to track which branch you are currently working on. Put another way, when you switch branches (checkout), Git moves HEAD to point to the new branch and updates the files in your working directory to match.

      +

      Alex: Keep the thread going. Start with Learning Cards: Branches. There is something to understand, something to try, and something that proves the try worked.

      +

      Alex: These are the details that keep the idea from floating away. 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. 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.

      -

      Alex: Keep the teaching thread moving. Keep the learner anchored in 2. Who Can Contribute? Contributors come from all backgrounds, skill levels, and countries. This is the part to say slowly: 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. A good GitHub workflow is like a well-run meeting: everyone knows the topic, the next action, and who has the floor.

      -

      Jamie: Let's pause on 3. What Makes a Good First Contribution? What should a learner take away from it?

      -

      Alex: Start with 3. What Makes a Good First Contribution? There is something to understand, something to try, and something that proves the try worked.

      -

      Alex: The practical takeaway is this. 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.

      -

      Alex: Keep the teaching thread moving. Start with Signs a contribution is too large for a first attempt: A well-executed small contribution is far more valuable than a large contribution that cannot be merged because it is out of scope.

      -

      Alex: The practical takeaway is this. 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.

      +

      Jamie: Let's pause on 5. Local vs Remote. What should a learner take away from it?

      +

      Alex: Keep the learner anchored in 5. Local vs Remote. See also: Appendix D: Git Authentication covers how to set up credentials so push and pull work without password prompts. This is the part to say slowly: So far, we have talked about one repository.

      +

      Alex: Another way to ground it. The reason The remote repository matters is that the remote repository is the one on GitHub.com. That gives the learner a simple foothold: when you see a repository URL like github.com/Community-Access/git-going-with-github, that is the remote.

      +

      Jamie: Let's pause on The local repository. What should a learner take away from it?

      +

      Alex: Start with The local repository: The local repository is the copy on your computer. The next useful detail is this: When you run git clone, Git downloads the entire repository -- all files, all branches, all history -- to your machine.

      -

      Jamie: Let's pause on 4. Finding Something to Work On. What should a learner take away from it?

      -

      Alex: Here is the plain-English version of 4. Finding Something to Work On. Most open source projects label issues that are suitable for new contributors. Put another way, how to search: On any GitHub repository, go to Issues → filter by label.

      -

      Alex: Keep the teaching thread moving. Start with Learning Cards: Finding Something to Work On. There is something to understand, something to try, and something that proves the try worked.

      -

      Alex: The practical takeaway is this. 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. 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.

      -

      Jamie: What is the pre-flight check here?

      -

      Alex: Keep the learner anchored in 5. Reading an Issue Before You Start. Before commenting "I'll take this" on an issue, ask yourself. This is the part to say slowly: 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.

      -

      Alex: The practical takeaway is this. 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.

      +

      Alex: This is the part worth saying out loud. Here is the plain-English version of The two-copy model. The text diagram above shows two boxes side by side connected by arrows. Put another way, the left box is labeled "Your computer (local)" and contains working directory, staging area, and repository. It is like learning a transit route. The names of the stops matter because they tell you whether you are still going the right direction.

      +

      Jamie: Let's pause on Learning Cards: Local vs Remote. What should a learner take away from it?

      +

      Alex: Start with Learning Cards: Local vs Remote. There is something to understand, something to try, and something that proves the try worked.

      +

      Alex: That shows up in the workshop in a few specific ways. 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. 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.

      +

      Alex: That matters because of the next idea. Keep the learner anchored in 6. Push, Pull, and Fetch. These three operations keep your local and remote repositories synchronized.

      +

      Alex: A solid pull request habit is to separate three questions: what changed, why it changed, and what still needs review. That keeps the conversation useful instead of noisy.

      -

      Jamie: Let's pause on Tool Cards: Fork, Clone, and Contribute. What should a learner take away from it?

      -

      Alex: Start with Tool Cards: Fork, Clone, and Contribute. There is something to understand, something to try, and something that proves the try worked.

      -

      Alex: First, click Fork on the repository page, then Create fork. Then, edit files directly in your fork's web interface. After that, click Contribute Open pull request to submit back to the original. Finally, fork the repo on github.com first. The rhythm is simple: orient, act, verify, then continue.

      -

      Jamie: Before we leave Tool Cards: Fork, Clone, and Contribute, what is the practical point?

      -

      Alex: First, navigate to your fork and press. to open in the web editor. Then, edit, commit, and create a PR from the Source Control panel. After that, fork on github.com, then clone your fork: Ctrl+Shift+P Git: Clone. Finally, create a branch, make edits, commit and push. Think of it as a rail line: each stop confirms you are still on the right route before the next one.

      -

      Alex: Treat examples as spoken recipes, not decorations. You may hear something like 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. Read the command, understand what it changes, then run it only when the repository state matches the lesson.

      -

      Jamie: Let's pause on The Basic Workflow. What should a learner take away from it?

      -

      Alex: Start with The Basic Workflow. There is something to understand, something to try, and something that proves the try worked.

      -

      Alex: First, fork the repository - creates your own copy on GitHub. Then, clone your fork to your computer (or open a Codespace - see Appendix N). After that, create a branch - name it something descriptive: fix/broken-link-setup-guide. Finally, make your change - edit the file, save, verify. Think of it as a rail line: each stop confirms you are still on the right route before the next one.

      -

      Jamie: Before we leave The Basic Workflow, what is the practical point?

      -

      Alex: First, commit with a clear message - "Fix broken link in setup-guide.md line 34". Then, push to your fork. After that, open a pull request from your branch to the original repository's default branch. Finally, respond to review feedback - maintainers may ask for changes; this is normal and not a rejection. Treat it like a recipe: do not add the next ingredient until the previous one is actually in the bowl.

      -

      Alex: Keep the teaching thread moving. Here is the plain-English version of Writing a Good PR Description. Example: Fixed a broken link on line 34 of setup-guide.md. Put another way, the link pointed to /docs/old-setup which no longer exists. It is like learning a transit route. The names of the stops matter because they tell you whether you are still going the right direction.

      -

      Alex: The practical takeaway is this. What did you change? Why was the change needed? How did you verify it works?

      +

      Jamie: What should they understand before typing anything?

      +

      Alex: The reason Push: share your work matters is that git push sends your local commits to the remote. That gives the learner a simple foothold: after pushing, anyone who looks at the repository on GitHub.com will see your changes.

      +

      Alex: Treat examples as spoken recipes, not decorations. You may hear something like git push origin fix/typo. git push -u origin fix/typo. Read the command, understand what it changes, then run it only when the repository state matches the lesson.

      +

      Jamie: How do you keep commands from becoming magic words?

      +

      Alex: Start with Pull: get other people's work: git pull downloads new commits from the remote and immediately merges them into your current branch. The next useful detail is this: This is how you get changes that other people (or you on another computer) have pushed. Think of it like entering a new building: first you find the lobby, then the room, then the door you actually need.

      +

      Alex: Treat examples as spoken recipes, not decorations. You may hear something like git pull origin main. Read the command, understand what it changes, then run it only when the repository state matches the lesson.

      +

      Jamie: What is the safe way to learn from that example?

      +

      Alex: Here is the plain-English version of Fetch: check for updates without merging. git fetch downloads new commits from the remote but does not change your working directory or current branch. Put another way, it just updates your local knowledge of what the remote looks like.

      +

      Alex: Treat examples as spoken recipes, not decorations. You may hear something like git fetch origin. git log main.origin/main --oneline. Read the command, understand what it changes, then run it only when the repository state matches the lesson.

      -

      Jamie: How should someone ask for help in a way that gets them unstuck faster?

      -

      Alex: This is where 7. Getting Help becomes real: it is always acceptable to ask a question on an issue or pull request. That matters in practice: 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.

      -

      Alex: The practical takeaway is this. 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.

      -

      Alex: Keep the teaching thread moving. Keep the learner anchored in 8. After Your Contribution Is Merged. This matters for your GitHub profile. This is the part to say slowly: 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.

      -

      Alex: The practical takeaway is this. 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.

      -

      Jamie: Let's pause on 9. Building a Contribution Habit. What should a learner take away from it?

      -

      Alex: The reason 9. Building a Contribution Habit matters is that the hardest part of open source contribution is starting. That gives the learner a simple foothold: 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.

      +

      Alex: Keep the teaching thread moving. This is where 7. Why Merge Conflicts Happen becomes real: a merge conflict happens when Git cannot automatically combine two sets of changes.

      +

      Jamie: Let's pause on When conflicts occur. What should a learner take away from it?

      +

      Alex: Keep the learner anchored in When conflicts occur. Conflicts happen when two branches modify the same lines in the same file. This is the part to say slowly: Git knows how to merge changes to different files, and even different parts of the same file.

      +

      Alex: Keep the teaching thread moving. The reason What a conflict looks like matters is that when a conflict occurs, Git marks the conflicting section in the file with special markers. The interface gets friendlier when it stops being a wall of controls and starts being a set of named places.

      -

      Alex: Keep the teaching thread moving. Start with Practical habits: Challenge Time: Complete Challenge 8: The Culture Layer in the Challenge Hub, then advance to Chapter 09: Labels, Milestones and Projects. The next useful detail is this: Next: Chapter 09: Labels, Milestones, and Projects Back: Chapter 07: Merge Conflicts Related appendices: Appendix M: Accessibility Standards Appendix F: Git Security Appendix O: Branch Protection. Think of it like entering a new building: first you find the lobby, then the room, then the door you actually need.

      -

      Alex: The practical takeaway is this. 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.

      +

      Jamie: How would you walk the room through that step by step?

      +

      Alex: Start with How to resolve a conflict: The Day 1 connection: In Chapter 7, you resolved a merge conflict on GitHub.com using the web editor. The next useful detail is this: 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.

      +

      Alex: First, open the file with the conflict markers. Then, read both versions and decide which text to keep (or write a new version that combines both). After that, delete the conflict markers ( ). Finally, save the file. Think of it as a rail line: each stop confirms you are still on the right route before the next one.

      +

      Jamie: What does the learner do first, second, and then after that?

      +

      Alex: First, stage and commit the resolved file. Treat it like a recipe: do not add the next ingredient until the previous one is actually in the bowl.

      +

      Alex: Keep the teaching thread moving. Here is the plain-English version of Why conflicts are normal. They happen in every project where more than one person works at the same time. Put another way, the fact that Git stops and asks is a safety feature -- it prevents data loss by never silently choosing one version over another.

      +

      Jamie: Let's pause on Learning Cards: Merge Conflicts. What should a learner take away from it?

      +

      Alex: Start with Learning Cards: Merge Conflicts. There is something to understand, something to try, and something that proves the try worked.

      +

      Alex: For a learner, the useful signals are these. 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. 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.

      +
      +

      Alex: Keep the teaching thread moving. Keep the learner anchored in 8. The Git Timeline. Every commit has a parent pointer (except the very first commit). This is the part to say slowly: This creates a chain -- a timeline of the project's history. A good GitHub workflow is like a well-run meeting: everyone knows the topic, the next action, and who has the floor.

      +

      Jamie: Let's pause on Reading the timeline. What should a learner take away from it?

      +

      Alex: The reason Reading the timeline matters is that 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. That gives the learner a simple foothold: 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.

      +

      Alex: Keep the teaching thread moving. Start with Branching creates parallel timelines: When two branches diverge (both have commits that the other does not), the timeline splits into two parallel paths. The next useful detail is this: Both branches share commits A and B (their common history).

      +
      +

      Jamie: Let's pause on Merging reconnects timelines. What should a learner take away from it?

      +

      Alex: Here is the plain-English version of 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. Put another way, the two timelines join back together.

      +

      Alex: Keep the teaching thread moving. This is where 9. Putting It All Together becomes real: here is the complete workflow that you will practice in Chapter 14, translated through the mental model. That matters in practice: Everything in this table maps directly to the three areas (Section 2), the two copies (Section 5), and the timeline (Section 8). The workshop is closer to rehearsal than lecture. You hear the move, try the move, and then check what changed.

      +

      Jamie: Let's pause on Quick mental model checklist. What should a learner take away from it?

      +

      Alex: Keep the learner anchored in Quick mental model checklist. Before running a Git command, ask yourself. This is the part to say slowly: If you can answer these four questions, you can troubleshoot almost any Git situation.

      +

      Alex: That becomes easier when you listen for these cues. 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?

      +
      +

      Alex: Keep the teaching thread moving. The reason 10. If You Get Stuck matters is that next: Chapter 14: Git in Practice Back: Chapter 12: VS Code Accessibility Related appendices: Appendix E: Advanced Git Appendix D: Git Authentication.

      Jamie: What should people carry with them after this?

      Alex: Carry the map. Know what page or tool you are in, know which action you are taking, and know what confirmation should follow. If the confirmation is missing, pause. That pause is not wasted time; it is professional judgment.

      Jamie: That is a better way to say it than just follow the steps.

      -

      Alex: Right. Steps matter, but understanding wins. That is episode 37. Next in the series is episode 38, where we keep building the same contributor muscles.

      +

      Alex: Right. Steps matter, but understanding wins. That is episode 46. Next in the series is episode 47, where we keep building the same contributor muscles.

      -

      Appendices

      - -

      Tools, references, communities, and continued learning paths.

      -

      Based on: Appendix X: Resources and Links

      -

      Audio and transcript are being regenerated for this episode.

      +

      34. Episode 12: Git and Source Control in VS Code

      +

      Cloning, branching, staging, committing, pushing, and pulling from VS Code.

      +

      Based on: Chapter 14: Git and Source Control in VS Code

      + + +

      Download Episode 12 (MP3)

      -Read Transcript - Episode 38: Resources and Links +Read Transcript - Episode 12: Git and Source Control in VS Code

      Transcript

      -

      Alex: This is Git Going with GitHub, episode 38: Resources and Links. I am Alex. By the end of this episode, Resources and Links should feel less like a wall of GitHub words and more like a set of moves you can trust.

      -

      Jamie: And I am Jamie. I am here for the practical questions: what should I listen for, what can go wrong, and what is the next calm move?

      +

      Alex: Welcome to Git Going with GitHub, episode 12: Git and Source Control in VS Code. I am Alex. Today we are going to make Git and Source Control in VS Code something you can explain, practice, and recover from when the interface surprises you.

      +

      Jamie: And I am Jamie. I will be the voice of the learner who is willing to ask, what is this for, where am I, and how do I know I did it right?

      -

      Alex: Today we are working on this: Tools, references, communities, and continued learning paths. I want the learner to leave with a mental map, not just a remembered path through buttons.

      -

      Jamie: So the goal is understanding first, then action, then confirmation.

      -

      Alex: Right. We are building a rhythm: orient yourself, take one intentional action, then verify what changed before moving on.

      +

      Alex: The big idea today: Cloning, branching, staging, committing, pushing, and pulling from VS Code. We will name the concept, explain why it matters, practice the move, and point out the checks that tell you the work is real.

      +

      Jamie: So the episode should work even if someone has not read the chapter yet.

      +

      Alex: Exactly. The transcript has to stand on its own. It can point toward practice, but it should teach the concept right here in the conversation.

      -

      Jamie: What does someone need before they touch the keyboard?

      -

      Alex: Start with Everything You Need - Before, During, and After the Workshop: Every link, tool, guide, and community resource from the two-day workshop in one place. The next useful detail is this: Bookmark this page in your fork so it travels with you.

      -

      Alex: The next layer is this. Start with Learning Cards: Navigating This Resource Guide. There is something to understand, something to try, and something that proves the try worked.

      -

      Alex: The practical anchors are these. This appendix is organized as 16 numbered sections with heading levels -- press H or 2 to jump between major sections in browse mode. Most sections contain tables of links -- navigate tables with T to jump to the next table, then use arrow keys to read rows and columns. Each resource link opens in the same tab by default -- use Ctrl+Enter (Windows) to open in a new tab and keep this reference page available. Tables in this appendix have a Resource/URL/Notes column structure -- widen your browser or zoom out slightly if columns overlap at high magnification. Link text is descriptive (resource names, not raw URLs) making it easier to scan the page visually. Bookmark this page in your browser for quick access -- it is the single-page reference for everything from the workshop.

      -

      Jamie: What is the one idea that makes the next few steps less mysterious?

      -

      Alex: This is where 1. The Central Project - Accessibility Agents becomes real: the project you forked, contributed to, and carry home.

      +

      Jamie: Okay, set the room for us. What are we walking into?

      +

      Alex: Start with 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. The next useful detail is this: Prerequisites: VS Code Setup & Accessibility Basics, Working with Pull Requests, Merge Conflicts Mac keyboard shortcuts: Throughout this chapter, all Ctrl+ shortcuts use Cmd+ on Mac, and Alt+ shortcuts use Option+.

      +

      Alex: A solid Git habit is to know which branch you are on, what changed, and what confirmation you expect before you run the next command.

      +

      Alex: The next layer is this. Here is the plain-English version of Workshop Recommendation (Chapter 14 / Challenge 10). Chapter 14 is the first local Git workflow chapter with hands-on repository management. Put another way, it supports Challenge 10: Go Local. It is like learning a transit route. The names of the stops matter because they tell you whether you are still going the right direction.

      +

      Alex: The practical anchors are these. There are 3. Each challenge should take under 10 minutes each. The evidence is PR metadata, branch names, and committed changes. The pattern is clone, branch, edit, commit, push, PR.

      +

      Jamie: What does the learner do first, second, and then after that?

      +

      Alex: Start with Challenge 10 Practice Set. There is something to understand, something to try, and something that proves the try worked.

      +

      Alex: First, clone your Learning Room repository - clone your private Learning Room repo to your local machine using VS Code. Then, 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. After that, 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. It is a checklist, but a meaningful one: every item creates evidence that the next step is safe.

      Alex: A solid pull request habit is to separate three questions: what changed, why it changed, and what still needs review. That keeps the conversation useful instead of noisy.

      -

      Alex: Now bring the learner back to the room. Keep the learner anchored in Your Personal Fork. After the workshop, your fork lives at.

      +

      Jamie: Turn that into a path someone can follow.

      +

      Alex: Keep the learner anchored in Practice 10.1 Step-by-Step: Clone Your Learning Room Repository. Get a local copy of your Learning Room repository on your machine using VS Code. This is the part to say slowly: VS Code desktop (or github.dev if you cannot install desktop VS Code).

      +

      Alex: First, open VS Code. If no folder is open, you should see the Welcome tab. Then, open the Command Palette: Ctrl+Shift+P (Mac: Cmd+Shift+P). After that, type git clone and select Git: Clone. Finally, VS Code asks for a repository URL. Paste your Learning Room repo URL (it looks like https://github.com/the workshop organization/learning-room-your username.git). You can copy this from the green Code button on your repo's GitHub page. It is like walking a hallway with named doors: read the sign, enter the right room, then confirm where you landed.

      Jamie: What is the ordered workflow?

      -

      Alex: Start with Quick access from VS Code. There is something to understand, something to try, and something that proves the try worked.

      -

      Alex: First, clone your fork: git clone https://github.com/[your-username]/accessibility-agents.git. Then, open in VS Code: cd accessibility-agents && code. After that, open Copilot Chat: Ctrl+Shift+I. The rhythm is simple: orient, act, verify, then continue.

      -

      Alex: The useful habit is simple: orient first, act second, verify third. That pause before acting is part of the work.

      +

      Alex: First, press Enter. Then, 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. After that, VS Code clones the repository. When it finishes, a notification appears asking "Would you like to open the cloned repository?" Activate Open. Finally, 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. The rhythm is simple: orient, act, verify, then continue.

      Jamie: Give me the sequence, because order matters here.

      -

      Alex: Start with Personalizing Your Fork. There is something to understand, something to try, and something that proves the try worked.

      -

      Alex: First, copy preferences.example.md to preferences.md in.github/agents/. Then, add your GitHub username, your most-used repositories, and your preferred output format. After that, commit the file - now the agents know who you are and what you work on. Think of it as a rail line: each stop confirms you are still on the right route before the next one.

      -
      -

      Jamie: Okay, set the room for us. What are we walking into?

      -

      Alex: Here is the plain-English version of 2. GitHub Accessibility Guides. Official guides from the GitHub Accessibility team. Put another way, these were the primary research sources for this workshop's documentation.

      -

      Alex: This is where the talk moves from concept to action. This is where 3. GitHub Skills Learning Modules becomes real: GitHub Skills is GitHub's free, self-paced interactive learning platform. That matters in practice: Every course runs entirely inside GitHub - no external site, no separate login, no video to watch.

      -

      Jamie: Turn that into a path someone can follow.

      -

      Alex: Keep the learner anchored in How GitHub Skills Works. Unlike a conventional course where you watch videos or read slides, GitHub Skills teaches through doing.

      -

      Alex: First, copy the course: Select "Start course" → "Use this template" → "Create a new repository." This copies the course scaffold to your own account. Then, mona activates: A GitHub Actions workflow automatically runs - within 20 seconds, Mona opens your first lesson as an Issue in your new repository. After that, read and act: The issue contains step-by-step instructions. You do the task (commit a file, open a PR, resolve a conflict) in the same repository. Finally, mona validates: Another GitHub Actions workflow detects what you did, checks if it's correct, and either advances you to the next step or gives you feedback to try again. It is like walking a hallway with named doors: read the sign, enter the right room, then confirm where you landed.

      +

      Alex: The reason Practice 10.2 Step-by-Step: Create a Branch and Commit matters is that see also: Chapter 13: How Git Works explains the three areas (working directory, staging, repository) that make commits meaningful. That gives the learner a simple foothold: check out (or create) a properly named branch, edit a file, stage the change, and commit with a clear message.

      +

      Alex: First, open the Command Palette: Ctrl+Shift+P (Mac: Cmd+Shift+P). Then, 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/your username. If the branch does not exist yet, type git create branch and select Git: Create Branch. After that, 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. Finally, 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). The rhythm is simple: orient, act, verify, then continue.

      Jamie: How would you walk the room through that step by step?

      -

      Alex: First, repeat until done: All feedback arrives as issue comments and new issues. The course is complete when Mona closes the final issue with a success message. The rhythm is simple: orient, act, verify, then continue.

      -
      -

      Alex: Before the learner moves on. The reason Screen Reader Navigation of a GitHub Skills Course matters is that since everything happens in GitHub, the accessibility skills from this workshop apply directly. The interface gets friendlier when it stops being a wall of controls and starts being a set of named places.

      -

      Alex: A solid navigation habit is to prove where you are before activating controls. Headings, landmarks, and the address bar are not trivia; they are your map.

      -

      Jamie: How should they picture the shape of the workshop?

      -

      Alex: Start with After This Workshop - Your Learning Path: GitHub Skills courses are available 24/7 and are completely free. The next useful detail is this: Recommended order after this workshop.

      -

      Alex: Hold that next to this. Start with Learning Cards: Screen Reader Downloads and Setup. There is something to understand, something to try, and something that proves the try worked.

      -

      Alex: That shows up in the workshop in a few specific ways. NVDA (free, Windows): download from nvaccess.org -- after installing, toggle browse/focus mode with NVDA+Space and open the elements list with NVDA+F7. JAWS (Windows): download a trial from freedomscientific.com -- Virtual PC Cursor toggle is Insert+Z, elements list is Insert+F3. VoiceOver (macOS/iOS): built in, no download needed -- start with Cmd+F5 on Mac, or Settings then Accessibility then VoiceOver on iOS. NVDA and JAWS both support speech and braille output simultaneously if you use a refreshable braille display. VoiceOver on macOS integrates with Zoom (screen magnifier) -- enable both in System Settings then Accessibility for combined magnification and speech. Narrator on Windows is built in and requires no download -- launch with Win+Ctrl+Enter for a quick, lightweight screen reader experience.

      -
      -

      Jamie: There are a lot of tools in play. How do we keep that from feeling like a contest?

      -

      Alex: Start with Key commands (quick reference). There is something to understand, something to try, and something that proves the try worked.

      -

      Alex: For a learner, the useful signals are these. Toggle browse/focus mode: NVDA+Space. Elements list: NVDA+F7. Next heading: H Next link: K Next button: B Next form field: F.

      -

      Alex: That connects to another useful point. Start with Key commands (quick reference). There is something to understand, something to try, and something that proves the try worked.

      -

      Alex: The parts worth keeping in working memory are these. Virtual PC Cursor on/off: Insert+Z. Elements list: Insert+F3. Next heading: H Next link: Tab or U Next button: B.

      -

      Jamie: What stays the same when the tool changes?

      -

      Alex: On the ground, that means a few things. Start/stop VoiceOver: Cmd+F5. VO modifier: Caps Lock or Ctrl+Option. Rotor: VO+U. Next heading: VO+Cmd+H.

      +

      Alex: First, 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). Then, 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.". After that, 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.". Finally, 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. Think of it as a rail line: each stop confirms you are still on the right route before the next one.

      +

      Jamie: Let's pause on Practice 10.3 Step-by-Step: Push and Open a Linked PR. What should a learner take away from it?

      +

      Alex: Start with Practice 10.3 Step-by-Step: Push and Open a Linked PR: Push your branch to GitHub and open a PR in your Learning Room repo that references your challenge issue. The next useful detail is this: VS Code (for the push) and GitHub.com (for the PR). Think of it like entering a new building: first you find the lobby, then the room, then the door you actually need.

      +

      Alex: First, open the Command Palette: Ctrl+Shift+P (Mac: Cmd+Shift+P). Then, 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. After that, 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. Finally, open your browser and navigate to your Learning Room repository on GitHub. Think of it as a rail line: each stop confirms you are still on the right route before the next one.

      +

      Jamie: Before we leave Practice 10.3 Step-by-Step: Push and Open a Linked PR, what is the practical point?

      +

      Alex: First, GitHub usually shows a yellow banner: "yourname recently pushed to learn/yourname." Activate the Compare & pull request button in that banner. Then, 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/your username branch. After that, in the PR title, write a descriptive title (for example: "docs: improve welcome.md introduction"). Finally, 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. Treat it like a recipe: do not add the next ingredient until the previous one is actually in the bowl.

      -

      Jamie: What does the learner do first, second, and then after that?

      -

      Alex: Start with Install the GitHub PR extension quickly. There is something to understand, something to try, and something that proves the try worked.

      -

      Alex: First, open VS Code Extensions (Ctrl+Shift+X). Then, search: GitHub Pull Requests. After that, install: publisher is "GitHub". Think of it as a rail line: each stop confirms you are still on the right route before the next one.

      -

      Jamie: What would you say to someone who is already bracing for this to be too much?

      -

      Alex: Here is the plain-English version of 7. GitHub Agentic Workflows. GitHub Agentic Workflows are in technical preview as of February 2026. Put another way, access, feedback channels, and setup information.

      -

      Jamie: Let's pause on How Agentic Workflows connect to what you learned. What should a learner take away from it?

      -

      Alex: This is where How Agentic Workflows connect to what you learned becomes real: the only difference is where they run and how sophisticated their executor is. The workshop is closer to rehearsal than lecture. You hear the move, try the move, and then check what changed.

      -

      Alex: First, standard GitHub Actions (YAML workflows - triggers, jobs, steps). Then, accessibility Agents agents (.agent.md files - plain English instructions, Copilot Chat executor). After that, GitHub Agentic Workflows (.md files in.github/workflows/ - plain English instructions, cloud-based coding agent executor). It is a checklist, but a meaningful one: every item creates evidence that the next step is safe.

      +

      Jamie: What should the learner prove to themselves after each small task?

      +

      Alex: Here is the plain-English version of Completing Challenge 10: Submit Your Evidence. Open your assigned Challenge 10 issue in your Learning Room repo and post a completion comment. Put another way, close your Challenge 10 issue when your branch is pushed and the PR is open.

      +

      Alex: The useful habit is simple: orient first, act second, verify third. That pause before acting is part of the work.

      +

      Alex: This is where the talk moves from concept to action. Start with Expected Outcomes. There is something to understand, something to try, and something that proves the try worked.

      +

      Alex: The room should hear these as checkpoints. 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.

      +

      Jamie: Let's pause on If You Get Stuck. What should a learner take away from it?

      +

      Alex: Keep the learner anchored in If You Get Stuck. Continue learning: The GitHub Skills course Introduction to Git walks through commits, branches, and merges in an interactive, self-paced format. This is the part to say slowly: See Appendix Z for the full catalog.

      +

      Alex: First, command Palette does not open? Confirm you are in VS Code (not the browser) and press Ctrl+Shift+P (Mac: Cmd+Shift+P). Then, source Control panel is empty? You may not have saved your file yet. Press Ctrl+S to save, then check again. After that, 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. Finally, branch name wrong? Open Command Palette, run Git: Rename Branch. to fix it before pushing. It is like walking a hallway with named doors: read the sign, enter the right room, then confirm where you landed.

      +

      Jamie: Before we leave If You Get Stuck, what is the practical point?

      +

      Alex: First, cannot find the "Compare & pull request" banner on GitHub? Navigate to Pull requests tab and create the PR manually (step 6 above). Then, 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. After that, ask facilitator to verify your clone location, branch name, and help with one push. Finally, finished but not sure you did it right? Compare your work against the Challenge 10 reference solution. The rhythm is simple: orient, act, verify, then continue.

      -

      Jamie: If I am listening before the workshop starts, what should settle in my mind first?

      -

      Alex: Keep the learner anchored in 8. Spec-Driven Development - Spec Kit. The core idea: Write the intent of a feature before anyone builds it. This is the part to say slowly: The specification is a living document - AI uses it to plan tasks, contributors use it to stay aligned, the community uses it to evaluate whether the outcome matched the intention.

      -

      Alex: Another way to ground it. The reason Slash commands matters is that works with GitHub Copilot, Claude Code, and Gemini CLI.

      -

      Alex: That becomes easier when you listen for these cues. /specify - open a new specification session. /plan - convert a spec into a development plan. /tasks - break the plan into trackable tasks.

      -

      Jamie: What should they understand before typing anything?

      -

      Alex: Start with GitHub CLI (gh). There is something to understand, something to try, and something that proves the try worked.

      -

      Alex: Treat examples as spoken recipes, not decorations. You may hear something like Install; winget install GitHub.cli Windows; brew install gh macOS; Most useful commands for contributors; gh issue list List issues in current repo; gh issue view 42 Read issue 42; gh pr list List open PRs; gh pr view 14 Read PR 14; gh pr create Create a PR. Read the command, understand what it changes, then run it only when the repository state matches the lesson.

      +

      Alex: Before the learner moves on. The reason Learning Moment matters is that local Git operations give you full control and immediate feedback. That gives the learner a simple foothold: you can see your changes, review them, and fix mistakes before they reach GitHub. The interface gets friendlier when it stops being a wall of controls and starts being a set of named places.

      +

      Jamie: Let's pause on Learning Pattern Used in This Chapter. What should a learner take away from it?

      +

      Alex: Start with Learning Pattern Used in This Chapter. There is something to understand, something to try, and something that proves the try worked.

      +

      Alex: First, clone once to get a local copy of the project. Then, branch before editing (never work directly on main). After that, make small, focused edits with clear commit messages. Finally, push and open a PR that links to an issue for traceability. Think of it as a rail line: each stop confirms you are still on the right route before the next one.

      +

      Jamie: Before we leave Learning Pattern Used in This Chapter, what is the practical point?

      +

      Alex: First, verify each step before moving to the next. Treat it like a recipe: do not add the next ingredient until the previous one is actually in the bowl.

      +

      Alex: Hold that next to this. Here is the plain-English version of About Learning Cards. Throughout this chapter, each major operation includes learning cards - expandable sections showing how to accomplish the same task from multiple perspectives. Put another way, open the card that matches how you work.

      -

      Jamie: How do you keep commands from becoming magic words?

      -

      Alex: Start with Copilot in the CLI (gh copilot). There is something to understand, something to try, and something that proves the try worked.

      -

      Alex: Treat examples as spoken recipes, not decorations. You may hear something like Install the extension; gh extension install github/gh-copilot; Ask Copilot to explain a command; gh copilot explain "git rebase -i HEAD 3"; Ask Copilot to suggest a command; gh copilot suggest "undo my last commit but keep the changes staged". Read the command, understand what it changes, then run it only when the repository state matches the lesson.

      -

      Jamie: Give me the version that sounds like an instructor, not a manual.

      -

      Alex: This is where 10. GitHub Mobile Apps becomes real: GitHub's official mobile apps bring the full GitHub experience to your phone or tablet. That matters in practice: Perfect for reviewing PRs, triaging issues, and staying connected when away from your computer.

      -

      Alex: Here is the practical turn. Start with What You Can Do in GitHub Mobile. There is something to understand, something to try, and something that proves the try worked.

      -

      Alex: Here is what that changes in practice. Browse repositories - navigate code, read files, view commits. Manage issues - create, edit, comment, close, and label issues. Review pull requests - read diffs, leave comments, request changes, approve, merge. Manage notifications - triage your inbox on the go. Interact with GitHub Copilot - chat with Copilot Chat on mobile (as of Feb 2026). View GitHub Actions - monitor workflows and check build status.

      +

      Jamie: Let's pause on Tool Cards: Clone a Repository (Day 2). What should a learner take away from it?

      +

      Alex: This is where Tool Cards: Clone a Repository (Day 2) becomes real: VS Code Desktop (primary for Day 2). That matters in practice: github.dev (web editor): No clone needed.

      +

      Alex: First, ctrl+Shift+P Git: Clone paste the HTTPS URL choose a folder Open. Then, file Clone Repository paste URL or select from your account Clone. It is a checklist, but a meaningful one: every item creates evidence that the next step is safe.

      +

      Alex: Treat examples as spoken recipes, not decorations. You may hear something like git clone https://github.com/owner/repo.git && cd repo. gh repo clone owner/repo && cd repo. Read the command, understand what it changes, then run it only when the repository state matches the lesson.

      +

      Jamie: Let's pause on Method 1: Command Palette (Recommended for Screen Readers). What should a learner take away from it?

      +

      Alex: Start with Method 1: Command Palette (Recommended for Screen Readers). There is something to understand, something to try, and something that proves the try worked.

      +

      Alex: First, open Command Palette: Ctrl+Shift+P (Mac: Cmd+Shift+P). Then, type "git clone". After that, select "Git: Clone". Finally, paste the repository URL (example: https://github.com/community-access/accessibility-agents.git). It is like walking a hallway with named doors: read the sign, enter the right room, then confirm where you landed.

      +

      Jamie: Before we leave Method 1: Command Palette (Recommended for Screen Readers), what is the practical point?

      +

      Alex: First, press Enter. Then, choose a local folder where the repository should be cloned. After that, VS Code asks: "Would you like to open the cloned repository?" - select "Open". The rhythm is simple: orient, act, verify, then continue.

      +

      Alex: A solid navigation habit is to prove where you are before activating controls. Headings, landmarks, and the address bar are not trivia; they are your map.

      +

      Jamie: What is the one idea that makes the next few steps less mysterious?

      +

      Alex: Start with Screen reader navigation. There is something to understand, something to try, and something that proves the try worked.

      +

      Alex: The parts worth keeping in working memory are these. 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.

      -

      Jamie: Where do you want a learner to place their attention here?

      -

      Alex: The reason Accessibility Features matters is that pro tip: Enable push notifications for mentions and reviews so you can respond quickly when your input is needed.

      -

      Alex: The room should hear these as checkpoints. Native screen reader gestures (VoiceOver on iOS, TalkBack on Android). Dynamic text sizing. Dark mode / high contrast. Keyboard navigation (when using external keyboard with tablet).

      -

      Alex: That matters because of the next idea. Start with 11. GitHub Best Practices and Power Features: Essential tips and lesser-known features that make you a more effective contributor. Think of it like entering a new building: first you find the lobby, then the room, then the door you actually need.

      -

      Jamie: Let's pause on Saved Replies. What should a learner take away from it?

      -

      Alex: Here is the plain-English version of Saved Replies. Saved replies let you create reusable text templates for common responses.

      -

      Alex: These are the details that keep the idea from floating away. Thanking first-time contributors. Requesting more information with a friendly tone. Explaining common setup issues. Closing duplicate issues.

      -
      -

      Jamie: Let's pause on How to set up. What should a learner take away from it?

      -

      Alex: Start with How to set up. There is something to understand, something to try, and something that proves the try worked.

      -

      Alex: First, go to github.com/settings/replies. Then, click "Add a saved reply". After that, give it a short label (e.g., "welcome-first-time"). Finally, write your template text (can include Markdown). It is a checklist, but a meaningful one: every item creates evidence that the next step is safe.

      -

      Jamie: Let's pause on How to use. What should a learner take away from it?

      -

      Alex: Start with How to use. There is something to understand, something to try, and something that proves the try worked.

      -

      Alex: A few details make that real. When writing any comment, press Ctrl+. (period) to open the saved replies menu. Select your saved reply. Edit as needed before posting.

      -

      Alex: This is the part worth saying out loud. The reason Pinned Issues matters is that pin important issues to the top of your repository's Issues tab. The interface gets friendlier when it stops being a wall of controls and starts being a set of named places.

      -

      Alex: The practical takeaway is this. FAQs and getting started guides. Known issues and workarounds. Roadmap and project status updates. Community guidelines.

      -

      Alex: A solid issue habit is to read the title, the body, and the timeline before acting. You are listening for the requested action, the missing evidence, and the person who needs a response.

      +

      Jamie: Let's pause on Method 2: Start Page Clone Button. What should a learner take away from it?

      +

      Alex: Start with Method 2: Start Page Clone Button: The Start page is keyboard-accessible. The next useful detail is this: Tab to navigate between "New File," "Open Folder," and "Clone Repository" buttons.

      +

      Alex: First, open VS Code (no folder open). Then, the Start page appears. After that, navigate to "Clone Git Repository" button - press Enter. Finally, paste repository URL → Enter. Think of it as a rail line: each stop confirms you are still on the right route before the next one.

      +

      Jamie: Before we leave Method 2: Start Page Clone Button, what is the practical point?

      +

      Alex: First, choose destination folder. Then, open when prompted. Treat it like a recipe: do not add the next ingredient until the previous one is actually in the bowl.

      +

      Jamie: Let's pause on Method 3: From GitHub.com. What should a learner take away from it?

      +

      Alex: Start with Method 3: From GitHub.com. There is something to understand, something to try, and something that proves the try worked.

      +

      Alex: First, on any GitHub repository page, click the green "Code" button. Then, copy the HTTPS URL (recommended) or SSH URL. After that, open VS Code → Ctrl+Shift+P (Mac: Cmd+Shift+P) → "Git: Clone". Finally, paste URL → Enter. Treat it like a recipe: do not add the next ingredient until the previous one is actually in the bowl.

      +

      Jamie: Before we leave Method 3: From GitHub.com, what is the practical point?

      +

      Alex: First, choose destination → Open. It is a checklist, but a meaningful one: every item creates evidence that the next step is safe.

      +

      Jamie: Let's pause on Learning Cards: Cloning a Repository. What should a learner take away from it?

      +

      Alex: This is where Learning Cards: Cloning a Repository becomes real: low vision users (zoom, high contrast). That matters in practice: Cloning works the same as the Command Palette method above. The workshop is closer to rehearsal than lecture. You hear the move, try the move, and then check what changed.

      +

      Alex: First, 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. Then, 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. After that, 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. Finally, 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. It is a checklist, but a meaningful one: every item creates evidence that the next step is safe.

      +

      Jamie: Before we leave Learning Cards: Cloning a Repository, what is the practical point?

      +

      Alex: First, navigate to the repository on GitHub.com. Then, press. (period) to open github.dev - a browser-based VS Code editor. After that, the full repository opens in an editor with file tree, search, and editing. Finally, changes are committed directly to GitHub from the browser. It is like walking a hallway with named doors: read the sign, enter the right room, then confirm where you landed.

      +

      Alex: Treat examples as spoken recipes, not decorations. You may hear something like 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. Read the command, understand what it changes, then run it only when the repository state matches the lesson.

      -

      Jamie: Let's pause on How to pin an issue. What should a learner take away from it?

      -

      Alex: Start with How to pin an issue: You can pin up to 3 issues per repository. The next useful detail is this: Pinned issues are visible to everyone, even those who haven't starred or watched your repo.

      -

      Alex: First, open the issue you want to pin. Then, in the right sidebar, click the three-dot menu (⋯). After that, select "Pin issue". Finally, it now appears at the top of the Issues list. Think of it as a rail line: each stop confirms you are still on the right route before the next one.

      -

      Alex: Keep the thread going. Here is the plain-English version of Pinned Comments (New: Feb 2026). You can now pin a single comment within an issue thread to keep important information visible.

      -

      Alex: The practical takeaway is this. Workarounds or temporary solutions. Decisions made during discussion. Links to related issues or PRs. Status updates from maintainers.

      -

      Jamie: Let's pause on How to pin a comment. What should a learner take away from it?

      -

      Alex: This is where How to pin a comment becomes real: only repository collaborators can pin comments. That matters in practice: There can be only one pinned comment per issue.

      -

      Alex: First, find the comment you want to pin. Then, click the three-dot menu (⋯) on the comment. After that, select "Pin comment". It is a checklist, but a meaningful one: every item creates evidence that the next step is safe.

      +

      Jamie: Why is the evidence prompt part of the teaching, not just grading?

      +

      Alex: Keep the learner anchored in 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. This is the part to say slowly: Repository URL: https://github.com/community-access/vscode-sci-fi-themes.git.

      +

      Alex: These are the details that keep the idea from floating away. 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.

      +

      Alex: Another way to ground it. Start with Why Clone This? There is something to understand, something to try, and something that proves the try worked.

      +

      Alex: That becomes easier when you listen for these cues. 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!

      +

      Jamie: Let's pause on Quick Start. What should a learner take away from it?

      +

      Alex: Start with Quick Start: See CLONE-THIS-REPO.md in that repo for full instructions. The next useful detail is this: If you prefer not to clone locally, you can work entirely on GitHub.com.

      +

      Alex: First, clone: Ctrl+Shift+P → "Git: Clone" → paste URL above → Enter. Then, choose a destination folder and open when prompted. After that, navigate to the themes/ folder and pick a.json file (star-trek, hitchhikers, or star-wars). Finally, copy the chat.agent.thinking.phrases setting into your VS Code settings.json. Think of it as a rail line: each stop confirms you are still on the right route before the next one.

      +

      Jamie: Before we leave Quick Start, what is the practical point?

      +

      Alex: First, reload VS Code: Ctrl+Shift+P → "Developer: Reload Window". Then, open Copilot Chat (Ctrl+Shift+I) and ask a question--watch your custom phrases appear! After that, navigate to the repository on GitHub. Finally, click any file to view it, then click the pencil icon (Edit) to modify it directly in the browser. Treat it like a recipe: do not add the next ingredient until the previous one is actually in the bowl.

      +

      Alex: Treat examples as spoken recipes, not decorations. You may hear something like 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. Read the command, understand what it changes, then run it only when the repository state matches the lesson.

      -

      Alex: Keep the teaching thread moving. Keep the learner anchored in Linking to Specific Lines of Code. Share precise references to code by including line numbers in GitHub URLs. A good GitHub workflow is like a well-run meeting: everyone knows the topic, the next action, and who has the floor.

      -

      Jamie: Let's pause on Syntax. What should a learner take away from it?

      -

      Alex: Start with Syntax. There is something to understand, something to try, and something that proves the try worked.

      -

      Alex: The practical takeaway is this. Single line: github.com/owner/repo/blob/main/file.js L42. Line range: github.com/owner/repo/blob/main/file.js L42-L58.

      -

      Jamie: Let's pause on How to create these links. What should a learner take away from it?

      -

      Alex: Start with How to create these links: Line numbers are links announced as "Line 42 link" (or similar). The next useful detail is this: They're in the left margin of the code view.

      -

      Alex: First, navigate to a file on GitHub. Then, click the line number (in screen readers: navigate to the line and activate the number link). After that, hold Shift and click another line number to select a range. Finally, copy the URL from your browser - the line numbers are automatically included. Think of it as a rail line: each stop confirms you are still on the right route before the next one.

      +

      Alex: This is the part worth saying out loud. Here is the plain-English version of 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. Put another way, this section provides a complete screen reader walkthrough of every interactive element. It is like learning a transit route. The names of the stops matter because they tell you whether you are still going the right direction.

      +

      Jamie: What would you say to someone who is already bracing for this to be too much?

      +

      Alex: This is where Opening the Source Control Panel becomes real: shortcut: Ctrl+Shift+G (Mac: Cmd+Shift+G).

      +

      Alex: That connects to another useful point. Start with What opens. There is something to understand, something to try, and something that proves the try worked.

      +

      Alex: For a learner, the useful signals are these. 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).

      -

      Jamie: Let's pause on Permalinks - Stable Links That Never Break. What should a learner take away from it?

      -

      Alex: Here is the plain-English version of Permalinks - Stable Links That Never Break. When you link to code on GitHub using a branch name (main, develop), that link can break if the code changes or the file moves. Put another way, permalinks use the commit SHA instead of the branch name, creating a permanent snapshot link.

      -

      Jamie: Let's pause on How to create a permalink. What should a learner take away from it?

      -

      Alex: This is where How to create a permalink becomes real: shortcut: Y = "Yank permalink" (borrows from Vim terminology). The workshop is closer to rehearsal than lecture. You hear the move, try the move, and then check what changed.

      -

      Alex: First, view any file on GitHub. Then, press Y while viewing the file - the URL changes from /blob/main/file.js to /blob/a1b2c3d4./file.js. After that, copy the new URL - it now points to that specific commit. It is a checklist, but a meaningful one: every item creates evidence that the next step is safe.

      -

      Jamie: Let's pause on Converting Issues to Discussions. What should a learner take away from it?

      -

      Alex: Keep the learner anchored in Converting Issues to Discussions. Not every issue is a bug or feature request. This is the part to say slowly: Some are questions, proposals, or open-ended conversations.

      +

      Jamie: Let's pause on Panel structure from top to bottom. What should a learner take away from it?

      +

      Alex: Start with Panel structure from top to bottom. There is something to understand, something to try, and something that proves the try worked.

      +

      Alex: On the ground, that means a few things. Branch name displayed (example: "main" or "feature/add-documentation"). View/More Actions button (three dots menu). Type your commit message here. Announced as "Source Control Input, edit, multi-line". Shortcut: Ctrl+Enter (Mac: Cmd+Enter) when focused in the message input. Lists all modified files not yet staged.

      +

      Alex: First, source Control title bar (heading level 2). Then, commit message input (multi-line text field). After that, commit button (or "Publish Branch" if this is a new branch). Finally, changes section (collapsible tree). The rhythm is simple: orient, act, verify, then continue.

      +

      Jamie: Before we leave Panel structure from top to bottom, what is the practical point?

      +

      Alex: First, staged Changes section (collapsible tree). Then, merge Changes section (appears only during a merge). Think of it as a rail line: each stop confirms you are still on the right route before the next one.

      +

      Alex: Now bring the learner back to the room. Start with NVDA/JAWS. There is something to understand, something to try, and something that proves the try worked.

      +

      Alex: Here is what that changes in practice. 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).

      +

      Jamie: Where do you want a learner to place their attention here?

      +

      Alex: Here is the plain-English version of VoiceOver. Key point: The Source Control panel is not a standard file tree. Put another way, it's a specialized Git status view.

      +

      Alex: A few details make that real. Navigate with VO+Arrow keys. VO+Space to activate (open diff or stage/unstage). The panel is announced as a "group" containing lists.

      -

      Alex: Keep the teaching thread moving. Start with When to convert. There is something to understand, something to try, and something that proves the try worked.

      -

      Alex: The practical takeaway is this. Questions that don't require a code change ("How do I configure X?"). Proposals that need community feedback before becoming actionable. General discussion about the project's direction. Show-and-tell or community showcases.

      -

      Jamie: Let's pause on How to convert an issue to a discussion. What should a learner take away from it?

      -

      Alex: Start with How to convert an issue to a discussion: All comments and history are preserved. The next useful detail is this: The issue is closed and replaced with a link to the new discussion.

      -

      Alex: First, open the issue. Then, in the right sidebar, click "Convert to discussion". After that, select which discussion category it belongs in. Think of it as a rail line: each stop confirms you are still on the right route before the next one.

      -

      Alex: Keep the teaching thread moving. Here is the plain-English version of Team Mentions - Notify a Whole Group. In organizations, you can mention entire teams instead of individuals: @org-name/team-name. Put another way, example: @github/accessibility notifies everyone on GitHub's accessibility team. It is like learning a transit route. The names of the stops matter because they tell you whether you are still going the right direction.

      +

      Alex: That matters because of the next idea. This is where What Each File Shows becomes real: when a file appears in the Changes or Staged Changes list, VS Code shows a status letter. That matters in practice: Screen reader announcement: "docs/GUIDE.md, Modified" or "README.md, Added".

      +

      Jamie: Give me the version that sounds like an instructor, not a manual.

      +

      Alex: Keep the learner anchored in Context Menu Actions (Right-Click or Shift+F10). When focused on any file in the Source Control panel. This is the part to say slowly: Use Shift+F10 to open the context menu.

      +

      Jamie: Let's pause on Learning Cards: Source Control Panel. What should a learner take away from it?

      +

      Alex: The reason Learning Cards: Source Control Panel matters is that low vision users (zoom, high contrast). That gives the learner a simple foothold: the Source Control panel adapts well to zoom and high contrast settings. The interface gets friendlier when it stops being a wall of controls and starts being a set of named places.

      +

      Alex: First, 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. Then, 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. After that, 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). Finally, 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. The rhythm is simple: orient, act, verify, then continue.

      +

      Jamie: Before we leave Learning Cards: Source Control Panel, what is the practical point?

      +

      Alex: First, 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. Think of it as a rail line: each stop confirms you are still on the right route before the next one.

      +

      Alex: Treat examples as spoken recipes, not decorations. You may hear something like 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. Read the command, understand what it changes, then run it only when the repository state matches the lesson.

      -

      Jamie: Let's pause on Why this matters. What should a learner take away from it?

      -

      Alex: This is where Why this matters becomes real: permission: You can only mention teams you have visibility to. That matters in practice: Public teams in public orgs can be mentioned by anyone.

      -

      Alex: The practical takeaway is this. You don't need to know who's on a team - just mention the team. Teams can subscribe to notifications as a group. CODEOWNERS files use team mentions for automatic reviewer assignment.

      -

      Alex: Keep the teaching thread moving. Keep the learner anchored in Collapsible Sections in Markdown. Keep long issue descriptions or PR descriptions scannable by hiding details in collapsible sections.

      -

      Jamie: Let's pause on Use for. What should a learner take away from it?

      -

      Alex: The reason Use for matters is that accessibility note: Collapsible sections are announced as "disclosure triangles" or "expandable" regions by most screen readers. That gives the learner a simple foothold: the summary text is always visible.

      -

      Alex: The practical takeaway is this. Long error messages or logs. Optional context that most readers don't need. Large screenshots or code samples. Step-by-step troubleshooting instructions.

      +

      Jamie: If I am listening before the workshop starts, what should settle in my mind first?

      +

      Alex: Start with 3. Branch Management: Branches are how you organize work in Git. The next useful detail is this: Every repository starts with a main or master branch.

      +

      Jamie: Let's pause on Where it's shown. What should a learner take away from it?

      +

      Alex: Start with Where it's shown. There is something to understand, something to try, and something that proves the try worked.

      +

      Alex: First, bottom-left corner of VS Code (status bar) - visual users see it immediately. Then, source Control panel title bar. After that, command Palette: Ctrl+Shift+P (Mac: Cmd+Shift+P) → "Git: Show Git Output". Treat it like a recipe: do not add the next ingredient until the previous one is actually in the bowl.

      +

      Jamie: Let's pause on Keyboard access to status bar. What should a learner take away from it?

      +

      Alex: This is where Keyboard access to status bar becomes real: visual users: You can also click the branch name in the bottom-left status bar to open the branch picker directly.

      +

      Alex: That shows up in the workshop in a few specific ways. The status bar is not in the standard keyboard navigation flow. Use the Command Palette for branch operations instead.

      -

      Alex: Keep the teaching thread moving. Start with Co-Authored Commits: Credit multiple people for a single commit using the Co-authored-by trailer in your commit message. Think of it like entering a new building: first you find the lobby, then the room, then the door you actually need.

      -

      Alex: A solid Git habit is to know which branch you are on, what changed, and what confirmation you expect before you run the next command.

      -

      Jamie: Before we leave Why this matters, what is the practical point?

      -

      Alex: Here is the plain-English version of Why this matters. When viewing a commit with co-authors on GitHub, screen readers announce "Co-authored-by" in the commit details.

      -

      Alex: The practical takeaway is this. Pair programming - both people get credit in the Git history. Crediting someone who provided the solution but didn't write the code. GitHub recognizes these trailers and shows all co-authors on the commit.

      -

      Alex: Keep the teaching thread moving. This is where Understanding Watch, Star, and Fork becomes real: three ways to interact with a repository - each means something different.

      +

      Jamie: Let's pause on Command Palette method (recommended). What should a learner take away from it?

      +

      Alex: Start with Command Palette method (recommended). There is something to understand, something to try, and something that proves the try worked.

      +

      Alex: The practical takeaway is this. Creates the branch. Switches to it automatically. Your working files stay exactly as they were.

      +

      Alex: First, ctrl+Shift+P (Mac: Cmd+Shift+P). Then, type "git create branch". After that, select "Git: Create Branch.". Finally, type the new branch name (example: feature/improve-docs). It is like walking a hallway with named doors: read the sign, enter the right room, then confirm where you landed.

      +

      Jamie: Before we leave Command Palette method (recommended), what is the practical point?

      +

      Alex: First, press Enter. The rhythm is simple: orient, act, verify, then continue.

      +

      Jamie: Let's pause on Naming conventions. What should a learner take away from it?

      +

      Alex: The reason Naming conventions matters is that web alternative (github.com) - branch management. That gives the learner a simple foothold: create and switch branches without leaving your browser.

      +

      Alex: The practical takeaway is this. Use lowercase with hyphens: feature/add-timeline-guide. Avoid spaces and special characters. Be descriptive: fix/heading-hierarchy not fix1.

      +

      Alex: First, on the repository page, click the branch dropdown (shows "main" by default). Then, type a new branch name in the search field. After that, click "Create branch: your-branch-name from main". Finally, GitHub switches to the new branch immediately. The rhythm is simple: orient, act, verify, then continue.

      +

      Jamie: Before we leave Naming conventions, what is the practical point?

      +

      Alex: First, any file edits you make in the browser will be on this branch. Think of it as a rail line: each stop confirms you are still on the right route before the next one.

      +

      Alex: Treat examples as spoken recipes, not decorations. You may hear something like 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. Read the command, understand what it changes, then run it only when the repository state matches the lesson.

      +

      Jamie: Let's pause on Command Palette method. What should a learner take away from it?

      +

      Alex: Start with Command Palette method: Screen reader announcement: "Branch: main" or "Branch: feature/add-timeline-guide".

      +

      Alex: First, ctrl+Shift+P (Mac: Cmd+Shift+P). Then, type "git checkout". After that, select "Git: Checkout to.". Finally, a list of all branches appears. Think of it as a rail line: each stop confirms you are still on the right route before the next one.

      +

      Jamie: Before we leave Command Palette method, what is the practical point?

      +

      Alex: First, up/Down Arrow to navigate. Then, enter to switch. Treat it like a recipe: do not add the next ingredient until the previous one is actually in the bowl.

      -

      Jamie: Let's pause on Watch settings. What should a learner take away from it?

      -

      Alex: Keep the learner anchored in Watch settings. Pro tip: Star repos for discovery; Watch repos you actively contribute to.

      -

      Alex: The practical takeaway is this. All activity - every issue, PR, and discussion. Participating (default) - only threads you comment on or are @mentioned in. Releases only - just new releases. Ignore - unsubscribe completely.

      -

      Alex: Keep the teaching thread moving. The reason CODEOWNERS - Automatic Reviewer Assignment matters is that the CODEOWNERS file automatically requests reviews from specific people or teams when files in their area are changed. That gives the learner a simple foothold: location.github/CODEOWNERS in your repository. The interface gets friendlier when it stops being a wall of controls and starts being a set of named places.

      -

      Jamie: Let's pause on How it works. What should a learner take away from it?

      -

      Alex: Start with How it works. There is something to understand, something to try, and something that proves the try worked.

      -

      Alex: First, someone opens a PR that changes files in /docs/. Then, GitHub automatically requests a review from @org-name/docs-team. After that, the PR can't be merged until the required review is approved (if branch protection requires it). Think of it as a rail line: each stop confirms you are still on the right route before the next one.

      +

      Jamie: Let's pause on What happens when you switch. What should a learner take away from it?

      +

      Alex: Start with What happens when you switch. There is something to understand, something to try, and something that proves the try worked.

      +

      Alex: The practical takeaway is this. 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).

      +

      Jamie: Let's pause on After your PR is merged, you can delete the branch. What should a learner take away from it?

      +

      Alex: This is where After your PR is merged, you can delete the branch becomes real: you cannot delete the branch you're currently on. The workshop is closer to rehearsal than lecture. You hear the move, try the move, and then check what changed.

      +

      Alex: First, ctrl+Shift+P (Mac: Cmd+Shift+P). Then, type "git delete branch". After that, select "Git: Delete Branch.". Finally, choose the branch to delete from the list. It is a checklist, but a meaningful one: every item creates evidence that the next step is safe.

      +

      Jamie: What is the safe way to learn from that example?

      +

      Alex: Keep the learner anchored in Viewing All Branches. Command: Ctrl+Shift+P → "Git: Show Git Output" → Branch list appears. This is the part to say slowly: Alternative: Use the integrated terminal.

      +

      Alex: Treat examples as spoken recipes, not decorations. You may hear something like git branch Local branches only; git branch -a All branches (including remote). Read the command, understand what it changes, then run it only when the repository state matches the lesson.

      -

      Alex: Keep the teaching thread moving. Start with Use for. There is something to understand, something to try, and something that proves the try worked.

      -

      Alex: The practical takeaway is this. Ensuring domain experts review specialized code. Distributing review responsibilities. Preventing changes from being merged without appropriate oversight.

      -

      Jamie: Let's pause on GitHub Sponsors. What should a learner take away from it?

      -

      Alex: This is where GitHub Sponsors becomes real: support open source maintainers financially through GitHub Sponsors. That matters in practice: If a project you use has a "Sponsor" button, consider supporting them.

      -

      Alex: Keep the teaching thread moving. Start with How it works. There is something to understand, something to try, and something that proves the try worked.

      -

      Alex: The practical takeaway is this. Maintainers set up a Sponsors profile. You can sponsor with a monthly recurring amount or one-time payment. GitHub doesn't take a fee (as of 2026).

      +

      Jamie: Let's pause on Learning Cards: Branch Management. What should a learner take away from it?

      +

      Alex: The reason Learning Cards: Branch Management matters is that low vision users (zoom, high contrast). That gives the learner a simple foothold: screen reader users (NVDA / JAWS on Windows).

      +

      Alex: First, 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. Then, 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. After that, 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. The rhythm is simple: orient, act, verify, then continue.

      +

      Jamie: Let's pause on Creating a branch. What should a learner take away from it?

      +

      Alex: Start with Creating a branch. There is something to understand, something to try, and something that proves the try worked.

      +

      Alex: First, press Ctrl+Shift+P to open the Command Palette. Then, type "git create branch" - NVDA/JAWS announces results as you type. After that, press Enter on "Git: Create Branch.". Finally, the input focus moves to a text field - type your branch name (e.g., feature/add-docs). Think of it as a rail line: each stop confirms you are still on the right route before the next one.

      +

      Jamie: Before we leave Creating a branch, what is the practical point?

      +

      Alex: First, press Enter - VS Code creates and switches to the branch. Then, NVDA/JAWS announces the new branch name in the status bar notification. Treat it like a recipe: do not add the next ingredient until the previous one is actually in the bowl.

      +

      Jamie: Let's pause on Switching branches. What should a learner take away from it?

      +

      Alex: Start with Switching branches. There is something to understand, something to try, and something that proves the try worked.

      +

      Alex: First, press Ctrl+Shift+P, type "git checkout". Then, select "Git: Checkout to.". After that, a list of branches appears - navigate with Up/Down Arrow. Finally, each item is announced as the branch name (e.g., "main", "feature/add-docs"). Treat it like a recipe: do not add the next ingredient until the previous one is actually in the bowl.

      +

      Jamie: Before we leave Switching branches, what is the practical point?

      +

      Alex: First, press Enter to switch. Then, VS Code reloads files for that branch - you hear a status bar update. It is a checklist, but a meaningful one: every item creates evidence that the next step is safe.

      -

      Jamie: Let's pause on Why sponsor. What should a learner take away from it?

      -

      Alex: Start with Why sponsor. There is something to understand, something to try, and something that proves the try worked.

      -

      Alex: The practical takeaway is this. Open source maintainers often work for free in their spare time. Your sponsorship helps them dedicate more time to the project. Many maintainers offer perks to sponsors (early access, prioritized issues, etc.).

      -

      Jamie: Let's pause on How to sponsor. What should a learner take away from it?

      -

      Alex: Start with How to sponsor. There is something to understand, something to try, and something that proves the try worked.

      -

      Alex: First, visit a repository with a "Sponsor" button. Then, click the button. After that, choose a sponsorship tier. Finally, complete payment through GitHub Sponsors. Think of it as a rail line: each stop confirms you are still on the right route before the next one.

      -

      Jamie: Let's pause on Advanced Markdown Features. What should a learner take away from it?

      -

      Alex: Here is the plain-English version of Advanced Markdown Features. GitHub supports several powerful Markdown features beyond the basics.

      +

      Jamie: Let's pause on Deleting a branch. What should a learner take away from it?

      +

      Alex: This is where Deleting a branch becomes real: screen reader users (VoiceOver on macOS).

      +

      Alex: First, switch to a different branch first (you cannot delete the branch you are on). Then, press Ctrl+Shift+P, type "git delete branch". After that, select "Git: Delete Branch.". Finally, navigate the list to find the branch to delete, press Enter. It is a checklist, but a meaningful one: every item creates evidence that the next step is safe.

      +

      Jamie: What is the teaching move inside Creating a branch?

      +

      Alex: First, press Cmd+Shift+P to open the Command Palette. Then, type "git create branch" - VoiceOver announces filtered results. After that, press Return on "Git: Create Branch.". Finally, type the branch name in the input field. It is like walking a hallway with named doors: read the sign, enter the right room, then confirm where you landed.

      +

      Jamie: If someone only remembers one thing from Creating a branch, what should it be?

      +

      Alex: First, press Return to create and switch. The rhythm is simple: orient, act, verify, then continue.

      +

      Jamie: What is the teaching move inside Switching branches?

      +

      Alex: First, press Cmd+Shift+P, type "git checkout". Then, select "Git: Checkout to.". After that, use VO+Down Arrow to navigate the branch list. Finally, press Return to switch. The rhythm is simple: orient, act, verify, then continue.

      -

      Alex: Keep the teaching thread moving. This is where Mermaid Diagrams becomes real: graph TD A[User opens issue] -- B{Is it a bug?} B -- Yes C[Label: bug] B -- No D[Label: enhancement]. The workshop is closer to rehearsal than lecture. You hear the move, try the move, and then check what changed.

      -

      Jamie: Let's pause on 12. Finding More Contributions. What should a learner take away from it?

      -

      Alex: Keep the learner anchored in 12. Finding More Contributions. After the workshop, use these resources to find your next open source contribution.

      -

      Alex: Keep the teaching thread moving. The reason 14b. Learning Pathways matters is that not sure where to start after the workshop?

      +

      Jamie: Let's pause on Getting the current branch name. What should a learner take away from it?

      +

      Alex: Start with Getting the current branch name: Create and switch branches without leaving your browser. The next useful detail is this: Manage branches from your terminal. Think of it like entering a new building: first you find the lobby, then the room, then the door you actually need.

      +

      Alex: First, press VO+M to move to the menu bar, then VO+Right Arrow to the status bar area. Then, or use the Command Palette: Cmd+Shift+P then type "Git: Show Git Output" - the output pane includes the current branch. After that, on the repository page, find the branch dropdown button (shows "main" by default) - it is above the file table. Finally, click or activate the dropdown. Think of it as a rail line: each stop confirms you are still on the right route before the next one.

      +

      Jamie: Before we leave Getting the current branch name, what is the practical point?

      +

      Alex: First, type a new branch name in the search field. Then, click "Create branch: your-branch-name from main" when it appears. After that, GitHub switches to the new branch immediately. Finally, any file edits in the browser will be on this branch. Treat it like a recipe: do not add the next ingredient until the previous one is actually in the bowl.

      +

      Alex: Treat examples as spoken recipes, not decorations. You may hear something like 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. 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'. Read the command, understand what it changes, then run it only when the repository state matches the lesson.

      +

      Jamie: Let's pause on 4. Staging Changes - Files, Lines, and Chunks. What should a learner take away from it?

      +

      Alex: Here is the plain-English version of 4. Staging Changes - Files, Lines, and Chunks. This lets you commit only part of your work, leaving the rest for a later commit.

      +

      Alex: First, stage the changes you want to include. Then, commit those staged changes. Treat it like a recipe: do not add the next ingredient until the previous one is actually in the bowl.

      +

      Jamie: Let's pause on Staging an Entire File. What should a learner take away from it?

      +

      Alex: This is where Staging an Entire File becomes real: low vision users (zoom, high contrast). That matters in practice: Screen reader users (NVDA / JAWS / VoiceOver).

      +

      Alex: The practical takeaway is this. 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.

      +

      Alex: First, open Source Control: Ctrl+Shift+G (Mac: Cmd+Shift+G). Then, hover over a file in the "Changes" list - a + icon appears to its right. After that, click the + to stage that file. Finally, or right-click a file → "Stage Changes". It is a checklist, but a meaningful one: every item creates evidence that the next step is safe.

      +

      Jamie: Before we leave Staging an Entire File, what is the practical point?

      +

      Alex: First, at high zoom, the + (stage), undo (discard), and open file icons may be small. Instead of hovering. Then, 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. After that, in high contrast themes, staged files show a distinct background or border in the Staged Changes section. Finally, navigate to the file in the "Changes" list. It is like walking a hallway with named doors: read the sign, enter the right room, then confirm where you landed.

      -

      Jamie: What is the safe way to learn from that example?

      -

      Alex: Start with 16. Your Workshop Documentation - Offline Reference: Every guide from this workshop lives in your fork. The next useful detail is this: Clone your fork once and the complete documentation works offline - no internet required.

      -

      Alex: Treat examples as spoken recipes, not decorations. You may hear something like git clone https://github.com/[your-username]/accessibility-agents.git. Read the command, understand what it changes, then run it only when the repository state matches the lesson.

      -

      Alex: Keep the teaching thread moving. Here is the plain-English version of Quick Navigation. Next: Appendix Y: Workshop Materials Back: Appendix W: GitHub Pages Teaching chapter: All chapters. It is like learning a transit route. The names of the stops matter because they tell you whether you are still going the right direction.

      +

      Jamie: Let's pause on Alternative (keyboard shortcut). What should a learner take away from it?

      +

      Alex: Start with Alternative (keyboard shortcut). There is something to understand, something to try, and something that proves the try worked.

      +

      Alex: The practical takeaway is this. Focus the file → press Space.

      +

      Alex: Keep the thread going. Start with Alternative (context menu). There is something to understand, something to try, and something that proves the try worked.

      +

      Alex: The practical takeaway is this. Focus the file → press Shift+F10 (Mac: Ctrl+Return) → select "Stage Changes".

      +

      Jamie: Let's pause on What happens. What should a learner take away from it?

      +

      Alex: Start with What happens. There is something to understand, something to try, and something that proves the try worked.

      +

      Alex: The practical takeaway is this. The file moves from "Changes" → "Staged Changes". A green "A" or "M" indicator appears.

      -

      Jamie: What should people carry with them after this?

      -

      Alex: Carry the map. Know what page or tool you are in, know which action you are taking, and know what confirmation should follow. If the confirmation is missing, pause. That pause is not wasted time; it is professional judgment.

      -

      Jamie: That is a better way to say it than just follow the steps.

      -

      Alex: Right. Steps matter, but understanding wins. That is episode 38. Next in the series is episode 39, where we keep building the same contributor muscles.

      -
      - +

      Jamie: Let's pause on Staging Multiple Files at Once. What should a learner take away from it?

      +

      Alex: Here is the plain-English version of Staging Multiple Files at Once. All modified files move to "Staged Changes.".

      +

      Alex: First, ctrl+Shift+G (Mac: Cmd+Shift+G) to open Source Control. Then, navigate to the "Changes" section heading. After that, press Shift+F10 (Mac: Ctrl+Return) to open context menu on the section itself. Finally, select "Stage All Changes". Treat it like a recipe: do not add the next ingredient until the previous one is actually in the bowl.

      +

      Jamie: Let's pause on Staging Individual Lines or Chunks. What should a learner take away from it?

      +

      Alex: This is where Staging Individual Lines or Chunks becomes real: this is one of Git's most powerful features: You can stage only specific lines of a file, leaving other changes unstaged.

      +

      Jamie: Let's pause on Workflow. What should a learner take away from it?

      +

      Alex: Keep the learner anchored in Workflow. Result: Only those lines are staged. This is the part to say slowly: The rest of the file remains in "Changes.". A good GitHub workflow is like a well-run meeting: everyone knows the topic, the next action, and who has the floor.

      +

      Alex: First, open Source Control: Ctrl+Shift+G (Mac: Cmd+Shift+G). Then, navigate to a file in "Changes". After that, press Enter to open the diff view. Finally, the diff shows your changes side-by-side or inline. It is like walking a hallway with named doors: read the sign, enter the right room, then confirm where you landed.

      +

      Jamie: Before we leave Workflow, what is the practical point?

      +

      Alex: First, navigate to a changed line (use Arrow keys or F7 for next hunk). Then, press Shift+F10 (Mac: Ctrl+Return) to open context menu. After that, select "Stage Selected Lines". The rhythm is simple: orient, act, verify, then continue.

      -

      Episode 39: Accessibility Agents - Complete Reference

      -

      All 55 agents, all 54+ slash commands, customization, and troubleshooting.

      -

      Based on: Appendix L: Accessibility Agents - Complete Reference

      -

      Audio and transcript are being regenerated for this episode.

      -
      -Read Transcript - Episode 39: Accessibility Agents - Complete Reference - -

      Transcript

      -

      Alex: Welcome to episode 39 of Git Going with GitHub: Accessibility Agents - Complete Reference. I am Alex, and today we are teaching this topic as a conversation you can carry into the workshop, not as a page you have to memorize.

      -

      Jamie: And I am Jamie. I will keep pulling the lesson back to real learners, real repositories, and the evidence that proves the work happened.

      +

      Jamie: Let's pause on Use case for this workshop. What should a learner take away from it?

      +

      Alex: The reason Use case for this workshop matters is that in the diff view, press Alt+H to see Accessible Help for diff-specific keyboard shortcuts. That gives the learner a simple foothold: web alternative (github.com) - editing files.

      +

      Alex: The practical takeaway is this. 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".

      +

      Alex: First, click the pencil icon on any file to open the web editor. Then, make your changes. After that, click "Commit changes" - GitHub creates the commit directly. Finally, choose to commit to the current branch or create a new branch and PR. The rhythm is simple: orient, act, verify, then continue.

      +

      Alex: Treat examples as spoken recipes, not decorations. You may hear something like 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. Read the command, understand what it changes, then run it only when the repository state matches the lesson.

      +

      Jamie: Let's pause on Reverse the process. What should a learner take away from it?

      +

      Alex: Start with Reverse the process. There is something to understand, something to try, and something that proves the try worked.

      +

      Alex: First, focus the file in "Staged Changes". Then, press Ctrl+Enter (Mac: Cmd+Enter) or Space. After that, file moves back to "Changes". Think of it as a rail line: each stop confirms you are still on the right route before the next one.

      +

      Jamie: Let's pause on Learning Cards: Staging Changes. What should a learner take away from it?

      +

      Alex: Start with Learning Cards: Staging Changes. There is something to understand, something to try, and something that proves the try worked.

      +

      Alex: The practical takeaway is this. 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. 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.

      -

      Alex: The lesson focus is All 55 agents, all 54+ slash commands, customization, and troubleshooting. We will treat every step as a teachable decision, because that is what makes the skill portable.

      -

      Jamie: So we should explain the why clearly enough that the steps make sense when the learner meets them later.

      -

      Alex: That is it. If a listener only has audio right now, they should still get the complete concept and know what evidence would prove success.

      -
      -

      Jamie: There are a lot of tools in play. How do we keep that from feeling like a contest?

      -

      Alex: Start with Complete Reference - Agents, Slash Commands, Instructions, Configuration Levels, and All File Formats: This is your comprehensive reference for Accessibility Agents and the full VS Code Copilot customization system. The next useful detail is this: The ecosystem includes 55 agents across 3 teams and 5 platforms, plus 54+ slash commands, 17 skills, and 6 instruction files.

      -

      Alex: The next layer is this. Here is the plain-English version of 1. The Full Agent Ecosystem. Accessibility Agents includes 55 agents organized into three specialized teams, available on five platforms. It is like learning a transit route. The names of the stops matter because they tell you whether you are still going the right direction.

      -

      Jamie: What is the one idea that makes the next few steps less mysterious?

      -

      Alex: Start with Learning Cards: Agent Ecosystem Overview. There is something to understand, something to try, and something that proves the try worked.

      -

      Alex: That shows up in the workshop in a few specific ways. Invoke any agent by typing @agent-name in Copilot Chat (Ctrl+Shift+I) -- the autocomplete list is keyboard-navigable with arrow keys. The 55 agents are organized into 3 teams (Accessibility, GitHub Workflow, Developer Tools) -- use H in the team tables to jump between headings. Agent responses appear in the Chat panel; press Alt+F2 (Accessible View) for a structured, non-streaming version. The agent team tables use consistent columns (Agent, Type, What It Does) -- increase font size so the narrow "Type" column remains readable. Agents work in the Chat panel with your current theme and font settings -- no separate UI to configure. The five supported platforms (VS Code, Claude Code, Gemini CLI, Claude Desktop, Codex CLI) share the same agent logic with platform-specific formatting.

      -
      -

      Alex: Now bring the learner back to the room. Keep the learner anchored in 2. GitHub Workflow Agents - Quick Reference. The GitHub Workflow team includes 12 agents that automate common repository operations. This is the part to say slowly: These are good starting points if you have completed the Day 1 skills - but explore any agent in the ecosystem that matches your workflow.\n\nInvoke any agent by typing @agent-name in Copilot Chat (Ctrl+Shift+I).

      -

      Jamie: What would you say to someone who is already bracing for this to be too much?

      -

      Alex: The reason @daily-briefing - Morning Briefing matters is that agent file.github/agents/daily-briefing.agent.md.

      -

      Alex: The useful habit is simple: orient first, act second, verify third. That pause before acting is part of the work.

      -

      Alex: That matters because of the next idea. Start with Output sections (H2 headings - navigate with H). There is something to understand, something to try, and something that proves the try worked.

      -

      Alex: On the ground, that means a few things. Needs Your Action. Pull Requests Waiting for Your Review. @Mentions Requiring Response. CI Failures on Your Branches. For Your Awareness. Issues Opened Since Yesterday.

      -

      Alex: A solid navigation habit is to prove where you are before activating controls. Headings, landmarks, and the address bar are not trivia; they are your map.

      +

      Jamie: Let's pause on Standard process. What should a learner take away from it?

      +

      Alex: Start with Standard process. There is something to understand, something to try, and something that proves the try worked.

      +

      Alex: First, open Source Control: Ctrl+Shift+G (Mac: Cmd+Shift+G). Then, stage changes (see Section 4). After that, focus the commit message input (usually Tab or Shift+Tab to reach it). Finally, type your commit message. It is a checklist, but a meaningful one: every item creates evidence that the next step is safe.

      +

      Jamie: Before we leave Standard process, what is the practical point?

      +

      Alex: First, press Ctrl+Enter (Mac: Cmd+Enter) to commit. It is like walking a hallway with named doors: read the sign, enter the right room, then confirm where you landed.

      +

      Jamie: Let's pause on Learning Cards: Committing. What should a learner take away from it?

      +

      Alex: Keep the learner anchored in Learning Cards: Committing. Low vision users (zoom, high contrast).

      +

      Alex: First, open Source Control (Ctrl+Shift+G). Then, stage your files (click the + icon next to each file, or click Stage All Changes above the Changes section header). After that, click in the "Message" text area at the top of the Source Control panel. Finally, type your commit message. It is like walking a hallway with named doors: read the sign, enter the right room, then confirm where you landed.

      +

      Jamie: Before we leave Learning Cards: Committing, what is the practical point?

      +

      Alex: First, click the Commit button (checkmark icon) or press Ctrl+Enter. Then, 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. After that, 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. Finally, 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. The rhythm is simple: orient, act, verify, then continue.

      +

      Alex: Here is the practical turn. Start with NVDA/JAWS. There is something to understand, something to try, and something that proves the try worked.

      +

      Alex: The practical takeaway is this. 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).

      -

      Jamie: Okay, set the room for us. What are we walking into?

      -

      Alex: Here is the plain-English version of @issue-tracker - Issue Management. Agent file.github/agents/issue-tracker.agent.md. Put another way, the agent drafts replies.

      -

      Alex: A solid issue habit is to read the title, the body, and the timeline before acting. You are listening for the requested action, the missing evidence, and the person who needs a response.

      -

      Alex: This is where the talk moves from concept to action. This is where @pr-review - Pull Request Review becomes real: agent file.github/agents/pr-review.agent.md.

      -

      Alex: A solid pull request habit is to separate three questions: what changed, why it changed, and what still needs review. That keeps the conversation useful instead of noisy.

      -

      Jamie: Where do you want a learner to place their attention here?

      -

      Alex: Keep the learner anchored in Output sections (H2/H3 headings). Critical rule: The agent produces a starting point. This is the part to say slowly: Read it, edit it, post it under your own name.

      -

      Alex: These are the details that keep the idea from floating away. Risk Assessment (High / Medium / Low). Files Changed (per-file descriptions). Suggested Inline Comments (prefixed: nit:, question:, suggestion:, important:, blocking:, praise:). Questions for the Author.

      +

      Jamie: Let's pause on VoiceOver. What should a learner take away from it?

      +

      Alex: Start with VoiceOver. There is something to understand, something to try, and something that proves the try worked.

      +

      Alex: The practical takeaway is this. 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.

      +

      Alex: Keep the teaching thread moving. Here is the plain-English version of Writing Good Commit Messages. See Culture & Etiquette: Writing Good Commit Messages for format guidance. It is like learning a transit route. The names of the stops matter because they tell you whether you are still going the right direction.

      +

      Jamie: What should happen before anyone copies and runs it?

      +

      Alex: This is where Format becomes real: common types: feat:, fix:, docs:, style:, refactor:, test:, chore.

      +

      Alex: The practical takeaway is this. First line: type + colon + short summary (50 characters max). Blank line. Optional body: detailed explanation. Optional footer: "Fixes 123" to link to issue.

      +

      Alex: Treat examples as spoken recipes, not decorations. You may hear something like 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. Read the command, understand what it changes, then run it only when the repository state matches the lesson.

      -

      Alex: Before the learner moves on. The reason @analytics - Team Analytics matters is that agent file.github/agents/analytics.agent.md. The interface gets friendlier when it stops being a wall of controls and starts being a set of named places.

      -

      Jamie: Give me the version that sounds like an instructor, not a manual.

      -

      Alex: Start with @insiders-a11y-tracker - Accessibility Change Monitor: Agent file.github/agents/insiders-a11y-tracker.agent.md.

      -

      Alex: Hold that next to this. Here is the plain-English version of What it monitors. Risk levels: High (regression), Medium (degraded), Low (improvement opportunity).

      +

      Alex: Keep the teaching thread moving. Start with What Happens After Commit. There is something to understand, something to try, and something that proves the try worked.

      +

      Alex: The practical takeaway is this. 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).

      +

      Jamie: Let's pause on 6. Push and Pull Operations. What should a learner take away from it?

      +

      Alex: The reason 6. Push and Pull Operations matters is that push sends your local commits to GitHub. That gives the learner a simple foothold: pull downloads new commits from GitHub to your local repository.

      +

      Jamie: Let's pause on After committing locally. What should a learner take away from it?

      +

      Alex: Start with After committing locally. There is something to understand, something to try, and something that proves the try worked.

      +

      Alex: First, open Source Control: Ctrl+Shift+G (Mac: Cmd+Shift+G). Then, look for the "Publish Branch" button (if this is a new branch) or "Sync Changes" button. After that, press Enter on that button. Think of it as a rail line: each stop confirms you are still on the right route before the next one.

      -

      Jamie: If I am listening before the workshop starts, what should settle in my mind first?

      -

      Alex: This is where @template-builder - Issue Template Wizard becomes real: agent file.github/agents/template-builder.agent.md.

      -

      Jamie: Turn that into a path someone can follow.

      -

      Alex: Keep the learner anchored in Guided workflow phases. Supported field types: markdown, input, textarea, dropdown, checkboxes. A good GitHub workflow is like a well-run meeting: everyone knows the topic, the next action, and who has the floor.

      -

      Alex: First, metadata: name, description, title prefix, auto-labels. Then, fields (one at a time): type → label → description → required → type-specific options. After that, review and output: complete YAML ready to save to.github/ISSUE TEMPLATE/. It is like walking a hallway with named doors: read the sign, enter the right room, then confirm where you landed.

      -

      Jamie: What stays the same when the tool changes?

      -

      Alex: The reason 3. Slash Commands and Prompts matters is that the repository includes 54+ slash commands. That gives the learner a simple foothold: type / in Copilot Chat to open the command menu.

      +

      Jamie: Let's pause on Alternative: Command Palette. What should a learner take away from it?

      +

      Alex: Start with Alternative: Command Palette. There is something to understand, something to try, and something that proves the try worked.

      +

      Alex: First, ctrl+Shift+P (Mac: Cmd+Shift+P). Then, type "git push". After that, select "Git: Push". Finally, VS Code pushes your commits to GitHub. Treat it like a recipe: do not add the next ingredient until the previous one is actually in the bowl.

      +

      Jamie: Let's pause on Learning Cards: Push and Pull. What should a learner take away from it?

      +

      Alex: This is where Learning Cards: Push and Pull becomes real: low vision users (zoom, high contrast). That matters in practice: Screen reader users (NVDA / JAWS on Windows).

      +

      Alex: First, 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. Then, 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. After that, 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. Finally, 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. It is a checklist, but a meaningful one: every item creates evidence that the next step is safe.

      +

      Jamie: Let's pause on Pushing. What should a learner take away from it?

      +

      Alex: Start with Pushing. There is something to understand, something to try, and something that proves the try worked.

      +

      Alex: First, after committing, press Ctrl+Shift+P, type "git push", select "Git: Push". Then, NVDA/JAWS announces "Pushing." in the status bar. After that, on success, a notification appears: "Successfully pushed" - if using NVDA, check NVDA+N to read recent notifications. Finally, for a new branch (first push), use "Git: Publish Branch" instead - this sets up the upstream tracking. It is like walking a hallway with named doors: read the sign, enter the right room, then confirm where you landed.

      -

      Alex: Here is the practical turn. Start with 4. Customization Primitives - Decision Guide: Before creating any file, choose the right primitive for the job. The next useful detail is this: Each primitive is a different file type with a different purpose, scope, and trigger.

      -

      Jamie: Let's pause on Instructions vs Agent? What should a learner take away from it?

      -

      Alex: Start with Instructions vs Agent? There is something to understand, something to try, and something that proves the try worked.

      -

      Alex: Here is what that changes in practice. Instructions guide behavior passively (always-on or file-scoped). Agents perform tasks actively (on-demand, tool-using).

      -

      Alex: Keep the thread going. Start with Prompt vs Agent? There is something to understand, something to try, and something that proves the try worked.

      -

      Alex: The room should hear these as checkpoints. Use a prompt for a single focused task you invoke explicitly. Use an agent when the task spans multiple steps, needs different tools, or should work as a subagent for other agents.

      +

      Jamie: Let's pause on Pulling. What should a learner take away from it?

      +

      Alex: Start with Pulling. There is something to understand, something to try, and something that proves the try worked.

      +

      Alex: First, press Ctrl+Shift+P, type "git pull", select "Git: Pull". Then, NVDA/JAWS announces "Pulling." then the status changes. After that, if there are conflicts, the Source Control panel shows a "Merge Changes" section - navigate there with Ctrl+Shift+G then Down Arrow. The rhythm is simple: orient, act, verify, then continue.

      +

      Jamie: Let's pause on Checking sync status. What should a learner take away from it?

      +

      Alex: Start with Checking sync status: Screen reader users (VoiceOver on macOS).

      +

      Alex: First, press Ctrl+Shift+P, type "Git: Show Git Output". Then, the output pane opens with push/pull log messages in plain text. After that, use Up/Down Arrow to read line by line. Think of it as a rail line: each stop confirms you are still on the right route before the next one.

      +

      Jamie: Before we leave Pushing, what is the practical point?

      +

      Alex: First, press Cmd+Shift+P, type "git push", select "Git: Push". Then, VoiceOver announces progress from the status bar. After that, on success, a notification toast appears - press VO+F3 to read the latest notification. Treat it like a recipe: do not add the next ingredient until the previous one is actually in the bowl.

      -

      Jamie: Let's pause on Prompt vs Skill? What should a learner take away from it?

      -

      Alex: Start with Prompt vs Skill? There is something to understand, something to try, and something that proves the try worked.

      -

      Alex: That becomes easier when you listen for these cues. Both appear as / slash commands. Use a prompt for one well-defined task. Use a skill when the workflow bundles scripts, templates, or reference docs alongside the instructions.

      -

      Alex: Another way to ground it. Start with Instructions vs Hooks? There is something to understand, something to try, and something that proves the try worked.

      -

      Alex: A few details make that real. Instructions guide the agent (non-deterministic). Hooks enforce behavior via shell commands at lifecycle events - they run regardless of what the agent was prompted to do.

      -

      Jamie: Let's pause on Learning Cards: Customization Primitives. What should a learner take away from it?

      -

      Alex: Start with Learning Cards: Customization Primitives. There is something to understand, something to try, and something that proves the try worked.

      -

      Alex: The practical anchors are these. The decision table maps each file type to its purpose -- navigate with T (next table) in browse mode, then arrow through rows. Key distinction: instructions are passive (always-on guidance), agents are active (on-demand task performers), hooks are deterministic (shell commands at lifecycle events). Use the "Choosing Between Primitives" Q&A pairs below the table to decide which file type fits your need. The 7-row decision table is the single most important reference here -- zoom in on the "When to Use" column for the clearest guidance. Each Q&A pair under "Choosing Between Primitives" is a short paragraph -- easy to scan at high magnification. Color-coded syntax in YAML frontmatter examples benefits from a high-contrast theme with distinct keyword colors.

      +

      Jamie: Before we leave Pulling, what is the practical point?

      +

      Alex: First, press Cmd+Shift+P, type "git pull", select "Git: Pull". Then, VoiceOver announces when the pull completes. After that, if conflicts exist, navigate to Source Control (Cmd+Shift+G) and review the Merge Changes section. It is a checklist, but a meaningful one: every item creates evidence that the next step is safe.

      +

      Jamie: How do you keep commands from becoming magic words?

      +

      Alex: Keep the learner anchored in Screen reader feedback. Git CLI alternative - push and pull. This is the part to say slowly: Web alternative (github.com) - push and pull. A good GitHub workflow is like a well-run meeting: everyone knows the topic, the next action, and who has the floor.

      +

      Alex: The practical takeaway is this. 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).

      +

      Alex: Treat examples as spoken recipes, not decorations. You may hear something like 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. Read the command, understand what it changes, then run it only when the repository state matches the lesson.

      +

      Jamie: Let's pause on What to do if push fails. What should a learner take away from it?

      +

      Alex: Start with What to do if push fails. There is something to understand, something to try, and something that proves the try worked.

      +

      Alex: The practical takeaway is this. 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). Error: "Rejected - non-fast-forward" → Someone else pushed changes; you need to pull first.

      -

      Alex: This is the part worth saying out loud. Here is the plain-English version of 5. Scope and Priority - All Levels. Every customization file exists at one of three scopes. Put another way, VS Code combines all matching files from all scopes and sends them to the model. It is like learning a transit route. The names of the stops matter because they tell you whether you are still going the right direction.

      -

      Jamie: What does the learner do first, second, and then after that?

      -

      Alex: Start with Priority Order (highest wins in conflicts). There is something to understand, something to try, and something that proves the try worked.

      -

      Alex: First, personal / User-level - your profile instructions override everything. Then, workspace / Repository-level -.github/copilot-instructions.md, AGENTS.md,.github/agents/.agent.md. After that, organization-level - organization-defined custom instructions (lowest priority). It is a checklist, but a meaningful one: every item creates evidence that the next step is safe.

      -

      Jamie: What is the ordered workflow?

      -

      Alex: Keep the learner anchored in User-Level File Locations (Personal, Cross-Workspace). All of these files roam with your VS Code Settings Sync. This is the part to say slowly: On this machine: C:\Users\jeffb\AppData\Roaming\Code - Insiders\User\prompts.

      -

      Alex: First, enable Settings Sync (Ctrl+Shift+P → "Settings Sync: Turn On"). Then, ctrl+Shift+P → "Settings Sync: Configure". After that, check "Prompts and Instructions". It is like walking a hallway with named doors: read the sign, enter the right room, then confirm where you landed.

      +

      Alex: Keep the teaching thread moving. Start with When to pull. There is something to understand, something to try, and something that proves the try worked.

      +

      Alex: The practical takeaway is this. Before you start work each day. When GitHub shows your branch is behind the remote. When preparing to merge a PR.

      +

      Jamie: Let's pause on How to pull. What should a learner take away from it?

      +

      Alex: Here is the plain-English version of How to pull. If there are conflicts: See Section 9.

      +

      Alex: First, ctrl+Shift+P (Mac: Cmd+Shift+P). Then, type "git pull". After that, select "Git: Pull". Finally, VS Code fetches and merges remote changes. Treat it like a recipe: do not add the next ingredient until the previous one is actually in the bowl.

      +

      Alex: Keep the teaching thread moving. Start with Auto-fetch setting. There is something to understand, something to try, and something that proves the try worked.

      +

      Alex: The practical takeaway is this. VS Code can check for remote changes automatically every few minutes. Enable: Settings (Ctrl+, - Mac: Cmd+,) → search "git autofetch" → set to true.

      -

      Jamie: Let's pause on How Multiple Files Are Combined. What should a learner take away from it?

      -

      Alex: The reason How Multiple Files Are Combined matters is that VS Code collects all matching instruction files from all scopes and includes them all in the chat context. That gives the learner a simple foothold: there is no single winner - all are combined.

      -

      Alex: That connects to another useful point. Start with 6. Always-On Instructions - All File Types: Always-on instructions are automatically included in every chat request. The next useful detail is this: You never invoke them - Copilot simply follows them. Think of it like entering a new building: first you find the lobby, then the room, then the door you actually need.

      -

      Jamie: Let's pause on Option A.github/copilot-instructions.md (Recommended). What should a learner take away from it?

      -

      Alex: Here is the plain-English version of Option A.github/copilot-instructions.md (Recommended). Version-controlled and team-shared. Put another way, auto-generate with: Type /init in Copilot Chat - VS Code analyzes your workspace and generates a tailored copilot-instructions.md.

      +

      Jamie: Let's pause on Syncing Your Fork with the Upstream Repository. What should a learner take away from it?

      +

      Alex: Keep the learner anchored in 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. This is the part to say slowly: Keeping your fork current prevents merge conflicts and ensures you're working with the latest code.

      +

      Jamie: Let's pause on The GitHub "Sync fork" Button (Quickest Method). What should a learner take away from it?

      +

      Alex: The reason The GitHub "Sync fork" Button (Quickest Method) matters is that for straightforward updates, GitHub has a built-in sync button.

      +

      Alex: First, navigate to your fork on GitHub. Then, on the repository page, look for the "This branch is N commits behind owner/repo:main" notice. After that, activate the "Sync fork" button next to it. Finally, GitHub automatically merges upstream changes into your fork's default branch. The rhythm is simple: orient, act, verify, then continue.

      +

      Jamie: Before we leave The GitHub "Sync fork" Button (Quickest Method), what is the practical point?

      +

      Alex: First, then pull those changes to your local clone: Git: Pull from the Command Palette. Think of it as a rail line: each stop confirms you are still on the right route before the next one.

      +

      Jamie: Let's pause on Screen reader path. What should a learner take away from it?

      +

      Alex: Start with Screen reader path: Limitation: The GitHub sync button only syncs the default branch. The next useful detail is this: For other branches, use the git method below.

      -

      Alex: Keep the teaching thread moving. This is where Option B: AGENTS.md (Multi-Tool / Monorepo) becomes real: best for: Projects that use multiple AI tools (Copilot, Claude Code, Gemini CLI, etc.) where a single instruction file should work across all of them. That matters in practice: Also best for monorepos where different folders need different rules.

      -

      Jamie: Let's pause on Nested (per subfolder - experimental). What should a learner take away from it?

      -

      Alex: Keep the learner anchored in Nested (per subfolder - experimental). Enable nested file support: chat.useNestedAgentsMdFiles: true in VS Code settings. This is the part to say slowly: File structure: Same as copilot-instructions.md - plain Markdown, no frontmatter.

      -

      Alex: Keep the teaching thread moving. The reason Option C: CLAUDE.md (Claude Code Compatibility) matters is that best for: Teams that use Claude Code alongside VS Code. That gives the learner a simple foothold: VS Code recognizes all four locations when chat.useClaudeMdFile is enabled (default: on). The interface gets friendlier when it stops being a wall of controls and starts being a set of named places.

      +

      Jamie: What should they understand before typing anything?

      +

      Alex: Here is the plain-English version of Adding the Upstream Remote (One-Time Setup). To sync locally using git, you first configure the upstream remote. Put another way, this only needs to be done once per clone. It is like learning a transit route. The names of the stops matter because they tell you whether you are still going the right direction.

      +

      Alex: Treat examples as spoken recipes, not decorations. You may hear something like 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. Read the command, understand what it changes, then run it only when the repository state matches the lesson.

      +

      Jamie: Let's pause on Example for Accessibility Agents. What should a learner take away from it?

      +

      Alex: Start with Example for Accessibility Agents. There is something to understand, something to try, and something that proves the try worked.

      +

      Alex: Treat examples as spoken recipes, not decorations. You may hear something like git remote add upstream https://github.com/community-access/accessibility-agents.git. Read the command, understand what it changes, then run it only when the repository state matches the lesson.

      +

      Jamie: Let's pause on Fetching and Merging Upstream Changes. What should a learner take away from it?

      +

      Alex: Keep the learner anchored in Fetching and Merging Upstream Changes. Once your upstream remote is configured.

      +

      Alex: Treat examples as spoken recipes, not decorations. You may hear something like 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. Read the command, understand what it changes, then run it only when the repository state matches the lesson.

      -

      Jamie: Let's pause on Option D: Settings-Based Instructions (Deprecated). What should a learner take away from it?

      -

      Alex: Start with Option D: Settings-Based Instructions (Deprecated): Settings-based instructions may be removed in a future VS Code version. The next useful detail is this: Use file-based instructions instead for new work.

      -

      Alex: Keep the teaching thread moving. Here is the plain-English version of Organization-Level Instructions (GitHub Enterprise). Organization administrators can define custom instructions that apply to all repositories in the organization. Put another way, every team member gets these instructions automatically.

      -

      Jamie: What is the common workflow underneath the different interfaces?

      -

      Alex: This is where To enable discovery in VS Code becomes real: organization instructions are the lowest priority - workspace and user instructions override them when they conflict.

      +

      Jamie: Let's pause on When Conflicts Occur During Sync. What should a learner take away from it?

      +

      Alex: The reason When Conflicts Occur During Sync matters is that see also: Chapter 07: Merge Conflicts for a dedicated walkthrough of conflict resolution. That gives the learner a simple foothold: if you've made changes to the same files the upstream has changed, merge conflicts can occur during sync.

      +

      Alex: Keep the teaching thread moving. Start with 7. Discarding Changes: Discarding = permanently deleting your local edits. The next useful detail is this: The file reverts to the state of the last commit. Think of it like entering a new building: first you find the lobby, then the room, then the door you actually need.

      +

      Jamie: Let's pause on When to Discard. What should a learner take away from it?

      +

      Alex: Start with When to Discard. There is something to understand, something to try, and something that proves the try worked.

      +

      Alex: The practical takeaway is this. You made experimental changes and they didn't work. You want to start over from the last commit. You accidentally edited the wrong file.

      -

      Alex: Keep the teaching thread moving. Keep the learner anchored in 7. File-Based Instructions (.instructions.md). File-based instructions load conditionally - either when the files you are editing match a glob pattern, or when the agent determines the instruction is relevant to the current task. This is the part to say slowly: Use for: Language-specific rules, framework conventions, module-specific standards that only apply to part of the codebase. A good GitHub workflow is like a well-run meeting: everyone knows the topic, the next action, and who has the floor.

      -

      Jamie: Let's pause on The applyTo Glob Pattern. What should a learner take away from it?

      -

      Alex: The reason The applyTo Glob Pattern matters is that applyTo specifies which files trigger automatic inclusion of these instructions. That gives the learner a simple foothold: when a file matching the pattern is part of the chat context, the instructions are included automatically.

      -

      Alex: Keep the teaching thread moving. Start with Writing Effective Instructions: Guidance from GitHub's accessibility team on writing instructions that Copilot actually follows. The next useful detail is this: Share your instructions: The github/awesome-copilot repository collects community-contributed instructions files.

      -

      Alex: For a learner, the useful signals are these. Use normative language. Write MUST, MUST NOT, SHOULD, SHOULD NOT, and MAY for rules. LLMs respond well to these terms because they reduce ambiguity -- the same words used in WCAG. Example: Keyboard shortcuts MUST NOT override browser or OS shortcuts. Use lists and checklists. Structured lists provide guardrails that keep Copilot on track. Format accessibility requirements as a checklist so no criterion is overlooked. Specify your versions and standards. This application MUST conform to WCAG 2.2 Level AA is more useful than a general reference to accessibility. Include your design system's component names and flag deprecated components explicitly: DeprecatedButton MUST NOT. Focus on what Copilot doesn't already know. Instructions should add net-new information -- your team's conventions, exceptions, and priorities -- not restate what Copilot was trained on.

      +

      Jamie: Let's pause on Single file. What should a learner take away from it?

      +

      Alex: Start with Single file. There is something to understand, something to try, and something that proves the try worked.

      +

      Alex: First, open Source Control: Ctrl+Shift+G. Then, navigate to the file in "Changes". After that, press Shift+F10 for context menu. Finally, select "Discard Changes". It is a checklist, but a meaningful one: every item creates evidence that the next step is safe.

      +

      Jamie: Before we leave Single file, what is the practical point?

      +

      Alex: First, confirm in the warning dialog (VS Code will ask "Are you sure?"). It is like walking a hallway with named doors: read the sign, enter the right room, then confirm where you landed.

      +

      Jamie: Let's pause on All changes. What should a learner take away from it?

      +

      Alex: Keep the learner anchored in All changes. Screen reader warning: VS Code shows a modal confirmation dialog. This is the part to say slowly: Navigate with Tab, select "Discard" or "Cancel" with Enter.

      +

      Alex: First, ctrl+Shift+G. Then, navigate to the "Changes" section heading. After that, shift+F10 for context menu. Finally, select "Discard All Changes". It is like walking a hallway with named doors: read the sign, enter the right room, then confirm where you landed.

      +

      Jamie: Before we leave All changes, what is the practical point?

      +

      Alex: First, confirm (this affects every modified file). The rhythm is simple: orient, act, verify, then continue.

      +

      Jamie: Let's pause on Learning Cards: Discarding Changes. What should a learner take away from it?

      +

      Alex: The reason Learning Cards: Discarding Changes matters is that low vision users (zoom, high contrast). That gives the learner a simple foothold: screen reader users (NVDA / JAWS on Windows). The interface gets friendlier when it stops being a wall of controls and starts being a set of named places.

      +

      Alex: First, 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.". Then, 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. After that, for "Discard All Changes", right-click the "Changes" section heading to get the context menu. Finally, 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"). The rhythm is simple: orient, act, verify, then continue.

      -

      Jamie: How would you walk the room through that step by step?

      -

      Alex: Start with Command Palette method. There is something to understand, something to try, and something that proves the try worked.

      -

      Alex: First, ctrl+Shift+P → "Chat: New Instructions File". Then, choose Workspace or User Profile scope. After that, enter filename. Finally, add applyTo and/or description frontmatter. Treat it like a recipe: do not add the next ingredient until the previous one is actually in the bowl.

      -

      Jamie: Give me the sequence, because order matters here.

      -

      Alex: First, write instructions. It is a checklist, but a meaningful one: every item creates evidence that the next step is safe.

      -

      Alex: Keep the teaching thread moving. This is where Quick creation method becomes real: type /instructions in the Chat input to open the Configure Instructions menu. The workshop is closer to rehearsal than lecture. You hear the move, try the move, and then check what changed.

      -

      Jamie: Let's pause on Model Fallback Array. What should a learner take away from it?

      -

      Alex: Keep the learner anchored in Model Fallback Array. The first available model in the array is used. This is the part to say slowly: Useful for environments where not all models are licensed.

      +

      Jamie: What is the teaching move inside Single file?

      +

      Alex: First, press Ctrl+Shift+G to open Source Control. Then, navigate to the file in the Changes section with Down Arrow. After that, press Shift+F10 to open the context menu. Finally, navigate to "Discard Changes" with Down Arrow, press Enter. Think of it as a rail line: each stop confirms you are still on the right route before the next one.

      +

      Jamie: If someone only remembers one thing from Single file, what should it be?

      +

      Alex: First, a confirmation dialog appears - NVDA announces "Are you sure you want to discard changes" or similar. Then, press Tab to navigate between "Discard" and "Cancel", press Enter on your choice. Treat it like a recipe: do not add the next ingredient until the previous one is actually in the bowl.

      +

      Jamie: Let's pause on All files. What should a learner take away from it?

      +

      Alex: Here is the plain-English version of All files. Screen reader users (VoiceOver on macOS). Put another way, discard changes from your terminal.

      +

      Alex: First, navigate to the "Changes" section heading (announced as "Changes, expanded, N items"). Then, press Shift+F10, select "Discard All Changes". After that, confirm in the dialog. Finally, press Cmd+Shift+G to open Source Control. Treat it like a recipe: do not add the next ingredient until the previous one is actually in the bowl.

      +

      Jamie: Before we leave All files, what is the practical point?

      +

      Alex: First, use VO+Arrow keys to navigate to the file. Then, press VO+Shift+M to open the context menu (or Ctrl+Return). After that, navigate to "Discard Changes", press VO+Space. Finally, in the confirmation dialog, use VO+Right Arrow to reach the buttons, VO+Space to activate. It is a checklist, but a meaningful one: every item creates evidence that the next step is safe.

      +

      Alex: Treat examples as spoken recipes, not decorations. You may hear something like 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. Read the command, understand what it changes, then run it only when the repository state matches the lesson.

      +

      Jamie: Let's pause on Safer Alternative: Stash Instead of Discard. What should a learner take away from it?

      +

      Alex: This is where Safer Alternative: Stash Instead of Discard becomes real: if you're not sure whether you'll need these changes later, use stash (Section 10) instead of discard. That matters in practice: Stash saves your changes temporarily without committing them.

      -

      Alex: Keep the teaching thread moving. The reason [Section Header] matters is that [Describe the exact output structure here with placeholders].

      -

      Jamie: Let's pause on Creating Your Own Agent. What should a learner take away from it?

      -

      Alex: Start with Creating Your Own Agent: Write keyword-rich descriptions. The next useful detail is this: The description is how other agents decide whether to delegate to yours.

      -

      Alex: First, copy an existing.agent.md from.github/agents/. Then, edit the frontmatter (name, description, tools). After that, write clear step-by-step instructions in the body. Finally, add an Output Format section showing the expected structure. Think of it as a rail line: each stop confirms you are still on the right route before the next one.

      -

      Jamie: Before we leave Creating Your Own Agent, what is the practical point?

      -

      Alex: First, add Constraints and Scope Boundaries sections. Then, save to.github/agents/your-agent-name.agent.md. After that, reload VS Code: Ctrl+Shift+P → "Reload Window". Finally, type @your-agent-name in Copilot Chat. Treat it like a recipe: do not add the next ingredient until the previous one is actually in the bowl.

      -

      Alex: Keep the teaching thread moving. Start with Learning Cards.agent.md - Complete Format Reference. There is something to understand, something to try, and something that proves the try worked.

      -

      Alex: The parts worth keeping in working memory are these. YAML frontmatter is the first block in the file between --- delimiters -- arrow through it line by line to verify name, description, and tools fields; indentation matters. The name field in frontmatter is what you type after @ in Copilot Chat -- if the agent does not appear, check this field matches your invocation and reload VS Code (Ctrl+Shift+P then "Reload Window"). Use Chat Diagnostics (gear icon in Chat header then Diagnostics) to verify your agent loaded successfully -- it lists every agent found, with error details if frontmatter parsing failed. Agent files are small Markdown documents typically under 100 lines -- increase editor font size and use a theme with distinct YAML keyword colors so frontmatter fields stand out. The tools list in frontmatter uses array syntax (["read", "search"]) -- at high zoom, verify commas and quotes are correct since YAML is sensitive to formatting. The body template structure (Constraints, Behavior, Output Format, Scope Boundaries) uses headings -- use VS Code's Outline view (Ctrl+Shift+O) to navigate between sections.

      +

      Alex: Keep the teaching thread moving. Keep the learner anchored in 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 the part to say slowly: This is different from discarding changes - it permanently removes the file from the repository history going forward. A good GitHub workflow is like a well-run meeting: everyone knows the topic, the next action, and who has the floor.

      +

      Jamie: Let's pause on How to use. What should a learner take away from it?

      +

      Alex: The reason How to use matters is that the file is staged for deletion - you still need to commit to record the removal.

      +

      Alex: First, open the file you want to remove in the editor. Then, ctrl+Shift+P (Mac: Cmd+Shift+P). After that, type "Git: Delete". Finally, confirm the deletion. The rhythm is simple: orient, act, verify, then continue.

      +

      Alex: Keep the teaching thread moving. Start with When to use Git Delete vs. just deleting the file. There is something to understand, something to try, and something that proves the try worked.

      +

      Alex: The practical takeaway is this. 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.

      -

      Jamie: Let's pause on Complete Frontmatter Reference. What should a learner take away from it?

      -

      Alex: Start with Complete Frontmatter Reference. There is something to understand, something to try, and something that proves the try worked.

      -

      Jamie: Let's pause on Tool Priority When Agent Is Also Specified. What should a learner take away from it?

      -

      Alex: Keep the learner anchored in Tool Priority When Agent Is Also Specified. When both the prompt and the referenced agent define tools, VS Code uses this priority.

      -

      Alex: First, tools listed in the prompt file's frontmatter (highest priority). Then, tools from the referenced custom agent. After that, default tools for the selected agent mode. It is like walking a hallway with named doors: read the sign, enter the right room, then confirm where you landed.

      -

      Jamie: Let's pause on Input Parameters. What should a learner take away from it?

      -

      Alex: Start with Input Parameters. There is something to understand, something to try, and something that proves the try worked.

      -

      Alex: The practical takeaway is this. parameterName - internal identifier (no spaces). The text after the second: is shown to the user as a placeholder or tooltip. Multiple parameters are supported in one prompt file.

      +

      Jamie: Let's pause on Learning Cards: Deleting a File from the Repository. What should a learner take away from it?

      +

      Alex: Here is the plain-English version of Learning Cards: Deleting a File from the Repository. Alternatively: Ctrl+Shift+P then "Git: Delete" removes the file and stages the deletion in one step. Put another way, low vision users (zoom, high contrast).

      +

      Alex: First, right-click the file in the Explorer panel (Ctrl+Shift+E). Then, select "Delete" to delete from your file system. After that, the file appears in Source Control (Ctrl+Shift+G) under Changes with a "D" (deleted) status. Finally, stage and commit the deletion to record it in Git. Treat it like a recipe: do not add the next ingredient until the previous one is actually in the bowl.

      +

      Jamie: Before we leave Learning Cards: Deleting a File from the Repository, what is the practical point?

      +

      Alex: First, 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. Then, 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. After that, stage and commit as normal. Finally, open the file you want to remove in the editor. It is a checklist, but a meaningful one: every item creates evidence that the next step is safe.

      +

      Alex: Treat examples as spoken recipes, not decorations. You may hear something like 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. Read the command, understand what it changes, then run it only when the repository state matches the lesson.

      +

      Alex: Keep the teaching thread moving. This is where 8. Timeline View - File History and Blame becomes real: the Timeline view shows the Git history of the currently open file: every commit that touched this file, who made it, and when. The workshop is closer to rehearsal than lecture. You hear the move, try the move, and then check what changed.

      +

      Jamie: Let's pause on Method 1: Explorer Sidebar. What should a learner take away from it?

      +

      Alex: Start with Method 1: Explorer Sidebar. There is something to understand, something to try, and something that proves the try worked.

      +

      Alex: First, open Explorer: Ctrl+Shift+E. Then, at the bottom of the Explorer, there's a "Timeline" section. After that, tab or Arrow to navigate into Timeline. Finally, the list shows all commits affecting the currently open file. It is like walking a hallway with named doors: read the sign, enter the right room, then confirm where you landed.

      -

      Jamie: Let's pause on Creating Your Own Slash Command. What should a learner take away from it?

      -

      Alex: Start with Creating Your Own Slash Command: Both prompts and agent skills appear as / slash commands. The next useful detail is this: The difference: prompts are single-task Markdown files; skills are folders with bundled scripts and references. Think of it like entering a new building: first you find the lobby, then the room, then the door you actually need.

      -

      Alex: First, copy an existing.prompt.md from.github/prompts/. Then, edit frontmatter (name, description, tools). After that, write the task instructions in plain English. Finally, add ${input.} placeholders where the user must provide values. Think of it as a rail line: each stop confirms you are still on the right route before the next one.

      -

      Jamie: Before we leave Creating Your Own Slash Command, what is the practical point?

      -

      Alex: First, save to.github/prompts/your-command.prompt.md. Then, reload VS Code: Ctrl+Shift+P → "Reload Window". After that, type /your-command to invoke it. Treat it like a recipe: do not add the next ingredient until the previous one is actually in the bowl.

      -

      Jamie: What should someone listen for when a lesson offers more than one tool path?

      -

      Alex: Start with Learning Cards: Prompts and Slash Commands. There is something to understand, something to try, and something that proves the try worked.

      -

      Alex: The practical takeaway is this. Type / in Copilot Chat to see all available slash commands -- the autocomplete list reads each command name and description aloud.prompt.md files use YAML frontmatter for metadata (name, description, tools) followed by plain Markdown instructions. Use ${input:variableName} placeholders in prompts to create interactive fill-in-the-blank commands that prompt the user at invocation. The slash command picker popup is themed to match your current VS Code theme -- ensure your theme has sufficient contrast for dropdown items.prompt.md files are small Markdown files that are easy to read and edit at high zoom -- typically under 50 lines. The YAML frontmatter block at the top is indentation-sensitive -- use VS Code's indentation guides or a linter to verify structure.

      -

      Alex: Keep the teaching thread moving. This is where 10. Agent Skills (SKILL.md) - Complete Format Reference becomes real: a Skill is a folder - not a single file. That matters in practice: The folder contains SKILL.md plus any scripts, templates, and reference documents the skill needs.

      +

      Jamie: Let's pause on Method 2: Command Palette. What should a learner take away from it?

      +

      Alex: Start with Method 2: Command Palette. There is something to understand, something to try, and something that proves the try worked.

      +

      Alex: First, open a file in the editor. Then, ctrl+Shift+P. After that, type "timeline". Finally, select "View: Show Timeline". The rhythm is simple: orient, act, verify, then continue.

      +

      Jamie: Let's pause on What Timeline Shows. What should a learner take away from it?

      +

      Alex: Start with What Timeline Shows: Screen reader announcement: "docs: add Timeline Guide, Jeff, 2 days ago".

      +

      Alex: The practical takeaway is this. Commit message (first line). Author name. Relative time (example: "3 days ago" or "2 hours ago"). Commit hash (short form, like a3f2b9c).

      +

      Jamie: Let's pause on Viewing a Commit's Changes. What should a learner take away from it?

      +

      Alex: Here is the plain-English version of Viewing a Commit's Changes. This is incredibly useful for understanding. It is like learning a transit route. The names of the stops matter because they tell you whether you are still going the right direction.

      +

      Alex: The practical takeaway is this. When a particular line was added. Why a section was removed. What the file looked like at any point in history.

      +

      Alex: First, navigate to a commit in the Timeline list. Then, press Enter. After that, a diff view opens showing what changed in that specific commit. Treat it like a recipe: do not add the next ingredient until the previous one is actually in the bowl.

      -

      Jamie: Before we leave Complete Frontmatter Reference, what is the practical point?

      -

      Jamie: Let's pause on Progressive Loading - How VS Code Loads Skills. What should a learner take away from it?

      -

      Alex: The reason Progressive Loading - How VS Code Loads Skills matters is that move reference material to references/ folder files. The interface gets friendlier when it stops being a wall of controls and starts being a set of named places.

      -

      Alex: First, discovery ( 100 tokens): Reads name and description to decide if the skill is relevant. Then, instructions (<5000 tokens): Loads the full SKILL.md body when the skill is relevant. After that, resources: Additional files (scripts/, references/) only load when explicitly referenced from SKILL.md. The rhythm is simple: orient, act, verify, then continue.

      -

      Jamie: Let's pause on 11. Hooks (.json) - Lifecycle Automation. What should a learner take away from it?

      -

      Alex: Start with 11. Hooks (.json) - Lifecycle Automation: Hooks execute shell commands at specific points in an agent's lifecycle. The next useful detail is this: They are deterministic - they run regardless of what the agent was prompted to do.

      +

      Jamie: Let's pause on Git Blame - Line-by-Line History. What should a learner take away from it?

      +

      Alex: This is where Git Blame - Line-by-Line History becomes real: Git Blame shows who last modified each line of the file.

      +

      Jamie: Let's pause on How to access. What should a learner take away from it?

      +

      Alex: Start with How to access. There is something to understand, something to try, and something that proves the try worked.

      +

      Alex: First, open a file in the editor. Then, ctrl+Shift+P. After that, type "git blame". Finally, select "Git: Toggle Blame". It is like walking a hallway with named doors: read the sign, enter the right room, then confirm where you landed.

      +

      Jamie: Let's pause on What appears. What should a learner take away from it?

      +

      Alex: Start with What appears. There is something to understand, something to try, and something that proves the try worked.

      +

      Alex: The practical takeaway is this. Inline annotations next to every line (visually). Hover over a line to see commit details.

      -

      Alex: Keep the teaching thread moving. Here is the plain-English version of File Locations. Hooks from all locations are combined - workspace and user hooks do not override each other.

      -

      Jamie: What should they understand before typing anything?

      -

      Alex: Start with Configuration Format. There is something to understand, something to try, and something that proves the try worked.

      -

      Alex: Treat examples as spoken recipes, not decorations. You may hear something like {; "hooks": {; "PreToolUse": [; {; "type": "command",; "command": ".github/hooks/validate-before-edit.sh",; "timeout": 15; }; ],; "PostToolUse": [; {; "type": "command",; "command": "npx prettier --write",; "windows": "npx.cmd prettier --write",; "timeout". Read the command, understand what it changes, then run it only when the repository state matches the lesson.

      -

      Alex: Keep the teaching thread moving. Keep the learner anchored in PreToolUse permission decisions. Permission decisions: "allow" "ask" (prompt user) "deny" (block the tool call). A good GitHub workflow is like a well-run meeting: everyone knows the topic, the next action, and who has the floor.

      +

      Alex: Keep the teaching thread moving. Start with For screen reader users: Useful blame settings (add to.vscode/settings.json or user Settings). Think of it like entering a new building: first you find the lobby, then the room, then the door you actually need.

      +

      Alex: The practical takeaway is this. 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.

      +

      Jamie: Let's pause on Learning Cards: Timeline and History. What should a learner take away from it?

      +

      Alex: Here is the plain-English version of Learning Cards: Timeline and History. Low vision users (zoom, high contrast). Put another way, screen reader users (NVDA / JAWS on Windows).

      +

      Alex: First, 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. Then, 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. After that, 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. Finally, 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. Treat it like a recipe: do not add the next ingredient until the previous one is actually in the bowl.

      +

      Jamie: Let's pause on Opening Timeline. What should a learner take away from it?

      +

      Alex: Start with Opening Timeline. There is something to understand, something to try, and something that proves the try worked.

      +

      Alex: First, press Ctrl+Shift+E to open Explorer. Then, press Tab repeatedly or Down Arrow to navigate past the file tree to the "Timeline" section. After that, press Right Arrow to expand it if collapsed. Finally, navigate commit entries with Up/Down Arrow. It is a checklist, but a meaningful one: every item creates evidence that the next step is safe.

      +

      Jamie: Before we leave Opening Timeline, what is the practical point?

      +

      Alex: First, each entry is announced as: "commit message, author, time" (e.g., "docs: add Timeline Guide, Jeff, 2 days ago"). Then, press Enter on any entry to open its diff view. It is like walking a hallway with named doors: read the sign, enter the right room, then confirm where you landed.

      -

      Jamie: Let's pause on Exit codes. What should a learner take away from it?

      -

      Alex: Start with Exit codes. There is something to understand, something to try, and something that proves the try worked.

      -

      Alex: The practical takeaway is this. 0 - success; agent continues. 2 - blocking error; agent stops. Other - non-blocking warning.

      -

      Alex: Keep the teaching thread moving. Start with Learning Cards: Hooks. There is something to understand, something to try, and something that proves the try worked.

      -

      Alex: The practical takeaway is this. Hooks are JSON files, not Markdown -- navigate them in the editor with arrow keys; each hook event (e.g., PreToolUse, PostToolUse) is a key in the "hooks" object. Hook output is returned as JSON on stdout -- the "continue" field (true/false) determines whether the agent proceeds; listen for the "stopReason" message if the hook blocks an action. The "permissionDecision" values (allow, ask, deny) control tool access -- ask triggers a confirmation dialog that your screen reader will announce as a standard VS Code dialog. JSON syntax requires careful attention to braces, brackets, and commas -- use VS Code's bracket pair colorization (editor.bracketPairColorization.enabled) and increase font size to verify structure. The hook events table maps each event name to when it fires -- zoom in on the "When It Fires" column to understand the lifecycle timing. Hook errors appear in the agent session output -- look for non-zero exit codes or "continue": false in the output pane.

      -

      Jamie: Let's pause on 12. preferences.md - Accessibility Agents Personal Settings. What should a learner take away from it?

      -

      Alex: Here is the plain-English version of 12. preferences.md - Accessibility Agents Personal Settings. Copy.github/agents/preferences.example.md to.github/agents/preferences.md. Put another way, the file is in.gitignore - your private settings stay only in your local fork.

      +

      Jamie: Let's pause on Reading a diff with screen reader. What should a learner take away from it?

      +

      Alex: Start with Reading a diff with screen reader. There is something to understand, something to try, and something that proves the try worked.

      +

      Alex: First, in the diff view, press Alt+F2 to open the Accessible Diff Viewer. Then, the Accessible Diff Viewer presents changes as a text list: each line shows + (added), - (removed), or unchanged. After that, navigate with Up/Down Arrow to read each line. Finally, press Escape to close the Accessible Diff Viewer. It is like walking a hallway with named doors: read the sign, enter the right room, then confirm where you landed.

      +

      Jamie: Let's pause on Git Blame. What should a learner take away from it?

      +

      Alex: The reason Git Blame matters is that screen reader users (VoiceOver on macOS). The interface gets friendlier when it stops being a wall of controls and starts being a set of named places.

      +

      Alex: First, open a file, press Ctrl+Shift+P, type "Git: Toggle Blame". Then, blame annotations appear inline - NVDA reads them when navigating lines. After that, to reduce noise, disable blame (repeat the toggle command) and use Timeline instead. The rhythm is simple: orient, act, verify, then continue.

      +

      Jamie: What is the teaching move inside Opening Timeline?

      +

      Alex: First, press Cmd+Shift+E to open Explorer. Then, use VO+Down Arrow to navigate below the file tree to the Timeline section. After that, press VO+Space to expand if collapsed. Finally, navigate entries with VO+Down Arrow. Think of it as a rail line: each stop confirms you are still on the right route before the next one.

      +

      Jamie: If someone only remembers one thing from Opening Timeline, what should it be?

      +

      Alex: First, press VO+Space on a commit to open its diff. Treat it like a recipe: do not add the next ingredient until the previous one is actually in the bowl.

      -

      Jamie: How do you keep commands from becoming magic words?

      -

      Alex: Start with Full File Template. There is something to understand, something to try, and something that proves the try worked.

      -

      Alex: Treat examples as spoken recipes, not decorations. You may hear something like My Accessibility Agents Preferences; My GitHub Username; your-github-username; Repositories I Work On Most; - community-access/accessibility-agents; - your-org/your-repo; Preferred Output Format; screen-reader-optimized; Notification Priority; Accessibility. Read the command, understand what it changes, then run it only when the repository state matches the lesson.

      -

      Jamie: Can you translate that into plain choices?

      -

      Alex: Start with Preferred Output Format Options. There is something to understand, something to try, and something that proves the try worked.

      -

      Alex: Use the comparison to make a decision, not to recite a table. The main contrasts are: "concise" means Bullet points and short summaries, minimal prose. "detailed" means Full context and more explanation in every response. "screen-reader-optimized" means Heading-heavy structure, no tables, explicit empty-state messages.

      -

      Alex: Keep the teaching thread moving. The reason Notification Priority Options matters is that the @daily-briefing agent reads this to sort its output sections.

      +

      Jamie: Let's pause on Accessible Diff Viewer. What should a learner take away from it?

      +

      Alex: Here is the plain-English version of Accessible Diff Viewer. Screen reader advantage: git log --oneline and git blame produce clean, columnar text output. Put another way, read line by line with arrow keys in the terminal.

      +

      Alex: First, in any diff view, press Option+F2 to open the Accessible Diff Viewer. Then, read changes line by line with VO+Down Arrow. After that, press Escape to close. Treat it like a recipe: do not add the next ingredient until the previous one is actually in the bowl.

      +

      Alex: Treat examples as spoken recipes, not decorations. You may hear something like 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. 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. Read the command, understand what it changes, then run it only when the repository state matches the lesson.

      +

      Jamie: What should someone listen for when a lesson offers more than one tool path?

      +

      Alex: This is where 9. Resolving Merge Conflicts in VS Code becomes real: merge conflicts happen when two people edit the same lines of a file. That matters in practice: Git can't decide which version to keep, so it asks you to choose.

      +

      Alex: Keep the teaching thread moving. Keep the learner anchored in How VS Code Displays Conflicts. When you open a file with conflicts, you see something like. This is the part to say slowly: VS Code adds buttons above each conflict (visually). A good GitHub workflow is like a well-run meeting: everyone knows the topic, the next action, and who has the floor.

      +

      Alex: The practical takeaway is this. "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).

      -

      Jamie: Let's pause on Review Comment Tone Options. What should a learner take away from it?

      -

      Alex: Start with Review Comment Tone Options: The @pr-review and @issue-tracker agents read this when drafting comments.

      -

      Jamie: What is the safe way to learn from that example?

      -

      Alex: Here is the plain-English version of Accessibility Context Options. Tells agents which screen reader and browser you use so they can tailor output and recommendations. It is like learning a transit route. The names of the stops matter because they tell you whether you are still going the right direction.

      -

      Alex: Treat examples as spoken recipes, not decorations. You may hear something like I use NVDA with Chrome on Windows 11.; I use VoiceOver with Safari on macOS Sonoma.; I use JAWS with Firefox on Windows 10.; I use Narrator with Edge on Windows 11.; I use TalkBack on Android. Read the command, understand what it changes, then run it only when the repository state matches the lesson.

      -

      Jamie: Let's pause on View All Loaded Customizations. What should a learner take away from it?

      -

      Alex: This is where View All Loaded Customizations becomes real: to see every instruction file, agent, prompt, and skill currently loaded and any errors. That matters in practice: This shows: which files were found, which were loaded, which have errors, and from which scope (user vs workspace vs organization).

      -

      Alex: First, in Copilot Chat, select the gear icon (Configure Chat) → Diagnostics. Then, or right-click in the Chat view → Diagnostics. It is a checklist, but a meaningful one: every item creates evidence that the next step is safe.

      +

      Jamie: Let's pause on Screen Reader Workflow for Resolving Conflicts. What should a learner take away from it?

      +

      Alex: The reason Screen Reader Workflow for Resolving Conflicts matters is that the buttons are NOT accessible via keyboard.

      +

      Alex: The practical takeaway is this. <<<<<<< marks the start. ======= separates the two versions. marks the end. The section between <<<<<<< and ======= is your current branch (HEAD). The section between ======= and is the incoming branch (the branch you're merging). Delete the conflict markers ( ).

      +

      Alex: First, identify the conflict markers. Then, read both versions. After that, decide what to keep. Finally, stage the resolved file. The rhythm is simple: orient, act, verify, then continue.

      +

      Jamie: Before we leave Screen Reader Workflow for Resolving Conflicts, what is the practical point?

      +

      Alex: First, commit the merge. Think of it as a rail line: each stop confirms you are still on the right route before the next one.

      +

      Jamie: Let's pause on Using Accessible Diff for Conflict Review. What should a learner take away from it?

      +

      Alex: Start with Using Accessible Diff for Conflict Review: Better approach: Use the Accessible Diff Viewer (F7) to navigate conflict hunks systematically.

      +

      Alex: First, open the conflicted file. Then, press F7 to jump to the first conflict hunk. After that, press Alt+F2 to open Accessible View. Finally, read both versions clearly. Think of it as a rail line: each stop confirms you are still on the right route before the next one.

      +

      Jamie: Before we leave Using Accessible Diff for Conflict Review, what is the practical point?

      +

      Alex: First, press Escape to return to editor. Then, manually edit to resolve. After that, press F7 to jump to the next conflict. Finally, repeat until all conflicts resolved. Treat it like a recipe: do not add the next ingredient until the previous one is actually in the bowl.

      +

      Jamie: Let's pause on Aborting a Merge. What should a learner take away from it?

      +

      Alex: Here is the plain-English version of Aborting a Merge. If you want to cancel the merge and go back to before you started. Put another way, everything returns to the pre-merge state.

      +

      Alex: First, ctrl+Shift+P. Then, type "git abort". After that, select "Git: Abort Merge". Treat it like a recipe: do not add the next ingredient until the previous one is actually in the bowl.

      -

      Jamie: Let's pause on Agent not found when typing @agent-name. What should a learner take away from it?

      -

      Alex: Start with Agent not found when typing @agent-name. There is something to understand, something to try, and something that proves the try worked.

      -

      Alex: First, verify.github/agents/[name].agent.md exists in your open workspace folder. Then, check that the YAML frontmatter has no syntax errors (missing quotes, wrong indentation). After that, ctrl+Shift+P → "Reload Window". Finally, check that the name field in the frontmatter matches what you are typing. It is like walking a hallway with named doors: read the sign, enter the right room, then confirm where you landed.

      -

      Jamie: Let's pause on Instructions not being applied. What should a learner take away from it?

      -

      Alex: Start with Instructions not being applied. There is something to understand, something to try, and something that proves the try worked.

      -

      Alex: First, for.github/copilot-instructions.md: file must be at workspace root in the.github/ folder. Then, for.instructions.md: check that applyTo glob matches the file you are editing, and that chat.includeApplyingInstructions is true in VS Code settings. After that, for AGENTS.md: check that chat.useAgentsMdFile is true. Finally, use Diagnostics view (above) to verify the file was found and loaded. The rhythm is simple: orient, act, verify, then continue.

      -

      Alex: Keep the teaching thread moving. Start with Instructions file in wrong place. There is something to understand, something to try, and something that proves the try worked.

      -

      Alex: The practical takeaway is this. Add custom locations: chat.instructionsFilesLocations setting accepts an array of additional folder paths.

      +

      Alex: Keep the teaching thread moving. Start with Learning Cards: Resolving Merge Conflicts. There is something to understand, something to try, and something that proves the try worked.

      +

      Alex: The practical takeaway is this. 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. 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.

      +

      Jamie: Let's pause on 10. Stash Management. What should a learner take away from it?

      +

      Alex: Keep the learner anchored in 10. Stash Management. Stash temporarily saves your uncommitted changes so you can switch branches or pull updates without committing half-finished work.

      +

      Alex: Keep the teaching thread moving. Start with When to Use Stash. There is something to understand, something to try, and something that proves the try worked.

      +

      Alex: The practical takeaway is this. 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.

      -

      Jamie: Let's pause on Slash command not appearing. What should a learner take away from it?

      -

      Alex: Start with Slash command not appearing. There is something to understand, something to try, and something that proves the try worked.

      -

      Alex: First, verify.github/prompts/[name].prompt.md exists. Then, ctrl+Shift+P → "Reload Window". After that, file must use.prompt.md extension (not just.md). Treat it like a recipe: do not add the next ingredient until the previous one is actually in the bowl.

      -

      Alex: Keep the teaching thread moving. This is where 14. Further Reading becomes real: for the broader ecosystem - the community plugin marketplace, MCP server integrations, and running agents in the cloud via GitHub Actions - see Appendix K: GitHub Copilot and Agentic Reference.

      -

      Jamie: Let's pause on Official accessibility.github.com Guides. What should a learner take away from it?

      -

      Alex: Keep the learner anchored in Official accessibility.github.com Guides. Next: Appendix M: Accessibility Standards Back: Appendix K: Copilot Reference Teaching chapter: Chapter 19: Accessibility Agents.

      +

      Jamie: Let's pause on Method 1: Command Palette. What should a learner take away from it?

      +

      Alex: Start with Method 1: Command Palette. There is something to understand, something to try, and something that proves the try worked.

      +

      Alex: First, ctrl+Shift+P. Then, type "git stash". After that, select "Git: Stash". Finally, optionally type a stash message (helps you remember what's in it). Think of it as a rail line: each stop confirms you are still on the right route before the next one.

      +

      Alex: Keep the teaching thread moving. Start with What happens. There is something to understand, something to try, and something that proves the try worked.

      +

      Alex: The practical takeaway is this. 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.

      +

      Jamie: Let's pause on Command Palette. What should a learner take away from it?

      +

      Alex: Start with Command Palette. There is something to understand, something to try, and something that proves the try worked.

      +

      Alex: First, ctrl+Shift+P. Then, type "git stash list". After that, select "Git: Show Stash". It is a checklist, but a meaningful one: every item creates evidence that the next step is safe.

      +
      +

      Jamie: Let's pause on Alternative: Integrated Terminal. What should a learner take away from it?

      +

      Alex: Start with Alternative: Integrated Terminal. There is something to understand, something to try, and something that proves the try worked.

      +

      Alex: Treat examples as spoken recipes, not decorations. You may hear something like git stash list. Read the command, understand what it changes, then run it only when the repository state matches the lesson.

      +

      Jamie: Let's pause on To restore your stashed changes. What should a learner take away from it?

      +

      Alex: Start with To restore your stashed changes. There is something to understand, something to try, and something that proves the try worked.

      +

      Alex: First, ctrl+Shift+P. Then, type "git stash apply". After that, select "Git: Apply Latest Stash". The rhythm is simple: orient, act, verify, then continue.

      +

      Jamie: Let's pause on Or to apply a specific stash. What should a learner take away from it?

      +

      Alex: Start with Or to apply a specific stash. There is something to understand, something to try, and something that proves the try worked.

      +

      Alex: First, ctrl+Shift+P. Then, type "git stash pop". After that, select "Git: Pop Stash.". Finally, choose which stash from the list. Think of it as a rail line: each stop confirms you are still on the right route before the next one.

      +
      +

      Jamie: Let's pause on Difference between Apply and Pop. What should a learner take away from it?

      +

      Alex: Start with Difference between Apply and Pop. There is something to understand, something to try, and something that proves the try worked.

      +

      Alex: The practical takeaway is this. Apply: restores changes and keeps the stash (you can apply it again later). Pop: restores changes and deletes the stash.

      +

      Jamie: Let's pause on Dropping a Stash. What should a learner take away from it?

      +

      Alex: This is where Dropping a Stash becomes real: if you no longer need what's in a stash.

      +

      Alex: First, ctrl+Shift+P. Then, type "git stash drop". After that, select "Git: Drop Stash.". Finally, choose which stash to delete. It is a checklist, but a meaningful one: every item creates evidence that the next step is safe.

      +

      Jamie: Let's pause on Learning Cards: Stash Management. What should a learner take away from it?

      +

      Alex: Keep the learner anchored in Learning Cards: Stash Management. If the Stashes section is not visible, use the Command Palette: Ctrl+Shift+P then type "git stash" to access all stash commands. This is the part to say slowly: Low vision users (zoom, high contrast).

      +

      Alex: First, open Source Control: Ctrl+Shift+G. Then, in the Source Control panel, there may be a "Stashes" section below Staged Changes (visible when stashes exist). After that, click a stash to see what it contains. Finally, right-click a stash to Apply, Pop, or Drop it. It is like walking a hallway with named doors: read the sign, enter the right room, then confirm where you landed.

      +

      Jamie: Before we leave Learning Cards: Stash Management, what is the practical point?

      +

      Alex: First, 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. Then, 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. After that, after applying a stash, your files reappear in the Changes section of Source Control. Check the file count to confirm. The rhythm is simple: orient, act, verify, then continue.

      +
      +

      Jamie: Let's pause on Creating a stash. What should a learner take away from it?

      +

      Alex: Start with Creating a stash. There is something to understand, something to try, and something that proves the try worked.

      +

      Alex: First, press Ctrl+Shift+P, type "git stash". Then, select "Git: Stash" - NVDA announces the result. After that, an input appears asking for a stash message - type something descriptive (e.g., "WIP: documentation changes for Timeline section"). Finally, press Enter - your changes disappear from Source Control and are saved in the stash. The rhythm is simple: orient, act, verify, then continue.

      +

      Jamie: Before we leave Creating a stash, what is the practical point?

      +

      Alex: First, NVDA announces the Source Control panel update (file counts drop to 0). Think of it as a rail line: each stop confirms you are still on the right route before the next one.

      +

      Jamie: Let's pause on Applying a stash. What should a learner take away from it?

      +

      Alex: Start with Applying a stash. There is something to understand, something to try, and something that proves the try worked.

      +

      Alex: First, press Ctrl+Shift+P, type "git stash pop". Then, select "Git: Pop Stash.". After that, a list of stashes appears - navigate with Up/Down Arrow. Finally, each item is announced with the stash message you wrote. Think of it as a rail line: each stop confirms you are still on the right route before the next one.

      +

      Jamie: Before we leave Applying a stash, what is the practical point?

      +

      Alex: First, press Enter to apply and delete the stash. Then, your changes reappear in the Changes section. Treat it like a recipe: do not add the next ingredient until the previous one is actually in the bowl.

      +

      Jamie: Let's pause on Viewing stashes. What should a learner take away from it?

      +

      Alex: Here is the plain-English version of Viewing stashes. Screen reader users (VoiceOver on macOS). Put another way, GitHub.com does not have a stash feature.

      +

      Alex: First, press Ctrl+Shift+P, type "git stash list". Then, or in the terminal: type git stash list and read the output line by line. After that, press Cmd+Shift+P, type "git stash". Finally, select "Git: Stash" and provide a message. Treat it like a recipe: do not add the next ingredient until the previous one is actually in the bowl.

      +

      Jamie: Before we leave Viewing stashes, what is the practical point?

      +

      Alex: First, press Return. Then, to apply: Cmd+Shift+P, type "git stash pop", select from the list with VO+Down Arrow, press Return. After that, create a draft commit on a temporary branch. Finally, or use GitHub Codespaces (which runs a full VS Code environment in the browser and supports git stash in the terminal). It is a checklist, but a meaningful one: every item creates evidence that the next step is safe.

      +

      Alex: Treat examples as spoken recipes, not decorations. You may hear something like 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. Read the command, understand what it changes, then run it only when the repository state matches the lesson.

      +
      +

      Jamie: What do you want them to do when the plan breaks?

      +

      Alex: This is where 10b. Emergency Recovery - git reflog becomes real: 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. That matters in practice: It is the most underused recovery tool in Git.

      +

      Jamie: What decision is this helping them make?

      +

      Alex: Start with When to Use Reflog. There is something to understand, something to try, and something that proves the try worked.

      +

      Alex: Use the comparison to make a decision, not to recite a table. The main contrasts are: Scenario means What happened means Reflog solution. Deleted a branch by mistake means git branch -D feature/x means Find the last commit SHA from reflog → recreate branch. git reset --hard lost commits means Moved HEAD to older commit means Find the SHA before the reset → reset back to it.

      +

      Jamie: Let's pause on Reading the Reflog in VS Code Terminal. What should a learner take away from it?

      +

      Alex: The reason Reading the Reflog in VS Code Terminal matters is that run this in the integrated terminal (Ctrl+Backtick). That gives the learner a simple foothold: the output is plain text - read line by line with ↓.

      +

      Alex: Treat examples as spoken recipes, not decorations. You may hear something like git reflog. Read the command, understand what it changes, then run it only when the repository state matches the lesson.

      +
      +

      Jamie: Let's pause on If you need to restore a commit that has been lost. What should a learner take away from it?

      +

      Alex: Start with If you need to restore a commit that has been lost: 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.

      +

      Alex: Treat examples as spoken recipes, not decorations. You may hear something like 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. Read the command, understand what it changes, then run it only when the repository state matches the lesson.

      +

      Jamie: Let's pause on Recovering a Deleted Branch. What should a learner take away from it?

      +

      Alex: Start with Recovering a Deleted Branch. There is something to understand, something to try, and something that proves the try worked.

      +

      Alex: Treat examples as spoken recipes, not decorations. You may hear something like 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. Read the command, understand what it changes, then run it only when the repository state matches the lesson.

      +

      Alex: Keep the teaching thread moving. This is where Why Reflog Is Local-Only becomes real: reflog records are stored in your local.git/ directory and are not pushed to GitHub. That matters in practice: 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. The workshop is closer to rehearsal than lecture. You hear the move, try the move, and then check what changed.

      +
      +

      Jamie: How should someone ask for help in a way that gets them unstuck faster?

      +

      Alex: Start with Learning Cards: Emergency Recovery. There is something to understand, something to try, and something that proves the try worked.

      +

      Alex: The practical takeaway is this. 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. 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.

      +

      Alex: Keep the teaching thread moving. The reason 11. Alternative Git Interfaces matters is that VS Code's Source Control panel is one way to use Git. That gives the learner a simple foothold: these alternatives exist for different workflows.

      +

      Jamie: What stays the same when the tool changes?

      +

      Alex: Start with GitHub Desktop. There is something to understand, something to try, and something that proves the try worked.

      +

      Alex: The practical takeaway is this. Graphical Git client. Download: 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.

      +
      +

      Alex: Keep the teaching thread moving. Start with GitHub CLI (gh). There is something to understand, something to try, and something that proves the try worked.

      +

      Alex: The practical takeaway is this. 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).

      +

      Jamie: Let's pause on Common commands. What should a learner take away from it?

      +

      Alex: This is where Common commands becomes real: see Culture & Etiquette for more gh examples.

      +

      Alex: Treat examples as spoken recipes, not decorations. You may hear something like 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. Read the command, understand what it changes, then run it only when the repository state matches the lesson.

      +

      Alex: Keep the teaching thread moving. Start with Git CLI (Terminal). There is something to understand, something to try, and something that proves the try worked.

      +

      Alex: The practical takeaway is this. The standard Git command-line interface. Included with VS Code (integrated terminal: Ctrl+Backtick).

      +
      +

      Jamie: Before we leave Common commands, what is the practical point?

      +

      Alex: The reason Common commands matters is that terminal output is plain text - more predictable than GUI elements for some operations.

      +

      Alex: Treat examples as spoken recipes, not decorations. You may hear something like 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. Read the command, understand what it changes, then run it only when the repository state matches the lesson.

      +

      Jamie: Let's pause on Try It: Clone, Branch, Commit. What should a learner take away from it?

      +

      Alex: Start with Try It: Clone, Branch, Commit: Time: 5 minutes What you need: VS Code with Git configured. The next useful detail is this: Do the complete Git workflow once, start to finish. Think of it like entering a new building: first you find the lobby, then the room, then the door you actually need.

      +

      Alex: First, 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. Then, 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. After that, 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. Finally, stage - Press Ctrl+Shift+G to open Source Control. Navigate to your changed file and press Enter to stage it (or use the + button). Think of it as a rail line: each stop confirms you are still on the right route before the next one.

      +

      Jamie: Before we leave Try It: Clone, Branch, Commit, what is the practical point?

      +

      Alex: First, commit - Tab to the message input, type feat: add new thinking phrase, press Ctrl+Enter. Then, push - Press Ctrl+Shift+P → Git: Push. Treat it like a recipe: do not add the next ingredient until the previous one is actually in the bowl.

      Jamie: What should people carry with them after this?

      Alex: Carry the map. Know what page or tool you are in, know which action you are taking, and know what confirmation should follow. If the confirmation is missing, pause. That pause is not wasted time; it is professional judgment.

      Jamie: That is a better way to say it than just follow the steps.

      -

      Alex: Right. Steps matter, but understanding wins. That is episode 39. Next in the series is episode 40, where we keep building the same contributor muscles.

      +

      Alex: Right. Steps matter, but understanding wins. That is episode 12. Next in the series is episode 13, where we keep building the same contributor muscles.

      -

      Episode 40: GitHub Copilot - Complete Reference

      -

      All Copilot features, chat participants, slash commands, and MCP servers.

      -

      Based on: Appendix K: GitHub Copilot - Complete Reference

      +

      35. Challenge 10: Go Local

      +

      Cloning, local branches, commits, pushing, and understanding local versus remote.

      +

      Practice focus: Day 2 local workflow

      Audio and transcript are being regenerated for this episode.

      -Read Transcript - Episode 40: GitHub Copilot - Complete Reference +Read Transcript - Challenge 10: Go Local

      Transcript

      -

      Alex: Welcome to Git Going with GitHub, episode 40: GitHub Copilot - Complete Reference. I am Alex. Today we are going to make GitHub Copilot - Complete Reference something you can explain, practice, and recover from when the interface surprises you.

      -

      Jamie: And I am Jamie. I will be the voice of the learner who is willing to ask, what is this for, where am I, and how do I know I did it right?

      +

      Alex: Welcome back to Challenge Coach. Today we are taking on Go Local, one careful step at a time.

      +

      Jamie: And I am Jamie. I am listening for the confusing parts: where to start, what to submit, and how to tell whether it worked.

      -

      Alex: The big idea today: All Copilot features, chat participants, slash commands, and MCP servers. We will name the concept, explain why it matters, practice the move, and point out the checks that tell you the work is real.

      -

      Jamie: So the episode should work even if someone has not read the chapter yet.

      -

      Alex: Exactly. The transcript has to stand on its own. It can point toward practice, but it should teach the concept right here in the conversation.

      +

      Alex: In this challenge, the learner is practicing cloning, local branches, commits, pushing, and understanding local versus remote. The point is not to rush. The point is to leave a clear trace of good work.

      +

      Jamie: So we should name what success sounds like before the learner starts clicking or typing.

      +

      Alex: Yes. When the checkpoint is clear, the learner can tell the difference between being stuck and simply not being finished yet.

      -

      Jamie: Okay, set the room for us. What are we walking into?

      -

      Alex: Start with Keyboard Shortcuts, Chat, Screen Reader Workflow, Plugin Ecosystem, and GitHub Agentic Workflows: Quick-reference card for GitHub Copilot in VS Code and the broader agentic ecosystem - plugins, MCP servers, and cloud-based automation. The next useful detail is this: For the Copilot lesson, see Chapter 16: GitHub Copilot.

      -

      Alex: A solid navigation habit is to prove where you are before activating controls. Headings, landmarks, and the address bar are not trivia; they are your map.

      -

      Alex: The next layer is this. Here is the plain-English version of Inline Suggestions (Ghost Text). Word-by-word acceptance (Ctrl+Right Arrow) is recommended for screen reader users - it lets you review the suggestion incrementally before committing to it. Put another way, accessible View workflow for screen reader users: Press Alt+F2 when a suggestion appears to hear the full text without streaming noise, then press Ctrl+/ to insert it directly from the Accessible View without closing the panel first. It is like learning a transit route. The names of the stops matter because they tell you whether you are still going the right direction.

      -

      Jamie: What is the one idea that makes the next few steps less mysterious?

      -

      Alex: This is where Accessibility becomes real: use Accessible View (Alt+F2) every time Copilot responds. That matters in practice: It provides the complete response in a readable pane - no streaming, no live region noise, proper heading structure.

      +

      Jamie: What makes this practice feel low-stakes but still real?

      +

      Alex: Start with Challenge 10: Go Local: What you will do: Clone the learning-room to your computer, create a feature branch, make an edit, commit locally, and push to GitHub.

      +

      Jamie: How would you walk the room through that step by step?

      +

      Alex: Here is the plain-English version of The local workflow. This is the professional Git workflow you will use for the rest of your career. It is like learning a transit route. The names of the stops matter because they tell you whether you are still going the right direction.

      +

      Alex: First, clone the repository to your computer. Then, branch -- create a new branch for your work. After that, edit -- make your changes. Finally, commit -- save a snapshot locally. Treat it like a recipe: do not add the next ingredient until the previous one is actually in the bowl.

      +

      Jamie: What does the learner do first, second, and then after that?

      +

      Alex: First, push -- send your branch to GitHub. It is a checklist, but a meaningful one: every item creates evidence that the next step is safe.

      +

      Jamie: Turn that into a path someone can follow.

      +

      Alex: This is where Instructions (choose your tool) becomes real: autograded: The autograder verifies that at least one commit exists on a non-default branch pushed from a local tool. That matters in practice: Commit message: "." validations: required: true.

      +

      Alex: First, open VS Code. Open the Command Palette (Ctrl+Shift+P / Cmd+Shift+P). Then, type "Git: Clone" and paste the repository URL. After that, after cloning, create a branch: open the Command Palette, type "Git: Create Branch", name it fix/YOUR-USERNAME. Finally, edit any file in the docs/ folder (fix a typo, improve a sentence, add a comment). It is a checklist, but a meaningful one: every item creates evidence that the next step is safe.

      +

      Jamie: What is the ordered workflow?

      +

      Alex: First, in the Source Control panel (Ctrl+Shift+G), stage your change, write a commit message, and commit. Then, push: open the Command Palette, type "Git: Push". After that, file Clone Repository. Paste the URL. Finally, branch New Branch. Name it fix/YOUR-USERNAME. It is like walking a hallway with named doors: read the sign, enter the right room, then confirm where you landed.

      +

      Alex: Treat examples as spoken recipes, not decorations. You may hear something like git clone; cd learning-room; git checkout -b fix/YOUR-USERNAME; edit a file; git add.; git commit -m "fix: improve docs section"; git push -u origin fix/YOUR-USERNAME. Read the command, understand what it changes, then run it only when the repository state matches the lesson.

      -

      Alex: Now bring the learner back to the room. Keep the learner anchored in 2. Chat Participants. Type these in the Copilot Chat input to give Copilot context from a specific source.

      +

      Alex: Now bring the learner back to the room. Keep the learner anchored in Peer simulation check. Compare your local tool choice with the peer-simulation PR notes or with a real buddy. This is the part to say slowly: What was different about the workflow?

      Jamie: What should they understand before typing anything?

      -

      Alex: Start with Example prompts. There is something to understand, something to try, and something that proves the try worked.

      -

      Alex: Treat examples as spoken recipes, not decorations. You may hear something like @workspace find all places where heading hierarchy is documented; @github search community-access/accessibility-agents for issues labeled accessibility; @terminal what did the last command output mean? Read the command, understand what it changes, then run it only when the repository state matches the lesson.

      +

      Alex: Start with Terminal/CLI approach. There is something to understand, something to try, and something that proves the try worked.

      +

      Alex: Treat examples as spoken recipes, not decorations. You may hear something like Clone the repository; git clone https://github.com/the workshop organization/learning-room-your username.git; cd learning-room; Create a branch; git checkout -b fix/local-edit; Make an edit (any text editor works); For example, fix a typo or add content to. Read the command, understand what it changes, then run it only when the repository state matches the lesson.

      Alex: A solid pull request habit is to separate three questions: what changed, why it changed, and what still needs review. That keeps the conversation useful instead of noisy.

      -

      Alex: That matters because of the next idea. Start with 3. Chat Slash Commands: Type / in Copilot Chat to see the available built-in commands. Think of it like entering a new building: first you find the lobby, then the room, then the door you actually need.

      -

      Alex: The useful habit is simple: orient first, act second, verify third. That pause before acting is part of the work.

      +

      Jamie: Give me the sequence, because order matters here.

      +

      Alex: Start with VS Code approach. There is something to understand, something to try, and something that proves the try worked.

      +

      Alex: First, open the Command Palette (Ctrl+Shift+P or Cmd+Shift+P). Then, run "Git: Clone" and paste the repository URL. After that, open the cloned folder. Finally, click the branch name in the bottom-left status bar, create a new branch. Think of it as a rail line: each stop confirms you are still on the right route before the next one.

      +

      Jamie: Let's pause on VS Code approach. What should a learner take away from it?

      +

      Alex: First, edit a file. Then, open the Source Control sidebar (Ctrl+Shift+G). After that, stage changes with the + icon, type a commit message, click the checkmark. Finally, click "Publish Branch" or use the sync button. Treat it like a recipe: do not add the next ingredient until the previous one is actually in the bowl.

      -

      Jamie: There are a lot of tools in play. How do we keep that from feeling like a contest?

      -

      Alex: Here is the plain-English version of Workspace management slash commands. These are Copilot's built-in chat slash commands. Put another way, accessibility Agents adds 28 additional workspace-level slash commands from.github/prompts/ - see Appendix L for the full list.

      -

      Alex: This is where the talk moves from concept to action. This is where 4. Chat Modes becomes real: select the current mode from the dropdown at the bottom of the Chat input area. That matters in practice: The mode selector is in the Chat panel toolbar at the bottom.

      -

      Jamie: What stays the same when the tool changes?

      -

      Alex: Start with Learning Cards: Chat Participants, Commands, and Modes. There is something to understand, something to try, and something that proves the try worked.

      -

      Alex: These are the details that keep the idea from floating away. Type @ in Chat to scope context (@workspace, @terminal, @github) -- the autocomplete list is keyboard-navigable with arrow keys. Type / for slash commands (/explain, /fix, /tests) -- each is announced with its description as you arrow through. The mode selector is at the bottom of the Chat panel toolbar; Tab to it, then Space or Enter to open the dropdown. Chat responses appear in the panel with syntax highlighting -- increase the Chat panel font size via editor.fontSize in settings. The @ and / trigger characters are small but the autocomplete popup that follows is large and themed to your current color scheme. Use Ask mode for reading explanations, Agent mode for controlled multi-file changes and autonomous tasks (Edit mode is being deprecated into Agent mode as of VS Code 1.118).

      +

      Jamie: Let's pause on GitHub Desktop approach. What should a learner take away from it?

      +

      Alex: Start with GitHub Desktop approach. There is something to understand, something to try, and something that proves the try worked.

      +

      Alex: First, file, Clone Repository, paste the URL. Then, current Branch dropdown, New Branch. After that, open the file in your editor and make a change. Finally, return to GitHub Desktop -- it shows the diff. Treat it like a recipe: do not add the next ingredient until the previous one is actually in the bowl.

      +

      Jamie: Before we leave GitHub Desktop approach, what is the practical point?

      +

      Alex: First, write a commit message at the bottom-left, click "Commit". Then, click "Publish branch" to push. It is a checklist, but a meaningful one: every item creates evidence that the next step is safe.

      +

      Alex: This is where the talk moves from concept to action. This is where Verifying success becomes real: after pushing, go to github.com and you should see.

      +

      Alex: The room should hear these as checkpoints. A banner saying "fix/local-edit had recent pushes" with a "Compare & pull request" button. Your branch in the branch dropdown. Your commit in the branch's commit history.

      +

      Alex: The useful habit is simple: orient first, act second, verify third. That pause before acting is part of the work.

      +

      Jamie: What is the one idea that makes the next few steps less mysterious?

      +

      Alex: Keep the learner anchored in What matters. The learning objective is executing the full local workflow: clone, branch, edit, commit, push. This is the part to say slowly: The specific change you made does not matter.

      -

      Alex: Before the learner moves on. The reason 5. Custom Instructions - All Levels matters is that GitHub Copilot supports multiple ways to provide custom instructions. That gives the learner a simple foothold: they differ by scope, priority, trigger mechanism, and which tools recognize them. The interface gets friendlier when it stops being a wall of controls and starts being a set of named places.

      +

      Alex: Before the learner moves on. The reason 1. Why a Mental Model Matters matters is that on Day 1, you edited files on GitHub.com using the web editor. That gives the learner a simple foothold: GitHub handled Git for you behind the scenes -- creating commits, managing branches, and tracking changes. The interface gets friendlier when it stops being a wall of controls and starts being a set of named places.

      Jamie: What would you say to someone who is already bracing for this to be too much?

      -

      Alex: Start with 4A. Always-On Instructions -.github/copilot-instructions.md: What it is: The primary VS Code Copilot instruction file. The next useful detail is this: Content is automatically included in every chat request and inline suggestion context - you never need to invoke it.

      -

      Jamie: How would you walk the room through that step by step?

      -

      Alex: Start with Auto-generate with /init. There is something to understand, something to try, and something that proves the try worked.

      -

      Alex: First, open Copilot Chat. Then, type /init. After that, VS Code analyzes your workspace and generates a tailored copilot-instructions.md. Finally, review and edit the result before committing. Treat it like a recipe: do not add the next ingredient until the previous one is actually in the bowl.

      +

      Alex: Start with 2. The Three Areas: Working Directory, Staging Area, Repository: Git organizes your work into three areas. The next useful detail is this: Understanding these three areas is the single most important concept in this chapter.

      +

      Alex: Hold that next to this. Here is the plain-English version of Working directory. The working directory is the folder on your computer where the files live. Put another way, when you open a project in VS Code, everything you see in the file explorer is the working directory.

      -

      Jamie: How should a learner choose a tool without feeling judged by the choice?

      -

      Alex: This is where 4B. Always-On Instructions - AGENTS.md (Multi-Tool / Monorepo) becomes real: what it is: An open standard instruction file recognized by multiple AI tools - GitHub Copilot, Claude Code, Gemini CLI, and others. That matters in practice: Use this instead of copilot-instructions.md when you want one instruction file that works across all AI coding assistants.

      -

      Alex: That connects to another useful point. Keep the learner anchored in 4C. Always-On Instructions - CLAUDE.md (Cross-Tool Compatibility). What it is: Instructions file originally from Claude Code that VS Code Copilot also recognizes. This is the part to say slowly: When to use: Mixed AI tool environments where Claude Code and VS Code Copilot are both used. A good GitHub workflow is like a well-run meeting: everyone knows the topic, the next action, and who has the floor.

      -

      Jamie: Where do you want a learner to place their attention here?

      -

      Alex: The reason Supported locations matters is that enable/disable: Set chat.useClaudeMdFile: true (default: on). That gives the learner a simple foothold: claude Rules format (for.claude/rules/ and /.claude/rules/).

      +

      Jamie: Okay, set the room for us. What are we walking into?

      +

      Alex: This is where Staging area (also called the index) becomes real: the staging area is a holding zone. That matters in practice: When you are happy with a change in the working directory, you add it to the staging area.

      +

      Alex: That connects to another useful point. Keep the learner anchored in Repository (the.git folder). The repository is Git's permanent record. This is the part to say slowly: 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. A good GitHub workflow is like a well-run meeting: everyone knows the topic, the next action, and who has the floor.

      +

      Alex: A solid Git habit is to know which branch you are on, what changed, and what confirmation you expect before you run the next command.

      +

      Jamie: Let's pause on How the three areas connect. What should a learner take away from it?

      +

      Alex: The reason How the three areas connect matters is that many visual Git tutorials use diagrams with arrows to show this flow. That gives the learner a simple foothold: the text description above and the three-step sequence are the same information without requiring a visual representation.

      +

      Alex: First, edit files in the working directory. Then, stage the changes you want to keep (add to the staging area). After that, commit the staged changes (save to the repository). The rhythm is simple: orient, act, verify, then continue.

      -

      Alex: Here is the practical turn. Start with 4D. Conditional / Scoped Instructions -.instructions.md: What it is: Instructions that apply only when specific file types or folders are involved in the chat. The next useful detail is this: More targeted than always-on instructions.

      +

      Alex: Here is the practical turn. Start with An analogy: packing a box: Think of it like packing a box to mail. The next useful detail is this: 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).

      +

      Alex: On the ground, that means a few things. 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.

      Jamie: Give me the version that sounds like an instructor, not a manual.

      -

      Alex: Start with Create an instructions file. There is something to understand, something to try, and something that proves the try worked.

      -

      Alex: Here is what that changes in practice. Ctrl+Shift+P → "Chat: New Instructions File" → choose scope (Workspace or User). Or create the file manually in.github/instructions/.

      -

      Alex: Keep the thread going. This is where 4E. Organization-Level Instructions (GitHub Enterprise and Teams) becomes real: what it is: Organization administrators define custom instructions that apply to all repositories in the organization. That matters in practice: Every team member automatically gets these instructions added to their Copilot context. The workshop is closer to rehearsal than lecture. You hear the move, try the move, and then check what changed.

      +

      Alex: Start with Learning Cards: The Three Areas. There is something to understand, something to try, and something that proves the try worked.

      +

      Alex: Here is what that changes in practice. 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. 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.

      +

      Alex: Keep the thread going. This is where 3. What Is a Commit? becomes real: a commit is a snapshot of your project at a specific moment in time. That matters in practice: It is not a diff (a list of changes). The workshop is closer to rehearsal than lecture. You hear the move, try the move, and then check what changed.

      Jamie: If I am listening before the workshop starts, what should settle in my mind first?

      -

      Alex: Keep the learner anchored in Requirements. Use for: Organization-wide coding standards, security policies, legal disclaimers (open source license obligations), toolchain conventions.

      -

      Alex: That becomes easier when you listen for these cues. GitHub Enterprise or Teams plan with Copilot enabled. Admin configures instructions in organization settings on GitHub.com. Each user must enable discovery in VS Code.

      -

      Alex: Another way to ground it. The reason 4F. Settings-Based Instructions (Deprecated - Use Files Instead) matters is that these settings-based instructions are deprecated and may be removed in a future VS Code release. That gives the learner a simple foothold: for new work, use copilot-instructions.md or.instructions.md files.

      -

      Jamie: How should someone choose between those options?

      -

      Alex: Start with 4G. Comparison - When to Use Each Approach. There is something to understand, something to try, and something that proves the try worked.

      -

      Alex: Use the comparison to make a decision, not to recite a table. The main contrasts are: Approach means Always-on? means Multi-tool? means Best. copilot-instructions.md means Workspace means VS Code only means Primary project instructions. AGENTS.md means Workspace + monorepo means All AI tools means Multi-tool teams or large monorepos.

      -
      -

      Alex: This is the part worth saying out loud. Start with Learning Cards: Custom Instructions. There is something to understand, something to try, and something that proves the try worked.

      -

      Alex: The practical anchors are these. The three-level scope hierarchy (Organization, Workspace, User) means instructions can come from multiple places -- use Chat Diagnostics (gear icon in Chat header) to list every loaded instruction file and its source.github/copilot-instructions.md is always-on and requires no frontmatter -- just write plain Markdown; screen readers read the source file like any other Markdown document.instructions.md files use YAML frontmatter with applyTo globs -- the frontmatter is the first few lines between --- delimiters; arrow through carefully to verify syntax. The Diagnostics panel (Chat gear, then Diagnostics) lists loaded files in a scrollable pane -- increase font size in VS Code settings if the file paths are hard to read. YAML frontmatter is indentation-sensitive -- enable VS Code's indentation guides (editor.guides.indentation) and use a high-contrast theme so the guide lines are visible. The /init command auto-generates copilot-instructions.md from your workspace -- review the generated file in your editor at your preferred zoom before committing.

      -

      Jamie: Let's pause on 6. Accessible View Workflow. What should a learner take away from it?

      -

      Alex: This is where 6. Accessible View Workflow becomes real: Copilot Chat responses stream in token by token, which can fragment screen reader announcements. That matters in practice: Accessible View (Alt+F2) gives you a complete, static, properly structured version of the response.

      -

      Jamie: What should happen before anyone copies and runs it?

      -

      Alex: Keep the learner anchored in Recommended Workflow - Every Copilot Interaction. VS Code December 2025: The Accessible View now streams dynamically. This is the part to say slowly: You can open it immediately after sending a prompt and follow the response as it arrives - no need to wait for the response to finish before pressing Alt+F2.

      -

      Alex: Treat examples as spoken recipes, not decorations. You may hear something like Open Copilot Chat: Ctrl+Shift+I; 2. Type your prompt; 3. Press Ctrl+Enter to send; 4. Press Alt+F2 to open Accessible View (open immediately - no need to wait); 5. Follow as the response streams in the Accessible View in real-time; 6. Read or re-read any part. Read the command, understand what it changes, then run it only when the repository state matches the lesson.

      +

      Alex: Keep the learner anchored in Commit IDs (hashes). Every commit gets a unique identifier -- a 40-character string called a SHA hash. This is the part to say slowly: In practice, you usually see only the first 7 characters: a1b2c3d.

      +

      Alex: Another way to ground it. The reason Commits are permanent (mostly) matters is that once a commit is made, it is part of the repository's history. That gives the learner a simple foothold: you can make new commits that undo the changes, but the original commit still exists in the timeline.

      +

      Jamie: Where do you want a learner to place their attention here?

      +

      Alex: Start with Learning Cards: Commits. There is something to understand, something to try, and something that proves the try worked.

      +

      Alex: A few details make that real. 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. 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.

      -

      Jamie: Let's pause on NVDA / JAWS. What should a learner take away from it?

      -

      Alex: Start with NVDA / JAWS. There is something to understand, something to try, and something that proves the try worked.

      -

      Alex: The parts worth keeping in working memory are these. Up/Down Arrow - read line by line. Ctrl+Home - jump to start. H - navigate by headings (if response has sections). Escape - close Accessible View, return to Chat.

      -

      Alex: Hold that next to this. Start with VoiceOver. There is something to understand, something to try, and something that proves the try worked.

      -

      Alex: On the ground, that means a few things. VO+Shift+Down - interact with the Accessible View content. Down Arrow - read line by line. VO+Escape - stop interacting. Escape - close Accessible View.

      -

      Jamie: What is the safe way to learn from that example?

      -

      Alex: Here is the plain-English version of Accessible View for Inline Suggestions. When a multi-line ghost text suggestion appears in the editor. Put another way, this is especially important for multi-line suggestions where ghost text is hard to review incrementally.

      -

      Alex: Treat examples as spoken recipes, not decorations. You may hear something like Do not accept immediately; 2. Press Alt+F2; 3. Accessible View shows: "Suggestion: [full text]"; 4. Read the complete suggestion at your own pace; 5. Press Escape to close; 6. Press Tab to accept, or Escape to reject. Read the command, understand what it changes, then run it only when the repository state matches the lesson.

      +

      Alex: This is the part worth saying out loud. Here is the plain-English version of 4. What Is a Branch? See also: Chapter 14: Git in Practice shows how to create and switch branches hands-on in VS Code. Put another way, a branch is a name that points to a specific commit. It is like learning a transit route. The names of the stops matter because they tell you whether you are still going the right direction.

      +

      Jamie: Let's pause on The default branch: main. What should a learner take away from it?

      +

      Alex: This is where The default branch: main becomes real: every repository has a default branch, usually called main. That matters in practice: 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.

      +

      Alex: The next layer is this. Keep the learner anchored in Creating a branch. When you create a new branch, Git creates a new pointer that starts at the same commit you are currently on. This is the part to say slowly: Both branches point to the same commit.

      -

      Alex: Keep the teaching thread moving. Start with Accessible View for Code Blocks. There is something to understand, something to try, and something that proves the try worked.

      -

      Alex: The room should hear these as checkpoints. Code blocks appear inside elements in Accessible View. Screen readers announce "code block" or "pre-formatted text" at the start. Each line is on its own line (not run together). Indentation is preserved.

      -

      Jamie: Let's pause on Learning Cards: Accessible View Workflow. What should a learner take away from it?

      -

      Alex: Start with Learning Cards: Accessible View Workflow. There is something to understand, something to try, and something that proves the try worked.

      -

      Alex: A few details make that real. Press Alt+F2 immediately after sending a prompt -- Accessible View now streams dynamically so you can follow along in real time. Navigate Chat responses with Up/Down Arrow; headings, code blocks, and lists are structurally intact in the view. For inline suggestions, press Alt+F2 to read the full ghost text, then Ctrl+/ to insert it directly from the Accessible View. Accessible View renders Chat responses as a static, scrollable pane -- easier to read at high zoom than the streaming Chat panel. Code blocks in Accessible View preserve indentation and syntax -- pair with a high-contrast theme for maximum readability. Ctrl+Home jumps to the start of the response; Ctrl+End to the end -- useful for long multi-section outputs.

      -

      Alex: Keep the teaching thread moving. The reason 7. Configuration Scope Reference matters is that every Copilot customization file lives at one of three scopes. That gives the learner a simple foothold: VS Code combines all matching files from all scopes - it is additive, not winner-takes-all. The interface gets friendlier when it stops being a wall of controls and starts being a set of named places.

      +

      Jamie: Let's pause on Making commits on a branch. What should a learner take away from it?

      +

      Alex: The reason Making commits on a branch matters is that when you make a new commit while on the fix/typo branch, the fix/typo pointer moves forward to the new commit. That gives the learner a simple foothold: the main pointer stays where it was.

      +

      Alex: That matters because of the next idea. Start with HEAD: which branch are you on?: Git uses a special pointer called HEAD to track which branch you are currently working on. The next useful detail is this: When you switch branches (checkout), Git moves HEAD to point to the new branch and updates the files in your working directory to match. Think of it like entering a new building: first you find the lobby, then the room, then the door you actually need.

      +

      Jamie: Let's pause on Learning Cards: Branches. What should a learner take away from it?

      +

      Alex: Start with Learning Cards: Branches. There is something to understand, something to try, and something that proves the try worked.

      +

      Alex: These are the details that keep the idea from floating away. 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. 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.

      -

      Jamie: Let's pause on Workspace (Repository) - Team-Shared. What should a learner take away from it?

      -

      Alex: Start with Workspace (Repository) - Team-Shared: Files committed to your repository. The next useful detail is this: Everyone who clones the repo gets them.

      -

      Alex: Keep the teaching thread moving. Here is the plain-English version of User / Personal - Follows You Across Workspaces. Files in your VS Code profile folder. Put another way, available in every workspace you open.

      -

      Jamie: Let's pause on Organization - GitHub-Configured (Enterprise/Teams). What should a learner take away from it?

      -

      Alex: This is where Organization - GitHub-Configured (Enterprise/Teams) becomes real: configured by administrators in GitHub organization settings. That matters in practice: Automatically applied to all organization members.

      -

      Alex: That shows up in the workshop in a few specific ways. Enable discovery: github.copilot.chat.organizationInstructions.enabled: true. Lowest priority - workspace and user instructions override when there is a conflict.

      +

      Alex: Keep the teaching thread moving. This is where 5. Local vs Remote becomes real: see also: Appendix D: Git Authentication covers how to set up credentials so push and pull work without password prompts. That matters in practice: So far, we have talked about one repository.

      +

      Jamie: Let's pause on The remote repository. What should a learner take away from it?

      +

      Alex: Keep the learner anchored in The remote repository. The remote repository is the one on GitHub.com. This is the part to say slowly: When you see a repository URL like github.com/Community-Access/git-going-with-github, that is the remote.

      +

      Alex: Keep the teaching thread moving. The reason The local repository matters is that the local repository is the copy on your computer. That gives the learner a simple foothold: when you run git clone, Git downloads the entire repository -- all files, all branches, all history -- to your machine. The interface gets friendlier when it stops being a wall of controls and starts being a set of named places.

      -

      Alex: Keep the teaching thread moving. Keep the learner anchored in 8. Instruction Priority and Conflicts. When multiple instruction sources give conflicting guidance, VS Code uses this priority order. This is the part to say slowly: This priority applies to conflicts. A good GitHub workflow is like a well-run meeting: everyone knows the topic, the next action, and who has the floor.

      -

      Jamie: Let's pause on How Instructions Are Combined. What should a learner take away from it?

      -

      Alex: The reason How Instructions Are Combined matters is that result: Copilot follows TypeScript strict mode (from workspace), British English (from org), AND the Z-spelling override (from user, which overrides the org instruction on that specific point).

      -

      Alex: For a learner, the useful signals are these. Organization: "Use British English spellings". Workspace: "Use TypeScript strict mode". User: "Use British English spellings - but use Z spellings (organize, not organise) for technical terms".

      -

      Alex: Keep the teaching thread moving. Start with Priority Within the Same Scope: Within a single scope (e.g., workspace), all matching instructions files are combined with no inherent priority. The next useful detail is this: If two workspace-level.instructions.md files contradict each other, the behavior is undefined - avoid conflicting workspace instructions.

      +

      Jamie: Let's pause on The two-copy model. What should a learner take away from it?

      +

      Alex: Start with The two-copy model: The text diagram above shows two boxes side by side connected by arrows. The next useful detail is this: The left box is labeled "Your computer (local)" and contains working directory, staging area, and repository.

      +

      Alex: Keep the teaching thread moving. Start with Learning Cards: Local vs Remote. There is something to understand, something to try, and something that proves the try worked.

      +

      Alex: The practical anchors are these. 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. 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.

      +

      Jamie: Let's pause on 6. Push, Pull, and Fetch. What should a learner take away from it?

      +

      Alex: This is where 6. Push, Pull, and Fetch becomes real: these three operations keep your local and remote repositories synchronized.

      -

      Jamie: Let's pause on Create any new customization file. What should a learner take away from it?

      -

      Alex: Here is the plain-English version of Create any new customization file. Ctrl+Shift+P → "Chat: New Instructions File" (or "New Prompt File", "New Agent File").

      -

      Alex: Keep the teaching thread moving. This is where 10. VS Code Settings Reference becomes real: all Copilot customization-related settings. That matters in practice: Set in VS Code Settings (Ctrl+,) or settings.json. The workshop is closer to rehearsal than lecture. You hear the move, try the move, and then check what changed.

      -

      Jamie: Let's pause on Deprecated Task-Specific Instructions. What should a learner take away from it?

      -

      Alex: Keep the learner anchored in Deprecated Task-Specific Instructions. Prefer file-based instructions over these settings for new work. This is the part to say slowly: Each accepts an array with items: { "text": "." } (inline) or { "file": "relative/path" } (from file).

      +

      Jamie: How do you keep commands from becoming magic words?

      +

      Alex: Keep the learner anchored in Push: share your work. git push sends your local commits to the remote. This is the part to say slowly: After pushing, anyone who looks at the repository on GitHub.com will see your changes. A good GitHub workflow is like a well-run meeting: everyone knows the topic, the next action, and who has the floor.

      +

      Alex: Treat examples as spoken recipes, not decorations. You may hear something like git push origin fix/typo. git push -u origin fix/typo. Read the command, understand what it changes, then run it only when the repository state matches the lesson.

      +

      Jamie: What is the safe way to learn from that example?

      +

      Alex: The reason Pull: get other people's work matters is that git pull downloads new commits from the remote and immediately merges them into your current branch. That gives the learner a simple foothold: this is how you get changes that other people (or you on another computer) have pushed.

      +

      Alex: Treat examples as spoken recipes, not decorations. You may hear something like git pull origin main. Read the command, understand what it changes, then run it only when the repository state matches the lesson.

      +

      Jamie: What should happen before anyone copies and runs it?

      +

      Alex: Start with Fetch: check for updates without merging: git fetch downloads new commits from the remote but does not change your working directory or current branch. The next useful detail is this: It just updates your local knowledge of what the remote looks like.

      +

      Alex: Treat examples as spoken recipes, not decorations. You may hear something like git fetch origin. git log main.origin/main --oneline. Read the command, understand what it changes, then run it only when the repository state matches the lesson.

      -

      Jamie: What is the ordered workflow?

      -

      Alex: The reason Settings Sync matters is that to sync your personal prompts, instructions, and agents across devices. That gives the learner a simple foothold: your personal.instructions.md,.agent.md, and.prompt.md files will sync to all signed-in VS Code instances.

      -

      Alex: First, ctrl+Shift+P → "Settings Sync: Turn On". Then, ctrl+Shift+P → "Settings Sync: Configure". After that, check "Prompts and Instructions". The rhythm is simple: orient, act, verify, then continue.

      -

      Jamie: Give me the sequence, because order matters here.

      -

      Alex: Start with View All Loaded Customizations: To see which instruction files, agents, prompts, and skills are currently loaded - and check for errors.

      -

      Alex: The practical takeaway is this. All agents found and whether they loaded successfully. All prompt/instruction files and their source (workspace vs user vs organization). All skills and their discovery status. Any parse errors or invalid frontmatter.

      -

      Alex: First, configure Chat Gear: Click the gear () icon in the Copilot Chat header → "Diagnostics". Then, right-click method: Right-click in the Chat view → "Diagnostics". Think of it as a rail line: each stop confirms you are still on the right route before the next one.

      -

      Jamie: What does the learner do first, second, and then after that?

      -

      Alex: Start with copilot-instructions.md not being followed. There is something to understand, something to try, and something that proves the try worked.

      -

      Alex: First, confirm the file is at exactly.github/copilot-instructions.md (relative to workspace root). Then, check the file is plain Markdown with no frontmatter syntax errors. After that, open Diagnostics to confirm it appears in the loaded files list. Finally, some instructions work better with specific phrasing; use imperative mood ("Always use."). Treat it like a recipe: do not add the next ingredient until the previous one is actually in the bowl.

      +

      Jamie: Let's pause on 7. Why Merge Conflicts Happen. What should a learner take away from it?

      +

      Alex: Here is the plain-English version of 7. Why Merge Conflicts Happen. A merge conflict happens when Git cannot automatically combine two sets of changes.

      +

      Alex: Keep the teaching thread moving. This is where When conflicts occur becomes real: conflicts happen when two branches modify the same lines in the same file. That matters in practice: Git knows how to merge changes to different files, and even different parts of the same file. The workshop is closer to rehearsal than lecture. You hear the move, try the move, and then check what changed.

      +

      Jamie: Let's pause on What a conflict looks like. What should a learner take away from it?

      +

      Alex: Keep the learner anchored in What a conflict looks like. When a conflict occurs, Git marks the conflicting section in the file with special markers.

      -

      Jamie: Turn that into a path someone can follow.

      -

      Alex: Start with.instructions.md file not loading automatically. There is something to understand, something to try, and something that proves the try worked.

      -

      Alex: First, verify chat.includeApplyingInstructions is not set to false. Then, check the applyTo glob - test with " " temporarily to confirm the file loads at all. After that, confirm the file is in.github/instructions/ or a folder listed in chat.instructionsFilesLocations. Finally, file extension must be.instructions.md exactly - not.md, not.instruction.md. It is a checklist, but a meaningful one: every item creates evidence that the next step is safe.

      -

      Jamie: Let's pause on Custom agent (@agent-name) not appearing. What should a learner take away from it?

      -

      Alex: Start with Custom agent (@agent-name) not appearing. There is something to understand, something to try, and something that proves the try worked.

      -

      Alex: First, file must be named.agent.md and placed in.github/agents/. Then, check YAML frontmatter for syntax errors - use a YAML validator. After that, confirm user-invocable is not set to false (which hides it from the picker). Finally, run Ctrl+Shift+P → "Reload Window" after any changes to agent files. It is like walking a hallway with named doors: read the sign, enter the right room, then confirm where you landed.

      -

      Jamie: Let's pause on Slash command (/command) not appearing. What should a learner take away from it?

      -

      Alex: Start with Slash command (/command) not appearing. There is something to understand, something to try, and something that proves the try worked.

      -

      Alex: First, file must be at.github/prompts/.prompt.md. Then, extension must be.prompt.md exactly. After that, reload VS Code: Ctrl+Shift+P → "Reload Window". The rhythm is simple: orient, act, verify, then continue.

      +

      Jamie: Let's pause on How to resolve a conflict. What should a learner take away from it?

      +

      Alex: The reason How to resolve a conflict matters is that the Day 1 connection: In Chapter 7, you resolved a merge conflict on GitHub.com using the web editor. That gives the learner a simple foothold: 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.

      +

      Alex: First, open the file with the conflict markers. Then, read both versions and decide which text to keep (or write a new version that combines both). After that, delete the conflict markers ( ). Finally, save the file. The rhythm is simple: orient, act, verify, then continue.

      +

      Jamie: Before we leave How to resolve a conflict, what is the practical point?

      +

      Alex: First, stage and commit the resolved file. Think of it as a rail line: each stop confirms you are still on the right route before the next one.

      +

      Jamie: Let's pause on Why conflicts are normal. What should a learner take away from it?

      +

      Alex: Start with Why conflicts are normal: They happen in every project where more than one person works at the same time. The next useful detail is this: The fact that Git stops and asks is a safety feature -- it prevents data loss by never silently choosing one version over another.

      +

      Alex: Keep the teaching thread moving. Start with Learning Cards: Merge Conflicts. There is something to understand, something to try, and something that proves the try worked.

      +

      Alex: That shows up in the workshop in a few specific ways. 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. 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.

      -

      Jamie: Let's pause on Instructions from different files conflicting. What should a learner take away from it?

      -

      Alex: Start with Instructions from different files conflicting. There is something to understand, something to try, and something that proves the try worked.

      -

      Alex: First, open Diagnostics to see all loaded instruction files. Then, remove or edit conflicting instructions - they are not automatically de-duplicated. After that, user-level instructions override workspace instructions for the same topic. Think of it as a rail line: each stop confirms you are still on the right route before the next one.

      -

      Jamie: Let's pause on chat.instructionsFilesLocations not working. What should a learner take away from it?

      -

      Alex: Start with chat.instructionsFilesLocations not working. There is something to understand, something to try, and something that proves the try worked.

      -

      Alex: The practical takeaway is this. Path must be a folder path, not a file path. Use forward slashes or escaped backslashes. Relative paths are relative to the workspace root.

      -

      Alex: Keep the teaching thread moving. This is where 12. Screen Reader Workflow - Official Guide becomes real: source: accessibility.github.com/documentation/guide/github-copilot-vsc/ Contributors: @mlama007, zersiax Community: GitHub Accessibility Discussions.

      +

      Jamie: Let's pause on 8. The Git Timeline. What should a learner take away from it?

      +

      Alex: This is where 8. The Git Timeline becomes real: every commit has a parent pointer (except the very first commit). That matters in practice: This creates a chain -- a timeline of the project's history.

      +

      Alex: Keep the teaching thread moving. Keep the learner anchored in 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. This is the part to say slowly: 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.

      +

      Jamie: Let's pause on Branching creates parallel timelines. What should a learner take away from it?

      +

      Alex: The reason Branching creates parallel timelines matters is that when two branches diverge (both have commits that the other does not), the timeline splits into two parallel paths. That gives the learner a simple foothold: both branches share commits A and B (their common history).

      -

      Jamie: Let's pause on Prerequisites. What should a learner take away from it?

      -

      Alex: Start with Prerequisites. There is something to understand, something to try, and something that proves the try worked.

      -

      Alex: The practical takeaway is this. VS Code with GitHub Copilot Chat extension installed. A GitHub account with Copilot access (Free tier or paid). A screen reader (NVDA recommended for this guide).

      -

      Jamie: Let's pause on Step 1: Enable VS Code Screen Reader Mode. What should a learner take away from it?

      -

      Alex: The reason Step 1: Enable VS Code Screen Reader Mode matters is that when Screen Reader Mode is on, VS Code changes how it announces suggestions (full text instead of streaming), adjusts live regions, and enables accessible navigation patterns throughout the editor. The interface gets friendlier when it stops being a wall of controls and starts being a set of named places.

      -

      Alex: First, press Shift+Alt+F1 to toggle Screen Reader Accessibility Mode. Then, or use Command Palette: Ctrl+Shift+P → "Toggle Screen Reader Accessibility Mode". After that, VS Code announces: "Screen Reader Accessibility Mode enabled". The rhythm is simple: orient, act, verify, then continue.

      -

      Jamie: Let's pause on Step 2: Configure Accessibility Signals (Optional but Recommended). What should a learner take away from it?

      -

      Alex: Start with Step 2: Configure Accessibility Signals (Optional but Recommended): Recommended JSON config for Copilot accessibility signals.

      -

      Alex: First, open Settings: Ctrl+,. Then, search "accessibility signals". After that, enable the Copilot-specific signals. Think of it as a rail line: each stop confirms you are still on the right route before the next one.

      +

      Alex: Keep the teaching thread moving. Start with 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 next useful detail is this: The two timelines join back together. Think of it like entering a new building: first you find the lobby, then the room, then the door you actually need.

      +

      Jamie: Let's pause on 9. Putting It All Together. What should a learner take away from it?

      +

      Alex: Here is the plain-English version of 9. Putting It All Together. Here is the complete workflow that you will practice in Chapter 14, translated through the mental model. Put another way, everything in this table maps directly to the three areas (Section 2), the two copies (Section 5), and the timeline (Section 8).

      +

      Alex: Keep the teaching thread moving. This is where Quick mental model checklist becomes real: before running a Git command, ask yourself. That matters in practice: If you can answer these four questions, you can troubleshoot almost any Git situation.

      +

      Alex: That becomes easier when you listen for these cues. 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?

      -

      Alex: Keep the teaching thread moving. Here is the plain-English version of Step 3: Official Shortcut Table (from accessibility.github.com). This is the complete table of Copilot screen reader shortcuts as published by the GitHub Accessibility team.

      -

      Jamie: How do you keep commands from becoming magic words?

      -

      Alex: This is where The screen reader-optimized workflow for every inline suggestion becomes real: this workflow avoids the streaming announcement problem (where suggestions are read out in fragments as tokens arrive) and gives you full, uninterrupted access to the suggestion text before committing.

      -

      Alex: Treat examples as spoken recipes, not decorations. You may hear something like Type your code or documentation; 2. Copilot generates a suggestion (audio cue sounds if enabled); 3. DO NOT press Tab immediately; 4. Press Alt+F2 - Accessible View opens with the full suggestion text; 5. Read the suggestion at your own pace with Arrow keys. Read the command, understand what it changes, then run it only when the repository state matches the lesson.

      -

      Jamie: Let's pause on Step 5: Recommended Workflow for Chat Responses. What should a learner take away from it?

      -

      Alex: Start with Step 5: Recommended Workflow for Chat Responses. There is something to understand, something to try, and something that proves the try worked.

      -

      Alex: Treat examples as spoken recipes, not decorations. You may hear something like Open Chat: Ctrl+Shift+I; 2. Type your prompt, press Ctrl+Enter to send; 3. Press Alt+F2 - Accessible View opens immediately; the response streams live into it; 4. Navigate with Arrow keys - no streaming noise, follow along in real-time; 5. Headings, code. Read the command, understand what it changes, then run it only when the repository state matches the lesson.

      +

      Jamie: What do you want them to do when the plan breaks?

      +

      Alex: Keep the learner anchored in 10. If You Get Stuck. Next: Chapter 14: Git in Practice Back: Chapter 12: VS Code Accessibility Related appendices: Appendix E: Advanced Git Appendix D: Git Authentication.

      +

      Alex: Keep the teaching thread moving. The reason Managing Repositories, Branches, and Changes Accessibly matters is that 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. That gives the learner a simple foothold: prerequisites: VS Code Setup & Accessibility Basics, Working with Pull Requests, Merge Conflicts Mac keyboard shortcuts: Throughout this chapter, all Ctrl+ shortcuts use Cmd+ on Mac, and Alt+ shortcuts use Option+. The interface gets friendlier when it stops being a wall of controls and starts being a set of named places.

      +

      Jamie: How should they picture the shape of the workshop?

      +

      Alex: Start with Workshop Recommendation (Chapter 14 / Challenge 10): Chapter 14 is the first local Git workflow chapter with hands-on repository management. The next useful detail is this: It supports Challenge 10: Go Local.

      +

      Alex: For a learner, the useful signals are these. There are 3. Each challenge should take under 10 minutes each. The evidence is PR metadata, branch names, and committed changes. The pattern is clone, branch, edit, commit, push, PR.

      -

      Jamie: Let's pause on Reading the Suggestions Panel (Ctrl+Enter). What should a learner take away from it?

      -

      Alex: The reason Reading the Suggestions Panel (Ctrl+Enter) matters is that pressing Ctrl+Enter opens a Suggestions Panel - a separate editor tab that shows up to 10 alternative suggestions simultaneously. That gives the learner a simple foothold: this is useful when the default suggestion isn't quite right and you want to compare options.

      -

      Alex: Treat examples as spoken recipes, not decorations. You may hear something like Ctrl+Enter - opens "GitHub Copilot" editor tab; 2. Screen Reader Mode is active: navigate with Browse Mode; 3. H key to navigate headings (each suggestion may be under a heading); 4. Press Alt+F2 on a focused suggestion to read it in Accessible View; 5. Tab to. Read the command, understand what it changes, then run it only when the repository state matches the lesson.

      -

      Alex: Keep the teaching thread moving. Start with Learning Cards: Screen Reader Copilot Workflow. There is something to understand, something to try, and something that proves the try worked.

      -

      Alex: The practical takeaway is this. The golden rule: never accept a suggestion with Tab before reviewing it -- press Alt+F2 first, read it, then Ctrl+/ to insert. Enable the four Copilot audio signals (inline suggestion, request sent, response pending, response received) for non-verbal status awareness. Ctrl+Enter opens a Suggestions Panel with up to 10 alternatives -- navigate with H for headings, then Tab to the Accept button. Inline ghost text is typically rendered in a muted color -- if hard to see, rely on the lineHasInlineSuggestion audio signal instead. The Suggestions Panel (Ctrl+Enter) shows alternatives in a full editor tab at your current font size and theme. Chat responses are easier to read in Accessible View than in the streaming panel, especially at high zoom.

      -

      Jamie: Let's pause on 13. awesome-copilot - Plugin Ecosystem. What should a learner take away from it?

      -

      Alex: Here is the plain-English version of 13. awesome-copilot - Plugin Ecosystem. awesome-copilot is a GitHub repository (github/awesome-copilot) - not a VS Code Marketplace extension. Put another way, it is GitHub's curated ecosystem of Copilot plugins, prompts, instructions, agents, skills, and hooks that can be shared and discovered by anyone.

      +

      Jamie: Let's pause on Challenge 10 Practice Set. What should a learner take away from it?

      +

      Alex: Start with Challenge 10 Practice Set. There is something to understand, something to try, and something that proves the try worked.

      +

      Alex: First, clone your Learning Room repository - clone your private Learning Room repo to your local machine using VS Code. Then, 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. After that, 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. Treat it like a recipe: do not add the next ingredient until the previous one is actually in the bowl.

      +

      Jamie: Let's pause on Practice 10.1 Step-by-Step: Clone Your Learning Room Repository. What should a learner take away from it?

      +

      Alex: This is where Practice 10.1 Step-by-Step: Clone Your Learning Room Repository becomes real: get a local copy of your Learning Room repository on your machine using VS Code. That matters in practice: VS Code desktop (or github.dev if you cannot install desktop VS Code).

      +

      Alex: First, open VS Code. If no folder is open, you should see the Welcome tab. Then, open the Command Palette: Ctrl+Shift+P (Mac: Cmd+Shift+P). After that, type git clone and select Git: Clone. Finally, VS Code asks for a repository URL. Paste your Learning Room repo URL (it looks like https://github.com/the workshop organization/learning-room-your username.git). You can copy this from the green Code button on your repo's GitHub page. It is a checklist, but a meaningful one: every item creates evidence that the next step is safe.

      +

      Jamie: Before we leave Practice 10.1 Step-by-Step: Clone Your Learning Room Repository, what is the practical point?

      +

      Alex: First, press Enter. Then, 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. After that, VS Code clones the repository. When it finishes, a notification appears asking "Would you like to open the cloned repository?" Activate Open. Finally, 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. It is like walking a hallway with named doors: read the sign, enter the right room, then confirm where you landed.

      +

      Jamie: Let's pause on Practice 10.2 Step-by-Step: Create a Branch and Commit. What should a learner take away from it?

      +

      Alex: Keep the learner anchored in Practice 10.2 Step-by-Step: Create a Branch and Commit. See also: Chapter 13: How Git Works explains the three areas (working directory, staging, repository) that make commits meaningful. This is the part to say slowly: Check out (or create) a properly named branch, edit a file, stage the change, and commit with a clear message. A good GitHub workflow is like a well-run meeting: everyone knows the topic, the next action, and who has the floor.

      +

      Alex: First, open the Command Palette: Ctrl+Shift+P (Mac: Cmd+Shift+P). Then, 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/your username. If the branch does not exist yet, type git create branch and select Git: Create Branch. After that, 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. Finally, 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). It is like walking a hallway with named doors: read the sign, enter the right room, then confirm where you landed.

      +

      Jamie: Before we leave Practice 10.2 Step-by-Step: Create a Branch and Commit, what is the practical point?

      +

      Alex: First, 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). Then, 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.". After that, 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.". Finally, 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. The rhythm is simple: orient, act, verify, then continue.

      -

      Alex: Keep the teaching thread moving. This is where Repository Structure becomes real: lLM discovery: https://github.github.io/awesome-copilot/llms.txt - a machine-readable index of all available resources. The workshop is closer to rehearsal than lecture. You hear the move, try the move, and then check what changed.

      -

      Jamie: Let's pause on The /plugin Command - Browse and Install from Chat. What should a learner take away from it?

      -

      Alex: Keep the learner anchored in The /plugin Command - Browse and Install from Chat. The easiest way to explore awesome-copilot from VS Code.

      -

      Alex: First, open Copilot Chat (Ctrl+Shift+I). Then, type /plugin and press Enter. After that, Copilot Chat opens an interactive plugin marketplace browser. Finally, browse plugins by category, read descriptions, and install with a single command. It is like walking a hallway with named doors: read the sign, enter the right room, then confirm where you landed.

      -

      Jamie: Let's pause on CLI Plugin Installation. What should a learner take away from it?

      -

      Alex: The reason CLI Plugin Installation matters is that from any terminal with GitHub CLI (gh) installed.

      -

      Alex: Treat examples as spoken recipes, not decorations. You may hear something like Browse the marketplace; gh copilot plugin marketplace list; Add the awesome-copilot collection; gh copilot plugin marketplace add github/awesome-copilot; Install a specific plugin; gh copilot plugin install @awesome-copilot/accessibility-toolkit; List what you. Read the command, understand what it changes, then run it only when the repository state matches the lesson.

      +

      Jamie: Let's pause on Practice 10.3 Step-by-Step: Push and Open a Linked PR. What should a learner take away from it?

      +

      Alex: The reason Practice 10.3 Step-by-Step: Push and Open a Linked PR matters is that push your branch to GitHub and open a PR in your Learning Room repo that references your challenge issue. That gives the learner a simple foothold: VS Code (for the push) and GitHub.com (for the PR).

      +

      Alex: First, open the Command Palette: Ctrl+Shift+P (Mac: Cmd+Shift+P). Then, 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. After that, 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. Finally, open your browser and navigate to your Learning Room repository on GitHub. The rhythm is simple: orient, act, verify, then continue.

      +

      Jamie: Before we leave Practice 10.3 Step-by-Step: Push and Open a Linked PR, what is the practical point?

      +

      Alex: First, GitHub usually shows a yellow banner: "yourname recently pushed to learn/yourname." Activate the Compare & pull request button in that banner. Then, 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/your username branch. After that, in the PR title, write a descriptive title (for example: "docs: improve welcome.md introduction"). Finally, 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. Think of it as a rail line: each stop confirms you are still on the right route before the next one.

      +

      Alex: Keep the teaching thread moving. Start with Completing Challenge 10: Submit Your Evidence: Open your assigned Challenge 10 issue in your Learning Room repo and post a completion comment. The next useful detail is this: Close your Challenge 10 issue when your branch is pushed and the PR is open.

      +

      Jamie: Let's pause on Expected Outcomes. What should a learner take away from it?

      +

      Alex: Start with Expected Outcomes. There is something to understand, something to try, and something that proves the try worked.

      +

      Alex: The parts worth keeping in working memory are these. 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.

      -

      Jamie: Let's pause on MCP Server Integration (Docker required). What should a learner take away from it?

      -

      Alex: Start with MCP Server Integration (Docker required): awesome-copilot also ships as an MCP (Model Context Protocol) Server - a Docker-based tool server that extends Copilot with additional capabilities beyond file-based customizations. The next useful detail is this: Install in VS Code by clicking the button at https://aka.ms/awesome-copilot/mcp/vscode, or add manually to settings.json.

      -

      Alex: Treat examples as spoken recipes, not decorations. You may hear something like {; "mcp": {; "servers": {; "awesome-copilot": {; "type": "stdio",; "command": "docker",; "args": [; "run", "-i", "--rm",; "ghcr.io/github/awesome-copilot-mcp:latest"; ]; }; }; }; }. Read the command, understand what it changes, then run it only when the repository state matches the lesson.

      -

      Alex: Keep the teaching thread moving. Here is the plain-English version of 14. GitHub Agentic Workflows - Agents in the Cloud. Status: Technical Preview - GitHub Agentic Workflows entered technical preview on February 13, 2026. Put another way, as of May 2026 the feature remains in active development and preview; changes to the API and workflow format are ongoing. It is like learning a transit route. The names of the stops matter because they tell you whether you are still going the right direction.

      -

      Jamie: Let's pause on What This Enables. What should a learner take away from it?

      -

      Alex: This is where What This Enables becomes real: browse 50+ community-built workflows at Peli's Agent Factory.

      +

      Jamie: Let's pause on If You Get Stuck. What should a learner take away from it?

      +

      Alex: This is where If You Get Stuck becomes real: continue learning: The GitHub Skills course Introduction to Git walks through commits, branches, and merges in an interactive, self-paced format. That matters in practice: See Appendix Z for the full catalog. The workshop is closer to rehearsal than lecture. You hear the move, try the move, and then check what changed.

      +

      Alex: First, command Palette does not open? Confirm you are in VS Code (not the browser) and press Ctrl+Shift+P (Mac: Cmd+Shift+P). Then, source Control panel is empty? You may not have saved your file yet. Press Ctrl+S to save, then check again. After that, 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. Finally, branch name wrong? Open Command Palette, run Git: Rename Branch. to fix it before pushing. It is a checklist, but a meaningful one: every item creates evidence that the next step is safe.

      +

      Jamie: Before we leave If You Get Stuck, what is the practical point?

      +

      Alex: First, cannot find the "Compare & pull request" banner on GitHub? Navigate to Pull requests tab and create the PR manually (step 6 above). Then, 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. After that, ask facilitator to verify your clone location, branch name, and help with one push. Finally, finished but not sure you did it right? Compare your work against the Challenge 10 reference solution. It is like walking a hallway with named doors: read the sign, enter the right room, then confirm where you landed.

      +

      Jamie: Let's pause on Learning Moment. What should a learner take away from it?

      +

      Alex: Keep the learner anchored in Learning Moment. Local Git operations give you full control and immediate feedback. This is the part to say slowly: You can see your changes, review them, and fix mistakes before they reach GitHub.

      +

      Jamie: Let's pause on Learning Pattern Used in This Chapter. What should a learner take away from it?

      +

      Alex: Start with Learning Pattern Used in This Chapter. There is something to understand, something to try, and something that proves the try worked.

      +

      Alex: First, clone once to get a local copy of the project. Then, branch before editing (never work directly on main). After that, make small, focused edits with clear commit messages. Finally, push and open a PR that links to an issue for traceability. The rhythm is simple: orient, act, verify, then continue.

      +

      Jamie: Before we leave Learning Pattern Used in This Chapter, what is the practical point?

      +

      Alex: First, verify each step before moving to the next. Think of it as a rail line: each stop confirms you are still on the right route before the next one.

      -

      Alex: Keep the teaching thread moving. Keep the learner anchored in How It Works. The gh aw CLI (a gh extension) compiles.md workflow files into.lock.yml GitHub Actions workflows. This is the part to say slowly: The AI agent (GitHub Copilot, Claude, or OpenAI Codex) reads your repository context and the natural language instructions, then performs the task using the GitHub MCP Server and other available tools.

      -

      Jamie: Let's pause on Workflow Format - Markdown with Frontmatter. What should a learner take away from it?

      -

      Alex: The reason Workflow Format - Markdown with Frontmatter matters is that unlike standard GitHub Actions (YAML), agentic workflows are Markdown files. That gives the learner a simple foothold: the body is natural language - describe what you want the AI agent to do.

      -

      Alex: Keep the teaching thread moving. Start with Security Model - "Safe Outputs": Workflows run read-only by default with sandboxed execution, network isolation, and SHA-pinned dependencies. The next useful detail is this: Write operations require explicit declaration in safe-outputs - a set of pre-approved, sanitized GitHub operations. Think of it like entering a new building: first you find the lobby, then the room, then the door you actually need.

      +

      Jamie: Let's pause on About Learning Cards. What should a learner take away from it?

      +

      Alex: Start with About Learning Cards: Throughout this chapter, each major operation includes learning cards - expandable sections showing how to accomplish the same task from multiple perspectives. The next useful detail is this: Open the card that matches how you work.

      +

      Jamie: Let's pause on Tool Cards: Clone a Repository (Day 2). What should a learner take away from it?

      +

      Alex: Here is the plain-English version of Tool Cards: Clone a Repository (Day 2). VS Code Desktop (primary for Day 2). Put another way, github.dev (web editor): No clone needed. It is like learning a transit route. The names of the stops matter because they tell you whether you are still going the right direction.

      +

      Alex: First, ctrl+Shift+P Git: Clone paste the HTTPS URL choose a folder Open. Then, file Clone Repository paste URL or select from your account Clone. Treat it like a recipe: do not add the next ingredient until the previous one is actually in the bowl.

      +

      Alex: Treat examples as spoken recipes, not decorations. You may hear something like git clone https://github.com/owner/repo.git && cd repo. gh repo clone owner/repo && cd repo. Read the command, understand what it changes, then run it only when the repository state matches the lesson.

      +

      Jamie: Let's pause on Method 1: Command Palette (Recommended for Screen Readers). What should a learner take away from it?

      +

      Alex: Start with Method 1: Command Palette (Recommended for Screen Readers). There is something to understand, something to try, and something that proves the try worked.

      +

      Alex: First, open Command Palette: Ctrl+Shift+P (Mac: Cmd+Shift+P). Then, type "git clone". After that, select "Git: Clone". Finally, paste the repository URL (example: https://github.com/community-access/accessibility-agents.git). It is a checklist, but a meaningful one: every item creates evidence that the next step is safe.

      +

      Jamie: Before we leave Method 1: Command Palette (Recommended for Screen Readers), what is the practical point?

      +

      Alex: First, press Enter. Then, choose a local folder where the repository should be cloned. After that, VS Code asks: "Would you like to open the cloned repository?" - select "Open". It is like walking a hallway with named doors: read the sign, enter the right room, then confirm where you landed.

      +

      Alex: A solid navigation habit is to prove where you are before activating controls. Headings, landmarks, and the address bar are not trivia; they are your map.

      -

      Jamie: Let's pause on Getting Started with gh aw. What should a learner take away from it?

      -

      Alex: Start with Getting Started with gh aw. There is something to understand, something to try, and something that proves the try worked.

      -

      Alex: Treat examples as spoken recipes, not decorations. You may hear something like Install the CLI extension; gh extension install github/gh-aw; Create a new workflow interactively (from github.com or VS Code also works); gh aw create; Compile your Markdown workflow to a GitHub Actions.lock.yml; gh aw. Read the command, understand what it changes, then run it only when the repository state matches the lesson.

      -

      Jamie: Let's pause on Monitoring Agentic Workflow Runs. What should a learner take away from it?

      -

      Alex: Start with Monitoring Agentic Workflow Runs. There is something to understand, something to try, and something that proves the try worked.

      -

      Alex: First, navigate to the Actions tab of your repository (D → Repository navigation → K to Actions). Then, find the workflow by name (h3 headings, navigate with 3). After that, press Enter to open a specific run. Finally, expand job steps to read the agent output log and any safe-outputs created. It is a checklist, but a meaningful one: every item creates evidence that the next step is safe.

      -

      Jamie: Let's pause on Resources. What should a learner take away from it?

      -

      Alex: Keep the learner anchored in Resources. Relationship to Accessibility Agents: Accessibility Agents agents (.agent.md files) are designed for interactive use inside VS Code. This is the part to say slowly: GitHub Agentic Workflows are a separate, cloud-native system that uses its own Markdown workflow format and the gh aw CLI - they are complementary tools, not the same mechanism.

      +

      Alex: Keep the teaching thread moving. Start with Screen reader navigation. There is something to understand, something to try, and something that proves the try worked.

      +

      Alex: The practical takeaway is this. 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.

      +

      Jamie: Let's pause on Method 2: Start Page Clone Button. What should a learner take away from it?

      +

      Alex: The reason Method 2: Start Page Clone Button matters is that the Start page is keyboard-accessible. That gives the learner a simple foothold: tab to navigate between "New File," "Open Folder," and "Clone Repository" buttons.

      +

      Alex: First, open VS Code (no folder open). Then, the Start page appears. After that, navigate to "Clone Git Repository" button - press Enter. Finally, paste repository URL → Enter. The rhythm is simple: orient, act, verify, then continue.

      +

      Jamie: Before we leave Method 2: Start Page Clone Button, what is the practical point?

      +

      Alex: First, choose destination folder. Then, open when prompted. Think of it as a rail line: each stop confirms you are still on the right route before the next one.

      +

      Jamie: Let's pause on Method 3: From GitHub.com. What should a learner take away from it?

      +

      Alex: Start with Method 3: From GitHub.com. There is something to understand, something to try, and something that proves the try worked.

      +

      Alex: First, on any GitHub repository page, click the green "Code" button. Then, copy the HTTPS URL (recommended) or SSH URL. After that, open VS Code → Ctrl+Shift+P (Mac: Cmd+Shift+P) → "Git: Clone". Finally, paste URL → Enter. Think of it as a rail line: each stop confirms you are still on the right route before the next one.

      +

      Jamie: Before we leave Method 3: From GitHub.com, what is the practical point?

      +

      Alex: First, choose destination → Open. Treat it like a recipe: do not add the next ingredient until the previous one is actually in the bowl.

      -

      Alex: Keep the teaching thread moving. Start with Learning Cards: GitHub Agentic Workflows. There is something to understand, something to try, and something that proves the try worked.

      -

      Alex: The practical takeaway is this. Agentic workflow runs appear in the Actions tab of your repository -- navigate to Actions with T (tab bar), then use heading navigation (3) to jump between workflow run entries. Workflow files are Markdown (.md) not YAML -- the frontmatter at the top controls triggers and permissions; the body is natural language instructions the AI agent reads. The safe-outputs frontmatter property lists every write operation the agent is allowed to perform -- review this section carefully since it is the security boundary. The Actions tab lists workflow runs with status icons (green check, red X, yellow circle) -- at high zoom, also look for the text status label next to each run name. Workflow.md files use the same Markdown rendering as any other file in the repo -- edit them in VS Code with your preferred font size and theme. The gh aw compile command generates a.lock.yml file alongside your.md file -- both appear in the file explorer; the.lock.yml is auto-generated and should not be edited manually.

      -

      Jamie: Let's pause on Copilot Models. What should a learner take away from it?

      -

      Alex: Start with Copilot Models. There is something to understand, something to try, and something that proves the try worked.

      -

      Alex: The practical takeaway is this. Overview. How to Choose a Model. Complete Model Reference. Model Availability by Plan. Premium Requests and Cost Multipliers. Switching Models in VS Code.

      -

      Alex: Keep the teaching thread moving. Here is the plain-English version of 1. Overview. GitHub Copilot offers access to AI models from multiple providers including OpenAI, Anthropic, Google, and xAI. Put another way, the model you choose affects response quality, speed, and premium request consumption.

      -
      -

      Jamie: Let's pause on 2. How to Choose a Model. What should a learner take away from it?

      -

      Alex: This is where 2. How to Choose a Model becomes real: GitHub Docs organizes models by task. That matters in practice: Match your task to the right model to get the best results without unnecessary premium request cost.

      -

      Alex: Keep the teaching thread moving. Keep the learner anchored in General-Purpose Coding and Writing. For everyday tasks - code completions, explanations, refactoring, writing documentation. A good GitHub workflow is like a well-run meeting: everyone knows the topic, the next action, and who has the floor.

      -

      Jamie: How should someone ask for help in a way that gets them unstuck faster?

      -

      Alex: The reason Fast Help with Simple or Repetitive Tasks matters is that for quick answers, boilerplate generation, renaming, or lightweight explanations where speed matters.

      +

      Jamie: Let's pause on Learning Cards: Cloning a Repository. What should a learner take away from it?

      +

      Alex: Here is the plain-English version of Learning Cards: Cloning a Repository. Low vision users (zoom, high contrast). Put another way, cloning works the same as the Command Palette method above.

      +

      Alex: First, 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. Then, 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. After that, 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. Finally, 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. Treat it like a recipe: do not add the next ingredient until the previous one is actually in the bowl.

      +

      Jamie: Before we leave Learning Cards: Cloning a Repository, what is the practical point?

      +

      Alex: First, navigate to the repository on GitHub.com. Then, press. (period) to open github.dev - a browser-based VS Code editor. After that, the full repository opens in an editor with file tree, search, and editing. Finally, changes are committed directly to GitHub from the browser. It is a checklist, but a meaningful one: every item creates evidence that the next step is safe.

      +

      Alex: Treat examples as spoken recipes, not decorations. You may hear something like 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. Read the command, understand what it changes, then run it only when the repository state matches the lesson.

      +

      Alex: Keep the teaching thread moving. This is where Try It Now: Clone the Sci-Fi Themes Repo becomes real: to make your first clone meaningful and fun, try cloning the VS Code Sci-Fi Thinking Phrases repository. That matters in practice: Repository URL: https://github.com/community-access/vscode-sci-fi-themes.git.

      +

      Alex: The practical takeaway is this. 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.

      +

      Jamie: Let's pause on Why Clone This? What should a learner take away from it?

      +

      Alex: Start with Why Clone This? There is something to understand, something to try, and something that proves the try worked.

      +

      Alex: The practical takeaway is 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!

      -

      Alex: Keep the teaching thread moving. Start with Deep Reasoning and Debugging: For complex problems, architecture decisions, multi-file analysis, tricky bugs, and understanding unfamiliar codebases.

      -

      Jamie: Let's pause on Agentic Software Development. What should a learner take away from it?

      -

      Alex: Here is the plain-English version of Agentic Software Development. For autonomous coding tasks in Agent mode - when Copilot writes code, runs terminal commands, and iterates without step-by-step guidance from you.

      -

      Alex: Keep the teaching thread moving. This is where Working with Visuals becomes real: for tasks that involve images, screenshots, diagrams, or UI mockups - paste an image directly into the chat input. The workshop is closer to rehearsal than lecture. You hear the move, try the move, and then check what changed.

      +

      Jamie: Let's pause on Quick Start. What should a learner take away from it?

      +

      Alex: The reason Quick Start matters is that see CLONE-THIS-REPO.md in that repo for full instructions. That gives the learner a simple foothold: if you prefer not to clone locally, you can work entirely on GitHub.com. The interface gets friendlier when it stops being a wall of controls and starts being a set of named places.

      +

      Alex: First, clone: Ctrl+Shift+P → "Git: Clone" → paste URL above → Enter. Then, choose a destination folder and open when prompted. After that, navigate to the themes/ folder and pick a.json file (star-trek, hitchhikers, or star-wars). Finally, copy the chat.agent.thinking.phrases setting into your VS Code settings.json. The rhythm is simple: orient, act, verify, then continue.

      +

      Jamie: Before we leave Quick Start, what is the practical point?

      +

      Alex: First, reload VS Code: Ctrl+Shift+P → "Developer: Reload Window". Then, open Copilot Chat (Ctrl+Shift+I) and ask a question--watch your custom phrases appear! After that, navigate to the repository on GitHub. Finally, click any file to view it, then click the pencil icon (Edit) to modify it directly in the browser. Think of it as a rail line: each stop confirms you are still on the right route before the next one.

      +

      Alex: Treat examples as spoken recipes, not decorations. You may hear something like 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. Read the command, understand what it changes, then run it only when the repository state matches the lesson.

      +

      Jamie: Let's pause on 2. The Source Control Panel - Complete Walkthrough. What should a learner take away from it?

      +

      Alex: Start with 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. The next useful detail is this: This section provides a complete screen reader walkthrough of every interactive element.

      +

      Alex: Keep the teaching thread moving. Here is the plain-English version of Opening the Source Control Panel. Shortcut: Ctrl+Shift+G (Mac: Cmd+Shift+G).

      -

      Jamie: Let's pause on 3. Complete Model Reference. What should a learner take away from it?

      -

      Alex: Keep the learner anchored in 3. Complete Model Reference. Model availability changes frequently. This is the part to say slowly: Check GitHub's supported models page for the current list.

      -

      Alex: Keep the teaching thread moving. The reason 4. Model Availability by Plan matters is that GitHub Copilot plan details and billing models are actively evolving. That gives the learner a simple foothold: facilitators will provide current guidance at the workshop.

      -

      Jamie: Let's pause on Tips for managing premium request usage. What should a learner take away from it?

      -

      Alex: Start with Tips for managing premium request usage. There is something to understand, something to try, and something that proves the try worked.

      -

      Alex: The practical takeaway is this. Use GPT-4.1 or GPT-5 mini (both free) for everyday questions, quick explanations, and simple completions - they're fast and capable. Upgrade to Claude Sonnet or GPT-5.2 (1×) only when the task genuinely requires deeper reasoning. Save Claude Opus (3×) for the most demanding analyses - architecture decisions, complex debugging, sophisticated design review. Use Auto mode (see below) and let Copilot allocate model selection intelligently.

      +

      Jamie: Let's pause on What opens. What should a learner take away from it?

      +

      Alex: Start with What opens. There is something to understand, something to try, and something that proves the try worked.

      +

      Alex: The practical takeaway is this. 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).

      +

      Jamie: Let's pause on Panel structure from top to bottom. What should a learner take away from it?

      +

      Alex: Start with Panel structure from top to bottom. There is something to understand, something to try, and something that proves the try worked.

      +

      Alex: The practical takeaway is this. Branch name displayed (example: "main" or "feature/add-documentation"). View/More Actions button (three dots menu). Type your commit message here. Announced as "Source Control Input, edit, multi-line". Shortcut: Ctrl+Enter (Mac: Cmd+Enter) when focused in the message input. Lists all modified files not yet staged.

      +

      Alex: First, source Control title bar (heading level 2). Then, commit message input (multi-line text field). After that, commit button (or "Publish Branch" if this is a new branch). Finally, changes section (collapsible tree). It is like walking a hallway with named doors: read the sign, enter the right room, then confirm where you landed.

      +

      Jamie: Before we leave Panel structure from top to bottom, what is the practical point?

      +

      Alex: First, staged Changes section (collapsible tree). Then, merge Changes section (appears only during a merge). The rhythm is simple: orient, act, verify, then continue.

      +

      Jamie: Let's pause on NVDA/JAWS. What should a learner take away from it?

      +

      Alex: Start with NVDA/JAWS. There is something to understand, something to try, and something that proves the try worked.

      +

      Alex: The practical takeaway is this. 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).

      -

      Jamie: Let's pause on In the Chat Panel. What should a learner take away from it?

      -

      Alex: Start with In the Chat Panel. There is something to understand, something to try, and something that proves the try worked.

      -

      Alex: First, open the Chat panel (Ctrl+Shift+I / Cmd+Shift+I). Then, at the bottom of the chat input area, you'll see the current model name as a button (e.g., "Auto" or "Claude Sonnet 4.6"). After that, activate the model picker button - this opens a dropdown list of available models. Finally, arrow through the list and press Enter to select a model. Treat it like a recipe: do not add the next ingredient until the previous one is actually in the bowl.

      -

      Jamie: Before we leave In the Chat Panel, what is the practical point?

      -

      Alex: First, for screen reader users: the chat input will announce the newly selected model after switching. It is a checklist, but a meaningful one: every item creates evidence that the next step is safe.

      -

      Jamie: Let's pause on In an Inline Chat Session. What should a learner take away from it?

      -

      Alex: Start with In an Inline Chat Session. There is something to understand, something to try, and something that proves the try worked.

      -

      Alex: First, open Inline Chat (Ctrl+I / Cmd+I). Then, the model picker appears in the inline chat toolbar. After that, same interaction: activate the model button to switch. It is a checklist, but a meaningful one: every item creates evidence that the next step is safe.

      -

      Alex: Keep the teaching thread moving. Keep the learner anchored in Keyboard Note for Screen Readers. In the Chat panel, the model picker button is near the bottom of the chat view. This is the part to say slowly: If you're having trouble locating it.

      -

      Alex: The practical takeaway is this. Tab through the bottom toolbar of the chat panel. Listen for the model name announced - it appears between the "Attach" button and the send button. Press Space or Enter to open the picker.

      +

      Alex: Keep the teaching thread moving. Start with VoiceOver: Key point: The Source Control panel is not a standard file tree. The next useful detail is this: It's a specialized Git status view.

      +

      Alex: The practical takeaway is this. Navigate with VO+Arrow keys. VO+Space to activate (open diff or stage/unstage). The panel is announced as a "group" containing lists.

      +

      Jamie: Let's pause on What Each File Shows. What should a learner take away from it?

      +

      Alex: Here is the plain-English version of What Each File Shows. When a file appears in the Changes or Staged Changes list, VS Code shows a status letter. Put another way, screen reader announcement: "docs/GUIDE.md, Modified" or "README.md, Added".

      +

      Alex: Keep the teaching thread moving. This is where Context Menu Actions (Right-Click or Shift+F10) becomes real: when focused on any file in the Source Control panel. That matters in practice: Use Shift+F10 to open the context menu. The workshop is closer to rehearsal than lecture. You hear the move, try the move, and then check what changed.

      -

      Jamie: Let's pause on 7. Auto Model Selection. What should a learner take away from it?

      -

      Alex: The reason 7. Auto Model Selection matters is that auto mode (the default) lets Copilot choose the best model based on the type of request. That gives the learner a simple foothold: it became generally available on December 10, 2025.

      -

      Alex: Keep the teaching thread moving. Start with How Auto works. There is something to understand, something to try, and something that proves the try worked.

      -

      Alex: The practical takeaway is this. For simple questions, Copilot routes to a faster, lighter model. For complex code generation or debugging, Copilot upgrades to a more capable model automatically. For agent tasks, Copilot selects an appropriate Codex model. You can see which model was used after each response.

      -

      Jamie: Let's pause on When to override Auto. What should a learner take away from it?

      -

      Alex: Here is the plain-English version of When to override Auto. To switch back to Auto from a specific model, re-open the model picker and select Auto at the top of the list.

      -

      Alex: The practical takeaway is this. You specifically need a model with certain capabilities (e.g., vision input with Claude Sonnet 4). You're managing premium request quotas and want to control costs. You've found a particular model gives better results for your specific workflow or domain. You're doing agentic work and want to explicitly select an agent-optimized Codex model (check current availability in the model picker).

      +

      Jamie: Let's pause on Learning Cards: Source Control Panel. What should a learner take away from it?

      +

      Alex: Keep the learner anchored in Learning Cards: Source Control Panel. Low vision users (zoom, high contrast). This is the part to say slowly: The Source Control panel adapts well to zoom and high contrast settings.

      +

      Alex: First, 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. Then, 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. After that, 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). Finally, 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. It is like walking a hallway with named doors: read the sign, enter the right room, then confirm where you landed.

      +

      Jamie: Before we leave Learning Cards: Source Control Panel, what is the practical point?

      +

      Alex: First, 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. The rhythm is simple: orient, act, verify, then continue.

      +

      Alex: Treat examples as spoken recipes, not decorations. You may hear something like 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. Read the command, understand what it changes, then run it only when the repository state matches the lesson.

      +

      Alex: Keep the teaching thread moving. The reason 3. Branch Management matters is that branches are how you organize work in Git. That gives the learner a simple foothold: every repository starts with a main or master branch.

      +

      Jamie: Let's pause on Where it's shown. What should a learner take away from it?

      +

      Alex: Start with Where it's shown. There is something to understand, something to try, and something that proves the try worked.

      +

      Alex: First, bottom-left corner of VS Code (status bar) - visual users see it immediately. Then, source Control panel title bar. After that, command Palette: Ctrl+Shift+P (Mac: Cmd+Shift+P) → "Git: Show Git Output". Think of it as a rail line: each stop confirms you are still on the right route before the next one.

      -

      Alex: Keep the teaching thread moving. This is where 8. Models Retiring Soon becomes real: GitHub regularly updates the model roster. That matters in practice: Older model versions are retired when newer equivalents are available.

      -

      Jamie: Let's pause on Already retired (as of April 2026). What should a learner take away from it?

      -

      Alex: Keep the learner anchored in Already retired (as of April 2026). To stay current, watch the GitHub Copilot changelog - model additions and retirements are announced there.

      -

      Alex: The practical takeaway is this. Claude Sonnet 3.5, Claude Sonnet 3.7. Gemini 2.0 Flash. o1-mini, o3, o3-mini, o4-mini. Claude Opus 4.1. GPT-5 (base), GPT-5-Codex. GPT-5.3-Codex (removed from Student plan model picker, April 2026).

      -

      Alex: Keep the teaching thread moving. The reason Related Resources matters is that next: Appendix L: Agents Reference Back: Appendix J: Codespaces Teaching chapter: Chapter 16: GitHub Copilot. The interface gets friendlier when it stops being a wall of controls and starts being a set of named places.

      +

      Alex: Keep the teaching thread moving. Here is the plain-English version of Keyboard access to status bar. Visual users: You can also click the branch name in the bottom-left status bar to open the branch picker directly. It is like learning a transit route. The names of the stops matter because they tell you whether you are still going the right direction.

      +

      Alex: The practical takeaway is this. The status bar is not in the standard keyboard navigation flow. Use the Command Palette for branch operations instead.

      +

      Jamie: Let's pause on Command Palette method (recommended). What should a learner take away from it?

      +

      Alex: Start with Command Palette method (recommended). There is something to understand, something to try, and something that proves the try worked.

      +

      Alex: The practical takeaway is this. Creates the branch. Switches to it automatically. Your working files stay exactly as they were.

      +

      Alex: First, ctrl+Shift+P (Mac: Cmd+Shift+P). Then, type "git create branch". After that, select "Git: Create Branch.". Finally, type the new branch name (example: feature/improve-docs). It is a checklist, but a meaningful one: every item creates evidence that the next step is safe.

      +

      Jamie: Before we leave Command Palette method (recommended), what is the practical point?

      +

      Alex: First, press Enter. It is like walking a hallway with named doors: read the sign, enter the right room, then confirm where you landed.

      +

      Jamie: Let's pause on Naming conventions. What should a learner take away from it?

      +

      Alex: Keep the learner anchored in Naming conventions. Web alternative (github.com) - branch management. This is the part to say slowly: Create and switch branches without leaving your browser.

      +

      Alex: The practical takeaway is this. Use lowercase with hyphens: feature/add-timeline-guide. Avoid spaces and special characters. Be descriptive: fix/heading-hierarchy not fix1.

      +

      Alex: First, on the repository page, click the branch dropdown (shows "main" by default). Then, type a new branch name in the search field. After that, click "Create branch: your-branch-name from main". Finally, GitHub switches to the new branch immediately. It is like walking a hallway with named doors: read the sign, enter the right room, then confirm where you landed.

      +

      Jamie: Before we leave Naming conventions, what is the practical point?

      +

      Alex: First, any file edits you make in the browser will be on this branch. The rhythm is simple: orient, act, verify, then continue.

      +

      Alex: Treat examples as spoken recipes, not decorations. You may hear something like 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. Read the command, understand what it changes, then run it only when the repository state matches the lesson.

      -

      Jamie: What should people carry with them after this?

      -

      Alex: Carry the map. Know what page or tool you are in, know which action you are taking, and know what confirmation should follow. If the confirmation is missing, pause. That pause is not wasted time; it is professional judgment.

      -

      Jamie: That is a better way to say it than just follow the steps.

      -

      Alex: Right. Steps matter, but understanding wins. That is episode 40. Next in the series is episode 41, where we keep building the same contributor muscles.

      -
      - +

      Jamie: Let's pause on Command Palette method. What should a learner take away from it?

      +

      Alex: The reason Command Palette method matters is that screen reader announcement: "Branch: main" or "Branch: feature/add-timeline-guide".

      +

      Alex: First, ctrl+Shift+P (Mac: Cmd+Shift+P). Then, type "git checkout". After that, select "Git: Checkout to.". Finally, a list of all branches appears. The rhythm is simple: orient, act, verify, then continue.

      +

      Jamie: Before we leave Command Palette method, what is the practical point?

      +

      Alex: First, up/Down Arrow to navigate. Then, enter to switch. Think of it as a rail line: each stop confirms you are still on the right route before the next one.

      +

      Alex: Keep the teaching thread moving. Start with What happens when you switch. There is something to understand, something to try, and something that proves the try worked.

      +

      Alex: The practical takeaway is this. 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).

      +

      Jamie: Let's pause on After your PR is merged, you can delete the branch. What should a learner take away from it?

      +

      Alex: Here is the plain-English version of After your PR is merged, you can delete the branch. You cannot delete the branch you're currently on.

      +

      Alex: First, ctrl+Shift+P (Mac: Cmd+Shift+P). Then, type "git delete branch". After that, select "Git: Delete Branch.". Finally, choose the branch to delete from the list. Treat it like a recipe: do not add the next ingredient until the previous one is actually in the bowl.

      -

      Episode 41: Copilot AI Models

      -

      Model comparison, strengths, plan availability, and selection guidance.

      -

      Based on: Appendix K: Copilot AI Models

      -

      Audio and transcript are being regenerated for this episode.

      -
      -Read Transcript - Episode 41: Copilot AI Models - -

      Transcript

      -

      Alex: Welcome back to Git Going with GitHub. This is episode 41: Copilot AI Models. I am Alex, and today we are turning Copilot AI Models from a list of instructions into a working mental model.

      -

      Jamie: And I am Jamie. I will stop us whenever the instructions sound simple on paper but might feel different with a keyboard and screen reader.

      +

      Jamie: Let's pause on Viewing All Branches. What should a learner take away from it?

      +

      Alex: This is where Viewing All Branches becomes real: command: Ctrl+Shift+P → "Git: Show Git Output" → Branch list appears. That matters in practice: Alternative: Use the integrated terminal.

      +

      Alex: Treat examples as spoken recipes, not decorations. You may hear something like git branch Local branches only; git branch -a All branches (including remote). Read the command, understand what it changes, then run it only when the repository state matches the lesson.

      +

      Jamie: Let's pause on Learning Cards: Branch Management. What should a learner take away from it?

      +

      Alex: Keep the learner anchored in Learning Cards: Branch Management. Low vision users (zoom, high contrast). This is the part to say slowly: Screen reader users (NVDA / JAWS on Windows).

      +

      Alex: First, 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. Then, 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. After that, 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. It is like walking a hallway with named doors: read the sign, enter the right room, then confirm where you landed.

      +

      Jamie: Let's pause on Creating a branch. What should a learner take away from it?

      +

      Alex: Start with Creating a branch. There is something to understand, something to try, and something that proves the try worked.

      +

      Alex: First, press Ctrl+Shift+P to open the Command Palette. Then, type "git create branch" - NVDA/JAWS announces results as you type. After that, press Enter on "Git: Create Branch.". Finally, the input focus moves to a text field - type your branch name (e.g., feature/add-docs). The rhythm is simple: orient, act, verify, then continue.

      +

      Jamie: Before we leave Creating a branch, what is the practical point?

      +

      Alex: First, press Enter - VS Code creates and switches to the branch. Then, NVDA/JAWS announces the new branch name in the status bar notification. Think of it as a rail line: each stop confirms you are still on the right route before the next one.

      -

      Alex: Model comparison, strengths, plan availability, and selection guidance. That is the surface description. Underneath it, we are building judgment: where to focus, what to ignore, and how to verify the result.

      -

      Jamie: So we are not using the audio as a shortcut around learning. We are using it to make the learning easier to enter.

      -

      Alex: Yes. A good audio lesson gives someone enough context to try the work with confidence, even before they open the written material.

      +

      Jamie: Let's pause on Switching branches. What should a learner take away from it?

      +

      Alex: Start with Switching branches. There is something to understand, something to try, and something that proves the try worked.

      +

      Alex: First, press Ctrl+Shift+P, type "git checkout". Then, select "Git: Checkout to.". After that, a list of branches appears - navigate with Up/Down Arrow. Finally, each item is announced as the branch name (e.g., "main", "feature/add-docs"). Think of it as a rail line: each stop confirms you are still on the right route before the next one.

      +

      Jamie: Before we leave Switching branches, what is the practical point?

      +

      Alex: First, press Enter to switch. Then, VS Code reloads files for that branch - you hear a status bar update. Treat it like a recipe: do not add the next ingredient until the previous one is actually in the bowl.

      +

      Jamie: Let's pause on Deleting a branch. What should a learner take away from it?

      +

      Alex: Here is the plain-English version of Deleting a branch. Screen reader users (VoiceOver on macOS).

      +

      Alex: First, switch to a different branch first (you cannot delete the branch you are on). Then, press Ctrl+Shift+P, type "git delete branch". After that, select "Git: Delete Branch.". Finally, navigate the list to find the branch to delete, press Enter. Treat it like a recipe: do not add the next ingredient until the previous one is actually in the bowl.

      +

      Jamie: What is the teaching move inside Creating a branch?

      +

      Alex: First, press Cmd+Shift+P to open the Command Palette. Then, type "git create branch" - VoiceOver announces filtered results. After that, press Return on "Git: Create Branch.". Finally, type the branch name in the input field. It is a checklist, but a meaningful one: every item creates evidence that the next step is safe.

      +

      Jamie: If someone only remembers one thing from Creating a branch, what should it be?

      +

      Alex: First, press Return to create and switch. It is like walking a hallway with named doors: read the sign, enter the right room, then confirm where you landed.

      -

      Jamie: Okay, set the room for us. What are we walking into?

      -

      Alex: Start with Keyboard Shortcuts, Chat, Screen Reader Workflow, Plugin Ecosystem, and GitHub Agentic Workflows: Quick-reference card for GitHub Copilot in VS Code and the broader agentic ecosystem - plugins, MCP servers, and cloud-based automation. The next useful detail is this: For the Copilot lesson, see Chapter 16: GitHub Copilot.

      -

      Alex: A solid navigation habit is to prove where you are before activating controls. Headings, landmarks, and the address bar are not trivia; they are your map.

      -

      Alex: The next layer is this. Here is the plain-English version of Inline Suggestions (Ghost Text). Word-by-word acceptance (Ctrl+Right Arrow) is recommended for screen reader users - it lets you review the suggestion incrementally before committing to it. Put another way, accessible View workflow for screen reader users: Press Alt+F2 when a suggestion appears to hear the full text without streaming noise, then press Ctrl+/ to insert it directly from the Accessible View without closing the panel first. It is like learning a transit route. The names of the stops matter because they tell you whether you are still going the right direction.

      -

      Jamie: What is the one idea that makes the next few steps less mysterious?

      -

      Alex: This is where Accessibility becomes real: use Accessible View (Alt+F2) every time Copilot responds. That matters in practice: It provides the complete response in a readable pane - no streaming, no live region noise, proper heading structure.

      +

      Jamie: What is the teaching move inside Switching branches?

      +

      Alex: First, press Cmd+Shift+P, type "git checkout". Then, select "Git: Checkout to.". After that, use VO+Down Arrow to navigate the branch list. Finally, press Return to switch. It is like walking a hallway with named doors: read the sign, enter the right room, then confirm where you landed.

      +

      Jamie: Let's pause on Getting the current branch name. What should a learner take away from it?

      +

      Alex: The reason Getting the current branch name matters is that create and switch branches without leaving your browser. That gives the learner a simple foothold: manage branches from your terminal.

      +

      Alex: First, press VO+M to move to the menu bar, then VO+Right Arrow to the status bar area. Then, or use the Command Palette: Cmd+Shift+P then type "Git: Show Git Output" - the output pane includes the current branch. After that, on the repository page, find the branch dropdown button (shows "main" by default) - it is above the file table. Finally, click or activate the dropdown. The rhythm is simple: orient, act, verify, then continue.

      +

      Jamie: Before we leave Getting the current branch name, what is the practical point?

      +

      Alex: First, type a new branch name in the search field. Then, click "Create branch: your-branch-name from main" when it appears. After that, GitHub switches to the new branch immediately. Finally, any file edits in the browser will be on this branch. Think of it as a rail line: each stop confirms you are still on the right route before the next one.

      +

      Alex: Treat examples as spoken recipes, not decorations. You may hear something like 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. 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'. Read the command, understand what it changes, then run it only when the repository state matches the lesson.

      +

      Jamie: Let's pause on 4. Staging Changes - Files, Lines, and Chunks. What should a learner take away from it?

      +

      Alex: Start with 4. Staging Changes - Files, Lines, and Chunks: This lets you commit only part of your work, leaving the rest for a later commit.

      +

      Alex: First, stage the changes you want to include. Then, commit those staged changes. Think of it as a rail line: each stop confirms you are still on the right route before the next one.

      -

      Alex: Now bring the learner back to the room. Keep the learner anchored in 2. Chat Participants. Type these in the Copilot Chat input to give Copilot context from a specific source.

      -

      Jamie: What should they understand before typing anything?

      -

      Alex: Start with Example prompts. There is something to understand, something to try, and something that proves the try worked.

      -

      Alex: Treat examples as spoken recipes, not decorations. You may hear something like @workspace find all places where heading hierarchy is documented; @github search community-access/accessibility-agents for issues labeled accessibility; @terminal what did the last command output mean? Read the command, understand what it changes, then run it only when the repository state matches the lesson.

      -

      Alex: A solid pull request habit is to separate three questions: what changed, why it changed, and what still needs review. That keeps the conversation useful instead of noisy.

      -

      Alex: That matters because of the next idea. Start with 3. Chat Slash Commands: Type / in Copilot Chat to see the available built-in commands. Think of it like entering a new building: first you find the lobby, then the room, then the door you actually need.

      -

      Alex: The useful habit is simple: orient first, act second, verify third. That pause before acting is part of the work.

      +

      Jamie: Let's pause on Staging an Entire File. What should a learner take away from it?

      +

      Alex: Here is the plain-English version of Staging an Entire File. Low vision users (zoom, high contrast). Put another way, screen reader users (NVDA / JAWS / VoiceOver).

      +

      Alex: The practical takeaway is this. 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.

      +

      Alex: First, open Source Control: Ctrl+Shift+G (Mac: Cmd+Shift+G). Then, hover over a file in the "Changes" list - a + icon appears to its right. After that, click the + to stage that file. Finally, or right-click a file → "Stage Changes". Treat it like a recipe: do not add the next ingredient until the previous one is actually in the bowl.

      +

      Jamie: Before we leave Staging an Entire File, what is the practical point?

      +

      Alex: First, at high zoom, the + (stage), undo (discard), and open file icons may be small. Instead of hovering. Then, 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. After that, in high contrast themes, staged files show a distinct background or border in the Staged Changes section. Finally, navigate to the file in the "Changes" list. It is a checklist, but a meaningful one: every item creates evidence that the next step is safe.

      +

      Alex: Keep the teaching thread moving. Start with Alternative (keyboard shortcut). There is something to understand, something to try, and something that proves the try worked.

      +

      Alex: The practical takeaway is this. Focus the file → press Space.

      +

      Jamie: Let's pause on Alternative (context menu). What should a learner take away from it?

      +

      Alex: Start with Alternative (context menu). There is something to understand, something to try, and something that proves the try worked.

      +

      Alex: The practical takeaway is this. Focus the file → press Shift+F10 (Mac: Ctrl+Return) → select "Stage Changes".

      -

      Jamie: There are a lot of tools in play. How do we keep that from feeling like a contest?

      -

      Alex: Here is the plain-English version of Workspace management slash commands. These are Copilot's built-in chat slash commands. Put another way, accessibility Agents adds 28 additional workspace-level slash commands from.github/prompts/ - see Appendix L for the full list.

      -

      Alex: This is where the talk moves from concept to action. This is where 4. Chat Modes becomes real: select the current mode from the dropdown at the bottom of the Chat input area. That matters in practice: The mode selector is in the Chat panel toolbar at the bottom.

      -

      Jamie: What stays the same when the tool changes?

      -

      Alex: Start with Learning Cards: Chat Participants, Commands, and Modes. There is something to understand, something to try, and something that proves the try worked.

      -

      Alex: These are the details that keep the idea from floating away. Type @ in Chat to scope context (@workspace, @terminal, @github) -- the autocomplete list is keyboard-navigable with arrow keys. Type / for slash commands (/explain, /fix, /tests) -- each is announced with its description as you arrow through. The mode selector is at the bottom of the Chat panel toolbar; Tab to it, then Space or Enter to open the dropdown. Chat responses appear in the panel with syntax highlighting -- increase the Chat panel font size via editor.fontSize in settings. The @ and / trigger characters are small but the autocomplete popup that follows is large and themed to your current color scheme. Use Ask mode for reading explanations, Agent mode for controlled multi-file changes and autonomous tasks (Edit mode is being deprecated into Agent mode as of VS Code 1.118).

      +

      Alex: Keep the teaching thread moving. Start with What happens. There is something to understand, something to try, and something that proves the try worked.

      +

      Alex: The practical takeaway is this. The file moves from "Changes" → "Staged Changes". A green "A" or "M" indicator appears.

      +

      Jamie: Let's pause on Staging Multiple Files at Once. What should a learner take away from it?

      +

      Alex: Start with Staging Multiple Files at Once: All modified files move to "Staged Changes.".

      +

      Alex: First, ctrl+Shift+G (Mac: Cmd+Shift+G) to open Source Control. Then, navigate to the "Changes" section heading. After that, press Shift+F10 (Mac: Ctrl+Return) to open context menu on the section itself. Finally, select "Stage All Changes". Think of it as a rail line: each stop confirms you are still on the right route before the next one.

      +

      Alex: Keep the teaching thread moving. Here is the plain-English version of 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. It is like learning a transit route. The names of the stops matter because they tell you whether you are still going the right direction.

      -

      Alex: Before the learner moves on. The reason 5. Custom Instructions - All Levels matters is that GitHub Copilot supports multiple ways to provide custom instructions. That gives the learner a simple foothold: they differ by scope, priority, trigger mechanism, and which tools recognize them. The interface gets friendlier when it stops being a wall of controls and starts being a set of named places.

      -

      Jamie: What would you say to someone who is already bracing for this to be too much?

      -

      Alex: Start with 4A. Always-On Instructions -.github/copilot-instructions.md: What it is: The primary VS Code Copilot instruction file. The next useful detail is this: Content is automatically included in every chat request and inline suggestion context - you never need to invoke it.

      -

      Jamie: How would you walk the room through that step by step?

      -

      Alex: Start with Auto-generate with /init. There is something to understand, something to try, and something that proves the try worked.

      -

      Alex: First, open Copilot Chat. Then, type /init. After that, VS Code analyzes your workspace and generates a tailored copilot-instructions.md. Finally, review and edit the result before committing. Treat it like a recipe: do not add the next ingredient until the previous one is actually in the bowl.

      +

      Jamie: Let's pause on Workflow. What should a learner take away from it?

      +

      Alex: This is where Workflow becomes real: result: Only those lines are staged. That matters in practice: The rest of the file remains in "Changes.".

      +

      Alex: First, open Source Control: Ctrl+Shift+G (Mac: Cmd+Shift+G). Then, navigate to a file in "Changes". After that, press Enter to open the diff view. Finally, the diff shows your changes side-by-side or inline. It is a checklist, but a meaningful one: every item creates evidence that the next step is safe.

      +

      Jamie: Before we leave Workflow, what is the practical point?

      +

      Alex: First, navigate to a changed line (use Arrow keys or F7 for next hunk). Then, press Shift+F10 (Mac: Ctrl+Return) to open context menu. After that, select "Stage Selected Lines". It is like walking a hallway with named doors: read the sign, enter the right room, then confirm where you landed.

      +

      Jamie: Let's pause on Use case for this workshop. What should a learner take away from it?

      +

      Alex: Keep the learner anchored in Use case for this workshop. In the diff view, press Alt+H to see Accessible Help for diff-specific keyboard shortcuts. This is the part to say slowly: Web alternative (github.com) - editing files.

      +

      Alex: The practical takeaway is this. 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".

      +

      Alex: First, click the pencil icon on any file to open the web editor. Then, make your changes. After that, click "Commit changes" - GitHub creates the commit directly. Finally, choose to commit to the current branch or create a new branch and PR. It is like walking a hallway with named doors: read the sign, enter the right room, then confirm where you landed.

      +

      Alex: Treat examples as spoken recipes, not decorations. You may hear something like 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. Read the command, understand what it changes, then run it only when the repository state matches the lesson.

      +

      Jamie: Let's pause on Reverse the process. What should a learner take away from it?

      +

      Alex: Start with Reverse the process. There is something to understand, something to try, and something that proves the try worked.

      +

      Alex: First, focus the file in "Staged Changes". Then, press Ctrl+Enter (Mac: Cmd+Enter) or Space. After that, file moves back to "Changes". The rhythm is simple: orient, act, verify, then continue.

      -

      Jamie: How should a learner choose a tool without feeling judged by the choice?

      -

      Alex: This is where 4B. Always-On Instructions - AGENTS.md (Multi-Tool / Monorepo) becomes real: what it is: An open standard instruction file recognized by multiple AI tools - GitHub Copilot, Claude Code, Gemini CLI, and others. That matters in practice: Use this instead of copilot-instructions.md when you want one instruction file that works across all AI coding assistants.

      -

      Alex: That connects to another useful point. Keep the learner anchored in 4C. Always-On Instructions - CLAUDE.md (Cross-Tool Compatibility). What it is: Instructions file originally from Claude Code that VS Code Copilot also recognizes. This is the part to say slowly: When to use: Mixed AI tool environments where Claude Code and VS Code Copilot are both used. A good GitHub workflow is like a well-run meeting: everyone knows the topic, the next action, and who has the floor.

      -

      Jamie: Where do you want a learner to place their attention here?

      -

      Alex: The reason Supported locations matters is that enable/disable: Set chat.useClaudeMdFile: true (default: on). That gives the learner a simple foothold: claude Rules format (for.claude/rules/ and /.claude/rules/).

      +

      Alex: Keep the teaching thread moving. Start with Learning Cards: Staging Changes. There is something to understand, something to try, and something that proves the try worked.

      +

      Alex: The practical takeaway is this. 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. 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.

      +

      Jamie: Let's pause on Standard process. What should a learner take away from it?

      +

      Alex: Start with Standard process. There is something to understand, something to try, and something that proves the try worked.

      +

      Alex: First, open Source Control: Ctrl+Shift+G (Mac: Cmd+Shift+G). Then, stage changes (see Section 4). After that, focus the commit message input (usually Tab or Shift+Tab to reach it). Finally, type your commit message. Treat it like a recipe: do not add the next ingredient until the previous one is actually in the bowl.

      +

      Jamie: Before we leave Standard process, what is the practical point?

      +

      Alex: First, press Ctrl+Enter (Mac: Cmd+Enter) to commit. It is a checklist, but a meaningful one: every item creates evidence that the next step is safe.

      +

      Jamie: Let's pause on Learning Cards: Committing. What should a learner take away from it?

      +

      Alex: This is where Learning Cards: Committing becomes real: low vision users (zoom, high contrast).

      +

      Alex: First, open Source Control (Ctrl+Shift+G). Then, stage your files (click the + icon next to each file, or click Stage All Changes above the Changes section header). After that, click in the "Message" text area at the top of the Source Control panel. Finally, type your commit message. It is a checklist, but a meaningful one: every item creates evidence that the next step is safe.

      +

      Jamie: Before we leave Learning Cards: Committing, what is the practical point?

      +

      Alex: First, click the Commit button (checkmark icon) or press Ctrl+Enter. Then, 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. After that, 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. Finally, 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. It is like walking a hallway with named doors: read the sign, enter the right room, then confirm where you landed.

      -

      Alex: Here is the practical turn. Start with 4D. Conditional / Scoped Instructions -.instructions.md: What it is: Instructions that apply only when specific file types or folders are involved in the chat. The next useful detail is this: More targeted than always-on instructions.

      -

      Jamie: Give me the version that sounds like an instructor, not a manual.

      -

      Alex: Start with Create an instructions file. There is something to understand, something to try, and something that proves the try worked.

      -

      Alex: Here is what that changes in practice. Ctrl+Shift+P → "Chat: New Instructions File" → choose scope (Workspace or User). Or create the file manually in.github/instructions/.

      -

      Alex: Keep the thread going. This is where 4E. Organization-Level Instructions (GitHub Enterprise and Teams) becomes real: what it is: Organization administrators define custom instructions that apply to all repositories in the organization. That matters in practice: Every team member automatically gets these instructions added to their Copilot context. The workshop is closer to rehearsal than lecture. You hear the move, try the move, and then check what changed.

      +

      Jamie: Before we leave NVDA/JAWS, what is the practical point?

      +

      Alex: The practical takeaway is this. 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).

      +

      Alex: Keep the teaching thread moving. Start with VoiceOver. There is something to understand, something to try, and something that proves the try worked.

      +

      Alex: The practical takeaway is this. 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.

      +

      Jamie: Let's pause on Writing Good Commit Messages. What should a learner take away from it?

      +

      Alex: Start with Writing Good Commit Messages: See Culture & Etiquette: Writing Good Commit Messages for format guidance.

      -

      Jamie: If I am listening before the workshop starts, what should settle in my mind first?

      -

      Alex: Keep the learner anchored in Requirements. Use for: Organization-wide coding standards, security policies, legal disclaimers (open source license obligations), toolchain conventions.

      -

      Alex: That becomes easier when you listen for these cues. GitHub Enterprise or Teams plan with Copilot enabled. Admin configures instructions in organization settings on GitHub.com. Each user must enable discovery in VS Code.

      -

      Alex: Another way to ground it. The reason 4F. Settings-Based Instructions (Deprecated - Use Files Instead) matters is that these settings-based instructions are deprecated and may be removed in a future VS Code release. That gives the learner a simple foothold: for new work, use copilot-instructions.md or.instructions.md files.

      -

      Jamie: How should someone choose between those options?

      -

      Alex: Start with 4G. Comparison - When to Use Each Approach. There is something to understand, something to try, and something that proves the try worked.

      -

      Alex: Use the comparison to make a decision, not to recite a table. The main contrasts are: Approach means Always-on? means Multi-tool? means Best. copilot-instructions.md means Workspace means VS Code only means Primary project instructions. AGENTS.md means Workspace + monorepo means All AI tools means Multi-tool teams or large monorepos.

      -
      -

      Alex: This is the part worth saying out loud. Start with Learning Cards: Custom Instructions. There is something to understand, something to try, and something that proves the try worked.

      -

      Alex: The practical anchors are these. The three-level scope hierarchy (Organization, Workspace, User) means instructions can come from multiple places -- use Chat Diagnostics (gear icon in Chat header) to list every loaded instruction file and its source.github/copilot-instructions.md is always-on and requires no frontmatter -- just write plain Markdown; screen readers read the source file like any other Markdown document.instructions.md files use YAML frontmatter with applyTo globs -- the frontmatter is the first few lines between --- delimiters; arrow through carefully to verify syntax. The Diagnostics panel (Chat gear, then Diagnostics) lists loaded files in a scrollable pane -- increase font size in VS Code settings if the file paths are hard to read. YAML frontmatter is indentation-sensitive -- enable VS Code's indentation guides (editor.guides.indentation) and use a high-contrast theme so the guide lines are visible. The /init command auto-generates copilot-instructions.md from your workspace -- review the generated file in your editor at your preferred zoom before committing.

      -

      Jamie: Let's pause on 6. Accessible View Workflow. What should a learner take away from it?

      -

      Alex: This is where 6. Accessible View Workflow becomes real: Copilot Chat responses stream in token by token, which can fragment screen reader announcements. That matters in practice: Accessible View (Alt+F2) gives you a complete, static, properly structured version of the response.

      -

      Jamie: What should happen before anyone copies and runs it?

      -

      Alex: Keep the learner anchored in Recommended Workflow - Every Copilot Interaction. VS Code December 2025: The Accessible View now streams dynamically. This is the part to say slowly: You can open it immediately after sending a prompt and follow the response as it arrives - no need to wait for the response to finish before pressing Alt+F2.

      -

      Alex: Treat examples as spoken recipes, not decorations. You may hear something like Open Copilot Chat: Ctrl+Shift+I; 2. Type your prompt; 3. Press Ctrl+Enter to send; 4. Press Alt+F2 to open Accessible View (open immediately - no need to wait); 5. Follow as the response streams in the Accessible View in real-time; 6. Read or re-read any part. Read the command, understand what it changes, then run it only when the repository state matches the lesson.

      +

      Jamie: Let's pause on Format. What should a learner take away from it?

      +

      Alex: Here is the plain-English version of Format. Common types: feat:, fix:, docs:, style:, refactor:, test:, chore.

      +

      Alex: The practical takeaway is this. First line: type + colon + short summary (50 characters max). Blank line. Optional body: detailed explanation. Optional footer: "Fixes 123" to link to issue.

      +

      Alex: Treat examples as spoken recipes, not decorations. You may hear something like 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. Read the command, understand what it changes, then run it only when the repository state matches the lesson.

      +

      Jamie: Let's pause on What Happens After Commit. What should a learner take away from it?

      +

      Alex: Start with What Happens After Commit. There is something to understand, something to try, and something that proves the try worked.

      +

      Alex: The practical takeaway is this. 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).

      +

      Alex: Keep the teaching thread moving. Keep the learner anchored in 6. Push and Pull Operations. Push sends your local commits to GitHub. This is the part to say slowly: Pull downloads new commits from GitHub to your local repository. A good GitHub workflow is like a well-run meeting: everyone knows the topic, the next action, and who has the floor.

      -

      Jamie: Let's pause on NVDA / JAWS. What should a learner take away from it?

      -

      Alex: Start with NVDA / JAWS. There is something to understand, something to try, and something that proves the try worked.

      -

      Alex: The parts worth keeping in working memory are these. Up/Down Arrow - read line by line. Ctrl+Home - jump to start. H - navigate by headings (if response has sections). Escape - close Accessible View, return to Chat.

      -

      Alex: Hold that next to this. Start with VoiceOver. There is something to understand, something to try, and something that proves the try worked.

      -

      Alex: On the ground, that means a few things. VO+Shift+Down - interact with the Accessible View content. Down Arrow - read line by line. VO+Escape - stop interacting. Escape - close Accessible View.

      -

      Jamie: What is the safe way to learn from that example?

      -

      Alex: Here is the plain-English version of Accessible View for Inline Suggestions. When a multi-line ghost text suggestion appears in the editor. Put another way, this is especially important for multi-line suggestions where ghost text is hard to review incrementally.

      -

      Alex: Treat examples as spoken recipes, not decorations. You may hear something like Do not accept immediately; 2. Press Alt+F2; 3. Accessible View shows: "Suggestion: [full text]"; 4. Read the complete suggestion at your own pace; 5. Press Escape to close; 6. Press Tab to accept, or Escape to reject. Read the command, understand what it changes, then run it only when the repository state matches the lesson.

      +

      Jamie: Let's pause on After committing locally. What should a learner take away from it?

      +

      Alex: Start with After committing locally. There is something to understand, something to try, and something that proves the try worked.

      +

      Alex: First, open Source Control: Ctrl+Shift+G (Mac: Cmd+Shift+G). Then, look for the "Publish Branch" button (if this is a new branch) or "Sync Changes" button. After that, press Enter on that button. The rhythm is simple: orient, act, verify, then continue.

      +

      Jamie: Let's pause on Alternative: Command Palette. What should a learner take away from it?

      +

      Alex: Start with Alternative: Command Palette. There is something to understand, something to try, and something that proves the try worked.

      +

      Alex: First, ctrl+Shift+P (Mac: Cmd+Shift+P). Then, type "git push". After that, select "Git: Push". Finally, VS Code pushes your commits to GitHub. Think of it as a rail line: each stop confirms you are still on the right route before the next one.

      +

      Jamie: Let's pause on Learning Cards: Push and Pull. What should a learner take away from it?

      +

      Alex: Here is the plain-English version of Learning Cards: Push and Pull. Low vision users (zoom, high contrast). Put another way, screen reader users (NVDA / JAWS on Windows).

      +

      Alex: First, 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. Then, 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. After that, 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. Finally, 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. Treat it like a recipe: do not add the next ingredient until the previous one is actually in the bowl.

      -

      Alex: Keep the teaching thread moving. Start with Accessible View for Code Blocks. There is something to understand, something to try, and something that proves the try worked.

      -

      Alex: The room should hear these as checkpoints. Code blocks appear inside elements in Accessible View. Screen readers announce "code block" or "pre-formatted text" at the start. Each line is on its own line (not run together). Indentation is preserved.

      -

      Jamie: Let's pause on Learning Cards: Accessible View Workflow. What should a learner take away from it?

      -

      Alex: Start with Learning Cards: Accessible View Workflow. There is something to understand, something to try, and something that proves the try worked.

      -

      Alex: A few details make that real. Press Alt+F2 immediately after sending a prompt -- Accessible View now streams dynamically so you can follow along in real time. Navigate Chat responses with Up/Down Arrow; headings, code blocks, and lists are structurally intact in the view. For inline suggestions, press Alt+F2 to read the full ghost text, then Ctrl+/ to insert it directly from the Accessible View. Accessible View renders Chat responses as a static, scrollable pane -- easier to read at high zoom than the streaming Chat panel. Code blocks in Accessible View preserve indentation and syntax -- pair with a high-contrast theme for maximum readability. Ctrl+Home jumps to the start of the response; Ctrl+End to the end -- useful for long multi-section outputs.

      -

      Alex: Keep the teaching thread moving. The reason 7. Configuration Scope Reference matters is that every Copilot customization file lives at one of three scopes. That gives the learner a simple foothold: VS Code combines all matching files from all scopes - it is additive, not winner-takes-all. The interface gets friendlier when it stops being a wall of controls and starts being a set of named places.

      +

      Jamie: Let's pause on Pushing. What should a learner take away from it?

      +

      Alex: Start with Pushing. There is something to understand, something to try, and something that proves the try worked.

      +

      Alex: First, after committing, press Ctrl+Shift+P, type "git push", select "Git: Push". Then, NVDA/JAWS announces "Pushing." in the status bar. After that, on success, a notification appears: "Successfully pushed" - if using NVDA, check NVDA+N to read recent notifications. Finally, for a new branch (first push), use "Git: Publish Branch" instead - this sets up the upstream tracking. It is a checklist, but a meaningful one: every item creates evidence that the next step is safe.

      +

      Jamie: Let's pause on Pulling. What should a learner take away from it?

      +

      Alex: Start with Pulling. There is something to understand, something to try, and something that proves the try worked.

      +

      Alex: First, press Ctrl+Shift+P, type "git pull", select "Git: Pull". Then, NVDA/JAWS announces "Pulling." then the status changes. After that, if there are conflicts, the Source Control panel shows a "Merge Changes" section - navigate there with Ctrl+Shift+G then Down Arrow. It is like walking a hallway with named doors: read the sign, enter the right room, then confirm where you landed.

      +

      Jamie: Let's pause on Checking sync status. What should a learner take away from it?

      +

      Alex: The reason Checking sync status matters is that screen reader users (VoiceOver on macOS).

      +

      Alex: First, press Ctrl+Shift+P, type "Git: Show Git Output". Then, the output pane opens with push/pull log messages in plain text. After that, use Up/Down Arrow to read line by line. The rhythm is simple: orient, act, verify, then continue.

      -

      Jamie: Let's pause on Workspace (Repository) - Team-Shared. What should a learner take away from it?

      -

      Alex: Start with Workspace (Repository) - Team-Shared: Files committed to your repository. The next useful detail is this: Everyone who clones the repo gets them.

      -

      Alex: Keep the teaching thread moving. Here is the plain-English version of User / Personal - Follows You Across Workspaces. Files in your VS Code profile folder. Put another way, available in every workspace you open.

      -

      Jamie: Let's pause on Organization - GitHub-Configured (Enterprise/Teams). What should a learner take away from it?

      -

      Alex: This is where Organization - GitHub-Configured (Enterprise/Teams) becomes real: configured by administrators in GitHub organization settings. That matters in practice: Automatically applied to all organization members.

      -

      Alex: That shows up in the workshop in a few specific ways. Enable discovery: github.copilot.chat.organizationInstructions.enabled: true. Lowest priority - workspace and user instructions override when there is a conflict.

      +

      Jamie: Before we leave Pushing, what is the practical point?

      +

      Alex: First, press Cmd+Shift+P, type "git push", select "Git: Push". Then, VoiceOver announces progress from the status bar. After that, on success, a notification toast appears - press VO+F3 to read the latest notification. Think of it as a rail line: each stop confirms you are still on the right route before the next one.

      +

      Jamie: Before we leave Pulling, what is the practical point?

      +

      Alex: First, press Cmd+Shift+P, type "git pull", select "Git: Pull". Then, VoiceOver announces when the pull completes. After that, if conflicts exist, navigate to Source Control (Cmd+Shift+G) and review the Merge Changes section. Treat it like a recipe: do not add the next ingredient until the previous one is actually in the bowl.

      +

      Jamie: Let's pause on Screen reader feedback. What should a learner take away from it?

      +

      Alex: This is where Screen reader feedback becomes real: Git CLI alternative - push and pull. That matters in practice: Web alternative (github.com) - push and pull.

      +

      Alex: The practical takeaway is this. 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).

      +

      Alex: Treat examples as spoken recipes, not decorations. You may hear something like 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. Read the command, understand what it changes, then run it only when the repository state matches the lesson.

      -

      Alex: Keep the teaching thread moving. Keep the learner anchored in 8. Instruction Priority and Conflicts. When multiple instruction sources give conflicting guidance, VS Code uses this priority order. This is the part to say slowly: This priority applies to conflicts. A good GitHub workflow is like a well-run meeting: everyone knows the topic, the next action, and who has the floor.

      -

      Jamie: Let's pause on How Instructions Are Combined. What should a learner take away from it?

      -

      Alex: The reason How Instructions Are Combined matters is that result: Copilot follows TypeScript strict mode (from workspace), British English (from org), AND the Z-spelling override (from user, which overrides the org instruction on that specific point).

      -

      Alex: For a learner, the useful signals are these. Organization: "Use British English spellings". Workspace: "Use TypeScript strict mode". User: "Use British English spellings - but use Z spellings (organize, not organise) for technical terms".

      -

      Alex: Keep the teaching thread moving. Start with Priority Within the Same Scope: Within a single scope (e.g., workspace), all matching instructions files are combined with no inherent priority. The next useful detail is this: If two workspace-level.instructions.md files contradict each other, the behavior is undefined - avoid conflicting workspace instructions.

      +

      Alex: Keep the teaching thread moving. Start with What to do if push fails. There is something to understand, something to try, and something that proves the try worked.

      +

      Alex: The practical takeaway is this. 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). Error: "Rejected - non-fast-forward" → Someone else pushed changes; you need to pull first.

      +

      Jamie: Let's pause on When to pull. What should a learner take away from it?

      +

      Alex: Start with When to pull. There is something to understand, something to try, and something that proves the try worked.

      +

      Alex: The practical takeaway is this. Before you start work each day. When GitHub shows your branch is behind the remote. When preparing to merge a PR.

      +

      Jamie: Let's pause on How to pull. What should a learner take away from it?

      +

      Alex: Start with How to pull: If there are conflicts: See Section 9. Think of it like entering a new building: first you find the lobby, then the room, then the door you actually need.

      +

      Alex: First, ctrl+Shift+P (Mac: Cmd+Shift+P). Then, type "git pull". After that, select "Git: Pull". Finally, VS Code fetches and merges remote changes. Think of it as a rail line: each stop confirms you are still on the right route before the next one.

      -

      Jamie: Let's pause on Create any new customization file. What should a learner take away from it?

      -

      Alex: Here is the plain-English version of Create any new customization file. Ctrl+Shift+P → "Chat: New Instructions File" (or "New Prompt File", "New Agent File").

      -

      Alex: Keep the teaching thread moving. This is where 10. VS Code Settings Reference becomes real: all Copilot customization-related settings. That matters in practice: Set in VS Code Settings (Ctrl+,) or settings.json. The workshop is closer to rehearsal than lecture. You hear the move, try the move, and then check what changed.

      -

      Jamie: Let's pause on Deprecated Task-Specific Instructions. What should a learner take away from it?

      -

      Alex: Keep the learner anchored in Deprecated Task-Specific Instructions. Prefer file-based instructions over these settings for new work. This is the part to say slowly: Each accepts an array with items: { "text": "." } (inline) or { "file": "relative/path" } (from file).

      +

      Jamie: Let's pause on Auto-fetch setting. What should a learner take away from it?

      +

      Alex: Start with Auto-fetch setting. There is something to understand, something to try, and something that proves the try worked.

      +

      Alex: The practical takeaway is this. VS Code can check for remote changes automatically every few minutes. Enable: Settings (Ctrl+, - Mac: Cmd+,) → search "git autofetch" → set to true.

      +

      Alex: Keep the teaching thread moving. This is where Syncing Your Fork with the Upstream Repository becomes real: when you fork a repository and the original (upstream) repository receives new commits, your fork gets out of date. That matters in practice: Keeping your fork current prevents merge conflicts and ensures you're working with the latest code.

      +

      Jamie: Let's pause on The GitHub "Sync fork" Button (Quickest Method). What should a learner take away from it?

      +

      Alex: Keep the learner anchored in The GitHub "Sync fork" Button (Quickest Method). For straightforward updates, GitHub has a built-in sync button.

      +

      Alex: First, navigate to your fork on GitHub. Then, on the repository page, look for the "This branch is N commits behind owner/repo:main" notice. After that, activate the "Sync fork" button next to it. Finally, GitHub automatically merges upstream changes into your fork's default branch. It is like walking a hallway with named doors: read the sign, enter the right room, then confirm where you landed.

      +

      Jamie: Before we leave The GitHub "Sync fork" Button (Quickest Method), what is the practical point?

      +

      Alex: First, then pull those changes to your local clone: Git: Pull from the Command Palette. The rhythm is simple: orient, act, verify, then continue.

      -

      Jamie: What is the ordered workflow?

      -

      Alex: The reason Settings Sync matters is that to sync your personal prompts, instructions, and agents across devices. That gives the learner a simple foothold: your personal.instructions.md,.agent.md, and.prompt.md files will sync to all signed-in VS Code instances.

      -

      Alex: First, ctrl+Shift+P → "Settings Sync: Turn On". Then, ctrl+Shift+P → "Settings Sync: Configure". After that, check "Prompts and Instructions". The rhythm is simple: orient, act, verify, then continue.

      -

      Jamie: Give me the sequence, because order matters here.

      -

      Alex: Start with View All Loaded Customizations: To see which instruction files, agents, prompts, and skills are currently loaded - and check for errors.

      -

      Alex: The practical takeaway is this. All agents found and whether they loaded successfully. All prompt/instruction files and their source (workspace vs user vs organization). All skills and their discovery status. Any parse errors or invalid frontmatter.

      -

      Alex: First, configure Chat Gear: Click the gear () icon in the Copilot Chat header → "Diagnostics". Then, right-click method: Right-click in the Chat view → "Diagnostics". Think of it as a rail line: each stop confirms you are still on the right route before the next one.

      -

      Jamie: What does the learner do first, second, and then after that?

      -

      Alex: Start with copilot-instructions.md not being followed. There is something to understand, something to try, and something that proves the try worked.

      -

      Alex: First, confirm the file is at exactly.github/copilot-instructions.md (relative to workspace root). Then, check the file is plain Markdown with no frontmatter syntax errors. After that, open Diagnostics to confirm it appears in the loaded files list. Finally, some instructions work better with specific phrasing; use imperative mood ("Always use."). Treat it like a recipe: do not add the next ingredient until the previous one is actually in the bowl.

      +

      Alex: Keep the teaching thread moving. The reason Screen reader path matters is that limitation: The GitHub sync button only syncs the default branch. That gives the learner a simple foothold: for other branches, use the git method below. The interface gets friendlier when it stops being a wall of controls and starts being a set of named places.

      +

      Jamie: Let's pause on Adding the Upstream Remote (One-Time Setup). What should a learner take away from it?

      +

      Alex: Start with Adding the Upstream Remote (One-Time Setup): To sync locally using git, you first configure the upstream remote. The next useful detail is this: This only needs to be done once per clone.

      +

      Alex: Treat examples as spoken recipes, not decorations. You may hear something like 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. Read the command, understand what it changes, then run it only when the repository state matches the lesson.

      +

      Jamie: Let's pause on Example for Accessibility Agents. What should a learner take away from it?

      +

      Alex: Start with Example for Accessibility Agents. There is something to understand, something to try, and something that proves the try worked.

      +

      Alex: Treat examples as spoken recipes, not decorations. You may hear something like git remote add upstream https://github.com/community-access/accessibility-agents.git. Read the command, understand what it changes, then run it only when the repository state matches the lesson.

      -

      Jamie: Turn that into a path someone can follow.

      -

      Alex: Start with.instructions.md file not loading automatically. There is something to understand, something to try, and something that proves the try worked.

      -

      Alex: First, verify chat.includeApplyingInstructions is not set to false. Then, check the applyTo glob - test with " " temporarily to confirm the file loads at all. After that, confirm the file is in.github/instructions/ or a folder listed in chat.instructionsFilesLocations. Finally, file extension must be.instructions.md exactly - not.md, not.instruction.md. It is a checklist, but a meaningful one: every item creates evidence that the next step is safe.

      -

      Jamie: Let's pause on Custom agent (@agent-name) not appearing. What should a learner take away from it?

      -

      Alex: Start with Custom agent (@agent-name) not appearing. There is something to understand, something to try, and something that proves the try worked.

      -

      Alex: First, file must be named.agent.md and placed in.github/agents/. Then, check YAML frontmatter for syntax errors - use a YAML validator. After that, confirm user-invocable is not set to false (which hides it from the picker). Finally, run Ctrl+Shift+P → "Reload Window" after any changes to agent files. It is like walking a hallway with named doors: read the sign, enter the right room, then confirm where you landed.

      -

      Jamie: Let's pause on Slash command (/command) not appearing. What should a learner take away from it?

      -

      Alex: Start with Slash command (/command) not appearing. There is something to understand, something to try, and something that proves the try worked.

      -

      Alex: First, file must be at.github/prompts/.prompt.md. Then, extension must be.prompt.md exactly. After that, reload VS Code: Ctrl+Shift+P → "Reload Window". The rhythm is simple: orient, act, verify, then continue.

      +

      Jamie: Let's pause on Fetching and Merging Upstream Changes. What should a learner take away from it?

      +

      Alex: This is where Fetching and Merging Upstream Changes becomes real: once your upstream remote is configured.

      +

      Alex: Treat examples as spoken recipes, not decorations. You may hear something like 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. Read the command, understand what it changes, then run it only when the repository state matches the lesson.

      +

      Alex: Keep the teaching thread moving. Keep the learner anchored in When Conflicts Occur During Sync. See also: Chapter 07: Merge Conflicts for a dedicated walkthrough of conflict resolution. This is the part to say slowly: If you've made changes to the same files the upstream has changed, merge conflicts can occur during sync. A good GitHub workflow is like a well-run meeting: everyone knows the topic, the next action, and who has the floor.

      +

      Jamie: Let's pause on 7. Discarding Changes. What should a learner take away from it?

      +

      Alex: The reason 7. Discarding Changes matters is that discarding = permanently deleting your local edits. That gives the learner a simple foothold: the file reverts to the state of the last commit.

      -

      Jamie: Let's pause on Instructions from different files conflicting. What should a learner take away from it?

      -

      Alex: Start with Instructions from different files conflicting. There is something to understand, something to try, and something that proves the try worked.

      -

      Alex: First, open Diagnostics to see all loaded instruction files. Then, remove or edit conflicting instructions - they are not automatically de-duplicated. After that, user-level instructions override workspace instructions for the same topic. Think of it as a rail line: each stop confirms you are still on the right route before the next one.

      -

      Jamie: Let's pause on chat.instructionsFilesLocations not working. What should a learner take away from it?

      -

      Alex: Start with chat.instructionsFilesLocations not working. There is something to understand, something to try, and something that proves the try worked.

      -

      Alex: The practical takeaway is this. Path must be a folder path, not a file path. Use forward slashes or escaped backslashes. Relative paths are relative to the workspace root.

      -

      Alex: Keep the teaching thread moving. This is where 12. Screen Reader Workflow - Official Guide becomes real: source: accessibility.github.com/documentation/guide/github-copilot-vsc/ Contributors: @mlama007, zersiax Community: GitHub Accessibility Discussions.

      +

      Alex: Keep the teaching thread moving. Start with When to Discard. There is something to understand, something to try, and something that proves the try worked.

      +

      Alex: The practical takeaway is this. You made experimental changes and they didn't work. You want to start over from the last commit. You accidentally edited the wrong file.

      +

      Jamie: Let's pause on Single file. What should a learner take away from it?

      +

      Alex: Start with Single file. There is something to understand, something to try, and something that proves the try worked.

      +

      Alex: First, open Source Control: Ctrl+Shift+G. Then, navigate to the file in "Changes". After that, press Shift+F10 for context menu. Finally, select "Discard Changes". Treat it like a recipe: do not add the next ingredient until the previous one is actually in the bowl.

      +

      Jamie: Before we leave Single file, what is the practical point?

      +

      Alex: First, confirm in the warning dialog (VS Code will ask "Are you sure?"). It is a checklist, but a meaningful one: every item creates evidence that the next step is safe.

      +

      Jamie: Let's pause on All changes. What should a learner take away from it?

      +

      Alex: This is where All changes becomes real: screen reader warning: VS Code shows a modal confirmation dialog. That matters in practice: Navigate with Tab, select "Discard" or "Cancel" with Enter. The workshop is closer to rehearsal than lecture. You hear the move, try the move, and then check what changed.

      +

      Alex: First, ctrl+Shift+G. Then, navigate to the "Changes" section heading. After that, shift+F10 for context menu. Finally, select "Discard All Changes". It is a checklist, but a meaningful one: every item creates evidence that the next step is safe.

      +

      Jamie: Before we leave All changes, what is the practical point?

      +

      Alex: First, confirm (this affects every modified file). It is like walking a hallway with named doors: read the sign, enter the right room, then confirm where you landed.

      -

      Jamie: Let's pause on Prerequisites. What should a learner take away from it?

      -

      Alex: Start with Prerequisites. There is something to understand, something to try, and something that proves the try worked.

      -

      Alex: The practical takeaway is this. VS Code with GitHub Copilot Chat extension installed. A GitHub account with Copilot access (Free tier or paid). A screen reader (NVDA recommended for this guide).

      -

      Jamie: Let's pause on Step 1: Enable VS Code Screen Reader Mode. What should a learner take away from it?

      -

      Alex: The reason Step 1: Enable VS Code Screen Reader Mode matters is that when Screen Reader Mode is on, VS Code changes how it announces suggestions (full text instead of streaming), adjusts live regions, and enables accessible navigation patterns throughout the editor. The interface gets friendlier when it stops being a wall of controls and starts being a set of named places.

      -

      Alex: First, press Shift+Alt+F1 to toggle Screen Reader Accessibility Mode. Then, or use Command Palette: Ctrl+Shift+P → "Toggle Screen Reader Accessibility Mode". After that, VS Code announces: "Screen Reader Accessibility Mode enabled". The rhythm is simple: orient, act, verify, then continue.

      -

      Jamie: Let's pause on Step 2: Configure Accessibility Signals (Optional but Recommended). What should a learner take away from it?

      -

      Alex: Start with Step 2: Configure Accessibility Signals (Optional but Recommended): Recommended JSON config for Copilot accessibility signals.

      -

      Alex: First, open Settings: Ctrl+,. Then, search "accessibility signals". After that, enable the Copilot-specific signals. Think of it as a rail line: each stop confirms you are still on the right route before the next one.

      +

      Jamie: Let's pause on Learning Cards: Discarding Changes. What should a learner take away from it?

      +

      Alex: Keep the learner anchored in Learning Cards: Discarding Changes. Low vision users (zoom, high contrast). This is the part to say slowly: Screen reader users (NVDA / JAWS on Windows).

      +

      Alex: First, 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.". Then, 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. After that, for "Discard All Changes", right-click the "Changes" section heading to get the context menu. Finally, 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"). It is like walking a hallway with named doors: read the sign, enter the right room, then confirm where you landed.

      +

      Jamie: What is the teaching move inside Single file?

      +

      Alex: First, press Ctrl+Shift+G to open Source Control. Then, navigate to the file in the Changes section with Down Arrow. After that, press Shift+F10 to open the context menu. Finally, navigate to "Discard Changes" with Down Arrow, press Enter. The rhythm is simple: orient, act, verify, then continue.

      +

      Jamie: If someone only remembers one thing from Single file, what should it be?

      +

      Alex: First, a confirmation dialog appears - NVDA announces "Are you sure you want to discard changes" or similar. Then, press Tab to navigate between "Discard" and "Cancel", press Enter on your choice. Think of it as a rail line: each stop confirms you are still on the right route before the next one.

      +

      Jamie: Let's pause on All files. What should a learner take away from it?

      +

      Alex: Start with All files: Screen reader users (VoiceOver on macOS). The next useful detail is this: Discard changes from your terminal.

      +

      Alex: First, navigate to the "Changes" section heading (announced as "Changes, expanded, N items"). Then, press Shift+F10, select "Discard All Changes". After that, confirm in the dialog. Finally, press Cmd+Shift+G to open Source Control. Think of it as a rail line: each stop confirms you are still on the right route before the next one.

      +

      Jamie: Before we leave All files, what is the practical point?

      +

      Alex: First, use VO+Arrow keys to navigate to the file. Then, press VO+Shift+M to open the context menu (or Ctrl+Return). After that, navigate to "Discard Changes", press VO+Space. Finally, in the confirmation dialog, use VO+Right Arrow to reach the buttons, VO+Space to activate. Treat it like a recipe: do not add the next ingredient until the previous one is actually in the bowl.

      +

      Alex: Treat examples as spoken recipes, not decorations. You may hear something like 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. Read the command, understand what it changes, then run it only when the repository state matches the lesson.

      -

      Alex: Keep the teaching thread moving. Here is the plain-English version of Step 3: Official Shortcut Table (from accessibility.github.com). This is the complete table of Copilot screen reader shortcuts as published by the GitHub Accessibility team.

      -

      Jamie: How do you keep commands from becoming magic words?

      -

      Alex: This is where The screen reader-optimized workflow for every inline suggestion becomes real: this workflow avoids the streaming announcement problem (where suggestions are read out in fragments as tokens arrive) and gives you full, uninterrupted access to the suggestion text before committing.

      -

      Alex: Treat examples as spoken recipes, not decorations. You may hear something like Type your code or documentation; 2. Copilot generates a suggestion (audio cue sounds if enabled); 3. DO NOT press Tab immediately; 4. Press Alt+F2 - Accessible View opens with the full suggestion text; 5. Read the suggestion at your own pace with Arrow keys. Read the command, understand what it changes, then run it only when the repository state matches the lesson.

      -

      Jamie: Let's pause on Step 5: Recommended Workflow for Chat Responses. What should a learner take away from it?

      -

      Alex: Start with Step 5: Recommended Workflow for Chat Responses. There is something to understand, something to try, and something that proves the try worked.

      -

      Alex: Treat examples as spoken recipes, not decorations. You may hear something like Open Chat: Ctrl+Shift+I; 2. Type your prompt, press Ctrl+Enter to send; 3. Press Alt+F2 - Accessible View opens immediately; the response streams live into it; 4. Navigate with Arrow keys - no streaming noise, follow along in real-time; 5. Headings, code. Read the command, understand what it changes, then run it only when the repository state matches the lesson.

      +

      Alex: Keep the teaching thread moving. Here is the plain-English version of 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. Put another way, stash saves your changes temporarily without committing them. It is like learning a transit route. The names of the stops matter because they tell you whether you are still going the right direction.

      +

      Jamie: Let's pause on Deleting a File from the Repository (Git Delete / git rm). What should a learner take away from it?

      +

      Alex: This is where Deleting a File from the Repository (Git Delete / git rm) becomes real: Git Delete removes a file from both your working directory AND Git's tracking. That matters in practice: This is different from discarding changes - it permanently removes the file from the repository history going forward.

      +

      Jamie: Let's pause on How to use. What should a learner take away from it?

      +

      Alex: Keep the learner anchored in How to use. The file is staged for deletion - you still need to commit to record the removal.

      +

      Alex: First, open the file you want to remove in the editor. Then, ctrl+Shift+P (Mac: Cmd+Shift+P). After that, type "Git: Delete". Finally, confirm the deletion. It is like walking a hallway with named doors: read the sign, enter the right room, then confirm where you landed.

      -

      Jamie: Let's pause on Reading the Suggestions Panel (Ctrl+Enter). What should a learner take away from it?

      -

      Alex: The reason Reading the Suggestions Panel (Ctrl+Enter) matters is that pressing Ctrl+Enter opens a Suggestions Panel - a separate editor tab that shows up to 10 alternative suggestions simultaneously. That gives the learner a simple foothold: this is useful when the default suggestion isn't quite right and you want to compare options.

      -

      Alex: Treat examples as spoken recipes, not decorations. You may hear something like Ctrl+Enter - opens "GitHub Copilot" editor tab; 2. Screen Reader Mode is active: navigate with Browse Mode; 3. H key to navigate headings (each suggestion may be under a heading); 4. Press Alt+F2 on a focused suggestion to read it in Accessible View; 5. Tab to. Read the command, understand what it changes, then run it only when the repository state matches the lesson.

      -

      Alex: Keep the teaching thread moving. Start with Learning Cards: Screen Reader Copilot Workflow. There is something to understand, something to try, and something that proves the try worked.

      -

      Alex: The practical takeaway is this. The golden rule: never accept a suggestion with Tab before reviewing it -- press Alt+F2 first, read it, then Ctrl+/ to insert. Enable the four Copilot audio signals (inline suggestion, request sent, response pending, response received) for non-verbal status awareness. Ctrl+Enter opens a Suggestions Panel with up to 10 alternatives -- navigate with H for headings, then Tab to the Accept button. Inline ghost text is typically rendered in a muted color -- if hard to see, rely on the lineHasInlineSuggestion audio signal instead. The Suggestions Panel (Ctrl+Enter) shows alternatives in a full editor tab at your current font size and theme. Chat responses are easier to read in Accessible View than in the streaming panel, especially at high zoom.

      -

      Jamie: Let's pause on 13. awesome-copilot - Plugin Ecosystem. What should a learner take away from it?

      -

      Alex: Here is the plain-English version of 13. awesome-copilot - Plugin Ecosystem. awesome-copilot is a GitHub repository (github/awesome-copilot) - not a VS Code Marketplace extension. Put another way, it is GitHub's curated ecosystem of Copilot plugins, prompts, instructions, agents, skills, and hooks that can be shared and discovered by anyone.

      +

      Jamie: Let's pause on When to use Git Delete vs. just deleting the file. What should a learner take away from it?

      +

      Alex: Start with When to use Git Delete vs. just deleting the file. There is something to understand, something to try, and something that proves the try worked.

      +

      Alex: The practical takeaway is this. 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.

      +

      Jamie: Let's pause on Learning Cards: Deleting a File from the Repository. What should a learner take away from it?

      +

      Alex: Start with Learning Cards: Deleting a File from the Repository: Alternatively: Ctrl+Shift+P then "Git: Delete" removes the file and stages the deletion in one step. The next useful detail is this: Low vision users (zoom, high contrast). Think of it like entering a new building: first you find the lobby, then the room, then the door you actually need.

      +

      Alex: First, right-click the file in the Explorer panel (Ctrl+Shift+E). Then, select "Delete" to delete from your file system. After that, the file appears in Source Control (Ctrl+Shift+G) under Changes with a "D" (deleted) status. Finally, stage and commit the deletion to record it in Git. Think of it as a rail line: each stop confirms you are still on the right route before the next one.

      +

      Jamie: Before we leave Learning Cards: Deleting a File from the Repository, what is the practical point?

      +

      Alex: First, 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. Then, 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. After that, stage and commit as normal. Finally, open the file you want to remove in the editor. Treat it like a recipe: do not add the next ingredient until the previous one is actually in the bowl.

      +

      Alex: Treat examples as spoken recipes, not decorations. You may hear something like 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. Read the command, understand what it changes, then run it only when the repository state matches the lesson.

      +

      Jamie: Let's pause on 8. Timeline View - File History and Blame. What should a learner take away from it?

      +

      Alex: Here is the plain-English version of 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.

      -

      Alex: Keep the teaching thread moving. This is where Repository Structure becomes real: lLM discovery: https://github.github.io/awesome-copilot/llms.txt - a machine-readable index of all available resources. The workshop is closer to rehearsal than lecture. You hear the move, try the move, and then check what changed.

      -

      Jamie: Let's pause on The /plugin Command - Browse and Install from Chat. What should a learner take away from it?

      -

      Alex: Keep the learner anchored in The /plugin Command - Browse and Install from Chat. The easiest way to explore awesome-copilot from VS Code.

      -

      Alex: First, open Copilot Chat (Ctrl+Shift+I). Then, type /plugin and press Enter. After that, Copilot Chat opens an interactive plugin marketplace browser. Finally, browse plugins by category, read descriptions, and install with a single command. It is like walking a hallway with named doors: read the sign, enter the right room, then confirm where you landed.

      -

      Jamie: Let's pause on CLI Plugin Installation. What should a learner take away from it?

      -

      Alex: The reason CLI Plugin Installation matters is that from any terminal with GitHub CLI (gh) installed.

      -

      Alex: Treat examples as spoken recipes, not decorations. You may hear something like Browse the marketplace; gh copilot plugin marketplace list; Add the awesome-copilot collection; gh copilot plugin marketplace add github/awesome-copilot; Install a specific plugin; gh copilot plugin install @awesome-copilot/accessibility-toolkit; List what you. Read the command, understand what it changes, then run it only when the repository state matches the lesson.

      +

      Jamie: Let's pause on Method 1: Explorer Sidebar. What should a learner take away from it?

      +

      Alex: Start with Method 1: Explorer Sidebar. There is something to understand, something to try, and something that proves the try worked.

      +

      Alex: First, open Explorer: Ctrl+Shift+E. Then, at the bottom of the Explorer, there's a "Timeline" section. After that, tab or Arrow to navigate into Timeline. Finally, the list shows all commits affecting the currently open file. It is a checklist, but a meaningful one: every item creates evidence that the next step is safe.

      +

      Jamie: Let's pause on Method 2: Command Palette. What should a learner take away from it?

      +

      Alex: Start with Method 2: Command Palette. There is something to understand, something to try, and something that proves the try worked.

      +

      Alex: First, open a file in the editor. Then, ctrl+Shift+P. After that, type "timeline". Finally, select "View: Show Timeline". It is like walking a hallway with named doors: read the sign, enter the right room, then confirm where you landed.

      +

      Alex: Keep the teaching thread moving. The reason What Timeline Shows matters is that screen reader announcement: "docs: add Timeline Guide, Jeff, 2 days ago". The interface gets friendlier when it stops being a wall of controls and starts being a set of named places.

      +

      Alex: The practical takeaway is this. Commit message (first line). Author name. Relative time (example: "3 days ago" or "2 hours ago"). Commit hash (short form, like a3f2b9c).

      -

      Jamie: Let's pause on MCP Server Integration (Docker required). What should a learner take away from it?

      -

      Alex: Start with MCP Server Integration (Docker required): awesome-copilot also ships as an MCP (Model Context Protocol) Server - a Docker-based tool server that extends Copilot with additional capabilities beyond file-based customizations. The next useful detail is this: Install in VS Code by clicking the button at https://aka.ms/awesome-copilot/mcp/vscode, or add manually to settings.json.

      -

      Alex: Treat examples as spoken recipes, not decorations. You may hear something like {; "mcp": {; "servers": {; "awesome-copilot": {; "type": "stdio",; "command": "docker",; "args": [; "run", "-i", "--rm",; "ghcr.io/github/awesome-copilot-mcp:latest"; ]; }; }; }; }. Read the command, understand what it changes, then run it only when the repository state matches the lesson.

      -

      Alex: Keep the teaching thread moving. Here is the plain-English version of 14. GitHub Agentic Workflows - Agents in the Cloud. Status: Technical Preview - GitHub Agentic Workflows entered technical preview on February 13, 2026. Put another way, as of May 2026 the feature remains in active development and preview; changes to the API and workflow format are ongoing. It is like learning a transit route. The names of the stops matter because they tell you whether you are still going the right direction.

      -

      Jamie: Let's pause on What This Enables. What should a learner take away from it?

      -

      Alex: This is where What This Enables becomes real: browse 50+ community-built workflows at Peli's Agent Factory.

      +

      Jamie: Let's pause on Viewing a Commit's Changes. What should a learner take away from it?

      +

      Alex: Start with Viewing a Commit's Changes: This is incredibly useful for understanding.

      +

      Alex: The practical takeaway is this. When a particular line was added. Why a section was removed. What the file looked like at any point in history.

      +

      Alex: First, navigate to a commit in the Timeline list. Then, press Enter. After that, a diff view opens showing what changed in that specific commit. Think of it as a rail line: each stop confirms you are still on the right route before the next one.

      +

      Alex: Keep the teaching thread moving. Here is the plain-English version of Git Blame - Line-by-Line History. Git Blame shows who last modified each line of the file.

      +

      Jamie: Let's pause on How to access. What should a learner take away from it?

      +

      Alex: Start with How to access. There is something to understand, something to try, and something that proves the try worked.

      +

      Alex: First, open a file in the editor. Then, ctrl+Shift+P. After that, type "git blame". Finally, select "Git: Toggle Blame". It is a checklist, but a meaningful one: every item creates evidence that the next step is safe.

      -

      Alex: Keep the teaching thread moving. Keep the learner anchored in How It Works. The gh aw CLI (a gh extension) compiles.md workflow files into.lock.yml GitHub Actions workflows. This is the part to say slowly: The AI agent (GitHub Copilot, Claude, or OpenAI Codex) reads your repository context and the natural language instructions, then performs the task using the GitHub MCP Server and other available tools.

      -

      Jamie: Let's pause on Workflow Format - Markdown with Frontmatter. What should a learner take away from it?

      -

      Alex: The reason Workflow Format - Markdown with Frontmatter matters is that unlike standard GitHub Actions (YAML), agentic workflows are Markdown files. That gives the learner a simple foothold: the body is natural language - describe what you want the AI agent to do.

      -

      Alex: Keep the teaching thread moving. Start with Security Model - "Safe Outputs": Workflows run read-only by default with sandboxed execution, network isolation, and SHA-pinned dependencies. The next useful detail is this: Write operations require explicit declaration in safe-outputs - a set of pre-approved, sanitized GitHub operations. Think of it like entering a new building: first you find the lobby, then the room, then the door you actually need.

      +

      Alex: Keep the teaching thread moving. Start with What appears. There is something to understand, something to try, and something that proves the try worked.

      +

      Alex: The practical takeaway is this. Inline annotations next to every line (visually). Hover over a line to see commit details.

      +

      Jamie: Let's pause on For screen reader users. What should a learner take away from it?

      +

      Alex: The reason For screen reader users matters is that useful blame settings (add to.vscode/settings.json or user Settings).

      +

      Alex: The practical takeaway is this. 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.

      +

      Jamie: Let's pause on Learning Cards: Timeline and History. What should a learner take away from it?

      +

      Alex: Start with Learning Cards: Timeline and History: Low vision users (zoom, high contrast). The next useful detail is this: Screen reader users (NVDA / JAWS on Windows).

      +

      Alex: First, 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. Then, 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. After that, 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. Finally, 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. Think of it as a rail line: each stop confirms you are still on the right route before the next one.

      -

      Jamie: Let's pause on Getting Started with gh aw. What should a learner take away from it?

      -

      Alex: Start with Getting Started with gh aw. There is something to understand, something to try, and something that proves the try worked.

      -

      Alex: Treat examples as spoken recipes, not decorations. You may hear something like Install the CLI extension; gh extension install github/gh-aw; Create a new workflow interactively (from github.com or VS Code also works); gh aw create; Compile your Markdown workflow to a GitHub Actions.lock.yml; gh aw. Read the command, understand what it changes, then run it only when the repository state matches the lesson.

      -

      Jamie: Let's pause on Monitoring Agentic Workflow Runs. What should a learner take away from it?

      -

      Alex: Start with Monitoring Agentic Workflow Runs. There is something to understand, something to try, and something that proves the try worked.

      -

      Alex: First, navigate to the Actions tab of your repository (D → Repository navigation → K to Actions). Then, find the workflow by name (h3 headings, navigate with 3). After that, press Enter to open a specific run. Finally, expand job steps to read the agent output log and any safe-outputs created. It is a checklist, but a meaningful one: every item creates evidence that the next step is safe.

      -

      Jamie: Let's pause on Resources. What should a learner take away from it?

      -

      Alex: Keep the learner anchored in Resources. Relationship to Accessibility Agents: Accessibility Agents agents (.agent.md files) are designed for interactive use inside VS Code. This is the part to say slowly: GitHub Agentic Workflows are a separate, cloud-native system that uses its own Markdown workflow format and the gh aw CLI - they are complementary tools, not the same mechanism.

      +

      Jamie: Let's pause on Opening Timeline. What should a learner take away from it?

      +

      Alex: Start with Opening Timeline. There is something to understand, something to try, and something that proves the try worked.

      +

      Alex: First, press Ctrl+Shift+E to open Explorer. Then, press Tab repeatedly or Down Arrow to navigate past the file tree to the "Timeline" section. After that, press Right Arrow to expand it if collapsed. Finally, navigate commit entries with Up/Down Arrow. Treat it like a recipe: do not add the next ingredient until the previous one is actually in the bowl.

      +

      Jamie: Before we leave Opening Timeline, what is the practical point?

      +

      Alex: First, each entry is announced as: "commit message, author, time" (e.g., "docs: add Timeline Guide, Jeff, 2 days ago"). Then, press Enter on any entry to open its diff view. It is a checklist, but a meaningful one: every item creates evidence that the next step is safe.

      +

      Jamie: Let's pause on Reading a diff with screen reader. What should a learner take away from it?

      +

      Alex: Start with Reading a diff with screen reader. There is something to understand, something to try, and something that proves the try worked.

      +

      Alex: First, in the diff view, press Alt+F2 to open the Accessible Diff Viewer. Then, the Accessible Diff Viewer presents changes as a text list: each line shows + (added), - (removed), or unchanged. After that, navigate with Up/Down Arrow to read each line. Finally, press Escape to close the Accessible Diff Viewer. It is a checklist, but a meaningful one: every item creates evidence that the next step is safe.

      +

      Jamie: Let's pause on Git Blame. What should a learner take away from it?

      +

      Alex: Keep the learner anchored in Git Blame. Screen reader users (VoiceOver on macOS).

      +

      Alex: First, open a file, press Ctrl+Shift+P, type "Git: Toggle Blame". Then, blame annotations appear inline - NVDA reads them when navigating lines. After that, to reduce noise, disable blame (repeat the toggle command) and use Timeline instead. It is like walking a hallway with named doors: read the sign, enter the right room, then confirm where you landed.

      -

      Alex: Keep the teaching thread moving. Start with Learning Cards: GitHub Agentic Workflows. There is something to understand, something to try, and something that proves the try worked.

      -

      Alex: The practical takeaway is this. Agentic workflow runs appear in the Actions tab of your repository -- navigate to Actions with T (tab bar), then use heading navigation (3) to jump between workflow run entries. Workflow files are Markdown (.md) not YAML -- the frontmatter at the top controls triggers and permissions; the body is natural language instructions the AI agent reads. The safe-outputs frontmatter property lists every write operation the agent is allowed to perform -- review this section carefully since it is the security boundary. The Actions tab lists workflow runs with status icons (green check, red X, yellow circle) -- at high zoom, also look for the text status label next to each run name. Workflow.md files use the same Markdown rendering as any other file in the repo -- edit them in VS Code with your preferred font size and theme. The gh aw compile command generates a.lock.yml file alongside your.md file -- both appear in the file explorer; the.lock.yml is auto-generated and should not be edited manually.

      -

      Jamie: Let's pause on Copilot Models. What should a learner take away from it?

      -

      Alex: Start with Copilot Models. There is something to understand, something to try, and something that proves the try worked.

      -

      Alex: The practical takeaway is this. Overview. How to Choose a Model. Complete Model Reference. Model Availability by Plan. Premium Requests and Cost Multipliers. Switching Models in VS Code.

      -

      Alex: Keep the teaching thread moving. Here is the plain-English version of 1. Overview. GitHub Copilot offers access to AI models from multiple providers including OpenAI, Anthropic, Google, and xAI. Put another way, the model you choose affects response quality, speed, and premium request consumption.

      +

      Jamie: What is the teaching move inside Opening Timeline?

      +

      Alex: First, press Cmd+Shift+E to open Explorer. Then, use VO+Down Arrow to navigate below the file tree to the Timeline section. After that, press VO+Space to expand if collapsed. Finally, navigate entries with VO+Down Arrow. The rhythm is simple: orient, act, verify, then continue.

      +

      Jamie: If someone only remembers one thing from Opening Timeline, what should it be?

      +

      Alex: First, press VO+Space on a commit to open its diff. Think of it as a rail line: each stop confirms you are still on the right route before the next one.

      +

      Jamie: Let's pause on Accessible Diff Viewer. What should a learner take away from it?

      +

      Alex: Start with Accessible Diff Viewer: Screen reader advantage: git log --oneline and git blame produce clean, columnar text output. The next useful detail is this: Read line by line with arrow keys in the terminal.

      +

      Alex: First, in any diff view, press Option+F2 to open the Accessible Diff Viewer. Then, read changes line by line with VO+Down Arrow. After that, press Escape to close. Think of it as a rail line: each stop confirms you are still on the right route before the next one.

      +

      Alex: Treat examples as spoken recipes, not decorations. You may hear something like 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. 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. Read the command, understand what it changes, then run it only when the repository state matches the lesson.

      +

      Alex: Keep the teaching thread moving. Here is the plain-English version of 9. Resolving Merge Conflicts in VS Code. Merge conflicts happen when two people edit the same lines of a file. Put another way, Git can't decide which version to keep, so it asks you to choose. It is like learning a transit route. The names of the stops matter because they tell you whether you are still going the right direction.

      -

      Jamie: Let's pause on 2. How to Choose a Model. What should a learner take away from it?

      -

      Alex: This is where 2. How to Choose a Model becomes real: GitHub Docs organizes models by task. That matters in practice: Match your task to the right model to get the best results without unnecessary premium request cost.

      -

      Alex: Keep the teaching thread moving. Keep the learner anchored in General-Purpose Coding and Writing. For everyday tasks - code completions, explanations, refactoring, writing documentation. A good GitHub workflow is like a well-run meeting: everyone knows the topic, the next action, and who has the floor.

      -

      Jamie: How should someone ask for help in a way that gets them unstuck faster?

      -

      Alex: The reason Fast Help with Simple or Repetitive Tasks matters is that for quick answers, boilerplate generation, renaming, or lightweight explanations where speed matters.

      +

      Jamie: There are a lot of tools in play. How do we keep that from feeling like a contest?

      +

      Alex: This is where How VS Code Displays Conflicts becomes real: when you open a file with conflicts, you see something like. That matters in practice: VS Code adds buttons above each conflict (visually).

      +

      Alex: The practical takeaway is this. "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).

      +

      Jamie: Let's pause on Screen Reader Workflow for Resolving Conflicts. What should a learner take away from it?

      +

      Alex: Keep the learner anchored in Screen Reader Workflow for Resolving Conflicts. The buttons are NOT accessible via keyboard.

      +

      Alex: The practical takeaway is this. <<<<<<< marks the start. ======= separates the two versions. marks the end. The section between <<<<<<< and ======= is your current branch (HEAD). The section between ======= and is the incoming branch (the branch you're merging). Delete the conflict markers ( ).

      +

      Alex: First, identify the conflict markers. Then, read both versions. After that, decide what to keep. Finally, stage the resolved file. It is like walking a hallway with named doors: read the sign, enter the right room, then confirm where you landed.

      +

      Jamie: Before we leave Screen Reader Workflow for Resolving Conflicts, what is the practical point?

      +

      Alex: First, commit the merge. The rhythm is simple: orient, act, verify, then continue.

      +

      Jamie: Let's pause on Using Accessible Diff for Conflict Review. What should a learner take away from it?

      +

      Alex: The reason Using Accessible Diff for Conflict Review matters is that better approach: Use the Accessible Diff Viewer (F7) to navigate conflict hunks systematically.

      +

      Alex: First, open the conflicted file. Then, press F7 to jump to the first conflict hunk. After that, press Alt+F2 to open Accessible View. Finally, read both versions clearly. The rhythm is simple: orient, act, verify, then continue.

      +

      Jamie: Before we leave Using Accessible Diff for Conflict Review, what is the practical point?

      +

      Alex: First, press Escape to return to editor. Then, manually edit to resolve. After that, press F7 to jump to the next conflict. Finally, repeat until all conflicts resolved. Think of it as a rail line: each stop confirms you are still on the right route before the next one.

      -

      Alex: Keep the teaching thread moving. Start with Deep Reasoning and Debugging: For complex problems, architecture decisions, multi-file analysis, tricky bugs, and understanding unfamiliar codebases.

      -

      Jamie: Let's pause on Agentic Software Development. What should a learner take away from it?

      -

      Alex: Here is the plain-English version of Agentic Software Development. For autonomous coding tasks in Agent mode - when Copilot writes code, runs terminal commands, and iterates without step-by-step guidance from you.

      -

      Alex: Keep the teaching thread moving. This is where Working with Visuals becomes real: for tasks that involve images, screenshots, diagrams, or UI mockups - paste an image directly into the chat input. The workshop is closer to rehearsal than lecture. You hear the move, try the move, and then check what changed.

      +

      Jamie: Let's pause on Aborting a Merge. What should a learner take away from it?

      +

      Alex: Start with Aborting a Merge: If you want to cancel the merge and go back to before you started. The next useful detail is this: Everything returns to the pre-merge state. Think of it like entering a new building: first you find the lobby, then the room, then the door you actually need.

      +

      Alex: First, ctrl+Shift+P. Then, type "git abort". After that, select "Git: Abort Merge". Think of it as a rail line: each stop confirms you are still on the right route before the next one.

      +

      Jamie: Let's pause on Learning Cards: Resolving Merge Conflicts. What should a learner take away from it?

      +

      Alex: Start with Learning Cards: Resolving Merge Conflicts. There is something to understand, something to try, and something that proves the try worked.

      +

      Alex: The practical takeaway is this. 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. 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.

      +

      Alex: Keep the teaching thread moving. This is where 10. Stash Management becomes real: stash temporarily saves your uncommitted changes so you can switch branches or pull updates without committing half-finished work.

      -

      Jamie: Let's pause on 3. Complete Model Reference. What should a learner take away from it?

      -

      Alex: Keep the learner anchored in 3. Complete Model Reference. Model availability changes frequently. This is the part to say slowly: Check GitHub's supported models page for the current list.

      -

      Alex: Keep the teaching thread moving. The reason 4. Model Availability by Plan matters is that GitHub Copilot plan details and billing models are actively evolving. That gives the learner a simple foothold: facilitators will provide current guidance at the workshop.

      -

      Jamie: Let's pause on Tips for managing premium request usage. What should a learner take away from it?

      -

      Alex: Start with Tips for managing premium request usage. There is something to understand, something to try, and something that proves the try worked.

      -

      Alex: The practical takeaway is this. Use GPT-4.1 or GPT-5 mini (both free) for everyday questions, quick explanations, and simple completions - they're fast and capable. Upgrade to Claude Sonnet or GPT-5.2 (1×) only when the task genuinely requires deeper reasoning. Save Claude Opus (3×) for the most demanding analyses - architecture decisions, complex debugging, sophisticated design review. Use Auto mode (see below) and let Copilot allocate model selection intelligently.

      +

      Jamie: Let's pause on When to Use Stash. What should a learner take away from it?

      +

      Alex: Start with When to Use Stash. There is something to understand, something to try, and something that proves the try worked.

      +

      Alex: The practical takeaway is this. 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.

      +

      Jamie: Let's pause on Method 1: Command Palette. What should a learner take away from it?

      +

      Alex: Start with Method 1: Command Palette. There is something to understand, something to try, and something that proves the try worked.

      +

      Alex: First, ctrl+Shift+P. Then, type "git stash". After that, select "Git: Stash". Finally, optionally type a stash message (helps you remember what's in it). The rhythm is simple: orient, act, verify, then continue.

      +

      Jamie: Let's pause on What happens. What should a learner take away from it?

      +

      Alex: Start with What happens. There is something to understand, something to try, and something that proves the try worked.

      +

      Alex: The practical takeaway is this. 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.

      -

      Jamie: Let's pause on In the Chat Panel. What should a learner take away from it?

      -

      Alex: Start with In the Chat Panel. There is something to understand, something to try, and something that proves the try worked.

      -

      Alex: First, open the Chat panel (Ctrl+Shift+I / Cmd+Shift+I). Then, at the bottom of the chat input area, you'll see the current model name as a button (e.g., "Auto" or "Claude Sonnet 4.6"). After that, activate the model picker button - this opens a dropdown list of available models. Finally, arrow through the list and press Enter to select a model. Treat it like a recipe: do not add the next ingredient until the previous one is actually in the bowl.

      -

      Jamie: Before we leave In the Chat Panel, what is the practical point?

      -

      Alex: First, for screen reader users: the chat input will announce the newly selected model after switching. It is a checklist, but a meaningful one: every item creates evidence that the next step is safe.

      -

      Jamie: Let's pause on In an Inline Chat Session. What should a learner take away from it?

      -

      Alex: Start with In an Inline Chat Session. There is something to understand, something to try, and something that proves the try worked.

      -

      Alex: First, open Inline Chat (Ctrl+I / Cmd+I). Then, the model picker appears in the inline chat toolbar. After that, same interaction: activate the model button to switch. It is a checklist, but a meaningful one: every item creates evidence that the next step is safe.

      -

      Alex: Keep the teaching thread moving. Keep the learner anchored in Keyboard Note for Screen Readers. In the Chat panel, the model picker button is near the bottom of the chat view. This is the part to say slowly: If you're having trouble locating it.

      -

      Alex: The practical takeaway is this. Tab through the bottom toolbar of the chat panel. Listen for the model name announced - it appears between the "Attach" button and the send button. Press Space or Enter to open the picker.

      +

      Jamie: Let's pause on Command Palette. What should a learner take away from it?

      +

      Alex: Start with Command Palette. There is something to understand, something to try, and something that proves the try worked.

      +

      Alex: First, ctrl+Shift+P. Then, type "git stash list". After that, select "Git: Show Stash". Treat it like a recipe: do not add the next ingredient until the previous one is actually in the bowl.

      +

      Jamie: Let's pause on Alternative: Integrated Terminal. What should a learner take away from it?

      +

      Alex: Start with Alternative: Integrated Terminal. There is something to understand, something to try, and something that proves the try worked.

      +

      Alex: Treat examples as spoken recipes, not decorations. You may hear something like git stash list. Read the command, understand what it changes, then run it only when the repository state matches the lesson.

      +

      Jamie: Let's pause on To restore your stashed changes. What should a learner take away from it?

      +

      Alex: Start with To restore your stashed changes. There is something to understand, something to try, and something that proves the try worked.

      +

      Alex: First, ctrl+Shift+P. Then, type "git stash apply". After that, select "Git: Apply Latest Stash". It is like walking a hallway with named doors: read the sign, enter the right room, then confirm where you landed.

      -

      Jamie: Let's pause on 7. Auto Model Selection. What should a learner take away from it?

      -

      Alex: The reason 7. Auto Model Selection matters is that auto mode (the default) lets Copilot choose the best model based on the type of request. That gives the learner a simple foothold: it became generally available on December 10, 2025.

      -

      Alex: Keep the teaching thread moving. Start with How Auto works. There is something to understand, something to try, and something that proves the try worked.

      -

      Alex: The practical takeaway is this. For simple questions, Copilot routes to a faster, lighter model. For complex code generation or debugging, Copilot upgrades to a more capable model automatically. For agent tasks, Copilot selects an appropriate Codex model. You can see which model was used after each response.

      -

      Jamie: Let's pause on When to override Auto. What should a learner take away from it?

      -

      Alex: Here is the plain-English version of When to override Auto. To switch back to Auto from a specific model, re-open the model picker and select Auto at the top of the list.

      -

      Alex: The practical takeaway is this. You specifically need a model with certain capabilities (e.g., vision input with Claude Sonnet 4). You're managing premium request quotas and want to control costs. You've found a particular model gives better results for your specific workflow or domain. You're doing agentic work and want to explicitly select an agent-optimized Codex model (check current availability in the model picker).

      +

      Jamie: Let's pause on Or to apply a specific stash. What should a learner take away from it?

      +

      Alex: Start with Or to apply a specific stash. There is something to understand, something to try, and something that proves the try worked.

      +

      Alex: First, ctrl+Shift+P. Then, type "git stash pop". After that, select "Git: Pop Stash.". Finally, choose which stash from the list. The rhythm is simple: orient, act, verify, then continue.

      +

      Alex: Keep the teaching thread moving. Start with Difference between Apply and Pop. There is something to understand, something to try, and something that proves the try worked.

      +

      Alex: The practical takeaway is this. Apply: restores changes and keeps the stash (you can apply it again later). Pop: restores changes and deletes the stash.

      +

      Jamie: Let's pause on Dropping a Stash. What should a learner take away from it?

      +

      Alex: Here is the plain-English version of Dropping a Stash. If you no longer need what's in a stash.

      +

      Alex: First, ctrl+Shift+P. Then, type "git stash drop". After that, select "Git: Drop Stash.". Finally, choose which stash to delete. Treat it like a recipe: do not add the next ingredient until the previous one is actually in the bowl.

      -

      Alex: Keep the teaching thread moving. This is where 8. Models Retiring Soon becomes real: GitHub regularly updates the model roster. That matters in practice: Older model versions are retired when newer equivalents are available.

      -

      Jamie: Let's pause on Already retired (as of April 2026). What should a learner take away from it?

      -

      Alex: Keep the learner anchored in Already retired (as of April 2026). To stay current, watch the GitHub Copilot changelog - model additions and retirements are announced there.

      -

      Alex: The practical takeaway is this. Claude Sonnet 3.5, Claude Sonnet 3.7. Gemini 2.0 Flash. o1-mini, o3, o3-mini, o4-mini. Claude Opus 4.1. GPT-5 (base), GPT-5-Codex. GPT-5.3-Codex (removed from Student plan model picker, April 2026).

      -

      Alex: Keep the teaching thread moving. The reason Related Resources matters is that next: Appendix L: Agents Reference Back: Appendix J: Codespaces Teaching chapter: Chapter 16: GitHub Copilot. The interface gets friendlier when it stops being a wall of controls and starts being a set of named places.

      +

      Jamie: Let's pause on Learning Cards: Stash Management. What should a learner take away from it?

      +

      Alex: This is where Learning Cards: Stash Management becomes real: if the Stashes section is not visible, use the Command Palette: Ctrl+Shift+P then type "git stash" to access all stash commands. That matters in practice: Low vision users (zoom, high contrast). The workshop is closer to rehearsal than lecture. You hear the move, try the move, and then check what changed.

      +

      Alex: First, open Source Control: Ctrl+Shift+G. Then, in the Source Control panel, there may be a "Stashes" section below Staged Changes (visible when stashes exist). After that, click a stash to see what it contains. Finally, right-click a stash to Apply, Pop, or Drop it. It is a checklist, but a meaningful one: every item creates evidence that the next step is safe.

      +

      Jamie: Before we leave Learning Cards: Stash Management, what is the practical point?

      +

      Alex: First, 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. Then, 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. After that, after applying a stash, your files reappear in the Changes section of Source Control. Check the file count to confirm. It is like walking a hallway with named doors: read the sign, enter the right room, then confirm where you landed.

      +

      Jamie: Let's pause on Creating a stash. What should a learner take away from it?

      +

      Alex: Start with Creating a stash. There is something to understand, something to try, and something that proves the try worked.

      +

      Alex: First, press Ctrl+Shift+P, type "git stash". Then, select "Git: Stash" - NVDA announces the result. After that, an input appears asking for a stash message - type something descriptive (e.g., "WIP: documentation changes for Timeline section"). Finally, press Enter - your changes disappear from Source Control and are saved in the stash. It is like walking a hallway with named doors: read the sign, enter the right room, then confirm where you landed.

      +

      Jamie: Before we leave Creating a stash, what is the practical point?

      +

      Alex: First, NVDA announces the Source Control panel update (file counts drop to 0). The rhythm is simple: orient, act, verify, then continue.

      +

      Jamie: Let's pause on Applying a stash. What should a learner take away from it?

      +

      Alex: Start with Applying a stash. There is something to understand, something to try, and something that proves the try worked.

      +

      Alex: First, press Ctrl+Shift+P, type "git stash pop". Then, select "Git: Pop Stash.". After that, a list of stashes appears - navigate with Up/Down Arrow. Finally, each item is announced with the stash message you wrote. The rhythm is simple: orient, act, verify, then continue.

      +

      Jamie: Before we leave Applying a stash, what is the practical point?

      +

      Alex: First, press Enter to apply and delete the stash. Then, your changes reappear in the Changes section. Think of it as a rail line: each stop confirms you are still on the right route before the next one.

      -

      Jamie: What should people carry with them after this?

      -

      Alex: Carry the map. Know what page or tool you are in, know which action you are taking, and know what confirmation should follow. If the confirmation is missing, pause. That pause is not wasted time; it is professional judgment.

      -

      Jamie: That is a better way to say it than just follow the steps.

      -

      Alex: Right. Steps matter, but understanding wins. That is episode 41. Next in the series is episode 42, where we keep building the same contributor muscles.

      +

      Jamie: Let's pause on Viewing stashes. What should a learner take away from it?

      +

      Alex: Start with Viewing stashes: Screen reader users (VoiceOver on macOS). The next useful detail is this: GitHub.com does not have a stash feature.

      +

      Alex: First, press Ctrl+Shift+P, type "git stash list". Then, or in the terminal: type git stash list and read the output line by line. After that, press Cmd+Shift+P, type "git stash". Finally, select "Git: Stash" and provide a message. Think of it as a rail line: each stop confirms you are still on the right route before the next one.

      +

      Jamie: Before we leave Viewing stashes, what is the practical point?

      +

      Alex: First, press Return. Then, to apply: Cmd+Shift+P, type "git stash pop", select from the list with VO+Down Arrow, press Return. After that, create a draft commit on a temporary branch. Finally, or use GitHub Codespaces (which runs a full VS Code environment in the browser and supports git stash in the terminal). Treat it like a recipe: do not add the next ingredient until the previous one is actually in the bowl.

      +

      Alex: Treat examples as spoken recipes, not decorations. You may hear something like 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. Read the command, understand what it changes, then run it only when the repository state matches the lesson.

      +

      Alex: Keep the teaching thread moving. Here is the plain-English version of 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. Put another way, it is the most underused recovery tool in Git. It is like learning a transit route. The names of the stops matter because they tell you whether you are still going the right direction.

      +

      Jamie: Can you translate that into plain choices?

      +

      Alex: Start with When to Use Reflog. There is something to understand, something to try, and something that proves the try worked.

      +

      Alex: Use the comparison to make a decision, not to recite a table. The main contrasts are: Scenario means What happened means Reflog solution. Deleted a branch by mistake means git branch -D feature/x means Find the last commit SHA from reflog → recreate branch. git reset --hard lost commits means Moved HEAD to older commit means Find the SHA before the reset → reset back to it.

      +
      +

      Jamie: Let's pause on Reading the Reflog in VS Code Terminal. What should a learner take away from it?

      +

      Alex: Keep the learner anchored in Reading the Reflog in VS Code Terminal. Run this in the integrated terminal (Ctrl+Backtick). This is the part to say slowly: The output is plain text - read line by line with ↓.

      +

      Alex: Treat examples as spoken recipes, not decorations. You may hear something like git reflog. Read the command, understand what it changes, then run it only when the repository state matches the lesson.

      +

      Jamie: Let's pause on If you need to restore a commit that has been lost. What should a learner take away from it?

      +

      Alex: The reason If you need to restore a commit that has been lost matters is that 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.

      +

      Alex: Treat examples as spoken recipes, not decorations. You may hear something like 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. Read the command, understand what it changes, then run it only when the repository state matches the lesson.

      +

      Jamie: Let's pause on Recovering a Deleted Branch. What should a learner take away from it?

      +

      Alex: Start with Recovering a Deleted Branch. There is something to understand, something to try, and something that proves the try worked.

      +

      Alex: Treat examples as spoken recipes, not decorations. You may hear something like 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. Read the command, understand what it changes, then run it only when the repository state matches the lesson.

      +
      +

      Jamie: Let's pause on Why Reflog Is Local-Only. What should a learner take away from it?

      +

      Alex: Here is the plain-English version of Why Reflog Is Local-Only. Reflog records are stored in your local.git/ directory and are not pushed to GitHub. Put another way, 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.

      +

      Alex: Keep the teaching thread moving. Start with Learning Cards: Emergency Recovery. There is something to understand, something to try, and something that proves the try worked.

      +

      Alex: The practical takeaway is this. 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. 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.

      +

      Jamie: Let's pause on 11. Alternative Git Interfaces. What should a learner take away from it?

      +

      Alex: Keep the learner anchored in 11. Alternative Git Interfaces. VS Code's Source Control panel is one way to use Git. This is the part to say slowly: These alternatives exist for different workflows.

      +
      +

      Alex: Keep the teaching thread moving. Start with GitHub Desktop. There is something to understand, something to try, and something that proves the try worked.

      +

      Alex: The practical takeaway is this. Graphical Git client. Download: 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.

      +

      Jamie: Let's pause on GitHub CLI (gh). What should a learner take away from it?

      +

      Alex: Start with GitHub CLI (gh). There is something to understand, something to try, and something that proves the try worked.

      +

      Alex: The practical takeaway is this. 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).

      +

      Jamie: Let's pause on Common commands. What should a learner take away from it?

      +

      Alex: Here is the plain-English version of Common commands. See Culture & Etiquette for more gh examples.

      +

      Alex: Treat examples as spoken recipes, not decorations. You may hear something like 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. Read the command, understand what it changes, then run it only when the repository state matches the lesson.

      +
      +

      Jamie: Let's pause on Git CLI (Terminal). What should a learner take away from it?

      +

      Alex: Start with Git CLI (Terminal). There is something to understand, something to try, and something that proves the try worked.

      +

      Alex: The practical takeaway is this. The standard Git command-line interface. Included with VS Code (integrated terminal: Ctrl+Backtick).

      +

      Jamie: Before we leave Common commands, what is the practical point?

      +

      Alex: Keep the learner anchored in Common commands. Terminal output is plain text - more predictable than GUI elements for some operations. A good GitHub workflow is like a well-run meeting: everyone knows the topic, the next action, and who has the floor.

      +

      Alex: Treat examples as spoken recipes, not decorations. You may hear something like 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. Read the command, understand what it changes, then run it only when the repository state matches the lesson.

      +

      Jamie: Let's pause on Try It: Clone, Branch, Commit. What should a learner take away from it?

      +

      Alex: The reason Try It: Clone, Branch, Commit matters is that time: 5 minutes What you need: VS Code with Git configured. That gives the learner a simple foothold: do the complete Git workflow once, start to finish.

      +

      Alex: First, 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. Then, 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. After that, 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. Finally, stage - Press Ctrl+Shift+G to open Source Control. Navigate to your changed file and press Enter to stage it (or use the + button). The rhythm is simple: orient, act, verify, then continue.

      +

      Jamie: Before we leave Try It: Clone, Branch, Commit, what is the practical point?

      +

      Alex: First, commit - Tab to the message input, type feat: add new thinking phrase, press Ctrl+Enter. Then, push - Press Ctrl+Shift+P → Git: Push. Think of it as a rail line: each stop confirms you are still on the right route before the next one.

      +
      +

      Jamie: What is the final checkpoint?

      +

      Alex: You should be able to point to the evidence, explain the action, and describe what you would do next if this were a real open source project. If you can teach the move back, you have learned it.

      +

      Jamie: And if they get stuck?

      +

      Alex: Read the latest message, not the loudest worry. Check the issue, the branch, the pull request, the status check, or the bot comment. Then ask for help with those facts in hand. That is how professionals collaborate.

      -

      Episode 42: Accessing Workshop Materials

      -

      Downloading the repository, reading offline, keeping updated, audio format.

      -

      Based on: Appendix Y: Accessing Workshop Materials

      +

      36. Challenge bonus-e: Git History

      +

      Reading history, understanding commits over time, and using history as a learning tool.

      +

      Practice focus: Bonus

      Audio and transcript are being regenerated for this episode.

      -Read Transcript - Episode 42: Accessing Workshop Materials +Read Transcript - Challenge bonus-e: Git History

      Transcript

      -

      Alex: This is Git Going with GitHub, episode 42: Accessing Workshop Materials. I am Alex. By the end of this episode, Accessing Workshop Materials should feel less like a wall of GitHub words and more like a set of moves you can trust.

      -

      Jamie: And I am Jamie. I am here for the practical questions: what should I listen for, what can go wrong, and what is the next calm move?

      +

      Alex: This is Challenge Coach for Git History. I am Alex, and we are going to teach the move before asking you to prove it.

      +

      Jamie: And I am Jamie. I will translate the challenge into the practical questions learners actually have while doing it.

      -

      Alex: Today we are working on this: Downloading the repository, reading offline, keeping updated, audio format. I want the learner to leave with a mental map, not just a remembered path through buttons.

      -

      Jamie: So the goal is understanding first, then action, then confirmation.

      -

      Alex: Right. We are building a rhythm: orient yourself, take one intentional action, then verify what changed before moving on.

      +

      Alex: Reading history, understanding commits over time, and using history as a learning tool. That is the task layer. The teaching layer is understanding why the move belongs in a contributor workflow.

      +

      Jamie: So evidence is not just proof for the facilitator. It is part of how the learner understands the workflow.

      +

      Alex: Right. A good challenge produces something inspectable: a comment, issue, branch, commit, pull request, review, or clear note about what happened.

      Jamie: Okay, set the room for us. What are we walking into?

      -

      Alex: Start with How to Get, Read, and Keep These Documents: Why this appendix exists: The workshop content is available in multiple formats - Markdown source files, pre-built HTML pages, and a live GitHub Pages site. The next useful detail is this: This guide explains how to access each format, download materials for offline use, and keep your copy up to date.

      -

      Alex: The next layer is this. Start with Learning Cards: Accessing Workshop Materials. There is something to understand, something to try, and something that proves the try worked.

      -

      Alex: The practical anchors are these. The GitHub Pages site includes skip-to-content links and ARIA landmarks -- press D (NVDA) or R (JAWS) to jump to the main content landmark on any page. On GitHub.com, press T on the repository's main page to open the file finder -- type any filename to jump directly to it without navigating the file tree. After cloning the repository, open it in VS Code and use the Explorer panel (Ctrl+Shift+E) to browse the file tree with arrow keys. The HTML version in the html/ folder provides the most polished reading experience with styled, navigable pages that work offline in any browser. For reading Markdown source files, use VS Code's built-in preview (Ctrl+Shift+V) which renders headings, links, and code blocks in a formatted view. When downloading a ZIP from GitHub, the Code button and its dropdown appear near the top of the repository page -- look for the green button.

      -

      Jamie: What does the learner do first, second, and then after that?

      -

      Alex: This is where 1. Browsing Online (GitHub Pages) becomes real: if the facilitator has enabled GitHub Pages for this repository, the workshop materials are available as a website at a URL like. That matters in practice: Your facilitator will share the exact URL.

      -

      Alex: First, open the URL in your browser. Then, the landing page (index.html) is the workshop homepage - equivalent to the README. After that, use headings (H key in NVDA/JAWS browse mode) to navigate within any page. Finally, all internal links between chapters and appendices work - click any cross-reference to go directly to that page. It is a checklist, but a meaningful one: every item creates evidence that the next step is safe.

      -

      Jamie: Turn that into a path someone can follow.

      -

      Alex: First, bookmark the URL for quick access during the workshop. It is like walking a hallway with named doors: read the sign, enter the right room, then confirm where you landed.

      -
      -

      Jamie: What is the ordered workflow?

      -

      Alex: Keep the learner anchored in 2. Reading on GitHub.com. You can read every file directly on GitHub.com without downloading anything.

      -

      Alex: First, go to the repository page (your facilitator will share the link). Then, the README renders automatically as the repository homepage. After that, click into the docs/ folder to see all chapters and appendices. Finally, click any.md file - GitHub renders it as formatted text with headings, links, and code blocks. It is like walking a hallway with named doors: read the sign, enter the right room, then confirm where you landed.

      -

      Jamie: What would you say to someone who is already bracing for this to be too much?

      -

      Alex: Start with Navigating the repository with a screen reader. There is something to understand, something to try, and something that proves the try worked.

      -

      Alex: The parts worth keeping in working memory are these. File list: The repository file listing is a grid. Use T to jump to the file table, then arrow keys to navigate rows. File content: Once inside a file, GitHub renders the Markdown. Use H to navigate headings. Breadcrumbs: At the top of each file view, breadcrumb links show the path (e.g., Learning-Room / docs / 06-working-with-pull-requests.md). Use these to navigate back. Go to File shortcut: Press T on the repository's main page to open the file finder - type any filename to jump to it.

      -

      Alex: A solid navigation habit is to prove where you are before activating controls. Headings, landmarks, and the address bar are not trivia; they are your map.

      -

      Jamie: How do you keep commands from becoming magic words?

      -

      Alex: Start with Option A: Clone with Git (recommended): Cloning gives you a full copy of the repository that you can update later with git pull. The next useful detail is this: After cloning, every file (Markdown source, HTML output, scripts, learning-room materials) is on your computer. Think of it like entering a new building: first you find the lobby, then the room, then the door you actually need.

      -

      Alex: Treat examples as spoken recipes, not decorations. You may hear something like Clone the repository; git clone https://github.com/community-access/git-going-with-github.git; Move into the folder; cd Learning-Room. Read the command, understand what it changes, then run it only when the repository state matches the lesson.

      +

      Alex: Start with Bonus E: Explore Git History Visually: For students who: Want to see branching and merging as a visual timeline. The next useful detail is this: What you will do: Use GitHub Desktop (or the GitHub.com commit graph) to explore the learning-room's Git history as a visual timeline.

      Alex: A solid Git habit is to know which branch you are on, what changed, and what confirmation you expect before you run the next command.

      -

      Jamie: How would you walk the room through that step by step?

      -

      Alex: Here is the plain-English version of Option B: Download ZIP (no Git required). If you do not have Git installed or prefer not to use the command line.

      -

      Alex: First, go to the repository page on GitHub.com. Then, press T to find the file finder, or navigate to the green Code button (it is a dropdown button near the top of the file listing). After that, activate the Code button - a dropdown menu opens. Finally, choose Download ZIP. Treat it like a recipe: do not add the next ingredient until the previous one is actually in the bowl.

      -

      Jamie: Give me the sequence, because order matters here.

      -

      Alex: First, save the file and extract it to a folder on your computer. It is a checklist, but a meaningful one: every item creates evidence that the next step is safe.

      -

      Alex: This is where the talk moves from concept to action. This is where Screen reader navigation for the Code dropdown becomes real: a ZIP download is a snapshot. That matters in practice: It does not update automatically - see Section 7 for how to get updates.

      -

      Alex: The room should hear these as checkpoints. The Code button is near the repository description, after the branch selector. In NVDA/JAWS browse mode, press B to jump between buttons until you reach "Code". Activate it with Enter or Space. The dropdown contains options including "Download ZIP" - arrow down to find it.

      +

      Alex: Start with Instructions. There is something to understand, something to try, and something that proves the try worked.

      +

      Alex: The practical anchors are these. How branches appear as parallel lines. Where merges bring lines back together. Which commits are yours vs seeded peer-simulation commits.

      +

      Alex: First, open the learning-room repository in GitHub Desktop. Then, go to the History tab. After that, explore the commit timeline. Notice. Finally, go to the learning-room repository on GitHub.com. Treat it like a recipe: do not add the next ingredient until the previous one is actually in the bowl.

      +

      Jamie: What does the learner do first, second, and then after that?

      +

      Alex: First, select Insights Network to see the branch graph. Then, or select Commits on the Code tab to see the linear history. It is a checklist, but a meaningful one: every item creates evidence that the next step is safe.

      Jamie: What is the one idea that makes the next few steps less mysterious?

      -

      Alex: Keep the learner anchored in 4. Downloading Individual Files. To download a single file (for example, one chapter or the screen reader cheat sheet).

      -

      Alex: The useful habit is simple: orient first, act second, verify third. That pause before acting is part of the work.

      +

      Alex: This is where What to observe becomes real: answer these questions as you explore.

      +

      Alex: That shows up in the workshop in a few specific ways. [ ] How many branches exist in the repository right now? [ ] Can you find your Challenge 5 commit in the history? [ ] Where does your learn/YOUR-USERNAME branch diverge from main? [ ] Can you find the merge commit from your Challenge 9 PR? [ ] What is the oldest commit in the repository?

      -

      Jamie: Let's pause on From GitHub.com. What should a learner take away from it?

      -

      Alex: The reason From GitHub.com matters is that for HTML files: Navigate to the html/ folder and download the.html version of any file using the same Raw → Save method. The interface gets friendlier when it stops being a wall of controls and starts being a set of named places.

      -

      Alex: First, navigate to the file in the repository. Then, click the Raw button (it appears above the file content, in the toolbar with "Preview", "Code", "Blame" buttons). After that, the browser shows the raw file content. Finally, press Ctrl+S (Windows/Linux) or Cmd+S (macOS) to save the page. The rhythm is simple: orient, act, verify, then continue.

      -

      Jamie: Give me the version that sounds like an instructor, not a manual.

      -

      Alex: Start with From a cloned repository: If you have already cloned the repo, every file is already on your computer. The next useful detail is this: Open the folder and copy whichever files you need.

      -

      Alex: Hold that next to this. Here is the plain-English version of 6. Offline Reading. Once you have downloaded or cloned the repository, you can read everything offline.

      +

      Jamie: Turn that into a path someone can follow.

      +

      Alex: Start with Viewing commit history. There is something to understand, something to try, and something that proves the try worked.

      +

      Alex: First, navigate to any repository. Then, click the "X commits" link near the top (shows total commit count). After that, the history page shows each commit with author, date, message, and SHA. Finally, click any commit to see what changed (green lines added, red lines removed). It is like walking a hallway with named doors: read the sign, enter the right room, then confirm where you landed.

      +

      Jamie: What would you say to someone who is already bracing for this to be too much?

      +

      Alex: The reason What you see matters is that the commit history tells the story of a project.

      +

      Alex: The parts worth keeping in working memory are these. Chronological order: Most recent commits first. Author attribution: Every change has a name attached. Commit messages: Each entry explains what changed and (ideally) why. Diffs: Click any commit to see exactly which lines were added, removed, or modified.

      +

      Alex: The useful habit is simple: orient first, act second, verify third. That pause before acting is part of the work.

      +

      Jamie: Give me the sequence, because order matters here.

      +

      Alex: Start with Visual timeline. There is something to understand, something to try, and something that proves the try worked.

      +

      Alex: First, open the repository in GitHub Desktop. Then, click the "History" tab. After that, the left panel shows commits as a timeline. Finally, click any commit to see the diff in the right panel. Think of it as a rail line: each stop confirms you are still on the right route before the next one.

      +

      Jamie: What is the ordered workflow?

      +

      Alex: First, the branch visualization shows where branches diverged and merged. Treat it like a recipe: do not add the next ingredient until the previous one is actually in the bowl.

      Jamie: If I am listening before the workshop starts, what should settle in my mind first?

      -

      Alex: This is where Reading Markdown files becomes real: they are plain text with lightweight formatting syntax. That matters in practice: VS Code renders Markdown with a preview panel (Ctrl+Shift+V).

      -

      Jamie: Let's pause on Reading HTML files. What should a learner take away from it?

      -

      Alex: Keep the learner anchored in Reading HTML files. The HTML files work the same offline as online. This is the part to say slowly: All ARIA landmarks, heading structure, and skip links are embedded in each file. A good GitHub workflow is like a well-run meeting: everyone knows the topic, the next action, and who has the floor.

      -

      Alex: First, open html/index.html in any web browser. Then, all internal links between pages work locally - no internet connection required. After that, navigate between chapters using the links at the bottom of each page. It is like walking a hallway with named doors: read the sign, enter the right room, then confirm where you landed.

      -

      Jamie: What is the pre-flight check here?

      -

      Alex: Start with Recommended offline reading setup. There is something to understand, something to try, and something that proves the try worked.

      -

      Alex: On the ground, that means a few things. VS Code with Markdown: Open the repo folder in VS Code, browse the Explorer, and read files directly in the editor. Use Ctrl+Shift+V to open the rendered preview. Browser with HTML: Open html/index.html and navigate from there - this gives the most polished reading experience.

      -
      -

      Jamie: What should happen before anyone copies and runs it?

      -

      Alex: Start with If you cloned with Git: If you have not made local changes, this updates your copy cleanly. The next useful detail is this: If you have local edits, Git will attempt to merge - see Chapter 7 - Merge Conflicts if needed.

      -

      Alex: Treat examples as spoken recipes, not decorations. You may hear something like Navigate to your local copy; cd Learning-Room; Pull the latest changes; git pull. npm run build:html. Read the command, understand what it changes, then run it only when the repository state matches the lesson.

      +

      Alex: Start with Key observations from exploring history. There is something to understand, something to try, and something that proves the try worked.

      +

      Alex: Here is what that changes in practice. Merge commits show where two branches came together -- they have two parent commits. The first commit in a repository is often called "initial commit" and creates the project structure. Commit frequency varies -- some days have many commits, others have none. This is normal.

      +

      Alex: This is where the talk moves from concept to action. This is where In VS Code becomes real: the "Timeline" view in the Explorer sidebar shows the history for the currently open file. That matters in practice: Each entry is a commit that changed that file.

      Jamie: Where do you want a learner to place their attention here?

      -

      Alex: Here is the plain-English version of If you downloaded a ZIP. Download a fresh ZIP from the repository and replace your local copy. Put another way, there is no incremental update for ZIP downloads.

      -

      Jamie: What decision is this helping them make?

      -

      Alex: Start with 8. Which Format Should I Use? There is something to understand, something to try, and something that proves the try worked.

      -

      Alex: Use the comparison to make a decision, not to recite a table. The main contrasts are: Reading during the workshop means GitHub Pages (online HTML) means No setup, always current, fully accessible. Offline reference means Local HTML (html/ folder) means Works in any browser, no internet needed, styled and navigable. Editing or contributing means Markdown (.md files) means The source format - edit these, then rebuild HTML.

      -
      -

      Jamie: Let's pause on Learning Cards: Choosing the Right Format. What should a learner take away from it?

      -

      Alex: Keep the learner anchored in Learning Cards: Choosing the Right Format. Next: Appendix Z: GitHub Skills Back: Appendix X: Resources Teaching chapter: Chapter 00: Pre-Workshop Setup.

      -

      Alex: These are the details that keep the idea from floating away. For workshop use, the GitHub Pages HTML site is the most accessible option -- it includes skip links, landmarks, and proper heading structure in every page. For offline reference, the local HTML files in the html/ folder work identically to the online version with full navigation between pages. For contributing edits, work with the Markdown source files in docs/ using VS Code -- these are the canonical source that generates everything else. GitHub Pages and local HTML both support browser zoom to 200%+ without layout breakage -- use whichever gives you a better reading experience. VS Code's Markdown preview inherits your editor theme -- if you use a high-contrast theme, the preview will match. If viewing on GitHub.com, enable GitHub's dark theme (Settings then Appearance) for reduced eye strain during long reading sessions.

      +

      Alex: Keep the learner anchored in What matters. The learning objective is understanding that Git history is a navigable record of every change. This is the part to say slowly: If you explored the commit history, clicked into at least one commit to see its diff, and can describe what the history tells you about the project, you completed this bonus.

      -

      Jamie: What should people carry with them after this?

      -

      Alex: Carry the map. Know what page or tool you are in, know which action you are taking, and know what confirmation should follow. If the confirmation is missing, pause. That pause is not wasted time; it is professional judgment.

      -

      Jamie: That is a better way to say it than just follow the steps.

      -

      Alex: Right. Steps matter, but understanding wins. That is episode 42. Next in the series is episode 43, where we keep building the same contributor muscles.

      -
      - +

      Alex: Before the learner moves on. The reason 1. Why a Mental Model Matters matters is that on Day 1, you edited files on GitHub.com using the web editor. That gives the learner a simple foothold: GitHub handled Git for you behind the scenes -- creating commits, managing branches, and tracking changes. The interface gets friendlier when it stops being a wall of controls and starts being a set of named places.

      +

      Jamie: Give me the version that sounds like an instructor, not a manual.

      +

      Alex: Start with 2. The Three Areas: Working Directory, Staging Area, Repository: Git organizes your work into three areas. The next useful detail is this: Understanding these three areas is the single most important concept in this chapter.

      +

      Alex: Hold that next to this. Here is the plain-English version of Working directory. The working directory is the folder on your computer where the files live. Put another way, when you open a project in VS Code, everything you see in the file explorer is the working directory.

      -

      Episode 43: GitHub Skills - Complete Course Catalog

      -

      All 36 GitHub Skills modules organized into six learning paths.

      -

      Based on: Appendix Z: GitHub Skills - Complete Course Catalog

      -

      Audio and transcript are being regenerated for this episode.

      -
      -Read Transcript - Episode 43: GitHub Skills - Complete Course Catalog - -

      Transcript

      -

      Alex: Welcome to episode 43 of Git Going with GitHub: GitHub Skills - Complete Course Catalog. I am Alex, and today we are teaching this topic as a conversation you can carry into the workshop, not as a page you have to memorize.

      -

      Jamie: And I am Jamie. I will keep pulling the lesson back to real learners, real repositories, and the evidence that proves the work happened.

      +

      Jamie: Let's pause on Staging area (also called the index). What should a learner take away from it?

      +

      Alex: This is where Staging area (also called the index) becomes real: the staging area is a holding zone. That matters in practice: When you are happy with a change in the working directory, you add it to the staging area.

      +

      Alex: That connects to another useful point. Keep the learner anchored in Repository (the.git folder). The repository is Git's permanent record. This is the part to say slowly: 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. A good GitHub workflow is like a well-run meeting: everyone knows the topic, the next action, and who has the floor.

      +

      Jamie: Let's pause on How the three areas connect. What should a learner take away from it?

      +

      Alex: The reason How the three areas connect matters is that many visual Git tutorials use diagrams with arrows to show this flow. That gives the learner a simple foothold: the text description above and the three-step sequence are the same information without requiring a visual representation.

      +

      Alex: First, edit files in the working directory. Then, stage the changes you want to keep (add to the staging area). After that, commit the staged changes (save to the repository). The rhythm is simple: orient, act, verify, then continue.

      -

      Alex: The lesson focus is All 36 GitHub Skills modules organized into six learning paths. We will treat every step as a teachable decision, because that is what makes the skill portable.

      -

      Jamie: So we should explain the why clearly enough that the steps make sense when the learner meets them later.

      -

      Alex: That is it. If a listener only has audio right now, they should still get the complete concept and know what evidence would prove success.

      +

      Alex: Here is the practical turn. Start with An analogy: packing a box: Think of it like packing a box to mail. The next useful detail is this: 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).

      +

      Alex: On the ground, that means a few things. 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.

      +

      Jamie: Let's pause on Learning Cards: The Three Areas. What should a learner take away from it?

      +

      Alex: Start with Learning Cards: The Three Areas. There is something to understand, something to try, and something that proves the try worked.

      +

      Alex: The room should hear these as checkpoints. 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. 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.

      +

      Alex: Keep the thread going. This is where 3. What Is a Commit? becomes real: a commit is a snapshot of your project at a specific moment in time. That matters in practice: It is not a diff (a list of changes). The workshop is closer to rehearsal than lecture. You hear the move, try the move, and then check what changed.

      -

      Jamie: Okay, set the room for us. What are we walking into?

      -

      Alex: Start with Learning Cards: How GitHub Skills Works. There is something to understand, something to try, and something that proves the try worked.

      -

      Alex: A few details make that real. Every GitHub Skills course runs inside a standard GitHub repository -- the screen reader navigation skills from this workshop (heading nav, issue reading, PR workflows) apply directly. After copying a course with "Use this template," navigate to the Issues tab (G then I) and press H or 3 to find "Step 1:" -- this is where Mona's first lesson appears. Mona posts feedback as issue comments -- press 9 (NVDA/JAWS) to jump to the comments section and read her instructions. Course content appears as standard GitHub issues and comments -- your existing GitHub theme and font size settings apply automatically. Mona's step numbers appear as issue titles with "Step 1:", "Step 2:" prefixes -- scan the Issues list for these numbered titles to track your progress. Course completion is indicated when Mona closes the final issue with a success message -- look for the purple "Closed" badge.

      -

      Jamie: How would you walk the room through that step by step?

      -

      Alex: Here is the plain-English version of How GitHub Skills Works. Each course follows the same pattern. Put another way, all interaction happens through GitHub's standard interface. It is like learning a transit route. The names of the stops matter because they tell you whether you are still going the right direction.

      -

      Alex: First, navigate to the course URL and select "Start course". Then, GitHub copies the course repository to your account. After that, mona (GitHub's automated learning bot) opens an issue with Step 1 instructions within 20 seconds. Finally, you complete the task described in the issue (create a branch, edit a file, open a PR). Treat it like a recipe: do not add the next ingredient until the previous one is actually in the bowl.

      -

      Jamie: What does the learner do first, second, and then after that?

      -

      Alex: First, mona detects your action, validates it, and posts the next step as a comment or new issue. Then, repeat until Mona closes the final issue with a completion message. It is a checklist, but a meaningful one: every item creates evidence that the next step is safe.

      -

      Jamie: What should feel predictable before the first live session starts?

      -

      Alex: This is where Courses Used in This Workshop becomes real: these three modules are integrated into the Day 1 agenda. That matters in practice: You complete them during the workshop with facilitator guidance.

      +

      Jamie: Let's pause on Commit IDs (hashes). What should a learner take away from it?

      +

      Alex: Keep the learner anchored in Commit IDs (hashes). Every commit gets a unique identifier -- a 40-character string called a SHA hash. This is the part to say slowly: In practice, you usually see only the first 7 characters: a1b2c3d.

      +

      Alex: Another way to ground it. The reason Commits are permanent (mostly) matters is that once a commit is made, it is part of the repository's history. That gives the learner a simple foothold: you can make new commits that undo the changes, but the original commit still exists in the timeline.

      +

      Jamie: Let's pause on Learning Cards: Commits. What should a learner take away from it?

      +

      Alex: Start with Learning Cards: Commits. There is something to understand, something to try, and something that proves the try worked.

      +

      Alex: A few details make that real. 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. 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.

      -

      Alex: Now bring the learner back to the room. Keep the learner anchored in Learning Paths. The remaining courses are organized into six learning paths. This is the part to say slowly: Each path builds on skills from this workshop and progresses from introductory to advanced.

      -

      Jamie: What would you say to someone who is already bracing for this to be too much?

      -

      Alex: Start with Learning Cards: Navigating Learning Paths. There is something to understand, something to try, and something that proves the try worked.

      -

      Alex: The parts worth keeping in working memory are these. The six learning paths below are organized as H3 headings with tables listing courses in recommended order -- press 3 to jump between paths, then T to enter each course table. Each course link is in the rightmost "Link" column of the table -- navigate to it with arrow keys after entering the table. Use the Personal Completion Checklist at the bottom of this appendix as a progress tracker -- copy it into a GitHub issue or personal notes file. Each learning path table has columns for Order, Module, Duration, Prerequisite, What You Learn, and Link -- widen your browser if columns appear truncated at high zoom. Course durations range from 30 minutes to 2 hours -- the Duration column helps you plan which courses fit your available time. The Quick Reference table near the bottom alphabetically lists all 36 courses for fast scanning when you know the course name.

      -

      Alex: The useful habit is simple: orient first, act second, verify third. That pause before acting is part of the work.

      -

      Alex: That matters because of the next idea. Start with Path 1: Git Fundamentals: Deepen your understanding of Git version control beyond what the workshop covered. The next useful detail is this: The following table lists Git fundamentals courses in recommended order. Think of it like entering a new building: first you find the lobby, then the room, then the door you actually need.

      -

      Alex: A solid Git habit is to know which branch you are on, what changed, and what confirmation you expect before you run the next command.

      +

      Alex: This is the part worth saying out loud. Here is the plain-English version of 4. What Is a Branch? See also: Chapter 14: Git in Practice shows how to create and switch branches hands-on in VS Code. Put another way, a branch is a name that points to a specific commit. It is like learning a transit route. The names of the stops matter because they tell you whether you are still going the right direction.

      +

      Jamie: Let's pause on The default branch: main. What should a learner take away from it?

      +

      Alex: This is where The default branch: main becomes real: every repository has a default branch, usually called main. That matters in practice: 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.

      +

      Alex: The next layer is this. Keep the learner anchored in Creating a branch. When you create a new branch, Git creates a new pointer that starts at the same commit you are currently on. This is the part to say slowly: Both branches point to the same commit.

      -

      Jamie: If I am listening before the workshop starts, what should settle in my mind first?

      -

      Alex: Here is the plain-English version of Path 2: GitHub Collaboration. Learn the collaboration features that power open source projects and team workflows. Put another way, the following table lists GitHub collaboration courses in recommended order.

      -

      Alex: This is where the talk moves from concept to action. This is where Path 3: GitHub Actions and Automation becomes real: build automated workflows that test, build, and deploy your projects. That matters in practice: The following table lists GitHub Actions courses in recommended order.

      -

      Jamie: What is the one idea that makes the next few steps less mysterious?

      -

      Alex: Keep the learner anchored in Path 4: GitHub Copilot. Master AI-assisted development with GitHub Copilot across editors, CLI, and GitHub itself. This is the part to say slowly: The following table lists GitHub Copilot courses in recommended order.

      +

      Jamie: Let's pause on Making commits on a branch. What should a learner take away from it?

      +

      Alex: The reason Making commits on a branch matters is that when you make a new commit while on the fix/typo branch, the fix/typo pointer moves forward to the new commit. That gives the learner a simple foothold: the main pointer stays where it was.

      +

      Alex: Now bring the learner back to the room. Start with HEAD: which branch are you on?: Git uses a special pointer called HEAD to track which branch you are currently working on. The next useful detail is this: When you switch branches (checkout), Git moves HEAD to point to the new branch and updates the files in your working directory to match. Think of it like entering a new building: first you find the lobby, then the room, then the door you actually need.

      +

      Jamie: Let's pause on Learning Cards: Branches. What should a learner take away from it?

      +

      Alex: Start with Learning Cards: Branches. There is something to understand, something to try, and something that proves the try worked.

      +

      Alex: These are the details that keep the idea from floating away. 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. 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.

      -

      Alex: Before the learner moves on. The reason Path 5: Security matters is that learn to identify vulnerabilities, scan for secrets, and secure your supply chain. That gives the learner a simple foothold: the following table lists security courses in recommended order. The interface gets friendlier when it stops being a wall of controls and starts being a set of named places.

      -

      Jamie: Give me the version that sounds like an instructor, not a manual.

      -

      Alex: Start with Path 6: Cloud and Migration: Deploy to the cloud and migrate existing projects to GitHub. The next useful detail is this: The following table lists cloud and migration courses in recommended order.

      -

      Alex: Hold that next to this. Here is the plain-English version of Quick Reference - All 36 Courses. The following table alphabetically lists every GitHub Skills course with its category and link for quick lookup.

      +

      Alex: That matters because of the next idea. This is where 5. Local vs Remote becomes real: see also: Appendix D: Git Authentication covers how to set up credentials so push and pull work without password prompts. That matters in practice: So far, we have talked about one repository.

      +

      Jamie: Let's pause on The remote repository. What should a learner take away from it?

      +

      Alex: Keep the learner anchored in The remote repository. The remote repository is the one on GitHub.com. This is the part to say slowly: When you see a repository URL like github.com/Community-Access/git-going-with-github, that is the remote.

      +

      Alex: Keep the teaching thread moving. The reason The local repository matters is that the local repository is the copy on your computer. That gives the learner a simple foothold: when you run git clone, Git downloads the entire repository -- all files, all branches, all history -- to your machine. The interface gets friendlier when it stops being a wall of controls and starts being a set of named places.

      -

      Jamie: How do the two days connect instead of feeling like separate courses?

      -

      Alex: This is where During the Workshop becomes real: three courses are woven into Day 1. That matters in practice: You set each one up during the block where it appears, work through Mona's steps alongside the learning room exercises, and finish before moving to the next block.

      -

      Jamie: Turn that into a path someone can follow.

      -

      Alex: Start with After the Workshop - Recommended Next Steps. There is something to understand, something to try, and something that proves the try worked.

      -

      Alex: For a learner, the useful signals are these. Want to contribute to open source? Start with Path 2 (Collaboration). Want to automate your workflow? Start with Path 3 (Actions). Want to code faster with AI? Start with Path 4 (Copilot). Want to secure your projects? Start with Path 5 (Security).

      -

      Alex: First, finish any incomplete workshop courses first. If Introduction to GitHub, Communicate Using Markdown, or Review Pull Requests are still in progress, complete them before starting new modules. Then, pick one path that matches your next goal. After that, work through one course at a time. Each course takes 30-60 minutes. Spreading them across multiple days helps with retention. Finally, use the workshop materials as reference. When a GitHub Skills course asks you to create a branch or open a PR, the chapter guides from this workshop describe the same operations with screen reader instructions. It is like walking a hallway with named doors: read the sign, enter the right room, then confirm where you landed.

      -

      Jamie: Where do you want a learner to place their attention here?

      -

      Alex: The reason Tracking Your Progress matters is that GitHub Skills does not have a central dashboard for tracking completions.

      -

      Alex: On the ground, that means a few things. GitHub profile: Completed courses appear as repositories in your account. Pin your favorites to your profile. Repository list: Filter your repositories by the "skills-" prefix to see all courses you have started. Mona's final message: When you finish a course, Mona posts a completion message in the final issue. Bookmark it. This checklist: Copy the list below into a personal note or issue to track which courses you have completed.

      +

      Jamie: Let's pause on The two-copy model. What should a learner take away from it?

      +

      Alex: Start with The two-copy model: The text diagram above shows two boxes side by side connected by arrows. The next useful detail is this: The left box is labeled "Your computer (local)" and contains working directory, staging area, and repository.

      +

      Alex: Keep the teaching thread moving. Start with Learning Cards: Local vs Remote. There is something to understand, something to try, and something that proves the try worked.

      +

      Alex: For a learner, the useful signals are these. 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. 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.

      +

      Jamie: Let's pause on 6. Push, Pull, and Fetch. What should a learner take away from it?

      +

      Alex: This is where 6. Push, Pull, and Fetch becomes real: these three operations keep your local and remote repositories synchronized.

      Alex: A solid pull request habit is to separate three questions: what changed, why it changed, and what still needs review. That keeps the conversation useful instead of noisy.

      -

      Alex: Here is the practical turn. Start with Personal Completion Checklist: Copy this list into your own notes to track progress.

      -

      Jamie: Let's pause on Additional Resources. What should a learner take away from it?

      -

      Alex: Here is the plain-English version of Additional Resources. Back: Appendix Y: Workshop Materials Teaching chapter: Chapter 00: Pre-Workshop Setup.

      -

      Alex: Here is what that changes in practice. GitHub Skills homepage - browse all courses with descriptions. GitHub Skills organization - view all course repositories directly. GitHub Skills Discussions - ask questions and share feedback with the GitHub Skills community.

      -
      -

      Jamie: What should people carry with them after this?

      -

      Alex: Carry the map. Know what page or tool you are in, know which action you are taking, and know what confirmation should follow. If the confirmation is missing, pause. That pause is not wasted time; it is professional judgment.

      -

      Jamie: That is a better way to say it than just follow the steps.

      -

      Alex: Right. Steps matter, but understanding wins. That is episode 43. Next in the series is episode 44, where we keep building the same contributor muscles.

      -
      - +

      Jamie: How do you keep commands from becoming magic words?

      +

      Alex: Keep the learner anchored in Push: share your work. git push sends your local commits to the remote. This is the part to say slowly: After pushing, anyone who looks at the repository on GitHub.com will see your changes. A good GitHub workflow is like a well-run meeting: everyone knows the topic, the next action, and who has the floor.

      +

      Alex: Treat examples as spoken recipes, not decorations. You may hear something like git push origin fix/typo. git push -u origin fix/typo. Read the command, understand what it changes, then run it only when the repository state matches the lesson.

      +

      Jamie: What is the safe way to learn from that example?

      +

      Alex: The reason Pull: get other people's work matters is that git pull downloads new commits from the remote and immediately merges them into your current branch. That gives the learner a simple foothold: this is how you get changes that other people (or you on another computer) have pushed.

      +

      Alex: Treat examples as spoken recipes, not decorations. You may hear something like git pull origin main. Read the command, understand what it changes, then run it only when the repository state matches the lesson.

      +

      Jamie: What should happen before anyone copies and runs it?

      +

      Alex: Start with Fetch: check for updates without merging: git fetch downloads new commits from the remote but does not change your working directory or current branch. The next useful detail is this: It just updates your local knowledge of what the remote looks like.

      +

      Alex: Treat examples as spoken recipes, not decorations. You may hear something like git fetch origin. git log main.origin/main --oneline. Read the command, understand what it changes, then run it only when the repository state matches the lesson.

      -

      Day 1: GitHub Foundations

      -

      Episode 44: Choose Your Tools

      -

      A guided tour of browser GitHub, github.dev, VS Code, GitHub Desktop, and the CLI.

      -

      Based on: Chapter 1: Choose Your Tools

      -

      Audio and transcript are being regenerated for this episode.

      -
      -Read Transcript - Episode 44: Choose Your Tools - -

      Transcript

      -

      Alex: Welcome to Git Going with GitHub, episode 44: Choose Your Tools. I am Alex. Today we are going to make Choose Your Tools something you can explain, practice, and recover from when the interface surprises you.

      -

      Jamie: And I am Jamie. I will be the voice of the learner who is willing to ask, what is this for, where am I, and how do I know I did it right?

      +

      Jamie: Let's pause on 7. Why Merge Conflicts Happen. What should a learner take away from it?

      +

      Alex: Here is the plain-English version of 7. Why Merge Conflicts Happen. A merge conflict happens when Git cannot automatically combine two sets of changes.

      +

      Alex: Keep the teaching thread moving. This is where When conflicts occur becomes real: conflicts happen when two branches modify the same lines in the same file. That matters in practice: Git knows how to merge changes to different files, and even different parts of the same file. The workshop is closer to rehearsal than lecture. You hear the move, try the move, and then check what changed.

      +

      Jamie: Let's pause on What a conflict looks like. What should a learner take away from it?

      +

      Alex: Keep the learner anchored in What a conflict looks like. When a conflict occurs, Git marks the conflicting section in the file with special markers.

      -

      Alex: The big idea today: A guided tour of browser GitHub, github.dev, VS Code, GitHub Desktop, and the CLI. We will name the concept, explain why it matters, practice the move, and point out the checks that tell you the work is real.

      -

      Jamie: So the episode should work even if someone has not read the chapter yet.

      -

      Alex: Exactly. The transcript has to stand on its own. It can point toward practice, but it should teach the concept right here in the conversation.

      +

      Jamie: Let's pause on How to resolve a conflict. What should a learner take away from it?

      +

      Alex: The reason How to resolve a conflict matters is that the Day 1 connection: In Chapter 7, you resolved a merge conflict on GitHub.com using the web editor. That gives the learner a simple foothold: 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.

      +

      Alex: First, open the file with the conflict markers. Then, read both versions and decide which text to keep (or write a new version that combines both). After that, delete the conflict markers ( ). Finally, save the file. The rhythm is simple: orient, act, verify, then continue.

      +

      Jamie: Before we leave How to resolve a conflict, what is the practical point?

      +

      Alex: First, stage and commit the resolved file. Think of it as a rail line: each stop confirms you are still on the right route before the next one.

      +

      Jamie: Let's pause on Why conflicts are normal. What should a learner take away from it?

      +

      Alex: Start with Why conflicts are normal: They happen in every project where more than one person works at the same time. The next useful detail is this: The fact that Git stops and asks is a safety feature -- it prevents data loss by never silently choosing one version over another.

      +

      Alex: Keep the teaching thread moving. Start with Learning Cards: Merge Conflicts. There is something to understand, something to try, and something that proves the try worked.

      +

      Alex: That becomes easier when you listen for these cues. 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. 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.

      -

      Jamie: Okay, set the room for us. What are we walking into?

      -

      Alex: Start with 1. Why This Matters: There is no single "right" way to use GitHub. The next useful detail is this: Some switch between all of them depending on the task.

      -

      Alex: The next layer is this. Here is the plain-English version of 2. The Five Paths. The following table summarizes all five environments at a glance. Put another way, read through the summaries first, then explore the sections that interest you. It is like learning a transit route. The names of the stops matter because they tell you whether you are still going the right direction.

      -

      Jamie: What stays the same when the tool changes?

      -

      Alex: This is where 3. Path 1: GitHub.com (Browser) becomes real: what it is: The GitHub website at github.com. That matters in practice: Every repository, issue, pull request, and setting lives here.

      +

      Jamie: Let's pause on 8. The Git Timeline. What should a learner take away from it?

      +

      Alex: This is where 8. The Git Timeline becomes real: every commit has a parent pointer (except the very first commit). That matters in practice: This creates a chain -- a timeline of the project's history.

      +

      Alex: Keep the teaching thread moving. Keep the learner anchored in 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. This is the part to say slowly: 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.

      +

      Jamie: Let's pause on Branching creates parallel timelines. What should a learner take away from it?

      +

      Alex: The reason Branching creates parallel timelines matters is that when two branches diverge (both have commits that the other does not), the timeline splits into two parallel paths. That gives the learner a simple foothold: both branches share commits A and B (their common history).

      -

      Alex: Now bring the learner back to the room. Start with What you can do here. There is something to understand, something to try, and something that proves the try worked.

      -

      Alex: For a learner, the useful signals are these. 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.

      -

      Jamie: What would you say to someone who is already bracing for this to be too much?

      -

      Alex: Start with What you cannot do here. There is something to understand, something to try, and something that proves the try worked.

      -

      Alex: The parts worth keeping in working memory are these. Run code or tests locally. Use a full-featured code editor with extensions. Make offline changes.

      -

      Alex: The useful habit is simple: orient first, act second, verify third. That pause before acting is part of the work.

      -

      Alex: That matters because of the next idea. Start with Screen reader experience: GitHub.com has strong screen reader support. The next useful detail is this: Every page uses ARIA landmarks, headings follow a consistent hierarchy, and keyboard shortcuts are available for most actions. Think of it like entering a new building: first you find the lobby, then the room, then the door you actually need.

      -

      Alex: A solid navigation habit is to prove where you are before activating controls. Headings, landmarks, and the address bar are not trivia; they are your map.

      +

      Alex: Keep the teaching thread moving. Start with 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 next useful detail is this: The two timelines join back together. Think of it like entering a new building: first you find the lobby, then the room, then the door you actually need.

      +

      Jamie: Let's pause on 9. Putting It All Together. What should a learner take away from it?

      +

      Alex: Here is the plain-English version of 9. Putting It All Together. Here is the complete workflow that you will practice in Chapter 14, translated through the mental model. Put another way, everything in this table maps directly to the three areas (Section 2), the two copies (Section 5), and the timeline (Section 8).

      +

      Alex: Keep the teaching thread moving. This is where Quick mental model checklist becomes real: before running a Git command, ask yourself. That matters in practice: If you can answer these four questions, you can troubleshoot almost any Git situation.

      +

      Alex: The practical takeaway is this. 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?

      -

      Jamie: How would you walk the room through that step by step?

      -

      Alex: Here is the plain-English version of Low vision experience. GitHub supports light and dark themes, high contrast themes, and responds to your operating system's contrast preferences. Put another way, GitHub's layout adapts to browser zoom up to 400% without horizontal scrolling on most pages.

      -

      Alex: First, go to github.com/settings/appearance. Then, choose from Light, Dark, Light high contrast, or Dark high contrast. After that, or select "Sync with system" to follow your OS setting. Treat it like a recipe: do not add the next ingredient until the previous one is actually in the bowl.

      -

      Alex: This is where the talk moves from concept to action. Start with Learning Cards: GitHub.com (Browser). There is something to understand, something to try, and something that proves the try worked.

      -

      Alex: The room should hear these as checkpoints. 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. 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.

      -

      Jamie: What is the common workflow underneath the different interfaces?

      -

      Alex: Keep the learner anchored in 4. Path 2: github.dev (Browser-Based Editor). What it is: A VS Code editor that runs entirely in your browser. This is the part to say slowly: Open any repository by pressing the.

      +

      Jamie: What do you want them to do when the plan breaks?

      +

      Alex: Keep the learner anchored in 10. If You Get Stuck. Next: Chapter 14: Git in Practice Back: Chapter 12: VS Code Accessibility Related appendices: Appendix E: Advanced Git Appendix D: Git Authentication.

      +

      Alex: Keep the teaching thread moving. The reason Going Deeper with Git matters is that who this is for: You have completed Chapter 11 (Git & Source Control) and feel comfortable with the basics -- cloning, branching, committing, pushing, and pulling. That gives the learner a simple foothold: this appendix covers the next tier of Git skills that come up constantly in real open source contribution: cherry-picking fixes across branches, cleaning up messy commit history before a PR, safely undoing mistakes, and understanding why your push sometimes. The interface gets friendlier when it stops being a wall of controls and starts being a set of named places.

      +

      Jamie: Let's pause on Learning Cards: Using This Advanced Git Reference. What should a learner take away from it?

      +

      Alex: Start with Learning Cards: Using This Advanced Git Reference. There is something to understand, something to try, and something that proves the try worked.

      +

      Alex: The practical takeaway is this. Each operation is a numbered h2 section with three sub-paths: VS Code, GitHub CLI, and Git CLI. Use H to jump between operations and 3 to jump between the tool-specific sub-headings within each. The Table of Contents above has anchor links -- activate any link to jump directly to that operation. Command examples are in labeled code blocks -- increase zoom and each command fits on one line. Every section follows the same structure: what it is, when to use it, then tool-specific steps. The Quick Reference table near the bottom gives a one-row-per-operation summary for fast lookup.

      -

      Alex: Before the learner moves on. Start with What you can do here. There is something to understand, something to try, and something that proves the try worked.

      -

      Alex: That becomes easier when you listen for these cues. 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.

      -

      Jamie: Give me the version that sounds like an instructor, not a manual.

      -

      Alex: A few details make that real. 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.

      -

      Alex: Hold that next to this. Here is the plain-English version of Screen reader experience. github.dev is VS Code running in the browser, so the same keyboard navigation and screen reader support applies. Put another way, the command palette (Ctrl+Shift+P or Cmd+Shift+P) is available, and all editor keybindings work.

      +

      Alex: Keep the teaching thread moving. Here is the plain-English version of 1. Cherry-Pick -- Grabbing a Specific Commit. What it is: Cherry-pick lets you take a single commit from any branch and apply it to your current branch. Put another way, think of it like copy-pasting a specific change -- without bringing the entire branch along with it.

      +

      Alex: The practical takeaway is this. You fixed a bug on a feature branch, but main also needs that fix right now. A teammate landed a commit on their branch and you need just that one change. You accidentally committed to the wrong branch and need to move that commit somewhere else.

      +

      Jamie: Let's pause on Finding the Commit SHA. What should a learner take away from it?

      +

      Alex: This is where Finding the Commit SHA becomes real: before cherry-picking, you need the commit's SHA (the unique ID for that commit).

      +

      Jamie: Let's pause on VS Code. What should a learner take away from it?

      +

      Alex: Start with VS Code. There is something to understand, something to try, and something that proves the try worked.

      +

      Alex: First, open the Timeline panel: Click View → Open View → Timeline (or press Ctrl+Shift+P and type "Timeline"). Then, switch to the branch that has the commit you want, browse the Timeline, and copy the commit SHA shown in the details panel. It is like walking a hallway with named doors: read the sign, enter the right room, then confirm where you landed.

      -

      Jamie: If I am listening before the workshop starts, what should settle in my mind first?

      -

      Alex: This is where When to use github.dev over GitHub.com becomes real: 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. That matters in practice: For single-file edits, the pencil icon on GitHub.com is simpler.

      -

      Alex: That connects to another useful point. Keep the learner anchored in 5. Path 3: VS Code (Desktop). What it is: Visual Studio Code is a free desktop code editor from Microsoft. This is the part to say slowly: It has built-in Git support, an integrated terminal, thousands of extensions, and GitHub Copilot included. A good GitHub workflow is like a well-run meeting: everyone knows the topic, the next action, and who has the floor.

      -

      Jamie: What is the one idea that makes the next few steps less mysterious?

      -

      Alex: Start with What you can do here. There is something to understand, something to try, and something that proves the try worked.

      -

      Alex: On the ground, that means a few things. 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).

      +

      Jamie: What should they understand before typing anything?

      +

      Alex: The reason Git CLI matters is that the short SHA is the first 7 characters (a1b2c3d).

      +

      Alex: Treat examples as spoken recipes, not decorations. You may hear something like See commits on another branch without switching to it; git log feature/bug-fix --oneline; Output:; a1b2c3d Fix null pointer error in auth module; e4f5g6h Add unit tests for login. Read the command, understand what it changes, then run it only when the repository state matches the lesson.

      +

      Jamie: Let's pause on VS Code (Command Palette). What should a learner take away from it?

      +

      Alex: Start with VS Code (Command Palette). There is something to understand, something to try, and something that proves the try worked.

      +

      Alex: First, press Ctrl+Shift+P (or Cmd+Shift+P on macOS). Then, type "cherry" and select "Git: Cherry Pick.". After that, paste or type the commit SHA. Finally, press Enter -- VS Code applies the commit to your current branch. Think of it as a rail line: each stop confirms you are still on the right route before the next one.

      +

      Jamie: Let's pause on GitHub CLI. What should a learner take away from it?

      +

      Alex: Here is the plain-English version of GitHub CLI. The GitHub CLI doesn't have a direct cherry-pick command (it's a local Git operation), but you can use it to find the SHA first.

      +

      Alex: Treat examples as spoken recipes, not decorations. You may hear something like List commits on a branch via gh to find the one you want; gh api repos/{owner}/{repo}/commits?sha=feature/bug-fix --jq '.[].sha,.[].commit.message' head -20; Then cherry-pick using git; git cherry-pick a1b2c3d. Read the command, understand what it changes, then run it only when the repository state matches the lesson.

      -

      Alex: Here is the practical turn. Start with What you cannot do here (without extensions). There is something to understand, something to try, and something that proves the try worked.

      -

      Alex: Here is what that changes in practice. Manage GitHub issues and pull requests directly (install the GitHub Pull Requests extension for this). View repository insights or settings (use GitHub.com for that).

      -

      Jamie: Where do you want a learner to place their attention here?

      -

      Alex: Here is the plain-English version of Screen reader experience. VS Code has a dedicated accessibility mode that activates automatically when a screen reader is detected. Put another way, deep dive: Chapter 11 covers the VS Code interface in detail.

      -

      Alex: These are the details that keep the idea from floating away. 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.

      -

      Alex: Keep the thread going. This is where Low vision experience becomes real: VS Code supports high contrast themes, custom zoom levels (Ctrl+= to zoom in, Ctrl+- to zoom out), and configurable font sizes. That matters in practice: 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. The workshop is closer to rehearsal than lecture. You hear the move, try the move, and then check what changed.

      +

      Jamie: Let's pause on Git CLI. What should a learner take away from it?

      +

      Alex: Start with Git CLI. There is something to understand, something to try, and something that proves the try worked.

      +

      Alex: Treat examples as spoken recipes, not decorations. You may hear something like Apply a single commit; git cherry-pick a1b2c3d; Apply a range of commits (from older to newer, exclusive of first); git cherry-pick a1b2c3d.e4f5g6h; Apply without automatically committing (lets you review changes first); git cherry-pick --no-commit a1b2c3d. Read the command, understand what it changes, then run it only when the repository state matches the lesson.

      +

      Jamie: Let's pause on If There's a Conflict. What should a learner take away from it?

      +

      Alex: Keep the learner anchored in If There's a Conflict. Cherry-pick can hit conflicts just like a merge. This is the part to say slowly: When a cherry-pick stops due to a conflict, run git status in the terminal -- it announces exactly which files need attention.

      +

      Alex: First, Git pauses and marks the conflicting files (same <<<<<<< HEAD markers as merge conflicts). Then, resolve the conflicts in VS Code's conflict editor (see Chapter 7: Merge Conflicts). After that, stage the resolved files. Finally, then either. It is like walking a hallway with named doors: read the sign, enter the right room, then confirm where you landed.

      +

      Alex: Treat examples as spoken recipes, not decorations. You may hear something like Continue the cherry-pick after resolving; git cherry-pick --continue; Or cancel it entirely and go back to where you started; git cherry-pick --abort. Read the command, understand what it changes, then run it only when the repository state matches the lesson.

      +

      Alex: Keep the teaching thread moving. The reason 2. Interactive Rebase -- Cleaning Up Your History matters is that what it is: Interactive rebase (git rebase -i) is like a time machine for your commits. That gives the learner a simple foothold: before you open a PR, you can reorder commits, combine several small commits into one clean commit, rewrite commit messages, or remove commits that were just experiments.

      +

      Alex: The practical takeaway is this. You made 8 "WIP" commits while working and want to combine them into 1 clean commit for your PR. You want to reword a commit message to better describe what changed. You accidentally committed a debug file and want to remove that commit entirely.

      -

      Jamie: There are a lot of tools in play. How do we keep that from feeling like a contest?

      -

      Alex: Start with Learning Cards: VS Code (Desktop). There is something to understand, something to try, and something that proves the try worked.

      -

      Alex: The practical anchors are these. 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. 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.

      -

      Alex: Another way to ground it. The reason 6. Path 4: GitHub Desktop matters is that what it is: A desktop application that provides a graphical interface for Git operations. That gives the learner a simple foothold: instead of typing git commit in a terminal, you use buttons, lists, and visual diffs.

      -

      Jamie: Let's pause on What you can do here. What should a learner take away from it?

      -

      Alex: That shows up in the workshop in a few specific ways. 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).

      +

      Jamie: Before we leave VS Code, what is the practical point?

      +

      Alex: Start with VS Code: VS Code has basic rebase support via the Command Palette, but for full interactive rebase you'll want the terminal. The next useful detail is this: After that, git rebase -i will open the commit list in VS Code itself -- much more screen-reader-friendly.

      +

      Alex: First, open the Integrated Terminal: Ctrl+Backtick. Then, run the command below to rebase the last N commits (replace N with how many commits you want to edit). After that, your default editor opens with a list of your commits. If it opens in vim, type i to enter insert mode, make your edits, then press Esc followed by:wq to save. If you'd prefer VS Code as the editor. Think of it as a rail line: each stop confirms you are still on the right route before the next one.

      +

      Alex: Treat examples as spoken recipes, not decorations. You may hear something like git rebase -i HEAD 3; This opens your last 3 commits for editing. git config --global core.editor "code --wait". Read the command, understand what it changes, then run it only when the repository state matches the lesson.

      +

      Jamie: Let's pause on Git CLI (Terminal). What should a learner take away from it?

      +

      Alex: Start with Git CLI (Terminal). There is something to understand, something to try, and something that proves the try worked.

      +

      Alex: Treat examples as spoken recipes, not decorations. You may hear something like Rebase the last 3 commits; git rebase -i HEAD 3; Or rebase everything since you branched from main; git rebase -i main. Read the command, understand what it changes, then run it only when the repository state matches the lesson.

      +

      Jamie: Let's pause on The Commit List -- What You're Looking At. What should a learner take away from it?

      +

      Alex: This is where The Commit List -- What You're Looking At becomes real: when the editor opens, you see something like this. That matters in practice: Each line starts with a command word.

      -

      Alex: This is the part worth saying out loud. Start with What you cannot do here. There is something to understand, something to try, and something that proves the try worked.

      -

      Alex: The practical takeaway is this. 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.

      -

      Jamie: Let's pause on Screen reader experience. What should a learner take away from it?

      -

      Alex: This is where Screen reader experience becomes real: GitHub Desktop uses Electron and provides basic screen reader support. That matters in practice: Branch switching, commit history, and file lists are navigable.

      -

      Alex: Keep the teaching thread moving. Keep the learner anchored in 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. This is the part to say slowly: It is a good stepping stone between the GitHub.com web editor and the full VS Code workflow.

      +

      Alex: Keep the teaching thread moving. Keep the learner anchored in Example: Squashing 3 Commits Into 1. Git opens a second editor for you to write the combined commit message. This is the part to say slowly: Write a clean summary and save -- done.

      +

      Jamie: Let's pause on Example: Rewriting a Commit Message. What should a learner take away from it?

      +

      Alex: The reason Example: Rewriting a Commit Message matters is that Git opens the commit message for a1b2c3d for you to edit. That gives the learner a simple foothold: write the new message, save -- done.

      +

      Jamie: Let's pause on If Something Goes Wrong. What should a learner take away from it?

      +

      Alex: Start with If Something Goes Wrong: Run git rebase -i with VS Code as your editor (git config --global core.editor "code --wait") -- the commit list opens in a VS Code tab that your screen reader can navigate normally with arrow keys. The next useful detail is this: GitHub Copilot can help: Not sure how to word a squashed commit message? Think of it like entering a new building: first you find the lobby, then the room, then the door you actually need.

      +

      Alex: Treat examples as spoken recipes, not decorations. You may hear something like Abort the rebase and go back to where you started; git rebase --abort; If you're mid-rebase and hit a conflict, resolve it then continue; git rebase --continue. Read the command, understand what it changes, then run it only when the repository state matches the lesson.

      -

      Jamie: Let's pause on 7. Path 5: GitHub CLI. What should a learner take away from it?

      -

      Alex: The reason 7. Path 5: GitHub CLI matters is that what it is: A command-line tool called gh that brings GitHub features to your terminal. That gives the learner a simple foothold: it handles authentication, issue management, pull request workflows, and repository operations -- directly from the command line.

      -

      Alex: Keep the teaching thread moving. Start with What you can do here. There is something to understand, something to try, and something that proves the try worked.

      -

      Alex: The practical takeaway is this. 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.

      -

      Jamie: Let's pause on What you cannot do here. What should a learner take away from it?

      -

      Alex: The practical takeaway is this. 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).

      +

      Jamie: Let's pause on 3. git reset -- Undoing at Different Depths. What should a learner take away from it?

      +

      Alex: Here is the plain-English version of 3. git reset -- Undoing at Different Depths. What it is: git reset moves the tip of your current branch backward to a previous commit. Put another way, the three modes (--soft, --mixed, --hard) control what happens to the changes that were in those commits.

      +

      Alex: The practical takeaway is this. You committed too early and want to add more changes to that commit. You staged the wrong files and want to unstage them. You want to completely throw away the last few commits and start fresh.

      +

      Alex: Keep the teaching thread moving. This is where The Three Modes becomes real: think of Git as having three layers: your working files (what you can see in the editor), the staging area (what git add puts there), and the commit history. That matters in practice: It permanently discards your uncommitted changes.

      +

      Jamie: Let's pause on Using the Source Control panel. What should a learner take away from it?

      +

      Alex: Keep the learner anchored in Using the Source Control panel. This is equivalent to git reset --soft HEAD 1 -- your changes come back as staged files, nothing is lost.

      +

      Alex: First, open Source Control: Ctrl+Shift+G. Then, click the "." (More Actions) menu at the top of the panel. After that, select "Commit → Undo Last Commit". It is like walking a hallway with named doors: read the sign, enter the right room, then confirm where you landed.

      -

      Alex: Keep the teaching thread moving. This is where Screen reader experience becomes real: the GitHub CLI is a text-based tool running in a terminal. That matters in practice: Screen reader users read its output directly as plain text -- no landmarks, headings, or ARIA to worry about.

      -

      Jamie: Let's pause on When to choose GitHub CLI. What should a learner take away from it?

      -

      Alex: Keep the learner anchored in When to choose GitHub CLI. Choose the CLI if you are comfortable in a terminal and want fast, scriptable access to GitHub features. This is the part to say slowly: It pairs well with VS Code's integrated terminal, giving you the best of both worlds.

      -

      Alex: Keep the teaching thread moving. Start with Learning Cards: GitHub CLI. There is something to understand, something to try, and something that proves the try worked.

      -

      Alex: The practical takeaway is this. 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. 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.

      +

      Jamie: Let's pause on Using the Command Palette. What should a learner take away from it?

      +

      Alex: Start with Using the Command Palette. There is something to understand, something to try, and something that proves the try worked.

      +

      Alex: Treat examples as spoken recipes, not decorations. You may hear something like Ctrl+Shift+P → type "git undo" → select "Git: Undo Last Commit". Read the command, understand what it changes, then run it only when the repository state matches the lesson.

      +

      Jamie: Before we leave Git CLI, what is the practical point?

      +

      Alex: Treat examples as spoken recipes, not decorations. You may hear something like Undo last commit -- keep changes staged (safest); git reset --soft HEAD 1; Undo last commit -- keep changes but unstage them; git reset --mixed HEAD 1; Undo last 3 commits -- keep all changes unstaged; git reset --mixed HEAD 3; Undo last commit -- DISCARD all. Read the command, understand what it changes, then run it only when the repository state matches the lesson.

      +

      Alex: Keep the teaching thread moving. Here is the plain-English version of Unstaging a File (Without Undoing the Commit). If you just want to remove a file from the staging area without touching commit history.

      -

      Jamie: What is the pre-flight check here?

      -

      Alex: Start with 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.

      -

      Alex: Keep the teaching thread moving. Here is the plain-English version of Day 2 recommendation. On Day 2, you work with Git locally. Put another way, most students add VS Code (Path 3) at this point.

      -

      Jamie: Let's pause on Switching paths is normal. What should a learner take away from it?

      -

      Alex: This is where Switching paths is normal becomes real: the learner will likely use more than one tool during the workshop. That matters in practice: The workshop chapters always tell you which tool to use for each step.

      -

      Alex: The practical takeaway is this. 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.

      +

      Jamie: There are a lot of tools in play. How do we keep that from feeling like a contest?

      +

      Alex: This is where VS Code becomes real: in the Source Control panel, click the minus (--) icon next to a staged file, or right-click it and select "Unstage Changes".

      +

      Jamie: What is the teaching move inside Git CLI?

      +

      Alex: Treat examples as spoken recipes, not decorations. You may hear something like Unstage a specific file; git restore --staged docs/README.md; Unstage everything; git restore --staged. Read the command, understand what it changes, then run it only when the repository state matches the lesson.

      +

      Jamie: Let's pause on 4. git revert -- The Safe Undo for Shared Branches. What should a learner take away from it?

      +

      Alex: The reason 4. git revert -- The Safe Undo for Shared Branches matters is that what it is: git revert creates a new commit that undoes the changes from a previous commit. That gives the learner a simple foothold: unlike git reset, it does not rewrite history -- it adds to it.

      +

      Alex: The practical takeaway is this. A commit made it to main and it broke something -- you need to roll it back without force-pushing. You want to undo a change but keep a record that the undo happened. You're working on a protected branch where force-push is disabled.

      -

      Alex: Keep the teaching thread moving. Start with Learning Cards: Which Path Should I Start With? There is something to understand, something to try, and something that proves the try worked.

      -

      Alex: The practical takeaway is this. 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. 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.

      -

      Jamie: What should the learner prove to themselves after each small task?

      -

      Alex: The reason 9. Your First Confidence Exercise matters is that this exercise takes approximately five minutes. That gives the learner a simple foothold: it verifies your tool is working and builds your confidence before Day 1 begins.

      -

      Alex: Keep the teaching thread moving. Start with The task: Open the public workshop curriculum repository and find the README file.

      +

      Jamie: What is the teaching move inside VS Code?

      +

      Alex: First, open the Timeline panel and navigate to the commit you want to undo. Then, right-click the commit and select "Revert Commit". After that, VS Code creates a new commit with message Revert "your original message" -- review it and push. Think of it as a rail line: each stop confirms you are still on the right route before the next one.

      +

      Jamie: If someone only remembers one thing from Git CLI, what should it be?

      +

      Alex: Treat examples as spoken recipes, not decorations. You may hear something like Revert a specific commit (opens editor to confirm the message); git revert a1b2c3d; Revert without opening the editor (uses default message); git revert --no-edit a1b2c3d; Stage the revert but don't commit yet (lets you edit the message manually); git revert. Read the command, understand what it changes, then run it only when the repository state matches the lesson.

      +

      Jamie: What decision is this helping them make?

      +

      Alex: This is where When to Use revert vs reset becomes real: GitHub Copilot can help: Not sure whether to use reset or revert? That matters in practice: Describe your situation to Copilot Chat: "I pushed a commit to main that broke the login page. The workshop is closer to rehearsal than lecture. You hear the move, try the move, and then check what changed.

      +

      Alex: Use the comparison to make a decision, not to recite a table. The main contrasts are: Commit is only local (not pushed) means git reset -- cleaner, no extra commit. Commit is on a shared branch (main, dev) means git revert -- preserves history, safe for others. Branch has protection rules (no force push) means git revert -- the only option.

      -

      Jamie: What does the learner do first, second, and then after that?

      -

      Alex: Start with Path 1: GitHub.com. There is something to understand, something to try, and something that proves the try worked.

      -

      Alex: First, go to github.com/Community-Access/git-going-with-github. Then, the README is displayed below the file list on the repository's home page. After that, screen reader users: press H to navigate headings. The README's first heading announces the repository name. Finally, you are done when you can read the first paragraph of the README. Treat it like a recipe: do not add the next ingredient until the previous one is actually in the bowl.

      -

      Jamie: Turn that into a path someone can follow.

      -

      Alex: Start with Path 2: github.dev. There is something to understand, something to try, and something that proves the try worked.

      -

      Alex: First, go to github.dev/Community-Access/git-going-with-github. Then, the file explorer opens on the left. Press Ctrl+Shift+E (or Cmd+Shift+E) to focus it. After that, navigate to README.md and press Enter to open it in a tab. Finally, you are done when the file content appears in the editor. It is a checklist, but a meaningful one: every item creates evidence that the next step is safe.

      -

      Jamie: What is the ordered workflow?

      -

      Alex: Start with Path 3: VS Code (if set up). There is something to understand, something to try, and something that proves the try worked.

      -

      Alex: First, open VS Code. Then, open the command palette: Ctrl+Shift+P (or Cmd+Shift+P). After that, type "Git: Clone" and press Enter. Finally, paste the URL: https://github.com/Community-Access/git-going-with-github.git. It is like walking a hallway with named doors: read the sign, enter the right room, then confirm where you landed.

      -

      Jamie: Give me the sequence, because order matters here.

      -

      Alex: First, choose a folder to clone into and wait for the download. Then, when it finishes, VS Code offers to open the repository. Accept. After that, open the file explorer (Ctrl+Shift+E) and select README.md. Finally, you are done when the file content appears in the editor. The rhythm is simple: orient, act, verify, then continue.

      +

      Jamie: Let's pause on 5. Tags -- Marking Important Moments. What should a learner take away from it?

      +

      Alex: Keep the learner anchored in 5. Tags -- Marking Important Moments. What it is: A tag is a permanent label you attach to a specific commit -- usually to mark a release version like v1.0.0. This is the part to say slowly: Unlike a branch (which moves as you commit), a tag always points to the exact same commit forever.

      +

      Alex: The practical takeaway is this. Releasing a new version of a project. Marking a stable checkpoint before starting a big refactor. Documenting when a major feature shipped.

      +

      Jamie: Before we leave VS Code (Command Palette), what is the practical point?

      +

      Alex: The reason VS Code (Command Palette) matters is that type the tag name (e.g., v1.2.0) and optionally a message.

      +

      Alex: Treat examples as spoken recipes, not decorations. You may hear something like Ctrl+Shift+P → type "git tag" → select "Git: Create Tag". Read the command, understand what it changes, then run it only when the repository state matches the lesson.

      +

      Jamie: Before we leave GitHub CLI, what is the practical point?

      +

      Alex: Start with GitHub CLI. There is something to understand, something to try, and something that proves the try worked.

      +

      Alex: Treat examples as spoken recipes, not decorations. You may hear something like Create a tag and push it to GitHub in one step (using the API); gh release create v1.2.0 --title "Version 1.2.0" --notes "Bug fixes and accessibility improvements"; This creates both a GitHub Release and the underlying tag. Read the command, understand what it changes, then run it only when the repository state matches the lesson.

      -

      Jamie: Let's pause on Path 4: GitHub Desktop. What should a learner take away from it?

      -

      Alex: Start with Path 4: GitHub Desktop. There is something to understand, something to try, and something that proves the try worked.

      -

      Alex: First, open GitHub Desktop. Then, go to File, then Clone repository (or press Ctrl+Shift+O). After that, paste the URL: https://github.com/Community-Access/git-going-with-github.git. Finally, choose a local path and click Clone. The rhythm is simple: orient, act, verify, then continue.

      -

      Jamie: Before we leave Path 4: GitHub Desktop, what is the practical point?

      -

      Alex: First, once cloned, the repository appears in GitHub Desktop. Click "Open in Visual Studio Code" (or your preferred editor) to read the README. Think of it as a rail line: each stop confirms you are still on the right route before the next one.

      -

      Jamie: Let's pause on Path 5: GitHub CLI. What should a learner take away from it?

      -

      Alex: Start with Path 5: GitHub CLI. There is something to understand, something to try, and something that proves the try worked.

      -

      Alex: First, open your terminal. Then, open the README in your preferred way. After that, you are done when you can read the first paragraph. Think of it as a rail line: each stop confirms you are still on the right route before the next one.

      -

      Alex: Treat examples as spoken recipes, not decorations. You may hear something like gh repo clone Community-Access/git-going-with-github; cd learning-room. cat README.md print to terminal; code README.md open in VS Code. Read the command, understand what it changes, then run it only when the repository state matches the lesson.

      -

      Alex: Keep the teaching thread moving. Here is the plain-English version of What success looks like. You opened a real repository and found a real file. Put another way, that is the core action of this entire workshop -- everything else builds on it. It is like learning a transit route. The names of the stops matter because they tell you whether you are still going the right direction.

      +

      Jamie: Let's pause on Git CLI. What should a learner take away from it?

      +

      Alex: Treat examples as spoken recipes, not decorations. You may hear something like Create a lightweight tag at the current commit; git tag v1.2.0; Create an annotated tag (recommended for releases); git tag -a v1.2.0 -m "Release version 1.2.0 - bug fixes and accessibility improvements"; Tag a specific past commit; git tag -a v1.1.5 a1b2c3d. Read the command, understand what it changes, then run it only when the repository state matches the lesson.

      +

      Jamie: Let's pause on Pushing Tags to GitHub. What should a learner take away from it?

      +

      Alex: This is where Pushing Tags to GitHub becomes real: tags are not pushed automatically when you run git push.

      +

      Alex: Treat examples as spoken recipes, not decorations. You may hear something like Push a specific tag; git push origin v1.2.0; Push all local tags at once; git push origin --tags. Read the command, understand what it changes, then run it only when the repository state matches the lesson.

      +

      Jamie: Let's pause on Deleting a Tag. What should a learner take away from it?

      +

      Alex: Start with Deleting a Tag. There is something to understand, something to try, and something that proves the try worked.

      +

      Alex: Treat examples as spoken recipes, not decorations. You may hear something like Delete a local tag; git tag -d v1.2.0; Delete the tag on GitHub (remote); git push origin --delete v1.2.0. Read the command, understand what it changes, then run it only when the repository state matches the lesson.

      +
      +

      Jamie: Let's pause on 6. Detached HEAD -- What It Is and How to Get Out. What should a learner take away from it?

      +

      Alex: The reason 6. Detached HEAD -- What It Is and How to Get Out matters is that what it is: Normally, you're working on a branch -- Git tracks your commits and moves the branch forward as you commit. That gives the learner a simple foothold: a "detached HEAD" happens when you check out a specific commit SHA (or a tag) directly instead of a branch.

      +

      Alex: Treat examples as spoken recipes, not decorations. You may hear something like git checkout a1b2c3d Check out a specific commit; git checkout v1.0.0 Check out a tag. Read the command, understand what it changes, then run it only when the repository state matches the lesson.

      +

      Jamie: Let's pause on If you just want to go back to your branch. What should a learner take away from it?

      +

      Alex: Start with If you just want to go back to your branch. There is something to understand, something to try, and something that proves the try worked.

      +

      Alex: Treat examples as spoken recipes, not decorations. You may hear something like git checkout main; or whatever branch you were on; git switch main. Read the command, understand what it changes, then run it only when the repository state matches the lesson.

      +

      Jamie: Let's pause on If you made commits in detached HEAD and want to keep them. What should a learner take away from it?

      +

      Alex: Start with If you made commits in detached HEAD and want to keep them. There is something to understand, something to try, and something that proves the try worked.

      +

      Alex: Treat examples as spoken recipes, not decorations. You may hear something like Create a new branch at the current (detached) position to save your work; git checkout -b my-experiment; Now you're on a real branch and those commits are safe. Read the command, understand what it changes, then run it only when the repository state matches the lesson.

      +
      +

      Alex: Keep the teaching thread moving. This is where VS Code becomes real: VS Code shows the current branch name in the bottom-left status bar. That matters in practice: If you're in detached HEAD, it shows something like (HEAD detached at a1b2c3d) instead of a branch name.

      +

      Jamie: Let's pause on 7. Force Pushing Safely. What should a learner take away from it?

      +

      Alex: Keep the learner anchored in 7. Force Pushing Safely. What it is: After you rebase or amend commits that have already been pushed, the remote branch has a different history than your local branch. This is the part to say slowly: A regular git push will fail because Git sees them as diverged.

      +

      Alex: Keep the teaching thread moving. The reason --force-with-lease vs --force matters is that always use --force-with-lease instead of --force. The interface gets friendlier when it stops being a wall of controls and starts being a set of named places.

      +
      +

      Jamie: Let's pause on When You'd Use It. What should a learner take away from it?

      +

      Alex: Start with When You'd Use It. There is something to understand, something to try, and something that proves the try worked.

      +

      Alex: The practical takeaway is this. You rebased a feature branch to squash commits before a PR review. You amended the last commit with git commit --amend after already pushing. A reviewer asked you to rebase onto main and you've now done.

      +

      Jamie: If someone only remembers one thing from VS Code, what should it be?

      +

      Alex: Here is the plain-English version of VS Code. VS Code doesn't have a "force push" button in the UI -- this is intentional to prevent accidents.

      +

      Alex: Treat examples as spoken recipes, not decorations. You may hear something like Ctrl+Backtick → then type the command below. Read the command, understand what it changes, then run it only when the repository state matches the lesson.

      +

      Jamie: What is the teaching move inside GitHub CLI?

      +

      Alex: Treat examples as spoken recipes, not decorations. You may hear something like Force push your current branch; gh repo sync This is for syncing FROM remote, not for force pushing; For force pushing, use git directly:; git push --force-with-lease origin your-branch-name. Read the command, understand what it changes, then run it only when the repository state matches the lesson.

      +
      +

      Jamie: Let's pause on Git CLI. What should a learner take away from it?

      +

      Alex: Treat examples as spoken recipes, not decorations. You may hear something like Safe force push -- fails if someone else pushed since your last fetch; git push --force-with-lease origin feature/my-branch; Check what will happen before pushing; git push --force-with-lease --dry-run origin feature/my-branch; Unconditional force push (avoid. Read the command, understand what it changes, then run it only when the repository state matches the lesson.

      +

      Jamie: Let's pause on The Typical Rebase + Force Push Workflow. What should a learner take away from it?

      +

      Alex: Start with The Typical Rebase + Force Push Workflow. There is something to understand, something to try, and something that proves the try worked.

      +

      Alex: Treat examples as spoken recipes, not decorations. You may hear something like You're on your feature branch -- rebase onto main to get latest changes; git fetch origin; git rebase origin/main; 2. Resolve any conflicts, then continue; git rebase --continue; 3. Force push your rebased branch (origin already has the old version); git push. Read the command, understand what it changes, then run it only when the repository state matches the lesson.

      +

      Alex: Keep the teaching thread moving. Start with 8. git bisect -- Finding the Commit That Broke Things: What it is: git bisect performs a binary search through your commit history to find exactly which commit introduced a bug. The next useful detail is this: Instead of checking 100 commits one by one, Git cuts the search in half each time -- usually finding the culprit in 7-10 steps.

      +

      Alex: The practical takeaway is this. "This was working last week, now it's broken -- what changed?". You need to find the exact commit so you can revert or fix it. A test that used to pass now fails and you don't know why.

      +
      +

      Jamie: Let's pause on Starting a Bisect Session. What should a learner take away from it?

      +

      Alex: Here is the plain-English version of Starting a Bisect Session. Git now checks out a commit in the middle of your history. Put another way, test your code -- does the bug exist here?

      +

      Alex: Treat examples as spoken recipes, not decorations. You may hear something like Start bisect mode; git bisect start; 2. Mark the current commit as bad (broken); git bisect bad; 3. Mark a commit you know was good (working); Use a tag, SHA, or branch name from before the problem started; git bisect good v1.0.0; or; git bisect good a1b2c3d. If the bug IS present at this commit; git bisect bad; If the bug is NOT present at this commit; git bisect good. Read the command, understand what it changes, then run it only when the repository state matches the lesson.

      +

      Jamie: Let's pause on Finishing. What should a learner take away from it?

      +

      Alex: Start with Finishing. There is something to understand, something to try, and something that proves the try worked.

      +

      Alex: Treat examples as spoken recipes, not decorations. You may hear something like End the bisect session and return to your original branch; git bisect reset. Read the command, understand what it changes, then run it only when the repository state matches the lesson.

      +

      Jamie: Let's pause on Automating Bisect with a Test Script. What should a learner take away from it?

      +

      Alex: Keep the learner anchored in Automating Bisect with a Test Script. If you have a test command that exits with code 0 on success and non-zero on failure, Git can run bisect automatically. This is the part to say slowly: Bisect output is plain text -- each step tells you exactly where it checked out and how many steps remain.

      +

      Alex: Treat examples as spoken recipes, not decorations. You may hear something like git bisect start; git bisect bad HEAD; git bisect good v1.0.0; Run automatically -- git runs your test script at each step; git bisect run npm test; or; git bisect run python -m pytest tests/test auth.py. Read the command, understand what it changes, then run it only when the repository state matches the lesson.

      +
      +

      Alex: Keep the teaching thread moving. The reason 9. git clean -- Clearing Out Untracked Files matters is that what it is: git clean removes untracked files and directories from your working directory -- files that Git doesn't know about yet (not staged, not committed, not in.gitignore). That gives the learner a simple foothold: this is useful when you have build artifacts, generated files, or experimental files cluttering your project.

      +

      Alex: The practical takeaway is this. After a build that left temporary files everywhere. You want a completely fresh state matching the last commit. Clearing out generated files before running a clean build.

      +

      Jamie: Let's pause on Always Dry-Run First. What should a learner take away from it?

      +

      Alex: Start with Always Dry-Run First. There is something to understand, something to try, and something that proves the try worked.

      +

      Alex: Treat examples as spoken recipes, not decorations. You may hear something like See what WOULD be deleted without actually deleting anything; git clean -n; or equivalently; git clean --dry-run. Read the command, understand what it changes, then run it only when the repository state matches the lesson.

      +

      Jamie: Let's pause on VS Code. What should a learner take away from it?

      +

      Alex: Here is the plain-English version of VS Code. VS Code's Source Control panel shows untracked files in the "Changes" section. Put another way, for bulk removal, use the terminal (see Git CLI below). It is like learning a transit route. The names of the stops matter because they tell you whether you are still going the right direction.

      +

      Alex: First, open Source Control: Ctrl+Shift+G. Then, right-click an untracked file. After that, select "Discard Changes" -- this removes new untracked files. Treat it like a recipe: do not add the next ingredient until the previous one is actually in the bowl.

      +
      +

      Jamie: Let's pause on Git CLI. What should a learner take away from it?

      +

      Alex: Treat examples as spoken recipes, not decorations. You may hear something like Dry run -- see what would be removed; git clean -n; Remove untracked files (NOT directories); git clean -f; Remove untracked files AND directories; git clean -fd; Remove untracked files AND ignored files (be careful -- removes build artifacts AND things. Read the command, understand what it changes, then run it only when the repository state matches the lesson.

      +

      Alex: Keep the teaching thread moving. Keep the learner anchored in 10. Branch Protection -- Why Your Push or Merge May Be Blocked. What it is: Branch protection rules are settings a repository administrator applies to specific branches (usually main or release branches). This is the part to say slowly: They prevent direct pushes, require pull requests, require approvals before merging, and enforce status checks passing.

      +

      Jamie: Let's pause on The Correct Flow for Protected Branches. What should a learner take away from it?

      +

      Alex: Start with The Correct Flow for Protected Branches. There is something to understand, something to try, and something that proves the try worked.

      +

      Alex: Treat examples as spoken recipes, not decorations. You may hear something like Never push directly to main -- always work on a branch; git checkout -b feature/my-change; 2. Make your changes, commit them; git add.; git commit -m "Add screen reader support to navigation"; 3. Push your branch (not main); git push origin feature/my-change. Read the command, understand what it changes, then run it only when the repository state matches the lesson.

      +
      +

      Alex: Keep the teaching thread moving. Start with Updating a Branch That's Out of Date: When GitHub says your branch is out of date with main. Think of it like entering a new building: first you find the lobby, then the room, then the door you actually need.

      +

      Jamie: Let's pause on VS Code. What should a learner take away from it?

      +

      Alex: First, open Source Control → Ctrl+Shift+P. Then, type "merge" → select "Git: Merge Branch.". After that, choose origin/main from the list. Finally, resolve any conflicts, then push again. Treat it like a recipe: do not add the next ingredient until the previous one is actually in the bowl.

      +

      Jamie: Let's pause on Git CLI. What should a learner take away from it?

      +

      Alex: Treat examples as spoken recipes, not decorations. You may hear something like Option A: Merge main into your branch (creates a merge commit); git fetch origin; git merge origin/main; Option B: Rebase onto main (cleaner history, requires force push after); git fetch origin; git rebase origin/main; git push --force-with-lease origin. Read the command, understand what it changes, then run it only when the repository state matches the lesson.

      +
      +

      Jamie: If someone only remembers one thing from GitHub CLI, what should it be?

      +

      Alex: Treat examples as spoken recipes, not decorations. You may hear something like Update your PR branch from the GitHub UI via CLI; gh pr update-branch --rebase; or; gh pr update-branch uses merge by default. Read the command, understand what it changes, then run it only when the repository state matches the lesson.

      +

      Jamie: Let's pause on GitHub CLI. What should a learner take away from it?

      +

      Alex: Treat examples as spoken recipes, not decorations. You may hear something like View branch protection rules for main; gh api repos/{owner}/{repo}/branches/main/protection --jq '{; required reviews.required pull request reviews.required approving review count,; require status checks.required status checks.contexts,; enforce. Read the command, understand what it changes, then run it only when the repository state matches the lesson.

      +

      Jamie: Let's pause on On GitHub.com. What should a learner take away from it?

      +

      Alex: Start with On GitHub.com: Navigate to Settings → Branches in the repository. The next useful detail is this: (You need admin access to see the full config; contributors can see the effect through blocked PRs and the merge box status.).

      +
      +

      Alex: Keep the teaching thread moving. Start with Learning Cards: Quick Reference Table. There is something to understand, something to try, and something that proves the try worked.

      +

      Alex: The practical takeaway is this. This table has four columns: Task, VS Code, Git CLI, and GitHub CLI -- column headers are announced on entry. Use Ctrl+Alt+Arrow keys to navigate cells; the Task column on the left identifies each row. Cells with a dash (--) mean that tool does not support the operation -- move right to try another column. At high zoom the table may scroll horizontally -- use Shift+scroll or arrow keys to see all four columns. The Task column is always the leftmost -- anchor your reading from there. Consider copying this table into a text file or spreadsheet for easier viewing at your preferred zoom.

      +

      Jamie: Let's pause on 11. Using GitHub Copilot for Git Operations. What should a learner take away from it?

      +

      Alex: This is where 11. Using GitHub Copilot for Git Operations becomes real: GitHub Copilot isn't just for writing code -- it's genuinely useful for Git operations, especially when you're doing something unfamiliar, hit a conflict, or need to understand what a command did. That matters in practice: Here's how to use it across the advanced operations in this appendix.

      +

      Alex: Keep the teaching thread moving. Keep the learner anchored in Resolving Merge Conflicts. When a cherry-pick, rebase, or branch merge stops due to a conflict, VS Code highlights the conflict regions. This is the part to say slowly: Place your cursor inside a conflict block and ask Copilot. A good GitHub workflow is like a well-run meeting: everyone knows the topic, the next action, and who has the floor.

      +

      Alex: The practical takeaway is this. "Resolve this merge conflict. Keep meaningful changes from both sides.". "Explain what each side of this conflict is trying to do.". "Which version of this change should I keep, and why?".

      +

      Jamie: Let's pause on Writing Better Commit Messages. What should a learner take away from it?

      +

      Alex: The reason Writing Better Commit Messages matters is that Copilot is excellent at turning "WIP: stuff" into a clear, conventional commit message. That gives the learner a simple foothold: open Copilot Chat after staging your changes and try.

      +

      Alex: The practical takeaway is this. "Write a conventional commit message for these changes." (Copilot can see open files). "I changed the navigation component to add keyboard focus indicators. Write a commit message.". "Here are my last 5 WIP commit messages: [paste them]. Write one clean message that summarizes all of them.".

      +

      Alex: Keep the teaching thread moving. Start with Understanding Confusing Git Output: Git's error messages and status output can be cryptic. The next useful detail is this: Paste them directly into Copilot Chat.

      +

      Alex: The practical takeaway is this. "I got this git error message: [paste it]. What does it mean and how do I fix it?". "My git status output looks like this: [paste it]. What happened and what should I do next?". "I accidentally ran git reset --hard. What are my options for recovering my changes?".

      +

      Jamie: What stays the same when the tool changes?

      +

      Alex: Here is the plain-English version of Choosing the Right Command. When you're not sure which git command to reach for, describe what you want to do.

      +

      Alex: The practical takeaway is this. "I committed a fix on my feature branch but main also needs it urgently. What's the right git command to use?" → Copilot will suggest cherry-pick. "I have 6 messy commits on my PR branch before I open the PR. How do I clean them up?" → Interactive rebase with squash. "I pushed a commit that broke CI and I need to undo it without force-pushing." → git revert. "My PR branch hasn't been updated from main in two weeks. How do I bring it up to date?" → fetch + rebase or merge.

      +
      +

      Alex: Keep the teaching thread moving. This is where Debugging a Failing Bisect becomes real: when git bisect lands on a commit and you're not sure what to test. The workshop is closer to rehearsal than lecture. You hear the move, try the move, and then check what changed.

      +

      Alex: The practical takeaway is this. "I'm running git bisect to find a bug. Git just checked out commit a1b2c3d. Here's the diff: [paste git show a1b2c3d]. What changed in this commit and what should I test?".

      Jamie: How should someone ask for help in a way that gets them unstuck faster?

      -

      Alex: This is where 10. If You Get Stuck becomes real: next Step: Start your learning journey with Chapter 02: Understanding GitHub. That matters in practice: Next: Chapter 02: Understanding GitHub Back: Chapter 00: Pre-Workshop Setup Related appendices: Appendix H: GitHub Desktop Appendix I: GitHub CLI Appendix J: Codespaces.

      +

      Alex: Keep the learner anchored in Getting Help With Branch Protection Errors. Paste the full error message from a rejected push into Copilot.

      +

      Alex: The practical takeaway is this. "I got this error when pushing to my repository: [paste error]. What does it mean and what do I do?". "My PR can't merge because of a required status check. Here's the check output: [paste it]. What's wrong?".

      +

      Jamie: Let's pause on GitHub Copilot CLI -- Git Command Suggestions. What should a learner take away from it?

      +

      Alex: The reason GitHub Copilot CLI -- Git Command Suggestions matters is that if you have the GitHub CLI with Copilot extension installed, you can ask for git commands directly in the terminal. That gives the learner a simple foothold: Copilot CLI explains the command before running it and asks for confirmation -- great for learning while doing.

      +

      Alex: Treat examples as spoken recipes, not decorations. You may hear something like Ask Copilot to suggest a git command for what you want to do; gh copilot suggest "squash my last 4 commits into one"; gh copilot suggest "undo my last commit but keep the changes"; gh copilot suggest "find which commit broke the login tests". Read the command, understand what it changes, then run it only when the repository state matches the lesson.

      -

      Jamie: What should people carry with them after this?

      -

      Alex: Carry the map. Know what page or tool you are in, know which action you are taking, and know what confirmation should follow. If the confirmation is missing, pause. That pause is not wasted time; it is professional judgment.

      -

      Jamie: That is a better way to say it than just follow the steps.

      -

      Alex: Right. Steps matter, but understanding wins. That is episode 44. Next in the series is episode 45, where we keep building the same contributor muscles.

      +

      Jamie: What is the final checkpoint?

      +

      Alex: You should be able to point to the evidence, explain the action, and describe what you would do next if this were a real open source project. If you can teach the move back, you have learned it.

      +

      Jamie: And if they get stuck?

      +

      Alex: Read the latest message, not the loudest worry. Check the issue, the branch, the pull request, the status check, or the bot comment. Then ask for help with those facts in hand. That is how professionals collaborate.

      -

      Day 2: VS Code and Accessibility Agents

      -

      Episode 45: VS Code Accessibility Deep Dive

      -

      Keyboard navigation, accessible views, terminal access, signals, speech, and Copilot accessibility in VS Code.

      -

      Based on: Chapter 12: VS Code Accessibility Deep Dive

      -

      Audio and transcript are being regenerated for this episode.

      +

      37. Episode 13: The GitHub Pull Requests Extension

      +

      Viewing, creating, reviewing, and merging PRs from inside VS Code.

      +

      Based on: Chapter 15: The GitHub Pull Requests Extension

      + + +

      Download Episode 13 (MP3)

      -Read Transcript - Episode 45: VS Code Accessibility Deep Dive +Read Transcript - Episode 13: The GitHub Pull Requests Extension

      Transcript

      -

      Alex: Welcome back to Git Going with GitHub. This is episode 45: VS Code Accessibility Deep Dive. I am Alex, and today we are turning VS Code Accessibility Deep Dive from a list of instructions into a working mental model.

      +

      Alex: Welcome back to Git Going with GitHub. This is episode 13: The GitHub Pull Requests Extension. I am Alex, and today we are turning The GitHub Pull Requests Extension from a list of instructions into a working mental model.

      Jamie: And I am Jamie. I will stop us whenever the instructions sound simple on paper but might feel different with a keyboard and screen reader.

      -

      Alex: Keyboard navigation, accessible views, terminal access, signals, speech, and Copilot accessibility in VS Code. That is the surface description. Underneath it, we are building judgment: where to focus, what to ignore, and how to verify the result.

      +

      Alex: Viewing, creating, reviewing, and merging PRs from inside VS Code. That is the surface description. Underneath it, we are building judgment: where to focus, what to ignore, and how to verify the result.

      Jamie: So we are not using the audio as a shortcut around learning. We are using it to make the learning easier to enter.

      Alex: Yes. A good audio lesson gives someone enough context to try the work with confidence, even before they open the written material.

      Jamie: Okay, set the room for us. What are we walking into?

      -

      Alex: Start with Accessibility Features for Power Users: Challenge 10: Go Local depends on the accessibility features covered in this chapter. The next useful detail is this: Configure these settings before your first local commit.

      -

      Alex: The next layer is this. Here is the plain-English version of Panels and Areas. Mac users: Substitute Cmd for Ctrl and Option for Alt in all shortcuts below. It is like learning a transit route. The names of the stops matter because they tell you whether you are still going the right direction.

      -

      Jamie: What is the one idea that makes the next few steps less mysterious?

      -

      Alex: This is where Find in Current File (Ctrl+F) becomes real: when the Find widget opens, three toggle buttons refine what matches.

      +

      Alex: Start with The GitHub Pull Requests Extension: See also: Appendix G: VS Code Reference for the complete list of GitHub Pull Requests extension keyboard shortcuts.

      +

      Alex: A solid pull request habit is to separate three questions: what changed, why it changed, and what still needs review. That keeps the conversation useful instead of noisy.

      +

      Alex: The next layer is this. Here is the plain-English version of 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,. Put another way, prerequisites: Working with Pull Requests, Git & Source Control in VS Code Mac keyboard shortcuts: Throughout this chapter, all Ctrl+ shortcuts use Cmd+ on Mac, and Alt+ shortcuts use Option+ on Mac. It is like learning a transit route. The names of the stops matter because they tell you whether you are still going the right direction.

      +

      Jamie: What should feel predictable before the first live session starts?

      +

      Alex: This is where Workshop Recommendation (Chapter 15, Part 1) becomes real: chapter 15, Part 1 introduces the GitHub Pull Requests extension for managing PRs directly from VS Code.

      +

      Alex: That shows up in the workshop in a few specific ways. There are 2 guided challenges. Automation check: none (extension installation and review state are account-local). The evidence is issue comment with confirmation of actions completed. The pattern is install, check out, review, comment.

      -

      Alex: Now bring the learner back to the room. Keep the learner anchored in Screen reader interactions inside the Find widget. Replace (Ctrl+H): Opens the Find widget with a second input for the replacement text.

      -

      Alex: For a learner, the useful signals are these. 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. Ctrl+Shift+1 - replace the current match. Ctrl+Alt+Enter - replace all matches at once.

      -

      Alex: A solid navigation habit is to prove where you are before activating controls. Headings, landmarks, and the address bar are not trivia; they are your map.

      -

      Jamie: What would you say to someone who is already bracing for this to be too much?

      -

      Alex: The reason Global Search Across the Workspace (Ctrl+Shift+F) matters is that the global Search panel has a rich filtering system - all keyboard-accessible.

      -

      Alex: The useful habit is simple: orient first, act second, verify third. That pause before acting is part of the work.

      +

      Jamie: Turn that into a path someone can follow.

      +

      Alex: Start with Chapter 15, Part 1 Practice Set. There is something to understand, something to try, and something that proves the try worked.

      +

      Alex: First, install the GitHub Pull Requests extension - add the extension to VS Code and sign in with your GitHub account. Then, check out a PR and post a review comment - download a PR branch locally, read the diff, and post one constructive review comment. It is like walking a hallway with named doors: read the sign, enter the right room, then confirm where you landed.

      +

      Jamie: What is the ordered workflow?

      +

      Alex: The reason Practice 15.1 Step-by-Step: Install the Extension matters is that install the GitHub Pull Requests and Issues extension and authenticate with your GitHub account. That gives the learner a simple foothold: VS Code desktop with your Learning Room repository open.

      +

      Alex: First, open the Extensions sidebar: Ctrl+Shift+X (Mac: Cmd+Shift+X). Then, your screen reader announces "Extensions: Marketplace." The search box has focus. After that, type GitHub Pull Requests in the search box and press Enter. Finally, navigate down the results list. Select GitHub Pull Requests (publisher: GitHub). The rhythm is simple: orient, act, verify, then continue.

      Jamie: Give me the sequence, because order matters here.

      -

      Alex: Start with Type-to-Filter in Tree Views: In the Explorer file tree and the Source Control changes list, type characters to narrow visible items. Think of it like entering a new building: first you find the lobby, then the room, then the door you actually need.

      -

      Alex: First, focus the Explorer (Ctrl+Shift+E). Then, start typing a filename - a filter input appears at the bottom of the tree. After that, the tree instantly narrows to matching files. Finally, press Escape to clear the filter and restore full view. Think of it as a rail line: each stop confirms you are still on the right route before the next one.

      +

      Alex: First, activate the Install button. VS Code installs the extension and may show a notification. Then, after installation, VS Code prompts you to sign in. Activate Sign in to GitHub. After that, a browser window opens for GitHub OAuth. Approve the authorization and return to VS Code. Finally, verify: open the Explorer sidebar (Ctrl+Shift+E). You should now see a GitHub section in the sidebar showing Pull Requests and Issues. Think of it as a rail line: each stop confirms you are still on the right route before the next one.

      +

      Jamie: How would you walk the room through that step by step?

      +

      Alex: Start with Practice 15.2 Step-by-Step: Check Out a PR and Post a Comment: Check out someone else's PR branch locally, read the diff in VS Code, and post one constructive review comment. The next useful detail is this: VS Code with the GitHub Pull Requests extension installed. Think of it like entering a new building: first you find the lobby, then the room, then the door you actually need.

      +

      Alex: First, open the Command Palette: Ctrl+Shift+P (Mac: Cmd+Shift+P). Then, type GitHub Pull Requests: Focus on Pull Requests View and select it. The Pull Requests panel opens. After that, navigate the list of open PRs. Find one that is not yours (a classmate's PR from Chapter 6, 7, or 14). Finally, 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. Think of it as a rail line: each stop confirms you are still on the right route before the next one.

      +

      Jamie: What does the learner do first, second, and then after that?

      +

      Alex: First, open the Command Palette again and run GitHub Pull Requests: Open Changed Files. This shows the list of files the PR changed. Then, open one changed file. VS Code opens the Diff Editor showing old content on the left and new content on the right. After that, 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). Finally, find one specific thing to comment on: a typo, an unclear sentence, a missing step, or something the author did well. Treat it like a recipe: do not add the next ingredient until the previous one is actually in the bowl.

      -

      Jamie: If I am listening before the workshop starts, what should settle in my mind first?

      -

      Alex: Here is the plain-English version of Go to Symbol with Inline Filtering (Ctrl+Shift+O). In any Markdown file, Ctrl+Shift+O opens a symbol picker populated by every heading. Put another way, type to narrow the list, then press Enter to jump.

      -

      Alex: This is where the talk moves from concept to action. Start with Learning Cards: Keyboard Navigation and Find. There is something to understand, something to try, and something that proves the try worked.

      -

      Alex: The room should hear these as checkpoints. 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. 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.

      -

      Jamie: Where do you want a learner to place their attention here?

      -

      Alex: Keep the learner anchored in 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.

      -

      Alex: A solid pull request habit is to separate three questions: what changed, why it changed, and what still needs review. That keeps the conversation useful instead of noisy.

      +

      Jamie: What should the learner prove to themselves after each small task?

      +

      Alex: Here is the plain-English version of Completing Chapter 15, Part 1: Submit Your Evidence. Open your assigned setup or review practice issue and post a completion comment. Put another way, close your Chapter 12 challenge issues when done.

      +

      Alex: The useful habit is simple: orient first, act second, verify third. That pause before acting is part of the work.

      +

      Alex: This is where the talk moves from concept to action. Start with Expected Outcomes. There is something to understand, something to try, and something that proves the try worked.

      +

      Alex: The room should hear these as checkpoints. 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.

      +

      Jamie: Let's pause on If You Get Stuck. What should a learner take away from it?

      +

      Alex: Keep the learner anchored in If You Get Stuck. Continue learning: The GitHub Skills course Review Pull Requests practices approving, requesting changes, and using suggestions in an interactive format. This is the part to say slowly: See Appendix Z for the full catalog.

      +

      Alex: First, extension does not install? Reload VS Code: Ctrl+Shift+P, then run Developer: Reload Window. Then, oAuth sign-in fails? Verify your GitHub account is active in the browser first, close VS Code, reopen, and retry. After that, pR list is empty? Switch to "All Open" view in the GitHub Pull Requests panel. Finally, checkout fails? Confirm you have write access to the repository. If not, use the read-only GitHub.com fallback. It is like walking a hallway with named doors: read the sign, enter the right room, then confirm where you landed.

      +

      Jamie: Before we leave If You Get Stuck, what is the practical point?

      +

      Alex: First, diff Editor is hard to navigate? Press F7 for the Accessible Diff Viewer mode, which is purpose-built for screen readers. Then, cannot find the Add Comment command? Use Command Palette and search for GitHub Pull Requests: Add Comment. After that, ask facilitator to help verify the GitHub PR panel and model one review comment. Finally, finished but not sure you did it right? Compare your work against the Challenge 11 reference solution. The rhythm is simple: orient, act, verify, then continue.

      -

      Alex: Before the learner moves on. Start with Opening the Problems Panel. There is something to understand, something to try, and something that proves the try worked.

      -

      Alex: That becomes easier when you listen for these cues. 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).

      -

      Jamie: Give me the version that sounds like an instructor, not a manual.

      -

      Alex: Start with Understanding Problem Entries. There is something to understand, something to try, and something that proves the try worked.

      -

      Alex: A few details make that real. 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.

      -

      Alex: Hold that next to this. Start with Learning Cards: Problems Panel. There is something to understand, something to try, and something that proves the try worked.

      -

      Alex: The practical anchors are these. 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. Problems are color-coded: red for errors, yellow for warnings, blue for info.

      +

      Alex: Before the learner moves on. The reason Learning Moment matters is that reviewing others' work refines your own standards and builds community trust. That gives the learner a simple foothold: the comment you just wrote helps another student learn - and you learn by articulating what makes documentation clear. The interface gets friendlier when it stops being a wall of controls and starts being a set of named places.

      +

      Jamie: Let's pause on Learning Pattern Used in This Chapter. What should a learner take away from it?

      +

      Alex: Start with Learning Pattern Used in This Chapter. There is something to understand, something to try, and something that proves the try worked.

      +

      Alex: First, install and configure the tool before starting the task. Then, practice on someone else's work first (reviewing is safer than authoring). After that, use accessibility tools (F7 Accessible Diff Viewer) to navigate efficiently. Finally, write specific, constructive feedback (not just "looks good"). Think of it as a rail line: each stop confirms you are still on the right route before the next one.

      +

      Alex: Hold that next to this. Here is the plain-English version of 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.

      -

      Jamie: Let's pause on 14. The Terminal. What should a learner take away from it?

      -

      Alex: This is where 14. The Terminal becomes real: VS Code includes a fully featured integrated terminal. That matters in practice: You can run shell commands, Git operations, and scripts without leaving the editor.

      -

      Alex: That connects to another useful point. Keep the learner anchored in Terminal Shell Integration. VS Code's shell integration enhances the terminal. This is the part to say slowly: Enable Terminal IntelliSense: Settings (Ctrl+,) then search terminal.integrated.suggest.enabled then set to on. A good GitHub workflow is like a well-run meeting: everyone knows the topic, the next action, and who has the floor.

      -

      Alex: The parts worth keeping in working memory are these. 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.

      -

      Jamie: Let's pause on Learning Cards: Terminal. What should a learner take away from it?

      -

      Alex: Start with Learning Cards: Terminal. There is something to understand, something to try, and something that proves the try worked.

      -

      Alex: On the ground, that means a few things. 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. VS Code enforces a minimum contrast ratio (4.5:1 by default) for terminal text.

      -
      -

      Alex: Here is the practical turn. Start with 15. Copilot Chat Window: The Copilot Chat window (Ctrl+Shift+I) is your conversational AI assistant within VS Code. The next useful detail is this: It can answer questions, generate code, explain code, fix problems, and help with documentation.

      -

      Jamie: Let's pause on Chat Modes. What should a learner take away from it?

      -

      Alex: Here is the plain-English version of Chat Modes. Switch modes using the mode picker at the top of the Chat view, or use keyboard shortcuts.

      -

      Alex: Here is what that changes in practice. workbench.action.chat.openAsk - Ask mode. workbench.action.chat.openEdit - Edit mode. workbench.action.chat.openAgent - Agent mode.

      -

      Alex: Keep the thread going. This is where Using Chat Participants becomes real: type @ in the chat input to see available participants. The workshop is closer to rehearsal than lecture. You hear the move, try the move, and then check what changed.

      -

      Alex: These are the details that keep the idea from floating away. @workspace - Ask questions about your entire codebase. @vscode - Ask about VS Code settings and features. @terminal - Run commands or explain terminal output.

      +

      Jamie: Let's pause on Method 1: Extensions Sidebar. What should a learner take away from it?

      +

      Alex: Start with Method 1: Extensions Sidebar. There is something to understand, something to try, and something that proves the try worked.

      +

      Alex: First, open Extensions sidebar: Ctrl+Shift+X (Mac: Cmd+Shift+X). Then, type "GitHub Pull Requests" in the search box. After that, find "GitHub Pull Requests and Issues" (publisher: GitHub). Finally, navigate to the extension in the results list. It is a checklist, but a meaningful one: every item creates evidence that the next step is safe.

      +

      Jamie: Before we leave Method 1: Extensions Sidebar, what is the practical point?

      +

      Alex: First, press Enter to open the extension detail page. Then, tab to "Install" button → press Enter. It is like walking a hallway with named doors: read the sign, enter the right room, then confirm where you landed.

      +

      Jamie: Let's pause on Method 2: Command Palette. What should a learner take away from it?

      +

      Alex: Keep the learner anchored in Method 2: Command Palette. The Extensions sidebar is a tree view. This is the part to say slowly: Use Up/Down Arrow to navigate, Enter to open an extension's detail page. A good GitHub workflow is like a well-run meeting: everyone knows the topic, the next action, and who has the floor.

      +

      Alex: First, ctrl+Shift+P. Then, type "install extensions". After that, select "Extensions: Install Extensions". Finally, search for "GitHub Pull Requests". It is like walking a hallway with named doors: read the sign, enter the right room, then confirm where you landed.

      +

      Jamie: Before we leave Method 2: Command Palette, what is the practical point?

      +

      Alex: First, install "GitHub Pull Requests and Issues". The rhythm is simple: orient, act, verify, then continue.

      +

      Jamie: Let's pause on Signing In to GitHub. What should a learner take away from it?

      +

      Alex: The reason Signing In to GitHub matters is that after installation, VS Code prompts you to sign in.

      +

      Alex: First, a notification appears: "Sign in to GitHub to use Pull Requests". Then, navigate to the notification (Alt+N / Mac: Option+N, or status bar navigation). After that, select "Sign in". Finally, VS Code opens your browser for GitHub OAuth authentication. The rhythm is simple: orient, act, verify, then continue.

      +

      Jamie: Before we leave Signing In to GitHub, what is the practical point?

      +

      Alex: First, authorize VS Code in the browser. Then, return to VS Code - you're now signed in. Think of it as a rail line: each stop confirms you are still on the right route before the next one.

      -

      Jamie: Let's pause on Learning Cards: Copilot Chat. What should a learner take away from it?

      -

      Alex: Start with Learning Cards: Copilot Chat. There is something to understand, something to try, and something that proves the try worked.

      -

      Alex: That shows up in the workshop in a few specific ways. 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. The Chat view appears in the sidebar and respects your zoom level and font settings.

      -

      Alex: Another way to ground it. The reason Agent Mode: Question Carousel and Terminal Focus matters is that 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. That gives the learner a simple foothold: the carousel shows what the terminal is asking and lets you respond without switching focus to the terminal manually.

      -

      Jamie: What do you want them to do when the plan breaks?

      -

      Alex: Start with 16. Accessible Help, Accessible View, and Accessible Diff: See also: Appendix G: VS Code Reference has a complete keyboard shortcut reference for all VS Code accessibility features. The next useful detail is this: 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.

      +

      Alex: Here is the practical turn. Start with Verify sign-in. There is something to understand, something to try, and something that proves the try worked.

      +

      Alex: On the ground, that means a few things. 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.

      +

      Jamie: What would you say to someone who is already bracing for this to be too much?

      +

      Alex: Start with What the Extension Adds. There is something to understand, something to try, and something that proves the try worked.

      +

      Alex: Here is what that changes in practice. 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.

      +

      Alex: Keep the thread going. Start with Learning Cards: Installing the PR Extension. There is something to understand, something to try, and something that proves the try worked.

      +

      Alex: These are the details that keep the idea from floating away. 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". 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.

      -

      Alex: This is the part worth saying out loud. Here is the plain-English version of 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. Put another way, accessible Help surfaces those commands in a plain-text, fully readable dialog, tailored to exactly where your focus is right now. It is like learning a transit route. The names of the stops matter because they tell you whether you are still going the right direction.

      -

      Jamie: How should someone ask for help in a way that gets them unstuck faster?

      -

      Alex: This is where How to open Accessible Help becomes real: the dialog is announced with a heading and a complete list of keyboard shortcuts for that specific widget. That matters in practice: Press Escape to dismiss and return focus to where you were.

      -

      Jamie: What should happen before anyone copies and runs it?

      -

      Alex: Keep the learner anchored in Example output when pressing Alt+H in the editor. Use Accessible Help as your first action whenever you land somewhere new in VS Code.

      -

      Alex: Treat examples as spoken recipes, not decorations. You may hear something like 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. Read the command, understand what it changes, then run it only when the repository state matches the lesson.

      +

      Jamie: Let's pause on Method 1: Activity Bar. What should a learner take away from it?

      +

      Alex: Keep the learner anchored in Method 1: Activity Bar. Click the GitHub logo icon in the Activity Bar (the vertical strip of icons on the far left). This is the part to say slowly: The GitHub Pull Requests panel opens.

      +

      Alex: That becomes easier when you listen for these cues. "Pull Requests". "Issues".

      +

      Alex: First, the Activity Bar is not always reachable by Tab from the editor. Then, use Ctrl+Shift+P (Mac: Cmd+Shift+P) → type "GitHub Pull Requests: View Pull Request" or "Focus on Pull Requests View" → press Enter. After that, alternatively press Ctrl+Shift+G (Mac: Cmd+Shift+G) to open Source Control, then Tab until you reach the Activity Bar icon strip. Finally, navigate to the repository on GitHub.com. It is like walking a hallway with named doors: read the sign, enter the right room, then confirm where you landed.

      +

      Jamie: Before we leave Method 1: Activity Bar, what is the practical point?

      +

      Alex: First, click the Pull requests tab. Then, click any PR title to view its conversation, commits, and changed files. After that, use the Files changed tab to review diffs. The rhythm is simple: orient, act, verify, then continue.

      +

      Alex: Treat examples as spoken recipes, not decorations. You may hear something like 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". Read the command, understand what it changes, then run it only when the repository state matches the lesson.

      +

      Jamie: Let's pause on Method 2: Explorer Section. What should a learner take away from it?

      +

      Alex: Start with Method 2: Explorer Section. There is something to understand, something to try, and something that proves the try worked.

      +

      Alex: First, open Explorer: Ctrl+Shift+E (Mac: Cmd+Shift+E). Then, navigate with Arrow keys to find the "GitHub Pull Requests" section. After that, expand it with Right Arrow. The rhythm is simple: orient, act, verify, then continue.

      +

      Jamie: What is the one idea that makes the next few steps less mysterious?

      +

      Alex: Start with Description: The GitHub Pull Requests panel has two top-level sections. The next useful detail is this: "My Pull Requests" contains four filters: Assigned to Me, Created by Me, Waiting for my Review, and All Open.

      -

      Jamie: Let's pause on 16.2 Accessible View - Reading Dynamic and Streamed Content. What should a learner take away from it?

      -

      Alex: The reason 16.2 Accessible View - Reading Dynamic and Streamed Content matters is that 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.

      -

      Jamie: How would you walk the room through that step by step?

      -

      Alex: Start with Recommended workflow for Copilot Chat. There is something to understand, something to try, and something that proves the try worked.

      -

      Alex: First, type your prompt in the Chat input. Then, wait for the response to finish (NVDA: live region announcements stop; JAWS: typing indicator disappears; VoiceOver: busy state clears). After that, press Alt+F2 - Accessible View opens with the complete response. Finally, navigate with Up/Down Arrow through the response. Think of it as a rail line: each stop confirms you are still on the right route before the next one.

      -

      Jamie: What does the learner do first, second, and then after that?

      -

      Alex: First, press Escape to return to the chat input. Treat it like a recipe: do not add the next ingredient until the previous one is actually in the bowl.

      -

      Jamie: Turn that into a path someone can follow.

      -

      Alex: Start with Recommended workflow for hover documentation. There is something to understand, something to try, and something that proves the try worked.

      -

      Alex: First, navigate to a symbol or link with keyboard. Then, press Ctrl+K I to trigger hover programmatically (no mouse needed). After that, press Alt+F2 to open Accessible View with the full hover content. Finally, press Escape to dismiss. Treat it like a recipe: do not add the next ingredient until the previous one is actually in the bowl.

      +

      Alex: This is the part worth saying out loud. Here is the plain-English version of Screen reader announcement example. "Pull Request 42: Add Timeline Guide, opened by jeffb, 2 days ago, 3 files changed". It is like learning a transit route. The names of the stops matter because they tell you whether you are still going the right direction.

      +

      Alex: A solid navigation habit is to prove where you are before activating controls. Headings, landmarks, and the address bar are not trivia; they are your map.

      +

      Jamie: Give me the version that sounds like an instructor, not a manual.

      +

      Alex: Start with By status. There is something to understand, something to try, and something that proves the try worked.

      +

      Alex: For a learner, the useful signals are these. "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.

      +

      Alex: That connects to another useful point. Keep the learner anchored in By repository. The tree organizes PRs by repository.

      -

      Alex: That matters because of the next idea. This is where 16.3 Accessible Diff Viewer - Reading Changes Without Visual Scanning becomes real: 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. That matters in practice: For screen reader users, tracking which lines changed and how can be difficult without a structured reading mode.

      -

      Jamie: What should they understand before typing anything?

      -

      Alex: Keep the learner anchored in What the Accessible Diff Viewer announces. For each hunk (a block of related changes), the viewer announces. This is the part to say slowly: This gives you the complete picture of what changed, in reading order, without visual diff scanning.

      -

      Alex: The practical takeaway is this. The hunk number and total hunk count (Hunk 2 of 5). The line range affected. Each line, prefixed with its change type.

      -

      Alex: Treat examples as spoken recipes, not decorations. You may hear something like 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. Read the command, understand what it changes, then run it only when the repository state matches the lesson.

      -

      Alex: Keep the teaching thread moving. Start with Practical uses during this workshop. There is something to understand, something to try, and something that proves the try worked.

      -

      Alex: The practical takeaway is this. 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.

      +

      Jamie: Let's pause on Viewing PR Details. What should a learner take away from it?

      +

      Alex: The reason Viewing PR Details matters is that a PR detail view opens in the editor area showing.

      +

      Alex: The parts worth keeping in working memory are these. 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).

      +

      Alex: First, navigate to a PR in the tree. Then, press Enter. The rhythm is simple: orient, act, verify, then continue.

      +

      Alex: Now bring the learner back to the room. Start with Screen reader experience. There is something to understand, something to try, and something that proves the try worked.

      +

      Alex: A few details make that real. 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.

      +

      Jamie: Where do you want a learner to place their attention here?

      +

      Alex: Here is the plain-English version of 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.

      -

      Jamie: Let's pause on Audio cues for diffs. What should a learner take away from it?

      -

      Alex: Start with 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). The next useful detail is this: You receive change-type information through sound before the line text is announced.

      -

      Alex: Keep the teaching thread moving. Start with Learning Cards: Accessible Help, View, and Diff. There is something to understand, something to try, and something that proves the try worked.

      -

      Alex: The practical takeaway is this. 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. 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.

      -

      Jamie: Let's pause on 17. Accessibility Signals. What should a learner take away from it?

      -

      Alex: This is where 17. Accessibility Signals becomes real: 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. That matters in practice: Signals replaced the older "Audio Cues" system (deprecated since VS Code 1.85) and are significantly more powerful.

      +

      Alex: That matters because of the next idea. Start with Why Check Out a PR. There is something to understand, something to try, and something that proves the try worked.

      +

      Alex: The practical anchors are these. 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.

      +

      Jamie: Let's pause on Method 1: From the PR Detail View. What should a learner take away from it?

      +

      Alex: Start with Method 1: From the PR Detail View. There is something to understand, something to try, and something that proves the try worked.

      +

      Alex: The practical takeaway is this. Downloads the branch. Switches your local repository to that branch. Opens the changed files in the editor.

      +

      Alex: First, open a PR (see Section 2). Then, in the PR detail view, navigate to "Checkout" button. After that, press Enter. It is like walking a hallway with named doors: read the sign, enter the right room, then confirm where you landed.

      +

      Jamie: Let's pause on Method 2: From the PR Tree. What should a learner take away from it?

      +

      Alex: Start with Method 2: From the PR Tree. There is something to understand, something to try, and something that proves the try worked.

      +

      Alex: First, navigate to the PR in the GitHub Pull Requests tree. Then, press Shift+F10 (Mac: Ctrl+Return) to open context menu. After that, select "Checkout Pull Request". The rhythm is simple: orient, act, verify, then continue.

      -

      Alex: Keep the teaching thread moving. Keep the learner anchored in How Signals Work: The Dual-Channel Architecture. Every accessibility signal has two independent channels that you control separately. This is the part to say slowly: Each channel accepts one of these values. A good GitHub workflow is like a well-run meeting: everyone knows the topic, the next action, and who has the floor.

      -

      Jamie: What should someone listen for when a lesson offers more than one tool path?

      -

      Alex: The reason Discovering Signals: The Two Essential Commands matters is that 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. That gives the learner a simple foothold: these are the fastest way to configure signals.

      -

      Alex: Keep the teaching thread moving. Start with Volume Control: Control signal volume independently from your system volume. The next useful detail is this: Set this in Settings (Ctrl+,) by searching "signal volume" or add it to settings.json.

      +

      Jamie: Let's pause on Method 3: Command Palette. What should a learner take away from it?

      +

      Alex: Start with Method 3: Command Palette: After checkout, the bottom-left status bar shows the branch name (example: "jeffb/add-timeline-guide"). The next useful detail is this: Your local files now match that branch.

      +

      Alex: First, ctrl+Shift+P (Mac: Cmd+Shift+P). Then, type "GitHub Pull Requests: Checkout". After that, select "GitHub Pull Requests: Checkout Pull Request". Finally, choose the PR from the list. Think of it as a rail line: each stop confirms you are still on the right route before the next one.

      +

      Jamie: Let's pause on Returning to Your Original Branch. What should a learner take away from it?

      +

      Alex: Start with Returning to Your Original Branch. There is something to understand, something to try, and something that proves the try worked.

      +

      Alex: First, ctrl+Shift+P (Mac: Cmd+Shift+P). Then, type "git checkout". After that, select "Git: Checkout to.". Finally, choose your original branch (usually main or your feature branch). Treat it like a recipe: do not add the next ingredient until the previous one is actually in the bowl.

      +

      Alex: A solid Git habit is to know which branch you are on, what changed, and what confirmation you expect before you run the next command.

      +

      Jamie: If I am listening before the workshop starts, what should settle in my mind first?

      +

      Alex: Start with Learning Cards: Checking Out a PR. There is something to understand, something to try, and something that proves the try worked.

      +

      Alex: The practical takeaway is this. 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. 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.

      -

      Jamie: Let's pause on Complete Signal Reference. What should a learner take away from it?

      -

      Alex: Here is the plain-English version of Complete Signal Reference. VS Code registers 30+ accessibility signals organized into categories. Put another way, the tables below list every signal, its setting key, the sound it plays, and whether it supports announcements.

      -

      Alex: Keep the teaching thread moving. This is where Editor Signals becomes real: these fire when your cursor moves to a line or position with a specific marker. That matters in practice: Line vs Position signals: The lineHasError signal fires once when your cursor enters the line. The workshop is closer to rehearsal than lecture. You hear the move, try the move, and then check what changed.

      -

      Jamie: Let's pause on Diff Signals. What should a learner take away from it?

      -

      Alex: Keep the learner anchored in Diff Signals. These fire when navigating changes in the diff editor or reviewing pull requests. This is the part to say slowly: These are critical for pull request review.

      +

      Alex: Another way to ground it. Keep the learner anchored in 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. A good GitHub workflow is like a well-run meeting: everyone knows the topic, the next action, and who has the floor.

      +

      Jamie: Let's pause on In the PR detail view. What should a learner take away from it?

      +

      Alex: Start with In the PR detail view. There is something to understand, something to try, and something that proves the try worked.

      +

      Alex: First, scroll down to "Files Changed" section. Then, each file is a link. After that, navigate with Arrow keys. Finally, press Enter on a file to open its diff view. The rhythm is simple: orient, act, verify, then continue.

      +

      Alex: Keep the teaching thread moving. Start with Screen reader announcement: "docs/11-vscode-interface.md, 42 additions, 3 deletions".

      -

      Alex: Keep the teaching thread moving. The reason Terminal Signals matters is that enable taskCompleted and taskFailed immediately. That gives the learner a simple foothold: when you run git push or npm test in the terminal, you hear whether it succeeded without switching back to the terminal panel.

      -

      Jamie: Let's pause on Chat and Copilot Signals. What should a learner take away from it?

      -

      Alex: Start with Chat and Copilot Signals: chatResponseReceived plays a randomly chosen variant each time (responseReceived1 through responseReceived4). The next useful detail is this: This prevents habituation -- your brain stays alert to the signal instead of filtering it out after hearing the same sound repeatedly.

      -

      Alex: Keep the teaching thread moving. Here is the plain-English version of Editor Action Signals. These fire on user-triggered actions and use the "userGesture" value to distinguish manual saves from auto-saves. Put another way, set these to "userGesture" rather than "on" if auto-save is enabled, to avoid a sound on every keystroke pause. It is like learning a transit route. The names of the stops matter because they tell you whether you are still going the right direction.

      +

      Jamie: Let's pause on Understanding the Diff View. What should a learner take away from it?

      +

      Alex: Here is the plain-English version of Understanding the Diff View. When you open a file from "Files Changed".

      +

      Alex: Keep the teaching thread moving. Start with Split view mode (default). There is something to understand, something to try, and something that proves the try worked.

      +

      Alex: The practical takeaway is this. Left side: original file (before changes). Right side: modified file (after changes). Changed lines highlighted (added = green, removed = red).

      +

      Jamie: Let's pause on Inline view mode. What should a learner take away from it?

      +

      Alex: Start with Inline view mode. There is something to understand, something to try, and something that proves the try worked.

      +

      Alex: The practical takeaway is this. Single editor. Removed lines shown with - prefix. Added lines shown with + prefix.

      -

      Jamie: Let's pause on Debounce Settings for Position Signals. What should a learner take away from it?

      -

      Alex: This is where Debounce Settings for Position Signals becomes real: 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. That matters in practice: VS Code debounces these by default.

      -

      Alex: Keep the teaching thread moving. Keep the learner anchored in Recommended Workshop Profile. Add this to your VS Code settings.json (Ctrl+Shift+P then "Preferences: Open User Settings (JSON)"). This is the part to say slowly: This profile enables core sounds for everyone and sets announcements to auto so they activate only when a screen reader is detected.

      -

      Alex: The practical takeaway is this. 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.

      -

      Jamie: Let's pause on Migrating from Legacy Audio Cues. What should a learner take away from it?

      -

      Alex: The reason Migrating from Legacy Audio Cues matters is that if you previously configured the older audioCues. That gives the learner a simple foothold: settings (deprecated since VS Code 1.85), VS Code automatically maps them to the new accessibility.signals.

      +

      Alex: Keep the teaching thread moving. Start with To toggle between views. There is something to understand, something to try, and something that proves the try worked.

      +

      Alex: The practical takeaway is this. Command Palette: Ctrl+Shift+P (Mac: Cmd+Shift+P) → "Diff: Toggle Inline View".

      +

      Jamie: Let's pause on Recommended workflow for screen reader users. What should a learner take away from it?

      +

      Alex: Start with Recommended workflow for screen reader users. There is something to understand, something to try, and something that proves the try worked.

      +

      Alex: The practical takeaway is this. Unchanged lines (for context). Removed lines (prefixed with -). Added lines (prefixed with +).

      +

      Alex: First, open a changed file from the PR detail view. Then, press F7 to jump to the first diff hunk. After that, press Alt+F2 (Mac: Option+F2) to open Accessible View. Finally, read the hunk content. Think of it as a rail line: each stop confirms you are still on the right route before the next one.

      +

      Jamie: Before we leave Recommended workflow for screen reader users, what is the practical point?

      +

      Alex: First, press Escape to close Accessible View. Then, press F7 to jump to the next hunk. After that, repeat until all hunks reviewed. Treat it like a recipe: do not add the next ingredient until the previous one is actually in the bowl.

      +

      Alex: Keep the teaching thread moving. Here is the plain-English version of 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. Put another way, previously, deleted code could only be read, not selected. It is like learning a transit route. The names of the stops matter because they tell you whether you are still going the right direction.

      -

      Alex: Keep the teaching thread moving. Start with Learning Cards: Accessibility Signals. There is something to understand, something to try, and something that proves the try worked.

      -

      Alex: The practical takeaway is this. 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. 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.

      -

      Jamie: How do we make tool choice feel like access, not pressure?

      -

      Alex: Here is the plain-English version of 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. Put another way, all voice processing happens locally on your machine - no audio data is sent to any online service.

      -

      Jamie: What is the ordered workflow?

      -

      Alex: This is where Installing VS Code Speech becomes real: after installation, a microphone icon appears in all Chat input fields and new voice commands become available in the Command Palette. That matters in practice: Microphone permissions: On macOS, go to System Settings, Privacy and Security, Microphone, and confirm Visual Studio Code is enabled.

      -

      Alex: First, open Extensions: Ctrl+Shift+X (Mac: Cmd+Shift+X). Then, search for VS Code Speech. After that, find VS Code Speech (publisher: Microsoft, identifier: ms-vscode.vscode-speech). Finally, press Enter to open the extension detail page, then Tab to "Install" and press Enter. It is a checklist, but a meaningful one: every item creates evidence that the next step is safe.

      +

      Jamie: Let's pause on Flagging Issues During Review. What should a learner take away from it?

      +

      Alex: This is where Flagging Issues During Review becomes real: start Review saves your comments as a draft until you submit the full review (see Section 7).

      +

      Alex: First, navigate to the specific line in the diff. Then, press Shift+F10 (Mac: Ctrl+Return) for context menu. After that, select "Add Comment". Finally, type your comment in the input that appears. It is a checklist, but a meaningful one: every item creates evidence that the next step is safe.

      +

      Jamie: Before we leave Flagging Issues During Review, what is the practical point?

      +

      Alex: First, choose "Single Comment" or "Start Review". It is like walking a hallway with named doors: read the sign, enter the right room, then confirm where you landed.

      +

      Alex: A solid issue habit is to read the title, the body, and the timeline before acting. You are listening for the requested action, the missing evidence, and the person who needs a response.

      +

      Alex: Keep the teaching thread moving. Start with Learning Cards: Reviewing Pull Requests in VS Code. There is something to understand, something to try, and something that proves the try worked.

      +

      Alex: The practical takeaway is this. 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. 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.

      +

      Jamie: Let's pause on Tool Cards: Create a Pull Request (from your editor). What should a learner take away from it?

      +

      Alex: The reason Tool Cards: Create a Pull Request (from your editor) matters is that VS Code Desktop (primary for Day 2). That gives the learner a simple foothold: after you've pushed commits to a feature branch, you can create a PR without leaving VS Code.

      +

      Alex: First, ctrl+Shift+P GitHub Pull Requests: Create Pull Request. Then, fill in the title, description, and base branch. After that, click Create. Finally, push your branch, then click the Compare & pull request banner on the repo page. The rhythm is simple: orient, act, verify, then continue.

      +

      Jamie: Before we leave Tool Cards: Create a Pull Request (from your editor), what is the practical point?

      +

      Alex: First, fill in the form and click Create pull request. Then, after pushing, click Create Pull Request -- this opens gitub.com with the form pre-filled. Think of it as a rail line: each stop confirms you are still on the right route before the next one.

      +

      Alex: Treat examples as spoken recipes, not decorations. You may hear something like git push -u origin your-branch; gh pr create --title "Title" --body "Description". Read the command, understand what it changes, then run it only when the repository state matches the lesson.

      -

      Jamie: Let's pause on Editor Dictation - Type with Your Voice. What should a learner take away from it?

      -

      Alex: Keep the learner anchored in Editor Dictation - Type with Your Voice. Editor dictation lets you speak and have your words appear as text wherever your cursor is. This is the part to say slowly: This works in the code editor, the SCM commit input box, and the comments field when reviewing pull requests.

      -

      Alex: The practical takeaway is this. 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.

      -

      Alex: Keep the teaching thread moving. The reason Voice in Copilot Chat - Talk to Copilot matters is that instead of typing prompts, you can speak them. That gives the learner a simple foothold: this works in the Chat panel, inline chat, and quick chat. The interface gets friendlier when it stops being a wall of controls and starts being a set of named places.

      -

      Alex: The practical takeaway is this. 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.

      -

      Jamie: Let's pause on Text-to-Speech - Listen to Chat Responses. What should a learner take away from it?

      -

      Alex: Start with Text-to-Speech - Listen to Chat Responses: VS Code Speech can read Copilot Chat responses aloud. The next useful detail is this: Each chat response shows a speaker icon you can activate to hear that specific response.

      +

      Jamie: Let's pause on Prerequisites. What should a learner take away from it?

      +

      Alex: Start with Prerequisites. There is something to understand, something to try, and something that proves the try worked.

      +

      Alex: First, you've created a branch (see Git & Source Control: Branch Management). Then, you've made commits. After that, you've pushed the branch to GitHub (Ctrl+Shift+P / Mac: Cmd+Shift+P → "Git: Push"). Think of it as a rail line: each stop confirms you are still on the right route before the next one.

      +

      Jamie: Let's pause on Method 1: Command Palette (Recommended). What should a learner take away from it?

      +

      Alex: Start with Method 1: Command Palette (Recommended). There is something to understand, something to try, and something that proves the try worked.

      +

      Alex: First, ctrl+Shift+P (Mac: Cmd+Shift+P). Then, type "GitHub Pull Requests: Create". After that, select "GitHub Pull Requests: Create Pull Request". Finally, a form opens in the editor. Treat it like a recipe: do not add the next ingredient until the previous one is actually in the bowl.

      +

      Jamie: Let's pause on Method 2: Source Control Panel. What should a learner take away from it?

      +

      Alex: Start with Method 2: Source Control Panel. There is something to understand, something to try, and something that proves the try worked.

      +

      Alex: First, open Source Control: Ctrl+Shift+G (Mac: Cmd+Shift+G). Then, after pushing, a "Create Pull Request" button appears. After that, press Enter on that button. It is a checklist, but a meaningful one: every item creates evidence that the next step is safe.

      -

      Jamie: Let's pause on Automatic read-aloud after voice input. What should a learner take away from it?

      -

      Alex: Here is the plain-English version of 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.

      -

      Alex: First, you speak a question using voice chat. Then, Copilot responds in text. After that, the response is automatically read aloud. Finally, to stop playback mid-sentence, press Escape or activate the stop icon. Treat it like a recipe: do not add the next ingredient until the previous one is actually in the bowl.

      -

      Jamie: Let's pause on Manual read-aloud for any response. What should a learner take away from it?

      -

      Alex: This is where Manual read-aloud for any response becomes real: even without autoSynthesize, every Chat response has a speaker icon. That matters in practice: Activate it to hear that specific response read aloud.

      -

      Alex: The practical takeaway is this. 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.

      -

      Alex: Keep the teaching thread moving. Keep the learner anchored in "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. This is the part to say slowly: 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. A good GitHub workflow is like a well-run meeting: everyone knows the topic, the next action, and who has the floor.

      +

      Jamie: Let's pause on Method 3: GitHub Panel. What should a learner take away from it?

      +

      Alex: Start with Method 3: GitHub Panel. There is something to understand, something to try, and something that proves the try worked.

      +

      Alex: First, open GitHub view (Activity Bar → GitHub icon). Then, right-click your branch in the tree. After that, select "Create Pull Request". It is like walking a hallway with named doors: read the sign, enter the right room, then confirm where you landed.

      +

      Alex: Keep the teaching thread moving. Start with Title (required). There is something to understand, something to try, and something that proves the try worked.

      +

      Alex: The practical takeaway is this. Auto-filled with your most recent commit message. Edit to make it descriptive (example: "Add Timeline View documentation").

      +

      Jamie: Let's pause on Description (optional but recommended). What should a learner take away from it?

      +

      Alex: Start with Description (optional but recommended). There is something to understand, something to try, and something that proves the try worked.

      +

      Alex: The practical takeaway is this. 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.

      -

      Jamie: Let's pause on Language Configuration. What should a learner take away from it?

      -

      Alex: The reason Language Configuration matters is that VS Code Speech supports 26 languages. That gives the learner a simple foothold: by default it matches your VS Code display language.

      -

      Jamie: How do you keep commands from becoming magic words?

      -

      Alex: Start with Custom Keybindings for Voice: You can assign your own shortcuts for voice commands. The next useful detail is this: Open the Keyboard Shortcuts editor (Ctrl+K Ctrl+S) and search for "voice" or "dictation".

      -

      Alex: Treat examples as spoken recipes, not decorations. You may hear something like [; {; "key": "ctrl+u",; "command": "workbench.action.chat.startVoiceChat",; "when": "!voiceChatInProgress"; },; {; "key": "ctrl+u",; "command": "workbench.action.chat.stopListeningAndSubmit",; "when": "voiceChatInProgress"; },; {; "key": "ctrl+d",; "command". Read the command, understand what it changes, then run it only when the repository state matches the lesson.

      -

      Jamie: Let's pause on Supported Platforms. What should a learner take away from it?

      -

      Alex: Here is the plain-English version of Supported Platforms. On Linux, the extension requires the ALSA shared library (libasound). Put another way, install it with sudo apt install libasound2 on Debian/Ubuntu if it is not already present.

      +

      Alex: Keep the teaching thread moving. Start with Base branch (target). There is something to understand, something to try, and something that proves the try worked.

      +

      Alex: The practical takeaway is this. Usually main or develop. This is the branch your changes will merge into.

      +

      Jamie: Let's pause on Compare branch (source). What should a learner take away from it?

      +

      Alex: Start with Compare branch (source). There is something to understand, something to try, and something that proves the try worked.

      +

      Alex: The practical takeaway is this. Your feature branch (auto-selected). This is the branch with your changes.

      +

      Alex: Keep the teaching thread moving. Start with Reviewers (optional). There is something to understand, something to try, and something that proves the try worked.

      +

      Alex: The practical takeaway is this. Select people to review your PR. Navigate the list with Arrow keys.

      -

      Alex: Keep the teaching thread moving. This is where 19. Markdown Authoring in VS Code becomes real: you write Markdown in nearly every challenge of this workshop -- issue descriptions, pull request bodies, README updates, and agent files. That matters in practice: 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. The workshop is closer to rehearsal than lecture. You hear the move, try the move, and then check what changed.

      -

      Jamie: Let's pause on Markdown Preview. What should a learner take away from it?

      -

      Alex: Keep the learner anchored in Markdown Preview. VS Code includes a live Markdown preview so you can see rendered output alongside your source. This is the part to say slowly: The preview pane renders HTML, so your screen reader announces headings, links, and list items using their semantic roles.

      -

      Alex: The practical takeaway is this. 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.

      -

      Jamie: Let's pause on The markdownlint Extension. What should a learner take away from it?

      -

      Alex: The reason The markdownlint Extension matters is that the markdownlint extension (identifier: DavidAnson.vscode-markdownlint) catches common Markdown mistakes as you type, the same way a spell checker catches typos. That gives the learner a simple foothold: once installed, problems appear as wavy underlines in the editor and as entries in the Problems panel (Ctrl+Shift+M).

      -

      Alex: The practical takeaway is this. 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.

      -

      Alex: First, open Extensions: Ctrl+Shift+X (Mac: Cmd+Shift+X). Then, search for markdownlint. After that, install the one by David Anson. The rhythm is simple: orient, act, verify, then continue.

      +

      Jamie: Let's pause on Labels (optional). What should a learner take away from it?

      +

      Alex: Start with Labels (optional). There is something to understand, something to try, and something that proves the try worked.

      +

      Alex: The practical takeaway is this. Add labels like documentation, accessibility, good-first-issue.

      +

      Alex: Keep the teaching thread moving. Start with Milestone (optional). There is something to understand, something to try, and something that proves the try worked.

      +

      Alex: The practical takeaway is this. Link the PR to a project milestone.

      +

      Jamie: Let's pause on Draft PR checkbox. What should a learner take away from it?

      +

      Alex: Start with Draft PR checkbox. There is something to understand, something to try, and something that proves the try worked.

      +

      Alex: The practical takeaway is this. Check this if the PR is not ready for review yet. Unchecked = "Ready for review".

      -

      Jamie: Let's pause on Outline View for Headings. What should a learner take away from it?

      -

      Alex: Start with 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. The next useful detail is this: 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.

      -

      Alex: The practical takeaway is this. 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.

      -

      Alex: Keep the teaching thread moving. Here is the plain-English version of Copilot Markdown Assistance. If you have GitHub Copilot enabled (see Chapter 16), it can help with Markdown authoring directly in the editor. Put another way, these features save time when you are writing issue descriptions or pull request bodies during the workshop challenges. It is like learning a transit route. The names of the stops matter because they tell you whether you are still going the right direction.

      -

      Alex: The practical takeaway is this. 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, 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.

      -

      Jamie: What should feel predictable before the first live session starts?

      -

      Alex: This is where Why This Matters for the Workshop becomes real: students write Markdown in every single challenge -- from the very first issue you file in Chapter 5 to the agent file you create in Chapter 20. That matters in practice: Markdown is also how you write pull request descriptions (Chapter 6) and README files.

      +

      Alex: Keep the teaching thread moving. Start with Screen reader navigation. There is something to understand, something to try, and something that proves the try worked.

      +

      Alex: The practical takeaway is this. All fields are standard form inputs. Tab to move between fields. Use Arrow keys in dropdowns (reviewers, labels, milestones).

      +

      Jamie: Let's pause on Submitting the PR. What should a learner take away from it?

      +

      Alex: Keep the learner anchored in Submitting the PR. VS Code creates the PR on GitHub and shows a success message. This is the part to say slowly: The PR link appears in the notification - click it to open the PR on GitHub, or open it in the GitHub Pull Requests panel.

      +

      Alex: First, review all fields. Then, tab to "Create" button. After that, press Enter. Finally, navigate to the repository on GitHub. It is like walking a hallway with named doors: read the sign, enter the right room, then confirm where you landed.

      +

      Jamie: Before we leave Submitting the PR, what is the practical point?

      +

      Alex: First, if you recently pushed, a yellow banner "Compare & pull request" appears - click it. Then, otherwise: click Pull requests tab, then New pull request, then select your branch. After that, fill in the title and description. Finally, click Create pull request. The rhythm is simple: orient, act, verify, then continue.

      +

      Alex: Treat examples as spoken recipes, not decorations. You may hear something like 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. Read the command, understand what it changes, then run it only when the repository state matches the lesson.

      +

      Alex: Keep the teaching thread moving. Start with Learning Cards: Creating a Pull Request. There is something to understand, something to try, and something that proves the try worked.

      +

      Alex: The practical takeaway is this. 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. 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.

      -

      Alex: Keep the teaching thread moving. Keep the learner anchored in If You Get Stuck. Next: Chapter 13: How Git Works Back: Chapter 11: VS Code Interface Related appendices: Appendix G: VS Code Reference.

      +

      Jamie: Let's pause on 6. Pull Request Description Templates. What should a learner take away from it?

      +

      Alex: Start with 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.

      +

      Alex: Keep the teaching thread moving. Here is the plain-English version of Where Templates Are Stored. When you create a PR in VS Code, the extension automatically loads the template into the description field. It is like learning a transit route. The names of the stops matter because they tell you whether you are still going the right direction.

      +

      Alex: The practical takeaway is this.github/pull request template.md (root).github/PULL REQUEST TEMPLATE.md.github/PULL REQUEST TEMPLATE/ (folder with multiple templates). docs/pull request template.md.

      +

      Jamie: What is the safe way to learn from that example?

      +

      Alex: Start with Example PR Template. There is something to understand, something to try, and something that proves the try worked.

      +

      Alex: Treat examples as spoken recipes, not decorations. You may hear something like 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,. Read the command, understand what it changes, then run it only when the repository state matches the lesson.

      -

      Jamie: What should people carry with them after this?

      -

      Alex: Carry the map. Know what page or tool you are in, know which action you are taking, and know what confirmation should follow. If the confirmation is missing, pause. That pause is not wasted time; it is professional judgment.

      -

      Jamie: That is a better way to say it than just follow the steps.

      -

      Alex: Right. Steps matter, but understanding wins. That is episode 45. Next in the series is episode 46, where we keep building the same contributor muscles.

      -
      - +

      Jamie: Let's pause on Screen reader workflow. What should a learner take away from it?

      +

      Alex: Keep the learner anchored in Screen reader workflow. Keyboard tip: Use Ctrl+F (Mac: Cmd+F) to jump to each <!-- placeholder, fill it in, then F3 to jump to the next one.

      +

      Alex: First, create PR (Method 1-3 from Section 5). Then, the description field is pre-filled with the template. After that, navigate through the template with Arrow keys. Finally, replace each `` with your content. It is like walking a hallway with named doors: read the sign, enter the right room, then confirm where you landed.

      +

      Jamie: Before we leave Screen reader workflow, what is the practical point?

      +

      Alex: First, check checkboxes by typing x between the brackets: - [x]. The rhythm is simple: orient, act, verify, then continue.

      +

      Jamie: Let's pause on 7. Commenting and Requesting Changes. What should a learner take away from it?

      +

      Alex: Start with 7. Commenting and Requesting Changes. There is something to understand, something to try, and something that proves the try worked.

      +

      Alex: The practical takeaway is this. Leave inline comments on specific lines. Request changes before the PR can be merged. Approve the PR. Submit general feedback.

      +

      Jamie: Let's pause on Adding an Inline Comment. What should a learner take away from it?

      +

      Alex: Start with Adding an Inline Comment. There is something to understand, something to try, and something that proves the try worked.

      +

      Alex: First, open a file from the PR's "Files Changed" list. Then, navigate to the line you want to comment on. After that, press Shift+F10 (Mac: Ctrl+Return) to open context menu. Finally, select "Add Comment". Think of it as a rail line: each stop confirms you are still on the right route before the next one.

      +

      Jamie: Before we leave Adding an Inline Comment, what is the practical point?

      +

      Alex: First, type your comment. Then, choose "Add Single Comment" (posts immediately) or "Start Review" (saves as a draft). Treat it like a recipe: do not add the next ingredient until the previous one is actually in the bowl.

      -

      Episode 46: How Git Works: The Mental Model

      -

      Commits, branches, staging, local versus remote, push, pull, fetch, and why conflicts happen.

      -

      Based on: Chapter 13: How Git Works: The Mental Model

      -

      Audio and transcript are being regenerated for this episode.

      -
      -Read Transcript - Episode 46: How Git Works: The Mental Model - -

      Transcript

      -

      Alex: This is Git Going with GitHub, episode 46: How Git Works: The Mental Model. I am Alex. By the end of this episode, How Git Works: The Mental Model should feel less like a wall of GitHub words and more like a set of moves you can trust.

      -

      Jamie: And I am Jamie. I am here for the practical questions: what should I listen for, what can go wrong, and what is the next calm move?

      +

      Jamie: Let's pause on Comment format tips. What should a learner take away from it?

      +

      Alex: Start with Comment format tips. There is something to understand, something to try, and something that proves the try worked.

      +

      Alex: The practical takeaway is this. Be specific: "This heading should be H3, not H2". Provide context: "Screen readers announce this as 'list with 1 item' - should be a paragraph instead". Suggest a fix: "Consider rewording to: 'Click the button to save'".

      +

      Jamie: Let's pause on If you have multiple comments to make, use "Start Review". What should a learner take away from it?

      +

      Alex: Start with If you have multiple comments to make, use "Start Review". There is something to understand, something to try, and something that proves the try worked.

      +

      Alex: First, add your first inline comment → select "Start Review". Then, continue adding comments to other lines. After that, all comments are saved as drafts (not visible to others yet). It is a checklist, but a meaningful one: every item creates evidence that the next step is safe.

      +

      Jamie: Let's pause on Submitting Your Review. What should a learner take away from it?

      +

      Alex: Keep the learner anchored in Submitting Your Review. The review type selector is a radio button group. This is the part to say slowly: Use Arrow keys to choose, Enter to confirm.

      +

      Alex: The practical takeaway is this. Comment - general feedback, no approval decision. Approve - PR looks good, ready to merge. Request Changes - issues must be fixed before merging.

      +

      Alex: First, ctrl+Shift+P (Mac: Cmd+Shift+P). Then, type "GitHub Pull Requests: Submit Review". After that, select "GitHub Pull Requests: Finish Review". Finally, choose review type. It is like walking a hallway with named doors: read the sign, enter the right room, then confirm where you landed.

      +

      Jamie: Before we leave Submitting Your Review, what is the practical point?

      +

      Alex: First, optionally add a summary comment. Then, press Enter to submit. The rhythm is simple: orient, act, verify, then continue.

      -

      Alex: Today we are working on this: Commits, branches, staging, local versus remote, push, pull, fetch, and why conflicts happen. I want the learner to leave with a mental map, not just a remembered path through buttons.

      -

      Jamie: So the goal is understanding first, then action, then confirmation.

      -

      Alex: Right. We are building a rhythm: orient yourself, take one intentional action, then verify what changed before moving on.

      +

      Jamie: Let's pause on What Happens After Submission. What should a learner take away from it?

      +

      Alex: The reason What Happens After Submission matters is that web alternative (github.com) - reviewing. That gives the learner a simple foothold: see Accessible Code Review for detailed screen reader steps. The interface gets friendlier when it stops being a wall of controls and starts being a set of named places.

      +

      Alex: The practical takeaway is this. All your draft comments post to GitHub. The PR author receives a notification. Your review status appears on the PR (Approved / Changes Requested / Commented). If you requested changes, the PR cannot merge until you approve it.

      +

      Alex: First, open the PR and click the Files changed tab. Then, read through each file's diff. After that, click the blue + button on any line to add an inline comment. Finally, choose Start a review to batch comments. The rhythm is simple: orient, act, verify, then continue.

      +

      Jamie: Before we leave What Happens After Submission, what is the practical point?

      +

      Alex: First, click Review changes (top right) to select Comment / Approve / Request changes. Then, click Submit review. Think of it as a rail line: each stop confirms you are still on the right route before the next one.

      +

      Alex: Treat examples as spoken recipes, not decorations. You may hear something like View the PR diff in your terminal; gh pr diff 42; Approve; gh pr review 42 --approve --body "Looks good."; Request changes; gh pr review 42 --request-changes --body "Heading hierarchy needs fixing."; Comment-only (no verdict); gh pr review 42 --comment --body. Read the command, understand what it changes, then run it only when the repository state matches the lesson.

      +

      Jamie: Let's pause on Learning Cards: Commenting and Requesting Changes. What should a learner take away from it?

      +

      Alex: Start with Learning Cards: Commenting and Requesting Changes. There is something to understand, something to try, and something that proves the try worked.

      +

      Alex: The practical takeaway is this. In a diff view, navigate to a line and press Shift+F10 for the context menu, then select "Add Comment" to leave inline feedback. Choose "Start Review" instead of "Single Comment" to batch multiple comments before submitting them all at once. When submitting a review, use Ctrl+Shift+P then "GitHub Pull Requests: Submit Review" and choose Approve, Request Changes, or Comment. Inline comments appear as expandable banners within the diff view -- look for the text input box that opens below the target line. The review submission dialog has radio buttons for Approve, Request Changes, and Comment with clear labels. Increase diff view font size with Ctrl+= so line numbers and change annotations are easier to read.

      +

      Alex: Keep the teaching thread moving. Here is the plain-English version of 8. Merging Pull Requests. Who can merge: Repository maintainers, or contributors with write access.

      -

      Jamie: Okay, set the room for us. What are we walking into?

      -

      Alex: Start with 1. Why a Mental Model Matters: On Day 1, you edited files on GitHub.com using the web editor. The next useful detail is this: GitHub handled Git for you behind the scenes -- creating commits, managing branches, and tracking changes.

      -

      Alex: The next layer is this. Here is the plain-English version of 2. The Three Areas: Working Directory, Staging Area, Repository. Git organizes your work into three areas. Put another way, understanding these three areas is the single most important concept in this chapter. It is like learning a transit route. The names of the stops matter because they tell you whether you are still going the right direction.

      -

      Jamie: What is the one idea that makes the next few steps less mysterious?

      -

      Alex: This is where Working directory becomes real: the working directory is the folder on your computer where the files live. That matters in practice: When you open a project in VS Code, everything you see in the file explorer is the working directory.

      +

      Jamie: Let's pause on Prerequisites for Merging. What should a learner take away from it?

      +

      Alex: This is where Prerequisites for Merging becomes real: changing the base branch: If the PR was opened against the wrong base branch, you can change it from the PR detail view in VS Code. That matters in practice: Scroll to the base branch field in the PR detail view and activate the dropdown to select a different target branch.

      +

      Alex: First, all required reviews are approved. Then, all CI checks pass (green checkmarks). After that, no merge conflicts exist. Finally, branch is up to date with base branch (main). It is a checklist, but a meaningful one: every item creates evidence that the next step is safe.

      +

      Jamie: Let's pause on Method 1: PR Detail View. What should a learner take away from it?

      +

      Alex: Start with Method 1: PR Detail View. There is something to understand, something to try, and something that proves the try worked.

      +

      Alex: First, open the PR in VS Code. Then, scroll to the bottom of the PR detail view. After that, find "Merge Pull Request" button. Finally, press Enter. It is like walking a hallway with named doors: read the sign, enter the right room, then confirm where you landed.

      +

      Jamie: Before we leave Method 1: PR Detail View, what is the practical point?

      +

      Alex: First, choose merge type (see below). The rhythm is simple: orient, act, verify, then continue.

      +

      Jamie: What is the teaching move inside Method 2: Command Palette?

      +

      Alex: Start with Method 2: Command Palette. There is something to understand, something to try, and something that proves the try worked.

      +

      Alex: First, ctrl+Shift+P (Mac: Cmd+Shift+P). Then, type "GitHub Pull Requests: Merge". After that, select "GitHub Pull Requests: Merge Pull Request". Finally, choose the PR from the list. The rhythm is simple: orient, act, verify, then continue.

      +

      Jamie: If someone only remembers one thing from Method 2: Command Palette, what should it be?

      +

      Alex: First, select merge type. Think of it as a rail line: each stop confirms you are still on the right route before the next one.

      -

      Alex: Now bring the learner back to the room. Keep the learner anchored in Staging area (also called the index). The staging area is a holding zone. This is the part to say slowly: When you are happy with a change in the working directory, you add it to the staging area.

      -

      Jamie: What would you say to someone who is already bracing for this to be too much?

      -

      Alex: The reason Repository (the.git folder) matters is that the repository is Git's permanent record. That gives the learner a simple foothold: 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.

      -

      Alex: A solid Git habit is to know which branch you are on, what changed, and what confirmation you expect before you run the next command.

      -

      Jamie: Give me the sequence, because order matters here.

      -

      Alex: Start with How the three areas connect: Many visual Git tutorials use diagrams with arrows to show this flow. The next useful detail is this: The text description above and the three-step sequence are the same information without requiring a visual representation. Think of it like entering a new building: first you find the lobby, then the room, then the door you actually need.

      -

      Alex: First, edit files in the working directory. Then, stage the changes you want to keep (add to the staging area). After that, commit the staged changes (save to the repository). Think of it as a rail line: each stop confirms you are still on the right route before the next one.

      -

      Alex: The useful habit is simple: orient first, act second, verify third. That pause before acting is part of the work.

      +

      Alex: Keep the teaching thread moving. Start with Merge Types: The merge type selector is a dropdown or radio group. The next useful detail is this: Navigate with Arrow keys, confirm with Enter.

      +

      Jamie: Let's pause on Which merge type to use. What should a learner take away from it?

      +

      Alex: Start with Which merge type to use. There is something to understand, something to try, and something that proves the try worked.

      +

      Alex: The practical takeaway is this. Check the repository's CONTRIBUTING.md for guidance. If unsure, use Merge Commit (the default and safest option).

      +

      Jamie: Let's pause on After Merging. What should a learner take away from it?

      +

      Alex: Start with After Merging. There is something to understand, something to try, and something that proves the try worked.

      +

      Alex: First, the PR closes automatically. Then, the feature branch can be deleted (VS Code prompts: "Delete branch?"). After that, recommended: switch back to main and pull the merged changes. It is a checklist, but a meaningful one: every item creates evidence that the next step is safe.

      -

      Jamie: If I am listening before the workshop starts, what should settle in my mind first?

      -

      Alex: Here is the plain-English version of An analogy: packing a box. Think of it like packing a box to mail. Put another way, 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).

      -

      Alex: Here is what that changes in practice. 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.

      -

      Alex: This is where the talk moves from concept to action. Start with Learning Cards: The Three Areas. There is something to understand, something to try, and something that proves the try worked.

      -

      Alex: The room should hear these as checkpoints. 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. 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.

      -

      Jamie: Where do you want a learner to place their attention here?

      -

      Alex: Keep the learner anchored in 3. What Is a Commit? A commit is a snapshot of your project at a specific moment in time. This is the part to say slowly: It is not a diff (a list of changes).

      +

      Jamie: What should happen before anyone copies and runs it?

      +

      Alex: Keep the learner anchored in Switching to main and pulling. (Mac users: use Cmd+Shift+P instead of Ctrl+Shift+P).

      +

      Alex: Treat examples as spoken recipes, not decorations. You may hear something like Ctrl+Shift+P → "Git: Checkout to." → select "main"; Ctrl+Shift+P → "Git: Pull". Read the command, understand what it changes, then run it only when the repository state matches the lesson.

      +

      Jamie: Let's pause on Deleting the Feature Branch. What should a learner take away from it?

      +

      Alex: The reason Deleting the Feature Branch matters is that after merging, the feature branch is no longer needed. That gives the learner a simple foothold: web alternative (github.com) - merging.

      +

      Alex: First, ctrl+Shift+P (Mac: Cmd+Shift+P). Then, type "git delete branch". After that, select "Git: Delete Branch.". Finally, choose the merged branch. The rhythm is simple: orient, act, verify, then continue.

      +

      Jamie: Before we leave Deleting the Feature Branch, what is the practical point?

      +

      Alex: First, open the PR's Conversation tab. Then, scroll to the merge button at the bottom. After that, click the dropdown arrow to choose a merge strategy (Squash, Rebase, or Merge commit). Finally, click Merge pull request, then Confirm merge. Think of it as a rail line: each stop confirms you are still on the right route before the next one.

      +

      Alex: Treat examples as spoken recipes, not decorations. You may hear something like Merge with default strategy; gh pr merge 42; Squash and merge, then delete the branch; gh pr merge 42 --squash --delete-branch; Enable auto-merge (merges when checks pass); gh pr merge 42 --auto --squash. Read the command, understand what it changes, then run it only when the repository state matches the lesson.

      +

      Jamie: Let's pause on Learning Cards: Merging Pull Requests. What should a learner take away from it?

      +

      Alex: Start with Learning Cards: Merging Pull Requests. There is something to understand, something to try, and something that proves the try worked.

      +

      Alex: The practical takeaway is this. The merge type selector (Merge Commit, Squash, Rebase) is announced as a dropdown or radio group -- use Arrow keys to move between options and Enter to confirm; if unsure, choose Merge Commit (the default and safest option). After merging, VS Code prompts "Delete branch?" as a notification -- press Alt+N to focus the notification and Enter to confirm, then run Ctrl+Shift+P then "Git: Checkout to" and select main to return to your default branch. Confirm the merge succeeded by pressing F6 to reach the Status Bar and verifying it now reads main instead of the feature branch name. The merge button at the bottom of the PR detail view includes a dropdown arrow for selecting merge type -- at high zoom, widen the editor pane so the button label and dropdown are not truncated. After merging, the PR detail view header changes from "Open" (green badge) to "Merged" (purple badge) -- verify this colour/label change before deleting the branch. When switching back to main, the branch name in the bottom-left Status Bar updates immediately -- confirm it reads main before pulling new changes with Ctrl+Shift+P then "Git: Pull".

      -

      Alex: Before the learner moves on. The reason Commit IDs (hashes) matters is that every commit gets a unique identifier -- a 40-character string called a SHA hash. That gives the learner a simple foothold: in practice, you usually see only the first 7 characters: a1b2c3d. The interface gets friendlier when it stops being a wall of controls and starts being a set of named places.

      -

      Jamie: Give me the version that sounds like an instructor, not a manual.

      -

      Alex: Start with Commits are permanent (mostly): Once a commit is made, it is part of the repository's history. The next useful detail is this: You can make new commits that undo the changes, but the original commit still exists in the timeline.

      -

      Alex: Hold that next to this. Start with Learning Cards: Commits. There is something to understand, something to try, and something that proves the try worked.

      -

      Alex: The practical anchors are these. 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. 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.

      +

      Alex: Keep the teaching thread moving. Here is the plain-English version of "No pull requests found". Issue: The GitHub Pull Requests panel is empty. It is like learning a transit route. The names of the stops matter because they tell you whether you are still going the right direction.

      +

      Jamie: Let's pause on Solutions. What should a learner take away from it?

      +

      Alex: Start with Solutions. There is something to understand, something to try, and something that proves the try worked.

      +

      Alex: First, verify you're signed in: Ctrl+Shift+P (Mac: Cmd+Shift+P) → "GitHub Pull Requests: Sign in". Then, check you have a folder open containing a Git repository. After that, refresh the panel: Ctrl+Shift+P (Mac: Cmd+Shift+P) → "GitHub Pull Requests: Refresh Pull Requests List". It is a checklist, but a meaningful one: every item creates evidence that the next step is safe.

      +

      Jamie: Before we leave Solutions, what is the practical point?

      +

      Alex: First, verify you've pushed your branch: Ctrl+Shift+P (Mac: Cmd+Shift+P) → "Git: Push". Then, check you have write access to the repository. After that, ensure your branch is ahead of the base branch (has new commits). It is like walking a hallway with named doors: read the sign, enter the right room, then confirm where you landed.

      -

      Jamie: Let's pause on 4. What Is a Branch? What should a learner take away from it?

      -

      Alex: This is where 4. What Is a Branch? becomes real: see also: Chapter 14: Git in Practice shows how to create and switch branches hands-on in VS Code. That matters in practice: A branch is a name that points to a specific commit.

      -

      Alex: That connects to another useful point. Keep the learner anchored in The default branch: main. Every repository has a default branch, usually called main. This is the part to say slowly: 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. A good GitHub workflow is like a well-run meeting: everyone knows the topic, the next action, and who has the floor.

      -

      Jamie: Let's pause on Creating a branch. What should a learner take away from it?

      -

      Alex: The reason Creating a branch matters is that when you create a new branch, Git creates a new pointer that starts at the same commit you are currently on. That gives the learner a simple foothold: both branches point to the same commit.

      +

      Jamie: Let's pause on "Authentication failed". What should a learner take away from it?

      +

      Alex: The reason "Authentication failed" matters is that issue: VS Code can't connect to GitHub.

      +

      Jamie: What is the teaching move inside Solutions?

      +

      Alex: First, sign out and sign back in: Ctrl+Shift+P (Mac: Cmd+Shift+P) → "GitHub Pull Requests: Sign out" → then sign in again. Then, check your GitHub Personal Access Token (see Appendix D: Git Authentication). After that, verify network connection. Think of it as a rail line: each stop confirms you are still on the right route before the next one.

      +

      Jamie: Let's pause on Try It: Review a PR from VS Code. What should a learner take away from it?

      +

      Alex: Here is the plain-English version of Try It: Review a PR from VS Code. Time: 3 minutes What you need: VS Code with GitHub Pull Requests extension installed and signed in. Put another way, you just reviewed a pull request entirely from VS Code.

      +

      Alex: First, open the PR view - Press Ctrl+Shift+P → type Pull Requests: Focus on GitHub Pull Requests View → Enter. Then, find a PR - Navigate the tree with arrow keys. Expand a PR to see its changed files. After that, open a diff - Press Enter on a changed file. The diff editor opens. Finally, use the Accessible Diff Viewer - Press F7 to jump to the first change. Your screen reader announces what was added or removed. Press F7 again to move to the next change. Treat it like a recipe: do not add the next ingredient until the previous one is actually in the bowl.

      +

      Jamie: Before we leave Try It: Review a PR from VS Code, what is the practical point?

      +

      Alex: First, leave a comment - Position your cursor on a line you want to comment on, then press Ctrl+Shift+P → Pull Request: Add Comment on Current Diff Line. Type a brief, constructive comment and submit. It is a checklist, but a meaningful one: every item creates evidence that the next step is safe.

      -

      Alex: Here is the practical turn. Start with 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 next useful detail is this: The main pointer stays where it was.

      -

      Jamie: Let's pause on HEAD: which branch are you on? What should a learner take away from it?

      -

      Alex: Here is the plain-English version of HEAD: which branch are you on? Git uses a special pointer called HEAD to track which branch you are currently working on. Put another way, when you switch branches (checkout), Git moves HEAD to point to the new branch and updates the files in your working directory to match.

      -

      Alex: Keep the thread going. Start with Learning Cards: Branches. There is something to understand, something to try, and something that proves the try worked.

      -

      Alex: These are the details that keep the idea from floating away. 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. 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.

      +

      Alex: Keep the teaching thread moving. This is where Conducting Pull Request Reviews with a Screen Reader becomes real: this guide is focused entirely on the reviewer experience - navigating diffs, reading changes, leaving comments, and submitting a review - using only your keyboard and screen reader. That matters in practice: For the full pull request lifecycle (opening PRs, merge options, conflict resolution), see Working with Pull Requests.

      +

      Jamie: Where does the workshop stop being a tour and start becoming contribution?

      +

      Alex: Keep the learner anchored in Workshop Recommendation (Chapter 15 / Challenge 12). Chapter 15 is the code review chapter focused on practicing constructive feedback. This is the part to say slowly: It supports Challenge 12: Review Like a Pro.

      +

      Alex: The practical takeaway is this. There are 2 guided challenges. Automation check: none (review quality is subjective and human-focused). The evidence is issue comment with summary of review and feedback posted. The pattern is navigate diff, comment on specifics, submit verdict.

      +

      Jamie: Let's pause on Challenge 12 Practice Set. What should a learner take away from it?

      +

      Alex: Start with Challenge 12 Practice Set. There is something to understand, something to try, and something that proves the try worked.

      +

      Alex: First, review a practice PR and leave 2-3 inline comments - read the diff line by line, find specific items to comment on, and post constructive feedback. Then, submit a formal review verdict - complete your review by choosing approve, request changes, or comment only. The rhythm is simple: orient, act, verify, then continue.

      -

      Jamie: Let's pause on 5. Local vs Remote. What should a learner take away from it?

      -

      Alex: Keep the learner anchored in 5. Local vs Remote. See also: Appendix D: Git Authentication covers how to set up credentials so push and pull work without password prompts. This is the part to say slowly: So far, we have talked about one repository.

      -

      Alex: Another way to ground it. The reason The remote repository matters is that the remote repository is the one on GitHub.com. That gives the learner a simple foothold: when you see a repository URL like github.com/Community-Access/git-going-with-github, that is the remote.

      -

      Jamie: Let's pause on The local repository. What should a learner take away from it?

      -

      Alex: Start with The local repository: The local repository is the copy on your computer. The next useful detail is this: When you run git clone, Git downloads the entire repository -- all files, all branches, all history -- to your machine.

      +

      Jamie: Let's pause on Practice 12.1 Step-by-Step: Review a PR and Leave Inline Comments. What should a learner take away from it?

      +

      Alex: Start with Practice 12.1 Step-by-Step: Review a PR and Leave Inline Comments: Navigate a PR diff using screen reader-friendly tools and post 2-3 specific, constructive inline comments. The next useful detail is this: GitHub.com (Files changed tab of a PR) or VS Code with the GitHub Pull Requests extension.

      +

      Alex: The practical takeaway is this. On GitHub.com: Use heading navigation to jump between files (H in NVDA). Each file header is a heading. Within a file, use arrow keys to move line by line. In VS Code: Press F7 to open the Accessible Diff Viewer (see Chapter 15, Part 1). Use F7/Shift+F7 to move between changes. Typos or grammar issues. Unclear headings or link text.

      +

      Alex: First, open your Learning Room repository on GitHub.com and navigate to the Pull requests tab. Then, find a classmate's open PR (from Chapter 6, 7, or 14). Open it. After that, activate the Files changed tab. This shows the diff - lines added in green, lines removed in red. Finally, navigate the diff. Think of it as a rail line: each stop confirms you are still on the right route before the next one.

      +

      Jamie: Before we leave Practice 12.1 Step-by-Step: Review a PR and Leave Inline Comments, what is the practical point?

      +

      Alex: First, read through the changes carefully. Look. Then, to leave an inline comment on GitHub.com: activate the + button that appears to the left of a line number when you hover or Tab to it. (Screen reader users: this button may be announced as "Add a comment to this line.") Type your comment in the text box that. After that, post 2-3 inline comments. Each comment should be. Finally, examples of good inline comments. Treat it like a recipe: do not add the next ingredient until the previous one is actually in the bowl.

      +

      Jamie: Let's pause on Practice 12.2 Step-by-Step: Submit a Formal Review Verdict. What should a learner take away from it?

      +

      Alex: Here is the plain-English version of Practice 12.2 Step-by-Step: Submit a Formal Review Verdict. Complete your review by selecting a verdict that tells the author what action to take next. Put another way, GitHub.com (the same PR you reviewed in 14.1).

      +

      Alex: The practical takeaway is this. Comment - general feedback, no explicit approval or rejection. Approve - you think the PR is ready to merge. Request changes - you found something that should be fixed before merging. If the PR has clear documentation with only minor suggestions, choose Approve.

      +

      Alex: First, after posting your inline comments, scroll to the top of the Files changed tab. Then, activate the Review changes button (at the top-right of the files changed area, or use heading navigation). After that, a dropdown opens with three options. Finally, choose the verdict that matches your review. Treat it like a recipe: do not add the next ingredient until the previous one is actually in the bowl.

      +

      Jamie: Before we leave Practice 12.2 Step-by-Step: Submit a Formal Review Verdict, what is the practical point?

      +

      Alex: First, write a brief summary in the review body (1-2 sentences). Example: "Clear improvement to the shortcut table. Two minor suggestions for link text clarity.". Then, activate Submit review. It is a checklist, but a meaningful one: every item creates evidence that the next step is safe.

      +

      Jamie: What makes this practice feel low-stakes but still real?

      +

      Alex: This is where Completing Challenge 12: Submit Your Evidence becomes real: open your assigned Challenge 12 issue and post a completion comment. That matters in practice: Close your Challenge 12 issue when done.

      -

      Alex: This is the part worth saying out loud. Here is the plain-English version of The two-copy model. The text diagram above shows two boxes side by side connected by arrows. Put another way, the left box is labeled "Your computer (local)" and contains working directory, staging area, and repository. It is like learning a transit route. The names of the stops matter because they tell you whether you are still going the right direction.

      -

      Jamie: Let's pause on Learning Cards: Local vs Remote. What should a learner take away from it?

      -

      Alex: Start with Learning Cards: Local vs Remote. There is something to understand, something to try, and something that proves the try worked.

      -

      Alex: That shows up in the workshop in a few specific ways. 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. 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.

      -

      Alex: That matters because of the next idea. Keep the learner anchored in 6. Push, Pull, and Fetch. These three operations keep your local and remote repositories synchronized.

      -

      Alex: A solid pull request habit is to separate three questions: what changed, why it changed, and what still needs review. That keeps the conversation useful instead of noisy.

      +

      Alex: Keep the teaching thread moving. Start with Expected Outcomes. There is something to understand, something to try, and something that proves the try worked.

      +

      Alex: The practical takeaway is this. Student can navigate PR diffs with a screen reader. Student can post inline comments on specific lines of a diff. Student can write constructive, specific feedback that helps the author improve. Student can submit a formal review verdict.

      +

      Jamie: What is the teaching move inside If You Get Stuck?

      +

      Alex: The reason If You Get Stuck matters is that continue learning: The GitHub Skills courses Review Pull Requests and Code Review with GitHub Copilot cover review workflows and AI-assisted code review. That gives the learner a simple foothold: see Appendix Z for the full catalog.

      +

      Alex: First, files Changed tab will not open? Reload the PR page and retry. Make sure you are on the PR page, not the issue page. Then, cannot find the inline comment button? Tab through the line controls in the diff. The button may be announced as "Add a comment" or have a + label. If you cannot find it, use the "Review changes" button at the top to add a general comment instead. After that, not sure what to comment on? Focus on clarity: is every heading descriptive? Is every link meaningful? Are steps complete? Are keyboard shortcuts correct? Finally, review verdict button not working? Make sure you have at least one comment or have written summary text. Try reloading the page. The rhythm is simple: orient, act, verify, then continue.

      +

      Jamie: If someone only remembers one thing from If You Get Stuck, what should it be?

      +

      Alex: First, submitting the review fails? Check that you are not in draft mode and have at least read access to the repo. Then, ask facilitator to model one inline comment and one verdict submission. After that, finished but not sure you did it right? Compare your work against the Challenge 12 reference solution. Think of it as a rail line: each stop confirms you are still on the right route before the next one.

      +

      Alex: Keep the teaching thread moving. Start with Learning Moment: Specific, kind feedback helps authors improve and builds trust in the community. The next useful detail is this: Every comment you write is practice for the professional code review you will do on real projects.

      +
      +

      Jamie: Before we leave Learning Pattern Used in This Chapter, what is the practical point?

      +

      Alex: First, read the full diff before commenting (understand the author's intent first). Then, find specific items to comment on (lines, phrases, missing steps). After that, write comments that help, not just criticize (suggest improvements, note what works). Finally, choose a verdict that matches the substance of your feedback. Treat it like a recipe: do not add the next ingredient until the previous one is actually in the bowl.

      +

      Jamie: What is the teaching move inside Learning Pattern Used in This Chapter?

      +

      Alex: First, summarize your overall impression in 1-2 sentences. It is a checklist, but a meaningful one: every item creates evidence that the next step is safe.

      +

      Alex: Keep the teaching thread moving. This is where Before starting this chapter, verify you have completed becomes real: estimated time for this chapter: 1 hour (including exercises). The workshop is closer to rehearsal than lecture. You hear the move, try the move, and then check what changed.

      +

      Alex: The practical takeaway is this. [ ] Chapter 6: Working with Pull Requests - Understand PR structure, diffs, and comment workflows. [ ] Chapter 13: GitHub Copilot - VS Code installed and configured. [ ] Screen Reader Setup - NVDA, JAWS, or VoiceOver installed and ready to use. [ ] Access to at least one pull request to review (your own fork or a practice repo).

      +

      Jamie: Let's pause on Two Environments for Code Review. What should a learner take away from it?

      +

      Alex: Keep the learner anchored in Two Environments for Code Review. You can review pull requests in two places - each with different strengths. This is the part to say slowly: Both environments give you full keyboard and screen reader access.

      Jamie: What should they understand before typing anything?

      -

      Alex: The reason Push: share your work matters is that git push sends your local commits to the remote. That gives the learner a simple foothold: after pushing, anyone who looks at the repository on GitHub.com will see your changes.

      -

      Alex: Treat examples as spoken recipes, not decorations. You may hear something like git push origin fix/typo. git push -u origin fix/typo. Read the command, understand what it changes, then run it only when the repository state matches the lesson.

      +

      Alex: The reason About Learning Cards in This Chapter matters is that each review step includes expandable learning cards for different interaction styles. That gives the learner a simple foothold: open the one that matches how you work.

      +

      Alex: Treat examples as spoken recipes, not decorations. You may hear something like View the full PR diff in your terminal; gh pr diff 42; View PR details (description, status, checks); gh pr view 42; Checkout the PR branch locally for testing; gh pr checkout 42; Approve the PR; gh pr review 42 --approve --body "Heading hierarchy looks. Read the command, understand what it changes, then run it only when the repository state matches the lesson.

      +

      Jamie: Let's pause on Good News: Modern Interface is Default. What should a learner take away from it?

      +

      Alex: Start with Good News: Modern Interface is Default: As of January 2026, GitHub's improved Files Changed experience is enabled by default. The next useful detail is this: The instructions below assume you have the modern interface (which you do).

      +

      Jamie: Let's pause on Step 1: Reach the Files Changed Tab. What should a learner take away from it?

      +

      Alex: Here is the plain-English version of Step 1: Reach the Files Changed Tab. Click the Files changed tab at the top of the PR page. Put another way, the tab label shows the number of changed files (e.g., "Files changed 4"). It is like learning a transit route. The names of the stops matter because they tell you whether you are still going the right direction.

      +

      Alex: First, the PR tabs (Conversation, Commits, Checks, Files changed) are across the top of the PR page. At high zoom they may wrap to multiple lines. Then, the Files changed tab includes a badge with the number of changed files. This badge uses text (not colour alone) so it is visible in all themes. After that, after clicking Files changed, the diff page loads. At high zoom, the file tree panel on the left may collapse automatically. Click the file tree toggle (a small panel icon) or press T to toggle it back. Finally, added lines use a green background; removed lines use red. In high contrast browser settings (Windows: Settings Accessibility Contrast themes), these colours map to strong border indicators. Treat it like a recipe: do not add the next ingredient until the previous one is actually in the bowl.

      +

      Jamie: Before we leave Step 1: Reach the Files Changed Tab, what is the practical point?

      +

      Alex: First, use Ctrl++ to zoom the browser if the diff text is too small, and Ctrl+- to zoom out. It is a checklist, but a meaningful one: every item creates evidence that the next step is safe.

      +

      Alex: Treat examples as spoken recipes, not decorations. You may hear something like Press D → navigate to "Pull request navigation tabs" landmark; Press → or Tab → find "Files changed" link → Enter. Read the command, understand what it changes, then run it only when the repository state matches the lesson.

      +
      +

      Jamie: Let's pause on Step 2: Use the File Tree to Orient Yourself. What should a learner take away from it?

      +

      Alex: This is where Step 2: Use the File Tree to Orient Yourself becomes real: the file tree panel lists every changed file. That matters in practice: Before reading any diff, scan this list to understand the scope of the PR.

      +

      Jamie: Let's pause on What to listen for / look for. What should a learner take away from it?

      +

      Alex: Keep the learner anchored in What to listen for / look for. Low vision users (zoom, high contrast).

      +

      Alex: The practical takeaway is this. How many files changed? Which areas of the codebase are affected? Are there unexpected files (generated files, lock files, configuration changes)?

      +

      Alex: First, the file tree shows each filename with a colour-coded bar indicating lines added (green) and removed (red). In high contrast mode, these bars may be less visible - the +N / -N text badge next to each file is the reliable indicator. Then, at high zoom, long file paths truncate. Hover over a truncated name to see the full path in a tooltip. After that, if the file tree panel is too narrow at high zoom, drag its right edge to widen it, or toggle it off and use heading navigation (H key) to move between file diffs. It is like walking a hallway with named doors: read the sign, enter the right room, then confirm where you landed.

      Jamie: How do you keep commands from becoming magic words?

      -

      Alex: Start with Pull: get other people's work: git pull downloads new commits from the remote and immediately merges them into your current branch. The next useful detail is this: This is how you get changes that other people (or you on another computer) have pushed. Think of it like entering a new building: first you find the lobby, then the room, then the door you actually need.

      -

      Alex: Treat examples as spoken recipes, not decorations. You may hear something like git pull origin main. Read the command, understand what it changes, then run it only when the repository state matches the lesson.

      -

      Jamie: What is the safe way to learn from that example?

      -

      Alex: Here is the plain-English version of Fetch: check for updates without merging. git fetch downloads new commits from the remote but does not change your working directory or current branch. Put another way, it just updates your local knowledge of what the remote looks like.

      -

      Alex: Treat examples as spoken recipes, not decorations. You may hear something like git fetch origin. git log main.origin/main --oneline. Read the command, understand what it changes, then run it only when the repository state matches the lesson.

      +

      Alex: The reason Step 3: Navigate Between File Diffs matters is that each changed file in the main area is an h3 heading containing the filename. That gives the learner a simple foothold: scroll through the page or click a filename in the file tree on the left.

      +

      Alex: Treat examples as spoken recipes, not decorations. You may hear something like Press 3 to jump file-by-file through the diff; Listen for: "learning-room/docs/keyboard-shortcuts.md - collapsed" or "expanded"; Press Enter or Space to expand a collapsed file. Quick Nav H or VO+Cmd+H to jump file-by-file through the diff; Listen for: "learning-room/docs/keyboard-shortcuts.md - collapsed" or "expanded"; VO+Space to expand a collapsed file. Read the command, understand what it changes, then run it only when the repository state matches the lesson.

      -

      Alex: Keep the teaching thread moving. This is where 7. Why Merge Conflicts Happen becomes real: a merge conflict happens when Git cannot automatically combine two sets of changes.

      -

      Jamie: Let's pause on When conflicts occur. What should a learner take away from it?

      -

      Alex: Keep the learner anchored in When conflicts occur. Conflicts happen when two branches modify the same lines in the same file. This is the part to say slowly: Git knows how to merge changes to different files, and even different parts of the same file.

      -

      Alex: Keep the teaching thread moving. The reason What a conflict looks like matters is that when a conflict occurs, Git marks the conflicting section in the file with special markers. The interface gets friendlier when it stops being a wall of controls and starts being a set of named places.

      +

      Jamie: Let's pause on Step 4: Read a Diff. What should a learner take away from it?

      +

      Alex: Start with Step 4: Read a Diff: Low vision users (zoom, high contrast). The next useful detail is this: Screen reader users - VoiceOver (macOS). Think of it like entering a new building: first you find the lobby, then the room, then the door you actually need.

      +

      Alex: The practical takeaway is this. Green highlighted lines (with a +) = lines added. Red highlighted lines (with a -) = lines removed. Plain/white lines = unchanged context. Use Ctrl+F to search within the page for specific text in the diff.

      +

      Alex: First, colour is not the only indicator. Every added line has a + character in the gutter; every removed line has a -. These text characters are reliable regardless of colour settings. Then, at high zoom, long lines of code wrap. The +/- gutter character stays at the beginning of the first line, so look left to determine the change type. After that, use Ctrl+F (browser find) to search for specific text across the entire diff page. Finally, if the diff is split view (side by side), it may be very wide at high zoom. Switch to unified diff mode: click the gear icon in the Files Changed toolbar and select "Unified" - this shows old and new in a single column. Think of it as a rail line: each stop confirms you are still on the right route before the next one.

      +

      Jamie: Before we leave Step 4: Read a Diff, what is the practical point?

      +

      Alex: First, high contrast themes in Windows (Settings Accessibility Contrast themes) make the +/- lines use bold border patterns instead of subtle colour shading. Treat it like a recipe: do not add the next ingredient until the previous one is actually in the bowl.

      +

      Alex: Treat examples as spoken recipes, not decorations. You may hear something like Press T to jump to the diff table then Insert+Space (Focus Mode); Press Down Arrow to move through lines one at a time; Press Ctrl+Alt+Right Arrow to read across columns: line number, change type, code content. Press T to jump to the diff table then Insert+Z (Virtual PC Cursor off); Press Down Arrow to move through lines; Press Ctrl+Alt+Right Arrow for column-by-column reading. Read the command, understand what it changes, then run it only when the repository state matches the lesson.

      +

      Jamie: Let's pause on What each line announces / shows. What should a learner take away from it?

      +

      Alex: Here is the plain-English version of What each line announces / shows. If the code on a line is very long, the screen reader will read the full line. Put another way, for minified or generated files, consider collapsing the file in the tree and skipping it.

      +

      Alex: The practical takeaway is this. Added lines: "+ [code content]" - or announced as "inserted". Removed lines: "- [code content]" - or announced as "deleted". Context lines: code without a + or -.

      +

      Jamie: Let's pause on Step 5: Place an Inline Comment. What should a learner take away from it?

      +

      Alex: This is where Step 5: Place an Inline Comment becomes real: when you have a specific observation about a particular line, place an inline comment directly on it. That matters in practice: Screen reader users (VoiceOver - macOS).

      +

      Alex: First, hover your mouse over a line in the diff - a blue + (comment) button appears on the left. Then, click it to open the inline comment box. After that, type your comment. Finally, click "Start a review" (not "Add single comment" - see note below). It is a checklist, but a meaningful one: every item creates evidence that the next step is safe.

      -

      Jamie: How would you walk the room through that step by step?

      -

      Alex: Start with How to resolve a conflict: The Day 1 connection: In Chapter 7, you resolved a merge conflict on GitHub.com using the web editor. The next useful detail is this: 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.

      -

      Alex: First, open the file with the conflict markers. Then, read both versions and decide which text to keep (or write a new version that combines both). After that, delete the conflict markers ( ). Finally, save the file. Think of it as a rail line: each stop confirms you are still on the right route before the next one.

      -

      Jamie: What does the learner do first, second, and then after that?

      -

      Alex: First, stage and commit the resolved file. Treat it like a recipe: do not add the next ingredient until the previous one is actually in the bowl.

      -

      Alex: Keep the teaching thread moving. Here is the plain-English version of Why conflicts are normal. They happen in every project where more than one person works at the same time. Put another way, the fact that Git stops and asks is a safety feature -- it prevents data loss by never silently choosing one version over another.

      -

      Jamie: Let's pause on Learning Cards: Merge Conflicts. What should a learner take away from it?

      -

      Alex: Start with Learning Cards: Merge Conflicts. There is something to understand, something to try, and something that proves the try worked.

      -

      Alex: For a learner, the useful signals are these. 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. 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.

      +

      Jamie: Let's pause on Placing a multi-line comment. What should a learner take away from it?

      +

      Alex: Keep the learner anchored in Placing a multi-line comment. Click and drag across multiple line numbers in the diff gutter to select a range. This is the part to say slowly: A comment button appears for the selected range.

      +

      Jamie: Let's pause on Step 6: Read Existing Comments and Threads. What should a learner take away from it?

      +

      Alex: The reason Step 6: Read Existing Comments and Threads matters is that inline comments from other reviewers appear as h3 headings within the diff table. That gives the learner a simple foothold: each thread shows: reviewer username, comment body, replies, a "Reply" link and resolution button. The interface gets friendlier when it stops being a wall of controls and starts being a set of named places.

      +

      Alex: Treat examples as spoken recipes, not decorations. You may hear something like Tab to the "Resolve conversation" button → Enter. Tab to the "Resolve conversation" button → VO+Space. Read the command, understand what it changes, then run it only when the repository state matches the lesson.

      +

      Jamie: Let's pause on Step 7: Submit Your Review. What should a learner take away from it?

      +

      Alex: Start with Step 7: Submit Your Review: Screen reader users (VoiceOver - macOS).

      +

      Alex: First, click the "Review changes" button (top-right of the Files Changed page or bottom of the PR). Then, a dialog opens with a summary text area and three radio buttons: Comment / Approve / Request changes. After that, optionally type an overall summary in the text area. Finally, select your verdict. Think of it as a rail line: each stop confirms you are still on the right route before the next one.

      +

      Jamie: Before we leave Step 7: Submit Your Review, what is the practical point?

      +

      Alex: First, click "Submit review". Treat it like a recipe: do not add the next ingredient until the previous one is actually in the bowl.

      -

      Alex: Keep the teaching thread moving. Keep the learner anchored in 8. The Git Timeline. Every commit has a parent pointer (except the very first commit). This is the part to say slowly: This creates a chain -- a timeline of the project's history. A good GitHub workflow is like a well-run meeting: everyone knows the topic, the next action, and who has the floor.

      -

      Jamie: Let's pause on Reading the timeline. What should a learner take away from it?

      -

      Alex: The reason Reading the timeline matters is that 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. That gives the learner a simple foothold: 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.

      -

      Alex: Keep the teaching thread moving. Start with Branching creates parallel timelines: When two branches diverge (both have commits that the other does not), the timeline splits into two parallel paths. The next useful detail is this: Both branches share commits A and B (their common history).

      +

      Jamie: Let's pause on Step 8: Re-request Review (for Authors). What should a learner take away from it?

      +

      Alex: Here is the plain-English version of Step 8: Re-request Review (for Authors). After you address review comments on your own PR. Put another way, look in the right sidebar for the Reviewers section.

      +

      Alex: Treat examples as spoken recipes, not decorations. You may hear something like Step 1: From your PR's Conversation tab, Quick Nav H or VO+Cmd+H to find the "Reviewers" heading in the sidebar; Step 2: Tab or Quick Nav B to find the re-request icon ("Re-request review") next to the reviewer's name; Step 3: VO+Space to activate - this. Read the command, understand what it changes, then run it only when the repository state matches the lesson.

      +

      Jamie: Let's pause on Learning Cards: Reviewing on GitHub.com. What should a learner take away from it?

      +

      Alex: Start with Learning Cards: Reviewing on GitHub.com. There is something to understand, something to try, and something that proves the try worked.

      +

      Alex: The practical takeaway is this. In the Files Changed tab, press T to jump to the diff table, then use Focus Mode (Insert+Space in NVDA, Insert+Z in JAWS) and Down Arrow to read line by line -- each added line starts with + and each removed line with -. To place an inline comment, navigate to the target line and press Tab or B to find the "Add a comment to this line" button; after typing your comment, choose "Start a review" (not "Add single comment") to batch all feedback into one notification. Submit your full review by pressing B repeatedly to find the "Review changes" button; the dialog contains a radio group (Comment / Approve / Request changes) navigable with Arrow keys, then Tab to "Submit review". Switch from split diff to unified diff (gear icon in the Files Changed toolbar then select "Unified") to show old and new code in a single column -- much easier to follow at high zoom than two side-by-side panes. The blue + comment button appears in the line gutter on hover; at high zoom it may be small -- use Ctrl++ to increase browser zoom and look just left of the line number column. The "Review changes" dialog uses clearly labeled radio buttons for the three verdict types; each label includes a brief description, and the currently selected option has a filled circle indicator visible in all themes.

      +

      Alex: Keep the teaching thread moving. Keep the learner anchored in Reviewing in VS Code with the Accessible Diff Viewer. When you check out a branch locally, VS Code's diff editor offers the Accessible Diff Viewer - a purpose-built, line-by-line reading mode designed specifically for screen readers. A good GitHub workflow is like a well-run meeting: everyone knows the topic, the next action, and who has the floor.

      -

      Jamie: Let's pause on Merging reconnects timelines. What should a learner take away from it?

      -

      Alex: Here is the plain-English version of 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. Put another way, the two timelines join back together.

      -

      Alex: Keep the teaching thread moving. This is where 9. Putting It All Together becomes real: here is the complete workflow that you will practice in Chapter 14, translated through the mental model. That matters in practice: Everything in this table maps directly to the three areas (Section 2), the two copies (Section 5), and the timeline (Section 8). The workshop is closer to rehearsal than lecture. You hear the move, try the move, and then check what changed.

      -

      Jamie: Let's pause on Quick mental model checklist. What should a learner take away from it?

      -

      Alex: Keep the learner anchored in Quick mental model checklist. Before running a Git command, ask yourself. This is the part to say slowly: If you can answer these four questions, you can troubleshoot almost any Git situation.

      -

      Alex: That becomes easier when you listen for these cues. 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?

      +

      Jamie: Let's pause on Opening a Diff in VS Code. What should a learner take away from it?

      +

      Alex: The reason Opening a Diff in VS Code matters is that if you have the GitHub Pull Requests extension. That gives the learner a simple foothold: without the extension, any git diff operation also opens the diff editor.

      +

      Alex: First, open the GitHub Pull Requests view (Explorer sidebar or Ctrl+Shift+P → "GitHub Pull Requests: View Pull Request"). Then, find the PR and open it - changed files appear in the file tree. After that, navigate to any file in the tree and press Enter to open its diff view. The rhythm is simple: orient, act, verify, then continue.

      +

      Jamie: Let's pause on Learning Cards: VS Code Code Review. What should a learner take away from it?

      +

      Alex: Start with Learning Cards: VS Code Code Review: Low vision users (zoom, high contrast). The next useful detail is this: VS Code's diff editor works well at high zoom.

      +

      Alex: First, split view vs. inline: By default, VS Code shows diffs in a split (side-by-side) view. At high zoom this can be very cramped. Switch to inline mode: Ctrl+Shift+P then type "Toggle Inline View" in any diff editor. Inline mode shows old and new code in a single. Then, colour indicators: Added lines have a green gutter bar; removed lines have a red gutter bar. In high contrast themes, these use heavy solid borders that are visible even at extreme zoom levels. After that, change navigation: Press F7 to jump to the next change and Shift+F7 for the previous. Each change is highlighted with a visible focus box that moves with your position - much easier than scrolling at high zoom. Finally, minimap in diff view: The minimap (right edge) shows an overview of changes as coloured blocks. At high zoom the minimap may be too small to be useful - disable it via Settings if it adds visual noise. Think of it as a rail line: each stop confirms you are still on the right route before the next one.

      +

      Jamie: Before we leave Learning Cards: VS Code Code Review, what is the practical point?

      +

      Alex: First, font size for diffs: Diff editors use your configured editor font size (editor.fontSize). Increase this in Settings (Ctrl+,) if the diff text is too small at your zoom level. Then, comment highlight: When you add a comment through the GitHub PR extension, the commented line gets a distinct background. In high contrast themes this is a solid colour band. Treat it like a recipe: do not add the next ingredient until the previous one is actually in the bowl.

      +

      Jamie: Let's pause on Opening the PR for review. What should a learner take away from it?

      +

      Alex: Start with Opening the PR for review. There is something to understand, something to try, and something that proves the try worked.

      +

      Alex: First, press Ctrl+Shift+P, type "GitHub Pull Requests: View Pull Request". Then, the PR tree appears in the sidebar - navigate with Down Arrow. After that, each changed file is announced with its name and change summary. Finally, press Enter on a file to open its diff editor. Treat it like a recipe: do not add the next ingredient until the previous one is actually in the bowl.

      +

      Jamie: Before we leave Opening the PR for review, what is the practical point?

      +

      Alex: First, the diff editor opens with the standard VS Code diff layout. It is a checklist, but a meaningful one: every item creates evidence that the next step is safe.

      -

      Alex: Keep the teaching thread moving. The reason 10. If You Get Stuck matters is that next: Chapter 14: Git in Practice Back: Chapter 12: VS Code Accessibility Related appendices: Appendix E: Advanced Git Appendix D: Git Authentication.

      +

      Jamie: Let's pause on Using the Accessible Diff Viewer. What should a learner take away from it?

      +

      Alex: Start with Using the Accessible Diff Viewer. There is something to understand, something to try, and something that proves the try worked.

      +

      Alex: First, in the diff editor, press F7 to open the Accessible Diff Viewer. Then, NVDA announces: "Changed lines X to Y in filename, Change 1 of N". After that, the viewer shows each change with "Removed:" and "Added:" labels. Finally, press F7 to move to the next change, Shift+F7 for previous. It is a checklist, but a meaningful one: every item creates evidence that the next step is safe.

      +

      Jamie: Before we leave Using the Accessible Diff Viewer, what is the practical point?

      +

      Alex: First, press Escape when done to close the viewer. It is like walking a hallway with named doors: read the sign, enter the right room, then confirm where you landed.

      +

      Jamie: Let's pause on Placing a comment. What should a learner take away from it?

      +

      Alex: Keep the learner anchored in Placing a comment. Screen reader users (VoiceOver on macOS).

      +

      Alex: First, navigate to the line you want to comment on in the diff. Then, press Ctrl+Shift+P, type "GitHub Pull Requests: Add Comment". After that, a text area opens below the line - NVDA announces the input focus. Finally, type your comment. It is like walking a hallway with named doors: read the sign, enter the right room, then confirm where you landed.

      +

      Jamie: Before we leave Placing a comment, what is the practical point?

      +

      Alex: First, press Tab to the Submit button, then Enter. The rhythm is simple: orient, act, verify, then continue.

      +

      Jamie: Let's pause on Opening the PR. What should a learner take away from it?

      +

      Alex: Start with Opening the PR. There is something to understand, something to try, and something that proves the try worked.

      +

      Alex: First, press Cmd+Shift+P, type "GitHub Pull Requests: View Pull Request". Then, navigate the PR tree with VO+Down Arrow. After that, press Return on a file to open its diff. The rhythm is simple: orient, act, verify, then continue.

      -

      Jamie: What should people carry with them after this?

      -

      Alex: Carry the map. Know what page or tool you are in, know which action you are taking, and know what confirmation should follow. If the confirmation is missing, pause. That pause is not wasted time; it is professional judgment.

      -

      Jamie: That is a better way to say it than just follow the steps.

      -

      Alex: Right. Steps matter, but understanding wins. That is episode 46. Next in the series is episode 47, where we keep building the same contributor muscles.

      -
      - +

      Jamie: Let's pause on Accessible Diff Viewer. What should a learner take away from it?

      +

      Alex: Start with Accessible Diff Viewer. There is something to understand, something to try, and something that proves the try worked.

      +

      Alex: First, press F7 in the diff editor. Then, VoiceOver announces each change with clear "Removed" and "Added" labels. After that, navigate with F7/Shift+F7. Finally, press Escape to close. Think of it as a rail line: each stop confirms you are still on the right route before the next one.

      +

      Jamie: Let's pause on Comment placement. What should a learner take away from it?

      +

      Alex: Start with Comment placement. There is something to understand, something to try, and something that proves the try worked.

      +

      Alex: First, press Cmd+Shift+P, type "GitHub Pull Requests: Add Comment". Then, vO+Shift+Down Arrow to interact with the comment text area. After that, type your comment. Finally, vO+Shift+Up Arrow to stop interacting, then Tab to Submit. Treat it like a recipe: do not add the next ingredient until the previous one is actually in the bowl.

      +

      Jamie: Let's pause on Using the Accessible Diff Viewer (F7). What should a learner take away from it?

      +

      Alex: This is where Using the Accessible Diff Viewer (F7) becomes real: the Accessible Diff Viewer reads each change as a structured block. That matters in practice: This example is from a real Learning Room scenario: a contributor fixing the heading hierarchy in docs/keyboard-shortcuts.md by changing a level-4 heading to level-3, which is exactly what you look for when reviewing Challenge 2 PRs.

      +

      Alex: Treat examples as spoken recipes, not decorations. You may hear something like "Changed lines 14 to 14 in docs/keyboard-shortcuts.md; [Change 1 of 3]; Removed:; NVDA Single-Key Navigation; Added:; NVDA Single-Key Navigation". Read the command, understand what it changes, then run it only when the repository state matches the lesson.

      -

      Episode 47: Fork and Contribute

      -

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

      -

      Based on: Chapter 18: Fork and Contribute

      -

      Audio and transcript are being regenerated for this episode.

      -
      -Read Transcript - Episode 47: Fork and Contribute - -

      Transcript

      -

      Alex: Welcome to episode 47 of Git Going with GitHub: Fork and Contribute. I am Alex, and today we are teaching this topic as a conversation you can carry into the workshop, not as a page you have to memorize.

      -

      Jamie: And I am Jamie. I will keep pulling the lesson back to real learners, real repositories, and the evidence that proves the work happened.

      +

      Alex: Keep the teaching thread moving. Start with Navigation. There is something to understand, something to try, and something that proves the try worked.

      +

      Alex: The practical takeaway is this. F7 - jump to next change (next hunk). Shift+F7 - jump to previous change. Alt+F2 - open VS Code's Accessible View for additional context on the current item. Escape - close the Accessible Diff Viewer.

      +

      Jamie: Let's pause on What makes this better than the raw diff editor. What should a learner take away from it?

      +

      Alex: Start with What makes this better than the raw diff editor. There is something to understand, something to try, and something that proves the try worked.

      +

      Alex: The practical takeaway is this. Each change is announced as a discrete unit with clear "Removed:" and "Added:" labels. You hear the change number of total changes ("Change 3 of 12"). No table navigation required - purpose-built for sequential listening. Works with all three major screen readers without any special configuration.

      +

      Alex: Keep the teaching thread moving. Start with Placing Comments in VS Code (GitHub PR Extension): From the diff editor with the GitHub PR extension. The next useful detail is this: Comments placed in VS Code sync to GitHub - they appear in the PR's Files Changed tab and the author receives the same notification. Think of it like entering a new building: first you find the lobby, then the room, then the door you actually need.

      -

      Alex: The lesson focus is The complete fork-based open source contribution workflow from fork to upstream pull request. We will treat every step as a teachable decision, because that is what makes the skill portable.

      -

      Jamie: So we should explain the why clearly enough that the steps make sense when the learner meets them later.

      -

      Alex: That is it. If a listener only has audio right now, they should still get the complete concept and know what evidence would prove success.

      +

      Jamie: Let's pause on The Anatomy of a Useful Review Comment. What should a learner take away from it?

      +

      Alex: Here is the plain-English version of The Anatomy of a Useful Review Comment. A comment that helps the author is.

      +

      Alex: First, specific - link to the exact line and name the pattern you see. Then, educational - say why something matters, not just what to change. After that, graduated - signal whether this is blocking, or a preference. Treat it like a recipe: do not add the next ingredient until the previous one is actually in the bowl.

      +

      Alex: Keep the teaching thread moving. This is where Blocking example (reviewing a PR for docs/keyboard-shortcuts.md) becomes real: "The heading on line 34 uses (level 4) directly after (level 2), skipping heading level 3. That matters in practice: Screen reader users who navigate by heading level will miss any content between those two levels.

      +

      Jamie: Let's pause on Non-blocking (nit) example (reviewing a PR for docs/welcome.md). What should a learner take away from it?

      +

      Alex: Keep the learner anchored in Non-blocking (nit) example (reviewing a PR for docs/welcome.md). "nit: The link text in the 'Getting Help' section reads 'click here for more information.' Screen reader users who navigate links out of context will hear only 'click here' with no destination. This is the part to say slowly: Consider 'See the accessibility setup guide' instead.

      -

      Jamie: Okay, set the room for us. What are we walking into?

      -

      Alex: Start with 1. What Is a Fork?: See also: Chapter 08: Open Source Culture for the cultural context of forking and contributing. The next useful detail is this: A fork is your personal copy of someone else's repository on GitHub.

      -

      Jamie: How would you walk the room through that step by step?

      -

      Alex: Here is the plain-English version of Why forks exist. Most open source projects do not give every contributor write access to the main repository. Put another way, this way anyone can contribute without the maintainers giving out write access. It is like learning a transit route. The names of the stops matter because they tell you whether you are still going the right direction.

      -

      Alex: First, you fork the project (creates your copy). Then, you make changes on your copy. After that, you open a pull request asking the maintainers to merge your changes. Treat it like a recipe: do not add the next ingredient until the previous one is actually in the bowl.

      -

      Jamie: What is the one idea that makes the next few steps less mysterious?

      -

      Alex: This is where 2. Fork vs Clone vs Branch becomes real: these three concepts are related but different. That matters in practice: Understanding the distinctions prevents confusion.

      -

      Alex: A solid Git habit is to know which branch you are on, what changed, and what confirmation you expect before you run the next command.

      +

      Alex: Keep the teaching thread moving. The reason Question example (reviewing a PR for docs/setup-guide.md) matters is that "The PR description says this fixes broken links in the setup guide, but the link on line 12 still points to /docs/old-setup. That gives the learner a simple foothold: am I reading the diff correctly, or was this link intentionally left? The interface gets friendlier when it stops being a wall of controls and starts being a set of named places.

      +

      Jamie: Let's pause on Prefixes That Set Expectations. What should a learner take away from it?

      +

      Alex: Start with Prefixes That Set Expectations: Using shorthand prefixes helps authors parse many comments quickly.

      +

      Alex: Keep the teaching thread moving. Here is the plain-English version of How Many Comments Is Too Many? There is no hard limit, but quantity without prioritization is noise. Put another way, if you have 15 comments, make clear which 2-3 are blocking.

      -

      Jamie: Turn that into a path someone can follow.

      -

      Alex: Keep the learner anchored in How they work together. In the fork workflow, you use all three. This is the part to say slowly: The text diagram above shows three boxes arranged left to right.

      -

      Alex: First, fork the upstream repository to create your copy on GitHub. Then, clone your fork to your computer. After that, create a branch on your local clone for your specific change. Finally, push the branch to your fork and open a PR to the upstream. It is like walking a hallway with named doors: read the sign, enter the right room, then confirm where you landed.

      -

      Jamie: What would you say to someone who is already bracing for this to be too much?

      -

      Alex: Start with Learning Cards: Fork vs Clone vs Branch. There is something to understand, something to try, and something that proves the try worked.

      -

      Alex: The parts worth keeping in working memory are these. 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. 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.

      -

      Jamie: Give me the sequence, because order matters here.

      -

      Alex: Start with Tool Cards: Fork and Clone a Repository: For this workshop, you will fork the Community-Access/accessibility-agents repository. Think of it like entering a new building: first you find the lobby, then the room, then the door you actually need.

      -

      Alex: First, click Fork on the repository page Create fork. Then, clone: click the green Code button copy URL paste into your local tool. After that, fork on github.com first (browser required for forking). Finally, ctrl+Shift+P Git: Clone paste your fork's URL. Think of it as a rail line: each stop confirms you are still on the right route before the next one.

      -

      Jamie: What does the learner do first, second, and then after that?

      -

      Alex: First, fork on github.com first. Then, file Clone Repository select your fork from the GitHub.com tab. Treat it like a recipe: do not add the next ingredient until the previous one is actually in the bowl.

      -

      Alex: Treat examples as spoken recipes, not decorations. You may hear something like gh repo fork Community-Access/accessibility-agents --clone; cd accessibility-agents. Read the command, understand what it changes, then run it only when the repository state matches the lesson.

      -

      Alex: The useful habit is simple: orient first, act second, verify third. That pause before acting is part of the work.

      +

      Jamie: Let's pause on "I want to verify the PR only changes what it claims". What should a learner take away from it?

      +

      Alex: This is where "I want to verify the PR only changes what it claims" becomes real: example: A PR says "Challenge 2: Add NVDA shortcut" but the file tree shows changes to both docs/keyboard-shortcuts.md and docs/welcome.md.

      +

      Alex: Keep the teaching thread moving. Keep the learner anchored in "I want to find all changes to one specific section". Example: A PR for Challenge 3 modified docs/welcome.md. This is the part to say slowly: You want to verify the [TODO] in the "Who Can Contribute?" section was filled in correctly. A good GitHub workflow is like a well-run meeting: everyone knows the topic, the next action, and who has the floor.

      +

      Jamie: Why is the evidence prompt part of the teaching, not just grading?

      +

      Alex: The reason Exercises matters is that these exercises use the files in learning-room/docs/ in this repository. That gives the learner a simple foothold: all examples involve documentation changes - no code required.

      -

      Jamie: What is the ordered workflow?

      -

      Alex: Here is the plain-English version of On GitHub.com. The original repository at Community-Access/accessibility-agents is untouched.

      -

      Alex: Here is what that changes in practice. 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.". Owner: your username. Repository name: accessibility-agents. Copy the main branch only: checked (leave this checked).

      -

      Alex: First, go to github.com/Community-Access/accessibility-agents. Then, find the Fork button in the upper-right area of the page. After that, GitHub shows a "Create a new fork" page. The defaults are correct. Finally, activate Create fork. Treat it like a recipe: do not add the next ingredient until the previous one is actually in the bowl.

      -

      Jamie: Let's pause on On GitHub.com. What should a learner take away from it?

      -

      Alex: First, GitHub redirects you to your fork: github.com/your-username/accessibility-agents. It is a checklist, but a meaningful one: every item creates evidence that the next step is safe.

      -

      Jamie: What should happen before anyone copies and runs it?

      -

      Alex: This is where Using GitHub CLI becomes real: this creates the fork on GitHub without cloning it locally.

      -

      Alex: Treat examples as spoken recipes, not decorations. You may hear something like gh repo fork Community-Access/accessibility-agents --clone=false. Read the command, understand what it changes, then run it only when the repository state matches the lesson.

      -

      Jamie: Where do you want a learner to place their attention here?

      -

      Alex: Keep the learner anchored in 4. Step 2: Clone Your Fork Locally. Now download your fork to your computer so you can work on it.

      +

      Alex: Keep the teaching thread moving. Start with Exercise A - Complete a Web Review: Scenario: A contributor has submitted a pull request titled "Add screen reader tips to the setup guide." The PR modifies learning-room/docs/setup-guide.md. The next useful detail is this: Your job is to review it before it merges.

      +

      Jamie: Let's pause on Step 1: Navigate to the Pull Request. What should a learner take away from it?

      +

      Alex: Here is the plain-English version of Step 1: Navigate to the Pull Request. How to know you're in the right place.

      +

      Alex: The practical takeaway is this. The PR title is visible at the top. You see a description box with text about what this PR does. You see tabs labeled "Conversation," "Commits," "Files Changed". Use Ctrl+F to search the PR list for "screen reader tips". Or ask in the workshop Slack - someone can share the exact URL.

      +

      Alex: First, open GitHub in your browser and navigate to the workshop repository (github.com/[your-fork]/[workshop-repo] or community-access/accessibility-agents). Then, click the Pull Requests tab (top navigation). After that, look for a PR titled "Add screen reader tips to the setup guide" - click it to open. Finally, you should now see the PR page with sections: Conversation, Commits, Files Changed. Treat it like a recipe: do not add the next ingredient until the previous one is actually in the bowl.

      +

      Jamie: Let's pause on Step 2: Read the PR Description. What should a learner take away from it?

      +

      Alex: Start with Step 2: Read the PR Description. There is something to understand, something to try, and something that proves the try worked.

      +

      Alex: The practical takeaway is this. Does the PR author explain what file changed? (should mention setup-guide.md). Does it explain why? (should mention "improve accessibility" or "add tips"). Is it clear enough that a reviewer can understand the goal without reading the diff? You can answer: "This PR adds [specific content] to [specific file] because [clear reason]". Example: "This PR adds screen reader usage tips to the setup guide because new users need accessibility guidance".

      +

      Alex: First, you are currently on the Conversation tab. Then, read the PR description (the text immediately under the PR title). After that, look for: "What does this PR change?" and "Why does it change it?". Finally, with screen reader: Navigate to the description with D (NVDA) or press Ctrl+Option+Up (VoiceOver) to find main landmarks, then read the content region. It is a checklist, but a meaningful one: every item creates evidence that the next step is safe.

      -

      Jamie: Let's pause on Using VS Code. What should a learner take away from it?

      -

      Alex: Start with Using VS Code. There is something to understand, something to try, and something that proves the try worked.

      -

      Alex: First, open VS Code. Then, open the command palette: Ctrl+Shift+P (or Cmd+Shift+P). After that, type "Git: Clone" and press Enter. Finally, paste your fork URL: https://github.com/your-username/accessibility-agents.git (replace your-username with your GitHub username). The rhythm is simple: orient, act, verify, then continue.

      -

      Jamie: Before we leave Using VS Code, what is the practical point?

      -

      Alex: First, choose a folder (for example, Documents) and confirm. Then, when the clone finishes, VS Code offers to open the repository. Accept. Think of it as a rail line: each stop confirms you are still on the right route before the next one.

      -

      Jamie: What is the safe way to learn from that example?

      -

      Alex: Start with Using the terminal. There is something to understand, something to try, and something that proves the try worked.

      -

      Alex: Treat examples as spoken recipes, not decorations. You may hear something like git clone https://github.com/your-username/accessibility-agents.git; cd accessibility-agents. Read the command, understand what it changes, then run it only when the repository state matches the lesson.

      -

      Jamie: Let's pause on Using GitHub Desktop. What should a learner take away from it?

      -

      Alex: Start with Using GitHub Desktop. There is something to understand, something to try, and something that proves the try worked.

      -

      Alex: First, open GitHub Desktop. Then, go to File, then Clone repository. After that, select the GitHub.com tab and find your-username/accessibility-agents. Finally, choose a local path and click Clone. Treat it like a recipe: do not add the next ingredient until the previous one is actually in the bowl.

      +

      Jamie: Let's pause on Step 3: Navigate to "Files Changed". What should a learner take away from it?

      +

      Alex: Start with Step 3: Navigate to "Files Changed". There is something to understand, something to try, and something that proves the try worked.

      +

      Alex: The practical takeaway is this. A section showing the file name setup-guide.md with a small badge showing "+20 −0" (20 lines added, 0 lines removed). Below it, the diff with removed lines (preceded by −) and added lines (preceded by +). Scroll up to see if there are other files. For this exercise, only setup-guide.md should be changed. If you see other files, confirm they are not modified (the badge should show "+0 −0" or no changes).

      +

      Alex: First, click the Files Changed tab (top of the PR page, to the right of "Commits"). Then, you are now viewing the diff. After that, with keyboard (all screen readers): Press T to jump to the diff table. The page focuses on the file comparison area. It is like walking a hallway with named doors: read the sign, enter the right room, then confirm where you landed.

      +

      Jamie: Let's pause on Step 4: Activate Focus Mode for Better Diff Reading. What should a learner take away from it?

      +

      Alex: The reason Step 4: Activate Focus Mode for Better Diff Reading matters is that with screen reader (once in Focus Mode).

      +

      Alex: The practical takeaway is this. The page simplifies: sidebars disappear. Only the diff is visible - easier for screen reader navigation and less cognitive load. The diff is now the main content area. NVDA/JAWS: Press T to jump to the diff table. VoiceOver: Navigate with VO+Right Arrow to find the table/content region. Read through the changes: ↓ arrow moves to each line.

      +

      Alex: First, look for a button labeled "Focus Mode" or an icon (usually at the top right of the diff area). Then, with keyboard: Press F to toggle Focus Mode (may need to be in the diff area first). After that, with mouse: Click the Focus Mode button/icon. The rhythm is simple: orient, act, verify, then continue.

      +

      Jamie: Let's pause on Step 5: Find the Heading Hierarchy Issue. What should a learner take away from it?

      +

      Alex: Start with Step 5: Find the Heading Hierarchy Issue. There is something to understand, something to try, and something that proves the try worked.

      +

      Alex: The practical takeaway is this. Screen reader users navigate documents by heading level: 1 → 2 → 3 → 4. A skip from to breaks that navigation. When a user presses "jump to heading level 3," they'll find none, wondering if content is missing. You found the line with that violates hierarchy. You can say the line number and what heading text appears there. You understand why this is an accessibility problem.

      +

      Alex: First, read through the entire diff line by line. Pay special attention to lines starting. Then, you are looking for: a line with (four hashes, heading level 4) that comes directly after a (two hashes, heading level 2). After that, when you find it, note the exact line number shown in the diff. Think of it as a rail line: each stop confirms you are still on the right route before the next one.

      -

      Jamie: What should they understand before typing anything?

      -

      Alex: This is where Using GitHub CLI becomes real: after cloning, your local repository has one remote called origin that points to your fork.

      -

      Alex: Treat examples as spoken recipes, not decorations. You may hear something like gh repo clone your-username/accessibility-agents; cd accessibility-agents. Read the command, understand what it changes, then run it only when the repository state matches the lesson.

      -

      Alex: That connects to another useful point. Start with Learning Cards: Cloning Your Fork. There is something to understand, something to try, and something that proves the try worked.

      -

      Alex: For a learner, the useful signals are these. 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. 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.

      -

      Jamie: Give me the version that sounds like an instructor, not a manual.

      -

      Alex: The reason 5. Step 3: Add the Upstream Remote matters is that see also: Appendix E: Advanced Git for advanced remote and upstream management. That gives the learner a simple foothold: your clone knows about your fork (origin).

      +

      Jamie: Let's pause on Step 6: Place a Blocking Review Comment on the Heading. What should a learner take away from it?

      +

      Alex: Here is the plain-English version of Step 6: Place a Blocking Review Comment on the Heading. If the comment button doesn't appear. It is like learning a transit route. The names of the stops matter because they tell you whether you are still going the right direction.

      +

      Alex: The practical takeaway is this. Your comment appears in the thread under that line. The PR author sees it and can make the fix. Make sure you're hovering over the line number area (left side of the line). Try refreshing the page and trying again. Or use the "Add a reply" field at the bottom of the PR and mention the line number manually.

      +

      Alex: First, find the diff line with the problematic heading. Then, hover your mouse over the line number on the left side of that line (or if using keyboard, navigate to that line in the table). After that, a button should appear (or press the Add Comment hotkey - usually C in GitHub). Finally, click it or press Enter to open a comment box. Treat it like a recipe: do not add the next ingredient until the previous one is actually in the bowl.

      +

      Jamie: Before we leave Step 6: Place a Blocking Review Comment on the Heading, what is the practical point?

      +

      Alex: First, press Space, then explain. Then, click the Comment button (or press Ctrl+Enter for keyboard submit). It is a checklist, but a meaningful one: every item creates evidence that the next step is safe.

      +

      Jamie: Let's pause on Step 7: Find the Link Text Issue. What should a learner take away from it?

      +

      Alex: Start with Step 7: Find the Link Text Issue. There is something to understand, something to try, and something that proves the try worked.

      +

      Alex: The practical takeaway is this. Screen reader users can ask their reader to "list all links on this page" - they hear only the link text. If the text is "click here," they have no context about where it goes. Descriptive link text is WCAG 2.4.4 (Link Purpose). You found a link with non-descriptive text. You can explain why "click here" is bad and what would be better.

      +

      Alex: First, continue reading the diff (from where you left off). Then, look for a line containing link text that reads "click here" or "click here for more information". After that, note the line number. It is a checklist, but a meaningful one: every item creates evidence that the next step is safe.

      +

      Jamie: Let's pause on Step 8: Place a Comment on the Link. What should a learner take away from it?

      +

      Alex: Keep the learner anchored in Step 8: Place a Comment on the Link. nit: means "nice-to-have improvement" (not blocking, but good to fix).

      +

      Alex: First, find the line in the diff with the problematic link. Then, hover over the line number and click to open a comment box (or press C). After that, click Comment or press Ctrl+Enter. It is like walking a hallway with named doors: read the sign, enter the right room, then confirm where you landed.

      -

      Alex: Here is the practical turn. Start with Why this matters: Without the upstream remote, you cannot.

      -

      Alex: On the ground, that means a few things. 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.

      -

      Jamie: How do you keep commands from becoming magic words?

      -

      Alex: Start with Add the upstream remote. There is something to understand, something to try, and something that proves the try worked.

      -

      Alex: Treat examples as spoken recipes, not decorations. You may hear something like git remote add upstream https://github.com/Community-Access/accessibility-agents.git. Read the command, understand what it changes, then run it only when the repository state matches the lesson.

      -

      Jamie: Let's pause on Verify your remotes. What should a learner take away from it?

      -

      Alex: This is where Verify your remotes becomes real: two remotes: origin (your fork) and upstream (the original). That matters in practice: In VS Code: You can also add the remote using the command palette. The workshop is closer to rehearsal than lecture. You hear the move, try the move, and then check what changed.

      -

      Alex: Treat examples as spoken recipes, not decorations. You may hear something like git remote -v. Read the command, understand what it changes, then run it only when the repository state matches the lesson.

      +

      Jamie: Let's pause on Step 9: Submit Your Review. What should a learner take away from it?

      +

      Alex: Start with Step 9: Submit Your Review. There is something to understand, something to try, and something that proves the try worked.

      +

      Alex: The practical takeaway is this. Comment - provide feedback but don't block (for minor notes). Approve - the PR is ready to merge. Request changes - this PR cannot merge until changes are made. Your review is submitted. The PR author gets a notification. The PR shows your review with the two comments.

      +

      Alex: First, look for a button labeled "Review changes" (usually at the top right of the page or bottom of comments). Then, click it (or navigate with keyboard and press Enter). After that, a dialog appears with options. Finally, select "Request changes" (you found two things to fix). The rhythm is simple: orient, act, verify, then continue.

      +

      Jamie: Before we leave Step 9: Submit Your Review, what is the practical point?

      +

      Alex: First, in the summary field, write: Found 2 accessibility issues that must be fixed before merging. Then, click "Submit review". Think of it as a rail line: each stop confirms you are still on the right route before the next one.

      +

      Jamie: Let's pause on Reflect on This Exercise. What should a learner take away from it?

      +

      Alex: Start with Reflect on This Exercise: Keep your answers - you'll need them for Chapter 16's Accessibility Agents exercise to compare manual review with agent-assisted review. Think of it like entering a new building: first you find the lobby, then the room, then the door you actually need.

      +

      Alex: First, did heading-level navigation help? When you were looking for the issue, was it easier to navigate by heading level (1-6) than to scan every line? Then, would you have caught this without the exercise prompt? If you were a real reviewer not specifically looking for heading issues, would the diff have been obvious? After that, why does screen reader navigation matter? In one sentence, explain why a screen reader user's ability to jump through heading levels is important for this document. Think of it as a rail line: each stop confirms you are still on the right route before the next one.

      +

      Jamie: What stays the same when the tool changes?

      +

      Alex: Here is the plain-English version of Exercise B - Use the VS Code Accessible Diff Viewer. Scenario: Review the same pull request from Exercise A, this time entirely in VS Code. Put another way, you'll compare the browser experience with the VS Code experience.

      -

      Jamie: If I am listening before the workshop starts, what should settle in my mind first?

      -

      Alex: Keep the learner anchored in 6. Step 4: Create a Feature Branch. Never work directly on the main branch of your fork. This is the part to say slowly: Always create a feature branch for each change.

      -

      Jamie: Let's pause on Create and switch to a new branch. What should a learner take away from it?

      -

      Alex: The reason Create and switch to a new branch matters is that the branch name agents/your-username-my-agent follows the workshop convention for Day 2 capstone branches. That gives the learner a simple foothold: replace your-username with your GitHub username and my-agent with a short name for your agent.

      -

      Alex: Treat examples as spoken recipes, not decorations. You may hear something like git checkout -b agents/your-username-my-agent. Read the command, understand what it changes, then run it only when the repository state matches the lesson.

      -

      Jamie: Let's pause on In VS Code. What should a learner take away from it?

      -

      Alex: Start with In VS Code. There is something to understand, something to try, and something that proves the try worked.

      -

      Alex: First, click the branch name in the bottom-left status bar (or press Ctrl+Shift+P and type "Git: Create Branch"). Then, type the branch name: agents/your-username-my-agent. After that, press Enter. VS Code creates the branch and switches to it. Think of it as a rail line: each stop confirms you are still on the right route before the next one.

      +

      Alex: Keep the teaching thread moving. Start with Prerequisites. There is something to understand, something to try, and something that proves the try worked.

      +

      Alex: The practical takeaway is this. VS Code must be installed on your machine. The GitHub Pull Requests extension must be installed (see Chapter 12 for installation). You must be signed into GitHub from VS Code (use Ctrl+Shift+P → "GitHub: Sign in").

      +

      Jamie: Let's pause on Step 1: Open the GitHub Pull Requests Extension. What should a learner take away from it?

      +

      Alex: Start with Step 1: Open the GitHub Pull Requests Extension. There is something to understand, something to try, and something that proves the try worked.

      +

      Alex: The practical takeaway is this. With mouse: Click the Extensions icon on the left sidebar (looks like four squares). The extension is listed as active. It mentions: "Review and manage GitHub pull requests and issues".

      +

      Alex: First, open VS Code. Then, with keyboard (all screen readers): Press Ctrl+Shift+X to open the Extensions sidebar. After that, search for "GitHub Pull Requests". Finally, if it's not installed, click Install. It is like walking a hallway with named doors: read the sign, enter the right room, then confirm where you landed.

      +

      Jamie: Before we leave Step 1: Open the GitHub Pull Requests Extension, what is the practical point?

      +

      Alex: First, if it is installed, click GitHub Pull Requests to view its details. The rhythm is simple: orient, act, verify, then continue.

      +

      Jamie: Let's pause on Step 2: Open the Pull Requests Sidebar. What should a learner take away from it?

      +

      Alex: Start with Step 2: Open the Pull Requests Sidebar. There is something to understand, something to try, and something that proves the try worked.

      +

      Alex: The practical takeaway is this. With keyboard: The icon may not be keyboard-reachable directly; instead go to Step 3. VS Code opens a new editor tab for this PR. Below the PR title, you see a "Changes" section listing modified files. You should see setup-guide.md in the changes list. Use Ctrl+Shift+P → search GitHub Pull Requests: Open Pull Request. Paste the PR URL: https://github.com/[owner]/[repo]/pull/[number].

      +

      Alex: First, look for a GitHub-themed icon on the left sidebar (circle with octocat logo) - click it. Then, a sidebar appears showing open pull requests on repositories you have access to. After that, find the PR titled "Add screen reader tips to the setup guide" - it should appear in a list. Finally, click it to open. The rhythm is simple: orient, act, verify, then continue.

      -

      Jamie: Let's pause on In GitHub Desktop. What should a learner take away from it?

      -

      Alex: Start with In GitHub Desktop. There is something to understand, something to try, and something that proves the try worked.

      -

      Alex: First, click the Current Branch dropdown. Then, click New Branch. After that, type the branch name and click Create Branch. Treat it like a recipe: do not add the next ingredient until the previous one is actually in the bowl.

      -

      Jamie: Let's pause on Verify you are on the new branch. What should a learner take away from it?

      -

      Alex: This is where Verify you are on the new branch becomes real: the current branch has an asterisk ( ) next to it.

      -

      Alex: Treat examples as spoken recipes, not decorations. You may hear something like git branch. Read the command, understand what it changes, then run it only when the repository state matches the lesson.

      -

      Alex: The next layer is this. Keep the learner anchored in 7. Step 5: Make Your Changes. Now you are on your feature branch and ready to work. This is the part to say slowly: For the capstone, you will create an agent file.

      +

      Jamie: Let's pause on Step 3: View the File Changes. What should a learner take away from it?

      +

      Alex: Start with Step 3: View the File Changes. There is something to understand, something to try, and something that proves the try worked.

      +

      Alex: The practical takeaway is this. A diff editor opens showing two columns. Left: the original file (before changes). Right: the new file (after changes). Different colors show added (green), removed (red), and modified (blue) lines. The file name appears at the top: setup-guide.md. NVDA/JAWS: The editor announces "Diff Editor - setup-guide.md".

      +

      Alex: First, in the Changes section, locate setup-guide.md. Then, click on the filename to open it. Think of it as a rail line: each stop confirms you are still on the right route before the next one.

      +

      Jamie: Let's pause on Step 4: Access the Accessible Diff Viewer. What should a learner take away from it?

      +

      Alex: Here is the plain-English version of Step 4: Access the Accessible Diff Viewer. If the Accessible Diff Viewer doesn't open.

      +

      Alex: The practical takeaway is this. With mouse: Look for a button or menu option labeled "Accessible View" or "Open Accessible Diff". If no button is visible, try Alt+F2 (VS Code Accessible View toggle). A new panel opens at the bottom of VS Code. The panel announces each change one at a time. Changes appear in text format with labels: "Added: " and "Removed: ". The panel is read-only (you read the changes, you don't edit here).

      +

      Alex: First, with keyboard: Press F7 to open the Accessible Diff Viewer. Treat it like a recipe: do not add the next ingredient until the previous one is actually in the bowl.

      +

      Jamie: Let's pause on Step 5: Listen to and Understand the First Change. What should a learner take away from it?

      +

      Alex: Start with Step 5: Listen to and Understand the First Change. There is something to understand, something to try, and something that proves the try worked.

      +

      Alex: The practical takeaway is this. NVDA/JAWS: The Accessible Diff Viewer announces "Removed:" and "Added:" labels, followed by the line content. VoiceOver: The announcement may be similar; listen for "removed" and "added" keywords.

      +

      Alex: First, the first change is automatically announced when you open the Accessible Diff Viewer. Then, let your screen reader read it completely - don't interrupt. After that, write down the exact text announced. Finally, press the Down arrow to move to the next change. It is a checklist, but a meaningful one: every item creates evidence that the next step is safe.

      -

      Jamie: Let's pause on General principles for contributing. What should a learner take away from it?

      -

      Alex: Start with General principles for contributing. There is something to understand, something to try, and something that proves the try worked.

      -

      Alex: The room should hear these as checkpoints. 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.

      -

      Alex: A solid pull request habit is to separate three questions: what changed, why it changed, and what still needs review. That keeps the conversation useful instead of noisy.

      -

      Jamie: Let's pause on Stage and commit your changes. What should a learner take away from it?

      -

      Alex: Start with Stage and commit your changes. There is something to understand, something to try, and something that proves the try worked.

      -

      Alex: Treat examples as spoken recipes, not decorations. You may hear something like git add your-file.md; git commit -m "Add my-agent accessibility agent". git add.; git commit -m "Add my-agent accessibility agent". Read the command, understand what it changes, then run it only when the repository state matches the lesson.

      -

      Jamie: Before we leave In VS Code, what is the practical point?

      -

      Alex: These are the details that keep the idea from floating away. 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.

      -

      Alex: First, open the Source Control panel: Ctrl+Shift+G (or Cmd+Shift+G). Then, changed files appear under "Changes." Click the + icon next to each file to stage it, or click + on the "Changes" header to stage all. After that, type your commit message in the text field at the top. Finally, press Ctrl+Enter (or Cmd+Enter) to commit. Treat it like a recipe: do not add the next ingredient until the previous one is actually in the bowl.

      +

      Jamie: Let's pause on Step 6: Find the Heading Hierarchy Issue. What should a learner take away from it?

      +

      Alex: Start with Step 6: Find the Heading Hierarchy Issue. There is something to understand, something to try, and something that proves the try worked.

      +

      Alex: The practical takeaway is this. Four hashes ( ) indicate a level 4 heading. In the diff, you're looking for it appearing after a level 2 heading ( ). This creates the hierarchy skip you caught in Exercise A. You found the explanation in the Accessible Diff Viewer's format. You can explain: "The added line with directly follows a, skipping level 3". The Accessible Diff Viewer made this pattern clearer than scanning raw + characters.

      +

      Alex: First, continue pressing Down arrow to move through changes. Then, listen carefully for a change involving headings (lines starting with ). After that, specifically, listen for: "Added: " (four hashes). Finally, when you hear this, stop and write it down. It is like walking a hallway with named doors: read the sign, enter the right room, then confirm where you landed.

      +

      Jamie: Let's pause on Step 7: Locate the Heading Line and Add an Inline Comment. What should a learner take away from it?

      +

      Alex: Start with Step 7: Locate the Heading Line and Add an Inline Comment. There is something to understand, something to try, and something that proves the try worked.

      +

      Alex: The practical takeaway is this. Use Ctrl+F to open Find. Search for to locate it quickly. Press Enter to jump to it. With keyboard: The comment button may appear on the current line; navigate to it and press Enter. A comment box opens. You can type your comment.

      +

      Alex: First, once you identified the problematic heading in the Accessible Diff Viewer, close the Accessible Diff Viewer (press F7 again or Alt+F2). Then, you're back in the regular Diff Editor. After that, find the line with the problematic heading. Finally, close Find (Escape). The rhythm is simple: orient, act, verify, then continue.

      +

      Jamie: Before we leave Step 7: Locate the Heading Line and Add an Inline Comment, what is the practical point?

      +

      Alex: First, place your cursor on that line. Then, right-click and select "Add Comment" or press the Comment icon that appears on the left margin. Think of it as a rail line: each stop confirms you are still on the right route before the next one.

      +

      Jamie: Let's pause on Step 8: Write Your Accessible Diff Comment. What should a learner take away from it?

      +

      Alex: Start with Step 8: Write Your Accessible Diff Comment: Why mention the Accessible Diff Viewer?

      +

      Alex: The practical takeaway is this. It shows that the tool itself helps you see the issue. It documents how you caught the problem (useful for learning).

      +

      Alex: First, in the comment box, type. Then, press Ctrl+Enter or click Comment to submit. Think of it as a rail line: each stop confirms you are still on the right route before the next one.

      -

      Alex: That matters because of the next idea. This is where Multiple commits are fine becomes real: you do not need to make all your changes in a single commit. That matters in practice: In fact, smaller commits are better because they are easier to review and easier to revert if something goes wrong.

      -

      Jamie: Let's pause on 8. Step 6: Push to Your Fork. What should a learner take away from it?

      -

      Alex: Keep the learner anchored in 8. Step 6: Push to Your Fork. Now push them to your fork on GitHub.

      -

      Jamie: Let's pause on First push (new branch). What should a learner take away from it?

      -

      Alex: The reason First push (new branch) matters is that the -u flag sets up tracking so future pushes from this branch go to the right place automatically. The interface gets friendlier when it stops being a wall of controls and starts being a set of named places.

      -

      Alex: Treat examples as spoken recipes, not decorations. You may hear something like git push -u origin agents/your-username-my-agent. Read the command, understand what it changes, then run it only when the repository state matches the lesson.

      +

      Jamie: Let's pause on Step 9: Create a GitHub Pull Request Comment. What should a learner take away from it?

      +

      Alex: Here is the plain-English version of Step 9: Create a GitHub Pull Request Comment. Now you've reviewed the same PR in.

      +

      Alex: First, browser (Exercise A): You spot-checked line numbers manually. Then, VS Code (Exercise B): The Diff Editor plus Accessible Diff Viewer announced changes. After that, go to GitHub in your browser and open the same PR. Finally, scroll to the bottom and leave a comment in the Conversation tab. Treat it like a recipe: do not add the next ingredient until the previous one is actually in the bowl.

      +

      Jamie: Before we leave Step 9: Create a GitHub Pull Request Comment, what is the practical point?

      +

      Alex: First, click Comment. It is a checklist, but a meaningful one: every item creates evidence that the next step is safe.

      +

      Jamie: Before we leave Reflect on This Exercise, what is the practical point?

      +

      Alex: This is where Reflect on This Exercise becomes real: after completing Steps 1-9, answer. That matters in practice: In Chapter 16, you'll compare these manual reviews with the @pr-review agent's suggested changes. The workshop is closer to rehearsal than lecture. You hear the move, try the move, and then check what changed.

      +

      Alex: First, announcement clarity: Did the "Added:" and "Removed:" labels from the Accessible Diff Viewer help you follow changes faster than reading + and − prefixes in the browser? Then, navigation pattern: Which tool required less back-and-forth clicking/tabbing to understand each change? After that, when would you use each? In one sentence: describe a type of PR where you'd prefer to use each tool. It is a checklist, but a meaningful one: every item creates evidence that the next step is safe.

      +

      Jamie: How do these exercises create confidence instead of pressure?

      +

      Alex: Keep the learner anchored in Exercise C - Compare and Reflect. Your Mission: Synthesize what you learned from the manual code reviews (Exercises A & B) and document your findings. This is the part to say slowly: What You'll Learn: Which tools work best for different scenarios, and how your manual review skills prepare you to use AI agents effectively.

      -

      Jamie: Let's pause on Subsequent pushes. What should a learner take away from it?

      -

      Alex: Start with Subsequent pushes. There is something to understand, something to try, and something that proves the try worked.

      -

      Alex: Treat examples as spoken recipes, not decorations. You may hear something like git push. Read the command, understand what it changes, then run it only when the repository state matches the lesson.

      -

      Alex: Before the learner moves on. Here is the plain-English version of In VS Code. After committing, the Source Control panel shows a Sync Changes button (or a cloud icon with an up arrow). Put another way, alternatively, use the command palette: Ctrl+Shift+P, type "Git: Push.".

      -

      Jamie: What stays the same when the tool changes?

      -

      Alex: This is where In GitHub Desktop becomes real: after committing, click the Push origin button in the top bar.

      +

      Alex: Keep the teaching thread moving. The reason Step 1: Gather Your Data matters is that before writing your reflection, collect all the information you gathered. That gives the learner a simple foothold: write these down (in a text editor, on paper, or mentally) - you'll reference them in Steps 2-4.

      +

      Alex: The practical takeaway is this. Which line number had the heading hierarchy skip? Which line number had the link text issue? How many steps did it take to find each issue? Did you use screen reader commands or visual scanning more?

      +

      Jamie: Let's pause on Step 2: Navigate to the PR and Leave Your Reflection Comment. What should a learner take away from it?

      +

      Alex: Start with Step 2: Navigate to the PR and Leave Your Reflection Comment. There is something to understand, something to try, and something that proves the try worked.

      +

      Alex: The practical takeaway is this. A text editing area with formatting options (Bold, Italic, Link, etc.). A Comment button below the text area.

      +

      Alex: First, go to GitHub in your browser. Then, open the same PR ("Add screen reader tips to the setup guide"). After that, scroll to the Conversation tab. Finally, scroll all the way down to the comment box at the bottom (labeled "Leave a comment" or "Add a comment"). Think of it as a rail line: each stop confirms you are still on the right route before the next one.

      +

      Jamie: Before we leave Step 2: Navigate to the PR and Leave Your Reflection Comment, what is the practical point?

      +

      Alex: First, click in the comment box. Treat it like a recipe: do not add the next ingredient until the previous one is actually in the bowl.

      +

      Alex: Keep the teaching thread moving. Here is the plain-English version of Step 3: Write Your Comparison. Type your response to these three questions. Put another way, be specific - reference exact tools, steps, and what you discovered. It is like learning a transit route. The names of the stops matter because they tell you whether you are still going the right direction.

      -

      Alex: Hold that next to this. Keep the learner anchored in Verify on GitHub. After pushing, visit your fork on GitHub: github.com/your-username/accessibility-agents. This is the part to say slowly: You should see a banner saying "your-username-my-agent had recent pushes" with a Compare and pull request button. A good GitHub workflow is like a well-run meeting: everyone knows the topic, the next action, and who has the floor.

      -

      Jamie: Let's pause on 9. Step 7: Open a Pull Request. What should a learner take away from it?

      -

      Alex: The reason 9. Step 7: Open a Pull Request matters is that a pull request asks the upstream maintainers to merge your branch into their repository.

      -

      Jamie: Let's pause on From the GitHub.com banner. What should a learner take away from it?

      -

      Alex: Start with From the GitHub.com banner. There is something to understand, something to try, and something that proves the try worked.

      -

      Alex: That becomes easier when you listen for these cues. Base repository: Community-Access/accessibility-agents. Base branch: main. Head repository: your-username/accessibility-agents. Compare branch: agents/your-username-my-agent. What your change does. Why it is useful.

      -

      Alex: First, after pushing, GitHub shows a yellow banner on your fork with a Compare and pull request button. Click it. Then, GitHub opens the "Open a pull request" page. Verify. After that, write a descriptive title. Example: "Add document-contrast-checker agent.". Finally, in the body, explain. Think of it as a rail line: each stop confirms you are still on the right route before the next one.

      -

      Jamie: Before we leave From the GitHub.com banner, what is the practical point?

      -

      Alex: First, if the project has a PR template, fill in all the required sections. Then, activate Create pull request. Treat it like a recipe: do not add the next ingredient until the previous one is actually in the bowl.

      +

      Jamie: Let's pause on Step 4: Review Your Comment. What should a learner take away from it?

      +

      Alex: Start with Step 4: Review Your Comment. There is something to understand, something to try, and something that proves the try worked.

      +

      Alex: The practical takeaway is this. Is it clear which tool I preferred? Did I explain why with concrete examples? Am I describing the real-world impact accurately? Would someone else reading this understand how I caught the issue?

      +

      Alex: First, before submitting, re-read your comment using your screen reader or by reading aloud. Then, ask yourself. After that, make any corrections needed. Finally, do not submit yet - continue to Step 5. It is a checklist, but a meaningful one: every item creates evidence that the next step is safe.

      +

      Jamie: Let's pause on Step 5: Submit Your Reflection. What should a learner take away from it?

      +

      Alex: Start with Step 5: Submit Your Reflection. There is something to understand, something to try, and something that proves the try worked.

      +

      Alex: The practical takeaway is this. Your comment is now visible on the PR. Other reviewers can see your comparison. You have completed the three-part exercise series. Your comment appears on the PR thread. It includes all three reflections. The PR author and other reviewers can see your thought process.

      +

      Alex: First, locate the Comment button at the bottom right of the comment box. Then, with keyboard: Press Tab until the Comment button is focused, then Enter. After that, with mouse: Click the Comment button. Finally, your comment is submitted and appears on the PR page. It is like walking a hallway with named doors: read the sign, enter the right room, then confirm where you landed.

      +

      Jamie: Let's pause on Step 6: Checkpoint - Validate Your Learning. What should a learner take away from it?

      +

      Alex: The reason Step 6: Checkpoint - Validate Your Learning matters is that before moving forward, verify you understand. That gives the learner a simple foothold: if you can answer all three, you're ready for the next chapter.

      +

      Alex: The practical takeaway is this. Expected answer: Something like "Screen readers let users navigate by heading level (pressing 3 jumps to H3), so skipping a level makes users think content is missing.". Expected answer: e.g., "Browser: finding context in discussions. VS Code: linear reading of changes.". Expected answer: Something like "Open the document in a browser, use screen reader heading navigation, and confirm I can reach all levels (H2, H3, H4).".

      +

      Alex: First, heading Hierarchy: Can you explain in one sentence why a → skip breaks screen reader navigation? Then, tool Strengths: For each tool you used, name one task it made easier. After that, real-World Testing: How would you test the heading issue in the published document (not the PR diff)? The rhythm is simple: orient, act, verify, then continue.

      -

      Jamie: Let's pause on From the Pull Requests tab. What should a learner take away from it?

      -

      Alex: Start with From the Pull Requests tab. There is something to understand, something to try, and something that proves the try worked.

      -

      Alex: First, go to the upstream repository: github.com/Community-Access/accessibility-agents. Then, click the Pull requests tab. After that, click New pull request. Finally, click compare across forks. Treat it like a recipe: do not add the next ingredient until the previous one is actually in the bowl.

      -

      Jamie: Before we leave From the Pull Requests tab, what is the practical point?

      -

      Alex: First, set the head repository to your fork and the compare branch to your feature branch. Then, click Create pull request and fill in the details. It is a checklist, but a meaningful one: every item creates evidence that the next step is safe.

      -

      Jamie: Let's pause on Using GitHub CLI. What should a learner take away from it?

      -

      Alex: This is where Using GitHub CLI becomes real: the PR creation form is a standard web form. That matters in practice: Navigate with Tab to move between fields. The workshop is closer to rehearsal than lecture. You hear the move, try the move, and then check what changed.

      -

      Alex: Treat examples as spoken recipes, not decorations. You may hear something like 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.". Read the command, understand what it changes, then run it only when the repository state matches the lesson.

      -

      Jamie: Let's pause on Learning Cards: Opening a Pull Request. What should a learner take away from it?

      -

      Alex: Start with Learning Cards: Opening a Pull Request. There is something to understand, something to try, and something that proves the try worked.

      -

      Alex: A few details make that real. The PR form has a title input and a body textarea -- Tab between them; your screen reader announces field labels. The base and compare branch dropdowns use ARIA listbox patterns -- press Down Arrow to open and select branches. After submitting, GitHub navigates to the new PR page; press h to jump by headings and find the "Files changed" section. The "Compare and pull request" yellow banner appears at the top of your fork page after pushing -- it is a large, visible button. Use browser zoom (Ctrl+=) to enlarge the PR creation form if the text inputs are too small. The base and head repository/branch selectors appear near the top of the form -- verify these before submitting.

      +

      Alex: Keep the teaching thread moving. Start with Using GitHub Copilot to Understand Code Changes: Reviewing code is about understanding what changed, why it changed, and whether the change is safe and correct. The next useful detail is this: GitHub Copilot can help you gather and understand information about code changes - especially when diffs are large, complex, or involve unfamiliar frameworks. Think of it like entering a new building: first you find the lobby, then the room, then the door you actually need.

      +

      Jamie: Let's pause on When to Use Copilot During Code Review. What should a learner take away from it?

      +

      Alex: Here is the plain-English version of When to Use Copilot During Code Review. Copilot is most useful for answering these questions.

      +

      Alex: First, "What does this code do?" - you're reading unfamiliar syntax or a framework you don't know well. Then, "Why might this change break something?" - you need to understand dependencies or side effects. After that, "Is this pattern safe?" - you want to verify that the approach follows best practices. Finally, "What would be a better way to write this?" - you're looking for alternatives to suggest. Treat it like a recipe: do not add the next ingredient until the previous one is actually in the bowl.

      +

      Jamie: Before we leave When to Use Copilot During Code Review, what is the practical point?

      +

      Alex: First, "Does this match the PR's description?" - the change seems to do more (or less) than claimed. It is a checklist, but a meaningful one: every item creates evidence that the next step is safe.

      +

      Jamie: Let's pause on In VS Code with an Open Diff. What should a learner take away from it?

      +

      Alex: Start with In VS Code with an Open Diff. There is something to understand, something to try, and something that proves the try worked.

      +

      Alex: First, open the PR using the GitHub Pull Requests extension (see Part 2). Then, open the diff for any file. After that, select a block of code that confuses you (highlight it). Finally, open Copilot Chat: Ctrl+Shift+I. It is a checklist, but a meaningful one: every item creates evidence that the next step is safe.

      +

      Jamie: Before we leave In VS Code with an Open Diff, what is the practical point?

      +

      Alex: First, Copilot reads the selected code and answers in the chat. It is like walking a hallway with named doors: read the sign, enter the right room, then confirm where you landed.

      -

      Alex: Keep the thread going. The reason 10. Step 8: Respond to Review Feedback matters is that after you open a pull request, maintainers and peers will review your changes.

      -

      Alex: The practical anchors are these. Approve - your PR is ready to merge. Request changes - you need to update your PR. Comment - ask questions or suggest improvements without formally requesting changes.

      -

      Jamie: Let's pause on How to respond to requested changes. What should a learner take away from it?

      -

      Alex: Start with How to respond to requested changes. There is something to understand, something to try, and something that proves the try worked.

      -

      Alex: First, read each review comment carefully. Understand what the reviewer is asking. Then, make the requested changes in your local clone. After that, stage, commit, and push. Finally, your new commits automatically appear in the open pull request. The reviewer is notified. Think of it as a rail line: each stop confirms you are still on the right route before the next one.

      -

      Jamie: Before we leave How to respond to requested changes, what is the practical point?

      -

      Alex: First, reply to each review comment explaining what you changed, or ask clarifying questions if the feedback is unclear. Treat it like a recipe: do not add the next ingredient until the previous one is actually in the bowl.

      -

      Alex: Treat examples as spoken recipes, not decorations. You may hear something like git add modified-file.md; git commit -m "Address review feedback: improve guardrails section"; git push. Read the command, understand what it changes, then run it only when the repository state matches the lesson.

      -

      Alex: Another way to ground it. Here is the plain-English version of Review etiquette. The Day 1 connection: You practiced code review in Chapter 15. Put another way, the same principles apply here, but now you are on the other side -- receiving feedback instead of giving it. It is like learning a transit route. The names of the stops matter because they tell you whether you are still going the right direction.

      -

      Alex: That shows up in the workshop in a few specific ways. Thank the reviewer. They spent time reading your code. Address every comment. Even if you disagree, explain your reasoning. Do not take feedback personally. Review is about the code, not about you. Ask questions. If you do not understand a comment, ask. Reviewers expect questions from new contributors.

      +

      Jamie: Let's pause on On GitHub.com (Web Interface). What should a learner take away from it?

      +

      Alex: Keep the learner anchored in On GitHub.com (Web Interface). Another option: Use the GitHub Copilot inline suggestions on GitHub.com.

      +

      Alex: The practical takeaway is this. Some GitHub PRs show Copilot insights directly in the diff (as of early 2026). If you see a lightbulb icon, click it to see Copilot's suggestion about that line.

      +

      Alex: First, open the PR's Files Changed tab. Then, focus on a line or section you want to understand better. After that, in VS Code Copilot Chat (not in the browser - Copilot Chat doesn't work directly in browser diffs yet). Finally, copy the confusing code, paste it into chat, and ask Copilot to explain. It is like walking a hallway with named doors: read the sign, enter the right room, then confirm where you landed.

      +

      Alex: Keep the teaching thread moving. The reason Copilot Limitations During Review (Critical to Know) matters is that this is why manual review is essential: You have context (project history, team decisions, user impact) that Copilot does not. That gives the learner a simple foothold: use Copilot to understand, then use your judgment to decide. The interface gets friendlier when it stops being a wall of controls and starts being a set of named places.

      +

      Alex: The practical takeaway is this. See the whole project - it sees only what you show it (the selected diff, not the context of the entire codebase). Verify correctness - it can explain what code does, but not whether it's correct for your specific use case. Understand intent - it reads the code, not the author's mind or the PR description. Catch all risks - it can spot common patterns, but not edge cases unique to your project.

      +

      Jamie: Let's pause on Best Practices. What should a learner take away from it?

      +

      Alex: Start with Best Practices. There is something to understand, something to try, and something that proves the try worked.

      +

      Alex: First, read the diff manually first - you spot the big picture before asking Copilot details. Then, ask Copilot specific questions - not "review this code" but "does this regex handle Unicode?". After that, fact-check Copilot's answers - it can be confidently wrong, especially about frameworks or domains it has less training data. Finally, combine Copilot with manual analysis - ask Copilot to explain, then verify by checking the PR description or looking for related files. Think of it as a rail line: each stop confirms you are still on the right route before the next one.

      +

      Jamie: Before we leave Best Practices, what is the practical point?

      +

      Alex: First, use Copilot to draft comments - type Draft a comment about [issue] for this PR and edit Copilot's suggestion to match your tone. Treat it like a recipe: do not add the next ingredient until the previous one is actually in the bowl.

      -

      Jamie: Let's pause on 11. Keeping Your Fork in Sync. What should a learner take away from it?

      -

      Alex: This is where 11. Keeping Your Fork in Sync becomes real: over time, other people's changes get merged into the upstream repository. That matters in practice: Your fork does not update automatically.

      -

      Jamie: Let's pause on Sync from the command line. What should a learner take away from it?

      -

      Alex: Start with Sync from the command line. There is something to understand, something to try, and something that proves the try worked.

      -

      Alex: Treat examples as spoken recipes, not decorations. You may hear something like Make sure you are on main; git checkout main; Download the latest changes from upstream; git fetch upstream; Merge upstream changes into your local main; git merge upstream/main; Push the updated main to your fork; git push origin main. Read the command, understand what it changes, then run it only when the repository state matches the lesson.

      -

      Jamie: Let's pause on Sync from GitHub.com. What should a learner take away from it?

      -

      Alex: Start with Sync from GitHub.com. There is something to understand, something to try, and something that proves the try worked.

      -

      Alex: First, go to your fork on GitHub. Then, if your fork is behind the upstream, GitHub shows a banner: "This branch is X commits behind Community-Access:main.". After that, click Sync fork, then Update branch. The rhythm is simple: orient, act, verify, then continue.

      +

      Alex: Keep the teaching thread moving. Here is the plain-English version of What Comes Next. Your manual code review skills - identifying heading issues, catching link text problems, understanding screen reader navigation, gathering information with Copilot - are the foundation for understanding automated review. Put another way, in Chapter 16 (Accessibility Agents), you'll meet a full team of agents designed to amplify these skills.

      +

      Jamie: Let's pause on Part 4: The Reviewer's Craft. What should a learner take away from it?

      +

      Alex: This is where The Reviewer's Craft becomes real: parts 1 through 3 taught you the mechanics -- how to read diffs, leave comments, and use Copilot to understand unfamiliar code. That matters in practice: This part covers something equally important: how to think like a reviewer.

      +

      Alex: Keep the teaching thread moving. Keep the learner anchored in What to Look for in a Review. Every PR is different, but most reviews benefit from scanning across these five categories. This is the part to say slowly: You do not need to check every category exhaustively on every PR. A good GitHub workflow is like a well-run meeting: everyone knows the topic, the next action, and who has the floor.

      -

      Jamie: Let's pause on Sync from GitHub CLI. What should a learner take away from it?

      -

      Alex: Start with Sync from GitHub CLI. There is something to understand, something to try, and something that proves the try worked.

      -

      Alex: Treat examples as spoken recipes, not decorations. You may hear something like gh repo sync your-username/accessibility-agents. Read the command, understand what it changes, then run it only when the repository state matches the lesson.

      -

      Jamie: Let's pause on When to sync. What should a learner take away from it?

      -

      Alex: Start with When to sync. There is something to understand, something to try, and something that proves the try worked.

      -

      Alex: The practical takeaway is this. Before starting new work: Always sync before creating a new feature branch. This ensures your branch starts from the latest code. Before opening a PR: Sync and merge main into your feature branch to check for conflicts before asking for review. Periodically: If you are working on a long-running branch, sync weekly to avoid large conflicts.

      -

      Alex: Now bring the learner back to the room. Start with Learning Cards: Keeping Your Fork in Sync. There is something to understand, something to try, and something that proves the try worked.

      -

      Alex: The practical takeaway is this. Run git fetch upstream then git merge upstream/main in the terminal -- listen for "Already up to date" or a merge summary announcing new commits. Use git status after syncing to confirm your local main is not behind the upstream. On GitHub.com, the "Sync fork" button is near the top of your fork page; press Tab to reach it and Enter to activate. On GitHub.com, the "Sync fork" button appears below the repository description with a dropdown showing how many commits behind you are. After syncing, the Status Bar in VS Code shows no up/down arrows next to the branch name, confirming you are in sync. If a merge conflict occurs during sync, VS Code highlights conflicts with colored backgrounds (green = yours, blue = upstream).

      +

      Jamie: Let's pause on The Three Review Actions. What should a learner take away from it?

      +

      Alex: The reason The Three Review Actions matters is that when you submit a review on GitHub, you choose one of three actions. That gives the learner a simple foothold: picking the right one matters because it signals your intent to the author and to anyone else watching the PR.

      +

      Alex: First, did you find a bug, security issue, or broken test? -- Request Changes. Then, does the code do something different from what the description says? -- Request Changes. After that, does everything work, with maybe a few style nits? -- Approve (mention the nits in a comment). Finally, do you have questions or optional suggestions? -- Comment. The rhythm is simple: orient, act, verify, then continue.

      +

      Alex: Keep the teaching thread moving. Start with Writing Constructive Feedback: The way you phrase feedback determines whether the author feels supported or attacked. The next useful detail is this: Before pointing out problems, acknowledge something the author did well.

      +

      Jamie: Let's pause on The Reviewer's Checklist. What should a learner take away from it?

      +

      Alex: Here is the plain-English version of The Reviewer's Checklist. Run through this list mentally (or copy it into your notes) for every PR you review.

      +

      Alex: The practical takeaway is this. [ ] I read the PR description before reading the code. [ ] The code does what the description says it does. [ ] The change does not include unrelated modifications. [ ] Variable and function names are clear. [ ] I checked for accessibility: labels, headings, keyboard reach, contrast. [ ] I verified no existing behavior is broken by the change.

      -

      Jamie: Let's pause on 12. The Fork Workflow Checklist. What should a learner take away from it?

      -

      Alex: Keep the learner anchored in 12. The Fork Workflow Checklist. Use this checklist every time you contribute to a repository you do not own.

      -

      Alex: The practical takeaway is this. [ ] Fork the repository on GitHub. [ ] Clone your fork locally. [ ] Add the upstream remote (git remote add upstream URL). [ ] Create a feature branch (git checkout -b branch-name). [ ] Make your changes, stage, and commit. [ ] Push your branch to your fork (git push -u origin branch-name).

      -

      Jamie: Let's pause on Cleaning up after merge. What should a learner take away from it?

      -

      Alex: The reason Cleaning up after merge matters is that after your PR is merged, delete the feature branch. That gives the learner a simple foothold: GitHub also offers a "Delete branch" button on the merged PR page. The interface gets friendlier when it stops being a wall of controls and starts being a set of named places.

      -

      Alex: Treat examples as spoken recipes, not decorations. You may hear something like Delete the local branch; git checkout main; git branch -d agents/your-username-my-agent; Delete the remote branch on your fork; git push origin --delete agents/your-username-my-agent. Read the command, understand what it changes, then run it only when the repository state matches the lesson.

      -

      Jamie: How should someone ask for help in a way that gets them unstuck faster?

      -

      Alex: Start with 13. If You Get Stuck: Next: Chapter 19: Accessibility Agents Back: Chapter 17: Issue Templates Related appendices: Appendix E: Advanced Git Appendix O: Branch Protection.

      +

      Alex: Keep the teaching thread moving. This is where Reviewing as a Learning Tool becomes real: reviewing is not just a gate to keep bad code out. That matters in practice: It is one of the fastest ways to grow as a developer. The workshop is closer to rehearsal than lecture. You hear the move, try the move, and then check what changed.

      +

      Jamie: Let's pause on Learning Cards: The Reviewer's Craft. What should a learner take away from it?

      +

      Alex: Start with Learning Cards: The Reviewer's Craft. There is something to understand, something to try, and something that proves the try worked.

      +

      Alex: The practical takeaway is this. Jump between changed hunks in a diff with Alt+F5 (next change) and Shift+Alt+F5 (previous change) to scan for scope creep efficiently. Use Alt+F2 (Accessible View) on a Copilot-generated review summary to read the full text with arrow keys before posting. When leaving feedback, mention specific line numbers ("Line 42 skips from h2 to h4") so the author can navigate directly with Ctrl+G. The three review actions (Approve, Request Changes, Comment) are shown as clearly labeled radio buttons in the review submission form. Use the reviewer checklist in this section as a mental framework -- copy it into your notes and check items off as you review each PR. The diff view uses green and red backgrounds for added/removed lines; pair with a High Contrast theme if these colors are hard to distinguish.

      +

      Alex: Keep the teaching thread moving. The reason Day 2 Teaser: The Full Accessibility Agents Review Ecosystem matters is that chapter 16 shows you how to leverage 50+ specialized agents to make your reviews faster, more consistent, and more thorough - while staying in full control of what you post.

      +
      +

      Jamie: What do you want them to do when the plan breaks?

      +

      Alex: Start with The Agents That Help With Code Review: Accessibility Review Agents (when code affects UI/UX).

      +

      Alex: The practical takeaway is this. @pr-review - Generates a full-draft PR review with line-numbered diff maps, risk assessment, before/after snapshots, and suggested inline comments. You edit and post it under your name. @pr-author-checklist - Before you even submit your PR, use this to verify you haven't missed setup steps, accessibility checks, or documentation. @insiders-a11y-tracker - Monitors your PR for accessibility-sensitive changes: WCAG violations, heading hierarchy issues, link text quality, keyboard navigation impacts. @developer-hub - Orchestrates explanations for unfamiliar code, patterns, or frameworks you're reviewing. @python-specialist - If your PR contains Python code, this agent explains patterns, spots accessibility issues, and suggests improvements. @wxpython-specialist - For desktop GUI code, helps verify accessible widget patterns and focus management.

      +

      Jamie: Let's pause on How It Works. What should a learner take away from it?

      +

      Alex: Start with How It Works. There is something to understand, something to try, and something that proves the try worked.

      +

      Alex: First, review manually first (you just did this with Exercises A, B, C). Then, run an agent - @pr-review review PR 14 generates a draft in seconds. After that, edit the agent's draft - you add context, remove noise, correct errors. Finally, post your review - it now has both AI efficiency and your human judgment. Treat it like a recipe: do not add the next ingredient until the previous one is actually in the bowl.

      +

      Jamie: Before we leave How It Works, what is the practical point?

      +

      Alex: First, the agent tracks impact - @insiders-a11y-tracker monitors whether your accessibility feedback was addressed. It is a checklist, but a meaningful one: every item creates evidence that the next step is safe.

      +

      Jamie: Let's pause on The Principle: Skill First, Agent Second. What should a learner take away from it?

      +

      Alex: This is where The Principle: Skill First, Agent Second becomes real: why do this manually before using agents? That matters in practice: Manual reviews teach you what to look for.

      +

      Alex: The practical takeaway is this. You understand what the agent is doing (you did it manually). You evaluate the agent's output critically (you know what right looks like). You add judgment the agent lacks (context, intent, team decisions). You verify the agent didn't miss anything important.

      +
      +

      Jamie: Let's pause on A Real Example: The Flow. What should a learner take away from it?

      +

      Alex: Keep the learner anchored in A Real Example: The Flow. Manual Review (your work in part 1-2). This is the part to say slowly: Agent-Assisted Review (what you'll do in Chapter 19).

      +

      Alex: The practical takeaway is this. Read diff, identify heading hierarchy skip. Write comment explaining why it matters. Submit your verdict.

      +

      Alex: First, run: @pr-review review PR 14. Then, agent generates a draft review covering the heading skip, link text, and 5 other issues. After that, you read the draft and notice: "the agent's explanation of the heading skip is good, but it missed that the link text on line 23 is still vague. Let me add that.". Finally, you post the agent's review + your additions. It is like walking a hallway with named doors: read the sign, enter the right room, then confirm where you landed.

      +

      Jamie: Before we leave A Real Example: The Flow, what is the practical point?

      +

      Alex: First, next time you review a similar PR, the agent works faster because it learned from your feedback. The rhythm is simple: orient, act, verify, then continue.

      Jamie: What should people carry with them after this?

      Alex: Carry the map. Know what page or tool you are in, know which action you are taking, and know what confirmation should follow. If the confirmation is missing, pause. That pause is not wasted time; it is professional judgment.

      Jamie: That is a better way to say it than just follow the steps.

      -

      Alex: Right. Steps matter, but understanding wins. That is episode 47. Next in the series is episode 48, where we keep building the same contributor muscles.

      +

      Alex: Right. Steps matter, but understanding wins. That is episode 13. Next in the series is episode 14, where we keep building the same contributor muscles.

      -

      Episode 48: Build Your Agent: Capstone

      -

      Designing, writing, testing, and contributing a custom accessibility agent.

      -

      Based on: Chapter 20: Build Your Agent: Capstone

      +

      38. Episode 15: Accessible Code Review

      +

      Navigating diffs with a screen reader, reviewing PRs in browser and VS Code.

      +

      Based on: Chapter 15: Accessible Code Review

      Audio and transcript are being regenerated for this episode.

      -Read Transcript - Episode 48: Build Your Agent: Capstone +Read Transcript - Episode 15: Accessible Code Review

      Transcript

      -

      Alex: Welcome to Git Going with GitHub, episode 48: Build Your Agent: Capstone. I am Alex. Today we are going to make Build Your Agent: Capstone something you can explain, practice, and recover from when the interface surprises you.

      -

      Jamie: And I am Jamie. I will be the voice of the learner who is willing to ask, what is this for, where am I, and how do I know I did it right?

      +

      Alex: Welcome to episode 15 of Git Going with GitHub: Accessible Code Review. I am Alex, and today we are teaching this topic as a conversation you can carry into the workshop, not as a page you have to memorize.

      +

      Jamie: And I am Jamie. I will keep pulling the lesson back to real learners, real repositories, and the evidence that proves the work happened.

      -

      Alex: The big idea today: Designing, writing, testing, and contributing a custom accessibility agent. We will name the concept, explain why it matters, practice the move, and point out the checks that tell you the work is real.

      -

      Jamie: So the episode should work even if someone has not read the chapter yet.

      -

      Alex: Exactly. The transcript has to stand on its own. It can point toward practice, but it should teach the concept right here in the conversation.

      +

      Alex: The lesson focus is Navigating diffs with a screen reader, reviewing PRs in browser and VS Code. We will treat every step as a teachable decision, because that is what makes the skill portable.

      +

      Jamie: So we should explain the why clearly enough that the steps make sense when the learner meets them later.

      +

      Alex: That is it. If a listener only has audio right now, they should still get the complete concept and know what evidence would prove success.

      +
      +

      Jamie: Okay, set the room for us. What are we walking into?

      +

      Alex: Start with The GitHub Pull Requests Extension: See also: Appendix G: VS Code Reference for the complete list of GitHub Pull Requests extension keyboard shortcuts.

      +

      Alex: A solid pull request habit is to separate three questions: what changed, why it changed, and what still needs review. That keeps the conversation useful instead of noisy.

      +

      Alex: The next layer is this. Here is the plain-English version of 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,. Put another way, prerequisites: Working with Pull Requests, Git & Source Control in VS Code Mac keyboard shortcuts: Throughout this chapter, all Ctrl+ shortcuts use Cmd+ on Mac, and Alt+ shortcuts use Option+ on Mac. It is like learning a transit route. The names of the stops matter because they tell you whether you are still going the right direction.

      +

      Jamie: What should feel predictable before the first live session starts?

      +

      Alex: This is where Workshop Recommendation (Chapter 15, Part 1) becomes real: chapter 15, Part 1 introduces the GitHub Pull Requests extension for managing PRs directly from VS Code.

      +

      Alex: That shows up in the workshop in a few specific ways. There are 2 guided challenges. Automation check: none (extension installation and review state are account-local). The evidence is issue comment with confirmation of actions completed. The pattern is install, check out, review, comment.

      +

      Jamie: Turn that into a path someone can follow.

      +

      Alex: Start with Chapter 15, Part 1 Practice Set. There is something to understand, something to try, and something that proves the try worked.

      +

      Alex: First, install the GitHub Pull Requests extension - add the extension to VS Code and sign in with your GitHub account. Then, check out a PR and post a review comment - download a PR branch locally, read the diff, and post one constructive review comment. It is like walking a hallway with named doors: read the sign, enter the right room, then confirm where you landed.

      +

      Jamie: What is the ordered workflow?

      +

      Alex: The reason Practice 15.1 Step-by-Step: Install the Extension matters is that install the GitHub Pull Requests and Issues extension and authenticate with your GitHub account. That gives the learner a simple foothold: VS Code desktop with your Learning Room repository open.

      +

      Alex: First, open the Extensions sidebar: Ctrl+Shift+X (Mac: Cmd+Shift+X). Then, your screen reader announces "Extensions: Marketplace." The search box has focus. After that, type GitHub Pull Requests in the search box and press Enter. Finally, navigate down the results list. Select GitHub Pull Requests (publisher: GitHub). The rhythm is simple: orient, act, verify, then continue.

      Jamie: Give me the sequence, because order matters here.

      -

      Alex: Start with 1. The Capstone Challenge: The capstone is Challenge 16 -- the final challenge of the workshop. The next useful detail is this: Your pull request goes to a real repository.

      -

      Alex: First, choose a mission for a new accessibility agent (or improve an existing one). Then, write an agent file with valid YAML frontmatter. After that, define clear responsibilities and guardrails. Finally, test the agent locally with GitHub Copilot. Think of it as a rail line: each stop confirms you are still on the right route before the next one.

      +

      Alex: First, activate the Install button. VS Code installs the extension and may show a notification. Then, after installation, VS Code prompts you to sign in. Activate Sign in to GitHub. After that, a browser window opens for GitHub OAuth. Approve the authorization and return to VS Code. Finally, verify: open the Explorer sidebar (Ctrl+Shift+E). You should now see a GitHub section in the sidebar showing Pull Requests and Issues. Think of it as a rail line: each stop confirms you are still on the right route before the next one.

      Jamie: How would you walk the room through that step by step?

      -

      Alex: First, open a pull request from your fork to the upstream repository. Then, respond to peer review feedback. Treat it like a recipe: do not add the next ingredient until the previous one is actually in the bowl.

      -

      Alex: The next layer is this. Start with What you need before starting. There is something to understand, something to try, and something that proves the try worked.

      -

      Alex: The practical anchors are these. [ ] You have forked and cloned the accessibility-agents repository (Chapter 18). [ ] You have a feature branch created: agents/your-username-agent-name. [ ] You understand how to push to your fork and open a PR (Chapter 18). [ ] You have GitHub Copilot or Copilot Free active (Chapter 16). [ ] You have explored the existing agents in Chapter 19.

      -

      Jamie: What is the one idea that makes the next few steps less mysterious?

      -

      Alex: This is where Time estimate becomes real: most students complete the capstone in 60 to 90 minutes. That matters in practice: The phases are designed so you can get a working agent in 30 minutes and spend the remaining time improving it.

      +

      Alex: Start with Practice 15.2 Step-by-Step: Check Out a PR and Post a Comment: Check out someone else's PR branch locally, read the diff in VS Code, and post one constructive review comment. The next useful detail is this: VS Code with the GitHub Pull Requests extension installed. Think of it like entering a new building: first you find the lobby, then the room, then the door you actually need.

      +

      Alex: First, open the Command Palette: Ctrl+Shift+P (Mac: Cmd+Shift+P). Then, type GitHub Pull Requests: Focus on Pull Requests View and select it. The Pull Requests panel opens. After that, navigate the list of open PRs. Find one that is not yours (a classmate's PR from Chapter 6, 7, or 14). Finally, 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. Think of it as a rail line: each stop confirms you are still on the right route before the next one.

      +

      Jamie: What does the learner do first, second, and then after that?

      +

      Alex: First, open the Command Palette again and run GitHub Pull Requests: Open Changed Files. This shows the list of files the PR changed. Then, open one changed file. VS Code opens the Diff Editor showing old content on the left and new content on the right. After that, 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). Finally, find one specific thing to comment on: a typo, an unclear sentence, a missing step, or something the author did well. Treat it like a recipe: do not add the next ingredient until the previous one is actually in the bowl.

      -

      Alex: Now bring the learner back to the room. Keep the learner anchored in 2. Phase 1: Choose Your Agent's Mission. See also: Chapter 19: Accessibility Agents introduces the agent ecosystem and shows existing agents for inspiration.

      -

      Jamie: What would you say to someone who is already bracing for this to be too much?

      -

      Alex: The reason What makes a good agent mission matters is that a good agent solves a specific, recurring problem.

      -

      Alex: The parts worth keeping in working memory are these. What task do you repeat? Think about workflow steps from Day 1 and Day 2 that felt repetitive. What would a specialist know? An agent works best when it has deep knowledge of a focused area. What gap exists? Look at the existing agents in Chapter 19. Is there a workflow that no agent covers?

      +

      Jamie: What should the learner prove to themselves after each small task?

      +

      Alex: Here is the plain-English version of Completing Chapter 15, Part 1: Submit Your Evidence. Open your assigned setup or review practice issue and post a completion comment. Put another way, close your Chapter 12 challenge issues when done.

      Alex: The useful habit is simple: orient first, act second, verify third. That pause before acting is part of the work.

      -

      Alex: That matters because of the next idea. Start with Write your mission statement: Before writing any code, write a one-sentence mission statement. The next useful detail is this: "My agent helps [who] by [doing what] when [in what situation].". Think of it like entering a new building: first you find the lobby, then the room, then the door you actually need.

      -
      -

      Jamie: Okay, set the room for us. What are we walking into?

      -

      Alex: Here is the plain-English version of 3. Phase 2: Write the Agent File. An agent file is a Markdown file with YAML frontmatter that defines the agent's identity, and a body that contains the agent's instructions. Put another way, agent files live in the.github/agents/ directory (for GitHub Copilot agents) or in team-specific directories in the accessibility-agents repository.

      -

      Alex: This is where the talk moves from concept to action. This is where File location and naming becomes real: example.github/agents/alt-text-validator.md.

      -

      Jamie: Turn that into a path someone can follow.

      -

      Alex: Start with The agent file structure. There is something to understand, something to try, and something that proves the try worked.

      -

      Alex: First, yAML frontmatter -- metadata between --- markers at the top of the file. Then, instructions body -- Markdown content that tells the agent how to behave. It is like walking a hallway with named doors: read the sign, enter the right room, then confirm where you landed.

      +

      Alex: This is where the talk moves from concept to action. Start with Expected Outcomes. There is something to understand, something to try, and something that proves the try worked.

      +

      Alex: The room should hear these as checkpoints. 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.

      +

      Jamie: Let's pause on If You Get Stuck. What should a learner take away from it?

      +

      Alex: Keep the learner anchored in If You Get Stuck. Continue learning: The GitHub Skills course Review Pull Requests practices approving, requesting changes, and using suggestions in an interactive format. This is the part to say slowly: See Appendix Z for the full catalog.

      +

      Alex: First, extension does not install? Reload VS Code: Ctrl+Shift+P, then run Developer: Reload Window. Then, oAuth sign-in fails? Verify your GitHub account is active in the browser first, close VS Code, reopen, and retry. After that, pR list is empty? Switch to "All Open" view in the GitHub Pull Requests panel. Finally, checkout fails? Confirm you have write access to the repository. If not, use the read-only GitHub.com fallback. It is like walking a hallway with named doors: read the sign, enter the right room, then confirm where you landed.

      +

      Jamie: Before we leave If You Get Stuck, what is the practical point?

      +

      Alex: First, diff Editor is hard to navigate? Press F7 for the Accessible Diff Viewer mode, which is purpose-built for screen readers. Then, cannot find the Add Comment command? Use Command Palette and search for GitHub Pull Requests: Add Comment. After that, ask facilitator to help verify the GitHub PR panel and model one review comment. Finally, finished but not sure you did it right? Compare your work against the Challenge 11 reference solution. The rhythm is simple: orient, act, verify, then continue.

      -

      Alex: Before the learner moves on. The reason YAML frontmatter fields matters is that vague descriptions result in missed automatic routing. That gives the learner a simple foothold: weak: Helps with accessibility - Strong: Checks markdown files for accessibility issues, fixes descriptive links and heading hierarchy, and flags alt text for human review The more specific the description, the more reliably Copilot invokes the right agent for. The interface gets friendlier when it stops being a wall of controls and starts being a set of named places.

      -

      Jamie: Give me the version that sounds like an instructor, not a manual.

      -

      Alex: Start with Writing the instructions body: The instructions body tells the agent how to behave. The next useful detail is this: Write it as if you are briefing a new team member on their first day.

      -

      Alex: A few details make that real. Start with identity. "You are a [role] focused on [area].". List responsibilities. What specific tasks does this agent handle? Set guardrails. What should the agent never do? What are its limits? Provide examples. Show what good output looks like.

      -

      Alex: Hold that next to this. Start with Learning Cards: Writing the Agent File. There is something to understand, something to try, and something that proves the try worked.

      -

      Alex: That shows up in the workshop in a few specific ways. Create your agent file with Ctrl+N, then Ctrl+S and save to.github/agents/your-agent-name.md -- the Explorer navigates to the folder automatically. Use Ctrl+Shift+O to navigate between YAML frontmatter fields and Markdown headings (Responsibilities, Guardrails) in your agent file. The YAML frontmatter is between --- markers at the top -- your screen reader announces these as horizontal rules. Agent files are standard Markdown -- open Markdown Preview (Ctrl+Shift+V) side by side to verify formatting as you write. The YAML frontmatter at the top uses name: and description: fields -- keep these on separate lines for readability at high zoom. Use a consistent heading hierarchy ( for title, for sections) so the Outline view (Ctrl+Shift+O) shows a clean structure.

      +

      Alex: Before the learner moves on. The reason Learning Moment matters is that reviewing others' work refines your own standards and builds community trust. That gives the learner a simple foothold: the comment you just wrote helps another student learn - and you learn by articulating what makes documentation clear. The interface gets friendlier when it stops being a wall of controls and starts being a set of named places.

      +

      Jamie: Let's pause on Learning Pattern Used in This Chapter. What should a learner take away from it?

      +

      Alex: Start with Learning Pattern Used in This Chapter. There is something to understand, something to try, and something that proves the try worked.

      +

      Alex: First, install and configure the tool before starting the task. Then, practice on someone else's work first (reviewing is safer than authoring). After that, use accessibility tools (F7 Accessible Diff Viewer) to navigate efficiently. Finally, write specific, constructive feedback (not just "looks good"). Think of it as a rail line: each stop confirms you are still on the right route before the next one.

      +

      Alex: Hold that next to this. Here is the plain-English version of 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.

      -

      Jamie: If I am listening before the workshop starts, what should settle in my mind first?

      -

      Alex: This is where 4. Phase 3: Define Responsibilities and Guardrails becomes real: responsibilities and guardrails are the most important parts of your agent's instructions. That matters in practice: The autograder checks that both sections exist.

      -

      Alex: That connects to another useful point. Keep the learner anchored in Writing responsibilities. Responsibilities define what the agent does. This is the part to say slowly: Each responsibility should describe one discrete action the agent can take. A good GitHub workflow is like a well-run meeting: everyone knows the topic, the next action, and who has the floor.

      -

      Alex: For a learner, the useful signals are these. Scan HTML files for tags missing the alt attribute. Check that all elements have visible text or an aria-label. Verify heading levels do not skip (e.g., h1 to h3 without h2). Help with accessibility.

      -

      Jamie: Where do you want a learner to place their attention here?

      -

      Alex: The reason Writing guardrails matters is that guardrails define what the agent must not do. That gives the learner a simple foothold: they prevent the agent from overstepping, giving harmful advice, or acting without permission.

      -

      Alex: On the ground, that means a few things. Never auto-fix code without asking the user first. Do not provide medical, legal, or financial advice when discussing accessibility compliance. Limit reviews to the files the user specifies -- do not scan the entire repository. If a finding is uncertain, say so explicitly rather than presenting it as definitive.

      +

      Jamie: Let's pause on Method 1: Extensions Sidebar. What should a learner take away from it?

      +

      Alex: Start with Method 1: Extensions Sidebar. There is something to understand, something to try, and something that proves the try worked.

      +

      Alex: First, open Extensions sidebar: Ctrl+Shift+X (Mac: Cmd+Shift+X). Then, type "GitHub Pull Requests" in the search box. After that, find "GitHub Pull Requests and Issues" (publisher: GitHub). Finally, navigate to the extension in the results list. It is a checklist, but a meaningful one: every item creates evidence that the next step is safe.

      +

      Jamie: Before we leave Method 1: Extensions Sidebar, what is the practical point?

      +

      Alex: First, press Enter to open the extension detail page. Then, tab to "Install" button → press Enter. It is like walking a hallway with named doors: read the sign, enter the right room, then confirm where you landed.

      +

      Jamie: Let's pause on Method 2: Command Palette. What should a learner take away from it?

      +

      Alex: Keep the learner anchored in Method 2: Command Palette. The Extensions sidebar is a tree view. This is the part to say slowly: Use Up/Down Arrow to navigate, Enter to open an extension's detail page. A good GitHub workflow is like a well-run meeting: everyone knows the topic, the next action, and who has the floor.

      +

      Alex: First, ctrl+Shift+P. Then, type "install extensions". After that, select "Extensions: Install Extensions". Finally, search for "GitHub Pull Requests". It is like walking a hallway with named doors: read the sign, enter the right room, then confirm where you landed.

      +

      Jamie: Before we leave Method 2: Command Palette, what is the practical point?

      +

      Alex: First, install "GitHub Pull Requests and Issues". The rhythm is simple: orient, act, verify, then continue.

      +

      Jamie: Let's pause on Signing In to GitHub. What should a learner take away from it?

      +

      Alex: The reason Signing In to GitHub matters is that after installation, VS Code prompts you to sign in.

      +

      Alex: First, a notification appears: "Sign in to GitHub to use Pull Requests". Then, navigate to the notification (Alt+N / Mac: Option+N, or status bar navigation). After that, select "Sign in". Finally, VS Code opens your browser for GitHub OAuth authentication. The rhythm is simple: orient, act, verify, then continue.

      +

      Jamie: Before we leave Signing In to GitHub, what is the practical point?

      +

      Alex: First, authorize VS Code in the browser. Then, return to VS Code - you're now signed in. Think of it as a rail line: each stop confirms you are still on the right route before the next one.

      -

      Alex: Here is the practical turn. Start with Learning Cards: Responsibilities and Guardrails. There is something to understand, something to try, and something that proves the try worked.

      -

      Alex: Here is what that changes in practice. Use Responsibilities and Guardrails as exact heading names -- the autograder searches for these strings. Each responsibility should start with a verb (Scan, Check, Verify, Flag) -- this makes them concrete and testable. Guardrails should start with "Never" or "Do not" to set clear boundaries your screen reader identifies as restrictions when reviewing the file. Format responsibilities as a bulleted list (starting with -) for easy scanning at high zoom -- one responsibility per bullet. Keep each guardrail to a single line so it remains visible without horizontal scrolling at your zoom level. Use bold text for emphasis on critical guardrails (e.g., Never modify files without approval ) to improve visual scanning.

      -

      Jamie: Let's pause on 5. Phase 4: Test Your Agent Locally. What should a learner take away from it?

      -

      Alex: Here is the plain-English version of 5. Phase 4: Test Your Agent Locally. See also: Chapter 18: Fork and Contribute covers the fork-and-PR workflow you will use to submit your agent. Put another way, before opening a pull request, test your agent to verify it works.

      -

      Jamie: What does the learner do first, second, and then after that?

      -

      Alex: Start with Testing with GitHub Copilot Chat. There is something to understand, something to try, and something that proves the try worked.

      -

      Alex: The room should hear these as checkpoints. Understand its mission? Follow its responsibilities? Respect its guardrails?

      -

      Alex: First, open VS Code with the accessibility-agents repository. Then, ensure your agent file is saved in.github/agents/. After that, open GitHub Copilot Chat (Ctrl+Shift+I or Cmd+Shift+I). Finally, invoke your agent by name: @your-agent-name check this file for accessibility issues. It is a checklist, but a meaningful one: every item creates evidence that the next step is safe.

      -

      Jamie: What is the ordered workflow?

      -

      Alex: First, observe the response. Does the agent. It is like walking a hallway with named doors: read the sign, enter the right room, then confirm where you landed.

      +

      Alex: Here is the practical turn. Start with Verify sign-in. There is something to understand, something to try, and something that proves the try worked.

      +

      Alex: On the ground, that means a few things. 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.

      +

      Jamie: What would you say to someone who is already bracing for this to be too much?

      +

      Alex: Start with What the Extension Adds. There is something to understand, something to try, and something that proves the try worked.

      +

      Alex: Here is what that changes in practice. 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.

      +

      Alex: Keep the thread going. Start with Learning Cards: Installing the PR Extension. There is something to understand, something to try, and something that proves the try worked.

      +

      Alex: These are the details that keep the idea from floating away. 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". 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.

      -

      Jamie: Let's pause on Testing checklist. What should a learner take away from it?

      -

      Alex: Start with Testing checklist. There is something to understand, something to try, and something that proves the try worked.

      -

      Alex: These are the details that keep the idea from floating away. [ ] The agent responds when invoked by name. [ ] The agent stays within its defined responsibilities. [ ] The agent does not violate any guardrails. [ ] The agent's output is useful and specific. [ ] The agent handles edge cases gracefully (empty files, no issues found).

      -

      Jamie: Let's pause on Iterating on your agent. What should a learner take away from it?

      -

      Alex: The reason Iterating on your agent matters is that if the agent does not behave as expected. That gives the learner a simple foothold: most students iterate 2-3 times before they are satisfied.

      -

      Alex: First, read its instructions carefully. Is anything ambiguous? Then, add more specific instructions or examples. After that, test again with the same prompt. Finally, repeat until the behavior matches your intent. The rhythm is simple: orient, act, verify, then continue.

      -

      Jamie: Let's pause on Learning Cards: Testing Your Agent. What should a learner take away from it?

      -

      Alex: Start with Learning Cards: Testing Your Agent. There is something to understand, something to try, and something that proves the try worked.

      -

      Alex: That becomes easier when you listen for these cues. Open Copilot Chat (Ctrl+Shift+I) and type @your-agent-name followed by a test prompt -- your screen reader announces the response as it streams. Press Alt+F2 after the response finishes to read the full output in Accessible View with arrow keys. If the agent does not respond as expected, edit the.agent.md file and ask again -- Copilot picks up changes immediately. Agent responses appear in the Copilot Chat panel -- widen the panel by dragging its left edge for better readability. Test with a simple prompt first (e.g., "review this file") and read the full response before trying complex requests. Use Accessible View (Alt+F2) to read responses at your preferred editor font size instead of the Chat panel's default.

      +

      Jamie: Let's pause on Method 1: Activity Bar. What should a learner take away from it?

      +

      Alex: Keep the learner anchored in Method 1: Activity Bar. Click the GitHub logo icon in the Activity Bar (the vertical strip of icons on the far left). This is the part to say slowly: The GitHub Pull Requests panel opens.

      +

      Alex: That becomes easier when you listen for these cues. "Pull Requests". "Issues".

      +

      Alex: First, the Activity Bar is not always reachable by Tab from the editor. Then, use Ctrl+Shift+P (Mac: Cmd+Shift+P) → type "GitHub Pull Requests: View Pull Request" or "Focus on Pull Requests View" → press Enter. After that, alternatively press Ctrl+Shift+G (Mac: Cmd+Shift+G) to open Source Control, then Tab until you reach the Activity Bar icon strip. Finally, navigate to the repository on GitHub.com. It is like walking a hallway with named doors: read the sign, enter the right room, then confirm where you landed.

      +

      Jamie: Before we leave Method 1: Activity Bar, what is the practical point?

      +

      Alex: First, click the Pull requests tab. Then, click any PR title to view its conversation, commits, and changed files. After that, use the Files changed tab to review diffs. The rhythm is simple: orient, act, verify, then continue.

      +

      Alex: Treat examples as spoken recipes, not decorations. You may hear something like 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". Read the command, understand what it changes, then run it only when the repository state matches the lesson.

      +

      Jamie: Let's pause on Method 2: Explorer Section. What should a learner take away from it?

      +

      Alex: Start with Method 2: Explorer Section. There is something to understand, something to try, and something that proves the try worked.

      +

      Alex: First, open Explorer: Ctrl+Shift+E (Mac: Cmd+Shift+E). Then, navigate with Arrow keys to find the "GitHub Pull Requests" section. After that, expand it with Right Arrow. The rhythm is simple: orient, act, verify, then continue.

      +

      Jamie: What is the one idea that makes the next few steps less mysterious?

      +

      Alex: Start with Description: The GitHub Pull Requests panel has two top-level sections. The next useful detail is this: "My Pull Requests" contains four filters: Assigned to Me, Created by Me, Waiting for my Review, and All Open.

      -

      Jamie: Let's pause on Tool Cards: Open Your Capstone PR. What should a learner take away from it?

      -

      Alex: Here is the plain-English version of Tool Cards: Open Your Capstone PR. VS Code Desktop (primary for Day 2). It is like learning a transit route. The names of the stops matter because they tell you whether you are still going the right direction.

      -

      Alex: First, push your branch: Ctrl+Shift+P Git: Push. Then, ctrl+Shift+P GitHub Pull Requests: Create Pull Request. After that, set base repo to Community-Access/accessibility-agents, fill in the title and description. Finally, navigate to your fork on GitHub. Treat it like a recipe: do not add the next ingredient until the previous one is actually in the bowl.

      -

      Jamie: Before we leave Tool Cards: Open Your Capstone PR, what is the practical point?

      -

      Alex: First, click Contribute Open pull request. Then, verify the base is Community-Access/accessibility-agents:main and the compare is your branch. It is a checklist, but a meaningful one: every item creates evidence that the next step is safe.

      -

      Alex: Treat examples as spoken recipes, not decorations. You may hear something like git push -u origin your-branch; gh pr create --repo Community-Access/accessibility-agents. Read the command, understand what it changes, then run it only when the repository state matches the lesson.

      -

      Alex: A solid pull request habit is to separate three questions: what changed, why it changed, and what still needs review. That keeps the conversation useful instead of noisy.

      -

      Jamie: Let's pause on Pre-PR checklist. What should a learner take away from it?

      -

      Alex: Start with Pre-PR checklist. There is something to understand, something to try, and something that proves the try worked.

      -

      Alex: The practical takeaway is this. [ ] Your agent file has valid YAML frontmatter (name and description fields). [ ] Your agent file has a Responsibilities section. [ ] Your agent file has a Guardrails section. [ ] The file is in the correct directory. [ ] You have committed and pushed to your fork.

      -

      Jamie: Let's pause on Open the PR. What should a learner take away from it?

      -

      Alex: Keep the learner anchored in Open the PR. Follow the pull request steps from Chapter 18, Step 7.

      -

      Alex: The practical takeaway is this. Your mission statement from Phase 1. What the agent does (summary of responsibilities). Any design decisions you made. How you tested it.

      -

      Alex: First, push your branch: git push -u origin agents/your-username-agent-name. Then, go to the upstream repository on GitHub.com. After that, click the banner or go to Pull Requests and click New pull request, then compare across forks. Finally, select your fork and branch. It is like walking a hallway with named doors: read the sign, enter the right room, then confirm where you landed.

      -

      Jamie: Before we leave Open the PR, what is the practical point?

      -

      Alex: First, write a PR title: "Add [agent-name] accessibility agent". Then, in the PR body,. After that, create the pull request. The rhythm is simple: orient, act, verify, then continue.

      +

      Alex: This is the part worth saying out loud. Here is the plain-English version of Screen reader announcement example. "Pull Request 42: Add Timeline Guide, opened by jeffb, 2 days ago, 3 files changed". It is like learning a transit route. The names of the stops matter because they tell you whether you are still going the right direction.

      +

      Alex: A solid navigation habit is to prove where you are before activating controls. Headings, landmarks, and the address bar are not trivia; they are your map.

      +

      Jamie: Give me the version that sounds like an instructor, not a manual.

      +

      Alex: Start with By status. There is something to understand, something to try, and something that proves the try worked.

      +

      Alex: For a learner, the useful signals are these. "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.

      +

      Alex: That connects to another useful point. Keep the learner anchored in By repository. The tree organizes PRs by repository.

      -

      Jamie: Let's pause on The autograder. What should a learner take away from it?

      -

      Alex: The reason The autograder matters is that the repository has an autograding workflow that runs on every pull request. That gives the learner a simple foothold: the autograder posts results as a comment on your PR.

      -

      Alex: Keep the thread going. Start with Learning Cards: Opening Your Pull Request. There is something to understand, something to try, and something that proves the try worked.

      -

      Alex: The practical takeaway is this. The autograder comment appears in the PR timeline -- navigate to Comments on GitHub.com with h (heading navigation) to find the results. Each autograder check is listed with a pass/fail status and point value -- listen for "10/10" or "0/15" to identify which checks need attention. If a check fails, read the failure message, fix the issue locally, commit, push, and the autograder re-runs automatically. The autograder results appear as a comment with a table showing checks, points, and pass/fail status -- zoom with Ctrl+= to read the details. Green checkmarks indicate passing checks; red X marks indicate failures -- pair with High Contrast theme for clearest visibility. Your PR description should include your mission statement, responsibilities summary, and testing notes.

      -

      Jamie: Let's pause on 7. Phase 6: Respond to Review. What should a learner take away from it?

      -

      Alex: Here is the plain-English version of 7. Phase 6: Respond to Review. After the autograder passes, a peer reviewer (your buddy or another student) and a facilitator will review your agent.

      +

      Jamie: Let's pause on Viewing PR Details. What should a learner take away from it?

      +

      Alex: The reason Viewing PR Details matters is that a PR detail view opens in the editor area showing.

      +

      Alex: The parts worth keeping in working memory are these. 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).

      +

      Alex: First, navigate to a PR in the tree. Then, press Enter. The rhythm is simple: orient, act, verify, then continue.

      +

      Alex: Now bring the learner back to the room. Start with Screen reader experience. There is something to understand, something to try, and something that proves the try worked.

      +

      Alex: A few details make that real. 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.

      +

      Jamie: Where do you want a learner to place their attention here?

      +

      Alex: Here is the plain-English version of 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.

      -

      Alex: Another way to ground it. Start with What reviewers look for. There is something to understand, something to try, and something that proves the try worked.

      -

      Alex: The practical takeaway is this. Clarity: Are the instructions easy to understand? Specificity: Are responsibilities concrete and actionable? Safety: Are guardrails sufficient to prevent harmful behavior? Usefulness: Would this agent actually help someone? Scope: Does the agent try to do too much or too little?

      -

      Jamie: Let's pause on Responding to feedback. What should a learner take away from it?

      -

      Alex: Keep the learner anchored in Responding to feedback. This is the same process from Chapter 18, Step 8.

      -

      Alex: First, read each review comment. Then, make changes locally. After that, commit and push. The PR updates automatically. Finally, reply to each comment explaining your changes. It is like walking a hallway with named doors: read the sign, enter the right room, then confirm where you landed.

      -

      Alex: This is the part worth saying out loud. The reason When your PR is merged matters is that your agent is now part of the accessibility-agents ecosystem. That gives the learner a simple foothold: it is available to anyone who uses the repository. The interface gets friendlier when it stops being a wall of controls and starts being a set of named places.

      -

      Alex: The practical takeaway is this. You can navigate the fork workflow end to end. You can write clear, structured technical documentation. You understand accessibility concepts well enough to teach an AI agent about them. You can respond constructively to code review.

      +

      Alex: That matters because of the next idea. Start with Why Check Out a PR. There is something to understand, something to try, and something that proves the try worked.

      +

      Alex: The practical anchors are these. 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.

      +

      Jamie: Let's pause on Method 1: From the PR Detail View. What should a learner take away from it?

      +

      Alex: Start with Method 1: From the PR Detail View. There is something to understand, something to try, and something that proves the try worked.

      +

      Alex: The practical takeaway is this. Downloads the branch. Switches your local repository to that branch. Opens the changed files in the editor.

      +

      Alex: First, open a PR (see Section 2). Then, in the PR detail view, navigate to "Checkout" button. After that, press Enter. It is like walking a hallway with named doors: read the sign, enter the right room, then confirm where you landed.

      +

      Jamie: Let's pause on Method 2: From the PR Tree. What should a learner take away from it?

      +

      Alex: Start with Method 2: From the PR Tree. There is something to understand, something to try, and something that proves the try worked.

      +

      Alex: First, navigate to the PR in the GitHub Pull Requests tree. Then, press Shift+F10 (Mac: Ctrl+Return) to open context menu. After that, select "Checkout Pull Request". The rhythm is simple: orient, act, verify, then continue.

      -

      Jamie: Let's pause on 8. Capstone Rubric. What should a learner take away from it?

      -

      Alex: Start with 8. Capstone Rubric: The capstone is worth 60 autograded points plus peer review.

      -

      Alex: Keep the teaching thread moving. Here is the plain-English version of What "meets expectations" looks like. A capstone that meets expectations has.

      -

      Alex: The practical takeaway is this. A focused mission (not "help with accessibility" -- something specific). At least 3 concrete responsibilities. At least 3 meaningful guardrails. A PR description that explains the agent's purpose. All autograder checks passing.

      -

      Jamie: Let's pause on What "exceeds expectations" looks like. What should a learner take away from it?

      -

      Alex: This is where What "exceeds expectations" looks like becomes real: a capstone that exceeds expectations also has.

      -

      Alex: The practical takeaway is this. Examples of expected input and output in the agent instructions. A section describing the agent's limitations. Evidence of testing (screenshots or transcripts in the PR description). Thoughtful responses to review feedback.

      +

      Jamie: Let's pause on Method 3: Command Palette. What should a learner take away from it?

      +

      Alex: Start with Method 3: Command Palette: After checkout, the bottom-left status bar shows the branch name (example: "jeffb/add-timeline-guide"). The next useful detail is this: Your local files now match that branch.

      +

      Alex: First, ctrl+Shift+P (Mac: Cmd+Shift+P). Then, type "GitHub Pull Requests: Checkout". After that, select "GitHub Pull Requests: Checkout Pull Request". Finally, choose the PR from the list. Think of it as a rail line: each stop confirms you are still on the right route before the next one.

      +

      Jamie: Let's pause on Returning to Your Original Branch. What should a learner take away from it?

      +

      Alex: Start with Returning to Your Original Branch. There is something to understand, something to try, and something that proves the try worked.

      +

      Alex: First, ctrl+Shift+P (Mac: Cmd+Shift+P). Then, type "git checkout". After that, select "Git: Checkout to.". Finally, choose your original branch (usually main or your feature branch). Treat it like a recipe: do not add the next ingredient until the previous one is actually in the bowl.

      +

      Alex: A solid Git habit is to know which branch you are on, what changed, and what confirmation you expect before you run the next command.

      +

      Jamie: If I am listening before the workshop starts, what should settle in my mind first?

      +

      Alex: Start with Learning Cards: Checking Out a PR. There is something to understand, something to try, and something that proves the try worked.

      +

      Alex: The practical takeaway is this. 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. 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.

      -

      Alex: Keep the teaching thread moving. Keep the learner anchored in 9. Example Agents for Inspiration. These examples show the range of valid agent designs. This is the part to say slowly: Your agent does not need to be this long, but it should be this clear. A good GitHub workflow is like a well-run meeting: everyone knows the topic, the next action, and who has the floor.

      -

      Jamie: Let's pause on Example 1: Heading Hierarchy Checker. What should a learner take away from it?

      -

      Alex: The reason Example 1: Heading Hierarchy Checker matters is that mission: Validates that HTML and Markdown documents follow a correct heading hierarchy (no skipped levels).

      -

      Alex: The practical takeaway is this. Scan files for heading elements (h1 through h6 in HTML, through in Markdown). Report any instance where a heading level is skipped (e.g., h2 followed by h4). Suggest the correct heading level for each violation. Check that there is exactly one h1 per page. Do not modify files -- only report findings. Do not change heading text, only heading levels.

      -

      Alex: A solid navigation habit is to prove where you are before activating controls. Headings, landmarks, and the address bar are not trivia; they are your map.

      -

      Alex: Keep the teaching thread moving. Start with Example 2: PR Description Quality Gate: Mission: Reviews pull request descriptions to ensure they contain enough context for reviewers.

      -

      Alex: The practical takeaway is this. Check that the PR description is at least 50 characters. Verify the description references an issue with Closes XX or Fixes XX. Check for a summary of changes made. Verify the description explains why the change was made, not just what was changed. Never approve or block a PR based solely on description quality. Do not rewrite the description for the author -- suggest improvements.

      +

      Alex: Another way to ground it. Keep the learner anchored in 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. A good GitHub workflow is like a well-run meeting: everyone knows the topic, the next action, and who has the floor.

      +

      Jamie: Let's pause on In the PR detail view. What should a learner take away from it?

      +

      Alex: Start with In the PR detail view. There is something to understand, something to try, and something that proves the try worked.

      +

      Alex: First, scroll down to "Files Changed" section. Then, each file is a link. After that, navigate with Arrow keys. Finally, press Enter on a file to open its diff view. The rhythm is simple: orient, act, verify, then continue.

      +

      Alex: Keep the teaching thread moving. Start with Screen reader announcement: "docs/11-vscode-interface.md, 42 additions, 3 deletions".

      -

      Jamie: Let's pause on Example 3: Keyboard Navigation Auditor. What should a learner take away from it?

      -

      Alex: Here is the plain-English version of Example 3: Keyboard Navigation Auditor. Mission: Checks web components for keyboard accessibility compliance.

      -

      Alex: The practical takeaway is this. Verify all interactive elements are reachable via Tab key. Check that custom components have appropriate tabindex values. Validate that focus order follows visual layout. Detect keyboard traps (elements that receive focus but cannot release it via keyboard). Do not modify component code without user approval. Flag potential issues with confidence levels (certain, likely, possible).

      -

      Alex: Keep the teaching thread moving. This is where The universal safety net becomes real: if everything else fails, post this on your challenge issue. That matters in practice: I attempted Challenge 16 and here is what happened: What I tried: [specific actions] What I expected: [what should have happened] What actually happened: [error or unexpected result] What I learned: [even from failure, what do I understand now?]. The workshop is closer to rehearsal than lecture. You hear the move, try the move, and then check what changed.

      +

      Jamie: Let's pause on Understanding the Diff View. What should a learner take away from it?

      +

      Alex: Here is the plain-English version of Understanding the Diff View. When you open a file from "Files Changed".

      +

      Alex: Keep the teaching thread moving. Start with Split view mode (default). There is something to understand, something to try, and something that proves the try worked.

      +

      Alex: The practical takeaway is this. Left side: original file (before changes). Right side: modified file (after changes). Changed lines highlighted (added = green, removed = red).

      +

      Jamie: Let's pause on Inline view mode. What should a learner take away from it?

      +

      Alex: Start with Inline view mode. There is something to understand, something to try, and something that proves the try worked.

      +

      Alex: The practical takeaway is this. Single editor. Removed lines shown with - prefix. Added lines shown with + prefix.

      -

      Jamie: What should people carry with them after this?

      -

      Alex: Carry the map. Know what page or tool you are in, know which action you are taking, and know what confirmation should follow. If the confirmation is missing, pause. That pause is not wasted time; it is professional judgment.

      -

      Jamie: That is a better way to say it than just follow the steps.

      -

      Alex: Right. Steps matter, but understanding wins. That is episode 48. Next in the series is episode 49, where we keep building the same contributor muscles.

      -
      - +

      Alex: Keep the teaching thread moving. Start with To toggle between views. There is something to understand, something to try, and something that proves the try worked.

      +

      Alex: The practical takeaway is this. Command Palette: Ctrl+Shift+P (Mac: Cmd+Shift+P) → "Diff: Toggle Inline View".

      +

      Jamie: Let's pause on Recommended workflow for screen reader users. What should a learner take away from it?

      +

      Alex: Start with Recommended workflow for screen reader users. There is something to understand, something to try, and something that proves the try worked.

      +

      Alex: The practical takeaway is this. Unchanged lines (for context). Removed lines (prefixed with -). Added lines (prefixed with +).

      +

      Alex: First, open a changed file from the PR detail view. Then, press F7 to jump to the first diff hunk. After that, press Alt+F2 (Mac: Option+F2) to open Accessible View. Finally, read the hunk content. Think of it as a rail line: each stop confirms you are still on the right route before the next one.

      +

      Jamie: Before we leave Recommended workflow for screen reader users, what is the practical point?

      +

      Alex: First, press Escape to close Accessible View. Then, press F7 to jump to the next hunk. After that, repeat until all hunks reviewed. Treat it like a recipe: do not add the next ingredient until the previous one is actually in the bowl.

      +

      Alex: Keep the teaching thread moving. Here is the plain-English version of 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. Put another way, previously, deleted code could only be read, not selected. It is like learning a transit route. The names of the stops matter because they tell you whether you are still going the right direction.

      -

      Episode 49: What Comes Next

      -

      How to continue learning, contributing, and building confidence after the workshop.

      -

      Based on: Chapter 21: What Comes Next

      -

      Audio and transcript are being regenerated for this episode.

      -
      -Read Transcript - Episode 49: What Comes Next - -

      Transcript

      -

      Alex: Welcome back to Git Going with GitHub. This is episode 49: What Comes Next. I am Alex, and today we are turning What Comes Next from a list of instructions into a working mental model.

      -

      Jamie: And I am Jamie. I will stop us whenever the instructions sound simple on paper but might feel different with a keyboard and screen reader.

      +

      Jamie: Let's pause on Flagging Issues During Review. What should a learner take away from it?

      +

      Alex: This is where Flagging Issues During Review becomes real: start Review saves your comments as a draft until you submit the full review (see Section 7).

      +

      Alex: First, navigate to the specific line in the diff. Then, press Shift+F10 (Mac: Ctrl+Return) for context menu. After that, select "Add Comment". Finally, type your comment in the input that appears. It is a checklist, but a meaningful one: every item creates evidence that the next step is safe.

      +

      Jamie: Before we leave Flagging Issues During Review, what is the practical point?

      +

      Alex: First, choose "Single Comment" or "Start Review". It is like walking a hallway with named doors: read the sign, enter the right room, then confirm where you landed.

      +

      Alex: A solid issue habit is to read the title, the body, and the timeline before acting. You are listening for the requested action, the missing evidence, and the person who needs a response.

      +

      Alex: Keep the teaching thread moving. Start with Learning Cards: Reviewing Pull Requests in VS Code. There is something to understand, something to try, and something that proves the try worked.

      +

      Alex: The practical takeaway is this. 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. 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.

      +

      Jamie: Let's pause on Tool Cards: Create a Pull Request (from your editor). What should a learner take away from it?

      +

      Alex: The reason Tool Cards: Create a Pull Request (from your editor) matters is that VS Code Desktop (primary for Day 2). That gives the learner a simple foothold: after you've pushed commits to a feature branch, you can create a PR without leaving VS Code.

      +

      Alex: First, ctrl+Shift+P GitHub Pull Requests: Create Pull Request. Then, fill in the title, description, and base branch. After that, click Create. Finally, push your branch, then click the Compare & pull request banner on the repo page. The rhythm is simple: orient, act, verify, then continue.

      +

      Jamie: Before we leave Tool Cards: Create a Pull Request (from your editor), what is the practical point?

      +

      Alex: First, fill in the form and click Create pull request. Then, after pushing, click Create Pull Request -- this opens gitub.com with the form pre-filled. Think of it as a rail line: each stop confirms you are still on the right route before the next one.

      +

      Alex: Treat examples as spoken recipes, not decorations. You may hear something like git push -u origin your-branch; gh pr create --title "Title" --body "Description". Read the command, understand what it changes, then run it only when the repository state matches the lesson.

      -

      Alex: How to continue learning, contributing, and building confidence after the workshop. That is the surface description. Underneath it, we are building judgment: where to focus, what to ignore, and how to verify the result.

      -

      Jamie: So we are not using the audio as a shortcut around learning. We are using it to make the learning easier to enter.

      -

      Alex: Yes. A good audio lesson gives someone enough context to try the work with confidence, even before they open the written material.

      +

      Jamie: Let's pause on Prerequisites. What should a learner take away from it?

      +

      Alex: Start with Prerequisites. There is something to understand, something to try, and something that proves the try worked.

      +

      Alex: First, you've created a branch (see Git & Source Control: Branch Management). Then, you've made commits. After that, you've pushed the branch to GitHub (Ctrl+Shift+P / Mac: Cmd+Shift+P → "Git: Push"). Think of it as a rail line: each stop confirms you are still on the right route before the next one.

      +

      Jamie: Let's pause on Method 1: Command Palette (Recommended). What should a learner take away from it?

      +

      Alex: Start with Method 1: Command Palette (Recommended). There is something to understand, something to try, and something that proves the try worked.

      +

      Alex: First, ctrl+Shift+P (Mac: Cmd+Shift+P). Then, type "GitHub Pull Requests: Create". After that, select "GitHub Pull Requests: Create Pull Request". Finally, a form opens in the editor. Treat it like a recipe: do not add the next ingredient until the previous one is actually in the bowl.

      +

      Jamie: Let's pause on Method 2: Source Control Panel. What should a learner take away from it?

      +

      Alex: Start with Method 2: Source Control Panel. There is something to understand, something to try, and something that proves the try worked.

      +

      Alex: First, open Source Control: Ctrl+Shift+G (Mac: Cmd+Shift+G). Then, after pushing, a "Create Pull Request" button appears. After that, press Enter on that button. It is a checklist, but a meaningful one: every item creates evidence that the next step is safe.

      -

      Jamie: Okay, set the room for us. What are we walking into?

      -

      Alex: Start with 1. What You Built in Two Days: Take a moment to appreciate what you accomplished. The next useful detail is this: This is not a list of what you were taught -- it is a list of what you did.

      -

      Alex: The next layer is this. Start with Day 1: You Can Navigate This. There is something to understand, something to try, and something that proves the try worked.

      -

      Alex: The practical anchors are these. Created and configured a GitHub account with accessibility settings. Navigated repositories, files, and folders using your screen reader, keyboard, or preferred tools. Filed issues with descriptive titles, labels, and context. Created branches, edited files, and opened pull requests. Responded to bot feedback and passed automated checks. Resolved a merge conflict.

      -

      Jamie: What should feel predictable before the first live session starts?

      -

      Alex: Start with Day 2: You Can Build This. There is something to understand, something to try, and something that proves the try worked.

      -

      Alex: That shows up in the workshop in a few specific ways. Installed and configured VS Code with accessibility settings. Cloned a repository and worked with Git locally. Understood the mental model: working directory, staging area, repository. Created branches, staged changes, committed, and pushed from the command line. Explored GitHub Copilot: code suggestions, chat, and code review. Created an issue template.

      +

      Jamie: Let's pause on Method 3: GitHub Panel. What should a learner take away from it?

      +

      Alex: Start with Method 3: GitHub Panel. There is something to understand, something to try, and something that proves the try worked.

      +

      Alex: First, open GitHub view (Activity Bar → GitHub icon). Then, right-click your branch in the tree. After that, select "Create Pull Request". It is like walking a hallway with named doors: read the sign, enter the right room, then confirm where you landed.

      +

      Alex: Keep the teaching thread moving. Start with Title (required). There is something to understand, something to try, and something that proves the try worked.

      +

      Alex: The practical takeaway is this. Auto-filled with your most recent commit message. Edit to make it descriptive (example: "Add Timeline View documentation").

      +

      Jamie: Let's pause on Description (optional but recommended). What should a learner take away from it?

      +

      Alex: Start with Description (optional but recommended). There is something to understand, something to try, and something that proves the try worked.

      +

      Alex: The practical takeaway is this. 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.

      -

      Alex: Now bring the learner back to the room. Keep the learner anchored in The evidence. Your GitHub profile now contains real activity: issues filed, pull requests merged, code reviewed, and an agent contributed to an open source project.

      -

      Jamie: What would you say to someone who is already bracing for this to be too much?

      -

      Alex: The reason 2. Your New Skills Inventory matters is that the following table maps what you learned to where it applies beyond this workshop. That gives the learner a simple foothold: every skill transfers directly to real-world development.

      -

      Alex: The useful habit is simple: orient first, act second, verify third. That pause before acting is part of the work.

      -

      Alex: That matters because of the next idea. Start with Skills you may not have noticed. There is something to understand, something to try, and something that proves the try worked.

      -

      Alex: On the ground, that means a few things. Reading documentation: You navigated technical guides, followed step-by-step instructions, and troubleshot problems using written references. This is the most important developer skill. Asking for help effectively: You posted on issues with context, error messages, and what you tried. This is how experienced developers communicate. Learning tools by doing: You did not read a manual cover to cover. You tried things, hit problems, and figured them out. This is how real tool learning works.

      +

      Alex: Keep the teaching thread moving. Start with Base branch (target). There is something to understand, something to try, and something that proves the try worked.

      +

      Alex: The practical takeaway is this. Usually main or develop. This is the branch your changes will merge into.

      +

      Jamie: Let's pause on Compare branch (source). What should a learner take away from it?

      +

      Alex: Start with Compare branch (source). There is something to understand, something to try, and something that proves the try worked.

      +

      Alex: The practical takeaway is this. Your feature branch (auto-selected). This is the branch with your changes.

      +

      Alex: Keep the teaching thread moving. Start with Reviewers (optional). There is something to understand, something to try, and something that proves the try worked.

      +

      Alex: The practical takeaway is this. Select people to review your PR. Navigate the list with Arrow keys.

      -

      Jamie: If I am listening before the workshop starts, what should settle in my mind first?

      -

      Alex: Here is the plain-English version of 3. Building Your Developer Portfolio. See also: Appendix X: Resources has links to every tool and resource mentioned in this course. Put another way, your GitHub profile is your portfolio.

      -

      Jamie: What does the learner do first, second, and then after that?

      -

      Alex: Start with Pin your best repositories. There is something to understand, something to try, and something that proves the try worked.

      -

      Alex: The room should hear these as checkpoints. Your fork of the accessibility-agents repository (shows open source contribution). Any personal projects you create after the workshop.

      -

      Alex: First, go to github.com/settings/profile. Then, scroll to "Pinned repositories.". After that, pin the repositories that show your best work. Consider. It is a checklist, but a meaningful one: every item creates evidence that the next step is safe.

      -

      Jamie: What is the one idea that makes the next few steps less mysterious?

      -

      Alex: Keep the learner anchored in Write a profile README. Your profile README is the first thing people see when they visit your GitHub profile. This is the part to say slowly: Create a repository with the same name as your username (e.g., your-username/your-username) and add a README.md.

      -

      Alex: A solid pull request habit is to separate three questions: what changed, why it changed, and what still needs review. That keeps the conversation useful instead of noisy.

      +

      Jamie: Let's pause on Labels (optional). What should a learner take away from it?

      +

      Alex: Start with Labels (optional). There is something to understand, something to try, and something that proves the try worked.

      +

      Alex: The practical takeaway is this. Add labels like documentation, accessibility, good-first-issue.

      +

      Alex: Keep the teaching thread moving. Start with Milestone (optional). There is something to understand, something to try, and something that proves the try worked.

      +

      Alex: The practical takeaway is this. Link the PR to a project milestone.

      +

      Jamie: Let's pause on Draft PR checkbox. What should a learner take away from it?

      +

      Alex: Start with Draft PR checkbox. There is something to understand, something to try, and something that proves the try worked.

      +

      Alex: The practical takeaway is this. Check this if the PR is not ready for review yet. Unchecked = "Ready for review".

      -

      Alex: Before the learner moves on. The reason Keep your contribution graph active matters is that the green squares on your GitHub profile show when you made contributions. That gives the learner a simple foothold: even small actions count: filing issues, opening PRs, making commits, and reviewing code. The interface gets friendlier when it stops being a wall of controls and starts being a set of named places.

      -

      Jamie: Give me the version that sounds like an instructor, not a manual.

      -

      Alex: Start with Learning Cards: Building Your Developer Portfolio. There is something to understand, something to try, and something that proves the try worked.

      -

      Alex: A few details make that real. Navigate to your profile settings at github.com/settings/profile -- the "Pinned repositories" section is a group of checkboxes; Tab through and press Space to pin or unpin. Your profile README repository must match your username exactly (case-sensitive) -- screen readers will read the rendered README as regular page content when visitors navigate your profile. The contribution graph is announced as a table or grid; arrow keys move between day cells, each announcing the date and contribution count. Pinned repositories appear as cards below your avatar -- at high zoom the 2x3 grid may reflow to a single column, which is easier to scan. The profile README renders with your current GitHub theme -- test yours in both light and dark modes to confirm text and images remain readable. Contribution graph squares use green intensity to show activity levels; enable high-contrast mode if the shading differences are hard to distinguish.

      -

      Alex: Hold that next to this. Here is the plain-English version of 4. Continued Learning Roadmap. See also: Appendix Z: GitHub Skills has the complete catalog of recommended GitHub Skills courses. Put another way, the workshop taught you the fundamentals.

      +

      Alex: Keep the teaching thread moving. Start with Screen reader navigation. There is something to understand, something to try, and something that proves the try worked.

      +

      Alex: The practical takeaway is this. All fields are standard form inputs. Tab to move between fields. Use Arrow keys in dropdowns (reviewers, labels, milestones).

      +

      Jamie: Let's pause on Submitting the PR. What should a learner take away from it?

      +

      Alex: Keep the learner anchored in Submitting the PR. VS Code creates the PR on GitHub and shows a success message. This is the part to say slowly: The PR link appears in the notification - click it to open the PR on GitHub, or open it in the GitHub Pull Requests panel.

      +

      Alex: First, review all fields. Then, tab to "Create" button. After that, press Enter. Finally, navigate to the repository on GitHub. It is like walking a hallway with named doors: read the sign, enter the right room, then confirm where you landed.

      +

      Jamie: Before we leave Submitting the PR, what is the practical point?

      +

      Alex: First, if you recently pushed, a yellow banner "Compare & pull request" appears - click it. Then, otherwise: click Pull requests tab, then New pull request, then select your branch. After that, fill in the title and description. Finally, click Create pull request. The rhythm is simple: orient, act, verify, then continue.

      +

      Alex: Treat examples as spoken recipes, not decorations. You may hear something like 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. Read the command, understand what it changes, then run it only when the repository state matches the lesson.

      +

      Alex: Keep the teaching thread moving. Start with Learning Cards: Creating a Pull Request. There is something to understand, something to try, and something that proves the try worked.

      +

      Alex: The practical takeaway is this. 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. 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.

      -

      Jamie: Where do you want a learner to place their attention here?

      -

      Alex: Start with Git and version control. There is something to understand, something to try, and something that proves the try worked.

      -

      Alex: For a learner, the useful signals are these. Pro Git book -- Free, comprehensive, and the official Git resource. Start with chapters 2 and 3. Appendix E: Advanced Git -- Rebasing, cherry-picking, stashing, and other techniques you will need eventually.

      -

      Alex: A solid Git habit is to know which branch you are on, what changed, and what confirmation you expect before you run the next command.

      -

      Alex: That connects to another useful point. Start with GitHub platform. There is something to understand, something to try, and something that proves the try worked.

      -

      Alex: The parts worth keeping in working memory are these. GitHub Docs -- The official documentation covers everything. Bookmark it. GitHub Skills -- Free, interactive courses that teach by doing (see Section 5 below). GitHub Blog -- Stay current with new features and best practices.

      -

      Jamie: What stays the same when the tool changes?

      -

      Alex: Start with VS Code. There is something to understand, something to try, and something that proves the try worked.

      -

      Alex: Here is what that changes in practice. VS Code documentation -- Complete reference for settings, keybindings, and extensions. VS Code accessibility documentation -- Deep dive into screen reader support, high contrast, and keyboard navigation.

      +

      Jamie: Let's pause on 6. Pull Request Description Templates. What should a learner take away from it?

      +

      Alex: Start with 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.

      +

      Alex: Keep the teaching thread moving. Here is the plain-English version of Where Templates Are Stored. When you create a PR in VS Code, the extension automatically loads the template into the description field. It is like learning a transit route. The names of the stops matter because they tell you whether you are still going the right direction.

      +

      Alex: The practical takeaway is this.github/pull request template.md (root).github/PULL REQUEST TEMPLATE.md.github/PULL REQUEST TEMPLATE/ (folder with multiple templates). docs/pull request template.md.

      +

      Jamie: What is the safe way to learn from that example?

      +

      Alex: Start with Example PR Template. There is something to understand, something to try, and something that proves the try worked.

      +

      Alex: Treat examples as spoken recipes, not decorations. You may hear something like 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,. Read the command, understand what it changes, then run it only when the repository state matches the lesson.

      -

      Alex: Here is the practical turn. Start with Accessibility. There is something to understand, something to try, and something that proves the try worked.

      -

      Alex: These are the details that keep the idea from floating away. Web Content Accessibility Guidelines (WCAG) 2.2 -- The quick reference version is the most practical. Appendix M: Accessibility Standards -- Workshop reference for WCAG criteria used in this course. WebAIM -- Practical accessibility resources, training, and tools. Deque University -- Free and paid courses on web accessibility.

      -

      Jamie: Let's pause on AI-assisted development. What should a learner take away from it?

      -

      Alex: Start with AI-assisted development. There is something to understand, something to try, and something that proves the try worked.

      -

      Alex: That becomes easier when you listen for these cues. GitHub Copilot documentation -- Official docs for Copilot features, configuration, and best practices. Appendix K: Copilot Reference -- Workshop quick-reference card. Appendix L: Agents Reference -- Full accessibility agents roster and command reference.

      -

      Alex: Keep the thread going. This is where 5. GitHub Skills Courses to Try Next becomes real: GitHub Skills offers free, interactive courses that run inside GitHub repositories. That matters in practice: Each course creates a repository in your account with step-by-step instructions and automated feedback -- the same model we used in this workshop. The workshop is closer to rehearsal than lecture. You hear the move, try the move, and then check what changed.

      +

      Jamie: Let's pause on Screen reader workflow. What should a learner take away from it?

      +

      Alex: Keep the learner anchored in Screen reader workflow. Keyboard tip: Use Ctrl+F (Mac: Cmd+F) to jump to each <!-- placeholder, fill it in, then F3 to jump to the next one.

      +

      Alex: First, create PR (Method 1-3 from Section 5). Then, the description field is pre-filled with the template. After that, navigate through the template with Arrow keys. Finally, replace each `` with your content. It is like walking a hallway with named doors: read the sign, enter the right room, then confirm where you landed.

      +

      Jamie: Before we leave Screen reader workflow, what is the practical point?

      +

      Alex: First, check checkboxes by typing x between the brackets: - [x]. The rhythm is simple: orient, act, verify, then continue.

      +

      Jamie: Let's pause on 7. Commenting and Requesting Changes. What should a learner take away from it?

      +

      Alex: Start with 7. Commenting and Requesting Changes. There is something to understand, something to try, and something that proves the try worked.

      +

      Alex: The practical takeaway is this. Leave inline comments on specific lines. Request changes before the PR can be merged. Approve the PR. Submit general feedback.

      +

      Jamie: Let's pause on Adding an Inline Comment. What should a learner take away from it?

      +

      Alex: Start with Adding an Inline Comment. There is something to understand, something to try, and something that proves the try worked.

      +

      Alex: First, open a file from the PR's "Files Changed" list. Then, navigate to the line you want to comment on. After that, press Shift+F10 (Mac: Ctrl+Return) to open context menu. Finally, select "Add Comment". Think of it as a rail line: each stop confirms you are still on the right route before the next one.

      +

      Jamie: Before we leave Adding an Inline Comment, what is the practical point?

      +

      Alex: First, type your comment. Then, choose "Add Single Comment" (posts immediately) or "Start Review" (saves as a draft). Treat it like a recipe: do not add the next ingredient until the previous one is actually in the bowl.

      -

      Jamie: Turn that into a path someone can follow.

      -

      Alex: Keep the learner anchored in How to start a course. Each course takes 15 to 60 minutes.

      -

      Alex: First, go to skills.github.com. Then, find a course and click its title. After that, click Start course (this creates a repository in your account). Finally, follow the instructions in the repository's README. It is like walking a hallway with named doors: read the sign, enter the right room, then confirm where you landed.

      -

      Alex: Another way to ground it. Start with Community Access. There is something to understand, something to try, and something that proves the try worked.

      -

      Alex: The practical takeaway is this. Community Access on GitHub -- The organization behind this workshop. Watch the repositories for updates. Workshop facilitators are available for questions after the event. Post on the learning-room repository or the git-going-with-github repository.

      -

      Jamie: Give me the sequence, because order matters here.

      -

      Alex: Start with Open source contribution: The capstone was your first contribution.

      -

      Alex: First, start with projects you use. If you use a tool or library and find a bug or missing documentation, that is your first issue. Then, look for "good first issue" labels. Many projects label issues that are suitable for new contributors. After that, documentation counts. Fixing typos, improving instructions, and adding examples are valuable contributions. Do not underestimate them. Finally, the fork workflow scales. The same fork, branch, commit, push, PR workflow from Chapter 18 works for every GitHub project. Think of it as a rail line: each stop confirms you are still on the right route before the next one.

      +

      Jamie: Let's pause on Comment format tips. What should a learner take away from it?

      +

      Alex: Start with Comment format tips. There is something to understand, something to try, and something that proves the try worked.

      +

      Alex: The practical takeaway is this. Be specific: "This heading should be H3, not H2". Provide context: "Screen readers announce this as 'list with 1 item' - should be a paragraph instead". Suggest a fix: "Consider rewording to: 'Click the button to save'".

      +

      Jamie: Let's pause on If you have multiple comments to make, use "Start Review". What should a learner take away from it?

      +

      Alex: Start with If you have multiple comments to make, use "Start Review". There is something to understand, something to try, and something that proves the try worked.

      +

      Alex: First, add your first inline comment → select "Start Review". Then, continue adding comments to other lines. After that, all comments are saved as drafts (not visible to others yet). It is a checklist, but a meaningful one: every item creates evidence that the next step is safe.

      +

      Jamie: Let's pause on Submitting Your Review. What should a learner take away from it?

      +

      Alex: Keep the learner anchored in Submitting Your Review. The review type selector is a radio button group. This is the part to say slowly: Use Arrow keys to choose, Enter to confirm.

      +

      Alex: The practical takeaway is this. Comment - general feedback, no approval decision. Approve - PR looks good, ready to merge. Request Changes - issues must be fixed before merging.

      +

      Alex: First, ctrl+Shift+P (Mac: Cmd+Shift+P). Then, type "GitHub Pull Requests: Submit Review". After that, select "GitHub Pull Requests: Finish Review". Finally, choose review type. It is like walking a hallway with named doors: read the sign, enter the right room, then confirm where you landed.

      +

      Jamie: Before we leave Submitting Your Review, what is the practical point?

      +

      Alex: First, optionally add a summary comment. Then, press Enter to submit. The rhythm is simple: orient, act, verify, then continue.

      -

      Alex: This is the part worth saying out loud. Start with Accessibility community. There is something to understand, something to try, and something that proves the try worked.

      -

      Alex: The practical takeaway is this. GitHub Accessibility documentation -- Official accessibility guides for GitHub's interface. WebAIM mailing list -- Active discussion forum for web accessibility practitioners. A11y Project -- Community-driven accessibility resources and checklist.

      -

      Jamie: How do the two days connect instead of feeling like separate courses?

      -

      Alex: This is where 7. Contributing Back to This Workshop becomes real: if you found something confusing, incorrect, or missing, you can fix it.

      -

      Jamie: What is the ordered workflow?

      -

      Alex: Keep the learner anchored in The contribution workflow. You have already practiced every step of this workflow.

      -

      Alex: First, fork the git-going-with-github repository. Then, clone your fork, create a branch, make your edit. After that, open a PR with a clear title and description. Finally, mention the chapter number and section in your PR. It is like walking a hallway with named doors: read the sign, enter the right room, then confirm where you landed.

      +

      Jamie: Let's pause on What Happens After Submission. What should a learner take away from it?

      +

      Alex: The reason What Happens After Submission matters is that web alternative (github.com) - reviewing. That gives the learner a simple foothold: see Accessible Code Review for detailed screen reader steps. The interface gets friendlier when it stops being a wall of controls and starts being a set of named places.

      +

      Alex: The practical takeaway is this. All your draft comments post to GitHub. The PR author receives a notification. Your review status appears on the PR (Approved / Changes Requested / Commented). If you requested changes, the PR cannot merge until you approve it.

      +

      Alex: First, open the PR and click the Files changed tab. Then, read through each file's diff. After that, click the blue + button on any line to add an inline comment. Finally, choose Start a review to batch comments. The rhythm is simple: orient, act, verify, then continue.

      +

      Jamie: Before we leave What Happens After Submission, what is the practical point?

      +

      Alex: First, click Review changes (top right) to select Comment / Approve / Request changes. Then, click Submit review. Think of it as a rail line: each stop confirms you are still on the right route before the next one.

      +

      Alex: Treat examples as spoken recipes, not decorations. You may hear something like View the PR diff in your terminal; gh pr diff 42; Approve; gh pr review 42 --approve --body "Looks good."; Request changes; gh pr review 42 --request-changes --body "Heading hierarchy needs fixing."; Comment-only (no verdict); gh pr review 42 --comment --body. Read the command, understand what it changes, then run it only when the repository state matches the lesson.

      +

      Jamie: Let's pause on Learning Cards: Commenting and Requesting Changes. What should a learner take away from it?

      +

      Alex: Start with Learning Cards: Commenting and Requesting Changes. There is something to understand, something to try, and something that proves the try worked.

      +

      Alex: The practical takeaway is this. In a diff view, navigate to a line and press Shift+F10 for the context menu, then select "Add Comment" to leave inline feedback. Choose "Start Review" instead of "Single Comment" to batch multiple comments before submitting them all at once. When submitting a review, use Ctrl+Shift+P then "GitHub Pull Requests: Submit Review" and choose Approve, Request Changes, or Comment. Inline comments appear as expandable banners within the diff view -- look for the text input box that opens below the target line. The review submission dialog has radio buttons for Approve, Request Changes, and Comment with clear labels. Increase diff view font size with Ctrl+= so line numbers and change annotations are easier to read.

      +

      Alex: Keep the teaching thread moving. Here is the plain-English version of 8. Merging Pull Requests. Who can merge: Repository maintainers, or contributors with write access.

      -

      Jamie: Where is the promise of the workshop, underneath all the logistics?

      -

      Alex: Start with Learning Cards: Contributing Back to This Workshop. There is something to understand, something to try, and something that proves the try worked.

      -

      Alex: The practical takeaway is this. The contribution workflow here is identical to Chapter 18 (Fork and Contribute) -- fork, clone, branch, edit, push, PR; use the same keyboard and screen reader patterns you already practiced. When filing an issue, include the chapter number and section heading in the title so maintainers can locate the problem with heading navigation. After opening a PR, listen for the automated check results in the PR timeline -- each check is announced as a link with its pass/fail status. The contribution types table above maps each kind of contribution to its workflow -- zoom in on the "How to do it" column for the quickest path. When editing documentation in your fork, use VS Code's Markdown Preview (Ctrl+Shift+V) at your preferred zoom level to verify formatting before pushing. PR descriptions render as Markdown on GitHub -- use headings and lists so reviewers can scan your changes at any zoom level.

      -

      Alex: This is where the talk moves from concept to action. Start with 8. Final Words: Now you have filed issues, opened pull requests, resolved conflicts, reviewed code, and contributed to a real open source project. The next useful detail is this: Every expert started exactly where you are standing. Think of it like entering a new building: first you find the lobby, then the room, then the door you actually need.

      +

      Jamie: Let's pause on Prerequisites for Merging. What should a learner take away from it?

      +

      Alex: This is where Prerequisites for Merging becomes real: changing the base branch: If the PR was opened against the wrong base branch, you can change it from the PR detail view in VS Code. That matters in practice: Scroll to the base branch field in the PR detail view and activate the dropdown to select a different target branch.

      +

      Alex: First, all required reviews are approved. Then, all CI checks pass (green checkmarks). After that, no merge conflicts exist. Finally, branch is up to date with base branch (main). It is a checklist, but a meaningful one: every item creates evidence that the next step is safe.

      +

      Jamie: Let's pause on Method 1: PR Detail View. What should a learner take away from it?

      +

      Alex: Start with Method 1: PR Detail View. There is something to understand, something to try, and something that proves the try worked.

      +

      Alex: First, open the PR in VS Code. Then, scroll to the bottom of the PR detail view. After that, find "Merge Pull Request" button. Finally, press Enter. It is like walking a hallway with named doors: read the sign, enter the right room, then confirm where you landed.

      +

      Jamie: Before we leave Method 1: PR Detail View, what is the practical point?

      +

      Alex: First, choose merge type (see below). The rhythm is simple: orient, act, verify, then continue.

      +

      Jamie: What is the teaching move inside Method 2: Command Palette?

      +

      Alex: Start with Method 2: Command Palette. There is something to understand, something to try, and something that proves the try worked.

      +

      Alex: First, ctrl+Shift+P (Mac: Cmd+Shift+P). Then, type "GitHub Pull Requests: Merge". After that, select "GitHub Pull Requests: Merge Pull Request". Finally, choose the PR from the list. The rhythm is simple: orient, act, verify, then continue.

      +

      Jamie: If someone only remembers one thing from Method 2: Command Palette, what should it be?

      +

      Alex: First, select merge type. Think of it as a rail line: each stop confirms you are still on the right route before the next one.

      -

      Jamie: What should people carry with them after this?

      -

      Alex: Carry the map. Know what page or tool you are in, know which action you are taking, and know what confirmation should follow. If the confirmation is missing, pause. That pause is not wasted time; it is professional judgment.

      -

      Jamie: That is a better way to say it than just follow the steps.

      -

      Alex: Right. Steps matter, but understanding wins. That is episode 49. Next in the series is episode 50, where we keep building the same contributor muscles.

      -
      - +

      Alex: Keep the teaching thread moving. Start with Merge Types: The merge type selector is a dropdown or radio group. The next useful detail is this: Navigate with Arrow keys, confirm with Enter.

      +

      Jamie: Let's pause on Which merge type to use. What should a learner take away from it?

      +

      Alex: Start with Which merge type to use. There is something to understand, something to try, and something that proves the try worked.

      +

      Alex: The practical takeaway is this. Check the repository's CONTRIBUTING.md for guidance. If unsure, use Merge Commit (the default and safest option).

      +

      Jamie: Let's pause on After Merging. What should a learner take away from it?

      +

      Alex: Start with After Merging. There is something to understand, something to try, and something that proves the try worked.

      +

      Alex: First, the PR closes automatically. Then, the feature branch can be deleted (VS Code prompts: "Delete branch?"). After that, recommended: switch back to main and pull the merged changes. It is a checklist, but a meaningful one: every item creates evidence that the next step is safe.

      -

      Appendices

      -

      Episode 50: Advanced Git Operations

      -

      Cherry-pick, rebase, revert, reset, tags, bisect, clean, and other Git recovery tools.

      -

      Based on: Appendix E: Advanced Git Operations

      -

      Audio and transcript are being regenerated for this episode.

      -
      -Read Transcript - Episode 50: Advanced Git Operations - -

      Transcript

      -

      Alex: This is Git Going with GitHub, episode 50: Advanced Git Operations. I am Alex. By the end of this episode, Advanced Git Operations should feel less like a wall of GitHub words and more like a set of moves you can trust.

      -

      Jamie: And I am Jamie. I am here for the practical questions: what should I listen for, what can go wrong, and what is the next calm move?

      +

      Jamie: What should happen before anyone copies and runs it?

      +

      Alex: Keep the learner anchored in Switching to main and pulling. (Mac users: use Cmd+Shift+P instead of Ctrl+Shift+P).

      +

      Alex: Treat examples as spoken recipes, not decorations. You may hear something like Ctrl+Shift+P → "Git: Checkout to." → select "main"; Ctrl+Shift+P → "Git: Pull". Read the command, understand what it changes, then run it only when the repository state matches the lesson.

      +

      Jamie: Let's pause on Deleting the Feature Branch. What should a learner take away from it?

      +

      Alex: The reason Deleting the Feature Branch matters is that after merging, the feature branch is no longer needed. That gives the learner a simple foothold: web alternative (github.com) - merging.

      +

      Alex: First, ctrl+Shift+P (Mac: Cmd+Shift+P). Then, type "git delete branch". After that, select "Git: Delete Branch.". Finally, choose the merged branch. The rhythm is simple: orient, act, verify, then continue.

      +

      Jamie: Before we leave Deleting the Feature Branch, what is the practical point?

      +

      Alex: First, open the PR's Conversation tab. Then, scroll to the merge button at the bottom. After that, click the dropdown arrow to choose a merge strategy (Squash, Rebase, or Merge commit). Finally, click Merge pull request, then Confirm merge. Think of it as a rail line: each stop confirms you are still on the right route before the next one.

      +

      Alex: Treat examples as spoken recipes, not decorations. You may hear something like Merge with default strategy; gh pr merge 42; Squash and merge, then delete the branch; gh pr merge 42 --squash --delete-branch; Enable auto-merge (merges when checks pass); gh pr merge 42 --auto --squash. Read the command, understand what it changes, then run it only when the repository state matches the lesson.

      +

      Jamie: Let's pause on Learning Cards: Merging Pull Requests. What should a learner take away from it?

      +

      Alex: Start with Learning Cards: Merging Pull Requests. There is something to understand, something to try, and something that proves the try worked.

      +

      Alex: The practical takeaway is this. The merge type selector (Merge Commit, Squash, Rebase) is announced as a dropdown or radio group -- use Arrow keys to move between options and Enter to confirm; if unsure, choose Merge Commit (the default and safest option). After merging, VS Code prompts "Delete branch?" as a notification -- press Alt+N to focus the notification and Enter to confirm, then run Ctrl+Shift+P then "Git: Checkout to" and select main to return to your default branch. Confirm the merge succeeded by pressing F6 to reach the Status Bar and verifying it now reads main instead of the feature branch name. The merge button at the bottom of the PR detail view includes a dropdown arrow for selecting merge type -- at high zoom, widen the editor pane so the button label and dropdown are not truncated. After merging, the PR detail view header changes from "Open" (green badge) to "Merged" (purple badge) -- verify this colour/label change before deleting the branch. When switching back to main, the branch name in the bottom-left Status Bar updates immediately -- confirm it reads main before pulling new changes with Ctrl+Shift+P then "Git: Pull".

      -

      Alex: Today we are working on this: Cherry-pick, rebase, revert, reset, tags, bisect, clean, and other Git recovery tools. I want the learner to leave with a mental map, not just a remembered path through buttons.

      -

      Jamie: So the goal is understanding first, then action, then confirmation.

      -

      Alex: Right. We are building a rhythm: orient yourself, take one intentional action, then verify what changed before moving on.

      +

      Alex: Keep the teaching thread moving. Here is the plain-English version of "No pull requests found". Issue: The GitHub Pull Requests panel is empty. It is like learning a transit route. The names of the stops matter because they tell you whether you are still going the right direction.

      +

      Jamie: Let's pause on Solutions. What should a learner take away from it?

      +

      Alex: Start with Solutions. There is something to understand, something to try, and something that proves the try worked.

      +

      Alex: First, verify you're signed in: Ctrl+Shift+P (Mac: Cmd+Shift+P) → "GitHub Pull Requests: Sign in". Then, check you have a folder open containing a Git repository. After that, refresh the panel: Ctrl+Shift+P (Mac: Cmd+Shift+P) → "GitHub Pull Requests: Refresh Pull Requests List". It is a checklist, but a meaningful one: every item creates evidence that the next step is safe.

      +

      Jamie: Before we leave Solutions, what is the practical point?

      +

      Alex: First, verify you've pushed your branch: Ctrl+Shift+P (Mac: Cmd+Shift+P) → "Git: Push". Then, check you have write access to the repository. After that, ensure your branch is ahead of the base branch (has new commits). It is like walking a hallway with named doors: read the sign, enter the right room, then confirm where you landed.

      -

      Jamie: Okay, set the room for us. What are we walking into?

      -

      Alex: Start with Going Deeper with Git: Who this is for: You have completed Chapter 11 (Git & Source Control) and feel comfortable with the basics -- cloning, branching, committing, pushing, and pulling. The next useful detail is this: This appendix covers the next tier of Git skills that come up constantly in real open source contribution: cherry-picking fixes across branches, cleaning up messy commit history before a PR, safely undoing mistakes, and understanding why your push sometimes.

      -

      Alex: A solid Git habit is to know which branch you are on, what changed, and what confirmation you expect before you run the next command.

      -

      Alex: The next layer is this. Start with Learning Cards: Using This Advanced Git Reference. There is something to understand, something to try, and something that proves the try worked.

      -

      Alex: The practical anchors are these. Each operation is a numbered h2 section with three sub-paths: VS Code, GitHub CLI, and Git CLI. Use H to jump between operations and 3 to jump between the tool-specific sub-headings within each. The Table of Contents above has anchor links -- activate any link to jump directly to that operation. Command examples are in labeled code blocks -- increase zoom and each command fits on one line. Every section follows the same structure: what it is, when to use it, then tool-specific steps. The Quick Reference table near the bottom gives a one-row-per-operation summary for fast lookup.

      -

      Jamie: What is the one idea that makes the next few steps less mysterious?

      -

      Alex: This is where 1. Cherry-Pick -- Grabbing a Specific Commit becomes real: what it is: Cherry-pick lets you take a single commit from any branch and apply it to your current branch. That matters in practice: Think of it like copy-pasting a specific change -- without bringing the entire branch along with it.

      -

      Alex: That shows up in the workshop in a few specific ways. You fixed a bug on a feature branch, but main also needs that fix right now. A teammate landed a commit on their branch and you need just that one change. You accidentally committed to the wrong branch and need to move that commit somewhere else.

      +

      Jamie: Let's pause on "Authentication failed". What should a learner take away from it?

      +

      Alex: The reason "Authentication failed" matters is that issue: VS Code can't connect to GitHub.

      +

      Jamie: What is the teaching move inside Solutions?

      +

      Alex: First, sign out and sign back in: Ctrl+Shift+P (Mac: Cmd+Shift+P) → "GitHub Pull Requests: Sign out" → then sign in again. Then, check your GitHub Personal Access Token (see Appendix D: Git Authentication). After that, verify network connection. Think of it as a rail line: each stop confirms you are still on the right route before the next one.

      +

      Jamie: Let's pause on Try It: Review a PR from VS Code. What should a learner take away from it?

      +

      Alex: Here is the plain-English version of Try It: Review a PR from VS Code. Time: 3 minutes What you need: VS Code with GitHub Pull Requests extension installed and signed in. Put another way, you just reviewed a pull request entirely from VS Code.

      +

      Alex: First, open the PR view - Press Ctrl+Shift+P → type Pull Requests: Focus on GitHub Pull Requests View → Enter. Then, find a PR - Navigate the tree with arrow keys. Expand a PR to see its changed files. After that, open a diff - Press Enter on a changed file. The diff editor opens. Finally, use the Accessible Diff Viewer - Press F7 to jump to the first change. Your screen reader announces what was added or removed. Press F7 again to move to the next change. Treat it like a recipe: do not add the next ingredient until the previous one is actually in the bowl.

      +

      Jamie: Before we leave Try It: Review a PR from VS Code, what is the practical point?

      +

      Alex: First, leave a comment - Position your cursor on a line you want to comment on, then press Ctrl+Shift+P → Pull Request: Add Comment on Current Diff Line. Type a brief, constructive comment and submit. It is a checklist, but a meaningful one: every item creates evidence that the next step is safe.

      -

      Alex: Now bring the learner back to the room. Keep the learner anchored in Finding the Commit SHA. Before cherry-picking, you need the commit's SHA (the unique ID for that commit).

      -

      Jamie: What is the ordered workflow?

      -

      Alex: Start with VS Code. There is something to understand, something to try, and something that proves the try worked.

      -

      Alex: First, open the Timeline panel: Click View → Open View → Timeline (or press Ctrl+Shift+P and type "Timeline"). Then, switch to the branch that has the commit you want, browse the Timeline, and copy the commit SHA shown in the details panel. The rhythm is simple: orient, act, verify, then continue.

      -

      Alex: The useful habit is simple: orient first, act second, verify third. That pause before acting is part of the work.

      -

      Jamie: How do you keep commands from becoming magic words?

      -

      Alex: Start with Git CLI: The short SHA is the first 7 characters (a1b2c3d). Think of it like entering a new building: first you find the lobby, then the room, then the door you actually need.

      -

      Alex: Treat examples as spoken recipes, not decorations. You may hear something like See commits on another branch without switching to it; git log feature/bug-fix --oneline; Output:; a1b2c3d Fix null pointer error in auth module; e4f5g6h Add unit tests for login. Read the command, understand what it changes, then run it only when the repository state matches the lesson.

      +

      Alex: Keep the teaching thread moving. This is where Conducting Pull Request Reviews with a Screen Reader becomes real: this guide is focused entirely on the reviewer experience - navigating diffs, reading changes, leaving comments, and submitting a review - using only your keyboard and screen reader. That matters in practice: For the full pull request lifecycle (opening PRs, merge options, conflict resolution), see Working with Pull Requests.

      +

      Jamie: Where does the workshop stop being a tour and start becoming contribution?

      +

      Alex: Keep the learner anchored in Workshop Recommendation (Chapter 15 / Challenge 12). Chapter 15 is the code review chapter focused on practicing constructive feedback. This is the part to say slowly: It supports Challenge 12: Review Like a Pro.

      +

      Alex: The practical takeaway is this. There are 2 guided challenges. Automation check: none (review quality is subjective and human-focused). The evidence is issue comment with summary of review and feedback posted. The pattern is navigate diff, comment on specifics, submit verdict.

      +

      Jamie: Let's pause on Challenge 12 Practice Set. What should a learner take away from it?

      +

      Alex: Start with Challenge 12 Practice Set. There is something to understand, something to try, and something that proves the try worked.

      +

      Alex: First, review a practice PR and leave 2-3 inline comments - read the diff line by line, find specific items to comment on, and post constructive feedback. Then, submit a formal review verdict - complete your review by choosing approve, request changes, or comment only. The rhythm is simple: orient, act, verify, then continue.

      -

      Jamie: How would you walk the room through that step by step?

      -

      Alex: Start with VS Code (Command Palette). There is something to understand, something to try, and something that proves the try worked.

      -

      Alex: First, press Ctrl+Shift+P (or Cmd+Shift+P on macOS). Then, type "cherry" and select "Git: Cherry Pick.". After that, paste or type the commit SHA. Finally, press Enter -- VS Code applies the commit to your current branch. Treat it like a recipe: do not add the next ingredient until the previous one is actually in the bowl.

      -

      Jamie: What should happen before anyone copies and runs it?

      -

      Alex: This is where GitHub CLI becomes real: the GitHub CLI doesn't have a direct cherry-pick command (it's a local Git operation), but you can use it to find the SHA first.

      -

      Alex: Treat examples as spoken recipes, not decorations. You may hear something like List commits on a branch via gh to find the one you want; gh api repos/{owner}/{repo}/commits?sha=feature/bug-fix --jq '.[].sha,.[].commit.message' head -20; Then cherry-pick using git; git cherry-pick a1b2c3d. Read the command, understand what it changes, then run it only when the repository state matches the lesson.

      -

      Jamie: What should they understand before typing anything?

      -

      Alex: Start with Git CLI. There is something to understand, something to try, and something that proves the try worked.

      -

      Alex: Treat examples as spoken recipes, not decorations. You may hear something like Apply a single commit; git cherry-pick a1b2c3d; Apply a range of commits (from older to newer, exclusive of first); git cherry-pick a1b2c3d.e4f5g6h; Apply without automatically committing (lets you review changes first); git cherry-pick --no-commit a1b2c3d. Read the command, understand what it changes, then run it only when the repository state matches the lesson.

      +

      Jamie: Let's pause on Practice 12.1 Step-by-Step: Review a PR and Leave Inline Comments. What should a learner take away from it?

      +

      Alex: Start with Practice 12.1 Step-by-Step: Review a PR and Leave Inline Comments: Navigate a PR diff using screen reader-friendly tools and post 2-3 specific, constructive inline comments. The next useful detail is this: GitHub.com (Files changed tab of a PR) or VS Code with the GitHub Pull Requests extension.

      +

      Alex: The practical takeaway is this. On GitHub.com: Use heading navigation to jump between files (H in NVDA). Each file header is a heading. Within a file, use arrow keys to move line by line. In VS Code: Press F7 to open the Accessible Diff Viewer (see Chapter 15, Part 1). Use F7/Shift+F7 to move between changes. Typos or grammar issues. Unclear headings or link text.

      +

      Alex: First, open your Learning Room repository on GitHub.com and navigate to the Pull requests tab. Then, find a classmate's open PR (from Chapter 6, 7, or 14). Open it. After that, activate the Files changed tab. This shows the diff - lines added in green, lines removed in red. Finally, navigate the diff. Think of it as a rail line: each stop confirms you are still on the right route before the next one.

      +

      Jamie: Before we leave Practice 12.1 Step-by-Step: Review a PR and Leave Inline Comments, what is the practical point?

      +

      Alex: First, read through the changes carefully. Look. Then, to leave an inline comment on GitHub.com: activate the + button that appears to the left of a line number when you hover or Tab to it. (Screen reader users: this button may be announced as "Add a comment to this line.") Type your comment in the text box that. After that, post 2-3 inline comments. Each comment should be. Finally, examples of good inline comments. Treat it like a recipe: do not add the next ingredient until the previous one is actually in the bowl.

      +

      Jamie: Let's pause on Practice 12.2 Step-by-Step: Submit a Formal Review Verdict. What should a learner take away from it?

      +

      Alex: Here is the plain-English version of Practice 12.2 Step-by-Step: Submit a Formal Review Verdict. Complete your review by selecting a verdict that tells the author what action to take next. Put another way, GitHub.com (the same PR you reviewed in 14.1).

      +

      Alex: The practical takeaway is this. Comment - general feedback, no explicit approval or rejection. Approve - you think the PR is ready to merge. Request changes - you found something that should be fixed before merging. If the PR has clear documentation with only minor suggestions, choose Approve.

      +

      Alex: First, after posting your inline comments, scroll to the top of the Files changed tab. Then, activate the Review changes button (at the top-right of the files changed area, or use heading navigation). After that, a dropdown opens with three options. Finally, choose the verdict that matches your review. Treat it like a recipe: do not add the next ingredient until the previous one is actually in the bowl.

      +

      Jamie: Before we leave Practice 12.2 Step-by-Step: Submit a Formal Review Verdict, what is the practical point?

      +

      Alex: First, write a brief summary in the review body (1-2 sentences). Example: "Clear improvement to the shortcut table. Two minor suggestions for link text clarity.". Then, activate Submit review. It is a checklist, but a meaningful one: every item creates evidence that the next step is safe.

      +

      Jamie: What makes this practice feel low-stakes but still real?

      +

      Alex: This is where Completing Challenge 12: Submit Your Evidence becomes real: open your assigned Challenge 12 issue and post a completion comment. That matters in practice: Close your Challenge 12 issue when done.

      -

      Jamie: Give me the sequence, because order matters here.

      -

      Alex: The reason If There's a Conflict matters is that cherry-pick can hit conflicts just like a merge. That gives the learner a simple foothold: when a cherry-pick stops due to a conflict, run git status in the terminal -- it announces exactly which files need attention. The interface gets friendlier when it stops being a wall of controls and starts being a set of named places.

      -

      Alex: First, Git pauses and marks the conflicting files (same <<<<<<< HEAD markers as merge conflicts). Then, resolve the conflicts in VS Code's conflict editor (see Chapter 7: Merge Conflicts). After that, stage the resolved files. Finally, then either. The rhythm is simple: orient, act, verify, then continue.

      -

      Alex: Treat examples as spoken recipes, not decorations. You may hear something like Continue the cherry-pick after resolving; git cherry-pick --continue; Or cancel it entirely and go back to where you started; git cherry-pick --abort. Read the command, understand what it changes, then run it only when the repository state matches the lesson.

      -

      Jamie: What would you say to someone who is already bracing for this to be too much?

      -

      Alex: Start with 2. Interactive Rebase -- Cleaning Up Your History: What it is: Interactive rebase (git rebase -i) is like a time machine for your commits. The next useful detail is this: Before you open a PR, you can reorder commits, combine several small commits into one clean commit, rewrite commit messages, or remove commits that were just experiments.

      -

      Alex: A few details make that real. You made 8 "WIP" commits while working and want to combine them into 1 clean commit for your PR. You want to reword a commit message to better describe what changed. You accidentally committed a debug file and want to remove that commit entirely.

      -

      Jamie: What does the learner do first, second, and then after that?

      -

      Alex: Here is the plain-English version of VS Code. VS Code has basic rebase support via the Command Palette, but for full interactive rebase you'll want the terminal. Put another way, after that, git rebase -i will open the commit list in VS Code itself -- much more screen-reader-friendly.

      -

      Alex: First, open the Integrated Terminal: Ctrl+Backtick. Then, run the command below to rebase the last N commits (replace N with how many commits you want to edit). After that, your default editor opens with a list of your commits. If it opens in vim, type i to enter insert mode, make your edits, then press Esc followed by:wq to save. If you'd prefer VS Code as the editor. Treat it like a recipe: do not add the next ingredient until the previous one is actually in the bowl.

      -

      Alex: Treat examples as spoken recipes, not decorations. You may hear something like git rebase -i HEAD 3; This opens your last 3 commits for editing. git config --global core.editor "code --wait". Read the command, understand what it changes, then run it only when the repository state matches the lesson.

      +

      Alex: Keep the teaching thread moving. Start with Expected Outcomes. There is something to understand, something to try, and something that proves the try worked.

      +

      Alex: The practical takeaway is this. Student can navigate PR diffs with a screen reader. Student can post inline comments on specific lines of a diff. Student can write constructive, specific feedback that helps the author improve. Student can submit a formal review verdict.

      +

      Jamie: What is the teaching move inside If You Get Stuck?

      +

      Alex: The reason If You Get Stuck matters is that continue learning: The GitHub Skills courses Review Pull Requests and Code Review with GitHub Copilot cover review workflows and AI-assisted code review. That gives the learner a simple foothold: see Appendix Z for the full catalog.

      +

      Alex: First, files Changed tab will not open? Reload the PR page and retry. Make sure you are on the PR page, not the issue page. Then, cannot find the inline comment button? Tab through the line controls in the diff. The button may be announced as "Add a comment" or have a + label. If you cannot find it, use the "Review changes" button at the top to add a general comment instead. After that, not sure what to comment on? Focus on clarity: is every heading descriptive? Is every link meaningful? Are steps complete? Are keyboard shortcuts correct? Finally, review verdict button not working? Make sure you have at least one comment or have written summary text. Try reloading the page. The rhythm is simple: orient, act, verify, then continue.

      +

      Jamie: If someone only remembers one thing from If You Get Stuck, what should it be?

      +

      Alex: First, submitting the review fails? Check that you are not in draft mode and have at least read access to the repo. Then, ask facilitator to model one inline comment and one verdict submission. After that, finished but not sure you did it right? Compare your work against the Challenge 12 reference solution. Think of it as a rail line: each stop confirms you are still on the right route before the next one.

      +

      Alex: Keep the teaching thread moving. Start with Learning Moment: Specific, kind feedback helps authors improve and builds trust in the community. The next useful detail is this: Every comment you write is practice for the professional code review you will do on real projects.

      -

      Jamie: What is the safe way to learn from that example?

      -

      Alex: Start with Git CLI (Terminal). There is something to understand, something to try, and something that proves the try worked.

      -

      Alex: Treat examples as spoken recipes, not decorations. You may hear something like Rebase the last 3 commits; git rebase -i HEAD 3; Or rebase everything since you branched from main; git rebase -i main. Read the command, understand what it changes, then run it only when the repository state matches the lesson.

      -

      Alex: That connects to another useful point. Keep the learner anchored in The Commit List -- What You're Looking At. When the editor opens, you see something like this. This is the part to say slowly: Each line starts with a command word. A good GitHub workflow is like a well-run meeting: everyone knows the topic, the next action, and who has the floor.

      -

      Jamie: Where do you want a learner to place their attention here?

      -

      Alex: The reason Example: Squashing 3 Commits Into 1 matters is that Git opens a second editor for you to write the combined commit message. That gives the learner a simple foothold: write a clean summary and save -- done.

      +

      Jamie: Before we leave Learning Pattern Used in This Chapter, what is the practical point?

      +

      Alex: First, read the full diff before commenting (understand the author's intent first). Then, find specific items to comment on (lines, phrases, missing steps). After that, write comments that help, not just criticize (suggest improvements, note what works). Finally, choose a verdict that matches the substance of your feedback. Treat it like a recipe: do not add the next ingredient until the previous one is actually in the bowl.

      +

      Jamie: What is the teaching move inside Learning Pattern Used in This Chapter?

      +

      Alex: First, summarize your overall impression in 1-2 sentences. It is a checklist, but a meaningful one: every item creates evidence that the next step is safe.

      +

      Alex: Keep the teaching thread moving. This is where Before starting this chapter, verify you have completed becomes real: estimated time for this chapter: 1 hour (including exercises). The workshop is closer to rehearsal than lecture. You hear the move, try the move, and then check what changed.

      +

      Alex: The practical takeaway is this. [ ] Chapter 6: Working with Pull Requests - Understand PR structure, diffs, and comment workflows. [ ] Chapter 13: GitHub Copilot - VS Code installed and configured. [ ] Screen Reader Setup - NVDA, JAWS, or VoiceOver installed and ready to use. [ ] Access to at least one pull request to review (your own fork or a practice repo).

      +

      Jamie: Let's pause on Two Environments for Code Review. What should a learner take away from it?

      +

      Alex: Keep the learner anchored in Two Environments for Code Review. You can review pull requests in two places - each with different strengths. This is the part to say slowly: Both environments give you full keyboard and screen reader access.

      -

      Alex: Here is the practical turn. Start with Example: Rewriting a Commit Message: Git opens the commit message for a1b2c3d for you to edit. The next useful detail is this: Write the new message, save -- done.

      -

      Jamie: Let's pause on If Something Goes Wrong. What should a learner take away from it?

      -

      Alex: Here is the plain-English version of If Something Goes Wrong. Run git rebase -i with VS Code as your editor (git config --global core.editor "code --wait") -- the commit list opens in a VS Code tab that your screen reader can navigate normally with arrow keys. Put another way, GitHub Copilot can help: Not sure how to word a squashed commit message?

      -

      Alex: Treat examples as spoken recipes, not decorations. You may hear something like Abort the rebase and go back to where you started; git rebase --abort; If you're mid-rebase and hit a conflict, resolve it then continue; git rebase --continue. Read the command, understand what it changes, then run it only when the repository state matches the lesson.

      -

      Alex: Keep the thread going. This is where 3. git reset -- Undoing at Different Depths becomes real: what it is: git reset moves the tip of your current branch backward to a previous commit. That matters in practice: The three modes (--soft, --mixed, --hard) control what happens to the changes that were in those commits. The workshop is closer to rehearsal than lecture. You hear the move, try the move, and then check what changed.

      -

      Alex: The room should hear these as checkpoints. You committed too early and want to add more changes to that commit. You staged the wrong files and want to unstage them. You want to completely throw away the last few commits and start fresh.

      -

      Alex: A solid pull request habit is to separate three questions: what changed, why it changed, and what still needs review. That keeps the conversation useful instead of noisy.

      +

      Jamie: What should they understand before typing anything?

      +

      Alex: The reason About Learning Cards in This Chapter matters is that each review step includes expandable learning cards for different interaction styles. That gives the learner a simple foothold: open the one that matches how you work.

      +

      Alex: Treat examples as spoken recipes, not decorations. You may hear something like View the full PR diff in your terminal; gh pr diff 42; View PR details (description, status, checks); gh pr view 42; Checkout the PR branch locally for testing; gh pr checkout 42; Approve the PR; gh pr review 42 --approve --body "Heading hierarchy looks. Read the command, understand what it changes, then run it only when the repository state matches the lesson.

      +

      Jamie: Let's pause on Good News: Modern Interface is Default. What should a learner take away from it?

      +

      Alex: Start with Good News: Modern Interface is Default: As of January 2026, GitHub's improved Files Changed experience is enabled by default. The next useful detail is this: The instructions below assume you have the modern interface (which you do).

      +

      Jamie: Let's pause on Step 1: Reach the Files Changed Tab. What should a learner take away from it?

      +

      Alex: Here is the plain-English version of Step 1: Reach the Files Changed Tab. Click the Files changed tab at the top of the PR page. Put another way, the tab label shows the number of changed files (e.g., "Files changed 4"). It is like learning a transit route. The names of the stops matter because they tell you whether you are still going the right direction.

      +

      Alex: First, the PR tabs (Conversation, Commits, Checks, Files changed) are across the top of the PR page. At high zoom they may wrap to multiple lines. Then, the Files changed tab includes a badge with the number of changed files. This badge uses text (not colour alone) so it is visible in all themes. After that, after clicking Files changed, the diff page loads. At high zoom, the file tree panel on the left may collapse automatically. Click the file tree toggle (a small panel icon) or press T to toggle it back. Finally, added lines use a green background; removed lines use red. In high contrast browser settings (Windows: Settings Accessibility Contrast themes), these colours map to strong border indicators. Treat it like a recipe: do not add the next ingredient until the previous one is actually in the bowl.

      +

      Jamie: Before we leave Step 1: Reach the Files Changed Tab, what is the practical point?

      +

      Alex: First, use Ctrl++ to zoom the browser if the diff text is too small, and Ctrl+- to zoom out. It is a checklist, but a meaningful one: every item creates evidence that the next step is safe.

      +

      Alex: Treat examples as spoken recipes, not decorations. You may hear something like Press D → navigate to "Pull request navigation tabs" landmark; Press → or Tab → find "Files changed" link → Enter. Read the command, understand what it changes, then run it only when the repository state matches the lesson.

      -

      Jamie: If I am listening before the workshop starts, what should settle in my mind first?

      -

      Alex: Keep the learner anchored in The Three Modes. Think of Git as having three layers: your working files (what you can see in the editor), the staging area (what git add puts there), and the commit history. This is the part to say slowly: It permanently discards your uncommitted changes.

      -

      Jamie: Turn that into a path someone can follow.

      -

      Alex: The reason Using the Source Control panel matters is that this is equivalent to git reset --soft HEAD 1 -- your changes come back as staged files, nothing is lost.

      -

      Alex: First, open Source Control: Ctrl+Shift+G. Then, click the "." (More Actions) menu at the top of the panel. After that, select "Commit → Undo Last Commit". The rhythm is simple: orient, act, verify, then continue.

      -

      Jamie: Let's pause on Using the Command Palette. What should a learner take away from it?

      -

      Alex: Start with Using the Command Palette. There is something to understand, something to try, and something that proves the try worked.

      -

      Alex: Treat examples as spoken recipes, not decorations. You may hear something like Ctrl+Shift+P → type "git undo" → select "Git: Undo Last Commit". Read the command, understand what it changes, then run it only when the repository state matches the lesson.

      +

      Jamie: Let's pause on Step 2: Use the File Tree to Orient Yourself. What should a learner take away from it?

      +

      Alex: This is where Step 2: Use the File Tree to Orient Yourself becomes real: the file tree panel lists every changed file. That matters in practice: Before reading any diff, scan this list to understand the scope of the PR.

      +

      Jamie: Let's pause on What to listen for / look for. What should a learner take away from it?

      +

      Alex: Keep the learner anchored in What to listen for / look for. Low vision users (zoom, high contrast).

      +

      Alex: The practical takeaway is this. How many files changed? Which areas of the codebase are affected? Are there unexpected files (generated files, lock files, configuration changes)?

      +

      Alex: First, the file tree shows each filename with a colour-coded bar indicating lines added (green) and removed (red). In high contrast mode, these bars may be less visible - the +N / -N text badge next to each file is the reliable indicator. Then, at high zoom, long file paths truncate. Hover over a truncated name to see the full path in a tooltip. After that, if the file tree panel is too narrow at high zoom, drag its right edge to widen it, or toggle it off and use heading navigation (H key) to move between file diffs. It is like walking a hallway with named doors: read the sign, enter the right room, then confirm where you landed.

      +

      Jamie: How do you keep commands from becoming magic words?

      +

      Alex: The reason Step 3: Navigate Between File Diffs matters is that each changed file in the main area is an h3 heading containing the filename. That gives the learner a simple foothold: scroll through the page or click a filename in the file tree on the left.

      +

      Alex: Treat examples as spoken recipes, not decorations. You may hear something like Press 3 to jump file-by-file through the diff; Listen for: "learning-room/docs/keyboard-shortcuts.md - collapsed" or "expanded"; Press Enter or Space to expand a collapsed file. Quick Nav H or VO+Cmd+H to jump file-by-file through the diff; Listen for: "learning-room/docs/keyboard-shortcuts.md - collapsed" or "expanded"; VO+Space to expand a collapsed file. Read the command, understand what it changes, then run it only when the repository state matches the lesson.

      -

      Jamie: Let's pause on Git CLI. What should a learner take away from it?

      -

      Alex: Treat examples as spoken recipes, not decorations. You may hear something like Undo last commit -- keep changes staged (safest); git reset --soft HEAD 1; Undo last commit -- keep changes but unstage them; git reset --mixed HEAD 1; Undo last 3 commits -- keep all changes unstaged; git reset --mixed HEAD 3; Undo last commit -- DISCARD all. Read the command, understand what it changes, then run it only when the repository state matches the lesson.

      -

      Jamie: Give me the version that sounds like an instructor, not a manual.

      -

      Alex: This is where Unstaging a File (Without Undoing the Commit) becomes real: if you just want to remove a file from the staging area without touching commit history.

      -

      Alex: That matters because of the next idea. Keep the learner anchored in VS Code. In the Source Control panel, click the minus (--) icon next to a staged file, or right-click it and select "Unstage Changes".

      +

      Jamie: Let's pause on Step 4: Read a Diff. What should a learner take away from it?

      +

      Alex: Start with Step 4: Read a Diff: Low vision users (zoom, high contrast). The next useful detail is this: Screen reader users - VoiceOver (macOS). Think of it like entering a new building: first you find the lobby, then the room, then the door you actually need.

      +

      Alex: The practical takeaway is this. Green highlighted lines (with a +) = lines added. Red highlighted lines (with a -) = lines removed. Plain/white lines = unchanged context. Use Ctrl+F to search within the page for specific text in the diff.

      +

      Alex: First, colour is not the only indicator. Every added line has a + character in the gutter; every removed line has a -. These text characters are reliable regardless of colour settings. Then, at high zoom, long lines of code wrap. The +/- gutter character stays at the beginning of the first line, so look left to determine the change type. After that, use Ctrl+F (browser find) to search for specific text across the entire diff page. Finally, if the diff is split view (side by side), it may be very wide at high zoom. Switch to unified diff mode: click the gear icon in the Files Changed toolbar and select "Unified" - this shows old and new in a single column. Think of it as a rail line: each stop confirms you are still on the right route before the next one.

      +

      Jamie: Before we leave Step 4: Read a Diff, what is the practical point?

      +

      Alex: First, high contrast themes in Windows (Settings Accessibility Contrast themes) make the +/- lines use bold border patterns instead of subtle colour shading. Treat it like a recipe: do not add the next ingredient until the previous one is actually in the bowl.

      +

      Alex: Treat examples as spoken recipes, not decorations. You may hear something like Press T to jump to the diff table then Insert+Space (Focus Mode); Press Down Arrow to move through lines one at a time; Press Ctrl+Alt+Right Arrow to read across columns: line number, change type, code content. Press T to jump to the diff table then Insert+Z (Virtual PC Cursor off); Press Down Arrow to move through lines; Press Ctrl+Alt+Right Arrow for column-by-column reading. Read the command, understand what it changes, then run it only when the repository state matches the lesson.

      +

      Jamie: Let's pause on What each line announces / shows. What should a learner take away from it?

      +

      Alex: Here is the plain-English version of What each line announces / shows. If the code on a line is very long, the screen reader will read the full line. Put another way, for minified or generated files, consider collapsing the file in the tree and skipping it.

      +

      Alex: The practical takeaway is this. Added lines: "+ [code content]" - or announced as "inserted". Removed lines: "- [code content]" - or announced as "deleted". Context lines: code without a + or -.

      +

      Jamie: Let's pause on Step 5: Place an Inline Comment. What should a learner take away from it?

      +

      Alex: This is where Step 5: Place an Inline Comment becomes real: when you have a specific observation about a particular line, place an inline comment directly on it. That matters in practice: Screen reader users (VoiceOver - macOS).

      +

      Alex: First, hover your mouse over a line in the diff - a blue + (comment) button appears on the left. Then, click it to open the inline comment box. After that, type your comment. Finally, click "Start a review" (not "Add single comment" - see note below). It is a checklist, but a meaningful one: every item creates evidence that the next step is safe.

      -

      Jamie: Before we leave Git CLI, what is the practical point?

      -

      Alex: Treat examples as spoken recipes, not decorations. You may hear something like Unstage a specific file; git restore --staged docs/README.md; Unstage everything; git restore --staged. Read the command, understand what it changes, then run it only when the repository state matches the lesson.

      -

      Alex: This is where the talk moves from concept to action. Start with 4. git revert -- The Safe Undo for Shared Branches: What it is: git revert creates a new commit that undoes the changes from a previous commit. The next useful detail is this: Unlike git reset, it does not rewrite history -- it adds to it. Think of it like entering a new building: first you find the lobby, then the room, then the door you actually need.

      -

      Alex: On the ground, that means a few things. A commit made it to main and it broke something -- you need to roll it back without force-pushing. You want to undo a change but keep a record that the undo happened. You're working on a protected branch where force-push is disabled.

      -

      Jamie: Let's pause on VS Code. What should a learner take away from it?

      -

      Alex: First, open the Timeline panel and navigate to the commit you want to undo. Then, right-click the commit and select "Revert Commit". After that, VS Code creates a new commit with message Revert "your original message" -- review it and push. Treat it like a recipe: do not add the next ingredient until the previous one is actually in the bowl.

      -
      -

      Jamie: What is the teaching move inside Git CLI?

      -

      Alex: Treat examples as spoken recipes, not decorations. You may hear something like Revert a specific commit (opens editor to confirm the message); git revert a1b2c3d; Revert without opening the editor (uses default message); git revert --no-edit a1b2c3d; Stage the revert but don't commit yet (lets you edit the message manually); git revert. Read the command, understand what it changes, then run it only when the repository state matches the lesson.

      -

      Jamie: How should someone choose between those options?

      -

      Alex: Keep the learner anchored in When to Use revert vs reset. GitHub Copilot can help: Not sure whether to use reset or revert? This is the part to say slowly: Describe your situation to Copilot Chat: "I pushed a commit to main that broke the login page.

      -

      Alex: Use the comparison to make a decision, not to recite a table. The main contrasts are: Commit is only local (not pushed) means git reset -- cleaner, no extra commit. Commit is on a shared branch (main, dev) means git revert -- preserves history, safe for others. Branch has protection rules (no force push) means git revert -- the only option.

      -

      Alex: Another way to ground it. The reason 5. Tags -- Marking Important Moments matters is that what it is: A tag is a permanent label you attach to a specific commit -- usually to mark a release version like v1.0.0. That gives the learner a simple foothold: unlike a branch (which moves as you commit), a tag always points to the exact same commit forever. The interface gets friendlier when it stops being a wall of controls and starts being a set of named places.

      -

      Alex: That becomes easier when you listen for these cues. Releasing a new version of a project. Marking a stable checkpoint before starting a big refactor. Documenting when a major feature shipped.

      +

      Jamie: Let's pause on Placing a multi-line comment. What should a learner take away from it?

      +

      Alex: Keep the learner anchored in Placing a multi-line comment. Click and drag across multiple line numbers in the diff gutter to select a range. This is the part to say slowly: A comment button appears for the selected range.

      +

      Jamie: Let's pause on Step 6: Read Existing Comments and Threads. What should a learner take away from it?

      +

      Alex: The reason Step 6: Read Existing Comments and Threads matters is that inline comments from other reviewers appear as h3 headings within the diff table. That gives the learner a simple foothold: each thread shows: reviewer username, comment body, replies, a "Reply" link and resolution button. The interface gets friendlier when it stops being a wall of controls and starts being a set of named places.

      +

      Alex: Treat examples as spoken recipes, not decorations. You may hear something like Tab to the "Resolve conversation" button → Enter. Tab to the "Resolve conversation" button → VO+Space. Read the command, understand what it changes, then run it only when the repository state matches the lesson.

      +

      Jamie: Let's pause on Step 7: Submit Your Review. What should a learner take away from it?

      +

      Alex: Start with Step 7: Submit Your Review: Screen reader users (VoiceOver - macOS).

      +

      Alex: First, click the "Review changes" button (top-right of the Files Changed page or bottom of the PR). Then, a dialog opens with a summary text area and three radio buttons: Comment / Approve / Request changes. After that, optionally type an overall summary in the text area. Finally, select your verdict. Think of it as a rail line: each stop confirms you are still on the right route before the next one.

      +

      Jamie: Before we leave Step 7: Submit Your Review, what is the practical point?

      +

      Alex: First, click "Submit review". Treat it like a recipe: do not add the next ingredient until the previous one is actually in the bowl.

      -

      Jamie: Let's pause on VS Code (Command Palette). What should a learner take away from it?

      -

      Alex: Start with VS Code (Command Palette): Type the tag name (e.g., v1.2.0) and optionally a message.

      -

      Alex: Treat examples as spoken recipes, not decorations. You may hear something like Ctrl+Shift+P → type "git tag" → select "Git: Create Tag". Read the command, understand what it changes, then run it only when the repository state matches the lesson.

      -

      Jamie: Let's pause on GitHub CLI. What should a learner take away from it?

      -

      Alex: Start with GitHub CLI. There is something to understand, something to try, and something that proves the try worked.

      -

      Alex: Treat examples as spoken recipes, not decorations. You may hear something like Create a tag and push it to GitHub in one step (using the API); gh release create v1.2.0 --title "Version 1.2.0" --notes "Bug fixes and accessibility improvements"; This creates both a GitHub Release and the underlying tag. Read the command, understand what it changes, then run it only when the repository state matches the lesson.

      -

      Jamie: If someone only remembers one thing from Git CLI, what should it be?

      -

      Alex: Treat examples as spoken recipes, not decorations. You may hear something like Create a lightweight tag at the current commit; git tag v1.2.0; Create an annotated tag (recommended for releases); git tag -a v1.2.0 -m "Release version 1.2.0 - bug fixes and accessibility improvements"; Tag a specific past commit; git tag -a v1.1.5 a1b2c3d. Read the command, understand what it changes, then run it only when the repository state matches the lesson.

      +

      Jamie: Let's pause on Step 8: Re-request Review (for Authors). What should a learner take away from it?

      +

      Alex: Here is the plain-English version of Step 8: Re-request Review (for Authors). After you address review comments on your own PR. Put another way, look in the right sidebar for the Reviewers section.

      +

      Alex: Treat examples as spoken recipes, not decorations. You may hear something like Step 1: From your PR's Conversation tab, Quick Nav H or VO+Cmd+H to find the "Reviewers" heading in the sidebar; Step 2: Tab or Quick Nav B to find the re-request icon ("Re-request review") next to the reviewer's name; Step 3: VO+Space to activate - this. Read the command, understand what it changes, then run it only when the repository state matches the lesson.

      +

      Jamie: Let's pause on Learning Cards: Reviewing on GitHub.com. What should a learner take away from it?

      +

      Alex: Start with Learning Cards: Reviewing on GitHub.com. There is something to understand, something to try, and something that proves the try worked.

      +

      Alex: The practical takeaway is this. In the Files Changed tab, press T to jump to the diff table, then use Focus Mode (Insert+Space in NVDA, Insert+Z in JAWS) and Down Arrow to read line by line -- each added line starts with + and each removed line with -. To place an inline comment, navigate to the target line and press Tab or B to find the "Add a comment to this line" button; after typing your comment, choose "Start a review" (not "Add single comment") to batch all feedback into one notification. Submit your full review by pressing B repeatedly to find the "Review changes" button; the dialog contains a radio group (Comment / Approve / Request changes) navigable with Arrow keys, then Tab to "Submit review". Switch from split diff to unified diff (gear icon in the Files Changed toolbar then select "Unified") to show old and new code in a single column -- much easier to follow at high zoom than two side-by-side panes. The blue + comment button appears in the line gutter on hover; at high zoom it may be small -- use Ctrl++ to increase browser zoom and look just left of the line number column. The "Review changes" dialog uses clearly labeled radio buttons for the three verdict types; each label includes a brief description, and the currently selected option has a filled circle indicator visible in all themes.

      +

      Alex: Keep the teaching thread moving. Keep the learner anchored in Reviewing in VS Code with the Accessible Diff Viewer. When you check out a branch locally, VS Code's diff editor offers the Accessible Diff Viewer - a purpose-built, line-by-line reading mode designed specifically for screen readers. A good GitHub workflow is like a well-run meeting: everyone knows the topic, the next action, and who has the floor.

      -

      Jamie: Let's pause on Pushing Tags to GitHub. What should a learner take away from it?

      -

      Alex: Keep the learner anchored in Pushing Tags to GitHub. Tags are not pushed automatically when you run git push. A good GitHub workflow is like a well-run meeting: everyone knows the topic, the next action, and who has the floor.

      -

      Alex: Treat examples as spoken recipes, not decorations. You may hear something like Push a specific tag; git push origin v1.2.0; Push all local tags at once; git push origin --tags. Read the command, understand what it changes, then run it only when the repository state matches the lesson.

      -

      Jamie: Let's pause on Deleting a Tag. What should a learner take away from it?

      -

      Alex: Start with Deleting a Tag. There is something to understand, something to try, and something that proves the try worked.

      -

      Alex: Treat examples as spoken recipes, not decorations. You may hear something like Delete a local tag; git tag -d v1.2.0; Delete the tag on GitHub (remote); git push origin --delete v1.2.0. Read the command, understand what it changes, then run it only when the repository state matches the lesson.

      -

      Jamie: Let's pause on 6. Detached HEAD -- What It Is and How to Get Out. What should a learner take away from it?

      -

      Alex: Start with 6. Detached HEAD -- What It Is and How to Get Out: What it is: Normally, you're working on a branch -- Git tracks your commits and moves the branch forward as you commit. The next useful detail is this: A "detached HEAD" happens when you check out a specific commit SHA (or a tag) directly instead of a branch.

      -

      Alex: Treat examples as spoken recipes, not decorations. You may hear something like git checkout a1b2c3d Check out a specific commit; git checkout v1.0.0 Check out a tag. Read the command, understand what it changes, then run it only when the repository state matches the lesson.

      +

      Jamie: Let's pause on Opening a Diff in VS Code. What should a learner take away from it?

      +

      Alex: The reason Opening a Diff in VS Code matters is that if you have the GitHub Pull Requests extension. That gives the learner a simple foothold: without the extension, any git diff operation also opens the diff editor.

      +

      Alex: First, open the GitHub Pull Requests view (Explorer sidebar or Ctrl+Shift+P → "GitHub Pull Requests: View Pull Request"). Then, find the PR and open it - changed files appear in the file tree. After that, navigate to any file in the tree and press Enter to open its diff view. The rhythm is simple: orient, act, verify, then continue.

      +

      Jamie: Let's pause on Learning Cards: VS Code Code Review. What should a learner take away from it?

      +

      Alex: Start with Learning Cards: VS Code Code Review: Low vision users (zoom, high contrast). The next useful detail is this: VS Code's diff editor works well at high zoom.

      +

      Alex: First, split view vs. inline: By default, VS Code shows diffs in a split (side-by-side) view. At high zoom this can be very cramped. Switch to inline mode: Ctrl+Shift+P then type "Toggle Inline View" in any diff editor. Inline mode shows old and new code in a single. Then, colour indicators: Added lines have a green gutter bar; removed lines have a red gutter bar. In high contrast themes, these use heavy solid borders that are visible even at extreme zoom levels. After that, change navigation: Press F7 to jump to the next change and Shift+F7 for the previous. Each change is highlighted with a visible focus box that moves with your position - much easier than scrolling at high zoom. Finally, minimap in diff view: The minimap (right edge) shows an overview of changes as coloured blocks. At high zoom the minimap may be too small to be useful - disable it via Settings if it adds visual noise. Think of it as a rail line: each stop confirms you are still on the right route before the next one.

      +

      Jamie: Before we leave Learning Cards: VS Code Code Review, what is the practical point?

      +

      Alex: First, font size for diffs: Diff editors use your configured editor font size (editor.fontSize). Increase this in Settings (Ctrl+,) if the diff text is too small at your zoom level. Then, comment highlight: When you add a comment through the GitHub PR extension, the commented line gets a distinct background. In high contrast themes this is a solid colour band. Treat it like a recipe: do not add the next ingredient until the previous one is actually in the bowl.

      +

      Jamie: Let's pause on Opening the PR for review. What should a learner take away from it?

      +

      Alex: Start with Opening the PR for review. There is something to understand, something to try, and something that proves the try worked.

      +

      Alex: First, press Ctrl+Shift+P, type "GitHub Pull Requests: View Pull Request". Then, the PR tree appears in the sidebar - navigate with Down Arrow. After that, each changed file is announced with its name and change summary. Finally, press Enter on a file to open its diff editor. Treat it like a recipe: do not add the next ingredient until the previous one is actually in the bowl.

      +

      Jamie: Before we leave Opening the PR for review, what is the practical point?

      +

      Alex: First, the diff editor opens with the standard VS Code diff layout. It is a checklist, but a meaningful one: every item creates evidence that the next step is safe.

      -

      Jamie: Let's pause on If you just want to go back to your branch. What should a learner take away from it?

      -

      Alex: Start with If you just want to go back to your branch. There is something to understand, something to try, and something that proves the try worked.

      -

      Alex: Treat examples as spoken recipes, not decorations. You may hear something like git checkout main; or whatever branch you were on; git switch main. Read the command, understand what it changes, then run it only when the repository state matches the lesson.

      -

      Jamie: Let's pause on If you made commits in detached HEAD and want to keep them. What should a learner take away from it?

      -

      Alex: Start with If you made commits in detached HEAD and want to keep them. There is something to understand, something to try, and something that proves the try worked.

      -

      Alex: Treat examples as spoken recipes, not decorations. You may hear something like Create a new branch at the current (detached) position to save your work; git checkout -b my-experiment; Now you're on a real branch and those commits are safe. Read the command, understand what it changes, then run it only when the repository state matches the lesson.

      -

      Jamie: What stays the same when the tool changes?

      -

      Alex: Keep the learner anchored in VS Code. VS Code shows the current branch name in the bottom-left status bar. This is the part to say slowly: If you're in detached HEAD, it shows something like (HEAD detached at a1b2c3d) instead of a branch name.

      +

      Jamie: Let's pause on Using the Accessible Diff Viewer. What should a learner take away from it?

      +

      Alex: Start with Using the Accessible Diff Viewer. There is something to understand, something to try, and something that proves the try worked.

      +

      Alex: First, in the diff editor, press F7 to open the Accessible Diff Viewer. Then, NVDA announces: "Changed lines X to Y in filename, Change 1 of N". After that, the viewer shows each change with "Removed:" and "Added:" labels. Finally, press F7 to move to the next change, Shift+F7 for previous. It is a checklist, but a meaningful one: every item creates evidence that the next step is safe.

      +

      Jamie: Before we leave Using the Accessible Diff Viewer, what is the practical point?

      +

      Alex: First, press Escape when done to close the viewer. It is like walking a hallway with named doors: read the sign, enter the right room, then confirm where you landed.

      +

      Jamie: Let's pause on Placing a comment. What should a learner take away from it?

      +

      Alex: Keep the learner anchored in Placing a comment. Screen reader users (VoiceOver on macOS).

      +

      Alex: First, navigate to the line you want to comment on in the diff. Then, press Ctrl+Shift+P, type "GitHub Pull Requests: Add Comment". After that, a text area opens below the line - NVDA announces the input focus. Finally, type your comment. It is like walking a hallway with named doors: read the sign, enter the right room, then confirm where you landed.

      +

      Jamie: Before we leave Placing a comment, what is the practical point?

      +

      Alex: First, press Tab to the Submit button, then Enter. The rhythm is simple: orient, act, verify, then continue.

      +

      Jamie: Let's pause on Opening the PR. What should a learner take away from it?

      +

      Alex: Start with Opening the PR. There is something to understand, something to try, and something that proves the try worked.

      +

      Alex: First, press Cmd+Shift+P, type "GitHub Pull Requests: View Pull Request". Then, navigate the PR tree with VO+Down Arrow. After that, press Return on a file to open its diff. The rhythm is simple: orient, act, verify, then continue.

      -

      Alex: Before the learner moves on. The reason 7. Force Pushing Safely matters is that what it is: After you rebase or amend commits that have already been pushed, the remote branch has a different history than your local branch. That gives the learner a simple foothold: a regular git push will fail because Git sees them as diverged.

      -

      Jamie: Let's pause on --force-with-lease vs --force. What should a learner take away from it?

      -

      Alex: Start with --force-with-lease vs --force: Always use --force-with-lease instead of --force.

      -

      Alex: This is the part worth saying out loud. Start with When You'd Use It. There is something to understand, something to try, and something that proves the try worked.

      -

      Alex: For a learner, the useful signals are these. You rebased a feature branch to squash commits before a PR review. You amended the last commit with git commit --amend after already pushing. A reviewer asked you to rebase onto main and you've now done.

      +

      Jamie: Let's pause on Accessible Diff Viewer. What should a learner take away from it?

      +

      Alex: Start with Accessible Diff Viewer. There is something to understand, something to try, and something that proves the try worked.

      +

      Alex: First, press F7 in the diff editor. Then, VoiceOver announces each change with clear "Removed" and "Added" labels. After that, navigate with F7/Shift+F7. Finally, press Escape to close. Think of it as a rail line: each stop confirms you are still on the right route before the next one.

      +

      Jamie: Let's pause on Comment placement. What should a learner take away from it?

      +

      Alex: Start with Comment placement. There is something to understand, something to try, and something that proves the try worked.

      +

      Alex: First, press Cmd+Shift+P, type "GitHub Pull Requests: Add Comment". Then, vO+Shift+Down Arrow to interact with the comment text area. After that, type your comment. Finally, vO+Shift+Up Arrow to stop interacting, then Tab to Submit. Treat it like a recipe: do not add the next ingredient until the previous one is actually in the bowl.

      +

      Jamie: Let's pause on Using the Accessible Diff Viewer (F7). What should a learner take away from it?

      +

      Alex: This is where Using the Accessible Diff Viewer (F7) becomes real: the Accessible Diff Viewer reads each change as a structured block. That matters in practice: This example is from a real Learning Room scenario: a contributor fixing the heading hierarchy in docs/keyboard-shortcuts.md by changing a level-4 heading to level-3, which is exactly what you look for when reviewing Challenge 2 PRs.

      +

      Alex: Treat examples as spoken recipes, not decorations. You may hear something like "Changed lines 14 to 14 in docs/keyboard-shortcuts.md; [Change 1 of 3]; Removed:; NVDA Single-Key Navigation; Added:; NVDA Single-Key Navigation". Read the command, understand what it changes, then run it only when the repository state matches the lesson.

      -

      Jamie: Before we leave VS Code, what is the practical point?

      -

      Alex: This is where VS Code becomes real: VS Code doesn't have a "force push" button in the UI -- this is intentional to prevent accidents.

      -

      Alex: Treat examples as spoken recipes, not decorations. You may hear something like Ctrl+Backtick → then type the command below. Read the command, understand what it changes, then run it only when the repository state matches the lesson.

      -

      Jamie: Before we leave GitHub CLI, what is the practical point?

      -

      Alex: Treat examples as spoken recipes, not decorations. You may hear something like Force push your current branch; gh repo sync This is for syncing FROM remote, not for force pushing; For force pushing, use git directly:; git push --force-with-lease origin your-branch-name. Read the command, understand what it changes, then run it only when the repository state matches the lesson.

      -

      Jamie: Let's pause on Git CLI. What should a learner take away from it?

      -

      Alex: Treat examples as spoken recipes, not decorations. You may hear something like Safe force push -- fails if someone else pushed since your last fetch; git push --force-with-lease origin feature/my-branch; Check what will happen before pushing; git push --force-with-lease --dry-run origin feature/my-branch; Unconditional force push (avoid. Read the command, understand what it changes, then run it only when the repository state matches the lesson.

      +

      Alex: Keep the teaching thread moving. Start with Navigation. There is something to understand, something to try, and something that proves the try worked.

      +

      Alex: The practical takeaway is this. F7 - jump to next change (next hunk). Shift+F7 - jump to previous change. Alt+F2 - open VS Code's Accessible View for additional context on the current item. Escape - close the Accessible Diff Viewer.

      +

      Jamie: Let's pause on What makes this better than the raw diff editor. What should a learner take away from it?

      +

      Alex: Start with What makes this better than the raw diff editor. There is something to understand, something to try, and something that proves the try worked.

      +

      Alex: The practical takeaway is this. Each change is announced as a discrete unit with clear "Removed:" and "Added:" labels. You hear the change number of total changes ("Change 3 of 12"). No table navigation required - purpose-built for sequential listening. Works with all three major screen readers without any special configuration.

      +

      Alex: Keep the teaching thread moving. Start with Placing Comments in VS Code (GitHub PR Extension): From the diff editor with the GitHub PR extension. The next useful detail is this: Comments placed in VS Code sync to GitHub - they appear in the PR's Files Changed tab and the author receives the same notification. Think of it like entering a new building: first you find the lobby, then the room, then the door you actually need.

      -

      Jamie: Let's pause on The Typical Rebase + Force Push Workflow. What should a learner take away from it?

      -

      Alex: Start with The Typical Rebase + Force Push Workflow. There is something to understand, something to try, and something that proves the try worked.

      -

      Alex: Treat examples as spoken recipes, not decorations. You may hear something like You're on your feature branch -- rebase onto main to get latest changes; git fetch origin; git rebase origin/main; 2. Resolve any conflicts, then continue; git rebase --continue; 3. Force push your rebased branch (origin already has the old version); git push. Read the command, understand what it changes, then run it only when the repository state matches the lesson.

      -

      Jamie: Let's pause on 8. git bisect -- Finding the Commit That Broke Things. What should a learner take away from it?

      -

      Alex: Here is the plain-English version of 8. git bisect -- Finding the Commit That Broke Things. What it is: git bisect performs a binary search through your commit history to find exactly which commit introduced a bug. Put another way, instead of checking 100 commits one by one, Git cuts the search in half each time -- usually finding the culprit in 7-10 steps.

      -

      Alex: Here is what that changes in practice. "This was working last week, now it's broken -- what changed?". You need to find the exact commit so you can revert or fix it. A test that used to pass now fails and you don't know why.

      -

      Jamie: Let's pause on Starting a Bisect Session. What should a learner take away from it?

      -

      Alex: This is where Starting a Bisect Session becomes real: Git now checks out a commit in the middle of your history. That matters in practice: Test your code -- does the bug exist here?

      -

      Alex: Treat examples as spoken recipes, not decorations. You may hear something like Start bisect mode; git bisect start; 2. Mark the current commit as bad (broken); git bisect bad; 3. Mark a commit you know was good (working); Use a tag, SHA, or branch name from before the problem started; git bisect good v1.0.0; or; git bisect good a1b2c3d. If the bug IS present at this commit; git bisect bad; If the bug is NOT present at this commit; git bisect good. Read the command, understand what it changes, then run it only when the repository state matches the lesson.

      +

      Jamie: Let's pause on The Anatomy of a Useful Review Comment. What should a learner take away from it?

      +

      Alex: Here is the plain-English version of The Anatomy of a Useful Review Comment. A comment that helps the author is.

      +

      Alex: First, specific - link to the exact line and name the pattern you see. Then, educational - say why something matters, not just what to change. After that, graduated - signal whether this is blocking, or a preference. Treat it like a recipe: do not add the next ingredient until the previous one is actually in the bowl.

      +

      Alex: Keep the teaching thread moving. This is where Blocking example (reviewing a PR for docs/keyboard-shortcuts.md) becomes real: "The heading on line 34 uses (level 4) directly after (level 2), skipping heading level 3. That matters in practice: Screen reader users who navigate by heading level will miss any content between those two levels.

      +

      Jamie: Let's pause on Non-blocking (nit) example (reviewing a PR for docs/welcome.md). What should a learner take away from it?

      +

      Alex: Keep the learner anchored in Non-blocking (nit) example (reviewing a PR for docs/welcome.md). "nit: The link text in the 'Getting Help' section reads 'click here for more information.' Screen reader users who navigate links out of context will hear only 'click here' with no destination. This is the part to say slowly: Consider 'See the accessibility setup guide' instead.

      -

      Jamie: Let's pause on Finishing. What should a learner take away from it?

      -

      Alex: Start with Finishing. There is something to understand, something to try, and something that proves the try worked.

      -

      Alex: Treat examples as spoken recipes, not decorations. You may hear something like End the bisect session and return to your original branch; git bisect reset. Read the command, understand what it changes, then run it only when the repository state matches the lesson.

      -

      Jamie: Let's pause on Automating Bisect with a Test Script. What should a learner take away from it?

      -

      Alex: The reason Automating Bisect with a Test Script matters is that if you have a test command that exits with code 0 on success and non-zero on failure, Git can run bisect automatically. That gives the learner a simple foothold: bisect output is plain text -- each step tells you exactly where it checked out and how many steps remain. The interface gets friendlier when it stops being a wall of controls and starts being a set of named places.

      -

      Alex: Treat examples as spoken recipes, not decorations. You may hear something like git bisect start; git bisect bad HEAD; git bisect good v1.0.0; Run automatically -- git runs your test script at each step; git bisect run npm test; or; git bisect run python -m pytest tests/test auth.py. Read the command, understand what it changes, then run it only when the repository state matches the lesson.

      -

      Jamie: Let's pause on 9. git clean -- Clearing Out Untracked Files. What should a learner take away from it?

      -

      Alex: Start with 9. git clean -- Clearing Out Untracked Files: What it is: git clean removes untracked files and directories from your working directory -- files that Git doesn't know about yet (not staged, not committed, not in.gitignore). The next useful detail is this: This is useful when you have build artifacts, generated files, or experimental files cluttering your project.

      -

      Alex: The parts worth keeping in working memory are these. After a build that left temporary files everywhere. You want a completely fresh state matching the last commit. Clearing out generated files before running a clean build.

      +

      Alex: Keep the teaching thread moving. The reason Question example (reviewing a PR for docs/setup-guide.md) matters is that "The PR description says this fixes broken links in the setup guide, but the link on line 12 still points to /docs/old-setup. That gives the learner a simple foothold: am I reading the diff correctly, or was this link intentionally left? The interface gets friendlier when it stops being a wall of controls and starts being a set of named places.

      +

      Jamie: Let's pause on Prefixes That Set Expectations. What should a learner take away from it?

      +

      Alex: Start with Prefixes That Set Expectations: Using shorthand prefixes helps authors parse many comments quickly.

      +

      Alex: Keep the teaching thread moving. Here is the plain-English version of How Many Comments Is Too Many? There is no hard limit, but quantity without prioritization is noise. Put another way, if you have 15 comments, make clear which 2-3 are blocking.

      -

      Jamie: Let's pause on Always Dry-Run First. What should a learner take away from it?

      -

      Alex: Start with Always Dry-Run First. There is something to understand, something to try, and something that proves the try worked.

      -

      Alex: Treat examples as spoken recipes, not decorations. You may hear something like See what WOULD be deleted without actually deleting anything; git clean -n; or equivalently; git clean --dry-run. Read the command, understand what it changes, then run it only when the repository state matches the lesson.

      -

      Jamie: What is the teaching move inside VS Code?

      -

      Alex: This is where VS Code becomes real: VS Code's Source Control panel shows untracked files in the "Changes" section. That matters in practice: For bulk removal, use the terminal (see Git CLI below).

      -

      Alex: First, open Source Control: Ctrl+Shift+G. Then, right-click an untracked file. After that, select "Discard Changes" -- this removes new untracked files. It is a checklist, but a meaningful one: every item creates evidence that the next step is safe.

      -

      Jamie: Let's pause on Git CLI. What should a learner take away from it?

      -

      Alex: Treat examples as spoken recipes, not decorations. You may hear something like Dry run -- see what would be removed; git clean -n; Remove untracked files (NOT directories); git clean -f; Remove untracked files AND directories; git clean -fd; Remove untracked files AND ignored files (be careful -- removes build artifacts AND things. Read the command, understand what it changes, then run it only when the repository state matches the lesson.

      +

      Jamie: Let's pause on "I want to verify the PR only changes what it claims". What should a learner take away from it?

      +

      Alex: This is where "I want to verify the PR only changes what it claims" becomes real: example: A PR says "Challenge 2: Add NVDA shortcut" but the file tree shows changes to both docs/keyboard-shortcuts.md and docs/welcome.md.

      +

      Alex: Keep the teaching thread moving. Keep the learner anchored in "I want to find all changes to one specific section". Example: A PR for Challenge 3 modified docs/welcome.md. This is the part to say slowly: You want to verify the [TODO] in the "Who Can Contribute?" section was filled in correctly. A good GitHub workflow is like a well-run meeting: everyone knows the topic, the next action, and who has the floor.

      +

      Jamie: Why is the evidence prompt part of the teaching, not just grading?

      +

      Alex: The reason Exercises matters is that these exercises use the files in learning-room/docs/ in this repository. That gives the learner a simple foothold: all examples involve documentation changes - no code required.

      -

      Jamie: Let's pause on 10. Branch Protection -- Why Your Push or Merge May Be Blocked. What should a learner take away from it?

      -

      Alex: The reason 10. Branch Protection -- Why Your Push or Merge May Be Blocked matters is that what it is: Branch protection rules are settings a repository administrator applies to specific branches (usually main or release branches). That gives the learner a simple foothold: they prevent direct pushes, require pull requests, require approvals before merging, and enforce status checks passing.

      -

      Jamie: Let's pause on The Correct Flow for Protected Branches. What should a learner take away from it?

      -

      Alex: Start with The Correct Flow for Protected Branches. There is something to understand, something to try, and something that proves the try worked.

      -

      Alex: Treat examples as spoken recipes, not decorations. You may hear something like Never push directly to main -- always work on a branch; git checkout -b feature/my-change; 2. Make your changes, commit them; git add.; git commit -m "Add screen reader support to navigation"; 3. Push your branch (not main); git push origin feature/my-change. Read the command, understand what it changes, then run it only when the repository state matches the lesson.

      -

      Jamie: Let's pause on Updating a Branch That's Out of Date. What should a learner take away from it?

      -

      Alex: Here is the plain-English version of Updating a Branch That's Out of Date. When GitHub says your branch is out of date with main.

      +

      Alex: Keep the teaching thread moving. Start with Exercise A - Complete a Web Review: Scenario: A contributor has submitted a pull request titled "Add screen reader tips to the setup guide." The PR modifies learning-room/docs/setup-guide.md. The next useful detail is this: Your job is to review it before it merges.

      +

      Jamie: Let's pause on Step 1: Navigate to the Pull Request. What should a learner take away from it?

      +

      Alex: Here is the plain-English version of Step 1: Navigate to the Pull Request. How to know you're in the right place.

      +

      Alex: The practical takeaway is this. The PR title is visible at the top. You see a description box with text about what this PR does. You see tabs labeled "Conversation," "Commits," "Files Changed". Use Ctrl+F to search the PR list for "screen reader tips". Or ask in the workshop Slack - someone can share the exact URL.

      +

      Alex: First, open GitHub in your browser and navigate to the workshop repository (github.com/[your-fork]/[workshop-repo] or community-access/accessibility-agents). Then, click the Pull Requests tab (top navigation). After that, look for a PR titled "Add screen reader tips to the setup guide" - click it to open. Finally, you should now see the PR page with sections: Conversation, Commits, Files Changed. Treat it like a recipe: do not add the next ingredient until the previous one is actually in the bowl.

      +

      Jamie: Let's pause on Step 2: Read the PR Description. What should a learner take away from it?

      +

      Alex: Start with Step 2: Read the PR Description. There is something to understand, something to try, and something that proves the try worked.

      +

      Alex: The practical takeaway is this. Does the PR author explain what file changed? (should mention setup-guide.md). Does it explain why? (should mention "improve accessibility" or "add tips"). Is it clear enough that a reviewer can understand the goal without reading the diff? You can answer: "This PR adds [specific content] to [specific file] because [clear reason]". Example: "This PR adds screen reader usage tips to the setup guide because new users need accessibility guidance".

      +

      Alex: First, you are currently on the Conversation tab. Then, read the PR description (the text immediately under the PR title). After that, look for: "What does this PR change?" and "Why does it change it?". Finally, with screen reader: Navigate to the description with D (NVDA) or press Ctrl+Option+Up (VoiceOver) to find main landmarks, then read the content region. It is a checklist, but a meaningful one: every item creates evidence that the next step is safe.

      -

      Jamie: If someone only remembers one thing from VS Code, what should it be?

      -

      Alex: First, open Source Control → Ctrl+Shift+P. Then, type "merge" → select "Git: Merge Branch.". After that, choose origin/main from the list. Finally, resolve any conflicts, then push again. It is a checklist, but a meaningful one: every item creates evidence that the next step is safe.

      -

      Jamie: Let's pause on Git CLI. What should a learner take away from it?

      -

      Alex: Treat examples as spoken recipes, not decorations. You may hear something like Option A: Merge main into your branch (creates a merge commit); git fetch origin; git merge origin/main; Option B: Rebase onto main (cleaner history, requires force push after); git fetch origin; git rebase origin/main; git push --force-with-lease origin. Read the command, understand what it changes, then run it only when the repository state matches the lesson.

      -

      Jamie: What is the teaching move inside GitHub CLI?

      -

      Alex: Treat examples as spoken recipes, not decorations. You may hear something like Update your PR branch from the GitHub UI via CLI; gh pr update-branch --rebase; or; gh pr update-branch uses merge by default. Read the command, understand what it changes, then run it only when the repository state matches the lesson.

      +

      Jamie: Let's pause on Step 3: Navigate to "Files Changed". What should a learner take away from it?

      +

      Alex: Start with Step 3: Navigate to "Files Changed". There is something to understand, something to try, and something that proves the try worked.

      +

      Alex: The practical takeaway is this. A section showing the file name setup-guide.md with a small badge showing "+20 −0" (20 lines added, 0 lines removed). Below it, the diff with removed lines (preceded by −) and added lines (preceded by +). Scroll up to see if there are other files. For this exercise, only setup-guide.md should be changed. If you see other files, confirm they are not modified (the badge should show "+0 −0" or no changes).

      +

      Alex: First, click the Files Changed tab (top of the PR page, to the right of "Commits"). Then, you are now viewing the diff. After that, with keyboard (all screen readers): Press T to jump to the diff table. The page focuses on the file comparison area. It is like walking a hallway with named doors: read the sign, enter the right room, then confirm where you landed.

      +

      Jamie: Let's pause on Step 4: Activate Focus Mode for Better Diff Reading. What should a learner take away from it?

      +

      Alex: The reason Step 4: Activate Focus Mode for Better Diff Reading matters is that with screen reader (once in Focus Mode).

      +

      Alex: The practical takeaway is this. The page simplifies: sidebars disappear. Only the diff is visible - easier for screen reader navigation and less cognitive load. The diff is now the main content area. NVDA/JAWS: Press T to jump to the diff table. VoiceOver: Navigate with VO+Right Arrow to find the table/content region. Read through the changes: ↓ arrow moves to each line.

      +

      Alex: First, look for a button labeled "Focus Mode" or an icon (usually at the top right of the diff area). Then, with keyboard: Press F to toggle Focus Mode (may need to be in the diff area first). After that, with mouse: Click the Focus Mode button/icon. The rhythm is simple: orient, act, verify, then continue.

      +

      Jamie: Let's pause on Step 5: Find the Heading Hierarchy Issue. What should a learner take away from it?

      +

      Alex: Start with Step 5: Find the Heading Hierarchy Issue. There is something to understand, something to try, and something that proves the try worked.

      +

      Alex: The practical takeaway is this. Screen reader users navigate documents by heading level: 1 → 2 → 3 → 4. A skip from to breaks that navigation. When a user presses "jump to heading level 3," they'll find none, wondering if content is missing. You found the line with that violates hierarchy. You can say the line number and what heading text appears there. You understand why this is an accessibility problem.

      +

      Alex: First, read through the entire diff line by line. Pay special attention to lines starting. Then, you are looking for: a line with (four hashes, heading level 4) that comes directly after a (two hashes, heading level 2). After that, when you find it, note the exact line number shown in the diff. Think of it as a rail line: each stop confirms you are still on the right route before the next one.

      -

      Jamie: If someone only remembers one thing from GitHub CLI, what should it be?

      -

      Alex: Treat examples as spoken recipes, not decorations. You may hear something like View branch protection rules for main; gh api repos/{owner}/{repo}/branches/main/protection --jq '{; required reviews.required pull request reviews.required approving review count,; require status checks.required status checks.contexts,; enforce. Read the command, understand what it changes, then run it only when the repository state matches the lesson.

      -

      Alex: Hold that next to this. Here is the plain-English version of On GitHub.com. Navigate to Settings → Branches in the repository. Put another way, (You need admin access to see the full config; contributors can see the effect through blocked PRs and the merge box status.). It is like learning a transit route. The names of the stops matter because they tell you whether you are still going the right direction.

      -

      Jamie: Let's pause on Learning Cards: Quick Reference Table. What should a learner take away from it?

      -

      Alex: Start with Learning Cards: Quick Reference Table. There is something to understand, something to try, and something that proves the try worked.

      -

      Alex: These are the details that keep the idea from floating away. This table has four columns: Task, VS Code, Git CLI, and GitHub CLI -- column headers are announced on entry. Use Ctrl+Alt+Arrow keys to navigate cells; the Task column on the left identifies each row. Cells with a dash (--) mean that tool does not support the operation -- move right to try another column. At high zoom the table may scroll horizontally -- use Shift+scroll or arrow keys to see all four columns. The Task column is always the leftmost -- anchor your reading from there. Consider copying this table into a text file or spreadsheet for easier viewing at your preferred zoom.

      +

      Jamie: Let's pause on Step 6: Place a Blocking Review Comment on the Heading. What should a learner take away from it?

      +

      Alex: Here is the plain-English version of Step 6: Place a Blocking Review Comment on the Heading. If the comment button doesn't appear. It is like learning a transit route. The names of the stops matter because they tell you whether you are still going the right direction.

      +

      Alex: The practical takeaway is this. Your comment appears in the thread under that line. The PR author sees it and can make the fix. Make sure you're hovering over the line number area (left side of the line). Try refreshing the page and trying again. Or use the "Add a reply" field at the bottom of the PR and mention the line number manually.

      +

      Alex: First, find the diff line with the problematic heading. Then, hover your mouse over the line number on the left side of that line (or if using keyboard, navigate to that line in the table). After that, a button should appear (or press the Add Comment hotkey - usually C in GitHub). Finally, click it or press Enter to open a comment box. Treat it like a recipe: do not add the next ingredient until the previous one is actually in the bowl.

      +

      Jamie: Before we leave Step 6: Place a Blocking Review Comment on the Heading, what is the practical point?

      +

      Alex: First, press Space, then explain. Then, click the Comment button (or press Ctrl+Enter for keyboard submit). It is a checklist, but a meaningful one: every item creates evidence that the next step is safe.

      +

      Jamie: Let's pause on Step 7: Find the Link Text Issue. What should a learner take away from it?

      +

      Alex: Start with Step 7: Find the Link Text Issue. There is something to understand, something to try, and something that proves the try worked.

      +

      Alex: The practical takeaway is this. Screen reader users can ask their reader to "list all links on this page" - they hear only the link text. If the text is "click here," they have no context about where it goes. Descriptive link text is WCAG 2.4.4 (Link Purpose). You found a link with non-descriptive text. You can explain why "click here" is bad and what would be better.

      +

      Alex: First, continue reading the diff (from where you left off). Then, look for a line containing link text that reads "click here" or "click here for more information". After that, note the line number. It is a checklist, but a meaningful one: every item creates evidence that the next step is safe.

      +

      Jamie: Let's pause on Step 8: Place a Comment on the Link. What should a learner take away from it?

      +

      Alex: Keep the learner anchored in Step 8: Place a Comment on the Link. nit: means "nice-to-have improvement" (not blocking, but good to fix).

      +

      Alex: First, find the line in the diff with the problematic link. Then, hover over the line number and click to open a comment box (or press C). After that, click Comment or press Ctrl+Enter. It is like walking a hallway with named doors: read the sign, enter the right room, then confirm where you landed.

      -

      Alex: Keep the teaching thread moving. Keep the learner anchored in 11. Using GitHub Copilot for Git Operations. GitHub Copilot isn't just for writing code -- it's genuinely useful for Git operations, especially when you're doing something unfamiliar, hit a conflict, or need to understand what a command did. This is the part to say slowly: Here's how to use it across the advanced operations in this appendix.

      -

      Jamie: Let's pause on Resolving Merge Conflicts. What should a learner take away from it?

      -

      Alex: The reason Resolving Merge Conflicts matters is that when a cherry-pick, rebase, or branch merge stops due to a conflict, VS Code highlights the conflict regions. That gives the learner a simple foothold: place your cursor inside a conflict block and ask Copilot.

      -

      Alex: The practical takeaway is this. "Resolve this merge conflict. Keep meaningful changes from both sides.". "Explain what each side of this conflict is trying to do.". "Which version of this change should I keep, and why?".

      -

      Alex: Keep the teaching thread moving. Start with Writing Better Commit Messages: Copilot is excellent at turning "WIP: stuff" into a clear, conventional commit message. The next useful detail is this: Open Copilot Chat after staging your changes and try. Think of it like entering a new building: first you find the lobby, then the room, then the door you actually need.

      -

      Alex: The practical takeaway is this. "Write a conventional commit message for these changes." (Copilot can see open files). "I changed the navigation component to add keyboard focus indicators. Write a commit message.". "Here are my last 5 WIP commit messages: [paste them]. Write one clean message that summarizes all of them.".

      +

      Jamie: Let's pause on Step 9: Submit Your Review. What should a learner take away from it?

      +

      Alex: Start with Step 9: Submit Your Review. There is something to understand, something to try, and something that proves the try worked.

      +

      Alex: The practical takeaway is this. Comment - provide feedback but don't block (for minor notes). Approve - the PR is ready to merge. Request changes - this PR cannot merge until changes are made. Your review is submitted. The PR author gets a notification. The PR shows your review with the two comments.

      +

      Alex: First, look for a button labeled "Review changes" (usually at the top right of the page or bottom of comments). Then, click it (or navigate with keyboard and press Enter). After that, a dialog appears with options. Finally, select "Request changes" (you found two things to fix). The rhythm is simple: orient, act, verify, then continue.

      +

      Jamie: Before we leave Step 9: Submit Your Review, what is the practical point?

      +

      Alex: First, in the summary field, write: Found 2 accessibility issues that must be fixed before merging. Then, click "Submit review". Think of it as a rail line: each stop confirms you are still on the right route before the next one.

      +

      Jamie: Let's pause on Reflect on This Exercise. What should a learner take away from it?

      +

      Alex: Start with Reflect on This Exercise: Keep your answers - you'll need them for Chapter 16's Accessibility Agents exercise to compare manual review with agent-assisted review. Think of it like entering a new building: first you find the lobby, then the room, then the door you actually need.

      +

      Alex: First, did heading-level navigation help? When you were looking for the issue, was it easier to navigate by heading level (1-6) than to scan every line? Then, would you have caught this without the exercise prompt? If you were a real reviewer not specifically looking for heading issues, would the diff have been obvious? After that, why does screen reader navigation matter? In one sentence, explain why a screen reader user's ability to jump through heading levels is important for this document. Think of it as a rail line: each stop confirms you are still on the right route before the next one.

      +

      Jamie: What stays the same when the tool changes?

      +

      Alex: Here is the plain-English version of Exercise B - Use the VS Code Accessible Diff Viewer. Scenario: Review the same pull request from Exercise A, this time entirely in VS Code. Put another way, you'll compare the browser experience with the VS Code experience.

      -

      Jamie: Let's pause on Understanding Confusing Git Output. What should a learner take away from it?

      -

      Alex: Here is the plain-English version of Understanding Confusing Git Output. Git's error messages and status output can be cryptic. Put another way, paste them directly into Copilot Chat.

      -

      Alex: The practical takeaway is this. "I got this git error message: [paste it]. What does it mean and how do I fix it?". "My git status output looks like this: [paste it]. What happened and what should I do next?". "I accidentally ran git reset --hard. What are my options for recovering my changes?".

      -

      Alex: Keep the teaching thread moving. This is where Choosing the Right Command becomes real: when you're not sure which git command to reach for, describe what you want to do.

      -

      Alex: The practical takeaway is this. "I committed a fix on my feature branch but main also needs it urgently. What's the right git command to use?" → Copilot will suggest cherry-pick. "I have 6 messy commits on my PR branch before I open the PR. How do I clean them up?" → Interactive rebase with squash. "I pushed a commit that broke CI and I need to undo it without force-pushing." → git revert. "My PR branch hasn't been updated from main in two weeks. How do I bring it up to date?" → fetch + rebase or merge.

      -

      Jamie: Let's pause on Debugging a Failing Bisect. What should a learner take away from it?

      -

      Alex: Keep the learner anchored in Debugging a Failing Bisect. When git bisect lands on a commit and you're not sure what to test.

      -

      Alex: The practical takeaway is this. "I'm running git bisect to find a bug. Git just checked out commit a1b2c3d. Here's the diff: [paste git show a1b2c3d]. What changed in this commit and what should I test?".

      +

      Alex: Keep the teaching thread moving. Start with Prerequisites. There is something to understand, something to try, and something that proves the try worked.

      +

      Alex: The practical takeaway is this. VS Code must be installed on your machine. The GitHub Pull Requests extension must be installed (see Chapter 12 for installation). You must be signed into GitHub from VS Code (use Ctrl+Shift+P → "GitHub: Sign in").

      +

      Jamie: Let's pause on Step 1: Open the GitHub Pull Requests Extension. What should a learner take away from it?

      +

      Alex: Start with Step 1: Open the GitHub Pull Requests Extension. There is something to understand, something to try, and something that proves the try worked.

      +

      Alex: The practical takeaway is this. With mouse: Click the Extensions icon on the left sidebar (looks like four squares). The extension is listed as active. It mentions: "Review and manage GitHub pull requests and issues".

      +

      Alex: First, open VS Code. Then, with keyboard (all screen readers): Press Ctrl+Shift+X to open the Extensions sidebar. After that, search for "GitHub Pull Requests". Finally, if it's not installed, click Install. It is like walking a hallway with named doors: read the sign, enter the right room, then confirm where you landed.

      +

      Jamie: Before we leave Step 1: Open the GitHub Pull Requests Extension, what is the practical point?

      +

      Alex: First, if it is installed, click GitHub Pull Requests to view its details. The rhythm is simple: orient, act, verify, then continue.

      +

      Jamie: Let's pause on Step 2: Open the Pull Requests Sidebar. What should a learner take away from it?

      +

      Alex: Start with Step 2: Open the Pull Requests Sidebar. There is something to understand, something to try, and something that proves the try worked.

      +

      Alex: The practical takeaway is this. With keyboard: The icon may not be keyboard-reachable directly; instead go to Step 3. VS Code opens a new editor tab for this PR. Below the PR title, you see a "Changes" section listing modified files. You should see setup-guide.md in the changes list. Use Ctrl+Shift+P → search GitHub Pull Requests: Open Pull Request. Paste the PR URL: https://github.com/[owner]/[repo]/pull/[number].

      +

      Alex: First, look for a GitHub-themed icon on the left sidebar (circle with octocat logo) - click it. Then, a sidebar appears showing open pull requests on repositories you have access to. After that, find the PR titled "Add screen reader tips to the setup guide" - it should appear in a list. Finally, click it to open. The rhythm is simple: orient, act, verify, then continue.

      -

      Alex: Keep the teaching thread moving. The reason Getting Help With Branch Protection Errors matters is that paste the full error message from a rejected push into Copilot. The interface gets friendlier when it stops being a wall of controls and starts being a set of named places.

      -

      Alex: The practical takeaway is this. "I got this error when pushing to my repository: [paste error]. What does it mean and what do I do?". "My PR can't merge because of a required status check. Here's the check output: [paste it]. What's wrong?".

      -

      Jamie: Let's pause on GitHub Copilot CLI -- Git Command Suggestions. What should a learner take away from it?

      -

      Alex: Start with GitHub Copilot CLI -- Git Command Suggestions: If you have the GitHub CLI with Copilot extension installed, you can ask for git commands directly in the terminal. The next useful detail is this: Copilot CLI explains the command before running it and asks for confirmation -- great for learning while doing.

      -

      Alex: Treat examples as spoken recipes, not decorations. You may hear something like Ask Copilot to suggest a git command for what you want to do; gh copilot suggest "squash my last 4 commits into one"; gh copilot suggest "undo my last commit but keep the changes"; gh copilot suggest "find which commit broke the login tests". Read the command, understand what it changes, then run it only when the repository state matches the lesson.

      +

      Jamie: Let's pause on Step 3: View the File Changes. What should a learner take away from it?

      +

      Alex: Start with Step 3: View the File Changes. There is something to understand, something to try, and something that proves the try worked.

      +

      Alex: The practical takeaway is this. A diff editor opens showing two columns. Left: the original file (before changes). Right: the new file (after changes). Different colors show added (green), removed (red), and modified (blue) lines. The file name appears at the top: setup-guide.md. NVDA/JAWS: The editor announces "Diff Editor - setup-guide.md".

      +

      Alex: First, in the Changes section, locate setup-guide.md. Then, click on the filename to open it. Think of it as a rail line: each stop confirms you are still on the right route before the next one.

      +

      Jamie: Let's pause on Step 4: Access the Accessible Diff Viewer. What should a learner take away from it?

      +

      Alex: Here is the plain-English version of Step 4: Access the Accessible Diff Viewer. If the Accessible Diff Viewer doesn't open.

      +

      Alex: The practical takeaway is this. With mouse: Look for a button or menu option labeled "Accessible View" or "Open Accessible Diff". If no button is visible, try Alt+F2 (VS Code Accessible View toggle). A new panel opens at the bottom of VS Code. The panel announces each change one at a time. Changes appear in text format with labels: "Added: " and "Removed: ". The panel is read-only (you read the changes, you don't edit here).

      +

      Alex: First, with keyboard: Press F7 to open the Accessible Diff Viewer. Treat it like a recipe: do not add the next ingredient until the previous one is actually in the bowl.

      +

      Jamie: Let's pause on Step 5: Listen to and Understand the First Change. What should a learner take away from it?

      +

      Alex: Start with Step 5: Listen to and Understand the First Change. There is something to understand, something to try, and something that proves the try worked.

      +

      Alex: The practical takeaway is this. NVDA/JAWS: The Accessible Diff Viewer announces "Removed:" and "Added:" labels, followed by the line content. VoiceOver: The announcement may be similar; listen for "removed" and "added" keywords.

      +

      Alex: First, the first change is automatically announced when you open the Accessible Diff Viewer. Then, let your screen reader read it completely - don't interrupt. After that, write down the exact text announced. Finally, press the Down arrow to move to the next change. It is a checklist, but a meaningful one: every item creates evidence that the next step is safe.

      -

      Jamie: What should people carry with them after this?

      -

      Alex: Carry the map. Know what page or tool you are in, know which action you are taking, and know what confirmation should follow. If the confirmation is missing, pause. That pause is not wasted time; it is professional judgment.

      -

      Jamie: That is a better way to say it than just follow the steps.

      -

      Alex: Right. Steps matter, but understanding wins. That is episode 50. Next in the series is episode 51, where we keep building the same contributor muscles.

      -
      - -
      -

      Episode 51: Git Security for Contributors

      -

      Secrets, .gitignore, environment variables, push protection, and safe contributor habits.

      -

      Based on: Appendix F: Git Security for Contributors

      -

      Audio and transcript are being regenerated for this episode.

      -
      -Read Transcript - Episode 51: Git Security for Contributors - -

      Transcript

      -

      Alex: Welcome to episode 51 of Git Going with GitHub: Git Security for Contributors. I am Alex, and today we are teaching this topic as a conversation you can carry into the workshop, not as a page you have to memorize.

      -

      Jamie: And I am Jamie. I will keep pulling the lesson back to real learners, real repositories, and the evidence that proves the work happened.

      -
      -

      Alex: The lesson focus is Secrets,.gitignore, environment variables, push protection, and safe contributor habits. We will treat every step as a teachable decision, because that is what makes the skill portable.

      -

      Jamie: So we should explain the why clearly enough that the steps make sense when the learner meets them later.

      -

      Alex: That is it. If a listener only has audio right now, they should still get the complete concept and know what evidence would prove success.

      -
      -

      Jamie: Okay, set the room for us. What are we walking into?

      -

      Alex: Start with Keeping Secrets Out of Your Repository: Who this is for: Anyone committing code or documentation to a repository. The next useful detail is this: You don't need to be a security expert -- this appendix covers the practical habits that protect you and the projects you contribute to.

      -

      Alex: The next layer is this. Start with Learning Cards: Using This Security Reference. There is something to understand, something to try, and something that proves the try worked.

      -

      Alex: The practical anchors are these. Sections are ordered from understanding (section 1) to prevention (2-5) to recovery (6-7) to daily habits (8-9). Code blocks contain exact gitignore patterns and terminal commands -- switch to Focus Mode before copying. The Security Checklist (section 9) is a task list you can use before every push. Code examples for.gitignore patterns and terminal commands are in high-contrast code blocks. Warning callouts use bold text -- scan for bold to find the most critical safety notes. The Security Checklist at the bottom uses checkbox formatting for easy visual tracking.

      -

      Jamie: What is the one idea that makes the next few steps less mysterious?

      -

      Alex: This is where 1. Why This Matters -- What Happens When Secrets Leak becomes real: when a secret (API key, token, password, private key) is committed to a public GitHub repository -- even for a few seconds before you delete it -- it's effectively compromised. That matters in practice: Why "I'll just delete it right away" isn't enough.

      -

      Alex: That shows up in the workshop in a few specific ways. Bots scan GitHub continuously and harvest secrets within seconds of a push. The secret lives in your git history even after you delete the file. GitHub forks capture history -- once forked, you can't fully erase it. Search engines may index the content before you remove it.

      -
      -

      Alex: Now bring the learner back to the room. Keep the learner anchored in 2. The.gitignore File -- Your First Line of Defense. A.gitignore file tells Git which files to never track. This is the part to say slowly: Files listed in.gitignore won't show up in git status, won't be staged by git add, and won't be committed.

      -

      Jamie: What should they understand before typing anything?

      -

      Alex: The reason Checking if a file is already tracked matters is that.gitignore only prevents untracked files from being added. That gives the learner a simple foothold: if Git is already tracking a file,.gitignore won't stop it from being committed in the future.

      -

      Alex: Treat examples as spoken recipes, not decorations. You may hear something like Check if a specific file is tracked; git ls-files.env; If it returns the filename, it's being tracked -- you need to untrack it; git rm --cached.env; Then add it to.gitignore and commit. Read the command, understand what it changes, then run it only when the repository state matches the lesson.

      -

      Alex: The useful habit is simple: orient first, act second, verify third. That pause before acting is part of the work.

      -

      Jamie: How do you keep commands from becoming magic words?

      -

      Alex: Start with Global.gitignore -- apply to every repo on your machine: You can create a global.gitignore that applies to all repositories on your computer -- useful for OS-specific and editor-specific files you never want to commit anywhere. The next useful detail is this: Add your editor and OS files to /.gitignore global so you never have to add them to individual repos. Think of it like entering a new building: first you find the lobby, then the room, then the door you actually need.

      -

      Alex: Treat examples as spoken recipes, not decorations. You may hear something like Create a global gitignore file; touch /.gitignore global; Tell Git to use it; git config --global core.excludesfile /.gitignore global. Read the command, understand what it changes, then run it only when the repository state matches the lesson.

      +

      Jamie: Let's pause on Step 6: Find the Heading Hierarchy Issue. What should a learner take away from it?

      +

      Alex: Start with Step 6: Find the Heading Hierarchy Issue. There is something to understand, something to try, and something that proves the try worked.

      +

      Alex: The practical takeaway is this. Four hashes ( ) indicate a level 4 heading. In the diff, you're looking for it appearing after a level 2 heading ( ). This creates the hierarchy skip you caught in Exercise A. You found the explanation in the Accessible Diff Viewer's format. You can explain: "The added line with directly follows a, skipping level 3". The Accessible Diff Viewer made this pattern clearer than scanning raw + characters.

      +

      Alex: First, continue pressing Down arrow to move through changes. Then, listen carefully for a change involving headings (lines starting with ). After that, specifically, listen for: "Added: " (four hashes). Finally, when you hear this, stop and write it down. It is like walking a hallway with named doors: read the sign, enter the right room, then confirm where you landed.

      +

      Jamie: Let's pause on Step 7: Locate the Heading Line and Add an Inline Comment. What should a learner take away from it?

      +

      Alex: Start with Step 7: Locate the Heading Line and Add an Inline Comment. There is something to understand, something to try, and something that proves the try worked.

      +

      Alex: The practical takeaway is this. Use Ctrl+F to open Find. Search for to locate it quickly. Press Enter to jump to it. With keyboard: The comment button may appear on the current line; navigate to it and press Enter. A comment box opens. You can type your comment.

      +

      Alex: First, once you identified the problematic heading in the Accessible Diff Viewer, close the Accessible Diff Viewer (press F7 again or Alt+F2). Then, you're back in the regular Diff Editor. After that, find the line with the problematic heading. Finally, close Find (Escape). The rhythm is simple: orient, act, verify, then continue.

      +

      Jamie: Before we leave Step 7: Locate the Heading Line and Add an Inline Comment, what is the practical point?

      +

      Alex: First, place your cursor on that line. Then, right-click and select "Add Comment" or press the Comment icon that appears on the left margin. Think of it as a rail line: each stop confirms you are still on the right route before the next one.

      +

      Jamie: Let's pause on Step 8: Write Your Accessible Diff Comment. What should a learner take away from it?

      +

      Alex: Start with Step 8: Write Your Accessible Diff Comment: Why mention the Accessible Diff Viewer?

      +

      Alex: The practical takeaway is this. It shows that the tool itself helps you see the issue. It documents how you caught the problem (useful for learning).

      +

      Alex: First, in the comment box, type. Then, press Ctrl+Enter or click Comment to submit. Think of it as a rail line: each stop confirms you are still on the right route before the next one.

      -

      Jamie: What is the safe way to learn from that example?

      -

      Alex: Here is the plain-English version of GitHub's.gitignore templates. When creating a new repository on GitHub, you can choose a.gitignore template for your language -- GitHub pre-fills it with the most common patterns for that ecosystem. Put another way, find all templates at github.com/github/gitignore.

      -

      Alex: Treat examples as spoken recipes, not decorations. You may hear something like Download a template (e.g., for Node.js); curl https://raw.githubusercontent.com/github/gitignore/main/Node.gitignore.gitignore. Read the command, understand what it changes, then run it only when the repository state matches the lesson.

      -

      Alex: This is where the talk moves from concept to action. This is where 3. Environment Variables -- The Right Way to Store Secrets becomes real: instead of hardcoding secrets in your files, store them in environment variables that live outside of your repository.

      -

      Jamie: Where do you want a learner to place their attention here?

      -

      Alex: Keep the learner anchored in Using a.env file locally. A.env file stores your local environment variables. This is the part to say slowly: It's convenient and universally supported -- and it must be in your.gitignore.

      +

      Jamie: Let's pause on Step 9: Create a GitHub Pull Request Comment. What should a learner take away from it?

      +

      Alex: Here is the plain-English version of Step 9: Create a GitHub Pull Request Comment. Now you've reviewed the same PR in.

      +

      Alex: First, browser (Exercise A): You spot-checked line numbers manually. Then, VS Code (Exercise B): The Diff Editor plus Accessible Diff Viewer announced changes. After that, go to GitHub in your browser and open the same PR. Finally, scroll to the bottom and leave a comment in the Conversation tab. Treat it like a recipe: do not add the next ingredient until the previous one is actually in the bowl.

      +

      Jamie: Before we leave Step 9: Create a GitHub Pull Request Comment, what is the practical point?

      +

      Alex: First, click Comment. It is a checklist, but a meaningful one: every item creates evidence that the next step is safe.

      +

      Jamie: Before we leave Reflect on This Exercise, what is the practical point?

      +

      Alex: This is where Reflect on This Exercise becomes real: after completing Steps 1-9, answer. That matters in practice: In Chapter 16, you'll compare these manual reviews with the @pr-review agent's suggested changes. The workshop is closer to rehearsal than lecture. You hear the move, try the move, and then check what changed.

      +

      Alex: First, announcement clarity: Did the "Added:" and "Removed:" labels from the Accessible Diff Viewer help you follow changes faster than reading + and − prefixes in the browser? Then, navigation pattern: Which tool required less back-and-forth clicking/tabbing to understand each change? After that, when would you use each? In one sentence: describe a type of PR where you'd prefer to use each tool. It is a checklist, but a meaningful one: every item creates evidence that the next step is safe.

      +

      Jamie: How do these exercises create confidence instead of pressure?

      +

      Alex: Keep the learner anchored in Exercise C - Compare and Reflect. Your Mission: Synthesize what you learned from the manual code reviews (Exercises A & B) and document your findings. This is the part to say slowly: What You'll Learn: Which tools work best for different scenarios, and how your manual review skills prepare you to use AI agents effectively.

      -

      Alex: Before the learner moves on. The reason Sharing secrets with your team safely matters is that never send secrets in Slack, email, or GitHub comments. The interface gets friendlier when it stops being a wall of controls and starts being a set of named places.

      -

      Alex: That becomes easier when you listen for these cues. GitHub Actions Secrets -- for CI/CD pipelines: Settings → Secrets and variables → Actions. A password manager with sharing (1Password Teams, Bitwarden) -- for team credentials. A secrets manager (AWS Secrets Manager, HashiCorp Vault) -- for production systems.

      -

      Jamie: What is the pre-flight check here?

      -

      Alex: Start with 4. Review Before You Commit: The most effective habit is simply reviewing what you're about to commit before you commit it.

      -

      Alex: A solid pull request habit is to separate three questions: what changed, why it changed, and what still needs review. That keeps the conversation useful instead of noisy.

      -

      Jamie: What should happen before anyone copies and runs it?

      -

      Alex: Start with git diff --staged -- see exactly what's going in. There is something to understand, something to try, and something that proves the try worked.

      -

      Alex: For a learner, the useful signals are these. Any hardcoded passwords, tokens, or API keys.env or credential files that snuck in. Any TODO comments that reference sensitive information.

      -

      Alex: Treat examples as spoken recipes, not decorations. You may hear something like Review all staged changes before committing; git diff --staged; Review a specific file; git diff --staged docs/config.md. Read the command, understand what it changes, then run it only when the repository state matches the lesson.

      +

      Alex: Keep the teaching thread moving. The reason Step 1: Gather Your Data matters is that before writing your reflection, collect all the information you gathered. That gives the learner a simple foothold: write these down (in a text editor, on paper, or mentally) - you'll reference them in Steps 2-4.

      +

      Alex: The practical takeaway is this. Which line number had the heading hierarchy skip? Which line number had the link text issue? How many steps did it take to find each issue? Did you use screen reader commands or visual scanning more?

      +

      Jamie: Let's pause on Step 2: Navigate to the PR and Leave Your Reflection Comment. What should a learner take away from it?

      +

      Alex: Start with Step 2: Navigate to the PR and Leave Your Reflection Comment. There is something to understand, something to try, and something that proves the try worked.

      +

      Alex: The practical takeaway is this. A text editing area with formatting options (Bold, Italic, Link, etc.). A Comment button below the text area.

      +

      Alex: First, go to GitHub in your browser. Then, open the same PR ("Add screen reader tips to the setup guide"). After that, scroll to the Conversation tab. Finally, scroll all the way down to the comment box at the bottom (labeled "Leave a comment" or "Add a comment"). Think of it as a rail line: each stop confirms you are still on the right route before the next one.

      +

      Jamie: Before we leave Step 2: Navigate to the PR and Leave Your Reflection Comment, what is the practical point?

      +

      Alex: First, click in the comment box. Treat it like a recipe: do not add the next ingredient until the previous one is actually in the bowl.

      +

      Alex: Keep the teaching thread moving. Here is the plain-English version of Step 3: Write Your Comparison. Type your response to these three questions. Put another way, be specific - reference exact tools, steps, and what you discovered. It is like learning a transit route. The names of the stops matter because they tell you whether you are still going the right direction.

      -

      Jamie: Let's pause on Avoid git add. blindly. What should a learner take away from it?

      -

      Alex: This is where Avoid git add. blindly becomes real: stages everything in your working directory -- including files you didn't mean to add. That matters in practice: git add -p (patch mode) walks you through each change chunk by chunk and asks whether to stage it.

      -

      Alex: Treat examples as spoken recipes, not decorations. You may hear something like Risky - stages everything without review; git add.; Better - stage specific files you know are clean; git add src/auth.js docs/README.md; Or stage interactively - review each file before adding; git add -p. Read the command, understand what it changes, then run it only when the repository state matches the lesson.

      -

      Alex: A solid Git habit is to know which branch you are on, what changed, and what confirmation you expect before you run the next command.

      -

      Jamie: Let's pause on Check what's staged before committing. What should a learner take away from it?

      -

      Alex: Keep the learner anchored in Check what's staged before committing. GitHub Copilot can help: After staging your changes, open Copilot Chat and ask: "Review my staged changes for any accidentally included secrets, API keys, or credentials." Paste the output of git diff --staged into the chat. A good GitHub workflow is like a well-run meeting: everyone knows the topic, the next action, and who has the floor.

      -

      Alex: Treat examples as spoken recipes, not decorations. You may hear something like See which files are staged (and which aren't); git status; See the full diff of staged changes; git diff --staged. Read the command, understand what it changes, then run it only when the repository state matches the lesson.

      -

      Jamie: What would you say to someone who is already bracing for this to be too much?

      -

      Alex: The reason 5. Pre-Commit Hooks -- Automated Secret Detection matters is that a pre-commit hook is a script that runs automatically every time you try to commit. That gives the learner a simple foothold: if the script detects a problem (like a potential secret), it blocks the commit and tells you what it found.

      +

      Jamie: Let's pause on Step 4: Review Your Comment. What should a learner take away from it?

      +

      Alex: Start with Step 4: Review Your Comment. There is something to understand, something to try, and something that proves the try worked.

      +

      Alex: The practical takeaway is this. Is it clear which tool I preferred? Did I explain why with concrete examples? Am I describing the real-world impact accurately? Would someone else reading this understand how I caught the issue?

      +

      Alex: First, before submitting, re-read your comment using your screen reader or by reading aloud. Then, ask yourself. After that, make any corrections needed. Finally, do not submit yet - continue to Step 5. It is a checklist, but a meaningful one: every item creates evidence that the next step is safe.

      +

      Jamie: Let's pause on Step 5: Submit Your Reflection. What should a learner take away from it?

      +

      Alex: Start with Step 5: Submit Your Reflection. There is something to understand, something to try, and something that proves the try worked.

      +

      Alex: The practical takeaway is this. Your comment is now visible on the PR. Other reviewers can see your comparison. You have completed the three-part exercise series. Your comment appears on the PR thread. It includes all three reflections. The PR author and other reviewers can see your thought process.

      +

      Alex: First, locate the Comment button at the bottom right of the comment box. Then, with keyboard: Press Tab until the Comment button is focused, then Enter. After that, with mouse: Click the Comment button. Finally, your comment is submitted and appears on the PR page. It is like walking a hallway with named doors: read the sign, enter the right room, then confirm where you landed.

      +

      Jamie: Let's pause on Step 6: Checkpoint - Validate Your Learning. What should a learner take away from it?

      +

      Alex: The reason Step 6: Checkpoint - Validate Your Learning matters is that before moving forward, verify you understand. That gives the learner a simple foothold: if you can answer all three, you're ready for the next chapter.

      +

      Alex: The practical takeaway is this. Expected answer: Something like "Screen readers let users navigate by heading level (pressing 3 jumps to H3), so skipping a level makes users think content is missing.". Expected answer: e.g., "Browser: finding context in discussions. VS Code: linear reading of changes.". Expected answer: Something like "Open the document in a browser, use screen reader heading navigation, and confirm I can reach all levels (H2, H3, H4).".

      +

      Alex: First, heading Hierarchy: Can you explain in one sentence why a → skip breaks screen reader navigation? Then, tool Strengths: For each tool you used, name one task it made easier. After that, real-World Testing: How would you test the heading issue in the published document (not the PR diff)? The rhythm is simple: orient, act, verify, then continue.

      -

      Alex: Here is the practical turn. Start with Option A: detect-secrets (recommended, Python-based): detect-secrets scans for over 20 types of secrets and integrates well with existing repos. The next useful detail is this: After setup, any commit containing a potential secret is blocked with a clear message showing which file and line triggered the alert.

      -

      Jamie: Give me the version that sounds like an instructor, not a manual.

      -

      Alex: Here is the plain-English version of Option C: pre-commit framework (manages multiple hooks). The pre-commit framework lets you install and manage hooks from a YAML config file, making it easy to share hook config across your team. Put another way, pre-commit hooks live in.git/hooks/ and are local to your machine -- they're not committed to the repo automatically.

      -

      Alex: Keep the thread going. This is where Step 1: Rotate the secret immediately becomes real: before anything else -- go to wherever that secret is managed and revoke or rotate it. That matters in practice: It may already be compromised, so neutralizing it is more important than removing it from git history. The workshop is closer to rehearsal than lecture. You hear the move, try the move, and then check what changed.

      +

      Alex: Keep the teaching thread moving. Start with Using GitHub Copilot to Understand Code Changes: Reviewing code is about understanding what changed, why it changed, and whether the change is safe and correct. The next useful detail is this: GitHub Copilot can help you gather and understand information about code changes - especially when diffs are large, complex, or involve unfamiliar frameworks. Think of it like entering a new building: first you find the lobby, then the room, then the door you actually need.

      +

      Jamie: Let's pause on When to Use Copilot During Code Review. What should a learner take away from it?

      +

      Alex: Here is the plain-English version of When to Use Copilot During Code Review. Copilot is most useful for answering these questions.

      +

      Alex: First, "What does this code do?" - you're reading unfamiliar syntax or a framework you don't know well. Then, "Why might this change break something?" - you need to understand dependencies or side effects. After that, "Is this pattern safe?" - you want to verify that the approach follows best practices. Finally, "What would be a better way to write this?" - you're looking for alternatives to suggest. Treat it like a recipe: do not add the next ingredient until the previous one is actually in the bowl.

      +

      Jamie: Before we leave When to Use Copilot During Code Review, what is the practical point?

      +

      Alex: First, "Does this match the PR's description?" - the change seems to do more (or less) than claimed. It is a checklist, but a meaningful one: every item creates evidence that the next step is safe.

      +

      Jamie: Let's pause on In VS Code with an Open Diff. What should a learner take away from it?

      +

      Alex: Start with In VS Code with an Open Diff. There is something to understand, something to try, and something that proves the try worked.

      +

      Alex: First, open the PR using the GitHub Pull Requests extension (see Part 2). Then, open the diff for any file. After that, select a block of code that confuses you (highlight it). Finally, open Copilot Chat: Ctrl+Shift+I. It is a checklist, but a meaningful one: every item creates evidence that the next step is safe.

      +

      Jamie: Before we leave In VS Code with an Open Diff, what is the practical point?

      +

      Alex: First, Copilot reads the selected code and answers in the chat. It is like walking a hallway with named doors: read the sign, enter the right room, then confirm where you landed.

      -

      Jamie: Let's pause on Step 2: Was it pushed to a public repo? What should a learner take away from it?

      -

      Alex: Keep the learner anchored in Step 2: Was it pushed to a public repo? If it was pushed (remote has the secret). This is the part to say slowly: The secret is potentially already compromised -- assume it was harvested.

      -

      Alex: Treat examples as spoken recipes, not decorations. You may hear something like Undo the last commit, keep your changes staged (safest); git reset --soft HEAD 1; Now remove the secret from the file, re-add, and re-commit; (Edit the file to remove the secret); git add -p Review what you stage; git commit -m "Your original commit message. Read the command, understand what it changes, then run it only when the repository state matches the lesson.

      -

      Alex: Another way to ground it. The reason Step 3: Remove the secret from git history matters is that this only matters if the commit was pushed. That gives the learner a simple foothold: if it was local-only and you used git reset --soft above, you're done.

      -

      Jamie: Let's pause on Method A: git filter-repo (recommended -- built-in, modern). What should a learner take away from it?

      -

      Alex: Start with Method A: git filter-repo (recommended -- built-in, modern). There is something to understand, something to try, and something that proves the try worked.

      -

      Alex: Treat examples as spoken recipes, not decorations. You may hear something like Install git-filter-repo; pip install git-filter-repo; Remove a specific file from all history; git filter-repo --path secrets.json --invert-paths; Replace a specific string (the secret value) throughout all history; git filter-repo --replace-text REMOVED"). Read the command, understand what it changes, then run it only when the repository state matches the lesson.

      +

      Jamie: Let's pause on On GitHub.com (Web Interface). What should a learner take away from it?

      +

      Alex: Keep the learner anchored in On GitHub.com (Web Interface). Another option: Use the GitHub Copilot inline suggestions on GitHub.com.

      +

      Alex: The practical takeaway is this. Some GitHub PRs show Copilot insights directly in the diff (as of early 2026). If you see a lightbulb icon, click it to see Copilot's suggestion about that line.

      +

      Alex: First, open the PR's Files Changed tab. Then, focus on a line or section you want to understand better. After that, in VS Code Copilot Chat (not in the browser - Copilot Chat doesn't work directly in browser diffs yet). Finally, copy the confusing code, paste it into chat, and ask Copilot to explain. It is like walking a hallway with named doors: read the sign, enter the right room, then confirm where you landed.

      +

      Alex: Keep the teaching thread moving. The reason Copilot Limitations During Review (Critical to Know) matters is that this is why manual review is essential: You have context (project history, team decisions, user impact) that Copilot does not. That gives the learner a simple foothold: use Copilot to understand, then use your judgment to decide. The interface gets friendlier when it stops being a wall of controls and starts being a set of named places.

      +

      Alex: The practical takeaway is this. See the whole project - it sees only what you show it (the selected diff, not the context of the entire codebase). Verify correctness - it can explain what code does, but not whether it's correct for your specific use case. Understand intent - it reads the code, not the author's mind or the PR description. Catch all risks - it can spot common patterns, but not edge cases unique to your project.

      +

      Jamie: Let's pause on Best Practices. What should a learner take away from it?

      +

      Alex: Start with Best Practices. There is something to understand, something to try, and something that proves the try worked.

      +

      Alex: First, read the diff manually first - you spot the big picture before asking Copilot details. Then, ask Copilot specific questions - not "review this code" but "does this regex handle Unicode?". After that, fact-check Copilot's answers - it can be confidently wrong, especially about frameworks or domains it has less training data. Finally, combine Copilot with manual analysis - ask Copilot to explain, then verify by checking the PR description or looking for related files. Think of it as a rail line: each stop confirms you are still on the right route before the next one.

      +

      Jamie: Before we leave Best Practices, what is the practical point?

      +

      Alex: First, use Copilot to draft comments - type Draft a comment about [issue] for this PR and edit Copilot's suggestion to match your tone. Treat it like a recipe: do not add the next ingredient until the previous one is actually in the bowl.

      -

      Jamie: Let's pause on Step 4: Force push the cleaned history. What should a learner take away from it?

      -

      Alex: Here is the plain-English version of Step 4: Force push the cleaned history. After rewriting history, you must force push. Put another way, anyone who has cloned or pulled the repo will need to re-clone or rebase after a force push. It is like learning a transit route. The names of the stops matter because they tell you whether you are still going the right direction.

      -

      Alex: Treat examples as spoken recipes, not decorations. You may hear something like git push --force-with-lease origin main. Read the command, understand what it changes, then run it only when the repository state matches the lesson.

      -

      Jamie: If I am listening before the workshop starts, what should settle in my mind first?

      -

      Alex: This is where Step 5: Tell GitHub to rescan becomes real: after removing the secret from history, go to Security → Secret scanning in your repository and mark any open alerts as resolved.

      -

      Alex: That connects to another useful point. Keep the learner anchored in 7. GitHub's Built-In Push Protection. GitHub automatically scans pushes for known secret patterns before they reach the remote. This is the part to say slowly: If it detects a secret, the push is blocked.

      +

      Alex: Keep the teaching thread moving. Here is the plain-English version of What Comes Next. Your manual code review skills - identifying heading issues, catching link text problems, understanding screen reader navigation, gathering information with Copilot - are the foundation for understanding automated review. Put another way, in Chapter 16 (Accessibility Agents), you'll meet a full team of agents designed to amplify these skills.

      +

      Jamie: Let's pause on Part 4: The Reviewer's Craft. What should a learner take away from it?

      +

      Alex: This is where The Reviewer's Craft becomes real: parts 1 through 3 taught you the mechanics -- how to read diffs, leave comments, and use Copilot to understand unfamiliar code. That matters in practice: This part covers something equally important: how to think like a reviewer.

      +

      Alex: Keep the teaching thread moving. Keep the learner anchored in What to Look for in a Review. Every PR is different, but most reviews benefit from scanning across these five categories. This is the part to say slowly: You do not need to check every category exhaustively on every PR. A good GitHub workflow is like a well-run meeting: everyone knows the topic, the next action, and who has the floor.

      -

      Jamie: Let's pause on What push protection covers. What should a learner take away from it?

      -

      Alex: The reason What push protection covers matters is that GitHub knows the patterns for hundreds of secret types including.

      -

      Alex: The parts worth keeping in working memory are these. GitHub tokens (PATs, GitHub App tokens, OAuth tokens). AWS access keys. Azure credentials. Google Cloud keys. Stripe, Twilio, Slack, and dozens more API keys.

      -

      Jamie: Give me the sequence, because order matters here.

      -

      Alex: Start with If push protection blocks you. There is something to understand, something to try, and something that proves the try worked.

      -

      Alex: First, confirm it's actually a secret -- check the file and line mentioned. Then, if it's a real secret: Remove it from the file, amend your commit, and push again. After that, if it's a false positive: Use the bypass URL GitHub provides to push with an explanation. Think of it as a rail line: each stop confirms you are still on the right route before the next one.

      -

      Jamie: Let's pause on Checking your repo's push protection status. What should a learner take away from it?

      -

      Alex: Here is the plain-English version of Checking your repo's push protection status. As a contributor you can see push protection in action when a push is blocked. Put another way, maintainers configure it in Settings → Code security → Push protection.

      +

      Jamie: Let's pause on The Three Review Actions. What should a learner take away from it?

      +

      Alex: The reason The Three Review Actions matters is that when you submit a review on GitHub, you choose one of three actions. That gives the learner a simple foothold: picking the right one matters because it signals your intent to the author and to anyone else watching the PR.

      +

      Alex: First, did you find a bug, security issue, or broken test? -- Request Changes. Then, does the code do something different from what the description says? -- Request Changes. After that, does everything work, with maybe a few style nits? -- Approve (mention the nits in a comment). Finally, do you have questions or optional suggestions? -- Comment. The rhythm is simple: orient, act, verify, then continue.

      +

      Alex: Keep the teaching thread moving. Start with Writing Constructive Feedback: The way you phrase feedback determines whether the author feels supported or attacked. The next useful detail is this: Before pointing out problems, acknowledge something the author did well.

      +

      Jamie: Let's pause on The Reviewer's Checklist. What should a learner take away from it?

      +

      Alex: Here is the plain-English version of The Reviewer's Checklist. Run through this list mentally (or copy it into your notes) for every PR you review.

      +

      Alex: The practical takeaway is this. [ ] I read the PR description before reading the code. [ ] The code does what the description says it does. [ ] The change does not include unrelated modifications. [ ] Variable and function names are clear. [ ] I checked for accessibility: labels, headings, keyboard reach, contrast. [ ] I verified no existing behavior is broken by the change.

      -

      Jamie: Let's pause on Never store credentials in plaintext. What should a learner take away from it?

      -

      Alex: This is where Never store credentials in plaintext becomes real: do this instead - use the OS credential store. That matters in practice: With a credential helper set, Git asks for your credentials once and stores them securely in the OS keychain -- not in any file.

      -

      Alex: Treat examples as spoken recipes, not decorations. You may hear something like Storing a token in a plain text file; echo "ghp mytoken" /token.txt; Hardcoding in a script; export GITHUB TOKEN="ghp mytoken" in a.bashrc or.zshrc that's committed; In a git config; git config --global url."https://myusername:ghp mytoken@github.com".insteadOf. macOS -- use Keychain; git config --global credential.helper osxkeychain; Windows -- use Credential Manager (set automatically by Git for Windows); git config --global credential.helper wincred; Linux -- use the libsecret store (requires installation); git. Read the command, understand what it changes, then run it only when the repository state matches the lesson.

      -

      Jamie: Let's pause on Using a password manager. What should a learner take away from it?

      -

      Alex: Keep the learner anchored in Using a password manager. Store your GitHub PAT, SSH key passphrase, and other credentials in a password manager (1Password, Bitwarden, KeePass). This is the part to say slowly: Most support browser extensions, CLI access, and automatic lock after inactivity.

      -

      Jamie: Let's pause on Checking what credential helper is set. What should a learner take away from it?

      -

      Alex: The reason Checking what credential helper is set matters is that if this returns nothing, your credentials may be stored in plaintext. The interface gets friendlier when it stops being a wall of controls and starts being a set of named places.

      -

      Alex: Treat examples as spoken recipes, not decorations. You may hear something like git config --global credential.helper. Read the command, understand what it changes, then run it only when the repository state matches the lesson.

      +

      Alex: Keep the teaching thread moving. This is where Reviewing as a Learning Tool becomes real: reviewing is not just a gate to keep bad code out. That matters in practice: It is one of the fastest ways to grow as a developer. The workshop is closer to rehearsal than lecture. You hear the move, try the move, and then check what changed.

      +

      Jamie: Let's pause on Learning Cards: The Reviewer's Craft. What should a learner take away from it?

      +

      Alex: Start with Learning Cards: The Reviewer's Craft. There is something to understand, something to try, and something that proves the try worked.

      +

      Alex: The practical takeaway is this. Jump between changed hunks in a diff with Alt+F5 (next change) and Shift+Alt+F5 (previous change) to scan for scope creep efficiently. Use Alt+F2 (Accessible View) on a Copilot-generated review summary to read the full text with arrow keys before posting. When leaving feedback, mention specific line numbers ("Line 42 skips from h2 to h4") so the author can navigate directly with Ctrl+G. The three review actions (Approve, Request Changes, Comment) are shown as clearly labeled radio buttons in the review submission form. Use the reviewer checklist in this section as a mental framework -- copy it into your notes and check items off as you review each PR. The diff view uses green and red backgrounds for added/removed lines; pair with a High Contrast theme if these colors are hard to distinguish.

      +

      Alex: Keep the teaching thread moving. The reason Day 2 Teaser: The Full Accessibility Agents Review Ecosystem matters is that chapter 16 shows you how to leverage 50+ specialized agents to make your reviews faster, more consistent, and more thorough - while staying in full control of what you post.

      -

      Jamie: Let's pause on Learning Cards: Security Checklist. What should a learner take away from it?

      -

      Alex: Start with Learning Cards: Security Checklist. There is something to understand, something to try, and something that proves the try worked.

      -

      Alex: A few details make that real. The checklist below uses Markdown task list formatting -- each item is announced as "checkbox not checked". Items are grouped into three categories: Before Committing, Before Pushing, and Repository Setup. Read through the list once to learn the habits, then use it as a pre-push routine. Checkboxes create a clear visual pattern for scanning -- each line starts with a square box. Three groups are separated by h3 headings: Before Committing, Before Pushing, Repository Setup. Consider copying this checklist into a personal note and checking items off for each project.

      -

      Alex: This is the part worth saying out loud. Here is the plain-English version of 9. Security Checklist for Contributors. Use this before every push to a public repository.

      -

      Jamie: What does someone need before they touch the keyboard?

      -

      Alex: Start with Before committing. There is something to understand, something to try, and something that proves the try worked.

      -

      Alex: On the ground, that means a few things. [ ] I reviewed git diff --staged and didn't see any tokens, passwords, or keys. [ ] I used git add or git add -p rather than git add. [ ] Any.env files or credential files are listed in.gitignore. [ ] Config files with real values are in.gitignore; only example/template files are committed.

      +

      Jamie: What do you want them to do when the plan breaks?

      +

      Alex: Start with The Agents That Help With Code Review: Accessibility Review Agents (when code affects UI/UX).

      +

      Alex: The practical takeaway is this. @pr-review - Generates a full-draft PR review with line-numbered diff maps, risk assessment, before/after snapshots, and suggested inline comments. You edit and post it under your name. @pr-author-checklist - Before you even submit your PR, use this to verify you haven't missed setup steps, accessibility checks, or documentation. @insiders-a11y-tracker - Monitors your PR for accessibility-sensitive changes: WCAG violations, heading hierarchy issues, link text quality, keyboard navigation impacts. @developer-hub - Orchestrates explanations for unfamiliar code, patterns, or frameworks you're reviewing. @python-specialist - If your PR contains Python code, this agent explains patterns, spots accessibility issues, and suggests improvements. @wxpython-specialist - For desktop GUI code, helps verify accessible widget patterns and focus management.

      +

      Jamie: Let's pause on How It Works. What should a learner take away from it?

      +

      Alex: Start with How It Works. There is something to understand, something to try, and something that proves the try worked.

      +

      Alex: First, review manually first (you just did this with Exercises A, B, C). Then, run an agent - @pr-review review PR 14 generates a draft in seconds. After that, edit the agent's draft - you add context, remove noise, correct errors. Finally, post your review - it now has both AI efficiency and your human judgment. Treat it like a recipe: do not add the next ingredient until the previous one is actually in the bowl.

      +

      Jamie: Before we leave How It Works, what is the practical point?

      +

      Alex: First, the agent tracks impact - @insiders-a11y-tracker monitors whether your accessibility feedback was addressed. It is a checklist, but a meaningful one: every item creates evidence that the next step is safe.

      +

      Jamie: Let's pause on The Principle: Skill First, Agent Second. What should a learner take away from it?

      +

      Alex: This is where The Principle: Skill First, Agent Second becomes real: why do this manually before using agents? That matters in practice: Manual reviews teach you what to look for.

      +

      Alex: The practical takeaway is this. You understand what the agent is doing (you did it manually). You evaluate the agent's output critically (you know what right looks like). You add judgment the agent lacks (context, intent, team decisions). You verify the agent didn't miss anything important.

      -

      Alex: Hold that next to this. Start with Before pushing. There is something to understand, something to try, and something that proves the try worked.

      -

      Alex: Here is what that changes in practice. [ ] git log --oneline -5 -- all commits look expected. [ ] No commits with messages like "remove secret" or "oops" that suggest a secret was added and removed (the secret is still in history).

      -

      Jamie: If setup starts to feel like a barrier, how should a learner think about it?

      -

      Alex: Start with Repository setup (one time). There is something to understand, something to try, and something that proves the try worked.

      -

      Alex: The room should hear these as checkpoints. [ ].gitignore includes.env,.key,.pem, and relevant patterns for your stack. [ ] Global.gitignore ( /.gitignore global) covers editor/OS files. [ ] Git credential helper is configured to use the OS keychain. [ ] (Optional) A pre-commit hook is installed to scan for secrets automatically.

      -

      Alex: That matters because of the next idea. Start with If you're a maintainer: See also: Appendix L: GitHub Security Features for the GitHub platform security tools (Dependabot, secret scanning alerts, code scanning). The next useful detail is this: Appendix D: Git Authentication for SSH keys, PATs, and commit signing.

      -

      Alex: These are the details that keep the idea from floating away. [ ] Branch protection is enabled on main with required reviews and status checks. [ ] Secret scanning is enabled (Settings → Code security → Secret scanning). [ ] Push protection is enabled for the repository. [ ] A SECURITY.md file exists with instructions for reporting vulnerabilities.

      +

      Jamie: Let's pause on A Real Example: The Flow. What should a learner take away from it?

      +

      Alex: Keep the learner anchored in A Real Example: The Flow. Manual Review (your work in part 1-2). This is the part to say slowly: Agent-Assisted Review (what you'll do in Chapter 19).

      +

      Alex: The practical takeaway is this. Read diff, identify heading hierarchy skip. Write comment explaining why it matters. Submit your verdict.

      +

      Alex: First, run: @pr-review review PR 14. Then, agent generates a draft review covering the heading skip, link text, and 5 other issues. After that, you read the draft and notice: "the agent's explanation of the heading skip is good, but it missed that the link text on line 23 is still vague. Let me add that.". Finally, you post the agent's review + your additions. It is like walking a hallway with named doors: read the sign, enter the right room, then confirm where you landed.

      +

      Jamie: Before we leave A Real Example: The Flow, what is the practical point?

      +

      Alex: First, next time you review a similar PR, the agent works faster because it learned from your feedback. The rhythm is simple: orient, act, verify, then continue.

      Jamie: What should people carry with them after this?

      Alex: Carry the map. Know what page or tool you are in, know which action you are taking, and know what confirmation should follow. If the confirmation is missing, pause. That pause is not wasted time; it is professional judgment.

      Jamie: That is a better way to say it than just follow the steps.

      -

      Alex: Right. Steps matter, but understanding wins. That is episode 51. Next in the series is episode 52, where we keep building the same contributor muscles.

      +

      Alex: Right. Steps matter, but understanding wins. That is episode 15. Next in the series is episode 16, where we keep building the same contributor muscles.

      -

      Episode 52: GitHub Desktop

      -

      Using GitHub Desktop as an accessible alternative for cloning, branching, committing, and syncing.

      -

      Based on: Appendix H: GitHub Desktop

      +

      39. Challenge 11: Open a Day 2 PR

      +

      Opening a pull request from a locally pushed branch and reading it in VS Code.

      +

      Practice focus: Day 2 local workflow

      Audio and transcript are being regenerated for this episode.

      -Read Transcript - Episode 52: GitHub Desktop +Read Transcript - Challenge 11: Open a Day 2 PR

      Transcript

      -

      Alex: Welcome to Git Going with GitHub, episode 52: GitHub Desktop. I am Alex. Today we are going to make GitHub Desktop something you can explain, practice, and recover from when the interface surprises you.

      -

      Jamie: And I am Jamie. I will be the voice of the learner who is willing to ask, what is this for, where am I, and how do I know I did it right?

      +

      Alex: You are listening to Challenge Coach: Open a Day 2 PR. I am Alex, and this is the calm walkthrough before the hands-on work.

      +

      Jamie: And I am Jamie. I will make sure we teach the skill instead of just reading the checklist aloud.

      -

      Alex: The big idea today: Using GitHub Desktop as an accessible alternative for cloning, branching, committing, and syncing. We will name the concept, explain why it matters, practice the move, and point out the checks that tell you the work is real.

      -

      Jamie: So the episode should work even if someone has not read the chapter yet.

      -

      Alex: Exactly. The transcript has to stand on its own. It can point toward practice, but it should teach the concept right here in the conversation.

      +

      Alex: The focus is Opening a pull request from a locally pushed branch and reading it in VS Code. We will explain the concept, the action, the evidence, and the most common recovery path.

      +

      Jamie: So the learner needs the why, the move, and the checkpoint all in the same mental pocket.

      +

      Alex: That is the teaching shape: understand the concept, do the smallest real action, then verify the result before moving on.

      -

      Jamie: Okay, set the room for us. What are we walking into?

      -

      Alex: Start with A Visual Git Client for Every Workflow: Who this is for: You want a dedicated graphical Git application -- something separate from your code editor, with a clear visual interface for cloning, branching, committing, and managing pull requests. The next useful detail is this: GitHub Desktop is a great fit if you prefer working with a purpose-built Git GUI, or if VS Code's Source Control panel feels too embedded in the editor for your workflow.

      -

      Alex: A solid Git habit is to know which branch you are on, what changed, and what confirmation you expect before you run the next command.

      -

      Alex: The next layer is this. Here is the plain-English version of 1. What GitHub Desktop Does (and Doesn't Do). GitHub Desktop covers the everyday Git workflow that most contributors use on most days. It is like learning a transit route. The names of the stops matter because they tell you whether you are still going the right direction.

      +

      Jamie: How should they picture the shape of the workshop?

      +

      Alex: Start with Challenge 11: Open a Day 2 PR: What you will do: Open a pull request from the branch you pushed in Challenge 10. The next useful detail is this: Notice that the workflow is the same as Day 1 -- the only difference is where the commits came from.

      +

      Alex: A solid pull request habit is to separate three questions: what changed, why it changed, and what still needs review. That keeps the conversation useful instead of noisy.

      +

      Jamie: How would you walk the room through that step by step?

      +

      Alex: Start with Instructions. There is something to understand, something to try, and something that proves the try worked.

      +

      Alex: First, go to the learning-room repository on GitHub.com. Then, you may see a banner saying your branch had recent pushes -- select Compare & pull request if it appears. After that, or go to Pull requests New pull request, set base to main and compare to fix/YOUR-USERNAME. Finally, write a clear PR title and description. Treat it like a recipe: do not add the next ingredient until the previous one is actually in the bowl.

      +

      Jamie: What does the learner do first, second, and then after that?

      +

      Alex: First, include Closes XX if this PR addresses an existing issue. Then, submit the pull request. It is a checklist, but a meaningful one: every item creates evidence that the next step is safe.

      Jamie: What is the one idea that makes the next few steps less mysterious?

      -

      Alex: Start with What it supports. There is something to understand, something to try, and something that proves the try worked.

      -

      Alex: That shows up in the workshop in a few specific ways. Supported: Clone repositories from GitHub. Supported: Create, switch, and delete branches. Supported: Stage files (and individual lines/hunks within files). Supported: Write commit messages and commit. Supported: Push and pull from GitHub. Supported: Open pull requests (launches GitHub.com in your browser).

      +

      Alex: This is where The pattern is the same becomes real: the pull request step is identical. That matters in practice: The only change is where you made the edits.

      +

      Alex: That shows up in the workshop in a few specific ways. Day 1: Edit on GitHub.com commit open PR. Day 2: Edit locally commit push open PR.

      -

      Alex: Now bring the learner back to the room. Keep the learner anchored in What it does not support (use Git CLI or VS Code terminal instead). For these operations, open the repository in your terminal directly from GitHub Desktop -- Repository → Open in Terminal or Repository → Open in Command Prompt puts you in the right directory instantly.

      -

      Alex: For a learner, the useful signals are these. Not supported in the GitHub Desktop UI: Interactive rebase (git rebase -i). Not supported in the GitHub Desktop UI: git bisect. Not supported in the GitHub Desktop UI: git clean. Not supported in the GitHub Desktop UI: Creating annotated tags. Not supported in the GitHub Desktop UI: Commit signing (GPG/SSH).

      -

      Jamie: What should someone listen for when a lesson offers more than one tool path?

      -

      Alex: Start with Learning Cards: What GitHub Desktop Does. There is something to understand, something to try, and something that proves the try worked.

      -

      Alex: The parts worth keeping in working memory are these. GitHub Desktop handles cloning, branching, staging, committing, and pushing -- all accessible via keyboard and standard form controls. For operations Desktop does not support (rebase, bisect, clean), use Repository then Open in Terminal to land in the right directory instantly. All commit message fields are standard text inputs that screen readers announce as editable text. GitHub Desktop supports system-level zoom and high-contrast OS themes on both Windows and macOS. The diff panel uses green and red backgrounds for additions and deletions -- pair these with font size adjustments in your OS display settings. If the diff colors are hard to distinguish, open the same diff in VS Code via Repository then Open in VS Code for more theme options.

      +

      Alex: Now bring the learner back to the room. Keep the learner anchored in Peer simulation check. Review the peer-simulation PR title and description. This is the part to say slowly: If you have real buddy access, review your buddy's PR too.

      +

      Jamie: What would you say to someone who is already bracing for this to be too much?

      +

      Alex: Start with Example PR. There is something to understand, something to try, and something that proves the try worked.

      +

      Alex: That matters because of the next idea. Start with What matters: The learning objective is recognizing the similarities and differences between web-based and local Git workflows. The next useful detail is this: If you created a PR from a locally-pushed branch and noted what changed compared to Day 1, you completed this challenge. Think of it like entering a new building: first you find the lobby, then the room, then the door you actually need.

      Alex: The useful habit is simple: orient first, act second, verify third. That pause before acting is part of the work.

      -

      Jamie: Give me the sequence, because order matters here.

      -

      Alex: Start with Windows. There is something to understand, something to try, and something that proves the try worked.

      -

      Alex: First, go to desktop.github.com. Then, select "Download for Windows". After that, run the installer -- it installs and launches automatically. Think of it as a rail line: each stop confirms you are still on the right route before the next one.

      -

      Jamie: How would you walk the room through that step by step?

      -

      Alex: Here is the plain-English version of macOS. Linux: GitHub Desktop does not officially support Linux. Put another way, linux users should use VS Code's Source Control panel or the Git CLI.

      -

      Alex: First, go to desktop.github.com. Then, select "Download for macOS". After that, open the downloaded.zip, drag GitHub Desktop to your Applications folder. Treat it like a recipe: do not add the next ingredient until the previous one is actually in the bowl.

      -

      Alex: This is where the talk moves from concept to action. This is where 3. Signing In and Authentication becomes real: GitHub Desktop uses browser-based OAuth sign-in -- no tokens or SSH keys needed. That matters in practice: It handles authentication for you automatically.

      +

      Jamie: Okay, set the room for us. What are we walking into?

      +

      Alex: Here is the plain-English version of 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. Put another way, prerequisites: VS Code Setup & Accessibility Basics, Working with Pull Requests, Merge Conflicts Mac keyboard shortcuts: Throughout this chapter, all Ctrl+ shortcuts use Cmd+ on Mac, and Alt+ shortcuts use Option+.

      +

      Alex: A solid Git habit is to know which branch you are on, what changed, and what confirmation you expect before you run the next command.

      +

      Alex: This is where the talk moves from concept to action. This is where Workshop Recommendation (Chapter 14 / Challenge 10) becomes real: chapter 14 is the first local Git workflow chapter with hands-on repository management. That matters in practice: It supports Challenge 10: Go Local.

      +

      Alex: The room should hear these as checkpoints. There are 3. Each challenge should take under 10 minutes each. The evidence is PR metadata, branch names, and committed changes. The pattern is clone, branch, edit, commit, push, PR.

      Jamie: Turn that into a path someone can follow.

      -

      Alex: Keep the learner anchored in Sign in on first launch. GitHub Desktop stores your credentials securely in the system keychain. This is the part to say slowly: You won't be asked for a password again.

      -

      Alex: First, open GitHub Desktop. Then, select "Sign in to GitHub.com". After that, your browser opens to a GitHub authorization page -- sign in with your GitHub account. Finally, authorize GitHub Desktop when prompted. It is like walking a hallway with named doors: read the sign, enter the right room, then confirm where you landed.

      -

      Jamie: What is the ordered workflow?

      -

      Alex: First, switch back to GitHub Desktop -- you're signed in. The rhythm is simple: orient, act, verify, then continue.

      -
      -

      Jamie: How do you keep commands from becoming magic words?

      -

      Alex: The reason 4. The Interface at a Glance matters is that GitHub Desktop has three main areas. The interface gets friendlier when it stops being a wall of controls and starts being a set of named places.

      -

      Alex: Treat examples as spoken recipes, not decorations. You may hear something like ┌─────────────────────────────────────────────────────────┐; │ Toolbar: Current Repository ▾ Current Branch ▾ │; │ Fetch/Push button │; ├─────────────────┬───────────────────────────────────────┤; │ │ │; │ Left panel: │ Main area: │; │ Changes tab │ File diff. Read the command, understand what it changes, then run it only when the repository state matches the lesson.

      -

      Jamie: How do we make tool choice feel like access, not pressure?

      -

      Alex: Start with Learning Cards: The Desktop Interface. There is something to understand, something to try, and something that proves the try worked.

      -

      Alex: A few details make that real. Use Tab to move between the toolbar, file list, diff pane, and commit area -- each is a distinct focus region. The branch selector is a searchable dropdown: type to filter, Down Arrow to navigate, Enter to select. The commit button is announced as "Commit to [branch name]" -- press Enter to activate. The toolbar at the top stays fixed as you scroll -- repository name, branch, and sync button are always visible. Increase your OS display scaling to enlarge all panels proportionally without breaking the layout. The Changes and History tabs are side-by-side at the top of the left panel -- each tab label is clearly distinct.

      -

      Jamie: What does the learner do first, second, and then after that?

      -

      Alex: Here is the plain-English version of From GitHub.com. The easiest way is to go to the repository on GitHub.com and use the Code button.

      -

      Alex: First, on the repository page, activate Code → Open with GitHub Desktop. Then, GitHub Desktop opens with a dialog confirming the URL. After that, choose where to save the repository on your computer. Finally, select "Clone". Treat it like a recipe: do not add the next ingredient until the previous one is actually in the bowl.

      -
      -

      Jamie: Let's pause on From inside GitHub Desktop. What should a learner take away from it?

      -

      Alex: Start with From inside GitHub Desktop. There is something to understand, something to try, and something that proves the try worked.

      -

      Alex: First, press Ctrl+Shift+O (Windows) or Cmd+Shift+O (macOS) -- "Clone a repository". Then, choose the GitHub.com tab to browse your own repositories, or the URL tab to paste any repo URL. After that, select or type the repository. Finally, choose a local path. It is a checklist, but a meaningful one: every item creates evidence that the next step is safe.

      -

      Jamie: Before we leave From inside GitHub Desktop, what is the practical point?

      -

      Alex: First, select "Clone". It is like walking a hallway with named doors: read the sign, enter the right room, then confirm where you landed.

      -

      Jamie: What is the safe way to learn from that example?

      -

      Alex: Start with GitHub CLI alternative. There is something to understand, something to try, and something that proves the try worked.

      -

      Alex: Treat examples as spoken recipes, not decorations. You may hear something like gh repo clone owner/repo-name; Then open it in GitHub Desktop:; github /path/to/repo. Read the command, understand what it changes, then run it only when the repository state matches the lesson.

      -

      Jamie: Let's pause on Create a new branch. What should a learner take away from it?

      -

      Alex: The reason Create a new branch matters is that GitHub Desktop switches to the new branch immediately.

      -

      Alex: First, click Current Branch in the toolbar (or press Ctrl+Shift+N / Cmd+Shift+N). Then, type a name for your new branch. After that, select "Create Branch". Finally, choose whether to base it on the current branch or another -- usually keep the default. The rhythm is simple: orient, act, verify, then continue.

      +

      Alex: Start with Challenge 10 Practice Set. There is something to understand, something to try, and something that proves the try worked.

      +

      Alex: First, clone your Learning Room repository - clone your private Learning Room repo to your local machine using VS Code. Then, 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. After that, 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. It is like walking a hallway with named doors: read the sign, enter the right room, then confirm where you landed.

      -

      Jamie: Let's pause on Switch to an existing branch. What should a learner take away from it?

      -

      Alex: Start with Switch to an existing branch. There is something to understand, something to try, and something that proves the try worked.

      -

      Alex: First, click Current Branch in the toolbar. Then, type to search or scroll through the branch list. After that, click the branch name -- GitHub Desktop switches and updates your files. Think of it as a rail line: each stop confirms you are still on the right route before the next one.

      -

      Jamie: Let's pause on Delete a branch. What should a learner take away from it?

      -

      Alex: Here is the plain-English version of Delete a branch. The branch selector is a dropdown that opens a searchable list. Put another way, screen readers announce the currently selected branch name in the toolbar.

      -

      Alex: First, click Current Branch in the toolbar. Then, right-click the branch you want to delete. After that, select "Delete.". Treat it like a recipe: do not add the next ingredient until the previous one is actually in the bowl.

      -

      Alex: Keep the thread going. This is where Reviewing your changes becomes real: when you edit files in your editor and save them, GitHub Desktop automatically detects the changes and shows them in the Changes tab on the left. The workshop is closer to rehearsal than lecture. You hear the move, try the move, and then check what changed.

      -

      Alex: The room should hear these as checkpoints. The left panel lists every changed file with a checkbox. The right panel shows the diff for the selected file -- red lines removed, green lines added.

      -

      Alex: A solid pull request habit is to separate three questions: what changed, why it changed, and what still needs review. That keeps the conversation useful instead of noisy.

      +

      Jamie: What is the ordered workflow?

      +

      Alex: The reason Practice 10.1 Step-by-Step: Clone Your Learning Room Repository matters is that get a local copy of your Learning Room repository on your machine using VS Code. That gives the learner a simple foothold: VS Code desktop (or github.dev if you cannot install desktop VS Code). The interface gets friendlier when it stops being a wall of controls and starts being a set of named places.

      +

      Alex: First, open VS Code. If no folder is open, you should see the Welcome tab. Then, open the Command Palette: Ctrl+Shift+P (Mac: Cmd+Shift+P). After that, type git clone and select Git: Clone. Finally, VS Code asks for a repository URL. Paste your Learning Room repo URL (it looks like https://github.com/the workshop organization/learning-room-your username.git). You can copy this from the green Code button on your repo's GitHub page. The rhythm is simple: orient, act, verify, then continue.

      +

      Jamie: Give me the sequence, because order matters here.

      +

      Alex: First, press Enter. Then, 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. After that, VS Code clones the repository. When it finishes, a notification appears asking "Would you like to open the cloned repository?" Activate Open. Finally, 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. Think of it as a rail line: each stop confirms you are still on the right route before the next one.

      +

      Jamie: Let's pause on Practice 10.2 Step-by-Step: Create a Branch and Commit. What should a learner take away from it?

      +

      Alex: Start with Practice 10.2 Step-by-Step: Create a Branch and Commit: See also: Chapter 13: How Git Works explains the three areas (working directory, staging, repository) that make commits meaningful. The next useful detail is this: Check out (or create) a properly named branch, edit a file, stage the change, and commit with a clear message.

      +

      Alex: First, open the Command Palette: Ctrl+Shift+P (Mac: Cmd+Shift+P). Then, 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/your username. If the branch does not exist yet, type git create branch and select Git: Create Branch. After that, 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. Finally, 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). Think of it as a rail line: each stop confirms you are still on the right route before the next one.

      +

      Jamie: Before we leave Practice 10.2 Step-by-Step: Create a Branch and Commit, what is the practical point?

      +

      Alex: First, 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). Then, 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.". After that, 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.". Finally, 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. Treat it like a recipe: do not add the next ingredient until the previous one is actually in the bowl.

      +

      Jamie: Let's pause on Practice 10.3 Step-by-Step: Push and Open a Linked PR. What should a learner take away from it?

      +

      Alex: Here is the plain-English version of Practice 10.3 Step-by-Step: Push and Open a Linked PR. Push your branch to GitHub and open a PR in your Learning Room repo that references your challenge issue. Put another way, VS Code (for the push) and GitHub.com (for the PR).

      +

      Alex: First, open the Command Palette: Ctrl+Shift+P (Mac: Cmd+Shift+P). Then, 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. After that, 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. Finally, open your browser and navigate to your Learning Room repository on GitHub. Treat it like a recipe: do not add the next ingredient until the previous one is actually in the bowl.

      +

      Jamie: Before we leave Practice 10.3 Step-by-Step: Push and Open a Linked PR, what is the practical point?

      +

      Alex: First, GitHub usually shows a yellow banner: "yourname recently pushed to learn/yourname." Activate the Compare & pull request button in that banner. Then, 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/your username branch. After that, in the PR title, write a descriptive title (for example: "docs: improve welcome.md introduction"). Finally, 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. It is a checklist, but a meaningful one: every item creates evidence that the next step is safe.

      -

      Jamie: If I am listening before the workshop starts, what should settle in my mind first?

      -

      Alex: Keep the learner anchored in Staging files. Every file with a checked checkbox will be included in your next commit.

      -

      Alex: These are the details that keep the idea from floating away. Check all -- click the checkbox at the top of the list to stage everything. Uncheck a file to exclude it from the commit (it stays as an uncommitted change).

      -

      Jamie: Let's pause on Staging individual lines (hunks). What should a learner take away from it?

      -

      Alex: The reason Staging individual lines (hunks) matters is that if a file has multiple changes and you only want to commit some of them.

      -

      Alex: First, select the file in the Changes list. Then, in the diff view, right-click a line or block. After that, select "Stage Line" or "Stage Hunk" -- only those lines get included in the commit. The rhythm is simple: orient, act, verify, then continue.

      -

      Jamie: Let's pause on Writing your commit message. What should a learner take away from it?

      -

      Alex: Start with Writing your commit message: GitHub Copilot can help: Not sure what to write? The next useful detail is this: Open VS Code alongside GitHub Desktop, open Copilot Chat, and ask: "Write a commit message for these changes: [describe what you changed]." Or use the conventional commit format: feat:, fix:, docs:, refactor.

      -

      Alex: First, in the Summary field at the bottom, type a short commit message (under 72 characters is ideal). Then, optionally add a longer description in the Description field below it. After that, select "Commit to [branch name]" -- your changes are committed locally. Think of it as a rail line: each stop confirms you are still on the right route before the next one.

      +

      Jamie: What makes this practice feel low-stakes but still real?

      +

      Alex: This is where Completing Challenge 10: Submit Your Evidence becomes real: open your assigned Challenge 10 issue in your Learning Room repo and post a completion comment. That matters in practice: Close your Challenge 10 issue when your branch is pushed and the PR is open.

      +

      Alex: That connects to another useful point. Start with Expected Outcomes. There is something to understand, something to try, and something that proves the try worked.

      +

      Alex: For a learner, the useful signals are these. 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.

      +

      Jamie: Let's pause on If You Get Stuck. What should a learner take away from it?

      +

      Alex: The reason If You Get Stuck matters is that continue learning: The GitHub Skills course Introduction to Git walks through commits, branches, and merges in an interactive, self-paced format. That gives the learner a simple foothold: see Appendix Z for the full catalog.

      +

      Alex: First, command Palette does not open? Confirm you are in VS Code (not the browser) and press Ctrl+Shift+P (Mac: Cmd+Shift+P). Then, source Control panel is empty? You may not have saved your file yet. Press Ctrl+S to save, then check again. After that, 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. Finally, branch name wrong? Open Command Palette, run Git: Rename Branch. to fix it before pushing. The rhythm is simple: orient, act, verify, then continue.

      +

      Jamie: Before we leave If You Get Stuck, what is the practical point?

      +

      Alex: First, cannot find the "Compare & pull request" banner on GitHub? Navigate to Pull requests tab and create the PR manually (step 6 above). Then, 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. After that, ask facilitator to verify your clone location, branch name, and help with one push. Finally, finished but not sure you did it right? Compare your work against the Challenge 10 reference solution. Think of it as a rail line: each stop confirms you are still on the right route before the next one.

      -

      Alex: This is the part worth saying out loud. Here is the plain-English version of 8. Push and Pull. After committing, your changes are saved locally but not yet on GitHub. Put another way, the Fetch/Push button in the top-right toolbar handles syncing. It is like learning a transit route. The names of the stops matter because they tell you whether you are still going the right direction.

      -

      Jamie: What would you say to someone who is already bracing for this to be too much?

      -

      Alex: This is where Pushing commits to GitHub becomes real: after committing, the button changes to "Push origin" with an upward arrow and the number of commits waiting.

      -

      Alex: On the ground, that means a few things. Click "Push origin" -- your commits go to GitHub.

      -

      Alex: That connects to another useful point. Keep the learner anchored in Pulling changes from GitHub. When collaborators have pushed new commits, the button shows "Pull origin" with a downward arrow.

      -

      Alex: Here is what that changes in practice. Click "Pull origin" -- GitHub Desktop downloads the new commits and updates your local branch.

      +

      Alex: Here is the practical turn. Start with Learning Moment: Local Git operations give you full control and immediate feedback. The next useful detail is this: You can see your changes, review them, and fix mistakes before they reach GitHub.

      +

      Jamie: Let's pause on Learning Pattern Used in This Chapter. What should a learner take away from it?

      +

      Alex: Start with Learning Pattern Used in This Chapter. There is something to understand, something to try, and something that proves the try worked.

      +

      Alex: First, clone once to get a local copy of the project. Then, branch before editing (never work directly on main). After that, make small, focused edits with clear commit messages. Finally, push and open a PR that links to an issue for traceability. Treat it like a recipe: do not add the next ingredient until the previous one is actually in the bowl.

      +

      Jamie: Before we leave Learning Pattern Used in This Chapter, what is the practical point?

      +

      Alex: First, verify each step before moving to the next. It is a checklist, but a meaningful one: every item creates evidence that the next step is safe.

      +

      Alex: Keep the thread going. This is where About Learning Cards becomes real: throughout this chapter, each major operation includes learning cards - expandable sections showing how to accomplish the same task from multiple perspectives. That matters in practice: Open the card that matches how you work. The workshop is closer to rehearsal than lecture. You hear the move, try the move, and then check what changed.

      +

      Jamie: Let's pause on Tool Cards: Clone a Repository (Day 2). What should a learner take away from it?

      +

      Alex: Keep the learner anchored in Tool Cards: Clone a Repository (Day 2). VS Code Desktop (primary for Day 2). This is the part to say slowly: github.dev (web editor): No clone needed.

      +

      Alex: First, ctrl+Shift+P Git: Clone paste the HTTPS URL choose a folder Open. Then, file Clone Repository paste URL or select from your account Clone. It is like walking a hallway with named doors: read the sign, enter the right room, then confirm where you landed.

      +

      Alex: Treat examples as spoken recipes, not decorations. You may hear something like git clone https://github.com/owner/repo.git && cd repo. gh repo clone owner/repo && cd repo. Read the command, understand what it changes, then run it only when the repository state matches the lesson.

      +

      Jamie: Let's pause on Method 1: Command Palette (Recommended for Screen Readers). What should a learner take away from it?

      +

      Alex: Start with Method 1: Command Palette (Recommended for Screen Readers). There is something to understand, something to try, and something that proves the try worked.

      +

      Alex: First, open Command Palette: Ctrl+Shift+P (Mac: Cmd+Shift+P). Then, type "git clone". After that, select "Git: Clone". Finally, paste the repository URL (example: https://github.com/community-access/accessibility-agents.git). The rhythm is simple: orient, act, verify, then continue.

      +

      Jamie: Before we leave Method 1: Command Palette (Recommended for Screen Readers), what is the practical point?

      +

      Alex: First, press Enter. Then, choose a local folder where the repository should be cloned. After that, VS Code asks: "Would you like to open the cloned repository?" - select "Open". Think of it as a rail line: each stop confirms you are still on the right route before the next one.

      +

      Alex: A solid navigation habit is to prove where you are before activating controls. Headings, landmarks, and the address bar are not trivia; they are your map.

      Jamie: Where do you want a learner to place their attention here?

      -

      Alex: Start with Fetching (checking without pulling). There is something to understand, something to try, and something that proves the try worked.

      -

      Alex: That becomes easier when you listen for these cues. Click "Fetch origin" -- GitHub Desktop checks for new commits and shows you the count, but doesn't update your files yet. This is safe to do at any time -- it's read-only.

      -

      Jamie: Let's pause on 9. Syncing Your Fork. What should a learner take away from it?

      -

      Alex: Start with 9. Syncing Your Fork: If you forked a repository and the original upstream repo has new commits you want to bring in. Think of it like entering a new building: first you find the lobby, then the room, then the door you actually need.

      -

      Alex: First, go to Branch → Merge into current branch. Then, in the branch picker, switch to the "Other branches" tab. After that, select upstream/main (or upstream/master) -- the upstream remote's default branch. Finally, select "Create a merge commit". Think of it as a rail line: each stop confirms you are still on the right route before the next one.

      -

      Jamie: Before we leave 9. Syncing Your Fork, what is the practical point?

      -

      Alex: First, then push to your fork with "Push origin". Treat it like a recipe: do not add the next ingredient until the previous one is actually in the bowl.

      -

      Jamie: Let's pause on Setting up the upstream remote (if not already there). What should a learner take away from it?

      -

      Alex: Here is the plain-English version of Setting up the upstream remote (if not already there). GitHub Desktop adds the upstream remote automatically when you clone a fork from GitHub.com.

      -

      Alex: First, open the repository in terminal: Repository → Open in Terminal. Then, switch back to GitHub Desktop -- it will now see the upstream branches. Treat it like a recipe: do not add the next ingredient until the previous one is actually in the bowl.

      -

      Alex: Treat examples as spoken recipes, not decorations. You may hear something like git remote add upstream https://github.com/ORIGINAL-OWNER/ORIGINAL-REPO.git; git fetch upstream. Read the command, understand what it changes, then run it only when the repository state matches the lesson.

      +

      Alex: Start with Screen reader navigation. There is something to understand, something to try, and something that proves the try worked.

      +

      Alex: A few details make that real. 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.

      -

      Alex: That matters because of the next idea. This is where 10. Resolving Merge Conflicts becomes real: when you pull from GitHub or merge a branch and there are conflicts, GitHub Desktop shows a dialog listing the conflicting files.

      -

      Jamie: Let's pause on Step by step. What should a learner take away from it?

      -

      Alex: Start with Step by step. There is something to understand, something to try, and something that proves the try worked.

      -

      Alex: The practical anchors are these. "Open in [your editor]" -- opens the file with conflict markers for manual editing. "Use mine" / "Use theirs" -- accept one entire side of the conflict without editing.

      -

      Alex: First, GitHub Desktop shows a "Resolve conflicts before merging" screen. Then, each conflicting file has two options next to it. After that, for simple conflicts (one side is clearly right), use "Use mine" or "Use theirs". Finally, for conflicts where you need to keep parts of both, select "Open in [editor]" and resolve manually. It is like walking a hallway with named doors: read the sign, enter the right room, then confirm where you landed.

      -

      Jamie: Let's pause on After resolving in your editor. What should a learner take away from it?

      -

      Alex: The reason After resolving in your editor matters is that GitHub Copilot can help: Open the conflicting file in VS Code alongside GitHub Desktop. That gives the learner a simple foothold: place your cursor inside a conflict region and open Copilot Chat (Ctrl+Shift+I): "Resolve this merge conflict -- keep meaningful changes from both sides." Copilot suggests a resolution; you review and save. The interface gets friendlier when it stops being a wall of controls and starts being a set of named places.

      -

      Alex: First, save the file. Then, switch back to GitHub Desktop -- the file moves from "Conflicting" to "Resolved". After that, once all conflicts are resolved, select "Continue merge". The rhythm is simple: orient, act, verify, then continue.

      +

      Jamie: Let's pause on Method 2: Start Page Clone Button. What should a learner take away from it?

      +

      Alex: Here is the plain-English version of Method 2: Start Page Clone Button. The Start page is keyboard-accessible. Put another way, tab to navigate between "New File," "Open Folder," and "Clone Repository" buttons. It is like learning a transit route. The names of the stops matter because they tell you whether you are still going the right direction.

      +

      Alex: First, open VS Code (no folder open). Then, the Start page appears. After that, navigate to "Clone Git Repository" button - press Enter. Finally, paste repository URL → Enter. Treat it like a recipe: do not add the next ingredient until the previous one is actually in the bowl.

      +

      Jamie: Before we leave Method 2: Start Page Clone Button, what is the practical point?

      +

      Alex: First, choose destination folder. Then, open when prompted. It is a checklist, but a meaningful one: every item creates evidence that the next step is safe.

      +

      Jamie: Let's pause on Method 3: From GitHub.com. What should a learner take away from it?

      +

      Alex: Start with Method 3: From GitHub.com. There is something to understand, something to try, and something that proves the try worked.

      +

      Alex: First, on any GitHub repository page, click the green "Code" button. Then, copy the HTTPS URL (recommended) or SSH URL. After that, open VS Code → Ctrl+Shift+P (Mac: Cmd+Shift+P) → "Git: Clone". Finally, paste URL → Enter. It is a checklist, but a meaningful one: every item creates evidence that the next step is safe.

      +

      Jamie: Before we leave Method 3: From GitHub.com, what is the practical point?

      +

      Alex: First, choose destination → Open. It is like walking a hallway with named doors: read the sign, enter the right room, then confirm where you landed.

      +

      Jamie: Let's pause on Learning Cards: Cloning a Repository. What should a learner take away from it?

      +

      Alex: Keep the learner anchored in Learning Cards: Cloning a Repository. Low vision users (zoom, high contrast). This is the part to say slowly: Cloning works the same as the Command Palette method above.

      +

      Alex: First, 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. Then, 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. After that, 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. Finally, 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. It is like walking a hallway with named doors: read the sign, enter the right room, then confirm where you landed.

      +

      Jamie: Before we leave Learning Cards: Cloning a Repository, what is the practical point?

      +

      Alex: First, navigate to the repository on GitHub.com. Then, press. (period) to open github.dev - a browser-based VS Code editor. After that, the full repository opens in an editor with file tree, search, and editing. Finally, changes are committed directly to GitHub from the browser. The rhythm is simple: orient, act, verify, then continue.

      +

      Alex: Treat examples as spoken recipes, not decorations. You may hear something like 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. Read the command, understand what it changes, then run it only when the repository state matches the lesson.

      -

      Jamie: Give me the version that sounds like an instructor, not a manual.

      -

      Alex: Start with 11. Viewing History: The History tab (next to the Changes tab in the left panel) shows every commit on the current branch.

      -

      Jamie: Let's pause on Navigating history. What should a learner take away from it?

      -

      Alex: Start with Navigating history. There is something to understand, something to try, and something that proves the try worked.

      -

      Alex: First, click the History tab. Then, each commit appears as a row: author avatar, commit message, author name, and timestamp. After that, click any commit to see the full diff on the right -- what changed in each file. Treat it like a recipe: do not add the next ingredient until the previous one is actually in the bowl.

      -

      Jamie: Let's pause on Filtering commits. What should a learner take away from it?

      -

      Alex: This is where Filtering commits becomes real: type in the search field above the commit list to filter by commit message, author, or SHA.

      +

      Jamie: How do these exercises create confidence instead of pressure?

      +

      Alex: The reason Try It Now: Clone the Sci-Fi Themes Repo matters is that to make your first clone meaningful and fun, try cloning the VS Code Sci-Fi Thinking Phrases repository. That gives the learner a simple foothold: repository URL: https://github.com/community-access/vscode-sci-fi-themes.git.

      +

      Alex: The parts worth keeping in working memory are these. 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.

      +

      Alex: Another way to ground it. Start with Why Clone This? There is something to understand, something to try, and something that proves the try worked.

      +

      Alex: On the ground, that means a few things. 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!

      +

      Jamie: Let's pause on Quick Start. What should a learner take away from it?

      +

      Alex: Here is the plain-English version of Quick Start. See CLONE-THIS-REPO.md in that repo for full instructions. Put another way, if you prefer not to clone locally, you can work entirely on GitHub.com.

      +

      Alex: First, clone: Ctrl+Shift+P → "Git: Clone" → paste URL above → Enter. Then, choose a destination folder and open when prompted. After that, navigate to the themes/ folder and pick a.json file (star-trek, hitchhikers, or star-wars). Finally, copy the chat.agent.thinking.phrases setting into your VS Code settings.json. Treat it like a recipe: do not add the next ingredient until the previous one is actually in the bowl.

      +

      Jamie: Before we leave Quick Start, what is the practical point?

      +

      Alex: First, reload VS Code: Ctrl+Shift+P → "Developer: Reload Window". Then, open Copilot Chat (Ctrl+Shift+I) and ask a question--watch your custom phrases appear! After that, navigate to the repository on GitHub. Finally, click any file to view it, then click the pencil icon (Edit) to modify it directly in the browser. It is a checklist, but a meaningful one: every item creates evidence that the next step is safe.

      +

      Alex: Treat examples as spoken recipes, not decorations. You may hear something like 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. Read the command, understand what it changes, then run it only when the repository state matches the lesson.

      -

      Jamie: Let's pause on Viewing a specific file's history. What should a learner take away from it?

      -

      Alex: Start with Viewing a specific file's history. There is something to understand, something to try, and something that proves the try worked.

      -

      Alex: First, right-click any file in your project (via the Files panel in the diff area). Then, select "Show in History" -- the commit list filters to only commits that touched that file. It is like walking a hallway with named doors: read the sign, enter the right room, then confirm where you landed.

      -

      Jamie: Let's pause on Comparing branches. What should a learner take away from it?

      -

      Alex: Start with Comparing branches. There is something to understand, something to try, and something that proves the try worked.

      -

      Alex: First, click History. Then, in the branch comparison bar above the commit list, switch to another branch. After that, GitHub Desktop shows the commits that are different between your current branch and the selected branch. The rhythm is simple: orient, act, verify, then continue.

      -

      Alex: Here is the practical turn. Start with 12. Cherry-Pick in GitHub Desktop: Cherry-pick lets you take a commit from another branch and apply it to your current branch -- without merging the whole branch.

      +

      Alex: Before the learner moves on. This is where 2. The Source Control Panel - Complete Walkthrough becomes real: the Source Control panel (Ctrl+Shift+G - Mac: Cmd+Shift+G) is where all Git operations happen in VS Code. That matters in practice: This section provides a complete screen reader walkthrough of every interactive element.

      +

      Jamie: Give me the version that sounds like an instructor, not a manual.

      +

      Alex: Keep the learner anchored in Opening the Source Control Panel. Shortcut: Ctrl+Shift+G (Mac: Cmd+Shift+G).

      +

      Alex: This is the part worth saying out loud. Start with What opens. There is something to understand, something to try, and something that proves the try worked.

      +

      Alex: That becomes easier when you listen for these cues. 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).

      -

      Jamie: Let's pause on How to cherry-pick. What should a learner take away from it?

      -

      Alex: Start with How to cherry-pick. There is something to understand, something to try, and something that proves the try worked.

      -

      Alex: First, switch to the branch you want to copy the commit FROM (the source branch). Then, open the History tab. After that, find the commit you want to copy. Finally, right-click the commit. Treat it like a recipe: do not add the next ingredient until the previous one is actually in the bowl.

      -

      Jamie: Before we leave How to cherry-pick, what is the practical point?

      -

      Alex: First, select "Cherry-pick commit.". Then, choose the destination branch -- the branch you want to apply the commit TO. After that, GitHub Desktop applies the commit and switches to the destination branch. It is a checklist, but a meaningful one: every item creates evidence that the next step is safe.

      -

      Alex: Another way to ground it. This is where If there's a conflict becomes real: GitHub Desktop shows the conflict resolution screen (same as merging). That matters in practice: Resolve the conflicts in your editor, then switch back to GitHub Desktop to continue. The workshop is closer to rehearsal than lecture. You hear the move, try the move, and then check what changed.

      -

      Jamie: Let's pause on 13. Stashing Changes. What should a learner take away from it?

      -

      Alex: Keep the learner anchored in 13. Stashing Changes. Stash saves your uncommitted changes temporarily so you can switch branches or pull without committing half-finished work.

      +

      Jamie: Let's pause on Panel structure from top to bottom. What should a learner take away from it?

      +

      Alex: Start with Panel structure from top to bottom. There is something to understand, something to try, and something that proves the try worked.

      +

      Alex: The practical anchors are these. Branch name displayed (example: "main" or "feature/add-documentation"). View/More Actions button (three dots menu). Type your commit message here. Announced as "Source Control Input, edit, multi-line". Shortcut: Ctrl+Enter (Mac: Cmd+Enter) when focused in the message input. Lists all modified files not yet staged.

      +

      Alex: First, source Control title bar (heading level 2). Then, commit message input (multi-line text field). After that, commit button (or "Publish Branch" if this is a new branch). Finally, changes section (collapsible tree). Think of it as a rail line: each stop confirms you are still on the right route before the next one.

      +

      Jamie: Before we leave Panel structure from top to bottom, what is the practical point?

      +

      Alex: First, staged Changes section (collapsible tree). Then, merge Changes section (appears only during a merge). Treat it like a recipe: do not add the next ingredient until the previous one is actually in the bowl.

      +

      Alex: Hold that next to this. Start with NVDA/JAWS. There is something to understand, something to try, and something that proves the try worked.

      +

      Alex: Here is what that changes in practice. 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).

      +

      Jamie: If I am listening before the workshop starts, what should settle in my mind first?

      +

      Alex: This is where VoiceOver becomes real: key point: The Source Control panel is not a standard file tree. That matters in practice: It's a specialized Git status view.

      +

      Alex: These are the details that keep the idea from floating away. Navigate with VO+Arrow keys. VO+Space to activate (open diff or stage/unstage). The panel is announced as a "group" containing lists.

      -

      Jamie: Let's pause on Stash your changes. What should a learner take away from it?

      -

      Alex: Start with Stash your changes. There is something to understand, something to try, and something that proves the try worked.

      -

      Alex: First, go to Branch → Stash All Changes (or press Ctrl+Shift+H / Cmd+Shift+H). Then, your working directory reverts to the last commit. After that, you can now switch branches safely. The rhythm is simple: orient, act, verify, then continue.

      -

      Jamie: Let's pause on Restore your stash. What should a learner take away from it?

      -

      Alex: Start with Restore your stash: GitHub Desktop supports one stash at a time per branch. The next useful detail is this: For multiple stashes, use the Git CLI: git stash list, git stash apply stash@{1}.

      -

      Alex: First, switch back to the branch where you stashed. Then, go to Branch → Pop Stash. After that, your changes come back. Think of it as a rail line: each stop confirms you are still on the right route before the next one.

      -

      Alex: Before the learner moves on. Here is the plain-English version of Undo the last commit. Go to Edit → Undo Last Commit (or press Ctrl+Z / Cmd+Z right after committing). Put another way, this is equivalent to git reset --soft HEAD 1 -- your changes come back as staged files. It is like learning a transit route. The names of the stops matter because they tell you whether you are still going the right direction.

      +

      Alex: The next layer is this. Keep the learner anchored in What Each File Shows. When a file appears in the Changes or Staged Changes list, VS Code shows a status letter. This is the part to say slowly: Screen reader announcement: "docs/GUIDE.md, Modified" or "README.md, Added". A good GitHub workflow is like a well-run meeting: everyone knows the topic, the next action, and who has the floor.

      +

      Jamie: Let's pause on Context Menu Actions (Right-Click or Shift+F10). What should a learner take away from it?

      +

      Alex: The reason Context Menu Actions (Right-Click or Shift+F10) matters is that when focused on any file in the Source Control panel. That gives the learner a simple foothold: use Shift+F10 to open the context menu.

      +

      Jamie: Let's pause on Learning Cards: Source Control Panel. What should a learner take away from it?

      +

      Alex: Start with Learning Cards: Source Control Panel: Low vision users (zoom, high contrast). The next useful detail is this: The Source Control panel adapts well to zoom and high contrast settings.

      +

      Alex: First, 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. Then, 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. After that, 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). Finally, 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. Think of it as a rail line: each stop confirms you are still on the right route before the next one.

      +

      Jamie: Before we leave Learning Cards: Source Control Panel, what is the practical point?

      +

      Alex: First, 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. Treat it like a recipe: do not add the next ingredient until the previous one is actually in the bowl.

      +

      Alex: Treat examples as spoken recipes, not decorations. You may hear something like 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. Read the command, understand what it changes, then run it only when the repository state matches the lesson.

      -

      Jamie: Let's pause on Discard changes to a file. What should a learner take away from it?

      -

      Alex: This is where Discard changes to a file becomes real: warning: Discarding changes cannot be undone. That matters in practice: The changes are permanently deleted, not moved to trash.

      -

      Alex: First, right-click a file. Then, select "Discard Changes.". After that, confirm the dialog -- the file reverts to its last committed state. It is a checklist, but a meaningful one: every item creates evidence that the next step is safe.

      -

      Jamie: Let's pause on Discard all changes. What should a learner take away from it?

      -

      Alex: Start with Discard all changes. There is something to understand, something to try, and something that proves the try worked.

      -

      Alex: First, right-click anywhere in the Changes list. Then, select "Discard All Changes.". After that, confirm -- everything in your working directory reverts to the last commit. It is like walking a hallway with named doors: read the sign, enter the right room, then confirm where you landed.

      -

      Jamie: Let's pause on 15. Accessibility and Screen Reader Notes. What should a learner take away from it?

      -

      Alex: The reason 15. Accessibility and Screen Reader Notes matters is that GitHub Desktop has partial screen reader support. That gives the learner a simple foothold: core workflows work well with keyboard navigation; some visual-only elements (like avatar images and some icons) don't have text equivalents.

      -

      Alex: A solid navigation habit is to prove where you are before activating controls. Headings, landmarks, and the address bar are not trivia; they are your map.

      +

      Jamie: Let's pause on 3. Branch Management. What should a learner take away from it?

      +

      Alex: Here is the plain-English version of 3. Branch Management. Branches are how you organize work in Git. Put another way, every repository starts with a main or master branch.

      +

      Jamie: Let's pause on Where it's shown. What should a learner take away from it?

      +

      Alex: Start with Where it's shown. There is something to understand, something to try, and something that proves the try worked.

      +

      Alex: First, bottom-left corner of VS Code (status bar) - visual users see it immediately. Then, source Control panel title bar. After that, command Palette: Ctrl+Shift+P (Mac: Cmd+Shift+P) → "Git: Show Git Output". It is a checklist, but a meaningful one: every item creates evidence that the next step is safe.

      +

      Jamie: Let's pause on Keyboard access to status bar. What should a learner take away from it?

      +

      Alex: Keep the learner anchored in Keyboard access to status bar. Visual users: You can also click the branch name in the bottom-left status bar to open the branch picker directly.

      +

      Alex: The practical takeaway is this. The status bar is not in the standard keyboard navigation flow. Use the Command Palette for branch operations instead.

      -

      Alex: Hold that next to this. Start with Windows -- NVDA / JAWS. There is something to understand, something to try, and something that proves the try worked.

      -

      Alex: The practical takeaway is this. Use Tab to move between panels; arrow keys within lists. The commit summary field is reached with Tab after the file list. Conflict dialogs are modal -- screen reader focus moves into the dialog automatically.

      -

      Jamie: Let's pause on macOS -- VoiceOver. What should a learner take away from it?

      -

      Alex: Start with macOS -- VoiceOver. There is something to understand, something to try, and something that proves the try worked.

      -

      Alex: The practical takeaway is this. Use Tab and VO+Arrow to navigate panels. The diff view can be explored with VO+Right through the lines. Branch selector opens a searchable popup -- type to filter, Down Arrow to navigate, Return to select.

      -

      Alex: Keep the teaching thread moving. This is where VS Code as a better accessible alternative becomes real: if screen reader navigation in GitHub Desktop is frustrating for a specific operation, VS Code's Source Control panel is often more accessible. That matters in practice: The two tools complement each other -- use whichever works best for the task at hand.

      +

      Jamie: Let's pause on Command Palette method (recommended). What should a learner take away from it?

      +

      Alex: Start with Command Palette method (recommended). There is something to understand, something to try, and something that proves the try worked.

      +

      Alex: The practical takeaway is this. Creates the branch. Switches to it automatically. Your working files stay exactly as they were.

      +

      Alex: First, ctrl+Shift+P (Mac: Cmd+Shift+P). Then, type "git create branch". After that, select "Git: Create Branch.". Finally, type the new branch name (example: feature/improve-docs). The rhythm is simple: orient, act, verify, then continue.

      +

      Jamie: Before we leave Command Palette method (recommended), what is the practical point?

      +

      Alex: First, press Enter. Think of it as a rail line: each stop confirms you are still on the right route before the next one.

      +

      Jamie: Let's pause on Naming conventions. What should a learner take away from it?

      +

      Alex: Start with Naming conventions: Web alternative (github.com) - branch management. The next useful detail is this: Create and switch branches without leaving your browser.

      +

      Alex: The practical takeaway is this. Use lowercase with hyphens: feature/add-timeline-guide. Avoid spaces and special characters. Be descriptive: fix/heading-hierarchy not fix1.

      +

      Alex: First, on the repository page, click the branch dropdown (shows "main" by default). Then, type a new branch name in the search field. After that, click "Create branch: your-branch-name from main". Finally, GitHub switches to the new branch immediately. Think of it as a rail line: each stop confirms you are still on the right route before the next one.

      +

      Jamie: Before we leave Naming conventions, what is the practical point?

      +

      Alex: First, any file edits you make in the browser will be on this branch. Treat it like a recipe: do not add the next ingredient until the previous one is actually in the bowl.

      +

      Alex: Treat examples as spoken recipes, not decorations. You may hear something like 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. Read the command, understand what it changes, then run it only when the repository state matches the lesson.

      +

      Jamie: Let's pause on Command Palette method. What should a learner take away from it?

      +

      Alex: Here is the plain-English version of Command Palette method. Screen reader announcement: "Branch: main" or "Branch: feature/add-timeline-guide". It is like learning a transit route. The names of the stops matter because they tell you whether you are still going the right direction.

      +

      Alex: First, ctrl+Shift+P (Mac: Cmd+Shift+P). Then, type "git checkout". After that, select "Git: Checkout to.". Finally, a list of all branches appears. Treat it like a recipe: do not add the next ingredient until the previous one is actually in the bowl.

      +

      Jamie: Before we leave Command Palette method, what is the practical point?

      +

      Alex: First, up/Down Arrow to navigate. Then, enter to switch. It is a checklist, but a meaningful one: every item creates evidence that the next step is safe.

      -

      Jamie: There are a lot of tools in play. How do we keep that from feeling like a contest?

      -

      Alex: Start with Learning Cards: Desktop Accessibility. There is something to understand, something to try, and something that proves the try worked.

      -

      Alex: The practical takeaway is this. Commit message fields, branch selector, and conflict resolution buttons are fully keyboard-accessible and announced. The diff panel has partial screen reader support -- for difficult diffs, switch to VS Code's Accessible Diff Viewer (F7 / Alt+F2). Use Shift+F10 on Windows to open context menus via keyboard when right-click actions are needed. File status icons (M, A, D) are small -- increase OS scaling or watch for the filename and status text that accompany them. The conflict resolution dialog uses labeled buttons ("Use mine", "Use theirs") that are easy to identify at any zoom level. If diff colors are indistinguishable at your contrast settings, open the same file in VS Code for richer theme support.

      -

      Jamie: What decision is this helping them make?

      -

      Alex: The reason 16. GitHub Desktop vs VS Code vs Git CLI -- When to Use Each matters is that GitHub Desktop, VS Code, and the Git CLI all talk to the same Git repository. That gives the learner a simple foothold: you can switch between them freely -- use GitHub Desktop to stage and commit, then open the terminal for a git rebase -i. The interface gets friendlier when it stops being a wall of controls and starts being a set of named places.

      -

      Alex: Use the comparison to make a decision, not to recite a table. The main contrasts are: Situation means Best tool. You want a clean visual overview of changes before committing means GitHub Desktop. You want to stage individual lines or hunks means GitHub Desktop or VS Code.

      +

      Jamie: Let's pause on What happens when you switch. What should a learner take away from it?

      +

      Alex: Start with What happens when you switch. There is something to understand, something to try, and something that proves the try worked.

      +

      Alex: The practical takeaway is this. 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).

      +

      Jamie: Let's pause on After your PR is merged, you can delete the branch. What should a learner take away from it?

      +

      Alex: Keep the learner anchored in After your PR is merged, you can delete the branch. You cannot delete the branch you're currently on.

      +

      Alex: First, ctrl+Shift+P (Mac: Cmd+Shift+P). Then, type "git delete branch". After that, select "Git: Delete Branch.". Finally, choose the branch to delete from the list. It is like walking a hallway with named doors: read the sign, enter the right room, then confirm where you landed.

      +

      Jamie: What should they understand before typing anything?

      +

      Alex: The reason Viewing All Branches matters is that command: Ctrl+Shift+P → "Git: Show Git Output" → Branch list appears. That gives the learner a simple foothold: alternative: Use the integrated terminal.

      +

      Alex: Treat examples as spoken recipes, not decorations. You may hear something like git branch Local branches only; git branch -a All branches (including remote). Read the command, understand what it changes, then run it only when the repository state matches the lesson.

      -

      Jamie: What should people carry with them after this?

      -

      Alex: Carry the map. Know what page or tool you are in, know which action you are taking, and know what confirmation should follow. If the confirmation is missing, pause. That pause is not wasted time; it is professional judgment.

      -

      Jamie: That is a better way to say it than just follow the steps.

      -

      Alex: Right. Steps matter, but understanding wins. That is episode 52. Next in the series is episode 53, where we keep building the same contributor muscles.

      -
      - +

      Jamie: Let's pause on Learning Cards: Branch Management. What should a learner take away from it?

      +

      Alex: Start with Learning Cards: Branch Management: Low vision users (zoom, high contrast). The next useful detail is this: Screen reader users (NVDA / JAWS on Windows). Think of it like entering a new building: first you find the lobby, then the room, then the door you actually need.

      +

      Alex: First, 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. Then, 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. After that, 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. Think of it as a rail line: each stop confirms you are still on the right route before the next one.

      +

      Jamie: Let's pause on Creating a branch. What should a learner take away from it?

      +

      Alex: Start with Creating a branch. There is something to understand, something to try, and something that proves the try worked.

      +

      Alex: First, press Ctrl+Shift+P to open the Command Palette. Then, type "git create branch" - NVDA/JAWS announces results as you type. After that, press Enter on "Git: Create Branch.". Finally, the input focus moves to a text field - type your branch name (e.g., feature/add-docs). Treat it like a recipe: do not add the next ingredient until the previous one is actually in the bowl.

      +

      Jamie: Before we leave Creating a branch, what is the practical point?

      +

      Alex: First, press Enter - VS Code creates and switches to the branch. Then, NVDA/JAWS announces the new branch name in the status bar notification. It is a checklist, but a meaningful one: every item creates evidence that the next step is safe.

      +

      Jamie: Let's pause on Switching branches. What should a learner take away from it?

      +

      Alex: Start with Switching branches. There is something to understand, something to try, and something that proves the try worked.

      +

      Alex: First, press Ctrl+Shift+P, type "git checkout". Then, select "Git: Checkout to.". After that, a list of branches appears - navigate with Up/Down Arrow. Finally, each item is announced as the branch name (e.g., "main", "feature/add-docs"). It is a checklist, but a meaningful one: every item creates evidence that the next step is safe.

      +

      Jamie: Before we leave Switching branches, what is the practical point?

      +

      Alex: First, press Enter to switch. Then, VS Code reloads files for that branch - you hear a status bar update. It is like walking a hallway with named doors: read the sign, enter the right room, then confirm where you landed.

      -

      Episode 53: GitHub CLI Reference

      -

      Using the GitHub CLI for issues, pull requests, authentication, and automation-friendly workflows.

      -

      Based on: Appendix I: GitHub CLI Reference

      -

      Audio and transcript are being regenerated for this episode.

      -
      -Read Transcript - Episode 53: GitHub CLI Reference - -

      Transcript

      -

      Alex: Welcome back to Git Going with GitHub. This is episode 53: GitHub CLI Reference. I am Alex, and today we are turning GitHub CLI Reference from a list of instructions into a working mental model.

      -

      Jamie: And I am Jamie. I will stop us whenever the instructions sound simple on paper but might feel different with a keyboard and screen reader.

      +

      Jamie: Let's pause on Deleting a branch. What should a learner take away from it?

      +

      Alex: Keep the learner anchored in Deleting a branch. Screen reader users (VoiceOver on macOS).

      +

      Alex: First, switch to a different branch first (you cannot delete the branch you are on). Then, press Ctrl+Shift+P, type "git delete branch". After that, select "Git: Delete Branch.". Finally, navigate the list to find the branch to delete, press Enter. It is like walking a hallway with named doors: read the sign, enter the right room, then confirm where you landed.

      +

      Jamie: What is the teaching move inside Creating a branch?

      +

      Alex: First, press Cmd+Shift+P to open the Command Palette. Then, type "git create branch" - VoiceOver announces filtered results. After that, press Return on "Git: Create Branch.". Finally, type the branch name in the input field. The rhythm is simple: orient, act, verify, then continue.

      +

      Jamie: If someone only remembers one thing from Creating a branch, what should it be?

      +

      Alex: First, press Return to create and switch. Think of it as a rail line: each stop confirms you are still on the right route before the next one.

      +

      Jamie: What is the teaching move inside Switching branches?

      +

      Alex: First, press Cmd+Shift+P, type "git checkout". Then, select "Git: Checkout to.". After that, use VO+Down Arrow to navigate the branch list. Finally, press Return to switch. Think of it as a rail line: each stop confirms you are still on the right route before the next one.

      -

      Alex: Using the GitHub CLI for issues, pull requests, authentication, and automation-friendly workflows. That is the surface description. Underneath it, we are building judgment: where to focus, what to ignore, and how to verify the result.

      -

      Jamie: So we are not using the audio as a shortcut around learning. We are using it to make the learning easier to enter.

      -

      Alex: Yes. A good audio lesson gives someone enough context to try the work with confidence, even before they open the written material.

      +

      Jamie: Let's pause on Getting the current branch name. What should a learner take away from it?

      +

      Alex: Here is the plain-English version of Getting the current branch name. Create and switch branches without leaving your browser. Put another way, manage branches from your terminal.

      +

      Alex: First, press VO+M to move to the menu bar, then VO+Right Arrow to the status bar area. Then, or use the Command Palette: Cmd+Shift+P then type "Git: Show Git Output" - the output pane includes the current branch. After that, on the repository page, find the branch dropdown button (shows "main" by default) - it is above the file table. Finally, click or activate the dropdown. Treat it like a recipe: do not add the next ingredient until the previous one is actually in the bowl.

      +

      Jamie: Before we leave Getting the current branch name, what is the practical point?

      +

      Alex: First, type a new branch name in the search field. Then, click "Create branch: your-branch-name from main" when it appears. After that, GitHub switches to the new branch immediately. Finally, any file edits in the browser will be on this branch. It is a checklist, but a meaningful one: every item creates evidence that the next step is safe.

      +

      Alex: Treat examples as spoken recipes, not decorations. You may hear something like 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. 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'. Read the command, understand what it changes, then run it only when the repository state matches the lesson.

      +

      Jamie: Let's pause on 4. Staging Changes - Files, Lines, and Chunks. What should a learner take away from it?

      +

      Alex: This is where 4. Staging Changes - Files, Lines, and Chunks becomes real: this lets you commit only part of your work, leaving the rest for a later commit.

      +

      Alex: First, stage the changes you want to include. Then, commit those staged changes. It is a checklist, but a meaningful one: every item creates evidence that the next step is safe.

      +

      Jamie: Let's pause on Staging an Entire File. What should a learner take away from it?

      +

      Alex: Keep the learner anchored in Staging an Entire File. Low vision users (zoom, high contrast). This is the part to say slowly: Screen reader users (NVDA / JAWS / VoiceOver). A good GitHub workflow is like a well-run meeting: everyone knows the topic, the next action, and who has the floor.

      +

      Alex: The practical takeaway is this. 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.

      +

      Alex: First, open Source Control: Ctrl+Shift+G (Mac: Cmd+Shift+G). Then, hover over a file in the "Changes" list - a + icon appears to its right. After that, click the + to stage that file. Finally, or right-click a file → "Stage Changes". It is like walking a hallway with named doors: read the sign, enter the right room, then confirm where you landed.

      +

      Jamie: Before we leave Staging an Entire File, what is the practical point?

      +

      Alex: First, at high zoom, the + (stage), undo (discard), and open file icons may be small. Instead of hovering. Then, 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. After that, in high contrast themes, staged files show a distinct background or border in the Staged Changes section. Finally, navigate to the file in the "Changes" list. The rhythm is simple: orient, act, verify, then continue.

      -

      Jamie: Okay, set the room for us. What are we walking into?

      -

      Alex: Start with Your Terminal, Supercharged for GitHub: Who this is for: You want to manage GitHub -- issues, pull requests, repos, releases -- from your terminal without opening a browser. The next useful detail is this: The GitHub CLI (gh) gives you full access to GitHub from the command line, with clean plain-text output that works beautifully with screen readers.

      -

      Alex: The next layer is this. Here is the plain-English version of Windows. Or download the installer from cli.github.com. It is like learning a transit route. The names of the stops matter because they tell you whether you are still going the right direction.

      -

      Jamie: What is the safe way to learn from that example?

      -

      Alex: Start with Verify installation. There is something to understand, something to try, and something that proves the try worked.

      -

      Alex: Treat examples as spoken recipes, not decorations. You may hear something like gh --version. Read the command, understand what it changes, then run it only when the repository state matches the lesson.

      +

      Jamie: Let's pause on Alternative (keyboard shortcut). What should a learner take away from it?

      +

      Alex: Start with Alternative (keyboard shortcut). There is something to understand, something to try, and something that proves the try worked.

      +

      Alex: The practical takeaway is this. Focus the file → press Space.

      +

      Alex: Keep the teaching thread moving. Start with Alternative (context menu). There is something to understand, something to try, and something that proves the try worked.

      +

      Alex: The practical takeaway is this. Focus the file → press Shift+F10 (Mac: Ctrl+Return) → select "Stage Changes".

      +

      Jamie: Let's pause on What happens. What should a learner take away from it?

      +

      Alex: Start with What happens. There is something to understand, something to try, and something that proves the try worked.

      +

      Alex: The practical takeaway is this. The file moves from "Changes" → "Staged Changes". A green "A" or "M" indicator appears.

      -

      Jamie: What should happen before anyone copies and runs it?

      -

      Alex: Keep the learner anchored in Authenticating. After signing in, return to the terminal. This is the part to say slowly: gh auth login is an interactive prompt -- navigate with Arrow keys, confirm with Enter.

      -

      Alex: For a learner, the useful signals are these. Where do you use GitHub? → GitHub.com (or Enterprise). Preferred protocol? → HTTPS (or SSH). Authenticate with browser? → Yes -- your browser opens for OAuth sign-in.

      -

      Alex: Treat examples as spoken recipes, not decorations. You may hear something like gh auth login. Check your auth status at any time; gh auth status; Log out; gh auth logout; Refresh credentials / add new scopes; gh auth refresh. Read the command, understand what it changes, then run it only when the repository state matches the lesson.

      -

      Jamie: What does someone need before they touch the keyboard?

      -

      Alex: Start with Learning Cards: Getting Started with gh. There is something to understand, something to try, and something that proves the try worked.

      -

      Alex: The parts worth keeping in working memory are these. gh auth login uses plain-text arrow-key prompts -- every option is announced as you arrow through the list. After authentication, gh auth status confirms your login in a single readable line -- no browser needed. All gh output is plain text with no hidden elements, making it one of the most screen-reader-friendly GitHub interfaces. Increase your terminal font size before running gh commands -- all output scales with your terminal settings. Use a high-contrast terminal theme (light text on dark background, or vice versa) for comfortable reading of command output. gh output is plain text with no color-dependent meaning -- colors are supplementary labels, not the only indicator.

      -

      Alex: The useful habit is simple: orient first, act second, verify third. That pause before acting is part of the work.

      -

      Jamie: How do you keep commands from becoming magic words?

      -

      Alex: Start with 2. Repos -- Clone, Fork, Create, View. There is something to understand, something to try, and something that proves the try worked.

      -

      Alex: Treat examples as spoken recipes, not decorations. You may hear something like Clone a repository (automatically sets up the remote); gh repo clone owner/repo-name; Fork a repo and clone your fork in one step; gh repo fork owner/repo-name --clone; Fork without cloning (creates the fork on GitHub only); gh repo fork owner/repo-name. Read the command, understand what it changes, then run it only when the repository state matches the lesson.

      +

      Jamie: Let's pause on Staging Multiple Files at Once. What should a learner take away from it?

      +

      Alex: This is where Staging Multiple Files at Once becomes real: all modified files move to "Staged Changes.". The workshop is closer to rehearsal than lecture. You hear the move, try the move, and then check what changed.

      +

      Alex: First, ctrl+Shift+G (Mac: Cmd+Shift+G) to open Source Control. Then, navigate to the "Changes" section heading. After that, press Shift+F10 (Mac: Ctrl+Return) to open context menu on the section itself. Finally, select "Stage All Changes". It is a checklist, but a meaningful one: every item creates evidence that the next step is safe.

      +

      Jamie: Let's pause on Staging Individual Lines or Chunks. What should a learner take away from it?

      +

      Alex: Keep the learner anchored in 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.

      +

      Jamie: Let's pause on Workflow. What should a learner take away from it?

      +

      Alex: The reason Workflow matters is that result: Only those lines are staged. That gives the learner a simple foothold: the rest of the file remains in "Changes.".

      +

      Alex: First, open Source Control: Ctrl+Shift+G (Mac: Cmd+Shift+G). Then, navigate to a file in "Changes". After that, press Enter to open the diff view. Finally, the diff shows your changes side-by-side or inline. The rhythm is simple: orient, act, verify, then continue.

      +

      Jamie: Before we leave Workflow, what is the practical point?

      +

      Alex: First, navigate to a changed line (use Arrow keys or F7 for next hunk). Then, press Shift+F10 (Mac: Ctrl+Return) to open context menu. After that, select "Stage Selected Lines". Think of it as a rail line: each stop confirms you are still on the right route before the next one.

      -

      Jamie: What should they understand before typing anything?

      -

      Alex: Start with Creating issues. There is something to understand, something to try, and something that proves the try worked.

      -

      Alex: Treat examples as spoken recipes, not decorations. You may hear something like Create an issue interactively (opens a prompt for title, body, labels, etc.); gh issue create; Create with all details inline; gh issue create ; --title "Screen reader can't navigate the settings menu" ; --body "When using NVDA with Firefox, the Settings. Read the command, understand what it changes, then run it only when the repository state matches the lesson.

      -

      Alex: A solid issue habit is to read the title, the body, and the timeline before acting. You are listening for the requested action, the missing evidence, and the person who needs a response.

      -

      Jamie: Let's pause on Listing and filtering issues. What should a learner take away from it?

      -

      Alex: Start with Listing and filtering issues. There is something to understand, something to try, and something that proves the try worked.

      -

      Alex: Treat examples as spoken recipes, not decorations. You may hear something like List open issues (current repo); gh issue list; List issues with filters; gh issue list --label "accessibility"; gh issue list --label "good first issue"; gh issue list --assignee "@me"; gh issue list --state closed; gh issue list --limit 50; Search issues by. Read the command, understand what it changes, then run it only when the repository state matches the lesson.

      -

      Jamie: Let's pause on Viewing issues. What should a learner take away from it?

      -

      Alex: Keep the learner anchored in Viewing issues. gh issue view 42 outputs clean plain text -- title, metadata, and body all formatted without noise. This is the part to say slowly: Much faster than navigating a browser page with a screen reader.

      -

      Alex: Treat examples as spoken recipes, not decorations. You may hear something like View an issue (renders Markdown as plain text in the terminal); gh issue view 42; Open the issue in your browser; gh issue view 42 --web; View comments on an issue; gh issue view 42 --comments. Read the command, understand what it changes, then run it only when the repository state matches the lesson.

      +

      Jamie: Let's pause on Use case for this workshop. What should a learner take away from it?

      +

      Alex: Start with Use case for this workshop: In the diff view, press Alt+H to see Accessible Help for diff-specific keyboard shortcuts. The next useful detail is this: Web alternative (github.com) - editing files.

      +

      Alex: The practical takeaway is this. 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".

      +

      Alex: First, click the pencil icon on any file to open the web editor. Then, make your changes. After that, click "Commit changes" - GitHub creates the commit directly. Finally, choose to commit to the current branch or create a new branch and PR. Think of it as a rail line: each stop confirms you are still on the right route before the next one.

      +

      Alex: Treat examples as spoken recipes, not decorations. You may hear something like 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. Read the command, understand what it changes, then run it only when the repository state matches the lesson.

      +

      Jamie: Let's pause on Reverse the process. What should a learner take away from it?

      +

      Alex: Start with Reverse the process. There is something to understand, something to try, and something that proves the try worked.

      +

      Alex: First, focus the file in "Staged Changes". Then, press Ctrl+Enter (Mac: Cmd+Enter) or Space. After that, file moves back to "Changes". Treat it like a recipe: do not add the next ingredient until the previous one is actually in the bowl.

      +

      Jamie: Let's pause on Learning Cards: Staging Changes. What should a learner take away from it?

      +

      Alex: Start with Learning Cards: Staging Changes. There is something to understand, something to try, and something that proves the try worked.

      +

      Alex: The practical takeaway is this. 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. 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.

      -

      Jamie: Let's pause on Commenting and updating. What should a learner take away from it?

      -

      Alex: Start with Commenting and updating. There is something to understand, something to try, and something that proves the try worked.

      -

      Alex: Treat examples as spoken recipes, not decorations. You may hear something like Add a comment to an issue; gh issue comment 42 --body "I can reproduce this on Windows 11 with NVDA 2024.1."; Comment from a file; gh issue comment 42 --body-file./my-comment.md; Edit an issue (title, body, labels, assignees); gh issue edit 42 --title "Updated. Read the command, understand what it changes, then run it only when the repository state matches the lesson.

      -

      Jamie: Let's pause on Pinning and locking. What should a learner take away from it?

      -

      Alex: Start with Pinning and locking. There is something to understand, something to try, and something that proves the try worked.

      -

      Alex: Treat examples as spoken recipes, not decorations. You may hear something like Pin an issue (shows at top of the Issues tab); gh issue pin 42; Lock an issue (prevents new comments); gh issue lock 42 --reason "resolved". Read the command, understand what it changes, then run it only when the repository state matches the lesson.

      -

      Jamie: Let's pause on Creating a PR. What should a learner take away from it?

      -

      Alex: Start with Creating a PR. There is something to understand, something to try, and something that proves the try worked.

      -

      Alex: Treat examples as spoken recipes, not decorations. You may hear something like Create a PR interactively (prompts for title, body, base branch, etc.); gh pr create; Create with all details inline; gh pr create ; --title "Add keyboard navigation to settings menu" ; --body "Closes 42. Adds Tab/arrow key support to the settings dropdown.". Read the command, understand what it changes, then run it only when the repository state matches the lesson.

      -

      Alex: A solid pull request habit is to separate three questions: what changed, why it changed, and what still needs review. That keeps the conversation useful instead of noisy.

      +

      Jamie: Let's pause on Standard process. What should a learner take away from it?

      +

      Alex: Start with Standard process. There is something to understand, something to try, and something that proves the try worked.

      +

      Alex: First, open Source Control: Ctrl+Shift+G (Mac: Cmd+Shift+G). Then, stage changes (see Section 4). After that, focus the commit message input (usually Tab or Shift+Tab to reach it). Finally, type your commit message. It is like walking a hallway with named doors: read the sign, enter the right room, then confirm where you landed.

      +

      Jamie: Before we leave Standard process, what is the practical point?

      +

      Alex: First, press Ctrl+Enter (Mac: Cmd+Enter) to commit. The rhythm is simple: orient, act, verify, then continue.

      +

      Jamie: Let's pause on Learning Cards: Committing. What should a learner take away from it?

      +

      Alex: The reason Learning Cards: Committing matters is that low vision users (zoom, high contrast).

      +

      Alex: First, open Source Control (Ctrl+Shift+G). Then, stage your files (click the + icon next to each file, or click Stage All Changes above the Changes section header). After that, click in the "Message" text area at the top of the Source Control panel. Finally, type your commit message. The rhythm is simple: orient, act, verify, then continue.

      +

      Jamie: Before we leave Learning Cards: Committing, what is the practical point?

      +

      Alex: First, click the Commit button (checkmark icon) or press Ctrl+Enter. Then, 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. After that, 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. Finally, 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. Think of it as a rail line: each stop confirms you are still on the right route before the next one.

      +

      Alex: Keep the teaching thread moving. Start with NVDA/JAWS. There is something to understand, something to try, and something that proves the try worked.

      +

      Alex: The practical takeaway is this. 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).

      -

      Jamie: Let's pause on Listing and viewing PRs. What should a learner take away from it?

      -

      Alex: Start with Listing and viewing PRs. There is something to understand, something to try, and something that proves the try worked.

      -

      Alex: Treat examples as spoken recipes, not decorations. You may hear something like List open PRs; gh pr list; List with filters; gh pr list --state closed; gh pr list --author "@me"; gh pr list --label "accessibility"; gh pr list --search "screen reader"; View a PR (title, description, status, checks); gh pr view 56; View the diff of a PR. Read the command, understand what it changes, then run it only when the repository state matches the lesson.

      -

      Jamie: Let's pause on Reviewing PRs. What should a learner take away from it?

      -

      Alex: Start with Reviewing PRs. There is something to understand, something to try, and something that proves the try worked.

      -

      Alex: Treat examples as spoken recipes, not decorations. You may hear something like Approve a PR; gh pr review 56 --approve; gh pr review 56 --approve --body "Tested with NVDA -- keyboard nav works perfectly. LGTM!"; Request changes; gh pr review 56 --request-changes --body "The focus indicator disappears on the last menu item."; Leave a. Read the command, understand what it changes, then run it only when the repository state matches the lesson.

      -

      Jamie: Let's pause on Checking CI status. What should a learner take away from it?

      -

      Alex: Start with Checking CI status. There is something to understand, something to try, and something that proves the try worked.

      -

      Alex: Treat examples as spoken recipes, not decorations. You may hear something like View all CI checks for a PR; gh pr checks 56; Watch checks update in real time (refreshes every 10s); gh pr checks 56 --watch; View checks for the current branch; gh pr checks. Read the command, understand what it changes, then run it only when the repository state matches the lesson.

      +

      Jamie: Let's pause on VoiceOver. What should a learner take away from it?

      +

      Alex: Start with VoiceOver. There is something to understand, something to try, and something that proves the try worked.

      +

      Alex: The practical takeaway is this. 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.

      +

      Alex: Keep the teaching thread moving. This is where Writing Good Commit Messages becomes real: see Culture & Etiquette: Writing Good Commit Messages for format guidance.

      +

      Jamie: How do you keep commands from becoming magic words?

      +

      Alex: Keep the learner anchored in Format. Common types: feat:, fix:, docs:, style:, refactor:, test:, chore.

      +

      Alex: The practical takeaway is this. First line: type + colon + short summary (50 characters max). Blank line. Optional body: detailed explanation. Optional footer: "Fixes 123" to link to issue.

      +

      Alex: Treat examples as spoken recipes, not decorations. You may hear something like 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. Read the command, understand what it changes, then run it only when the repository state matches the lesson.

      -

      Jamie: Let's pause on Merging PRs. What should a learner take away from it?

      -

      Alex: Start with Merging PRs. There is something to understand, something to try, and something that proves the try worked.

      -

      Alex: Treat examples as spoken recipes, not decorations. You may hear something like Merge a PR (interactive -- prompts for merge strategy); gh pr merge 56; Merge with a specific strategy; gh pr merge 56 --merge Creates a merge commit; gh pr merge 56 --squash Squashes all commits into one; gh pr merge 56 --rebase Rebases commits onto base. Read the command, understand what it changes, then run it only when the repository state matches the lesson.

      -

      Jamie: Let's pause on Other PR operations. What should a learner take away from it?

      -

      Alex: Start with Other PR operations. There is something to understand, something to try, and something that proves the try worked.

      -

      Alex: Treat examples as spoken recipes, not decorations. You may hear something like Convert a draft PR to ready for review; gh pr ready 56; Mark a ready PR back as draft; gh pr ready 56 --undo; Update your PR branch with the latest from base (equivalent to "Update branch" button); gh pr update-branch 56; gh pr update-branch 56 --rebase; Close. Read the command, understand what it changes, then run it only when the repository state matches the lesson.

      -

      Jamie: Let's pause on 5. Releases -- Create, List, Upload. What should a learner take away from it?

      -

      Alex: This is where 5. Releases -- Create, List, Upload becomes real: see also: Appendix H: Releases, Tags, and Insights for the GitHub.com interface side of releases. The workshop is closer to rehearsal than lecture. You hear the move, try the move, and then check what changed.

      -

      Alex: Treat examples as spoken recipes, not decorations. You may hear something like Create a release interactively; gh release create v1.2.0; Create with all details; gh release create v1.2.0 ; --title "Version 1.2.0 -- Accessibility Improvements" ; --notes "- Fixed keyboard navigation in settings\n- Added ARIA labels to all form inputs". Read the command, understand what it changes, then run it only when the repository state matches the lesson.

      +

      Alex: Keep the teaching thread moving. Start with What Happens After Commit. There is something to understand, something to try, and something that proves the try worked.

      +

      Alex: The practical takeaway is this. 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).

      +

      Jamie: Let's pause on 6. Push and Pull Operations. What should a learner take away from it?

      +

      Alex: Start with 6. Push and Pull Operations: Push sends your local commits to GitHub. The next useful detail is this: Pull downloads new commits from GitHub to your local repository.

      +

      Jamie: Let's pause on After committing locally. What should a learner take away from it?

      +

      Alex: Start with After committing locally. There is something to understand, something to try, and something that proves the try worked.

      +

      Alex: First, open Source Control: Ctrl+Shift+G (Mac: Cmd+Shift+G). Then, look for the "Publish Branch" button (if this is a new branch) or "Sync Changes" button. After that, press Enter on that button. Treat it like a recipe: do not add the next ingredient until the previous one is actually in the bowl.

      -

      Jamie: Let's pause on 6. Search -- Issues, PRs, Repos, Code. What should a learner take away from it?

      -

      Alex: Start with 6. Search -- Issues, PRs, Repos, Code. There is something to understand, something to try, and something that proves the try worked.

      -

      Alex: Treat examples as spoken recipes, not decorations. You may hear something like Search issues across all of GitHub; gh search issues "screen reader navigation" --label accessibility; gh search issues "keyboard shortcut" --repo owner/repo-name; gh search issues "help wanted" --language javascript --limit 20; Search pull requests; gh search. Read the command, understand what it changes, then run it only when the repository state matches the lesson.

      -

      Jamie: Let's pause on Labels. What should a learner take away from it?

      -

      Alex: Start with Labels. There is something to understand, something to try, and something that proves the try worked.

      -

      Alex: Treat examples as spoken recipes, not decorations. You may hear something like List labels in the current repo; gh label list; Create a label; gh label create "accessibility" --color "0075ca" --description "Accessibility improvements"; Clone labels from another repo (copies all their labels to yours); gh label clone owner/source-repo. Read the command, understand what it changes, then run it only when the repository state matches the lesson.

      -

      Alex: A solid project habit is to treat metadata as decision support. Labels, status, assignees, and notifications tell you what kind of attention the work needs.

      -

      Jamie: Let's pause on Milestones. What should a learner take away from it?

      -

      Alex: Start with Milestones. There is something to understand, something to try, and something that proves the try worked.

      -

      Alex: Treat examples as spoken recipes, not decorations. You may hear something like List milestones; gh api repos/{owner}/{repo}/milestones --jq '.[].title'; Create a milestone; gh api repos/{owner}/{repo}/milestones ; --method POST ; --field title="v2.0 Launch" ; --field description="All features for the v2.0 release" ; --field due. Read the command, understand what it changes, then run it only when the repository state matches the lesson.

      +

      Jamie: Let's pause on Alternative: Command Palette. What should a learner take away from it?

      +

      Alex: Start with Alternative: Command Palette. There is something to understand, something to try, and something that proves the try worked.

      +

      Alex: First, ctrl+Shift+P (Mac: Cmd+Shift+P). Then, type "git push". After that, select "Git: Push". Finally, VS Code pushes your commits to GitHub. It is a checklist, but a meaningful one: every item creates evidence that the next step is safe.

      +

      Jamie: Let's pause on Learning Cards: Push and Pull. What should a learner take away from it?

      +

      Alex: Keep the learner anchored in Learning Cards: Push and Pull. Low vision users (zoom, high contrast). This is the part to say slowly: Screen reader users (NVDA / JAWS on Windows). A good GitHub workflow is like a well-run meeting: everyone knows the topic, the next action, and who has the floor.

      +

      Alex: First, 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. Then, 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. After that, 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. Finally, 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. It is like walking a hallway with named doors: read the sign, enter the right room, then confirm where you landed.

      +

      Jamie: Let's pause on Pushing. What should a learner take away from it?

      +

      Alex: Start with Pushing. There is something to understand, something to try, and something that proves the try worked.

      +

      Alex: First, after committing, press Ctrl+Shift+P, type "git push", select "Git: Push". Then, NVDA/JAWS announces "Pushing." in the status bar. After that, on success, a notification appears: "Successfully pushed" - if using NVDA, check NVDA+N to read recent notifications. Finally, for a new branch (first push), use "Git: Publish Branch" instead - this sets up the upstream tracking. The rhythm is simple: orient, act, verify, then continue.

      -

      Alex: This is the part worth saying out loud. Here is the plain-English version of 8. Output Formatting -- JSON, jq, Templates. By default gh outputs human-readable text. Put another way, for scripting or custom display, you can get raw JSON and filter it. It is like learning a transit route. The names of the stops matter because they tell you whether you are still going the right direction.

      -

      Jamie: Let's pause on --json flag. What should a learner take away from it?

      -

      Alex: Start with --json flag. There is something to understand, something to try, and something that proves the try worked.

      -

      Alex: Treat examples as spoken recipes, not decorations. You may hear something like Get issue data as JSON; gh issue view 42 --json title,body,labels,state; Get PR data as JSON; gh pr view 56 --json title,number,state,mergeable,reviews; List issues as JSON; gh issue list --json number,title,labels,assignees. Read the command, understand what it changes, then run it only when the repository state matches the lesson.

      -

      Jamie: Let's pause on --jq flag (filter JSON inline). What should a learner take away from it?

      -

      Alex: Start with --jq flag (filter JSON inline). There is something to understand, something to try, and something that proves the try worked.

      -

      Alex: Treat examples as spoken recipes, not decorations. You may hear something like List just issue numbers and titles; gh issue list --json number,title --jq '.[] "(.number): (.title)"'; Get the names of all labels on an issue; gh issue view 42 --json labels --jq '.labels[].name'; Count open PRs; gh pr list --json number --jq 'length'. Read the command, understand what it changes, then run it only when the repository state matches the lesson.

      +

      Jamie: Let's pause on Pulling. What should a learner take away from it?

      +

      Alex: Start with Pulling. There is something to understand, something to try, and something that proves the try worked.

      +

      Alex: First, press Ctrl+Shift+P, type "git pull", select "Git: Pull". Then, NVDA/JAWS announces "Pulling." then the status changes. After that, if there are conflicts, the Source Control panel shows a "Merge Changes" section - navigate there with Ctrl+Shift+G then Down Arrow. Think of it as a rail line: each stop confirms you are still on the right route before the next one.

      +

      Jamie: Let's pause on Checking sync status. What should a learner take away from it?

      +

      Alex: Here is the plain-English version of Checking sync status. Screen reader users (VoiceOver on macOS).

      +

      Alex: First, press Ctrl+Shift+P, type "Git: Show Git Output". Then, the output pane opens with push/pull log messages in plain text. After that, use Up/Down Arrow to read line by line. Treat it like a recipe: do not add the next ingredient until the previous one is actually in the bowl.

      +

      Jamie: Before we leave Pushing, what is the practical point?

      +

      Alex: First, press Cmd+Shift+P, type "git push", select "Git: Push". Then, VoiceOver announces progress from the status bar. After that, on success, a notification toast appears - press VO+F3 to read the latest notification. It is a checklist, but a meaningful one: every item creates evidence that the next step is safe.

      -

      Jamie: Let's pause on --template flag (Go templates). What should a learner take away from it?

      -

      Alex: The reason --template flag (Go templates) matters is that --json with --jq produces clean, predictable output -- ideal for piping to a file or reading with a screen reader. That gives the learner a simple foothold: the default human-readable output is also clean, but JSON gives you precise control over what's announced.

      -

      Alex: Treat examples as spoken recipes, not decorations. You may hear something like Custom formatted output; gh issue list --template '{{range.}} {{.number}} {{.title}} ({{.state}}){{"\n"}}{{end}}'. Read the command, understand what it changes, then run it only when the repository state matches the lesson.

      -

      Alex: Now bring the learner back to the room. Start with Learning Cards: Output Formatting. There is something to understand, something to try, and something that proves the try worked.

      -

      Alex: On the ground, that means a few things. Use --json with --jq to extract exactly the fields you need -- this eliminates table formatting noise and reads as clean key-value pairs. Pipe long output to a file (gh issue list --json title issues.txt) and open it in VS Code for structured navigation with Alt+F2. Go templates (--template) let you define a single-line-per-item format that reads naturally with arrow keys. The default table output aligns columns with spaces -- increase terminal font size so columns stay readable. JSON output with --jq strips visual formatting and gives compact text that scales cleanly with any font size. Pipe output to VS Code (gh pr view 42 --json body --jq '.body' code -) to read it with your preferred editor theme and zoom.

      -

      Jamie: Let's pause on 9. Aliases -- Create Your Own Shortcuts. What should a learner take away from it?

      -

      Alex: Here is the plain-English version of 9. Aliases -- Create Your Own Shortcuts. Aliases let you create custom gh commands from long commands you run often.

      -

      Alex: Treat examples as spoken recipes, not decorations. You may hear something like Create an alias; gh alias set bugs 'issue list --label bug'; gh alias set my-prs 'pr list --author @me'; gh alias set review-ready 'pr list --label "ready for review"'; Use your alias; gh bugs; gh my-prs; gh review-ready; List all aliases; gh alias list. Read the command, understand what it changes, then run it only when the repository state matches the lesson.

      +

      Jamie: Before we leave Pulling, what is the practical point?

      +

      Alex: First, press Cmd+Shift+P, type "git pull", select "Git: Pull". Then, VoiceOver announces when the pull completes. After that, if conflicts exist, navigate to Source Control (Cmd+Shift+G) and review the Merge Changes section. It is like walking a hallway with named doors: read the sign, enter the right room, then confirm where you landed.

      +

      Jamie: What should happen before anyone copies and runs it?

      +

      Alex: The reason Screen reader feedback matters is that Git CLI alternative - push and pull. That gives the learner a simple foothold: web alternative (github.com) - push and pull.

      +

      Alex: The practical takeaway is this. 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).

      +

      Alex: Treat examples as spoken recipes, not decorations. You may hear something like 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. Read the command, understand what it changes, then run it only when the repository state matches the lesson.

      +

      Jamie: Let's pause on What to do if push fails. What should a learner take away from it?

      +

      Alex: Start with What to do if push fails. There is something to understand, something to try, and something that proves the try worked.

      +

      Alex: The practical takeaway is this. 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). Error: "Rejected - non-fast-forward" → Someone else pushed changes; you need to pull first.

      -

      Jamie: Let's pause on Useful aliases to set up. What should a learner take away from it?

      -

      Alex: Start with Useful aliases to set up. There is something to understand, something to try, and something that proves the try worked.

      -

      Alex: Treat examples as spoken recipes, not decorations. You may hear something like Issues assigned to you; gh alias set mine 'issue list --assignee @me'; Your open PRs; gh alias set mypr 'pr list --author @me --state open'; Check CI on current branch's PR; gh alias set ci 'pr checks'; View current PR; gh alias set pr 'pr view'. Read the command, understand what it changes, then run it only when the repository state matches the lesson.

      -

      Jamie: Let's pause on 10. Extensions -- Adding New Commands. What should a learner take away from it?

      -

      Alex: Keep the learner anchored in 10. Extensions -- Adding New Commands. Extensions add new gh subcommands written by the community.

      -

      Alex: Treat examples as spoken recipes, not decorations. You may hear something like Browse available extensions; gh extension search; Install an extension; gh extension install owner/gh-extension-name; List installed extensions; gh extension list; Update all extensions; gh extension upgrade --all; Update a specific extension; gh extension. Read the command, understand what it changes, then run it only when the repository state matches the lesson.

      -

      Jamie: Let's pause on 11. Copilot in the CLI. What should a learner take away from it?

      -

      Alex: The reason 11. Copilot in the CLI matters is that install the Copilot extension once, then ask coding and git questions without leaving the terminal. That gives the learner a simple foothold: Copilot CLI shows the suggested command, explains what it does, and asks whether to run it - perfect for learning while doing. The interface gets friendlier when it stops being a wall of controls and starts being a set of named places.

      -

      Alex: Treat examples as spoken recipes, not decorations. You may hear something like Install (one time); gh extension install github/gh-copilot; Ask for a command suggestion; gh copilot suggest "squash my last 4 commits into one"; gh copilot suggest "find which commit introduced a bug in auth.js"; gh copilot suggest "create a pull request from. Read the command, understand what it changes, then run it only when the repository state matches the lesson.

      +

      Alex: Keep the teaching thread moving. Start with When to pull. There is something to understand, something to try, and something that proves the try worked.

      +

      Alex: The practical takeaway is this. Before you start work each day. When GitHub shows your branch is behind the remote. When preparing to merge a PR.

      +

      Jamie: Let's pause on How to pull. What should a learner take away from it?

      +

      Alex: This is where How to pull becomes real: if there are conflicts: See Section 9.

      +

      Alex: First, ctrl+Shift+P (Mac: Cmd+Shift+P). Then, type "git pull". After that, select "Git: Pull". Finally, VS Code fetches and merges remote changes. It is a checklist, but a meaningful one: every item creates evidence that the next step is safe.

      +

      Alex: Keep the teaching thread moving. Start with Auto-fetch setting. There is something to understand, something to try, and something that proves the try worked.

      +

      Alex: The practical takeaway is this. VS Code can check for remote changes automatically every few minutes. Enable: Settings (Ctrl+, - Mac: Cmd+,) → search "git autofetch" → set to true.

      -

      Jamie: Let's pause on Auto model selection. What should a learner take away from it?

      -

      Alex: Start with Auto model selection: As of early 2026, gh copilot uses auto model selection by default - it picks the best available model for your request without you needing to specify one. The next useful detail is this: You can still request a specific model using the --model flag if you prefer.

      -

      Alex: Treat examples as spoken recipes, not decorations. You may hear something like Let Copilot choose automatically (default); gh copilot suggest "create a pull request from my current branch"; Request a specific model; gh copilot suggest --model gpt-5 "create a pull request from my current branch". Read the command, understand what it changes, then run it only when the repository state matches the lesson.

      -

      Jamie: Let's pause on Telemetry opt-out. What should a learner take away from it?

      -

      Alex: Here is the plain-English version of Telemetry opt-out. As of gh CLI 2.70 (April 2026), gh collects anonymized usage telemetry by default to improve the product. Put another way, or set the environment variable GH NO UPDATE NOTIFIER=1 to suppress update notifications only.

      -

      Alex: Treat examples as spoken recipes, not decorations. You may hear something like gh config set telemetry disabled. Read the command, understand what it changes, then run it only when the repository state matches the lesson.

      -

      Jamie: What is the one idea that makes the next few steps less mysterious?

      -

      Alex: This is where 12. Screen Reader Tips becomes real: the GitHub CLI is one of the most screen-reader-friendly ways to use GitHub. That matters in practice: Here's why and how to get the most out of it.

      -

      Alex: A solid navigation habit is to prove where you are before activating controls. Headings, landmarks, and the address bar are not trivia; they are your map.

      +

      Jamie: Let's pause on Syncing Your Fork with the Upstream Repository. What should a learner take away from it?

      +

      Alex: The reason Syncing Your Fork with the Upstream Repository matters is that when you fork a repository and the original (upstream) repository receives new commits, your fork gets out of date. That gives the learner a simple foothold: keeping your fork current prevents merge conflicts and ensures you're working with the latest code.

      +

      Jamie: Let's pause on The GitHub "Sync fork" Button (Quickest Method). What should a learner take away from it?

      +

      Alex: Start with The GitHub "Sync fork" Button (Quickest Method): For straightforward updates, GitHub has a built-in sync button. Think of it like entering a new building: first you find the lobby, then the room, then the door you actually need.

      +

      Alex: First, navigate to your fork on GitHub. Then, on the repository page, look for the "This branch is N commits behind owner/repo:main" notice. After that, activate the "Sync fork" button next to it. Finally, GitHub automatically merges upstream changes into your fork's default branch. Think of it as a rail line: each stop confirms you are still on the right route before the next one.

      +

      Jamie: Before we leave The GitHub "Sync fork" Button (Quickest Method), what is the practical point?

      +

      Alex: First, then pull those changes to your local clone: Git: Pull from the Command Palette. Treat it like a recipe: do not add the next ingredient until the previous one is actually in the bowl.

      +

      Jamie: Let's pause on Screen reader path. What should a learner take away from it?

      +

      Alex: Here is the plain-English version of Screen reader path. Limitation: The GitHub sync button only syncs the default branch. Put another way, for other branches, use the git method below.

      -

      Alex: Hold that next to this. Start with Why the CLI works so well. There is something to understand, something to try, and something that proves the try worked.

      -

      Alex: Here is what that changes in practice. Plain text output -- no visual noise, no unlabelled buttons, no hidden dialogs. Predictable structure -- every command produces consistent output you can navigate with arrow keys. No focus traps -- you control when you read output; nothing streams unexpectedly. Keyboard-first by design -- everything is a command you type.

      -

      Jamie: Let's pause on Tips by task. What should a learner take away from it?

      -

      Alex: The reason Tips by task matters is that creating content without a browser.

      -

      Alex: Treat examples as spoken recipes, not decorations. You may hear something like Pipe output to less for page-by-page reading; gh issue view 42 less; Save to a file and open in your editor; gh pr view 56 pr-56.md; code pr-56.md. Limit results to a manageable number; gh issue list --limit 10; Combine with search to narrow down; gh issue list --search "keyboard" --limit 5. Read the command, understand what it changes, then run it only when the repository state matches the lesson.

      -

      Alex: That connects to another useful point. Start with NVDA / JAWS (Windows). There is something to understand, something to try, and something that proves the try worked.

      -

      Alex: The room should hear these as checkpoints. Run gh commands in Windows Terminal or the VS Code integrated terminal -- both work well with NVDA/JAWS. Use Insert+Down (NVDA) or Insert+F12 (JAWS) to read the current line of terminal output. For long output, use less and navigate with Space (next page) and b (back).

      -
      -

      Jamie: If I am listening before the workshop starts, what should settle in my mind first?

      -

      Alex: Start with VoiceOver (macOS). There is something to understand, something to try, and something that proves the try worked.

      -

      Alex: These are the details that keep the idea from floating away. Run gh in Terminal.app or VS Code integrated terminal. VO+Right moves through terminal output character by character; VO+Down line by line. Use Ctrl+C to stop a running command if output is too long.

      -

      Alex: Here is the practical turn. Start with Learning Cards: Screen Reader CLI Workflow. There is something to understand, something to try, and something that proves the try worked.

      -

      Alex: That becomes easier when you listen for these cues. gh is keyboard-first by design -- no focus traps, no streaming, no unlabelled buttons; everything is typed and read as plain text. Use Insert+Down (NVDA) or Insert+F12 (JAWS) to read the current line, and arrow keys to move through multi-line output. Write issue and PR bodies in a text file first, then use --body-file./issue.md to submit -- much easier than composing inline. Terminal output from gh has no icons or images -- all information is conveyed as text that scales with your terminal font. Use --limit 10 on list commands to keep output short enough to scan comfortably without scrolling. Run gh in the VS Code integrated terminal to benefit from VS Code's zoom, themes, and Accessible View (Alt+F2).

      -

      Jamie: Where do you want a learner to place their attention here?

      -

      Alex: Keep the learner anchored in Copilot. Next: Appendix J: Codespaces Back: Appendix H: GitHub Desktop Teaching chapter: Chapter 01: Choose Your Tools.

      +

      Jamie: What is the safe way to learn from that example?

      +

      Alex: This is where Adding the Upstream Remote (One-Time Setup) becomes real: to sync locally using git, you first configure the upstream remote. That matters in practice: This only needs to be done once per clone.

      +

      Alex: Treat examples as spoken recipes, not decorations. You may hear something like 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. Read the command, understand what it changes, then run it only when the repository state matches the lesson.

      +

      Jamie: Let's pause on Example for Accessibility Agents. What should a learner take away from it?

      +

      Alex: Start with Example for Accessibility Agents. There is something to understand, something to try, and something that proves the try worked.

      +

      Alex: Treat examples as spoken recipes, not decorations. You may hear something like git remote add upstream https://github.com/community-access/accessibility-agents.git. Read the command, understand what it changes, then run it only when the repository state matches the lesson.

      +

      Jamie: Let's pause on Fetching and Merging Upstream Changes. What should a learner take away from it?

      +

      Alex: The reason Fetching and Merging Upstream Changes matters is that once your upstream remote is configured. The interface gets friendlier when it stops being a wall of controls and starts being a set of named places.

      +

      Alex: Treat examples as spoken recipes, not decorations. You may hear something like 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. Read the command, understand what it changes, then run it only when the repository state matches the lesson.

      -

      Jamie: What should people carry with them after this?

      -

      Alex: Carry the map. Know what page or tool you are in, know which action you are taking, and know what confirmation should follow. If the confirmation is missing, pause. That pause is not wasted time; it is professional judgment.

      -

      Jamie: That is a better way to say it than just follow the steps.

      -

      Alex: Right. Steps matter, but understanding wins. That is episode 53. Next in the series is the next learning block, where we keep building the same contributor muscles.

      -
      - +

      Jamie: Let's pause on When Conflicts Occur During Sync. What should a learner take away from it?

      +

      Alex: Start with When Conflicts Occur During Sync: See also: Chapter 07: Merge Conflicts for a dedicated walkthrough of conflict resolution. The next useful detail is this: If you've made changes to the same files the upstream has changed, merge conflicts can occur during sync.

      +

      Alex: Keep the teaching thread moving. Here is the plain-English version of 7. Discarding Changes. Discarding = permanently deleting your local edits. Put another way, the file reverts to the state of the last commit.

      +

      Jamie: Let's pause on When to Discard. What should a learner take away from it?

      +

      Alex: Start with When to Discard. There is something to understand, something to try, and something that proves the try worked.

      +

      Alex: The practical takeaway is this. You made experimental changes and they didn't work. You want to start over from the last commit. You accidentally edited the wrong file.

      -

      Challenge Coach Episodes

      -

      These short teaching transcripts cover each Learning Room challenge in the same Alex and Jamie conversational style. Audio will be generated after transcript review.

      -

      Challenge 01: Find Your Way Around

      -

      Repository orientation, headings, tabs, file tree navigation, and confidence in the Learning Room.

      -
      -Read Transcript - Challenge 01: Find Your Way Around - -

      Transcript

      -

      Alex: This is Challenge Coach for Find Your Way Around. I am Alex, and we are going to teach the move before asking you to prove it.

      -

      Jamie: And I am Jamie. I will translate the challenge into the practical questions learners actually have while doing it.

      +

      Jamie: Let's pause on Single file. What should a learner take away from it?

      +

      Alex: Start with Single file. There is something to understand, something to try, and something that proves the try worked.

      +

      Alex: First, open Source Control: Ctrl+Shift+G. Then, navigate to the file in "Changes". After that, press Shift+F10 for context menu. Finally, select "Discard Changes". It is like walking a hallway with named doors: read the sign, enter the right room, then confirm where you landed.

      +

      Jamie: Before we leave Single file, what is the practical point?

      +

      Alex: First, confirm in the warning dialog (VS Code will ask "Are you sure?"). The rhythm is simple: orient, act, verify, then continue.

      +

      Jamie: Let's pause on All changes. What should a learner take away from it?

      +

      Alex: The reason All changes matters is that screen reader warning: VS Code shows a modal confirmation dialog. That gives the learner a simple foothold: navigate with Tab, select "Discard" or "Cancel" with Enter.

      +

      Alex: First, ctrl+Shift+G. Then, navigate to the "Changes" section heading. After that, shift+F10 for context menu. Finally, select "Discard All Changes". The rhythm is simple: orient, act, verify, then continue.

      +

      Jamie: Before we leave All changes, what is the practical point?

      +

      Alex: First, confirm (this affects every modified file). Think of it as a rail line: each stop confirms you are still on the right route before the next one.

      +

      Jamie: Let's pause on Learning Cards: Discarding Changes. What should a learner take away from it?

      +

      Alex: Start with Learning Cards: Discarding Changes: Low vision users (zoom, high contrast). The next useful detail is this: Screen reader users (NVDA / JAWS on Windows).

      +

      Alex: First, 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.". Then, 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. After that, for "Discard All Changes", right-click the "Changes" section heading to get the context menu. Finally, 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"). Think of it as a rail line: each stop confirms you are still on the right route before the next one.

      -

      Alex: Repository orientation, headings, tabs, file tree navigation, and confidence in the Learning Room. That is the task layer. The teaching layer is understanding why the move belongs in a contributor workflow.

      -

      Jamie: So evidence is not just proof for the facilitator. It is part of how the learner understands the workflow.

      -

      Alex: Right. A good challenge produces something inspectable: a comment, issue, branch, commit, pull request, review, or clear note about what happened.

      +

      Jamie: What is the teaching move inside Single file?

      +

      Alex: First, press Ctrl+Shift+G to open Source Control. Then, navigate to the file in the Changes section with Down Arrow. After that, press Shift+F10 to open the context menu. Finally, navigate to "Discard Changes" with Down Arrow, press Enter. Treat it like a recipe: do not add the next ingredient until the previous one is actually in the bowl.

      +

      Jamie: If someone only remembers one thing from Single file, what should it be?

      +

      Alex: First, a confirmation dialog appears - NVDA announces "Are you sure you want to discard changes" or similar. Then, press Tab to navigate between "Discard" and "Cancel", press Enter on your choice. It is a checklist, but a meaningful one: every item creates evidence that the next step is safe.

      +

      Jamie: Let's pause on All files. What should a learner take away from it?

      +

      Alex: This is where All files becomes real: screen reader users (VoiceOver on macOS). That matters in practice: Discard changes from your terminal. The workshop is closer to rehearsal than lecture. You hear the move, try the move, and then check what changed.

      +

      Alex: First, navigate to the "Changes" section heading (announced as "Changes, expanded, N items"). Then, press Shift+F10, select "Discard All Changes". After that, confirm in the dialog. Finally, press Cmd+Shift+G to open Source Control. It is a checklist, but a meaningful one: every item creates evidence that the next step is safe.

      +

      Jamie: Before we leave All files, what is the practical point?

      +

      Alex: First, use VO+Arrow keys to navigate to the file. Then, press VO+Shift+M to open the context menu (or Ctrl+Return). After that, navigate to "Discard Changes", press VO+Space. Finally, in the confirmation dialog, use VO+Right Arrow to reach the buttons, VO+Space to activate. It is like walking a hallway with named doors: read the sign, enter the right room, then confirm where you landed.

      +

      Alex: Treat examples as spoken recipes, not decorations. You may hear something like 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. Read the command, understand what it changes, then run it only when the repository state matches the lesson.

      +

      Jamie: Let's pause on Safer Alternative: Stash Instead of Discard. What should a learner take away from it?

      +

      Alex: Keep the learner anchored in 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. This is the part to say slowly: Stash saves your changes temporarily without committing them.

      -

      Jamie: What makes this practice feel low-stakes but still real?

      -

      Alex: Start with Challenge 1: Find Your Way Around: What you will do: Explore the learning-room repository like a scavenger hunt. The next useful detail is this: Find the tabs, navigate the file tree, read the README, and locate key files.

      -

      Jamie: How would you walk the room through that step by step?

      -

      Alex: Here is the plain-English version of Scavenger hunt checklist. You do not need to complete them in order. Put another way, for each item, write a short sentence about what you found." placeholder. It is like learning a transit route. The names of the stops matter because they tell you whether you are still going the right direction.

      -

      Alex: The practical anchors are these. [ ] Find the Code tab and count how many files are in the root of the repository. [ ] Open the Issues tab and find an open issue. [ ] Navigate to docs/welcome.md and read the first paragraph. [ ] Find the repository description (hint: it is near the top of the Code tab).

      -

      Alex: First, I found files in the root of the repository. Then, the open issue I found was titled " ". After that, the first paragraph of welcome.md says. Finally, the repository description is. Treat it like a recipe: do not add the next ingredient until the previous one is actually in the bowl.

      -

      Jamie: What does the learner do first, second, and then after that?

      -

      Alex: First, the README says this workshop is for. Then, the About section shows. It is a checklist, but a meaningful one: every item creates evidence that the next step is safe.

      -

      Jamie: What is the one idea that makes the next few steps less mysterious?

      -

      Alex: This is where Peer simulation check becomes real: after you submit your evidence, open the Peer Simulation: Welcome Link Needs Context issue in this repository and leave an encouraging comment or reaction. That matters in practice: If your facilitator gave you access to a real buddy repository, you may use your buddy's issue instead.

      +

      Alex: Keep the teaching thread moving. The reason Deleting a File from the Repository (Git Delete / git rm) matters is that Git Delete removes a file from both your working directory AND Git's tracking. That gives the learner a simple foothold: this is different from discarding changes - it permanently removes the file from the repository history going forward.

      +

      Jamie: Let's pause on How to use. What should a learner take away from it?

      +

      Alex: Start with How to use: The file is staged for deletion - you still need to commit to record the removal.

      +

      Alex: First, open the file you want to remove in the editor. Then, ctrl+Shift+P (Mac: Cmd+Shift+P). After that, type "Git: Delete". Finally, confirm the deletion. Think of it as a rail line: each stop confirms you are still on the right route before the next one.

      +

      Alex: Keep the teaching thread moving. Start with When to use Git Delete vs. just deleting the file. There is something to understand, something to try, and something that proves the try worked.

      +

      Alex: The practical takeaway is this. 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.

      -

      Alex: Now bring the learner back to the room. Start with Code tab. There is something to understand, something to try, and something that proves the try worked.

      -

      Alex: For a learner, the useful signals are these. The root of the repository contains files like README.md, docs/, and.github/. The file count varies as the repository evolves -- any reasonable count is correct.

      -

      Jamie: What would you say to someone who is already bracing for this to be too much?

      -

      Alex: Start with Issues tab. There is something to understand, something to try, and something that proves the try worked.

      -

      Alex: The parts worth keeping in working memory are these. You should have found at least one open issue. If no issues were open, noting that the tab exists is sufficient.

      -

      Alex: A solid issue habit is to read the title, the body, and the timeline before acting. You are listening for the requested action, the missing evidence, and the person who needs a response.

      -

      Alex: That matters because of the next idea. Start with docs/welcome.md. There is something to understand, something to try, and something that proves the try worked.

      -

      Alex: On the ground, that means a few things. The first paragraph introduces the learning room and what students will do. You may have noticed TODO comments -- those are intentionally left for Challenge 2.

      -

      Alex: The useful habit is simple: orient first, act second, verify third. That pause before acting is part of the work.

      +

      Jamie: Let's pause on Learning Cards: Deleting a File from the Repository. What should a learner take away from it?

      +

      Alex: This is where Learning Cards: Deleting a File from the Repository becomes real: alternatively: Ctrl+Shift+P then "Git: Delete" removes the file and stages the deletion in one step. That matters in practice: Low vision users (zoom, high contrast).

      +

      Alex: First, right-click the file in the Explorer panel (Ctrl+Shift+E). Then, select "Delete" to delete from your file system. After that, the file appears in Source Control (Ctrl+Shift+G) under Changes with a "D" (deleted) status. Finally, stage and commit the deletion to record it in Git. It is a checklist, but a meaningful one: every item creates evidence that the next step is safe.

      +

      Jamie: Before we leave Learning Cards: Deleting a File from the Repository, what is the practical point?

      +

      Alex: First, 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. Then, 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. After that, stage and commit as normal. Finally, open the file you want to remove in the editor. It is like walking a hallway with named doors: read the sign, enter the right room, then confirm where you landed.

      +

      Alex: Treat examples as spoken recipes, not decorations. You may hear something like 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. Read the command, understand what it changes, then run it only when the repository state matches the lesson.

      +

      Alex: Keep the teaching thread moving. Keep the learner anchored in 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.

      +

      Jamie: Let's pause on Method 1: Explorer Sidebar. What should a learner take away from it?

      +

      Alex: Start with Method 1: Explorer Sidebar. There is something to understand, something to try, and something that proves the try worked.

      +

      Alex: First, open Explorer: Ctrl+Shift+E. Then, at the bottom of the Explorer, there's a "Timeline" section. After that, tab or Arrow to navigate into Timeline. Finally, the list shows all commits affecting the currently open file. The rhythm is simple: orient, act, verify, then continue.

      -

      Jamie: Okay, set the room for us. What are we walking into?

      -

      Alex: Start with Repository description and README. There is something to understand, something to try, and something that proves the try worked.

      -

      Alex: Here is what that changes in practice. The description appears at the top of the Code tab, below the repository name. The README renders automatically below the file list.

      -

      Alex: This is where the talk moves from concept to action. Start with Alternate approaches. There is something to understand, something to try, and something that proves the try worked.

      -

      Alex: The room should hear these as checkpoints. github.com: Click each tab in the top navigation bar. github.dev: press the period key on any repo page to open the web editor, then use the Explorer sidebar. VS Code with GitHub extension: Use the GitHub Repositories extension to browse remotely. GitHub CLI: gh repo view Community-Access/git-going-with-github --web opens the repo in a browser.

      -

      Alex: A solid pull request habit is to separate three questions: what changed, why it changed, and what still needs review. That keeps the conversation useful instead of noisy.

      -

      Jamie: Where do you want a learner to place their attention here?

      -

      Alex: Keep the learner anchored in What matters. The learning objective is familiarity with repository navigation, not memorizing exact file counts. This is the part to say slowly: If you explored the tabs and found the key files, you completed this challenge.

      +

      Jamie: Let's pause on Method 2: Command Palette. What should a learner take away from it?

      +

      Alex: Start with Method 2: Command Palette. There is something to understand, something to try, and something that proves the try worked.

      +

      Alex: First, open a file in the editor. Then, ctrl+Shift+P. After that, type "timeline". Finally, select "View: Show Timeline". Think of it as a rail line: each stop confirms you are still on the right route before the next one.

      +

      Jamie: Let's pause on What Timeline Shows. What should a learner take away from it?

      +

      Alex: Here is the plain-English version of What Timeline Shows. Screen reader announcement: "docs: add Timeline Guide, Jeff, 2 days ago".

      +

      Alex: The practical takeaway is this. Commit message (first line). Author name. Relative time (example: "3 days ago" or "2 hours ago"). Commit hash (short form, like a3f2b9c).

      +

      Jamie: Let's pause on Viewing a Commit's Changes. What should a learner take away from it?

      +

      Alex: This is where Viewing a Commit's Changes becomes real: this is incredibly useful for understanding.

      +

      Alex: The practical takeaway is this. When a particular line was added. Why a section was removed. What the file looked like at any point in history.

      +

      Alex: First, navigate to a commit in the Timeline list. Then, press Enter. After that, a diff view opens showing what changed in that specific commit. It is a checklist, but a meaningful one: every item creates evidence that the next step is safe.

      -

      Alex: Before the learner moves on. The reason How GitHub Is Organized, and How to Orient Yourself on Every Page matters is that read this before navigating GitHub for the first time. That gives the learner a simple foothold: the lesson is the mental model that makes every subsequent guide easier. The interface gets friendlier when it stops being a wall of controls and starts being a set of named places.

      -

      Jamie: Give me the version that sounds like an instructor, not a manual.

      -

      Alex: Start with 1. GitHub's Three-Level Structure: GitHub is not a single page or a single kind of page. The next useful detail is this: It is three nested levels, and understanding which level you are on changes how you navigate.

      -

      Alex: Hold that next to this. Here is the plain-English version of 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. Put another way, understanding its landmark structure means you always have a fixed orientation point.

      +

      Jamie: Let's pause on Git Blame - Line-by-Line History. What should a learner take away from it?

      +

      Alex: Keep the learner anchored in Git Blame - Line-by-Line History. Git Blame shows who last modified each line of the file.

      +

      Jamie: Let's pause on How to access. What should a learner take away from it?

      +

      Alex: Start with How to access. There is something to understand, something to try, and something that proves the try worked.

      +

      Alex: First, open a file in the editor. Then, ctrl+Shift+P. After that, type "git blame". Finally, select "Git: Toggle Blame". The rhythm is simple: orient, act, verify, then continue.

      +

      Jamie: Let's pause on What appears. What should a learner take away from it?

      +

      Alex: Start with What appears. There is something to understand, something to try, and something that proves the try worked.

      +

      Alex: The practical takeaway is this. Inline annotations next to every line (visually). Hover over a line to see commit details.

      -

      Jamie: If I am listening before the workshop starts, what should settle in my mind first?

      -

      Alex: This is where The Global Navigation Bar (always present) becomes real: visually, the top bar contains (left to right). That matters in practice: Screen reader landmark: All of these live inside the landmark labeled "Navigation Menu".

      -

      Alex: That connects to another useful point. Keep the learner anchored in Secondary navigation (repository pages only). When you are inside a repository, a second navigation bar appears below the global bar. This is the part to say slowly: This contains the repository's tabs: Code, Issues, Pull requests, Actions, Projects, Wiki, Security, Insights, and Settings. A good GitHub workflow is like a well-run meeting: everyone knows the topic, the next action, and who has the floor.

      -

      Alex: A solid navigation habit is to prove where you are before activating controls. Headings, landmarks, and the address bar are not trivia; they are your map.

      -

      Jamie: Let's pause on Learning Cards: What Is Always on Every GitHub Page. What should a learner take away from it?

      -

      Alex: Start with Learning Cards: What Is Always on Every GitHub Page. There is something to understand, something to try, and something that proves the try worked.

      -

      Alex: These are the details that keep the idea from floating away. 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. 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.

      +

      Alex: Keep the teaching thread moving. Here is the plain-English version of For screen reader users. Useful blame settings (add to.vscode/settings.json or user Settings).

      +

      Alex: The practical takeaway is this. 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.

      +

      Jamie: Let's pause on Learning Cards: Timeline and History. What should a learner take away from it?

      +

      Alex: This is where Learning Cards: Timeline and History becomes real: low vision users (zoom, high contrast). That matters in practice: Screen reader users (NVDA / JAWS on Windows).

      +

      Alex: First, 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. Then, 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. After that, 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. Finally, 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. It is a checklist, but a meaningful one: every item creates evidence that the next step is safe.

      +

      Jamie: Let's pause on Opening Timeline. What should a learner take away from it?

      +

      Alex: Start with Opening Timeline. There is something to understand, something to try, and something that proves the try worked.

      +

      Alex: First, press Ctrl+Shift+E to open Explorer. Then, press Tab repeatedly or Down Arrow to navigate past the file tree to the "Timeline" section. After that, press Right Arrow to expand it if collapsed. Finally, navigate commit entries with Up/Down Arrow. It is like walking a hallway with named doors: read the sign, enter the right room, then confirm where you landed.

      +

      Jamie: Before we leave Opening Timeline, what is the practical point?

      +

      Alex: First, each entry is announced as: "commit message, author, time" (e.g., "docs: add Timeline Guide, Jeff, 2 days ago"). Then, press Enter on any entry to open its diff view. The rhythm is simple: orient, act, verify, then continue.

      -

      Alex: Here is the practical turn. Start with 3. How to Tell Where You Are: Three signals tell you exactly where you are on GitHub, without needing to see the visual layout.

      -

      Jamie: Let's pause on Signal 1: The URL. What should a learner take away from it?

      -

      Alex: Here is the plain-English version of Signal 1: The URL. GitHub URLs are readable descriptions of your location. Put another way, your browser's address bar is always reachable with Alt+D (Windows) or Cmd+L (Mac).

      -

      Alex: Keep the thread going. This is where Signal 2: The browser tab title becomes real: GitHub formats page titles consistently. The workshop is closer to rehearsal than lecture. You hear the move, try the move, and then check what changed.

      +

      Jamie: Let's pause on Reading a diff with screen reader. What should a learner take away from it?

      +

      Alex: Start with Reading a diff with screen reader. There is something to understand, something to try, and something that proves the try worked.

      +

      Alex: First, in the diff view, press Alt+F2 to open the Accessible Diff Viewer. Then, the Accessible Diff Viewer presents changes as a text list: each line shows + (added), - (removed), or unchanged. After that, navigate with Up/Down Arrow to read each line. Finally, press Escape to close the Accessible Diff Viewer. The rhythm is simple: orient, act, verify, then continue.

      +

      Jamie: Let's pause on Git Blame. What should a learner take away from it?

      +

      Alex: Start with Git Blame: Screen reader users (VoiceOver on macOS).

      +

      Alex: First, open a file, press Ctrl+Shift+P, type "Git: Toggle Blame". Then, blame annotations appear inline - NVDA reads them when navigating lines. After that, to reduce noise, disable blame (repeat the toggle command) and use Timeline instead. Think of it as a rail line: each stop confirms you are still on the right route before the next one.

      +

      Jamie: What is the teaching move inside Opening Timeline?

      +

      Alex: First, press Cmd+Shift+E to open Explorer. Then, use VO+Down Arrow to navigate below the file tree to the Timeline section. After that, press VO+Space to expand if collapsed. Finally, navigate entries with VO+Down Arrow. Treat it like a recipe: do not add the next ingredient until the previous one is actually in the bowl.

      +

      Jamie: If someone only remembers one thing from Opening Timeline, what should it be?

      +

      Alex: First, press VO+Space on a commit to open its diff. It is a checklist, but a meaningful one: every item creates evidence that the next step is safe.

      -

      Jamie: Let's pause on Signal 3: The first H1 heading. What should a learner take away from it?

      -

      Alex: Keep the learner anchored in Signal 3: The first H1 heading. Press 1 (in Browse Mode) on any GitHub page to jump to the first H1 heading. This is the part to say slowly: What you hear tells you what type of page you are on.

      -

      Alex: Another way to ground it. The reason Page Type 1: Repository Home (Code Tab) matters is that this is the central hub of any project. That gives the learner a simple foothold: it is where you find the file tree, the README, branch information, and links to all other parts of the repository.

      -

      Jamie: Let's pause on What to expect. What should a learner take away from it?

      -

      Alex: Start with What to expect. There is something to understand, something to try, and something that proves the try worked.

      -

      Alex: A few details make that real. 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.

      +

      Jamie: Let's pause on Accessible Diff Viewer. What should a learner take away from it?

      +

      Alex: This is where Accessible Diff Viewer becomes real: screen reader advantage: git log --oneline and git blame produce clean, columnar text output. That matters in practice: Read line by line with arrow keys in the terminal. The workshop is closer to rehearsal than lecture. You hear the move, try the move, and then check what changed.

      +

      Alex: First, in any diff view, press Option+F2 to open the Accessible Diff Viewer. Then, read changes line by line with VO+Down Arrow. After that, press Escape to close. It is a checklist, but a meaningful one: every item creates evidence that the next step is safe.

      +

      Alex: Treat examples as spoken recipes, not decorations. You may hear something like 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. 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. Read the command, understand what it changes, then run it only when the repository state matches the lesson.

      +

      Jamie: What should someone listen for when a lesson offers more than one tool path?

      +

      Alex: Keep the learner anchored in 9. Resolving Merge Conflicts in VS Code. Merge conflicts happen when two people edit the same lines of a file. This is the part to say slowly: Git can't decide which version to keep, so it asks you to choose.

      +

      Alex: Keep the teaching thread moving. The reason How VS Code Displays Conflicts matters is that when you open a file with conflicts, you see something like. That gives the learner a simple foothold: VS Code adds buttons above each conflict (visually).

      +

      Alex: The practical takeaway is this. "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).

      -

      Alex: This is the part worth saying out loud. Here is the plain-English version of Page Type 2: Issues List. A searchable, filterable list of all issues in the repository. It is like learning a transit route. The names of the stops matter because they tell you whether you are still going the right direction.

      -

      Jamie: Before we leave What to expect, what is the practical point?

      -

      Alex: That shows up in the workshop in a few specific ways. 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".

      -

      Alex: The next layer is this. Keep the learner anchored in Page Type 3: Issue Detail. The full view of a single issue: the original report, all comments, labels, assignees, and the timeline.

      +

      Jamie: Let's pause on Screen Reader Workflow for Resolving Conflicts. What should a learner take away from it?

      +

      Alex: Start with Screen Reader Workflow for Resolving Conflicts: The buttons are NOT accessible via keyboard.

      +

      Alex: The practical takeaway is this. <<<<<<< marks the start. ======= separates the two versions. marks the end. The section between <<<<<<< and ======= is your current branch (HEAD). The section between ======= and is the incoming branch (the branch you're merging). Delete the conflict markers ( ).

      +

      Alex: First, identify the conflict markers. Then, read both versions. After that, decide what to keep. Finally, stage the resolved file. Think of it as a rail line: each stop confirms you are still on the right route before the next one.

      +

      Jamie: Before we leave Screen Reader Workflow for Resolving Conflicts, what is the practical point?

      +

      Alex: First, commit the merge. Treat it like a recipe: do not add the next ingredient until the previous one is actually in the bowl.

      +

      Jamie: Let's pause on Using Accessible Diff for Conflict Review. What should a learner take away from it?

      +

      Alex: Here is the plain-English version of Using Accessible Diff for Conflict Review. Better approach: Use the Accessible Diff Viewer (F7) to navigate conflict hunks systematically. It is like learning a transit route. The names of the stops matter because they tell you whether you are still going the right direction.

      +

      Alex: First, open the conflicted file. Then, press F7 to jump to the first conflict hunk. After that, press Alt+F2 to open Accessible View. Finally, read both versions clearly. Treat it like a recipe: do not add the next ingredient until the previous one is actually in the bowl.

      +

      Jamie: Before we leave Using Accessible Diff for Conflict Review, what is the practical point?

      +

      Alex: First, press Escape to return to editor. Then, manually edit to resolve. After that, press F7 to jump to the next conflict. Finally, repeat until all conflicts resolved. It is a checklist, but a meaningful one: every item creates evidence that the next step is safe.

      +

      Jamie: Let's pause on Aborting a Merge. What should a learner take away from it?

      +

      Alex: This is where Aborting a Merge becomes real: if you want to cancel the merge and go back to before you started. That matters in practice: Everything returns to the pre-merge state.

      +

      Alex: First, ctrl+Shift+P. Then, type "git abort". After that, select "Git: Abort Merge". It is a checklist, but a meaningful one: every item creates evidence that the next step is safe.

      -

      Jamie: What is the teaching move inside What to expect?

      -

      Alex: That becomes easier when you listen for these cues. 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.

      -

      Alex: Keep the teaching thread moving. Start with 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. Think of it like entering a new building: first you find the lobby, then the room, then the door you actually need.

      -

      Jamie: If someone only remembers one thing from What to expect, what should it be?

      -

      Alex: The practical takeaway is this. 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.

      +

      Alex: Keep the teaching thread moving. Start with Learning Cards: Resolving Merge Conflicts. There is something to understand, something to try, and something that proves the try worked.

      +

      Alex: The practical takeaway is this. 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. 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.

      +

      Jamie: Let's pause on 10. Stash Management. What should a learner take away from it?

      +

      Alex: The reason 10. Stash Management matters is that stash temporarily saves your uncommitted changes so you can switch branches or pull updates without committing half-finished work.

      +

      Alex: Keep the teaching thread moving. Start with When to Use Stash. There is something to understand, something to try, and something that proves the try worked.

      +

      Alex: The practical takeaway is this. 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.

      -

      Alex: Keep the teaching thread moving. This is where Page Type 5: Your Personal Feed and Profile becomes real: your personal home (github.com) shows activity from repositories you follow. That matters in practice: Your profile (github.com/username) shows your contribution graph, pinned repos, and bio.

      -

      Jamie: Let's pause on What to expect on your feed. What should a learner take away from it?

      -

      Alex: Start with What to expect on your feed. There is something to understand, something to try, and something that proves the try worked.

      -

      Alex: The practical takeaway is this. A "For you" activity stream - recent activity from repos you watch. A sidebar of suggested repositories and topics.

      -

      Alex: Keep the teaching thread moving. Start with What to expect on your profile. There is something to understand, something to try, and something that proves the try worked.

      -

      Alex: The practical takeaway is this. 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.

      +

      Jamie: Let's pause on Method 1: Command Palette. What should a learner take away from it?

      +

      Alex: Start with Method 1: Command Palette. There is something to understand, something to try, and something that proves the try worked.

      +

      Alex: First, ctrl+Shift+P. Then, type "git stash". After that, select "Git: Stash". Finally, optionally type a stash message (helps you remember what's in it). Treat it like a recipe: do not add the next ingredient until the previous one is actually in the bowl.

      +

      Alex: Keep the teaching thread moving. Start with What happens. There is something to understand, something to try, and something that proves the try worked.

      +

      Alex: The practical takeaway is this. 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.

      +

      Jamie: Let's pause on Command Palette. What should a learner take away from it?

      +

      Alex: Start with Command Palette. There is something to understand, something to try, and something that proves the try worked.

      +

      Alex: First, ctrl+Shift+P. Then, type "git stash list". After that, select "Git: Show Stash". It is like walking a hallway with named doors: read the sign, enter the right room, then confirm where you landed.

      -

      Jamie: Let's pause on Learning Cards: The Five Key Page Types. What should a learner take away from it?

      -

      Alex: Start with Learning Cards: The Five Key Page Types. There is something to understand, something to try, and something that proves the try worked.

      -

      Alex: The practical takeaway is this. 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. 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.

      -

      Alex: Keep the teaching thread moving. Here is the plain-English version of 5. Visual Map of a Repository Page. See also: Appendix A: Glossary defines every term used in this course. Put another way, appendix B: Screen Reader Cheat Sheet has quick-reference keyboard shortcuts for navigating headings and landmarks.

      -

      Jamie: Let's pause on Description. What should a learner take away from it?

      -

      Alex: This is where Description becomes real: a repository home page is laid out from top to bottom as follows. That matters in practice: The Global Navigation bar (landmark: "Navigation Menu") contains the GitHub logo, Search, Copilot, Pull Requests, Issues, Notifications bell, and your avatar.

      +

      Jamie: Let's pause on Alternative: Integrated Terminal. What should a learner take away from it?

      +

      Alex: Start with Alternative: Integrated Terminal. There is something to understand, something to try, and something that proves the try worked.

      +

      Alex: Treat examples as spoken recipes, not decorations. You may hear something like git stash list. Read the command, understand what it changes, then run it only when the repository state matches the lesson.

      +

      Jamie: Let's pause on To restore your stashed changes. What should a learner take away from it?

      +

      Alex: Start with To restore your stashed changes. There is something to understand, something to try, and something that proves the try worked.

      +

      Alex: First, ctrl+Shift+P. Then, type "git stash apply". After that, select "Git: Apply Latest Stash". Think of it as a rail line: each stop confirms you are still on the right route before the next one.

      +

      Jamie: Let's pause on Or to apply a specific stash. What should a learner take away from it?

      +

      Alex: Start with Or to apply a specific stash. There is something to understand, something to try, and something that proves the try worked.

      +

      Alex: First, ctrl+Shift+P. Then, type "git stash pop". After that, select "Git: Pop Stash.". Finally, choose which stash from the list. Treat it like a recipe: do not add the next ingredient until the previous one is actually in the bowl.

      -

      Alex: Keep the teaching thread moving. Keep the learner anchored in Screen reader navigation of this page. Press 1 to hear "owner/repo-name" (the H1, confirms you are on the right repo). This is the part to say slowly: Press D to hear "Navigation Menu," then D again for "Repository navigation," then D again for "Main" (the file tree area). A good GitHub workflow is like a well-run meeting: everyone knows the topic, the next action, and who has the floor.

      -

      Jamie: What is the ordered workflow?

      -

      Alex: The reason 6. Screen Reader Orientation Sequence matters is that do this every time you land on a new GitHub page. That gives the learner a simple foothold: it takes about 10 seconds once you are practiced.

      -

      Alex: The practical takeaway is this. 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).

      -

      Alex: First, browser tab title - tells you the page type and repo context. Then, global nav bar (top strip) - GitHub logo, search box, bells/icons. After that, repo tabs (below global nav, visible only inside a repo) - Code, Issues, Pull Requests, etc. Finally, h1 heading - tells you exactly what page you're on (repo name / "Issues" / issue title / PR title). The rhythm is simple: orient, act, verify, then continue.

      -

      Jamie: Give me the sequence, because order matters here.

      -

      Alex: First, main content area - file tree, issue list, PR diff, etc. Think of it as a rail line: each stop confirms you are still on the right route before the next one.

      -

      Alex: Keep the teaching thread moving. Start with Learning Cards: Screen Reader Orientation Sequence. There is something to understand, something to try, and something that proves the try worked.

      -

      Alex: The practical takeaway is this. 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. 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.

      +

      Jamie: Let's pause on Difference between Apply and Pop. What should a learner take away from it?

      +

      Alex: Start with Difference between Apply and Pop. There is something to understand, something to try, and something that proves the try worked.

      +

      Alex: The practical takeaway is this. Apply: restores changes and keeps the stash (you can apply it again later). Pop: restores changes and deletes the stash.

      +

      Jamie: Let's pause on Dropping a Stash. What should a learner take away from it?

      +

      Alex: Keep the learner anchored in Dropping a Stash. If you no longer need what's in a stash. A good GitHub workflow is like a well-run meeting: everyone knows the topic, the next action, and who has the floor.

      +

      Alex: First, ctrl+Shift+P. Then, type "git stash drop". After that, select "Git: Drop Stash.". Finally, choose which stash to delete. It is like walking a hallway with named doors: read the sign, enter the right room, then confirm where you landed.

      +

      Jamie: Let's pause on Learning Cards: Stash Management. What should a learner take away from it?

      +

      Alex: The reason Learning Cards: Stash Management matters is that if the Stashes section is not visible, use the Command Palette: Ctrl+Shift+P then type "git stash" to access all stash commands. That gives the learner a simple foothold: low vision users (zoom, high contrast).

      +

      Alex: First, open Source Control: Ctrl+Shift+G. Then, in the Source Control panel, there may be a "Stashes" section below Staged Changes (visible when stashes exist). After that, click a stash to see what it contains. Finally, right-click a stash to Apply, Pop, or Drop it. The rhythm is simple: orient, act, verify, then continue.

      +

      Jamie: Before we leave Learning Cards: Stash Management, what is the practical point?

      +

      Alex: First, 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. Then, 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. After that, after applying a stash, your files reappear in the Changes section of Source Control. Check the file count to confirm. Think of it as a rail line: each stop confirms you are still on the right route before the next one.

      -

      Jamie: Let's pause on 7. Landmark Structure by Page Type. What should a learner take away from it?

      -

      Alex: Here is the plain-English version of 7. Landmark Structure by Page Type. Each GitHub page type has a consistent landmark pattern. Put another way, knowing the pattern means you can skip steps 2 and 3 above for familiar pages.

      -

      Alex: Keep the teaching thread moving. This is where 8. GitHub's Heading Hierarchy in Practice becomes real: GitHub uses a predictable heading structure. That matters in practice: Learning this pattern means you can navigate any page by heading level alone. The workshop is closer to rehearsal than lecture. You hear the move, try the move, and then check what changed.

      -

      Jamie: Let's pause on Pull request detail - Files Changed tab. What should a learner take away from it?

      -

      Alex: Keep the learner anchored in Pull request detail - Files Changed tab. 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.

      +

      Jamie: Let's pause on Creating a stash. What should a learner take away from it?

      +

      Alex: Start with Creating a stash. There is something to understand, something to try, and something that proves the try worked.

      +

      Alex: First, press Ctrl+Shift+P, type "git stash". Then, select "Git: Stash" - NVDA announces the result. After that, an input appears asking for a stash message - type something descriptive (e.g., "WIP: documentation changes for Timeline section"). Finally, press Enter - your changes disappear from Source Control and are saved in the stash. Think of it as a rail line: each stop confirms you are still on the right route before the next one.

      +

      Jamie: Before we leave Creating a stash, what is the practical point?

      +

      Alex: First, NVDA announces the Source Control panel update (file counts drop to 0). Treat it like a recipe: do not add the next ingredient until the previous one is actually in the bowl.

      +

      Jamie: Let's pause on Applying a stash. What should a learner take away from it?

      +

      Alex: Start with Applying a stash. There is something to understand, something to try, and something that proves the try worked.

      +

      Alex: First, press Ctrl+Shift+P, type "git stash pop". Then, select "Git: Pop Stash.". After that, a list of stashes appears - navigate with Up/Down Arrow. Finally, each item is announced with the stash message you wrote. Treat it like a recipe: do not add the next ingredient until the previous one is actually in the bowl.

      +

      Jamie: Before we leave Applying a stash, what is the practical point?

      +

      Alex: First, press Enter to apply and delete the stash. Then, your changes reappear in the Changes section. It is a checklist, but a meaningful one: every item creates evidence that the next step is safe.

      +

      Jamie: Let's pause on Viewing stashes. What should a learner take away from it?

      +

      Alex: This is where Viewing stashes becomes real: screen reader users (VoiceOver on macOS). That matters in practice: GitHub.com does not have a stash feature. The workshop is closer to rehearsal than lecture. You hear the move, try the move, and then check what changed.

      +

      Alex: First, press Ctrl+Shift+P, type "git stash list". Then, or in the terminal: type git stash list and read the output line by line. After that, press Cmd+Shift+P, type "git stash". Finally, select "Git: Stash" and provide a message. It is a checklist, but a meaningful one: every item creates evidence that the next step is safe.

      +

      Jamie: Before we leave Viewing stashes, what is the practical point?

      +

      Alex: First, press Return. Then, to apply: Cmd+Shift+P, type "git stash pop", select from the list with VO+Down Arrow, press Return. After that, create a draft commit on a temporary branch. Finally, or use GitHub Codespaces (which runs a full VS Code environment in the browser and supports git stash in the terminal). It is like walking a hallway with named doors: read the sign, enter the right room, then confirm where you landed.

      +

      Alex: Treat examples as spoken recipes, not decorations. You may hear something like 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. Read the command, understand what it changes, then run it only when the repository state matches the lesson.

      -

      Alex: Keep the teaching thread moving. Start with Learning Cards: GitHub's Heading Hierarchy. There is something to understand, something to try, and something that proves the try worked.

      -

      Alex: The practical takeaway is this. 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. 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.

      -

      Jamie: Let's pause on 9. How GitHub's Layout Changes by Viewport. What should a learner take away from it?

      -

      Alex: Start with 9. How GitHub's Layout Changes by Viewport: GitHub is a responsive web application. The next useful detail is this: The layout shifts at different screen widths, and this affects what landmarks and headings you encounter.

      -

      Alex: Keep the teaching thread moving. Start with At full desktop width (1200px+). There is something to understand, something to try, and something that proves the try worked.

      -

      Alex: The practical takeaway is this. File tree and sidebar are visible alongside the main content. The full repository tab bar is visible. All landmark regions described above are present.

      +

      Jamie: How should someone ask for help in a way that gets them unstuck faster?

      +

      Alex: Keep the learner anchored in 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. This is the part to say slowly: It is the most underused recovery tool in Git.

      +

      Jamie: What is the judgment call here?

      +

      Alex: Start with When to Use Reflog. There is something to understand, something to try, and something that proves the try worked.

      +

      Alex: Use the comparison to make a decision, not to recite a table. The main contrasts are: Scenario means What happened means Reflog solution. Deleted a branch by mistake means git branch -D feature/x means Find the last commit SHA from reflog → recreate branch. git reset --hard lost commits means Moved HEAD to older commit means Find the SHA before the reset → reset back to it.

      +

      Jamie: Let's pause on Reading the Reflog in VS Code Terminal. What should a learner take away from it?

      +

      Alex: Start with Reading the Reflog in VS Code Terminal: Run this in the integrated terminal (Ctrl+Backtick). The next useful detail is this: The output is plain text - read line by line with ↓.

      +

      Alex: Treat examples as spoken recipes, not decorations. You may hear something like git reflog. Read the command, understand what it changes, then run it only when the repository state matches the lesson.

      -

      Jamie: Let's pause on At tablet width (768-1199px). What should a learner take away from it?

      -

      Alex: Start with At tablet width (768-1199px). There is something to understand, something to try, and something that proves the try worked.

      -

      Alex: The practical takeaway is this. 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.

      -

      Alex: Keep the teaching thread moving. Keep the learner anchored in At mobile width (below 768px). Consistent experience recommendation: Use your browser maximized or at full desktop width during this workshop. This is the part to say slowly: GitHub's landmark and heading structure is most consistent at desktop width.

      -

      Alex: The practical takeaway is this. 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.

      -

      Jamie: Turn that into a path someone can follow.

      -

      Alex: The reason 10. The Mental Model - Building Your Internal Map matters is that after your first day of using GitHub, you will have an internal map. That gives the learner a simple foothold: here is what that map should look like.

      -

      Alex: First, press 1 - hear the H1 - know what floor you are on. Then, press D - hear the landmarks - know what rooms are available. After that, press NVDA+F7 - see the full outline - know what's in the room. The rhythm is simple: orient, act, verify, then continue.

      +

      Jamie: Let's pause on If you need to restore a commit that has been lost. What should a learner take away from it?

      +

      Alex: Here is the plain-English version of If you need to restore a commit that has been lost. 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. It is like learning a transit route. The names of the stops matter because they tell you whether you are still going the right direction.

      +

      Alex: Treat examples as spoken recipes, not decorations. You may hear something like 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. Read the command, understand what it changes, then run it only when the repository state matches the lesson.

      +

      Jamie: Let's pause on Recovering a Deleted Branch. What should a learner take away from it?

      +

      Alex: Start with Recovering a Deleted Branch. There is something to understand, something to try, and something that proves the try worked.

      +

      Alex: Treat examples as spoken recipes, not decorations. You may hear something like 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. Read the command, understand what it changes, then run it only when the repository state matches the lesson.

      +

      Alex: Keep the teaching thread moving. Keep the learner anchored in Why Reflog Is Local-Only. Reflog records are stored in your local.git/ directory and are not pushed to GitHub. This is the part to say slowly: 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.

      -

      Alex: Keep the teaching thread moving. Start with Learning Cards: Building Your Internal Map. There is something to understand, something to try, and something that proves the try worked.

      -

      Alex: The practical takeaway is this. 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. 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.

      -

      Jamie: Let's pause on Try It: The 60-Second Orientation. What should a learner take away from it?

      -

      Alex: Here is the plain-English version of Try It: The 60-Second Orientation. Time: 1 minute What you need: A browser with your screen reader running. Put another way, open any GitHub repository - try github.com/community-access/accessibility-agents - and prove to yourself that the mental model works.

      -

      Alex: First, press 1 - your screen reader announces the repo name. You know where you are. Then, press D - you hear the first landmark. Press D again to hear the next one. You now know the rooms on this floor. After that, press 2 - you jump to the first section heading. Press 2 again to scan the page structure. Finally, press H three times - you're moving through headings at any level. You're reading the outline. Treat it like a recipe: do not add the next ingredient until the previous one is actually in the bowl.

      -

      Alex: Keep the teaching thread moving. This is where Day 2 Amplifier becomes real: once you have this mental model solid, the Accessibility Agents make more sense. That matters in practice: 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.

      +

      Jamie: What do you want them to do when the plan breaks?

      +

      Alex: Start with Learning Cards: Emergency Recovery. There is something to understand, something to try, and something that proves the try worked.

      +

      Alex: The practical takeaway is this. 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. 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.

      +

      Alex: Keep the teaching thread moving. Start with 11. Alternative Git Interfaces: VS Code's Source Control panel is one way to use Git. The next useful detail is this: These alternatives exist for different workflows. Think of it like entering a new building: first you find the lobby, then the room, then the door you actually need.

      +

      Jamie: What stays the same when the tool changes?

      +

      Alex: Start with GitHub Desktop. There is something to understand, something to try, and something that proves the try worked.

      +

      Alex: The practical takeaway is this. Graphical Git client. Download: 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.

      -

      Jamie: Let's pause on A Screen Reader Guide to GitHub Repositories. What should a learner take away from it?

      -

      Alex: Keep the learner anchored in A Screen Reader Guide to GitHub Repositories. everything you need to explore a GitHub repository using your keyboard and screen reader. This is the part to say slowly: 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.

      -

      Alex: Keep the teaching thread moving. The reason Workshop Recommendation (Chapter 3) matters is that chapter 3 is a confidence-building orientation chapter. The interface gets friendlier when it stops being a wall of controls and starts being a set of named places.

      -

      Alex: The practical takeaway is this. There are none. Automation check: none. Why: this chapter teaches navigation foundations that are practiced in later issue and PR chapters.

      -

      Jamie: Let's pause on Safety-First Learning Pattern. What should a learner take away from it?

      -

      Alex: Start with Safety-First Learning Pattern: Use this sequence before moving to graded chapters.

      -

      Alex: First, learn the page structure (heading, landmarks, tabs). Then, practice orientation (1, D, heading list). After that, confirm readiness with a peer or facilitator. Finally, move to Chapter 4 for Learning Room orientation, then Chapter 5 for issue-based, traceable challenges. Think of it as a rail line: each stop confirms you are still on the right route before the next one.

      +

      Alex: Keep the teaching thread moving. Start with GitHub CLI (gh). There is something to understand, something to try, and something that proves the try worked.

      +

      Alex: The practical takeaway is this. 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).

      +

      Jamie: Let's pause on Common commands. What should a learner take away from it?

      +

      Alex: Keep the learner anchored in Common commands. See Culture & Etiquette for more gh examples.

      +

      Alex: Treat examples as spoken recipes, not decorations. You may hear something like 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. Read the command, understand what it changes, then run it only when the repository state matches the lesson.

      +

      Alex: Keep the teaching thread moving. Start with Git CLI (Terminal). There is something to understand, something to try, and something that proves the try worked.

      +

      Alex: The practical takeaway is this. The standard Git command-line interface. Included with VS Code (integrated terminal: Ctrl+Backtick).

      -

      Alex: Keep the teaching thread moving. Here is the plain-English version of About Learning Cards in This Chapter. This chapter provides learning cards: expandable blocks that offer perspective-specific guidance for different ways of working. Put another way, not every card appears at every step.

      -

      Jamie: Let's pause on What Is a Repository Page? What should a learner take away from it?

      -

      Alex: This is where What Is a Repository Page? becomes real: 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). That matters in practice: This page has several distinct regions.

      -

      Alex: Keep the teaching thread moving. Keep the learner anchored in Description. The repository home page is organized from top to bottom as follows. This is the part to say slowly: The Navigation bar (GitHub global nav) contains the avatar menu, Notifications, and search. A good GitHub workflow is like a well-run meeting: everyone knows the topic, the next action, and who has the floor.

      +

      Jamie: Before we leave Common commands, what is the practical point?

      +

      Alex: Start with Common commands: Terminal output is plain text - more predictable than GUI elements for some operations.

      +

      Alex: Treat examples as spoken recipes, not decorations. You may hear something like 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. Read the command, understand what it changes, then run it only when the repository state matches the lesson.

      +

      Jamie: Let's pause on Try It: Clone, Branch, Commit. What should a learner take away from it?

      +

      Alex: Here is the plain-English version of Try It: Clone, Branch, Commit. Time: 5 minutes What you need: VS Code with Git configured. Put another way, do the complete Git workflow once, start to finish.

      +

      Alex: First, 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. Then, 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. After that, 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. Finally, stage - Press Ctrl+Shift+G to open Source Control. Navigate to your changed file and press Enter to stage it (or use the + button). Treat it like a recipe: do not add the next ingredient until the previous one is actually in the bowl.

      +

      Jamie: Before we leave Try It: Clone, Branch, Commit, what is the practical point?

      +

      Alex: First, commit - Tab to the message input, type feat: add new thinking phrase, press Ctrl+Enter. Then, push - Press Ctrl+Shift+P → Git: Push. It is a checklist, but a meaningful one: every item creates evidence that the next step is safe.

      +

      Jamie: Let's pause on Part 1: The GitHub Pull Requests Extension. What should a learner take away from it?

      +

      Alex: This is where The GitHub Pull Requests Extension becomes real: see also: Appendix G: VS Code Reference for the complete list of GitHub Pull Requests extension keyboard shortcuts.

      -

      Jamie: Let's pause on Landing on a Repository - What to Expect. What should a learner take away from it?

      -

      Alex: The reason Landing on a Repository - What to Expect matters is that when you first navigate to a repo URL.

      -

      Alex: First, the page title is announced with the format: owner/repo-name: Short description - GitHub. Then, first heading (1 key) will navigate to the repo name: "owner/repo-name". After that, the tab bar is a landmark labeled "Repository navigation". The rhythm is simple: orient, act, verify, then continue.

      -

      Jamie: What should happen before anyone copies and runs it?

      -

      Alex: Start with Orientation sequence (do this on every new repo): 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. The next useful detail is this: Within each landmark, press H or 2 to navigate subsections - most are organized under heading level 2.

      -

      Alex: Treat examples as spoken recipes, not decorations. You may hear something like 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. Read the command, understand what it changes, then run it only when the repository state matches the lesson.

      -

      Jamie: Let's pause on Navigating the Repository Tabs. What should a learner take away from it?

      -

      Alex: Here is the plain-English version of 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). Put another way, not all tabs appear on every repository - Discussions, Wiki, and Projects must be enabled by the repository owner.

      +

      Alex: Keep the teaching thread moving. Keep the learner anchored in 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,. This is the part to say slowly: Prerequisites: Working with Pull Requests, Git & Source Control in VS Code Mac keyboard shortcuts: Throughout this chapter, all Ctrl+ shortcuts use Cmd+ on Mac, and Alt+ shortcuts use Option+ on Mac. A good GitHub workflow is like a well-run meeting: everyone knows the topic, the next action, and who has the floor.

      +

      Jamie: Where is the promise of the workshop, underneath all the logistics?

      +

      Alex: The reason Workshop Recommendation (Chapter 15, Part 1) matters is that chapter 15, Part 1 introduces the GitHub Pull Requests extension for managing PRs directly from VS Code.

      +

      Alex: The practical takeaway is this. There are 2 guided challenges. Automation check: none (extension installation and review state are account-local). The evidence is issue comment with confirmation of actions completed. The pattern is install, check out, review, comment.

      +

      Jamie: Let's pause on Chapter 15, Part 1 Practice Set. What should a learner take away from it?

      +

      Alex: Start with Chapter 15, Part 1 Practice Set. There is something to understand, something to try, and something that proves the try worked.

      +

      Alex: First, install the GitHub Pull Requests extension - add the extension to VS Code and sign in with your GitHub account. Then, check out a PR and post a review comment - download a PR branch locally, read the diff, and post one constructive review comment. Think of it as a rail line: each stop confirms you are still on the right route before the next one.

      -

      Jamie: Let's pause on How to reach the tabs. What should a learner take away from it?

      -

      Alex: This is where How to reach the tabs becomes real: the tab bar is visible just below the repository name. That matters in practice: Click the tab you want - Code, Issues, Pull requests, etc. The workshop is closer to rehearsal than lecture. You hear the move, try the move, and then check what changed.

      -

      Alex: The practical takeaway is this. 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.

      -

      Alex: First, press D to jump to the "Repository navigation" landmark. Then, press K or Tab to navigate between the tab links. After that, vO+U → Landmarks rotor → navigate to "Repository navigation". Finally, vO+Right to move through items in the landmark. It is a checklist, but a meaningful one: every item creates evidence that the next step is safe.

      -

      Jamie: Let's pause on Reading the tab labels. What should a learner take away from it?

      -

      Alex: Keep the learner anchored in 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.".

      -

      Alex: A solid project habit is to treat metadata as decision support. Labels, status, assignees, and notifications tell you what kind of attention the work needs.

      -

      Alex: Keep the teaching thread moving. The reason The Files Table matters is that see also: Appendix B: Screen Reader Cheat Sheet lists the keyboard shortcuts for navigating repository file trees. That gives the learner a simple foothold: the files table is the core of the Code tab - it shows every file and folder in the repo.

      +

      Jamie: Let's pause on Practice 15.1 Step-by-Step: Install the Extension. What should a learner take away from it?

      +

      Alex: Here is the plain-English version of Practice 15.1 Step-by-Step: Install the Extension. Install the GitHub Pull Requests and Issues extension and authenticate with your GitHub account. Put another way, VS Code desktop with your Learning Room repository open.

      +

      Alex: First, open the Extensions sidebar: Ctrl+Shift+X (Mac: Cmd+Shift+X). Then, your screen reader announces "Extensions: Marketplace." The search box has focus. After that, type GitHub Pull Requests in the search box and press Enter. Finally, navigate down the results list. Select GitHub Pull Requests (publisher: GitHub). Treat it like a recipe: do not add the next ingredient until the previous one is actually in the bowl.

      +

      Jamie: Before we leave Practice 15.1 Step-by-Step: Install the Extension, what is the practical point?

      +

      Alex: First, activate the Install button. VS Code installs the extension and may show a notification. Then, after installation, VS Code prompts you to sign in. Activate Sign in to GitHub. After that, a browser window opens for GitHub OAuth. Approve the authorization and return to VS Code. Finally, verify: open the Explorer sidebar (Ctrl+Shift+E). You should now see a GitHub section in the sidebar showing Pull Requests and Issues. It is a checklist, but a meaningful one: every item creates evidence that the next step is safe.

      +

      Jamie: Let's pause on Practice 15.2 Step-by-Step: Check Out a PR and Post a Comment. What should a learner take away from it?

      +

      Alex: This is where Practice 15.2 Step-by-Step: Check Out a PR and Post a Comment becomes real: check out someone else's PR branch locally, read the diff in VS Code, and post one constructive review comment. That matters in practice: VS Code with the GitHub Pull Requests extension installed. The workshop is closer to rehearsal than lecture. You hear the move, try the move, and then check what changed.

      +

      Alex: First, open the Command Palette: Ctrl+Shift+P (Mac: Cmd+Shift+P). Then, type GitHub Pull Requests: Focus on Pull Requests View and select it. The Pull Requests panel opens. After that, navigate the list of open PRs. Find one that is not yours (a classmate's PR from Chapter 6, 7, or 14). Finally, 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. It is a checklist, but a meaningful one: every item creates evidence that the next step is safe.

      +

      Jamie: Before we leave Practice 15.2 Step-by-Step: Check Out a PR and Post a Comment, what is the practical point?

      +

      Alex: First, open the Command Palette again and run GitHub Pull Requests: Open Changed Files. This shows the list of files the PR changed. Then, open one changed file. VS Code opens the Diff Editor showing old content on the left and new content on the right. After that, 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). Finally, find one specific thing to comment on: a typo, an unclear sentence, a missing step, or something the author did well. It is like walking a hallway with named doors: read the sign, enter the right room, then confirm where you landed.

      +

      Jamie: What should the learner prove to themselves after each small task?

      +

      Alex: Keep the learner anchored in Completing Chapter 15, Part 1: Submit Your Evidence. Open your assigned setup or review practice issue and post a completion comment. This is the part to say slowly: Close your Chapter 12 challenge issues when done.

      -

      Jamie: Let's pause on Reaching the files table. What should a learner take away from it?

      -

      Alex: Start with Reaching the files table: 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. The next useful detail is this: It's visible immediately below the branch selector.

      -

      Alex: The practical takeaway is this. 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.

      -

      Alex: First, name - file or folder name. Then, message - the most recent commit message that changed this file. After that, age - how long ago that commit happened. Think of it as a rail line: each stop confirms you are still on the right route before the next one.

      -

      Alex: Keep the teaching thread moving. Here is the plain-English version of 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. Put another way, for example: "docs/ Add accessibility guide 3 days ago". It is like learning a transit route. The names of the stops matter because they tell you whether you are still going the right direction.

      -

      Jamie: Let's pause on Folder vs file. What should a learner take away from it?

      -

      Alex: Start with Folder vs file. There is something to understand, something to try, and something that proves the try worked.

      -

      Alex: The practical takeaway is this. 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.

      +

      Alex: Keep the teaching thread moving. Start with Expected Outcomes. There is something to understand, something to try, and something that proves the try worked.

      +

      Alex: The practical takeaway is this. 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.

      +

      Jamie: What is the teaching move inside If You Get Stuck?

      +

      Alex: Start with If You Get Stuck: Continue learning: The GitHub Skills course Review Pull Requests practices approving, requesting changes, and using suggestions in an interactive format. The next useful detail is this: See Appendix Z for the full catalog.

      +

      Alex: First, extension does not install? Reload VS Code: Ctrl+Shift+P, then run Developer: Reload Window. Then, oAuth sign-in fails? Verify your GitHub account is active in the browser first, close VS Code, reopen, and retry. After that, pR list is empty? Switch to "All Open" view in the GitHub Pull Requests panel. Finally, checkout fails? Confirm you have write access to the repository. If not, use the read-only GitHub.com fallback. Think of it as a rail line: each stop confirms you are still on the right route before the next one.

      +

      Jamie: If someone only remembers one thing from If You Get Stuck, what should it be?

      +

      Alex: First, diff Editor is hard to navigate? Press F7 for the Accessible Diff Viewer mode, which is purpose-built for screen readers. Then, cannot find the Add Comment command? Use Command Palette and search for GitHub Pull Requests: Add Comment. After that, ask facilitator to help verify the GitHub PR panel and model one review comment. Finally, finished but not sure you did it right? Compare your work against the Challenge 11 reference solution. Treat it like a recipe: do not add the next ingredient until the previous one is actually in the bowl.

      +

      Alex: Keep the teaching thread moving. Here is the plain-English version of Learning Moment. Reviewing others' work refines your own standards and builds community trust. Put another way, the comment you just wrote helps another student learn - and you learn by articulating what makes documentation clear. It is like learning a transit route. The names of the stops matter because they tell you whether you are still going the right direction.

      -

      Alex: Keep the teaching thread moving. Start with Learning Cards: The Files Table. There is something to understand, something to try, and something that proves the try worked.

      -

      Alex: The practical takeaway is this. 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. 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.

      -

      Jamie: Let's pause on The Branch Selector. What should a learner take away from it?

      -

      Alex: The reason The Branch Selector matters is that the branch selector button sits just above the files table. That gives the learner a simple foothold: it lets you switch which branch you are viewing.

      -

      Jamie: Let's pause on How to open the branch selector. What should a learner take away from it?

      -

      Alex: Start with How to open the branch selector: Mouse users see the current branch name as a button with a dropdown arrow (e.g., main ▼) just above the file table. The next useful detail is this: Type to filter branches, then click a branch name to switch. Think of it like entering a new building: first you find the lobby, then the room, then the door you actually need.

      -

      Alex: The practical takeaway is this. 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.

      -

      Alex: First, after reaching the repository navigation landmark, press B to navigate to buttons. Then, the branch button reads: "[branch-name] branch" (e.g., "main branch"). After that, press Enter to open the dropdown. Finally, tab to the branch button (it will be labeled with the current branch name). Think of it as a rail line: each stop confirms you are still on the right route before the next one.

      -

      Jamie: Before we leave How to open the branch selector, what is the practical point?

      -

      Alex: First, vO+Space to open. Treat it like a recipe: do not add the next ingredient until the previous one is actually in the bowl.

      +

      Jamie: What is the teaching move inside Learning Pattern Used in This Chapter?

      +

      Alex: First, install and configure the tool before starting the task. Then, practice on someone else's work first (reviewing is safer than authoring). After that, use accessibility tools (F7 Accessible Diff Viewer) to navigate efficiently. Finally, write specific, constructive feedback (not just "looks good"). It is a checklist, but a meaningful one: every item creates evidence that the next step is safe.

      +

      Alex: Keep the teaching thread moving. Keep the learner anchored in 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.

      +

      Jamie: Let's pause on Method 1: Extensions Sidebar. What should a learner take away from it?

      +

      Alex: Start with Method 1: Extensions Sidebar. There is something to understand, something to try, and something that proves the try worked.

      +

      Alex: First, open Extensions sidebar: Ctrl+Shift+X (Mac: Cmd+Shift+X). Then, type "GitHub Pull Requests" in the search box. After that, find "GitHub Pull Requests and Issues" (publisher: GitHub). Finally, navigate to the extension in the results list. The rhythm is simple: orient, act, verify, then continue.

      +

      Jamie: Before we leave Method 1: Extensions Sidebar, what is the practical point?

      +

      Alex: First, press Enter to open the extension detail page. Then, tab to "Install" button → press Enter. Think of it as a rail line: each stop confirms you are still on the right route before the next one.

      -

      Jamie: Let's pause on Inside the branch dropdown. What should a learner take away from it?

      -

      Alex: Here is the plain-English version of Inside the branch dropdown. 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. Put another way, VoiceOver: After activating the button, VO+Down to interact with the dropdown → VO+Right to navigate items.

      -

      Jamie: Let's pause on Switching to a tag. What should a learner take away from it?

      -

      Alex: This is where Switching to a tag becomes real: tags mark specific releases or versions. That matters in practice: The branch dropdown also provides tag navigation.

      -

      Alex: First, open the branch button (same steps as above). Then, inside the dropdown, navigate to the tabs control at the top (reads as "Branches tab" and "Tags tab"). After that, use ←/→ to switch to the Tags tab. Finally, tab to move to the tags list. It is a checklist, but a meaningful one: every item creates evidence that the next step is safe.

      -

      Jamie: Before we leave Switching to a tag, what is the practical point?

      -

      Alex: First, navigate with ↑/↓ and press Enter to select a tag. It is like walking a hallway with named doors: read the sign, enter the right room, then confirm where you landed.

      -

      Jamie: Let's pause on Cloning a Repository. What should a learner take away from it?

      -

      Alex: Keep the learner anchored in Cloning a Repository. Cloning copies the repository to your local machine so you can work with it in VS Code or the terminal. This is the part to say slowly: Alternative: Tab further to find Download ZIP if you want a one-time copy without Git.

      -

      Alex: First, on the repository's main page (Code tab), find and click the green Code button above the file table. Then, a popover opens showing HTTPS, SSH, and GitHub CLI tabs. After that, click the HTTPS tab (default) and click the copy icon next to the URL. Finally, open your terminal, cd to where you want the folder, and run git clone. It is like walking a hallway with named doors: read the sign, enter the right room, then confirm where you landed.

      -

      Jamie: Before we leave Cloning a Repository, what is the practical point?

      -

      Alex: First, alternatively, click Download ZIP to get a one-time archive without Git. Then, press 1 or Shift+1 to navigate to the repository h1 heading. After that, press B to navigate to the next button - look for the "Code" button. Finally, press Enter or Space to open the Code flyout panel. The rhythm is simple: orient, act, verify, then continue.

      -

      Alex: Treat examples as spoken recipes, not decorations. You may hear something like 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. Read the command, understand what it changes, then run it only when the repository state matches the lesson.

      +

      Jamie: Before we leave Method 2: Command Palette, what is the practical point?

      +

      Alex: Start with Method 2: Command Palette: The Extensions sidebar is a tree view. The next useful detail is this: Use Up/Down Arrow to navigate, Enter to open an extension's detail page. Think of it like entering a new building: first you find the lobby, then the room, then the door you actually need.

      +

      Alex: First, ctrl+Shift+P. Then, type "install extensions". After that, select "Extensions: Install Extensions". Finally, search for "GitHub Pull Requests". Think of it as a rail line: each stop confirms you are still on the right route before the next one.

      +

      Jamie: What is the teaching move inside Method 2: Command Palette?

      +

      Alex: First, install "GitHub Pull Requests and Issues". Treat it like a recipe: do not add the next ingredient until the previous one is actually in the bowl.

      +

      Jamie: Let's pause on Signing In to GitHub. What should a learner take away from it?

      +

      Alex: Here is the plain-English version of Signing In to GitHub. After installation, VS Code prompts you to sign in.

      +

      Alex: First, a notification appears: "Sign in to GitHub to use Pull Requests". Then, navigate to the notification (Alt+N / Mac: Option+N, or status bar navigation). After that, select "Sign in". Finally, VS Code opens your browser for GitHub OAuth authentication. Treat it like a recipe: do not add the next ingredient until the previous one is actually in the bowl.

      +

      Jamie: Before we leave Signing In to GitHub, what is the practical point?

      +

      Alex: First, authorize VS Code in the browser. Then, return to VS Code - you're now signed in. It is a checklist, but a meaningful one: every item creates evidence that the next step is safe.

      +

      Alex: Keep the teaching thread moving. Start with Verify sign-in. There is something to understand, something to try, and something that proves the try worked.

      +

      Alex: The practical takeaway is this. 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.

      -

      Jamie: How do you keep commands from becoming magic words?

      -

      Alex: The reason Or with standard Git matters is that setup: Install the GitHub CLI from cli.github.com and authenticate with gh auth login. The interface gets friendlier when it stops being a wall of controls and starts being a set of named places.

      -

      Alex: Treat examples as spoken recipes, not decorations. You may hear something like git clone https://github.com/community-access/git-going-with-github.git; cd git-going-with-github. Read the command, understand what it changes, then run it only when the repository state matches the lesson.

      -

      Jamie: Let's pause on Learning Cards: Cloning a Repository. What should a learner take away from it?

      -

      Alex: Start with Learning Cards: Cloning a Repository. There is something to understand, something to try, and something that proves the try worked.

      -

      Alex: The practical takeaway is this. 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. 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.

      -

      Jamie: Let's pause on Tool Cards: Clone a Repository. What should a learner take away from it?

      -

      Alex: Here is the plain-English version of Tool Cards: Clone a Repository. github.dev (web editor): No clone needed. Put another way, press the period key on any repository page to open it in the browser-based editor instantly.

      -

      Alex: First, click the green Code button above the file table. Then, copy the HTTPS URL. After that, you will paste this into your local tool of choice below. Finally, press Ctrl+Shift+P, type Git: Clone, press Enter. Treat it like a recipe: do not add the next ingredient until the previous one is actually in the bowl.

      -

      Jamie: Before we leave Tool Cards: Clone a Repository, what is the practical point?

      -

      Alex: First, paste the HTTPS URL and choose a local folder. Then, click Open when prompted. After that, file Clone Repository (or Ctrl+Shift+O). Finally, paste the URL or select from your GitHub account list. It is a checklist, but a meaningful one: every item creates evidence that the next step is safe.

      -

      Alex: Treat examples as spoken recipes, not decorations. You may hear something like git clone https://github.com/owner/repo.git; cd repo. Read the command, understand what it changes, then run it only when the repository state matches the lesson.

      +

      Jamie: Let's pause on What the Extension Adds. What should a learner take away from it?

      +

      Alex: Start with What the Extension Adds. There is something to understand, something to try, and something that proves the try worked.

      +

      Alex: The practical takeaway is this. 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.

      +

      Alex: Keep the teaching thread moving. Start with Learning Cards: Installing the PR Extension. There is something to understand, something to try, and something that proves the try worked.

      +

      Alex: The practical takeaway is this. 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". 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.

      +

      Jamie: Let's pause on Method 1: Activity Bar. What should a learner take away from it?

      +

      Alex: Start with Method 1: Activity Bar: Click the GitHub logo icon in the Activity Bar (the vertical strip of icons on the far left). The next useful detail is this: The GitHub Pull Requests panel opens.

      +

      Alex: The practical takeaway is this. "Pull Requests". "Issues".

      +

      Alex: First, the Activity Bar is not always reachable by Tab from the editor. Then, use Ctrl+Shift+P (Mac: Cmd+Shift+P) → type "GitHub Pull Requests: View Pull Request" or "Focus on Pull Requests View" → press Enter. After that, alternatively press Ctrl+Shift+G (Mac: Cmd+Shift+G) to open Source Control, then Tab until you reach the Activity Bar icon strip. Finally, navigate to the repository on GitHub.com. Think of it as a rail line: each stop confirms you are still on the right route before the next one.

      +

      Jamie: Before we leave Method 1: Activity Bar, what is the practical point?

      +

      Alex: First, click the Pull requests tab. Then, click any PR title to view its conversation, commits, and changed files. After that, use the Files changed tab to review diffs. Treat it like a recipe: do not add the next ingredient until the previous one is actually in the bowl.

      +

      Alex: Treat examples as spoken recipes, not decorations. You may hear something like 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". Read the command, understand what it changes, then run it only when the repository state matches the lesson.

      -

      Jamie: Let's pause on Fork vs. Clone vs. Branch - What Is the Difference? What should a learner take away from it?

      -

      Alex: This is where Fork vs. Clone vs. Branch - What Is the Difference? becomes real: these three concepts are related but serve different purposes. That matters in practice: Students often confuse them, so here is a side-by-side comparison.

      -

      Alex: Keep the teaching thread moving. Start with Learning Cards: Fork vs. Clone vs. Branch. There is something to understand, something to try, and something that proves the try worked.

      -

      Alex: The practical takeaway is this. 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. 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.

      -

      Jamie: Let's pause on Watching, Starring, and Forking. What should a learner take away from it?

      -

      Alex: The reason Watching, Starring, and Forking matters is that these three actions let you follow, bookmark, or copy a repository.

      +

      Jamie: Let's pause on Method 2: Explorer Section. What should a learner take away from it?

      +

      Alex: Start with Method 2: Explorer Section. There is something to understand, something to try, and something that proves the try worked.

      +

      Alex: First, open Explorer: Ctrl+Shift+E (Mac: Cmd+Shift+E). Then, navigate with Arrow keys to find the "GitHub Pull Requests" section. After that, expand it with Right Arrow. Treat it like a recipe: do not add the next ingredient until the previous one is actually in the bowl.

      +

      Jamie: Let's pause on Description. What should a learner take away from it?

      +

      Alex: This is where Description becomes real: the GitHub Pull Requests panel has two top-level sections. That matters in practice: "My Pull Requests" contains four filters: Assigned to Me, Created by Me, Waiting for my Review, and All Open.

      +

      Alex: Keep the teaching thread moving. Keep the learner anchored in Screen reader announcement example. "Pull Request 42: Add Timeline Guide, opened by jeffb, 2 days ago, 3 files changed". A good GitHub workflow is like a well-run meeting: everyone knows the topic, the next action, and who has the floor.

      -

      Jamie: Let's pause on Watching (subscribe to notifications). What should a learner take away from it?

      -

      Alex: Start with Watching (subscribe to notifications): The Watch, Star, and Fork buttons are at the top-right of the repository page, just below the global navigation bar. The next useful detail is this: Click Watch to open a dropdown of subscription options: Participating and @mentions, All Activity, or Ignore.

      -

      Alex: First, press L to navigate through list items to reach the Main landmark. Then, continue pressing L until you find the Watch button (reads as "Watch this repository"). After that, press Enter to open the subscription submenu. Finally, press ↑/↓ to browse options: Participating, All Activity, Ignore, Custom. Think of it as a rail line: each stop confirms you are still on the right route before the next one.

      -

      Jamie: Before we leave Watching (subscribe to notifications), what is the practical point?

      -

      Alex: First, press Enter to confirm. Then, 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. Treat it like a recipe: do not add the next ingredient until the previous one is actually in the bowl.

      -

      Jamie: Let's pause on Forking (create your own copy). What should a learner take away from it?

      -

      Alex: Here is the plain-English version of Forking (create your own copy). Click the Fork button (top-right, next to Watch and Star). Put another way, a page opens asking you to choose the owner and repository name for your fork.

      -

      Alex: First, press L to navigate list items in the Main landmark. Then, press I to navigate individual list items until you find "Fork your own copy". After that, press Enter to start the fork workflow. Finally, the fork creation page lets you choose the owner and repository name. Treat it like a recipe: do not add the next ingredient until the previous one is actually in the bowl.

      -

      Jamie: Before we leave Forking (create your own copy), what is the practical point?

      -

      Alex: First, tab to "Create fork" and press Enter. It is a checklist, but a meaningful one: every item creates evidence that the next step is safe.

      -

      Jamie: Let's pause on Starring (bookmarking). What should a learner take away from it?

      -

      Alex: This is where Starring (bookmarking) becomes real: the button changes to Starred with a filled star icon to confirm. That matters in practice: 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. The workshop is closer to rehearsal than lecture. You hear the move, try the move, and then check what changed.

      -

      Alex: First, press L to navigate list items in the Main landmark. Then, press I to navigate individual list items until you find "Star this repository". After that, press Enter or Space to star. Finally, the button text changes to "Unstar" on the next focus. It is a checklist, but a meaningful one: every item creates evidence that the next step is safe.

      +

      Jamie: Let's pause on By status. What should a learner take away from it?

      +

      Alex: Start with By status. There is something to understand, something to try, and something that proves the try worked.

      +

      Alex: The practical takeaway is this. "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.

      +

      Alex: Keep the teaching thread moving. Start with By repository: The tree organizes PRs by repository.

      +

      Jamie: Let's pause on Viewing PR Details. What should a learner take away from it?

      +

      Alex: Here is the plain-English version of Viewing PR Details. A PR detail view opens in the editor area showing.

      +

      Alex: The practical takeaway is this. 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).

      +

      Alex: First, navigate to a PR in the tree. Then, press Enter. Treat it like a recipe: do not add the next ingredient until the previous one is actually in the bowl.

      -

      Jamie: Let's pause on Viewing a Single File. What should a learner take away from it?

      -

      Alex: Keep the learner anchored in 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).

      -

      Alex: Keep the teaching thread moving. The reason Reading a Markdown file (like README.md) matters is that the README renders with full heading structure.

      -

      Alex: The practical takeaway is this. H - navigate headings within the README. T - find any tables. L - find lists. K - navigate links.

      -

      Jamie: Let's pause on Reading a code file. What should a learner take away from it?

      -

      Alex: Start with Reading a code file: Code files render as a table where each row is one line of code.

      +

      Alex: Keep the teaching thread moving. Start with Screen reader experience. There is something to understand, something to try, and something that proves the try worked.

      +

      Alex: The practical takeaway is this. 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.

      +

      Jamie: Let's pause on 3. Checking Out a Pull Request Branch. What should a learner take away from it?

      +

      Alex: Keep the learner anchored in 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.

      +

      Alex: Keep the teaching thread moving. Start with Why Check Out a PR. There is something to understand, something to try, and something that proves the try worked.

      +

      Alex: The practical takeaway is this. 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.

      -

      Alex: Keep the teaching thread moving. Here is the plain-English version of The file action buttons. Above the file content, there are buttons. It is like learning a transit route. The names of the stops matter because they tell you whether you are still going the right direction.

      -

      Alex: The practical takeaway is this. 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).

      -

      Jamie: Let's pause on How to reach these buttons. What should a learner take away from it?

      -

      Alex: This is where How to reach these buttons becomes real: press B from within the file area, OR use D to navigate to the "Repository files navigation" landmark.

      -

      Jamie: Let's pause on Editing a file. What should a learner take away from it?

      -

      Alex: Keep the learner anchored in Editing a file. Switch back to Browse Mode after step 6 (NVDA+Space) to use Shift+Tab more reliably to reach the commit button.

      -

      Alex: First, open the file you want to edit. Then, click the pencil icon (Edit file) in the top-right of the file content area. After that, the file opens in a web editor - click in the content area and edit. Finally, when done, scroll down to "Commit changes", type a commit message, and click the green Commit changes button. It is like walking a hallway with named doors: read the sign, enter the right room, then confirm where you landed.

      -

      Jamie: Before we leave Editing a file, what is the practical point?

      -

      Alex: First, choose "Commit directly to main" (or your branch) and confirm. Then, press K to navigate links until you find the "Edit file" link (may be labeled with a pencil icon description). After that, press Enter to activate the link - the page opens in edit mode with a code editor textarea. Finally, switch to Focus Mode: press NVDA+Space (NVDA) or Insert+Z (JAWS). The rhythm is simple: orient, act, verify, then continue.

      -
      -

      Jamie: Let's pause on Learning Cards: Viewing a Single File. What should a learner take away from it?

      -

      Alex: Start with Learning Cards: Viewing a Single File. There is something to understand, something to try, and something that proves the try worked.

      -

      Alex: The practical takeaway is this. 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. 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.

      -

      Alex: Keep the teaching thread moving. Start with The Blame View: Blame shows you who changed each line of a file, in what commit, and when. The next useful detail is this: It is useful for tracing why a particular change was made. Think of it like entering a new building: first you find the lobby, then the room, then the door you actually need.

      -

      Jamie: Let's pause on Navigating Blame. What should a learner take away from it?

      -

      Alex: Start with Navigating Blame. There is something to understand, something to try, and something that proves the try worked.

      -

      Alex: First, from a file page, activate the "Blame" button. Then, the page reloads in Blame view. After that, the content is a table: left column = commit info (who, when, message), right column = the line of code. Treat it like a recipe: do not add the next ingredient until the previous one is actually in the bowl.

      +

      Jamie: Let's pause on Method 1: From the PR Detail View. What should a learner take away from it?

      +

      Alex: Start with Method 1: From the PR Detail View. There is something to understand, something to try, and something that proves the try worked.

      +

      Alex: The practical takeaway is this. Downloads the branch. Switches your local repository to that branch. Opens the changed files in the editor.

      +

      Alex: First, open a PR (see Section 2). Then, in the PR detail view, navigate to "Checkout" button. After that, press Enter. Think of it as a rail line: each stop confirms you are still on the right route before the next one.

      +

      Jamie: Let's pause on Method 2: From the PR Tree. What should a learner take away from it?

      +

      Alex: Start with Method 2: From the PR Tree. There is something to understand, something to try, and something that proves the try worked.

      +

      Alex: First, navigate to the PR in the GitHub Pull Requests tree. Then, press Shift+F10 (Mac: Ctrl+Return) to open context menu. After that, select "Checkout Pull Request". Treat it like a recipe: do not add the next ingredient until the previous one is actually in the bowl.

      +

      Jamie: Let's pause on Method 3: Command Palette. What should a learner take away from it?

      +

      Alex: This is where Method 3: Command Palette becomes real: after checkout, the bottom-left status bar shows the branch name (example: "jeffb/add-timeline-guide"). That matters in practice: Your local files now match that branch.

      +

      Alex: First, ctrl+Shift+P (Mac: Cmd+Shift+P). Then, type "GitHub Pull Requests: Checkout". After that, select "GitHub Pull Requests: Checkout Pull Request". Finally, choose the PR from the list. It is a checklist, but a meaningful one: every item creates evidence that the next step is safe.

      -

      Alex: Keep the teaching thread moving. Start with Commit History. There is something to understand, something to try, and something that proves the try worked.

      -

      Alex: The practical takeaway is this. 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.

      -

      Jamie: What should they understand before typing anything?

      -

      Alex: Start with Reading the Commits List Page. There is something to understand, something to try, and something that proves the try worked.

      -

      Alex: Treat examples as spoken recipes, not decorations. You may hear something like 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. Read the command, understand what it changes, then run it only when the repository state matches the lesson.

      -

      Alex: Keep the teaching thread moving. Start with Reading a Commit Page. There is something to understand, something to try, and something that proves the try worked.

      -

      Alex: The practical takeaway is this. The commit message (heading). Author and date. Parent commit link. A diff for every file changed.

      +

      Jamie: Let's pause on Returning to Your Original Branch. What should a learner take away from it?

      +

      Alex: Start with Returning to Your Original Branch. There is something to understand, something to try, and something that proves the try worked.

      +

      Alex: First, ctrl+Shift+P (Mac: Cmd+Shift+P). Then, type "git checkout". After that, select "Git: Checkout to.". Finally, choose your original branch (usually main or your feature branch). It is like walking a hallway with named doors: read the sign, enter the right room, then confirm where you landed.

      +

      Jamie: Let's pause on Learning Cards: Checking Out a PR. What should a learner take away from it?

      +

      Alex: Start with Learning Cards: Checking Out a PR. There is something to understand, something to try, and something that proves the try worked.

      +

      Alex: The practical takeaway is this. 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. 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.

      +

      Alex: Keep the teaching thread moving. Start with 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. Think of it like entering a new building: first you find the lobby, then the room, then the door you actually need.

      -

      Jamie: Let's pause on Searching for a File. What should a learner take away from it?

      -

      Alex: Start with Searching for a File: The "Go to file" shortcut is extremely useful when you know what you are looking for.

      -

      Jamie: Let's pause on How to use Go to File. What should a learner take away from it?

      -

      Alex: Here is the plain-English version of How to use Go to File. GitHub keyboard shortcut: T - opens the Go to File dialog. Put another way, screen reader conflict warning: T normally means "next table" in NVDA/JAWS Browse Mode.

      -

      Alex: The practical takeaway is this. If hovercards are off, no navigation penalty - just navigate normally. 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.

      -

      Alex: First, make sure you are on the Code tab of a repository. Then, 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". After that, type the filename or partial path. Finally, results appear as a dropdown - use ↓ to navigate, Enter to open. Treat it like a recipe: do not add the next ingredient until the previous one is actually in the bowl.

      -

      Jamie: Let's pause on Learning Cards: Searching for a File. What should a learner take away from it?

      -

      Alex: Start with Learning Cards: Searching for a File. There is something to understand, something to try, and something that proves the try worked.

      -

      Alex: The practical takeaway is this. 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. 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.

      +

      Jamie: Let's pause on In the PR detail view. What should a learner take away from it?

      +

      Alex: Start with In the PR detail view. There is something to understand, something to try, and something that proves the try worked.

      +

      Alex: First, scroll down to "Files Changed" section. Then, each file is a link. After that, navigate with Arrow keys. Finally, press Enter on a file to open its diff view. Treat it like a recipe: do not add the next ingredient until the previous one is actually in the bowl.

      +

      Alex: Keep the teaching thread moving. This is where Screen reader announcement becomes real: "docs/11-vscode-interface.md, 42 additions, 3 deletions".

      +

      Jamie: Let's pause on Understanding the Diff View. What should a learner take away from it?

      +

      Alex: Keep the learner anchored in Understanding the Diff View. When you open a file from "Files Changed".

      -

      Alex: Keep the teaching thread moving. Keep the learner anchored in GitHub Shortcuts for Repository Navigation - Spotlight. These are the GitHub built-in shortcuts you will use most on repository pages. This is the part to say slowly: They work by sending keystrokes directly to GitHub's JavaScript, so enable Focus Mode first (NVDA: NVDA+Space, JAWS: Insert+Z). A good GitHub workflow is like a well-run meeting: everyone knows the topic, the next action, and who has the floor.

      -

      Alex: The practical takeaway is this. About - the repo description and topics. Releases - recent published releases. Packages - Docker/npm packages attached to the repo. Contributors - the top contributors.

      -

      Jamie: Let's pause on Navigating the sidebar. What should a learner take away from it?

      -

      Alex: The reason Navigating the sidebar matters is that the sidebar content is inside the "Main" landmark, after the files table and README. That gives the learner a simple foothold: after the README, press H or 2 to reach "About" and the sidebar section headings.

      -

      Jamie: Let's pause on The Repository About Section. What should a learner take away from it?

      -

      Alex: Start with The Repository About Section: Quick way to check the project description, website link, and topics.

      -

      Alex: First, press D to walk through landmarks. Then, look for a heading "About" in the sidebar. After that, 2 or H to jump to that "About" heading. Finally, then ↓ to read the description, URL, and topics. Think of it as a rail line: each stop confirms you are still on the right route before the next one.

      +

      Alex: Keep the teaching thread moving. Start with Split view mode (default). There is something to understand, something to try, and something that proves the try worked.

      +

      Alex: The practical takeaway is this. Left side: original file (before changes). Right side: modified file (after changes). Changed lines highlighted (added = green, removed = red).

      +

      Jamie: Let's pause on Inline view mode. What should a learner take away from it?

      +

      Alex: Start with Inline view mode. There is something to understand, something to try, and something that proves the try worked.

      +

      Alex: The practical takeaway is this. Single editor. Removed lines shown with - prefix. Added lines shown with + prefix.

      +

      Alex: Keep the teaching thread moving. Start with To toggle between views. There is something to understand, something to try, and something that proves the try worked.

      +

      Alex: The practical takeaway is this. Command Palette: Ctrl+Shift+P (Mac: Cmd+Shift+P) → "Diff: Toggle Inline View".

      -

      Jamie: Let's pause on Scenario A: "I want to find out what this project does". What should a learner take away from it?

      -

      Alex: Start with Scenario A: "I want to find out what this project does". There is something to understand, something to try, and something that proves the try worked.

      -

      Alex: First, navigate to the repo URL. Then, press 1 - hear the repo name. After that, ↓ - read the description (announced as a paragraph after the heading). Finally, navigate to README: D → "Repository files navigation" → H within the README. Treat it like a recipe: do not add the next ingredient until the previous one is actually in the bowl.

      -

      Jamie: Let's pause on Scenario B: "I want to find a good file to edit". What should a learner take away from it?

      -

      Alex: Start with Scenario B: "I want to find a good file to edit". There is something to understand, something to try, and something that proves the try worked.

      -

      Alex: First, open the files table with T. Then, navigate rows with Ctrl+Alt+↓. After that, move right with Ctrl+Alt+→ to read the commit message (what's been changing recently). Finally, when found, press Enter on the Name column to open the file. It is a checklist, but a meaningful one: every item creates evidence that the next step is safe.

      -

      Jamie: Let's pause on Scenario C: "I want to know who has been working on this file recently". What should a learner take away from it?

      -

      Alex: Start with Scenario C: "I want to know who has been working on this file recently". There is something to understand, something to try, and something that proves the try worked.

      -

      Alex: First, open the file. Then, activate the "Blame" button (B from the Repository files navigation landmark). After that, navigate the blame table to see authors. It is like walking a hallway with named doors: read the sign, enter the right room, then confirm where you landed.

      +

      Jamie: Let's pause on Recommended workflow for screen reader users. What should a learner take away from it?

      +

      Alex: Start with Recommended workflow for screen reader users. There is something to understand, something to try, and something that proves the try worked.

      +

      Alex: The practical takeaway is this. Unchanged lines (for context). Removed lines (prefixed with -). Added lines (prefixed with +).

      +

      Alex: First, open a changed file from the PR detail view. Then, press F7 to jump to the first diff hunk. After that, press Alt+F2 (Mac: Option+F2) to open Accessible View. Finally, read the hunk content. It is a checklist, but a meaningful one: every item creates evidence that the next step is safe.

      +

      Jamie: Before we leave Recommended workflow for screen reader users, what is the practical point?

      +

      Alex: First, press Escape to close Accessible View. Then, press F7 to jump to the next hunk. After that, repeat until all hunks reviewed. It is like walking a hallway with named doors: read the sign, enter the right room, then confirm where you landed.

      +

      Alex: Keep the teaching thread moving. Keep the learner anchored in 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. This is the part to say slowly: Previously, deleted code could only be read, not selected. A good GitHub workflow is like a well-run meeting: everyone knows the topic, the next action, and who has the floor.

      +

      Jamie: Let's pause on Flagging Issues During Review. What should a learner take away from it?

      +

      Alex: The reason Flagging Issues During Review matters is that start Review saves your comments as a draft until you submit the full review (see Section 7).

      +

      Alex: First, navigate to the specific line in the diff. Then, press Shift+F10 (Mac: Ctrl+Return) for context menu. After that, select "Add Comment". Finally, type your comment in the input that appears. The rhythm is simple: orient, act, verify, then continue.

      +

      Jamie: Before we leave Flagging Issues During Review, what is the practical point?

      +

      Alex: First, choose "Single Comment" or "Start Review". Think of it as a rail line: each stop confirms you are still on the right route before the next one.

      +

      Alex: A solid issue habit is to read the title, the body, and the timeline before acting. You are listening for the requested action, the missing evidence, and the person who needs a response.

      -

      Jamie: Let's pause on Scenario D: "I want to understand what changed in the last release". What should a learner take away from it?

      -

      Alex: Start with Scenario D: "I want to understand what changed in the last release". There is something to understand, something to try, and something that proves the try worked.

      -

      Alex: First, navigate to the sidebar "Releases" section (H or 2). Then, activate the latest release link. After that, read the release notes (rendered Markdown with headings and lists). The rhythm is simple: orient, act, verify, then continue.

      -

      Jamie: Let's pause on Scenario E: "I want to contribute - where do I start?". What should a learner take away from it?

      -

      Alex: Start with Scenario E: "I want to contribute - where do I start?". There is something to understand, something to try, and something that proves the try worked.

      -

      Alex: First, navigate to the Code tab. Then, look for CONTRIBUTING.md in the files table. After that, open it and read the contributing guidelines. Finally, then go to Issues tab and filter by good first issue. Think of it as a rail line: each stop confirms you are still on the right route before the next one.

      -

      Jamie: Let's pause on Try It: The Five-Tab Tour. What should a learner take away from it?

      -

      Alex: Here is the plain-English version of Try It: The Five-Tab Tour. Time: 3 minutes What you need: Browser with screen reader, signed in to GitHub. Put another way, navigate to the Accessibility Agents repository and do this. It is like learning a transit route. The names of the stops matter because they tell you whether you are still going the right direction.

      -

      Alex: First, code tab - Press D to the "Repository navigation" landmark, then K to find "Code". Press Enter. You're on the file list. Then, issues tab - Press G then I (Focus Mode first: NVDA+Space). How many open issues are there? Press 3 to jump through issue titles. After that, pull Requests tab - Press G then P. Are there any open PRs? Finally, 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. Treat it like a recipe: do not add the next ingredient until the previous one is actually in the bowl.

      -

      Jamie: Before we leave Try It: The Five-Tab Tour, what is the practical point?

      -

      Alex: First, read the README - Press 1 to find the page title, then 2 to scan sections. It is a checklist, but a meaningful one: every item creates evidence that the next step is safe.

      +

      Alex: Keep the teaching thread moving. Start with Learning Cards: Reviewing Pull Requests in VS Code. There is something to understand, something to try, and something that proves the try worked.

      +

      Alex: The practical takeaway is this. 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. 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.

      +

      Jamie: Let's pause on Tool Cards: Create a Pull Request (from your editor). What should a learner take away from it?

      +

      Alex: Here is the plain-English version of Tool Cards: Create a Pull Request (from your editor). VS Code Desktop (primary for Day 2). Put another way, after you've pushed commits to a feature branch, you can create a PR without leaving VS Code.

      +

      Alex: First, ctrl+Shift+P GitHub Pull Requests: Create Pull Request. Then, fill in the title, description, and base branch. After that, click Create. Finally, push your branch, then click the Compare & pull request banner on the repo page. Treat it like a recipe: do not add the next ingredient until the previous one is actually in the bowl.

      +

      Jamie: Before we leave Tool Cards: Create a Pull Request (from your editor), what is the practical point?

      +

      Alex: First, fill in the form and click Create pull request. Then, after pushing, click Create Pull Request -- this opens gitub.com with the form pre-filled. It is a checklist, but a meaningful one: every item creates evidence that the next step is safe.

      +

      Alex: Treat examples as spoken recipes, not decorations. You may hear something like git push -u origin your-branch; gh pr create --title "Title" --body "Description". Read the command, understand what it changes, then run it only when the repository state matches the lesson.

      +

      Jamie: Let's pause on Prerequisites. What should a learner take away from it?

      +

      Alex: Start with Prerequisites. There is something to understand, something to try, and something that proves the try worked.

      +

      Alex: First, you've created a branch (see Git & Source Control: Branch Management). Then, you've made commits. After that, you've pushed the branch to GitHub (Ctrl+Shift+P / Mac: Cmd+Shift+P → "Git: Push"). It is a checklist, but a meaningful one: every item creates evidence that the next step is safe.

      -

      Jamie: Let's pause on What Is the Learning Room? What should a learner take away from it?

      -

      Alex: This is where What Is the Learning Room? becomes real: the Learning Room is your own private GitHub repository for the workshop. That matters in practice: When you accept the GitHub Classroom assignment in Block 0, GitHub copies the Community-Access/learning-room-template repository into the workshop classroom organization as the workshop organization/learning-room-your username.

      -

      Alex: Keep the teaching thread moving. Keep the learner anchored in Why a Per-Student Repo? GitHub Classroom gives each participant their own repository for three reasons. This is the part to say slowly: 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.

      -

      Alex: The practical takeaway is this. 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.

      -

      Jamie: Let's pause on Step-by-Step: Accept Your Classroom Assignment and Open Your Repo. What should a learner take away from it?

      -

      Alex: The reason Step-by-Step: Accept Your Classroom Assignment and Open Your Repo matters is that this is the very first hands-on step of Day 1. That gives the learner a simple foothold: by the end of this walkthrough you will have your own Learning Room repository on GitHub and your first challenge issue waiting for you.

      +

      Jamie: Let's pause on Method 1: Command Palette (Recommended). What should a learner take away from it?

      +

      Alex: Start with Method 1: Command Palette (Recommended). There is something to understand, something to try, and something that proves the try worked.

      +

      Alex: First, ctrl+Shift+P (Mac: Cmd+Shift+P). Then, type "GitHub Pull Requests: Create". After that, select "GitHub Pull Requests: Create Pull Request". Finally, a form opens in the editor. It is like walking a hallway with named doors: read the sign, enter the right room, then confirm where you landed.

      +

      Jamie: Let's pause on Method 2: Source Control Panel. What should a learner take away from it?

      +

      Alex: Start with Method 2: Source Control Panel. There is something to understand, something to try, and something that proves the try worked.

      +

      Alex: First, open Source Control: Ctrl+Shift+G (Mac: Cmd+Shift+G). Then, after pushing, a "Create Pull Request" button appears. After that, press Enter on that button. The rhythm is simple: orient, act, verify, then continue.

      +

      Jamie: Let's pause on Method 3: GitHub Panel. What should a learner take away from it?

      +

      Alex: Start with Method 3: GitHub Panel. There is something to understand, something to try, and something that proves the try worked.

      +

      Alex: First, open GitHub view (Activity Bar → GitHub icon). Then, right-click your branch in the tree. After that, select "Create Pull Request". Think of it as a rail line: each stop confirms you are still on the right route before the next one.

      -

      Jamie: Let's pause on 1. Open the assignment link. What should a learner take away from it?

      -

      Alex: Start with 1. Open the assignment link. There is something to understand, something to try, and something that proves the try worked.

      -

      Alex: First, in the same browser where you are signed into GitHub, open the Day 1 assignment link the facilitator shared. Then, 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"). After that, if the page asks you to authorize GitHub Classroom to access your GitHub account, activate Authorize GitHub Classroom. This is a one-time step. Think of it as a rail line: each stop confirms you are still on the right route before the next one.

      -

      Jamie: Let's pause on 2. Identify yourself (if asked). What should a learner take away from it?

      -

      Alex: Here is the plain-English version of 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.

      -

      Alex: First, 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. Then, activate the link or button next to your name. After that, 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. Treat it like a recipe: do not add the next ingredient until the previous one is actually in the bowl.

      -

      Jamie: Let's pause on 3. Accept the assignment. What should a learner take away from it?

      -

      Alex: This is where 3. Accept the assignment becomes real: the status page does not auto-announce when the repo is ready. That matters in practice: Use Browse mode and press K to step through links until you hear your repository link, or refresh the page until it appears.

      -

      Alex: First, you now see a screen with a button that says Accept this assignment (or just Accept the assignment ). Activate it. Then, 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. After that, 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/the workshop organization/learning-room-your username. It is a checklist, but a meaningful one: every item creates evidence that the next step is safe.

      +

      Alex: Keep the teaching thread moving. Start with Title (required). There is something to understand, something to try, and something that proves the try worked.

      +

      Alex: The practical takeaway is this. Auto-filled with your most recent commit message. Edit to make it descriptive (example: "Add Timeline View documentation").

      +

      Jamie: Let's pause on Description (optional but recommended). What should a learner take away from it?

      +

      Alex: Start with Description (optional but recommended). There is something to understand, something to try, and something that proves the try worked.

      +

      Alex: The practical takeaway is this. 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.

      +

      Alex: Keep the teaching thread moving. Start with Base branch (target). There is something to understand, something to try, and something that proves the try worked.

      +

      Alex: The practical takeaway is this. Usually main or develop. This is the branch your changes will merge into.

      -

      Jamie: Let's pause on 4. Open your new repository. What should a learner take away from it?

      -

      Alex: Start with 4. Open your new repository. There is something to understand, something to try, and something that proves the try worked.

      -

      Alex: The practical takeaway is this. The repo name in the heading matches learning-room-your username. 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.

      -

      Alex: First, activate the link to your repository. You land on the standard GitHub repo page for the workshop organization/learning-room-your username. Then, verify three things on this page. After that, bookmark this page. You will return here for every Day 1 challenge. It is like walking a hallway with named doors: read the sign, enter the right room, then confirm where you landed.

      -

      Jamie: Let's pause on 5. Find your first challenge issue. What should a learner take away from it?

      -

      Alex: The reason 5. Find your first challenge issue matters is that when your Learning Room repo is ready, Challenge 1 appears as a GitHub issue in your repo. That gives the learner a simple foothold: the facilitators prepare this by running the Student Progression Bot after students accept the Classroom assignment. The interface gets friendlier when it stops being a wall of controls and starts being a set of named places.

      -

      Alex: First, from your repository page, navigate to the Issues tab. Keyboard shortcut: press G then I. Then, 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]). After that, open Challenge 1. Read the issue body -- it tells you what to do, where to find evidence, and how to submit completion. The rhythm is simple: orient, act, verify, then continue.

      -

      Jamie: Let's pause on 6. Confirm Aria can talk to you. What should a learner take away from it?

      -

      Alex: Start with 6. Confirm Aria can talk to you: The PR validation bot, Aria, posts educational feedback whenever you open a pull request. The next useful detail is this: 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 ).

      +

      Jamie: Let's pause on Compare branch (source). What should a learner take away from it?

      +

      Alex: Start with Compare branch (source). There is something to understand, something to try, and something that proves the try worked.

      +

      Alex: The practical takeaway is this. Your feature branch (auto-selected). This is the branch with your changes.

      +

      Alex: Keep the teaching thread moving. Start with Reviewers (optional). There is something to understand, something to try, and something that proves the try worked.

      +

      Alex: The practical takeaway is this. Select people to review your PR. Navigate the list with Arrow keys.

      +

      Jamie: Let's pause on Labels (optional). What should a learner take away from it?

      +

      Alex: Start with Labels (optional). There is something to understand, something to try, and something that proves the try worked.

      +

      Alex: The practical takeaway is this. Add labels like documentation, accessibility, good-first-issue.

      -

      Alex: Keep the teaching thread moving. Here is the plain-English version of Workshop Recommendation (Chapter 4). Chapter 4 is a system orientation chapter.

      -

      Alex: The practical takeaway is this. There are 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.

      -

      Jamie: Let's pause on Readiness Checkpoint. What should a learner take away from it?

      -

      Alex: This is where Readiness Checkpoint becomes real: before starting Chapter 5 challenges, you should be able to.

      -

      Alex: First, find docs/CHALLENGES.md in your Learning Room repository. Then, explain the flow: issue - branch - pull request - review - merge. After that, identify where Aria bot feedback appears on a PR (the Conversation tab). It is a checklist, but a meaningful one: every item creates evidence that the next step is safe.

      -

      Alex: Keep the teaching thread moving. Keep the learner anchored in Two Tracks That Reinforce Each Other. Throughout Day 1 you work on two parallel learning tracks, both in your own account. A good GitHub workflow is like a well-run meeting: everyone knows the topic, the next action, and who has the floor.

      +

      Alex: Keep the teaching thread moving. Start with Milestone (optional). There is something to understand, something to try, and something that proves the try worked.

      +

      Alex: The practical takeaway is this. Link the PR to a project milestone.

      +

      Jamie: Let's pause on Draft PR checkbox. What should a learner take away from it?

      +

      Alex: Start with Draft PR checkbox. There is something to understand, something to try, and something that proves the try worked.

      +

      Alex: The practical takeaway is this. Check this if the PR is not ready for review yet. Unchecked = "Ready for review".

      +

      Alex: Keep the teaching thread moving. Start with Screen reader navigation. There is something to understand, something to try, and something that proves the try worked.

      +

      Alex: The practical takeaway is this. All fields are standard form inputs. Tab to move between fields. Use Arrow keys in dropdowns (reviewers, labels, milestones).

      -

      Jamie: Let's pause on Track 1: GitHub Skills Modules (Optional Self-Paced Practice). What should a learner take away from it?

      -

      Alex: The reason Track 1: GitHub Skills Modules (Optional Self-Paced Practice) matters is that 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.

      -

      Alex: The practical takeaway is this. Introduction to GitHub - Create branch, open PR, merge. Communicate Using Markdown - Write headings, links, code, tables. Review Pull Requests - Comment, approve, suggest changes.

      -

      Alex: Keep the teaching thread moving. Start with Track 2: Your Learning Room Repository (Required Workshop Track). There is something to understand, something to try, and something that proves the try worked.

      -

      Alex: The practical takeaway is this. 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).

      -

      Jamie: How should someone choose between those options?

      -

      Alex: Start with How the Two Tracks Compare. There is something to understand, something to try, and something that proves the try worked.

      -

      Alex: Use the comparison to make a decision, not to recite a table. The main contrasts are: GitHub Skills (optional) means Your Learning Room (required). Create a branch in a Skills repo means Create a branch in your Learning Room. Open a PR means Open a PR.

      +

      Jamie: Let's pause on Submitting the PR. What should a learner take away from it?

      +

      Alex: Start with Submitting the PR: VS Code creates the PR on GitHub and shows a success message. The next useful detail is this: The PR link appears in the notification - click it to open the PR on GitHub, or open it in the GitHub Pull Requests panel.

      +

      Alex: First, review all fields. Then, tab to "Create" button. After that, press Enter. Finally, navigate to the repository on GitHub. Think of it as a rail line: each stop confirms you are still on the right route before the next one.

      +

      Jamie: Before we leave Submitting the PR, what is the practical point?

      +

      Alex: First, if you recently pushed, a yellow banner "Compare & pull request" appears - click it. Then, otherwise: click Pull requests tab, then New pull request, then select your branch. After that, fill in the title and description. Finally, click Create pull request. Treat it like a recipe: do not add the next ingredient until the previous one is actually in the bowl.

      +

      Alex: Treat examples as spoken recipes, not decorations. You may hear something like 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. Read the command, understand what it changes, then run it only when the repository state matches the lesson.

      +

      Alex: Keep the teaching thread moving. Start with Learning Cards: Creating a Pull Request. There is something to understand, something to try, and something that proves the try worked.

      +

      Alex: The practical takeaway is this. 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. 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.

      +

      Jamie: Let's pause on 6. Pull Request Description Templates. What should a learner take away from it?

      +

      Alex: This is where 6. Pull Request Description Templates becomes real: many repositories include a PR template - a Markdown file that pre-fills the PR description with a checklist or structure.

      -

      Alex: Keep the teaching thread moving. Start with Learning Cards: Two Tracks, One Account. There is something to understand, something to try, and something that proves the try worked.

      -

      Alex: The practical takeaway is this. 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. 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.

      -

      Jamie: Let's pause on Your Learning Room Folder Structure. What should a learner take away from it?

      -

      Alex: Keep the learner anchored in 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.

      -

      Alex: The practical takeaway is this. 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.

      -

      Alex: Keep the teaching thread moving. The reason Your Practice Branch matters is that in your own Learning Room repository, you decide what branches to create. That gives the learner a simple foothold: the Day 1 challenge sequence asks you to work on a single feature branch named after yourself.

      -

      Alex: The practical takeaway is this. 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.

      +

      Alex: Keep the teaching thread moving. Keep the learner anchored in Where Templates Are Stored. When you create a PR in VS Code, the extension automatically loads the template into the description field. A good GitHub workflow is like a well-run meeting: everyone knows the topic, the next action, and who has the floor.

      +

      Alex: The practical takeaway is this.github/pull request template.md (root).github/PULL REQUEST TEMPLATE.md.github/PULL REQUEST TEMPLATE/ (folder with multiple templates). docs/pull request template.md.

      +

      Jamie: Let's pause on Example PR Template. What should a learner take away from it?

      +

      Alex: Start with Example PR Template. There is something to understand, something to try, and something that proves the try worked.

      +

      Alex: Treat examples as spoken recipes, not decorations. You may hear something like 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,. Read the command, understand what it changes, then run it only when the repository state matches the lesson.

      +

      Jamie: Let's pause on Screen reader workflow. What should a learner take away from it?

      +

      Alex: Start with Screen reader workflow: Keyboard tip: Use Ctrl+F (Mac: Cmd+F) to jump to each <!-- placeholder, fill it in, then F3 to jump to the next one.

      +

      Alex: First, create PR (Method 1-3 from Section 5). Then, the description field is pre-filled with the template. After that, navigate through the template with Arrow keys. Finally, replace each `` with your content. Think of it as a rail line: each stop confirms you are still on the right route before the next one.

      +

      Jamie: Before we leave Screen reader workflow, what is the practical point?

      +

      Alex: First, check checkboxes by typing x between the brackets: - [x]. Treat it like a recipe: do not add the next ingredient until the previous one is actually in the bowl.

      -

      Jamie: Let's pause on Why you create a separate branch. What should a learner take away from it?

      -

      Alex: Start with Why you create a separate branch. There is something to understand, something to try, and something that proves the try worked.

      -

      Alex: The practical takeaway is this. 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.

      -

      Jamie: Let's pause on How to use your branch. What should a learner take away from it?

      -

      Alex: Here is the plain-English version of How to use your branch. The Day 1 challenges (4 onward) walk you through creating and using your branch on GitHub.com. Put another way, once you start working locally in Chapter 14, the same branch is what you check out. It is like learning a transit route. The names of the stops matter because they tell you whether you are still going the right direction.

      -

      Alex: First, create the branch on GitHub.com (Challenge 4) or locally with git checkout -b learn/ from main. Then, make your changes and commit them to the branch. After that, push the branch to GitHub if you created it locally. Finally, open a pull request from learn/ - main (Challenge 6). Treat it like a recipe: do not add the next ingredient until the previous one is actually in the bowl.

      -

      Alex: Treat examples as spoken recipes, not decorations. You may hear something like git checkout learn/. Read the command, understand what it changes, then run it only when the repository state matches the lesson.

      -

      Jamie: Let's pause on Learning Cards: Your Practice Branch. What should a learner take away from it?

      -

      Alex: Start with Learning Cards: Your Practice Branch. There is something to understand, something to try, and something that proves the try worked.

      -

      Alex: The practical takeaway is this. 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. 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.

      +

      Jamie: Let's pause on 7. Commenting and Requesting Changes. What should a learner take away from it?

      +

      Alex: Start with 7. Commenting and Requesting Changes. There is something to understand, something to try, and something that proves the try worked.

      +

      Alex: The practical takeaway is this. Leave inline comments on specific lines. Request changes before the PR can be merged. Approve the PR. Submit general feedback.

      +

      Jamie: Let's pause on Adding an Inline Comment. What should a learner take away from it?

      +

      Alex: Start with Adding an Inline Comment. There is something to understand, something to try, and something that proves the try worked.

      +

      Alex: First, open a file from the PR's "Files Changed" list. Then, navigate to the line you want to comment on. After that, press Shift+F10 (Mac: Ctrl+Return) to open context menu. Finally, select "Add Comment". It is a checklist, but a meaningful one: every item creates evidence that the next step is safe.

      +

      Jamie: Before we leave Adding an Inline Comment, what is the practical point?

      +

      Alex: First, type your comment. Then, choose "Add Single Comment" (posts immediately) or "Start Review" (saves as a draft). It is like walking a hallway with named doors: read the sign, enter the right room, then confirm where you landed.

      +

      Jamie: Let's pause on Comment format tips. What should a learner take away from it?

      +

      Alex: Start with Comment format tips. There is something to understand, something to try, and something that proves the try worked.

      +

      Alex: The practical takeaway is this. Be specific: "This heading should be H3, not H2". Provide context: "Screen readers announce this as 'list with 1 item' - should be a paragraph instead". Suggest a fix: "Consider rewording to: 'Click the button to save'".

      -

      Jamie: Let's pause on Tool Cards: Switch to Your Practice Branch. What should a learner take away from it?

      -

      Alex: Start with Tool Cards: Switch to Your Practice Branch. There is something to understand, something to try, and something that proves the try worked.

      -

      Alex: First, on the repository page, click the branch selector dropdown (shows "main"). Then, type learn to filter, then select learn/. After that, click the branch name in the bottom-left status bar. Finally, select your learn/ branch from the list. It is like walking a hallway with named doors: read the sign, enter the right room, then confirm where you landed.

      -

      Jamie: Before we leave Tool Cards: Switch to Your Practice Branch, what is the practical point?

      -

      Alex: First, click the branch name in the bottom-left status bar (or press Ctrl+Shift+P then type Git: Checkout to ). Then, select origin/learn/ from the branch list. After that, click the Current Branch dropdown at the top. The rhythm is simple: orient, act, verify, then continue.

      -

      Jamie: Let's pause on The Practice Files: What You Will Work On. What should a learner take away from it?

      -

      Alex: The reason The Practice Files: What You Will Work On matters is that see also: Appendix C: Markdown Reference covers all Markdown syntax with accessible examples -- you will need it for editing these files. That gives the learner a simple foothold: the docs/ folder contains three practice files with intentional issues.

      -

      Alex: Keep the teaching thread moving. Start with docs/welcome.md - Introduction to Open Source Contribution: This file introduces newcomers to open source. The next useful detail is this: It has three [TODO] sections where content is missing. Think of it like entering a new building: first you find the lobby, then the room, then the door you actually need.

      +

      Jamie: Let's pause on If you have multiple comments to make, use "Start Review". What should a learner take away from it?

      +

      Alex: Start with If you have multiple comments to make, use "Start Review". There is something to understand, something to try, and something that proves the try worked.

      +

      Alex: First, add your first inline comment → select "Start Review". Then, continue adding comments to other lines. After that, all comments are saved as drafts (not visible to others yet). The rhythm is simple: orient, act, verify, then continue.

      +

      Jamie: Let's pause on Submitting Your Review. What should a learner take away from it?

      +

      Alex: Start with Submitting Your Review: The review type selector is a radio button group. The next useful detail is this: Use Arrow keys to choose, Enter to confirm.

      +

      Alex: The practical takeaway is this. Comment - general feedback, no approval decision. Approve - PR looks good, ready to merge. Request Changes - issues must be fixed before merging.

      +

      Alex: First, ctrl+Shift+P (Mac: Cmd+Shift+P). Then, type "GitHub Pull Requests: Submit Review". After that, select "GitHub Pull Requests: Finish Review". Finally, choose review type. Think of it as a rail line: each stop confirms you are still on the right route before the next one.

      +

      Jamie: Before we leave Submitting Your Review, what is the practical point?

      +

      Alex: First, optionally add a summary comment. Then, press Enter to submit. Treat it like a recipe: do not add the next ingredient until the previous one is actually in the bowl.

      +

      Jamie: Let's pause on What Happens After Submission. What should a learner take away from it?

      +

      Alex: Here is the plain-English version of What Happens After Submission. Web alternative (github.com) - reviewing. Put another way, see Accessible Code Review for detailed screen reader steps. It is like learning a transit route. The names of the stops matter because they tell you whether you are still going the right direction.

      +

      Alex: The practical takeaway is this. All your draft comments post to GitHub. The PR author receives a notification. Your review status appears on the PR (Approved / Changes Requested / Commented). If you requested changes, the PR cannot merge until you approve it.

      +

      Alex: First, open the PR and click the Files changed tab. Then, read through each file's diff. After that, click the blue + button on any line to add an inline comment. Finally, choose Start a review to batch comments. Treat it like a recipe: do not add the next ingredient until the previous one is actually in the bowl.

      +

      Jamie: Before we leave What Happens After Submission, what is the practical point?

      +

      Alex: First, click Review changes (top right) to select Comment / Approve / Request changes. Then, click Submit review. It is a checklist, but a meaningful one: every item creates evidence that the next step is safe.

      +

      Alex: Treat examples as spoken recipes, not decorations. You may hear something like View the PR diff in your terminal; gh pr diff 42; Approve; gh pr review 42 --approve --body "Looks good."; Request changes; gh pr review 42 --request-changes --body "Heading hierarchy needs fixing."; Comment-only (no verdict); gh pr review 42 --comment --body. Read the command, understand what it changes, then run it only when the repository state matches the lesson.

      -

      Jamie: Let's pause on [TODO] 1 - "Who Can Contribute?" section. What should a learner take away from it?

      -

      Alex: Here is the plain-English version of [TODO] 1 - "Who Can Contribute?" section. [TODO: Add a paragraph explaining that contributors come from all backgrounds, skill levels, and countries. Put another way, emphasize that using assistive technology is not a barrier to contribution - in fact, AT users bring a perspective that improves projects for everyone.].

      -

      Alex: Keep the teaching thread moving. This is where [TODO] 2 - "Finding Something to Work On" section becomes real: [TODO: Add two or three sentences about how to read an issue to decide if it is right for you. That matters in practice: What questions should you ask yourself?

      -

      Jamie: Let's pause on [TODO] 3 - "After Your Contribution Is Merged" section. What should a learner take away from it?

      -

      Alex: Keep the learner anchored in [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.]. This is the part to say slowly: It also has a broken internal link that needs to be found and fixed.

      -
      -

      Alex: Keep the teaching thread moving. The reason docs/keyboard-shortcuts.md - Screen Reader Shortcut Reference matters is that this is a comprehensive reference with tables for NVDA, JAWS, and VoiceOver shortcuts. That gives the learner a simple foothold: it contains intentional errors in some shortcut references that students need to find and fix. The interface gets friendlier when it stops being a wall of controls and starts being a set of named places.

      -

      Alex: The practical takeaway is this. 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.

      -

      Jamie: What is the pre-flight check here?

      -

      Alex: Start with 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. The next useful detail is this: It contains broken links that point to incorrect URLs and incomplete steps.

      -

      Alex: The practical takeaway is this. 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.

      -

      Alex: Keep the teaching thread moving. Here is the plain-English version of docs/CHALLENGES.md - Your Challenge Menu. This file lists all 21 challenges organized by progression level. Put another way, each challenge lists the file(s) to edit, estimated time, skills practiced, and success criteria.

      -
      -

      Jamie: How do these exercises create confidence instead of pressure?

      -

      Alex: This is where Bonus Challenges becomes real: five bonus challenges (A through E) are available for students who finish faster. That matters in practice: These include an accessibility audit, mentoring a peer, cross-repository contribution, creating a custom workflow, and documentation improvement.

      -

      Jamie: Let's pause on Student A (working on Challenge 3: Complete Welcome Guide). What should a learner take away from it?

      -

      Alex: Keep the learner anchored in Student A (working on Challenge 3: Complete Welcome Guide). Visibility: The PR immediately appears in the repo's Pull Requests tab. A good GitHub workflow is like a well-run meeting: everyone knows the topic, the next action, and who has the floor.

      -

      Alex: First, finds their assigned issue (Issues tab → filter Assignee:@me). Then, opens docs/welcome.md and edits the three [TODO] sections. After that, commits to a new branch: fix/studentA-issue12. Finally, opens a pull request with description. It is like walking a hallway with named doors: read the sign, enter the right room, then confirm where you landed.

      -

      Jamie: Before we leave Student A (working on Challenge 3: Complete Welcome Guide), what is the practical point?

      -

      Alex: First, submits the PR. The rhythm is simple: orient, act, verify, then continue.

      -

      Jamie: Let's pause on Bot (.github/workflows/learning-room-pr-bot.yml). What should a learner take away from it?

      -

      Alex: The reason Bot (.github/workflows/learning-room-pr-bot.yml) matters is that visibility: The bot comment appears in your PR. That gives the learner a simple foothold: you see it; the facilitators see it; nobody else does unless they have been added as a collaborator on your repo.

      -

      Alex: The practical takeaway is this. Runs within 30 seconds. 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).

      +

      Jamie: Let's pause on Learning Cards: Commenting and Requesting Changes. What should a learner take away from it?

      +

      Alex: Start with Learning Cards: Commenting and Requesting Changes. There is something to understand, something to try, and something that proves the try worked.

      +

      Alex: The practical takeaway is this. In a diff view, navigate to a line and press Shift+F10 for the context menu, then select "Add Comment" to leave inline feedback. Choose "Start Review" instead of "Single Comment" to batch multiple comments before submitting them all at once. When submitting a review, use Ctrl+Shift+P then "GitHub Pull Requests: Submit Review" and choose Approve, Request Changes, or Comment. Inline comments appear as expandable banners within the diff view -- look for the text input box that opens below the target line. The review submission dialog has radio buttons for Approve, Request Changes, and Comment with clear labels. Increase diff view font size with Ctrl+= so line numbers and change annotations are easier to read.

      +

      Alex: Keep the teaching thread moving. Keep the learner anchored in 8. Merging Pull Requests. Who can merge: Repository maintainers, or contributors with write access.

      +

      Jamie: Let's pause on Prerequisites for Merging. What should a learner take away from it?

      +

      Alex: The reason Prerequisites for Merging matters is that changing the base branch: If the PR was opened against the wrong base branch, you can change it from the PR detail view in VS Code. That gives the learner a simple foothold: scroll to the base branch field in the PR detail view and activate the dropdown to select a different target branch.

      +

      Alex: First, all required reviews are approved. Then, all CI checks pass (green checkmarks). After that, no merge conflicts exist. Finally, branch is up to date with base branch (main). The rhythm is simple: orient, act, verify, then continue.

      -

      Jamie: Let's pause on Step 3: Peer Review (Facilitator-Arranged). What should a learner take away from it?

      -

      Alex: Start with 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. The next useful detail is this: 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.

      -

      Alex: First, the facilitators (Jeff and Michael) pair you with another participant. Then, they add each of you as a collaborator on the other's Learning Room repo. After that, each of you receives a notification: "You have been added as a collaborator.". Finally, you can now read the other person's PRs, leave comments, request changes, and approve. Think of it as a rail line: each stop confirms you are still on the right route before the next one.

      -

      Jamie: Before we leave Step 3: Peer Review (Facilitator-Arranged), what is the practical point?

      -

      Alex: First, 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. Treat it like a recipe: do not add the next ingredient until the previous one is actually in the bowl.

      -

      Jamie: Let's pause on Visibility. What should a learner take away from it?

      -

      Alex: Start with Visibility. There is something to understand, something to try, and something that proves the try worked.

      -

      Alex: The practical takeaway is this. 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.

      -

      Jamie: Let's pause on Your assigned peer reviewer (when one is paired with you). What should a learner take away from it?

      -

      Alex: Start with Your assigned peer reviewer (when one is paired with you). There is something to understand, something to try, and something that proves the try worked.

      -

      Alex: The practical takeaway is this. 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. 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.".

      -

      Alex: First, receives notification: "PR review requested". Then, navigates to the PR in your Learning Room repo (they have collaborator access). After that, leaves review comments. Finally, submits review: Approve (or Request Changes if a [TODO] marker was missed). It is a checklist, but a meaningful one: every item creates evidence that the next step is safe.

      +

      Jamie: Let's pause on Method 1: PR Detail View. What should a learner take away from it?

      +

      Alex: Start with Method 1: PR Detail View. There is something to understand, something to try, and something that proves the try worked.

      +

      Alex: First, open the PR in VS Code. Then, scroll to the bottom of the PR detail view. After that, find "Merge Pull Request" button. Finally, press Enter. Think of it as a rail line: each stop confirms you are still on the right route before the next one.

      +

      Jamie: Before we leave Method 1: PR Detail View, what is the practical point?

      +

      Alex: First, choose merge type (see below). Treat it like a recipe: do not add the next ingredient until the previous one is actually in the bowl.

      +

      Jamie: If someone only remembers one thing from Method 2: Command Palette, what should it be?

      +

      Alex: First, ctrl+Shift+P (Mac: Cmd+Shift+P). Then, type "GitHub Pull Requests: Merge". After that, select "GitHub Pull Requests: Merge Pull Request". Finally, choose the PR from the list. Treat it like a recipe: do not add the next ingredient until the previous one is actually in the bowl.

      +

      Alex: First, select merge type. It is a checklist, but a meaningful one: every item creates evidence that the next step is safe.

      +

      Alex: Keep the teaching thread moving. This is where Merge Types becomes real: the merge type selector is a dropdown or radio group. That matters in practice: Navigate with Arrow keys, confirm with Enter.

      -

      Jamie: Before we leave Visibility, what is the practical point?

      -

      Alex: The practical takeaway is this. 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.

      -

      Jamie: Let's pause on You (PR author). What should a learner take away from it?

      -

      Alex: Start with You (PR author). There is something to understand, something to try, and something that proves the try worked.

      -

      Alex: First, read Aria's feedback and any human review. Then, talks to the reviewer if something is unclear. After that, makes changes based on feedback. Finally, pushes new commits to the same branch. The rhythm is simple: orient, act, verify, then continue.

      -

      Jamie: Before we leave You (PR author), what is the practical point?

      -

      Alex: First, re-addresses the feedback. Think of it as a rail line: each stop confirms you are still on the right route before the next one.

      -

      Jamie: What is the teaching move inside Visibility?

      -

      Alex: The practical takeaway is this. 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.

      +

      Jamie: Let's pause on Which merge type to use. What should a learner take away from it?

      +

      Alex: Start with Which merge type to use. There is something to understand, something to try, and something that proves the try worked.

      +

      Alex: The practical takeaway is this. Check the repository's CONTRIBUTING.md for guidance. If unsure, use Merge Commit (the default and safest option).

      +

      Jamie: Let's pause on After Merging. What should a learner take away from it?

      +

      Alex: Start with After Merging. There is something to understand, something to try, and something that proves the try worked.

      +

      Alex: First, the PR closes automatically. Then, the feature branch can be deleted (VS Code prompts: "Delete branch?"). After that, recommended: switch back to main and pull the merged changes. The rhythm is simple: orient, act, verify, then continue.

      +

      Jamie: Let's pause on Switching to main and pulling. What should a learner take away from it?

      +

      Alex: Start with Switching to main and pulling: (Mac users: use Cmd+Shift+P instead of Ctrl+Shift+P).

      +

      Alex: Treat examples as spoken recipes, not decorations. You may hear something like Ctrl+Shift+P → "Git: Checkout to." → select "main"; Ctrl+Shift+P → "Git: Pull". Read the command, understand what it changes, then run it only when the repository state matches the lesson.

      -

      Alex: Keep the teaching thread moving. Start with When the review is approved (or you decide to self-merge). There is something to understand, something to try, and something that proves the try worked.

      -

      Alex: The practical takeaway is this. You merge the PR (button becomes available). PR closes, shows "merged".

      -

      Jamie: What should the learner prove to themselves after each small task?

      -

      Alex: Start with Progression Bot Posts the Next Challenge. There is something to understand, something to try, and something that proves the try worked.

      -

      Alex: The practical takeaway is this. 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.

      -

      Alex: Keep the teaching thread moving. Start with Visibility. There is something to understand, something to try, and something that proves the try worked.

      -

      Alex: The practical takeaway is this. 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.

      +

      Jamie: Let's pause on Deleting the Feature Branch. What should a learner take away from it?

      +

      Alex: Here is the plain-English version of Deleting the Feature Branch. After merging, the feature branch is no longer needed. Put another way, web alternative (github.com) - merging.

      +

      Alex: First, ctrl+Shift+P (Mac: Cmd+Shift+P). Then, type "git delete branch". After that, select "Git: Delete Branch.". Finally, choose the merged branch. Treat it like a recipe: do not add the next ingredient until the previous one is actually in the bowl.

      +

      Jamie: Before we leave Deleting the Feature Branch, what is the practical point?

      +

      Alex: First, open the PR's Conversation tab. Then, scroll to the merge button at the bottom. After that, click the dropdown arrow to choose a merge strategy (Squash, Rebase, or Merge commit). Finally, click Merge pull request, then Confirm merge. It is a checklist, but a meaningful one: every item creates evidence that the next step is safe.

      +

      Alex: Treat examples as spoken recipes, not decorations. You may hear something like Merge with default strategy; gh pr merge 42; Squash and merge, then delete the branch; gh pr merge 42 --squash --delete-branch; Enable auto-merge (merges when checks pass); gh pr merge 42 --auto --squash. Read the command, understand what it changes, then run it only when the repository state matches the lesson.

      +

      Jamie: Let's pause on Learning Cards: Merging Pull Requests. What should a learner take away from it?

      +

      Alex: Start with Learning Cards: Merging Pull Requests. There is something to understand, something to try, and something that proves the try worked.

      +

      Alex: The practical takeaway is this. The merge type selector (Merge Commit, Squash, Rebase) is announced as a dropdown or radio group -- use Arrow keys to move between options and Enter to confirm; if unsure, choose Merge Commit (the default and safest option). After merging, VS Code prompts "Delete branch?" as a notification -- press Alt+N to focus the notification and Enter to confirm, then run Ctrl+Shift+P then "Git: Checkout to" and select main to return to your default branch. Confirm the merge succeeded by pressing F6 to reach the Status Bar and verifying it now reads main instead of the feature branch name. The merge button at the bottom of the PR detail view includes a dropdown arrow for selecting merge type -- at high zoom, widen the editor pane so the button label and dropdown are not truncated. After merging, the PR detail view header changes from "Open" (green badge) to "Merged" (purple badge) -- verify this colour/label change before deleting the branch. When switching back to main, the branch name in the bottom-left Status Bar updates immediately -- confirm it reads main before pulling new changes with Ctrl+Shift+P then "Git: Pull".

      +

      Alex: Keep the teaching thread moving. Keep the learner anchored in "No pull requests found". Issue: The GitHub Pull Requests panel is empty. A good GitHub workflow is like a well-run meeting: everyone knows the topic, the next action, and who has the floor.

      -

      Jamie: Let's pause on Learning Cards: How PR Sharing Works. What should a learner take away from it?

      -

      Alex: Start with Learning Cards: How PR Sharing Works. There is something to understand, something to try, and something that proves the try worked.

      -

      Alex: The practical takeaway is this. 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. 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.

      -

      Alex: Keep the teaching thread moving. Start with The Learning Automation System: When you open a PR in the Learning Room, you get three types of feedback. Think of it like entering a new building: first you find the lobby, then the room, then the door you actually need.

      -

      Jamie: Let's pause on Type 1: Automated Bot Feedback (30 seconds). What should a learner take away from it?

      -

      Alex: Start with Type 1: Automated Bot Feedback (30 seconds). There is something to understand, something to try, and something that proves the try worked.

      -

      Alex: The practical takeaway is this. 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.

      +

      Jamie: Let's pause on Solutions. What should a learner take away from it?

      +

      Alex: Start with Solutions. There is something to understand, something to try, and something that proves the try worked.

      +

      Alex: First, verify you're signed in: Ctrl+Shift+P (Mac: Cmd+Shift+P) → "GitHub Pull Requests: Sign in". Then, check you have a folder open containing a Git repository. After that, refresh the panel: Ctrl+Shift+P (Mac: Cmd+Shift+P) → "GitHub Pull Requests: Refresh Pull Requests List". The rhythm is simple: orient, act, verify, then continue.

      +

      Jamie: Before we leave Solutions, what is the practical point?

      +

      Alex: First, verify you've pushed your branch: Ctrl+Shift+P (Mac: Cmd+Shift+P) → "Git: Push". Then, check you have write access to the repository. After that, ensure your branch is ahead of the base branch (has new commits). Think of it as a rail line: each stop confirms you are still on the right route before the next one.

      +

      Jamie: Let's pause on "Authentication failed". What should a learner take away from it?

      +

      Alex: Here is the plain-English version of "Authentication failed". Issue: VS Code can't connect to GitHub.

      -

      Alex: Keep the teaching thread moving. Start with Type 2: Peer Reviewer Feedback (15-60 minutes). There is something to understand, something to try, and something that proves the try worked.

      -

      Alex: The practical takeaway is this. Human judgment on content. Creative suggestions. Encouragement and mentorship. Understanding of context. Can approve, request changes, or comment.

      -

      Jamie: Let's pause on Type 3: Progress Tracking (on merge). What should a learner take away from it?

      -

      Alex: Keep the learner anchored in Type 3: Progress Tracking (on merge). Together: Instant technical feedback + human mentorship + visible progress.

      -

      Alex: The practical takeaway is this. Skill badges (Markdown Master, Accessibility Advocate). Level progression (Beginner → Intermediate → Advanced → Expert). Milestone celebrations (1st, 5th, 10th PR). Motivational comments.

      -

      Jamie: Let's pause on Study Groups (Optional). What should a learner take away from it?

      -

      Alex: The reason Study Groups (Optional) matters is that 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. The interface gets friendlier when it stops being a wall of controls and starts being a set of named places.

      -

      Alex: First, group Issue Thread - Private communication space for your group. Then, shared Review Responsibility - You review each other's work. After that, collaborative Challenges - Optional group exercises. Finally, peer Support - Tag each other with questions. The rhythm is simple: orient, act, verify, then continue.

      +

      Jamie: What is the teaching move inside Solutions?

      +

      Alex: First, sign out and sign back in: Ctrl+Shift+P (Mac: Cmd+Shift+P) → "GitHub Pull Requests: Sign out" → then sign in again. Then, check your GitHub Personal Access Token (see Appendix D: Git Authentication). After that, verify network connection. It is a checklist, but a meaningful one: every item creates evidence that the next step is safe.

      +

      Jamie: Let's pause on Try It: Review a PR from VS Code. What should a learner take away from it?

      +

      Alex: Keep the learner anchored in Try It: Review a PR from VS Code. Time: 3 minutes What you need: VS Code with GitHub Pull Requests extension installed and signed in. This is the part to say slowly: You just reviewed a pull request entirely from VS Code.

      +

      Alex: First, open the PR view - Press Ctrl+Shift+P → type Pull Requests: Focus on GitHub Pull Requests View → Enter. Then, find a PR - Navigate the tree with arrow keys. Expand a PR to see its changed files. After that, open a diff - Press Enter on a changed file. The diff editor opens. Finally, use the Accessible Diff Viewer - Press F7 to jump to the first change. Your screen reader announces what was added or removed. Press F7 again to move to the next change. It is like walking a hallway with named doors: read the sign, enter the right room, then confirm where you landed.

      +

      Jamie: Before we leave Try It: Review a PR from VS Code, what is the practical point?

      +

      Alex: First, leave a comment - Position your cursor on a line you want to comment on, then press Ctrl+Shift+P → Pull Request: Add Comment on Current Diff Line. Type a brief, constructive comment and submit. The rhythm is simple: orient, act, verify, then continue.

      +

      Alex: Keep the teaching thread moving. The reason Conducting Pull Request Reviews with a Screen Reader matters is that this guide is focused entirely on the reviewer experience - navigating diffs, reading changes, leaving comments, and submitting a review - using only your keyboard and screen reader. That gives the learner a simple foothold: for the full pull request lifecycle (opening PRs, merge options, conflict resolution), see Working with Pull Requests.

      -

      Jamie: Can you translate that into plain choices?

      -

      Alex: Start with Key Differences: Skills Module vs. Your Learning Room. There is something to understand, something to try, and something that proves the try worked.

      -

      Alex: Use the comparison to make a decision, not to recite a table. The main contrasts are: GitHub Skills (Your Account) means Your Learning Room (Classroom). Your personal copy of a Skills repo means Your private copy of learning-room-template. Mona (GitHub) means Aria (PR validation) and the Student Progression bot.

      -

      Alex: Keep the teaching thread moving. Here is the plain-English version of 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. Put another way, here is how to find the PRs they want you to look at.

      -

      Jamie: Let's pause on Finding PRs to Review. What should a learner take away from it?

      -

      Alex: This is where Finding PRs to Review becomes real: screen reader users (VoiceOver - macOS).

      -

      Alex: First, go to your peer's Learning Room repo (the URL the facilitators sent you, or open it from your GitHub Notifications inbox). Then, click the Pull Requests tab. After that, click the Filters dropdown - "Review requested" - your username. Finally, click any PR title to open it. It is a checklist, but a meaningful one: every item creates evidence that the next step is safe.

      -

      Alex: Treat examples as spoken recipes, not decorations. You may hear something like 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. 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. Read the command, understand what it changes, then run it only when the repository state matches the lesson.

      +

      Jamie: Zoom out for a second. What kind of journey is this?

      +

      Alex: Start with Workshop Recommendation (Chapter 15 / Challenge 12): Chapter 15 is the code review chapter focused on practicing constructive feedback. The next useful detail is this: It supports Challenge 12: Review Like a Pro.

      +

      Alex: The practical takeaway is this. There are 2 guided challenges. Automation check: none (review quality is subjective and human-focused). The evidence is issue comment with summary of review and feedback posted. The pattern is navigate diff, comment on specifics, submit verdict.

      +

      Jamie: Let's pause on Challenge 12 Practice Set. What should a learner take away from it?

      +

      Alex: Start with Challenge 12 Practice Set. There is something to understand, something to try, and something that proves the try worked.

      +

      Alex: First, review a practice PR and leave 2-3 inline comments - read the diff line by line, find specific items to comment on, and post constructive feedback. Then, submit a formal review verdict - complete your review by choosing approve, request changes, or comment only. Treat it like a recipe: do not add the next ingredient until the previous one is actually in the bowl.

      +

      Jamie: Let's pause on Practice 12.1 Step-by-Step: Review a PR and Leave Inline Comments. What should a learner take away from it?

      +

      Alex: This is where Practice 12.1 Step-by-Step: Review a PR and Leave Inline Comments becomes real: navigate a PR diff using screen reader-friendly tools and post 2-3 specific, constructive inline comments. That matters in practice: GitHub.com (Files changed tab of a PR) or VS Code with the GitHub Pull Requests extension.

      +

      Alex: The practical takeaway is this. On GitHub.com: Use heading navigation to jump between files (H in NVDA). Each file header is a heading. Within a file, use arrow keys to move line by line. In VS Code: Press F7 to open the Accessible Diff Viewer (see Chapter 15, Part 1). Use F7/Shift+F7 to move between changes. Typos or grammar issues. Unclear headings or link text.

      +

      Alex: First, open your Learning Room repository on GitHub.com and navigate to the Pull requests tab. Then, find a classmate's open PR (from Chapter 6, 7, or 14). Open it. After that, activate the Files changed tab. This shows the diff - lines added in green, lines removed in red. Finally, navigate the diff. It is a checklist, but a meaningful one: every item creates evidence that the next step is safe.

      +

      Jamie: Before we leave Practice 12.1 Step-by-Step: Review a PR and Leave Inline Comments, what is the practical point?

      +

      Alex: First, read through the changes carefully. Look. Then, to leave an inline comment on GitHub.com: activate the + button that appears to the left of a line number when you hover or Tab to it. (Screen reader users: this button may be announced as "Add a comment to this line.") Type your comment in the text box that. After that, post 2-3 inline comments. Each comment should be. Finally, examples of good inline comments. It is like walking a hallway with named doors: read the sign, enter the right room, then confirm where you landed.

      -

      Alex: Keep the teaching thread moving. Keep the learner anchored in Reading a PR You're Assigned To. Screen reader users (VoiceOver - macOS). A good GitHub workflow is like a well-run meeting: everyone knows the topic, the next action, and who has the floor.

      -

      Alex: The practical takeaway is this. 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.

      -

      Jamie: Let's pause on Leaving a Review. What should a learner take away from it?

      -

      Alex: The reason Leaving a Review matters is that screen reader users (VoiceOver - macOS).

      -

      Alex: First, scroll to the comment box on the Conversation tab. Then, type your review comment. After that, click "Review Changes" (top-right of the Files Changed tab, or at the bottom of the PR page). Finally, select your review type: Comment / Approve / Request changes. The rhythm is simple: orient, act, verify, then continue.

      -

      Jamie: Before we leave Leaving a Review, what is the practical point?

      -

      Alex: First, click "Submit review". Think of it as a rail line: each stop confirms you are still on the right route before the next one.

      -

      Alex: Treat examples as spoken recipes, not decorations. You may hear something like 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". Read the command, understand what it changes, then run it only when the repository state matches the lesson.

      -

      Jamie: Let's pause on Responding to Feedback. What should a learner take away from it?

      -

      Alex: Start with Responding to Feedback: Screen reader users (VoiceOver - macOS).

      -

      Alex: First, open your PR (Pull Requests tab → click your PR). Then, read all comments and bot feedback. After that, click in the comment box to reply. Finally, push your fixes to the same branch. Think of it as a rail line: each stop confirms you are still on the right route before the next one.

      -

      Jamie: Before we leave Responding to Feedback, what is the practical point?

      -

      Alex: First, comment: "Updates pushed, ready for review". Treat it like a recipe: do not add the next ingredient until the previous one is actually in the bowl.

      -

      Alex: Treat examples as spoken recipes, not decorations. You may hear something like 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". Read the command, understand what it changes, then run it only when the repository state matches the lesson.

      +

      Jamie: Let's pause on Practice 12.2 Step-by-Step: Submit a Formal Review Verdict. What should a learner take away from it?

      +

      Alex: Keep the learner anchored in Practice 12.2 Step-by-Step: Submit a Formal Review Verdict. Complete your review by selecting a verdict that tells the author what action to take next. This is the part to say slowly: GitHub.com (the same PR you reviewed in 14.1).

      +

      Alex: The practical takeaway is this. Comment - general feedback, no explicit approval or rejection. Approve - you think the PR is ready to merge. Request changes - you found something that should be fixed before merging. If the PR has clear documentation with only minor suggestions, choose Approve.

      +

      Alex: First, after posting your inline comments, scroll to the top of the Files changed tab. Then, activate the Review changes button (at the top-right of the files changed area, or use heading navigation). After that, a dropdown opens with three options. Finally, choose the verdict that matches your review. It is like walking a hallway with named doors: read the sign, enter the right room, then confirm where you landed.

      +

      Jamie: Before we leave Practice 12.2 Step-by-Step: Submit a Formal Review Verdict, what is the practical point?

      +

      Alex: First, write a brief summary in the review body (1-2 sentences). Example: "Clear improvement to the shortcut table. Two minor suggestions for link text clarity.". Then, activate Submit review. The rhythm is simple: orient, act, verify, then continue.

      +

      Jamie: Why is the evidence prompt part of the teaching, not just grading?

      +

      Alex: The reason Completing Challenge 12: Submit Your Evidence matters is that open your assigned Challenge 12 issue and post a completion comment. That gives the learner a simple foothold: close your Challenge 12 issue when done.

      +

      Alex: The practical takeaway is this. Student can navigate PR diffs with a screen reader. Student can post inline comments on specific lines of a diff. Student can write constructive, specific feedback that helps the author improve. Student can submit a formal review verdict.

      -

      Jamie: Let's pause on Learning Cards: Tips for PR Sharing. What should a learner take away from it?

      -

      Alex: Start with Learning Cards: Tips for PR Sharing. There is something to understand, something to try, and something that proves the try worked.

      -

      Alex: The practical takeaway is this. 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. 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.

      -

      Alex: Keep the teaching thread moving. This is where "Can I see other students' PRs?" becomes real: not inside their Learning Room repos -- those are private to each student. That matters in practice: You can see other participants' work in two ways. The workshop is closer to rehearsal than lecture. You hear the move, try the move, and then check what changed.

      -

      Alex: The practical takeaway is this. 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.

      -

      Jamie: Let's pause on "What if I don't agree with my assigned reviewer?". What should a learner take away from it?

      -

      Alex: Keep the learner anchored in "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. This is the part to say slowly: You can request additional reviewers manually.

      +

      Jamie: Let's pause on If You Get Stuck. What should a learner take away from it?

      +

      Alex: Here is the plain-English version of If You Get Stuck. Continue learning: The GitHub Skills courses Review Pull Requests and Code Review with GitHub Copilot cover review workflows and AI-assisted code review. Put another way, see Appendix Z for the full catalog.

      +

      Alex: First, files Changed tab will not open? Reload the PR page and retry. Make sure you are on the PR page, not the issue page. Then, cannot find the inline comment button? Tab through the line controls in the diff. The button may be announced as "Add a comment" or have a + label. If you cannot find it, use the "Review changes" button at the top to add a general comment instead. After that, not sure what to comment on? Focus on clarity: is every heading descriptive? Is every link meaningful? Are steps complete? Are keyboard shortcuts correct? Finally, review verdict button not working? Make sure you have at least one comment or have written summary text. Try reloading the page. Treat it like a recipe: do not add the next ingredient until the previous one is actually in the bowl.

      +

      Jamie: Let's pause on If You Get Stuck. What should a learner take away from it?

      +

      Alex: First, submitting the review fails? Check that you are not in draft mode and have at least read access to the repo. Then, ask facilitator to model one inline comment and one verdict submission. After that, finished but not sure you did it right? Compare your work against the Challenge 12 reference solution. It is a checklist, but a meaningful one: every item creates evidence that the next step is safe.

      +

      Alex: Keep the teaching thread moving. This is where Learning Moment becomes real: specific, kind feedback helps authors improve and builds trust in the community. That matters in practice: Every comment you write is practice for the professional code review you will do on real projects.

      +

      Jamie: If someone only remembers one thing from Learning Pattern Used in This Chapter, what should it be?

      +

      Alex: First, read the full diff before commenting (understand the author's intent first). Then, find specific items to comment on (lines, phrases, missing steps). After that, write comments that help, not just criticize (suggest improvements, note what works). Finally, choose a verdict that matches the substance of your feedback. It is like walking a hallway with named doors: read the sign, enter the right room, then confirm where you landed.

      +

      Alex: First, summarize your overall impression in 1-2 sentences. The rhythm is simple: orient, act, verify, then continue.

      -

      Alex: Keep the teaching thread moving. The reason "Will my PR get lost when everyone is working at once?" matters is that your repo is your own; you only see your own PRs. That gives the learner a simple foothold: Aria's feedback is on your PR alone, and any peer reviewer is specifically assigned to you.

      -

      Jamie: Let's pause on "Can I comment on someone else's PR?". What should a learner take away from it?

      -

      Alex: Start with "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. The next useful detail is this: On the public accessibility-agents repo, anyone can comment on any open PR.

      -

      Alex: Keep the teaching thread moving. Here is the plain-English version of "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. It is like learning a transit route. The names of the stops matter because they tell you whether you are still going the right direction.

      +

      Alex: Keep the teaching thread moving. The reason Before starting this chapter, verify you have completed matters is that estimated time for this chapter: 1 hour (including exercises). The interface gets friendlier when it stops being a wall of controls and starts being a set of named places.

      +

      Alex: The practical takeaway is this. [ ] Chapter 6: Working with Pull Requests - Understand PR structure, diffs, and comment workflows. [ ] Chapter 13: GitHub Copilot - VS Code installed and configured. [ ] Screen Reader Setup - NVDA, JAWS, or VoiceOver installed and ready to use. [ ] Access to at least one pull request to review (your own fork or a practice repo).

      +

      Jamie: Let's pause on Two Environments for Code Review. What should a learner take away from it?

      +

      Alex: Start with Two Environments for Code Review: You can review pull requests in two places - each with different strengths. The next useful detail is this: Both environments give you full keyboard and screen reader access.

      +

      Jamie: Let's pause on About Learning Cards in This Chapter. What should a learner take away from it?

      +

      Alex: Here is the plain-English version of About Learning Cards in This Chapter. Each review step includes expandable learning cards for different interaction styles. Put another way, open the one that matches how you work.

      +

      Alex: Treat examples as spoken recipes, not decorations. You may hear something like View the full PR diff in your terminal; gh pr diff 42; View PR details (description, status, checks); gh pr view 42; Checkout the PR branch locally for testing; gh pr checkout 42; Approve the PR; gh pr review 42 --approve --body "Heading hierarchy looks. Read the command, understand what it changes, then run it only when the repository state matches the lesson.

      -

      Jamie: Let's pause on "Can I work with a friend?". What should a learner take away from it?

      -

      Alex: This is where "Can I work with a friend?" becomes real: 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.

      -

      Alex: Keep the teaching thread moving. Keep the learner anchored in "How long does review take?". When pairings happen during a workshop block, typically 15-60 minutes. This is the part to say slowly: If a reviewer is slow, the facilitators can step in or assign someone else.

      -

      Jamie: Let's pause on "What if bot feedback is wrong?". What should a learner take away from it?

      -

      Alex: The reason "What if bot feedback is wrong?" matters is that Aria is intentionally educational, not punitive -- if you disagree with a check, the facilitators can override it. That gives the learner a simple foothold: Aria is not perfect, which is exactly why human review still matters.

      +

      Jamie: Let's pause on Good News: Modern Interface is Default. What should a learner take away from it?

      +

      Alex: This is where Good News: Modern Interface is Default becomes real: as of January 2026, GitHub's improved Files Changed experience is enabled by default. That matters in practice: The instructions below assume you have the modern interface (which you do).

      +

      Jamie: Let's pause on Step 1: Reach the Files Changed Tab. What should a learner take away from it?

      +

      Alex: Keep the learner anchored in Step 1: Reach the Files Changed Tab. Click the Files changed tab at the top of the PR page. This is the part to say slowly: The tab label shows the number of changed files (e.g., "Files changed 4"). A good GitHub workflow is like a well-run meeting: everyone knows the topic, the next action, and who has the floor.

      +

      Alex: First, the PR tabs (Conversation, Commits, Checks, Files changed) are across the top of the PR page. At high zoom they may wrap to multiple lines. Then, the Files changed tab includes a badge with the number of changed files. This badge uses text (not colour alone) so it is visible in all themes. After that, after clicking Files changed, the diff page loads. At high zoom, the file tree panel on the left may collapse automatically. Click the file tree toggle (a small panel icon) or press T to toggle it back. Finally, added lines use a green background; removed lines use red. In high contrast browser settings (Windows: Settings Accessibility Contrast themes), these colours map to strong border indicators. It is like walking a hallway with named doors: read the sign, enter the right room, then confirm where you landed.

      +

      Jamie: Before we leave Step 1: Reach the Files Changed Tab, what is the practical point?

      +

      Alex: First, use Ctrl++ to zoom the browser if the diff text is too small, and Ctrl+- to zoom out. The rhythm is simple: orient, act, verify, then continue.

      +

      Alex: Treat examples as spoken recipes, not decorations. You may hear something like Press D → navigate to "Pull request navigation tabs" landmark; Press → or Tab → find "Files changed" link → Enter. Read the command, understand what it changes, then run it only when the repository state matches the lesson.

      +

      Jamie: Let's pause on Step 2: Use the File Tree to Orient Yourself. What should a learner take away from it?

      +

      Alex: The reason Step 2: Use the File Tree to Orient Yourself matters is that the file tree panel lists every changed file. That gives the learner a simple foothold: before reading any diff, scan this list to understand the scope of the PR.

      -

      Alex: Keep the teaching thread moving. Start with "Do I need to complete every challenge?": The Learning Room has challenges for all skill levels. The next useful detail is this: You can pick what interests you, complete at your pace, and continue after the workshop -- your repo stays yours. Think of it like entering a new building: first you find the lobby, then the room, then the door you actually need.

      -

      Jamie: Let's pause on Celebration: You're Contributing. What should a learner take away from it?

      -

      Alex: Here is the plain-English version of Celebration: You're Contributing. Every PR you open and merge in the Learning Room is a real contribution. Put another way, you found something to improve You made a meaningful change You received feedback (technical + human) You incorporated suggestions You merged your work.

      +

      Jamie: Let's pause on What to listen for / look for. What should a learner take away from it?

      +

      Alex: Start with What to listen for / look for: Low vision users (zoom, high contrast).

      +

      Alex: The practical takeaway is this. How many files changed? Which areas of the codebase are affected? Are there unexpected files (generated files, lock files, configuration changes)?

      +

      Alex: First, the file tree shows each filename with a colour-coded bar indicating lines added (green) and removed (red). In high contrast mode, these bars may be less visible - the +N / -N text badge next to each file is the reliable indicator. Then, at high zoom, long file paths truncate. Hover over a truncated name to see the full path in a tooltip. After that, if the file tree panel is too narrow at high zoom, drag its right edge to widen it, or toggle it off and use heading navigation (H key) to move between file diffs. Think of it as a rail line: each stop confirms you are still on the right route before the next one.

      +

      Jamie: Let's pause on Step 3: Navigate Between File Diffs. What should a learner take away from it?

      +

      Alex: Here is the plain-English version of Step 3: Navigate Between File Diffs. Each changed file in the main area is an h3 heading containing the filename. Put another way, scroll through the page or click a filename in the file tree on the left.

      +

      Alex: Treat examples as spoken recipes, not decorations. You may hear something like Press 3 to jump file-by-file through the diff; Listen for: "learning-room/docs/keyboard-shortcuts.md - collapsed" or "expanded"; Press Enter or Space to expand a collapsed file. Quick Nav H or VO+Cmd+H to jump file-by-file through the diff; Listen for: "learning-room/docs/keyboard-shortcuts.md - collapsed" or "expanded"; VO+Space to expand a collapsed file. Read the command, understand what it changes, then run it only when the repository state matches the lesson.

      +

      Jamie: Let's pause on Step 4: Read a Diff. What should a learner take away from it?

      +

      Alex: This is where Step 4: Read a Diff becomes real: low vision users (zoom, high contrast). That matters in practice: Screen reader users - VoiceOver (macOS). The workshop is closer to rehearsal than lecture. You hear the move, try the move, and then check what changed.

      +

      Alex: The practical takeaway is this. Green highlighted lines (with a +) = lines added. Red highlighted lines (with a -) = lines removed. Plain/white lines = unchanged context. Use Ctrl+F to search within the page for specific text in the diff.

      +

      Alex: First, colour is not the only indicator. Every added line has a + character in the gutter; every removed line has a -. These text characters are reliable regardless of colour settings. Then, at high zoom, long lines of code wrap. The +/- gutter character stays at the beginning of the first line, so look left to determine the change type. After that, use Ctrl+F (browser find) to search for specific text across the entire diff page. Finally, if the diff is split view (side by side), it may be very wide at high zoom. Switch to unified diff mode: click the gear icon in the Files Changed toolbar and select "Unified" - this shows old and new in a single column. It is a checklist, but a meaningful one: every item creates evidence that the next step is safe.

      +

      Jamie: Before we leave Step 4: Read a Diff, what is the practical point?

      +

      Alex: First, high contrast themes in Windows (Settings Accessibility Contrast themes) make the +/- lines use bold border patterns instead of subtle colour shading. It is like walking a hallway with named doors: read the sign, enter the right room, then confirm where you landed.

      +

      Alex: Treat examples as spoken recipes, not decorations. You may hear something like Press T to jump to the diff table then Insert+Space (Focus Mode); Press Down Arrow to move through lines one at a time; Press Ctrl+Alt+Right Arrow to read across columns: line number, change type, code content. Press T to jump to the diff table then Insert+Z (Virtual PC Cursor off); Press Down Arrow to move through lines; Press Ctrl+Alt+Right Arrow for column-by-column reading. Read the command, understand what it changes, then run it only when the repository state matches the lesson.

      -

      Jamie: What is the final checkpoint?

      -

      Alex: You should be able to point to the evidence, explain the action, and describe what you would do next if this were a real open source project. If you can teach the move back, you have learned it.

      -

      Jamie: And if they get stuck?

      -

      Alex: Read the latest message, not the loudest worry. Check the issue, the branch, the pull request, the status check, or the bot comment. Then ask for help with those facts in hand. That is how professionals collaborate.

      -
      - +

      Jamie: Let's pause on What each line announces / shows. What should a learner take away from it?

      +

      Alex: Keep the learner anchored in What each line announces / shows. If the code on a line is very long, the screen reader will read the full line. This is the part to say slowly: For minified or generated files, consider collapsing the file in the tree and skipping it.

      +

      Alex: The practical takeaway is this. Added lines: "+ [code content]" - or announced as "inserted". Removed lines: "- [code content]" - or announced as "deleted". Context lines: code without a + or -.

      +

      Jamie: Let's pause on Step 5: Place an Inline Comment. What should a learner take away from it?

      +

      Alex: The reason Step 5: Place an Inline Comment matters is that when you have a specific observation about a particular line, place an inline comment directly on it. That gives the learner a simple foothold: screen reader users (VoiceOver - macOS).

      +

      Alex: First, hover your mouse over a line in the diff - a blue + (comment) button appears on the left. Then, click it to open the inline comment box. After that, type your comment. Finally, click "Start a review" (not "Add single comment" - see note below). The rhythm is simple: orient, act, verify, then continue.

      +

      Jamie: Let's pause on Placing a multi-line comment. What should a learner take away from it?

      +

      Alex: Start with Placing a multi-line comment: Click and drag across multiple line numbers in the diff gutter to select a range. The next useful detail is this: A comment button appears for the selected range.

      -

      Challenge 02: File Your First Issue

      -

      Finding a TODO, creating a clear issue, and explaining what needs to change.

      -
      -Read Transcript - Challenge 02: File Your First Issue - -

      Transcript

      -

      Alex: Welcome back to Challenge Coach. Today we are taking on File Your First Issue, one careful step at a time.

      -

      Jamie: And I am Jamie. I am listening for the confusing parts: where to start, what to submit, and how to tell whether it worked.

      +

      Jamie: Let's pause on Step 6: Read Existing Comments and Threads. What should a learner take away from it?

      +

      Alex: Here is the plain-English version of Step 6: Read Existing Comments and Threads. Inline comments from other reviewers appear as h3 headings within the diff table. Put another way, each thread shows: reviewer username, comment body, replies, a "Reply" link and resolution button. It is like learning a transit route. The names of the stops matter because they tell you whether you are still going the right direction.

      +

      Alex: Treat examples as spoken recipes, not decorations. You may hear something like Tab to the "Resolve conversation" button → Enter. Tab to the "Resolve conversation" button → VO+Space. Read the command, understand what it changes, then run it only when the repository state matches the lesson.

      +

      Jamie: Let's pause on Step 7: Submit Your Review. What should a learner take away from it?

      +

      Alex: This is where Step 7: Submit Your Review becomes real: screen reader users (VoiceOver - macOS).

      +

      Alex: First, click the "Review changes" button (top-right of the Files Changed page or bottom of the PR). Then, a dialog opens with a summary text area and three radio buttons: Comment / Approve / Request changes. After that, optionally type an overall summary in the text area. Finally, select your verdict. It is a checklist, but a meaningful one: every item creates evidence that the next step is safe.

      +

      Jamie: Before we leave Step 7: Submit Your Review, what is the practical point?

      +

      Alex: First, click "Submit review". It is like walking a hallway with named doors: read the sign, enter the right room, then confirm where you landed.

      +

      Jamie: Let's pause on Step 8: Re-request Review (for Authors). What should a learner take away from it?

      +

      Alex: Keep the learner anchored in Step 8: Re-request Review (for Authors). After you address review comments on your own PR. This is the part to say slowly: Look in the right sidebar for the Reviewers section.

      +

      Alex: Treat examples as spoken recipes, not decorations. You may hear something like Step 1: From your PR's Conversation tab, Quick Nav H or VO+Cmd+H to find the "Reviewers" heading in the sidebar; Step 2: Tab or Quick Nav B to find the re-request icon ("Re-request review") next to the reviewer's name; Step 3: VO+Space to activate - this. Read the command, understand what it changes, then run it only when the repository state matches the lesson.

      -

      Alex: In this challenge, the learner is practicing finding a TODO, creating a clear issue, and explaining what needs to change. The point is not to rush. The point is to leave a clear trace of good work.

      -

      Jamie: So we should name what success sounds like before the learner starts clicking or typing.

      -

      Alex: Yes. When the checkpoint is clear, the learner can tell the difference between being stuck and simply not being finished yet.

      +

      Jamie: Let's pause on Learning Cards: Reviewing on GitHub.com. What should a learner take away from it?

      +

      Alex: Start with Learning Cards: Reviewing on GitHub.com. There is something to understand, something to try, and something that proves the try worked.

      +

      Alex: The practical takeaway is this. In the Files Changed tab, press T to jump to the diff table, then use Focus Mode (Insert+Space in NVDA, Insert+Z in JAWS) and Down Arrow to read line by line -- each added line starts with + and each removed line with -. To place an inline comment, navigate to the target line and press Tab or B to find the "Add a comment to this line" button; after typing your comment, choose "Start a review" (not "Add single comment") to batch all feedback into one notification. Submit your full review by pressing B repeatedly to find the "Review changes" button; the dialog contains a radio group (Comment / Approve / Request changes) navigable with Arrow keys, then Tab to "Submit review". Switch from split diff to unified diff (gear icon in the Files Changed toolbar then select "Unified") to show old and new code in a single column -- much easier to follow at high zoom than two side-by-side panes. The blue + comment button appears in the line gutter on hover; at high zoom it may be small -- use Ctrl++ to increase browser zoom and look just left of the line number column. The "Review changes" dialog uses clearly labeled radio buttons for the three verdict types; each label includes a brief description, and the currently selected option has a filled circle indicator visible in all themes.

      +

      Alex: Keep the teaching thread moving. Start with Reviewing in VS Code with the Accessible Diff Viewer: When you check out a branch locally, VS Code's diff editor offers the Accessible Diff Viewer - a purpose-built, line-by-line reading mode designed specifically for screen readers. Think of it like entering a new building: first you find the lobby, then the room, then the door you actually need.

      +

      Jamie: Let's pause on Opening a Diff in VS Code. What should a learner take away from it?

      +

      Alex: Here is the plain-English version of Opening a Diff in VS Code. If you have the GitHub Pull Requests extension. Put another way, without the extension, any git diff operation also opens the diff editor.

      +

      Alex: First, open the GitHub Pull Requests view (Explorer sidebar or Ctrl+Shift+P → "GitHub Pull Requests: View Pull Request"). Then, find the PR and open it - changed files appear in the file tree. After that, navigate to any file in the tree and press Enter to open its diff view. Treat it like a recipe: do not add the next ingredient until the previous one is actually in the bowl.

      -

      Jamie: What makes this practice feel low-stakes but still real?

      -

      Alex: Start with Challenge 2: File Your First Issue: What you will do: Find a TODO comment in docs/welcome.md, then file an issue describing the problem with a clear title and description.

      -

      Alex: A solid issue habit is to read the title, the body, and the timeline before acting. You are listening for the requested action, the missing evidence, and the person who needs a response.

      -

      Jamie: How would you walk the room through that step by step?

      -

      Alex: Start with Instructions. There is something to understand, something to try, and something that proves the try worked.

      -

      Alex: The practical anchors are these. What needs to change. Where the problem is (file name and what section). Why it matters.

      -

      Alex: First, open docs/welcome.md and look for a line that contains TODO -- this marks something that needs fixing. Then, go to the Issues tab and select New issue. After that, write a clear, descriptive title (not just "Fix TODO"). Finally, in the description, explain. Treat it like a recipe: do not add the next ingredient until the previous one is actually in the bowl.

      -

      Jamie: What is the one idea that makes the next few steps less mysterious?

      -

      Alex: This is where What makes a good issue title? becomes real: I found a TODO in docs/welcome.md that said.

      -
      -

      Alex: Now bring the learner back to the room. Keep the learner anchored in Peer simulation check. Open the Peer Simulation: Welcome Link Needs Context issue and leave a comment: Is the title clear? This is the part to say slowly: Would you know what needs fixing just from reading the title?

      -

      Jamie: What would you say to someone who is already bracing for this to be too much?

      -

      Alex: The reason Example 1: Bug report style matters is that in docs/welcome.md, line 15, there is a TODO comment that says "add link to workshop schedule." This placeholder should be replaced with an actual link so students can find the schedule.

      -

      Alex: The useful habit is simple: orient first, act second, verify third. That pause before acting is part of the work.

      -

      Alex: That matters because of the next idea. Start with Example 2: Feature request style: The welcome document covers what students will do but does not mention accessibility features. The next useful detail is this: A short section pointing students to screen reader shortcuts and keyboard navigation would help everyone start on equal footing. Think of it like entering a new building: first you find the lobby, then the room, then the door you actually need.

      +

      Jamie: Let's pause on Learning Cards: VS Code Code Review. What should a learner take away from it?

      +

      Alex: This is where Learning Cards: VS Code Code Review becomes real: low vision users (zoom, high contrast). That matters in practice: VS Code's diff editor works well at high zoom.

      +

      Alex: First, split view vs. inline: By default, VS Code shows diffs in a split (side-by-side) view. At high zoom this can be very cramped. Switch to inline mode: Ctrl+Shift+P then type "Toggle Inline View" in any diff editor. Inline mode shows old and new code in a single. Then, colour indicators: Added lines have a green gutter bar; removed lines have a red gutter bar. In high contrast themes, these use heavy solid borders that are visible even at extreme zoom levels. After that, change navigation: Press F7 to jump to the next change and Shift+F7 for the previous. Each change is highlighted with a visible focus box that moves with your position - much easier than scrolling at high zoom. Finally, minimap in diff view: The minimap (right edge) shows an overview of changes as coloured blocks. At high zoom the minimap may be too small to be useful - disable it via Settings if it adds visual noise. It is a checklist, but a meaningful one: every item creates evidence that the next step is safe.

      +

      Jamie: Before we leave Learning Cards: VS Code Code Review, what is the practical point?

      +

      Alex: First, font size for diffs: Diff editors use your configured editor font size (editor.fontSize). Increase this in Settings (Ctrl+,) if the diff text is too small at your zoom level. Then, comment highlight: When you add a comment through the GitHub PR extension, the commented line gets a distinct background. In high contrast themes this is a solid colour band. It is like walking a hallway with named doors: read the sign, enter the right room, then confirm where you landed.

      +

      Jamie: Let's pause on Opening the PR for review. What should a learner take away from it?

      +

      Alex: Start with Opening the PR for review. There is something to understand, something to try, and something that proves the try worked.

      +

      Alex: First, press Ctrl+Shift+P, type "GitHub Pull Requests: View Pull Request". Then, the PR tree appears in the sidebar - navigate with Down Arrow. After that, each changed file is announced with its name and change summary. Finally, press Enter on a file to open its diff editor. It is like walking a hallway with named doors: read the sign, enter the right room, then confirm where you landed.

      +

      Jamie: Before we leave Opening the PR for review, what is the practical point?

      +

      Alex: First, the diff editor opens with the standard VS Code diff layout. The rhythm is simple: orient, act, verify, then continue.

      +

      Jamie: Let's pause on Using the Accessible Diff Viewer. What should a learner take away from it?

      +

      Alex: Start with Using the Accessible Diff Viewer. There is something to understand, something to try, and something that proves the try worked.

      +

      Alex: First, in the diff editor, press F7 to open the Accessible Diff Viewer. Then, NVDA announces: "Changed lines X to Y in filename, Change 1 of N". After that, the viewer shows each change with "Removed:" and "Added:" labels. Finally, press F7 to move to the next change, Shift+F7 for previous. The rhythm is simple: orient, act, verify, then continue.

      +

      Jamie: Before we leave Using the Accessible Diff Viewer, what is the practical point?

      +

      Alex: First, press Escape when done to close the viewer. Think of it as a rail line: each stop confirms you are still on the right route before the next one.

      -

      Jamie: Okay, set the room for us. What are we walking into?

      -

      Alex: Start with What makes a good issue. There is something to understand, something to try, and something that proves the try worked.

      -

      Alex: Here is what that changes in practice. Clear title: Someone scanning the issue list can understand the topic without opening it. Enough context: Another person could find and understand the problem from your description alone. Reproducible location: File name and line number (if relevant) so the fix is easy to find.

      -

      Alex: This is where the talk moves from concept to action. This is where Alternate approaches becomes real: both bug reports and feature suggestions are valid for this challenge. That matters in practice: The key is writing clearly enough that a stranger could act on your issue.

      -

      Alex: A solid pull request habit is to separate three questions: what changed, why it changed, and what still needs review. That keeps the conversation useful instead of noisy.

      -

      Jamie: Where do you want a learner to place their attention here?

      -

      Alex: Keep the learner anchored in Filing, Managing, and Participating in GitHub Issues. Issues are where open source collaboration begins. This is the part to say slowly: everything from finding the right issue to file a perfect bug report - all with your keyboard and screen reader.

      +

      Jamie: Let's pause on Placing a comment. What should a learner take away from it?

      +

      Alex: Start with Placing a comment: Screen reader users (VoiceOver on macOS).

      +

      Alex: First, navigate to the line you want to comment on in the diff. Then, press Ctrl+Shift+P, type "GitHub Pull Requests: Add Comment". After that, a text area opens below the line - NVDA announces the input focus. Finally, type your comment. Think of it as a rail line: each stop confirms you are still on the right route before the next one.

      +

      Jamie: Before we leave Placing a comment, what is the practical point?

      +

      Alex: First, press Tab to the Submit button, then Enter. Treat it like a recipe: do not add the next ingredient until the previous one is actually in the bowl.

      +

      Jamie: Let's pause on Opening the PR. What should a learner take away from it?

      +

      Alex: Start with Opening the PR. There is something to understand, something to try, and something that proves the try worked.

      +

      Alex: First, press Cmd+Shift+P, type "GitHub Pull Requests: View Pull Request". Then, navigate the PR tree with VO+Down Arrow. After that, press Return on a file to open its diff. Treat it like a recipe: do not add the next ingredient until the previous one is actually in the bowl.

      +

      Jamie: Before we leave Accessible Diff Viewer, what is the practical point?

      +

      Alex: Start with Accessible Diff Viewer. There is something to understand, something to try, and something that proves the try worked.

      +

      Alex: First, press F7 in the diff editor. Then, VoiceOver announces each change with clear "Removed" and "Added" labels. After that, navigate with F7/Shift+F7. Finally, press Escape to close. It is a checklist, but a meaningful one: every item creates evidence that the next step is safe.

      -

      Alex: Before the learner moves on. The reason Workshop Recommendation (Chapter 5 / Challenges 2-3) matters is that chapter 5 is the first issue-based challenge chapter with short, confidence-building tasks. That gives the learner a simple foothold: it supports Challenge 2 (File Your First Issue) and Challenge 3 (Join the Conversation). The interface gets friendlier when it stops being a wall of controls and starts being a set of named places.

      -

      Alex: That becomes easier when you listen for these cues. There are 2 core challenges plus one optional extension. Each challenge should take under 10 minutes. The evidence is issue comments and issue metadata. The pattern is claim - act - confirm.

      -

      Jamie: Give me the sequence, because order matters here.

      -

      Alex: Start with Chapter 5 Challenge Set: Chapter 5 focuses on issue skills. The next useful detail is this: You do NOT need to create a branch or edit any files for these challenges.

      -

      Alex: First, create your first issue - file a new issue with a clear title and description. Then, comment and @mention - leave a comment on a classmate's issue and tag them with an @mention. After that, optional extension: Add a sub-issue - break a larger issue into smaller, trackable pieces if your repository has sub-issues enabled. Think of it as a rail line: each stop confirms you are still on the right route before the next one.

      -

      Jamie: What does the learner do first, second, and then after that?

      -

      Alex: Here is the plain-English version of Challenge 2 Step-by-Step: Create Your First Issue. File a new issue in your Learning Room repository with a specific title and a meaningful description. Put another way, issues are the prompts that wake up AI.

      -

      Alex: That shows up in the workshop in a few specific ways. "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". What the problem is or what content is missing.

      -

      Alex: First, open your Learning Room repository in your browser. Then, navigate to the Issues tab (press G then I to jump there with keyboard shortcuts, or find the "Issues" link in the repository navigation). After that, activate the New issue button. Finally, if a template picker appears, select Open a blank issue (or choose a template if one fits). Treat it like a recipe: do not add the next ingredient until the previous one is actually in the bowl.

      -

      Jamie: Turn that into a path someone can follow.

      -

      Alex: First, in the Title field, type a clear, specific title (at least 12 characters). Then, in the Body field, write a meaningful description (at least 80 characters). After that, activate Submit new issue. Finally, copy the issue URL or note the issue number (for example, 150). You will reference this later. It is a checklist, but a meaningful one: every item creates evidence that the next step is safe.

      +

      Jamie: Let's pause on Comment placement. What should a learner take away from it?

      +

      Alex: Start with Comment placement. There is something to understand, something to try, and something that proves the try worked.

      +

      Alex: First, press Cmd+Shift+P, type "GitHub Pull Requests: Add Comment". Then, vO+Shift+Down Arrow to interact with the comment text area. After that, type your comment. Finally, vO+Shift+Up Arrow to stop interacting, then Tab to Submit. It is like walking a hallway with named doors: read the sign, enter the right room, then confirm where you landed.

      +

      Jamie: Let's pause on Using the Accessible Diff Viewer (F7). What should a learner take away from it?

      +

      Alex: The reason Using the Accessible Diff Viewer (F7) matters is that the Accessible Diff Viewer reads each change as a structured block. That gives the learner a simple foothold: this example is from a real Learning Room scenario: a contributor fixing the heading hierarchy in docs/keyboard-shortcuts.md by changing a level-4 heading to level-3, which is exactly what you look for when reviewing Challenge 2 PRs.

      +

      Alex: Treat examples as spoken recipes, not decorations. You may hear something like "Changed lines 14 to 14 in docs/keyboard-shortcuts.md; [Change 1 of 3]; Removed:; NVDA Single-Key Navigation; Added:; NVDA Single-Key Navigation". Read the command, understand what it changes, then run it only when the repository state matches the lesson.

      +

      Alex: Keep the teaching thread moving. Start with Navigation. There is something to understand, something to try, and something that proves the try worked.

      +

      Alex: The practical takeaway is this. F7 - jump to next change (next hunk). Shift+F7 - jump to previous change. Alt+F2 - open VS Code's Accessible View for additional context on the current item. Escape - close the Accessible Diff Viewer.

      -

      Jamie: What is the ordered workflow?

      -

      Alex: This is where Challenge 4.2 Step-by-Step: Comment and @Mention becomes real: leave a comment on another student's issue and use an @mention to notify them. That matters in practice: the Issues tab of your Learning Room repository on GitHub.com.

      -

      Alex: For a learner, the useful signals are these. "@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.".

      -

      Alex: First, open the Issues tab in your Learning Room repository. Then, find an issue created by a classmate (look for issues from Challenge 4.1, or browse recent open issues). After that, open the issue by activating its title link. Finally, read the issue description to understand what they reported. It is a checklist, but a meaningful one: every item creates evidence that the next step is safe.

      -

      Jamie: Let's pause on Challenge 4.2 Step-by-Step: Comment and @Mention. What should a learner take away from it?

      -

      Alex: First, scroll to the comment box at the bottom of the issue. Then, write a helpful comment that @mentions the issue author by username. After that, activate the Comment button (or press Ctrl+Enter). It is like walking a hallway with named doors: read the sign, enter the right room, then confirm where you landed.

      -

      Jamie: Let's pause on Challenge 4.3 Step-by-Step: Add a Sub-Issue. What should a learner take away from it?

      -

      Alex: Keep the learner anchored in Challenge 4.3 Step-by-Step: Add a Sub-Issue. Break a larger issue into smaller, trackable pieces using GitHub's sub-issue feature. This is the part to say slowly: the issue you created in Challenge 4.1 (or any open issue you have permission to edit). A good GitHub workflow is like a well-run meeting: everyone knows the topic, the next action, and who has the floor.

      -

      Alex: The parts worth keeping in working memory are these. Sub-issue: "Add alt text to welcome banner image". Sub-issue: "Fix heading hierarchy in Getting Started section".

      -

      Alex: First, open the issue you created in Challenge 4.1. Then, 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. After that, activate Add sub-issue and choose Create new sub-issue. Finally, 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". It is like walking a hallway with named doors: read the sign, enter the right room, then confirm where you landed.

      -

      Jamie: Before we leave Challenge 4.3 Step-by-Step: Add a Sub-Issue, what is the practical point?

      -

      Alex: First, add a short description and activate Create. Then, the sub-issue now appears nested under the parent issue with a progress indicator. The rhythm is simple: orient, act, verify, then continue.

      -

      Jamie: What should the learner prove to themselves after each small task?

      -

      Alex: The reason Completing Chapter 4: Submit Your Evidence matters is that 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. That gives the learner a simple foothold: replace [number] with the actual issue numbers.

      +

      Jamie: Let's pause on What makes this better than the raw diff editor. What should a learner take away from it?

      +

      Alex: Start with What makes this better than the raw diff editor. There is something to understand, something to try, and something that proves the try worked.

      +

      Alex: The practical takeaway is this. Each change is announced as a discrete unit with clear "Removed:" and "Added:" labels. You hear the change number of total changes ("Change 3 of 12"). No table navigation required - purpose-built for sequential listening. Works with all three major screen readers without any special configuration.

      +

      Alex: Keep the teaching thread moving. This is where Placing Comments in VS Code (GitHub PR Extension) becomes real: from the diff editor with the GitHub PR extension. That matters in practice: Comments placed in VS Code sync to GitHub - they appear in the PR's Files Changed tab and the author receives the same notification. The workshop is closer to rehearsal than lecture. You hear the move, try the move, and then check what changed.

      +

      Jamie: Let's pause on The Anatomy of a Useful Review Comment. What should a learner take away from it?

      +

      Alex: Keep the learner anchored in The Anatomy of a Useful Review Comment. A comment that helps the author is.

      +

      Alex: First, specific - link to the exact line and name the pattern you see. Then, educational - say why something matters, not just what to change. After that, graduated - signal whether this is blocking, or a preference. It is like walking a hallway with named doors: read the sign, enter the right room, then confirm where you landed.

      -

      Alex: Here is the practical turn. Start with Expected Outcomes. There is something to understand, something to try, and something that proves the try worked.

      -

      Alex: On the ground, that means a few things. 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.

      -

      Jamie: Let's pause on If You Get Stuck. What should a learner take away from it?

      -

      Alex: Start with If You Get Stuck. There is something to understand, something to try, and something that proves the try worked.

      -

      Alex: First, can't find a classmate's issue? Filter the Issues tab by is:open and look for recent ones. Then, @mention not working? Make sure you type @ immediately followed by the username with no space. After that, sub-issue option not visible? Ask a facilitator - the feature may need to be enabled for the repository. Finally, still stuck? Ask a facilitator for a direct issue link. Treat it like a recipe: do not add the next ingredient until the previous one is actually in the bowl.

      -

      Jamie: Before we leave If You Get Stuck, what is the practical point?

      -

      Alex: First, finished but not sure you did it right? Compare your work against the Challenge 2 reference solution or the Challenge 3 reference solution. It is a checklist, but a meaningful one: every item creates evidence that the next step is safe.

      -

      Alex: Keep the thread going. This is where Learning Moment becomes real: issues are collaborative spaces, not just task lists. That matters in practice: An @mention tells someone "I need your attention here." Sub-issues turn vague tasks into clear checklists. The workshop is closer to rehearsal than lecture. You hear the move, try the move, and then check what changed.

      +

      Alex: Keep the teaching thread moving. The reason Blocking example (reviewing a PR for docs/keyboard-shortcuts.md) matters is that "The heading on line 34 uses (level 4) directly after (level 2), skipping heading level 3. That gives the learner a simple foothold: screen reader users who navigate by heading level will miss any content between those two levels.

      +

      Jamie: Let's pause on Non-blocking (nit) example (reviewing a PR for docs/welcome.md). What should a learner take away from it?

      +

      Alex: Start with Non-blocking (nit) example (reviewing a PR for docs/welcome.md): "nit: The link text in the 'Getting Help' section reads 'click here for more information.' Screen reader users who navigate links out of context will hear only 'click here' with no destination. The next useful detail is this: Consider 'See the accessibility setup guide' instead.

      +

      Alex: Keep the teaching thread moving. Here is the plain-English version of Question example (reviewing a PR for docs/setup-guide.md). "The PR description says this fixes broken links in the setup guide, but the link on line 12 still points to /docs/old-setup. Put another way, am I reading the diff correctly, or was this link intentionally left? It is like learning a transit route. The names of the stops matter because they tell you whether you are still going the right direction.

      -

      Jamie: Let's pause on Learning Pattern Used in This Chapter. What should a learner take away from it?

      -

      Alex: Start with Learning Pattern Used in This Chapter. There is something to understand, something to try, and something that proves the try worked.

      -

      Alex: First, start with a small, safe action (create an issue). Then, practice communication in public issue threads (@mention a peer). After that, organize work into smaller pieces (sub-issues). Finally, leave clear evidence in the issue timeline. It is like walking a hallway with named doors: read the sign, enter the right room, then confirm where you landed.

      -

      Jamie: Before we leave Learning Pattern Used in This Chapter, what is the practical point?

      -

      Alex: First, build momentum for file editing and PR work in Chapter 6. The rhythm is simple: orient, act, verify, then continue.

      -

      Alex: Another way to ground it. The reason About Learning Cards in This Chapter matters is that this chapter provides learning cards: expandable blocks that offer perspective-specific guidance for different ways of working. That gives the learner a simple foothold: not every card appears at every step.

      -

      Jamie: What should they understand before typing anything?

      -

      Alex: Start with Local Git Alternative: Working from Your Clone: If you cloned the learning-room in Block 0 and prefer working locally. The next useful detail is this: During Block 0 you cloned the Learning Room repository to your computer.

      -

      Alex: Treat examples as spoken recipes, not decorations. You may hear something like cd /Documents/learning-room or wherever you cloned it; git status should show "On branch main". 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. Read the command, understand what it changes, then run it only when the repository state matches the lesson.

      -

      Alex: A solid Git habit is to know which branch you are on, what changed, and what confirmation you expect before you run the next command.

      +

      Jamie: Let's pause on Prefixes That Set Expectations. What should a learner take away from it?

      +

      Alex: This is where Prefixes That Set Expectations becomes real: using shorthand prefixes helps authors parse many comments quickly.

      +

      Alex: Keep the teaching thread moving. Keep the learner anchored in How Many Comments Is Too Many? There is no hard limit, but quantity without prioritization is noise. This is the part to say slowly: If you have 15 comments, make clear which 2-3 are blocking.

      +

      Jamie: Let's pause on "I want to verify the PR only changes what it claims". What should a learner take away from it?

      +

      Alex: The reason "I want to verify the PR only changes what it claims" matters is that example: A PR says "Challenge 2: Add NVDA shortcut" but the file tree shows changes to both docs/keyboard-shortcuts.md and docs/welcome.md.

      -

      Alex: This is the part worth saying out loud. Here is the plain-English version of What Is a GitHub Issue? An issue is a discussion thread attached to a repository. Put another way, every issue has a number ( 42), a state (Open or Closed), a title, a description, and a comment thread. It is like learning a transit route. The names of the stops matter because they tell you whether you are still going the right direction.

      -

      Alex: The room should hear these as checkpoints. 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".

      -

      Jamie: Let's pause on From a repository page. What should a learner take away from it?

      -

      Alex: This is where From a repository page becomes real: click the Issues tab in the repository navigation bar below the repository name. That matters in practice: The tab shows the open issue count (e.g., "Issues · 14").

      -

      Alex: First, press D to navigate to the "Repository navigation" landmark. Then, press K or Tab to move through the tab links. After that, find "Issues" - it will be announced with the count: "Issues, 14 open". Finally, press Enter to open the Issues tab. It is a checklist, but a meaningful one: every item creates evidence that the next step is safe.

      -

      Jamie: Before we leave From a repository page, what is the practical point?

      -

      Alex: First, vO+U → Landmarks → navigate to "Repository navigation". Then, vO+Right or Quick Nav K to move through tab links. After that, find "Issues" - VoiceOver announces the count: "Issues 14". Finally, vO+Space to activate the Issues tab. It is like walking a hallway with named doors: read the sign, enter the right room, then confirm where you landed.

      -

      Alex: Treat examples as spoken recipes, not decorations. You may hear something like gh issue list. gh issue list --label "good first issue"; gh issue list --assignee @me; gh issue list --state closed. Read the command, understand what it changes, then run it only when the repository state matches the lesson.

      -

      Alex: The next layer is this. Keep the learner anchored in Direct URL. Navigate directly: https://github.com/[owner]/[repo]/issues.

      +

      Alex: Keep the teaching thread moving. Start with "I want to find all changes to one specific section": Example: A PR for Challenge 3 modified docs/welcome.md. The next useful detail is this: You want to verify the [TODO] in the "Who Can Contribute?" section was filled in correctly. Think of it like entering a new building: first you find the lobby, then the room, then the door you actually need.

      +

      Jamie: Let's pause on Exercises. What should a learner take away from it?

      +

      Alex: Here is the plain-English version of Exercises. These exercises use the files in learning-room/docs/ in this repository. Put another way, all examples involve documentation changes - no code required.

      +

      Alex: Keep the teaching thread moving. This is where Exercise A - Complete a Web Review becomes real: scenario: A contributor has submitted a pull request titled "Add screen reader tips to the setup guide." The PR modifies learning-room/docs/setup-guide.md. That matters in practice: Your job is to review it before it merges.

      -

      Jamie: If I am listening before the workshop starts, what should settle in my mind first?

      -

      Alex: Start with Learning Cards: Navigating to the Issues List. There is something to understand, something to try, and something that proves the try worked.

      -

      Alex: These are the details that keep the idea from floating away. 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. 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.

      -

      Alex: Hold that next to this. Start with Page structure: 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. The next useful detail is this: This is often faster than tabbing through many elements and helps you understand the full page structure before diving in. Think of it like entering a new building: first you find the lobby, then the room, then the door you actually need.

      -

      Jamie: Let's pause on How to read the issue list. What should a learner take away from it?

      -

      Alex: Here is the plain-English version of How to read the issue list. The issues list shows each issue as a row with its title, labels, number, assignee avatars, and comment count. Put another way, closed issues show a purple merged/closed badge.

      -

      Alex: A few details make that real. 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.

      -

      Alex: First, press D to reach the "Search Results List" landmark. Then, press 3 (h3) to navigate by issue titles - each issue title is an h3 link. After that, press I to move between list items if you want more detail per item. Finally, press Enter on a title to open that issue. Treat it like a recipe: do not add the next ingredient until the previous one is actually in the bowl.

      -

      Jamie: Before we leave How to read the issue list, what is the practical point?

      -

      Alex: First, vO+U → Landmarks → navigate to "Search Results List". Then, vO+Down to read through items. After that, h (with Quick Nav on) or VO+U → Headings to jump by issue title. It is a checklist, but a meaningful one: every item creates evidence that the next step is safe.

      +

      Jamie: Let's pause on Step 1: Navigate to the Pull Request. What should a learner take away from it?

      +

      Alex: Keep the learner anchored in Step 1: Navigate to the Pull Request. How to know you're in the right place.

      +

      Alex: The practical takeaway is this. The PR title is visible at the top. You see a description box with text about what this PR does. You see tabs labeled "Conversation," "Commits," "Files Changed". Use Ctrl+F to search the PR list for "screen reader tips". Or ask in the workshop Slack - someone can share the exact URL.

      +

      Alex: First, open GitHub in your browser and navigate to the workshop repository (github.com/[your-fork]/[workshop-repo] or community-access/accessibility-agents). Then, click the Pull Requests tab (top navigation). After that, look for a PR titled "Add screen reader tips to the setup guide" - click it to open. Finally, you should now see the PR page with sections: Conversation, Commits, Files Changed. It is like walking a hallway with named doors: read the sign, enter the right room, then confirm where you landed.

      +

      Jamie: Let's pause on Step 2: Read the PR Description. What should a learner take away from it?

      +

      Alex: Start with Step 2: Read the PR Description. There is something to understand, something to try, and something that proves the try worked.

      +

      Alex: The practical takeaway is this. Does the PR author explain what file changed? (should mention setup-guide.md). Does it explain why? (should mention "improve accessibility" or "add tips"). Is it clear enough that a reviewer can understand the goal without reading the diff? You can answer: "This PR adds [specific content] to [specific file] because [clear reason]". Example: "This PR adds screen reader usage tips to the setup guide because new users need accessibility guidance".

      +

      Alex: First, you are currently on the Conversation tab. Then, read the PR description (the text immediately under the PR title). After that, look for: "What does this PR change?" and "Why does it change it?". Finally, with screen reader: Navigate to the description with D (NVDA) or press Ctrl+Option+Up (VoiceOver) to find main landmarks, then read the content region. The rhythm is simple: orient, act, verify, then continue.

      +

      Jamie: Let's pause on Step 3: Navigate to "Files Changed". What should a learner take away from it?

      +

      Alex: Start with Step 3: Navigate to "Files Changed". There is something to understand, something to try, and something that proves the try worked.

      +

      Alex: The practical takeaway is this. A section showing the file name setup-guide.md with a small badge showing "+20 −0" (20 lines added, 0 lines removed). Below it, the diff with removed lines (preceded by −) and added lines (preceded by +). Scroll up to see if there are other files. For this exercise, only setup-guide.md should be changed. If you see other files, confirm they are not modified (the badge should show "+0 −0" or no changes).

      +

      Alex: First, click the Files Changed tab (top of the PR page, to the right of "Commits"). Then, you are now viewing the diff. After that, with keyboard (all screen readers): Press T to jump to the diff table. The page focuses on the file comparison area. Think of it as a rail line: each stop confirms you are still on the right route before the next one.

      -

      Alex: That connects to another useful point. This is where What is announced per issue becomes real: when you navigate to an issue in the list, your screen reader will announce (in some order).

      -

      Alex: The practical takeaway is this. 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").

      -

      Jamie: Give me the version that sounds like an instructor, not a manual.

      -

      Alex: Start with Learning Cards: The Issues List Page. There is something to understand, something to try, and something that proves the try worked.

      -

      Alex: The practical takeaway is this. 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. 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.

      -

      Alex: Keep the teaching thread moving. The reason Filtering and Searching Issues matters is that filtering lets you narrow the list to find the right issue quickly. The interface gets friendlier when it stops being a wall of controls and starts being a set of named places.

      +

      Jamie: Let's pause on Step 4: Activate Focus Mode for Better Diff Reading. What should a learner take away from it?

      +

      Alex: Here is the plain-English version of Step 4: Activate Focus Mode for Better Diff Reading. With screen reader (once in Focus Mode).

      +

      Alex: The practical takeaway is this. The page simplifies: sidebars disappear. Only the diff is visible - easier for screen reader navigation and less cognitive load. The diff is now the main content area. NVDA/JAWS: Press T to jump to the diff table. VoiceOver: Navigate with VO+Right Arrow to find the table/content region. Read through the changes: ↓ arrow moves to each line.

      +

      Alex: First, look for a button labeled "Focus Mode" or an icon (usually at the top right of the diff area). Then, with keyboard: Press F to toggle Focus Mode (may need to be in the diff area first). After that, with mouse: Click the Focus Mode button/icon. Treat it like a recipe: do not add the next ingredient until the previous one is actually in the bowl.

      +

      Jamie: Let's pause on Step 5: Find the Heading Hierarchy Issue. What should a learner take away from it?

      +

      Alex: Start with Step 5: Find the Heading Hierarchy Issue. There is something to understand, something to try, and something that proves the try worked.

      +

      Alex: The practical takeaway is this. Screen reader users navigate documents by heading level: 1 → 2 → 3 → 4. A skip from to breaks that navigation. When a user presses "jump to heading level 3," they'll find none, wondering if content is missing. You found the line with that violates hierarchy. You can say the line number and what heading text appears there. You understand why this is an accessibility problem.

      +

      Alex: First, read through the entire diff line by line. Pay special attention to lines starting. Then, you are looking for: a line with (four hashes, heading level 4) that comes directly after a (two hashes, heading level 2). After that, when you find it, note the exact line number shown in the diff. It is a checklist, but a meaningful one: every item creates evidence that the next step is safe.

      +

      Jamie: Let's pause on Step 6: Place a Blocking Review Comment on the Heading. What should a learner take away from it?

      +

      Alex: Keep the learner anchored in Step 6: Place a Blocking Review Comment on the Heading. If the comment button doesn't appear. A good GitHub workflow is like a well-run meeting: everyone knows the topic, the next action, and who has the floor.

      +

      Alex: The practical takeaway is this. Your comment appears in the thread under that line. The PR author sees it and can make the fix. Make sure you're hovering over the line number area (left side of the line). Try refreshing the page and trying again. Or use the "Add a reply" field at the bottom of the PR and mention the line number manually.

      +

      Alex: First, find the diff line with the problematic heading. Then, hover your mouse over the line number on the left side of that line (or if using keyboard, navigate to that line in the table). After that, a button should appear (or press the Add Comment hotkey - usually C in GitHub). Finally, click it or press Enter to open a comment box. It is like walking a hallway with named doors: read the sign, enter the right room, then confirm where you landed.

      +

      Jamie: Before we leave Step 6: Place a Blocking Review Comment on the Heading, what is the practical point?

      +

      Alex: First, press Space, then explain. Then, click the Comment button (or press Ctrl+Enter for keyboard submit). The rhythm is simple: orient, act, verify, then continue.

      -

      Jamie: Let's pause on Using the search/filter bar. What should a learner take away from it?

      -

      Alex: Start with Using the search/filter bar. There is something to understand, something to try, and something that proves the try worked.

      -

      Alex: First, press F or E to jump to the filter input field (or navigate from the landmark). Then, switch to Focus Mode (NVDA+Space / Insert+Z) if not already in it. After that, type your filter or search query. Finally, press Enter to apply. Think of it as a rail line: each stop confirms you are still on the right route before the next one.

      -

      Jamie: Let's pause on Using the filter buttons. What should a learner take away from it?

      -

      Alex: Here is the plain-English version of Using the filter buttons. Above the issue list, there is an actions toolbar with filter buttons for Labels, Milestones, Assignees, etc. Put another way, the filter buttons do not indicate the current filter state.

      -

      Alex: The practical takeaway is this. 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.

      -

      Alex: First, press Tab from the search bar (or Shift+Tab from the issue list) to reach the actions toolbar. Then, press ←/→ to move between toolbar options (Label, Milestone, Assignee, Sort). After that, press Enter to open the selected dropdown. Finally, use ↑/↓ to navigate options in the dropdown. Treat it like a recipe: do not add the next ingredient until the previous one is actually in the bowl.

      -

      Jamie: Before we leave Using the filter buttons, what is the practical point?

      -

      Alex: First, press Enter or Space to select. Then, press Escape to close (filter applies immediately). After that, tab forward from the search bar to reach the filter buttons, or use Quick Nav to find them. Finally, vO+Left/Right to move between Label, Milestone, Assignee, Sort buttons. It is a checklist, but a meaningful one: every item creates evidence that the next step is safe.

      -

      Alex: Treat examples as spoken recipes, not decorations. You may hear something like 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". Read the command, understand what it changes, then run it only when the repository state matches the lesson.

      -

      Jamie: Let's pause on Open vs Closed filter. What should a learner take away from it?

      -

      Alex: This is where Open vs Closed filter becomes real: the two state links "Open" and "Closed" appear near the top of the issue list. That matters in practice: Press K to navigate links until you find them, or look for them as buttons near the search bar.

      +

      Jamie: Let's pause on Step 7: Find the Link Text Issue. What should a learner take away from it?

      +

      Alex: Start with Step 7: Find the Link Text Issue. There is something to understand, something to try, and something that proves the try worked.

      +

      Alex: The practical takeaway is this. Screen reader users can ask their reader to "list all links on this page" - they hear only the link text. If the text is "click here," they have no context about where it goes. Descriptive link text is WCAG 2.4.4 (Link Purpose). You found a link with non-descriptive text. You can explain why "click here" is bad and what would be better.

      +

      Alex: First, continue reading the diff (from where you left off). Then, look for a line containing link text that reads "click here" or "click here for more information". After that, note the line number. The rhythm is simple: orient, act, verify, then continue.

      +

      Jamie: Let's pause on Step 8: Place a Comment on the Link. What should a learner take away from it?

      +

      Alex: Start with Step 8: Place a Comment on the Link: nit: means "nice-to-have improvement" (not blocking, but good to fix).

      +

      Alex: First, find the line in the diff with the problematic link. Then, hover over the line number and click to open a comment box (or press C). After that, click Comment or press Ctrl+Enter. Think of it as a rail line: each stop confirms you are still on the right route before the next one.

      +

      Jamie: Let's pause on Step 9: Submit Your Review. What should a learner take away from it?

      +

      Alex: Start with Step 9: Submit Your Review. There is something to understand, something to try, and something that proves the try worked.

      +

      Alex: The practical takeaway is this. Comment - provide feedback but don't block (for minor notes). Approve - the PR is ready to merge. Request changes - this PR cannot merge until changes are made. Your review is submitted. The PR author gets a notification. The PR shows your review with the two comments.

      +

      Alex: First, look for a button labeled "Review changes" (usually at the top right of the page or bottom of comments). Then, click it (or navigate with keyboard and press Enter). After that, a dialog appears with options. Finally, select "Request changes" (you found two things to fix). Treat it like a recipe: do not add the next ingredient until the previous one is actually in the bowl.

      +

      Jamie: Before we leave Step 9: Submit Your Review, what is the practical point?

      +

      Alex: First, in the summary field, write: Found 2 accessibility issues that must be fixed before merging. Then, click "Submit review". It is a checklist, but a meaningful one: every item creates evidence that the next step is safe.

      -

      Alex: Keep the teaching thread moving. Start with Learning Cards: Filtering and Searching Issues. There is something to understand, something to try, and something that proves the try worked.

      -

      Alex: The practical takeaway is this. 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. 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.

      -

      Jamie: Let's pause on Landing on an issue page. What should a learner take away from it?

      -

      Alex: The reason Landing on an issue page matters is that when you open an issue, the page structure is.

      -

      Jamie: Let's pause on Reading the issue description. What should a learner take away from it?

      -

      Alex: Start with Reading the issue description: Browse Mode recommended: The issue detail page is primarily text-based. The next useful detail is this: Stay in Browse Mode (not Focus Mode) for reading - it gives you full heading (H), section (D), and link (K) navigation throughout the page.

      -

      Alex: First, press 2 to reach the "Description" heading. Then, press ↓ to read the content line by line,. After that, use NVDA+↓ (NVDA say all) to have it read continuously. Think of it as a rail line: each stop confirms you are still on the right route before the next one.

      -

      Alex: Treat examples as spoken recipes, not decorations. You may hear something like 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. Read the command, understand what it changes, then run it only when the repository state matches the lesson.

      +

      Jamie: Let's pause on Reflect on This Exercise. What should a learner take away from it?

      +

      Alex: This is where Reflect on This Exercise becomes real: keep your answers - you'll need them for Chapter 16's Accessibility Agents exercise to compare manual review with agent-assisted review. The workshop is closer to rehearsal than lecture. You hear the move, try the move, and then check what changed.

      +

      Alex: First, did heading-level navigation help? When you were looking for the issue, was it easier to navigate by heading level (1-6) than to scan every line? Then, would you have caught this without the exercise prompt? If you were a real reviewer not specifically looking for heading issues, would the diff have been obvious? After that, why does screen reader navigation matter? In one sentence, explain why a screen reader user's ability to jump through heading levels is important for this document. It is a checklist, but a meaningful one: every item creates evidence that the next step is safe.

      +

      Jamie: How do we make tool choice feel like access, not pressure?

      +

      Alex: Keep the learner anchored in Exercise B - Use the VS Code Accessible Diff Viewer. Scenario: Review the same pull request from Exercise A, this time entirely in VS Code. This is the part to say slowly: You'll compare the browser experience with the VS Code experience.

      +

      Alex: Keep the teaching thread moving. Start with Prerequisites. There is something to understand, something to try, and something that proves the try worked.

      +

      Alex: The practical takeaway is this. VS Code must be installed on your machine. The GitHub Pull Requests extension must be installed (see Chapter 12 for installation). You must be signed into GitHub from VS Code (use Ctrl+Shift+P → "GitHub: Sign in").

      -

      Jamie: Let's pause on Reading comments and activity. What should a learner take away from it?

      -

      Alex: Here is the plain-English version of Reading comments and activity. Each comment in the thread is marked as an h3. Put another way, other timeline events (label added, PR linked, issue closed) appear between comments in the activity stream.

      -

      Alex: The practical takeaway is this. Commenter's username. Timestamp ("2 days ago"). Body text. Reactions (if any - announced as a button with an emoji and count).

      -

      Alex: Keep the teaching thread moving. Start with Learning Cards: Reading an Issue. There is something to understand, something to try, and something that proves the try worked.

      -

      Alex: The practical takeaway is this. 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. 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.

      -

      Jamie: Let's pause on Step-by-step. What should a learner take away from it?

      -

      Alex: Keep the learner anchored in Step-by-step. To close the issue while commenting: click the arrow on the Close issue button and choose Close with comment. This is the part to say slowly: Low vision users (zoom, high contrast).

      -

      Alex: First, scroll to the bottom of the issue page. Then, click in the Leave a comment text area. After that, type your comment (Markdown is supported - use the toolbar buttons above the text for bold, italic, code, etc.). Finally, optionally click Preview to see how it will render. It is like walking a hallway with named doors: read the sign, enter the right room, then confirm where you landed.

      -

      Jamie: Before we leave Step-by-step, what is the practical point?

      -

      Alex: First, click the green Comment button to post. Then, scroll to the bottom to find the Leave a comment text area. At 200%+ zoom, this may require significant scrolling past the timeline. After that, the text area expands as you type. The formatting toolbar above it (bold, italic, code, etc.) wraps at high zoom but remains functional. Finally, the Preview tab next to Write lets you check Markdown rendering before posting. The rhythm is simple: orient, act, verify, then continue.

      -

      Alex: Treat examples as spoken recipes, not decorations. You may hear something like 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.". Read the command, understand what it changes, then run it only when the repository state matches the lesson.

      +

      Jamie: Let's pause on Step 1: Open the GitHub Pull Requests Extension. What should a learner take away from it?

      +

      Alex: Start with Step 1: Open the GitHub Pull Requests Extension. There is something to understand, something to try, and something that proves the try worked.

      +

      Alex: The practical takeaway is this. With mouse: Click the Extensions icon on the left sidebar (looks like four squares). The extension is listed as active. It mentions: "Review and manage GitHub pull requests and issues".

      +

      Alex: First, open VS Code. Then, with keyboard (all screen readers): Press Ctrl+Shift+X to open the Extensions sidebar. After that, search for "GitHub Pull Requests". Finally, if it's not installed, click Install. Think of it as a rail line: each stop confirms you are still on the right route before the next one.

      +

      Jamie: Before we leave Step 1: Open the GitHub Pull Requests Extension, what is the practical point?

      +

      Alex: First, if it is installed, click GitHub Pull Requests to view its details. Treat it like a recipe: do not add the next ingredient until the previous one is actually in the bowl.

      +

      Jamie: Let's pause on Step 2: Open the Pull Requests Sidebar. What should a learner take away from it?

      +

      Alex: Start with Step 2: Open the Pull Requests Sidebar. There is something to understand, something to try, and something that proves the try worked.

      +

      Alex: The practical takeaway is this. With keyboard: The icon may not be keyboard-reachable directly; instead go to Step 3. VS Code opens a new editor tab for this PR. Below the PR title, you see a "Changes" section listing modified files. You should see setup-guide.md in the changes list. Use Ctrl+Shift+P → search GitHub Pull Requests: Open Pull Request. Paste the PR URL: https://github.com/[owner]/[repo]/pull/[number].

      +

      Alex: First, look for a GitHub-themed icon on the left sidebar (circle with octocat logo) - click it. Then, a sidebar appears showing open pull requests on repositories you have access to. After that, find the PR titled "Add screen reader tips to the setup guide" - it should appear in a list. Finally, click it to open. Treat it like a recipe: do not add the next ingredient until the previous one is actually in the bowl.

      +

      Jamie: Let's pause on Step 3: View the File Changes. What should a learner take away from it?

      +

      Alex: Start with Step 3: View the File Changes. There is something to understand, something to try, and something that proves the try worked.

      +

      Alex: The practical takeaway is this. A diff editor opens showing two columns. Left: the original file (before changes). Right: the new file (after changes). Different colors show added (green), removed (red), and modified (blue) lines. The file name appears at the top: setup-guide.md. NVDA/JAWS: The editor announces "Diff Editor - setup-guide.md".

      +

      Alex: First, in the Changes section, locate setup-guide.md. Then, click on the filename to open it. It is a checklist, but a meaningful one: every item creates evidence that the next step is safe.

      -

      Alex: Keep the teaching thread moving. The reason Markdown formatting while typing matters is that these keyboard shortcuts work inside the text area (Focus Mode).

      -

      Jamie: Let's pause on GitHub shortcuts for the Issues pages. What should a learner take away from it?

      -

      Alex: Start with GitHub shortcuts for the Issues pages: These are the GitHub built-in shortcuts for working with issues. The next useful detail is this: Enable Focus Mode first (NVDA: NVDA+Space, JAWS: Insert+Z) before using single-key shortcuts.

      -

      Alex: Keep the teaching thread moving. Here is the plain-English version of On the Issues list page. Shortcut note: For G I, press G, release it, then press I (two sequential key presses, not simultaneous). It is like learning a transit route. The names of the stops matter because they tell you whether you are still going the right direction.

      +

      Jamie: Let's pause on Step 4: Access the Accessible Diff Viewer. What should a learner take away from it?

      +

      Alex: Keep the learner anchored in Step 4: Access the Accessible Diff Viewer. If the Accessible Diff Viewer doesn't open.

      +

      Alex: The practical takeaway is this. With mouse: Look for a button or menu option labeled "Accessible View" or "Open Accessible Diff". If no button is visible, try Alt+F2 (VS Code Accessible View toggle). A new panel opens at the bottom of VS Code. The panel announces each change one at a time. Changes appear in text format with labels: "Added: " and "Removed: ". The panel is read-only (you read the changes, you don't edit here).

      +

      Alex: First, with keyboard: Press F7 to open the Accessible Diff Viewer. It is like walking a hallway with named doors: read the sign, enter the right room, then confirm where you landed.

      +

      Jamie: Let's pause on Step 5: Listen to and Understand the First Change. What should a learner take away from it?

      +

      Alex: Start with Step 5: Listen to and Understand the First Change. There is something to understand, something to try, and something that proves the try worked.

      +

      Alex: The practical takeaway is this. NVDA/JAWS: The Accessible Diff Viewer announces "Removed:" and "Added:" labels, followed by the line content. VoiceOver: The announcement may be similar; listen for "removed" and "added" keywords.

      +

      Alex: First, the first change is automatically announced when you open the Accessible Diff Viewer. Then, let your screen reader read it completely - don't interrupt. After that, write down the exact text announced. Finally, press the Down arrow to move to the next change. The rhythm is simple: orient, act, verify, then continue.

      +

      Jamie: Let's pause on Step 6: Find the Heading Hierarchy Issue. What should a learner take away from it?

      +

      Alex: Start with Step 6: Find the Heading Hierarchy Issue. There is something to understand, something to try, and something that proves the try worked.

      +

      Alex: The practical takeaway is this. Four hashes ( ) indicate a level 4 heading. In the diff, you're looking for it appearing after a level 2 heading ( ). This creates the hierarchy skip you caught in Exercise A. You found the explanation in the Accessible Diff Viewer's format. You can explain: "The added line with directly follows a, skipping level 3". The Accessible Diff Viewer made this pattern clearer than scanning raw + characters.

      +

      Alex: First, continue pressing Down arrow to move through changes. Then, listen carefully for a change involving headings (lines starting with ). After that, specifically, listen for: "Added: " (four hashes). Finally, when you hear this, stop and write it down. Think of it as a rail line: each stop confirms you are still on the right route before the next one.

      -

      Jamie: Let's pause on On an open issue. What should a learner take away from it?

      -

      Alex: This is where On an open issue becomes real: r to quote is a power move: Select any text in a comment while in Browse Mode (Shift+Arrow to select), then press R. That matters in practice: GitHub puts the quoted text in the comment box as a Markdown blockquote.

      -

      Alex: First, navigate to your comment (3 to jump to comments). Then, find the "." (ellipsis) menu button near your comment. After that, press Enter on "Edit" from that menu. Finally, the comment turns into a text area - switch to Focus Mode. It is a checklist, but a meaningful one: every item creates evidence that the next step is safe.

      -

      Jamie: Before we leave On an open issue, what is the practical point?

      -

      Alex: First, make your changes. Then, tab to "Update comment" button → Enter. It is like walking a hallway with named doors: read the sign, enter the right room, then confirm where you landed.

      -

      Alex: Keep the teaching thread moving. Start with Learning Cards: Leaving a Comment. There is something to understand, something to try, and something that proves the try worked.

      -

      Alex: The practical takeaway is this. 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. 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.

      -

      Jamie: Let's pause on Navigating to New Issue. What should a learner take away from it?

      -

      Alex: The reason Navigating to New Issue matters is that from the Issues list page, click the green New issue button in the top-right of the issue list. That gives the learner a simple foothold: 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.

      -

      Alex: The practical takeaway is this. 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.

      -

      Alex: First, press K to navigate links and find the "New issue" button/link. Then, press Enter. After that, 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. Finally, quick Nav B or VO+U → Buttons to find the "New issue" button. The rhythm is simple: orient, act, verify, then continue.

      -

      Jamie: Before we leave Navigating to New Issue, what is the practical point?

      -

      Alex: First, vO+Space to activate it. Then, 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. Think of it as a rail line: each stop confirms you are still on the right route before the next one.

      -
      -

      Alex: Keep the teaching thread moving. Start with Filling Out the Issue Form: The issue form has these fields (order may vary depending on the template). Think of it like entering a new building: first you find the lobby, then the room, then the door you actually need.

      -

      Jamie: Let's pause on Title field. What should a learner take away from it?

      -

      Alex: Start with Title field. There is something to understand, something to try, and something that proves the try worked.

      -

      Alex: First, find the Title input field (F or by landmark). Then, focus Mode → type a clear, specific title. After that, good title: "Screen reader announces wrong element count on Issues list with 50+ items". Finally, bad title: "Bug with screen reader". Treat it like a recipe: do not add the next ingredient until the previous one is actually in the bowl.

      -

      Jamie: Let's pause on Description / Body field. What should a learner take away from it?

      -

      Alex: Start with Description / Body field. There is something to understand, something to try, and something that proves the try worked.

      -

      Alex: First, tab to the body text area. Then, focus Mode → type using the Markdown template provided. After that, if no template, use this structure. It is a checklist, but a meaningful one: every item creates evidence that the next step is safe.

      -

      Alex: Treat examples as spoken recipes, not decorations. You may hear something like 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. Read the command, understand what it changes, then run it only when the repository state matches the lesson.

      -
      -

      Jamie: Let's pause on Assigning labels from the sidebar. What should a learner take away from it?

      -

      Alex: Keep the learner anchored in Assigning labels from the sidebar. See also: Chapter 09: Labels, Milestones, and Projects covers the full label and milestone system. This is the part to say slowly: While the form is open, the sidebar has dropdowns for Labels, Assignees, and Milestone.

      -

      Alex: First, tab away from the text area (or press Escape to leave Focus Mode). Then, navigate to the sidebar - press H to find "Labels" heading. After that, press Enter on the Labels gear/button. Finally, dropdown opens → ↑/↓ to navigate labels. It is like walking a hallway with named doors: read the sign, enter the right room, then confirm where you landed.

      -

      Jamie: Before we leave Assigning labels from the sidebar, what is the practical point?

      -

      Alex: First, enter to select/deselect. Then, escape to close (selections save automatically). After that, vO+Shift+Up to stop interacting with the text area. Finally, vO+U → Headings to find the "Labels" heading in the sidebar. The rhythm is simple: orient, act, verify, then continue.

      -

      Alex: A solid project habit is to treat metadata as decision support. Labels, status, assignees, and notifications tell you what kind of attention the work needs.

      -

      Jamie: Let's pause on Submitting the issue. What should a learner take away from it?

      -

      Alex: The reason Submitting the issue matters is that GitHub CLI (gh) alternative - filing a new issue. That gives the learner a simple foothold: create an issue from your terminal. The interface gets friendlier when it stops being a wall of controls and starts being a set of named places.

      -

      Alex: First, tab to "Submit new issue" button. Then, press Enter. The rhythm is simple: orient, act, verify, then continue.

      -

      Alex: Treat examples as spoken recipes, not decorations. You may hear something like 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. Read the command, understand what it changes, then run it only when the repository state matches the lesson.

      -

      Jamie: Let's pause on Learning Cards: Filing a New Issue. What should a learner take away from it?

      -

      Alex: Start with Learning Cards: Filing a New Issue. There is something to understand, something to try, and something that proves the try worked.

      -

      Alex: The practical takeaway is this. 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. 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.

      -
      -

      Jamie: Let's pause on Tool Cards: File a New Issue. What should a learner take away from it?

      -

      Alex: Here is the plain-English version of Tool Cards: File a New Issue. github.dev (web editor): Not available -- issues are managed through the repository's Issues tab, not the code editor. Put another way, VS Code Desktop (GitHub Pull Requests extension).

      -

      Alex: First, navigate to the repository's Issues tab (or press G then I). Then, click New issue, choose a template or blank issue. After that, fill in the title and description, then click Submit new issue. Finally, open the GitHub panel in the sidebar. Treat it like a recipe: do not add the next ingredient until the previous one is actually in the bowl.

      -

      Jamie: Before we leave Tool Cards: File a New Issue, what is the practical point?

      -

      Alex: First, under Issues, click the + icon to create a new issue. Then, fill in the title and body, then click Create. It is a checklist, but a meaningful one: every item creates evidence that the next step is safe.

      -

      Alex: Treat examples as spoken recipes, not decorations. You may hear something like gh issue create --title "Your title" --body "Description here"; Or interactively:; gh issue create. Read the command, understand what it changes, then run it only when the repository state matches the lesson.

      -

      Jamie: Let's pause on Cross-Referencing Issues. What should a learner take away from it?

      -

      Alex: This is where Cross-Referencing Issues becomes real: linking issues and PRs to each other creates a trail of context that helps everyone understand the project's history.

      -

      Alex: Keep the teaching thread moving. Keep the learner anchored in 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. A good GitHub workflow is like a well-run meeting: everyone knows the topic, the next action, and who has the floor.

      -
      -

      Jamie: Let's pause on Mentioning another issue in a comment. What should a learner take away from it?

      -

      Alex: The reason Mentioning another issue in a comment matters is that simply type followed by a number anywhere in a comment body. That gives the learner a simple foothold: GitHub autocompletes with a dropdown of matching issues and PRs.

      -

      Alex: Keep the teaching thread moving. Start with Cross-repo references: owner/repo 42 - references issue 42 in a different repository.

      -

      Jamie: Let's pause on Learning Cards: Cross-Referencing Issues. What should a learner take away from it?

      -

      Alex: Start with Learning Cards: Cross-Referencing Issues. There is something to understand, something to try, and something that proves the try worked.

      -

      Alex: The practical takeaway is this. 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. 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.

      +

      Jamie: Let's pause on Step 7: Locate the Heading Line and Add an Inline Comment. What should a learner take away from it?

      +

      Alex: Start with Step 7: Locate the Heading Line and Add an Inline Comment. There is something to understand, something to try, and something that proves the try worked.

      +

      Alex: The practical takeaway is this. Use Ctrl+F to open Find. Search for to locate it quickly. Press Enter to jump to it. With keyboard: The comment button may appear on the current line; navigate to it and press Enter. A comment box opens. You can type your comment.

      +

      Alex: First, once you identified the problematic heading in the Accessible Diff Viewer, close the Accessible Diff Viewer (press F7 again or Alt+F2). Then, you're back in the regular Diff Editor. After that, find the line with the problematic heading. Finally, close Find (Escape). Treat it like a recipe: do not add the next ingredient until the previous one is actually in the bowl.

      +

      Jamie: Before we leave Step 7: Locate the Heading Line and Add an Inline Comment, what is the practical point?

      +

      Alex: First, place your cursor on that line. Then, right-click and select "Add Comment" or press the Comment icon that appears on the left margin. It is a checklist, but a meaningful one: every item creates evidence that the next step is safe.

      +

      Jamie: Let's pause on Step 8: Write Your Accessible Diff Comment. What should a learner take away from it?

      +

      Alex: This is where Step 8: Write Your Accessible Diff Comment becomes real: why mention the Accessible Diff Viewer?

      +

      Alex: The practical takeaway is this. It shows that the tool itself helps you see the issue. It documents how you caught the problem (useful for learning).

      +

      Alex: First, in the comment box, type. Then, press Ctrl+Enter or click Comment to submit. It is a checklist, but a meaningful one: every item creates evidence that the next step is safe.

      +

      Jamie: Let's pause on Step 9: Create a GitHub Pull Request Comment. What should a learner take away from it?

      +

      Alex: Keep the learner anchored in Step 9: Create a GitHub Pull Request Comment. Now you've reviewed the same PR in.

      +

      Alex: First, browser (Exercise A): You spot-checked line numbers manually. Then, VS Code (Exercise B): The Diff Editor plus Accessible Diff Viewer announced changes. After that, go to GitHub in your browser and open the same PR. Finally, scroll to the bottom and leave a comment in the Conversation tab. It is like walking a hallway with named doors: read the sign, enter the right room, then confirm where you landed.

      +

      Jamie: Before we leave Step 9: Create a GitHub Pull Request Comment, what is the practical point?

      +

      Alex: First, click Comment. The rhythm is simple: orient, act, verify, then continue.

      -

      Alex: Keep the teaching thread moving. This is where Sub-Issues - Parent and Child Relationships becomes real: sub-issues (released 2025) let you nest issues inside a parent issue to break large work into tracked pieces. That matters in practice: A "parent" issue contains a list of child issues; each child is a full issue with its own discussion, labels, and assignees. The workshop is closer to rehearsal than lecture. You hear the move, try the move, and then check what changed.

      -

      Jamie: Can you translate that into plain choices?

      -

      Alex: Start with When to Use Sub-Issues. There is something to understand, something to try, and something that proves the try worked.

      -

      Alex: Use the comparison to make a decision, not to recite a table. The main contrasts are: Large feature broken down means Parent: "Redesign navigation"; Children: "Keyboard nav," "Screen reader nav," "Mobile nav". Epic tracking means Parent: "WCAG 2.1 AA compliance"; Children: one issue per failing criterion. Release milestone means Parent: "v2.0 release"; Children: every required PR/fix.

      -

      Alex: Keep the teaching thread moving. The reason Creating a Sub-Issue matters is that the sub-issues section is announced as a region. That gives the learner a simple foothold: after linking, the child issue appears as a list item with a checkbox showing its open/closed state.

      +

      Jamie: Before we leave Reflect on This Exercise, what is the practical point?

      +

      Alex: The reason Reflect on This Exercise matters is that after completing Steps 1-9, answer. That gives the learner a simple foothold: in Chapter 16, you'll compare these manual reviews with the @pr-review agent's suggested changes. The interface gets friendlier when it stops being a wall of controls and starts being a set of named places.

      +

      Alex: First, announcement clarity: Did the "Added:" and "Removed:" labels from the Accessible Diff Viewer help you follow changes faster than reading + and − prefixes in the browser? Then, navigation pattern: Which tool required less back-and-forth clicking/tabbing to understand each change? After that, when would you use each? In one sentence: describe a type of PR where you'd prefer to use each tool. The rhythm is simple: orient, act, verify, then continue.

      +

      Jamie: Let's pause on Exercise C - Compare and Reflect. What should a learner take away from it?

      +

      Alex: Start with Exercise C - Compare and Reflect: Your Mission: Synthesize what you learned from the manual code reviews (Exercises A & B) and document your findings. The next useful detail is this: What You'll Learn: Which tools work best for different scenarios, and how your manual review skills prepare you to use AI agents effectively.

      +

      Alex: Keep the teaching thread moving. Here is the plain-English version of Step 1: Gather Your Data. Before writing your reflection, collect all the information you gathered. Put another way, write these down (in a text editor, on paper, or mentally) - you'll reference them in Steps 2-4.

      +

      Alex: The practical takeaway is this. Which line number had the heading hierarchy skip? Which line number had the link text issue? How many steps did it take to find each issue? Did you use screen reader commands or visual scanning more?

      -

      Jamie: Let's pause on Reading Sub-Issues on a Parent Issue. What should a learner take away from it?

      -

      Alex: Start with Reading Sub-Issues on a Parent Issue: Progress indicator: The parent issue shows a completion bar (e.g., "3 of 7 completed") based on how many child issues are closed. The next useful detail is this: Screen readers announce this as a progress region.

      -

      Alex: Keep the teaching thread moving. Here is the plain-English version of Viewing a Child Issue's Parent. Every child issue shows a "Parent issue" link near the top of the page (above the description). Put another way, navigate with H or links (K) to find it. It is like learning a transit route. The names of the stops matter because they tell you whether you are still going the right direction.

      -

      Jamie: Let's pause on Sub-Issues vs. Task Lists. What should a learner take away from it?

      -

      Alex: This is where Sub-Issues vs. Task Lists becomes real: if you are working on a feature that requires multiple PRs or involves several team members, ask the maintainer to create a parent issue. That matters in practice: You can then claim individual child issues without one person owning the whole feature.

      +

      Jamie: Let's pause on Step 2: Navigate to the PR and Leave Your Reflection Comment. What should a learner take away from it?

      +

      Alex: Start with Step 2: Navigate to the PR and Leave Your Reflection Comment. There is something to understand, something to try, and something that proves the try worked.

      +

      Alex: The practical takeaway is this. A text editing area with formatting options (Bold, Italic, Link, etc.). A Comment button below the text area.

      +

      Alex: First, go to GitHub in your browser. Then, open the same PR ("Add screen reader tips to the setup guide"). After that, scroll to the Conversation tab. Finally, scroll all the way down to the comment box at the bottom (labeled "Leave a comment" or "Add a comment"). It is a checklist, but a meaningful one: every item creates evidence that the next step is safe.

      +

      Jamie: Before we leave Step 2: Navigate to the PR and Leave Your Reflection Comment, what is the practical point?

      +

      Alex: First, click in the comment box. It is like walking a hallway with named doors: read the sign, enter the right room, then confirm where you landed.

      +

      Alex: Keep the teaching thread moving. Keep the learner anchored in Step 3: Write Your Comparison. Type your response to these three questions. This is the part to say slowly: Be specific - reference exact tools, steps, and what you discovered. A good GitHub workflow is like a well-run meeting: everyone knows the topic, the next action, and who has the floor.

      +

      Jamie: Let's pause on Step 4: Review Your Comment. What should a learner take away from it?

      +

      Alex: Start with Step 4: Review Your Comment. There is something to understand, something to try, and something that proves the try worked.

      +

      Alex: The practical takeaway is this. Is it clear which tool I preferred? Did I explain why with concrete examples? Am I describing the real-world impact accurately? Would someone else reading this understand how I caught the issue?

      +

      Alex: First, before submitting, re-read your comment using your screen reader or by reading aloud. Then, ask yourself. After that, make any corrections needed. Finally, do not submit yet - continue to Step 5. The rhythm is simple: orient, act, verify, then continue.

      -

      Alex: Keep the teaching thread moving. Start with Learning Cards: Sub-Issues. There is something to understand, something to try, and something that proves the try worked.

      -

      Alex: The practical takeaway is this. 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. 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.

      -

      Jamie: Let's pause on Closing an issue. What should a learner take away from it?

      -

      Alex: The reason Closing an issue matters is that scroll to the bottom of the issue page. That gives the learner a simple foothold: click the Close issue button next to the comment box.

      -

      Alex: First, 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. Then, button approach: Tab to the "Close issue" button (at the bottom of the page, near the comment box) and press Enter. After that, optionally leave a closing comment first. Finally, 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. The rhythm is simple: orient, act, verify, then continue.

      -

      Jamie: Before we leave Closing an issue, what is the practical point?

      -

      Alex: First, button approach: Quick Nav B or Tab to find the "Close issue" button, then VO+Space. Think of it as a rail line: each stop confirms you are still on the right route before the next one.

      -

      Alex: Treat examples as spoken recipes, not decorations. You may hear something like 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. Read the command, understand what it changes, then run it only when the repository state matches the lesson.

      -

      Alex: Keep the teaching thread moving. Start with Reopening a closed issue: If an issue is Closed, the "Close issue" button becomes "Reopen issue" - navigate and activate to reopen. Think of it like entering a new building: first you find the lobby, then the room, then the door you actually need.

      +

      Jamie: Let's pause on Step 5: Submit Your Reflection. What should a learner take away from it?

      +

      Alex: Start with Step 5: Submit Your Reflection. There is something to understand, something to try, and something that proves the try worked.

      +

      Alex: The practical takeaway is this. Your comment is now visible on the PR. Other reviewers can see your comparison. You have completed the three-part exercise series. Your comment appears on the PR thread. It includes all three reflections. The PR author and other reviewers can see your thought process.

      +

      Alex: First, locate the Comment button at the bottom right of the comment box. Then, with keyboard: Press Tab until the Comment button is focused, then Enter. After that, with mouse: Click the Comment button. Finally, your comment is submitted and appears on the PR page. Think of it as a rail line: each stop confirms you are still on the right route before the next one.

      +

      Jamie: Let's pause on Step 6: Checkpoint - Validate Your Learning. What should a learner take away from it?

      +

      Alex: Here is the plain-English version of Step 6: Checkpoint - Validate Your Learning. Before moving forward, verify you understand. Put another way, if you can answer all three, you're ready for the next chapter.

      +

      Alex: The practical takeaway is this. Expected answer: Something like "Screen readers let users navigate by heading level (pressing 3 jumps to H3), so skipping a level makes users think content is missing.". Expected answer: e.g., "Browser: finding context in discussions. VS Code: linear reading of changes.". Expected answer: Something like "Open the document in a browser, use screen reader heading navigation, and confirm I can reach all levels (H2, H3, H4).".

      +

      Alex: First, heading Hierarchy: Can you explain in one sentence why a → skip breaks screen reader navigation? Then, tool Strengths: For each tool you used, name one task it made easier. After that, real-World Testing: How would you test the heading issue in the published document (not the PR diff)? Treat it like a recipe: do not add the next ingredient until the previous one is actually in the bowl.

      +

      Alex: Keep the teaching thread moving. This is where Using GitHub Copilot to Understand Code Changes becomes real: reviewing code is about understanding what changed, why it changed, and whether the change is safe and correct. That matters in practice: GitHub Copilot can help you gather and understand information about code changes - especially when diffs are large, complex, or involve unfamiliar frameworks. The workshop is closer to rehearsal than lecture. You hear the move, try the move, and then check what changed.

      -

      Jamie: Let's pause on Assigning an issue. What should a learner take away from it?

      -

      Alex: Here is the plain-English version of Assigning an issue. GitHub CLI (gh) alternative - assigning and labeling. Put another way, manage assignments and labels from your terminal.

      -

      Alex: First, navigate to "Assignees" heading (3 or H). Then, activate the gear/plus button. After that, type a username in the search field. Finally, select from the dropdown. Treat it like a recipe: do not add the next ingredient until the previous one is actually in the bowl.

      -

      Alex: Treat examples as spoken recipes, not decorations. You may hear something like 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". Read the command, understand what it changes, then run it only when the repository state matches the lesson.

      -

      Jamie: Let's pause on Changing labels. What should a learner take away from it?

      -

      Alex: Start with Changing labels. There is something to understand, something to try, and something that proves the try worked.

      -

      Alex: First, navigate to "Labels" heading. Then, activate the gear button. After that, select/deselect labels from the dropdown. Finally, press Escape to save. It is a checklist, but a meaningful one: every item creates evidence that the next step is safe.

      -

      Jamie: Let's pause on Transferring or deleting an issue. What should a learner take away from it?

      -

      Alex: Keep the learner anchored in Transferring or deleting an issue. Available from the "." (ellipsis) button at the top of the issue - navigate buttons with B to find it.

      +

      Jamie: Let's pause on When to Use Copilot During Code Review. What should a learner take away from it?

      +

      Alex: Keep the learner anchored in When to Use Copilot During Code Review. Copilot is most useful for answering these questions.

      +

      Alex: First, "What does this code do?" - you're reading unfamiliar syntax or a framework you don't know well. Then, "Why might this change break something?" - you need to understand dependencies or side effects. After that, "Is this pattern safe?" - you want to verify that the approach follows best practices. Finally, "What would be a better way to write this?" - you're looking for alternatives to suggest. It is like walking a hallway with named doors: read the sign, enter the right room, then confirm where you landed.

      +

      Jamie: Before we leave When to Use Copilot During Code Review, what is the practical point?

      +

      Alex: First, "Does this match the PR's description?" - the change seems to do more (or less) than claimed. The rhythm is simple: orient, act, verify, then continue.

      +

      Jamie: Let's pause on In VS Code with an Open Diff. What should a learner take away from it?

      +

      Alex: Start with In VS Code with an Open Diff. There is something to understand, something to try, and something that proves the try worked.

      +

      Alex: First, open the PR using the GitHub Pull Requests extension (see Part 2). Then, open the diff for any file. After that, select a block of code that confuses you (highlight it). Finally, open Copilot Chat: Ctrl+Shift+I. The rhythm is simple: orient, act, verify, then continue.

      +

      Jamie: Before we leave In VS Code with an Open Diff, what is the practical point?

      +

      Alex: First, Copilot reads the selected code and answers in the chat. Think of it as a rail line: each stop confirms you are still on the right route before the next one.

      +

      Jamie: Let's pause on On GitHub.com (Web Interface). What should a learner take away from it?

      +

      Alex: Start with On GitHub.com (Web Interface): Another option: Use the GitHub Copilot inline suggestions on GitHub.com.

      +

      Alex: The practical takeaway is this. Some GitHub PRs show Copilot insights directly in the diff (as of early 2026). If you see a lightbulb icon, click it to see Copilot's suggestion about that line.

      +

      Alex: First, open the PR's Files Changed tab. Then, focus on a line or section you want to understand better. After that, in VS Code Copilot Chat (not in the browser - Copilot Chat doesn't work directly in browser diffs yet). Finally, copy the confusing code, paste it into chat, and ask Copilot to explain. Think of it as a rail line: each stop confirms you are still on the right route before the next one.

      -

      Alex: Keep the teaching thread moving. Start with Learning Cards: Managing Issues. There is something to understand, something to try, and something that proves the try worked.

      -

      Alex: The practical takeaway is this. 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. 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.

      -

      Jamie: Let's pause on The "good first issue" Label - Your Entry Point. What should a learner take away from it?

      -

      Alex: Start with The "good first issue" Label - Your Entry Point: When looking for your first open source contribution. The next useful detail is this: Remember: It's respectful to ask before starting.

      -

      Alex: First, navigate to any project's Issues tab. Then, filter by label: type is:open label:"good first issue" in the search. After that, read through issues until you find one in your area of interest. Finally, comment on the issue: "Hi, I'd like to work on this. Can I be assigned?". Think of it as a rail line: each stop confirms you are still on the right route before the next one.

      -

      Jamie: Before we leave The "good first issue" Label - Your Entry Point, what is the practical point?

      -

      Alex: First, wait for a maintainer to respond and assign you before starting work. Treat it like a recipe: do not add the next ingredient until the previous one is actually in the bowl.

      -

      Alex: Keep the teaching thread moving. Start with Learning Cards: The "good first issue" Label. There is something to understand, something to try, and something that proves the try worked.

      -

      Alex: The practical takeaway is this. 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. 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.

      +

      Alex: Keep the teaching thread moving. Here is the plain-English version of Copilot Limitations During Review (Critical to Know). This is why manual review is essential: You have context (project history, team decisions, user impact) that Copilot does not. Put another way, use Copilot to understand, then use your judgment to decide. It is like learning a transit route. The names of the stops matter because they tell you whether you are still going the right direction.

      +

      Alex: The practical takeaway is this. See the whole project - it sees only what you show it (the selected diff, not the context of the entire codebase). Verify correctness - it can explain what code does, but not whether it's correct for your specific use case. Understand intent - it reads the code, not the author's mind or the PR description. Catch all risks - it can spot common patterns, but not edge cases unique to your project.

      +

      Jamie: Let's pause on Best Practices. What should a learner take away from it?

      +

      Alex: Start with Best Practices. There is something to understand, something to try, and something that proves the try worked.

      +

      Alex: First, read the diff manually first - you spot the big picture before asking Copilot details. Then, ask Copilot specific questions - not "review this code" but "does this regex handle Unicode?". After that, fact-check Copilot's answers - it can be confidently wrong, especially about frameworks or domains it has less training data. Finally, combine Copilot with manual analysis - ask Copilot to explain, then verify by checking the PR description or looking for related files. It is a checklist, but a meaningful one: every item creates evidence that the next step is safe.

      +

      Jamie: Before we leave Best Practices, what is the practical point?

      +

      Alex: First, use Copilot to draft comments - type Draft a comment about [issue] for this PR and edit Copilot's suggestion to match your tone. It is like walking a hallway with named doors: read the sign, enter the right room, then confirm where you landed.

      +

      Alex: Keep the teaching thread moving. Keep the learner anchored in What Comes Next. Your manual code review skills - identifying heading issues, catching link text problems, understanding screen reader navigation, gathering information with Copilot - are the foundation for understanding automated review. This is the part to say slowly: In Chapter 16 (Accessibility Agents), you'll meet a full team of agents designed to amplify these skills.

      -

      Jamie: Let's pause on Accessibility-Specific Issue Writing Tips. What should a learner take away from it?

      -

      Alex: This is where Accessibility-Specific Issue Writing Tips becomes real: when filing accessibility bugs, these details help maintainers reproduce and fix the problem.

      -

      Alex: First, screen reader and version - "NVDA 2025.3.3" not just "screen reader". Then, oS and version - "Windows 11 22H2". After that, browser and version - "Chrome 124.0.6367.82". Finally, GitHub interface - "Modern experience (default since Jan 2026)" or "Classic experience (opted out)". It is a checklist, but a meaningful one: every item creates evidence that the next step is safe.

      -

      Jamie: Before we leave Accessibility-Specific Issue Writing Tips, what is the practical point?

      -

      Alex: First, what was announced - quote the exact text your screen reader spoke. Then, what should have been announced - describe the expected behavior. After that, aRIA issue if known - e.g., "The button has no accessible name". Finally, steps to reproduce - numbered, step-by-step. It is like walking a hallway with named doors: read the sign, enter the right room, then confirm where you landed.

      -

      Alex: Keep the teaching thread moving. Start with Example of a well-filed accessibility issue. There is something to understand, something to try, and something that proves the try worked.

      -

      Jamie: Let's pause on Learning Cards: Accessibility-Specific Issue Writing. What should a learner take away from it?

      -

      Alex: Start with Learning Cards: Accessibility-Specific Issue Writing. There is something to understand, something to try, and something that proves the try worked.

      -

      Alex: The practical takeaway is this. 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. 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.

      +

      Jamie: Let's pause on Part 4: The Reviewer's Craft. What should a learner take away from it?

      +

      Alex: The reason The Reviewer's Craft matters is that parts 1 through 3 taught you the mechanics -- how to read diffs, leave comments, and use Copilot to understand unfamiliar code. That gives the learner a simple foothold: this part covers something equally important: how to think like a reviewer.

      +

      Alex: Keep the teaching thread moving. Start with What to Look for in a Review: Every PR is different, but most reviews benefit from scanning across these five categories. The next useful detail is this: You do not need to check every category exhaustively on every PR. Think of it like entering a new building: first you find the lobby, then the room, then the door you actually need.

      +

      Jamie: Let's pause on The Three Review Actions. What should a learner take away from it?

      +

      Alex: Here is the plain-English version of The Three Review Actions. When you submit a review on GitHub, you choose one of three actions. Put another way, picking the right one matters because it signals your intent to the author and to anyone else watching the PR.

      +

      Alex: First, did you find a bug, security issue, or broken test? -- Request Changes. Then, does the code do something different from what the description says? -- Request Changes. After that, does everything work, with maybe a few style nits? -- Approve (mention the nits in a comment). Finally, do you have questions or optional suggestions? -- Comment. Treat it like a recipe: do not add the next ingredient until the previous one is actually in the bowl.

      -

      Alex: Keep the teaching thread moving. Start with Writing Effective Issues: See also: Appendix N: Advanced Search covers search qualifiers to find existing issues before filing a new one. The next useful detail is this: 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.

      -

      Jamie: Let's pause on Bug Report Structure. What should a learner take away from it?

      -

      Alex: Here is the plain-English version of Bug Report Structure. A strong bug report answers five questions. Put another way, use this template every time you report something broken.

      -

      Jamie: Let's pause on Feature Request Structure. What should a learner take away from it?

      -

      Alex: This is where Feature Request Structure becomes real: feature requests work best when they focus on the problem before jumping to the solution. That matters in practice: 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. The workshop is closer to rehearsal than lecture. You hear the move, try the move, and then check what changed.

      -

      Alex: First, problem statement -- Describe the pain point. What are you trying to do, and why is it hard or impossible right now? Then, proposed solution -- Your best idea for fixing the problem. Be specific enough to discuss, but hold it loosely. After that, alternatives considered -- Other approaches you thought about and why they fell short. This shows you have done your homework. Finally, who benefits -- Name the audience. "Screen reader users navigating large repositories" is more compelling than "everyone.". It is a checklist, but a meaningful one: every item creates evidence that the next step is safe.

      +

      Alex: Keep the teaching thread moving. This is where Writing Constructive Feedback becomes real: the way you phrase feedback determines whether the author feels supported or attacked. That matters in practice: Before pointing out problems, acknowledge something the author did well.

      +

      Jamie: Let's pause on The Reviewer's Checklist. What should a learner take away from it?

      +

      Alex: Keep the learner anchored in The Reviewer's Checklist. Run through this list mentally (or copy it into your notes) for every PR you review.

      +

      Alex: The practical takeaway is this. [ ] I read the PR description before reading the code. [ ] The code does what the description says it does. [ ] The change does not include unrelated modifications. [ ] Variable and function names are clear. [ ] I checked for accessibility: labels, headings, keyboard reach, contrast. [ ] I verified no existing behavior is broken by the change.

      +

      Alex: Keep the teaching thread moving. The reason Reviewing as a Learning Tool matters is that reviewing is not just a gate to keep bad code out. That gives the learner a simple foothold: it is one of the fastest ways to grow as a developer. The interface gets friendlier when it stops being a wall of controls and starts being a set of named places.

      -

      Jamie: Let's pause on General Issue Writing Principles. What should a learner take away from it?

      -

      Alex: Keep the learner anchored in General Issue Writing Principles. These rules apply to every issue -- bugs, features, questions, and everything in between. This is the part to say slowly: If you discovered two bugs during the same session, file two separate issues.

      -

      Alex: Keep the teaching thread moving. The reason Before and After: A Vague Issue vs. a Clear Issue matters is that I tried clicking and nothing happened. That gives the learner a simple foothold: the maintainer has to ask: What doesn't work?

      -

      Jamie: Let's pause on Learning Cards: Writing Effective Issues. What should a learner take away from it?

      -

      Alex: Start with Learning Cards: Writing Effective Issues. There is something to understand, something to try, and something that proves the try worked.

      -

      Alex: The practical takeaway is this. 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. 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.

      +

      Jamie: Let's pause on Learning Cards: The Reviewer's Craft. What should a learner take away from it?

      +

      Alex: Start with Learning Cards: The Reviewer's Craft. There is something to understand, something to try, and something that proves the try worked.

      +

      Alex: The practical takeaway is this. Jump between changed hunks in a diff with Alt+F5 (next change) and Shift+Alt+F5 (previous change) to scan for scope creep efficiently. Use Alt+F2 (Accessible View) on a Copilot-generated review summary to read the full text with arrow keys before posting. When leaving feedback, mention specific line numbers ("Line 42 skips from h2 to h4") so the author can navigate directly with Ctrl+G. The three review actions (Approve, Request Changes, Comment) are shown as clearly labeled radio buttons in the review submission form. Use the reviewer checklist in this section as a mental framework -- copy it into your notes and check items off as you review each PR. The diff view uses green and red backgrounds for added/removed lines; pair with a High Contrast theme if these colors are hard to distinguish.

      +

      Alex: Keep the teaching thread moving. Here is the plain-English version of Day 2 Teaser: The Full Accessibility Agents Review Ecosystem. Chapter 16 shows you how to leverage 50+ specialized agents to make your reviews faster, more consistent, and more thorough - while staying in full control of what you post.

      +

      Jamie: What is the calm recovery move here?

      +

      Alex: This is where The Agents That Help With Code Review becomes real: accessibility Review Agents (when code affects UI/UX).

      +

      Alex: The practical takeaway is this. @pr-review - Generates a full-draft PR review with line-numbered diff maps, risk assessment, before/after snapshots, and suggested inline comments. You edit and post it under your name. @pr-author-checklist - Before you even submit your PR, use this to verify you haven't missed setup steps, accessibility checks, or documentation. @insiders-a11y-tracker - Monitors your PR for accessibility-sensitive changes: WCAG violations, heading hierarchy issues, link text quality, keyboard navigation impacts. @developer-hub - Orchestrates explanations for unfamiliar code, patterns, or frameworks you're reviewing. @python-specialist - If your PR contains Python code, this agent explains patterns, spots accessibility issues, and suggests improvements. @wxpython-specialist - For desktop GUI code, helps verify accessible widget patterns and focus management.

      -

      Jamie: Let's pause on Try It: File Your First Issue. What should a learner take away from it?

      -

      Alex: Here is the plain-English version of Try It: File Your First Issue. Time: 3 minutes What you need: Browser, signed in to GitHub. Put another way, go to the Learning Room repository and file a real issue. It is like learning a transit route. The names of the stops matter because they tell you whether you are still going the right direction.

      -

      Alex: First, navigate to the Issues tab (press G then I in Focus Mode). Then, find and activate the "New issue" button (K to links, or Tab to it). After that, in the title field, type: "Introduce myself - [Your Name]". Finally, in the description, write 2-3 sentences: who you are, what screen reader you use, and one thing you're hoping to learn today. Treat it like a recipe: do not add the next ingredient until the previous one is actually in the bowl.

      -

      Jamie: Before we leave Try It: File Your First Issue, what is the practical point?

      -

      Alex: First, press Ctrl+Enter to submit (or Tab to the Submit button and press Enter). It is a checklist, but a meaningful one: every item creates evidence that the next step is safe.

      -

      Jamie: Let's pause on Learning Cards: Filing Your First Issue. What should a learner take away from it?

      -

      Alex: This is where Learning Cards: Filing Your First Issue becomes real: day 2 Amplifier - Accessibility Agents: @issue-tracker File, read, comment on, and triage real issues manually before using any agent. That matters in practice: 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.

      -

      Alex: The practical takeaway is this. 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. 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.

      +

      Jamie: Let's pause on How It Works. What should a learner take away from it?

      +

      Alex: Start with How It Works. There is something to understand, something to try, and something that proves the try worked.

      +

      Alex: First, review manually first (you just did this with Exercises A, B, C). Then, run an agent - @pr-review review PR 14 generates a draft in seconds. After that, edit the agent's draft - you add context, remove noise, correct errors. Finally, post your review - it now has both AI efficiency and your human judgment. It is like walking a hallway with named doors: read the sign, enter the right room, then confirm where you landed.

      +

      Jamie: Before we leave How It Works, what is the practical point?

      +

      Alex: First, the agent tracks impact - @insiders-a11y-tracker monitors whether your accessibility feedback was addressed. The rhythm is simple: orient, act, verify, then continue.

      +

      Jamie: Let's pause on The Principle: Skill First, Agent Second. What should a learner take away from it?

      +

      Alex: The reason The Principle: Skill First, Agent Second matters is that why do this manually before using agents? That gives the learner a simple foothold: manual reviews teach you what to look for.

      +

      Alex: The practical takeaway is this. You understand what the agent is doing (you did it manually). You evaluate the agent's output critically (you know what right looks like). You add judgment the agent lacks (context, intent, team decisions). You verify the agent didn't miss anything important.

      +

      Jamie: Let's pause on A Real Example: The Flow. What should a learner take away from it?

      +

      Alex: Start with A Real Example: The Flow: Manual Review (your work in part 1-2). The next useful detail is this: Agent-Assisted Review (what you'll do in Chapter 19).

      +

      Alex: The practical takeaway is this. Read diff, identify heading hierarchy skip. Write comment explaining why it matters. Submit your verdict.

      +

      Alex: First, run: @pr-review review PR 14. Then, agent generates a draft review covering the heading skip, link text, and 5 other issues. After that, you read the draft and notice: "the agent's explanation of the heading skip is good, but it missed that the link text on line 23 is still vague. Let me add that.". Finally, you post the agent's review + your additions. Think of it as a rail line: each stop confirms you are still on the right route before the next one.

      +

      Jamie: Before we leave A Real Example: The Flow, what is the practical point?

      +

      Alex: First, next time you review a similar PR, the agent works faster because it learned from your feedback. Treat it like a recipe: do not add the next ingredient until the previous one is actually in the bowl.

      Jamie: What is the final checkpoint?

      Alex: You should be able to point to the evidence, explain the action, and describe what you would do next if this were a real open source project. If you can teach the move back, you have learned it.

      @@ -12200,1088 +12499,970 @@

      Transcript

      -

      Challenge 03: Join the Conversation

      -

      Comments, mentions, reactions, and constructive peer communication.

      +

      40. Challenge 12: Review Like a Pro

      +

      Reviewing a classmate PR, leaving specific feedback, and owning review tone.

      +

      Practice focus: Day 2 local workflow

      +

      Audio and transcript are being regenerated for this episode.

      -Read Transcript - Challenge 03: Join the Conversation +Read Transcript - Challenge 12: Review Like a Pro

      Transcript

      -

      Alex: You are listening to Challenge Coach: Join the Conversation. I am Alex, and this is the calm walkthrough before the hands-on work.

      -

      Jamie: And I am Jamie. I will make sure we teach the skill instead of just reading the checklist aloud.

      +

      Alex: Welcome to Challenge Coach: Review Like a Pro. I am Alex. Before you do the task, we are going to make the skill feel concrete enough to practice.

      +

      Jamie: And I am Jamie. I will keep asking what the learner should do, what evidence counts, and how to recover if the page does something unexpected.

      -

      Alex: The focus is Comments, mentions, reactions, and constructive peer communication. We will explain the concept, the action, the evidence, and the most common recovery path.

      -

      Jamie: So the learner needs the why, the move, and the checkpoint all in the same mental pocket.

      -

      Alex: That is the teaching shape: understand the concept, do the smallest real action, then verify the result before moving on.

      +

      Alex: The skill focus is Reviewing a classmate PR, leaving specific feedback, and owning review tone. This is rehearsal for real contribution, so the evidence matters because it proves the move happened.

      +

      Jamie: So the challenge has to leave the learner with both confidence and a trail of evidence.

      +

      Alex: Exactly. Evidence is not busywork. It is how a learner, a facilitator, and a future maintainer can understand what changed and why.

      Jamie: What makes this practice feel low-stakes but still real?

      -

      Alex: Start with Challenge 3: Join the Conversation: What you will do: Practice GitHub's collaboration features by commenting on a peer-simulation issue, using @mentions, and adding reactions.

      +

      Alex: Start with Challenge 12: Review Like a Pro: What you will do: Give the peer-simulation PR a thorough code review with inline comments, a suggestion, and a verdict. The next useful detail is this: If your facilitator gave you access to a real buddy's PR, you may review that PR instead.

      +

      Alex: A solid pull request habit is to separate three questions: what changed, why it changed, and what still needs review. That keeps the conversation useful instead of noisy.

      Jamie: How would you walk the room through that step by step?

      Alex: Start with Instructions. There is something to understand, something to try, and something that proves the try worked.

      -

      Alex: The practical anchors are these. Confirm you can reproduce the problem they described. Suggest an approach to fix it. Ask a clarifying question.

      -

      Alex: First, open the Peer Simulation: Welcome Link Needs Context issue in this repository. If your facilitator gave you access to a real buddy repository, you may use your buddy's Challenge 2 issue instead. Then, leave a meaningful comment on their issue. Ideas. After that, use an @mention in your comment. For the simulation, mention @aria-bot. For a real buddy repository, mention your buddy's username. Finally, add a reaction to the original issue. Treat it like a recipe: do not add the next ingredient until the previous one is actually in the bowl.

      +

      Alex: The practical anchors are these. One specific observation about something they did well. One constructive suggestion for improvement.

      +

      Alex: First, open the Peer Simulation: Improve contribution guidance PR. If you have real buddy access, you may open your buddy's Day 2 PR instead. Then, go to the Files changed tab. After that, review the changes and leave at least two inline comments. Finally, use the Suggest changes feature for at least one of your comments (select the +/- icon in the comment toolbar to create a code suggestion block). Treat it like a recipe: do not add the next ingredient until the previous one is actually in the bowl.

      +

      Jamie: What does the learner do first, second, and then after that?

      +

      Alex: First, submit your review with a verdict: Approve, Request changes, or Comment. It is a checklist, but a meaningful one: every item creates evidence that the next step is safe.

      Jamie: What is the one idea that makes the next few steps less mysterious?

      -

      Alex: This is where Good commenting tips becomes real: I commented on the peer-simulation issue about.

      -

      Alex: That shows up in the workshop in a few specific ways. Be specific ("I found the same TODO on line 12" is better than "I agree"). Be encouraging ("Great find!" is always welcome). Be constructive (suggest, do not just criticize).

      +

      Alex: Start with Review checklist. There is something to understand, something to try, and something that proves the try worked.

      +

      Alex: That shows up in the workshop in a few specific ways. [ ] Does the change do what the PR description says? [ ] Is the commit message clear? [ ] Are there any typos or formatting issues? [ ] Would someone reading this file for the first time understand the changes? [ ] Is the content accessible (clear language, proper Markdown formatting)?

      -

      Alex: Now bring the learner back to the room. Keep the learner anchored in Peer simulation check. If your facilitator gave you a real buddy, check whether they commented on your issue and reply. This is the part to say slowly: Otherwise, reply to Aria or to your own peer-simulation comment with one follow-up thought.

      +

      Alex: Now bring the learner back to the room. Start with The three verdicts. There is something to understand, something to try, and something that proves the try worked.

      Jamie: What would you say to someone who is already bracing for this to be too much?

      -

      Alex: The reason Your comment (on a buddy's issue) matters is that good catch on the missing link in welcome.md! That gives the learner a simple foothold: @maria-student Have you also noticed the TODO on line 28?

      -

      Alex: A solid issue habit is to read the title, the body, and the timeline before acting. You are listening for the requested action, the missing evidence, and the person who needs a response.

      -

      Alex: That matters because of the next idea. Start with Buddy's reply: @your-username Thanks for pointing that out! The next useful detail is this: Let me update my issue description to cover both TODOs. Think of it like entering a new building: first you find the lobby, then the room, then the door you actually need.

      +

      Alex: The reason Peer simulation check matters is that read any review comments on your PR. That gives the learner a simple foothold: if you do not have real buddy access, reply to a comment on the peer-simulation PR with one thing you learned.

      Alex: The useful habit is simple: orient first, act second, verify third. That pause before acting is part of the work.

      +

      Alex: That matters because of the next idea. Start with Inline comment (on a specific line): Line 18 of docs/welcome.md: This heading says " getting started" but the other headings in the file use title case (" What You Will Learn"). The next useful detail is this: Consider changing it to " Getting Started" for consistency. Think of it like entering a new building: first you find the lobby, then the room, then the door you actually need.

      Jamie: Okay, set the room for us. What are we walking into?

      -

      Alex: Start with What makes a good comment. There is something to understand, something to try, and something that proves the try worked.

      -

      Alex: Here is what that changes in practice. Specific reference: Mention what you are responding to (line numbers, file names). Constructive tone: Add information or ask questions rather than just agreeing. @mention: Tag the person you are talking to so they get notified. Actionable: Your comment helps move the conversation forward.

      -

      Alex: This is where the talk moves from concept to action. Start with Alternate approaches. There is something to understand, something to try, and something that proves the try worked.

      -

      Alex: The room should hear these as checkpoints. Comment on an issue someone else filed. Reply to a comment on your own issue. Ask a clarifying question about someone else's proposed change.

      -

      Alex: A solid pull request habit is to separate three questions: what changed, why it changed, and what still needs review. That keeps the conversation useful instead of noisy.

      +

      Alex: Here is the plain-English version of Suggestion (using GitHub's suggestion feature). Using the suggestion feature lets the PR author accept the change with one click, which creates a commit automatically.

      +

      Alex: This is where the talk moves from concept to action. This is where Review verdict becomes real: changes requested Good work overall. That matters in practice: The content additions are helpful and well-written.

      Jamie: Where do you want a learner to place their attention here?

      -

      Alex: Keep the learner anchored in What matters. The learning objective is participating in asynchronous collaboration. This is the part to say slowly: A single thoughtful comment with an @mention is sufficient evidence.

      +

      Alex: Start with Types of review comments. There is something to understand, something to try, and something that proves the try worked.

      +

      Alex: These are the details that keep the idea from floating away. Praise: "This section reads really clearly" -- positive feedback encourages good practices. Question: "What happens if the user does not have a GitHub account yet?" -- surfaces assumptions. Suggestion: Use the suggestion block to propose specific text changes. Required change: "The YAML frontmatter is missing the description field, which is required".

      -

      Alex: Before the learner moves on. The reason Filing, Managing, and Participating in GitHub Issues matters is that issues are where open source collaboration begins. That gives the learner a simple foothold: everything from finding the right issue to file a perfect bug report - all with your keyboard and screen reader. The interface gets friendlier when it stops being a wall of controls and starts being a set of named places.

      -

      Jamie: How should they picture the shape of the workshop?

      -

      Alex: Start with Workshop Recommendation (Chapter 5 / Challenges 2-3): Chapter 5 is the first issue-based challenge chapter with short, confidence-building tasks. The next useful detail is this: It supports Challenge 2 (File Your First Issue) and Challenge 3 (Join the Conversation).

      -

      Alex: A few details make that real. There are 2 core challenges plus one optional extension. Each challenge should take under 10 minutes. The evidence is issue comments and issue metadata. The pattern is claim - act - confirm.

      -

      Jamie: What does the learner do first, second, and then after that?

      -

      Alex: Here is the plain-English version of Chapter 5 Challenge Set. Chapter 5 focuses on issue skills. Put another way, you do NOT need to create a branch or edit any files for these challenges.

      -

      Alex: First, create your first issue - file a new issue with a clear title and description. Then, comment and @mention - leave a comment on a classmate's issue and tag them with an @mention. After that, optional extension: Add a sub-issue - break a larger issue into smaller, trackable pieces if your repository has sub-issues enabled. Treat it like a recipe: do not add the next ingredient until the previous one is actually in the bowl.

      +

      Alex: Before the learner moves on. The reason What matters matters is that the learning objective is providing constructive feedback on someone else's work. That gives the learner a simple foothold: if you left at least one specific, helpful comment on a buddy's PR, you completed this challenge. The interface gets friendlier when it stops being a wall of controls and starts being a set of named places.

      +

      Jamie: Give me the version that sounds like an instructor, not a manual.

      +

      Alex: Start with The GitHub Pull Requests Extension: See also: Appendix G: VS Code Reference for the complete list of GitHub Pull Requests extension keyboard shortcuts.

      +

      Alex: Hold that next to this. Here is the plain-English version of 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,. Put another way, prerequisites: Working with Pull Requests, Git & Source Control in VS Code Mac keyboard shortcuts: Throughout this chapter, all Ctrl+ shortcuts use Cmd+ on Mac, and Alt+ shortcuts use Option+ on Mac.

      +

      Jamie: What should feel predictable before the first live session starts?

      +

      Alex: This is where Workshop Recommendation (Chapter 15, Part 1) becomes real: chapter 15, Part 1 introduces the GitHub Pull Requests extension for managing PRs directly from VS Code.

      +

      Alex: For a learner, the useful signals are these. There are 2 guided challenges. Automation check: none (extension installation and review state are account-local). The evidence is issue comment with confirmation of actions completed. The pattern is install, check out, review, comment.

      Jamie: Turn that into a path someone can follow.

      -

      Alex: This is where Challenge 2 Step-by-Step: Create Your First Issue becomes real: file a new issue in your Learning Room repository with a specific title and a meaningful description. That matters in practice: Issues are the prompts that wake up AI.

      -

      Alex: For a learner, the useful signals are these. "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". What the problem is or what content is missing.

      -

      Alex: First, open your Learning Room repository in your browser. Then, navigate to the Issues tab (press G then I to jump there with keyboard shortcuts, or find the "Issues" link in the repository navigation). After that, activate the New issue button. Finally, if a template picker appears, select Open a blank issue (or choose a template if one fits). It is a checklist, but a meaningful one: every item creates evidence that the next step is safe.

      +

      Alex: Start with Chapter 15, Part 1 Practice Set. There is something to understand, something to try, and something that proves the try worked.

      +

      Alex: First, install the GitHub Pull Requests extension - add the extension to VS Code and sign in with your GitHub account. Then, check out a PR and post a review comment - download a PR branch locally, read the diff, and post one constructive review comment. It is like walking a hallway with named doors: read the sign, enter the right room, then confirm where you landed.

      Jamie: What is the ordered workflow?

      -

      Alex: First, in the Title field, type a clear, specific title (at least 12 characters). Then, in the Body field, write a meaningful description (at least 80 characters). After that, activate Submit new issue. Finally, copy the issue URL or note the issue number (for example, 150). You will reference this later. It is like walking a hallway with named doors: read the sign, enter the right room, then confirm where you landed.

      +

      Alex: The reason Practice 15.1 Step-by-Step: Install the Extension matters is that install the GitHub Pull Requests and Issues extension and authenticate with your GitHub account. That gives the learner a simple foothold: VS Code desktop with your Learning Room repository open.

      +

      Alex: First, open the Extensions sidebar: Ctrl+Shift+X (Mac: Cmd+Shift+X). Then, your screen reader announces "Extensions: Marketplace." The search box has focus. After that, type GitHub Pull Requests in the search box and press Enter. Finally, navigate down the results list. Select GitHub Pull Requests (publisher: GitHub). The rhythm is simple: orient, act, verify, then continue.

      Jamie: Give me the sequence, because order matters here.

      -

      Alex: Keep the learner anchored in Challenge 4.2 Step-by-Step: Comment and @Mention. Leave a comment on another student's issue and use an @mention to notify them. This is the part to say slowly: the Issues tab of your Learning Room repository on GitHub.com. A good GitHub workflow is like a well-run meeting: everyone knows the topic, the next action, and who has the floor.

      -

      Alex: The parts worth keeping in working memory are these. "@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.".

      -

      Alex: First, open the Issues tab in your Learning Room repository. Then, find an issue created by a classmate (look for issues from Challenge 4.1, or browse recent open issues). After that, open the issue by activating its title link. Finally, read the issue description to understand what they reported. It is like walking a hallway with named doors: read the sign, enter the right room, then confirm where you landed.

      -

      Jamie: Let's pause on Challenge 4.2 Step-by-Step: Comment and @Mention. What should a learner take away from it?

      -

      Alex: First, scroll to the comment box at the bottom of the issue. Then, write a helpful comment that @mentions the issue author by username. After that, activate the Comment button (or press Ctrl+Enter). The rhythm is simple: orient, act, verify, then continue.

      -

      Jamie: Let's pause on Challenge 4.3 Step-by-Step: Add a Sub-Issue. What should a learner take away from it?

      -

      Alex: The reason Challenge 4.3 Step-by-Step: Add a Sub-Issue matters is that break a larger issue into smaller, trackable pieces using GitHub's sub-issue feature. That gives the learner a simple foothold: the issue you created in Challenge 4.1 (or any open issue you have permission to edit).

      -

      Alex: On the ground, that means a few things. Sub-issue: "Add alt text to welcome banner image". Sub-issue: "Fix heading hierarchy in Getting Started section".

      -

      Alex: First, open the issue you created in Challenge 4.1. Then, 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. After that, activate Add sub-issue and choose Create new sub-issue. Finally, 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". The rhythm is simple: orient, act, verify, then continue.

      -

      Jamie: Before we leave Challenge 4.3 Step-by-Step: Add a Sub-Issue, what is the practical point?

      -

      Alex: First, add a short description and activate Create. Then, the sub-issue now appears nested under the parent issue with a progress indicator. Think of it as a rail line: each stop confirms you are still on the right route before the next one.

      +

      Alex: First, activate the Install button. VS Code installs the extension and may show a notification. Then, after installation, VS Code prompts you to sign in. Activate Sign in to GitHub. After that, a browser window opens for GitHub OAuth. Approve the authorization and return to VS Code. Finally, verify: open the Explorer sidebar (Ctrl+Shift+E). You should now see a GitHub section in the sidebar showing Pull Requests and Issues. Think of it as a rail line: each stop confirms you are still on the right route before the next one.

      +
      +

      Jamie: Let's pause on Practice 15.2 Step-by-Step: Check Out a PR and Post a Comment. What should a learner take away from it?

      +

      Alex: Start with Practice 15.2 Step-by-Step: Check Out a PR and Post a Comment: Check out someone else's PR branch locally, read the diff in VS Code, and post one constructive review comment. The next useful detail is this: VS Code with the GitHub Pull Requests extension installed.

      +

      Alex: First, open the Command Palette: Ctrl+Shift+P (Mac: Cmd+Shift+P). Then, type GitHub Pull Requests: Focus on Pull Requests View and select it. The Pull Requests panel opens. After that, navigate the list of open PRs. Find one that is not yours (a classmate's PR from Chapter 6, 7, or 14). Finally, 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. Think of it as a rail line: each stop confirms you are still on the right route before the next one.

      +

      Jamie: Before we leave Practice 15.2 Step-by-Step: Check Out a PR and Post a Comment, what is the practical point?

      +

      Alex: First, open the Command Palette again and run GitHub Pull Requests: Open Changed Files. This shows the list of files the PR changed. Then, open one changed file. VS Code opens the Diff Editor showing old content on the left and new content on the right. After that, 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). Finally, find one specific thing to comment on: a typo, an unclear sentence, a missing step, or something the author did well. Treat it like a recipe: do not add the next ingredient until the previous one is actually in the bowl.

      +

      Jamie: How do these exercises create confidence instead of pressure?

      +

      Alex: Here is the plain-English version of Completing Chapter 15, Part 1: Submit Your Evidence. Open your assigned setup or review practice issue and post a completion comment. Put another way, close your Chapter 12 challenge issues when done.

      +

      Alex: Keep the thread going. Start with Expected Outcomes. There is something to understand, something to try, and something that proves the try worked.

      +

      Alex: The room should hear these as checkpoints. 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.

      -

      Alex: Here is the practical turn. Start with 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. The next useful detail is this: Replace [number] with the actual issue numbers.

      -

      Jamie: Give me the version that sounds like an instructor, not a manual.

      -

      Alex: Start with Expected Outcomes. There is something to understand, something to try, and something that proves the try worked.

      -

      Alex: These are the details that keep the idea from floating away. 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.

      Jamie: Let's pause on If You Get Stuck. What should a learner take away from it?

      -

      Alex: Start with If You Get Stuck. There is something to understand, something to try, and something that proves the try worked.

      -

      Alex: First, can't find a classmate's issue? Filter the Issues tab by is:open and look for recent ones. Then, @mention not working? Make sure you type @ immediately followed by the username with no space. After that, sub-issue option not visible? Ask a facilitator - the feature may need to be enabled for the repository. Finally, still stuck? Ask a facilitator for a direct issue link. It is a checklist, but a meaningful one: every item creates evidence that the next step is safe.

      +

      Alex: Keep the learner anchored in If You Get Stuck. Continue learning: The GitHub Skills course Review Pull Requests practices approving, requesting changes, and using suggestions in an interactive format. This is the part to say slowly: See Appendix Z for the full catalog.

      +

      Alex: First, extension does not install? Reload VS Code: Ctrl+Shift+P, then run Developer: Reload Window. Then, oAuth sign-in fails? Verify your GitHub account is active in the browser first, close VS Code, reopen, and retry. After that, pR list is empty? Switch to "All Open" view in the GitHub Pull Requests panel. Finally, checkout fails? Confirm you have write access to the repository. If not, use the read-only GitHub.com fallback. It is like walking a hallway with named doors: read the sign, enter the right room, then confirm where you landed.

      Jamie: Before we leave If You Get Stuck, what is the practical point?

      -

      Alex: First, finished but not sure you did it right? Compare your work against the Challenge 2 reference solution or the Challenge 3 reference solution. It is like walking a hallway with named doors: read the sign, enter the right room, then confirm where you landed.

      -
      -

      Jamie: If I am listening before the workshop starts, what should settle in my mind first?

      -

      Alex: Keep the learner anchored in Learning Moment. Issues are collaborative spaces, not just task lists. This is the part to say slowly: An @mention tells someone "I need your attention here." Sub-issues turn vague tasks into clear checklists.

      +

      Alex: First, diff Editor is hard to navigate? Press F7 for the Accessible Diff Viewer mode, which is purpose-built for screen readers. Then, cannot find the Add Comment command? Use Command Palette and search for GitHub Pull Requests: Add Comment. After that, ask facilitator to help verify the GitHub PR panel and model one review comment. Finally, finished but not sure you did it right? Compare your work against the Challenge 11 reference solution. The rhythm is simple: orient, act, verify, then continue.

      +

      Alex: Another way to ground it. The reason Learning Moment matters is that reviewing others' work refines your own standards and builds community trust. That gives the learner a simple foothold: the comment you just wrote helps another student learn - and you learn by articulating what makes documentation clear.

      Jamie: Let's pause on Learning Pattern Used in This Chapter. What should a learner take away from it?

      Alex: Start with Learning Pattern Used in This Chapter. There is something to understand, something to try, and something that proves the try worked.

      -

      Alex: First, start with a small, safe action (create an issue). Then, practice communication in public issue threads (@mention a peer). After that, organize work into smaller pieces (sub-issues). Finally, leave clear evidence in the issue timeline. The rhythm is simple: orient, act, verify, then continue.

      -

      Jamie: Before we leave Learning Pattern Used in This Chapter, what is the practical point?

      -

      Alex: First, build momentum for file editing and PR work in Chapter 6. Think of it as a rail line: each stop confirms you are still on the right route before the next one.

      -

      Jamie: Let's pause on About Learning Cards in This Chapter. What should a learner take away from it?

      -

      Alex: Start with About Learning Cards in This Chapter: This chapter provides learning cards: expandable blocks that offer perspective-specific guidance for different ways of working. The next useful detail is this: Not every card appears at every step.

      +

      Alex: First, install and configure the tool before starting the task. Then, practice on someone else's work first (reviewing is safer than authoring). After that, use accessibility tools (F7 Accessible Diff Viewer) to navigate efficiently. Finally, write specific, constructive feedback (not just "looks good"). Think of it as a rail line: each stop confirms you are still on the right route before the next one.

      -

      Jamie: How do you keep commands from becoming magic words?

      -

      Alex: Here is the plain-English version of Local Git Alternative: Working from Your Clone. If you cloned the learning-room in Block 0 and prefer working locally. Put another way, during Block 0 you cloned the Learning Room repository to your computer. It is like learning a transit route. The names of the stops matter because they tell you whether you are still going the right direction.

      -

      Alex: Treat examples as spoken recipes, not decorations. You may hear something like cd /Documents/learning-room or wherever you cloned it; git status should show "On branch main". 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. Read the command, understand what it changes, then run it only when the repository state matches the lesson.

      -

      Alex: A solid Git habit is to know which branch you are on, what changed, and what confirmation you expect before you run the next command.

      -

      Jamie: Let's pause on What Is a GitHub Issue? What should a learner take away from it?

      -

      Alex: This is where What Is a GitHub Issue? becomes real: an issue is a discussion thread attached to a repository. That matters in practice: Every issue has a number ( 42), a state (Open or Closed), a title, a description, and a comment thread.

      -

      Alex: That becomes easier when you listen for these cues. 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".

      -

      Jamie: Let's pause on From a repository page. What should a learner take away from it?

      -

      Alex: Keep the learner anchored in From a repository page. Click the Issues tab in the repository navigation bar below the repository name. This is the part to say slowly: The tab shows the open issue count (e.g., "Issues · 14").

      -

      Alex: First, press D to navigate to the "Repository navigation" landmark. Then, press K or Tab to move through the tab links. After that, find "Issues" - it will be announced with the count: "Issues, 14 open". Finally, press Enter to open the Issues tab. It is like walking a hallway with named doors: read the sign, enter the right room, then confirm where you landed.

      -

      Jamie: Before we leave From a repository page, what is the practical point?

      -

      Alex: First, vO+U → Landmarks → navigate to "Repository navigation". Then, vO+Right or Quick Nav K to move through tab links. After that, find "Issues" - VoiceOver announces the count: "Issues 14". Finally, vO+Space to activate the Issues tab. The rhythm is simple: orient, act, verify, then continue.

      -

      Alex: Treat examples as spoken recipes, not decorations. You may hear something like gh issue list. gh issue list --label "good first issue"; gh issue list --assignee @me; gh issue list --state closed. Read the command, understand what it changes, then run it only when the repository state matches the lesson.

      +

      Alex: This is the part worth saying out loud. Here is the plain-English version of 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. It is like learning a transit route. The names of the stops matter because they tell you whether you are still going the right direction.

      +

      Jamie: Let's pause on Method 1: Extensions Sidebar. What should a learner take away from it?

      +

      Alex: Start with Method 1: Extensions Sidebar. There is something to understand, something to try, and something that proves the try worked.

      +

      Alex: First, open Extensions sidebar: Ctrl+Shift+X (Mac: Cmd+Shift+X). Then, type "GitHub Pull Requests" in the search box. After that, find "GitHub Pull Requests and Issues" (publisher: GitHub). Finally, navigate to the extension in the results list. It is a checklist, but a meaningful one: every item creates evidence that the next step is safe.

      +

      Jamie: Before we leave Method 1: Extensions Sidebar, what is the practical point?

      +

      Alex: First, press Enter to open the extension detail page. Then, tab to "Install" button → press Enter. It is like walking a hallway with named doors: read the sign, enter the right room, then confirm where you landed.

      +

      Jamie: Let's pause on Method 2: Command Palette. What should a learner take away from it?

      +

      Alex: Keep the learner anchored in Method 2: Command Palette. The Extensions sidebar is a tree view. This is the part to say slowly: Use Up/Down Arrow to navigate, Enter to open an extension's detail page.

      +

      Alex: First, ctrl+Shift+P. Then, type "install extensions". After that, select "Extensions: Install Extensions". Finally, search for "GitHub Pull Requests". It is like walking a hallway with named doors: read the sign, enter the right room, then confirm where you landed.

      +

      Jamie: Before we leave Method 2: Command Palette, what is the practical point?

      +

      Alex: First, install "GitHub Pull Requests and Issues". The rhythm is simple: orient, act, verify, then continue.

      -

      Jamie: Let's pause on Direct URL. What should a learner take away from it?

      -

      Alex: The reason Direct URL matters is that navigate directly: https://github.com/[owner]/[repo]/issues.

      -

      Alex: Keep the thread going. Start with Learning Cards: Navigating to the Issues List. There is something to understand, something to try, and something that proves the try worked.

      -

      Alex: The practical takeaway is this. 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. 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.

      -

      Jamie: Let's pause on Page structure. What should a learner take away from it?

      -

      Alex: Here is the plain-English version of Page structure. 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. Put another way, this is often faster than tabbing through many elements and helps you understand the full page structure before diving in.

      +

      Jamie: Let's pause on Signing In to GitHub. What should a learner take away from it?

      +

      Alex: The reason Signing In to GitHub matters is that after installation, VS Code prompts you to sign in.

      +

      Alex: First, a notification appears: "Sign in to GitHub to use Pull Requests". Then, navigate to the notification (Alt+N / Mac: Option+N, or status bar navigation). After that, select "Sign in". Finally, VS Code opens your browser for GitHub OAuth authentication. The rhythm is simple: orient, act, verify, then continue.

      +

      Jamie: Before we leave Signing In to GitHub, what is the practical point?

      +

      Alex: First, authorize VS Code in the browser. Then, return to VS Code - you're now signed in. Think of it as a rail line: each stop confirms you are still on the right route before the next one.

      +

      Alex: Here is the practical turn. Start with Verify sign-in. There is something to understand, something to try, and something that proves the try worked.

      +

      Alex: On the ground, that means a few things. 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.

      +

      Jamie: If I am listening before the workshop starts, what should settle in my mind first?

      +

      Alex: Start with What the Extension Adds. There is something to understand, something to try, and something that proves the try worked.

      +

      Alex: Here is what that changes in practice. 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.

      -

      Jamie: Let's pause on How to read the issue list. What should a learner take away from it?

      -

      Alex: This is where How to read the issue list becomes real: the issues list shows each issue as a row with its title, labels, number, assignee avatars, and comment count. That matters in practice: Closed issues show a purple merged/closed badge.

      -

      Alex: The practical takeaway is this. 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.

      -

      Alex: First, press D to reach the "Search Results List" landmark. Then, press 3 (h3) to navigate by issue titles - each issue title is an h3 link. After that, press I to move between list items if you want more detail per item. Finally, press Enter on a title to open that issue. It is a checklist, but a meaningful one: every item creates evidence that the next step is safe.

      -

      Jamie: Before we leave How to read the issue list, what is the practical point?

      -

      Alex: First, vO+U → Landmarks → navigate to "Search Results List". Then, vO+Down to read through items. After that, h (with Quick Nav on) or VO+U → Headings to jump by issue title. It is like walking a hallway with named doors: read the sign, enter the right room, then confirm where you landed.

      -

      Jamie: Let's pause on What is announced per issue. What should a learner take away from it?

      -

      Alex: Keep the learner anchored in What is announced per issue. When you navigate to an issue in the list, your screen reader will announce (in some order).

      -

      Alex: The practical takeaway is this. 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").

      -

      Alex: Another way to ground it. Start with Learning Cards: The Issues List Page. There is something to understand, something to try, and something that proves the try worked.

      -

      Alex: The practical takeaway is this. 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. 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.

      +

      Alex: The next layer is this. Start with Learning Cards: Installing the PR Extension. There is something to understand, something to try, and something that proves the try worked.

      +

      Alex: That becomes easier when you listen for these cues. 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". 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.

      +

      Jamie: Let's pause on Method 1: Activity Bar. What should a learner take away from it?

      +

      Alex: Keep the learner anchored in Method 1: Activity Bar. Click the GitHub logo icon in the Activity Bar (the vertical strip of icons on the far left). This is the part to say slowly: The GitHub Pull Requests panel opens.

      +

      Alex: A few details make that real. "Pull Requests". "Issues".

      +

      Alex: First, the Activity Bar is not always reachable by Tab from the editor. Then, use Ctrl+Shift+P (Mac: Cmd+Shift+P) → type "GitHub Pull Requests: View Pull Request" or "Focus on Pull Requests View" → press Enter. After that, alternatively press Ctrl+Shift+G (Mac: Cmd+Shift+G) to open Source Control, then Tab until you reach the Activity Bar icon strip. Finally, navigate to the repository on GitHub.com. It is like walking a hallway with named doors: read the sign, enter the right room, then confirm where you landed.

      +

      Jamie: Before we leave Method 1: Activity Bar, what is the practical point?

      +

      Alex: First, click the Pull requests tab. Then, click any PR title to view its conversation, commits, and changed files. After that, use the Files changed tab to review diffs. The rhythm is simple: orient, act, verify, then continue.

      +

      Alex: Treat examples as spoken recipes, not decorations. You may hear something like 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". Read the command, understand what it changes, then run it only when the repository state matches the lesson.

      +

      Jamie: Let's pause on Method 2: Explorer Section. What should a learner take away from it?

      +

      Alex: Start with Method 2: Explorer Section. There is something to understand, something to try, and something that proves the try worked.

      +

      Alex: First, open Explorer: Ctrl+Shift+E (Mac: Cmd+Shift+E). Then, navigate with Arrow keys to find the "GitHub Pull Requests" section. After that, expand it with Right Arrow. The rhythm is simple: orient, act, verify, then continue.

      -

      Jamie: Let's pause on Filtering and Searching Issues. What should a learner take away from it?

      -

      Alex: Start with Filtering and Searching Issues: Filtering lets you narrow the list to find the right issue quickly.

      -

      Jamie: Let's pause on Using the search/filter bar. What should a learner take away from it?

      -

      Alex: Start with Using the search/filter bar. There is something to understand, something to try, and something that proves the try worked.

      -

      Alex: First, press F or E to jump to the filter input field (or navigate from the landmark). Then, switch to Focus Mode (NVDA+Space / Insert+Z) if not already in it. After that, type your filter or search query. Finally, press Enter to apply. Treat it like a recipe: do not add the next ingredient until the previous one is actually in the bowl.

      -

      Jamie: Let's pause on Using the filter buttons. What should a learner take away from it?

      -

      Alex: This is where Using the filter buttons becomes real: above the issue list, there is an actions toolbar with filter buttons for Labels, Milestones, Assignees, etc. That matters in practice: The filter buttons do not indicate the current filter state.

      -

      Alex: The practical takeaway is this. 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.

      -

      Alex: First, press Tab from the search bar (or Shift+Tab from the issue list) to reach the actions toolbar. Then, press ←/→ to move between toolbar options (Label, Milestone, Assignee, Sort). After that, press Enter to open the selected dropdown. Finally, use ↑/↓ to navigate options in the dropdown. It is a checklist, but a meaningful one: every item creates evidence that the next step is safe.

      -

      Jamie: Before we leave Using the filter buttons, what is the practical point?

      -

      Alex: First, press Enter or Space to select. Then, press Escape to close (filter applies immediately). After that, tab forward from the search bar to reach the filter buttons, or use Quick Nav to find them. Finally, vO+Left/Right to move between Label, Milestone, Assignee, Sort buttons. It is like walking a hallway with named doors: read the sign, enter the right room, then confirm where you landed.

      -

      Alex: Treat examples as spoken recipes, not decorations. You may hear something like 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". Read the command, understand what it changes, then run it only when the repository state matches the lesson.

      +

      Jamie: Let's pause on Description. What should a learner take away from it?

      +

      Alex: Start with Description: The GitHub Pull Requests panel has two top-level sections. The next useful detail is this: "My Pull Requests" contains four filters: Assigned to Me, Created by Me, Waiting for my Review, and All Open.

      +

      Alex: That connects to another useful point. Here is the plain-English version of Screen reader announcement example. "Pull Request 42: Add Timeline Guide, opened by jeffb, 2 days ago, 3 files changed".

      +

      Alex: A solid navigation habit is to prove where you are before activating controls. Headings, landmarks, and the address bar are not trivia; they are your map.

      +

      Jamie: Let's pause on By status. What should a learner take away from it?

      +

      Alex: Start with By status. There is something to understand, something to try, and something that proves the try worked.

      +

      Alex: The parts worth keeping in working memory are these. "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.

      -

      Alex: Hold that next to this. Keep the learner anchored in Open vs Closed filter. The two state links "Open" and "Closed" appear near the top of the issue list. This is the part to say slowly: Press K to navigate links until you find them, or look for them as buttons near the search bar. A good GitHub workflow is like a well-run meeting: everyone knows the topic, the next action, and who has the floor.

      -

      Jamie: Let's pause on Learning Cards: Filtering and Searching Issues. What should a learner take away from it?

      -

      Alex: Start with Learning Cards: Filtering and Searching Issues. There is something to understand, something to try, and something that proves the try worked.

      -

      Alex: The practical takeaway is this. 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. 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.

      -

      Alex: That connects to another useful point. Start with Landing on an issue page: When you open an issue, the page structure is.

      +

      Alex: Keep the teaching thread moving. Keep the learner anchored in By repository. The tree organizes PRs by repository. A good GitHub workflow is like a well-run meeting: everyone knows the topic, the next action, and who has the floor.

      +

      Jamie: Let's pause on Viewing PR Details. What should a learner take away from it?

      +

      Alex: The reason Viewing PR Details matters is that a PR detail view opens in the editor area showing.

      +

      Alex: The practical takeaway is this. 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).

      +

      Alex: First, navigate to a PR in the tree. Then, press Enter. The rhythm is simple: orient, act, verify, then continue.

      +

      Alex: Keep the teaching thread moving. Start with Screen reader experience. There is something to understand, something to try, and something that proves the try worked.

      +

      Alex: The practical takeaway is this. 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.

      -

      Jamie: Let's pause on Reading the issue description. What should a learner take away from it?

      -

      Alex: Here is the plain-English version of Reading the issue description. Browse Mode recommended: The issue detail page is primarily text-based. Put another way, stay in Browse Mode (not Focus Mode) for reading - it gives you full heading (H), section (D), and link (K) navigation throughout the page.

      -

      Alex: First, press 2 to reach the "Description" heading. Then, press ↓ to read the content line by line,. After that, use NVDA+↓ (NVDA say all) to have it read continuously. Treat it like a recipe: do not add the next ingredient until the previous one is actually in the bowl.

      -

      Alex: Treat examples as spoken recipes, not decorations. You may hear something like 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. Read the command, understand what it changes, then run it only when the repository state matches the lesson.

      -

      Alex: This is the part worth saying out loud. This is where Reading comments and activity becomes real: each comment in the thread is marked as an h3. That matters in practice: Other timeline events (label added, PR linked, issue closed) appear between comments in the activity stream. The workshop is closer to rehearsal than lecture. You hear the move, try the move, and then check what changed.

      -

      Alex: The practical takeaway is this. Commenter's username. Timestamp ("2 days ago"). Body text. Reactions (if any - announced as a button with an emoji and count).

      -

      Jamie: Let's pause on Learning Cards: Reading an Issue. What should a learner take away from it?

      -

      Alex: Start with Learning Cards: Reading an Issue. There is something to understand, something to try, and something that proves the try worked.

      -

      Alex: The practical takeaway is this. 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. 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.

      +

      Jamie: Let's pause on 3. Checking Out a Pull Request Branch. What should a learner take away from it?

      +

      Alex: Here is the plain-English version of 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.

      +

      Alex: Keep the teaching thread moving. Start with Why Check Out a PR. There is something to understand, something to try, and something that proves the try worked.

      +

      Alex: The practical takeaway is this. 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.

      +

      Jamie: Let's pause on Method 1: From the PR Detail View. What should a learner take away from it?

      +

      Alex: Start with Method 1: From the PR Detail View. There is something to understand, something to try, and something that proves the try worked.

      +

      Alex: The practical takeaway is this. Downloads the branch. Switches your local repository to that branch. Opens the changed files in the editor.

      +

      Alex: First, open a PR (see Section 2). Then, in the PR detail view, navigate to "Checkout" button. After that, press Enter. It is like walking a hallway with named doors: read the sign, enter the right room, then confirm where you landed.

      -

      Jamie: Let's pause on Step-by-step. What should a learner take away from it?

      -

      Alex: The reason Step-by-step matters is that to close the issue while commenting: click the arrow on the Close issue button and choose Close with comment. That gives the learner a simple foothold: low vision users (zoom, high contrast).

      -

      Alex: First, scroll to the bottom of the issue page. Then, click in the Leave a comment text area. After that, type your comment (Markdown is supported - use the toolbar buttons above the text for bold, italic, code, etc.). Finally, optionally click Preview to see how it will render. The rhythm is simple: orient, act, verify, then continue.

      -

      Jamie: Before we leave Step-by-step, what is the practical point?

      -

      Alex: First, click the green Comment button to post. Then, scroll to the bottom to find the Leave a comment text area. At 200%+ zoom, this may require significant scrolling past the timeline. After that, the text area expands as you type. The formatting toolbar above it (bold, italic, code, etc.) wraps at high zoom but remains functional. Finally, the Preview tab next to Write lets you check Markdown rendering before posting. Think of it as a rail line: each stop confirms you are still on the right route before the next one.

      -

      Alex: Treat examples as spoken recipes, not decorations. You may hear something like 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.". Read the command, understand what it changes, then run it only when the repository state matches the lesson.

      -

      Jamie: Let's pause on Markdown formatting while typing. What should a learner take away from it?

      -

      Alex: Start with Markdown formatting while typing: These keyboard shortcuts work inside the text area (Focus Mode).

      -

      Alex: The next layer is this. Here is the plain-English version of GitHub shortcuts for the Issues pages. These are the GitHub built-in shortcuts for working with issues. Put another way, enable Focus Mode first (NVDA: NVDA+Space, JAWS: Insert+Z) before using single-key shortcuts. It is like learning a transit route. The names of the stops matter because they tell you whether you are still going the right direction.

      +

      Jamie: Let's pause on Method 2: From the PR Tree. What should a learner take away from it?

      +

      Alex: Start with Method 2: From the PR Tree. There is something to understand, something to try, and something that proves the try worked.

      +

      Alex: First, navigate to the PR in the GitHub Pull Requests tree. Then, press Shift+F10 (Mac: Ctrl+Return) to open context menu. After that, select "Checkout Pull Request". The rhythm is simple: orient, act, verify, then continue.

      +

      Jamie: Let's pause on Method 3: Command Palette. What should a learner take away from it?

      +

      Alex: Start with Method 3: Command Palette: After checkout, the bottom-left status bar shows the branch name (example: "jeffb/add-timeline-guide"). The next useful detail is this: Your local files now match that branch.

      +

      Alex: First, ctrl+Shift+P (Mac: Cmd+Shift+P). Then, type "GitHub Pull Requests: Checkout". After that, select "GitHub Pull Requests: Checkout Pull Request". Finally, choose the PR from the list. Think of it as a rail line: each stop confirms you are still on the right route before the next one.

      +

      Jamie: Let's pause on Returning to Your Original Branch. What should a learner take away from it?

      +

      Alex: Start with Returning to Your Original Branch. There is something to understand, something to try, and something that proves the try worked.

      +

      Alex: First, ctrl+Shift+P (Mac: Cmd+Shift+P). Then, type "git checkout". After that, select "Git: Checkout to.". Finally, choose your original branch (usually main or your feature branch). Treat it like a recipe: do not add the next ingredient until the previous one is actually in the bowl.

      +

      Alex: A solid Git habit is to know which branch you are on, what changed, and what confirmation you expect before you run the next command.

      -

      Jamie: Let's pause on On the Issues list page. What should a learner take away from it?

      -

      Alex: This is where On the Issues list page becomes real: shortcut note: For G I, press G, release it, then press I (two sequential key presses, not simultaneous).

      -

      Jamie: Let's pause on On an open issue. What should a learner take away from it?

      -

      Alex: Keep the learner anchored in On an open issue. R to quote is a power move: Select any text in a comment while in Browse Mode (Shift+Arrow to select), then press R. This is the part to say slowly: GitHub puts the quoted text in the comment box as a Markdown blockquote.

      -

      Alex: First, navigate to your comment (3 to jump to comments). Then, find the "." (ellipsis) menu button near your comment. After that, press Enter on "Edit" from that menu. Finally, the comment turns into a text area - switch to Focus Mode. It is like walking a hallway with named doors: read the sign, enter the right room, then confirm where you landed.

      -

      Jamie: Before we leave On an open issue, what is the practical point?

      -

      Alex: First, make your changes. Then, tab to "Update comment" button → Enter. The rhythm is simple: orient, act, verify, then continue.

      -

      Jamie: Let's pause on Learning Cards: Leaving a Comment. What should a learner take away from it?

      -

      Alex: Start with Learning Cards: Leaving a Comment. There is something to understand, something to try, and something that proves the try worked.

      -

      Alex: The practical takeaway is this. 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. 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.

      +

      Jamie: Let's pause on Learning Cards: Checking Out a PR. What should a learner take away from it?

      +

      Alex: Start with Learning Cards: Checking Out a PR. There is something to understand, something to try, and something that proves the try worked.

      +

      Alex: The practical takeaway is this. 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. 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.

      +

      Alex: Keep the teaching thread moving. Keep the learner anchored in 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.

      +

      Jamie: Let's pause on In the PR detail view. What should a learner take away from it?

      +

      Alex: Start with In the PR detail view. There is something to understand, something to try, and something that proves the try worked.

      +

      Alex: First, scroll down to "Files Changed" section. Then, each file is a link. After that, navigate with Arrow keys. Finally, press Enter on a file to open its diff view. The rhythm is simple: orient, act, verify, then continue.

      -

      Jamie: Let's pause on Navigating to New Issue. What should a learner take away from it?

      -

      Alex: Start with Navigating to New Issue: From the Issues list page, click the green New issue button in the top-right of the issue list. The next useful detail is this: 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. Think of it like entering a new building: first you find the lobby, then the room, then the door you actually need.

      -

      Alex: The practical takeaway is this. 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.

      -

      Alex: First, press K to navigate links and find the "New issue" button/link. Then, press Enter. After that, 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. Finally, quick Nav B or VO+U → Buttons to find the "New issue" button. Think of it as a rail line: each stop confirms you are still on the right route before the next one.

      -

      Jamie: Before we leave Navigating to New Issue, what is the practical point?

      -

      Alex: First, vO+Space to activate it. Then, 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. Treat it like a recipe: do not add the next ingredient until the previous one is actually in the bowl.

      -

      Jamie: Let's pause on Filling Out the Issue Form. What should a learner take away from it?

      -

      Alex: Here is the plain-English version of Filling Out the Issue Form. The issue form has these fields (order may vary depending on the template).

      -

      Jamie: Let's pause on Title field. What should a learner take away from it?

      -

      Alex: Start with Title field. There is something to understand, something to try, and something that proves the try worked.

      -

      Alex: First, find the Title input field (F or by landmark). Then, focus Mode → type a clear, specific title. After that, good title: "Screen reader announces wrong element count on Issues list with 50+ items". Finally, bad title: "Bug with screen reader". It is a checklist, but a meaningful one: every item creates evidence that the next step is safe.

      +

      Alex: Keep the teaching thread moving. Start with Screen reader announcement: "docs/11-vscode-interface.md, 42 additions, 3 deletions". Think of it like entering a new building: first you find the lobby, then the room, then the door you actually need.

      +

      Jamie: Let's pause on Understanding the Diff View. What should a learner take away from it?

      +

      Alex: Here is the plain-English version of Understanding the Diff View. When you open a file from "Files Changed".

      +

      Alex: Keep the teaching thread moving. Start with Split view mode (default). There is something to understand, something to try, and something that proves the try worked.

      +

      Alex: The practical takeaway is this. Left side: original file (before changes). Right side: modified file (after changes). Changed lines highlighted (added = green, removed = red).

      -

      Jamie: Let's pause on Description / Body field. What should a learner take away from it?

      -

      Alex: Start with Description / Body field. There is something to understand, something to try, and something that proves the try worked.

      -

      Alex: First, tab to the body text area. Then, focus Mode → type using the Markdown template provided. After that, if no template, use this structure. It is like walking a hallway with named doors: read the sign, enter the right room, then confirm where you landed.

      -

      Alex: Treat examples as spoken recipes, not decorations. You may hear something like 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. Read the command, understand what it changes, then run it only when the repository state matches the lesson.

      -

      Jamie: Let's pause on Assigning labels from the sidebar. What should a learner take away from it?

      -

      Alex: The reason Assigning labels from the sidebar matters is that see also: Chapter 09: Labels, Milestones, and Projects covers the full label and milestone system. That gives the learner a simple foothold: while the form is open, the sidebar has dropdowns for Labels, Assignees, and Milestone. The interface gets friendlier when it stops being a wall of controls and starts being a set of named places.

      -

      Alex: First, tab away from the text area (or press Escape to leave Focus Mode). Then, navigate to the sidebar - press H to find "Labels" heading. After that, press Enter on the Labels gear/button. Finally, dropdown opens → ↑/↓ to navigate labels. The rhythm is simple: orient, act, verify, then continue.

      -

      Jamie: Before we leave Assigning labels from the sidebar, what is the practical point?

      -

      Alex: First, enter to select/deselect. Then, escape to close (selections save automatically). After that, vO+Shift+Up to stop interacting with the text area. Finally, vO+U → Headings to find the "Labels" heading in the sidebar. Think of it as a rail line: each stop confirms you are still on the right route before the next one.

      -

      Alex: A solid project habit is to treat metadata as decision support. Labels, status, assignees, and notifications tell you what kind of attention the work needs.

      -

      Jamie: Let's pause on Submitting the issue. What should a learner take away from it?

      -

      Alex: Start with Submitting the issue: GitHub CLI (gh) alternative - filing a new issue. The next useful detail is this: Create an issue from your terminal.

      -

      Alex: First, tab to "Submit new issue" button. Then, press Enter. Think of it as a rail line: each stop confirms you are still on the right route before the next one.

      -

      Alex: Treat examples as spoken recipes, not decorations. You may hear something like 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. Read the command, understand what it changes, then run it only when the repository state matches the lesson.

      +

      Jamie: Let's pause on Inline view mode. What should a learner take away from it?

      +

      Alex: Start with Inline view mode. There is something to understand, something to try, and something that proves the try worked.

      +

      Alex: The practical takeaway is this. Single editor. Removed lines shown with - prefix. Added lines shown with + prefix.

      +

      Alex: Keep the teaching thread moving. Start with To toggle between views. There is something to understand, something to try, and something that proves the try worked.

      +

      Alex: The practical takeaway is this. Command Palette: Ctrl+Shift+P (Mac: Cmd+Shift+P) → "Diff: Toggle Inline View".

      +

      Jamie: Let's pause on Recommended workflow for screen reader users. What should a learner take away from it?

      +

      Alex: Start with Recommended workflow for screen reader users. There is something to understand, something to try, and something that proves the try worked.

      +

      Alex: The practical takeaway is this. Unchanged lines (for context). Removed lines (prefixed with -). Added lines (prefixed with +).

      +

      Alex: First, open a changed file from the PR detail view. Then, press F7 to jump to the first diff hunk. After that, press Alt+F2 (Mac: Option+F2) to open Accessible View. Finally, read the hunk content. Think of it as a rail line: each stop confirms you are still on the right route before the next one.

      +

      Jamie: Before we leave Recommended workflow for screen reader users, what is the practical point?

      +

      Alex: First, press Escape to close Accessible View. Then, press F7 to jump to the next hunk. After that, repeat until all hunks reviewed. Treat it like a recipe: do not add the next ingredient until the previous one is actually in the bowl.

      -

      Alex: Keep the teaching thread moving. Start with Learning Cards: Filing a New Issue. There is something to understand, something to try, and something that proves the try worked.

      -

      Alex: The practical takeaway is this. 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. 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.

      -

      Jamie: Let's pause on Tool Cards: File a New Issue. What should a learner take away from it?

      -

      Alex: This is where Tool Cards: File a New Issue becomes real: github.dev (web editor): Not available -- issues are managed through the repository's Issues tab, not the code editor. That matters in practice: VS Code Desktop (GitHub Pull Requests extension).

      -

      Alex: First, navigate to the repository's Issues tab (or press G then I). Then, click New issue, choose a template or blank issue. After that, fill in the title and description, then click Submit new issue. Finally, open the GitHub panel in the sidebar. It is a checklist, but a meaningful one: every item creates evidence that the next step is safe.

      -

      Jamie: Before we leave Tool Cards: File a New Issue, what is the practical point?

      -

      Alex: First, under Issues, click the + icon to create a new issue. Then, fill in the title and body, then click Create. It is like walking a hallway with named doors: read the sign, enter the right room, then confirm where you landed.

      -

      Alex: Treat examples as spoken recipes, not decorations. You may hear something like gh issue create --title "Your title" --body "Description here"; Or interactively:; gh issue create. Read the command, understand what it changes, then run it only when the repository state matches the lesson.

      -

      Alex: Keep the teaching thread moving. Keep the learner anchored in Cross-Referencing Issues. Linking issues and PRs to each other creates a trail of context that helps everyone understand the project's history. A good GitHub workflow is like a well-run meeting: everyone knows the topic, the next action, and who has the floor.

      +

      Alex: Keep the teaching thread moving. Here is the plain-English version of 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. Put another way, previously, deleted code could only be read, not selected.

      +

      Jamie: Let's pause on Flagging Issues During Review. What should a learner take away from it?

      +

      Alex: This is where Flagging Issues During Review becomes real: start Review saves your comments as a draft until you submit the full review (see Section 7).

      +

      Alex: First, navigate to the specific line in the diff. Then, press Shift+F10 (Mac: Ctrl+Return) for context menu. After that, select "Add Comment". Finally, type your comment in the input that appears. It is a checklist, but a meaningful one: every item creates evidence that the next step is safe.

      +

      Jamie: Before we leave Flagging Issues During Review, what is the practical point?

      +

      Alex: First, choose "Single Comment" or "Start Review". It is like walking a hallway with named doors: read the sign, enter the right room, then confirm where you landed.

      +

      Alex: A solid issue habit is to read the title, the body, and the timeline before acting. You are listening for the requested action, the missing evidence, and the person who needs a response.

      +

      Alex: Keep the teaching thread moving. Start with Learning Cards: Reviewing Pull Requests in VS Code. There is something to understand, something to try, and something that proves the try worked.

      +

      Alex: The practical takeaway is this. 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. 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.

      -

      Jamie: Let's pause on Closing keywords in PR descriptions or issue comments. What should a learner take away from it?

      -

      Alex: The reason Closing keywords in PR descriptions or issue comments matters is that when you type these phrases in a PR description or comment (followed by an issue number), GitHub creates a connection.

      -

      Alex: Keep the teaching thread moving. Start with Mentioning another issue in a comment: Simply type followed by a number anywhere in a comment body. The next useful detail is this: GitHub autocompletes with a dropdown of matching issues and PRs.

      -

      Jamie: Let's pause on Cross-repo references. What should a learner take away from it?

      -

      Alex: Here is the plain-English version of Cross-repo references. owner/repo 42 - references issue 42 in a different repository.

      +

      Jamie: Let's pause on Tool Cards: Create a Pull Request (from your editor). What should a learner take away from it?

      +

      Alex: The reason Tool Cards: Create a Pull Request (from your editor) matters is that VS Code Desktop (primary for Day 2). That gives the learner a simple foothold: after you've pushed commits to a feature branch, you can create a PR without leaving VS Code.

      +

      Alex: First, ctrl+Shift+P GitHub Pull Requests: Create Pull Request. Then, fill in the title, description, and base branch. After that, click Create. Finally, push your branch, then click the Compare & pull request banner on the repo page. The rhythm is simple: orient, act, verify, then continue.

      +

      Jamie: Before we leave Tool Cards: Create a Pull Request (from your editor), what is the practical point?

      +

      Alex: First, fill in the form and click Create pull request. Then, after pushing, click Create Pull Request -- this opens gitub.com with the form pre-filled. Think of it as a rail line: each stop confirms you are still on the right route before the next one.

      +

      Alex: Treat examples as spoken recipes, not decorations. You may hear something like git push -u origin your-branch; gh pr create --title "Title" --body "Description". Read the command, understand what it changes, then run it only when the repository state matches the lesson.

      +

      Jamie: Let's pause on Prerequisites. What should a learner take away from it?

      +

      Alex: Start with Prerequisites. There is something to understand, something to try, and something that proves the try worked.

      +

      Alex: First, you've created a branch (see Git & Source Control: Branch Management). Then, you've made commits. After that, you've pushed the branch to GitHub (Ctrl+Shift+P / Mac: Cmd+Shift+P → "Git: Push"). Think of it as a rail line: each stop confirms you are still on the right route before the next one.

      +

      Jamie: Let's pause on Method 1: Command Palette (Recommended). What should a learner take away from it?

      +

      Alex: Start with Method 1: Command Palette (Recommended). There is something to understand, something to try, and something that proves the try worked.

      +

      Alex: First, ctrl+Shift+P (Mac: Cmd+Shift+P). Then, type "GitHub Pull Requests: Create". After that, select "GitHub Pull Requests: Create Pull Request". Finally, a form opens in the editor. Treat it like a recipe: do not add the next ingredient until the previous one is actually in the bowl.

      -

      Alex: Keep the teaching thread moving. Start with Learning Cards: Cross-Referencing Issues. There is something to understand, something to try, and something that proves the try worked.

      -

      Alex: The practical takeaway is this. 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. 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.

      -

      Jamie: Let's pause on Sub-Issues - Parent and Child Relationships. What should a learner take away from it?

      -

      Alex: Keep the learner anchored in 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. This is the part to say slowly: A "parent" issue contains a list of child issues; each child is a full issue with its own discussion, labels, and assignees.

      -

      Jamie: What is the judgment call here?

      -

      Alex: Start with When to Use Sub-Issues. There is something to understand, something to try, and something that proves the try worked.

      -

      Alex: Use the comparison to make a decision, not to recite a table. The main contrasts are: Large feature broken down means Parent: "Redesign navigation"; Children: "Keyboard nav," "Screen reader nav," "Mobile nav". Epic tracking means Parent: "WCAG 2.1 AA compliance"; Children: one issue per failing criterion. Release milestone means Parent: "v2.0 release"; Children: every required PR/fix.

      +

      Jamie: Let's pause on Method 2: Source Control Panel. What should a learner take away from it?

      +

      Alex: Start with Method 2: Source Control Panel. There is something to understand, something to try, and something that proves the try worked.

      +

      Alex: First, open Source Control: Ctrl+Shift+G (Mac: Cmd+Shift+G). Then, after pushing, a "Create Pull Request" button appears. After that, press Enter on that button. It is a checklist, but a meaningful one: every item creates evidence that the next step is safe.

      +

      Jamie: Let's pause on Method 3: GitHub Panel. What should a learner take away from it?

      +

      Alex: Start with Method 3: GitHub Panel. There is something to understand, something to try, and something that proves the try worked.

      +

      Alex: First, open GitHub view (Activity Bar → GitHub icon). Then, right-click your branch in the tree. After that, select "Create Pull Request". It is like walking a hallway with named doors: read the sign, enter the right room, then confirm where you landed.

      +

      Alex: Keep the teaching thread moving. Start with Title (required). There is something to understand, something to try, and something that proves the try worked.

      +

      Alex: The practical takeaway is this. Auto-filled with your most recent commit message. Edit to make it descriptive (example: "Add Timeline View documentation").

      -

      Jamie: Let's pause on Creating a Sub-Issue. What should a learner take away from it?

      -

      Alex: Start with Creating a Sub-Issue: The sub-issues section is announced as a region. The next useful detail is this: After linking, the child issue appears as a list item with a checkbox showing its open/closed state.

      -

      Alex: Keep the teaching thread moving. Here is the plain-English version of Reading Sub-Issues on a Parent Issue. Progress indicator: The parent issue shows a completion bar (e.g., "3 of 7 completed") based on how many child issues are closed. Put another way, screen readers announce this as a progress region. It is like learning a transit route. The names of the stops matter because they tell you whether you are still going the right direction.

      -

      Jamie: Let's pause on Viewing a Child Issue's Parent. What should a learner take away from it?

      -

      Alex: This is where Viewing a Child Issue's Parent becomes real: every child issue shows a "Parent issue" link near the top of the page (above the description). That matters in practice: Navigate with H or links (K) to find it.

      +

      Jamie: Let's pause on Description (optional but recommended). What should a learner take away from it?

      +

      Alex: Start with Description (optional but recommended). There is something to understand, something to try, and something that proves the try worked.

      +

      Alex: The practical takeaway is this. 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.

      +

      Alex: Keep the teaching thread moving. Start with Base branch (target). There is something to understand, something to try, and something that proves the try worked.

      +

      Alex: The practical takeaway is this. Usually main or develop. This is the branch your changes will merge into.

      +

      Jamie: Let's pause on Compare branch (source). What should a learner take away from it?

      +

      Alex: Start with Compare branch (source). There is something to understand, something to try, and something that proves the try worked.

      +

      Alex: The practical takeaway is this. Your feature branch (auto-selected). This is the branch with your changes.

      -

      Alex: Keep the teaching thread moving. Keep the learner anchored in Sub-Issues vs. Task Lists. If you are working on a feature that requires multiple PRs or involves several team members, ask the maintainer to create a parent issue. This is the part to say slowly: You can then claim individual child issues without one person owning the whole feature.

      -

      Jamie: Let's pause on Learning Cards: Sub-Issues. What should a learner take away from it?

      -

      Alex: Start with Learning Cards: Sub-Issues. There is something to understand, something to try, and something that proves the try worked.

      -

      Alex: The practical takeaway is this. 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. 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.

      -

      Jamie: Let's pause on Closing an issue. What should a learner take away from it?

      -

      Alex: Start with Closing an issue: Scroll to the bottom of the issue page. The next useful detail is this: Click the Close issue button next to the comment box. Think of it like entering a new building: first you find the lobby, then the room, then the door you actually need.

      -

      Alex: First, 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. Then, button approach: Tab to the "Close issue" button (at the bottom of the page, near the comment box) and press Enter. After that, optionally leave a closing comment first. Finally, 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. Think of it as a rail line: each stop confirms you are still on the right route before the next one.

      -

      Jamie: Before we leave Closing an issue, what is the practical point?

      -

      Alex: First, button approach: Quick Nav B or Tab to find the "Close issue" button, then VO+Space. Treat it like a recipe: do not add the next ingredient until the previous one is actually in the bowl.

      -

      Alex: Treat examples as spoken recipes, not decorations. You may hear something like 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. Read the command, understand what it changes, then run it only when the repository state matches the lesson.

      +

      Alex: Keep the teaching thread moving. Start with Reviewers (optional). There is something to understand, something to try, and something that proves the try worked.

      +

      Alex: The practical takeaway is this. Select people to review your PR. Navigate the list with Arrow keys.

      +

      Jamie: Let's pause on Labels (optional). What should a learner take away from it?

      +

      Alex: Start with Labels (optional). There is something to understand, something to try, and something that proves the try worked.

      +

      Alex: The practical takeaway is this. Add labels like documentation, accessibility, good-first-issue.

      +

      Alex: Keep the teaching thread moving. Start with Milestone (optional). There is something to understand, something to try, and something that proves the try worked.

      +

      Alex: The practical takeaway is this. Link the PR to a project milestone.

      -

      Jamie: Let's pause on Reopening a closed issue. What should a learner take away from it?

      -

      Alex: Here is the plain-English version of Reopening a closed issue. If an issue is Closed, the "Close issue" button becomes "Reopen issue" - navigate and activate to reopen.

      -

      Jamie: Let's pause on Assigning an issue. What should a learner take away from it?

      -

      Alex: This is where Assigning an issue becomes real: GitHub CLI (gh) alternative - assigning and labeling. That matters in practice: Manage assignments and labels from your terminal.

      -

      Alex: First, navigate to "Assignees" heading (3 or H). Then, activate the gear/plus button. After that, type a username in the search field. Finally, select from the dropdown. It is a checklist, but a meaningful one: every item creates evidence that the next step is safe.

      -

      Alex: Treat examples as spoken recipes, not decorations. You may hear something like 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". Read the command, understand what it changes, then run it only when the repository state matches the lesson.

      -

      Jamie: Let's pause on Changing labels. What should a learner take away from it?

      -

      Alex: Start with Changing labels. There is something to understand, something to try, and something that proves the try worked.

      -

      Alex: First, navigate to "Labels" heading. Then, activate the gear button. After that, select/deselect labels from the dropdown. Finally, press Escape to save. It is like walking a hallway with named doors: read the sign, enter the right room, then confirm where you landed.

      +

      Jamie: Let's pause on Draft PR checkbox. What should a learner take away from it?

      +

      Alex: Start with Draft PR checkbox. There is something to understand, something to try, and something that proves the try worked.

      +

      Alex: The practical takeaway is this. Check this if the PR is not ready for review yet. Unchecked = "Ready for review".

      +

      Alex: Keep the teaching thread moving. Start with Screen reader navigation. There is something to understand, something to try, and something that proves the try worked.

      +

      Alex: The practical takeaway is this. All fields are standard form inputs. Tab to move between fields. Use Arrow keys in dropdowns (reviewers, labels, milestones).

      +

      Jamie: Let's pause on Submitting the PR. What should a learner take away from it?

      +

      Alex: Keep the learner anchored in Submitting the PR. VS Code creates the PR on GitHub and shows a success message. This is the part to say slowly: The PR link appears in the notification - click it to open the PR on GitHub, or open it in the GitHub Pull Requests panel.

      +

      Alex: First, review all fields. Then, tab to "Create" button. After that, press Enter. Finally, navigate to the repository on GitHub. It is like walking a hallway with named doors: read the sign, enter the right room, then confirm where you landed.

      +

      Jamie: Before we leave Submitting the PR, what is the practical point?

      +

      Alex: First, if you recently pushed, a yellow banner "Compare & pull request" appears - click it. Then, otherwise: click Pull requests tab, then New pull request, then select your branch. After that, fill in the title and description. Finally, click Create pull request. The rhythm is simple: orient, act, verify, then continue.

      +

      Alex: Treat examples as spoken recipes, not decorations. You may hear something like 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. Read the command, understand what it changes, then run it only when the repository state matches the lesson.

      -

      Alex: Keep the teaching thread moving. The reason Transferring or deleting an issue matters is that available from the "." (ellipsis) button at the top of the issue - navigate buttons with B to find it. The interface gets friendlier when it stops being a wall of controls and starts being a set of named places.

      -

      Jamie: Let's pause on Learning Cards: Managing Issues. What should a learner take away from it?

      -

      Alex: Start with Learning Cards: Managing Issues. There is something to understand, something to try, and something that proves the try worked.

      -

      Alex: The practical takeaway is this. 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. 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.

      -

      Jamie: Let's pause on The "good first issue" Label - Your Entry Point. What should a learner take away from it?

      -

      Alex: Here is the plain-English version of The "good first issue" Label - Your Entry Point. When looking for your first open source contribution. Put another way, remember: It's respectful to ask before starting.

      -

      Alex: First, navigate to any project's Issues tab. Then, filter by label: type is:open label:"good first issue" in the search. After that, read through issues until you find one in your area of interest. Finally, comment on the issue: "Hi, I'd like to work on this. Can I be assigned?". Treat it like a recipe: do not add the next ingredient until the previous one is actually in the bowl.

      -

      Jamie: Before we leave The "good first issue" Label - Your Entry Point, what is the practical point?

      -

      Alex: First, wait for a maintainer to respond and assign you before starting work. It is a checklist, but a meaningful one: every item creates evidence that the next step is safe.

      +

      Alex: Keep the teaching thread moving. Start with Learning Cards: Creating a Pull Request. There is something to understand, something to try, and something that proves the try worked.

      +

      Alex: The practical takeaway is this. 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. 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.

      +

      Jamie: Let's pause on 6. Pull Request Description Templates. What should a learner take away from it?

      +

      Alex: Start with 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.

      +

      Alex: Keep the teaching thread moving. Here is the plain-English version of Where Templates Are Stored. When you create a PR in VS Code, the extension automatically loads the template into the description field.

      +

      Alex: The practical takeaway is this.github/pull request template.md (root).github/PULL REQUEST TEMPLATE.md.github/PULL REQUEST TEMPLATE/ (folder with multiple templates). docs/pull request template.md.

      -

      Jamie: Let's pause on Learning Cards: The "good first issue" Label. What should a learner take away from it?

      -

      Alex: Start with Learning Cards: The "good first issue" Label. There is something to understand, something to try, and something that proves the try worked.

      -

      Alex: The practical takeaway is this. 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. 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.

      -

      Jamie: Let's pause on Accessibility-Specific Issue Writing Tips. What should a learner take away from it?

      -

      Alex: Keep the learner anchored in Accessibility-Specific Issue Writing Tips. When filing accessibility bugs, these details help maintainers reproduce and fix the problem. A good GitHub workflow is like a well-run meeting: everyone knows the topic, the next action, and who has the floor.

      -

      Alex: First, screen reader and version - "NVDA 2025.3.3" not just "screen reader". Then, oS and version - "Windows 11 22H2". After that, browser and version - "Chrome 124.0.6367.82". Finally, GitHub interface - "Modern experience (default since Jan 2026)" or "Classic experience (opted out)". It is like walking a hallway with named doors: read the sign, enter the right room, then confirm where you landed.

      -

      Jamie: Before we leave Accessibility-Specific Issue Writing Tips, what is the practical point?

      -

      Alex: First, what was announced - quote the exact text your screen reader spoke. Then, what should have been announced - describe the expected behavior. After that, aRIA issue if known - e.g., "The button has no accessible name". Finally, steps to reproduce - numbered, step-by-step. The rhythm is simple: orient, act, verify, then continue.

      -

      Jamie: Let's pause on Example of a well-filed accessibility issue. What should a learner take away from it?

      -

      Alex: Start with Example of a well-filed accessibility issue. There is something to understand, something to try, and something that proves the try worked.

      +

      Jamie: What should they understand before typing anything?

      +

      Alex: Start with Example PR Template. There is something to understand, something to try, and something that proves the try worked.

      +

      Alex: Treat examples as spoken recipes, not decorations. You may hear something like 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,. Read the command, understand what it changes, then run it only when the repository state matches the lesson.

      +

      Jamie: Let's pause on Screen reader workflow. What should a learner take away from it?

      +

      Alex: Keep the learner anchored in Screen reader workflow. Keyboard tip: Use Ctrl+F (Mac: Cmd+F) to jump to each <!-- placeholder, fill it in, then F3 to jump to the next one. A good GitHub workflow is like a well-run meeting: everyone knows the topic, the next action, and who has the floor.

      +

      Alex: First, create PR (Method 1-3 from Section 5). Then, the description field is pre-filled with the template. After that, navigate through the template with Arrow keys. Finally, replace each `` with your content. It is like walking a hallway with named doors: read the sign, enter the right room, then confirm where you landed.

      +

      Jamie: Before we leave Screen reader workflow, what is the practical point?

      +

      Alex: First, check checkboxes by typing x between the brackets: - [x]. The rhythm is simple: orient, act, verify, then continue.

      +

      Jamie: Let's pause on 7. Commenting and Requesting Changes. What should a learner take away from it?

      +

      Alex: Start with 7. Commenting and Requesting Changes. There is something to understand, something to try, and something that proves the try worked.

      +

      Alex: The practical takeaway is this. Leave inline comments on specific lines. Request changes before the PR can be merged. Approve the PR. Submit general feedback.

      -

      Alex: Keep the teaching thread moving. Start with Learning Cards: Accessibility-Specific Issue Writing. There is something to understand, something to try, and something that proves the try worked.

      -

      Alex: The practical takeaway is this. 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. 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.

      -

      Jamie: Let's pause on Writing Effective Issues. What should a learner take away from it?

      -

      Alex: Here is the plain-English version of Writing Effective Issues. See also: Appendix N: Advanced Search covers search qualifiers to find existing issues before filing a new one. Put another way, 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.

      -

      Alex: Keep the teaching thread moving. This is where Bug Report Structure becomes real: a strong bug report answers five questions. That matters in practice: Use this template every time you report something broken. The workshop is closer to rehearsal than lecture. You hear the move, try the move, and then check what changed.

      +

      Jamie: Let's pause on Adding an Inline Comment. What should a learner take away from it?

      +

      Alex: Start with Adding an Inline Comment. There is something to understand, something to try, and something that proves the try worked.

      +

      Alex: First, open a file from the PR's "Files Changed" list. Then, navigate to the line you want to comment on. After that, press Shift+F10 (Mac: Ctrl+Return) to open context menu. Finally, select "Add Comment". Think of it as a rail line: each stop confirms you are still on the right route before the next one.

      +

      Jamie: Before we leave Adding an Inline Comment, what is the practical point?

      +

      Alex: First, type your comment. Then, choose "Add Single Comment" (posts immediately) or "Start Review" (saves as a draft). Treat it like a recipe: do not add the next ingredient until the previous one is actually in the bowl.

      +

      Jamie: Let's pause on Comment format tips. What should a learner take away from it?

      +

      Alex: Start with Comment format tips. There is something to understand, something to try, and something that proves the try worked.

      +

      Alex: The practical takeaway is this. Be specific: "This heading should be H3, not H2". Provide context: "Screen readers announce this as 'list with 1 item' - should be a paragraph instead". Suggest a fix: "Consider rewording to: 'Click the button to save'".

      +

      Jamie: Let's pause on If you have multiple comments to make, use "Start Review". What should a learner take away from it?

      +

      Alex: Start with If you have multiple comments to make, use "Start Review". There is something to understand, something to try, and something that proves the try worked.

      +

      Alex: First, add your first inline comment → select "Start Review". Then, continue adding comments to other lines. After that, all comments are saved as drafts (not visible to others yet). It is a checklist, but a meaningful one: every item creates evidence that the next step is safe.

      -

      Jamie: Let's pause on Feature Request Structure. What should a learner take away from it?

      -

      Alex: Keep the learner anchored in Feature Request Structure. Feature requests work best when they focus on the problem before jumping to the solution. This is the part to say slowly: 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.

      -

      Alex: First, problem statement -- Describe the pain point. What are you trying to do, and why is it hard or impossible right now? Then, proposed solution -- Your best idea for fixing the problem. Be specific enough to discuss, but hold it loosely. After that, alternatives considered -- Other approaches you thought about and why they fell short. This shows you have done your homework. Finally, who benefits -- Name the audience. "Screen reader users navigating large repositories" is more compelling than "everyone.". It is like walking a hallway with named doors: read the sign, enter the right room, then confirm where you landed.

      -

      Alex: Keep the teaching thread moving. The reason General Issue Writing Principles matters is that these rules apply to every issue -- bugs, features, questions, and everything in between. That gives the learner a simple foothold: if you discovered two bugs during the same session, file two separate issues.

      -

      Jamie: What does someone need before they touch the keyboard?

      -

      Alex: Start with Before and After: A Vague Issue vs. a Clear Issue: I tried clicking and nothing happened. The next useful detail is this: The maintainer has to ask: What doesn't work?

      +

      Jamie: Let's pause on Submitting Your Review. What should a learner take away from it?

      +

      Alex: Keep the learner anchored in Submitting Your Review. The review type selector is a radio button group. This is the part to say slowly: Use Arrow keys to choose, Enter to confirm.

      +

      Alex: The practical takeaway is this. Comment - general feedback, no approval decision. Approve - PR looks good, ready to merge. Request Changes - issues must be fixed before merging.

      +

      Alex: First, ctrl+Shift+P (Mac: Cmd+Shift+P). Then, type "GitHub Pull Requests: Submit Review". After that, select "GitHub Pull Requests: Finish Review". Finally, choose review type. It is like walking a hallway with named doors: read the sign, enter the right room, then confirm where you landed.

      +

      Jamie: Before we leave Submitting Your Review, what is the practical point?

      +

      Alex: First, optionally add a summary comment. Then, press Enter to submit. The rhythm is simple: orient, act, verify, then continue.

      +

      Jamie: Let's pause on What Happens After Submission. What should a learner take away from it?

      +

      Alex: The reason What Happens After Submission matters is that web alternative (github.com) - reviewing. That gives the learner a simple foothold: see Accessible Code Review for detailed screen reader steps.

      +

      Alex: The practical takeaway is this. All your draft comments post to GitHub. The PR author receives a notification. Your review status appears on the PR (Approved / Changes Requested / Commented). If you requested changes, the PR cannot merge until you approve it.

      +

      Alex: First, open the PR and click the Files changed tab. Then, read through each file's diff. After that, click the blue + button on any line to add an inline comment. Finally, choose Start a review to batch comments. The rhythm is simple: orient, act, verify, then continue.

      +

      Jamie: Before we leave What Happens After Submission, what is the practical point?

      +

      Alex: First, click Review changes (top right) to select Comment / Approve / Request changes. Then, click Submit review. Think of it as a rail line: each stop confirms you are still on the right route before the next one.

      +

      Alex: Treat examples as spoken recipes, not decorations. You may hear something like View the PR diff in your terminal; gh pr diff 42; Approve; gh pr review 42 --approve --body "Looks good."; Request changes; gh pr review 42 --request-changes --body "Heading hierarchy needs fixing."; Comment-only (no verdict); gh pr review 42 --comment --body. Read the command, understand what it changes, then run it only when the repository state matches the lesson.

      +

      Jamie: Let's pause on Learning Cards: Commenting and Requesting Changes. What should a learner take away from it?

      +

      Alex: Start with Learning Cards: Commenting and Requesting Changes. There is something to understand, something to try, and something that proves the try worked.

      +

      Alex: The practical takeaway is this. In a diff view, navigate to a line and press Shift+F10 for the context menu, then select "Add Comment" to leave inline feedback. Choose "Start Review" instead of "Single Comment" to batch multiple comments before submitting them all at once. When submitting a review, use Ctrl+Shift+P then "GitHub Pull Requests: Submit Review" and choose Approve, Request Changes, or Comment. Inline comments appear as expandable banners within the diff view -- look for the text input box that opens below the target line. The review submission dialog has radio buttons for Approve, Request Changes, and Comment with clear labels. Increase diff view font size with Ctrl+= so line numbers and change annotations are easier to read.

      -

      Alex: Keep the teaching thread moving. Start with Learning Cards: Writing Effective Issues. There is something to understand, something to try, and something that proves the try worked.

      -

      Alex: The practical takeaway is this. 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. 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.

      -

      Jamie: Let's pause on Try It: File Your First Issue. What should a learner take away from it?

      -

      Alex: This is where Try It: File Your First Issue becomes real: time: 3 minutes What you need: Browser, signed in to GitHub. That matters in practice: Go to the Learning Room repository and file a real issue.

      -

      Alex: First, navigate to the Issues tab (press G then I in Focus Mode). Then, find and activate the "New issue" button (K to links, or Tab to it). After that, in the title field, type: "Introduce myself - [Your Name]". Finally, in the description, write 2-3 sentences: who you are, what screen reader you use, and one thing you're hoping to learn today. It is a checklist, but a meaningful one: every item creates evidence that the next step is safe.

      -

      Jamie: Before we leave Try It: File Your First Issue, what is the practical point?

      -

      Alex: First, press Ctrl+Enter to submit (or Tab to the Submit button and press Enter). It is like walking a hallway with named doors: read the sign, enter the right room, then confirm where you landed.

      -

      Alex: Keep the teaching thread moving. Keep the learner anchored in Learning Cards: Filing Your First Issue. Day 2 Amplifier - Accessibility Agents: @issue-tracker File, read, comment on, and triage real issues manually before using any agent. This is the part to say slowly: 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.

      -

      Alex: The practical takeaway is this. 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. 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.

      +

      Alex: Keep the teaching thread moving. Here is the plain-English version of 8. Merging Pull Requests. Who can merge: Repository maintainers, or contributors with write access. It is like learning a transit route. The names of the stops matter because they tell you whether you are still going the right direction.

      +

      Jamie: Let's pause on Prerequisites for Merging. What should a learner take away from it?

      +

      Alex: This is where Prerequisites for Merging becomes real: changing the base branch: If the PR was opened against the wrong base branch, you can change it from the PR detail view in VS Code. That matters in practice: Scroll to the base branch field in the PR detail view and activate the dropdown to select a different target branch.

      +

      Alex: First, all required reviews are approved. Then, all CI checks pass (green checkmarks). After that, no merge conflicts exist. Finally, branch is up to date with base branch (main). It is a checklist, but a meaningful one: every item creates evidence that the next step is safe.

      +

      Jamie: Let's pause on Method 1: PR Detail View. What should a learner take away from it?

      +

      Alex: Start with Method 1: PR Detail View. There is something to understand, something to try, and something that proves the try worked.

      +

      Alex: First, open the PR in VS Code. Then, scroll to the bottom of the PR detail view. After that, find "Merge Pull Request" button. Finally, press Enter. It is like walking a hallway with named doors: read the sign, enter the right room, then confirm where you landed.

      +

      Jamie: Before we leave Method 1: PR Detail View, what is the practical point?

      +

      Alex: First, choose merge type (see below). The rhythm is simple: orient, act, verify, then continue.

      -

      Jamie: Let's pause on How to Be an Effective and Respectful Open Source Contributor. What should a learner take away from it?

      -

      Alex: The reason How to Be an Effective and Respectful Open Source Contributor matters is that technical skills get your code into a project. That gives the learner a simple foothold: communication skills keep you welcomed in the community.

      -

      Alex: Keep the teaching thread moving. Start with Workshop Recommendation (Chapter 8): Chapter 8 is a communication and culture chapter. Think of it like entering a new building: first you find the lobby, then the room, then the door you actually need.

      -

      Alex: The practical takeaway is this. There are 1 guided reflection (no bot grading). Automation check: none - communication quality is too subjective for fair automated scoring. The evidence is structured reflection comment on your assigned challenge issue. The pattern is read, reflect, commit to one behavior.

      -

      Jamie: Let's pause on Chapter 8 Challenge Set. What should a learner take away from it?

      -

      Alex: Start with Chapter 8 Challenge Set. There is something to understand, something to try, and something that proves the try worked.

      -

      Alex: First, guided reflection - read the chapter, then post a short reflection comment committing to three specific collaboration behaviors. Treat it like a recipe: do not add the next ingredient until the previous one is actually in the bowl.

      +

      Jamie: What is the teaching move inside Method 2: Command Palette?

      +

      Alex: Start with Method 2: Command Palette. There is something to understand, something to try, and something that proves the try worked.

      +

      Alex: First, ctrl+Shift+P (Mac: Cmd+Shift+P). Then, type "GitHub Pull Requests: Merge". After that, select "GitHub Pull Requests: Merge Pull Request". Finally, choose the PR from the list. The rhythm is simple: orient, act, verify, then continue.

      +

      Jamie: If someone only remembers one thing from Method 2: Command Palette, what should it be?

      +

      Alex: First, select merge type. Think of it as a rail line: each stop confirms you are still on the right route before the next one.

      +

      Alex: Keep the teaching thread moving. Start with Merge Types: The merge type selector is a dropdown or radio group. The next useful detail is this: Navigate with Arrow keys, confirm with Enter. Think of it like entering a new building: first you find the lobby, then the room, then the door you actually need.

      +

      Jamie: Let's pause on Which merge type to use. What should a learner take away from it?

      +

      Alex: Start with Which merge type to use. There is something to understand, something to try, and something that proves the try worked.

      +

      Alex: The practical takeaway is this. Check the repository's CONTRIBUTING.md for guidance. If unsure, use Merge Commit (the default and safest option).

      -

      Jamie: Let's pause on Challenge 8.1 Step-by-Step: Guided Reflection. What should a learner take away from it?

      -

      Alex: This is where Challenge 8.1 Step-by-Step: Guided Reflection becomes real: identify three concrete communication behaviors you will practice during the rest of the workshop. That matters in practice: your assigned Chapter 8 challenge issue in your Learning Room repository on GitHub.com.

      -

      Alex: The practical takeaway is this. 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.".

      -

      Alex: First, read through the chapter content below, paying attention to the sections on GitHub Flow, constructive feedback, and asking for help. Then, as you read, think about one situation from Day 1 where communication helped (or could have helped) you. After that, open your assigned Chapter 8 challenge issue (the one titled "Chapter 8.1: Guided Reflection (@yourname)"). Finally, scroll to the comment box at the bottom of the issue. It is a checklist, but a meaningful one: every item creates evidence that the next step is safe.

      -

      Jamie: Before we leave Challenge 8.1 Step-by-Step: Guided Reflection, what is the practical point?

      -

      Alex: First, post a reflection comment using this format. Then, for each prompt, write one specific, actionable sentence - not a vague goal. After that, activate the Comment button (or press Ctrl+Enter). It is like walking a hallway with named doors: read the sign, enter the right room, then confirm where you landed.

      -

      Jamie: How do these exercises create confidence instead of pressure?

      -

      Alex: Keep the learner anchored in Completing Chapter 8: Submit Your Evidence. The reflection comment itself is your evidence. This is the part to say slowly: The facilitator reviews your comment for specificity.

      -

      Alex: Keep the teaching thread moving. Start with Expected Outcomes. There is something to understand, something to try, and something that proves the try worked.

      -

      Alex: The practical takeaway is this. 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.

      +

      Jamie: Let's pause on After Merging. What should a learner take away from it?

      +

      Alex: Start with After Merging. There is something to understand, something to try, and something that proves the try worked.

      +

      Alex: First, the PR closes automatically. Then, the feature branch can be deleted (VS Code prompts: "Delete branch?"). After that, recommended: switch back to main and pull the merged changes. It is a checklist, but a meaningful one: every item creates evidence that the next step is safe.

      +

      Jamie: How do you keep commands from becoming magic words?

      +

      Alex: Keep the learner anchored in Switching to main and pulling. (Mac users: use Cmd+Shift+P instead of Ctrl+Shift+P).

      +

      Alex: Treat examples as spoken recipes, not decorations. You may hear something like Ctrl+Shift+P → "Git: Checkout to." → select "main"; Ctrl+Shift+P → "Git: Pull". Read the command, understand what it changes, then run it only when the repository state matches the lesson.

      +

      Jamie: Let's pause on Deleting the Feature Branch. What should a learner take away from it?

      +

      Alex: The reason Deleting the Feature Branch matters is that after merging, the feature branch is no longer needed. That gives the learner a simple foothold: web alternative (github.com) - merging. The interface gets friendlier when it stops being a wall of controls and starts being a set of named places.

      +

      Alex: First, ctrl+Shift+P (Mac: Cmd+Shift+P). Then, type "git delete branch". After that, select "Git: Delete Branch.". Finally, choose the merged branch. The rhythm is simple: orient, act, verify, then continue.

      +

      Jamie: Before we leave Deleting the Feature Branch, what is the practical point?

      +

      Alex: First, open the PR's Conversation tab. Then, scroll to the merge button at the bottom. After that, click the dropdown arrow to choose a merge strategy (Squash, Rebase, or Merge commit). Finally, click Merge pull request, then Confirm merge. Think of it as a rail line: each stop confirms you are still on the right route before the next one.

      +

      Alex: Treat examples as spoken recipes, not decorations. You may hear something like Merge with default strategy; gh pr merge 42; Squash and merge, then delete the branch; gh pr merge 42 --squash --delete-branch; Enable auto-merge (merges when checks pass); gh pr merge 42 --auto --squash. Read the command, understand what it changes, then run it only when the repository state matches the lesson.

      -

      Jamie: What is the teaching move inside If You Get Stuck?

      -

      Alex: First, use one simple sentence per prompt - do not overthink it. Then, focus on one real behavior you can start doing today, not an abstract principle. After that, if writing feels hard, draft bullet points first in a text editor, then paste into the comment. Finally, look at the "Giving Feedback" and "Asking for Help" sections in this chapter for concrete examples. Think of it as a rail line: each stop confirms you are still on the right route before the next one.

      -

      Jamie: If someone only remembers one thing from If You Get Stuck, what should it be?

      -

      Alex: First, ask facilitator for one example response and adapt it to your own words. Then, finished but not sure you did it right? Compare your work against the Challenge 8 reference solution. Treat it like a recipe: do not add the next ingredient until the previous one is actually in the bowl.

      -

      Alex: Keep the teaching thread moving. Here is the plain-English version of Learning Moment. Technical quality and communication quality work together. Put another way, respectful, clear communication helps good code get merged faster.

      -

      Jamie: What is the teaching move inside Learning Pattern Used in This Chapter?

      -

      Alex: First, read and absorb community norms (not just rules, but reasons). Then, reflect on personal experience (what worked, what was hard). After that, commit to specific behaviors in writing (public accountability). Finally, apply those behaviors in upcoming chapters (reviews, comments, PRs). It is a checklist, but a meaningful one: every item creates evidence that the next step is safe.

      +

      Jamie: Let's pause on Learning Cards: Merging Pull Requests. What should a learner take away from it?

      +

      Alex: Start with Learning Cards: Merging Pull Requests. There is something to understand, something to try, and something that proves the try worked.

      +

      Alex: The practical takeaway is this. The merge type selector (Merge Commit, Squash, Rebase) is announced as a dropdown or radio group -- use Arrow keys to move between options and Enter to confirm; if unsure, choose Merge Commit (the default and safest option). After merging, VS Code prompts "Delete branch?" as a notification -- press Alt+N to focus the notification and Enter to confirm, then run Ctrl+Shift+P then "Git: Checkout to" and select main to return to your default branch. Confirm the merge succeeded by pressing F6 to reach the Status Bar and verifying it now reads main instead of the feature branch name. The merge button at the bottom of the PR detail view includes a dropdown arrow for selecting merge type -- at high zoom, widen the editor pane so the button label and dropdown are not truncated. After merging, the PR detail view header changes from "Open" (green badge) to "Merged" (purple badge) -- verify this colour/label change before deleting the branch. When switching back to main, the branch name in the bottom-left Status Bar updates immediately -- confirm it reads main before pulling new changes with Ctrl+Shift+P then "Git: Pull".

      +

      Alex: Keep the teaching thread moving. Here is the plain-English version of "No pull requests found". Issue: The GitHub Pull Requests panel is empty.

      +

      Jamie: Let's pause on Solutions. What should a learner take away from it?

      +

      Alex: Start with Solutions. There is something to understand, something to try, and something that proves the try worked.

      +

      Alex: First, verify you're signed in: Ctrl+Shift+P (Mac: Cmd+Shift+P) → "GitHub Pull Requests: Sign in". Then, check you have a folder open containing a Git repository. After that, refresh the panel: Ctrl+Shift+P (Mac: Cmd+Shift+P) → "GitHub Pull Requests: Refresh Pull Requests List". It is a checklist, but a meaningful one: every item creates evidence that the next step is safe.

      -

      Alex: Keep the teaching thread moving. Keep the learner anchored in 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. This is the part to say slowly: GitHub Flow is the lightweight branching model recommended for open source contribution. A good GitHub workflow is like a well-run meeting: everyone knows the topic, the next action, and who has the floor.

      -

      Jamie: Let's pause on Why This Model Works. What should a learner take away from it?

      -

      Alex: Start with Why This Model Works. There is something to understand, something to try, and something that proves the try worked.

      -

      Alex: The practical takeaway is this. 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.

      -

      Alex: Keep the teaching thread moving. Start with GitHub Flow vs Git Flow: You may encounter "Git Flow" (sometimes written "GitFlow") in older projects or enterprise environments. The next useful detail is this: This section explains what Git Flow is, how it differs from GitHub Flow, and why this workshop teaches GitHub Flow.

      +

      Jamie: Before we leave Solutions, what is the practical point?

      +

      Alex: First, verify you've pushed your branch: Ctrl+Shift+P (Mac: Cmd+Shift+P) → "Git: Push". Then, check you have write access to the repository. After that, ensure your branch is ahead of the base branch (has new commits). It is like walking a hallway with named doors: read the sign, enter the right room, then confirm where you landed.

      +

      Jamie: Let's pause on "Authentication failed". What should a learner take away from it?

      +

      Alex: The reason "Authentication failed" matters is that issue: VS Code can't connect to GitHub.

      +

      Jamie: What is the teaching move inside Solutions?

      +

      Alex: First, sign out and sign back in: Ctrl+Shift+P (Mac: Cmd+Shift+P) → "GitHub Pull Requests: Sign out" → then sign in again. Then, check your GitHub Personal Access Token (see Appendix D: Git Authentication). After that, verify network connection. Think of it as a rail line: each stop confirms you are still on the right route before the next one.

      -

      Jamie: Let's pause on What Git Flow Is. What should a learner take away from it?

      -

      Alex: Here is the plain-English version of What Git Flow Is. Git Flow is a branching model published by Vincent Driessen in 2010. Put another way, it was designed for teams that ship versioned releases on a schedule (desktop software, mobile apps, embedded systems).

      -

      Jamie: Let's pause on How the Git Flow Cycle Works. What should a learner take away from it?

      -

      Alex: Start with How the Git Flow Cycle Works. There is something to understand, something to try, and something that proves the try worked.

      -

      Alex: First, developers branch feature/my-feature off develop and work there. Then, completed features merge back into develop via pull request. After that, when develop has enough features for a release, a release/1.2.0 branch is created. Finally, the release branch gets final testing, bug fixes, and version number updates. It is a checklist, but a meaningful one: every item creates evidence that the next step is safe.

      -

      Jamie: Before we leave How the Git Flow Cycle Works, what is the practical point?

      -

      Alex: First, the release branch merges into main (tagged with the version) and back into develop. Then, if a critical bug is found in production, a hotfix/ branch is created from main, fixed, and merged into both main and develop. It is like walking a hallway with named doors: read the sign, enter the right room, then confirm where you landed.

      -

      Jamie: Let's pause on How GitHub Flow Differs. What should a learner take away from it?

      -

      Alex: Keep the learner anchored in How GitHub Flow Differs. The following table compares GitHub Flow and Git Flow across key dimensions.

      -
      -

      Alex: Keep the teaching thread moving. Start with When You Might See Git Flow. There is something to understand, something to try, and something that proves the try worked.

      -

      Alex: The practical takeaway is this. 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.

      -

      Jamie: Zoom out for a second. What kind of journey is this?

      -

      Alex: Start with 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. The next useful detail is this: It is what GitHub itself uses and what most modern open source projects follow.

      -

      Alex: Keep the teaching thread moving. Here is the plain-English version of The Unwritten Rule: One Thing Per Branch. A branch and its PR should do one thing. Put another way, if you are fixing a broken link and you notice a typo nearby, fix the typo in a separate branch and PR. It is like learning a transit route. The names of the stops matter because they tell you whether you are still going the right direction.

      -
      -

      Jamie: Let's pause on Learning Cards: GitHub Flow. What should a learner take away from it?

      -

      Alex: Start with Learning Cards: GitHub Flow. There is something to understand, something to try, and something that proves the try worked.

      -

      Alex: The practical takeaway is this. 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). 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.

      -

      Alex: Keep the teaching thread moving. Keep the learner anchored in Keeping Your Fork Up to Date. When you fork a repository, you get a snapshot of the project at that moment. This is the part to say slowly: The original repository (called "upstream") continues to evolve.

      -

      Jamie: Let's pause on Why Sync Your Fork? What should a learner take away from it?

      -

      Alex: Start with Why Sync Your Fork? There is something to understand, something to try, and something that proves the try worked.

      -

      Alex: The practical takeaway is this. 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.

      +

      Jamie: Let's pause on Try It: Review a PR from VS Code. What should a learner take away from it?

      +

      Alex: Here is the plain-English version of Try It: Review a PR from VS Code. Time: 3 minutes What you need: VS Code with GitHub Pull Requests extension installed and signed in. Put another way, you just reviewed a pull request entirely from VS Code.

      +

      Alex: First, open the PR view - Press Ctrl+Shift+P → type Pull Requests: Focus on GitHub Pull Requests View → Enter. Then, find a PR - Navigate the tree with arrow keys. Expand a PR to see its changed files. After that, open a diff - Press Enter on a changed file. The diff editor opens. Finally, use the Accessible Diff Viewer - Press F7 to jump to the first change. Your screen reader announces what was added or removed. Press F7 again to move to the next change. Treat it like a recipe: do not add the next ingredient until the previous one is actually in the bowl.

      +

      Jamie: Before we leave Try It: Review a PR from VS Code, what is the practical point?

      +

      Alex: First, leave a comment - Position your cursor on a line you want to comment on, then press Ctrl+Shift+P → Pull Request: Add Comment on Current Diff Line. Type a brief, constructive comment and submit. It is a checklist, but a meaningful one: every item creates evidence that the next step is safe.

      +

      Alex: Keep the teaching thread moving. This is where Conducting Pull Request Reviews with a Screen Reader becomes real: this guide is focused entirely on the reviewer experience - navigating diffs, reading changes, leaving comments, and submitting a review - using only your keyboard and screen reader. That matters in practice: For the full pull request lifecycle (opening PRs, merge options, conflict resolution), see Working with Pull Requests. The workshop is closer to rehearsal than lecture. You hear the move, try the move, and then check what changed.

      +

      Jamie: Where does the workshop stop being a tour and start becoming contribution?

      +

      Alex: Keep the learner anchored in Workshop Recommendation (Chapter 15 / Challenge 12). Chapter 15 is the code review chapter focused on practicing constructive feedback. This is the part to say slowly: It supports Challenge 12: Review Like a Pro.

      +

      Alex: The practical takeaway is this. There are 2 guided challenges. Automation check: none (review quality is subjective and human-focused). The evidence is issue comment with summary of review and feedback posted. The pattern is navigate diff, comment on specifics, submit verdict.

      -

      Jamie: Let's pause on Method 1: GitHub Web Interface (Easiest). What should a learner take away from it?

      -

      Alex: Start with Method 1: GitHub Web Interface (Easiest): GitHub merges the upstream changes into your fork automatically. The next useful detail is this: Screen reader users (NVDA / JAWS / VoiceOver). Think of it like entering a new building: first you find the lobby, then the room, then the door you actually need.

      -

      Alex: First, navigate to your fork's main page: github.com/your-username/repo-name. Then, look for the sync indicator: "This branch is X commits behind upstream/main". After that, click the "Sync fork" button. Finally, click "Update branch". Think of it as a rail line: each stop confirms you are still on the right route before the next one.

      -

      Jamie: Before we leave Method 1: GitHub Web Interface (Easiest), what is the practical point?

      -

      Alex: First, the sync button appears in the landmark that contains the branch selector. Then, press D to cycle through landmarks until you reach that region. After that, press B to cycle buttons until you hear "Sync fork" → press Enter. Finally, a dialog or page update presents "Update branch" - activate it. Treat it like a recipe: do not add the next ingredient until the previous one is actually in the bowl.

      -

      Jamie: What should someone listen for when a lesson offers more than one tool path?

      -

      Alex: Here is the plain-English version of Method 2: Git Command Line (VS Code Terminal). If you're working locally in VS Code.

      -

      Jamie: What should happen before anyone copies and runs it?

      -

      Alex: Start with One-time setup - add the upstream remote. There is something to understand, something to try, and something that proves the try worked.

      -

      Alex: Treat examples as spoken recipes, not decorations. You may hear something like git remote add upstream https://github.com/original-owner/repo-name.git; git remote -v Verify it was added. Read the command, understand what it changes, then run it only when the repository state matches the lesson.

      +

      Jamie: Let's pause on Challenge 12 Practice Set. What should a learner take away from it?

      +

      Alex: Start with Challenge 12 Practice Set. There is something to understand, something to try, and something that proves the try worked.

      +

      Alex: First, review a practice PR and leave 2-3 inline comments - read the diff line by line, find specific items to comment on, and post constructive feedback. Then, submit a formal review verdict - complete your review by choosing approve, request changes, or comment only. The rhythm is simple: orient, act, verify, then continue.

      +

      Jamie: Let's pause on Practice 12.1 Step-by-Step: Review a PR and Leave Inline Comments. What should a learner take away from it?

      +

      Alex: Start with Practice 12.1 Step-by-Step: Review a PR and Leave Inline Comments: Navigate a PR diff using screen reader-friendly tools and post 2-3 specific, constructive inline comments. The next useful detail is this: GitHub.com (Files changed tab of a PR) or VS Code with the GitHub Pull Requests extension.

      +

      Alex: The practical takeaway is this. On GitHub.com: Use heading navigation to jump between files (H in NVDA). Each file header is a heading. Within a file, use arrow keys to move line by line. In VS Code: Press F7 to open the Accessible Diff Viewer (see Chapter 15, Part 1). Use F7/Shift+F7 to move between changes. Typos or grammar issues. Unclear headings or link text.

      +

      Alex: First, open your Learning Room repository on GitHub.com and navigate to the Pull requests tab. Then, find a classmate's open PR (from Chapter 6, 7, or 14). Open it. After that, activate the Files changed tab. This shows the diff - lines added in green, lines removed in red. Finally, navigate the diff. Think of it as a rail line: each stop confirms you are still on the right route before the next one.

      +

      Jamie: Before we leave Practice 12.1 Step-by-Step: Review a PR and Leave Inline Comments, what is the practical point?

      +

      Alex: First, read through the changes carefully. Look. Then, to leave an inline comment on GitHub.com: activate the + button that appears to the left of a line number when you hover or Tab to it. (Screen reader users: this button may be announced as "Add a comment to this line.") Type your comment in the text box that. After that, post 2-3 inline comments. Each comment should be. Finally, examples of good inline comments. Treat it like a recipe: do not add the next ingredient until the previous one is actually in the bowl.

      +

      Jamie: Let's pause on Practice 12.2 Step-by-Step: Submit a Formal Review Verdict. What should a learner take away from it?

      +

      Alex: Here is the plain-English version of Practice 12.2 Step-by-Step: Submit a Formal Review Verdict. Complete your review by selecting a verdict that tells the author what action to take next. Put another way, GitHub.com (the same PR you reviewed in 14.1). It is like learning a transit route. The names of the stops matter because they tell you whether you are still going the right direction.

      +

      Alex: The practical takeaway is this. Comment - general feedback, no explicit approval or rejection. Approve - you think the PR is ready to merge. Request changes - you found something that should be fixed before merging. If the PR has clear documentation with only minor suggestions, choose Approve.

      +

      Alex: First, after posting your inline comments, scroll to the top of the Files changed tab. Then, activate the Review changes button (at the top-right of the files changed area, or use heading navigation). After that, a dropdown opens with three options. Finally, choose the verdict that matches your review. Treat it like a recipe: do not add the next ingredient until the previous one is actually in the bowl.

      +

      Jamie: Before we leave Practice 12.2 Step-by-Step: Submit a Formal Review Verdict, what is the practical point?

      +

      Alex: First, write a brief summary in the review body (1-2 sentences). Example: "Clear improvement to the shortcut table. Two minor suggestions for link text clarity.". Then, activate Submit review. It is a checklist, but a meaningful one: every item creates evidence that the next step is safe.

      -

      Jamie: What should they understand before typing anything?

      -

      Alex: Start with Sync process. There is something to understand, something to try, and something that proves the try worked.

      -

      Alex: Treat examples as spoken recipes, not decorations. You may hear something like 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. Read the command, understand what it changes, then run it only when the repository state matches the lesson.

      -

      Alex: Keep the teaching thread moving. Start with When to sync. There is something to understand, something to try, and something that proves the try worked.

      -

      Alex: The practical takeaway is this. 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).

      -

      Jamie: Let's pause on Method 3: GitHub Desktop. What should a learner take away from it?

      -

      Alex: Start with Method 3: GitHub Desktop. There is something to understand, something to try, and something that proves the try worked.

      -

      Alex: First, open GitHub Desktop. Then, select Repository → Pull to get your fork's latest. After that, select Branch → Merge into Current Branch. Finally, choose upstream/main. Think of it as a rail line: each stop confirms you are still on the right route before the next one.

      -

      Jamie: Before we leave Method 3: GitHub Desktop, what is the practical point?

      -

      Alex: First, push the changes to your fork on GitHub. Treat it like a recipe: do not add the next ingredient until the previous one is actually in the bowl.

      +

      Jamie: What should the learner prove to themselves after each small task?

      +

      Alex: This is where Completing Challenge 12: Submit Your Evidence becomes real: open your assigned Challenge 12 issue and post a completion comment. That matters in practice: Close your Challenge 12 issue when done.

      +

      Alex: Keep the teaching thread moving. Start with Expected Outcomes. There is something to understand, something to try, and something that proves the try worked.

      +

      Alex: The practical takeaway is this. Student can navigate PR diffs with a screen reader. Student can post inline comments on specific lines of a diff. Student can write constructive, specific feedback that helps the author improve. Student can submit a formal review verdict.

      +

      Jamie: What is the teaching move inside If You Get Stuck?

      +

      Alex: The reason If You Get Stuck matters is that continue learning: The GitHub Skills courses Review Pull Requests and Code Review with GitHub Copilot cover review workflows and AI-assisted code review. That gives the learner a simple foothold: see Appendix Z for the full catalog.

      +

      Alex: First, files Changed tab will not open? Reload the PR page and retry. Make sure you are on the PR page, not the issue page. Then, cannot find the inline comment button? Tab through the line controls in the diff. The button may be announced as "Add a comment" or have a + label. If you cannot find it, use the "Review changes" button at the top to add a general comment instead. After that, not sure what to comment on? Focus on clarity: is every heading descriptive? Is every link meaningful? Are steps complete? Are keyboard shortcuts correct? Finally, review verdict button not working? Make sure you have at least one comment or have written summary text. Try reloading the page. The rhythm is simple: orient, act, verify, then continue.

      +

      Jamie: If someone only remembers one thing from If You Get Stuck, what should it be?

      +

      Alex: First, submitting the review fails? Check that you are not in draft mode and have at least read access to the repo. Then, ask facilitator to model one inline comment and one verdict submission. After that, finished but not sure you did it right? Compare your work against the Challenge 12 reference solution. Think of it as a rail line: each stop confirms you are still on the right route before the next one.

      -

      Alex: Keep the teaching thread moving. Start with Learning Cards: Keeping Your Fork Up to Date. There is something to understand, something to try, and something that proves the try worked.

      -

      Alex: The practical takeaway is this. 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. 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.

      -

      Jamie: Let's pause on Writing Good Commit Messages. What should a learner take away from it?

      -

      Alex: This is where Writing Good Commit Messages becomes real: every commit you make includes a message describing what changed. That matters in practice: Good commit messages make project history understandable months or years later.

      -

      Alex: Keep the teaching thread moving. Keep the learner anchored in The First Line (Required). This is the commit summary that appears in logs and GitHub's commit list. This is the part to say slowly: Think of it as an email subject line. A good GitHub workflow is like a well-run meeting: everyone knows the topic, the next action, and who has the floor.

      -

      Alex: The practical takeaway is this. fix: - bug fix. feat: - new feature. docs: - documentation only. style: - formatting, no code change.

      +

      Alex: Keep the teaching thread moving. Start with Learning Moment: Specific, kind feedback helps authors improve and builds trust in the community. The next useful detail is this: Every comment you write is practice for the professional code review you will do on real projects. Think of it like entering a new building: first you find the lobby, then the room, then the door you actually need.

      +

      Jamie: Before we leave Learning Pattern Used in This Chapter, what is the practical point?

      +

      Alex: First, read the full diff before commenting (understand the author's intent first). Then, find specific items to comment on (lines, phrases, missing steps). After that, write comments that help, not just criticize (suggest improvements, note what works). Finally, choose a verdict that matches the substance of your feedback. Treat it like a recipe: do not add the next ingredient until the previous one is actually in the bowl.

      +

      Jamie: What is the teaching move inside Learning Pattern Used in This Chapter?

      +

      Alex: First, summarize your overall impression in 1-2 sentences. It is a checklist, but a meaningful one: every item creates evidence that the next step is safe.

      +

      Alex: Keep the teaching thread moving. This is where Before starting this chapter, verify you have completed becomes real: estimated time for this chapter: 1 hour (including exercises).

      +

      Alex: The practical takeaway is this. [ ] Chapter 6: Working with Pull Requests - Understand PR structure, diffs, and comment workflows. [ ] Chapter 13: GitHub Copilot - VS Code installed and configured. [ ] Screen Reader Setup - NVDA, JAWS, or VoiceOver installed and ready to use. [ ] Access to at least one pull request to review (your own fork or a practice repo).

      +

      Jamie: Let's pause on Two Environments for Code Review. What should a learner take away from it?

      +

      Alex: Keep the learner anchored in Two Environments for Code Review. You can review pull requests in two places - each with different strengths. This is the part to say slowly: Both environments give you full keyboard and screen reader access.

      Jamie: What is the safe way to learn from that example?

      -

      Alex: The reason The Body (Optional) matters is that if the summary isn't enough, add a body explaining. That gives the learner a simple foothold: leave a blank line between the summary and the body.

      -

      Alex: The practical takeaway is this. Why you made the change (more important than what). What trade-offs you considered. How the change affects behavior.

      -

      Alex: Treat examples as spoken recipes, not decorations. You may hear something like 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. Read the command, understand what it changes, then run it only when the repository state matches the lesson.

      -

      Alex: Keep the teaching thread moving. Start with The Footer (Optional): When the commit is merged, GitHub automatically closes linked issues.

      -

      Jamie: Let's pause on Atomic Commits. What should a learner take away from it?

      -

      Alex: Here is the plain-English version of Atomic Commits. Each commit should represent one logical change. Put another way, don't bundle unrelated fixes into a single commit.

      -
      -

      Alex: Keep the teaching thread moving. Start with Common mistakes to avoid. There is something to understand, something to try, and something that proves the try worked.

      -

      Alex: The practical takeaway is this. "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.

      -

      Jamie: Let's pause on Good commit messages in practice. What should a learner take away from it?

      -

      Alex: Keep the learner anchored in Good commit messages in practice. When you make a habit of writing good commit messages, you build trust. This is the part to say slowly: Maintainers see that you care about the project's long-term health, not just your immediate contribution.

      -

      Alex: Treat examples as spoken recipes, not decorations. You may hear something like 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. Read the command, understand what it changes, then run it only when the repository state matches the lesson.

      -

      Alex: Keep the teaching thread moving. Start with Learning Cards: Writing Good Commit Messages. There is something to understand, something to try, and something that proves the try worked.

      -

      Alex: The practical takeaway is this. 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. 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.

      +

      Alex: The reason About Learning Cards in This Chapter matters is that each review step includes expandable learning cards for different interaction styles. That gives the learner a simple foothold: open the one that matches how you work. The interface gets friendlier when it stops being a wall of controls and starts being a set of named places.

      +

      Alex: Treat examples as spoken recipes, not decorations. You may hear something like View the full PR diff in your terminal; gh pr diff 42; View PR details (description, status, checks); gh pr view 42; Checkout the PR branch locally for testing; gh pr checkout 42; Approve the PR; gh pr review 42 --approve --body "Heading hierarchy looks. Read the command, understand what it changes, then run it only when the repository state matches the lesson.

      +

      Jamie: Let's pause on Good News: Modern Interface is Default. What should a learner take away from it?

      +

      Alex: Start with Good News: Modern Interface is Default: As of January 2026, GitHub's improved Files Changed experience is enabled by default. The next useful detail is this: The instructions below assume you have the modern interface (which you do).

      -

      Jamie: Let's pause on The Nature of Open Source Communication. What should a learner take away from it?

      -

      Alex: Start with The Nature of Open Source Communication: Open source collaboration happens primarily in writing, asynchronously, in public. The next useful detail is this: Understanding these three characteristics shapes everything about how we communicate.

      -

      Alex: Keep the teaching thread moving. Start with In writing. There is something to understand, something to try, and something that proves the try worked.

      -

      Alex: The practical takeaway is this. 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.".

      -

      Jamie: Let's pause on Asynchronously. What should a learner take away from it?

      -

      Alex: Start with Asynchronously. There is something to understand, something to try, and something that proves the try worked.

      -

      Alex: The practical takeaway is this. 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.

      +

      Jamie: Let's pause on Step 1: Reach the Files Changed Tab. What should a learner take away from it?

      +

      Alex: Here is the plain-English version of Step 1: Reach the Files Changed Tab. Click the Files changed tab at the top of the PR page. Put another way, the tab label shows the number of changed files (e.g., "Files changed 4").

      +

      Alex: First, the PR tabs (Conversation, Commits, Checks, Files changed) are across the top of the PR page. At high zoom they may wrap to multiple lines. Then, the Files changed tab includes a badge with the number of changed files. This badge uses text (not colour alone) so it is visible in all themes. After that, after clicking Files changed, the diff page loads. At high zoom, the file tree panel on the left may collapse automatically. Click the file tree toggle (a small panel icon) or press T to toggle it back. Finally, added lines use a green background; removed lines use red. In high contrast browser settings (Windows: Settings Accessibility Contrast themes), these colours map to strong border indicators. Treat it like a recipe: do not add the next ingredient until the previous one is actually in the bowl.

      +

      Jamie: Before we leave Step 1: Reach the Files Changed Tab, what is the practical point?

      +

      Alex: First, use Ctrl++ to zoom the browser if the diff text is too small, and Ctrl+- to zoom out. It is a checklist, but a meaningful one: every item creates evidence that the next step is safe.

      +

      Alex: Treat examples as spoken recipes, not decorations. You may hear something like Press D → navigate to "Pull request navigation tabs" landmark; Press → or Tab → find "Files changed" link → Enter. Read the command, understand what it changes, then run it only when the repository state matches the lesson.

      +

      Jamie: Let's pause on Step 2: Use the File Tree to Orient Yourself. What should a learner take away from it?

      +

      Alex: This is where Step 2: Use the File Tree to Orient Yourself becomes real: the file tree panel lists every changed file. That matters in practice: Before reading any diff, scan this list to understand the scope of the PR.

      +

      Jamie: Let's pause on What to listen for / look for. What should a learner take away from it?

      +

      Alex: Keep the learner anchored in What to listen for / look for. Low vision users (zoom, high contrast). A good GitHub workflow is like a well-run meeting: everyone knows the topic, the next action, and who has the floor.

      +

      Alex: The practical takeaway is this. How many files changed? Which areas of the codebase are affected? Are there unexpected files (generated files, lock files, configuration changes)?

      +

      Alex: First, the file tree shows each filename with a colour-coded bar indicating lines added (green) and removed (red). In high contrast mode, these bars may be less visible - the +N / -N text badge next to each file is the reliable indicator. Then, at high zoom, long file paths truncate. Hover over a truncated name to see the full path in a tooltip. After that, if the file tree panel is too narrow at high zoom, drag its right edge to widen it, or toggle it off and use heading navigation (H key) to move between file diffs. It is like walking a hallway with named doors: read the sign, enter the right room, then confirm where you landed.

      -

      Alex: Keep the teaching thread moving. Start with In public. There is something to understand, something to try, and something that proves the try worked.

      -

      Alex: The practical takeaway is this. 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.

      -

      Jamie: What do you want them to do when the plan breaks?

      -

      Alex: The reason The Anatomy of Helpful Feedback matters is that whether commenting on an issue, reviewing a PR, or responding to a question, effective feedback has a structure.

      -

      Alex: Keep the teaching thread moving. Start with 1. Acknowledge what's working: Before identifying problems, name what is good. The next useful detail is this: This is not flattery - it is accuracy. Think of it like entering a new building: first you find the lobby, then the room, then the door you actually need.

      +

      Jamie: What should happen before anyone copies and runs it?

      +

      Alex: The reason Step 3: Navigate Between File Diffs matters is that each changed file in the main area is an h3 heading containing the filename. That gives the learner a simple foothold: scroll through the page or click a filename in the file tree on the left.

      +

      Alex: Treat examples as spoken recipes, not decorations. You may hear something like Press 3 to jump file-by-file through the diff; Listen for: "learning-room/docs/keyboard-shortcuts.md - collapsed" or "expanded"; Press Enter or Space to expand a collapsed file. Quick Nav H or VO+Cmd+H to jump file-by-file through the diff; Listen for: "learning-room/docs/keyboard-shortcuts.md - collapsed" or "expanded"; VO+Space to expand a collapsed file. Read the command, understand what it changes, then run it only when the repository state matches the lesson.

      +

      Jamie: Let's pause on Step 4: Read a Diff. What should a learner take away from it?

      +

      Alex: Start with Step 4: Read a Diff: Low vision users (zoom, high contrast). The next useful detail is this: Screen reader users - VoiceOver (macOS).

      +

      Alex: The practical takeaway is this. Green highlighted lines (with a +) = lines added. Red highlighted lines (with a -) = lines removed. Plain/white lines = unchanged context. Use Ctrl+F to search within the page for specific text in the diff.

      +

      Alex: First, colour is not the only indicator. Every added line has a + character in the gutter; every removed line has a -. These text characters are reliable regardless of colour settings. Then, at high zoom, long lines of code wrap. The +/- gutter character stays at the beginning of the first line, so look left to determine the change type. After that, use Ctrl+F (browser find) to search for specific text across the entire diff page. Finally, if the diff is split view (side by side), it may be very wide at high zoom. Switch to unified diff mode: click the gear icon in the Files Changed toolbar and select "Unified" - this shows old and new in a single column. Think of it as a rail line: each stop confirms you are still on the right route before the next one.

      +

      Jamie: Before we leave Step 4: Read a Diff, what is the practical point?

      +

      Alex: First, high contrast themes in Windows (Settings Accessibility Contrast themes) make the +/- lines use bold border patterns instead of subtle colour shading. Treat it like a recipe: do not add the next ingredient until the previous one is actually in the bowl.

      +

      Alex: Treat examples as spoken recipes, not decorations. You may hear something like Press T to jump to the diff table then Insert+Space (Focus Mode); Press Down Arrow to move through lines one at a time; Press Ctrl+Alt+Right Arrow to read across columns: line number, change type, code content. Press T to jump to the diff table then Insert+Z (Virtual PC Cursor off); Press Down Arrow to move through lines; Press Ctrl+Alt+Right Arrow for column-by-column reading. Read the command, understand what it changes, then run it only when the repository state matches the lesson.

      +

      Jamie: Let's pause on What each line announces / shows. What should a learner take away from it?

      +

      Alex: Here is the plain-English version of What each line announces / shows. If the code on a line is very long, the screen reader will read the full line. Put another way, for minified or generated files, consider collapsing the file in the tree and skipping it.

      +

      Alex: The practical takeaway is this. Added lines: "+ [code content]" - or announced as "inserted". Removed lines: "- [code content]" - or announced as "deleted". Context lines: code without a + or -.

      -

      Jamie: Let's pause on 2. Identify the specific concern. What should a learner take away from it?

      -

      Alex: Here is the plain-English version of 2. Identify the specific concern. "This code is inaccessible." "This button has no accessible name - aria-label or visible text is needed for screen readers to announce its purpose.".

      -

      Alex: Keep the teaching thread moving. This is where 3. Explain why it matters becomes real: context turns a complaint into a lesson. That matters in practice: It also respects the contributor - they deserve to understand, not just comply.

      -

      Jamie: Let's pause on 4. Suggest a path forward (when you can). What should a learner take away from it?

      -

      Alex: Keep the learner anchored in 4. Suggest a path forward (when you can). If you have an idea for a solution, offer it as a suggestion, not a mandate. This is the part to say slowly: "Something like aria-label='Close navigation menu' would work well here.

      +

      Jamie: Let's pause on Step 5: Place an Inline Comment. What should a learner take away from it?

      +

      Alex: This is where Step 5: Place an Inline Comment becomes real: when you have a specific observation about a particular line, place an inline comment directly on it. That matters in practice: Screen reader users (VoiceOver - macOS). The workshop is closer to rehearsal than lecture. You hear the move, try the move, and then check what changed.

      +

      Alex: First, hover your mouse over a line in the diff - a blue + (comment) button appears on the left. Then, click it to open the inline comment box. After that, type your comment. Finally, click "Start a review" (not "Add single comment" - see note below). It is a checklist, but a meaningful one: every item creates evidence that the next step is safe.

      +

      Jamie: Let's pause on Placing a multi-line comment. What should a learner take away from it?

      +

      Alex: Keep the learner anchored in Placing a multi-line comment. Click and drag across multiple line numbers in the diff gutter to select a range. This is the part to say slowly: A comment button appears for the selected range.

      +

      Jamie: Let's pause on Step 6: Read Existing Comments and Threads. What should a learner take away from it?

      +

      Alex: The reason Step 6: Read Existing Comments and Threads matters is that inline comments from other reviewers appear as h3 headings within the diff table. That gives the learner a simple foothold: each thread shows: reviewer username, comment body, replies, a "Reply" link and resolution button.

      +

      Alex: Treat examples as spoken recipes, not decorations. You may hear something like Tab to the "Resolve conversation" button → Enter. Tab to the "Resolve conversation" button → VO+Space. Read the command, understand what it changes, then run it only when the repository state matches the lesson.

      -

      Alex: Keep the teaching thread moving. The reason 5. Signal the weight of the concern matters is that help contributors understand what is a blocker versus a preference. The interface gets friendlier when it stops being a wall of controls and starts being a set of named places.

      -

      Alex: The practical takeaway is this. 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.

      -

      Jamie: Let's pause on Prefer "we" or describe the code, not the person. What should a learner take away from it?

      -

      Alex: Start with 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.".

      -

      Alex: Keep the teaching thread moving. Here is the plain-English version of 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?".

      +

      Jamie: Let's pause on Step 7: Submit Your Review. What should a learner take away from it?

      +

      Alex: Start with Step 7: Submit Your Review: Screen reader users (VoiceOver - macOS).

      +

      Alex: First, click the "Review changes" button (top-right of the Files Changed page or bottom of the PR). Then, a dialog opens with a summary text area and three radio buttons: Comment / Approve / Request changes. After that, optionally type an overall summary in the text area. Finally, select your verdict. Think of it as a rail line: each stop confirms you are still on the right route before the next one.

      +

      Jamie: Before we leave Step 7: Submit Your Review, what is the practical point?

      +

      Alex: First, click "Submit review". Treat it like a recipe: do not add the next ingredient until the previous one is actually in the bowl.

      +

      Jamie: Let's pause on Step 8: Re-request Review (for Authors). What should a learner take away from it?

      +

      Alex: Here is the plain-English version of Step 8: Re-request Review (for Authors). After you address review comments on your own PR. Put another way, look in the right sidebar for the Reviewers section. It is like learning a transit route. The names of the stops matter because they tell you whether you are still going the right direction.

      +

      Alex: Treat examples as spoken recipes, not decorations. You may hear something like Step 1: From your PR's Conversation tab, Quick Nav H or VO+Cmd+H to find the "Reviewers" heading in the sidebar; Step 2: Tab or Quick Nav B to find the re-request icon ("Re-request review") next to the reviewer's name; Step 3: VO+Space to activate - this. Read the command, understand what it changes, then run it only when the repository state matches the lesson.

      +

      Jamie: Let's pause on Learning Cards: Reviewing on GitHub.com. What should a learner take away from it?

      +

      Alex: Start with Learning Cards: Reviewing on GitHub.com. There is something to understand, something to try, and something that proves the try worked.

      +

      Alex: The practical takeaway is this. In the Files Changed tab, press T to jump to the diff table, then use Focus Mode (Insert+Space in NVDA, Insert+Z in JAWS) and Down Arrow to read line by line -- each added line starts with + and each removed line with -. To place an inline comment, navigate to the target line and press Tab or B to find the "Add a comment to this line" button; after typing your comment, choose "Start a review" (not "Add single comment") to batch all feedback into one notification. Submit your full review by pressing B repeatedly to find the "Review changes" button; the dialog contains a radio group (Comment / Approve / Request changes) navigable with Arrow keys, then Tab to "Submit review". Switch from split diff to unified diff (gear icon in the Files Changed toolbar then select "Unified") to show old and new code in a single column -- much easier to follow at high zoom than two side-by-side panes. The blue + comment button appears in the line gutter on hover; at high zoom it may be small -- use Ctrl++ to increase browser zoom and look just left of the line number column. The "Review changes" dialog uses clearly labeled radio buttons for the three verdict types; each label includes a brief description, and the currently selected option has a filled circle indicator visible in all themes.

      -

      Jamie: Let's pause on Acknowledge cultural and language diversity. What should a learner take away from it?

      -

      Alex: This is where Acknowledge cultural and language diversity becomes real: when reading someone's comment: Assume good intent unless there is clear evidence otherwise. That matters in practice: When writing: Choose plain words over clever ones.

      -

      Alex: The practical takeaway is this. 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.

      -

      Alex: Keep the teaching thread moving. Keep the learner anchored in 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?". A good GitHub workflow is like a well-run meeting: everyone knows the topic, the next action, and who has the floor.

      -

      Jamie: Let's pause on Keep comments focused. What should a learner take away from it?

      -

      Alex: The reason Keep comments focused matters is that each comment should address one concern. That gives the learner a simple foothold: if you have three issues, leave three comments - unless they are closely related.

      +

      Alex: Keep the teaching thread moving. Keep the learner anchored in Reviewing in VS Code with the Accessible Diff Viewer. When you check out a branch locally, VS Code's diff editor offers the Accessible Diff Viewer - a purpose-built, line-by-line reading mode designed specifically for screen readers.

      +

      Jamie: Let's pause on Opening a Diff in VS Code. What should a learner take away from it?

      +

      Alex: The reason Opening a Diff in VS Code matters is that if you have the GitHub Pull Requests extension. That gives the learner a simple foothold: without the extension, any git diff operation also opens the diff editor.

      +

      Alex: First, open the GitHub Pull Requests view (Explorer sidebar or Ctrl+Shift+P → "GitHub Pull Requests: View Pull Request"). Then, find the PR and open it - changed files appear in the file tree. After that, navigate to any file in the tree and press Enter to open its diff view. The rhythm is simple: orient, act, verify, then continue.

      +

      Jamie: Let's pause on Learning Cards: VS Code Code Review. What should a learner take away from it?

      +

      Alex: Start with Learning Cards: VS Code Code Review: Low vision users (zoom, high contrast). The next useful detail is this: VS Code's diff editor works well at high zoom. Think of it like entering a new building: first you find the lobby, then the room, then the door you actually need.

      +

      Alex: First, split view vs. inline: By default, VS Code shows diffs in a split (side-by-side) view. At high zoom this can be very cramped. Switch to inline mode: Ctrl+Shift+P then type "Toggle Inline View" in any diff editor. Inline mode shows old and new code in a single. Then, colour indicators: Added lines have a green gutter bar; removed lines have a red gutter bar. In high contrast themes, these use heavy solid borders that are visible even at extreme zoom levels. After that, change navigation: Press F7 to jump to the next change and Shift+F7 for the previous. Each change is highlighted with a visible focus box that moves with your position - much easier than scrolling at high zoom. Finally, minimap in diff view: The minimap (right edge) shows an overview of changes as coloured blocks. At high zoom the minimap may be too small to be useful - disable it via Settings if it adds visual noise. Think of it as a rail line: each stop confirms you are still on the right route before the next one.

      +

      Jamie: Before we leave Learning Cards: VS Code Code Review, what is the practical point?

      +

      Alex: First, font size for diffs: Diff editors use your configured editor font size (editor.fontSize). Increase this in Settings (Ctrl+,) if the diff text is too small at your zoom level. Then, comment highlight: When you add a comment through the GitHub PR extension, the commented line gets a distinct background. In high contrast themes this is a solid colour band. Treat it like a recipe: do not add the next ingredient until the previous one is actually in the bowl.

      -

      Alex: Keep the teaching thread moving. Start with Don't leave comments unresolved: If you asked a question and got an answer, respond. The next useful detail is this: "Thanks, that makes sense" or resolving the conversation thread signals that the thread is complete.

      -

      Jamie: Let's pause on Resolving conversations. What should a learner take away from it?

      -

      Alex: Here is the plain-English version of Resolving conversations. On a PR, conversations (inline comment threads) can be "resolved" once addressed. Put another way, the author of the change and the reviewer can both resolve them.

      -

      Alex: Keep the teaching thread moving. This is where Do not "pile on" becomes real: if five people already said the same thing about an issue, you don't need to add a sixth comment saying the same thing. That matters in practice: A reaction on an existing comment is enough. The workshop is closer to rehearsal than lecture. You hear the move, try the move, and then check what changed.

      +

      Jamie: Let's pause on Opening the PR for review. What should a learner take away from it?

      +

      Alex: Start with Opening the PR for review. There is something to understand, something to try, and something that proves the try worked.

      +

      Alex: First, press Ctrl+Shift+P, type "GitHub Pull Requests: View Pull Request". Then, the PR tree appears in the sidebar - navigate with Down Arrow. After that, each changed file is announced with its name and change summary. Finally, press Enter on a file to open its diff editor. Treat it like a recipe: do not add the next ingredient until the previous one is actually in the bowl.

      +

      Jamie: Before we leave Opening the PR for review, what is the practical point?

      +

      Alex: First, the diff editor opens with the standard VS Code diff layout. It is a checklist, but a meaningful one: every item creates evidence that the next step is safe.

      +

      Jamie: Let's pause on Using the Accessible Diff Viewer. What should a learner take away from it?

      +

      Alex: Start with Using the Accessible Diff Viewer. There is something to understand, something to try, and something that proves the try worked.

      +

      Alex: First, in the diff editor, press F7 to open the Accessible Diff Viewer. Then, NVDA announces: "Changed lines X to Y in filename, Change 1 of N". After that, the viewer shows each change with "Removed:" and "Added:" labels. Finally, press F7 to move to the next change, Shift+F7 for previous. It is a checklist, but a meaningful one: every item creates evidence that the next step is safe.

      +

      Jamie: Before we leave Using the Accessible Diff Viewer, what is the practical point?

      +

      Alex: First, press Escape when done to close the viewer. It is like walking a hallway with named doors: read the sign, enter the right room, then confirm where you landed.

      +

      Jamie: Let's pause on Placing a comment. What should a learner take away from it?

      +

      Alex: Keep the learner anchored in Placing a comment. Screen reader users (VoiceOver on macOS).

      +

      Alex: First, navigate to the line you want to comment on in the diff. Then, press Ctrl+Shift+P, type "GitHub Pull Requests: Add Comment". After that, a text area opens below the line - NVDA announces the input focus. Finally, type your comment. It is like walking a hallway with named doors: read the sign, enter the right room, then confirm where you landed.

      +

      Jamie: Before we leave Placing a comment, what is the practical point?

      +

      Alex: First, press Tab to the Submit button, then Enter. The rhythm is simple: orient, act, verify, then continue.

      -

      Jamie: Let's pause on Reactions. What should a learner take away from it?

      -

      Alex: Keep the learner anchored in Reactions. GitHub reactions () are an efficient way to express agreement, appreciation, or concern without adding noise to a thread.

      -

      Alex: Keep the teaching thread moving. The reason Saved Replies - Your Accessibility Win matters is that GitHub lets you save frequently used responses as Saved Replies - reusable text snippets you can insert into any comment box with a few keystrokes. That gives the learner a simple foothold: this is a significant accessibility win for anyone who types the same comments repeatedly during triage, reviews, or issue management.

      -

      Jamie: Let's pause on Common uses. What should a learner take away from it?

      -

      Alex: Start with Common uses. There is something to understand, something to try, and something that proves the try worked.

      -

      Alex: The practical takeaway is this. "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.

      +

      Jamie: Let's pause on Opening the PR. What should a learner take away from it?

      +

      Alex: Start with Opening the PR. There is something to understand, something to try, and something that proves the try worked.

      +

      Alex: First, press Cmd+Shift+P, type "GitHub Pull Requests: View Pull Request". Then, navigate the PR tree with VO+Down Arrow. After that, press Return on a file to open its diff. The rhythm is simple: orient, act, verify, then continue.

      +

      Jamie: Let's pause on Accessible Diff Viewer. What should a learner take away from it?

      +

      Alex: Start with Accessible Diff Viewer. There is something to understand, something to try, and something that proves the try worked.

      +

      Alex: First, press F7 in the diff editor. Then, VoiceOver announces each change with clear "Removed" and "Added" labels. After that, navigate with F7/Shift+F7. Finally, press Escape to close. Think of it as a rail line: each stop confirms you are still on the right route before the next one.

      +

      Jamie: Let's pause on Comment placement. What should a learner take away from it?

      +

      Alex: Start with Comment placement. There is something to understand, something to try, and something that proves the try worked.

      +

      Alex: First, press Cmd+Shift+P, type "GitHub Pull Requests: Add Comment". Then, vO+Shift+Down Arrow to interact with the comment text area. After that, type your comment. Finally, vO+Shift+Up Arrow to stop interacting, then Tab to Submit. Treat it like a recipe: do not add the next ingredient until the previous one is actually in the bowl.

      -

      Jamie: Let's pause on Creating a Saved Reply. What should a learner take away from it?

      -

      Alex: Start with Creating a Saved Reply. There is something to understand, something to try, and something that proves the try worked.

      -

      Alex: First, navigate to github.com/settings/replies. Then, activate "Add a saved reply". After that, give it a title (e.g., "Good first issue claim") - this is what you search. Finally, type the full reply text in the body (Markdown is supported). Treat it like a recipe: do not add the next ingredient until the previous one is actually in the bowl.

      -

      Jamie: Let's pause on Using a Saved Reply in a comment. What should a learner take away from it?

      -

      Alex: Start with Using a Saved Reply in a comment. There is something to understand, something to try, and something that proves the try worked.

      -

      Alex: First, navigate to any comment text area. Then, activate the Saved Replies button (the speech bubble icon in the comment toolbar, or press Ctrl+. if enabled). After that, a dropdown appears showing your saved replies - type to filter by title. Finally, select the reply - it inserts into the text area. It is a checklist, but a meaningful one: every item creates evidence that the next step is safe.

      -

      Jamie: Before we leave Using a Saved Reply in a comment, what is the practical point?

      -

      Alex: First, edit as needed before submitting. It is like walking a hallway with named doors: read the sign, enter the right room, then confirm where you landed.

      -

      Alex: Keep the teaching thread moving. Keep the learner anchored in Screen reader path. Limit: GitHub allows up to 100 saved replies per account.

      +

      Jamie: Let's pause on Using the Accessible Diff Viewer (F7). What should a learner take away from it?

      +

      Alex: This is where Using the Accessible Diff Viewer (F7) becomes real: the Accessible Diff Viewer reads each change as a structured block. That matters in practice: This example is from a real Learning Room scenario: a contributor fixing the heading hierarchy in docs/keyboard-shortcuts.md by changing a level-4 heading to level-3, which is exactly what you look for when reviewing Challenge 2 PRs.

      +

      Alex: Treat examples as spoken recipes, not decorations. You may hear something like "Changed lines 14 to 14 in docs/keyboard-shortcuts.md; [Change 1 of 3]; Removed:; NVDA Single-Key Navigation; Added:; NVDA Single-Key Navigation". Read the command, understand what it changes, then run it only when the repository state matches the lesson.

      +

      Alex: Keep the teaching thread moving. Start with Navigation. There is something to understand, something to try, and something that proves the try worked.

      +

      Alex: The practical takeaway is this. F7 - jump to next change (next hunk). Shift+F7 - jump to previous change. Alt+F2 - open VS Code's Accessible View for additional context on the current item. Escape - close the Accessible Diff Viewer.

      +

      Jamie: Let's pause on What makes this better than the raw diff editor. What should a learner take away from it?

      +

      Alex: Start with What makes this better than the raw diff editor. There is something to understand, something to try, and something that proves the try worked.

      +

      Alex: The practical takeaway is this. Each change is announced as a discrete unit with clear "Removed:" and "Added:" labels. You hear the change number of total changes ("Change 3 of 12"). No table navigation required - purpose-built for sequential listening. Works with all three major screen readers without any special configuration.

      -

      Jamie: Let's pause on Learning Cards: Commenting Etiquette. What should a learner take away from it?

      -

      Alex: Start with Learning Cards: Commenting Etiquette. There is something to understand, something to try, and something that proves the try worked.

      -

      Alex: The practical takeaway is this. 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. 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.

      -

      Alex: Keep the teaching thread moving. Start with 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.". Think of it like entering a new building: first you find the lobby, then the room, then the door you actually need.

      -

      Jamie: Let's pause on Don't gatekeep knowledge. What should a learner take away from it?

      -

      Alex: Here is the plain-English version of Don't gatekeep knowledge. If a contributor makes a mistake because they didn't know something, explain the concept.

      +

      Alex: Keep the teaching thread moving. Start with Placing Comments in VS Code (GitHub PR Extension): From the diff editor with the GitHub PR extension. The next useful detail is this: Comments placed in VS Code sync to GitHub - they appear in the PR's Files Changed tab and the author receives the same notification.

      +

      Jamie: Let's pause on The Anatomy of a Useful Review Comment. What should a learner take away from it?

      +

      Alex: Here is the plain-English version of The Anatomy of a Useful Review Comment. A comment that helps the author is.

      +

      Alex: First, specific - link to the exact line and name the pattern you see. Then, educational - say why something matters, not just what to change. After that, graduated - signal whether this is blocking, or a preference. Treat it like a recipe: do not add the next ingredient until the previous one is actually in the bowl.

      +

      Alex: Keep the teaching thread moving. This is where Blocking example (reviewing a PR for docs/keyboard-shortcuts.md) becomes real: "The heading on line 34 uses (level 4) directly after (level 2), skipping heading level 3. That matters in practice: Screen reader users who navigate by heading level will miss any content between those two levels. The workshop is closer to rehearsal than lecture. You hear the move, try the move, and then check what changed.

      -

      Alex: Keep the teaching thread moving. This is where Ask questions instead of making demands becomes real: "Change this to use aria-label." "What do you think about using aria-label here instead? That matters in practice: Screen readers would then announce the button's purpose directly.".

      -

      Jamie: Let's pause on Distinguish opinion from requirement. What should a learner take away from it?

      -

      Alex: Keep the learner anchored in Distinguish opinion from requirement. If something is your stylistic preference but NOT a bug or correctness issue, say so. This is the part to say slowly: "The current implementation is correct.

      -

      Alex: Keep the teaching thread moving. The reason Approve explicitly matters is that 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! The interface gets friendlier when it stops being a wall of controls and starts being a set of named places.

      +

      Jamie: Let's pause on Non-blocking (nit) example (reviewing a PR for docs/welcome.md). What should a learner take away from it?

      +

      Alex: Keep the learner anchored in Non-blocking (nit) example (reviewing a PR for docs/welcome.md). "nit: The link text in the 'Getting Help' section reads 'click here for more information.' Screen reader users who navigate links out of context will hear only 'click here' with no destination. This is the part to say slowly: Consider 'See the accessibility setup guide' instead.

      +

      Alex: Keep the teaching thread moving. The reason Question example (reviewing a PR for docs/setup-guide.md) matters is that "The PR description says this fixes broken links in the setup guide, but the link on line 12 still points to /docs/old-setup. That gives the learner a simple foothold: am I reading the diff correctly, or was this link intentionally left?

      +

      Jamie: Let's pause on Prefixes That Set Expectations. What should a learner take away from it?

      +

      Alex: Start with Prefixes That Set Expectations: Using shorthand prefixes helps authors parse many comments quickly.

      -

      Jamie: Let's pause on Say thank you. What should a learner take away from it?

      -

      Alex: Start with Say thank you: When someone takes time to review your work, acknowledge it - even if you disagree with some feedback. The next useful detail is this: "Thanks so much for the thorough review!

      -

      Alex: Keep the teaching thread moving. Here is the plain-English version of Don't take feedback personally. Code review is about the code, not your worth as a person or developer. Put another way, even the most senior contributors receive change requests.

      -

      Jamie: Let's pause on Explain your choices. What should a learner take away from it?

      -

      Alex: This is where Explain your choices becomes real: if you are keeping your implementation despite feedback, explain why. That matters in practice: "I considered aria-label here, but I went with a visually-hidden instead because it allows translators to localize the text more easily.

      +

      Alex: Keep the teaching thread moving. Here is the plain-English version of How Many Comments Is Too Many? There is no hard limit, but quantity without prioritization is noise. Put another way, if you have 15 comments, make clear which 2-3 are blocking. It is like learning a transit route. The names of the stops matter because they tell you whether you are still going the right direction.

      +

      Jamie: Let's pause on "I want to verify the PR only changes what it claims". What should a learner take away from it?

      +

      Alex: This is where "I want to verify the PR only changes what it claims" becomes real: example: A PR says "Challenge 2: Add NVDA shortcut" but the file tree shows changes to both docs/keyboard-shortcuts.md and docs/welcome.md.

      +

      Alex: Keep the teaching thread moving. Keep the learner anchored in "I want to find all changes to one specific section". Example: A PR for Challenge 3 modified docs/welcome.md. This is the part to say slowly: You want to verify the [TODO] in the "Who Can Contribute?" section was filled in correctly.

      -

      Alex: Keep the teaching thread moving. Keep the learner anchored in Surface blockers early. Don't wait until you have finished a 500-line PR to mention that you weren't sure about the approach. A good GitHub workflow is like a well-run meeting: everyone knows the topic, the next action, and who has the floor.

      -

      Jamie: Let's pause on Inclusive Commenting for Accessibility Issues. What should a learner take away from it?

      -

      Alex: The reason Inclusive Commenting for Accessibility Issues matters is that when filing or discussing accessibility bugs, additional context helps.

      -

      Alex: The practical takeaway is this. 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.

      -

      Jamie: Let's pause on The "Good First Issue" Social Contract. What should a learner take away from it?

      -

      Alex: Start with The "Good First Issue" Social Contract: When a maintainer labels an issue good first issue, they are. The next useful detail is this: When you take a good first issue, your responsibilities.

      -

      Alex: The practical takeaway is this. Investing time - good first issues require extra documentation and mentorship. Signaling welcome - they want to support a new contributor.

      -

      Alex: First, comment to claim it - "Hi, I'd like to work on this. Can I be assigned?". Then, wait for assignment - do not start until assigned; two people working in parallel wastes everyone's time. After that, 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?". Finally, 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?". Think of it as a rail line: each stop confirms you are still on the right route before the next one.

      -

      Jamie: Before we leave The "Good First Issue" Social Contract, what is the practical point?

      -

      Alex: First, don't disappear - if you claim an issue, see it through or explicitly hand it back. Treat it like a recipe: do not add the next ingredient until the previous one is actually in the bowl.

      +

      Jamie: Why is the evidence prompt part of the teaching, not just grading?

      +

      Alex: The reason Exercises matters is that these exercises use the files in learning-room/docs/ in this repository. That gives the learner a simple foothold: all examples involve documentation changes - no code required.

      +

      Alex: Keep the teaching thread moving. Start with Exercise A - Complete a Web Review: Scenario: A contributor has submitted a pull request titled "Add screen reader tips to the setup guide." The PR modifies learning-room/docs/setup-guide.md. The next useful detail is this: Your job is to review it before it merges. Think of it like entering a new building: first you find the lobby, then the room, then the door you actually need.

      +

      Jamie: Let's pause on Step 1: Navigate to the Pull Request. What should a learner take away from it?

      +

      Alex: Here is the plain-English version of Step 1: Navigate to the Pull Request. How to know you're in the right place.

      +

      Alex: The practical takeaway is this. The PR title is visible at the top. You see a description box with text about what this PR does. You see tabs labeled "Conversation," "Commits," "Files Changed". Use Ctrl+F to search the PR list for "screen reader tips". Or ask in the workshop Slack - someone can share the exact URL.

      +

      Alex: First, open GitHub in your browser and navigate to the workshop repository (github.com/[your-fork]/[workshop-repo] or community-access/accessibility-agents). Then, click the Pull Requests tab (top navigation). After that, look for a PR titled "Add screen reader tips to the setup guide" - click it to open. Finally, you should now see the PR page with sections: Conversation, Commits, Files Changed. Treat it like a recipe: do not add the next ingredient until the previous one is actually in the bowl.

      -

      Jamie: Let's pause on When you receive harsh feedback. What should a learner take away from it?

      -

      Alex: Start with When you receive harsh feedback. There is something to understand, something to try, and something that proves the try worked.

      -

      Alex: First, take a breath before responding - there is no urgency; the thread will wait. Then, look for the valid concern underneath the harsh words. After that, respond to the concern, not the tone. Finally, if the behavior crosses into harassment, report it via the "." button on the comment → "Report". Treat it like a recipe: do not add the next ingredient until the previous one is actually in the bowl.

      -

      Jamie: Let's pause on When you disagree with a decision. What should a learner take away from it?

      -

      Alex: Start with When you disagree with a decision. There is something to understand, something to try, and something that proves the try worked.

      -

      Alex: First, make your case once, clearly and with evidence. Then, accept that the maintainer has the final say in their project. After that, if you strongly disagree, you can fork the project and take it in a different direction - this is legitimate in open source. It is a checklist, but a meaningful one: every item creates evidence that the next step is safe.

      -

      Jamie: Let's pause on When someone is rude to you. What should a learner take away from it?

      -

      Alex: Start with When someone is rude to you. There is something to understand, something to try, and something that proves the try worked.

      -

      Alex: First, you do not have to engage. Then, 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.". After that, report via GitHub's reporting tools if the behavior is abusive. It is like walking a hallway with named doors: read the sign, enter the right room, then confirm where you landed.

      +

      Jamie: Let's pause on Step 2: Read the PR Description. What should a learner take away from it?

      +

      Alex: Start with Step 2: Read the PR Description. There is something to understand, something to try, and something that proves the try worked.

      +

      Alex: The practical takeaway is this. Does the PR author explain what file changed? (should mention setup-guide.md). Does it explain why? (should mention "improve accessibility" or "add tips"). Is it clear enough that a reviewer can understand the goal without reading the diff? You can answer: "This PR adds [specific content] to [specific file] because [clear reason]". Example: "This PR adds screen reader usage tips to the setup guide because new users need accessibility guidance".

      +

      Alex: First, you are currently on the Conversation tab. Then, read the PR description (the text immediately under the PR title). After that, look for: "What does this PR change?" and "Why does it change it?". Finally, with screen reader: Navigate to the description with D (NVDA) or press Ctrl+Option+Up (VoiceOver) to find main landmarks, then read the content region. It is a checklist, but a meaningful one: every item creates evidence that the next step is safe.

      +

      Jamie: Let's pause on Step 3: Navigate to "Files Changed". What should a learner take away from it?

      +

      Alex: Start with Step 3: Navigate to "Files Changed". There is something to understand, something to try, and something that proves the try worked.

      +

      Alex: The practical takeaway is this. A section showing the file name setup-guide.md with a small badge showing "+20 −0" (20 lines added, 0 lines removed). Below it, the diff with removed lines (preceded by −) and added lines (preceded by +). Scroll up to see if there are other files. For this exercise, only setup-guide.md should be changed. If you see other files, confirm they are not modified (the badge should show "+0 −0" or no changes).

      +

      Alex: First, click the Files Changed tab (top of the PR page, to the right of "Commits"). Then, you are now viewing the diff. After that, with keyboard (all screen readers): Press T to jump to the diff table. The page focuses on the file comparison area. It is like walking a hallway with named doors: read the sign, enter the right room, then confirm where you landed.

      +

      Jamie: Let's pause on Step 4: Activate Focus Mode for Better Diff Reading. What should a learner take away from it?

      +

      Alex: The reason Step 4: Activate Focus Mode for Better Diff Reading matters is that with screen reader (once in Focus Mode). The interface gets friendlier when it stops being a wall of controls and starts being a set of named places.

      +

      Alex: The practical takeaway is this. The page simplifies: sidebars disappear. Only the diff is visible - easier for screen reader navigation and less cognitive load. The diff is now the main content area. NVDA/JAWS: Press T to jump to the diff table. VoiceOver: Navigate with VO+Right Arrow to find the table/content region. Read through the changes: ↓ arrow moves to each line.

      +

      Alex: First, look for a button labeled "Focus Mode" or an icon (usually at the top right of the diff area). Then, with keyboard: Press F to toggle Focus Mode (may need to be in the diff area first). After that, with mouse: Click the Focus Mode button/icon. The rhythm is simple: orient, act, verify, then continue.

      -

      Jamie: Let's pause on When you accidentally caused offense. What should a learner take away from it?

      -

      Alex: Start with When you accidentally caused offense. There is something to understand, something to try, and something that proves the try worked.

      -

      Alex: First, acknowledge it directly: "I can see how that came across as dismissive - that wasn't my intention.". Then, do not over-explain or defend excessively. After that, adjust going forward. The rhythm is simple: orient, act, verify, then continue.

      -

      Jamie: Let's pause on Writing Your First README. What should a learner take away from it?

      -

      Alex: Start with Writing Your First README: See also: Appendix W: GitHub Pages for publishing your README as a website. The next useful detail is this: A README is the front door of your project.

      -

      Alex: Keep the teaching thread moving. Here is the plain-English version of What belongs in a README. Every README should answer these questions, roughly in this order. Put another way, 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. It is like learning a transit route. The names of the stops matter because they tell you whether you are still going the right direction.

      +

      Jamie: Let's pause on Step 5: Find the Heading Hierarchy Issue. What should a learner take away from it?

      +

      Alex: Start with Step 5: Find the Heading Hierarchy Issue. There is something to understand, something to try, and something that proves the try worked.

      +

      Alex: The practical takeaway is this. Screen reader users navigate documents by heading level: 1 → 2 → 3 → 4. A skip from to breaks that navigation. When a user presses "jump to heading level 3," they'll find none, wondering if content is missing. You found the line with that violates hierarchy. You can say the line number and what heading text appears there. You understand why this is an accessibility problem.

      +

      Alex: First, read through the entire diff line by line. Pay special attention to lines starting. Then, you are looking for: a line with (four hashes, heading level 4) that comes directly after a (two hashes, heading level 2). After that, when you find it, note the exact line number shown in the diff. Think of it as a rail line: each stop confirms you are still on the right route before the next one.

      +

      Jamie: Let's pause on Step 6: Place a Blocking Review Comment on the Heading. What should a learner take away from it?

      +

      Alex: Here is the plain-English version of Step 6: Place a Blocking Review Comment on the Heading. If the comment button doesn't appear.

      +

      Alex: The practical takeaway is this. Your comment appears in the thread under that line. The PR author sees it and can make the fix. Make sure you're hovering over the line number area (left side of the line). Try refreshing the page and trying again. Or use the "Add a reply" field at the bottom of the PR and mention the line number manually.

      +

      Alex: First, find the diff line with the problematic heading. Then, hover your mouse over the line number on the left side of that line (or if using keyboard, navigate to that line in the table). After that, a button should appear (or press the Add Comment hotkey - usually C in GitHub). Finally, click it or press Enter to open a comment box. Treat it like a recipe: do not add the next ingredient until the previous one is actually in the bowl.

      +

      Jamie: Before we leave Step 6: Place a Blocking Review Comment on the Heading, what is the practical point?

      +

      Alex: First, press Space, then explain. Then, click the Comment button (or press Ctrl+Enter for keyboard submit). It is a checklist, but a meaningful one: every item creates evidence that the next step is safe.

      +

      Jamie: Let's pause on Step 7: Find the Link Text Issue. What should a learner take away from it?

      +

      Alex: Start with Step 7: Find the Link Text Issue. There is something to understand, something to try, and something that proves the try worked.

      +

      Alex: The practical takeaway is this. Screen reader users can ask their reader to "list all links on this page" - they hear only the link text. If the text is "click here," they have no context about where it goes. Descriptive link text is WCAG 2.4.4 (Link Purpose). You found a link with non-descriptive text. You can explain why "click here" is bad and what would be better.

      +

      Alex: First, continue reading the diff (from where you left off). Then, look for a line containing link text that reads "click here" or "click here for more information". After that, note the line number. It is a checklist, but a meaningful one: every item creates evidence that the next step is safe.

      -

      Jamie: Let's pause on Accessibility in READMEs. What should a learner take away from it?

      -

      Alex: This is where Accessibility in READMEs becomes real: your README is a web page -- GitHub renders it as HTML. That matters in practice: That means the same accessibility rules apply.

      -

      Alex: The practical takeaway is this. Alt text for images and badges. A badge that says is invisible to screen readers. Write 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 -- not Click here.

      -

      Alex: Keep the teaching thread moving. Keep the learner anchored in Good README vs. bad README. Bad: A single paragraph that says "This is my project. This is the part to say slowly: Run it with npm start." No headings, no license, no description of what the project does.

      -

      Jamie: Let's pause on Learning Cards: Writing Your First README. What should a learner take away from it?

      -

      Alex: Start with Learning Cards: Writing Your First README. There is something to understand, something to try, and something that proves the try worked.

      -

      Alex: The practical takeaway is this. 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: rather than an empty that reads as "image" with no context. Use real Markdown link text (installation guide) instead of bare URLs, so your screen reader announces the destination rather than spelling out a long URL. 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.

      +

      Jamie: Let's pause on Step 8: Place a Comment on the Link. What should a learner take away from it?

      +

      Alex: Keep the learner anchored in Step 8: Place a Comment on the Link. nit: means "nice-to-have improvement" (not blocking, but good to fix). A good GitHub workflow is like a well-run meeting: everyone knows the topic, the next action, and who has the floor.

      +

      Alex: First, find the line in the diff with the problematic link. Then, hover over the line number and click to open a comment box (or press C). After that, click Comment or press Ctrl+Enter. It is like walking a hallway with named doors: read the sign, enter the right room, then confirm where you landed.

      +

      Jamie: Let's pause on Step 9: Submit Your Review. What should a learner take away from it?

      +

      Alex: Start with Step 9: Submit Your Review. There is something to understand, something to try, and something that proves the try worked.

      +

      Alex: The practical takeaway is this. Comment - provide feedback but don't block (for minor notes). Approve - the PR is ready to merge. Request changes - this PR cannot merge until changes are made. Your review is submitted. The PR author gets a notification. The PR shows your review with the two comments.

      +

      Alex: First, look for a button labeled "Review changes" (usually at the top right of the page or bottom of comments). Then, click it (or navigate with keyboard and press Enter). After that, a dialog appears with options. Finally, select "Request changes" (you found two things to fix). The rhythm is simple: orient, act, verify, then continue.

      +

      Jamie: Before we leave Step 9: Submit Your Review, what is the practical point?

      +

      Alex: First, in the summary field, write: Found 2 accessibility issues that must be fixed before merging. Then, click "Submit review". Think of it as a rail line: each stop confirms you are still on the right route before the next one.

      +

      Jamie: Let's pause on Reflect on This Exercise. What should a learner take away from it?

      +

      Alex: Start with Reflect on This Exercise: Keep your answers - you'll need them for Chapter 16's Accessibility Agents exercise to compare manual review with agent-assisted review.

      +

      Alex: First, did heading-level navigation help? When you were looking for the issue, was it easier to navigate by heading level (1-6) than to scan every line? Then, would you have caught this without the exercise prompt? If you were a real reviewer not specifically looking for heading issues, would the diff have been obvious? After that, why does screen reader navigation matter? In one sentence, explain why a screen reader user's ability to jump through heading levels is important for this document. Think of it as a rail line: each stop confirms you are still on the right route before the next one.

      -

      Alex: Keep the teaching thread moving. Start with Community Health Files: Community health files tell contributors how your project operates before they write a single line of code. The next useful detail is this: 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. Think of it like entering a new building: first you find the lobby, then the room, then the door you actually need.

      -

      Jamie: Let's pause on CONTRIBUTING.md. What should a learner take away from it?

      -

      Alex: Here is the plain-English version of CONTRIBUTING.md. This file answers the question every newcomer asks: "How do I help?" A good CONTRIBUTING.md covers. Put another way, a sentence like "We are glad you are here" costs nothing and signals that newcomers are expected, not tolerated.

      -

      Alex: The practical takeaway is this. 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.

      -

      Alex: Keep the teaching thread moving. This is where CODE OF CONDUCT.md becomes real: a code of conduct sets the social contract for your project. That matters in practice: Without one, "acceptable behavior" is whatever each participant assumes it is -- and those assumptions vary widely.

      -

      Alex: The practical takeaway is this. 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.

      +

      Jamie: There are a lot of tools in play. How do we keep that from feeling like a contest?

      +

      Alex: Here is the plain-English version of Exercise B - Use the VS Code Accessible Diff Viewer. Scenario: Review the same pull request from Exercise A, this time entirely in VS Code. Put another way, you'll compare the browser experience with the VS Code experience.

      +

      Alex: Keep the teaching thread moving. Start with Prerequisites. There is something to understand, something to try, and something that proves the try worked.

      +

      Alex: The practical takeaway is this. VS Code must be installed on your machine. The GitHub Pull Requests extension must be installed (see Chapter 12 for installation). You must be signed into GitHub from VS Code (use Ctrl+Shift+P → "GitHub: Sign in").

      +

      Jamie: Let's pause on Step 1: Open the GitHub Pull Requests Extension. What should a learner take away from it?

      +

      Alex: Start with Step 1: Open the GitHub Pull Requests Extension. There is something to understand, something to try, and something that proves the try worked.

      +

      Alex: The practical takeaway is this. With mouse: Click the Extensions icon on the left sidebar (looks like four squares). The extension is listed as active. It mentions: "Review and manage GitHub pull requests and issues".

      +

      Alex: First, open VS Code. Then, with keyboard (all screen readers): Press Ctrl+Shift+X to open the Extensions sidebar. After that, search for "GitHub Pull Requests". Finally, if it's not installed, click Install. It is like walking a hallway with named doors: read the sign, enter the right room, then confirm where you landed.

      +

      Jamie: Before we leave Step 1: Open the GitHub Pull Requests Extension, what is the practical point?

      +

      Alex: First, if it is installed, click GitHub Pull Requests to view its details. The rhythm is simple: orient, act, verify, then continue.

      -

      Jamie: Let's pause on SECURITY.md. What should a learner take away from it?

      -

      Alex: Keep the learner anchored in SECURITY.md. See also: Appendix F: Git Security and Appendix P: Security Features for security best practices. This is the part to say slowly: If someone discovers a vulnerability in your project, you do not want them to file a public issue.

      -

      Alex: The practical takeaway is this. 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.

      -

      Alex: Keep the teaching thread moving. The reason LICENSE matters is that 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. That gives the learner a simple foothold: adding a LICENSE file is a one-time step that makes your project genuinely open source. The interface gets friendlier when it stops being a wall of controls and starts being a set of named places.

      -

      Jamie: Let's pause on Finding these files on GitHub. What should a learner take away from it?

      -

      Alex: Start with Finding these files on GitHub: Navigate to any repository and click Insights then Community Standards. The next useful detail is this: GitHub shows a checklist of which community health files are present and links to add any that are missing.

      +

      Jamie: Let's pause on Step 2: Open the Pull Requests Sidebar. What should a learner take away from it?

      +

      Alex: Start with Step 2: Open the Pull Requests Sidebar. There is something to understand, something to try, and something that proves the try worked.

      +

      Alex: The practical takeaway is this. With keyboard: The icon may not be keyboard-reachable directly; instead go to Step 3. VS Code opens a new editor tab for this PR. Below the PR title, you see a "Changes" section listing modified files. You should see setup-guide.md in the changes list. Use Ctrl+Shift+P → search GitHub Pull Requests: Open Pull Request. Paste the PR URL: https://github.com/[owner]/[repo]/pull/[number].

      +

      Alex: First, look for a GitHub-themed icon on the left sidebar (circle with octocat logo) - click it. Then, a sidebar appears showing open pull requests on repositories you have access to. After that, find the PR titled "Add screen reader tips to the setup guide" - it should appear in a list. Finally, click it to open. The rhythm is simple: orient, act, verify, then continue.

      +

      Jamie: Let's pause on Step 3: View the File Changes. What should a learner take away from it?

      +

      Alex: Start with Step 3: View the File Changes. There is something to understand, something to try, and something that proves the try worked.

      +

      Alex: The practical takeaway is this. A diff editor opens showing two columns. Left: the original file (before changes). Right: the new file (after changes). Different colors show added (green), removed (red), and modified (blue) lines. The file name appears at the top: setup-guide.md. NVDA/JAWS: The editor announces "Diff Editor - setup-guide.md".

      +

      Alex: First, in the Changes section, locate setup-guide.md. Then, click on the filename to open it. Think of it as a rail line: each stop confirms you are still on the right route before the next one.

      +

      Jamie: Let's pause on Step 4: Access the Accessible Diff Viewer. What should a learner take away from it?

      +

      Alex: Here is the plain-English version of Step 4: Access the Accessible Diff Viewer. If the Accessible Diff Viewer doesn't open. It is like learning a transit route. The names of the stops matter because they tell you whether you are still going the right direction.

      +

      Alex: The practical takeaway is this. With mouse: Look for a button or menu option labeled "Accessible View" or "Open Accessible Diff". If no button is visible, try Alt+F2 (VS Code Accessible View toggle). A new panel opens at the bottom of VS Code. The panel announces each change one at a time. Changes appear in text format with labels: "Added: " and "Removed: ". The panel is read-only (you read the changes, you don't edit here).

      +

      Alex: First, with keyboard: Press F7 to open the Accessible Diff Viewer. Treat it like a recipe: do not add the next ingredient until the previous one is actually in the bowl.

      -

      Alex: Keep the teaching thread moving. Start with Learning Cards: Community Health Files. There is something to understand, something to try, and something that proves the try worked.

      -

      Alex: The practical takeaway is this. 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. 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.

      -

      Jamie: How should someone choose between those options?

      -

      Alex: This is where When to Use Different Communication Channels becomes real: GitHub Discussions are separate from Issues. That matters in practice: Use Discussions for: "What do people think about X approach?" and Issues for: "The X button is broken.".

      -

      Alex: Use the comparison to make a decision, not to recite a table. The main contrasts are: PR comment means Feedback on a specific code change. PR review means Formal verdict (approve/request changes) with consolidated feedback. Discussion means Open-ended conversation, proposals, community Q&A.

      -

      Jamie: Let's pause on Try It: Rewrite One Comment. What should a learner take away from it?

      -

      Alex: Keep the learner anchored in Try It: Rewrite One Comment. Time: 2 minutes What you need: Just your brain. This is the part to say slowly: Read this code review comment and rewrite it to be constructive. A good GitHub workflow is like a well-run meeting: everyone knows the topic, the next action, and who has the floor.

      -

      Alex: First, what you noticed. Then, why it matters. After that, what you suggest. Finally, why the suggestion helps. It is like walking a hallway with named doors: read the sign, enter the right room, then confirm where you landed.

      -

      Jamie: Before we leave Try It: Rewrite One Comment, what is the practical point?

      -

      Alex: First, encouragement. The rhythm is simple: orient, act, verify, then continue.

      +

      Jamie: Let's pause on Step 5: Listen to and Understand the First Change. What should a learner take away from it?

      +

      Alex: Start with Step 5: Listen to and Understand the First Change. There is something to understand, something to try, and something that proves the try worked.

      +

      Alex: The practical takeaway is this. NVDA/JAWS: The Accessible Diff Viewer announces "Removed:" and "Added:" labels, followed by the line content. VoiceOver: The announcement may be similar; listen for "removed" and "added" keywords.

      +

      Alex: First, the first change is automatically announced when you open the Accessible Diff Viewer. Then, let your screen reader read it completely - don't interrupt. After that, write down the exact text announced. Finally, press the Down arrow to move to the next change. It is a checklist, but a meaningful one: every item creates evidence that the next step is safe.

      +

      Jamie: Let's pause on Step 6: Find the Heading Hierarchy Issue. What should a learner take away from it?

      +

      Alex: Start with Step 6: Find the Heading Hierarchy Issue. There is something to understand, something to try, and something that proves the try worked.

      +

      Alex: The practical takeaway is this. Four hashes ( ) indicate a level 4 heading. In the diff, you're looking for it appearing after a level 2 heading ( ). This creates the hierarchy skip you caught in Exercise A. You found the explanation in the Accessible Diff Viewer's format. You can explain: "The added line with directly follows a, skipping level 3". The Accessible Diff Viewer made this pattern clearer than scanning raw + characters.

      +

      Alex: First, continue pressing Down arrow to move through changes. Then, listen carefully for a change involving headings (lines starting with ). After that, specifically, listen for: "Added: " (four hashes). Finally, when you hear this, stop and write it down. It is like walking a hallway with named doors: read the sign, enter the right room, then confirm where you landed.

      +

      Jamie: Let's pause on Step 7: Locate the Heading Line and Add an Inline Comment. What should a learner take away from it?

      +

      Alex: Start with Step 7: Locate the Heading Line and Add an Inline Comment. There is something to understand, something to try, and something that proves the try worked.

      +

      Alex: The practical takeaway is this. Use Ctrl+F to open Find. Search for to locate it quickly. Press Enter to jump to it. With keyboard: The comment button may appear on the current line; navigate to it and press Enter. A comment box opens. You can type your comment.

      +

      Alex: First, once you identified the problematic heading in the Accessible Diff Viewer, close the Accessible Diff Viewer (press F7 again or Alt+F2). Then, you're back in the regular Diff Editor. After that, find the line with the problematic heading. Finally, close Find (Escape). The rhythm is simple: orient, act, verify, then continue.

      +

      Jamie: Before we leave Step 7: Locate the Heading Line and Add an Inline Comment, what is the practical point?

      +

      Alex: First, place your cursor on that line. Then, right-click and select "Add Comment" or press the Comment icon that appears on the left margin. Think of it as a rail line: each stop confirms you are still on the right route before the next one.

      -

      Jamie: Let's pause on Contributing to Open Source. What should a learner take away from it?

      -

      Alex: The reason Contributing to Open Source matters is that this section was previously Appendix T. That gives the learner a simple foothold: it is now part of the teaching narrative.

      -

      Alex: Keep the teaching thread moving. Start with A Guide for First-Time Contributors: You do not need to be a professional developer to contribute to open source. The next useful detail is this: Documentation, accessibility improvements, and bug reports are among the most valuable contributions any project can receive.

      -

      Jamie: Let's pause on 1. What Is Open Source? What should a learner take away from it?

      -

      Alex: Here is the plain-English version of 1. What Is Open Source? Open source software is software whose source code is publicly available. Put another way, anyone can read it, use it, and - in most cases - contribute to it.

      -

      Alex: The practical takeaway is this. 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.

      +

      Jamie: Let's pause on Step 8: Write Your Accessible Diff Comment. What should a learner take away from it?

      +

      Alex: Start with Step 8: Write Your Accessible Diff Comment: Why mention the Accessible Diff Viewer? Think of it like entering a new building: first you find the lobby, then the room, then the door you actually need.

      +

      Alex: The practical takeaway is this. It shows that the tool itself helps you see the issue. It documents how you caught the problem (useful for learning).

      +

      Alex: First, in the comment box, type. Then, press Ctrl+Enter or click Comment to submit. Think of it as a rail line: each stop confirms you are still on the right route before the next one.

      +

      Jamie: Let's pause on Step 9: Create a GitHub Pull Request Comment. What should a learner take away from it?

      +

      Alex: Here is the plain-English version of Step 9: Create a GitHub Pull Request Comment. Now you've reviewed the same PR in.

      +

      Alex: First, browser (Exercise A): You spot-checked line numbers manually. Then, VS Code (Exercise B): The Diff Editor plus Accessible Diff Viewer announced changes. After that, go to GitHub in your browser and open the same PR. Finally, scroll to the bottom and leave a comment in the Conversation tab. Treat it like a recipe: do not add the next ingredient until the previous one is actually in the bowl.

      +

      Jamie: Before we leave Step 9: Create a GitHub Pull Request Comment, what is the practical point?

      +

      Alex: First, click Comment. It is a checklist, but a meaningful one: every item creates evidence that the next step is safe.

      +

      Jamie: Before we leave Reflect on This Exercise, what is the practical point?

      +

      Alex: This is where Reflect on This Exercise becomes real: after completing Steps 1-9, answer. That matters in practice: In Chapter 16, you'll compare these manual reviews with the @pr-review agent's suggested changes.

      +

      Alex: First, announcement clarity: Did the "Added:" and "Removed:" labels from the Accessible Diff Viewer help you follow changes faster than reading + and − prefixes in the browser? Then, navigation pattern: Which tool required less back-and-forth clicking/tabbing to understand each change? After that, when would you use each? In one sentence: describe a type of PR where you'd prefer to use each tool. It is a checklist, but a meaningful one: every item creates evidence that the next step is safe.

      -

      Alex: Keep the teaching thread moving. This is where 2. Who Can Contribute? becomes real: contributors come from all backgrounds, skill levels, and countries. That matters in practice: 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. The workshop is closer to rehearsal than lecture. You hear the move, try the move, and then check what changed.

      -

      Jamie: Let's pause on 3. What Makes a Good First Contribution? What should a learner take away from it?

      -

      Alex: Start with 3. What Makes a Good First Contribution? There is something to understand, something to try, and something that proves the try worked.

      -

      Alex: The practical takeaway is this. 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.

      -

      Alex: Keep the teaching thread moving. The reason Signs a contribution is too large for a first attempt matters is that a well-executed small contribution is far more valuable than a large contribution that cannot be merged because it is out of scope.

      -

      Alex: The practical takeaway is this. 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.

      +

      Jamie: Let's pause on Exercise C - Compare and Reflect. What should a learner take away from it?

      +

      Alex: Keep the learner anchored in Exercise C - Compare and Reflect. Your Mission: Synthesize what you learned from the manual code reviews (Exercises A & B) and document your findings. This is the part to say slowly: What You'll Learn: Which tools work best for different scenarios, and how your manual review skills prepare you to use AI agents effectively.

      +

      Alex: Keep the teaching thread moving. The reason Step 1: Gather Your Data matters is that before writing your reflection, collect all the information you gathered. That gives the learner a simple foothold: write these down (in a text editor, on paper, or mentally) - you'll reference them in Steps 2-4. The interface gets friendlier when it stops being a wall of controls and starts being a set of named places.

      +

      Alex: The practical takeaway is this. Which line number had the heading hierarchy skip? Which line number had the link text issue? How many steps did it take to find each issue? Did you use screen reader commands or visual scanning more?

      +

      Jamie: Let's pause on Step 2: Navigate to the PR and Leave Your Reflection Comment. What should a learner take away from it?

      +

      Alex: Start with Step 2: Navigate to the PR and Leave Your Reflection Comment. There is something to understand, something to try, and something that proves the try worked.

      +

      Alex: The practical takeaway is this. A text editing area with formatting options (Bold, Italic, Link, etc.). A Comment button below the text area.

      +

      Alex: First, go to GitHub in your browser. Then, open the same PR ("Add screen reader tips to the setup guide"). After that, scroll to the Conversation tab. Finally, scroll all the way down to the comment box at the bottom (labeled "Leave a comment" or "Add a comment"). Think of it as a rail line: each stop confirms you are still on the right route before the next one.

      +

      Jamie: Before we leave Step 2: Navigate to the PR and Leave Your Reflection Comment, what is the practical point?

      +

      Alex: First, click in the comment box. Treat it like a recipe: do not add the next ingredient until the previous one is actually in the bowl.

      -

      Jamie: Let's pause on 4. Finding Something to Work On. What should a learner take away from it?

      -

      Alex: Start with 4. Finding Something to Work On: Most open source projects label issues that are suitable for new contributors. The next useful detail is this: How to search: On any GitHub repository, go to Issues → filter by label.

      -

      Alex: Keep the teaching thread moving. Start with Learning Cards: Finding Something to Work On. There is something to understand, something to try, and something that proves the try worked.

      -

      Alex: The practical takeaway is this. 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. 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.

      -

      Jamie: What is the pre-flight check here?

      -

      Alex: This is where 5. Reading an Issue Before You Start becomes real: before commenting "I'll take this" on an issue, ask yourself. That matters in practice: 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.

      -

      Alex: The practical takeaway is this. 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.

      +

      Alex: Keep the teaching thread moving. Here is the plain-English version of Step 3: Write Your Comparison. Type your response to these three questions. Put another way, be specific - reference exact tools, steps, and what you discovered.

      +

      Jamie: Let's pause on Step 4: Review Your Comment. What should a learner take away from it?

      +

      Alex: Start with Step 4: Review Your Comment. There is something to understand, something to try, and something that proves the try worked.

      +

      Alex: The practical takeaway is this. Is it clear which tool I preferred? Did I explain why with concrete examples? Am I describing the real-world impact accurately? Would someone else reading this understand how I caught the issue?

      +

      Alex: First, before submitting, re-read your comment using your screen reader or by reading aloud. Then, ask yourself. After that, make any corrections needed. Finally, do not submit yet - continue to Step 5. It is a checklist, but a meaningful one: every item creates evidence that the next step is safe.

      +

      Jamie: Let's pause on Step 5: Submit Your Reflection. What should a learner take away from it?

      +

      Alex: Start with Step 5: Submit Your Reflection. There is something to understand, something to try, and something that proves the try worked.

      +

      Alex: The practical takeaway is this. Your comment is now visible on the PR. Other reviewers can see your comparison. You have completed the three-part exercise series. Your comment appears on the PR thread. It includes all three reflections. The PR author and other reviewers can see your thought process.

      +

      Alex: First, locate the Comment button at the bottom right of the comment box. Then, with keyboard: Press Tab until the Comment button is focused, then Enter. After that, with mouse: Click the Comment button. Finally, your comment is submitted and appears on the PR page. It is like walking a hallway with named doors: read the sign, enter the right room, then confirm where you landed.

      -

      Jamie: Let's pause on Tool Cards: Fork, Clone, and Contribute. What should a learner take away from it?

      -

      Alex: Start with Tool Cards: Fork, Clone, and Contribute. There is something to understand, something to try, and something that proves the try worked.

      -

      Alex: First, click Fork on the repository page, then Create fork. Then, edit files directly in your fork's web interface. After that, click Contribute Open pull request to submit back to the original. Finally, fork the repo on github.com first. It is like walking a hallway with named doors: read the sign, enter the right room, then confirm where you landed.

      -

      Jamie: Before we leave Tool Cards: Fork, Clone, and Contribute, what is the practical point?

      -

      Alex: First, navigate to your fork and press. to open in the web editor. Then, edit, commit, and create a PR from the Source Control panel. After that, fork on github.com, then clone your fork: Ctrl+Shift+P Git: Clone. Finally, create a branch, make edits, commit and push. The rhythm is simple: orient, act, verify, then continue.

      -

      Alex: Treat examples as spoken recipes, not decorations. You may hear something like 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. Read the command, understand what it changes, then run it only when the repository state matches the lesson.

      -

      Jamie: Let's pause on The Basic Workflow. What should a learner take away from it?

      -

      Alex: Start with The Basic Workflow. There is something to understand, something to try, and something that proves the try worked.

      -

      Alex: First, fork the repository - creates your own copy on GitHub. Then, clone your fork to your computer (or open a Codespace - see Appendix N). After that, create a branch - name it something descriptive: fix/broken-link-setup-guide. Finally, make your change - edit the file, save, verify. The rhythm is simple: orient, act, verify, then continue.

      -

      Jamie: Before we leave The Basic Workflow, what is the practical point?

      -

      Alex: First, commit with a clear message - "Fix broken link in setup-guide.md line 34". Then, push to your fork. After that, open a pull request from your branch to the original repository's default branch. Finally, respond to review feedback - maintainers may ask for changes; this is normal and not a rejection. Think of it as a rail line: each stop confirms you are still on the right route before the next one.

      -

      Alex: Keep the teaching thread moving. Start with Writing a Good PR Description: Example: Fixed a broken link on line 34 of setup-guide.md. The next useful detail is this: The link pointed to /docs/old-setup which no longer exists. Think of it like entering a new building: first you find the lobby, then the room, then the door you actually need.

      -

      Alex: The practical takeaway is this. What did you change? Why was the change needed? How did you verify it works?

      +

      Jamie: Let's pause on Step 6: Checkpoint - Validate Your Learning. What should a learner take away from it?

      +

      Alex: The reason Step 6: Checkpoint - Validate Your Learning matters is that before moving forward, verify you understand. That gives the learner a simple foothold: if you can answer all three, you're ready for the next chapter.

      +

      Alex: The practical takeaway is this. Expected answer: Something like "Screen readers let users navigate by heading level (pressing 3 jumps to H3), so skipping a level makes users think content is missing.". Expected answer: e.g., "Browser: finding context in discussions. VS Code: linear reading of changes.". Expected answer: Something like "Open the document in a browser, use screen reader heading navigation, and confirm I can reach all levels (H2, H3, H4).".

      +

      Alex: First, heading Hierarchy: Can you explain in one sentence why a → skip breaks screen reader navigation? Then, tool Strengths: For each tool you used, name one task it made easier. After that, real-World Testing: How would you test the heading issue in the published document (not the PR diff)? The rhythm is simple: orient, act, verify, then continue.

      +

      Alex: Keep the teaching thread moving. Start with Using GitHub Copilot to Understand Code Changes: Reviewing code is about understanding what changed, why it changed, and whether the change is safe and correct. The next useful detail is this: GitHub Copilot can help you gather and understand information about code changes - especially when diffs are large, complex, or involve unfamiliar frameworks.

      +

      Jamie: Let's pause on When to Use Copilot During Code Review. What should a learner take away from it?

      +

      Alex: Here is the plain-English version of When to Use Copilot During Code Review. Copilot is most useful for answering these questions.

      +

      Alex: First, "What does this code do?" - you're reading unfamiliar syntax or a framework you don't know well. Then, "Why might this change break something?" - you need to understand dependencies or side effects. After that, "Is this pattern safe?" - you want to verify that the approach follows best practices. Finally, "What would be a better way to write this?" - you're looking for alternatives to suggest. Treat it like a recipe: do not add the next ingredient until the previous one is actually in the bowl.

      +

      Jamie: Before we leave When to Use Copilot During Code Review, what is the practical point?

      +

      Alex: First, "Does this match the PR's description?" - the change seems to do more (or less) than claimed. It is a checklist, but a meaningful one: every item creates evidence that the next step is safe.

      -

      Jamie: How should someone ask for help in a way that gets them unstuck faster?

      -

      Alex: Here is the plain-English version of 7. Getting Help. It is always acceptable to ask a question on an issue or pull request. Put another way, 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.

      -

      Alex: The practical takeaway is this. 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.

      -

      Alex: Keep the teaching thread moving. This is where 8. After Your Contribution Is Merged becomes real: this matters for your GitHub profile. That matters in practice: 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.

      -

      Alex: The practical takeaway is this. 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.

      -

      Jamie: Let's pause on 9. Building a Contribution Habit. What should a learner take away from it?

      -

      Alex: Keep the learner anchored in 9. Building a Contribution Habit. The hardest part of open source contribution is starting. This is the part to say slowly: 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.

      +

      Jamie: Let's pause on In VS Code with an Open Diff. What should a learner take away from it?

      +

      Alex: Start with In VS Code with an Open Diff. There is something to understand, something to try, and something that proves the try worked.

      +

      Alex: First, open the PR using the GitHub Pull Requests extension (see Part 2). Then, open the diff for any file. After that, select a block of code that confuses you (highlight it). Finally, open Copilot Chat: Ctrl+Shift+I. It is a checklist, but a meaningful one: every item creates evidence that the next step is safe.

      +

      Jamie: Before we leave In VS Code with an Open Diff, what is the practical point?

      +

      Alex: First, Copilot reads the selected code and answers in the chat. It is like walking a hallway with named doors: read the sign, enter the right room, then confirm where you landed.

      +

      Jamie: Let's pause on On GitHub.com (Web Interface). What should a learner take away from it?

      +

      Alex: Keep the learner anchored in On GitHub.com (Web Interface). Another option: Use the GitHub Copilot inline suggestions on GitHub.com.

      +

      Alex: The practical takeaway is this. Some GitHub PRs show Copilot insights directly in the diff (as of early 2026). If you see a lightbulb icon, click it to see Copilot's suggestion about that line.

      +

      Alex: First, open the PR's Files Changed tab. Then, focus on a line or section you want to understand better. After that, in VS Code Copilot Chat (not in the browser - Copilot Chat doesn't work directly in browser diffs yet). Finally, copy the confusing code, paste it into chat, and ask Copilot to explain. It is like walking a hallway with named doors: read the sign, enter the right room, then confirm where you landed.

      +

      Alex: Keep the teaching thread moving. The reason Copilot Limitations During Review (Critical to Know) matters is that this is why manual review is essential: You have context (project history, team decisions, user impact) that Copilot does not. That gives the learner a simple foothold: use Copilot to understand, then use your judgment to decide.

      +

      Alex: The practical takeaway is this. See the whole project - it sees only what you show it (the selected diff, not the context of the entire codebase). Verify correctness - it can explain what code does, but not whether it's correct for your specific use case. Understand intent - it reads the code, not the author's mind or the PR description. Catch all risks - it can spot common patterns, but not edge cases unique to your project.

      -

      Alex: Keep the teaching thread moving. The reason Practical habits matters is that challenge Time: Complete Challenge 8: The Culture Layer in the Challenge Hub, then advance to Chapter 09: Labels, Milestones and Projects. That gives the learner a simple foothold: next: Chapter 09: Labels, Milestones, and Projects Back: Chapter 07: Merge Conflicts Related appendices: Appendix M: Accessibility Standards Appendix F: Git Security Appendix O: Branch Protection. The interface gets friendlier when it stops being a wall of controls and starts being a set of named places.

      -

      Alex: The practical takeaway is this. 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.

      +

      Jamie: Let's pause on Best Practices. What should a learner take away from it?

      +

      Alex: Start with Best Practices. There is something to understand, something to try, and something that proves the try worked.

      +

      Alex: First, read the diff manually first - you spot the big picture before asking Copilot details. Then, ask Copilot specific questions - not "review this code" but "does this regex handle Unicode?". After that, fact-check Copilot's answers - it can be confidently wrong, especially about frameworks or domains it has less training data. Finally, combine Copilot with manual analysis - ask Copilot to explain, then verify by checking the PR description or looking for related files. Think of it as a rail line: each stop confirms you are still on the right route before the next one.

      +

      Jamie: Before we leave Best Practices, what is the practical point?

      +

      Alex: First, use Copilot to draft comments - type Draft a comment about [issue] for this PR and edit Copilot's suggestion to match your tone. Treat it like a recipe: do not add the next ingredient until the previous one is actually in the bowl.

      +

      Alex: Keep the teaching thread moving. Here is the plain-English version of What Comes Next. Your manual code review skills - identifying heading issues, catching link text problems, understanding screen reader navigation, gathering information with Copilot - are the foundation for understanding automated review. Put another way, in Chapter 16 (Accessibility Agents), you'll meet a full team of agents designed to amplify these skills. It is like learning a transit route. The names of the stops matter because they tell you whether you are still going the right direction.

      +

      Jamie: Let's pause on Part 4: The Reviewer's Craft. What should a learner take away from it?

      +

      Alex: This is where The Reviewer's Craft becomes real: parts 1 through 3 taught you the mechanics -- how to read diffs, leave comments, and use Copilot to understand unfamiliar code. That matters in practice: This part covers something equally important: how to think like a reviewer.

      -

      Jamie: What is the final checkpoint?

      -

      Alex: You should be able to point to the evidence, explain the action, and describe what you would do next if this were a real open source project. If you can teach the move back, you have learned it.

      -

      Jamie: And if they get stuck?

      -

      Alex: Read the latest message, not the loudest worry. Check the issue, the branch, the pull request, the status check, or the bot comment. Then ask for help with those facts in hand. That is how professionals collaborate.

      -
      - +

      Alex: Keep the teaching thread moving. Keep the learner anchored in What to Look for in a Review. Every PR is different, but most reviews benefit from scanning across these five categories. This is the part to say slowly: You do not need to check every category exhaustively on every PR.

      +

      Jamie: Let's pause on The Three Review Actions. What should a learner take away from it?

      +

      Alex: The reason The Three Review Actions matters is that when you submit a review on GitHub, you choose one of three actions. That gives the learner a simple foothold: picking the right one matters because it signals your intent to the author and to anyone else watching the PR.

      +

      Alex: First, did you find a bug, security issue, or broken test? -- Request Changes. Then, does the code do something different from what the description says? -- Request Changes. After that, does everything work, with maybe a few style nits? -- Approve (mention the nits in a comment). Finally, do you have questions or optional suggestions? -- Comment. The rhythm is simple: orient, act, verify, then continue.

      +

      Alex: Keep the teaching thread moving. Start with Writing Constructive Feedback: The way you phrase feedback determines whether the author feels supported or attacked. The next useful detail is this: Before pointing out problems, acknowledge something the author did well. Think of it like entering a new building: first you find the lobby, then the room, then the door you actually need.

      -

      Challenge 04: Branch Out

      -

      Creating a safe working branch and understanding why branches protect main.

      -
      -Read Transcript - Challenge 04: Branch Out - -

      Transcript

      -

      Alex: Welcome to Challenge Coach: Branch Out. I am Alex. Before you do the task, we are going to make the skill feel concrete enough to practice.

      -

      Jamie: And I am Jamie. I will keep asking what the learner should do, what evidence counts, and how to recover if the page does something unexpected.

      -
      -

      Alex: The skill focus is Creating a safe working branch and understanding why branches protect main. This is rehearsal for real contribution, so the evidence matters because it proves the move happened.

      -

      Jamie: So the challenge has to leave the learner with both confidence and a trail of evidence.

      -

      Alex: Exactly. Evidence is not busywork. It is how a learner, a facilitator, and a future maintainer can understand what changed and why.

      +

      Jamie: Let's pause on The Reviewer's Checklist. What should a learner take away from it?

      +

      Alex: Here is the plain-English version of The Reviewer's Checklist. Run through this list mentally (or copy it into your notes) for every PR you review.

      +

      Alex: The practical takeaway is this. [ ] I read the PR description before reading the code. [ ] The code does what the description says it does. [ ] The change does not include unrelated modifications. [ ] Variable and function names are clear. [ ] I checked for accessibility: labels, headings, keyboard reach, contrast. [ ] I verified no existing behavior is broken by the change.

      +

      Alex: Keep the teaching thread moving. This is where Reviewing as a Learning Tool becomes real: reviewing is not just a gate to keep bad code out. That matters in practice: It is one of the fastest ways to grow as a developer.

      +

      Jamie: Let's pause on Learning Cards: The Reviewer's Craft. What should a learner take away from it?

      +

      Alex: Start with Learning Cards: The Reviewer's Craft. There is something to understand, something to try, and something that proves the try worked.

      +

      Alex: The practical takeaway is this. Jump between changed hunks in a diff with Alt+F5 (next change) and Shift+Alt+F5 (previous change) to scan for scope creep efficiently. Use Alt+F2 (Accessible View) on a Copilot-generated review summary to read the full text with arrow keys before posting. When leaving feedback, mention specific line numbers ("Line 42 skips from h2 to h4") so the author can navigate directly with Ctrl+G. The three review actions (Approve, Request Changes, Comment) are shown as clearly labeled radio buttons in the review submission form. Use the reviewer checklist in this section as a mental framework -- copy it into your notes and check items off as you review each PR. The diff view uses green and red backgrounds for added/removed lines; pair with a High Contrast theme if these colors are hard to distinguish.

      -

      Jamie: What makes this practice feel low-stakes but still real?

      -

      Alex: Start with Challenge 4: Branch Out: What you will do: Create a personal branch named learn/YOUR-USERNAME where you will make your Day 1 changes.

      -

      Alex: A solid Git habit is to know which branch you are on, what changed, and what confirmation you expect before you run the next command.

      -

      Jamie: How would you walk the room through that step by step?

      -

      Alex: Start with Instructions. There is something to understand, something to try, and something that proves the try worked.

      -

      Alex: First, make sure you are on the Code tab of the learning-room repository. Then, find the branch dropdown (it shows "main" by default). After that, type learn/YOUR-USERNAME (replace YOUR-USERNAME with your actual GitHub username). Finally, select Create branch: learn/YOUR-USERNAME from main. Treat it like a recipe: do not add the next ingredient until the previous one is actually in the bowl.

      -

      Jamie: What is the one idea that makes the next few steps less mysterious?

      -

      Alex: This is where Branch naming convention becomes real: your branch name must follow this pattern: learn/ followed by your GitHub username. That matters in practice: This naming convention helps facilitators and automation identify your work.

      -

      Alex: That shows up in the workshop in a few specific ways. learn/octocat. learn/mona-lisa. learn/student42.

      +

      Alex: Keep the teaching thread moving. The reason Day 2 Teaser: The Full Accessibility Agents Review Ecosystem matters is that chapter 16 shows you how to leverage 50+ specialized agents to make your reviews faster, more consistent, and more thorough - while staying in full control of what you post. The interface gets friendlier when it stops being a wall of controls and starts being a set of named places.

      +

      Jamie: How should someone ask for help in a way that gets them unstuck faster?

      +

      Alex: Start with The Agents That Help With Code Review: Accessibility Review Agents (when code affects UI/UX).

      +

      Alex: The practical takeaway is this. @pr-review - Generates a full-draft PR review with line-numbered diff maps, risk assessment, before/after snapshots, and suggested inline comments. You edit and post it under your name. @pr-author-checklist - Before you even submit your PR, use this to verify you haven't missed setup steps, accessibility checks, or documentation. @insiders-a11y-tracker - Monitors your PR for accessibility-sensitive changes: WCAG violations, heading hierarchy issues, link text quality, keyboard navigation impacts. @developer-hub - Orchestrates explanations for unfamiliar code, patterns, or frameworks you're reviewing. @python-specialist - If your PR contains Python code, this agent explains patterns, spots accessibility issues, and suggests improvements. @wxpython-specialist - For desktop GUI code, helps verify accessible widget patterns and focus management.

      +

      Jamie: Let's pause on How It Works. What should a learner take away from it?

      +

      Alex: Start with How It Works. There is something to understand, something to try, and something that proves the try worked.

      +

      Alex: First, review manually first (you just did this with Exercises A, B, C). Then, run an agent - @pr-review review PR 14 generates a draft in seconds. After that, edit the agent's draft - you add context, remove noise, correct errors. Finally, post your review - it now has both AI efficiency and your human judgment. Treat it like a recipe: do not add the next ingredient until the previous one is actually in the bowl.

      +

      Jamie: Before we leave How It Works, what is the practical point?

      +

      Alex: First, the agent tracks impact - @insiders-a11y-tracker monitors whether your accessibility feedback was addressed. It is a checklist, but a meaningful one: every item creates evidence that the next step is safe.

      -

      Alex: Now bring the learner back to the room. Keep the learner anchored in Peer simulation check. Open the peer-simulation PR and notice its branch name. This is the part to say slowly: If you have a real buddy, ask whether they created their branch and help them find the branch dropdown if they are stuck.

      -

      Jamie: What is the ordered workflow?

      -

      Alex: The reason On github.com matters is that you can switch to it using the same dropdown.

      -

      Alex: First, go to the repository's Code tab. Then, click the branch dropdown (it says "main"). After that, type a new branch name like fix/welcome-todo. Finally, click "Create branch: fix/welcome-todo from main". The rhythm is simple: orient, act, verify, then continue.

      -

      Alex: The useful habit is simple: orient first, act second, verify third. That pause before acting is part of the work.

      -

      Jamie: How do you keep commands from becoming magic words?

      -

      Alex: Start with In VS Code (with Git): Or use the Source Control sidebar: click the branch name in the bottom-left status bar, then select "Create new branch.". Think of it like entering a new building: first you find the lobby, then the room, then the door you actually need.

      -

      Alex: Treat examples as spoken recipes, not decorations. You may hear something like git checkout -b fix/welcome-todo. Read the command, understand what it changes, then run it only when the repository state matches the lesson.

      +

      Jamie: Let's pause on The Principle: Skill First, Agent Second. What should a learner take away from it?

      +

      Alex: This is where The Principle: Skill First, Agent Second becomes real: why do this manually before using agents? That matters in practice: Manual reviews teach you what to look for.

      +

      Alex: The practical takeaway is this. You understand what the agent is doing (you did it manually). You evaluate the agent's output critically (you know what right looks like). You add judgment the agent lacks (context, intent, team decisions). You verify the agent didn't miss anything important.

      +

      Jamie: Let's pause on A Real Example: The Flow. What should a learner take away from it?

      +

      Alex: Keep the learner anchored in A Real Example: The Flow. Manual Review (your work in part 1-2). This is the part to say slowly: Agent-Assisted Review (what you'll do in Chapter 19). A good GitHub workflow is like a well-run meeting: everyone knows the topic, the next action, and who has the floor.

      +

      Alex: The practical takeaway is this. Read diff, identify heading hierarchy skip. Write comment explaining why it matters. Submit your verdict.

      +

      Alex: First, run: @pr-review review PR 14. Then, agent generates a draft review covering the heading skip, link text, and 5 other issues. After that, you read the draft and notice: "the agent's explanation of the heading skip is good, but it missed that the link text on line 23 is still vague. Let me add that.". Finally, you post the agent's review + your additions. It is like walking a hallway with named doors: read the sign, enter the right room, then confirm where you landed.

      +

      Jamie: Before we leave A Real Example: The Flow, what is the practical point?

      +

      Alex: First, next time you review a similar PR, the agent works faster because it learned from your feedback. The rhythm is simple: orient, act, verify, then continue.

      +

      Jamie: Let's pause on How to Be an Effective and Respectful Open Source Contributor. What should a learner take away from it?

      +

      Alex: The reason How to Be an Effective and Respectful Open Source Contributor matters is that technical skills get your code into a project. That gives the learner a simple foothold: communication skills keep you welcomed in the community.

      -

      Jamie: What does the learner do first, second, and then after that?

      -

      Alex: Start with In GitHub Desktop. There is something to understand, something to try, and something that proves the try worked.

      -

      Alex: First, click the Current Branch dropdown. Then, click "New Branch". After that, enter the name fix/welcome-todo. Finally, confirm it is based on main. Treat it like a recipe: do not add the next ingredient until the previous one is actually in the bowl.

      -

      Jamie: What should happen before anyone copies and runs it?

      -

      Alex: Start with With GitHub CLI. There is something to understand, something to try, and something that proves the try worked.

      -

      Alex: Treat examples as spoken recipes, not decorations. You may hear something like gh repo clone the workshop organization/learning-room-your username; cd learning-room; git checkout -b fix/welcome-todo. Read the command, understand what it changes, then run it only when the repository state matches the lesson.

      -

      Jamie: Where do you want a learner to place their attention here?

      -

      Alex: Keep the learner anchored in Branch naming. Good branch names are short and descriptive. This is the part to say slowly: The convention type/description is common but not required.

      -

      Alex: These are the details that keep the idea from floating away. fix/welcome-todo -- fixing a TODO in welcome.md. feature/add-schedule-link -- adding a new link. docs/update-readme -- documentation change.

      +

      Alex: Keep the teaching thread moving. Start with Workshop Recommendation (Chapter 8): Chapter 8 is a communication and culture chapter.

      +

      Alex: The practical takeaway is this. There are 1 guided reflection (no bot grading). Automation check: none - communication quality is too subjective for fair automated scoring. The evidence is structured reflection comment on your assigned challenge issue. The pattern is read, reflect, commit to one behavior.

      +

      Jamie: Let's pause on Chapter 8 Challenge Set. What should a learner take away from it?

      +

      Alex: Start with Chapter 8 Challenge Set. There is something to understand, something to try, and something that proves the try worked.

      +

      Alex: First, guided reflection - read the chapter, then post a short reflection comment committing to three specific collaboration behaviors. Treat it like a recipe: do not add the next ingredient until the previous one is actually in the bowl.

      +

      Jamie: Let's pause on Challenge 8.1 Step-by-Step: Guided Reflection. What should a learner take away from it?

      +

      Alex: This is where Challenge 8.1 Step-by-Step: Guided Reflection becomes real: identify three concrete communication behaviors you will practice during the rest of the workshop. That matters in practice: your assigned Chapter 8 challenge issue in your Learning Room repository on GitHub.com. The workshop is closer to rehearsal than lecture. You hear the move, try the move, and then check what changed.

      +

      Alex: The practical takeaway is this. 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.".

      +

      Alex: First, read through the chapter content below, paying attention to the sections on GitHub Flow, constructive feedback, and asking for help. Then, as you read, think about one situation from Day 1 where communication helped (or could have helped) you. After that, open your assigned Chapter 8 challenge issue (the one titled "Chapter 8.1: Guided Reflection (@yourname)"). Finally, scroll to the comment box at the bottom of the issue. It is a checklist, but a meaningful one: every item creates evidence that the next step is safe.

      +

      Jamie: Before we leave Challenge 8.1 Step-by-Step: Guided Reflection, what is the practical point?

      +

      Alex: First, post a reflection comment using this format. Then, for each prompt, write one specific, actionable sentence - not a vague goal. After that, activate the Comment button (or press Ctrl+Enter). It is like walking a hallway with named doors: read the sign, enter the right room, then confirm where you landed.

      -

      Alex: Before the learner moves on. The reason What matters matters is that the learning objective is understanding that branches let you work in isolation without affecting main. That gives the learner a simple foothold: if you created any branch with any name, you completed this challenge. The interface gets friendlier when it stops being a wall of controls and starts being a set of named places.

      -

      Jamie: What would you say to someone who is already bracing for this to be too much?

      -

      Alex: Start with What Is the Learning Room?: The Learning Room is your own private GitHub repository for the workshop. The next useful detail is this: When you accept the GitHub Classroom assignment in Block 0, GitHub copies the Community-Access/learning-room-template repository into the workshop classroom organization as the workshop organization/learning-room-your username.

      -

      Alex: Hold that next to this. Here is the plain-English version of Why a Per-Student Repo? GitHub Classroom gives each participant their own repository for three reasons. Put another way, 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.

      -

      Alex: The practical anchors are these. 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.

      +

      Jamie: Let's pause on Completing Chapter 8: Submit Your Evidence. What should a learner take away from it?

      +

      Alex: Keep the learner anchored in Completing Chapter 8: Submit Your Evidence. The reflection comment itself is your evidence. This is the part to say slowly: The facilitator reviews your comment for specificity.

      +

      Alex: The practical takeaway is this. 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.

      +

      Jamie: Let's pause on If You Get Stuck. What should a learner take away from it?

      +

      Alex: Start with If You Get Stuck. There is something to understand, something to try, and something that proves the try worked.

      +

      Alex: First, use one simple sentence per prompt - do not overthink it. Then, focus on one real behavior you can start doing today, not an abstract principle. After that, if writing feels hard, draft bullet points first in a text editor, then paste into the comment. Finally, look at the "Giving Feedback" and "Asking for Help" sections in this chapter for concrete examples. Think of it as a rail line: each stop confirms you are still on the right route before the next one.

      +

      Jamie: Let's pause on If You Get Stuck. What should a learner take away from it?

      +

      Alex: First, ask facilitator for one example response and adapt it to your own words. Then, finished but not sure you did it right? Compare your work against the Challenge 8 reference solution. Treat it like a recipe: do not add the next ingredient until the previous one is actually in the bowl.

      -

      Jamie: Okay, set the room for us. What are we walking into?

      -

      Alex: This is where Step-by-Step: Accept Your Classroom Assignment and Open Your Repo becomes real: this is the very first hands-on step of Day 1. That matters in practice: By the end of this walkthrough you will have your own Learning Room repository on GitHub and your first challenge issue waiting for you.

      -

      Jamie: Turn that into a path someone can follow.

      -

      Alex: Start with 1. Open the assignment link. There is something to understand, something to try, and something that proves the try worked.

      -

      Alex: First, in the same browser where you are signed into GitHub, open the Day 1 assignment link the facilitator shared. Then, 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"). After that, if the page asks you to authorize GitHub Classroom to access your GitHub account, activate Authorize GitHub Classroom. This is a one-time step. It is like walking a hallway with named doors: read the sign, enter the right room, then confirm where you landed.

      -

      Jamie: Give me the sequence, because order matters here.

      -

      Alex: The reason 2. Identify yourself (if asked) matters is that GitHub Classroom may ask you to pick your name from a roster so the facilitators can match your GitHub username to the registration list.

      -

      Alex: First, 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. Then, activate the link or button next to your name. After that, 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. The rhythm is simple: orient, act, verify, then continue.

      +

      Alex: Keep the teaching thread moving. Here is the plain-English version of Learning Moment. Technical quality and communication quality work together. Put another way, respectful, clear communication helps good code get merged faster. It is like learning a transit route. The names of the stops matter because they tell you whether you are still going the right direction.

      +

      Jamie: If someone only remembers one thing from Learning Pattern Used in This Chapter, what should it be?

      +

      Alex: First, read and absorb community norms (not just rules, but reasons). Then, reflect on personal experience (what worked, what was hard). After that, commit to specific behaviors in writing (public accountability). Finally, apply those behaviors in upcoming chapters (reviews, comments, PRs). It is a checklist, but a meaningful one: every item creates evidence that the next step is safe.

      +

      Alex: Keep the teaching thread moving. Keep the learner anchored in 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. This is the part to say slowly: GitHub Flow is the lightweight branching model recommended for open source contribution.

      -

      Jamie: Let's pause on 3. Accept the assignment. What should a learner take away from it?

      -

      Alex: Start with 3. Accept the assignment: The status page does not auto-announce when the repo is ready. The next useful detail is this: Use Browse mode and press K to step through links until you hear your repository link, or refresh the page until it appears.

      -

      Alex: First, you now see a screen with a button that says Accept this assignment (or just Accept the assignment ). Activate it. Then, 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. After that, 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/the workshop organization/learning-room-your username. Think of it as a rail line: each stop confirms you are still on the right route before the next one.

      -

      Jamie: Let's pause on 4. Open your new repository. What should a learner take away from it?

      -

      Alex: Start with 4. Open your new repository. There is something to understand, something to try, and something that proves the try worked.

      -

      Alex: Here is what that changes in practice. The repo name in the heading matches learning-room-your username. 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.

      -

      Alex: First, activate the link to your repository. You land on the standard GitHub repo page for the workshop organization/learning-room-your username. Then, verify three things on this page. After that, bookmark this page. You will return here for every Day 1 challenge. Treat it like a recipe: do not add the next ingredient until the previous one is actually in the bowl.

      -

      Jamie: Let's pause on 5. Find your first challenge issue. What should a learner take away from it?

      -

      Alex: This is where 5. Find your first challenge issue becomes real: when your Learning Room repo is ready, Challenge 1 appears as a GitHub issue in your repo. That matters in practice: The facilitators prepare this by running the Student Progression Bot after students accept the Classroom assignment. The workshop is closer to rehearsal than lecture. You hear the move, try the move, and then check what changed.

      -

      Alex: First, from your repository page, navigate to the Issues tab. Keyboard shortcut: press G then I. Then, 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]). After that, open Challenge 1. Read the issue body -- it tells you what to do, where to find evidence, and how to submit completion. It is a checklist, but a meaningful one: every item creates evidence that the next step is safe.

      -

      Alex: A solid issue habit is to read the title, the body, and the timeline before acting. You are listening for the requested action, the missing evidence, and the person who needs a response.

      +

      Jamie: Let's pause on Why This Model Works. What should a learner take away from it?

      +

      Alex: Start with Why This Model Works. There is something to understand, something to try, and something that proves the try worked.

      +

      Alex: The practical takeaway is this. 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.

      +

      Alex: Keep the teaching thread moving. Start with GitHub Flow vs Git Flow: You may encounter "Git Flow" (sometimes written "GitFlow") in older projects or enterprise environments. The next useful detail is this: This section explains what Git Flow is, how it differs from GitHub Flow, and why this workshop teaches GitHub Flow. Think of it like entering a new building: first you find the lobby, then the room, then the door you actually need.

      +

      Jamie: Let's pause on What Git Flow Is. What should a learner take away from it?

      +

      Alex: Here is the plain-English version of What Git Flow Is. Git Flow is a branching model published by Vincent Driessen in 2010. Put another way, it was designed for teams that ship versioned releases on a schedule (desktop software, mobile apps, embedded systems).

      -

      Jamie: If I am listening before the workshop starts, what should settle in my mind first?

      -

      Alex: Keep the learner anchored in 6. Confirm Aria can talk to you. The PR validation bot, Aria, posts educational feedback whenever you open a pull request. This is the part to say slowly: 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 ).

      -

      Alex: Another way to ground it. The reason Workshop Recommendation (Chapter 4) matters is that chapter 4 is a system orientation chapter.

      -

      Alex: That becomes easier when you listen for these cues. There are 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.

      -

      Jamie: Let's pause on Readiness Checkpoint. What should a learner take away from it?

      -

      Alex: Start with Readiness Checkpoint: Before starting Chapter 5 challenges, you should be able to.

      -

      Alex: First, find docs/CHALLENGES.md in your Learning Room repository. Then, explain the flow: issue - branch - pull request - review - merge. After that, identify where Aria bot feedback appears on a PR (the Conversation tab). Think of it as a rail line: each stop confirms you are still on the right route before the next one.

      +

      Jamie: Let's pause on How the Git Flow Cycle Works. What should a learner take away from it?

      +

      Alex: Start with How the Git Flow Cycle Works. There is something to understand, something to try, and something that proves the try worked.

      +

      Alex: First, developers branch feature/my-feature off develop and work there. Then, completed features merge back into develop via pull request. After that, when develop has enough features for a release, a release/1.2.0 branch is created. Finally, the release branch gets final testing, bug fixes, and version number updates. It is a checklist, but a meaningful one: every item creates evidence that the next step is safe.

      +

      Jamie: Before we leave How the Git Flow Cycle Works, what is the practical point?

      +

      Alex: First, the release branch merges into main (tagged with the version) and back into develop. Then, if a critical bug is found in production, a hotfix/ branch is created from main, fixed, and merged into both main and develop. It is like walking a hallway with named doors: read the sign, enter the right room, then confirm where you landed.

      +

      Jamie: Let's pause on How GitHub Flow Differs. What should a learner take away from it?

      +

      Alex: Keep the learner anchored in How GitHub Flow Differs. The following table compares GitHub Flow and Git Flow across key dimensions.

      +

      Alex: Keep the teaching thread moving. Start with When You Might See Git Flow. There is something to understand, something to try, and something that proves the try worked.

      +

      Alex: The practical takeaway is this. 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.

      -

      Alex: This is the part worth saying out loud. Here is the plain-English version of Two Tracks That Reinforce Each Other. Throughout Day 1 you work on two parallel learning tracks, both in your own account. It is like learning a transit route. The names of the stops matter because they tell you whether you are still going the right direction.

      -

      Jamie: Give me the version that sounds like an instructor, not a manual.

      -

      Alex: This is where Track 1: GitHub Skills Modules (Optional Self-Paced Practice) becomes real: 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.

      -

      Alex: For a learner, the useful signals are these. Introduction to GitHub - Create branch, open PR, merge. Communicate Using Markdown - Write headings, links, code, tables. Review Pull Requests - Comment, approve, suggest changes.

      -

      Alex: A solid pull request habit is to separate three questions: what changed, why it changed, and what still needs review. That keeps the conversation useful instead of noisy.

      -

      Alex: The next layer is this. Start with Track 2: Your Learning Room Repository (Required Workshop Track). There is something to understand, something to try, and something that proves the try worked.

      -

      Alex: The parts worth keeping in working memory are these. 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).

      +

      Jamie: How should they picture the shape of the workshop?

      +

      Alex: Start with 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. The next useful detail is this: It is what GitHub itself uses and what most modern open source projects follow.

      +

      Alex: Keep the teaching thread moving. Here is the plain-English version of The Unwritten Rule: One Thing Per Branch. A branch and its PR should do one thing. Put another way, if you are fixing a broken link and you notice a typo nearby, fix the typo in a separate branch and PR.

      +

      Jamie: Let's pause on Learning Cards: GitHub Flow. What should a learner take away from it?

      +

      Alex: Start with Learning Cards: GitHub Flow. There is something to understand, something to try, and something that proves the try worked.

      +

      Alex: The practical takeaway is this. 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). 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.

      -

      Jamie: How should someone choose between those options?

      -

      Alex: Start with How the Two Tracks Compare. There is something to understand, something to try, and something that proves the try worked.

      -

      Alex: Use the comparison to make a decision, not to recite a table. The main contrasts are: GitHub Skills (optional) means Your Learning Room (required). Create a branch in a Skills repo means Create a branch in your Learning Room. Open a PR means Open a PR.

      -

      Alex: Here is the practical turn. Start with Learning Cards: Two Tracks, One Account. There is something to understand, something to try, and something that proves the try worked.

      -

      Alex: On the ground, that means a few things. 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. 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.

      -

      Jamie: Let's pause on Your Learning Room Folder Structure. What should a learner take away from it?

      -

      Alex: Here is the plain-English version of 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.

      -

      Alex: The room should hear these as checkpoints. 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.

      +

      Alex: Keep the teaching thread moving. Keep the learner anchored in Keeping Your Fork Up to Date. When you fork a repository, you get a snapshot of the project at that moment. This is the part to say slowly: The original repository (called "upstream") continues to evolve. A good GitHub workflow is like a well-run meeting: everyone knows the topic, the next action, and who has the floor.

      +

      Jamie: Let's pause on Why Sync Your Fork? What should a learner take away from it?

      +

      Alex: Start with Why Sync Your Fork? There is something to understand, something to try, and something that proves the try worked.

      +

      Alex: The practical takeaway is this. 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.

      +

      Jamie: Let's pause on Method 1: GitHub Web Interface (Easiest). What should a learner take away from it?

      +

      Alex: Start with Method 1: GitHub Web Interface (Easiest): GitHub merges the upstream changes into your fork automatically. The next useful detail is this: Screen reader users (NVDA / JAWS / VoiceOver).

      +

      Alex: First, navigate to your fork's main page: github.com/your-username/repo-name. Then, look for the sync indicator: "This branch is X commits behind upstream/main". After that, click the "Sync fork" button. Finally, click "Update branch". Think of it as a rail line: each stop confirms you are still on the right route before the next one.

      +

      Jamie: Before we leave Method 1: GitHub Web Interface (Easiest), what is the practical point?

      +

      Alex: First, the sync button appears in the landmark that contains the branch selector. Then, press D to cycle through landmarks until you reach that region. After that, press B to cycle buttons until you hear "Sync fork" → press Enter. Finally, a dialog or page update presents "Update branch" - activate it. Treat it like a recipe: do not add the next ingredient until the previous one is actually in the bowl.

      -

      Alex: That matters because of the next idea. This is where Your Practice Branch becomes real: in your own Learning Room repository, you decide what branches to create. That matters in practice: The Day 1 challenge sequence asks you to work on a single feature branch named after yourself.

      -

      Alex: A few details make that real. 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.

      -

      Jamie: Let's pause on Why you create a separate branch. What should a learner take away from it?

      -

      Alex: Start with Why you create a separate branch. There is something to understand, something to try, and something that proves the try worked.

      -

      Alex: The practical takeaway is this. 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.

      -

      Jamie: Let's pause on How to use your branch. What should a learner take away from it?

      -

      Alex: The reason How to use your branch matters is that the Day 1 challenges (4 onward) walk you through creating and using your branch on GitHub.com. That gives the learner a simple foothold: once you start working locally in Chapter 14, the same branch is what you check out. The interface gets friendlier when it stops being a wall of controls and starts being a set of named places.

      -

      Alex: First, create the branch on GitHub.com (Challenge 4) or locally with git checkout -b learn/ from main. Then, make your changes and commit them to the branch. After that, push the branch to GitHub if you created it locally. Finally, open a pull request from learn/ - main (Challenge 6). The rhythm is simple: orient, act, verify, then continue.

      -

      Alex: Treat examples as spoken recipes, not decorations. You may hear something like git checkout learn/. Read the command, understand what it changes, then run it only when the repository state matches the lesson.

      +

      Jamie: How should a learner choose a tool without feeling judged by the choice?

      +

      Alex: Here is the plain-English version of Method 2: Git Command Line (VS Code Terminal). If you're working locally in VS Code.

      +

      Jamie: Let's pause on One-time setup - add the upstream remote. What should a learner take away from it?

      +

      Alex: Start with One-time setup - add the upstream remote. There is something to understand, something to try, and something that proves the try worked.

      +

      Alex: Treat examples as spoken recipes, not decorations. You may hear something like git remote add upstream https://github.com/original-owner/repo-name.git; git remote -v Verify it was added. Read the command, understand what it changes, then run it only when the repository state matches the lesson.

      +

      Jamie: Let's pause on Sync process. What should a learner take away from it?

      +

      Alex: Start with Sync process. There is something to understand, something to try, and something that proves the try worked.

      +

      Alex: Treat examples as spoken recipes, not decorations. You may hear something like 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. Read the command, understand what it changes, then run it only when the repository state matches the lesson.

      -

      Jamie: Let's pause on Learning Cards: Your Practice Branch. What should a learner take away from it?

      -

      Alex: Start with Learning Cards: Your Practice Branch. There is something to understand, something to try, and something that proves the try worked.

      -

      Alex: The practical takeaway is this. 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. 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.

      -

      Jamie: Let's pause on Tool Cards: Switch to Your Practice Branch. What should a learner take away from it?

      -

      Alex: Start with Tool Cards: Switch to Your Practice Branch. There is something to understand, something to try, and something that proves the try worked.

      -

      Alex: First, on the repository page, click the branch selector dropdown (shows "main"). Then, type learn to filter, then select learn/. After that, click the branch name in the bottom-left status bar. Finally, select your learn/ branch from the list. Treat it like a recipe: do not add the next ingredient until the previous one is actually in the bowl.

      -

      Jamie: Before we leave Tool Cards: Switch to Your Practice Branch, what is the practical point?

      -

      Alex: First, click the branch name in the bottom-left status bar (or press Ctrl+Shift+P then type Git: Checkout to ). Then, select origin/learn/ from the branch list. After that, click the Current Branch dropdown at the top. It is a checklist, but a meaningful one: every item creates evidence that the next step is safe.

      -

      Jamie: Let's pause on The Practice Files: What You Will Work On. What should a learner take away from it?

      -

      Alex: This is where The Practice Files: What You Will Work On becomes real: see also: Appendix C: Markdown Reference covers all Markdown syntax with accessible examples -- you will need it for editing these files. That matters in practice: The docs/ folder contains three practice files with intentional issues.

      +

      Alex: Keep the teaching thread moving. Start with When to sync. There is something to understand, something to try, and something that proves the try worked.

      +

      Alex: The practical takeaway is this. 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).

      +

      Jamie: Let's pause on Method 3: GitHub Desktop. What should a learner take away from it?

      +

      Alex: Start with Method 3: GitHub Desktop. There is something to understand, something to try, and something that proves the try worked.

      +

      Alex: First, open GitHub Desktop. Then, select Repository → Pull to get your fork's latest. After that, select Branch → Merge into Current Branch. Finally, choose upstream/main. Think of it as a rail line: each stop confirms you are still on the right route before the next one.

      +

      Jamie: Before we leave Method 3: GitHub Desktop, what is the practical point?

      +

      Alex: First, push the changes to your fork on GitHub. Treat it like a recipe: do not add the next ingredient until the previous one is actually in the bowl.

      +

      Alex: Keep the teaching thread moving. Start with Learning Cards: Keeping Your Fork Up to Date. There is something to understand, something to try, and something that proves the try worked.

      +

      Alex: The practical takeaway is this. 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. 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.

      -

      Alex: That connects to another useful point. Keep the learner anchored in docs/welcome.md - Introduction to Open Source Contribution. This file introduces newcomers to open source. This is the part to say slowly: It has three [TODO] sections where content is missing. A good GitHub workflow is like a well-run meeting: everyone knows the topic, the next action, and who has the floor.

      -

      Jamie: Let's pause on [TODO] 1 - "Who Can Contribute?" section. What should a learner take away from it?

      -

      Alex: The reason [TODO] 1 - "Who Can Contribute?" section matters is that [TODO: Add a paragraph explaining that contributors come from all backgrounds, skill levels, and countries. That gives the learner a simple foothold: emphasize that using assistive technology is not a barrier to contribution - in fact, AT users bring a perspective that improves projects for everyone.].

      -

      Alex: Keep the thread going. Start with [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. The next useful detail is this: What questions should you ask yourself?

      +

      Jamie: Let's pause on Writing Good Commit Messages. What should a learner take away from it?

      +

      Alex: This is where Writing Good Commit Messages becomes real: every commit you make includes a message describing what changed. That matters in practice: Good commit messages make project history understandable months or years later.

      +

      Alex: Keep the teaching thread moving. Keep the learner anchored in The First Line (Required). This is the commit summary that appears in logs and GitHub's commit list. This is the part to say slowly: Think of it as an email subject line.

      +

      Alex: The practical takeaway is this. fix: - bug fix. feat: - new feature. docs: - documentation only. style: - formatting, no code change.

      +

      Jamie: Let's pause on The Body (Optional). What should a learner take away from it?

      +

      Alex: The reason The Body (Optional) matters is that if the summary isn't enough, add a body explaining. That gives the learner a simple foothold: leave a blank line between the summary and the body.

      +

      Alex: The practical takeaway is this. Why you made the change (more important than what). What trade-offs you considered. How the change affects behavior.

      +

      Alex: Treat examples as spoken recipes, not decorations. You may hear something like 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. Read the command, understand what it changes, then run it only when the repository state matches the lesson.

      -

      Jamie: Let's pause on [TODO] 3 - "After Your Contribution Is Merged" section. What should a learner take away from it?

      -

      Alex: Here is the plain-English version of [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.]. Put another way, it also has a broken internal link that needs to be found and fixed.

      -

      Alex: This is where the talk moves from concept to action. This is where docs/keyboard-shortcuts.md - Screen Reader Shortcut Reference becomes real: this is a comprehensive reference with tables for NVDA, JAWS, and VoiceOver shortcuts. That matters in practice: It contains intentional errors in some shortcut references that students need to find and fix. The workshop is closer to rehearsal than lecture. You hear the move, try the move, and then check what changed.

      -

      Alex: The practical takeaway is this. 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.

      -

      Alex: A solid navigation habit is to prove where you are before activating controls. Headings, landmarks, and the address bar are not trivia; they are your map.

      -

      Jamie: What is the pre-flight check here?

      -

      Alex: Keep the learner anchored in 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. This is the part to say slowly: It contains broken links that point to incorrect URLs and incomplete steps.

      -

      Alex: The practical takeaway is this. 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.

      +

      Alex: Keep the teaching thread moving. Start with The Footer (Optional): When the commit is merged, GitHub automatically closes linked issues. Think of it like entering a new building: first you find the lobby, then the room, then the door you actually need.

      +

      Jamie: Let's pause on Atomic Commits. What should a learner take away from it?

      +

      Alex: Here is the plain-English version of Atomic Commits. Each commit should represent one logical change. Put another way, don't bundle unrelated fixes into a single commit.

      +

      Alex: Keep the teaching thread moving. Start with Common mistakes to avoid. There is something to understand, something to try, and something that proves the try worked.

      +

      Alex: The practical takeaway is this. "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.

      -

      Alex: Keep the teaching thread moving. The reason docs/CHALLENGES.md - Your Challenge Menu matters is that this file lists all 21 challenges organized by progression level. That gives the learner a simple foothold: each challenge lists the file(s) to edit, estimated time, skills practiced, and success criteria.

      -

      Jamie: How do these exercises create confidence instead of pressure?

      -

      Alex: Start with Bonus Challenges: Five bonus challenges (A through E) are available for students who finish faster. The next useful detail is this: These include an accessibility audit, mentoring a peer, cross-repository contribution, creating a custom workflow, and documentation improvement.

      -

      Jamie: Let's pause on Student A (working on Challenge 3: Complete Welcome Guide). What should a learner take away from it?

      -

      Alex: Here is the plain-English version of Student A (working on Challenge 3: Complete Welcome Guide). Visibility: The PR immediately appears in the repo's Pull Requests tab. It is like learning a transit route. The names of the stops matter because they tell you whether you are still going the right direction.

      -

      Alex: First, finds their assigned issue (Issues tab → filter Assignee:@me). Then, opens docs/welcome.md and edits the three [TODO] sections. After that, commits to a new branch: fix/studentA-issue12. Finally, opens a pull request with description. Treat it like a recipe: do not add the next ingredient until the previous one is actually in the bowl.

      -

      Jamie: Before we leave Student A (working on Challenge 3: Complete Welcome Guide), what is the practical point?

      -

      Alex: First, submits the PR. It is a checklist, but a meaningful one: every item creates evidence that the next step is safe.

      +

      Jamie: Let's pause on Good commit messages in practice. What should a learner take away from it?

      +

      Alex: Keep the learner anchored in Good commit messages in practice. When you make a habit of writing good commit messages, you build trust. This is the part to say slowly: Maintainers see that you care about the project's long-term health, not just your immediate contribution.

      +

      Alex: Treat examples as spoken recipes, not decorations. You may hear something like 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. Read the command, understand what it changes, then run it only when the repository state matches the lesson.

      +

      Alex: Keep the teaching thread moving. Start with Learning Cards: Writing Good Commit Messages. There is something to understand, something to try, and something that proves the try worked.

      +

      Alex: The practical takeaway is this. 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. 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.

      +

      Jamie: Let's pause on The Nature of Open Source Communication. What should a learner take away from it?

      +

      Alex: Start with The Nature of Open Source Communication: Open source collaboration happens primarily in writing, asynchronously, in public. The next useful detail is this: Understanding these three characteristics shapes everything about how we communicate.

      -

      Jamie: Let's pause on Bot (.github/workflows/learning-room-pr-bot.yml). What should a learner take away from it?

      -

      Alex: This is where Bot (.github/workflows/learning-room-pr-bot.yml) becomes real: visibility: The bot comment appears in your PR. That matters in practice: You see it; the facilitators see it; nobody else does unless they have been added as a collaborator on your repo.

      -

      Alex: The practical takeaway is this. Runs within 30 seconds. 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).

      -

      Jamie: Let's pause on Step 3: Peer Review (Facilitator-Arranged). What should a learner take away from it?

      -

      Alex: Keep the learner anchored in 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. This is the part to say slowly: 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.

      -

      Alex: First, the facilitators (Jeff and Michael) pair you with another participant. Then, they add each of you as a collaborator on the other's Learning Room repo. After that, each of you receives a notification: "You have been added as a collaborator.". Finally, you can now read the other person's PRs, leave comments, request changes, and approve. It is like walking a hallway with named doors: read the sign, enter the right room, then confirm where you landed.

      -

      Jamie: Before we leave Step 3: Peer Review (Facilitator-Arranged), what is the practical point?

      -

      Alex: First, 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. The rhythm is simple: orient, act, verify, then continue.

      -

      Jamie: Let's pause on Visibility. What should a learner take away from it?

      -

      Alex: Start with Visibility. There is something to understand, something to try, and something that proves the try worked.

      -

      Alex: The practical takeaway is this. 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.

      +

      Alex: Keep the teaching thread moving. Start with In writing. There is something to understand, something to try, and something that proves the try worked.

      +

      Alex: The practical takeaway is this. 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.".

      +

      Jamie: Let's pause on Asynchronously. What should a learner take away from it?

      +

      Alex: Start with Asynchronously. There is something to understand, something to try, and something that proves the try worked.

      +

      Alex: The practical takeaway is this. 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.

      +

      Alex: Keep the teaching thread moving. Start with In public. There is something to understand, something to try, and something that proves the try worked.

      +

      Alex: The practical takeaway is this. 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.

      -

      Jamie: Let's pause on Your assigned peer reviewer (when one is paired with you). What should a learner take away from it?

      -

      Alex: Start with Your assigned peer reviewer (when one is paired with you). There is something to understand, something to try, and something that proves the try worked.

      -

      Alex: The practical takeaway is this. 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. 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.".

      -

      Alex: First, receives notification: "PR review requested". Then, navigates to the PR in your Learning Room repo (they have collaborator access). After that, leaves review comments. Finally, submits review: Approve (or Request Changes if a [TODO] marker was missed). Think of it as a rail line: each stop confirms you are still on the right route before the next one.

      -

      Jamie: Before we leave Visibility, what is the practical point?

      -

      Alex: The practical takeaway is this. 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.

      -

      Jamie: Let's pause on You (PR author). What should a learner take away from it?

      -

      Alex: Start with You (PR author). There is something to understand, something to try, and something that proves the try worked.

      -

      Alex: First, read Aria's feedback and any human review. Then, talks to the reviewer if something is unclear. After that, makes changes based on feedback. Finally, pushes new commits to the same branch. It is a checklist, but a meaningful one: every item creates evidence that the next step is safe.

      -

      Jamie: Before we leave You (PR author), what is the practical point?

      -

      Alex: First, re-addresses the feedback. It is like walking a hallway with named doors: read the sign, enter the right room, then confirm where you landed.

      +

      Jamie: What do we want them to notice before they start over?

      +

      Alex: The reason The Anatomy of Helpful Feedback matters is that whether commenting on an issue, reviewing a PR, or responding to a question, effective feedback has a structure.

      +

      Alex: Keep the teaching thread moving. Start with 1. Acknowledge what's working: Before identifying problems, name what is good. The next useful detail is this: This is not flattery - it is accuracy.

      +

      Jamie: Let's pause on 2. Identify the specific concern. What should a learner take away from it?

      +

      Alex: Here is the plain-English version of 2. Identify the specific concern. "This code is inaccessible." "This button has no accessible name - aria-label or visible text is needed for screen readers to announce its purpose.".

      -

      Jamie: What is the teaching move inside Visibility?

      -

      Alex: The practical takeaway is this. 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.

      -

      Alex: Keep the teaching thread moving. Start with When the review is approved (or you decide to self-merge). There is something to understand, something to try, and something that proves the try worked.

      -

      Alex: The practical takeaway is this. You merge the PR (button becomes available). PR closes, shows "merged".

      -

      Jamie: What should the learner prove to themselves after each small task?

      -

      Alex: Start with Progression Bot Posts the Next Challenge. There is something to understand, something to try, and something that proves the try worked.

      -

      Alex: The practical takeaway is this. 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.

      +

      Alex: Keep the teaching thread moving. This is where 3. Explain why it matters becomes real: context turns a complaint into a lesson. That matters in practice: It also respects the contributor - they deserve to understand, not just comply. The workshop is closer to rehearsal than lecture. You hear the move, try the move, and then check what changed.

      +

      Jamie: Let's pause on 4. Suggest a path forward (when you can). What should a learner take away from it?

      +

      Alex: Keep the learner anchored in 4. Suggest a path forward (when you can). If you have an idea for a solution, offer it as a suggestion, not a mandate. This is the part to say slowly: "Something like aria-label='Close navigation menu' would work well here.

      +

      Alex: Keep the teaching thread moving. The reason 5. Signal the weight of the concern matters is that help contributors understand what is a blocker versus a preference.

      +

      Alex: The practical takeaway is this. 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.

      -

      Alex: Keep the teaching thread moving. Start with Visibility. There is something to understand, something to try, and something that proves the try worked.

      -

      Alex: The practical takeaway is this. 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.

      -

      Jamie: Let's pause on Learning Cards: How PR Sharing Works. What should a learner take away from it?

      -

      Alex: Start with Learning Cards: How PR Sharing Works. There is something to understand, something to try, and something that proves the try worked.

      -

      Alex: The practical takeaway is this. 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. 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.

      -

      Alex: Keep the teaching thread moving. Keep the learner anchored in The Learning Automation System. When you open a PR in the Learning Room, you get three types of feedback. A good GitHub workflow is like a well-run meeting: everyone knows the topic, the next action, and who has the floor.

      +

      Jamie: Let's pause on Prefer "we" or describe the code, not the person. What should a learner take away from it?

      +

      Alex: Start with 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.".

      +

      Alex: Keep the teaching thread moving. Here is the plain-English version of 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?". It is like learning a transit route. The names of the stops matter because they tell you whether you are still going the right direction.

      +

      Jamie: Let's pause on Acknowledge cultural and language diversity. What should a learner take away from it?

      +

      Alex: This is where Acknowledge cultural and language diversity becomes real: when reading someone's comment: Assume good intent unless there is clear evidence otherwise. That matters in practice: When writing: Choose plain words over clever ones.

      +

      Alex: The practical takeaway is this. 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.

      -

      Jamie: Let's pause on Type 1: Automated Bot Feedback (30 seconds). What should a learner take away from it?

      -

      Alex: Start with Type 1: Automated Bot Feedback (30 seconds). There is something to understand, something to try, and something that proves the try worked.

      -

      Alex: The practical takeaway is this. 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.

      -

      Alex: Keep the teaching thread moving. Start with Type 2: Peer Reviewer Feedback (15-60 minutes). There is something to understand, something to try, and something that proves the try worked.

      -

      Alex: The practical takeaway is this. Human judgment on content. Creative suggestions. Encouragement and mentorship. Understanding of context. Can approve, request changes, or comment.

      -

      Jamie: Let's pause on Type 3: Progress Tracking (on merge). What should a learner take away from it?

      -

      Alex: Here is the plain-English version of Type 3: Progress Tracking (on merge). Together: Instant technical feedback + human mentorship + visible progress.

      -

      Alex: The practical takeaway is this. Skill badges (Markdown Master, Accessibility Advocate). Level progression (Beginner → Intermediate → Advanced → Expert). Milestone celebrations (1st, 5th, 10th PR). Motivational comments.

      +

      Alex: Keep the teaching thread moving. Keep the learner anchored in 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?".

      +

      Jamie: Let's pause on Keep comments focused. What should a learner take away from it?

      +

      Alex: The reason Keep comments focused matters is that each comment should address one concern. That gives the learner a simple foothold: if you have three issues, leave three comments - unless they are closely related.

      +

      Alex: Keep the teaching thread moving. Start with Don't leave comments unresolved: If you asked a question and got an answer, respond. The next useful detail is this: "Thanks, that makes sense" or resolving the conversation thread signals that the thread is complete. Think of it like entering a new building: first you find the lobby, then the room, then the door you actually need.

      -

      Jamie: Let's pause on Study Groups (Optional). What should a learner take away from it?

      -

      Alex: This is where Study Groups (Optional) becomes real: 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. The workshop is closer to rehearsal than lecture. You hear the move, try the move, and then check what changed.

      -

      Alex: First, group Issue Thread - Private communication space for your group. Then, shared Review Responsibility - You review each other's work. After that, collaborative Challenges - Optional group exercises. Finally, peer Support - Tag each other with questions. It is a checklist, but a meaningful one: every item creates evidence that the next step is safe.

      -

      Jamie: Can you translate that into plain choices?

      -

      Alex: Start with Key Differences: Skills Module vs. Your Learning Room. There is something to understand, something to try, and something that proves the try worked.

      -

      Alex: Use the comparison to make a decision, not to recite a table. The main contrasts are: GitHub Skills (Your Account) means Your Learning Room (Classroom). Your personal copy of a Skills repo means Your private copy of learning-room-template. Mona (GitHub) means Aria (PR validation) and the Student Progression bot.

      -

      Alex: Keep the teaching thread moving. The reason Tips for Reviewing a Peer's PR matters is that 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. That gives the learner a simple foothold: here is how to find the PRs they want you to look at.

      +

      Jamie: Let's pause on Resolving conversations. What should a learner take away from it?

      +

      Alex: Here is the plain-English version of Resolving conversations. On a PR, conversations (inline comment threads) can be "resolved" once addressed. Put another way, the author of the change and the reviewer can both resolve them.

      +

      Alex: Keep the teaching thread moving. This is where Do not "pile on" becomes real: if five people already said the same thing about an issue, you don't need to add a sixth comment saying the same thing. That matters in practice: A reaction on an existing comment is enough.

      +

      Jamie: Let's pause on Reactions. What should a learner take away from it?

      +

      Alex: Keep the learner anchored in Reactions. GitHub reactions () are an efficient way to express agreement, appreciation, or concern without adding noise to a thread.

      -

      Jamie: Let's pause on Finding PRs to Review. What should a learner take away from it?

      -

      Alex: Start with Finding PRs to Review: Screen reader users (VoiceOver - macOS).

      -

      Alex: First, go to your peer's Learning Room repo (the URL the facilitators sent you, or open it from your GitHub Notifications inbox). Then, click the Pull Requests tab. After that, click the Filters dropdown - "Review requested" - your username. Finally, click any PR title to open it. Think of it as a rail line: each stop confirms you are still on the right route before the next one.

      -

      Alex: Treat examples as spoken recipes, not decorations. You may hear something like 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. 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. Read the command, understand what it changes, then run it only when the repository state matches the lesson.

      -

      Alex: Keep the teaching thread moving. Here is the plain-English version of Reading a PR You're Assigned To. Screen reader users (VoiceOver - macOS). It is like learning a transit route. The names of the stops matter because they tell you whether you are still going the right direction.

      -

      Alex: The practical takeaway is this. 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.

      -

      Jamie: Let's pause on Leaving a Review. What should a learner take away from it?

      -

      Alex: This is where Leaving a Review becomes real: screen reader users (VoiceOver - macOS).

      -

      Alex: First, scroll to the comment box on the Conversation tab. Then, type your review comment. After that, click "Review Changes" (top-right of the Files Changed tab, or at the bottom of the PR page). Finally, select your review type: Comment / Approve / Request changes. It is a checklist, but a meaningful one: every item creates evidence that the next step is safe.

      -

      Jamie: Before we leave Leaving a Review, what is the practical point?

      -

      Alex: First, click "Submit review". It is like walking a hallway with named doors: read the sign, enter the right room, then confirm where you landed.

      -

      Alex: Treat examples as spoken recipes, not decorations. You may hear something like 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". Read the command, understand what it changes, then run it only when the repository state matches the lesson.

      +

      Alex: Keep the teaching thread moving. The reason Saved Replies - Your Accessibility Win matters is that GitHub lets you save frequently used responses as Saved Replies - reusable text snippets you can insert into any comment box with a few keystrokes. That gives the learner a simple foothold: this is a significant accessibility win for anyone who types the same comments repeatedly during triage, reviews, or issue management. The interface gets friendlier when it stops being a wall of controls and starts being a set of named places.

      +

      Jamie: Let's pause on Common uses. What should a learner take away from it?

      +

      Alex: Start with Common uses. There is something to understand, something to try, and something that proves the try worked.

      +

      Alex: The practical takeaway is this. "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.

      +

      Jamie: Let's pause on Creating a Saved Reply. What should a learner take away from it?

      +

      Alex: Start with Creating a Saved Reply. There is something to understand, something to try, and something that proves the try worked.

      +

      Alex: First, navigate to github.com/settings/replies. Then, activate "Add a saved reply". After that, give it a title (e.g., "Good first issue claim") - this is what you search. Finally, type the full reply text in the body (Markdown is supported). Treat it like a recipe: do not add the next ingredient until the previous one is actually in the bowl.

      -

      Jamie: Let's pause on Responding to Feedback. What should a learner take away from it?

      -

      Alex: Keep the learner anchored in Responding to Feedback. Screen reader users (VoiceOver - macOS).

      -

      Alex: First, open your PR (Pull Requests tab → click your PR). Then, read all comments and bot feedback. After that, click in the comment box to reply. Finally, push your fixes to the same branch. It is like walking a hallway with named doors: read the sign, enter the right room, then confirm where you landed.

      -

      Jamie: Before we leave Responding to Feedback, what is the practical point?

      -

      Alex: First, comment: "Updates pushed, ready for review". The rhythm is simple: orient, act, verify, then continue.

      -

      Alex: Treat examples as spoken recipes, not decorations. You may hear something like 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". Read the command, understand what it changes, then run it only when the repository state matches the lesson.

      -

      Jamie: Let's pause on Learning Cards: Tips for PR Sharing. What should a learner take away from it?

      -

      Alex: Start with Learning Cards: Tips for PR Sharing. There is something to understand, something to try, and something that proves the try worked.

      -

      Alex: The practical takeaway is this. 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. 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.

      -

      Alex: Keep the teaching thread moving. Start with "Can I see other students' PRs?": Not inside their Learning Room repos -- those are private to each student. The next useful detail is this: You can see other participants' work in two ways. Think of it like entering a new building: first you find the lobby, then the room, then the door you actually need.

      -

      Alex: The practical takeaway is this. 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.

      +

      Jamie: Let's pause on Using a Saved Reply in a comment. What should a learner take away from it?

      +

      Alex: Start with Using a Saved Reply in a comment. There is something to understand, something to try, and something that proves the try worked.

      +

      Alex: First, navigate to any comment text area. Then, activate the Saved Replies button (the speech bubble icon in the comment toolbar, or press Ctrl+. if enabled). After that, a dropdown appears showing your saved replies - type to filter by title. Finally, select the reply - it inserts into the text area. It is a checklist, but a meaningful one: every item creates evidence that the next step is safe.

      +

      Jamie: Before we leave Using a Saved Reply in a comment, what is the practical point?

      +

      Alex: First, edit as needed before submitting. It is like walking a hallway with named doors: read the sign, enter the right room, then confirm where you landed.

      +

      Alex: Keep the teaching thread moving. Keep the learner anchored in Screen reader path. Limit: GitHub allows up to 100 saved replies per account. A good GitHub workflow is like a well-run meeting: everyone knows the topic, the next action, and who has the floor.

      +

      Jamie: Let's pause on Learning Cards: Commenting Etiquette. What should a learner take away from it?

      +

      Alex: Start with Learning Cards: Commenting Etiquette. There is something to understand, something to try, and something that proves the try worked.

      +

      Alex: The practical takeaway is this. 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. 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.

      -

      Jamie: Let's pause on "What if I don't agree with my assigned reviewer?". What should a learner take away from it?

      -

      Alex: Here is the plain-English version of "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. Put another way, you can request additional reviewers manually.

      -

      Alex: Keep the teaching thread moving. This is where "Will my PR get lost when everyone is working at once?" becomes real: your repo is your own; you only see your own PRs. That matters in practice: Aria's feedback is on your PR alone, and any peer reviewer is specifically assigned to you.

      -

      Jamie: Let's pause on "Can I comment on someone else's PR?". What should a learner take away from it?

      -

      Alex: Keep the learner anchored in "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. This is the part to say slowly: On the public accessibility-agents repo, anyone can comment on any open PR.

      +

      Alex: Keep the teaching thread moving. Start with 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.".

      +

      Jamie: Let's pause on Don't gatekeep knowledge. What should a learner take away from it?

      +

      Alex: Here is the plain-English version of Don't gatekeep knowledge. If a contributor makes a mistake because they didn't know something, explain the concept.

      +

      Alex: Keep the teaching thread moving. This is where Ask questions instead of making demands becomes real: "Change this to use aria-label." "What do you think about using aria-label here instead? That matters in practice: Screen readers would then announce the button's purpose directly.". The workshop is closer to rehearsal than lecture. You hear the move, try the move, and then check what changed.

      -

      Alex: Keep the teaching thread moving. The reason "What if my reviewer doesn't respond?" matters is that mention them directly in a PR comment: "@name, any thoughts on the changes I pushed?" Or ask a facilitator to follow up. The interface gets friendlier when it stops being a wall of controls and starts being a set of named places.

      -

      Jamie: Let's pause on "Can I work with a friend?". What should a learner take away from it?

      -

      Alex: Start with "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.

      -

      Alex: Keep the teaching thread moving. Here is the plain-English version of "How long does review take?". When pairings happen during a workshop block, typically 15-60 minutes. Put another way, if a reviewer is slow, the facilitators can step in or assign someone else.

      +

      Jamie: Let's pause on Distinguish opinion from requirement. What should a learner take away from it?

      +

      Alex: Keep the learner anchored in Distinguish opinion from requirement. If something is your stylistic preference but NOT a bug or correctness issue, say so. This is the part to say slowly: "The current implementation is correct.

      +

      Alex: Keep the teaching thread moving. The reason Approve explicitly matters is that 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!

      +

      Jamie: Let's pause on Say thank you. What should a learner take away from it?

      +

      Alex: Start with Say thank you: When someone takes time to review your work, acknowledge it - even if you disagree with some feedback. The next useful detail is this: "Thanks so much for the thorough review!

      -

      Jamie: Let's pause on "What if bot feedback is wrong?". What should a learner take away from it?

      -

      Alex: This is where "What if bot feedback is wrong?" becomes real: Aria is intentionally educational, not punitive -- if you disagree with a check, the facilitators can override it. That matters in practice: Aria is not perfect, which is exactly why human review still matters.

      -

      Alex: Keep the teaching thread moving. Keep the learner anchored in "Do I need to complete every challenge?". The Learning Room has challenges for all skill levels. This is the part to say slowly: You can pick what interests you, complete at your pace, and continue after the workshop -- your repo stays yours. A good GitHub workflow is like a well-run meeting: everyone knows the topic, the next action, and who has the floor.

      -

      Jamie: Let's pause on Celebration: You're Contributing. What should a learner take away from it?

      -

      Alex: The reason Celebration: You're Contributing matters is that every PR you open and merge in the Learning Room is a real contribution. That gives the learner a simple foothold: you found something to improve You made a meaningful change You received feedback (technical + human) You incorporated suggestions You merged your work.

      +

      Alex: Keep the teaching thread moving. Here is the plain-English version of Don't take feedback personally. Code review is about the code, not your worth as a person or developer. Put another way, even the most senior contributors receive change requests. It is like learning a transit route. The names of the stops matter because they tell you whether you are still going the right direction.

      +

      Jamie: Let's pause on Explain your choices. What should a learner take away from it?

      +

      Alex: This is where Explain your choices becomes real: if you are keeping your implementation despite feedback, explain why. That matters in practice: "I considered aria-label here, but I went with a visually-hidden instead because it allows translators to localize the text more easily.

      +

      Alex: Keep the teaching thread moving. Keep the learner anchored in Surface blockers early. Don't wait until you have finished a 500-line PR to mention that you weren't sure about the approach.

      -

      Alex: Keep the teaching thread moving. Start with Creating, Reviewing, and Merging Pull Requests with a Screen Reader: See also: Chapter 15: Code Review covers the full review workflow including multi-file diffs and suggested changes. The next useful detail is this: Pull requests are where your work becomes a contribution.

      -

      Jamie: What belongs in the live room, and what can wait until after?

      -

      Alex: Here is the plain-English version of Workshop Recommendation (Chapter 6). Chapter 6 is the first PR-validated chapter where students convert issue work into merge-ready contributions.

      -

      Alex: The practical takeaway is this. There are 3. Each challenge should take under 10 minutes each. The evidence is PR metadata, bot checks, and merged issue linkage. The pattern is small change - linked PR - green checks.

      -

      Jamie: Let's pause on Chapter 6 Challenge Set. What should a learner take away from it?

      -

      Alex: This is where Chapter 6 Challenge Set becomes real: this is the first chapter where you edit files and create branches. That matters in practice: 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. The workshop is closer to rehearsal than lecture. You hear the move, try the move, and then check what changed.

      -

      Alex: First, create one small branch change - edit a practice file on a new branch. Then, open a linked PR - use the PR template and include Closes XX. After that, pass required checks - respond to bot feedback until all required checks pass. It is a checklist, but a meaningful one: every item creates evidence that the next step is safe.

      +

      Jamie: Let's pause on Inclusive Commenting for Accessibility Issues. What should a learner take away from it?

      +

      Alex: The reason Inclusive Commenting for Accessibility Issues matters is that when filing or discussing accessibility bugs, additional context helps.

      +

      Alex: The practical takeaway is this. 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.

      +

      Jamie: Let's pause on The "Good First Issue" Social Contract. What should a learner take away from it?

      +

      Alex: Start with The "Good First Issue" Social Contract: When a maintainer labels an issue good first issue, they are. The next useful detail is this: When you take a good first issue, your responsibilities. Think of it like entering a new building: first you find the lobby, then the room, then the door you actually need.

      +

      Alex: The practical takeaway is this. Investing time - good first issues require extra documentation and mentorship. Signaling welcome - they want to support a new contributor.

      +

      Alex: First, comment to claim it - "Hi, I'd like to work on this. Can I be assigned?". Then, wait for assignment - do not start until assigned; two people working in parallel wastes everyone's time. After that, 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?". Finally, 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?". Think of it as a rail line: each stop confirms you are still on the right route before the next one.

      +

      Jamie: Before we leave The "Good First Issue" Social Contract, what is the practical point?

      +

      Alex: First, don't disappear - if you claim an issue, see it through or explicitly hand it back. Treat it like a recipe: do not add the next ingredient until the previous one is actually in the bowl.

      +

      Jamie: Let's pause on When you receive harsh feedback. What should a learner take away from it?

      +

      Alex: Start with When you receive harsh feedback. There is something to understand, something to try, and something that proves the try worked.

      +

      Alex: First, take a breath before responding - there is no urgency; the thread will wait. Then, look for the valid concern underneath the harsh words. After that, respond to the concern, not the tone. Finally, if the behavior crosses into harassment, report it via the "." button on the comment → "Report". Treat it like a recipe: do not add the next ingredient until the previous one is actually in the bowl.

      -

      Jamie: Let's pause on Challenge 6.1 Step-by-Step: Create One Small Branch Change. What should a learner take away from it?

      -

      Alex: Keep the learner anchored in Challenge 6.1 Step-by-Step: Create One Small Branch Change. Edit one of the practice files and save your change on a new branch. This is the part to say slowly: your Learning Room repository on GitHub.com, using the web editor.

      -

      Alex: The practical takeaway is this. 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. 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.

      -

      Alex: First, 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). Then, open the file and activate the pencil icon (Edit this file) button. After that, the file opens in the web editor. Make your change. For. Finally, keep your change small and focused. Edit only what the issue asks for. It is like walking a hallway with named doors: read the sign, enter the right room, then confirm where you landed.

      -

      Jamie: Before we leave Challenge 6.1 Step-by-Step: Create One Small Branch Change, what is the practical point?

      -

      Alex: First, after editing, activate the Commit changes button (green button above the editor). Then, a dialog appears. In the Branch name field, type: fix/yourname-issueXX (replace yourname with your GitHub username, and XX with the issue number). After that, select Create a new branch for this commit and start a pull request. Finally, activate Propose changes. The rhythm is simple: orient, act, verify, then continue.

      -

      Jamie: Let's pause on Challenge 6.2 Step-by-Step: Open a Linked PR. What should a learner take away from it?

      -

      Alex: The reason Challenge 6.2 Step-by-Step: Open a Linked PR matters is that AI agents do not just deploy code directly; they submit pull requests. That gives the learner a simple foothold: learning to edit a file, format it in Markdown, and review a PR today prepares you to audit and approve AI-generated changes tomorrow.

      -

      Alex: The practical takeaway is this. "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". A summary of what you changed and why (at least 50 characters).

      -

      Alex: First, in the Title field, write a short description of your change. Then, in the Body field, use the PR template if one is provided. Make sure to. After that, verify the base branch is main and the compare branch is your fix/yourname-issueXX branch. Finally, activate the Create pull request button. The rhythm is simple: orient, act, verify, then continue.

      -

      Jamie: Let's pause on Challenge 6.3 Step-by-Step: Pass Required Checks. What should a learner take away from it?

      -

      Alex: Start with Challenge 6.3 Step-by-Step: Pass Required Checks: Read bot feedback, fix any issues it finds, and get all required checks to pass. The next useful detail is this: the Conversation tab of your open pull request.

      -

      Alex: The practical takeaway is this. 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.

      -

      Alex: First, wait approximately 30 seconds after opening the PR. The bot posts a validation comment. Then, read the bot comment carefully. It checks. After that, if the bot reports failures. Finally, repeat step 3 until all required checks show a green checkmark. Think of it as a rail line: each stop confirms you are still on the right route before the next one.

      -

      Jamie: Before we leave Challenge 6.3 Step-by-Step: Pass Required Checks, what is the practical point?

      -

      Alex: First, when all checks pass, request a review from a peer or the facilitator. Treat it like a recipe: do not add the next ingredient until the previous one is actually in the bowl.

      +

      Jamie: Let's pause on When you disagree with a decision. What should a learner take away from it?

      +

      Alex: Start with When you disagree with a decision. There is something to understand, something to try, and something that proves the try worked.

      +

      Alex: First, make your case once, clearly and with evidence. Then, accept that the maintainer has the final say in their project. After that, if you strongly disagree, you can fork the project and take it in a different direction - this is legitimate in open source. It is a checklist, but a meaningful one: every item creates evidence that the next step is safe.

      +

      Jamie: Let's pause on When someone is rude to you. What should a learner take away from it?

      +

      Alex: Start with When someone is rude to you. There is something to understand, something to try, and something that proves the try worked.

      +

      Alex: First, you do not have to engage. Then, 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.". After that, report via GitHub's reporting tools if the behavior is abusive. It is like walking a hallway with named doors: read the sign, enter the right room, then confirm where you landed.

      +

      Jamie: Let's pause on When you accidentally caused offense. What should a learner take away from it?

      +

      Alex: Start with When you accidentally caused offense. There is something to understand, something to try, and something that proves the try worked.

      +

      Alex: First, acknowledge it directly: "I can see how that came across as dismissive - that wasn't my intention.". Then, do not over-explain or defend excessively. After that, adjust going forward. The rhythm is simple: orient, act, verify, then continue.

      -

      Alex: Keep the teaching thread moving. Start with Expected Outcomes. There is something to understand, something to try, and something that proves the try worked.

      -

      Alex: The practical takeaway is this. Student opens a focused PR that maps to one issue. Student uses Closes XX correctly. Student can interpret bot feedback and improve the PR.

      -

      Jamie: Let's pause on If You Get Stuck. What should a learner take away from it?

      -

      Alex: Start with If You Get Stuck. There is something to understand, something to try, and something that proves the try worked.

      -

      Alex: First, confirm your PR includes Closes XX in title or body. Then, check that changed files are only in learning-room/. After that, open the bot validation comment and resolve one required check at a time. Finally, if checks still fail, ask for peer or facilitator review with the exact error message. It is a checklist, but a meaningful one: every item creates evidence that the next step is safe.

      -

      Jamie: Before we leave If You Get Stuck, what is the practical point?

      -

      Alex: First, finished but not sure you did it right? Compare your work against the Challenge 6 reference solution. It is like walking a hallway with named doors: read the sign, enter the right room, then confirm where you landed.

      -

      Alex: Keep the teaching thread moving. Keep the learner anchored in Learning Moment. A great PR is small, linked to an issue, and easy to review. This is the part to say slowly: Faster feedback builds confidence and momentum.

      +

      Jamie: Let's pause on Writing Your First README. What should a learner take away from it?

      +

      Alex: Start with Writing Your First README: See also: Appendix W: GitHub Pages for publishing your README as a website. The next useful detail is this: A README is the front door of your project.

      +

      Alex: Keep the teaching thread moving. Here is the plain-English version of What belongs in a README. Every README should answer these questions, roughly in this order. Put another way, 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.

      +

      Jamie: Let's pause on Accessibility in READMEs. What should a learner take away from it?

      +

      Alex: This is where Accessibility in READMEs becomes real: your README is a web page -- GitHub renders it as HTML. That matters in practice: That means the same accessibility rules apply.

      +

      Alex: The practical takeaway is this. Alt text for images and badges. A badge that says is invisible to screen readers. Write 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 -- not Click here.

      -

      Jamie: Let's pause on Why this feels achievable. What should a learner take away from it?

      -

      Alex: Start with Why this feels achievable. There is something to understand, something to try, and something that proves the try worked.

      -

      Alex: The practical takeaway is this. Scope is intentionally small. Feedback is immediate and specific. Success is visible (green checks + closed issue).

      -

      Alex: Keep the teaching thread moving. Start with About Learning Cards in This Chapter: This chapter provides learning cards: expandable blocks that offer perspective-specific guidance for different ways of working. The next useful detail is this: Not every card appears at every step. Think of it like entering a new building: first you find the lobby, then the room, then the door you actually need.

      -

      Jamie: What is the safe way to learn from that example?

      -

      Alex: Here is the plain-English version of Local Git Alternative: The Full Branch-Edit-PR Workflow. If you cloned the learning-room in Block 0 and prefer working locally. Put another way, the web editor workflow (pencil button, "Propose changes") is the primary path taught in this chapter.

      -

      Alex: Treat examples as spoken recipes, not decorations. You may hear something like cd /Documents/learning-room; git checkout main; git pull origin main; git checkout -b fix/welcome-todos. code docs/welcome.md. Read the command, understand what it changes, then run it only when the repository state matches the lesson.

      +

      Alex: Keep the teaching thread moving. Keep the learner anchored in Good README vs. bad README. Bad: A single paragraph that says "This is my project. This is the part to say slowly: Run it with npm start." No headings, no license, no description of what the project does. A good GitHub workflow is like a well-run meeting: everyone knows the topic, the next action, and who has the floor.

      +

      Jamie: Let's pause on Learning Cards: Writing Your First README. What should a learner take away from it?

      +

      Alex: Start with Learning Cards: Writing Your First README. There is something to understand, something to try, and something that proves the try worked.

      +

      Alex: The practical takeaway is this. 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: rather than an empty that reads as "image" with no context. Use real Markdown link text (installation guide) instead of bare URLs, so your screen reader announces the destination rather than spelling out a long URL. 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.

      +

      Alex: Keep the teaching thread moving. Start with Community Health Files: Community health files tell contributors how your project operates before they write a single line of code. The next useful detail is this: 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.

      -

      Alex: Keep the teaching thread moving. This is where What Is a Pull Request? becomes real: a pull request (PR) is a proposal to merge changes from one branch into another. That matters in practice.you open a PR to request that those changes be merged into the target branch (usually main).

      -

      Alex: The practical takeaway is this. Edited a file directly on GitHub (web editor). Made changes in your fork. Made changes on a feature branch. What changed - a diff of every file.

      -

      Jamie: Let's pause on Navigating to Pull Requests. What should a learner take away from it?

      -

      Alex: Keep the learner anchored in Navigating to Pull Requests. Global pull requests dashboard: GitHub now shows a global pull requests page at github.com/pulls listing all open PRs across every repository you have access to. This is the part to say slowly: 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).

      -

      Alex: The practical takeaway is this. 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.

      -

      Alex: First, d → "Repository navigation" landmark. Then, k to navigate tabs → "Pull requests, [N] open". After that, enter to open. Finally, vO+U → Landmarks → navigate to "Repository navigation". It is like walking a hallway with named doors: read the sign, enter the right room, then confirm where you landed.

      -

      Jamie: Before we leave Navigating to Pull Requests, what is the practical point?

      -

      Alex: First, quick Nav K or VO+Right to navigate tabs → "Pull requests". Then, vO+Space to open. The rhythm is simple: orient, act, verify, then continue.

      -

      Jamie: What should they understand before typing anything?

      -

      Alex: The reason From a PR notification matters is that if you received a notification about a PR, follow the notification link directly to the PR page. That gives the learner a simple foothold: list and view pull requests from your terminal. The interface gets friendlier when it stops being a wall of controls and starts being a set of named places.

      -

      Alex: Treat examples as spoken recipes, not decorations. You may hear something like 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. Read the command, understand what it changes, then run it only when the repository state matches the lesson.

      +

      Jamie: Let's pause on CONTRIBUTING.md. What should a learner take away from it?

      +

      Alex: Here is the plain-English version of CONTRIBUTING.md. This file answers the question every newcomer asks: "How do I help?" A good CONTRIBUTING.md covers. Put another way, a sentence like "We are glad you are here" costs nothing and signals that newcomers are expected, not tolerated.

      +

      Alex: The practical takeaway is this. 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.

      +

      Alex: Keep the teaching thread moving. This is where CODE OF CONDUCT.md becomes real: a code of conduct sets the social contract for your project. That matters in practice: Without one, "acceptable behavior" is whatever each participant assumes it is -- and those assumptions vary widely. The workshop is closer to rehearsal than lecture. You hear the move, try the move, and then check what changed.

      +

      Alex: The practical takeaway is this. 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.

      +

      Jamie: Let's pause on SECURITY.md. What should a learner take away from it?

      +

      Alex: Keep the learner anchored in SECURITY.md. See also: Appendix F: Git Security and Appendix P: Security Features for security best practices. This is the part to say slowly: If someone discovers a vulnerability in your project, you do not want them to file a public issue.

      +

      Alex: The practical takeaway is this. 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.

      -

      Jamie: Let's pause on Learning Cards: Navigating to Pull Requests. What should a learner take away from it?

      -

      Alex: Start with Learning Cards: Navigating to Pull Requests. There is something to understand, something to try, and something that proves the try worked.

      -

      Alex: The practical takeaway is this. 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. 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.

      -

      Alex: Keep the teaching thread moving. Here is the plain-English version of The Pull Request List Page. The PR list works identically to the Issues list. Put another way, for screen reader users, - PR list semantics: The PR list does not have individual ARIA item containers with per-item semantics.

      -

      Alex: The practical takeaway is this. 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.

      -

      Jamie: Let's pause on Navigating the PR Tab Bar. What should a learner take away from it?

      -

      Alex: This is where Navigating the PR Tab Bar becomes real: the Conversation, Commits, and Files changed tabs are in a "Pull request navigation tabs" landmark. That matters in practice: The three tabs - Conversation, Commits, and Files changed - appear just below the PR title.

      -

      Alex: The practical takeaway is this. 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.

      -

      Alex: First, press D → navigate to "Pull request navigation tabs". Then, press ← or → arrow keys to move between tab options. After that, press Enter to activate a tab. Finally, vO+U → Landmarks → "Pull request navigation tabs". It is a checklist, but a meaningful one: every item creates evidence that the next step is safe.

      -

      Jamie: Before we leave Navigating the PR Tab Bar, what is the practical point?

      -

      Alex: First, vO+Right to move between tabs. Then, vO+Space to activate. It is like walking a hallway with named doors: read the sign, enter the right room, then confirm where you landed.

      +

      Alex: Keep the teaching thread moving. The reason LICENSE matters is that 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. That gives the learner a simple foothold: adding a LICENSE file is a one-time step that makes your project genuinely open source.

      +

      Jamie: Let's pause on Finding these files on GitHub. What should a learner take away from it?

      +

      Alex: Start with Finding these files on GitHub: Navigate to any repository and click Insights then Community Standards. The next useful detail is this: GitHub shows a checklist of which community health files are present and links to add any that are missing.

      +

      Alex: Keep the teaching thread moving. Start with Learning Cards: Community Health Files. There is something to understand, something to try, and something that proves the try worked.

      +

      Alex: The practical takeaway is this. 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. 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.

      -

      Jamie: Let's pause on PR Description. What should a learner take away from it?

      -

      Alex: Start with PR Description. There is something to understand, something to try, and something that proves the try worked.

      -

      Alex: First, 2 → navigate to "Description" h2 heading. Then, ↓ to read the description. After that, markdown renders as semantic HTML - headings, lists, code blocks are fully accessible. It is like walking a hallway with named doors: read the sign, enter the right room, then confirm where you landed.

      -

      Jamie: Let's pause on Status Checks Section. What should a learner take away from it?

      -

      Alex: The reason Status Checks Section matters is that below the description, the status checks summary shows whether automated tests passed. That gives the learner a simple foothold: status checks appear as a coloured banner below the PR description - green tick for passed, red X for failed, yellow spinner for running.

      -

      Alex: The practical takeaway is this. "All checks have passed" / "Some checks failed" / "Checks pending". A "Show all checks" button or link.

      -

      Alex: First, press H or 2 to find the "Checks" or "Status checks" heading. Then, press K to navigate links for individual check names. After that, press Enter on a check to see its details. Finally, quick Nav H or VO+Cmd+H to jump to the "Checks" or "Status checks" heading. The rhythm is simple: orient, act, verify, then continue.

      -

      Jamie: Before we leave Status Checks Section, what is the practical point?

      -

      Alex: First, quick Nav K to navigate check name links. Then, vO+Space on a check to see its details. Think of it as a rail line: each stop confirms you are still on the right route before the next one.

      -

      Alex: Keep the teaching thread moving. Start with Review Comments: Each review comment thread is an h3.

      -

      Alex: The practical takeaway is this. 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.

      +

      Jamie: Can you translate that into plain choices?

      +

      Alex: This is where When to Use Different Communication Channels becomes real: GitHub Discussions are separate from Issues. That matters in practice: Use Discussions for: "What do people think about X approach?" and Issues for: "The X button is broken.".

      +

      Alex: Use the comparison to make a decision, not to recite a table. The main contrasts are: PR comment means Feedback on a specific code change. PR review means Formal verdict (approve/request changes) with consolidated feedback. Discussion means Open-ended conversation, proposals, community Q&A.

      +

      Jamie: Let's pause on Try It: Rewrite One Comment. What should a learner take away from it?

      +

      Alex: Keep the learner anchored in Try It: Rewrite One Comment. Time: 2 minutes What you need: Just your brain. This is the part to say slowly: Read this code review comment and rewrite it to be constructive.

      +

      Alex: First, what you noticed. Then, why it matters. After that, what you suggest. Finally, why the suggestion helps. It is like walking a hallway with named doors: read the sign, enter the right room, then confirm where you landed.

      +

      Jamie: Before we leave Try It: Rewrite One Comment, what is the practical point?

      +

      Alex: First, encouragement. The rhythm is simple: orient, act, verify, then continue.

      +

      Jamie: Let's pause on Contributing to Open Source. What should a learner take away from it?

      +

      Alex: The reason Contributing to Open Source matters is that this section was previously Appendix T. That gives the learner a simple foothold: it is now part of the teaching narrative.

      -

      Jamie: Let's pause on Resolving conversations. What should a learner take away from it?

      -

      Alex: Here is the plain-English version of Resolving conversations. When a review comment has been addressed, you can mark the conversation as resolved. Put another way, resolved conversations are still accessible - they collapse but can be expanded again.

      -

      Alex: First, navigate to the conversation thread (3 to jump between comment headings). Then, tab to the end of the thread to find the "Resolve conversation" button. After that, press Enter to mark it resolved. Finally, the conversation collapses and shows as "Resolved". Treat it like a recipe: do not add the next ingredient until the previous one is actually in the bowl.

      -

      Alex: Keep the teaching thread moving. Start with Learning Cards: Reading the Conversation Tab. There is something to understand, something to try, and something that proves the try worked.

      -

      Alex: The practical takeaway is this. 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. 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.

      -

      Jamie: Let's pause on Reading the Checks Tab. What should a learner take away from it?

      -

      Alex: Keep the learner anchored in Reading the Checks Tab. The Checks tab shows the status of automated tests, CI workflows, and other verification processes running on your PR. This is the part to say slowly: It helps you verify whether your changes pass all required tests before merging.

      -

      Alex: The practical takeaway is this. Navigate through the check steps with K or Tab. Activate a step for more details.

      -

      Alex: First, navigate to the "Pull request tabs" landmark (D). Then, navigate between tab links (K or Tab) and activate "Checks". After that, press D to jump to the "check suites" section - this moves focus to the collapsed details button of the first check. Finally, press B or Tab to navigate between check buttons; each button is labeled with the check's name. It is like walking a hallway with named doors: read the sign, enter the right room, then confirm where you landed.

      -

      Jamie: Before we leave Reading the Checks Tab, what is the practical point?

      -

      Alex: First, press Enter or Space to expand a check and reveal its logs. Then, for a summary view: press D to navigate to the "check run summary" section. After that, vO+U - Landmarks - "Pull request tabs" - activate "Checks". Finally, vO+U - Landmarks - navigate to "check suites" section. The rhythm is simple: orient, act, verify, then continue.

      -
      -

      Alex: Keep the teaching thread moving. Start with Learning Cards: Reading the Checks Tab. There is something to understand, something to try, and something that proves the try worked.

      -

      Alex: The practical takeaway is this. 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. 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.

      -

      Jamie: Let's pause on Reading the Files Changed Tab. What should a learner take away from it?

      -

      Alex: Start with Reading the Files Changed Tab: the learner will read diffs - the before/after state of every file that changed. The next useful detail is this: This guide uses GitHub's improved Files Changed experience.

      -

      Jamie: Let's pause on File Tree (left panel). What should a learner take away from it?

      -

      Alex: Here is the plain-English version of File Tree (left panel). The file tree lists every changed file. Put another way, use it to jump directly to a specific file's diff. It is like learning a transit route. The names of the stops matter because they tell you whether you are still going the right direction.

      -

      Alex: The practical takeaway is this. 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.

      -

      Alex: First, d → navigate to "File tree" region. Then, ↑/↓ to navigate the file list. After that, enter to jump to that file's diff. Finally, vO+U → Landmarks → navigate to "File tree" region. Treat it like a recipe: do not add the next ingredient until the previous one is actually in the bowl.

      -

      Jamie: Before we leave File Tree (left panel), what is the practical point?

      -

      Alex: First, vO+Down to move through the file list. Then, vO+Space to jump to that file's diff. It is a checklist, but a meaningful one: every item creates evidence that the next step is safe.

      -
      -

      Jamie: Let's pause on The Diff for a File. What should a learner take away from it?

      -

      Alex: Start with The Diff for a File. There is something to understand, something to try, and something that proves the try worked.

      -

      Alex: The practical takeaway is this. 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.

      -

      Alex: Keep the teaching thread moving. Start with Lines in a diff are read as. There is something to understand, something to try, and something that proves the try worked.

      -

      Alex: The practical takeaway is this. + Added line - line that was added. Removed line - line that was removed. Context line - unchanged line shown for context.

      -

      Jamie: Let's pause on Navigating the diff with a screen reader. What should a learner take away from it?

      -

      Alex: The reason Navigating the diff with a screen reader matters is that each file's diff shows added lines in green and removed lines in red. That gives the learner a simple foothold: scroll the page to read through changes.

      -

      Alex: The practical takeaway is this. 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.

      -

      Alex: First, t to jump to the next diff table. Then, switch to Focus Mode: Insert+Space (NVDA) or Insert+Z (JAWS). After that, ctrl+Alt+↓ to move down one row (next diff line), Ctrl+Alt+↑ to move up. Finally, ctrl+Alt+→ to read across columns (line number change type content). The rhythm is simple: orient, act, verify, then continue.

      -

      Jamie: Before we leave Navigating the diff with a screen reader, what is the practical point?

      -

      Alex: First, the screen reader reads: "+ Add accessible name to submit button". Then, collapsed sections contain unchanged code. Focus the expand/disclosure control and activate it (Enter or Space) to reveal the hidden lines. After that, t or VO+U → Tables → select the diff table. Finally, vO+Shift+Down to enter the table. Think of it as a rail line: each stop confirms you are still on the right route before the next one.

      -
      -

      Jamie: Let's pause on Placing an inline comment on a diff line. What should a learner take away from it?

      -

      Alex: Start with Placing an inline comment on a diff line: Hover over any line in the diff - a blue + button appears on the left margin. The next useful detail is this: Click it to open a comment box for that line. Think of it like entering a new building: first you find the lobby, then the room, then the door you actually need.

      -

      Alex: The practical takeaway is this. 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.

      -

      Alex: First, navigate to the specific line in the diff (using the table navigation above). Then, while focused on that line, a comment button appears - press Enter or Space to activate it. After that, a comment box opens below the line. Finally, focus Mode → type your comment. Think of it as a rail line: each stop confirms you are still on the right route before the next one.

      -

      Jamie: Before we leave Placing an inline comment on a diff line, what is the practical point?

      -

      Alex: First, tab to Add single comment button (instant comment) OR Start a review (to batch comments). Treat it like a recipe: do not add the next ingredient until the previous one is actually in the bowl.

      -

      Jamie: Let's pause on Multi-line comment (Windows). What should a learner take away from it?

      -

      Alex: Here is the plain-English version of Multi-line comment (Windows). Screen reader users (VoiceOver - macOS).

      -

      Alex: First, focus the first line you want to comment on. Then, press Shift+↓ to extend the selection to additional lines. After that, a comment button appears - activate it. Finally, the comment applies to the full range of selected lines. Treat it like a recipe: do not add the next ingredient until the previous one is actually in the bowl.

      -

      Jamie: Before we leave Multi-line comment (Windows), what is the practical point?

      -

      Alex: First, navigate to the specific line in the diff (using the table navigation above). Then, while focused on that line, VO+Space on the comment button that appears. After that, a comment box opens below the line. Finally, vO+Shift+Down to interact with the text area, then type your comment. It is a checklist, but a meaningful one: every item creates evidence that the next step is safe.

      -

      Jamie: Let's pause on Multi-line comment (macOS). What should a learner take away from it?

      -

      Alex: Start with Multi-line comment (macOS). There is something to understand, something to try, and something that proves the try worked.

      -

      Alex: First, focus the first line and Shift+↓ to extend the selection. Then, vO+Space on the comment button that appears. After that, the comment applies to the full range of selected lines. It is a checklist, but a meaningful one: every item creates evidence that the next step is safe.

      -
      -

      Jamie: Let's pause on Viewing comments within the diff. What should a learner take away from it?

      -

      Alex: Keep the learner anchored in Viewing comments within the diff. Inline comments appear as expandable threads within the diff table. This is the part to say slowly: Navigate to them with 3 (they are h3 headings).

      -

      Alex: Keep the teaching thread moving. Start with Learning Cards: Reading the Files Changed Tab. There is something to understand, something to try, and something that proves the try worked.

      -

      Alex: The practical takeaway is this. 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. 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.

      -

      Jamie: Let's pause on Tool Cards: Open a Pull Request. What should a learner take away from it?

      -

      Alex: Start with Tool Cards: Open a Pull Request: VS Code Desktop (GitHub Pull Requests extension).

      -

      Alex: First, push your branch, then click the Compare & pull request banner (or go to Pull requests New pull request ). Then, set base branch to main, compare branch to yours. After that, fill in the title and description, then click Create pull request. Finally, after committing changes, click the Source Control icon. Think of it as a rail line: each stop confirms you are still on the right route before the next one.

      -

      Jamie: Before we leave Tool Cards: Open a Pull Request, what is the practical point?

      -

      Alex: First, click Create Pull Request in the Source Control panel header. Then, fill in details and submit. After that, press Ctrl+Shift+P, type GitHub Pull Requests: Create Pull Request. Finally, select base and compare branches. Treat it like a recipe: do not add the next ingredient until the previous one is actually in the bowl.

      -

      Alex: Treat examples as spoken recipes, not decorations. You may hear something like git push -u origin your-branch; gh pr create --title "Your title" --body "Description". Read the command, understand what it changes, then run it only when the repository state matches the lesson.

      -
      -

      Jamie: Let's pause on From the web editor workflow (editing a file on GitHub). What should a learner take away from it?

      -

      Alex: Start with From the web editor workflow (editing a file on GitHub). There is something to understand, something to try, and something that proves the try worked.

      -

      Alex: First, you edited a file → GitHub showed a "Propose changes" form. Then, you named your branch and activated "Propose changes". After that, GitHub redirected you to the "Open a pull request" page. Treat it like a recipe: do not add the next ingredient until the previous one is actually in the bowl.

      -

      Jamie: Let's pause on From a fork or feature branch. What should a learner take away from it?

      -

      Alex: This is where From a fork or feature branch becomes real: screen reader users (NVDA / JAWS - Windows). That matters in practice: Screen reader users (VoiceOver - macOS).

      -

      Alex: First, navigate to the repository on GitHub. Then, if you recently pushed, a yellow banner "Compare & pull request" appears at the top - click it. After that, if no banner appears: click the Pull requests tab → click the green New pull request button. Finally, use the branch dropdowns to choose your base branch (what to merge into) and your compare branch (your changes). It is a checklist, but a meaningful one: every item creates evidence that the next step is safe.

      -

      Jamie: Before we leave From a fork or feature branch, what is the practical point?

      -

      Alex: First, click Create pull request. Then, navigate to the repository. After that, a "Compare & pull request" banner may appear (if you recently pushed) - activate it. Finally, oR: Navigate to Pull Requests tab → "New pull request". It is like walking a hallway with named doors: read the sign, enter the right room, then confirm where you landed.

      -

      Jamie: Let's pause on Description field. What should a learner take away from it?

      -

      Alex: Keep the learner anchored in Description field. Copilot can write your PR description: If your account has Copilot access, a "Copilot actions" button appears in the description toolbar. This is the part to say slowly: 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. A good GitHub workflow is like a well-run meeting: everyone knows the topic, the next action, and who has the floor.

      -

      Alex: Treat examples as spoken recipes, not decorations. You may hear something like Step 1: Tab to the body text area; Step 2: Focus Mode → type using the PR template (if provided). 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 for the dismiss control; Related Issues; Closes 42; Testing; - Tested with NVDA + Chrome on Windows 11; -. Read the command, understand what it changes, then run it only when the repository state matches the lesson.

      -
      -

      Jamie: Let's pause on Setting a Draft PR. What should a learner take away from it?

      -

      Alex: The reason Setting a Draft PR matters is that if your work is not finished, open as a Draft.

      -

      Alex: First, after filling in the form, find the dropdown arrow next to "Create pull request". Then, select "Create draft pull request". After that, this signals to reviewers that it is not ready for formal review yet. The rhythm is simple: orient, act, verify, then continue.

      -

      Alex: Keep the teaching thread moving. Start with Draft Pull Requests - Full Lifecycle: A draft pull request is a PR explicitly marked as a work in progress. The next useful detail is this: It is visible to the team, can receive comments, and runs CI - but is blocked from being merged until you mark it ready.

      -

      Jamie: Let's pause on When to use a draft. What should a learner take away from it?

      -

      Alex: Start with When to use a draft. There is something to understand, something to try, and something that proves the try worked.

      -

      Alex: The practical takeaway is this. You want to show your approach and get early feedback before finishing. You need CI to run but don't want accidental merges. You are working across multiple days and want your progress visible. You want to pair with a collaborator on the work.

      -
      -

      Alex: Keep the teaching thread moving. Start with What a draft PR does differently. There is something to understand, something to try, and something that proves the try worked.

      -

      Alex: The practical takeaway is this. The merge button is disabled - even an authorized maintainer cannot merge a draft. The PR header shows a grey "Draft" badge instead of the green "Open" badge. Reviewers are not auto-notified (no review requests are sent until ready). CI workflows still run normally.

      -

      Jamie: Let's pause on Mark a draft ready for review. What should a learner take away from it?

      -

      Alex: Start with Mark a draft ready for review. There is something to understand, something to try, and something that proves the try worked.

      -

      Alex: First, open the PR. Then, navigate to the "Reviewers" sidebar or scroll to bottom of the Conversation tab. After that, find and activate the "Ready for review" button. Finally, the draft badge changes to "Open" and reviewers are notified. It is like walking a hallway with named doors: read the sign, enter the right room, then confirm where you landed.

      -

      Jamie: Let's pause on Convert an open PR to draft (after opening). What should a learner take away from it?

      -

      Alex: The reason Convert an open PR to draft (after opening) matters is that GitHub CLI (gh) alternative - draft PR lifecycle. That gives the learner a simple foothold: manage draft PRs from your terminal.

      -

      Alex: First, in the right sidebar, find the "Reviewers" section. Then, look for the "Convert to draft" link (below the review status). After that, confirm in the dialog - this removes merge eligibility until you mark it ready again. The rhythm is simple: orient, act, verify, then continue.

      -

      Alex: Treat examples as spoken recipes, not decorations. You may hear something like Create a draft PR; gh pr create --draft --title "WIP: Add carousel keyboard nav"; Mark a draft ready for review; gh pr ready 42; Check PR status (shows draft state); gh pr view 42; List only draft PRs; gh pr list --draft. Read the command, understand what it changes, then run it only when the repository state matches the lesson.

      -
      -

      Jamie: Let's pause on Learning Cards: Opening a Pull Request. What should a learner take away from it?

      -

      Alex: Start with Learning Cards: Opening a Pull Request. There is something to understand, something to try, and something that proves the try worked.

      -

      Alex: The practical takeaway is this. After editing a file on GitHub, the "Propose changes" form has a branch name field and a commit message field; press Tab to move between them. On the "Open a pull request" page, press F to jump to the Title field; Tab moves to the Description text area. Press Ctrl+Enter from inside the description text area to submit the PR without finding the Create button. The "Compare & pull request" yellow banner appears at the top of the repo after a recent push; at high zoom it may span the full width of the page. The branch comparison dropdowns (base and compare) use small text; zoom in on the area above the diff preview to read them. Draft PR: look for the dropdown arrow next to the green "Create pull request" button to switch to "Create draft pull request".

      -

      Jamie: Let's pause on Requesting reviewers. What should a learner take away from it?

      -

      Alex: Here is the plain-English version of Requesting reviewers. From the sidebar Reviewers section. Put another way, why some reviews are requested automatically: A file called CODEOWNERS in many repositories maps file paths to specific people or teams. It is like learning a transit route. The names of the stops matter because they tell you whether you are still going the right direction.

      -

      Alex: First, navigate to "Reviewers" heading (3 or H). Then, activate the gear button. After that, type a username in the search field. Finally, select from the dropdown. Treat it like a recipe: do not add the next ingredient until the previous one is actually in the bowl.

      -

      Jamie: Before we leave Requesting reviewers, what is the practical point?

      -

      Alex: First, escape to save. It is a checklist, but a meaningful one: every item creates evidence that the next step is safe.

      -

      Jamie: Let's pause on Submitting a Review. What should a learner take away from it?

      -

      Alex: This is where Submitting a Review becomes real: when you are asked to review a PR, you have three options.

      -

      Alex: The practical takeaway is this. Comment - leave feedback without a verdict; does not block merging. Approve - signal you are satisfied; often required before merge. Request changes - indicate changes must be addressed; blocks merge until resolved.

      -
      -

      Alex: Keep the teaching thread moving. Keep the learner anchored in Starting a review. On the Files Changed tab, when you add inline comments, choose "Start a review" instead of "Add single comment." This batches all your comments into one review submission.

      -

      Jamie: Let's pause on Completing and submitting a review. What should a learner take away from it?

      -

      Alex: The reason Completing and submitting a review matters is that after adding your inline comments via "Start a review," you must submit the review to notify the PR author. That gives the learner a simple foothold: the review is pending until you submit it.

      -

      Alex: The practical takeaway is this. The button may scroll off-screen to the right. Use horizontal scrolling or press Tab from the page top to cycle through focusable elements until you reach it. When clicked, a popover appears with a summary text area and three radio buttons ( Comment, Approve, Request changes ). At 200%+ zoom, the popover may extend below the visible viewport. Scroll down within the popover to see the Submit review button. The radio buttons are standard HTML radio buttons. In Windows High Contrast mode, the selected radio button uses the system highlight color. Keyboard shortcut: If the button is hard to find visually, press Ctrl+Shift+Enter from within any review comment text area to open the submit review dialog directly.

      -

      Alex: First, look for the Finish your review button in the top-right area of the Files Changed tab (it shows the number of pending comments). Then, click it - a popover appears with a summary text area and three radio buttons: Comment, Approve, Request changes. After that, optionally type a summary comment. Finally, select your verdict by clicking the radio button. The rhythm is simple: orient, act, verify, then continue.

      -

      Jamie: Before we leave Completing and submitting a review, what is the practical point?

      -

      Alex: First, click Submit review. Then, press 1 to go to the h1 (PR title). After that, press B (or Tab) to navigate to the "Submit review" button and activate it (Enter/Space). Finally, a "Submit review" dialog/panel appears. Think of it as a rail line: each stop confirms you are still on the right route before the next one.

      -

      Alex: Treat examples as spoken recipes, not decorations. You may hear something like View the PR diff in your terminal; gh pr diff 42; Approve a PR; gh pr review 42 --approve; Approve with a comment; gh pr review 42 --approve --body "Looks good - heading hierarchy is correct."; Request changes; gh pr review 42 --request-changes --body "The alt. Read the command, understand what it changes, then run it only when the repository state matches the lesson.

      -

      Alex: Keep the teaching thread moving. Start with GitHub shortcuts for pull requests: These are the GitHub built-in shortcuts for PR pages. The next useful detail is this: Enable Focus Mode first (NVDA: NVDA+Space, JAWS: Insert+Z) before using single-key shortcuts. Think of it like entering a new building: first you find the lobby, then the room, then the door you actually need.

      -
      -

      Jamie: Let's pause on On the PR list page. What should a learner take away from it?

      -

      Alex: Here is the plain-English version of On the PR list page. Shortcut note: For G P, press G, release it, then press P (two sequential key presses, not simultaneous).

      -

      Alex: Keep the teaching thread moving. This is where On the Files Changed tab becomes real: for the full shortcut system, see Screen Reader Cheat Sheet - GitHub Shortcuts section.

      -

      Jamie: Let's pause on Learning Cards: Submitting a Review. What should a learner take away from it?

      -

      Alex: Start with Learning Cards: Submitting a Review. There is something to understand, something to try, and something that proves the try worked.

      -

      Alex: The practical takeaway is this. The review verdict controls are inside a popover triggered by the "Finish your review" button; press 1 to return to the h1 (PR title), then B or Tab forward to find the button -- it is easy to miss because it is not a landmark. Inside the popover, Tab past the summary text area to reach a radio group labeled "Review Event"; use Up/Down Arrow to switch between Comment, Approve, and Request Changes. Shortcut: press Ctrl+Shift+Enter from any review comment text area to open the submit review dialog directly, bypassing the search for the button. The "Finish your review" button sits in the top-right corner of the Files Changed tab with a small badge showing your pending comment count; at 200%+ zoom it may scroll off-screen to the right. Inside the submit popover, the three radio buttons (Comment, Approve, Request changes) are small standard HTML radios; zoom in on the popover area or use Tab to step between them. After submitting, your review verdict appears as a colored banner in the Conversation timeline: green for Approve, red for Request Changes, grey for Comment.

      -
      -

      Alex: Keep the teaching thread moving. The reason Suggested Changes matters is that a suggested change is a special form of inline review comment where the reviewer proposes exact replacement text. That gives the learner a simple foothold: the PR author can apply the suggestion directly from GitHub - no copy-paste or separate commit needed. The interface gets friendlier when it stops being a wall of controls and starts being a set of named places.

      -

      Jamie: Let's pause on As a reviewer - inserting a suggestion. What should a learner take away from it?

      -

      Alex: Start with As a reviewer - inserting a suggestion: The suggestion block is plain Markdown text in the comment editor. The next useful detail is this: (Three backticks, the word suggestion, Enter, your text, Enter, three backticks.).

      -

      Alex: First, on the Files Changed tab, navigate to the line you want to propose a change. Then, activate the line comment button for that line (the + that appears on hover, or Tab to navigate to it). After that, in the comment text area that opens, press Ctrl+G (Windows) or Cmd+G (Mac). Finally, GitHub wraps a suggestion block around the current line content. Think of it as a rail line: each stop confirms you are still on the right route before the next one.

      -

      Jamie: Before we leave As a reviewer - inserting a suggestion, what is the practical point?

      -

      Alex: First, edit the text inside the suggestion block to show your proposed change. Then, add context above the block if helpful: "This makes the alt text more descriptive:". After that, submit as part of your review ("Start a review" → batch with other comments). Treat it like a recipe: do not add the next ingredient until the previous one is actually in the bowl.

      -

      Jamie: Let's pause on As an author - applying a suggestion. What should a learner take away from it?

      -

      Alex: Start with As an author - applying a suggestion. There is something to understand, something to try, and something that proves the try worked.

      -

      Alex: First, open the PR Conversation or Files Changed tab. Then, navigate to the inline comment containing a suggestion (it shows a diff-style preview). After that, find and activate the "Apply suggestion" button below the suggestion block. Finally, GitHub creates a commit automatically that applies the change - no file editing required. Treat it like a recipe: do not add the next ingredient until the previous one is actually in the bowl.

      -

      Jamie: Before we leave As an author - applying a suggestion, what is the practical point?

      -

      Alex: First, the conversation thread is marked as resolved. It is a checklist, but a meaningful one: every item creates evidence that the next step is safe.

      -
      -

      Jamie: Let's pause on Batching multiple suggestions into one commit. What should a learner take away from it?

      -

      Alex: Start with Batching multiple suggestions into one commit. There is something to understand, something to try, and something that proves the try worked.

      -

      Alex: First, for each suggestion you want to apply, activate "Add suggestion to batch" instead of "Apply suggestion". Then, after selecting all suggestions, activate the "Commit suggestions" button that appears at the top. After that, GitHub applies all batched suggestions in a single commit. It is a checklist, but a meaningful one: every item creates evidence that the next step is safe.

      -

      Jamie: Let's pause on When to use suggestions vs. comments. What should a learner take away from it?

      -

      Alex: Start with When to use suggestions vs. comments. There is something to understand, something to try, and something that proves the try worked.

      -

      Alex: The practical takeaway is this. Use a suggestion when you know the exact text that would fix the issue. Use a plain comment when the change requires judgment from the author (e.g., "this alt text isn't descriptive - can you describe what the image shows?"). A summary text area for overall comments. Radio buttons for Comment / Approve / Request changes.

      -

      Alex: First, after adding all your inline comments, navigate to the review summary button. Then, on Files Changed tab: find the "Review changes" button (B to navigate buttons). After that, press Enter to open the review dialog. Finally, a panel opens. It is like walking a hallway with named doors: read the sign, enter the right room, then confirm where you landed.

      -

      Jamie: Before we leave When to use suggestions vs. comments, what is the practical point?

      -

      Alex: First, switch to Focus Mode → type your summary comment. Then, navigate to the radio buttons with arrow keys → select your verdict. After that, tab to "Submit review" button → Enter. The rhythm is simple: orient, act, verify, then continue.

      -

      Jamie: Let's pause on Learning Cards: Suggested Changes. What should a learner take away from it?

      -

      Alex: Start with Learning Cards: Suggested Changes. There is something to understand, something to try, and something that proves the try worked.

      -

      Alex: The practical takeaway is this. To insert a suggestion block, press Ctrl+G (Windows) or Cmd+G (Mac) in the comment text area; the screen reader announces the inserted fence -- arrow down to edit the text between the backtick lines. Alternatively type the block manually: three backticks, the word suggestion, Enter, your replacement text, Enter, three backticks -- this avoids relying on the keyboard shortcut. As a PR author, navigate to a suggestion comment with 3, then Tab to the "Apply suggestion" button; GitHub commits the change automatically with no file editing required. Suggestion blocks render as a mini inline diff: the original line in red/pink background and your proposed replacement in green background; in high-contrast mode these use system diff colors. The "Apply suggestion" button is small and sits below the suggestion diff preview; zoom into the comment area to find it, or Tab from the suggestion text to reach it. When batching multiple suggestions, a floating "Commit suggestions" bar appears at the top of the page; at high zoom scroll up or press Home to find it.

      -
      -

      Jamie: Let's pause on Understanding Merge Options (for Maintainers). What should a learner take away from it?

      -

      Alex: Start with Understanding Merge Options (for Maintainers): When a PR is approved and checks pass, a maintainer can merge it. The next useful detail is this: The merge button section appears at the bottom of the Conversation tab.

      -

      Alex: Treat examples as spoken recipes, not decorations. You may hear something like Merge with default strategy (merge commit); gh pr merge 42; Squash and merge; gh pr merge 42 --squash; Rebase and merge; gh pr merge 42 --rebase; Delete the branch after merging; gh pr merge 42 --squash --delete-branch; Enable auto-merge (merges when checks. Read the command, understand what it changes, then run it only when the repository state matches the lesson.

      -

      Jamie: Let's pause on After a PR is merged. What should a learner take away from it?

      -

      Alex: Here is the plain-English version of After a PR is merged. for screen reader users, - deleting the branch after merge: Navigate to the "Add a comment" section (D), then press Shift+B to navigate backwards to the "Delete branch" button and activate it. Put another way, this keeps your repository clean by removing the now-merged feature branch.

      -

      Alex: The practical takeaway is this. The PR status badge changes to "Merged" (purple). The source branch can be deleted - a "Delete branch" button appears. Any linked issues with Closes N in the description are automatically closed.

      -

      Alex: Keep the teaching thread moving. This is where Auto-Merge - Merging When You Can't Wait Around becomes real: auto-merge lets you pre-authorize a PR to merge automatically the moment all branch protection requirements are satisfied - required reviews approved, all status checks passing, and the branch up to date. The workshop is closer to rehearsal than lecture. You hear the move, try the move, and then check what changed.

      -

      Alex: The practical takeaway is this. You've addressed all review comments and are waiting for CI to finish. A maintainer has approved the PR but a required check is still running. You're in a different time zone from the reviewers.

      -
      -

      Jamie: Let's pause on What happens next. What should a learner take away from it?

      -

      Alex: Start with What happens next. There is something to understand, something to try, and something that proves the try worked.

      -

      Alex: The practical takeaway is this. The PR merge box changes to show "Auto-merge enabled - merge will happen automatically". When the last required check passes (or last required review arrives), GitHub merges the PR silently. You receive a notification: "Your PR was automatically merged". If a reviewer requests changes after auto-merge is enabled, auto-merge is automatically cancelled (a new approval is required before it re-enables).

      -

      Jamie: Let's pause on Cancelling Auto-Merge. What should a learner take away from it?

      -

      Alex: The reason Cancelling Auto-Merge matters is that auto-merge is only available if the repository administrator has enabled it in Settings → General. That gives the learner a simple foothold: many open source repos have it on; some do not.

      -

      Alex: Treat examples as spoken recipes, not decorations. You may hear something like Merge box → Tab → "Disable auto-merge" button → Enter. Read the command, understand what it changes, then run it only when the repository state matches the lesson.

      -

      Jamie: Let's pause on Scenario A: "I want to review an assigned PR". What should a learner take away from it?

      -

      Alex: Start with Scenario A: "I want to review an assigned PR": Example: You are assigned to review a PR titled "Add missing NVDA shortcut to keyboard-shortcuts.md." The PR modifies docs/keyboard-shortcuts.md in the Learning Room repository and references Challenge 2.

      +

      Alex: Keep the teaching thread moving. Start with A Guide for First-Time Contributors: You do not need to be a professional developer to contribute to open source. The next useful detail is this: Documentation, accessibility improvements, and bug reports are among the most valuable contributions any project can receive. Think of it like entering a new building: first you find the lobby, then the room, then the door you actually need.

      +

      Jamie: Let's pause on 1. What Is Open Source? What should a learner take away from it?

      +

      Alex: Here is the plain-English version of 1. What Is Open Source? Open source software is software whose source code is publicly available. Put another way, anyone can read it, use it, and - in most cases - contribute to it.

      +

      Alex: The practical takeaway is this. 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.

      +

      Alex: Keep the teaching thread moving. This is where 2. Who Can Contribute? becomes real: contributors come from all backgrounds, skill levels, and countries. That matters in practice: 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.

      -

      Alex: Keep the teaching thread moving. Here is the plain-English version of Scenario B: "I want to respond to review feedback on my PR". Example: Your PR for Challenge 3 (Complete Welcome Guide) received a review comment: "The [TODO] about evaluating issues is good, but the paragraph could mention checking if the issue is already assigned." The validation bot also flagged a link text issue. It is like learning a transit route. The names of the stops matter because they tell you whether you are still going the right direction.

      -

      Jamie: Let's pause on Writing PR Descriptions That Get Reviewed. What should a learner take away from it?

      -

      Alex: This is where Writing PR Descriptions That Get Reviewed becomes real: see also: Appendix C: Markdown Reference for formatting your PR description with headings, lists, and task lists. That matters in practice: A pull request is only as useful as its description.

      -

      Jamie: Let's pause on What Reviewers Look For. What should a learner take away from it?

      -

      Alex: Keep the learner anchored in What Reviewers Look For. When a reviewer opens your PR, they are asking four questions before they ever look at the diff. This is the part to say slowly: If your description answers all four, the reviewer can jump straight into the code with context.

      -

      Alex: First, why does this change exist? -- What problem does it solve, or what goal does it advance? Then, what is the scope? -- Which files changed, and roughly how big is the change? After that, how was it tested? -- Did you verify that the change works, and how? Finally, what should I pay attention to? -- Are there tricky parts, trade-offs, or areas where you want a second opinion? It is like walking a hallway with named doors: read the sign, enter the right room, then confirm where you landed.

      +

      Jamie: Let's pause on 3. What Makes a Good First Contribution? What should a learner take away from it?

      +

      Alex: Start with 3. What Makes a Good First Contribution? There is something to understand, something to try, and something that proves the try worked.

      +

      Alex: The practical takeaway is this. 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.

      +

      Alex: Keep the teaching thread moving. The reason Signs a contribution is too large for a first attempt matters is that a well-executed small contribution is far more valuable than a large contribution that cannot be merged because it is out of scope. The interface gets friendlier when it stops being a wall of controls and starts being a set of named places.

      +

      Alex: The practical takeaway is this. 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.

      +

      Jamie: Let's pause on 4. Finding Something to Work On. What should a learner take away from it?

      +

      Alex: Start with 4. Finding Something to Work On: Most open source projects label issues that are suitable for new contributors. The next useful detail is this: How to search: On any GitHub repository, go to Issues → filter by label.

      -

      Jamie: Let's pause on The Closes XX Pattern. What should a learner take away from it?

      -

      Alex: The reason The Closes XX Pattern matters is that GitHub recognizes special keywords in PR descriptions that automatically close linked issues when the PR merges. That gives the learner a simple foothold: you do not need to close issues by hand -- just include the right keyword followed by the issue number.

      -

      Alex: Keep the teaching thread moving. Start with Before/After Structure: One of the most effective patterns for PR descriptions is showing the state before your change and the state after. The next useful detail is this: This gives the reviewer an instant mental model of what changed without reading the diff line by line. Think of it like entering a new building: first you find the lobby, then the room, then the door you actually need.

      -

      Jamie: Let's pause on A PR Description Template. What should a learner take away from it?

      -

      Alex: Here is the plain-English version of A PR Description Template. Here is a template you can copy into your PR descriptions. Put another way, not every section applies to every PR, but filling in even a few sentences per section makes a meaningful difference.

      +

      Alex: Keep the teaching thread moving. Start with Learning Cards: Finding Something to Work On. There is something to understand, something to try, and something that proves the try worked.

      +

      Alex: The practical takeaway is this. 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. 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.

      +

      Jamie: What does someone need before they touch the keyboard?

      +

      Alex: This is where 5. Reading an Issue Before You Start becomes real: before commenting "I'll take this" on an issue, ask yourself. That matters in practice: 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.

      +

      Alex: The practical takeaway is this. 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.

      +

      Jamie: Let's pause on Tool Cards: Fork, Clone, and Contribute. What should a learner take away from it?

      +

      Alex: Start with Tool Cards: Fork, Clone, and Contribute. There is something to understand, something to try, and something that proves the try worked.

      +

      Alex: First, click Fork on the repository page, then Create fork. Then, edit files directly in your fork's web interface. After that, click Contribute Open pull request to submit back to the original. Finally, fork the repo on github.com first. It is like walking a hallway with named doors: read the sign, enter the right room, then confirm where you landed.

      +

      Jamie: Before we leave Tool Cards: Fork, Clone, and Contribute, what is the practical point?

      +

      Alex: First, navigate to your fork and press. to open in the web editor. Then, edit, commit, and create a PR from the Source Control panel. After that, fork on github.com, then clone your fork: Ctrl+Shift+P Git: Clone. Finally, create a branch, make edits, commit and push. The rhythm is simple: orient, act, verify, then continue.

      +

      Alex: Treat examples as spoken recipes, not decorations. You may hear something like 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. Read the command, understand what it changes, then run it only when the repository state matches the lesson.

      -

      Alex: Keep the teaching thread moving. This is where Common Description Mistakes becomes real: even experienced contributors make these mistakes. That matters in practice: Knowing what to avoid is half the battle.

      -

      Jamie: Let's pause on Good vs. Bad: Side by Side. What should a learner take away from it?

      -

      Alex: Keep the learner anchored in Good vs. Bad: Side by Side. No context, no linked issue, no explanation of what file or what was wrong with it. This is the part to say slowly: A reviewer seeing this has to open the diff, figure out which file changed, read every line, and guess at the intent.

      -

      Alex: Keep the teaching thread moving. Start with Learning Cards: Writing PR Descriptions That Get Reviewed. There is something to understand, something to try, and something that proves the try worked.

      -

      Alex: The practical takeaway is this. Use Markdown headings ( ) in your description (Summary, Changes, Related Issues, Testing) so reviewers can press H to jump between sections. Type Closes followed by the issue number to auto-close the linked issue on merge; GitHub autocompletes when you type. Press Ctrl+Shift+P in the description text area to toggle between Write and Preview modes; Preview renders your Markdown so you can check structure before submitting. Use the Preview tab to verify your Markdown renders correctly; headings, bullet lists, and code blocks are easier to proofread in rendered form. Keep bullet points short (one line each) so the description is scannable at high zoom without excessive horizontal scrolling. When including screenshots, add alt text in the Markdown image syntax: so every reader gets the same information.

      +

      Jamie: Let's pause on The Basic Workflow. What should a learner take away from it?

      +

      Alex: Start with The Basic Workflow. There is something to understand, something to try, and something that proves the try worked.

      +

      Alex: First, fork the repository - creates your own copy on GitHub. Then, clone your fork to your computer (or open a Codespace - see Appendix N). After that, create a branch - name it something descriptive: fix/broken-link-setup-guide. Finally, make your change - edit the file, save, verify. The rhythm is simple: orient, act, verify, then continue.

      +

      Jamie: Before we leave The Basic Workflow, what is the practical point?

      +

      Alex: First, commit with a clear message - "Fix broken link in setup-guide.md line 34". Then, push to your fork. After that, open a pull request from your branch to the original repository's default branch. Finally, respond to review feedback - maintainers may ask for changes; this is normal and not a rejection. Think of it as a rail line: each stop confirms you are still on the right route before the next one.

      +

      Alex: Keep the teaching thread moving. Start with Writing a Good PR Description: Example: Fixed a broken link on line 34 of setup-guide.md. The next useful detail is this: The link pointed to /docs/old-setup which no longer exists.

      +

      Alex: The practical takeaway is this. What did you change? Why was the change needed? How did you verify it works?

      +

      Jamie: What do you want them to do when the plan breaks?

      +

      Alex: Here is the plain-English version of 7. Getting Help. It is always acceptable to ask a question on an issue or pull request. Put another way, 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.

      +

      Alex: The practical takeaway is this. 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.

      -

      Jamie: Let's pause on Try It: Read a Real Pull Request. What should a learner take away from it?

      -

      Alex: Start with Try It: Read a Real Pull Request: Time: 3 minutes What you need: Browser, signed in to GitHub. The next useful detail is this: Go to the Learning Room repository's Pull Requests tab and find any open or recently closed PR.

      -

      Alex: First, navigate to Pull Requests (G then P in Focus Mode). Then, open the first PR in the list (press Enter on its title). After that, read the description - press 2 to jump to the first section heading, then arrow down to read. Look for: which file was changed (docs/welcome.md, docs/keyboard-shortcuts.md, or docs/setup-guide.md)? Which challenge was this PR solving? Does the description. Finally, check the conversation - press 3 to jump between comments. Read what the validation bot reported - did the bot find any accessibility issues like broken headings or non-descriptive links? How did the author respond? Think of it as a rail line: each stop confirms you are still on the right route before the next one.

      -

      Jamie: Before we leave Try It: Read a Real Pull Request, what is the practical point?

      -

      Alex: First, look at the diff - press D to the "Pull request tabs" landmark, then navigate to "Files changed" and press Enter. Press H to scan the changed file headings. If the PR touched docs/welcome.md, you should see + lines where the [TODO] sections were filled in. If. Treat it like a recipe: do not add the next ingredient until the previous one is actually in the bowl.

      +

      Alex: Keep the teaching thread moving. This is where 8. After Your Contribution Is Merged becomes real: this matters for your GitHub profile. That matters in practice: 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. The workshop is closer to rehearsal than lecture. You hear the move, try the move, and then check what changed.

      +

      Alex: The practical takeaway is this. 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.

      +

      Jamie: Let's pause on 9. Building a Contribution Habit. What should a learner take away from it?

      +

      Alex: Keep the learner anchored in 9. Building a Contribution Habit. The hardest part of open source contribution is starting. This is the part to say slowly: 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.

      +

      Alex: Keep the teaching thread moving. The reason Practical habits matters is that challenge Time: Complete Challenge 8: The Culture Layer in the Challenge Hub, then advance to Chapter 09: Labels, Milestones and Projects. That gives the learner a simple foothold: next: Chapter 09: Labels, Milestones, and Projects Back: Chapter 07: Merge Conflicts Related appendices: Appendix M: Accessibility Standards Appendix F: Git Security Appendix O: Branch Protection.

      +

      Alex: The practical takeaway is this. 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.

      Jamie: What is the final checkpoint?

      Alex: You should be able to point to the evidence, explain the action, and describe what you would do next if this were a real open source project. If you can teach the move back, you have learned it.

      @@ -13290,3747 +13471,3274 @@

      Transcript

      -

      Challenge 05: Make Your Mark

      -

      Editing a file, writing a useful commit message, and connecting a change to an issue.

      +

      Day 2: Copilot and Agents

      +

      41. Episode 14: GitHub Copilot

      +

      Inline suggestions, Copilot Chat, prompting strategies, and custom instructions.

      +

      Based on: Chapter 16: GitHub Copilot

      + + +

      Download Episode 14 (MP3)

      -Read Transcript - Challenge 05: Make Your Mark +Read Transcript - Episode 14: GitHub Copilot

      Transcript

      -

      Alex: This is Challenge Coach for Make Your Mark. I am Alex, and we are going to teach the move before asking you to prove it.

      -

      Jamie: And I am Jamie. I will translate the challenge into the practical questions learners actually have while doing it.

      +

      Alex: This is Git Going with GitHub, episode 14: GitHub Copilot. I am Alex. By the end of this episode, GitHub Copilot should feel less like a wall of GitHub words and more like a set of moves you can trust.

      +

      Jamie: And I am Jamie. I am here for the practical questions: what should I listen for, what can go wrong, and what is the next calm move?

      -

      Alex: Editing a file, writing a useful commit message, and connecting a change to an issue. That is the task layer. The teaching layer is understanding why the move belongs in a contributor workflow.

      -

      Jamie: So evidence is not just proof for the facilitator. It is part of how the learner understands the workflow.

      -

      Alex: Right. A good challenge produces something inspectable: a comment, issue, branch, commit, pull request, review, or clear note about what happened.

      +

      Alex: Today we are working on this: Inline suggestions, Copilot Chat, prompting strategies, and custom instructions. I want the learner to leave with a mental map, not just a remembered path through buttons.

      +

      Jamie: So the goal is understanding first, then action, then confirmation.

      +

      Alex: Right. We are building a rhythm: orient yourself, take one intentional action, then verify what changed before moving on.

      -

      Jamie: What makes this practice feel low-stakes but still real?

      -

      Alex: Start with Challenge 5: Make Your Mark: What you will do: Edit docs/welcome.md on your branch to fix the TODO you found in Challenge 2, then commit with a meaningful message.

      -

      Jamie: How would you walk the room through that step by step?

      -

      Alex: Start with Instructions. There is something to understand, something to try, and something that proves the try worked.

      -

      Alex: First, make sure you are on your learn/YOUR-USERNAME branch (check the branch dropdown). Then, navigate to docs/welcome.md. After that, select the pencil icon (Edit this file) to open the editor. Finally, find the TODO and replace it with real content. Treat it like a recipe: do not add the next ingredient until the previous one is actually in the bowl.

      +

      Jamie: There are a lot of tools in play. How do we keep that from feeling like a contest?

      +

      Alex: Start with AI-Powered Code Assistance in VS Code: Day 2, Block 2-3 Material This guide covers GitHub Copilot: inline code suggestions, Copilot Chat (conversational assistance), custom instructions vs custom agents, effective prompting for non-code contributions, and using Accessible View to read AI-generated. The next useful detail is this: Use the official guides as companion references.

      +

      Alex: The next layer is this. Here is the plain-English version of Workshop Recommendation (Chapter 16 / Challenge 13). Free to use: GitHub Copilot Free tier is included with all GitHub accounts at no cost. Put another way, this workshop uses only the free tier. It is like learning a transit route. The names of the stops matter because they tell you whether you are still going the right direction.

      +

      Alex: The practical anchors are these. There are 3 guided challenges. Automation check: none (tool configuration is account-local and account-specific). The evidence is issue comment with checklist of completed actions. The pattern is install, prompt, apply, reflect.

      Jamie: What does the learner do first, second, and then after that?

      -

      Alex: First, write a meaningful commit message that explains what you changed and why. Then, commit directly to your branch. It is a checklist, but a meaningful one: every item creates evidence that the next step is safe.

      -

      Jamie: What is the one idea that makes the next few steps less mysterious?

      -

      Alex: This is where What makes a good commit message? becomes real: a good commit message answers: What did I change and why? That matters in practice: My commit message was: "." I changed the TODO to say.

      -

      Alex: A solid Git habit is to know which branch you are on, what changed, and what confirmation you expect before you run the next command.

      +

      Alex: Start with Challenge 13 Set. There is something to understand, something to try, and something that proves the try worked.

      +

      Alex: First, sign in to GitHub Copilot - authenticate with GitHub (VS Code 1.116+ has Copilot built in; no extension install needed). Then, ask Copilot to explain a codebase - clone the sci-fi themes repo and use Copilot Chat to understand it. After that, ask Copilot to create something new - prompt Copilot to generate a custom theme and apply it. It is a checklist, but a meaningful one: every item creates evidence that the next step is safe.

      -

      Alex: Now bring the learner back to the room. Keep the learner anchored in Peer simulation check. Compare your commit message with the peer-simulation PR title and commit message. This is the part to say slowly: Can you tell what changed just from reading it?

      -

      Jamie: What would you say to someone who is already bracing for this to be too much?

      -

      Alex: Start with What makes a good commit message. There is something to understand, something to try, and something that proves the try worked.

      -

      Alex: The parts worth keeping in working memory are these. First line: Short summary (50 characters or less is ideal), starts with the type of change. Blank line: Separates summary from body. Body (optional): Explains what changed and why.

      -

      Alex: That matters because of the next idea. Start with Simpler alternatives that are also fine: The more structured format is a convention, not a requirement. Think of it like entering a new building: first you find the lobby, then the room, then the door you actually need.

      -

      Alex: The useful habit is simple: orient first, act second, verify third. That pause before acting is part of the work.

      -
      -

      Jamie: Okay, set the room for us. What are we walking into?

      -

      Alex: Start with Alternate approaches. There is something to understand, something to try, and something that proves the try worked.

      -

      Alex: Here is what that changes in practice. github.com: Click the pencil icon on the file, make the edit, fill in the commit message at the bottom. github.dev: Press. to open the editor, edit the file, use the Source Control sidebar to commit. VS Code: Edit locally, stage with git add, commit with git commit. GitHub Desktop: Edit in your preferred editor, return to Desktop, write the message, click Commit.

      -

      Alex: A solid pull request habit is to separate three questions: what changed, why it changed, and what still needs review. That keeps the conversation useful instead of noisy.

      -

      Alex: This is where the talk moves from concept to action. This is where What matters becomes real: the learning objective is making a meaningful change and describing it in a commit message. That matters in practice: Any clear edit with any descriptive message is a success.

      -

      Jamie: Where do you want a learner to place their attention here?

      -

      Alex: Keep the learner anchored in What Is the Learning Room? The Learning Room is your own private GitHub repository for the workshop. This is the part to say slowly: When you accept the GitHub Classroom assignment in Block 0, GitHub copies the Community-Access/learning-room-template repository into the workshop classroom organization as the workshop organization/learning-room-your username.

      -
      -

      Alex: Before the learner moves on. The reason Why a Per-Student Repo? matters is that GitHub Classroom gives each participant their own repository for three reasons. That gives the learner a simple foothold: 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 interface gets friendlier when it stops being a wall of controls and starts being a set of named places.

      -

      Alex: That becomes easier when you listen for these cues. 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.

      -

      Jamie: Give me the version that sounds like an instructor, not a manual.

      -

      Alex: Start with Step-by-Step: Accept Your Classroom Assignment and Open Your Repo: This is the very first hands-on step of Day 1. The next useful detail is this: By the end of this walkthrough you will have your own Learning Room repository on GitHub and your first challenge issue waiting for you.

      Jamie: Turn that into a path someone can follow.

      -

      Alex: Start with 1. Open the assignment link. There is something to understand, something to try, and something that proves the try worked.

      -

      Alex: First, in the same browser where you are signed into GitHub, open the Day 1 assignment link the facilitator shared. Then, 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"). After that, if the page asks you to authorize GitHub Classroom to access your GitHub account, activate Authorize GitHub Classroom. This is a one-time step. Treat it like a recipe: do not add the next ingredient until the previous one is actually in the bowl.

      -
      +

      Alex: Keep the learner anchored in Challenge 13.1 Step-by-Step: Sign In to Copilot. Sign in to GitHub Copilot and verify it responds to prompts. This is the part to say slowly: VS Code desktop with your Learning Room repository open.

      +

      Alex: First, (Older VS Code only) Open the Extensions sidebar: Ctrl+Shift+X (Mac: Cmd+Shift+X). Then, (Older VS Code only) Type GitHub Copilot in the search box and press Enter. After that, (Older VS Code only) Find GitHub Copilot (publisher: GitHub) in the results. Activate Install. Finally, (Older VS Code only) VS Code may also install GitHub Copilot Chat automatically. If not, search for it separately and install it. It is like walking a hallway with named doors: read the sign, enter the right room, then confirm where you landed.

      Jamie: What is the ordered workflow?

      -

      Alex: This is where 2. Identify yourself (if asked) becomes real: GitHub Classroom may ask you to pick your name from a roster so the facilitators can match your GitHub username to the registration list.

      -

      Alex: First, 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. Then, activate the link or button next to your name. After that, 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. It is a checklist, but a meaningful one: every item creates evidence that the next step is safe.

      +

      Alex: First, sign in when prompted: activate Sign in to GitHub and complete the OAuth flow in your browser. Then, verify Copilot is active: open Copilot Chat with Ctrl+Shift+I (Mac: Cmd+Shift+I). Type Hello, are you working? and press Enter. Copilot should respond. The rhythm is simple: orient, act, verify, then continue.

      Jamie: Give me the sequence, because order matters here.

      -

      Alex: Keep the learner anchored in 3. Accept the assignment. The status page does not auto-announce when the repo is ready. This is the part to say slowly: Use Browse mode and press K to step through links until you hear your repository link, or refresh the page until it appears. A good GitHub workflow is like a well-run meeting: everyone knows the topic, the next action, and who has the floor.

      -

      Alex: First, you now see a screen with a button that says Accept this assignment (or just Accept the assignment ). Activate it. Then, 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. After that, 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/the workshop organization/learning-room-your username. It is like walking a hallway with named doors: read the sign, enter the right room, then confirm where you landed.

      -

      Jamie: Let's pause on 4. Open your new repository. What should a learner take away from it?

      -

      Alex: Start with 4. Open your new repository. There is something to understand, something to try, and something that proves the try worked.

      -

      Alex: On the ground, that means a few things. The repo name in the heading matches learning-room-your username. 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.

      -

      Alex: First, activate the link to your repository. You land on the standard GitHub repo page for the workshop organization/learning-room-your username. Then, verify three things on this page. After that, bookmark this page. You will return here for every Day 1 challenge. The rhythm is simple: orient, act, verify, then continue.

      -
      -

      Jamie: Let's pause on 5. Find your first challenge issue. What should a learner take away from it?

      -

      Alex: Start with 5. Find your first challenge issue: When your Learning Room repo is ready, Challenge 1 appears as a GitHub issue in your repo. The next useful detail is this: The facilitators prepare this by running the Student Progression Bot after students accept the Classroom assignment.

      -

      Alex: First, from your repository page, navigate to the Issues tab. Keyboard shortcut: press G then I. Then, 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]). After that, open Challenge 1. Read the issue body -- it tells you what to do, where to find evidence, and how to submit completion. Think of it as a rail line: each stop confirms you are still on the right route before the next one.

      -

      Alex: A solid issue habit is to read the title, the body, and the timeline before acting. You are listening for the requested action, the missing evidence, and the person who needs a response.

      -

      Jamie: If I am listening before the workshop starts, what should settle in my mind first?

      -

      Alex: Here is the plain-English version of 6. Confirm Aria can talk to you. The PR validation bot, Aria, posts educational feedback whenever you open a pull request. Put another way, 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 ).

      -

      Alex: Keep the thread going. This is where Workshop Recommendation (Chapter 4) becomes real: chapter 4 is a system orientation chapter. The workshop is closer to rehearsal than lecture. You hear the move, try the move, and then check what changed.

      -

      Alex: The room should hear these as checkpoints. There are 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.

      +

      Alex: The reason Challenge 13.2 Step-by-Step: Explain a Codebase matters is that use Copilot Chat to understand an unfamiliar repository by asking targeted questions. That gives the learner a simple foothold: VS Code with the sci-fi themes repository cloned.

      +

      Alex: First, open the Command Palette: Ctrl+Shift+P (Mac: Cmd+Shift+P). Then, run Git: Clone and paste: https://github.com/community-access/vscode-sci-fi-themes.git. After that, open the cloned repository when VS Code prompts. Finally, open Copilot Chat: Ctrl+Shift+I (Mac: Cmd+Shift+I). The rhythm is simple: orient, act, verify, then continue.

      +

      Jamie: How would you walk the room through that step by step?

      +

      Alex: First, ask Copilot: "What does the chat.agent.thinking.phrases setting do in VS Code?". Then, read the response. Use Alt+F2 (Accessible View) if needed to read the full text. After that, ask a follow-up: "How do I apply one of these themes to my settings.json?". Finally, follow Copilot's instructions to apply one theme to your settings.json file. Think of it as a rail line: each stop confirms you are still on the right route before the next one.

      +

      Alex: The useful habit is simple: orient first, act second, verify third. That pause before acting is part of the work.

      +

      Jamie: Let's pause on Challenge 13.3 Step-by-Step: Create Something New. What should a learner take away from it?

      +

      Alex: Start with Challenge 13.3 Step-by-Step: Create Something New: Use Copilot as a creative collaborator to generate a custom config and apply it. The next useful detail is this: VS Code with Copilot Chat open. Think of it like entering a new building: first you find the lobby, then the room, then the door you actually need.

      +

      Alex: First, open Copilot Chat: Ctrl+Shift+I (Mac: Cmd+Shift+I). Then, type a creative prompt: "Create a custom GitHub Copilot thinking phrases theme for [your favorite universe - Dune, Marvel, Studio Ghibli, Star Trek, etc.]". After that, read Copilot's generated theme. It should include an array of themed phrases. Finally, copy the generated content: select all text in the Copilot response, then Ctrl+C (Mac: Cmd+C). Think of it as a rail line: each stop confirms you are still on the right route before the next one.

      +

      Jamie: Before we leave Challenge 13.3 Step-by-Step: Create Something New, what is the practical point?

      +

      Alex: First, open your settings.json: Command Palette, then Preferences: Open User Settings (JSON). Then, paste the theme configuration into your settings. After that, save with Ctrl+S and reload VS Code: Command Palette, then Developer: Reload Window. Finally, test your new theme by asking Copilot a question and watching the thinking phrases. Treat it like a recipe: do not add the next ingredient until the previous one is actually in the bowl.

      -

      Jamie: Let's pause on Readiness Checkpoint. What should a learner take away from it?

      -

      Alex: Keep the learner anchored in Readiness Checkpoint. Before starting Chapter 5 challenges, you should be able to.

      -

      Alex: First, find docs/CHALLENGES.md in your Learning Room repository. Then, explain the flow: issue - branch - pull request - review - merge. After that, identify where Aria bot feedback appears on a PR (the Conversation tab). It is like walking a hallway with named doors: read the sign, enter the right room, then confirm where you landed.

      -

      Alex: Another way to ground it. The reason Two Tracks That Reinforce Each Other matters is that throughout Day 1 you work on two parallel learning tracks, both in your own account.

      -

      Jamie: Let's pause on Track 1: GitHub Skills Modules (Optional Self-Paced Practice). What should a learner take away from it?

      -

      Alex: Start with Track 1: GitHub Skills Modules (Optional Self-Paced Practice): 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.

      -

      Alex: A few details make that real. Introduction to GitHub - Create branch, open PR, merge. Communicate Using Markdown - Write headings, links, code, tables. Review Pull Requests - Comment, approve, suggest changes.

      +

      Jamie: What should the learner prove to themselves after each small task?

      +

      Alex: Here is the plain-English version of Completing Challenge 13: Submit Your Evidence. Open your assigned Challenge 13 issue and post a completion comment. Put another way, close your Challenge 13 issue when done.

      +

      Alex: This is where the talk moves from concept to action. Start with Expected Outcomes. There is something to understand, something to try, and something that proves the try worked.

      +

      Alex: The room should hear these as checkpoints. Student can install and authenticate GitHub Copilot Chat. Student can ask Copilot effective questions about code and settings. Student can use Copilot's output to customize their development environment. Student understands Copilot as a tool to explain and create, not just autocomplete.

      +

      Jamie: Let's pause on If You Get Stuck. What should a learner take away from it?

      +

      Alex: Keep the learner anchored in If You Get Stuck. Continue learning: The GitHub Skills courses Getting Started with GitHub Copilot and Customize Your GitHub Copilot Experience cover Copilot setup, prompting, and personalization. This is the part to say slowly: See Appendix Z for the full catalog.

      +

      Alex: First, extension installation fails? Reload VS Code: Ctrl+Shift+P, then Developer: Reload Window. Then, oAuth sign-in fails? Verify your GitHub account is active in the browser first, close VS Code and retry. After that, chat panel does not open? Try Ctrl+Shift+I (Mac: Cmd+Shift+I). If still nothing, check that the Copilot Chat extension is installed (not just the base Copilot extension). Finally, Copilot seems unresponsive? Click the model selector at the bottom of Chat panel and confirm you are signed in. It is like walking a hallway with named doors: read the sign, enter the right room, then confirm where you landed.

      +

      Jamie: Before we leave If You Get Stuck, what is the practical point?

      +

      Alex: First, cannot copy from Copilot response? Use Alt+F2 (Accessible View) to get the text in a copyable buffer. Then, ask facilitator to verify Copilot is activated and show you one example prompt. After that, finished but not sure you did it right? Compare your work against the Challenge 13 reference solution. The rhythm is simple: orient, act, verify, then continue.

      -

      Alex: This is the part worth saying out loud. Start with Track 2: Your Learning Room Repository (Required Workshop Track). There is something to understand, something to try, and something that proves the try worked.

      -

      Alex: The practical anchors are these. 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).

      -

      Jamie: Can you translate that into plain choices?

      -

      Alex: Start with How the Two Tracks Compare. There is something to understand, something to try, and something that proves the try worked.

      -

      Alex: Use the comparison to make a decision, not to recite a table. The main contrasts are: GitHub Skills (optional) means Your Learning Room (required). Create a branch in a Skills repo means Create a branch in your Learning Room. Open a PR means Open a PR.

      -

      Alex: The next layer is this. Start with Learning Cards: Two Tracks, One Account. There is something to understand, something to try, and something that proves the try worked.

      -

      Alex: For a learner, the useful signals are these. 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. 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.

      +

      Alex: Before the learner moves on. The reason Learning Moment matters is that using Copilot as a brainstorming partner helps you write documentation that others can actually understand. That gives the learner a simple foothold: the prompting skill you practiced here - asking specific questions, iterating on responses, applying results - transfers to every AI tool you will use in your career. The interface gets friendlier when it stops being a wall of controls and starts being a set of named places.

      +

      Jamie: Let's pause on Learning Pattern Used in This Chapter. What should a learner take away from it?

      +

      Alex: Start with Learning Pattern Used in This Chapter. There is something to understand, something to try, and something that proves the try worked.

      +

      Alex: First, install the tool and verify it works before starting the task. Then, use the tool to explore and understand (ask questions, read responses). After that, use the tool to create something new (generate, customize, apply). Finally, reflect on when the tool helped and when your own judgment was better. Think of it as a rail line: each stop confirms you are still on the right route before the next one.

      +

      Alex: Hold that next to this. Here is the plain-English version of About Learning Cards in This Chapter. Throughout this chapter, look for expandable "learning cards" that show how to accomplish each task from different perspectives. Put another way, not every section has every card - only the cards that add meaningful guidance for that topic are included.

      -

      Jamie: Let's pause on Your Learning Room Folder Structure. What should a learner take away from it?

      -

      Alex: The reason Your Learning Room Folder Structure matters is that 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.

      -

      Alex: These are the details that keep the idea from floating away. 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.

      -

      Alex: Here is the practical turn. Start with Your Practice Branch: In your own Learning Room repository, you decide what branches to create. The next useful detail is this: The Day 1 challenge sequence asks you to work on a single feature branch named after yourself. Think of it like entering a new building: first you find the lobby, then the room, then the door you actually need.

      -

      Alex: That shows up in the workshop in a few specific ways. 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.

      -

      Jamie: Let's pause on Why you create a separate branch. What should a learner take away from it?

      -

      Alex: Start with Why you create a separate branch. There is something to understand, something to try, and something that proves the try worked.

      -

      Alex: The practical takeaway is this. 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.

      +

      Jamie: Okay, set the room for us. What are we walking into?

      +

      Alex: This is where 1. What is GitHub Copilot becomes real: GitHub Copilot is an AI pair programmer that suggests code and text completions as you type. That matters in practice: For this workshop: Copilot helps with Markdown documentation, issue triage, PR descriptions, and commit messages - not just code.

      +

      Alex: That shows up in the workshop in a few specific ways. Complete lines of code or documentation. Generate entire functions or sections of text from comments. Answer questions about code in your workspace. Explain complex code in plain language.

      +

      Jamie: Let's pause on Installation Steps. What should a learner take away from it?

      +

      Alex: Keep the learner anchored in Installation Steps. One extension, all features: GitHub Copilot Chat is now the single all-in-one extension. This is the part to say slowly: It provides inline code suggestions, the Chat panel (Ctrl+Shift+I / Mac: Cmd+Shift+I), inline chat (Ctrl+I / Mac: Cmd+I), and all agent features. A good GitHub workflow is like a well-run meeting: everyone knows the topic, the next action, and who has the floor.

      +

      Alex: First, open Extensions sidebar: Ctrl+Shift+X (Mac: Cmd+Shift+X). Then, search for "GitHub Copilot Chat". After that, find GitHub Copilot Chat (publisher: GitHub). Finally, press Enter to open the extension detail page. It is like walking a hallway with named doors: read the sign, enter the right room, then confirm where you landed.

      +

      Jamie: Before we leave Installation Steps, what is the practical point?

      +

      Alex: First, tab to "Install" button → press Enter. Then, wait for installation to complete. The rhythm is simple: orient, act, verify, then continue.

      +

      Jamie: Let's pause on Signing In. What should a learner take away from it?

      +

      Alex: Start with Signing In. There is something to understand, something to try, and something that proves the try worked.

      +

      Alex: First, VS Code prompts: "Sign in to use GitHub Copilot". Then, navigate to the notification or click the Copilot icon in the status bar. After that, select "Sign in to GitHub". Finally, your browser opens for GitHub authentication. The rhythm is simple: orient, act, verify, then continue.

      +

      Jamie: Before we leave Signing In, what is the practical point?

      +

      Alex: First, authorize the Copilot extension. Then, return to VS Code. Think of it as a rail line: each stop confirms you are still on the right route before the next one.

      -

      Jamie: Let's pause on How to use your branch. What should a learner take away from it?

      -

      Alex: This is where How to use your branch becomes real: the Day 1 challenges (4 onward) walk you through creating and using your branch on GitHub.com. That matters in practice: Once you start working locally in Chapter 14, the same branch is what you check out.

      -

      Alex: First, create the branch on GitHub.com (Challenge 4) or locally with git checkout -b learn/ from main. Then, make your changes and commit them to the branch. After that, push the branch to GitHub if you created it locally. Finally, open a pull request from learn/ - main (Challenge 6). It is a checklist, but a meaningful one: every item creates evidence that the next step is safe.

      -

      Alex: Treat examples as spoken recipes, not decorations. You may hear something like git checkout learn/. Read the command, understand what it changes, then run it only when the repository state matches the lesson.

      -

      Jamie: Let's pause on Learning Cards: Your Practice Branch. What should a learner take away from it?

      -

      Alex: Start with Learning Cards: Your Practice Branch. There is something to understand, something to try, and something that proves the try worked.

      -

      Alex: The practical takeaway is this. 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. 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.

      -

      Jamie: Let's pause on Tool Cards: Switch to Your Practice Branch. What should a learner take away from it?

      -

      Alex: Start with Tool Cards: Switch to Your Practice Branch. There is something to understand, something to try, and something that proves the try worked.

      -

      Alex: First, on the repository page, click the branch selector dropdown (shows "main"). Then, type learn to filter, then select learn/. After that, click the branch name in the bottom-left status bar. Finally, select your learn/ branch from the list. The rhythm is simple: orient, act, verify, then continue.

      -

      Jamie: Before we leave Tool Cards: Switch to Your Practice Branch, what is the practical point?

      -

      Alex: First, click the branch name in the bottom-left status bar (or press Ctrl+Shift+P then type Git: Checkout to ). Then, select origin/learn/ from the branch list. After that, click the Current Branch dropdown at the top. Think of it as a rail line: each stop confirms you are still on the right route before the next one.

      +

      Alex: Here is the practical turn. Start with Verify activation. There is something to understand, something to try, and something that proves the try worked.

      +

      Alex: On the ground, that means a few things. Bottom-right status bar shows Copilot icon (looks like <). Icon should be active (not grayed out). If grayed out, click it to sign in.

      +

      Jamie: Let's pause on Command Palette. What should a learner take away from it?

      +

      Alex: Start with Command Palette. There is something to understand, something to try, and something that proves the try worked.

      +

      Alex: First, ctrl+Shift+P (Mac: Cmd+Shift+P). Then, type "Copilot: Check Status". After that, select it to see your subscription tier (Free, Pro, Enterprise). Treat it like a recipe: do not add the next ingredient until the previous one is actually in the bowl.

      +

      Alex: Keep the thread going. This is where Free tier includes becomes real: billing note: GitHub Copilot plan details are evolving. That matters in practice: Facilitators will provide current guidance at the workshop. The workshop is closer to rehearsal than lecture. You hear the move, try the move, and then check what changed.

      +

      Alex: These are the details that keep the idea from floating away. Completions and multi-line suggestions. Copilot Chat. Limited monthly usage (usually sufficient for documentation work).

      -

      Jamie: Let's pause on The Practice Files: What You Will Work On. What should a learner take away from it?

      -

      Alex: Start with The Practice Files: What You Will Work On: See also: Appendix C: Markdown Reference covers all Markdown syntax with accessible examples -- you will need it for editing these files. The next useful detail is this: The docs/ folder contains three practice files with intentional issues.

      -

      Alex: Hold that next to this. Here is the plain-English version of docs/welcome.md - Introduction to Open Source Contribution. This file introduces newcomers to open source. Put another way, it has three [TODO] sections where content is missing.

      -

      Jamie: Let's pause on [TODO] 1 - "Who Can Contribute?" section. What should a learner take away from it?

      -

      Alex: This is where [TODO] 1 - "Who Can Contribute?" section becomes real: [TODO: Add a paragraph explaining that contributors come from all backgrounds, skill levels, and countries. That matters in practice: Emphasize that using assistive technology is not a barrier to contribution - in fact, AT users bring a perspective that improves projects for everyone.].

      +

      Jamie: If I am listening before the workshop starts, what should settle in my mind first?

      +

      Alex: Keep the learner anchored in 3. Inline Suggestions - Ghost Text Completions. Copilot suggests completions as you type, displayed as gray "ghost text" after your cursor. This is the part to say slowly: In screen reader mode, VS Code announces suggestions rather than showing them visually.

      +

      Jamie: Let's pause on While typing. What should a learner take away from it?

      +

      Alex: The reason While typing matters is that the suggestion appears as gray "ghost text" after your cursor - a preview of what Copilot thinks you want to type next. That gives the learner a simple foothold: it's there but not inserted; press Tab to accept it or Escape to dismiss.

      +

      Alex: That becomes easier when you listen for these cues. Increase ghost text contrast: Open Settings (Ctrl+,), search editorGhostText, then customize editor.ghostText.foreground in your color theme to a darker shade such as 555555. Use Accessible View instead: Press Alt+F2 when a suggestion appears. The suggestion text renders at your configured font size in a separate pane, making it far easier to read at 200%+ zoom. Word-by-word acceptance (Ctrl+Right Arrow) lets you watch each word appear at full contrast before deciding whether to continue. High Contrast themes do not automatically restyle ghost text. The color customization above is the most reliable fix.

      +

      Alex: First, Copilot analyzes your context (file content, cursor position, nearby files). Then, generates a suggestion. After that, presents the suggestion. The rhythm is simple: orient, act, verify, then continue.

      +

      Jamie: What is the one idea that makes the next few steps less mysterious?

      +

      Alex: Start with Navigating the full Suggestions Panel (Ctrl+Enter): Pressing Ctrl+Enter opens a separate side-by-side tab showing up to 10 alternative suggestions. The next useful detail is this: Alt+F2 on a single suggestion is usually faster.

      +

      Alex: A few details make that real. Switch to your screen reader's browse/virtual mode when the panel opens (NVDA: Insert+Space to toggle off Application mode; JAWS: this may happen automatically). Use heading keys (H in NVDA/JAWS browse mode) to navigate between each suggestion -- each suggestion is announced as a heading. Each suggestion is followed by an Accept button -- navigate to it with Tab or B (button key) and press Enter to insert it at your cursor position. Press Escape or close the tab to dismiss without accepting.

      -

      Alex: That connects to another useful point. Keep the learner anchored in [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. This is the part to say slowly: What questions should you ask yourself? A good GitHub workflow is like a well-run meeting: everyone knows the topic, the next action, and who has the floor.

      -

      Jamie: Let's pause on [TODO] 3 - "After Your Contribution Is Merged" section. What should a learner take away from it?

      -

      Alex: The reason [TODO] 3 - "After Your Contribution Is Merged" section matters is that [TODO: Add a sentence or two about what this means for someone's GitHub profile and open source portfolio.]. That gives the learner a simple foothold: it also has a broken internal link that needs to be found and fixed.

      -

      Alex: Keep the teaching thread moving. Start with docs/keyboard-shortcuts.md - Screen Reader Shortcut Reference: This is a comprehensive reference with tables for NVDA, JAWS, and VoiceOver shortcuts. The next useful detail is this: It contains intentional errors in some shortcut references that students need to find and fix.

      -

      Alex: The practical takeaway is this. 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.

      +

      Alex: This is the part worth saying out loud. Start with Accepting word-by-word (Ctrl+Right Arrow / Mac: Cmd+Right Arrow) is particularly useful when. There is something to understand, something to try, and something that proves the try worked.

      +

      Alex: For a learner, the useful signals are these. The suggestion starts correctly but you want to finish differently. You want to review the suggestion incrementally. You're learning and want to see how Copilot structures responses.

      +

      Jamie: What would you say to someone who is already bracing for this to be too much?

      +

      Alex: This is where Reading Suggestions with Screen Readers becomes real: visual users: If Copilot's ghost text is getting in the way, skip to "Disabling Inline Suggestions" below. That matters in practice: Screen reader users - tuning announcement verbosity.

      Alex: A solid navigation habit is to prove where you are before activating controls. Headings, landmarks, and the address bar are not trivia; they are your map.

      +

      Jamie: Let's pause on NVDA. What should a learner take away from it?

      +

      Alex: Start with NVDA. There is something to understand, something to try, and something that proves the try worked.

      +

      Alex: First, NVDA Menu → Preferences → Settings → Presentation. Then, find "Report dynamic content changes". After that, reduce verbosity level or set specific delays. It is like walking a hallway with named doors: read the sign, enter the right room, then confirm where you landed.

      -

      Jamie: What does someone need before they touch the keyboard?

      -

      Alex: Here is the plain-English version of 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. Put another way, it contains broken links that point to incorrect URLs and incomplete steps.

      -

      Alex: The practical takeaway is this. 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.

      -

      Alex: Keep the teaching thread moving. This is where docs/CHALLENGES.md - Your Challenge Menu becomes real: this file lists all 21 challenges organized by progression level. That matters in practice: Each challenge lists the file(s) to edit, estimated time, skills practiced, and success criteria. The workshop is closer to rehearsal than lecture. You hear the move, try the move, and then check what changed.

      -

      Jamie: What should the learner prove to themselves after each small task?

      -

      Alex: Keep the learner anchored in Bonus Challenges. Five bonus challenges (A through E) are available for students who finish faster. This is the part to say slowly: These include an accessibility audit, mentoring a peer, cross-repository contribution, creating a custom workflow, and documentation improvement.

      +

      Jamie: Let's pause on JAWS. What should a learner take away from it?

      +

      Alex: Start with JAWS. There is something to understand, something to try, and something that proves the try worked.

      +

      Alex: First, settings Center → HTML/PDF/Accessibility. Then, adjust "Auto Forms Mode" and "ARIA Live Region" settings. The rhythm is simple: orient, act, verify, then continue.

      +

      Jamie: Let's pause on VoiceOver. What should a learner take away from it?

      +

      Alex: Start with VoiceOver. There is something to understand, something to try, and something that proves the try worked.

      +

      Alex: First, VoiceOver Utility → Verbosity. Then, reduce "Announcements" level. Think of it as a rail line: each stop confirms you are still on the right route before the next one.

      +

      Jamie: Where do you want a learner to place their attention here?

      +

      Alex: Here is the plain-English version of Alternative: Use Accessible View. Press Alt+F2 (Mac: Option+F2) when a suggestion appears to read it in the Accessible View (full text, no streaming).

      -

      Jamie: Let's pause on Student A (working on Challenge 3: Complete Welcome Guide). What should a learner take away from it?

      -

      Alex: The reason Student A (working on Challenge 3: Complete Welcome Guide) matters is that visibility: The PR immediately appears in the repo's Pull Requests tab.

      -

      Alex: First, finds their assigned issue (Issues tab → filter Assignee:@me). Then, opens docs/welcome.md and edits the three [TODO] sections. After that, commits to a new branch: fix/studentA-issue12. Finally, opens a pull request with description. The rhythm is simple: orient, act, verify, then continue.

      -

      Jamie: Before we leave Student A (working on Challenge 3: Complete Welcome Guide), what is the practical point?

      -

      Alex: First, submits the PR. Think of it as a rail line: each stop confirms you are still on the right route before the next one.

      -

      Jamie: Let's pause on Bot (.github/workflows/learning-room-pr-bot.yml). What should a learner take away from it?

      -

      Alex: Start with Bot (.github/workflows/learning-room-pr-bot.yml): Visibility: The bot comment appears in your PR. The next useful detail is this: You see it; the facilitators see it; nobody else does unless they have been added as a collaborator on your repo.

      -

      Alex: The practical takeaway is this. Runs within 30 seconds. 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).

      -

      Jamie: Let's pause on Step 3: Peer Review (Facilitator-Arranged). What should a learner take away from it?

      -

      Alex: Here is the plain-English version of 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. Put another way, 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. It is like learning a transit route. The names of the stops matter because they tell you whether you are still going the right direction.

      -

      Alex: First, the facilitators (Jeff and Michael) pair you with another participant. Then, they add each of you as a collaborator on the other's Learning Room repo. After that, each of you receives a notification: "You have been added as a collaborator.". Finally, you can now read the other person's PRs, leave comments, request changes, and approve. Treat it like a recipe: do not add the next ingredient until the previous one is actually in the bowl.

      -

      Jamie: Before we leave Step 3: Peer Review (Facilitator-Arranged), what is the practical point?

      -

      Alex: First, 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. It is a checklist, but a meaningful one: every item creates evidence that the next step is safe.

      +

      Alex: That matters because of the next idea. This is where Prompting Through Comments becomes real: Copilot reads inline comments as instructions. That matters in practice: Type this comment, press Enter, and Copilot drafts content based on your instruction.

      +

      Alex: A solid pull request habit is to separate three questions: what changed, why it changed, and what still needs review. That keeps the conversation useful instead of noisy.

      +

      Jamie: Give me the version that sounds like an instructor, not a manual.

      +

      Alex: Start with Temporarily disable for current language. There is something to understand, something to try, and something that proves the try worked.

      +

      Alex: The parts worth keeping in working memory are these. Click the Copilot icon in the status bar (bottom-right < icon). Select "Disable Completions for [language]".

      +

      Alex: Another way to ground it. The reason Permanently disable completions matters is that the Copilot status bar icon ( <) can be tiny at standard DPI. That gives the learner a simple foothold: use the Command Palette approach instead. The interface gets friendlier when it stops being a wall of controls and starts being a set of named places.

      +

      Alex: Here is what that changes in practice. Open Settings: Ctrl+, (Mac: Cmd+,) → search "Copilot enable" → uncheck "Enable Inline Suggestions". Ctrl+Shift+P → type "Copilot: Toggle Completions" → press Enter. This toggles inline suggestions on/off without needing to find a small icon.

      -

      Jamie: Let's pause on Visibility. What should a learner take away from it?

      -

      Alex: Start with Visibility. There is something to understand, something to try, and something that proves the try worked.

      -

      Alex: The practical takeaway is this. 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.

      -

      Jamie: Let's pause on Your assigned peer reviewer (when one is paired with you). What should a learner take away from it?

      -

      Alex: Start with Your assigned peer reviewer (when one is paired with you). There is something to understand, something to try, and something that proves the try worked.

      -

      Alex: The practical takeaway is this. 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. 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.".

      -

      Alex: First, receives notification: "PR review requested". Then, navigates to the PR in your Learning Room repo (they have collaborator access). After that, leaves review comments. Finally, submits review: Approve (or Request Changes if a [TODO] marker was missed). It is like walking a hallway with named doors: read the sign, enter the right room, then confirm where you landed.

      -

      Jamie: Before we leave Visibility, what is the practical point?

      -

      Alex: The practical takeaway is this. 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.

      +

      Jamie: How should a learner choose a tool without feeling judged by the choice?

      +

      Alex: Start with Temporarily disable via Command Palette. There is something to understand, something to try, and something that proves the try worked.

      +

      Alex: The practical takeaway is this. 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).

      +

      Alex: That connects to another useful point. Start with Permanently disable via Settings. There is something to understand, something to try, and something that proves the try worked.

      +

      Alex: The practical takeaway is this. Ctrl+, (Mac: Cmd+,) → search "inline suggestions" → toggle off "GitHub Copilot: Enable Inline Completions".

      +

      Jamie: Let's pause on Learning Cards: Inline Suggestions. What should a learner take away from it?

      +

      Alex: Start with Learning Cards: Inline Suggestions. There is something to understand, something to try, and something that proves the try worked.

      +

      Alex: The practical takeaway is this. 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. 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.

      -

      Jamie: Let's pause on You (PR author). What should a learner take away from it?

      -

      Alex: Start with You (PR author). There is something to understand, something to try, and something that proves the try worked.

      -

      Alex: First, read Aria's feedback and any human review. Then, talks to the reviewer if something is unclear. After that, makes changes based on feedback. Finally, pushes new commits to the same branch. Think of it as a rail line: each stop confirms you are still on the right route before the next one.

      -

      Jamie: Before we leave You (PR author), what is the practical point?

      -

      Alex: First, re-addresses the feedback. Treat it like a recipe: do not add the next ingredient until the previous one is actually in the bowl.

      -

      Jamie: What is the teaching move inside Visibility?

      -

      Alex: The practical takeaway is this. 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.

      -

      Alex: Keep the teaching thread moving. Start with When the review is approved (or you decide to self-merge). There is something to understand, something to try, and something that proves the try worked.

      -

      Alex: The practical takeaway is this. You merge the PR (button becomes available). PR closes, shows "merged".

      +

      Alex: Now bring the learner back to the room. Keep the learner anchored in 4. GitHub Copilot Chat - Conversational Assistance. See also: Appendix K: Copilot Reference has the complete slash command and chat variable reference. This is the part to say slowly: Copilot Chat is a full conversation interface where you ask questions, request explanations, and have content drafted. A good GitHub workflow is like a well-run meeting: everyone knows the topic, the next action, and who has the floor.

      +

      Jamie: What is the safe way to learn from that example?

      +

      Alex: The reason Opening Copilot Chat matters is that primary panel: Ctrl+Shift+I (Mac: Cmd+Shift+I). That gives the learner a simple foothold: opens the Chat panel on the right side of VS Code.

      +

      Alex: The practical takeaway is this. 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.

      +

      Alex: Treat examples as spoken recipes, not decorations. You may hear something like gh extension install github/gh-copilot. gh copilot suggest "How do I squash the last 3 commits?". Read the command, understand what it changes, then run it only when the repository state matches the lesson.

      +

      Alex: Keep the teaching thread moving. Start with Chat Modes: Copilot Chat has four modes, selected from a dropdown at the bottom of the Chat input area. The next useful detail is this: Each mode changes how Copilot interprets your request and what it can do.

      -

      Jamie: How do these exercises create confidence instead of pressure?

      -

      Alex: Start with Progression Bot Posts the Next Challenge. There is something to understand, something to try, and something that proves the try worked.

      -

      Alex: The practical takeaway is this. 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.

      -

      Alex: Keep the teaching thread moving. Start with Visibility. There is something to understand, something to try, and something that proves the try worked.

      -

      Alex: The practical takeaway is this. 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.

      -

      Jamie: Let's pause on Learning Cards: How PR Sharing Works. What should a learner take away from it?

      -

      Alex: Start with Learning Cards: How PR Sharing Works. There is something to understand, something to try, and something that proves the try worked.

      -

      Alex: The practical takeaway is this. 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. 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.

      +

      Jamie: Let's pause on Switching modes. What should a learner take away from it?

      +

      Alex: Here is the plain-English version of Switching modes. 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. Put another way, agent mode is powerful but works best once you're comfortable reviewing its output.

      +

      Alex: The practical takeaway is this. 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.

      +

      Alex: Keep the teaching thread moving. This is where Choosing a Model becomes real: Copilot gives you access to AI models from OpenAI, Anthropic (Claude), Google (Gemini), xAI (Grok), and others. That matters in practice: 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"). The workshop is closer to rehearsal than lecture. You hear the move, try the move, and then check what changed.

      +

      Jamie: Let's pause on Quick guidance. What should a learner take away from it?

      +

      Alex: Keep the learner anchored in Quick guidance. Model availability changes frequently. This is the part to say slowly: Facilitators will provide current guidance at the workshop.

      +

      Alex: The practical takeaway is this. 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.

      -

      Alex: Keep the teaching thread moving. Here is the plain-English version of The Learning Automation System. When you open a PR in the Learning Room, you get three types of feedback.

      -

      Jamie: Let's pause on Type 1: Automated Bot Feedback (30 seconds). What should a learner take away from it?

      -

      Alex: Start with Type 1: Automated Bot Feedback (30 seconds). There is something to understand, something to try, and something that proves the try worked.

      -

      Alex: The practical takeaway is this. 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.

      -

      Alex: Keep the teaching thread moving. Start with Type 2: Peer Reviewer Feedback (15-60 minutes). There is something to understand, something to try, and something that proves the try worked.

      -

      Alex: The practical takeaway is this. Human judgment on content. Creative suggestions. Encouragement and mentorship. Understanding of context. Can approve, request changes, or comment.

      +

      Jamie: Let's pause on Panel layout (top to bottom). What should a learner take away from it?

      +

      Alex: Start with Panel layout (top to bottom). There is something to understand, something to try, and something that proves the try worked.

      +

      Alex: The practical takeaway is this. Type your prompt here. Press Ctrl+Enter (Mac: Cmd+Enter) or Enter to send. Choose which AI model to use (GPT-4, Claude, etc.). Some models better for code, others for prose. Shows your previous prompts and Copilot's responses. Navigate with Up/Down Arrow.

      +

      Alex: First, chat input field (multi-line text area). Then, model selector dropdown. After that, conversation history. Finally, action buttons. The rhythm is simple: orient, act, verify, then continue.

      +

      Jamie: Let's pause on NVDA/JAWS. What should a learner take away from it?

      +

      Alex: Start with NVDA/JAWS. There is something to understand, something to try, and something that proves the try worked.

      +

      Alex: The practical takeaway is this. 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.

      +

      Alex: Keep the teaching thread moving. Start with VoiceOver. There is something to understand, something to try, and something that proves the try worked.

      +

      Alex: The practical takeaway is this. 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.

      -

      Jamie: Let's pause on Type 3: Progress Tracking (on merge). What should a learner take away from it?

      -

      Alex: The reason Type 3: Progress Tracking (on merge) matters is that together: Instant technical feedback + human mentorship + visible progress.

      -

      Alex: The practical takeaway is this. Skill badges (Markdown Master, Accessibility Advocate). Level progression (Beginner → Intermediate → Advanced → Expert). Milestone celebrations (1st, 5th, 10th PR). Motivational comments.

      -

      Jamie: Let's pause on Study Groups (Optional). What should a learner take away from it?

      -

      Alex: Start with 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.

      -

      Alex: First, group Issue Thread - Private communication space for your group. Then, shared Review Responsibility - You review each other's work. After that, collaborative Challenges - Optional group exercises. Finally, peer Support - Tag each other with questions. Think of it as a rail line: each stop confirms you are still on the right route before the next one.

      -

      Jamie: How should someone choose between those options?

      -

      Alex: Start with Key Differences: Skills Module vs. Your Learning Room. There is something to understand, something to try, and something that proves the try worked.

      -

      Alex: Use the comparison to make a decision, not to recite a table. The main contrasts are: GitHub Skills (Your Account) means Your Learning Room (Classroom). Your personal copy of a Skills repo means Your private copy of learning-room-template. Mona (GitHub) means Aria (PR validation) and the Student Progression bot.

      +

      Jamie: What stays the same when the tool changes?

      +

      Alex: This is where Using Slash Commands becomes real: type / in Copilot Chat to see available commands.

      +

      Jamie: Let's pause on Example. What should a learner take away from it?

      +

      Alex: Start with Example. There is something to understand, something to try, and something that proves the try worked.

      +

      Alex: First, select a block of complex Markdown. Then, open Chat: Ctrl+Shift+I (Mac: Cmd+Shift+I). After that, type /explain. Finally, Copilot explains the structure and purpose. It is like walking a hallway with named doors: read the sign, enter the right room, then confirm where you landed.

      +

      Jamie: Let's pause on Built-in Actions via Command Palette. What should a learner take away from it?

      +

      Alex: The reason Built-in Actions via Command Palette matters is that Copilot registers actions directly in the Command Palette. That gives the learner a simple foothold: this provides a discoverable way to use Copilot without remembering slash commands or keyboard shortcuts.

      +

      Alex: First, open Command Palette: F1 or Ctrl+Shift+P (Mac: Cmd+Shift+P). Then, type copilot. After that, browse the list of available actions. The rhythm is simple: orient, act, verify, then continue.

      -

      Alex: Keep the teaching thread moving. This is where Tips for Reviewing a Peer's PR becomes real: 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. That matters in practice: Here is how to find the PRs they want you to look at. The workshop is closer to rehearsal than lecture. You hear the move, try the move, and then check what changed.

      -

      Jamie: Let's pause on Finding PRs to Review. What should a learner take away from it?

      -

      Alex: Keep the learner anchored in Finding PRs to Review. Screen reader users (VoiceOver - macOS).

      -

      Alex: First, go to your peer's Learning Room repo (the URL the facilitators sent you, or open it from your GitHub Notifications inbox). Then, click the Pull Requests tab. After that, click the Filters dropdown - "Review requested" - your username. Finally, click any PR title to open it. It is like walking a hallway with named doors: read the sign, enter the right room, then confirm where you landed.

      -

      Alex: Treat examples as spoken recipes, not decorations. You may hear something like 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. 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. Read the command, understand what it changes, then run it only when the repository state matches the lesson.

      -

      Alex: Keep the teaching thread moving. The reason Reading a PR You're Assigned To matters is that screen reader users (VoiceOver - macOS).

      -

      Alex: The practical takeaway is this. 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.

      -
      -

      Jamie: Let's pause on Leaving a Review. What should a learner take away from it?

      -

      Alex: Start with Leaving a Review: Screen reader users (VoiceOver - macOS).

      -

      Alex: First, scroll to the comment box on the Conversation tab. Then, type your review comment. After that, click "Review Changes" (top-right of the Files Changed tab, or at the bottom of the PR page). Finally, select your review type: Comment / Approve / Request changes. Think of it as a rail line: each stop confirms you are still on the right route before the next one.

      -

      Jamie: Before we leave Leaving a Review, what is the practical point?

      -

      Alex: First, click "Submit review". Treat it like a recipe: do not add the next ingredient until the previous one is actually in the bowl.

      -

      Alex: Treat examples as spoken recipes, not decorations. You may hear something like 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". Read the command, understand what it changes, then run it only when the repository state matches the lesson.

      -

      Jamie: Let's pause on Responding to Feedback. What should a learner take away from it?

      -

      Alex: Here is the plain-English version of Responding to Feedback. Screen reader users (VoiceOver - macOS). It is like learning a transit route. The names of the stops matter because they tell you whether you are still going the right direction.

      -

      Alex: First, open your PR (Pull Requests tab → click your PR). Then, read all comments and bot feedback. After that, click in the comment box to reply. Finally, push your fixes to the same branch. Treat it like a recipe: do not add the next ingredient until the previous one is actually in the bowl.

      -

      Jamie: Before we leave Responding to Feedback, what is the practical point?

      -

      Alex: First, comment: "Updates pushed, ready for review". It is a checklist, but a meaningful one: every item creates evidence that the next step is safe.

      -

      Alex: Treat examples as spoken recipes, not decorations. You may hear something like 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". Read the command, understand what it changes, then run it only when the repository state matches the lesson.

      -

      Jamie: Let's pause on Learning Cards: Tips for PR Sharing. What should a learner take away from it?

      -

      Alex: Start with Learning Cards: Tips for PR Sharing. There is something to understand, something to try, and something that proves the try worked.

      -

      Alex: The practical takeaway is this. 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. 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.

      -
      -

      Alex: Keep the teaching thread moving. Keep the learner anchored in "Can I see other students' PRs?". Not inside their Learning Room repos -- those are private to each student. This is the part to say slowly: You can see other participants' work in two ways.

      -

      Alex: The practical takeaway is this. 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.

      -

      Jamie: Let's pause on "What if I don't agree with my assigned reviewer?". What should a learner take away from it?

      -

      Alex: The reason "What if I don't agree with my assigned reviewer?" matters is that when the facilitators pair you for peer review, the pairing is a starting point, not a mandate. That gives the learner a simple foothold: you can request additional reviewers manually.

      -

      Alex: Keep the teaching thread moving. Start with "Will my PR get lost when everyone is working at once?": Your repo is your own; you only see your own PRs. The next useful detail is this: Aria's feedback is on your PR alone, and any peer reviewer is specifically assigned to you. Think of it like entering a new building: first you find the lobby, then the room, then the door you actually need.

      -
      -

      Jamie: Let's pause on "Can I comment on someone else's PR?". What should a learner take away from it?

      -

      Alex: Here is the plain-English version of "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. Put another way, on the public accessibility-agents repo, anyone can comment on any open PR.

      -

      Alex: Keep the teaching thread moving. This is where "What if my reviewer doesn't respond?" becomes real: mention them directly in a PR comment: "@name, any thoughts on the changes I pushed?" Or ask a facilitator to follow up.

      -

      Jamie: Let's pause on "Can I work with a friend?". What should a learner take away from it?

      -

      Alex: Keep the learner anchored in "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.

      +

      Alex: Keep the teaching thread moving. Start with Learning Cards: Copilot Chat. There is something to understand, something to try, and something that proves the try worked.

      +

      Alex: The practical takeaway is this. 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?"). 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.

      +

      Jamie: Let's pause on 5. Copilot Edits -- Making Multi-File Changes. What should a learner take away from it?

      +

      Alex: Here is the plain-English version of 5. Copilot Edits -- Making Multi-File Changes. As of VS Code 1.118 (April 2026), the separate Edit chat mode is being merged into Agent mode. Put another way, agent mode now supports the same working-set diff workflow that Edit mode provided.

      +

      Alex: The practical takeaway is this. 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.

      +

      Jamie: Let's pause on How to use Copilot Edits. What should a learner take away from it?

      +

      Alex: This is where How to use Copilot Edits becomes real: Copilot Edits shows you the full diff first.

      +

      Alex: The practical takeaway is this. Click "Add Files." above the chat input,. Type in the chat input and select a file from the picker,. Right-click a file in the Explorer and choose "Add File to Copilot Edits".

      +

      Alex: First, open Copilot Chat: Ctrl+Shift+I (Mac: Cmd+Shift+I). Then, at the bottom of the Chat panel, click the mode dropdown and select Edit. After that, add files to your working set -- these are the files Copilot is allowed to edit. Finally, 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". It is a checklist, but a meaningful one: every item creates evidence that the next step is safe.

      +

      Jamie: Before we leave How to use Copilot Edits, what is the practical point?

      +

      Alex: First, press Enter -- Copilot shows a diff of proposed changes in each file. Then, review the changes: use Accept or Reject on individual files, or Accept All / Reject All. It is like walking a hallway with named doors: read the sign, enter the right room, then confirm where you landed.

      -

      Alex: Keep the teaching thread moving. The reason "How long does review take?" matters is that when pairings happen during a workshop block, typically 15-60 minutes. That gives the learner a simple foothold: if a reviewer is slow, the facilitators can step in or assign someone else. The interface gets friendlier when it stops being a wall of controls and starts being a set of named places.

      -

      Jamie: Let's pause on "What if bot feedback is wrong?". What should a learner take away from it?

      -

      Alex: Start with "What if bot feedback is wrong?": Aria is intentionally educational, not punitive -- if you disagree with a check, the facilitators can override it. The next useful detail is this: Aria is not perfect, which is exactly why human review still matters.

      -

      Alex: Keep the teaching thread moving. Here is the plain-English version of "Do I need to complete every challenge?". The Learning Room has challenges for all skill levels. Put another way, you can pick what interests you, complete at your pace, and continue after the workshop -- your repo stays yours.

      +

      Jamie: Let's pause on Navigating the diff with a screen reader. What should a learner take away from it?

      +

      Alex: Start with Navigating the diff with a screen reader. There is something to understand, something to try, and something that proves the try worked.

      +

      Alex: The practical takeaway is this. 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.

      +

      Alex: Keep the teaching thread moving. Start with Working set tips. There is something to understand, something to try, and something that proves the try worked.

      +

      Alex: The practical takeaway is this. 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.

      +

      Jamie: Let's pause on Learning Cards: Copilot Edits. What should a learner take away from it?

      +

      Alex: Start with Learning Cards: Copilot Edits. There is something to understand, something to try, and something that proves the try worked.

      +

      Alex: The practical takeaway is this. 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. 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.

      -

      Jamie: Let's pause on Celebration: You're Contributing. What should a learner take away from it?

      -

      Alex: This is where Celebration: You're Contributing becomes real: every PR you open and merge in the Learning Room is a real contribution. That matters in practice: You found something to improve You made a meaningful change You received feedback (technical + human) You incorporated suggestions You merged your work.

      -

      Alex: Keep the teaching thread moving. Keep the learner anchored in Creating, Reviewing, and Merging Pull Requests with a Screen Reader. See also: Chapter 15: Code Review covers the full review workflow including multi-file diffs and suggested changes. This is the part to say slowly: Pull requests are where your work becomes a contribution. A good GitHub workflow is like a well-run meeting: everyone knows the topic, the next action, and who has the floor.

      -

      Jamie: Where is the promise of the workshop, underneath all the logistics?

      -

      Alex: The reason Workshop Recommendation (Chapter 6) matters is that chapter 6 is the first PR-validated chapter where students convert issue work into merge-ready contributions.

      -

      Alex: The practical takeaway is this. There are 3. Each challenge should take under 10 minutes each. The evidence is PR metadata, bot checks, and merged issue linkage. The pattern is small change - linked PR - green checks.

      +

      Alex: Keep the teaching thread moving. Here is the plain-English version of 6. Agent Mode -- Let Copilot Drive. See also: Chapter 19: Accessibility Agents and Chapter 20: Build Your Agent for creating your own Copilot agent. Put another way, agent mode is the most autonomous way to use Copilot.

      +

      Alex: The practical takeaway is this. 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.

      +

      Jamie: Let's pause on How to use Agent mode. What should a learner take away from it?

      +

      Alex: Start with How to use Agent mode. There is something to understand, something to try, and something that proves the try worked.

      +

      Alex: First, open Copilot Chat: Ctrl+Shift+I (Mac: Cmd+Shift+I). Then, select Agent from the mode dropdown at the bottom of the Chat panel. After that, 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". Finally, Copilot begins working -- it shows each step it's taking and asks for approval before running terminal commands. It is a checklist, but a meaningful one: every item creates evidence that the next step is safe.

      +

      Jamie: Before we leave How to use Agent mode, what is the practical point?

      +

      Alex: First, watch the progress in the Chat panel; review any proposed changes in the editor. It is like walking a hallway with named doors: read the sign, enter the right room, then confirm where you landed.

      +

      Alex: Keep the teaching thread moving. Keep the learner anchored in 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. This is the part to say slowly: When Copilot pauses for approval, focus moves to the approval dialog in the Chat panel. A good GitHub workflow is like a well-run meeting: everyone knows the topic, the next action, and who has the floor.

      +

      Alex: The practical takeaway is this. Allow -- run this command once. Allow Always -- always allow this command type without asking again (use carefully). Cancel -- stop and don't run it.

      -

      Jamie: Let's pause on Chapter 6 Challenge Set. What should a learner take away from it?

      -

      Alex: Start with Chapter 6 Challenge Set: This is the first chapter where you edit files and create branches. The next useful detail is this: 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.

      -

      Alex: First, create one small branch change - edit a practice file on a new branch. Then, open a linked PR - use the PR template and include Closes XX. After that, pass required checks - respond to bot feedback until all required checks pass. Think of it as a rail line: each stop confirms you are still on the right route before the next one.

      -

      Jamie: Let's pause on Challenge 6.1 Step-by-Step: Create One Small Branch Change. What should a learner take away from it?

      -

      Alex: Here is the plain-English version of Challenge 6.1 Step-by-Step: Create One Small Branch Change. Edit one of the practice files and save your change on a new branch. Put another way, your Learning Room repository on GitHub.com, using the web editor.

      -

      Alex: The practical takeaway is this. 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. 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.

      -

      Alex: First, 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). Then, open the file and activate the pencil icon (Edit this file) button. After that, the file opens in the web editor. Make your change. For. Finally, keep your change small and focused. Edit only what the issue asks for. Treat it like a recipe: do not add the next ingredient until the previous one is actually in the bowl.

      -

      Jamie: Before we leave Challenge 6.1 Step-by-Step: Create One Small Branch Change, what is the practical point?

      -

      Alex: First, after editing, activate the Commit changes button (green button above the editor). Then, a dialog appears. In the Branch name field, type: fix/yourname-issueXX (replace yourname with your GitHub username, and XX with the issue number). After that, select Create a new branch for this commit and start a pull request. Finally, activate Propose changes. It is a checklist, but a meaningful one: every item creates evidence that the next step is safe.

      -

      Jamie: Let's pause on Challenge 6.2 Step-by-Step: Open a Linked PR. What should a learner take away from it?

      -

      Alex: This is where Challenge 6.2 Step-by-Step: Open a Linked PR becomes real: AI agents do not just deploy code directly; they submit pull requests. That matters in practice: Learning to edit a file, format it in Markdown, and review a PR today prepares you to audit and approve AI-generated changes tomorrow. The workshop is closer to rehearsal than lecture. You hear the move, try the move, and then check what changed.

      -

      Alex: The practical takeaway is this. "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". A summary of what you changed and why (at least 50 characters).

      -

      Alex: First, in the Title field, write a short description of your change. Then, in the Body field, use the PR template if one is provided. Make sure to. After that, verify the base branch is main and the compare branch is your fix/yourname-issueXX branch. Finally, activate the Create pull request button. It is a checklist, but a meaningful one: every item creates evidence that the next step is safe.

      +

      Jamie: Let's pause on Learning Cards: Agent Mode. What should a learner take away from it?

      +

      Alex: Start with Learning Cards: Agent Mode. There is something to understand, something to try, and something that proves the try worked.

      +

      Alex: The practical takeaway is this. 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. 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.

      +

      Alex: Keep the teaching thread moving. Start with 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. The next useful detail is this: Unlike regular inline suggestions that complete what you're currently typing, NES looks ahead to related edits elsewhere in the file.

      +

      Jamie: Let's pause on Turning on Next Edit Suggestions. What should a learner take away from it?

      +

      Alex: Start with Turning on Next Edit Suggestions. There is something to understand, something to try, and something that proves the try worked.

      +

      Alex: First, open Settings: Ctrl+, (Mac: Cmd+,). Then, search for nextEditSuggestions. After that, enable "GitHub Copilot: Next Edit Suggestions". Treat it like a recipe: do not add the next ingredient until the previous one is actually in the bowl.

      -

      Jamie: Let's pause on Challenge 6.3 Step-by-Step: Pass Required Checks. What should a learner take away from it?

      -

      Alex: Keep the learner anchored in Challenge 6.3 Step-by-Step: Pass Required Checks. Read bot feedback, fix any issues it finds, and get all required checks to pass. This is the part to say slowly: the Conversation tab of your open pull request.

      -

      Alex: The practical takeaway is this. 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.

      -

      Alex: First, wait approximately 30 seconds after opening the PR. The bot posts a validation comment. Then, read the bot comment carefully. It checks. After that, if the bot reports failures. Finally, repeat step 3 until all required checks show a green checkmark. It is like walking a hallway with named doors: read the sign, enter the right room, then confirm where you landed.

      -

      Jamie: Before we leave Challenge 6.3 Step-by-Step: Pass Required Checks, what is the practical point?

      -

      Alex: First, when all checks pass, request a review from a peer or the facilitator. The rhythm is simple: orient, act, verify, then continue.

      -

      Alex: Keep the teaching thread moving. Start with Expected Outcomes. There is something to understand, something to try, and something that proves the try worked.

      -

      Alex: The practical takeaway is this. Student opens a focused PR that maps to one issue. Student uses Closes XX correctly. Student can interpret bot feedback and improve the PR.

      -

      Jamie: Let's pause on If You Get Stuck. What should a learner take away from it?

      -

      Alex: Start with If You Get Stuck. There is something to understand, something to try, and something that proves the try worked.

      -

      Alex: First, confirm your PR includes Closes XX in title or body. Then, check that changed files are only in learning-room/. After that, open the bot validation comment and resolve one required check at a time. Finally, if checks still fail, ask for peer or facilitator review with the exact error message. Think of it as a rail line: each stop confirms you are still on the right route before the next one.

      -

      Jamie: Before we leave If You Get Stuck, what is the practical point?

      -

      Alex: First, finished but not sure you did it right? Compare your work against the Challenge 6 reference solution. Treat it like a recipe: do not add the next ingredient until the previous one is actually in the bowl.

      +

      Alex: Keep the teaching thread moving. This is where How it works in practice becomes real: nES is announced as an inline suggestion at the predicted location. That matters in practice: With screen reader optimized mode on (Shift+Alt+F1), VS Code announces when a next edit suggestion is available. The workshop is closer to rehearsal than lecture. You hear the move, try the move, and then check what changed.

      +

      Alex: The practical takeaway is this. 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.

      +

      Jamie: Let's pause on 8. Copilot on GitHub.com. What should a learner take away from it?

      +

      Alex: Keep the learner anchored in 8. Copilot on GitHub.com. You don't need VS Code to use Copilot. This is the part to say slowly: GitHub.com has Copilot built directly into the website -- useful for quick questions, reviewing code in the browser, drafting PR descriptions, and more.

      +

      Jamie: Let's pause on Opening Copilot Chat on GitHub.com. What should a learner take away from it?

      +

      Alex: The reason Opening Copilot Chat on GitHub.com matters is that Copilot on GitHub.com has context about your repositories, issues, PRs, and code -- you can reference them directly.

      +

      Alex: First, go to github.com -- you must be signed in. Then, look for the Copilot icon (a circle with dot pattern) in the top navigation bar. After that, click it (or press? then select Copilot from the command palette) to open the chat panel. Finally, type your question and press Enter. The rhythm is simple: orient, act, verify, then continue.

      -

      Alex: Keep the teaching thread moving. Here is the plain-English version of Learning Moment. A great PR is small, linked to an issue, and easy to review. Put another way, faster feedback builds confidence and momentum. It is like learning a transit route. The names of the stops matter because they tell you whether you are still going the right direction.

      -

      Jamie: Let's pause on Why this feels achievable. What should a learner take away from it?

      -

      Alex: Start with Why this feels achievable. There is something to understand, something to try, and something that proves the try worked.

      -

      Alex: The practical takeaway is this. Scope is intentionally small. Feedback is immediate and specific. Success is visible (green checks + closed issue).

      -

      Alex: Keep the teaching thread moving. Keep the learner anchored in About Learning Cards in This Chapter. This chapter provides learning cards: expandable blocks that offer perspective-specific guidance for different ways of working. This is the part to say slowly: Not every card appears at every step.

      +

      Jamie: Let's pause on Copilot for Pull Request Summaries. What should a learner take away from it?

      +

      Alex: Start with Copilot for Pull Request Summaries: When you open a pull request on GitHub.com, Copilot can generate a description for you automatically. The next useful detail is this: Copilot-generated PR descriptions are usually a solid first draft.

      +

      Alex: First, start creating a new pull request: go to your branch and select "Compare & pull request". Then, in the PR form, look for the Copilot icon next to the description field. After that, click it -- Copilot reads your commits and diff and writes a draft description. Finally, review and edit the draft -- it typically includes what changed and why. Think of it as a rail line: each stop confirms you are still on the right route before the next one.

      +

      Jamie: Before we leave Copilot for Pull Request Summaries, what is the practical point?

      +

      Alex: First, submit the PR. Treat it like a recipe: do not add the next ingredient until the previous one is actually in the bowl.

      +

      Alex: Keep the teaching thread moving. Here is the plain-English version of Copilot for Code Review on GitHub.com. Maintainers can use Copilot to review pull requests on GitHub.com. Put another way, as a contributor, you may see Copilot-authored review comments on your PR -- they look like regular review comments but are labelled "Copilot". It is like learning a transit route. The names of the stops matter because they tell you whether you are still going the right direction.

      +

      Alex: The practical takeaway is this. 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.

      +

      Jamie: Let's pause on Learning Cards: Copilot on GitHub.com. What should a learner take away from it?

      +

      Alex: Start with Learning Cards: Copilot on GitHub.com. There is something to understand, something to try, and something that proves the try worked.

      +

      Alex: The practical takeaway is this. 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. 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.

      +

      Alex: Keep the teaching thread moving. Keep the learner anchored in 9. Effective Prompting for Documentation Work. Copilot works best with clear, specific prompts. This is the part to say slowly: The more context you provide, the better the response.

      Jamie: What should they understand before typing anything?

      -

      Alex: The reason Local Git Alternative: The Full Branch-Edit-PR Workflow matters is that if you cloned the learning-room in Block 0 and prefer working locally. That gives the learner a simple foothold: the web editor workflow (pencil button, "Propose changes") is the primary path taught in this chapter.

      -

      Alex: Treat examples as spoken recipes, not decorations. You may hear something like cd /Documents/learning-room; git checkout main; git pull origin main; git checkout -b fix/welcome-todos. code docs/welcome.md. Read the command, understand what it changes, then run it only when the repository state matches the lesson.

      -

      Alex: Keep the teaching thread moving. Start with What Is a Pull Request?: A pull request (PR) is a proposal to merge changes from one branch into another. The next useful detail is this.you open a PR to request that those changes be merged into the target branch (usually main). Think of it like entering a new building: first you find the lobby, then the room, then the door you actually need.

      -

      Alex: The practical takeaway is this. Edited a file directly on GitHub (web editor). Made changes in your fork. Made changes on a feature branch. What changed - a diff of every file.

      -

      Jamie: Let's pause on Navigating to Pull Requests. What should a learner take away from it?

      -

      Alex: Here is the plain-English version of Navigating to Pull Requests. Global pull requests dashboard: GitHub now shows a global pull requests page at github.com/pulls listing all open PRs across every repository you have access to. Put another way, 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).

      -

      Alex: The practical takeaway is this. 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.

      -

      Alex: First, d → "Repository navigation" landmark. Then, k to navigate tabs → "Pull requests, [N] open". After that, enter to open. Finally, vO+U → Landmarks → navigate to "Repository navigation". Treat it like a recipe: do not add the next ingredient until the previous one is actually in the bowl.

      -

      Jamie: Before we leave Navigating to Pull Requests, what is the practical point?

      -

      Alex: First, quick Nav K or VO+Right to navigate tabs → "Pull requests". Then, vO+Space to open. It is a checklist, but a meaningful one: every item creates evidence that the next step is safe.

      +

      Alex: Start with Good prompt. There is something to understand, something to try, and something that proves the try worked.

      +

      Alex: Treat examples as spoken recipes, not decorations. You may hear something like 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. Read the command, understand what it changes, then run it only when the repository state matches the lesson.

      +

      Jamie: Let's pause on What makes it good. What should a learner take away from it?

      +

      Alex: Start with What makes it good. There is something to understand, something to try, and something that proves the try worked.

      +

      Alex: First, specific scope: "3-paragraph section". Then, clear topic: "navigate the VS Code Explorer sidebar". After that, target audience: "screen reader users" who "never used VS Code". Finally, required details: "keyboard shortcuts for NVDA and JAWS". Think of it as a rail line: each stop confirms you are still on the right route before the next one.

      +

      Jamie: Before we leave What makes it good, what is the practical point?

      +

      Alex: First, format guidance: "headings and bullet points". Treat it like a recipe: do not add the next ingredient until the previous one is actually in the bowl.

      Jamie: What should happen before anyone copies and runs it?

      -

      Alex: This is where From a PR notification becomes real: if you received a notification about a PR, follow the notification link directly to the PR page. That matters in practice: List and view pull requests from your terminal.

      -

      Alex: Treat examples as spoken recipes, not decorations. You may hear something like 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. Read the command, understand what it changes, then run it only when the repository state matches the lesson.

      -

      Jamie: Let's pause on Learning Cards: Navigating to Pull Requests. What should a learner take away from it?

      -

      Alex: Start with Learning Cards: Navigating to Pull Requests. There is something to understand, something to try, and something that proves the try worked.

      -

      Alex: The practical takeaway is this. 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. 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.

      -

      Alex: Keep the teaching thread moving. The reason The Pull Request List Page matters is that the PR list works identically to the Issues list. That gives the learner a simple foothold: for screen reader users, - PR list semantics: The PR list does not have individual ARIA item containers with per-item semantics. The interface gets friendlier when it stops being a wall of controls and starts being a set of named places.

      -

      Alex: The practical takeaway is this. 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.

      +

      Alex: Start with Pattern 2: Generate with Constraints. There is something to understand, something to try, and something that proves the try worked.

      +

      Alex: Treat examples as spoken recipes, not decorations. You may hear something like 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. Read the command, understand what it changes, then run it only when the repository state matches the lesson.

      +

      Alex: Keep the teaching thread moving. This is where Iterating on Responses becomes real: Copilot's first response is a draft.

      +

      Jamie: How do you keep commands from becoming magic words?

      +

      Alex: Keep the learner anchored in Follow-up prompts. Copilot remembers the conversation context - just say what to change.

      +

      Alex: Treat examples as spoken recipes, not decorations. You may hear something like 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. Read the command, understand what it changes, then run it only when the repository state matches the lesson.

      -

      Jamie: Let's pause on Navigating the PR Tab Bar. What should a learner take away from it?

      -

      Alex: Start with Navigating the PR Tab Bar: The Conversation, Commits, and Files changed tabs are in a "Pull request navigation tabs" landmark. The next useful detail is this: The three tabs - Conversation, Commits, and Files changed - appear just below the PR title.

      -

      Alex: The practical takeaway is this. 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.

      -

      Alex: First, press D → navigate to "Pull request navigation tabs". Then, press ← or → arrow keys to move between tab options. After that, press Enter to activate a tab. Finally, vO+U → Landmarks → "Pull request navigation tabs". Think of it as a rail line: each stop confirms you are still on the right route before the next one.

      -

      Jamie: Before we leave Navigating the PR Tab Bar, what is the practical point?

      -

      Alex: First, vO+Right to move between tabs. Then, vO+Space to activate. Treat it like a recipe: do not add the next ingredient until the previous one is actually in the bowl.

      -

      Jamie: Let's pause on PR Description. What should a learner take away from it?

      -

      Alex: Start with PR Description. There is something to understand, something to try, and something that proves the try worked.

      -

      Alex: First, 2 → navigate to "Description" h2 heading. Then, ↓ to read the description. After that, markdown renders as semantic HTML - headings, lists, code blocks are fully accessible. Treat it like a recipe: do not add the next ingredient until the previous one is actually in the bowl.

      -

      Jamie: Let's pause on Status Checks Section. What should a learner take away from it?

      -

      Alex: This is where Status Checks Section becomes real: below the description, the status checks summary shows whether automated tests passed. That matters in practice: Status checks appear as a coloured banner below the PR description - green tick for passed, red X for failed, yellow spinner for running.

      -

      Alex: The practical takeaway is this. "All checks have passed" / "Some checks failed" / "Checks pending". A "Show all checks" button or link.

      -

      Alex: First, press H or 2 to find the "Checks" or "Status checks" heading. Then, press K to navigate links for individual check names. After that, press Enter on a check to see its details. Finally, quick Nav H or VO+Cmd+H to jump to the "Checks" or "Status checks" heading. It is a checklist, but a meaningful one: every item creates evidence that the next step is safe.

      -

      Jamie: Before we leave Status Checks Section, what is the practical point?

      -

      Alex: First, quick Nav K to navigate check name links. Then, vO+Space on a check to see its details. It is like walking a hallway with named doors: read the sign, enter the right room, then confirm where you landed.

      +

      Alex: Keep the teaching thread moving. Start with Learning Cards: Effective Prompting. There is something to understand, something to try, and something that proves the try worked.

      +

      Alex: The practical takeaway is this. 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. 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.

      +

      Jamie: Let's pause on 10. Custom Instructions vs Custom Agents. What should a learner take away from it?

      +

      Alex: Start with 10. Custom Instructions vs Custom Agents: Two distinct tools shape how Copilot behaves. The next useful detail is this: Understanding the difference is critical for working with Accessibility Agents (see Chapter 16: Accessibility Agents).

      +

      Alex: Keep the teaching thread moving. Here is the plain-English version of Custom Instructions. File.github/copilot-instructions.md. Put another way, purpose: Always-on background guidance for every Copilot interaction.

      -

      Alex: Keep the teaching thread moving. Keep the learner anchored in Review Comments. Each review comment thread is an h3. A good GitHub workflow is like a well-run meeting: everyone knows the topic, the next action, and who has the floor.

      -

      Alex: The practical takeaway is this. 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.

      -

      Jamie: Let's pause on Resolving conversations. What should a learner take away from it?

      -

      Alex: The reason Resolving conversations matters is that when a review comment has been addressed, you can mark the conversation as resolved. That gives the learner a simple foothold: resolved conversations are still accessible - they collapse but can be expanded again.

      -

      Alex: First, navigate to the conversation thread (3 to jump between comment headings). Then, tab to the end of the thread to find the "Resolve conversation" button. After that, press Enter to mark it resolved. Finally, the conversation collapses and shows as "Resolved". The rhythm is simple: orient, act, verify, then continue.

      -

      Alex: Keep the teaching thread moving. Start with Learning Cards: Reading the Conversation Tab. There is something to understand, something to try, and something that proves the try worked.

      -

      Alex: The practical takeaway is this. 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. 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.

      +

      Jamie: Let's pause on What they do. What should a learner take away from it?

      +

      Alex: Start with What they do. There is something to understand, something to try, and something that proves the try worked.

      +

      Alex: The practical takeaway is this. Apply to all code suggestions automatically. Set project-wide standards. Influence tone and style. Provide context about your project's conventions.

      +

      Jamie: Let's pause on Example.github/copilot-instructions.md. What should a learner take away from it?

      +

      Alex: Keep the learner anchored in Example.github/copilot-instructions.md. When active: Every time Copilot generates a suggestion (inline or in Chat). A good GitHub workflow is like a well-run meeting: everyone knows the topic, the next action, and who has the floor.

      +

      Alex: Treat examples as spoken recipes, not decorations. You may hear something like 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. Read the command, understand what it changes, then run it only when the repository state matches the lesson.

      +

      Jamie: Let's pause on Custom Agents. What should a learner take away from it?

      +

      Alex: The reason Custom Agents matters is that files.github/agents/[name].agent.md. That gives the learner a simple foothold: purpose: On-demand, focused workflows that you deliberately invoke.

      -

      Jamie: Let's pause on Reading the Checks Tab. What should a learner take away from it?

      -

      Alex: Here is the plain-English version of Reading the Checks Tab. The Checks tab shows the status of automated tests, CI workflows, and other verification processes running on your PR. Put another way, it helps you verify whether your changes pass all required tests before merging.

      -

      Alex: The practical takeaway is this. Navigate through the check steps with K or Tab. Activate a step for more details.

      -

      Alex: First, navigate to the "Pull request tabs" landmark (D). Then, navigate between tab links (K or Tab) and activate "Checks". After that, press D to jump to the "check suites" section - this moves focus to the collapsed details button of the first check. Finally, press B or Tab to navigate between check buttons; each button is labeled with the check's name. Treat it like a recipe: do not add the next ingredient until the previous one is actually in the bowl.

      -

      Jamie: Before we leave Reading the Checks Tab, what is the practical point?

      -

      Alex: First, press Enter or Space to expand a check and reveal its logs. Then, for a summary view: press D to navigate to the "check run summary" section. After that, vO+U - Landmarks - "Pull request tabs" - activate "Checks". Finally, vO+U - Landmarks - navigate to "check suites" section. It is a checklist, but a meaningful one: every item creates evidence that the next step is safe.

      -

      Alex: Keep the teaching thread moving. Start with Learning Cards: Reading the Checks Tab. There is something to understand, something to try, and something that proves the try worked.

      -

      Alex: The practical takeaway is this. 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. 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.

      -

      Jamie: Let's pause on Reading the Files Changed Tab. What should a learner take away from it?

      -

      Alex: Keep the learner anchored in Reading the Files Changed Tab. the learner will read diffs - the before/after state of every file that changed. This is the part to say slowly: This guide uses GitHub's improved Files Changed experience.

      +

      Alex: Keep the teaching thread moving. Start with What they do. There is something to understand, something to try, and something that proves the try worked.

      +

      Alex: The practical takeaway is this. Perform specific, repeatable tasks. Can access specific tools (GitHub API, file system, terminal). Generate structured output (reports, reviews, analysis). Execute multi-step workflows.

      +

      Jamie: Let's pause on Example agent names. What should a learner take away from it?

      +

      Alex: Here is the plain-English version of Example agent names. When active: Only when you type @agent-name in Copilot Chat. Put another way, see Chapter 16: Accessibility Agents for complete agent documentation.

      +

      Alex: The practical takeaway is this. @daily-briefing - Summarize repository activity. @issue-tracker - Find and prioritize issues. @pr-review - Generate PR review documentation. @analytics - Team contribution metrics.

      +

      Jamie: What decision is this helping them make?

      +

      Alex: Start with Comparison Table. There is something to understand, something to try, and something that proves the try worked.

      +

      Alex: Use the comparison to make a decision, not to recite a table. The main contrasts are: Custom Instructions means Custom Agent. When active means Background - every interaction means On-demand - you type @agent-name. Defined in means.github/copilot-instructions.md means.github/agents/[name].agent.md.

      -

      Jamie: Let's pause on File Tree (left panel). What should a learner take away from it?

      -

      Alex: The reason File Tree (left panel) matters is that the file tree lists every changed file. That gives the learner a simple foothold: use it to jump directly to a specific file's diff.

      -

      Alex: The practical takeaway is this. 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.

      -

      Alex: First, d → navigate to "File tree" region. Then, ↑/↓ to navigate the file list. After that, enter to jump to that file's diff. Finally, vO+U → Landmarks → navigate to "File tree" region. The rhythm is simple: orient, act, verify, then continue.

      -

      Jamie: Before we leave File Tree (left panel), what is the practical point?

      -

      Alex: First, vO+Down to move through the file list. Then, vO+Space to jump to that file's diff. Think of it as a rail line: each stop confirms you are still on the right route before the next one.

      -

      Jamie: Let's pause on The Diff for a File. What should a learner take away from it?

      -

      Alex: Start with The Diff for a File. There is something to understand, something to try, and something that proves the try worked.

      -

      Alex: The practical takeaway is this. 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.

      -

      Alex: Keep the teaching thread moving. Start with Lines in a diff are read as. There is something to understand, something to try, and something that proves the try worked.

      -

      Alex: The practical takeaway is this. + Added line - line that was added. Removed line - line that was removed. Context line - unchanged line shown for context.

      +

      Jamie: Let's pause on Using Both Together. What should a learner take away from it?

      +

      Alex: Keep the learner anchored in Using Both Together. Custom instructions ensure Copilot follows your accessibility standards on every suggestion. This is the part to say slowly: Custom agents handle specific workflows like auditing, issue tracking, or automated remediation.

      +

      Jamie: Let's pause on Example workflow. What should a learner take away from it?

      +

      Alex: Start with Example workflow. There is something to understand, something to try, and something that proves the try worked.

      +

      Alex: First, your.github/copilot-instructions.md says: "Always check heading hierarchy in Markdown". Then, you invoke @insiders-a11y-tracker to scan recent changes. After that, the agent finds a heading skip (H1 → H3). Finally, you ask Copilot Chat to fix it: "Fix the heading hierarchy in this file". The rhythm is simple: orient, act, verify, then continue.

      +

      Jamie: Before we leave Example workflow, what is the practical point?

      +

      Alex: First, Copilot's fix follows your custom instructions (uses semantic HTML, adds ARIA where needed). Think of it as a rail line: each stop confirms you are still on the right route before the next one.

      +

      Jamie: Let's pause on Writing Accessibility-Focused Custom Instructions. What should a learner take away from it?

      +

      Alex: Start with Writing Accessibility-Focused Custom Instructions: Source: accessibility.github.com/documentation/guide/copilot-instructions/. The next useful detail is this: Custom instructions can be set at three levels.

      -

      Jamie: Let's pause on Navigating the diff with a screen reader. What should a learner take away from it?

      -

      Alex: This is where Navigating the diff with a screen reader becomes real: each file's diff shows added lines in green and removed lines in red. That matters in practice: Scroll the page to read through changes.

      -

      Alex: The practical takeaway is this. 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.

      -

      Alex: First, t to jump to the next diff table. Then, switch to Focus Mode: Insert+Space (NVDA) or Insert+Z (JAWS). After that, ctrl+Alt+↓ to move down one row (next diff line), Ctrl+Alt+↑ to move up. Finally, ctrl+Alt+→ to read across columns (line number change type content). It is a checklist, but a meaningful one: every item creates evidence that the next step is safe.

      -

      Jamie: Before we leave Navigating the diff with a screen reader, what is the practical point?

      -

      Alex: First, the screen reader reads: "+ Add accessible name to submit button". Then, collapsed sections contain unchanged code. Focus the expand/disclosure control and activate it (Enter or Space) to reveal the hidden lines. After that, t or VO+U → Tables → select the diff table. Finally, vO+Shift+Down to enter the table. It is like walking a hallway with named doors: read the sign, enter the right room, then confirm where you landed.

      -

      Jamie: Let's pause on Placing an inline comment on a diff line. What should a learner take away from it?

      -

      Alex: Keep the learner anchored in Placing an inline comment on a diff line. Hover over any line in the diff - a blue + button appears on the left margin. This is the part to say slowly: Click it to open a comment box for that line.

      -

      Alex: The practical takeaway is this. 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.

      -

      Alex: First, navigate to the specific line in the diff (using the table navigation above). Then, while focused on that line, a comment button appears - press Enter or Space to activate it. After that, a comment box opens below the line. Finally, focus Mode → type your comment. It is like walking a hallway with named doors: read the sign, enter the right room, then confirm where you landed.

      -

      Jamie: Before we leave Placing an inline comment on a diff line, what is the practical point?

      -

      Alex: First, tab to Add single comment button (instant comment) OR Start a review (to batch comments). The rhythm is simple: orient, act, verify, then continue.

      -

      Jamie: Let's pause on Multi-line comment (Windows). What should a learner take away from it?

      -

      Alex: The reason Multi-line comment (Windows) matters is that screen reader users (VoiceOver - macOS).

      -

      Alex: First, focus the first line you want to comment on. Then, press Shift+↓ to extend the selection to additional lines. After that, a comment button appears - activate it. Finally, the comment applies to the full range of selected lines. The rhythm is simple: orient, act, verify, then continue.

      -

      Jamie: Before we leave Multi-line comment (Windows), what is the practical point?

      -

      Alex: First, navigate to the specific line in the diff (using the table navigation above). Then, while focused on that line, VO+Space on the comment button that appears. After that, a comment box opens below the line. Finally, vO+Shift+Down to interact with the text area, then type your comment. Think of it as a rail line: each stop confirms you are still on the right route before the next one.

      +

      Jamie: Let's pause on Do's - What Makes Instructions Effective. What should a learner take away from it?

      +

      Alex: Here is the plain-English version of Do's - What Makes Instructions Effective. Use normative language: MUST, MUST NOT, SHOULD, SHOULD NOT. Put another way, most language models respond well to normative language. It is like learning a transit route. The names of the stops matter because they tell you whether you are still going the right direction.

      +

      Alex: Treat examples as spoken recipes, not decorations. You may hear something like 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. Read the command, understand what it changes, then run it only when the repository state matches the lesson.

      +

      Jamie: Let's pause on Focus on team-specific standards, not generic principles. What should a learner take away from it?

      +

      Alex: This is where Focus on team-specific standards, not generic principles becomes real: tell it what your team does specifically.

      +

      Alex: Keep the teaching thread moving. Keep the learner anchored in Use lists and checklists to structure instructions. Lists provide clear guardrails - Copilot follows them step by step.

      -

      Jamie: Let's pause on Multi-line comment (macOS). What should a learner take away from it?

      -

      Alex: Start with Multi-line comment (macOS). There is something to understand, something to try, and something that proves the try worked.

      -

      Alex: First, focus the first line and Shift+↓ to extend the selection. Then, vO+Space on the comment button that appears. After that, the comment applies to the full range of selected lines. Think of it as a rail line: each stop confirms you are still on the right route before the next one.

      -

      Jamie: Let's pause on Viewing comments within the diff. What should a learner take away from it?

      -

      Alex: Here is the plain-English version of Viewing comments within the diff. Inline comments appear as expandable threads within the diff table. Put another way, navigate to them with 3 (they are h3 headings).

      -

      Alex: Keep the teaching thread moving. Start with Learning Cards: Reading the Files Changed Tab. There is something to understand, something to try, and something that proves the try worked.

      -

      Alex: The practical takeaway is this. 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. 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.

      -
      -

      Jamie: Let's pause on Tool Cards: Open a Pull Request. What should a learner take away from it?

      -

      Alex: Keep the learner anchored in Tool Cards: Open a Pull Request. VS Code Desktop (GitHub Pull Requests extension).

      -

      Alex: First, push your branch, then click the Compare & pull request banner (or go to Pull requests New pull request ). Then, set base branch to main, compare branch to yours. After that, fill in the title and description, then click Create pull request. Finally, after committing changes, click the Source Control icon. It is like walking a hallway with named doors: read the sign, enter the right room, then confirm where you landed.

      -

      Jamie: Before we leave Tool Cards: Open a Pull Request, what is the practical point?

      -

      Alex: First, click Create Pull Request in the Source Control panel header. Then, fill in details and submit. After that, press Ctrl+Shift+P, type GitHub Pull Requests: Create Pull Request. Finally, select base and compare branches. The rhythm is simple: orient, act, verify, then continue.

      -

      Alex: Treat examples as spoken recipes, not decorations. You may hear something like git push -u origin your-branch; gh pr create --title "Your title" --body "Description". Read the command, understand what it changes, then run it only when the repository state matches the lesson.

      -

      Jamie: Let's pause on From the web editor workflow (editing a file on GitHub). What should a learner take away from it?

      -

      Alex: Start with From the web editor workflow (editing a file on GitHub). There is something to understand, something to try, and something that proves the try worked.

      -

      Alex: First, you edited a file → GitHub showed a "Propose changes" form. Then, you named your branch and activated "Propose changes". After that, GitHub redirected you to the "Open a pull request" page. The rhythm is simple: orient, act, verify, then continue.

      -

      Jamie: Let's pause on From a fork or feature branch. What should a learner take away from it?

      -

      Alex: Start with From a fork or feature branch: Screen reader users (NVDA / JAWS - Windows). The next useful detail is this: Screen reader users (VoiceOver - macOS).

      -

      Alex: First, navigate to the repository on GitHub. Then, if you recently pushed, a yellow banner "Compare & pull request" appears at the top - click it. After that, if no banner appears: click the Pull requests tab → click the green New pull request button. Finally, use the branch dropdowns to choose your base branch (what to merge into) and your compare branch (your changes). Think of it as a rail line: each stop confirms you are still on the right route before the next one.

      -

      Jamie: Before we leave From a fork or feature branch, what is the practical point?

      -

      Alex: First, click Create pull request. Then, navigate to the repository. After that, a "Compare & pull request" banner may appear (if you recently pushed) - activate it. Finally, oR: Navigate to Pull Requests tab → "New pull request". Treat it like a recipe: do not add the next ingredient until the previous one is actually in the bowl.

      -
      -

      Jamie: How do you keep commands from becoming magic words?

      -

      Alex: Here is the plain-English version of Description field. Copilot can write your PR description: If your account has Copilot access, a "Copilot actions" button appears in the description toolbar. Put another way, 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.

      -

      Alex: Treat examples as spoken recipes, not decorations. You may hear something like Step 1: Tab to the body text area; Step 2: Focus Mode → type using the PR template (if provided). 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 for the dismiss control; Related Issues; Closes 42; Testing; - Tested with NVDA + Chrome on Windows 11; -. Read the command, understand what it changes, then run it only when the repository state matches the lesson.

      -

      Jamie: Let's pause on Setting a Draft PR. What should a learner take away from it?

      -

      Alex: This is where Setting a Draft PR becomes real: if your work is not finished, open as a Draft.

      -

      Alex: First, after filling in the form, find the dropdown arrow next to "Create pull request". Then, select "Create draft pull request". After that, this signals to reviewers that it is not ready for formal review yet. It is a checklist, but a meaningful one: every item creates evidence that the next step is safe.

      -

      Alex: Keep the teaching thread moving. Keep the learner anchored in Draft Pull Requests - Full Lifecycle. A draft pull request is a PR explicitly marked as a work in progress. This is the part to say slowly: It is visible to the team, can receive comments, and runs CI - but is blocked from being merged until you mark it ready. A good GitHub workflow is like a well-run meeting: everyone knows the topic, the next action, and who has the floor.

      -
      -

      Jamie: Let's pause on When to use a draft. What should a learner take away from it?

      -

      Alex: Start with When to use a draft. There is something to understand, something to try, and something that proves the try worked.

      -

      Alex: The practical takeaway is this. You want to show your approach and get early feedback before finishing. You need CI to run but don't want accidental merges. You are working across multiple days and want your progress visible. You want to pair with a collaborator on the work.

      -

      Alex: Keep the teaching thread moving. Start with What a draft PR does differently. There is something to understand, something to try, and something that proves the try worked.

      -

      Alex: The practical takeaway is this. The merge button is disabled - even an authorized maintainer cannot merge a draft. The PR header shows a grey "Draft" badge instead of the green "Open" badge. Reviewers are not auto-notified (no review requests are sent until ready). CI workflows still run normally.

      -

      Jamie: Let's pause on Mark a draft ready for review. What should a learner take away from it?

      -

      Alex: Start with Mark a draft ready for review. There is something to understand, something to try, and something that proves the try worked.

      -

      Alex: First, open the PR. Then, navigate to the "Reviewers" sidebar or scroll to bottom of the Conversation tab. After that, find and activate the "Ready for review" button. Finally, the draft badge changes to "Open" and reviewers are notified. Treat it like a recipe: do not add the next ingredient until the previous one is actually in the bowl.

      -
      -

      Jamie: Let's pause on Convert an open PR to draft (after opening). What should a learner take away from it?

      -

      Alex: This is where Convert an open PR to draft (after opening) becomes real: GitHub CLI (gh) alternative - draft PR lifecycle. That matters in practice: Manage draft PRs from your terminal. The workshop is closer to rehearsal than lecture. You hear the move, try the move, and then check what changed.

      -

      Alex: First, in the right sidebar, find the "Reviewers" section. Then, look for the "Convert to draft" link (below the review status). After that, confirm in the dialog - this removes merge eligibility until you mark it ready again. It is a checklist, but a meaningful one: every item creates evidence that the next step is safe.

      -

      Alex: Treat examples as spoken recipes, not decorations. You may hear something like Create a draft PR; gh pr create --draft --title "WIP: Add carousel keyboard nav"; Mark a draft ready for review; gh pr ready 42; Check PR status (shows draft state); gh pr view 42; List only draft PRs; gh pr list --draft. Read the command, understand what it changes, then run it only when the repository state matches the lesson.

      -

      Jamie: Let's pause on Learning Cards: Opening a Pull Request. What should a learner take away from it?

      -

      Alex: Start with Learning Cards: Opening a Pull Request. There is something to understand, something to try, and something that proves the try worked.

      -

      Alex: The practical takeaway is this. After editing a file on GitHub, the "Propose changes" form has a branch name field and a commit message field; press Tab to move between them. On the "Open a pull request" page, press F to jump to the Title field; Tab moves to the Description text area. Press Ctrl+Enter from inside the description text area to submit the PR without finding the Create button. The "Compare & pull request" yellow banner appears at the top of the repo after a recent push; at high zoom it may span the full width of the page. The branch comparison dropdowns (base and compare) use small text; zoom in on the area above the diff preview to read them. Draft PR: look for the dropdown arrow next to the green "Create pull request" button to switch to "Create draft pull request".

      -

      Jamie: Let's pause on Requesting reviewers. What should a learner take away from it?

      -

      Alex: The reason Requesting reviewers matters is that from the sidebar Reviewers section. That gives the learner a simple foothold: why some reviews are requested automatically: A file called CODEOWNERS in many repositories maps file paths to specific people or teams.

      -

      Alex: First, navigate to "Reviewers" heading (3 or H). Then, activate the gear button. After that, type a username in the search field. Finally, select from the dropdown. The rhythm is simple: orient, act, verify, then continue.

      -

      Jamie: Before we leave Requesting reviewers, what is the practical point?

      -

      Alex: First, escape to save. Think of it as a rail line: each stop confirms you are still on the right route before the next one.

      +

      Jamie: Let's pause on Reference and enforce your design system. What should a learner take away from it?

      +

      Alex: The reason Reference and enforce your design system matters is that document which components to use and which are deprecated. That gives the learner a simple foothold: design systems evolve - keep instructions current.

      +

      Alex: Keep the teaching thread moving. Start with Don'ts - Common Instruction Mistakes: Copilot is already trained on WCAG. The next useful detail is this: Pasting the full text wastes context space and dilutes your specific instructions. Think of it like entering a new building: first you find the lobby, then the room, then the door you actually need.

      +

      Jamie: Let's pause on Additional Guidance. What should a learner take away from it?

      +

      Alex: Here is the plain-English version of Additional Guidance. Role-based prompting - You can give Copilot a persona to shape how it responds. Put another way, be specific about skills and responsibilities; avoid broad personas that may introduce unintended assumptions.

      -

      Jamie: Let's pause on Submitting a Review. What should a learner take away from it?

      -

      Alex: Start with Submitting a Review: When you are asked to review a PR, you have three options.

      -

      Alex: The practical takeaway is this. Comment - leave feedback without a verdict; does not block merging. Approve - signal you are satisfied; often required before merge. Request changes - indicate changes must be addressed; blocks merge until resolved.

      -

      Alex: Keep the teaching thread moving. Here is the plain-English version of Starting a review. On the Files Changed tab, when you add inline comments, choose "Start a review" instead of "Add single comment." This batches all your comments into one review submission. It is like learning a transit route. The names of the stops matter because they tell you whether you are still going the right direction.

      -

      Jamie: Let's pause on Completing and submitting a review. What should a learner take away from it?

      -

      Alex: This is where Completing and submitting a review becomes real: after adding your inline comments via "Start a review," you must submit the review to notify the PR author. That matters in practice: The review is pending until you submit it.

      -

      Alex: The practical takeaway is this. The button may scroll off-screen to the right. Use horizontal scrolling or press Tab from the page top to cycle through focusable elements until you reach it. When clicked, a popover appears with a summary text area and three radio buttons ( Comment, Approve, Request changes ). At 200%+ zoom, the popover may extend below the visible viewport. Scroll down within the popover to see the Submit review button. The radio buttons are standard HTML radio buttons. In Windows High Contrast mode, the selected radio button uses the system highlight color. Keyboard shortcut: If the button is hard to find visually, press Ctrl+Shift+Enter from within any review comment text area to open the submit review dialog directly.

      -

      Alex: First, look for the Finish your review button in the top-right area of the Files Changed tab (it shows the number of pending comments). Then, click it - a popover appears with a summary text area and three radio buttons: Comment, Approve, Request changes. After that, optionally type a summary comment. Finally, select your verdict by clicking the radio button. It is a checklist, but a meaningful one: every item creates evidence that the next step is safe.

      -

      Jamie: Before we leave Completing and submitting a review, what is the practical point?

      -

      Alex: First, click Submit review. Then, press 1 to go to the h1 (PR title). After that, press B (or Tab) to navigate to the "Submit review" button and activate it (Enter/Space). Finally, a "Submit review" dialog/panel appears. It is like walking a hallway with named doors: read the sign, enter the right room, then confirm where you landed.

      -

      Alex: Treat examples as spoken recipes, not decorations. You may hear something like View the PR diff in your terminal; gh pr diff 42; Approve a PR; gh pr review 42 --approve; Approve with a comment; gh pr review 42 --approve --body "Looks good - heading hierarchy is correct."; Request changes; gh pr review 42 --request-changes --body "The alt. Read the command, understand what it changes, then run it only when the repository state matches the lesson.

      +

      Alex: Keep the teaching thread moving. This is where Accessibility Resources for Custom Instructions becomes real: these resources can help you write better accessibility-focused custom instructions and evaluate Copilot's output.

      +

      Alex: The practical takeaway is this. A11y LLM Evaluation Report - GitHub's own evaluation of how well LLMs handle accessibility tasks, with practical benchmarks: Accessibility LLM Evaluation. 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. Markdown Accessibility Review Guidelines - A practical guide for reviewing Markdown output for accessibility, useful as a reference when writing documentation-focused instructions: Markdown Accessibility.

      +

      Jamie: Let's pause on 11. Using Accessible View with Copilot Responses. What should a learner take away from it?

      +

      Alex: Keep the learner anchored in 11. Using Accessible View with Copilot Responses. Copilot Chat responses stream in token by token. This is the part to say slowly: This is visually nice but can fragment screen reader announcements.

      +

      Alex: Keep the teaching thread moving. Start with Without Accessible View. There is something to understand, something to try, and something that proves the try worked.

      +

      Alex: The practical takeaway is this. 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.

      -

      Alex: Keep the teaching thread moving. Keep the learner anchored in GitHub shortcuts for pull requests. These are the GitHub built-in shortcuts for PR pages. This is the part to say slowly: Enable Focus Mode first (NVDA: NVDA+Space, JAWS: Insert+Z) before using single-key shortcuts.

      -

      Jamie: Let's pause on On the PR list page. What should a learner take away from it?

      -

      Alex: The reason On the PR list page matters is that shortcut note: For G P, press G, release it, then press P (two sequential key presses, not simultaneous).

      -

      Alex: Keep the teaching thread moving. Start with On the Files Changed tab: For the full shortcut system, see Screen Reader Cheat Sheet - GitHub Shortcuts section. Think of it like entering a new building: first you find the lobby, then the room, then the door you actually need.

      +

      Jamie: Let's pause on With Accessible View (Alt+F2 / Mac: Option+F2). What should a learner take away from it?

      +

      Alex: Start with With Accessible View (Alt+F2 / Mac: Option+F2). There is something to understand, something to try, and something that proves the try worked.

      +

      Alex: The practical takeaway is this. 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.

      +

      Jamie: Let's pause on Every time you ask Copilot something. What should a learner take away from it?

      +

      Alex: Here is the plain-English version of Every time you ask Copilot something. VS Code December 2025 update: The Accessible View now updates dynamically as responses stream in. Put another way, 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.

      +

      Alex: First, type your prompt in Chat input. Then, press Ctrl+Enter (Mac: Cmd+Enter) to send. After that, press Alt+F2 (Mac: Option+F2) to open Accessible View - you can open it immediately after sending, before the response finishes. Finally, follow along as the response streams in the Accessible View in real-time. Treat it like a recipe: do not add the next ingredient until the previous one is actually in the bowl.

      +

      Jamie: Before we leave Every time you ask Copilot something, what is the practical point?

      +

      Alex: First, read or re-read any section with Arrow keys. Then, press Escape to close Accessible View and return to Chat. It is a checklist, but a meaningful one: every item creates evidence that the next step is safe.

      +

      Jamie: Let's pause on Benefits. What should a learner take away from it?

      +

      Alex: Start with Benefits. There is something to understand, something to try, and something that proves the try worked.

      +

      Alex: The practical takeaway is this. Follow responses live without waiting. Navigate and re-read at your own pace. Code blocks and lists are properly structured. Headings are announced correctly.

      -

      Jamie: Let's pause on Learning Cards: Submitting a Review. What should a learner take away from it?

      -

      Alex: Start with Learning Cards: Submitting a Review. There is something to understand, something to try, and something that proves the try worked.

      -

      Alex: The practical takeaway is this. The review verdict controls are inside a popover triggered by the "Finish your review" button; press 1 to return to the h1 (PR title), then B or Tab forward to find the button -- it is easy to miss because it is not a landmark. Inside the popover, Tab past the summary text area to reach a radio group labeled "Review Event"; use Up/Down Arrow to switch between Comment, Approve, and Request Changes. Shortcut: press Ctrl+Shift+Enter from any review comment text area to open the submit review dialog directly, bypassing the search for the button. The "Finish your review" button sits in the top-right corner of the Files Changed tab with a small badge showing your pending comment count; at 200%+ zoom it may scroll off-screen to the right. Inside the submit popover, the three radio buttons (Comment, Approve, Request changes) are small standard HTML radios; zoom in on the popover area or use Tab to step between them. After submitting, your review verdict appears as a colored banner in the Conversation timeline: green for Approve, red for Request Changes, grey for Comment.

      -

      Alex: Keep the teaching thread moving. This is where Suggested Changes becomes real: a suggested change is a special form of inline review comment where the reviewer proposes exact replacement text. That matters in practice: The PR author can apply the suggestion directly from GitHub - no copy-paste or separate commit needed.

      -

      Jamie: Let's pause on As a reviewer - inserting a suggestion. What should a learner take away from it?

      -

      Alex: Keep the learner anchored in As a reviewer - inserting a suggestion. The suggestion block is plain Markdown text in the comment editor. This is the part to say slowly: (Three backticks, the word suggestion, Enter, your text, Enter, three backticks.).

      -

      Alex: First, on the Files Changed tab, navigate to the line you want to propose a change. Then, activate the line comment button for that line (the + that appears on hover, or Tab to navigate to it). After that, in the comment text area that opens, press Ctrl+G (Windows) or Cmd+G (Mac). Finally, GitHub wraps a suggestion block around the current line content. It is like walking a hallway with named doors: read the sign, enter the right room, then confirm where you landed.

      -

      Jamie: Before we leave As a reviewer - inserting a suggestion, what is the practical point?

      -

      Alex: First, edit the text inside the suggestion block to show your proposed change. Then, add context above the block if helpful: "This makes the alt text more descriptive:". After that, submit as part of your review ("Start a review" → batch with other comments). The rhythm is simple: orient, act, verify, then continue.

      +

      Jamie: Let's pause on When a suggestion appears. What should a learner take away from it?

      +

      Alex: Keep the learner anchored in When a suggestion appears. 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 part to say slowly: This is the recommended workflow for screen reader users. A good GitHub workflow is like a well-run meeting: everyone knows the topic, the next action, and who has the floor.

      +

      Alex: First, don't accept it immediately. Then, press Alt+F2 (Mac: Option+F2). After that, accessible View shows: "Suggestion: [full text of the suggestion]". Finally, read it completely. It is like walking a hallway with named doors: read the sign, enter the right room, then confirm where you landed.

      +

      Jamie: Before we leave When a suggestion appears, what is the practical point?

      +

      Alex: First, to insert the suggestion at your cursor: press Ctrl+/ (Mac: Cmd+/). Then, to close without inserting: press Escape, then Tab to accept or Escape to reject. The rhythm is simple: orient, act, verify, then continue.

      +

      Jamie: Let's pause on Code Blocks in Accessible View. What should a learner take away from it?

      +

      Alex: The reason Code Blocks in Accessible View matters is that when Copilot suggests code or Markdown.

      +

      Alex: Keep the teaching thread moving. Start with In Accessible View: NVDA/JAWS: Use Arrow keys to read line by line. The next useful detail is this: Use Ctrl+Home to jump to the start.

      +

      Alex: The practical takeaway is this. 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.

      -

      Jamie: Let's pause on As an author - applying a suggestion. What should a learner take away from it?

      -

      Alex: Start with As an author - applying a suggestion. There is something to understand, something to try, and something that proves the try worked.

      -

      Alex: First, open the PR Conversation or Files Changed tab. Then, navigate to the inline comment containing a suggestion (it shows a diff-style preview). After that, find and activate the "Apply suggestion" button below the suggestion block. Finally, GitHub creates a commit automatically that applies the change - no file editing required. The rhythm is simple: orient, act, verify, then continue.

      -

      Jamie: Before we leave As an author - applying a suggestion, what is the practical point?

      -

      Alex: First, the conversation thread is marked as resolved. Think of it as a rail line: each stop confirms you are still on the right route before the next one.

      -

      Jamie: Let's pause on Batching multiple suggestions into one commit. What should a learner take away from it?

      -

      Alex: Start with Batching multiple suggestions into one commit. There is something to understand, something to try, and something that proves the try worked.

      -

      Alex: First, for each suggestion you want to apply, activate "Add suggestion to batch" instead of "Apply suggestion". Then, after selecting all suggestions, activate the "Commit suggestions" button that appears at the top. After that, GitHub applies all batched suggestions in a single commit. Think of it as a rail line: each stop confirms you are still on the right route before the next one.

      -

      Jamie: Let's pause on When to use suggestions vs. comments. What should a learner take away from it?

      -

      Alex: Start with When to use suggestions vs. comments. There is something to understand, something to try, and something that proves the try worked.

      -

      Alex: The practical takeaway is this. Use a suggestion when you know the exact text that would fix the issue. Use a plain comment when the change requires judgment from the author (e.g., "this alt text isn't descriptive - can you describe what the image shows?"). A summary text area for overall comments. Radio buttons for Comment / Approve / Request changes.

      -

      Alex: First, after adding all your inline comments, navigate to the review summary button. Then, on Files Changed tab: find the "Review changes" button (B to navigate buttons). After that, press Enter to open the review dialog. Finally, a panel opens. Treat it like a recipe: do not add the next ingredient until the previous one is actually in the bowl.

      -

      Jamie: Before we leave When to use suggestions vs. comments, what is the practical point?

      -

      Alex: First, switch to Focus Mode → type your summary comment. Then, navigate to the radio buttons with arrow keys → select your verdict. After that, tab to "Submit review" button → Enter. It is a checklist, but a meaningful one: every item creates evidence that the next step is safe.

      +

      Jamie: Let's pause on Learning Cards: Using Accessible View with Copilot Responses. What should a learner take away from it?

      +

      Alex: Start with Learning Cards: Using Accessible View with Copilot Responses. There is something to understand, something to try, and something that proves the try worked.

      +

      Alex: The practical takeaway is this. 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. 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.

      +

      Alex: Keep the teaching thread moving. This is where GitHub.com Shortcuts (Not VS Code) becomes real: these shortcuts work on GitHub.com in your browser, not inside VS Code. That matters in practice: Students sometimes confuse them with Copilot shortcuts because they involve similar key combinations. The workshop is closer to rehearsal than lecture. You hear the move, try the move, and then check what changed.

      +

      Jamie: Let's pause on Video Tutorials (Screen Reader Demonstrations). What should a learner take away from it?

      +

      Alex: Keep the learner anchored in Video Tutorials (Screen Reader Demonstrations). GitHub's accessibility team has published screen reader walkthroughs for each major Copilot feature. This is the part to say slowly: These are sourced from the official GitHub Accessibility guide for Copilot in VS Code.

      +

      Alex: The practical takeaway is this. Inline suggestions with a screen reader - accepting, rejecting, and reviewing ghost text suggestions with NVDA. Inline chat with a screen reader - using Ctrl+I to edit code in place with screen reader feedback. Chat view with a screen reader - navigating the Chat panel, reading responses, and using Accessible View. Built-in actions with a screen reader - running Copilot commands from the Command Palette.

      -

      Jamie: Let's pause on Learning Cards: Suggested Changes. What should a learner take away from it?

      -

      Alex: Start with Learning Cards: Suggested Changes. There is something to understand, something to try, and something that proves the try worked.

      -

      Alex: The practical takeaway is this. To insert a suggestion block, press Ctrl+G (Windows) or Cmd+G (Mac) in the comment text area; the screen reader announces the inserted fence -- arrow down to edit the text between the backtick lines. Alternatively type the block manually: three backticks, the word suggestion, Enter, your replacement text, Enter, three backticks -- this avoids relying on the keyboard shortcut. As a PR author, navigate to a suggestion comment with 3, then Tab to the "Apply suggestion" button; GitHub commits the change automatically with no file editing required. Suggestion blocks render as a mini inline diff: the original line in red/pink background and your proposed replacement in green background; in high-contrast mode these use system diff colors. The "Apply suggestion" button is small and sits below the suggestion diff preview; zoom into the comment area to find it, or Tab from the suggestion text to reach it. When batching multiple suggestions, a floating "Commit suggestions" bar appears at the top of the page; at high zoom scroll up or press Home to find it.

      -

      Jamie: What is the safe way to learn from that example?

      -

      Alex: Keep the learner anchored in Understanding Merge Options (for Maintainers). When a PR is approved and checks pass, a maintainer can merge it. This is the part to say slowly: The merge button section appears at the bottom of the Conversation tab. A good GitHub workflow is like a well-run meeting: everyone knows the topic, the next action, and who has the floor.

      -

      Alex: Treat examples as spoken recipes, not decorations. You may hear something like Merge with default strategy (merge commit); gh pr merge 42; Squash and merge; gh pr merge 42 --squash; Rebase and merge; gh pr merge 42 --rebase; Delete the branch after merging; gh pr merge 42 --squash --delete-branch; Enable auto-merge (merges when checks. Read the command, understand what it changes, then run it only when the repository state matches the lesson.

      -

      Jamie: Let's pause on After a PR is merged. What should a learner take away from it?

      -

      Alex: The reason After a PR is merged matters is that for screen reader users, - deleting the branch after merge: Navigate to the "Add a comment" section (D), then press Shift+B to navigate backwards to the "Delete branch" button and activate it. That gives the learner a simple foothold: this keeps your repository clean by removing the now-merged feature branch.

      -

      Alex: The practical takeaway is this. The PR status badge changes to "Merged" (purple). The source branch can be deleted - a "Delete branch" button appears. Any linked issues with Closes N in the description are automatically closed.

      +

      Alex: Keep the teaching thread moving. The reason 13. Critically Evaluating AI Output matters is that Copilot is fast, fluent, and frequently wrong. That gives the learner a simple foothold: 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.

      +

      Jamie: Let's pause on When to Trust Copilot. What should a learner take away from it?

      +

      Alex: Start with When to Trust Copilot: Copilot is at its best when it is generating code that thousands of developers have written before. The next useful detail is this: You can generally trust suggestions that fall into these categories.

      +

      Alex: The practical takeaway is this. 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.

      +

      Alex: Keep the teaching thread moving. Here is the plain-English version of When to Verify. Some suggestions look correct at first glance but carry hidden risks. Put another way, always read these carefully before accepting. It is like learning a transit route. The names of the stops matter because they tell you whether you are still going the right direction.

      +

      Alex: The practical takeaway is this. 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.

      -

      Alex: Keep the teaching thread moving. Start with Auto-Merge - Merging When You Can't Wait Around: Auto-merge lets you pre-authorize a PR to merge automatically the moment all branch protection requirements are satisfied - required reviews approved, all status checks passing, and the branch up to date.

      -

      Alex: The practical takeaway is this. You've addressed all review comments and are waiting for CI to finish. A maintainer has approved the PR but a required check is still running. You're in a different time zone from the reviewers.

      -

      Jamie: Let's pause on What happens next. What should a learner take away from it?

      -

      Alex: Start with What happens next. There is something to understand, something to try, and something that proves the try worked.

      -

      Alex: The practical takeaway is this. The PR merge box changes to show "Auto-merge enabled - merge will happen automatically". When the last required check passes (or last required review arrives), GitHub merges the PR silently. You receive a notification: "Your PR was automatically merged". If a reviewer requests changes after auto-merge is enabled, auto-merge is automatically cancelled (a new approval is required before it re-enables).

      -

      Jamie: Let's pause on Cancelling Auto-Merge. What should a learner take away from it?

      -

      Alex: This is where Cancelling Auto-Merge becomes real: auto-merge is only available if the repository administrator has enabled it in Settings → General. That matters in practice: Many open source repos have it on; some do not. The workshop is closer to rehearsal than lecture. You hear the move, try the move, and then check what changed.

      -

      Alex: Treat examples as spoken recipes, not decorations. You may hear something like Merge box → Tab → "Disable auto-merge" button → Enter. Read the command, understand what it changes, then run it only when the repository state matches the lesson.

      +

      Jamie: Let's pause on When to Reject. What should a learner take away from it?

      +

      Alex: This is where When to Reject becomes real: delete the suggestion and write the code yourself when you see any of these. That matters in practice: If you are not sure whether a suggestion falls into this category, verify it.

      +

      Alex: The practical takeaway is this. 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.

      +

      Alex: Keep the teaching thread moving. Keep the learner anchored in Common Failure Modes. The table below shows the kinds of mistakes Copilot makes most often. This is the part to say slowly: Recognizing these patterns helps you catch problems before they reach a reviewer.

      +

      Jamie: Let's pause on The Verification Checklist. What should a learner take away from it?

      +

      Alex: The reason The Verification Checklist matters is that before you accept any non-trivial Copilot suggestion, run through these steps. That gives the learner a simple foothold: keep the Problems panel open (Ctrl+Shift+M) while you work with Copilot.

      +

      Alex: First, does it compile or run? -- Accept the suggestion, save the file, and check for errors in the Problems panel (Ctrl+Shift+M). Then, does it do what I asked? -- Read the code and confirm it matches your intent, not just your prompt. After that, 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. Finally, does it match the project's conventions? -- Check naming, formatting, file organization, and error handling against the existing codebase. The rhythm is simple: orient, act, verify, then continue.

      +

      Jamie: Before we leave The Verification Checklist, what is the practical point?

      +

      Alex: First, did I check any URLs or references it generated? -- Open every link, verify every package name, confirm every API endpoint. Then, would this pass an accessibility review? -- Run it through the checks described below. Think of it as a rail line: each stop confirms you are still on the right route before the next one.

      -

      Jamie: Let's pause on Scenario A: "I want to review an assigned PR". What should a learner take away from it?

      -

      Alex: Keep the learner anchored in Scenario A: "I want to review an assigned PR". Example: You are assigned to review a PR titled "Add missing NVDA shortcut to keyboard-shortcuts.md." The PR modifies docs/keyboard-shortcuts.md in the Learning Room repository and references Challenge 2.

      -

      Alex: Keep the teaching thread moving. The reason Scenario B: "I want to respond to review feedback on my PR" matters is that example: Your PR for Challenge 3 (Complete Welcome Guide) received a review comment: "The [TODO] about evaluating issues is good, but the paragraph could mention checking if the issue is already assigned." The validation bot also flagged a link text issue.

      -

      Jamie: Let's pause on Writing PR Descriptions That Get Reviewed. What should a learner take away from it?

      -

      Alex: Start with Writing PR Descriptions That Get Reviewed: See also: Appendix C: Markdown Reference for formatting your PR description with headings, lists, and task lists. The next useful detail is this: A pull request is only as useful as its description.

      +

      Alex: Keep the teaching thread moving. Start with Accessibility-Specific Concerns: Copilot generates HTML and UI code based on what it has seen -- and much of the web is inaccessible. The next useful detail is this: Watch for these problems in any suggestion that touches the user interface. Think of it like entering a new building: first you find the lobby, then the room, then the door you actually need.

      +

      Alex: The practical takeaway is this. 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.

      +

      Jamie: Let's pause on The Right Mental Model. What should a learner take away from it?

      +

      Alex: Here is the plain-English version of The Right Mental Model. Think of Copilot as a fast typist who has read a lot of code. Put another way, it can reproduce patterns it has seen before, and it can combine those patterns in new ways.

      +

      Alex: The practical takeaway is this. 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.

      +

      Alex: Keep the teaching thread moving. Start with Learning Cards: Critically Evaluating AI Output. There is something to understand, something to try, and something that proves the try worked.

      +

      Alex: The practical takeaway is this. 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. 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.

      -

      Jamie: Let's pause on What Reviewers Look For. What should a learner take away from it?

      -

      Alex: Here is the plain-English version of What Reviewers Look For. When a reviewer opens your PR, they are asking four questions before they ever look at the diff. Put another way, if your description answers all four, the reviewer can jump straight into the code with context. It is like learning a transit route. The names of the stops matter because they tell you whether you are still going the right direction.

      -

      Alex: First, why does this change exist? -- What problem does it solve, or what goal does it advance? Then, what is the scope? -- Which files changed, and roughly how big is the change? After that, how was it tested? -- Did you verify that the change works, and how? Finally, what should I pay attention to? -- Are there tricky parts, trade-offs, or areas where you want a second opinion? Treat it like a recipe: do not add the next ingredient until the previous one is actually in the bowl.

      -

      Jamie: Let's pause on The Closes XX Pattern. What should a learner take away from it?

      -

      Alex: This is where The Closes XX Pattern becomes real: GitHub recognizes special keywords in PR descriptions that automatically close linked issues when the PR merges. That matters in practice: You do not need to close issues by hand -- just include the right keyword followed by the issue number.

      -

      Alex: Keep the teaching thread moving. Keep the learner anchored in Before/After Structure. One of the most effective patterns for PR descriptions is showing the state before your change and the state after. This is the part to say slowly: This gives the reviewer an instant mental model of what changed without reading the diff line by line.

      +

      Jamie: Let's pause on Copilot Not Suggesting Anything. What should a learner take away from it?

      +

      Alex: Keep the learner anchored in Copilot Not Suggesting Anything. Issue: No suggestions appear as you type.

      +

      Jamie: Let's pause on Solutions. What should a learner take away from it?

      +

      Alex: Start with Solutions. There is something to understand, something to try, and something that proves the try worked.

      +

      Alex: First, check Copilot is active: status bar icon should not be grayed out. Then, click the Copilot icon → verify "Completions enabled". After that, check subscription status: Ctrl+Shift+P → "Copilot: Check Status". Finally, restart VS Code. The rhythm is simple: orient, act, verify, then continue.

      +

      Jamie: Before we leave Solutions, what is the practical point?

      +

      Alex: First, sign out and sign back in: Ctrl+Shift+P → "Copilot: Sign Out". Think of it as a rail line: each stop confirms you are still on the right route before the next one.

      +

      Jamie: Let's pause on Suggestions Are Too Frequent/Distracting. What should a learner take away from it?

      +

      Alex: Start with Suggestions Are Too Frequent/Distracting: Issue: Constant interruptions from suggestions.

      -

      Jamie: Let's pause on A PR Description Template. What should a learner take away from it?

      -

      Alex: The reason A PR Description Template matters is that here is a template you can copy into your PR descriptions. That gives the learner a simple foothold: not every section applies to every PR, but filling in even a few sentences per section makes a meaningful difference.

      -

      Alex: Keep the teaching thread moving. Start with Common Description Mistakes: Even experienced contributors make these mistakes. The next useful detail is this: Knowing what to avoid is half the battle. Think of it like entering a new building: first you find the lobby, then the room, then the door you actually need.

      -

      Jamie: Let's pause on Good vs. Bad: Side by Side. What should a learner take away from it?

      -

      Alex: Here is the plain-English version of Good vs. Bad: Side by Side. No context, no linked issue, no explanation of what file or what was wrong with it. Put another way, a reviewer seeing this has to open the diff, figure out which file changed, read every line, and guess at the intent.

      +

      Jamie: What is the teaching move inside Solutions?

      +

      Alex: First, use word-by-word acceptance: Ctrl+Right Arrow. Then, reduce screen reader verbosity (see Section 3). After that, use Accessible View (Alt+F2) to review suggestions without live announcements. Finally, disable inline suggestions temporarily: Copilot icon → "Disable Completions". Treat it like a recipe: do not add the next ingredient until the previous one is actually in the bowl.

      +

      Jamie: Let's pause on Chat Responses Not Announced. What should a learner take away from it?

      +

      Alex: This is where Chat Responses Not Announced becomes real: issue: Screen reader silent when Copilot responds.

      +

      Jamie: If someone only remembers one thing from Solutions, what should it be?

      +

      Alex: First, wait for response to complete, then press Alt+F2 for Accessible View. Then, check ARIA live region settings in your screen reader. After that, navigate manually to the response area with Tab or Arrow keys. Finally, use Quick Chat (Ctrl+Shift+Alt+I) instead of panel chat. It is like walking a hallway with named doors: read the sign, enter the right room, then confirm where you landed.

      -

      Alex: Keep the teaching thread moving. Start with Learning Cards: Writing PR Descriptions That Get Reviewed. There is something to understand, something to try, and something that proves the try worked.

      -

      Alex: The practical takeaway is this. Use Markdown headings ( ) in your description (Summary, Changes, Related Issues, Testing) so reviewers can press H to jump between sections. Type Closes followed by the issue number to auto-close the linked issue on merge; GitHub autocompletes when you type. Press Ctrl+Shift+P in the description text area to toggle between Write and Preview modes; Preview renders your Markdown so you can check structure before submitting. Use the Preview tab to verify your Markdown renders correctly; headings, bullet lists, and code blocks are easier to proofread in rendered form. Keep bullet points short (one line each) so the description is scannable at high zoom without excessive horizontal scrolling. When including screenshots, add alt text in the Markdown image syntax: so every reader gets the same information.

      -

      Jamie: Let's pause on Try It: Read a Real Pull Request. What should a learner take away from it?

      -

      Alex: Keep the learner anchored in Try It: Read a Real Pull Request. Time: 3 minutes What you need: Browser, signed in to GitHub. This is the part to say slowly: Go to the Learning Room repository's Pull Requests tab and find any open or recently closed PR.

      -

      Alex: First, navigate to Pull Requests (G then P in Focus Mode). Then, open the first PR in the list (press Enter on its title). After that, read the description - press 2 to jump to the first section heading, then arrow down to read. Look for: which file was changed (docs/welcome.md, docs/keyboard-shortcuts.md, or docs/setup-guide.md)? Which challenge was this PR solving? Does the description. Finally, check the conversation - press 3 to jump between comments. Read what the validation bot reported - did the bot find any accessibility issues like broken headings or non-descriptive links? How did the author respond? It is like walking a hallway with named doors: read the sign, enter the right room, then confirm where you landed.

      -

      Jamie: Before we leave Try It: Read a Real Pull Request, what is the practical point?

      -

      Alex: First, look at the diff - press D to the "Pull request tabs" landmark, then navigate to "Files changed" and press Enter. Press H to scan the changed file headings. If the PR touched docs/welcome.md, you should see + lines where the [TODO] sections were filled in. If. The rhythm is simple: orient, act, verify, then continue.

      +

      Jamie: Let's pause on "Copilot Subscription Required". What should a learner take away from it?

      +

      Alex: The reason "Copilot Subscription Required" matters is that issue: Extension installed but asks for subscription.

      +

      Jamie: Let's pause on Solutions. What should a learner take away from it?

      +

      Alex: First, sign in to GitHub: Copilot icon → "Sign in". Then, verify GitHub account has Copilot access (free tier or paid). After that, check github.com/settings/copilot for subscription status. Finally, free tier users: ensure you haven't exceeded monthly limits. Think of it as a rail line: each stop confirms you are still on the right route before the next one.

      +

      Jamie: Let's pause on Try It: Your First Copilot Conversation. What should a learner take away from it?

      +

      Alex: Here is the plain-English version of Try It: Your First Copilot Conversation. Time: 3 minutes What you need: VS Code with Copilot Chat extension installed. Put another way, you just had a conversation with an AI about your codebase.

      +

      Alex: First, open Copilot Chat - Press Ctrl+Shift+I (Mac: Cmd+Shift+I). Your screen reader announces the chat panel. Then, ask a question - Type: What does the CONTRIBUTING.md file in this repository say about how to submit a pull request? Press Enter. After that, 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. Finally, try a follow-up - Type: Summarize that in 3 bullet points and press Enter. Copilot remembers the context from your first question. Treat it like a recipe: do not add the next ingredient until the previous one is actually in the bowl.

      -

      Jamie: What is the final checkpoint?

      -

      Alex: You should be able to point to the evidence, explain the action, and describe what you would do next if this were a real open source project. If you can teach the move back, you have learned it.

      -

      Jamie: And if they get stuck?

      -

      Alex: Read the latest message, not the loudest worry. Check the issue, the branch, the pull request, the status check, or the bot comment. Then ask for help with those facts in hand. That is how professionals collaborate.

      +

      Jamie: What should people carry with them after this?

      +

      Alex: Carry the map. Know what page or tool you are in, know which action you are taking, and know what confirmation should follow. If the confirmation is missing, pause. That pause is not wasted time; it is professional judgment.

      +

      Jamie: That is a better way to say it than just follow the steps.

      +

      Alex: Right. Steps matter, but understanding wins. That is episode 14. Next in the series is episode 15, where we keep building the same contributor muscles.

      -

      Challenge 06: Open Your First Pull Request

      -

      Opening a pull request, comparing branches, and using closing keywords.

      +

      42. Episode 40: GitHub Copilot - Complete Reference

      +

      All Copilot features, chat participants, slash commands, and MCP servers.

      +

      Based on: Appendix K: GitHub Copilot - Complete Reference

      +

      Audio and transcript are being regenerated for this episode.

      -Read Transcript - Challenge 06: Open Your First Pull Request +Read Transcript - Episode 40: GitHub Copilot - Complete Reference

      Transcript

      -

      Alex: Welcome back to Challenge Coach. Today we are taking on Open Your First Pull Request, one careful step at a time.

      -

      Jamie: And I am Jamie. I am listening for the confusing parts: where to start, what to submit, and how to tell whether it worked.

      +

      Alex: Welcome to Git Going with GitHub, episode 40: GitHub Copilot - Complete Reference. I am Alex. Today we are going to make GitHub Copilot - Complete Reference something you can explain, practice, and recover from when the interface surprises you.

      +

      Jamie: And I am Jamie. I will be the voice of the learner who is willing to ask, what is this for, where am I, and how do I know I did it right?

      -

      Alex: In this challenge, the learner is practicing opening a pull request, comparing branches, and using closing keywords. The point is not to rush. The point is to leave a clear trace of good work.

      -

      Jamie: So we should name what success sounds like before the learner starts clicking or typing.

      -

      Alex: Yes. When the checkpoint is clear, the learner can tell the difference between being stuck and simply not being finished yet.

      +

      Alex: The big idea today: All Copilot features, chat participants, slash commands, and MCP servers. We will name the concept, explain why it matters, practice the move, and point out the checks that tell you the work is real.

      +

      Jamie: So the episode should work even if someone has not read the chapter yet.

      +

      Alex: Exactly. The transcript has to stand on its own. It can point toward practice, but it should teach the concept right here in the conversation.

      -

      Jamie: What makes this practice feel low-stakes but still real?

      -

      Alex: Start with Challenge 6: Open Your First Pull Request: What you will do: Open a pull request from your learn/YOUR-USERNAME branch to main, connecting it to the issue you filed in Challenge 2.

      -

      Alex: A solid pull request habit is to separate three questions: what changed, why it changed, and what still needs review. That keeps the conversation useful instead of noisy.

      -

      Jamie: How would you walk the room through that step by step?

      -

      Alex: Start with Instructions. There is something to understand, something to try, and something that proves the try worked.

      -

      Alex: First, go to the Pull requests tab. Then, select New pull request. After that, set base to main and compare to learn/YOUR-USERNAME. Finally, write a descriptive PR title. Treat it like a recipe: do not add the next ingredient until the previous one is actually in the bowl.

      -

      Jamie: What does the learner do first, second, and then after that?

      -

      Alex: First, in the PR description, include Closes XX (replace XX with your Challenge 2 issue number). This automatically links and closes the issue when the PR is merged. Then, submit the pull request. It is a checklist, but a meaningful one: every item creates evidence that the next step is safe.

      +

      Jamie: Okay, set the room for us. What are we walking into?

      +

      Alex: Start with Keyboard Shortcuts, Chat, Screen Reader Workflow, Plugin Ecosystem, and GitHub Agentic Workflows: Quick-reference card for GitHub Copilot in VS Code and the broader agentic ecosystem - plugins, MCP servers, and cloud-based automation. The next useful detail is this: For the Copilot lesson, see Chapter 16: GitHub Copilot.

      +

      Alex: A solid navigation habit is to prove where you are before activating controls. Headings, landmarks, and the address bar are not trivia; they are your map.

      +

      Alex: The next layer is this. Here is the plain-English version of Inline Suggestions (Ghost Text). Word-by-word acceptance (Ctrl+Right Arrow) is recommended for screen reader users - it lets you review the suggestion incrementally before committing to it. Put another way, accessible View workflow for screen reader users: Press Alt+F2 when a suggestion appears to hear the full text without streaming noise, then press Ctrl+/ to insert it directly from the Accessible View without closing the panel first. It is like learning a transit route. The names of the stops matter because they tell you whether you are still going the right direction.

      Jamie: What is the one idea that makes the next few steps less mysterious?

      -

      Alex: This is where PR description template becomes real: use this structure for your PR description.

      -
      -

      Alex: Now bring the learner back to the room. Keep the learner anchored in The magic of Closes XX. When you write Closes 12 in a PR description, GitHub automatically. This is the part to say slowly: This is one of GitHub's most powerful workflow features.

      -

      Alex: For a learner, the useful signals are these. Links the PR to issue 12. Closes issue 12 when the PR is merged.

      -

      Jamie: What would you say to someone who is already bracing for this to be too much?

      -

      Alex: The reason Peer simulation check matters is that find the Peer Simulation: Improve contribution guidance PR and leave an encouraging comment. That gives the learner a simple foothold: if you have access to a real buddy's PR, you may comment there too.

      -

      Alex: The useful habit is simple: orient first, act second, verify third. That pause before acting is part of the work.

      -

      Alex: That matters because of the next idea. Start with Example PR. There is something to understand, something to try, and something that proves the try worked.

      +

      Alex: This is where Accessibility becomes real: use Accessible View (Alt+F2) every time Copilot responds. That matters in practice: It provides the complete response in a readable pane - no streaming, no live region noise, proper heading structure.

      -

      Jamie: Okay, set the room for us. What are we walking into?

      -

      Alex: Start with Title. There is something to understand, something to try, and something that proves the try worked.

      -

      Alex: Here is what that changes in practice. Describes the change clearly: someone reading just the title understands what happened. Short enough to scan in a list.

      -

      Alex: This is where the talk moves from concept to action. Start with Body. There is something to understand, something to try, and something that proves the try worked.

      -

      Alex: The room should hear these as checkpoints. What: Summarizes the change. Why: Explains the motivation. Closes N: Links to the issue this PR resolves -- GitHub automatically closes the issue when the PR merges.

      +

      Alex: Now bring the learner back to the room. Keep the learner anchored in 2. Chat Participants. Type these in the Copilot Chat input to give Copilot context from a specific source.

      +

      Jamie: What should they understand before typing anything?

      +

      Alex: Start with Example prompts. There is something to understand, something to try, and something that proves the try worked.

      +

      Alex: Treat examples as spoken recipes, not decorations. You may hear something like @workspace find all places where heading hierarchy is documented; @github search community-access/accessibility-agents for issues labeled accessibility; @terminal what did the last command output mean? Read the command, understand what it changes, then run it only when the repository state matches the lesson.

      +

      Alex: A solid pull request habit is to separate three questions: what changed, why it changed, and what still needs review. That keeps the conversation useful instead of noisy.

      +

      Alex: That matters because of the next idea. Start with 3. Chat Slash Commands: Type / in Copilot Chat to see the available built-in commands. Think of it like entering a new building: first you find the lobby, then the room, then the door you actually need.

      +

      Alex: The useful habit is simple: orient first, act second, verify third. That pause before acting is part of the work.

      +
      +

      Jamie: There are a lot of tools in play. How do we keep that from feeling like a contest?

      +

      Alex: Here is the plain-English version of Workspace management slash commands. These are Copilot's built-in chat slash commands. Put another way, accessibility Agents adds 28 additional workspace-level slash commands from.github/prompts/ - see Appendix L for the full list.

      +

      Alex: This is where the talk moves from concept to action. This is where 4. Chat Modes becomes real: select the current mode from the dropdown at the bottom of the Chat input area. That matters in practice: The mode selector is in the Chat panel toolbar at the bottom.

      +

      Jamie: What stays the same when the tool changes?

      +

      Alex: Start with Learning Cards: Chat Participants, Commands, and Modes. There is something to understand, something to try, and something that proves the try worked.

      +

      Alex: These are the details that keep the idea from floating away. Type @ in Chat to scope context (@workspace, @terminal, @github) -- the autocomplete list is keyboard-navigable with arrow keys. Type / for slash commands (/explain, /fix, /tests) -- each is announced with its description as you arrow through. The mode selector is at the bottom of the Chat panel toolbar; Tab to it, then Space or Enter to open the dropdown. Chat responses appear in the panel with syntax highlighting -- increase the Chat panel font size via editor.fontSize in settings. The @ and / trigger characters are small but the autocomplete popup that follows is large and themed to your current color scheme. Use Ask mode for reading explanations, Agent mode for controlled multi-file changes and autonomous tasks (Edit mode is being deprecated into Agent mode as of VS Code 1.118).

      +
      +

      Alex: Before the learner moves on. The reason 5. Custom Instructions - All Levels matters is that GitHub Copilot supports multiple ways to provide custom instructions. That gives the learner a simple foothold: they differ by scope, priority, trigger mechanism, and which tools recognize them. The interface gets friendlier when it stops being a wall of controls and starts being a set of named places.

      +

      Jamie: What would you say to someone who is already bracing for this to be too much?

      +

      Alex: Start with 4A. Always-On Instructions -.github/copilot-instructions.md: What it is: The primary VS Code Copilot instruction file. The next useful detail is this: Content is automatically included in every chat request and inline suggestion context - you never need to invoke it.

      +

      Jamie: How would you walk the room through that step by step?

      +

      Alex: Start with Auto-generate with /init. There is something to understand, something to try, and something that proves the try worked.

      +

      Alex: First, open Copilot Chat. Then, type /init. After that, VS Code analyzes your workspace and generates a tailored copilot-instructions.md. Finally, review and edit the result before committing. Treat it like a recipe: do not add the next ingredient until the previous one is actually in the bowl.

      +
      +

      Jamie: How should a learner choose a tool without feeling judged by the choice?

      +

      Alex: This is where 4B. Always-On Instructions - AGENTS.md (Multi-Tool / Monorepo) becomes real: what it is: An open standard instruction file recognized by multiple AI tools - GitHub Copilot, Claude Code, Gemini CLI, and others. That matters in practice: Use this instead of copilot-instructions.md when you want one instruction file that works across all AI coding assistants.

      +

      Alex: That connects to another useful point. Keep the learner anchored in 4C. Always-On Instructions - CLAUDE.md (Cross-Tool Compatibility). What it is: Instructions file originally from Claude Code that VS Code Copilot also recognizes. This is the part to say slowly: When to use: Mixed AI tool environments where Claude Code and VS Code Copilot are both used. A good GitHub workflow is like a well-run meeting: everyone knows the topic, the next action, and who has the floor.

      Jamie: Where do you want a learner to place their attention here?

      -

      Alex: Keep the learner anchored in Linked issue. The Closes 3 line creates a two-way link. This is the part to say slowly: The issue shows "referenced by PR 5" and the PR shows "Closes 3." When the PR merges, issue 3 closes automatically.

      -

      Alex: A solid issue habit is to read the title, the body, and the timeline before acting. You are listening for the requested action, the missing evidence, and the person who needs a response.

      +

      Alex: The reason Supported locations matters is that enable/disable: Set chat.useClaudeMdFile: true (default: on). That gives the learner a simple foothold: claude Rules format (for.claude/rules/ and /.claude/rules/).

      -

      Alex: Before the learner moves on. The reason Passing checks matters is that if the repository has automated checks (the PR validation bot), a green checkmark appears. That gives the learner a simple foothold: if checks fail, read the bot's feedback comment for specific guidance. The interface gets friendlier when it stops being a wall of controls and starts being a set of named places.

      +

      Alex: Here is the practical turn. Start with 4D. Conditional / Scoped Instructions -.instructions.md: What it is: Instructions that apply only when specific file types or folders are involved in the chat. The next useful detail is this: More targeted than always-on instructions.

      Jamie: Give me the version that sounds like an instructor, not a manual.

      -

      Alex: Start with Alternate linking syntax. There is something to understand, something to try, and something that proves the try worked.

      -

      Alex: A few details make that real. Closes 3. Resolves 3.

      -

      Alex: Hold that next to this. Here is the plain-English version of What matters. The learning objective is connecting a change (PR) to a reason (issue) through GitHub's linking system. Put another way, if your PR has a clear title, a description, and references an issue number, you completed this challenge.

      +

      Alex: Start with Create an instructions file. There is something to understand, something to try, and something that proves the try worked.

      +

      Alex: Here is what that changes in practice. Ctrl+Shift+P → "Chat: New Instructions File" → choose scope (Workspace or User). Or create the file manually in.github/instructions/.

      +

      Alex: Keep the thread going. This is where 4E. Organization-Level Instructions (GitHub Enterprise and Teams) becomes real: what it is: Organization administrators define custom instructions that apply to all repositories in the organization. That matters in practice: Every team member automatically gets these instructions added to their Copilot context. The workshop is closer to rehearsal than lecture. You hear the move, try the move, and then check what changed.

      Jamie: If I am listening before the workshop starts, what should settle in my mind first?

      -

      Alex: This is where Creating, Reviewing, and Merging Pull Requests with a Screen Reader becomes real: see also: Chapter 15: Code Review covers the full review workflow including multi-file diffs and suggested changes. That matters in practice: Pull requests are where your work becomes a contribution.

      -

      Alex: That connects to another useful point. Keep the learner anchored in Workshop Recommendation (Chapter 6). Chapter 6 is the first PR-validated chapter where students convert issue work into merge-ready contributions. A good GitHub workflow is like a well-run meeting: everyone knows the topic, the next action, and who has the floor.

      -

      Alex: The parts worth keeping in working memory are these. There are 3. Each challenge should take under 10 minutes each. The evidence is PR metadata, bot checks, and merged issue linkage. The pattern is small change - linked PR - green checks.

      -

      Jamie: What is the ordered workflow?

      -

      Alex: The reason Chapter 6 Challenge Set matters is that this is the first chapter where you edit files and create branches. That gives the learner a simple foothold: 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.

      -

      Alex: First, create one small branch change - edit a practice file on a new branch. Then, open a linked PR - use the PR template and include Closes XX. After that, pass required checks - respond to bot feedback until all required checks pass. The rhythm is simple: orient, act, verify, then continue.

      -
      -

      Jamie: Give me the sequence, because order matters here.

      -

      Alex: Start with Challenge 6.1 Step-by-Step: Create One Small Branch Change: Edit one of the practice files and save your change on a new branch. The next useful detail is this: your Learning Room repository on GitHub.com, using the web editor.

      -

      Alex: On the ground, that means a few things. 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. 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.

      -

      Alex: First, 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). Then, open the file and activate the pencil icon (Edit this file) button. After that, the file opens in the web editor. Make your change. For. Finally, keep your change small and focused. Edit only what the issue asks for. Think of it as a rail line: each stop confirms you are still on the right route before the next one.

      -

      Jamie: Turn that into a path someone can follow.

      -

      Alex: First, after editing, activate the Commit changes button (green button above the editor). Then, a dialog appears. In the Branch name field, type: fix/yourname-issueXX (replace yourname with your GitHub username, and XX with the issue number). After that, select Create a new branch for this commit and start a pull request. Finally, activate Propose changes. Treat it like a recipe: do not add the next ingredient until the previous one is actually in the bowl.

      -

      Alex: A solid Git habit is to know which branch you are on, what changed, and what confirmation you expect before you run the next command.

      -

      Jamie: Let's pause on Challenge 6.2 Step-by-Step: Open a Linked PR. What should a learner take away from it?

      -

      Alex: Here is the plain-English version of Challenge 6.2 Step-by-Step: Open a Linked PR. AI agents do not just deploy code directly; they submit pull requests. Put another way, learning to edit a file, format it in Markdown, and review a PR today prepares you to audit and approve AI-generated changes tomorrow.

      -

      Alex: These are the details that keep the idea from floating away. "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". A summary of what you changed and why (at least 50 characters).

      -

      Alex: First, in the Title field, write a short description of your change. Then, in the Body field, use the PR template if one is provided. Make sure to. After that, verify the base branch is main and the compare branch is your fix/yourname-issueXX branch. Finally, activate the Create pull request button. Treat it like a recipe: do not add the next ingredient until the previous one is actually in the bowl.

      -

      Jamie: Let's pause on Challenge 6.3 Step-by-Step: Pass Required Checks. What should a learner take away from it?

      -

      Alex: This is where Challenge 6.3 Step-by-Step: Pass Required Checks becomes real: read bot feedback, fix any issues it finds, and get all required checks to pass. That matters in practice: the Conversation tab of your open pull request. The workshop is closer to rehearsal than lecture. You hear the move, try the move, and then check what changed.

      -

      Alex: That becomes easier when you listen for these cues. 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.

      -

      Alex: First, wait approximately 30 seconds after opening the PR. The bot posts a validation comment. Then, read the bot comment carefully. It checks. After that, if the bot reports failures. Finally, repeat step 3 until all required checks show a green checkmark. It is a checklist, but a meaningful one: every item creates evidence that the next step is safe.

      -

      Jamie: Before we leave Challenge 6.3 Step-by-Step: Pass Required Checks, what is the practical point?

      -

      Alex: First, when all checks pass, request a review from a peer or the facilitator. It is like walking a hallway with named doors: read the sign, enter the right room, then confirm where you landed.

      -
      -

      Jamie: Let's pause on Expected Outcomes. What should a learner take away from it?

      -

      Alex: Start with Expected Outcomes. There is something to understand, something to try, and something that proves the try worked.

      -

      Alex: The practical anchors are these. Student opens a focused PR that maps to one issue. Student uses Closes XX correctly. Student can interpret bot feedback and improve the PR.

      -

      Jamie: Let's pause on If You Get Stuck. What should a learner take away from it?

      -

      Alex: Start with If You Get Stuck. There is something to understand, something to try, and something that proves the try worked.

      -

      Alex: First, confirm your PR includes Closes XX in title or body. Then, check that changed files are only in learning-room/. After that, open the bot validation comment and resolve one required check at a time. Finally, if checks still fail, ask for peer or facilitator review with the exact error message. The rhythm is simple: orient, act, verify, then continue.

      -

      Jamie: Before we leave If You Get Stuck, what is the practical point?

      -

      Alex: First, finished but not sure you did it right? Compare your work against the Challenge 6 reference solution. Think of it as a rail line: each stop confirms you are still on the right route before the next one.

      -

      Jamie: Let's pause on Learning Moment. What should a learner take away from it?

      -

      Alex: Start with Learning Moment: A great PR is small, linked to an issue, and easy to review. The next useful detail is this: Faster feedback builds confidence and momentum.

      +

      Alex: Keep the learner anchored in Requirements. Use for: Organization-wide coding standards, security policies, legal disclaimers (open source license obligations), toolchain conventions.

      +

      Alex: That becomes easier when you listen for these cues. GitHub Enterprise or Teams plan with Copilot enabled. Admin configures instructions in organization settings on GitHub.com. Each user must enable discovery in VS Code.

      +

      Alex: Another way to ground it. The reason 4F. Settings-Based Instructions (Deprecated - Use Files Instead) matters is that these settings-based instructions are deprecated and may be removed in a future VS Code release. That gives the learner a simple foothold: for new work, use copilot-instructions.md or.instructions.md files.

      +

      Jamie: How should someone choose between those options?

      +

      Alex: Start with 4G. Comparison - When to Use Each Approach. There is something to understand, something to try, and something that proves the try worked.

      +

      Alex: Use the comparison to make a decision, not to recite a table. The main contrasts are: Approach means Always-on? means Multi-tool? means Best. copilot-instructions.md means Workspace means VS Code only means Primary project instructions. AGENTS.md means Workspace + monorepo means All AI tools means Multi-tool teams or large monorepos.

      -

      Alex: This is the part worth saying out loud. Start with Why this feels achievable. There is something to understand, something to try, and something that proves the try worked.

      -

      Alex: That shows up in the workshop in a few specific ways. Scope is intentionally small. Feedback is immediate and specific. Success is visible (green checks + closed issue).

      -

      Jamie: Let's pause on About Learning Cards in This Chapter. What should a learner take away from it?

      -

      Alex: This is where About Learning Cards in This Chapter becomes real: this chapter provides learning cards: expandable blocks that offer perspective-specific guidance for different ways of working. That matters in practice: Not every card appears at every step.

      +

      Alex: This is the part worth saying out loud. Start with Learning Cards: Custom Instructions. There is something to understand, something to try, and something that proves the try worked.

      +

      Alex: The practical anchors are these. The three-level scope hierarchy (Organization, Workspace, User) means instructions can come from multiple places -- use Chat Diagnostics (gear icon in Chat header) to list every loaded instruction file and its source.github/copilot-instructions.md is always-on and requires no frontmatter -- just write plain Markdown; screen readers read the source file like any other Markdown document.instructions.md files use YAML frontmatter with applyTo globs -- the frontmatter is the first few lines between --- delimiters; arrow through carefully to verify syntax. The Diagnostics panel (Chat gear, then Diagnostics) lists loaded files in a scrollable pane -- increase font size in VS Code settings if the file paths are hard to read. YAML frontmatter is indentation-sensitive -- enable VS Code's indentation guides (editor.guides.indentation) and use a high-contrast theme so the guide lines are visible. The /init command auto-generates copilot-instructions.md from your workspace -- review the generated file in your editor at your preferred zoom before committing.

      +

      Jamie: Let's pause on 6. Accessible View Workflow. What should a learner take away from it?

      +

      Alex: This is where 6. Accessible View Workflow becomes real: Copilot Chat responses stream in token by token, which can fragment screen reader announcements. That matters in practice: Accessible View (Alt+F2) gives you a complete, static, properly structured version of the response.

      Jamie: What should happen before anyone copies and runs it?

      -

      Alex: Keep the learner anchored in Local Git Alternative: The Full Branch-Edit-PR Workflow. If you cloned the learning-room in Block 0 and prefer working locally. This is the part to say slowly: The web editor workflow (pencil button, "Propose changes") is the primary path taught in this chapter.

      -

      Alex: Treat examples as spoken recipes, not decorations. You may hear something like cd /Documents/learning-room; git checkout main; git pull origin main; git checkout -b fix/welcome-todos. code docs/welcome.md. Read the command, understand what it changes, then run it only when the repository state matches the lesson.

      +

      Alex: Keep the learner anchored in Recommended Workflow - Every Copilot Interaction. VS Code December 2025: The Accessible View now streams dynamically. This is the part to say slowly: You can open it immediately after sending a prompt and follow the response as it arrives - no need to wait for the response to finish before pressing Alt+F2.

      +

      Alex: Treat examples as spoken recipes, not decorations. You may hear something like Open Copilot Chat: Ctrl+Shift+I; 2. Type your prompt; 3. Press Ctrl+Enter to send; 4. Press Alt+F2 to open Accessible View (open immediately - no need to wait); 5. Follow as the response streams in the Accessible View in real-time; 6. Read or re-read any part. Read the command, understand what it changes, then run it only when the repository state matches the lesson.

      -

      Jamie: Let's pause on What Is a Pull Request? What should a learner take away from it?

      -

      Alex: The reason What Is a Pull Request? matters is that a pull request (PR) is a proposal to merge changes from one branch into another. That gives the learner a simple foothold.you open a PR to request that those changes be merged into the target branch (usually main).

      -

      Alex: The practical takeaway is this. Edited a file directly on GitHub (web editor). Made changes in your fork. Made changes on a feature branch. What changed - a diff of every file.

      -

      Jamie: Let's pause on Navigating to Pull Requests. What should a learner take away from it?

      -

      Alex: Start with Navigating to Pull Requests: Global pull requests dashboard: GitHub now shows a global pull requests page at github.com/pulls listing all open PRs across every repository you have access to. The next useful detail is this: 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). Think of it like entering a new building: first you find the lobby, then the room, then the door you actually need.

      -

      Alex: The practical takeaway is this. 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.

      -

      Alex: First, d → "Repository navigation" landmark. Then, k to navigate tabs → "Pull requests, [N] open". After that, enter to open. Finally, vO+U → Landmarks → navigate to "Repository navigation". Think of it as a rail line: each stop confirms you are still on the right route before the next one.

      -

      Jamie: Before we leave Navigating to Pull Requests, what is the practical point?

      -

      Alex: First, quick Nav K or VO+Right to navigate tabs → "Pull requests". Then, vO+Space to open. Treat it like a recipe: do not add the next ingredient until the previous one is actually in the bowl.

      +

      Jamie: Let's pause on NVDA / JAWS. What should a learner take away from it?

      +

      Alex: Start with NVDA / JAWS. There is something to understand, something to try, and something that proves the try worked.

      +

      Alex: The parts worth keeping in working memory are these. Up/Down Arrow - read line by line. Ctrl+Home - jump to start. H - navigate by headings (if response has sections). Escape - close Accessible View, return to Chat.

      +

      Alex: Hold that next to this. Start with VoiceOver. There is something to understand, something to try, and something that proves the try worked.

      +

      Alex: On the ground, that means a few things. VO+Shift+Down - interact with the Accessible View content. Down Arrow - read line by line. VO+Escape - stop interacting. Escape - close Accessible View.

      Jamie: What is the safe way to learn from that example?

      -

      Alex: Here is the plain-English version of From a PR notification. If you received a notification about a PR, follow the notification link directly to the PR page. Put another way, list and view pull requests from your terminal.

      -

      Alex: Treat examples as spoken recipes, not decorations. You may hear something like 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. Read the command, understand what it changes, then run it only when the repository state matches the lesson.

      -
      -

      Alex: Keep the thread going. Start with Learning Cards: Navigating to Pull Requests. There is something to understand, something to try, and something that proves the try worked.

      -

      Alex: The practical takeaway is this. 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. 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.

      -

      Jamie: Let's pause on The Pull Request List Page. What should a learner take away from it?

      -

      Alex: Keep the learner anchored in The Pull Request List Page. The PR list works identically to the Issues list. This is the part to say slowly: for screen reader users, - PR list semantics: The PR list does not have individual ARIA item containers with per-item semantics.

      -

      Alex: The practical takeaway is this. 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.

      -

      Jamie: Let's pause on Navigating the PR Tab Bar. What should a learner take away from it?

      -

      Alex: The reason Navigating the PR Tab Bar matters is that the Conversation, Commits, and Files changed tabs are in a "Pull request navigation tabs" landmark. That gives the learner a simple foothold: the three tabs - Conversation, Commits, and Files changed - appear just below the PR title. The interface gets friendlier when it stops being a wall of controls and starts being a set of named places.

      -

      Alex: The practical takeaway is this. 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.

      -

      Alex: First, press D → navigate to "Pull request navigation tabs". Then, press ← or → arrow keys to move between tab options. After that, press Enter to activate a tab. Finally, vO+U → Landmarks → "Pull request navigation tabs". The rhythm is simple: orient, act, verify, then continue.

      -

      Jamie: Before we leave Navigating the PR Tab Bar, what is the practical point?

      -

      Alex: First, vO+Right to move between tabs. Then, vO+Space to activate. Think of it as a rail line: each stop confirms you are still on the right route before the next one.

      +

      Alex: Here is the plain-English version of Accessible View for Inline Suggestions. When a multi-line ghost text suggestion appears in the editor. Put another way, this is especially important for multi-line suggestions where ghost text is hard to review incrementally.

      +

      Alex: Treat examples as spoken recipes, not decorations. You may hear something like Do not accept immediately; 2. Press Alt+F2; 3. Accessible View shows: "Suggestion: [full text]"; 4. Read the complete suggestion at your own pace; 5. Press Escape to close; 6. Press Tab to accept, or Escape to reject. Read the command, understand what it changes, then run it only when the repository state matches the lesson.

      -

      Jamie: Let's pause on PR Description. What should a learner take away from it?

      -

      Alex: Start with PR Description. There is something to understand, something to try, and something that proves the try worked.

      -

      Alex: First, 2 → navigate to "Description" h2 heading. Then, ↓ to read the description. After that, markdown renders as semantic HTML - headings, lists, code blocks are fully accessible. Think of it as a rail line: each stop confirms you are still on the right route before the next one.

      -

      Jamie: Let's pause on Status Checks Section. What should a learner take away from it?

      -

      Alex: Here is the plain-English version of Status Checks Section. Below the description, the status checks summary shows whether automated tests passed. Put another way, status checks appear as a coloured banner below the PR description - green tick for passed, red X for failed, yellow spinner for running.

      -

      Alex: The practical takeaway is this. "All checks have passed" / "Some checks failed" / "Checks pending". A "Show all checks" button or link.

      -

      Alex: First, press H or 2 to find the "Checks" or "Status checks" heading. Then, press K to navigate links for individual check names. After that, press Enter on a check to see its details. Finally, quick Nav H or VO+Cmd+H to jump to the "Checks" or "Status checks" heading. Treat it like a recipe: do not add the next ingredient until the previous one is actually in the bowl.

      -

      Jamie: Before we leave Status Checks Section, what is the practical point?

      -

      Alex: First, quick Nav K to navigate check name links. Then, vO+Space on a check to see its details. It is a checklist, but a meaningful one: every item creates evidence that the next step is safe.

      -

      Jamie: Let's pause on Review Comments. What should a learner take away from it?

      -

      Alex: This is where Review Comments becomes real: each review comment thread is an h3.

      -

      Alex: The practical takeaway is this. 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.

      +

      Alex: Keep the teaching thread moving. Start with Accessible View for Code Blocks. There is something to understand, something to try, and something that proves the try worked.

      +

      Alex: The room should hear these as checkpoints. Code blocks appear inside elements in Accessible View. Screen readers announce "code block" or "pre-formatted text" at the start. Each line is on its own line (not run together). Indentation is preserved.

      +

      Jamie: Let's pause on Learning Cards: Accessible View Workflow. What should a learner take away from it?

      +

      Alex: Start with Learning Cards: Accessible View Workflow. There is something to understand, something to try, and something that proves the try worked.

      +

      Alex: A few details make that real. Press Alt+F2 immediately after sending a prompt -- Accessible View now streams dynamically so you can follow along in real time. Navigate Chat responses with Up/Down Arrow; headings, code blocks, and lists are structurally intact in the view. For inline suggestions, press Alt+F2 to read the full ghost text, then Ctrl+/ to insert it directly from the Accessible View. Accessible View renders Chat responses as a static, scrollable pane -- easier to read at high zoom than the streaming Chat panel. Code blocks in Accessible View preserve indentation and syntax -- pair with a high-contrast theme for maximum readability. Ctrl+Home jumps to the start of the response; Ctrl+End to the end -- useful for long multi-section outputs.

      +

      Alex: Keep the teaching thread moving. The reason 7. Configuration Scope Reference matters is that every Copilot customization file lives at one of three scopes. That gives the learner a simple foothold: VS Code combines all matching files from all scopes - it is additive, not winner-takes-all. The interface gets friendlier when it stops being a wall of controls and starts being a set of named places.

      -

      Jamie: Let's pause on Resolving conversations. What should a learner take away from it?

      -

      Alex: Keep the learner anchored in Resolving conversations. When a review comment has been addressed, you can mark the conversation as resolved. This is the part to say slowly: Resolved conversations are still accessible - they collapse but can be expanded again. A good GitHub workflow is like a well-run meeting: everyone knows the topic, the next action, and who has the floor.

      -

      Alex: First, navigate to the conversation thread (3 to jump between comment headings). Then, tab to the end of the thread to find the "Resolve conversation" button. After that, press Enter to mark it resolved. Finally, the conversation collapses and shows as "Resolved". It is like walking a hallway with named doors: read the sign, enter the right room, then confirm where you landed.

      -

      Jamie: Let's pause on Learning Cards: Reading the Conversation Tab. What should a learner take away from it?

      -

      Alex: Start with Learning Cards: Reading the Conversation Tab. There is something to understand, something to try, and something that proves the try worked.

      -

      Alex: The practical takeaway is this. 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. 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.

      -

      Jamie: Let's pause on Reading the Checks Tab. What should a learner take away from it?

      -

      Alex: Start with Reading the Checks Tab: The Checks tab shows the status of automated tests, CI workflows, and other verification processes running on your PR. The next useful detail is this: It helps you verify whether your changes pass all required tests before merging.

      -

      Alex: The practical takeaway is this. Navigate through the check steps with K or Tab. Activate a step for more details.

      -

      Alex: First, navigate to the "Pull request tabs" landmark (D). Then, navigate between tab links (K or Tab) and activate "Checks". After that, press D to jump to the "check suites" section - this moves focus to the collapsed details button of the first check. Finally, press B or Tab to navigate between check buttons; each button is labeled with the check's name. Think of it as a rail line: each stop confirms you are still on the right route before the next one.

      -

      Jamie: Before we leave Reading the Checks Tab, what is the practical point?

      -

      Alex: First, press Enter or Space to expand a check and reveal its logs. Then, for a summary view: press D to navigate to the "check run summary" section. After that, vO+U - Landmarks - "Pull request tabs" - activate "Checks". Finally, vO+U - Landmarks - navigate to "check suites" section. Treat it like a recipe: do not add the next ingredient until the previous one is actually in the bowl.

      +

      Jamie: Let's pause on Workspace (Repository) - Team-Shared. What should a learner take away from it?

      +

      Alex: Start with Workspace (Repository) - Team-Shared: Files committed to your repository. The next useful detail is this: Everyone who clones the repo gets them.

      +

      Alex: Keep the teaching thread moving. Here is the plain-English version of User / Personal - Follows You Across Workspaces. Files in your VS Code profile folder. Put another way, available in every workspace you open.

      +

      Jamie: Let's pause on Organization - GitHub-Configured (Enterprise/Teams). What should a learner take away from it?

      +

      Alex: This is where Organization - GitHub-Configured (Enterprise/Teams) becomes real: configured by administrators in GitHub organization settings. That matters in practice: Automatically applied to all organization members.

      +

      Alex: That shows up in the workshop in a few specific ways. Enable discovery: github.copilot.chat.organizationInstructions.enabled: true. Lowest priority - workspace and user instructions override when there is a conflict.

      -

      Jamie: Let's pause on Learning Cards: Reading the Checks Tab. What should a learner take away from it?

      -

      Alex: Start with Learning Cards: Reading the Checks Tab. There is something to understand, something to try, and something that proves the try worked.

      -

      Alex: The practical takeaway is this. 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. 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.

      -

      Alex: Here is the practical turn. This is where Reading the Files Changed Tab becomes real: the learner will read diffs - the before/after state of every file that changed. That matters in practice: This guide uses GitHub's improved Files Changed experience. The workshop is closer to rehearsal than lecture. You hear the move, try the move, and then check what changed.

      -

      Jamie: Let's pause on File Tree (left panel). What should a learner take away from it?

      -

      Alex: Keep the learner anchored in File Tree (left panel). The file tree lists every changed file. This is the part to say slowly: Use it to jump directly to a specific file's diff.

      -

      Alex: The practical takeaway is this. 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.

      -

      Alex: First, d → navigate to "File tree" region. Then, ↑/↓ to navigate the file list. After that, enter to jump to that file's diff. Finally, vO+U → Landmarks → navigate to "File tree" region. It is like walking a hallway with named doors: read the sign, enter the right room, then confirm where you landed.

      -

      Jamie: Before we leave File Tree (left panel), what is the practical point?

      -

      Alex: First, vO+Down to move through the file list. Then, vO+Space to jump to that file's diff. The rhythm is simple: orient, act, verify, then continue.

      +

      Alex: Keep the teaching thread moving. Keep the learner anchored in 8. Instruction Priority and Conflicts. When multiple instruction sources give conflicting guidance, VS Code uses this priority order. This is the part to say slowly: This priority applies to conflicts. A good GitHub workflow is like a well-run meeting: everyone knows the topic, the next action, and who has the floor.

      +

      Jamie: Let's pause on How Instructions Are Combined. What should a learner take away from it?

      +

      Alex: The reason How Instructions Are Combined matters is that result: Copilot follows TypeScript strict mode (from workspace), British English (from org), AND the Z-spelling override (from user, which overrides the org instruction on that specific point).

      +

      Alex: For a learner, the useful signals are these. Organization: "Use British English spellings". Workspace: "Use TypeScript strict mode". User: "Use British English spellings - but use Z spellings (organize, not organise) for technical terms".

      +

      Alex: Keep the teaching thread moving. Start with Priority Within the Same Scope: Within a single scope (e.g., workspace), all matching instructions files are combined with no inherent priority. The next useful detail is this: If two workspace-level.instructions.md files contradict each other, the behavior is undefined - avoid conflicting workspace instructions.

      -

      Alex: Another way to ground it. Start with The Diff for a File. There is something to understand, something to try, and something that proves the try worked.

      -

      Alex: The practical takeaway is this. 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.

      -

      Jamie: Let's pause on Lines in a diff are read as. What should a learner take away from it?

      -

      Alex: Start with Lines in a diff are read as. There is something to understand, something to try, and something that proves the try worked.

      -

      Alex: The practical takeaway is this. + Added line - line that was added. Removed line - line that was removed. Context line - unchanged line shown for context.

      -

      Jamie: Let's pause on Navigating the diff with a screen reader. What should a learner take away from it?

      -

      Alex: Here is the plain-English version of Navigating the diff with a screen reader. Each file's diff shows added lines in green and removed lines in red. Put another way, scroll the page to read through changes. It is like learning a transit route. The names of the stops matter because they tell you whether you are still going the right direction.

      -

      Alex: The practical takeaway is this. 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.

      -

      Alex: First, t to jump to the next diff table. Then, switch to Focus Mode: Insert+Space (NVDA) or Insert+Z (JAWS). After that, ctrl+Alt+↓ to move down one row (next diff line), Ctrl+Alt+↑ to move up. Finally, ctrl+Alt+→ to read across columns (line number change type content). Treat it like a recipe: do not add the next ingredient until the previous one is actually in the bowl.

      -

      Jamie: Before we leave Navigating the diff with a screen reader, what is the practical point?

      -

      Alex: First, the screen reader reads: "+ Add accessible name to submit button". Then, collapsed sections contain unchanged code. Focus the expand/disclosure control and activate it (Enter or Space) to reveal the hidden lines. After that, t or VO+U → Tables → select the diff table. Finally, vO+Shift+Down to enter the table. It is a checklist, but a meaningful one: every item creates evidence that the next step is safe.

      +

      Jamie: Let's pause on Create any new customization file. What should a learner take away from it?

      +

      Alex: Here is the plain-English version of Create any new customization file. Ctrl+Shift+P → "Chat: New Instructions File" (or "New Prompt File", "New Agent File").

      +

      Alex: Keep the teaching thread moving. This is where 10. VS Code Settings Reference becomes real: all Copilot customization-related settings. That matters in practice: Set in VS Code Settings (Ctrl+,) or settings.json. The workshop is closer to rehearsal than lecture. You hear the move, try the move, and then check what changed.

      +

      Jamie: Let's pause on Deprecated Task-Specific Instructions. What should a learner take away from it?

      +

      Alex: Keep the learner anchored in Deprecated Task-Specific Instructions. Prefer file-based instructions over these settings for new work. This is the part to say slowly: Each accepts an array with items: { "text": "." } (inline) or { "file": "relative/path" } (from file).

      -

      Jamie: Let's pause on Placing an inline comment on a diff line. What should a learner take away from it?

      -

      Alex: This is where Placing an inline comment on a diff line becomes real: hover over any line in the diff - a blue + button appears on the left margin. That matters in practice: Click it to open a comment box for that line.

      -

      Alex: The practical takeaway is this. 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.

      -

      Alex: First, navigate to the specific line in the diff (using the table navigation above). Then, while focused on that line, a comment button appears - press Enter or Space to activate it. After that, a comment box opens below the line. Finally, focus Mode → type your comment. It is a checklist, but a meaningful one: every item creates evidence that the next step is safe.

      -

      Jamie: Before we leave Placing an inline comment on a diff line, what is the practical point?

      -

      Alex: First, tab to Add single comment button (instant comment) OR Start a review (to batch comments). It is like walking a hallway with named doors: read the sign, enter the right room, then confirm where you landed.

      -

      Jamie: Let's pause on Multi-line comment (Windows). What should a learner take away from it?

      -

      Alex: Keep the learner anchored in Multi-line comment (Windows). Screen reader users (VoiceOver - macOS).

      -

      Alex: First, focus the first line you want to comment on. Then, press Shift+↓ to extend the selection to additional lines. After that, a comment button appears - activate it. Finally, the comment applies to the full range of selected lines. It is like walking a hallway with named doors: read the sign, enter the right room, then confirm where you landed.

      -

      Jamie: Before we leave Multi-line comment (Windows), what is the practical point?

      -

      Alex: First, navigate to the specific line in the diff (using the table navigation above). Then, while focused on that line, VO+Space on the comment button that appears. After that, a comment box opens below the line. Finally, vO+Shift+Down to interact with the text area, then type your comment. The rhythm is simple: orient, act, verify, then continue.

      -

      Jamie: Let's pause on Multi-line comment (macOS). What should a learner take away from it?

      -

      Alex: Start with Multi-line comment (macOS). There is something to understand, something to try, and something that proves the try worked.

      -

      Alex: First, focus the first line and Shift+↓ to extend the selection. Then, vO+Space on the comment button that appears. After that, the comment applies to the full range of selected lines. The rhythm is simple: orient, act, verify, then continue.

      +

      Jamie: What is the ordered workflow?

      +

      Alex: The reason Settings Sync matters is that to sync your personal prompts, instructions, and agents across devices. That gives the learner a simple foothold: your personal.instructions.md,.agent.md, and.prompt.md files will sync to all signed-in VS Code instances.

      +

      Alex: First, ctrl+Shift+P → "Settings Sync: Turn On". Then, ctrl+Shift+P → "Settings Sync: Configure". After that, check "Prompts and Instructions". The rhythm is simple: orient, act, verify, then continue.

      +

      Jamie: Give me the sequence, because order matters here.

      +

      Alex: Start with View All Loaded Customizations: To see which instruction files, agents, prompts, and skills are currently loaded - and check for errors.

      +

      Alex: The practical takeaway is this. All agents found and whether they loaded successfully. All prompt/instruction files and their source (workspace vs user vs organization). All skills and their discovery status. Any parse errors or invalid frontmatter.

      +

      Alex: First, configure Chat Gear: Click the gear () icon in the Copilot Chat header → "Diagnostics". Then, right-click method: Right-click in the Chat view → "Diagnostics". Think of it as a rail line: each stop confirms you are still on the right route before the next one.

      +

      Jamie: What does the learner do first, second, and then after that?

      +

      Alex: Start with copilot-instructions.md not being followed. There is something to understand, something to try, and something that proves the try worked.

      +

      Alex: First, confirm the file is at exactly.github/copilot-instructions.md (relative to workspace root). Then, check the file is plain Markdown with no frontmatter syntax errors. After that, open Diagnostics to confirm it appears in the loaded files list. Finally, some instructions work better with specific phrasing; use imperative mood ("Always use."). Treat it like a recipe: do not add the next ingredient until the previous one is actually in the bowl.

      -

      Alex: The next layer is this. Start with Viewing comments within the diff: Inline comments appear as expandable threads within the diff table. The next useful detail is this: Navigate to them with 3 (they are h3 headings). Think of it like entering a new building: first you find the lobby, then the room, then the door you actually need.

      -

      Jamie: Let's pause on Learning Cards: Reading the Files Changed Tab. What should a learner take away from it?

      -

      Alex: Start with Learning Cards: Reading the Files Changed Tab. There is something to understand, something to try, and something that proves the try worked.

      -

      Alex: The practical takeaway is this. 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. 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.

      -

      Jamie: Let's pause on Tool Cards: Open a Pull Request. What should a learner take away from it?

      -

      Alex: This is where Tool Cards: Open a Pull Request becomes real: VS Code Desktop (GitHub Pull Requests extension).

      -

      Alex: First, push your branch, then click the Compare & pull request banner (or go to Pull requests New pull request ). Then, set base branch to main, compare branch to yours. After that, fill in the title and description, then click Create pull request. Finally, after committing changes, click the Source Control icon. It is a checklist, but a meaningful one: every item creates evidence that the next step is safe.

      -

      Jamie: Before we leave Tool Cards: Open a Pull Request, what is the practical point?

      -

      Alex: First, click Create Pull Request in the Source Control panel header. Then, fill in details and submit. After that, press Ctrl+Shift+P, type GitHub Pull Requests: Create Pull Request. Finally, select base and compare branches. It is like walking a hallway with named doors: read the sign, enter the right room, then confirm where you landed.

      -

      Alex: Treat examples as spoken recipes, not decorations. You may hear something like git push -u origin your-branch; gh pr create --title "Your title" --body "Description". Read the command, understand what it changes, then run it only when the repository state matches the lesson.

      +

      Jamie: Turn that into a path someone can follow.

      +

      Alex: Start with.instructions.md file not loading automatically. There is something to understand, something to try, and something that proves the try worked.

      +

      Alex: First, verify chat.includeApplyingInstructions is not set to false. Then, check the applyTo glob - test with " " temporarily to confirm the file loads at all. After that, confirm the file is in.github/instructions/ or a folder listed in chat.instructionsFilesLocations. Finally, file extension must be.instructions.md exactly - not.md, not.instruction.md. It is a checklist, but a meaningful one: every item creates evidence that the next step is safe.

      +

      Jamie: Let's pause on Custom agent (@agent-name) not appearing. What should a learner take away from it?

      +

      Alex: Start with Custom agent (@agent-name) not appearing. There is something to understand, something to try, and something that proves the try worked.

      +

      Alex: First, file must be named.agent.md and placed in.github/agents/. Then, check YAML frontmatter for syntax errors - use a YAML validator. After that, confirm user-invocable is not set to false (which hides it from the picker). Finally, run Ctrl+Shift+P → "Reload Window" after any changes to agent files. It is like walking a hallway with named doors: read the sign, enter the right room, then confirm where you landed.

      +

      Jamie: Let's pause on Slash command (/command) not appearing. What should a learner take away from it?

      +

      Alex: Start with Slash command (/command) not appearing. There is something to understand, something to try, and something that proves the try worked.

      +

      Alex: First, file must be at.github/prompts/.prompt.md. Then, extension must be.prompt.md exactly. After that, reload VS Code: Ctrl+Shift+P → "Reload Window". The rhythm is simple: orient, act, verify, then continue.

      -

      Jamie: Let's pause on From the web editor workflow (editing a file on GitHub). What should a learner take away from it?

      -

      Alex: Start with From the web editor workflow (editing a file on GitHub). There is something to understand, something to try, and something that proves the try worked.

      -

      Alex: First, you edited a file → GitHub showed a "Propose changes" form. Then, you named your branch and activated "Propose changes". After that, GitHub redirected you to the "Open a pull request" page. It is like walking a hallway with named doors: read the sign, enter the right room, then confirm where you landed.

      -

      Jamie: Let's pause on From a fork or feature branch. What should a learner take away from it?

      -

      Alex: The reason From a fork or feature branch matters is that screen reader users (NVDA / JAWS - Windows). That gives the learner a simple foothold: screen reader users (VoiceOver - macOS). The interface gets friendlier when it stops being a wall of controls and starts being a set of named places.

      -

      Alex: First, navigate to the repository on GitHub. Then, if you recently pushed, a yellow banner "Compare & pull request" appears at the top - click it. After that, if no banner appears: click the Pull requests tab → click the green New pull request button. Finally, use the branch dropdowns to choose your base branch (what to merge into) and your compare branch (your changes). The rhythm is simple: orient, act, verify, then continue.

      -

      Jamie: Before we leave From a fork or feature branch, what is the practical point?

      -

      Alex: First, click Create pull request. Then, navigate to the repository. After that, a "Compare & pull request" banner may appear (if you recently pushed) - activate it. Finally, oR: Navigate to Pull Requests tab → "New pull request". Think of it as a rail line: each stop confirms you are still on the right route before the next one.

      -

      Jamie: What should they understand before typing anything?

      -

      Alex: Start with Description field: Copilot can write your PR description: If your account has Copilot access, a "Copilot actions" button appears in the description toolbar. The next useful detail is this: 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.

      -

      Alex: Treat examples as spoken recipes, not decorations. You may hear something like Step 1: Tab to the body text area; Step 2: Focus Mode → type using the PR template (if provided). 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 for the dismiss control; Related Issues; Closes 42; Testing; - Tested with NVDA + Chrome on Windows 11; -. Read the command, understand what it changes, then run it only when the repository state matches the lesson.

      +

      Jamie: Let's pause on Instructions from different files conflicting. What should a learner take away from it?

      +

      Alex: Start with Instructions from different files conflicting. There is something to understand, something to try, and something that proves the try worked.

      +

      Alex: First, open Diagnostics to see all loaded instruction files. Then, remove or edit conflicting instructions - they are not automatically de-duplicated. After that, user-level instructions override workspace instructions for the same topic. Think of it as a rail line: each stop confirms you are still on the right route before the next one.

      +

      Jamie: Let's pause on chat.instructionsFilesLocations not working. What should a learner take away from it?

      +

      Alex: Start with chat.instructionsFilesLocations not working. There is something to understand, something to try, and something that proves the try worked.

      +

      Alex: The practical takeaway is this. Path must be a folder path, not a file path. Use forward slashes or escaped backslashes. Relative paths are relative to the workspace root.

      +

      Alex: Keep the teaching thread moving. This is where 12. Screen Reader Workflow - Official Guide becomes real: source: accessibility.github.com/documentation/guide/github-copilot-vsc/ Contributors: @mlama007, zersiax Community: GitHub Accessibility Discussions.

      -

      Jamie: Let's pause on Setting a Draft PR. What should a learner take away from it?

      -

      Alex: Here is the plain-English version of Setting a Draft PR. If your work is not finished, open as a Draft.

      -

      Alex: First, after filling in the form, find the dropdown arrow next to "Create pull request". Then, select "Create draft pull request". After that, this signals to reviewers that it is not ready for formal review yet. Treat it like a recipe: do not add the next ingredient until the previous one is actually in the bowl.

      -

      Jamie: Let's pause on Draft Pull Requests - Full Lifecycle. What should a learner take away from it?

      -

      Alex: This is where Draft Pull Requests - Full Lifecycle becomes real: a draft pull request is a PR explicitly marked as a work in progress. That matters in practice: It is visible to the team, can receive comments, and runs CI - but is blocked from being merged until you mark it ready.

      -

      Alex: Keep the teaching thread moving. Start with When to use a draft. There is something to understand, something to try, and something that proves the try worked.

      -

      Alex: The practical takeaway is this. You want to show your approach and get early feedback before finishing. You need CI to run but don't want accidental merges. You are working across multiple days and want your progress visible. You want to pair with a collaborator on the work.

      +

      Jamie: Let's pause on Prerequisites. What should a learner take away from it?

      +

      Alex: Start with Prerequisites. There is something to understand, something to try, and something that proves the try worked.

      +

      Alex: The practical takeaway is this. VS Code with GitHub Copilot Chat extension installed. A GitHub account with Copilot access (Free tier or paid). A screen reader (NVDA recommended for this guide).

      +

      Jamie: Let's pause on Step 1: Enable VS Code Screen Reader Mode. What should a learner take away from it?

      +

      Alex: The reason Step 1: Enable VS Code Screen Reader Mode matters is that when Screen Reader Mode is on, VS Code changes how it announces suggestions (full text instead of streaming), adjusts live regions, and enables accessible navigation patterns throughout the editor. The interface gets friendlier when it stops being a wall of controls and starts being a set of named places.

      +

      Alex: First, press Shift+Alt+F1 to toggle Screen Reader Accessibility Mode. Then, or use Command Palette: Ctrl+Shift+P → "Toggle Screen Reader Accessibility Mode". After that, VS Code announces: "Screen Reader Accessibility Mode enabled". The rhythm is simple: orient, act, verify, then continue.

      +

      Jamie: Let's pause on Step 2: Configure Accessibility Signals (Optional but Recommended). What should a learner take away from it?

      +

      Alex: Start with Step 2: Configure Accessibility Signals (Optional but Recommended): Recommended JSON config for Copilot accessibility signals.

      +

      Alex: First, open Settings: Ctrl+,. Then, search "accessibility signals". After that, enable the Copilot-specific signals. Think of it as a rail line: each stop confirms you are still on the right route before the next one.

      -

      Jamie: Let's pause on What a draft PR does differently. What should a learner take away from it?

      -

      Alex: Start with What a draft PR does differently. There is something to understand, something to try, and something that proves the try worked.

      -

      Alex: The practical takeaway is this. The merge button is disabled - even an authorized maintainer cannot merge a draft. The PR header shows a grey "Draft" badge instead of the green "Open" badge. Reviewers are not auto-notified (no review requests are sent until ready). CI workflows still run normally.

      -

      Jamie: Let's pause on Mark a draft ready for review. What should a learner take away from it?

      -

      Alex: Start with Mark a draft ready for review. There is something to understand, something to try, and something that proves the try worked.

      -

      Alex: First, open the PR. Then, navigate to the "Reviewers" sidebar or scroll to bottom of the Conversation tab. After that, find and activate the "Ready for review" button. Finally, the draft badge changes to "Open" and reviewers are notified. Think of it as a rail line: each stop confirms you are still on the right route before the next one.

      -

      Jamie: Let's pause on Convert an open PR to draft (after opening). What should a learner take away from it?

      -

      Alex: Here is the plain-English version of Convert an open PR to draft (after opening). GitHub CLI (gh) alternative - draft PR lifecycle. Put another way, manage draft PRs from your terminal.

      -

      Alex: First, in the right sidebar, find the "Reviewers" section. Then, look for the "Convert to draft" link (below the review status). After that, confirm in the dialog - this removes merge eligibility until you mark it ready again. Treat it like a recipe: do not add the next ingredient until the previous one is actually in the bowl.

      -

      Alex: Treat examples as spoken recipes, not decorations. You may hear something like Create a draft PR; gh pr create --draft --title "WIP: Add carousel keyboard nav"; Mark a draft ready for review; gh pr ready 42; Check PR status (shows draft state); gh pr view 42; List only draft PRs; gh pr list --draft. Read the command, understand what it changes, then run it only when the repository state matches the lesson.

      +

      Alex: Keep the teaching thread moving. Here is the plain-English version of Step 3: Official Shortcut Table (from accessibility.github.com). This is the complete table of Copilot screen reader shortcuts as published by the GitHub Accessibility team.

      +

      Jamie: How do you keep commands from becoming magic words?

      +

      Alex: This is where The screen reader-optimized workflow for every inline suggestion becomes real: this workflow avoids the streaming announcement problem (where suggestions are read out in fragments as tokens arrive) and gives you full, uninterrupted access to the suggestion text before committing.

      +

      Alex: Treat examples as spoken recipes, not decorations. You may hear something like Type your code or documentation; 2. Copilot generates a suggestion (audio cue sounds if enabled); 3. DO NOT press Tab immediately; 4. Press Alt+F2 - Accessible View opens with the full suggestion text; 5. Read the suggestion at your own pace with Arrow keys. Read the command, understand what it changes, then run it only when the repository state matches the lesson.

      +

      Jamie: Let's pause on Step 5: Recommended Workflow for Chat Responses. What should a learner take away from it?

      +

      Alex: Start with Step 5: Recommended Workflow for Chat Responses. There is something to understand, something to try, and something that proves the try worked.

      +

      Alex: Treat examples as spoken recipes, not decorations. You may hear something like Open Chat: Ctrl+Shift+I; 2. Type your prompt, press Ctrl+Enter to send; 3. Press Alt+F2 - Accessible View opens immediately; the response streams live into it; 4. Navigate with Arrow keys - no streaming noise, follow along in real-time; 5. Headings, code. Read the command, understand what it changes, then run it only when the repository state matches the lesson.

      -

      Alex: Keep the teaching thread moving. Start with Learning Cards: Opening a Pull Request. There is something to understand, something to try, and something that proves the try worked.

      -

      Alex: The practical takeaway is this. After editing a file on GitHub, the "Propose changes" form has a branch name field and a commit message field; press Tab to move between them. On the "Open a pull request" page, press F to jump to the Title field; Tab moves to the Description text area. Press Ctrl+Enter from inside the description text area to submit the PR without finding the Create button. The "Compare & pull request" yellow banner appears at the top of the repo after a recent push; at high zoom it may span the full width of the page. The branch comparison dropdowns (base and compare) use small text; zoom in on the area above the diff preview to read them. Draft PR: look for the dropdown arrow next to the green "Create pull request" button to switch to "Create draft pull request".

      -

      Jamie: Let's pause on Requesting reviewers. What should a learner take away from it?

      -

      Alex: Keep the learner anchored in Requesting reviewers. From the sidebar Reviewers section. This is the part to say slowly: Why some reviews are requested automatically: A file called CODEOWNERS in many repositories maps file paths to specific people or teams.

      -

      Alex: First, navigate to "Reviewers" heading (3 or H). Then, activate the gear button. After that, type a username in the search field. Finally, select from the dropdown. It is like walking a hallway with named doors: read the sign, enter the right room, then confirm where you landed.

      -

      Jamie: Before we leave Requesting reviewers, what is the practical point?

      -

      Alex: First, escape to save. The rhythm is simple: orient, act, verify, then continue.

      -

      Alex: Keep the teaching thread moving. The reason Submitting a Review matters is that when you are asked to review a PR, you have three options.

      -

      Alex: The practical takeaway is this. Comment - leave feedback without a verdict; does not block merging. Approve - signal you are satisfied; often required before merge. Request changes - indicate changes must be addressed; blocks merge until resolved.

      +

      Jamie: Let's pause on Reading the Suggestions Panel (Ctrl+Enter). What should a learner take away from it?

      +

      Alex: The reason Reading the Suggestions Panel (Ctrl+Enter) matters is that pressing Ctrl+Enter opens a Suggestions Panel - a separate editor tab that shows up to 10 alternative suggestions simultaneously. That gives the learner a simple foothold: this is useful when the default suggestion isn't quite right and you want to compare options.

      +

      Alex: Treat examples as spoken recipes, not decorations. You may hear something like Ctrl+Enter - opens "GitHub Copilot" editor tab; 2. Screen Reader Mode is active: navigate with Browse Mode; 3. H key to navigate headings (each suggestion may be under a heading); 4. Press Alt+F2 on a focused suggestion to read it in Accessible View; 5. Tab to. Read the command, understand what it changes, then run it only when the repository state matches the lesson.

      +

      Alex: Keep the teaching thread moving. Start with Learning Cards: Screen Reader Copilot Workflow. There is something to understand, something to try, and something that proves the try worked.

      +

      Alex: The practical takeaway is this. The golden rule: never accept a suggestion with Tab before reviewing it -- press Alt+F2 first, read it, then Ctrl+/ to insert. Enable the four Copilot audio signals (inline suggestion, request sent, response pending, response received) for non-verbal status awareness. Ctrl+Enter opens a Suggestions Panel with up to 10 alternatives -- navigate with H for headings, then Tab to the Accept button. Inline ghost text is typically rendered in a muted color -- if hard to see, rely on the lineHasInlineSuggestion audio signal instead. The Suggestions Panel (Ctrl+Enter) shows alternatives in a full editor tab at your current font size and theme. Chat responses are easier to read in Accessible View than in the streaming panel, especially at high zoom.

      +

      Jamie: Let's pause on 13. awesome-copilot - Plugin Ecosystem. What should a learner take away from it?

      +

      Alex: Here is the plain-English version of 13. awesome-copilot - Plugin Ecosystem. awesome-copilot is a GitHub repository (github/awesome-copilot) - not a VS Code Marketplace extension. Put another way, it is GitHub's curated ecosystem of Copilot plugins, prompts, instructions, agents, skills, and hooks that can be shared and discovered by anyone.

      -

      Jamie: What does someone need before they touch the keyboard?

      -

      Alex: Start with Starting a review: On the Files Changed tab, when you add inline comments, choose "Start a review" instead of "Add single comment." This batches all your comments into one review submission.

      -

      Jamie: Let's pause on Completing and submitting a review. What should a learner take away from it?

      -

      Alex: Here is the plain-English version of Completing and submitting a review. After adding your inline comments via "Start a review," you must submit the review to notify the PR author. Put another way, the review is pending until you submit it. It is like learning a transit route. The names of the stops matter because they tell you whether you are still going the right direction.

      -

      Alex: The practical takeaway is this. The button may scroll off-screen to the right. Use horizontal scrolling or press Tab from the page top to cycle through focusable elements until you reach it. When clicked, a popover appears with a summary text area and three radio buttons ( Comment, Approve, Request changes ). At 200%+ zoom, the popover may extend below the visible viewport. Scroll down within the popover to see the Submit review button. The radio buttons are standard HTML radio buttons. In Windows High Contrast mode, the selected radio button uses the system highlight color. Keyboard shortcut: If the button is hard to find visually, press Ctrl+Shift+Enter from within any review comment text area to open the submit review dialog directly.

      -

      Alex: First, look for the Finish your review button in the top-right area of the Files Changed tab (it shows the number of pending comments). Then, click it - a popover appears with a summary text area and three radio buttons: Comment, Approve, Request changes. After that, optionally type a summary comment. Finally, select your verdict by clicking the radio button. Treat it like a recipe: do not add the next ingredient until the previous one is actually in the bowl.

      -

      Jamie: Before we leave Completing and submitting a review, what is the practical point?

      -

      Alex: First, click Submit review. Then, press 1 to go to the h1 (PR title). After that, press B (or Tab) to navigate to the "Submit review" button and activate it (Enter/Space). Finally, a "Submit review" dialog/panel appears. It is a checklist, but a meaningful one: every item creates evidence that the next step is safe.

      -

      Alex: Treat examples as spoken recipes, not decorations. You may hear something like View the PR diff in your terminal; gh pr diff 42; Approve a PR; gh pr review 42 --approve; Approve with a comment; gh pr review 42 --approve --body "Looks good - heading hierarchy is correct."; Request changes; gh pr review 42 --request-changes --body "The alt. Read the command, understand what it changes, then run it only when the repository state matches the lesson.

      -

      Jamie: Let's pause on GitHub shortcuts for pull requests. What should a learner take away from it?

      -

      Alex: This is where GitHub shortcuts for pull requests becomes real: these are the GitHub built-in shortcuts for PR pages. That matters in practice: Enable Focus Mode first (NVDA: NVDA+Space, JAWS: Insert+Z) before using single-key shortcuts.

      +

      Alex: Keep the teaching thread moving. This is where Repository Structure becomes real: lLM discovery: https://github.github.io/awesome-copilot/llms.txt - a machine-readable index of all available resources. The workshop is closer to rehearsal than lecture. You hear the move, try the move, and then check what changed.

      +

      Jamie: Let's pause on The /plugin Command - Browse and Install from Chat. What should a learner take away from it?

      +

      Alex: Keep the learner anchored in The /plugin Command - Browse and Install from Chat. The easiest way to explore awesome-copilot from VS Code.

      +

      Alex: First, open Copilot Chat (Ctrl+Shift+I). Then, type /plugin and press Enter. After that, Copilot Chat opens an interactive plugin marketplace browser. Finally, browse plugins by category, read descriptions, and install with a single command. It is like walking a hallway with named doors: read the sign, enter the right room, then confirm where you landed.

      +

      Jamie: Let's pause on CLI Plugin Installation. What should a learner take away from it?

      +

      Alex: The reason CLI Plugin Installation matters is that from any terminal with GitHub CLI (gh) installed.

      +

      Alex: Treat examples as spoken recipes, not decorations. You may hear something like Browse the marketplace; gh copilot plugin marketplace list; Add the awesome-copilot collection; gh copilot plugin marketplace add github/awesome-copilot; Install a specific plugin; gh copilot plugin install @awesome-copilot/accessibility-toolkit; List what you. Read the command, understand what it changes, then run it only when the repository state matches the lesson.

      -

      Alex: Keep the teaching thread moving. Keep the learner anchored in On the PR list page. Shortcut note: For G P, press G, release it, then press P (two sequential key presses, not simultaneous).

      -

      Jamie: Let's pause on On the Files Changed tab. What should a learner take away from it?

      -

      Alex: The reason On the Files Changed tab matters is that for the full shortcut system, see Screen Reader Cheat Sheet - GitHub Shortcuts section.

      -

      Alex: Keep the teaching thread moving. Start with Learning Cards: Submitting a Review. There is something to understand, something to try, and something that proves the try worked.

      -

      Alex: The practical takeaway is this. The review verdict controls are inside a popover triggered by the "Finish your review" button; press 1 to return to the h1 (PR title), then B or Tab forward to find the button -- it is easy to miss because it is not a landmark. Inside the popover, Tab past the summary text area to reach a radio group labeled "Review Event"; use Up/Down Arrow to switch between Comment, Approve, and Request Changes. Shortcut: press Ctrl+Shift+Enter from any review comment text area to open the submit review dialog directly, bypassing the search for the button. The "Finish your review" button sits in the top-right corner of the Files Changed tab with a small badge showing your pending comment count; at 200%+ zoom it may scroll off-screen to the right. Inside the submit popover, the three radio buttons (Comment, Approve, Request changes) are small standard HTML radios; zoom in on the popover area or use Tab to step between them. After submitting, your review verdict appears as a colored banner in the Conversation timeline: green for Approve, red for Request Changes, grey for Comment.

      +

      Jamie: Let's pause on MCP Server Integration (Docker required). What should a learner take away from it?

      +

      Alex: Start with MCP Server Integration (Docker required): awesome-copilot also ships as an MCP (Model Context Protocol) Server - a Docker-based tool server that extends Copilot with additional capabilities beyond file-based customizations. The next useful detail is this: Install in VS Code by clicking the button at https://aka.ms/awesome-copilot/mcp/vscode, or add manually to settings.json.

      +

      Alex: Treat examples as spoken recipes, not decorations. You may hear something like {; "mcp": {; "servers": {; "awesome-copilot": {; "type": "stdio",; "command": "docker",; "args": [; "run", "-i", "--rm",; "ghcr.io/github/awesome-copilot-mcp:latest"; ]; }; }; }; }. Read the command, understand what it changes, then run it only when the repository state matches the lesson.

      +

      Alex: Keep the teaching thread moving. Here is the plain-English version of 14. GitHub Agentic Workflows - Agents in the Cloud. Status: Technical Preview - GitHub Agentic Workflows entered technical preview on February 13, 2026. Put another way, as of May 2026 the feature remains in active development and preview; changes to the API and workflow format are ongoing. It is like learning a transit route. The names of the stops matter because they tell you whether you are still going the right direction.

      +

      Jamie: Let's pause on What This Enables. What should a learner take away from it?

      +

      Alex: This is where What This Enables becomes real: browse 50+ community-built workflows at Peli's Agent Factory.

      -

      Jamie: Let's pause on Suggested Changes. What should a learner take away from it?

      -

      Alex: Here is the plain-English version of Suggested Changes. A suggested change is a special form of inline review comment where the reviewer proposes exact replacement text. Put another way, the PR author can apply the suggestion directly from GitHub - no copy-paste or separate commit needed.

      -

      Jamie: Let's pause on As a reviewer - inserting a suggestion. What should a learner take away from it?

      -

      Alex: This is where As a reviewer - inserting a suggestion becomes real: the suggestion block is plain Markdown text in the comment editor. That matters in practice: (Three backticks, the word suggestion, Enter, your text, Enter, three backticks.).

      -

      Alex: First, on the Files Changed tab, navigate to the line you want to propose a change. Then, activate the line comment button for that line (the + that appears on hover, or Tab to navigate to it). After that, in the comment text area that opens, press Ctrl+G (Windows) or Cmd+G (Mac). Finally, GitHub wraps a suggestion block around the current line content. It is a checklist, but a meaningful one: every item creates evidence that the next step is safe.

      -

      Jamie: Before we leave As a reviewer - inserting a suggestion, what is the practical point?

      -

      Alex: First, edit the text inside the suggestion block to show your proposed change. Then, add context above the block if helpful: "This makes the alt text more descriptive:". After that, submit as part of your review ("Start a review" → batch with other comments). It is like walking a hallway with named doors: read the sign, enter the right room, then confirm where you landed.

      -

      Jamie: Let's pause on As an author - applying a suggestion. What should a learner take away from it?

      -

      Alex: Start with As an author - applying a suggestion. There is something to understand, something to try, and something that proves the try worked.

      -

      Alex: First, open the PR Conversation or Files Changed tab. Then, navigate to the inline comment containing a suggestion (it shows a diff-style preview). After that, find and activate the "Apply suggestion" button below the suggestion block. Finally, GitHub creates a commit automatically that applies the change - no file editing required. It is like walking a hallway with named doors: read the sign, enter the right room, then confirm where you landed.

      -

      Jamie: Before we leave As an author - applying a suggestion, what is the practical point?

      -

      Alex: First, the conversation thread is marked as resolved. The rhythm is simple: orient, act, verify, then continue.

      +

      Alex: Keep the teaching thread moving. Keep the learner anchored in How It Works. The gh aw CLI (a gh extension) compiles.md workflow files into.lock.yml GitHub Actions workflows. This is the part to say slowly: The AI agent (GitHub Copilot, Claude, or OpenAI Codex) reads your repository context and the natural language instructions, then performs the task using the GitHub MCP Server and other available tools.

      +

      Jamie: Let's pause on Workflow Format - Markdown with Frontmatter. What should a learner take away from it?

      +

      Alex: The reason Workflow Format - Markdown with Frontmatter matters is that unlike standard GitHub Actions (YAML), agentic workflows are Markdown files. That gives the learner a simple foothold: the body is natural language - describe what you want the AI agent to do.

      +

      Alex: Keep the teaching thread moving. Start with Security Model - "Safe Outputs": Workflows run read-only by default with sandboxed execution, network isolation, and SHA-pinned dependencies. The next useful detail is this: Write operations require explicit declaration in safe-outputs - a set of pre-approved, sanitized GitHub operations. Think of it like entering a new building: first you find the lobby, then the room, then the door you actually need.

      -

      Jamie: Let's pause on Batching multiple suggestions into one commit. What should a learner take away from it?

      -

      Alex: Start with Batching multiple suggestions into one commit. There is something to understand, something to try, and something that proves the try worked.

      -

      Alex: First, for each suggestion you want to apply, activate "Add suggestion to batch" instead of "Apply suggestion". Then, after selecting all suggestions, activate the "Commit suggestions" button that appears at the top. After that, GitHub applies all batched suggestions in a single commit. The rhythm is simple: orient, act, verify, then continue.

      -

      Jamie: Let's pause on When to use suggestions vs. comments. What should a learner take away from it?

      -

      Alex: Start with When to use suggestions vs. comments. There is something to understand, something to try, and something that proves the try worked.

      -

      Alex: The practical takeaway is this. Use a suggestion when you know the exact text that would fix the issue. Use a plain comment when the change requires judgment from the author (e.g., "this alt text isn't descriptive - can you describe what the image shows?"). A summary text area for overall comments. Radio buttons for Comment / Approve / Request changes.

      -

      Alex: First, after adding all your inline comments, navigate to the review summary button. Then, on Files Changed tab: find the "Review changes" button (B to navigate buttons). After that, press Enter to open the review dialog. Finally, a panel opens. Think of it as a rail line: each stop confirms you are still on the right route before the next one.

      -

      Jamie: Before we leave When to use suggestions vs. comments, what is the practical point?

      -

      Alex: First, switch to Focus Mode → type your summary comment. Then, navigate to the radio buttons with arrow keys → select your verdict. After that, tab to "Submit review" button → Enter. Treat it like a recipe: do not add the next ingredient until the previous one is actually in the bowl.

      -

      Alex: Keep the teaching thread moving. Start with Learning Cards: Suggested Changes. There is something to understand, something to try, and something that proves the try worked.

      -

      Alex: The practical takeaway is this. To insert a suggestion block, press Ctrl+G (Windows) or Cmd+G (Mac) in the comment text area; the screen reader announces the inserted fence -- arrow down to edit the text between the backtick lines. Alternatively type the block manually: three backticks, the word suggestion, Enter, your replacement text, Enter, three backticks -- this avoids relying on the keyboard shortcut. As a PR author, navigate to a suggestion comment with 3, then Tab to the "Apply suggestion" button; GitHub commits the change automatically with no file editing required. Suggestion blocks render as a mini inline diff: the original line in red/pink background and your proposed replacement in green background; in high-contrast mode these use system diff colors. The "Apply suggestion" button is small and sits below the suggestion diff preview; zoom into the comment area to find it, or Tab from the suggestion text to reach it. When batching multiple suggestions, a floating "Commit suggestions" bar appears at the top of the page; at high zoom scroll up or press Home to find it.

      +

      Jamie: Let's pause on Getting Started with gh aw. What should a learner take away from it?

      +

      Alex: Start with Getting Started with gh aw. There is something to understand, something to try, and something that proves the try worked.

      +

      Alex: Treat examples as spoken recipes, not decorations. You may hear something like Install the CLI extension; gh extension install github/gh-aw; Create a new workflow interactively (from github.com or VS Code also works); gh aw create; Compile your Markdown workflow to a GitHub Actions.lock.yml; gh aw. Read the command, understand what it changes, then run it only when the repository state matches the lesson.

      +

      Jamie: Let's pause on Monitoring Agentic Workflow Runs. What should a learner take away from it?

      +

      Alex: Start with Monitoring Agentic Workflow Runs. There is something to understand, something to try, and something that proves the try worked.

      +

      Alex: First, navigate to the Actions tab of your repository (D → Repository navigation → K to Actions). Then, find the workflow by name (h3 headings, navigate with 3). After that, press Enter to open a specific run. Finally, expand job steps to read the agent output log and any safe-outputs created. It is a checklist, but a meaningful one: every item creates evidence that the next step is safe.

      +

      Jamie: Let's pause on Resources. What should a learner take away from it?

      +

      Alex: Keep the learner anchored in Resources. Relationship to Accessibility Agents: Accessibility Agents agents (.agent.md files) are designed for interactive use inside VS Code. This is the part to say slowly: GitHub Agentic Workflows are a separate, cloud-native system that uses its own Markdown workflow format and the gh aw CLI - they are complementary tools, not the same mechanism.

      -

      Jamie: How do you keep commands from becoming magic words?

      -

      Alex: This is where Understanding Merge Options (for Maintainers) becomes real: when a PR is approved and checks pass, a maintainer can merge it. That matters in practice: The merge button section appears at the bottom of the Conversation tab.

      -

      Alex: Treat examples as spoken recipes, not decorations. You may hear something like Merge with default strategy (merge commit); gh pr merge 42; Squash and merge; gh pr merge 42 --squash; Rebase and merge; gh pr merge 42 --rebase; Delete the branch after merging; gh pr merge 42 --squash --delete-branch; Enable auto-merge (merges when checks. Read the command, understand what it changes, then run it only when the repository state matches the lesson.

      -

      Alex: Keep the teaching thread moving. Keep the learner anchored in After a PR is merged. for screen reader users, - deleting the branch after merge: Navigate to the "Add a comment" section (D), then press Shift+B to navigate backwards to the "Delete branch" button and activate it. This is the part to say slowly: This keeps your repository clean by removing the now-merged feature branch. A good GitHub workflow is like a well-run meeting: everyone knows the topic, the next action, and who has the floor.

      -

      Alex: The practical takeaway is this. The PR status badge changes to "Merged" (purple). The source branch can be deleted - a "Delete branch" button appears. Any linked issues with Closes N in the description are automatically closed.

      -

      Jamie: Let's pause on Auto-Merge - Merging When You Can't Wait Around. What should a learner take away from it?

      -

      Alex: The reason Auto-Merge - Merging When You Can't Wait Around matters is that auto-merge lets you pre-authorize a PR to merge automatically the moment all branch protection requirements are satisfied - required reviews approved, all status checks passing, and the branch up to date.

      -

      Alex: The practical takeaway is this. You've addressed all review comments and are waiting for CI to finish. A maintainer has approved the PR but a required check is still running. You're in a different time zone from the reviewers.

      +

      Alex: Keep the teaching thread moving. Start with Learning Cards: GitHub Agentic Workflows. There is something to understand, something to try, and something that proves the try worked.

      +

      Alex: The practical takeaway is this. Agentic workflow runs appear in the Actions tab of your repository -- navigate to Actions with T (tab bar), then use heading navigation (3) to jump between workflow run entries. Workflow files are Markdown (.md) not YAML -- the frontmatter at the top controls triggers and permissions; the body is natural language instructions the AI agent reads. The safe-outputs frontmatter property lists every write operation the agent is allowed to perform -- review this section carefully since it is the security boundary. The Actions tab lists workflow runs with status icons (green check, red X, yellow circle) -- at high zoom, also look for the text status label next to each run name. Workflow.md files use the same Markdown rendering as any other file in the repo -- edit them in VS Code with your preferred font size and theme. The gh aw compile command generates a.lock.yml file alongside your.md file -- both appear in the file explorer; the.lock.yml is auto-generated and should not be edited manually.

      +

      Jamie: Let's pause on Copilot Models. What should a learner take away from it?

      +

      Alex: Start with Copilot Models. There is something to understand, something to try, and something that proves the try worked.

      +

      Alex: The practical takeaway is this. Overview. How to Choose a Model. Complete Model Reference. Model Availability by Plan. Premium Requests and Cost Multipliers. Switching Models in VS Code.

      +

      Alex: Keep the teaching thread moving. Here is the plain-English version of 1. Overview. GitHub Copilot offers access to AI models from multiple providers including OpenAI, Anthropic, Google, and xAI. Put another way, the model you choose affects response quality, speed, and premium request consumption.

      -

      Alex: Keep the teaching thread moving. Start with What happens next. There is something to understand, something to try, and something that proves the try worked.

      -

      Alex: The practical takeaway is this. The PR merge box changes to show "Auto-merge enabled - merge will happen automatically". When the last required check passes (or last required review arrives), GitHub merges the PR silently. You receive a notification: "Your PR was automatically merged". If a reviewer requests changes after auto-merge is enabled, auto-merge is automatically cancelled (a new approval is required before it re-enables).

      -

      Jamie: Let's pause on Cancelling Auto-Merge. What should a learner take away from it?

      -

      Alex: Here is the plain-English version of Cancelling Auto-Merge. Auto-merge is only available if the repository administrator has enabled it in Settings → General. Put another way, many open source repos have it on; some do not.

      -

      Alex: Treat examples as spoken recipes, not decorations. You may hear something like Merge box → Tab → "Disable auto-merge" button → Enter. Read the command, understand what it changes, then run it only when the repository state matches the lesson.

      -

      Alex: Keep the teaching thread moving. This is where Scenario A: "I want to review an assigned PR" becomes real: example: You are assigned to review a PR titled "Add missing NVDA shortcut to keyboard-shortcuts.md." The PR modifies docs/keyboard-shortcuts.md in the Learning Room repository and references Challenge 2. The workshop is closer to rehearsal than lecture. You hear the move, try the move, and then check what changed.

      +

      Jamie: Let's pause on 2. How to Choose a Model. What should a learner take away from it?

      +

      Alex: This is where 2. How to Choose a Model becomes real: GitHub Docs organizes models by task. That matters in practice: Match your task to the right model to get the best results without unnecessary premium request cost.

      +

      Alex: Keep the teaching thread moving. Keep the learner anchored in General-Purpose Coding and Writing. For everyday tasks - code completions, explanations, refactoring, writing documentation. A good GitHub workflow is like a well-run meeting: everyone knows the topic, the next action, and who has the floor.

      +

      Jamie: How should someone ask for help in a way that gets them unstuck faster?

      +

      Alex: The reason Fast Help with Simple or Repetitive Tasks matters is that for quick answers, boilerplate generation, renaming, or lightweight explanations where speed matters.

      -

      Jamie: Let's pause on Scenario B: "I want to respond to review feedback on my PR". What should a learner take away from it?

      -

      Alex: Keep the learner anchored in Scenario B: "I want to respond to review feedback on my PR". Example: Your PR for Challenge 3 (Complete Welcome Guide) received a review comment: "The [TODO] about evaluating issues is good, but the paragraph could mention checking if the issue is already assigned." The validation bot also flagged a link text issue.

      -

      Alex: Keep the teaching thread moving. The reason Writing PR Descriptions That Get Reviewed matters is that see also: Appendix C: Markdown Reference for formatting your PR description with headings, lists, and task lists. That gives the learner a simple foothold: a pull request is only as useful as its description.

      -

      Jamie: Let's pause on What Reviewers Look For. What should a learner take away from it?

      -

      Alex: Start with What Reviewers Look For: When a reviewer opens your PR, they are asking four questions before they ever look at the diff. The next useful detail is this: If your description answers all four, the reviewer can jump straight into the code with context.

      -

      Alex: First, why does this change exist? -- What problem does it solve, or what goal does it advance? Then, what is the scope? -- Which files changed, and roughly how big is the change? After that, how was it tested? -- Did you verify that the change works, and how? Finally, what should I pay attention to? -- Are there tricky parts, trade-offs, or areas where you want a second opinion? Think of it as a rail line: each stop confirms you are still on the right route before the next one.

      +

      Alex: Keep the teaching thread moving. Start with Deep Reasoning and Debugging: For complex problems, architecture decisions, multi-file analysis, tricky bugs, and understanding unfamiliar codebases.

      +

      Jamie: Let's pause on Agentic Software Development. What should a learner take away from it?

      +

      Alex: Here is the plain-English version of Agentic Software Development. For autonomous coding tasks in Agent mode - when Copilot writes code, runs terminal commands, and iterates without step-by-step guidance from you.

      +

      Alex: Keep the teaching thread moving. This is where Working with Visuals becomes real: for tasks that involve images, screenshots, diagrams, or UI mockups - paste an image directly into the chat input. The workshop is closer to rehearsal than lecture. You hear the move, try the move, and then check what changed.

      -

      Alex: Keep the teaching thread moving. Here is the plain-English version of The Closes XX Pattern. GitHub recognizes special keywords in PR descriptions that automatically close linked issues when the PR merges. Put another way, you do not need to close issues by hand -- just include the right keyword followed by the issue number. It is like learning a transit route. The names of the stops matter because they tell you whether you are still going the right direction.

      -

      Jamie: What is the pre-flight check here?

      -

      Alex: This is where Before/After Structure becomes real: one of the most effective patterns for PR descriptions is showing the state before your change and the state after. That matters in practice: This gives the reviewer an instant mental model of what changed without reading the diff line by line.

      -

      Alex: Keep the teaching thread moving. Keep the learner anchored in A PR Description Template. Here is a template you can copy into your PR descriptions. This is the part to say slowly: Not every section applies to every PR, but filling in even a few sentences per section makes a meaningful difference.

      +

      Jamie: Let's pause on 3. Complete Model Reference. What should a learner take away from it?

      +

      Alex: Keep the learner anchored in 3. Complete Model Reference. Model availability changes frequently. This is the part to say slowly: Check GitHub's supported models page for the current list.

      +

      Alex: Keep the teaching thread moving. The reason 4. Model Availability by Plan matters is that GitHub Copilot plan details and billing models are actively evolving. That gives the learner a simple foothold: facilitators will provide current guidance at the workshop.

      +

      Jamie: Let's pause on Tips for managing premium request usage. What should a learner take away from it?

      +

      Alex: Start with Tips for managing premium request usage. There is something to understand, something to try, and something that proves the try worked.

      +

      Alex: The practical takeaway is this. Use GPT-4.1 or GPT-5 mini (both free) for everyday questions, quick explanations, and simple completions - they're fast and capable. Upgrade to Claude Sonnet or GPT-5.2 (1×) only when the task genuinely requires deeper reasoning. Save Claude Opus (3×) for the most demanding analyses - architecture decisions, complex debugging, sophisticated design review. Use Auto mode (see below) and let Copilot allocate model selection intelligently.

      -

      Jamie: Let's pause on Common Description Mistakes. What should a learner take away from it?

      -

      Alex: The reason Common Description Mistakes matters is that even experienced contributors make these mistakes. That gives the learner a simple foothold: knowing what to avoid is half the battle.

      -

      Alex: Keep the teaching thread moving. Start with Good vs. Bad: Side by Side: No context, no linked issue, no explanation of what file or what was wrong with it. The next useful detail is this: A reviewer seeing this has to open the diff, figure out which file changed, read every line, and guess at the intent. Think of it like entering a new building: first you find the lobby, then the room, then the door you actually need.

      -

      Jamie: Let's pause on Learning Cards: Writing PR Descriptions That Get Reviewed. What should a learner take away from it?

      -

      Alex: Start with Learning Cards: Writing PR Descriptions That Get Reviewed. There is something to understand, something to try, and something that proves the try worked.

      -

      Alex: The practical takeaway is this. Use Markdown headings ( ) in your description (Summary, Changes, Related Issues, Testing) so reviewers can press H to jump between sections. Type Closes followed by the issue number to auto-close the linked issue on merge; GitHub autocompletes when you type. Press Ctrl+Shift+P in the description text area to toggle between Write and Preview modes; Preview renders your Markdown so you can check structure before submitting. Use the Preview tab to verify your Markdown renders correctly; headings, bullet lists, and code blocks are easier to proofread in rendered form. Keep bullet points short (one line each) so the description is scannable at high zoom without excessive horizontal scrolling. When including screenshots, add alt text in the Markdown image syntax: so every reader gets the same information.

      +

      Jamie: Let's pause on In the Chat Panel. What should a learner take away from it?

      +

      Alex: Start with In the Chat Panel. There is something to understand, something to try, and something that proves the try worked.

      +

      Alex: First, open the Chat panel (Ctrl+Shift+I / Cmd+Shift+I). Then, at the bottom of the chat input area, you'll see the current model name as a button (e.g., "Auto" or "Claude Sonnet 4.6"). After that, activate the model picker button - this opens a dropdown list of available models. Finally, arrow through the list and press Enter to select a model. Treat it like a recipe: do not add the next ingredient until the previous one is actually in the bowl.

      +

      Jamie: Before we leave In the Chat Panel, what is the practical point?

      +

      Alex: First, for screen reader users: the chat input will announce the newly selected model after switching. It is a checklist, but a meaningful one: every item creates evidence that the next step is safe.

      +

      Jamie: Let's pause on In an Inline Chat Session. What should a learner take away from it?

      +

      Alex: Start with In an Inline Chat Session. There is something to understand, something to try, and something that proves the try worked.

      +

      Alex: First, open Inline Chat (Ctrl+I / Cmd+I). Then, the model picker appears in the inline chat toolbar. After that, same interaction: activate the model button to switch. It is a checklist, but a meaningful one: every item creates evidence that the next step is safe.

      +

      Alex: Keep the teaching thread moving. Keep the learner anchored in Keyboard Note for Screen Readers. In the Chat panel, the model picker button is near the bottom of the chat view. This is the part to say slowly: If you're having trouble locating it.

      +

      Alex: The practical takeaway is this. Tab through the bottom toolbar of the chat panel. Listen for the model name announced - it appears between the "Attach" button and the send button. Press Space or Enter to open the picker.

      -

      Jamie: Let's pause on Try It: Read a Real Pull Request. What should a learner take away from it?

      -

      Alex: This is where Try It: Read a Real Pull Request becomes real: time: 3 minutes What you need: Browser, signed in to GitHub. That matters in practice: Go to the Learning Room repository's Pull Requests tab and find any open or recently closed PR.

      -

      Alex: First, navigate to Pull Requests (G then P in Focus Mode). Then, open the first PR in the list (press Enter on its title). After that, read the description - press 2 to jump to the first section heading, then arrow down to read. Look for: which file was changed (docs/welcome.md, docs/keyboard-shortcuts.md, or docs/setup-guide.md)? Which challenge was this PR solving? Does the description. Finally, check the conversation - press 3 to jump between comments. Read what the validation bot reported - did the bot find any accessibility issues like broken headings or non-descriptive links? How did the author respond? It is a checklist, but a meaningful one: every item creates evidence that the next step is safe.

      -

      Jamie: Before we leave Try It: Read a Real Pull Request, what is the practical point?

      -

      Alex: First, look at the diff - press D to the "Pull request tabs" landmark, then navigate to "Files changed" and press Enter. Press H to scan the changed file headings. If the PR touched docs/welcome.md, you should see + lines where the [TODO] sections were filled in. If. It is like walking a hallway with named doors: read the sign, enter the right room, then confirm where you landed.

      +

      Jamie: Let's pause on 7. Auto Model Selection. What should a learner take away from it?

      +

      Alex: The reason 7. Auto Model Selection matters is that auto mode (the default) lets Copilot choose the best model based on the type of request. That gives the learner a simple foothold: it became generally available on December 10, 2025.

      +

      Alex: Keep the teaching thread moving. Start with How Auto works. There is something to understand, something to try, and something that proves the try worked.

      +

      Alex: The practical takeaway is this. For simple questions, Copilot routes to a faster, lighter model. For complex code generation or debugging, Copilot upgrades to a more capable model automatically. For agent tasks, Copilot selects an appropriate Codex model. You can see which model was used after each response.

      +

      Jamie: Let's pause on When to override Auto. What should a learner take away from it?

      +

      Alex: Here is the plain-English version of When to override Auto. To switch back to Auto from a specific model, re-open the model picker and select Auto at the top of the list.

      +

      Alex: The practical takeaway is this. You specifically need a model with certain capabilities (e.g., vision input with Claude Sonnet 4). You're managing premium request quotas and want to control costs. You've found a particular model gives better results for your specific workflow or domain. You're doing agentic work and want to explicitly select an agent-optimized Codex model (check current availability in the model picker).

      -

      Jamie: What is the final checkpoint?

      -

      Alex: You should be able to point to the evidence, explain the action, and describe what you would do next if this were a real open source project. If you can teach the move back, you have learned it.

      -

      Jamie: And if they get stuck?

      -

      Alex: Read the latest message, not the loudest worry. Check the issue, the branch, the pull request, the status check, or the bot comment. Then ask for help with those facts in hand. That is how professionals collaborate.

      +

      Alex: Keep the teaching thread moving. This is where 8. Models Retiring Soon becomes real: GitHub regularly updates the model roster. That matters in practice: Older model versions are retired when newer equivalents are available.

      +

      Jamie: Let's pause on Already retired (as of April 2026). What should a learner take away from it?

      +

      Alex: Keep the learner anchored in Already retired (as of April 2026). To stay current, watch the GitHub Copilot changelog - model additions and retirements are announced there.

      +

      Alex: The practical takeaway is this. Claude Sonnet 3.5, Claude Sonnet 3.7. Gemini 2.0 Flash. o1-mini, o3, o3-mini, o4-mini. Claude Opus 4.1. GPT-5 (base), GPT-5-Codex. GPT-5.3-Codex (removed from Student plan model picker, April 2026).

      +

      Alex: Keep the teaching thread moving. The reason Related Resources matters is that next: Appendix L: Agents Reference Back: Appendix J: Codespaces Teaching chapter: Chapter 16: GitHub Copilot. The interface gets friendlier when it stops being a wall of controls and starts being a set of named places.

      +
      +

      Jamie: What should people carry with them after this?

      +

      Alex: Carry the map. Know what page or tool you are in, know which action you are taking, and know what confirmation should follow. If the confirmation is missing, pause. That pause is not wasted time; it is professional judgment.

      +

      Jamie: That is a better way to say it than just follow the steps.

      +

      Alex: Right. Steps matter, but understanding wins. That is episode 40. Next in the series is episode 41, where we keep building the same contributor muscles.

      -

      Challenge 07: Survive a Merge Conflict

      -

      Reading conflict markers, choosing content, deleting markers, and committing a resolution.

      +

      43. Episode 41: Copilot AI Models

      +

      Model comparison, strengths, plan availability, and selection guidance.

      +

      Based on: Appendix K: Copilot AI Models

      +

      Audio and transcript are being regenerated for this episode.

      -Read Transcript - Challenge 07: Survive a Merge Conflict +Read Transcript - Episode 41: Copilot AI Models

      Transcript

      -

      Alex: You are listening to Challenge Coach: Survive a Merge Conflict. I am Alex, and this is the calm walkthrough before the hands-on work.

      -

      Jamie: And I am Jamie. I will make sure we teach the skill instead of just reading the checklist aloud.

      +

      Alex: Welcome back to Git Going with GitHub. This is episode 41: Copilot AI Models. I am Alex, and today we are turning Copilot AI Models from a list of instructions into a working mental model.

      +

      Jamie: And I am Jamie. I will stop us whenever the instructions sound simple on paper but might feel different with a keyboard and screen reader.

      -

      Alex: The focus is Reading conflict markers, choosing content, deleting markers, and committing a resolution. We will explain the concept, the action, the evidence, and the most common recovery path.

      -

      Jamie: So the learner needs the why, the move, and the checkpoint all in the same mental pocket.

      -

      Alex: That is the teaching shape: understand the concept, do the smallest real action, then verify the result before moving on.

      +

      Alex: Model comparison, strengths, plan availability, and selection guidance. That is the surface description. Underneath it, we are building judgment: where to focus, what to ignore, and how to verify the result.

      +

      Jamie: So we are not using the audio as a shortcut around learning. We are using it to make the learning easier to enter.

      +

      Alex: Yes. A good audio lesson gives someone enough context to try the work with confidence, even before they open the written material.

      -

      Jamie: What makes this practice feel low-stakes but still real?

      -

      Alex: Start with Challenge 7: Survive a Merge Conflict: What you will do: Your facilitator will trigger a merge conflict in your PR. The next useful detail is this: the learner will resolve it by editing the file, removing conflict markers, and keeping the right content.

      -

      Alex: A solid Git habit is to know which branch you are on, what changed, and what confirmation you expect before you run the next command.

      -

      Alex: The next layer is this. Here is the plain-English version of What are conflict markers? When Git cannot automatically merge changes, it inserts markers like this. Put another way, your job: decide what the final version should look like, then delete all three marker lines ( ). It is like learning a transit route. The names of the stops matter because they tell you whether you are still going the right direction.

      -

      Jamie: What does the learner do first, second, and then after that?

      -

      Alex: This is where Instructions becomes real: autograded: The autograder will check that no conflict markers remain in your file and that the file has meaningful content.

      -

      Alex: First, wait for your facilitator to trigger the conflict (they will tell you when). Then, open your PR -- you will see a message about conflicts. After that, select Resolve conflicts (or edit the file directly on your branch). Finally, find the conflict markers in the file. It is a checklist, but a meaningful one: every item creates evidence that the next step is safe.

      -

      Jamie: Turn that into a path someone can follow.

      -

      Alex: First, decide which content to keep (or combine both). Then, delete all conflict marker lines. After that, commit the resolution. It is like walking a hallway with named doors: read the sign, enter the right room, then confirm where you landed.

      +

      Jamie: Okay, set the room for us. What are we walking into?

      +

      Alex: Start with Keyboard Shortcuts, Chat, Screen Reader Workflow, Plugin Ecosystem, and GitHub Agentic Workflows: Quick-reference card for GitHub Copilot in VS Code and the broader agentic ecosystem - plugins, MCP servers, and cloud-based automation. The next useful detail is this: For the Copilot lesson, see Chapter 16: GitHub Copilot.

      +

      Alex: A solid navigation habit is to prove where you are before activating controls. Headings, landmarks, and the address bar are not trivia; they are your map.

      +

      Alex: The next layer is this. Here is the plain-English version of Inline Suggestions (Ghost Text). Word-by-word acceptance (Ctrl+Right Arrow) is recommended for screen reader users - it lets you review the suggestion incrementally before committing to it. Put another way, accessible View workflow for screen reader users: Press Alt+F2 when a suggestion appears to hear the full text without streaming noise, then press Ctrl+/ to insert it directly from the Accessible View without closing the panel first. It is like learning a transit route. The names of the stops matter because they tell you whether you are still going the right direction.

      +

      Jamie: What is the one idea that makes the next few steps less mysterious?

      +

      Alex: This is where Accessibility becomes real: use Accessible View (Alt+F2) every time Copilot responds. That matters in practice: It provides the complete response in a readable pane - no streaming, no live region noise, proper heading structure.

      -

      Alex: Now bring the learner back to the room. Keep the learner anchored in Peer simulation check. Compare your resolution with the facilitator's conflict seed or with a real buddy if you have access. This is the part to say slowly: It is OK if two valid resolutions keep different wording.

      -

      Jamie: What would you say to someone who is already bracing for this to be too much?

      -

      Alex: The reason What conflict markers look like matters is that when Git cannot automatically merge two changes to the same lines, it inserts markers.

      +

      Alex: Now bring the learner back to the room. Keep the learner anchored in 2. Chat Participants. Type these in the Copilot Chat input to give Copilot context from a specific source.

      +

      Jamie: What should they understand before typing anything?

      +

      Alex: Start with Example prompts. There is something to understand, something to try, and something that proves the try worked.

      +

      Alex: Treat examples as spoken recipes, not decorations. You may hear something like @workspace find all places where heading hierarchy is documented; @github search community-access/accessibility-agents for issues labeled accessibility; @terminal what did the last command output mean? Read the command, understand what it changes, then run it only when the repository state matches the lesson.

      +

      Alex: A solid pull request habit is to separate three questions: what changed, why it changed, and what still needs review. That keeps the conversation useful instead of noisy.

      +

      Alex: That matters because of the next idea. Start with 3. Chat Slash Commands: Type / in Copilot Chat to see the available built-in commands. Think of it like entering a new building: first you find the lobby, then the room, then the door you actually need.

      Alex: The useful habit is simple: orient first, act second, verify third. That pause before acting is part of the work.

      -

      Alex: That matters because of the next idea. Start with The three sections. There is something to understand, something to try, and something that proves the try worked.

      -

      Alex: On the ground, that means a few things. Between <<<<<<< HEAD and =======: The version on the branch you are merging INTO (usually main). Between ======= and: The version on YOUR branch. The marker lines themselves: Must be deleted -- they are not content.

      -

      Jamie: How would you walk the room through that step by step?

      -

      Alex: Here is the plain-English version of Decision process. The choice depends on which version is better for the project.

      -

      Alex: First, keep yours: Delete the HEAD section and all markers, keep your changes. Then, keep theirs: Delete your section and all markers, keep the HEAD version. After that, combine both: Write new text that incorporates ideas from both versions, delete all markers. Treat it like a recipe: do not add the next ingredient until the previous one is actually in the bowl.

      -

      Alex: A solid pull request habit is to separate three questions: what changed, why it changed, and what still needs review. That keeps the conversation useful instead of noisy.

      -

      Jamie: What is the ordered workflow?

      -

      Alex: This is where On github.com becomes real: GitHub offers a conflict editor directly in the browser.

      -

      Alex: First, click "Resolve conflicts" on the PR page. Then, the editor highlights conflicting sections. After that, edit the file to remove markers and keep the content you want. Finally, click "Mark as resolved" then "Commit merge". It is a checklist, but a meaningful one: every item creates evidence that the next step is safe.

      +

      Jamie: There are a lot of tools in play. How do we keep that from feeling like a contest?

      +

      Alex: Here is the plain-English version of Workspace management slash commands. These are Copilot's built-in chat slash commands. Put another way, accessibility Agents adds 28 additional workspace-level slash commands from.github/prompts/ - see Appendix L for the full list.

      +

      Alex: This is where the talk moves from concept to action. This is where 4. Chat Modes becomes real: select the current mode from the dropdown at the bottom of the Chat input area. That matters in practice: The mode selector is in the Chat panel toolbar at the bottom.

      Jamie: What stays the same when the tool changes?

      -

      Alex: Keep the learner anchored in In VS Code. VS Code highlights conflicts and offers clickable options above each conflict.

      -

      Alex: These are the details that keep the idea from floating away. "Accept Current Change" (HEAD version). "Accept Incoming Change" (your version). "Accept Both Changes" (keeps both, you edit after).

      +

      Alex: Start with Learning Cards: Chat Participants, Commands, and Modes. There is something to understand, something to try, and something that proves the try worked.

      +

      Alex: These are the details that keep the idea from floating away. Type @ in Chat to scope context (@workspace, @terminal, @github) -- the autocomplete list is keyboard-navigable with arrow keys. Type / for slash commands (/explain, /fix, /tests) -- each is announced with its description as you arrow through. The mode selector is at the bottom of the Chat panel toolbar; Tab to it, then Space or Enter to open the dropdown. Chat responses appear in the panel with syntax highlighting -- increase the Chat panel font size via editor.fontSize in settings. The @ and / trigger characters are small but the autocomplete popup that follows is large and themed to your current color scheme. Use Ask mode for reading explanations, Agent mode for controlled multi-file changes and autonomous tasks (Edit mode is being deprecated into Agent mode as of VS Code 1.118).

      -

      Alex: Before the learner moves on. The reason What matters matters is that the learning objective is understanding that conflicts are normal and resolvable. That gives the learner a simple foothold: if you removed all conflict markers and the file makes sense, you completed this challenge. The interface gets friendlier when it stops being a wall of controls and starts being a set of named places.

      -

      Jamie: Give me the version that sounds like an instructor, not a manual.

      -

      Alex: Start with Understanding, Preventing, and Resolving Conflicts: Merge conflicts sound intimidating but are a normal, manageable part of collaborative development. The next useful detail is this: This guide explains what conflicts are, how to read conflict markers, and how to resolve them - step by step.

      -

      Alex: Hold that next to this. Here is the plain-English version of Workshop Recommendation (Chapter 7). Chapter 7 uses one controlled practice challenge so students can learn conflict resolution without high-pressure scenarios.

      -

      Alex: The practical anchors are these. There are 1. Time: under 10 minutes. The evidence is issue-linked PR and completion comment. The pattern is observe, resolve, verify.

      -
      -

      Jamie: Give me the sequence, because order matters here.

      -

      Alex: This is where Chapter 7 Challenge Set becomes real: use a short-lived feature branch: fix/yourname-issueXX (for example, fix/maria-issue48). That matters in practice: The same pattern you used in Chapter 6.

      -

      Alex: First, resolve conflict markers - identify and clean up conflict markers in a practice file, then open a linked PR. It is a checklist, but a meaningful one: every item creates evidence that the next step is safe.

      -

      Jamie: Let's pause on Challenge 7.1 Step-by-Step: Resolve Conflict Markers. What should a learner take away from it?

      -

      Alex: Keep the learner anchored in Challenge 7.1 Step-by-Step: Resolve Conflict Markers. Identify the three types of conflict markers in a practice file, decide which content to keep, remove the markers, and submit a clean PR. This is the part to say slowly: Sometimes an AI agent will confidently generate code that conflicts with human-written code. A good GitHub workflow is like a well-run meeting: everyone knows the topic, the next action, and who has the floor.

      -

      Alex: For a learner, the useful signals are these. Keep only your version,. Keep only their version,. Combine both versions into one clean paragraph. The <<<<<<< HEAD line (or similar).

      -

      Alex: First, open the practice file specified in your challenge issue. Then, search the file for <<<<<<<. This is the start marker - it shows where the conflict begins. After that, read the content between <<<<<<< and =======. This is your version (the current branch). Finally, read the content between ======= and. This is their version (the incoming branch). It is like walking a hallway with named doors: read the sign, enter the right room, then confirm where you landed.

      -

      Jamie: Before we leave Challenge 7.1 Step-by-Step: Resolve Conflict Markers, what is the practical point?

      -

      Alex: First, decide which content to keep. Then, delete all three marker lines. After that, review the file to confirm no marker lines remain. Search for <<<<<<< again - there should be zero results. Finally, commit your changes on a branch named fix/yourname-issueXX. The rhythm is simple: orient, act, verify, then continue.

      -

      Jamie: What should the learner prove to themselves after each small task?

      -

      Alex: The reason Completing Chapter 7: Submit Your Evidence matters is that when your PR is open and passing checks, post a comment on your assigned Chapter 7 challenge issue.

      -
      -

      Alex: Here is the practical turn. Start with Expected Outcomes. There is something to understand, something to try, and something that proves the try worked.

      -

      Alex: Here is what that changes in practice. Student can identify the three conflict marker lines ( ) immediately. Student can read both sides of a conflict and make an intentional content decision. Student can remove all markers and submit a clean, issue-linked PR.

      -

      Jamie: Let's pause on If You Get Stuck. What should a learner take away from it?

      -

      Alex: Start with If You Get Stuck. There is something to understand, something to try, and something that proves the try worked.

      -

      Alex: First, can't find the markers? Use Ctrl+F and search for <<<<<<< - they are always in sets of three. Then, not sure which side to keep? Read both versions aloud. Pick the one that is clearer, or combine them. After that, accidentally deleted too much? Undo with Ctrl+Z and start the section over. Finally, pR bot says content is wrong? Double-check that zero marker lines remain - search for. Treat it like a recipe: do not add the next ingredient until the previous one is actually in the bowl.

      -

      Jamie: Before we leave If You Get Stuck, what is the practical point?

      -

      Alex: First, ask facilitator to sanity-check your final content before opening the PR. Then, finished but not sure you did it right? Compare your work against the Challenge 7 reference solution. It is a checklist, but a meaningful one: every item creates evidence that the next step is safe.

      -

      Alex: Keep the thread going. This is where Learning Moment becomes real: they are a normal collaboration checkpoint and a chance to make an intentional content decision. That matters in practice: In real open source projects, conflicts happen whenever two people edit near the same lines. The workshop is closer to rehearsal than lecture. You hear the move, try the move, and then check what changed.

      +

      Alex: Before the learner moves on. The reason 5. Custom Instructions - All Levels matters is that GitHub Copilot supports multiple ways to provide custom instructions. That gives the learner a simple foothold: they differ by scope, priority, trigger mechanism, and which tools recognize them. The interface gets friendlier when it stops being a wall of controls and starts being a set of named places.

      +

      Jamie: What would you say to someone who is already bracing for this to be too much?

      +

      Alex: Start with 4A. Always-On Instructions -.github/copilot-instructions.md: What it is: The primary VS Code Copilot instruction file. The next useful detail is this: Content is automatically included in every chat request and inline suggestion context - you never need to invoke it.

      +

      Jamie: How would you walk the room through that step by step?

      +

      Alex: Start with Auto-generate with /init. There is something to understand, something to try, and something that proves the try worked.

      +

      Alex: First, open Copilot Chat. Then, type /init. After that, VS Code analyzes your workspace and generates a tailored copilot-instructions.md. Finally, review and edit the result before committing. Treat it like a recipe: do not add the next ingredient until the previous one is actually in the bowl.

      -

      Jamie: Let's pause on Learning Pattern Used in This Chapter. What should a learner take away from it?

      -

      Alex: Start with Learning Pattern Used in This Chapter. There is something to understand, something to try, and something that proves the try worked.

      -

      Alex: First, start with a controlled, safe conflict (practice file with known markers). Then, learn to read the conflict structure (your version vs. their version). After that, make a deliberate content decision (not just deleting randomly). Finally, submit clean evidence through the PR workflow. It is like walking a hallway with named doors: read the sign, enter the right room, then confirm where you landed.

      -

      Jamie: Before we leave Learning Pattern Used in This Chapter, what is the practical point?

      -

      Alex: First, build confidence for real conflicts in future contributions. The rhythm is simple: orient, act, verify, then continue.

      -

      Alex: Another way to ground it. The reason About Learning Cards in This Chapter matters is that this chapter provides learning cards: expandable blocks that offer perspective-specific guidance for different ways of working. That gives the learner a simple foothold: not every card appears at every step.

      -

      Jamie: What should they understand before typing anything?

      -

      Alex: Start with Local Git Alternative: Resolving Conflicts from Your Terminal: If you cloned the learning-room in Block 0 and prefer resolving conflicts locally. The next useful detail is this: The GitHub web conflict editor works well and is the primary method taught in this chapter.

      -

      Alex: A few details make that real. Keep the version you want (or combine both). Delete all three marker lines ( ). Save the file.

      -

      Alex: Treat examples as spoken recipes, not decorations. You may hear something like cd /Documents/learning-room; git checkout main; git pull origin main; git checkout your-branch-name; git merge main. code docs/welcome.md or your preferred editor. Read the command, understand what it changes, then run it only when the repository state matches the lesson.

      +

      Jamie: How should a learner choose a tool without feeling judged by the choice?

      +

      Alex: This is where 4B. Always-On Instructions - AGENTS.md (Multi-Tool / Monorepo) becomes real: what it is: An open standard instruction file recognized by multiple AI tools - GitHub Copilot, Claude Code, Gemini CLI, and others. That matters in practice: Use this instead of copilot-instructions.md when you want one instruction file that works across all AI coding assistants.

      +

      Alex: That connects to another useful point. Keep the learner anchored in 4C. Always-On Instructions - CLAUDE.md (Cross-Tool Compatibility). What it is: Instructions file originally from Claude Code that VS Code Copilot also recognizes. This is the part to say slowly: When to use: Mixed AI tool environments where Claude Code and VS Code Copilot are both used. A good GitHub workflow is like a well-run meeting: everyone knows the topic, the next action, and who has the floor.

      +

      Jamie: Where do you want a learner to place their attention here?

      +

      Alex: The reason Supported locations matters is that enable/disable: Set chat.useClaudeMdFile: true (default: on). That gives the learner a simple foothold: claude Rules format (for.claude/rules/ and /.claude/rules/).

      -

      Alex: This is the part worth saying out loud. Here is the plain-English version of What Is a Merge Conflict? A merge conflict occurs when two people have both changed the same part of the same file in different ways, and Git cannot automatically decide which version is correct. Put another way, Git can merge changes automatically when they touch different parts of a file. It is like learning a transit route. The names of the stops matter because they tell you whether you are still going the right direction.

      -

      Alex: That shows up in the workshop in a few specific ways. Person A changed line 12 to say "Submit form". Person B changed line 12 to say "Send message". Git asks: which one do you want to keep?

      -

      Jamie: Okay, set the room for us. What are we walking into?

      -

      Alex: This is where How to Prevent Conflicts (Prevention is Easier Than Resolution) becomes real: avoiding conflicts in the first place saves time and reduces stress. That matters in practice: Here are the most effective strategies.

      -

      Alex: That connects to another useful point. Keep the learner anchored in 1. Keep your branches short-lived. A branch that lives for 3 days has far fewer conflicts than one that lives for 3 weeks.

      -

      Alex: The parts worth keeping in working memory are these. Target: 1-3 days from branch to merge. If a feature takes longer, break it into smaller PRs.

      +

      Alex: Here is the practical turn. Start with 4D. Conditional / Scoped Instructions -.instructions.md: What it is: Instructions that apply only when specific file types or folders are involved in the chat. The next useful detail is this: More targeted than always-on instructions.

      +

      Jamie: Give me the version that sounds like an instructor, not a manual.

      +

      Alex: Start with Create an instructions file. There is something to understand, something to try, and something that proves the try worked.

      +

      Alex: Here is what that changes in practice. Ctrl+Shift+P → "Chat: New Instructions File" → choose scope (Workspace or User). Or create the file manually in.github/instructions/.

      +

      Alex: Keep the thread going. This is where 4E. Organization-Level Instructions (GitHub Enterprise and Teams) becomes real: what it is: Organization administrators define custom instructions that apply to all repositories in the organization. That matters in practice: Every team member automatically gets these instructions added to their Copilot context. The workshop is closer to rehearsal than lecture. You hear the move, try the move, and then check what changed.

      -

      Jamie: How do you keep commands from becoming magic words?

      -

      Alex: The reason 2. Sync with main frequently matters is that the longer your branch diverges from main, the more likely conflicts become. That gives the learner a simple foothold: best practice: Sync daily if main is active.

      -

      Alex: Treat examples as spoken recipes, not decorations. You may hear something like From your feature branch; git fetch origin; git merge origin/main; Or: git rebase origin/main (if comfortable with rebasing). Read the command, understand what it changes, then run it only when the repository state matches the lesson.

      -

      Alex: This is where the talk moves from concept to action. Start with 3. Communicate with your team: Let others know what files you're working on. The next useful detail is this: "Heads up: I'm working on the [TODO] sections in docs/welcome.md for Challenge 3. Think of it like entering a new building: first you find the lobby, then the room, then the door you actually need.

      -

      Jamie: What is the one idea that makes the next few steps less mysterious?

      -

      Alex: Here is the plain-English version of 4. Avoid mass reformatting. Running a formatter on an entire file creates conflicts with anyone else editing that file.

      -

      Alex: The room should hear these as checkpoints. Do it in a separate PR before functional changes. Announce it to the team. Merge it quickly so everyone can sync.

      +

      Jamie: If I am listening before the workshop starts, what should settle in my mind first?

      +

      Alex: Keep the learner anchored in Requirements. Use for: Organization-wide coding standards, security policies, legal disclaimers (open source license obligations), toolchain conventions.

      +

      Alex: That becomes easier when you listen for these cues. GitHub Enterprise or Teams plan with Copilot enabled. Admin configures instructions in organization settings on GitHub.com. Each user must enable discovery in VS Code.

      +

      Alex: Another way to ground it. The reason 4F. Settings-Based Instructions (Deprecated - Use Files Instead) matters is that these settings-based instructions are deprecated and may be removed in a future VS Code release. That gives the learner a simple foothold: for new work, use copilot-instructions.md or.instructions.md files.

      +

      Jamie: How should someone choose between those options?

      +

      Alex: Start with 4G. Comparison - When to Use Each Approach. There is something to understand, something to try, and something that proves the try worked.

      +

      Alex: Use the comparison to make a decision, not to recite a table. The main contrasts are: Approach means Always-on? means Multi-tool? means Best. copilot-instructions.md means Workspace means VS Code only means Primary project instructions. AGENTS.md means Workspace + monorepo means All AI tools means Multi-tool teams or large monorepos.

      +

      Alex: This is the part worth saying out loud. Start with Learning Cards: Custom Instructions. There is something to understand, something to try, and something that proves the try worked.

      +

      Alex: The practical anchors are these. The three-level scope hierarchy (Organization, Workspace, User) means instructions can come from multiple places -- use Chat Diagnostics (gear icon in Chat header) to list every loaded instruction file and its source.github/copilot-instructions.md is always-on and requires no frontmatter -- just write plain Markdown; screen readers read the source file like any other Markdown document.instructions.md files use YAML frontmatter with applyTo globs -- the frontmatter is the first few lines between --- delimiters; arrow through carefully to verify syntax. The Diagnostics panel (Chat gear, then Diagnostics) lists loaded files in a scrollable pane -- increase font size in VS Code settings if the file paths are hard to read. YAML frontmatter is indentation-sensitive -- enable VS Code's indentation guides (editor.guides.indentation) and use a high-contrast theme so the guide lines are visible. The /init command auto-generates copilot-instructions.md from your workspace -- review the generated file in your editor at your preferred zoom before committing.

      +

      Jamie: Let's pause on 6. Accessible View Workflow. What should a learner take away from it?

      +

      Alex: This is where 6. Accessible View Workflow becomes real: Copilot Chat responses stream in token by token, which can fragment screen reader announcements. That matters in practice: Accessible View (Alt+F2) gives you a complete, static, properly structured version of the response.

      Jamie: What should happen before anyone copies and runs it?

      -

      Alex: This is where 5. Pull before you push becomes real: always fetch and merge (or pull) before pushing your changes. That matters in practice: This catches conflicts locally where they're easier to resolve.

      -

      Alex: Treat examples as spoken recipes, not decorations. You may hear something like git pull origin main Sync your local main; git checkout your-branch; git merge main Merge main into your branch; git push Now push. Read the command, understand what it changes, then run it only when the repository state matches the lesson.

      -

      Jamie: If I am listening before the workshop starts, what should settle in my mind first?

      -

      Alex: Keep the learner anchored in 6. Work on separate files when possible. If multiple people are working simultaneously, divide tasks by files or modules rather than everyone touching the same code.

      -

      Alex: Keep the teaching thread moving. The reason 7. Keep PRs small matters is that a 50-file PR will almost certainly conflict with something. That gives the learner a simple foothold: a 5-file PR merges quickly and cleanly. The interface gets friendlier when it stops being a wall of controls and starts being a set of named places.

      +

      Alex: Keep the learner anchored in Recommended Workflow - Every Copilot Interaction. VS Code December 2025: The Accessible View now streams dynamically. This is the part to say slowly: You can open it immediately after sending a prompt and follow the response as it arrives - no need to wait for the response to finish before pressing Alt+F2.

      +

      Alex: Treat examples as spoken recipes, not decorations. You may hear something like Open Copilot Chat: Ctrl+Shift+I; 2. Type your prompt; 3. Press Ctrl+Enter to send; 4. Press Alt+F2 to open Accessible View (open immediately - no need to wait); 5. Follow as the response streams in the Accessible View in real-time; 6. Read or re-read any part. Read the command, understand what it changes, then run it only when the repository state matches the lesson.

      -

      Jamie: Where do you want a learner to place their attention here?

      -

      Alex: Start with 8. Use Draft PRs for early visibility: Open your PR as a draft while still working. The next useful detail is this: Others can see what you're changing and avoid overlapping work.

      -

      Alex: Keep the teaching thread moving. Start with Learning Cards: How to Prevent Conflicts. There is something to understand, something to try, and something that proves the try worked.

      -

      Alex: That becomes easier when you listen for these cues. Before starting work, run git pull origin main in VS Code's terminal ( Ctrl+ `) to sync your branch; this prevents conflicts from stale branches. On GitHub, check the PR's merge status section by pressing D toward the bottom of the Conversation tab; "This branch has conflicts" warns you before you waste review time. Use issue comments to announce which files you are editing; press D to the "Add a comment" landmark on the issue and type your coordination message. The "Update branch" button on a PR appears near the merge section at the bottom of the Conversation tab; it has a white-on-green style when available. When multiple students are editing the same file, GitHub shows a yellow conflict banner; zoom in on the merge area to check for it before requesting review. Draft PRs show a grey "Draft" badge in the PR list; opening drafts early gives teammates visibility into which files you are changing.

      +

      Jamie: Let's pause on NVDA / JAWS. What should a learner take away from it?

      +

      Alex: Start with NVDA / JAWS. There is something to understand, something to try, and something that proves the try worked.

      +

      Alex: The parts worth keeping in working memory are these. Up/Down Arrow - read line by line. Ctrl+Home - jump to start. H - navigate by headings (if response has sections). Escape - close Accessible View, return to Chat.

      +

      Alex: Hold that next to this. Start with VoiceOver. There is something to understand, something to try, and something that proves the try worked.

      +

      Alex: On the ground, that means a few things. VO+Shift+Down - interact with the Accessible View content. Down Arrow - read line by line. VO+Escape - stop interacting. Escape - close Accessible View.

      Jamie: What is the safe way to learn from that example?

      -

      Alex: This is where Advanced Prevention: Understanding Fast-Forward Merges becomes real: when your branch is perfectly up to date with main and adds new commits on top, GitHub can do a "fast-forward" merge - main simply moves forward to your latest commit. That matters in practice: How to achieve this: Rebase your branch on main right before merging.

      -

      Alex: Treat examples as spoken recipes, not decorations. You may hear something like git checkout your-branch; git fetch origin; git rebase origin/main; git push --force-with-lease See warning below about force pushing. Read the command, understand what it changes, then run it only when the repository state matches the lesson.

      +

      Alex: Here is the plain-English version of Accessible View for Inline Suggestions. When a multi-line ghost text suggestion appears in the editor. Put another way, this is especially important for multi-line suggestions where ghost text is hard to review incrementally.

      +

      Alex: Treat examples as spoken recipes, not decorations. You may hear something like Do not accept immediately; 2. Press Alt+F2; 3. Accessible View shows: "Suggestion: [full text]"; 4. Read the complete suggestion at your own pace; 5. Press Escape to close; 6. Press Tab to accept, or Escape to reject. Read the command, understand what it changes, then run it only when the repository state matches the lesson.

      -

      Alex: Keep the teaching thread moving. Keep the learner anchored in When Conflicts Are Actually Good. Conflicts indicate that multiple people are actively improving the project. This is the part to say slowly: In a healthy, collaborative environment, occasional conflicts are normal and manageable. A good GitHub workflow is like a well-run meeting: everyone knows the topic, the next action, and who has the floor.

      -

      Alex: The practical takeaway is this. You're the only contributor (less review, less learning). PRs are moving too slowly (stagnation). People are avoiding working on important files (technical debt).

      -

      Jamie: Let's pause on Tool Cards: Resolve a Merge Conflict. What should a learner take away from it?

      -

      Alex: The reason Tool Cards: Resolve a Merge Conflict matters is that when a PR has a merge conflict, you will see this message on the Conversation tab, near the merge section. That gives the learner a simple foothold: "This branch has conflicts that must be resolved".

      -

      Alex: The practical takeaway is this. The banner uses a yellow or orange background. In Windows High Contrast mode, it renders with the system alert color so it remains visible. The Resolve conflicts button is a standard link-style button. If it is hard to target at high zoom, use Tab to reach it after the merge status section and press Enter. If the button does not appear, you may lack write access to the repository. Ask the PR author or a maintainer for help.

      -

      Alex: First, on the PR page, click Resolve conflicts if the button is available. Then, edit the file in the web editor to remove conflict markers. After that, click Mark as resolved, then Commit merge. Finally, open the PR's branch by pressing. on the repository page. The rhythm is simple: orient, act, verify, then continue.

      -

      Jamie: Before we leave Tool Cards: Resolve a Merge Conflict, what is the practical point?

      -

      Alex: First, open the conflicting file -- conflict markers are highlighted in the editor. Then, edit to resolve, commit via Source Control panel. After that, pull the latest changes: git pull origin main. Finally, VS Code highlights conflicts with Accept Current / Accept Incoming / Accept Both buttons. Think of it as a rail line: each stop confirms you are still on the right route before the next one.

      -

      Alex: Treat examples as spoken recipes, not decorations. You may hear something like git merge main; Edit conflicting files to remove; git add resolved-file.md; git commit -m "resolve merge conflict". Read the command, understand what it changes, then run it only when the repository state matches the lesson.

      -

      Alex: Keep the teaching thread moving. Start with Conflict Markers - What They Mean: When conflict markers appear in a file, your editor is showing you both versions of the conflicted content so you can choose.

      +

      Alex: Keep the teaching thread moving. Start with Accessible View for Code Blocks. There is something to understand, something to try, and something that proves the try worked.

      +

      Alex: The room should hear these as checkpoints. Code blocks appear inside elements in Accessible View. Screen readers announce "code block" or "pre-formatted text" at the start. Each line is on its own line (not run together). Indentation is preserved.

      +

      Jamie: Let's pause on Learning Cards: Accessible View Workflow. What should a learner take away from it?

      +

      Alex: Start with Learning Cards: Accessible View Workflow. There is something to understand, something to try, and something that proves the try worked.

      +

      Alex: A few details make that real. Press Alt+F2 immediately after sending a prompt -- Accessible View now streams dynamically so you can follow along in real time. Navigate Chat responses with Up/Down Arrow; headings, code blocks, and lists are structurally intact in the view. For inline suggestions, press Alt+F2 to read the full ghost text, then Ctrl+/ to insert it directly from the Accessible View. Accessible View renders Chat responses as a static, scrollable pane -- easier to read at high zoom than the streaming Chat panel. Code blocks in Accessible View preserve indentation and syntax -- pair with a high-contrast theme for maximum readability. Ctrl+Home jumps to the start of the response; Ctrl+End to the end -- useful for long multi-section outputs.

      +

      Alex: Keep the teaching thread moving. The reason 7. Configuration Scope Reference matters is that every Copilot customization file lives at one of three scopes. That gives the learner a simple foothold: VS Code combines all matching files from all scopes - it is additive, not winner-takes-all. The interface gets friendlier when it stops being a wall of controls and starts being a set of named places.

      -

      Jamie: Let's pause on Breakdown. What should a learner take away from it?

      -

      Alex: Start with Breakdown. There is something to understand, something to try, and something that proves the try worked.

      -

      Alex: The practical takeaway is this. <<<<<<< HEAD - the start of YOUR version (HEAD = "the branch you are currently on"). ======= - the dividing line between the two versions. branch-name - the end of the INCOMING version (from the branch being merged in).

      -

      Jamie: Let's pause on After two students both added a shortcut to the same table row. What should a learner take away from it?

      -

      Alex: Start with After two students both added a shortcut to the same table row. There is something to understand, something to try, and something that proves the try worked.

      -

      Alex: Treat examples as spoken recipes, not decorations. You may hear something like add-nvda-shortcut. Read the command, understand what it changes, then run it only when the repository state matches the lesson.

      -

      Jamie: Let's pause on Resolution options. What should a learner take away from it?

      -

      Alex: Start with Resolution options. There is something to understand, something to try, and something that proves the try worked.

      -

      Alex: First, keep your version: add only Insert+F5. Then, keep their version: add only Insert+F7. After that, keep both rows: add both shortcuts to the table (often the right answer when two students added different valid shortcuts). It is like walking a hallway with named doors: read the sign, enter the right room, then confirm where you landed.

      +

      Jamie: Let's pause on Workspace (Repository) - Team-Shared. What should a learner take away from it?

      +

      Alex: Start with Workspace (Repository) - Team-Shared: Files committed to your repository. The next useful detail is this: Everyone who clones the repo gets them.

      +

      Alex: Keep the teaching thread moving. Here is the plain-English version of User / Personal - Follows You Across Workspaces. Files in your VS Code profile folder. Put another way, available in every workspace you open.

      +

      Jamie: Let's pause on Organization - GitHub-Configured (Enterprise/Teams). What should a learner take away from it?

      +

      Alex: This is where Organization - GitHub-Configured (Enterprise/Teams) becomes real: configured by administrators in GitHub organization settings. That matters in practice: Automatically applied to all organization members.

      +

      Alex: That shows up in the workshop in a few specific ways. Enable discovery: github.copilot.chat.organizationInstructions.enabled: true. Lowest priority - workspace and user instructions override when there is a conflict.

      -

      Alex: Keep the teaching thread moving. Start with Learning Cards: Conflict Markers. There is something to understand, something to try, and something that proves the try worked.

      -

      Alex: The practical takeaway is this. Conflict markers are three lines: branch-name; your screen reader may spell out each character individually. Everything between is the INCOMING version. After resolving, search the file for <<<< using Ctrl+F to verify no markers remain; any leftover markers will break the file. In GitHub's conflict editor, each version is highlighted with a different background color (typically green for yours, blue for incoming); high-contrast themes use bolder system colors. The three marker lines ( ) span the full width of the editor; look for rows that contain only repeated symbols. After resolving, zoom in on the edited area and confirm the marker lines are completely deleted, not just partially removed.

      -

      Jamie: Let's pause on Resolving Conflicts on GitHub (Web Editor). What should a learner take away from it?

      -

      Alex: Start with Resolving Conflicts on GitHub (Web Editor): GitHub has a built-in conflict editor that you can use without any local tools.

      -

      Jamie: Let's pause on Step-by-step: GitHub Conflict Editor. What should a learner take away from it?

      -

      Alex: Here is the plain-English version of Step-by-step: GitHub Conflict Editor. Low vision users (zoom, high contrast). Put another way, increase your browser's minimum font size (Settings, Appearance, Font size) for a more comfortable editing experience in the conflict editor. It is like learning a transit route. The names of the stops matter because they tell you whether you are still going the right direction.

      -

      Alex: The practical takeaway is this. <<<<<<< HEAD marks the start of your version. ======= is the dividing line. branch-name marks the end of the incoming version.

      -

      Alex: First, click Resolve conflicts on the PR Conversation tab. Then, GitHub opens a full-page text editor showing each conflicted file. After that, the conflict markers are highlighted - everything between is the incoming version. Finally, edit the content directly: delete the lines you don't want, including the three marker lines ( ). Treat it like a recipe: do not add the next ingredient until the previous one is actually in the bowl.

      -

      Jamie: Before we leave Step-by-step: GitHub Conflict Editor, what is the practical point?

      -

      Alex: First, when the file looks correct, click Mark as resolved (top-right of the file). Then, if there are multiple conflicted files, a file list on the left lets you jump between them. After that, after all files are resolved, click Commit merge. Finally, open the conflict editor from the Resolve conflicts button on the PR Conversation tab. It is a checklist, but a meaningful one: every item creates evidence that the next step is safe.

      +

      Alex: Keep the teaching thread moving. Keep the learner anchored in 8. Instruction Priority and Conflicts. When multiple instruction sources give conflicting guidance, VS Code uses this priority order. This is the part to say slowly: This priority applies to conflicts. A good GitHub workflow is like a well-run meeting: everyone knows the topic, the next action, and who has the floor.

      +

      Jamie: Let's pause on How Instructions Are Combined. What should a learner take away from it?

      +

      Alex: The reason How Instructions Are Combined matters is that result: Copilot follows TypeScript strict mode (from workspace), British English (from org), AND the Z-spelling override (from user, which overrides the org instruction on that specific point).

      +

      Alex: For a learner, the useful signals are these. Organization: "Use British English spellings". Workspace: "Use TypeScript strict mode". User: "Use British English spellings - but use Z spellings (organize, not organise) for technical terms".

      +

      Alex: Keep the teaching thread moving. Start with Priority Within the Same Scope: Within a single scope (e.g., workspace), all matching instructions files are combined with no inherent priority. The next useful detail is this: If two workspace-level.instructions.md files contradict each other, the behavior is undefined - avoid conflicting workspace instructions.

      -

      Jamie: Let's pause on What it looks like in the editor. What should a learner take away from it?

      -

      Alex: This is where What it looks like in the editor becomes real: when the conflict editor opens, your screen reader will announce a text editor. That matters in practice: In Focus Mode, navigate with arrow keys.

      -

      Alex: Keep the teaching thread moving. Start with Learning Cards: Resolving Conflicts on GitHub. There is something to understand, something to try, and something that proves the try worked.

      -

      Alex: The practical takeaway is this. 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. 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.

      -

      Jamie: Where is the promise of the workshop, underneath all the logistics?

      -

      Alex: The reason Resolving Conflicts in VS Code (Day 2) matters is that see also: Appendix E: Advanced Git covers rebase, cherry-pick, and other advanced conflict resolution strategies. That gives the learner a simple foothold: VS Code has excellent merge conflict tooling with full screen reader support.

      +

      Jamie: Let's pause on Create any new customization file. What should a learner take away from it?

      +

      Alex: Here is the plain-English version of Create any new customization file. Ctrl+Shift+P → "Chat: New Instructions File" (or "New Prompt File", "New Agent File").

      +

      Alex: Keep the teaching thread moving. This is where 10. VS Code Settings Reference becomes real: all Copilot customization-related settings. That matters in practice: Set in VS Code Settings (Ctrl+,) or settings.json. The workshop is closer to rehearsal than lecture. You hear the move, try the move, and then check what changed.

      +

      Jamie: Let's pause on Deprecated Task-Specific Instructions. What should a learner take away from it?

      +

      Alex: Keep the learner anchored in Deprecated Task-Specific Instructions. Prefer file-based instructions over these settings for new work. This is the part to say slowly: Each accepts an array with items: { "text": "." } (inline) or { "file": "relative/path" } (from file).

      -

      Jamie: Let's pause on VS Code merge conflict actions. What should a learner take away from it?

      -

      Alex: Start with VS Code merge conflict actions: When your cursor is on a conflict region, VS Code shows CodeLens action links above the conflict block in the editor. The next useful detail is this: The conflict markers disappear and your chosen content remains. Think of it like entering a new building: first you find the lobby, then the room, then the door you actually need.

      -

      Alex: The practical takeaway is this. 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.

      -

      Alex: First, open the conflicted file. Then, press ↓ to navigate to a conflict marker (<<<<<<<). After that, the CodeLens links appear above - press Tab to reach them. Finally, press Enter on your chosen action. Think of it as a rail line: each stop confirms you are still on the right route before the next one.

      -

      Jamie: Before we leave VS Code merge conflict actions, what is the practical point?

      -

      Alex: First, save the file (Ctrl+S). Then, stage the resolved file: Ctrl+Shift+G → find the file → Stage changes. After that, commit the merge. Finally, vO+Down or arrow keys to navigate to a conflict marker (<<<<<<<). Treat it like a recipe: do not add the next ingredient until the previous one is actually in the bowl.

      -

      Jamie: Let's pause on Ask for help - it's normal. What should a learner take away from it?

      -

      Alex: Here is the plain-English version of Ask for help - it's normal. If you are unsure which version to keep.

      -

      Alex: First, 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?". Then, tag the PR author or a maintainer with @username. Treat it like a recipe: do not add the next ingredient until the previous one is actually in the bowl.

      -

      Jamie: Let's pause on Abandon and start fresh (nuclear option). What should a learner take away from it?

      -

      Alex: This is where Abandon and start fresh (nuclear option) becomes real: if a conflict is severe (the branch diverged a lot from main). That matters in practice: This is legitimate - not a failure.

      -

      Alex: First, close the PR without merging. Then, start a new branch from the latest main. After that, apply only your intended changes to the new branch. Finally, open a new PR. It is a checklist, but a meaningful one: every item creates evidence that the next step is safe.

      +

      Jamie: What is the ordered workflow?

      +

      Alex: The reason Settings Sync matters is that to sync your personal prompts, instructions, and agents across devices. That gives the learner a simple foothold: your personal.instructions.md,.agent.md, and.prompt.md files will sync to all signed-in VS Code instances.

      +

      Alex: First, ctrl+Shift+P → "Settings Sync: Turn On". Then, ctrl+Shift+P → "Settings Sync: Configure". After that, check "Prompts and Instructions". The rhythm is simple: orient, act, verify, then continue.

      +

      Jamie: Give me the sequence, because order matters here.

      +

      Alex: Start with View All Loaded Customizations: To see which instruction files, agents, prompts, and skills are currently loaded - and check for errors.

      +

      Alex: The practical takeaway is this. All agents found and whether they loaded successfully. All prompt/instruction files and their source (workspace vs user vs organization). All skills and their discovery status. Any parse errors or invalid frontmatter.

      +

      Alex: First, configure Chat Gear: Click the gear () icon in the Copilot Chat header → "Diagnostics". Then, right-click method: Right-click in the Chat view → "Diagnostics". Think of it as a rail line: each stop confirms you are still on the right route before the next one.

      +

      Jamie: What does the learner do first, second, and then after that?

      +

      Alex: Start with copilot-instructions.md not being followed. There is something to understand, something to try, and something that proves the try worked.

      +

      Alex: First, confirm the file is at exactly.github/copilot-instructions.md (relative to workspace root). Then, check the file is plain Markdown with no frontmatter syntax errors. After that, open Diagnostics to confirm it appears in the loaded files list. Finally, some instructions work better with specific phrasing; use imperative mood ("Always use."). Treat it like a recipe: do not add the next ingredient until the previous one is actually in the bowl.

      -

      Jamie: What do you want them to do when the plan breaks?

      -

      Alex: Start with Learning Cards: When You Feel Stuck. There is something to understand, something to try, and something that proves the try worked.

      -

      Alex: The practical takeaway is this. 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. 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.

      -

      Jamie: Let's pause on Reading a Conflict Message from Git (Command Line Reference). What should a learner take away from it?

      -

      Alex: The reason Reading a Conflict Message from Git (Command Line Reference) matters is that if you work locally, git merge or git pull will say. That gives the learner a simple foothold: the conflict markers are inserted into the file by Git - open the file and follow the steps above. The interface gets friendlier when it stops being a wall of controls and starts being a set of named places.

      -

      Alex: Treat examples as spoken recipes, not decorations. You may hear something like 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,. 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. Read the command, understand what it changes, then run it only when the repository state matches the lesson.

      -

      Jamie: Let's pause on Try It: Read a Conflict (Without Fear). What should a learner take away from it?

      -

      Alex: Start with Try It: Read a Conflict (Without Fear): Time: 2 minutes What you need: Any text editor or just read below. The next useful detail is this: The goal is not to resolve it - just to understand what you're hearing.

      -

      Alex: First, what does your branch say? (The text between <<<<<<< HEAD and =======). Then, what does the other branch say? (The text between ======= and ). After that, which version would you keep, and why? Think of it as a rail line: each stop confirms you are still on the right route before the next one.

      +

      Jamie: Turn that into a path someone can follow.

      +

      Alex: Start with.instructions.md file not loading automatically. There is something to understand, something to try, and something that proves the try worked.

      +

      Alex: First, verify chat.includeApplyingInstructions is not set to false. Then, check the applyTo glob - test with " " temporarily to confirm the file loads at all. After that, confirm the file is in.github/instructions/ or a folder listed in chat.instructionsFilesLocations. Finally, file extension must be.instructions.md exactly - not.md, not.instruction.md. It is a checklist, but a meaningful one: every item creates evidence that the next step is safe.

      +

      Jamie: Let's pause on Custom agent (@agent-name) not appearing. What should a learner take away from it?

      +

      Alex: Start with Custom agent (@agent-name) not appearing. There is something to understand, something to try, and something that proves the try worked.

      +

      Alex: First, file must be named.agent.md and placed in.github/agents/. Then, check YAML frontmatter for syntax errors - use a YAML validator. After that, confirm user-invocable is not set to false (which hides it from the picker). Finally, run Ctrl+Shift+P → "Reload Window" after any changes to agent files. It is like walking a hallway with named doors: read the sign, enter the right room, then confirm where you landed.

      +

      Jamie: Let's pause on Slash command (/command) not appearing. What should a learner take away from it?

      +

      Alex: Start with Slash command (/command) not appearing. There is something to understand, something to try, and something that proves the try worked.

      +

      Alex: First, file must be at.github/prompts/.prompt.md. Then, extension must be.prompt.md exactly. After that, reload VS Code: Ctrl+Shift+P → "Reload Window". The rhythm is simple: orient, act, verify, then continue.

      -

      Jamie: What is the final checkpoint?

      -

      Alex: You should be able to point to the evidence, explain the action, and describe what you would do next if this were a real open source project. If you can teach the move back, you have learned it.

      -

      Jamie: And if they get stuck?

      -

      Alex: Read the latest message, not the loudest worry. Check the issue, the branch, the pull request, the status check, or the bot comment. Then ask for help with those facts in hand. That is how professionals collaborate.

      -
      - +

      Jamie: Let's pause on Instructions from different files conflicting. What should a learner take away from it?

      +

      Alex: Start with Instructions from different files conflicting. There is something to understand, something to try, and something that proves the try worked.

      +

      Alex: First, open Diagnostics to see all loaded instruction files. Then, remove or edit conflicting instructions - they are not automatically de-duplicated. After that, user-level instructions override workspace instructions for the same topic. Think of it as a rail line: each stop confirms you are still on the right route before the next one.

      +

      Jamie: Let's pause on chat.instructionsFilesLocations not working. What should a learner take away from it?

      +

      Alex: Start with chat.instructionsFilesLocations not working. There is something to understand, something to try, and something that proves the try worked.

      +

      Alex: The practical takeaway is this. Path must be a folder path, not a file path. Use forward slashes or escaped backslashes. Relative paths are relative to the workspace root.

      +

      Alex: Keep the teaching thread moving. This is where 12. Screen Reader Workflow - Official Guide becomes real: source: accessibility.github.com/documentation/guide/github-copilot-vsc/ Contributors: @mlama007, zersiax Community: GitHub Accessibility Discussions.

      -

      Challenge 08: The Culture Layer

      -

      Reflection, community norms, issue triage, labels, and respectful communication.

      -
      -Read Transcript - Challenge 08: The Culture Layer - -

      Transcript

      -

      Alex: Welcome to Challenge Coach: The Culture Layer. I am Alex. Before you do the task, we are going to make the skill feel concrete enough to practice.

      -

      Jamie: And I am Jamie. I will keep asking what the learner should do, what evidence counts, and how to recover if the page does something unexpected.

      +

      Jamie: Let's pause on Prerequisites. What should a learner take away from it?

      +

      Alex: Start with Prerequisites. There is something to understand, something to try, and something that proves the try worked.

      +

      Alex: The practical takeaway is this. VS Code with GitHub Copilot Chat extension installed. A GitHub account with Copilot access (Free tier or paid). A screen reader (NVDA recommended for this guide).

      +

      Jamie: Let's pause on Step 1: Enable VS Code Screen Reader Mode. What should a learner take away from it?

      +

      Alex: The reason Step 1: Enable VS Code Screen Reader Mode matters is that when Screen Reader Mode is on, VS Code changes how it announces suggestions (full text instead of streaming), adjusts live regions, and enables accessible navigation patterns throughout the editor. The interface gets friendlier when it stops being a wall of controls and starts being a set of named places.

      +

      Alex: First, press Shift+Alt+F1 to toggle Screen Reader Accessibility Mode. Then, or use Command Palette: Ctrl+Shift+P → "Toggle Screen Reader Accessibility Mode". After that, VS Code announces: "Screen Reader Accessibility Mode enabled". The rhythm is simple: orient, act, verify, then continue.

      +

      Jamie: Let's pause on Step 2: Configure Accessibility Signals (Optional but Recommended). What should a learner take away from it?

      +

      Alex: Start with Step 2: Configure Accessibility Signals (Optional but Recommended): Recommended JSON config for Copilot accessibility signals.

      +

      Alex: First, open Settings: Ctrl+,. Then, search "accessibility signals". After that, enable the Copilot-specific signals. Think of it as a rail line: each stop confirms you are still on the right route before the next one.

      -

      Alex: The skill focus is Reflection, community norms, issue triage, labels, and respectful communication. This is rehearsal for real contribution, so the evidence matters because it proves the move happened.

      -

      Jamie: So the challenge has to leave the learner with both confidence and a trail of evidence.

      -

      Alex: Exactly. Evidence is not busywork. It is how a learner, a facilitator, and a future maintainer can understand what changed and why.

      +

      Alex: Keep the teaching thread moving. Here is the plain-English version of Step 3: Official Shortcut Table (from accessibility.github.com). This is the complete table of Copilot screen reader shortcuts as published by the GitHub Accessibility team.

      +

      Jamie: How do you keep commands from becoming magic words?

      +

      Alex: This is where The screen reader-optimized workflow for every inline suggestion becomes real: this workflow avoids the streaming announcement problem (where suggestions are read out in fragments as tokens arrive) and gives you full, uninterrupted access to the suggestion text before committing.

      +

      Alex: Treat examples as spoken recipes, not decorations. You may hear something like Type your code or documentation; 2. Copilot generates a suggestion (audio cue sounds if enabled); 3. DO NOT press Tab immediately; 4. Press Alt+F2 - Accessible View opens with the full suggestion text; 5. Read the suggestion at your own pace with Arrow keys. Read the command, understand what it changes, then run it only when the repository state matches the lesson.

      +

      Jamie: Let's pause on Step 5: Recommended Workflow for Chat Responses. What should a learner take away from it?

      +

      Alex: Start with Step 5: Recommended Workflow for Chat Responses. There is something to understand, something to try, and something that proves the try worked.

      +

      Alex: Treat examples as spoken recipes, not decorations. You may hear something like Open Chat: Ctrl+Shift+I; 2. Type your prompt, press Ctrl+Enter to send; 3. Press Alt+F2 - Accessible View opens immediately; the response streams live into it; 4. Navigate with Arrow keys - no streaming noise, follow along in real-time; 5. Headings, code. Read the command, understand what it changes, then run it only when the repository state matches the lesson.

      -

      Jamie: What makes this practice feel low-stakes but still real?

      -

      Alex: Start with Challenge 8: The Culture Layer: What you will do: Reflect on what makes open source communities welcoming, then practice triaging an issue by adding labels.

      -

      Alex: The next layer is this. Here is the plain-English version of Reflection. Think about your experience so far in this workshop. Put another way, answer one or more of these questions. It is like learning a transit route. The names of the stops matter because they tell you whether you are still going the right direction.

      -

      Alex: The practical anchors are these. What made you feel welcome when you arrived? What would make the learning-room more accessible or inclusive? What is one thing you learned from a peer-simulation issue, PR, or classmate today?

      -

      Jamie: What does the learner do first, second, and then after that?

      -

      Alex: This is where Triage an issue becomes real: I triaged issue XX by adding the label " ".

      -

      Alex: That shows up in the workshop in a few specific ways. bug -- something is broken. enhancement -- a suggestion for improvement. documentation -- related to docs. good first issue -- easy for newcomers.

      -

      Alex: First, go to the Issues tab and find an open issue. The peer-simulation issue is a good choice; if you have real buddy access, you may use a classmate's issue. Then, add at least one label that describes the issue. Some options. After that, if you think the issue needs a specific person's attention, leave a comment tagging them. It is a checklist, but a meaningful one: every item creates evidence that the next step is safe.

      -

      Alex: A solid issue habit is to read the title, the body, and the timeline before acting. You are listening for the requested action, the missing evidence, and the person who needs a response.

      +

      Jamie: Let's pause on Reading the Suggestions Panel (Ctrl+Enter). What should a learner take away from it?

      +

      Alex: The reason Reading the Suggestions Panel (Ctrl+Enter) matters is that pressing Ctrl+Enter opens a Suggestions Panel - a separate editor tab that shows up to 10 alternative suggestions simultaneously. That gives the learner a simple foothold: this is useful when the default suggestion isn't quite right and you want to compare options.

      +

      Alex: Treat examples as spoken recipes, not decorations. You may hear something like Ctrl+Enter - opens "GitHub Copilot" editor tab; 2. Screen Reader Mode is active: navigate with Browse Mode; 3. H key to navigate headings (each suggestion may be under a heading); 4. Press Alt+F2 on a focused suggestion to read it in Accessible View; 5. Tab to. Read the command, understand what it changes, then run it only when the repository state matches the lesson.

      +

      Alex: Keep the teaching thread moving. Start with Learning Cards: Screen Reader Copilot Workflow. There is something to understand, something to try, and something that proves the try worked.

      +

      Alex: The practical takeaway is this. The golden rule: never accept a suggestion with Tab before reviewing it -- press Alt+F2 first, read it, then Ctrl+/ to insert. Enable the four Copilot audio signals (inline suggestion, request sent, response pending, response received) for non-verbal status awareness. Ctrl+Enter opens a Suggestions Panel with up to 10 alternatives -- navigate with H for headings, then Tab to the Accept button. Inline ghost text is typically rendered in a muted color -- if hard to see, rely on the lineHasInlineSuggestion audio signal instead. The Suggestions Panel (Ctrl+Enter) shows alternatives in a full editor tab at your current font size and theme. Chat responses are easier to read in Accessible View than in the streaming panel, especially at high zoom.

      +

      Jamie: Let's pause on 13. awesome-copilot - Plugin Ecosystem. What should a learner take away from it?

      +

      Alex: Here is the plain-English version of 13. awesome-copilot - Plugin Ecosystem. awesome-copilot is a GitHub repository (github/awesome-copilot) - not a VS Code Marketplace extension. Put another way, it is GitHub's curated ecosystem of Copilot plugins, prompts, instructions, agents, skills, and hooks that can be shared and discovered by anyone.

      -

      Alex: Now bring the learner back to the room. Keep the learner anchored in Peer simulation check. Share your reflection in the peer-simulation issue or with your buddy if you have one. This is the part to say slowly: Different perspectives make the community richer.

      -

      Jamie: What would you say to someone who is already bracing for this to be too much?

      -

      Alex: The reason Example reflection comment matters is that reading the CODE OF CONDUCT.md and CONTRIBUTING.md files helped me understand that open source projects are communities, not just code. That gives the learner a simple foothold: the contributing guide made it clear that you do not need to be an expert to participate -- filing a good issue is a contribution.

      -

      Alex: The useful habit is simple: orient first, act second, verify third. That pause before acting is part of the work.

      -

      Alex: That matters because of the next idea. Start with Example triage recommendation: If your challenge asked you to evaluate an issue and recommend a label. The next useful detail is this: Issue: "The welcome page loads slowly on mobile" Recommended label: bug Justification: This describes unexpected behavior (slow loading) that affects the user experience. Think of it like entering a new building: first you find the lobby, then the room, then the door you actually need.

      +

      Alex: Keep the teaching thread moving. This is where Repository Structure becomes real: lLM discovery: https://github.github.io/awesome-copilot/llms.txt - a machine-readable index of all available resources. The workshop is closer to rehearsal than lecture. You hear the move, try the move, and then check what changed.

      +

      Jamie: Let's pause on The /plugin Command - Browse and Install from Chat. What should a learner take away from it?

      +

      Alex: Keep the learner anchored in The /plugin Command - Browse and Install from Chat. The easiest way to explore awesome-copilot from VS Code.

      +

      Alex: First, open Copilot Chat (Ctrl+Shift+I). Then, type /plugin and press Enter. After that, Copilot Chat opens an interactive plugin marketplace browser. Finally, browse plugins by category, read descriptions, and install with a single command. It is like walking a hallway with named doors: read the sign, enter the right room, then confirm where you landed.

      +

      Jamie: Let's pause on CLI Plugin Installation. What should a learner take away from it?

      +

      Alex: The reason CLI Plugin Installation matters is that from any terminal with GitHub CLI (gh) installed.

      +

      Alex: Treat examples as spoken recipes, not decorations. You may hear something like Browse the marketplace; gh copilot plugin marketplace list; Add the awesome-copilot collection; gh copilot plugin marketplace add github/awesome-copilot; Install a specific plugin; gh copilot plugin install @awesome-copilot/accessibility-toolkit; List what you. Read the command, understand what it changes, then run it only when the repository state matches the lesson.

      -

      Jamie: Okay, set the room for us. What are we walking into?

      -

      Alex: Start with Alternate approaches. There is something to understand, something to try, and something that proves the try worked.

      -

      Alex: Here is what that changes in practice. Focus on CODE OF CONDUCT.md and what it means for inclusive collaboration. Focus on CONTRIBUTING.md and what you learned about the contribution process. Compare this project's guidelines to another open source project you have seen.

      -

      Alex: A solid pull request habit is to separate three questions: what changed, why it changed, and what still needs review. That keeps the conversation useful instead of noisy.

      -

      Alex: This is where the talk moves from concept to action. This is where What matters becomes real: the learning objective is understanding that open source has cultural norms, not just technical ones. That matters in practice: Any thoughtful reflection that shows engagement with the governance and contribution documents is a success.

      -

      Jamie: What is the one idea that makes the next few steps less mysterious?

      -

      Alex: Keep the learner anchored in How to Be an Effective and Respectful Open Source Contributor. Technical skills get your code into a project. This is the part to say slowly: Communication skills keep you welcomed in the community.

      -
      -

      Alex: Before the learner moves on. The reason Workshop Recommendation (Chapter 8) matters is that chapter 8 is a communication and culture chapter. The interface gets friendlier when it stops being a wall of controls and starts being a set of named places.

      -

      Alex: That becomes easier when you listen for these cues. There are 1 guided reflection (no bot grading). Automation check: none - communication quality is too subjective for fair automated scoring. The evidence is structured reflection comment on your assigned challenge issue. The pattern is read, reflect, commit to one behavior.

      -

      Jamie: Give me the sequence, because order matters here.

      -

      Alex: Start with Chapter 8 Challenge Set. There is something to understand, something to try, and something that proves the try worked.

      -

      Alex: First, guided reflection - read the chapter, then post a short reflection comment committing to three specific collaboration behaviors. Think of it as a rail line: each stop confirms you are still on the right route before the next one.

      -

      Jamie: How would you walk the room through that step by step?

      -

      Alex: Here is the plain-English version of Challenge 8.1 Step-by-Step: Guided Reflection. Identify three concrete communication behaviors you will practice during the rest of the workshop. Put another way, your assigned Chapter 8 challenge issue in your Learning Room repository on GitHub.com.

      -

      Alex: For a learner, the useful signals are these. 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.".

      -

      Alex: First, read through the chapter content below, paying attention to the sections on GitHub Flow, constructive feedback, and asking for help. Then, as you read, think about one situation from Day 1 where communication helped (or could have helped) you. After that, open your assigned Chapter 8 challenge issue (the one titled "Chapter 8.1: Guided Reflection (@yourname)"). Finally, scroll to the comment box at the bottom of the issue. Treat it like a recipe: do not add the next ingredient until the previous one is actually in the bowl.

      -

      Jamie: Turn that into a path someone can follow.

      -

      Alex: First, post a reflection comment using this format. Then, for each prompt, write one specific, actionable sentence - not a vague goal. After that, activate the Comment button (or press Ctrl+Enter). It is a checklist, but a meaningful one: every item creates evidence that the next step is safe.

      +

      Jamie: Let's pause on MCP Server Integration (Docker required). What should a learner take away from it?

      +

      Alex: Start with MCP Server Integration (Docker required): awesome-copilot also ships as an MCP (Model Context Protocol) Server - a Docker-based tool server that extends Copilot with additional capabilities beyond file-based customizations. The next useful detail is this: Install in VS Code by clicking the button at https://aka.ms/awesome-copilot/mcp/vscode, or add manually to settings.json.

      +

      Alex: Treat examples as spoken recipes, not decorations. You may hear something like {; "mcp": {; "servers": {; "awesome-copilot": {; "type": "stdio",; "command": "docker",; "args": [; "run", "-i", "--rm",; "ghcr.io/github/awesome-copilot-mcp:latest"; ]; }; }; }; }. Read the command, understand what it changes, then run it only when the repository state matches the lesson.

      +

      Alex: Keep the teaching thread moving. Here is the plain-English version of 14. GitHub Agentic Workflows - Agents in the Cloud. Status: Technical Preview - GitHub Agentic Workflows entered technical preview on February 13, 2026. Put another way, as of May 2026 the feature remains in active development and preview; changes to the API and workflow format are ongoing. It is like learning a transit route. The names of the stops matter because they tell you whether you are still going the right direction.

      +

      Jamie: Let's pause on What This Enables. What should a learner take away from it?

      +

      Alex: This is where What This Enables becomes real: browse 50+ community-built workflows at Peli's Agent Factory.

      -

      Jamie: How do these exercises create confidence instead of pressure?

      -

      Alex: This is where Completing Chapter 8: Submit Your Evidence becomes real: the reflection comment itself is your evidence. That matters in practice: The facilitator reviews your comment for specificity.

      -

      Alex: That connects to another useful point. Start with Expected Outcomes. There is something to understand, something to try, and something that proves the try worked.

      -

      Alex: The parts worth keeping in working memory are these. 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.

      -

      Jamie: What is the ordered workflow?

      -

      Alex: Start with If You Get Stuck. There is something to understand, something to try, and something that proves the try worked.

      -

      Alex: First, use one simple sentence per prompt - do not overthink it. Then, focus on one real behavior you can start doing today, not an abstract principle. After that, if writing feels hard, draft bullet points first in a text editor, then paste into the comment. Finally, look at the "Giving Feedback" and "Asking for Help" sections in this chapter for concrete examples. The rhythm is simple: orient, act, verify, then continue.

      -

      Jamie: Let's pause on If You Get Stuck. What should a learner take away from it?

      -

      Alex: First, ask facilitator for one example response and adapt it to your own words. Then, finished but not sure you did it right? Compare your work against the Challenge 8 reference solution. Think of it as a rail line: each stop confirms you are still on the right route before the next one.

      +

      Alex: Keep the teaching thread moving. Keep the learner anchored in How It Works. The gh aw CLI (a gh extension) compiles.md workflow files into.lock.yml GitHub Actions workflows. This is the part to say slowly: The AI agent (GitHub Copilot, Claude, or OpenAI Codex) reads your repository context and the natural language instructions, then performs the task using the GitHub MCP Server and other available tools.

      +

      Jamie: Let's pause on Workflow Format - Markdown with Frontmatter. What should a learner take away from it?

      +

      Alex: The reason Workflow Format - Markdown with Frontmatter matters is that unlike standard GitHub Actions (YAML), agentic workflows are Markdown files. That gives the learner a simple foothold: the body is natural language - describe what you want the AI agent to do.

      +

      Alex: Keep the teaching thread moving. Start with Security Model - "Safe Outputs": Workflows run read-only by default with sandboxed execution, network isolation, and SHA-pinned dependencies. The next useful detail is this: Write operations require explicit declaration in safe-outputs - a set of pre-approved, sanitized GitHub operations. Think of it like entering a new building: first you find the lobby, then the room, then the door you actually need.

      -

      Alex: Here is the practical turn. Start with Learning Moment: Technical quality and communication quality work together. The next useful detail is this: Respectful, clear communication helps good code get merged faster.

      -

      Jamie: Let's pause on Learning Pattern Used in This Chapter. What should a learner take away from it?

      -

      Alex: Start with Learning Pattern Used in This Chapter. There is something to understand, something to try, and something that proves the try worked.

      -

      Alex: First, read and absorb community norms (not just rules, but reasons). Then, reflect on personal experience (what worked, what was hard). After that, commit to specific behaviors in writing (public accountability). Finally, apply those behaviors in upcoming chapters (reviews, comments, PRs). Treat it like a recipe: do not add the next ingredient until the previous one is actually in the bowl.

      -

      Alex: Keep the thread going. This is where GitHub Flow - The Standard Contribution Workflow becomes real: before diving into communication norms, it helps to understand the workflow that gives all of those conversations their context. That matters in practice: GitHub Flow is the lightweight branching model recommended for open source contribution. The workshop is closer to rehearsal than lecture. You hear the move, try the move, and then check what changed.

      +

      Jamie: Let's pause on Getting Started with gh aw. What should a learner take away from it?

      +

      Alex: Start with Getting Started with gh aw. There is something to understand, something to try, and something that proves the try worked.

      +

      Alex: Treat examples as spoken recipes, not decorations. You may hear something like Install the CLI extension; gh extension install github/gh-aw; Create a new workflow interactively (from github.com or VS Code also works); gh aw create; Compile your Markdown workflow to a GitHub Actions.lock.yml; gh aw. Read the command, understand what it changes, then run it only when the repository state matches the lesson.

      +

      Jamie: Let's pause on Monitoring Agentic Workflow Runs. What should a learner take away from it?

      +

      Alex: Start with Monitoring Agentic Workflow Runs. There is something to understand, something to try, and something that proves the try worked.

      +

      Alex: First, navigate to the Actions tab of your repository (D → Repository navigation → K to Actions). Then, find the workflow by name (h3 headings, navigate with 3). After that, press Enter to open a specific run. Finally, expand job steps to read the agent output log and any safe-outputs created. It is a checklist, but a meaningful one: every item creates evidence that the next step is safe.

      +

      Jamie: Let's pause on Resources. What should a learner take away from it?

      +

      Alex: Keep the learner anchored in Resources. Relationship to Accessibility Agents: Accessibility Agents agents (.agent.md files) are designed for interactive use inside VS Code. This is the part to say slowly: GitHub Agentic Workflows are a separate, cloud-native system that uses its own Markdown workflow format and the gh aw CLI - they are complementary tools, not the same mechanism.

      -

      Jamie: If I am listening before the workshop starts, what should settle in my mind first?

      -

      Alex: Start with Why This Model Works. There is something to understand, something to try, and something that proves the try worked.

      -

      Alex: These are the details that keep the idea from floating away. 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.

      -

      Alex: Another way to ground it. The reason GitHub Flow vs Git Flow matters is that you may encounter "Git Flow" (sometimes written "GitFlow") in older projects or enterprise environments. That gives the learner a simple foothold: this section explains what Git Flow is, how it differs from GitHub Flow, and why this workshop teaches GitHub Flow.

      -

      Alex: A solid Git habit is to know which branch you are on, what changed, and what confirmation you expect before you run the next command.

      -

      Jamie: Where do you want a learner to place their attention here?

      -

      Alex: Start with What Git Flow Is: Git Flow is a branching model published by Vincent Driessen in 2010. The next useful detail is this: It was designed for teams that ship versioned releases on a schedule (desktop software, mobile apps, embedded systems).

      +

      Alex: Keep the teaching thread moving. Start with Learning Cards: GitHub Agentic Workflows. There is something to understand, something to try, and something that proves the try worked.

      +

      Alex: The practical takeaway is this. Agentic workflow runs appear in the Actions tab of your repository -- navigate to Actions with T (tab bar), then use heading navigation (3) to jump between workflow run entries. Workflow files are Markdown (.md) not YAML -- the frontmatter at the top controls triggers and permissions; the body is natural language instructions the AI agent reads. The safe-outputs frontmatter property lists every write operation the agent is allowed to perform -- review this section carefully since it is the security boundary. The Actions tab lists workflow runs with status icons (green check, red X, yellow circle) -- at high zoom, also look for the text status label next to each run name. Workflow.md files use the same Markdown rendering as any other file in the repo -- edit them in VS Code with your preferred font size and theme. The gh aw compile command generates a.lock.yml file alongside your.md file -- both appear in the file explorer; the.lock.yml is auto-generated and should not be edited manually.

      +

      Jamie: Let's pause on Copilot Models. What should a learner take away from it?

      +

      Alex: Start with Copilot Models. There is something to understand, something to try, and something that proves the try worked.

      +

      Alex: The practical takeaway is this. Overview. How to Choose a Model. Complete Model Reference. Model Availability by Plan. Premium Requests and Cost Multipliers. Switching Models in VS Code.

      +

      Alex: Keep the teaching thread moving. Here is the plain-English version of 1. Overview. GitHub Copilot offers access to AI models from multiple providers including OpenAI, Anthropic, Google, and xAI. Put another way, the model you choose affects response quality, speed, and premium request consumption.

      -

      Jamie: Let's pause on How the Git Flow Cycle Works. What should a learner take away from it?

      -

      Alex: Start with How the Git Flow Cycle Works. There is something to understand, something to try, and something that proves the try worked.

      -

      Alex: First, developers branch feature/my-feature off develop and work there. Then, completed features merge back into develop via pull request. After that, when develop has enough features for a release, a release/1.2.0 branch is created. Finally, the release branch gets final testing, bug fixes, and version number updates. Treat it like a recipe: do not add the next ingredient until the previous one is actually in the bowl.

      -

      Jamie: Before we leave How the Git Flow Cycle Works, what is the practical point?

      -

      Alex: First, the release branch merges into main (tagged with the version) and back into develop. Then, if a critical bug is found in production, a hotfix/ branch is created from main, fixed, and merged into both main and develop. It is a checklist, but a meaningful one: every item creates evidence that the next step is safe.

      -

      Jamie: Give me the version that sounds like an instructor, not a manual.

      -

      Alex: This is where How GitHub Flow Differs becomes real: the following table compares GitHub Flow and Git Flow across key dimensions.

      -

      Alex: This is the part worth saying out loud. Start with When You Might See Git Flow. There is something to understand, something to try, and something that proves the try worked.

      -

      Alex: On the ground, that means a few things. 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.

      +

      Jamie: Let's pause on 2. How to Choose a Model. What should a learner take away from it?

      +

      Alex: This is where 2. How to Choose a Model becomes real: GitHub Docs organizes models by task. That matters in practice: Match your task to the right model to get the best results without unnecessary premium request cost.

      +

      Alex: Keep the teaching thread moving. Keep the learner anchored in General-Purpose Coding and Writing. For everyday tasks - code completions, explanations, refactoring, writing documentation. A good GitHub workflow is like a well-run meeting: everyone knows the topic, the next action, and who has the floor.

      +

      Jamie: How should someone ask for help in a way that gets them unstuck faster?

      +

      Alex: The reason Fast Help with Simple or Repetitive Tasks matters is that for quick answers, boilerplate generation, renaming, or lightweight explanations where speed matters.

      -

      Jamie: Where is the promise of the workshop, underneath all the logistics?

      -

      Alex: The reason Why This Workshop Uses GitHub Flow matters is that for open source contribution - especially at a hackathon or when contributing to web-based projects - GitHub Flow is what you want. That gives the learner a simple foothold: it is what GitHub itself uses and what most modern open source projects follow.

      -

      Alex: Hold that next to this. Start with The Unwritten Rule: One Thing Per Branch: A branch and its PR should do one thing. The next useful detail is this: If you are fixing a broken link and you notice a typo nearby, fix the typo in a separate branch and PR. Think of it like entering a new building: first you find the lobby, then the room, then the door you actually need.

      -

      Jamie: Let's pause on Learning Cards: GitHub Flow. What should a learner take away from it?

      -

      Alex: Start with Learning Cards: GitHub Flow. There is something to understand, something to try, and something that proves the try worked.

      -

      Alex: The room should hear these as checkpoints. 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). 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.

      +

      Alex: Keep the teaching thread moving. Start with Deep Reasoning and Debugging: For complex problems, architecture decisions, multi-file analysis, tricky bugs, and understanding unfamiliar codebases.

      +

      Jamie: Let's pause on Agentic Software Development. What should a learner take away from it?

      +

      Alex: Here is the plain-English version of Agentic Software Development. For autonomous coding tasks in Agent mode - when Copilot writes code, runs terminal commands, and iterates without step-by-step guidance from you.

      +

      Alex: Keep the teaching thread moving. This is where Working with Visuals becomes real: for tasks that involve images, screenshots, diagrams, or UI mockups - paste an image directly into the chat input. The workshop is closer to rehearsal than lecture. You hear the move, try the move, and then check what changed.

      -

      Alex: Keep the teaching thread moving. This is where Keeping Your Fork Up to Date becomes real: when you fork a repository, you get a snapshot of the project at that moment. That matters in practice: The original repository (called "upstream") continues to evolve.

      -

      Jamie: Let's pause on Why Sync Your Fork? What should a learner take away from it?

      -

      Alex: Start with Why Sync Your Fork? There is something to understand, something to try, and something that proves the try worked.

      -

      Alex: A few details make that real. 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.

      -

      Jamie: Let's pause on Method 1: GitHub Web Interface (Easiest). What should a learner take away from it?

      -

      Alex: The reason Method 1: GitHub Web Interface (Easiest) matters is that GitHub merges the upstream changes into your fork automatically. That gives the learner a simple foothold: screen reader users (NVDA / JAWS / VoiceOver). The interface gets friendlier when it stops being a wall of controls and starts being a set of named places.

      -

      Alex: First, navigate to your fork's main page: github.com/your-username/repo-name. Then, look for the sync indicator: "This branch is X commits behind upstream/main". After that, click the "Sync fork" button. Finally, click "Update branch". The rhythm is simple: orient, act, verify, then continue.

      -

      Jamie: Before we leave Method 1: GitHub Web Interface (Easiest), what is the practical point?

      -

      Alex: First, the sync button appears in the landmark that contains the branch selector. Then, press D to cycle through landmarks until you reach that region. After that, press B to cycle buttons until you hear "Sync fork" → press Enter. Finally, a dialog or page update presents "Update branch" - activate it. Think of it as a rail line: each stop confirms you are still on the right route before the next one.

      +

      Jamie: Let's pause on 3. Complete Model Reference. What should a learner take away from it?

      +

      Alex: Keep the learner anchored in 3. Complete Model Reference. Model availability changes frequently. This is the part to say slowly: Check GitHub's supported models page for the current list.

      +

      Alex: Keep the teaching thread moving. The reason 4. Model Availability by Plan matters is that GitHub Copilot plan details and billing models are actively evolving. That gives the learner a simple foothold: facilitators will provide current guidance at the workshop.

      +

      Jamie: Let's pause on Tips for managing premium request usage. What should a learner take away from it?

      +

      Alex: Start with Tips for managing premium request usage. There is something to understand, something to try, and something that proves the try worked.

      +

      Alex: The practical takeaway is this. Use GPT-4.1 or GPT-5 mini (both free) for everyday questions, quick explanations, and simple completions - they're fast and capable. Upgrade to Claude Sonnet or GPT-5.2 (1×) only when the task genuinely requires deeper reasoning. Save Claude Opus (3×) for the most demanding analyses - architecture decisions, complex debugging, sophisticated design review. Use Auto mode (see below) and let Copilot allocate model selection intelligently.

      -

      Jamie: There are a lot of tools in play. How do we keep that from feeling like a contest?

      -

      Alex: Start with Method 2: Git Command Line (VS Code Terminal): If you're working locally in VS Code.

      -

      Jamie: What should happen before anyone copies and runs it?

      -

      Alex: Start with One-time setup - add the upstream remote. There is something to understand, something to try, and something that proves the try worked.

      -

      Alex: Treat examples as spoken recipes, not decorations. You may hear something like git remote add upstream https://github.com/original-owner/repo-name.git; git remote -v Verify it was added. Read the command, understand what it changes, then run it only when the repository state matches the lesson.

      -

      Jamie: What should they understand before typing anything?

      -

      Alex: Start with Sync process. There is something to understand, something to try, and something that proves the try worked.

      -

      Alex: Treat examples as spoken recipes, not decorations. You may hear something like 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. Read the command, understand what it changes, then run it only when the repository state matches the lesson.

      +

      Jamie: Let's pause on In the Chat Panel. What should a learner take away from it?

      +

      Alex: Start with In the Chat Panel. There is something to understand, something to try, and something that proves the try worked.

      +

      Alex: First, open the Chat panel (Ctrl+Shift+I / Cmd+Shift+I). Then, at the bottom of the chat input area, you'll see the current model name as a button (e.g., "Auto" or "Claude Sonnet 4.6"). After that, activate the model picker button - this opens a dropdown list of available models. Finally, arrow through the list and press Enter to select a model. Treat it like a recipe: do not add the next ingredient until the previous one is actually in the bowl.

      +

      Jamie: Before we leave In the Chat Panel, what is the practical point?

      +

      Alex: First, for screen reader users: the chat input will announce the newly selected model after switching. It is a checklist, but a meaningful one: every item creates evidence that the next step is safe.

      +

      Jamie: Let's pause on In an Inline Chat Session. What should a learner take away from it?

      +

      Alex: Start with In an Inline Chat Session. There is something to understand, something to try, and something that proves the try worked.

      +

      Alex: First, open Inline Chat (Ctrl+I / Cmd+I). Then, the model picker appears in the inline chat toolbar. After that, same interaction: activate the model button to switch. It is a checklist, but a meaningful one: every item creates evidence that the next step is safe.

      +

      Alex: Keep the teaching thread moving. Keep the learner anchored in Keyboard Note for Screen Readers. In the Chat panel, the model picker button is near the bottom of the chat view. This is the part to say slowly: If you're having trouble locating it.

      +

      Alex: The practical takeaway is this. Tab through the bottom toolbar of the chat panel. Listen for the model name announced - it appears between the "Attach" button and the send button. Press Space or Enter to open the picker.

      -

      Alex: Keep the teaching thread moving. Start with When to sync. There is something to understand, something to try, and something that proves the try worked.

      -

      Alex: The practical takeaway is this. 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).

      -

      Jamie: Let's pause on Method 3: GitHub Desktop. What should a learner take away from it?

      -

      Alex: Start with Method 3: GitHub Desktop. There is something to understand, something to try, and something that proves the try worked.

      -

      Alex: First, open GitHub Desktop. Then, select Repository → Pull to get your fork's latest. After that, select Branch → Merge into Current Branch. Finally, choose upstream/main. The rhythm is simple: orient, act, verify, then continue.

      -

      Jamie: Before we leave Method 3: GitHub Desktop, what is the practical point?

      -

      Alex: First, push the changes to your fork on GitHub. Think of it as a rail line: each stop confirms you are still on the right route before the next one.

      -

      Alex: Keep the teaching thread moving. Start with Learning Cards: Keeping Your Fork Up to Date. There is something to understand, something to try, and something that proves the try worked.

      -

      Alex: The practical takeaway is this. 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. 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.

      +

      Jamie: Let's pause on 7. Auto Model Selection. What should a learner take away from it?

      +

      Alex: The reason 7. Auto Model Selection matters is that auto mode (the default) lets Copilot choose the best model based on the type of request. That gives the learner a simple foothold: it became generally available on December 10, 2025.

      +

      Alex: Keep the teaching thread moving. Start with How Auto works. There is something to understand, something to try, and something that proves the try worked.

      +

      Alex: The practical takeaway is this. For simple questions, Copilot routes to a faster, lighter model. For complex code generation or debugging, Copilot upgrades to a more capable model automatically. For agent tasks, Copilot selects an appropriate Codex model. You can see which model was used after each response.

      +

      Jamie: Let's pause on When to override Auto. What should a learner take away from it?

      +

      Alex: Here is the plain-English version of When to override Auto. To switch back to Auto from a specific model, re-open the model picker and select Auto at the top of the list.

      +

      Alex: The practical takeaway is this. You specifically need a model with certain capabilities (e.g., vision input with Claude Sonnet 4). You're managing premium request quotas and want to control costs. You've found a particular model gives better results for your specific workflow or domain. You're doing agentic work and want to explicitly select an agent-optimized Codex model (check current availability in the model picker).

      -

      Jamie: Let's pause on Writing Good Commit Messages. What should a learner take away from it?

      -

      Alex: Here is the plain-English version of Writing Good Commit Messages. Every commit you make includes a message describing what changed. Put another way, good commit messages make project history understandable months or years later.

      -

      Alex: Keep the teaching thread moving. This is where The First Line (Required) becomes real: this is the commit summary that appears in logs and GitHub's commit list. That matters in practice: Think of it as an email subject line. The workshop is closer to rehearsal than lecture. You hear the move, try the move, and then check what changed.

      -

      Alex: The practical takeaway is this. fix: - bug fix. feat: - new feature. docs: - documentation only. style: - formatting, no code change.

      -

      Jamie: What is the safe way to learn from that example?

      -

      Alex: Keep the learner anchored in The Body (Optional). If the summary isn't enough, add a body explaining. This is the part to say slowly: Leave a blank line between the summary and the body.

      -

      Alex: The practical takeaway is this. Why you made the change (more important than what). What trade-offs you considered. How the change affects behavior.

      -

      Alex: Treat examples as spoken recipes, not decorations. You may hear something like 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. Read the command, understand what it changes, then run it only when the repository state matches the lesson.

      +

      Alex: Keep the teaching thread moving. This is where 8. Models Retiring Soon becomes real: GitHub regularly updates the model roster. That matters in practice: Older model versions are retired when newer equivalents are available.

      +

      Jamie: Let's pause on Already retired (as of April 2026). What should a learner take away from it?

      +

      Alex: Keep the learner anchored in Already retired (as of April 2026). To stay current, watch the GitHub Copilot changelog - model additions and retirements are announced there.

      +

      Alex: The practical takeaway is this. Claude Sonnet 3.5, Claude Sonnet 3.7. Gemini 2.0 Flash. o1-mini, o3, o3-mini, o4-mini. Claude Opus 4.1. GPT-5 (base), GPT-5-Codex. GPT-5.3-Codex (removed from Student plan model picker, April 2026).

      +

      Alex: Keep the teaching thread moving. The reason Related Resources matters is that next: Appendix L: Agents Reference Back: Appendix J: Codespaces Teaching chapter: Chapter 16: GitHub Copilot. The interface gets friendlier when it stops being a wall of controls and starts being a set of named places.

      -

      Alex: Keep the teaching thread moving. The reason The Footer (Optional) matters is that when the commit is merged, GitHub automatically closes linked issues.

      -

      Jamie: Let's pause on Atomic Commits. What should a learner take away from it?

      -

      Alex: Start with Atomic Commits: Each commit should represent one logical change. The next useful detail is this: Don't bundle unrelated fixes into a single commit.

      -

      Alex: Keep the teaching thread moving. Start with Common mistakes to avoid. There is something to understand, something to try, and something that proves the try worked.

      -

      Alex: The practical takeaway is this. "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.

      +

      Jamie: What should people carry with them after this?

      +

      Alex: Carry the map. Know what page or tool you are in, know which action you are taking, and know what confirmation should follow. If the confirmation is missing, pause. That pause is not wasted time; it is professional judgment.

      +

      Jamie: That is a better way to say it than just follow the steps.

      +

      Alex: Right. Steps matter, but understanding wins. That is episode 41. Next in the series is episode 42, where we keep building the same contributor muscles.

      +
      +
      -

      Jamie: How do you keep commands from becoming magic words?

      -

      Alex: This is where Good commit messages in practice becomes real: when you make a habit of writing good commit messages, you build trust. That matters in practice: Maintainers see that you care about the project's long-term health, not just your immediate contribution.

      -

      Alex: Treat examples as spoken recipes, not decorations. You may hear something like 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. Read the command, understand what it changes, then run it only when the repository state matches the lesson.

      -

      Alex: Keep the teaching thread moving. Start with Learning Cards: Writing Good Commit Messages. There is something to understand, something to try, and something that proves the try worked.

      -

      Alex: The practical takeaway is this. 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. 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.

      -

      Jamie: Let's pause on The Nature of Open Source Communication. What should a learner take away from it?

      -

      Alex: The reason The Nature of Open Source Communication matters is that open source collaboration happens primarily in writing, asynchronously, in public. That gives the learner a simple foothold: understanding these three characteristics shapes everything about how we communicate.

      +

      44. Challenge 13: AI as Your Copilot

      +

      Using Copilot as a reviewed writing partner while keeping human judgment in charge.

      +

      Practice focus: Day 2 local workflow

      +

      Audio and transcript are being regenerated for this episode.

      +
      +Read Transcript - Challenge 13: AI as Your Copilot + +

      Transcript

      +

      Alex: This is Challenge Coach for AI as Your Copilot. I am Alex, and we are going to teach the move before asking you to prove it.

      +

      Jamie: And I am Jamie. I will translate the challenge into the practical questions learners actually have while doing it.

      -

      Alex: Keep the teaching thread moving. Start with In writing. There is something to understand, something to try, and something that proves the try worked.

      -

      Alex: The practical takeaway is this. 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.".

      -

      Jamie: Let's pause on Asynchronously. What should a learner take away from it?

      -

      Alex: Start with Asynchronously. There is something to understand, something to try, and something that proves the try worked.

      -

      Alex: The practical takeaway is this. 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.

      -

      Alex: Keep the teaching thread moving. Start with In public. There is something to understand, something to try, and something that proves the try worked.

      -

      Alex: The practical takeaway is this. 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.

      +

      Alex: Using Copilot as a reviewed writing partner while keeping human judgment in charge. That is the task layer. The teaching layer is understanding why the move belongs in a contributor workflow.

      +

      Jamie: So evidence is not just proof for the facilitator. It is part of how the learner understands the workflow.

      +

      Alex: Right. A good challenge produces something inspectable: a comment, issue, branch, commit, pull request, review, or clear note about what happened.

      -

      Jamie: What do you want them to do when the plan breaks?

      -

      Alex: Keep the learner anchored in The Anatomy of Helpful Feedback. Whether commenting on an issue, reviewing a PR, or responding to a question, effective feedback has a structure.

      -

      Alex: Keep the teaching thread moving. The reason 1. Acknowledge what's working matters is that before identifying problems, name what is good. That gives the learner a simple foothold: this is not flattery - it is accuracy. The interface gets friendlier when it stops being a wall of controls and starts being a set of named places.

      -

      Jamie: Let's pause on 2. Identify the specific concern. What should a learner take away from it?

      -

      Alex: Start with 2. Identify the specific concern: "This code is inaccessible." "This button has no accessible name - aria-label or visible text is needed for screen readers to announce its purpose.".

      +

      Jamie: What makes this practice feel low-stakes but still real?

      +

      Alex: Start with Challenge 13: AI as Your Copilot: What you will do: Use GitHub Copilot to improve a documentation file, then critically evaluate whether the AI's suggestions are actually improvements.

      +

      Jamie: How would you walk the room through that step by step?

      +

      Alex: Start with Instructions. There is something to understand, something to try, and something that proves the try worked.

      +

      Alex: The practical anchors are these. Improve the clarity of a paragraph. Fix any grammar or spelling issues. Suggest a better heading or structure.

      +

      Alex: First, open the sample file: docs/samples/copilot-improvement-before.md (or any documentation file in the repo). Then, use GitHub Copilot (Chat or inline suggestions) to. After that, critically evaluate the AI's output before accepting it. Treat it like a recipe: do not add the next ingredient until the previous one is actually in the bowl.

      +

      Jamie: What is the one idea that makes the next few steps less mysterious?

      +

      Alex: This is where The trust-verify-reject framework becomes real: for every Copilot suggestion, ask yourself.

      -

      Alex: Keep the teaching thread moving. Here is the plain-English version of 3. Explain why it matters. Context turns a complaint into a lesson. Put another way, it also respects the contributor - they deserve to understand, not just comply.

      -

      Jamie: Let's pause on 4. Suggest a path forward (when you can). What should a learner take away from it?

      -

      Alex: This is where 4. Suggest a path forward (when you can) becomes real: if you have an idea for a solution, offer it as a suggestion, not a mandate. That matters in practice: "Something like aria-label='Close navigation menu' would work well here.

      -

      Alex: Keep the teaching thread moving. Keep the learner anchored in 5. Signal the weight of the concern. Help contributors understand what is a blocker versus a preference. A good GitHub workflow is like a well-run meeting: everyone knows the topic, the next action, and who has the floor.

      -

      Alex: The practical takeaway is this. 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.

      +

      Alex: Now bring the learner back to the room. Keep the learner anchored in What to watch for. My evaluation: I accepted/modified/rejected this because.

      +

      Alex: For a learner, the useful signals are these. Hallucinated links -- URLs that look real but go nowhere. Over-complicated language -- simpler is usually better. Lost context -- the AI may not understand the workshop's audience. Accessibility regressions -- images without alt text, complex tables where lists work better.

      +

      Jamie: What would you say to someone who is already bracing for this to be too much?

      +

      Alex: The reason Peer simulation check matters is that compare your Copilot result with the peer-simulation PR or with a real buddy if you have access. That gives the learner a simple foothold: did the AI suggestion actually improve the document?

      +

      Alex: The useful habit is simple: orient first, act second, verify third. That pause before acting is part of the work.

      +

      Alex: That matters because of the next idea. Start with Example interaction transcript: Review the alt text in docs/welcome.md and suggest improvements for screen reader users. The next useful detail is this: The image on line 42 has alt="screenshot" which is not descriptive. Think of it like entering a new building: first you find the lobby, then the room, then the door you actually need.

      -

      Jamie: Let's pause on Prefer "we" or describe the code, not the person. What should a learner take away from it?

      -

      Alex: The reason Prefer "we" or describe the code, not the person matters is that "You made an error here." "There's an error here." or "This line does X but we need Y.".

      -

      Alex: Keep the teaching thread moving. Start with 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?".

      -

      Jamie: Let's pause on Acknowledge cultural and language diversity. What should a learner take away from it?

      -

      Alex: Here is the plain-English version of Acknowledge cultural and language diversity. When reading someone's comment: Assume good intent unless there is clear evidence otherwise. Put another way, when writing: Choose plain words over clever ones.

      -

      Alex: The practical takeaway is this. 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.

      +

      Jamie: What is the pre-flight check here?

      +

      Alex: Here is the plain-English version of Before and after. After (improved with Copilot's help).

      +

      Alex: This is where the talk moves from concept to action. This is where Critical evaluation notes becomes real: not everything Copilot suggests is correct. That matters in practice: What Copilot got right: The suggestion to be more descriptive than "screenshot" is correct.

      +

      Jamie: Where do you want a learner to place their attention here?

      +

      Alex: Start with Alternate approaches. There is something to understand, something to try, and something that proves the try worked.

      +

      Alex: These are the details that keep the idea from floating away. Ask Copilot to improve documentation clarity, then evaluate whether the suggestions make sense. Ask Copilot to check Markdown formatting, then verify its corrections. Ask Copilot to suggest commit messages, then refine them.

      +

      Alex: A solid pull request habit is to separate three questions: what changed, why it changed, and what still needs review. That keeps the conversation useful instead of noisy.

      -

      Alex: Keep the teaching thread moving. This is where Avoid urgency markers unless genuinely urgent becomes real: "I need this fixed ASAP" "This is blocking our release scheduled for next Friday - is there capacity to look at it this week?". The workshop is closer to rehearsal than lecture. You hear the move, try the move, and then check what changed.

      -

      Jamie: Let's pause on Keep comments focused. What should a learner take away from it?

      -

      Alex: Keep the learner anchored in Keep comments focused. Each comment should address one concern. This is the part to say slowly: If you have three issues, leave three comments - unless they are closely related.

      -

      Alex: Keep the teaching thread moving. The reason Don't leave comments unresolved matters is that if you asked a question and got an answer, respond. That gives the learner a simple foothold: "Thanks, that makes sense" or resolving the conversation thread signals that the thread is complete.

      +

      Alex: Before the learner moves on. The reason What matters matters is that the learning objective is using AI as a collaborator while maintaining your own judgment. That gives the learner a simple foothold: if you used Copilot, evaluated its output critically, and made an improvement based on that evaluation, you completed this challenge. The interface gets friendlier when it stops being a wall of controls and starts being a set of named places.

      +

      Jamie: What should someone listen for when a lesson offers more than one tool path?

      +

      Alex: Start with AI-Powered Code Assistance in VS Code: Day 2, Block 2-3 Material This guide covers GitHub Copilot: inline code suggestions, Copilot Chat (conversational assistance), custom instructions vs custom agents, effective prompting for non-code contributions, and using Accessible View to read AI-generated. The next useful detail is this: Use the official guides as companion references.

      +

      Alex: Hold that next to this. Here is the plain-English version of Workshop Recommendation (Chapter 16 / Challenge 13). Free to use: GitHub Copilot Free tier is included with all GitHub accounts at no cost. Put another way, this workshop uses only the free tier.

      +

      Alex: That shows up in the workshop in a few specific ways. There are 3 guided challenges. Automation check: none (tool configuration is account-local and account-specific). The evidence is issue comment with checklist of completed actions. The pattern is install, prompt, apply, reflect.

      -

      Jamie: Let's pause on Resolving conversations. What should a learner take away from it?

      -

      Alex: Start with Resolving conversations: On a PR, conversations (inline comment threads) can be "resolved" once addressed. The next useful detail is this: The author of the change and the reviewer can both resolve them.

      -

      Alex: Keep the teaching thread moving. Here is the plain-English version of 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. Put another way, a reaction on an existing comment is enough. It is like learning a transit route. The names of the stops matter because they tell you whether you are still going the right direction.

      -

      Jamie: Let's pause on Reactions. What should a learner take away from it?

      -

      Alex: This is where Reactions becomes real: GitHub reactions () are an efficient way to express agreement, appreciation, or concern without adding noise to a thread.

      +

      Jamie: What does the learner do first, second, and then after that?

      +

      Alex: Start with Challenge 13 Set. There is something to understand, something to try, and something that proves the try worked.

      +

      Alex: First, sign in to GitHub Copilot - authenticate with GitHub (VS Code 1.116+ has Copilot built in; no extension install needed). Then, ask Copilot to explain a codebase - clone the sci-fi themes repo and use Copilot Chat to understand it. After that, ask Copilot to create something new - prompt Copilot to generate a custom theme and apply it. It is a checklist, but a meaningful one: every item creates evidence that the next step is safe.

      +

      Jamie: Turn that into a path someone can follow.

      +

      Alex: Keep the learner anchored in Challenge 13.1 Step-by-Step: Sign In to Copilot. Sign in to GitHub Copilot and verify it responds to prompts. This is the part to say slowly: VS Code desktop with your Learning Room repository open. A good GitHub workflow is like a well-run meeting: everyone knows the topic, the next action, and who has the floor.

      +

      Alex: First, (Older VS Code only) Open the Extensions sidebar: Ctrl+Shift+X (Mac: Cmd+Shift+X). Then, (Older VS Code only) Type GitHub Copilot in the search box and press Enter. After that, (Older VS Code only) Find GitHub Copilot (publisher: GitHub) in the results. Activate Install. Finally, (Older VS Code only) VS Code may also install GitHub Copilot Chat automatically. If not, search for it separately and install it. It is like walking a hallway with named doors: read the sign, enter the right room, then confirm where you landed.

      +

      Jamie: What is the ordered workflow?

      +

      Alex: First, sign in when prompted: activate Sign in to GitHub and complete the OAuth flow in your browser. Then, verify Copilot is active: open Copilot Chat with Ctrl+Shift+I (Mac: Cmd+Shift+I). Type Hello, are you working? and press Enter. Copilot should respond. The rhythm is simple: orient, act, verify, then continue.

      +

      Jamie: Give me the sequence, because order matters here.

      +

      Alex: The reason Challenge 13.2 Step-by-Step: Explain a Codebase matters is that use Copilot Chat to understand an unfamiliar repository by asking targeted questions. That gives the learner a simple foothold: VS Code with the sci-fi themes repository cloned.

      +

      Alex: First, open the Command Palette: Ctrl+Shift+P (Mac: Cmd+Shift+P). Then, run Git: Clone and paste: https://github.com/community-access/vscode-sci-fi-themes.git. After that, open the cloned repository when VS Code prompts. Finally, open Copilot Chat: Ctrl+Shift+I (Mac: Cmd+Shift+I). The rhythm is simple: orient, act, verify, then continue.

      +

      Jamie: Let's pause on Challenge 13.2 Step-by-Step: Explain a Codebase. What should a learner take away from it?

      +

      Alex: First, ask Copilot: "What does the chat.agent.thinking.phrases setting do in VS Code?". Then, read the response. Use Alt+F2 (Accessible View) if needed to read the full text. After that, ask a follow-up: "How do I apply one of these themes to my settings.json?". Finally, follow Copilot's instructions to apply one theme to your settings.json file. Think of it as a rail line: each stop confirms you are still on the right route before the next one.

      -

      Alex: Keep the teaching thread moving. Keep the learner anchored in 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 the part to say slowly: This is a significant accessibility win for anyone who types the same comments repeatedly during triage, reviews, or issue management.

      -

      Jamie: Let's pause on Common uses. What should a learner take away from it?

      -

      Alex: Start with Common uses. There is something to understand, something to try, and something that proves the try worked.

      -

      Alex: The practical takeaway is this. "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.

      -

      Jamie: Let's pause on Creating a Saved Reply. What should a learner take away from it?

      -

      Alex: Start with Creating a Saved Reply. There is something to understand, something to try, and something that proves the try worked.

      -

      Alex: First, navigate to github.com/settings/replies. Then, activate "Add a saved reply". After that, give it a title (e.g., "Good first issue claim") - this is what you search. Finally, type the full reply text in the body (Markdown is supported). Think of it as a rail line: each stop confirms you are still on the right route before the next one.

      -
      -

      Jamie: Let's pause on Using a Saved Reply in a comment. What should a learner take away from it?

      -

      Alex: Start with Using a Saved Reply in a comment. There is something to understand, something to try, and something that proves the try worked.

      -

      Alex: First, navigate to any comment text area. Then, activate the Saved Replies button (the speech bubble icon in the comment toolbar, or press Ctrl+. if enabled). After that, a dropdown appears showing your saved replies - type to filter by title. Finally, select the reply - it inserts into the text area. Treat it like a recipe: do not add the next ingredient until the previous one is actually in the bowl.

      -

      Jamie: Before we leave Using a Saved Reply in a comment, what is the practical point?

      -

      Alex: First, edit as needed before submitting. It is a checklist, but a meaningful one: every item creates evidence that the next step is safe.

      -

      Alex: Keep the teaching thread moving. This is where Screen reader path becomes real: limit: GitHub allows up to 100 saved replies per account.

      -

      Alex: A solid navigation habit is to prove where you are before activating controls. Headings, landmarks, and the address bar are not trivia; they are your map.

      -

      Jamie: Let's pause on Learning Cards: Commenting Etiquette. What should a learner take away from it?

      -

      Alex: Start with Learning Cards: Commenting Etiquette. There is something to understand, something to try, and something that proves the try worked.

      -

      Alex: The practical takeaway is this. 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. 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.

      +

      Jamie: Let's pause on Challenge 13.3 Step-by-Step: Create Something New. What should a learner take away from it?

      +

      Alex: Start with Challenge 13.3 Step-by-Step: Create Something New: Use Copilot as a creative collaborator to generate a custom config and apply it. The next useful detail is this: VS Code with Copilot Chat open.

      +

      Alex: First, open Copilot Chat: Ctrl+Shift+I (Mac: Cmd+Shift+I). Then, type a creative prompt: "Create a custom GitHub Copilot thinking phrases theme for [your favorite universe - Dune, Marvel, Studio Ghibli, Star Trek, etc.]". After that, read Copilot's generated theme. It should include an array of themed phrases. Finally, copy the generated content: select all text in the Copilot response, then Ctrl+C (Mac: Cmd+C). Think of it as a rail line: each stop confirms you are still on the right route before the next one.

      +

      Jamie: Before we leave Challenge 13.3 Step-by-Step: Create Something New, what is the practical point?

      +

      Alex: First, open your settings.json: Command Palette, then Preferences: Open User Settings (JSON). Then, paste the theme configuration into your settings. After that, save with Ctrl+S and reload VS Code: Command Palette, then Developer: Reload Window. Finally, test your new theme by asking Copilot a question and watching the thinking phrases. Treat it like a recipe: do not add the next ingredient until the previous one is actually in the bowl.

      +

      Jamie: How do these exercises create confidence instead of pressure?

      +

      Alex: Here is the plain-English version of Completing Challenge 13: Submit Your Evidence. Open your assigned Challenge 13 issue and post a completion comment. Put another way, close your Challenge 13 issue when done.

      +

      Alex: Keep the thread going. Start with Expected Outcomes. There is something to understand, something to try, and something that proves the try worked.

      +

      Alex: The room should hear these as checkpoints. Student can install and authenticate GitHub Copilot Chat. Student can ask Copilot effective questions about code and settings. Student can use Copilot's output to customize their development environment. Student understands Copilot as a tool to explain and create, not just autocomplete.

      -

      Alex: Keep the teaching thread moving. The reason Review the code, not the person matters is that "You clearly don't understand accessibility." "This implementation doesn't account for keyboard navigation - here's how to add it.". The interface gets friendlier when it stops being a wall of controls and starts being a set of named places.

      -

      Jamie: Let's pause on Don't gatekeep knowledge. What should a learner take away from it?

      -

      Alex: Start with Don't gatekeep knowledge: If a contributor makes a mistake because they didn't know something, explain the concept.

      -

      Alex: Keep the teaching thread moving. Here is the plain-English version of Ask questions instead of making demands. "Change this to use aria-label." "What do you think about using aria-label here instead? Put another way, screen readers would then announce the button's purpose directly.".

      +

      Jamie: Let's pause on If You Get Stuck. What should a learner take away from it?

      +

      Alex: Keep the learner anchored in If You Get Stuck. Continue learning: The GitHub Skills courses Getting Started with GitHub Copilot and Customize Your GitHub Copilot Experience cover Copilot setup, prompting, and personalization. This is the part to say slowly: See Appendix Z for the full catalog.

      +

      Alex: First, extension installation fails? Reload VS Code: Ctrl+Shift+P, then Developer: Reload Window. Then, oAuth sign-in fails? Verify your GitHub account is active in the browser first, close VS Code and retry. After that, chat panel does not open? Try Ctrl+Shift+I (Mac: Cmd+Shift+I). If still nothing, check that the Copilot Chat extension is installed (not just the base Copilot extension). Finally, Copilot seems unresponsive? Click the model selector at the bottom of Chat panel and confirm you are signed in. It is like walking a hallway with named doors: read the sign, enter the right room, then confirm where you landed.

      +

      Jamie: Before we leave If You Get Stuck, what is the practical point?

      +

      Alex: First, cannot copy from Copilot response? Use Alt+F2 (Accessible View) to get the text in a copyable buffer. Then, ask facilitator to verify Copilot is activated and show you one example prompt. After that, finished but not sure you did it right? Compare your work against the Challenge 13 reference solution. The rhythm is simple: orient, act, verify, then continue.

      +

      Alex: Another way to ground it. The reason Learning Moment matters is that using Copilot as a brainstorming partner helps you write documentation that others can actually understand. That gives the learner a simple foothold: the prompting skill you practiced here - asking specific questions, iterating on responses, applying results - transfers to every AI tool you will use in your career.

      +

      Jamie: Let's pause on Learning Pattern Used in This Chapter. What should a learner take away from it?

      +

      Alex: Start with Learning Pattern Used in This Chapter. There is something to understand, something to try, and something that proves the try worked.

      +

      Alex: First, install the tool and verify it works before starting the task. Then, use the tool to explore and understand (ask questions, read responses). After that, use the tool to create something new (generate, customize, apply). Finally, reflect on when the tool helped and when your own judgment was better. Think of it as a rail line: each stop confirms you are still on the right route before the next one.

      -

      Jamie: Let's pause on Distinguish opinion from requirement. What should a learner take away from it?

      -

      Alex: This is where Distinguish opinion from requirement becomes real: if something is your stylistic preference but NOT a bug or correctness issue, say so. That matters in practice: "The current implementation is correct.

      -

      Alex: Keep the teaching thread moving. Keep the learner anchored in 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! A good GitHub workflow is like a well-run meeting: everyone knows the topic, the next action, and who has the floor.

      -

      Jamie: Let's pause on Say thank you. What should a learner take away from it?

      -

      Alex: The reason Say thank you matters is that when someone takes time to review your work, acknowledge it - even if you disagree with some feedback. That gives the learner a simple foothold: "Thanks so much for the thorough review!

      +

      Alex: This is the part worth saying out loud. Here is the plain-English version of About Learning Cards in This Chapter. Throughout this chapter, look for expandable "learning cards" that show how to accomplish each task from different perspectives. Put another way, not every section has every card - only the cards that add meaningful guidance for that topic are included. It is like learning a transit route. The names of the stops matter because they tell you whether you are still going the right direction.

      +

      Jamie: Give me the version that sounds like an instructor, not a manual.

      +

      Alex: This is where 1. What is GitHub Copilot becomes real: GitHub Copilot is an AI pair programmer that suggests code and text completions as you type. That matters in practice: For this workshop: Copilot helps with Markdown documentation, issue triage, PR descriptions, and commit messages - not just code.

      +

      Alex: The parts worth keeping in working memory are these. Complete lines of code or documentation. Generate entire functions or sections of text from comments. Answer questions about code in your workspace. Explain complex code in plain language.

      +

      Jamie: Let's pause on Installation Steps. What should a learner take away from it?

      +

      Alex: Keep the learner anchored in Installation Steps. One extension, all features: GitHub Copilot Chat is now the single all-in-one extension. This is the part to say slowly: It provides inline code suggestions, the Chat panel (Ctrl+Shift+I / Mac: Cmd+Shift+I), inline chat (Ctrl+I / Mac: Cmd+I), and all agent features.

      +

      Alex: First, open Extensions sidebar: Ctrl+Shift+X (Mac: Cmd+Shift+X). Then, search for "GitHub Copilot Chat". After that, find GitHub Copilot Chat (publisher: GitHub). Finally, press Enter to open the extension detail page. It is like walking a hallway with named doors: read the sign, enter the right room, then confirm where you landed.

      +

      Jamie: Before we leave Installation Steps, what is the practical point?

      +

      Alex: First, tab to "Install" button → press Enter. Then, wait for installation to complete. The rhythm is simple: orient, act, verify, then continue.

      -

      Alex: Keep the teaching thread moving. Start with Don't take feedback personally: Code review is about the code, not your worth as a person or developer. The next useful detail is this: Even the most senior contributors receive change requests.

      -

      Jamie: Let's pause on Explain your choices. What should a learner take away from it?

      -

      Alex: Here is the plain-English version of Explain your choices. If you are keeping your implementation despite feedback, explain why. Put another way, "I considered aria-label here, but I went with a visually-hidden instead because it allows translators to localize the text more easily.

      -

      Alex: Keep the teaching thread moving. This is where Surface blockers early becomes real: don't wait until you have finished a 500-line PR to mention that you weren't sure about the approach. The workshop is closer to rehearsal than lecture. You hear the move, try the move, and then check what changed.

      +

      Jamie: Let's pause on Signing In. What should a learner take away from it?

      +

      Alex: Start with Signing In. There is something to understand, something to try, and something that proves the try worked.

      +

      Alex: First, VS Code prompts: "Sign in to use GitHub Copilot". Then, navigate to the notification or click the Copilot icon in the status bar. After that, select "Sign in to GitHub". Finally, your browser opens for GitHub authentication. The rhythm is simple: orient, act, verify, then continue.

      +

      Jamie: Before we leave Signing In, what is the practical point?

      +

      Alex: First, authorize the Copilot extension. Then, return to VS Code. Think of it as a rail line: each stop confirms you are still on the right route before the next one.

      +

      Alex: Here is the practical turn. Start with Verify activation. There is something to understand, something to try, and something that proves the try worked.

      +

      Alex: On the ground, that means a few things. Bottom-right status bar shows Copilot icon (looks like <). Icon should be active (not grayed out). If grayed out, click it to sign in.

      +

      Jamie: Let's pause on Command Palette. What should a learner take away from it?

      +

      Alex: Start with Command Palette. There is something to understand, something to try, and something that proves the try worked.

      +

      Alex: First, ctrl+Shift+P (Mac: Cmd+Shift+P). Then, type "Copilot: Check Status". After that, select it to see your subscription tier (Free, Pro, Enterprise). Treat it like a recipe: do not add the next ingredient until the previous one is actually in the bowl.

      -

      Jamie: Let's pause on Inclusive Commenting for Accessibility Issues. What should a learner take away from it?

      -

      Alex: Keep the learner anchored in Inclusive Commenting for Accessibility Issues. When filing or discussing accessibility bugs, additional context helps.

      -

      Alex: The practical takeaway is this. 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.

      -

      Jamie: Let's pause on The "Good First Issue" Social Contract. What should a learner take away from it?

      -

      Alex: The reason The "Good First Issue" Social Contract matters is that when a maintainer labels an issue good first issue, they are. That gives the learner a simple foothold: when you take a good first issue, your responsibilities.

      -

      Alex: The practical takeaway is this. Investing time - good first issues require extra documentation and mentorship. Signaling welcome - they want to support a new contributor.

      -

      Alex: First, comment to claim it - "Hi, I'd like to work on this. Can I be assigned?". Then, wait for assignment - do not start until assigned; two people working in parallel wastes everyone's time. After that, 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?". Finally, 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?". The rhythm is simple: orient, act, verify, then continue.

      -

      Jamie: Before we leave The "Good First Issue" Social Contract, what is the practical point?

      -

      Alex: First, don't disappear - if you claim an issue, see it through or explicitly hand it back. Think of it as a rail line: each stop confirms you are still on the right route before the next one.

      -

      Jamie: Let's pause on When you receive harsh feedback. What should a learner take away from it?

      -

      Alex: Start with When you receive harsh feedback. There is something to understand, something to try, and something that proves the try worked.

      -

      Alex: First, take a breath before responding - there is no urgency; the thread will wait. Then, look for the valid concern underneath the harsh words. After that, respond to the concern, not the tone. Finally, if the behavior crosses into harassment, report it via the "." button on the comment → "Report". Think of it as a rail line: each stop confirms you are still on the right route before the next one.

      +

      Alex: The next layer is this. This is where Free tier includes becomes real: billing note: GitHub Copilot plan details are evolving. That matters in practice: Facilitators will provide current guidance at the workshop.

      +

      Alex: That becomes easier when you listen for these cues. Completions and multi-line suggestions. Copilot Chat. Limited monthly usage (usually sufficient for documentation work).

      +

      Jamie: Okay, set the room for us. What are we walking into?

      +

      Alex: Keep the learner anchored in 3. Inline Suggestions - Ghost Text Completions. Copilot suggests completions as you type, displayed as gray "ghost text" after your cursor. This is the part to say slowly: In screen reader mode, VS Code announces suggestions rather than showing them visually.

      +

      Jamie: Let's pause on While typing. What should a learner take away from it?

      +

      Alex: The reason While typing matters is that the suggestion appears as gray "ghost text" after your cursor - a preview of what Copilot thinks you want to type next. That gives the learner a simple foothold: it's there but not inserted; press Tab to accept it or Escape to dismiss. The interface gets friendlier when it stops being a wall of controls and starts being a set of named places.

      +

      Alex: A few details make that real. Increase ghost text contrast: Open Settings (Ctrl+,), search editorGhostText, then customize editor.ghostText.foreground in your color theme to a darker shade such as 555555. Use Accessible View instead: Press Alt+F2 when a suggestion appears. The suggestion text renders at your configured font size in a separate pane, making it far easier to read at 200%+ zoom. Word-by-word acceptance (Ctrl+Right Arrow) lets you watch each word appear at full contrast before deciding whether to continue. High Contrast themes do not automatically restyle ghost text. The color customization above is the most reliable fix.

      +

      Alex: First, Copilot analyzes your context (file content, cursor position, nearby files). Then, generates a suggestion. After that, presents the suggestion. The rhythm is simple: orient, act, verify, then continue.

      -

      Jamie: Let's pause on When you disagree with a decision. What should a learner take away from it?

      -

      Alex: Start with When you disagree with a decision. There is something to understand, something to try, and something that proves the try worked.

      -

      Alex: First, make your case once, clearly and with evidence. Then, accept that the maintainer has the final say in their project. After that, if you strongly disagree, you can fork the project and take it in a different direction - this is legitimate in open source. Treat it like a recipe: do not add the next ingredient until the previous one is actually in the bowl.

      -

      Jamie: Let's pause on When someone is rude to you. What should a learner take away from it?

      -

      Alex: Start with When someone is rude to you. There is something to understand, something to try, and something that proves the try worked.

      -

      Alex: First, you do not have to engage. Then, 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.". After that, report via GitHub's reporting tools if the behavior is abusive. It is a checklist, but a meaningful one: every item creates evidence that the next step is safe.

      -

      Jamie: Let's pause on When you accidentally caused offense. What should a learner take away from it?

      -

      Alex: Start with When you accidentally caused offense. There is something to understand, something to try, and something that proves the try worked.

      -

      Alex: First, acknowledge it directly: "I can see how that came across as dismissive - that wasn't my intention.". Then, do not over-explain or defend excessively. After that, adjust going forward. It is like walking a hallway with named doors: read the sign, enter the right room, then confirm where you landed.

      +

      Jamie: If I am listening before the workshop starts, what should settle in my mind first?

      +

      Alex: Start with Navigating the full Suggestions Panel (Ctrl+Enter): Pressing Ctrl+Enter opens a separate side-by-side tab showing up to 10 alternative suggestions. The next useful detail is this: Alt+F2 on a single suggestion is usually faster.

      +

      Alex: Here is what that changes in practice. Switch to your screen reader's browse/virtual mode when the panel opens (NVDA: Insert+Space to toggle off Application mode; JAWS: this may happen automatically). Use heading keys (H in NVDA/JAWS browse mode) to navigate between each suggestion -- each suggestion is announced as a heading. Each suggestion is followed by an Accept button -- navigate to it with Tab or B (button key) and press Enter to insert it at your cursor position. Press Escape or close the tab to dismiss without accepting.

      +

      Alex: That connects to another useful point. Start with Accepting word-by-word (Ctrl+Right Arrow / Mac: Cmd+Right Arrow) is particularly useful when. There is something to understand, something to try, and something that proves the try worked.

      +

      Alex: The practical takeaway is this. The suggestion starts correctly but you want to finish differently. You want to review the suggestion incrementally. You're learning and want to see how Copilot structures responses.

      +

      Jamie: Let's pause on Reading Suggestions with Screen Readers. What should a learner take away from it?

      +

      Alex: This is where Reading Suggestions with Screen Readers becomes real: visual users: If Copilot's ghost text is getting in the way, skip to "Disabling Inline Suggestions" below. That matters in practice: Screen reader users - tuning announcement verbosity.

      +

      Alex: A solid navigation habit is to prove where you are before activating controls. Headings, landmarks, and the address bar are not trivia; they are your map.

      -

      Jamie: Let's pause on Writing Your First README. What should a learner take away from it?

      -

      Alex: The reason Writing Your First README matters is that see also: Appendix W: GitHub Pages for publishing your README as a website. That gives the learner a simple foothold: a README is the front door of your project.

      -

      Alex: Keep the teaching thread moving. Start with What belongs in a README: Every README should answer these questions, roughly in this order. The next useful detail is this: 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. Think of it like entering a new building: first you find the lobby, then the room, then the door you actually need.

      -

      Jamie: Let's pause on Accessibility in READMEs. What should a learner take away from it?

      -

      Alex: Here is the plain-English version of Accessibility in READMEs. Your README is a web page -- GitHub renders it as HTML. Put another way, that means the same accessibility rules apply.

      -

      Alex: The practical takeaway is this. Alt text for images and badges. A badge that says is invisible to screen readers. Write 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 -- not Click here.

      +

      Jamie: Let's pause on NVDA. What should a learner take away from it?

      +

      Alex: Start with NVDA. There is something to understand, something to try, and something that proves the try worked.

      +

      Alex: First, NVDA Menu → Preferences → Settings → Presentation. Then, find "Report dynamic content changes". After that, reduce verbosity level or set specific delays. It is like walking a hallway with named doors: read the sign, enter the right room, then confirm where you landed.

      +

      Jamie: Let's pause on JAWS. What should a learner take away from it?

      +

      Alex: Start with JAWS. There is something to understand, something to try, and something that proves the try worked.

      +

      Alex: First, settings Center → HTML/PDF/Accessibility. Then, adjust "Auto Forms Mode" and "ARIA Live Region" settings. The rhythm is simple: orient, act, verify, then continue.

      +

      Jamie: Let's pause on VoiceOver. What should a learner take away from it?

      +

      Alex: Start with VoiceOver. There is something to understand, something to try, and something that proves the try worked.

      +

      Alex: First, VoiceOver Utility → Verbosity. Then, reduce "Announcements" level. Think of it as a rail line: each stop confirms you are still on the right route before the next one.

      -

      Alex: Keep the teaching thread moving. This is where Good README vs. bad README becomes real: bad: A single paragraph that says "This is my project. That matters in practice: Run it with npm start." No headings, no license, no description of what the project does.

      -

      Jamie: Let's pause on Learning Cards: Writing Your First README. What should a learner take away from it?

      -

      Alex: Start with Learning Cards: Writing Your First README. There is something to understand, something to try, and something that proves the try worked.

      -

      Alex: The practical takeaway is this. 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: rather than an empty that reads as "image" with no context. Use real Markdown link text (installation guide) instead of bare URLs, so your screen reader announces the destination rather than spelling out a long URL. 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.

      -

      Alex: Keep the teaching thread moving. The reason Community Health Files matters is that community health files tell contributors how your project operates before they write a single line of code. That gives the learner a simple foothold: 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. The interface gets friendlier when it stops being a wall of controls and starts being a set of named places.

      +

      Jamie: Let's pause on Alternative: Use Accessible View. What should a learner take away from it?

      +

      Alex: Here is the plain-English version of Alternative: Use Accessible View. Press Alt+F2 (Mac: Option+F2) when a suggestion appears to read it in the Accessible View (full text, no streaming).

      +

      Alex: Keep the teaching thread moving. This is where Prompting Through Comments becomes real: Copilot reads inline comments as instructions. That matters in practice: Type this comment, press Enter, and Copilot drafts content based on your instruction. The workshop is closer to rehearsal than lecture. You hear the move, try the move, and then check what changed.

      +

      Jamie: Let's pause on Temporarily disable for current language. What should a learner take away from it?

      +

      Alex: Start with Temporarily disable for current language. There is something to understand, something to try, and something that proves the try worked.

      +

      Alex: The practical takeaway is this. Click the Copilot icon in the status bar (bottom-right < icon). Select "Disable Completions for [language]".

      -

      Jamie: Let's pause on CONTRIBUTING.md. What should a learner take away from it?

      -

      Alex: Start with CONTRIBUTING.md: This file answers the question every newcomer asks: "How do I help?" A good CONTRIBUTING.md covers. The next useful detail is this: A sentence like "We are glad you are here" costs nothing and signals that newcomers are expected, not tolerated.

      -

      Alex: The practical takeaway is this. 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.

      -

      Alex: Keep the teaching thread moving. Here is the plain-English version of CODE OF CONDUCT.md. A code of conduct sets the social contract for your project. Put another way, without one, "acceptable behavior" is whatever each participant assumes it is -- and those assumptions vary widely.

      -

      Alex: The practical takeaway is this. 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.

      -

      Jamie: Let's pause on SECURITY.md. What should a learner take away from it?

      -

      Alex: This is where SECURITY.md becomes real: see also: Appendix F: Git Security and Appendix P: Security Features for security best practices. That matters in practice: If someone discovers a vulnerability in your project, you do not want them to file a public issue.

      -

      Alex: The practical takeaway is this. 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.

      +

      Alex: Keep the teaching thread moving. The reason Permanently disable completions matters is that the Copilot status bar icon ( <) can be tiny at standard DPI. That gives the learner a simple foothold: use the Command Palette approach instead.

      +

      Alex: The practical takeaway is this. Open Settings: Ctrl+, (Mac: Cmd+,) → search "Copilot enable" → uncheck "Enable Inline Suggestions". Ctrl+Shift+P → type "Copilot: Toggle Completions" → press Enter. This toggles inline suggestions on/off without needing to find a small icon.

      +

      Jamie: How do we make tool choice feel like access, not pressure?

      +

      Alex: Start with Temporarily disable via Command Palette. There is something to understand, something to try, and something that proves the try worked.

      +

      Alex: The practical takeaway is this. 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).

      +

      Alex: Keep the teaching thread moving. Start with Permanently disable via Settings. There is something to understand, something to try, and something that proves the try worked.

      +

      Alex: The practical takeaway is this. Ctrl+, (Mac: Cmd+,) → search "inline suggestions" → toggle off "GitHub Copilot: Enable Inline Completions".

      -

      Alex: Keep the teaching thread moving. Keep the learner anchored in 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. This is the part to say slowly: Adding a LICENSE file is a one-time step that makes your project genuinely open source. A good GitHub workflow is like a well-run meeting: everyone knows the topic, the next action, and who has the floor.

      -

      Jamie: Let's pause on Finding these files on GitHub. What should a learner take away from it?

      -

      Alex: The reason Finding these files on GitHub matters is that navigate to any repository and click Insights then Community Standards. That gives the learner a simple foothold: GitHub shows a checklist of which community health files are present and links to add any that are missing.

      -

      Alex: Keep the teaching thread moving. Start with Learning Cards: Community Health Files. There is something to understand, something to try, and something that proves the try worked.

      -

      Alex: The practical takeaway is this. 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. 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.

      +

      Jamie: Let's pause on Learning Cards: Inline Suggestions. What should a learner take away from it?

      +

      Alex: Start with Learning Cards: Inline Suggestions. There is something to understand, something to try, and something that proves the try worked.

      +

      Alex: The practical takeaway is this. 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. 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.

      +

      Alex: Keep the teaching thread moving. Keep the learner anchored in 4. GitHub Copilot Chat - Conversational Assistance. See also: Appendix K: Copilot Reference has the complete slash command and chat variable reference. This is the part to say slowly: Copilot Chat is a full conversation interface where you ask questions, request explanations, and have content drafted.

      +

      Jamie: What should they understand before typing anything?

      +

      Alex: The reason Opening Copilot Chat matters is that primary panel: Ctrl+Shift+I (Mac: Cmd+Shift+I). That gives the learner a simple foothold: opens the Chat panel on the right side of VS Code.

      +

      Alex: The practical takeaway is this. 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.

      +

      Alex: Treat examples as spoken recipes, not decorations. You may hear something like gh extension install github/gh-copilot. gh copilot suggest "How do I squash the last 3 commits?". Read the command, understand what it changes, then run it only when the repository state matches the lesson.

      -

      Jamie: How should someone choose between those options?

      -

      Alex: Here is the plain-English version of When to Use Different Communication Channels. GitHub Discussions are separate from Issues. Put another way, use Discussions for: "What do people think about X approach?" and Issues for: "The X button is broken.".

      -

      Alex: Use the comparison to make a decision, not to recite a table. The main contrasts are: PR comment means Feedback on a specific code change. PR review means Formal verdict (approve/request changes) with consolidated feedback. Discussion means Open-ended conversation, proposals, community Q&A.

      -

      Jamie: Let's pause on Try It: Rewrite One Comment. What should a learner take away from it?

      -

      Alex: This is where Try It: Rewrite One Comment becomes real: time: 2 minutes What you need: Just your brain. That matters in practice: Read this code review comment and rewrite it to be constructive. The workshop is closer to rehearsal than lecture. You hear the move, try the move, and then check what changed.

      -

      Alex: First, what you noticed. Then, why it matters. After that, what you suggest. Finally, why the suggestion helps. It is a checklist, but a meaningful one: every item creates evidence that the next step is safe.

      -

      Jamie: Before we leave Try It: Rewrite One Comment, what is the practical point?

      -

      Alex: First, encouragement. It is like walking a hallway with named doors: read the sign, enter the right room, then confirm where you landed.

      -

      Jamie: Let's pause on Contributing to Open Source. What should a learner take away from it?

      -

      Alex: Keep the learner anchored in Contributing to Open Source. This section was previously Appendix T. This is the part to say slowly: It is now part of the teaching narrative.

      +

      Alex: Keep the teaching thread moving. Start with Chat Modes: Copilot Chat has four modes, selected from a dropdown at the bottom of the Chat input area. The next useful detail is this: Each mode changes how Copilot interprets your request and what it can do. Think of it like entering a new building: first you find the lobby, then the room, then the door you actually need.

      +

      Jamie: Let's pause on Switching modes. What should a learner take away from it?

      +

      Alex: Here is the plain-English version of Switching modes. 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. Put another way, agent mode is powerful but works best once you're comfortable reviewing its output.

      +

      Alex: The practical takeaway is this. 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.

      +

      Alex: Keep the teaching thread moving. This is where Choosing a Model becomes real: Copilot gives you access to AI models from OpenAI, Anthropic (Claude), Google (Gemini), xAI (Grok), and others. That matters in practice: 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").

      -

      Alex: Keep the teaching thread moving. The reason A Guide for First-Time Contributors matters is that you do not need to be a professional developer to contribute to open source. That gives the learner a simple foothold: documentation, accessibility improvements, and bug reports are among the most valuable contributions any project can receive.

      -

      Jamie: Let's pause on 1. What Is Open Source? What should a learner take away from it?

      -

      Alex: Start with 1. What Is Open Source?: Open source software is software whose source code is publicly available. The next useful detail is this: Anyone can read it, use it, and - in most cases - contribute to it.

      -

      Alex: The practical takeaway is this. 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.

      -

      Alex: Keep the teaching thread moving. Here is the plain-English version of 2. Who Can Contribute? Contributors come from all backgrounds, skill levels, and countries. Put another way, 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. It is like learning a transit route. The names of the stops matter because they tell you whether you are still going the right direction.

      +

      Jamie: Let's pause on Quick guidance. What should a learner take away from it?

      +

      Alex: Keep the learner anchored in Quick guidance. Model availability changes frequently. This is the part to say slowly: Facilitators will provide current guidance at the workshop.

      +

      Alex: The practical takeaway is this. 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.

      +

      Jamie: Let's pause on Panel layout (top to bottom). What should a learner take away from it?

      +

      Alex: Start with Panel layout (top to bottom). There is something to understand, something to try, and something that proves the try worked.

      +

      Alex: The practical takeaway is this. Type your prompt here. Press Ctrl+Enter (Mac: Cmd+Enter) or Enter to send. Choose which AI model to use (GPT-4, Claude, etc.). Some models better for code, others for prose. Shows your previous prompts and Copilot's responses. Navigate with Up/Down Arrow.

      +

      Alex: First, chat input field (multi-line text area). Then, model selector dropdown. After that, conversation history. Finally, action buttons. The rhythm is simple: orient, act, verify, then continue.

      +

      Jamie: Let's pause on NVDA/JAWS. What should a learner take away from it?

      +

      Alex: Start with NVDA/JAWS. There is something to understand, something to try, and something that proves the try worked.

      +

      Alex: The practical takeaway is this. 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.

      -

      Jamie: Let's pause on 3. What Makes a Good First Contribution? What should a learner take away from it?

      -

      Alex: Start with 3. What Makes a Good First Contribution? There is something to understand, something to try, and something that proves the try worked.

      -

      Alex: The practical takeaway is this. 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.

      -

      Alex: Keep the teaching thread moving. Keep the learner anchored in Signs a contribution is too large for a first attempt. A well-executed small contribution is far more valuable than a large contribution that cannot be merged because it is out of scope.

      -

      Alex: The practical takeaway is this. 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.

      -

      Jamie: Let's pause on 4. Finding Something to Work On. What should a learner take away from it?

      -

      Alex: The reason 4. Finding Something to Work On matters is that most open source projects label issues that are suitable for new contributors. That gives the learner a simple foothold: how to search: On any GitHub repository, go to Issues → filter by label.

      +

      Alex: Keep the teaching thread moving. Start with VoiceOver. There is something to understand, something to try, and something that proves the try worked.

      +

      Alex: The practical takeaway is this. 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.

      +

      Jamie: There are a lot of tools in play. How do we keep that from feeling like a contest?

      +

      Alex: This is where Using Slash Commands becomes real: type / in Copilot Chat to see available commands.

      +

      Jamie: Let's pause on Example. What should a learner take away from it?

      +

      Alex: Start with Example. There is something to understand, something to try, and something that proves the try worked.

      +

      Alex: First, select a block of complex Markdown. Then, open Chat: Ctrl+Shift+I (Mac: Cmd+Shift+I). After that, type /explain. Finally, Copilot explains the structure and purpose. It is like walking a hallway with named doors: read the sign, enter the right room, then confirm where you landed.

      -

      Alex: Keep the teaching thread moving. Start with Learning Cards: Finding Something to Work On. There is something to understand, something to try, and something that proves the try worked.

      -

      Alex: The practical takeaway is this. 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. 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.

      -

      Jamie: What is the pre-flight check here?

      -

      Alex: Here is the plain-English version of 5. Reading an Issue Before You Start. Before commenting "I'll take this" on an issue, ask yourself. Put another way, 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.

      -

      Alex: The practical takeaway is this. 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.

      -

      Jamie: Let's pause on Tool Cards: Fork, Clone, and Contribute. What should a learner take away from it?

      -

      Alex: Start with Tool Cards: Fork, Clone, and Contribute. There is something to understand, something to try, and something that proves the try worked.

      -

      Alex: First, click Fork on the repository page, then Create fork. Then, edit files directly in your fork's web interface. After that, click Contribute Open pull request to submit back to the original. Finally, fork the repo on github.com first. It is a checklist, but a meaningful one: every item creates evidence that the next step is safe.

      -

      Jamie: Before we leave Tool Cards: Fork, Clone, and Contribute, what is the practical point?

      -

      Alex: First, navigate to your fork and press. to open in the web editor. Then, edit, commit, and create a PR from the Source Control panel. After that, fork on github.com, then clone your fork: Ctrl+Shift+P Git: Clone. Finally, create a branch, make edits, commit and push. It is like walking a hallway with named doors: read the sign, enter the right room, then confirm where you landed.

      -

      Alex: Treat examples as spoken recipes, not decorations. You may hear something like 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. Read the command, understand what it changes, then run it only when the repository state matches the lesson.

      +

      Jamie: Let's pause on Built-in Actions via Command Palette. What should a learner take away from it?

      +

      Alex: The reason Built-in Actions via Command Palette matters is that Copilot registers actions directly in the Command Palette. That gives the learner a simple foothold: this provides a discoverable way to use Copilot without remembering slash commands or keyboard shortcuts.

      +

      Alex: First, open Command Palette: F1 or Ctrl+Shift+P (Mac: Cmd+Shift+P). Then, type copilot. After that, browse the list of available actions. The rhythm is simple: orient, act, verify, then continue.

      +

      Alex: Keep the teaching thread moving. Start with Learning Cards: Copilot Chat. There is something to understand, something to try, and something that proves the try worked.

      +

      Alex: The practical takeaway is this. 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?"). 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.

      +

      Jamie: Let's pause on 5. Copilot Edits -- Making Multi-File Changes. What should a learner take away from it?

      +

      Alex: Here is the plain-English version of 5. Copilot Edits -- Making Multi-File Changes. As of VS Code 1.118 (April 2026), the separate Edit chat mode is being merged into Agent mode. Put another way, agent mode now supports the same working-set diff workflow that Edit mode provided.

      +

      Alex: The practical takeaway is this. 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.

      -

      Jamie: Let's pause on The Basic Workflow. What should a learner take away from it?

      -

      Alex: Start with The Basic Workflow. There is something to understand, something to try, and something that proves the try worked.

      -

      Alex: First, fork the repository - creates your own copy on GitHub. Then, clone your fork to your computer (or open a Codespace - see Appendix N). After that, create a branch - name it something descriptive: fix/broken-link-setup-guide. Finally, make your change - edit the file, save, verify. It is like walking a hallway with named doors: read the sign, enter the right room, then confirm where you landed.

      -

      Jamie: Before we leave The Basic Workflow, what is the practical point?

      -

      Alex: First, commit with a clear message - "Fix broken link in setup-guide.md line 34". Then, push to your fork. After that, open a pull request from your branch to the original repository's default branch. Finally, respond to review feedback - maintainers may ask for changes; this is normal and not a rejection. The rhythm is simple: orient, act, verify, then continue.

      -

      Alex: Keep the teaching thread moving. The reason Writing a Good PR Description matters is that example: Fixed a broken link on line 34 of setup-guide.md. That gives the learner a simple foothold: the link pointed to /docs/old-setup which no longer exists. The interface gets friendlier when it stops being a wall of controls and starts being a set of named places.

      -

      Alex: The practical takeaway is this. What did you change? Why was the change needed? How did you verify it works?

      -

      Jamie: How should someone ask for help in a way that gets them unstuck faster?

      -

      Alex: Start with 7. Getting Help: It is always acceptable to ask a question on an issue or pull request. The next useful detail is this: 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.

      -

      Alex: The practical takeaway is this. 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.

      +

      Jamie: Let's pause on How to use Copilot Edits. What should a learner take away from it?

      +

      Alex: This is where How to use Copilot Edits becomes real: Copilot Edits shows you the full diff first. The workshop is closer to rehearsal than lecture. You hear the move, try the move, and then check what changed.

      +

      Alex: The practical takeaway is this. Click "Add Files." above the chat input,. Type in the chat input and select a file from the picker,. Right-click a file in the Explorer and choose "Add File to Copilot Edits".

      +

      Alex: First, open Copilot Chat: Ctrl+Shift+I (Mac: Cmd+Shift+I). Then, at the bottom of the Chat panel, click the mode dropdown and select Edit. After that, add files to your working set -- these are the files Copilot is allowed to edit. Finally, 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". It is a checklist, but a meaningful one: every item creates evidence that the next step is safe.

      +

      Jamie: Before we leave How to use Copilot Edits, what is the practical point?

      +

      Alex: First, press Enter -- Copilot shows a diff of proposed changes in each file. Then, review the changes: use Accept or Reject on individual files, or Accept All / Reject All. It is like walking a hallway with named doors: read the sign, enter the right room, then confirm where you landed.

      +

      Jamie: Let's pause on Navigating the diff with a screen reader. What should a learner take away from it?

      +

      Alex: Start with Navigating the diff with a screen reader. There is something to understand, something to try, and something that proves the try worked.

      +

      Alex: The practical takeaway is this. 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.

      +

      Alex: Keep the teaching thread moving. Start with Working set tips. There is something to understand, something to try, and something that proves the try worked.

      +

      Alex: The practical takeaway is this. 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.

      -

      Alex: Keep the teaching thread moving. Here is the plain-English version of 8. After Your Contribution Is Merged. This matters for your GitHub profile. Put another way, 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.

      -

      Alex: The practical takeaway is this. 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.

      -

      Jamie: Let's pause on 9. Building a Contribution Habit. What should a learner take away from it?

      -

      Alex: This is where 9. Building a Contribution Habit becomes real: the hardest part of open source contribution is starting. That matters in practice: 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.

      -

      Alex: Keep the teaching thread moving. Keep the learner anchored in Practical habits. Challenge Time: Complete Challenge 8: The Culture Layer in the Challenge Hub, then advance to Chapter 09: Labels, Milestones and Projects. This is the part to say slowly: Next: Chapter 09: Labels, Milestones, and Projects Back: Chapter 07: Merge Conflicts Related appendices: Appendix M: Accessibility Standards Appendix F: Git Security Appendix O: Branch Protection. A good GitHub workflow is like a well-run meeting: everyone knows the topic, the next action, and who has the floor.

      -

      Alex: The practical takeaway is this. 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.

      +

      Jamie: Let's pause on Learning Cards: Copilot Edits. What should a learner take away from it?

      +

      Alex: Start with Learning Cards: Copilot Edits. There is something to understand, something to try, and something that proves the try worked.

      +

      Alex: The practical takeaway is this. 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. 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.

      +

      Alex: Keep the teaching thread moving. Here is the plain-English version of 6. Agent Mode -- Let Copilot Drive. See also: Chapter 19: Accessibility Agents and Chapter 20: Build Your Agent for creating your own Copilot agent. Put another way, agent mode is the most autonomous way to use Copilot. It is like learning a transit route. The names of the stops matter because they tell you whether you are still going the right direction.

      +

      Alex: The practical takeaway is this. 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.

      +

      Jamie: Let's pause on How to use Agent mode. What should a learner take away from it?

      +

      Alex: Start with How to use Agent mode. There is something to understand, something to try, and something that proves the try worked.

      +

      Alex: First, open Copilot Chat: Ctrl+Shift+I (Mac: Cmd+Shift+I). Then, select Agent from the mode dropdown at the bottom of the Chat panel. After that, 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". Finally, Copilot begins working -- it shows each step it's taking and asks for approval before running terminal commands. It is a checklist, but a meaningful one: every item creates evidence that the next step is safe.

      +

      Jamie: Before we leave How to use Agent mode, what is the practical point?

      +

      Alex: First, watch the progress in the Chat panel; review any proposed changes in the editor. It is like walking a hallway with named doors: read the sign, enter the right room, then confirm where you landed.

      -

      Jamie: Let's pause on Organizing Work and Cross-Referencing on GitHub. What should a learner take away from it?

      -

      Alex: The reason Organizing Work and Cross-Referencing on GitHub matters is that labels, milestones, and projects are the organizational layer of GitHub. That gives the learner a simple foothold: they turn a chaotic list of issues into a structured, navigable, prioritized body of work.

      -

      Alex: Keep the teaching thread moving. Start with Workshop Recommendation (Chapter 9): Chapter 9 is a guided triage chapter focused on organization skills.

      -

      Alex: The practical takeaway is this. There are 1 guided challenge. Automation check: none by default. The evidence is structured issue comment in assigned challenge issue. The pattern is inspect, classify, explain.

      -

      Jamie: Let's pause on Chapter 9 Challenge Set. What should a learner take away from it?

      -

      Alex: Start with Chapter 9 Challenge Set. There is something to understand, something to try, and something that proves the try worked.

      -

      Alex: First, post a triage recommendation - read an issue, recommend labels/milestone/project placement, and explain your reasoning. Treat it like a recipe: do not add the next ingredient until the previous one is actually in the bowl.

      -
      -

      Jamie: Let's pause on Challenge 9.1 Step-by-Step: Triage Recommendation Comment. What should a learner take away from it?

      -

      Alex: This is where Challenge 9.1 Step-by-Step: Triage Recommendation Comment becomes real: read the details of a Learning Room issue and post a structured triage recommendation that a maintainer could act on immediately. That matters in practice: Labels and issue states are how we wake up agents. The workshop is closer to rehearsal than lecture. You hear the move, try the move, and then check what changed.

      -

      Alex: The practical takeaway is this. 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?

      -

      Alex: First, open the Issues tab in your Learning Room repository. Then, find any open issue that does not already have labels applied (or pick one your facilitator assigns). After that, read the issue title and full description carefully. Note. Finally, open your assigned Chapter 9 challenge issue (the one titled "Chapter 9.1: Triage Recommendation (@yourname)"). It is a checklist, but a meaningful one: every item creates evidence that the next step is safe.

      -

      Jamie: Before we leave Challenge 9.1 Step-by-Step: Triage Recommendation Comment, what is the practical point?

      -

      Alex: First, scroll to the comment box and post a triage recommendation using this format. Then, if you have write access to the repository, apply the recommended labels and milestone directly on the issue you triaged. After that, activate the Comment button. It is like walking a hallway with named doors: read the sign, enter the right room, then confirm where you landed.

      -

      Jamie: What should the learner prove to themselves after each small task?

      -

      Alex: Keep the learner anchored in Completing Chapter 9: Submit Your Evidence. Your triage recommendation comment is your evidence. This is the part to say slowly: Close your Chapter 9 challenge issue when done.

      -

      Alex: Keep the teaching thread moving. Start with Expected Outcomes. There is something to understand, something to try, and something that proves the try worked.

      -

      Alex: The practical takeaway is this. 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.

      +

      Alex: Keep the teaching thread moving. Keep the learner anchored in 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. This is the part to say slowly: When Copilot pauses for approval, focus moves to the approval dialog in the Chat panel.

      +

      Alex: The practical takeaway is this. Allow -- run this command once. Allow Always -- always allow this command type without asking again (use carefully). Cancel -- stop and don't run it.

      +

      Jamie: Let's pause on Learning Cards: Agent Mode. What should a learner take away from it?

      +

      Alex: Start with Learning Cards: Agent Mode. There is something to understand, something to try, and something that proves the try worked.

      +

      Alex: The practical takeaway is this. 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. 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.

      +

      Alex: Keep the teaching thread moving. Start with 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. The next useful detail is this: Unlike regular inline suggestions that complete what you're currently typing, NES looks ahead to related edits elsewhere in the file. Think of it like entering a new building: first you find the lobby, then the room, then the door you actually need.

      -

      Jamie: Before we leave If You Get Stuck, what is the practical point?

      -

      Alex: First, not sure which label to pick? Start with just one: documentation, bug, or accessibility. You can always add more. Then, milestone is unclear? Write none and explain why - that is a valid triage decision. After that, project board is unknown? Write Needs Triage - that is the correct default. Finally, 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"). Think of it as a rail line: each stop confirms you are still on the right route before the next one.

      -

      Jamie: What is the teaching move inside If You Get Stuck?

      -

      Alex: First, ask facilitator to review your one-sentence reason before posting. Treat it like a recipe: do not add the next ingredient until the previous one is actually in the bowl.

      -

      Alex: Keep the teaching thread moving. Here is the plain-English version of Learning Moment. Triage is about clarity, not authority. Put another way, you do not need maintainer permissions to help organize work. It is like learning a transit route. The names of the stops matter because they tell you whether you are still going the right direction.

      -

      Jamie: Before we leave Learning Pattern Used in This Chapter, what is the practical point?

      -

      Alex: First, inspect an issue carefully before acting (read before you write). Then, classify work using a consistent vocabulary (labels, milestones). After that, explain your reasoning in writing (one-sentence justification). Finally, build triage instincts that transfer to any open source project. It is a checklist, but a meaningful one: every item creates evidence that the next step is safe.

      +

      Jamie: Let's pause on Turning on Next Edit Suggestions. What should a learner take away from it?

      +

      Alex: Start with Turning on Next Edit Suggestions. There is something to understand, something to try, and something that proves the try worked.

      +

      Alex: First, open Settings: Ctrl+, (Mac: Cmd+,). Then, search for nextEditSuggestions. After that, enable "GitHub Copilot: Next Edit Suggestions". Treat it like a recipe: do not add the next ingredient until the previous one is actually in the bowl.

      +

      Alex: Keep the teaching thread moving. This is where How it works in practice becomes real: nES is announced as an inline suggestion at the predicted location. That matters in practice: With screen reader optimized mode on (Shift+Alt+F1), VS Code announces when a next edit suggestion is available.

      +

      Alex: The practical takeaway is this. 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.

      +

      Jamie: Let's pause on 8. Copilot on GitHub.com. What should a learner take away from it?

      +

      Alex: Keep the learner anchored in 8. Copilot on GitHub.com. You don't need VS Code to use Copilot. This is the part to say slowly: GitHub.com has Copilot built directly into the website -- useful for quick questions, reviewing code in the browser, drafting PR descriptions, and more.

      -

      Alex: Keep the teaching thread moving. Keep the learner anchored in What Are Labels? Labels are colored tags applied to issues and pull requests. This is the part to say slowly: They communicate at a glance what category, priority, or status an item belongs to.

      -

      Jamie: Let's pause on Navigating to the Labels Page. What should a learner take away from it?

      -

      Alex: The reason Navigating to the Labels Page matters is that go to the Issues tab, then click the Labels link/button (it's in the filter toolbar above the issue list, next to Milestones). That gives the learner a simple foothold: the Labels page shows every label with its colour, name, and description.

      -

      Alex: First, navigate to the Issues tab. Then, press K to find the "Labels" link (near the "Milestones" link in the toolbar). After that, press Enter. Finally, quick Nav K to find the "Labels" link (near the "Milestones" link in the toolbar). The rhythm is simple: orient, act, verify, then continue.

      -

      Jamie: Before we leave Navigating to the Labels Page, what is the practical point?

      -

      Alex: First, vO+Space to activate. Think of it as a rail line: each stop confirms you are still on the right route before the next one.

      -

      Alex: Treat examples as spoken recipes, not decorations. You may hear something like List all labels with descriptions; gh label list; List labels in a specific format; gh label list --json name,description. Read the command, understand what it changes, then run it only when the repository state matches the lesson.

      -

      Jamie: Let's pause on Tool Cards: Apply a Label. What should a learner take away from it?

      -

      Alex: Start with Tool Cards: Apply a Label: github.dev (web editor): Not available -- labels are managed on the issue/PR page, not in the code editor. The next useful detail is this: VS Code Desktop (GitHub Pull Requests extension). Think of it like entering a new building: first you find the lobby, then the room, then the door you actually need.

      -

      Alex: First, open the issue or PR. Then, in the right sidebar, click the gear icon next to Labels. After that, select labels from the dropdown, then click outside to apply. Finally, open the issue in the GitHub sidebar panel. Think of it as a rail line: each stop confirms you are still on the right route before the next one.

      -

      Jamie: Before we leave Tool Cards: Apply a Label, what is the practical point?

      -

      Alex: First, click the label area to add or remove labels. Then, navigate to the sidebar → press H or 3 to find the "Labels" heading. After that, activate the Labels gear/edit button (B until you hear "Labels" button → Enter). Finally, dropdown opens showing all available labels: use ↑/↓ to navigate. Treat it like a recipe: do not add the next ingredient until the previous one is actually in the bowl.

      -

      Alex: Treat examples as spoken recipes, not decorations. You may hear something like gh issue edit 42 --add-label "accessibility,good first issue"; gh pr edit 15 --add-label "documentation". 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. Read the command, understand what it changes, then run it only when the repository state matches the lesson.

      +

      Jamie: Let's pause on Opening Copilot Chat on GitHub.com. What should a learner take away from it?

      +

      Alex: The reason Opening Copilot Chat on GitHub.com matters is that Copilot on GitHub.com has context about your repositories, issues, PRs, and code -- you can reference them directly. The interface gets friendlier when it stops being a wall of controls and starts being a set of named places.

      +

      Alex: First, go to github.com -- you must be signed in. Then, look for the Copilot icon (a circle with dot pattern) in the top navigation bar. After that, click it (or press? then select Copilot from the command palette) to open the chat panel. Finally, type your question and press Enter. The rhythm is simple: orient, act, verify, then continue.

      +

      Jamie: Let's pause on Copilot for Pull Request Summaries. What should a learner take away from it?

      +

      Alex: Start with Copilot for Pull Request Summaries: When you open a pull request on GitHub.com, Copilot can generate a description for you automatically. The next useful detail is this: Copilot-generated PR descriptions are usually a solid first draft.

      +

      Alex: First, start creating a new pull request: go to your branch and select "Compare & pull request". Then, in the PR form, look for the Copilot icon next to the description field. After that, click it -- Copilot reads your commits and diff and writes a draft description. Finally, review and edit the draft -- it typically includes what changed and why. Think of it as a rail line: each stop confirms you are still on the right route before the next one.

      +

      Jamie: Before we leave Copilot for Pull Request Summaries, what is the practical point?

      +

      Alex: First, submit the PR. Treat it like a recipe: do not add the next ingredient until the previous one is actually in the bowl.

      +

      Alex: Keep the teaching thread moving. Here is the plain-English version of Copilot for Code Review on GitHub.com. Maintainers can use Copilot to review pull requests on GitHub.com. Put another way, as a contributor, you may see Copilot-authored review comments on your PR -- they look like regular review comments but are labelled "Copilot".

      +

      Alex: The practical takeaway is this. 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.

      -

      Jamie: Let's pause on Filtering Issues by Label. What should a learner take away from it?

      -

      Alex: Here is the plain-English version of Filtering Issues by Label. Screen reader users (NVDA / JAWS - Windows). Put another way, option A - Filter bar: Press F → type is:open label:accessibility → Enter.

      -

      Alex: The practical takeaway is this. 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.

      -

      Alex: Treat examples as spoken recipes, not decorations. You may hear something like 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. Read the command, understand what it changes, then run it only when the repository state matches the lesson.

      -

      Jamie: Let's pause on Creating a New Label. What should a learner take away from it?

      -

      Alex: This is where Creating a New Label becomes real: GitHub CLI (gh) alternative - creating labels. That matters in practice: Accessibility note for color: Labels have color, but they also have a text name and description - the color is supplementary information.

      -

      Alex: First, navigate to Issues → Labels page. Then, tab to "New label" button → Enter. After that, fill in: Label name (F for form field), Color (use the color picker or hex code), Description. Finally, tab to "Create label" button → Enter. It is a checklist, but a meaningful one: every item creates evidence that the next step is safe.

      -

      Alex: Treat examples as spoken recipes, not decorations. You may hear something like 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". Read the command, understand what it changes, then run it only when the repository state matches the lesson.

      -

      Jamie: Let's pause on Learning Cards: Labels. What should a learner take away from it?

      -

      Alex: Start with Learning Cards: Labels. There is something to understand, something to try, and something that proves the try worked.

      -

      Alex: The practical takeaway is this. 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. 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.

      +

      Jamie: Let's pause on Learning Cards: Copilot on GitHub.com. What should a learner take away from it?

      +

      Alex: Start with Learning Cards: Copilot on GitHub.com. There is something to understand, something to try, and something that proves the try worked.

      +

      Alex: The practical takeaway is this. 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. 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.

      +

      Alex: Keep the teaching thread moving. Keep the learner anchored in 9. Effective Prompting for Documentation Work. Copilot works best with clear, specific prompts. This is the part to say slowly: The more context you provide, the better the response. A good GitHub workflow is like a well-run meeting: everyone knows the topic, the next action, and who has the floor.

      +

      Jamie: What is the safe way to learn from that example?

      +

      Alex: Start with Good prompt. There is something to understand, something to try, and something that proves the try worked.

      +

      Alex: Treat examples as spoken recipes, not decorations. You may hear something like 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. Read the command, understand what it changes, then run it only when the repository state matches the lesson.

      -

      Alex: Keep the teaching thread moving. The reason What Are Milestones? matters is that milestones group issues and PRs toward a shared goal or deadline. That gives the learner a simple foothold: think of a milestone as a sprint, a version release, or an event (like "Hackathon Day 1 Deliverables"). The interface gets friendlier when it stops being a wall of controls and starts being a set of named places.

      -

      Alex: The practical takeaway is this. A title and optional description. An optional due date. A progress bar (percentage of closed issues vs total).

      -

      Jamie: Let's pause on Navigating to Milestones. What should a learner take away from it?

      -

      Alex: Start with Navigating to Milestones. There is something to understand, something to try, and something that proves the try worked.

      -

      Alex: First, press K to find the "Milestones" link → Enter. Then, you see a list of milestones, each with its title, progress, and due date. Think of it as a rail line: each stop confirms you are still on the right route before the next one.

      -

      Alex: Keep the teaching thread moving. Here is the plain-English version of Reading a milestone. Each milestone is announced as a heading + progress information.

      -

      Alex: The practical takeaway is this. "Hackathon Day 1 Deliverables, 3 of 8 issues closed, due April 20".

      +

      Jamie: Let's pause on What makes it good. What should a learner take away from it?

      +

      Alex: Start with What makes it good. There is something to understand, something to try, and something that proves the try worked.

      +

      Alex: First, specific scope: "3-paragraph section". Then, clear topic: "navigate the VS Code Explorer sidebar". After that, target audience: "screen reader users" who "never used VS Code". Finally, required details: "keyboard shortcuts for NVDA and JAWS". Think of it as a rail line: each stop confirms you are still on the right route before the next one.

      +

      Jamie: Before we leave What makes it good, what is the practical point?

      +

      Alex: First, format guidance: "headings and bullet points". Treat it like a recipe: do not add the next ingredient until the previous one is actually in the bowl.

      +

      Jamie: How do you keep commands from becoming magic words?

      +

      Alex: Start with Pattern 2: Generate with Constraints. There is something to understand, something to try, and something that proves the try worked.

      +

      Alex: Treat examples as spoken recipes, not decorations. You may hear something like 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. Read the command, understand what it changes, then run it only when the repository state matches the lesson.

      +

      Alex: Keep the teaching thread moving. This is where Iterating on Responses becomes real: Copilot's first response is a draft. The workshop is closer to rehearsal than lecture. You hear the move, try the move, and then check what changed.

      -

      Jamie: Let's pause on Opening a Milestone. What should a learner take away from it?

      -

      Alex: Start with Opening a Milestone. There is something to understand, something to try, and something that proves the try worked.

      -

      Alex: First, press 3 to navigate milestone titles (they are h3 links). Then, press Enter to open a milestone. After that, the milestone detail page shows all issues and PRs belonging to it. Finally, navigate the list with 3 (issue titles) or I (list items). It is a checklist, but a meaningful one: every item creates evidence that the next step is safe.

      -

      Jamie: Let's pause on Adding an Issue to a Milestone. What should a learner take away from it?

      -

      Alex: Keep the learner anchored in Adding an Issue to a Milestone. From the open issue, find the Milestone section in the right sidebar and click the gear icon. This is the part to say slowly: A dropdown lists available milestones - click one to assign it. A good GitHub workflow is like a well-run meeting: everyone knows the topic, the next action, and who has the floor.

      -

      Alex: First, navigate to the sidebar → "Milestone" heading (H or 3). Then, activate the Milestone gear button. After that, select a milestone from the dropdown (↑/↓ → Enter). Finally, esc to close. It is like walking a hallway with named doors: read the sign, enter the right room, then confirm where you landed.

      -

      Jamie: Before we leave Adding an Issue to a Milestone, what is the practical point?

      -

      Alex: First, quick Nav H or VO+Cmd+H to find the "Milestone" heading in the sidebar. Then, quick Nav B to find and activate the Milestone gear button (VO+Space). After that, select a milestone from the dropdown (VO+Down or arrow keys → VO+Space). The rhythm is simple: orient, act, verify, then continue.

      -

      Alex: Treat examples as spoken recipes, not decorations. You may hear something like 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". gh api repos/{owner}/{repo}/milestones -f title="Hackathon Day 1" -f description="Day 1 deliverables". Read the command, understand what it changes, then run it only when the repository state matches the lesson.

      -

      Jamie: Let's pause on Creating a Milestone. What should a learner take away from it?

      -

      Alex: The reason Creating a Milestone matters is that due date field note: The date field may render as a date picker. That gives the learner a simple foothold: screen readers handle date pickers inconsistently - typing the date is most reliable across browsers.

      -

      Alex: The practical takeaway is this. 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.

      -

      Alex: First, navigate to Milestones page. Then, tab to "New milestone" button → Enter. After that, fill in: Title, Description, Due date (optional). Finally, tab to "Create milestone" → Enter. The rhythm is simple: orient, act, verify, then continue.

      +

      Jamie: What should happen before anyone copies and runs it?

      +

      Alex: Keep the learner anchored in Follow-up prompts. Copilot remembers the conversation context - just say what to change.

      +

      Alex: Treat examples as spoken recipes, not decorations. You may hear something like 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. Read the command, understand what it changes, then run it only when the repository state matches the lesson.

      +

      Alex: Keep the teaching thread moving. Start with Learning Cards: Effective Prompting. There is something to understand, something to try, and something that proves the try worked.

      +

      Alex: The practical takeaway is this. 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. 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.

      +

      Jamie: Let's pause on 10. Custom Instructions vs Custom Agents. What should a learner take away from it?

      +

      Alex: Start with 10. Custom Instructions vs Custom Agents: Two distinct tools shape how Copilot behaves. The next useful detail is this: Understanding the difference is critical for working with Accessibility Agents (see Chapter 16: Accessibility Agents).

      -

      Alex: Keep the teaching thread moving. Start with Learning Cards: Milestones. There is something to understand, something to try, and something that proves the try worked.

      -

      Alex: The practical takeaway is this. 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. 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.

      -

      Jamie: Let's pause on Cross-References. What should a learner take away from it?

      -

      Alex: Here is the plain-English version of Cross-References. Cross-references are links between issues, PRs, and commits. Put another way, GitHub automatically renders 42 as a link to issue or PR 42.

      -

      Jamie: Let's pause on Typing a Cross-Reference. What should a learner take away from it?

      -

      Alex: This is where Typing a Cross-Reference becomes real: inside any comment or PR description text area (Focus Mode). The workshop is closer to rehearsal than lecture. You hear the move, try the move, and then check what changed.

      -

      Alex: First, type - a live-search dropdown appears. Then, continue typing the issue number or title fragment. After that, use ↓ to navigate the dropdown → Enter to select. Finally, the 42 link is inserted automatically. It is a checklist, but a meaningful one: every item creates evidence that the next step is safe.

      -

      Jamie: Before we leave Typing a Cross-Reference, what is the practical point?

      -

      Alex: First, type @ followed by a username. Then, a dropdown of suggestions appears. After that, ↓ to navigate → Enter to select. It is like walking a hallway with named doors: read the sign, enter the right room, then confirm where you landed.

      +

      Alex: Keep the teaching thread moving. Here is the plain-English version of Custom Instructions. File.github/copilot-instructions.md. Put another way, purpose: Always-on background guidance for every Copilot interaction. It is like learning a transit route. The names of the stops matter because they tell you whether you are still going the right direction.

      +

      Jamie: Let's pause on What they do. What should a learner take away from it?

      +

      Alex: Start with What they do. There is something to understand, something to try, and something that proves the try worked.

      +

      Alex: The practical takeaway is this. Apply to all code suggestions automatically. Set project-wide standards. Influence tone and style. Provide context about your project's conventions.

      +

      Jamie: Let's pause on Example.github/copilot-instructions.md. What should a learner take away from it?

      +

      Alex: Keep the learner anchored in Example.github/copilot-instructions.md. When active: Every time Copilot generates a suggestion (inline or in Chat).

      +

      Alex: Treat examples as spoken recipes, not decorations. You may hear something like 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. Read the command, understand what it changes, then run it only when the repository state matches the lesson.

      -

      Jamie: Let's pause on When the "Closes" Keyword Fires. What should a learner take away from it?

      -

      Alex: Keep the learner anchored in When the "Closes" Keyword Fires. The Closes 42 keyword must appear in. This is the part to say slowly: It does not fire from comments on the PR.

      -

      Alex: The practical takeaway is this. The PR description (body text). A commit message pushed to the default branch.

      -

      Alex: Keep the teaching thread moving. Start with Learning Cards: Cross-References. There is something to understand, something to try, and something that proves the try worked.

      -

      Alex: The practical takeaway is this. 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. 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.

      -

      Jamie: Let's pause on GitHub Projects. What should a learner take away from it?

      -

      Alex: Start with GitHub Projects: See also: Appendix R: Projects Deep Dive covers advanced project board configuration, custom fields, and automation.

      +

      Jamie: Let's pause on Custom Agents. What should a learner take away from it?

      +

      Alex: The reason Custom Agents matters is that files.github/agents/[name].agent.md. That gives the learner a simple foothold: purpose: On-demand, focused workflows that you deliberately invoke.

      +

      Alex: Keep the teaching thread moving. Start with What they do. There is something to understand, something to try, and something that proves the try worked.

      +

      Alex: The practical takeaway is this. Perform specific, repeatable tasks. Can access specific tools (GitHub API, file system, terminal). Generate structured output (reports, reviews, analysis). Execute multi-step workflows.

      +

      Jamie: Let's pause on Example agent names. What should a learner take away from it?

      +

      Alex: Here is the plain-English version of Example agent names. When active: Only when you type @agent-name in Copilot Chat. Put another way, see Chapter 16: Accessibility Agents for complete agent documentation.

      +

      Alex: The practical takeaway is this. @daily-briefing - Summarize repository activity. @issue-tracker - Find and prioritize issues. @pr-review - Generate PR review documentation. @analytics - Team contribution metrics.

      -

      Alex: Keep the teaching thread moving. Here is the plain-English version of What Is a GitHub Project? GitHub Projects is a built-in project management tool. Put another way, it can display issues and PRs from across multiple repositories in one view. It is like learning a transit route. The names of the stops matter because they tell you whether you are still going the right direction.

      -

      Jamie: Let's pause on Finding a Project. What should a learner take away from it?

      -

      Alex: This is where Finding a Project becomes real: from an organization page or repository.

      -

      Alex: First, navigate to the "Projects" tab. Then, press 3 to navigate project titles (they are h3 links). After that, enter to open a project. It is a checklist, but a meaningful one: every item creates evidence that the next step is safe.

      -

      Alex: Keep the teaching thread moving. Keep the learner anchored in What is announced per row. "Add keyboard navigation to carousel Status: In Progress Assignee: username Priority: High".

      +

      Jamie: What is the judgment call here?

      +

      Alex: Start with Comparison Table. There is something to understand, something to try, and something that proves the try worked.

      +

      Alex: Use the comparison to make a decision, not to recite a table. The main contrasts are: Custom Instructions means Custom Agent. When active means Background - every interaction means On-demand - you type @agent-name. Defined in means.github/copilot-instructions.md means.github/agents/[name].agent.md.

      +

      Jamie: Let's pause on Using Both Together. What should a learner take away from it?

      +

      Alex: Keep the learner anchored in Using Both Together. Custom instructions ensure Copilot follows your accessibility standards on every suggestion. This is the part to say slowly: Custom agents handle specific workflows like auditing, issue tracking, or automated remediation.

      +

      Jamie: Let's pause on Example workflow. What should a learner take away from it?

      +

      Alex: Start with Example workflow. There is something to understand, something to try, and something that proves the try worked.

      +

      Alex: First, your.github/copilot-instructions.md says: "Always check heading hierarchy in Markdown". Then, you invoke @insiders-a11y-tracker to scan recent changes. After that, the agent finds a heading skip (H1 → H3). Finally, you ask Copilot Chat to fix it: "Fix the heading hierarchy in this file". The rhythm is simple: orient, act, verify, then continue.

      +

      Jamie: Before we leave Example workflow, what is the practical point?

      +

      Alex: First, Copilot's fix follows your custom instructions (uses semantic HTML, adds ARIA where needed). Think of it as a rail line: each stop confirms you are still on the right route before the next one.

      -

      Jamie: Let's pause on Navigating a Project - Board View. What should a learner take away from it?

      -

      Alex: Start with Navigating a Project - Board View. There is something to understand, something to try, and something that proves the try worked.

      -

      Alex: Treat examples as spoken recipes, not decorations. You may hear something like 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. Read the command, understand what it changes, then run it only when the repository state matches the lesson.

      -

      Jamie: Let's pause on Adding an Issue to a Project. What should a learner take away from it?

      -

      Alex: Start with Adding an Issue to a Project. There is something to understand, something to try, and something that proves the try worked.

      -

      Alex: First, navigate to the sidebar "Projects" section (H or 3). Then, activate the Projects gear button. After that, select the project from the dropdown. Finally, activate "Add item" button at the bottom of a column/table. Think of it as a rail line: each stop confirms you are still on the right route before the next one.

      -

      Jamie: Before we leave Adding an Issue to a Project, what is the practical point?

      -

      Alex: First, type to search for existing issues. Then, select the issue → it's added to the project. Treat it like a recipe: do not add the next ingredient until the previous one is actually in the bowl.

      -

      Jamie: Let's pause on Learning Cards: GitHub Projects. What should a learner take away from it?

      -

      Alex: Start with Learning Cards: GitHub Projects. There is something to understand, something to try, and something that proves the try worked.

      -

      Alex: The practical takeaway is this. 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. 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.

      +

      Jamie: Let's pause on Writing Accessibility-Focused Custom Instructions. What should a learner take away from it?

      +

      Alex: Start with Writing Accessibility-Focused Custom Instructions: Source: accessibility.github.com/documentation/guide/copilot-instructions/. The next useful detail is this: Custom instructions can be set at three levels.

      +

      Jamie: Let's pause on Do's - What Makes Instructions Effective. What should a learner take away from it?

      +

      Alex: Here is the plain-English version of Do's - What Makes Instructions Effective. Use normative language: MUST, MUST NOT, SHOULD, SHOULD NOT. Put another way, most language models respond well to normative language.

      +

      Alex: Treat examples as spoken recipes, not decorations. You may hear something like 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. Read the command, understand what it changes, then run it only when the repository state matches the lesson.

      +

      Jamie: Let's pause on Focus on team-specific standards, not generic principles. What should a learner take away from it?

      +

      Alex: This is where Focus on team-specific standards, not generic principles becomes real: tell it what your team does specifically.

      -

      Alex: Keep the teaching thread moving. This is where Practical Organization Strategy for the Hackathon becomes real: here is a recommended structure for your Learning Room sandbox project.

      -

      Jamie: Let's pause on Try It: Label and Link. What should a learner take away from it?

      -

      Alex: Keep the learner anchored in Try It: Label and Link. Time: 2 minutes What you need: Browser, signed in to GitHub. This is the part to say slowly: Go to the Learning Room repository and do two things.

      -

      Alex: First, 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. Then, 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. It is like walking a hallway with named doors: read the sign, enter the right room, then confirm where you landed.

      +

      Alex: Keep the teaching thread moving. Keep the learner anchored in Use lists and checklists to structure instructions. Lists provide clear guardrails - Copilot follows them step by step. A good GitHub workflow is like a well-run meeting: everyone knows the topic, the next action, and who has the floor.

      +

      Jamie: Let's pause on Reference and enforce your design system. What should a learner take away from it?

      +

      Alex: The reason Reference and enforce your design system matters is that document which components to use and which are deprecated. That gives the learner a simple foothold: design systems evolve - keep instructions current.

      +

      Alex: Keep the teaching thread moving. Start with Don'ts - Common Instruction Mistakes: Copilot is already trained on WCAG. The next useful detail is this: Pasting the full text wastes context space and dilutes your specific instructions.

      -

      Jamie: What is the final checkpoint?

      -

      Alex: You should be able to point to the evidence, explain the action, and describe what you would do next if this were a real open source project. If you can teach the move back, you have learned it.

      -

      Jamie: And if they get stuck?

      -

      Alex: Read the latest message, not the loudest worry. Check the issue, the branch, the pull request, the status check, or the bot comment. Then ask for help with those facts in hand. That is how professionals collaborate.

      -
      - +

      Jamie: Let's pause on Additional Guidance. What should a learner take away from it?

      +

      Alex: Here is the plain-English version of Additional Guidance. Role-based prompting - You can give Copilot a persona to shape how it responds. Put another way, be specific about skills and responsibilities; avoid broad personas that may introduce unintended assumptions.

      +

      Alex: Keep the teaching thread moving. This is where Accessibility Resources for Custom Instructions becomes real: these resources can help you write better accessibility-focused custom instructions and evaluate Copilot's output. The workshop is closer to rehearsal than lecture. You hear the move, try the move, and then check what changed.

      +

      Alex: The practical takeaway is this. A11y LLM Evaluation Report - GitHub's own evaluation of how well LLMs handle accessibility tasks, with practical benchmarks: Accessibility LLM Evaluation. 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. Markdown Accessibility Review Guidelines - A practical guide for reviewing Markdown output for accessibility, useful as a reference when writing documentation-focused instructions: Markdown Accessibility.

      +

      Jamie: Let's pause on 11. Using Accessible View with Copilot Responses. What should a learner take away from it?

      +

      Alex: Keep the learner anchored in 11. Using Accessible View with Copilot Responses. Copilot Chat responses stream in token by token. This is the part to say slowly: This is visually nice but can fragment screen reader announcements.

      -

      Challenge 09: Merge Day

      -

      Final PR readiness, review signals, merging, and verifying linked issue closure.

      -
      -Read Transcript - Challenge 09: Merge Day - -

      Transcript

      -

      Alex: This is Challenge Coach for Merge Day. I am Alex, and we are going to teach the move before asking you to prove it.

      -

      Jamie: And I am Jamie. I will translate the challenge into the practical questions learners actually have while doing it.

      +

      Alex: Keep the teaching thread moving. Start with Without Accessible View. There is something to understand, something to try, and something that proves the try worked.

      +

      Alex: The practical takeaway is this. 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.

      +

      Jamie: Let's pause on With Accessible View (Alt+F2 / Mac: Option+F2). What should a learner take away from it?

      +

      Alex: Start with With Accessible View (Alt+F2 / Mac: Option+F2). There is something to understand, something to try, and something that proves the try worked.

      +

      Alex: The practical takeaway is this. 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.

      +

      Jamie: Let's pause on Every time you ask Copilot something. What should a learner take away from it?

      +

      Alex: Here is the plain-English version of Every time you ask Copilot something. VS Code December 2025 update: The Accessible View now updates dynamically as responses stream in. Put another way, 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. It is like learning a transit route. The names of the stops matter because they tell you whether you are still going the right direction.

      +

      Alex: First, type your prompt in Chat input. Then, press Ctrl+Enter (Mac: Cmd+Enter) to send. After that, press Alt+F2 (Mac: Option+F2) to open Accessible View - you can open it immediately after sending, before the response finishes. Finally, follow along as the response streams in the Accessible View in real-time. Treat it like a recipe: do not add the next ingredient until the previous one is actually in the bowl.

      +

      Jamie: Before we leave Every time you ask Copilot something, what is the practical point?

      +

      Alex: First, read or re-read any section with Arrow keys. Then, press Escape to close Accessible View and return to Chat. It is a checklist, but a meaningful one: every item creates evidence that the next step is safe.

      -

      Alex: Final PR readiness, review signals, merging, and verifying linked issue closure. That is the task layer. The teaching layer is understanding why the move belongs in a contributor workflow.

      -

      Jamie: So evidence is not just proof for the facilitator. It is part of how the learner understands the workflow.

      -

      Alex: Right. A good challenge produces something inspectable: a comment, issue, branch, commit, pull request, review, or clear note about what happened.

      +

      Jamie: Let's pause on Benefits. What should a learner take away from it?

      +

      Alex: Start with Benefits. There is something to understand, something to try, and something that proves the try worked.

      +

      Alex: The practical takeaway is this. Follow responses live without waiting. Navigate and re-read at your own pace. Code blocks and lists are properly structured. Headings are announced correctly.

      +

      Jamie: Let's pause on When a suggestion appears. What should a learner take away from it?

      +

      Alex: Keep the learner anchored in When a suggestion appears. 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 part to say slowly: This is the recommended workflow for screen reader users.

      +

      Alex: First, don't accept it immediately. Then, press Alt+F2 (Mac: Option+F2). After that, accessible View shows: "Suggestion: [full text of the suggestion]". Finally, read it completely. It is like walking a hallway with named doors: read the sign, enter the right room, then confirm where you landed.

      +

      Jamie: Before we leave When a suggestion appears, what is the practical point?

      +

      Alex: First, to insert the suggestion at your cursor: press Ctrl+/ (Mac: Cmd+/). Then, to close without inserting: press Escape, then Tab to accept or Escape to reject. The rhythm is simple: orient, act, verify, then continue.

      +

      Jamie: Let's pause on Code Blocks in Accessible View. What should a learner take away from it?

      +

      Alex: The reason Code Blocks in Accessible View matters is that when Copilot suggests code or Markdown.

      -

      Jamie: What makes this practice feel low-stakes but still real?

      -

      Alex: Start with Challenge 9: Merge Day: What you will do: Get your Day 1 PR merged into main, verify your changes appear, and celebrate completing Day 1.

      -

      Alex: A solid Git habit is to know which branch you are on, what changed, and what confirmation you expect before you run the next command.

      -

      Alex: The next layer is this. Here is the plain-English version of Merge checklist. Before merging, verify everything is ready. It is like learning a transit route. The names of the stops matter because they tell you whether you are still going the right direction.

      -

      Alex: The practical anchors are these. [ ] Your PR has no merge conflicts (if it does, resolve them first -- see Challenge 7). [ ] Your PR links to your issue with Closes XX. [ ] Your commit message is meaningful. [ ] You have reviewed your own changes one last time.

      -

      Jamie: What does the learner do first, second, and then after that?

      -

      Alex: Start with Instructions. There is something to understand, something to try, and something that proves the try worked.

      -

      Alex: First, open your PR on the Pull requests tab. Then, if all checks pass (green checkmarks), you are ready to merge. After that, select Merge pull request (your facilitator may handle this step). Finally, after the merge, go to the Code tab and verify your changes appear on the main branch. It is a checklist, but a meaningful one: every item creates evidence that the next step is safe.

      -

      Jamie: Turn that into a path someone can follow.

      -

      Alex: First, check that your linked issue was automatically closed. It is like walking a hallway with named doors: read the sign, enter the right room, then confirm where you landed.

      +

      Alex: Keep the teaching thread moving. Start with In Accessible View: NVDA/JAWS: Use Arrow keys to read line by line. The next useful detail is this: Use Ctrl+Home to jump to the start. Think of it like entering a new building: first you find the lobby, then the room, then the door you actually need.

      +

      Alex: The practical takeaway is this. 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.

      +

      Jamie: Let's pause on Learning Cards: Using Accessible View with Copilot Responses. What should a learner take away from it?

      +

      Alex: Start with Learning Cards: Using Accessible View with Copilot Responses. There is something to understand, something to try, and something that proves the try worked.

      +

      Alex: The practical takeaway is this. 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. 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.

      +

      Alex: Keep the teaching thread moving. This is where GitHub.com Shortcuts (Not VS Code) becomes real: these shortcuts work on GitHub.com in your browser, not inside VS Code. That matters in practice: Students sometimes confuse them with Copilot shortcuts because they involve similar key combinations.

      -

      Alex: Now bring the learner back to the room. Keep the learner anchored in Day 1 celebration. Take a moment to appreciate what you accomplished.

      -

      Alex: For a learner, the useful signals are these. You navigated a real GitHub repository. You filed an issue and had a conversation. You created a branch, made changes, and opened a pull request. You survived a merge conflict. You contributed to an open source community.

      -

      Jamie: What would you say to someone who is already bracing for this to be too much?

      -

      Alex: The reason Peer simulation check matters is that leave a wrap-up comment on the peer-simulation issue or PR. That gives the learner a simple foothold: if you have real buddy access, congratulate your buddy on completing Day 1.

      -

      Alex: The useful habit is simple: orient first, act second, verify third. That pause before acting is part of the work.

      -

      Jamie: Give me the sequence, because order matters here.

      -

      Alex: Start with What happens at merge: When your PR from Challenge 6 (or a later challenge) is approved and merged. Think of it like entering a new building: first you find the lobby, then the room, then the door you actually need.

      -

      Alex: First, the "Merge pull request" button turns green. Then, after clicking it, your branch's commits appear on main. After that, the linked issue (from Closes N) automatically closes. Finally, the PR status changes to "Merged" with a purple icon. Think of it as a rail line: each stop confirms you are still on the right route before the next one.

      +

      Jamie: Let's pause on Video Tutorials (Screen Reader Demonstrations). What should a learner take away from it?

      +

      Alex: Keep the learner anchored in Video Tutorials (Screen Reader Demonstrations). GitHub's accessibility team has published screen reader walkthroughs for each major Copilot feature. This is the part to say slowly: These are sourced from the official GitHub Accessibility guide for Copilot in VS Code.

      +

      Alex: The practical takeaway is this. Inline suggestions with a screen reader - accepting, rejecting, and reviewing ghost text suggestions with NVDA. Inline chat with a screen reader - using Ctrl+I to edit code in place with screen reader feedback. Chat view with a screen reader - navigating the Chat panel, reading responses, and using Accessible View. Built-in actions with a screen reader - running Copilot commands from the Command Palette.

      +

      Alex: Keep the teaching thread moving. The reason 13. Critically Evaluating AI Output matters is that Copilot is fast, fluent, and frequently wrong. That gives the learner a simple foothold: 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. The interface gets friendlier when it stops being a wall of controls and starts being a set of named places.

      +

      Jamie: Let's pause on When to Trust Copilot. What should a learner take away from it?

      +

      Alex: Start with When to Trust Copilot: Copilot is at its best when it is generating code that thousands of developers have written before. The next useful detail is this: You can generally trust suggestions that fall into these categories.

      +

      Alex: The practical takeaway is this. 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.

      -

      Jamie: What should the learner prove to themselves after each small task?

      -

      Alex: Here is the plain-English version of Example evidence. Your Day 1 recap evidence might.

      -

      Alex: This is where the talk moves from concept to action. Start with Alternate approaches. There is something to understand, something to try, and something that proves the try worked.

      -

      Alex: The room should hear these as checkpoints. Post your recap as a comment on your challenge issue. Share a summary in the workshop discussion channel. Write a short reflection in a new file on your branch.

      -

      Alex: A solid pull request habit is to separate three questions: what changed, why it changed, and what still needs review. That keeps the conversation useful instead of noisy.

      -

      Jamie: What is the one idea that makes the next few steps less mysterious?

      -

      Alex: Keep the learner anchored in What matters. The learning objective is completing the Day 1 loop: issue to branch to commit to PR to merge. This is the part to say slowly: If you merged at least one PR and can articulate what you learned, you completed this challenge.

      +

      Alex: Keep the teaching thread moving. Here is the plain-English version of When to Verify. Some suggestions look correct at first glance but carry hidden risks. Put another way, always read these carefully before accepting.

      +

      Alex: The practical takeaway is this. 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.

      +

      Jamie: Let's pause on When to Reject. What should a learner take away from it?

      +

      Alex: This is where When to Reject becomes real: delete the suggestion and write the code yourself when you see any of these. That matters in practice: If you are not sure whether a suggestion falls into this category, verify it.

      +

      Alex: The practical takeaway is this. 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.

      +

      Alex: Keep the teaching thread moving. Keep the learner anchored in Common Failure Modes. The table below shows the kinds of mistakes Copilot makes most often. This is the part to say slowly: Recognizing these patterns helps you catch problems before they reach a reviewer. A good GitHub workflow is like a well-run meeting: everyone knows the topic, the next action, and who has the floor.

      -

      Alex: Before the learner moves on. The reason Creating, Reviewing, and Merging Pull Requests with a Screen Reader matters is that see also: Chapter 15: Code Review covers the full review workflow including multi-file diffs and suggested changes. That gives the learner a simple foothold: pull requests are where your work becomes a contribution. The interface gets friendlier when it stops being a wall of controls and starts being a set of named places.

      -

      Jamie: How should they picture the shape of the workshop?

      -

      Alex: Start with Workshop Recommendation (Chapter 6): Chapter 6 is the first PR-validated chapter where students convert issue work into merge-ready contributions.

      -

      Alex: A few details make that real. There are 3. Each challenge should take under 10 minutes each. The evidence is PR metadata, bot checks, and merged issue linkage. The pattern is small change - linked PR - green checks.

      -

      Jamie: How would you walk the room through that step by step?

      -

      Alex: Here is the plain-English version of Chapter 6 Challenge Set. This is the first chapter where you edit files and create branches. Put another way, 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.

      -

      Alex: First, create one small branch change - edit a practice file on a new branch. Then, open a linked PR - use the PR template and include Closes XX. After that, pass required checks - respond to bot feedback until all required checks pass. Treat it like a recipe: do not add the next ingredient until the previous one is actually in the bowl.

      +

      Jamie: Let's pause on The Verification Checklist. What should a learner take away from it?

      +

      Alex: The reason The Verification Checklist matters is that before you accept any non-trivial Copilot suggestion, run through these steps. That gives the learner a simple foothold: keep the Problems panel open (Ctrl+Shift+M) while you work with Copilot.

      +

      Alex: First, does it compile or run? -- Accept the suggestion, save the file, and check for errors in the Problems panel (Ctrl+Shift+M). Then, does it do what I asked? -- Read the code and confirm it matches your intent, not just your prompt. After that, 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. Finally, does it match the project's conventions? -- Check naming, formatting, file organization, and error handling against the existing codebase. The rhythm is simple: orient, act, verify, then continue.

      +

      Jamie: Before we leave The Verification Checklist, what is the practical point?

      +

      Alex: First, did I check any URLs or references it generated? -- Open every link, verify every package name, confirm every API endpoint. Then, would this pass an accessibility review? -- Run it through the checks described below. Think of it as a rail line: each stop confirms you are still on the right route before the next one.

      +

      Alex: Keep the teaching thread moving. Start with Accessibility-Specific Concerns: Copilot generates HTML and UI code based on what it has seen -- and much of the web is inaccessible. The next useful detail is this: Watch for these problems in any suggestion that touches the user interface.

      +

      Alex: The practical takeaway is this. 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.

      +

      Jamie: Let's pause on The Right Mental Model. What should a learner take away from it?

      +

      Alex: Here is the plain-English version of The Right Mental Model. Think of Copilot as a fast typist who has read a lot of code. Put another way, it can reproduce patterns it has seen before, and it can combine those patterns in new ways.

      +

      Alex: The practical takeaway is this. 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.

      -

      Jamie: What is the ordered workflow?

      -

      Alex: This is where Challenge 6.1 Step-by-Step: Create One Small Branch Change becomes real: edit one of the practice files and save your change on a new branch. That matters in practice: your Learning Room repository on GitHub.com, using the web editor.

      -

      Alex: That shows up in the workshop in a few specific ways. 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. 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.

      -

      Alex: First, 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). Then, open the file and activate the pencil icon (Edit this file) button. After that, the file opens in the web editor. Make your change. For. Finally, keep your change small and focused. Edit only what the issue asks for. It is a checklist, but a meaningful one: every item creates evidence that the next step is safe.

      -

      Jamie: Let's pause on Challenge 6.1 Step-by-Step: Create One Small Branch Change. What should a learner take away from it?

      -

      Alex: First, after editing, activate the Commit changes button (green button above the editor). Then, a dialog appears. In the Branch name field, type: fix/yourname-issueXX (replace yourname with your GitHub username, and XX with the issue number). After that, select Create a new branch for this commit and start a pull request. Finally, activate Propose changes. It is like walking a hallway with named doors: read the sign, enter the right room, then confirm where you landed.

      -

      Jamie: Let's pause on Challenge 6.2 Step-by-Step: Open a Linked PR. What should a learner take away from it?

      -

      Alex: Keep the learner anchored in Challenge 6.2 Step-by-Step: Open a Linked PR. AI agents do not just deploy code directly; they submit pull requests. This is the part to say slowly: Learning to edit a file, format it in Markdown, and review a PR today prepares you to audit and approve AI-generated changes tomorrow. A good GitHub workflow is like a well-run meeting: everyone knows the topic, the next action, and who has the floor.

      -

      Alex: The parts worth keeping in working memory are these. "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". A summary of what you changed and why (at least 50 characters).

      -

      Alex: First, in the Title field, write a short description of your change. Then, in the Body field, use the PR template if one is provided. Make sure to. After that, verify the base branch is main and the compare branch is your fix/yourname-issueXX branch. Finally, activate the Create pull request button. It is like walking a hallway with named doors: read the sign, enter the right room, then confirm where you landed.

      -

      Jamie: Let's pause on Challenge 6.3 Step-by-Step: Pass Required Checks. What should a learner take away from it?

      -

      Alex: The reason Challenge 6.3 Step-by-Step: Pass Required Checks matters is that read bot feedback, fix any issues it finds, and get all required checks to pass. That gives the learner a simple foothold: the Conversation tab of your open pull request.

      -

      Alex: On the ground, that means a few things. 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.

      -

      Alex: First, wait approximately 30 seconds after opening the PR. The bot posts a validation comment. Then, read the bot comment carefully. It checks. After that, if the bot reports failures. Finally, repeat step 3 until all required checks show a green checkmark. The rhythm is simple: orient, act, verify, then continue.

      -

      Jamie: Before we leave Challenge 6.3 Step-by-Step: Pass Required Checks, what is the practical point?

      -

      Alex: First, when all checks pass, request a review from a peer or the facilitator. Think of it as a rail line: each stop confirms you are still on the right route before the next one.

      +

      Alex: Keep the teaching thread moving. Start with Learning Cards: Critically Evaluating AI Output. There is something to understand, something to try, and something that proves the try worked.

      +

      Alex: The practical takeaway is this. 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. 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.

      +

      Jamie: Let's pause on Copilot Not Suggesting Anything. What should a learner take away from it?

      +

      Alex: Keep the learner anchored in Copilot Not Suggesting Anything. Issue: No suggestions appear as you type.

      +

      Jamie: Let's pause on Solutions. What should a learner take away from it?

      +

      Alex: Start with Solutions. There is something to understand, something to try, and something that proves the try worked.

      +

      Alex: First, check Copilot is active: status bar icon should not be grayed out. Then, click the Copilot icon → verify "Completions enabled". After that, check subscription status: Ctrl+Shift+P → "Copilot: Check Status". Finally, restart VS Code. The rhythm is simple: orient, act, verify, then continue.

      +

      Jamie: Before we leave Solutions, what is the practical point?

      +

      Alex: First, sign out and sign back in: Ctrl+Shift+P → "Copilot: Sign Out". Think of it as a rail line: each stop confirms you are still on the right route before the next one.

      -

      Alex: Here is the practical turn. Start with Expected Outcomes. There is something to understand, something to try, and something that proves the try worked.

      -

      Alex: Here is what that changes in practice. Student opens a focused PR that maps to one issue. Student uses Closes XX correctly. Student can interpret bot feedback and improve the PR.

      -

      Jamie: Let's pause on If You Get Stuck. What should a learner take away from it?

      -

      Alex: Start with If You Get Stuck. There is something to understand, something to try, and something that proves the try worked.

      -

      Alex: First, confirm your PR includes Closes XX in title or body. Then, check that changed files are only in learning-room/. After that, open the bot validation comment and resolve one required check at a time. Finally, if checks still fail, ask for peer or facilitator review with the exact error message. Treat it like a recipe: do not add the next ingredient until the previous one is actually in the bowl.

      -

      Jamie: Before we leave If You Get Stuck, what is the practical point?

      -

      Alex: First, finished but not sure you did it right? Compare your work against the Challenge 6 reference solution. It is a checklist, but a meaningful one: every item creates evidence that the next step is safe.

      -

      Alex: Keep the thread going. This is where Learning Moment becomes real: a great PR is small, linked to an issue, and easy to review. That matters in practice: Faster feedback builds confidence and momentum. The workshop is closer to rehearsal than lecture. You hear the move, try the move, and then check what changed.

      +

      Jamie: Let's pause on Suggestions Are Too Frequent/Distracting. What should a learner take away from it?

      +

      Alex: Start with Suggestions Are Too Frequent/Distracting: Issue: Constant interruptions from suggestions.

      +

      Jamie: What is the teaching move inside Solutions?

      +

      Alex: First, use word-by-word acceptance: Ctrl+Right Arrow. Then, reduce screen reader verbosity (see Section 3). After that, use Accessible View (Alt+F2) to review suggestions without live announcements. Finally, disable inline suggestions temporarily: Copilot icon → "Disable Completions". Treat it like a recipe: do not add the next ingredient until the previous one is actually in the bowl.

      +

      Jamie: Let's pause on Chat Responses Not Announced. What should a learner take away from it?

      +

      Alex: This is where Chat Responses Not Announced becomes real: issue: Screen reader silent when Copilot responds.

      -

      Jamie: Okay, set the room for us. What are we walking into?

      -

      Alex: Start with Why this feels achievable. There is something to understand, something to try, and something that proves the try worked.

      -

      Alex: These are the details that keep the idea from floating away. Scope is intentionally small. Feedback is immediate and specific. Success is visible (green checks + closed issue).

      -

      Alex: Another way to ground it. The reason About Learning Cards in This Chapter matters is that this chapter provides learning cards: expandable blocks that offer perspective-specific guidance for different ways of working. That gives the learner a simple foothold: not every card appears at every step.

      -

      Jamie: What should they understand before typing anything?

      -

      Alex: Start with Local Git Alternative: The Full Branch-Edit-PR Workflow: If you cloned the learning-room in Block 0 and prefer working locally. The next useful detail is this: The web editor workflow (pencil button, "Propose changes") is the primary path taught in this chapter.

      -

      Alex: Treat examples as spoken recipes, not decorations. You may hear something like cd /Documents/learning-room; git checkout main; git pull origin main; git checkout -b fix/welcome-todos. code docs/welcome.md. Read the command, understand what it changes, then run it only when the repository state matches the lesson.

      +

      Jamie: If someone only remembers one thing from Solutions, what should it be?

      +

      Alex: First, wait for response to complete, then press Alt+F2 for Accessible View. Then, check ARIA live region settings in your screen reader. After that, navigate manually to the response area with Tab or Arrow keys. Finally, use Quick Chat (Ctrl+Shift+Alt+I) instead of panel chat. It is like walking a hallway with named doors: read the sign, enter the right room, then confirm where you landed.

      +

      Jamie: Let's pause on "Copilot Subscription Required". What should a learner take away from it?

      +

      Alex: The reason "Copilot Subscription Required" matters is that issue: Extension installed but asks for subscription.

      +

      Jamie: Let's pause on Solutions. What should a learner take away from it?

      +

      Alex: First, sign in to GitHub: Copilot icon → "Sign in". Then, verify GitHub account has Copilot access (free tier or paid). After that, check github.com/settings/copilot for subscription status. Finally, free tier users: ensure you haven't exceeded monthly limits. Think of it as a rail line: each stop confirms you are still on the right route before the next one.

      -

      Alex: This is the part worth saying out loud. Here is the plain-English version of What Is a Pull Request? A pull request (PR) is a proposal to merge changes from one branch into another. Put another way,.you open a PR to request that those changes be merged into the target branch (usually main). It is like learning a transit route. The names of the stops matter because they tell you whether you are still going the right direction.

      -

      Alex: That becomes easier when you listen for these cues. Edited a file directly on GitHub (web editor). Made changes in your fork. Made changes on a feature branch. What changed - a diff of every file.

      -

      Jamie: Let's pause on Navigating to Pull Requests. What should a learner take away from it?

      -

      Alex: This is where Navigating to Pull Requests becomes real: global pull requests dashboard: GitHub now shows a global pull requests page at github.com/pulls listing all open PRs across every repository you have access to. That matters in practice: 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).

      -

      Alex: The practical takeaway is this. 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.

      -

      Alex: First, d → "Repository navigation" landmark. Then, k to navigate tabs → "Pull requests, [N] open". After that, enter to open. Finally, vO+U → Landmarks → navigate to "Repository navigation". It is a checklist, but a meaningful one: every item creates evidence that the next step is safe.

      -

      Jamie: Before we leave Navigating to Pull Requests, what is the practical point?

      -

      Alex: First, quick Nav K or VO+Right to navigate tabs → "Pull requests". Then, vO+Space to open. It is like walking a hallway with named doors: read the sign, enter the right room, then confirm where you landed.

      -

      Jamie: What should happen before anyone copies and runs it?

      -

      Alex: Keep the learner anchored in From a PR notification. If you received a notification about a PR, follow the notification link directly to the PR page. This is the part to say slowly: List and view pull requests from your terminal.

      -

      Alex: Treat examples as spoken recipes, not decorations. You may hear something like 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. Read the command, understand what it changes, then run it only when the repository state matches the lesson.

      +

      Jamie: Let's pause on Try It: Your First Copilot Conversation. What should a learner take away from it?

      +

      Alex: Here is the plain-English version of Try It: Your First Copilot Conversation. Time: 3 minutes What you need: VS Code with Copilot Chat extension installed. Put another way, you just had a conversation with an AI about your codebase.

      +

      Alex: First, open Copilot Chat - Press Ctrl+Shift+I (Mac: Cmd+Shift+I). Your screen reader announces the chat panel. Then, ask a question - Type: What does the CONTRIBUTING.md file in this repository say about how to submit a pull request? Press Enter. After that, 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. Finally, try a follow-up - Type: Summarize that in 3 bullet points and press Enter. Copilot remembers the context from your first question. Treat it like a recipe: do not add the next ingredient until the previous one is actually in the bowl.

      -

      Jamie: If I am listening before the workshop starts, what should settle in my mind first?

      -

      Alex: Start with Learning Cards: Navigating to Pull Requests. There is something to understand, something to try, and something that proves the try worked.

      -

      Alex: The practical takeaway is this. 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. 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.

      -

      Alex: That matters because of the next idea. Start with The Pull Request List Page: The PR list works identically to the Issues list. The next useful detail is this: for screen reader users, - PR list semantics: The PR list does not have individual ARIA item containers with per-item semantics. Think of it like entering a new building: first you find the lobby, then the room, then the door you actually need.

      -

      Alex: The practical takeaway is this. 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.

      -

      Jamie: Let's pause on Navigating the PR Tab Bar. What should a learner take away from it?

      -

      Alex: Here is the plain-English version of Navigating the PR Tab Bar. The Conversation, Commits, and Files changed tabs are in a "Pull request navigation tabs" landmark. Put another way, the three tabs - Conversation, Commits, and Files changed - appear just below the PR title.

      -

      Alex: The practical takeaway is this. 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.

      -

      Alex: First, press D → navigate to "Pull request navigation tabs". Then, press ← or → arrow keys to move between tab options. After that, press Enter to activate a tab. Finally, vO+U → Landmarks → "Pull request navigation tabs". Treat it like a recipe: do not add the next ingredient until the previous one is actually in the bowl.

      -

      Jamie: Before we leave Navigating the PR Tab Bar, what is the practical point?

      -

      Alex: First, vO+Right to move between tabs. Then, vO+Space to activate. It is a checklist, but a meaningful one: every item creates evidence that the next step is safe.

      +

      Jamie: What is the final checkpoint?

      +

      Alex: You should be able to point to the evidence, explain the action, and describe what you would do next if this were a real open source project. If you can teach the move back, you have learned it.

      +

      Jamie: And if they get stuck?

      +

      Alex: Read the latest message, not the loudest worry. Check the issue, the branch, the pull request, the status check, or the bot comment. Then ask for help with those facts in hand. That is how professionals collaborate.

      +
      +
      -

      Jamie: Let's pause on PR Description. What should a learner take away from it?

      -

      Alex: Start with PR Description. There is something to understand, something to try, and something that proves the try worked.

      -

      Alex: First, 2 → navigate to "Description" h2 heading. Then, ↓ to read the description. After that, markdown renders as semantic HTML - headings, lists, code blocks are fully accessible. It is a checklist, but a meaningful one: every item creates evidence that the next step is safe.

      -

      Jamie: Let's pause on Status Checks Section. What should a learner take away from it?

      -

      Alex: Keep the learner anchored in Status Checks Section. Below the description, the status checks summary shows whether automated tests passed. This is the part to say slowly: Status checks appear as a coloured banner below the PR description - green tick for passed, red X for failed, yellow spinner for running.

      -

      Alex: The practical takeaway is this. "All checks have passed" / "Some checks failed" / "Checks pending". A "Show all checks" button or link.

      -

      Alex: First, press H or 2 to find the "Checks" or "Status checks" heading. Then, press K to navigate links for individual check names. After that, press Enter on a check to see its details. Finally, quick Nav H or VO+Cmd+H to jump to the "Checks" or "Status checks" heading. It is like walking a hallway with named doors: read the sign, enter the right room, then confirm where you landed.

      -

      Jamie: Before we leave Status Checks Section, what is the practical point?

      -

      Alex: First, quick Nav K to navigate check name links. Then, vO+Space on a check to see its details. The rhythm is simple: orient, act, verify, then continue.

      -

      Alex: Hold that next to this. The reason Review Comments matters is that each review comment thread is an h3. The interface gets friendlier when it stops being a wall of controls and starts being a set of named places.

      -

      Alex: The practical takeaway is this. 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.

      +

      45. Episode 16: Issue Templates

      +

      Creating YAML-based issue templates for bug reports, features, and custom forms.

      +

      Based on: Chapter 17: Issue Templates

      +

      Audio and transcript are being regenerated for this episode.

      +
      +Read Transcript - Episode 16: Issue Templates + +

      Transcript

      +

      Alex: Welcome to Git Going with GitHub, episode 16: Issue Templates. I am Alex. Today we are going to make Issue Templates something you can explain, practice, and recover from when the interface surprises you.

      +

      Jamie: And I am Jamie. I will be the voice of the learner who is willing to ask, what is this for, where am I, and how do I know I did it right?

      -

      Jamie: Let's pause on Resolving conversations. What should a learner take away from it?

      -

      Alex: Start with Resolving conversations: When a review comment has been addressed, you can mark the conversation as resolved. The next useful detail is this: Resolved conversations are still accessible - they collapse but can be expanded again.

      -

      Alex: First, navigate to the conversation thread (3 to jump between comment headings). Then, tab to the end of the thread to find the "Resolve conversation" button. After that, press Enter to mark it resolved. Finally, the conversation collapses and shows as "Resolved". Think of it as a rail line: each stop confirms you are still on the right route before the next one.

      -

      Alex: That connects to another useful point. Start with Learning Cards: Reading the Conversation Tab. There is something to understand, something to try, and something that proves the try worked.

      -

      Alex: The practical takeaway is this. 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. 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.

      -

      Jamie: Let's pause on Reading the Checks Tab. What should a learner take away from it?

      -

      Alex: This is where Reading the Checks Tab becomes real: the Checks tab shows the status of automated tests, CI workflows, and other verification processes running on your PR. That matters in practice: It helps you verify whether your changes pass all required tests before merging.

      -

      Alex: The practical takeaway is this. Navigate through the check steps with K or Tab. Activate a step for more details.

      -

      Alex: First, navigate to the "Pull request tabs" landmark (D). Then, navigate between tab links (K or Tab) and activate "Checks". After that, press D to jump to the "check suites" section - this moves focus to the collapsed details button of the first check. Finally, press B or Tab to navigate between check buttons; each button is labeled with the check's name. It is a checklist, but a meaningful one: every item creates evidence that the next step is safe.

      -

      Jamie: Before we leave Reading the Checks Tab, what is the practical point?

      -

      Alex: First, press Enter or Space to expand a check and reveal its logs. Then, for a summary view: press D to navigate to the "check run summary" section. After that, vO+U - Landmarks - "Pull request tabs" - activate "Checks". Finally, vO+U - Landmarks - navigate to "check suites" section. It is like walking a hallway with named doors: read the sign, enter the right room, then confirm where you landed.

      +

      Alex: The big idea today: Creating YAML-based issue templates for bug reports, features, and custom forms. We will name the concept, explain why it matters, practice the move, and point out the checks that tell you the work is real.

      +

      Jamie: So the episode should work even if someone has not read the chapter yet.

      +

      Alex: Exactly. The transcript has to stand on its own. It can point toward practice, but it should teach the concept right here in the conversation.

      -

      Alex: Keep the teaching thread moving. Start with Learning Cards: Reading the Checks Tab. There is something to understand, something to try, and something that proves the try worked.

      -

      Alex: The practical takeaway is this. 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. 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.

      -

      Jamie: Give me the version that sounds like an instructor, not a manual.

      -

      Alex: The reason Reading the Files Changed Tab matters is that the learner will read diffs - the before/after state of every file that changed. That gives the learner a simple foothold: this guide uses GitHub's improved Files Changed experience.

      -

      Jamie: Let's pause on File Tree (left panel). What should a learner take away from it?

      -

      Alex: Start with File Tree (left panel): The file tree lists every changed file. The next useful detail is this: Use it to jump directly to a specific file's diff.

      -

      Alex: The practical takeaway is this. 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.

      -

      Alex: First, d → navigate to "File tree" region. Then, ↑/↓ to navigate the file list. After that, enter to jump to that file's diff. Finally, vO+U → Landmarks → navigate to "File tree" region. Think of it as a rail line: each stop confirms you are still on the right route before the next one.

      -

      Jamie: Before we leave File Tree (left panel), what is the practical point?

      -

      Alex: First, vO+Down to move through the file list. Then, vO+Space to jump to that file's diff. Treat it like a recipe: do not add the next ingredient until the previous one is actually in the bowl.

      +

      Jamie: Okay, set the room for us. What are we walking into?

      +

      Alex: Start with Structuring Contributions for Clarity and Quality: Issue templates turn a blank text box into a guided form. The next useful detail is this: They help contributors provide the information maintainers need, reduce back-and-forth, and make every issue immediately actionable.

      +

      Alex: The next layer is this. Here is the plain-English version of Before starting this chapter, verify you have completed. Day 2 Amplifier: In Chapter 19 (Accessibility Agents), you'll use @template-builder to automate template creation. Put another way, complete this chapter first, then come back to Chapter 19. It is like learning a transit route. The names of the stops matter because they tell you whether you are still going the right direction.

      +

      Alex: The practical anchors are these. [ ] Chapter 4: Working with Issues - 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). [ ] Chapter 16: GitHub Copilot - Optional but helpful for generating template variations.

      +

      Jamie: What should feel predictable before the first live session starts?

      +

      Alex: This is where Workshop Recommendation (Chapter 17 / Challenge 14) becomes real: chapter 17 is a template design and implementation chapter focused on structuring contributions with a concrete, familiar example. That matters in practice: It supports Challenge 14: Template Remix.

      +

      Alex: That shows up in the workshop in a few specific ways. There are 2-3 guided challenges (+ 1 optional). Automation check: none (template structure quality is design-focused). The evidence is issue comment or PR with template remixed or created. The pattern is analyze, remix, create, test.

      -

      Jamie: Where do you want a learner to place their attention here?

      -

      Alex: Start with The Diff for a File. There is something to understand, something to try, and something that proves the try worked.

      -

      Alex: The practical takeaway is this. 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.

      -

      Alex: Keep the teaching thread moving. Start with Lines in a diff are read as. There is something to understand, something to try, and something that proves the try worked.

      -

      Alex: The practical takeaway is this. + Added line - line that was added. Removed line - line that was removed. Context line - unchanged line shown for context.

      -

      Jamie: Let's pause on Navigating the diff with a screen reader. What should a learner take away from it?

      -

      Alex: Keep the learner anchored in Navigating the diff with a screen reader. Each file's diff shows added lines in green and removed lines in red. This is the part to say slowly: Scroll the page to read through changes.

      -

      Alex: The practical takeaway is this. 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.

      -

      Alex: First, t to jump to the next diff table. Then, switch to Focus Mode: Insert+Space (NVDA) or Insert+Z (JAWS). After that, ctrl+Alt+↓ to move down one row (next diff line), Ctrl+Alt+↑ to move up. Finally, ctrl+Alt+→ to read across columns (line number change type content). It is like walking a hallway with named doors: read the sign, enter the right room, then confirm where you landed.

      -

      Jamie: Before we leave Navigating the diff with a screen reader, what is the practical point?

      -

      Alex: First, the screen reader reads: "+ Add accessible name to submit button". Then, collapsed sections contain unchanged code. Focus the expand/disclosure control and activate it (Enter or Space) to reveal the hidden lines. After that, t or VO+U → Tables → select the diff table. Finally, vO+Shift+Down to enter the table. The rhythm is simple: orient, act, verify, then continue.

      +

      Jamie: Turn that into a path someone can follow.

      +

      Alex: Start with Challenge 14 Set. There is something to understand, something to try, and something that proves the try worked.

      +

      Alex: First, analyze the registration template - understand how the template you already filled out works. Then, remix the registration template - adapt it for a new use case (bug report, event, research). After that, create a Markdown template (optional) - build a Markdown-based template from scratch. Finally, test in the template chooser (optional) - verify your template appears and works. It is like walking a hallway with named doors: read the sign, enter the right room, then confirm where you landed.

      +

      Jamie: What is the ordered workflow?

      +

      Alex: The reason Challenge 14.1 Step-by-Step: Analyze the Registration Template matters is that understand how professional YAML form templates work by examining the one you filled out to register for this workshop. That gives the learner a simple foothold: GitHub.com - reading the template file in the git-going-with-github repository.

      +

      Alex: The parts worth keeping in working memory are these. 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.

      +

      Alex: First, open the template file on GitHub.com (use the link above). Then, read the YAML frontmatter (top 5 lines) and identify. After that, read the field types in the body section. Note the four types used. Finally, for each field, identify the metadata. The rhythm is simple: orient, act, verify, then continue.

      +

      Jamie: Give me the sequence, because order matters here.

      +

      Alex: First, search the file for "accessible" - notice the description mentions that all fields work with screen readers. This is professional template thinking. Then, 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. Think of it as a rail line: each stop confirms you are still on the right route before the next one.

      +

      Alex: The useful habit is simple: orient first, act second, verify third. That pause before acting is part of the work.

      +

      Jamie: How would you walk the room through that step by step?

      +

      Alex: Start with Challenge 14.2 Step-by-Step: Remix the Registration Template: Adapt the registration template for a different use case while keeping the same YAML structure. The next useful detail is this: VS Code with a repository where you have write access (your fork or personal repo), or github.dev. Think of it like entering a new building: first you find the lobby, then the room, then the door you actually need.

      +

      Alex: On the ground, that means a few things. Source.github/ISSUE TEMPLATE/workshop-registration.yml. Remix sample: learning-room/docs/samples/challenge-14-registration-remix-example.yml. Keep: the YAML skeleton (name, description, title, labels, body). Keep: field structure (type, id, attributes, validations).

      +

      Alex: First, pick a new context for your template (for example: bug report, event attendance, product research, accessibility audit request). Then, copy the registration template file to a new file.github/ISSUE TEMPLATE/my-template.yml. After that, change the name and description in the frontmatter to match your new context. Finally, change the title prefix (for example: [Bug Report]: or [Event]: ). Think of it as a rail line: each stop confirms you are still on the right route before the next one.

      +

      Jamie: What does the learner do first, second, and then after that?

      +

      Alex: First, change the labels to appropriate labels for your use case. Then, replace each field's label, description, placeholder, and options to match your new context. After that, decide which fields should be required: true and which can be optional. Finally, validate your YAML syntax: copy the file contents to yamllint.com and fix any errors. Treat it like a recipe: do not add the next ingredient until the previous one is actually in the bowl.

      -

      Jamie: Let's pause on Placing an inline comment on a diff line. What should a learner take away from it?

      -

      Alex: The reason Placing an inline comment on a diff line matters is that hover over any line in the diff - a blue + button appears on the left margin. That gives the learner a simple foothold: click it to open a comment box for that line.

      -

      Alex: The practical takeaway is this. 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.

      -

      Alex: First, navigate to the specific line in the diff (using the table navigation above). Then, while focused on that line, a comment button appears - press Enter or Space to activate it. After that, a comment box opens below the line. Finally, focus Mode → type your comment. The rhythm is simple: orient, act, verify, then continue.

      -

      Jamie: Before we leave Placing an inline comment on a diff line, what is the practical point?

      -

      Alex: First, tab to Add single comment button (instant comment) OR Start a review (to batch comments). Think of it as a rail line: each stop confirms you are still on the right route before the next one.

      -

      Jamie: Let's pause on Multi-line comment (Windows). What should a learner take away from it?

      -

      Alex: Start with Multi-line comment (Windows): Screen reader users (VoiceOver - macOS).

      -

      Alex: First, focus the first line you want to comment on. Then, press Shift+↓ to extend the selection to additional lines. After that, a comment button appears - activate it. Finally, the comment applies to the full range of selected lines. Think of it as a rail line: each stop confirms you are still on the right route before the next one.

      -

      Jamie: Before we leave Multi-line comment (Windows), what is the practical point?

      -

      Alex: First, navigate to the specific line in the diff (using the table navigation above). Then, while focused on that line, VO+Space on the comment button that appears. After that, a comment box opens below the line. Finally, vO+Shift+Down to interact with the text area, then type your comment. Treat it like a recipe: do not add the next ingredient until the previous one is actually in the bowl.

      -

      Jamie: Let's pause on Multi-line comment (macOS). What should a learner take away from it?

      -

      Alex: Start with Multi-line comment (macOS). There is something to understand, something to try, and something that proves the try worked.

      -

      Alex: First, focus the first line and Shift+↓ to extend the selection. Then, vO+Space on the comment button that appears. After that, the comment applies to the full range of selected lines. Treat it like a recipe: do not add the next ingredient until the previous one is actually in the bowl.

      +

      Jamie: Let's pause on Challenge 14.3 (Optional) Step-by-Step: Create a Markdown Template. What should a learner take away from it?

      +

      Alex: Here is the plain-English version of Challenge 14.3 (Optional) Step-by-Step: Create a Markdown Template. Create a Markdown-based template to compare the two template formats. Put another way, VS Code with a repository where you have write access.

      +

      Alex: First, create a new file.github/ISSUE TEMPLATE/my-markdown-template.md. Then, add the Markdown template frontmatter at the top. After that, markdown templates use about instead of description (unlike YAML form templates). Finally, below the frontmatter, add 3-4 sections with HTML comment instructions. Treat it like a recipe: do not add the next ingredient until the previous one is actually in the bowl.

      +

      Jamie: Before we leave Challenge 14.3 (Optional) Step-by-Step: Create a Markdown Template, what is the practical point?

      +

      Alex: First, commit and push. It is a checklist, but a meaningful one: every item creates evidence that the next step is safe.

      +

      Jamie: Let's pause on Challenge 14.4 (Optional): Test in the Template Chooser. What should a learner take away from it?

      +

      Alex: This is where Challenge 14.4 (Optional): Test in the Template Chooser becomes real: you are done when: Your template works and appears in the GitHub template picker.

      +

      Alex: First, navigate to your test repository on GitHub.com. Then, activate New Issue. After that, verify your template appears in the template chooser. Finally, activate Get started on your template and file a test issue. It is a checklist, but a meaningful one: every item creates evidence that the next step is safe.

      +

      Jamie: What makes this practice feel low-stakes but still real?

      +

      Alex: Keep the learner anchored in Completing Challenge 14: Submit Your Evidence. Open your assigned Challenge 14 issue and post a completion comment. This is the part to say slowly: Close your Challenge 14 issue when done.

      -

      Jamie: Let's pause on Viewing comments within the diff. What should a learner take away from it?

      -

      Alex: This is where Viewing comments within the diff becomes real: inline comments appear as expandable threads within the diff table. That matters in practice: Navigate to them with 3 (they are h3 headings).

      -

      Alex: Keep the teaching thread moving. Start with Learning Cards: Reading the Files Changed Tab. There is something to understand, something to try, and something that proves the try worked.

      -

      Alex: The practical takeaway is this. 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. 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.

      -

      Jamie: Let's pause on Tool Cards: Open a Pull Request. What should a learner take away from it?

      -

      Alex: The reason Tool Cards: Open a Pull Request matters is that VS Code Desktop (GitHub Pull Requests extension).

      -

      Alex: First, push your branch, then click the Compare & pull request banner (or go to Pull requests New pull request ). Then, set base branch to main, compare branch to yours. After that, fill in the title and description, then click Create pull request. Finally, after committing changes, click the Source Control icon. The rhythm is simple: orient, act, verify, then continue.

      -

      Jamie: Before we leave Tool Cards: Open a Pull Request, what is the practical point?

      -

      Alex: First, click Create Pull Request in the Source Control panel header. Then, fill in details and submit. After that, press Ctrl+Shift+P, type GitHub Pull Requests: Create Pull Request. Finally, select base and compare branches. Think of it as a rail line: each stop confirms you are still on the right route before the next one.

      -

      Alex: Treat examples as spoken recipes, not decorations. You may hear something like git push -u origin your-branch; gh pr create --title "Your title" --body "Description". Read the command, understand what it changes, then run it only when the repository state matches the lesson.

      +

      Alex: Before the learner moves on. Start with Expected Overall Outcomes. There is something to understand, something to try, and something that proves the try worked.

      +

      Alex: That becomes easier when you listen for these cues. 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.

      +

      Jamie: Let's pause on If You Get Stuck. What should a learner take away from it?

      +

      Alex: Start with If You Get Stuck: Continue learning: The GitHub Skills course Introduction to Repository Management covers templates and contributor settings in an interactive format. The next useful detail is this: See Appendix Z for the full catalog.

      +

      Alex: First, cannot find the registration template? Look in.github/ISSUE TEMPLATE/workshop-registration.yml in the git-going-with-github repository. Then, 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. After that, yAML not parsing? Compare with the remix sample in learning-room/docs/samples/challenge-14-registration-remix-example.yml and check indentation. Finally, 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. Think of it as a rail line: each stop confirms you are still on the right route before the next one.

      +

      Jamie: Before we leave If You Get Stuck, what is the practical point?

      +

      Alex: First, 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. Then, remix approach feels overwhelming? Start by changing just the field labels and descriptions. Do not change the structure yet. After that, ask facilitator to review your template and suggest improvements. Finally, finished but not sure you did it right? Compare your work against the Challenge 14 reference solution. Treat it like a recipe: do not add the next ingredient until the previous one is actually in the bowl.

      +

      Alex: Hold that next to this. Here is the plain-English version of Learning Moment. They do not restrict expert contributors - they guide newcomers. Put another way, a template that takes 2 minutes to understand saves 30 minutes of back-and-forth questions later.

      -

      Jamie: Let's pause on From the web editor workflow (editing a file on GitHub). What should a learner take away from it?

      -

      Alex: Start with From the web editor workflow (editing a file on GitHub). There is something to understand, something to try, and something that proves the try worked.

      -

      Alex: First, you edited a file → GitHub showed a "Propose changes" form. Then, you named your branch and activated "Propose changes". After that, GitHub redirected you to the "Open a pull request" page. Think of it as a rail line: each stop confirms you are still on the right route before the next one.

      -

      Jamie: Let's pause on From a fork or feature branch. What should a learner take away from it?

      -

      Alex: Here is the plain-English version of From a fork or feature branch. Screen reader users (NVDA / JAWS - Windows). Put another way, screen reader users (VoiceOver - macOS).

      -

      Alex: First, navigate to the repository on GitHub. Then, if you recently pushed, a yellow banner "Compare & pull request" appears at the top - click it. After that, if no banner appears: click the Pull requests tab → click the green New pull request button. Finally, use the branch dropdowns to choose your base branch (what to merge into) and your compare branch (your changes). Treat it like a recipe: do not add the next ingredient until the previous one is actually in the bowl.

      -

      Jamie: Before we leave From a fork or feature branch, what is the practical point?

      -

      Alex: First, click Create pull request. Then, navigate to the repository. After that, a "Compare & pull request" banner may appear (if you recently pushed) - activate it. Finally, oR: Navigate to Pull Requests tab → "New pull request". It is a checklist, but a meaningful one: every item creates evidence that the next step is safe.

      -

      Jamie: How do you keep commands from becoming magic words?

      -

      Alex: This is where Description field becomes real: Copilot can write your PR description: If your account has Copilot access, a "Copilot actions" button appears in the description toolbar. That matters in practice: 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.

      -

      Alex: Treat examples as spoken recipes, not decorations. You may hear something like Step 1: Tab to the body text area; Step 2: Focus Mode → type using the PR template (if provided). 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 for the dismiss control; Related Issues; Closes 42; Testing; - Tested with NVDA + Chrome on Windows 11; -. Read the command, understand what it changes, then run it only when the repository state matches the lesson.

      +

      Jamie: Let's pause on Learning Pattern Used in This Chapter. What should a learner take away from it?

      +

      Alex: Start with Learning Pattern Used in This Chapter. There is something to understand, something to try, and something that proves the try worked.

      +

      Alex: First, analyze an existing, working example before building your own. Then, remix by changing content while keeping structure (safe, fast iteration). After that, create from scratch only after you understand the pattern (Markdown template). Finally, test the result in the real environment (template chooser). It is a checklist, but a meaningful one: every item creates evidence that the next step is safe.

      +

      Alex: That connects to another useful point. Keep the learner anchored in 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. A good GitHub workflow is like a well-run meeting: everyone knows the topic, the next action, and who has the floor.

      +

      Alex: For a learner, the useful signals are these. Instructions explaining what information is needed. Section headers guiding them through the report. Checkboxes for conditions to verify. Placeholder text showing the expected format.

      +

      Alex: A solid issue habit is to read the title, the body, and the timeline before acting. You are listening for the requested action, the missing evidence, and the person who needs a response.

      +

      Jamie: What is the one idea that makes the next few steps less mysterious?

      +

      Alex: The reason Why they matter for accessibility projects matters is that accessibility bugs require specific context that general bug templates often omit. That gives the learner a simple foothold: without this context, maintainers ask follow-up questions - which delays the fix and uses everyone's time.

      +

      Alex: Here is what that changes in practice. Which screen reader and version? Which browser and version? Which operating system? Which WCAG success criterion is affected?

      +

      Alex: A solid pull request habit is to separate three questions: what changed, why it changed, and what still needs review. That keeps the conversation useful instead of noisy.

      -

      Jamie: Let's pause on Setting a Draft PR. What should a learner take away from it?

      -

      Alex: Keep the learner anchored in Setting a Draft PR. If your work is not finished, open as a Draft.

      -

      Alex: First, after filling in the form, find the dropdown arrow next to "Create pull request". Then, select "Create draft pull request". After that, this signals to reviewers that it is not ready for formal review yet. It is like walking a hallway with named doors: read the sign, enter the right room, then confirm where you landed.

      -

      Alex: Keep the teaching thread moving. The reason Draft Pull Requests - Full Lifecycle matters is that a draft pull request is a PR explicitly marked as a work in progress. That gives the learner a simple foothold: it is visible to the team, can receive comments, and runs CI - but is blocked from being merged until you mark it ready. The interface gets friendlier when it stops being a wall of controls and starts being a set of named places.

      -

      Jamie: Let's pause on When to use a draft. What should a learner take away from it?

      -

      Alex: Start with When to use a draft. There is something to understand, something to try, and something that proves the try worked.

      -

      Alex: The practical takeaway is this. You want to show your approach and get early feedback before finishing. You need CI to run but don't want accidental merges. You are working across multiple days and want your progress visible. You want to pair with a collaborator on the work.

      +

      Alex: Here is the practical turn. Start with 2. How Templates Work on GitHub: Templates live in a specific folder in your repository.

      +

      Jamie: What would you say to someone who is already bracing for this to be too much?

      +

      Alex: Here is the plain-English version of Description. Templates live inside your-repo/.github/. Put another way, 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).

      +

      Alex: Keep the thread going. This is where Example config.yml becomes real: with blank issues enabled: false, the "Open a blank issue" link disappears from the template chooser. That matters in practice: Contributors must use one of your structured templates or one of the contact links. The workshop is closer to rehearsal than lecture. You hear the move, try the move, and then check what changed.

      -

      Alex: Keep the teaching thread moving. Start with What a draft PR does differently. There is something to understand, something to try, and something that proves the try worked.

      -

      Alex: The practical takeaway is this. The merge button is disabled - even an authorized maintainer cannot merge a draft. The PR header shows a grey "Draft" badge instead of the green "Open" badge. Reviewers are not auto-notified (no review requests are sent until ready). CI workflows still run normally.

      -

      Jamie: Let's pause on Mark a draft ready for review. What should a learner take away from it?

      -

      Alex: Start with Mark a draft ready for review. There is something to understand, something to try, and something that proves the try worked.

      -

      Alex: First, open the PR. Then, navigate to the "Reviewers" sidebar or scroll to bottom of the Conversation tab. After that, find and activate the "Ready for review" button. Finally, the draft badge changes to "Open" and reviewers are notified. It is a checklist, but a meaningful one: every item creates evidence that the next step is safe.

      -

      Jamie: Let's pause on Convert an open PR to draft (after opening). What should a learner take away from it?

      -

      Alex: Keep the learner anchored in Convert an open PR to draft (after opening). GitHub CLI (gh) alternative - draft PR lifecycle. This is the part to say slowly: Manage draft PRs from your terminal. A good GitHub workflow is like a well-run meeting: everyone knows the topic, the next action, and who has the floor.

      -

      Alex: First, in the right sidebar, find the "Reviewers" section. Then, look for the "Convert to draft" link (below the review status). After that, confirm in the dialog - this removes merge eligibility until you mark it ready again. It is like walking a hallway with named doors: read the sign, enter the right room, then confirm where you landed.

      -

      Alex: Treat examples as spoken recipes, not decorations. You may hear something like Create a draft PR; gh pr create --draft --title "WIP: Add carousel keyboard nav"; Mark a draft ready for review; gh pr ready 42; Check PR status (shows draft state); gh pr view 42; List only draft PRs; gh pr list --draft. Read the command, understand what it changes, then run it only when the repository state matches the lesson.

      +

      Jamie: If I am listening before the workshop starts, what should settle in my mind first?

      +

      Alex: Start with Learning Cards: How Templates Work on GitHub. There is something to understand, something to try, and something that proves the try worked.

      +

      Alex: These are the details that keep the idea from floating away. 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. 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.

      +

      Jamie: Let's pause on 3. Navigating the Template Picker. What should a learner take away from it?

      +

      Alex: The reason 3. Navigating the Template Picker matters is that when a repository has multiple templates, GitHub shows a template chooser page before the issue editor. That gives the learner a simple foothold: screen reader users - NVDA / JAWS (Windows).

      +

      Alex: First, click the Issues tab on any repository. Then, click the New issue button. After that, the template chooser page loads - templates appear as cards with a title, description, and "Get started" button. Finally, click "Get started" on the template you want. The rhythm is simple: orient, act, verify, then continue.

      +

      Jamie: Before we leave 3. Navigating the Template Picker, what is the practical point?

      +

      Alex: First, the issue editor opens with that template's content pre-filled. Then, navigate to the Issues tab (press T from the repository tabs landmark). After that, activate "New issue" button. Finally, the template chooser page loads. Think of it as a rail line: each stop confirms you are still on the right route before the next one.

      +

      Jamie: Where do you want a learner to place their attention here?

      +

      Alex: Start with Bypassing the Chooser: If you want to file an issue without using a template.

      +

      Alex: A few details make that real. Scroll past all templates to the bottom of the chooser page. Activate "Open a blank issue".

      -

      Jamie: Let's pause on Learning Cards: Opening a Pull Request. What should a learner take away from it?

      -

      Alex: Start with Learning Cards: Opening a Pull Request. There is something to understand, something to try, and something that proves the try worked.

      -

      Alex: The practical takeaway is this. After editing a file on GitHub, the "Propose changes" form has a branch name field and a commit message field; press Tab to move between them. On the "Open a pull request" page, press F to jump to the Title field; Tab moves to the Description text area. Press Ctrl+Enter from inside the description text area to submit the PR without finding the Create button. The "Compare & pull request" yellow banner appears at the top of the repo after a recent push; at high zoom it may span the full width of the page. The branch comparison dropdowns (base and compare) use small text; zoom in on the area above the diff preview to read them. Draft PR: look for the dropdown arrow next to the green "Create pull request" button to switch to "Create draft pull request".

      -

      Jamie: Let's pause on Requesting reviewers. What should a learner take away from it?

      -

      Alex: Start with Requesting reviewers: From the sidebar Reviewers section. The next useful detail is this: Why some reviews are requested automatically: A file called CODEOWNERS in many repositories maps file paths to specific people or teams.

      -

      Alex: First, navigate to "Reviewers" heading (3 or H). Then, activate the gear button. After that, type a username in the search field. Finally, select from the dropdown. Think of it as a rail line: each stop confirms you are still on the right route before the next one.

      -

      Jamie: Before we leave Requesting reviewers, what is the practical point?

      -

      Alex: First, escape to save. Treat it like a recipe: do not add the next ingredient until the previous one is actually in the bowl.

      -

      Jamie: Let's pause on Submitting a Review. What should a learner take away from it?

      -

      Alex: Here is the plain-English version of Submitting a Review. When you are asked to review a PR, you have three options.

      -

      Alex: The practical takeaway is this. Comment - leave feedback without a verdict; does not block merging. Approve - signal you are satisfied; often required before merge. Request changes - indicate changes must be addressed; blocks merge until resolved.

      +

      Alex: This is the part worth saying out loud. Start with Learning Cards: Navigating the Template Picker. There is something to understand, something to try, and something that proves the try worked.

      +

      Alex: The room should hear these as checkpoints. 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. 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.

      +

      Jamie: Let's pause on 4. The Accessibility Agents Issue Templates. What should a learner take away from it?

      +

      Alex: This is where 4. The Accessibility Agents Issue Templates becomes real: accessibility Agents uses templates to structure contributions. That matters in practice: Navigate to.github/ISSUE TEMPLATE/ in the repository to read them.

      +

      Alex: First, click the Code tab on the repository. Then, click the.github folder in the file listing. After that, click ISSUE TEMPLATE. Finally, you'll see the template files - click any to read it. It is a checklist, but a meaningful one: every item creates evidence that the next step is safe.

      +

      Jamie: Before we leave 4. The Accessibility Agents Issue Templates, what is the practical point?

      +

      Alex: First, open the Code tab. Then, use Ctrl+Alt+Down/Up (NVDA/JAWS) or VO+Arrow (VoiceOver) in the files table to reach the.github folder. After that, activate the folder. Finally, activate ISSUE TEMPLATE. It is like walking a hallway with named doors: read the sign, enter the right room, then confirm where you landed.

      +

      Alex: Now bring the learner back to the room. Keep the learner anchored in 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").

      +

      Alex: The practical takeaway is this. Frontmatter (between --- delimiters): name, about, title, labels, assignees.

      -

      Alex: Keep the teaching thread moving. This is where Starting a review becomes real: on the Files Changed tab, when you add inline comments, choose "Start a review" instead of "Add single comment." This batches all your comments into one review submission. The workshop is closer to rehearsal than lecture. You hear the move, try the move, and then check what changed.

      -

      Jamie: Let's pause on Completing and submitting a review. What should a learner take away from it?

      -

      Alex: Keep the learner anchored in Completing and submitting a review. After adding your inline comments via "Start a review," you must submit the review to notify the PR author. This is the part to say slowly: The review is pending until you submit it.

      -

      Alex: The practical takeaway is this. The button may scroll off-screen to the right. Use horizontal scrolling or press Tab from the page top to cycle through focusable elements until you reach it. When clicked, a popover appears with a summary text area and three radio buttons ( Comment, Approve, Request changes ). At 200%+ zoom, the popover may extend below the visible viewport. Scroll down within the popover to see the Submit review button. The radio buttons are standard HTML radio buttons. In Windows High Contrast mode, the selected radio button uses the system highlight color. Keyboard shortcut: If the button is hard to find visually, press Ctrl+Shift+Enter from within any review comment text area to open the submit review dialog directly.

      -

      Alex: First, look for the Finish your review button in the top-right area of the Files Changed tab (it shows the number of pending comments). Then, click it - a popover appears with a summary text area and three radio buttons: Comment, Approve, Request changes. After that, optionally type a summary comment. Finally, select your verdict by clicking the radio button. It is like walking a hallway with named doors: read the sign, enter the right room, then confirm where you landed.

      -

      Jamie: Before we leave Completing and submitting a review, what is the practical point?

      -

      Alex: First, click Submit review. Then, press 1 to go to the h1 (PR title). After that, press B (or Tab) to navigate to the "Submit review" button and activate it (Enter/Space). Finally, a "Submit review" dialog/panel appears. The rhythm is simple: orient, act, verify, then continue.

      -

      Alex: Treat examples as spoken recipes, not decorations. You may hear something like View the PR diff in your terminal; gh pr diff 42; Approve a PR; gh pr review 42 --approve; Approve with a comment; gh pr review 42 --approve --body "Looks good - heading hierarchy is correct."; Request changes; gh pr review 42 --request-changes --body "The alt. Read the command, understand what it changes, then run it only when the repository state matches the lesson.

      -

      Alex: Keep the teaching thread moving. The reason GitHub shortcuts for pull requests matters is that these are the GitHub built-in shortcuts for PR pages. That gives the learner a simple foothold: enable Focus Mode first (NVDA: NVDA+Space, JAWS: Insert+Z) before using single-key shortcuts.

      +

      Jamie: Give me the version that sounds like an instructor, not a manual.

      +

      Alex: The reason Example frontmatter matters is that the about text appears in the template chooser. That gives the learner a simple foothold: the title pre-fills the issue title field (the contributor replaces the placeholder).

      +

      Jamie: Let's pause on Tool Cards: Create an Issue Template. What should a learner take away from it?

      +

      Alex: Start with Tool Cards: Create an Issue Template. There is something to understand, something to try, and something that proves the try worked.

      +

      Alex: First, go to Settings General (scroll to Features section) Set up templates. Then, choose a starter template or create a blank one. After that, edit the template content and click Propose changes to commit. Finally, create the file.github/ISSUE TEMPLATE/your-template.md (or.yml for form-based). Think of it as a rail line: each stop confirms you are still on the right route before the next one.

      +

      Jamie: Before we leave Tool Cards: Create an Issue Template, what is the practical point?

      +

      Alex: First, add YAML frontmatter (name, description, title, labels) and body content. Then, commit and push. Treat it like a recipe: do not add the next ingredient until the previous one is actually in the bowl.

      +

      Alex: Treat examples as spoken recipes, not decorations. You may hear something like 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. Read the command, understand what it changes, then run it only when the repository state matches the lesson.

      +

      Jamie: Let's pause on Choosing Between Markdown and YAML Templates. What should a learner take away from it?

      +

      Alex: Here is the plain-English version of Choosing Between Markdown and YAML Templates. See also: Appendix Q: GitHub Actions covers how templates connect to automated workflows. Put another way, before creating a template, decide which format best suits your needs.

      -

      Jamie: Let's pause on On the PR list page. What should a learner take away from it?

      -

      Alex: Start with On the PR list page: Shortcut note: For G P, press G, release it, then press P (two sequential key presses, not simultaneous).

      -

      Alex: Keep the teaching thread moving. Here is the plain-English version of On the Files Changed tab. For the full shortcut system, see Screen Reader Cheat Sheet - GitHub Shortcuts section. It is like learning a transit route. The names of the stops matter because they tell you whether you are still going the right direction.

      -

      Jamie: Let's pause on Learning Cards: Submitting a Review. What should a learner take away from it?

      -

      Alex: Start with Learning Cards: Submitting a Review. There is something to understand, something to try, and something that proves the try worked.

      -

      Alex: The practical takeaway is this. The review verdict controls are inside a popover triggered by the "Finish your review" button; press 1 to return to the h1 (PR title), then B or Tab forward to find the button -- it is easy to miss because it is not a landmark. Inside the popover, Tab past the summary text area to reach a radio group labeled "Review Event"; use Up/Down Arrow to switch between Comment, Approve, and Request Changes. Shortcut: press Ctrl+Shift+Enter from any review comment text area to open the submit review dialog directly, bypassing the search for the button. The "Finish your review" button sits in the top-right corner of the Files Changed tab with a small badge showing your pending comment count; at 200%+ zoom it may scroll off-screen to the right. Inside the submit popover, the three radio buttons (Comment, Approve, Request changes) are small standard HTML radios; zoom in on the popover area or use Tab to step between them. After submitting, your review verdict appears as a colored banner in the Conversation timeline: green for Approve, red for Request Changes, grey for Comment.

      +

      Alex: That matters because of the next idea. Start with Use Markdown templates when. There is something to understand, something to try, and something that proves the try worked.

      +

      Alex: The practical takeaway is this. 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.

      +

      Jamie: Let's pause on Use YAML form templates when. What should a learner take away from it?

      +

      Alex: Keep the learner anchored in Use YAML form templates when. For accessibility projects: YAML form templates are strongly recommended. This is the part to say slowly: Accessibility bug reports require specific context (screen reader, browser, OS, version numbers) that Markdown templates rely on contributors to remember.

      +

      Alex: The practical takeaway is this. 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.

      +

      Alex: This is where the talk moves from concept to action. The reason Markdown Template Structure matters is that a Markdown template consists of two parts. That gives the learner a simple foothold: yAML Frontmatter (between --- delimiters). The interface gets friendlier when it stops being a wall of controls and starts being a set of named places.

      -

      Alex: Keep the teaching thread moving. Keep the learner anchored in Suggested Changes. A suggested change is a special form of inline review comment where the reviewer proposes exact replacement text. This is the part to say slowly: The PR author can apply the suggestion directly from GitHub - no copy-paste or separate commit needed.

      -

      Jamie: Let's pause on As a reviewer - inserting a suggestion. What should a learner take away from it?

      -

      Alex: The reason As a reviewer - inserting a suggestion matters is that the suggestion block is plain Markdown text in the comment editor. That gives the learner a simple foothold: (Three backticks, the word suggestion, Enter, your text, Enter, three backticks.).

      -

      Alex: First, on the Files Changed tab, navigate to the line you want to propose a change. Then, activate the line comment button for that line (the + that appears on hover, or Tab to navigate to it). After that, in the comment text area that opens, press Ctrl+G (Windows) or Cmd+G (Mac). Finally, GitHub wraps a suggestion block around the current line content. The rhythm is simple: orient, act, verify, then continue.

      -

      Jamie: Before we leave As a reviewer - inserting a suggestion, what is the practical point?

      -

      Alex: First, edit the text inside the suggestion block to show your proposed change. Then, add context above the block if helpful: "This makes the alt text more descriptive:". After that, submit as part of your review ("Start a review" → batch with other comments). Think of it as a rail line: each stop confirms you are still on the right route before the next one.

      -

      Jamie: Let's pause on As an author - applying a suggestion. What should a learner take away from it?

      -

      Alex: Start with As an author - applying a suggestion. There is something to understand, something to try, and something that proves the try worked.

      -

      Alex: First, open the PR Conversation or Files Changed tab. Then, navigate to the inline comment containing a suggestion (it shows a diff-style preview). After that, find and activate the "Apply suggestion" button below the suggestion block. Finally, GitHub creates a commit automatically that applies the change - no file editing required. Think of it as a rail line: each stop confirms you are still on the right route before the next one.

      -

      Jamie: Before we leave As an author - applying a suggestion, what is the practical point?

      -

      Alex: First, the conversation thread is marked as resolved. Treat it like a recipe: do not add the next ingredient until the previous one is actually in the bowl.

      +

      Jamie: What is the safe way to learn from that example?

      +

      Alex: Start with 2. Markdown Body: The template content that pre-fills the issue editor.

      +

      Alex: Treat examples as spoken recipes, not decorations. You may hear something like 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. Read the command, understand what it changes, then run it only when the repository state matches the lesson.

      +

      Alex: Another way to ground it. Start with Markdown template tips. There is something to understand, something to try, and something that proves the try worked.

      +

      Alex: The practical takeaway is this. 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.

      +

      Jamie: Let's pause on Complete Markdown Template Example. What should a learner take away from it?

      +

      Alex: This is where Complete Markdown Template Example becomes real: here's a complete accessibility bug report template in Markdown format. That matters in practice: Save this as.github/ISSUE TEMPLATE/accessibility-bug-simple.md.

      -

      Jamie: Let's pause on Batching multiple suggestions into one commit. What should a learner take away from it?

      -

      Alex: Start with Batching multiple suggestions into one commit. There is something to understand, something to try, and something that proves the try worked.

      -

      Alex: First, for each suggestion you want to apply, activate "Add suggestion to batch" instead of "Apply suggestion". Then, after selecting all suggestions, activate the "Commit suggestions" button that appears at the top. After that, GitHub applies all batched suggestions in a single commit. Treat it like a recipe: do not add the next ingredient until the previous one is actually in the bowl.

      -

      Jamie: Let's pause on When to use suggestions vs. comments. What should a learner take away from it?

      -

      Alex: Start with When to use suggestions vs. comments. There is something to understand, something to try, and something that proves the try worked.

      -

      Alex: The practical takeaway is this. Use a suggestion when you know the exact text that would fix the issue. Use a plain comment when the change requires judgment from the author (e.g., "this alt text isn't descriptive - can you describe what the image shows?"). A summary text area for overall comments. Radio buttons for Comment / Approve / Request changes.

      -

      Alex: First, after adding all your inline comments, navigate to the review summary button. Then, on Files Changed tab: find the "Review changes" button (B to navigate buttons). After that, press Enter to open the review dialog. Finally, a panel opens. It is a checklist, but a meaningful one: every item creates evidence that the next step is safe.

      -

      Jamie: Before we leave When to use suggestions vs. comments, what is the practical point?

      -

      Alex: First, switch to Focus Mode → type your summary comment. Then, navigate to the radio buttons with arrow keys → select your verdict. After that, tab to "Submit review" button → Enter. It is like walking a hallway with named doors: read the sign, enter the right room, then confirm where you landed.

      -

      Jamie: Let's pause on Learning Cards: Suggested Changes. What should a learner take away from it?

      -

      Alex: Start with Learning Cards: Suggested Changes. There is something to understand, something to try, and something that proves the try worked.

      -

      Alex: The practical takeaway is this. To insert a suggestion block, press Ctrl+G (Windows) or Cmd+G (Mac) in the comment text area; the screen reader announces the inserted fence -- arrow down to edit the text between the backtick lines. Alternatively type the block manually: three backticks, the word suggestion, Enter, your replacement text, Enter, three backticks -- this avoids relying on the keyboard shortcut. As a PR author, navigate to a suggestion comment with 3, then Tab to the "Apply suggestion" button; GitHub commits the change automatically with no file editing required. Suggestion blocks render as a mini inline diff: the original line in red/pink background and your proposed replacement in green background; in high-contrast mode these use system diff colors. The "Apply suggestion" button is small and sits below the suggestion diff preview; zoom into the comment area to find it, or Tab from the suggestion text to reach it. When batching multiple suggestions, a floating "Commit suggestions" bar appears at the top of the page; at high zoom scroll up or press Home to find it.

      +

      Alex: Keep the teaching thread moving. Start with When to use this Markdown version instead of YAML. There is something to understand, something to try, and something that proves the try worked.

      +

      Alex: The practical takeaway is this. 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.

      +

      Jamie: Let's pause on Markdown template accessibility considerations. What should a learner take away from it?

      +

      Alex: Start with Markdown template accessibility considerations. There is something to understand, something to try, and something that proves the try worked.

      +

      Alex: The practical takeaway is this. 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.

      +

      Jamie: Let's pause on Creating Markdown Templates: The Manual Workflow (Browser). What should a learner take away from it?

      +

      Alex: Start with Creating Markdown Templates: The Manual Workflow (Browser): Screen reader users (NVDA / JAWS / VoiceOver). The next useful detail is this: Alternative: Navigate directly to.github/ISSUE TEMPLATE/ → activate the "+" button → "Create new file".

      +

      Alex: The practical takeaway is this. Template name: what appears in the chooser heading. About: the description in the chooser. Template content: the Markdown body.

      +

      Alex: First, navigate to your fork of accessibility-agents on GitHub. Then, click the Settings tab. After that, scroll to the "Features" section → click the checkmark next to "Issues" → click "Set up templates". Finally, or navigate directly to.github/ISSUE TEMPLATE/ in your fork → click the + button → "Create new file". Think of it as a rail line: each stop confirms you are still on the right route before the next one.

      +

      Jamie: Before we leave Creating Markdown Templates: The Manual Workflow (Browser), what is the practical point?

      +

      Alex: First, GitHub opens a template editor. Fill in the template name, about description, and body. Then, GitHub auto-populates the filename - you can change it. After that, click "Propose changes" → create a PR to add the template. Finally, go to the Settings tab (press T from the tabs landmark, then navigate to "Settings"). Treat it like a recipe: do not add the next ingredient until the previous one is actually in the bowl.

      -

      Jamie: What is the safe way to learn from that example?

      -

      Alex: The reason Understanding Merge Options (for Maintainers) matters is that when a PR is approved and checks pass, a maintainer can merge it. That gives the learner a simple foothold: the merge button section appears at the bottom of the Conversation tab. The interface gets friendlier when it stops being a wall of controls and starts being a set of named places.

      -

      Alex: Treat examples as spoken recipes, not decorations. You may hear something like Merge with default strategy (merge commit); gh pr merge 42; Squash and merge; gh pr merge 42 --squash; Rebase and merge; gh pr merge 42 --rebase; Delete the branch after merging; gh pr merge 42 --squash --delete-branch; Enable auto-merge (merges when checks. Read the command, understand what it changes, then run it only when the repository state matches the lesson.

      -

      Jamie: Let's pause on After a PR is merged. What should a learner take away from it?

      -

      Alex: Start with After a PR is merged: for screen reader users, - deleting the branch after merge: Navigate to the "Add a comment" section (D), then press Shift+B to navigate backwards to the "Delete branch" button and activate it. The next useful detail is this: This keeps your repository clean by removing the now-merged feature branch.

      -

      Alex: The practical takeaway is this. The PR status badge changes to "Merged" (purple). The source branch can be deleted - a "Delete branch" button appears. Any linked issues with Closes N in the description are automatically closed.

      -

      Alex: Keep the teaching thread moving. Here is the plain-English version of Auto-Merge - Merging When You Can't Wait Around. Auto-merge lets you pre-authorize a PR to merge automatically the moment all branch protection requirements are satisfied - required reviews approved, all status checks passing, and the branch up to date.

      -

      Alex: The practical takeaway is this. You've addressed all review comments and are waiting for CI to finish. A maintainer has approved the PR but a required check is still running. You're in a different time zone from the reviewers.

      +

      Jamie: Let's pause on Creating Markdown Templates: The VS Code Workflow. What should a learner take away from it?

      +

      Alex: Start with Creating Markdown Templates: The VS Code Workflow. There is something to understand, something to try, and something that proves the try worked.

      +

      Alex: First, open your accessibility-agents fork in VS Code. Then, navigate in Explorer to.github/ISSUE TEMPLATE/. After that, create a new file: Ctrl+N → save as your-template-name.md in that folder. Finally, add frontmatter first (between --- delimiters), then the body. Treat it like a recipe: do not add the next ingredient until the previous one is actually in the bowl.

      +

      Jamie: Before we leave Creating Markdown Templates: The VS Code Workflow, what is the practical point?

      +

      Alex: First, commit and push: open Source Control (Ctrl+Shift+G) → stage → commit → push. It is a checklist, but a meaningful one: every item creates evidence that the next step is safe.

      +

      Alex: Keep the teaching thread moving. Start with File naming conventions. There is something to understand, something to try, and something that proves the try worked.

      +

      Alex: The practical takeaway is this. Use lowercase with hyphens: accessibility-bug.md, feature-request.md. Be descriptive: security-vulnerability.md is better than security.md. Avoid spaces in filenames.

      +

      Jamie: Let's pause on Learning Cards: Creating a New Template. What should a learner take away from it?

      +

      Alex: Start with Learning Cards: Creating a New Template. There is something to understand, something to try, and something that proves the try worked.

      +

      Alex: The practical takeaway is this. 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. 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.

      -

      Jamie: Let's pause on What happens next. What should a learner take away from it?

      -

      Alex: Start with What happens next. There is something to understand, something to try, and something that proves the try worked.

      -

      Alex: The practical takeaway is this. The PR merge box changes to show "Auto-merge enabled - merge will happen automatically". When the last required check passes (or last required review arrives), GitHub merges the PR silently. You receive a notification: "Your PR was automatically merged". If a reviewer requests changes after auto-merge is enabled, auto-merge is automatically cancelled (a new approval is required before it re-enables).

      -

      Jamie: Let's pause on Cancelling Auto-Merge. What should a learner take away from it?

      -

      Alex: Keep the learner anchored in Cancelling Auto-Merge. Auto-merge is only available if the repository administrator has enabled it in Settings → General. This is the part to say slowly: Many open source repos have it on; some do not. A good GitHub workflow is like a well-run meeting: everyone knows the topic, the next action, and who has the floor.

      -

      Alex: Treat examples as spoken recipes, not decorations. You may hear something like Merge box → Tab → "Disable auto-merge" button → Enter. Read the command, understand what it changes, then run it only when the repository state matches the lesson.

      -

      Jamie: Let's pause on Scenario A: "I want to review an assigned PR". What should a learner take away from it?

      -

      Alex: The reason Scenario A: "I want to review an assigned PR" matters is that example: You are assigned to review a PR titled "Add missing NVDA shortcut to keyboard-shortcuts.md." The PR modifies docs/keyboard-shortcuts.md in the Learning Room repository and references Challenge 2.

      +

      Alex: Keep the teaching thread moving. The reason 6. YAML Form-Based Templates matters is that yAML templates create a proper form interface - labeled fields, dropdowns, checkboxes - rather than a pre-filled text editor. That gives the learner a simple foothold: this is the preferred format for modern GitHub projects, especially those focused on accessibility.

      +

      Jamie: Let's pause on Why YAML Forms Are Better for Accessibility. What should a learner take away from it?

      +

      Alex: Start with Why YAML Forms Are Better for Accessibility: Explicit labels: Each field has a label: that screen readers announce. The next useful detail is this: In Markdown templates, users must infer structure from headings and placeholder text.

      +

      Alex: Keep the teaching thread moving. Here is the plain-English version of YAML Template Structure. A YAML form template consists of several parts. It is like learning a transit route. The names of the stops matter because they tell you whether you are still going the right direction.

      -

      Alex: Keep the teaching thread moving. Start with Scenario B: "I want to respond to review feedback on my PR": Example: Your PR for Challenge 3 (Complete Welcome Guide) received a review comment: "The [TODO] about evaluating issues is good, but the paragraph could mention checking if the issue is already assigned." The validation bot also flagged a link text issue.

      -

      Jamie: Let's pause on Writing PR Descriptions That Get Reviewed. What should a learner take away from it?

      -

      Alex: Here is the plain-English version of Writing PR Descriptions That Get Reviewed. See also: Appendix C: Markdown Reference for formatting your PR description with headings, lists, and task lists. Put another way, a pull request is only as useful as its description.

      -

      Jamie: Let's pause on What Reviewers Look For. What should a learner take away from it?

      -

      Alex: This is where What Reviewers Look For becomes real: when a reviewer opens your PR, they are asking four questions before they ever look at the diff. That matters in practice: If your description answers all four, the reviewer can jump straight into the code with context. The workshop is closer to rehearsal than lecture. You hear the move, try the move, and then check what changed.

      -

      Alex: First, why does this change exist? -- What problem does it solve, or what goal does it advance? Then, what is the scope? -- Which files changed, and roughly how big is the change? After that, how was it tested? -- Did you verify that the change works, and how? Finally, what should I pay attention to? -- Are there tricky parts, trade-offs, or areas where you want a second opinion? It is a checklist, but a meaningful one: every item creates evidence that the next step is safe.

      +

      Jamie: Let's pause on Top-level keys. What should a learner take away from it?

      +

      Alex: Start with Top-level keys. There is something to understand, something to try, and something that proves the try worked.

      +

      Alex: The practical takeaway is this. 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).

      +

      Alex: Keep the teaching thread moving. Keep the learner anchored in YAML Field Types Reference. GitHub supports several field types in YAML form templates. This is the part to say slowly: Each has specific attributes and uses.

      +

      Jamie: Let's pause on 1. markdown - Instructional Text. What should a learner take away from it?

      +

      Alex: The reason 1. markdown - Instructional Text matters is that displays formatted Markdown content. That gives the learner a simple foothold: use for instructions, warnings, or explanations.

      +

      Alex: The practical takeaway is this. value (required): Markdown content to display. Use for multi-line text.

      -

      Jamie: Let's pause on The Closes XX Pattern. What should a learner take away from it?

      -

      Alex: Keep the learner anchored in The Closes XX Pattern. GitHub recognizes special keywords in PR descriptions that automatically close linked issues when the PR merges. This is the part to say slowly: You do not need to close issues by hand -- just include the right keyword followed by the issue number.

      -

      Alex: Keep the teaching thread moving. The reason Before/After Structure matters is that one of the most effective patterns for PR descriptions is showing the state before your change and the state after. That gives the learner a simple foothold: this gives the reviewer an instant mental model of what changed without reading the diff line by line.

      -

      Jamie: Let's pause on A PR Description Template. What should a learner take away from it?

      -

      Alex: Start with A PR Description Template: Here is a template you can copy into your PR descriptions. The next useful detail is this: Not every section applies to every PR, but filling in even a few sentences per section makes a meaningful difference.

      +

      Alex: Keep the teaching thread moving. Start with 2. input - Single-line Text Field: Best for short answers like version numbers, URLs, or names. The next useful detail is this: Screen reader announcement: "Version Number, required, edit text, Which version of the software are you using?". Think of it like entering a new building: first you find the lobby, then the room, then the door you actually need.

      +

      Alex: The practical takeaway is this. label (required): Field label, announced by screen readers. description (optional): Help text below the label. placeholder (optional): Placeholder text inside the field. required (boolean): Whether the field must be filled.

      +

      Jamie: Let's pause on 3. textarea - Multi-line Text Area. What should a learner take away from it?

      +

      Alex: Here is the plain-English version of 3. textarea - Multi-line Text Area. Best for descriptions, reproduction steps, code snippets, or any long-form content. Put another way, accessibility tip: Use placeholder for examples, value for pre-filled template text that contributors should edit.

      +

      Alex: The practical takeaway is this. label (required): Field label. description (optional): Help text. placeholder (optional): Placeholder text (multi-line with ). value (optional): Pre-filled content (multi-line with ).

      +

      Jamie: Let's pause on 4. dropdown - Select Menu. What should a learner take away from it?

      +

      Alex: This is where 4. dropdown - Select Menu becomes real: a dropdown menu with predefined options. That matters in practice: Best for bounded answer spaces like OS, browser, or severity.

      +

      Alex: The practical takeaway is this. label (required):Field label. description (optional): Help text. options (required): Array of choices (strings). multiple (boolean, default false): Whether user can select multiple options.

      +

      Alex: First, field is announced as "Browser, required, combo box". Then, press Down Arrow or Alt+Down to expand the dropdown. After that, up/Down Arrow to navigate options. Finally, screen reader announces each option. It is a checklist, but a meaningful one: every item creates evidence that the next step is safe.

      +

      Jamie: Before we leave 4. dropdown - Select Menu, what is the practical point?

      +

      Alex: First, enter or Space to select. It is like walking a hallway with named doors: read the sign, enter the right room, then confirm where you landed.

      -

      Alex: Keep the teaching thread moving. Here is the plain-English version of Common Description Mistakes. Even experienced contributors make these mistakes. Put another way, knowing what to avoid is half the battle. It is like learning a transit route. The names of the stops matter because they tell you whether you are still going the right direction.

      -

      Jamie: Let's pause on Good vs. Bad: Side by Side. What should a learner take away from it?

      -

      Alex: This is where Good vs. Bad: Side by Side becomes real: no context, no linked issue, no explanation of what file or what was wrong with it. That matters in practice: A reviewer seeing this has to open the diff, figure out which file changed, read every line, and guess at the intent.

      -

      Alex: Keep the teaching thread moving. Start with Learning Cards: Writing PR Descriptions That Get Reviewed. There is something to understand, something to try, and something that proves the try worked.

      -

      Alex: The practical takeaway is this. Use Markdown headings ( ) in your description (Summary, Changes, Related Issues, Testing) so reviewers can press H to jump between sections. Type Closes followed by the issue number to auto-close the linked issue on merge; GitHub autocompletes when you type. Press Ctrl+Shift+P in the description text area to toggle between Write and Preview modes; Preview renders your Markdown so you can check structure before submitting. Use the Preview tab to verify your Markdown renders correctly; headings, bullet lists, and code blocks are easier to proofread in rendered form. Keep bullet points short (one line each) so the description is scannable at high zoom without excessive horizontal scrolling. When including screenshots, add alt text in the Markdown image syntax: so every reader gets the same information.

      +

      Jamie: Let's pause on 5. checkboxes - Checkbox Group. What should a learner take away from it?

      +

      Alex: Keep the learner anchored in 5. checkboxes - Checkbox Group. Contributors can select multiple options or use as a verification checklist. This is the part to say slowly: No top-level validation - validation is per-checkbox in options.

      +

      Alex: The practical takeaway is this. label (required): Group label. description (optional): Group description. options (required): Array of checkbox objects. label (required): Checkbox label (what the user sees).

      +

      Alex: First, group label announced: "Before Submitting, Please verify these items". Then, each checkbox announced as "I searched for existing issues, checkbox, not checked, required". After that, screen reader users can check each box with Space. It is like walking a hallway with named doors: read the sign, enter the right room, then confirm where you landed.

      +

      Alex: Keep the teaching thread moving. Start with Choosing the right field type. There is something to understand, something to try, and something that proves the try worked.

      +

      Alex: The practical takeaway is this. 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.

      +

      Jamie: Let's pause on Learning Cards: YAML Form Templates. What should a learner take away from it?

      +

      Alex: Start with Learning Cards: YAML Form Templates. There is something to understand, something to try, and something that proves the try worked.

      +

      Alex: The practical takeaway is this. 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. 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.

      -

      Jamie: Let's pause on Try It: Read a Real Pull Request. What should a learner take away from it?

      -

      Alex: The reason Try It: Read a Real Pull Request matters is that time: 3 minutes What you need: Browser, signed in to GitHub. That gives the learner a simple foothold: go to the Learning Room repository's Pull Requests tab and find any open or recently closed PR.

      -

      Alex: First, navigate to Pull Requests (G then P in Focus Mode). Then, open the first PR in the list (press Enter on its title). After that, read the description - press 2 to jump to the first section heading, then arrow down to read. Look for: which file was changed (docs/welcome.md, docs/keyboard-shortcuts.md, or docs/setup-guide.md)? Which challenge was this PR solving? Does the description. Finally, check the conversation - press 3 to jump between comments. Read what the validation bot reported - did the bot find any accessibility issues like broken headings or non-descriptive links? How did the author respond? The rhythm is simple: orient, act, verify, then continue.

      -

      Jamie: Before we leave Try It: Read a Real Pull Request, what is the practical point?

      -

      Alex: First, look at the diff - press D to the "Pull request tabs" landmark, then navigate to "Files changed" and press Enter. Press H to scan the changed file headings. If the PR touched docs/welcome.md, you should see + lines where the [TODO] sections were filled in. If. Think of it as a rail line: each stop confirms you are still on the right route before the next one.

      -

      Alex: Keep the teaching thread moving. Start with Managing Your GitHub Notification Inbox: See also: Appendix V: GitHub Mobile for managing notifications on your phone. The next useful detail is this: GitHub notifications are how GitHub tells you when something needs your attention. Think of it like entering a new building: first you find the lobby, then the room, then the door you actually need.

      -

      Alex: A solid project habit is to treat metadata as decision support. Labels, status, assignees, and notifications tell you what kind of attention the work needs.

      -

      Jamie: What belongs in the live room, and what can wait until after?

      -

      Alex: Here is the plain-English version of Workshop Recommendation (Chapter 10). For this workshop, Chapter 10 is a guided practice chapter, not a graded automation chapter.

      -

      Alex: The practical takeaway is this. There are 1 guided walkthrough. Automation check: none - notification settings are account-level and cannot be validated by the Learning Room PR bot. The evidence is structured completion comment on your assigned challenge issue. The pattern is configure, filter, act.

      +

      Alex: Keep the teaching thread moving. Here is the plain-English version of 7. Building an Accessibility Bug Report Template. the learner will create a YAML form template specifically for accessibility bug reports in accessibility-agents.

      +

      Jamie: Let's pause on Full Template. What should a learner take away from it?

      +

      Alex: This is where Full Template becomes real: save this as.github/ISSUE TEMPLATE/accessibility-bug.yml in your fork.

      +

      Alex: Keep the teaching thread moving. Keep the learner anchored in What Makes This Template Accessible. This template is itself an accessibility contribution. A good GitHub workflow is like a well-run meeting: everyone knows the topic, the next action, and who has the floor.

      +

      Alex: The practical takeaway is this. 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.

      -

      Jamie: Let's pause on Chapter 10 Challenge Set. What should a learner take away from it?

      -

      Alex: Start with Chapter 10 Challenge Set. There is something to understand, something to try, and something that proves the try worked.

      -

      Alex: First, configure notifications and practice inbox management - set your watch level, use filters to find relevant notifications, and perform one inbox action. It is a checklist, but a meaningful one: every item creates evidence that the next step is safe.

      -

      Jamie: Let's pause on Challenge 10.1 Step-by-Step: Notification Inbox Walkthrough. What should a learner take away from it?

      -

      Alex: Keep the learner anchored in Challenge 10.1 Step-by-Step: Notification Inbox Walkthrough. Set up a useful notification workflow so you can keep up with reviews, mentions, and assignments without inbox overload. This is the part to say slowly: the GitHub.com notifications page and your Learning Room repository settings.

      -

      Alex: The practical takeaway is this. Press M to mute the thread (you will not receive future updates),. Press E to mark done (removes it from inbox but you can still get future updates).

      -

      Alex: First, open your Learning Room repository on GitHub.com. Then, find the Watch button near the top-right of the repository page (next to Star and Fork). After that, 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. Finally, open the notifications inbox by navigating to https://github.com/notifications (or activate the bell icon in the GitHub header). It is like walking a hallway with named doors: read the sign, enter the right room, then confirm where you landed.

      -

      Jamie: Before we leave Challenge 10.1 Step-by-Step: Notification Inbox Walkthrough, what is the practical point?

      -

      Alex: First, in the notification filters, activate the Review requested filter. This shows only notifications where someone has asked you to review their PR. Then, clear that filter and activate the Assigned filter. This shows notifications for issues and PRs assigned to you. After that, open one notification by activating its title link. Read it briefly, then navigate back to the inbox. Finally, perform one inbox action on a non-critical notification thread. The rhythm is simple: orient, act, verify, then continue.

      -

      Alex: Keep the teaching thread moving. The reason Completing Chapter 10: Submit Your Evidence matters is that open your assigned Chapter 10 challenge issue and post a completion comment. That gives the learner a simple foothold: close your Chapter 10 challenge issue when done. The interface gets friendlier when it stops being a wall of controls and starts being a set of named places.

      +

      Jamie: Let's pause on A Second Template: Feature Request Form. What should a learner take away from it?

      +

      Alex: The reason A Second Template: Feature Request Form matters is that the bug report template above is specific to accessibility issues. That gives the learner a simple foothold: once you understand the pattern, you can create templates for any contribution type.

      +

      Alex: Keep the teaching thread moving. Start with Designing Templates for Your Own Projects: When designing templates for a project you maintain, use these principles. The next useful detail is this: Ask for the minimum that makes the report actionable.

      +

      Jamie: Let's pause on Learning Cards: Building an Accessibility Bug Report Template. What should a learner take away from it?

      +

      Alex: Start with Learning Cards: Building an Accessibility Bug Report Template. There is something to understand, something to try, and something that proves the try worked.

      +

      Alex: The practical takeaway is this. 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. 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.

      -

      Jamie: Let's pause on Expected Outcomes. What should a learner take away from it?

      -

      Alex: Start with Expected Outcomes. There is something to understand, something to try, and something that proves the try worked.

      -

      Alex: The practical takeaway is this. 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.

      -

      Jamie: What is the teaching move inside If You Get Stuck?

      -

      Alex: First, can't find the Watch button? It is near the top-right of the repository page, in the same row as Star and Fork. Then, 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. After that, 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. Finally, filters not showing results? Clear all filters first (click the X next to each active filter), then apply one filter at a time. Treat it like a recipe: do not add the next ingredient until the previous one is actually in the bowl.

      -

      Jamie: If someone only remembers one thing from If You Get Stuck, what should it be?

      -

      Alex: First, ask facilitator to model one inbox action live, then repeat the steps yourself. Then, finished but not sure you did it right? Compare your work against the Challenge 9 reference solution. It is a checklist, but a meaningful one: every item creates evidence that the next step is safe.

      -

      Jamie: Let's pause on Learning Moment. What should a learner take away from it?

      -

      Alex: This is where Learning Moment becomes real: notification management protects focus. That matters in practice: You can stay responsive to your team without drowning in updates.

      +

      Alex: Keep the teaching thread moving. This is where 8. Pull Request Templates becomes real: a pull request template appears as the default body of every new PR in your repository. That matters in practice: File location.github/pull request template.md (singular - only one PR template per repo). The workshop is closer to rehearsal than lecture. You hear the move, try the move, and then check what changed.

      +

      Jamie: What should happen before anyone copies and runs it?

      +

      Alex: Keep the learner anchored in Reading the Accessibility Agents PR Template. Open.github/pull request template.md in VS Code. This is the part to say slowly: the learner will see the standard sections the project expects.

      +

      Alex: Treat examples as spoken recipes, not decorations. You may hear something like 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. Read the command, understand what it changes, then run it only when the repository state matches the lesson.

      +

      Alex: Keep the teaching thread moving. Start with Learning Cards: Pull Request Templates. There is something to understand, something to try, and something that proves the try worked.

      +

      Alex: The practical takeaway is this. 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. 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.

      -

      Jamie: Let's pause on Learning Pattern Used in This Chapter. What should a learner take away from it?

      -

      Alex: Start with Learning Pattern Used in This Chapter. There is something to understand, something to try, and something that proves the try worked.

      -

      Alex: First, configure settings proactively (watch level) before work generates noise. Then, use filters to find signal in noise (review requests, assignments). After that, take decisive action on each notification (mute, done, or respond). Finally, build a daily routine that keeps your inbox manageable. It is like walking a hallway with named doors: read the sign, enter the right room, then confirm where you landed.

      -

      Jamie: Let's pause on What Generates a Notification? What should a learner take away from it?

      -

      Alex: The reason What Generates a Notification? matters is that GitHub sends you a notification when.

      -

      Alex: Keep the teaching thread moving. Start with Notification Subscription Levels: For each repository, you choose how many notifications to receive.

      +

      Jamie: Let's pause on Learning Cards: Hands-On Activity. What should a learner take away from it?

      +

      Alex: Start with Learning Cards: Hands-On Activity. There is something to understand, something to try, and something that proves the try worked.

      +

      Alex: The practical takeaway is this. 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. 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.

      +

      Alex: Keep the teaching thread moving. Here is the plain-English version of Exercise A - Use an Existing Template. Your Mission: File your first issue using a structured template. Put another way, you'll experience the template as an end-user, which teaches you what good template design feels like. It is like learning a transit route. The names of the stops matter because they tell you whether you are still going the right direction.

      +

      Jamie: Let's pause on Step 1: Navigate to the Accessibility Agents Issues Section. What should a learner take away from it?

      +

      Alex: Start with Step 1: Navigate to the Accessibility Agents Issues Section. There is something to understand, something to try, and something that proves the try worked.

      +

      Alex: The practical takeaway is this. A tab labeled "Issues" (currently active). A list of open/closed issues below. A large green button labeled "New issue" on the right side. Go directly to: https://github.com/community-access/accessibility-agents/issues/new. This opens the issue template chooser.

      +

      Alex: First, open GitHub in your browser. Then, navigate to the community-access/accessibility-agents repository (or your fork). After that, click the Issues tab (top navigation, between Pull Requests and Discussions). Finally, you should see a list of existing issues. It is a checklist, but a meaningful one: every item creates evidence that the next step is safe.

      +

      Jamie: Before we leave Step 1: Navigate to the Accessibility Agents Issues Section, what is the practical point?

      +

      Alex: First, click the "New issue" button. It is like walking a hallway with named doors: read the sign, enter the right room, then confirm where you landed.

      -

      Jamie: Let's pause on Changing your watch settings for a repo. What should a learner take away from it?

      -

      Alex: Here is the plain-English version of Changing your watch settings for a repo. At the top of any repository page, find the Watch button (near Star and Fork). Put another way, click it to open a dropdown with levels: Participating and @mentions, All Activity, Custom, and Ignore.

      -

      Alex: First, find the Watch button in the repo header (B to navigate buttons → find "Watch [N]" or "Unwatch" button). Then, press Enter to open the dropdown. After that, press ↑/↓ to navigate the subscription options. Finally, press Enter to select your preferred level. Treat it like a recipe: do not add the next ingredient until the previous one is actually in the bowl.

      -

      Jamie: Before we leave Changing your watch settings for a repo, what is the practical point?

      -

      Alex: First, the button label updates to confirm your choice. Then, quick Nav B to find the Watch button in the repo header (listen for "Watch" or "Unwatch"). After that, vO+Space to open the dropdown. Finally, vO+Down or arrow keys to navigate subscription options. It is a checklist, but a meaningful one: every item creates evidence that the next step is safe.

      -

      Jamie: Let's pause on Tool Cards: Manage Notifications. What should a learner take away from it?

      -

      Alex: This is where Tool Cards: Manage Notifications becomes real: VS Code Desktop (GitHub Pull Requests extension). That matters in practice: GitHub Desktop: GitHub Desktop does not manage notifications. The workshop is closer to rehearsal than lecture. You hear the move, try the move, and then check what changed.

      -

      Alex: First, go to github.com/notifications (or press G then N). Then, use E to mark done, I to mark read/unread, Shift+M to mute a thread. After that, the Notifications view in the GitHub sidebar shows items needing attention. Finally, click a notification to open the related issue or PR directly in VS Code. It is a checklist, but a meaningful one: every item creates evidence that the next step is safe.

      -

      Alex: Treat examples as spoken recipes, not decorations. You may hear something like 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. 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. Read the command, understand what it changes, then run it only when the repository state matches the lesson.

      -

      Jamie: Let's pause on Navigating the notification list. What should a learner take away from it?

      -

      Alex: Keep the learner anchored in Navigating the notification list. The inbox shows notifications grouped by date (Today, Yesterday, This week, Older). This is the part to say slowly: Each row shows the repository, the issue or PR title, the event type, and the time.

      -

      Alex: First, d → main content landmark. Then, h to navigate group headings (Today / Yesterday / This week / Older). After that, tab through individual notifications - each row announces: repo name, issue/PR title, event type, time. Finally, enter to open the notification (goes to the issue/PR page). It is like walking a hallway with named doors: read the sign, enter the right room, then confirm where you landed.

      -

      Jamie: Before we leave Navigating the notification list, what is the practical point?

      -

      Alex: First, vO+U → Main → navigate to notification list. Then, vO+Down to move through notifications. After that, vO+Space to open a notification. The rhythm is simple: orient, act, verify, then continue.

      -
      -

      Alex: Keep the teaching thread moving. The reason What is announced per notification matters is that "microsoft/vscode - Add keyboard shortcut for accessible view - @username mentioned you - 2 hours ago". That gives the learner a simple foothold: components: repo/org thread title event type timestamp.

      -

      Jamie: Let's pause on Learning Cards: The Notifications Inbox. What should a learner take away from it?

      -

      Alex: Start with Learning Cards: The Notifications Inbox. There is something to understand, something to try, and something that proves the try worked.

      -

      Alex: The practical takeaway is this. 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. 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.

      -

      Alex: Keep the teaching thread moving. Here is the plain-English version of Inbox Actions - Keyboard Shortcuts. These shortcuts work when a notification is focused in the inbox. Put another way, these are GitHub's own keyboard shortcuts. It is like learning a transit route. The names of the stops matter because they tell you whether you are still going the right direction.

      +

      Jamie: Let's pause on Step 2: View the Template Chooser with Your Screen Reader. What should a learner take away from it?

      +

      Alex: Start with Step 2: View the Template Chooser with Your Screen Reader. There is something to understand, something to try, and something that proves the try worked.

      +

      Alex: The practical takeaway is this. 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. Template 1: [name] - [description]. Template 2: [name] - [description]. And so on. Is each template name announced clearly?

      +

      Alex: First, you should now see a Template Chooser page. Then, the page displays available templates as buttons or links. After that, with screen reader: Navigate through the templates. Finally, count the templates and read their descriptions aloud (or write them down). It is like walking a hallway with named doors: read the sign, enter the right room, then confirm where you landed.

      Alex: A solid navigation habit is to prove where you are before activating controls. Headings, landmarks, and the address bar are not trivia; they are your map.

      +

      Jamie: Let's pause on Step 3: Select a Template. What should a learner take away from it?

      +

      Alex: Start with Step 3: Select a Template. There is something to understand, something to try, and something that proves the try worked.

      +

      Alex: The practical takeaway is this. The issue form opens. You see a form with labeled fields. Each field is pre-filled with helpful prompts or instructions. Choose "Blank Issue" or the most general template. You'll learn what an unstructured issue looks like (which teaches the value of templates).

      +

      Alex: First, 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). Then, click it (or press Enter if focused with keyboard). The rhythm is simple: orient, act, verify, then continue.

      +

      Jamie: Let's pause on Step 4: Navigate the Form Fields. What should a learner take away from it?

      +

      Alex: Start with Step 4: Navigate the Form Fields. There is something to understand, something to try, and something that proves the try worked.

      +

      Alex: The practical takeaway is this. 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. 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"). Field: [name] - Required? [Yes/No].

      +

      Alex: First, the issue form is now open. Then, navigate through all visible fields using your screen reader or by tabbing. After that, for each field, note. Finally, write down at least 3 fields and whether each is required. Think of it as a rail line: each stop confirms you are still on the right route before the next one.

      -

      Jamie: Let's pause on Filtering the Inbox. What should a learner take away from it?

      -

      Alex: This is where Filtering the Inbox becomes real: the left sidebar has quick filters.

      -

      Jamie: Let's pause on Filtering by repository or organization. What should a learner take away from it?

      -

      Alex: Keep the learner anchored in Filtering by repository or organization. At the top of the notification list there is a filter/search field. This is the part to say slowly: Click the filter/search box at the top of the notification list and type a repository or organization name.

      -

      Alex: First, press F or E to reach the filter input. Then, focus Mode → type repo name or org name. After that, results filter in real time. Finally, press Esc to clear the filter. It is like walking a hallway with named doors: read the sign, enter the right room, then confirm where you landed.

      -

      Jamie: Before we leave Filtering by repository or organization, what is the practical point?

      -

      Alex: First, quick Nav F to reach the filter input. Then, vO+Shift+Down to interact → type repo or org name. After that, press Esc to clear the filter and VO+Shift+Up to stop interacting. The rhythm is simple: orient, act, verify, then continue.

      -

      Jamie: Let's pause on The "mark all as done" workflow. What should a learner take away from it?

      -

      Alex: The reason The "mark all as done" workflow matters is that after a busy day or coming back from time away, clear your inbox methodically.

      -

      Alex: First, open Notifications inbox. Then, tab to "Mark all as done" button → Enter (clears everything at once). After that, then use the "Done" filter to retrieve any you want to revisit. The rhythm is simple: orient, act, verify, then continue.

      -
      -

      Jamie: Let's pause on Muting a noisy thread. What should a learner take away from it?

      -

      Alex: Start with Muting a noisy thread: If a thread generates too many notifications. The next useful detail is this: Screen reader users (NVDA / JAWS - Windows). Think of it like entering a new building: first you find the lobby, then the room, then the door you actually need.

      -

      Alex: First, open the issue or PR page. Then, in the right sidebar, scroll to the Notifications section. After that, click Unsubscribe - you will stop receiving notifications from this thread. Finally, alternatively, from the inbox: hover over the notification row and click the mute icon (or the … menu). Think of it as a rail line: each stop confirms you are still on the right route before the next one.

      -

      Jamie: Before we leave Muting a noisy thread, what is the practical point?

      -

      Alex: First, open the notification. Then, on the issue/PR page, navigate the sidebar to the Notifications section (H or D). After that, activate the Unsubscribe button. Finally, or from the inbox: focus the notification → press M to mute. Treat it like a recipe: do not add the next ingredient until the previous one is actually in the bowl.

      -

      Jamie: Let's pause on Dealing with @mentions you didn't expect. What should a learner take away from it?

      -

      Alex: Here is the plain-English version of Dealing with @mentions you didn't expect. If you were @mentioned in an unfamiliar thread.

      -

      Alex: First, read the thread for context before responding. Then, 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. After that, unsubscribe after reading if you don't need to stay in the loop. Treat it like a recipe: do not add the next ingredient until the previous one is actually in the bowl.

      -

      Alex: Keep the teaching thread moving. Start with Learning Cards: Managing Notifications at Scale. There is something to understand, something to try, and something that proves the try worked.

      -

      Alex: The practical takeaway is this. 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. 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.

      +

      Jamie: Let's pause on Step 5: Fill In the Form. What should a learner take away from it?

      +

      Alex: Start with Step 5: Fill In the Form. There is something to understand, something to try, and something that proves the try worked.

      +

      Alex: The practical takeaway is this. Example: If the template asks "Screen Reader," select "NVDA". If it asks "Steps to reproduce," write 2-3 specific steps. 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).

      +

      Alex: First, fill in at least 3 fields with realistic content based on an issue you identified on Day 1. Then, for required fields marked with: Fill them in completely. After that, for optional fields: Choose at least one and fill it in (so you test optional fields). Finally, don't worry about filling in every field - the point is to test the form. Treat it like a recipe: do not add the next ingredient until the previous one is actually in the bowl.

      +

      Jamie: Let's pause on Step 6: Preview the Issue Before Submitting. What should a learner take away from it?

      +

      Alex: Start with Step 6: Preview the Issue Before Submitting. There is something to understand, something to try, and something that proves the try worked.

      +

      Alex: The practical takeaway is this. 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. 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?

      +

      Alex: First, look for a Preview tab or button (usually near the top of the form, next to "Write" or "Markdown"). Then, click it (or press the hotkey shown). After that, a preview pane appears showing how the issue will look when published. It is a checklist, but a meaningful one: every item creates evidence that the next step is safe.

      +

      Jamie: Let's pause on Step 7: Submit the Issue. What should a learner take away from it?

      +

      Alex: Start with Step 7: Submit the Issue. There is something to understand, something to try, and something that proves the try worked.

      +

      Alex: The practical takeaway is this. 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.

      +

      Alex: First, once you're satisfied with the preview, go back to the "Write" tab. Then, locate the green "New issue" button (usually at the bottom of the form). After that, with keyboard: Press Tab until the button is focused, then Enter. Finally, with mouse: Click the button. It is like walking a hallway with named doors: read the sign, enter the right room, then confirm where you landed.

      +

      Jamie: Before we leave Step 7: Submit the Issue, what is the practical point?

      +

      Alex: First, the issue is submitted and you see the new issue page with your content. The rhythm is simple: orient, act, verify, then continue.

      -

      Jamie: Let's pause on Notification Settings - Per Your Account. What should a learner take away from it?

      -

      Alex: Keep the learner anchored in Notification Settings - Per Your Account. Global notification preferences are at https://github.com/settings/notifications.

      -

      Alex: Keep the teaching thread moving. The reason Starring vs. Watching - What Is the Difference? matters is that new contributors often confuse these two. That gives the learner a simple foothold: they appear next to each other on every repository page and do completely different things. The interface gets friendlier when it stops being a wall of controls and starts being a set of named places.

      -

      Jamie: Let's pause on Starring a Repository. What should a learner take away from it?

      -

      Alex: Start with Starring a Repository: Starring is GitHub's equivalent of a bookmark + public endorsement. The next useful detail is this: The star count on a repository is a community signal of popularity.

      +

      Jamie: Let's pause on Step 8: Checkpoint - Reflect on the Template. What should a learner take away from it?

      +

      Alex: The reason Step 8: Checkpoint - Reflect on the Template matters is that you'll use them in Exercise D when you design your own template. The interface gets friendlier when it stops being a wall of controls and starts being a set of named places.

      +

      Alex: First, template Clarity: Did the template guide you toward providing useful information, or did fields feel confusing or unnecessary? Then, screen Reader Accessibility: Were all field labels announced clearly? Did you encounter any accessibility barriers? After that, required vs Optional: Was it obvious which fields were required? If you skipped an optional field, would you have known it was optional? Finally, context Helpfulness: Did the placeholder text or help text under each field make you understand what information to provide? The rhythm is simple: orient, act, verify, then continue.

      +

      Jamie: What should the learner prove to themselves after each small task?

      +

      Alex: Start with 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. The next useful detail is this: This teaches you the file structure and gives you hands-on experience with YAML syntax.

      +

      Alex: The practical takeaway is this. You have already read Section 7 thoroughly (Building an Accessibility Bug Report Template). You have a fork of accessibility-agents (created on Day 1). VS Code is installed on your machine. Git is installed and configure with your GitHub credentials.

      +

      Jamie: Let's pause on Step 1: Clone Your Fork to Your Machine. What should a learner take away from it?

      +

      Alex: Here is the plain-English version of Step 1: Clone Your Fork to Your Machine. (Or wherever you keep code projects). Put another way, replace [YOUR-USERNAME] with your actual GitHub username.

      +

      Alex: The practical takeaway is this. 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. "Repository not found" → Make sure your GitHub username is correct.

      +

      Alex: First, open a terminal (PowerShell on Windows, Terminal on macOS/Linux). Then, navigate to a folder where you want to store the project. After that, clone your fork. Finally, wait for the clone to complete (should take 10-30 seconds). Treat it like a recipe: do not add the next ingredient until the previous one is actually in the bowl.

      +

      Jamie: Before we leave Step 1: Clone Your Fork to Your Machine, what is the practical point?

      +

      Alex: First, navigate into the folder. It is a checklist, but a meaningful one: every item creates evidence that the next step is safe.

      +

      Alex: Treat examples as spoken recipes, not decorations. You may hear something like cd /projects. git clone https://github.com/[YOUR-USERNAME]/accessibility-agents.git. Read the command, understand what it changes, then run it only when the repository state matches the lesson.

      -

      Alex: Keep the teaching thread moving. Here is the plain-English version of 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. Put another way, 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.

      -

      Jamie: Let's pause on How to silence a repository you accidentally over-subscribed to. What should a learner take away from it?

      -

      Alex: This is where How to silence a repository you accidentally over-subscribed to becomes real: this immediately reduces notifications from that repository to only threads you personally participated in.

      -

      Alex: Keep the teaching thread moving. Start with Learning Cards: Starring vs. Watching. There is something to understand, something to try, and something that proves the try worked.

      -

      Alex: The practical takeaway is this. 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. 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.

      +

      Jamie: Let's pause on Step 2: Open Your Fork in VS Code. What should a learner take away from it?

      +

      Alex: Start with Step 2: Open Your Fork in VS Code. There is something to understand, something to try, and something that proves the try worked.

      +

      Alex: The practical takeaway is this. VS Code opens a new window. The left sidebar shows the folder structure of accessibility-agents. At the top, you see the folder name: accessibility-agents. Use VS Code's File menu: File → Open Folder → navigate to your accessibility-agents folder.

      +

      Alex: First, from the terminal, while in your accessibility-agents folder, type. Then, press Enter. After that, VS Code opens with your fork loaded. It is a checklist, but a meaningful one: every item creates evidence that the next step is safe.

      +

      Jamie: Let's pause on Step 3: Navigate to the Templates Folder. What should a learner take away from it?

      +

      Alex: Start with Step 3: Navigate to the Templates Folder. There is something to understand, something to try, and something that proves the try worked.

      +

      Alex: The practical takeaway is this. 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. Right-click on the.github folder and select New Folder. Name it ISSUE TEMPLATE.

      +

      Alex: First, in VS Code's file tree (left sidebar), expand the.github folder. Then, inside, find and expand the ISSUE TEMPLATE folder. After that, you should see existing template files (like bug-report-template.yml or similar). It is like walking a hallway with named doors: read the sign, enter the right room, then confirm where you landed.

      +

      Jamie: Let's pause on Step 4: Create a New Template File. What should a learner take away from it?

      +

      Alex: Start with Step 4: Create a New Template File. There is something to understand, something to try, and something that proves the try worked.

      +

      Alex: The practical takeaway is this. A new, empty file opens in the editor. The cursor is ready for you to start typing.

      +

      Alex: First, right-click on the ISSUE TEMPLATE folder. Then, select New File. After that, name it: accessibility-bug.yml (exactly this name). Finally, press Enter. The rhythm is simple: orient, act, verify, then continue.

      -

      Jamie: Let's pause on NVDA. What should a learner take away from it?

      -

      Alex: Start with NVDA. There is something to understand, something to try, and something that proves the try worked.

      -

      Alex: The practical takeaway is this. 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.

      -

      Alex: Keep the teaching thread moving. Start with JAWS. There is something to understand, something to try, and something that proves the try worked.

      -

      Alex: The practical takeaway is this. 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.

      -

      Jamie: Let's pause on VoiceOver. What should a learner take away from it?

      -

      Alex: Start with VoiceOver. There is something to understand, something to try, and something that proves the try worked.

      -

      Alex: The practical takeaway is this. 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.

      +

      Jamie: Let's pause on Step 5: Copy the Accessibility Template YAML. What should a learner take away from it?

      +

      Alex: Start with Step 5: Copy the Accessibility Template YAML. There is something to understand, something to try, and something that proves the try worked.

      +

      Alex: The practical takeaway is this. 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).

      +

      Alex: First, go to Chapter 17, Section 7 in this curriculum. Then, find the complete YAML template code block (starting with name: and ending with the last field). After that, select all the YAML code (use Ctrl+A on the webpage or manually select). Finally, copy it (Ctrl+C). Think of it as a rail line: each stop confirms you are still on the right route before the next one.

      +

      Jamie: Before we leave Step 5: Copy the Accessibility Template YAML, what is the practical point?

      +

      Alex: First, go back to VS Code. Then, paste it into your new accessibility-bug.yml file (Ctrl+V). Treat it like a recipe: do not add the next ingredient until the previous one is actually in the bowl.

      +

      Jamie: Let's pause on Step 6: Verify the YAML Syntax. What should a learner take away from it?

      +

      Alex: Start with Step 6: Verify the YAML Syntax. There is something to understand, something to try, and something that proves the try worked.

      +

      Alex: The practical takeaway is this. 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. Your YAML syntax is correct!

      +

      Alex: First, save the file (Ctrl+S). Then, look at the bottom right of VS Code - you may see some notifications. After that, check if VS Code shows any red squiggly lines (indicating syntax errors). Finally, hover over the error to see what VS Code suggests. Treat it like a recipe: do not add the next ingredient until the previous one is actually in the bowl.

      +

      Jamie: Before we leave Step 6: Verify the YAML Syntax, what is the practical point?

      +

      Alex: First, compare your file with Section 7's template - look for extra/missing spaces or colons. Then, make corrections and save again. It is a checklist, but a meaningful one: every item creates evidence that the next step is safe.

      +

      Jamie: Let's pause on Step 7: Create a Branch and Commit. What should a learner take away from it?

      +

      Alex: Start with Step 7: Create a Branch and Commit. There is something to understand, something to try, and something that proves the try worked.

      +

      Alex: The practical takeaway is this. Git uploads your branch to GitHub. You're ready to test the template in the next step. "Not a git repository" → Make sure you opened the accessibility-agents folder in VS Code. "Permission denied" → Make sure you authenticated with GitHub (see Prerequisites).

      +

      Alex: First, open the terminal in VS Code: Terminal → New Terminal (or Ctrl+ ` on Windows). Then, you should be in the accessibility-agents folder already. After that, create a new branch for this change. Finally, add the file to git. It is a checklist, but a meaningful one: every item creates evidence that the next step is safe.

      +

      Jamie: Before we leave Step 7: Create a Branch and Commit, what is the practical point?

      +

      Alex: First, commit with a message. Then, push to your fork. It is like walking a hallway with named doors: read the sign, enter the right room, then confirm where you landed.

      +

      Alex: Treat examples as spoken recipes, not decorations. You may hear something like git checkout -b feat/add-accessibility-template. git add.github/ISSUE TEMPLATE/accessibility-bug.yml. Read the command, understand what it changes, then run it only when the repository state matches the lesson.

      +

      Alex: A solid Git habit is to know which branch you are on, what changed, and what confirmation you expect before you run the next command.

      -

      Alex: Keep the teaching thread moving. This is where The GitHub Mobile App - A Reference Note becomes real: GitHub has an iOS and Android app that supports push notifications. That matters in practice: While the app itself is not covered as a primary tool in this workshop, it is worth knowing. The workshop is closer to rehearsal than lecture. You hear the move, try the move, and then check what changed.

      -

      Alex: The practical takeaway is this. 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.

      -

      Jamie: Let's pause on Try It: Tame Your Inbox. What should a learner take away from it?

      -

      Alex: Keep the learner anchored in Try It: Tame Your Inbox. Time: 2 minutes What you need: Browser, signed in to GitHub. This is the part to say slowly: Go to github.com/notifications and practice.

      -

      Alex: First, scan your inbox - Press H and Tab to navigate through notifications. Each one shows the repo name, type (issue/PR), and title. Then, mark one as done - Find a notification you've already read. Press E to mark it as done. It disappears from the list. After that, 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. It is like walking a hallway with named doors: read the sign, enter the right room, then confirm where you landed.

      -

      Alex: Keep the teaching thread moving. The reason What You Accomplished Today matters is that day 1 is complete -- and you did a lot. That gives the learner a simple foothold: here is every skill you practiced, mapped to the chapter where you learned it and the evidence you created along the way.

      +

      Jamie: Let's pause on Step 8: Test the Template in GitHub Web. What should a learner take away from it?

      +

      Alex: Start with Step 8: Test the Template in GitHub Web. There is something to understand, something to try, and something that proves the try worked.

      +

      Alex: The practical takeaway is this. 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. Go back to the main repository page (code tab). Refresh the browser (Ctrl+Shift+R for hard refresh).

      +

      Alex: First, open GitHub in your browser. Then, go to your fork: https://github.com/[YOUR-USERNAME]/accessibility-agents. After that, you should see a notification or purple bar saying "Compare & pull request" (your new branch). Finally, but instead of opening a PR, click the Issues tab. It is like walking a hallway with named doors: read the sign, enter the right room, then confirm where you landed.

      +

      Jamie: Before we leave Step 8: Test the Template in GitHub Web, what is the practical point?

      +

      Alex: First, click New issue. Then, you should now see your new template in the chooser: "Accessibility Bug Report". After that, click it to open the form. The rhythm is simple: orient, act, verify, then continue.

      +

      Jamie: Let's pause on Step 9: Test with Your Screen Reader. What should a learner take away from it?

      +

      Alex: The reason Step 9: Test with Your Screen Reader matters is that record your findings - you'll use this for Exercise D.

      +

      Alex: The practical takeaway is this. Is the label announced clearly? Is it obvious whether the field is required? Do dropdowns announce their options correctly? Are descriptions/help text announced? Did you encounter any accessibility barriers? Would a screen reader user find this template easy to use?

      +

      Alex: First, with screen reader activated: Navigate through the template form using your reader's commands. Then, for each field, note. The rhythm is simple: orient, act, verify, then continue.

      +

      Jamie: Let's pause on Step 10: Merge Your Branch (Optional). What should a learner take away from it?

      +

      Alex: Start with Step 10: Merge Your Branch (Optional). There is something to understand, something to try, and something that proves the try worked.

      +

      Alex: The practical takeaway is this. Go to your fork on GitHub. You should see a "Compare & pull request" button. Click it. It shows the template is finalized and tested. If you continue working on this fork, the template is ready for everyone who clones it.

      +

      Alex: First, open an PR for your branch. Then, add a title: feat: add accessibility bug report template. After that, add a description: This template guides contributors to report accessibility issues with clear fields for screen reader type, browser, and WCAG criteria. Finally, click Create pull request. Think of it as a rail line: each stop confirms you are still on the right route before the next one.

      +

      Jamie: Before we leave Step 10: Merge Your Branch (Optional), what is the practical point?

      +

      Alex: First, review your PR (using skills from Chapter 14!). Then, if satisfied, click Merge pull request to merge it into your fork's main branch. Treat it like a recipe: do not add the next ingredient until the previous one is actually in the bowl.

      -

      Jamie: Let's pause on If This Was Your First Time. What should a learner take away from it?

      -

      Alex: Start with 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. The next useful detail is this: You navigated a complex platform, created real contributions, and collaborated with other people in a shared codebase.

      -

      Jamie: Let's pause on Confidence Check. What should a learner take away from it?

      -

      Alex: Here is the plain-English version of Confidence Check. Before you close your laptop, take two minutes to answer these questions in your Chapter 10 challenge issue. Put another way, there are no wrong answers -- this is for you. It is like learning a transit route. The names of the stops matter because they tell you whether you are still going the right direction.

      -

      Alex: First, which chapter felt the most natural to you? Which one do you want to revisit? Then, can you explain what a pull request does to someone who has never used GitHub? After that, if you saw a merge conflict right now, would you know where to start? Finally, what is one thing you want to try on GitHub this week that you did not get to today? Treat it like a recipe: do not add the next ingredient until the previous one is actually in the bowl.

      +

      Jamie: Let's pause on Checkpoint. What should a learner take away from it?

      +

      Alex: Here is the plain-English version of Checkpoint. After completing Steps 1-9, verify. It is like learning a transit route. The names of the stops matter because they tell you whether you are still going the right direction.

      +

      Alex: First, you created a file named accessibility-bug.yml in.github/ISSUE TEMPLATE/. Then, the file contains valid YAML (no red squiggles in VS Code). After that, the template is visible when you click "New issue" in your fork. Finally, you tested it with your screen reader and noted any issues. Treat it like a recipe: do not add the next ingredient until the previous one is actually in the bowl.

      Jamie: Why is the evidence prompt part of the teaching, not just grading?

      -

      Alex: This is where Your Challenge Progress becomes real: look at how many challenge issues you completed today. That matters in practice: Each one represents a skill you did not just read about -- you practiced it, posted evidence, and moved on.

      -
      -

      Alex: Keep the teaching thread moving. Start with Learning Cards: What You Accomplished Today. There is something to understand, something to try, and something that proves the try worked.

      -

      Alex: The practical takeaway is this. 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. 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.

      -

      Jamie: Where is the promise of the workshop, underneath all the logistics?

      -

      Alex: The reason What Day 2 Adds matters is that see also: Chapter 11: VS Code Interface is where Day 2 begins -- have VS Code installed and ready. That gives the learner a simple foothold: on Day 1, you worked entirely on GitHub.com.

      -

      Jamie: Let's pause on Between Days. What should a learner take away from it?

      -

      Alex: Start with 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. The next useful detail is this: GitHub Skills courses use bot-driven feedback inside pull requests. Think of it like entering a new building: first you find the lobby, then the room, then the door you actually need.

      -

      Alex: First, explore your notification settings. Now that you understand how notifications work, visit github.com/settings/notifications and customize your email and web preferences. There is no wrong configuration -- just find what feels manageable. Then, 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. After that, try a GitHub Skills course. GitHub Skills 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 for the full list of recommended courses. Think of it as a rail line: each stop confirms you are still on the right route before the next one.

      +

      Alex: This is where Exercise C - Submit It Upstream becomes real: your Mission: Contribute your tested template to the upstream community-access/accessibility-agents repository. That matters in practice: This is a real open source contribution!

      +

      Alex: The practical takeaway is this. 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.

      +

      Jamie: Let's pause on Step 1: Verify Your Template is Ready. What should a learner take away from it?

      +

      Alex: Keep the learner anchored in Step 1: Verify Your Template is Ready. Before submitting upstream, make sure your template is production-ready.

      +

      Alex: The practical takeaway is this. All fields display correctly. No broken formatting. Dropdowns work properly. Required fields are marked. The template is clean, no error messages. Every field is functional.

      +

      Alex: First, go to your fork on GitHub. Then, click Issues → New issue. After that, verify your template appears and is named "Accessibility Bug Report". Finally, open it and fill it out once more to confirm. It is like walking a hallway with named doors: read the sign, enter the right room, then confirm where you landed.

      +

      Jamie: Before we leave Step 1: Verify Your Template is Ready, what is the practical point?

      +

      Alex: First, don't submit this test issue - just close the tab. The rhythm is simple: orient, act, verify, then continue.

      -

      Jamie: Let's pause on You Already Know More Than You Think. What should a learner take away from it?

      -

      Alex: Here is the plain-English version of You Already Know More Than You Think. Think about where you started this morning. Put another way, 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.

      +

      Jamie: Let's pause on Step 2: Create the Pull Request. What should a learner take away from it?

      +

      Alex: Start with Step 2: Create the Pull Request. There is something to understand, something to try, and something that proves the try worked.

      +

      Alex: The practical takeaway is this. Click the Code tab. Click the branches dropdown. Select your branch (feat/add-accessibility-template). Click "New pull request" to the right. Base: community-access/accessibility-agents / main (the upstream repo). Head: [your-username]/accessibility-agents / feat/add-accessibility-template (your fork/branch).

      +

      Alex: First, stay on your fork's GitHub page. Then, you should see a "Compare & pull request" button (or look for your feature branch). After that, if that button doesn't appear. Finally, a PR creation page opens showing. The rhythm is simple: orient, act, verify, then continue.

      +

      Jamie: Before we leave Step 2: Create the Pull Request, what is the practical point?

      +

      Alex: First, confirm this is correct - you're sending your branch to the upstream repository. Think of it as a rail line: each stop confirms you are still on the right route before the next one.

      +

      Jamie: How do you keep commands from becoming magic words?

      +

      Alex: Start with Step 3: Write Your PR Title and Description: Write a clear description that explains what you're contributing. Think of it like entering a new building: first you find the lobby, then the room, then the door you actually need.

      +

      Alex: Treat examples as spoken recipes, not decorations. You may hear something like 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. Read the command, understand what it changes, then run it only when the repository state matches the lesson.

      +

      Jamie: Let's pause on What to do. What should a learner take away from it?

      +

      Alex: Start with What to do. There is something to understand, something to try, and something that proves the try worked.

      +

      Alex: The practical takeaway is this. 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?

      +

      Alex: First, copy the template above into the description field. Then, edit it with your actual testing experience. After that, keep it concise but thorough. Treat it like a recipe: do not add the next ingredient until the previous one is actually in the bowl.

      -

      Jamie: What is the final checkpoint?

      -

      Alex: You should be able to point to the evidence, explain the action, and describe what you would do next if this were a real open source project. If you can teach the move back, you have learned it.

      -

      Jamie: And if they get stuck?

      -

      Alex: Read the latest message, not the loudest worry. Check the issue, the branch, the pull request, the status check, or the bot comment. Then ask for help with those facts in hand. That is how professionals collaborate.

      -
      - +

      Jamie: Let's pause on Step 4: Review Your PR Before Submitting. What should a learner take away from it?

      +

      Alex: Start with Step 4: Review Your PR Before Submitting. There is something to understand, something to try, and something that proves the try worked.

      +

      Alex: The practical takeaway is this. Is the title clear about what you're adding? Does the description explain the value of this template? Are all checkmarks (``) and formatting visible?

      +

      Alex: First, scroll down and preview your PR description as it will appear. Then, using your screen reader, read through it. After that, make any corrections needed. Finally, do not submit yet - continue to Step 5. It is a checklist, but a meaningful one: every item creates evidence that the next step is safe.

      +

      Jamie: Let's pause on Step 5: Submit the PR. What should a learner take away from it?

      +

      Alex: Start with Step 5: Submit the PR. There is something to understand, something to try, and something that proves the try worked.

      +

      Alex: The practical takeaway is this. 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. Your PR appears in the upstream repository's PR list. You see comments from maintainers (positive feedback = great sign!).

      +

      Alex: First, click the green "Create pull request" button. Then, your PR is now submitted to the upstream repository. After that, you see a confirmation page showing your new PR number (e.g., " 42"). Finally, GitHub may automatically assign reviewers or run CI checks. It is like walking a hallway with named doors: read the sign, enter the right room, then confirm where you landed.

      +

      Jamie: Let's pause on Step 6: Respond to Feedback. What should a learner take away from it?

      +

      Alex: Start with Step 6: Respond to Feedback. There is something to understand, something to try, and something that proves the try worked.

      +

      Alex: The practical takeaway is this. Go back to your fork in VS Code. Edit the accessibility-bug.yml file accordingly. Commit and push. Your changes automatically appear in the PR (linked to the branch). You can leave a polite comment: "Friendly ping - is there anything else needed from my end?".

      +

      Alex: First, read their feedback carefully using your screen reader. Then, understand what changes they're requesting (or what they're praising!). After that, if changes are needed. Finally, leave a reply comment on the PR. The rhythm is simple: orient, act, verify, then continue.

      +

      Jamie: Before we leave Step 6: Respond to Feedback, what is the practical point?

      +

      Alex: First, click Reply. Think of it as a rail line: each stop confirms you are still on the right route before the next one.

      +

      Alex: Treat examples as spoken recipes, not decorations. You may hear something like git add.github/ISSUE TEMPLATE/accessibility-bug.yml; git commit -m "Address feedback from maintainers: [brief description]"; git push origin feat/add-accessibility-template. Read the command, understand what it changes, then run it only when the repository state matches the lesson.

      -

      Challenge 10: Go Local

      -

      Cloning, local branches, commits, pushing, and understanding local versus remote.

      -
      -Read Transcript - Challenge 10: Go Local - -

      Transcript

      -

      Alex: Welcome back to Challenge Coach. Today we are taking on Go Local, one careful step at a time.

      -

      Jamie: And I am Jamie. I am listening for the confusing parts: where to start, what to submit, and how to tell whether it worked.

      +

      Jamie: Let's pause on Step 7: Celebrate Your Contribution. What should a learner take away from it?

      +

      Alex: Start with Step 7: Celebrate Your Contribution: -Write down: "I contributed [template name] to an open source project".

      +

      Alex: The practical takeaway is this. Take a screenshot of your merged PR. This is valuable experience for your resume and for learning how open source collaboration works.

      +

      Alex: First, you'll see the PR status change to "Merged". Then, your template is now part of the community-access/accessibility-agents repository. After that, everyone who forks that repo will get your template. Finally, you can claim this as a real open source contribution. Think of it as a rail line: each stop confirms you are still on the right route before the next one.

      +

      Jamie: Before we leave Checkpoint, what is the practical point?

      +

      Alex: Here is the plain-English version of Checkpoint. After completing Steps 1-7, verify.

      +

      Alex: The practical takeaway is this. 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?

      +

      Alex: First, you created a PR to the upstream repository. Then, your PR includes a clear description of what you're contributing. After that, your template is the only change in the PR (one file). Finally, you addressed any feedback from maintainers. Treat it like a recipe: do not add the next ingredient until the previous one is actually in the bowl.

      +

      Jamie: What is the teaching move inside Checkpoint?

      +

      Alex: First, your PR was merged (or is waiting for merge). It is a checklist, but a meaningful one: every item creates evidence that the next step is safe.

      +

      Jamie: How do these exercises create confidence instead of pressure?

      +

      Alex: This is where Exercise D - Design a Template for Your Own Project becomes real: your Mission: Apply everything you've learned to design a template for a repository you own, maintain, or plan to create. That matters in practice: What You'll Learn: How to make design decisions about required vs.

      -

      Alex: In this challenge, the learner is practicing cloning, local branches, commits, pushing, and understanding local versus remote. The point is not to rush. The point is to leave a clear trace of good work.

      -

      Jamie: So we should name what success sounds like before the learner starts clicking or typing.

      -

      Alex: Yes. When the checkpoint is clear, the learner can tell the difference between being stuck and simply not being finished yet.

      +

      Jamie: Let's pause on Part 1: Choose Your Project. What should a learner take away from it?

      +

      Alex: Start with Choose Your Project. There is something to understand, something to try, and something that proves the try worked.

      +

      Alex: The practical takeaway is this. 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. You have a specific project in mind (not generic). You can articulate why you care about it.

      +

      Alex: First, think of a repository you have a personal connection to. Then, write down the project name and briefly why chose it. It is like walking a hallway with named doors: read the sign, enter the right room, then confirm where you landed.

      +

      Jamie: Let's pause on Part 2: Identify Issue Patterns. What should a learner take away from it?

      +

      Alex: The reason Identify Issue Patterns matters is that your task: Study the issues your project receives (or would receive) to understand what information is most valuable. That gives the learner a simple foothold: if your project doesn't exist yet or has no issues.

      +

      Alex: The practical takeaway is this. 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? Bug reports?

      +

      Alex: First, open your issue list in GitHub. Then, read the last 5-10 issues (or all open issues if fewer). After that, for each issue, ask yourself. Finally, write down 3-5 patterns. The rhythm is simple: orient, act, verify, then continue.

      +

      Jamie: Before we leave Part 2: Identify Issue Patterns, what is the practical point?

      +

      Alex: First, think about the type of issues you'd want to receive. Then, for each type, ask: "If someone reported this issue, what would I need to know?". After that, write down. Think of it as a rail line: each stop confirms you are still on the right route before the next one.

      +

      Jamie: Let's pause on Part 3: Design Your Required Fields. What should a learner take away from it?

      +

      Alex: Start with Design Your Required Fields: Your task: List the fields you absolutely need to understand an issue. The next useful detail is this: Rule: Keep required fields minimal.

      +

      Alex: The practical takeaway is this. You have 2-4 required fields. Each has a clear reason (not arbitrary). You can explain to someone why each field is required.

      +

      Alex: First, create a table. Then, for each issue type from Part 2, add 2-4 required fields. After that, write down at least 2 required fields. Think of it as a rail line: each stop confirms you are still on the right route before the next one.

      -

      Jamie: What makes this practice feel low-stakes but still real?

      -

      Alex: Start with Challenge 10: Go Local: What you will do: Clone the learning-room to your computer, create a feature branch, make an edit, commit locally, and push to GitHub.

      -

      Jamie: How would you walk the room through that step by step?

      -

      Alex: Here is the plain-English version of The local workflow. This is the professional Git workflow you will use for the rest of your career. It is like learning a transit route. The names of the stops matter because they tell you whether you are still going the right direction.

      -

      Alex: First, clone the repository to your computer. Then, branch -- create a new branch for your work. After that, edit -- make your changes. Finally, commit -- save a snapshot locally. Treat it like a recipe: do not add the next ingredient until the previous one is actually in the bowl.

      -

      Jamie: What does the learner do first, second, and then after that?

      -

      Alex: First, push -- send your branch to GitHub. It is a checklist, but a meaningful one: every item creates evidence that the next step is safe.

      -

      Jamie: Turn that into a path someone can follow.

      -

      Alex: This is where Instructions (choose your tool) becomes real: autograded: The autograder verifies that at least one commit exists on a non-default branch pushed from a local tool. That matters in practice: Commit message: "." validations: required: true.

      -

      Alex: First, open VS Code. Open the Command Palette (Ctrl+Shift+P / Cmd+Shift+P). Then, type "Git: Clone" and paste the repository URL. After that, after cloning, create a branch: open the Command Palette, type "Git: Create Branch", name it fix/YOUR-USERNAME. Finally, edit any file in the docs/ folder (fix a typo, improve a sentence, add a comment). It is a checklist, but a meaningful one: every item creates evidence that the next step is safe.

      -

      Jamie: What is the ordered workflow?

      -

      Alex: First, in the Source Control panel (Ctrl+Shift+G), stage your change, write a commit message, and commit. Then, push: open the Command Palette, type "Git: Push". After that, file Clone Repository. Paste the URL. Finally, branch New Branch. Name it fix/YOUR-USERNAME. It is like walking a hallway with named doors: read the sign, enter the right room, then confirm where you landed.

      -

      Alex: Treat examples as spoken recipes, not decorations. You may hear something like git clone; cd learning-room; git checkout -b fix/YOUR-USERNAME; edit a file; git add.; git commit -m "fix: improve docs section"; git push -u origin fix/YOUR-USERNAME. Read the command, understand what it changes, then run it only when the repository state matches the lesson.

      +

      Jamie: Let's pause on Part 4: Design Your Optional Fields. What should a learner take away from it?

      +

      Alex: Here is the plain-English version of Design Your Optional Fields. Your task: Add optional fields that would be helpful but aren't blocking.

      +

      Alex: The practical takeaway is this. Information that's helpful but you could triage without it. Information that helps you prioritize or assign the issue. Information that provides missing context. Environment details (CPU, RAM, versions of dependencies). Screenshots or links. Workarounds the reporter has found.

      +

      Alex: First, brainstorm nice-to-have information. Then, example optional fields for a bug report. After that, write down at least 2 optional fields. Finally, for each field, decide. Treat it like a recipe: do not add the next ingredient until the previous one is actually in the bowl.

      +

      Jamie: Let's pause on Part 5: Write Field Placeholders and Help Text. What should a learner take away from it?

      +

      Alex: This is where Write Field Placeholders and Help Text becomes real: your task: For each field, write helpful placeholder or description text that guides the reporter. That matters in practice: For each required and optional field, draft. The workshop is closer to rehearsal than lecture. You hear the move, try the move, and then check what changed.

      +

      Alex: The practical takeaway is this. 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.

      +

      Alex: First, field label (the visible name). Then, description (short help text). After that, placeholder (example of what to type, for input/textarea fields). It is a checklist, but a meaningful one: every item creates evidence that the next step is safe.

      +

      Jamie: Let's pause on Part 6: Test Your Template Locally. What should a learner take away from it?

      +

      Alex: Keep the learner anchored in Test Your Template Locally. Your task: Create a draft YAML template file and test it with your screen reader.

      +

      Alex: The practical takeaway is this. Start with the frontmatter (name:, description:, title:, labels:). Add your fields in the body: section. Use appropriate field types (input, textarea, dropdown, checkboxes). Name it: [your-project-name]-template.yml. Save it to your desktop or a projects folder. Is the YAML syntax correct? (no red squiggles).

      +

      Alex: First, create a text file with your template in YAML format. Use Section 6 as a template. Then, save it locally (not yet in GitHub). After that, open it in VS Code and check. Finally, test the structure. It is like walking a hallway with named doors: read the sign, enter the right room, then confirm where you landed.

      +

      Jamie: Before we leave Part 6: Test Your Template Locally, what is the practical point?

      +

      Alex: First, with your screen reader. The rhythm is simple: orient, act, verify, then continue.

      -

      Alex: Now bring the learner back to the room. Keep the learner anchored in Peer simulation check. Compare your local tool choice with the peer-simulation PR notes or with a real buddy. This is the part to say slowly: What was different about the workflow?

      -

      Jamie: What should they understand before typing anything?

      -

      Alex: Start with Terminal/CLI approach. There is something to understand, something to try, and something that proves the try worked.

      -

      Alex: Treat examples as spoken recipes, not decorations. You may hear something like Clone the repository; git clone https://github.com/the workshop organization/learning-room-your username.git; cd learning-room; Create a branch; git checkout -b fix/local-edit; Make an edit (any text editor works); For example, fix a typo or add content to. Read the command, understand what it changes, then run it only when the repository state matches the lesson.

      -

      Alex: A solid pull request habit is to separate three questions: what changed, why it changed, and what still needs review. That keeps the conversation useful instead of noisy.

      -

      Jamie: Give me the sequence, because order matters here.

      -

      Alex: Start with VS Code approach. There is something to understand, something to try, and something that proves the try worked.

      -

      Alex: First, open the Command Palette (Ctrl+Shift+P or Cmd+Shift+P). Then, run "Git: Clone" and paste the repository URL. After that, open the cloned folder. Finally, click the branch name in the bottom-left status bar, create a new branch. Think of it as a rail line: each stop confirms you are still on the right route before the next one.

      -

      Jamie: Let's pause on VS Code approach. What should a learner take away from it?

      -

      Alex: First, edit a file. Then, open the Source Control sidebar (Ctrl+Shift+G). After that, stage changes with the + icon, type a commit message, click the checkmark. Finally, click "Publish Branch" or use the sync button. Treat it like a recipe: do not add the next ingredient until the previous one is actually in the bowl.

      +

      Jamie: Let's pause on Part 7: (Optional) Deploy to GitHub and Test with a Friend. What should a learner take away from it?

      +

      Alex: The reason (Optional) Deploy to GitHub and Test with a Friend matters is that your task: Upload your template to a GitHub repository and test it with a colleague or friend. That gives the learner a simple foothold: this is optional but powerful - real user testing is the best validation.

      +

      Alex: The practical takeaway is this. Create a test branch in a personal repo. Add your template file to.github/ISSUE TEMPLATE/. Push the branch. "Could you try filing an issue using this template?".

      +

      Alex: First, upload your template to a test repository. Then, ask a colleague or friend. After that, collect feedback. Finally, refine your template based on their feedback. The rhythm is simple: orient, act, verify, then continue.

      +

      Jamie: Let's pause on Part 8: Reflect on Your Template Design. What should a learner take away from it?

      +

      Alex: Start with Reflect on Your Template Design: Your task: Document what you learned from this exercise.

      +

      Alex: The practical takeaway is this. 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.

      +

      Alex: First, decision-making: Which field did you debate including? Why did you finally decide yes or no? Then, trade-offs: You can't ask for everything without overwhelming reporters. What information did you choose not to ask for? Why? After that, iteration: If you had user feedback (from Part 7), what did you learn? Finally, real-world readiness: Would you actually deploy this template to a real project? Think of it as a rail line: each stop confirms you are still on the right route before the next one.

      +

      Alex: Keep the teaching thread moving. Here is the plain-English version of Checkpoint. After completing Parts 1-8, you have. Put another way, you now understand the thinking that separates "a blank text box" from "structured, actionable contributions.". It is like learning a transit route. The names of the stops matter because they tell you whether you are still going the right direction.

      +

      Alex: The practical takeaway is this. Chosen a specific project to design. Identified issue patterns and common questions. Designed required fields (minimal, crucial information). Designed optional fields (helpful but not blocking).

      -

      Jamie: Let's pause on GitHub Desktop approach. What should a learner take away from it?

      -

      Alex: Start with GitHub Desktop approach. There is something to understand, something to try, and something that proves the try worked.

      -

      Alex: First, file, Clone Repository, paste the URL. Then, current Branch dropdown, New Branch. After that, open the file in your editor and make a change. Finally, return to GitHub Desktop -- it shows the diff. Treat it like a recipe: do not add the next ingredient until the previous one is actually in the bowl.

      -

      Jamie: Before we leave GitHub Desktop approach, what is the practical point?

      -

      Alex: First, write a commit message at the bottom-left, click "Commit". Then, click "Publish branch" to push. It is a checklist, but a meaningful one: every item creates evidence that the next step is safe.

      -

      Alex: This is where the talk moves from concept to action. This is where Verifying success becomes real: after pushing, go to github.com and you should see.

      -

      Alex: The room should hear these as checkpoints. A banner saying "fix/local-edit had recent pushes" with a "Compare & pull request" button. Your branch in the branch dropdown. Your commit in the branch's commit history.

      -

      Alex: The useful habit is simple: orient first, act second, verify third. That pause before acting is part of the work.

      +

      Jamie: Let's pause on You've Completed the Template Exercises. What should a learner take away from it?

      +

      Alex: This is where You've Completed the Template Exercises becomes real: 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. That matters in practice: The agent generates YAML; you decide what questions to ask.

      +

      Alex: First, understand templates from the user perspective (Exercise A). Then, can create and deploy templates yourself (Exercise B). After that, know how to contribute upstream (Exercise C). Finally, can design templates with real thinking behind them (Exercise D). It is a checklist, but a meaningful one: every item creates evidence that the next step is safe.

      +

      Alex: Keep the teaching thread moving. Keep the learner anchored in 10. Day 2 Amplifier: The Template Builder Agent. Everything you just learned - field types, YAML structure, accessibility testing - is core GitHub knowledge. This is the part to say slowly: Now see how Accessibility Agents amplifies it.

      +

      Jamie: What stays the same when the tool changes?

      +

      Alex: The reason In VS Code matters is that then you copy, paste to.github/ISSUE TEMPLATE/your-template.yml, commit, and done.

      +
      +

      Alex: Keep the teaching thread moving. Start with Why It Matters: The Template Builder does not teach you to design templates - Section 5 taught you that. The next useful detail is this: It automates the mechanical part: translating your decisions into working YAML. Think of it like entering a new building: first you find the lobby, then the room, then the door you actually need.

      +

      Jamie: Let's pause on Using the Template Builder. What should a learner take away from it?

      +

      Alex: Here is the plain-English version of Using the Template Builder. Next: Chapter 18: Fork and Contribute Back: Chapter 16: GitHub Copilot Related appendices: Appendix Q: GitHub Actions Appendix C: Markdown Reference.

      +
      +

      Jamie: What should people carry with them after this?

      +

      Alex: Carry the map. Know what page or tool you are in, know which action you are taking, and know what confirmation should follow. If the confirmation is missing, pause. That pause is not wasted time; it is professional judgment.

      +

      Jamie: That is a better way to say it than just follow the steps.

      +

      Alex: Right. Steps matter, but understanding wins. That is episode 16. Next in the series is episode 17, where we keep building the same contributor muscles.

      +
      + +
      +

      46. Challenge 14: Template Remix

      +

      YAML issue forms, accessible labels, required fields, and useful maintainer intake.

      +

      Practice focus: Day 2 capstone

      +

      Audio and transcript are being regenerated for this episode.

      +
      +Read Transcript - Challenge 14: Template Remix + +

      Transcript

      +

      Alex: Welcome back to Challenge Coach. Today we are taking on Template Remix, one careful step at a time.

      +

      Jamie: And I am Jamie. I am listening for the confusing parts: where to start, what to submit, and how to tell whether it worked.

      +
      +

      Alex: In this challenge, the learner is practicing yAML issue forms, accessible labels, required fields, and useful maintainer intake. The point is not to rush. The point is to leave a clear trace of good work.

      +

      Jamie: So we should name what success sounds like before the learner starts clicking or typing.

      +

      Alex: Yes. When the checkpoint is clear, the learner can tell the difference between being stuck and simply not being finished yet.

      +
      +

      Jamie: What makes this practice feel low-stakes but still real?

      +

      Alex: Start with Challenge 14: Template Remix: What you will do: Create your own custom issue template by studying the existing registration template and remixing it for a new purpose.

      +

      Jamie: How would you walk the room through that step by step?

      +

      Alex: Start with Instructions. There is something to understand, something to try, and something that proves the try worked.

      +

      Alex: The practical anchors are these. A name field (required -- the autograder checks for this). A description field. A title field with a prefix pattern. At least one textarea or input field in the body. Accessibility feedback form. Workshop improvement suggestion.

      +

      Alex: First, study the sample template at docs/samples/chapter-15-registration-remix-example.yml to understand the YAML format. Then, create a new file at.github/ISSUE TEMPLATE/YOUR-USERNAME-template.yml on your branch. After that, your template must. Finally, choose your own topic. Ideas. Treat it like a recipe: do not add the next ingredient until the previous one is actually in the bowl.

      +

      Jamie: What does the learner do first, second, and then after that?

      +

      Alex: First, commit and push your template. It is a checklist, but a meaningful one: every item creates evidence that the next step is safe.

      Jamie: What is the one idea that makes the next few steps less mysterious?

      -

      Alex: Keep the learner anchored in What matters. The learning objective is executing the full local workflow: clone, branch, edit, commit, push. This is the part to say slowly: The specific change you made does not matter.

      +

      Alex: This is where Minimum YAML structure becomes real: autograded: The autograder verifies that a YAML file exists in.github/ISSUE TEMPLATE/ with a valid name field.

      -

      Alex: Before the learner moves on. The reason 1. Why a Mental Model Matters matters is that on Day 1, you edited files on GitHub.com using the web editor. That gives the learner a simple foothold: GitHub handled Git for you behind the scenes -- creating commits, managing branches, and tracking changes. The interface gets friendlier when it stops being a wall of controls and starts being a set of named places.

      -

      Jamie: What would you say to someone who is already bracing for this to be too much?

      -

      Alex: Start with 2. The Three Areas: Working Directory, Staging Area, Repository: Git organizes your work into three areas. The next useful detail is this: Understanding these three areas is the single most important concept in this chapter.

      -

      Alex: Hold that next to this. Here is the plain-English version of Working directory. The working directory is the folder on your computer where the files live. Put another way, when you open a project in VS Code, everything you see in the file explorer is the working directory.

      +

      Alex: Now bring the learner back to the room. Keep the learner anchored in Peer simulation check. Create a test issue using your own custom template, then compare it with the seeded challenge templates. This is the part to say slowly: If you have real buddy access, you may also try your buddy's template.

      +

      Jamie: What should they understand before typing anything?

      +

      Alex: The reason Example template matters is that file.github/ISSUE TEMPLATE/accessibility-report.yml.

      +

      Alex: Treat examples as spoken recipes, not decorations. You may hear something like The name appears in the template chooser when someone clicks "New Issue"; name: Accessibility Report; The description appears below the name in the chooser; description: Report an accessibility barrier in workshop materials; Labels are automatically applied to. Read the command, understand what it changes, then run it only when the repository state matches the lesson.

      +

      Alex: The useful habit is simple: orient first, act second, verify third. That pause before acting is part of the work.

      +

      Alex: That matters because of the next idea. Start with Alternate valid templates: Any topic works for this challenge. Think of it like entering a new building: first you find the lobby, then the room, then the door you actually need.

      +

      Alex: On the ground, that means a few things. A bug report template for the workshop. A feature request template for new workshop topics. A feedback template for session evaluations. A question template for asking for help.

      Jamie: Okay, set the room for us. What are we walking into?

      -

      Alex: This is where Staging area (also called the index) becomes real: the staging area is a holding zone. That matters in practice: When you are happy with a change in the working directory, you add it to the staging area.

      -

      Alex: That connects to another useful point. Keep the learner anchored in Repository (the.git folder). The repository is Git's permanent record. This is the part to say slowly: 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. A good GitHub workflow is like a well-run meeting: everyone knows the topic, the next action, and who has the floor.

      -

      Alex: A solid Git habit is to know which branch you are on, what changed, and what confirmation you expect before you run the next command.

      -

      Jamie: Let's pause on How the three areas connect. What should a learner take away from it?

      -

      Alex: The reason How the three areas connect matters is that many visual Git tutorials use diagrams with arrows to show this flow. That gives the learner a simple foothold: the text description above and the three-step sequence are the same information without requiring a visual representation.

      -

      Alex: First, edit files in the working directory. Then, stage the changes you want to keep (add to the staging area). After that, commit the staged changes (save to the repository). The rhythm is simple: orient, act, verify, then continue.

      +

      Alex: Here is the plain-English version of What matters. The learning objective is understanding structured issue templates as a way to guide contributors. Put another way, if your YAML file has a name, description, and at least one body field, you completed this challenge.

      +

      Alex: This is where the talk moves from concept to action. This is where Structuring Contributions for Clarity and Quality becomes real: issue templates turn a blank text box into a guided form. That matters in practice: They help contributors provide the information maintainers need, reduce back-and-forth, and make every issue immediately actionable.

      +

      Jamie: What does someone need before they touch the keyboard?

      +

      Alex: Keep the learner anchored in Before starting this chapter, verify you have completed. Day 2 Amplifier: In Chapter 19 (Accessibility Agents), you'll use @template-builder to automate template creation. This is the part to say slowly: Complete this chapter first, then come back to Chapter 19.

      +

      Alex: These are the details that keep the idea from floating away. [ ] Chapter 4: Working with Issues - 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). [ ] Chapter 16: GitHub Copilot - Optional but helpful for generating template variations.

      -

      Alex: Here is the practical turn. Start with An analogy: packing a box: Think of it like packing a box to mail. The next useful detail is this: 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).

      -

      Alex: On the ground, that means a few things. 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.

      -

      Jamie: Give me the version that sounds like an instructor, not a manual.

      -

      Alex: Start with Learning Cards: The Three Areas. There is something to understand, something to try, and something that proves the try worked.

      -

      Alex: Here is what that changes in practice. 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. 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.

      -

      Alex: Keep the thread going. This is where 3. What Is a Commit? becomes real: a commit is a snapshot of your project at a specific moment in time. That matters in practice: It is not a diff (a list of changes). The workshop is closer to rehearsal than lecture. You hear the move, try the move, and then check what changed.

      +

      Alex: Before the learner moves on. The reason Workshop Recommendation (Chapter 17 / Challenge 14) matters is that chapter 17 is a template design and implementation chapter focused on structuring contributions with a concrete, familiar example. That gives the learner a simple foothold: it supports Challenge 14: Template Remix. The interface gets friendlier when it stops being a wall of controls and starts being a set of named places.

      +

      Alex: That becomes easier when you listen for these cues. There are 2-3 guided challenges (+ 1 optional). Automation check: none (template structure quality is design-focused). The evidence is issue comment or PR with template remixed or created. The pattern is analyze, remix, create, test.

      +

      Jamie: Give me the sequence, because order matters here.

      +

      Alex: Start with Challenge 14 Set. There is something to understand, something to try, and something that proves the try worked.

      +

      Alex: First, analyze the registration template - understand how the template you already filled out works. Then, remix the registration template - adapt it for a new use case (bug report, event, research). After that, create a Markdown template (optional) - build a Markdown-based template from scratch. Finally, test in the template chooser (optional) - verify your template appears and works. Think of it as a rail line: each stop confirms you are still on the right route before the next one.

      +

      Jamie: Turn that into a path someone can follow.

      +

      Alex: Here is the plain-English version of Challenge 14.1 Step-by-Step: Analyze the Registration Template. Understand how professional YAML form templates work by examining the one you filled out to register for this workshop. Put another way, GitHub.com - reading the template file in the git-going-with-github repository.

      +

      Alex: That shows up in the workshop in a few specific ways. 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.

      +

      Alex: First, open the template file on GitHub.com (use the link above). Then, read the YAML frontmatter (top 5 lines) and identify. After that, read the field types in the body section. Note the four types used. Finally, for each field, identify the metadata. Treat it like a recipe: do not add the next ingredient until the previous one is actually in the bowl.

      +

      Jamie: What is the ordered workflow?

      +

      Alex: First, search the file for "accessible" - notice the description mentions that all fields work with screen readers. This is professional template thinking. Then, 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. It is a checklist, but a meaningful one: every item creates evidence that the next step is safe.

      +
      +

      Jamie: Let's pause on Challenge 14.2 Step-by-Step: Remix the Registration Template. What should a learner take away from it?

      +

      Alex: This is where Challenge 14.2 Step-by-Step: Remix the Registration Template becomes real: adapt the registration template for a different use case while keeping the same YAML structure. That matters in practice: VS Code with a repository where you have write access (your fork or personal repo), or github.dev.

      +

      Alex: For a learner, the useful signals are these. Source.github/ISSUE TEMPLATE/workshop-registration.yml. Remix sample: learning-room/docs/samples/challenge-14-registration-remix-example.yml. Keep: the YAML skeleton (name, description, title, labels, body). Keep: field structure (type, id, attributes, validations).

      +

      Alex: First, pick a new context for your template (for example: bug report, event attendance, product research, accessibility audit request). Then, copy the registration template file to a new file.github/ISSUE TEMPLATE/my-template.yml. After that, change the name and description in the frontmatter to match your new context. Finally, change the title prefix (for example: [Bug Report]: or [Event]: ). It is a checklist, but a meaningful one: every item creates evidence that the next step is safe.

      +

      Jamie: Before we leave Challenge 14.2 Step-by-Step: Remix the Registration Template, what is the practical point?

      +

      Alex: First, change the labels to appropriate labels for your use case. Then, replace each field's label, description, placeholder, and options to match your new context. After that, decide which fields should be required: true and which can be optional. Finally, validate your YAML syntax: copy the file contents to yamllint.com and fix any errors. It is like walking a hallway with named doors: read the sign, enter the right room, then confirm where you landed.

      +

      Jamie: Let's pause on Challenge 14.3 (Optional) Step-by-Step: Create a Markdown Template. What should a learner take away from it?

      +

      Alex: Keep the learner anchored in Challenge 14.3 (Optional) Step-by-Step: Create a Markdown Template. Create a Markdown-based template to compare the two template formats. This is the part to say slowly: VS Code with a repository where you have write access. A good GitHub workflow is like a well-run meeting: everyone knows the topic, the next action, and who has the floor.

      +

      Alex: First, create a new file.github/ISSUE TEMPLATE/my-markdown-template.md. Then, add the Markdown template frontmatter at the top. After that, markdown templates use about instead of description (unlike YAML form templates). Finally, below the frontmatter, add 3-4 sections with HTML comment instructions. It is like walking a hallway with named doors: read the sign, enter the right room, then confirm where you landed.

      +

      Jamie: Before we leave Challenge 14.3 (Optional) Step-by-Step: Create a Markdown Template, what is the practical point?

      +

      Alex: First, commit and push. The rhythm is simple: orient, act, verify, then continue.

      +

      Jamie: Let's pause on Challenge 14.4 (Optional): Test in the Template Chooser. What should a learner take away from it?

      +

      Alex: The reason Challenge 14.4 (Optional): Test in the Template Chooser matters is that you are done when: Your template works and appears in the GitHub template picker.

      +

      Alex: First, navigate to your test repository on GitHub.com. Then, activate New Issue. After that, verify your template appears in the template chooser. Finally, activate Get started on your template and file a test issue. The rhythm is simple: orient, act, verify, then continue.

      +
      +

      Alex: Here is the practical turn. Start with Completing Challenge 14: Submit Your Evidence: Open your assigned Challenge 14 issue and post a completion comment. The next useful detail is this: Close your Challenge 14 issue when done.

      +

      Jamie: What would you say to someone who is already bracing for this to be too much?

      +

      Alex: Start with Expected Overall Outcomes. There is something to understand, something to try, and something that proves the try worked.

      +

      Alex: Here is what that changes in practice. 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.

      +

      Jamie: Let's pause on If You Get Stuck. What should a learner take away from it?

      +

      Alex: This is where If You Get Stuck becomes real: continue learning: The GitHub Skills course Introduction to Repository Management covers templates and contributor settings in an interactive format. That matters in practice: See Appendix Z for the full catalog. The workshop is closer to rehearsal than lecture. You hear the move, try the move, and then check what changed.

      +

      Alex: First, cannot find the registration template? Look in.github/ISSUE TEMPLATE/workshop-registration.yml in the git-going-with-github repository. Then, 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. After that, yAML not parsing? Compare with the remix sample in learning-room/docs/samples/challenge-14-registration-remix-example.yml and check indentation. Finally, 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. It is a checklist, but a meaningful one: every item creates evidence that the next step is safe.

      +

      Jamie: Before we leave If You Get Stuck, what is the practical point?

      +

      Alex: First, 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. Then, remix approach feels overwhelming? Start by changing just the field labels and descriptions. Do not change the structure yet. After that, ask facilitator to review your template and suggest improvements. Finally, finished but not sure you did it right? Compare your work against the Challenge 14 reference solution. It is like walking a hallway with named doors: read the sign, enter the right room, then confirm where you landed.

      Jamie: If I am listening before the workshop starts, what should settle in my mind first?

      -

      Alex: Keep the learner anchored in Commit IDs (hashes). Every commit gets a unique identifier -- a 40-character string called a SHA hash. This is the part to say slowly: In practice, you usually see only the first 7 characters: a1b2c3d.

      -

      Alex: Another way to ground it. The reason Commits are permanent (mostly) matters is that once a commit is made, it is part of the repository's history. That gives the learner a simple foothold: you can make new commits that undo the changes, but the original commit still exists in the timeline.

      +

      Alex: Keep the learner anchored in Learning Moment. They do not restrict expert contributors - they guide newcomers. This is the part to say slowly: A template that takes 2 minutes to understand saves 30 minutes of back-and-forth questions later.

      +

      Jamie: Let's pause on Learning Pattern Used in This Chapter. What should a learner take away from it?

      +

      Alex: Start with Learning Pattern Used in This Chapter. There is something to understand, something to try, and something that proves the try worked.

      +

      Alex: First, analyze an existing, working example before building your own. Then, remix by changing content while keeping structure (safe, fast iteration). After that, create from scratch only after you understand the pattern (Markdown template). Finally, test the result in the real environment (template chooser). The rhythm is simple: orient, act, verify, then continue.

      Jamie: Where do you want a learner to place their attention here?

      -

      Alex: Start with Learning Cards: Commits. There is something to understand, something to try, and something that proves the try worked.

      -

      Alex: A few details make that real. 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. 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.

      +

      Alex: Start with 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.

      +

      Alex: A few details make that real. Instructions explaining what information is needed. Section headers guiding them through the report. Checkboxes for conditions to verify. Placeholder text showing the expected format.

      +

      Alex: A solid issue habit is to read the title, the body, and the timeline before acting. You are listening for the requested action, the missing evidence, and the person who needs a response.

      -

      Alex: This is the part worth saying out loud. Here is the plain-English version of 4. What Is a Branch? See also: Chapter 14: Git in Practice shows how to create and switch branches hands-on in VS Code. Put another way, a branch is a name that points to a specific commit. It is like learning a transit route. The names of the stops matter because they tell you whether you are still going the right direction.

      -

      Jamie: Let's pause on The default branch: main. What should a learner take away from it?

      -

      Alex: This is where The default branch: main becomes real: every repository has a default branch, usually called main. That matters in practice: 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.

      -

      Alex: The next layer is this. Keep the learner anchored in Creating a branch. When you create a new branch, Git creates a new pointer that starts at the same commit you are currently on. This is the part to say slowly: Both branches point to the same commit.

      +

      Alex: This is the part worth saying out loud. Here is the plain-English version of Why they matter for accessibility projects. Accessibility bugs require specific context that general bug templates often omit. Put another way, without this context, maintainers ask follow-up questions - which delays the fix and uses everyone's time. It is like learning a transit route. The names of the stops matter because they tell you whether you are still going the right direction.

      +

      Alex: The parts worth keeping in working memory are these. Which screen reader and version? Which browser and version? Which operating system? Which WCAG success criterion is affected?

      +

      Alex: A solid pull request habit is to separate three questions: what changed, why it changed, and what still needs review. That keeps the conversation useful instead of noisy.

      +

      Jamie: Give me the version that sounds like an instructor, not a manual.

      +

      Alex: This is where 2. How Templates Work on GitHub becomes real: templates live in a specific folder in your repository.

      +

      Alex: The next layer is this. Keep the learner anchored in Description. Templates live inside your-repo/.github/. This is the part to say slowly: 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).

      -

      Jamie: Let's pause on Making commits on a branch. What should a learner take away from it?

      -

      Alex: The reason Making commits on a branch matters is that when you make a new commit while on the fix/typo branch, the fix/typo pointer moves forward to the new commit. That gives the learner a simple foothold: the main pointer stays where it was.

      -

      Alex: That matters because of the next idea. Start with HEAD: which branch are you on?: Git uses a special pointer called HEAD to track which branch you are currently working on. The next useful detail is this: When you switch branches (checkout), Git moves HEAD to point to the new branch and updates the files in your working directory to match. Think of it like entering a new building: first you find the lobby, then the room, then the door you actually need.

      -

      Jamie: Let's pause on Learning Cards: Branches. What should a learner take away from it?

      -

      Alex: Start with Learning Cards: Branches. There is something to understand, something to try, and something that proves the try worked.

      -

      Alex: These are the details that keep the idea from floating away. 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. 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.

      +

      Jamie: Let's pause on Example config.yml. What should a learner take away from it?

      +

      Alex: The reason Example config.yml matters is that with blank issues enabled: false, the "Open a blank issue" link disappears from the template chooser. That gives the learner a simple foothold: contributors must use one of your structured templates or one of the contact links.

      +

      Alex: Keep the thread going. Start with Learning Cards: How Templates Work on GitHub. There is something to understand, something to try, and something that proves the try worked.

      +

      Alex: The room should hear these as checkpoints. 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. 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.

      +

      Jamie: Let's pause on 3. Navigating the Template Picker. What should a learner take away from it?

      +

      Alex: Here is the plain-English version of 3. Navigating the Template Picker. When a repository has multiple templates, GitHub shows a template chooser page before the issue editor. Put another way, screen reader users - NVDA / JAWS (Windows).

      +

      Alex: First, click the Issues tab on any repository. Then, click the New issue button. After that, the template chooser page loads - templates appear as cards with a title, description, and "Get started" button. Finally, click "Get started" on the template you want. Treat it like a recipe: do not add the next ingredient until the previous one is actually in the bowl.

      +

      Jamie: Before we leave 3. Navigating the Template Picker, what is the practical point?

      +

      Alex: First, the issue editor opens with that template's content pre-filled. Then, navigate to the Issues tab (press T from the repository tabs landmark). After that, activate "New issue" button. Finally, the template chooser page loads. It is a checklist, but a meaningful one: every item creates evidence that the next step is safe.

      -

      Alex: Keep the teaching thread moving. This is where 5. Local vs Remote becomes real: see also: Appendix D: Git Authentication covers how to set up credentials so push and pull work without password prompts. That matters in practice: So far, we have talked about one repository.

      -

      Jamie: Let's pause on The remote repository. What should a learner take away from it?

      -

      Alex: Keep the learner anchored in The remote repository. The remote repository is the one on GitHub.com. This is the part to say slowly: When you see a repository URL like github.com/Community-Access/git-going-with-github, that is the remote.

      -

      Alex: Keep the teaching thread moving. The reason The local repository matters is that the local repository is the copy on your computer. That gives the learner a simple foothold: when you run git clone, Git downloads the entire repository -- all files, all branches, all history -- to your machine. The interface gets friendlier when it stops being a wall of controls and starts being a set of named places.

      +

      Alex: Another way to ground it. This is where Bypassing the Chooser becomes real: if you want to file an issue without using a template.

      +

      Alex: The practical takeaway is this. Scroll past all templates to the bottom of the chooser page. Activate "Open a blank issue".

      +

      Jamie: Let's pause on Learning Cards: Navigating the Template Picker. What should a learner take away from it?

      +

      Alex: Start with Learning Cards: Navigating the Template Picker. There is something to understand, something to try, and something that proves the try worked.

      +

      Alex: The practical takeaway is this. 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. 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.

      +

      Jamie: Let's pause on 4. The Accessibility Agents Issue Templates. What should a learner take away from it?

      +

      Alex: The reason 4. The Accessibility Agents Issue Templates matters is that accessibility Agents uses templates to structure contributions. That gives the learner a simple foothold: navigate to.github/ISSUE TEMPLATE/ in the repository to read them. The interface gets friendlier when it stops being a wall of controls and starts being a set of named places.

      +

      Alex: First, click the Code tab on the repository. Then, click the.github folder in the file listing. After that, click ISSUE TEMPLATE. Finally, you'll see the template files - click any to read it. The rhythm is simple: orient, act, verify, then continue.

      +

      Jamie: Before we leave 4. The Accessibility Agents Issue Templates, what is the practical point?

      +

      Alex: First, open the Code tab. Then, use Ctrl+Alt+Down/Up (NVDA/JAWS) or VO+Arrow (VoiceOver) in the files table to reach the.github folder. After that, activate the folder. Finally, activate ISSUE TEMPLATE. Think of it as a rail line: each stop confirms you are still on the right route before the next one.

      -

      Jamie: Let's pause on The two-copy model. What should a learner take away from it?

      -

      Alex: Start with The two-copy model: The text diagram above shows two boxes side by side connected by arrows. The next useful detail is this: The left box is labeled "Your computer (local)" and contains working directory, staging area, and repository.

      -

      Alex: Keep the teaching thread moving. Start with Learning Cards: Local vs Remote. There is something to understand, something to try, and something that proves the try worked.

      -

      Alex: The practical anchors are these. 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. 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.

      -

      Jamie: Let's pause on 6. Push, Pull, and Fetch. What should a learner take away from it?

      -

      Alex: This is where 6. Push, Pull, and Fetch becomes real: these three operations keep your local and remote repositories synchronized.

      +

      Jamie: Let's pause on Reading a Template File. What should a learner take away from it?

      +

      Alex: Start with 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").

      +

      Alex: The practical takeaway is this. Frontmatter (between --- delimiters): name, about, title, labels, assignees.

      +

      Alex: Hold that next to this. Here is the plain-English version of Example frontmatter. The about text appears in the template chooser. Put another way, the title pre-fills the issue title field (the contributor replaces the placeholder).

      +

      Jamie: Let's pause on Tool Cards: Create an Issue Template. What should a learner take away from it?

      +

      Alex: Start with Tool Cards: Create an Issue Template. There is something to understand, something to try, and something that proves the try worked.

      +

      Alex: First, go to Settings General (scroll to Features section) Set up templates. Then, choose a starter template or create a blank one. After that, edit the template content and click Propose changes to commit. Finally, create the file.github/ISSUE TEMPLATE/your-template.md (or.yml for form-based). It is a checklist, but a meaningful one: every item creates evidence that the next step is safe.

      +

      Jamie: Before we leave Tool Cards: Create an Issue Template, what is the practical point?

      +

      Alex: First, add YAML frontmatter (name, description, title, labels) and body content. Then, commit and push. It is like walking a hallway with named doors: read the sign, enter the right room, then confirm where you landed.

      +

      Alex: Treat examples as spoken recipes, not decorations. You may hear something like 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. Read the command, understand what it changes, then run it only when the repository state matches the lesson.

      +
      +

      Alex: That connects to another useful point. Keep the learner anchored in Choosing Between Markdown and YAML Templates. See also: Appendix Q: GitHub Actions covers how templates connect to automated workflows. This is the part to say slowly: Before creating a template, decide which format best suits your needs. A good GitHub workflow is like a well-run meeting: everyone knows the topic, the next action, and who has the floor.

      +

      Jamie: Let's pause on Use Markdown templates when. What should a learner take away from it?

      +

      Alex: Start with Use Markdown templates when. There is something to understand, something to try, and something that proves the try worked.

      +

      Alex: The practical takeaway is this. 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.

      +

      Alex: Keep the teaching thread moving. Start with Use YAML form templates when: For accessibility projects: YAML form templates are strongly recommended. The next useful detail is this: Accessibility bug reports require specific context (screen reader, browser, OS, version numbers) that Markdown templates rely on contributors to remember.

      +

      Alex: The practical takeaway is this. 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.

      +

      Jamie: Let's pause on Markdown Template Structure. What should a learner take away from it?

      +

      Alex: Here is the plain-English version of Markdown Template Structure. A Markdown template consists of two parts. Put another way, yAML Frontmatter (between --- delimiters).

      Jamie: How do you keep commands from becoming magic words?

      -

      Alex: Keep the learner anchored in Push: share your work. git push sends your local commits to the remote. This is the part to say slowly: After pushing, anyone who looks at the repository on GitHub.com will see your changes. A good GitHub workflow is like a well-run meeting: everyone knows the topic, the next action, and who has the floor.

      -

      Alex: Treat examples as spoken recipes, not decorations. You may hear something like git push origin fix/typo. git push -u origin fix/typo. Read the command, understand what it changes, then run it only when the repository state matches the lesson.

      -

      Jamie: What is the safe way to learn from that example?

      -

      Alex: The reason Pull: get other people's work matters is that git pull downloads new commits from the remote and immediately merges them into your current branch. That gives the learner a simple foothold: this is how you get changes that other people (or you on another computer) have pushed.

      -

      Alex: Treat examples as spoken recipes, not decorations. You may hear something like git pull origin main. Read the command, understand what it changes, then run it only when the repository state matches the lesson.

      -

      Jamie: What should happen before anyone copies and runs it?

      -

      Alex: Start with Fetch: check for updates without merging: git fetch downloads new commits from the remote but does not change your working directory or current branch. The next useful detail is this: It just updates your local knowledge of what the remote looks like.

      -

      Alex: Treat examples as spoken recipes, not decorations. You may hear something like git fetch origin. git log main.origin/main --oneline. Read the command, understand what it changes, then run it only when the repository state matches the lesson.

      +

      Alex: This is where 2. Markdown Body becomes real: the template content that pre-fills the issue editor. The workshop is closer to rehearsal than lecture. You hear the move, try the move, and then check what changed.

      +

      Alex: Treat examples as spoken recipes, not decorations. You may hear something like 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. Read the command, understand what it changes, then run it only when the repository state matches the lesson.

      +

      Jamie: Let's pause on Markdown template tips. What should a learner take away from it?

      +

      Alex: Start with Markdown template tips. There is something to understand, something to try, and something that proves the try worked.

      +

      Alex: The practical takeaway is this. 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.

      -

      Jamie: Let's pause on 7. Why Merge Conflicts Happen. What should a learner take away from it?

      -

      Alex: Here is the plain-English version of 7. Why Merge Conflicts Happen. A merge conflict happens when Git cannot automatically combine two sets of changes.

      -

      Alex: Keep the teaching thread moving. This is where When conflicts occur becomes real: conflicts happen when two branches modify the same lines in the same file. That matters in practice: Git knows how to merge changes to different files, and even different parts of the same file. The workshop is closer to rehearsal than lecture. You hear the move, try the move, and then check what changed.

      -

      Jamie: Let's pause on What a conflict looks like. What should a learner take away from it?

      -

      Alex: Keep the learner anchored in What a conflict looks like. When a conflict occurs, Git marks the conflicting section in the file with special markers.

      +

      Alex: Keep the teaching thread moving. The reason Complete Markdown Template Example matters is that here's a complete accessibility bug report template in Markdown format. That gives the learner a simple foothold: save this as.github/ISSUE TEMPLATE/accessibility-bug-simple.md.

      +

      Jamie: Let's pause on When to use this Markdown version instead of YAML. What should a learner take away from it?

      +

      Alex: Start with When to use this Markdown version instead of YAML. There is something to understand, something to try, and something that proves the try worked.

      +

      Alex: The practical takeaway is this. 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.

      +

      Alex: Keep the teaching thread moving. Start with Markdown template accessibility considerations. There is something to understand, something to try, and something that proves the try worked.

      +

      Alex: The practical takeaway is this. 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.

      -

      Jamie: Let's pause on How to resolve a conflict. What should a learner take away from it?

      -

      Alex: The reason How to resolve a conflict matters is that the Day 1 connection: In Chapter 7, you resolved a merge conflict on GitHub.com using the web editor. That gives the learner a simple foothold: 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.

      -

      Alex: First, open the file with the conflict markers. Then, read both versions and decide which text to keep (or write a new version that combines both). After that, delete the conflict markers ( ). Finally, save the file. The rhythm is simple: orient, act, verify, then continue.

      -

      Jamie: Before we leave How to resolve a conflict, what is the practical point?

      -

      Alex: First, stage and commit the resolved file. Think of it as a rail line: each stop confirms you are still on the right route before the next one.

      -

      Jamie: Let's pause on Why conflicts are normal. What should a learner take away from it?

      -

      Alex: Start with Why conflicts are normal: They happen in every project where more than one person works at the same time. The next useful detail is this: The fact that Git stops and asks is a safety feature -- it prevents data loss by never silently choosing one version over another.

      -

      Alex: Keep the teaching thread moving. Start with Learning Cards: Merge Conflicts. There is something to understand, something to try, and something that proves the try worked.

      -

      Alex: That shows up in the workshop in a few specific ways. 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. 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.

      -
      -

      Jamie: Let's pause on 8. The Git Timeline. What should a learner take away from it?

      -

      Alex: This is where 8. The Git Timeline becomes real: every commit has a parent pointer (except the very first commit). That matters in practice: This creates a chain -- a timeline of the project's history.

      -

      Alex: Keep the teaching thread moving. Keep the learner anchored in 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. This is the part to say slowly: 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.

      -

      Jamie: Let's pause on Branching creates parallel timelines. What should a learner take away from it?

      -

      Alex: The reason Branching creates parallel timelines matters is that when two branches diverge (both have commits that the other does not), the timeline splits into two parallel paths. That gives the learner a simple foothold: both branches share commits A and B (their common history).

      +

      Jamie: Let's pause on Creating Markdown Templates: The Manual Workflow (Browser). What should a learner take away from it?

      +

      Alex: This is where Creating Markdown Templates: The Manual Workflow (Browser) becomes real: screen reader users (NVDA / JAWS / VoiceOver). That matters in practice: Alternative: Navigate directly to.github/ISSUE TEMPLATE/ → activate the "+" button → "Create new file".

      +

      Alex: The practical takeaway is this. Template name: what appears in the chooser heading. About: the description in the chooser. Template content: the Markdown body.

      +

      Alex: First, navigate to your fork of accessibility-agents on GitHub. Then, click the Settings tab. After that, scroll to the "Features" section → click the checkmark next to "Issues" → click "Set up templates". Finally, or navigate directly to.github/ISSUE TEMPLATE/ in your fork → click the + button → "Create new file". It is a checklist, but a meaningful one: every item creates evidence that the next step is safe.

      +

      Jamie: Before we leave Creating Markdown Templates: The Manual Workflow (Browser), what is the practical point?

      +

      Alex: First, GitHub opens a template editor. Fill in the template name, about description, and body. Then, GitHub auto-populates the filename - you can change it. After that, click "Propose changes" → create a PR to add the template. Finally, go to the Settings tab (press T from the tabs landmark, then navigate to "Settings"). It is like walking a hallway with named doors: read the sign, enter the right room, then confirm where you landed.

      +

      Jamie: Let's pause on Creating Markdown Templates: The VS Code Workflow. What should a learner take away from it?

      +

      Alex: Start with Creating Markdown Templates: The VS Code Workflow. There is something to understand, something to try, and something that proves the try worked.

      +

      Alex: First, open your accessibility-agents fork in VS Code. Then, navigate in Explorer to.github/ISSUE TEMPLATE/. After that, create a new file: Ctrl+N → save as your-template-name.md in that folder. Finally, add frontmatter first (between --- delimiters), then the body. It is like walking a hallway with named doors: read the sign, enter the right room, then confirm where you landed.

      +

      Jamie: Before we leave Creating Markdown Templates: The VS Code Workflow, what is the practical point?

      +

      Alex: First, commit and push: open Source Control (Ctrl+Shift+G) → stage → commit → push. The rhythm is simple: orient, act, verify, then continue.

      +

      Jamie: Let's pause on File naming conventions. What should a learner take away from it?

      +

      Alex: Start with File naming conventions. There is something to understand, something to try, and something that proves the try worked.

      +

      Alex: The practical takeaway is this. Use lowercase with hyphens: accessibility-bug.md, feature-request.md. Be descriptive: security-vulnerability.md is better than security.md. Avoid spaces in filenames.

      -

      Alex: Keep the teaching thread moving. Start with 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 next useful detail is this: The two timelines join back together. Think of it like entering a new building: first you find the lobby, then the room, then the door you actually need.

      -

      Jamie: Let's pause on 9. Putting It All Together. What should a learner take away from it?

      -

      Alex: Here is the plain-English version of 9. Putting It All Together. Here is the complete workflow that you will practice in Chapter 14, translated through the mental model. Put another way, everything in this table maps directly to the three areas (Section 2), the two copies (Section 5), and the timeline (Section 8).

      -

      Alex: Keep the teaching thread moving. This is where Quick mental model checklist becomes real: before running a Git command, ask yourself. That matters in practice: If you can answer these four questions, you can troubleshoot almost any Git situation.

      -

      Alex: That becomes easier when you listen for these cues. 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?

      +

      Alex: Keep the teaching thread moving. Start with Learning Cards: Creating a New Template. There is something to understand, something to try, and something that proves the try worked.

      +

      Alex: The practical takeaway is this. 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. 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.

      +

      Jamie: Let's pause on 6. YAML Form-Based Templates. What should a learner take away from it?

      +

      Alex: Here is the plain-English version of 6. YAML Form-Based Templates. YAML templates create a proper form interface - labeled fields, dropdowns, checkboxes - rather than a pre-filled text editor. Put another way, this is the preferred format for modern GitHub projects, especially those focused on accessibility.

      +

      Alex: Keep the teaching thread moving. This is where Why YAML Forms Are Better for Accessibility becomes real: explicit labels: Each field has a label: that screen readers announce. That matters in practice: In Markdown templates, users must infer structure from headings and placeholder text.

      -

      Jamie: What do you want them to do when the plan breaks?

      -

      Alex: Keep the learner anchored in 10. If You Get Stuck. Next: Chapter 14: Git in Practice Back: Chapter 12: VS Code Accessibility Related appendices: Appendix E: Advanced Git Appendix D: Git Authentication.

      -

      Alex: Keep the teaching thread moving. The reason Managing Repositories, Branches, and Changes Accessibly matters is that 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. That gives the learner a simple foothold: prerequisites: VS Code Setup & Accessibility Basics, Working with Pull Requests, Merge Conflicts Mac keyboard shortcuts: Throughout this chapter, all Ctrl+ shortcuts use Cmd+ on Mac, and Alt+ shortcuts use Option+. The interface gets friendlier when it stops being a wall of controls and starts being a set of named places.

      -

      Jamie: How should they picture the shape of the workshop?

      -

      Alex: Start with Workshop Recommendation (Chapter 14 / Challenge 10): Chapter 14 is the first local Git workflow chapter with hands-on repository management. The next useful detail is this: It supports Challenge 10: Go Local.

      -

      Alex: For a learner, the useful signals are these. There are 3. Each challenge should take under 10 minutes each. The evidence is PR metadata, branch names, and committed changes. The pattern is clone, branch, edit, commit, push, PR.

      +

      Jamie: Let's pause on YAML Template Structure. What should a learner take away from it?

      +

      Alex: Keep the learner anchored in YAML Template Structure. A YAML form template consists of several parts.

      +

      Alex: Keep the teaching thread moving. Start with Top-level keys. There is something to understand, something to try, and something that proves the try worked.

      +

      Alex: The practical takeaway is this. 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).

      +

      Jamie: Let's pause on YAML Field Types Reference. What should a learner take away from it?

      +

      Alex: Start with YAML Field Types Reference: GitHub supports several field types in YAML form templates. The next useful detail is this: Each has specific attributes and uses.

      -

      Jamie: Let's pause on Challenge 10 Practice Set. What should a learner take away from it?

      -

      Alex: Start with Challenge 10 Practice Set. There is something to understand, something to try, and something that proves the try worked.

      -

      Alex: First, clone your Learning Room repository - clone your private Learning Room repo to your local machine using VS Code. Then, 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. After that, 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. Treat it like a recipe: do not add the next ingredient until the previous one is actually in the bowl.

      -

      Jamie: Let's pause on Practice 10.1 Step-by-Step: Clone Your Learning Room Repository. What should a learner take away from it?

      -

      Alex: This is where Practice 10.1 Step-by-Step: Clone Your Learning Room Repository becomes real: get a local copy of your Learning Room repository on your machine using VS Code. That matters in practice: VS Code desktop (or github.dev if you cannot install desktop VS Code).

      -

      Alex: First, open VS Code. If no folder is open, you should see the Welcome tab. Then, open the Command Palette: Ctrl+Shift+P (Mac: Cmd+Shift+P). After that, type git clone and select Git: Clone. Finally, VS Code asks for a repository URL. Paste your Learning Room repo URL (it looks like https://github.com/the workshop organization/learning-room-your username.git). You can copy this from the green Code button on your repo's GitHub page. It is a checklist, but a meaningful one: every item creates evidence that the next step is safe.

      -

      Jamie: Before we leave Practice 10.1 Step-by-Step: Clone Your Learning Room Repository, what is the practical point?

      -

      Alex: First, press Enter. Then, 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. After that, VS Code clones the repository. When it finishes, a notification appears asking "Would you like to open the cloned repository?" Activate Open. Finally, 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. It is like walking a hallway with named doors: read the sign, enter the right room, then confirm where you landed.

      -

      Jamie: Let's pause on Practice 10.2 Step-by-Step: Create a Branch and Commit. What should a learner take away from it?

      -

      Alex: Keep the learner anchored in Practice 10.2 Step-by-Step: Create a Branch and Commit. See also: Chapter 13: How Git Works explains the three areas (working directory, staging, repository) that make commits meaningful. This is the part to say slowly: Check out (or create) a properly named branch, edit a file, stage the change, and commit with a clear message. A good GitHub workflow is like a well-run meeting: everyone knows the topic, the next action, and who has the floor.

      -

      Alex: First, open the Command Palette: Ctrl+Shift+P (Mac: Cmd+Shift+P). Then, 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/your username. If the branch does not exist yet, type git create branch and select Git: Create Branch. After that, 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. Finally, 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). It is like walking a hallway with named doors: read the sign, enter the right room, then confirm where you landed.

      -

      Jamie: Before we leave Practice 10.2 Step-by-Step: Create a Branch and Commit, what is the practical point?

      -

      Alex: First, 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). Then, 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.". After that, 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.". Finally, 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. The rhythm is simple: orient, act, verify, then continue.

      +

      Alex: Keep the teaching thread moving. Here is the plain-English version of 1. markdown - Instructional Text. Displays formatted Markdown content. Put another way, use for instructions, warnings, or explanations.

      +

      Alex: The practical takeaway is this. value (required): Markdown content to display. Use for multi-line text.

      +

      Jamie: Let's pause on 2. input - Single-line Text Field. What should a learner take away from it?

      +

      Alex: This is where 2. input - Single-line Text Field becomes real: best for short answers like version numbers, URLs, or names. That matters in practice: Screen reader announcement: "Version Number, required, edit text, Which version of the software are you using?".

      +

      Alex: The practical takeaway is this. label (required): Field label, announced by screen readers. description (optional): Help text below the label. placeholder (optional): Placeholder text inside the field. required (boolean): Whether the field must be filled.

      +

      Alex: Keep the teaching thread moving. Keep the learner anchored in 3. textarea - Multi-line Text Area. Best for descriptions, reproduction steps, code snippets, or any long-form content. This is the part to say slowly: Accessibility tip: Use placeholder for examples, value for pre-filled template text that contributors should edit. A good GitHub workflow is like a well-run meeting: everyone knows the topic, the next action, and who has the floor.

      +

      Alex: The practical takeaway is this. label (required): Field label. description (optional): Help text. placeholder (optional): Placeholder text (multi-line with ). value (optional): Pre-filled content (multi-line with ).

      -

      Jamie: Let's pause on Practice 10.3 Step-by-Step: Push and Open a Linked PR. What should a learner take away from it?

      -

      Alex: The reason Practice 10.3 Step-by-Step: Push and Open a Linked PR matters is that push your branch to GitHub and open a PR in your Learning Room repo that references your challenge issue. That gives the learner a simple foothold: VS Code (for the push) and GitHub.com (for the PR).

      -

      Alex: First, open the Command Palette: Ctrl+Shift+P (Mac: Cmd+Shift+P). Then, 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. After that, 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. Finally, open your browser and navigate to your Learning Room repository on GitHub. The rhythm is simple: orient, act, verify, then continue.

      -

      Jamie: Before we leave Practice 10.3 Step-by-Step: Push and Open a Linked PR, what is the practical point?

      -

      Alex: First, GitHub usually shows a yellow banner: "yourname recently pushed to learn/yourname." Activate the Compare & pull request button in that banner. Then, 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/your username branch. After that, in the PR title, write a descriptive title (for example: "docs: improve welcome.md introduction"). Finally, 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. Think of it as a rail line: each stop confirms you are still on the right route before the next one.

      -

      Alex: Keep the teaching thread moving. Start with Completing Challenge 10: Submit Your Evidence: Open your assigned Challenge 10 issue in your Learning Room repo and post a completion comment. The next useful detail is this: Close your Challenge 10 issue when your branch is pushed and the PR is open.

      -

      Jamie: Let's pause on Expected Outcomes. What should a learner take away from it?

      -

      Alex: Start with Expected Outcomes. There is something to understand, something to try, and something that proves the try worked.

      -

      Alex: The parts worth keeping in working memory are these. 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.

      +

      Jamie: Let's pause on 4. dropdown - Select Menu. What should a learner take away from it?

      +

      Alex: The reason 4. dropdown - Select Menu matters is that a dropdown menu with predefined options. That gives the learner a simple foothold: best for bounded answer spaces like OS, browser, or severity.

      +

      Alex: The practical takeaway is this. label (required):Field label. description (optional): Help text. options (required): Array of choices (strings). multiple (boolean, default false): Whether user can select multiple options.

      +

      Alex: First, field is announced as "Browser, required, combo box". Then, press Down Arrow or Alt+Down to expand the dropdown. After that, up/Down Arrow to navigate options. Finally, screen reader announces each option. The rhythm is simple: orient, act, verify, then continue.

      +

      Jamie: Before we leave 4. dropdown - Select Menu, what is the practical point?

      +

      Alex: First, enter or Space to select. Think of it as a rail line: each stop confirms you are still on the right route before the next one.

      +

      Jamie: Let's pause on 5. checkboxes - Checkbox Group. What should a learner take away from it?

      +

      Alex: Start with 5. checkboxes - Checkbox Group: Contributors can select multiple options or use as a verification checklist. The next useful detail is this: No top-level validation - validation is per-checkbox in options.

      +

      Alex: The practical takeaway is this. label (required): Group label. description (optional): Group description. options (required): Array of checkbox objects. label (required): Checkbox label (what the user sees).

      +

      Alex: First, group label announced: "Before Submitting, Please verify these items". Then, each checkbox announced as "I searched for existing issues, checkbox, not checked, required". After that, screen reader users can check each box with Space. Think of it as a rail line: each stop confirms you are still on the right route before the next one.

      +

      Jamie: Let's pause on Choosing the right field type. What should a learner take away from it?

      +

      Alex: Start with Choosing the right field type. There is something to understand, something to try, and something that proves the try worked.

      +

      Alex: The practical takeaway is this. 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.

      -

      Jamie: Let's pause on If You Get Stuck. What should a learner take away from it?

      -

      Alex: This is where If You Get Stuck becomes real: continue learning: The GitHub Skills course Introduction to Git walks through commits, branches, and merges in an interactive, self-paced format. That matters in practice: See Appendix Z for the full catalog. The workshop is closer to rehearsal than lecture. You hear the move, try the move, and then check what changed.

      -

      Alex: First, command Palette does not open? Confirm you are in VS Code (not the browser) and press Ctrl+Shift+P (Mac: Cmd+Shift+P). Then, source Control panel is empty? You may not have saved your file yet. Press Ctrl+S to save, then check again. After that, 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. Finally, branch name wrong? Open Command Palette, run Git: Rename Branch. to fix it before pushing. It is a checklist, but a meaningful one: every item creates evidence that the next step is safe.

      -

      Jamie: Before we leave If You Get Stuck, what is the practical point?

      -

      Alex: First, cannot find the "Compare & pull request" banner on GitHub? Navigate to Pull requests tab and create the PR manually (step 6 above). Then, 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. After that, ask facilitator to verify your clone location, branch name, and help with one push. Finally, finished but not sure you did it right? Compare your work against the Challenge 10 reference solution. It is like walking a hallway with named doors: read the sign, enter the right room, then confirm where you landed.

      -

      Jamie: Let's pause on Learning Moment. What should a learner take away from it?

      -

      Alex: Keep the learner anchored in Learning Moment. Local Git operations give you full control and immediate feedback. This is the part to say slowly: You can see your changes, review them, and fix mistakes before they reach GitHub.

      -

      Jamie: Let's pause on Learning Pattern Used in This Chapter. What should a learner take away from it?

      -

      Alex: Start with Learning Pattern Used in This Chapter. There is something to understand, something to try, and something that proves the try worked.

      -

      Alex: First, clone once to get a local copy of the project. Then, branch before editing (never work directly on main). After that, make small, focused edits with clear commit messages. Finally, push and open a PR that links to an issue for traceability. The rhythm is simple: orient, act, verify, then continue.

      -

      Jamie: Before we leave Learning Pattern Used in This Chapter, what is the practical point?

      -

      Alex: First, verify each step before moving to the next. Think of it as a rail line: each stop confirms you are still on the right route before the next one.

      +

      Alex: Keep the teaching thread moving. Start with Learning Cards: YAML Form Templates. There is something to understand, something to try, and something that proves the try worked.

      +

      Alex: The practical takeaway is this. 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. 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.

      +

      Jamie: Let's pause on 7. Building an Accessibility Bug Report Template. What should a learner take away from it?

      +

      Alex: Keep the learner anchored in 7. Building an Accessibility Bug Report Template. the learner will create a YAML form template specifically for accessibility bug reports in accessibility-agents.

      +

      Alex: Keep the teaching thread moving. The reason Full Template matters is that save this as.github/ISSUE TEMPLATE/accessibility-bug.yml in your fork.

      -

      Jamie: Let's pause on About Learning Cards. What should a learner take away from it?

      -

      Alex: Start with About Learning Cards: Throughout this chapter, each major operation includes learning cards - expandable sections showing how to accomplish the same task from multiple perspectives. The next useful detail is this: Open the card that matches how you work.

      -

      Jamie: Let's pause on Tool Cards: Clone a Repository (Day 2). What should a learner take away from it?

      -

      Alex: Here is the plain-English version of Tool Cards: Clone a Repository (Day 2). VS Code Desktop (primary for Day 2). Put another way, github.dev (web editor): No clone needed. It is like learning a transit route. The names of the stops matter because they tell you whether you are still going the right direction.

      -

      Alex: First, ctrl+Shift+P Git: Clone paste the HTTPS URL choose a folder Open. Then, file Clone Repository paste URL or select from your account Clone. Treat it like a recipe: do not add the next ingredient until the previous one is actually in the bowl.

      -

      Alex: Treat examples as spoken recipes, not decorations. You may hear something like git clone https://github.com/owner/repo.git && cd repo. gh repo clone owner/repo && cd repo. Read the command, understand what it changes, then run it only when the repository state matches the lesson.

      -

      Jamie: Let's pause on Method 1: Command Palette (Recommended for Screen Readers). What should a learner take away from it?

      -

      Alex: Start with Method 1: Command Palette (Recommended for Screen Readers). There is something to understand, something to try, and something that proves the try worked.

      -

      Alex: First, open Command Palette: Ctrl+Shift+P (Mac: Cmd+Shift+P). Then, type "git clone". After that, select "Git: Clone". Finally, paste the repository URL (example: https://github.com/community-access/accessibility-agents.git). It is a checklist, but a meaningful one: every item creates evidence that the next step is safe.

      -

      Jamie: Before we leave Method 1: Command Palette (Recommended for Screen Readers), what is the practical point?

      -

      Alex: First, press Enter. Then, choose a local folder where the repository should be cloned. After that, VS Code asks: "Would you like to open the cloned repository?" - select "Open". It is like walking a hallway with named doors: read the sign, enter the right room, then confirm where you landed.

      -

      Alex: A solid navigation habit is to prove where you are before activating controls. Headings, landmarks, and the address bar are not trivia; they are your map.

      +

      Jamie: Let's pause on What Makes This Template Accessible. What should a learner take away from it?

      +

      Alex: Start with What Makes This Template Accessible: This template is itself an accessibility contribution.

      +

      Alex: The practical takeaway is this. 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.

      +

      Alex: Keep the teaching thread moving. Here is the plain-English version of A Second Template: Feature Request Form. The bug report template above is specific to accessibility issues. Put another way, once you understand the pattern, you can create templates for any contribution type. It is like learning a transit route. The names of the stops matter because they tell you whether you are still going the right direction.

      +

      Jamie: Let's pause on Designing Templates for Your Own Projects. What should a learner take away from it?

      +

      Alex: This is where Designing Templates for Your Own Projects becomes real: when designing templates for a project you maintain, use these principles. That matters in practice: Ask for the minimum that makes the report actionable.

      -

      Alex: Keep the teaching thread moving. Start with Screen reader navigation. There is something to understand, something to try, and something that proves the try worked.

      -

      Alex: The practical takeaway is this. 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.

      -

      Jamie: Let's pause on Method 2: Start Page Clone Button. What should a learner take away from it?

      -

      Alex: The reason Method 2: Start Page Clone Button matters is that the Start page is keyboard-accessible. That gives the learner a simple foothold: tab to navigate between "New File," "Open Folder," and "Clone Repository" buttons.

      -

      Alex: First, open VS Code (no folder open). Then, the Start page appears. After that, navigate to "Clone Git Repository" button - press Enter. Finally, paste repository URL → Enter. The rhythm is simple: orient, act, verify, then continue.

      -

      Jamie: Before we leave Method 2: Start Page Clone Button, what is the practical point?

      -

      Alex: First, choose destination folder. Then, open when prompted. Think of it as a rail line: each stop confirms you are still on the right route before the next one.

      -

      Jamie: Let's pause on Method 3: From GitHub.com. What should a learner take away from it?

      -

      Alex: Start with Method 3: From GitHub.com. There is something to understand, something to try, and something that proves the try worked.

      -

      Alex: First, on any GitHub repository page, click the green "Code" button. Then, copy the HTTPS URL (recommended) or SSH URL. After that, open VS Code → Ctrl+Shift+P (Mac: Cmd+Shift+P) → "Git: Clone". Finally, paste URL → Enter. Think of it as a rail line: each stop confirms you are still on the right route before the next one.

      -

      Jamie: Before we leave Method 3: From GitHub.com, what is the practical point?

      -

      Alex: First, choose destination → Open. Treat it like a recipe: do not add the next ingredient until the previous one is actually in the bowl.

      +

      Alex: Keep the teaching thread moving. Start with Learning Cards: Building an Accessibility Bug Report Template. There is something to understand, something to try, and something that proves the try worked.

      +

      Alex: The practical takeaway is this. 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. 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.

      +

      Jamie: Let's pause on 8. Pull Request Templates. What should a learner take away from it?

      +

      Alex: The reason 8. Pull Request Templates matters is that a pull request template appears as the default body of every new PR in your repository. That gives the learner a simple foothold: file location.github/pull request template.md (singular - only one PR template per repo).

      +

      Jamie: What is the safe way to learn from that example?

      +

      Alex: Start with Reading the Accessibility Agents PR Template: Open.github/pull request template.md in VS Code. The next useful detail is this: the learner will see the standard sections the project expects. Think of it like entering a new building: first you find the lobby, then the room, then the door you actually need.

      +

      Alex: Treat examples as spoken recipes, not decorations. You may hear something like 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. Read the command, understand what it changes, then run it only when the repository state matches the lesson.

      -

      Jamie: Let's pause on Learning Cards: Cloning a Repository. What should a learner take away from it?

      -

      Alex: Here is the plain-English version of Learning Cards: Cloning a Repository. Low vision users (zoom, high contrast). Put another way, cloning works the same as the Command Palette method above.

      -

      Alex: First, 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. Then, 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. After that, 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. Finally, 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. Treat it like a recipe: do not add the next ingredient until the previous one is actually in the bowl.

      -

      Jamie: Before we leave Learning Cards: Cloning a Repository, what is the practical point?

      -

      Alex: First, navigate to the repository on GitHub.com. Then, press. (period) to open github.dev - a browser-based VS Code editor. After that, the full repository opens in an editor with file tree, search, and editing. Finally, changes are committed directly to GitHub from the browser. It is a checklist, but a meaningful one: every item creates evidence that the next step is safe.

      -

      Alex: Treat examples as spoken recipes, not decorations. You may hear something like 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. Read the command, understand what it changes, then run it only when the repository state matches the lesson.

      -

      Alex: Keep the teaching thread moving. This is where Try It Now: Clone the Sci-Fi Themes Repo becomes real: to make your first clone meaningful and fun, try cloning the VS Code Sci-Fi Thinking Phrases repository. That matters in practice: Repository URL: https://github.com/community-access/vscode-sci-fi-themes.git.

      -

      Alex: The practical takeaway is this. 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.

      -

      Jamie: Let's pause on Why Clone This? What should a learner take away from it?

      -

      Alex: Start with Why Clone This? There is something to understand, something to try, and something that proves the try worked.

      -

      Alex: The practical takeaway is 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!

      +

      Jamie: Let's pause on Learning Cards: Pull Request Templates. What should a learner take away from it?

      +

      Alex: Start with Learning Cards: Pull Request Templates. There is something to understand, something to try, and something that proves the try worked.

      +

      Alex: The practical takeaway is this. 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. 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.

      +

      Alex: Keep the teaching thread moving. Start with Learning Cards: Hands-On Activity. There is something to understand, something to try, and something that proves the try worked.

      +

      Alex: The practical takeaway is this. 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. 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.

      +

      Jamie: How do these exercises create confidence instead of pressure?

      +

      Alex: Keep the learner anchored in Exercise A - Use an Existing Template. Your Mission: File your first issue using a structured template. This is the part to say slowly: You'll experience the template as an end-user, which teaches you what good template design feels like.

      -

      Jamie: Let's pause on Quick Start. What should a learner take away from it?

      -

      Alex: The reason Quick Start matters is that see CLONE-THIS-REPO.md in that repo for full instructions. That gives the learner a simple foothold: if you prefer not to clone locally, you can work entirely on GitHub.com. The interface gets friendlier when it stops being a wall of controls and starts being a set of named places.

      -

      Alex: First, clone: Ctrl+Shift+P → "Git: Clone" → paste URL above → Enter. Then, choose a destination folder and open when prompted. After that, navigate to the themes/ folder and pick a.json file (star-trek, hitchhikers, or star-wars). Finally, copy the chat.agent.thinking.phrases setting into your VS Code settings.json. The rhythm is simple: orient, act, verify, then continue.

      -

      Jamie: Before we leave Quick Start, what is the practical point?

      -

      Alex: First, reload VS Code: Ctrl+Shift+P → "Developer: Reload Window". Then, open Copilot Chat (Ctrl+Shift+I) and ask a question--watch your custom phrases appear! After that, navigate to the repository on GitHub. Finally, click any file to view it, then click the pencil icon (Edit) to modify it directly in the browser. Think of it as a rail line: each stop confirms you are still on the right route before the next one.

      -

      Alex: Treat examples as spoken recipes, not decorations. You may hear something like 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. Read the command, understand what it changes, then run it only when the repository state matches the lesson.

      -

      Jamie: Let's pause on 2. The Source Control Panel - Complete Walkthrough. What should a learner take away from it?

      -

      Alex: Start with 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. The next useful detail is this: This section provides a complete screen reader walkthrough of every interactive element.

      -

      Alex: Keep the teaching thread moving. Here is the plain-English version of Opening the Source Control Panel. Shortcut: Ctrl+Shift+G (Mac: Cmd+Shift+G).

      +

      Jamie: Let's pause on Step 1: Navigate to the Accessibility Agents Issues Section. What should a learner take away from it?

      +

      Alex: Start with Step 1: Navigate to the Accessibility Agents Issues Section. There is something to understand, something to try, and something that proves the try worked.

      +

      Alex: The practical takeaway is this. A tab labeled "Issues" (currently active). A list of open/closed issues below. A large green button labeled "New issue" on the right side. Go directly to: https://github.com/community-access/accessibility-agents/issues/new. This opens the issue template chooser.

      +

      Alex: First, open GitHub in your browser. Then, navigate to the community-access/accessibility-agents repository (or your fork). After that, click the Issues tab (top navigation, between Pull Requests and Discussions). Finally, you should see a list of existing issues. The rhythm is simple: orient, act, verify, then continue.

      +

      Jamie: Before we leave Step 1: Navigate to the Accessibility Agents Issues Section, what is the practical point?

      +

      Alex: First, click the "New issue" button. Think of it as a rail line: each stop confirms you are still on the right route before the next one.

      +

      Jamie: Let's pause on Step 2: View the Template Chooser with Your Screen Reader. What should a learner take away from it?

      +

      Alex: Start with Step 2: View the Template Chooser with Your Screen Reader. There is something to understand, something to try, and something that proves the try worked.

      +

      Alex: The practical takeaway is this. 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. Template 1: [name] - [description]. Template 2: [name] - [description]. And so on. Is each template name announced clearly?

      +

      Alex: First, you should now see a Template Chooser page. Then, the page displays available templates as buttons or links. After that, with screen reader: Navigate through the templates. Finally, count the templates and read their descriptions aloud (or write them down). Think of it as a rail line: each stop confirms you are still on the right route before the next one.

      +

      Alex: A solid navigation habit is to prove where you are before activating controls. Headings, landmarks, and the address bar are not trivia; they are your map.

      +

      Jamie: Let's pause on Step 3: Select a Template. What should a learner take away from it?

      +

      Alex: Start with Step 3: Select a Template. There is something to understand, something to try, and something that proves the try worked.

      +

      Alex: The practical takeaway is this. The issue form opens. You see a form with labeled fields. Each field is pre-filled with helpful prompts or instructions. Choose "Blank Issue" or the most general template. You'll learn what an unstructured issue looks like (which teaches the value of templates).

      +

      Alex: First, 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). Then, click it (or press Enter if focused with keyboard). Treat it like a recipe: do not add the next ingredient until the previous one is actually in the bowl.

      -

      Jamie: Let's pause on What opens. What should a learner take away from it?

      -

      Alex: Start with What opens. There is something to understand, something to try, and something that proves the try worked.

      -

      Alex: The practical takeaway is this. 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).

      -

      Jamie: Let's pause on Panel structure from top to bottom. What should a learner take away from it?

      -

      Alex: Start with Panel structure from top to bottom. There is something to understand, something to try, and something that proves the try worked.

      -

      Alex: The practical takeaway is this. Branch name displayed (example: "main" or "feature/add-documentation"). View/More Actions button (three dots menu). Type your commit message here. Announced as "Source Control Input, edit, multi-line". Shortcut: Ctrl+Enter (Mac: Cmd+Enter) when focused in the message input. Lists all modified files not yet staged.

      -

      Alex: First, source Control title bar (heading level 2). Then, commit message input (multi-line text field). After that, commit button (or "Publish Branch" if this is a new branch). Finally, changes section (collapsible tree). It is like walking a hallway with named doors: read the sign, enter the right room, then confirm where you landed.

      -

      Jamie: Before we leave Panel structure from top to bottom, what is the practical point?

      -

      Alex: First, staged Changes section (collapsible tree). Then, merge Changes section (appears only during a merge). The rhythm is simple: orient, act, verify, then continue.

      -

      Jamie: Let's pause on NVDA/JAWS. What should a learner take away from it?

      -

      Alex: Start with NVDA/JAWS. There is something to understand, something to try, and something that proves the try worked.

      -

      Alex: The practical takeaway is this. 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).

      +

      Jamie: Let's pause on Step 4: Navigate the Form Fields. What should a learner take away from it?

      +

      Alex: Start with Step 4: Navigate the Form Fields. There is something to understand, something to try, and something that proves the try worked.

      +

      Alex: The practical takeaway is this. 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. 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"). Field: [name] - Required? [Yes/No].

      +

      Alex: First, the issue form is now open. Then, navigate through all visible fields using your screen reader or by tabbing. After that, for each field, note. Finally, write down at least 3 fields and whether each is required. It is a checklist, but a meaningful one: every item creates evidence that the next step is safe.

      +

      Jamie: Let's pause on Step 5: Fill In the Form. What should a learner take away from it?

      +

      Alex: Start with Step 5: Fill In the Form. There is something to understand, something to try, and something that proves the try worked.

      +

      Alex: The practical takeaway is this. Example: If the template asks "Screen Reader," select "NVDA". If it asks "Steps to reproduce," write 2-3 specific steps. 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).

      +

      Alex: First, fill in at least 3 fields with realistic content based on an issue you identified on Day 1. Then, for required fields marked with: Fill them in completely. After that, for optional fields: Choose at least one and fill it in (so you test optional fields). Finally, don't worry about filling in every field - the point is to test the form. It is like walking a hallway with named doors: read the sign, enter the right room, then confirm where you landed.

      +

      Jamie: Let's pause on Step 6: Preview the Issue Before Submitting. What should a learner take away from it?

      +

      Alex: Start with Step 6: Preview the Issue Before Submitting. There is something to understand, something to try, and something that proves the try worked.

      +

      Alex: The practical takeaway is this. 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. 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?

      +

      Alex: First, look for a Preview tab or button (usually near the top of the form, next to "Write" or "Markdown"). Then, click it (or press the hotkey shown). After that, a preview pane appears showing how the issue will look when published. The rhythm is simple: orient, act, verify, then continue.

      -

      Alex: Keep the teaching thread moving. Start with VoiceOver: Key point: The Source Control panel is not a standard file tree. The next useful detail is this: It's a specialized Git status view.

      -

      Alex: The practical takeaway is this. Navigate with VO+Arrow keys. VO+Space to activate (open diff or stage/unstage). The panel is announced as a "group" containing lists.

      -

      Jamie: Let's pause on What Each File Shows. What should a learner take away from it?

      -

      Alex: Here is the plain-English version of What Each File Shows. When a file appears in the Changes or Staged Changes list, VS Code shows a status letter. Put another way, screen reader announcement: "docs/GUIDE.md, Modified" or "README.md, Added".

      -

      Alex: Keep the teaching thread moving. This is where Context Menu Actions (Right-Click or Shift+F10) becomes real: when focused on any file in the Source Control panel. That matters in practice: Use Shift+F10 to open the context menu. The workshop is closer to rehearsal than lecture. You hear the move, try the move, and then check what changed.

      +

      Jamie: Let's pause on Step 7: Submit the Issue. What should a learner take away from it?

      +

      Alex: Start with Step 7: Submit the Issue. There is something to understand, something to try, and something that proves the try worked.

      +

      Alex: The practical takeaway is this. 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.

      +

      Alex: First, once you're satisfied with the preview, go back to the "Write" tab. Then, locate the green "New issue" button (usually at the bottom of the form). After that, with keyboard: Press Tab until the button is focused, then Enter. Finally, with mouse: Click the button. Think of it as a rail line: each stop confirms you are still on the right route before the next one.

      +

      Jamie: Before we leave Step 7: Submit the Issue, what is the practical point?

      +

      Alex: First, the issue is submitted and you see the new issue page with your content. Treat it like a recipe: do not add the next ingredient until the previous one is actually in the bowl.

      +

      Jamie: Let's pause on Step 8: Checkpoint - Reflect on the Template. What should a learner take away from it?

      +

      Alex: Here is the plain-English version of Step 8: Checkpoint - Reflect on the Template. You'll use them in Exercise D when you design your own template.

      +

      Alex: First, template Clarity: Did the template guide you toward providing useful information, or did fields feel confusing or unnecessary? Then, screen Reader Accessibility: Were all field labels announced clearly? Did you encounter any accessibility barriers? After that, required vs Optional: Was it obvious which fields were required? If you skipped an optional field, would you have known it was optional? Finally, context Helpfulness: Did the placeholder text or help text under each field make you understand what information to provide? Treat it like a recipe: do not add the next ingredient until the previous one is actually in the bowl.

      +

      Alex: Keep the teaching thread moving. This is where Exercise B - Add the Accessibility Bug Report Template to Your Fork becomes real: your Mission: Create your own instance of the accessibility bug report template in your personal fork. That matters in practice: This teaches you the file structure and gives you hands-on experience with YAML syntax. The workshop is closer to rehearsal than lecture. You hear the move, try the move, and then check what changed.

      +

      Alex: The practical takeaway is this. You have already read Section 7 thoroughly (Building an Accessibility Bug Report Template). You have a fork of accessibility-agents (created on Day 1). VS Code is installed on your machine. Git is installed and configure with your GitHub credentials.

      -

      Jamie: Let's pause on Learning Cards: Source Control Panel. What should a learner take away from it?

      -

      Alex: Keep the learner anchored in Learning Cards: Source Control Panel. Low vision users (zoom, high contrast). This is the part to say slowly: The Source Control panel adapts well to zoom and high contrast settings.

      -

      Alex: First, 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. Then, 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. After that, 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). Finally, 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. It is like walking a hallway with named doors: read the sign, enter the right room, then confirm where you landed.

      -

      Jamie: Before we leave Learning Cards: Source Control Panel, what is the practical point?

      -

      Alex: First, 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. The rhythm is simple: orient, act, verify, then continue.

      -

      Alex: Treat examples as spoken recipes, not decorations. You may hear something like 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. Read the command, understand what it changes, then run it only when the repository state matches the lesson.

      -

      Alex: Keep the teaching thread moving. The reason 3. Branch Management matters is that branches are how you organize work in Git. That gives the learner a simple foothold: every repository starts with a main or master branch.

      -

      Jamie: Let's pause on Where it's shown. What should a learner take away from it?

      -

      Alex: Start with Where it's shown. There is something to understand, something to try, and something that proves the try worked.

      -

      Alex: First, bottom-left corner of VS Code (status bar) - visual users see it immediately. Then, source Control panel title bar. After that, command Palette: Ctrl+Shift+P (Mac: Cmd+Shift+P) → "Git: Show Git Output". Think of it as a rail line: each stop confirms you are still on the right route before the next one.

      +

      Jamie: Let's pause on Step 1: Clone Your Fork to Your Machine. What should a learner take away from it?

      +

      Alex: Keep the learner anchored in Step 1: Clone Your Fork to Your Machine. (Or wherever you keep code projects). This is the part to say slowly: Replace [YOUR-USERNAME] with your actual GitHub username.

      +

      Alex: The practical takeaway is this. 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. "Repository not found" → Make sure your GitHub username is correct.

      +

      Alex: First, open a terminal (PowerShell on Windows, Terminal on macOS/Linux). Then, navigate to a folder where you want to store the project. After that, clone your fork. Finally, wait for the clone to complete (should take 10-30 seconds). It is like walking a hallway with named doors: read the sign, enter the right room, then confirm where you landed.

      +

      Jamie: Before we leave Step 1: Clone Your Fork to Your Machine, what is the practical point?

      +

      Alex: First, navigate into the folder. The rhythm is simple: orient, act, verify, then continue.

      +

      Alex: Treat examples as spoken recipes, not decorations. You may hear something like cd /projects. git clone https://github.com/[YOUR-USERNAME]/accessibility-agents.git. Read the command, understand what it changes, then run it only when the repository state matches the lesson.

      +

      Jamie: Let's pause on Step 2: Open Your Fork in VS Code. What should a learner take away from it?

      +

      Alex: Start with Step 2: Open Your Fork in VS Code. There is something to understand, something to try, and something that proves the try worked.

      +

      Alex: The practical takeaway is this. VS Code opens a new window. The left sidebar shows the folder structure of accessibility-agents. At the top, you see the folder name: accessibility-agents. Use VS Code's File menu: File → Open Folder → navigate to your accessibility-agents folder.

      +

      Alex: First, from the terminal, while in your accessibility-agents folder, type. Then, press Enter. After that, VS Code opens with your fork loaded. The rhythm is simple: orient, act, verify, then continue.

      +

      Jamie: Let's pause on Step 3: Navigate to the Templates Folder. What should a learner take away from it?

      +

      Alex: Start with Step 3: Navigate to the Templates Folder. There is something to understand, something to try, and something that proves the try worked.

      +

      Alex: The practical takeaway is this. 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. Right-click on the.github folder and select New Folder. Name it ISSUE TEMPLATE.

      +

      Alex: First, in VS Code's file tree (left sidebar), expand the.github folder. Then, inside, find and expand the ISSUE TEMPLATE folder. After that, you should see existing template files (like bug-report-template.yml or similar). Think of it as a rail line: each stop confirms you are still on the right route before the next one.

      -

      Alex: Keep the teaching thread moving. Here is the plain-English version of Keyboard access to status bar. Visual users: You can also click the branch name in the bottom-left status bar to open the branch picker directly. It is like learning a transit route. The names of the stops matter because they tell you whether you are still going the right direction.

      -

      Alex: The practical takeaway is this. The status bar is not in the standard keyboard navigation flow. Use the Command Palette for branch operations instead.

      -

      Jamie: Let's pause on Command Palette method (recommended). What should a learner take away from it?

      -

      Alex: Start with Command Palette method (recommended). There is something to understand, something to try, and something that proves the try worked.

      -

      Alex: The practical takeaway is this. Creates the branch. Switches to it automatically. Your working files stay exactly as they were.

      -

      Alex: First, ctrl+Shift+P (Mac: Cmd+Shift+P). Then, type "git create branch". After that, select "Git: Create Branch.". Finally, type the new branch name (example: feature/improve-docs). It is a checklist, but a meaningful one: every item creates evidence that the next step is safe.

      -

      Jamie: Before we leave Command Palette method (recommended), what is the practical point?

      -

      Alex: First, press Enter. It is like walking a hallway with named doors: read the sign, enter the right room, then confirm where you landed.

      -

      Jamie: Let's pause on Naming conventions. What should a learner take away from it?

      -

      Alex: Keep the learner anchored in Naming conventions. Web alternative (github.com) - branch management. This is the part to say slowly: Create and switch branches without leaving your browser.

      -

      Alex: The practical takeaway is this. Use lowercase with hyphens: feature/add-timeline-guide. Avoid spaces and special characters. Be descriptive: fix/heading-hierarchy not fix1.

      -

      Alex: First, on the repository page, click the branch dropdown (shows "main" by default). Then, type a new branch name in the search field. After that, click "Create branch: your-branch-name from main". Finally, GitHub switches to the new branch immediately. It is like walking a hallway with named doors: read the sign, enter the right room, then confirm where you landed.

      -

      Jamie: Before we leave Naming conventions, what is the practical point?

      -

      Alex: First, any file edits you make in the browser will be on this branch. The rhythm is simple: orient, act, verify, then continue.

      -

      Alex: Treat examples as spoken recipes, not decorations. You may hear something like 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. Read the command, understand what it changes, then run it only when the repository state matches the lesson.

      -
      -

      Jamie: Let's pause on Command Palette method. What should a learner take away from it?

      -

      Alex: The reason Command Palette method matters is that screen reader announcement: "Branch: main" or "Branch: feature/add-timeline-guide".

      -

      Alex: First, ctrl+Shift+P (Mac: Cmd+Shift+P). Then, type "git checkout". After that, select "Git: Checkout to.". Finally, a list of all branches appears. The rhythm is simple: orient, act, verify, then continue.

      -

      Jamie: Before we leave Command Palette method, what is the practical point?

      -

      Alex: First, up/Down Arrow to navigate. Then, enter to switch. Think of it as a rail line: each stop confirms you are still on the right route before the next one.

      -

      Alex: Keep the teaching thread moving. Start with What happens when you switch. There is something to understand, something to try, and something that proves the try worked.

      -

      Alex: The practical takeaway is this. 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).

      -

      Jamie: Let's pause on After your PR is merged, you can delete the branch. What should a learner take away from it?

      -

      Alex: Here is the plain-English version of After your PR is merged, you can delete the branch. You cannot delete the branch you're currently on.

      -

      Alex: First, ctrl+Shift+P (Mac: Cmd+Shift+P). Then, type "git delete branch". After that, select "Git: Delete Branch.". Finally, choose the branch to delete from the list. Treat it like a recipe: do not add the next ingredient until the previous one is actually in the bowl.

      +

      Jamie: Let's pause on Step 4: Create a New Template File. What should a learner take away from it?

      +

      Alex: Start with Step 4: Create a New Template File. There is something to understand, something to try, and something that proves the try worked.

      +

      Alex: The practical takeaway is this. A new, empty file opens in the editor. The cursor is ready for you to start typing.

      +

      Alex: First, right-click on the ISSUE TEMPLATE folder. Then, select New File. After that, name it: accessibility-bug.yml (exactly this name). Finally, press Enter. Treat it like a recipe: do not add the next ingredient until the previous one is actually in the bowl.

      +

      Jamie: Let's pause on Step 5: Copy the Accessibility Template YAML. What should a learner take away from it?

      +

      Alex: Start with Step 5: Copy the Accessibility Template YAML. There is something to understand, something to try, and something that proves the try worked.

      +

      Alex: The practical takeaway is this. 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).

      +

      Alex: First, go to Chapter 17, Section 7 in this curriculum. Then, find the complete YAML template code block (starting with name: and ending with the last field). After that, select all the YAML code (use Ctrl+A on the webpage or manually select). Finally, copy it (Ctrl+C). It is a checklist, but a meaningful one: every item creates evidence that the next step is safe.

      +

      Jamie: Before we leave Step 5: Copy the Accessibility Template YAML, what is the practical point?

      +

      Alex: First, go back to VS Code. Then, paste it into your new accessibility-bug.yml file (Ctrl+V). It is like walking a hallway with named doors: read the sign, enter the right room, then confirm where you landed.

      +

      Jamie: Let's pause on Step 6: Verify the YAML Syntax. What should a learner take away from it?

      +

      Alex: Start with Step 6: Verify the YAML Syntax. There is something to understand, something to try, and something that proves the try worked.

      +

      Alex: The practical takeaway is this. 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. Your YAML syntax is correct!

      +

      Alex: First, save the file (Ctrl+S). Then, look at the bottom right of VS Code - you may see some notifications. After that, check if VS Code shows any red squiggly lines (indicating syntax errors). Finally, hover over the error to see what VS Code suggests. It is like walking a hallway with named doors: read the sign, enter the right room, then confirm where you landed.

      +

      Jamie: Before we leave Step 6: Verify the YAML Syntax, what is the practical point?

      +

      Alex: First, compare your file with Section 7's template - look for extra/missing spaces or colons. Then, make corrections and save again. The rhythm is simple: orient, act, verify, then continue.

      -

      Jamie: Let's pause on Viewing All Branches. What should a learner take away from it?

      -

      Alex: This is where Viewing All Branches becomes real: command: Ctrl+Shift+P → "Git: Show Git Output" → Branch list appears. That matters in practice: Alternative: Use the integrated terminal.

      -

      Alex: Treat examples as spoken recipes, not decorations. You may hear something like git branch Local branches only; git branch -a All branches (including remote). Read the command, understand what it changes, then run it only when the repository state matches the lesson.

      -

      Jamie: Let's pause on Learning Cards: Branch Management. What should a learner take away from it?

      -

      Alex: Keep the learner anchored in Learning Cards: Branch Management. Low vision users (zoom, high contrast). This is the part to say slowly: Screen reader users (NVDA / JAWS on Windows).

      -

      Alex: First, 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. Then, 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. After that, 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. It is like walking a hallway with named doors: read the sign, enter the right room, then confirm where you landed.

      -

      Jamie: Let's pause on Creating a branch. What should a learner take away from it?

      -

      Alex: Start with Creating a branch. There is something to understand, something to try, and something that proves the try worked.

      -

      Alex: First, press Ctrl+Shift+P to open the Command Palette. Then, type "git create branch" - NVDA/JAWS announces results as you type. After that, press Enter on "Git: Create Branch.". Finally, the input focus moves to a text field - type your branch name (e.g., feature/add-docs). The rhythm is simple: orient, act, verify, then continue.

      -

      Jamie: Before we leave Creating a branch, what is the practical point?

      -

      Alex: First, press Enter - VS Code creates and switches to the branch. Then, NVDA/JAWS announces the new branch name in the status bar notification. Think of it as a rail line: each stop confirms you are still on the right route before the next one.

      +

      Jamie: Let's pause on Step 7: Create a Branch and Commit. What should a learner take away from it?

      +

      Alex: Start with Step 7: Create a Branch and Commit. There is something to understand, something to try, and something that proves the try worked.

      +

      Alex: The practical takeaway is this. Git uploads your branch to GitHub. You're ready to test the template in the next step. "Not a git repository" → Make sure you opened the accessibility-agents folder in VS Code. "Permission denied" → Make sure you authenticated with GitHub (see Prerequisites).

      +

      Alex: First, open the terminal in VS Code: Terminal → New Terminal (or Ctrl+ ` on Windows). Then, you should be in the accessibility-agents folder already. After that, create a new branch for this change. Finally, add the file to git. The rhythm is simple: orient, act, verify, then continue.

      +

      Jamie: Before we leave Step 7: Create a Branch and Commit, what is the practical point?

      +

      Alex: First, commit with a message. Then, push to your fork. Think of it as a rail line: each stop confirms you are still on the right route before the next one.

      +

      Alex: Treat examples as spoken recipes, not decorations. You may hear something like git checkout -b feat/add-accessibility-template. git add.github/ISSUE TEMPLATE/accessibility-bug.yml. Read the command, understand what it changes, then run it only when the repository state matches the lesson.

      +

      Alex: A solid Git habit is to know which branch you are on, what changed, and what confirmation you expect before you run the next command.

      +

      Jamie: Let's pause on Step 8: Test the Template in GitHub Web. What should a learner take away from it?

      +

      Alex: Start with Step 8: Test the Template in GitHub Web. There is something to understand, something to try, and something that proves the try worked.

      +

      Alex: The practical takeaway is this. 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. Go back to the main repository page (code tab). Refresh the browser (Ctrl+Shift+R for hard refresh).

      +

      Alex: First, open GitHub in your browser. Then, go to your fork: https://github.com/[YOUR-USERNAME]/accessibility-agents. After that, you should see a notification or purple bar saying "Compare & pull request" (your new branch). Finally, but instead of opening a PR, click the Issues tab. Think of it as a rail line: each stop confirms you are still on the right route before the next one.

      +

      Jamie: Before we leave Step 8: Test the Template in GitHub Web, what is the practical point?

      +

      Alex: First, click New issue. Then, you should now see your new template in the chooser: "Accessibility Bug Report". After that, click it to open the form. Treat it like a recipe: do not add the next ingredient until the previous one is actually in the bowl.

      +

      Jamie: Let's pause on Step 9: Test with Your Screen Reader. What should a learner take away from it?

      +

      Alex: Here is the plain-English version of Step 9: Test with Your Screen Reader. Record your findings - you'll use this for Exercise D.

      +

      Alex: The practical takeaway is this. Is the label announced clearly? Is it obvious whether the field is required? Do dropdowns announce their options correctly? Are descriptions/help text announced? Did you encounter any accessibility barriers? Would a screen reader user find this template easy to use?

      +

      Alex: First, with screen reader activated: Navigate through the template form using your reader's commands. Then, for each field, note. Treat it like a recipe: do not add the next ingredient until the previous one is actually in the bowl.

      -

      Jamie: Let's pause on Switching branches. What should a learner take away from it?

      -

      Alex: Start with Switching branches. There is something to understand, something to try, and something that proves the try worked.

      -

      Alex: First, press Ctrl+Shift+P, type "git checkout". Then, select "Git: Checkout to.". After that, a list of branches appears - navigate with Up/Down Arrow. Finally, each item is announced as the branch name (e.g., "main", "feature/add-docs"). Think of it as a rail line: each stop confirms you are still on the right route before the next one.

      -

      Jamie: Before we leave Switching branches, what is the practical point?

      -

      Alex: First, press Enter to switch. Then, VS Code reloads files for that branch - you hear a status bar update. Treat it like a recipe: do not add the next ingredient until the previous one is actually in the bowl.

      -

      Jamie: Let's pause on Deleting a branch. What should a learner take away from it?

      -

      Alex: Here is the plain-English version of Deleting a branch. Screen reader users (VoiceOver on macOS).

      -

      Alex: First, switch to a different branch first (you cannot delete the branch you are on). Then, press Ctrl+Shift+P, type "git delete branch". After that, select "Git: Delete Branch.". Finally, navigate the list to find the branch to delete, press Enter. Treat it like a recipe: do not add the next ingredient until the previous one is actually in the bowl.

      -

      Jamie: What is the teaching move inside Creating a branch?

      -

      Alex: First, press Cmd+Shift+P to open the Command Palette. Then, type "git create branch" - VoiceOver announces filtered results. After that, press Return on "Git: Create Branch.". Finally, type the branch name in the input field. It is a checklist, but a meaningful one: every item creates evidence that the next step is safe.

      -

      Jamie: If someone only remembers one thing from Creating a branch, what should it be?

      -

      Alex: First, press Return to create and switch. It is like walking a hallway with named doors: read the sign, enter the right room, then confirm where you landed.

      +

      Jamie: Let's pause on Step 10: Merge Your Branch (Optional). What should a learner take away from it?

      +

      Alex: Start with Step 10: Merge Your Branch (Optional). There is something to understand, something to try, and something that proves the try worked.

      +

      Alex: The practical takeaway is this. Go to your fork on GitHub. You should see a "Compare & pull request" button. Click it. It shows the template is finalized and tested. If you continue working on this fork, the template is ready for everyone who clones it.

      +

      Alex: First, open an PR for your branch. Then, add a title: feat: add accessibility bug report template. After that, add a description: This template guides contributors to report accessibility issues with clear fields for screen reader type, browser, and WCAG criteria. Finally, click Create pull request. It is a checklist, but a meaningful one: every item creates evidence that the next step is safe.

      +

      Jamie: Before we leave Step 10: Merge Your Branch (Optional), what is the practical point?

      +

      Alex: First, review your PR (using skills from Chapter 14!). Then, if satisfied, click Merge pull request to merge it into your fork's main branch. It is like walking a hallway with named doors: read the sign, enter the right room, then confirm where you landed.

      +

      Jamie: Let's pause on Checkpoint. What should a learner take away from it?

      +

      Alex: Keep the learner anchored in Checkpoint. After completing Steps 1-9, verify.

      +

      Alex: First, you created a file named accessibility-bug.yml in.github/ISSUE TEMPLATE/. Then, the file contains valid YAML (no red squiggles in VS Code). After that, the template is visible when you click "New issue" in your fork. Finally, you tested it with your screen reader and noted any issues. It is like walking a hallway with named doors: read the sign, enter the right room, then confirm where you landed.

      +

      Alex: Keep the teaching thread moving. The reason Exercise C - Submit It Upstream matters is that your Mission: Contribute your tested template to the upstream community-access/accessibility-agents repository. That gives the learner a simple foothold: this is a real open source contribution! The interface gets friendlier when it stops being a wall of controls and starts being a set of named places.

      +

      Alex: The practical takeaway is this. 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.

      -

      Jamie: What is the teaching move inside Switching branches?

      -

      Alex: First, press Cmd+Shift+P, type "git checkout". Then, select "Git: Checkout to.". After that, use VO+Down Arrow to navigate the branch list. Finally, press Return to switch. It is like walking a hallway with named doors: read the sign, enter the right room, then confirm where you landed.

      -

      Jamie: Let's pause on Getting the current branch name. What should a learner take away from it?

      -

      Alex: The reason Getting the current branch name matters is that create and switch branches without leaving your browser. That gives the learner a simple foothold: manage branches from your terminal.

      -

      Alex: First, press VO+M to move to the menu bar, then VO+Right Arrow to the status bar area. Then, or use the Command Palette: Cmd+Shift+P then type "Git: Show Git Output" - the output pane includes the current branch. After that, on the repository page, find the branch dropdown button (shows "main" by default) - it is above the file table. Finally, click or activate the dropdown. The rhythm is simple: orient, act, verify, then continue.

      -

      Jamie: Before we leave Getting the current branch name, what is the practical point?

      -

      Alex: First, type a new branch name in the search field. Then, click "Create branch: your-branch-name from main" when it appears. After that, GitHub switches to the new branch immediately. Finally, any file edits in the browser will be on this branch. Think of it as a rail line: each stop confirms you are still on the right route before the next one.

      -

      Alex: Treat examples as spoken recipes, not decorations. You may hear something like 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. 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'. Read the command, understand what it changes, then run it only when the repository state matches the lesson.

      -

      Jamie: Let's pause on 4. Staging Changes - Files, Lines, and Chunks. What should a learner take away from it?

      -

      Alex: Start with 4. Staging Changes - Files, Lines, and Chunks: This lets you commit only part of your work, leaving the rest for a later commit.

      -

      Alex: First, stage the changes you want to include. Then, commit those staged changes. Think of it as a rail line: each stop confirms you are still on the right route before the next one.

      +

      Jamie: Let's pause on Step 1: Verify Your Template is Ready. What should a learner take away from it?

      +

      Alex: Start with Step 1: Verify Your Template is Ready: Before submitting upstream, make sure your template is production-ready.

      +

      Alex: The practical takeaway is this. All fields display correctly. No broken formatting. Dropdowns work properly. Required fields are marked. The template is clean, no error messages. Every field is functional.

      +

      Alex: First, go to your fork on GitHub. Then, click Issues → New issue. After that, verify your template appears and is named "Accessibility Bug Report". Finally, open it and fill it out once more to confirm. Think of it as a rail line: each stop confirms you are still on the right route before the next one.

      +

      Jamie: Before we leave Step 1: Verify Your Template is Ready, what is the practical point?

      +

      Alex: First, don't submit this test issue - just close the tab. Treat it like a recipe: do not add the next ingredient until the previous one is actually in the bowl.

      +

      Jamie: Let's pause on Step 2: Create the Pull Request. What should a learner take away from it?

      +

      Alex: Start with Step 2: Create the Pull Request. There is something to understand, something to try, and something that proves the try worked.

      +

      Alex: The practical takeaway is this. Click the Code tab. Click the branches dropdown. Select your branch (feat/add-accessibility-template). Click "New pull request" to the right. Base: community-access/accessibility-agents / main (the upstream repo). Head: [your-username]/accessibility-agents / feat/add-accessibility-template (your fork/branch).

      +

      Alex: First, stay on your fork's GitHub page. Then, you should see a "Compare & pull request" button (or look for your feature branch). After that, if that button doesn't appear. Finally, a PR creation page opens showing. Treat it like a recipe: do not add the next ingredient until the previous one is actually in the bowl.

      +

      Jamie: Before we leave Step 2: Create the Pull Request, what is the practical point?

      +

      Alex: First, confirm this is correct - you're sending your branch to the upstream repository. It is a checklist, but a meaningful one: every item creates evidence that the next step is safe.

      +

      Jamie: What should happen before anyone copies and runs it?

      +

      Alex: This is where Step 3: Write Your PR Title and Description becomes real: write a clear description that explains what you're contributing.

      +

      Alex: Treat examples as spoken recipes, not decorations. You may hear something like 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. Read the command, understand what it changes, then run it only when the repository state matches the lesson.

      -

      Jamie: Let's pause on Staging an Entire File. What should a learner take away from it?

      -

      Alex: Here is the plain-English version of Staging an Entire File. Low vision users (zoom, high contrast). Put another way, screen reader users (NVDA / JAWS / VoiceOver).

      -

      Alex: The practical takeaway is this. 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.

      -

      Alex: First, open Source Control: Ctrl+Shift+G (Mac: Cmd+Shift+G). Then, hover over a file in the "Changes" list - a + icon appears to its right. After that, click the + to stage that file. Finally, or right-click a file → "Stage Changes". Treat it like a recipe: do not add the next ingredient until the previous one is actually in the bowl.

      -

      Jamie: Before we leave Staging an Entire File, what is the practical point?

      -

      Alex: First, at high zoom, the + (stage), undo (discard), and open file icons may be small. Instead of hovering. Then, 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. After that, in high contrast themes, staged files show a distinct background or border in the Staged Changes section. Finally, navigate to the file in the "Changes" list. It is a checklist, but a meaningful one: every item creates evidence that the next step is safe.

      -

      Alex: Keep the teaching thread moving. Start with Alternative (keyboard shortcut). There is something to understand, something to try, and something that proves the try worked.

      -

      Alex: The practical takeaway is this. Focus the file → press Space.

      -

      Jamie: Let's pause on Alternative (context menu). What should a learner take away from it?

      -

      Alex: Start with Alternative (context menu). There is something to understand, something to try, and something that proves the try worked.

      -

      Alex: The practical takeaway is this. Focus the file → press Shift+F10 (Mac: Ctrl+Return) → select "Stage Changes".

      +

      Jamie: Let's pause on What to do. What should a learner take away from it?

      +

      Alex: Start with What to do. There is something to understand, something to try, and something that proves the try worked.

      +

      Alex: The practical takeaway is this. 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?

      +

      Alex: First, copy the template above into the description field. Then, edit it with your actual testing experience. After that, keep it concise but thorough. It is like walking a hallway with named doors: read the sign, enter the right room, then confirm where you landed.

      +

      Jamie: Let's pause on Step 4: Review Your PR Before Submitting. What should a learner take away from it?

      +

      Alex: Start with Step 4: Review Your PR Before Submitting. There is something to understand, something to try, and something that proves the try worked.

      +

      Alex: The practical takeaway is this. Is the title clear about what you're adding? Does the description explain the value of this template? Are all checkmarks (``) and formatting visible?

      +

      Alex: First, scroll down and preview your PR description as it will appear. Then, using your screen reader, read through it. After that, make any corrections needed. Finally, do not submit yet - continue to Step 5. The rhythm is simple: orient, act, verify, then continue.

      +

      Jamie: Let's pause on Step 5: Submit the PR. What should a learner take away from it?

      +

      Alex: Start with Step 5: Submit the PR. There is something to understand, something to try, and something that proves the try worked.

      +

      Alex: The practical takeaway is this. 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. Your PR appears in the upstream repository's PR list. You see comments from maintainers (positive feedback = great sign!).

      +

      Alex: First, click the green "Create pull request" button. Then, your PR is now submitted to the upstream repository. After that, you see a confirmation page showing your new PR number (e.g., " 42"). Finally, GitHub may automatically assign reviewers or run CI checks. Think of it as a rail line: each stop confirms you are still on the right route before the next one.

      -

      Alex: Keep the teaching thread moving. Start with What happens. There is something to understand, something to try, and something that proves the try worked.

      -

      Alex: The practical takeaway is this. The file moves from "Changes" → "Staged Changes". A green "A" or "M" indicator appears.

      -

      Jamie: Let's pause on Staging Multiple Files at Once. What should a learner take away from it?

      -

      Alex: Start with Staging Multiple Files at Once: All modified files move to "Staged Changes.".

      -

      Alex: First, ctrl+Shift+G (Mac: Cmd+Shift+G) to open Source Control. Then, navigate to the "Changes" section heading. After that, press Shift+F10 (Mac: Ctrl+Return) to open context menu on the section itself. Finally, select "Stage All Changes". Think of it as a rail line: each stop confirms you are still on the right route before the next one.

      -

      Alex: Keep the teaching thread moving. Here is the plain-English version of 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. It is like learning a transit route. The names of the stops matter because they tell you whether you are still going the right direction.

      +

      Jamie: Let's pause on Step 6: Respond to Feedback. What should a learner take away from it?

      +

      Alex: Start with Step 6: Respond to Feedback. There is something to understand, something to try, and something that proves the try worked.

      +

      Alex: The practical takeaway is this. Go back to your fork in VS Code. Edit the accessibility-bug.yml file accordingly. Commit and push. Your changes automatically appear in the PR (linked to the branch). You can leave a polite comment: "Friendly ping - is there anything else needed from my end?".

      +

      Alex: First, read their feedback carefully using your screen reader. Then, understand what changes they're requesting (or what they're praising!). After that, if changes are needed. Finally, leave a reply comment on the PR. Treat it like a recipe: do not add the next ingredient until the previous one is actually in the bowl.

      +

      Jamie: Before we leave Step 6: Respond to Feedback, what is the practical point?

      +

      Alex: First, click Reply. It is a checklist, but a meaningful one: every item creates evidence that the next step is safe.

      +

      Alex: Treat examples as spoken recipes, not decorations. You may hear something like git add.github/ISSUE TEMPLATE/accessibility-bug.yml; git commit -m "Address feedback from maintainers: [brief description]"; git push origin feat/add-accessibility-template. Read the command, understand what it changes, then run it only when the repository state matches the lesson.

      +

      Jamie: Let's pause on Step 7: Celebrate Your Contribution. What should a learner take away from it?

      +

      Alex: This is where Step 7: Celebrate Your Contribution becomes real: -Write down: "I contributed [template name] to an open source project". The workshop is closer to rehearsal than lecture. You hear the move, try the move, and then check what changed.

      +

      Alex: The practical takeaway is this. Take a screenshot of your merged PR. This is valuable experience for your resume and for learning how open source collaboration works.

      +

      Alex: First, you'll see the PR status change to "Merged". Then, your template is now part of the community-access/accessibility-agents repository. After that, everyone who forks that repo will get your template. Finally, you can claim this as a real open source contribution. It is a checklist, but a meaningful one: every item creates evidence that the next step is safe.

      +

      Jamie: Before we leave Checkpoint, what is the practical point?

      +

      Alex: Keep the learner anchored in Checkpoint. After completing Steps 1-7, verify.

      +

      Alex: The practical takeaway is this. 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?

      +

      Alex: First, you created a PR to the upstream repository. Then, your PR includes a clear description of what you're contributing. After that, your template is the only change in the PR (one file). Finally, you addressed any feedback from maintainers. It is like walking a hallway with named doors: read the sign, enter the right room, then confirm where you landed.

      +

      Jamie: What is the teaching move inside Checkpoint?

      +

      Alex: First, your PR was merged (or is waiting for merge). The rhythm is simple: orient, act, verify, then continue.

      -

      Jamie: Let's pause on Workflow. What should a learner take away from it?

      -

      Alex: This is where Workflow becomes real: result: Only those lines are staged. That matters in practice: The rest of the file remains in "Changes.".

      -

      Alex: First, open Source Control: Ctrl+Shift+G (Mac: Cmd+Shift+G). Then, navigate to a file in "Changes". After that, press Enter to open the diff view. Finally, the diff shows your changes side-by-side or inline. It is a checklist, but a meaningful one: every item creates evidence that the next step is safe.

      -

      Jamie: Before we leave Workflow, what is the practical point?

      -

      Alex: First, navigate to a changed line (use Arrow keys or F7 for next hunk). Then, press Shift+F10 (Mac: Ctrl+Return) to open context menu. After that, select "Stage Selected Lines". It is like walking a hallway with named doors: read the sign, enter the right room, then confirm where you landed.

      -

      Jamie: Let's pause on Use case for this workshop. What should a learner take away from it?

      -

      Alex: Keep the learner anchored in Use case for this workshop. In the diff view, press Alt+H to see Accessible Help for diff-specific keyboard shortcuts. This is the part to say slowly: Web alternative (github.com) - editing files.

      -

      Alex: The practical takeaway is this. 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".

      -

      Alex: First, click the pencil icon on any file to open the web editor. Then, make your changes. After that, click "Commit changes" - GitHub creates the commit directly. Finally, choose to commit to the current branch or create a new branch and PR. It is like walking a hallway with named doors: read the sign, enter the right room, then confirm where you landed.

      -

      Alex: Treat examples as spoken recipes, not decorations. You may hear something like 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. Read the command, understand what it changes, then run it only when the repository state matches the lesson.

      -

      Jamie: Let's pause on Reverse the process. What should a learner take away from it?

      -

      Alex: Start with Reverse the process. There is something to understand, something to try, and something that proves the try worked.

      -

      Alex: First, focus the file in "Staged Changes". Then, press Ctrl+Enter (Mac: Cmd+Enter) or Space. After that, file moves back to "Changes". The rhythm is simple: orient, act, verify, then continue.

      +

      Alex: Keep the teaching thread moving. The reason Exercise D - Design a Template for Your Own Project matters is that your Mission: Apply everything you've learned to design a template for a repository you own, maintain, or plan to create. That gives the learner a simple foothold: what You'll Learn: How to make design decisions about required vs.

      +

      Jamie: Let's pause on Part 1: Choose Your Project. What should a learner take away from it?

      +

      Alex: Start with Choose Your Project. There is something to understand, something to try, and something that proves the try worked.

      +

      Alex: The practical takeaway is this. 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. You have a specific project in mind (not generic). You can articulate why you care about it.

      +

      Alex: First, think of a repository you have a personal connection to. Then, write down the project name and briefly why chose it. Think of it as a rail line: each stop confirms you are still on the right route before the next one.

      +

      Jamie: Let's pause on Part 2: Identify Issue Patterns. What should a learner take away from it?

      +

      Alex: Here is the plain-English version of Identify Issue Patterns. Your task: Study the issues your project receives (or would receive) to understand what information is most valuable. Put another way, if your project doesn't exist yet or has no issues. It is like learning a transit route. The names of the stops matter because they tell you whether you are still going the right direction.

      +

      Alex: The practical takeaway is this. 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? Bug reports?

      +

      Alex: First, open your issue list in GitHub. Then, read the last 5-10 issues (or all open issues if fewer). After that, for each issue, ask yourself. Finally, write down 3-5 patterns. Treat it like a recipe: do not add the next ingredient until the previous one is actually in the bowl.

      +

      Jamie: Before we leave Part 2: Identify Issue Patterns, what is the practical point?

      +

      Alex: First, think about the type of issues you'd want to receive. Then, for each type, ask: "If someone reported this issue, what would I need to know?". After that, write down. It is a checklist, but a meaningful one: every item creates evidence that the next step is safe.

      -

      Alex: Keep the teaching thread moving. Start with Learning Cards: Staging Changes. There is something to understand, something to try, and something that proves the try worked.

      -

      Alex: The practical takeaway is this. 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. 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.

      -

      Jamie: Let's pause on Standard process. What should a learner take away from it?

      -

      Alex: Start with Standard process. There is something to understand, something to try, and something that proves the try worked.

      -

      Alex: First, open Source Control: Ctrl+Shift+G (Mac: Cmd+Shift+G). Then, stage changes (see Section 4). After that, focus the commit message input (usually Tab or Shift+Tab to reach it). Finally, type your commit message. Treat it like a recipe: do not add the next ingredient until the previous one is actually in the bowl.

      -

      Jamie: Before we leave Standard process, what is the practical point?

      -

      Alex: First, press Ctrl+Enter (Mac: Cmd+Enter) to commit. It is a checklist, but a meaningful one: every item creates evidence that the next step is safe.

      -

      Jamie: Let's pause on Learning Cards: Committing. What should a learner take away from it?

      -

      Alex: This is where Learning Cards: Committing becomes real: low vision users (zoom, high contrast).

      -

      Alex: First, open Source Control (Ctrl+Shift+G). Then, stage your files (click the + icon next to each file, or click Stage All Changes above the Changes section header). After that, click in the "Message" text area at the top of the Source Control panel. Finally, type your commit message. It is a checklist, but a meaningful one: every item creates evidence that the next step is safe.

      -

      Jamie: Before we leave Learning Cards: Committing, what is the practical point?

      -

      Alex: First, click the Commit button (checkmark icon) or press Ctrl+Enter. Then, 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. After that, 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. Finally, 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. It is like walking a hallway with named doors: read the sign, enter the right room, then confirm where you landed.

      +

      Jamie: Let's pause on Part 3: Design Your Required Fields. What should a learner take away from it?

      +

      Alex: This is where Design Your Required Fields becomes real: your task: List the fields you absolutely need to understand an issue. That matters in practice: Rule: Keep required fields minimal.

      +

      Alex: The practical takeaway is this. You have 2-4 required fields. Each has a clear reason (not arbitrary). You can explain to someone why each field is required.

      +

      Alex: First, create a table. Then, for each issue type from Part 2, add 2-4 required fields. After that, write down at least 2 required fields. It is a checklist, but a meaningful one: every item creates evidence that the next step is safe.

      +

      Jamie: Let's pause on Part 4: Design Your Optional Fields. What should a learner take away from it?

      +

      Alex: Keep the learner anchored in Design Your Optional Fields. Your task: Add optional fields that would be helpful but aren't blocking.

      +

      Alex: The practical takeaway is this. Information that's helpful but you could triage without it. Information that helps you prioritize or assign the issue. Information that provides missing context. Environment details (CPU, RAM, versions of dependencies). Screenshots or links. Workarounds the reporter has found.

      +

      Alex: First, brainstorm nice-to-have information. Then, example optional fields for a bug report. After that, write down at least 2 optional fields. Finally, for each field, decide. It is like walking a hallway with named doors: read the sign, enter the right room, then confirm where you landed.

      +

      Jamie: Let's pause on Part 5: Write Field Placeholders and Help Text. What should a learner take away from it?

      +

      Alex: The reason Write Field Placeholders and Help Text matters is that your task: For each field, write helpful placeholder or description text that guides the reporter. That gives the learner a simple foothold: for each required and optional field, draft.

      +

      Alex: The practical takeaway is this. 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.

      +

      Alex: First, field label (the visible name). Then, description (short help text). After that, placeholder (example of what to type, for input/textarea fields). The rhythm is simple: orient, act, verify, then continue.

      -

      Jamie: Before we leave NVDA/JAWS, what is the practical point?

      -

      Alex: The practical takeaway is this. 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).

      -

      Alex: Keep the teaching thread moving. Start with VoiceOver. There is something to understand, something to try, and something that proves the try worked.

      -

      Alex: The practical takeaway is this. 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.

      -

      Jamie: Let's pause on Writing Good Commit Messages. What should a learner take away from it?

      -

      Alex: Start with Writing Good Commit Messages: See Culture & Etiquette: Writing Good Commit Messages for format guidance.

      +

      Jamie: Let's pause on Part 6: Test Your Template Locally. What should a learner take away from it?

      +

      Alex: Start with Test Your Template Locally: Your task: Create a draft YAML template file and test it with your screen reader. Think of it like entering a new building: first you find the lobby, then the room, then the door you actually need.

      +

      Alex: The practical takeaway is this. Start with the frontmatter (name:, description:, title:, labels:). Add your fields in the body: section. Use appropriate field types (input, textarea, dropdown, checkboxes). Name it: [your-project-name]-template.yml. Save it to your desktop or a projects folder. Is the YAML syntax correct? (no red squiggles).

      +

      Alex: First, create a text file with your template in YAML format. Use Section 6 as a template. Then, save it locally (not yet in GitHub). After that, open it in VS Code and check. Finally, test the structure. Think of it as a rail line: each stop confirms you are still on the right route before the next one.

      +

      Jamie: Before we leave Part 6: Test Your Template Locally, what is the practical point?

      +

      Alex: First, with your screen reader. Treat it like a recipe: do not add the next ingredient until the previous one is actually in the bowl.

      +

      Jamie: Let's pause on Part 7: (Optional) Deploy to GitHub and Test with a Friend. What should a learner take away from it?

      +

      Alex: Here is the plain-English version of (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. Put another way, this is optional but powerful - real user testing is the best validation.

      +

      Alex: The practical takeaway is this. Create a test branch in a personal repo. Add your template file to.github/ISSUE TEMPLATE/. Push the branch. "Could you try filing an issue using this template?".

      +

      Alex: First, upload your template to a test repository. Then, ask a colleague or friend. After that, collect feedback. Finally, refine your template based on their feedback. Treat it like a recipe: do not add the next ingredient until the previous one is actually in the bowl.

      +

      Jamie: Let's pause on Part 8: Reflect on Your Template Design. What should a learner take away from it?

      +

      Alex: This is where Reflect on Your Template Design becomes real: your task: Document what you learned from this exercise.

      +

      Alex: The practical takeaway is this. 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.

      +

      Alex: First, decision-making: Which field did you debate including? Why did you finally decide yes or no? Then, trade-offs: You can't ask for everything without overwhelming reporters. What information did you choose not to ask for? Why? After that, iteration: If you had user feedback (from Part 7), what did you learn? Finally, real-world readiness: Would you actually deploy this template to a real project? It is a checklist, but a meaningful one: every item creates evidence that the next step is safe.

      -

      Jamie: Let's pause on Format. What should a learner take away from it?

      -

      Alex: Here is the plain-English version of Format. Common types: feat:, fix:, docs:, style:, refactor:, test:, chore.

      -

      Alex: The practical takeaway is this. First line: type + colon + short summary (50 characters max). Blank line. Optional body: detailed explanation. Optional footer: "Fixes 123" to link to issue.

      -

      Alex: Treat examples as spoken recipes, not decorations. You may hear something like 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. Read the command, understand what it changes, then run it only when the repository state matches the lesson.

      -

      Jamie: Let's pause on What Happens After Commit. What should a learner take away from it?

      -

      Alex: Start with What Happens After Commit. There is something to understand, something to try, and something that proves the try worked.

      -

      Alex: The practical takeaway is this. 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).

      -

      Alex: Keep the teaching thread moving. Keep the learner anchored in 6. Push and Pull Operations. Push sends your local commits to GitHub. This is the part to say slowly: Pull downloads new commits from GitHub to your local repository. A good GitHub workflow is like a well-run meeting: everyone knows the topic, the next action, and who has the floor.

      +

      Jamie: If someone only remembers one thing from Checkpoint, what should it be?

      +

      Alex: Keep the learner anchored in Checkpoint. After completing Parts 1-8, you have. This is the part to say slowly: You now understand the thinking that separates "a blank text box" from "structured, actionable contributions.".

      +

      Alex: The practical takeaway is this. Chosen a specific project to design. Identified issue patterns and common questions. Designed required fields (minimal, crucial information). Designed optional fields (helpful but not blocking).

      +

      Jamie: Let's pause on You've Completed the Template Exercises. What should a learner take away from it?

      +

      Alex: The reason You've Completed the Template Exercises matters is that 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. That gives the learner a simple foothold: the agent generates YAML; you decide what questions to ask. The interface gets friendlier when it stops being a wall of controls and starts being a set of named places.

      +

      Alex: First, understand templates from the user perspective (Exercise A). Then, can create and deploy templates yourself (Exercise B). After that, know how to contribute upstream (Exercise C). Finally, can design templates with real thinking behind them (Exercise D). The rhythm is simple: orient, act, verify, then continue.

      +

      Jamie: How should they picture the shape of the workshop?

      +

      Alex: Start with 10. Day 2 Amplifier: The Template Builder Agent: Everything you just learned - field types, YAML structure, accessibility testing - is core GitHub knowledge. The next useful detail is this: Now see how Accessibility Agents amplifies it.

      -

      Jamie: Let's pause on After committing locally. What should a learner take away from it?

      -

      Alex: Start with After committing locally. There is something to understand, something to try, and something that proves the try worked.

      -

      Alex: First, open Source Control: Ctrl+Shift+G (Mac: Cmd+Shift+G). Then, look for the "Publish Branch" button (if this is a new branch) or "Sync Changes" button. After that, press Enter on that button. The rhythm is simple: orient, act, verify, then continue.

      -

      Jamie: Let's pause on Alternative: Command Palette. What should a learner take away from it?

      -

      Alex: Start with Alternative: Command Palette. There is something to understand, something to try, and something that proves the try worked.

      -

      Alex: First, ctrl+Shift+P (Mac: Cmd+Shift+P). Then, type "git push". After that, select "Git: Push". Finally, VS Code pushes your commits to GitHub. Think of it as a rail line: each stop confirms you are still on the right route before the next one.

      -

      Jamie: Let's pause on Learning Cards: Push and Pull. What should a learner take away from it?

      -

      Alex: Here is the plain-English version of Learning Cards: Push and Pull. Low vision users (zoom, high contrast). Put another way, screen reader users (NVDA / JAWS on Windows).

      -

      Alex: First, 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. Then, 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. After that, 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. Finally, 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. Treat it like a recipe: do not add the next ingredient until the previous one is actually in the bowl.

      +

      Alex: Keep the teaching thread moving. Here is the plain-English version of In VS Code. Then you copy, paste to.github/ISSUE TEMPLATE/your-template.yml, commit, and done.

      +

      Jamie: Let's pause on Why It Matters. What should a learner take away from it?

      +

      Alex: This is where Why It Matters becomes real: the Template Builder does not teach you to design templates - Section 5 taught you that. That matters in practice: It automates the mechanical part: translating your decisions into working YAML.

      +

      Alex: Keep the teaching thread moving. Keep the learner anchored in Using the Template Builder. Next: Chapter 18: Fork and Contribute Back: Chapter 16: GitHub Copilot Related appendices: Appendix Q: GitHub Actions Appendix C: Markdown Reference. A good GitHub workflow is like a well-run meeting: everyone knows the topic, the next action, and who has the floor.

      -

      Jamie: Let's pause on Pushing. What should a learner take away from it?

      -

      Alex: Start with Pushing. There is something to understand, something to try, and something that proves the try worked.

      -

      Alex: First, after committing, press Ctrl+Shift+P, type "git push", select "Git: Push". Then, NVDA/JAWS announces "Pushing." in the status bar. After that, on success, a notification appears: "Successfully pushed" - if using NVDA, check NVDA+N to read recent notifications. Finally, for a new branch (first push), use "Git: Publish Branch" instead - this sets up the upstream tracking. It is a checklist, but a meaningful one: every item creates evidence that the next step is safe.

      -

      Jamie: Let's pause on Pulling. What should a learner take away from it?

      -

      Alex: Start with Pulling. There is something to understand, something to try, and something that proves the try worked.

      -

      Alex: First, press Ctrl+Shift+P, type "git pull", select "Git: Pull". Then, NVDA/JAWS announces "Pulling." then the status changes. After that, if there are conflicts, the Source Control panel shows a "Merge Changes" section - navigate there with Ctrl+Shift+G then Down Arrow. It is like walking a hallway with named doors: read the sign, enter the right room, then confirm where you landed.

      -

      Jamie: Let's pause on Checking sync status. What should a learner take away from it?

      -

      Alex: The reason Checking sync status matters is that screen reader users (VoiceOver on macOS).

      -

      Alex: First, press Ctrl+Shift+P, type "Git: Show Git Output". Then, the output pane opens with push/pull log messages in plain text. After that, use Up/Down Arrow to read line by line. The rhythm is simple: orient, act, verify, then continue.

      +

      Jamie: What is the final checkpoint?

      +

      Alex: You should be able to point to the evidence, explain the action, and describe what you would do next if this were a real open source project. If you can teach the move back, you have learned it.

      +

      Jamie: And if they get stuck?

      +

      Alex: Read the latest message, not the loudest worry. Check the issue, the branch, the pull request, the status check, or the bot comment. Then ask for help with those facts in hand. That is how professionals collaborate.

      +
      +
      -

      Jamie: Before we leave Pushing, what is the practical point?

      -

      Alex: First, press Cmd+Shift+P, type "git push", select "Git: Push". Then, VoiceOver announces progress from the status bar. After that, on success, a notification toast appears - press VO+F3 to read the latest notification. Think of it as a rail line: each stop confirms you are still on the right route before the next one.

      -

      Jamie: Before we leave Pulling, what is the practical point?

      -

      Alex: First, press Cmd+Shift+P, type "git pull", select "Git: Pull". Then, VoiceOver announces when the pull completes. After that, if conflicts exist, navigate to Source Control (Cmd+Shift+G) and review the Merge Changes section. Treat it like a recipe: do not add the next ingredient until the previous one is actually in the bowl.

      -

      Jamie: Let's pause on Screen reader feedback. What should a learner take away from it?

      -

      Alex: This is where Screen reader feedback becomes real: Git CLI alternative - push and pull. That matters in practice: Web alternative (github.com) - push and pull.

      -

      Alex: The practical takeaway is this. 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).

      -

      Alex: Treat examples as spoken recipes, not decorations. You may hear something like 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. Read the command, understand what it changes, then run it only when the repository state matches the lesson.

      +

      47. Episode 17: Accessibility Agents

      +

      55 agents across 3 teams and 5 platforms, 54+ slash commands, custom agents, and agentic accessibility workflows.

      +

      Based on: Chapter 19: Accessibility Agents

      +

      Audio and transcript are being regenerated for this episode.

      +
      +Read Transcript - Episode 17: Accessibility Agents + +

      Transcript

      +

      Alex: Welcome back to Git Going with GitHub. This is episode 17: Accessibility Agents. I am Alex, and today we are turning Accessibility Agents from a list of instructions into a working mental model.

      +

      Jamie: And I am Jamie. I will stop us whenever the instructions sound simple on paper but might feel different with a keyboard and screen reader.

      -

      Alex: Keep the teaching thread moving. Start with What to do if push fails. There is something to understand, something to try, and something that proves the try worked.

      -

      Alex: The practical takeaway is this. 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). Error: "Rejected - non-fast-forward" → Someone else pushed changes; you need to pull first.

      -

      Jamie: Let's pause on When to pull. What should a learner take away from it?

      -

      Alex: Start with When to pull. There is something to understand, something to try, and something that proves the try worked.

      -

      Alex: The practical takeaway is this. Before you start work each day. When GitHub shows your branch is behind the remote. When preparing to merge a PR.

      -

      Jamie: Let's pause on How to pull. What should a learner take away from it?

      -

      Alex: Start with How to pull: If there are conflicts: See Section 9. Think of it like entering a new building: first you find the lobby, then the room, then the door you actually need.

      -

      Alex: First, ctrl+Shift+P (Mac: Cmd+Shift+P). Then, type "git pull". After that, select "Git: Pull". Finally, VS Code fetches and merges remote changes. Think of it as a rail line: each stop confirms you are still on the right route before the next one.

      +

      Alex: 55 agents across 3 teams and 5 platforms, 54+ slash commands, custom agents, and agentic accessibility workflows. That is the surface description. Underneath it, we are building judgment: where to focus, what to ignore, and how to verify the result.

      +

      Jamie: So we are not using the audio as a shortcut around learning. We are using it to make the learning easier to enter.

      +

      Alex: Yes. A good audio lesson gives someone enough context to try the work with confidence, even before they open the written material.

      -

      Jamie: Let's pause on Auto-fetch setting. What should a learner take away from it?

      -

      Alex: Start with Auto-fetch setting. There is something to understand, something to try, and something that proves the try worked.

      -

      Alex: The practical takeaway is this. VS Code can check for remote changes automatically every few minutes. Enable: Settings (Ctrl+, - Mac: Cmd+,) → search "git autofetch" → set to true.

      -

      Alex: Keep the teaching thread moving. This is where Syncing Your Fork with the Upstream Repository becomes real: when you fork a repository and the original (upstream) repository receives new commits, your fork gets out of date. That matters in practice: Keeping your fork current prevents merge conflicts and ensures you're working with the latest code.

      -

      Jamie: Let's pause on The GitHub "Sync fork" Button (Quickest Method). What should a learner take away from it?

      -

      Alex: Keep the learner anchored in The GitHub "Sync fork" Button (Quickest Method). For straightforward updates, GitHub has a built-in sync button.

      -

      Alex: First, navigate to your fork on GitHub. Then, on the repository page, look for the "This branch is N commits behind owner/repo:main" notice. After that, activate the "Sync fork" button next to it. Finally, GitHub automatically merges upstream changes into your fork's default branch. It is like walking a hallway with named doors: read the sign, enter the right room, then confirm where you landed.

      -

      Jamie: Before we leave The GitHub "Sync fork" Button (Quickest Method), what is the practical point?

      -

      Alex: First, then pull those changes to your local clone: Git: Pull from the Command Palette. The rhythm is simple: orient, act, verify, then continue.

      +

      Jamie: Okay, set the room for us. What are we walking into?

      +

      Alex: Start with 55 AI Agents Across 3 Teams and 5 Platforms: Day 2, Block 3 Material Before you read this guide: Accessibility Agents is a growing open source ecosystem: 55 AI-powered agents organized into three teams (Accessibility, GitHub Workflow, and Developer Tools), running on five platforms (GitHub Copilot,. The next useful detail is this: This chapter introduces the full landscape.

      +

      Alex: The next layer is this. Start with Core Prerequisites (Required for All Agents). There is something to understand, something to try, and something that proves the try worked.

      +

      Alex: The practical anchors are these. [ ] Chapter 0: Pre-Workshop Setup - Git, VS Code, and GitHub account. [ ] Chapter 16: GitHub Copilot - GitHub Copilot Chat installed and working. [ ] GitHub Copilot access (Copilot Free tier is enough for this workshop). [ ].github/agents/ folder exists in your repository (or will create custom agents).

      +

      Alex: A solid pull request habit is to separate three questions: what changed, why it changed, and what still needs review. That keeps the conversation useful instead of noisy.

      +

      Jamie: What is the one idea that makes the next few steps less mysterious?

      +

      Alex: This is where Agent Prerequisites (The "Skill First" Principle) becomes real: every agent automates a skill you should already know by hand. That matters in practice: Before using any agent, verify you have done the corresponding manual work.

      -

      Alex: Keep the teaching thread moving. The reason Screen reader path matters is that limitation: The GitHub sync button only syncs the default branch. That gives the learner a simple foothold: for other branches, use the git method below. The interface gets friendlier when it stops being a wall of controls and starts being a set of named places.

      -

      Jamie: Let's pause on Adding the Upstream Remote (One-Time Setup). What should a learner take away from it?

      -

      Alex: Start with Adding the Upstream Remote (One-Time Setup): To sync locally using git, you first configure the upstream remote. The next useful detail is this: This only needs to be done once per clone.

      -

      Alex: Treat examples as spoken recipes, not decorations. You may hear something like 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. Read the command, understand what it changes, then run it only when the repository state matches the lesson.

      -

      Jamie: Let's pause on Example for Accessibility Agents. What should a learner take away from it?

      -

      Alex: Start with Example for Accessibility Agents. There is something to understand, something to try, and something that proves the try worked.

      -

      Alex: Treat examples as spoken recipes, not decorations. You may hear something like git remote add upstream https://github.com/community-access/accessibility-agents.git. Read the command, understand what it changes, then run it only when the repository state matches the lesson.

      +

      Alex: Now bring the learner back to the room. Keep the learner anchored in Workshop Recommendation (Chapter 19 / Challenge 15). Chapter 19 is the agent exploration and hands-on validation chapter - where students match agents to skills they already have and learn how to trust, evaluate, and improve AI-powered workflow automation. This is the part to say slowly: It supports Challenge 15: Meet the Agents.

      +

      Alex: For a learner, the useful signals are these. There are 3 guided + 1-2 optional contribution challenges. Automation check: none (agent output requires human judgment before use). The evidence is issue comment showing agent output and your evaluation of it. The pattern is explore, validate, read internals, optionally contribute.

      +

      Jamie: What is the ordered workflow?

      +

      Alex: Start with Challenge 15 Set. There is something to understand, something to try, and something that proves the try worked.

      +

      Alex: First, agent Discovery Mapping - identify 3-5 agents that match skills you already have from Day 1. Then, agent Skill Validation - run one agent and evaluate its output against your manual experience. After that, agent Instructions Deep Dive - read one agent's source file and assess what it can and cannot do. Finally, improve an Existing Agent (optional hackathon) - find a gap in an agent's instructions and fix it via PR. The rhythm is simple: orient, act, verify, then continue.

      +

      Jamie: Give me the sequence, because order matters here.

      +

      Alex: First, propose a New Agent (optional hackathon) - file an issue proposing an agent for an uncovered workflow. Think of it as a rail line: each stop confirms you are still on the right route before the next one.

      +

      Alex: The useful habit is simple: orient first, act second, verify third. That pause before acting is part of the work.

      +

      Jamie: How would you walk the room through that step by step?

      +

      Alex: Start with Challenge 15.1 Step-by-Step: Agent Discovery Mapping: Map your Day 1 manual skills to specific agents in the ecosystem so you know which agents you are ready to use. The next useful detail is this: GitHub.com - the accessibility-agents repository and your assigned Challenge 15 issue. Think of it like entering a new building: first you find the lobby, then the room, then the door you actually need.

      +

      Alex: On the ground, that means a few things. @daily-briefing (maps to repository and issue awareness from Chapters 2-4). @issue-tracker (maps to Chapter 4 issue workflow). @pr-review (maps to Chapter 6 and Chapter 14 review workflow). Example: You filed issues manually (Ch 4) - you can use @issue-tracker.

      +

      Alex: First, fork the accessibility-agents repository on GitHub.com. Then, open the repository and navigate to Section 3 of the README (or this chapter's Section 3 below) to see the full list of 55 agents organized by team. After that, read through the agent names and descriptions. For each one, ask yourself: "Have I done this task manually during the workshop?". Finally, identify 3-5 agents that match workflows you already practiced. Think of it as a rail line: each stop confirms you are still on the right route before the next one.

      +

      Jamie: What does the learner do first, second, and then after that?

      +

      Alex: First, open your assigned Challenge 15 issue. Then, post a discovery mapping comment using this format. Treat it like a recipe: do not add the next ingredient until the previous one is actually in the bowl.

      -

      Jamie: Let's pause on Fetching and Merging Upstream Changes. What should a learner take away from it?

      -

      Alex: This is where Fetching and Merging Upstream Changes becomes real: once your upstream remote is configured.

      -

      Alex: Treat examples as spoken recipes, not decorations. You may hear something like 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. Read the command, understand what it changes, then run it only when the repository state matches the lesson.

      -

      Alex: Keep the teaching thread moving. Keep the learner anchored in When Conflicts Occur During Sync. See also: Chapter 07: Merge Conflicts for a dedicated walkthrough of conflict resolution. This is the part to say slowly: If you've made changes to the same files the upstream has changed, merge conflicts can occur during sync. A good GitHub workflow is like a well-run meeting: everyone knows the topic, the next action, and who has the floor.

      -

      Jamie: Let's pause on 7. Discarding Changes. What should a learner take away from it?

      -

      Alex: The reason 7. Discarding Changes matters is that discarding = permanently deleting your local edits. That gives the learner a simple foothold: the file reverts to the state of the last commit.

      +

      Jamie: Turn that into a path someone can follow.

      +

      Alex: Here is the plain-English version of Challenge 15.2 Step-by-Step: Agent Skill Validation. Run one agent, read its output, and evaluate whether it matches your manual experience. Put another way, VS Code with the accessibility-agents repository cloned and Copilot Chat open.

      +

      Alex: Here is what that changes in practice. @daily-briefing morning briefing. @issue-tracker find open issues labeled good-first-issue in accessibility-agents. @pr-review show open PRs in accessibility-agents.

      +

      Alex: First, clone your fork of accessibility-agents to VS Code (or open it in github.dev). Then, open Copilot Chat: Ctrl+Shift+I (Mac: Cmd+Shift+I). After that, choose one agent from your discovery list. If unsure, start with @daily-briefing or @issue-tracker. Finally, run it with a simple prompt. Treat it like a recipe: do not add the next ingredient until the previous one is actually in the bowl.

      +

      Jamie: Let's pause on Challenge 15.2 Step-by-Step: Agent Skill Validation. What should a learner take away from it?

      +

      Alex: First, read the agent's output carefully. Take a moment to think about what you expected. Then, open your assigned Challenge 15 issue and post an evaluation comment. It is a checklist, but a meaningful one: every item creates evidence that the next step is safe.

      +

      Jamie: Let's pause on Challenge 15.3 Step-by-Step: Agent Instructions Deep Dive. What should a learner take away from it?

      +

      Alex: This is where Challenge 15.3 Step-by-Step: Agent Instructions Deep Dive becomes real: read one agent's source file to understand what instructions it follows, what tools it can use, and what mistakes it could make. That matters in practice: VS Code or GitHub.com - reading files in the accessibility-agents repository.

      +

      Alex: The room should hear these as checkpoints. What is this agent trying to do? (its purpose). What tools does it have access to? (tool permissions). What constraints or guardrails are in the instructions?

      +

      Alex: First, in the accessibility-agents repository, navigate to the.github/ folder (or wherever agent definition files are stored). Then, open one.agent.md or.prompt.md file for an agent you used or are curious about. After that, read the file and identify. Finally, think critically: could this agent make a mistake? What kind? It is a checklist, but a meaningful one: every item creates evidence that the next step is safe.

      +

      Jamie: Before we leave Challenge 15.3 Step-by-Step: Agent Instructions Deep Dive, what is the practical point?

      +

      Alex: First, open your assigned Challenge 15 issue and post your analysis. It is like walking a hallway with named doors: read the sign, enter the right room, then confirm where you landed.

      +

      Jamie: Where do you want a learner to place their attention here?

      +

      Alex: Keep the learner anchored in Optional Extensions 15.4-15.5 (Hackathon). Extension 15.4: Improve an Existing Agent (45 min). This is the part to say slowly: Extension 15.5: Propose a New Agent (60 min).

      +

      Alex: These are the details that keep the idea from floating away. Find an agent whose instructions have a gap (use Section 6 suggestions or file an issue). Fork the repo, edit the agent's.agent.md file. Get a facilitator review. Open a PR with your improvement.

      -

      Alex: Keep the teaching thread moving. Start with When to Discard. There is something to understand, something to try, and something that proves the try worked.

      -

      Alex: The practical takeaway is this. You made experimental changes and they didn't work. You want to start over from the last commit. You accidentally edited the wrong file.

      -

      Jamie: Let's pause on Single file. What should a learner take away from it?

      -

      Alex: Start with Single file. There is something to understand, something to try, and something that proves the try worked.

      -

      Alex: First, open Source Control: Ctrl+Shift+G. Then, navigate to the file in "Changes". After that, press Shift+F10 for context menu. Finally, select "Discard Changes". Treat it like a recipe: do not add the next ingredient until the previous one is actually in the bowl.

      -

      Jamie: Before we leave Single file, what is the practical point?

      -

      Alex: First, confirm in the warning dialog (VS Code will ask "Are you sure?"). It is a checklist, but a meaningful one: every item creates evidence that the next step is safe.

      -

      Jamie: Let's pause on All changes. What should a learner take away from it?

      -

      Alex: This is where All changes becomes real: screen reader warning: VS Code shows a modal confirmation dialog. That matters in practice: Navigate with Tab, select "Discard" or "Cancel" with Enter. The workshop is closer to rehearsal than lecture. You hear the move, try the move, and then check what changed.

      -

      Alex: First, ctrl+Shift+G. Then, navigate to the "Changes" section heading. After that, shift+F10 for context menu. Finally, select "Discard All Changes". It is a checklist, but a meaningful one: every item creates evidence that the next step is safe.

      -

      Jamie: Before we leave All changes, what is the practical point?

      -

      Alex: First, confirm (this affects every modified file). It is like walking a hallway with named doors: read the sign, enter the right room, then confirm where you landed.

      +

      Alex: Before the learner moves on. The reason Completing Challenge 15: Submit Your Evidence matters is that your evidence is the Challenge 15 issue comments for 15.1, 15.2, and 15.3. That gives the learner a simple foothold: for optional extensions, your PR or proposal issue is the evidence. The interface gets friendlier when it stops being a wall of controls and starts being a set of named places.

      +

      Jamie: What would you say to someone who is already bracing for this to be too much?

      +

      Alex: Start with Expected Outcomes. There is something to understand, something to try, and something that proves the try worked.

      +

      Alex: A few details make that real. Student can map personal Day 1 skills to specific agents in the ecosystem. Student understands the Skill First, Agent Second principle and can articulate why agent output requires human judgment. Student can read agent instructions and evaluate what an agent can and cannot do. Student has used at least one agent and verified it against manual skills. (Optional) Student has contributed to the accessibility-agents ecosystem with a fix, improvement, or proposal.

      +

      Jamie: Let's pause on If You Get Stuck. What should a learner take away from it?

      +

      Alex: Here is the plain-English version of If You Get Stuck. Continue learning: The GitHub Skills courses Build Applications with Copilot Agent Mode and Expand Your Team with Copilot explore agent-powered development workflows. Put another way, see Appendix Z for the full catalog.

      +

      Alex: First, cannot find an agent that matches your skills? Start with @daily-briefing or @issue-tracker - those build directly on Chapter 2-5 material. If you have not done those manual steps yet, go back to those chapters first. Then, agent output does not make sense? That is the right response. Paste the output in an issue comment along with your confusion. That is valuable feedback - the agent may need better instructions or guardrails. After that, cannot access the agents in Copilot Chat? Verify: Is Copilot Chat extension installed (not just base Copilot)? Are you signed in to GitHub in VS Code? Does.github/agents/ folder exist in your cloned repository? Finally, repository will not clone? Use the terminal: git clone https://github.com/[your-username]/accessibility-agents.git then open the folder in VS Code. Treat it like a recipe: do not add the next ingredient until the previous one is actually in the bowl.

      +

      Jamie: Before we leave If You Get Stuck, what is the practical point?

      +

      Alex: First, ask facilitator to show them what agent you wanted to run, what output you got, and what you expected. Then, finished but not sure you did it right? Compare your work against the Challenge 15 reference solution. It is a checklist, but a meaningful one: every item creates evidence that the next step is safe.

      -

      Jamie: Let's pause on Learning Cards: Discarding Changes. What should a learner take away from it?

      -

      Alex: Keep the learner anchored in Learning Cards: Discarding Changes. Low vision users (zoom, high contrast). This is the part to say slowly: Screen reader users (NVDA / JAWS on Windows).

      -

      Alex: First, 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.". Then, 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. After that, for "Discard All Changes", right-click the "Changes" section heading to get the context menu. Finally, 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"). It is like walking a hallway with named doors: read the sign, enter the right room, then confirm where you landed.

      -

      Jamie: What is the teaching move inside Single file?

      -

      Alex: First, press Ctrl+Shift+G to open Source Control. Then, navigate to the file in the Changes section with Down Arrow. After that, press Shift+F10 to open the context menu. Finally, navigate to "Discard Changes" with Down Arrow, press Enter. The rhythm is simple: orient, act, verify, then continue.

      -

      Jamie: If someone only remembers one thing from Single file, what should it be?

      -

      Alex: First, a confirmation dialog appears - NVDA announces "Are you sure you want to discard changes" or similar. Then, press Tab to navigate between "Discard" and "Cancel", press Enter on your choice. Think of it as a rail line: each stop confirms you are still on the right route before the next one.

      -

      Jamie: Let's pause on All files. What should a learner take away from it?

      -

      Alex: Start with All files: Screen reader users (VoiceOver on macOS). The next useful detail is this: Discard changes from your terminal.

      -

      Alex: First, navigate to the "Changes" section heading (announced as "Changes, expanded, N items"). Then, press Shift+F10, select "Discard All Changes". After that, confirm in the dialog. Finally, press Cmd+Shift+G to open Source Control. Think of it as a rail line: each stop confirms you are still on the right route before the next one.

      -

      Jamie: Before we leave All files, what is the practical point?

      -

      Alex: First, use VO+Arrow keys to navigate to the file. Then, press VO+Shift+M to open the context menu (or Ctrl+Return). After that, navigate to "Discard Changes", press VO+Space. Finally, in the confirmation dialog, use VO+Right Arrow to reach the buttons, VO+Space to activate. Treat it like a recipe: do not add the next ingredient until the previous one is actually in the bowl.

      -

      Alex: Treat examples as spoken recipes, not decorations. You may hear something like 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. Read the command, understand what it changes, then run it only when the repository state matches the lesson.

      +

      Jamie: If I am listening before the workshop starts, what should settle in my mind first?

      +

      Alex: This is where Learning Moment becomes real: the 55 agents exist because someone did the manual work first, then automated the repetitive parts. That matters in practice: As you explore agents, you are not just learning tools - you are learning what automation looks like when it is built on real expertise and real constraints.

      +

      Jamie: Let's pause on Learning Pattern Used in This Chapter. What should a learner take away from it?

      +

      Alex: Start with Learning Pattern Used in This Chapter. There is something to understand, something to try, and something that proves the try worked.

      +

      Alex: First, map your existing skills to available tools (discovery before action). Then, run one tool and evaluate its output critically (trust but verify). After that, read the source to understand capabilities and limits (internals matter). Finally, contribute improvements based on your evaluation (close the feedback loop). It is like walking a hallway with named doors: read the sign, enter the right room, then confirm where you landed.

      +

      Jamie: Give me the version that sounds like an instructor, not a manual.

      +

      Alex: The reason Capstone: Share Your Feedback (The Most Important Task!) matters is that you have now explored the full agent ecosystem, completed the workshop, and have valuable perspective on what worked, what confused you, and what we should improve for the next cohort. That gives the learner a simple foothold: your feedback directly shapes the future of this project.

      -

      Alex: Keep the teaching thread moving. Here is the plain-English version of 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. Put another way, stash saves your changes temporarily without committing them. It is like learning a transit route. The names of the stops matter because they tell you whether you are still going the right direction.

      -

      Jamie: Let's pause on Deleting a File from the Repository (Git Delete / git rm). What should a learner take away from it?

      -

      Alex: This is where Deleting a File from the Repository (Git Delete / git rm) becomes real: Git Delete removes a file from both your working directory AND Git's tracking. That matters in practice: This is different from discarding changes - it permanently removes the file from the repository history going forward.

      -

      Jamie: Let's pause on How to use. What should a learner take away from it?

      -

      Alex: Keep the learner anchored in How to use. The file is staged for deletion - you still need to commit to record the removal.

      -

      Alex: First, open the file you want to remove in the editor. Then, ctrl+Shift+P (Mac: Cmd+Shift+P). After that, type "Git: Delete". Finally, confirm the deletion. It is like walking a hallway with named doors: read the sign, enter the right room, then confirm where you landed.

      +

      Alex: Here is the practical turn. Start with Submit Workshop Feedback: Use the Workshop Feedback form to share. The next useful detail is this: Answer as much or as little as you're comfortable sharing.

      +

      Alex: That becomes easier when you listen for these cues. Which agents stood out? (Most useful or surprising). Which agents confused you? (What would make them better). Was the chapter progression logical? (Did earlier chapters prepare you for later ones). Accessibility experience (If applicable - did any assistive technology work/fail?).

      +

      Jamie: Let's pause on 1. The Principle: Skill First, Agent Second. What should a learner take away from it?

      +

      Alex: Here is the plain-English version of 1. The Principle: Skill First, Agent Second. Accessibility Agents is not a way to skip learning GitHub. Put another way, it is a way to amplify skills you have already built through deliberate practice.

      +

      Alex: That shows up in the workshop in a few specific ways. Verify that the agent's output is correct. Catch when the agent misses context that only you have. Edit the agent's drafts into something worth posting under your name. Know when the agent is confidently wrong.

      +

      Alex: Keep the thread going. This is where Every agent has a manual prerequisite. If you have not done the corresponding skill by hand, the agent is not ready for you yet - and you are not ready for it becomes real: this applies across all three teams and all 55 agents. That matters in practice: Before running any agent, the facilitator asks the same question. The workshop is closer to rehearsal than lecture. You hear the move, try the move, and then check what changed.

      +

      Alex: The parts worth keeping in working memory are these. GitHub Workflow agents automate repository navigation, issue triage, PR review, and contribution analytics - skills you practiced on Day 1. Accessibility agents automate WCAG auditing, contrast checking, keyboard navigation review, and document scanning - knowledge from your accessibility training and the standards in Appendix C. Developer Tools agents automate accessible coding patterns for Python, wxPython, and desktop applications - skills from your development experience.

      -

      Jamie: Let's pause on When to use Git Delete vs. just deleting the file. What should a learner take away from it?

      -

      Alex: Start with When to use Git Delete vs. just deleting the file. There is something to understand, something to try, and something that proves the try worked.

      -

      Alex: The practical takeaway is this. 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.

      -

      Jamie: Let's pause on Learning Cards: Deleting a File from the Repository. What should a learner take away from it?

      -

      Alex: Start with Learning Cards: Deleting a File from the Repository: Alternatively: Ctrl+Shift+P then "Git: Delete" removes the file and stages the deletion in one step. The next useful detail is this: Low vision users (zoom, high contrast). Think of it like entering a new building: first you find the lobby, then the room, then the door you actually need.

      -

      Alex: First, right-click the file in the Explorer panel (Ctrl+Shift+E). Then, select "Delete" to delete from your file system. After that, the file appears in Source Control (Ctrl+Shift+G) under Changes with a "D" (deleted) status. Finally, stage and commit the deletion to record it in Git. Think of it as a rail line: each stop confirms you are still on the right route before the next one.

      -

      Jamie: Before we leave Learning Cards: Deleting a File from the Repository, what is the practical point?

      -

      Alex: First, 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. Then, 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. After that, stage and commit as normal. Finally, open the file you want to remove in the editor. Treat it like a recipe: do not add the next ingredient until the previous one is actually in the bowl.

      -

      Alex: Treat examples as spoken recipes, not decorations. You may hear something like 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. Read the command, understand what it changes, then run it only when the repository state matches the lesson.

      -

      Jamie: Let's pause on 8. Timeline View - File History and Blame. What should a learner take away from it?

      -

      Alex: Here is the plain-English version of 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.

      +

      Jamie: Let's pause on Learning Cards: Skill First, Agent Second. What should a learner take away from it?

      +

      Alex: Start with Learning Cards: Skill First, Agent Second. There is something to understand, something to try, and something that proves the try worked.

      +

      Alex: The practical takeaway is this. Before using any agent, verify you can do the task manually -- for @daily-briefing, confirm you can navigate Issues and PRs on GitHub.com with keyboard shortcuts (j/k to move, Enter to open). Agent output appears in Copilot Chat -- press Alt+F2 to open Accessible View and read the full response with arrow keys before acting on it. If an agent produces something you do not understand, stop and learn the manual skill first from the relevant chapter. Agent responses appear in the Copilot Chat panel -- drag the panel wider or use Alt+F2 (Accessible View) for a larger, cleaner reading pane. Each agent's instructions are in a.agent.md file you can open in VS Code and read at your preferred zoom level before invoking the agent. The agent ecosystem table in Section 3 uses standard Markdown tables that scale with your editor font size.

      +

      Alex: Another way to ground it. The reason Quick Install (One Command) matters is that accessibility Agents now ships with a one-liner installer that sets up all 55 agents for your platform.

      +

      Jamie: What should they understand before typing anything?

      +

      Alex: Start with macOS / Linux. There is something to understand, something to try, and something that proves the try worked.

      +

      Alex: Treat examples as spoken recipes, not decorations. You may hear something like curl -fsSL https://raw.githubusercontent.com/Community-Access/accessibility-agents/main/install.sh bash. Read the command, understand what it changes, then run it only when the repository state matches the lesson.

      -

      Jamie: Let's pause on Method 1: Explorer Sidebar. What should a learner take away from it?

      -

      Alex: Start with Method 1: Explorer Sidebar. There is something to understand, something to try, and something that proves the try worked.

      -

      Alex: First, open Explorer: Ctrl+Shift+E. Then, at the bottom of the Explorer, there's a "Timeline" section. After that, tab or Arrow to navigate into Timeline. Finally, the list shows all commits affecting the currently open file. It is a checklist, but a meaningful one: every item creates evidence that the next step is safe.

      -

      Jamie: Let's pause on Method 2: Command Palette. What should a learner take away from it?

      -

      Alex: Start with Method 2: Command Palette. There is something to understand, something to try, and something that proves the try worked.

      -

      Alex: First, open a file in the editor. Then, ctrl+Shift+P. After that, type "timeline". Finally, select "View: Show Timeline". It is like walking a hallway with named doors: read the sign, enter the right room, then confirm where you landed.

      -

      Alex: Keep the teaching thread moving. The reason What Timeline Shows matters is that screen reader announcement: "docs: add Timeline Guide, Jeff, 2 days ago". The interface gets friendlier when it stops being a wall of controls and starts being a set of named places.

      -

      Alex: The practical takeaway is this. Commit message (first line). Author name. Relative time (example: "3 days ago" or "2 hours ago"). Commit hash (short form, like a3f2b9c).

      +

      Alex: This is the part worth saying out loud. Here is the plain-English version of Windows (PowerShell). The installer detects which AI tools you have installed (VS Code with Copilot, Claude Code, Gemini CLI, Claude Desktop, Codex CLI) and configures the appropriate agent files for each platform. Put another way, to uninstall, run the corresponding uninstall script from the repository. It is like learning a transit route. The names of the stops matter because they tell you whether you are still going the right direction.

      +

      Jamie: Let's pause on Workshop Setup (Fork and Clone). What should a learner take away from it?

      +

      Alex: This is where Workshop Setup (Fork and Clone) becomes real: for the workshop, you will also fork and clone the repository so you can make contributions. That matters in practice: If Copilot Chat works, the agents work.

      +

      Alex: First, fork accessibility-agents to your GitHub account (you did this on Day 1 or Day 2 morning). Then, clone your fork. After that, open in VS Code: navigate to the folder and run code. (or File, then Open Folder). Finally, open Copilot Chat: Ctrl+Shift+I. It is a checklist, but a meaningful one: every item creates evidence that the next step is safe.

      +

      Jamie: Before we leave Workshop Setup (Fork and Clone), what is the practical point?

      +

      Alex: First, test: type @daily-briefing morning briefing and press Enter. It is like walking a hallway with named doors: read the sign, enter the right room, then confirm where you landed.

      +

      Alex: Treat examples as spoken recipes, not decorations. You may hear something like git clone https://github.com/[your-username]/accessibility-agents.git. Read the command, understand what it changes, then run it only when the repository state matches the lesson.

      +

      Alex: That connects to another useful point. Start with Prerequisites. There is something to understand, something to try, and something that proves the try worked.

      +

      Alex: The practical takeaway is this. GitHub Copilot Chat extension installed (see GitHub Copilot: Installation). Signed in to GitHub via VS Code. A workspace open containing.github/agents/ folder with.agent.md files.

      -

      Jamie: Let's pause on Viewing a Commit's Changes. What should a learner take away from it?

      -

      Alex: Start with Viewing a Commit's Changes: This is incredibly useful for understanding.

      -

      Alex: The practical takeaway is this. When a particular line was added. Why a section was removed. What the file looked like at any point in history.

      -

      Alex: First, navigate to a commit in the Timeline list. Then, press Enter. After that, a diff view opens showing what changed in that specific commit. Think of it as a rail line: each stop confirms you are still on the right route before the next one.

      -

      Alex: Keep the teaching thread moving. Here is the plain-English version of Git Blame - Line-by-Line History. Git Blame shows who last modified each line of the file.

      -

      Jamie: Let's pause on How to access. What should a learner take away from it?

      -

      Alex: Start with How to access. There is something to understand, something to try, and something that proves the try worked.

      -

      Alex: First, open a file in the editor. Then, ctrl+Shift+P. After that, type "git blame". Finally, select "Git: Toggle Blame". It is a checklist, but a meaningful one: every item creates evidence that the next step is safe.

      +

      Jamie: Let's pause on How Agents Are Discovered. What should a learner take away from it?

      +

      Alex: The reason How Agents Are Discovered matters is that when you type @ in Copilot Chat, VS Code scans. That gives the learner a simple foothold: the Accessibility Agents ecosystem installs agents appropriate to each platform.

      +

      Alex: First,.github/agents/.agent.md in your current workspace. Then, any agents installed globally on your machine. After that, agents defined by extensions. The rhythm is simple: orient, act, verify, then continue.

      +

      Alex: That matters because of the next idea. Start with Optional: Personalize Your Instance: Open preferences.md in VS Code and edit. The next useful detail is this: Commit preferences.md to your fork. Think of it like entering a new building: first you find the lobby, then the room, then the door you actually need.

      +

      Jamie: Let's pause on How Agents Travel with Your Repo. What should a learner take away from it?

      +

      Alex: Here is the plain-English version of How Agents Travel with Your Repo. When you fork accessibility-agents, the.github/agents/ folder comes with it.

      +

      Alex: The practical takeaway is this. Any collaborator who clones your fork gets all 55 agents automatically. You can customize agents for your specific project by editing the.agent.md files in your fork. Any project can have agents - create a.github/agents/ folder in any repository and add.agent.md files using the same pattern. The one-liner installer can also set up agents globally, so they are available in every workspace you open.

      -

      Alex: Keep the teaching thread moving. Start with What appears. There is something to understand, something to try, and something that proves the try worked.

      -

      Alex: The practical takeaway is this. Inline annotations next to every line (visually). Hover over a line to see commit details.

      -

      Jamie: Let's pause on For screen reader users. What should a learner take away from it?

      -

      Alex: The reason For screen reader users matters is that useful blame settings (add to.vscode/settings.json or user Settings).

      -

      Alex: The practical takeaway is this. 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.

      -

      Jamie: Let's pause on Learning Cards: Timeline and History. What should a learner take away from it?

      -

      Alex: Start with Learning Cards: Timeline and History: Low vision users (zoom, high contrast). The next useful detail is this: Screen reader users (NVDA / JAWS on Windows).

      -

      Alex: First, 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. Then, 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. After that, 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. Finally, 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. Think of it as a rail line: each stop confirms you are still on the right route before the next one.

      +

      Alex: This is where the talk moves from concept to action. This is where Invoking Agents on GitHub.com becomes real: accessibility Agents agents run in VS Code. That matters in practice: But the same.agent.md files can also be invoked directly on GitHub.com - no VS Code, no local clone required.

      +

      Jamie: Let's pause on Option 1: Copilot Chat with Task mode. What should a learner take away from it?

      +

      Alex: Keep the learner anchored in Option 1: Copilot Chat with Task mode. Screen reader users (NVDA / JAWS / VoiceOver).

      +

      Alex: First, open Copilot Chat on GitHub.com (icon in the top-right navigation bar). Then, click Task in the mode picker. After that, optionally click the agent picker to select a custom agent. Finally, type your request and click Send. It is like walking a hallway with named doors: read the sign, enter the right room, then confirm where you landed.

      +

      Jamie: Before we leave Option 1: Copilot Chat with Task mode, what is the practical point?

      +

      Alex: First, Copilot analyzes the task and can create a branch and open a PR automatically. Then, open Copilot Chat on GitHub.com (navigate to icon in top-right navigation → Enter). After that, the mode picker (Task vs Chat) is a set of radio buttons - navigate with Arrow keys to select "Task". Finally, the agent picker is a listbox - Up/Down Arrow to navigate, Enter to select. The rhythm is simple: orient, act, verify, then continue.

      +

      Jamie: Let's pause on Option 2: Assign an issue to Copilot. What should a learner take away from it?

      +

      Alex: The reason Option 2: Assign an issue to Copilot matters is that screen reader users (NVDA / JAWS / VoiceOver). That gives the learner a simple foothold: this is the bridge to Section 6 (The Cloud Extension). The interface gets friendlier when it stops being a wall of controls and starts being a set of named places.

      +

      Alex: First, open any issue (or create a new one describing the task). Then, in the Assignees sidebar section, click the gear icon. After that, in the dropdown, click Copilot as the assignee. Finally, a dialog opens - optionally provide additional instructions and select a custom agent. The rhythm is simple: orient, act, verify, then continue.

      +

      Jamie: Before we leave Option 2: Assign an issue to Copilot, what is the practical point?

      +

      Alex: First, click Assign to confirm. Then, open any issue in the repository. After that, press B to navigate to the Assignees gear button → Enter to open the popup. Finally, navigate the popup with Arrow keys → find "Copilot" → Enter to select. Think of it as a rail line: each stop confirms you are still on the right route before the next one.

      +

      Alex: A solid issue habit is to read the title, the body, and the timeline before acting. You are listening for the requested action, the missing evidence, and the person who needs a response.

      -

      Jamie: Let's pause on Opening Timeline. What should a learner take away from it?

      -

      Alex: Start with Opening Timeline. There is something to understand, something to try, and something that proves the try worked.

      -

      Alex: First, press Ctrl+Shift+E to open Explorer. Then, press Tab repeatedly or Down Arrow to navigate past the file tree to the "Timeline" section. After that, press Right Arrow to expand it if collapsed. Finally, navigate commit entries with Up/Down Arrow. Treat it like a recipe: do not add the next ingredient until the previous one is actually in the bowl.

      -

      Jamie: Before we leave Opening Timeline, what is the practical point?

      -

      Alex: First, each entry is announced as: "commit message, author, time" (e.g., "docs: add Timeline Guide, Jeff, 2 days ago"). Then, press Enter on any entry to open its diff view. It is a checklist, but a meaningful one: every item creates evidence that the next step is safe.

      -

      Jamie: Let's pause on Reading a diff with screen reader. What should a learner take away from it?

      -

      Alex: Start with Reading a diff with screen reader. There is something to understand, something to try, and something that proves the try worked.

      -

      Alex: First, in the diff view, press Alt+F2 to open the Accessible Diff Viewer. Then, the Accessible Diff Viewer presents changes as a text list: each line shows + (added), - (removed), or unchanged. After that, navigate with Up/Down Arrow to read each line. Finally, press Escape to close the Accessible Diff Viewer. It is a checklist, but a meaningful one: every item creates evidence that the next step is safe.

      -

      Jamie: Let's pause on Git Blame. What should a learner take away from it?

      -

      Alex: Keep the learner anchored in Git Blame. Screen reader users (VoiceOver on macOS).

      -

      Alex: First, open a file, press Ctrl+Shift+P, type "Git: Toggle Blame". Then, blame annotations appear inline - NVDA reads them when navigating lines. After that, to reduce noise, disable blame (repeat the toggle command) and use Timeline instead. It is like walking a hallway with named doors: read the sign, enter the right room, then confirm where you landed.

      +

      Jamie: There are a lot of tools in play. How do we keep that from feeling like a contest?

      +

      Alex: Start with Copilot on GitHub.com - Browser-Native Features: Beyond assigning Copilot to issues and using Task mode in Chat, GitHub.com now has several standalone Copilot features built directly into the web interface. The next useful detail is this: These work entirely in your browser - no VS Code, no local clone needed.

      +

      Alex: Hold that next to this. Here is the plain-English version of Copilot PR Summary. On any open pull request, GitHub adds a "Summarize" button in the PR description area. Put another way, selecting it generates a plain-language summary of what the PR changes, why, and what reviewers should focus on.

      +

      Jamie: Let's pause on Copilot PR Review. What should a learner take away from it?

      +

      Alex: This is where Copilot PR Review becomes real: on open PRs you have write access to review, a "Review" button (or Copilot icon) appears in the Files changed tab. That matters in practice: Copilot generates inline review comments across the diff.

      -

      Jamie: What is the teaching move inside Opening Timeline?

      -

      Alex: First, press Cmd+Shift+E to open Explorer. Then, use VO+Down Arrow to navigate below the file tree to the Timeline section. After that, press VO+Space to expand if collapsed. Finally, navigate entries with VO+Down Arrow. The rhythm is simple: orient, act, verify, then continue.

      -

      Jamie: If someone only remembers one thing from Opening Timeline, what should it be?

      -

      Alex: First, press VO+Space on a commit to open its diff. Think of it as a rail line: each stop confirms you are still on the right route before the next one.

      -

      Jamie: Let's pause on Accessible Diff Viewer. What should a learner take away from it?

      -

      Alex: Start with Accessible Diff Viewer: Screen reader advantage: git log --oneline and git blame produce clean, columnar text output. The next useful detail is this: Read line by line with arrow keys in the terminal.

      -

      Alex: First, in any diff view, press Option+F2 to open the Accessible Diff Viewer. Then, read changes line by line with VO+Down Arrow. After that, press Escape to close. Think of it as a rail line: each stop confirms you are still on the right route before the next one.

      -

      Alex: Treat examples as spoken recipes, not decorations. You may hear something like 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. 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. Read the command, understand what it changes, then run it only when the repository state matches the lesson.

      -

      Alex: Keep the teaching thread moving. Here is the plain-English version of 9. Resolving Merge Conflicts in VS Code. Merge conflicts happen when two people edit the same lines of a file. Put another way, Git can't decide which version to keep, so it asks you to choose. It is like learning a transit route. The names of the stops matter because they tell you whether you are still going the right direction.

      +

      Alex: Keep the teaching thread moving. Keep the learner anchored in Copilot in Issues. On any issue page, Copilot adds sidebar buttons that appear once the page loads. This is the part to say slowly: Look in the right sidebar on any issue page for a Copilot section with "Explain" and "Suggest fix" buttons. A good GitHub workflow is like a well-run meeting: everyone knows the topic, the next action, and who has the floor.

      +

      Alex: The practical takeaway is this. "Explain this issue" - generates a plain-language explanation of a complex technical issue. "Suggest fix" - proposes an approach to resolving the issue (opens a task/PR workflow).

      +

      Jamie: Let's pause on GitHub Models - Free AI Playground. What should a learner take away from it?

      +

      Alex: The reason GitHub Models - Free AI Playground matters is that github.com/marketplace/models is a free playground where you can test AI models (OpenAI GPT-4o, Meta Llama 3, Mistral, Phi-4 Mini, and others) directly in your browser. That gives the learner a simple foothold: why it matters for Accessibility Agents: When you build custom agents and prompts, you can test your system prompts and prompt templates in GitHub Models before adding them to your.prompt.md files - rapid iteration without burning API credits.

      +

      Alex: The practical takeaway is this. Send prompts to any listed model and compare responses side by side. Adjust parameters (temperature, max tokens) without any setup. Use the code sample generator to get API code for your chosen model. All free with a GitHub account (rate-limited for free tier).

      +

      Alex: Keep the teaching thread moving. Start with Copilot-Drafted Release Notes: When creating a release (Releases tab → Draft a new release), GitHub provides a "Generate release notes" button. The next useful detail is this: It scans merged PRs since the last release and drafts categorized release notes automatically.

      -

      Jamie: There are a lot of tools in play. How do we keep that from feeling like a contest?

      -

      Alex: This is where How VS Code Displays Conflicts becomes real: when you open a file with conflicts, you see something like. That matters in practice: VS Code adds buttons above each conflict (visually).

      -

      Alex: The practical takeaway is this. "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).

      -

      Jamie: Let's pause on Screen Reader Workflow for Resolving Conflicts. What should a learner take away from it?

      -

      Alex: Keep the learner anchored in Screen Reader Workflow for Resolving Conflicts. The buttons are NOT accessible via keyboard.

      -

      Alex: The practical takeaway is this. <<<<<<< marks the start. ======= separates the two versions. marks the end. The section between <<<<<<< and ======= is your current branch (HEAD). The section between ======= and is the incoming branch (the branch you're merging). Delete the conflict markers ( ).

      -

      Alex: First, identify the conflict markers. Then, read both versions. After that, decide what to keep. Finally, stage the resolved file. It is like walking a hallway with named doors: read the sign, enter the right room, then confirm where you landed.

      -

      Jamie: Before we leave Screen Reader Workflow for Resolving Conflicts, what is the practical point?

      -

      Alex: First, commit the merge. The rhythm is simple: orient, act, verify, then continue.

      -

      Jamie: Let's pause on Using Accessible Diff for Conflict Review. What should a learner take away from it?

      -

      Alex: The reason Using Accessible Diff for Conflict Review matters is that better approach: Use the Accessible Diff Viewer (F7) to navigate conflict hunks systematically.

      -

      Alex: First, open the conflicted file. Then, press F7 to jump to the first conflict hunk. After that, press Alt+F2 to open Accessible View. Finally, read both versions clearly. The rhythm is simple: orient, act, verify, then continue.

      -

      Jamie: Before we leave Using Accessible Diff for Conflict Review, what is the practical point?

      -

      Alex: First, press Escape to return to editor. Then, manually edit to resolve. After that, press F7 to jump to the next conflict. Finally, repeat until all conflicts resolved. Think of it as a rail line: each stop confirms you are still on the right route before the next one.

      +

      Jamie: What does someone need before they touch the keyboard?

      +

      Alex: Start with Learning Cards: Setup and Configuration. There is something to understand, something to try, and something that proves the try worked.

      +

      Alex: The practical takeaway is this. Run the installer command in the VS Code terminal (Ctrl+) -- it announces progress as it copies agent files to.github/agents/`. After installation, press Ctrl+Shift+E to open the Explorer and navigate to.github/agents/ to verify agent files are present. Edit.github/agents/preferences.md to configure your username, repositories, and notification preferences -- it is a standard Markdown file. The installer creates files in.github/agents/ and.github/prompts/ -- verify in the Explorer sidebar that these folders appeared. Open preferences.md in the editor to set your configuration -- use Ctrl+= to zoom if the YAML frontmatter is hard to read. Agent files use.agent.md extension -- they appear alongside regular Markdown files in the Explorer but are distinguished by their extension.

      +

      Alex: Keep the teaching thread moving. This is where 3. The Ecosystem: 55 Agents, 3 Teams, 5 Platforms becomes real: accessibility Agents is an ecosystem of 55 specialized agents organized into three teams, each addressing a different dimension of accessible software development. That matters in practice: Browse all three teams below, then choose the agents that match your current skills and interests. The workshop is closer to rehearsal than lecture. You hear the move, try the move, and then check what changed.

      +

      Jamie: Let's pause on Team 1: Accessibility (26 agents). What should a learner take away from it?

      +

      Alex: Keep the learner anchored in Team 1: Accessibility (26 agents). These agents audit, fix, and enforce accessibility across web, document, and mobile platforms.

      -

      Jamie: Let's pause on Aborting a Merge. What should a learner take away from it?

      -

      Alex: Start with Aborting a Merge: If you want to cancel the merge and go back to before you started. The next useful detail is this: Everything returns to the pre-merge state. Think of it like entering a new building: first you find the lobby, then the room, then the door you actually need.

      -

      Alex: First, ctrl+Shift+P. Then, type "git abort". After that, select "Git: Abort Merge". Think of it as a rail line: each stop confirms you are still on the right route before the next one.

      -

      Jamie: Let's pause on Learning Cards: Resolving Merge Conflicts. What should a learner take away from it?

      -

      Alex: Start with Learning Cards: Resolving Merge Conflicts. There is something to understand, something to try, and something that proves the try worked.

      -

      Alex: The practical takeaway is this. 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. 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.

      -

      Alex: Keep the teaching thread moving. This is where 10. Stash Management becomes real: stash temporarily saves your uncommitted changes so you can switch branches or pull updates without committing half-finished work.

      +

      Alex: Keep the teaching thread moving. The reason Team 2: GitHub Workflow (12 agents) matters is that these agents automate GitHub operations - issue triage, PR review, contribution analytics, and repository management.

      +

      Jamie: What should someone listen for when a lesson offers more than one tool path?

      +

      Alex: Start with Team 3: Developer Tools (6 agents): These agents support accessible application development across desktop and cross-platform frameworks.

      +

      Alex: Keep the teaching thread moving. Here is the plain-English version of Beyond Agents: The Supporting Ecosystem. The 55 agents are backed by additional resources in the repository. It is like learning a transit route. The names of the stops matter because they tell you whether you are still going the right direction.

      -

      Jamie: Let's pause on When to Use Stash. What should a learner take away from it?

      -

      Alex: Start with When to Use Stash. There is something to understand, something to try, and something that proves the try worked.

      -

      Alex: The practical takeaway is this. 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.

      -

      Jamie: Let's pause on Method 1: Command Palette. What should a learner take away from it?

      -

      Alex: Start with Method 1: Command Palette. There is something to understand, something to try, and something that proves the try worked.

      -

      Alex: First, ctrl+Shift+P. Then, type "git stash". After that, select "Git: Stash". Finally, optionally type a stash message (helps you remember what's in it). The rhythm is simple: orient, act, verify, then continue.

      -

      Jamie: Let's pause on What happens. What should a learner take away from it?

      -

      Alex: Start with What happens. There is something to understand, something to try, and something that proves the try worked.

      -

      Alex: The practical takeaway is this. 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.

      +

      Jamie: Let's pause on Hook-Based Enforcement (Claude Code). What should a learner take away from it?

      +

      Alex: This is where Hook-Based Enforcement (Claude Code) becomes real: on Claude Code, Accessibility Agents includes a hook system that enforces accessibility standards automatically. That matters in practice: This means accessibility enforcement happens whether or not the developer remembers to ask for it.

      +

      Alex: First, proactive detection hook - scans every file edit for accessibility regressions before they are committed. Then, edit gate hook - blocks commits that introduce WCAG violations until they are fixed. After that, session marker hook - tracks which accessibility checks have run during the current session. It is a checklist, but a meaningful one: every item creates evidence that the next step is safe.

      +

      Alex: Keep the teaching thread moving. Keep the learner anchored in What Would You Build? This is the question that matters most. This is the part to say slowly: The 55 agents that exist today were built by contributors who saw a gap and filled it.

      +

      Alex: The practical takeaway is this. "Why is there no agent for [framework] accessibility patterns?". "I spend 30 minutes on [task] every week - could an agent do the repetitive part?". "This agent is good but it misses [specific edge case] - I could improve those instructions". "Mobile native accessibility testing has no agent coverage yet - I could start one".

      +

      Jamie: Let's pause on The contribution paths are. What should a learner take away from it?

      +

      Alex: The reason The contribution paths are matters is that see the Accessibility Agents CONTRIBUTING guide for detailed instructions on each path.

      +

      Alex: First, report an agent gap - file an issue describing what is missing and why it matters. Then, improve existing agent instructions - make an agent smarter about edge cases it misses. After that, add framework-specific patterns - teach agents about React, Vue, Angular, Svelte, or other framework accessibility patterns. Finally, fix installer issues - improve the one-liner scripts for different OS configurations. The rhythm is simple: orient, act, verify, then continue.

      +

      Jamie: Before we leave The contribution paths are, what is the practical point?

      +

      Alex: First, write documentation - help others understand how to use and contribute to agents. Think of it as a rail line: each stop confirms you are still on the right route before the next one.

      -

      Jamie: Let's pause on Command Palette. What should a learner take away from it?

      -

      Alex: Start with Command Palette. There is something to understand, something to try, and something that proves the try worked.

      -

      Alex: First, ctrl+Shift+P. Then, type "git stash list". After that, select "Git: Show Stash". Treat it like a recipe: do not add the next ingredient until the previous one is actually in the bowl.

      -

      Jamie: Let's pause on Alternative: Integrated Terminal. What should a learner take away from it?

      -

      Alex: Start with Alternative: Integrated Terminal. There is something to understand, something to try, and something that proves the try worked.

      -

      Alex: Treat examples as spoken recipes, not decorations. You may hear something like git stash list. Read the command, understand what it changes, then run it only when the repository state matches the lesson.

      -

      Jamie: Let's pause on To restore your stashed changes. What should a learner take away from it?

      -

      Alex: Start with To restore your stashed changes. There is something to understand, something to try, and something that proves the try worked.

      -

      Alex: First, ctrl+Shift+P. Then, type "git stash apply". After that, select "Git: Apply Latest Stash". It is like walking a hallway with named doors: read the sign, enter the right room, then confirm where you landed.

      +

      Alex: Keep the teaching thread moving. Start with Roadmap: What Is Coming Next: Your contribution could be the next item that ships. The next useful detail is this: Every agent started as one person's idea and one pull request. Think of it like entering a new building: first you find the lobby, then the room, then the door you actually need.

      +

      Alex: The practical takeaway is this. Mobile native agents - agents specialized for iOS (VoiceOver) and Android (TalkBack) native app accessibility. Anthropic Connectors listing - making agents discoverable through the Anthropic marketplace. veraPDF integration - automated PDF/UA validation for the PDF accessibility agent. Document remediation agents - agents that fix accessibility issues in documents, not just find them.

      +

      Jamie: Let's pause on Learning Cards: The Agent Ecosystem. What should a learner take away from it?

      +

      Alex: Start with Learning Cards: The Agent Ecosystem. There is something to understand, something to try, and something that proves the try worked.

      +

      Alex: The practical takeaway is this. The three team tables use standard Markdown table format -- navigate with T (NVDA/JAWS) to jump between tables, then Arrow keys to read cells. Agent names start with @ -- type @ followed by the agent name in Copilot Chat to invoke it (e.g., @daily-briefing). Use Ctrl+Shift+O (symbol outline) in any agent file to navigate between its YAML frontmatter sections (Purpose, Responsibilities, Guardrails). The agent tables are dense -- use Ctrl+= to increase font size or open the file in Markdown Preview (Ctrl+Shift+V) for cleaner rendering. Each team has a distinct table: Team 1 (Accessibility, 26 agents), Team 2 (GitHub Workflow, 15 agents), Team 3 (Developer Tools, 14 agents). Agent files in.github/agents/ have descriptive filenames that match the @agent-name -- browse them in the Explorer to find specific agents.

      +

      Alex: Keep the teaching thread moving. This is where 4. Agents in Detail - Hands-On Reference becomes real: this section walks through several agents in depth so you can see how they work, what they produce, and how to evaluate their output. That matters in practice: These examples use GitHub Workflow agents because they build directly on Day 1 skills - but the same patterns apply to every agent in the ecosystem.

      -

      Jamie: Let's pause on Or to apply a specific stash. What should a learner take away from it?

      -

      Alex: Start with Or to apply a specific stash. There is something to understand, something to try, and something that proves the try worked.

      -

      Alex: First, ctrl+Shift+P. Then, type "git stash pop". After that, select "Git: Pop Stash.". Finally, choose which stash from the list. The rhythm is simple: orient, act, verify, then continue.

      -

      Alex: Keep the teaching thread moving. Start with Difference between Apply and Pop. There is something to understand, something to try, and something that proves the try worked.

      -

      Alex: The practical takeaway is this. Apply: restores changes and keeps the stash (you can apply it again later). Pop: restores changes and deletes the stash.

      -

      Jamie: Let's pause on Dropping a Stash. What should a learner take away from it?

      -

      Alex: Here is the plain-English version of Dropping a Stash. If you no longer need what's in a stash.

      -

      Alex: First, ctrl+Shift+P. Then, type "git stash drop". After that, select "Git: Drop Stash.". Finally, choose which stash to delete. Treat it like a recipe: do not add the next ingredient until the previous one is actually in the bowl.

      +

      Jamie: Let's pause on Two Types of Agents. What should a learner take away from it?

      +

      Alex: Keep the learner anchored in Two Types of Agents. Before diving in, it helps to know that custom agents fall into two categories - this distinction affects what tool permissions they need and what they can do. This is the part to say slowly: Informational agents search, analyze, and report.

      +

      Alex: Keep the teaching thread moving. The reason Agent 1: @daily-briefing - Morning Briefing matters is that file.github/agents/daily-briefing.agent.md. That gives the learner a simple foothold: before you run this agent: You should have manually navigated a repository's Issues tab, read your GitHub Notifications page, understood what a pull request waiting for review looks like, and know the difference between subscribed and participating. The interface gets friendlier when it stops being a wall of controls and starts being a set of named places.

      +

      Jamie: Let's pause on What it does. What should a learner take away from it?

      +

      Alex: Start with What it does: Sweeps every repository you have access to and builds a prioritized dashboard.

      +

      Alex: The practical takeaway is this. Issues opened in the last 24 hours. Pull requests waiting for your review. CI failures on your branches. Security and Dependabot alerts. Community reactions to your recent comments.

      -

      Jamie: Let's pause on Learning Cards: Stash Management. What should a learner take away from it?

      -

      Alex: This is where Learning Cards: Stash Management becomes real: if the Stashes section is not visible, use the Command Palette: Ctrl+Shift+P then type "git stash" to access all stash commands. That matters in practice: Low vision users (zoom, high contrast). The workshop is closer to rehearsal than lecture. You hear the move, try the move, and then check what changed.

      -

      Alex: First, open Source Control: Ctrl+Shift+G. Then, in the Source Control panel, there may be a "Stashes" section below Staged Changes (visible when stashes exist). After that, click a stash to see what it contains. Finally, right-click a stash to Apply, Pop, or Drop it. It is a checklist, but a meaningful one: every item creates evidence that the next step is safe.

      -

      Jamie: Before we leave Learning Cards: Stash Management, what is the practical point?

      -

      Alex: First, 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. Then, 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. After that, after applying a stash, your files reappear in the Changes section of Source Control. Check the file count to confirm. It is like walking a hallway with named doors: read the sign, enter the right room, then confirm where you landed.

      -

      Jamie: Let's pause on Creating a stash. What should a learner take away from it?

      -

      Alex: Start with Creating a stash. There is something to understand, something to try, and something that proves the try worked.

      -

      Alex: First, press Ctrl+Shift+P, type "git stash". Then, select "Git: Stash" - NVDA announces the result. After that, an input appears asking for a stash message - type something descriptive (e.g., "WIP: documentation changes for Timeline section"). Finally, press Enter - your changes disappear from Source Control and are saved in the stash. It is like walking a hallway with named doors: read the sign, enter the right room, then confirm where you landed.

      -

      Jamie: Before we leave Creating a stash, what is the practical point?

      -

      Alex: First, NVDA announces the Source Control panel update (file counts drop to 0). The rhythm is simple: orient, act, verify, then continue.

      -

      Jamie: Let's pause on Applying a stash. What should a learner take away from it?

      -

      Alex: Start with Applying a stash. There is something to understand, something to try, and something that proves the try worked.

      -

      Alex: First, press Ctrl+Shift+P, type "git stash pop". Then, select "Git: Pop Stash.". After that, a list of stashes appears - navigate with Up/Down Arrow. Finally, each item is announced with the stash message you wrote. The rhythm is simple: orient, act, verify, then continue.

      -

      Jamie: Before we leave Applying a stash, what is the practical point?

      -

      Alex: First, press Enter to apply and delete the stash. Then, your changes reappear in the Changes section. Think of it as a rail line: each stop confirms you are still on the right route before the next one.

      +

      Alex: Keep the teaching thread moving. Here is the plain-English version of Example commands. The briefing output uses heading level 2 for each section. Put another way, use H key (NVDA/JAWS virtual mode) or VO+Command+H (VoiceOver) to jump between: Open Issues, Review Requests, CI Status, Security Alerts, Community Activity.

      +

      Jamie: Let's pause on Agent 2: @issue-tracker - Issue Management. What should a learner take away from it?

      +

      Alex: This is where Agent 2: @issue-tracker - Issue Management becomes real: file.github/agents/issue-tracker.agent.md. That matters in practice: Before you run this agent: You should have filed at least one issue using the full manual process - writing a title, description, and reproduction steps; applying labels and a milestone; and reading at least five existing issues to understand what a.

      +

      Alex: Keep the teaching thread moving. Keep the learner anchored in What it does. Finds, prioritizes, and helps you manage issues across all your repositories. A good GitHub workflow is like a well-run meeting: everyone knows the topic, the next action, and who has the floor.

      +

      Alex: The practical takeaway is this. Cross-repository priority scoring with community sentiment. Batch-reply capability (draft replies to multiple issues at once). Saved search support. Release-awareness (flags issues that affect upcoming releases).

      -

      Jamie: Let's pause on Viewing stashes. What should a learner take away from it?

      -

      Alex: Start with Viewing stashes: Screen reader users (VoiceOver on macOS). The next useful detail is this: GitHub.com does not have a stash feature.

      -

      Alex: First, press Ctrl+Shift+P, type "git stash list". Then, or in the terminal: type git stash list and read the output line by line. After that, press Cmd+Shift+P, type "git stash". Finally, select "Git: Stash" and provide a message. Think of it as a rail line: each stop confirms you are still on the right route before the next one.

      -

      Jamie: Before we leave Viewing stashes, what is the practical point?

      -

      Alex: First, press Return. Then, to apply: Cmd+Shift+P, type "git stash pop", select from the list with VO+Down Arrow, press Return. After that, create a draft commit on a temporary branch. Finally, or use GitHub Codespaces (which runs a full VS Code environment in the browser and supports git stash in the terminal). Treat it like a recipe: do not add the next ingredient until the previous one is actually in the bowl.

      -

      Alex: Treat examples as spoken recipes, not decorations. You may hear something like 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. Read the command, understand what it changes, then run it only when the repository state matches the lesson.

      -

      Alex: Keep the teaching thread moving. Here is the plain-English version of 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. Put another way, it is the most underused recovery tool in Git. It is like learning a transit route. The names of the stops matter because they tell you whether you are still going the right direction.

      -

      Jamie: Can you translate that into plain choices?

      -

      Alex: Start with When to Use Reflog. There is something to understand, something to try, and something that proves the try worked.

      -

      Alex: Use the comparison to make a decision, not to recite a table. The main contrasts are: Scenario means What happened means Reflog solution. Deleted a branch by mistake means git branch -D feature/x means Find the last commit SHA from reflog → recreate branch. git reset --hard lost commits means Moved HEAD to older commit means Find the SHA before the reset → reset back to it.

      +

      Jamie: How should a learner choose a tool without feeling judged by the choice?

      +

      Alex: The reason Example commands matters is that the agent can draft a reply. That gives the learner a simple foothold: you review the tone against the Culture & Etiquette guide before posting.

      +

      Jamie: What should happen before anyone copies and runs it?

      +

      Alex: Start with Output example. There is something to understand, something to try, and something that proves the try worked.

      +

      Alex: Treat examples as spoken recipes, not decorations. You may hear something like Open Issues Labeled "good-first-issue"; High Priority; - 45 [accessibility-agents] Add NVDA-specific navigation tips (3 comments, opened 5 days ago); - Priority Score: 8/10 (high community interest, clear scope, no assignee); - Recommended for: First-time. Read the command, understand what it changes, then run it only when the repository state matches the lesson.

      +

      Jamie: Let's pause on Agent 3: @pr-review - Pull Request Review. What should a learner take away from it?

      +

      Alex: Here is the plain-English version of Agent 3: @pr-review - Pull Request Review. File.github/agents/pr-review.agent.md. Put another way, before you run this agent: You should have manually reviewed at least one pull request diff in the GitHub browser interface - navigating the Files Changed tab with your screen reader, reading added and removed lines, leaving at least one inline comment, and.

      -

      Jamie: Let's pause on Reading the Reflog in VS Code Terminal. What should a learner take away from it?

      -

      Alex: Keep the learner anchored in Reading the Reflog in VS Code Terminal. Run this in the integrated terminal (Ctrl+Backtick). This is the part to say slowly: The output is plain text - read line by line with ↓.

      -

      Alex: Treat examples as spoken recipes, not decorations. You may hear something like git reflog. Read the command, understand what it changes, then run it only when the repository state matches the lesson.

      -

      Jamie: Let's pause on If you need to restore a commit that has been lost. What should a learner take away from it?

      -

      Alex: The reason If you need to restore a commit that has been lost matters is that 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.

      -

      Alex: Treat examples as spoken recipes, not decorations. You may hear something like 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. Read the command, understand what it changes, then run it only when the repository state matches the lesson.

      -

      Jamie: Let's pause on Recovering a Deleted Branch. What should a learner take away from it?

      -

      Alex: Start with Recovering a Deleted Branch. There is something to understand, something to try, and something that proves the try worked.

      -

      Alex: Treat examples as spoken recipes, not decorations. You may hear something like 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. Read the command, understand what it changes, then run it only when the repository state matches the lesson.

      +

      Alex: Keep the teaching thread moving. This is where What it does becomes real: generates full review documents for pull requests. The workshop is closer to rehearsal than lecture. You hear the move, try the move, and then check what changed.

      +

      Alex: The practical takeaway is this. Line-numbered diffs with change maps. Risk assessment (what could break, what is high-impact). Before-and-after snapshots. CI results and test coverage information. Suggested inline review comments with line number references.

      +

      Jamie: How do we make tool choice feel like access, not pressure?

      +

      Alex: Keep the learner anchored in Example commands. Critical rule: Read the agent's review. This is the part to say slowly: The agent produces a starting point - it does not know the project's history, the contributor's background, or the community's implicit standards the way you do.

      +

      Jamie: How do you keep commands from becoming magic words?

      +

      Alex: Treat examples as spoken recipes, not decorations. You may hear something like PR Review: 14 - Improve screen reader navigation guide; Summary; This PR adds 3 new sections to the screen reader navigation guide and updates 2 existing sections with NVDA-specific keyboard shortcuts.; Files Changed: 1; Lines Added: 127; Lines Removed: 18. Read the command, understand what it changes, then run it only when the repository state matches the lesson.

      -

      Jamie: Let's pause on Why Reflog Is Local-Only. What should a learner take away from it?

      -

      Alex: Here is the plain-English version of Why Reflog Is Local-Only. Reflog records are stored in your local.git/ directory and are not pushed to GitHub. Put another way, 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.

      -

      Alex: Keep the teaching thread moving. Start with Learning Cards: Emergency Recovery. There is something to understand, something to try, and something that proves the try worked.

      -

      Alex: The practical takeaway is this. 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. 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.

      -

      Jamie: Let's pause on 11. Alternative Git Interfaces. What should a learner take away from it?

      -

      Alex: Keep the learner anchored in 11. Alternative Git Interfaces. VS Code's Source Control panel is one way to use Git. This is the part to say slowly: These alternatives exist for different workflows.

      +

      Jamie: Let's pause on Agent 4: @analytics - Team Analytics. What should a learner take away from it?

      +

      Alex: Start with Agent 4: @analytics - Team Analytics: File.github/agents/analytics.agent.md. The next useful detail is this: Before you run this agent: You should have explored the Insights tab of at least one repository - looked at the contribution graph, understood what commit frequency means, and thought about what "high-churn files" implies for a project's stability.

      +

      Alex: Keep the teaching thread moving. Here is the plain-English version of What it does. Surfaces team contribution patterns, velocity metrics, and bottleneck detection. It is like learning a transit route. The names of the stops matter because they tell you whether you are still going the right direction.

      +

      Alex: The practical takeaway is this. Contribution velocity over time. Review turnaround time by reviewer. Code hotspot detection (files with the most churn). Workload distribution across contributors.

      +

      Jamie: What stays the same when the tool changes?

      +

      Alex: This is where Example commands becomes real: accessibility use case: After Day 2's contribution wave, run @analytics team velocity in accessibility-agents today to see the hackathon's collective output. That matters in practice: A moment of real-time team celebration.

      -

      Alex: Keep the teaching thread moving. Start with GitHub Desktop. There is something to understand, something to try, and something that proves the try worked.

      -

      Alex: The practical takeaway is this. Graphical Git client. Download: 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.

      -

      Jamie: Let's pause on GitHub CLI (gh). What should a learner take away from it?

      -

      Alex: Start with GitHub CLI (gh). There is something to understand, something to try, and something that proves the try worked.

      -

      Alex: The practical takeaway is this. 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).

      -

      Jamie: Let's pause on Common commands. What should a learner take away from it?

      -

      Alex: Here is the plain-English version of Common commands. See Culture & Etiquette for more gh examples.

      -

      Alex: Treat examples as spoken recipes, not decorations. You may hear something like 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. Read the command, understand what it changes, then run it only when the repository state matches the lesson.

      +

      Alex: Keep the teaching thread moving. Keep the learner anchored in Agent 5: @insiders-a11y-tracker - Accessibility Change Monitoring. File.github/agents/insiders-a11y-tracker.agent.md. This is the part to say slowly: Before you run this agent: You should have filed at least one accessibility bug report using the workshop's issue template, applied a WCAG label to an issue, and manually reviewed a Markdown file for heading hierarchy - knowing what H1 means, what H2 means,.

      +

      Jamie: Before we leave What it does, what is the practical point?

      +

      Alex: The reason What it does matters is that monitors accessibility-sensitive changes across configured repositories.

      +

      Alex: The practical takeaway is this. WCAG/ARIA cross-referenced change tracking. Flags changes to keyboard navigation, ARIA attributes, focus management, color usage. Monitors for heading hierarchy violations in Markdown. Tracks link text quality (flags bare URLs, non-descriptive labels).

      +

      Alex: Keep the teaching thread moving. Start with Example commands: Day 2 workflow: Run this before submitting any PR. The next useful detail is this: If the agent flags an issue, fix it before requesting review - not after. Think of it like entering a new building: first you find the lobby, then the room, then the door you actually need.

      -

      Jamie: Let's pause on Git CLI (Terminal). What should a learner take away from it?

      -

      Alex: Start with Git CLI (Terminal). There is something to understand, something to try, and something that proves the try worked.

      -

      Alex: The practical takeaway is this. The standard Git command-line interface. Included with VS Code (integrated terminal: Ctrl+Backtick).

      -

      Jamie: Before we leave Common commands, what is the practical point?

      -

      Alex: Keep the learner anchored in Common commands. Terminal output is plain text - more predictable than GUI elements for some operations. A good GitHub workflow is like a well-run meeting: everyone knows the topic, the next action, and who has the floor.

      -

      Alex: Treat examples as spoken recipes, not decorations. You may hear something like 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. Read the command, understand what it changes, then run it only when the repository state matches the lesson.

      -

      Jamie: Let's pause on Try It: Clone, Branch, Commit. What should a learner take away from it?

      -

      Alex: The reason Try It: Clone, Branch, Commit matters is that time: 5 minutes What you need: VS Code with Git configured. That gives the learner a simple foothold: do the complete Git workflow once, start to finish.

      -

      Alex: First, 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. Then, 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. After that, 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. Finally, stage - Press Ctrl+Shift+G to open Source Control. Navigate to your changed file and press Enter to stage it (or use the + button). The rhythm is simple: orient, act, verify, then continue.

      -

      Jamie: Before we leave Try It: Clone, Branch, Commit, what is the practical point?

      -

      Alex: First, commit - Tab to the message input, type feat: add new thinking phrase, press Ctrl+Enter. Then, push - Press Ctrl+Shift+P → Git: Push. Think of it as a rail line: each stop confirms you are still on the right route before the next one.

      +

      Jamie: Let's pause on Agent 6: @template-builder - Interactive Issue Template Wizard. What should a learner take away from it?

      +

      Alex: Here is the plain-English version of Agent 6: @template-builder - Interactive Issue Template Wizard. File.github/agents/template-builder.agent.md. Put another way, before you run this agent: You should have read Issue Templates thoroughly - understanding YAML field types, creating a template manually (Exercise B), and designing your own template (Exercise D).

      +

      Alex: Keep the teaching thread moving. This is where What it does becomes real: an interactive wizard that guides you through building GitHub issue templates step-by-step using VS Code's Ask Questions feature. That matters in practice: Instead of writing YAML syntax, answer simple questions and the agent generates production-ready templates.

      +

      Jamie: What is the common workflow underneath the different interfaces?

      +

      Alex: Keep the learner anchored in Example commands. Manual YAML template creation takes 15-20 minutes and is error-prone. This is the part to say slowly: The Template Builder generates correct, tested templates in 2-3 minutes via guided questions.

      -

      Jamie: What is the final checkpoint?

      -

      Alex: You should be able to point to the evidence, explain the action, and describe what you would do next if this were a real open source project. If you can teach the move back, you have learned it.

      -

      Jamie: And if they get stuck?

      -

      Alex: Read the latest message, not the loudest worry. Check the issue, the branch, the pull request, the status check, or the bot comment. Then ask for help with those facts in hand. That is how professionals collaborate.

      -
      - +

      Alex: Keep the teaching thread moving. The reason 5. Slash Commands and Prompts matters is that the repository includes 54+ slash commands defined as.prompt.md files in.github/prompts/. That gives the learner a simple foothold: type / in Copilot Chat to see the full command menu. The interface gets friendlier when it stops being a wall of controls and starts being a set of named places.

      +

      Jamie: How should they picture the shape of the workshop?

      +

      Alex: Start with Workshop Slash Command Quick Reference: The commands listed below are the ones most relevant to this workshop. The next useful detail is this: The full repository contains 54+ commands covering accessibility auditing, document scanning, framework-specific checks, and more.

      +

      Alex: Keep the teaching thread moving. Here is the plain-English version of Reading Slash Command Definitions. Each /command corresponds to a.prompt.md file in.github/prompts/. Put another way, open any of them in VS Code to read what instructions it gives Copilot.

      -

      Challenge 11: Open a Day 2 PR

      -

      Opening a pull request from a locally pushed branch and reading it in VS Code.

      -
      -Read Transcript - Challenge 11: Open a Day 2 PR - -

      Transcript

      -

      Alex: You are listening to Challenge Coach: Open a Day 2 PR. I am Alex, and this is the calm walkthrough before the hands-on work.

      -

      Jamie: And I am Jamie. I will make sure we teach the skill instead of just reading the checklist aloud.

      +

      Jamie: Let's pause on Example: /a11y-update. What should a learner take away from it?

      +

      Alex: This is where Example: /a11y-update becomes real: file.github/prompts/a11y-update.prompt.md. That matters in practice: This is how you learn to write your own.

      +

      Alex: Keep the teaching thread moving. Start with Learning Cards: Slash Commands and Prompts. There is something to understand, something to try, and something that proves the try worked.

      +

      Alex: The practical takeaway is this. Type / in Copilot Chat to see all available slash commands -- your screen reader announces each command name as you arrow through the list. Slash commands are defined in.github/prompts/ as.prompt.md files -- open them in the Explorer to read what each command does before using it. Create your own command by copying an existing.prompt.md file, renaming it, and editing the instructions -- no code required. The / command menu appears as a dropdown list in Copilot Chat -- it scales with VS Code's font and zoom settings. Each command has a short description visible in the dropdown; use Ctrl+= to zoom if the text is too small. Open the.prompt.md file in the editor to read the full command definition at your preferred zoom level.

      +

      Jamie: Let's pause on 6. Contributing to the Ecosystem. What should a learner take away from it?

      +

      Alex: The reason 6. Contributing to the Ecosystem matters is that the 55 Accessibility Agents and 54+ slash commands are starting points. That gives the learner a simple foothold: the.agent.md format is open - you can create your own agents for any repeatable workflow, and contribute them back to the project.

      -

      Alex: The focus is Opening a pull request from a locally pushed branch and reading it in VS Code. We will explain the concept, the action, the evidence, and the most common recovery path.

      -

      Jamie: So the learner needs the why, the move, and the checkpoint all in the same mental pocket.

      -

      Alex: That is the teaching shape: understand the concept, do the smallest real action, then verify the result before moving on.

      +

      Alex: Keep the teaching thread moving. Start with Two Types of Custom Agents: Informational agents - conversational; search, analyze, and present results. The next useful detail is this: Task-oriented agents - active; edit files, run commands, submit PRs.

      +

      Alex: The practical takeaway is this. Perform GitHub searches with predefined scopes and filters. Present results in specific structured formats. Query GitHub API tools to answer questions. Execute external tools (linters, test suites, axe-core).

      +

      Jamie: Let's pause on Agent File Structure. What should a learner take away from it?

      +

      Alex: Here is the plain-English version of Agent File Structure. See also: Appendix L: Agents Reference has the complete agent.md format specification and examples. Put another way, every.agent.md file has two parts: YAML frontmatter (metadata) and a system prompt (markdown body).

      +

      Alex: Keep the teaching thread moving. This is where Frontmatter fields becomes real: restricting tool access is a security best practice - only grant what the agent actually needs. The workshop is closer to rehearsal than lecture. You hear the move, try the move, and then check what changed.

      -

      Jamie: How should they picture the shape of the workshop?

      -

      Alex: Start with Challenge 11: Open a Day 2 PR: What you will do: Open a pull request from the branch you pushed in Challenge 10. The next useful detail is this: Notice that the workflow is the same as Day 1 -- the only difference is where the commits came from.

      -

      Alex: A solid pull request habit is to separate three questions: what changed, why it changed, and what still needs review. That keeps the conversation useful instead of noisy.

      -

      Jamie: How would you walk the room through that step by step?

      -

      Alex: Start with Instructions. There is something to understand, something to try, and something that proves the try worked.

      -

      Alex: First, go to the learning-room repository on GitHub.com. Then, you may see a banner saying your branch had recent pushes -- select Compare & pull request if it appears. After that, or go to Pull requests New pull request, set base to main and compare to fix/YOUR-USERNAME. Finally, write a clear PR title and description. Treat it like a recipe: do not add the next ingredient until the previous one is actually in the bowl.

      -

      Jamie: What does the learner do first, second, and then after that?

      -

      Alex: First, include Closes XX if this PR addresses an existing issue. Then, submit the pull request. It is a checklist, but a meaningful one: every item creates evidence that the next step is safe.

      -

      Jamie: What is the one idea that makes the next few steps less mysterious?

      -

      Alex: This is where The pattern is the same becomes real: the pull request step is identical. That matters in practice: The only change is where you made the edits.

      -

      Alex: That shows up in the workshop in a few specific ways. Day 1: Edit on GitHub.com commit open PR. Day 2: Edit locally commit push open PR.

      +

      Jamie: Let's pause on Example: Informational Agent - @insiders-a11y-tracker. What should a learner take away from it?

      +

      Alex: Keep the learner anchored in Example: Informational Agent - @insiders-a11y-tracker. This agent monitors VS Code Insiders releases for accessibility improvements. This is the part to say slowly: It searches the microsoft/vscode repository using predefined GitHub query syntax, so you never have to remember the exact filter parameters.

      +

      Jamie: Let's pause on Use it. What should a learner take away from it?

      +

      Alex: The reason Use it matters is that prerequisite: GitHub MCP server installed (github.com/github/github-mcp-server).

      +

      Alex: First, select @insiders-a11y-tracker from the agent picker. Then, ask: what shipped this month? or any keyboard navigation improvements in January? After that, the agent searches with repo:microsoft/vscode is:closed milestone:"[Month] [Year]" label:accessibility label:insiders-released and returns formatted results. The rhythm is simple: orient, act, verify, then continue.

      +

      Jamie: Let's pause on Example: Task-Oriented Agent - The Markdown Accessibility Assistant. What should a learner take away from it?

      +

      Alex: Start with Example: Task-Oriented Agent - The Markdown Accessibility Assistant: The GitHub Accessibility team published a complete walkthrough for building a Markdown Accessibility Assistant - a task-oriented agent that reviews Markdown files for accessibility issues and makes direct fixes. The next useful detail is this: This agent is the automated version of the accessibility review skills you built during Day 1.

      +

      Alex: The practical takeaway is this. Runs markdownlint-cli2 to catch structural problems (heading skips, bare URLs, missing blank lines). Reviews link text for descriptiveness. Flags missing or inadequate alt text and waits for your approval before changing it (alt text requires human judgment). Fixes heading hierarchy, list structure, and bare URL formatting directly.

      -

      Alex: Now bring the learner back to the room. Keep the learner anchored in Peer simulation check. Review the peer-simulation PR title and description. This is the part to say slowly: If you have real buddy access, review your buddy's PR too.

      -

      Jamie: What would you say to someone who is already bracing for this to be too much?

      -

      Alex: Start with Example PR. There is something to understand, something to try, and something that proves the try worked.

      -

      Alex: That matters because of the next idea. Start with What matters: The learning objective is recognizing the similarities and differences between web-based and local Git workflows. The next useful detail is this: If you created a PR from a locally-pushed branch and noted what changed compared to Day 1, you completed this challenge. Think of it like entering a new building: first you find the lobby, then the room, then the door you actually need.

      -

      Alex: The useful habit is simple: orient first, act second, verify third. That pause before acting is part of the work.

      +

      Alex: Keep the teaching thread moving. Here is the plain-English version of Key Pattern: Tiered Decision-Making. This tiered approach - automate what can be objectively evaluated, flag what needs human judgment - is the right model for any accessibility agent. Put another way, it maximizes the agent's value while keeping humans in control of decisions that require context. It is like learning a transit route. The names of the stops matter because they tell you whether you are still going the right direction.

      +

      Jamie: Let's pause on Required Prerequisites for the Markdown Accessibility Assistant. What should a learner take away from it?

      +

      Alex: Start with Required Prerequisites for the Markdown Accessibility Assistant. There is something to understand, something to try, and something that proves the try worked.

      +

      Alex: The practical takeaway is this. GitHub MCP server installed and configured (github.com/github/github-mcp-server). Node.js installed (for npx markdownlint-cli2).

      +

      Jamie: Let's pause on From VS Code. What should a learner take away from it?

      +

      Alex: Start with From VS Code. There is something to understand, something to try, and something that proves the try worked.

      +

      Alex: First, open Copilot Chat (Ctrl+Shift+I / Cmd+Shift+I on macOS). Then, in the Chat input toolbar, select the Set Agent button. After that, select your custom agent from the agent picker. Finally, type your request - the agent executes in your local workspace. It is like walking a hallway with named doors: read the sign, enter the right room, then confirm where you landed.

      -

      Jamie: Okay, set the room for us. What are we walking into?

      -

      Alex: Here is the plain-English version of 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. Put another way, prerequisites: VS Code Setup & Accessibility Basics, Working with Pull Requests, Merge Conflicts Mac keyboard shortcuts: Throughout this chapter, all Ctrl+ shortcuts use Cmd+ on Mac, and Alt+ shortcuts use Option+.

      -

      Alex: A solid Git habit is to know which branch you are on, what changed, and what confirmation you expect before you run the next command.

      -

      Alex: This is where the talk moves from concept to action. This is where Workshop Recommendation (Chapter 14 / Challenge 10) becomes real: chapter 14 is the first local Git workflow chapter with hands-on repository management. That matters in practice: It supports Challenge 10: Go Local.

      -

      Alex: The room should hear these as checkpoints. There are 3. Each challenge should take under 10 minutes each. The evidence is PR metadata, branch names, and committed changes. The pattern is clone, branch, edit, commit, push, PR.

      -

      Jamie: Turn that into a path someone can follow.

      -

      Alex: Start with Challenge 10 Practice Set. There is something to understand, something to try, and something that proves the try worked.

      -

      Alex: First, clone your Learning Room repository - clone your private Learning Room repo to your local machine using VS Code. Then, 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. After that, 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. It is like walking a hallway with named doors: read the sign, enter the right room, then confirm where you landed.

      -
      -

      Jamie: What is the ordered workflow?

      -

      Alex: The reason Practice 10.1 Step-by-Step: Clone Your Learning Room Repository matters is that get a local copy of your Learning Room repository on your machine using VS Code. That gives the learner a simple foothold: VS Code desktop (or github.dev if you cannot install desktop VS Code). The interface gets friendlier when it stops being a wall of controls and starts being a set of named places.

      -

      Alex: First, open VS Code. If no folder is open, you should see the Welcome tab. Then, open the Command Palette: Ctrl+Shift+P (Mac: Cmd+Shift+P). After that, type git clone and select Git: Clone. Finally, VS Code asks for a repository URL. Paste your Learning Room repo URL (it looks like https://github.com/the workshop organization/learning-room-your username.git). You can copy this from the green Code button on your repo's GitHub page. The rhythm is simple: orient, act, verify, then continue.

      -

      Jamie: Give me the sequence, because order matters here.

      -

      Alex: First, press Enter. Then, 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. After that, VS Code clones the repository. When it finishes, a notification appears asking "Would you like to open the cloned repository?" Activate Open. Finally, 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. Think of it as a rail line: each stop confirms you are still on the right route before the next one.

      -

      Jamie: Let's pause on Practice 10.2 Step-by-Step: Create a Branch and Commit. What should a learner take away from it?

      -

      Alex: Start with Practice 10.2 Step-by-Step: Create a Branch and Commit: See also: Chapter 13: How Git Works explains the three areas (working directory, staging, repository) that make commits meaningful. The next useful detail is this: Check out (or create) a properly named branch, edit a file, stage the change, and commit with a clear message.

      -

      Alex: First, open the Command Palette: Ctrl+Shift+P (Mac: Cmd+Shift+P). Then, 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/your username. If the branch does not exist yet, type git create branch and select Git: Create Branch. After that, 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. Finally, 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). Think of it as a rail line: each stop confirms you are still on the right route before the next one.

      -

      Jamie: Before we leave Practice 10.2 Step-by-Step: Create a Branch and Commit, what is the practical point?

      -

      Alex: First, 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). Then, 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.". After that, 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.". Finally, 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. Treat it like a recipe: do not add the next ingredient until the previous one is actually in the bowl.

      -

      Jamie: Let's pause on Practice 10.3 Step-by-Step: Push and Open a Linked PR. What should a learner take away from it?

      -

      Alex: Here is the plain-English version of Practice 10.3 Step-by-Step: Push and Open a Linked PR. Push your branch to GitHub and open a PR in your Learning Room repo that references your challenge issue. Put another way, VS Code (for the push) and GitHub.com (for the PR).

      -

      Alex: First, open the Command Palette: Ctrl+Shift+P (Mac: Cmd+Shift+P). Then, 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. After that, 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. Finally, open your browser and navigate to your Learning Room repository on GitHub. Treat it like a recipe: do not add the next ingredient until the previous one is actually in the bowl.

      -

      Jamie: Before we leave Practice 10.3 Step-by-Step: Push and Open a Linked PR, what is the practical point?

      -

      Alex: First, GitHub usually shows a yellow banner: "yourname recently pushed to learn/yourname." Activate the Compare & pull request button in that banner. Then, 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/your username branch. After that, in the PR title, write a descriptive title (for example: "docs: improve welcome.md introduction"). Finally, 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. It is a checklist, but a meaningful one: every item creates evidence that the next step is safe.

      +

      Jamie: Let's pause on From GitHub.com (Task mode). What should a learner take away from it?

      +

      Alex: Start with From GitHub.com (Task mode). There is something to understand, something to try, and something that proves the try worked.

      +

      Alex: First, open Copilot Chat on GitHub.com. Then, select Task from the mode picker. After that, optionally select a custom agent from the agent picker. Finally, submit your request - the agent can create a PR automatically. The rhythm is simple: orient, act, verify, then continue.

      +

      Jamie: Let's pause on From an issue (Issue Assignment). What should a learner take away from it?

      +

      Alex: Start with From an issue (Issue Assignment). There is something to understand, something to try, and something that proves the try worked.

      +

      Alex: First, open any issue → Assignees → assign Copilot. Then, in the dialog, optionally select a custom agent. After that, select Assign - Copilot creates a branch, makes changes, and opens a PR. Think of it as a rail line: each stop confirms you are still on the right route before the next one.

      +

      Jamie: What is the pre-flight check here?

      +

      Alex: Here is the plain-English version of Environment Setup for GitHub (Cloud Agents). When agents run on GitHub (not locally), they may need additional tools. Put another way, create a workflow file at.github/workflows/copilot-setup-steps.yml with a single job named copilot-setup-steps.

      +

      Jamie: Let's pause on To Create Your Own Agent. What should a learner take away from it?

      +

      Alex: Start with To Create Your Own Agent. There is something to understand, something to try, and something that proves the try worked.

      +

      Alex: First, create.github/agents/your-agent-name.agent.md. Then, write YAML frontmatter (name, description, tools). After that, write the system prompt - identity, capabilities, domain knowledge, behavioral rules, output format. Finally, save and reload VS Code (Ctrl+Shift+P → "Reload Window"). It is a checklist, but a meaningful one: every item creates evidence that the next step is safe.

      +

      Jamie: Before we leave To Create Your Own Agent, what is the practical point?

      +

      Alex: First, type @your-agent-name in Copilot Chat. It is like walking a hallway with named doors: read the sign, enter the right room, then confirm where you landed.

      Jamie: What makes this practice feel low-stakes but still real?

      -

      Alex: This is where Completing Challenge 10: Submit Your Evidence becomes real: open your assigned Challenge 10 issue in your Learning Room repo and post a completion comment. That matters in practice: Close your Challenge 10 issue when your branch is pushed and the PR is open.

      -

      Alex: That connects to another useful point. Start with Expected Outcomes. There is something to understand, something to try, and something that proves the try worked.

      -

      Alex: For a learner, the useful signals are these. 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.

      -

      Jamie: Let's pause on If You Get Stuck. What should a learner take away from it?

      -

      Alex: The reason If You Get Stuck matters is that continue learning: The GitHub Skills course Introduction to Git walks through commits, branches, and merges in an interactive, self-paced format. That gives the learner a simple foothold: see Appendix Z for the full catalog.

      -

      Alex: First, command Palette does not open? Confirm you are in VS Code (not the browser) and press Ctrl+Shift+P (Mac: Cmd+Shift+P). Then, source Control panel is empty? You may not have saved your file yet. Press Ctrl+S to save, then check again. After that, 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. Finally, branch name wrong? Open Command Palette, run Git: Rename Branch. to fix it before pushing. The rhythm is simple: orient, act, verify, then continue.

      -

      Jamie: Before we leave If You Get Stuck, what is the practical point?

      -

      Alex: First, cannot find the "Compare & pull request" banner on GitHub? Navigate to Pull requests tab and create the PR manually (step 6 above). Then, 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. After that, ask facilitator to verify your clone location, branch name, and help with one push. Finally, finished but not sure you did it right? Compare your work against the Challenge 10 reference solution. Think of it as a rail line: each stop confirms you are still on the right route before the next one.

      +

      Alex: Keep the learner anchored in Exercise: Extend the Template Builder Agent. You've built templates manually (Chapters 15-16) and seen them in action. This is the part to say slowly: Now see how to harness AI to generate templates interactively, and learn to customize agents for your own projects.

      +

      Alex: The practical takeaway is this. Complete Chapters 15-16 (especially Exercise D - designing your own template). VS Code is installed and GitHub Copilot is active. You have forked accessibility-agents to your GitHub account. You have cloned your fork locally: git clone https://github.com/[your-username]/accessibility-agents.git.

      +

      Jamie: Let's pause on Exercise 1: Generate a Template with the Agent. What should a learner take away from it?

      +

      Alex: The reason Exercise 1: Generate a Template with the Agent matters is that your Mission: Use the @template-builder agent to generate an accessibility bug report template interactively. That gives the learner a simple foothold: you'll experience the agent as an end-user and see what production-ready agent output looks like. The interface gets friendlier when it stops being a wall of controls and starts being a set of named places.

      +

      Alex: The practical takeaway is this. Left sidebar showing.github/, docs/, learning-room/, README.md, etc. The status bar at the bottom shows your current git branch (probably main). Alternative: Use menu: View → Copilot Chat. Copilot is now ready to receive instructions.

      +

      Alex: First, open VS Code. Then, file → Open Folder → select your locally cloned accessibility-agents folder. After that, the folder tree appears on the left showing the repository structure. Finally, verify you're in the right place: The folder name should be accessibility-agents at the top of the sidebar. The rhythm is simple: orient, act, verify, then continue.

      +

      Jamie: Before we leave Exercise 1: Generate a Template with the Agent, what is the practical point?

      +

      Alex: First, keyboard shortcut: Press Ctrl+Shift+I (Windows/Linux) or Cmd+Shift+I (macOS). Then, a chat panel opens on the right side of VS Code. After that, at the top, you see "Copilot Chat" and probably a text input at the bottom saying "Ask Copilot.". Finally, click in the chat input box (bottom of Copilot Chat panel). Think of it as a rail line: each stop confirms you are still on the right route before the next one.

      +

      Alex: Treat examples as spoken recipes, not decorations. You may hear something like Q: Template name?; A: Accessibility Bug Report; Q: What's it for?; A: Report screen reader and keyboard navigation issues; Q: First field name?; A: Screen Reader; Q: Field type?; A: dropdown; Q: Dropdown options? (comma-separated); A: NVDA, JAWS, VoiceOver,. Read the command, understand what it changes, then run it only when the repository state matches the lesson.

      -

      Alex: Here is the practical turn. Start with Learning Moment: Local Git operations give you full control and immediate feedback. The next useful detail is this: You can see your changes, review them, and fix mistakes before they reach GitHub.

      -

      Jamie: Let's pause on Learning Pattern Used in This Chapter. What should a learner take away from it?

      -

      Alex: Start with Learning Pattern Used in This Chapter. There is something to understand, something to try, and something that proves the try worked.

      -

      Alex: First, clone once to get a local copy of the project. Then, branch before editing (never work directly on main). After that, make small, focused edits with clear commit messages. Finally, push and open a PR that links to an issue for traceability. Treat it like a recipe: do not add the next ingredient until the previous one is actually in the bowl.

      -

      Jamie: Before we leave Learning Pattern Used in This Chapter, what is the practical point?

      -

      Alex: First, verify each step before moving to the next. It is a checklist, but a meaningful one: every item creates evidence that the next step is safe.

      -

      Alex: Keep the thread going. This is where About Learning Cards becomes real: throughout this chapter, each major operation includes learning cards - expandable sections showing how to accomplish the same task from multiple perspectives. That matters in practice: Open the card that matches how you work. The workshop is closer to rehearsal than lecture. You hear the move, try the move, and then check what changed.

      +

      Jamie: Let's pause on Exercise 2: Extend the Agent for Your Project. What should a learner take away from it?

      +

      Alex: Start with Exercise 2: Extend the Agent for Your Project: Your Mission: Customize the Template Builder agent to recognize and guide a Security Vulnerability Report template. The next useful detail is this: This teaches you how to tailor agents for project-specific needs.

      +

      Alex: The practical takeaway is this. The file starts with YAML frontmatter (name, description, topics). Below that, sections like " How to Use", " Pre-Built Workflow". Search for the text "Pre-Built Workflow: Guided Accessibility Template".

      +

      Alex: First, in VS Code, navigate to.github/agents/. Then, file: template-builder.agent.md. After that, double-click to open it in the editor. Finally, you see the agent's instructions in Markdown format. Think of it as a rail line: each stop confirms you are still on the right route before the next one.

      +

      Jamie: Before we leave Exercise 2: Extend the Agent for Your Project, what is the practical point?

      +

      Alex: First, use Ctrl+F to open Find. Then, search for: Pre-Built Workflow. After that, press Enter to jump to the first match. Finally, you should land on the "Pre-Built Workflow: Guided Accessibility Template" section. Treat it like a recipe: do not add the next ingredient until the previous one is actually in the bowl.

      +

      Jamie: Let's pause on What you're adding. What should a learner take away from it?

      +

      Alex: Here is the plain-English version of What you're adding. If the agent doesn't recognize your new workflow.

      +

      Alex: The practical takeaway is this. A clear label for the new workflow. Instructions on how to invoke it. Pre-defined fields that make sense for security reports. Specific options for severity and vulnerability type. The agent recognizes your new workflow. Next time you invoke @template-builder with "create security template", it will follow your new guidance.

      +

      Alex: First, save the file: Ctrl+S. Then, you should see no error messages. After that, the agent file now includes your new Pre-Built Workflow. Finally, open Copilot Chat again: Ctrl+Shift+I. Treat it like a recipe: do not add the next ingredient until the previous one is actually in the bowl.

      +

      Jamie: Before we leave What you're adding, what is the practical point?

      +

      Alex: First, press Enter. Then, the agent should now ask vulnerability-specific questions. After that, commit your agent change. Finally, the extended agent is now in your fork. It is a checklist, but a meaningful one: every item creates evidence that the next step is safe.

      +

      Alex: Treat examples as spoken recipes, not decorations. You may hear something like git add.github/agents/template-builder.agent.md; git commit -m "feat: add security vulnerability template workflow to template-builder agent"; git push origin main. Read the command, understand what it changes, then run it only when the repository state matches the lesson.

      +

      Jamie: Let's pause on Exercise 3: Iterative Refinement with Agents. What should a learner take away from it?

      +

      Alex: This is where Exercise 3: Iterative Refinement with Agents becomes real: your Mission: Generate a template, then ask the agent to modify it incrementally. That matters in practice: This teaches you the iterative pattern that scales to all agent-assisted workflows.

      +

      Alex: The practical takeaway is this. Running a complete template generation (same as Exercise 1). The agent modifies the YAML it generated. The new checkbox appears in the YAML with proper formatting and indentation. It doesn't regenerate from scratch - just adds your change.

      +

      Alex: First, in Copilot Chat, type: @template-builder create a feature request template. Then, answer the agent's questions to build a feature request form. After that, let the agent generate the YAML. Finally, copy it to a file.github/ISSUE TEMPLATE/feature-request.yml. It is a checklist, but a meaningful one: every item creates evidence that the next step is safe.

      +

      Jamie: Before we leave Exercise 3: Iterative Refinement with Agents, what is the practical point?

      +

      Alex: First, once the template is generated, while still in the same chat conversation, ask. Then, the agent regenerates the YAML with your new checkbox added in the right place (usually as required field pre-validation). After that, follow up. Finally, the agent modifies the textarea field's attributes to enable code highlighting. It is like walking a hallway with named doors: read the sign, enter the right room, then confirm where you landed.

      -

      Jamie: Let's pause on Tool Cards: Clone a Repository (Day 2). What should a learner take away from it?

      -

      Alex: Keep the learner anchored in Tool Cards: Clone a Repository (Day 2). VS Code Desktop (primary for Day 2). This is the part to say slowly: github.dev (web editor): No clone needed.

      -

      Alex: First, ctrl+Shift+P Git: Clone paste the HTTPS URL choose a folder Open. Then, file Clone Repository paste URL or select from your account Clone. It is like walking a hallway with named doors: read the sign, enter the right room, then confirm where you landed.

      -

      Alex: Treat examples as spoken recipes, not decorations. You may hear something like git clone https://github.com/owner/repo.git && cd repo. gh repo clone owner/repo && cd repo. Read the command, understand what it changes, then run it only when the repository state matches the lesson.

      -

      Jamie: Let's pause on Method 1: Command Palette (Recommended for Screen Readers). What should a learner take away from it?

      -

      Alex: Start with Method 1: Command Palette (Recommended for Screen Readers). There is something to understand, something to try, and something that proves the try worked.

      -

      Alex: First, open Command Palette: Ctrl+Shift+P (Mac: Cmd+Shift+P). Then, type "git clone". After that, select "Git: Clone". Finally, paste the repository URL (example: https://github.com/community-access/accessibility-agents.git). The rhythm is simple: orient, act, verify, then continue.

      -

      Jamie: Before we leave Method 1: Command Palette (Recommended for Screen Readers), what is the practical point?

      -

      Alex: First, press Enter. Then, choose a local folder where the repository should be cloned. After that, VS Code asks: "Would you like to open the cloned repository?" - select "Open". Think of it as a rail line: each stop confirms you are still on the right route before the next one.

      -

      Alex: A solid navigation habit is to prove where you are before activating controls. Headings, landmarks, and the address bar are not trivia; they are your map.

      -

      Jamie: Where do you want a learner to place their attention here?

      -

      Alex: Start with Screen reader navigation. There is something to understand, something to try, and something that proves the try worked.

      -

      Alex: A few details make that real. 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.

      +

      Jamie: Let's pause on What Comes Next. What should a learner take away from it?

      +

      Alex: Keep the learner anchored in What Comes Next. Your next step: explore the broader ecosystem. This is the part to say slowly: That is Accessibility Agents' promise: not to replace your thinking, but to amplify your skills across all 55 agents - and to grow through the contributions of everyone who uses it. A good GitHub workflow is like a well-run meeting: everyone knows the topic, the next action, and who has the floor.

      +

      Alex: The practical takeaway is this. Browse the full agent list - which agents solve problems you face regularly? Try an Accessibility team agent: @contrast-master check this page or @alt-text-headings review this file. Try a Developer Tools agent: @python-specialist review this module for accessibility or @desktop-a11y-specialist audit this dialog. Think about what is missing: what agent would you build if you could?

      +

      Alex: First, generated a template using an agent (Exercise 1). Then, customized an agent for your domain (Exercise 2). After that, refined iteratively with agent help (Exercise 3). It is like walking a hallway with named doors: read the sign, enter the right room, then confirm where you landed.

      +

      Jamie: Let's pause on Learning Cards: Contributing to the Ecosystem. What should a learner take away from it?

      +

      Alex: Start with Learning Cards: Contributing to the Ecosystem. There is something to understand, something to try, and something that proves the try worked.

      +

      Alex: The practical takeaway is this. Agent.agent.md files use YAML frontmatter at the top (between --- delimiters) followed by Markdown body; in VS Code, use Ctrl+G to jump to line 1 and arrow through the frontmatter fields (name, description, tools) before reading the body instructions. When writing your own.agent.md, use VS Code's Outline view (Ctrl+Shift+O) to verify that your Markdown headings (Purpose, Capabilities, Responsibilities) are correctly nested -- malformed headings will not appear in the outline. Before submitting a PR with a new agent file, run the file through a YAML linter (install the YAML extension, or use yamllint from the terminal) -- frontmatter syntax errors silently break agent registration. YAML frontmatter fields are densely packed with colons and quotes; increase your editor font size or use a monospaced font with wide character spacing so name:, description:, and tools: are clearly distinct. The.agent.md files in the agents/ directory follow a consistent structure -- use the file explorer's icon theme or file nesting feature to visually group agent files separately from regular documentation. When reviewing existing agents for contribution ideas, use VS Code's split editor to place the agent file and the README side by side so you can cross-reference the agent's instructions with its documented capabilities.

      +

      Alex: Keep the teaching thread moving. Start with 7. The Bigger Picture: Teams, Orchestration, and Beyond VS Code: The 55 agents are not 55 independent tools. The next useful detail is this: They are organized into three teams that work together, and several orchestrator agents exist specifically to coordinate multi-agent workflows.

      -

      Jamie: Let's pause on Method 2: Start Page Clone Button. What should a learner take away from it?

      -

      Alex: Here is the plain-English version of Method 2: Start Page Clone Button. The Start page is keyboard-accessible. Put another way, tab to navigate between "New File," "Open Folder," and "Clone Repository" buttons. It is like learning a transit route. The names of the stops matter because they tell you whether you are still going the right direction.

      -

      Alex: First, open VS Code (no folder open). Then, the Start page appears. After that, navigate to "Clone Git Repository" button - press Enter. Finally, paste repository URL → Enter. Treat it like a recipe: do not add the next ingredient until the previous one is actually in the bowl.

      -

      Jamie: Before we leave Method 2: Start Page Clone Button, what is the practical point?

      -

      Alex: First, choose destination folder. Then, open when prompted. It is a checklist, but a meaningful one: every item creates evidence that the next step is safe.

      -

      Jamie: Let's pause on Method 3: From GitHub.com. What should a learner take away from it?

      -

      Alex: Start with Method 3: From GitHub.com. There is something to understand, something to try, and something that proves the try worked.

      -

      Alex: First, on any GitHub repository page, click the green "Code" button. Then, copy the HTTPS URL (recommended) or SSH URL. After that, open VS Code → Ctrl+Shift+P (Mac: Cmd+Shift+P) → "Git: Clone". Finally, paste URL → Enter. It is a checklist, but a meaningful one: every item creates evidence that the next step is safe.

      -

      Jamie: Before we leave Method 3: From GitHub.com, what is the practical point?

      -

      Alex: First, choose destination → Open. It is like walking a hallway with named doors: read the sign, enter the right room, then confirm where you landed.

      -

      Jamie: Let's pause on Learning Cards: Cloning a Repository. What should a learner take away from it?

      -

      Alex: Keep the learner anchored in Learning Cards: Cloning a Repository. Low vision users (zoom, high contrast). This is the part to say slowly: Cloning works the same as the Command Palette method above.

      -

      Alex: First, 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. Then, 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. After that, 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. Finally, 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. It is like walking a hallway with named doors: read the sign, enter the right room, then confirm where you landed.

      -

      Jamie: Before we leave Learning Cards: Cloning a Repository, what is the practical point?

      -

      Alex: First, navigate to the repository on GitHub.com. Then, press. (period) to open github.dev - a browser-based VS Code editor. After that, the full repository opens in an editor with file tree, search, and editing. Finally, changes are committed directly to GitHub from the browser. The rhythm is simple: orient, act, verify, then continue.

      -

      Alex: Treat examples as spoken recipes, not decorations. You may hear something like 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. Read the command, understand what it changes, then run it only when the repository state matches the lesson.

      +

      Jamie: Let's pause on How the Three Teams Connect. What should a learner take away from it?

      +

      Alex: Here is the plain-English version of How the Three Teams Connect. In practice, a single task often spans multiple teams. Put another way, no single agent covers the entire workflow.

      +

      Alex: The practical takeaway is this. You ask @daily-briefing (GitHub Workflow) for your morning report. It flags a PR that changes ARIA attributes. You ask @pr-review (GitHub Workflow) to generate a structured review of that PR. The review notes potential accessibility impact. You invoke @aria-specialist (Accessibility) to deep-check the ARIA changes. It identifies a missing aria-expanded state on a disclosure widget. You fix the issue using patterns from @desktop-a11y-specialist (Developer Tools) if it is a desktop application, or directly in the HTML if it is a web project.

      +

      Alex: Keep the teaching thread moving. Start with Learning Cards: Teams and Orchestration. There is something to understand, something to try, and something that proves the try worked.

      +

      Alex: The practical takeaway is this. Orchestrator agents like @accessibility-lead coordinate multi-agent workflows -- invoke one and it delegates to specialists, announcing which agent it is calling. Multi-agent output appears in sequence in Copilot Chat -- press Alt+F2 after each response to read it in Accessible View before the next agent responds. The three teams are GitHub Workflow (what happened), Accessibility (is it correct), and Developer Tools (fix it) -- choose your entry point based on your current task. Orchestrator responses can be long -- use Accessible View (Alt+F2) or widen the Chat panel to read comfortably at high zoom. The workflow diagrams in this section are described in text -- no visual-only content is required to understand the agent coordination pattern. Each team's agents are listed in the tables in Section 3 -- refer back there to find the right specialist agent.

      +

      Jamie: Let's pause on Orchestrator Agents. What should a learner take away from it?

      +

      Alex: Keep the learner anchored in Orchestrator Agents. Four agents are specifically designed to coordinate others. This is the part to say slowly: You do not need to use orchestrators to get value from individual agents.

      -

      Jamie: How do these exercises create confidence instead of pressure?

      -

      Alex: The reason Try It Now: Clone the Sci-Fi Themes Repo matters is that to make your first clone meaningful and fun, try cloning the VS Code Sci-Fi Thinking Phrases repository. That gives the learner a simple foothold: repository URL: https://github.com/community-access/vscode-sci-fi-themes.git.

      -

      Alex: The parts worth keeping in working memory are these. 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.

      -

      Alex: Another way to ground it. Start with Why Clone This? There is something to understand, something to try, and something that proves the try worked.

      -

      Alex: On the ground, that means a few things. 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!

      -

      Jamie: Let's pause on Quick Start. What should a learner take away from it?

      -

      Alex: Here is the plain-English version of Quick Start. See CLONE-THIS-REPO.md in that repo for full instructions. Put another way, if you prefer not to clone locally, you can work entirely on GitHub.com.

      -

      Alex: First, clone: Ctrl+Shift+P → "Git: Clone" → paste URL above → Enter. Then, choose a destination folder and open when prompted. After that, navigate to the themes/ folder and pick a.json file (star-trek, hitchhikers, or star-wars). Finally, copy the chat.agent.thinking.phrases setting into your VS Code settings.json. Treat it like a recipe: do not add the next ingredient until the previous one is actually in the bowl.

      -

      Jamie: Before we leave Quick Start, what is the practical point?

      -

      Alex: First, reload VS Code: Ctrl+Shift+P → "Developer: Reload Window". Then, open Copilot Chat (Ctrl+Shift+I) and ask a question--watch your custom phrases appear! After that, navigate to the repository on GitHub. Finally, click any file to view it, then click the pencil icon (Edit) to modify it directly in the browser. It is a checklist, but a meaningful one: every item creates evidence that the next step is safe.

      -

      Alex: Treat examples as spoken recipes, not decorations. You may hear something like 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. Read the command, understand what it changes, then run it only when the repository state matches the lesson.

      +

      Alex: Keep the teaching thread moving. The reason High-Impact Agents to Try First matters is that rather than exploring all 55 agents at once, start with the ones that deliver immediate value based on Day 1 skills you already have.

      +

      Jamie: Let's pause on Slash Commands That Save the Most Time. What should a learner take away from it?

      +

      Alex: Start with Slash Commands That Save the Most Time: These commands work without invoking a full agent - type them directly in Copilot Chat. The next useful detail is this: The full list of 54+ commands is in Appendix L, and Episode 39 walks through all of them with examples.

      +

      Alex: The practical takeaway is this. /my-issues and /my-prs - Instant dashboard of your open work across all repos. /review-pr 14 - Full AI-generated review with inline suggestions, replacing manual line-by-line reading. /triage 22 - Label, priority, and assignment suggestions for any new issue. /daily-briefing - Morning snapshot of repository activity, PRs needing review, and stale issues.

      +

      Alex: Keep the teaching thread moving. Here is the plain-English version of Running Agents Beyond VS Code. Accessibility Agents' agents run on your machine, in your editor, when you ask for them. Put another way, the same Markdown-authored pattern extends further. It is like learning a transit route. The names of the stops matter because they tell you whether you are still going the right direction.

      -

      Alex: Before the learner moves on. This is where 2. The Source Control Panel - Complete Walkthrough becomes real: the Source Control panel (Ctrl+Shift+G - Mac: Cmd+Shift+G) is where all Git operations happen in VS Code. That matters in practice: This section provides a complete screen reader walkthrough of every interactive element.

      -

      Jamie: Give me the version that sounds like an instructor, not a manual.

      -

      Alex: Keep the learner anchored in Opening the Source Control Panel. Shortcut: Ctrl+Shift+G (Mac: Cmd+Shift+G).

      -

      Alex: This is the part worth saying out loud. Start with What opens. There is something to understand, something to try, and something that proves the try worked.

      -

      Alex: That becomes easier when you listen for these cues. 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).

      +

      Jamie: Let's pause on Scope 1: Your Editor (Accessibility Agents). What should a learner take away from it?

      +

      Alex: Start with Scope 1: Your Editor (Accessibility Agents). There is something to understand, something to try, and something that proves the try worked.

      +

      Alex: The practical takeaway is this. File lives in.github/agents/[name].agent.md in your workspace. Triggered by: You, when you type @[agent-name] in Copilot Chat. Runs on: Your machine, using your Copilot subscription. Reaches: Every repository your GitHub account has access to. Scale: All 55 agents available when the workspace is open.

      +

      Alex: Keep the teaching thread moving. Keep the learner anchored in Scope 2: Your Repository (Travels with Forks). When you fork accessibility-agents, all 55 agents come with it. This is the part to say slowly: You can edit them for your project's context.

      +

      Alex: The practical takeaway is this. File lives in.github/agents/[name].agent.md in the repo. Triggered by: Any contributor who has Copilot and opens the repo as a VS Code workspace. Runs on: Their machine, using their Copilot subscription. Reaches: Their GitHub account's repositories.

      +

      Jamie: Let's pause on Scope 3: The Cloud (GitHub Agentic Workflows). What should a learner take away from it?

      +

      Alex: The reason Scope 3: The Cloud (GitHub Agentic Workflows) matters is that the workflow runs whether or not anyone is watching - when an issue is opened at 3am, the agentic response fires. That gives the learner a simple foothold: the link between Accessibility Agents and Agentic Workflows: Both use Markdown-authored instructions.

      +

      Alex: The practical takeaway is this. File lives in.github/workflows/[name].md (same folder as standard Actions YAML). Triggered by: Any GitHub event - issues: opened, pull request: created, schedule. Runs on: GitHub Actions infrastructure, serverlessly. Reaches: The repository where the workflow is defined.

      -

      Jamie: Let's pause on Panel structure from top to bottom. What should a learner take away from it?

      -

      Alex: Start with Panel structure from top to bottom. There is something to understand, something to try, and something that proves the try worked.

      -

      Alex: The practical anchors are these. Branch name displayed (example: "main" or "feature/add-documentation"). View/More Actions button (three dots menu). Type your commit message here. Announced as "Source Control Input, edit, multi-line". Shortcut: Ctrl+Enter (Mac: Cmd+Enter) when focused in the message input. Lists all modified files not yet staged.

      -

      Alex: First, source Control title bar (heading level 2). Then, commit message input (multi-line text field). After that, commit button (or "Publish Branch" if this is a new branch). Finally, changes section (collapsible tree). Think of it as a rail line: each stop confirms you are still on the right route before the next one.

      -

      Jamie: Before we leave Panel structure from top to bottom, what is the practical point?

      -

      Alex: First, staged Changes section (collapsible tree). Then, merge Changes section (appears only during a merge). Treat it like a recipe: do not add the next ingredient until the previous one is actually in the bowl.

      -

      Alex: Hold that next to this. Start with NVDA/JAWS. There is something to understand, something to try, and something that proves the try worked.

      -

      Alex: Here is what that changes in practice. 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).

      -

      Jamie: If I am listening before the workshop starts, what should settle in my mind first?

      -

      Alex: This is where VoiceOver becomes real: key point: The Source Control panel is not a standard file tree. That matters in practice: It's a specialized Git status view.

      -

      Alex: These are the details that keep the idea from floating away. Navigate with VO+Arrow keys. VO+Space to activate (open diff or stage/unstage). The panel is announced as a "group" containing lists.

      +

      Alex: Keep the teaching thread moving. Start with Go Deeper: For full documentation on every agent, all 54+ slash commands, customization formats, and troubleshooting, see Appendix L: Accessibility Agents Reference. The next useful detail is this: For the audio version, listen to Episode 39: Accessibility Agents - Complete Reference. Think of it like entering a new building: first you find the lobby, then the room, then the door you actually need.

      +

      Jamie: Let's pause on Example: Auto-triage accessibility issues. What should a learner take away from it?

      +

      Alex: Here is the plain-English version of Example: Auto-triage accessibility issues. File.github/workflows/auto-triage-a11y.md. Put another way, this runs automatically on every new issue.

      +

      Alex: Keep the teaching thread moving. This is where 8. GitHub Desktop, GitHub CLI, and Copilot CLI becomes real: these tools are not required for this workshop, but are worth knowing as options for different workflows.

      -

      Alex: The next layer is this. Keep the learner anchored in What Each File Shows. When a file appears in the Changes or Staged Changes list, VS Code shows a status letter. This is the part to say slowly: Screen reader announcement: "docs/GUIDE.md, Modified" or "README.md, Added". A good GitHub workflow is like a well-run meeting: everyone knows the topic, the next action, and who has the floor.

      -

      Jamie: Let's pause on Context Menu Actions (Right-Click or Shift+F10). What should a learner take away from it?

      -

      Alex: The reason Context Menu Actions (Right-Click or Shift+F10) matters is that when focused on any file in the Source Control panel. That gives the learner a simple foothold: use Shift+F10 to open the context menu.

      -

      Jamie: Let's pause on Learning Cards: Source Control Panel. What should a learner take away from it?

      -

      Alex: Start with Learning Cards: Source Control Panel: Low vision users (zoom, high contrast). The next useful detail is this: The Source Control panel adapts well to zoom and high contrast settings.

      -

      Alex: First, 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. Then, 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. After that, 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). Finally, 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. Think of it as a rail line: each stop confirms you are still on the right route before the next one.

      -

      Jamie: Before we leave Learning Cards: Source Control Panel, what is the practical point?

      -

      Alex: First, 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. Treat it like a recipe: do not add the next ingredient until the previous one is actually in the bowl.

      -

      Alex: Treat examples as spoken recipes, not decorations. You may hear something like 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. Read the command, understand what it changes, then run it only when the repository state matches the lesson.

      +

      Jamie: Let's pause on GitHub Desktop. What should a learner take away from it?

      +

      Alex: Keep the learner anchored in GitHub Desktop. A graphical Git application with an accessible interface. This is the part to say slowly: When to use: If command-line Git feels overwhelming, GitHub Desktop provides a GUI alternative.

      +

      Alex: The practical takeaway is this. Download: desktop.github.com. Useful for: Visual diff review, simpler branch management. Screen reader support: Partial - keyboard navigation works for core flows.

      +

      Alex: Keep the teaching thread moving. The reason GitHub CLI (gh) matters is that a command-line interface for GitHub operations. The interface gets friendlier when it stops being a wall of controls and starts being a set of named places.

      +

      Jamie: What is the safe way to learn from that example?

      +

      Alex: Start with Authenticate. There is something to understand, something to try, and something that proves the try worked.

      +

      Alex: Treat examples as spoken recipes, not decorations. You may hear something like gh auth login. Read the command, understand what it changes, then run it only when the repository state matches the lesson.

      -

      Jamie: Let's pause on 3. Branch Management. What should a learner take away from it?

      -

      Alex: Here is the plain-English version of 3. Branch Management. Branches are how you organize work in Git. Put another way, every repository starts with a main or master branch.

      -

      Jamie: Let's pause on Where it's shown. What should a learner take away from it?

      -

      Alex: Start with Where it's shown. There is something to understand, something to try, and something that proves the try worked.

      -

      Alex: First, bottom-left corner of VS Code (status bar) - visual users see it immediately. Then, source Control panel title bar. After that, command Palette: Ctrl+Shift+P (Mac: Cmd+Shift+P) → "Git: Show Git Output". It is a checklist, but a meaningful one: every item creates evidence that the next step is safe.

      -

      Jamie: Let's pause on Keyboard access to status bar. What should a learner take away from it?

      -

      Alex: Keep the learner anchored in Keyboard access to status bar. Visual users: You can also click the branch name in the bottom-left status bar to open the branch picker directly.

      -

      Alex: The practical takeaway is this. The status bar is not in the standard keyboard navigation flow. Use the Command Palette for branch operations instead.

      +

      Jamie: Let's pause on Common commands. What should a learner take away from it?

      +

      Alex: Here is the plain-English version of Common commands. Screen reader advantage: gh output is plain text with no dynamic regions - more predictable than the browser for certain operations.

      +

      Alex: Treat examples as spoken recipes, not decorations. You may hear something like gh issue list List issues in current repo; gh issue view 42 Read issue 42; gh pr list List pull requests; gh pr view 14 Read PR 14; gh pr create Create a new PR interactively; gh pr merge 14 Merge PR 14; gh repo clone owner/repo Clone a repository; gh repo. Read the command, understand what it changes, then run it only when the repository state matches the lesson.

      +

      Jamie: Let's pause on GitHub Copilot CLI (gh copilot). What should a learner take away from it?

      +

      Alex: This is where GitHub Copilot CLI (gh copilot) becomes real: an extension that adds Copilot to the terminal.

      +

      Jamie: Let's pause on Install. What should a learner take away from it?

      +

      Alex: Start with Install. There is something to understand, something to try, and something that proves the try worked.

      +

      Alex: Treat examples as spoken recipes, not decorations. You may hear something like gh extension install github/gh-copilot. Read the command, understand what it changes, then run it only when the repository state matches the lesson.

      -

      Jamie: Let's pause on Command Palette method (recommended). What should a learner take away from it?

      -

      Alex: Start with Command Palette method (recommended). There is something to understand, something to try, and something that proves the try worked.

      -

      Alex: The practical takeaway is this. Creates the branch. Switches to it automatically. Your working files stay exactly as they were.

      -

      Alex: First, ctrl+Shift+P (Mac: Cmd+Shift+P). Then, type "git create branch". After that, select "Git: Create Branch.". Finally, type the new branch name (example: feature/improve-docs). The rhythm is simple: orient, act, verify, then continue.

      -

      Jamie: Before we leave Command Palette method (recommended), what is the practical point?

      -

      Alex: First, press Enter. Think of it as a rail line: each stop confirms you are still on the right route before the next one.

      -

      Jamie: Let's pause on Naming conventions. What should a learner take away from it?

      -

      Alex: Start with Naming conventions: Web alternative (github.com) - branch management. The next useful detail is this: Create and switch branches without leaving your browser.

      -

      Alex: The practical takeaway is this. Use lowercase with hyphens: feature/add-timeline-guide. Avoid spaces and special characters. Be descriptive: fix/heading-hierarchy not fix1.

      -

      Alex: First, on the repository page, click the branch dropdown (shows "main" by default). Then, type a new branch name in the search field. After that, click "Create branch: your-branch-name from main". Finally, GitHub switches to the new branch immediately. Think of it as a rail line: each stop confirms you are still on the right route before the next one.

      -

      Jamie: Before we leave Naming conventions, what is the practical point?

      -

      Alex: First, any file edits you make in the browser will be on this branch. Treat it like a recipe: do not add the next ingredient until the previous one is actually in the bowl.

      -

      Alex: Treat examples as spoken recipes, not decorations. You may hear something like 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. Read the command, understand what it changes, then run it only when the repository state matches the lesson.

      -

      Jamie: Let's pause on Command Palette method. What should a learner take away from it?

      -

      Alex: Here is the plain-English version of Command Palette method. Screen reader announcement: "Branch: main" or "Branch: feature/add-timeline-guide". It is like learning a transit route. The names of the stops matter because they tell you whether you are still going the right direction.

      -

      Alex: First, ctrl+Shift+P (Mac: Cmd+Shift+P). Then, type "git checkout". After that, select "Git: Checkout to.". Finally, a list of all branches appears. Treat it like a recipe: do not add the next ingredient until the previous one is actually in the bowl.

      -

      Jamie: Before we leave Command Palette method, what is the practical point?

      -

      Alex: First, up/Down Arrow to navigate. Then, enter to switch. It is a checklist, but a meaningful one: every item creates evidence that the next step is safe.

      +

      Jamie: Let's pause on Commands. What should a learner take away from it?

      +

      Alex: The reason Commands matters is that use case: When you know what you want to do but are unsure of the exact git command syntax.

      +

      Alex: Treat examples as spoken recipes, not decorations. You may hear something like Ask Copilot to explain a command; gh copilot explain "git rebase -i HEAD 3"; Ask Copilot to suggest a command; gh copilot suggest "undo my last commit but keep the changes"; Ask Copilot to write a shell script; gh copilot suggest "create a script that finds. Read the command, understand what it changes, then run it only when the repository state matches the lesson.

      +

      Jamie: Let's pause on Example session. What should a learner take away from it?

      +

      Alex: Start with Example session. There is something to understand, something to try, and something that proves the try worked.

      +

      Alex: Treat examples as spoken recipes, not decorations. You may hear something like $ gh copilot suggest "show me all commits from last week"; Suggestion: git log --since="1 week ago" --oneline; Run this command? (Y/n). Read the command, understand what it changes, then run it only when the repository state matches the lesson.

      +

      Jamie: Let's pause on Learning Cards: GitHub Desktop, GitHub CLI, and Copilot CLI. What should a learner take away from it?

      +

      Alex: Start with Learning Cards: GitHub Desktop, GitHub CLI, and Copilot CLI. There is something to understand, something to try, and something that proves the try worked.

      +

      Alex: The practical takeaway is this. GitHub Desktop is a native application -- on Windows it uses UI Automation, not a browser DOM; your screen reader's object navigation (NVDA: Insert+Numpad) rather than browse mode is the correct approach for navigating its interface. GitHub CLI (gh) is entirely terminal-based; all output is plain text that your screen reader reads line by line -- pipe verbose output through head -20 or Select-Object -First 20 to avoid overwhelming your speech buffer. Copilot CLI (gh copilot suggest and gh copilot explain) presents interactive prompts in the terminal; listen for the "Run this command? (Y/n)" confirmation before pressing Enter to avoid executing unreviewed commands. GitHub Desktop inherits your Windows display scaling -- if text appears small, increase system-level scaling (Settings Display Scale) rather than looking for an in-app zoom option. Terminal output from gh and gh copilot uses your terminal's font and color settings; configure your terminal profile (Windows Terminal settings or iTerm2 preferences) with a high-contrast color scheme and large font for comfortable reading. Copilot CLI suggestions appear as plain text in the terminal, not in a styled panel -- they are easy to miss among other output; look for the indented suggestion block immediately after your prompt.

      -

      Jamie: Let's pause on What happens when you switch. What should a learner take away from it?

      -

      Alex: Start with What happens when you switch. There is something to understand, something to try, and something that proves the try worked.

      -

      Alex: The practical takeaway is this. 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).

      -

      Jamie: Let's pause on After your PR is merged, you can delete the branch. What should a learner take away from it?

      -

      Alex: Keep the learner anchored in After your PR is merged, you can delete the branch. You cannot delete the branch you're currently on.

      -

      Alex: First, ctrl+Shift+P (Mac: Cmd+Shift+P). Then, type "git delete branch". After that, select "Git: Delete Branch.". Finally, choose the branch to delete from the list. It is like walking a hallway with named doors: read the sign, enter the right room, then confirm where you landed.

      -

      Jamie: What should they understand before typing anything?

      -

      Alex: The reason Viewing All Branches matters is that command: Ctrl+Shift+P → "Git: Show Git Output" → Branch list appears. That gives the learner a simple foothold: alternative: Use the integrated terminal.

      -

      Alex: Treat examples as spoken recipes, not decorations. You may hear something like git branch Local branches only; git branch -a All branches (including remote). Read the command, understand what it changes, then run it only when the repository state matches the lesson.

      +

      Alex: Keep the teaching thread moving. This is where "Agent not found" becomes real: issue: Typing @agent-name shows "No agent found.". The workshop is closer to rehearsal than lecture. You hear the move, try the move, and then check what changed.

      +

      Jamie: Let's pause on Solutions. What should a learner take away from it?

      +

      Alex: Start with Solutions. There is something to understand, something to try, and something that proves the try worked.

      +

      Alex: First, verify.github/agents/[name].agent.md exists in your workspace. Then, reload VS Code window: Ctrl+Shift+P → "Reload Window". After that, check file naming: must end with.agent.md. Finally, verify YAML frontmatter is valid (no syntax errors). It is like walking a hallway with named doors: read the sign, enter the right room, then confirm where you landed.

      +

      Alex: Keep the teaching thread moving. The reason Agent produces incorrect output matters is that issue: Agent's response is wrong or misses context.

      -

      Jamie: Let's pause on Learning Cards: Branch Management. What should a learner take away from it?

      -

      Alex: Start with Learning Cards: Branch Management: Low vision users (zoom, high contrast). The next useful detail is this: Screen reader users (NVDA / JAWS on Windows). Think of it like entering a new building: first you find the lobby, then the room, then the door you actually need.

      -

      Alex: First, 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. Then, 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. After that, 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. Think of it as a rail line: each stop confirms you are still on the right route before the next one.

      -

      Jamie: Let's pause on Creating a branch. What should a learner take away from it?

      -

      Alex: Start with Creating a branch. There is something to understand, something to try, and something that proves the try worked.

      -

      Alex: First, press Ctrl+Shift+P to open the Command Palette. Then, type "git create branch" - NVDA/JAWS announces results as you type. After that, press Enter on "Git: Create Branch.". Finally, the input focus moves to a text field - type your branch name (e.g., feature/add-docs). Treat it like a recipe: do not add the next ingredient until the previous one is actually in the bowl.

      -

      Jamie: Before we leave Creating a branch, what is the practical point?

      -

      Alex: First, press Enter - VS Code creates and switches to the branch. Then, NVDA/JAWS announces the new branch name in the status bar notification. It is a checklist, but a meaningful one: every item creates evidence that the next step is safe.

      -

      Jamie: Let's pause on Switching branches. What should a learner take away from it?

      -

      Alex: Start with Switching branches. There is something to understand, something to try, and something that proves the try worked.

      -

      Alex: First, press Ctrl+Shift+P, type "git checkout". Then, select "Git: Checkout to.". After that, a list of branches appears - navigate with Up/Down Arrow. Finally, each item is announced as the branch name (e.g., "main", "feature/add-docs"). It is a checklist, but a meaningful one: every item creates evidence that the next step is safe.

      -

      Jamie: Before we leave Switching branches, what is the practical point?

      -

      Alex: First, press Enter to switch. Then, VS Code reloads files for that branch - you hear a status bar update. It is like walking a hallway with named doors: read the sign, enter the right room, then confirm where you landed.

      +

      Jamie: Before we leave Solutions, what is the practical point?

      +

      Alex: First, provide more context in your prompt: Be specific about what you need. Then, use @ mentions: Reference specific files or selections (@filename.md, selection). After that, check the agent's prerequisites: Did you do the manual work first? Finally, review the agent's instructions: Open.github/agents/[name].agent.md and read what it's supposed to do. Think of it as a rail line: each stop confirms you are still on the right route before the next one.

      +

      Alex: Keep the teaching thread moving. Here is the plain-English version of Slash command doesn't work. Issue: /command shows "Command not found.". It is like learning a transit route. The names of the stops matter because they tell you whether you are still going the right direction.

      +

      Jamie: What is the teaching move inside Solutions?

      +

      Alex: This is where Solutions becomes real: next: Chapter 20: Build Your Agent Back: Chapter 18: Fork and Contribute Related appendices: Appendix L: Agents Reference Appendix K: Copilot Reference.

      +

      Alex: First, verify.github/prompts/[name].md exists. Then, reload window: Ctrl+Shift+P → "Reload Window". After that, check file naming: must be a.md file in.github/prompts/. Finally, try typing the full command name (autocomplete may be incomplete). It is a checklist, but a meaningful one: every item creates evidence that the next step is safe.

      -

      Jamie: Let's pause on Deleting a branch. What should a learner take away from it?

      -

      Alex: Keep the learner anchored in Deleting a branch. Screen reader users (VoiceOver on macOS).

      -

      Alex: First, switch to a different branch first (you cannot delete the branch you are on). Then, press Ctrl+Shift+P, type "git delete branch". After that, select "Git: Delete Branch.". Finally, navigate the list to find the branch to delete, press Enter. It is like walking a hallway with named doors: read the sign, enter the right room, then confirm where you landed.

      -

      Jamie: What is the teaching move inside Creating a branch?

      -

      Alex: First, press Cmd+Shift+P to open the Command Palette. Then, type "git create branch" - VoiceOver announces filtered results. After that, press Return on "Git: Create Branch.". Finally, type the branch name in the input field. The rhythm is simple: orient, act, verify, then continue.

      -

      Jamie: If someone only remembers one thing from Creating a branch, what should it be?

      -

      Alex: First, press Return to create and switch. Think of it as a rail line: each stop confirms you are still on the right route before the next one.

      -

      Jamie: What is the teaching move inside Switching branches?

      -

      Alex: First, press Cmd+Shift+P, type "git checkout". Then, select "Git: Checkout to.". After that, use VO+Down Arrow to navigate the branch list. Finally, press Return to switch. Think of it as a rail line: each stop confirms you are still on the right route before the next one.

      +

      Jamie: What should people carry with them after this?

      +

      Alex: Carry the map. Know what page or tool you are in, know which action you are taking, and know what confirmation should follow. If the confirmation is missing, pause. That pause is not wasted time; it is professional judgment.

      +

      Jamie: That is a better way to say it than just follow the steps.

      +

      Alex: Right. Steps matter, but understanding wins. That is episode 17. Next in the series is episode 18, where we keep building the same contributor muscles.

      +
      +
      -

      Jamie: Let's pause on Getting the current branch name. What should a learner take away from it?

      -

      Alex: Here is the plain-English version of Getting the current branch name. Create and switch branches without leaving your browser. Put another way, manage branches from your terminal.

      -

      Alex: First, press VO+M to move to the menu bar, then VO+Right Arrow to the status bar area. Then, or use the Command Palette: Cmd+Shift+P then type "Git: Show Git Output" - the output pane includes the current branch. After that, on the repository page, find the branch dropdown button (shows "main" by default) - it is above the file table. Finally, click or activate the dropdown. Treat it like a recipe: do not add the next ingredient until the previous one is actually in the bowl.

      -

      Jamie: Before we leave Getting the current branch name, what is the practical point?

      -

      Alex: First, type a new branch name in the search field. Then, click "Create branch: your-branch-name from main" when it appears. After that, GitHub switches to the new branch immediately. Finally, any file edits in the browser will be on this branch. It is a checklist, but a meaningful one: every item creates evidence that the next step is safe.

      -

      Alex: Treat examples as spoken recipes, not decorations. You may hear something like 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. 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'. Read the command, understand what it changes, then run it only when the repository state matches the lesson.

      -

      Jamie: Let's pause on 4. Staging Changes - Files, Lines, and Chunks. What should a learner take away from it?

      -

      Alex: This is where 4. Staging Changes - Files, Lines, and Chunks becomes real: this lets you commit only part of your work, leaving the rest for a later commit.

      -

      Alex: First, stage the changes you want to include. Then, commit those staged changes. It is a checklist, but a meaningful one: every item creates evidence that the next step is safe.

      -

      Jamie: Let's pause on Staging an Entire File. What should a learner take away from it?

      -

      Alex: Keep the learner anchored in Staging an Entire File. Low vision users (zoom, high contrast). This is the part to say slowly: Screen reader users (NVDA / JAWS / VoiceOver). A good GitHub workflow is like a well-run meeting: everyone knows the topic, the next action, and who has the floor.

      -

      Alex: The practical takeaway is this. 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.

      -

      Alex: First, open Source Control: Ctrl+Shift+G (Mac: Cmd+Shift+G). Then, hover over a file in the "Changes" list - a + icon appears to its right. After that, click the + to stage that file. Finally, or right-click a file → "Stage Changes". It is like walking a hallway with named doors: read the sign, enter the right room, then confirm where you landed.

      -

      Jamie: Before we leave Staging an Entire File, what is the practical point?

      -

      Alex: First, at high zoom, the + (stage), undo (discard), and open file icons may be small. Instead of hovering. Then, 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. After that, in high contrast themes, staged files show a distinct background or border in the Staged Changes section. Finally, navigate to the file in the "Changes" list. The rhythm is simple: orient, act, verify, then continue.

      +

      48. Episode 39: Accessibility Agents - Complete Reference

      +

      All 55 agents, all 54+ slash commands, customization, and troubleshooting.

      +

      Based on: Appendix L: Accessibility Agents - Complete Reference

      +

      Audio and transcript are being regenerated for this episode.

      +
      +Read Transcript - Episode 39: Accessibility Agents - Complete Reference + +

      Transcript

      +

      Alex: Welcome to episode 39 of Git Going with GitHub: Accessibility Agents - Complete Reference. I am Alex, and today we are teaching this topic as a conversation you can carry into the workshop, not as a page you have to memorize.

      +

      Jamie: And I am Jamie. I will keep pulling the lesson back to real learners, real repositories, and the evidence that proves the work happened.

      -

      Jamie: Let's pause on Alternative (keyboard shortcut). What should a learner take away from it?

      -

      Alex: Start with Alternative (keyboard shortcut). There is something to understand, something to try, and something that proves the try worked.

      -

      Alex: The practical takeaway is this. Focus the file → press Space.

      -

      Alex: Keep the teaching thread moving. Start with Alternative (context menu). There is something to understand, something to try, and something that proves the try worked.

      -

      Alex: The practical takeaway is this. Focus the file → press Shift+F10 (Mac: Ctrl+Return) → select "Stage Changes".

      -

      Jamie: Let's pause on What happens. What should a learner take away from it?

      -

      Alex: Start with What happens. There is something to understand, something to try, and something that proves the try worked.

      -

      Alex: The practical takeaway is this. The file moves from "Changes" → "Staged Changes". A green "A" or "M" indicator appears.

      +

      Alex: The lesson focus is All 55 agents, all 54+ slash commands, customization, and troubleshooting. We will treat every step as a teachable decision, because that is what makes the skill portable.

      +

      Jamie: So we should explain the why clearly enough that the steps make sense when the learner meets them later.

      +

      Alex: That is it. If a listener only has audio right now, they should still get the complete concept and know what evidence would prove success.

      -

      Jamie: Let's pause on Staging Multiple Files at Once. What should a learner take away from it?

      -

      Alex: This is where Staging Multiple Files at Once becomes real: all modified files move to "Staged Changes.". The workshop is closer to rehearsal than lecture. You hear the move, try the move, and then check what changed.

      -

      Alex: First, ctrl+Shift+G (Mac: Cmd+Shift+G) to open Source Control. Then, navigate to the "Changes" section heading. After that, press Shift+F10 (Mac: Ctrl+Return) to open context menu on the section itself. Finally, select "Stage All Changes". It is a checklist, but a meaningful one: every item creates evidence that the next step is safe.

      -

      Jamie: Let's pause on Staging Individual Lines or Chunks. What should a learner take away from it?

      -

      Alex: Keep the learner anchored in 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.

      -

      Jamie: Let's pause on Workflow. What should a learner take away from it?

      -

      Alex: The reason Workflow matters is that result: Only those lines are staged. That gives the learner a simple foothold: the rest of the file remains in "Changes.".

      -

      Alex: First, open Source Control: Ctrl+Shift+G (Mac: Cmd+Shift+G). Then, navigate to a file in "Changes". After that, press Enter to open the diff view. Finally, the diff shows your changes side-by-side or inline. The rhythm is simple: orient, act, verify, then continue.

      -

      Jamie: Before we leave Workflow, what is the practical point?

      -

      Alex: First, navigate to a changed line (use Arrow keys or F7 for next hunk). Then, press Shift+F10 (Mac: Ctrl+Return) to open context menu. After that, select "Stage Selected Lines". Think of it as a rail line: each stop confirms you are still on the right route before the next one.

      +

      Jamie: There are a lot of tools in play. How do we keep that from feeling like a contest?

      +

      Alex: Start with Complete Reference - Agents, Slash Commands, Instructions, Configuration Levels, and All File Formats: This is your comprehensive reference for Accessibility Agents and the full VS Code Copilot customization system. The next useful detail is this: The ecosystem includes 55 agents across 3 teams and 5 platforms, plus 54+ slash commands, 17 skills, and 6 instruction files.

      +

      Alex: The next layer is this. Here is the plain-English version of 1. The Full Agent Ecosystem. Accessibility Agents includes 55 agents organized into three specialized teams, available on five platforms. It is like learning a transit route. The names of the stops matter because they tell you whether you are still going the right direction.

      +

      Jamie: What is the one idea that makes the next few steps less mysterious?

      +

      Alex: Start with Learning Cards: Agent Ecosystem Overview. There is something to understand, something to try, and something that proves the try worked.

      +

      Alex: That shows up in the workshop in a few specific ways. Invoke any agent by typing @agent-name in Copilot Chat (Ctrl+Shift+I) -- the autocomplete list is keyboard-navigable with arrow keys. The 55 agents are organized into 3 teams (Accessibility, GitHub Workflow, Developer Tools) -- use H in the team tables to jump between headings. Agent responses appear in the Chat panel; press Alt+F2 (Accessible View) for a structured, non-streaming version. The agent team tables use consistent columns (Agent, Type, What It Does) -- increase font size so the narrow "Type" column remains readable. Agents work in the Chat panel with your current theme and font settings -- no separate UI to configure. The five supported platforms (VS Code, Claude Code, Gemini CLI, Claude Desktop, Codex CLI) share the same agent logic with platform-specific formatting.

      -

      Jamie: Let's pause on Use case for this workshop. What should a learner take away from it?

      -

      Alex: Start with Use case for this workshop: In the diff view, press Alt+H to see Accessible Help for diff-specific keyboard shortcuts. The next useful detail is this: Web alternative (github.com) - editing files.

      -

      Alex: The practical takeaway is this. 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".

      -

      Alex: First, click the pencil icon on any file to open the web editor. Then, make your changes. After that, click "Commit changes" - GitHub creates the commit directly. Finally, choose to commit to the current branch or create a new branch and PR. Think of it as a rail line: each stop confirms you are still on the right route before the next one.

      -

      Alex: Treat examples as spoken recipes, not decorations. You may hear something like 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. Read the command, understand what it changes, then run it only when the repository state matches the lesson.

      -

      Jamie: Let's pause on Reverse the process. What should a learner take away from it?

      -

      Alex: Start with Reverse the process. There is something to understand, something to try, and something that proves the try worked.

      -

      Alex: First, focus the file in "Staged Changes". Then, press Ctrl+Enter (Mac: Cmd+Enter) or Space. After that, file moves back to "Changes". Treat it like a recipe: do not add the next ingredient until the previous one is actually in the bowl.

      -

      Jamie: Let's pause on Learning Cards: Staging Changes. What should a learner take away from it?

      -

      Alex: Start with Learning Cards: Staging Changes. There is something to understand, something to try, and something that proves the try worked.

      -

      Alex: The practical takeaway is this. 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. 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.

      +

      Alex: Now bring the learner back to the room. Keep the learner anchored in 2. GitHub Workflow Agents - Quick Reference. The GitHub Workflow team includes 12 agents that automate common repository operations. This is the part to say slowly: These are good starting points if you have completed the Day 1 skills - but explore any agent in the ecosystem that matches your workflow.\n\nInvoke any agent by typing @agent-name in Copilot Chat (Ctrl+Shift+I).

      +

      Jamie: What would you say to someone who is already bracing for this to be too much?

      +

      Alex: The reason @daily-briefing - Morning Briefing matters is that agent file.github/agents/daily-briefing.agent.md.

      +

      Alex: The useful habit is simple: orient first, act second, verify third. That pause before acting is part of the work.

      +

      Alex: That matters because of the next idea. Start with Output sections (H2 headings - navigate with H). There is something to understand, something to try, and something that proves the try worked.

      +

      Alex: On the ground, that means a few things. Needs Your Action. Pull Requests Waiting for Your Review. @Mentions Requiring Response. CI Failures on Your Branches. For Your Awareness. Issues Opened Since Yesterday.

      +

      Alex: A solid navigation habit is to prove where you are before activating controls. Headings, landmarks, and the address bar are not trivia; they are your map.

      -

      Jamie: Let's pause on Standard process. What should a learner take away from it?

      -

      Alex: Start with Standard process. There is something to understand, something to try, and something that proves the try worked.

      -

      Alex: First, open Source Control: Ctrl+Shift+G (Mac: Cmd+Shift+G). Then, stage changes (see Section 4). After that, focus the commit message input (usually Tab or Shift+Tab to reach it). Finally, type your commit message. It is like walking a hallway with named doors: read the sign, enter the right room, then confirm where you landed.

      -

      Jamie: Before we leave Standard process, what is the practical point?

      -

      Alex: First, press Ctrl+Enter (Mac: Cmd+Enter) to commit. The rhythm is simple: orient, act, verify, then continue.

      -

      Jamie: Let's pause on Learning Cards: Committing. What should a learner take away from it?

      -

      Alex: The reason Learning Cards: Committing matters is that low vision users (zoom, high contrast).

      -

      Alex: First, open Source Control (Ctrl+Shift+G). Then, stage your files (click the + icon next to each file, or click Stage All Changes above the Changes section header). After that, click in the "Message" text area at the top of the Source Control panel. Finally, type your commit message. The rhythm is simple: orient, act, verify, then continue.

      -

      Jamie: Before we leave Learning Cards: Committing, what is the practical point?

      -

      Alex: First, click the Commit button (checkmark icon) or press Ctrl+Enter. Then, 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. After that, 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. Finally, 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. Think of it as a rail line: each stop confirms you are still on the right route before the next one.

      -

      Alex: Keep the teaching thread moving. Start with NVDA/JAWS. There is something to understand, something to try, and something that proves the try worked.

      -

      Alex: The practical takeaway is this. 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).

      +

      Jamie: Okay, set the room for us. What are we walking into?

      +

      Alex: Here is the plain-English version of @issue-tracker - Issue Management. Agent file.github/agents/issue-tracker.agent.md. Put another way, the agent drafts replies.

      +

      Alex: A solid issue habit is to read the title, the body, and the timeline before acting. You are listening for the requested action, the missing evidence, and the person who needs a response.

      +

      Alex: This is where the talk moves from concept to action. This is where @pr-review - Pull Request Review becomes real: agent file.github/agents/pr-review.agent.md.

      +

      Alex: A solid pull request habit is to separate three questions: what changed, why it changed, and what still needs review. That keeps the conversation useful instead of noisy.

      +

      Jamie: Where do you want a learner to place their attention here?

      +

      Alex: Keep the learner anchored in Output sections (H2/H3 headings). Critical rule: The agent produces a starting point. This is the part to say slowly: Read it, edit it, post it under your own name.

      +

      Alex: These are the details that keep the idea from floating away. Risk Assessment (High / Medium / Low). Files Changed (per-file descriptions). Suggested Inline Comments (prefixed: nit:, question:, suggestion:, important:, blocking:, praise:). Questions for the Author.

      -

      Jamie: Let's pause on VoiceOver. What should a learner take away from it?

      -

      Alex: Start with VoiceOver. There is something to understand, something to try, and something that proves the try worked.

      -

      Alex: The practical takeaway is this. 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.

      -

      Alex: Keep the teaching thread moving. This is where Writing Good Commit Messages becomes real: see Culture & Etiquette: Writing Good Commit Messages for format guidance.

      -

      Jamie: How do you keep commands from becoming magic words?

      -

      Alex: Keep the learner anchored in Format. Common types: feat:, fix:, docs:, style:, refactor:, test:, chore.

      -

      Alex: The practical takeaway is this. First line: type + colon + short summary (50 characters max). Blank line. Optional body: detailed explanation. Optional footer: "Fixes 123" to link to issue.

      -

      Alex: Treat examples as spoken recipes, not decorations. You may hear something like 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. Read the command, understand what it changes, then run it only when the repository state matches the lesson.

      +

      Alex: Before the learner moves on. The reason @analytics - Team Analytics matters is that agent file.github/agents/analytics.agent.md. The interface gets friendlier when it stops being a wall of controls and starts being a set of named places.

      +

      Jamie: Give me the version that sounds like an instructor, not a manual.

      +

      Alex: Start with @insiders-a11y-tracker - Accessibility Change Monitor: Agent file.github/agents/insiders-a11y-tracker.agent.md.

      +

      Alex: Hold that next to this. Here is the plain-English version of What it monitors. Risk levels: High (regression), Medium (degraded), Low (improvement opportunity).

      -

      Alex: Keep the teaching thread moving. Start with What Happens After Commit. There is something to understand, something to try, and something that proves the try worked.

      -

      Alex: The practical takeaway is this. 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).

      -

      Jamie: Let's pause on 6. Push and Pull Operations. What should a learner take away from it?

      -

      Alex: Start with 6. Push and Pull Operations: Push sends your local commits to GitHub. The next useful detail is this: Pull downloads new commits from GitHub to your local repository.

      -

      Jamie: Let's pause on After committing locally. What should a learner take away from it?

      -

      Alex: Start with After committing locally. There is something to understand, something to try, and something that proves the try worked.

      -

      Alex: First, open Source Control: Ctrl+Shift+G (Mac: Cmd+Shift+G). Then, look for the "Publish Branch" button (if this is a new branch) or "Sync Changes" button. After that, press Enter on that button. Treat it like a recipe: do not add the next ingredient until the previous one is actually in the bowl.

      +

      Jamie: If I am listening before the workshop starts, what should settle in my mind first?

      +

      Alex: This is where @template-builder - Issue Template Wizard becomes real: agent file.github/agents/template-builder.agent.md.

      +

      Jamie: Turn that into a path someone can follow.

      +

      Alex: Keep the learner anchored in Guided workflow phases. Supported field types: markdown, input, textarea, dropdown, checkboxes. A good GitHub workflow is like a well-run meeting: everyone knows the topic, the next action, and who has the floor.

      +

      Alex: First, metadata: name, description, title prefix, auto-labels. Then, fields (one at a time): type → label → description → required → type-specific options. After that, review and output: complete YAML ready to save to.github/ISSUE TEMPLATE/. It is like walking a hallway with named doors: read the sign, enter the right room, then confirm where you landed.

      +

      Jamie: What stays the same when the tool changes?

      +

      Alex: The reason 3. Slash Commands and Prompts matters is that the repository includes 54+ slash commands. That gives the learner a simple foothold: type / in Copilot Chat to open the command menu.

      -

      Jamie: Let's pause on Alternative: Command Palette. What should a learner take away from it?

      -

      Alex: Start with Alternative: Command Palette. There is something to understand, something to try, and something that proves the try worked.

      -

      Alex: First, ctrl+Shift+P (Mac: Cmd+Shift+P). Then, type "git push". After that, select "Git: Push". Finally, VS Code pushes your commits to GitHub. It is a checklist, but a meaningful one: every item creates evidence that the next step is safe.

      -

      Jamie: Let's pause on Learning Cards: Push and Pull. What should a learner take away from it?

      -

      Alex: Keep the learner anchored in Learning Cards: Push and Pull. Low vision users (zoom, high contrast). This is the part to say slowly: Screen reader users (NVDA / JAWS on Windows). A good GitHub workflow is like a well-run meeting: everyone knows the topic, the next action, and who has the floor.

      -

      Alex: First, 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. Then, 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. After that, 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. Finally, 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. It is like walking a hallway with named doors: read the sign, enter the right room, then confirm where you landed.

      -

      Jamie: Let's pause on Pushing. What should a learner take away from it?

      -

      Alex: Start with Pushing. There is something to understand, something to try, and something that proves the try worked.

      -

      Alex: First, after committing, press Ctrl+Shift+P, type "git push", select "Git: Push". Then, NVDA/JAWS announces "Pushing." in the status bar. After that, on success, a notification appears: "Successfully pushed" - if using NVDA, check NVDA+N to read recent notifications. Finally, for a new branch (first push), use "Git: Publish Branch" instead - this sets up the upstream tracking. The rhythm is simple: orient, act, verify, then continue.

      +

      Alex: Here is the practical turn. Start with 4. Customization Primitives - Decision Guide: Before creating any file, choose the right primitive for the job. The next useful detail is this: Each primitive is a different file type with a different purpose, scope, and trigger.

      +

      Jamie: Let's pause on Instructions vs Agent? What should a learner take away from it?

      +

      Alex: Start with Instructions vs Agent? There is something to understand, something to try, and something that proves the try worked.

      +

      Alex: Here is what that changes in practice. Instructions guide behavior passively (always-on or file-scoped). Agents perform tasks actively (on-demand, tool-using).

      +

      Alex: Keep the thread going. Start with Prompt vs Agent? There is something to understand, something to try, and something that proves the try worked.

      +

      Alex: The room should hear these as checkpoints. Use a prompt for a single focused task you invoke explicitly. Use an agent when the task spans multiple steps, needs different tools, or should work as a subagent for other agents.

      -

      Jamie: Let's pause on Pulling. What should a learner take away from it?

      -

      Alex: Start with Pulling. There is something to understand, something to try, and something that proves the try worked.

      -

      Alex: First, press Ctrl+Shift+P, type "git pull", select "Git: Pull". Then, NVDA/JAWS announces "Pulling." then the status changes. After that, if there are conflicts, the Source Control panel shows a "Merge Changes" section - navigate there with Ctrl+Shift+G then Down Arrow. Think of it as a rail line: each stop confirms you are still on the right route before the next one.

      -

      Jamie: Let's pause on Checking sync status. What should a learner take away from it?

      -

      Alex: Here is the plain-English version of Checking sync status. Screen reader users (VoiceOver on macOS).

      -

      Alex: First, press Ctrl+Shift+P, type "Git: Show Git Output". Then, the output pane opens with push/pull log messages in plain text. After that, use Up/Down Arrow to read line by line. Treat it like a recipe: do not add the next ingredient until the previous one is actually in the bowl.

      -

      Jamie: Before we leave Pushing, what is the practical point?

      -

      Alex: First, press Cmd+Shift+P, type "git push", select "Git: Push". Then, VoiceOver announces progress from the status bar. After that, on success, a notification toast appears - press VO+F3 to read the latest notification. It is a checklist, but a meaningful one: every item creates evidence that the next step is safe.

      +

      Jamie: Let's pause on Prompt vs Skill? What should a learner take away from it?

      +

      Alex: Start with Prompt vs Skill? There is something to understand, something to try, and something that proves the try worked.

      +

      Alex: That becomes easier when you listen for these cues. Both appear as / slash commands. Use a prompt for one well-defined task. Use a skill when the workflow bundles scripts, templates, or reference docs alongside the instructions.

      +

      Alex: Another way to ground it. Start with Instructions vs Hooks? There is something to understand, something to try, and something that proves the try worked.

      +

      Alex: A few details make that real. Instructions guide the agent (non-deterministic). Hooks enforce behavior via shell commands at lifecycle events - they run regardless of what the agent was prompted to do.

      +

      Jamie: Let's pause on Learning Cards: Customization Primitives. What should a learner take away from it?

      +

      Alex: Start with Learning Cards: Customization Primitives. There is something to understand, something to try, and something that proves the try worked.

      +

      Alex: The practical anchors are these. The decision table maps each file type to its purpose -- navigate with T (next table) in browse mode, then arrow through rows. Key distinction: instructions are passive (always-on guidance), agents are active (on-demand task performers), hooks are deterministic (shell commands at lifecycle events). Use the "Choosing Between Primitives" Q&A pairs below the table to decide which file type fits your need. The 7-row decision table is the single most important reference here -- zoom in on the "When to Use" column for the clearest guidance. Each Q&A pair under "Choosing Between Primitives" is a short paragraph -- easy to scan at high magnification. Color-coded syntax in YAML frontmatter examples benefits from a high-contrast theme with distinct keyword colors.

      -

      Jamie: Before we leave Pulling, what is the practical point?

      -

      Alex: First, press Cmd+Shift+P, type "git pull", select "Git: Pull". Then, VoiceOver announces when the pull completes. After that, if conflicts exist, navigate to Source Control (Cmd+Shift+G) and review the Merge Changes section. It is like walking a hallway with named doors: read the sign, enter the right room, then confirm where you landed.

      -

      Jamie: What should happen before anyone copies and runs it?

      -

      Alex: The reason Screen reader feedback matters is that Git CLI alternative - push and pull. That gives the learner a simple foothold: web alternative (github.com) - push and pull.

      -

      Alex: The practical takeaway is this. 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).

      -

      Alex: Treat examples as spoken recipes, not decorations. You may hear something like 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. Read the command, understand what it changes, then run it only when the repository state matches the lesson.

      -

      Jamie: Let's pause on What to do if push fails. What should a learner take away from it?

      -

      Alex: Start with What to do if push fails. There is something to understand, something to try, and something that proves the try worked.

      -

      Alex: The practical takeaway is this. 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). Error: "Rejected - non-fast-forward" → Someone else pushed changes; you need to pull first.

      +

      Alex: This is the part worth saying out loud. Here is the plain-English version of 5. Scope and Priority - All Levels. Every customization file exists at one of three scopes. Put another way, VS Code combines all matching files from all scopes and sends them to the model. It is like learning a transit route. The names of the stops matter because they tell you whether you are still going the right direction.

      +

      Jamie: What does the learner do first, second, and then after that?

      +

      Alex: Start with Priority Order (highest wins in conflicts). There is something to understand, something to try, and something that proves the try worked.

      +

      Alex: First, personal / User-level - your profile instructions override everything. Then, workspace / Repository-level -.github/copilot-instructions.md, AGENTS.md,.github/agents/.agent.md. After that, organization-level - organization-defined custom instructions (lowest priority). It is a checklist, but a meaningful one: every item creates evidence that the next step is safe.

      +

      Jamie: What is the ordered workflow?

      +

      Alex: Keep the learner anchored in User-Level File Locations (Personal, Cross-Workspace). All of these files roam with your VS Code Settings Sync. This is the part to say slowly: On this machine: C:\Users\jeffb\AppData\Roaming\Code - Insiders\User\prompts.

      +

      Alex: First, enable Settings Sync (Ctrl+Shift+P → "Settings Sync: Turn On"). Then, ctrl+Shift+P → "Settings Sync: Configure". After that, check "Prompts and Instructions". It is like walking a hallway with named doors: read the sign, enter the right room, then confirm where you landed.

      -

      Alex: Keep the teaching thread moving. Start with When to pull. There is something to understand, something to try, and something that proves the try worked.

      -

      Alex: The practical takeaway is this. Before you start work each day. When GitHub shows your branch is behind the remote. When preparing to merge a PR.

      -

      Jamie: Let's pause on How to pull. What should a learner take away from it?

      -

      Alex: This is where How to pull becomes real: if there are conflicts: See Section 9.

      -

      Alex: First, ctrl+Shift+P (Mac: Cmd+Shift+P). Then, type "git pull". After that, select "Git: Pull". Finally, VS Code fetches and merges remote changes. It is a checklist, but a meaningful one: every item creates evidence that the next step is safe.

      -

      Alex: Keep the teaching thread moving. Start with Auto-fetch setting. There is something to understand, something to try, and something that proves the try worked.

      -

      Alex: The practical takeaway is this. VS Code can check for remote changes automatically every few minutes. Enable: Settings (Ctrl+, - Mac: Cmd+,) → search "git autofetch" → set to true.

      +

      Jamie: Let's pause on How Multiple Files Are Combined. What should a learner take away from it?

      +

      Alex: The reason How Multiple Files Are Combined matters is that VS Code collects all matching instruction files from all scopes and includes them all in the chat context. That gives the learner a simple foothold: there is no single winner - all are combined.

      +

      Alex: That connects to another useful point. Start with 6. Always-On Instructions - All File Types: Always-on instructions are automatically included in every chat request. The next useful detail is this: You never invoke them - Copilot simply follows them. Think of it like entering a new building: first you find the lobby, then the room, then the door you actually need.

      +

      Jamie: Let's pause on Option A.github/copilot-instructions.md (Recommended). What should a learner take away from it?

      +

      Alex: Here is the plain-English version of Option A.github/copilot-instructions.md (Recommended). Version-controlled and team-shared. Put another way, auto-generate with: Type /init in Copilot Chat - VS Code analyzes your workspace and generates a tailored copilot-instructions.md.

      -

      Jamie: Let's pause on Syncing Your Fork with the Upstream Repository. What should a learner take away from it?

      -

      Alex: The reason Syncing Your Fork with the Upstream Repository matters is that when you fork a repository and the original (upstream) repository receives new commits, your fork gets out of date. That gives the learner a simple foothold: keeping your fork current prevents merge conflicts and ensures you're working with the latest code.

      -

      Jamie: Let's pause on The GitHub "Sync fork" Button (Quickest Method). What should a learner take away from it?

      -

      Alex: Start with The GitHub "Sync fork" Button (Quickest Method): For straightforward updates, GitHub has a built-in sync button. Think of it like entering a new building: first you find the lobby, then the room, then the door you actually need.

      -

      Alex: First, navigate to your fork on GitHub. Then, on the repository page, look for the "This branch is N commits behind owner/repo:main" notice. After that, activate the "Sync fork" button next to it. Finally, GitHub automatically merges upstream changes into your fork's default branch. Think of it as a rail line: each stop confirms you are still on the right route before the next one.

      -

      Jamie: Before we leave The GitHub "Sync fork" Button (Quickest Method), what is the practical point?

      -

      Alex: First, then pull those changes to your local clone: Git: Pull from the Command Palette. Treat it like a recipe: do not add the next ingredient until the previous one is actually in the bowl.

      -

      Jamie: Let's pause on Screen reader path. What should a learner take away from it?

      -

      Alex: Here is the plain-English version of Screen reader path. Limitation: The GitHub sync button only syncs the default branch. Put another way, for other branches, use the git method below.

      +

      Alex: Keep the teaching thread moving. This is where Option B: AGENTS.md (Multi-Tool / Monorepo) becomes real: best for: Projects that use multiple AI tools (Copilot, Claude Code, Gemini CLI, etc.) where a single instruction file should work across all of them. That matters in practice: Also best for monorepos where different folders need different rules.

      +

      Jamie: Let's pause on Nested (per subfolder - experimental). What should a learner take away from it?

      +

      Alex: Keep the learner anchored in Nested (per subfolder - experimental). Enable nested file support: chat.useNestedAgentsMdFiles: true in VS Code settings. This is the part to say slowly: File structure: Same as copilot-instructions.md - plain Markdown, no frontmatter.

      +

      Alex: Keep the teaching thread moving. The reason Option C: CLAUDE.md (Claude Code Compatibility) matters is that best for: Teams that use Claude Code alongside VS Code. That gives the learner a simple foothold: VS Code recognizes all four locations when chat.useClaudeMdFile is enabled (default: on). The interface gets friendlier when it stops being a wall of controls and starts being a set of named places.

      -

      Jamie: What is the safe way to learn from that example?

      -

      Alex: This is where Adding the Upstream Remote (One-Time Setup) becomes real: to sync locally using git, you first configure the upstream remote. That matters in practice: This only needs to be done once per clone.

      -

      Alex: Treat examples as spoken recipes, not decorations. You may hear something like 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. Read the command, understand what it changes, then run it only when the repository state matches the lesson.

      -

      Jamie: Let's pause on Example for Accessibility Agents. What should a learner take away from it?

      -

      Alex: Start with Example for Accessibility Agents. There is something to understand, something to try, and something that proves the try worked.

      -

      Alex: Treat examples as spoken recipes, not decorations. You may hear something like git remote add upstream https://github.com/community-access/accessibility-agents.git. Read the command, understand what it changes, then run it only when the repository state matches the lesson.

      -

      Jamie: Let's pause on Fetching and Merging Upstream Changes. What should a learner take away from it?

      -

      Alex: The reason Fetching and Merging Upstream Changes matters is that once your upstream remote is configured. The interface gets friendlier when it stops being a wall of controls and starts being a set of named places.

      -

      Alex: Treat examples as spoken recipes, not decorations. You may hear something like 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. Read the command, understand what it changes, then run it only when the repository state matches the lesson.

      +

      Jamie: Let's pause on Option D: Settings-Based Instructions (Deprecated). What should a learner take away from it?

      +

      Alex: Start with Option D: Settings-Based Instructions (Deprecated): Settings-based instructions may be removed in a future VS Code version. The next useful detail is this: Use file-based instructions instead for new work.

      +

      Alex: Keep the teaching thread moving. Here is the plain-English version of Organization-Level Instructions (GitHub Enterprise). Organization administrators can define custom instructions that apply to all repositories in the organization. Put another way, every team member gets these instructions automatically.

      +

      Jamie: What is the common workflow underneath the different interfaces?

      +

      Alex: This is where To enable discovery in VS Code becomes real: organization instructions are the lowest priority - workspace and user instructions override them when they conflict.

      -

      Jamie: Let's pause on When Conflicts Occur During Sync. What should a learner take away from it?

      -

      Alex: Start with When Conflicts Occur During Sync: See also: Chapter 07: Merge Conflicts for a dedicated walkthrough of conflict resolution. The next useful detail is this: If you've made changes to the same files the upstream has changed, merge conflicts can occur during sync.

      -

      Alex: Keep the teaching thread moving. Here is the plain-English version of 7. Discarding Changes. Discarding = permanently deleting your local edits. Put another way, the file reverts to the state of the last commit.

      -

      Jamie: Let's pause on When to Discard. What should a learner take away from it?

      -

      Alex: Start with When to Discard. There is something to understand, something to try, and something that proves the try worked.

      -

      Alex: The practical takeaway is this. You made experimental changes and they didn't work. You want to start over from the last commit. You accidentally edited the wrong file.

      +

      Alex: Keep the teaching thread moving. Keep the learner anchored in 7. File-Based Instructions (.instructions.md). File-based instructions load conditionally - either when the files you are editing match a glob pattern, or when the agent determines the instruction is relevant to the current task. This is the part to say slowly: Use for: Language-specific rules, framework conventions, module-specific standards that only apply to part of the codebase. A good GitHub workflow is like a well-run meeting: everyone knows the topic, the next action, and who has the floor.

      +

      Jamie: Let's pause on The applyTo Glob Pattern. What should a learner take away from it?

      +

      Alex: The reason The applyTo Glob Pattern matters is that applyTo specifies which files trigger automatic inclusion of these instructions. That gives the learner a simple foothold: when a file matching the pattern is part of the chat context, the instructions are included automatically.

      +

      Alex: Keep the teaching thread moving. Start with Writing Effective Instructions: Guidance from GitHub's accessibility team on writing instructions that Copilot actually follows. The next useful detail is this: Share your instructions: The github/awesome-copilot repository collects community-contributed instructions files.

      +

      Alex: For a learner, the useful signals are these. Use normative language. Write MUST, MUST NOT, SHOULD, SHOULD NOT, and MAY for rules. LLMs respond well to these terms because they reduce ambiguity -- the same words used in WCAG. Example: Keyboard shortcuts MUST NOT override browser or OS shortcuts. Use lists and checklists. Structured lists provide guardrails that keep Copilot on track. Format accessibility requirements as a checklist so no criterion is overlooked. Specify your versions and standards. This application MUST conform to WCAG 2.2 Level AA is more useful than a general reference to accessibility. Include your design system's component names and flag deprecated components explicitly: DeprecatedButton MUST NOT. Focus on what Copilot doesn't already know. Instructions should add net-new information -- your team's conventions, exceptions, and priorities -- not restate what Copilot was trained on.

      -

      Jamie: Let's pause on Single file. What should a learner take away from it?

      -

      Alex: Start with Single file. There is something to understand, something to try, and something that proves the try worked.

      -

      Alex: First, open Source Control: Ctrl+Shift+G. Then, navigate to the file in "Changes". After that, press Shift+F10 for context menu. Finally, select "Discard Changes". It is like walking a hallway with named doors: read the sign, enter the right room, then confirm where you landed.

      -

      Jamie: Before we leave Single file, what is the practical point?

      -

      Alex: First, confirm in the warning dialog (VS Code will ask "Are you sure?"). The rhythm is simple: orient, act, verify, then continue.

      -

      Jamie: Let's pause on All changes. What should a learner take away from it?

      -

      Alex: The reason All changes matters is that screen reader warning: VS Code shows a modal confirmation dialog. That gives the learner a simple foothold: navigate with Tab, select "Discard" or "Cancel" with Enter.

      -

      Alex: First, ctrl+Shift+G. Then, navigate to the "Changes" section heading. After that, shift+F10 for context menu. Finally, select "Discard All Changes". The rhythm is simple: orient, act, verify, then continue.

      -

      Jamie: Before we leave All changes, what is the practical point?

      -

      Alex: First, confirm (this affects every modified file). Think of it as a rail line: each stop confirms you are still on the right route before the next one.

      -

      Jamie: Let's pause on Learning Cards: Discarding Changes. What should a learner take away from it?

      -

      Alex: Start with Learning Cards: Discarding Changes: Low vision users (zoom, high contrast). The next useful detail is this: Screen reader users (NVDA / JAWS on Windows).

      -

      Alex: First, 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.". Then, 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. After that, for "Discard All Changes", right-click the "Changes" section heading to get the context menu. Finally, 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"). Think of it as a rail line: each stop confirms you are still on the right route before the next one.

      +

      Jamie: How would you walk the room through that step by step?

      +

      Alex: Start with Command Palette method. There is something to understand, something to try, and something that proves the try worked.

      +

      Alex: First, ctrl+Shift+P → "Chat: New Instructions File". Then, choose Workspace or User Profile scope. After that, enter filename. Finally, add applyTo and/or description frontmatter. Treat it like a recipe: do not add the next ingredient until the previous one is actually in the bowl.

      +

      Jamie: Give me the sequence, because order matters here.

      +

      Alex: First, write instructions. It is a checklist, but a meaningful one: every item creates evidence that the next step is safe.

      +

      Alex: Keep the teaching thread moving. This is where Quick creation method becomes real: type /instructions in the Chat input to open the Configure Instructions menu. The workshop is closer to rehearsal than lecture. You hear the move, try the move, and then check what changed.

      +

      Jamie: Let's pause on Model Fallback Array. What should a learner take away from it?

      +

      Alex: Keep the learner anchored in Model Fallback Array. The first available model in the array is used. This is the part to say slowly: Useful for environments where not all models are licensed.

      -

      Jamie: What is the teaching move inside Single file?

      -

      Alex: First, press Ctrl+Shift+G to open Source Control. Then, navigate to the file in the Changes section with Down Arrow. After that, press Shift+F10 to open the context menu. Finally, navigate to "Discard Changes" with Down Arrow, press Enter. Treat it like a recipe: do not add the next ingredient until the previous one is actually in the bowl.

      -

      Jamie: If someone only remembers one thing from Single file, what should it be?

      -

      Alex: First, a confirmation dialog appears - NVDA announces "Are you sure you want to discard changes" or similar. Then, press Tab to navigate between "Discard" and "Cancel", press Enter on your choice. It is a checklist, but a meaningful one: every item creates evidence that the next step is safe.

      -

      Jamie: Let's pause on All files. What should a learner take away from it?

      -

      Alex: This is where All files becomes real: screen reader users (VoiceOver on macOS). That matters in practice: Discard changes from your terminal. The workshop is closer to rehearsal than lecture. You hear the move, try the move, and then check what changed.

      -

      Alex: First, navigate to the "Changes" section heading (announced as "Changes, expanded, N items"). Then, press Shift+F10, select "Discard All Changes". After that, confirm in the dialog. Finally, press Cmd+Shift+G to open Source Control. It is a checklist, but a meaningful one: every item creates evidence that the next step is safe.

      -

      Jamie: Before we leave All files, what is the practical point?

      -

      Alex: First, use VO+Arrow keys to navigate to the file. Then, press VO+Shift+M to open the context menu (or Ctrl+Return). After that, navigate to "Discard Changes", press VO+Space. Finally, in the confirmation dialog, use VO+Right Arrow to reach the buttons, VO+Space to activate. It is like walking a hallway with named doors: read the sign, enter the right room, then confirm where you landed.

      -

      Alex: Treat examples as spoken recipes, not decorations. You may hear something like 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. Read the command, understand what it changes, then run it only when the repository state matches the lesson.

      -

      Jamie: Let's pause on Safer Alternative: Stash Instead of Discard. What should a learner take away from it?

      -

      Alex: Keep the learner anchored in 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. This is the part to say slowly: Stash saves your changes temporarily without committing them.

      +

      Alex: Keep the teaching thread moving. The reason [Section Header] matters is that [Describe the exact output structure here with placeholders].

      +

      Jamie: Let's pause on Creating Your Own Agent. What should a learner take away from it?

      +

      Alex: Start with Creating Your Own Agent: Write keyword-rich descriptions. The next useful detail is this: The description is how other agents decide whether to delegate to yours.

      +

      Alex: First, copy an existing.agent.md from.github/agents/. Then, edit the frontmatter (name, description, tools). After that, write clear step-by-step instructions in the body. Finally, add an Output Format section showing the expected structure. Think of it as a rail line: each stop confirms you are still on the right route before the next one.

      +

      Jamie: Before we leave Creating Your Own Agent, what is the practical point?

      +

      Alex: First, add Constraints and Scope Boundaries sections. Then, save to.github/agents/your-agent-name.agent.md. After that, reload VS Code: Ctrl+Shift+P → "Reload Window". Finally, type @your-agent-name in Copilot Chat. Treat it like a recipe: do not add the next ingredient until the previous one is actually in the bowl.

      +

      Alex: Keep the teaching thread moving. Start with Learning Cards.agent.md - Complete Format Reference. There is something to understand, something to try, and something that proves the try worked.

      +

      Alex: The parts worth keeping in working memory are these. YAML frontmatter is the first block in the file between --- delimiters -- arrow through it line by line to verify name, description, and tools fields; indentation matters. The name field in frontmatter is what you type after @ in Copilot Chat -- if the agent does not appear, check this field matches your invocation and reload VS Code (Ctrl+Shift+P then "Reload Window"). Use Chat Diagnostics (gear icon in Chat header then Diagnostics) to verify your agent loaded successfully -- it lists every agent found, with error details if frontmatter parsing failed. Agent files are small Markdown documents typically under 100 lines -- increase editor font size and use a theme with distinct YAML keyword colors so frontmatter fields stand out. The tools list in frontmatter uses array syntax (["read", "search"]) -- at high zoom, verify commas and quotes are correct since YAML is sensitive to formatting. The body template structure (Constraints, Behavior, Output Format, Scope Boundaries) uses headings -- use VS Code's Outline view (Ctrl+Shift+O) to navigate between sections.

      -

      Alex: Keep the teaching thread moving. The reason Deleting a File from the Repository (Git Delete / git rm) matters is that Git Delete removes a file from both your working directory AND Git's tracking. That gives the learner a simple foothold: this is different from discarding changes - it permanently removes the file from the repository history going forward.

      -

      Jamie: Let's pause on How to use. What should a learner take away from it?

      -

      Alex: Start with How to use: The file is staged for deletion - you still need to commit to record the removal.

      -

      Alex: First, open the file you want to remove in the editor. Then, ctrl+Shift+P (Mac: Cmd+Shift+P). After that, type "Git: Delete". Finally, confirm the deletion. Think of it as a rail line: each stop confirms you are still on the right route before the next one.

      -

      Alex: Keep the teaching thread moving. Start with When to use Git Delete vs. just deleting the file. There is something to understand, something to try, and something that proves the try worked.

      -

      Alex: The practical takeaway is this. 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.

      +

      Jamie: Let's pause on Complete Frontmatter Reference. What should a learner take away from it?

      +

      Alex: Start with Complete Frontmatter Reference. There is something to understand, something to try, and something that proves the try worked.

      +

      Jamie: Let's pause on Tool Priority When Agent Is Also Specified. What should a learner take away from it?

      +

      Alex: Keep the learner anchored in Tool Priority When Agent Is Also Specified. When both the prompt and the referenced agent define tools, VS Code uses this priority.

      +

      Alex: First, tools listed in the prompt file's frontmatter (highest priority). Then, tools from the referenced custom agent. After that, default tools for the selected agent mode. It is like walking a hallway with named doors: read the sign, enter the right room, then confirm where you landed.

      +

      Jamie: Let's pause on Input Parameters. What should a learner take away from it?

      +

      Alex: Start with Input Parameters. There is something to understand, something to try, and something that proves the try worked.

      +

      Alex: The practical takeaway is this. parameterName - internal identifier (no spaces). The text after the second: is shown to the user as a placeholder or tooltip. Multiple parameters are supported in one prompt file.

      -

      Jamie: Let's pause on Learning Cards: Deleting a File from the Repository. What should a learner take away from it?

      -

      Alex: This is where Learning Cards: Deleting a File from the Repository becomes real: alternatively: Ctrl+Shift+P then "Git: Delete" removes the file and stages the deletion in one step. That matters in practice: Low vision users (zoom, high contrast).

      -

      Alex: First, right-click the file in the Explorer panel (Ctrl+Shift+E). Then, select "Delete" to delete from your file system. After that, the file appears in Source Control (Ctrl+Shift+G) under Changes with a "D" (deleted) status. Finally, stage and commit the deletion to record it in Git. It is a checklist, but a meaningful one: every item creates evidence that the next step is safe.

      -

      Jamie: Before we leave Learning Cards: Deleting a File from the Repository, what is the practical point?

      -

      Alex: First, 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. Then, 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. After that, stage and commit as normal. Finally, open the file you want to remove in the editor. It is like walking a hallway with named doors: read the sign, enter the right room, then confirm where you landed.

      -

      Alex: Treat examples as spoken recipes, not decorations. You may hear something like 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. Read the command, understand what it changes, then run it only when the repository state matches the lesson.

      -

      Alex: Keep the teaching thread moving. Keep the learner anchored in 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.

      -

      Jamie: Let's pause on Method 1: Explorer Sidebar. What should a learner take away from it?

      -

      Alex: Start with Method 1: Explorer Sidebar. There is something to understand, something to try, and something that proves the try worked.

      -

      Alex: First, open Explorer: Ctrl+Shift+E. Then, at the bottom of the Explorer, there's a "Timeline" section. After that, tab or Arrow to navigate into Timeline. Finally, the list shows all commits affecting the currently open file. The rhythm is simple: orient, act, verify, then continue.

      +

      Jamie: Let's pause on Creating Your Own Slash Command. What should a learner take away from it?

      +

      Alex: Start with Creating Your Own Slash Command: Both prompts and agent skills appear as / slash commands. The next useful detail is this: The difference: prompts are single-task Markdown files; skills are folders with bundled scripts and references. Think of it like entering a new building: first you find the lobby, then the room, then the door you actually need.

      +

      Alex: First, copy an existing.prompt.md from.github/prompts/. Then, edit frontmatter (name, description, tools). After that, write the task instructions in plain English. Finally, add ${input.} placeholders where the user must provide values. Think of it as a rail line: each stop confirms you are still on the right route before the next one.

      +

      Jamie: Before we leave Creating Your Own Slash Command, what is the practical point?

      +

      Alex: First, save to.github/prompts/your-command.prompt.md. Then, reload VS Code: Ctrl+Shift+P → "Reload Window". After that, type /your-command to invoke it. Treat it like a recipe: do not add the next ingredient until the previous one is actually in the bowl.

      +

      Jamie: What should someone listen for when a lesson offers more than one tool path?

      +

      Alex: Start with Learning Cards: Prompts and Slash Commands. There is something to understand, something to try, and something that proves the try worked.

      +

      Alex: The practical takeaway is this. Type / in Copilot Chat to see all available slash commands -- the autocomplete list reads each command name and description aloud.prompt.md files use YAML frontmatter for metadata (name, description, tools) followed by plain Markdown instructions. Use ${input:variableName} placeholders in prompts to create interactive fill-in-the-blank commands that prompt the user at invocation. The slash command picker popup is themed to match your current VS Code theme -- ensure your theme has sufficient contrast for dropdown items.prompt.md files are small Markdown files that are easy to read and edit at high zoom -- typically under 50 lines. The YAML frontmatter block at the top is indentation-sensitive -- use VS Code's indentation guides or a linter to verify structure.

      +

      Alex: Keep the teaching thread moving. This is where 10. Agent Skills (SKILL.md) - Complete Format Reference becomes real: a Skill is a folder - not a single file. That matters in practice: The folder contains SKILL.md plus any scripts, templates, and reference documents the skill needs.

      -

      Jamie: Let's pause on Method 2: Command Palette. What should a learner take away from it?

      -

      Alex: Start with Method 2: Command Palette. There is something to understand, something to try, and something that proves the try worked.

      -

      Alex: First, open a file in the editor. Then, ctrl+Shift+P. After that, type "timeline". Finally, select "View: Show Timeline". Think of it as a rail line: each stop confirms you are still on the right route before the next one.

      -

      Jamie: Let's pause on What Timeline Shows. What should a learner take away from it?

      -

      Alex: Here is the plain-English version of What Timeline Shows. Screen reader announcement: "docs: add Timeline Guide, Jeff, 2 days ago".

      -

      Alex: The practical takeaway is this. Commit message (first line). Author name. Relative time (example: "3 days ago" or "2 hours ago"). Commit hash (short form, like a3f2b9c).

      -

      Jamie: Let's pause on Viewing a Commit's Changes. What should a learner take away from it?

      -

      Alex: This is where Viewing a Commit's Changes becomes real: this is incredibly useful for understanding.

      -

      Alex: The practical takeaway is this. When a particular line was added. Why a section was removed. What the file looked like at any point in history.

      -

      Alex: First, navigate to a commit in the Timeline list. Then, press Enter. After that, a diff view opens showing what changed in that specific commit. It is a checklist, but a meaningful one: every item creates evidence that the next step is safe.

      +

      Jamie: Before we leave Complete Frontmatter Reference, what is the practical point?

      +

      Jamie: Let's pause on Progressive Loading - How VS Code Loads Skills. What should a learner take away from it?

      +

      Alex: The reason Progressive Loading - How VS Code Loads Skills matters is that move reference material to references/ folder files. The interface gets friendlier when it stops being a wall of controls and starts being a set of named places.

      +

      Alex: First, discovery ( 100 tokens): Reads name and description to decide if the skill is relevant. Then, instructions (<5000 tokens): Loads the full SKILL.md body when the skill is relevant. After that, resources: Additional files (scripts/, references/) only load when explicitly referenced from SKILL.md. The rhythm is simple: orient, act, verify, then continue.

      +

      Jamie: Let's pause on 11. Hooks (.json) - Lifecycle Automation. What should a learner take away from it?

      +

      Alex: Start with 11. Hooks (.json) - Lifecycle Automation: Hooks execute shell commands at specific points in an agent's lifecycle. The next useful detail is this: They are deterministic - they run regardless of what the agent was prompted to do.

      -

      Jamie: Let's pause on Git Blame - Line-by-Line History. What should a learner take away from it?

      -

      Alex: Keep the learner anchored in Git Blame - Line-by-Line History. Git Blame shows who last modified each line of the file.

      -

      Jamie: Let's pause on How to access. What should a learner take away from it?

      -

      Alex: Start with How to access. There is something to understand, something to try, and something that proves the try worked.

      -

      Alex: First, open a file in the editor. Then, ctrl+Shift+P. After that, type "git blame". Finally, select "Git: Toggle Blame". The rhythm is simple: orient, act, verify, then continue.

      -

      Jamie: Let's pause on What appears. What should a learner take away from it?

      -

      Alex: Start with What appears. There is something to understand, something to try, and something that proves the try worked.

      -

      Alex: The practical takeaway is this. Inline annotations next to every line (visually). Hover over a line to see commit details.

      +

      Alex: Keep the teaching thread moving. Here is the plain-English version of File Locations. Hooks from all locations are combined - workspace and user hooks do not override each other.

      +

      Jamie: What should they understand before typing anything?

      +

      Alex: Start with Configuration Format. There is something to understand, something to try, and something that proves the try worked.

      +

      Alex: Treat examples as spoken recipes, not decorations. You may hear something like {; "hooks": {; "PreToolUse": [; {; "type": "command",; "command": ".github/hooks/validate-before-edit.sh",; "timeout": 15; }; ],; "PostToolUse": [; {; "type": "command",; "command": "npx prettier --write",; "windows": "npx.cmd prettier --write",; "timeout". Read the command, understand what it changes, then run it only when the repository state matches the lesson.

      +

      Alex: Keep the teaching thread moving. Keep the learner anchored in PreToolUse permission decisions. Permission decisions: "allow" "ask" (prompt user) "deny" (block the tool call). A good GitHub workflow is like a well-run meeting: everyone knows the topic, the next action, and who has the floor.

      -

      Alex: Keep the teaching thread moving. Here is the plain-English version of For screen reader users. Useful blame settings (add to.vscode/settings.json or user Settings).

      -

      Alex: The practical takeaway is this. 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.

      -

      Jamie: Let's pause on Learning Cards: Timeline and History. What should a learner take away from it?

      -

      Alex: This is where Learning Cards: Timeline and History becomes real: low vision users (zoom, high contrast). That matters in practice: Screen reader users (NVDA / JAWS on Windows).

      -

      Alex: First, 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. Then, 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. After that, 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. Finally, 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. It is a checklist, but a meaningful one: every item creates evidence that the next step is safe.

      -

      Jamie: Let's pause on Opening Timeline. What should a learner take away from it?

      -

      Alex: Start with Opening Timeline. There is something to understand, something to try, and something that proves the try worked.

      -

      Alex: First, press Ctrl+Shift+E to open Explorer. Then, press Tab repeatedly or Down Arrow to navigate past the file tree to the "Timeline" section. After that, press Right Arrow to expand it if collapsed. Finally, navigate commit entries with Up/Down Arrow. It is like walking a hallway with named doors: read the sign, enter the right room, then confirm where you landed.

      -

      Jamie: Before we leave Opening Timeline, what is the practical point?

      -

      Alex: First, each entry is announced as: "commit message, author, time" (e.g., "docs: add Timeline Guide, Jeff, 2 days ago"). Then, press Enter on any entry to open its diff view. The rhythm is simple: orient, act, verify, then continue.

      +

      Jamie: Let's pause on Exit codes. What should a learner take away from it?

      +

      Alex: Start with Exit codes. There is something to understand, something to try, and something that proves the try worked.

      +

      Alex: The practical takeaway is this. 0 - success; agent continues. 2 - blocking error; agent stops. Other - non-blocking warning.

      +

      Alex: Keep the teaching thread moving. Start with Learning Cards: Hooks. There is something to understand, something to try, and something that proves the try worked.

      +

      Alex: The practical takeaway is this. Hooks are JSON files, not Markdown -- navigate them in the editor with arrow keys; each hook event (e.g., PreToolUse, PostToolUse) is a key in the "hooks" object. Hook output is returned as JSON on stdout -- the "continue" field (true/false) determines whether the agent proceeds; listen for the "stopReason" message if the hook blocks an action. The "permissionDecision" values (allow, ask, deny) control tool access -- ask triggers a confirmation dialog that your screen reader will announce as a standard VS Code dialog. JSON syntax requires careful attention to braces, brackets, and commas -- use VS Code's bracket pair colorization (editor.bracketPairColorization.enabled) and increase font size to verify structure. The hook events table maps each event name to when it fires -- zoom in on the "When It Fires" column to understand the lifecycle timing. Hook errors appear in the agent session output -- look for non-zero exit codes or "continue": false in the output pane.

      +

      Jamie: Let's pause on 12. preferences.md - Accessibility Agents Personal Settings. What should a learner take away from it?

      +

      Alex: Here is the plain-English version of 12. preferences.md - Accessibility Agents Personal Settings. Copy.github/agents/preferences.example.md to.github/agents/preferences.md. Put another way, the file is in.gitignore - your private settings stay only in your local fork.

      -

      Jamie: Let's pause on Reading a diff with screen reader. What should a learner take away from it?

      -

      Alex: Start with Reading a diff with screen reader. There is something to understand, something to try, and something that proves the try worked.

      -

      Alex: First, in the diff view, press Alt+F2 to open the Accessible Diff Viewer. Then, the Accessible Diff Viewer presents changes as a text list: each line shows + (added), - (removed), or unchanged. After that, navigate with Up/Down Arrow to read each line. Finally, press Escape to close the Accessible Diff Viewer. The rhythm is simple: orient, act, verify, then continue.

      -

      Jamie: Let's pause on Git Blame. What should a learner take away from it?

      -

      Alex: Start with Git Blame: Screen reader users (VoiceOver on macOS).

      -

      Alex: First, open a file, press Ctrl+Shift+P, type "Git: Toggle Blame". Then, blame annotations appear inline - NVDA reads them when navigating lines. After that, to reduce noise, disable blame (repeat the toggle command) and use Timeline instead. Think of it as a rail line: each stop confirms you are still on the right route before the next one.

      -

      Jamie: What is the teaching move inside Opening Timeline?

      -

      Alex: First, press Cmd+Shift+E to open Explorer. Then, use VO+Down Arrow to navigate below the file tree to the Timeline section. After that, press VO+Space to expand if collapsed. Finally, navigate entries with VO+Down Arrow. Treat it like a recipe: do not add the next ingredient until the previous one is actually in the bowl.

      -

      Jamie: If someone only remembers one thing from Opening Timeline, what should it be?

      -

      Alex: First, press VO+Space on a commit to open its diff. It is a checklist, but a meaningful one: every item creates evidence that the next step is safe.

      +

      Jamie: How do you keep commands from becoming magic words?

      +

      Alex: Start with Full File Template. There is something to understand, something to try, and something that proves the try worked.

      +

      Alex: Treat examples as spoken recipes, not decorations. You may hear something like My Accessibility Agents Preferences; My GitHub Username; your-github-username; Repositories I Work On Most; - community-access/accessibility-agents; - your-org/your-repo; Preferred Output Format; screen-reader-optimized; Notification Priority; Accessibility. Read the command, understand what it changes, then run it only when the repository state matches the lesson.

      +

      Jamie: Can you translate that into plain choices?

      +

      Alex: Start with Preferred Output Format Options. There is something to understand, something to try, and something that proves the try worked.

      +

      Alex: Use the comparison to make a decision, not to recite a table. The main contrasts are: "concise" means Bullet points and short summaries, minimal prose. "detailed" means Full context and more explanation in every response. "screen-reader-optimized" means Heading-heavy structure, no tables, explicit empty-state messages.

      +

      Alex: Keep the teaching thread moving. The reason Notification Priority Options matters is that the @daily-briefing agent reads this to sort its output sections.

      -

      Jamie: Let's pause on Accessible Diff Viewer. What should a learner take away from it?

      -

      Alex: This is where Accessible Diff Viewer becomes real: screen reader advantage: git log --oneline and git blame produce clean, columnar text output. That matters in practice: Read line by line with arrow keys in the terminal. The workshop is closer to rehearsal than lecture. You hear the move, try the move, and then check what changed.

      -

      Alex: First, in any diff view, press Option+F2 to open the Accessible Diff Viewer. Then, read changes line by line with VO+Down Arrow. After that, press Escape to close. It is a checklist, but a meaningful one: every item creates evidence that the next step is safe.

      -

      Alex: Treat examples as spoken recipes, not decorations. You may hear something like 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. 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. Read the command, understand what it changes, then run it only when the repository state matches the lesson.

      -

      Jamie: What should someone listen for when a lesson offers more than one tool path?

      -

      Alex: Keep the learner anchored in 9. Resolving Merge Conflicts in VS Code. Merge conflicts happen when two people edit the same lines of a file. This is the part to say slowly: Git can't decide which version to keep, so it asks you to choose.

      -

      Alex: Keep the teaching thread moving. The reason How VS Code Displays Conflicts matters is that when you open a file with conflicts, you see something like. That gives the learner a simple foothold: VS Code adds buttons above each conflict (visually).

      -

      Alex: The practical takeaway is this. "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).

      +

      Jamie: Let's pause on Review Comment Tone Options. What should a learner take away from it?

      +

      Alex: Start with Review Comment Tone Options: The @pr-review and @issue-tracker agents read this when drafting comments.

      +

      Jamie: What is the safe way to learn from that example?

      +

      Alex: Here is the plain-English version of Accessibility Context Options. Tells agents which screen reader and browser you use so they can tailor output and recommendations. It is like learning a transit route. The names of the stops matter because they tell you whether you are still going the right direction.

      +

      Alex: Treat examples as spoken recipes, not decorations. You may hear something like I use NVDA with Chrome on Windows 11.; I use VoiceOver with Safari on macOS Sonoma.; I use JAWS with Firefox on Windows 10.; I use Narrator with Edge on Windows 11.; I use TalkBack on Android. Read the command, understand what it changes, then run it only when the repository state matches the lesson.

      +

      Jamie: Let's pause on View All Loaded Customizations. What should a learner take away from it?

      +

      Alex: This is where View All Loaded Customizations becomes real: to see every instruction file, agent, prompt, and skill currently loaded and any errors. That matters in practice: This shows: which files were found, which were loaded, which have errors, and from which scope (user vs workspace vs organization).

      +

      Alex: First, in Copilot Chat, select the gear icon (Configure Chat) → Diagnostics. Then, or right-click in the Chat view → Diagnostics. It is a checklist, but a meaningful one: every item creates evidence that the next step is safe.

      -

      Jamie: Let's pause on Screen Reader Workflow for Resolving Conflicts. What should a learner take away from it?

      -

      Alex: Start with Screen Reader Workflow for Resolving Conflicts: The buttons are NOT accessible via keyboard.

      -

      Alex: The practical takeaway is this. <<<<<<< marks the start. ======= separates the two versions. marks the end. The section between <<<<<<< and ======= is your current branch (HEAD). The section between ======= and is the incoming branch (the branch you're merging). Delete the conflict markers ( ).

      -

      Alex: First, identify the conflict markers. Then, read both versions. After that, decide what to keep. Finally, stage the resolved file. Think of it as a rail line: each stop confirms you are still on the right route before the next one.

      -

      Jamie: Before we leave Screen Reader Workflow for Resolving Conflicts, what is the practical point?

      -

      Alex: First, commit the merge. Treat it like a recipe: do not add the next ingredient until the previous one is actually in the bowl.

      -

      Jamie: Let's pause on Using Accessible Diff for Conflict Review. What should a learner take away from it?

      -

      Alex: Here is the plain-English version of Using Accessible Diff for Conflict Review. Better approach: Use the Accessible Diff Viewer (F7) to navigate conflict hunks systematically. It is like learning a transit route. The names of the stops matter because they tell you whether you are still going the right direction.

      -

      Alex: First, open the conflicted file. Then, press F7 to jump to the first conflict hunk. After that, press Alt+F2 to open Accessible View. Finally, read both versions clearly. Treat it like a recipe: do not add the next ingredient until the previous one is actually in the bowl.

      -

      Jamie: Before we leave Using Accessible Diff for Conflict Review, what is the practical point?

      -

      Alex: First, press Escape to return to editor. Then, manually edit to resolve. After that, press F7 to jump to the next conflict. Finally, repeat until all conflicts resolved. It is a checklist, but a meaningful one: every item creates evidence that the next step is safe.

      -

      Jamie: Let's pause on Aborting a Merge. What should a learner take away from it?

      -

      Alex: This is where Aborting a Merge becomes real: if you want to cancel the merge and go back to before you started. That matters in practice: Everything returns to the pre-merge state.

      -

      Alex: First, ctrl+Shift+P. Then, type "git abort". After that, select "Git: Abort Merge". It is a checklist, but a meaningful one: every item creates evidence that the next step is safe.

      +

      Jamie: Let's pause on Agent not found when typing @agent-name. What should a learner take away from it?

      +

      Alex: Start with Agent not found when typing @agent-name. There is something to understand, something to try, and something that proves the try worked.

      +

      Alex: First, verify.github/agents/[name].agent.md exists in your open workspace folder. Then, check that the YAML frontmatter has no syntax errors (missing quotes, wrong indentation). After that, ctrl+Shift+P → "Reload Window". Finally, check that the name field in the frontmatter matches what you are typing. It is like walking a hallway with named doors: read the sign, enter the right room, then confirm where you landed.

      +

      Jamie: Let's pause on Instructions not being applied. What should a learner take away from it?

      +

      Alex: Start with Instructions not being applied. There is something to understand, something to try, and something that proves the try worked.

      +

      Alex: First, for.github/copilot-instructions.md: file must be at workspace root in the.github/ folder. Then, for.instructions.md: check that applyTo glob matches the file you are editing, and that chat.includeApplyingInstructions is true in VS Code settings. After that, for AGENTS.md: check that chat.useAgentsMdFile is true. Finally, use Diagnostics view (above) to verify the file was found and loaded. The rhythm is simple: orient, act, verify, then continue.

      +

      Alex: Keep the teaching thread moving. Start with Instructions file in wrong place. There is something to understand, something to try, and something that proves the try worked.

      +

      Alex: The practical takeaway is this. Add custom locations: chat.instructionsFilesLocations setting accepts an array of additional folder paths.

      -

      Alex: Keep the teaching thread moving. Start with Learning Cards: Resolving Merge Conflicts. There is something to understand, something to try, and something that proves the try worked.

      -

      Alex: The practical takeaway is this. 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. 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.

      -

      Jamie: Let's pause on 10. Stash Management. What should a learner take away from it?

      -

      Alex: The reason 10. Stash Management matters is that stash temporarily saves your uncommitted changes so you can switch branches or pull updates without committing half-finished work.

      -

      Alex: Keep the teaching thread moving. Start with When to Use Stash. There is something to understand, something to try, and something that proves the try worked.

      -

      Alex: The practical takeaway is this. 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.

      +

      Jamie: Let's pause on Slash command not appearing. What should a learner take away from it?

      +

      Alex: Start with Slash command not appearing. There is something to understand, something to try, and something that proves the try worked.

      +

      Alex: First, verify.github/prompts/[name].prompt.md exists. Then, ctrl+Shift+P → "Reload Window". After that, file must use.prompt.md extension (not just.md). Treat it like a recipe: do not add the next ingredient until the previous one is actually in the bowl.

      +

      Alex: Keep the teaching thread moving. This is where 14. Further Reading becomes real: for the broader ecosystem - the community plugin marketplace, MCP server integrations, and running agents in the cloud via GitHub Actions - see Appendix K: GitHub Copilot and Agentic Reference.

      +

      Jamie: Let's pause on Official accessibility.github.com Guides. What should a learner take away from it?

      +

      Alex: Keep the learner anchored in Official accessibility.github.com Guides. Next: Appendix M: Accessibility Standards Back: Appendix K: Copilot Reference Teaching chapter: Chapter 19: Accessibility Agents.

      -

      Jamie: Let's pause on Method 1: Command Palette. What should a learner take away from it?

      -

      Alex: Start with Method 1: Command Palette. There is something to understand, something to try, and something that proves the try worked.

      -

      Alex: First, ctrl+Shift+P. Then, type "git stash". After that, select "Git: Stash". Finally, optionally type a stash message (helps you remember what's in it). Treat it like a recipe: do not add the next ingredient until the previous one is actually in the bowl.

      -

      Alex: Keep the teaching thread moving. Start with What happens. There is something to understand, something to try, and something that proves the try worked.

      -

      Alex: The practical takeaway is this. 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.

      -

      Jamie: Let's pause on Command Palette. What should a learner take away from it?

      -

      Alex: Start with Command Palette. There is something to understand, something to try, and something that proves the try worked.

      -

      Alex: First, ctrl+Shift+P. Then, type "git stash list". After that, select "Git: Show Stash". It is like walking a hallway with named doors: read the sign, enter the right room, then confirm where you landed.

      +

      Jamie: What should people carry with them after this?

      +

      Alex: Carry the map. Know what page or tool you are in, know which action you are taking, and know what confirmation should follow. If the confirmation is missing, pause. That pause is not wasted time; it is professional judgment.

      +

      Jamie: That is a better way to say it than just follow the steps.

      +

      Alex: Right. Steps matter, but understanding wins. That is episode 39. Next in the series is episode 40, where we keep building the same contributor muscles.

      +
      +
      -

      Jamie: Let's pause on Alternative: Integrated Terminal. What should a learner take away from it?

      -

      Alex: Start with Alternative: Integrated Terminal. There is something to understand, something to try, and something that proves the try worked.

      -

      Alex: Treat examples as spoken recipes, not decorations. You may hear something like git stash list. Read the command, understand what it changes, then run it only when the repository state matches the lesson.

      -

      Jamie: Let's pause on To restore your stashed changes. What should a learner take away from it?

      -

      Alex: Start with To restore your stashed changes. There is something to understand, something to try, and something that proves the try worked.

      -

      Alex: First, ctrl+Shift+P. Then, type "git stash apply". After that, select "Git: Apply Latest Stash". Think of it as a rail line: each stop confirms you are still on the right route before the next one.

      -

      Jamie: Let's pause on Or to apply a specific stash. What should a learner take away from it?

      -

      Alex: Start with Or to apply a specific stash. There is something to understand, something to try, and something that proves the try worked.

      -

      Alex: First, ctrl+Shift+P. Then, type "git stash pop". After that, select "Git: Pop Stash.". Finally, choose which stash from the list. Treat it like a recipe: do not add the next ingredient until the previous one is actually in the bowl.

      +

      49. Challenge 15: Meet the Agents

      +

      Exploring agent files, running agents carefully, and verifying AI output against manual skill.

      +

      Practice focus: Day 2 capstone

      +

      Audio and transcript are being regenerated for this episode.

      +
      +Read Transcript - Challenge 15: Meet the Agents + +

      Transcript

      +

      Alex: You are listening to Challenge Coach: Meet the Agents. I am Alex, and this is the calm walkthrough before the hands-on work.

      +

      Jamie: And I am Jamie. I will make sure we teach the skill instead of just reading the checklist aloud.

      -

      Jamie: Let's pause on Difference between Apply and Pop. What should a learner take away from it?

      -

      Alex: Start with Difference between Apply and Pop. There is something to understand, something to try, and something that proves the try worked.

      -

      Alex: The practical takeaway is this. Apply: restores changes and keeps the stash (you can apply it again later). Pop: restores changes and deletes the stash.

      -

      Jamie: Let's pause on Dropping a Stash. What should a learner take away from it?

      -

      Alex: Keep the learner anchored in Dropping a Stash. If you no longer need what's in a stash. A good GitHub workflow is like a well-run meeting: everyone knows the topic, the next action, and who has the floor.

      -

      Alex: First, ctrl+Shift+P. Then, type "git stash drop". After that, select "Git: Drop Stash.". Finally, choose which stash to delete. It is like walking a hallway with named doors: read the sign, enter the right room, then confirm where you landed.

      -

      Jamie: Let's pause on Learning Cards: Stash Management. What should a learner take away from it?

      -

      Alex: The reason Learning Cards: Stash Management matters is that if the Stashes section is not visible, use the Command Palette: Ctrl+Shift+P then type "git stash" to access all stash commands. That gives the learner a simple foothold: low vision users (zoom, high contrast).

      -

      Alex: First, open Source Control: Ctrl+Shift+G. Then, in the Source Control panel, there may be a "Stashes" section below Staged Changes (visible when stashes exist). After that, click a stash to see what it contains. Finally, right-click a stash to Apply, Pop, or Drop it. The rhythm is simple: orient, act, verify, then continue.

      -

      Jamie: Before we leave Learning Cards: Stash Management, what is the practical point?

      -

      Alex: First, 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. Then, 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. After that, after applying a stash, your files reappear in the Changes section of Source Control. Check the file count to confirm. Think of it as a rail line: each stop confirms you are still on the right route before the next one.

      +

      Alex: The focus is Exploring agent files, running agents carefully, and verifying AI output against manual skill. We will explain the concept, the action, the evidence, and the most common recovery path.

      +

      Jamie: So the learner needs the why, the move, and the checkpoint all in the same mental pocket.

      +

      Alex: That is the teaching shape: understand the concept, do the smallest real action, then verify the result before moving on.

      -

      Jamie: Let's pause on Creating a stash. What should a learner take away from it?

      -

      Alex: Start with Creating a stash. There is something to understand, something to try, and something that proves the try worked.

      -

      Alex: First, press Ctrl+Shift+P, type "git stash". Then, select "Git: Stash" - NVDA announces the result. After that, an input appears asking for a stash message - type something descriptive (e.g., "WIP: documentation changes for Timeline section"). Finally, press Enter - your changes disappear from Source Control and are saved in the stash. Think of it as a rail line: each stop confirms you are still on the right route before the next one.

      -

      Jamie: Before we leave Creating a stash, what is the practical point?

      -

      Alex: First, NVDA announces the Source Control panel update (file counts drop to 0). Treat it like a recipe: do not add the next ingredient until the previous one is actually in the bowl.

      -

      Jamie: Let's pause on Applying a stash. What should a learner take away from it?

      -

      Alex: Start with Applying a stash. There is something to understand, something to try, and something that proves the try worked.

      -

      Alex: First, press Ctrl+Shift+P, type "git stash pop". Then, select "Git: Pop Stash.". After that, a list of stashes appears - navigate with Up/Down Arrow. Finally, each item is announced with the stash message you wrote. Treat it like a recipe: do not add the next ingredient until the previous one is actually in the bowl.

      -

      Jamie: Before we leave Applying a stash, what is the practical point?

      -

      Alex: First, press Enter to apply and delete the stash. Then, your changes reappear in the Changes section. It is a checklist, but a meaningful one: every item creates evidence that the next step is safe.

      -

      Jamie: Let's pause on Viewing stashes. What should a learner take away from it?

      -

      Alex: This is where Viewing stashes becomes real: screen reader users (VoiceOver on macOS). That matters in practice: GitHub.com does not have a stash feature. The workshop is closer to rehearsal than lecture. You hear the move, try the move, and then check what changed.

      -

      Alex: First, press Ctrl+Shift+P, type "git stash list". Then, or in the terminal: type git stash list and read the output line by line. After that, press Cmd+Shift+P, type "git stash". Finally, select "Git: Stash" and provide a message. It is a checklist, but a meaningful one: every item creates evidence that the next step is safe.

      -

      Jamie: Before we leave Viewing stashes, what is the practical point?

      -

      Alex: First, press Return. Then, to apply: Cmd+Shift+P, type "git stash pop", select from the list with VO+Down Arrow, press Return. After that, create a draft commit on a temporary branch. Finally, or use GitHub Codespaces (which runs a full VS Code environment in the browser and supports git stash in the terminal). It is like walking a hallway with named doors: read the sign, enter the right room, then confirm where you landed.

      -

      Alex: Treat examples as spoken recipes, not decorations. You may hear something like 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. Read the command, understand what it changes, then run it only when the repository state matches the lesson.

      +

      Jamie: What makes this practice feel low-stakes but still real?

      +

      Alex: Start with Challenge 15: Meet the Agents: What you will do: Explore the accessibility-agents repository, discover what agents are available, run one agent, and read one agent's.agent.md file to understand how it works.

      +

      Jamie: How would you walk the room through that step by step?

      +

      Alex: Start with Instructions. There is something to understand, something to try, and something that proves the try worked.

      +

      Alex: The practical anchors are these. Using a slash command in GitHub Copilot Chat. Invoking an agent through the VS Code command palette. Following the usage instructions in the agent's README. What is the agent's purpose? What are its responsibilities? What are its guardrails (things it should NOT do)?

      +

      Alex: First, discover -- Browse the accessibility-agents repository and find at least 3 different agents. Note their names and what they do. Then, run -- Choose one agent and try it out. This might mean. After that, read -- Open one agent's.agent.md file. Identify. Treat it like a recipe: do not add the next ingredient until the previous one is actually in the bowl.

      +

      Jamie: What is the one idea that makes the next few steps less mysterious?

      +

      Alex: This is where What to look for in an.agent.md file becomes real: every agent file follows a pattern. That matters in practice: Its purpose is., its guardrails include.

      +

      Alex: That shows up in the workshop in a few specific ways. YAML frontmatter at the top: metadata like name, description, tools. Responsibilities section: what the agent is designed to do. Guardrails section: boundaries that keep the agent safe and focused.

      -

      Jamie: How should someone ask for help in a way that gets them unstuck faster?

      -

      Alex: Keep the learner anchored in 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. This is the part to say slowly: It is the most underused recovery tool in Git.

      -

      Jamie: What is the judgment call here?

      -

      Alex: Start with When to Use Reflog. There is something to understand, something to try, and something that proves the try worked.

      -

      Alex: Use the comparison to make a decision, not to recite a table. The main contrasts are: Scenario means What happened means Reflog solution. Deleted a branch by mistake means git branch -D feature/x means Find the last commit SHA from reflog → recreate branch. git reset --hard lost commits means Moved HEAD to older commit means Find the SHA before the reset → reset back to it.

      -

      Jamie: Let's pause on Reading the Reflog in VS Code Terminal. What should a learner take away from it?

      -

      Alex: Start with Reading the Reflog in VS Code Terminal: Run this in the integrated terminal (Ctrl+Backtick). The next useful detail is this: The output is plain text - read line by line with ↓.

      -

      Alex: Treat examples as spoken recipes, not decorations. You may hear something like git reflog. Read the command, understand what it changes, then run it only when the repository state matches the lesson.

      +

      Alex: Now bring the learner back to the room. Keep the learner anchored in Peer simulation check. Compare your agent discoveries with the peer-simulation issue or with a real buddy if you have access. This is the part to say slowly: Did you find different agents or different use cases?

      +

      Jamie: What would you say to someone who is already bracing for this to be too much?

      +

      Alex: The reason Agent 1: accessibility-lead matters is that location.github/agents/accessibility-lead.agent.md. That gives the learner a simple foothold: purpose: Coordinates accessibility reviews across the team.

      +

      Alex: The useful habit is simple: orient first, act second, verify third. That pause before acting is part of the work.

      +

      Alex: That matters because of the next idea. Start with Agent 2: aria-specialist: Location.github/agents/aria-specialist.agent.md. The next useful detail is this: Purpose: Reviews ARIA (Accessible Rich Internet Applications) attributes in HTML and web components. Think of it like entering a new building: first you find the lobby, then the room, then the door you actually need.

      -

      Jamie: Let's pause on If you need to restore a commit that has been lost. What should a learner take away from it?

      -

      Alex: Here is the plain-English version of If you need to restore a commit that has been lost. 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. It is like learning a transit route. The names of the stops matter because they tell you whether you are still going the right direction.

      -

      Alex: Treat examples as spoken recipes, not decorations. You may hear something like 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. Read the command, understand what it changes, then run it only when the repository state matches the lesson.

      -

      Jamie: Let's pause on Recovering a Deleted Branch. What should a learner take away from it?

      -

      Alex: Start with Recovering a Deleted Branch. There is something to understand, something to try, and something that proves the try worked.

      -

      Alex: Treat examples as spoken recipes, not decorations. You may hear something like 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. Read the command, understand what it changes, then run it only when the repository state matches the lesson.

      -

      Alex: Keep the teaching thread moving. Keep the learner anchored in Why Reflog Is Local-Only. Reflog records are stored in your local.git/ directory and are not pushed to GitHub. This is the part to say slowly: 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.

      +

      Jamie: Okay, set the room for us. What are we walking into?

      +

      Alex: Here is the plain-English version of Agent 3: keyboard-navigator. Location.github/agents/keyboard-navigator.agent.md. Put another way, purpose: Ensures that all interactive elements are operable by keyboard.

      +

      Alex: A solid navigation habit is to prove where you are before activating controls. Headings, landmarks, and the address bar are not trivia; they are your map.

      +

      Alex: This is where the talk moves from concept to action. This is where Example: Running an agent becomes real: what I asked: "@accessibility-lead review the heading structure of this file". That matters in practice: What it did: The lead agent delegated to the alt-text-headings specialist, which analyzed the heading levels and reported that the file skipped from H2 to H4.

      +

      Jamie: Where do you want a learner to place their attention here?

      +

      Alex: Keep the learner anchored in Example: Reading agent instructions. Looking at the.agent.md file structure.

      +

      Alex: These are the details that keep the idea from floating away. YAML frontmatter: Contains the agent name, description, and tool restrictions. Responsibilities section: Lists what the agent is designed to do. Guardrails section: Lists what the agent should NOT do or cannot do reliably.

      -

      Jamie: What do you want them to do when the plan breaks?

      -

      Alex: Start with Learning Cards: Emergency Recovery. There is something to understand, something to try, and something that proves the try worked.

      -

      Alex: The practical takeaway is this. 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. 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.

      -

      Alex: Keep the teaching thread moving. Start with 11. Alternative Git Interfaces: VS Code's Source Control panel is one way to use Git. The next useful detail is this: These alternatives exist for different workflows. Think of it like entering a new building: first you find the lobby, then the room, then the door you actually need.

      -

      Jamie: What stays the same when the tool changes?

      -

      Alex: Start with GitHub Desktop. There is something to understand, something to try, and something that proves the try worked.

      -

      Alex: The practical takeaway is this. Graphical Git client. Download: 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.

      +

      Alex: Before the learner moves on. The reason What matters matters is that the learning objective is understanding that AI agents are configurable tools with defined boundaries. That gives the learner a simple foothold: if you examined at least one agent's instructions and can explain what it does and what it will not do, you completed this challenge. The interface gets friendlier when it stops being a wall of controls and starts being a set of named places.

      +

      Jamie: Give me the version that sounds like an instructor, not a manual.

      +

      Alex: Start with 55 AI Agents Across 3 Teams and 5 Platforms: Day 2, Block 3 Material Before you read this guide: Accessibility Agents is a growing open source ecosystem: 55 AI-powered agents organized into three teams (Accessibility, GitHub Workflow, and Developer Tools), running on five platforms (GitHub Copilot,. The next useful detail is this: This chapter introduces the full landscape.

      +

      Alex: Hold that next to this. Start with Core Prerequisites (Required for All Agents). There is something to understand, something to try, and something that proves the try worked.

      +

      Alex: For a learner, the useful signals are these. [ ] Chapter 0: Pre-Workshop Setup - Git, VS Code, and GitHub account. [ ] Chapter 16: GitHub Copilot - GitHub Copilot Chat installed and working. [ ] GitHub Copilot access (Copilot Free tier is enough for this workshop). [ ].github/agents/ folder exists in your repository (or will create custom agents).

      +

      Alex: A solid pull request habit is to separate three questions: what changed, why it changed, and what still needs review. That keeps the conversation useful instead of noisy.

      -

      Alex: Keep the teaching thread moving. Start with GitHub CLI (gh). There is something to understand, something to try, and something that proves the try worked.

      -

      Alex: The practical takeaway is this. 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).

      -

      Jamie: Let's pause on Common commands. What should a learner take away from it?

      -

      Alex: Keep the learner anchored in Common commands. See Culture & Etiquette for more gh examples.

      -

      Alex: Treat examples as spoken recipes, not decorations. You may hear something like 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. Read the command, understand what it changes, then run it only when the repository state matches the lesson.

      -

      Alex: Keep the teaching thread moving. Start with Git CLI (Terminal). There is something to understand, something to try, and something that proves the try worked.

      -

      Alex: The practical takeaway is this. The standard Git command-line interface. Included with VS Code (integrated terminal: Ctrl+Backtick).

      +

      Jamie: If I am listening before the workshop starts, what should settle in my mind first?

      +

      Alex: This is where Agent Prerequisites (The "Skill First" Principle) becomes real: every agent automates a skill you should already know by hand. That matters in practice: Before using any agent, verify you have done the corresponding manual work.

      +

      Alex: That connects to another useful point. Keep the learner anchored in Workshop Recommendation (Chapter 19 / Challenge 15). Chapter 19 is the agent exploration and hands-on validation chapter - where students match agents to skills they already have and learn how to trust, evaluate, and improve AI-powered workflow automation. This is the part to say slowly: It supports Challenge 15: Meet the Agents. A good GitHub workflow is like a well-run meeting: everyone knows the topic, the next action, and who has the floor.

      +

      Alex: The parts worth keeping in working memory are these. There are 3 guided + 1-2 optional contribution challenges. Automation check: none (agent output requires human judgment before use). The evidence is issue comment showing agent output and your evaluation of it. The pattern is explore, validate, read internals, optionally contribute.

      +

      Jamie: What is the ordered workflow?

      +

      Alex: Start with Challenge 15 Set. There is something to understand, something to try, and something that proves the try worked.

      +

      Alex: First, agent Discovery Mapping - identify 3-5 agents that match skills you already have from Day 1. Then, agent Skill Validation - run one agent and evaluate its output against your manual experience. After that, agent Instructions Deep Dive - read one agent's source file and assess what it can and cannot do. Finally, improve an Existing Agent (optional hackathon) - find a gap in an agent's instructions and fix it via PR. The rhythm is simple: orient, act, verify, then continue.

      +

      Jamie: Give me the sequence, because order matters here.

      +

      Alex: First, propose a New Agent (optional hackathon) - file an issue proposing an agent for an uncovered workflow. Think of it as a rail line: each stop confirms you are still on the right route before the next one.

      -

      Jamie: Before we leave Common commands, what is the practical point?

      -

      Alex: Start with Common commands: Terminal output is plain text - more predictable than GUI elements for some operations.

      -

      Alex: Treat examples as spoken recipes, not decorations. You may hear something like 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. Read the command, understand what it changes, then run it only when the repository state matches the lesson.

      -

      Jamie: Let's pause on Try It: Clone, Branch, Commit. What should a learner take away from it?

      -

      Alex: Here is the plain-English version of Try It: Clone, Branch, Commit. Time: 5 minutes What you need: VS Code with Git configured. Put another way, do the complete Git workflow once, start to finish.

      -

      Alex: First, 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. Then, 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. After that, 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. Finally, stage - Press Ctrl+Shift+G to open Source Control. Navigate to your changed file and press Enter to stage it (or use the + button). Treat it like a recipe: do not add the next ingredient until the previous one is actually in the bowl.

      -

      Jamie: Before we leave Try It: Clone, Branch, Commit, what is the practical point?

      -

      Alex: First, commit - Tab to the message input, type feat: add new thinking phrase, press Ctrl+Enter. Then, push - Press Ctrl+Shift+P → Git: Push. It is a checklist, but a meaningful one: every item creates evidence that the next step is safe.

      -

      Jamie: Let's pause on Part 1: The GitHub Pull Requests Extension. What should a learner take away from it?

      -

      Alex: This is where The GitHub Pull Requests Extension becomes real: see also: Appendix G: VS Code Reference for the complete list of GitHub Pull Requests extension keyboard shortcuts.

      +

      Jamie: What does the learner do first, second, and then after that?

      +

      Alex: Start with Challenge 15.1 Step-by-Step: Agent Discovery Mapping: Map your Day 1 manual skills to specific agents in the ecosystem so you know which agents you are ready to use. The next useful detail is this: GitHub.com - the accessibility-agents repository and your assigned Challenge 15 issue.

      +

      Alex: On the ground, that means a few things. @daily-briefing (maps to repository and issue awareness from Chapters 2-4). @issue-tracker (maps to Chapter 4 issue workflow). @pr-review (maps to Chapter 6 and Chapter 14 review workflow). Example: You filed issues manually (Ch 4) - you can use @issue-tracker.

      +

      Alex: First, fork the accessibility-agents repository on GitHub.com. Then, open the repository and navigate to Section 3 of the README (or this chapter's Section 3 below) to see the full list of 55 agents organized by team. After that, read through the agent names and descriptions. For each one, ask yourself: "Have I done this task manually during the workshop?". Finally, identify 3-5 agents that match workflows you already practiced. Think of it as a rail line: each stop confirms you are still on the right route before the next one.

      +

      Jamie: Turn that into a path someone can follow.

      +

      Alex: First, open your assigned Challenge 15 issue. Then, post a discovery mapping comment using this format. Treat it like a recipe: do not add the next ingredient until the previous one is actually in the bowl.

      +

      Jamie: Let's pause on Challenge 15.2 Step-by-Step: Agent Skill Validation. What should a learner take away from it?

      +

      Alex: Here is the plain-English version of Challenge 15.2 Step-by-Step: Agent Skill Validation. Run one agent, read its output, and evaluate whether it matches your manual experience. Put another way, VS Code with the accessibility-agents repository cloned and Copilot Chat open.

      +

      Alex: Here is what that changes in practice. @daily-briefing morning briefing. @issue-tracker find open issues labeled good-first-issue in accessibility-agents. @pr-review show open PRs in accessibility-agents.

      +

      Alex: First, clone your fork of accessibility-agents to VS Code (or open it in github.dev). Then, open Copilot Chat: Ctrl+Shift+I (Mac: Cmd+Shift+I). After that, choose one agent from your discovery list. If unsure, start with @daily-briefing or @issue-tracker. Finally, run it with a simple prompt. Treat it like a recipe: do not add the next ingredient until the previous one is actually in the bowl.

      +

      Jamie: Before we leave Challenge 15.2 Step-by-Step: Agent Skill Validation, what is the practical point?

      +

      Alex: First, read the agent's output carefully. Take a moment to think about what you expected. Then, open your assigned Challenge 15 issue and post an evaluation comment. It is a checklist, but a meaningful one: every item creates evidence that the next step is safe.

      +

      Jamie: Let's pause on Challenge 15.3 Step-by-Step: Agent Instructions Deep Dive. What should a learner take away from it?

      +

      Alex: This is where Challenge 15.3 Step-by-Step: Agent Instructions Deep Dive becomes real: read one agent's source file to understand what instructions it follows, what tools it can use, and what mistakes it could make. That matters in practice: VS Code or GitHub.com - reading files in the accessibility-agents repository. The workshop is closer to rehearsal than lecture. You hear the move, try the move, and then check what changed.

      +

      Alex: The room should hear these as checkpoints. What is this agent trying to do? (its purpose). What tools does it have access to? (tool permissions). What constraints or guardrails are in the instructions?

      +

      Alex: First, in the accessibility-agents repository, navigate to the.github/ folder (or wherever agent definition files are stored). Then, open one.agent.md or.prompt.md file for an agent you used or are curious about. After that, read the file and identify. Finally, think critically: could this agent make a mistake? What kind? It is a checklist, but a meaningful one: every item creates evidence that the next step is safe.

      +

      Jamie: Before we leave Challenge 15.3 Step-by-Step: Agent Instructions Deep Dive, what is the practical point?

      +

      Alex: First, open your assigned Challenge 15 issue and post your analysis. It is like walking a hallway with named doors: read the sign, enter the right room, then confirm where you landed.

      -

      Alex: Keep the teaching thread moving. Keep the learner anchored in 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,. This is the part to say slowly: Prerequisites: Working with Pull Requests, Git & Source Control in VS Code Mac keyboard shortcuts: Throughout this chapter, all Ctrl+ shortcuts use Cmd+ on Mac, and Alt+ shortcuts use Option+ on Mac. A good GitHub workflow is like a well-run meeting: everyone knows the topic, the next action, and who has the floor.

      -

      Jamie: Where is the promise of the workshop, underneath all the logistics?

      -

      Alex: The reason Workshop Recommendation (Chapter 15, Part 1) matters is that chapter 15, Part 1 introduces the GitHub Pull Requests extension for managing PRs directly from VS Code.

      -

      Alex: The practical takeaway is this. There are 2 guided challenges. Automation check: none (extension installation and review state are account-local). The evidence is issue comment with confirmation of actions completed. The pattern is install, check out, review, comment.

      -

      Jamie: Let's pause on Chapter 15, Part 1 Practice Set. What should a learner take away from it?

      -

      Alex: Start with Chapter 15, Part 1 Practice Set. There is something to understand, something to try, and something that proves the try worked.

      -

      Alex: First, install the GitHub Pull Requests extension - add the extension to VS Code and sign in with your GitHub account. Then, check out a PR and post a review comment - download a PR branch locally, read the diff, and post one constructive review comment. Think of it as a rail line: each stop confirms you are still on the right route before the next one.

      +

      Jamie: Let's pause on Optional Extensions 15.4-15.5 (Hackathon). What should a learner take away from it?

      +

      Alex: Keep the learner anchored in Optional Extensions 15.4-15.5 (Hackathon). Extension 15.4: Improve an Existing Agent (45 min). This is the part to say slowly: Extension 15.5: Propose a New Agent (60 min).

      +

      Alex: That becomes easier when you listen for these cues. Find an agent whose instructions have a gap (use Section 6 suggestions or file an issue). Fork the repo, edit the agent's.agent.md file. Get a facilitator review. Open a PR with your improvement.

      +

      Alex: Another way to ground it. The reason Completing Challenge 15: Submit Your Evidence matters is that your evidence is the Challenge 15 issue comments for 15.1, 15.2, and 15.3. That gives the learner a simple foothold: for optional extensions, your PR or proposal issue is the evidence.

      +

      Jamie: Let's pause on Expected Outcomes. What should a learner take away from it?

      +

      Alex: Start with Expected Outcomes. There is something to understand, something to try, and something that proves the try worked.

      +

      Alex: A few details make that real. Student can map personal Day 1 skills to specific agents in the ecosystem. Student understands the Skill First, Agent Second principle and can articulate why agent output requires human judgment. Student can read agent instructions and evaluate what an agent can and cannot do. Student has used at least one agent and verified it against manual skills. (Optional) Student has contributed to the accessibility-agents ecosystem with a fix, improvement, or proposal.

      -

      Jamie: Let's pause on Practice 15.1 Step-by-Step: Install the Extension. What should a learner take away from it?

      -

      Alex: Here is the plain-English version of Practice 15.1 Step-by-Step: Install the Extension. Install the GitHub Pull Requests and Issues extension and authenticate with your GitHub account. Put another way, VS Code desktop with your Learning Room repository open.

      -

      Alex: First, open the Extensions sidebar: Ctrl+Shift+X (Mac: Cmd+Shift+X). Then, your screen reader announces "Extensions: Marketplace." The search box has focus. After that, type GitHub Pull Requests in the search box and press Enter. Finally, navigate down the results list. Select GitHub Pull Requests (publisher: GitHub). Treat it like a recipe: do not add the next ingredient until the previous one is actually in the bowl.

      -

      Jamie: Before we leave Practice 15.1 Step-by-Step: Install the Extension, what is the practical point?

      -

      Alex: First, activate the Install button. VS Code installs the extension and may show a notification. Then, after installation, VS Code prompts you to sign in. Activate Sign in to GitHub. After that, a browser window opens for GitHub OAuth. Approve the authorization and return to VS Code. Finally, verify: open the Explorer sidebar (Ctrl+Shift+E). You should now see a GitHub section in the sidebar showing Pull Requests and Issues. It is a checklist, but a meaningful one: every item creates evidence that the next step is safe.

      -

      Jamie: Let's pause on Practice 15.2 Step-by-Step: Check Out a PR and Post a Comment. What should a learner take away from it?

      -

      Alex: This is where Practice 15.2 Step-by-Step: Check Out a PR and Post a Comment becomes real: check out someone else's PR branch locally, read the diff in VS Code, and post one constructive review comment. That matters in practice: VS Code with the GitHub Pull Requests extension installed. The workshop is closer to rehearsal than lecture. You hear the move, try the move, and then check what changed.

      -

      Alex: First, open the Command Palette: Ctrl+Shift+P (Mac: Cmd+Shift+P). Then, type GitHub Pull Requests: Focus on Pull Requests View and select it. The Pull Requests panel opens. After that, navigate the list of open PRs. Find one that is not yours (a classmate's PR from Chapter 6, 7, or 14). Finally, 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. It is a checklist, but a meaningful one: every item creates evidence that the next step is safe.

      -

      Jamie: Before we leave Practice 15.2 Step-by-Step: Check Out a PR and Post a Comment, what is the practical point?

      -

      Alex: First, open the Command Palette again and run GitHub Pull Requests: Open Changed Files. This shows the list of files the PR changed. Then, open one changed file. VS Code opens the Diff Editor showing old content on the left and new content on the right. After that, 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). Finally, find one specific thing to comment on: a typo, an unclear sentence, a missing step, or something the author did well. It is like walking a hallway with named doors: read the sign, enter the right room, then confirm where you landed.

      -

      Jamie: What should the learner prove to themselves after each small task?

      -

      Alex: Keep the learner anchored in Completing Chapter 15, Part 1: Submit Your Evidence. Open your assigned setup or review practice issue and post a completion comment. This is the part to say slowly: Close your Chapter 12 challenge issues when done.

      +

      Jamie: Let's pause on If You Get Stuck. What should a learner take away from it?

      +

      Alex: Here is the plain-English version of If You Get Stuck. Continue learning: The GitHub Skills courses Build Applications with Copilot Agent Mode and Expand Your Team with Copilot explore agent-powered development workflows. Put another way, see Appendix Z for the full catalog. It is like learning a transit route. The names of the stops matter because they tell you whether you are still going the right direction.

      +

      Alex: First, cannot find an agent that matches your skills? Start with @daily-briefing or @issue-tracker - those build directly on Chapter 2-5 material. If you have not done those manual steps yet, go back to those chapters first. Then, agent output does not make sense? That is the right response. Paste the output in an issue comment along with your confusion. That is valuable feedback - the agent may need better instructions or guardrails. After that, cannot access the agents in Copilot Chat? Verify: Is Copilot Chat extension installed (not just base Copilot)? Are you signed in to GitHub in VS Code? Does.github/agents/ folder exist in your cloned repository? Finally, repository will not clone? Use the terminal: git clone https://github.com/[your-username]/accessibility-agents.git then open the folder in VS Code. Treat it like a recipe: do not add the next ingredient until the previous one is actually in the bowl.

      +

      Jamie: Before we leave If You Get Stuck, what is the practical point?

      +

      Alex: First, ask facilitator to show them what agent you wanted to run, what output you got, and what you expected. Then, finished but not sure you did it right? Compare your work against the Challenge 15 reference solution. It is a checklist, but a meaningful one: every item creates evidence that the next step is safe.

      +

      Jamie: Let's pause on Learning Moment. What should a learner take away from it?

      +

      Alex: This is where Learning Moment becomes real: the 55 agents exist because someone did the manual work first, then automated the repetitive parts. That matters in practice: As you explore agents, you are not just learning tools - you are learning what automation looks like when it is built on real expertise and real constraints.

      +

      Jamie: Let's pause on Learning Pattern Used in This Chapter. What should a learner take away from it?

      +

      Alex: Start with Learning Pattern Used in This Chapter. There is something to understand, something to try, and something that proves the try worked.

      +

      Alex: First, map your existing skills to available tools (discovery before action). Then, run one tool and evaluate its output critically (trust but verify). After that, read the source to understand capabilities and limits (internals matter). Finally, contribute improvements based on your evaluation (close the feedback loop). It is like walking a hallway with named doors: read the sign, enter the right room, then confirm where you landed.

      -

      Alex: Keep the teaching thread moving. Start with Expected Outcomes. There is something to understand, something to try, and something that proves the try worked.

      -

      Alex: The practical takeaway is this. 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.

      -

      Jamie: What is the teaching move inside If You Get Stuck?

      -

      Alex: Start with If You Get Stuck: Continue learning: The GitHub Skills course Review Pull Requests practices approving, requesting changes, and using suggestions in an interactive format. The next useful detail is this: See Appendix Z for the full catalog.

      -

      Alex: First, extension does not install? Reload VS Code: Ctrl+Shift+P, then run Developer: Reload Window. Then, oAuth sign-in fails? Verify your GitHub account is active in the browser first, close VS Code, reopen, and retry. After that, pR list is empty? Switch to "All Open" view in the GitHub Pull Requests panel. Finally, checkout fails? Confirm you have write access to the repository. If not, use the read-only GitHub.com fallback. Think of it as a rail line: each stop confirms you are still on the right route before the next one.

      -

      Jamie: If someone only remembers one thing from If You Get Stuck, what should it be?

      -

      Alex: First, diff Editor is hard to navigate? Press F7 for the Accessible Diff Viewer mode, which is purpose-built for screen readers. Then, cannot find the Add Comment command? Use Command Palette and search for GitHub Pull Requests: Add Comment. After that, ask facilitator to help verify the GitHub PR panel and model one review comment. Finally, finished but not sure you did it right? Compare your work against the Challenge 11 reference solution. Treat it like a recipe: do not add the next ingredient until the previous one is actually in the bowl.

      -

      Alex: Keep the teaching thread moving. Here is the plain-English version of Learning Moment. Reviewing others' work refines your own standards and builds community trust. Put another way, the comment you just wrote helps another student learn - and you learn by articulating what makes documentation clear. It is like learning a transit route. The names of the stops matter because they tell you whether you are still going the right direction.

      +

      Jamie: Let's pause on Capstone: Share Your Feedback (The Most Important Task!). What should a learner take away from it?

      +

      Alex: The reason Capstone: Share Your Feedback (The Most Important Task!) matters is that you have now explored the full agent ecosystem, completed the workshop, and have valuable perspective on what worked, what confused you, and what we should improve for the next cohort. That gives the learner a simple foothold: your feedback directly shapes the future of this project.

      +

      Alex: Here is the practical turn. Start with Submit Workshop Feedback: Use the Workshop Feedback form to share. The next useful detail is this: Answer as much or as little as you're comfortable sharing. Think of it like entering a new building: first you find the lobby, then the room, then the door you actually need.

      +

      Alex: The practical takeaway is this. Which agents stood out? (Most useful or surprising). Which agents confused you? (What would make them better). Was the chapter progression logical? (Did earlier chapters prepare you for later ones). Accessibility experience (If applicable - did any assistive technology work/fail?).

      +

      Jamie: Let's pause on 1. The Principle: Skill First, Agent Second. What should a learner take away from it?

      +

      Alex: Here is the plain-English version of 1. The Principle: Skill First, Agent Second. Accessibility Agents is not a way to skip learning GitHub. Put another way, it is a way to amplify skills you have already built through deliberate practice.

      +

      Alex: The practical takeaway is this. Verify that the agent's output is correct. Catch when the agent misses context that only you have. Edit the agent's drafts into something worth posting under your name. Know when the agent is confidently wrong.

      -

      Jamie: What is the teaching move inside Learning Pattern Used in This Chapter?

      -

      Alex: First, install and configure the tool before starting the task. Then, practice on someone else's work first (reviewing is safer than authoring). After that, use accessibility tools (F7 Accessible Diff Viewer) to navigate efficiently. Finally, write specific, constructive feedback (not just "looks good"). It is a checklist, but a meaningful one: every item creates evidence that the next step is safe.

      -

      Alex: Keep the teaching thread moving. Keep the learner anchored in 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.

      -

      Jamie: Let's pause on Method 1: Extensions Sidebar. What should a learner take away from it?

      -

      Alex: Start with Method 1: Extensions Sidebar. There is something to understand, something to try, and something that proves the try worked.

      -

      Alex: First, open Extensions sidebar: Ctrl+Shift+X (Mac: Cmd+Shift+X). Then, type "GitHub Pull Requests" in the search box. After that, find "GitHub Pull Requests and Issues" (publisher: GitHub). Finally, navigate to the extension in the results list. The rhythm is simple: orient, act, verify, then continue.

      -

      Jamie: Before we leave Method 1: Extensions Sidebar, what is the practical point?

      -

      Alex: First, press Enter to open the extension detail page. Then, tab to "Install" button → press Enter. Think of it as a rail line: each stop confirms you are still on the right route before the next one.

      +

      Alex: Keep the thread going. This is where Every agent has a manual prerequisite. If you have not done the corresponding skill by hand, the agent is not ready for you yet - and you are not ready for it becomes real: this applies across all three teams and all 55 agents. That matters in practice: Before running any agent, the facilitator asks the same question.

      +

      Alex: The practical takeaway is this. GitHub Workflow agents automate repository navigation, issue triage, PR review, and contribution analytics - skills you practiced on Day 1. Accessibility agents automate WCAG auditing, contrast checking, keyboard navigation review, and document scanning - knowledge from your accessibility training and the standards in Appendix C. Developer Tools agents automate accessible coding patterns for Python, wxPython, and desktop applications - skills from your development experience.

      +

      Jamie: Let's pause on Learning Cards: Skill First, Agent Second. What should a learner take away from it?

      +

      Alex: Start with Learning Cards: Skill First, Agent Second. There is something to understand, something to try, and something that proves the try worked.

      +

      Alex: The practical takeaway is this. Before using any agent, verify you can do the task manually -- for @daily-briefing, confirm you can navigate Issues and PRs on GitHub.com with keyboard shortcuts (j/k to move, Enter to open). Agent output appears in Copilot Chat -- press Alt+F2 to open Accessible View and read the full response with arrow keys before acting on it. If an agent produces something you do not understand, stop and learn the manual skill first from the relevant chapter. Agent responses appear in the Copilot Chat panel -- drag the panel wider or use Alt+F2 (Accessible View) for a larger, cleaner reading pane. Each agent's instructions are in a.agent.md file you can open in VS Code and read at your preferred zoom level before invoking the agent. The agent ecosystem table in Section 3 uses standard Markdown tables that scale with your editor font size.

      +

      Alex: This is the part worth saying out loud. The reason Quick Install (One Command) matters is that accessibility Agents now ships with a one-liner installer that sets up all 55 agents for your platform. The interface gets friendlier when it stops being a wall of controls and starts being a set of named places.

      -

      Jamie: Before we leave Method 2: Command Palette, what is the practical point?

      -

      Alex: Start with Method 2: Command Palette: The Extensions sidebar is a tree view. The next useful detail is this: Use Up/Down Arrow to navigate, Enter to open an extension's detail page. Think of it like entering a new building: first you find the lobby, then the room, then the door you actually need.

      -

      Alex: First, ctrl+Shift+P. Then, type "install extensions". After that, select "Extensions: Install Extensions". Finally, search for "GitHub Pull Requests". Think of it as a rail line: each stop confirms you are still on the right route before the next one.

      -

      Jamie: What is the teaching move inside Method 2: Command Palette?

      -

      Alex: First, install "GitHub Pull Requests and Issues". Treat it like a recipe: do not add the next ingredient until the previous one is actually in the bowl.

      -

      Jamie: Let's pause on Signing In to GitHub. What should a learner take away from it?

      -

      Alex: Here is the plain-English version of Signing In to GitHub. After installation, VS Code prompts you to sign in.

      -

      Alex: First, a notification appears: "Sign in to GitHub to use Pull Requests". Then, navigate to the notification (Alt+N / Mac: Option+N, or status bar navigation). After that, select "Sign in". Finally, VS Code opens your browser for GitHub OAuth authentication. Treat it like a recipe: do not add the next ingredient until the previous one is actually in the bowl.

      -

      Jamie: Before we leave Signing In to GitHub, what is the practical point?

      -

      Alex: First, authorize VS Code in the browser. Then, return to VS Code - you're now signed in. It is a checklist, but a meaningful one: every item creates evidence that the next step is safe.

      -

      Alex: Keep the teaching thread moving. Start with Verify sign-in. There is something to understand, something to try, and something that proves the try worked.

      -

      Alex: The practical takeaway is this. 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.

      +

      Jamie: What is the safe way to learn from that example?

      +

      Alex: Start with macOS / Linux. There is something to understand, something to try, and something that proves the try worked.

      +

      Alex: Treat examples as spoken recipes, not decorations. You may hear something like curl -fsSL https://raw.githubusercontent.com/Community-Access/accessibility-agents/main/install.sh bash. Read the command, understand what it changes, then run it only when the repository state matches the lesson.

      +

      Alex: The next layer is this. Here is the plain-English version of Windows (PowerShell). The installer detects which AI tools you have installed (VS Code with Copilot, Claude Code, Gemini CLI, Claude Desktop, Codex CLI) and configures the appropriate agent files for each platform. Put another way, to uninstall, run the corresponding uninstall script from the repository.

      +

      Jamie: Let's pause on Workshop Setup (Fork and Clone). What should a learner take away from it?

      +

      Alex: This is where Workshop Setup (Fork and Clone) becomes real: for the workshop, you will also fork and clone the repository so you can make contributions. That matters in practice: If Copilot Chat works, the agents work.

      +

      Alex: First, fork accessibility-agents to your GitHub account (you did this on Day 1 or Day 2 morning). Then, clone your fork. After that, open in VS Code: navigate to the folder and run code. (or File, then Open Folder). Finally, open Copilot Chat: Ctrl+Shift+I. It is a checklist, but a meaningful one: every item creates evidence that the next step is safe.

      +

      Jamie: Before we leave Workshop Setup (Fork and Clone), what is the practical point?

      +

      Alex: First, test: type @daily-briefing morning briefing and press Enter. It is like walking a hallway with named doors: read the sign, enter the right room, then confirm where you landed.

      +

      Alex: Treat examples as spoken recipes, not decorations. You may hear something like git clone https://github.com/[your-username]/accessibility-agents.git. Read the command, understand what it changes, then run it only when the repository state matches the lesson.

      -

      Jamie: Let's pause on What the Extension Adds. What should a learner take away from it?

      -

      Alex: Start with What the Extension Adds. There is something to understand, something to try, and something that proves the try worked.

      -

      Alex: The practical takeaway is this. 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.

      -

      Alex: Keep the teaching thread moving. Start with Learning Cards: Installing the PR Extension. There is something to understand, something to try, and something that proves the try worked.

      -

      Alex: The practical takeaway is this. 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". 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.

      -

      Jamie: Let's pause on Method 1: Activity Bar. What should a learner take away from it?

      -

      Alex: Start with Method 1: Activity Bar: Click the GitHub logo icon in the Activity Bar (the vertical strip of icons on the far left). The next useful detail is this: The GitHub Pull Requests panel opens.

      -

      Alex: The practical takeaway is this. "Pull Requests". "Issues".

      -

      Alex: First, the Activity Bar is not always reachable by Tab from the editor. Then, use Ctrl+Shift+P (Mac: Cmd+Shift+P) → type "GitHub Pull Requests: View Pull Request" or "Focus on Pull Requests View" → press Enter. After that, alternatively press Ctrl+Shift+G (Mac: Cmd+Shift+G) to open Source Control, then Tab until you reach the Activity Bar icon strip. Finally, navigate to the repository on GitHub.com. Think of it as a rail line: each stop confirms you are still on the right route before the next one.

      -

      Jamie: Before we leave Method 1: Activity Bar, what is the practical point?

      -

      Alex: First, click the Pull requests tab. Then, click any PR title to view its conversation, commits, and changed files. After that, use the Files changed tab to review diffs. Treat it like a recipe: do not add the next ingredient until the previous one is actually in the bowl.

      -

      Alex: Treat examples as spoken recipes, not decorations. You may hear something like 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". Read the command, understand what it changes, then run it only when the repository state matches the lesson.

      +

      Alex: Keep the teaching thread moving. Start with Prerequisites. There is something to understand, something to try, and something that proves the try worked.

      +

      Alex: The practical takeaway is this. GitHub Copilot Chat extension installed (see GitHub Copilot: Installation). Signed in to GitHub via VS Code. A workspace open containing.github/agents/ folder with.agent.md files.

      +

      Jamie: Let's pause on How Agents Are Discovered. What should a learner take away from it?

      +

      Alex: The reason How Agents Are Discovered matters is that when you type @ in Copilot Chat, VS Code scans. That gives the learner a simple foothold: the Accessibility Agents ecosystem installs agents appropriate to each platform.

      +

      Alex: First,.github/agents/.agent.md in your current workspace. Then, any agents installed globally on your machine. After that, agents defined by extensions. The rhythm is simple: orient, act, verify, then continue.

      +

      Alex: Keep the teaching thread moving. Start with Optional: Personalize Your Instance: Open preferences.md in VS Code and edit. The next useful detail is this: Commit preferences.md to your fork.

      -

      Jamie: Let's pause on Method 2: Explorer Section. What should a learner take away from it?

      -

      Alex: Start with Method 2: Explorer Section. There is something to understand, something to try, and something that proves the try worked.

      -

      Alex: First, open Explorer: Ctrl+Shift+E (Mac: Cmd+Shift+E). Then, navigate with Arrow keys to find the "GitHub Pull Requests" section. After that, expand it with Right Arrow. Treat it like a recipe: do not add the next ingredient until the previous one is actually in the bowl.

      -

      Jamie: Let's pause on Description. What should a learner take away from it?

      -

      Alex: This is where Description becomes real: the GitHub Pull Requests panel has two top-level sections. That matters in practice: "My Pull Requests" contains four filters: Assigned to Me, Created by Me, Waiting for my Review, and All Open.

      -

      Alex: Keep the teaching thread moving. Keep the learner anchored in Screen reader announcement example. "Pull Request 42: Add Timeline Guide, opened by jeffb, 2 days ago, 3 files changed". A good GitHub workflow is like a well-run meeting: everyone knows the topic, the next action, and who has the floor.

      +

      Jamie: Let's pause on How Agents Travel with Your Repo. What should a learner take away from it?

      +

      Alex: Here is the plain-English version of How Agents Travel with Your Repo. When you fork accessibility-agents, the.github/agents/ folder comes with it.

      +

      Alex: The practical takeaway is this. Any collaborator who clones your fork gets all 55 agents automatically. You can customize agents for your specific project by editing the.agent.md files in your fork. Any project can have agents - create a.github/agents/ folder in any repository and add.agent.md files using the same pattern. The one-liner installer can also set up agents globally, so they are available in every workspace you open.

      +

      Alex: Keep the teaching thread moving. This is where Invoking Agents on GitHub.com becomes real: accessibility Agents agents run in VS Code. That matters in practice: But the same.agent.md files can also be invoked directly on GitHub.com - no VS Code, no local clone required. The workshop is closer to rehearsal than lecture. You hear the move, try the move, and then check what changed.

      +

      Jamie: Let's pause on Option 1: Copilot Chat with Task mode. What should a learner take away from it?

      +

      Alex: Keep the learner anchored in Option 1: Copilot Chat with Task mode. Screen reader users (NVDA / JAWS / VoiceOver).

      +

      Alex: First, open Copilot Chat on GitHub.com (icon in the top-right navigation bar). Then, click Task in the mode picker. After that, optionally click the agent picker to select a custom agent. Finally, type your request and click Send. It is like walking a hallway with named doors: read the sign, enter the right room, then confirm where you landed.

      +

      Jamie: Before we leave Option 1: Copilot Chat with Task mode, what is the practical point?

      +

      Alex: First, Copilot analyzes the task and can create a branch and open a PR automatically. Then, open Copilot Chat on GitHub.com (navigate to icon in top-right navigation → Enter). After that, the mode picker (Task vs Chat) is a set of radio buttons - navigate with Arrow keys to select "Task". Finally, the agent picker is a listbox - Up/Down Arrow to navigate, Enter to select. The rhythm is simple: orient, act, verify, then continue.

      -

      Jamie: Let's pause on By status. What should a learner take away from it?

      -

      Alex: Start with By status. There is something to understand, something to try, and something that proves the try worked.

      -

      Alex: The practical takeaway is this. "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.

      -

      Alex: Keep the teaching thread moving. Start with By repository: The tree organizes PRs by repository.

      -

      Jamie: Let's pause on Viewing PR Details. What should a learner take away from it?

      -

      Alex: Here is the plain-English version of Viewing PR Details. A PR detail view opens in the editor area showing.

      -

      Alex: The practical takeaway is this. 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).

      -

      Alex: First, navigate to a PR in the tree. Then, press Enter. Treat it like a recipe: do not add the next ingredient until the previous one is actually in the bowl.

      +

      Jamie: Let's pause on Option 2: Assign an issue to Copilot. What should a learner take away from it?

      +

      Alex: The reason Option 2: Assign an issue to Copilot matters is that screen reader users (NVDA / JAWS / VoiceOver). That gives the learner a simple foothold: this is the bridge to Section 6 (The Cloud Extension).

      +

      Alex: First, open any issue (or create a new one describing the task). Then, in the Assignees sidebar section, click the gear icon. After that, in the dropdown, click Copilot as the assignee. Finally, a dialog opens - optionally provide additional instructions and select a custom agent. The rhythm is simple: orient, act, verify, then continue.

      +

      Jamie: Before we leave Option 2: Assign an issue to Copilot, what is the practical point?

      +

      Alex: First, click Assign to confirm. Then, open any issue in the repository. After that, press B to navigate to the Assignees gear button → Enter to open the popup. Finally, navigate the popup with Arrow keys → find "Copilot" → Enter to select. Think of it as a rail line: each stop confirms you are still on the right route before the next one.

      +

      Alex: A solid issue habit is to read the title, the body, and the timeline before acting. You are listening for the requested action, the missing evidence, and the person who needs a response.

      +

      Jamie: What should someone listen for when a lesson offers more than one tool path?

      +

      Alex: Start with Copilot on GitHub.com - Browser-Native Features: Beyond assigning Copilot to issues and using Task mode in Chat, GitHub.com now has several standalone Copilot features built directly into the web interface. The next useful detail is this: These work entirely in your browser - no VS Code, no local clone needed.

      +

      Alex: Keep the teaching thread moving. Here is the plain-English version of Copilot PR Summary. On any open pull request, GitHub adds a "Summarize" button in the PR description area. Put another way, selecting it generates a plain-language summary of what the PR changes, why, and what reviewers should focus on. It is like learning a transit route. The names of the stops matter because they tell you whether you are still going the right direction.

      -

      Alex: Keep the teaching thread moving. Start with Screen reader experience. There is something to understand, something to try, and something that proves the try worked.

      -

      Alex: The practical takeaway is this. 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.

      -

      Jamie: Let's pause on 3. Checking Out a Pull Request Branch. What should a learner take away from it?

      -

      Alex: Keep the learner anchored in 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.

      -

      Alex: Keep the teaching thread moving. Start with Why Check Out a PR. There is something to understand, something to try, and something that proves the try worked.

      -

      Alex: The practical takeaway is this. 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.

      +

      Jamie: Let's pause on Copilot PR Review. What should a learner take away from it?

      +

      Alex: This is where Copilot PR Review becomes real: on open PRs you have write access to review, a "Review" button (or Copilot icon) appears in the Files changed tab. That matters in practice: Copilot generates inline review comments across the diff.

      +

      Alex: Keep the teaching thread moving. Keep the learner anchored in Copilot in Issues. On any issue page, Copilot adds sidebar buttons that appear once the page loads. This is the part to say slowly: Look in the right sidebar on any issue page for a Copilot section with "Explain" and "Suggest fix" buttons.

      +

      Alex: The practical takeaway is this. "Explain this issue" - generates a plain-language explanation of a complex technical issue. "Suggest fix" - proposes an approach to resolving the issue (opens a task/PR workflow).

      +

      Jamie: Let's pause on GitHub Models - Free AI Playground. What should a learner take away from it?

      +

      Alex: The reason GitHub Models - Free AI Playground matters is that github.com/marketplace/models is a free playground where you can test AI models (OpenAI GPT-4o, Meta Llama 3, Mistral, Phi-4 Mini, and others) directly in your browser. That gives the learner a simple foothold: why it matters for Accessibility Agents: When you build custom agents and prompts, you can test your system prompts and prompt templates in GitHub Models before adding them to your.prompt.md files - rapid iteration without burning API credits.

      +

      Alex: The practical takeaway is this. Send prompts to any listed model and compare responses side by side. Adjust parameters (temperature, max tokens) without any setup. Use the code sample generator to get API code for your chosen model. All free with a GitHub account (rate-limited for free tier).

      -

      Jamie: Let's pause on Method 1: From the PR Detail View. What should a learner take away from it?

      -

      Alex: Start with Method 1: From the PR Detail View. There is something to understand, something to try, and something that proves the try worked.

      -

      Alex: The practical takeaway is this. Downloads the branch. Switches your local repository to that branch. Opens the changed files in the editor.

      -

      Alex: First, open a PR (see Section 2). Then, in the PR detail view, navigate to "Checkout" button. After that, press Enter. Think of it as a rail line: each stop confirms you are still on the right route before the next one.

      -

      Jamie: Let's pause on Method 2: From the PR Tree. What should a learner take away from it?

      -

      Alex: Start with Method 2: From the PR Tree. There is something to understand, something to try, and something that proves the try worked.

      -

      Alex: First, navigate to the PR in the GitHub Pull Requests tree. Then, press Shift+F10 (Mac: Ctrl+Return) to open context menu. After that, select "Checkout Pull Request". Treat it like a recipe: do not add the next ingredient until the previous one is actually in the bowl.

      -

      Jamie: Let's pause on Method 3: Command Palette. What should a learner take away from it?

      -

      Alex: This is where Method 3: Command Palette becomes real: after checkout, the bottom-left status bar shows the branch name (example: "jeffb/add-timeline-guide"). That matters in practice: Your local files now match that branch.

      -

      Alex: First, ctrl+Shift+P (Mac: Cmd+Shift+P). Then, type "GitHub Pull Requests: Checkout". After that, select "GitHub Pull Requests: Checkout Pull Request". Finally, choose the PR from the list. It is a checklist, but a meaningful one: every item creates evidence that the next step is safe.

      +

      Alex: Keep the teaching thread moving. Start with Copilot-Drafted Release Notes: When creating a release (Releases tab → Draft a new release), GitHub provides a "Generate release notes" button. The next useful detail is this: It scans merged PRs since the last release and drafts categorized release notes automatically. Think of it like entering a new building: first you find the lobby, then the room, then the door you actually need.

      +

      Jamie: What is the pre-flight check here?

      +

      Alex: Start with Learning Cards: Setup and Configuration. There is something to understand, something to try, and something that proves the try worked.

      +

      Alex: The practical takeaway is this. Run the installer command in the VS Code terminal (Ctrl+) -- it announces progress as it copies agent files to.github/agents/`. After installation, press Ctrl+Shift+E to open the Explorer and navigate to.github/agents/ to verify agent files are present. Edit.github/agents/preferences.md to configure your username, repositories, and notification preferences -- it is a standard Markdown file. The installer creates files in.github/agents/ and.github/prompts/ -- verify in the Explorer sidebar that these folders appeared. Open preferences.md in the editor to set your configuration -- use Ctrl+= to zoom if the YAML frontmatter is hard to read. Agent files use.agent.md extension -- they appear alongside regular Markdown files in the Explorer but are distinguished by their extension.

      +

      Alex: Keep the teaching thread moving. This is where 3. The Ecosystem: 55 Agents, 3 Teams, 5 Platforms becomes real: accessibility Agents is an ecosystem of 55 specialized agents organized into three teams, each addressing a different dimension of accessible software development. That matters in practice: Browse all three teams below, then choose the agents that match your current skills and interests.

      -

      Jamie: Let's pause on Returning to Your Original Branch. What should a learner take away from it?

      -

      Alex: Start with Returning to Your Original Branch. There is something to understand, something to try, and something that proves the try worked.

      -

      Alex: First, ctrl+Shift+P (Mac: Cmd+Shift+P). Then, type "git checkout". After that, select "Git: Checkout to.". Finally, choose your original branch (usually main or your feature branch). It is like walking a hallway with named doors: read the sign, enter the right room, then confirm where you landed.

      -

      Jamie: Let's pause on Learning Cards: Checking Out a PR. What should a learner take away from it?

      -

      Alex: Start with Learning Cards: Checking Out a PR. There is something to understand, something to try, and something that proves the try worked.

      -

      Alex: The practical takeaway is this. 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. 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.

      -

      Alex: Keep the teaching thread moving. Start with 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. Think of it like entering a new building: first you find the lobby, then the room, then the door you actually need.

      +

      Jamie: Let's pause on Team 1: Accessibility (26 agents). What should a learner take away from it?

      +

      Alex: Keep the learner anchored in Team 1: Accessibility (26 agents). These agents audit, fix, and enforce accessibility across web, document, and mobile platforms.

      +

      Alex: Keep the teaching thread moving. The reason Team 2: GitHub Workflow (12 agents) matters is that these agents automate GitHub operations - issue triage, PR review, contribution analytics, and repository management. The interface gets friendlier when it stops being a wall of controls and starts being a set of named places.

      +

      Jamie: What stays the same when the tool changes?

      +

      Alex: Start with Team 3: Developer Tools (6 agents): These agents support accessible application development across desktop and cross-platform frameworks.

      -

      Jamie: Let's pause on In the PR detail view. What should a learner take away from it?

      -

      Alex: Start with In the PR detail view. There is something to understand, something to try, and something that proves the try worked.

      -

      Alex: First, scroll down to "Files Changed" section. Then, each file is a link. After that, navigate with Arrow keys. Finally, press Enter on a file to open its diff view. Treat it like a recipe: do not add the next ingredient until the previous one is actually in the bowl.

      -

      Alex: Keep the teaching thread moving. This is where Screen reader announcement becomes real: "docs/11-vscode-interface.md, 42 additions, 3 deletions".

      -

      Jamie: Let's pause on Understanding the Diff View. What should a learner take away from it?

      -

      Alex: Keep the learner anchored in Understanding the Diff View. When you open a file from "Files Changed".

      +

      Alex: Keep the teaching thread moving. Here is the plain-English version of Beyond Agents: The Supporting Ecosystem. The 55 agents are backed by additional resources in the repository.

      +

      Jamie: Let's pause on Hook-Based Enforcement (Claude Code). What should a learner take away from it?

      +

      Alex: This is where Hook-Based Enforcement (Claude Code) becomes real: on Claude Code, Accessibility Agents includes a hook system that enforces accessibility standards automatically. That matters in practice: This means accessibility enforcement happens whether or not the developer remembers to ask for it.

      +

      Alex: First, proactive detection hook - scans every file edit for accessibility regressions before they are committed. Then, edit gate hook - blocks commits that introduce WCAG violations until they are fixed. After that, session marker hook - tracks which accessibility checks have run during the current session. It is a checklist, but a meaningful one: every item creates evidence that the next step is safe.

      +

      Alex: Keep the teaching thread moving. Keep the learner anchored in What Would You Build? This is the question that matters most. This is the part to say slowly: The 55 agents that exist today were built by contributors who saw a gap and filled it. A good GitHub workflow is like a well-run meeting: everyone knows the topic, the next action, and who has the floor.

      +

      Alex: The practical takeaway is this. "Why is there no agent for [framework] accessibility patterns?". "I spend 30 minutes on [task] every week - could an agent do the repetitive part?". "This agent is good but it misses [specific edge case] - I could improve those instructions". "Mobile native accessibility testing has no agent coverage yet - I could start one".

      -

      Alex: Keep the teaching thread moving. Start with Split view mode (default). There is something to understand, something to try, and something that proves the try worked.

      -

      Alex: The practical takeaway is this. Left side: original file (before changes). Right side: modified file (after changes). Changed lines highlighted (added = green, removed = red).

      -

      Jamie: Let's pause on Inline view mode. What should a learner take away from it?

      -

      Alex: Start with Inline view mode. There is something to understand, something to try, and something that proves the try worked.

      -

      Alex: The practical takeaway is this. Single editor. Removed lines shown with - prefix. Added lines shown with + prefix.

      -

      Alex: Keep the teaching thread moving. Start with To toggle between views. There is something to understand, something to try, and something that proves the try worked.

      -

      Alex: The practical takeaway is this. Command Palette: Ctrl+Shift+P (Mac: Cmd+Shift+P) → "Diff: Toggle Inline View".

      +

      Jamie: Let's pause on The contribution paths are. What should a learner take away from it?

      +

      Alex: The reason The contribution paths are matters is that see the Accessibility Agents CONTRIBUTING guide for detailed instructions on each path.

      +

      Alex: First, report an agent gap - file an issue describing what is missing and why it matters. Then, improve existing agent instructions - make an agent smarter about edge cases it misses. After that, add framework-specific patterns - teach agents about React, Vue, Angular, Svelte, or other framework accessibility patterns. Finally, fix installer issues - improve the one-liner scripts for different OS configurations. The rhythm is simple: orient, act, verify, then continue.

      +

      Jamie: Before we leave The contribution paths are, what is the practical point?

      +

      Alex: First, write documentation - help others understand how to use and contribute to agents. Think of it as a rail line: each stop confirms you are still on the right route before the next one.

      +

      Alex: Keep the teaching thread moving. Start with Roadmap: What Is Coming Next: Your contribution could be the next item that ships. The next useful detail is this: Every agent started as one person's idea and one pull request.

      +

      Alex: The practical takeaway is this. Mobile native agents - agents specialized for iOS (VoiceOver) and Android (TalkBack) native app accessibility. Anthropic Connectors listing - making agents discoverable through the Anthropic marketplace. veraPDF integration - automated PDF/UA validation for the PDF accessibility agent. Document remediation agents - agents that fix accessibility issues in documents, not just find them.

      +

      Jamie: Let's pause on Learning Cards: The Agent Ecosystem. What should a learner take away from it?

      +

      Alex: Start with Learning Cards: The Agent Ecosystem. There is something to understand, something to try, and something that proves the try worked.

      +

      Alex: The practical takeaway is this. The three team tables use standard Markdown table format -- navigate with T (NVDA/JAWS) to jump between tables, then Arrow keys to read cells. Agent names start with @ -- type @ followed by the agent name in Copilot Chat to invoke it (e.g., @daily-briefing). Use Ctrl+Shift+O (symbol outline) in any agent file to navigate between its YAML frontmatter sections (Purpose, Responsibilities, Guardrails). The agent tables are dense -- use Ctrl+= to increase font size or open the file in Markdown Preview (Ctrl+Shift+V) for cleaner rendering. Each team has a distinct table: Team 1 (Accessibility, 26 agents), Team 2 (GitHub Workflow, 15 agents), Team 3 (Developer Tools, 14 agents). Agent files in.github/agents/ have descriptive filenames that match the @agent-name -- browse them in the Explorer to find specific agents.

      -

      Jamie: Let's pause on Recommended workflow for screen reader users. What should a learner take away from it?

      -

      Alex: Start with Recommended workflow for screen reader users. There is something to understand, something to try, and something that proves the try worked.

      -

      Alex: The practical takeaway is this. Unchanged lines (for context). Removed lines (prefixed with -). Added lines (prefixed with +).

      -

      Alex: First, open a changed file from the PR detail view. Then, press F7 to jump to the first diff hunk. After that, press Alt+F2 (Mac: Option+F2) to open Accessible View. Finally, read the hunk content. It is a checklist, but a meaningful one: every item creates evidence that the next step is safe.

      -

      Jamie: Before we leave Recommended workflow for screen reader users, what is the practical point?

      -

      Alex: First, press Escape to close Accessible View. Then, press F7 to jump to the next hunk. After that, repeat until all hunks reviewed. It is like walking a hallway with named doors: read the sign, enter the right room, then confirm where you landed.

      -

      Alex: Keep the teaching thread moving. Keep the learner anchored in 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. This is the part to say slowly: Previously, deleted code could only be read, not selected. A good GitHub workflow is like a well-run meeting: everyone knows the topic, the next action, and who has the floor.

      -

      Jamie: Let's pause on Flagging Issues During Review. What should a learner take away from it?

      -

      Alex: The reason Flagging Issues During Review matters is that start Review saves your comments as a draft until you submit the full review (see Section 7).

      -

      Alex: First, navigate to the specific line in the diff. Then, press Shift+F10 (Mac: Ctrl+Return) for context menu. After that, select "Add Comment". Finally, type your comment in the input that appears. The rhythm is simple: orient, act, verify, then continue.

      -

      Jamie: Before we leave Flagging Issues During Review, what is the practical point?

      -

      Alex: First, choose "Single Comment" or "Start Review". Think of it as a rail line: each stop confirms you are still on the right route before the next one.

      -

      Alex: A solid issue habit is to read the title, the body, and the timeline before acting. You are listening for the requested action, the missing evidence, and the person who needs a response.

      -
      -

      Alex: Keep the teaching thread moving. Start with Learning Cards: Reviewing Pull Requests in VS Code. There is something to understand, something to try, and something that proves the try worked.

      -

      Alex: The practical takeaway is this. 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. 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.

      -

      Jamie: Let's pause on Tool Cards: Create a Pull Request (from your editor). What should a learner take away from it?

      -

      Alex: Here is the plain-English version of Tool Cards: Create a Pull Request (from your editor). VS Code Desktop (primary for Day 2). Put another way, after you've pushed commits to a feature branch, you can create a PR without leaving VS Code.

      -

      Alex: First, ctrl+Shift+P GitHub Pull Requests: Create Pull Request. Then, fill in the title, description, and base branch. After that, click Create. Finally, push your branch, then click the Compare & pull request banner on the repo page. Treat it like a recipe: do not add the next ingredient until the previous one is actually in the bowl.

      -

      Jamie: Before we leave Tool Cards: Create a Pull Request (from your editor), what is the practical point?

      -

      Alex: First, fill in the form and click Create pull request. Then, after pushing, click Create Pull Request -- this opens gitub.com with the form pre-filled. It is a checklist, but a meaningful one: every item creates evidence that the next step is safe.

      -

      Alex: Treat examples as spoken recipes, not decorations. You may hear something like git push -u origin your-branch; gh pr create --title "Title" --body "Description". Read the command, understand what it changes, then run it only when the repository state matches the lesson.

      -

      Jamie: Let's pause on Prerequisites. What should a learner take away from it?

      -

      Alex: Start with Prerequisites. There is something to understand, something to try, and something that proves the try worked.

      -

      Alex: First, you've created a branch (see Git & Source Control: Branch Management). Then, you've made commits. After that, you've pushed the branch to GitHub (Ctrl+Shift+P / Mac: Cmd+Shift+P → "Git: Push"). It is a checklist, but a meaningful one: every item creates evidence that the next step is safe.

      +

      Alex: Keep the teaching thread moving. This is where 4. Agents in Detail - Hands-On Reference becomes real: this section walks through several agents in depth so you can see how they work, what they produce, and how to evaluate their output. That matters in practice: These examples use GitHub Workflow agents because they build directly on Day 1 skills - but the same patterns apply to every agent in the ecosystem. The workshop is closer to rehearsal than lecture. You hear the move, try the move, and then check what changed.

      +

      Jamie: Let's pause on Two Types of Agents. What should a learner take away from it?

      +

      Alex: Keep the learner anchored in Two Types of Agents. Before diving in, it helps to know that custom agents fall into two categories - this distinction affects what tool permissions they need and what they can do. This is the part to say slowly: Informational agents search, analyze, and report.

      +

      Alex: Keep the teaching thread moving. The reason Agent 1: @daily-briefing - Morning Briefing matters is that file.github/agents/daily-briefing.agent.md. That gives the learner a simple foothold: before you run this agent: You should have manually navigated a repository's Issues tab, read your GitHub Notifications page, understood what a pull request waiting for review looks like, and know the difference between subscribed and participating.

      -

      Jamie: Let's pause on Method 1: Command Palette (Recommended). What should a learner take away from it?

      -

      Alex: Start with Method 1: Command Palette (Recommended). There is something to understand, something to try, and something that proves the try worked.

      -

      Alex: First, ctrl+Shift+P (Mac: Cmd+Shift+P). Then, type "GitHub Pull Requests: Create". After that, select "GitHub Pull Requests: Create Pull Request". Finally, a form opens in the editor. It is like walking a hallway with named doors: read the sign, enter the right room, then confirm where you landed.

      -

      Jamie: Let's pause on Method 2: Source Control Panel. What should a learner take away from it?

      -

      Alex: Start with Method 2: Source Control Panel. There is something to understand, something to try, and something that proves the try worked.

      -

      Alex: First, open Source Control: Ctrl+Shift+G (Mac: Cmd+Shift+G). Then, after pushing, a "Create Pull Request" button appears. After that, press Enter on that button. The rhythm is simple: orient, act, verify, then continue.

      -

      Jamie: Let's pause on Method 3: GitHub Panel. What should a learner take away from it?

      -

      Alex: Start with Method 3: GitHub Panel. There is something to understand, something to try, and something that proves the try worked.

      -

      Alex: First, open GitHub view (Activity Bar → GitHub icon). Then, right-click your branch in the tree. After that, select "Create Pull Request". Think of it as a rail line: each stop confirms you are still on the right route before the next one.

      +

      Jamie: Let's pause on What it does. What should a learner take away from it?

      +

      Alex: Start with What it does: Sweeps every repository you have access to and builds a prioritized dashboard.

      +

      Alex: The practical takeaway is this. Issues opened in the last 24 hours. Pull requests waiting for your review. CI failures on your branches. Security and Dependabot alerts. Community reactions to your recent comments.

      +

      Alex: Keep the teaching thread moving. Here is the plain-English version of Example commands. The briefing output uses heading level 2 for each section. Put another way, use H key (NVDA/JAWS virtual mode) or VO+Command+H (VoiceOver) to jump between: Open Issues, Review Requests, CI Status, Security Alerts, Community Activity. It is like learning a transit route. The names of the stops matter because they tell you whether you are still going the right direction.

      +

      Jamie: Let's pause on Agent 2: @issue-tracker - Issue Management. What should a learner take away from it?

      +

      Alex: This is where Agent 2: @issue-tracker - Issue Management becomes real: file.github/agents/issue-tracker.agent.md. That matters in practice: Before you run this agent: You should have filed at least one issue using the full manual process - writing a title, description, and reproduction steps; applying labels and a milestone; and reading at least five existing issues to understand what a.

      -

      Alex: Keep the teaching thread moving. Start with Title (required). There is something to understand, something to try, and something that proves the try worked.

      -

      Alex: The practical takeaway is this. Auto-filled with your most recent commit message. Edit to make it descriptive (example: "Add Timeline View documentation").

      -

      Jamie: Let's pause on Description (optional but recommended). What should a learner take away from it?

      -

      Alex: Start with Description (optional but recommended). There is something to understand, something to try, and something that proves the try worked.

      -

      Alex: The practical takeaway is this. 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.

      -

      Alex: Keep the teaching thread moving. Start with Base branch (target). There is something to understand, something to try, and something that proves the try worked.

      -

      Alex: The practical takeaway is this. Usually main or develop. This is the branch your changes will merge into.

      +

      Alex: Keep the teaching thread moving. Keep the learner anchored in What it does. Finds, prioritizes, and helps you manage issues across all your repositories.

      +

      Alex: The practical takeaway is this. Cross-repository priority scoring with community sentiment. Batch-reply capability (draft replies to multiple issues at once). Saved search support. Release-awareness (flags issues that affect upcoming releases).

      +

      Jamie: How do we make tool choice feel like access, not pressure?

      +

      Alex: The reason Example commands matters is that the agent can draft a reply. That gives the learner a simple foothold: you review the tone against the Culture & Etiquette guide before posting.

      +

      Jamie: How do you keep commands from becoming magic words?

      +

      Alex: Start with Output example. There is something to understand, something to try, and something that proves the try worked.

      +

      Alex: Treat examples as spoken recipes, not decorations. You may hear something like Open Issues Labeled "good-first-issue"; High Priority; - 45 [accessibility-agents] Add NVDA-specific navigation tips (3 comments, opened 5 days ago); - Priority Score: 8/10 (high community interest, clear scope, no assignee); - Recommended for: First-time. Read the command, understand what it changes, then run it only when the repository state matches the lesson.

      -

      Jamie: Let's pause on Compare branch (source). What should a learner take away from it?

      -

      Alex: Start with Compare branch (source). There is something to understand, something to try, and something that proves the try worked.

      -

      Alex: The practical takeaway is this. Your feature branch (auto-selected). This is the branch with your changes.

      -

      Alex: Keep the teaching thread moving. Start with Reviewers (optional). There is something to understand, something to try, and something that proves the try worked.

      -

      Alex: The practical takeaway is this. Select people to review your PR. Navigate the list with Arrow keys.

      -

      Jamie: Let's pause on Labels (optional). What should a learner take away from it?

      -

      Alex: Start with Labels (optional). There is something to understand, something to try, and something that proves the try worked.

      -

      Alex: The practical takeaway is this. Add labels like documentation, accessibility, good-first-issue.

      +

      Jamie: Let's pause on Agent 3: @pr-review - Pull Request Review. What should a learner take away from it?

      +

      Alex: Here is the plain-English version of Agent 3: @pr-review - Pull Request Review. File.github/agents/pr-review.agent.md. Put another way, before you run this agent: You should have manually reviewed at least one pull request diff in the GitHub browser interface - navigating the Files Changed tab with your screen reader, reading added and removed lines, leaving at least one inline comment, and.

      +

      Alex: Keep the teaching thread moving. This is where What it does becomes real: generates full review documents for pull requests.

      +

      Alex: The practical takeaway is this. Line-numbered diffs with change maps. Risk assessment (what could break, what is high-impact). Before-and-after snapshots. CI results and test coverage information. Suggested inline review comments with line number references.

      +

      Jamie: What is the common workflow underneath the different interfaces?

      +

      Alex: Keep the learner anchored in Example commands. Critical rule: Read the agent's review. This is the part to say slowly: The agent produces a starting point - it does not know the project's history, the contributor's background, or the community's implicit standards the way you do.

      -

      Alex: Keep the teaching thread moving. Start with Milestone (optional). There is something to understand, something to try, and something that proves the try worked.

      -

      Alex: The practical takeaway is this. Link the PR to a project milestone.

      -

      Jamie: Let's pause on Draft PR checkbox. What should a learner take away from it?

      -

      Alex: Start with Draft PR checkbox. There is something to understand, something to try, and something that proves the try worked.

      -

      Alex: The practical takeaway is this. Check this if the PR is not ready for review yet. Unchecked = "Ready for review".

      -

      Alex: Keep the teaching thread moving. Start with Screen reader navigation. There is something to understand, something to try, and something that proves the try worked.

      -

      Alex: The practical takeaway is this. All fields are standard form inputs. Tab to move between fields. Use Arrow keys in dropdowns (reviewers, labels, milestones).

      +

      Jamie: What should happen before anyone copies and runs it?

      +

      Alex: Treat examples as spoken recipes, not decorations. You may hear something like PR Review: 14 - Improve screen reader navigation guide; Summary; This PR adds 3 new sections to the screen reader navigation guide and updates 2 existing sections with NVDA-specific keyboard shortcuts.; Files Changed: 1; Lines Added: 127; Lines Removed: 18. Read the command, understand what it changes, then run it only when the repository state matches the lesson.

      +

      Jamie: Let's pause on Agent 4: @analytics - Team Analytics. What should a learner take away from it?

      +

      Alex: Start with Agent 4: @analytics - Team Analytics: File.github/agents/analytics.agent.md. The next useful detail is this: Before you run this agent: You should have explored the Insights tab of at least one repository - looked at the contribution graph, understood what commit frequency means, and thought about what "high-churn files" implies for a project's stability.

      +

      Alex: Keep the teaching thread moving. Here is the plain-English version of What it does. Surfaces team contribution patterns, velocity metrics, and bottleneck detection.

      +

      Alex: The practical takeaway is this. Contribution velocity over time. Review turnaround time by reviewer. Code hotspot detection (files with the most churn). Workload distribution across contributors.

      -

      Jamie: Let's pause on Submitting the PR. What should a learner take away from it?

      -

      Alex: Start with Submitting the PR: VS Code creates the PR on GitHub and shows a success message. The next useful detail is this: The PR link appears in the notification - click it to open the PR on GitHub, or open it in the GitHub Pull Requests panel.

      -

      Alex: First, review all fields. Then, tab to "Create" button. After that, press Enter. Finally, navigate to the repository on GitHub. Think of it as a rail line: each stop confirms you are still on the right route before the next one.

      -

      Jamie: Before we leave Submitting the PR, what is the practical point?

      -

      Alex: First, if you recently pushed, a yellow banner "Compare & pull request" appears - click it. Then, otherwise: click Pull requests tab, then New pull request, then select your branch. After that, fill in the title and description. Finally, click Create pull request. Treat it like a recipe: do not add the next ingredient until the previous one is actually in the bowl.

      -

      Alex: Treat examples as spoken recipes, not decorations. You may hear something like 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. Read the command, understand what it changes, then run it only when the repository state matches the lesson.

      -

      Alex: Keep the teaching thread moving. Start with Learning Cards: Creating a Pull Request. There is something to understand, something to try, and something that proves the try worked.

      -

      Alex: The practical takeaway is this. 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. 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.

      -

      Jamie: Let's pause on 6. Pull Request Description Templates. What should a learner take away from it?

      -

      Alex: This is where 6. Pull Request Description Templates becomes real: many repositories include a PR template - a Markdown file that pre-fills the PR description with a checklist or structure.

      +

      Jamie: There are a lot of tools in play. How do we keep that from feeling like a contest?

      +

      Alex: This is where Example commands becomes real: accessibility use case: After Day 2's contribution wave, run @analytics team velocity in accessibility-agents today to see the hackathon's collective output. That matters in practice: A moment of real-time team celebration.

      +

      Alex: Keep the teaching thread moving. Keep the learner anchored in Agent 5: @insiders-a11y-tracker - Accessibility Change Monitoring. File.github/agents/insiders-a11y-tracker.agent.md. This is the part to say slowly: Before you run this agent: You should have filed at least one accessibility bug report using the workshop's issue template, applied a WCAG label to an issue, and manually reviewed a Markdown file for heading hierarchy - knowing what H1 means, what H2 means,. A good GitHub workflow is like a well-run meeting: everyone knows the topic, the next action, and who has the floor.

      +

      Jamie: Before we leave What it does, what is the practical point?

      +

      Alex: The reason What it does matters is that monitors accessibility-sensitive changes across configured repositories.

      +

      Alex: The practical takeaway is this. WCAG/ARIA cross-referenced change tracking. Flags changes to keyboard navigation, ARIA attributes, focus management, color usage. Monitors for heading hierarchy violations in Markdown. Tracks link text quality (flags bare URLs, non-descriptive labels).

      -

      Alex: Keep the teaching thread moving. Keep the learner anchored in Where Templates Are Stored. When you create a PR in VS Code, the extension automatically loads the template into the description field. A good GitHub workflow is like a well-run meeting: everyone knows the topic, the next action, and who has the floor.

      -

      Alex: The practical takeaway is this.github/pull request template.md (root).github/PULL REQUEST TEMPLATE.md.github/PULL REQUEST TEMPLATE/ (folder with multiple templates). docs/pull request template.md.

      -

      Jamie: Let's pause on Example PR Template. What should a learner take away from it?

      -

      Alex: Start with Example PR Template. There is something to understand, something to try, and something that proves the try worked.

      -

      Alex: Treat examples as spoken recipes, not decorations. You may hear something like 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,. Read the command, understand what it changes, then run it only when the repository state matches the lesson.

      -

      Jamie: Let's pause on Screen reader workflow. What should a learner take away from it?

      -

      Alex: Start with Screen reader workflow: Keyboard tip: Use Ctrl+F (Mac: Cmd+F) to jump to each <!-- placeholder, fill it in, then F3 to jump to the next one.

      -

      Alex: First, create PR (Method 1-3 from Section 5). Then, the description field is pre-filled with the template. After that, navigate through the template with Arrow keys. Finally, replace each `` with your content. Think of it as a rail line: each stop confirms you are still on the right route before the next one.

      -

      Jamie: Before we leave Screen reader workflow, what is the practical point?

      -

      Alex: First, check checkboxes by typing x between the brackets: - [x]. Treat it like a recipe: do not add the next ingredient until the previous one is actually in the bowl.

      +

      Alex: Keep the teaching thread moving. Start with Example commands: Day 2 workflow: Run this before submitting any PR. The next useful detail is this: If the agent flags an issue, fix it before requesting review - not after.

      +

      Jamie: Let's pause on Agent 6: @template-builder - Interactive Issue Template Wizard. What should a learner take away from it?

      +

      Alex: Here is the plain-English version of Agent 6: @template-builder - Interactive Issue Template Wizard. File.github/agents/template-builder.agent.md. Put another way, before you run this agent: You should have read Issue Templates thoroughly - understanding YAML field types, creating a template manually (Exercise B), and designing your own template (Exercise D).

      +

      Alex: Keep the teaching thread moving. This is where What it does becomes real: an interactive wizard that guides you through building GitHub issue templates step-by-step using VS Code's Ask Questions feature. That matters in practice: Instead of writing YAML syntax, answer simple questions and the agent generates production-ready templates. The workshop is closer to rehearsal than lecture. You hear the move, try the move, and then check what changed.

      -

      Jamie: Let's pause on 7. Commenting and Requesting Changes. What should a learner take away from it?

      -

      Alex: Start with 7. Commenting and Requesting Changes. There is something to understand, something to try, and something that proves the try worked.

      -

      Alex: The practical takeaway is this. Leave inline comments on specific lines. Request changes before the PR can be merged. Approve the PR. Submit general feedback.

      -

      Jamie: Let's pause on Adding an Inline Comment. What should a learner take away from it?

      -

      Alex: Start with Adding an Inline Comment. There is something to understand, something to try, and something that proves the try worked.

      -

      Alex: First, open a file from the PR's "Files Changed" list. Then, navigate to the line you want to comment on. After that, press Shift+F10 (Mac: Ctrl+Return) to open context menu. Finally, select "Add Comment". It is a checklist, but a meaningful one: every item creates evidence that the next step is safe.

      -

      Jamie: Before we leave Adding an Inline Comment, what is the practical point?

      -

      Alex: First, type your comment. Then, choose "Add Single Comment" (posts immediately) or "Start Review" (saves as a draft). It is like walking a hallway with named doors: read the sign, enter the right room, then confirm where you landed.

      -

      Jamie: Let's pause on Comment format tips. What should a learner take away from it?

      -

      Alex: Start with Comment format tips. There is something to understand, something to try, and something that proves the try worked.

      -

      Alex: The practical takeaway is this. Be specific: "This heading should be H3, not H2". Provide context: "Screen readers announce this as 'list with 1 item' - should be a paragraph instead". Suggest a fix: "Consider rewording to: 'Click the button to save'".

      +

      Jamie: How should a learner choose a tool without feeling judged by the choice?

      +

      Alex: Keep the learner anchored in Example commands. Manual YAML template creation takes 15-20 minutes and is error-prone. This is the part to say slowly: The Template Builder generates correct, tested templates in 2-3 minutes via guided questions.

      +

      Alex: Keep the teaching thread moving. The reason 5. Slash Commands and Prompts matters is that the repository includes 54+ slash commands defined as.prompt.md files in.github/prompts/. That gives the learner a simple foothold: type / in Copilot Chat to see the full command menu.

      +

      Jamie: How should they picture the shape of the workshop?

      +

      Alex: Start with Workshop Slash Command Quick Reference: The commands listed below are the ones most relevant to this workshop. The next useful detail is this: The full repository contains 54+ commands covering accessibility auditing, document scanning, framework-specific checks, and more.

      -

      Jamie: Let's pause on If you have multiple comments to make, use "Start Review". What should a learner take away from it?

      -

      Alex: Start with If you have multiple comments to make, use "Start Review". There is something to understand, something to try, and something that proves the try worked.

      -

      Alex: First, add your first inline comment → select "Start Review". Then, continue adding comments to other lines. After that, all comments are saved as drafts (not visible to others yet). The rhythm is simple: orient, act, verify, then continue.

      -

      Jamie: Let's pause on Submitting Your Review. What should a learner take away from it?

      -

      Alex: Start with Submitting Your Review: The review type selector is a radio button group. The next useful detail is this: Use Arrow keys to choose, Enter to confirm.

      -

      Alex: The practical takeaway is this. Comment - general feedback, no approval decision. Approve - PR looks good, ready to merge. Request Changes - issues must be fixed before merging.

      -

      Alex: First, ctrl+Shift+P (Mac: Cmd+Shift+P). Then, type "GitHub Pull Requests: Submit Review". After that, select "GitHub Pull Requests: Finish Review". Finally, choose review type. Think of it as a rail line: each stop confirms you are still on the right route before the next one.

      -

      Jamie: Before we leave Submitting Your Review, what is the practical point?

      -

      Alex: First, optionally add a summary comment. Then, press Enter to submit. Treat it like a recipe: do not add the next ingredient until the previous one is actually in the bowl.

      -

      Jamie: Let's pause on What Happens After Submission. What should a learner take away from it?

      -

      Alex: Here is the plain-English version of What Happens After Submission. Web alternative (github.com) - reviewing. Put another way, see Accessible Code Review for detailed screen reader steps. It is like learning a transit route. The names of the stops matter because they tell you whether you are still going the right direction.

      -

      Alex: The practical takeaway is this. All your draft comments post to GitHub. The PR author receives a notification. Your review status appears on the PR (Approved / Changes Requested / Commented). If you requested changes, the PR cannot merge until you approve it.

      -

      Alex: First, open the PR and click the Files changed tab. Then, read through each file's diff. After that, click the blue + button on any line to add an inline comment. Finally, choose Start a review to batch comments. Treat it like a recipe: do not add the next ingredient until the previous one is actually in the bowl.

      -

      Jamie: Before we leave What Happens After Submission, what is the practical point?

      -

      Alex: First, click Review changes (top right) to select Comment / Approve / Request changes. Then, click Submit review. It is a checklist, but a meaningful one: every item creates evidence that the next step is safe.

      -

      Alex: Treat examples as spoken recipes, not decorations. You may hear something like View the PR diff in your terminal; gh pr diff 42; Approve; gh pr review 42 --approve --body "Looks good."; Request changes; gh pr review 42 --request-changes --body "Heading hierarchy needs fixing."; Comment-only (no verdict); gh pr review 42 --comment --body. Read the command, understand what it changes, then run it only when the repository state matches the lesson.

      +

      Alex: Keep the teaching thread moving. Here is the plain-English version of Reading Slash Command Definitions. Each /command corresponds to a.prompt.md file in.github/prompts/. Put another way, open any of them in VS Code to read what instructions it gives Copilot. It is like learning a transit route. The names of the stops matter because they tell you whether you are still going the right direction.

      +

      Jamie: Let's pause on Example: /a11y-update. What should a learner take away from it?

      +

      Alex: This is where Example: /a11y-update becomes real: file.github/prompts/a11y-update.prompt.md. That matters in practice: This is how you learn to write your own.

      +

      Alex: Keep the teaching thread moving. Start with Learning Cards: Slash Commands and Prompts. There is something to understand, something to try, and something that proves the try worked.

      +

      Alex: The practical takeaway is this. Type / in Copilot Chat to see all available slash commands -- your screen reader announces each command name as you arrow through the list. Slash commands are defined in.github/prompts/ as.prompt.md files -- open them in the Explorer to read what each command does before using it. Create your own command by copying an existing.prompt.md file, renaming it, and editing the instructions -- no code required. The / command menu appears as a dropdown list in Copilot Chat -- it scales with VS Code's font and zoom settings. Each command has a short description visible in the dropdown; use Ctrl+= to zoom if the text is too small. Open the.prompt.md file in the editor to read the full command definition at your preferred zoom level.

      -

      Jamie: Let's pause on Learning Cards: Commenting and Requesting Changes. What should a learner take away from it?

      -

      Alex: Start with Learning Cards: Commenting and Requesting Changes. There is something to understand, something to try, and something that proves the try worked.

      -

      Alex: The practical takeaway is this. In a diff view, navigate to a line and press Shift+F10 for the context menu, then select "Add Comment" to leave inline feedback. Choose "Start Review" instead of "Single Comment" to batch multiple comments before submitting them all at once. When submitting a review, use Ctrl+Shift+P then "GitHub Pull Requests: Submit Review" and choose Approve, Request Changes, or Comment. Inline comments appear as expandable banners within the diff view -- look for the text input box that opens below the target line. The review submission dialog has radio buttons for Approve, Request Changes, and Comment with clear labels. Increase diff view font size with Ctrl+= so line numbers and change annotations are easier to read.

      -

      Alex: Keep the teaching thread moving. Keep the learner anchored in 8. Merging Pull Requests. Who can merge: Repository maintainers, or contributors with write access.

      -

      Jamie: Let's pause on Prerequisites for Merging. What should a learner take away from it?

      -

      Alex: The reason Prerequisites for Merging matters is that changing the base branch: If the PR was opened against the wrong base branch, you can change it from the PR detail view in VS Code. That gives the learner a simple foothold: scroll to the base branch field in the PR detail view and activate the dropdown to select a different target branch.

      -

      Alex: First, all required reviews are approved. Then, all CI checks pass (green checkmarks). After that, no merge conflicts exist. Finally, branch is up to date with base branch (main). The rhythm is simple: orient, act, verify, then continue.

      +

      Jamie: Let's pause on 6. Contributing to the Ecosystem. What should a learner take away from it?

      +

      Alex: The reason 6. Contributing to the Ecosystem matters is that the 55 Accessibility Agents and 54+ slash commands are starting points. That gives the learner a simple foothold: the.agent.md format is open - you can create your own agents for any repeatable workflow, and contribute them back to the project.

      +

      Alex: Keep the teaching thread moving. Start with Two Types of Custom Agents: Informational agents - conversational; search, analyze, and present results. The next useful detail is this: Task-oriented agents - active; edit files, run commands, submit PRs. Think of it like entering a new building: first you find the lobby, then the room, then the door you actually need.

      +

      Alex: The practical takeaway is this. Perform GitHub searches with predefined scopes and filters. Present results in specific structured formats. Query GitHub API tools to answer questions. Execute external tools (linters, test suites, axe-core).

      +

      Jamie: Let's pause on Agent File Structure. What should a learner take away from it?

      +

      Alex: Here is the plain-English version of Agent File Structure. See also: Appendix L: Agents Reference has the complete agent.md format specification and examples. Put another way, every.agent.md file has two parts: YAML frontmatter (metadata) and a system prompt (markdown body).

      -

      Jamie: Let's pause on Method 1: PR Detail View. What should a learner take away from it?

      -

      Alex: Start with Method 1: PR Detail View. There is something to understand, something to try, and something that proves the try worked.

      -

      Alex: First, open the PR in VS Code. Then, scroll to the bottom of the PR detail view. After that, find "Merge Pull Request" button. Finally, press Enter. Think of it as a rail line: each stop confirms you are still on the right route before the next one.

      -

      Jamie: Before we leave Method 1: PR Detail View, what is the practical point?

      -

      Alex: First, choose merge type (see below). Treat it like a recipe: do not add the next ingredient until the previous one is actually in the bowl.

      -

      Jamie: If someone only remembers one thing from Method 2: Command Palette, what should it be?

      -

      Alex: First, ctrl+Shift+P (Mac: Cmd+Shift+P). Then, type "GitHub Pull Requests: Merge". After that, select "GitHub Pull Requests: Merge Pull Request". Finally, choose the PR from the list. Treat it like a recipe: do not add the next ingredient until the previous one is actually in the bowl.

      -

      Alex: First, select merge type. It is a checklist, but a meaningful one: every item creates evidence that the next step is safe.

      -

      Alex: Keep the teaching thread moving. This is where Merge Types becomes real: the merge type selector is a dropdown or radio group. That matters in practice: Navigate with Arrow keys, confirm with Enter.

      +

      Alex: Keep the teaching thread moving. This is where Frontmatter fields becomes real: restricting tool access is a security best practice - only grant what the agent actually needs.

      +

      Jamie: Let's pause on Example: Informational Agent - @insiders-a11y-tracker. What should a learner take away from it?

      +

      Alex: Keep the learner anchored in Example: Informational Agent - @insiders-a11y-tracker. This agent monitors VS Code Insiders releases for accessibility improvements. This is the part to say slowly: It searches the microsoft/vscode repository using predefined GitHub query syntax, so you never have to remember the exact filter parameters.

      +

      Jamie: Let's pause on Use it. What should a learner take away from it?

      +

      Alex: The reason Use it matters is that prerequisite: GitHub MCP server installed (github.com/github/github-mcp-server). The interface gets friendlier when it stops being a wall of controls and starts being a set of named places.

      +

      Alex: First, select @insiders-a11y-tracker from the agent picker. Then, ask: what shipped this month? or any keyboard navigation improvements in January? After that, the agent searches with repo:microsoft/vscode is:closed milestone:"[Month] [Year]" label:accessibility label:insiders-released and returns formatted results. The rhythm is simple: orient, act, verify, then continue.

      -

      Jamie: Let's pause on Which merge type to use. What should a learner take away from it?

      -

      Alex: Start with Which merge type to use. There is something to understand, something to try, and something that proves the try worked.

      -

      Alex: The practical takeaway is this. Check the repository's CONTRIBUTING.md for guidance. If unsure, use Merge Commit (the default and safest option).

      -

      Jamie: Let's pause on After Merging. What should a learner take away from it?

      -

      Alex: Start with After Merging. There is something to understand, something to try, and something that proves the try worked.

      -

      Alex: First, the PR closes automatically. Then, the feature branch can be deleted (VS Code prompts: "Delete branch?"). After that, recommended: switch back to main and pull the merged changes. The rhythm is simple: orient, act, verify, then continue.

      -

      Jamie: Let's pause on Switching to main and pulling. What should a learner take away from it?

      -

      Alex: Start with Switching to main and pulling: (Mac users: use Cmd+Shift+P instead of Ctrl+Shift+P).

      -

      Alex: Treat examples as spoken recipes, not decorations. You may hear something like Ctrl+Shift+P → "Git: Checkout to." → select "main"; Ctrl+Shift+P → "Git: Pull". Read the command, understand what it changes, then run it only when the repository state matches the lesson.

      +

      Jamie: Let's pause on Example: Task-Oriented Agent - The Markdown Accessibility Assistant. What should a learner take away from it?

      +

      Alex: Start with Example: Task-Oriented Agent - The Markdown Accessibility Assistant: The GitHub Accessibility team published a complete walkthrough for building a Markdown Accessibility Assistant - a task-oriented agent that reviews Markdown files for accessibility issues and makes direct fixes. The next useful detail is this: This agent is the automated version of the accessibility review skills you built during Day 1.

      +

      Alex: The practical takeaway is this. Runs markdownlint-cli2 to catch structural problems (heading skips, bare URLs, missing blank lines). Reviews link text for descriptiveness. Flags missing or inadequate alt text and waits for your approval before changing it (alt text requires human judgment). Fixes heading hierarchy, list structure, and bare URL formatting directly.

      +

      Alex: Keep the teaching thread moving. Here is the plain-English version of Key Pattern: Tiered Decision-Making. This tiered approach - automate what can be objectively evaluated, flag what needs human judgment - is the right model for any accessibility agent. Put another way, it maximizes the agent's value while keeping humans in control of decisions that require context.

      +

      Jamie: Let's pause on Required Prerequisites for the Markdown Accessibility Assistant. What should a learner take away from it?

      +

      Alex: Start with Required Prerequisites for the Markdown Accessibility Assistant. There is something to understand, something to try, and something that proves the try worked.

      +

      Alex: The practical takeaway is this. GitHub MCP server installed and configured (github.com/github/github-mcp-server). Node.js installed (for npx markdownlint-cli2).

      -

      Jamie: Let's pause on Deleting the Feature Branch. What should a learner take away from it?

      -

      Alex: Here is the plain-English version of Deleting the Feature Branch. After merging, the feature branch is no longer needed. Put another way, web alternative (github.com) - merging.

      -

      Alex: First, ctrl+Shift+P (Mac: Cmd+Shift+P). Then, type "git delete branch". After that, select "Git: Delete Branch.". Finally, choose the merged branch. Treat it like a recipe: do not add the next ingredient until the previous one is actually in the bowl.

      -

      Jamie: Before we leave Deleting the Feature Branch, what is the practical point?

      -

      Alex: First, open the PR's Conversation tab. Then, scroll to the merge button at the bottom. After that, click the dropdown arrow to choose a merge strategy (Squash, Rebase, or Merge commit). Finally, click Merge pull request, then Confirm merge. It is a checklist, but a meaningful one: every item creates evidence that the next step is safe.

      -

      Alex: Treat examples as spoken recipes, not decorations. You may hear something like Merge with default strategy; gh pr merge 42; Squash and merge, then delete the branch; gh pr merge 42 --squash --delete-branch; Enable auto-merge (merges when checks pass); gh pr merge 42 --auto --squash. Read the command, understand what it changes, then run it only when the repository state matches the lesson.

      -

      Jamie: Let's pause on Learning Cards: Merging Pull Requests. What should a learner take away from it?

      -

      Alex: Start with Learning Cards: Merging Pull Requests. There is something to understand, something to try, and something that proves the try worked.

      -

      Alex: The practical takeaway is this. The merge type selector (Merge Commit, Squash, Rebase) is announced as a dropdown or radio group -- use Arrow keys to move between options and Enter to confirm; if unsure, choose Merge Commit (the default and safest option). After merging, VS Code prompts "Delete branch?" as a notification -- press Alt+N to focus the notification and Enter to confirm, then run Ctrl+Shift+P then "Git: Checkout to" and select main to return to your default branch. Confirm the merge succeeded by pressing F6 to reach the Status Bar and verifying it now reads main instead of the feature branch name. The merge button at the bottom of the PR detail view includes a dropdown arrow for selecting merge type -- at high zoom, widen the editor pane so the button label and dropdown are not truncated. After merging, the PR detail view header changes from "Open" (green badge) to "Merged" (purple badge) -- verify this colour/label change before deleting the branch. When switching back to main, the branch name in the bottom-left Status Bar updates immediately -- confirm it reads main before pulling new changes with Ctrl+Shift+P then "Git: Pull".

      -

      Alex: Keep the teaching thread moving. Keep the learner anchored in "No pull requests found". Issue: The GitHub Pull Requests panel is empty. A good GitHub workflow is like a well-run meeting: everyone knows the topic, the next action, and who has the floor.

      +

      Jamie: Let's pause on From VS Code. What should a learner take away from it?

      +

      Alex: Start with From VS Code. There is something to understand, something to try, and something that proves the try worked.

      +

      Alex: First, open Copilot Chat (Ctrl+Shift+I / Cmd+Shift+I on macOS). Then, in the Chat input toolbar, select the Set Agent button. After that, select your custom agent from the agent picker. Finally, type your request - the agent executes in your local workspace. It is like walking a hallway with named doors: read the sign, enter the right room, then confirm where you landed.

      +

      Jamie: Let's pause on From GitHub.com (Task mode). What should a learner take away from it?

      +

      Alex: Start with From GitHub.com (Task mode). There is something to understand, something to try, and something that proves the try worked.

      +

      Alex: First, open Copilot Chat on GitHub.com. Then, select Task from the mode picker. After that, optionally select a custom agent from the agent picker. Finally, submit your request - the agent can create a PR automatically. The rhythm is simple: orient, act, verify, then continue.

      +

      Jamie: Let's pause on From an issue (Issue Assignment). What should a learner take away from it?

      +

      Alex: Start with From an issue (Issue Assignment). There is something to understand, something to try, and something that proves the try worked.

      +

      Alex: First, open any issue → Assignees → assign Copilot. Then, in the dialog, optionally select a custom agent. After that, select Assign - Copilot creates a branch, makes changes, and opens a PR. Think of it as a rail line: each stop confirms you are still on the right route before the next one.

      -

      Jamie: Let's pause on Solutions. What should a learner take away from it?

      -

      Alex: Start with Solutions. There is something to understand, something to try, and something that proves the try worked.

      -

      Alex: First, verify you're signed in: Ctrl+Shift+P (Mac: Cmd+Shift+P) → "GitHub Pull Requests: Sign in". Then, check you have a folder open containing a Git repository. After that, refresh the panel: Ctrl+Shift+P (Mac: Cmd+Shift+P) → "GitHub Pull Requests: Refresh Pull Requests List". The rhythm is simple: orient, act, verify, then continue.

      -

      Jamie: Before we leave Solutions, what is the practical point?

      -

      Alex: First, verify you've pushed your branch: Ctrl+Shift+P (Mac: Cmd+Shift+P) → "Git: Push". Then, check you have write access to the repository. After that, ensure your branch is ahead of the base branch (has new commits). Think of it as a rail line: each stop confirms you are still on the right route before the next one.

      -

      Jamie: Let's pause on "Authentication failed". What should a learner take away from it?

      -

      Alex: Here is the plain-English version of "Authentication failed". Issue: VS Code can't connect to GitHub.

      +

      Jamie: What does someone need before they touch the keyboard?

      +

      Alex: Here is the plain-English version of Environment Setup for GitHub (Cloud Agents). When agents run on GitHub (not locally), they may need additional tools. Put another way, create a workflow file at.github/workflows/copilot-setup-steps.yml with a single job named copilot-setup-steps.

      +

      Jamie: Let's pause on To Create Your Own Agent. What should a learner take away from it?

      +

      Alex: Start with To Create Your Own Agent. There is something to understand, something to try, and something that proves the try worked.

      +

      Alex: First, create.github/agents/your-agent-name.agent.md. Then, write YAML frontmatter (name, description, tools). After that, write the system prompt - identity, capabilities, domain knowledge, behavioral rules, output format. Finally, save and reload VS Code (Ctrl+Shift+P → "Reload Window"). It is a checklist, but a meaningful one: every item creates evidence that the next step is safe.

      +

      Jamie: Before we leave To Create Your Own Agent, what is the practical point?

      +

      Alex: First, type @your-agent-name in Copilot Chat. It is like walking a hallway with named doors: read the sign, enter the right room, then confirm where you landed.

      +

      Jamie: What should the learner prove to themselves after each small task?

      +

      Alex: Keep the learner anchored in Exercise: Extend the Template Builder Agent. You've built templates manually (Chapters 15-16) and seen them in action. This is the part to say slowly: Now see how to harness AI to generate templates interactively, and learn to customize agents for your own projects.

      +

      Alex: The practical takeaway is this. Complete Chapters 15-16 (especially Exercise D - designing your own template). VS Code is installed and GitHub Copilot is active. You have forked accessibility-agents to your GitHub account. You have cloned your fork locally: git clone https://github.com/[your-username]/accessibility-agents.git.

      -

      Jamie: What is the teaching move inside Solutions?

      -

      Alex: First, sign out and sign back in: Ctrl+Shift+P (Mac: Cmd+Shift+P) → "GitHub Pull Requests: Sign out" → then sign in again. Then, check your GitHub Personal Access Token (see Appendix D: Git Authentication). After that, verify network connection. It is a checklist, but a meaningful one: every item creates evidence that the next step is safe.

      -

      Jamie: Let's pause on Try It: Review a PR from VS Code. What should a learner take away from it?

      -

      Alex: Keep the learner anchored in Try It: Review a PR from VS Code. Time: 3 minutes What you need: VS Code with GitHub Pull Requests extension installed and signed in. This is the part to say slowly: You just reviewed a pull request entirely from VS Code.

      -

      Alex: First, open the PR view - Press Ctrl+Shift+P → type Pull Requests: Focus on GitHub Pull Requests View → Enter. Then, find a PR - Navigate the tree with arrow keys. Expand a PR to see its changed files. After that, open a diff - Press Enter on a changed file. The diff editor opens. Finally, use the Accessible Diff Viewer - Press F7 to jump to the first change. Your screen reader announces what was added or removed. Press F7 again to move to the next change. It is like walking a hallway with named doors: read the sign, enter the right room, then confirm where you landed.

      -

      Jamie: Before we leave Try It: Review a PR from VS Code, what is the practical point?

      -

      Alex: First, leave a comment - Position your cursor on a line you want to comment on, then press Ctrl+Shift+P → Pull Request: Add Comment on Current Diff Line. Type a brief, constructive comment and submit. The rhythm is simple: orient, act, verify, then continue.

      -

      Alex: Keep the teaching thread moving. The reason Conducting Pull Request Reviews with a Screen Reader matters is that this guide is focused entirely on the reviewer experience - navigating diffs, reading changes, leaving comments, and submitting a review - using only your keyboard and screen reader. That gives the learner a simple foothold: for the full pull request lifecycle (opening PRs, merge options, conflict resolution), see Working with Pull Requests.

      +

      Jamie: Let's pause on Exercise 1: Generate a Template with the Agent. What should a learner take away from it?

      +

      Alex: The reason Exercise 1: Generate a Template with the Agent matters is that your Mission: Use the @template-builder agent to generate an accessibility bug report template interactively. That gives the learner a simple foothold: you'll experience the agent as an end-user and see what production-ready agent output looks like.

      +

      Alex: The practical takeaway is this. Left sidebar showing.github/, docs/, learning-room/, README.md, etc. The status bar at the bottom shows your current git branch (probably main). Alternative: Use menu: View → Copilot Chat. Copilot is now ready to receive instructions.

      +

      Alex: First, open VS Code. Then, file → Open Folder → select your locally cloned accessibility-agents folder. After that, the folder tree appears on the left showing the repository structure. Finally, verify you're in the right place: The folder name should be accessibility-agents at the top of the sidebar. The rhythm is simple: orient, act, verify, then continue.

      +

      Jamie: Before we leave Exercise 1: Generate a Template with the Agent, what is the practical point?

      +

      Alex: First, keyboard shortcut: Press Ctrl+Shift+I (Windows/Linux) or Cmd+Shift+I (macOS). Then, a chat panel opens on the right side of VS Code. After that, at the top, you see "Copilot Chat" and probably a text input at the bottom saying "Ask Copilot.". Finally, click in the chat input box (bottom of Copilot Chat panel). Think of it as a rail line: each stop confirms you are still on the right route before the next one.

      +

      Alex: Treat examples as spoken recipes, not decorations. You may hear something like Q: Template name?; A: Accessibility Bug Report; Q: What's it for?; A: Report screen reader and keyboard navigation issues; Q: First field name?; A: Screen Reader; Q: Field type?; A: dropdown; Q: Dropdown options? (comma-separated); A: NVDA, JAWS, VoiceOver,. Read the command, understand what it changes, then run it only when the repository state matches the lesson.

      +

      Jamie: Let's pause on Exercise 2: Extend the Agent for Your Project. What should a learner take away from it?

      +

      Alex: Start with Exercise 2: Extend the Agent for Your Project: Your Mission: Customize the Template Builder agent to recognize and guide a Security Vulnerability Report template. The next useful detail is this: This teaches you how to tailor agents for project-specific needs.

      +

      Alex: The practical takeaway is this. The file starts with YAML frontmatter (name, description, topics). Below that, sections like " How to Use", " Pre-Built Workflow". Search for the text "Pre-Built Workflow: Guided Accessibility Template".

      +

      Alex: First, in VS Code, navigate to.github/agents/. Then, file: template-builder.agent.md. After that, double-click to open it in the editor. Finally, you see the agent's instructions in Markdown format. Think of it as a rail line: each stop confirms you are still on the right route before the next one.

      +

      Jamie: Before we leave Exercise 2: Extend the Agent for Your Project, what is the practical point?

      +

      Alex: First, use Ctrl+F to open Find. Then, search for: Pre-Built Workflow. After that, press Enter to jump to the first match. Finally, you should land on the "Pre-Built Workflow: Guided Accessibility Template" section. Treat it like a recipe: do not add the next ingredient until the previous one is actually in the bowl.

      +

      Jamie: Let's pause on What you're adding. What should a learner take away from it?

      +

      Alex: Here is the plain-English version of What you're adding. If the agent doesn't recognize your new workflow. It is like learning a transit route. The names of the stops matter because they tell you whether you are still going the right direction.

      +

      Alex: The practical takeaway is this. A clear label for the new workflow. Instructions on how to invoke it. Pre-defined fields that make sense for security reports. Specific options for severity and vulnerability type. The agent recognizes your new workflow. Next time you invoke @template-builder with "create security template", it will follow your new guidance.

      +

      Alex: First, save the file: Ctrl+S. Then, you should see no error messages. After that, the agent file now includes your new Pre-Built Workflow. Finally, open Copilot Chat again: Ctrl+Shift+I. Treat it like a recipe: do not add the next ingredient until the previous one is actually in the bowl.

      +

      Jamie: Before we leave What you're adding, what is the practical point?

      +

      Alex: First, press Enter. Then, the agent should now ask vulnerability-specific questions. After that, commit your agent change. Finally, the extended agent is now in your fork. It is a checklist, but a meaningful one: every item creates evidence that the next step is safe.

      +

      Alex: Treat examples as spoken recipes, not decorations. You may hear something like git add.github/agents/template-builder.agent.md; git commit -m "feat: add security vulnerability template workflow to template-builder agent"; git push origin main. Read the command, understand what it changes, then run it only when the repository state matches the lesson.

      -

      Jamie: Zoom out for a second. What kind of journey is this?

      -

      Alex: Start with Workshop Recommendation (Chapter 15 / Challenge 12): Chapter 15 is the code review chapter focused on practicing constructive feedback. The next useful detail is this: It supports Challenge 12: Review Like a Pro.

      -

      Alex: The practical takeaway is this. There are 2 guided challenges. Automation check: none (review quality is subjective and human-focused). The evidence is issue comment with summary of review and feedback posted. The pattern is navigate diff, comment on specifics, submit verdict.

      -

      Jamie: Let's pause on Challenge 12 Practice Set. What should a learner take away from it?

      -

      Alex: Start with Challenge 12 Practice Set. There is something to understand, something to try, and something that proves the try worked.

      -

      Alex: First, review a practice PR and leave 2-3 inline comments - read the diff line by line, find specific items to comment on, and post constructive feedback. Then, submit a formal review verdict - complete your review by choosing approve, request changes, or comment only. Treat it like a recipe: do not add the next ingredient until the previous one is actually in the bowl.

      -

      Jamie: Let's pause on Practice 12.1 Step-by-Step: Review a PR and Leave Inline Comments. What should a learner take away from it?

      -

      Alex: This is where Practice 12.1 Step-by-Step: Review a PR and Leave Inline Comments becomes real: navigate a PR diff using screen reader-friendly tools and post 2-3 specific, constructive inline comments. That matters in practice: GitHub.com (Files changed tab of a PR) or VS Code with the GitHub Pull Requests extension.

      -

      Alex: The practical takeaway is this. On GitHub.com: Use heading navigation to jump between files (H in NVDA). Each file header is a heading. Within a file, use arrow keys to move line by line. In VS Code: Press F7 to open the Accessible Diff Viewer (see Chapter 15, Part 1). Use F7/Shift+F7 to move between changes. Typos or grammar issues. Unclear headings or link text.

      -

      Alex: First, open your Learning Room repository on GitHub.com and navigate to the Pull requests tab. Then, find a classmate's open PR (from Chapter 6, 7, or 14). Open it. After that, activate the Files changed tab. This shows the diff - lines added in green, lines removed in red. Finally, navigate the diff. It is a checklist, but a meaningful one: every item creates evidence that the next step is safe.

      -

      Jamie: Before we leave Practice 12.1 Step-by-Step: Review a PR and Leave Inline Comments, what is the practical point?

      -

      Alex: First, read through the changes carefully. Look. Then, to leave an inline comment on GitHub.com: activate the + button that appears to the left of a line number when you hover or Tab to it. (Screen reader users: this button may be announced as "Add a comment to this line.") Type your comment in the text box that. After that, post 2-3 inline comments. Each comment should be. Finally, examples of good inline comments. It is like walking a hallway with named doors: read the sign, enter the right room, then confirm where you landed.

      +

      Jamie: Let's pause on Exercise 3: Iterative Refinement with Agents. What should a learner take away from it?

      +

      Alex: This is where Exercise 3: Iterative Refinement with Agents becomes real: your Mission: Generate a template, then ask the agent to modify it incrementally. That matters in practice: This teaches you the iterative pattern that scales to all agent-assisted workflows.

      +

      Alex: The practical takeaway is this. Running a complete template generation (same as Exercise 1). The agent modifies the YAML it generated. The new checkbox appears in the YAML with proper formatting and indentation. It doesn't regenerate from scratch - just adds your change.

      +

      Alex: First, in Copilot Chat, type: @template-builder create a feature request template. Then, answer the agent's questions to build a feature request form. After that, let the agent generate the YAML. Finally, copy it to a file.github/ISSUE TEMPLATE/feature-request.yml. It is a checklist, but a meaningful one: every item creates evidence that the next step is safe.

      +

      Jamie: Before we leave Exercise 3: Iterative Refinement with Agents, what is the practical point?

      +

      Alex: First, once the template is generated, while still in the same chat conversation, ask. Then, the agent regenerates the YAML with your new checkbox added in the right place (usually as required field pre-validation). After that, follow up. Finally, the agent modifies the textarea field's attributes to enable code highlighting. It is like walking a hallway with named doors: read the sign, enter the right room, then confirm where you landed.

      +

      Jamie: Let's pause on What Comes Next. What should a learner take away from it?

      +

      Alex: Keep the learner anchored in What Comes Next. Your next step: explore the broader ecosystem. This is the part to say slowly: That is Accessibility Agents' promise: not to replace your thinking, but to amplify your skills across all 55 agents - and to grow through the contributions of everyone who uses it.

      +

      Alex: The practical takeaway is this. Browse the full agent list - which agents solve problems you face regularly? Try an Accessibility team agent: @contrast-master check this page or @alt-text-headings review this file. Try a Developer Tools agent: @python-specialist review this module for accessibility or @desktop-a11y-specialist audit this dialog. Think about what is missing: what agent would you build if you could?

      +

      Alex: First, generated a template using an agent (Exercise 1). Then, customized an agent for your domain (Exercise 2). After that, refined iteratively with agent help (Exercise 3). It is like walking a hallway with named doors: read the sign, enter the right room, then confirm where you landed.

      +

      Jamie: Let's pause on Learning Cards: Contributing to the Ecosystem. What should a learner take away from it?

      +

      Alex: Start with Learning Cards: Contributing to the Ecosystem. There is something to understand, something to try, and something that proves the try worked.

      +

      Alex: The practical takeaway is this. Agent.agent.md files use YAML frontmatter at the top (between --- delimiters) followed by Markdown body; in VS Code, use Ctrl+G to jump to line 1 and arrow through the frontmatter fields (name, description, tools) before reading the body instructions. When writing your own.agent.md, use VS Code's Outline view (Ctrl+Shift+O) to verify that your Markdown headings (Purpose, Capabilities, Responsibilities) are correctly nested -- malformed headings will not appear in the outline. Before submitting a PR with a new agent file, run the file through a YAML linter (install the YAML extension, or use yamllint from the terminal) -- frontmatter syntax errors silently break agent registration. YAML frontmatter fields are densely packed with colons and quotes; increase your editor font size or use a monospaced font with wide character spacing so name:, description:, and tools: are clearly distinct. The.agent.md files in the agents/ directory follow a consistent structure -- use the file explorer's icon theme or file nesting feature to visually group agent files separately from regular documentation. When reviewing existing agents for contribution ideas, use VS Code's split editor to place the agent file and the README side by side so you can cross-reference the agent's instructions with its documented capabilities.

      -

      Jamie: Let's pause on Practice 12.2 Step-by-Step: Submit a Formal Review Verdict. What should a learner take away from it?

      -

      Alex: Keep the learner anchored in Practice 12.2 Step-by-Step: Submit a Formal Review Verdict. Complete your review by selecting a verdict that tells the author what action to take next. This is the part to say slowly: GitHub.com (the same PR you reviewed in 14.1).

      -

      Alex: The practical takeaway is this. Comment - general feedback, no explicit approval or rejection. Approve - you think the PR is ready to merge. Request changes - you found something that should be fixed before merging. If the PR has clear documentation with only minor suggestions, choose Approve.

      -

      Alex: First, after posting your inline comments, scroll to the top of the Files changed tab. Then, activate the Review changes button (at the top-right of the files changed area, or use heading navigation). After that, a dropdown opens with three options. Finally, choose the verdict that matches your review. It is like walking a hallway with named doors: read the sign, enter the right room, then confirm where you landed.

      -

      Jamie: Before we leave Practice 12.2 Step-by-Step: Submit a Formal Review Verdict, what is the practical point?

      -

      Alex: First, write a brief summary in the review body (1-2 sentences). Example: "Clear improvement to the shortcut table. Two minor suggestions for link text clarity.". Then, activate Submit review. The rhythm is simple: orient, act, verify, then continue.

      -

      Jamie: Why is the evidence prompt part of the teaching, not just grading?

      -

      Alex: The reason Completing Challenge 12: Submit Your Evidence matters is that open your assigned Challenge 12 issue and post a completion comment. That gives the learner a simple foothold: close your Challenge 12 issue when done.

      -

      Alex: The practical takeaway is this. Student can navigate PR diffs with a screen reader. Student can post inline comments on specific lines of a diff. Student can write constructive, specific feedback that helps the author improve. Student can submit a formal review verdict.

      +

      Alex: Keep the teaching thread moving. Start with 7. The Bigger Picture: Teams, Orchestration, and Beyond VS Code: The 55 agents are not 55 independent tools. The next useful detail is this: They are organized into three teams that work together, and several orchestrator agents exist specifically to coordinate multi-agent workflows. Think of it like entering a new building: first you find the lobby, then the room, then the door you actually need.

      +

      Jamie: Let's pause on How the Three Teams Connect. What should a learner take away from it?

      +

      Alex: Here is the plain-English version of How the Three Teams Connect. In practice, a single task often spans multiple teams. Put another way, no single agent covers the entire workflow.

      +

      Alex: The practical takeaway is this. You ask @daily-briefing (GitHub Workflow) for your morning report. It flags a PR that changes ARIA attributes. You ask @pr-review (GitHub Workflow) to generate a structured review of that PR. The review notes potential accessibility impact. You invoke @aria-specialist (Accessibility) to deep-check the ARIA changes. It identifies a missing aria-expanded state on a disclosure widget. You fix the issue using patterns from @desktop-a11y-specialist (Developer Tools) if it is a desktop application, or directly in the HTML if it is a web project.

      +

      Alex: Keep the teaching thread moving. Start with Learning Cards: Teams and Orchestration. There is something to understand, something to try, and something that proves the try worked.

      +

      Alex: The practical takeaway is this. Orchestrator agents like @accessibility-lead coordinate multi-agent workflows -- invoke one and it delegates to specialists, announcing which agent it is calling. Multi-agent output appears in sequence in Copilot Chat -- press Alt+F2 after each response to read it in Accessible View before the next agent responds. The three teams are GitHub Workflow (what happened), Accessibility (is it correct), and Developer Tools (fix it) -- choose your entry point based on your current task. Orchestrator responses can be long -- use Accessible View (Alt+F2) or widen the Chat panel to read comfortably at high zoom. The workflow diagrams in this section are described in text -- no visual-only content is required to understand the agent coordination pattern. Each team's agents are listed in the tables in Section 3 -- refer back there to find the right specialist agent.

      -

      Jamie: Let's pause on If You Get Stuck. What should a learner take away from it?

      -

      Alex: Here is the plain-English version of If You Get Stuck. Continue learning: The GitHub Skills courses Review Pull Requests and Code Review with GitHub Copilot cover review workflows and AI-assisted code review. Put another way, see Appendix Z for the full catalog.

      -

      Alex: First, files Changed tab will not open? Reload the PR page and retry. Make sure you are on the PR page, not the issue page. Then, cannot find the inline comment button? Tab through the line controls in the diff. The button may be announced as "Add a comment" or have a + label. If you cannot find it, use the "Review changes" button at the top to add a general comment instead. After that, not sure what to comment on? Focus on clarity: is every heading descriptive? Is every link meaningful? Are steps complete? Are keyboard shortcuts correct? Finally, review verdict button not working? Make sure you have at least one comment or have written summary text. Try reloading the page. Treat it like a recipe: do not add the next ingredient until the previous one is actually in the bowl.

      -

      Jamie: Let's pause on If You Get Stuck. What should a learner take away from it?

      -

      Alex: First, submitting the review fails? Check that you are not in draft mode and have at least read access to the repo. Then, ask facilitator to model one inline comment and one verdict submission. After that, finished but not sure you did it right? Compare your work against the Challenge 12 reference solution. It is a checklist, but a meaningful one: every item creates evidence that the next step is safe.

      -

      Alex: Keep the teaching thread moving. This is where Learning Moment becomes real: specific, kind feedback helps authors improve and builds trust in the community. That matters in practice: Every comment you write is practice for the professional code review you will do on real projects.

      -

      Jamie: If someone only remembers one thing from Learning Pattern Used in This Chapter, what should it be?

      -

      Alex: First, read the full diff before commenting (understand the author's intent first). Then, find specific items to comment on (lines, phrases, missing steps). After that, write comments that help, not just criticize (suggest improvements, note what works). Finally, choose a verdict that matches the substance of your feedback. It is like walking a hallway with named doors: read the sign, enter the right room, then confirm where you landed.

      -

      Alex: First, summarize your overall impression in 1-2 sentences. The rhythm is simple: orient, act, verify, then continue.

      +

      Jamie: Let's pause on Orchestrator Agents. What should a learner take away from it?

      +

      Alex: Keep the learner anchored in Orchestrator Agents. Four agents are specifically designed to coordinate others. This is the part to say slowly: You do not need to use orchestrators to get value from individual agents.

      +

      Alex: Keep the teaching thread moving. The reason High-Impact Agents to Try First matters is that rather than exploring all 55 agents at once, start with the ones that deliver immediate value based on Day 1 skills you already have. The interface gets friendlier when it stops being a wall of controls and starts being a set of named places.

      +

      Jamie: Let's pause on Slash Commands That Save the Most Time. What should a learner take away from it?

      +

      Alex: Start with Slash Commands That Save the Most Time: These commands work without invoking a full agent - type them directly in Copilot Chat. The next useful detail is this: The full list of 54+ commands is in Appendix L, and Episode 39 walks through all of them with examples.

      +

      Alex: The practical takeaway is this. /my-issues and /my-prs - Instant dashboard of your open work across all repos. /review-pr 14 - Full AI-generated review with inline suggestions, replacing manual line-by-line reading. /triage 22 - Label, priority, and assignment suggestions for any new issue. /daily-briefing - Morning snapshot of repository activity, PRs needing review, and stale issues.

      -

      Alex: Keep the teaching thread moving. The reason Before starting this chapter, verify you have completed matters is that estimated time for this chapter: 1 hour (including exercises). The interface gets friendlier when it stops being a wall of controls and starts being a set of named places.

      -

      Alex: The practical takeaway is this. [ ] Chapter 6: Working with Pull Requests - Understand PR structure, diffs, and comment workflows. [ ] Chapter 13: GitHub Copilot - VS Code installed and configured. [ ] Screen Reader Setup - NVDA, JAWS, or VoiceOver installed and ready to use. [ ] Access to at least one pull request to review (your own fork or a practice repo).

      -

      Jamie: Let's pause on Two Environments for Code Review. What should a learner take away from it?

      -

      Alex: Start with Two Environments for Code Review: You can review pull requests in two places - each with different strengths. The next useful detail is this: Both environments give you full keyboard and screen reader access.

      -

      Jamie: Let's pause on About Learning Cards in This Chapter. What should a learner take away from it?

      -

      Alex: Here is the plain-English version of About Learning Cards in This Chapter. Each review step includes expandable learning cards for different interaction styles. Put another way, open the one that matches how you work.

      -

      Alex: Treat examples as spoken recipes, not decorations. You may hear something like View the full PR diff in your terminal; gh pr diff 42; View PR details (description, status, checks); gh pr view 42; Checkout the PR branch locally for testing; gh pr checkout 42; Approve the PR; gh pr review 42 --approve --body "Heading hierarchy looks. Read the command, understand what it changes, then run it only when the repository state matches the lesson.

      +

      Alex: Keep the teaching thread moving. Here is the plain-English version of Running Agents Beyond VS Code. Accessibility Agents' agents run on your machine, in your editor, when you ask for them. Put another way, the same Markdown-authored pattern extends further.

      +

      Jamie: Let's pause on Scope 1: Your Editor (Accessibility Agents). What should a learner take away from it?

      +

      Alex: Start with Scope 1: Your Editor (Accessibility Agents). There is something to understand, something to try, and something that proves the try worked.

      +

      Alex: The practical takeaway is this. File lives in.github/agents/[name].agent.md in your workspace. Triggered by: You, when you type @[agent-name] in Copilot Chat. Runs on: Your machine, using your Copilot subscription. Reaches: Every repository your GitHub account has access to. Scale: All 55 agents available when the workspace is open.

      +

      Alex: Keep the teaching thread moving. Keep the learner anchored in Scope 2: Your Repository (Travels with Forks). When you fork accessibility-agents, all 55 agents come with it. This is the part to say slowly: You can edit them for your project's context. A good GitHub workflow is like a well-run meeting: everyone knows the topic, the next action, and who has the floor.

      +

      Alex: The practical takeaway is this. File lives in.github/agents/[name].agent.md in the repo. Triggered by: Any contributor who has Copilot and opens the repo as a VS Code workspace. Runs on: Their machine, using their Copilot subscription. Reaches: Their GitHub account's repositories.

      -

      Jamie: Let's pause on Good News: Modern Interface is Default. What should a learner take away from it?

      -

      Alex: This is where Good News: Modern Interface is Default becomes real: as of January 2026, GitHub's improved Files Changed experience is enabled by default. That matters in practice: The instructions below assume you have the modern interface (which you do).

      -

      Jamie: Let's pause on Step 1: Reach the Files Changed Tab. What should a learner take away from it?

      -

      Alex: Keep the learner anchored in Step 1: Reach the Files Changed Tab. Click the Files changed tab at the top of the PR page. This is the part to say slowly: The tab label shows the number of changed files (e.g., "Files changed 4"). A good GitHub workflow is like a well-run meeting: everyone knows the topic, the next action, and who has the floor.

      -

      Alex: First, the PR tabs (Conversation, Commits, Checks, Files changed) are across the top of the PR page. At high zoom they may wrap to multiple lines. Then, the Files changed tab includes a badge with the number of changed files. This badge uses text (not colour alone) so it is visible in all themes. After that, after clicking Files changed, the diff page loads. At high zoom, the file tree panel on the left may collapse automatically. Click the file tree toggle (a small panel icon) or press T to toggle it back. Finally, added lines use a green background; removed lines use red. In high contrast browser settings (Windows: Settings Accessibility Contrast themes), these colours map to strong border indicators. It is like walking a hallway with named doors: read the sign, enter the right room, then confirm where you landed.

      -

      Jamie: Before we leave Step 1: Reach the Files Changed Tab, what is the practical point?

      -

      Alex: First, use Ctrl++ to zoom the browser if the diff text is too small, and Ctrl+- to zoom out. The rhythm is simple: orient, act, verify, then continue.

      -

      Alex: Treat examples as spoken recipes, not decorations. You may hear something like Press D → navigate to "Pull request navigation tabs" landmark; Press → or Tab → find "Files changed" link → Enter. Read the command, understand what it changes, then run it only when the repository state matches the lesson.

      -

      Jamie: Let's pause on Step 2: Use the File Tree to Orient Yourself. What should a learner take away from it?

      -

      Alex: The reason Step 2: Use the File Tree to Orient Yourself matters is that the file tree panel lists every changed file. That gives the learner a simple foothold: before reading any diff, scan this list to understand the scope of the PR.

      +

      Jamie: Let's pause on Scope 3: The Cloud (GitHub Agentic Workflows). What should a learner take away from it?

      +

      Alex: The reason Scope 3: The Cloud (GitHub Agentic Workflows) matters is that the workflow runs whether or not anyone is watching - when an issue is opened at 3am, the agentic response fires. That gives the learner a simple foothold: the link between Accessibility Agents and Agentic Workflows: Both use Markdown-authored instructions.

      +

      Alex: The practical takeaway is this. File lives in.github/workflows/[name].md (same folder as standard Actions YAML). Triggered by: Any GitHub event - issues: opened, pull request: created, schedule. Runs on: GitHub Actions infrastructure, serverlessly. Reaches: The repository where the workflow is defined.

      +

      Alex: Keep the teaching thread moving. Start with Go Deeper: For full documentation on every agent, all 54+ slash commands, customization formats, and troubleshooting, see Appendix L: Accessibility Agents Reference. The next useful detail is this: For the audio version, listen to Episode 39: Accessibility Agents - Complete Reference.

      +

      Jamie: Let's pause on Example: Auto-triage accessibility issues. What should a learner take away from it?

      +

      Alex: Here is the plain-English version of Example: Auto-triage accessibility issues. File.github/workflows/auto-triage-a11y.md. Put another way, this runs automatically on every new issue.

      -

      Jamie: Let's pause on What to listen for / look for. What should a learner take away from it?

      -

      Alex: Start with What to listen for / look for: Low vision users (zoom, high contrast).

      -

      Alex: The practical takeaway is this. How many files changed? Which areas of the codebase are affected? Are there unexpected files (generated files, lock files, configuration changes)?

      -

      Alex: First, the file tree shows each filename with a colour-coded bar indicating lines added (green) and removed (red). In high contrast mode, these bars may be less visible - the +N / -N text badge next to each file is the reliable indicator. Then, at high zoom, long file paths truncate. Hover over a truncated name to see the full path in a tooltip. After that, if the file tree panel is too narrow at high zoom, drag its right edge to widen it, or toggle it off and use heading navigation (H key) to move between file diffs. Think of it as a rail line: each stop confirms you are still on the right route before the next one.

      -

      Jamie: Let's pause on Step 3: Navigate Between File Diffs. What should a learner take away from it?

      -

      Alex: Here is the plain-English version of Step 3: Navigate Between File Diffs. Each changed file in the main area is an h3 heading containing the filename. Put another way, scroll through the page or click a filename in the file tree on the left.

      -

      Alex: Treat examples as spoken recipes, not decorations. You may hear something like Press 3 to jump file-by-file through the diff; Listen for: "learning-room/docs/keyboard-shortcuts.md - collapsed" or "expanded"; Press Enter or Space to expand a collapsed file. Quick Nav H or VO+Cmd+H to jump file-by-file through the diff; Listen for: "learning-room/docs/keyboard-shortcuts.md - collapsed" or "expanded"; VO+Space to expand a collapsed file. Read the command, understand what it changes, then run it only when the repository state matches the lesson.

      -

      Jamie: Let's pause on Step 4: Read a Diff. What should a learner take away from it?

      -

      Alex: This is where Step 4: Read a Diff becomes real: low vision users (zoom, high contrast). That matters in practice: Screen reader users - VoiceOver (macOS). The workshop is closer to rehearsal than lecture. You hear the move, try the move, and then check what changed.

      -

      Alex: The practical takeaway is this. Green highlighted lines (with a +) = lines added. Red highlighted lines (with a -) = lines removed. Plain/white lines = unchanged context. Use Ctrl+F to search within the page for specific text in the diff.

      -

      Alex: First, colour is not the only indicator. Every added line has a + character in the gutter; every removed line has a -. These text characters are reliable regardless of colour settings. Then, at high zoom, long lines of code wrap. The +/- gutter character stays at the beginning of the first line, so look left to determine the change type. After that, use Ctrl+F (browser find) to search for specific text across the entire diff page. Finally, if the diff is split view (side by side), it may be very wide at high zoom. Switch to unified diff mode: click the gear icon in the Files Changed toolbar and select "Unified" - this shows old and new in a single column. It is a checklist, but a meaningful one: every item creates evidence that the next step is safe.

      -

      Jamie: Before we leave Step 4: Read a Diff, what is the practical point?

      -

      Alex: First, high contrast themes in Windows (Settings Accessibility Contrast themes) make the +/- lines use bold border patterns instead of subtle colour shading. It is like walking a hallway with named doors: read the sign, enter the right room, then confirm where you landed.

      -

      Alex: Treat examples as spoken recipes, not decorations. You may hear something like Press T to jump to the diff table then Insert+Space (Focus Mode); Press Down Arrow to move through lines one at a time; Press Ctrl+Alt+Right Arrow to read across columns: line number, change type, code content. Press T to jump to the diff table then Insert+Z (Virtual PC Cursor off); Press Down Arrow to move through lines; Press Ctrl+Alt+Right Arrow for column-by-column reading. Read the command, understand what it changes, then run it only when the repository state matches the lesson.

      +

      Alex: Keep the teaching thread moving. This is where 8. GitHub Desktop, GitHub CLI, and Copilot CLI becomes real: these tools are not required for this workshop, but are worth knowing as options for different workflows. The workshop is closer to rehearsal than lecture. You hear the move, try the move, and then check what changed.

      +

      Jamie: Let's pause on GitHub Desktop. What should a learner take away from it?

      +

      Alex: Keep the learner anchored in GitHub Desktop. A graphical Git application with an accessible interface. This is the part to say slowly: When to use: If command-line Git feels overwhelming, GitHub Desktop provides a GUI alternative.

      +

      Alex: The practical takeaway is this. Download: desktop.github.com. Useful for: Visual diff review, simpler branch management. Screen reader support: Partial - keyboard navigation works for core flows.

      +

      Alex: Keep the teaching thread moving. The reason GitHub CLI (gh) matters is that a command-line interface for GitHub operations.

      -

      Jamie: Let's pause on What each line announces / shows. What should a learner take away from it?

      -

      Alex: Keep the learner anchored in What each line announces / shows. If the code on a line is very long, the screen reader will read the full line. This is the part to say slowly: For minified or generated files, consider collapsing the file in the tree and skipping it.

      -

      Alex: The practical takeaway is this. Added lines: "+ [code content]" - or announced as "inserted". Removed lines: "- [code content]" - or announced as "deleted". Context lines: code without a + or -.

      -

      Jamie: Let's pause on Step 5: Place an Inline Comment. What should a learner take away from it?

      -

      Alex: The reason Step 5: Place an Inline Comment matters is that when you have a specific observation about a particular line, place an inline comment directly on it. That gives the learner a simple foothold: screen reader users (VoiceOver - macOS).

      -

      Alex: First, hover your mouse over a line in the diff - a blue + (comment) button appears on the left. Then, click it to open the inline comment box. After that, type your comment. Finally, click "Start a review" (not "Add single comment" - see note below). The rhythm is simple: orient, act, verify, then continue.

      -

      Jamie: Let's pause on Placing a multi-line comment. What should a learner take away from it?

      -

      Alex: Start with Placing a multi-line comment: Click and drag across multiple line numbers in the diff gutter to select a range. The next useful detail is this: A comment button appears for the selected range.

      +

      Jamie: What should they understand before typing anything?

      +

      Alex: Start with Authenticate. There is something to understand, something to try, and something that proves the try worked.

      +

      Alex: Treat examples as spoken recipes, not decorations. You may hear something like gh auth login. Read the command, understand what it changes, then run it only when the repository state matches the lesson.

      +

      Jamie: Let's pause on Common commands. What should a learner take away from it?

      +

      Alex: Here is the plain-English version of Common commands. Screen reader advantage: gh output is plain text with no dynamic regions - more predictable than the browser for certain operations. It is like learning a transit route. The names of the stops matter because they tell you whether you are still going the right direction.

      +

      Alex: Treat examples as spoken recipes, not decorations. You may hear something like gh issue list List issues in current repo; gh issue view 42 Read issue 42; gh pr list List pull requests; gh pr view 14 Read PR 14; gh pr create Create a new PR interactively; gh pr merge 14 Merge PR 14; gh repo clone owner/repo Clone a repository; gh repo. Read the command, understand what it changes, then run it only when the repository state matches the lesson.

      +

      Jamie: Let's pause on GitHub Copilot CLI (gh copilot). What should a learner take away from it?

      +

      Alex: This is where GitHub Copilot CLI (gh copilot) becomes real: an extension that adds Copilot to the terminal.

      -

      Jamie: Let's pause on Step 6: Read Existing Comments and Threads. What should a learner take away from it?

      -

      Alex: Here is the plain-English version of Step 6: Read Existing Comments and Threads. Inline comments from other reviewers appear as h3 headings within the diff table. Put another way, each thread shows: reviewer username, comment body, replies, a "Reply" link and resolution button. It is like learning a transit route. The names of the stops matter because they tell you whether you are still going the right direction.

      -

      Alex: Treat examples as spoken recipes, not decorations. You may hear something like Tab to the "Resolve conversation" button → Enter. Tab to the "Resolve conversation" button → VO+Space. Read the command, understand what it changes, then run it only when the repository state matches the lesson.

      -

      Jamie: Let's pause on Step 7: Submit Your Review. What should a learner take away from it?

      -

      Alex: This is where Step 7: Submit Your Review becomes real: screen reader users (VoiceOver - macOS).

      -

      Alex: First, click the "Review changes" button (top-right of the Files Changed page or bottom of the PR). Then, a dialog opens with a summary text area and three radio buttons: Comment / Approve / Request changes. After that, optionally type an overall summary in the text area. Finally, select your verdict. It is a checklist, but a meaningful one: every item creates evidence that the next step is safe.

      -

      Jamie: Before we leave Step 7: Submit Your Review, what is the practical point?

      -

      Alex: First, click "Submit review". It is like walking a hallway with named doors: read the sign, enter the right room, then confirm where you landed.

      -

      Jamie: Let's pause on Step 8: Re-request Review (for Authors). What should a learner take away from it?

      -

      Alex: Keep the learner anchored in Step 8: Re-request Review (for Authors). After you address review comments on your own PR. This is the part to say slowly: Look in the right sidebar for the Reviewers section.

      -

      Alex: Treat examples as spoken recipes, not decorations. You may hear something like Step 1: From your PR's Conversation tab, Quick Nav H or VO+Cmd+H to find the "Reviewers" heading in the sidebar; Step 2: Tab or Quick Nav B to find the re-request icon ("Re-request review") next to the reviewer's name; Step 3: VO+Space to activate - this. Read the command, understand what it changes, then run it only when the repository state matches the lesson.

      +

      Jamie: Let's pause on Install. What should a learner take away from it?

      +

      Alex: Start with Install. There is something to understand, something to try, and something that proves the try worked.

      +

      Alex: Treat examples as spoken recipes, not decorations. You may hear something like gh extension install github/gh-copilot. Read the command, understand what it changes, then run it only when the repository state matches the lesson.

      +

      Jamie: Let's pause on Commands. What should a learner take away from it?

      +

      Alex: The reason Commands matters is that use case: When you know what you want to do but are unsure of the exact git command syntax.

      +

      Alex: Treat examples as spoken recipes, not decorations. You may hear something like Ask Copilot to explain a command; gh copilot explain "git rebase -i HEAD 3"; Ask Copilot to suggest a command; gh copilot suggest "undo my last commit but keep the changes"; Ask Copilot to write a shell script; gh copilot suggest "create a script that finds. Read the command, understand what it changes, then run it only when the repository state matches the lesson.

      +

      Jamie: Let's pause on Example session. What should a learner take away from it?

      +

      Alex: Start with Example session. There is something to understand, something to try, and something that proves the try worked.

      +

      Alex: Treat examples as spoken recipes, not decorations. You may hear something like $ gh copilot suggest "show me all commits from last week"; Suggestion: git log --since="1 week ago" --oneline; Run this command? (Y/n). Read the command, understand what it changes, then run it only when the repository state matches the lesson.

      -

      Jamie: Let's pause on Learning Cards: Reviewing on GitHub.com. What should a learner take away from it?

      -

      Alex: Start with Learning Cards: Reviewing on GitHub.com. There is something to understand, something to try, and something that proves the try worked.

      -

      Alex: The practical takeaway is this. In the Files Changed tab, press T to jump to the diff table, then use Focus Mode (Insert+Space in NVDA, Insert+Z in JAWS) and Down Arrow to read line by line -- each added line starts with + and each removed line with -. To place an inline comment, navigate to the target line and press Tab or B to find the "Add a comment to this line" button; after typing your comment, choose "Start a review" (not "Add single comment") to batch all feedback into one notification. Submit your full review by pressing B repeatedly to find the "Review changes" button; the dialog contains a radio group (Comment / Approve / Request changes) navigable with Arrow keys, then Tab to "Submit review". Switch from split diff to unified diff (gear icon in the Files Changed toolbar then select "Unified") to show old and new code in a single column -- much easier to follow at high zoom than two side-by-side panes. The blue + comment button appears in the line gutter on hover; at high zoom it may be small -- use Ctrl++ to increase browser zoom and look just left of the line number column. The "Review changes" dialog uses clearly labeled radio buttons for the three verdict types; each label includes a brief description, and the currently selected option has a filled circle indicator visible in all themes.

      -

      Alex: Keep the teaching thread moving. Start with Reviewing in VS Code with the Accessible Diff Viewer: When you check out a branch locally, VS Code's diff editor offers the Accessible Diff Viewer - a purpose-built, line-by-line reading mode designed specifically for screen readers. Think of it like entering a new building: first you find the lobby, then the room, then the door you actually need.

      -

      Jamie: Let's pause on Opening a Diff in VS Code. What should a learner take away from it?

      -

      Alex: Here is the plain-English version of Opening a Diff in VS Code. If you have the GitHub Pull Requests extension. Put another way, without the extension, any git diff operation also opens the diff editor.

      -

      Alex: First, open the GitHub Pull Requests view (Explorer sidebar or Ctrl+Shift+P → "GitHub Pull Requests: View Pull Request"). Then, find the PR and open it - changed files appear in the file tree. After that, navigate to any file in the tree and press Enter to open its diff view. Treat it like a recipe: do not add the next ingredient until the previous one is actually in the bowl.

      +

      Jamie: Let's pause on Learning Cards: GitHub Desktop, GitHub CLI, and Copilot CLI. What should a learner take away from it?

      +

      Alex: Start with Learning Cards: GitHub Desktop, GitHub CLI, and Copilot CLI. There is something to understand, something to try, and something that proves the try worked.

      +

      Alex: The practical takeaway is this. GitHub Desktop is a native application -- on Windows it uses UI Automation, not a browser DOM; your screen reader's object navigation (NVDA: Insert+Numpad) rather than browse mode is the correct approach for navigating its interface. GitHub CLI (gh) is entirely terminal-based; all output is plain text that your screen reader reads line by line -- pipe verbose output through head -20 or Select-Object -First 20 to avoid overwhelming your speech buffer. Copilot CLI (gh copilot suggest and gh copilot explain) presents interactive prompts in the terminal; listen for the "Run this command? (Y/n)" confirmation before pressing Enter to avoid executing unreviewed commands. GitHub Desktop inherits your Windows display scaling -- if text appears small, increase system-level scaling (Settings Display Scale) rather than looking for an in-app zoom option. Terminal output from gh and gh copilot uses your terminal's font and color settings; configure your terminal profile (Windows Terminal settings or iTerm2 preferences) with a high-contrast color scheme and large font for comfortable reading. Copilot CLI suggestions appear as plain text in the terminal, not in a styled panel -- they are easy to miss among other output; look for the indented suggestion block immediately after your prompt.

      +

      Alex: Keep the teaching thread moving. This is where "Agent not found" becomes real: issue: Typing @agent-name shows "No agent found.".

      +

      Jamie: Let's pause on Solutions. What should a learner take away from it?

      +

      Alex: Start with Solutions. There is something to understand, something to try, and something that proves the try worked.

      +

      Alex: First, verify.github/agents/[name].agent.md exists in your workspace. Then, reload VS Code window: Ctrl+Shift+P → "Reload Window". After that, check file naming: must end with.agent.md. Finally, verify YAML frontmatter is valid (no syntax errors). It is like walking a hallway with named doors: read the sign, enter the right room, then confirm where you landed.

      -

      Jamie: Let's pause on Learning Cards: VS Code Code Review. What should a learner take away from it?

      -

      Alex: This is where Learning Cards: VS Code Code Review becomes real: low vision users (zoom, high contrast). That matters in practice: VS Code's diff editor works well at high zoom.

      -

      Alex: First, split view vs. inline: By default, VS Code shows diffs in a split (side-by-side) view. At high zoom this can be very cramped. Switch to inline mode: Ctrl+Shift+P then type "Toggle Inline View" in any diff editor. Inline mode shows old and new code in a single. Then, colour indicators: Added lines have a green gutter bar; removed lines have a red gutter bar. In high contrast themes, these use heavy solid borders that are visible even at extreme zoom levels. After that, change navigation: Press F7 to jump to the next change and Shift+F7 for the previous. Each change is highlighted with a visible focus box that moves with your position - much easier than scrolling at high zoom. Finally, minimap in diff view: The minimap (right edge) shows an overview of changes as coloured blocks. At high zoom the minimap may be too small to be useful - disable it via Settings if it adds visual noise. It is a checklist, but a meaningful one: every item creates evidence that the next step is safe.

      -

      Jamie: Before we leave Learning Cards: VS Code Code Review, what is the practical point?

      -

      Alex: First, font size for diffs: Diff editors use your configured editor font size (editor.fontSize). Increase this in Settings (Ctrl+,) if the diff text is too small at your zoom level. Then, comment highlight: When you add a comment through the GitHub PR extension, the commented line gets a distinct background. In high contrast themes this is a solid colour band. It is like walking a hallway with named doors: read the sign, enter the right room, then confirm where you landed.

      -

      Jamie: Let's pause on Opening the PR for review. What should a learner take away from it?

      -

      Alex: Start with Opening the PR for review. There is something to understand, something to try, and something that proves the try worked.

      -

      Alex: First, press Ctrl+Shift+P, type "GitHub Pull Requests: View Pull Request". Then, the PR tree appears in the sidebar - navigate with Down Arrow. After that, each changed file is announced with its name and change summary. Finally, press Enter on a file to open its diff editor. It is like walking a hallway with named doors: read the sign, enter the right room, then confirm where you landed.

      -

      Jamie: Before we leave Opening the PR for review, what is the practical point?

      -

      Alex: First, the diff editor opens with the standard VS Code diff layout. The rhythm is simple: orient, act, verify, then continue.

      -

      Jamie: Let's pause on Using the Accessible Diff Viewer. What should a learner take away from it?

      -

      Alex: Start with Using the Accessible Diff Viewer. There is something to understand, something to try, and something that proves the try worked.

      -

      Alex: First, in the diff editor, press F7 to open the Accessible Diff Viewer. Then, NVDA announces: "Changed lines X to Y in filename, Change 1 of N". After that, the viewer shows each change with "Removed:" and "Added:" labels. Finally, press F7 to move to the next change, Shift+F7 for previous. The rhythm is simple: orient, act, verify, then continue.

      -

      Jamie: Before we leave Using the Accessible Diff Viewer, what is the practical point?

      -

      Alex: First, press Escape when done to close the viewer. Think of it as a rail line: each stop confirms you are still on the right route before the next one.

      +

      Alex: Keep the teaching thread moving. The reason Agent produces incorrect output matters is that issue: Agent's response is wrong or misses context. The interface gets friendlier when it stops being a wall of controls and starts being a set of named places.

      +

      Jamie: Before we leave Solutions, what is the practical point?

      +

      Alex: First, provide more context in your prompt: Be specific about what you need. Then, use @ mentions: Reference specific files or selections (@filename.md, selection). After that, check the agent's prerequisites: Did you do the manual work first? Finally, review the agent's instructions: Open.github/agents/[name].agent.md and read what it's supposed to do. Think of it as a rail line: each stop confirms you are still on the right route before the next one.

      +

      Alex: Keep the teaching thread moving. Here is the plain-English version of Slash command doesn't work. Issue: /command shows "Command not found.".

      -

      Jamie: Let's pause on Placing a comment. What should a learner take away from it?

      -

      Alex: Start with Placing a comment: Screen reader users (VoiceOver on macOS).

      -

      Alex: First, navigate to the line you want to comment on in the diff. Then, press Ctrl+Shift+P, type "GitHub Pull Requests: Add Comment". After that, a text area opens below the line - NVDA announces the input focus. Finally, type your comment. Think of it as a rail line: each stop confirms you are still on the right route before the next one.

      -

      Jamie: Before we leave Placing a comment, what is the practical point?

      -

      Alex: First, press Tab to the Submit button, then Enter. Treat it like a recipe: do not add the next ingredient until the previous one is actually in the bowl.

      -

      Jamie: Let's pause on Opening the PR. What should a learner take away from it?

      -

      Alex: Start with Opening the PR. There is something to understand, something to try, and something that proves the try worked.

      -

      Alex: First, press Cmd+Shift+P, type "GitHub Pull Requests: View Pull Request". Then, navigate the PR tree with VO+Down Arrow. After that, press Return on a file to open its diff. Treat it like a recipe: do not add the next ingredient until the previous one is actually in the bowl.

      -

      Jamie: Before we leave Accessible Diff Viewer, what is the practical point?

      -

      Alex: Start with Accessible Diff Viewer. There is something to understand, something to try, and something that proves the try worked.

      -

      Alex: First, press F7 in the diff editor. Then, VoiceOver announces each change with clear "Removed" and "Added" labels. After that, navigate with F7/Shift+F7. Finally, press Escape to close. It is a checklist, but a meaningful one: every item creates evidence that the next step is safe.

      +

      Jamie: What is the teaching move inside Solutions?

      +

      Alex: This is where Solutions becomes real: next: Chapter 20: Build Your Agent Back: Chapter 18: Fork and Contribute Related appendices: Appendix L: Agents Reference Appendix K: Copilot Reference.

      +

      Alex: First, verify.github/prompts/[name].md exists. Then, reload window: Ctrl+Shift+P → "Reload Window". After that, check file naming: must be a.md file in.github/prompts/. Finally, try typing the full command name (autocomplete may be incomplete). It is a checklist, but a meaningful one: every item creates evidence that the next step is safe.

      +

      Alex: Keep the teaching thread moving. Keep the learner anchored in Complete Reference - Agents, Slash Commands, Instructions, Configuration Levels, and All File Formats. This is your comprehensive reference for Accessibility Agents and the full VS Code Copilot customization system. This is the part to say slowly: The ecosystem includes 55 agents across 3 teams and 5 platforms, plus 54+ slash commands, 17 skills, and 6 instruction files. A good GitHub workflow is like a well-run meeting: everyone knows the topic, the next action, and who has the floor.

      +

      Jamie: Let's pause on 1. The Full Agent Ecosystem. What should a learner take away from it?

      +

      Alex: The reason 1. The Full Agent Ecosystem matters is that accessibility Agents includes 55 agents organized into three specialized teams, available on five platforms.

      -

      Jamie: Let's pause on Comment placement. What should a learner take away from it?

      -

      Alex: Start with Comment placement. There is something to understand, something to try, and something that proves the try worked.

      -

      Alex: First, press Cmd+Shift+P, type "GitHub Pull Requests: Add Comment". Then, vO+Shift+Down Arrow to interact with the comment text area. After that, type your comment. Finally, vO+Shift+Up Arrow to stop interacting, then Tab to Submit. It is like walking a hallway with named doors: read the sign, enter the right room, then confirm where you landed.

      -

      Jamie: Let's pause on Using the Accessible Diff Viewer (F7). What should a learner take away from it?

      -

      Alex: The reason Using the Accessible Diff Viewer (F7) matters is that the Accessible Diff Viewer reads each change as a structured block. That gives the learner a simple foothold: this example is from a real Learning Room scenario: a contributor fixing the heading hierarchy in docs/keyboard-shortcuts.md by changing a level-4 heading to level-3, which is exactly what you look for when reviewing Challenge 2 PRs.

      -

      Alex: Treat examples as spoken recipes, not decorations. You may hear something like "Changed lines 14 to 14 in docs/keyboard-shortcuts.md; [Change 1 of 3]; Removed:; NVDA Single-Key Navigation; Added:; NVDA Single-Key Navigation". Read the command, understand what it changes, then run it only when the repository state matches the lesson.

      -

      Alex: Keep the teaching thread moving. Start with Navigation. There is something to understand, something to try, and something that proves the try worked.

      -

      Alex: The practical takeaway is this. F7 - jump to next change (next hunk). Shift+F7 - jump to previous change. Alt+F2 - open VS Code's Accessible View for additional context on the current item. Escape - close the Accessible Diff Viewer.

      +

      Alex: Keep the teaching thread moving. Start with Learning Cards: Agent Ecosystem Overview. There is something to understand, something to try, and something that proves the try worked.

      +

      Alex: The practical takeaway is this. Invoke any agent by typing @agent-name in Copilot Chat (Ctrl+Shift+I) -- the autocomplete list is keyboard-navigable with arrow keys. The 55 agents are organized into 3 teams (Accessibility, GitHub Workflow, Developer Tools) -- use H in the team tables to jump between headings. Agent responses appear in the Chat panel; press Alt+F2 (Accessible View) for a structured, non-streaming version. The agent team tables use consistent columns (Agent, Type, What It Does) -- increase font size so the narrow "Type" column remains readable. Agents work in the Chat panel with your current theme and font settings -- no separate UI to configure. The five supported platforms (VS Code, Claude Code, Gemini CLI, Claude Desktop, Codex CLI) share the same agent logic with platform-specific formatting.

      +

      Jamie: Let's pause on 2. GitHub Workflow Agents - Quick Reference. What should a learner take away from it?

      +

      Alex: Here is the plain-English version of 2. GitHub Workflow Agents - Quick Reference. The GitHub Workflow team includes 12 agents that automate common repository operations. Put another way, these are good starting points if you have completed the Day 1 skills - but explore any agent in the ecosystem that matches your workflow.\n\nInvoke any agent by typing @agent-name in Copilot Chat (Ctrl+Shift+I).

      +

      Alex: Keep the teaching thread moving. This is where @daily-briefing - Morning Briefing becomes real: agent file.github/agents/daily-briefing.agent.md. The workshop is closer to rehearsal than lecture. You hear the move, try the move, and then check what changed.

      -

      Jamie: Let's pause on What makes this better than the raw diff editor. What should a learner take away from it?

      -

      Alex: Start with What makes this better than the raw diff editor. There is something to understand, something to try, and something that proves the try worked.

      -

      Alex: The practical takeaway is this. Each change is announced as a discrete unit with clear "Removed:" and "Added:" labels. You hear the change number of total changes ("Change 3 of 12"). No table navigation required - purpose-built for sequential listening. Works with all three major screen readers without any special configuration.

      -

      Alex: Keep the teaching thread moving. This is where Placing Comments in VS Code (GitHub PR Extension) becomes real: from the diff editor with the GitHub PR extension. That matters in practice: Comments placed in VS Code sync to GitHub - they appear in the PR's Files Changed tab and the author receives the same notification. The workshop is closer to rehearsal than lecture. You hear the move, try the move, and then check what changed.

      -

      Jamie: Let's pause on The Anatomy of a Useful Review Comment. What should a learner take away from it?

      -

      Alex: Keep the learner anchored in The Anatomy of a Useful Review Comment. A comment that helps the author is.

      -

      Alex: First, specific - link to the exact line and name the pattern you see. Then, educational - say why something matters, not just what to change. After that, graduated - signal whether this is blocking, or a preference. It is like walking a hallway with named doors: read the sign, enter the right room, then confirm where you landed.

      +

      Jamie: Let's pause on Output sections (H2 headings - navigate with H). What should a learner take away from it?

      +

      Alex: Start with Output sections (H2 headings - navigate with H). There is something to understand, something to try, and something that proves the try worked.

      +

      Alex: The practical takeaway is this. Needs Your Action. Pull Requests Waiting for Your Review. @Mentions Requiring Response. CI Failures on Your Branches. For Your Awareness. Issues Opened Since Yesterday.

      +

      Alex: Keep the teaching thread moving. The reason @issue-tracker - Issue Management matters is that agent file.github/agents/issue-tracker.agent.md. That gives the learner a simple foothold: the agent drafts replies.

      +

      Jamie: Let's pause on @pr-review - Pull Request Review. What should a learner take away from it?

      +

      Alex: Start with @pr-review - Pull Request Review: Agent file.github/agents/pr-review.agent.md.

      -

      Alex: Keep the teaching thread moving. The reason Blocking example (reviewing a PR for docs/keyboard-shortcuts.md) matters is that "The heading on line 34 uses (level 4) directly after (level 2), skipping heading level 3. That gives the learner a simple foothold: screen reader users who navigate by heading level will miss any content between those two levels.

      -

      Jamie: Let's pause on Non-blocking (nit) example (reviewing a PR for docs/welcome.md). What should a learner take away from it?

      -

      Alex: Start with Non-blocking (nit) example (reviewing a PR for docs/welcome.md): "nit: The link text in the 'Getting Help' section reads 'click here for more information.' Screen reader users who navigate links out of context will hear only 'click here' with no destination. The next useful detail is this: Consider 'See the accessibility setup guide' instead.

      -

      Alex: Keep the teaching thread moving. Here is the plain-English version of Question example (reviewing a PR for docs/setup-guide.md). "The PR description says this fixes broken links in the setup guide, but the link on line 12 still points to /docs/old-setup. Put another way, am I reading the diff correctly, or was this link intentionally left? It is like learning a transit route. The names of the stops matter because they tell you whether you are still going the right direction.

      +

      Alex: Keep the teaching thread moving. Here is the plain-English version of Output sections (H2/H3 headings). Critical rule: The agent produces a starting point. Put another way, read it, edit it, post it under your own name. It is like learning a transit route. The names of the stops matter because they tell you whether you are still going the right direction.

      +

      Alex: The practical takeaway is this. Risk Assessment (High / Medium / Low). Files Changed (per-file descriptions). Suggested Inline Comments (prefixed: nit:, question:, suggestion:, important:, blocking:, praise:). Questions for the Author.

      +

      Jamie: Let's pause on @analytics - Team Analytics. What should a learner take away from it?

      +

      Alex: This is where @analytics - Team Analytics becomes real: agent file.github/agents/analytics.agent.md.

      +

      Alex: Keep the teaching thread moving. Keep the learner anchored in @insiders-a11y-tracker - Accessibility Change Monitor. Agent file.github/agents/insiders-a11y-tracker.agent.md.

      -

      Jamie: Let's pause on Prefixes That Set Expectations. What should a learner take away from it?

      -

      Alex: This is where Prefixes That Set Expectations becomes real: using shorthand prefixes helps authors parse many comments quickly.

      -

      Alex: Keep the teaching thread moving. Keep the learner anchored in How Many Comments Is Too Many? There is no hard limit, but quantity without prioritization is noise. This is the part to say slowly: If you have 15 comments, make clear which 2-3 are blocking.

      -

      Jamie: Let's pause on "I want to verify the PR only changes what it claims". What should a learner take away from it?

      -

      Alex: The reason "I want to verify the PR only changes what it claims" matters is that example: A PR says "Challenge 2: Add NVDA shortcut" but the file tree shows changes to both docs/keyboard-shortcuts.md and docs/welcome.md.

      +

      Jamie: Let's pause on What it monitors. What should a learner take away from it?

      +

      Alex: The reason What it monitors matters is that risk levels: High (regression), Medium (degraded), Low (improvement opportunity).

      +

      Alex: Keep the teaching thread moving. Start with @template-builder - Issue Template Wizard: Agent file.github/agents/template-builder.agent.md. Think of it like entering a new building: first you find the lobby, then the room, then the door you actually need.

      +

      Jamie: Let's pause on Guided workflow phases. What should a learner take away from it?

      +

      Alex: Here is the plain-English version of Guided workflow phases. Supported field types: markdown, input, textarea, dropdown, checkboxes.

      +

      Alex: First, metadata: name, description, title prefix, auto-labels. Then, fields (one at a time): type → label → description → required → type-specific options. After that, review and output: complete YAML ready to save to.github/ISSUE TEMPLATE/. Treat it like a recipe: do not add the next ingredient until the previous one is actually in the bowl.

      -

      Alex: Keep the teaching thread moving. Start with "I want to find all changes to one specific section": Example: A PR for Challenge 3 modified docs/welcome.md. The next useful detail is this: You want to verify the [TODO] in the "Who Can Contribute?" section was filled in correctly. Think of it like entering a new building: first you find the lobby, then the room, then the door you actually need.

      -

      Jamie: Let's pause on Exercises. What should a learner take away from it?

      -

      Alex: Here is the plain-English version of Exercises. These exercises use the files in learning-room/docs/ in this repository. Put another way, all examples involve documentation changes - no code required.

      -

      Alex: Keep the teaching thread moving. This is where Exercise A - Complete a Web Review becomes real: scenario: A contributor has submitted a pull request titled "Add screen reader tips to the setup guide." The PR modifies learning-room/docs/setup-guide.md. That matters in practice: Your job is to review it before it merges.

      +

      Alex: Keep the teaching thread moving. This is where 3. Slash Commands and Prompts becomes real: the repository includes 54+ slash commands. That matters in practice: Type / in Copilot Chat to open the command menu.

      +

      Jamie: Let's pause on 4. Customization Primitives - Decision Guide. What should a learner take away from it?

      +

      Alex: Keep the learner anchored in 4. Customization Primitives - Decision Guide. Before creating any file, choose the right primitive for the job. This is the part to say slowly: Each primitive is a different file type with a different purpose, scope, and trigger.

      +

      Alex: Keep the teaching thread moving. Start with Instructions vs Agent? There is something to understand, something to try, and something that proves the try worked.

      +

      Alex: The practical takeaway is this. Instructions guide behavior passively (always-on or file-scoped). Agents perform tasks actively (on-demand, tool-using).

      -

      Jamie: Let's pause on Step 1: Navigate to the Pull Request. What should a learner take away from it?

      -

      Alex: Keep the learner anchored in Step 1: Navigate to the Pull Request. How to know you're in the right place.

      -

      Alex: The practical takeaway is this. The PR title is visible at the top. You see a description box with text about what this PR does. You see tabs labeled "Conversation," "Commits," "Files Changed". Use Ctrl+F to search the PR list for "screen reader tips". Or ask in the workshop Slack - someone can share the exact URL.

      -

      Alex: First, open GitHub in your browser and navigate to the workshop repository (github.com/[your-fork]/[workshop-repo] or community-access/accessibility-agents). Then, click the Pull Requests tab (top navigation). After that, look for a PR titled "Add screen reader tips to the setup guide" - click it to open. Finally, you should now see the PR page with sections: Conversation, Commits, Files Changed. It is like walking a hallway with named doors: read the sign, enter the right room, then confirm where you landed.

      -

      Jamie: Let's pause on Step 2: Read the PR Description. What should a learner take away from it?

      -

      Alex: Start with Step 2: Read the PR Description. There is something to understand, something to try, and something that proves the try worked.

      -

      Alex: The practical takeaway is this. Does the PR author explain what file changed? (should mention setup-guide.md). Does it explain why? (should mention "improve accessibility" or "add tips"). Is it clear enough that a reviewer can understand the goal without reading the diff? You can answer: "This PR adds [specific content] to [specific file] because [clear reason]". Example: "This PR adds screen reader usage tips to the setup guide because new users need accessibility guidance".

      -

      Alex: First, you are currently on the Conversation tab. Then, read the PR description (the text immediately under the PR title). After that, look for: "What does this PR change?" and "Why does it change it?". Finally, with screen reader: Navigate to the description with D (NVDA) or press Ctrl+Option+Up (VoiceOver) to find main landmarks, then read the content region. The rhythm is simple: orient, act, verify, then continue.

      -

      Jamie: Let's pause on Step 3: Navigate to "Files Changed". What should a learner take away from it?

      -

      Alex: Start with Step 3: Navigate to "Files Changed". There is something to understand, something to try, and something that proves the try worked.

      -

      Alex: The practical takeaway is this. A section showing the file name setup-guide.md with a small badge showing "+20 −0" (20 lines added, 0 lines removed). Below it, the diff with removed lines (preceded by −) and added lines (preceded by +). Scroll up to see if there are other files. For this exercise, only setup-guide.md should be changed. If you see other files, confirm they are not modified (the badge should show "+0 −0" or no changes).

      -

      Alex: First, click the Files Changed tab (top of the PR page, to the right of "Commits"). Then, you are now viewing the diff. After that, with keyboard (all screen readers): Press T to jump to the diff table. The page focuses on the file comparison area. Think of it as a rail line: each stop confirms you are still on the right route before the next one.

      +

      Jamie: Let's pause on Prompt vs Agent? What should a learner take away from it?

      +

      Alex: Start with Prompt vs Agent? There is something to understand, something to try, and something that proves the try worked.

      +

      Alex: The practical takeaway is this. Use a prompt for a single focused task you invoke explicitly. Use an agent when the task spans multiple steps, needs different tools, or should work as a subagent for other agents.

      +

      Alex: Keep the teaching thread moving. Start with Prompt vs Skill? There is something to understand, something to try, and something that proves the try worked.

      +

      Alex: The practical takeaway is this. Both appear as / slash commands. Use a prompt for one well-defined task. Use a skill when the workflow bundles scripts, templates, or reference docs alongside the instructions.

      +

      Jamie: Let's pause on Instructions vs Hooks? What should a learner take away from it?

      +

      Alex: Start with Instructions vs Hooks? There is something to understand, something to try, and something that proves the try worked.

      +

      Alex: The practical takeaway is this. Instructions guide the agent (non-deterministic). Hooks enforce behavior via shell commands at lifecycle events - they run regardless of what the agent was prompted to do.

      -

      Jamie: Let's pause on Step 4: Activate Focus Mode for Better Diff Reading. What should a learner take away from it?

      -

      Alex: Here is the plain-English version of Step 4: Activate Focus Mode for Better Diff Reading. With screen reader (once in Focus Mode).

      -

      Alex: The practical takeaway is this. The page simplifies: sidebars disappear. Only the diff is visible - easier for screen reader navigation and less cognitive load. The diff is now the main content area. NVDA/JAWS: Press T to jump to the diff table. VoiceOver: Navigate with VO+Right Arrow to find the table/content region. Read through the changes: ↓ arrow moves to each line.

      -

      Alex: First, look for a button labeled "Focus Mode" or an icon (usually at the top right of the diff area). Then, with keyboard: Press F to toggle Focus Mode (may need to be in the diff area first). After that, with mouse: Click the Focus Mode button/icon. Treat it like a recipe: do not add the next ingredient until the previous one is actually in the bowl.

      -

      Jamie: Let's pause on Step 5: Find the Heading Hierarchy Issue. What should a learner take away from it?

      -

      Alex: Start with Step 5: Find the Heading Hierarchy Issue. There is something to understand, something to try, and something that proves the try worked.

      -

      Alex: The practical takeaway is this. Screen reader users navigate documents by heading level: 1 → 2 → 3 → 4. A skip from to breaks that navigation. When a user presses "jump to heading level 3," they'll find none, wondering if content is missing. You found the line with that violates hierarchy. You can say the line number and what heading text appears there. You understand why this is an accessibility problem.

      -

      Alex: First, read through the entire diff line by line. Pay special attention to lines starting. Then, you are looking for: a line with (four hashes, heading level 4) that comes directly after a (two hashes, heading level 2). After that, when you find it, note the exact line number shown in the diff. It is a checklist, but a meaningful one: every item creates evidence that the next step is safe.

      -

      Jamie: Let's pause on Step 6: Place a Blocking Review Comment on the Heading. What should a learner take away from it?

      -

      Alex: Keep the learner anchored in Step 6: Place a Blocking Review Comment on the Heading. If the comment button doesn't appear. A good GitHub workflow is like a well-run meeting: everyone knows the topic, the next action, and who has the floor.

      -

      Alex: The practical takeaway is this. Your comment appears in the thread under that line. The PR author sees it and can make the fix. Make sure you're hovering over the line number area (left side of the line). Try refreshing the page and trying again. Or use the "Add a reply" field at the bottom of the PR and mention the line number manually.

      -

      Alex: First, find the diff line with the problematic heading. Then, hover your mouse over the line number on the left side of that line (or if using keyboard, navigate to that line in the table). After that, a button should appear (or press the Add Comment hotkey - usually C in GitHub). Finally, click it or press Enter to open a comment box. It is like walking a hallway with named doors: read the sign, enter the right room, then confirm where you landed.

      -

      Jamie: Before we leave Step 6: Place a Blocking Review Comment on the Heading, what is the practical point?

      -

      Alex: First, press Space, then explain. Then, click the Comment button (or press Ctrl+Enter for keyboard submit). The rhythm is simple: orient, act, verify, then continue.

      +

      Alex: Keep the teaching thread moving. Start with Learning Cards: Customization Primitives. There is something to understand, something to try, and something that proves the try worked.

      +

      Alex: The practical takeaway is this. The decision table maps each file type to its purpose -- navigate with T (next table) in browse mode, then arrow through rows. Key distinction: instructions are passive (always-on guidance), agents are active (on-demand task performers), hooks are deterministic (shell commands at lifecycle events). Use the "Choosing Between Primitives" Q&A pairs below the table to decide which file type fits your need. The 7-row decision table is the single most important reference here -- zoom in on the "When to Use" column for the clearest guidance. Each Q&A pair under "Choosing Between Primitives" is a short paragraph -- easy to scan at high magnification. Color-coded syntax in YAML frontmatter examples benefits from a high-contrast theme with distinct keyword colors.

      +

      Jamie: Let's pause on 5. Scope and Priority - All Levels. What should a learner take away from it?

      +

      Alex: The reason 5. Scope and Priority - All Levels matters is that every customization file exists at one of three scopes. That gives the learner a simple foothold: VS Code combines all matching files from all scopes and sends them to the model.

      +

      Jamie: Let's pause on Priority Order (highest wins in conflicts). What should a learner take away from it?

      +

      Alex: Start with Priority Order (highest wins in conflicts). There is something to understand, something to try, and something that proves the try worked.

      +

      Alex: First, personal / User-level - your profile instructions override everything. Then, workspace / Repository-level -.github/copilot-instructions.md, AGENTS.md,.github/agents/.agent.md. After that, organization-level - organization-defined custom instructions (lowest priority). Think of it as a rail line: each stop confirms you are still on the right route before the next one.

      -

      Jamie: Let's pause on Step 7: Find the Link Text Issue. What should a learner take away from it?

      -

      Alex: Start with Step 7: Find the Link Text Issue. There is something to understand, something to try, and something that proves the try worked.

      -

      Alex: The practical takeaway is this. Screen reader users can ask their reader to "list all links on this page" - they hear only the link text. If the text is "click here," they have no context about where it goes. Descriptive link text is WCAG 2.4.4 (Link Purpose). You found a link with non-descriptive text. You can explain why "click here" is bad and what would be better.

      -

      Alex: First, continue reading the diff (from where you left off). Then, look for a line containing link text that reads "click here" or "click here for more information". After that, note the line number. The rhythm is simple: orient, act, verify, then continue.

      -

      Jamie: Let's pause on Step 8: Place a Comment on the Link. What should a learner take away from it?

      -

      Alex: Start with Step 8: Place a Comment on the Link: nit: means "nice-to-have improvement" (not blocking, but good to fix).

      -

      Alex: First, find the line in the diff with the problematic link. Then, hover over the line number and click to open a comment box (or press C). After that, click Comment or press Ctrl+Enter. Think of it as a rail line: each stop confirms you are still on the right route before the next one.

      -

      Jamie: Let's pause on Step 9: Submit Your Review. What should a learner take away from it?

      -

      Alex: Start with Step 9: Submit Your Review. There is something to understand, something to try, and something that proves the try worked.

      -

      Alex: The practical takeaway is this. Comment - provide feedback but don't block (for minor notes). Approve - the PR is ready to merge. Request changes - this PR cannot merge until changes are made. Your review is submitted. The PR author gets a notification. The PR shows your review with the two comments.

      -

      Alex: First, look for a button labeled "Review changes" (usually at the top right of the page or bottom of comments). Then, click it (or navigate with keyboard and press Enter). After that, a dialog appears with options. Finally, select "Request changes" (you found two things to fix). Treat it like a recipe: do not add the next ingredient until the previous one is actually in the bowl.

      -

      Jamie: Before we leave Step 9: Submit Your Review, what is the practical point?

      -

      Alex: First, in the summary field, write: Found 2 accessibility issues that must be fixed before merging. Then, click "Submit review". It is a checklist, but a meaningful one: every item creates evidence that the next step is safe.

      +

      Jamie: Let's pause on User-Level File Locations (Personal, Cross-Workspace). What should a learner take away from it?

      +

      Alex: Here is the plain-English version of User-Level File Locations (Personal, Cross-Workspace). All of these files roam with your VS Code Settings Sync. Put another way, on this machine: C:\Users\jeffb\AppData\Roaming\Code - Insiders\User\prompts.

      +

      Alex: First, enable Settings Sync (Ctrl+Shift+P → "Settings Sync: Turn On"). Then, ctrl+Shift+P → "Settings Sync: Configure". After that, check "Prompts and Instructions". Treat it like a recipe: do not add the next ingredient until the previous one is actually in the bowl.

      +

      Alex: Keep the teaching thread moving. This is where How Multiple Files Are Combined becomes real: VS Code collects all matching instruction files from all scopes and includes them all in the chat context. That matters in practice: There is no single winner - all are combined. The workshop is closer to rehearsal than lecture. You hear the move, try the move, and then check what changed.

      +

      Jamie: Let's pause on 6. Always-On Instructions - All File Types. What should a learner take away from it?

      +

      Alex: Keep the learner anchored in 6. Always-On Instructions - All File Types. Always-on instructions are automatically included in every chat request. This is the part to say slowly: You never invoke them - Copilot simply follows them.

      -

      Jamie: Let's pause on Reflect on This Exercise. What should a learner take away from it?

      -

      Alex: This is where Reflect on This Exercise becomes real: keep your answers - you'll need them for Chapter 16's Accessibility Agents exercise to compare manual review with agent-assisted review. The workshop is closer to rehearsal than lecture. You hear the move, try the move, and then check what changed.

      -

      Alex: First, did heading-level navigation help? When you were looking for the issue, was it easier to navigate by heading level (1-6) than to scan every line? Then, would you have caught this without the exercise prompt? If you were a real reviewer not specifically looking for heading issues, would the diff have been obvious? After that, why does screen reader navigation matter? In one sentence, explain why a screen reader user's ability to jump through heading levels is important for this document. It is a checklist, but a meaningful one: every item creates evidence that the next step is safe.

      -

      Jamie: How do we make tool choice feel like access, not pressure?

      -

      Alex: Keep the learner anchored in Exercise B - Use the VS Code Accessible Diff Viewer. Scenario: Review the same pull request from Exercise A, this time entirely in VS Code. This is the part to say slowly: You'll compare the browser experience with the VS Code experience.

      -

      Alex: Keep the teaching thread moving. Start with Prerequisites. There is something to understand, something to try, and something that proves the try worked.

      -

      Alex: The practical takeaway is this. VS Code must be installed on your machine. The GitHub Pull Requests extension must be installed (see Chapter 12 for installation). You must be signed into GitHub from VS Code (use Ctrl+Shift+P → "GitHub: Sign in").

      +

      Alex: Keep the teaching thread moving. The reason Option A.github/copilot-instructions.md (Recommended) matters is that version-controlled and team-shared. That gives the learner a simple foothold: auto-generate with: Type /init in Copilot Chat - VS Code analyzes your workspace and generates a tailored copilot-instructions.md.

      +

      Jamie: Let's pause on Option B: AGENTS.md (Multi-Tool / Monorepo). What should a learner take away from it?

      +

      Alex: Start with Option B: AGENTS.md (Multi-Tool / Monorepo): Best for: Projects that use multiple AI tools (Copilot, Claude Code, Gemini CLI, etc.) where a single instruction file should work across all of them. The next useful detail is this: Also best for monorepos where different folders need different rules.

      +

      Alex: Keep the teaching thread moving. Here is the plain-English version of Nested (per subfolder - experimental). Enable nested file support: chat.useNestedAgentsMdFiles: true in VS Code settings. Put another way, file structure: Same as copilot-instructions.md - plain Markdown, no frontmatter. It is like learning a transit route. The names of the stops matter because they tell you whether you are still going the right direction.

      -

      Jamie: Let's pause on Step 1: Open the GitHub Pull Requests Extension. What should a learner take away from it?

      -

      Alex: Start with Step 1: Open the GitHub Pull Requests Extension. There is something to understand, something to try, and something that proves the try worked.

      -

      Alex: The practical takeaway is this. With mouse: Click the Extensions icon on the left sidebar (looks like four squares). The extension is listed as active. It mentions: "Review and manage GitHub pull requests and issues".

      -

      Alex: First, open VS Code. Then, with keyboard (all screen readers): Press Ctrl+Shift+X to open the Extensions sidebar. After that, search for "GitHub Pull Requests". Finally, if it's not installed, click Install. Think of it as a rail line: each stop confirms you are still on the right route before the next one.

      -

      Jamie: Before we leave Step 1: Open the GitHub Pull Requests Extension, what is the practical point?

      -

      Alex: First, if it is installed, click GitHub Pull Requests to view its details. Treat it like a recipe: do not add the next ingredient until the previous one is actually in the bowl.

      -

      Jamie: Let's pause on Step 2: Open the Pull Requests Sidebar. What should a learner take away from it?

      -

      Alex: Start with Step 2: Open the Pull Requests Sidebar. There is something to understand, something to try, and something that proves the try worked.

      -

      Alex: The practical takeaway is this. With keyboard: The icon may not be keyboard-reachable directly; instead go to Step 3. VS Code opens a new editor tab for this PR. Below the PR title, you see a "Changes" section listing modified files. You should see setup-guide.md in the changes list. Use Ctrl+Shift+P → search GitHub Pull Requests: Open Pull Request. Paste the PR URL: https://github.com/[owner]/[repo]/pull/[number].

      -

      Alex: First, look for a GitHub-themed icon on the left sidebar (circle with octocat logo) - click it. Then, a sidebar appears showing open pull requests on repositories you have access to. After that, find the PR titled "Add screen reader tips to the setup guide" - it should appear in a list. Finally, click it to open. Treat it like a recipe: do not add the next ingredient until the previous one is actually in the bowl.

      -

      Jamie: Let's pause on Step 3: View the File Changes. What should a learner take away from it?

      -

      Alex: Start with Step 3: View the File Changes. There is something to understand, something to try, and something that proves the try worked.

      -

      Alex: The practical takeaway is this. A diff editor opens showing two columns. Left: the original file (before changes). Right: the new file (after changes). Different colors show added (green), removed (red), and modified (blue) lines. The file name appears at the top: setup-guide.md. NVDA/JAWS: The editor announces "Diff Editor - setup-guide.md".

      -

      Alex: First, in the Changes section, locate setup-guide.md. Then, click on the filename to open it. It is a checklist, but a meaningful one: every item creates evidence that the next step is safe.

      +

      Jamie: Let's pause on Option C: CLAUDE.md (Claude Code Compatibility). What should a learner take away from it?

      +

      Alex: This is where Option C: CLAUDE.md (Claude Code Compatibility) becomes real: best for: Teams that use Claude Code alongside VS Code. That matters in practice: VS Code recognizes all four locations when chat.useClaudeMdFile is enabled (default: on).

      +

      Alex: Keep the teaching thread moving. Keep the learner anchored in Option D: Settings-Based Instructions (Deprecated). Settings-based instructions may be removed in a future VS Code version. This is the part to say slowly: Use file-based instructions instead for new work.

      +

      Jamie: Let's pause on Organization-Level Instructions (GitHub Enterprise). What should a learner take away from it?

      +

      Alex: The reason Organization-Level Instructions (GitHub Enterprise) matters is that organization administrators can define custom instructions that apply to all repositories in the organization. That gives the learner a simple foothold: every team member gets these instructions automatically.

      -

      Jamie: Let's pause on Step 4: Access the Accessible Diff Viewer. What should a learner take away from it?

      -

      Alex: Keep the learner anchored in Step 4: Access the Accessible Diff Viewer. If the Accessible Diff Viewer doesn't open.

      -

      Alex: The practical takeaway is this. With mouse: Look for a button or menu option labeled "Accessible View" or "Open Accessible Diff". If no button is visible, try Alt+F2 (VS Code Accessible View toggle). A new panel opens at the bottom of VS Code. The panel announces each change one at a time. Changes appear in text format with labels: "Added: " and "Removed: ". The panel is read-only (you read the changes, you don't edit here).

      -

      Alex: First, with keyboard: Press F7 to open the Accessible Diff Viewer. It is like walking a hallway with named doors: read the sign, enter the right room, then confirm where you landed.

      -

      Jamie: Let's pause on Step 5: Listen to and Understand the First Change. What should a learner take away from it?

      -

      Alex: Start with Step 5: Listen to and Understand the First Change. There is something to understand, something to try, and something that proves the try worked.

      -

      Alex: The practical takeaway is this. NVDA/JAWS: The Accessible Diff Viewer announces "Removed:" and "Added:" labels, followed by the line content. VoiceOver: The announcement may be similar; listen for "removed" and "added" keywords.

      -

      Alex: First, the first change is automatically announced when you open the Accessible Diff Viewer. Then, let your screen reader read it completely - don't interrupt. After that, write down the exact text announced. Finally, press the Down arrow to move to the next change. The rhythm is simple: orient, act, verify, then continue.

      -

      Jamie: Let's pause on Step 6: Find the Heading Hierarchy Issue. What should a learner take away from it?

      -

      Alex: Start with Step 6: Find the Heading Hierarchy Issue. There is something to understand, something to try, and something that proves the try worked.

      -

      Alex: The practical takeaway is this. Four hashes ( ) indicate a level 4 heading. In the diff, you're looking for it appearing after a level 2 heading ( ). This creates the hierarchy skip you caught in Exercise A. You found the explanation in the Accessible Diff Viewer's format. You can explain: "The added line with directly follows a, skipping level 3". The Accessible Diff Viewer made this pattern clearer than scanning raw + characters.

      -

      Alex: First, continue pressing Down arrow to move through changes. Then, listen carefully for a change involving headings (lines starting with ). After that, specifically, listen for: "Added: " (four hashes). Finally, when you hear this, stop and write it down. Think of it as a rail line: each stop confirms you are still on the right route before the next one.

      +

      Alex: Keep the teaching thread moving. Start with To enable discovery in VS Code: Organization instructions are the lowest priority - workspace and user instructions override them when they conflict. Think of it like entering a new building: first you find the lobby, then the room, then the door you actually need.

      +

      Jamie: Let's pause on 7. File-Based Instructions (.instructions.md). What should a learner take away from it?

      +

      Alex: Here is the plain-English version of 7. File-Based Instructions (.instructions.md). File-based instructions load conditionally - either when the files you are editing match a glob pattern, or when the agent determines the instruction is relevant to the current task. Put another way, use for: Language-specific rules, framework conventions, module-specific standards that only apply to part of the codebase.

      +

      Alex: Keep the teaching thread moving. This is where The applyTo Glob Pattern becomes real: applyTo specifies which files trigger automatic inclusion of these instructions. That matters in practice: When a file matching the pattern is part of the chat context, the instructions are included automatically.

      -

      Jamie: Let's pause on Step 7: Locate the Heading Line and Add an Inline Comment. What should a learner take away from it?

      -

      Alex: Start with Step 7: Locate the Heading Line and Add an Inline Comment. There is something to understand, something to try, and something that proves the try worked.

      -

      Alex: The practical takeaway is this. Use Ctrl+F to open Find. Search for to locate it quickly. Press Enter to jump to it. With keyboard: The comment button may appear on the current line; navigate to it and press Enter. A comment box opens. You can type your comment.

      -

      Alex: First, once you identified the problematic heading in the Accessible Diff Viewer, close the Accessible Diff Viewer (press F7 again or Alt+F2). Then, you're back in the regular Diff Editor. After that, find the line with the problematic heading. Finally, close Find (Escape). Treat it like a recipe: do not add the next ingredient until the previous one is actually in the bowl.

      -

      Jamie: Before we leave Step 7: Locate the Heading Line and Add an Inline Comment, what is the practical point?

      -

      Alex: First, place your cursor on that line. Then, right-click and select "Add Comment" or press the Comment icon that appears on the left margin. It is a checklist, but a meaningful one: every item creates evidence that the next step is safe.

      -

      Jamie: Let's pause on Step 8: Write Your Accessible Diff Comment. What should a learner take away from it?

      -

      Alex: This is where Step 8: Write Your Accessible Diff Comment becomes real: why mention the Accessible Diff Viewer?

      -

      Alex: The practical takeaway is this. It shows that the tool itself helps you see the issue. It documents how you caught the problem (useful for learning).

      -

      Alex: First, in the comment box, type. Then, press Ctrl+Enter or click Comment to submit. It is a checklist, but a meaningful one: every item creates evidence that the next step is safe.

      -

      Jamie: Let's pause on Step 9: Create a GitHub Pull Request Comment. What should a learner take away from it?

      -

      Alex: Keep the learner anchored in Step 9: Create a GitHub Pull Request Comment. Now you've reviewed the same PR in.

      -

      Alex: First, browser (Exercise A): You spot-checked line numbers manually. Then, VS Code (Exercise B): The Diff Editor plus Accessible Diff Viewer announced changes. After that, go to GitHub in your browser and open the same PR. Finally, scroll to the bottom and leave a comment in the Conversation tab. It is like walking a hallway with named doors: read the sign, enter the right room, then confirm where you landed.

      -

      Jamie: Before we leave Step 9: Create a GitHub Pull Request Comment, what is the practical point?

      -

      Alex: First, click Comment. The rhythm is simple: orient, act, verify, then continue.

      +

      Jamie: Let's pause on Writing Effective Instructions. What should a learner take away from it?

      +

      Alex: Keep the learner anchored in Writing Effective Instructions. Guidance from GitHub's accessibility team on writing instructions that Copilot actually follows. This is the part to say slowly: Share your instructions: The github/awesome-copilot repository collects community-contributed instructions files.

      +

      Alex: The practical takeaway is this. Use normative language. Write MUST, MUST NOT, SHOULD, SHOULD NOT, and MAY for rules. LLMs respond well to these terms because they reduce ambiguity -- the same words used in WCAG. Example: Keyboard shortcuts MUST NOT override browser or OS shortcuts. Use lists and checklists. Structured lists provide guardrails that keep Copilot on track. Format accessibility requirements as a checklist so no criterion is overlooked. Specify your versions and standards. This application MUST conform to WCAG 2.2 Level AA is more useful than a general reference to accessibility. Include your design system's component names and flag deprecated components explicitly: DeprecatedButton MUST NOT. Focus on what Copilot doesn't already know. Instructions should add net-new information -- your team's conventions, exceptions, and priorities -- not restate what Copilot was trained on.

      +

      Jamie: Let's pause on Command Palette method. What should a learner take away from it?

      +

      Alex: Start with Command Palette method. There is something to understand, something to try, and something that proves the try worked.

      +

      Alex: First, ctrl+Shift+P → "Chat: New Instructions File". Then, choose Workspace or User Profile scope. After that, enter filename. Finally, add applyTo and/or description frontmatter. The rhythm is simple: orient, act, verify, then continue.

      +

      Jamie: Before we leave Command Palette method, what is the practical point?

      +

      Alex: First, write instructions. Think of it as a rail line: each stop confirms you are still on the right route before the next one.

      +

      Jamie: Let's pause on Quick creation method. What should a learner take away from it?

      +

      Alex: Start with Quick creation method: Type /instructions in the Chat input to open the Configure Instructions menu.

      -

      Jamie: Before we leave Reflect on This Exercise, what is the practical point?

      -

      Alex: The reason Reflect on This Exercise matters is that after completing Steps 1-9, answer. That gives the learner a simple foothold: in Chapter 16, you'll compare these manual reviews with the @pr-review agent's suggested changes. The interface gets friendlier when it stops being a wall of controls and starts being a set of named places.

      -

      Alex: First, announcement clarity: Did the "Added:" and "Removed:" labels from the Accessible Diff Viewer help you follow changes faster than reading + and − prefixes in the browser? Then, navigation pattern: Which tool required less back-and-forth clicking/tabbing to understand each change? After that, when would you use each? In one sentence: describe a type of PR where you'd prefer to use each tool. The rhythm is simple: orient, act, verify, then continue.

      -

      Jamie: Let's pause on Exercise C - Compare and Reflect. What should a learner take away from it?

      -

      Alex: Start with Exercise C - Compare and Reflect: Your Mission: Synthesize what you learned from the manual code reviews (Exercises A & B) and document your findings. The next useful detail is this: What You'll Learn: Which tools work best for different scenarios, and how your manual review skills prepare you to use AI agents effectively.

      -

      Alex: Keep the teaching thread moving. Here is the plain-English version of Step 1: Gather Your Data. Before writing your reflection, collect all the information you gathered. Put another way, write these down (in a text editor, on paper, or mentally) - you'll reference them in Steps 2-4.

      -

      Alex: The practical takeaway is this. Which line number had the heading hierarchy skip? Which line number had the link text issue? How many steps did it take to find each issue? Did you use screen reader commands or visual scanning more?

      +

      Alex: Keep the teaching thread moving. Here is the plain-English version of Model Fallback Array. The first available model in the array is used. Put another way, useful for environments where not all models are licensed.

      +

      Jamie: Let's pause on [Section Header]. What should a learner take away from it?

      +

      Alex: This is where [Section Header] becomes real: [Describe the exact output structure here with placeholders].

      +

      Jamie: Let's pause on Creating Your Own Agent. What should a learner take away from it?

      +

      Alex: Keep the learner anchored in Creating Your Own Agent. Write keyword-rich descriptions. This is the part to say slowly: The description is how other agents decide whether to delegate to yours. A good GitHub workflow is like a well-run meeting: everyone knows the topic, the next action, and who has the floor.

      +

      Alex: First, copy an existing.agent.md from.github/agents/. Then, edit the frontmatter (name, description, tools). After that, write clear step-by-step instructions in the body. Finally, add an Output Format section showing the expected structure. It is like walking a hallway with named doors: read the sign, enter the right room, then confirm where you landed.

      +

      Jamie: Before we leave Creating Your Own Agent, what is the practical point?

      +

      Alex: First, add Constraints and Scope Boundaries sections. Then, save to.github/agents/your-agent-name.agent.md. After that, reload VS Code: Ctrl+Shift+P → "Reload Window". Finally, type @your-agent-name in Copilot Chat. The rhythm is simple: orient, act, verify, then continue.

      -

      Jamie: Let's pause on Step 2: Navigate to the PR and Leave Your Reflection Comment. What should a learner take away from it?

      -

      Alex: Start with Step 2: Navigate to the PR and Leave Your Reflection Comment. There is something to understand, something to try, and something that proves the try worked.

      -

      Alex: The practical takeaway is this. A text editing area with formatting options (Bold, Italic, Link, etc.). A Comment button below the text area.

      -

      Alex: First, go to GitHub in your browser. Then, open the same PR ("Add screen reader tips to the setup guide"). After that, scroll to the Conversation tab. Finally, scroll all the way down to the comment box at the bottom (labeled "Leave a comment" or "Add a comment"). It is a checklist, but a meaningful one: every item creates evidence that the next step is safe.

      -

      Jamie: Before we leave Step 2: Navigate to the PR and Leave Your Reflection Comment, what is the practical point?

      -

      Alex: First, click in the comment box. It is like walking a hallway with named doors: read the sign, enter the right room, then confirm where you landed.

      -

      Alex: Keep the teaching thread moving. Keep the learner anchored in Step 3: Write Your Comparison. Type your response to these three questions. This is the part to say slowly: Be specific - reference exact tools, steps, and what you discovered. A good GitHub workflow is like a well-run meeting: everyone knows the topic, the next action, and who has the floor.

      -

      Jamie: Let's pause on Step 4: Review Your Comment. What should a learner take away from it?

      -

      Alex: Start with Step 4: Review Your Comment. There is something to understand, something to try, and something that proves the try worked.

      -

      Alex: The practical takeaway is this. Is it clear which tool I preferred? Did I explain why with concrete examples? Am I describing the real-world impact accurately? Would someone else reading this understand how I caught the issue?

      -

      Alex: First, before submitting, re-read your comment using your screen reader or by reading aloud. Then, ask yourself. After that, make any corrections needed. Finally, do not submit yet - continue to Step 5. The rhythm is simple: orient, act, verify, then continue.

      +

      Jamie: Let's pause on Learning Cards.agent.md - Complete Format Reference. What should a learner take away from it?

      +

      Alex: Start with Learning Cards.agent.md - Complete Format Reference. There is something to understand, something to try, and something that proves the try worked.

      +

      Alex: The practical takeaway is this. YAML frontmatter is the first block in the file between --- delimiters -- arrow through it line by line to verify name, description, and tools fields; indentation matters. The name field in frontmatter is what you type after @ in Copilot Chat -- if the agent does not appear, check this field matches your invocation and reload VS Code (Ctrl+Shift+P then "Reload Window"). Use Chat Diagnostics (gear icon in Chat header then Diagnostics) to verify your agent loaded successfully -- it lists every agent found, with error details if frontmatter parsing failed. Agent files are small Markdown documents typically under 100 lines -- increase editor font size and use a theme with distinct YAML keyword colors so frontmatter fields stand out. The tools list in frontmatter uses array syntax (["read", "search"]) -- at high zoom, verify commas and quotes are correct since YAML is sensitive to formatting. The body template structure (Constraints, Behavior, Output Format, Scope Boundaries) uses headings -- use VS Code's Outline view (Ctrl+Shift+O) to navigate between sections.

      +

      Alex: Keep the teaching thread moving. Start with Complete Frontmatter Reference. There is something to understand, something to try, and something that proves the try worked.

      +

      Jamie: Let's pause on Tool Priority When Agent Is Also Specified. What should a learner take away from it?

      +

      Alex: Here is the plain-English version of Tool Priority When Agent Is Also Specified. When both the prompt and the referenced agent define tools, VS Code uses this priority.

      +

      Alex: First, tools listed in the prompt file's frontmatter (highest priority). Then, tools from the referenced custom agent. After that, default tools for the selected agent mode. Treat it like a recipe: do not add the next ingredient until the previous one is actually in the bowl.

      -

      Jamie: Let's pause on Step 5: Submit Your Reflection. What should a learner take away from it?

      -

      Alex: Start with Step 5: Submit Your Reflection. There is something to understand, something to try, and something that proves the try worked.

      -

      Alex: The practical takeaway is this. Your comment is now visible on the PR. Other reviewers can see your comparison. You have completed the three-part exercise series. Your comment appears on the PR thread. It includes all three reflections. The PR author and other reviewers can see your thought process.

      -

      Alex: First, locate the Comment button at the bottom right of the comment box. Then, with keyboard: Press Tab until the Comment button is focused, then Enter. After that, with mouse: Click the Comment button. Finally, your comment is submitted and appears on the PR page. Think of it as a rail line: each stop confirms you are still on the right route before the next one.

      -

      Jamie: Let's pause on Step 6: Checkpoint - Validate Your Learning. What should a learner take away from it?

      -

      Alex: Here is the plain-English version of Step 6: Checkpoint - Validate Your Learning. Before moving forward, verify you understand. Put another way, if you can answer all three, you're ready for the next chapter.

      -

      Alex: The practical takeaway is this. Expected answer: Something like "Screen readers let users navigate by heading level (pressing 3 jumps to H3), so skipping a level makes users think content is missing.". Expected answer: e.g., "Browser: finding context in discussions. VS Code: linear reading of changes.". Expected answer: Something like "Open the document in a browser, use screen reader heading navigation, and confirm I can reach all levels (H2, H3, H4).".

      -

      Alex: First, heading Hierarchy: Can you explain in one sentence why a → skip breaks screen reader navigation? Then, tool Strengths: For each tool you used, name one task it made easier. After that, real-World Testing: How would you test the heading issue in the published document (not the PR diff)? Treat it like a recipe: do not add the next ingredient until the previous one is actually in the bowl.

      -

      Alex: Keep the teaching thread moving. This is where Using GitHub Copilot to Understand Code Changes becomes real: reviewing code is about understanding what changed, why it changed, and whether the change is safe and correct. That matters in practice: GitHub Copilot can help you gather and understand information about code changes - especially when diffs are large, complex, or involve unfamiliar frameworks. The workshop is closer to rehearsal than lecture. You hear the move, try the move, and then check what changed.

      +

      Alex: Keep the teaching thread moving. Start with Input Parameters. There is something to understand, something to try, and something that proves the try worked.

      +

      Alex: The practical takeaway is this. parameterName - internal identifier (no spaces). The text after the second: is shown to the user as a placeholder or tooltip. Multiple parameters are supported in one prompt file.

      +

      Jamie: Let's pause on Creating Your Own Slash Command. What should a learner take away from it?

      +

      Alex: Keep the learner anchored in Creating Your Own Slash Command. Both prompts and agent skills appear as / slash commands. This is the part to say slowly: The difference: prompts are single-task Markdown files; skills are folders with bundled scripts and references.

      +

      Alex: First, copy an existing.prompt.md from.github/prompts/. Then, edit frontmatter (name, description, tools). After that, write the task instructions in plain English. Finally, add ${input.} placeholders where the user must provide values. It is like walking a hallway with named doors: read the sign, enter the right room, then confirm where you landed.

      +

      Jamie: Before we leave Creating Your Own Slash Command, what is the practical point?

      +

      Alex: First, save to.github/prompts/your-command.prompt.md. Then, reload VS Code: Ctrl+Shift+P → "Reload Window". After that, type /your-command to invoke it. The rhythm is simple: orient, act, verify, then continue.

      +

      Alex: Keep the teaching thread moving. Start with Learning Cards: Prompts and Slash Commands. There is something to understand, something to try, and something that proves the try worked.

      +

      Alex: The practical takeaway is this. Type / in Copilot Chat to see all available slash commands -- the autocomplete list reads each command name and description aloud.prompt.md files use YAML frontmatter for metadata (name, description, tools) followed by plain Markdown instructions. Use ${input:variableName} placeholders in prompts to create interactive fill-in-the-blank commands that prompt the user at invocation. The slash command picker popup is themed to match your current VS Code theme -- ensure your theme has sufficient contrast for dropdown items.prompt.md files are small Markdown files that are easy to read and edit at high zoom -- typically under 50 lines. The YAML frontmatter block at the top is indentation-sensitive -- use VS Code's indentation guides or a linter to verify structure.

      -

      Jamie: Let's pause on When to Use Copilot During Code Review. What should a learner take away from it?

      -

      Alex: Keep the learner anchored in When to Use Copilot During Code Review. Copilot is most useful for answering these questions.

      -

      Alex: First, "What does this code do?" - you're reading unfamiliar syntax or a framework you don't know well. Then, "Why might this change break something?" - you need to understand dependencies or side effects. After that, "Is this pattern safe?" - you want to verify that the approach follows best practices. Finally, "What would be a better way to write this?" - you're looking for alternatives to suggest. It is like walking a hallway with named doors: read the sign, enter the right room, then confirm where you landed.

      -

      Jamie: Before we leave When to Use Copilot During Code Review, what is the practical point?

      -

      Alex: First, "Does this match the PR's description?" - the change seems to do more (or less) than claimed. The rhythm is simple: orient, act, verify, then continue.

      -

      Jamie: Let's pause on In VS Code with an Open Diff. What should a learner take away from it?

      -

      Alex: Start with In VS Code with an Open Diff. There is something to understand, something to try, and something that proves the try worked.

      -

      Alex: First, open the PR using the GitHub Pull Requests extension (see Part 2). Then, open the diff for any file. After that, select a block of code that confuses you (highlight it). Finally, open Copilot Chat: Ctrl+Shift+I. The rhythm is simple: orient, act, verify, then continue.

      -

      Jamie: Before we leave In VS Code with an Open Diff, what is the practical point?

      -

      Alex: First, Copilot reads the selected code and answers in the chat. Think of it as a rail line: each stop confirms you are still on the right route before the next one.

      -

      Jamie: Let's pause on On GitHub.com (Web Interface). What should a learner take away from it?

      -

      Alex: Start with On GitHub.com (Web Interface): Another option: Use the GitHub Copilot inline suggestions on GitHub.com.

      -

      Alex: The practical takeaway is this. Some GitHub PRs show Copilot insights directly in the diff (as of early 2026). If you see a lightbulb icon, click it to see Copilot's suggestion about that line.

      -

      Alex: First, open the PR's Files Changed tab. Then, focus on a line or section you want to understand better. After that, in VS Code Copilot Chat (not in the browser - Copilot Chat doesn't work directly in browser diffs yet). Finally, copy the confusing code, paste it into chat, and ask Copilot to explain. Think of it as a rail line: each stop confirms you are still on the right route before the next one.

      +

      Jamie: Let's pause on 10. Agent Skills (SKILL.md) - Complete Format Reference. What should a learner take away from it?

      +

      Alex: Start with 10. Agent Skills (SKILL.md) - Complete Format Reference: A Skill is a folder - not a single file. The next useful detail is this: The folder contains SKILL.md plus any scripts, templates, and reference documents the skill needs.

      +

      Jamie: Let's pause on Progressive Loading - How VS Code Loads Skills. What should a learner take away from it?

      +

      Alex: This is where Progressive Loading - How VS Code Loads Skills becomes real: move reference material to references/ folder files.

      +

      Alex: First, discovery ( 100 tokens): Reads name and description to decide if the skill is relevant. Then, instructions (<5000 tokens): Loads the full SKILL.md body when the skill is relevant. After that, resources: Additional files (scripts/, references/) only load when explicitly referenced from SKILL.md. It is a checklist, but a meaningful one: every item creates evidence that the next step is safe.

      -

      Alex: Keep the teaching thread moving. Here is the plain-English version of Copilot Limitations During Review (Critical to Know). This is why manual review is essential: You have context (project history, team decisions, user impact) that Copilot does not. Put another way, use Copilot to understand, then use your judgment to decide. It is like learning a transit route. The names of the stops matter because they tell you whether you are still going the right direction.

      -

      Alex: The practical takeaway is this. See the whole project - it sees only what you show it (the selected diff, not the context of the entire codebase). Verify correctness - it can explain what code does, but not whether it's correct for your specific use case. Understand intent - it reads the code, not the author's mind or the PR description. Catch all risks - it can spot common patterns, but not edge cases unique to your project.

      -

      Jamie: Let's pause on Best Practices. What should a learner take away from it?

      -

      Alex: Start with Best Practices. There is something to understand, something to try, and something that proves the try worked.

      -

      Alex: First, read the diff manually first - you spot the big picture before asking Copilot details. Then, ask Copilot specific questions - not "review this code" but "does this regex handle Unicode?". After that, fact-check Copilot's answers - it can be confidently wrong, especially about frameworks or domains it has less training data. Finally, combine Copilot with manual analysis - ask Copilot to explain, then verify by checking the PR description or looking for related files. It is a checklist, but a meaningful one: every item creates evidence that the next step is safe.

      -

      Jamie: Before we leave Best Practices, what is the practical point?

      -

      Alex: First, use Copilot to draft comments - type Draft a comment about [issue] for this PR and edit Copilot's suggestion to match your tone. It is like walking a hallway with named doors: read the sign, enter the right room, then confirm where you landed.

      -

      Alex: Keep the teaching thread moving. Keep the learner anchored in What Comes Next. Your manual code review skills - identifying heading issues, catching link text problems, understanding screen reader navigation, gathering information with Copilot - are the foundation for understanding automated review. This is the part to say slowly: In Chapter 16 (Accessibility Agents), you'll meet a full team of agents designed to amplify these skills.

      +

      Alex: Keep the teaching thread moving. Keep the learner anchored in 11. Hooks (.json) - Lifecycle Automation. Hooks execute shell commands at specific points in an agent's lifecycle. This is the part to say slowly: They are deterministic - they run regardless of what the agent was prompted to do.

      +

      Jamie: Let's pause on File Locations. What should a learner take away from it?

      +

      Alex: The reason File Locations matters is that hooks from all locations are combined - workspace and user hooks do not override each other.

      +

      Jamie: Let's pause on Configuration Format. What should a learner take away from it?

      +

      Alex: Start with Configuration Format. There is something to understand, something to try, and something that proves the try worked.

      +

      Alex: Treat examples as spoken recipes, not decorations. You may hear something like {; "hooks": {; "PreToolUse": [; {; "type": "command",; "command": ".github/hooks/validate-before-edit.sh",; "timeout": 15; }; ],; "PostToolUse": [; {; "type": "command",; "command": "npx prettier --write",; "windows": "npx.cmd prettier --write",; "timeout". Read the command, understand what it changes, then run it only when the repository state matches the lesson.

      -

      Jamie: Let's pause on Part 4: The Reviewer's Craft. What should a learner take away from it?

      -

      Alex: The reason The Reviewer's Craft matters is that parts 1 through 3 taught you the mechanics -- how to read diffs, leave comments, and use Copilot to understand unfamiliar code. That gives the learner a simple foothold: this part covers something equally important: how to think like a reviewer.

      -

      Alex: Keep the teaching thread moving. Start with What to Look for in a Review: Every PR is different, but most reviews benefit from scanning across these five categories. The next useful detail is this: You do not need to check every category exhaustively on every PR. Think of it like entering a new building: first you find the lobby, then the room, then the door you actually need.

      -

      Jamie: Let's pause on The Three Review Actions. What should a learner take away from it?

      -

      Alex: Here is the plain-English version of The Three Review Actions. When you submit a review on GitHub, you choose one of three actions. Put another way, picking the right one matters because it signals your intent to the author and to anyone else watching the PR.

      -

      Alex: First, did you find a bug, security issue, or broken test? -- Request Changes. Then, does the code do something different from what the description says? -- Request Changes. After that, does everything work, with maybe a few style nits? -- Approve (mention the nits in a comment). Finally, do you have questions or optional suggestions? -- Comment. Treat it like a recipe: do not add the next ingredient until the previous one is actually in the bowl.

      +

      Jamie: Let's pause on PreToolUse permission decisions. What should a learner take away from it?

      +

      Alex: Here is the plain-English version of PreToolUse permission decisions. Permission decisions: "allow" "ask" (prompt user) "deny" (block the tool call).

      +

      Alex: Keep the teaching thread moving. Start with Exit codes. There is something to understand, something to try, and something that proves the try worked.

      +

      Alex: The practical takeaway is this. 0 - success; agent continues. 2 - blocking error; agent stops. Other - non-blocking warning.

      +

      Jamie: Let's pause on Learning Cards: Hooks. What should a learner take away from it?

      +

      Alex: Start with Learning Cards: Hooks. There is something to understand, something to try, and something that proves the try worked.

      +

      Alex: The practical takeaway is this. Hooks are JSON files, not Markdown -- navigate them in the editor with arrow keys; each hook event (e.g., PreToolUse, PostToolUse) is a key in the "hooks" object. Hook output is returned as JSON on stdout -- the "continue" field (true/false) determines whether the agent proceeds; listen for the "stopReason" message if the hook blocks an action. The "permissionDecision" values (allow, ask, deny) control tool access -- ask triggers a confirmation dialog that your screen reader will announce as a standard VS Code dialog. JSON syntax requires careful attention to braces, brackets, and commas -- use VS Code's bracket pair colorization (editor.bracketPairColorization.enabled) and increase font size to verify structure. The hook events table maps each event name to when it fires -- zoom in on the "When It Fires" column to understand the lifecycle timing. Hook errors appear in the agent session output -- look for non-zero exit codes or "continue": false in the output pane.

      -

      Alex: Keep the teaching thread moving. This is where Writing Constructive Feedback becomes real: the way you phrase feedback determines whether the author feels supported or attacked. That matters in practice: Before pointing out problems, acknowledge something the author did well.

      -

      Jamie: Let's pause on The Reviewer's Checklist. What should a learner take away from it?

      -

      Alex: Keep the learner anchored in The Reviewer's Checklist. Run through this list mentally (or copy it into your notes) for every PR you review.

      -

      Alex: The practical takeaway is this. [ ] I read the PR description before reading the code. [ ] The code does what the description says it does. [ ] The change does not include unrelated modifications. [ ] Variable and function names are clear. [ ] I checked for accessibility: labels, headings, keyboard reach, contrast. [ ] I verified no existing behavior is broken by the change.

      -

      Alex: Keep the teaching thread moving. The reason Reviewing as a Learning Tool matters is that reviewing is not just a gate to keep bad code out. That gives the learner a simple foothold: it is one of the fastest ways to grow as a developer. The interface gets friendlier when it stops being a wall of controls and starts being a set of named places.

      +

      Alex: Keep the teaching thread moving. The reason 12. preferences.md - Accessibility Agents Personal Settings matters is that copy.github/agents/preferences.example.md to.github/agents/preferences.md. That gives the learner a simple foothold: the file is in.gitignore - your private settings stay only in your local fork. The interface gets friendlier when it stops being a wall of controls and starts being a set of named places.

      +

      Jamie: Let's pause on Full File Template. What should a learner take away from it?

      +

      Alex: Start with Full File Template. There is something to understand, something to try, and something that proves the try worked.

      +

      Alex: Treat examples as spoken recipes, not decorations. You may hear something like My Accessibility Agents Preferences; My GitHub Username; your-github-username; Repositories I Work On Most; - community-access/accessibility-agents; - your-org/your-repo; Preferred Output Format; screen-reader-optimized; Notification Priority; Accessibility. Read the command, understand what it changes, then run it only when the repository state matches the lesson.

      +

      Jamie: What is the judgment call here?

      +

      Alex: Start with Preferred Output Format Options. There is something to understand, something to try, and something that proves the try worked.

      +

      Alex: Use the comparison to make a decision, not to recite a table. The main contrasts are: "concise" means Bullet points and short summaries, minimal prose. "detailed" means Full context and more explanation in every response. "screen-reader-optimized" means Heading-heavy structure, no tables, explicit empty-state messages.

      -

      Jamie: Let's pause on Learning Cards: The Reviewer's Craft. What should a learner take away from it?

      -

      Alex: Start with Learning Cards: The Reviewer's Craft. There is something to understand, something to try, and something that proves the try worked.

      -

      Alex: The practical takeaway is this. Jump between changed hunks in a diff with Alt+F5 (next change) and Shift+Alt+F5 (previous change) to scan for scope creep efficiently. Use Alt+F2 (Accessible View) on a Copilot-generated review summary to read the full text with arrow keys before posting. When leaving feedback, mention specific line numbers ("Line 42 skips from h2 to h4") so the author can navigate directly with Ctrl+G. The three review actions (Approve, Request Changes, Comment) are shown as clearly labeled radio buttons in the review submission form. Use the reviewer checklist in this section as a mental framework -- copy it into your notes and check items off as you review each PR. The diff view uses green and red backgrounds for added/removed lines; pair with a High Contrast theme if these colors are hard to distinguish.

      -

      Alex: Keep the teaching thread moving. Here is the plain-English version of Day 2 Teaser: The Full Accessibility Agents Review Ecosystem. Chapter 16 shows you how to leverage 50+ specialized agents to make your reviews faster, more consistent, and more thorough - while staying in full control of what you post.

      -

      Jamie: What is the calm recovery move here?

      -

      Alex: This is where The Agents That Help With Code Review becomes real: accessibility Review Agents (when code affects UI/UX).

      -

      Alex: The practical takeaway is this. @pr-review - Generates a full-draft PR review with line-numbered diff maps, risk assessment, before/after snapshots, and suggested inline comments. You edit and post it under your name. @pr-author-checklist - Before you even submit your PR, use this to verify you haven't missed setup steps, accessibility checks, or documentation. @insiders-a11y-tracker - Monitors your PR for accessibility-sensitive changes: WCAG violations, heading hierarchy issues, link text quality, keyboard navigation impacts. @developer-hub - Orchestrates explanations for unfamiliar code, patterns, or frameworks you're reviewing. @python-specialist - If your PR contains Python code, this agent explains patterns, spots accessibility issues, and suggests improvements. @wxpython-specialist - For desktop GUI code, helps verify accessible widget patterns and focus management.

      +

      Jamie: Let's pause on Notification Priority Options. What should a learner take away from it?

      +

      Alex: This is where Notification Priority Options becomes real: the @daily-briefing agent reads this to sort its output sections.

      +

      Alex: Keep the teaching thread moving. Keep the learner anchored in Review Comment Tone Options. The @pr-review and @issue-tracker agents read this when drafting comments. A good GitHub workflow is like a well-run meeting: everyone knows the topic, the next action, and who has the floor.

      +

      Jamie: Let's pause on Accessibility Context Options. What should a learner take away from it?

      +

      Alex: The reason Accessibility Context Options matters is that tells agents which screen reader and browser you use so they can tailor output and recommendations.

      +

      Alex: Treat examples as spoken recipes, not decorations. You may hear something like I use NVDA with Chrome on Windows 11.; I use VoiceOver with Safari on macOS Sonoma.; I use JAWS with Firefox on Windows 10.; I use Narrator with Edge on Windows 11.; I use TalkBack on Android. Read the command, understand what it changes, then run it only when the repository state matches the lesson.

      -

      Jamie: Let's pause on How It Works. What should a learner take away from it?

      -

      Alex: Start with How It Works. There is something to understand, something to try, and something that proves the try worked.

      -

      Alex: First, review manually first (you just did this with Exercises A, B, C). Then, run an agent - @pr-review review PR 14 generates a draft in seconds. After that, edit the agent's draft - you add context, remove noise, correct errors. Finally, post your review - it now has both AI efficiency and your human judgment. It is like walking a hallway with named doors: read the sign, enter the right room, then confirm where you landed.

      -

      Jamie: Before we leave How It Works, what is the practical point?

      -

      Alex: First, the agent tracks impact - @insiders-a11y-tracker monitors whether your accessibility feedback was addressed. The rhythm is simple: orient, act, verify, then continue.

      -

      Jamie: Let's pause on The Principle: Skill First, Agent Second. What should a learner take away from it?

      -

      Alex: The reason The Principle: Skill First, Agent Second matters is that why do this manually before using agents? That gives the learner a simple foothold: manual reviews teach you what to look for.

      -

      Alex: The practical takeaway is this. You understand what the agent is doing (you did it manually). You evaluate the agent's output critically (you know what right looks like). You add judgment the agent lacks (context, intent, team decisions). You verify the agent didn't miss anything important.

      -

      Jamie: Let's pause on A Real Example: The Flow. What should a learner take away from it?

      -

      Alex: Start with A Real Example: The Flow: Manual Review (your work in part 1-2). The next useful detail is this: Agent-Assisted Review (what you'll do in Chapter 19).

      -

      Alex: The practical takeaway is this. Read diff, identify heading hierarchy skip. Write comment explaining why it matters. Submit your verdict.

      -

      Alex: First, run: @pr-review review PR 14. Then, agent generates a draft review covering the heading skip, link text, and 5 other issues. After that, you read the draft and notice: "the agent's explanation of the heading skip is good, but it missed that the link text on line 23 is still vague. Let me add that.". Finally, you post the agent's review + your additions. Think of it as a rail line: each stop confirms you are still on the right route before the next one.

      -

      Jamie: Before we leave A Real Example: The Flow, what is the practical point?

      -

      Alex: First, next time you review a similar PR, the agent works faster because it learned from your feedback. Treat it like a recipe: do not add the next ingredient until the previous one is actually in the bowl.

      +

      Jamie: Let's pause on View All Loaded Customizations. What should a learner take away from it?

      +

      Alex: Start with View All Loaded Customizations: To see every instruction file, agent, prompt, and skill currently loaded and any errors. The next useful detail is this: This shows: which files were found, which were loaded, which have errors, and from which scope (user vs workspace vs organization).

      +

      Alex: First, in Copilot Chat, select the gear icon (Configure Chat) → Diagnostics. Then, or right-click in the Chat view → Diagnostics. Think of it as a rail line: each stop confirms you are still on the right route before the next one.

      +

      Jamie: Let's pause on Agent not found when typing @agent-name. What should a learner take away from it?

      +

      Alex: Start with Agent not found when typing @agent-name. There is something to understand, something to try, and something that proves the try worked.

      +

      Alex: First, verify.github/agents/[name].agent.md exists in your open workspace folder. Then, check that the YAML frontmatter has no syntax errors (missing quotes, wrong indentation). After that, ctrl+Shift+P → "Reload Window". Finally, check that the name field in the frontmatter matches what you are typing. Treat it like a recipe: do not add the next ingredient until the previous one is actually in the bowl.

      +

      Jamie: Let's pause on Instructions not being applied. What should a learner take away from it?

      +

      Alex: Start with Instructions not being applied. There is something to understand, something to try, and something that proves the try worked.

      +

      Alex: First, for.github/copilot-instructions.md: file must be at workspace root in the.github/ folder. Then, for.instructions.md: check that applyTo glob matches the file you are editing, and that chat.includeApplyingInstructions is true in VS Code settings. After that, for AGENTS.md: check that chat.useAgentsMdFile is true. Finally, use Diagnostics view (above) to verify the file was found and loaded. It is a checklist, but a meaningful one: every item creates evidence that the next step is safe.

      +
      +

      Jamie: Let's pause on Instructions file in wrong place. What should a learner take away from it?

      +

      Alex: Start with Instructions file in wrong place. There is something to understand, something to try, and something that proves the try worked.

      +

      Alex: The practical takeaway is this. Add custom locations: chat.instructionsFilesLocations setting accepts an array of additional folder paths.

      +

      Jamie: Let's pause on Slash command not appearing. What should a learner take away from it?

      +

      Alex: Start with Slash command not appearing. There is something to understand, something to try, and something that proves the try worked.

      +

      Alex: First, verify.github/prompts/[name].prompt.md exists. Then, ctrl+Shift+P → "Reload Window". After that, file must use.prompt.md extension (not just.md). The rhythm is simple: orient, act, verify, then continue.

      +

      Jamie: Let's pause on 14. Further Reading. What should a learner take away from it?

      +

      Alex: Start with 14. Further Reading: For the broader ecosystem - the community plugin marketplace, MCP server integrations, and running agents in the cloud via GitHub Actions - see Appendix K: GitHub Copilot and Agentic Reference.

      +
      +

      Alex: Keep the teaching thread moving. Here is the plain-English version of Official accessibility.github.com Guides. Next: Appendix M: Accessibility Standards Back: Appendix K: Copilot Reference Teaching chapter: Chapter 19: Accessibility Agents. It is like learning a transit route. The names of the stops matter because they tell you whether you are still going the right direction.

      Jamie: What is the final checkpoint?

      Alex: You should be able to point to the evidence, explain the action, and describe what you would do next if this were a real open source project. If you can teach the move back, you have learned it.

      @@ -17039,968 +16747,834 @@

      Transcript

      -

      Challenge 12: Review Like a Pro

      -

      Reviewing a classmate PR, leaving specific feedback, and owning review tone.

      +

      50. Episode 47: Fork and Contribute

      +

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

      +

      Based on: Chapter 18: Fork and Contribute

      +

      Audio and transcript are being regenerated for this episode.

      -Read Transcript - Challenge 12: Review Like a Pro +Read Transcript - Episode 47: Fork and Contribute

      Transcript

      -

      Alex: Welcome to Challenge Coach: Review Like a Pro. I am Alex. Before you do the task, we are going to make the skill feel concrete enough to practice.

      -

      Jamie: And I am Jamie. I will keep asking what the learner should do, what evidence counts, and how to recover if the page does something unexpected.

      +

      Alex: Welcome to episode 47 of Git Going with GitHub: Fork and Contribute. I am Alex, and today we are teaching this topic as a conversation you can carry into the workshop, not as a page you have to memorize.

      +

      Jamie: And I am Jamie. I will keep pulling the lesson back to real learners, real repositories, and the evidence that proves the work happened.

      -

      Alex: The skill focus is Reviewing a classmate PR, leaving specific feedback, and owning review tone. This is rehearsal for real contribution, so the evidence matters because it proves the move happened.

      -

      Jamie: So the challenge has to leave the learner with both confidence and a trail of evidence.

      -

      Alex: Exactly. Evidence is not busywork. It is how a learner, a facilitator, and a future maintainer can understand what changed and why.

      +

      Alex: The lesson focus is The complete fork-based open source contribution workflow from fork to upstream pull request. We will treat every step as a teachable decision, because that is what makes the skill portable.

      +

      Jamie: So we should explain the why clearly enough that the steps make sense when the learner meets them later.

      +

      Alex: That is it. If a listener only has audio right now, they should still get the complete concept and know what evidence would prove success.

      -

      Jamie: What makes this practice feel low-stakes but still real?

      -

      Alex: Start with Challenge 12: Review Like a Pro: What you will do: Give the peer-simulation PR a thorough code review with inline comments, a suggestion, and a verdict. The next useful detail is this: If your facilitator gave you access to a real buddy's PR, you may review that PR instead.

      -

      Alex: A solid pull request habit is to separate three questions: what changed, why it changed, and what still needs review. That keeps the conversation useful instead of noisy.

      +

      Jamie: Okay, set the room for us. What are we walking into?

      +

      Alex: Start with 1. What Is a Fork?: See also: Chapter 08: Open Source Culture for the cultural context of forking and contributing. The next useful detail is this: A fork is your personal copy of someone else's repository on GitHub.

      Jamie: How would you walk the room through that step by step?

      -

      Alex: Start with Instructions. There is something to understand, something to try, and something that proves the try worked.

      -

      Alex: The practical anchors are these. One specific observation about something they did well. One constructive suggestion for improvement.

      -

      Alex: First, open the Peer Simulation: Improve contribution guidance PR. If you have real buddy access, you may open your buddy's Day 2 PR instead. Then, go to the Files changed tab. After that, review the changes and leave at least two inline comments. Finally, use the Suggest changes feature for at least one of your comments (select the +/- icon in the comment toolbar to create a code suggestion block). Treat it like a recipe: do not add the next ingredient until the previous one is actually in the bowl.

      -

      Jamie: What does the learner do first, second, and then after that?

      -

      Alex: First, submit your review with a verdict: Approve, Request changes, or Comment. It is a checklist, but a meaningful one: every item creates evidence that the next step is safe.

      +

      Alex: Here is the plain-English version of Why forks exist. Most open source projects do not give every contributor write access to the main repository. Put another way, this way anyone can contribute without the maintainers giving out write access. It is like learning a transit route. The names of the stops matter because they tell you whether you are still going the right direction.

      +

      Alex: First, you fork the project (creates your copy). Then, you make changes on your copy. After that, you open a pull request asking the maintainers to merge your changes. Treat it like a recipe: do not add the next ingredient until the previous one is actually in the bowl.

      Jamie: What is the one idea that makes the next few steps less mysterious?

      -

      Alex: Start with Review checklist. There is something to understand, something to try, and something that proves the try worked.

      -

      Alex: That shows up in the workshop in a few specific ways. [ ] Does the change do what the PR description says? [ ] Is the commit message clear? [ ] Are there any typos or formatting issues? [ ] Would someone reading this file for the first time understand the changes? [ ] Is the content accessible (clear language, proper Markdown formatting)?

      +

      Alex: This is where 2. Fork vs Clone vs Branch becomes real: these three concepts are related but different. That matters in practice: Understanding the distinctions prevents confusion.

      +

      Alex: A solid Git habit is to know which branch you are on, what changed, and what confirmation you expect before you run the next command.

      -

      Alex: Now bring the learner back to the room. Start with The three verdicts. There is something to understand, something to try, and something that proves the try worked.

      +

      Jamie: Turn that into a path someone can follow.

      +

      Alex: Keep the learner anchored in How they work together. In the fork workflow, you use all three. This is the part to say slowly: The text diagram above shows three boxes arranged left to right.

      +

      Alex: First, fork the upstream repository to create your copy on GitHub. Then, clone your fork to your computer. After that, create a branch on your local clone for your specific change. Finally, push the branch to your fork and open a PR to the upstream. It is like walking a hallway with named doors: read the sign, enter the right room, then confirm where you landed.

      Jamie: What would you say to someone who is already bracing for this to be too much?

      -

      Alex: The reason Peer simulation check matters is that read any review comments on your PR. That gives the learner a simple foothold: if you do not have real buddy access, reply to a comment on the peer-simulation PR with one thing you learned.

      +

      Alex: Start with Learning Cards: Fork vs Clone vs Branch. There is something to understand, something to try, and something that proves the try worked.

      +

      Alex: The parts worth keeping in working memory are these. 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. 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.

      +

      Jamie: Give me the sequence, because order matters here.

      +

      Alex: Start with Tool Cards: Fork and Clone a Repository: For this workshop, you will fork the Community-Access/accessibility-agents repository. Think of it like entering a new building: first you find the lobby, then the room, then the door you actually need.

      +

      Alex: First, click Fork on the repository page Create fork. Then, clone: click the green Code button copy URL paste into your local tool. After that, fork on github.com first (browser required for forking). Finally, ctrl+Shift+P Git: Clone paste your fork's URL. Think of it as a rail line: each stop confirms you are still on the right route before the next one.

      +

      Jamie: What does the learner do first, second, and then after that?

      +

      Alex: First, fork on github.com first. Then, file Clone Repository select your fork from the GitHub.com tab. Treat it like a recipe: do not add the next ingredient until the previous one is actually in the bowl.

      +

      Alex: Treat examples as spoken recipes, not decorations. You may hear something like gh repo fork Community-Access/accessibility-agents --clone; cd accessibility-agents. Read the command, understand what it changes, then run it only when the repository state matches the lesson.

      Alex: The useful habit is simple: orient first, act second, verify third. That pause before acting is part of the work.

      -

      Alex: That matters because of the next idea. Start with Inline comment (on a specific line): Line 18 of docs/welcome.md: This heading says " getting started" but the other headings in the file use title case (" What You Will Learn"). The next useful detail is this: Consider changing it to " Getting Started" for consistency. Think of it like entering a new building: first you find the lobby, then the room, then the door you actually need.

      -

      Jamie: Okay, set the room for us. What are we walking into?

      -

      Alex: Here is the plain-English version of Suggestion (using GitHub's suggestion feature). Using the suggestion feature lets the PR author accept the change with one click, which creates a commit automatically.

      -

      Alex: This is where the talk moves from concept to action. This is where Review verdict becomes real: changes requested Good work overall. That matters in practice: The content additions are helpful and well-written.

      +

      Jamie: What is the ordered workflow?

      +

      Alex: Here is the plain-English version of On GitHub.com. The original repository at Community-Access/accessibility-agents is untouched.

      +

      Alex: Here is what that changes in practice. 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.". Owner: your username. Repository name: accessibility-agents. Copy the main branch only: checked (leave this checked).

      +

      Alex: First, go to github.com/Community-Access/accessibility-agents. Then, find the Fork button in the upper-right area of the page. After that, GitHub shows a "Create a new fork" page. The defaults are correct. Finally, activate Create fork. Treat it like a recipe: do not add the next ingredient until the previous one is actually in the bowl.

      +

      Jamie: Let's pause on On GitHub.com. What should a learner take away from it?

      +

      Alex: First, GitHub redirects you to your fork: github.com/your-username/accessibility-agents. It is a checklist, but a meaningful one: every item creates evidence that the next step is safe.

      +

      Jamie: What should happen before anyone copies and runs it?

      +

      Alex: This is where Using GitHub CLI becomes real: this creates the fork on GitHub without cloning it locally.

      +

      Alex: Treat examples as spoken recipes, not decorations. You may hear something like gh repo fork Community-Access/accessibility-agents --clone=false. Read the command, understand what it changes, then run it only when the repository state matches the lesson.

      Jamie: Where do you want a learner to place their attention here?

      -

      Alex: Start with Types of review comments. There is something to understand, something to try, and something that proves the try worked.

      -

      Alex: These are the details that keep the idea from floating away. Praise: "This section reads really clearly" -- positive feedback encourages good practices. Question: "What happens if the user does not have a GitHub account yet?" -- surfaces assumptions. Suggestion: Use the suggestion block to propose specific text changes. Required change: "The YAML frontmatter is missing the description field, which is required".

      +

      Alex: Keep the learner anchored in 4. Step 2: Clone Your Fork Locally. Now download your fork to your computer so you can work on it.

      -

      Alex: Before the learner moves on. The reason What matters matters is that the learning objective is providing constructive feedback on someone else's work. That gives the learner a simple foothold: if you left at least one specific, helpful comment on a buddy's PR, you completed this challenge. The interface gets friendlier when it stops being a wall of controls and starts being a set of named places.

      +

      Jamie: Let's pause on Using VS Code. What should a learner take away from it?

      +

      Alex: Start with Using VS Code. There is something to understand, something to try, and something that proves the try worked.

      +

      Alex: First, open VS Code. Then, open the command palette: Ctrl+Shift+P (or Cmd+Shift+P). After that, type "Git: Clone" and press Enter. Finally, paste your fork URL: https://github.com/your-username/accessibility-agents.git (replace your-username with your GitHub username). The rhythm is simple: orient, act, verify, then continue.

      +

      Jamie: Before we leave Using VS Code, what is the practical point?

      +

      Alex: First, choose a folder (for example, Documents) and confirm. Then, when the clone finishes, VS Code offers to open the repository. Accept. Think of it as a rail line: each stop confirms you are still on the right route before the next one.

      +

      Jamie: What is the safe way to learn from that example?

      +

      Alex: Start with Using the terminal. There is something to understand, something to try, and something that proves the try worked.

      +

      Alex: Treat examples as spoken recipes, not decorations. You may hear something like git clone https://github.com/your-username/accessibility-agents.git; cd accessibility-agents. Read the command, understand what it changes, then run it only when the repository state matches the lesson.

      +

      Jamie: Let's pause on Using GitHub Desktop. What should a learner take away from it?

      +

      Alex: Start with Using GitHub Desktop. There is something to understand, something to try, and something that proves the try worked.

      +

      Alex: First, open GitHub Desktop. Then, go to File, then Clone repository. After that, select the GitHub.com tab and find your-username/accessibility-agents. Finally, choose a local path and click Clone. Treat it like a recipe: do not add the next ingredient until the previous one is actually in the bowl.

      +
      +

      Jamie: What should they understand before typing anything?

      +

      Alex: This is where Using GitHub CLI becomes real: after cloning, your local repository has one remote called origin that points to your fork.

      +

      Alex: Treat examples as spoken recipes, not decorations. You may hear something like gh repo clone your-username/accessibility-agents; cd accessibility-agents. Read the command, understand what it changes, then run it only when the repository state matches the lesson.

      +

      Alex: That connects to another useful point. Start with Learning Cards: Cloning Your Fork. There is something to understand, something to try, and something that proves the try worked.

      +

      Alex: For a learner, the useful signals are these. 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. 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.

      Jamie: Give me the version that sounds like an instructor, not a manual.

      -

      Alex: Start with The GitHub Pull Requests Extension: See also: Appendix G: VS Code Reference for the complete list of GitHub Pull Requests extension keyboard shortcuts.

      -

      Alex: Hold that next to this. Here is the plain-English version of 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,. Put another way, prerequisites: Working with Pull Requests, Git & Source Control in VS Code Mac keyboard shortcuts: Throughout this chapter, all Ctrl+ shortcuts use Cmd+ on Mac, and Alt+ shortcuts use Option+ on Mac.

      +

      Alex: The reason 5. Step 3: Add the Upstream Remote matters is that see also: Appendix E: Advanced Git for advanced remote and upstream management. That gives the learner a simple foothold: your clone knows about your fork (origin).

      -

      Jamie: What should feel predictable before the first live session starts?

      -

      Alex: This is where Workshop Recommendation (Chapter 15, Part 1) becomes real: chapter 15, Part 1 introduces the GitHub Pull Requests extension for managing PRs directly from VS Code.

      -

      Alex: For a learner, the useful signals are these. There are 2 guided challenges. Automation check: none (extension installation and review state are account-local). The evidence is issue comment with confirmation of actions completed. The pattern is install, check out, review, comment.

      -

      Jamie: Turn that into a path someone can follow.

      -

      Alex: Start with Chapter 15, Part 1 Practice Set. There is something to understand, something to try, and something that proves the try worked.

      -

      Alex: First, install the GitHub Pull Requests extension - add the extension to VS Code and sign in with your GitHub account. Then, check out a PR and post a review comment - download a PR branch locally, read the diff, and post one constructive review comment. It is like walking a hallway with named doors: read the sign, enter the right room, then confirm where you landed.

      -

      Jamie: What is the ordered workflow?

      -

      Alex: The reason Practice 15.1 Step-by-Step: Install the Extension matters is that install the GitHub Pull Requests and Issues extension and authenticate with your GitHub account. That gives the learner a simple foothold: VS Code desktop with your Learning Room repository open.

      -

      Alex: First, open the Extensions sidebar: Ctrl+Shift+X (Mac: Cmd+Shift+X). Then, your screen reader announces "Extensions: Marketplace." The search box has focus. After that, type GitHub Pull Requests in the search box and press Enter. Finally, navigate down the results list. Select GitHub Pull Requests (publisher: GitHub). The rhythm is simple: orient, act, verify, then continue.

      -

      Jamie: Give me the sequence, because order matters here.

      -

      Alex: First, activate the Install button. VS Code installs the extension and may show a notification. Then, after installation, VS Code prompts you to sign in. Activate Sign in to GitHub. After that, a browser window opens for GitHub OAuth. Approve the authorization and return to VS Code. Finally, verify: open the Explorer sidebar (Ctrl+Shift+E). You should now see a GitHub section in the sidebar showing Pull Requests and Issues. Think of it as a rail line: each stop confirms you are still on the right route before the next one.

      +

      Alex: Here is the practical turn. Start with Why this matters: Without the upstream remote, you cannot.

      +

      Alex: On the ground, that means a few things. 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.

      +

      Jamie: How do you keep commands from becoming magic words?

      +

      Alex: Start with Add the upstream remote. There is something to understand, something to try, and something that proves the try worked.

      +

      Alex: Treat examples as spoken recipes, not decorations. You may hear something like git remote add upstream https://github.com/Community-Access/accessibility-agents.git. Read the command, understand what it changes, then run it only when the repository state matches the lesson.

      +

      Jamie: Let's pause on Verify your remotes. What should a learner take away from it?

      +

      Alex: This is where Verify your remotes becomes real: two remotes: origin (your fork) and upstream (the original). That matters in practice: In VS Code: You can also add the remote using the command palette. The workshop is closer to rehearsal than lecture. You hear the move, try the move, and then check what changed.

      +

      Alex: Treat examples as spoken recipes, not decorations. You may hear something like git remote -v. Read the command, understand what it changes, then run it only when the repository state matches the lesson.

      -

      Jamie: Let's pause on Practice 15.2 Step-by-Step: Check Out a PR and Post a Comment. What should a learner take away from it?

      -

      Alex: Start with Practice 15.2 Step-by-Step: Check Out a PR and Post a Comment: Check out someone else's PR branch locally, read the diff in VS Code, and post one constructive review comment. The next useful detail is this: VS Code with the GitHub Pull Requests extension installed.

      -

      Alex: First, open the Command Palette: Ctrl+Shift+P (Mac: Cmd+Shift+P). Then, type GitHub Pull Requests: Focus on Pull Requests View and select it. The Pull Requests panel opens. After that, navigate the list of open PRs. Find one that is not yours (a classmate's PR from Chapter 6, 7, or 14). Finally, 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. Think of it as a rail line: each stop confirms you are still on the right route before the next one.

      -

      Jamie: Before we leave Practice 15.2 Step-by-Step: Check Out a PR and Post a Comment, what is the practical point?

      -

      Alex: First, open the Command Palette again and run GitHub Pull Requests: Open Changed Files. This shows the list of files the PR changed. Then, open one changed file. VS Code opens the Diff Editor showing old content on the left and new content on the right. After that, 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). Finally, find one specific thing to comment on: a typo, an unclear sentence, a missing step, or something the author did well. Treat it like a recipe: do not add the next ingredient until the previous one is actually in the bowl.

      -

      Jamie: How do these exercises create confidence instead of pressure?

      -

      Alex: Here is the plain-English version of Completing Chapter 15, Part 1: Submit Your Evidence. Open your assigned setup or review practice issue and post a completion comment. Put another way, close your Chapter 12 challenge issues when done.

      -

      Alex: Keep the thread going. Start with Expected Outcomes. There is something to understand, something to try, and something that proves the try worked.

      -

      Alex: The room should hear these as checkpoints. 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.

      +

      Jamie: If I am listening before the workshop starts, what should settle in my mind first?

      +

      Alex: Keep the learner anchored in 6. Step 4: Create a Feature Branch. Never work directly on the main branch of your fork. This is the part to say slowly: Always create a feature branch for each change.

      +

      Jamie: Let's pause on Create and switch to a new branch. What should a learner take away from it?

      +

      Alex: The reason Create and switch to a new branch matters is that the branch name agents/your-username-my-agent follows the workshop convention for Day 2 capstone branches. That gives the learner a simple foothold: replace your-username with your GitHub username and my-agent with a short name for your agent.

      +

      Alex: Treat examples as spoken recipes, not decorations. You may hear something like git checkout -b agents/your-username-my-agent. Read the command, understand what it changes, then run it only when the repository state matches the lesson.

      +

      Jamie: Let's pause on In VS Code. What should a learner take away from it?

      +

      Alex: Start with In VS Code. There is something to understand, something to try, and something that proves the try worked.

      +

      Alex: First, click the branch name in the bottom-left status bar (or press Ctrl+Shift+P and type "Git: Create Branch"). Then, type the branch name: agents/your-username-my-agent. After that, press Enter. VS Code creates the branch and switches to it. Think of it as a rail line: each stop confirms you are still on the right route before the next one.

      -

      Jamie: Let's pause on If You Get Stuck. What should a learner take away from it?

      -

      Alex: Keep the learner anchored in If You Get Stuck. Continue learning: The GitHub Skills course Review Pull Requests practices approving, requesting changes, and using suggestions in an interactive format. This is the part to say slowly: See Appendix Z for the full catalog.

      -

      Alex: First, extension does not install? Reload VS Code: Ctrl+Shift+P, then run Developer: Reload Window. Then, oAuth sign-in fails? Verify your GitHub account is active in the browser first, close VS Code, reopen, and retry. After that, pR list is empty? Switch to "All Open" view in the GitHub Pull Requests panel. Finally, checkout fails? Confirm you have write access to the repository. If not, use the read-only GitHub.com fallback. It is like walking a hallway with named doors: read the sign, enter the right room, then confirm where you landed.

      -

      Jamie: Before we leave If You Get Stuck, what is the practical point?

      -

      Alex: First, diff Editor is hard to navigate? Press F7 for the Accessible Diff Viewer mode, which is purpose-built for screen readers. Then, cannot find the Add Comment command? Use Command Palette and search for GitHub Pull Requests: Add Comment. After that, ask facilitator to help verify the GitHub PR panel and model one review comment. Finally, finished but not sure you did it right? Compare your work against the Challenge 11 reference solution. The rhythm is simple: orient, act, verify, then continue.

      -

      Alex: Another way to ground it. The reason Learning Moment matters is that reviewing others' work refines your own standards and builds community trust. That gives the learner a simple foothold: the comment you just wrote helps another student learn - and you learn by articulating what makes documentation clear.

      -

      Jamie: Let's pause on Learning Pattern Used in This Chapter. What should a learner take away from it?

      -

      Alex: Start with Learning Pattern Used in This Chapter. There is something to understand, something to try, and something that proves the try worked.

      -

      Alex: First, install and configure the tool before starting the task. Then, practice on someone else's work first (reviewing is safer than authoring). After that, use accessibility tools (F7 Accessible Diff Viewer) to navigate efficiently. Finally, write specific, constructive feedback (not just "looks good"). Think of it as a rail line: each stop confirms you are still on the right route before the next one.

      +

      Jamie: Let's pause on In GitHub Desktop. What should a learner take away from it?

      +

      Alex: Start with In GitHub Desktop. There is something to understand, something to try, and something that proves the try worked.

      +

      Alex: First, click the Current Branch dropdown. Then, click New Branch. After that, type the branch name and click Create Branch. Treat it like a recipe: do not add the next ingredient until the previous one is actually in the bowl.

      +

      Jamie: Let's pause on Verify you are on the new branch. What should a learner take away from it?

      +

      Alex: This is where Verify you are on the new branch becomes real: the current branch has an asterisk ( ) next to it.

      +

      Alex: Treat examples as spoken recipes, not decorations. You may hear something like git branch. Read the command, understand what it changes, then run it only when the repository state matches the lesson.

      +

      Alex: The next layer is this. Keep the learner anchored in 7. Step 5: Make Your Changes. Now you are on your feature branch and ready to work. This is the part to say slowly: For the capstone, you will create an agent file.

      -

      Alex: This is the part worth saying out loud. Here is the plain-English version of 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. It is like learning a transit route. The names of the stops matter because they tell you whether you are still going the right direction.

      -

      Jamie: Let's pause on Method 1: Extensions Sidebar. What should a learner take away from it?

      -

      Alex: Start with Method 1: Extensions Sidebar. There is something to understand, something to try, and something that proves the try worked.

      -

      Alex: First, open Extensions sidebar: Ctrl+Shift+X (Mac: Cmd+Shift+X). Then, type "GitHub Pull Requests" in the search box. After that, find "GitHub Pull Requests and Issues" (publisher: GitHub). Finally, navigate to the extension in the results list. It is a checklist, but a meaningful one: every item creates evidence that the next step is safe.

      -

      Jamie: Before we leave Method 1: Extensions Sidebar, what is the practical point?

      -

      Alex: First, press Enter to open the extension detail page. Then, tab to "Install" button → press Enter. It is like walking a hallway with named doors: read the sign, enter the right room, then confirm where you landed.

      -

      Jamie: Let's pause on Method 2: Command Palette. What should a learner take away from it?

      -

      Alex: Keep the learner anchored in Method 2: Command Palette. The Extensions sidebar is a tree view. This is the part to say slowly: Use Up/Down Arrow to navigate, Enter to open an extension's detail page.

      -

      Alex: First, ctrl+Shift+P. Then, type "install extensions". After that, select "Extensions: Install Extensions". Finally, search for "GitHub Pull Requests". It is like walking a hallway with named doors: read the sign, enter the right room, then confirm where you landed.

      -

      Jamie: Before we leave Method 2: Command Palette, what is the practical point?

      -

      Alex: First, install "GitHub Pull Requests and Issues". The rhythm is simple: orient, act, verify, then continue.

      +

      Jamie: Let's pause on General principles for contributing. What should a learner take away from it?

      +

      Alex: Start with General principles for contributing. There is something to understand, something to try, and something that proves the try worked.

      +

      Alex: The room should hear these as checkpoints. 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.

      +

      Alex: A solid pull request habit is to separate three questions: what changed, why it changed, and what still needs review. That keeps the conversation useful instead of noisy.

      +

      Jamie: Let's pause on Stage and commit your changes. What should a learner take away from it?

      +

      Alex: Start with Stage and commit your changes. There is something to understand, something to try, and something that proves the try worked.

      +

      Alex: Treat examples as spoken recipes, not decorations. You may hear something like git add your-file.md; git commit -m "Add my-agent accessibility agent". git add.; git commit -m "Add my-agent accessibility agent". Read the command, understand what it changes, then run it only when the repository state matches the lesson.

      +

      Jamie: Before we leave In VS Code, what is the practical point?

      +

      Alex: These are the details that keep the idea from floating away. 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.

      +

      Alex: First, open the Source Control panel: Ctrl+Shift+G (or Cmd+Shift+G). Then, changed files appear under "Changes." Click the + icon next to each file to stage it, or click + on the "Changes" header to stage all. After that, type your commit message in the text field at the top. Finally, press Ctrl+Enter (or Cmd+Enter) to commit. Treat it like a recipe: do not add the next ingredient until the previous one is actually in the bowl.

      -

      Jamie: Let's pause on Signing In to GitHub. What should a learner take away from it?

      -

      Alex: The reason Signing In to GitHub matters is that after installation, VS Code prompts you to sign in.

      -

      Alex: First, a notification appears: "Sign in to GitHub to use Pull Requests". Then, navigate to the notification (Alt+N / Mac: Option+N, or status bar navigation). After that, select "Sign in". Finally, VS Code opens your browser for GitHub OAuth authentication. The rhythm is simple: orient, act, verify, then continue.

      -

      Jamie: Before we leave Signing In to GitHub, what is the practical point?

      -

      Alex: First, authorize VS Code in the browser. Then, return to VS Code - you're now signed in. Think of it as a rail line: each stop confirms you are still on the right route before the next one.

      -

      Alex: Here is the practical turn. Start with Verify sign-in. There is something to understand, something to try, and something that proves the try worked.

      -

      Alex: On the ground, that means a few things. 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.

      -

      Jamie: If I am listening before the workshop starts, what should settle in my mind first?

      -

      Alex: Start with What the Extension Adds. There is something to understand, something to try, and something that proves the try worked.

      -

      Alex: Here is what that changes in practice. 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.

      +

      Alex: That matters because of the next idea. This is where Multiple commits are fine becomes real: you do not need to make all your changes in a single commit. That matters in practice: In fact, smaller commits are better because they are easier to review and easier to revert if something goes wrong.

      +

      Jamie: Let's pause on 8. Step 6: Push to Your Fork. What should a learner take away from it?

      +

      Alex: Keep the learner anchored in 8. Step 6: Push to Your Fork. Now push them to your fork on GitHub.

      +

      Jamie: Let's pause on First push (new branch). What should a learner take away from it?

      +

      Alex: The reason First push (new branch) matters is that the -u flag sets up tracking so future pushes from this branch go to the right place automatically. The interface gets friendlier when it stops being a wall of controls and starts being a set of named places.

      +

      Alex: Treat examples as spoken recipes, not decorations. You may hear something like git push -u origin agents/your-username-my-agent. Read the command, understand what it changes, then run it only when the repository state matches the lesson.

      -

      Alex: The next layer is this. Start with Learning Cards: Installing the PR Extension. There is something to understand, something to try, and something that proves the try worked.

      -

      Alex: That becomes easier when you listen for these cues. 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". 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.

      -

      Jamie: Let's pause on Method 1: Activity Bar. What should a learner take away from it?

      -

      Alex: Keep the learner anchored in Method 1: Activity Bar. Click the GitHub logo icon in the Activity Bar (the vertical strip of icons on the far left). This is the part to say slowly: The GitHub Pull Requests panel opens.

      -

      Alex: A few details make that real. "Pull Requests". "Issues".

      -

      Alex: First, the Activity Bar is not always reachable by Tab from the editor. Then, use Ctrl+Shift+P (Mac: Cmd+Shift+P) → type "GitHub Pull Requests: View Pull Request" or "Focus on Pull Requests View" → press Enter. After that, alternatively press Ctrl+Shift+G (Mac: Cmd+Shift+G) to open Source Control, then Tab until you reach the Activity Bar icon strip. Finally, navigate to the repository on GitHub.com. It is like walking a hallway with named doors: read the sign, enter the right room, then confirm where you landed.

      -

      Jamie: Before we leave Method 1: Activity Bar, what is the practical point?

      -

      Alex: First, click the Pull requests tab. Then, click any PR title to view its conversation, commits, and changed files. After that, use the Files changed tab to review diffs. The rhythm is simple: orient, act, verify, then continue.

      -

      Alex: Treat examples as spoken recipes, not decorations. You may hear something like 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". Read the command, understand what it changes, then run it only when the repository state matches the lesson.

      -

      Jamie: Let's pause on Method 2: Explorer Section. What should a learner take away from it?

      -

      Alex: Start with Method 2: Explorer Section. There is something to understand, something to try, and something that proves the try worked.

      -

      Alex: First, open Explorer: Ctrl+Shift+E (Mac: Cmd+Shift+E). Then, navigate with Arrow keys to find the "GitHub Pull Requests" section. After that, expand it with Right Arrow. The rhythm is simple: orient, act, verify, then continue.

      +

      Jamie: Let's pause on Subsequent pushes. What should a learner take away from it?

      +

      Alex: Start with Subsequent pushes. There is something to understand, something to try, and something that proves the try worked.

      +

      Alex: Treat examples as spoken recipes, not decorations. You may hear something like git push. Read the command, understand what it changes, then run it only when the repository state matches the lesson.

      +

      Alex: Before the learner moves on. Here is the plain-English version of In VS Code. After committing, the Source Control panel shows a Sync Changes button (or a cloud icon with an up arrow). Put another way, alternatively, use the command palette: Ctrl+Shift+P, type "Git: Push.".

      +

      Jamie: What stays the same when the tool changes?

      +

      Alex: This is where In GitHub Desktop becomes real: after committing, click the Push origin button in the top bar.

      -

      Jamie: Let's pause on Description. What should a learner take away from it?

      -

      Alex: Start with Description: The GitHub Pull Requests panel has two top-level sections. The next useful detail is this: "My Pull Requests" contains four filters: Assigned to Me, Created by Me, Waiting for my Review, and All Open.

      -

      Alex: That connects to another useful point. Here is the plain-English version of Screen reader announcement example. "Pull Request 42: Add Timeline Guide, opened by jeffb, 2 days ago, 3 files changed".

      -

      Alex: A solid navigation habit is to prove where you are before activating controls. Headings, landmarks, and the address bar are not trivia; they are your map.

      -

      Jamie: Let's pause on By status. What should a learner take away from it?

      -

      Alex: Start with By status. There is something to understand, something to try, and something that proves the try worked.

      -

      Alex: The parts worth keeping in working memory are these. "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.

      +

      Alex: Hold that next to this. Keep the learner anchored in Verify on GitHub. After pushing, visit your fork on GitHub: github.com/your-username/accessibility-agents. This is the part to say slowly: You should see a banner saying "your-username-my-agent had recent pushes" with a Compare and pull request button. A good GitHub workflow is like a well-run meeting: everyone knows the topic, the next action, and who has the floor.

      +

      Jamie: Let's pause on 9. Step 7: Open a Pull Request. What should a learner take away from it?

      +

      Alex: The reason 9. Step 7: Open a Pull Request matters is that a pull request asks the upstream maintainers to merge your branch into their repository.

      +

      Jamie: Let's pause on From the GitHub.com banner. What should a learner take away from it?

      +

      Alex: Start with From the GitHub.com banner. There is something to understand, something to try, and something that proves the try worked.

      +

      Alex: That becomes easier when you listen for these cues. Base repository: Community-Access/accessibility-agents. Base branch: main. Head repository: your-username/accessibility-agents. Compare branch: agents/your-username-my-agent. What your change does. Why it is useful.

      +

      Alex: First, after pushing, GitHub shows a yellow banner on your fork with a Compare and pull request button. Click it. Then, GitHub opens the "Open a pull request" page. Verify. After that, write a descriptive title. Example: "Add document-contrast-checker agent.". Finally, in the body, explain. Think of it as a rail line: each stop confirms you are still on the right route before the next one.

      +

      Jamie: Before we leave From the GitHub.com banner, what is the practical point?

      +

      Alex: First, if the project has a PR template, fill in all the required sections. Then, activate Create pull request. Treat it like a recipe: do not add the next ingredient until the previous one is actually in the bowl.

      -

      Alex: Keep the teaching thread moving. Keep the learner anchored in By repository. The tree organizes PRs by repository. A good GitHub workflow is like a well-run meeting: everyone knows the topic, the next action, and who has the floor.

      -

      Jamie: Let's pause on Viewing PR Details. What should a learner take away from it?

      -

      Alex: The reason Viewing PR Details matters is that a PR detail view opens in the editor area showing.

      -

      Alex: The practical takeaway is this. 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).

      -

      Alex: First, navigate to a PR in the tree. Then, press Enter. The rhythm is simple: orient, act, verify, then continue.

      -

      Alex: Keep the teaching thread moving. Start with Screen reader experience. There is something to understand, something to try, and something that proves the try worked.

      -

      Alex: The practical takeaway is this. 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.

      +

      Jamie: Let's pause on From the Pull Requests tab. What should a learner take away from it?

      +

      Alex: Start with From the Pull Requests tab. There is something to understand, something to try, and something that proves the try worked.

      +

      Alex: First, go to the upstream repository: github.com/Community-Access/accessibility-agents. Then, click the Pull requests tab. After that, click New pull request. Finally, click compare across forks. Treat it like a recipe: do not add the next ingredient until the previous one is actually in the bowl.

      +

      Jamie: Before we leave From the Pull Requests tab, what is the practical point?

      +

      Alex: First, set the head repository to your fork and the compare branch to your feature branch. Then, click Create pull request and fill in the details. It is a checklist, but a meaningful one: every item creates evidence that the next step is safe.

      +

      Jamie: Let's pause on Using GitHub CLI. What should a learner take away from it?

      +

      Alex: This is where Using GitHub CLI becomes real: the PR creation form is a standard web form. That matters in practice: Navigate with Tab to move between fields. The workshop is closer to rehearsal than lecture. You hear the move, try the move, and then check what changed.

      +

      Alex: Treat examples as spoken recipes, not decorations. You may hear something like 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.". Read the command, understand what it changes, then run it only when the repository state matches the lesson.

      +

      Jamie: Let's pause on Learning Cards: Opening a Pull Request. What should a learner take away from it?

      +

      Alex: Start with Learning Cards: Opening a Pull Request. There is something to understand, something to try, and something that proves the try worked.

      +

      Alex: A few details make that real. The PR form has a title input and a body textarea -- Tab between them; your screen reader announces field labels. The base and compare branch dropdowns use ARIA listbox patterns -- press Down Arrow to open and select branches. After submitting, GitHub navigates to the new PR page; press h to jump by headings and find the "Files changed" section. The "Compare and pull request" yellow banner appears at the top of your fork page after pushing -- it is a large, visible button. Use browser zoom (Ctrl+=) to enlarge the PR creation form if the text inputs are too small. The base and head repository/branch selectors appear near the top of the form -- verify these before submitting.

      -

      Jamie: Let's pause on 3. Checking Out a Pull Request Branch. What should a learner take away from it?

      -

      Alex: Here is the plain-English version of 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.

      -

      Alex: Keep the teaching thread moving. Start with Why Check Out a PR. There is something to understand, something to try, and something that proves the try worked.

      -

      Alex: The practical takeaway is this. 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.

      -

      Jamie: Let's pause on Method 1: From the PR Detail View. What should a learner take away from it?

      -

      Alex: Start with Method 1: From the PR Detail View. There is something to understand, something to try, and something that proves the try worked.

      -

      Alex: The practical takeaway is this. Downloads the branch. Switches your local repository to that branch. Opens the changed files in the editor.

      -

      Alex: First, open a PR (see Section 2). Then, in the PR detail view, navigate to "Checkout" button. After that, press Enter. It is like walking a hallway with named doors: read the sign, enter the right room, then confirm where you landed.

      +

      Alex: Keep the thread going. The reason 10. Step 8: Respond to Review Feedback matters is that after you open a pull request, maintainers and peers will review your changes.

      +

      Alex: The practical anchors are these. Approve - your PR is ready to merge. Request changes - you need to update your PR. Comment - ask questions or suggest improvements without formally requesting changes.

      +

      Jamie: Let's pause on How to respond to requested changes. What should a learner take away from it?

      +

      Alex: Start with How to respond to requested changes. There is something to understand, something to try, and something that proves the try worked.

      +

      Alex: First, read each review comment carefully. Understand what the reviewer is asking. Then, make the requested changes in your local clone. After that, stage, commit, and push. Finally, your new commits automatically appear in the open pull request. The reviewer is notified. Think of it as a rail line: each stop confirms you are still on the right route before the next one.

      +

      Jamie: Before we leave How to respond to requested changes, what is the practical point?

      +

      Alex: First, reply to each review comment explaining what you changed, or ask clarifying questions if the feedback is unclear. Treat it like a recipe: do not add the next ingredient until the previous one is actually in the bowl.

      +

      Alex: Treat examples as spoken recipes, not decorations. You may hear something like git add modified-file.md; git commit -m "Address review feedback: improve guardrails section"; git push. Read the command, understand what it changes, then run it only when the repository state matches the lesson.

      +

      Alex: Another way to ground it. Here is the plain-English version of Review etiquette. The Day 1 connection: You practiced code review in Chapter 15. Put another way, the same principles apply here, but now you are on the other side -- receiving feedback instead of giving it. It is like learning a transit route. The names of the stops matter because they tell you whether you are still going the right direction.

      +

      Alex: That shows up in the workshop in a few specific ways. Thank the reviewer. They spent time reading your code. Address every comment. Even if you disagree, explain your reasoning. Do not take feedback personally. Review is about the code, not about you. Ask questions. If you do not understand a comment, ask. Reviewers expect questions from new contributors.

      -

      Jamie: Let's pause on Method 2: From the PR Tree. What should a learner take away from it?

      -

      Alex: Start with Method 2: From the PR Tree. There is something to understand, something to try, and something that proves the try worked.

      -

      Alex: First, navigate to the PR in the GitHub Pull Requests tree. Then, press Shift+F10 (Mac: Ctrl+Return) to open context menu. After that, select "Checkout Pull Request". The rhythm is simple: orient, act, verify, then continue.

      -

      Jamie: Let's pause on Method 3: Command Palette. What should a learner take away from it?

      -

      Alex: Start with Method 3: Command Palette: After checkout, the bottom-left status bar shows the branch name (example: "jeffb/add-timeline-guide"). The next useful detail is this: Your local files now match that branch.

      -

      Alex: First, ctrl+Shift+P (Mac: Cmd+Shift+P). Then, type "GitHub Pull Requests: Checkout". After that, select "GitHub Pull Requests: Checkout Pull Request". Finally, choose the PR from the list. Think of it as a rail line: each stop confirms you are still on the right route before the next one.

      -

      Jamie: Let's pause on Returning to Your Original Branch. What should a learner take away from it?

      -

      Alex: Start with Returning to Your Original Branch. There is something to understand, something to try, and something that proves the try worked.

      -

      Alex: First, ctrl+Shift+P (Mac: Cmd+Shift+P). Then, type "git checkout". After that, select "Git: Checkout to.". Finally, choose your original branch (usually main or your feature branch). Treat it like a recipe: do not add the next ingredient until the previous one is actually in the bowl.

      -

      Alex: A solid Git habit is to know which branch you are on, what changed, and what confirmation you expect before you run the next command.

      +

      Jamie: Let's pause on 11. Keeping Your Fork in Sync. What should a learner take away from it?

      +

      Alex: This is where 11. Keeping Your Fork in Sync becomes real: over time, other people's changes get merged into the upstream repository. That matters in practice: Your fork does not update automatically.

      +

      Jamie: Let's pause on Sync from the command line. What should a learner take away from it?

      +

      Alex: Start with Sync from the command line. There is something to understand, something to try, and something that proves the try worked.

      +

      Alex: Treat examples as spoken recipes, not decorations. You may hear something like Make sure you are on main; git checkout main; Download the latest changes from upstream; git fetch upstream; Merge upstream changes into your local main; git merge upstream/main; Push the updated main to your fork; git push origin main. Read the command, understand what it changes, then run it only when the repository state matches the lesson.

      +

      Jamie: Let's pause on Sync from GitHub.com. What should a learner take away from it?

      +

      Alex: Start with Sync from GitHub.com. There is something to understand, something to try, and something that proves the try worked.

      +

      Alex: First, go to your fork on GitHub. Then, if your fork is behind the upstream, GitHub shows a banner: "This branch is X commits behind Community-Access:main.". After that, click Sync fork, then Update branch. The rhythm is simple: orient, act, verify, then continue.

      -

      Jamie: Let's pause on Learning Cards: Checking Out a PR. What should a learner take away from it?

      -

      Alex: Start with Learning Cards: Checking Out a PR. There is something to understand, something to try, and something that proves the try worked.

      -

      Alex: The practical takeaway is this. 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. 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.

      -

      Alex: Keep the teaching thread moving. Keep the learner anchored in 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.

      -

      Jamie: Let's pause on In the PR detail view. What should a learner take away from it?

      -

      Alex: Start with In the PR detail view. There is something to understand, something to try, and something that proves the try worked.

      -

      Alex: First, scroll down to "Files Changed" section. Then, each file is a link. After that, navigate with Arrow keys. Finally, press Enter on a file to open its diff view. The rhythm is simple: orient, act, verify, then continue.

      +

      Jamie: Let's pause on Sync from GitHub CLI. What should a learner take away from it?

      +

      Alex: Start with Sync from GitHub CLI. There is something to understand, something to try, and something that proves the try worked.

      +

      Alex: Treat examples as spoken recipes, not decorations. You may hear something like gh repo sync your-username/accessibility-agents. Read the command, understand what it changes, then run it only when the repository state matches the lesson.

      +

      Jamie: Let's pause on When to sync. What should a learner take away from it?

      +

      Alex: Start with When to sync. There is something to understand, something to try, and something that proves the try worked.

      +

      Alex: The practical takeaway is this. Before starting new work: Always sync before creating a new feature branch. This ensures your branch starts from the latest code. Before opening a PR: Sync and merge main into your feature branch to check for conflicts before asking for review. Periodically: If you are working on a long-running branch, sync weekly to avoid large conflicts.

      +

      Alex: Now bring the learner back to the room. Start with Learning Cards: Keeping Your Fork in Sync. There is something to understand, something to try, and something that proves the try worked.

      +

      Alex: The practical takeaway is this. Run git fetch upstream then git merge upstream/main in the terminal -- listen for "Already up to date" or a merge summary announcing new commits. Use git status after syncing to confirm your local main is not behind the upstream. On GitHub.com, the "Sync fork" button is near the top of your fork page; press Tab to reach it and Enter to activate. On GitHub.com, the "Sync fork" button appears below the repository description with a dropdown showing how many commits behind you are. After syncing, the Status Bar in VS Code shows no up/down arrows next to the branch name, confirming you are in sync. If a merge conflict occurs during sync, VS Code highlights conflicts with colored backgrounds (green = yours, blue = upstream).

      -

      Alex: Keep the teaching thread moving. Start with Screen reader announcement: "docs/11-vscode-interface.md, 42 additions, 3 deletions". Think of it like entering a new building: first you find the lobby, then the room, then the door you actually need.

      -

      Jamie: Let's pause on Understanding the Diff View. What should a learner take away from it?

      -

      Alex: Here is the plain-English version of Understanding the Diff View. When you open a file from "Files Changed".

      -

      Alex: Keep the teaching thread moving. Start with Split view mode (default). There is something to understand, something to try, and something that proves the try worked.

      -

      Alex: The practical takeaway is this. Left side: original file (before changes). Right side: modified file (after changes). Changed lines highlighted (added = green, removed = red).

      +

      Jamie: Let's pause on 12. The Fork Workflow Checklist. What should a learner take away from it?

      +

      Alex: Keep the learner anchored in 12. The Fork Workflow Checklist. Use this checklist every time you contribute to a repository you do not own.

      +

      Alex: The practical takeaway is this. [ ] Fork the repository on GitHub. [ ] Clone your fork locally. [ ] Add the upstream remote (git remote add upstream URL). [ ] Create a feature branch (git checkout -b branch-name). [ ] Make your changes, stage, and commit. [ ] Push your branch to your fork (git push -u origin branch-name).

      +

      Jamie: Let's pause on Cleaning up after merge. What should a learner take away from it?

      +

      Alex: The reason Cleaning up after merge matters is that after your PR is merged, delete the feature branch. That gives the learner a simple foothold: GitHub also offers a "Delete branch" button on the merged PR page. The interface gets friendlier when it stops being a wall of controls and starts being a set of named places.

      +

      Alex: Treat examples as spoken recipes, not decorations. You may hear something like Delete the local branch; git checkout main; git branch -d agents/your-username-my-agent; Delete the remote branch on your fork; git push origin --delete agents/your-username-my-agent. Read the command, understand what it changes, then run it only when the repository state matches the lesson.

      +

      Jamie: How should someone ask for help in a way that gets them unstuck faster?

      +

      Alex: Start with 13. If You Get Stuck: Next: Chapter 19: Accessibility Agents Back: Chapter 17: Issue Templates Related appendices: Appendix E: Advanced Git Appendix O: Branch Protection.

      -

      Jamie: Let's pause on Inline view mode. What should a learner take away from it?

      -

      Alex: Start with Inline view mode. There is something to understand, something to try, and something that proves the try worked.

      -

      Alex: The practical takeaway is this. Single editor. Removed lines shown with - prefix. Added lines shown with + prefix.

      -

      Alex: Keep the teaching thread moving. Start with To toggle between views. There is something to understand, something to try, and something that proves the try worked.

      -

      Alex: The practical takeaway is this. Command Palette: Ctrl+Shift+P (Mac: Cmd+Shift+P) → "Diff: Toggle Inline View".

      -

      Jamie: Let's pause on Recommended workflow for screen reader users. What should a learner take away from it?

      -

      Alex: Start with Recommended workflow for screen reader users. There is something to understand, something to try, and something that proves the try worked.

      -

      Alex: The practical takeaway is this. Unchanged lines (for context). Removed lines (prefixed with -). Added lines (prefixed with +).

      -

      Alex: First, open a changed file from the PR detail view. Then, press F7 to jump to the first diff hunk. After that, press Alt+F2 (Mac: Option+F2) to open Accessible View. Finally, read the hunk content. Think of it as a rail line: each stop confirms you are still on the right route before the next one.

      -

      Jamie: Before we leave Recommended workflow for screen reader users, what is the practical point?

      -

      Alex: First, press Escape to close Accessible View. Then, press F7 to jump to the next hunk. After that, repeat until all hunks reviewed. Treat it like a recipe: do not add the next ingredient until the previous one is actually in the bowl.

      +

      Jamie: What should people carry with them after this?

      +

      Alex: Carry the map. Know what page or tool you are in, know which action you are taking, and know what confirmation should follow. If the confirmation is missing, pause. That pause is not wasted time; it is professional judgment.

      +

      Jamie: That is a better way to say it than just follow the steps.

      +

      Alex: Right. Steps matter, but understanding wins. That is episode 47. Next in the series is episode 48, where we keep building the same contributor muscles.

      +
      +
      -

      Alex: Keep the teaching thread moving. Here is the plain-English version of 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. Put another way, previously, deleted code could only be read, not selected.

      -

      Jamie: Let's pause on Flagging Issues During Review. What should a learner take away from it?

      -

      Alex: This is where Flagging Issues During Review becomes real: start Review saves your comments as a draft until you submit the full review (see Section 7).

      -

      Alex: First, navigate to the specific line in the diff. Then, press Shift+F10 (Mac: Ctrl+Return) for context menu. After that, select "Add Comment". Finally, type your comment in the input that appears. It is a checklist, but a meaningful one: every item creates evidence that the next step is safe.

      -

      Jamie: Before we leave Flagging Issues During Review, what is the practical point?

      -

      Alex: First, choose "Single Comment" or "Start Review". It is like walking a hallway with named doors: read the sign, enter the right room, then confirm where you landed.

      -

      Alex: A solid issue habit is to read the title, the body, and the timeline before acting. You are listening for the requested action, the missing evidence, and the person who needs a response.

      -

      Alex: Keep the teaching thread moving. Start with Learning Cards: Reviewing Pull Requests in VS Code. There is something to understand, something to try, and something that proves the try worked.

      -

      Alex: The practical takeaway is this. 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. 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.

      +

      51. Episode 48: Build Your Agent: Capstone

      +

      Designing, writing, testing, and contributing a custom accessibility agent.

      +

      Based on: Chapter 20: Build Your Agent: Capstone

      +

      Audio and transcript are being regenerated for this episode.

      +
      +Read Transcript - Episode 48: Build Your Agent: Capstone + +

      Transcript

      +

      Alex: Welcome to Git Going with GitHub, episode 48: Build Your Agent: Capstone. I am Alex. Today we are going to make Build Your Agent: Capstone something you can explain, practice, and recover from when the interface surprises you.

      +

      Jamie: And I am Jamie. I will be the voice of the learner who is willing to ask, what is this for, where am I, and how do I know I did it right?

      -

      Jamie: Let's pause on Tool Cards: Create a Pull Request (from your editor). What should a learner take away from it?

      -

      Alex: The reason Tool Cards: Create a Pull Request (from your editor) matters is that VS Code Desktop (primary for Day 2). That gives the learner a simple foothold: after you've pushed commits to a feature branch, you can create a PR without leaving VS Code.

      -

      Alex: First, ctrl+Shift+P GitHub Pull Requests: Create Pull Request. Then, fill in the title, description, and base branch. After that, click Create. Finally, push your branch, then click the Compare & pull request banner on the repo page. The rhythm is simple: orient, act, verify, then continue.

      -

      Jamie: Before we leave Tool Cards: Create a Pull Request (from your editor), what is the practical point?

      -

      Alex: First, fill in the form and click Create pull request. Then, after pushing, click Create Pull Request -- this opens gitub.com with the form pre-filled. Think of it as a rail line: each stop confirms you are still on the right route before the next one.

      -

      Alex: Treat examples as spoken recipes, not decorations. You may hear something like git push -u origin your-branch; gh pr create --title "Title" --body "Description". Read the command, understand what it changes, then run it only when the repository state matches the lesson.

      -

      Jamie: Let's pause on Prerequisites. What should a learner take away from it?

      -

      Alex: Start with Prerequisites. There is something to understand, something to try, and something that proves the try worked.

      -

      Alex: First, you've created a branch (see Git & Source Control: Branch Management). Then, you've made commits. After that, you've pushed the branch to GitHub (Ctrl+Shift+P / Mac: Cmd+Shift+P → "Git: Push"). Think of it as a rail line: each stop confirms you are still on the right route before the next one.

      -

      Jamie: Let's pause on Method 1: Command Palette (Recommended). What should a learner take away from it?

      -

      Alex: Start with Method 1: Command Palette (Recommended). There is something to understand, something to try, and something that proves the try worked.

      -

      Alex: First, ctrl+Shift+P (Mac: Cmd+Shift+P). Then, type "GitHub Pull Requests: Create". After that, select "GitHub Pull Requests: Create Pull Request". Finally, a form opens in the editor. Treat it like a recipe: do not add the next ingredient until the previous one is actually in the bowl.

      +

      Alex: The big idea today: Designing, writing, testing, and contributing a custom accessibility agent. We will name the concept, explain why it matters, practice the move, and point out the checks that tell you the work is real.

      +

      Jamie: So the episode should work even if someone has not read the chapter yet.

      +

      Alex: Exactly. The transcript has to stand on its own. It can point toward practice, but it should teach the concept right here in the conversation.

      -

      Jamie: Let's pause on Method 2: Source Control Panel. What should a learner take away from it?

      -

      Alex: Start with Method 2: Source Control Panel. There is something to understand, something to try, and something that proves the try worked.

      -

      Alex: First, open Source Control: Ctrl+Shift+G (Mac: Cmd+Shift+G). Then, after pushing, a "Create Pull Request" button appears. After that, press Enter on that button. It is a checklist, but a meaningful one: every item creates evidence that the next step is safe.

      -

      Jamie: Let's pause on Method 3: GitHub Panel. What should a learner take away from it?

      -

      Alex: Start with Method 3: GitHub Panel. There is something to understand, something to try, and something that proves the try worked.

      -

      Alex: First, open GitHub view (Activity Bar → GitHub icon). Then, right-click your branch in the tree. After that, select "Create Pull Request". It is like walking a hallway with named doors: read the sign, enter the right room, then confirm where you landed.

      -

      Alex: Keep the teaching thread moving. Start with Title (required). There is something to understand, something to try, and something that proves the try worked.

      -

      Alex: The practical takeaway is this. Auto-filled with your most recent commit message. Edit to make it descriptive (example: "Add Timeline View documentation").

      +

      Jamie: Give me the sequence, because order matters here.

      +

      Alex: Start with 1. The Capstone Challenge: The capstone is Challenge 16 -- the final challenge of the workshop. The next useful detail is this: Your pull request goes to a real repository.

      +

      Alex: First, choose a mission for a new accessibility agent (or improve an existing one). Then, write an agent file with valid YAML frontmatter. After that, define clear responsibilities and guardrails. Finally, test the agent locally with GitHub Copilot. Think of it as a rail line: each stop confirms you are still on the right route before the next one.

      +

      Jamie: How would you walk the room through that step by step?

      +

      Alex: First, open a pull request from your fork to the upstream repository. Then, respond to peer review feedback. Treat it like a recipe: do not add the next ingredient until the previous one is actually in the bowl.

      +

      Alex: The next layer is this. Start with What you need before starting. There is something to understand, something to try, and something that proves the try worked.

      +

      Alex: The practical anchors are these. [ ] You have forked and cloned the accessibility-agents repository (Chapter 18). [ ] You have a feature branch created: agents/your-username-agent-name. [ ] You understand how to push to your fork and open a PR (Chapter 18). [ ] You have GitHub Copilot or Copilot Free active (Chapter 16). [ ] You have explored the existing agents in Chapter 19.

      +

      Jamie: What is the one idea that makes the next few steps less mysterious?

      +

      Alex: This is where Time estimate becomes real: most students complete the capstone in 60 to 90 minutes. That matters in practice: The phases are designed so you can get a working agent in 30 minutes and spend the remaining time improving it.

      -

      Jamie: Let's pause on Description (optional but recommended). What should a learner take away from it?

      -

      Alex: Start with Description (optional but recommended). There is something to understand, something to try, and something that proves the try worked.

      -

      Alex: The practical takeaway is this. 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.

      -

      Alex: Keep the teaching thread moving. Start with Base branch (target). There is something to understand, something to try, and something that proves the try worked.

      -

      Alex: The practical takeaway is this. Usually main or develop. This is the branch your changes will merge into.

      -

      Jamie: Let's pause on Compare branch (source). What should a learner take away from it?

      -

      Alex: Start with Compare branch (source). There is something to understand, something to try, and something that proves the try worked.

      -

      Alex: The practical takeaway is this. Your feature branch (auto-selected). This is the branch with your changes.

      +

      Alex: Now bring the learner back to the room. Keep the learner anchored in 2. Phase 1: Choose Your Agent's Mission. See also: Chapter 19: Accessibility Agents introduces the agent ecosystem and shows existing agents for inspiration.

      +

      Jamie: What would you say to someone who is already bracing for this to be too much?

      +

      Alex: The reason What makes a good agent mission matters is that a good agent solves a specific, recurring problem.

      +

      Alex: The parts worth keeping in working memory are these. What task do you repeat? Think about workflow steps from Day 1 and Day 2 that felt repetitive. What would a specialist know? An agent works best when it has deep knowledge of a focused area. What gap exists? Look at the existing agents in Chapter 19. Is there a workflow that no agent covers?

      +

      Alex: The useful habit is simple: orient first, act second, verify third. That pause before acting is part of the work.

      +

      Alex: That matters because of the next idea. Start with Write your mission statement: Before writing any code, write a one-sentence mission statement. The next useful detail is this: "My agent helps [who] by [doing what] when [in what situation].". Think of it like entering a new building: first you find the lobby, then the room, then the door you actually need.

      -

      Alex: Keep the teaching thread moving. Start with Reviewers (optional). There is something to understand, something to try, and something that proves the try worked.

      -

      Alex: The practical takeaway is this. Select people to review your PR. Navigate the list with Arrow keys.

      -

      Jamie: Let's pause on Labels (optional). What should a learner take away from it?

      -

      Alex: Start with Labels (optional). There is something to understand, something to try, and something that proves the try worked.

      -

      Alex: The practical takeaway is this. Add labels like documentation, accessibility, good-first-issue.

      -

      Alex: Keep the teaching thread moving. Start with Milestone (optional). There is something to understand, something to try, and something that proves the try worked.

      -

      Alex: The practical takeaway is this. Link the PR to a project milestone.

      +

      Jamie: Okay, set the room for us. What are we walking into?

      +

      Alex: Here is the plain-English version of 3. Phase 2: Write the Agent File. An agent file is a Markdown file with YAML frontmatter that defines the agent's identity, and a body that contains the agent's instructions. Put another way, agent files live in the.github/agents/ directory (for GitHub Copilot agents) or in team-specific directories in the accessibility-agents repository.

      +

      Alex: This is where the talk moves from concept to action. This is where File location and naming becomes real: example.github/agents/alt-text-validator.md.

      +

      Jamie: Turn that into a path someone can follow.

      +

      Alex: Start with The agent file structure. There is something to understand, something to try, and something that proves the try worked.

      +

      Alex: First, yAML frontmatter -- metadata between --- markers at the top of the file. Then, instructions body -- Markdown content that tells the agent how to behave. It is like walking a hallway with named doors: read the sign, enter the right room, then confirm where you landed.

      -

      Jamie: Let's pause on Draft PR checkbox. What should a learner take away from it?

      -

      Alex: Start with Draft PR checkbox. There is something to understand, something to try, and something that proves the try worked.

      -

      Alex: The practical takeaway is this. Check this if the PR is not ready for review yet. Unchecked = "Ready for review".

      -

      Alex: Keep the teaching thread moving. Start with Screen reader navigation. There is something to understand, something to try, and something that proves the try worked.

      -

      Alex: The practical takeaway is this. All fields are standard form inputs. Tab to move between fields. Use Arrow keys in dropdowns (reviewers, labels, milestones).

      -

      Jamie: Let's pause on Submitting the PR. What should a learner take away from it?

      -

      Alex: Keep the learner anchored in Submitting the PR. VS Code creates the PR on GitHub and shows a success message. This is the part to say slowly: The PR link appears in the notification - click it to open the PR on GitHub, or open it in the GitHub Pull Requests panel.

      -

      Alex: First, review all fields. Then, tab to "Create" button. After that, press Enter. Finally, navigate to the repository on GitHub. It is like walking a hallway with named doors: read the sign, enter the right room, then confirm where you landed.

      -

      Jamie: Before we leave Submitting the PR, what is the practical point?

      -

      Alex: First, if you recently pushed, a yellow banner "Compare & pull request" appears - click it. Then, otherwise: click Pull requests tab, then New pull request, then select your branch. After that, fill in the title and description. Finally, click Create pull request. The rhythm is simple: orient, act, verify, then continue.

      -

      Alex: Treat examples as spoken recipes, not decorations. You may hear something like 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. Read the command, understand what it changes, then run it only when the repository state matches the lesson.

      +

      Alex: Before the learner moves on. The reason YAML frontmatter fields matters is that vague descriptions result in missed automatic routing. That gives the learner a simple foothold: weak: Helps with accessibility - Strong: Checks markdown files for accessibility issues, fixes descriptive links and heading hierarchy, and flags alt text for human review The more specific the description, the more reliably Copilot invokes the right agent for. The interface gets friendlier when it stops being a wall of controls and starts being a set of named places.

      +

      Jamie: Give me the version that sounds like an instructor, not a manual.

      +

      Alex: Start with Writing the instructions body: The instructions body tells the agent how to behave. The next useful detail is this: Write it as if you are briefing a new team member on their first day.

      +

      Alex: A few details make that real. Start with identity. "You are a [role] focused on [area].". List responsibilities. What specific tasks does this agent handle? Set guardrails. What should the agent never do? What are its limits? Provide examples. Show what good output looks like.

      +

      Alex: Hold that next to this. Start with Learning Cards: Writing the Agent File. There is something to understand, something to try, and something that proves the try worked.

      +

      Alex: That shows up in the workshop in a few specific ways. Create your agent file with Ctrl+N, then Ctrl+S and save to.github/agents/your-agent-name.md -- the Explorer navigates to the folder automatically. Use Ctrl+Shift+O to navigate between YAML frontmatter fields and Markdown headings (Responsibilities, Guardrails) in your agent file. The YAML frontmatter is between --- markers at the top -- your screen reader announces these as horizontal rules. Agent files are standard Markdown -- open Markdown Preview (Ctrl+Shift+V) side by side to verify formatting as you write. The YAML frontmatter at the top uses name: and description: fields -- keep these on separate lines for readability at high zoom. Use a consistent heading hierarchy ( for title, for sections) so the Outline view (Ctrl+Shift+O) shows a clean structure.

      -

      Alex: Keep the teaching thread moving. Start with Learning Cards: Creating a Pull Request. There is something to understand, something to try, and something that proves the try worked.

      -

      Alex: The practical takeaway is this. 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. 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.

      -

      Jamie: Let's pause on 6. Pull Request Description Templates. What should a learner take away from it?

      -

      Alex: Start with 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.

      -

      Alex: Keep the teaching thread moving. Here is the plain-English version of Where Templates Are Stored. When you create a PR in VS Code, the extension automatically loads the template into the description field.

      -

      Alex: The practical takeaway is this.github/pull request template.md (root).github/PULL REQUEST TEMPLATE.md.github/PULL REQUEST TEMPLATE/ (folder with multiple templates). docs/pull request template.md.

      +

      Jamie: If I am listening before the workshop starts, what should settle in my mind first?

      +

      Alex: This is where 4. Phase 3: Define Responsibilities and Guardrails becomes real: responsibilities and guardrails are the most important parts of your agent's instructions. That matters in practice: The autograder checks that both sections exist.

      +

      Alex: That connects to another useful point. Keep the learner anchored in Writing responsibilities. Responsibilities define what the agent does. This is the part to say slowly: Each responsibility should describe one discrete action the agent can take. A good GitHub workflow is like a well-run meeting: everyone knows the topic, the next action, and who has the floor.

      +

      Alex: For a learner, the useful signals are these. Scan HTML files for tags missing the alt attribute. Check that all elements have visible text or an aria-label. Verify heading levels do not skip (e.g., h1 to h3 without h2). Help with accessibility.

      +

      Jamie: Where do you want a learner to place their attention here?

      +

      Alex: The reason Writing guardrails matters is that guardrails define what the agent must not do. That gives the learner a simple foothold: they prevent the agent from overstepping, giving harmful advice, or acting without permission.

      +

      Alex: On the ground, that means a few things. Never auto-fix code without asking the user first. Do not provide medical, legal, or financial advice when discussing accessibility compliance. Limit reviews to the files the user specifies -- do not scan the entire repository. If a finding is uncertain, say so explicitly rather than presenting it as definitive.

      -

      Jamie: What should they understand before typing anything?

      -

      Alex: Start with Example PR Template. There is something to understand, something to try, and something that proves the try worked.

      -

      Alex: Treat examples as spoken recipes, not decorations. You may hear something like 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,. Read the command, understand what it changes, then run it only when the repository state matches the lesson.

      -

      Jamie: Let's pause on Screen reader workflow. What should a learner take away from it?

      -

      Alex: Keep the learner anchored in Screen reader workflow. Keyboard tip: Use Ctrl+F (Mac: Cmd+F) to jump to each <!-- placeholder, fill it in, then F3 to jump to the next one. A good GitHub workflow is like a well-run meeting: everyone knows the topic, the next action, and who has the floor.

      -

      Alex: First, create PR (Method 1-3 from Section 5). Then, the description field is pre-filled with the template. After that, navigate through the template with Arrow keys. Finally, replace each `` with your content. It is like walking a hallway with named doors: read the sign, enter the right room, then confirm where you landed.

      -

      Jamie: Before we leave Screen reader workflow, what is the practical point?

      -

      Alex: First, check checkboxes by typing x between the brackets: - [x]. The rhythm is simple: orient, act, verify, then continue.

      -

      Jamie: Let's pause on 7. Commenting and Requesting Changes. What should a learner take away from it?

      -

      Alex: Start with 7. Commenting and Requesting Changes. There is something to understand, something to try, and something that proves the try worked.

      -

      Alex: The practical takeaway is this. Leave inline comments on specific lines. Request changes before the PR can be merged. Approve the PR. Submit general feedback.

      +

      Alex: Here is the practical turn. Start with Learning Cards: Responsibilities and Guardrails. There is something to understand, something to try, and something that proves the try worked.

      +

      Alex: Here is what that changes in practice. Use Responsibilities and Guardrails as exact heading names -- the autograder searches for these strings. Each responsibility should start with a verb (Scan, Check, Verify, Flag) -- this makes them concrete and testable. Guardrails should start with "Never" or "Do not" to set clear boundaries your screen reader identifies as restrictions when reviewing the file. Format responsibilities as a bulleted list (starting with -) for easy scanning at high zoom -- one responsibility per bullet. Keep each guardrail to a single line so it remains visible without horizontal scrolling at your zoom level. Use bold text for emphasis on critical guardrails (e.g., Never modify files without approval ) to improve visual scanning.

      +

      Jamie: Let's pause on 5. Phase 4: Test Your Agent Locally. What should a learner take away from it?

      +

      Alex: Here is the plain-English version of 5. Phase 4: Test Your Agent Locally. See also: Chapter 18: Fork and Contribute covers the fork-and-PR workflow you will use to submit your agent. Put another way, before opening a pull request, test your agent to verify it works.

      +

      Jamie: What does the learner do first, second, and then after that?

      +

      Alex: Start with Testing with GitHub Copilot Chat. There is something to understand, something to try, and something that proves the try worked.

      +

      Alex: The room should hear these as checkpoints. Understand its mission? Follow its responsibilities? Respect its guardrails?

      +

      Alex: First, open VS Code with the accessibility-agents repository. Then, ensure your agent file is saved in.github/agents/. After that, open GitHub Copilot Chat (Ctrl+Shift+I or Cmd+Shift+I). Finally, invoke your agent by name: @your-agent-name check this file for accessibility issues. It is a checklist, but a meaningful one: every item creates evidence that the next step is safe.

      +

      Jamie: What is the ordered workflow?

      +

      Alex: First, observe the response. Does the agent. It is like walking a hallway with named doors: read the sign, enter the right room, then confirm where you landed.

      -

      Jamie: Let's pause on Adding an Inline Comment. What should a learner take away from it?

      -

      Alex: Start with Adding an Inline Comment. There is something to understand, something to try, and something that proves the try worked.

      -

      Alex: First, open a file from the PR's "Files Changed" list. Then, navigate to the line you want to comment on. After that, press Shift+F10 (Mac: Ctrl+Return) to open context menu. Finally, select "Add Comment". Think of it as a rail line: each stop confirms you are still on the right route before the next one.

      -

      Jamie: Before we leave Adding an Inline Comment, what is the practical point?

      -

      Alex: First, type your comment. Then, choose "Add Single Comment" (posts immediately) or "Start Review" (saves as a draft). Treat it like a recipe: do not add the next ingredient until the previous one is actually in the bowl.

      -

      Jamie: Let's pause on Comment format tips. What should a learner take away from it?

      -

      Alex: Start with Comment format tips. There is something to understand, something to try, and something that proves the try worked.

      -

      Alex: The practical takeaway is this. Be specific: "This heading should be H3, not H2". Provide context: "Screen readers announce this as 'list with 1 item' - should be a paragraph instead". Suggest a fix: "Consider rewording to: 'Click the button to save'".

      -

      Jamie: Let's pause on If you have multiple comments to make, use "Start Review". What should a learner take away from it?

      -

      Alex: Start with If you have multiple comments to make, use "Start Review". There is something to understand, something to try, and something that proves the try worked.

      -

      Alex: First, add your first inline comment → select "Start Review". Then, continue adding comments to other lines. After that, all comments are saved as drafts (not visible to others yet). It is a checklist, but a meaningful one: every item creates evidence that the next step is safe.

      +

      Jamie: Let's pause on Testing checklist. What should a learner take away from it?

      +

      Alex: Start with Testing checklist. There is something to understand, something to try, and something that proves the try worked.

      +

      Alex: These are the details that keep the idea from floating away. [ ] The agent responds when invoked by name. [ ] The agent stays within its defined responsibilities. [ ] The agent does not violate any guardrails. [ ] The agent's output is useful and specific. [ ] The agent handles edge cases gracefully (empty files, no issues found).

      +

      Jamie: Let's pause on Iterating on your agent. What should a learner take away from it?

      +

      Alex: The reason Iterating on your agent matters is that if the agent does not behave as expected. That gives the learner a simple foothold: most students iterate 2-3 times before they are satisfied.

      +

      Alex: First, read its instructions carefully. Is anything ambiguous? Then, add more specific instructions or examples. After that, test again with the same prompt. Finally, repeat until the behavior matches your intent. The rhythm is simple: orient, act, verify, then continue.

      +

      Jamie: Let's pause on Learning Cards: Testing Your Agent. What should a learner take away from it?

      +

      Alex: Start with Learning Cards: Testing Your Agent. There is something to understand, something to try, and something that proves the try worked.

      +

      Alex: That becomes easier when you listen for these cues. Open Copilot Chat (Ctrl+Shift+I) and type @your-agent-name followed by a test prompt -- your screen reader announces the response as it streams. Press Alt+F2 after the response finishes to read the full output in Accessible View with arrow keys. If the agent does not respond as expected, edit the.agent.md file and ask again -- Copilot picks up changes immediately. Agent responses appear in the Copilot Chat panel -- widen the panel by dragging its left edge for better readability. Test with a simple prompt first (e.g., "review this file") and read the full response before trying complex requests. Use Accessible View (Alt+F2) to read responses at your preferred editor font size instead of the Chat panel's default.

      -

      Jamie: Let's pause on Submitting Your Review. What should a learner take away from it?

      -

      Alex: Keep the learner anchored in Submitting Your Review. The review type selector is a radio button group. This is the part to say slowly: Use Arrow keys to choose, Enter to confirm.

      -

      Alex: The practical takeaway is this. Comment - general feedback, no approval decision. Approve - PR looks good, ready to merge. Request Changes - issues must be fixed before merging.

      -

      Alex: First, ctrl+Shift+P (Mac: Cmd+Shift+P). Then, type "GitHub Pull Requests: Submit Review". After that, select "GitHub Pull Requests: Finish Review". Finally, choose review type. It is like walking a hallway with named doors: read the sign, enter the right room, then confirm where you landed.

      -

      Jamie: Before we leave Submitting Your Review, what is the practical point?

      -

      Alex: First, optionally add a summary comment. Then, press Enter to submit. The rhythm is simple: orient, act, verify, then continue.

      -

      Jamie: Let's pause on What Happens After Submission. What should a learner take away from it?

      -

      Alex: The reason What Happens After Submission matters is that web alternative (github.com) - reviewing. That gives the learner a simple foothold: see Accessible Code Review for detailed screen reader steps.

      -

      Alex: The practical takeaway is this. All your draft comments post to GitHub. The PR author receives a notification. Your review status appears on the PR (Approved / Changes Requested / Commented). If you requested changes, the PR cannot merge until you approve it.

      -

      Alex: First, open the PR and click the Files changed tab. Then, read through each file's diff. After that, click the blue + button on any line to add an inline comment. Finally, choose Start a review to batch comments. The rhythm is simple: orient, act, verify, then continue.

      -

      Jamie: Before we leave What Happens After Submission, what is the practical point?

      -

      Alex: First, click Review changes (top right) to select Comment / Approve / Request changes. Then, click Submit review. Think of it as a rail line: each stop confirms you are still on the right route before the next one.

      -

      Alex: Treat examples as spoken recipes, not decorations. You may hear something like View the PR diff in your terminal; gh pr diff 42; Approve; gh pr review 42 --approve --body "Looks good."; Request changes; gh pr review 42 --request-changes --body "Heading hierarchy needs fixing."; Comment-only (no verdict); gh pr review 42 --comment --body. Read the command, understand what it changes, then run it only when the repository state matches the lesson.

      -

      Jamie: Let's pause on Learning Cards: Commenting and Requesting Changes. What should a learner take away from it?

      -

      Alex: Start with Learning Cards: Commenting and Requesting Changes. There is something to understand, something to try, and something that proves the try worked.

      -

      Alex: The practical takeaway is this. In a diff view, navigate to a line and press Shift+F10 for the context menu, then select "Add Comment" to leave inline feedback. Choose "Start Review" instead of "Single Comment" to batch multiple comments before submitting them all at once. When submitting a review, use Ctrl+Shift+P then "GitHub Pull Requests: Submit Review" and choose Approve, Request Changes, or Comment. Inline comments appear as expandable banners within the diff view -- look for the text input box that opens below the target line. The review submission dialog has radio buttons for Approve, Request Changes, and Comment with clear labels. Increase diff view font size with Ctrl+= so line numbers and change annotations are easier to read.

      +

      Jamie: Let's pause on Tool Cards: Open Your Capstone PR. What should a learner take away from it?

      +

      Alex: Here is the plain-English version of Tool Cards: Open Your Capstone PR. VS Code Desktop (primary for Day 2). It is like learning a transit route. The names of the stops matter because they tell you whether you are still going the right direction.

      +

      Alex: First, push your branch: Ctrl+Shift+P Git: Push. Then, ctrl+Shift+P GitHub Pull Requests: Create Pull Request. After that, set base repo to Community-Access/accessibility-agents, fill in the title and description. Finally, navigate to your fork on GitHub. Treat it like a recipe: do not add the next ingredient until the previous one is actually in the bowl.

      +

      Jamie: Before we leave Tool Cards: Open Your Capstone PR, what is the practical point?

      +

      Alex: First, click Contribute Open pull request. Then, verify the base is Community-Access/accessibility-agents:main and the compare is your branch. It is a checklist, but a meaningful one: every item creates evidence that the next step is safe.

      +

      Alex: Treat examples as spoken recipes, not decorations. You may hear something like git push -u origin your-branch; gh pr create --repo Community-Access/accessibility-agents. Read the command, understand what it changes, then run it only when the repository state matches the lesson.

      +

      Alex: A solid pull request habit is to separate three questions: what changed, why it changed, and what still needs review. That keeps the conversation useful instead of noisy.

      +

      Jamie: Let's pause on Pre-PR checklist. What should a learner take away from it?

      +

      Alex: Start with Pre-PR checklist. There is something to understand, something to try, and something that proves the try worked.

      +

      Alex: The practical takeaway is this. [ ] Your agent file has valid YAML frontmatter (name and description fields). [ ] Your agent file has a Responsibilities section. [ ] Your agent file has a Guardrails section. [ ] The file is in the correct directory. [ ] You have committed and pushed to your fork.

      +

      Jamie: Let's pause on Open the PR. What should a learner take away from it?

      +

      Alex: Keep the learner anchored in Open the PR. Follow the pull request steps from Chapter 18, Step 7.

      +

      Alex: The practical takeaway is this. Your mission statement from Phase 1. What the agent does (summary of responsibilities). Any design decisions you made. How you tested it.

      +

      Alex: First, push your branch: git push -u origin agents/your-username-agent-name. Then, go to the upstream repository on GitHub.com. After that, click the banner or go to Pull Requests and click New pull request, then compare across forks. Finally, select your fork and branch. It is like walking a hallway with named doors: read the sign, enter the right room, then confirm where you landed.

      +

      Jamie: Before we leave Open the PR, what is the practical point?

      +

      Alex: First, write a PR title: "Add [agent-name] accessibility agent". Then, in the PR body,. After that, create the pull request. The rhythm is simple: orient, act, verify, then continue.

      -

      Alex: Keep the teaching thread moving. Here is the plain-English version of 8. Merging Pull Requests. Who can merge: Repository maintainers, or contributors with write access. It is like learning a transit route. The names of the stops matter because they tell you whether you are still going the right direction.

      -

      Jamie: Let's pause on Prerequisites for Merging. What should a learner take away from it?

      -

      Alex: This is where Prerequisites for Merging becomes real: changing the base branch: If the PR was opened against the wrong base branch, you can change it from the PR detail view in VS Code. That matters in practice: Scroll to the base branch field in the PR detail view and activate the dropdown to select a different target branch.

      -

      Alex: First, all required reviews are approved. Then, all CI checks pass (green checkmarks). After that, no merge conflicts exist. Finally, branch is up to date with base branch (main). It is a checklist, but a meaningful one: every item creates evidence that the next step is safe.

      -

      Jamie: Let's pause on Method 1: PR Detail View. What should a learner take away from it?

      -

      Alex: Start with Method 1: PR Detail View. There is something to understand, something to try, and something that proves the try worked.

      -

      Alex: First, open the PR in VS Code. Then, scroll to the bottom of the PR detail view. After that, find "Merge Pull Request" button. Finally, press Enter. It is like walking a hallway with named doors: read the sign, enter the right room, then confirm where you landed.

      -

      Jamie: Before we leave Method 1: PR Detail View, what is the practical point?

      -

      Alex: First, choose merge type (see below). The rhythm is simple: orient, act, verify, then continue.

      +

      Jamie: Let's pause on The autograder. What should a learner take away from it?

      +

      Alex: The reason The autograder matters is that the repository has an autograding workflow that runs on every pull request. That gives the learner a simple foothold: the autograder posts results as a comment on your PR.

      +

      Alex: Keep the thread going. Start with Learning Cards: Opening Your Pull Request. There is something to understand, something to try, and something that proves the try worked.

      +

      Alex: The practical takeaway is this. The autograder comment appears in the PR timeline -- navigate to Comments on GitHub.com with h (heading navigation) to find the results. Each autograder check is listed with a pass/fail status and point value -- listen for "10/10" or "0/15" to identify which checks need attention. If a check fails, read the failure message, fix the issue locally, commit, push, and the autograder re-runs automatically. The autograder results appear as a comment with a table showing checks, points, and pass/fail status -- zoom with Ctrl+= to read the details. Green checkmarks indicate passing checks; red X marks indicate failures -- pair with High Contrast theme for clearest visibility. Your PR description should include your mission statement, responsibilities summary, and testing notes.

      +

      Jamie: Let's pause on 7. Phase 6: Respond to Review. What should a learner take away from it?

      +

      Alex: Here is the plain-English version of 7. Phase 6: Respond to Review. After the autograder passes, a peer reviewer (your buddy or another student) and a facilitator will review your agent.

      -

      Jamie: What is the teaching move inside Method 2: Command Palette?

      -

      Alex: Start with Method 2: Command Palette. There is something to understand, something to try, and something that proves the try worked.

      -

      Alex: First, ctrl+Shift+P (Mac: Cmd+Shift+P). Then, type "GitHub Pull Requests: Merge". After that, select "GitHub Pull Requests: Merge Pull Request". Finally, choose the PR from the list. The rhythm is simple: orient, act, verify, then continue.

      -

      Jamie: If someone only remembers one thing from Method 2: Command Palette, what should it be?

      -

      Alex: First, select merge type. Think of it as a rail line: each stop confirms you are still on the right route before the next one.

      -

      Alex: Keep the teaching thread moving. Start with Merge Types: The merge type selector is a dropdown or radio group. The next useful detail is this: Navigate with Arrow keys, confirm with Enter. Think of it like entering a new building: first you find the lobby, then the room, then the door you actually need.

      -

      Jamie: Let's pause on Which merge type to use. What should a learner take away from it?

      -

      Alex: Start with Which merge type to use. There is something to understand, something to try, and something that proves the try worked.

      -

      Alex: The practical takeaway is this. Check the repository's CONTRIBUTING.md for guidance. If unsure, use Merge Commit (the default and safest option).

      +

      Alex: Another way to ground it. Start with What reviewers look for. There is something to understand, something to try, and something that proves the try worked.

      +

      Alex: The practical takeaway is this. Clarity: Are the instructions easy to understand? Specificity: Are responsibilities concrete and actionable? Safety: Are guardrails sufficient to prevent harmful behavior? Usefulness: Would this agent actually help someone? Scope: Does the agent try to do too much or too little?

      +

      Jamie: Let's pause on Responding to feedback. What should a learner take away from it?

      +

      Alex: Keep the learner anchored in Responding to feedback. This is the same process from Chapter 18, Step 8.

      +

      Alex: First, read each review comment. Then, make changes locally. After that, commit and push. The PR updates automatically. Finally, reply to each comment explaining your changes. It is like walking a hallway with named doors: read the sign, enter the right room, then confirm where you landed.

      +

      Alex: This is the part worth saying out loud. The reason When your PR is merged matters is that your agent is now part of the accessibility-agents ecosystem. That gives the learner a simple foothold: it is available to anyone who uses the repository. The interface gets friendlier when it stops being a wall of controls and starts being a set of named places.

      +

      Alex: The practical takeaway is this. You can navigate the fork workflow end to end. You can write clear, structured technical documentation. You understand accessibility concepts well enough to teach an AI agent about them. You can respond constructively to code review.

      -

      Jamie: Let's pause on After Merging. What should a learner take away from it?

      -

      Alex: Start with After Merging. There is something to understand, something to try, and something that proves the try worked.

      -

      Alex: First, the PR closes automatically. Then, the feature branch can be deleted (VS Code prompts: "Delete branch?"). After that, recommended: switch back to main and pull the merged changes. It is a checklist, but a meaningful one: every item creates evidence that the next step is safe.

      -

      Jamie: How do you keep commands from becoming magic words?

      -

      Alex: Keep the learner anchored in Switching to main and pulling. (Mac users: use Cmd+Shift+P instead of Ctrl+Shift+P).

      -

      Alex: Treat examples as spoken recipes, not decorations. You may hear something like Ctrl+Shift+P → "Git: Checkout to." → select "main"; Ctrl+Shift+P → "Git: Pull". Read the command, understand what it changes, then run it only when the repository state matches the lesson.

      -

      Jamie: Let's pause on Deleting the Feature Branch. What should a learner take away from it?

      -

      Alex: The reason Deleting the Feature Branch matters is that after merging, the feature branch is no longer needed. That gives the learner a simple foothold: web alternative (github.com) - merging. The interface gets friendlier when it stops being a wall of controls and starts being a set of named places.

      -

      Alex: First, ctrl+Shift+P (Mac: Cmd+Shift+P). Then, type "git delete branch". After that, select "Git: Delete Branch.". Finally, choose the merged branch. The rhythm is simple: orient, act, verify, then continue.

      -

      Jamie: Before we leave Deleting the Feature Branch, what is the practical point?

      -

      Alex: First, open the PR's Conversation tab. Then, scroll to the merge button at the bottom. After that, click the dropdown arrow to choose a merge strategy (Squash, Rebase, or Merge commit). Finally, click Merge pull request, then Confirm merge. Think of it as a rail line: each stop confirms you are still on the right route before the next one.

      -

      Alex: Treat examples as spoken recipes, not decorations. You may hear something like Merge with default strategy; gh pr merge 42; Squash and merge, then delete the branch; gh pr merge 42 --squash --delete-branch; Enable auto-merge (merges when checks pass); gh pr merge 42 --auto --squash. Read the command, understand what it changes, then run it only when the repository state matches the lesson.

      +

      Jamie: Let's pause on 8. Capstone Rubric. What should a learner take away from it?

      +

      Alex: Start with 8. Capstone Rubric: The capstone is worth 60 autograded points plus peer review.

      +

      Alex: Keep the teaching thread moving. Here is the plain-English version of What "meets expectations" looks like. A capstone that meets expectations has.

      +

      Alex: The practical takeaway is this. A focused mission (not "help with accessibility" -- something specific). At least 3 concrete responsibilities. At least 3 meaningful guardrails. A PR description that explains the agent's purpose. All autograder checks passing.

      +

      Jamie: Let's pause on What "exceeds expectations" looks like. What should a learner take away from it?

      +

      Alex: This is where What "exceeds expectations" looks like becomes real: a capstone that exceeds expectations also has.

      +

      Alex: The practical takeaway is this. Examples of expected input and output in the agent instructions. A section describing the agent's limitations. Evidence of testing (screenshots or transcripts in the PR description). Thoughtful responses to review feedback.

      -

      Jamie: Let's pause on Learning Cards: Merging Pull Requests. What should a learner take away from it?

      -

      Alex: Start with Learning Cards: Merging Pull Requests. There is something to understand, something to try, and something that proves the try worked.

      -

      Alex: The practical takeaway is this. The merge type selector (Merge Commit, Squash, Rebase) is announced as a dropdown or radio group -- use Arrow keys to move between options and Enter to confirm; if unsure, choose Merge Commit (the default and safest option). After merging, VS Code prompts "Delete branch?" as a notification -- press Alt+N to focus the notification and Enter to confirm, then run Ctrl+Shift+P then "Git: Checkout to" and select main to return to your default branch. Confirm the merge succeeded by pressing F6 to reach the Status Bar and verifying it now reads main instead of the feature branch name. The merge button at the bottom of the PR detail view includes a dropdown arrow for selecting merge type -- at high zoom, widen the editor pane so the button label and dropdown are not truncated. After merging, the PR detail view header changes from "Open" (green badge) to "Merged" (purple badge) -- verify this colour/label change before deleting the branch. When switching back to main, the branch name in the bottom-left Status Bar updates immediately -- confirm it reads main before pulling new changes with Ctrl+Shift+P then "Git: Pull".

      -

      Alex: Keep the teaching thread moving. Here is the plain-English version of "No pull requests found". Issue: The GitHub Pull Requests panel is empty.

      -

      Jamie: Let's pause on Solutions. What should a learner take away from it?

      -

      Alex: Start with Solutions. There is something to understand, something to try, and something that proves the try worked.

      -

      Alex: First, verify you're signed in: Ctrl+Shift+P (Mac: Cmd+Shift+P) → "GitHub Pull Requests: Sign in". Then, check you have a folder open containing a Git repository. After that, refresh the panel: Ctrl+Shift+P (Mac: Cmd+Shift+P) → "GitHub Pull Requests: Refresh Pull Requests List". It is a checklist, but a meaningful one: every item creates evidence that the next step is safe.

      +

      Alex: Keep the teaching thread moving. Keep the learner anchored in 9. Example Agents for Inspiration. These examples show the range of valid agent designs. This is the part to say slowly: Your agent does not need to be this long, but it should be this clear. A good GitHub workflow is like a well-run meeting: everyone knows the topic, the next action, and who has the floor.

      +

      Jamie: Let's pause on Example 1: Heading Hierarchy Checker. What should a learner take away from it?

      +

      Alex: The reason Example 1: Heading Hierarchy Checker matters is that mission: Validates that HTML and Markdown documents follow a correct heading hierarchy (no skipped levels).

      +

      Alex: The practical takeaway is this. Scan files for heading elements (h1 through h6 in HTML, through in Markdown). Report any instance where a heading level is skipped (e.g., h2 followed by h4). Suggest the correct heading level for each violation. Check that there is exactly one h1 per page. Do not modify files -- only report findings. Do not change heading text, only heading levels.

      +

      Alex: A solid navigation habit is to prove where you are before activating controls. Headings, landmarks, and the address bar are not trivia; they are your map.

      +

      Alex: Keep the teaching thread moving. Start with Example 2: PR Description Quality Gate: Mission: Reviews pull request descriptions to ensure they contain enough context for reviewers.

      +

      Alex: The practical takeaway is this. Check that the PR description is at least 50 characters. Verify the description references an issue with Closes XX or Fixes XX. Check for a summary of changes made. Verify the description explains why the change was made, not just what was changed. Never approve or block a PR based solely on description quality. Do not rewrite the description for the author -- suggest improvements.

      -

      Jamie: Before we leave Solutions, what is the practical point?

      -

      Alex: First, verify you've pushed your branch: Ctrl+Shift+P (Mac: Cmd+Shift+P) → "Git: Push". Then, check you have write access to the repository. After that, ensure your branch is ahead of the base branch (has new commits). It is like walking a hallway with named doors: read the sign, enter the right room, then confirm where you landed.

      -

      Jamie: Let's pause on "Authentication failed". What should a learner take away from it?

      -

      Alex: The reason "Authentication failed" matters is that issue: VS Code can't connect to GitHub.

      -

      Jamie: What is the teaching move inside Solutions?

      -

      Alex: First, sign out and sign back in: Ctrl+Shift+P (Mac: Cmd+Shift+P) → "GitHub Pull Requests: Sign out" → then sign in again. Then, check your GitHub Personal Access Token (see Appendix D: Git Authentication). After that, verify network connection. Think of it as a rail line: each stop confirms you are still on the right route before the next one.

      +

      Jamie: Let's pause on Example 3: Keyboard Navigation Auditor. What should a learner take away from it?

      +

      Alex: Here is the plain-English version of Example 3: Keyboard Navigation Auditor. Mission: Checks web components for keyboard accessibility compliance.

      +

      Alex: The practical takeaway is this. Verify all interactive elements are reachable via Tab key. Check that custom components have appropriate tabindex values. Validate that focus order follows visual layout. Detect keyboard traps (elements that receive focus but cannot release it via keyboard). Do not modify component code without user approval. Flag potential issues with confidence levels (certain, likely, possible).

      +

      Alex: Keep the teaching thread moving. This is where The universal safety net becomes real: if everything else fails, post this on your challenge issue. That matters in practice: I attempted Challenge 16 and here is what happened: What I tried: [specific actions] What I expected: [what should have happened] What actually happened: [error or unexpected result] What I learned: [even from failure, what do I understand now?]. The workshop is closer to rehearsal than lecture. You hear the move, try the move, and then check what changed.

      -

      Jamie: Let's pause on Try It: Review a PR from VS Code. What should a learner take away from it?

      -

      Alex: Here is the plain-English version of Try It: Review a PR from VS Code. Time: 3 minutes What you need: VS Code with GitHub Pull Requests extension installed and signed in. Put another way, you just reviewed a pull request entirely from VS Code.

      -

      Alex: First, open the PR view - Press Ctrl+Shift+P → type Pull Requests: Focus on GitHub Pull Requests View → Enter. Then, find a PR - Navigate the tree with arrow keys. Expand a PR to see its changed files. After that, open a diff - Press Enter on a changed file. The diff editor opens. Finally, use the Accessible Diff Viewer - Press F7 to jump to the first change. Your screen reader announces what was added or removed. Press F7 again to move to the next change. Treat it like a recipe: do not add the next ingredient until the previous one is actually in the bowl.

      -

      Jamie: Before we leave Try It: Review a PR from VS Code, what is the practical point?

      -

      Alex: First, leave a comment - Position your cursor on a line you want to comment on, then press Ctrl+Shift+P → Pull Request: Add Comment on Current Diff Line. Type a brief, constructive comment and submit. It is a checklist, but a meaningful one: every item creates evidence that the next step is safe.

      -

      Alex: Keep the teaching thread moving. This is where Conducting Pull Request Reviews with a Screen Reader becomes real: this guide is focused entirely on the reviewer experience - navigating diffs, reading changes, leaving comments, and submitting a review - using only your keyboard and screen reader. That matters in practice: For the full pull request lifecycle (opening PRs, merge options, conflict resolution), see Working with Pull Requests. The workshop is closer to rehearsal than lecture. You hear the move, try the move, and then check what changed.

      -

      Jamie: Where does the workshop stop being a tour and start becoming contribution?

      -

      Alex: Keep the learner anchored in Workshop Recommendation (Chapter 15 / Challenge 12). Chapter 15 is the code review chapter focused on practicing constructive feedback. This is the part to say slowly: It supports Challenge 12: Review Like a Pro.

      -

      Alex: The practical takeaway is this. There are 2 guided challenges. Automation check: none (review quality is subjective and human-focused). The evidence is issue comment with summary of review and feedback posted. The pattern is navigate diff, comment on specifics, submit verdict.

      +

      Jamie: What should people carry with them after this?

      +

      Alex: Carry the map. Know what page or tool you are in, know which action you are taking, and know what confirmation should follow. If the confirmation is missing, pause. That pause is not wasted time; it is professional judgment.

      +

      Jamie: That is a better way to say it than just follow the steps.

      +

      Alex: Right. Steps matter, but understanding wins. That is episode 48. Next in the series is episode 49, where we keep building the same contributor muscles.

      +
      +
      -

      Jamie: Let's pause on Challenge 12 Practice Set. What should a learner take away from it?

      -

      Alex: Start with Challenge 12 Practice Set. There is something to understand, something to try, and something that proves the try worked.

      -

      Alex: First, review a practice PR and leave 2-3 inline comments - read the diff line by line, find specific items to comment on, and post constructive feedback. Then, submit a formal review verdict - complete your review by choosing approve, request changes, or comment only. The rhythm is simple: orient, act, verify, then continue.

      -

      Jamie: Let's pause on Practice 12.1 Step-by-Step: Review a PR and Leave Inline Comments. What should a learner take away from it?

      -

      Alex: Start with Practice 12.1 Step-by-Step: Review a PR and Leave Inline Comments: Navigate a PR diff using screen reader-friendly tools and post 2-3 specific, constructive inline comments. The next useful detail is this: GitHub.com (Files changed tab of a PR) or VS Code with the GitHub Pull Requests extension.

      -

      Alex: The practical takeaway is this. On GitHub.com: Use heading navigation to jump between files (H in NVDA). Each file header is a heading. Within a file, use arrow keys to move line by line. In VS Code: Press F7 to open the Accessible Diff Viewer (see Chapter 15, Part 1). Use F7/Shift+F7 to move between changes. Typos or grammar issues. Unclear headings or link text.

      -

      Alex: First, open your Learning Room repository on GitHub.com and navigate to the Pull requests tab. Then, find a classmate's open PR (from Chapter 6, 7, or 14). Open it. After that, activate the Files changed tab. This shows the diff - lines added in green, lines removed in red. Finally, navigate the diff. Think of it as a rail line: each stop confirms you are still on the right route before the next one.

      -

      Jamie: Before we leave Practice 12.1 Step-by-Step: Review a PR and Leave Inline Comments, what is the practical point?

      -

      Alex: First, read through the changes carefully. Look. Then, to leave an inline comment on GitHub.com: activate the + button that appears to the left of a line number when you hover or Tab to it. (Screen reader users: this button may be announced as "Add a comment to this line.") Type your comment in the text box that. After that, post 2-3 inline comments. Each comment should be. Finally, examples of good inline comments. Treat it like a recipe: do not add the next ingredient until the previous one is actually in the bowl.

      -

      Jamie: Let's pause on Practice 12.2 Step-by-Step: Submit a Formal Review Verdict. What should a learner take away from it?

      -

      Alex: Here is the plain-English version of Practice 12.2 Step-by-Step: Submit a Formal Review Verdict. Complete your review by selecting a verdict that tells the author what action to take next. Put another way, GitHub.com (the same PR you reviewed in 14.1). It is like learning a transit route. The names of the stops matter because they tell you whether you are still going the right direction.

      -

      Alex: The practical takeaway is this. Comment - general feedback, no explicit approval or rejection. Approve - you think the PR is ready to merge. Request changes - you found something that should be fixed before merging. If the PR has clear documentation with only minor suggestions, choose Approve.

      -

      Alex: First, after posting your inline comments, scroll to the top of the Files changed tab. Then, activate the Review changes button (at the top-right of the files changed area, or use heading navigation). After that, a dropdown opens with three options. Finally, choose the verdict that matches your review. Treat it like a recipe: do not add the next ingredient until the previous one is actually in the bowl.

      -

      Jamie: Before we leave Practice 12.2 Step-by-Step: Submit a Formal Review Verdict, what is the practical point?

      -

      Alex: First, write a brief summary in the review body (1-2 sentences). Example: "Clear improvement to the shortcut table. Two minor suggestions for link text clarity.". Then, activate Submit review. It is a checklist, but a meaningful one: every item creates evidence that the next step is safe.

      +

      52. Challenge 16: Build Your Agent (Capstone)

      +

      Designing an agent, writing responsibilities and guardrails, and preparing a contribution.

      +

      Practice focus: Day 2 capstone

      +

      Audio and transcript are being regenerated for this episode.

      +
      +Read Transcript - Challenge 16: Build Your Agent (Capstone) + +

      Transcript

      +

      Alex: Welcome to Challenge Coach: Build Your Agent (Capstone). I am Alex. Before you do the task, we are going to make the skill feel concrete enough to practice.

      +

      Jamie: And I am Jamie. I will keep asking what the learner should do, what evidence counts, and how to recover if the page does something unexpected.

      -

      Jamie: What should the learner prove to themselves after each small task?

      -

      Alex: This is where Completing Challenge 12: Submit Your Evidence becomes real: open your assigned Challenge 12 issue and post a completion comment. That matters in practice: Close your Challenge 12 issue when done.

      -

      Alex: Keep the teaching thread moving. Start with Expected Outcomes. There is something to understand, something to try, and something that proves the try worked.

      -

      Alex: The practical takeaway is this. Student can navigate PR diffs with a screen reader. Student can post inline comments on specific lines of a diff. Student can write constructive, specific feedback that helps the author improve. Student can submit a formal review verdict.

      -

      Jamie: What is the teaching move inside If You Get Stuck?

      -

      Alex: The reason If You Get Stuck matters is that continue learning: The GitHub Skills courses Review Pull Requests and Code Review with GitHub Copilot cover review workflows and AI-assisted code review. That gives the learner a simple foothold: see Appendix Z for the full catalog.

      -

      Alex: First, files Changed tab will not open? Reload the PR page and retry. Make sure you are on the PR page, not the issue page. Then, cannot find the inline comment button? Tab through the line controls in the diff. The button may be announced as "Add a comment" or have a + label. If you cannot find it, use the "Review changes" button at the top to add a general comment instead. After that, not sure what to comment on? Focus on clarity: is every heading descriptive? Is every link meaningful? Are steps complete? Are keyboard shortcuts correct? Finally, review verdict button not working? Make sure you have at least one comment or have written summary text. Try reloading the page. The rhythm is simple: orient, act, verify, then continue.

      -

      Jamie: If someone only remembers one thing from If You Get Stuck, what should it be?

      -

      Alex: First, submitting the review fails? Check that you are not in draft mode and have at least read access to the repo. Then, ask facilitator to model one inline comment and one verdict submission. After that, finished but not sure you did it right? Compare your work against the Challenge 12 reference solution. Think of it as a rail line: each stop confirms you are still on the right route before the next one.

      +

      Alex: The skill focus is Designing an agent, writing responsibilities and guardrails, and preparing a contribution. This is rehearsal for real contribution, so the evidence matters because it proves the move happened.

      +

      Jamie: So the challenge has to leave the learner with both confidence and a trail of evidence.

      +

      Alex: Exactly. Evidence is not busywork. It is how a learner, a facilitator, and a future maintainer can understand what changed and why.

      -

      Alex: Keep the teaching thread moving. Start with Learning Moment: Specific, kind feedback helps authors improve and builds trust in the community. The next useful detail is this: Every comment you write is practice for the professional code review you will do on real projects. Think of it like entering a new building: first you find the lobby, then the room, then the door you actually need.

      -

      Jamie: Before we leave Learning Pattern Used in This Chapter, what is the practical point?

      -

      Alex: First, read the full diff before commenting (understand the author's intent first). Then, find specific items to comment on (lines, phrases, missing steps). After that, write comments that help, not just criticize (suggest improvements, note what works). Finally, choose a verdict that matches the substance of your feedback. Treat it like a recipe: do not add the next ingredient until the previous one is actually in the bowl.

      -

      Jamie: What is the teaching move inside Learning Pattern Used in This Chapter?

      -

      Alex: First, summarize your overall impression in 1-2 sentences. It is a checklist, but a meaningful one: every item creates evidence that the next step is safe.

      -

      Alex: Keep the teaching thread moving. This is where Before starting this chapter, verify you have completed becomes real: estimated time for this chapter: 1 hour (including exercises).

      -

      Alex: The practical takeaway is this. [ ] Chapter 6: Working with Pull Requests - Understand PR structure, diffs, and comment workflows. [ ] Chapter 13: GitHub Copilot - VS Code installed and configured. [ ] Screen Reader Setup - NVDA, JAWS, or VoiceOver installed and ready to use. [ ] Access to at least one pull request to review (your own fork or a practice repo).

      +

      Jamie: What makes this practice feel low-stakes but still real?

      +

      Alex: Start with Challenge 16: Build Your Agent (Capstone): What you will do: This is the capstone project. The next useful detail is this: the learner will fork the accessibility-agents repository, write your own agent file, open a cross-fork pull request, and review a peer or facilitator-seeded agent.

      +

      Jamie: How would you walk the room through that step by step?

      +

      Alex: Start with Phase 1: Fork. There is something to understand, something to try, and something that proves the try worked.

      +

      Alex: First, go to the accessibility-agents repository. Then, select Fork to create your own copy. After that, clone your fork to your local machine. Treat it like a recipe: do not add the next ingredient until the previous one is actually in the bowl.

      +

      Jamie: What does the learner do first, second, and then after that?

      +

      Alex: Start with Phase 2: Branch. There is something to understand, something to try, and something that proves the try worked.

      +

      Alex: First, create a branch named agent/YOUR-USERNAME for your work. It is a checklist, but a meaningful one: every item creates evidence that the next step is safe.

      +

      Alex: A solid Git habit is to know which branch you are on, what changed, and what confirmation you expect before you run the next command.

      -

      Jamie: Let's pause on Two Environments for Code Review. What should a learner take away from it?

      -

      Alex: Keep the learner anchored in Two Environments for Code Review. You can review pull requests in two places - each with different strengths. This is the part to say slowly: Both environments give you full keyboard and screen reader access.

      -

      Jamie: What is the safe way to learn from that example?

      -

      Alex: The reason About Learning Cards in This Chapter matters is that each review step includes expandable learning cards for different interaction styles. That gives the learner a simple foothold: open the one that matches how you work. The interface gets friendlier when it stops being a wall of controls and starts being a set of named places.

      -

      Alex: Treat examples as spoken recipes, not decorations. You may hear something like View the full PR diff in your terminal; gh pr diff 42; View PR details (description, status, checks); gh pr view 42; Checkout the PR branch locally for testing; gh pr checkout 42; Approve the PR; gh pr review 42 --approve --body "Heading hierarchy looks. Read the command, understand what it changes, then run it only when the repository state matches the lesson.

      -

      Jamie: Let's pause on Good News: Modern Interface is Default. What should a learner take away from it?

      -

      Alex: Start with Good News: Modern Interface is Default: As of January 2026, GitHub's improved Files Changed experience is enabled by default. The next useful detail is this: The instructions below assume you have the modern interface (which you do).

      +

      Jamie: Turn that into a path someone can follow.

      +

      Alex: Start with Phase 3: Write your agent. There is something to understand, something to try, and something that proves the try worked.

      +

      Alex: For a learner, the useful signals are these. Valid YAML frontmatter with name, description, and at least one tools entry. Responsibilities section -- 3-5 bullet points describing what your agent does. Guardrails section -- 2-3 bullet points describing what your agent should NOT do.

      +

      Alex: First, create a new file: agents/YOUR-AGENT-NAME.agent.md. Then, your agent file must. It is like walking a hallway with named doors: read the sign, enter the right room, then confirm where you landed.

      +

      Jamie: What is the ordered workflow?

      +

      Alex: Start with Phase 4: Open a cross-fork PR. There is something to understand, something to try, and something that proves the try worked.

      +

      Alex: First, commit your agent file and push to your fork. Then, go to the original accessibility-agents repository. After that, open a pull request from your fork's branch to the original repo's main branch. Finally, write a PR description that explains your agent's purpose. The rhythm is simple: orient, act, verify, then continue.

      +

      Alex: A solid pull request habit is to separate three questions: what changed, why it changed, and what still needs review. That keeps the conversation useful instead of noisy.

      +

      Jamie: Give me the sequence, because order matters here.

      +

      Alex: Start with Phase 5: Peer review: Autograded: The autograder verifies that your agent file exists, has valid YAML frontmatter, and contains both responsibilities and guardrails sections. The next useful detail is this: I reviewed a peer or peer-simulation PR because. Think of it like entering a new building: first you find the lobby, then the room, then the door you actually need.

      +

      Alex: First, review a classmate's capstone PR if facilitator access is available. If not, review the peer-simulation PR and explain what you would look for in an agent PR. Then, check: Does their agent have responsibilities? Guardrails? Valid YAML? Think of it as a rail line: each stop confirms you are still on the right route before the next one.

      -

      Jamie: Let's pause on Step 1: Reach the Files Changed Tab. What should a learner take away from it?

      -

      Alex: Here is the plain-English version of Step 1: Reach the Files Changed Tab. Click the Files changed tab at the top of the PR page. Put another way, the tab label shows the number of changed files (e.g., "Files changed 4").

      -

      Alex: First, the PR tabs (Conversation, Commits, Checks, Files changed) are across the top of the PR page. At high zoom they may wrap to multiple lines. Then, the Files changed tab includes a badge with the number of changed files. This badge uses text (not colour alone) so it is visible in all themes. After that, after clicking Files changed, the diff page loads. At high zoom, the file tree panel on the left may collapse automatically. Click the file tree toggle (a small panel icon) or press T to toggle it back. Finally, added lines use a green background; removed lines use red. In high contrast browser settings (Windows: Settings Accessibility Contrast themes), these colours map to strong border indicators. Treat it like a recipe: do not add the next ingredient until the previous one is actually in the bowl.

      -

      Jamie: Before we leave Step 1: Reach the Files Changed Tab, what is the practical point?

      -

      Alex: First, use Ctrl++ to zoom the browser if the diff text is too small, and Ctrl+- to zoom out. It is a checklist, but a meaningful one: every item creates evidence that the next step is safe.

      -

      Alex: Treat examples as spoken recipes, not decorations. You may hear something like Press D → navigate to "Pull request navigation tabs" landmark; Press → or Tab → find "Files changed" link → Enter. Read the command, understand what it changes, then run it only when the repository state matches the lesson.

      -

      Jamie: Let's pause on Step 2: Use the File Tree to Orient Yourself. What should a learner take away from it?

      -

      Alex: This is where Step 2: Use the File Tree to Orient Yourself becomes real: the file tree panel lists every changed file. That matters in practice: Before reading any diff, scan this list to understand the scope of the PR.

      -

      Jamie: Let's pause on What to listen for / look for. What should a learner take away from it?

      -

      Alex: Keep the learner anchored in What to listen for / look for. Low vision users (zoom, high contrast). A good GitHub workflow is like a well-run meeting: everyone knows the topic, the next action, and who has the floor.

      -

      Alex: The practical takeaway is this. How many files changed? Which areas of the codebase are affected? Are there unexpected files (generated files, lock files, configuration changes)?

      -

      Alex: First, the file tree shows each filename with a colour-coded bar indicating lines added (green) and removed (red). In high contrast mode, these bars may be less visible - the +N / -N text badge next to each file is the reliable indicator. Then, at high zoom, long file paths truncate. Hover over a truncated name to see the full path in a tooltip. After that, if the file tree panel is too narrow at high zoom, drag its right edge to widen it, or toggle it off and use heading navigation (H key) to move between file diffs. It is like walking a hallway with named doors: read the sign, enter the right room, then confirm where you landed.

      +

      Jamie: Okay, set the room for us. What are we walking into?

      +

      Alex: Here is the plain-English version of Peer simulation check. Review a peer agent if access is available. Put another way, if not, use the peer-simulation PR to practice review language, then describe what you would check in an agent PR.

      +

      Alex: The useful habit is simple: orient first, act second, verify third. That pause before acting is part of the work.

      +

      Alex: This is where the talk moves from concept to action. This is where Example agent file becomes real: file: community-agents/workshop-buddy.agent.md.

      +

      Jamie: What is the one idea that makes the next few steps less mysterious?

      +

      Alex: Keep the learner anchored in Alternate valid agents. Other examples students have built.

      +

      Alex: These are the details that keep the idea from floating away. An agent that reviews Markdown formatting. An agent that checks issue titles for clarity. An agent that recommends which Git command to use. An agent that explains error messages.

      -

      Jamie: What should happen before anyone copies and runs it?

      -

      Alex: The reason Step 3: Navigate Between File Diffs matters is that each changed file in the main area is an h3 heading containing the filename. That gives the learner a simple foothold: scroll through the page or click a filename in the file tree on the left.

      -

      Alex: Treat examples as spoken recipes, not decorations. You may hear something like Press 3 to jump file-by-file through the diff; Listen for: "learning-room/docs/keyboard-shortcuts.md - collapsed" or "expanded"; Press Enter or Space to expand a collapsed file. Quick Nav H or VO+Cmd+H to jump file-by-file through the diff; Listen for: "learning-room/docs/keyboard-shortcuts.md - collapsed" or "expanded"; VO+Space to expand a collapsed file. Read the command, understand what it changes, then run it only when the repository state matches the lesson.

      -

      Jamie: Let's pause on Step 4: Read a Diff. What should a learner take away from it?

      -

      Alex: Start with Step 4: Read a Diff: Low vision users (zoom, high contrast). The next useful detail is this: Screen reader users - VoiceOver (macOS).

      -

      Alex: The practical takeaway is this. Green highlighted lines (with a +) = lines added. Red highlighted lines (with a -) = lines removed. Plain/white lines = unchanged context. Use Ctrl+F to search within the page for specific text in the diff.

      -

      Alex: First, colour is not the only indicator. Every added line has a + character in the gutter; every removed line has a -. These text characters are reliable regardless of colour settings. Then, at high zoom, long lines of code wrap. The +/- gutter character stays at the beginning of the first line, so look left to determine the change type. After that, use Ctrl+F (browser find) to search for specific text across the entire diff page. Finally, if the diff is split view (side by side), it may be very wide at high zoom. Switch to unified diff mode: click the gear icon in the Files Changed toolbar and select "Unified" - this shows old and new in a single column. Think of it as a rail line: each stop confirms you are still on the right route before the next one.

      -

      Jamie: Before we leave Step 4: Read a Diff, what is the practical point?

      -

      Alex: First, high contrast themes in Windows (Settings Accessibility Contrast themes) make the +/- lines use bold border patterns instead of subtle colour shading. Treat it like a recipe: do not add the next ingredient until the previous one is actually in the bowl.

      -

      Alex: Treat examples as spoken recipes, not decorations. You may hear something like Press T to jump to the diff table then Insert+Space (Focus Mode); Press Down Arrow to move through lines one at a time; Press Ctrl+Alt+Right Arrow to read across columns: line number, change type, code content. Press T to jump to the diff table then Insert+Z (Virtual PC Cursor off); Press Down Arrow to move through lines; Press Ctrl+Alt+Right Arrow for column-by-column reading. Read the command, understand what it changes, then run it only when the repository state matches the lesson.

      -

      Jamie: Let's pause on What each line announces / shows. What should a learner take away from it?

      -

      Alex: Here is the plain-English version of What each line announces / shows. If the code on a line is very long, the screen reader will read the full line. Put another way, for minified or generated files, consider collapsing the file in the tree and skipping it.

      -

      Alex: The practical takeaway is this. Added lines: "+ [code content]" - or announced as "inserted". Removed lines: "- [code content]" - or announced as "deleted". Context lines: code without a + or -.

      +

      Alex: Before the learner moves on. The reason What matters matters is that the learning objective is understanding that AI agents are defined by their responsibilities AND their guardrails. That gives the learner a simple foothold: if your agent file has valid YAML frontmatter, a clear purpose, and explicit boundaries, you completed this challenge. The interface gets friendlier when it stops being a wall of controls and starts being a set of named places.

      +

      Jamie: Let's pause on 1. The Capstone Challenge. What should a learner take away from it?

      +

      Alex: Start with 1. The Capstone Challenge: The capstone is Challenge 16 -- the final challenge of the workshop. The next useful detail is this: Your pull request goes to a real repository.

      +

      Alex: First, choose a mission for a new accessibility agent (or improve an existing one). Then, write an agent file with valid YAML frontmatter. After that, define clear responsibilities and guardrails. Finally, test the agent locally with GitHub Copilot. Think of it as a rail line: each stop confirms you are still on the right route before the next one.

      +

      Jamie: Before we leave 1. The Capstone Challenge, what is the practical point?

      +

      Alex: First, open a pull request from your fork to the upstream repository. Then, respond to peer review feedback. Treat it like a recipe: do not add the next ingredient until the previous one is actually in the bowl.

      +

      Alex: Hold that next to this. Start with What you need before starting. There is something to understand, something to try, and something that proves the try worked.

      +

      Alex: The practical anchors are these. [ ] You have forked and cloned the accessibility-agents repository (Chapter 18). [ ] You have a feature branch created: agents/your-username-agent-name. [ ] You understand how to push to your fork and open a PR (Chapter 18). [ ] You have GitHub Copilot or Copilot Free active (Chapter 16). [ ] You have explored the existing agents in Chapter 19.

      -

      Jamie: Let's pause on Step 5: Place an Inline Comment. What should a learner take away from it?

      -

      Alex: This is where Step 5: Place an Inline Comment becomes real: when you have a specific observation about a particular line, place an inline comment directly on it. That matters in practice: Screen reader users (VoiceOver - macOS). The workshop is closer to rehearsal than lecture. You hear the move, try the move, and then check what changed.

      -

      Alex: First, hover your mouse over a line in the diff - a blue + (comment) button appears on the left. Then, click it to open the inline comment box. After that, type your comment. Finally, click "Start a review" (not "Add single comment" - see note below). It is a checklist, but a meaningful one: every item creates evidence that the next step is safe.

      -

      Jamie: Let's pause on Placing a multi-line comment. What should a learner take away from it?

      -

      Alex: Keep the learner anchored in Placing a multi-line comment. Click and drag across multiple line numbers in the diff gutter to select a range. This is the part to say slowly: A comment button appears for the selected range.

      -

      Jamie: Let's pause on Step 6: Read Existing Comments and Threads. What should a learner take away from it?

      -

      Alex: The reason Step 6: Read Existing Comments and Threads matters is that inline comments from other reviewers appear as h3 headings within the diff table. That gives the learner a simple foothold: each thread shows: reviewer username, comment body, replies, a "Reply" link and resolution button.

      -

      Alex: Treat examples as spoken recipes, not decorations. You may hear something like Tab to the "Resolve conversation" button → Enter. Tab to the "Resolve conversation" button → VO+Space. Read the command, understand what it changes, then run it only when the repository state matches the lesson.

      +

      Jamie: If I am listening before the workshop starts, what should settle in my mind first?

      +

      Alex: This is where Time estimate becomes real: most students complete the capstone in 60 to 90 minutes. That matters in practice: The phases are designed so you can get a working agent in 30 minutes and spend the remaining time improving it.

      +

      Alex: That connects to another useful point. Keep the learner anchored in 2. Phase 1: Choose Your Agent's Mission. See also: Chapter 19: Accessibility Agents introduces the agent ecosystem and shows existing agents for inspiration. A good GitHub workflow is like a well-run meeting: everyone knows the topic, the next action, and who has the floor.

      +

      Jamie: Where do you want a learner to place their attention here?

      +

      Alex: The reason What makes a good agent mission matters is that a good agent solves a specific, recurring problem.

      +

      Alex: The parts worth keeping in working memory are these. What task do you repeat? Think about workflow steps from Day 1 and Day 2 that felt repetitive. What would a specialist know? An agent works best when it has deep knowledge of a focused area. What gap exists? Look at the existing agents in Chapter 19. Is there a workflow that no agent covers?

      -

      Jamie: Let's pause on Step 7: Submit Your Review. What should a learner take away from it?

      -

      Alex: Start with Step 7: Submit Your Review: Screen reader users (VoiceOver - macOS).

      -

      Alex: First, click the "Review changes" button (top-right of the Files Changed page or bottom of the PR). Then, a dialog opens with a summary text area and three radio buttons: Comment / Approve / Request changes. After that, optionally type an overall summary in the text area. Finally, select your verdict. Think of it as a rail line: each stop confirms you are still on the right route before the next one.

      -

      Jamie: Before we leave Step 7: Submit Your Review, what is the practical point?

      -

      Alex: First, click "Submit review". Treat it like a recipe: do not add the next ingredient until the previous one is actually in the bowl.

      -

      Jamie: Let's pause on Step 8: Re-request Review (for Authors). What should a learner take away from it?

      -

      Alex: Here is the plain-English version of Step 8: Re-request Review (for Authors). After you address review comments on your own PR. Put another way, look in the right sidebar for the Reviewers section. It is like learning a transit route. The names of the stops matter because they tell you whether you are still going the right direction.

      -

      Alex: Treat examples as spoken recipes, not decorations. You may hear something like Step 1: From your PR's Conversation tab, Quick Nav H or VO+Cmd+H to find the "Reviewers" heading in the sidebar; Step 2: Tab or Quick Nav B to find the re-request icon ("Re-request review") next to the reviewer's name; Step 3: VO+Space to activate - this. Read the command, understand what it changes, then run it only when the repository state matches the lesson.

      -

      Jamie: Let's pause on Learning Cards: Reviewing on GitHub.com. What should a learner take away from it?

      -

      Alex: Start with Learning Cards: Reviewing on GitHub.com. There is something to understand, something to try, and something that proves the try worked.

      -

      Alex: The practical takeaway is this. In the Files Changed tab, press T to jump to the diff table, then use Focus Mode (Insert+Space in NVDA, Insert+Z in JAWS) and Down Arrow to read line by line -- each added line starts with + and each removed line with -. To place an inline comment, navigate to the target line and press Tab or B to find the "Add a comment to this line" button; after typing your comment, choose "Start a review" (not "Add single comment") to batch all feedback into one notification. Submit your full review by pressing B repeatedly to find the "Review changes" button; the dialog contains a radio group (Comment / Approve / Request changes) navigable with Arrow keys, then Tab to "Submit review". Switch from split diff to unified diff (gear icon in the Files Changed toolbar then select "Unified") to show old and new code in a single column -- much easier to follow at high zoom than two side-by-side panes. The blue + comment button appears in the line gutter on hover; at high zoom it may be small -- use Ctrl++ to increase browser zoom and look just left of the line number column. The "Review changes" dialog uses clearly labeled radio buttons for the three verdict types; each label includes a brief description, and the currently selected option has a filled circle indicator visible in all themes.

      +

      Alex: Here is the practical turn. Start with Write your mission statement: Before writing any code, write a one-sentence mission statement. The next useful detail is this: "My agent helps [who] by [doing what] when [in what situation].".

      +

      Jamie: What would you say to someone who is already bracing for this to be too much?

      +

      Alex: Here is the plain-English version of 3. Phase 2: Write the Agent File. An agent file is a Markdown file with YAML frontmatter that defines the agent's identity, and a body that contains the agent's instructions. Put another way, agent files live in the.github/agents/ directory (for GitHub Copilot agents) or in team-specific directories in the accessibility-agents repository.

      +

      Alex: Keep the thread going. This is where File location and naming becomes real: example.github/agents/alt-text-validator.md. The workshop is closer to rehearsal than lecture. You hear the move, try the move, and then check what changed.

      -

      Alex: Keep the teaching thread moving. Keep the learner anchored in Reviewing in VS Code with the Accessible Diff Viewer. When you check out a branch locally, VS Code's diff editor offers the Accessible Diff Viewer - a purpose-built, line-by-line reading mode designed specifically for screen readers.

      -

      Jamie: Let's pause on Opening a Diff in VS Code. What should a learner take away from it?

      -

      Alex: The reason Opening a Diff in VS Code matters is that if you have the GitHub Pull Requests extension. That gives the learner a simple foothold: without the extension, any git diff operation also opens the diff editor.

      -

      Alex: First, open the GitHub Pull Requests view (Explorer sidebar or Ctrl+Shift+P → "GitHub Pull Requests: View Pull Request"). Then, find the PR and open it - changed files appear in the file tree. After that, navigate to any file in the tree and press Enter to open its diff view. The rhythm is simple: orient, act, verify, then continue.

      -

      Jamie: Let's pause on Learning Cards: VS Code Code Review. What should a learner take away from it?

      -

      Alex: Start with Learning Cards: VS Code Code Review: Low vision users (zoom, high contrast). The next useful detail is this: VS Code's diff editor works well at high zoom. Think of it like entering a new building: first you find the lobby, then the room, then the door you actually need.

      -

      Alex: First, split view vs. inline: By default, VS Code shows diffs in a split (side-by-side) view. At high zoom this can be very cramped. Switch to inline mode: Ctrl+Shift+P then type "Toggle Inline View" in any diff editor. Inline mode shows old and new code in a single. Then, colour indicators: Added lines have a green gutter bar; removed lines have a red gutter bar. In high contrast themes, these use heavy solid borders that are visible even at extreme zoom levels. After that, change navigation: Press F7 to jump to the next change and Shift+F7 for the previous. Each change is highlighted with a visible focus box that moves with your position - much easier than scrolling at high zoom. Finally, minimap in diff view: The minimap (right edge) shows an overview of changes as coloured blocks. At high zoom the minimap may be too small to be useful - disable it via Settings if it adds visual noise. Think of it as a rail line: each stop confirms you are still on the right route before the next one.

      -

      Jamie: Before we leave Learning Cards: VS Code Code Review, what is the practical point?

      -

      Alex: First, font size for diffs: Diff editors use your configured editor font size (editor.fontSize). Increase this in Settings (Ctrl+,) if the diff text is too small at your zoom level. Then, comment highlight: When you add a comment through the GitHub PR extension, the commented line gets a distinct background. In high contrast themes this is a solid colour band. Treat it like a recipe: do not add the next ingredient until the previous one is actually in the bowl.

      +

      Jamie: Let's pause on The agent file structure. What should a learner take away from it?

      +

      Alex: Start with The agent file structure. There is something to understand, something to try, and something that proves the try worked.

      +

      Alex: First, yAML frontmatter -- metadata between --- markers at the top of the file. Then, instructions body -- Markdown content that tells the agent how to behave. It is like walking a hallway with named doors: read the sign, enter the right room, then confirm where you landed.

      +

      Alex: Another way to ground it. The reason YAML frontmatter fields matters is that vague descriptions result in missed automatic routing. That gives the learner a simple foothold: weak: Helps with accessibility - Strong: Checks markdown files for accessibility issues, fixes descriptive links and heading hierarchy, and flags alt text for human review The more specific the description, the more reliably Copilot invokes the right agent for.

      +

      Jamie: Give me the version that sounds like an instructor, not a manual.

      +

      Alex: Start with Writing the instructions body: The instructions body tells the agent how to behave. The next useful detail is this: Write it as if you are briefing a new team member on their first day.

      +

      Alex: A few details make that real. Start with identity. "You are a [role] focused on [area].". List responsibilities. What specific tasks does this agent handle? Set guardrails. What should the agent never do? What are its limits? Provide examples. Show what good output looks like.

      -

      Jamie: Let's pause on Opening the PR for review. What should a learner take away from it?

      -

      Alex: Start with Opening the PR for review. There is something to understand, something to try, and something that proves the try worked.

      -

      Alex: First, press Ctrl+Shift+P, type "GitHub Pull Requests: View Pull Request". Then, the PR tree appears in the sidebar - navigate with Down Arrow. After that, each changed file is announced with its name and change summary. Finally, press Enter on a file to open its diff editor. Treat it like a recipe: do not add the next ingredient until the previous one is actually in the bowl.

      -

      Jamie: Before we leave Opening the PR for review, what is the practical point?

      -

      Alex: First, the diff editor opens with the standard VS Code diff layout. It is a checklist, but a meaningful one: every item creates evidence that the next step is safe.

      -

      Jamie: Let's pause on Using the Accessible Diff Viewer. What should a learner take away from it?

      -

      Alex: Start with Using the Accessible Diff Viewer. There is something to understand, something to try, and something that proves the try worked.

      -

      Alex: First, in the diff editor, press F7 to open the Accessible Diff Viewer. Then, NVDA announces: "Changed lines X to Y in filename, Change 1 of N". After that, the viewer shows each change with "Removed:" and "Added:" labels. Finally, press F7 to move to the next change, Shift+F7 for previous. It is a checklist, but a meaningful one: every item creates evidence that the next step is safe.

      -

      Jamie: Before we leave Using the Accessible Diff Viewer, what is the practical point?

      -

      Alex: First, press Escape when done to close the viewer. It is like walking a hallway with named doors: read the sign, enter the right room, then confirm where you landed.

      -

      Jamie: Let's pause on Placing a comment. What should a learner take away from it?

      -

      Alex: Keep the learner anchored in Placing a comment. Screen reader users (VoiceOver on macOS).

      -

      Alex: First, navigate to the line you want to comment on in the diff. Then, press Ctrl+Shift+P, type "GitHub Pull Requests: Add Comment". After that, a text area opens below the line - NVDA announces the input focus. Finally, type your comment. It is like walking a hallway with named doors: read the sign, enter the right room, then confirm where you landed.

      -

      Jamie: Before we leave Placing a comment, what is the practical point?

      -

      Alex: First, press Tab to the Submit button, then Enter. The rhythm is simple: orient, act, verify, then continue.

      +

      Alex: This is the part worth saying out loud. Start with Learning Cards: Writing the Agent File. There is something to understand, something to try, and something that proves the try worked.

      +

      Alex: That shows up in the workshop in a few specific ways. Create your agent file with Ctrl+N, then Ctrl+S and save to.github/agents/your-agent-name.md -- the Explorer navigates to the folder automatically. Use Ctrl+Shift+O to navigate between YAML frontmatter fields and Markdown headings (Responsibilities, Guardrails) in your agent file. The YAML frontmatter is between --- markers at the top -- your screen reader announces these as horizontal rules. Agent files are standard Markdown -- open Markdown Preview (Ctrl+Shift+V) side by side to verify formatting as you write. The YAML frontmatter at the top uses name: and description: fields -- keep these on separate lines for readability at high zoom. Use a consistent heading hierarchy ( for title, for sections) so the Outline view (Ctrl+Shift+O) shows a clean structure.

      +

      Jamie: Let's pause on 4. Phase 3: Define Responsibilities and Guardrails. What should a learner take away from it?

      +

      Alex: This is where 4. Phase 3: Define Responsibilities and Guardrails becomes real: responsibilities and guardrails are the most important parts of your agent's instructions. That matters in practice: The autograder checks that both sections exist.

      +

      Alex: The next layer is this. Keep the learner anchored in Writing responsibilities. Responsibilities define what the agent does. This is the part to say slowly: Each responsibility should describe one discrete action the agent can take.

      +

      Alex: On the ground, that means a few things. Scan HTML files for tags missing the alt attribute. Check that all elements have visible text or an aria-label. Verify heading levels do not skip (e.g., h1 to h3 without h2). Help with accessibility.

      -

      Jamie: Let's pause on Opening the PR. What should a learner take away from it?

      -

      Alex: Start with Opening the PR. There is something to understand, something to try, and something that proves the try worked.

      -

      Alex: First, press Cmd+Shift+P, type "GitHub Pull Requests: View Pull Request". Then, navigate the PR tree with VO+Down Arrow. After that, press Return on a file to open its diff. The rhythm is simple: orient, act, verify, then continue.

      -

      Jamie: Let's pause on Accessible Diff Viewer. What should a learner take away from it?

      -

      Alex: Start with Accessible Diff Viewer. There is something to understand, something to try, and something that proves the try worked.

      -

      Alex: First, press F7 in the diff editor. Then, VoiceOver announces each change with clear "Removed" and "Added" labels. After that, navigate with F7/Shift+F7. Finally, press Escape to close. Think of it as a rail line: each stop confirms you are still on the right route before the next one.

      -

      Jamie: Let's pause on Comment placement. What should a learner take away from it?

      -

      Alex: Start with Comment placement. There is something to understand, something to try, and something that proves the try worked.

      -

      Alex: First, press Cmd+Shift+P, type "GitHub Pull Requests: Add Comment". Then, vO+Shift+Down Arrow to interact with the comment text area. After that, type your comment. Finally, vO+Shift+Up Arrow to stop interacting, then Tab to Submit. Treat it like a recipe: do not add the next ingredient until the previous one is actually in the bowl.

      +

      Jamie: Let's pause on Writing guardrails. What should a learner take away from it?

      +

      Alex: The reason Writing guardrails matters is that guardrails define what the agent must not do. That gives the learner a simple foothold: they prevent the agent from overstepping, giving harmful advice, or acting without permission.

      +

      Alex: Here is what that changes in practice. Never auto-fix code without asking the user first. Do not provide medical, legal, or financial advice when discussing accessibility compliance. Limit reviews to the files the user specifies -- do not scan the entire repository. If a finding is uncertain, say so explicitly rather than presenting it as definitive.

      +

      Alex: Now bring the learner back to the room. Start with Learning Cards: Responsibilities and Guardrails. There is something to understand, something to try, and something that proves the try worked.

      +

      Alex: The room should hear these as checkpoints. Use Responsibilities and Guardrails as exact heading names -- the autograder searches for these strings. Each responsibility should start with a verb (Scan, Check, Verify, Flag) -- this makes them concrete and testable. Guardrails should start with "Never" or "Do not" to set clear boundaries your screen reader identifies as restrictions when reviewing the file. Format responsibilities as a bulleted list (starting with -) for easy scanning at high zoom -- one responsibility per bullet. Keep each guardrail to a single line so it remains visible without horizontal scrolling at your zoom level. Use bold text for emphasis on critical guardrails (e.g., Never modify files without approval ) to improve visual scanning.

      +

      Jamie: Let's pause on 5. Phase 4: Test Your Agent Locally. What should a learner take away from it?

      +

      Alex: Here is the plain-English version of 5. Phase 4: Test Your Agent Locally. See also: Chapter 18: Fork and Contribute covers the fork-and-PR workflow you will use to submit your agent. Put another way, before opening a pull request, test your agent to verify it works.

      -

      Jamie: Let's pause on Using the Accessible Diff Viewer (F7). What should a learner take away from it?

      -

      Alex: This is where Using the Accessible Diff Viewer (F7) becomes real: the Accessible Diff Viewer reads each change as a structured block. That matters in practice: This example is from a real Learning Room scenario: a contributor fixing the heading hierarchy in docs/keyboard-shortcuts.md by changing a level-4 heading to level-3, which is exactly what you look for when reviewing Challenge 2 PRs.

      -

      Alex: Treat examples as spoken recipes, not decorations. You may hear something like "Changed lines 14 to 14 in docs/keyboard-shortcuts.md; [Change 1 of 3]; Removed:; NVDA Single-Key Navigation; Added:; NVDA Single-Key Navigation". Read the command, understand what it changes, then run it only when the repository state matches the lesson.

      -

      Alex: Keep the teaching thread moving. Start with Navigation. There is something to understand, something to try, and something that proves the try worked.

      -

      Alex: The practical takeaway is this. F7 - jump to next change (next hunk). Shift+F7 - jump to previous change. Alt+F2 - open VS Code's Accessible View for additional context on the current item. Escape - close the Accessible Diff Viewer.

      -

      Jamie: Let's pause on What makes this better than the raw diff editor. What should a learner take away from it?

      -

      Alex: Start with What makes this better than the raw diff editor. There is something to understand, something to try, and something that proves the try worked.

      -

      Alex: The practical takeaway is this. Each change is announced as a discrete unit with clear "Removed:" and "Added:" labels. You hear the change number of total changes ("Change 3 of 12"). No table navigation required - purpose-built for sequential listening. Works with all three major screen readers without any special configuration.

      +

      Jamie: Let's pause on Testing with GitHub Copilot Chat. What should a learner take away from it?

      +

      Alex: Start with Testing with GitHub Copilot Chat. There is something to understand, something to try, and something that proves the try worked.

      +

      Alex: That becomes easier when you listen for these cues. Understand its mission? Follow its responsibilities? Respect its guardrails?

      +

      Alex: First, open VS Code with the accessibility-agents repository. Then, ensure your agent file is saved in.github/agents/. After that, open GitHub Copilot Chat (Ctrl+Shift+I or Cmd+Shift+I). Finally, invoke your agent by name: @your-agent-name check this file for accessibility issues. It is a checklist, but a meaningful one: every item creates evidence that the next step is safe.

      +

      Jamie: Before we leave Testing with GitHub Copilot Chat, what is the practical point?

      +

      Alex: First, observe the response. Does the agent. It is like walking a hallway with named doors: read the sign, enter the right room, then confirm where you landed.

      +

      Jamie: Let's pause on Testing checklist. What should a learner take away from it?

      +

      Alex: Start with Testing checklist. There is something to understand, something to try, and something that proves the try worked.

      +

      Alex: The practical takeaway is this. [ ] The agent responds when invoked by name. [ ] The agent stays within its defined responsibilities. [ ] The agent does not violate any guardrails. [ ] The agent's output is useful and specific. [ ] The agent handles edge cases gracefully (empty files, no issues found).

      +

      Jamie: Let's pause on Iterating on your agent. What should a learner take away from it?

      +

      Alex: The reason Iterating on your agent matters is that if the agent does not behave as expected. That gives the learner a simple foothold: most students iterate 2-3 times before they are satisfied. The interface gets friendlier when it stops being a wall of controls and starts being a set of named places.

      +

      Alex: First, read its instructions carefully. Is anything ambiguous? Then, add more specific instructions or examples. After that, test again with the same prompt. Finally, repeat until the behavior matches your intent. The rhythm is simple: orient, act, verify, then continue.

      -

      Alex: Keep the teaching thread moving. Start with Placing Comments in VS Code (GitHub PR Extension): From the diff editor with the GitHub PR extension. The next useful detail is this: Comments placed in VS Code sync to GitHub - they appear in the PR's Files Changed tab and the author receives the same notification.

      -

      Jamie: Let's pause on The Anatomy of a Useful Review Comment. What should a learner take away from it?

      -

      Alex: Here is the plain-English version of The Anatomy of a Useful Review Comment. A comment that helps the author is.

      -

      Alex: First, specific - link to the exact line and name the pattern you see. Then, educational - say why something matters, not just what to change. After that, graduated - signal whether this is blocking, or a preference. Treat it like a recipe: do not add the next ingredient until the previous one is actually in the bowl.

      -

      Alex: Keep the teaching thread moving. This is where Blocking example (reviewing a PR for docs/keyboard-shortcuts.md) becomes real: "The heading on line 34 uses (level 4) directly after (level 2), skipping heading level 3. That matters in practice: Screen reader users who navigate by heading level will miss any content between those two levels. The workshop is closer to rehearsal than lecture. You hear the move, try the move, and then check what changed.

      +

      Jamie: Let's pause on Learning Cards: Testing Your Agent. What should a learner take away from it?

      +

      Alex: Start with Learning Cards: Testing Your Agent. There is something to understand, something to try, and something that proves the try worked.

      +

      Alex: The practical takeaway is this. Open Copilot Chat (Ctrl+Shift+I) and type @your-agent-name followed by a test prompt -- your screen reader announces the response as it streams. Press Alt+F2 after the response finishes to read the full output in Accessible View with arrow keys. If the agent does not respond as expected, edit the.agent.md file and ask again -- Copilot picks up changes immediately. Agent responses appear in the Copilot Chat panel -- widen the panel by dragging its left edge for better readability. Test with a simple prompt first (e.g., "review this file") and read the full response before trying complex requests. Use Accessible View (Alt+F2) to read responses at your preferred editor font size instead of the Chat panel's default.

      +

      Jamie: Let's pause on Tool Cards: Open Your Capstone PR. What should a learner take away from it?

      +

      Alex: Here is the plain-English version of Tool Cards: Open Your Capstone PR. VS Code Desktop (primary for Day 2).

      +

      Alex: First, push your branch: Ctrl+Shift+P Git: Push. Then, ctrl+Shift+P GitHub Pull Requests: Create Pull Request. After that, set base repo to Community-Access/accessibility-agents, fill in the title and description. Finally, navigate to your fork on GitHub. Treat it like a recipe: do not add the next ingredient until the previous one is actually in the bowl.

      +

      Jamie: Before we leave Tool Cards: Open Your Capstone PR, what is the practical point?

      +

      Alex: First, click Contribute Open pull request. Then, verify the base is Community-Access/accessibility-agents:main and the compare is your branch. It is a checklist, but a meaningful one: every item creates evidence that the next step is safe.

      +

      Alex: Treat examples as spoken recipes, not decorations. You may hear something like git push -u origin your-branch; gh pr create --repo Community-Access/accessibility-agents. Read the command, understand what it changes, then run it only when the repository state matches the lesson.

      +

      Jamie: Let's pause on Pre-PR checklist. What should a learner take away from it?

      +

      Alex: Start with Pre-PR checklist. There is something to understand, something to try, and something that proves the try worked.

      +

      Alex: The practical takeaway is this. [ ] Your agent file has valid YAML frontmatter (name and description fields). [ ] Your agent file has a Responsibilities section. [ ] Your agent file has a Guardrails section. [ ] The file is in the correct directory. [ ] You have committed and pushed to your fork.

      -

      Jamie: Let's pause on Non-blocking (nit) example (reviewing a PR for docs/welcome.md). What should a learner take away from it?

      -

      Alex: Keep the learner anchored in Non-blocking (nit) example (reviewing a PR for docs/welcome.md). "nit: The link text in the 'Getting Help' section reads 'click here for more information.' Screen reader users who navigate links out of context will hear only 'click here' with no destination. This is the part to say slowly: Consider 'See the accessibility setup guide' instead.

      -

      Alex: Keep the teaching thread moving. The reason Question example (reviewing a PR for docs/setup-guide.md) matters is that "The PR description says this fixes broken links in the setup guide, but the link on line 12 still points to /docs/old-setup. That gives the learner a simple foothold: am I reading the diff correctly, or was this link intentionally left?

      -

      Jamie: Let's pause on Prefixes That Set Expectations. What should a learner take away from it?

      -

      Alex: Start with Prefixes That Set Expectations: Using shorthand prefixes helps authors parse many comments quickly.

      +

      Jamie: Let's pause on Open the PR. What should a learner take away from it?

      +

      Alex: Keep the learner anchored in Open the PR. Follow the pull request steps from Chapter 18, Step 7. A good GitHub workflow is like a well-run meeting: everyone knows the topic, the next action, and who has the floor.

      +

      Alex: The practical takeaway is this. Your mission statement from Phase 1. What the agent does (summary of responsibilities). Any design decisions you made. How you tested it.

      +

      Alex: First, push your branch: git push -u origin agents/your-username-agent-name. Then, go to the upstream repository on GitHub.com. After that, click the banner or go to Pull Requests and click New pull request, then compare across forks. Finally, select your fork and branch. It is like walking a hallway with named doors: read the sign, enter the right room, then confirm where you landed.

      +

      Jamie: Before we leave Open the PR, what is the practical point?

      +

      Alex: First, write a PR title: "Add [agent-name] accessibility agent". Then, in the PR body,. After that, create the pull request. The rhythm is simple: orient, act, verify, then continue.

      +

      Jamie: Let's pause on The autograder. What should a learner take away from it?

      +

      Alex: The reason The autograder matters is that the repository has an autograding workflow that runs on every pull request. That gives the learner a simple foothold: the autograder posts results as a comment on your PR.

      +

      Alex: That matters because of the next idea. Start with Learning Cards: Opening Your Pull Request. There is something to understand, something to try, and something that proves the try worked.

      +

      Alex: The practical takeaway is this. The autograder comment appears in the PR timeline -- navigate to Comments on GitHub.com with h (heading navigation) to find the results. Each autograder check is listed with a pass/fail status and point value -- listen for "10/10" or "0/15" to identify which checks need attention. If a check fails, read the failure message, fix the issue locally, commit, push, and the autograder re-runs automatically. The autograder results appear as a comment with a table showing checks, points, and pass/fail status -- zoom with Ctrl+= to read the details. Green checkmarks indicate passing checks; red X marks indicate failures -- pair with High Contrast theme for clearest visibility. Your PR description should include your mission statement, responsibilities summary, and testing notes.

      -

      Alex: Keep the teaching thread moving. Here is the plain-English version of How Many Comments Is Too Many? There is no hard limit, but quantity without prioritization is noise. Put another way, if you have 15 comments, make clear which 2-3 are blocking. It is like learning a transit route. The names of the stops matter because they tell you whether you are still going the right direction.

      -

      Jamie: Let's pause on "I want to verify the PR only changes what it claims". What should a learner take away from it?

      -

      Alex: This is where "I want to verify the PR only changes what it claims" becomes real: example: A PR says "Challenge 2: Add NVDA shortcut" but the file tree shows changes to both docs/keyboard-shortcuts.md and docs/welcome.md.

      -

      Alex: Keep the teaching thread moving. Keep the learner anchored in "I want to find all changes to one specific section". Example: A PR for Challenge 3 modified docs/welcome.md. This is the part to say slowly: You want to verify the [TODO] in the "Who Can Contribute?" section was filled in correctly.

      +

      Jamie: Let's pause on 7. Phase 6: Respond to Review. What should a learner take away from it?

      +

      Alex: Here is the plain-English version of 7. Phase 6: Respond to Review. After the autograder passes, a peer reviewer (your buddy or another student) and a facilitator will review your agent.

      +

      Alex: Keep the teaching thread moving. Start with What reviewers look for. There is something to understand, something to try, and something that proves the try worked.

      +

      Alex: The practical takeaway is this. Clarity: Are the instructions easy to understand? Specificity: Are responsibilities concrete and actionable? Safety: Are guardrails sufficient to prevent harmful behavior? Usefulness: Would this agent actually help someone? Scope: Does the agent try to do too much or too little?

      +

      Jamie: Let's pause on Responding to feedback. What should a learner take away from it?

      +

      Alex: Keep the learner anchored in Responding to feedback. This is the same process from Chapter 18, Step 8.

      +

      Alex: First, read each review comment. Then, make changes locally. After that, commit and push. The PR updates automatically. Finally, reply to each comment explaining your changes. It is like walking a hallway with named doors: read the sign, enter the right room, then confirm where you landed.

      -

      Jamie: Why is the evidence prompt part of the teaching, not just grading?

      -

      Alex: The reason Exercises matters is that these exercises use the files in learning-room/docs/ in this repository. That gives the learner a simple foothold: all examples involve documentation changes - no code required.

      -

      Alex: Keep the teaching thread moving. Start with Exercise A - Complete a Web Review: Scenario: A contributor has submitted a pull request titled "Add screen reader tips to the setup guide." The PR modifies learning-room/docs/setup-guide.md. The next useful detail is this: Your job is to review it before it merges. Think of it like entering a new building: first you find the lobby, then the room, then the door you actually need.

      -

      Jamie: Let's pause on Step 1: Navigate to the Pull Request. What should a learner take away from it?

      -

      Alex: Here is the plain-English version of Step 1: Navigate to the Pull Request. How to know you're in the right place.

      -

      Alex: The practical takeaway is this. The PR title is visible at the top. You see a description box with text about what this PR does. You see tabs labeled "Conversation," "Commits," "Files Changed". Use Ctrl+F to search the PR list for "screen reader tips". Or ask in the workshop Slack - someone can share the exact URL.

      -

      Alex: First, open GitHub in your browser and navigate to the workshop repository (github.com/[your-fork]/[workshop-repo] or community-access/accessibility-agents). Then, click the Pull Requests tab (top navigation). After that, look for a PR titled "Add screen reader tips to the setup guide" - click it to open. Finally, you should now see the PR page with sections: Conversation, Commits, Files Changed. Treat it like a recipe: do not add the next ingredient until the previous one is actually in the bowl.

      +

      Alex: Keep the teaching thread moving. The reason When your PR is merged matters is that your agent is now part of the accessibility-agents ecosystem. That gives the learner a simple foothold: it is available to anyone who uses the repository.

      +

      Alex: The practical takeaway is this. You can navigate the fork workflow end to end. You can write clear, structured technical documentation. You understand accessibility concepts well enough to teach an AI agent about them. You can respond constructively to code review.

      +

      Jamie: Let's pause on 8. Capstone Rubric. What should a learner take away from it?

      +

      Alex: Start with 8. Capstone Rubric: The capstone is worth 60 autograded points plus peer review.

      +

      Alex: Keep the teaching thread moving. Here is the plain-English version of What "meets expectations" looks like. A capstone that meets expectations has. It is like learning a transit route. The names of the stops matter because they tell you whether you are still going the right direction.

      +

      Alex: The practical takeaway is this. A focused mission (not "help with accessibility" -- something specific). At least 3 concrete responsibilities. At least 3 meaningful guardrails. A PR description that explains the agent's purpose. All autograder checks passing.

      -

      Jamie: Let's pause on Step 2: Read the PR Description. What should a learner take away from it?

      -

      Alex: Start with Step 2: Read the PR Description. There is something to understand, something to try, and something that proves the try worked.

      -

      Alex: The practical takeaway is this. Does the PR author explain what file changed? (should mention setup-guide.md). Does it explain why? (should mention "improve accessibility" or "add tips"). Is it clear enough that a reviewer can understand the goal without reading the diff? You can answer: "This PR adds [specific content] to [specific file] because [clear reason]". Example: "This PR adds screen reader usage tips to the setup guide because new users need accessibility guidance".

      -

      Alex: First, you are currently on the Conversation tab. Then, read the PR description (the text immediately under the PR title). After that, look for: "What does this PR change?" and "Why does it change it?". Finally, with screen reader: Navigate to the description with D (NVDA) or press Ctrl+Option+Up (VoiceOver) to find main landmarks, then read the content region. It is a checklist, but a meaningful one: every item creates evidence that the next step is safe.

      -

      Jamie: Let's pause on Step 3: Navigate to "Files Changed". What should a learner take away from it?

      -

      Alex: Start with Step 3: Navigate to "Files Changed". There is something to understand, something to try, and something that proves the try worked.

      -

      Alex: The practical takeaway is this. A section showing the file name setup-guide.md with a small badge showing "+20 −0" (20 lines added, 0 lines removed). Below it, the diff with removed lines (preceded by −) and added lines (preceded by +). Scroll up to see if there are other files. For this exercise, only setup-guide.md should be changed. If you see other files, confirm they are not modified (the badge should show "+0 −0" or no changes).

      -

      Alex: First, click the Files Changed tab (top of the PR page, to the right of "Commits"). Then, you are now viewing the diff. After that, with keyboard (all screen readers): Press T to jump to the diff table. The page focuses on the file comparison area. It is like walking a hallway with named doors: read the sign, enter the right room, then confirm where you landed.

      -

      Jamie: Let's pause on Step 4: Activate Focus Mode for Better Diff Reading. What should a learner take away from it?

      -

      Alex: The reason Step 4: Activate Focus Mode for Better Diff Reading matters is that with screen reader (once in Focus Mode). The interface gets friendlier when it stops being a wall of controls and starts being a set of named places.

      -

      Alex: The practical takeaway is this. The page simplifies: sidebars disappear. Only the diff is visible - easier for screen reader navigation and less cognitive load. The diff is now the main content area. NVDA/JAWS: Press T to jump to the diff table. VoiceOver: Navigate with VO+Right Arrow to find the table/content region. Read through the changes: ↓ arrow moves to each line.

      -

      Alex: First, look for a button labeled "Focus Mode" or an icon (usually at the top right of the diff area). Then, with keyboard: Press F to toggle Focus Mode (may need to be in the diff area first). After that, with mouse: Click the Focus Mode button/icon. The rhythm is simple: orient, act, verify, then continue.

      +

      Jamie: Let's pause on What "exceeds expectations" looks like. What should a learner take away from it?

      +

      Alex: This is where What "exceeds expectations" looks like becomes real: a capstone that exceeds expectations also has.

      +

      Alex: The practical takeaway is this. Examples of expected input and output in the agent instructions. A section describing the agent's limitations. Evidence of testing (screenshots or transcripts in the PR description). Thoughtful responses to review feedback.

      +

      Alex: Keep the teaching thread moving. Keep the learner anchored in 9. Example Agents for Inspiration. These examples show the range of valid agent designs. This is the part to say slowly: Your agent does not need to be this long, but it should be this clear.

      +

      Jamie: Let's pause on Example 1: Heading Hierarchy Checker. What should a learner take away from it?

      +

      Alex: The reason Example 1: Heading Hierarchy Checker matters is that mission: Validates that HTML and Markdown documents follow a correct heading hierarchy (no skipped levels).

      +

      Alex: The practical takeaway is this. Scan files for heading elements (h1 through h6 in HTML, through in Markdown). Report any instance where a heading level is skipped (e.g., h2 followed by h4). Suggest the correct heading level for each violation. Check that there is exactly one h1 per page. Do not modify files -- only report findings. Do not change heading text, only heading levels.

      +

      Alex: A solid navigation habit is to prove where you are before activating controls. Headings, landmarks, and the address bar are not trivia; they are your map.

      -

      Jamie: Let's pause on Step 5: Find the Heading Hierarchy Issue. What should a learner take away from it?

      -

      Alex: Start with Step 5: Find the Heading Hierarchy Issue. There is something to understand, something to try, and something that proves the try worked.

      -

      Alex: The practical takeaway is this. Screen reader users navigate documents by heading level: 1 → 2 → 3 → 4. A skip from to breaks that navigation. When a user presses "jump to heading level 3," they'll find none, wondering if content is missing. You found the line with that violates hierarchy. You can say the line number and what heading text appears there. You understand why this is an accessibility problem.

      -

      Alex: First, read through the entire diff line by line. Pay special attention to lines starting. Then, you are looking for: a line with (four hashes, heading level 4) that comes directly after a (two hashes, heading level 2). After that, when you find it, note the exact line number shown in the diff. Think of it as a rail line: each stop confirms you are still on the right route before the next one.

      -

      Jamie: Let's pause on Step 6: Place a Blocking Review Comment on the Heading. What should a learner take away from it?

      -

      Alex: Here is the plain-English version of Step 6: Place a Blocking Review Comment on the Heading. If the comment button doesn't appear.

      -

      Alex: The practical takeaway is this. Your comment appears in the thread under that line. The PR author sees it and can make the fix. Make sure you're hovering over the line number area (left side of the line). Try refreshing the page and trying again. Or use the "Add a reply" field at the bottom of the PR and mention the line number manually.

      -

      Alex: First, find the diff line with the problematic heading. Then, hover your mouse over the line number on the left side of that line (or if using keyboard, navigate to that line in the table). After that, a button should appear (or press the Add Comment hotkey - usually C in GitHub). Finally, click it or press Enter to open a comment box. Treat it like a recipe: do not add the next ingredient until the previous one is actually in the bowl.

      -

      Jamie: Before we leave Step 6: Place a Blocking Review Comment on the Heading, what is the practical point?

      -

      Alex: First, press Space, then explain. Then, click the Comment button (or press Ctrl+Enter for keyboard submit). It is a checklist, but a meaningful one: every item creates evidence that the next step is safe.

      -

      Jamie: Let's pause on Step 7: Find the Link Text Issue. What should a learner take away from it?

      -

      Alex: Start with Step 7: Find the Link Text Issue. There is something to understand, something to try, and something that proves the try worked.

      -

      Alex: The practical takeaway is this. Screen reader users can ask their reader to "list all links on this page" - they hear only the link text. If the text is "click here," they have no context about where it goes. Descriptive link text is WCAG 2.4.4 (Link Purpose). You found a link with non-descriptive text. You can explain why "click here" is bad and what would be better.

      -

      Alex: First, continue reading the diff (from where you left off). Then, look for a line containing link text that reads "click here" or "click here for more information". After that, note the line number. It is a checklist, but a meaningful one: every item creates evidence that the next step is safe.

      +

      Alex: Keep the teaching thread moving. Start with Example 2: PR Description Quality Gate: Mission: Reviews pull request descriptions to ensure they contain enough context for reviewers. Think of it like entering a new building: first you find the lobby, then the room, then the door you actually need.

      +

      Alex: The practical takeaway is this. Check that the PR description is at least 50 characters. Verify the description references an issue with Closes XX or Fixes XX. Check for a summary of changes made. Verify the description explains why the change was made, not just what was changed. Never approve or block a PR based solely on description quality. Do not rewrite the description for the author -- suggest improvements.

      +

      Jamie: Let's pause on Example 3: Keyboard Navigation Auditor. What should a learner take away from it?

      +

      Alex: Here is the plain-English version of Example 3: Keyboard Navigation Auditor. Mission: Checks web components for keyboard accessibility compliance.

      +

      Alex: The practical takeaway is this. Verify all interactive elements are reachable via Tab key. Check that custom components have appropriate tabindex values. Validate that focus order follows visual layout. Detect keyboard traps (elements that receive focus but cannot release it via keyboard). Do not modify component code without user approval. Flag potential issues with confidence levels (certain, likely, possible).

      +

      Alex: Keep the teaching thread moving. This is where The universal safety net becomes real: if everything else fails, post this on your challenge issue. That matters in practice: I attempted Challenge 16 and here is what happened: What I tried: [specific actions] What I expected: [what should have happened] What actually happened: [error or unexpected result] What I learned: [even from failure, what do I understand now?].

      -

      Jamie: Let's pause on Step 8: Place a Comment on the Link. What should a learner take away from it?

      -

      Alex: Keep the learner anchored in Step 8: Place a Comment on the Link. nit: means "nice-to-have improvement" (not blocking, but good to fix). A good GitHub workflow is like a well-run meeting: everyone knows the topic, the next action, and who has the floor.

      -

      Alex: First, find the line in the diff with the problematic link. Then, hover over the line number and click to open a comment box (or press C). After that, click Comment or press Ctrl+Enter. It is like walking a hallway with named doors: read the sign, enter the right room, then confirm where you landed.

      -

      Jamie: Let's pause on Step 9: Submit Your Review. What should a learner take away from it?

      -

      Alex: Start with Step 9: Submit Your Review. There is something to understand, something to try, and something that proves the try worked.

      -

      Alex: The practical takeaway is this. Comment - provide feedback but don't block (for minor notes). Approve - the PR is ready to merge. Request changes - this PR cannot merge until changes are made. Your review is submitted. The PR author gets a notification. The PR shows your review with the two comments.

      -

      Alex: First, look for a button labeled "Review changes" (usually at the top right of the page or bottom of comments). Then, click it (or navigate with keyboard and press Enter). After that, a dialog appears with options. Finally, select "Request changes" (you found two things to fix). The rhythm is simple: orient, act, verify, then continue.

      -

      Jamie: Before we leave Step 9: Submit Your Review, what is the practical point?

      -

      Alex: First, in the summary field, write: Found 2 accessibility issues that must be fixed before merging. Then, click "Submit review". Think of it as a rail line: each stop confirms you are still on the right route before the next one.

      -

      Jamie: Let's pause on Reflect on This Exercise. What should a learner take away from it?

      -

      Alex: Start with Reflect on This Exercise: Keep your answers - you'll need them for Chapter 16's Accessibility Agents exercise to compare manual review with agent-assisted review.

      -

      Alex: First, did heading-level navigation help? When you were looking for the issue, was it easier to navigate by heading level (1-6) than to scan every line? Then, would you have caught this without the exercise prompt? If you were a real reviewer not specifically looking for heading issues, would the diff have been obvious? After that, why does screen reader navigation matter? In one sentence, explain why a screen reader user's ability to jump through heading levels is important for this document. Think of it as a rail line: each stop confirms you are still on the right route before the next one.

      +

      Jamie: Let's pause on 55 AI Agents Across 3 Teams and 5 Platforms. What should a learner take away from it?

      +

      Alex: Keep the learner anchored in 55 AI Agents Across 3 Teams and 5 Platforms. Day 2, Block 3 Material Before you read this guide: Accessibility Agents is a growing open source ecosystem: 55 AI-powered agents organized into three teams (Accessibility, GitHub Workflow, and Developer Tools), running on five platforms (GitHub Copilot,. This is the part to say slowly: This chapter introduces the full landscape.

      +

      Alex: Keep the teaching thread moving. Start with Core Prerequisites (Required for All Agents). There is something to understand, something to try, and something that proves the try worked.

      +

      Alex: The practical takeaway is this. [ ] Chapter 0: Pre-Workshop Setup - Git, VS Code, and GitHub account. [ ] Chapter 16: GitHub Copilot - GitHub Copilot Chat installed and working. [ ] GitHub Copilot access (Copilot Free tier is enough for this workshop). [ ].github/agents/ folder exists in your repository (or will create custom agents).

      +

      Jamie: Let's pause on Agent Prerequisites (The "Skill First" Principle). What should a learner take away from it?

      +

      Alex: Start with Agent Prerequisites (The "Skill First" Principle): Every agent automates a skill you should already know by hand. The next useful detail is this: Before using any agent, verify you have done the corresponding manual work.

      -

      Jamie: There are a lot of tools in play. How do we keep that from feeling like a contest?

      -

      Alex: Here is the plain-English version of Exercise B - Use the VS Code Accessible Diff Viewer. Scenario: Review the same pull request from Exercise A, this time entirely in VS Code. Put another way, you'll compare the browser experience with the VS Code experience.

      -

      Alex: Keep the teaching thread moving. Start with Prerequisites. There is something to understand, something to try, and something that proves the try worked.

      -

      Alex: The practical takeaway is this. VS Code must be installed on your machine. The GitHub Pull Requests extension must be installed (see Chapter 12 for installation). You must be signed into GitHub from VS Code (use Ctrl+Shift+P → "GitHub: Sign in").

      -

      Jamie: Let's pause on Step 1: Open the GitHub Pull Requests Extension. What should a learner take away from it?

      -

      Alex: Start with Step 1: Open the GitHub Pull Requests Extension. There is something to understand, something to try, and something that proves the try worked.

      -

      Alex: The practical takeaway is this. With mouse: Click the Extensions icon on the left sidebar (looks like four squares). The extension is listed as active. It mentions: "Review and manage GitHub pull requests and issues".

      -

      Alex: First, open VS Code. Then, with keyboard (all screen readers): Press Ctrl+Shift+X to open the Extensions sidebar. After that, search for "GitHub Pull Requests". Finally, if it's not installed, click Install. It is like walking a hallway with named doors: read the sign, enter the right room, then confirm where you landed.

      -

      Jamie: Before we leave Step 1: Open the GitHub Pull Requests Extension, what is the practical point?

      -

      Alex: First, if it is installed, click GitHub Pull Requests to view its details. The rhythm is simple: orient, act, verify, then continue.

      +

      Alex: Keep the teaching thread moving. Here is the plain-English version of Workshop Recommendation (Chapter 19 / Challenge 15). Chapter 19 is the agent exploration and hands-on validation chapter - where students match agents to skills they already have and learn how to trust, evaluate, and improve AI-powered workflow automation. Put another way, it supports Challenge 15: Meet the Agents.

      +

      Alex: The practical takeaway is this. There are 3 guided + 1-2 optional contribution challenges. Automation check: none (agent output requires human judgment before use). The evidence is issue comment showing agent output and your evaluation of it. The pattern is explore, validate, read internals, optionally contribute.

      +

      Jamie: Let's pause on Challenge 15 Set. What should a learner take away from it?

      +

      Alex: Start with Challenge 15 Set. There is something to understand, something to try, and something that proves the try worked.

      +

      Alex: First, agent Discovery Mapping - identify 3-5 agents that match skills you already have from Day 1. Then, agent Skill Validation - run one agent and evaluate its output against your manual experience. After that, agent Instructions Deep Dive - read one agent's source file and assess what it can and cannot do. Finally, improve an Existing Agent (optional hackathon) - find a gap in an agent's instructions and fix it via PR. It is a checklist, but a meaningful one: every item creates evidence that the next step is safe.

      +

      Jamie: Before we leave Challenge 15 Set, what is the practical point?

      +

      Alex: First, propose a New Agent (optional hackathon) - file an issue proposing an agent for an uncovered workflow. It is like walking a hallway with named doors: read the sign, enter the right room, then confirm where you landed.

      +

      Jamie: Let's pause on Challenge 15.1 Step-by-Step: Agent Discovery Mapping. What should a learner take away from it?

      +

      Alex: Keep the learner anchored in Challenge 15.1 Step-by-Step: Agent Discovery Mapping. Map your Day 1 manual skills to specific agents in the ecosystem so you know which agents you are ready to use. This is the part to say slowly: GitHub.com - the accessibility-agents repository and your assigned Challenge 15 issue. A good GitHub workflow is like a well-run meeting: everyone knows the topic, the next action, and who has the floor.

      +

      Alex: The practical takeaway is this. @daily-briefing (maps to repository and issue awareness from Chapters 2-4). @issue-tracker (maps to Chapter 4 issue workflow). @pr-review (maps to Chapter 6 and Chapter 14 review workflow). Example: You filed issues manually (Ch 4) - you can use @issue-tracker.

      +

      Alex: First, fork the accessibility-agents repository on GitHub.com. Then, open the repository and navigate to Section 3 of the README (or this chapter's Section 3 below) to see the full list of 55 agents organized by team. After that, read through the agent names and descriptions. For each one, ask yourself: "Have I done this task manually during the workshop?". Finally, identify 3-5 agents that match workflows you already practiced. It is like walking a hallway with named doors: read the sign, enter the right room, then confirm where you landed.

      +

      Jamie: Before we leave Challenge 15.1 Step-by-Step: Agent Discovery Mapping, what is the practical point?

      +

      Alex: First, open your assigned Challenge 15 issue. Then, post a discovery mapping comment using this format. The rhythm is simple: orient, act, verify, then continue.

      -

      Jamie: Let's pause on Step 2: Open the Pull Requests Sidebar. What should a learner take away from it?

      -

      Alex: Start with Step 2: Open the Pull Requests Sidebar. There is something to understand, something to try, and something that proves the try worked.

      -

      Alex: The practical takeaway is this. With keyboard: The icon may not be keyboard-reachable directly; instead go to Step 3. VS Code opens a new editor tab for this PR. Below the PR title, you see a "Changes" section listing modified files. You should see setup-guide.md in the changes list. Use Ctrl+Shift+P → search GitHub Pull Requests: Open Pull Request. Paste the PR URL: https://github.com/[owner]/[repo]/pull/[number].

      -

      Alex: First, look for a GitHub-themed icon on the left sidebar (circle with octocat logo) - click it. Then, a sidebar appears showing open pull requests on repositories you have access to. After that, find the PR titled "Add screen reader tips to the setup guide" - it should appear in a list. Finally, click it to open. The rhythm is simple: orient, act, verify, then continue.

      -

      Jamie: Let's pause on Step 3: View the File Changes. What should a learner take away from it?

      -

      Alex: Start with Step 3: View the File Changes. There is something to understand, something to try, and something that proves the try worked.

      -

      Alex: The practical takeaway is this. A diff editor opens showing two columns. Left: the original file (before changes). Right: the new file (after changes). Different colors show added (green), removed (red), and modified (blue) lines. The file name appears at the top: setup-guide.md. NVDA/JAWS: The editor announces "Diff Editor - setup-guide.md".

      -

      Alex: First, in the Changes section, locate setup-guide.md. Then, click on the filename to open it. Think of it as a rail line: each stop confirms you are still on the right route before the next one.

      -

      Jamie: Let's pause on Step 4: Access the Accessible Diff Viewer. What should a learner take away from it?

      -

      Alex: Here is the plain-English version of Step 4: Access the Accessible Diff Viewer. If the Accessible Diff Viewer doesn't open. It is like learning a transit route. The names of the stops matter because they tell you whether you are still going the right direction.

      -

      Alex: The practical takeaway is this. With mouse: Look for a button or menu option labeled "Accessible View" or "Open Accessible Diff". If no button is visible, try Alt+F2 (VS Code Accessible View toggle). A new panel opens at the bottom of VS Code. The panel announces each change one at a time. Changes appear in text format with labels: "Added: " and "Removed: ". The panel is read-only (you read the changes, you don't edit here).

      -

      Alex: First, with keyboard: Press F7 to open the Accessible Diff Viewer. Treat it like a recipe: do not add the next ingredient until the previous one is actually in the bowl.

      +

      Jamie: Let's pause on Challenge 15.2 Step-by-Step: Agent Skill Validation. What should a learner take away from it?

      +

      Alex: The reason Challenge 15.2 Step-by-Step: Agent Skill Validation matters is that run one agent, read its output, and evaluate whether it matches your manual experience. That gives the learner a simple foothold: VS Code with the accessibility-agents repository cloned and Copilot Chat open.

      +

      Alex: The practical takeaway is this. @daily-briefing morning briefing. @issue-tracker find open issues labeled good-first-issue in accessibility-agents. @pr-review show open PRs in accessibility-agents.

      +

      Alex: First, clone your fork of accessibility-agents to VS Code (or open it in github.dev). Then, open Copilot Chat: Ctrl+Shift+I (Mac: Cmd+Shift+I). After that, choose one agent from your discovery list. If unsure, start with @daily-briefing or @issue-tracker. Finally, run it with a simple prompt. The rhythm is simple: orient, act, verify, then continue.

      +

      Jamie: Before we leave Challenge 15.2 Step-by-Step: Agent Skill Validation, what is the practical point?

      +

      Alex: First, read the agent's output carefully. Take a moment to think about what you expected. Then, open your assigned Challenge 15 issue and post an evaluation comment. Think of it as a rail line: each stop confirms you are still on the right route before the next one.

      +

      Jamie: Let's pause on Challenge 15.3 Step-by-Step: Agent Instructions Deep Dive. What should a learner take away from it?

      +

      Alex: Start with Challenge 15.3 Step-by-Step: Agent Instructions Deep Dive: Read one agent's source file to understand what instructions it follows, what tools it can use, and what mistakes it could make. The next useful detail is this: VS Code or GitHub.com - reading files in the accessibility-agents repository.

      +

      Alex: The practical takeaway is this. What is this agent trying to do? (its purpose). What tools does it have access to? (tool permissions). What constraints or guardrails are in the instructions?

      +

      Alex: First, in the accessibility-agents repository, navigate to the.github/ folder (or wherever agent definition files are stored). Then, open one.agent.md or.prompt.md file for an agent you used or are curious about. After that, read the file and identify. Finally, think critically: could this agent make a mistake? What kind? Think of it as a rail line: each stop confirms you are still on the right route before the next one.

      +

      Jamie: Before we leave Challenge 15.3 Step-by-Step: Agent Instructions Deep Dive, what is the practical point?

      +

      Alex: First, open your assigned Challenge 15 issue and post your analysis. Treat it like a recipe: do not add the next ingredient until the previous one is actually in the bowl.

      +

      Jamie: Let's pause on Optional Extensions 15.4-15.5 (Hackathon). What should a learner take away from it?

      +

      Alex: Here is the plain-English version of Optional Extensions 15.4-15.5 (Hackathon). Extension 15.4: Improve an Existing Agent (45 min). Put another way, extension 15.5: Propose a New Agent (60 min).

      +

      Alex: The practical takeaway is this. Find an agent whose instructions have a gap (use Section 6 suggestions or file an issue). Fork the repo, edit the agent's.agent.md file. Get a facilitator review. Open a PR with your improvement.

      -

      Jamie: Let's pause on Step 5: Listen to and Understand the First Change. What should a learner take away from it?

      -

      Alex: Start with Step 5: Listen to and Understand the First Change. There is something to understand, something to try, and something that proves the try worked.

      -

      Alex: The practical takeaway is this. NVDA/JAWS: The Accessible Diff Viewer announces "Removed:" and "Added:" labels, followed by the line content. VoiceOver: The announcement may be similar; listen for "removed" and "added" keywords.

      -

      Alex: First, the first change is automatically announced when you open the Accessible Diff Viewer. Then, let your screen reader read it completely - don't interrupt. After that, write down the exact text announced. Finally, press the Down arrow to move to the next change. It is a checklist, but a meaningful one: every item creates evidence that the next step is safe.

      -

      Jamie: Let's pause on Step 6: Find the Heading Hierarchy Issue. What should a learner take away from it?

      -

      Alex: Start with Step 6: Find the Heading Hierarchy Issue. There is something to understand, something to try, and something that proves the try worked.

      -

      Alex: The practical takeaway is this. Four hashes ( ) indicate a level 4 heading. In the diff, you're looking for it appearing after a level 2 heading ( ). This creates the hierarchy skip you caught in Exercise A. You found the explanation in the Accessible Diff Viewer's format. You can explain: "The added line with directly follows a, skipping level 3". The Accessible Diff Viewer made this pattern clearer than scanning raw + characters.

      -

      Alex: First, continue pressing Down arrow to move through changes. Then, listen carefully for a change involving headings (lines starting with ). After that, specifically, listen for: "Added: " (four hashes). Finally, when you hear this, stop and write it down. It is like walking a hallway with named doors: read the sign, enter the right room, then confirm where you landed.

      -

      Jamie: Let's pause on Step 7: Locate the Heading Line and Add an Inline Comment. What should a learner take away from it?

      -

      Alex: Start with Step 7: Locate the Heading Line and Add an Inline Comment. There is something to understand, something to try, and something that proves the try worked.

      -

      Alex: The practical takeaway is this. Use Ctrl+F to open Find. Search for to locate it quickly. Press Enter to jump to it. With keyboard: The comment button may appear on the current line; navigate to it and press Enter. A comment box opens. You can type your comment.

      -

      Alex: First, once you identified the problematic heading in the Accessible Diff Viewer, close the Accessible Diff Viewer (press F7 again or Alt+F2). Then, you're back in the regular Diff Editor. After that, find the line with the problematic heading. Finally, close Find (Escape). The rhythm is simple: orient, act, verify, then continue.

      -

      Jamie: Before we leave Step 7: Locate the Heading Line and Add an Inline Comment, what is the practical point?

      -

      Alex: First, place your cursor on that line. Then, right-click and select "Add Comment" or press the Comment icon that appears on the left margin. Think of it as a rail line: each stop confirms you are still on the right route before the next one.

      +

      Alex: Keep the teaching thread moving. This is where Completing Challenge 15: Submit Your Evidence becomes real: your evidence is the Challenge 15 issue comments for 15.1, 15.2, and 15.3. That matters in practice: For optional extensions, your PR or proposal issue is the evidence. The workshop is closer to rehearsal than lecture. You hear the move, try the move, and then check what changed.

      +

      Jamie: Let's pause on Expected Outcomes. What should a learner take away from it?

      +

      Alex: Start with Expected Outcomes. There is something to understand, something to try, and something that proves the try worked.

      +

      Alex: The practical takeaway is this. Student can map personal Day 1 skills to specific agents in the ecosystem. Student understands the Skill First, Agent Second principle and can articulate why agent output requires human judgment. Student can read agent instructions and evaluate what an agent can and cannot do. Student has used at least one agent and verified it against manual skills. (Optional) Student has contributed to the accessibility-agents ecosystem with a fix, improvement, or proposal.

      +

      Jamie: Let's pause on If You Get Stuck. What should a learner take away from it?

      +

      Alex: The reason If You Get Stuck matters is that continue learning: The GitHub Skills courses Build Applications with Copilot Agent Mode and Expand Your Team with Copilot explore agent-powered development workflows. That gives the learner a simple foothold: see Appendix Z for the full catalog.

      +

      Alex: First, cannot find an agent that matches your skills? Start with @daily-briefing or @issue-tracker - those build directly on Chapter 2-5 material. If you have not done those manual steps yet, go back to those chapters first. Then, agent output does not make sense? That is the right response. Paste the output in an issue comment along with your confusion. That is valuable feedback - the agent may need better instructions or guardrails. After that, cannot access the agents in Copilot Chat? Verify: Is Copilot Chat extension installed (not just base Copilot)? Are you signed in to GitHub in VS Code? Does.github/agents/ folder exist in your cloned repository? Finally, repository will not clone? Use the terminal: git clone https://github.com/[your-username]/accessibility-agents.git then open the folder in VS Code. The rhythm is simple: orient, act, verify, then continue.

      +

      Jamie: Before we leave If You Get Stuck, what is the practical point?

      +

      Alex: First, ask facilitator to show them what agent you wanted to run, what output you got, and what you expected. Then, finished but not sure you did it right? Compare your work against the Challenge 15 reference solution. Think of it as a rail line: each stop confirms you are still on the right route before the next one.

      -

      Jamie: Let's pause on Step 8: Write Your Accessible Diff Comment. What should a learner take away from it?

      -

      Alex: Start with Step 8: Write Your Accessible Diff Comment: Why mention the Accessible Diff Viewer? Think of it like entering a new building: first you find the lobby, then the room, then the door you actually need.

      -

      Alex: The practical takeaway is this. It shows that the tool itself helps you see the issue. It documents how you caught the problem (useful for learning).

      -

      Alex: First, in the comment box, type. Then, press Ctrl+Enter or click Comment to submit. Think of it as a rail line: each stop confirms you are still on the right route before the next one.

      -

      Jamie: Let's pause on Step 9: Create a GitHub Pull Request Comment. What should a learner take away from it?

      -

      Alex: Here is the plain-English version of Step 9: Create a GitHub Pull Request Comment. Now you've reviewed the same PR in.

      -

      Alex: First, browser (Exercise A): You spot-checked line numbers manually. Then, VS Code (Exercise B): The Diff Editor plus Accessible Diff Viewer announced changes. After that, go to GitHub in your browser and open the same PR. Finally, scroll to the bottom and leave a comment in the Conversation tab. Treat it like a recipe: do not add the next ingredient until the previous one is actually in the bowl.

      -

      Jamie: Before we leave Step 9: Create a GitHub Pull Request Comment, what is the practical point?

      -

      Alex: First, click Comment. It is a checklist, but a meaningful one: every item creates evidence that the next step is safe.

      -

      Jamie: Before we leave Reflect on This Exercise, what is the practical point?

      -

      Alex: This is where Reflect on This Exercise becomes real: after completing Steps 1-9, answer. That matters in practice: In Chapter 16, you'll compare these manual reviews with the @pr-review agent's suggested changes.

      -

      Alex: First, announcement clarity: Did the "Added:" and "Removed:" labels from the Accessible Diff Viewer help you follow changes faster than reading + and − prefixes in the browser? Then, navigation pattern: Which tool required less back-and-forth clicking/tabbing to understand each change? After that, when would you use each? In one sentence: describe a type of PR where you'd prefer to use each tool. It is a checklist, but a meaningful one: every item creates evidence that the next step is safe.

      +

      Jamie: Let's pause on Learning Moment. What should a learner take away from it?

      +

      Alex: Start with Learning Moment: The 55 agents exist because someone did the manual work first, then automated the repetitive parts. The next useful detail is this: As you explore agents, you are not just learning tools - you are learning what automation looks like when it is built on real expertise and real constraints.

      +

      Jamie: Let's pause on Learning Pattern Used in This Chapter. What should a learner take away from it?

      +

      Alex: Start with Learning Pattern Used in This Chapter. There is something to understand, something to try, and something that proves the try worked.

      +

      Alex: First, map your existing skills to available tools (discovery before action). Then, run one tool and evaluate its output critically (trust but verify). After that, read the source to understand capabilities and limits (internals matter). Finally, contribute improvements based on your evaluation (close the feedback loop). Treat it like a recipe: do not add the next ingredient until the previous one is actually in the bowl.

      +

      Jamie: Let's pause on Capstone: Share Your Feedback (The Most Important Task!). What should a learner take away from it?

      +

      Alex: This is where Capstone: Share Your Feedback (The Most Important Task!) becomes real: you have now explored the full agent ecosystem, completed the workshop, and have valuable perspective on what worked, what confused you, and what we should improve for the next cohort. That matters in practice: Your feedback directly shapes the future of this project.

      -

      Jamie: Let's pause on Exercise C - Compare and Reflect. What should a learner take away from it?

      -

      Alex: Keep the learner anchored in Exercise C - Compare and Reflect. Your Mission: Synthesize what you learned from the manual code reviews (Exercises A & B) and document your findings. This is the part to say slowly: What You'll Learn: Which tools work best for different scenarios, and how your manual review skills prepare you to use AI agents effectively.

      -

      Alex: Keep the teaching thread moving. The reason Step 1: Gather Your Data matters is that before writing your reflection, collect all the information you gathered. That gives the learner a simple foothold: write these down (in a text editor, on paper, or mentally) - you'll reference them in Steps 2-4. The interface gets friendlier when it stops being a wall of controls and starts being a set of named places.

      -

      Alex: The practical takeaway is this. Which line number had the heading hierarchy skip? Which line number had the link text issue? How many steps did it take to find each issue? Did you use screen reader commands or visual scanning more?

      -

      Jamie: Let's pause on Step 2: Navigate to the PR and Leave Your Reflection Comment. What should a learner take away from it?

      -

      Alex: Start with Step 2: Navigate to the PR and Leave Your Reflection Comment. There is something to understand, something to try, and something that proves the try worked.

      -

      Alex: The practical takeaway is this. A text editing area with formatting options (Bold, Italic, Link, etc.). A Comment button below the text area.

      -

      Alex: First, go to GitHub in your browser. Then, open the same PR ("Add screen reader tips to the setup guide"). After that, scroll to the Conversation tab. Finally, scroll all the way down to the comment box at the bottom (labeled "Leave a comment" or "Add a comment"). Think of it as a rail line: each stop confirms you are still on the right route before the next one.

      -

      Jamie: Before we leave Step 2: Navigate to the PR and Leave Your Reflection Comment, what is the practical point?

      -

      Alex: First, click in the comment box. Treat it like a recipe: do not add the next ingredient until the previous one is actually in the bowl.

      +

      Alex: Keep the teaching thread moving. Keep the learner anchored in Submit Workshop Feedback. Use the Workshop Feedback form to share. This is the part to say slowly: Answer as much or as little as you're comfortable sharing.

      +

      Alex: The practical takeaway is this. Which agents stood out? (Most useful or surprising). Which agents confused you? (What would make them better). Was the chapter progression logical? (Did earlier chapters prepare you for later ones). Accessibility experience (If applicable - did any assistive technology work/fail?).

      +

      Jamie: Let's pause on 1. The Principle: Skill First, Agent Second. What should a learner take away from it?

      +

      Alex: The reason 1. The Principle: Skill First, Agent Second matters is that accessibility Agents is not a way to skip learning GitHub. That gives the learner a simple foothold: it is a way to amplify skills you have already built through deliberate practice.

      +

      Alex: The practical takeaway is this. Verify that the agent's output is correct. Catch when the agent misses context that only you have. Edit the agent's drafts into something worth posting under your name. Know when the agent is confidently wrong.

      +

      Alex: Keep the teaching thread moving. Start with Every agent has a manual prerequisite. If you have not done the corresponding skill by hand, the agent is not ready for you yet - and you are not ready for it: This applies across all three teams and all 55 agents. The next useful detail is this: Before running any agent, the facilitator asks the same question. Think of it like entering a new building: first you find the lobby, then the room, then the door you actually need.

      +

      Alex: The practical takeaway is this. GitHub Workflow agents automate repository navigation, issue triage, PR review, and contribution analytics - skills you practiced on Day 1. Accessibility agents automate WCAG auditing, contrast checking, keyboard navigation review, and document scanning - knowledge from your accessibility training and the standards in Appendix C. Developer Tools agents automate accessible coding patterns for Python, wxPython, and desktop applications - skills from your development experience.

      -

      Alex: Keep the teaching thread moving. Here is the plain-English version of Step 3: Write Your Comparison. Type your response to these three questions. Put another way, be specific - reference exact tools, steps, and what you discovered.

      -

      Jamie: Let's pause on Step 4: Review Your Comment. What should a learner take away from it?

      -

      Alex: Start with Step 4: Review Your Comment. There is something to understand, something to try, and something that proves the try worked.

      -

      Alex: The practical takeaway is this. Is it clear which tool I preferred? Did I explain why with concrete examples? Am I describing the real-world impact accurately? Would someone else reading this understand how I caught the issue?

      -

      Alex: First, before submitting, re-read your comment using your screen reader or by reading aloud. Then, ask yourself. After that, make any corrections needed. Finally, do not submit yet - continue to Step 5. It is a checklist, but a meaningful one: every item creates evidence that the next step is safe.

      -

      Jamie: Let's pause on Step 5: Submit Your Reflection. What should a learner take away from it?

      -

      Alex: Start with Step 5: Submit Your Reflection. There is something to understand, something to try, and something that proves the try worked.

      -

      Alex: The practical takeaway is this. Your comment is now visible on the PR. Other reviewers can see your comparison. You have completed the three-part exercise series. Your comment appears on the PR thread. It includes all three reflections. The PR author and other reviewers can see your thought process.

      -

      Alex: First, locate the Comment button at the bottom right of the comment box. Then, with keyboard: Press Tab until the Comment button is focused, then Enter. After that, with mouse: Click the Comment button. Finally, your comment is submitted and appears on the PR page. It is like walking a hallway with named doors: read the sign, enter the right room, then confirm where you landed.

      -
      -

      Jamie: Let's pause on Step 6: Checkpoint - Validate Your Learning. What should a learner take away from it?

      -

      Alex: The reason Step 6: Checkpoint - Validate Your Learning matters is that before moving forward, verify you understand. That gives the learner a simple foothold: if you can answer all three, you're ready for the next chapter.

      -

      Alex: The practical takeaway is this. Expected answer: Something like "Screen readers let users navigate by heading level (pressing 3 jumps to H3), so skipping a level makes users think content is missing.". Expected answer: e.g., "Browser: finding context in discussions. VS Code: linear reading of changes.". Expected answer: Something like "Open the document in a browser, use screen reader heading navigation, and confirm I can reach all levels (H2, H3, H4).".

      -

      Alex: First, heading Hierarchy: Can you explain in one sentence why a → skip breaks screen reader navigation? Then, tool Strengths: For each tool you used, name one task it made easier. After that, real-World Testing: How would you test the heading issue in the published document (not the PR diff)? The rhythm is simple: orient, act, verify, then continue.

      -

      Alex: Keep the teaching thread moving. Start with Using GitHub Copilot to Understand Code Changes: Reviewing code is about understanding what changed, why it changed, and whether the change is safe and correct. The next useful detail is this: GitHub Copilot can help you gather and understand information about code changes - especially when diffs are large, complex, or involve unfamiliar frameworks.

      -

      Jamie: Let's pause on When to Use Copilot During Code Review. What should a learner take away from it?

      -

      Alex: Here is the plain-English version of When to Use Copilot During Code Review. Copilot is most useful for answering these questions.

      -

      Alex: First, "What does this code do?" - you're reading unfamiliar syntax or a framework you don't know well. Then, "Why might this change break something?" - you need to understand dependencies or side effects. After that, "Is this pattern safe?" - you want to verify that the approach follows best practices. Finally, "What would be a better way to write this?" - you're looking for alternatives to suggest. Treat it like a recipe: do not add the next ingredient until the previous one is actually in the bowl.

      -

      Jamie: Before we leave When to Use Copilot During Code Review, what is the practical point?

      -

      Alex: First, "Does this match the PR's description?" - the change seems to do more (or less) than claimed. It is a checklist, but a meaningful one: every item creates evidence that the next step is safe.

      -
      -

      Jamie: Let's pause on In VS Code with an Open Diff. What should a learner take away from it?

      -

      Alex: Start with In VS Code with an Open Diff. There is something to understand, something to try, and something that proves the try worked.

      -

      Alex: First, open the PR using the GitHub Pull Requests extension (see Part 2). Then, open the diff for any file. After that, select a block of code that confuses you (highlight it). Finally, open Copilot Chat: Ctrl+Shift+I. It is a checklist, but a meaningful one: every item creates evidence that the next step is safe.

      -

      Jamie: Before we leave In VS Code with an Open Diff, what is the practical point?

      -

      Alex: First, Copilot reads the selected code and answers in the chat. It is like walking a hallway with named doors: read the sign, enter the right room, then confirm where you landed.

      -

      Jamie: Let's pause on On GitHub.com (Web Interface). What should a learner take away from it?

      -

      Alex: Keep the learner anchored in On GitHub.com (Web Interface). Another option: Use the GitHub Copilot inline suggestions on GitHub.com.

      -

      Alex: The practical takeaway is this. Some GitHub PRs show Copilot insights directly in the diff (as of early 2026). If you see a lightbulb icon, click it to see Copilot's suggestion about that line.

      -

      Alex: First, open the PR's Files Changed tab. Then, focus on a line or section you want to understand better. After that, in VS Code Copilot Chat (not in the browser - Copilot Chat doesn't work directly in browser diffs yet). Finally, copy the confusing code, paste it into chat, and ask Copilot to explain. It is like walking a hallway with named doors: read the sign, enter the right room, then confirm where you landed.

      -

      Alex: Keep the teaching thread moving. The reason Copilot Limitations During Review (Critical to Know) matters is that this is why manual review is essential: You have context (project history, team decisions, user impact) that Copilot does not. That gives the learner a simple foothold: use Copilot to understand, then use your judgment to decide.

      -

      Alex: The practical takeaway is this. See the whole project - it sees only what you show it (the selected diff, not the context of the entire codebase). Verify correctness - it can explain what code does, but not whether it's correct for your specific use case. Understand intent - it reads the code, not the author's mind or the PR description. Catch all risks - it can spot common patterns, but not edge cases unique to your project.

      -
      -

      Jamie: Let's pause on Best Practices. What should a learner take away from it?

      -

      Alex: Start with Best Practices. There is something to understand, something to try, and something that proves the try worked.

      -

      Alex: First, read the diff manually first - you spot the big picture before asking Copilot details. Then, ask Copilot specific questions - not "review this code" but "does this regex handle Unicode?". After that, fact-check Copilot's answers - it can be confidently wrong, especially about frameworks or domains it has less training data. Finally, combine Copilot with manual analysis - ask Copilot to explain, then verify by checking the PR description or looking for related files. Think of it as a rail line: each stop confirms you are still on the right route before the next one.

      -

      Jamie: Before we leave Best Practices, what is the practical point?

      -

      Alex: First, use Copilot to draft comments - type Draft a comment about [issue] for this PR and edit Copilot's suggestion to match your tone. Treat it like a recipe: do not add the next ingredient until the previous one is actually in the bowl.

      -

      Alex: Keep the teaching thread moving. Here is the plain-English version of What Comes Next. Your manual code review skills - identifying heading issues, catching link text problems, understanding screen reader navigation, gathering information with Copilot - are the foundation for understanding automated review. Put another way, in Chapter 16 (Accessibility Agents), you'll meet a full team of agents designed to amplify these skills. It is like learning a transit route. The names of the stops matter because they tell you whether you are still going the right direction.

      -

      Jamie: Let's pause on Part 4: The Reviewer's Craft. What should a learner take away from it?

      -

      Alex: This is where The Reviewer's Craft becomes real: parts 1 through 3 taught you the mechanics -- how to read diffs, leave comments, and use Copilot to understand unfamiliar code. That matters in practice: This part covers something equally important: how to think like a reviewer.

      +

      Jamie: Let's pause on Learning Cards: Skill First, Agent Second. What should a learner take away from it?

      +

      Alex: Start with Learning Cards: Skill First, Agent Second. There is something to understand, something to try, and something that proves the try worked.

      +

      Alex: The practical takeaway is this. Before using any agent, verify you can do the task manually -- for @daily-briefing, confirm you can navigate Issues and PRs on GitHub.com with keyboard shortcuts (j/k to move, Enter to open). Agent output appears in Copilot Chat -- press Alt+F2 to open Accessible View and read the full response with arrow keys before acting on it. If an agent produces something you do not understand, stop and learn the manual skill first from the relevant chapter. Agent responses appear in the Copilot Chat panel -- drag the panel wider or use Alt+F2 (Accessible View) for a larger, cleaner reading pane. Each agent's instructions are in a.agent.md file you can open in VS Code and read at your preferred zoom level before invoking the agent. The agent ecosystem table in Section 3 uses standard Markdown tables that scale with your editor font size.

      +

      Alex: Keep the teaching thread moving. This is where Quick Install (One Command) becomes real: accessibility Agents now ships with a one-liner installer that sets up all 55 agents for your platform.

      +

      Jamie: What should they understand before typing anything?

      +

      Alex: Start with macOS / Linux. There is something to understand, something to try, and something that proves the try worked.

      +

      Alex: Treat examples as spoken recipes, not decorations. You may hear something like curl -fsSL https://raw.githubusercontent.com/Community-Access/accessibility-agents/main/install.sh bash. Read the command, understand what it changes, then run it only when the repository state matches the lesson.

      -

      Alex: Keep the teaching thread moving. Keep the learner anchored in What to Look for in a Review. Every PR is different, but most reviews benefit from scanning across these five categories. This is the part to say slowly: You do not need to check every category exhaustively on every PR.

      -

      Jamie: Let's pause on The Three Review Actions. What should a learner take away from it?

      -

      Alex: The reason The Three Review Actions matters is that when you submit a review on GitHub, you choose one of three actions. That gives the learner a simple foothold: picking the right one matters because it signals your intent to the author and to anyone else watching the PR.

      -

      Alex: First, did you find a bug, security issue, or broken test? -- Request Changes. Then, does the code do something different from what the description says? -- Request Changes. After that, does everything work, with maybe a few style nits? -- Approve (mention the nits in a comment). Finally, do you have questions or optional suggestions? -- Comment. The rhythm is simple: orient, act, verify, then continue.

      -

      Alex: Keep the teaching thread moving. Start with Writing Constructive Feedback: The way you phrase feedback determines whether the author feels supported or attacked. The next useful detail is this: Before pointing out problems, acknowledge something the author did well. Think of it like entering a new building: first you find the lobby, then the room, then the door you actually need.

      +

      Alex: Keep the teaching thread moving. The reason Windows (PowerShell) matters is that the installer detects which AI tools you have installed (VS Code with Copilot, Claude Code, Gemini CLI, Claude Desktop, Codex CLI) and configures the appropriate agent files for each platform. That gives the learner a simple foothold: to uninstall, run the corresponding uninstall script from the repository. The interface gets friendlier when it stops being a wall of controls and starts being a set of named places.

      +

      Jamie: Let's pause on Workshop Setup (Fork and Clone). What should a learner take away from it?

      +

      Alex: Start with Workshop Setup (Fork and Clone): For the workshop, you will also fork and clone the repository so you can make contributions. The next useful detail is this: If Copilot Chat works, the agents work.

      +

      Alex: First, fork accessibility-agents to your GitHub account (you did this on Day 1 or Day 2 morning). Then, clone your fork. After that, open in VS Code: navigate to the folder and run code. (or File, then Open Folder). Finally, open Copilot Chat: Ctrl+Shift+I. Think of it as a rail line: each stop confirms you are still on the right route before the next one.

      +

      Jamie: Before we leave Workshop Setup (Fork and Clone), what is the practical point?

      +

      Alex: First, test: type @daily-briefing morning briefing and press Enter. Treat it like a recipe: do not add the next ingredient until the previous one is actually in the bowl.

      +

      Alex: Treat examples as spoken recipes, not decorations. You may hear something like git clone https://github.com/[your-username]/accessibility-agents.git. Read the command, understand what it changes, then run it only when the repository state matches the lesson.

      +

      Alex: Keep the teaching thread moving. Start with Prerequisites. There is something to understand, something to try, and something that proves the try worked.

      +

      Alex: The practical takeaway is this. GitHub Copilot Chat extension installed (see GitHub Copilot: Installation). Signed in to GitHub via VS Code. A workspace open containing.github/agents/ folder with.agent.md files.

      -

      Jamie: Let's pause on The Reviewer's Checklist. What should a learner take away from it?

      -

      Alex: Here is the plain-English version of The Reviewer's Checklist. Run through this list mentally (or copy it into your notes) for every PR you review.

      -

      Alex: The practical takeaway is this. [ ] I read the PR description before reading the code. [ ] The code does what the description says it does. [ ] The change does not include unrelated modifications. [ ] Variable and function names are clear. [ ] I checked for accessibility: labels, headings, keyboard reach, contrast. [ ] I verified no existing behavior is broken by the change.

      -

      Alex: Keep the teaching thread moving. This is where Reviewing as a Learning Tool becomes real: reviewing is not just a gate to keep bad code out. That matters in practice: It is one of the fastest ways to grow as a developer.

      -

      Jamie: Let's pause on Learning Cards: The Reviewer's Craft. What should a learner take away from it?

      -

      Alex: Start with Learning Cards: The Reviewer's Craft. There is something to understand, something to try, and something that proves the try worked.

      -

      Alex: The practical takeaway is this. Jump between changed hunks in a diff with Alt+F5 (next change) and Shift+Alt+F5 (previous change) to scan for scope creep efficiently. Use Alt+F2 (Accessible View) on a Copilot-generated review summary to read the full text with arrow keys before posting. When leaving feedback, mention specific line numbers ("Line 42 skips from h2 to h4") so the author can navigate directly with Ctrl+G. The three review actions (Approve, Request Changes, Comment) are shown as clearly labeled radio buttons in the review submission form. Use the reviewer checklist in this section as a mental framework -- copy it into your notes and check items off as you review each PR. The diff view uses green and red backgrounds for added/removed lines; pair with a High Contrast theme if these colors are hard to distinguish.

      +

      Jamie: Let's pause on How Agents Are Discovered. What should a learner take away from it?

      +

      Alex: This is where How Agents Are Discovered becomes real: when you type @ in Copilot Chat, VS Code scans. That matters in practice: The Accessibility Agents ecosystem installs agents appropriate to each platform.

      +

      Alex: First,.github/agents/.agent.md in your current workspace. Then, any agents installed globally on your machine. After that, agents defined by extensions. It is a checklist, but a meaningful one: every item creates evidence that the next step is safe.

      +

      Alex: Keep the teaching thread moving. Keep the learner anchored in Optional: Personalize Your Instance. Open preferences.md in VS Code and edit. This is the part to say slowly: Commit preferences.md to your fork. A good GitHub workflow is like a well-run meeting: everyone knows the topic, the next action, and who has the floor.

      +

      Jamie: Let's pause on How Agents Travel with Your Repo. What should a learner take away from it?

      +

      Alex: The reason How Agents Travel with Your Repo matters is that when you fork accessibility-agents, the.github/agents/ folder comes with it.

      +

      Alex: The practical takeaway is this. Any collaborator who clones your fork gets all 55 agents automatically. You can customize agents for your specific project by editing the.agent.md files in your fork. Any project can have agents - create a.github/agents/ folder in any repository and add.agent.md files using the same pattern. The one-liner installer can also set up agents globally, so they are available in every workspace you open.

      -

      Alex: Keep the teaching thread moving. The reason Day 2 Teaser: The Full Accessibility Agents Review Ecosystem matters is that chapter 16 shows you how to leverage 50+ specialized agents to make your reviews faster, more consistent, and more thorough - while staying in full control of what you post. The interface gets friendlier when it stops being a wall of controls and starts being a set of named places.

      -

      Jamie: How should someone ask for help in a way that gets them unstuck faster?

      -

      Alex: Start with The Agents That Help With Code Review: Accessibility Review Agents (when code affects UI/UX).

      -

      Alex: The practical takeaway is this. @pr-review - Generates a full-draft PR review with line-numbered diff maps, risk assessment, before/after snapshots, and suggested inline comments. You edit and post it under your name. @pr-author-checklist - Before you even submit your PR, use this to verify you haven't missed setup steps, accessibility checks, or documentation. @insiders-a11y-tracker - Monitors your PR for accessibility-sensitive changes: WCAG violations, heading hierarchy issues, link text quality, keyboard navigation impacts. @developer-hub - Orchestrates explanations for unfamiliar code, patterns, or frameworks you're reviewing. @python-specialist - If your PR contains Python code, this agent explains patterns, spots accessibility issues, and suggests improvements. @wxpython-specialist - For desktop GUI code, helps verify accessible widget patterns and focus management.

      -

      Jamie: Let's pause on How It Works. What should a learner take away from it?

      -

      Alex: Start with How It Works. There is something to understand, something to try, and something that proves the try worked.

      -

      Alex: First, review manually first (you just did this with Exercises A, B, C). Then, run an agent - @pr-review review PR 14 generates a draft in seconds. After that, edit the agent's draft - you add context, remove noise, correct errors. Finally, post your review - it now has both AI efficiency and your human judgment. Treat it like a recipe: do not add the next ingredient until the previous one is actually in the bowl.

      -

      Jamie: Before we leave How It Works, what is the practical point?

      -

      Alex: First, the agent tracks impact - @insiders-a11y-tracker monitors whether your accessibility feedback was addressed. It is a checklist, but a meaningful one: every item creates evidence that the next step is safe.

      +

      Alex: Keep the teaching thread moving. Start with Invoking Agents on GitHub.com: Accessibility Agents agents run in VS Code. The next useful detail is this: But the same.agent.md files can also be invoked directly on GitHub.com - no VS Code, no local clone required.

      +

      Jamie: Let's pause on Option 1: Copilot Chat with Task mode. What should a learner take away from it?

      +

      Alex: Here is the plain-English version of Option 1: Copilot Chat with Task mode. Screen reader users (NVDA / JAWS / VoiceOver).

      +

      Alex: First, open Copilot Chat on GitHub.com (icon in the top-right navigation bar). Then, click Task in the mode picker. After that, optionally click the agent picker to select a custom agent. Finally, type your request and click Send. Treat it like a recipe: do not add the next ingredient until the previous one is actually in the bowl.

      +

      Jamie: Before we leave Option 1: Copilot Chat with Task mode, what is the practical point?

      +

      Alex: First, Copilot analyzes the task and can create a branch and open a PR automatically. Then, open Copilot Chat on GitHub.com (navigate to icon in top-right navigation → Enter). After that, the mode picker (Task vs Chat) is a set of radio buttons - navigate with Arrow keys to select "Task". Finally, the agent picker is a listbox - Up/Down Arrow to navigate, Enter to select. It is a checklist, but a meaningful one: every item creates evidence that the next step is safe.

      +

      Jamie: Let's pause on Option 2: Assign an issue to Copilot. What should a learner take away from it?

      +

      Alex: This is where Option 2: Assign an issue to Copilot becomes real: screen reader users (NVDA / JAWS / VoiceOver). That matters in practice: This is the bridge to Section 6 (The Cloud Extension). The workshop is closer to rehearsal than lecture. You hear the move, try the move, and then check what changed.

      +

      Alex: First, open any issue (or create a new one describing the task). Then, in the Assignees sidebar section, click the gear icon. After that, in the dropdown, click Copilot as the assignee. Finally, a dialog opens - optionally provide additional instructions and select a custom agent. It is a checklist, but a meaningful one: every item creates evidence that the next step is safe.

      +

      Jamie: Before we leave Option 2: Assign an issue to Copilot, what is the practical point?

      +

      Alex: First, click Assign to confirm. Then, open any issue in the repository. After that, press B to navigate to the Assignees gear button → Enter to open the popup. Finally, navigate the popup with Arrow keys → find "Copilot" → Enter to select. It is like walking a hallway with named doors: read the sign, enter the right room, then confirm where you landed.

      +

      Alex: A solid issue habit is to read the title, the body, and the timeline before acting. You are listening for the requested action, the missing evidence, and the person who needs a response.

      -

      Jamie: Let's pause on The Principle: Skill First, Agent Second. What should a learner take away from it?

      -

      Alex: This is where The Principle: Skill First, Agent Second becomes real: why do this manually before using agents? That matters in practice: Manual reviews teach you what to look for.

      -

      Alex: The practical takeaway is this. You understand what the agent is doing (you did it manually). You evaluate the agent's output critically (you know what right looks like). You add judgment the agent lacks (context, intent, team decisions). You verify the agent didn't miss anything important.

      -

      Jamie: Let's pause on A Real Example: The Flow. What should a learner take away from it?

      -

      Alex: Keep the learner anchored in A Real Example: The Flow. Manual Review (your work in part 1-2). This is the part to say slowly: Agent-Assisted Review (what you'll do in Chapter 19). A good GitHub workflow is like a well-run meeting: everyone knows the topic, the next action, and who has the floor.

      -

      Alex: The practical takeaway is this. Read diff, identify heading hierarchy skip. Write comment explaining why it matters. Submit your verdict.

      -

      Alex: First, run: @pr-review review PR 14. Then, agent generates a draft review covering the heading skip, link text, and 5 other issues. After that, you read the draft and notice: "the agent's explanation of the heading skip is good, but it missed that the link text on line 23 is still vague. Let me add that.". Finally, you post the agent's review + your additions. It is like walking a hallway with named doors: read the sign, enter the right room, then confirm where you landed.

      -

      Jamie: Before we leave A Real Example: The Flow, what is the practical point?

      -

      Alex: First, next time you review a similar PR, the agent works faster because it learned from your feedback. The rhythm is simple: orient, act, verify, then continue.

      -

      Jamie: Let's pause on How to Be an Effective and Respectful Open Source Contributor. What should a learner take away from it?

      -

      Alex: The reason How to Be an Effective and Respectful Open Source Contributor matters is that technical skills get your code into a project. That gives the learner a simple foothold: communication skills keep you welcomed in the community.

      +

      Jamie: There are a lot of tools in play. How do we keep that from feeling like a contest?

      +

      Alex: Keep the learner anchored in Copilot on GitHub.com - Browser-Native Features. Beyond assigning Copilot to issues and using Task mode in Chat, GitHub.com now has several standalone Copilot features built directly into the web interface. This is the part to say slowly: These work entirely in your browser - no VS Code, no local clone needed.

      +

      Alex: Keep the teaching thread moving. The reason Copilot PR Summary matters is that on any open pull request, GitHub adds a "Summarize" button in the PR description area. That gives the learner a simple foothold: selecting it generates a plain-language summary of what the PR changes, why, and what reviewers should focus on.

      +

      Jamie: Let's pause on Copilot PR Review. What should a learner take away from it?

      +

      Alex: Start with Copilot PR Review: On open PRs you have write access to review, a "Review" button (or Copilot icon) appears in the Files changed tab. The next useful detail is this: Copilot generates inline review comments across the diff.

      -

      Alex: Keep the teaching thread moving. Start with Workshop Recommendation (Chapter 8): Chapter 8 is a communication and culture chapter.

      -

      Alex: The practical takeaway is this. There are 1 guided reflection (no bot grading). Automation check: none - communication quality is too subjective for fair automated scoring. The evidence is structured reflection comment on your assigned challenge issue. The pattern is read, reflect, commit to one behavior.

      -

      Jamie: Let's pause on Chapter 8 Challenge Set. What should a learner take away from it?

      -

      Alex: Start with Chapter 8 Challenge Set. There is something to understand, something to try, and something that proves the try worked.

      -

      Alex: First, guided reflection - read the chapter, then post a short reflection comment committing to three specific collaboration behaviors. Treat it like a recipe: do not add the next ingredient until the previous one is actually in the bowl.

      -

      Jamie: Let's pause on Challenge 8.1 Step-by-Step: Guided Reflection. What should a learner take away from it?

      -

      Alex: This is where Challenge 8.1 Step-by-Step: Guided Reflection becomes real: identify three concrete communication behaviors you will practice during the rest of the workshop. That matters in practice: your assigned Chapter 8 challenge issue in your Learning Room repository on GitHub.com. The workshop is closer to rehearsal than lecture. You hear the move, try the move, and then check what changed.

      -

      Alex: The practical takeaway is this. 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.".

      -

      Alex: First, read through the chapter content below, paying attention to the sections on GitHub Flow, constructive feedback, and asking for help. Then, as you read, think about one situation from Day 1 where communication helped (or could have helped) you. After that, open your assigned Chapter 8 challenge issue (the one titled "Chapter 8.1: Guided Reflection (@yourname)"). Finally, scroll to the comment box at the bottom of the issue. It is a checklist, but a meaningful one: every item creates evidence that the next step is safe.

      -

      Jamie: Before we leave Challenge 8.1 Step-by-Step: Guided Reflection, what is the practical point?

      -

      Alex: First, post a reflection comment using this format. Then, for each prompt, write one specific, actionable sentence - not a vague goal. After that, activate the Comment button (or press Ctrl+Enter). It is like walking a hallway with named doors: read the sign, enter the right room, then confirm where you landed.

      +

      Alex: Keep the teaching thread moving. Here is the plain-English version of Copilot in Issues. On any issue page, Copilot adds sidebar buttons that appear once the page loads. Put another way, look in the right sidebar on any issue page for a Copilot section with "Explain" and "Suggest fix" buttons. It is like learning a transit route. The names of the stops matter because they tell you whether you are still going the right direction.

      +

      Alex: The practical takeaway is this. "Explain this issue" - generates a plain-language explanation of a complex technical issue. "Suggest fix" - proposes an approach to resolving the issue (opens a task/PR workflow).

      +

      Jamie: Let's pause on GitHub Models - Free AI Playground. What should a learner take away from it?

      +

      Alex: This is where GitHub Models - Free AI Playground becomes real: github.com/marketplace/models is a free playground where you can test AI models (OpenAI GPT-4o, Meta Llama 3, Mistral, Phi-4 Mini, and others) directly in your browser. That matters in practice: Why it matters for Accessibility Agents: When you build custom agents and prompts, you can test your system prompts and prompt templates in GitHub Models before adding them to your.prompt.md files - rapid iteration without burning API credits.

      +

      Alex: The practical takeaway is this. Send prompts to any listed model and compare responses side by side. Adjust parameters (temperature, max tokens) without any setup. Use the code sample generator to get API code for your chosen model. All free with a GitHub account (rate-limited for free tier).

      +

      Alex: Keep the teaching thread moving. Keep the learner anchored in Copilot-Drafted Release Notes. When creating a release (Releases tab → Draft a new release), GitHub provides a "Generate release notes" button. This is the part to say slowly: It scans merged PRs since the last release and drafts categorized release notes automatically.

      -

      Jamie: Let's pause on Completing Chapter 8: Submit Your Evidence. What should a learner take away from it?

      -

      Alex: Keep the learner anchored in Completing Chapter 8: Submit Your Evidence. The reflection comment itself is your evidence. This is the part to say slowly: The facilitator reviews your comment for specificity.

      -

      Alex: The practical takeaway is this. 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.

      -

      Jamie: Let's pause on If You Get Stuck. What should a learner take away from it?

      -

      Alex: Start with If You Get Stuck. There is something to understand, something to try, and something that proves the try worked.

      -

      Alex: First, use one simple sentence per prompt - do not overthink it. Then, focus on one real behavior you can start doing today, not an abstract principle. After that, if writing feels hard, draft bullet points first in a text editor, then paste into the comment. Finally, look at the "Giving Feedback" and "Asking for Help" sections in this chapter for concrete examples. Think of it as a rail line: each stop confirms you are still on the right route before the next one.

      -

      Jamie: Let's pause on If You Get Stuck. What should a learner take away from it?

      -

      Alex: First, ask facilitator for one example response and adapt it to your own words. Then, finished but not sure you did it right? Compare your work against the Challenge 8 reference solution. Treat it like a recipe: do not add the next ingredient until the previous one is actually in the bowl.

      +

      Jamie: What does someone need before they touch the keyboard?

      +

      Alex: Start with Learning Cards: Setup and Configuration. There is something to understand, something to try, and something that proves the try worked.

      +

      Alex: The practical takeaway is this. Run the installer command in the VS Code terminal (Ctrl+) -- it announces progress as it copies agent files to.github/agents/`. After installation, press Ctrl+Shift+E to open the Explorer and navigate to.github/agents/ to verify agent files are present. Edit.github/agents/preferences.md to configure your username, repositories, and notification preferences -- it is a standard Markdown file. The installer creates files in.github/agents/ and.github/prompts/ -- verify in the Explorer sidebar that these folders appeared. Open preferences.md in the editor to set your configuration -- use Ctrl+= to zoom if the YAML frontmatter is hard to read. Agent files use.agent.md extension -- they appear alongside regular Markdown files in the Explorer but are distinguished by their extension.

      +

      Alex: Keep the teaching thread moving. Start with 3. The Ecosystem: 55 Agents, 3 Teams, 5 Platforms: Accessibility Agents is an ecosystem of 55 specialized agents organized into three teams, each addressing a different dimension of accessible software development. The next useful detail is this: Browse all three teams below, then choose the agents that match your current skills and interests. Think of it like entering a new building: first you find the lobby, then the room, then the door you actually need.

      +

      Jamie: Let's pause on Team 1: Accessibility (26 agents). What should a learner take away from it?

      +

      Alex: Here is the plain-English version of Team 1: Accessibility (26 agents). These agents audit, fix, and enforce accessibility across web, document, and mobile platforms.

      -

      Alex: Keep the teaching thread moving. Here is the plain-English version of Learning Moment. Technical quality and communication quality work together. Put another way, respectful, clear communication helps good code get merged faster. It is like learning a transit route. The names of the stops matter because they tell you whether you are still going the right direction.

      -

      Jamie: If someone only remembers one thing from Learning Pattern Used in This Chapter, what should it be?

      -

      Alex: First, read and absorb community norms (not just rules, but reasons). Then, reflect on personal experience (what worked, what was hard). After that, commit to specific behaviors in writing (public accountability). Finally, apply those behaviors in upcoming chapters (reviews, comments, PRs). It is a checklist, but a meaningful one: every item creates evidence that the next step is safe.

      -

      Alex: Keep the teaching thread moving. Keep the learner anchored in 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. This is the part to say slowly: GitHub Flow is the lightweight branching model recommended for open source contribution.

      +

      Alex: Keep the teaching thread moving. This is where Team 2: GitHub Workflow (12 agents) becomes real: these agents automate GitHub operations - issue triage, PR review, contribution analytics, and repository management.

      +

      Jamie: What should someone listen for when a lesson offers more than one tool path?

      +

      Alex: Keep the learner anchored in Team 3: Developer Tools (6 agents). These agents support accessible application development across desktop and cross-platform frameworks.

      +

      Alex: Keep the teaching thread moving. The reason Beyond Agents: The Supporting Ecosystem matters is that the 55 agents are backed by additional resources in the repository. The interface gets friendlier when it stops being a wall of controls and starts being a set of named places.

      -

      Jamie: Let's pause on Why This Model Works. What should a learner take away from it?

      -

      Alex: Start with Why This Model Works. There is something to understand, something to try, and something that proves the try worked.

      -

      Alex: The practical takeaway is this. 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.

      -

      Alex: Keep the teaching thread moving. Start with GitHub Flow vs Git Flow: You may encounter "Git Flow" (sometimes written "GitFlow") in older projects or enterprise environments. The next useful detail is this: This section explains what Git Flow is, how it differs from GitHub Flow, and why this workshop teaches GitHub Flow. Think of it like entering a new building: first you find the lobby, then the room, then the door you actually need.

      -

      Jamie: Let's pause on What Git Flow Is. What should a learner take away from it?

      -

      Alex: Here is the plain-English version of What Git Flow Is. Git Flow is a branching model published by Vincent Driessen in 2010. Put another way, it was designed for teams that ship versioned releases on a schedule (desktop software, mobile apps, embedded systems).

      +

      Jamie: Let's pause on Hook-Based Enforcement (Claude Code). What should a learner take away from it?

      +

      Alex: Start with Hook-Based Enforcement (Claude Code): On Claude Code, Accessibility Agents includes a hook system that enforces accessibility standards automatically. The next useful detail is this: This means accessibility enforcement happens whether or not the developer remembers to ask for it.

      +

      Alex: First, proactive detection hook - scans every file edit for accessibility regressions before they are committed. Then, edit gate hook - blocks commits that introduce WCAG violations until they are fixed. After that, session marker hook - tracks which accessibility checks have run during the current session. Think of it as a rail line: each stop confirms you are still on the right route before the next one.

      +

      Alex: Keep the teaching thread moving. Here is the plain-English version of What Would You Build? This is the question that matters most. Put another way, the 55 agents that exist today were built by contributors who saw a gap and filled it.

      +

      Alex: The practical takeaway is this. "Why is there no agent for [framework] accessibility patterns?". "I spend 30 minutes on [task] every week - could an agent do the repetitive part?". "This agent is good but it misses [specific edge case] - I could improve those instructions". "Mobile native accessibility testing has no agent coverage yet - I could start one".

      +

      Jamie: Let's pause on The contribution paths are. What should a learner take away from it?

      +

      Alex: This is where The contribution paths are becomes real: see the Accessibility Agents CONTRIBUTING guide for detailed instructions on each path.

      +

      Alex: First, report an agent gap - file an issue describing what is missing and why it matters. Then, improve existing agent instructions - make an agent smarter about edge cases it misses. After that, add framework-specific patterns - teach agents about React, Vue, Angular, Svelte, or other framework accessibility patterns. Finally, fix installer issues - improve the one-liner scripts for different OS configurations. It is a checklist, but a meaningful one: every item creates evidence that the next step is safe.

      +

      Jamie: Before we leave The contribution paths are, what is the practical point?

      +

      Alex: First, write documentation - help others understand how to use and contribute to agents. It is like walking a hallway with named doors: read the sign, enter the right room, then confirm where you landed.

      -

      Jamie: Let's pause on How the Git Flow Cycle Works. What should a learner take away from it?

      -

      Alex: Start with How the Git Flow Cycle Works. There is something to understand, something to try, and something that proves the try worked.

      -

      Alex: First, developers branch feature/my-feature off develop and work there. Then, completed features merge back into develop via pull request. After that, when develop has enough features for a release, a release/1.2.0 branch is created. Finally, the release branch gets final testing, bug fixes, and version number updates. It is a checklist, but a meaningful one: every item creates evidence that the next step is safe.

      -

      Jamie: Before we leave How the Git Flow Cycle Works, what is the practical point?

      -

      Alex: First, the release branch merges into main (tagged with the version) and back into develop. Then, if a critical bug is found in production, a hotfix/ branch is created from main, fixed, and merged into both main and develop. It is like walking a hallway with named doors: read the sign, enter the right room, then confirm where you landed.

      -

      Jamie: Let's pause on How GitHub Flow Differs. What should a learner take away from it?

      -

      Alex: Keep the learner anchored in How GitHub Flow Differs. The following table compares GitHub Flow and Git Flow across key dimensions.

      -

      Alex: Keep the teaching thread moving. Start with When You Might See Git Flow. There is something to understand, something to try, and something that proves the try worked.

      -

      Alex: The practical takeaway is this. 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.

      +

      Alex: Keep the teaching thread moving. Keep the learner anchored in Roadmap: What Is Coming Next. Your contribution could be the next item that ships. This is the part to say slowly: Every agent started as one person's idea and one pull request. A good GitHub workflow is like a well-run meeting: everyone knows the topic, the next action, and who has the floor.

      +

      Alex: The practical takeaway is this. Mobile native agents - agents specialized for iOS (VoiceOver) and Android (TalkBack) native app accessibility. Anthropic Connectors listing - making agents discoverable through the Anthropic marketplace. veraPDF integration - automated PDF/UA validation for the PDF accessibility agent. Document remediation agents - agents that fix accessibility issues in documents, not just find them.

      +

      Jamie: Let's pause on Learning Cards: The Agent Ecosystem. What should a learner take away from it?

      +

      Alex: Start with Learning Cards: The Agent Ecosystem. There is something to understand, something to try, and something that proves the try worked.

      +

      Alex: The practical takeaway is this. The three team tables use standard Markdown table format -- navigate with T (NVDA/JAWS) to jump between tables, then Arrow keys to read cells. Agent names start with @ -- type @ followed by the agent name in Copilot Chat to invoke it (e.g., @daily-briefing). Use Ctrl+Shift+O (symbol outline) in any agent file to navigate between its YAML frontmatter sections (Purpose, Responsibilities, Guardrails). The agent tables are dense -- use Ctrl+= to increase font size or open the file in Markdown Preview (Ctrl+Shift+V) for cleaner rendering. Each team has a distinct table: Team 1 (Accessibility, 26 agents), Team 2 (GitHub Workflow, 15 agents), Team 3 (Developer Tools, 14 agents). Agent files in.github/agents/ have descriptive filenames that match the @agent-name -- browse them in the Explorer to find specific agents.

      +

      Alex: Keep the teaching thread moving. Start with 4. Agents in Detail - Hands-On Reference: This section walks through several agents in depth so you can see how they work, what they produce, and how to evaluate their output. The next useful detail is this: These examples use GitHub Workflow agents because they build directly on Day 1 skills - but the same patterns apply to every agent in the ecosystem.

      -

      Jamie: How should they picture the shape of the workshop?

      -

      Alex: Start with 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. The next useful detail is this: It is what GitHub itself uses and what most modern open source projects follow.

      -

      Alex: Keep the teaching thread moving. Here is the plain-English version of The Unwritten Rule: One Thing Per Branch. A branch and its PR should do one thing. Put another way, if you are fixing a broken link and you notice a typo nearby, fix the typo in a separate branch and PR.

      -

      Jamie: Let's pause on Learning Cards: GitHub Flow. What should a learner take away from it?

      -

      Alex: Start with Learning Cards: GitHub Flow. There is something to understand, something to try, and something that proves the try worked.

      -

      Alex: The practical takeaway is this. 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). 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.

      +

      Jamie: Let's pause on Two Types of Agents. What should a learner take away from it?

      +

      Alex: Here is the plain-English version of Two Types of Agents. Before diving in, it helps to know that custom agents fall into two categories - this distinction affects what tool permissions they need and what they can do. Put another way, informational agents search, analyze, and report.

      +

      Alex: Keep the teaching thread moving. This is where Agent 1: @daily-briefing - Morning Briefing becomes real: file.github/agents/daily-briefing.agent.md. That matters in practice: Before you run this agent: You should have manually navigated a repository's Issues tab, read your GitHub Notifications page, understood what a pull request waiting for review looks like, and know the difference between subscribed and participating. The workshop is closer to rehearsal than lecture. You hear the move, try the move, and then check what changed.

      +

      Jamie: Let's pause on What it does. What should a learner take away from it?

      +

      Alex: Keep the learner anchored in What it does. Sweeps every repository you have access to and builds a prioritized dashboard.

      +

      Alex: The practical takeaway is this. Issues opened in the last 24 hours. Pull requests waiting for your review. CI failures on your branches. Security and Dependabot alerts. Community reactions to your recent comments.

      -

      Alex: Keep the teaching thread moving. Keep the learner anchored in Keeping Your Fork Up to Date. When you fork a repository, you get a snapshot of the project at that moment. This is the part to say slowly: The original repository (called "upstream") continues to evolve. A good GitHub workflow is like a well-run meeting: everyone knows the topic, the next action, and who has the floor.

      -

      Jamie: Let's pause on Why Sync Your Fork? What should a learner take away from it?

      -

      Alex: Start with Why Sync Your Fork? There is something to understand, something to try, and something that proves the try worked.

      -

      Alex: The practical takeaway is this. 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.

      -

      Jamie: Let's pause on Method 1: GitHub Web Interface (Easiest). What should a learner take away from it?

      -

      Alex: Start with Method 1: GitHub Web Interface (Easiest): GitHub merges the upstream changes into your fork automatically. The next useful detail is this: Screen reader users (NVDA / JAWS / VoiceOver).

      -

      Alex: First, navigate to your fork's main page: github.com/your-username/repo-name. Then, look for the sync indicator: "This branch is X commits behind upstream/main". After that, click the "Sync fork" button. Finally, click "Update branch". Think of it as a rail line: each stop confirms you are still on the right route before the next one.

      -

      Jamie: Before we leave Method 1: GitHub Web Interface (Easiest), what is the practical point?

      -

      Alex: First, the sync button appears in the landmark that contains the branch selector. Then, press D to cycle through landmarks until you reach that region. After that, press B to cycle buttons until you hear "Sync fork" → press Enter. Finally, a dialog or page update presents "Update branch" - activate it. Treat it like a recipe: do not add the next ingredient until the previous one is actually in the bowl.

      +

      Alex: Keep the teaching thread moving. The reason Example commands matters is that the briefing output uses heading level 2 for each section. That gives the learner a simple foothold: use H key (NVDA/JAWS virtual mode) or VO+Command+H (VoiceOver) to jump between: Open Issues, Review Requests, CI Status, Security Alerts, Community Activity.

      +

      Jamie: Let's pause on Agent 2: @issue-tracker - Issue Management. What should a learner take away from it?

      +

      Alex: Start with Agent 2: @issue-tracker - Issue Management: File.github/agents/issue-tracker.agent.md. The next useful detail is this: Before you run this agent: You should have filed at least one issue using the full manual process - writing a title, description, and reproduction steps; applying labels and a milestone; and reading at least five existing issues to understand what a.

      +

      Alex: Keep the teaching thread moving. Here is the plain-English version of What it does. Finds, prioritizes, and helps you manage issues across all your repositories. It is like learning a transit route. The names of the stops matter because they tell you whether you are still going the right direction.

      +

      Alex: The practical takeaway is this. Cross-repository priority scoring with community sentiment. Batch-reply capability (draft replies to multiple issues at once). Saved search support. Release-awareness (flags issues that affect upcoming releases).

      Jamie: How should a learner choose a tool without feeling judged by the choice?

      -

      Alex: Here is the plain-English version of Method 2: Git Command Line (VS Code Terminal). If you're working locally in VS Code.

      -

      Jamie: Let's pause on One-time setup - add the upstream remote. What should a learner take away from it?

      -

      Alex: Start with One-time setup - add the upstream remote. There is something to understand, something to try, and something that proves the try worked.

      -

      Alex: Treat examples as spoken recipes, not decorations. You may hear something like git remote add upstream https://github.com/original-owner/repo-name.git; git remote -v Verify it was added. Read the command, understand what it changes, then run it only when the repository state matches the lesson.

      -

      Jamie: Let's pause on Sync process. What should a learner take away from it?

      -

      Alex: Start with Sync process. There is something to understand, something to try, and something that proves the try worked.

      -

      Alex: Treat examples as spoken recipes, not decorations. You may hear something like 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. Read the command, understand what it changes, then run it only when the repository state matches the lesson.

      +

      Alex: This is where Example commands becomes real: the agent can draft a reply. That matters in practice: You review the tone against the Culture & Etiquette guide before posting.

      +

      Jamie: What should happen before anyone copies and runs it?

      +

      Alex: Start with Output example. There is something to understand, something to try, and something that proves the try worked.

      +

      Alex: Treat examples as spoken recipes, not decorations. You may hear something like Open Issues Labeled "good-first-issue"; High Priority; - 45 [accessibility-agents] Add NVDA-specific navigation tips (3 comments, opened 5 days ago); - Priority Score: 8/10 (high community interest, clear scope, no assignee); - Recommended for: First-time. Read the command, understand what it changes, then run it only when the repository state matches the lesson.

      +

      Jamie: Let's pause on Agent 3: @pr-review - Pull Request Review. What should a learner take away from it?

      +

      Alex: The reason Agent 3: @pr-review - Pull Request Review matters is that file.github/agents/pr-review.agent.md. That gives the learner a simple foothold: before you run this agent: You should have manually reviewed at least one pull request diff in the GitHub browser interface - navigating the Files Changed tab with your screen reader, reading added and removed lines, leaving at least one inline comment, and.

      -

      Alex: Keep the teaching thread moving. Start with When to sync. There is something to understand, something to try, and something that proves the try worked.

      -

      Alex: The practical takeaway is this. 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).

      -

      Jamie: Let's pause on Method 3: GitHub Desktop. What should a learner take away from it?

      -

      Alex: Start with Method 3: GitHub Desktop. There is something to understand, something to try, and something that proves the try worked.

      -

      Alex: First, open GitHub Desktop. Then, select Repository → Pull to get your fork's latest. After that, select Branch → Merge into Current Branch. Finally, choose upstream/main. Think of it as a rail line: each stop confirms you are still on the right route before the next one.

      -

      Jamie: Before we leave Method 3: GitHub Desktop, what is the practical point?

      -

      Alex: First, push the changes to your fork on GitHub. Treat it like a recipe: do not add the next ingredient until the previous one is actually in the bowl.

      -

      Alex: Keep the teaching thread moving. Start with Learning Cards: Keeping Your Fork Up to Date. There is something to understand, something to try, and something that proves the try worked.

      -

      Alex: The practical takeaway is this. 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. 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.

      +

      Alex: Keep the teaching thread moving. Start with What it does: Generates full review documents for pull requests. Think of it like entering a new building: first you find the lobby, then the room, then the door you actually need.

      +

      Alex: The practical takeaway is this. Line-numbered diffs with change maps. Risk assessment (what could break, what is high-impact). Before-and-after snapshots. CI results and test coverage information. Suggested inline review comments with line number references.

      +

      Jamie: How do we make tool choice feel like access, not pressure?

      +

      Alex: Here is the plain-English version of Example commands. Critical rule: Read the agent's review. Put another way, the agent produces a starting point - it does not know the project's history, the contributor's background, or the community's implicit standards the way you do.

      +

      Jamie: How do you keep commands from becoming magic words?

      +

      Alex: Treat examples as spoken recipes, not decorations. You may hear something like PR Review: 14 - Improve screen reader navigation guide; Summary; This PR adds 3 new sections to the screen reader navigation guide and updates 2 existing sections with NVDA-specific keyboard shortcuts.; Files Changed: 1; Lines Added: 127; Lines Removed: 18. Read the command, understand what it changes, then run it only when the repository state matches the lesson.

      -

      Jamie: Let's pause on Writing Good Commit Messages. What should a learner take away from it?

      -

      Alex: This is where Writing Good Commit Messages becomes real: every commit you make includes a message describing what changed. That matters in practice: Good commit messages make project history understandable months or years later.

      -

      Alex: Keep the teaching thread moving. Keep the learner anchored in The First Line (Required). This is the commit summary that appears in logs and GitHub's commit list. This is the part to say slowly: Think of it as an email subject line.

      -

      Alex: The practical takeaway is this. fix: - bug fix. feat: - new feature. docs: - documentation only. style: - formatting, no code change.

      -

      Jamie: Let's pause on The Body (Optional). What should a learner take away from it?

      -

      Alex: The reason The Body (Optional) matters is that if the summary isn't enough, add a body explaining. That gives the learner a simple foothold: leave a blank line between the summary and the body.

      -

      Alex: The practical takeaway is this. Why you made the change (more important than what). What trade-offs you considered. How the change affects behavior.

      -

      Alex: Treat examples as spoken recipes, not decorations. You may hear something like 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. Read the command, understand what it changes, then run it only when the repository state matches the lesson.

      +

      Jamie: Let's pause on Agent 4: @analytics - Team Analytics. What should a learner take away from it?

      +

      Alex: Keep the learner anchored in Agent 4: @analytics - Team Analytics. File.github/agents/analytics.agent.md. This is the part to say slowly: Before you run this agent: You should have explored the Insights tab of at least one repository - looked at the contribution graph, understood what commit frequency means, and thought about what "high-churn files" implies for a project's stability.

      +

      Alex: Keep the teaching thread moving. The reason What it does matters is that surfaces team contribution patterns, velocity metrics, and bottleneck detection. The interface gets friendlier when it stops being a wall of controls and starts being a set of named places.

      +

      Alex: The practical takeaway is this. Contribution velocity over time. Review turnaround time by reviewer. Code hotspot detection (files with the most churn). Workload distribution across contributors.

      +

      Jamie: What stays the same when the tool changes?

      +

      Alex: Start with Example commands: Accessibility use case: After Day 2's contribution wave, run @analytics team velocity in accessibility-agents today to see the hackathon's collective output. The next useful detail is this: A moment of real-time team celebration.

      -

      Alex: Keep the teaching thread moving. Start with The Footer (Optional): When the commit is merged, GitHub automatically closes linked issues. Think of it like entering a new building: first you find the lobby, then the room, then the door you actually need.

      -

      Jamie: Let's pause on Atomic Commits. What should a learner take away from it?

      -

      Alex: Here is the plain-English version of Atomic Commits. Each commit should represent one logical change. Put another way, don't bundle unrelated fixes into a single commit.

      -

      Alex: Keep the teaching thread moving. Start with Common mistakes to avoid. There is something to understand, something to try, and something that proves the try worked.

      -

      Alex: The practical takeaway is this. "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.

      +

      Alex: Keep the teaching thread moving. Here is the plain-English version of Agent 5: @insiders-a11y-tracker - Accessibility Change Monitoring. File.github/agents/insiders-a11y-tracker.agent.md. Put another way, before you run this agent: You should have filed at least one accessibility bug report using the workshop's issue template, applied a WCAG label to an issue, and manually reviewed a Markdown file for heading hierarchy - knowing what H1 means, what H2 means,.

      +

      Jamie: Before we leave What it does, what is the practical point?

      +

      Alex: This is where What it does becomes real: monitors accessibility-sensitive changes across configured repositories.

      +

      Alex: The practical takeaway is this. WCAG/ARIA cross-referenced change tracking. Flags changes to keyboard navigation, ARIA attributes, focus management, color usage. Monitors for heading hierarchy violations in Markdown. Tracks link text quality (flags bare URLs, non-descriptive labels).

      +

      Alex: Keep the teaching thread moving. Keep the learner anchored in Example commands. Day 2 workflow: Run this before submitting any PR. This is the part to say slowly: If the agent flags an issue, fix it before requesting review - not after. A good GitHub workflow is like a well-run meeting: everyone knows the topic, the next action, and who has the floor.

      -

      Jamie: Let's pause on Good commit messages in practice. What should a learner take away from it?

      -

      Alex: Keep the learner anchored in Good commit messages in practice. When you make a habit of writing good commit messages, you build trust. This is the part to say slowly: Maintainers see that you care about the project's long-term health, not just your immediate contribution.

      -

      Alex: Treat examples as spoken recipes, not decorations. You may hear something like 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. Read the command, understand what it changes, then run it only when the repository state matches the lesson.

      -

      Alex: Keep the teaching thread moving. Start with Learning Cards: Writing Good Commit Messages. There is something to understand, something to try, and something that proves the try worked.

      -

      Alex: The practical takeaway is this. 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. 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.

      -

      Jamie: Let's pause on The Nature of Open Source Communication. What should a learner take away from it?

      -

      Alex: Start with The Nature of Open Source Communication: Open source collaboration happens primarily in writing, asynchronously, in public. The next useful detail is this: Understanding these three characteristics shapes everything about how we communicate.

      +

      Jamie: Let's pause on Agent 6: @template-builder - Interactive Issue Template Wizard. What should a learner take away from it?

      +

      Alex: The reason Agent 6: @template-builder - Interactive Issue Template Wizard matters is that file.github/agents/template-builder.agent.md. That gives the learner a simple foothold: before you run this agent: You should have read Issue Templates thoroughly - understanding YAML field types, creating a template manually (Exercise B), and designing your own template (Exercise D).

      +

      Alex: Keep the teaching thread moving. Start with What it does: An interactive wizard that guides you through building GitHub issue templates step-by-step using VS Code's Ask Questions feature. The next useful detail is this: Instead of writing YAML syntax, answer simple questions and the agent generates production-ready templates.

      +

      Jamie: What is the common workflow underneath the different interfaces?

      +

      Alex: Here is the plain-English version of Example commands. Manual YAML template creation takes 15-20 minutes and is error-prone. Put another way, the Template Builder generates correct, tested templates in 2-3 minutes via guided questions.

      -

      Alex: Keep the teaching thread moving. Start with In writing. There is something to understand, something to try, and something that proves the try worked.

      -

      Alex: The practical takeaway is this. 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.".

      -

      Jamie: Let's pause on Asynchronously. What should a learner take away from it?

      -

      Alex: Start with Asynchronously. There is something to understand, something to try, and something that proves the try worked.

      -

      Alex: The practical takeaway is this. 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.

      -

      Alex: Keep the teaching thread moving. Start with In public. There is something to understand, something to try, and something that proves the try worked.

      -

      Alex: The practical takeaway is this. 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.

      +

      Alex: Keep the teaching thread moving. This is where 5. Slash Commands and Prompts becomes real: the repository includes 54+ slash commands defined as.prompt.md files in.github/prompts/. That matters in practice: Type / in Copilot Chat to see the full command menu. The workshop is closer to rehearsal than lecture. You hear the move, try the move, and then check what changed.

      +

      Jamie: Where does the workshop stop being a tour and start becoming contribution?

      +

      Alex: Keep the learner anchored in Workshop Slash Command Quick Reference. The commands listed below are the ones most relevant to this workshop. This is the part to say slowly: The full repository contains 54+ commands covering accessibility auditing, document scanning, framework-specific checks, and more.

      +

      Alex: Keep the teaching thread moving. The reason Reading Slash Command Definitions matters is that each /command corresponds to a.prompt.md file in.github/prompts/. That gives the learner a simple foothold: open any of them in VS Code to read what instructions it gives Copilot.

      -

      Jamie: What do we want them to notice before they start over?

      -

      Alex: The reason The Anatomy of Helpful Feedback matters is that whether commenting on an issue, reviewing a PR, or responding to a question, effective feedback has a structure.

      -

      Alex: Keep the teaching thread moving. Start with 1. Acknowledge what's working: Before identifying problems, name what is good. The next useful detail is this: This is not flattery - it is accuracy.

      -

      Jamie: Let's pause on 2. Identify the specific concern. What should a learner take away from it?

      -

      Alex: Here is the plain-English version of 2. Identify the specific concern. "This code is inaccessible." "This button has no accessible name - aria-label or visible text is needed for screen readers to announce its purpose.".

      +

      Jamie: Let's pause on Example: /a11y-update. What should a learner take away from it?

      +

      Alex: Start with Example: /a11y-update: File.github/prompts/a11y-update.prompt.md. The next useful detail is this: This is how you learn to write your own.

      +

      Alex: Keep the teaching thread moving. Start with Learning Cards: Slash Commands and Prompts. There is something to understand, something to try, and something that proves the try worked.

      +

      Alex: The practical takeaway is this. Type / in Copilot Chat to see all available slash commands -- your screen reader announces each command name as you arrow through the list. Slash commands are defined in.github/prompts/ as.prompt.md files -- open them in the Explorer to read what each command does before using it. Create your own command by copying an existing.prompt.md file, renaming it, and editing the instructions -- no code required. The / command menu appears as a dropdown list in Copilot Chat -- it scales with VS Code's font and zoom settings. Each command has a short description visible in the dropdown; use Ctrl+= to zoom if the text is too small. Open the.prompt.md file in the editor to read the full command definition at your preferred zoom level.

      +

      Jamie: Let's pause on 6. Contributing to the Ecosystem. What should a learner take away from it?

      +

      Alex: This is where 6. Contributing to the Ecosystem becomes real: the 55 Accessibility Agents and 54+ slash commands are starting points. That matters in practice: The.agent.md format is open - you can create your own agents for any repeatable workflow, and contribute them back to the project.

      -

      Alex: Keep the teaching thread moving. This is where 3. Explain why it matters becomes real: context turns a complaint into a lesson. That matters in practice: It also respects the contributor - they deserve to understand, not just comply. The workshop is closer to rehearsal than lecture. You hear the move, try the move, and then check what changed.

      -

      Jamie: Let's pause on 4. Suggest a path forward (when you can). What should a learner take away from it?

      -

      Alex: Keep the learner anchored in 4. Suggest a path forward (when you can). If you have an idea for a solution, offer it as a suggestion, not a mandate. This is the part to say slowly: "Something like aria-label='Close navigation menu' would work well here.

      -

      Alex: Keep the teaching thread moving. The reason 5. Signal the weight of the concern matters is that help contributors understand what is a blocker versus a preference.

      -

      Alex: The practical takeaway is this. 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.

      +

      Alex: Keep the teaching thread moving. Keep the learner anchored in Two Types of Custom Agents. Informational agents - conversational; search, analyze, and present results. This is the part to say slowly: Task-oriented agents - active; edit files, run commands, submit PRs.

      +

      Alex: The practical takeaway is this. Perform GitHub searches with predefined scopes and filters. Present results in specific structured formats. Query GitHub API tools to answer questions. Execute external tools (linters, test suites, axe-core).

      +

      Jamie: Let's pause on Agent File Structure. What should a learner take away from it?

      +

      Alex: The reason Agent File Structure matters is that see also: Appendix L: Agents Reference has the complete agent.md format specification and examples. That gives the learner a simple foothold: every.agent.md file has two parts: YAML frontmatter (metadata) and a system prompt (markdown body).

      +

      Alex: Keep the teaching thread moving. Start with Frontmatter fields: Restricting tool access is a security best practice - only grant what the agent actually needs. Think of it like entering a new building: first you find the lobby, then the room, then the door you actually need.

      -

      Jamie: Let's pause on Prefer "we" or describe the code, not the person. What should a learner take away from it?

      -

      Alex: Start with 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.".

      -

      Alex: Keep the teaching thread moving. Here is the plain-English version of 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?". It is like learning a transit route. The names of the stops matter because they tell you whether you are still going the right direction.

      -

      Jamie: Let's pause on Acknowledge cultural and language diversity. What should a learner take away from it?

      -

      Alex: This is where Acknowledge cultural and language diversity becomes real: when reading someone's comment: Assume good intent unless there is clear evidence otherwise. That matters in practice: When writing: Choose plain words over clever ones.

      -

      Alex: The practical takeaway is this. 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.

      +

      Jamie: Let's pause on Example: Informational Agent - @insiders-a11y-tracker. What should a learner take away from it?

      +

      Alex: Here is the plain-English version of Example: Informational Agent - @insiders-a11y-tracker. This agent monitors VS Code Insiders releases for accessibility improvements. Put another way, it searches the microsoft/vscode repository using predefined GitHub query syntax, so you never have to remember the exact filter parameters.

      +

      Jamie: Let's pause on Use it. What should a learner take away from it?

      +

      Alex: This is where Use it becomes real: prerequisite: GitHub MCP server installed (github.com/github/github-mcp-server).

      +

      Alex: First, select @insiders-a11y-tracker from the agent picker. Then, ask: what shipped this month? or any keyboard navigation improvements in January? After that, the agent searches with repo:microsoft/vscode is:closed milestone:"[Month] [Year]" label:accessibility label:insiders-released and returns formatted results. It is a checklist, but a meaningful one: every item creates evidence that the next step is safe.

      +

      Jamie: Let's pause on Example: Task-Oriented Agent - The Markdown Accessibility Assistant. What should a learner take away from it?

      +

      Alex: Keep the learner anchored in Example: Task-Oriented Agent - The Markdown Accessibility Assistant. The GitHub Accessibility team published a complete walkthrough for building a Markdown Accessibility Assistant - a task-oriented agent that reviews Markdown files for accessibility issues and makes direct fixes. This is the part to say slowly: This agent is the automated version of the accessibility review skills you built during Day 1.

      +

      Alex: The practical takeaway is this. Runs markdownlint-cli2 to catch structural problems (heading skips, bare URLs, missing blank lines). Reviews link text for descriptiveness. Flags missing or inadequate alt text and waits for your approval before changing it (alt text requires human judgment). Fixes heading hierarchy, list structure, and bare URL formatting directly.

      -

      Alex: Keep the teaching thread moving. Keep the learner anchored in 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?".

      -

      Jamie: Let's pause on Keep comments focused. What should a learner take away from it?

      -

      Alex: The reason Keep comments focused matters is that each comment should address one concern. That gives the learner a simple foothold: if you have three issues, leave three comments - unless they are closely related.

      -

      Alex: Keep the teaching thread moving. Start with Don't leave comments unresolved: If you asked a question and got an answer, respond. The next useful detail is this: "Thanks, that makes sense" or resolving the conversation thread signals that the thread is complete. Think of it like entering a new building: first you find the lobby, then the room, then the door you actually need.

      +

      Alex: Keep the teaching thread moving. The reason Key Pattern: Tiered Decision-Making matters is that this tiered approach - automate what can be objectively evaluated, flag what needs human judgment - is the right model for any accessibility agent. That gives the learner a simple foothold: it maximizes the agent's value while keeping humans in control of decisions that require context. The interface gets friendlier when it stops being a wall of controls and starts being a set of named places.

      +

      Jamie: Let's pause on Required Prerequisites for the Markdown Accessibility Assistant. What should a learner take away from it?

      +

      Alex: Start with Required Prerequisites for the Markdown Accessibility Assistant. There is something to understand, something to try, and something that proves the try worked.

      +

      Alex: The practical takeaway is this. GitHub MCP server installed and configured (github.com/github/github-mcp-server). Node.js installed (for npx markdownlint-cli2).

      +

      Jamie: Let's pause on From VS Code. What should a learner take away from it?

      +

      Alex: Start with From VS Code. There is something to understand, something to try, and something that proves the try worked.

      +

      Alex: First, open Copilot Chat (Ctrl+Shift+I / Cmd+Shift+I on macOS). Then, in the Chat input toolbar, select the Set Agent button. After that, select your custom agent from the agent picker. Finally, type your request - the agent executes in your local workspace. Treat it like a recipe: do not add the next ingredient until the previous one is actually in the bowl.

      -

      Jamie: Let's pause on Resolving conversations. What should a learner take away from it?

      -

      Alex: Here is the plain-English version of Resolving conversations. On a PR, conversations (inline comment threads) can be "resolved" once addressed. Put another way, the author of the change and the reviewer can both resolve them.

      -

      Alex: Keep the teaching thread moving. This is where Do not "pile on" becomes real: if five people already said the same thing about an issue, you don't need to add a sixth comment saying the same thing. That matters in practice: A reaction on an existing comment is enough.

      -

      Jamie: Let's pause on Reactions. What should a learner take away from it?

      -

      Alex: Keep the learner anchored in Reactions. GitHub reactions () are an efficient way to express agreement, appreciation, or concern without adding noise to a thread.

      +

      Jamie: Let's pause on From GitHub.com (Task mode). What should a learner take away from it?

      +

      Alex: Start with From GitHub.com (Task mode). There is something to understand, something to try, and something that proves the try worked.

      +

      Alex: First, open Copilot Chat on GitHub.com. Then, select Task from the mode picker. After that, optionally select a custom agent from the agent picker. Finally, submit your request - the agent can create a PR automatically. It is a checklist, but a meaningful one: every item creates evidence that the next step is safe.

      +

      Jamie: Let's pause on From an issue (Issue Assignment). What should a learner take away from it?

      +

      Alex: Start with From an issue (Issue Assignment). There is something to understand, something to try, and something that proves the try worked.

      +

      Alex: First, open any issue → Assignees → assign Copilot. Then, in the dialog, optionally select a custom agent. After that, select Assign - Copilot creates a branch, makes changes, and opens a PR. It is like walking a hallway with named doors: read the sign, enter the right room, then confirm where you landed.

      +

      Jamie: What is the pre-flight check here?

      +

      Alex: The reason Environment Setup for GitHub (Cloud Agents) matters is that when agents run on GitHub (not locally), they may need additional tools. That gives the learner a simple foothold: create a workflow file at.github/workflows/copilot-setup-steps.yml with a single job named copilot-setup-steps.

      -

      Alex: Keep the teaching thread moving. The reason Saved Replies - Your Accessibility Win matters is that GitHub lets you save frequently used responses as Saved Replies - reusable text snippets you can insert into any comment box with a few keystrokes. That gives the learner a simple foothold: this is a significant accessibility win for anyone who types the same comments repeatedly during triage, reviews, or issue management. The interface gets friendlier when it stops being a wall of controls and starts being a set of named places.

      -

      Jamie: Let's pause on Common uses. What should a learner take away from it?

      -

      Alex: Start with Common uses. There is something to understand, something to try, and something that proves the try worked.

      -

      Alex: The practical takeaway is this. "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.

      -

      Jamie: Let's pause on Creating a Saved Reply. What should a learner take away from it?

      -

      Alex: Start with Creating a Saved Reply. There is something to understand, something to try, and something that proves the try worked.

      -

      Alex: First, navigate to github.com/settings/replies. Then, activate "Add a saved reply". After that, give it a title (e.g., "Good first issue claim") - this is what you search. Finally, type the full reply text in the body (Markdown is supported). Treat it like a recipe: do not add the next ingredient until the previous one is actually in the bowl.

      +

      Jamie: Let's pause on To Create Your Own Agent. What should a learner take away from it?

      +

      Alex: Start with To Create Your Own Agent. There is something to understand, something to try, and something that proves the try worked.

      +

      Alex: First, create.github/agents/your-agent-name.agent.md. Then, write YAML frontmatter (name, description, tools). After that, write the system prompt - identity, capabilities, domain knowledge, behavioral rules, output format. Finally, save and reload VS Code (Ctrl+Shift+P → "Reload Window"). Think of it as a rail line: each stop confirms you are still on the right route before the next one.

      +

      Jamie: Before we leave To Create Your Own Agent, what is the practical point?

      +

      Alex: First, type @your-agent-name in Copilot Chat. Treat it like a recipe: do not add the next ingredient until the previous one is actually in the bowl.

      +

      Jamie: How do these exercises create confidence instead of pressure?

      +

      Alex: Here is the plain-English version of Exercise: Extend the Template Builder Agent. You've built templates manually (Chapters 15-16) and seen them in action. Put another way, now see how to harness AI to generate templates interactively, and learn to customize agents for your own projects.

      +

      Alex: The practical takeaway is this. Complete Chapters 15-16 (especially Exercise D - designing your own template). VS Code is installed and GitHub Copilot is active. You have forked accessibility-agents to your GitHub account. You have cloned your fork locally: git clone https://github.com/[your-username]/accessibility-agents.git.

      +

      Jamie: Let's pause on Exercise 1: Generate a Template with the Agent. What should a learner take away from it?

      +

      Alex: This is where Exercise 1: Generate a Template with the Agent becomes real: your Mission: Use the @template-builder agent to generate an accessibility bug report template interactively. That matters in practice: You'll experience the agent as an end-user and see what production-ready agent output looks like. The workshop is closer to rehearsal than lecture. You hear the move, try the move, and then check what changed.

      +

      Alex: The practical takeaway is this. Left sidebar showing.github/, docs/, learning-room/, README.md, etc. The status bar at the bottom shows your current git branch (probably main). Alternative: Use menu: View → Copilot Chat. Copilot is now ready to receive instructions.

      +

      Alex: First, open VS Code. Then, file → Open Folder → select your locally cloned accessibility-agents folder. After that, the folder tree appears on the left showing the repository structure. Finally, verify you're in the right place: The folder name should be accessibility-agents at the top of the sidebar. It is a checklist, but a meaningful one: every item creates evidence that the next step is safe.

      +

      Jamie: Before we leave Exercise 1: Generate a Template with the Agent, what is the practical point?

      +

      Alex: First, keyboard shortcut: Press Ctrl+Shift+I (Windows/Linux) or Cmd+Shift+I (macOS). Then, a chat panel opens on the right side of VS Code. After that, at the top, you see "Copilot Chat" and probably a text input at the bottom saying "Ask Copilot.". Finally, click in the chat input box (bottom of Copilot Chat panel). It is like walking a hallway with named doors: read the sign, enter the right room, then confirm where you landed.

      +

      Alex: Treat examples as spoken recipes, not decorations. You may hear something like Q: Template name?; A: Accessibility Bug Report; Q: What's it for?; A: Report screen reader and keyboard navigation issues; Q: First field name?; A: Screen Reader; Q: Field type?; A: dropdown; Q: Dropdown options? (comma-separated); A: NVDA, JAWS, VoiceOver,. Read the command, understand what it changes, then run it only when the repository state matches the lesson.

      -

      Jamie: Let's pause on Using a Saved Reply in a comment. What should a learner take away from it?

      -

      Alex: Start with Using a Saved Reply in a comment. There is something to understand, something to try, and something that proves the try worked.

      -

      Alex: First, navigate to any comment text area. Then, activate the Saved Replies button (the speech bubble icon in the comment toolbar, or press Ctrl+. if enabled). After that, a dropdown appears showing your saved replies - type to filter by title. Finally, select the reply - it inserts into the text area. It is a checklist, but a meaningful one: every item creates evidence that the next step is safe.

      -

      Jamie: Before we leave Using a Saved Reply in a comment, what is the practical point?

      -

      Alex: First, edit as needed before submitting. It is like walking a hallway with named doors: read the sign, enter the right room, then confirm where you landed.

      -

      Alex: Keep the teaching thread moving. Keep the learner anchored in Screen reader path. Limit: GitHub allows up to 100 saved replies per account. A good GitHub workflow is like a well-run meeting: everyone knows the topic, the next action, and who has the floor.

      -

      Jamie: Let's pause on Learning Cards: Commenting Etiquette. What should a learner take away from it?

      -

      Alex: Start with Learning Cards: Commenting Etiquette. There is something to understand, something to try, and something that proves the try worked.

      -

      Alex: The practical takeaway is this. 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. 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.

      +

      Jamie: Let's pause on Exercise 2: Extend the Agent for Your Project. What should a learner take away from it?

      +

      Alex: Keep the learner anchored in Exercise 2: Extend the Agent for Your Project. Your Mission: Customize the Template Builder agent to recognize and guide a Security Vulnerability Report template. This is the part to say slowly: This teaches you how to tailor agents for project-specific needs.

      +

      Alex: The practical takeaway is this. The file starts with YAML frontmatter (name, description, topics). Below that, sections like " How to Use", " Pre-Built Workflow". Search for the text "Pre-Built Workflow: Guided Accessibility Template".

      +

      Alex: First, in VS Code, navigate to.github/agents/. Then, file: template-builder.agent.md. After that, double-click to open it in the editor. Finally, you see the agent's instructions in Markdown format. It is like walking a hallway with named doors: read the sign, enter the right room, then confirm where you landed.

      +

      Jamie: Before we leave Exercise 2: Extend the Agent for Your Project, what is the practical point?

      +

      Alex: First, use Ctrl+F to open Find. Then, search for: Pre-Built Workflow. After that, press Enter to jump to the first match. Finally, you should land on the "Pre-Built Workflow: Guided Accessibility Template" section. The rhythm is simple: orient, act, verify, then continue.

      +

      Jamie: Let's pause on What you're adding. What should a learner take away from it?

      +

      Alex: The reason What you're adding matters is that if the agent doesn't recognize your new workflow.

      +

      Alex: The practical takeaway is this. A clear label for the new workflow. Instructions on how to invoke it. Pre-defined fields that make sense for security reports. Specific options for severity and vulnerability type. The agent recognizes your new workflow. Next time you invoke @template-builder with "create security template", it will follow your new guidance.

      +

      Alex: First, save the file: Ctrl+S. Then, you should see no error messages. After that, the agent file now includes your new Pre-Built Workflow. Finally, open Copilot Chat again: Ctrl+Shift+I. The rhythm is simple: orient, act, verify, then continue.

      +

      Jamie: Before we leave What you're adding, what is the practical point?

      +

      Alex: First, press Enter. Then, the agent should now ask vulnerability-specific questions. After that, commit your agent change. Finally, the extended agent is now in your fork. Think of it as a rail line: each stop confirms you are still on the right route before the next one.

      +

      Alex: Treat examples as spoken recipes, not decorations. You may hear something like git add.github/agents/template-builder.agent.md; git commit -m "feat: add security vulnerability template workflow to template-builder agent"; git push origin main. Read the command, understand what it changes, then run it only when the repository state matches the lesson.

      +

      Jamie: Let's pause on Exercise 3: Iterative Refinement with Agents. What should a learner take away from it?

      +

      Alex: Start with Exercise 3: Iterative Refinement with Agents: Your Mission: Generate a template, then ask the agent to modify it incrementally. The next useful detail is this: This teaches you the iterative pattern that scales to all agent-assisted workflows.

      +

      Alex: The practical takeaway is this. Running a complete template generation (same as Exercise 1). The agent modifies the YAML it generated. The new checkbox appears in the YAML with proper formatting and indentation. It doesn't regenerate from scratch - just adds your change.

      +

      Alex: First, in Copilot Chat, type: @template-builder create a feature request template. Then, answer the agent's questions to build a feature request form. After that, let the agent generate the YAML. Finally, copy it to a file.github/ISSUE TEMPLATE/feature-request.yml. Think of it as a rail line: each stop confirms you are still on the right route before the next one.

      +

      Jamie: Before we leave Exercise 3: Iterative Refinement with Agents, what is the practical point?

      +

      Alex: First, once the template is generated, while still in the same chat conversation, ask. Then, the agent regenerates the YAML with your new checkbox added in the right place (usually as required field pre-validation). After that, follow up. Finally, the agent modifies the textarea field's attributes to enable code highlighting. Treat it like a recipe: do not add the next ingredient until the previous one is actually in the bowl.

      -

      Alex: Keep the teaching thread moving. Start with 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.".

      -

      Jamie: Let's pause on Don't gatekeep knowledge. What should a learner take away from it?

      -

      Alex: Here is the plain-English version of Don't gatekeep knowledge. If a contributor makes a mistake because they didn't know something, explain the concept.

      -

      Alex: Keep the teaching thread moving. This is where Ask questions instead of making demands becomes real: "Change this to use aria-label." "What do you think about using aria-label here instead? That matters in practice: Screen readers would then announce the button's purpose directly.". The workshop is closer to rehearsal than lecture. You hear the move, try the move, and then check what changed.

      +

      Jamie: Let's pause on What Comes Next. What should a learner take away from it?

      +

      Alex: Here is the plain-English version of What Comes Next. Your next step: explore the broader ecosystem. Put another way, that is Accessibility Agents' promise: not to replace your thinking, but to amplify your skills across all 55 agents - and to grow through the contributions of everyone who uses it. It is like learning a transit route. The names of the stops matter because they tell you whether you are still going the right direction.

      +

      Alex: The practical takeaway is this. Browse the full agent list - which agents solve problems you face regularly? Try an Accessibility team agent: @contrast-master check this page or @alt-text-headings review this file. Try a Developer Tools agent: @python-specialist review this module for accessibility or @desktop-a11y-specialist audit this dialog. Think about what is missing: what agent would you build if you could?

      +

      Alex: First, generated a template using an agent (Exercise 1). Then, customized an agent for your domain (Exercise 2). After that, refined iteratively with agent help (Exercise 3). Treat it like a recipe: do not add the next ingredient until the previous one is actually in the bowl.

      +

      Jamie: Let's pause on Learning Cards: Contributing to the Ecosystem. What should a learner take away from it?

      +

      Alex: Start with Learning Cards: Contributing to the Ecosystem. There is something to understand, something to try, and something that proves the try worked.

      +

      Alex: The practical takeaway is this. Agent.agent.md files use YAML frontmatter at the top (between --- delimiters) followed by Markdown body; in VS Code, use Ctrl+G to jump to line 1 and arrow through the frontmatter fields (name, description, tools) before reading the body instructions. When writing your own.agent.md, use VS Code's Outline view (Ctrl+Shift+O) to verify that your Markdown headings (Purpose, Capabilities, Responsibilities) are correctly nested -- malformed headings will not appear in the outline. Before submitting a PR with a new agent file, run the file through a YAML linter (install the YAML extension, or use yamllint from the terminal) -- frontmatter syntax errors silently break agent registration. YAML frontmatter fields are densely packed with colons and quotes; increase your editor font size or use a monospaced font with wide character spacing so name:, description:, and tools: are clearly distinct. The.agent.md files in the agents/ directory follow a consistent structure -- use the file explorer's icon theme or file nesting feature to visually group agent files separately from regular documentation. When reviewing existing agents for contribution ideas, use VS Code's split editor to place the agent file and the README side by side so you can cross-reference the agent's instructions with its documented capabilities.

      +

      Alex: Keep the teaching thread moving. Keep the learner anchored in 7. The Bigger Picture: Teams, Orchestration, and Beyond VS Code. The 55 agents are not 55 independent tools. This is the part to say slowly: They are organized into three teams that work together, and several orchestrator agents exist specifically to coordinate multi-agent workflows.

      -

      Jamie: Let's pause on Distinguish opinion from requirement. What should a learner take away from it?

      -

      Alex: Keep the learner anchored in Distinguish opinion from requirement. If something is your stylistic preference but NOT a bug or correctness issue, say so. This is the part to say slowly: "The current implementation is correct.

      -

      Alex: Keep the teaching thread moving. The reason Approve explicitly matters is that 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!

      -

      Jamie: Let's pause on Say thank you. What should a learner take away from it?

      -

      Alex: Start with Say thank you: When someone takes time to review your work, acknowledge it - even if you disagree with some feedback. The next useful detail is this: "Thanks so much for the thorough review!

      +

      Jamie: Let's pause on How the Three Teams Connect. What should a learner take away from it?

      +

      Alex: The reason How the Three Teams Connect matters is that in practice, a single task often spans multiple teams. That gives the learner a simple foothold: no single agent covers the entire workflow.

      +

      Alex: The practical takeaway is this. You ask @daily-briefing (GitHub Workflow) for your morning report. It flags a PR that changes ARIA attributes. You ask @pr-review (GitHub Workflow) to generate a structured review of that PR. The review notes potential accessibility impact. You invoke @aria-specialist (Accessibility) to deep-check the ARIA changes. It identifies a missing aria-expanded state on a disclosure widget. You fix the issue using patterns from @desktop-a11y-specialist (Developer Tools) if it is a desktop application, or directly in the HTML if it is a web project.

      +

      Alex: Keep the teaching thread moving. Start with Learning Cards: Teams and Orchestration. There is something to understand, something to try, and something that proves the try worked.

      +

      Alex: The practical takeaway is this. Orchestrator agents like @accessibility-lead coordinate multi-agent workflows -- invoke one and it delegates to specialists, announcing which agent it is calling. Multi-agent output appears in sequence in Copilot Chat -- press Alt+F2 after each response to read it in Accessible View before the next agent responds. The three teams are GitHub Workflow (what happened), Accessibility (is it correct), and Developer Tools (fix it) -- choose your entry point based on your current task. Orchestrator responses can be long -- use Accessible View (Alt+F2) or widen the Chat panel to read comfortably at high zoom. The workflow diagrams in this section are described in text -- no visual-only content is required to understand the agent coordination pattern. Each team's agents are listed in the tables in Section 3 -- refer back there to find the right specialist agent.

      +

      Jamie: Let's pause on Orchestrator Agents. What should a learner take away from it?

      +

      Alex: Here is the plain-English version of Orchestrator Agents. Four agents are specifically designed to coordinate others. Put another way, you do not need to use orchestrators to get value from individual agents.

      -

      Alex: Keep the teaching thread moving. Here is the plain-English version of Don't take feedback personally. Code review is about the code, not your worth as a person or developer. Put another way, even the most senior contributors receive change requests. It is like learning a transit route. The names of the stops matter because they tell you whether you are still going the right direction.

      -

      Jamie: Let's pause on Explain your choices. What should a learner take away from it?

      -

      Alex: This is where Explain your choices becomes real: if you are keeping your implementation despite feedback, explain why. That matters in practice: "I considered aria-label here, but I went with a visually-hidden instead because it allows translators to localize the text more easily.

      -

      Alex: Keep the teaching thread moving. Keep the learner anchored in Surface blockers early. Don't wait until you have finished a 500-line PR to mention that you weren't sure about the approach.

      +

      Alex: Keep the teaching thread moving. This is where High-Impact Agents to Try First becomes real: rather than exploring all 55 agents at once, start with the ones that deliver immediate value based on Day 1 skills you already have.

      +

      Jamie: Let's pause on Slash Commands That Save the Most Time. What should a learner take away from it?

      +

      Alex: Keep the learner anchored in Slash Commands That Save the Most Time. These commands work without invoking a full agent - type them directly in Copilot Chat. This is the part to say slowly: The full list of 54+ commands is in Appendix L, and Episode 39 walks through all of them with examples.

      +

      Alex: The practical takeaway is this. /my-issues and /my-prs - Instant dashboard of your open work across all repos. /review-pr 14 - Full AI-generated review with inline suggestions, replacing manual line-by-line reading. /triage 22 - Label, priority, and assignment suggestions for any new issue. /daily-briefing - Morning snapshot of repository activity, PRs needing review, and stale issues.

      +

      Alex: Keep the teaching thread moving. The reason Running Agents Beyond VS Code matters is that accessibility Agents' agents run on your machine, in your editor, when you ask for them. That gives the learner a simple foothold: the same Markdown-authored pattern extends further. The interface gets friendlier when it stops being a wall of controls and starts being a set of named places.

      -

      Jamie: Let's pause on Inclusive Commenting for Accessibility Issues. What should a learner take away from it?

      -

      Alex: The reason Inclusive Commenting for Accessibility Issues matters is that when filing or discussing accessibility bugs, additional context helps.

      -

      Alex: The practical takeaway is this. 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.

      -

      Jamie: Let's pause on The "Good First Issue" Social Contract. What should a learner take away from it?

      -

      Alex: Start with The "Good First Issue" Social Contract: When a maintainer labels an issue good first issue, they are. The next useful detail is this: When you take a good first issue, your responsibilities. Think of it like entering a new building: first you find the lobby, then the room, then the door you actually need.

      -

      Alex: The practical takeaway is this. Investing time - good first issues require extra documentation and mentorship. Signaling welcome - they want to support a new contributor.

      -

      Alex: First, comment to claim it - "Hi, I'd like to work on this. Can I be assigned?". Then, wait for assignment - do not start until assigned; two people working in parallel wastes everyone's time. After that, 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?". Finally, 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?". Think of it as a rail line: each stop confirms you are still on the right route before the next one.

      -

      Jamie: Before we leave The "Good First Issue" Social Contract, what is the practical point?

      -

      Alex: First, don't disappear - if you claim an issue, see it through or explicitly hand it back. Treat it like a recipe: do not add the next ingredient until the previous one is actually in the bowl.

      -

      Jamie: Let's pause on When you receive harsh feedback. What should a learner take away from it?

      -

      Alex: Start with When you receive harsh feedback. There is something to understand, something to try, and something that proves the try worked.

      -

      Alex: First, take a breath before responding - there is no urgency; the thread will wait. Then, look for the valid concern underneath the harsh words. After that, respond to the concern, not the tone. Finally, if the behavior crosses into harassment, report it via the "." button on the comment → "Report". Treat it like a recipe: do not add the next ingredient until the previous one is actually in the bowl.

      +

      Jamie: Let's pause on Scope 1: Your Editor (Accessibility Agents). What should a learner take away from it?

      +

      Alex: Start with Scope 1: Your Editor (Accessibility Agents). There is something to understand, something to try, and something that proves the try worked.

      +

      Alex: The practical takeaway is this. File lives in.github/agents/[name].agent.md in your workspace. Triggered by: You, when you type @[agent-name] in Copilot Chat. Runs on: Your machine, using your Copilot subscription. Reaches: Every repository your GitHub account has access to. Scale: All 55 agents available when the workspace is open.

      +

      Alex: Keep the teaching thread moving. Here is the plain-English version of Scope 2: Your Repository (Travels with Forks). When you fork accessibility-agents, all 55 agents come with it. Put another way, you can edit them for your project's context.

      +

      Alex: The practical takeaway is this. File lives in.github/agents/[name].agent.md in the repo. Triggered by: Any contributor who has Copilot and opens the repo as a VS Code workspace. Runs on: Their machine, using their Copilot subscription. Reaches: Their GitHub account's repositories.

      +

      Jamie: Let's pause on Scope 3: The Cloud (GitHub Agentic Workflows). What should a learner take away from it?

      +

      Alex: This is where Scope 3: The Cloud (GitHub Agentic Workflows) becomes real: the workflow runs whether or not anyone is watching - when an issue is opened at 3am, the agentic response fires. That matters in practice: The link between Accessibility Agents and Agentic Workflows: Both use Markdown-authored instructions.

      +

      Alex: The practical takeaway is this. File lives in.github/workflows/[name].md (same folder as standard Actions YAML). Triggered by: Any GitHub event - issues: opened, pull request: created, schedule. Runs on: GitHub Actions infrastructure, serverlessly. Reaches: The repository where the workflow is defined.

      -

      Jamie: Let's pause on When you disagree with a decision. What should a learner take away from it?

      -

      Alex: Start with When you disagree with a decision. There is something to understand, something to try, and something that proves the try worked.

      -

      Alex: First, make your case once, clearly and with evidence. Then, accept that the maintainer has the final say in their project. After that, if you strongly disagree, you can fork the project and take it in a different direction - this is legitimate in open source. It is a checklist, but a meaningful one: every item creates evidence that the next step is safe.

      -

      Jamie: Let's pause on When someone is rude to you. What should a learner take away from it?

      -

      Alex: Start with When someone is rude to you. There is something to understand, something to try, and something that proves the try worked.

      -

      Alex: First, you do not have to engage. Then, 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.". After that, report via GitHub's reporting tools if the behavior is abusive. It is like walking a hallway with named doors: read the sign, enter the right room, then confirm where you landed.

      -

      Jamie: Let's pause on When you accidentally caused offense. What should a learner take away from it?

      -

      Alex: Start with When you accidentally caused offense. There is something to understand, something to try, and something that proves the try worked.

      -

      Alex: First, acknowledge it directly: "I can see how that came across as dismissive - that wasn't my intention.". Then, do not over-explain or defend excessively. After that, adjust going forward. The rhythm is simple: orient, act, verify, then continue.

      +

      Alex: Keep the teaching thread moving. Keep the learner anchored in Go Deeper. For full documentation on every agent, all 54+ slash commands, customization formats, and troubleshooting, see Appendix L: Accessibility Agents Reference. This is the part to say slowly: For the audio version, listen to Episode 39: Accessibility Agents - Complete Reference. A good GitHub workflow is like a well-run meeting: everyone knows the topic, the next action, and who has the floor.

      +

      Jamie: Let's pause on Example: Auto-triage accessibility issues. What should a learner take away from it?

      +

      Alex: The reason Example: Auto-triage accessibility issues matters is that file.github/workflows/auto-triage-a11y.md. That gives the learner a simple foothold: this runs automatically on every new issue.

      +

      Alex: Keep the teaching thread moving. Start with 8. GitHub Desktop, GitHub CLI, and Copilot CLI: These tools are not required for this workshop, but are worth knowing as options for different workflows.

      -

      Jamie: Let's pause on Writing Your First README. What should a learner take away from it?

      -

      Alex: Start with Writing Your First README: See also: Appendix W: GitHub Pages for publishing your README as a website. The next useful detail is this: A README is the front door of your project.

      -

      Alex: Keep the teaching thread moving. Here is the plain-English version of What belongs in a README. Every README should answer these questions, roughly in this order. Put another way, 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.

      -

      Jamie: Let's pause on Accessibility in READMEs. What should a learner take away from it?

      -

      Alex: This is where Accessibility in READMEs becomes real: your README is a web page -- GitHub renders it as HTML. That matters in practice: That means the same accessibility rules apply.

      -

      Alex: The practical takeaway is this. Alt text for images and badges. A badge that says is invisible to screen readers. Write 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 -- not Click here.

      +

      Jamie: Let's pause on GitHub Desktop. What should a learner take away from it?

      +

      Alex: Here is the plain-English version of GitHub Desktop. A graphical Git application with an accessible interface. Put another way, when to use: If command-line Git feels overwhelming, GitHub Desktop provides a GUI alternative.

      +

      Alex: The practical takeaway is this. Download: desktop.github.com. Useful for: Visual diff review, simpler branch management. Screen reader support: Partial - keyboard navigation works for core flows.

      +

      Alex: Keep the teaching thread moving. This is where GitHub CLI (gh) becomes real: a command-line interface for GitHub operations. The workshop is closer to rehearsal than lecture. You hear the move, try the move, and then check what changed.

      +

      Jamie: What is the safe way to learn from that example?

      +

      Alex: Start with Authenticate. There is something to understand, something to try, and something that proves the try worked.

      +

      Alex: Treat examples as spoken recipes, not decorations. You may hear something like gh auth login. Read the command, understand what it changes, then run it only when the repository state matches the lesson.

      -

      Alex: Keep the teaching thread moving. Keep the learner anchored in Good README vs. bad README. Bad: A single paragraph that says "This is my project. This is the part to say slowly: Run it with npm start." No headings, no license, no description of what the project does. A good GitHub workflow is like a well-run meeting: everyone knows the topic, the next action, and who has the floor.

      -

      Jamie: Let's pause on Learning Cards: Writing Your First README. What should a learner take away from it?

      -

      Alex: Start with Learning Cards: Writing Your First README. There is something to understand, something to try, and something that proves the try worked.

      -

      Alex: The practical takeaway is this. 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: rather than an empty that reads as "image" with no context. Use real Markdown link text (installation guide) instead of bare URLs, so your screen reader announces the destination rather than spelling out a long URL. 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.

      -

      Alex: Keep the teaching thread moving. Start with Community Health Files: Community health files tell contributors how your project operates before they write a single line of code. The next useful detail is this: 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.

      +

      Jamie: Let's pause on Common commands. What should a learner take away from it?

      +

      Alex: The reason Common commands matters is that screen reader advantage: gh output is plain text with no dynamic regions - more predictable than the browser for certain operations.

      +

      Alex: Treat examples as spoken recipes, not decorations. You may hear something like gh issue list List issues in current repo; gh issue view 42 Read issue 42; gh pr list List pull requests; gh pr view 14 Read PR 14; gh pr create Create a new PR interactively; gh pr merge 14 Merge PR 14; gh repo clone owner/repo Clone a repository; gh repo. Read the command, understand what it changes, then run it only when the repository state matches the lesson.

      +

      Jamie: Let's pause on GitHub Copilot CLI (gh copilot). What should a learner take away from it?

      +

      Alex: Start with GitHub Copilot CLI (gh copilot): An extension that adds Copilot to the terminal.

      +

      Jamie: Let's pause on Install. What should a learner take away from it?

      +

      Alex: Start with Install. There is something to understand, something to try, and something that proves the try worked.

      +

      Alex: Treat examples as spoken recipes, not decorations. You may hear something like gh extension install github/gh-copilot. Read the command, understand what it changes, then run it only when the repository state matches the lesson.

      -

      Jamie: Let's pause on CONTRIBUTING.md. What should a learner take away from it?

      -

      Alex: Here is the plain-English version of CONTRIBUTING.md. This file answers the question every newcomer asks: "How do I help?" A good CONTRIBUTING.md covers. Put another way, a sentence like "We are glad you are here" costs nothing and signals that newcomers are expected, not tolerated.

      -

      Alex: The practical takeaway is this. 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.

      -

      Alex: Keep the teaching thread moving. This is where CODE OF CONDUCT.md becomes real: a code of conduct sets the social contract for your project. That matters in practice: Without one, "acceptable behavior" is whatever each participant assumes it is -- and those assumptions vary widely. The workshop is closer to rehearsal than lecture. You hear the move, try the move, and then check what changed.

      -

      Alex: The practical takeaway is this. 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.

      -

      Jamie: Let's pause on SECURITY.md. What should a learner take away from it?

      -

      Alex: Keep the learner anchored in SECURITY.md. See also: Appendix F: Git Security and Appendix P: Security Features for security best practices. This is the part to say slowly: If someone discovers a vulnerability in your project, you do not want them to file a public issue.

      -

      Alex: The practical takeaway is this. 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.

      +

      Jamie: Let's pause on Commands. What should a learner take away from it?

      +

      Alex: This is where Commands becomes real: use case: When you know what you want to do but are unsure of the exact git command syntax.

      +

      Alex: Treat examples as spoken recipes, not decorations. You may hear something like Ask Copilot to explain a command; gh copilot explain "git rebase -i HEAD 3"; Ask Copilot to suggest a command; gh copilot suggest "undo my last commit but keep the changes"; Ask Copilot to write a shell script; gh copilot suggest "create a script that finds. Read the command, understand what it changes, then run it only when the repository state matches the lesson.

      +

      Jamie: Let's pause on Example session. What should a learner take away from it?

      +

      Alex: Start with Example session. There is something to understand, something to try, and something that proves the try worked.

      +

      Alex: Treat examples as spoken recipes, not decorations. You may hear something like $ gh copilot suggest "show me all commits from last week"; Suggestion: git log --since="1 week ago" --oneline; Run this command? (Y/n). Read the command, understand what it changes, then run it only when the repository state matches the lesson.

      +

      Jamie: Let's pause on Learning Cards: GitHub Desktop, GitHub CLI, and Copilot CLI. What should a learner take away from it?

      +

      Alex: Start with Learning Cards: GitHub Desktop, GitHub CLI, and Copilot CLI. There is something to understand, something to try, and something that proves the try worked.

      +

      Alex: The practical takeaway is this. GitHub Desktop is a native application -- on Windows it uses UI Automation, not a browser DOM; your screen reader's object navigation (NVDA: Insert+Numpad) rather than browse mode is the correct approach for navigating its interface. GitHub CLI (gh) is entirely terminal-based; all output is plain text that your screen reader reads line by line -- pipe verbose output through head -20 or Select-Object -First 20 to avoid overwhelming your speech buffer. Copilot CLI (gh copilot suggest and gh copilot explain) presents interactive prompts in the terminal; listen for the "Run this command? (Y/n)" confirmation before pressing Enter to avoid executing unreviewed commands. GitHub Desktop inherits your Windows display scaling -- if text appears small, increase system-level scaling (Settings Display Scale) rather than looking for an in-app zoom option. Terminal output from gh and gh copilot uses your terminal's font and color settings; configure your terminal profile (Windows Terminal settings or iTerm2 preferences) with a high-contrast color scheme and large font for comfortable reading. Copilot CLI suggestions appear as plain text in the terminal, not in a styled panel -- they are easy to miss among other output; look for the indented suggestion block immediately after your prompt.

      -

      Alex: Keep the teaching thread moving. The reason LICENSE matters is that 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. That gives the learner a simple foothold: adding a LICENSE file is a one-time step that makes your project genuinely open source.

      -

      Jamie: Let's pause on Finding these files on GitHub. What should a learner take away from it?

      -

      Alex: Start with Finding these files on GitHub: Navigate to any repository and click Insights then Community Standards. The next useful detail is this: GitHub shows a checklist of which community health files are present and links to add any that are missing.

      -

      Alex: Keep the teaching thread moving. Start with Learning Cards: Community Health Files. There is something to understand, something to try, and something that proves the try worked.

      -

      Alex: The practical takeaway is this. 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. 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.

      +

      Alex: Keep the teaching thread moving. Start with "Agent not found": Issue: Typing @agent-name shows "No agent found.". Think of it like entering a new building: first you find the lobby, then the room, then the door you actually need.

      +

      Jamie: Let's pause on Solutions. What should a learner take away from it?

      +

      Alex: Start with Solutions. There is something to understand, something to try, and something that proves the try worked.

      +

      Alex: First, verify.github/agents/[name].agent.md exists in your workspace. Then, reload VS Code window: Ctrl+Shift+P → "Reload Window". After that, check file naming: must end with.agent.md. Finally, verify YAML frontmatter is valid (no syntax errors). Treat it like a recipe: do not add the next ingredient until the previous one is actually in the bowl.

      +

      Alex: Keep the teaching thread moving. This is where Agent produces incorrect output becomes real: issue: Agent's response is wrong or misses context.

      -

      Jamie: Can you translate that into plain choices?

      -

      Alex: This is where When to Use Different Communication Channels becomes real: GitHub Discussions are separate from Issues. That matters in practice: Use Discussions for: "What do people think about X approach?" and Issues for: "The X button is broken.".

      -

      Alex: Use the comparison to make a decision, not to recite a table. The main contrasts are: PR comment means Feedback on a specific code change. PR review means Formal verdict (approve/request changes) with consolidated feedback. Discussion means Open-ended conversation, proposals, community Q&A.

      -

      Jamie: Let's pause on Try It: Rewrite One Comment. What should a learner take away from it?

      -

      Alex: Keep the learner anchored in Try It: Rewrite One Comment. Time: 2 minutes What you need: Just your brain. This is the part to say slowly: Read this code review comment and rewrite it to be constructive.

      -

      Alex: First, what you noticed. Then, why it matters. After that, what you suggest. Finally, why the suggestion helps. It is like walking a hallway with named doors: read the sign, enter the right room, then confirm where you landed.

      -

      Jamie: Before we leave Try It: Rewrite One Comment, what is the practical point?

      -

      Alex: First, encouragement. The rhythm is simple: orient, act, verify, then continue.

      -

      Jamie: Let's pause on Contributing to Open Source. What should a learner take away from it?

      -

      Alex: The reason Contributing to Open Source matters is that this section was previously Appendix T. That gives the learner a simple foothold: it is now part of the teaching narrative.

      -
      -

      Alex: Keep the teaching thread moving. Start with A Guide for First-Time Contributors: You do not need to be a professional developer to contribute to open source. The next useful detail is this: Documentation, accessibility improvements, and bug reports are among the most valuable contributions any project can receive. Think of it like entering a new building: first you find the lobby, then the room, then the door you actually need.

      -

      Jamie: Let's pause on 1. What Is Open Source? What should a learner take away from it?

      -

      Alex: Here is the plain-English version of 1. What Is Open Source? Open source software is software whose source code is publicly available. Put another way, anyone can read it, use it, and - in most cases - contribute to it.

      -

      Alex: The practical takeaway is this. 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.

      -

      Alex: Keep the teaching thread moving. This is where 2. Who Can Contribute? becomes real: contributors come from all backgrounds, skill levels, and countries. That matters in practice: 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.

      -
      -

      Jamie: Let's pause on 3. What Makes a Good First Contribution? What should a learner take away from it?

      -

      Alex: Start with 3. What Makes a Good First Contribution? There is something to understand, something to try, and something that proves the try worked.

      -

      Alex: The practical takeaway is this. 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.

      -

      Alex: Keep the teaching thread moving. The reason Signs a contribution is too large for a first attempt matters is that a well-executed small contribution is far more valuable than a large contribution that cannot be merged because it is out of scope. The interface gets friendlier when it stops being a wall of controls and starts being a set of named places.

      -

      Alex: The practical takeaway is this. 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.

      -

      Jamie: Let's pause on 4. Finding Something to Work On. What should a learner take away from it?

      -

      Alex: Start with 4. Finding Something to Work On: Most open source projects label issues that are suitable for new contributors. The next useful detail is this: How to search: On any GitHub repository, go to Issues → filter by label.

      -
      -

      Alex: Keep the teaching thread moving. Start with Learning Cards: Finding Something to Work On. There is something to understand, something to try, and something that proves the try worked.

      -

      Alex: The practical takeaway is this. 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. 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.

      -

      Jamie: What does someone need before they touch the keyboard?

      -

      Alex: This is where 5. Reading an Issue Before You Start becomes real: before commenting "I'll take this" on an issue, ask yourself. That matters in practice: 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.

      -

      Alex: The practical takeaway is this. 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.

      -

      Jamie: Let's pause on Tool Cards: Fork, Clone, and Contribute. What should a learner take away from it?

      -

      Alex: Start with Tool Cards: Fork, Clone, and Contribute. There is something to understand, something to try, and something that proves the try worked.

      -

      Alex: First, click Fork on the repository page, then Create fork. Then, edit files directly in your fork's web interface. After that, click Contribute Open pull request to submit back to the original. Finally, fork the repo on github.com first. It is like walking a hallway with named doors: read the sign, enter the right room, then confirm where you landed.

      -

      Jamie: Before we leave Tool Cards: Fork, Clone, and Contribute, what is the practical point?

      -

      Alex: First, navigate to your fork and press. to open in the web editor. Then, edit, commit, and create a PR from the Source Control panel. After that, fork on github.com, then clone your fork: Ctrl+Shift+P Git: Clone. Finally, create a branch, make edits, commit and push. The rhythm is simple: orient, act, verify, then continue.

      -

      Alex: Treat examples as spoken recipes, not decorations. You may hear something like 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. Read the command, understand what it changes, then run it only when the repository state matches the lesson.

      -
      -

      Jamie: Let's pause on The Basic Workflow. What should a learner take away from it?

      -

      Alex: Start with The Basic Workflow. There is something to understand, something to try, and something that proves the try worked.

      -

      Alex: First, fork the repository - creates your own copy on GitHub. Then, clone your fork to your computer (or open a Codespace - see Appendix N). After that, create a branch - name it something descriptive: fix/broken-link-setup-guide. Finally, make your change - edit the file, save, verify. The rhythm is simple: orient, act, verify, then continue.

      -

      Jamie: Before we leave The Basic Workflow, what is the practical point?

      -

      Alex: First, commit with a clear message - "Fix broken link in setup-guide.md line 34". Then, push to your fork. After that, open a pull request from your branch to the original repository's default branch. Finally, respond to review feedback - maintainers may ask for changes; this is normal and not a rejection. Think of it as a rail line: each stop confirms you are still on the right route before the next one.

      -

      Alex: Keep the teaching thread moving. Start with Writing a Good PR Description: Example: Fixed a broken link on line 34 of setup-guide.md. The next useful detail is this: The link pointed to /docs/old-setup which no longer exists.

      -

      Alex: The practical takeaway is this. What did you change? Why was the change needed? How did you verify it works?

      -

      Jamie: What do you want them to do when the plan breaks?

      -

      Alex: Here is the plain-English version of 7. Getting Help. It is always acceptable to ask a question on an issue or pull request. Put another way, 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.

      -

      Alex: The practical takeaway is this. 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.

      -
      -

      Alex: Keep the teaching thread moving. This is where 8. After Your Contribution Is Merged becomes real: this matters for your GitHub profile. That matters in practice: 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. The workshop is closer to rehearsal than lecture. You hear the move, try the move, and then check what changed.

      -

      Alex: The practical takeaway is this. 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.

      -

      Jamie: Let's pause on 9. Building a Contribution Habit. What should a learner take away from it?

      -

      Alex: Keep the learner anchored in 9. Building a Contribution Habit. The hardest part of open source contribution is starting. This is the part to say slowly: 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.

      -

      Alex: Keep the teaching thread moving. The reason Practical habits matters is that challenge Time: Complete Challenge 8: The Culture Layer in the Challenge Hub, then advance to Chapter 09: Labels, Milestones and Projects. That gives the learner a simple foothold: next: Chapter 09: Labels, Milestones, and Projects Back: Chapter 07: Merge Conflicts Related appendices: Appendix M: Accessibility Standards Appendix F: Git Security Appendix O: Branch Protection.

      -

      Alex: The practical takeaway is this. 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.

      +

      Jamie: Before we leave Solutions, what is the practical point?

      +

      Alex: First, provide more context in your prompt: Be specific about what you need. Then, use @ mentions: Reference specific files or selections (@filename.md, selection). After that, check the agent's prerequisites: Did you do the manual work first? Finally, review the agent's instructions: Open.github/agents/[name].agent.md and read what it's supposed to do. It is like walking a hallway with named doors: read the sign, enter the right room, then confirm where you landed.

      +

      Alex: Keep the teaching thread moving. The reason Slash command doesn't work matters is that issue: /command shows "Command not found.". The interface gets friendlier when it stops being a wall of controls and starts being a set of named places.

      +

      Jamie: What is the teaching move inside Solutions?

      +

      Alex: Start with Solutions: Next: Chapter 20: Build Your Agent Back: Chapter 18: Fork and Contribute Related appendices: Appendix L: Agents Reference Appendix K: Copilot Reference.

      +

      Alex: First, verify.github/prompts/[name].md exists. Then, reload window: Ctrl+Shift+P → "Reload Window". After that, check file naming: must be a.md file in.github/prompts/. Finally, try typing the full command name (autocomplete may be incomplete). Think of it as a rail line: each stop confirms you are still on the right route before the next one.

      Jamie: What is the final checkpoint?

      Alex: You should be able to point to the evidence, explain the action, and describe what you would do next if this were a real open source project. If you can teach the move back, you have learned it.

      @@ -18009,834 +17583,1466 @@

      Transcript

      -

      Challenge 13: AI as Your Copilot

      -

      Using Copilot as a reviewed writing partner while keeping human judgment in charge.

      +

      53. Challenge bonus-a: Improve an Agent

      +

      Extending or improving an existing agent with a clear accessibility purpose.

      +

      Practice focus: Bonus

      +

      Audio and transcript are being regenerated for this episode.

      -Read Transcript - Challenge 13: AI as Your Copilot +Read Transcript - Challenge bonus-a: Improve an Agent

      Transcript

      -

      Alex: This is Challenge Coach for AI as Your Copilot. I am Alex, and we are going to teach the move before asking you to prove it.

      +

      Alex: This is Challenge Coach for Improve an Agent. I am Alex, and we are going to teach the move before asking you to prove it.

      Jamie: And I am Jamie. I will translate the challenge into the practical questions learners actually have while doing it.

      -

      Alex: Using Copilot as a reviewed writing partner while keeping human judgment in charge. That is the task layer. The teaching layer is understanding why the move belongs in a contributor workflow.

      +

      Alex: Extending or improving an existing agent with a clear accessibility purpose. That is the task layer. The teaching layer is understanding why the move belongs in a contributor workflow.

      Jamie: So evidence is not just proof for the facilitator. It is part of how the learner understands the workflow.

      Alex: Right. A good challenge produces something inspectable: a comment, issue, branch, commit, pull request, review, or clear note about what happened.

      -

      Jamie: What makes this practice feel low-stakes but still real?

      -

      Alex: Start with Challenge 13: AI as Your Copilot: What you will do: Use GitHub Copilot to improve a documentation file, then critically evaluate whether the AI's suggestions are actually improvements.

      +

      Jamie: Okay, set the room for us. What are we walking into?

      +

      Alex: Start with Bonus A: Improve an Existing Agent: For students who: Finish early and want to contribute more to the accessibility-agents ecosystem. The next useful detail is this: What you will do: Choose an existing agent in the accessibility-agents repository, identify something that could be better, and open a PR with your improvement.

      +

      Alex: A solid pull request habit is to separate three questions: what changed, why it changed, and what still needs review. That keeps the conversation useful instead of noisy.

      Jamie: How would you walk the room through that step by step?

      Alex: Start with Instructions. There is something to understand, something to try, and something that proves the try worked.

      -

      Alex: The practical anchors are these. Improve the clarity of a paragraph. Fix any grammar or spelling issues. Suggest a better heading or structure.

      -

      Alex: First, open the sample file: docs/samples/copilot-improvement-before.md (or any documentation file in the repo). Then, use GitHub Copilot (Chat or inline suggestions) to. After that, critically evaluate the AI's output before accepting it. Treat it like a recipe: do not add the next ingredient until the previous one is actually in the bowl.

      +

      Alex: The practical anchors are these. Add a missing guardrail. Clarify a responsibility that is vague. Fix a typo or improve the description. Add a new responsibility that fits the agent's purpose.

      +

      Alex: First, browse the agents in the accessibility-agents repository. Then, pick one that interests you and read its.agent.md file carefully. After that, identify an improvement. Ideas. Finally, make the change on your fork (you already forked this in Challenge 16). Treat it like a recipe: do not add the next ingredient until the previous one is actually in the bowl.

      +

      Jamie: What does the learner do first, second, and then after that?

      +

      Alex: First, open a pull request explaining what you improved and why. It is a checklist, but a meaningful one: every item creates evidence that the next step is safe.

      Jamie: What is the one idea that makes the next few steps less mysterious?

      -

      Alex: This is where The trust-verify-reject framework becomes real: for every Copilot suggestion, ask yourself.

      +

      Alex: Start with Improvement criteria. There is something to understand, something to try, and something that proves the try worked.

      +

      Alex: That shows up in the workshop in a few specific ways. Specific -- change one thing well, not many things vaguely. Justified -- explain WHY the change makes the agent better. Respectful -- the original author made choices for reasons. Improve, do not rewrite.

      -

      Alex: Now bring the learner back to the room. Keep the learner anchored in What to watch for. My evaluation: I accepted/modified/rejected this because.

      -

      Alex: For a learner, the useful signals are these. Hallucinated links -- URLs that look real but go nowhere. Over-complicated language -- simpler is usually better. Lost context -- the AI may not understand the workshop's audience. Accessibility regressions -- images without alt text, complex tables where lists work better.

      +

      Alex: Now bring the learner back to the room. Keep the learner anchored in Example improvement. Target agent: aria-specialist.agent.md. This is the part to say slowly: What I changed: Added a new responsibility for checking aria-live regions in dynamic content.

      Jamie: What would you say to someone who is already bracing for this to be too much?

      -

      Alex: The reason Peer simulation check matters is that compare your Copilot result with the peer-simulation PR or with a real buddy if you have access. That gives the learner a simple foothold: did the AI suggestion actually improve the document?

      +

      Alex: The reason What matters matters is that the learning objective is contributing to an existing project by understanding its conventions and making a targeted improvement. That gives the learner a simple foothold: if you identified a real gap and proposed a specific, well-reasoned change, you completed this bonus.

      Alex: The useful habit is simple: orient first, act second, verify third. That pause before acting is part of the work.

      -

      Alex: That matters because of the next idea. Start with Example interaction transcript: Review the alt text in docs/welcome.md and suggest improvements for screen reader users. The next useful detail is this: The image on line 42 has alt="screenshot" which is not descriptive. Think of it like entering a new building: first you find the lobby, then the room, then the door you actually need.

      -
      -

      Jamie: What is the pre-flight check here?

      -

      Alex: Here is the plain-English version of Before and after. After (improved with Copilot's help).

      -

      Alex: This is where the talk moves from concept to action. This is where Critical evaluation notes becomes real: not everything Copilot suggests is correct. That matters in practice: What Copilot got right: The suggestion to be more descriptive than "screenshot" is correct.

      -

      Jamie: Where do you want a learner to place their attention here?

      -

      Alex: Start with Alternate approaches. There is something to understand, something to try, and something that proves the try worked.

      -

      Alex: These are the details that keep the idea from floating away. Ask Copilot to improve documentation clarity, then evaluate whether the suggestions make sense. Ask Copilot to check Markdown formatting, then verify its corrections. Ask Copilot to suggest commit messages, then refine them.

      -

      Alex: A solid pull request habit is to separate three questions: what changed, why it changed, and what still needs review. That keeps the conversation useful instead of noisy.

      +

      Alex: That matters because of the next idea. Start with 55 AI Agents Across 3 Teams and 5 Platforms: Day 2, Block 3 Material Before you read this guide: Accessibility Agents is a growing open source ecosystem: 55 AI-powered agents organized into three teams (Accessibility, GitHub Workflow, and Developer Tools), running on five platforms (GitHub Copilot,. The next useful detail is this: This chapter introduces the full landscape. Think of it like entering a new building: first you find the lobby, then the room, then the door you actually need.

      -

      Alex: Before the learner moves on. The reason What matters matters is that the learning objective is using AI as a collaborator while maintaining your own judgment. That gives the learner a simple foothold: if you used Copilot, evaluated its output critically, and made an improvement based on that evaluation, you completed this challenge. The interface gets friendlier when it stops being a wall of controls and starts being a set of named places.

      -

      Jamie: What should someone listen for when a lesson offers more than one tool path?

      -

      Alex: Start with AI-Powered Code Assistance in VS Code: Day 2, Block 2-3 Material This guide covers GitHub Copilot: inline code suggestions, Copilot Chat (conversational assistance), custom instructions vs custom agents, effective prompting for non-code contributions, and using Accessible View to read AI-generated. The next useful detail is this: Use the official guides as companion references.

      -

      Alex: Hold that next to this. Here is the plain-English version of Workshop Recommendation (Chapter 16 / Challenge 13). Free to use: GitHub Copilot Free tier is included with all GitHub accounts at no cost. Put another way, this workshop uses only the free tier.

      -

      Alex: That shows up in the workshop in a few specific ways. There are 3 guided challenges. Automation check: none (tool configuration is account-local and account-specific). The evidence is issue comment with checklist of completed actions. The pattern is install, prompt, apply, reflect.

      +

      Jamie: If I am listening before the workshop starts, what should settle in my mind first?

      +

      Alex: Start with Core Prerequisites (Required for All Agents). There is something to understand, something to try, and something that proves the try worked.

      +

      Alex: Here is what that changes in practice. [ ] Chapter 0: Pre-Workshop Setup - Git, VS Code, and GitHub account. [ ] Chapter 16: GitHub Copilot - GitHub Copilot Chat installed and working. [ ] GitHub Copilot access (Copilot Free tier is enough for this workshop). [ ].github/agents/ folder exists in your repository (or will create custom agents).

      +

      Alex: This is where the talk moves from concept to action. This is where Agent Prerequisites (The "Skill First" Principle) becomes real: every agent automates a skill you should already know by hand. That matters in practice: Before using any agent, verify you have done the corresponding manual work.

      +

      Jamie: Where does the workshop stop being a tour and start becoming contribution?

      +

      Alex: Keep the learner anchored in Workshop Recommendation (Chapter 19 / Challenge 15). Chapter 19 is the agent exploration and hands-on validation chapter - where students match agents to skills they already have and learn how to trust, evaluate, and improve AI-powered workflow automation. This is the part to say slowly: It supports Challenge 15: Meet the Agents.

      +

      Alex: These are the details that keep the idea from floating away. There are 3 guided + 1-2 optional contribution challenges. Automation check: none (agent output requires human judgment before use). The evidence is issue comment showing agent output and your evaluation of it. The pattern is explore, validate, read internals, optionally contribute.

      -

      Jamie: What does the learner do first, second, and then after that?

      -

      Alex: Start with Challenge 13 Set. There is something to understand, something to try, and something that proves the try worked.

      -

      Alex: First, sign in to GitHub Copilot - authenticate with GitHub (VS Code 1.116+ has Copilot built in; no extension install needed). Then, ask Copilot to explain a codebase - clone the sci-fi themes repo and use Copilot Chat to understand it. After that, ask Copilot to create something new - prompt Copilot to generate a custom theme and apply it. It is a checklist, but a meaningful one: every item creates evidence that the next step is safe.

      -

      Jamie: Turn that into a path someone can follow.

      -

      Alex: Keep the learner anchored in Challenge 13.1 Step-by-Step: Sign In to Copilot. Sign in to GitHub Copilot and verify it responds to prompts. This is the part to say slowly: VS Code desktop with your Learning Room repository open. A good GitHub workflow is like a well-run meeting: everyone knows the topic, the next action, and who has the floor.

      -

      Alex: First, (Older VS Code only) Open the Extensions sidebar: Ctrl+Shift+X (Mac: Cmd+Shift+X). Then, (Older VS Code only) Type GitHub Copilot in the search box and press Enter. After that, (Older VS Code only) Find GitHub Copilot (publisher: GitHub) in the results. Activate Install. Finally, (Older VS Code only) VS Code may also install GitHub Copilot Chat automatically. If not, search for it separately and install it. It is like walking a hallway with named doors: read the sign, enter the right room, then confirm where you landed.

      Jamie: What is the ordered workflow?

      -

      Alex: First, sign in when prompted: activate Sign in to GitHub and complete the OAuth flow in your browser. Then, verify Copilot is active: open Copilot Chat with Ctrl+Shift+I (Mac: Cmd+Shift+I). Type Hello, are you working? and press Enter. Copilot should respond. The rhythm is simple: orient, act, verify, then continue.

      +

      Alex: Start with Challenge 15 Set. There is something to understand, something to try, and something that proves the try worked.

      +

      Alex: First, agent Discovery Mapping - identify 3-5 agents that match skills you already have from Day 1. Then, agent Skill Validation - run one agent and evaluate its output against your manual experience. After that, agent Instructions Deep Dive - read one agent's source file and assess what it can and cannot do. Finally, improve an Existing Agent (optional hackathon) - find a gap in an agent's instructions and fix it via PR. The rhythm is simple: orient, act, verify, then continue.

      Jamie: Give me the sequence, because order matters here.

      -

      Alex: The reason Challenge 13.2 Step-by-Step: Explain a Codebase matters is that use Copilot Chat to understand an unfamiliar repository by asking targeted questions. That gives the learner a simple foothold: VS Code with the sci-fi themes repository cloned.

      -

      Alex: First, open the Command Palette: Ctrl+Shift+P (Mac: Cmd+Shift+P). Then, run Git: Clone and paste: https://github.com/community-access/vscode-sci-fi-themes.git. After that, open the cloned repository when VS Code prompts. Finally, open Copilot Chat: Ctrl+Shift+I (Mac: Cmd+Shift+I). The rhythm is simple: orient, act, verify, then continue.

      -

      Jamie: Let's pause on Challenge 13.2 Step-by-Step: Explain a Codebase. What should a learner take away from it?

      -

      Alex: First, ask Copilot: "What does the chat.agent.thinking.phrases setting do in VS Code?". Then, read the response. Use Alt+F2 (Accessible View) if needed to read the full text. After that, ask a follow-up: "How do I apply one of these themes to my settings.json?". Finally, follow Copilot's instructions to apply one theme to your settings.json file. Think of it as a rail line: each stop confirms you are still on the right route before the next one.

      +

      Alex: First, propose a New Agent (optional hackathon) - file an issue proposing an agent for an uncovered workflow. Think of it as a rail line: each stop confirms you are still on the right route before the next one.

      +

      Jamie: Turn that into a path someone can follow.

      +

      Alex: Start with Challenge 15.1 Step-by-Step: Agent Discovery Mapping: Map your Day 1 manual skills to specific agents in the ecosystem so you know which agents you are ready to use. The next useful detail is this: GitHub.com - the accessibility-agents repository and your assigned Challenge 15 issue.

      +

      Alex: A few details make that real. @daily-briefing (maps to repository and issue awareness from Chapters 2-4). @issue-tracker (maps to Chapter 4 issue workflow). @pr-review (maps to Chapter 6 and Chapter 14 review workflow). Example: You filed issues manually (Ch 4) - you can use @issue-tracker.

      +

      Alex: First, fork the accessibility-agents repository on GitHub.com. Then, open the repository and navigate to Section 3 of the README (or this chapter's Section 3 below) to see the full list of 55 agents organized by team. After that, read through the agent names and descriptions. For each one, ask yourself: "Have I done this task manually during the workshop?". Finally, identify 3-5 agents that match workflows you already practiced. Think of it as a rail line: each stop confirms you are still on the right route before the next one.

      +

      Jamie: Let's pause on Challenge 15.1 Step-by-Step: Agent Discovery Mapping. What should a learner take away from it?

      +

      Alex: First, open your assigned Challenge 15 issue. Then, post a discovery mapping comment using this format. Treat it like a recipe: do not add the next ingredient until the previous one is actually in the bowl.

      +

      Jamie: Let's pause on Challenge 15.2 Step-by-Step: Agent Skill Validation. What should a learner take away from it?

      +

      Alex: Here is the plain-English version of Challenge 15.2 Step-by-Step: Agent Skill Validation. Run one agent, read its output, and evaluate whether it matches your manual experience. Put another way, VS Code with the accessibility-agents repository cloned and Copilot Chat open.

      +

      Alex: For a learner, the useful signals are these. @daily-briefing morning briefing. @issue-tracker find open issues labeled good-first-issue in accessibility-agents. @pr-review show open PRs in accessibility-agents.

      +

      Alex: First, clone your fork of accessibility-agents to VS Code (or open it in github.dev). Then, open Copilot Chat: Ctrl+Shift+I (Mac: Cmd+Shift+I). After that, choose one agent from your discovery list. If unsure, start with @daily-briefing or @issue-tracker. Finally, run it with a simple prompt. Treat it like a recipe: do not add the next ingredient until the previous one is actually in the bowl.

      +

      Jamie: Before we leave Challenge 15.2 Step-by-Step: Agent Skill Validation, what is the practical point?

      +

      Alex: First, read the agent's output carefully. Take a moment to think about what you expected. Then, open your assigned Challenge 15 issue and post an evaluation comment. It is a checklist, but a meaningful one: every item creates evidence that the next step is safe.

      -

      Jamie: Let's pause on Challenge 13.3 Step-by-Step: Create Something New. What should a learner take away from it?

      -

      Alex: Start with Challenge 13.3 Step-by-Step: Create Something New: Use Copilot as a creative collaborator to generate a custom config and apply it. The next useful detail is this: VS Code with Copilot Chat open.

      -

      Alex: First, open Copilot Chat: Ctrl+Shift+I (Mac: Cmd+Shift+I). Then, type a creative prompt: "Create a custom GitHub Copilot thinking phrases theme for [your favorite universe - Dune, Marvel, Studio Ghibli, Star Trek, etc.]". After that, read Copilot's generated theme. It should include an array of themed phrases. Finally, copy the generated content: select all text in the Copilot response, then Ctrl+C (Mac: Cmd+C). Think of it as a rail line: each stop confirms you are still on the right route before the next one.

      -

      Jamie: Before we leave Challenge 13.3 Step-by-Step: Create Something New, what is the practical point?

      -

      Alex: First, open your settings.json: Command Palette, then Preferences: Open User Settings (JSON). Then, paste the theme configuration into your settings. After that, save with Ctrl+S and reload VS Code: Command Palette, then Developer: Reload Window. Finally, test your new theme by asking Copilot a question and watching the thinking phrases. Treat it like a recipe: do not add the next ingredient until the previous one is actually in the bowl.

      -

      Jamie: How do these exercises create confidence instead of pressure?

      -

      Alex: Here is the plain-English version of Completing Challenge 13: Submit Your Evidence. Open your assigned Challenge 13 issue and post a completion comment. Put another way, close your Challenge 13 issue when done.

      -

      Alex: Keep the thread going. Start with Expected Outcomes. There is something to understand, something to try, and something that proves the try worked.

      -

      Alex: The room should hear these as checkpoints. Student can install and authenticate GitHub Copilot Chat. Student can ask Copilot effective questions about code and settings. Student can use Copilot's output to customize their development environment. Student understands Copilot as a tool to explain and create, not just autocomplete.

      +

      Jamie: Let's pause on Challenge 15.3 Step-by-Step: Agent Instructions Deep Dive. What should a learner take away from it?

      +

      Alex: This is where Challenge 15.3 Step-by-Step: Agent Instructions Deep Dive becomes real: read one agent's source file to understand what instructions it follows, what tools it can use, and what mistakes it could make. That matters in practice: VS Code or GitHub.com - reading files in the accessibility-agents repository.

      +

      Alex: The parts worth keeping in working memory are these. What is this agent trying to do? (its purpose). What tools does it have access to? (tool permissions). What constraints or guardrails are in the instructions?

      +

      Alex: First, in the accessibility-agents repository, navigate to the.github/ folder (or wherever agent definition files are stored). Then, open one.agent.md or.prompt.md file for an agent you used or are curious about. After that, read the file and identify. Finally, think critically: could this agent make a mistake? What kind? It is a checklist, but a meaningful one: every item creates evidence that the next step is safe.

      +

      Jamie: Before we leave Challenge 15.3 Step-by-Step: Agent Instructions Deep Dive, what is the practical point?

      +

      Alex: First, open your assigned Challenge 15 issue and post your analysis. It is like walking a hallway with named doors: read the sign, enter the right room, then confirm where you landed.

      +

      Alex: That connects to another useful point. Keep the learner anchored in Optional Extensions 15.4-15.5 (Hackathon). Extension 15.4: Improve an Existing Agent (45 min). This is the part to say slowly: Extension 15.5: Propose a New Agent (60 min). A good GitHub workflow is like a well-run meeting: everyone knows the topic, the next action, and who has the floor.

      +

      Alex: On the ground, that means a few things. Find an agent whose instructions have a gap (use Section 6 suggestions or file an issue). Fork the repo, edit the agent's.agent.md file. Get a facilitator review. Open a PR with your improvement.

      +

      Jamie: What should the learner prove to themselves after each small task?

      +

      Alex: The reason Completing Challenge 15: Submit Your Evidence matters is that your evidence is the Challenge 15 issue comments for 15.1, 15.2, and 15.3. That gives the learner a simple foothold: for optional extensions, your PR or proposal issue is the evidence.

      +

      Alex: Here is the practical turn. Start with Expected Outcomes. There is something to understand, something to try, and something that proves the try worked.

      +

      Alex: The room should hear these as checkpoints. Student can map personal Day 1 skills to specific agents in the ecosystem. Student understands the Skill First, Agent Second principle and can articulate why agent output requires human judgment. Student can read agent instructions and evaluate what an agent can and cannot do. Student has used at least one agent and verified it against manual skills. (Optional) Student has contributed to the accessibility-agents ecosystem with a fix, improvement, or proposal.

      Jamie: Let's pause on If You Get Stuck. What should a learner take away from it?

      -

      Alex: Keep the learner anchored in If You Get Stuck. Continue learning: The GitHub Skills courses Getting Started with GitHub Copilot and Customize Your GitHub Copilot Experience cover Copilot setup, prompting, and personalization. This is the part to say slowly: See Appendix Z for the full catalog.

      -

      Alex: First, extension installation fails? Reload VS Code: Ctrl+Shift+P, then Developer: Reload Window. Then, oAuth sign-in fails? Verify your GitHub account is active in the browser first, close VS Code and retry. After that, chat panel does not open? Try Ctrl+Shift+I (Mac: Cmd+Shift+I). If still nothing, check that the Copilot Chat extension is installed (not just the base Copilot extension). Finally, Copilot seems unresponsive? Click the model selector at the bottom of Chat panel and confirm you are signed in. It is like walking a hallway with named doors: read the sign, enter the right room, then confirm where you landed.

      +

      Alex: Here is the plain-English version of If You Get Stuck. Continue learning: The GitHub Skills courses Build Applications with Copilot Agent Mode and Expand Your Team with Copilot explore agent-powered development workflows. Put another way, see Appendix Z for the full catalog.

      +

      Alex: First, cannot find an agent that matches your skills? Start with @daily-briefing or @issue-tracker - those build directly on Chapter 2-5 material. If you have not done those manual steps yet, go back to those chapters first. Then, agent output does not make sense? That is the right response. Paste the output in an issue comment along with your confusion. That is valuable feedback - the agent may need better instructions or guardrails. After that, cannot access the agents in Copilot Chat? Verify: Is Copilot Chat extension installed (not just base Copilot)? Are you signed in to GitHub in VS Code? Does.github/agents/ folder exist in your cloned repository? Finally, repository will not clone? Use the terminal: git clone https://github.com/[your-username]/accessibility-agents.git then open the folder in VS Code. Treat it like a recipe: do not add the next ingredient until the previous one is actually in the bowl.

      Jamie: Before we leave If You Get Stuck, what is the practical point?

      -

      Alex: First, cannot copy from Copilot response? Use Alt+F2 (Accessible View) to get the text in a copyable buffer. Then, ask facilitator to verify Copilot is activated and show you one example prompt. After that, finished but not sure you did it right? Compare your work against the Challenge 13 reference solution. The rhythm is simple: orient, act, verify, then continue.

      -

      Alex: Another way to ground it. The reason Learning Moment matters is that using Copilot as a brainstorming partner helps you write documentation that others can actually understand. That gives the learner a simple foothold: the prompting skill you practiced here - asking specific questions, iterating on responses, applying results - transfers to every AI tool you will use in your career.

      +

      Alex: First, ask facilitator to show them what agent you wanted to run, what output you got, and what you expected. Then, finished but not sure you did it right? Compare your work against the Challenge 15 reference solution. It is a checklist, but a meaningful one: every item creates evidence that the next step is safe.

      +

      Alex: Keep the thread going. This is where Learning Moment becomes real: the 55 agents exist because someone did the manual work first, then automated the repetitive parts. That matters in practice: As you explore agents, you are not just learning tools - you are learning what automation looks like when it is built on real expertise and real constraints. The workshop is closer to rehearsal than lecture. You hear the move, try the move, and then check what changed.

      +

      Jamie: Let's pause on Learning Pattern Used in This Chapter. What should a learner take away from it?

      Alex: Start with Learning Pattern Used in This Chapter. There is something to understand, something to try, and something that proves the try worked.

      -

      Alex: First, install the tool and verify it works before starting the task. Then, use the tool to explore and understand (ask questions, read responses). After that, use the tool to create something new (generate, customize, apply). Finally, reflect on when the tool helped and when your own judgment was better. Think of it as a rail line: each stop confirms you are still on the right route before the next one.

      +

      Alex: First, map your existing skills to available tools (discovery before action). Then, run one tool and evaluate its output critically (trust but verify). After that, read the source to understand capabilities and limits (internals matter). Finally, contribute improvements based on your evaluation (close the feedback loop). It is like walking a hallway with named doors: read the sign, enter the right room, then confirm where you landed.

      +

      Alex: Another way to ground it. The reason Capstone: Share Your Feedback (The Most Important Task!) matters is that you have now explored the full agent ecosystem, completed the workshop, and have valuable perspective on what worked, what confused you, and what we should improve for the next cohort. That gives the learner a simple foothold: your feedback directly shapes the future of this project.

      +

      Jamie: How should they picture the shape of the workshop?

      +

      Alex: Start with Submit Workshop Feedback: Use the Workshop Feedback form to share. The next useful detail is this: Answer as much or as little as you're comfortable sharing.

      +

      Alex: That becomes easier when you listen for these cues. Which agents stood out? (Most useful or surprising). Which agents confused you? (What would make them better). Was the chapter progression logical? (Did earlier chapters prepare you for later ones). Accessibility experience (If applicable - did any assistive technology work/fail?).

      -

      Alex: This is the part worth saying out loud. Here is the plain-English version of About Learning Cards in This Chapter. Throughout this chapter, look for expandable "learning cards" that show how to accomplish each task from different perspectives. Put another way, not every section has every card - only the cards that add meaningful guidance for that topic are included. It is like learning a transit route. The names of the stops matter because they tell you whether you are still going the right direction.

      +

      Alex: This is the part worth saying out loud. Here is the plain-English version of 1. The Principle: Skill First, Agent Second. Accessibility Agents is not a way to skip learning GitHub. Put another way, it is a way to amplify skills you have already built through deliberate practice. It is like learning a transit route. The names of the stops matter because they tell you whether you are still going the right direction.

      +

      Alex: The practical takeaway is this. Verify that the agent's output is correct. Catch when the agent misses context that only you have. Edit the agent's drafts into something worth posting under your name. Know when the agent is confidently wrong.

      Jamie: Give me the version that sounds like an instructor, not a manual.

      -

      Alex: This is where 1. What is GitHub Copilot becomes real: GitHub Copilot is an AI pair programmer that suggests code and text completions as you type. That matters in practice: For this workshop: Copilot helps with Markdown documentation, issue triage, PR descriptions, and commit messages - not just code.

      -

      Alex: The parts worth keeping in working memory are these. Complete lines of code or documentation. Generate entire functions or sections of text from comments. Answer questions about code in your workspace. Explain complex code in plain language.

      -

      Jamie: Let's pause on Installation Steps. What should a learner take away from it?

      -

      Alex: Keep the learner anchored in Installation Steps. One extension, all features: GitHub Copilot Chat is now the single all-in-one extension. This is the part to say slowly: It provides inline code suggestions, the Chat panel (Ctrl+Shift+I / Mac: Cmd+Shift+I), inline chat (Ctrl+I / Mac: Cmd+I), and all agent features.

      -

      Alex: First, open Extensions sidebar: Ctrl+Shift+X (Mac: Cmd+Shift+X). Then, search for "GitHub Copilot Chat". After that, find GitHub Copilot Chat (publisher: GitHub). Finally, press Enter to open the extension detail page. It is like walking a hallway with named doors: read the sign, enter the right room, then confirm where you landed.

      -

      Jamie: Before we leave Installation Steps, what is the practical point?

      -

      Alex: First, tab to "Install" button → press Enter. Then, wait for installation to complete. The rhythm is simple: orient, act, verify, then continue.

      +

      Alex: This is where Every agent has a manual prerequisite. If you have not done the corresponding skill by hand, the agent is not ready for you yet - and you are not ready for it becomes real: this applies across all three teams and all 55 agents. That matters in practice: Before running any agent, the facilitator asks the same question.

      +

      Alex: The practical takeaway is this. GitHub Workflow agents automate repository navigation, issue triage, PR review, and contribution analytics - skills you practiced on Day 1. Accessibility agents automate WCAG auditing, contrast checking, keyboard navigation review, and document scanning - knowledge from your accessibility training and the standards in Appendix C. Developer Tools agents automate accessible coding patterns for Python, wxPython, and desktop applications - skills from your development experience.

      +

      Alex: The next layer is this. Start with Learning Cards: Skill First, Agent Second. There is something to understand, something to try, and something that proves the try worked.

      +

      Alex: The practical takeaway is this. Before using any agent, verify you can do the task manually -- for @daily-briefing, confirm you can navigate Issues and PRs on GitHub.com with keyboard shortcuts (j/k to move, Enter to open). Agent output appears in Copilot Chat -- press Alt+F2 to open Accessible View and read the full response with arrow keys before acting on it. If an agent produces something you do not understand, stop and learn the manual skill first from the relevant chapter. Agent responses appear in the Copilot Chat panel -- drag the panel wider or use Alt+F2 (Accessible View) for a larger, cleaner reading pane. Each agent's instructions are in a.agent.md file you can open in VS Code and read at your preferred zoom level before invoking the agent. The agent ecosystem table in Section 3 uses standard Markdown tables that scale with your editor font size.

      -

      Jamie: Let's pause on Signing In. What should a learner take away from it?

      -

      Alex: Start with Signing In. There is something to understand, something to try, and something that proves the try worked.

      -

      Alex: First, VS Code prompts: "Sign in to use GitHub Copilot". Then, navigate to the notification or click the Copilot icon in the status bar. After that, select "Sign in to GitHub". Finally, your browser opens for GitHub authentication. The rhythm is simple: orient, act, verify, then continue.

      -

      Jamie: Before we leave Signing In, what is the practical point?

      -

      Alex: First, authorize the Copilot extension. Then, return to VS Code. Think of it as a rail line: each stop confirms you are still on the right route before the next one.

      -

      Alex: Here is the practical turn. Start with Verify activation. There is something to understand, something to try, and something that proves the try worked.

      -

      Alex: On the ground, that means a few things. Bottom-right status bar shows Copilot icon (looks like <). Icon should be active (not grayed out). If grayed out, click it to sign in.

      -

      Jamie: Let's pause on Command Palette. What should a learner take away from it?

      -

      Alex: Start with Command Palette. There is something to understand, something to try, and something that proves the try worked.

      -

      Alex: First, ctrl+Shift+P (Mac: Cmd+Shift+P). Then, type "Copilot: Check Status". After that, select it to see your subscription tier (Free, Pro, Enterprise). Treat it like a recipe: do not add the next ingredient until the previous one is actually in the bowl.

      +

      Jamie: There are a lot of tools in play. How do we keep that from feeling like a contest?

      +

      Alex: The reason Quick Install (One Command) matters is that accessibility Agents now ships with a one-liner installer that sets up all 55 agents for your platform.

      +

      Jamie: How do you keep commands from becoming magic words?

      +

      Alex: Start with macOS / Linux. There is something to understand, something to try, and something that proves the try worked.

      +

      Alex: Treat examples as spoken recipes, not decorations. You may hear something like curl -fsSL https://raw.githubusercontent.com/Community-Access/accessibility-agents/main/install.sh bash. Read the command, understand what it changes, then run it only when the repository state matches the lesson.

      +

      Jamie: Where do you want a learner to place their attention here?

      +

      Alex: Here is the plain-English version of Windows (PowerShell). The installer detects which AI tools you have installed (VS Code with Copilot, Claude Code, Gemini CLI, Claude Desktop, Codex CLI) and configures the appropriate agent files for each platform. Put another way, to uninstall, run the corresponding uninstall script from the repository.

      -

      Alex: The next layer is this. This is where Free tier includes becomes real: billing note: GitHub Copilot plan details are evolving. That matters in practice: Facilitators will provide current guidance at the workshop.

      -

      Alex: That becomes easier when you listen for these cues. Completions and multi-line suggestions. Copilot Chat. Limited monthly usage (usually sufficient for documentation work).

      -

      Jamie: Okay, set the room for us. What are we walking into?

      -

      Alex: Keep the learner anchored in 3. Inline Suggestions - Ghost Text Completions. Copilot suggests completions as you type, displayed as gray "ghost text" after your cursor. This is the part to say slowly: In screen reader mode, VS Code announces suggestions rather than showing them visually.

      -

      Jamie: Let's pause on While typing. What should a learner take away from it?

      -

      Alex: The reason While typing matters is that the suggestion appears as gray "ghost text" after your cursor - a preview of what Copilot thinks you want to type next. That gives the learner a simple foothold: it's there but not inserted; press Tab to accept it or Escape to dismiss. The interface gets friendlier when it stops being a wall of controls and starts being a set of named places.

      -

      Alex: A few details make that real. Increase ghost text contrast: Open Settings (Ctrl+,), search editorGhostText, then customize editor.ghostText.foreground in your color theme to a darker shade such as 555555. Use Accessible View instead: Press Alt+F2 when a suggestion appears. The suggestion text renders at your configured font size in a separate pane, making it far easier to read at 200%+ zoom. Word-by-word acceptance (Ctrl+Right Arrow) lets you watch each word appear at full contrast before deciding whether to continue. High Contrast themes do not automatically restyle ghost text. The color customization above is the most reliable fix.

      -

      Alex: First, Copilot analyzes your context (file content, cursor position, nearby files). Then, generates a suggestion. After that, presents the suggestion. The rhythm is simple: orient, act, verify, then continue.

      +

      Jamie: Let's pause on Workshop Setup (Fork and Clone). What should a learner take away from it?

      +

      Alex: This is where Workshop Setup (Fork and Clone) becomes real: for the workshop, you will also fork and clone the repository so you can make contributions. That matters in practice: If Copilot Chat works, the agents work.

      +

      Alex: First, fork accessibility-agents to your GitHub account (you did this on Day 1 or Day 2 morning). Then, clone your fork. After that, open in VS Code: navigate to the folder and run code. (or File, then Open Folder). Finally, open Copilot Chat: Ctrl+Shift+I. It is a checklist, but a meaningful one: every item creates evidence that the next step is safe.

      +

      Jamie: Before we leave Workshop Setup (Fork and Clone), what is the practical point?

      +

      Alex: First, test: type @daily-briefing morning briefing and press Enter. It is like walking a hallway with named doors: read the sign, enter the right room, then confirm where you landed.

      +

      Alex: Treat examples as spoken recipes, not decorations. You may hear something like git clone https://github.com/[your-username]/accessibility-agents.git. Read the command, understand what it changes, then run it only when the repository state matches the lesson.

      +

      Jamie: Let's pause on Prerequisites. What should a learner take away from it?

      +

      Alex: Start with Prerequisites. There is something to understand, something to try, and something that proves the try worked.

      +

      Alex: The practical takeaway is this. GitHub Copilot Chat extension installed (see GitHub Copilot: Installation). Signed in to GitHub via VS Code. A workspace open containing.github/agents/ folder with.agent.md files.

      +

      Jamie: Let's pause on How Agents Are Discovered. What should a learner take away from it?

      +

      Alex: The reason How Agents Are Discovered matters is that when you type @ in Copilot Chat, VS Code scans. That gives the learner a simple foothold: the Accessibility Agents ecosystem installs agents appropriate to each platform. The interface gets friendlier when it stops being a wall of controls and starts being a set of named places.

      +

      Alex: First,.github/agents/.agent.md in your current workspace. Then, any agents installed globally on your machine. After that, agents defined by extensions. The rhythm is simple: orient, act, verify, then continue.

      -

      Jamie: If I am listening before the workshop starts, what should settle in my mind first?

      -

      Alex: Start with Navigating the full Suggestions Panel (Ctrl+Enter): Pressing Ctrl+Enter opens a separate side-by-side tab showing up to 10 alternative suggestions. The next useful detail is this: Alt+F2 on a single suggestion is usually faster.

      -

      Alex: Here is what that changes in practice. Switch to your screen reader's browse/virtual mode when the panel opens (NVDA: Insert+Space to toggle off Application mode; JAWS: this may happen automatically). Use heading keys (H in NVDA/JAWS browse mode) to navigate between each suggestion -- each suggestion is announced as a heading. Each suggestion is followed by an Accept button -- navigate to it with Tab or B (button key) and press Enter to insert it at your cursor position. Press Escape or close the tab to dismiss without accepting.

      -

      Alex: That connects to another useful point. Start with Accepting word-by-word (Ctrl+Right Arrow / Mac: Cmd+Right Arrow) is particularly useful when. There is something to understand, something to try, and something that proves the try worked.

      -

      Alex: The practical takeaway is this. The suggestion starts correctly but you want to finish differently. You want to review the suggestion incrementally. You're learning and want to see how Copilot structures responses.

      -

      Jamie: Let's pause on Reading Suggestions with Screen Readers. What should a learner take away from it?

      -

      Alex: This is where Reading Suggestions with Screen Readers becomes real: visual users: If Copilot's ghost text is getting in the way, skip to "Disabling Inline Suggestions" below. That matters in practice: Screen reader users - tuning announcement verbosity.

      -

      Alex: A solid navigation habit is to prove where you are before activating controls. Headings, landmarks, and the address bar are not trivia; they are your map.

      +

      Jamie: Let's pause on Optional: Personalize Your Instance. What should a learner take away from it?

      +

      Alex: Start with Optional: Personalize Your Instance: Open preferences.md in VS Code and edit. The next useful detail is this: Commit preferences.md to your fork.

      +

      Alex: Before the learner moves on. Here is the plain-English version of How Agents Travel with Your Repo. When you fork accessibility-agents, the.github/agents/ folder comes with it.

      +

      Alex: The practical takeaway is this. Any collaborator who clones your fork gets all 55 agents automatically. You can customize agents for your specific project by editing the.agent.md files in your fork. Any project can have agents - create a.github/agents/ folder in any repository and add.agent.md files using the same pattern. The one-liner installer can also set up agents globally, so they are available in every workspace you open.

      +

      Jamie: Let's pause on Invoking Agents on GitHub.com. What should a learner take away from it?

      +

      Alex: This is where Invoking Agents on GitHub.com becomes real: accessibility Agents agents run in VS Code. That matters in practice: But the same.agent.md files can also be invoked directly on GitHub.com - no VS Code, no local clone required.

      -

      Jamie: Let's pause on NVDA. What should a learner take away from it?

      -

      Alex: Start with NVDA. There is something to understand, something to try, and something that proves the try worked.

      -

      Alex: First, NVDA Menu → Preferences → Settings → Presentation. Then, find "Report dynamic content changes". After that, reduce verbosity level or set specific delays. It is like walking a hallway with named doors: read the sign, enter the right room, then confirm where you landed.

      -

      Jamie: Let's pause on JAWS. What should a learner take away from it?

      -

      Alex: Start with JAWS. There is something to understand, something to try, and something that proves the try worked.

      -

      Alex: First, settings Center → HTML/PDF/Accessibility. Then, adjust "Auto Forms Mode" and "ARIA Live Region" settings. The rhythm is simple: orient, act, verify, then continue.

      -

      Jamie: Let's pause on VoiceOver. What should a learner take away from it?

      -

      Alex: Start with VoiceOver. There is something to understand, something to try, and something that proves the try worked.

      -

      Alex: First, VoiceOver Utility → Verbosity. Then, reduce "Announcements" level. Think of it as a rail line: each stop confirms you are still on the right route before the next one.

      +

      Jamie: Let's pause on Option 1: Copilot Chat with Task mode. What should a learner take away from it?

      +

      Alex: Keep the learner anchored in Option 1: Copilot Chat with Task mode. Screen reader users (NVDA / JAWS / VoiceOver). A good GitHub workflow is like a well-run meeting: everyone knows the topic, the next action, and who has the floor.

      +

      Alex: First, open Copilot Chat on GitHub.com (icon in the top-right navigation bar). Then, click Task in the mode picker. After that, optionally click the agent picker to select a custom agent. Finally, type your request and click Send. It is like walking a hallway with named doors: read the sign, enter the right room, then confirm where you landed.

      +

      Jamie: Before we leave Option 1: Copilot Chat with Task mode, what is the practical point?

      +

      Alex: First, Copilot analyzes the task and can create a branch and open a PR automatically. Then, open Copilot Chat on GitHub.com (navigate to icon in top-right navigation → Enter). After that, the mode picker (Task vs Chat) is a set of radio buttons - navigate with Arrow keys to select "Task". Finally, the agent picker is a listbox - Up/Down Arrow to navigate, Enter to select. The rhythm is simple: orient, act, verify, then continue.

      +

      Jamie: Let's pause on Option 2: Assign an issue to Copilot. What should a learner take away from it?

      +

      Alex: The reason Option 2: Assign an issue to Copilot matters is that screen reader users (NVDA / JAWS / VoiceOver). That gives the learner a simple foothold: this is the bridge to Section 6 (The Cloud Extension).

      +

      Alex: First, open any issue (or create a new one describing the task). Then, in the Assignees sidebar section, click the gear icon. After that, in the dropdown, click Copilot as the assignee. Finally, a dialog opens - optionally provide additional instructions and select a custom agent. The rhythm is simple: orient, act, verify, then continue.

      +

      Jamie: Before we leave Option 2: Assign an issue to Copilot, what is the practical point?

      +

      Alex: First, click Assign to confirm. Then, open any issue in the repository. After that, press B to navigate to the Assignees gear button → Enter to open the popup. Finally, navigate the popup with Arrow keys → find "Copilot" → Enter to select. Think of it as a rail line: each stop confirms you are still on the right route before the next one.

      +

      Alex: A solid issue habit is to read the title, the body, and the timeline before acting. You are listening for the requested action, the missing evidence, and the person who needs a response.

      +

      Alex: Hold that next to this. Start with Copilot on GitHub.com - Browser-Native Features: Beyond assigning Copilot to issues and using Task mode in Chat, GitHub.com now has several standalone Copilot features built directly into the web interface. The next useful detail is this: These work entirely in your browser - no VS Code, no local clone needed.

      -

      Jamie: Let's pause on Alternative: Use Accessible View. What should a learner take away from it?

      -

      Alex: Here is the plain-English version of Alternative: Use Accessible View. Press Alt+F2 (Mac: Option+F2) when a suggestion appears to read it in the Accessible View (full text, no streaming).

      -

      Alex: Keep the teaching thread moving. This is where Prompting Through Comments becomes real: Copilot reads inline comments as instructions. That matters in practice: Type this comment, press Enter, and Copilot drafts content based on your instruction. The workshop is closer to rehearsal than lecture. You hear the move, try the move, and then check what changed.

      -

      Jamie: Let's pause on Temporarily disable for current language. What should a learner take away from it?

      -

      Alex: Start with Temporarily disable for current language. There is something to understand, something to try, and something that proves the try worked.

      -

      Alex: The practical takeaway is this. Click the Copilot icon in the status bar (bottom-right < icon). Select "Disable Completions for [language]".

      -
      -

      Alex: Keep the teaching thread moving. The reason Permanently disable completions matters is that the Copilot status bar icon ( <) can be tiny at standard DPI. That gives the learner a simple foothold: use the Command Palette approach instead.

      -

      Alex: The practical takeaway is this. Open Settings: Ctrl+, (Mac: Cmd+,) → search "Copilot enable" → uncheck "Enable Inline Suggestions". Ctrl+Shift+P → type "Copilot: Toggle Completions" → press Enter. This toggles inline suggestions on/off without needing to find a small icon.

      -

      Jamie: How do we make tool choice feel like access, not pressure?

      -

      Alex: Start with Temporarily disable via Command Palette. There is something to understand, something to try, and something that proves the try worked.

      -

      Alex: The practical takeaway is this. 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).

      -

      Alex: Keep the teaching thread moving. Start with Permanently disable via Settings. There is something to understand, something to try, and something that proves the try worked.

      -

      Alex: The practical takeaway is this. Ctrl+, (Mac: Cmd+,) → search "inline suggestions" → toggle off "GitHub Copilot: Enable Inline Completions".

      -
      -

      Jamie: Let's pause on Learning Cards: Inline Suggestions. What should a learner take away from it?

      -

      Alex: Start with Learning Cards: Inline Suggestions. There is something to understand, something to try, and something that proves the try worked.

      -

      Alex: The practical takeaway is this. 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. 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.

      -

      Alex: Keep the teaching thread moving. Keep the learner anchored in 4. GitHub Copilot Chat - Conversational Assistance. See also: Appendix K: Copilot Reference has the complete slash command and chat variable reference. This is the part to say slowly: Copilot Chat is a full conversation interface where you ask questions, request explanations, and have content drafted.

      -

      Jamie: What should they understand before typing anything?

      -

      Alex: The reason Opening Copilot Chat matters is that primary panel: Ctrl+Shift+I (Mac: Cmd+Shift+I). That gives the learner a simple foothold: opens the Chat panel on the right side of VS Code.

      -

      Alex: The practical takeaway is this. 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.

      -

      Alex: Treat examples as spoken recipes, not decorations. You may hear something like gh extension install github/gh-copilot. gh copilot suggest "How do I squash the last 3 commits?". Read the command, understand what it changes, then run it only when the repository state matches the lesson.

      -
      -

      Alex: Keep the teaching thread moving. Start with Chat Modes: Copilot Chat has four modes, selected from a dropdown at the bottom of the Chat input area. The next useful detail is this: Each mode changes how Copilot interprets your request and what it can do. Think of it like entering a new building: first you find the lobby, then the room, then the door you actually need.

      -

      Jamie: Let's pause on Switching modes. What should a learner take away from it?

      -

      Alex: Here is the plain-English version of Switching modes. 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. Put another way, agent mode is powerful but works best once you're comfortable reviewing its output.

      -

      Alex: The practical takeaway is this. 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.

      -

      Alex: Keep the teaching thread moving. This is where Choosing a Model becomes real: Copilot gives you access to AI models from OpenAI, Anthropic (Claude), Google (Gemini), xAI (Grok), and others. That matters in practice: 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").

      +

      Jamie: Let's pause on Copilot PR Summary. What should a learner take away from it?

      +

      Alex: Here is the plain-English version of Copilot PR Summary. On any open pull request, GitHub adds a "Summarize" button in the PR description area. Put another way, selecting it generates a plain-language summary of what the PR changes, why, and what reviewers should focus on.

      +

      Alex: Keep the teaching thread moving. This is where Copilot PR Review becomes real: on open PRs you have write access to review, a "Review" button (or Copilot icon) appears in the Files changed tab. That matters in practice: Copilot generates inline review comments across the diff. The workshop is closer to rehearsal than lecture. You hear the move, try the move, and then check what changed.

      +

      Jamie: Let's pause on Copilot in Issues. What should a learner take away from it?

      +

      Alex: Keep the learner anchored in Copilot in Issues. On any issue page, Copilot adds sidebar buttons that appear once the page loads. This is the part to say slowly: Look in the right sidebar on any issue page for a Copilot section with "Explain" and "Suggest fix" buttons.

      +

      Alex: The practical takeaway is this. "Explain this issue" - generates a plain-language explanation of a complex technical issue. "Suggest fix" - proposes an approach to resolving the issue (opens a task/PR workflow).

      -

      Jamie: Let's pause on Quick guidance. What should a learner take away from it?

      -

      Alex: Keep the learner anchored in Quick guidance. Model availability changes frequently. This is the part to say slowly: Facilitators will provide current guidance at the workshop.

      -

      Alex: The practical takeaway is this. 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.

      -

      Jamie: Let's pause on Panel layout (top to bottom). What should a learner take away from it?

      -

      Alex: Start with Panel layout (top to bottom). There is something to understand, something to try, and something that proves the try worked.

      -

      Alex: The practical takeaway is this. Type your prompt here. Press Ctrl+Enter (Mac: Cmd+Enter) or Enter to send. Choose which AI model to use (GPT-4, Claude, etc.). Some models better for code, others for prose. Shows your previous prompts and Copilot's responses. Navigate with Up/Down Arrow.

      -

      Alex: First, chat input field (multi-line text area). Then, model selector dropdown. After that, conversation history. Finally, action buttons. The rhythm is simple: orient, act, verify, then continue.

      -

      Jamie: Let's pause on NVDA/JAWS. What should a learner take away from it?

      -

      Alex: Start with NVDA/JAWS. There is something to understand, something to try, and something that proves the try worked.

      -

      Alex: The practical takeaway is this. 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.

      +

      Alex: Keep the teaching thread moving. The reason GitHub Models - Free AI Playground matters is that github.com/marketplace/models is a free playground where you can test AI models (OpenAI GPT-4o, Meta Llama 3, Mistral, Phi-4 Mini, and others) directly in your browser. That gives the learner a simple foothold: why it matters for Accessibility Agents: When you build custom agents and prompts, you can test your system prompts and prompt templates in GitHub Models before adding them to your.prompt.md files - rapid iteration without burning API credits.

      +

      Alex: The practical takeaway is this. Send prompts to any listed model and compare responses side by side. Adjust parameters (temperature, max tokens) without any setup. Use the code sample generator to get API code for your chosen model. All free with a GitHub account (rate-limited for free tier).

      +

      Jamie: Let's pause on Copilot-Drafted Release Notes. What should a learner take away from it?

      +

      Alex: Start with Copilot-Drafted Release Notes: When creating a release (Releases tab → Draft a new release), GitHub provides a "Generate release notes" button. The next useful detail is this: It scans merged PRs since the last release and drafts categorized release notes automatically.

      +

      Alex: Keep the teaching thread moving. Start with Learning Cards: Setup and Configuration. There is something to understand, something to try, and something that proves the try worked.

      +

      Alex: The practical takeaway is this. Run the installer command in the VS Code terminal (Ctrl+) -- it announces progress as it copies agent files to.github/agents/`. After installation, press Ctrl+Shift+E to open the Explorer and navigate to.github/agents/ to verify agent files are present. Edit.github/agents/preferences.md to configure your username, repositories, and notification preferences -- it is a standard Markdown file. The installer creates files in.github/agents/ and.github/prompts/ -- verify in the Explorer sidebar that these folders appeared. Open preferences.md in the editor to set your configuration -- use Ctrl+= to zoom if the YAML frontmatter is hard to read. Agent files use.agent.md extension -- they appear alongside regular Markdown files in the Explorer but are distinguished by their extension.

      -

      Alex: Keep the teaching thread moving. Start with VoiceOver. There is something to understand, something to try, and something that proves the try worked.

      -

      Alex: The practical takeaway is this. 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.

      -

      Jamie: There are a lot of tools in play. How do we keep that from feeling like a contest?

      -

      Alex: This is where Using Slash Commands becomes real: type / in Copilot Chat to see available commands.

      -

      Jamie: Let's pause on Example. What should a learner take away from it?

      -

      Alex: Start with Example. There is something to understand, something to try, and something that proves the try worked.

      -

      Alex: First, select a block of complex Markdown. Then, open Chat: Ctrl+Shift+I (Mac: Cmd+Shift+I). After that, type /explain. Finally, Copilot explains the structure and purpose. It is like walking a hallway with named doors: read the sign, enter the right room, then confirm where you landed.

      +

      Jamie: Let's pause on 3. The Ecosystem: 55 Agents, 3 Teams, 5 Platforms. What should a learner take away from it?

      +

      Alex: This is where 3. The Ecosystem: 55 Agents, 3 Teams, 5 Platforms becomes real: accessibility Agents is an ecosystem of 55 specialized agents organized into three teams, each addressing a different dimension of accessible software development. That matters in practice: Browse all three teams below, then choose the agents that match your current skills and interests.

      +

      Alex: Keep the teaching thread moving. Keep the learner anchored in Team 1: Accessibility (26 agents). These agents audit, fix, and enforce accessibility across web, document, and mobile platforms.

      +

      Jamie: Let's pause on Team 2: GitHub Workflow (12 agents). What should a learner take away from it?

      +

      Alex: The reason Team 2: GitHub Workflow (12 agents) matters is that these agents automate GitHub operations - issue triage, PR review, contribution analytics, and repository management.

      -

      Jamie: Let's pause on Built-in Actions via Command Palette. What should a learner take away from it?

      -

      Alex: The reason Built-in Actions via Command Palette matters is that Copilot registers actions directly in the Command Palette. That gives the learner a simple foothold: this provides a discoverable way to use Copilot without remembering slash commands or keyboard shortcuts.

      -

      Alex: First, open Command Palette: F1 or Ctrl+Shift+P (Mac: Cmd+Shift+P). Then, type copilot. After that, browse the list of available actions. The rhythm is simple: orient, act, verify, then continue.

      -

      Alex: Keep the teaching thread moving. Start with Learning Cards: Copilot Chat. There is something to understand, something to try, and something that proves the try worked.

      -

      Alex: The practical takeaway is this. 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?"). 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.

      -

      Jamie: Let's pause on 5. Copilot Edits -- Making Multi-File Changes. What should a learner take away from it?

      -

      Alex: Here is the plain-English version of 5. Copilot Edits -- Making Multi-File Changes. As of VS Code 1.118 (April 2026), the separate Edit chat mode is being merged into Agent mode. Put another way, agent mode now supports the same working-set diff workflow that Edit mode provided.

      -

      Alex: The practical takeaway is this. 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.

      +

      Alex: Keep the teaching thread moving. Start with Team 3: Developer Tools (6 agents): These agents support accessible application development across desktop and cross-platform frameworks. Think of it like entering a new building: first you find the lobby, then the room, then the door you actually need.

      +

      Jamie: Let's pause on Beyond Agents: The Supporting Ecosystem. What should a learner take away from it?

      +

      Alex: Here is the plain-English version of Beyond Agents: The Supporting Ecosystem. The 55 agents are backed by additional resources in the repository.

      +

      Jamie: Let's pause on Hook-Based Enforcement (Claude Code). What should a learner take away from it?

      +

      Alex: This is where Hook-Based Enforcement (Claude Code) becomes real: on Claude Code, Accessibility Agents includes a hook system that enforces accessibility standards automatically. That matters in practice: This means accessibility enforcement happens whether or not the developer remembers to ask for it.

      +

      Alex: First, proactive detection hook - scans every file edit for accessibility regressions before they are committed. Then, edit gate hook - blocks commits that introduce WCAG violations until they are fixed. After that, session marker hook - tracks which accessibility checks have run during the current session. It is a checklist, but a meaningful one: every item creates evidence that the next step is safe.

      -

      Jamie: Let's pause on How to use Copilot Edits. What should a learner take away from it?

      -

      Alex: This is where How to use Copilot Edits becomes real: Copilot Edits shows you the full diff first. The workshop is closer to rehearsal than lecture. You hear the move, try the move, and then check what changed.

      -

      Alex: The practical takeaway is this. Click "Add Files." above the chat input,. Type in the chat input and select a file from the picker,. Right-click a file in the Explorer and choose "Add File to Copilot Edits".

      -

      Alex: First, open Copilot Chat: Ctrl+Shift+I (Mac: Cmd+Shift+I). Then, at the bottom of the Chat panel, click the mode dropdown and select Edit. After that, add files to your working set -- these are the files Copilot is allowed to edit. Finally, 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". It is a checklist, but a meaningful one: every item creates evidence that the next step is safe.

      -

      Jamie: Before we leave How to use Copilot Edits, what is the practical point?

      -

      Alex: First, press Enter -- Copilot shows a diff of proposed changes in each file. Then, review the changes: use Accept or Reject on individual files, or Accept All / Reject All. It is like walking a hallway with named doors: read the sign, enter the right room, then confirm where you landed.

      -

      Jamie: Let's pause on Navigating the diff with a screen reader. What should a learner take away from it?

      -

      Alex: Start with Navigating the diff with a screen reader. There is something to understand, something to try, and something that proves the try worked.

      -

      Alex: The practical takeaway is this. 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.

      -

      Alex: Keep the teaching thread moving. Start with Working set tips. There is something to understand, something to try, and something that proves the try worked.

      -

      Alex: The practical takeaway is this. 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.

      +

      Jamie: Let's pause on What Would You Build? What should a learner take away from it?

      +

      Alex: Keep the learner anchored in What Would You Build? This is the question that matters most. This is the part to say slowly: The 55 agents that exist today were built by contributors who saw a gap and filled it.

      +

      Alex: The practical takeaway is this. "Why is there no agent for [framework] accessibility patterns?". "I spend 30 minutes on [task] every week - could an agent do the repetitive part?". "This agent is good but it misses [specific edge case] - I could improve those instructions". "Mobile native accessibility testing has no agent coverage yet - I could start one".

      +

      Jamie: Let's pause on The contribution paths are. What should a learner take away from it?

      +

      Alex: The reason The contribution paths are matters is that see the Accessibility Agents CONTRIBUTING guide for detailed instructions on each path. The interface gets friendlier when it stops being a wall of controls and starts being a set of named places.

      +

      Alex: First, report an agent gap - file an issue describing what is missing and why it matters. Then, improve existing agent instructions - make an agent smarter about edge cases it misses. After that, add framework-specific patterns - teach agents about React, Vue, Angular, Svelte, or other framework accessibility patterns. Finally, fix installer issues - improve the one-liner scripts for different OS configurations. The rhythm is simple: orient, act, verify, then continue.

      +

      Jamie: Before we leave The contribution paths are, what is the practical point?

      +

      Alex: First, write documentation - help others understand how to use and contribute to agents. Think of it as a rail line: each stop confirms you are still on the right route before the next one.

      +

      Jamie: Let's pause on Roadmap: What Is Coming Next. What should a learner take away from it?

      +

      Alex: Start with Roadmap: What Is Coming Next: Your contribution could be the next item that ships. The next useful detail is this: Every agent started as one person's idea and one pull request.

      +

      Alex: The practical takeaway is this. Mobile native agents - agents specialized for iOS (VoiceOver) and Android (TalkBack) native app accessibility. Anthropic Connectors listing - making agents discoverable through the Anthropic marketplace. veraPDF integration - automated PDF/UA validation for the PDF accessibility agent. Document remediation agents - agents that fix accessibility issues in documents, not just find them.

      -

      Jamie: Let's pause on Learning Cards: Copilot Edits. What should a learner take away from it?

      -

      Alex: Start with Learning Cards: Copilot Edits. There is something to understand, something to try, and something that proves the try worked.

      -

      Alex: The practical takeaway is this. 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. 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.

      -

      Alex: Keep the teaching thread moving. Here is the plain-English version of 6. Agent Mode -- Let Copilot Drive. See also: Chapter 19: Accessibility Agents and Chapter 20: Build Your Agent for creating your own Copilot agent. Put another way, agent mode is the most autonomous way to use Copilot. It is like learning a transit route. The names of the stops matter because they tell you whether you are still going the right direction.

      -

      Alex: The practical takeaway is this. 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.

      -

      Jamie: Let's pause on How to use Agent mode. What should a learner take away from it?

      -

      Alex: Start with How to use Agent mode. There is something to understand, something to try, and something that proves the try worked.

      -

      Alex: First, open Copilot Chat: Ctrl+Shift+I (Mac: Cmd+Shift+I). Then, select Agent from the mode dropdown at the bottom of the Chat panel. After that, 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". Finally, Copilot begins working -- it shows each step it's taking and asks for approval before running terminal commands. It is a checklist, but a meaningful one: every item creates evidence that the next step is safe.

      -

      Jamie: Before we leave How to use Agent mode, what is the practical point?

      -

      Alex: First, watch the progress in the Chat panel; review any proposed changes in the editor. It is like walking a hallway with named doors: read the sign, enter the right room, then confirm where you landed.

      +

      Alex: Keep the teaching thread moving. Start with Learning Cards: The Agent Ecosystem. There is something to understand, something to try, and something that proves the try worked.

      +

      Alex: The practical takeaway is this. The three team tables use standard Markdown table format -- navigate with T (NVDA/JAWS) to jump between tables, then Arrow keys to read cells. Agent names start with @ -- type @ followed by the agent name in Copilot Chat to invoke it (e.g., @daily-briefing). Use Ctrl+Shift+O (symbol outline) in any agent file to navigate between its YAML frontmatter sections (Purpose, Responsibilities, Guardrails). The agent tables are dense -- use Ctrl+= to increase font size or open the file in Markdown Preview (Ctrl+Shift+V) for cleaner rendering. Each team has a distinct table: Team 1 (Accessibility, 26 agents), Team 2 (GitHub Workflow, 15 agents), Team 3 (Developer Tools, 14 agents). Agent files in.github/agents/ have descriptive filenames that match the @agent-name -- browse them in the Explorer to find specific agents.

      +

      Jamie: Let's pause on 4. Agents in Detail - Hands-On Reference. What should a learner take away from it?

      +

      Alex: This is where 4. Agents in Detail - Hands-On Reference becomes real: this section walks through several agents in depth so you can see how they work, what they produce, and how to evaluate their output. That matters in practice: These examples use GitHub Workflow agents because they build directly on Day 1 skills - but the same patterns apply to every agent in the ecosystem.

      +

      Alex: Keep the teaching thread moving. Keep the learner anchored in Two Types of Agents. Before diving in, it helps to know that custom agents fall into two categories - this distinction affects what tool permissions they need and what they can do. This is the part to say slowly: Informational agents search, analyze, and report. A good GitHub workflow is like a well-run meeting: everyone knows the topic, the next action, and who has the floor.

      -

      Alex: Keep the teaching thread moving. Keep the learner anchored in 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. This is the part to say slowly: When Copilot pauses for approval, focus moves to the approval dialog in the Chat panel.

      -

      Alex: The practical takeaway is this. Allow -- run this command once. Allow Always -- always allow this command type without asking again (use carefully). Cancel -- stop and don't run it.

      -

      Jamie: Let's pause on Learning Cards: Agent Mode. What should a learner take away from it?

      -

      Alex: Start with Learning Cards: Agent Mode. There is something to understand, something to try, and something that proves the try worked.

      -

      Alex: The practical takeaway is this. 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. 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.

      -

      Alex: Keep the teaching thread moving. Start with 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. The next useful detail is this: Unlike regular inline suggestions that complete what you're currently typing, NES looks ahead to related edits elsewhere in the file. Think of it like entering a new building: first you find the lobby, then the room, then the door you actually need.

      +

      Jamie: Let's pause on Agent 1: @daily-briefing - Morning Briefing. What should a learner take away from it?

      +

      Alex: The reason Agent 1: @daily-briefing - Morning Briefing matters is that file.github/agents/daily-briefing.agent.md. That gives the learner a simple foothold: before you run this agent: You should have manually navigated a repository's Issues tab, read your GitHub Notifications page, understood what a pull request waiting for review looks like, and know the difference between subscribed and participating.

      +

      Alex: Keep the teaching thread moving. Start with What it does: Sweeps every repository you have access to and builds a prioritized dashboard.

      +

      Alex: The practical takeaway is this. Issues opened in the last 24 hours. Pull requests waiting for your review. CI failures on your branches. Security and Dependabot alerts. Community reactions to your recent comments.

      +

      Jamie: What stays the same when the tool changes?

      +

      Alex: Here is the plain-English version of Example commands. The briefing output uses heading level 2 for each section. Put another way, use H key (NVDA/JAWS virtual mode) or VO+Command+H (VoiceOver) to jump between: Open Issues, Review Requests, CI Status, Security Alerts, Community Activity.

      -

      Jamie: Let's pause on Turning on Next Edit Suggestions. What should a learner take away from it?

      -

      Alex: Start with Turning on Next Edit Suggestions. There is something to understand, something to try, and something that proves the try worked.

      -

      Alex: First, open Settings: Ctrl+, (Mac: Cmd+,). Then, search for nextEditSuggestions. After that, enable "GitHub Copilot: Next Edit Suggestions". Treat it like a recipe: do not add the next ingredient until the previous one is actually in the bowl.

      -

      Alex: Keep the teaching thread moving. This is where How it works in practice becomes real: nES is announced as an inline suggestion at the predicted location. That matters in practice: With screen reader optimized mode on (Shift+Alt+F1), VS Code announces when a next edit suggestion is available.

      -

      Alex: The practical takeaway is this. 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.

      -

      Jamie: Let's pause on 8. Copilot on GitHub.com. What should a learner take away from it?

      -

      Alex: Keep the learner anchored in 8. Copilot on GitHub.com. You don't need VS Code to use Copilot. This is the part to say slowly: GitHub.com has Copilot built directly into the website -- useful for quick questions, reviewing code in the browser, drafting PR descriptions, and more.

      +

      Alex: Keep the teaching thread moving. This is where Agent 2: @issue-tracker - Issue Management becomes real: file.github/agents/issue-tracker.agent.md. That matters in practice: Before you run this agent: You should have filed at least one issue using the full manual process - writing a title, description, and reproduction steps; applying labels and a milestone; and reading at least five existing issues to understand what a. The workshop is closer to rehearsal than lecture. You hear the move, try the move, and then check what changed.

      +

      Jamie: Let's pause on What it does. What should a learner take away from it?

      +

      Alex: Keep the learner anchored in What it does. Finds, prioritizes, and helps you manage issues across all your repositories.

      +

      Alex: The practical takeaway is this. Cross-repository priority scoring with community sentiment. Batch-reply capability (draft replies to multiple issues at once). Saved search support. Release-awareness (flags issues that affect upcoming releases).

      +

      Alex: Keep the teaching thread moving. The reason Example commands matters is that the agent can draft a reply. That gives the learner a simple foothold: you review the tone against the Culture & Etiquette guide before posting.

      -

      Jamie: Let's pause on Opening Copilot Chat on GitHub.com. What should a learner take away from it?

      -

      Alex: The reason Opening Copilot Chat on GitHub.com matters is that Copilot on GitHub.com has context about your repositories, issues, PRs, and code -- you can reference them directly. The interface gets friendlier when it stops being a wall of controls and starts being a set of named places.

      -

      Alex: First, go to github.com -- you must be signed in. Then, look for the Copilot icon (a circle with dot pattern) in the top navigation bar. After that, click it (or press? then select Copilot from the command palette) to open the chat panel. Finally, type your question and press Enter. The rhythm is simple: orient, act, verify, then continue.

      -

      Jamie: Let's pause on Copilot for Pull Request Summaries. What should a learner take away from it?

      -

      Alex: Start with Copilot for Pull Request Summaries: When you open a pull request on GitHub.com, Copilot can generate a description for you automatically. The next useful detail is this: Copilot-generated PR descriptions are usually a solid first draft.

      -

      Alex: First, start creating a new pull request: go to your branch and select "Compare & pull request". Then, in the PR form, look for the Copilot icon next to the description field. After that, click it -- Copilot reads your commits and diff and writes a draft description. Finally, review and edit the draft -- it typically includes what changed and why. Think of it as a rail line: each stop confirms you are still on the right route before the next one.

      -

      Jamie: Before we leave Copilot for Pull Request Summaries, what is the practical point?

      -

      Alex: First, submit the PR. Treat it like a recipe: do not add the next ingredient until the previous one is actually in the bowl.

      -

      Alex: Keep the teaching thread moving. Here is the plain-English version of Copilot for Code Review on GitHub.com. Maintainers can use Copilot to review pull requests on GitHub.com. Put another way, as a contributor, you may see Copilot-authored review comments on your PR -- they look like regular review comments but are labelled "Copilot".

      -

      Alex: The practical takeaway is this. 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.

      +

      Jamie: What should they understand before typing anything?

      +

      Alex: Start with Output example. There is something to understand, something to try, and something that proves the try worked.

      +

      Alex: Treat examples as spoken recipes, not decorations. You may hear something like Open Issues Labeled "good-first-issue"; High Priority; - 45 [accessibility-agents] Add NVDA-specific navigation tips (3 comments, opened 5 days ago); - Priority Score: 8/10 (high community interest, clear scope, no assignee); - Recommended for: First-time. Read the command, understand what it changes, then run it only when the repository state matches the lesson.

      +

      Alex: Keep the teaching thread moving. Here is the plain-English version of Agent 3: @pr-review - Pull Request Review. File.github/agents/pr-review.agent.md. Put another way, before you run this agent: You should have manually reviewed at least one pull request diff in the GitHub browser interface - navigating the Files Changed tab with your screen reader, reading added and removed lines, leaving at least one inline comment, and. It is like learning a transit route. The names of the stops matter because they tell you whether you are still going the right direction.

      +

      Jamie: Before we leave What it does, what is the practical point?

      +

      Alex: This is where What it does becomes real: generates full review documents for pull requests.

      +

      Alex: The practical takeaway is this. Line-numbered diffs with change maps. Risk assessment (what could break, what is high-impact). Before-and-after snapshots. CI results and test coverage information. Suggested inline review comments with line number references.

      -

      Jamie: Let's pause on Learning Cards: Copilot on GitHub.com. What should a learner take away from it?

      -

      Alex: Start with Learning Cards: Copilot on GitHub.com. There is something to understand, something to try, and something that proves the try worked.

      -

      Alex: The practical takeaway is this. 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. 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.

      -

      Alex: Keep the teaching thread moving. Keep the learner anchored in 9. Effective Prompting for Documentation Work. Copilot works best with clear, specific prompts. This is the part to say slowly: The more context you provide, the better the response. A good GitHub workflow is like a well-run meeting: everyone knows the topic, the next action, and who has the floor.

      +

      Alex: Keep the teaching thread moving. Keep the learner anchored in Example commands. Critical rule: Read the agent's review. This is the part to say slowly: The agent produces a starting point - it does not know the project's history, the contributor's background, or the community's implicit standards the way you do.

      Jamie: What is the safe way to learn from that example?

      -

      Alex: Start with Good prompt. There is something to understand, something to try, and something that proves the try worked.

      -

      Alex: Treat examples as spoken recipes, not decorations. You may hear something like 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. Read the command, understand what it changes, then run it only when the repository state matches the lesson.

      -
      -

      Jamie: Let's pause on What makes it good. What should a learner take away from it?

      -

      Alex: Start with What makes it good. There is something to understand, something to try, and something that proves the try worked.

      -

      Alex: First, specific scope: "3-paragraph section". Then, clear topic: "navigate the VS Code Explorer sidebar". After that, target audience: "screen reader users" who "never used VS Code". Finally, required details: "keyboard shortcuts for NVDA and JAWS". Think of it as a rail line: each stop confirms you are still on the right route before the next one.

      -

      Jamie: Before we leave What makes it good, what is the practical point?

      -

      Alex: First, format guidance: "headings and bullet points". Treat it like a recipe: do not add the next ingredient until the previous one is actually in the bowl.

      -

      Jamie: How do you keep commands from becoming magic words?

      -

      Alex: Start with Pattern 2: Generate with Constraints. There is something to understand, something to try, and something that proves the try worked.

      -

      Alex: Treat examples as spoken recipes, not decorations. You may hear something like 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. Read the command, understand what it changes, then run it only when the repository state matches the lesson.

      -

      Alex: Keep the teaching thread moving. This is where Iterating on Responses becomes real: Copilot's first response is a draft. The workshop is closer to rehearsal than lecture. You hear the move, try the move, and then check what changed.

      +

      Alex: Treat examples as spoken recipes, not decorations. You may hear something like PR Review: 14 - Improve screen reader navigation guide; Summary; This PR adds 3 new sections to the screen reader navigation guide and updates 2 existing sections with NVDA-specific keyboard shortcuts.; Files Changed: 1; Lines Added: 127; Lines Removed: 18. Read the command, understand what it changes, then run it only when the repository state matches the lesson.

      +

      Alex: Keep the teaching thread moving. Start with Agent 4: @analytics - Team Analytics: File.github/agents/analytics.agent.md. The next useful detail is this: Before you run this agent: You should have explored the Insights tab of at least one repository - looked at the contribution graph, understood what commit frequency means, and thought about what "high-churn files" implies for a project's stability. Think of it like entering a new building: first you find the lobby, then the room, then the door you actually need.

      -

      Jamie: What should happen before anyone copies and runs it?

      -

      Alex: Keep the learner anchored in Follow-up prompts. Copilot remembers the conversation context - just say what to change.

      -

      Alex: Treat examples as spoken recipes, not decorations. You may hear something like 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. Read the command, understand what it changes, then run it only when the repository state matches the lesson.

      -

      Alex: Keep the teaching thread moving. Start with Learning Cards: Effective Prompting. There is something to understand, something to try, and something that proves the try worked.

      -

      Alex: The practical takeaway is this. 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. 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.

      -

      Jamie: Let's pause on 10. Custom Instructions vs Custom Agents. What should a learner take away from it?

      -

      Alex: Start with 10. Custom Instructions vs Custom Agents: Two distinct tools shape how Copilot behaves. The next useful detail is this: Understanding the difference is critical for working with Accessibility Agents (see Chapter 16: Accessibility Agents).

      +

      Jamie: What is the teaching move inside What it does?

      +

      Alex: Here is the plain-English version of What it does. Surfaces team contribution patterns, velocity metrics, and bottleneck detection.

      +

      Alex: The practical takeaway is this. Contribution velocity over time. Review turnaround time by reviewer. Code hotspot detection (files with the most churn). Workload distribution across contributors.

      +

      Alex: Keep the teaching thread moving. This is where Example commands becomes real: accessibility use case: After Day 2's contribution wave, run @analytics team velocity in accessibility-agents today to see the hackathon's collective output. That matters in practice: A moment of real-time team celebration.

      +

      Jamie: Let's pause on Agent 5: @insiders-a11y-tracker - Accessibility Change Monitoring. What should a learner take away from it?

      +

      Alex: Keep the learner anchored in Agent 5: @insiders-a11y-tracker - Accessibility Change Monitoring. File.github/agents/insiders-a11y-tracker.agent.md. This is the part to say slowly: Before you run this agent: You should have filed at least one accessibility bug report using the workshop's issue template, applied a WCAG label to an issue, and manually reviewed a Markdown file for heading hierarchy - knowing what H1 means, what H2 means,.

      -

      Alex: Keep the teaching thread moving. Here is the plain-English version of Custom Instructions. File.github/copilot-instructions.md. Put another way, purpose: Always-on background guidance for every Copilot interaction. It is like learning a transit route. The names of the stops matter because they tell you whether you are still going the right direction.

      -

      Jamie: Let's pause on What they do. What should a learner take away from it?

      -

      Alex: Start with What they do. There is something to understand, something to try, and something that proves the try worked.

      -

      Alex: The practical takeaway is this. Apply to all code suggestions automatically. Set project-wide standards. Influence tone and style. Provide context about your project's conventions.

      -

      Jamie: Let's pause on Example.github/copilot-instructions.md. What should a learner take away from it?

      -

      Alex: Keep the learner anchored in Example.github/copilot-instructions.md. When active: Every time Copilot generates a suggestion (inline or in Chat).

      -

      Alex: Treat examples as spoken recipes, not decorations. You may hear something like 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. Read the command, understand what it changes, then run it only when the repository state matches the lesson.

      +

      Alex: Keep the teaching thread moving. The reason What it does matters is that monitors accessibility-sensitive changes across configured repositories. The interface gets friendlier when it stops being a wall of controls and starts being a set of named places.

      +

      Alex: The practical takeaway is this. WCAG/ARIA cross-referenced change tracking. Flags changes to keyboard navigation, ARIA attributes, focus management, color usage. Monitors for heading hierarchy violations in Markdown. Tracks link text quality (flags bare URLs, non-descriptive labels).

      +

      Jamie: What should someone listen for when a lesson offers more than one tool path?

      +

      Alex: Start with Example commands: Day 2 workflow: Run this before submitting any PR. The next useful detail is this: If the agent flags an issue, fix it before requesting review - not after.

      +

      Alex: Keep the teaching thread moving. Here is the plain-English version of Agent 6: @template-builder - Interactive Issue Template Wizard. File.github/agents/template-builder.agent.md. Put another way, before you run this agent: You should have read Issue Templates thoroughly - understanding YAML field types, creating a template manually (Exercise B), and designing your own template (Exercise D).

      -

      Jamie: Let's pause on Custom Agents. What should a learner take away from it?

      -

      Alex: The reason Custom Agents matters is that files.github/agents/[name].agent.md. That gives the learner a simple foothold: purpose: On-demand, focused workflows that you deliberately invoke.

      -

      Alex: Keep the teaching thread moving. Start with What they do. There is something to understand, something to try, and something that proves the try worked.

      -

      Alex: The practical takeaway is this. Perform specific, repeatable tasks. Can access specific tools (GitHub API, file system, terminal). Generate structured output (reports, reviews, analysis). Execute multi-step workflows.

      -

      Jamie: Let's pause on Example agent names. What should a learner take away from it?

      -

      Alex: Here is the plain-English version of Example agent names. When active: Only when you type @agent-name in Copilot Chat. Put another way, see Chapter 16: Accessibility Agents for complete agent documentation.

      -

      Alex: The practical takeaway is this. @daily-briefing - Summarize repository activity. @issue-tracker - Find and prioritize issues. @pr-review - Generate PR review documentation. @analytics - Team contribution metrics.

      +

      Jamie: If someone only remembers one thing from What it does, what should it be?

      +

      Alex: This is where What it does becomes real: an interactive wizard that guides you through building GitHub issue templates step-by-step using VS Code's Ask Questions feature. That matters in practice: Instead of writing YAML syntax, answer simple questions and the agent generates production-ready templates.

      +

      Alex: Keep the teaching thread moving. Keep the learner anchored in Example commands. Manual YAML template creation takes 15-20 minutes and is error-prone. This is the part to say slowly: The Template Builder generates correct, tested templates in 2-3 minutes via guided questions. A good GitHub workflow is like a well-run meeting: everyone knows the topic, the next action, and who has the floor.

      +

      Jamie: What is the common workflow underneath the different interfaces?

      +

      Alex: The reason 5. Slash Commands and Prompts matters is that the repository includes 54+ slash commands defined as.prompt.md files in.github/prompts/. That gives the learner a simple foothold: type / in Copilot Chat to see the full command menu.

      -

      Jamie: What is the judgment call here?

      -

      Alex: Start with Comparison Table. There is something to understand, something to try, and something that proves the try worked.

      -

      Alex: Use the comparison to make a decision, not to recite a table. The main contrasts are: Custom Instructions means Custom Agent. When active means Background - every interaction means On-demand - you type @agent-name. Defined in means.github/copilot-instructions.md means.github/agents/[name].agent.md.

      -

      Jamie: Let's pause on Using Both Together. What should a learner take away from it?

      -

      Alex: Keep the learner anchored in Using Both Together. Custom instructions ensure Copilot follows your accessibility standards on every suggestion. This is the part to say slowly: Custom agents handle specific workflows like auditing, issue tracking, or automated remediation.

      -

      Jamie: Let's pause on Example workflow. What should a learner take away from it?

      -

      Alex: Start with Example workflow. There is something to understand, something to try, and something that proves the try worked.

      -

      Alex: First, your.github/copilot-instructions.md says: "Always check heading hierarchy in Markdown". Then, you invoke @insiders-a11y-tracker to scan recent changes. After that, the agent finds a heading skip (H1 → H3). Finally, you ask Copilot Chat to fix it: "Fix the heading hierarchy in this file". The rhythm is simple: orient, act, verify, then continue.

      -

      Jamie: Before we leave Example workflow, what is the practical point?

      -

      Alex: First, Copilot's fix follows your custom instructions (uses semantic HTML, adds ARIA where needed). Think of it as a rail line: each stop confirms you are still on the right route before the next one.

      +

      Alex: Keep the teaching thread moving. Start with Workshop Slash Command Quick Reference: The commands listed below are the ones most relevant to this workshop. The next useful detail is this: The full repository contains 54+ commands covering accessibility auditing, document scanning, framework-specific checks, and more.

      +

      Jamie: How do we make tool choice feel like access, not pressure?

      +

      Alex: Here is the plain-English version of Reading Slash Command Definitions. Each /command corresponds to a.prompt.md file in.github/prompts/. Put another way, open any of them in VS Code to read what instructions it gives Copilot.

      +

      Alex: Keep the teaching thread moving. This is where Example: /a11y-update becomes real: file.github/prompts/a11y-update.prompt.md. That matters in practice: This is how you learn to write your own. The workshop is closer to rehearsal than lecture. You hear the move, try the move, and then check what changed.

      -

      Jamie: Let's pause on Writing Accessibility-Focused Custom Instructions. What should a learner take away from it?

      -

      Alex: Start with Writing Accessibility-Focused Custom Instructions: Source: accessibility.github.com/documentation/guide/copilot-instructions/. The next useful detail is this: Custom instructions can be set at three levels.

      -

      Jamie: Let's pause on Do's - What Makes Instructions Effective. What should a learner take away from it?

      -

      Alex: Here is the plain-English version of Do's - What Makes Instructions Effective. Use normative language: MUST, MUST NOT, SHOULD, SHOULD NOT. Put another way, most language models respond well to normative language.

      -

      Alex: Treat examples as spoken recipes, not decorations. You may hear something like 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. Read the command, understand what it changes, then run it only when the repository state matches the lesson.

      -

      Jamie: Let's pause on Focus on team-specific standards, not generic principles. What should a learner take away from it?

      -

      Alex: This is where Focus on team-specific standards, not generic principles becomes real: tell it what your team does specifically.

      +

      Jamie: How should a learner choose a tool without feeling judged by the choice?

      +

      Alex: Start with Learning Cards: Slash Commands and Prompts. There is something to understand, something to try, and something that proves the try worked.

      +

      Alex: The practical takeaway is this. Type / in Copilot Chat to see all available slash commands -- your screen reader announces each command name as you arrow through the list. Slash commands are defined in.github/prompts/ as.prompt.md files -- open them in the Explorer to read what each command does before using it. Create your own command by copying an existing.prompt.md file, renaming it, and editing the instructions -- no code required. The / command menu appears as a dropdown list in Copilot Chat -- it scales with VS Code's font and zoom settings. Each command has a short description visible in the dropdown; use Ctrl+= to zoom if the text is too small. Open the.prompt.md file in the editor to read the full command definition at your preferred zoom level.

      +

      Alex: Keep the teaching thread moving. The reason 6. Contributing to the Ecosystem matters is that the 55 Accessibility Agents and 54+ slash commands are starting points. That gives the learner a simple foothold: the.agent.md format is open - you can create your own agents for any repeatable workflow, and contribute them back to the project.

      +

      Jamie: Let's pause on Two Types of Custom Agents. What should a learner take away from it?

      +

      Alex: Start with Two Types of Custom Agents: Informational agents - conversational; search, analyze, and present results. The next useful detail is this: Task-oriented agents - active; edit files, run commands, submit PRs.

      +

      Alex: The practical takeaway is this. Perform GitHub searches with predefined scopes and filters. Present results in specific structured formats. Query GitHub API tools to answer questions. Execute external tools (linters, test suites, axe-core).

      -

      Alex: Keep the teaching thread moving. Keep the learner anchored in Use lists and checklists to structure instructions. Lists provide clear guardrails - Copilot follows them step by step. A good GitHub workflow is like a well-run meeting: everyone knows the topic, the next action, and who has the floor.

      -

      Jamie: Let's pause on Reference and enforce your design system. What should a learner take away from it?

      -

      Alex: The reason Reference and enforce your design system matters is that document which components to use and which are deprecated. That gives the learner a simple foothold: design systems evolve - keep instructions current.

      -

      Alex: Keep the teaching thread moving. Start with Don'ts - Common Instruction Mistakes: Copilot is already trained on WCAG. The next useful detail is this: Pasting the full text wastes context space and dilutes your specific instructions.

      +

      Alex: Keep the teaching thread moving. Here is the plain-English version of Agent File Structure. See also: Appendix L: Agents Reference has the complete agent.md format specification and examples. Put another way, every.agent.md file has two parts: YAML frontmatter (metadata) and a system prompt (markdown body). It is like learning a transit route. The names of the stops matter because they tell you whether you are still going the right direction.

      +

      Jamie: Let's pause on Frontmatter fields. What should a learner take away from it?

      +

      Alex: This is where Frontmatter fields becomes real: restricting tool access is a security best practice - only grant what the agent actually needs.

      +

      Alex: Keep the teaching thread moving. Keep the learner anchored in Example: Informational Agent - @insiders-a11y-tracker. This agent monitors VS Code Insiders releases for accessibility improvements. This is the part to say slowly: It searches the microsoft/vscode repository using predefined GitHub query syntax, so you never have to remember the exact filter parameters.

      -

      Jamie: Let's pause on Additional Guidance. What should a learner take away from it?

      -

      Alex: Here is the plain-English version of Additional Guidance. Role-based prompting - You can give Copilot a persona to shape how it responds. Put another way, be specific about skills and responsibilities; avoid broad personas that may introduce unintended assumptions.

      -

      Alex: Keep the teaching thread moving. This is where Accessibility Resources for Custom Instructions becomes real: these resources can help you write better accessibility-focused custom instructions and evaluate Copilot's output. The workshop is closer to rehearsal than lecture. You hear the move, try the move, and then check what changed.

      -

      Alex: The practical takeaway is this. A11y LLM Evaluation Report - GitHub's own evaluation of how well LLMs handle accessibility tasks, with practical benchmarks: Accessibility LLM Evaluation. 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. Markdown Accessibility Review Guidelines - A practical guide for reviewing Markdown output for accessibility, useful as a reference when writing documentation-focused instructions: Markdown Accessibility.

      -

      Jamie: Let's pause on 11. Using Accessible View with Copilot Responses. What should a learner take away from it?

      -

      Alex: Keep the learner anchored in 11. Using Accessible View with Copilot Responses. Copilot Chat responses stream in token by token. This is the part to say slowly: This is visually nice but can fragment screen reader announcements.

      +

      Jamie: Let's pause on Use it. What should a learner take away from it?

      +

      Alex: The reason Use it matters is that prerequisite: GitHub MCP server installed (github.com/github/github-mcp-server).

      +

      Alex: First, select @insiders-a11y-tracker from the agent picker. Then, ask: what shipped this month? or any keyboard navigation improvements in January? After that, the agent searches with repo:microsoft/vscode is:closed milestone:"[Month] [Year]" label:accessibility label:insiders-released and returns formatted results. The rhythm is simple: orient, act, verify, then continue.

      +

      Alex: Keep the teaching thread moving. Start with Example: Task-Oriented Agent - The Markdown Accessibility Assistant: The GitHub Accessibility team published a complete walkthrough for building a Markdown Accessibility Assistant - a task-oriented agent that reviews Markdown files for accessibility issues and makes direct fixes. The next useful detail is this: This agent is the automated version of the accessibility review skills you built during Day 1. Think of it like entering a new building: first you find the lobby, then the room, then the door you actually need.

      +

      Alex: The practical takeaway is this. Runs markdownlint-cli2 to catch structural problems (heading skips, bare URLs, missing blank lines). Reviews link text for descriptiveness. Flags missing or inadequate alt text and waits for your approval before changing it (alt text requires human judgment). Fixes heading hierarchy, list structure, and bare URL formatting directly.

      +

      Jamie: Let's pause on Key Pattern: Tiered Decision-Making. What should a learner take away from it?

      +

      Alex: Here is the plain-English version of Key Pattern: Tiered Decision-Making. This tiered approach - automate what can be objectively evaluated, flag what needs human judgment - is the right model for any accessibility agent. Put another way, it maximizes the agent's value while keeping humans in control of decisions that require context.

      -

      Alex: Keep the teaching thread moving. Start with Without Accessible View. There is something to understand, something to try, and something that proves the try worked.

      -

      Alex: The practical takeaway is this. 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.

      -

      Jamie: Let's pause on With Accessible View (Alt+F2 / Mac: Option+F2). What should a learner take away from it?

      -

      Alex: Start with With Accessible View (Alt+F2 / Mac: Option+F2). There is something to understand, something to try, and something that proves the try worked.

      -

      Alex: The practical takeaway is this. 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.

      -

      Jamie: Let's pause on Every time you ask Copilot something. What should a learner take away from it?

      -

      Alex: Here is the plain-English version of Every time you ask Copilot something. VS Code December 2025 update: The Accessible View now updates dynamically as responses stream in. Put another way, 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. It is like learning a transit route. The names of the stops matter because they tell you whether you are still going the right direction.

      -

      Alex: First, type your prompt in Chat input. Then, press Ctrl+Enter (Mac: Cmd+Enter) to send. After that, press Alt+F2 (Mac: Option+F2) to open Accessible View - you can open it immediately after sending, before the response finishes. Finally, follow along as the response streams in the Accessible View in real-time. Treat it like a recipe: do not add the next ingredient until the previous one is actually in the bowl.

      -

      Jamie: Before we leave Every time you ask Copilot something, what is the practical point?

      -

      Alex: First, read or re-read any section with Arrow keys. Then, press Escape to close Accessible View and return to Chat. It is a checklist, but a meaningful one: every item creates evidence that the next step is safe.

      +

      Alex: Keep the teaching thread moving. Start with Required Prerequisites for the Markdown Accessibility Assistant. There is something to understand, something to try, and something that proves the try worked.

      +

      Alex: The practical takeaway is this. GitHub MCP server installed and configured (github.com/github/github-mcp-server). Node.js installed (for npx markdownlint-cli2).

      +

      Jamie: Let's pause on From VS Code. What should a learner take away from it?

      +

      Alex: Start with From VS Code. There is something to understand, something to try, and something that proves the try worked.

      +

      Alex: First, open Copilot Chat (Ctrl+Shift+I / Cmd+Shift+I on macOS). Then, in the Chat input toolbar, select the Set Agent button. After that, select your custom agent from the agent picker. Finally, type your request - the agent executes in your local workspace. It is like walking a hallway with named doors: read the sign, enter the right room, then confirm where you landed.

      +

      Jamie: Let's pause on From GitHub.com (Task mode). What should a learner take away from it?

      +

      Alex: Start with From GitHub.com (Task mode). There is something to understand, something to try, and something that proves the try worked.

      +

      Alex: First, open Copilot Chat on GitHub.com. Then, select Task from the mode picker. After that, optionally select a custom agent from the agent picker. Finally, submit your request - the agent can create a PR automatically. The rhythm is simple: orient, act, verify, then continue.

      -

      Jamie: Let's pause on Benefits. What should a learner take away from it?

      -

      Alex: Start with Benefits. There is something to understand, something to try, and something that proves the try worked.

      -

      Alex: The practical takeaway is this. Follow responses live without waiting. Navigate and re-read at your own pace. Code blocks and lists are properly structured. Headings are announced correctly.

      -

      Jamie: Let's pause on When a suggestion appears. What should a learner take away from it?

      -

      Alex: Keep the learner anchored in When a suggestion appears. 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 part to say slowly: This is the recommended workflow for screen reader users.

      -

      Alex: First, don't accept it immediately. Then, press Alt+F2 (Mac: Option+F2). After that, accessible View shows: "Suggestion: [full text of the suggestion]". Finally, read it completely. It is like walking a hallway with named doors: read the sign, enter the right room, then confirm where you landed.

      -

      Jamie: Before we leave When a suggestion appears, what is the practical point?

      -

      Alex: First, to insert the suggestion at your cursor: press Ctrl+/ (Mac: Cmd+/). Then, to close without inserting: press Escape, then Tab to accept or Escape to reject. The rhythm is simple: orient, act, verify, then continue.

      -

      Jamie: Let's pause on Code Blocks in Accessible View. What should a learner take away from it?

      -

      Alex: The reason Code Blocks in Accessible View matters is that when Copilot suggests code or Markdown.

      +

      Jamie: Let's pause on From an issue (Issue Assignment). What should a learner take away from it?

      +

      Alex: Start with From an issue (Issue Assignment). There is something to understand, something to try, and something that proves the try worked.

      +

      Alex: First, open any issue → Assignees → assign Copilot. Then, in the dialog, optionally select a custom agent. After that, select Assign - Copilot creates a branch, makes changes, and opens a PR. Think of it as a rail line: each stop confirms you are still on the right route before the next one.

      +

      Alex: Keep the teaching thread moving. Here is the plain-English version of Environment Setup for GitHub (Cloud Agents). When agents run on GitHub (not locally), they may need additional tools. Put another way, create a workflow file at.github/workflows/copilot-setup-steps.yml with a single job named copilot-setup-steps.

      +

      Jamie: Let's pause on To Create Your Own Agent. What should a learner take away from it?

      +

      Alex: Start with To Create Your Own Agent. There is something to understand, something to try, and something that proves the try worked.

      +

      Alex: First, create.github/agents/your-agent-name.agent.md. Then, write YAML frontmatter (name, description, tools). After that, write the system prompt - identity, capabilities, domain knowledge, behavioral rules, output format. Finally, save and reload VS Code (Ctrl+Shift+P → "Reload Window"). It is a checklist, but a meaningful one: every item creates evidence that the next step is safe.

      +

      Jamie: Before we leave To Create Your Own Agent, what is the practical point?

      +

      Alex: First, type @your-agent-name in Copilot Chat. It is like walking a hallway with named doors: read the sign, enter the right room, then confirm where you landed.

      -

      Alex: Keep the teaching thread moving. Start with In Accessible View: NVDA/JAWS: Use Arrow keys to read line by line. The next useful detail is this: Use Ctrl+Home to jump to the start. Think of it like entering a new building: first you find the lobby, then the room, then the door you actually need.

      -

      Alex: The practical takeaway is this. 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.

      -

      Jamie: Let's pause on Learning Cards: Using Accessible View with Copilot Responses. What should a learner take away from it?

      -

      Alex: Start with Learning Cards: Using Accessible View with Copilot Responses. There is something to understand, something to try, and something that proves the try worked.

      -

      Alex: The practical takeaway is this. 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. 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.

      -

      Alex: Keep the teaching thread moving. This is where GitHub.com Shortcuts (Not VS Code) becomes real: these shortcuts work on GitHub.com in your browser, not inside VS Code. That matters in practice: Students sometimes confuse them with Copilot shortcuts because they involve similar key combinations.

      +

      Alex: Keep the teaching thread moving. Keep the learner anchored in Exercise: Extend the Template Builder Agent. You've built templates manually (Chapters 15-16) and seen them in action. This is the part to say slowly: Now see how to harness AI to generate templates interactively, and learn to customize agents for your own projects. A good GitHub workflow is like a well-run meeting: everyone knows the topic, the next action, and who has the floor.

      +

      Alex: The practical takeaway is this. Complete Chapters 15-16 (especially Exercise D - designing your own template). VS Code is installed and GitHub Copilot is active. You have forked accessibility-agents to your GitHub account. You have cloned your fork locally: git clone https://github.com/[your-username]/accessibility-agents.git.

      +

      Jamie: Let's pause on Exercise 1: Generate a Template with the Agent. What should a learner take away from it?

      +

      Alex: The reason Exercise 1: Generate a Template with the Agent matters is that your Mission: Use the @template-builder agent to generate an accessibility bug report template interactively. That gives the learner a simple foothold: you'll experience the agent as an end-user and see what production-ready agent output looks like.

      +

      Alex: The practical takeaway is this. Left sidebar showing.github/, docs/, learning-room/, README.md, etc. The status bar at the bottom shows your current git branch (probably main). Alternative: Use menu: View → Copilot Chat. Copilot is now ready to receive instructions.

      +

      Alex: First, open VS Code. Then, file → Open Folder → select your locally cloned accessibility-agents folder. After that, the folder tree appears on the left showing the repository structure. Finally, verify you're in the right place: The folder name should be accessibility-agents at the top of the sidebar. The rhythm is simple: orient, act, verify, then continue.

      +

      Jamie: Before we leave Exercise 1: Generate a Template with the Agent, what is the practical point?

      +

      Alex: First, keyboard shortcut: Press Ctrl+Shift+I (Windows/Linux) or Cmd+Shift+I (macOS). Then, a chat panel opens on the right side of VS Code. After that, at the top, you see "Copilot Chat" and probably a text input at the bottom saying "Ask Copilot.". Finally, click in the chat input box (bottom of Copilot Chat panel). Think of it as a rail line: each stop confirms you are still on the right route before the next one.

      +

      Alex: Treat examples as spoken recipes, not decorations. You may hear something like Q: Template name?; A: Accessibility Bug Report; Q: What's it for?; A: Report screen reader and keyboard navigation issues; Q: First field name?; A: Screen Reader; Q: Field type?; A: dropdown; Q: Dropdown options? (comma-separated); A: NVDA, JAWS, VoiceOver,. Read the command, understand what it changes, then run it only when the repository state matches the lesson.

      +

      Jamie: Let's pause on Exercise 2: Extend the Agent for Your Project. What should a learner take away from it?

      +

      Alex: Start with Exercise 2: Extend the Agent for Your Project: Your Mission: Customize the Template Builder agent to recognize and guide a Security Vulnerability Report template. The next useful detail is this: This teaches you how to tailor agents for project-specific needs.

      +

      Alex: The practical takeaway is this. The file starts with YAML frontmatter (name, description, topics). Below that, sections like " How to Use", " Pre-Built Workflow". Search for the text "Pre-Built Workflow: Guided Accessibility Template".

      +

      Alex: First, in VS Code, navigate to.github/agents/. Then, file: template-builder.agent.md. After that, double-click to open it in the editor. Finally, you see the agent's instructions in Markdown format. Think of it as a rail line: each stop confirms you are still on the right route before the next one.

      +

      Jamie: Before we leave Exercise 2: Extend the Agent for Your Project, what is the practical point?

      +

      Alex: First, use Ctrl+F to open Find. Then, search for: Pre-Built Workflow. After that, press Enter to jump to the first match. Finally, you should land on the "Pre-Built Workflow: Guided Accessibility Template" section. Treat it like a recipe: do not add the next ingredient until the previous one is actually in the bowl.

      -

      Jamie: Let's pause on Video Tutorials (Screen Reader Demonstrations). What should a learner take away from it?

      -

      Alex: Keep the learner anchored in Video Tutorials (Screen Reader Demonstrations). GitHub's accessibility team has published screen reader walkthroughs for each major Copilot feature. This is the part to say slowly: These are sourced from the official GitHub Accessibility guide for Copilot in VS Code.

      -

      Alex: The practical takeaway is this. Inline suggestions with a screen reader - accepting, rejecting, and reviewing ghost text suggestions with NVDA. Inline chat with a screen reader - using Ctrl+I to edit code in place with screen reader feedback. Chat view with a screen reader - navigating the Chat panel, reading responses, and using Accessible View. Built-in actions with a screen reader - running Copilot commands from the Command Palette.

      -

      Alex: Keep the teaching thread moving. The reason 13. Critically Evaluating AI Output matters is that Copilot is fast, fluent, and frequently wrong. That gives the learner a simple foothold: 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. The interface gets friendlier when it stops being a wall of controls and starts being a set of named places.

      -

      Jamie: Let's pause on When to Trust Copilot. What should a learner take away from it?

      -

      Alex: Start with When to Trust Copilot: Copilot is at its best when it is generating code that thousands of developers have written before. The next useful detail is this: You can generally trust suggestions that fall into these categories.

      -

      Alex: The practical takeaway is this. 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.

      +

      Jamie: Let's pause on What you're adding. What should a learner take away from it?

      +

      Alex: Here is the plain-English version of What you're adding. If the agent doesn't recognize your new workflow.

      +

      Alex: The practical takeaway is this. A clear label for the new workflow. Instructions on how to invoke it. Pre-defined fields that make sense for security reports. Specific options for severity and vulnerability type. The agent recognizes your new workflow. Next time you invoke @template-builder with "create security template", it will follow your new guidance.

      +

      Alex: First, save the file: Ctrl+S. Then, you should see no error messages. After that, the agent file now includes your new Pre-Built Workflow. Finally, open Copilot Chat again: Ctrl+Shift+I. Treat it like a recipe: do not add the next ingredient until the previous one is actually in the bowl.

      +

      Jamie: Before we leave What you're adding, what is the practical point?

      +

      Alex: First, press Enter. Then, the agent should now ask vulnerability-specific questions. After that, commit your agent change. Finally, the extended agent is now in your fork. It is a checklist, but a meaningful one: every item creates evidence that the next step is safe.

      +

      Alex: Treat examples as spoken recipes, not decorations. You may hear something like git add.github/agents/template-builder.agent.md; git commit -m "feat: add security vulnerability template workflow to template-builder agent"; git push origin main. Read the command, understand what it changes, then run it only when the repository state matches the lesson.

      +

      Jamie: Let's pause on Exercise 3: Iterative Refinement with Agents. What should a learner take away from it?

      +

      Alex: This is where Exercise 3: Iterative Refinement with Agents becomes real: your Mission: Generate a template, then ask the agent to modify it incrementally. That matters in practice: This teaches you the iterative pattern that scales to all agent-assisted workflows. The workshop is closer to rehearsal than lecture. You hear the move, try the move, and then check what changed.

      +

      Alex: The practical takeaway is this. Running a complete template generation (same as Exercise 1). The agent modifies the YAML it generated. The new checkbox appears in the YAML with proper formatting and indentation. It doesn't regenerate from scratch - just adds your change.

      +

      Alex: First, in Copilot Chat, type: @template-builder create a feature request template. Then, answer the agent's questions to build a feature request form. After that, let the agent generate the YAML. Finally, copy it to a file.github/ISSUE TEMPLATE/feature-request.yml. It is a checklist, but a meaningful one: every item creates evidence that the next step is safe.

      +

      Jamie: Before we leave Exercise 3: Iterative Refinement with Agents, what is the practical point?

      +

      Alex: First, once the template is generated, while still in the same chat conversation, ask. Then, the agent regenerates the YAML with your new checkbox added in the right place (usually as required field pre-validation). After that, follow up. Finally, the agent modifies the textarea field's attributes to enable code highlighting. It is like walking a hallway with named doors: read the sign, enter the right room, then confirm where you landed.

      +

      Jamie: Let's pause on What Comes Next. What should a learner take away from it?

      +

      Alex: Keep the learner anchored in What Comes Next. Your next step: explore the broader ecosystem. This is the part to say slowly: That is Accessibility Agents' promise: not to replace your thinking, but to amplify your skills across all 55 agents - and to grow through the contributions of everyone who uses it.

      +

      Alex: The practical takeaway is this. Browse the full agent list - which agents solve problems you face regularly? Try an Accessibility team agent: @contrast-master check this page or @alt-text-headings review this file. Try a Developer Tools agent: @python-specialist review this module for accessibility or @desktop-a11y-specialist audit this dialog. Think about what is missing: what agent would you build if you could?

      +

      Alex: First, generated a template using an agent (Exercise 1). Then, customized an agent for your domain (Exercise 2). After that, refined iteratively with agent help (Exercise 3). It is like walking a hallway with named doors: read the sign, enter the right room, then confirm where you landed.

      -

      Alex: Keep the teaching thread moving. Here is the plain-English version of When to Verify. Some suggestions look correct at first glance but carry hidden risks. Put another way, always read these carefully before accepting.

      -

      Alex: The practical takeaway is this. 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.

      -

      Jamie: Let's pause on When to Reject. What should a learner take away from it?

      -

      Alex: This is where When to Reject becomes real: delete the suggestion and write the code yourself when you see any of these. That matters in practice: If you are not sure whether a suggestion falls into this category, verify it.

      -

      Alex: The practical takeaway is this. 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.

      -

      Alex: Keep the teaching thread moving. Keep the learner anchored in Common Failure Modes. The table below shows the kinds of mistakes Copilot makes most often. This is the part to say slowly: Recognizing these patterns helps you catch problems before they reach a reviewer. A good GitHub workflow is like a well-run meeting: everyone knows the topic, the next action, and who has the floor.

      +

      Alex: Keep the teaching thread moving. Start with Learning Cards: Contributing to the Ecosystem. There is something to understand, something to try, and something that proves the try worked.

      +

      Alex: The practical takeaway is this. Agent.agent.md files use YAML frontmatter at the top (between --- delimiters) followed by Markdown body; in VS Code, use Ctrl+G to jump to line 1 and arrow through the frontmatter fields (name, description, tools) before reading the body instructions. When writing your own.agent.md, use VS Code's Outline view (Ctrl+Shift+O) to verify that your Markdown headings (Purpose, Capabilities, Responsibilities) are correctly nested -- malformed headings will not appear in the outline. Before submitting a PR with a new agent file, run the file through a YAML linter (install the YAML extension, or use yamllint from the terminal) -- frontmatter syntax errors silently break agent registration. YAML frontmatter fields are densely packed with colons and quotes; increase your editor font size or use a monospaced font with wide character spacing so name:, description:, and tools: are clearly distinct. The.agent.md files in the agents/ directory follow a consistent structure -- use the file explorer's icon theme or file nesting feature to visually group agent files separately from regular documentation. When reviewing existing agents for contribution ideas, use VS Code's split editor to place the agent file and the README side by side so you can cross-reference the agent's instructions with its documented capabilities.

      +

      Jamie: Let's pause on 7. The Bigger Picture: Teams, Orchestration, and Beyond VS Code. What should a learner take away from it?

      +

      Alex: Start with 7. The Bigger Picture: Teams, Orchestration, and Beyond VS Code: The 55 agents are not 55 independent tools. The next useful detail is this: They are organized into three teams that work together, and several orchestrator agents exist specifically to coordinate multi-agent workflows.

      +

      Alex: Keep the teaching thread moving. Here is the plain-English version of How the Three Teams Connect. In practice, a single task often spans multiple teams. Put another way, no single agent covers the entire workflow. It is like learning a transit route. The names of the stops matter because they tell you whether you are still going the right direction.

      +

      Alex: The practical takeaway is this. You ask @daily-briefing (GitHub Workflow) for your morning report. It flags a PR that changes ARIA attributes. You ask @pr-review (GitHub Workflow) to generate a structured review of that PR. The review notes potential accessibility impact. You invoke @aria-specialist (Accessibility) to deep-check the ARIA changes. It identifies a missing aria-expanded state on a disclosure widget. You fix the issue using patterns from @desktop-a11y-specialist (Developer Tools) if it is a desktop application, or directly in the HTML if it is a web project.

      -

      Jamie: Let's pause on The Verification Checklist. What should a learner take away from it?

      -

      Alex: The reason The Verification Checklist matters is that before you accept any non-trivial Copilot suggestion, run through these steps. That gives the learner a simple foothold: keep the Problems panel open (Ctrl+Shift+M) while you work with Copilot.

      -

      Alex: First, does it compile or run? -- Accept the suggestion, save the file, and check for errors in the Problems panel (Ctrl+Shift+M). Then, does it do what I asked? -- Read the code and confirm it matches your intent, not just your prompt. After that, 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. Finally, does it match the project's conventions? -- Check naming, formatting, file organization, and error handling against the existing codebase. The rhythm is simple: orient, act, verify, then continue.

      -

      Jamie: Before we leave The Verification Checklist, what is the practical point?

      -

      Alex: First, did I check any URLs or references it generated? -- Open every link, verify every package name, confirm every API endpoint. Then, would this pass an accessibility review? -- Run it through the checks described below. Think of it as a rail line: each stop confirms you are still on the right route before the next one.

      -

      Alex: Keep the teaching thread moving. Start with Accessibility-Specific Concerns: Copilot generates HTML and UI code based on what it has seen -- and much of the web is inaccessible. The next useful detail is this: Watch for these problems in any suggestion that touches the user interface.

      -

      Alex: The practical takeaway is this. 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.

      -

      Jamie: Let's pause on The Right Mental Model. What should a learner take away from it?

      -

      Alex: Here is the plain-English version of The Right Mental Model. Think of Copilot as a fast typist who has read a lot of code. Put another way, it can reproduce patterns it has seen before, and it can combine those patterns in new ways.

      -

      Alex: The practical takeaway is this. 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.

      +

      Jamie: Let's pause on Learning Cards: Teams and Orchestration. What should a learner take away from it?

      +

      Alex: Start with Learning Cards: Teams and Orchestration. There is something to understand, something to try, and something that proves the try worked.

      +

      Alex: The practical takeaway is this. Orchestrator agents like @accessibility-lead coordinate multi-agent workflows -- invoke one and it delegates to specialists, announcing which agent it is calling. Multi-agent output appears in sequence in Copilot Chat -- press Alt+F2 after each response to read it in Accessible View before the next agent responds. The three teams are GitHub Workflow (what happened), Accessibility (is it correct), and Developer Tools (fix it) -- choose your entry point based on your current task. Orchestrator responses can be long -- use Accessible View (Alt+F2) or widen the Chat panel to read comfortably at high zoom. The workflow diagrams in this section are described in text -- no visual-only content is required to understand the agent coordination pattern. Each team's agents are listed in the tables in Section 3 -- refer back there to find the right specialist agent.

      +

      Alex: Keep the teaching thread moving. Keep the learner anchored in Orchestrator Agents. Four agents are specifically designed to coordinate others. This is the part to say slowly: You do not need to use orchestrators to get value from individual agents.

      +

      Jamie: Let's pause on High-Impact Agents to Try First. What should a learner take away from it?

      +

      Alex: The reason High-Impact Agents to Try First matters is that rather than exploring all 55 agents at once, start with the ones that deliver immediate value based on Day 1 skills you already have.

      +
      +

      Alex: Keep the teaching thread moving. Start with Slash Commands That Save the Most Time: These commands work without invoking a full agent - type them directly in Copilot Chat. The next useful detail is this: The full list of 54+ commands is in Appendix L, and Episode 39 walks through all of them with examples. Think of it like entering a new building: first you find the lobby, then the room, then the door you actually need.

      +

      Alex: The practical takeaway is this. /my-issues and /my-prs - Instant dashboard of your open work across all repos. /review-pr 14 - Full AI-generated review with inline suggestions, replacing manual line-by-line reading. /triage 22 - Label, priority, and assignment suggestions for any new issue. /daily-briefing - Morning snapshot of repository activity, PRs needing review, and stale issues.

      +

      Jamie: Let's pause on Running Agents Beyond VS Code. What should a learner take away from it?

      +

      Alex: Here is the plain-English version of Running Agents Beyond VS Code. Accessibility Agents' agents run on your machine, in your editor, when you ask for them. Put another way, the same Markdown-authored pattern extends further.

      +

      Alex: Keep the teaching thread moving. Start with Scope 1: Your Editor (Accessibility Agents). There is something to understand, something to try, and something that proves the try worked.

      +

      Alex: The practical takeaway is this. File lives in.github/agents/[name].agent.md in your workspace. Triggered by: You, when you type @[agent-name] in Copilot Chat. Runs on: Your machine, using your Copilot subscription. Reaches: Every repository your GitHub account has access to. Scale: All 55 agents available when the workspace is open.

      +
      +

      Jamie: Let's pause on Scope 2: Your Repository (Travels with Forks). What should a learner take away from it?

      +

      Alex: Keep the learner anchored in Scope 2: Your Repository (Travels with Forks). When you fork accessibility-agents, all 55 agents come with it. This is the part to say slowly: You can edit them for your project's context.

      +

      Alex: The practical takeaway is this. File lives in.github/agents/[name].agent.md in the repo. Triggered by: Any contributor who has Copilot and opens the repo as a VS Code workspace. Runs on: Their machine, using their Copilot subscription. Reaches: Their GitHub account's repositories.

      +

      Alex: Keep the teaching thread moving. The reason Scope 3: The Cloud (GitHub Agentic Workflows) matters is that the workflow runs whether or not anyone is watching - when an issue is opened at 3am, the agentic response fires. That gives the learner a simple foothold: the link between Accessibility Agents and Agentic Workflows: Both use Markdown-authored instructions. The interface gets friendlier when it stops being a wall of controls and starts being a set of named places.

      +

      Alex: The practical takeaway is this. File lives in.github/workflows/[name].md (same folder as standard Actions YAML). Triggered by: Any GitHub event - issues: opened, pull request: created, schedule. Runs on: GitHub Actions infrastructure, serverlessly. Reaches: The repository where the workflow is defined.

      +

      Jamie: Let's pause on Go Deeper. What should a learner take away from it?

      +

      Alex: Start with Go Deeper: For full documentation on every agent, all 54+ slash commands, customization formats, and troubleshooting, see Appendix L: Accessibility Agents Reference. The next useful detail is this: For the audio version, listen to Episode 39: Accessibility Agents - Complete Reference.

      +
      +

      Alex: Keep the teaching thread moving. Here is the plain-English version of Example: Auto-triage accessibility issues. File.github/workflows/auto-triage-a11y.md. Put another way, this runs automatically on every new issue.

      +

      Jamie: Let's pause on 8. GitHub Desktop, GitHub CLI, and Copilot CLI. What should a learner take away from it?

      +

      Alex: This is where 8. GitHub Desktop, GitHub CLI, and Copilot CLI becomes real: these tools are not required for this workshop, but are worth knowing as options for different workflows.

      +

      Alex: Keep the teaching thread moving. Keep the learner anchored in GitHub Desktop. A graphical Git application with an accessible interface. This is the part to say slowly: When to use: If command-line Git feels overwhelming, GitHub Desktop provides a GUI alternative. A good GitHub workflow is like a well-run meeting: everyone knows the topic, the next action, and who has the floor.

      +

      Alex: The practical takeaway is this. Download: desktop.github.com. Useful for: Visual diff review, simpler branch management. Screen reader support: Partial - keyboard navigation works for core flows.

      +
      +

      Jamie: Let's pause on GitHub CLI (gh). What should a learner take away from it?

      +

      Alex: The reason GitHub CLI (gh) matters is that a command-line interface for GitHub operations.

      +

      Jamie: What should happen before anyone copies and runs it?

      +

      Alex: Start with Authenticate. There is something to understand, something to try, and something that proves the try worked.

      +

      Alex: Treat examples as spoken recipes, not decorations. You may hear something like gh auth login. Read the command, understand what it changes, then run it only when the repository state matches the lesson.

      +

      Jamie: Let's pause on Common commands. What should a learner take away from it?

      +

      Alex: Here is the plain-English version of Common commands. Screen reader advantage: gh output is plain text with no dynamic regions - more predictable than the browser for certain operations.

      +

      Alex: Treat examples as spoken recipes, not decorations. You may hear something like gh issue list List issues in current repo; gh issue view 42 Read issue 42; gh pr list List pull requests; gh pr view 14 Read PR 14; gh pr create Create a new PR interactively; gh pr merge 14 Merge PR 14; gh repo clone owner/repo Clone a repository; gh repo. Read the command, understand what it changes, then run it only when the repository state matches the lesson.

      +
      +

      Alex: Keep the teaching thread moving. This is where GitHub Copilot CLI (gh copilot) becomes real: an extension that adds Copilot to the terminal. The workshop is closer to rehearsal than lecture. You hear the move, try the move, and then check what changed.

      +

      Jamie: Let's pause on Install. What should a learner take away from it?

      +

      Alex: Start with Install. There is something to understand, something to try, and something that proves the try worked.

      +

      Alex: Treat examples as spoken recipes, not decorations. You may hear something like gh extension install github/gh-copilot. Read the command, understand what it changes, then run it only when the repository state matches the lesson.

      +

      Jamie: Let's pause on Commands. What should a learner take away from it?

      +

      Alex: The reason Commands matters is that use case: When you know what you want to do but are unsure of the exact git command syntax.

      +

      Alex: Treat examples as spoken recipes, not decorations. You may hear something like Ask Copilot to explain a command; gh copilot explain "git rebase -i HEAD 3"; Ask Copilot to suggest a command; gh copilot suggest "undo my last commit but keep the changes"; Ask Copilot to write a shell script; gh copilot suggest "create a script that finds. Read the command, understand what it changes, then run it only when the repository state matches the lesson.

      +
      +

      Jamie: Let's pause on Example session. What should a learner take away from it?

      +

      Alex: Start with Example session. There is something to understand, something to try, and something that proves the try worked.

      +

      Alex: Treat examples as spoken recipes, not decorations. You may hear something like $ gh copilot suggest "show me all commits from last week"; Suggestion: git log --since="1 week ago" --oneline; Run this command? (Y/n). Read the command, understand what it changes, then run it only when the repository state matches the lesson.

      +

      Alex: Keep the teaching thread moving. Start with Learning Cards: GitHub Desktop, GitHub CLI, and Copilot CLI. There is something to understand, something to try, and something that proves the try worked.

      +

      Alex: The practical takeaway is this. GitHub Desktop is a native application -- on Windows it uses UI Automation, not a browser DOM; your screen reader's object navigation (NVDA: Insert+Numpad) rather than browse mode is the correct approach for navigating its interface. GitHub CLI (gh) is entirely terminal-based; all output is plain text that your screen reader reads line by line -- pipe verbose output through head -20 or Select-Object -First 20 to avoid overwhelming your speech buffer. Copilot CLI (gh copilot suggest and gh copilot explain) presents interactive prompts in the terminal; listen for the "Run this command? (Y/n)" confirmation before pressing Enter to avoid executing unreviewed commands. GitHub Desktop inherits your Windows display scaling -- if text appears small, increase system-level scaling (Settings Display Scale) rather than looking for an in-app zoom option. Terminal output from gh and gh copilot uses your terminal's font and color settings; configure your terminal profile (Windows Terminal settings or iTerm2 preferences) with a high-contrast color scheme and large font for comfortable reading. Copilot CLI suggestions appear as plain text in the terminal, not in a styled panel -- they are easy to miss among other output; look for the indented suggestion block immediately after your prompt.

      +

      Jamie: Let's pause on "Agent not found". What should a learner take away from it?

      +

      Alex: This is where "Agent not found" becomes real: issue: Typing @agent-name shows "No agent found.".

      -

      Alex: Keep the teaching thread moving. Start with Learning Cards: Critically Evaluating AI Output. There is something to understand, something to try, and something that proves the try worked.

      -

      Alex: The practical takeaway is this. 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. 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.

      -

      Jamie: Let's pause on Copilot Not Suggesting Anything. What should a learner take away from it?

      -

      Alex: Keep the learner anchored in Copilot Not Suggesting Anything. Issue: No suggestions appear as you type.

      Jamie: Let's pause on Solutions. What should a learner take away from it?

      Alex: Start with Solutions. There is something to understand, something to try, and something that proves the try worked.

      -

      Alex: First, check Copilot is active: status bar icon should not be grayed out. Then, click the Copilot icon → verify "Completions enabled". After that, check subscription status: Ctrl+Shift+P → "Copilot: Check Status". Finally, restart VS Code. The rhythm is simple: orient, act, verify, then continue.

      +

      Alex: First, verify.github/agents/[name].agent.md exists in your workspace. Then, reload VS Code window: Ctrl+Shift+P → "Reload Window". After that, check file naming: must end with.agent.md. Finally, verify YAML frontmatter is valid (no syntax errors). It is like walking a hallway with named doors: read the sign, enter the right room, then confirm where you landed.

      +

      Jamie: Let's pause on Agent produces incorrect output. What should a learner take away from it?

      +

      Alex: The reason Agent produces incorrect output matters is that issue: Agent's response is wrong or misses context.

      Jamie: Before we leave Solutions, what is the practical point?

      -

      Alex: First, sign out and sign back in: Ctrl+Shift+P → "Copilot: Sign Out". Think of it as a rail line: each stop confirms you are still on the right route before the next one.

      +

      Alex: First, provide more context in your prompt: Be specific about what you need. Then, use @ mentions: Reference specific files or selections (@filename.md, selection). After that, check the agent's prerequisites: Did you do the manual work first? Finally, review the agent's instructions: Open.github/agents/[name].agent.md and read what it's supposed to do. Think of it as a rail line: each stop confirms you are still on the right route before the next one.

      -

      Jamie: Let's pause on Suggestions Are Too Frequent/Distracting. What should a learner take away from it?

      -

      Alex: Start with Suggestions Are Too Frequent/Distracting: Issue: Constant interruptions from suggestions.

      +

      Jamie: Let's pause on Slash command doesn't work. What should a learner take away from it?

      +

      Alex: Here is the plain-English version of Slash command doesn't work. Issue: /command shows "Command not found.".

      Jamie: What is the teaching move inside Solutions?

      -

      Alex: First, use word-by-word acceptance: Ctrl+Right Arrow. Then, reduce screen reader verbosity (see Section 3). After that, use Accessible View (Alt+F2) to review suggestions without live announcements. Finally, disable inline suggestions temporarily: Copilot icon → "Disable Completions". Treat it like a recipe: do not add the next ingredient until the previous one is actually in the bowl.

      -

      Jamie: Let's pause on Chat Responses Not Announced. What should a learner take away from it?

      -

      Alex: This is where Chat Responses Not Announced becomes real: issue: Screen reader silent when Copilot responds.

      +

      Alex: This is where Solutions becomes real: next: Chapter 20: Build Your Agent Back: Chapter 18: Fork and Contribute Related appendices: Appendix L: Agents Reference Appendix K: Copilot Reference.

      +

      Alex: First, verify.github/prompts/[name].md exists. Then, reload window: Ctrl+Shift+P → "Reload Window". After that, check file naming: must be a.md file in.github/prompts/. Finally, try typing the full command name (autocomplete may be incomplete). It is a checklist, but a meaningful one: every item creates evidence that the next step is safe.

      +

      Jamie: Let's pause on 1. The Capstone Challenge. What should a learner take away from it?

      +

      Alex: Keep the learner anchored in 1. The Capstone Challenge. The capstone is Challenge 16 -- the final challenge of the workshop. This is the part to say slowly: Your pull request goes to a real repository.

      +

      Alex: First, choose a mission for a new accessibility agent (or improve an existing one). Then, write an agent file with valid YAML frontmatter. After that, define clear responsibilities and guardrails. Finally, test the agent locally with GitHub Copilot. It is like walking a hallway with named doors: read the sign, enter the right room, then confirm where you landed.

      +

      Jamie: Before we leave 1. The Capstone Challenge, what is the practical point?

      +

      Alex: First, open a pull request from your fork to the upstream repository. Then, respond to peer review feedback. The rhythm is simple: orient, act, verify, then continue.

      -

      Jamie: If someone only remembers one thing from Solutions, what should it be?

      -

      Alex: First, wait for response to complete, then press Alt+F2 for Accessible View. Then, check ARIA live region settings in your screen reader. After that, navigate manually to the response area with Tab or Arrow keys. Finally, use Quick Chat (Ctrl+Shift+Alt+I) instead of panel chat. It is like walking a hallway with named doors: read the sign, enter the right room, then confirm where you landed.

      -

      Jamie: Let's pause on "Copilot Subscription Required". What should a learner take away from it?

      -

      Alex: The reason "Copilot Subscription Required" matters is that issue: Extension installed but asks for subscription.

      -

      Jamie: Let's pause on Solutions. What should a learner take away from it?

      -

      Alex: First, sign in to GitHub: Copilot icon → "Sign in". Then, verify GitHub account has Copilot access (free tier or paid). After that, check github.com/settings/copilot for subscription status. Finally, free tier users: ensure you haven't exceeded monthly limits. Think of it as a rail line: each stop confirms you are still on the right route before the next one.

      +

      Alex: Keep the teaching thread moving. Start with What you need before starting. There is something to understand, something to try, and something that proves the try worked.

      +

      Alex: The practical takeaway is this. [ ] You have forked and cloned the accessibility-agents repository (Chapter 18). [ ] You have a feature branch created: agents/your-username-agent-name. [ ] You understand how to push to your fork and open a PR (Chapter 18). [ ] You have GitHub Copilot or Copilot Free active (Chapter 16). [ ] You have explored the existing agents in Chapter 19.

      +

      Jamie: Let's pause on Time estimate. What should a learner take away from it?

      +

      Alex: Start with Time estimate: Most students complete the capstone in 60 to 90 minutes. The next useful detail is this: The phases are designed so you can get a working agent in 30 minutes and spend the remaining time improving it.

      +

      Alex: Keep the teaching thread moving. Here is the plain-English version of 2. Phase 1: Choose Your Agent's Mission. See also: Chapter 19: Accessibility Agents introduces the agent ecosystem and shows existing agents for inspiration.

      -

      Jamie: Let's pause on Try It: Your First Copilot Conversation. What should a learner take away from it?

      -

      Alex: Here is the plain-English version of Try It: Your First Copilot Conversation. Time: 3 minutes What you need: VS Code with Copilot Chat extension installed. Put another way, you just had a conversation with an AI about your codebase.

      -

      Alex: First, open Copilot Chat - Press Ctrl+Shift+I (Mac: Cmd+Shift+I). Your screen reader announces the chat panel. Then, ask a question - Type: What does the CONTRIBUTING.md file in this repository say about how to submit a pull request? Press Enter. After that, 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. Finally, try a follow-up - Type: Summarize that in 3 bullet points and press Enter. Copilot remembers the context from your first question. Treat it like a recipe: do not add the next ingredient until the previous one is actually in the bowl.

      +

      Jamie: Let's pause on What makes a good agent mission. What should a learner take away from it?

      +

      Alex: This is where What makes a good agent mission becomes real: a good agent solves a specific, recurring problem.

      +

      Alex: The practical takeaway is this. What task do you repeat? Think about workflow steps from Day 1 and Day 2 that felt repetitive. What would a specialist know? An agent works best when it has deep knowledge of a focused area. What gap exists? Look at the existing agents in Chapter 19. Is there a workflow that no agent covers?

      +

      Alex: Keep the teaching thread moving. Keep the learner anchored in Write your mission statement. Before writing any code, write a one-sentence mission statement. This is the part to say slowly: "My agent helps [who] by [doing what] when [in what situation].". A good GitHub workflow is like a well-run meeting: everyone knows the topic, the next action, and who has the floor.

      +

      Jamie: Let's pause on 3. Phase 2: Write the Agent File. What should a learner take away from it?

      +

      Alex: The reason 3. Phase 2: Write the Agent File matters is that an agent file is a Markdown file with YAML frontmatter that defines the agent's identity, and a body that contains the agent's instructions. That gives the learner a simple foothold: agent files live in the.github/agents/ directory (for GitHub Copilot agents) or in team-specific directories in the accessibility-agents repository.

      -

      Jamie: What is the final checkpoint?

      -

      Alex: You should be able to point to the evidence, explain the action, and describe what you would do next if this were a real open source project. If you can teach the move back, you have learned it.

      -

      Jamie: And if they get stuck?

      -

      Alex: Read the latest message, not the loudest worry. Check the issue, the branch, the pull request, the status check, or the bot comment. Then ask for help with those facts in hand. That is how professionals collaborate.

      -
      - +

      Alex: Keep the teaching thread moving. Start with File location and naming: Example.github/agents/alt-text-validator.md.

      +

      Jamie: Let's pause on The agent file structure. What should a learner take away from it?

      +

      Alex: Start with The agent file structure. There is something to understand, something to try, and something that proves the try worked.

      +

      Alex: First, yAML frontmatter -- metadata between --- markers at the top of the file. Then, instructions body -- Markdown content that tells the agent how to behave. Treat it like a recipe: do not add the next ingredient until the previous one is actually in the bowl.

      +

      Alex: Keep the teaching thread moving. This is where YAML frontmatter fields becomes real: vague descriptions result in missed automatic routing. That matters in practice: Weak: Helps with accessibility - Strong: Checks markdown files for accessibility issues, fixes descriptive links and heading hierarchy, and flags alt text for human review The more specific the description, the more reliably Copilot invokes the right agent for. The workshop is closer to rehearsal than lecture. You hear the move, try the move, and then check what changed.

      -

      Challenge 14: Template Remix

      -

      YAML issue forms, accessible labels, required fields, and useful maintainer intake.

      -
      -Read Transcript - Challenge 14: Template Remix - -

      Transcript

      -

      Alex: Welcome back to Challenge Coach. Today we are taking on Template Remix, one careful step at a time.

      -

      Jamie: And I am Jamie. I am listening for the confusing parts: where to start, what to submit, and how to tell whether it worked.

      +

      Jamie: Let's pause on Writing the instructions body. What should a learner take away from it?

      +

      Alex: Keep the learner anchored in Writing the instructions body. The instructions body tells the agent how to behave. This is the part to say slowly: Write it as if you are briefing a new team member on their first day.

      +

      Alex: The practical takeaway is this. Start with identity. "You are a [role] focused on [area].". List responsibilities. What specific tasks does this agent handle? Set guardrails. What should the agent never do? What are its limits? Provide examples. Show what good output looks like.

      +

      Alex: Keep the teaching thread moving. Start with Learning Cards: Writing the Agent File. There is something to understand, something to try, and something that proves the try worked.

      +

      Alex: The practical takeaway is this. Create your agent file with Ctrl+N, then Ctrl+S and save to.github/agents/your-agent-name.md -- the Explorer navigates to the folder automatically. Use Ctrl+Shift+O to navigate between YAML frontmatter fields and Markdown headings (Responsibilities, Guardrails) in your agent file. The YAML frontmatter is between --- markers at the top -- your screen reader announces these as horizontal rules. Agent files are standard Markdown -- open Markdown Preview (Ctrl+Shift+V) side by side to verify formatting as you write. The YAML frontmatter at the top uses name: and description: fields -- keep these on separate lines for readability at high zoom. Use a consistent heading hierarchy ( for title, for sections) so the Outline view (Ctrl+Shift+O) shows a clean structure.

      +

      Jamie: Let's pause on 4. Phase 3: Define Responsibilities and Guardrails. What should a learner take away from it?

      +

      Alex: Start with 4. Phase 3: Define Responsibilities and Guardrails: Responsibilities and guardrails are the most important parts of your agent's instructions. The next useful detail is this: The autograder checks that both sections exist.

      -

      Alex: In this challenge, the learner is practicing yAML issue forms, accessible labels, required fields, and useful maintainer intake. The point is not to rush. The point is to leave a clear trace of good work.

      -

      Jamie: So we should name what success sounds like before the learner starts clicking or typing.

      -

      Alex: Yes. When the checkpoint is clear, the learner can tell the difference between being stuck and simply not being finished yet.

      +

      Alex: Keep the teaching thread moving. Here is the plain-English version of Writing responsibilities. Responsibilities define what the agent does. Put another way, each responsibility should describe one discrete action the agent can take. It is like learning a transit route. The names of the stops matter because they tell you whether you are still going the right direction.

      +

      Alex: The practical takeaway is this. Scan HTML files for tags missing the alt attribute. Check that all elements have visible text or an aria-label. Verify heading levels do not skip (e.g., h1 to h3 without h2). Help with accessibility.

      +

      Jamie: Let's pause on Writing guardrails. What should a learner take away from it?

      +

      Alex: This is where Writing guardrails becomes real: guardrails define what the agent must not do. That matters in practice: They prevent the agent from overstepping, giving harmful advice, or acting without permission.

      +

      Alex: The practical takeaway is this. Never auto-fix code without asking the user first. Do not provide medical, legal, or financial advice when discussing accessibility compliance. Limit reviews to the files the user specifies -- do not scan the entire repository. If a finding is uncertain, say so explicitly rather than presenting it as definitive.

      +

      Alex: Keep the teaching thread moving. Start with Learning Cards: Responsibilities and Guardrails. There is something to understand, something to try, and something that proves the try worked.

      +

      Alex: The practical takeaway is this. Use Responsibilities and Guardrails as exact heading names -- the autograder searches for these strings. Each responsibility should start with a verb (Scan, Check, Verify, Flag) -- this makes them concrete and testable. Guardrails should start with "Never" or "Do not" to set clear boundaries your screen reader identifies as restrictions when reviewing the file. Format responsibilities as a bulleted list (starting with -) for easy scanning at high zoom -- one responsibility per bullet. Keep each guardrail to a single line so it remains visible without horizontal scrolling at your zoom level. Use bold text for emphasis on critical guardrails (e.g., Never modify files without approval ) to improve visual scanning.

      -

      Jamie: What makes this practice feel low-stakes but still real?

      -

      Alex: Start with Challenge 14: Template Remix: What you will do: Create your own custom issue template by studying the existing registration template and remixing it for a new purpose.

      -

      Jamie: How would you walk the room through that step by step?

      -

      Alex: Start with Instructions. There is something to understand, something to try, and something that proves the try worked.

      -

      Alex: The practical anchors are these. A name field (required -- the autograder checks for this). A description field. A title field with a prefix pattern. At least one textarea or input field in the body. Accessibility feedback form. Workshop improvement suggestion.

      -

      Alex: First, study the sample template at docs/samples/chapter-15-registration-remix-example.yml to understand the YAML format. Then, create a new file at.github/ISSUE TEMPLATE/YOUR-USERNAME-template.yml on your branch. After that, your template must. Finally, choose your own topic. Ideas. Treat it like a recipe: do not add the next ingredient until the previous one is actually in the bowl.

      -

      Jamie: What does the learner do first, second, and then after that?

      -

      Alex: First, commit and push your template. It is a checklist, but a meaningful one: every item creates evidence that the next step is safe.

      -

      Jamie: What is the one idea that makes the next few steps less mysterious?

      -

      Alex: This is where Minimum YAML structure becomes real: autograded: The autograder verifies that a YAML file exists in.github/ISSUE TEMPLATE/ with a valid name field.

      +

      Jamie: Let's pause on 5. Phase 4: Test Your Agent Locally. What should a learner take away from it?

      +

      Alex: The reason 5. Phase 4: Test Your Agent Locally matters is that see also: Chapter 18: Fork and Contribute covers the fork-and-PR workflow you will use to submit your agent. That gives the learner a simple foothold: before opening a pull request, test your agent to verify it works.

      +

      Jamie: Let's pause on Testing with GitHub Copilot Chat. What should a learner take away from it?

      +

      Alex: Start with Testing with GitHub Copilot Chat. There is something to understand, something to try, and something that proves the try worked.

      +

      Alex: The practical takeaway is this. Understand its mission? Follow its responsibilities? Respect its guardrails?

      +

      Alex: First, open VS Code with the accessibility-agents repository. Then, ensure your agent file is saved in.github/agents/. After that, open GitHub Copilot Chat (Ctrl+Shift+I or Cmd+Shift+I). Finally, invoke your agent by name: @your-agent-name check this file for accessibility issues. Think of it as a rail line: each stop confirms you are still on the right route before the next one.

      +

      Jamie: Before we leave Testing with GitHub Copilot Chat, what is the practical point?

      +

      Alex: First, observe the response. Does the agent. Treat it like a recipe: do not add the next ingredient until the previous one is actually in the bowl.

      +

      Jamie: Let's pause on Testing checklist. What should a learner take away from it?

      +

      Alex: Start with Testing checklist. There is something to understand, something to try, and something that proves the try worked.

      +

      Alex: The practical takeaway is this. [ ] The agent responds when invoked by name. [ ] The agent stays within its defined responsibilities. [ ] The agent does not violate any guardrails. [ ] The agent's output is useful and specific. [ ] The agent handles edge cases gracefully (empty files, no issues found).

      -

      Alex: Now bring the learner back to the room. Keep the learner anchored in Peer simulation check. Create a test issue using your own custom template, then compare it with the seeded challenge templates. This is the part to say slowly: If you have real buddy access, you may also try your buddy's template.

      -

      Jamie: What should they understand before typing anything?

      -

      Alex: The reason Example template matters is that file.github/ISSUE TEMPLATE/accessibility-report.yml.

      -

      Alex: Treat examples as spoken recipes, not decorations. You may hear something like The name appears in the template chooser when someone clicks "New Issue"; name: Accessibility Report; The description appears below the name in the chooser; description: Report an accessibility barrier in workshop materials; Labels are automatically applied to. Read the command, understand what it changes, then run it only when the repository state matches the lesson.

      +

      Jamie: Let's pause on Iterating on your agent. What should a learner take away from it?

      +

      Alex: This is where Iterating on your agent becomes real: if the agent does not behave as expected. That matters in practice: Most students iterate 2-3 times before they are satisfied.

      +

      Alex: First, read its instructions carefully. Is anything ambiguous? Then, add more specific instructions or examples. After that, test again with the same prompt. Finally, repeat until the behavior matches your intent. It is a checklist, but a meaningful one: every item creates evidence that the next step is safe.

      +

      Jamie: Let's pause on Learning Cards: Testing Your Agent. What should a learner take away from it?

      +

      Alex: Start with Learning Cards: Testing Your Agent. There is something to understand, something to try, and something that proves the try worked.

      +

      Alex: The practical takeaway is this. Open Copilot Chat (Ctrl+Shift+I) and type @your-agent-name followed by a test prompt -- your screen reader announces the response as it streams. Press Alt+F2 after the response finishes to read the full output in Accessible View with arrow keys. If the agent does not respond as expected, edit the.agent.md file and ask again -- Copilot picks up changes immediately. Agent responses appear in the Copilot Chat panel -- widen the panel by dragging its left edge for better readability. Test with a simple prompt first (e.g., "review this file") and read the full response before trying complex requests. Use Accessible View (Alt+F2) to read responses at your preferred editor font size instead of the Chat panel's default.

      +

      Jamie: Let's pause on Tool Cards: Open Your Capstone PR. What should a learner take away from it?

      +

      Alex: The reason Tool Cards: Open Your Capstone PR matters is that VS Code Desktop (primary for Day 2). The interface gets friendlier when it stops being a wall of controls and starts being a set of named places.

      +

      Alex: First, push your branch: Ctrl+Shift+P Git: Push. Then, ctrl+Shift+P GitHub Pull Requests: Create Pull Request. After that, set base repo to Community-Access/accessibility-agents, fill in the title and description. Finally, navigate to your fork on GitHub. The rhythm is simple: orient, act, verify, then continue.

      +

      Jamie: Before we leave Tool Cards: Open Your Capstone PR, what is the practical point?

      +

      Alex: First, click Contribute Open pull request. Then, verify the base is Community-Access/accessibility-agents:main and the compare is your branch. Think of it as a rail line: each stop confirms you are still on the right route before the next one.

      +

      Alex: Treat examples as spoken recipes, not decorations. You may hear something like git push -u origin your-branch; gh pr create --repo Community-Access/accessibility-agents. Read the command, understand what it changes, then run it only when the repository state matches the lesson.

      +
      +

      Jamie: Let's pause on Pre-PR checklist. What should a learner take away from it?

      +

      Alex: Start with Pre-PR checklist. There is something to understand, something to try, and something that proves the try worked.

      +

      Alex: The practical takeaway is this. [ ] Your agent file has valid YAML frontmatter (name and description fields). [ ] Your agent file has a Responsibilities section. [ ] Your agent file has a Guardrails section. [ ] The file is in the correct directory. [ ] You have committed and pushed to your fork.

      +

      Jamie: Let's pause on Open the PR. What should a learner take away from it?

      +

      Alex: Here is the plain-English version of Open the PR. Follow the pull request steps from Chapter 18, Step 7.

      +

      Alex: The practical takeaway is this. Your mission statement from Phase 1. What the agent does (summary of responsibilities). Any design decisions you made. How you tested it.

      +

      Alex: First, push your branch: git push -u origin agents/your-username-agent-name. Then, go to the upstream repository on GitHub.com. After that, click the banner or go to Pull Requests and click New pull request, then compare across forks. Finally, select your fork and branch. Treat it like a recipe: do not add the next ingredient until the previous one is actually in the bowl.

      +

      Jamie: Before we leave Open the PR, what is the practical point?

      +

      Alex: First, write a PR title: "Add [agent-name] accessibility agent". Then, in the PR body,. After that, create the pull request. It is a checklist, but a meaningful one: every item creates evidence that the next step is safe.

      +

      Jamie: Let's pause on The autograder. What should a learner take away from it?

      +

      Alex: This is where The autograder becomes real: the repository has an autograding workflow that runs on every pull request. That matters in practice: The autograder posts results as a comment on your PR.

      +
      +

      Alex: Keep the teaching thread moving. Start with Learning Cards: Opening Your Pull Request. There is something to understand, something to try, and something that proves the try worked.

      +

      Alex: The practical takeaway is this. The autograder comment appears in the PR timeline -- navigate to Comments on GitHub.com with h (heading navigation) to find the results. Each autograder check is listed with a pass/fail status and point value -- listen for "10/10" or "0/15" to identify which checks need attention. If a check fails, read the failure message, fix the issue locally, commit, push, and the autograder re-runs automatically. The autograder results appear as a comment with a table showing checks, points, and pass/fail status -- zoom with Ctrl+= to read the details. Green checkmarks indicate passing checks; red X marks indicate failures -- pair with High Contrast theme for clearest visibility. Your PR description should include your mission statement, responsibilities summary, and testing notes.

      +

      Jamie: Let's pause on 7. Phase 6: Respond to Review. What should a learner take away from it?

      +

      Alex: The reason 7. Phase 6: Respond to Review matters is that after the autograder passes, a peer reviewer (your buddy or another student) and a facilitator will review your agent.

      +

      Alex: Keep the teaching thread moving. Start with What reviewers look for. There is something to understand, something to try, and something that proves the try worked.

      +

      Alex: The practical takeaway is this. Clarity: Are the instructions easy to understand? Specificity: Are responsibilities concrete and actionable? Safety: Are guardrails sufficient to prevent harmful behavior? Usefulness: Would this agent actually help someone? Scope: Does the agent try to do too much or too little?

      +
      +

      Jamie: Let's pause on Responding to feedback. What should a learner take away from it?

      +

      Alex: Here is the plain-English version of Responding to feedback. This is the same process from Chapter 18, Step 8.

      +

      Alex: First, read each review comment. Then, make changes locally. After that, commit and push. The PR updates automatically. Finally, reply to each comment explaining your changes. Treat it like a recipe: do not add the next ingredient until the previous one is actually in the bowl.

      +

      Alex: Keep the teaching thread moving. This is where When your PR is merged becomes real: your agent is now part of the accessibility-agents ecosystem. That matters in practice: It is available to anyone who uses the repository. The workshop is closer to rehearsal than lecture. You hear the move, try the move, and then check what changed.

      +

      Alex: The practical takeaway is this. You can navigate the fork workflow end to end. You can write clear, structured technical documentation. You understand accessibility concepts well enough to teach an AI agent about them. You can respond constructively to code review.

      +

      Jamie: Let's pause on 8. Capstone Rubric. What should a learner take away from it?

      +

      Alex: Keep the learner anchored in 8. Capstone Rubric. The capstone is worth 60 autograded points plus peer review.

      +
      +

      Alex: Keep the teaching thread moving. The reason What "meets expectations" looks like matters is that a capstone that meets expectations has.

      +

      Alex: The practical takeaway is this. A focused mission (not "help with accessibility" -- something specific). At least 3 concrete responsibilities. At least 3 meaningful guardrails. A PR description that explains the agent's purpose. All autograder checks passing.

      +

      Jamie: Let's pause on What "exceeds expectations" looks like. What should a learner take away from it?

      +

      Alex: Start with What "exceeds expectations" looks like: A capstone that exceeds expectations also has.

      +

      Alex: The practical takeaway is this. Examples of expected input and output in the agent instructions. A section describing the agent's limitations. Evidence of testing (screenshots or transcripts in the PR description). Thoughtful responses to review feedback.

      +

      Alex: Keep the teaching thread moving. Here is the plain-English version of 9. Example Agents for Inspiration. These examples show the range of valid agent designs. Put another way, your agent does not need to be this long, but it should be this clear. It is like learning a transit route. The names of the stops matter because they tell you whether you are still going the right direction.

      +
      +

      Jamie: Let's pause on Example 1: Heading Hierarchy Checker. What should a learner take away from it?

      +

      Alex: This is where Example 1: Heading Hierarchy Checker becomes real: mission: Validates that HTML and Markdown documents follow a correct heading hierarchy (no skipped levels).

      +

      Alex: The practical takeaway is this. Scan files for heading elements (h1 through h6 in HTML, through in Markdown). Report any instance where a heading level is skipped (e.g., h2 followed by h4). Suggest the correct heading level for each violation. Check that there is exactly one h1 per page. Do not modify files -- only report findings. Do not change heading text, only heading levels.

      +

      Alex: A solid navigation habit is to prove where you are before activating controls. Headings, landmarks, and the address bar are not trivia; they are your map.

      +

      Alex: Keep the teaching thread moving. Keep the learner anchored in Example 2: PR Description Quality Gate. Mission: Reviews pull request descriptions to ensure they contain enough context for reviewers.

      +

      Alex: The practical takeaway is this. Check that the PR description is at least 50 characters. Verify the description references an issue with Closes XX or Fixes XX. Check for a summary of changes made. Verify the description explains why the change was made, not just what was changed. Never approve or block a PR based solely on description quality. Do not rewrite the description for the author -- suggest improvements.

      +

      Jamie: Let's pause on Example 3: Keyboard Navigation Auditor. What should a learner take away from it?

      +

      Alex: The reason Example 3: Keyboard Navigation Auditor matters is that mission: Checks web components for keyboard accessibility compliance.

      +

      Alex: The practical takeaway is this. Verify all interactive elements are reachable via Tab key. Check that custom components have appropriate tabindex values. Validate that focus order follows visual layout. Detect keyboard traps (elements that receive focus but cannot release it via keyboard). Do not modify component code without user approval. Flag potential issues with confidence levels (certain, likely, possible).

      +
      +

      Alex: Keep the teaching thread moving. Start with The universal safety net: If everything else fails, post this on your challenge issue. The next useful detail is this: I attempted Challenge 16 and here is what happened: What I tried: [specific actions] What I expected: [what should have happened] What actually happened: [error or unexpected result] What I learned: [even from failure, what do I understand now?]. Think of it like entering a new building: first you find the lobby, then the room, then the door you actually need.

      +
      +

      Jamie: What is the final checkpoint?

      +

      Alex: You should be able to point to the evidence, explain the action, and describe what you would do next if this were a real open source project. If you can teach the move back, you have learned it.

      +

      Jamie: And if they get stuck?

      +

      Alex: Read the latest message, not the loudest worry. Check the issue, the branch, the pull request, the status check, or the bot comment. Then ask for help with those facts in hand. That is how professionals collaborate.

      +
      + +
      +

      54. Challenge bonus-c: Group Challenge

      +

      Collaborative contribution, division of work, and communication across a small team.

      +

      Practice focus: Bonus

      +

      Audio and transcript are being regenerated for this episode.

      +
      +Read Transcript - Challenge bonus-c: Group Challenge + +

      Transcript

      +

      Alex: You are listening to Challenge Coach: Group Challenge. I am Alex, and this is the calm walkthrough before the hands-on work.

      +

      Jamie: And I am Jamie. I will make sure we teach the skill instead of just reading the checklist aloud.

      +
      +

      Alex: The focus is Collaborative contribution, division of work, and communication across a small team. We will explain the concept, the action, the evidence, and the most common recovery path.

      +

      Jamie: So the learner needs the why, the move, and the checkpoint all in the same mental pocket.

      +

      Alex: That is the teaching shape: understand the concept, do the smallest real action, then verify the result before moving on.

      +
      +

      Jamie: What makes this practice feel low-stakes but still real?

      +

      Alex: Start with Bonus C: Create a Group Challenge: For students who: Want to design exercises for future cohorts. The next useful detail is this: What you will do: Design a collaborative challenge that 3-5 students could work on together, then document it in the learning-room.

      +

      Jamie: How would you walk the room through that step by step?

      +

      Alex: Start with Instructions. There is something to understand, something to try, and something that proves the try worked.

      +

      Alex: The practical anchors are these. Title -- a catchy, descriptive name. Goal -- what students will learn or accomplish. Team size -- how many people (recommend 3-5). Time estimate -- how long it should take. Instructions -- step-by-step guide. Success criteria -- how do students know they are done?

      +

      Alex: First, think of a task that requires collaboration -- something one person cannot easily do alone. Then, create a file: docs/group-challenges/YOUR-USERNAME-challenge.md. After that, your challenge design must. Finally, commit, push, and open a PR. Treat it like a recipe: do not add the next ingredient until the previous one is actually in the bowl.

      +

      Jamie: What is the one idea that makes the next few steps less mysterious?

      +

      Alex: Start with Design criteria. There is something to understand, something to try, and something that proves the try worked.

      +

      Alex: That shows up in the workshop in a few specific ways. Require genuine collaboration (not just dividing work). Have clear success criteria. Are accessible to all participants. Can be completed within the workshop timeframe.

      +
      +

      Alex: Now bring the learner back to the room. Keep the learner anchored in Challenge description. Students audit a sample web page for accessibility issues, relay-style. This is the part to say slowly: Each person has a different focus area.

      +

      Alex: For a learner, the useful signals are these. Student 1: Checks all images for meaningful alt text. Student 2: Reviews heading hierarchy (H1, H2, H3 order). Student 3: Tests every link for descriptive text (no "click here"). Student 4: Checks color contrast on text elements.

      +

      Jamie: What is the ordered workflow?

      +

      Alex: Start with How it works. There is something to understand, something to try, and something that proves the try worked.

      +

      Alex: First, the group forks a sample repository containing a deliberately imperfect HTML page. Then, each student creates a branch for their focus area. After that, each student files issues for the problems they find. Finally, the group discusses which fixes to prioritize. The rhythm is simple: orient, act, verify, then continue.

      +

      Jamie: Give me the sequence, because order matters here.

      +

      Alex: First, each student submits a PR fixing at least one issue. Then, the group reviews and merges each other's PRs. Think of it as a rail line: each stop confirms you are still on the right route before the next one.

      Alex: The useful habit is simple: orient first, act second, verify third. That pause before acting is part of the work.

      -

      Alex: That matters because of the next idea. Start with Alternate valid templates: Any topic works for this challenge. Think of it like entering a new building: first you find the lobby, then the room, then the door you actually need.

      -

      Alex: On the ground, that means a few things. A bug report template for the workshop. A feature request template for new workshop topics. A feedback template for session evaluations. A question template for asking for help.

      +

      Alex: That matters because of the next idea. Start with Evidence: Each student posts: their issues filed, their PR, and one review they gave. Think of it like entering a new building: first you find the lobby, then the room, then the door you actually need.

      Jamie: Okay, set the room for us. What are we walking into?

      -

      Alex: Here is the plain-English version of What matters. The learning objective is understanding structured issue templates as a way to guide contributors. Put another way, if your YAML file has a name, description, and at least one body field, you completed this challenge.

      -

      Alex: This is where the talk moves from concept to action. This is where Structuring Contributions for Clarity and Quality becomes real: issue templates turn a blank text box into a guided form. That matters in practice: They help contributors provide the information maintainers need, reduce back-and-forth, and make every issue immediately actionable.

      -

      Jamie: What does someone need before they touch the keyboard?

      -

      Alex: Keep the learner anchored in Before starting this chapter, verify you have completed. Day 2 Amplifier: In Chapter 19 (Accessibility Agents), you'll use @template-builder to automate template creation. This is the part to say slowly: Complete this chapter first, then come back to Chapter 19.

      -

      Alex: These are the details that keep the idea from floating away. [ ] Chapter 4: Working with Issues - 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). [ ] Chapter 16: GitHub Copilot - Optional but helpful for generating template variations.

      +

      Alex: Start with Why this works for a group. There is something to understand, something to try, and something that proves the try worked.

      +

      Alex: Here is what that changes in practice. Every student has a defined role so no one is left out. The relay structure means students depend on each other (Student 3 cannot fix link text if Student 1 has not pushed their alt text fixes yet). The final product is a genuinely more accessible page.

      +

      Alex: This is where the talk moves from concept to action. This is where What matters becomes real: the learning objective is designing collaborative work that gives every participant a meaningful role. That matters in practice: If your challenge design includes clear roles, concrete deliverables, and a reason for people to work together (not just alongside each other), you completed this bonus.

      +

      Jamie: Where do you want a learner to place their attention here?

      +

      Alex: Keep the learner anchored in How to Be an Effective and Respectful Open Source Contributor. Technical skills get your code into a project. This is the part to say slowly: Communication skills keep you welcomed in the community.

      -

      Alex: Before the learner moves on. The reason Workshop Recommendation (Chapter 17 / Challenge 14) matters is that chapter 17 is a template design and implementation chapter focused on structuring contributions with a concrete, familiar example. That gives the learner a simple foothold: it supports Challenge 14: Template Remix. The interface gets friendlier when it stops being a wall of controls and starts being a set of named places.

      -

      Alex: That becomes easier when you listen for these cues. There are 2-3 guided challenges (+ 1 optional). Automation check: none (template structure quality is design-focused). The evidence is issue comment or PR with template remixed or created. The pattern is analyze, remix, create, test.

      -

      Jamie: Give me the sequence, because order matters here.

      -

      Alex: Start with Challenge 14 Set. There is something to understand, something to try, and something that proves the try worked.

      -

      Alex: First, analyze the registration template - understand how the template you already filled out works. Then, remix the registration template - adapt it for a new use case (bug report, event, research). After that, create a Markdown template (optional) - build a Markdown-based template from scratch. Finally, test in the template chooser (optional) - verify your template appears and works. Think of it as a rail line: each stop confirms you are still on the right route before the next one.

      +

      Alex: Before the learner moves on. The reason Workshop Recommendation (Chapter 8) matters is that chapter 8 is a communication and culture chapter. The interface gets friendlier when it stops being a wall of controls and starts being a set of named places.

      +

      Alex: That becomes easier when you listen for these cues. There are 1 guided reflection (no bot grading). Automation check: none - communication quality is too subjective for fair automated scoring. The evidence is structured reflection comment on your assigned challenge issue. The pattern is read, reflect, commit to one behavior.

      +

      Jamie: What does the learner do first, second, and then after that?

      +

      Alex: Start with Chapter 8 Challenge Set. There is something to understand, something to try, and something that proves the try worked.

      +

      Alex: First, guided reflection - read the chapter, then post a short reflection comment committing to three specific collaboration behaviors. Think of it as a rail line: each stop confirms you are still on the right route before the next one.

      Jamie: Turn that into a path someone can follow.

      -

      Alex: Here is the plain-English version of Challenge 14.1 Step-by-Step: Analyze the Registration Template. Understand how professional YAML form templates work by examining the one you filled out to register for this workshop. Put another way, GitHub.com - reading the template file in the git-going-with-github repository.

      -

      Alex: That shows up in the workshop in a few specific ways. 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.

      -

      Alex: First, open the template file on GitHub.com (use the link above). Then, read the YAML frontmatter (top 5 lines) and identify. After that, read the field types in the body section. Note the four types used. Finally, for each field, identify the metadata. Treat it like a recipe: do not add the next ingredient until the previous one is actually in the bowl.

      -

      Jamie: What is the ordered workflow?

      -

      Alex: First, search the file for "accessible" - notice the description mentions that all fields work with screen readers. This is professional template thinking. Then, 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. It is a checklist, but a meaningful one: every item creates evidence that the next step is safe.

      -
      -

      Jamie: Let's pause on Challenge 14.2 Step-by-Step: Remix the Registration Template. What should a learner take away from it?

      -

      Alex: This is where Challenge 14.2 Step-by-Step: Remix the Registration Template becomes real: adapt the registration template for a different use case while keeping the same YAML structure. That matters in practice: VS Code with a repository where you have write access (your fork or personal repo), or github.dev.

      -

      Alex: For a learner, the useful signals are these. Source.github/ISSUE TEMPLATE/workshop-registration.yml. Remix sample: learning-room/docs/samples/challenge-14-registration-remix-example.yml. Keep: the YAML skeleton (name, description, title, labels, body). Keep: field structure (type, id, attributes, validations).

      -

      Alex: First, pick a new context for your template (for example: bug report, event attendance, product research, accessibility audit request). Then, copy the registration template file to a new file.github/ISSUE TEMPLATE/my-template.yml. After that, change the name and description in the frontmatter to match your new context. Finally, change the title prefix (for example: [Bug Report]: or [Event]: ). It is a checklist, but a meaningful one: every item creates evidence that the next step is safe.

      -

      Jamie: Before we leave Challenge 14.2 Step-by-Step: Remix the Registration Template, what is the practical point?

      -

      Alex: First, change the labels to appropriate labels for your use case. Then, replace each field's label, description, placeholder, and options to match your new context. After that, decide which fields should be required: true and which can be optional. Finally, validate your YAML syntax: copy the file contents to yamllint.com and fix any errors. It is like walking a hallway with named doors: read the sign, enter the right room, then confirm where you landed.

      -

      Jamie: Let's pause on Challenge 14.3 (Optional) Step-by-Step: Create a Markdown Template. What should a learner take away from it?

      -

      Alex: Keep the learner anchored in Challenge 14.3 (Optional) Step-by-Step: Create a Markdown Template. Create a Markdown-based template to compare the two template formats. This is the part to say slowly: VS Code with a repository where you have write access. A good GitHub workflow is like a well-run meeting: everyone knows the topic, the next action, and who has the floor.

      -

      Alex: First, create a new file.github/ISSUE TEMPLATE/my-markdown-template.md. Then, add the Markdown template frontmatter at the top. After that, markdown templates use about instead of description (unlike YAML form templates). Finally, below the frontmatter, add 3-4 sections with HTML comment instructions. It is like walking a hallway with named doors: read the sign, enter the right room, then confirm where you landed.

      -

      Jamie: Before we leave Challenge 14.3 (Optional) Step-by-Step: Create a Markdown Template, what is the practical point?

      -

      Alex: First, commit and push. The rhythm is simple: orient, act, verify, then continue.

      -

      Jamie: Let's pause on Challenge 14.4 (Optional): Test in the Template Chooser. What should a learner take away from it?

      -

      Alex: The reason Challenge 14.4 (Optional): Test in the Template Chooser matters is that you are done when: Your template works and appears in the GitHub template picker.

      -

      Alex: First, navigate to your test repository on GitHub.com. Then, activate New Issue. After that, verify your template appears in the template chooser. Finally, activate Get started on your template and file a test issue. The rhythm is simple: orient, act, verify, then continue.

      +

      Alex: Here is the plain-English version of Challenge 8.1 Step-by-Step: Guided Reflection. Identify three concrete communication behaviors you will practice during the rest of the workshop. Put another way, your assigned Chapter 8 challenge issue in your Learning Room repository on GitHub.com.

      +

      Alex: The parts worth keeping in working memory are these. 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.".

      +

      Alex: First, read through the chapter content below, paying attention to the sections on GitHub Flow, constructive feedback, and asking for help. Then, as you read, think about one situation from Day 1 where communication helped (or could have helped) you. After that, open your assigned Chapter 8 challenge issue (the one titled "Chapter 8.1: Guided Reflection (@yourname)"). Finally, scroll to the comment box at the bottom of the issue. Treat it like a recipe: do not add the next ingredient until the previous one is actually in the bowl.

      +

      Jamie: Let's pause on Challenge 8.1 Step-by-Step: Guided Reflection. What should a learner take away from it?

      +

      Alex: First, post a reflection comment using this format. Then, for each prompt, write one specific, actionable sentence - not a vague goal. After that, activate the Comment button (or press Ctrl+Enter). It is a checklist, but a meaningful one: every item creates evidence that the next step is safe.

      -

      Alex: Here is the practical turn. Start with Completing Challenge 14: Submit Your Evidence: Open your assigned Challenge 14 issue and post a completion comment. The next useful detail is this: Close your Challenge 14 issue when done.

      -

      Jamie: What would you say to someone who is already bracing for this to be too much?

      -

      Alex: Start with Expected Overall Outcomes. There is something to understand, something to try, and something that proves the try worked.

      -

      Alex: Here is what that changes in practice. 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.

      +

      Jamie: How do these exercises create confidence instead of pressure?

      +

      Alex: This is where Completing Chapter 8: Submit Your Evidence becomes real: the reflection comment itself is your evidence. That matters in practice: The facilitator reviews your comment for specificity.

      +

      Alex: That connects to another useful point. Start with Expected Outcomes. There is something to understand, something to try, and something that proves the try worked.

      +

      Alex: On the ground, that means a few things. 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.

      Jamie: Let's pause on If You Get Stuck. What should a learner take away from it?

      -

      Alex: This is where If You Get Stuck becomes real: continue learning: The GitHub Skills course Introduction to Repository Management covers templates and contributor settings in an interactive format. That matters in practice: See Appendix Z for the full catalog. The workshop is closer to rehearsal than lecture. You hear the move, try the move, and then check what changed.

      -

      Alex: First, cannot find the registration template? Look in.github/ISSUE TEMPLATE/workshop-registration.yml in the git-going-with-github repository. Then, 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. After that, yAML not parsing? Compare with the remix sample in learning-room/docs/samples/challenge-14-registration-remix-example.yml and check indentation. Finally, 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. It is a checklist, but a meaningful one: every item creates evidence that the next step is safe.

      +

      Alex: Start with If You Get Stuck. There is something to understand, something to try, and something that proves the try worked.

      +

      Alex: First, use one simple sentence per prompt - do not overthink it. Then, focus on one real behavior you can start doing today, not an abstract principle. After that, if writing feels hard, draft bullet points first in a text editor, then paste into the comment. Finally, look at the "Giving Feedback" and "Asking for Help" sections in this chapter for concrete examples. The rhythm is simple: orient, act, verify, then continue.

      Jamie: Before we leave If You Get Stuck, what is the practical point?

      -

      Alex: First, 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. Then, remix approach feels overwhelming? Start by changing just the field labels and descriptions. Do not change the structure yet. After that, ask facilitator to review your template and suggest improvements. Finally, finished but not sure you did it right? Compare your work against the Challenge 14 reference solution. It is like walking a hallway with named doors: read the sign, enter the right room, then confirm where you landed.

      +

      Alex: First, ask facilitator for one example response and adapt it to your own words. Then, finished but not sure you did it right? Compare your work against the Challenge 8 reference solution. Think of it as a rail line: each stop confirms you are still on the right route before the next one.

      -

      Jamie: If I am listening before the workshop starts, what should settle in my mind first?

      -

      Alex: Keep the learner anchored in Learning Moment. They do not restrict expert contributors - they guide newcomers. This is the part to say slowly: A template that takes 2 minutes to understand saves 30 minutes of back-and-forth questions later.

      +

      Alex: Here is the practical turn. Start with Learning Moment: Technical quality and communication quality work together. The next useful detail is this: Respectful, clear communication helps good code get merged faster.

      Jamie: Let's pause on Learning Pattern Used in This Chapter. What should a learner take away from it?

      Alex: Start with Learning Pattern Used in This Chapter. There is something to understand, something to try, and something that proves the try worked.

      -

      Alex: First, analyze an existing, working example before building your own. Then, remix by changing content while keeping structure (safe, fast iteration). After that, create from scratch only after you understand the pattern (Markdown template). Finally, test the result in the real environment (template chooser). The rhythm is simple: orient, act, verify, then continue.

      -

      Jamie: Where do you want a learner to place their attention here?

      -

      Alex: Start with 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.

      -

      Alex: A few details make that real. Instructions explaining what information is needed. Section headers guiding them through the report. Checkboxes for conditions to verify. Placeholder text showing the expected format.

      -

      Alex: A solid issue habit is to read the title, the body, and the timeline before acting. You are listening for the requested action, the missing evidence, and the person who needs a response.

      +

      Alex: First, read and absorb community norms (not just rules, but reasons). Then, reflect on personal experience (what worked, what was hard). After that, commit to specific behaviors in writing (public accountability). Finally, apply those behaviors in upcoming chapters (reviews, comments, PRs). Treat it like a recipe: do not add the next ingredient until the previous one is actually in the bowl.

      +

      Alex: Keep the thread going. This is where GitHub Flow - The Standard Contribution Workflow becomes real: before diving into communication norms, it helps to understand the workflow that gives all of those conversations their context. That matters in practice: GitHub Flow is the lightweight branching model recommended for open source contribution. The workshop is closer to rehearsal than lecture. You hear the move, try the move, and then check what changed.

      -

      Alex: This is the part worth saying out loud. Here is the plain-English version of Why they matter for accessibility projects. Accessibility bugs require specific context that general bug templates often omit. Put another way, without this context, maintainers ask follow-up questions - which delays the fix and uses everyone's time. It is like learning a transit route. The names of the stops matter because they tell you whether you are still going the right direction.

      -

      Alex: The parts worth keeping in working memory are these. Which screen reader and version? Which browser and version? Which operating system? Which WCAG success criterion is affected?

      -

      Alex: A solid pull request habit is to separate three questions: what changed, why it changed, and what still needs review. That keeps the conversation useful instead of noisy.

      -

      Jamie: Give me the version that sounds like an instructor, not a manual.

      -

      Alex: This is where 2. How Templates Work on GitHub becomes real: templates live in a specific folder in your repository.

      -

      Alex: The next layer is this. Keep the learner anchored in Description. Templates live inside your-repo/.github/. This is the part to say slowly: 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).

      +

      Jamie: If I am listening before the workshop starts, what should settle in my mind first?

      +

      Alex: Start with Why This Model Works. There is something to understand, something to try, and something that proves the try worked.

      +

      Alex: These are the details that keep the idea from floating away. 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.

      +

      Alex: Another way to ground it. The reason GitHub Flow vs Git Flow matters is that you may encounter "Git Flow" (sometimes written "GitFlow") in older projects or enterprise environments. That gives the learner a simple foothold: this section explains what Git Flow is, how it differs from GitHub Flow, and why this workshop teaches GitHub Flow.

      +

      Alex: A solid Git habit is to know which branch you are on, what changed, and what confirmation you expect before you run the next command.

      +

      Jamie: What would you say to someone who is already bracing for this to be too much?

      +

      Alex: Start with What Git Flow Is: Git Flow is a branching model published by Vincent Driessen in 2010. The next useful detail is this: It was designed for teams that ship versioned releases on a schedule (desktop software, mobile apps, embedded systems).

      -

      Jamie: Let's pause on Example config.yml. What should a learner take away from it?

      -

      Alex: The reason Example config.yml matters is that with blank issues enabled: false, the "Open a blank issue" link disappears from the template chooser. That gives the learner a simple foothold: contributors must use one of your structured templates or one of the contact links.

      -

      Alex: Keep the thread going. Start with Learning Cards: How Templates Work on GitHub. There is something to understand, something to try, and something that proves the try worked.

      -

      Alex: The room should hear these as checkpoints. 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. 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.

      -

      Jamie: Let's pause on 3. Navigating the Template Picker. What should a learner take away from it?

      -

      Alex: Here is the plain-English version of 3. Navigating the Template Picker. When a repository has multiple templates, GitHub shows a template chooser page before the issue editor. Put another way, screen reader users - NVDA / JAWS (Windows).

      -

      Alex: First, click the Issues tab on any repository. Then, click the New issue button. After that, the template chooser page loads - templates appear as cards with a title, description, and "Get started" button. Finally, click "Get started" on the template you want. Treat it like a recipe: do not add the next ingredient until the previous one is actually in the bowl.

      -

      Jamie: Before we leave 3. Navigating the Template Picker, what is the practical point?

      -

      Alex: First, the issue editor opens with that template's content pre-filled. Then, navigate to the Issues tab (press T from the repository tabs landmark). After that, activate "New issue" button. Finally, the template chooser page loads. It is a checklist, but a meaningful one: every item creates evidence that the next step is safe.

      +

      Jamie: Let's pause on How the Git Flow Cycle Works. What should a learner take away from it?

      +

      Alex: Start with How the Git Flow Cycle Works. There is something to understand, something to try, and something that proves the try worked.

      +

      Alex: First, developers branch feature/my-feature off develop and work there. Then, completed features merge back into develop via pull request. After that, when develop has enough features for a release, a release/1.2.0 branch is created. Finally, the release branch gets final testing, bug fixes, and version number updates. Treat it like a recipe: do not add the next ingredient until the previous one is actually in the bowl.

      +

      Jamie: Before we leave How the Git Flow Cycle Works, what is the practical point?

      +

      Alex: First, the release branch merges into main (tagged with the version) and back into develop. Then, if a critical bug is found in production, a hotfix/ branch is created from main, fixed, and merged into both main and develop. It is a checklist, but a meaningful one: every item creates evidence that the next step is safe.

      +

      Jamie: Give me the version that sounds like an instructor, not a manual.

      +

      Alex: This is where How GitHub Flow Differs becomes real: the following table compares GitHub Flow and Git Flow across key dimensions.

      +

      Alex: A solid pull request habit is to separate three questions: what changed, why it changed, and what still needs review. That keeps the conversation useful instead of noisy.

      +

      Alex: The next layer is this. Start with When You Might See Git Flow. There is something to understand, something to try, and something that proves the try worked.

      +

      Alex: The room should hear these as checkpoints. 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.

      -

      Alex: Another way to ground it. This is where Bypassing the Chooser becomes real: if you want to file an issue without using a template.

      -

      Alex: The practical takeaway is this. Scroll past all templates to the bottom of the chooser page. Activate "Open a blank issue".

      -

      Jamie: Let's pause on Learning Cards: Navigating the Template Picker. What should a learner take away from it?

      -

      Alex: Start with Learning Cards: Navigating the Template Picker. There is something to understand, something to try, and something that proves the try worked.

      -

      Alex: The practical takeaway is this. 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. 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.

      -

      Jamie: Let's pause on 4. The Accessibility Agents Issue Templates. What should a learner take away from it?

      -

      Alex: The reason 4. The Accessibility Agents Issue Templates matters is that accessibility Agents uses templates to structure contributions. That gives the learner a simple foothold: navigate to.github/ISSUE TEMPLATE/ in the repository to read them. The interface gets friendlier when it stops being a wall of controls and starts being a set of named places.

      -

      Alex: First, click the Code tab on the repository. Then, click the.github folder in the file listing. After that, click ISSUE TEMPLATE. Finally, you'll see the template files - click any to read it. The rhythm is simple: orient, act, verify, then continue.

      -

      Jamie: Before we leave 4. The Accessibility Agents Issue Templates, what is the practical point?

      -

      Alex: First, open the Code tab. Then, use Ctrl+Alt+Down/Up (NVDA/JAWS) or VO+Arrow (VoiceOver) in the files table to reach the.github folder. After that, activate the folder. Finally, activate ISSUE TEMPLATE. Think of it as a rail line: each stop confirms you are still on the right route before the next one.

      +

      Jamie: Where is the promise of the workshop, underneath all the logistics?

      +

      Alex: The reason Why This Workshop Uses GitHub Flow matters is that for open source contribution - especially at a hackathon or when contributing to web-based projects - GitHub Flow is what you want. That gives the learner a simple foothold: it is what GitHub itself uses and what most modern open source projects follow.

      +

      Alex: This is the part worth saying out loud. Start with The Unwritten Rule: One Thing Per Branch: A branch and its PR should do one thing. The next useful detail is this: If you are fixing a broken link and you notice a typo nearby, fix the typo in a separate branch and PR. Think of it like entering a new building: first you find the lobby, then the room, then the door you actually need.

      +

      Jamie: Let's pause on Learning Cards: GitHub Flow. What should a learner take away from it?

      +

      Alex: Start with Learning Cards: GitHub Flow. There is something to understand, something to try, and something that proves the try worked.

      +

      Alex: A few details make that real. 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). 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.

      -

      Jamie: Let's pause on Reading a Template File. What should a learner take away from it?

      -

      Alex: Start with 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").

      -

      Alex: The practical takeaway is this. Frontmatter (between --- delimiters): name, about, title, labels, assignees.

      -

      Alex: Hold that next to this. Here is the plain-English version of Example frontmatter. The about text appears in the template chooser. Put another way, the title pre-fills the issue title field (the contributor replaces the placeholder).

      -

      Jamie: Let's pause on Tool Cards: Create an Issue Template. What should a learner take away from it?

      -

      Alex: Start with Tool Cards: Create an Issue Template. There is something to understand, something to try, and something that proves the try worked.

      -

      Alex: First, go to Settings General (scroll to Features section) Set up templates. Then, choose a starter template or create a blank one. After that, edit the template content and click Propose changes to commit. Finally, create the file.github/ISSUE TEMPLATE/your-template.md (or.yml for form-based). It is a checklist, but a meaningful one: every item creates evidence that the next step is safe.

      -

      Jamie: Before we leave Tool Cards: Create an Issue Template, what is the practical point?

      -

      Alex: First, add YAML frontmatter (name, description, title, labels) and body content. Then, commit and push. It is like walking a hallway with named doors: read the sign, enter the right room, then confirm where you landed.

      -

      Alex: Treat examples as spoken recipes, not decorations. You may hear something like 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. Read the command, understand what it changes, then run it only when the repository state matches the lesson.

      +

      Alex: Hold that next to this. This is where Keeping Your Fork Up to Date becomes real: when you fork a repository, you get a snapshot of the project at that moment. That matters in practice: The original repository (called "upstream") continues to evolve.

      +

      Jamie: Let's pause on Why Sync Your Fork? What should a learner take away from it?

      +

      Alex: Start with Why Sync Your Fork? There is something to understand, something to try, and something that proves the try worked.

      +

      Alex: The practical takeaway is this. 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.

      +

      Jamie: Let's pause on Method 1: GitHub Web Interface (Easiest). What should a learner take away from it?

      +

      Alex: The reason Method 1: GitHub Web Interface (Easiest) matters is that GitHub merges the upstream changes into your fork automatically. That gives the learner a simple foothold: screen reader users (NVDA / JAWS / VoiceOver). The interface gets friendlier when it stops being a wall of controls and starts being a set of named places.

      +

      Alex: First, navigate to your fork's main page: github.com/your-username/repo-name. Then, look for the sync indicator: "This branch is X commits behind upstream/main". After that, click the "Sync fork" button. Finally, click "Update branch". The rhythm is simple: orient, act, verify, then continue.

      +

      Jamie: Before we leave Method 1: GitHub Web Interface (Easiest), what is the practical point?

      +

      Alex: First, the sync button appears in the landmark that contains the branch selector. Then, press D to cycle through landmarks until you reach that region. After that, press B to cycle buttons until you hear "Sync fork" → press Enter. Finally, a dialog or page update presents "Update branch" - activate it. Think of it as a rail line: each stop confirms you are still on the right route before the next one.

      -

      Alex: That connects to another useful point. Keep the learner anchored in Choosing Between Markdown and YAML Templates. See also: Appendix Q: GitHub Actions covers how templates connect to automated workflows. This is the part to say slowly: Before creating a template, decide which format best suits your needs. A good GitHub workflow is like a well-run meeting: everyone knows the topic, the next action, and who has the floor.

      -

      Jamie: Let's pause on Use Markdown templates when. What should a learner take away from it?

      -

      Alex: Start with Use Markdown templates when. There is something to understand, something to try, and something that proves the try worked.

      -

      Alex: The practical takeaway is this. 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.

      -

      Alex: Keep the teaching thread moving. Start with Use YAML form templates when: For accessibility projects: YAML form templates are strongly recommended. The next useful detail is this: Accessibility bug reports require specific context (screen reader, browser, OS, version numbers) that Markdown templates rely on contributors to remember.

      -

      Alex: The practical takeaway is this. 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.

      +

      Jamie: There are a lot of tools in play. How do we keep that from feeling like a contest?

      +

      Alex: Start with Method 2: Git Command Line (VS Code Terminal): If you're working locally in VS Code.

      +

      Jamie: What should happen before anyone copies and runs it?

      +

      Alex: Start with One-time setup - add the upstream remote. There is something to understand, something to try, and something that proves the try worked.

      +

      Alex: Treat examples as spoken recipes, not decorations. You may hear something like git remote add upstream https://github.com/original-owner/repo-name.git; git remote -v Verify it was added. Read the command, understand what it changes, then run it only when the repository state matches the lesson.

      +

      Jamie: What should they understand before typing anything?

      +

      Alex: Start with Sync process. There is something to understand, something to try, and something that proves the try worked.

      +

      Alex: Treat examples as spoken recipes, not decorations. You may hear something like 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. Read the command, understand what it changes, then run it only when the repository state matches the lesson.

      -

      Jamie: Let's pause on Markdown Template Structure. What should a learner take away from it?

      -

      Alex: Here is the plain-English version of Markdown Template Structure. A Markdown template consists of two parts. Put another way, yAML Frontmatter (between --- delimiters).

      -

      Jamie: How do you keep commands from becoming magic words?

      -

      Alex: This is where 2. Markdown Body becomes real: the template content that pre-fills the issue editor. The workshop is closer to rehearsal than lecture. You hear the move, try the move, and then check what changed.

      -

      Alex: Treat examples as spoken recipes, not decorations. You may hear something like 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. Read the command, understand what it changes, then run it only when the repository state matches the lesson.

      -

      Jamie: Let's pause on Markdown template tips. What should a learner take away from it?

      -

      Alex: Start with Markdown template tips. There is something to understand, something to try, and something that proves the try worked.

      -

      Alex: The practical takeaway is this. 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.

      +

      Alex: Keep the teaching thread moving. Start with When to sync. There is something to understand, something to try, and something that proves the try worked.

      +

      Alex: The practical takeaway is this. 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).

      +

      Jamie: Let's pause on Method 3: GitHub Desktop. What should a learner take away from it?

      +

      Alex: Start with Method 3: GitHub Desktop. There is something to understand, something to try, and something that proves the try worked.

      +

      Alex: First, open GitHub Desktop. Then, select Repository → Pull to get your fork's latest. After that, select Branch → Merge into Current Branch. Finally, choose upstream/main. The rhythm is simple: orient, act, verify, then continue.

      +

      Jamie: Before we leave Method 3: GitHub Desktop, what is the practical point?

      +

      Alex: First, push the changes to your fork on GitHub. Think of it as a rail line: each stop confirms you are still on the right route before the next one.

      +

      Alex: Keep the teaching thread moving. Start with Learning Cards: Keeping Your Fork Up to Date. There is something to understand, something to try, and something that proves the try worked.

      +

      Alex: The practical takeaway is this. 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. 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.

      -

      Alex: Keep the teaching thread moving. The reason Complete Markdown Template Example matters is that here's a complete accessibility bug report template in Markdown format. That gives the learner a simple foothold: save this as.github/ISSUE TEMPLATE/accessibility-bug-simple.md.

      -

      Jamie: Let's pause on When to use this Markdown version instead of YAML. What should a learner take away from it?

      -

      Alex: Start with When to use this Markdown version instead of YAML. There is something to understand, something to try, and something that proves the try worked.

      -

      Alex: The practical takeaway is this. 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.

      -

      Alex: Keep the teaching thread moving. Start with Markdown template accessibility considerations. There is something to understand, something to try, and something that proves the try worked.

      -

      Alex: The practical takeaway is this. 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.

      +

      Jamie: Let's pause on Writing Good Commit Messages. What should a learner take away from it?

      +

      Alex: Here is the plain-English version of Writing Good Commit Messages. Every commit you make includes a message describing what changed. Put another way, good commit messages make project history understandable months or years later.

      +

      Alex: Keep the teaching thread moving. This is where The First Line (Required) becomes real: this is the commit summary that appears in logs and GitHub's commit list. That matters in practice: Think of it as an email subject line. The workshop is closer to rehearsal than lecture. You hear the move, try the move, and then check what changed.

      +

      Alex: The practical takeaway is this. fix: - bug fix. feat: - new feature. docs: - documentation only. style: - formatting, no code change.

      +

      Jamie: What is the safe way to learn from that example?

      +

      Alex: Keep the learner anchored in The Body (Optional). If the summary isn't enough, add a body explaining. This is the part to say slowly: Leave a blank line between the summary and the body.

      +

      Alex: The practical takeaway is this. Why you made the change (more important than what). What trade-offs you considered. How the change affects behavior.

      +

      Alex: Treat examples as spoken recipes, not decorations. You may hear something like 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. Read the command, understand what it changes, then run it only when the repository state matches the lesson.

      -

      Jamie: Let's pause on Creating Markdown Templates: The Manual Workflow (Browser). What should a learner take away from it?

      -

      Alex: This is where Creating Markdown Templates: The Manual Workflow (Browser) becomes real: screen reader users (NVDA / JAWS / VoiceOver). That matters in practice: Alternative: Navigate directly to.github/ISSUE TEMPLATE/ → activate the "+" button → "Create new file".

      -

      Alex: The practical takeaway is this. Template name: what appears in the chooser heading. About: the description in the chooser. Template content: the Markdown body.

      -

      Alex: First, navigate to your fork of accessibility-agents on GitHub. Then, click the Settings tab. After that, scroll to the "Features" section → click the checkmark next to "Issues" → click "Set up templates". Finally, or navigate directly to.github/ISSUE TEMPLATE/ in your fork → click the + button → "Create new file". It is a checklist, but a meaningful one: every item creates evidence that the next step is safe.

      -

      Jamie: Before we leave Creating Markdown Templates: The Manual Workflow (Browser), what is the practical point?

      -

      Alex: First, GitHub opens a template editor. Fill in the template name, about description, and body. Then, GitHub auto-populates the filename - you can change it. After that, click "Propose changes" → create a PR to add the template. Finally, go to the Settings tab (press T from the tabs landmark, then navigate to "Settings"). It is like walking a hallway with named doors: read the sign, enter the right room, then confirm where you landed.

      -

      Jamie: Let's pause on Creating Markdown Templates: The VS Code Workflow. What should a learner take away from it?

      -

      Alex: Start with Creating Markdown Templates: The VS Code Workflow. There is something to understand, something to try, and something that proves the try worked.

      -

      Alex: First, open your accessibility-agents fork in VS Code. Then, navigate in Explorer to.github/ISSUE TEMPLATE/. After that, create a new file: Ctrl+N → save as your-template-name.md in that folder. Finally, add frontmatter first (between --- delimiters), then the body. It is like walking a hallway with named doors: read the sign, enter the right room, then confirm where you landed.

      -

      Jamie: Before we leave Creating Markdown Templates: The VS Code Workflow, what is the practical point?

      -

      Alex: First, commit and push: open Source Control (Ctrl+Shift+G) → stage → commit → push. The rhythm is simple: orient, act, verify, then continue.

      -

      Jamie: Let's pause on File naming conventions. What should a learner take away from it?

      -

      Alex: Start with File naming conventions. There is something to understand, something to try, and something that proves the try worked.

      -

      Alex: The practical takeaway is this. Use lowercase with hyphens: accessibility-bug.md, feature-request.md. Be descriptive: security-vulnerability.md is better than security.md. Avoid spaces in filenames.

      +

      Alex: Keep the teaching thread moving. The reason The Footer (Optional) matters is that when the commit is merged, GitHub automatically closes linked issues.

      +

      Jamie: Let's pause on Atomic Commits. What should a learner take away from it?

      +

      Alex: Start with Atomic Commits: Each commit should represent one logical change. The next useful detail is this: Don't bundle unrelated fixes into a single commit.

      +

      Alex: Keep the teaching thread moving. Start with Common mistakes to avoid. There is something to understand, something to try, and something that proves the try worked.

      +

      Alex: The practical takeaway is this. "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.

      -

      Alex: Keep the teaching thread moving. Start with Learning Cards: Creating a New Template. There is something to understand, something to try, and something that proves the try worked.

      -

      Alex: The practical takeaway is this. 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. 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.

      -

      Jamie: Let's pause on 6. YAML Form-Based Templates. What should a learner take away from it?

      -

      Alex: Here is the plain-English version of 6. YAML Form-Based Templates. YAML templates create a proper form interface - labeled fields, dropdowns, checkboxes - rather than a pre-filled text editor. Put another way, this is the preferred format for modern GitHub projects, especially those focused on accessibility.

      -

      Alex: Keep the teaching thread moving. This is where Why YAML Forms Are Better for Accessibility becomes real: explicit labels: Each field has a label: that screen readers announce. That matters in practice: In Markdown templates, users must infer structure from headings and placeholder text.

      +

      Jamie: How do you keep commands from becoming magic words?

      +

      Alex: This is where Good commit messages in practice becomes real: when you make a habit of writing good commit messages, you build trust. That matters in practice: Maintainers see that you care about the project's long-term health, not just your immediate contribution.

      +

      Alex: Treat examples as spoken recipes, not decorations. You may hear something like 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. Read the command, understand what it changes, then run it only when the repository state matches the lesson.

      +

      Alex: Keep the teaching thread moving. Start with Learning Cards: Writing Good Commit Messages. There is something to understand, something to try, and something that proves the try worked.

      +

      Alex: The practical takeaway is this. 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. 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.

      +

      Jamie: Let's pause on The Nature of Open Source Communication. What should a learner take away from it?

      +

      Alex: The reason The Nature of Open Source Communication matters is that open source collaboration happens primarily in writing, asynchronously, in public. That gives the learner a simple foothold: understanding these three characteristics shapes everything about how we communicate.

      -

      Jamie: Let's pause on YAML Template Structure. What should a learner take away from it?

      -

      Alex: Keep the learner anchored in YAML Template Structure. A YAML form template consists of several parts.

      -

      Alex: Keep the teaching thread moving. Start with Top-level keys. There is something to understand, something to try, and something that proves the try worked.

      -

      Alex: The practical takeaway is this. 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).

      -

      Jamie: Let's pause on YAML Field Types Reference. What should a learner take away from it?

      -

      Alex: Start with YAML Field Types Reference: GitHub supports several field types in YAML form templates. The next useful detail is this: Each has specific attributes and uses.

      +

      Alex: Keep the teaching thread moving. Start with In writing. There is something to understand, something to try, and something that proves the try worked.

      +

      Alex: The practical takeaway is this. 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.".

      +

      Jamie: Let's pause on Asynchronously. What should a learner take away from it?

      +

      Alex: Start with Asynchronously. There is something to understand, something to try, and something that proves the try worked.

      +

      Alex: The practical takeaway is this. 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.

      +

      Alex: Keep the teaching thread moving. Start with In public. There is something to understand, something to try, and something that proves the try worked.

      +

      Alex: The practical takeaway is this. 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.

      -

      Alex: Keep the teaching thread moving. Here is the plain-English version of 1. markdown - Instructional Text. Displays formatted Markdown content. Put another way, use for instructions, warnings, or explanations.

      -

      Alex: The practical takeaway is this. value (required): Markdown content to display. Use for multi-line text.

      -

      Jamie: Let's pause on 2. input - Single-line Text Field. What should a learner take away from it?

      -

      Alex: This is where 2. input - Single-line Text Field becomes real: best for short answers like version numbers, URLs, or names. That matters in practice: Screen reader announcement: "Version Number, required, edit text, Which version of the software are you using?".

      -

      Alex: The practical takeaway is this. label (required): Field label, announced by screen readers. description (optional): Help text below the label. placeholder (optional): Placeholder text inside the field. required (boolean): Whether the field must be filled.

      -

      Alex: Keep the teaching thread moving. Keep the learner anchored in 3. textarea - Multi-line Text Area. Best for descriptions, reproduction steps, code snippets, or any long-form content. This is the part to say slowly: Accessibility tip: Use placeholder for examples, value for pre-filled template text that contributors should edit. A good GitHub workflow is like a well-run meeting: everyone knows the topic, the next action, and who has the floor.

      -

      Alex: The practical takeaway is this. label (required): Field label. description (optional): Help text. placeholder (optional): Placeholder text (multi-line with ). value (optional): Pre-filled content (multi-line with ).

      +

      Jamie: What do you want them to do when the plan breaks?

      +

      Alex: Keep the learner anchored in The Anatomy of Helpful Feedback. Whether commenting on an issue, reviewing a PR, or responding to a question, effective feedback has a structure.

      +

      Alex: Keep the teaching thread moving. The reason 1. Acknowledge what's working matters is that before identifying problems, name what is good. That gives the learner a simple foothold: this is not flattery - it is accuracy. The interface gets friendlier when it stops being a wall of controls and starts being a set of named places.

      +

      Jamie: Let's pause on 2. Identify the specific concern. What should a learner take away from it?

      +

      Alex: Start with 2. Identify the specific concern: "This code is inaccessible." "This button has no accessible name - aria-label or visible text is needed for screen readers to announce its purpose.".

      -

      Jamie: Let's pause on 4. dropdown - Select Menu. What should a learner take away from it?

      -

      Alex: The reason 4. dropdown - Select Menu matters is that a dropdown menu with predefined options. That gives the learner a simple foothold: best for bounded answer spaces like OS, browser, or severity.

      -

      Alex: The practical takeaway is this. label (required):Field label. description (optional): Help text. options (required): Array of choices (strings). multiple (boolean, default false): Whether user can select multiple options.

      -

      Alex: First, field is announced as "Browser, required, combo box". Then, press Down Arrow or Alt+Down to expand the dropdown. After that, up/Down Arrow to navigate options. Finally, screen reader announces each option. The rhythm is simple: orient, act, verify, then continue.

      -

      Jamie: Before we leave 4. dropdown - Select Menu, what is the practical point?

      -

      Alex: First, enter or Space to select. Think of it as a rail line: each stop confirms you are still on the right route before the next one.

      -

      Jamie: Let's pause on 5. checkboxes - Checkbox Group. What should a learner take away from it?

      -

      Alex: Start with 5. checkboxes - Checkbox Group: Contributors can select multiple options or use as a verification checklist. The next useful detail is this: No top-level validation - validation is per-checkbox in options.

      -

      Alex: The practical takeaway is this. label (required): Group label. description (optional): Group description. options (required): Array of checkbox objects. label (required): Checkbox label (what the user sees).

      -

      Alex: First, group label announced: "Before Submitting, Please verify these items". Then, each checkbox announced as "I searched for existing issues, checkbox, not checked, required". After that, screen reader users can check each box with Space. Think of it as a rail line: each stop confirms you are still on the right route before the next one.

      -

      Jamie: Let's pause on Choosing the right field type. What should a learner take away from it?

      -

      Alex: Start with Choosing the right field type. There is something to understand, something to try, and something that proves the try worked.

      -

      Alex: The practical takeaway is this. 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.

      +

      Alex: Keep the teaching thread moving. Here is the plain-English version of 3. Explain why it matters. Context turns a complaint into a lesson. Put another way, it also respects the contributor - they deserve to understand, not just comply.

      +

      Jamie: Let's pause on 4. Suggest a path forward (when you can). What should a learner take away from it?

      +

      Alex: This is where 4. Suggest a path forward (when you can) becomes real: if you have an idea for a solution, offer it as a suggestion, not a mandate. That matters in practice: "Something like aria-label='Close navigation menu' would work well here.

      +

      Alex: Keep the teaching thread moving. Keep the learner anchored in 5. Signal the weight of the concern. Help contributors understand what is a blocker versus a preference. A good GitHub workflow is like a well-run meeting: everyone knows the topic, the next action, and who has the floor.

      +

      Alex: The practical takeaway is this. 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.

      -

      Alex: Keep the teaching thread moving. Start with Learning Cards: YAML Form Templates. There is something to understand, something to try, and something that proves the try worked.

      -

      Alex: The practical takeaway is this. 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. 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.

      -

      Jamie: Let's pause on 7. Building an Accessibility Bug Report Template. What should a learner take away from it?

      -

      Alex: Keep the learner anchored in 7. Building an Accessibility Bug Report Template. the learner will create a YAML form template specifically for accessibility bug reports in accessibility-agents.

      -

      Alex: Keep the teaching thread moving. The reason Full Template matters is that save this as.github/ISSUE TEMPLATE/accessibility-bug.yml in your fork.

      +

      Jamie: Let's pause on Prefer "we" or describe the code, not the person. What should a learner take away from it?

      +

      Alex: The reason Prefer "we" or describe the code, not the person matters is that "You made an error here." "There's an error here." or "This line does X but we need Y.".

      +

      Alex: Keep the teaching thread moving. Start with 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?".

      +

      Jamie: Let's pause on Acknowledge cultural and language diversity. What should a learner take away from it?

      +

      Alex: Here is the plain-English version of Acknowledge cultural and language diversity. When reading someone's comment: Assume good intent unless there is clear evidence otherwise. Put another way, when writing: Choose plain words over clever ones.

      +

      Alex: The practical takeaway is this. 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.

      -

      Jamie: Let's pause on What Makes This Template Accessible. What should a learner take away from it?

      -

      Alex: Start with What Makes This Template Accessible: This template is itself an accessibility contribution.

      -

      Alex: The practical takeaway is this. 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.

      -

      Alex: Keep the teaching thread moving. Here is the plain-English version of A Second Template: Feature Request Form. The bug report template above is specific to accessibility issues. Put another way, once you understand the pattern, you can create templates for any contribution type. It is like learning a transit route. The names of the stops matter because they tell you whether you are still going the right direction.

      -

      Jamie: Let's pause on Designing Templates for Your Own Projects. What should a learner take away from it?

      -

      Alex: This is where Designing Templates for Your Own Projects becomes real: when designing templates for a project you maintain, use these principles. That matters in practice: Ask for the minimum that makes the report actionable.

      +

      Alex: Keep the teaching thread moving. This is where Avoid urgency markers unless genuinely urgent becomes real: "I need this fixed ASAP" "This is blocking our release scheduled for next Friday - is there capacity to look at it this week?". The workshop is closer to rehearsal than lecture. You hear the move, try the move, and then check what changed.

      +

      Jamie: Let's pause on Keep comments focused. What should a learner take away from it?

      +

      Alex: Keep the learner anchored in Keep comments focused. Each comment should address one concern. This is the part to say slowly: If you have three issues, leave three comments - unless they are closely related.

      +

      Alex: Keep the teaching thread moving. The reason Don't leave comments unresolved matters is that if you asked a question and got an answer, respond. That gives the learner a simple foothold: "Thanks, that makes sense" or resolving the conversation thread signals that the thread is complete.

      -

      Alex: Keep the teaching thread moving. Start with Learning Cards: Building an Accessibility Bug Report Template. There is something to understand, something to try, and something that proves the try worked.

      -

      Alex: The practical takeaway is this. 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. 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.

      -

      Jamie: Let's pause on 8. Pull Request Templates. What should a learner take away from it?

      -

      Alex: The reason 8. Pull Request Templates matters is that a pull request template appears as the default body of every new PR in your repository. That gives the learner a simple foothold: file location.github/pull request template.md (singular - only one PR template per repo).

      -

      Jamie: What is the safe way to learn from that example?

      -

      Alex: Start with Reading the Accessibility Agents PR Template: Open.github/pull request template.md in VS Code. The next useful detail is this: the learner will see the standard sections the project expects. Think of it like entering a new building: first you find the lobby, then the room, then the door you actually need.

      -

      Alex: Treat examples as spoken recipes, not decorations. You may hear something like 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. Read the command, understand what it changes, then run it only when the repository state matches the lesson.

      +

      Jamie: Let's pause on Resolving conversations. What should a learner take away from it?

      +

      Alex: Start with Resolving conversations: On a PR, conversations (inline comment threads) can be "resolved" once addressed. The next useful detail is this: The author of the change and the reviewer can both resolve them.

      +

      Alex: Keep the teaching thread moving. Here is the plain-English version of 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. Put another way, a reaction on an existing comment is enough. It is like learning a transit route. The names of the stops matter because they tell you whether you are still going the right direction.

      +

      Jamie: Let's pause on Reactions. What should a learner take away from it?

      +

      Alex: This is where Reactions becomes real: GitHub reactions () are an efficient way to express agreement, appreciation, or concern without adding noise to a thread.

      -

      Jamie: Let's pause on Learning Cards: Pull Request Templates. What should a learner take away from it?

      -

      Alex: Start with Learning Cards: Pull Request Templates. There is something to understand, something to try, and something that proves the try worked.

      -

      Alex: The practical takeaway is this. 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. 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.

      -

      Alex: Keep the teaching thread moving. Start with Learning Cards: Hands-On Activity. There is something to understand, something to try, and something that proves the try worked.

      -

      Alex: The practical takeaway is this. 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. 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.

      -

      Jamie: How do these exercises create confidence instead of pressure?

      -

      Alex: Keep the learner anchored in Exercise A - Use an Existing Template. Your Mission: File your first issue using a structured template. This is the part to say slowly: You'll experience the template as an end-user, which teaches you what good template design feels like.

      +

      Alex: Keep the teaching thread moving. Keep the learner anchored in 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 the part to say slowly: This is a significant accessibility win for anyone who types the same comments repeatedly during triage, reviews, or issue management.

      +

      Jamie: Let's pause on Common uses. What should a learner take away from it?

      +

      Alex: Start with Common uses. There is something to understand, something to try, and something that proves the try worked.

      +

      Alex: The practical takeaway is this. "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.

      +

      Jamie: Let's pause on Creating a Saved Reply. What should a learner take away from it?

      +

      Alex: Start with Creating a Saved Reply. There is something to understand, something to try, and something that proves the try worked.

      +

      Alex: First, navigate to github.com/settings/replies. Then, activate "Add a saved reply". After that, give it a title (e.g., "Good first issue claim") - this is what you search. Finally, type the full reply text in the body (Markdown is supported). Think of it as a rail line: each stop confirms you are still on the right route before the next one.

      -

      Jamie: Let's pause on Step 1: Navigate to the Accessibility Agents Issues Section. What should a learner take away from it?

      -

      Alex: Start with Step 1: Navigate to the Accessibility Agents Issues Section. There is something to understand, something to try, and something that proves the try worked.

      -

      Alex: The practical takeaway is this. A tab labeled "Issues" (currently active). A list of open/closed issues below. A large green button labeled "New issue" on the right side. Go directly to: https://github.com/community-access/accessibility-agents/issues/new. This opens the issue template chooser.

      -

      Alex: First, open GitHub in your browser. Then, navigate to the community-access/accessibility-agents repository (or your fork). After that, click the Issues tab (top navigation, between Pull Requests and Discussions). Finally, you should see a list of existing issues. The rhythm is simple: orient, act, verify, then continue.

      -

      Jamie: Before we leave Step 1: Navigate to the Accessibility Agents Issues Section, what is the practical point?

      -

      Alex: First, click the "New issue" button. Think of it as a rail line: each stop confirms you are still on the right route before the next one.

      -

      Jamie: Let's pause on Step 2: View the Template Chooser with Your Screen Reader. What should a learner take away from it?

      -

      Alex: Start with Step 2: View the Template Chooser with Your Screen Reader. There is something to understand, something to try, and something that proves the try worked.

      -

      Alex: The practical takeaway is this. 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. Template 1: [name] - [description]. Template 2: [name] - [description]. And so on. Is each template name announced clearly?

      -

      Alex: First, you should now see a Template Chooser page. Then, the page displays available templates as buttons or links. After that, with screen reader: Navigate through the templates. Finally, count the templates and read their descriptions aloud (or write them down). Think of it as a rail line: each stop confirms you are still on the right route before the next one.

      +

      Jamie: Let's pause on Using a Saved Reply in a comment. What should a learner take away from it?

      +

      Alex: Start with Using a Saved Reply in a comment. There is something to understand, something to try, and something that proves the try worked.

      +

      Alex: First, navigate to any comment text area. Then, activate the Saved Replies button (the speech bubble icon in the comment toolbar, or press Ctrl+. if enabled). After that, a dropdown appears showing your saved replies - type to filter by title. Finally, select the reply - it inserts into the text area. Treat it like a recipe: do not add the next ingredient until the previous one is actually in the bowl.

      +

      Jamie: Before we leave Using a Saved Reply in a comment, what is the practical point?

      +

      Alex: First, edit as needed before submitting. It is a checklist, but a meaningful one: every item creates evidence that the next step is safe.

      +

      Alex: Keep the teaching thread moving. This is where Screen reader path becomes real: limit: GitHub allows up to 100 saved replies per account.

      Alex: A solid navigation habit is to prove where you are before activating controls. Headings, landmarks, and the address bar are not trivia; they are your map.

      -

      Jamie: Let's pause on Step 3: Select a Template. What should a learner take away from it?

      -

      Alex: Start with Step 3: Select a Template. There is something to understand, something to try, and something that proves the try worked.

      -

      Alex: The practical takeaway is this. The issue form opens. You see a form with labeled fields. Each field is pre-filled with helpful prompts or instructions. Choose "Blank Issue" or the most general template. You'll learn what an unstructured issue looks like (which teaches the value of templates).

      -

      Alex: First, 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). Then, click it (or press Enter if focused with keyboard). Treat it like a recipe: do not add the next ingredient until the previous one is actually in the bowl.

      +

      Jamie: Let's pause on Learning Cards: Commenting Etiquette. What should a learner take away from it?

      +

      Alex: Start with Learning Cards: Commenting Etiquette. There is something to understand, something to try, and something that proves the try worked.

      +

      Alex: The practical takeaway is this. 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. 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.

      -

      Jamie: Let's pause on Step 4: Navigate the Form Fields. What should a learner take away from it?

      -

      Alex: Start with Step 4: Navigate the Form Fields. There is something to understand, something to try, and something that proves the try worked.

      -

      Alex: The practical takeaway is this. 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. 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"). Field: [name] - Required? [Yes/No].

      -

      Alex: First, the issue form is now open. Then, navigate through all visible fields using your screen reader or by tabbing. After that, for each field, note. Finally, write down at least 3 fields and whether each is required. It is a checklist, but a meaningful one: every item creates evidence that the next step is safe.

      -

      Jamie: Let's pause on Step 5: Fill In the Form. What should a learner take away from it?

      -

      Alex: Start with Step 5: Fill In the Form. There is something to understand, something to try, and something that proves the try worked.

      -

      Alex: The practical takeaway is this. Example: If the template asks "Screen Reader," select "NVDA". If it asks "Steps to reproduce," write 2-3 specific steps. 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).

      -

      Alex: First, fill in at least 3 fields with realistic content based on an issue you identified on Day 1. Then, for required fields marked with: Fill them in completely. After that, for optional fields: Choose at least one and fill it in (so you test optional fields). Finally, don't worry about filling in every field - the point is to test the form. It is like walking a hallway with named doors: read the sign, enter the right room, then confirm where you landed.

      -

      Jamie: Let's pause on Step 6: Preview the Issue Before Submitting. What should a learner take away from it?

      -

      Alex: Start with Step 6: Preview the Issue Before Submitting. There is something to understand, something to try, and something that proves the try worked.

      -

      Alex: The practical takeaway is this. 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. 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?

      -

      Alex: First, look for a Preview tab or button (usually near the top of the form, next to "Write" or "Markdown"). Then, click it (or press the hotkey shown). After that, a preview pane appears showing how the issue will look when published. The rhythm is simple: orient, act, verify, then continue.

      +

      Alex: Keep the teaching thread moving. The reason Review the code, not the person matters is that "You clearly don't understand accessibility." "This implementation doesn't account for keyboard navigation - here's how to add it.". The interface gets friendlier when it stops being a wall of controls and starts being a set of named places.

      +

      Jamie: Let's pause on Don't gatekeep knowledge. What should a learner take away from it?

      +

      Alex: Start with Don't gatekeep knowledge: If a contributor makes a mistake because they didn't know something, explain the concept.

      +

      Alex: Keep the teaching thread moving. Here is the plain-English version of Ask questions instead of making demands. "Change this to use aria-label." "What do you think about using aria-label here instead? Put another way, screen readers would then announce the button's purpose directly.".

      -

      Jamie: Let's pause on Step 7: Submit the Issue. What should a learner take away from it?

      -

      Alex: Start with Step 7: Submit the Issue. There is something to understand, something to try, and something that proves the try worked.

      -

      Alex: The practical takeaway is this. 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.

      -

      Alex: First, once you're satisfied with the preview, go back to the "Write" tab. Then, locate the green "New issue" button (usually at the bottom of the form). After that, with keyboard: Press Tab until the button is focused, then Enter. Finally, with mouse: Click the button. Think of it as a rail line: each stop confirms you are still on the right route before the next one.

      -

      Jamie: Before we leave Step 7: Submit the Issue, what is the practical point?

      -

      Alex: First, the issue is submitted and you see the new issue page with your content. Treat it like a recipe: do not add the next ingredient until the previous one is actually in the bowl.

      -

      Jamie: Let's pause on Step 8: Checkpoint - Reflect on the Template. What should a learner take away from it?

      -

      Alex: Here is the plain-English version of Step 8: Checkpoint - Reflect on the Template. You'll use them in Exercise D when you design your own template.

      -

      Alex: First, template Clarity: Did the template guide you toward providing useful information, or did fields feel confusing or unnecessary? Then, screen Reader Accessibility: Were all field labels announced clearly? Did you encounter any accessibility barriers? After that, required vs Optional: Was it obvious which fields were required? If you skipped an optional field, would you have known it was optional? Finally, context Helpfulness: Did the placeholder text or help text under each field make you understand what information to provide? Treat it like a recipe: do not add the next ingredient until the previous one is actually in the bowl.

      -

      Alex: Keep the teaching thread moving. This is where Exercise B - Add the Accessibility Bug Report Template to Your Fork becomes real: your Mission: Create your own instance of the accessibility bug report template in your personal fork. That matters in practice: This teaches you the file structure and gives you hands-on experience with YAML syntax. The workshop is closer to rehearsal than lecture. You hear the move, try the move, and then check what changed.

      -

      Alex: The practical takeaway is this. You have already read Section 7 thoroughly (Building an Accessibility Bug Report Template). You have a fork of accessibility-agents (created on Day 1). VS Code is installed on your machine. Git is installed and configure with your GitHub credentials.

      +

      Jamie: Let's pause on Distinguish opinion from requirement. What should a learner take away from it?

      +

      Alex: This is where Distinguish opinion from requirement becomes real: if something is your stylistic preference but NOT a bug or correctness issue, say so. That matters in practice: "The current implementation is correct.

      +

      Alex: Keep the teaching thread moving. Keep the learner anchored in 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! A good GitHub workflow is like a well-run meeting: everyone knows the topic, the next action, and who has the floor.

      +

      Jamie: Let's pause on Say thank you. What should a learner take away from it?

      +

      Alex: The reason Say thank you matters is that when someone takes time to review your work, acknowledge it - even if you disagree with some feedback. That gives the learner a simple foothold: "Thanks so much for the thorough review!

      -

      Jamie: Let's pause on Step 1: Clone Your Fork to Your Machine. What should a learner take away from it?

      -

      Alex: Keep the learner anchored in Step 1: Clone Your Fork to Your Machine. (Or wherever you keep code projects). This is the part to say slowly: Replace [YOUR-USERNAME] with your actual GitHub username.

      -

      Alex: The practical takeaway is this. 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. "Repository not found" → Make sure your GitHub username is correct.

      -

      Alex: First, open a terminal (PowerShell on Windows, Terminal on macOS/Linux). Then, navigate to a folder where you want to store the project. After that, clone your fork. Finally, wait for the clone to complete (should take 10-30 seconds). It is like walking a hallway with named doors: read the sign, enter the right room, then confirm where you landed.

      -

      Jamie: Before we leave Step 1: Clone Your Fork to Your Machine, what is the practical point?

      -

      Alex: First, navigate into the folder. The rhythm is simple: orient, act, verify, then continue.

      -

      Alex: Treat examples as spoken recipes, not decorations. You may hear something like cd /projects. git clone https://github.com/[YOUR-USERNAME]/accessibility-agents.git. Read the command, understand what it changes, then run it only when the repository state matches the lesson.

      -

      Jamie: Let's pause on Step 2: Open Your Fork in VS Code. What should a learner take away from it?

      -

      Alex: Start with Step 2: Open Your Fork in VS Code. There is something to understand, something to try, and something that proves the try worked.

      -

      Alex: The practical takeaway is this. VS Code opens a new window. The left sidebar shows the folder structure of accessibility-agents. At the top, you see the folder name: accessibility-agents. Use VS Code's File menu: File → Open Folder → navigate to your accessibility-agents folder.

      -

      Alex: First, from the terminal, while in your accessibility-agents folder, type. Then, press Enter. After that, VS Code opens with your fork loaded. The rhythm is simple: orient, act, verify, then continue.

      -

      Jamie: Let's pause on Step 3: Navigate to the Templates Folder. What should a learner take away from it?

      -

      Alex: Start with Step 3: Navigate to the Templates Folder. There is something to understand, something to try, and something that proves the try worked.

      -

      Alex: The practical takeaway is this. 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. Right-click on the.github folder and select New Folder. Name it ISSUE TEMPLATE.

      -

      Alex: First, in VS Code's file tree (left sidebar), expand the.github folder. Then, inside, find and expand the ISSUE TEMPLATE folder. After that, you should see existing template files (like bug-report-template.yml or similar). Think of it as a rail line: each stop confirms you are still on the right route before the next one.

      +

      Alex: Keep the teaching thread moving. Start with Don't take feedback personally: Code review is about the code, not your worth as a person or developer. The next useful detail is this: Even the most senior contributors receive change requests.

      +

      Jamie: Let's pause on Explain your choices. What should a learner take away from it?

      +

      Alex: Here is the plain-English version of Explain your choices. If you are keeping your implementation despite feedback, explain why. Put another way, "I considered aria-label here, but I went with a visually-hidden instead because it allows translators to localize the text more easily.

      +

      Alex: Keep the teaching thread moving. This is where Surface blockers early becomes real: don't wait until you have finished a 500-line PR to mention that you weren't sure about the approach. The workshop is closer to rehearsal than lecture. You hear the move, try the move, and then check what changed.

      -

      Jamie: Let's pause on Step 4: Create a New Template File. What should a learner take away from it?

      -

      Alex: Start with Step 4: Create a New Template File. There is something to understand, something to try, and something that proves the try worked.

      -

      Alex: The practical takeaway is this. A new, empty file opens in the editor. The cursor is ready for you to start typing.

      -

      Alex: First, right-click on the ISSUE TEMPLATE folder. Then, select New File. After that, name it: accessibility-bug.yml (exactly this name). Finally, press Enter. Treat it like a recipe: do not add the next ingredient until the previous one is actually in the bowl.

      -

      Jamie: Let's pause on Step 5: Copy the Accessibility Template YAML. What should a learner take away from it?

      -

      Alex: Start with Step 5: Copy the Accessibility Template YAML. There is something to understand, something to try, and something that proves the try worked.

      -

      Alex: The practical takeaway is this. 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).

      -

      Alex: First, go to Chapter 17, Section 7 in this curriculum. Then, find the complete YAML template code block (starting with name: and ending with the last field). After that, select all the YAML code (use Ctrl+A on the webpage or manually select). Finally, copy it (Ctrl+C). It is a checklist, but a meaningful one: every item creates evidence that the next step is safe.

      -

      Jamie: Before we leave Step 5: Copy the Accessibility Template YAML, what is the practical point?

      -

      Alex: First, go back to VS Code. Then, paste it into your new accessibility-bug.yml file (Ctrl+V). It is like walking a hallway with named doors: read the sign, enter the right room, then confirm where you landed.

      -

      Jamie: Let's pause on Step 6: Verify the YAML Syntax. What should a learner take away from it?

      -

      Alex: Start with Step 6: Verify the YAML Syntax. There is something to understand, something to try, and something that proves the try worked.

      -

      Alex: The practical takeaway is this. 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. Your YAML syntax is correct!

      -

      Alex: First, save the file (Ctrl+S). Then, look at the bottom right of VS Code - you may see some notifications. After that, check if VS Code shows any red squiggly lines (indicating syntax errors). Finally, hover over the error to see what VS Code suggests. It is like walking a hallway with named doors: read the sign, enter the right room, then confirm where you landed.

      -

      Jamie: Before we leave Step 6: Verify the YAML Syntax, what is the practical point?

      -

      Alex: First, compare your file with Section 7's template - look for extra/missing spaces or colons. Then, make corrections and save again. The rhythm is simple: orient, act, verify, then continue.

      +

      Jamie: Let's pause on Inclusive Commenting for Accessibility Issues. What should a learner take away from it?

      +

      Alex: Keep the learner anchored in Inclusive Commenting for Accessibility Issues. When filing or discussing accessibility bugs, additional context helps.

      +

      Alex: The practical takeaway is this. 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.

      +

      Alex: A solid issue habit is to read the title, the body, and the timeline before acting. You are listening for the requested action, the missing evidence, and the person who needs a response.

      +

      Jamie: Let's pause on The "Good First Issue" Social Contract. What should a learner take away from it?

      +

      Alex: The reason The "Good First Issue" Social Contract matters is that when a maintainer labels an issue good first issue, they are. That gives the learner a simple foothold: when you take a good first issue, your responsibilities.

      +

      Alex: The practical takeaway is this. Investing time - good first issues require extra documentation and mentorship. Signaling welcome - they want to support a new contributor.

      +

      Alex: First, comment to claim it - "Hi, I'd like to work on this. Can I be assigned?". Then, wait for assignment - do not start until assigned; two people working in parallel wastes everyone's time. After that, 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?". Finally, 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?". The rhythm is simple: orient, act, verify, then continue.

      +

      Jamie: Before we leave The "Good First Issue" Social Contract, what is the practical point?

      +

      Alex: First, don't disappear - if you claim an issue, see it through or explicitly hand it back. Think of it as a rail line: each stop confirms you are still on the right route before the next one.

      +

      Jamie: Let's pause on When you receive harsh feedback. What should a learner take away from it?

      +

      Alex: Start with When you receive harsh feedback. There is something to understand, something to try, and something that proves the try worked.

      +

      Alex: First, take a breath before responding - there is no urgency; the thread will wait. Then, look for the valid concern underneath the harsh words. After that, respond to the concern, not the tone. Finally, if the behavior crosses into harassment, report it via the "." button on the comment → "Report". Think of it as a rail line: each stop confirms you are still on the right route before the next one.

      -

      Jamie: Let's pause on Step 7: Create a Branch and Commit. What should a learner take away from it?

      -

      Alex: Start with Step 7: Create a Branch and Commit. There is something to understand, something to try, and something that proves the try worked.

      -

      Alex: The practical takeaway is this. Git uploads your branch to GitHub. You're ready to test the template in the next step. "Not a git repository" → Make sure you opened the accessibility-agents folder in VS Code. "Permission denied" → Make sure you authenticated with GitHub (see Prerequisites).

      -

      Alex: First, open the terminal in VS Code: Terminal → New Terminal (or Ctrl+ ` on Windows). Then, you should be in the accessibility-agents folder already. After that, create a new branch for this change. Finally, add the file to git. The rhythm is simple: orient, act, verify, then continue.

      -

      Jamie: Before we leave Step 7: Create a Branch and Commit, what is the practical point?

      -

      Alex: First, commit with a message. Then, push to your fork. Think of it as a rail line: each stop confirms you are still on the right route before the next one.

      -

      Alex: Treat examples as spoken recipes, not decorations. You may hear something like git checkout -b feat/add-accessibility-template. git add.github/ISSUE TEMPLATE/accessibility-bug.yml. Read the command, understand what it changes, then run it only when the repository state matches the lesson.

      -

      Alex: A solid Git habit is to know which branch you are on, what changed, and what confirmation you expect before you run the next command.

      -

      Jamie: Let's pause on Step 8: Test the Template in GitHub Web. What should a learner take away from it?

      -

      Alex: Start with Step 8: Test the Template in GitHub Web. There is something to understand, something to try, and something that proves the try worked.

      -

      Alex: The practical takeaway is this. 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. Go back to the main repository page (code tab). Refresh the browser (Ctrl+Shift+R for hard refresh).

      -

      Alex: First, open GitHub in your browser. Then, go to your fork: https://github.com/[YOUR-USERNAME]/accessibility-agents. After that, you should see a notification or purple bar saying "Compare & pull request" (your new branch). Finally, but instead of opening a PR, click the Issues tab. Think of it as a rail line: each stop confirms you are still on the right route before the next one.

      -

      Jamie: Before we leave Step 8: Test the Template in GitHub Web, what is the practical point?

      -

      Alex: First, click New issue. Then, you should now see your new template in the chooser: "Accessibility Bug Report". After that, click it to open the form. Treat it like a recipe: do not add the next ingredient until the previous one is actually in the bowl.

      -

      Jamie: Let's pause on Step 9: Test with Your Screen Reader. What should a learner take away from it?

      -

      Alex: Here is the plain-English version of Step 9: Test with Your Screen Reader. Record your findings - you'll use this for Exercise D.

      -

      Alex: The practical takeaway is this. Is the label announced clearly? Is it obvious whether the field is required? Do dropdowns announce their options correctly? Are descriptions/help text announced? Did you encounter any accessibility barriers? Would a screen reader user find this template easy to use?

      -

      Alex: First, with screen reader activated: Navigate through the template form using your reader's commands. Then, for each field, note. Treat it like a recipe: do not add the next ingredient until the previous one is actually in the bowl.

      +

      Jamie: Let's pause on When you disagree with a decision. What should a learner take away from it?

      +

      Alex: Start with When you disagree with a decision. There is something to understand, something to try, and something that proves the try worked.

      +

      Alex: First, make your case once, clearly and with evidence. Then, accept that the maintainer has the final say in their project. After that, if you strongly disagree, you can fork the project and take it in a different direction - this is legitimate in open source. Treat it like a recipe: do not add the next ingredient until the previous one is actually in the bowl.

      +

      Jamie: Let's pause on When someone is rude to you. What should a learner take away from it?

      +

      Alex: Start with When someone is rude to you. There is something to understand, something to try, and something that proves the try worked.

      +

      Alex: First, you do not have to engage. Then, 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.". After that, report via GitHub's reporting tools if the behavior is abusive. It is a checklist, but a meaningful one: every item creates evidence that the next step is safe.

      +

      Jamie: Let's pause on When you accidentally caused offense. What should a learner take away from it?

      +

      Alex: Start with When you accidentally caused offense. There is something to understand, something to try, and something that proves the try worked.

      +

      Alex: First, acknowledge it directly: "I can see how that came across as dismissive - that wasn't my intention.". Then, do not over-explain or defend excessively. After that, adjust going forward. It is like walking a hallway with named doors: read the sign, enter the right room, then confirm where you landed.

      +
      +

      Jamie: Let's pause on Writing Your First README. What should a learner take away from it?

      +

      Alex: The reason Writing Your First README matters is that see also: Appendix W: GitHub Pages for publishing your README as a website. That gives the learner a simple foothold: a README is the front door of your project.

      +

      Alex: Keep the teaching thread moving. Start with What belongs in a README: Every README should answer these questions, roughly in this order. The next useful detail is this: 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. Think of it like entering a new building: first you find the lobby, then the room, then the door you actually need.

      +

      Jamie: Let's pause on Accessibility in READMEs. What should a learner take away from it?

      +

      Alex: Here is the plain-English version of Accessibility in READMEs. Your README is a web page -- GitHub renders it as HTML. Put another way, that means the same accessibility rules apply.

      +

      Alex: The practical takeaway is this. Alt text for images and badges. A badge that says is invisible to screen readers. Write 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 -- not Click here.

      +
      +

      Alex: Keep the teaching thread moving. This is where Good README vs. bad README becomes real: bad: A single paragraph that says "This is my project. That matters in practice: Run it with npm start." No headings, no license, no description of what the project does.

      +

      Jamie: Let's pause on Learning Cards: Writing Your First README. What should a learner take away from it?

      +

      Alex: Start with Learning Cards: Writing Your First README. There is something to understand, something to try, and something that proves the try worked.

      +

      Alex: The practical takeaway is this. 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: rather than an empty that reads as "image" with no context. Use real Markdown link text (installation guide) instead of bare URLs, so your screen reader announces the destination rather than spelling out a long URL. 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.

      +

      Alex: Keep the teaching thread moving. The reason Community Health Files matters is that community health files tell contributors how your project operates before they write a single line of code. That gives the learner a simple foothold: 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. The interface gets friendlier when it stops being a wall of controls and starts being a set of named places.

      +
      +

      Jamie: Let's pause on CONTRIBUTING.md. What should a learner take away from it?

      +

      Alex: Start with CONTRIBUTING.md: This file answers the question every newcomer asks: "How do I help?" A good CONTRIBUTING.md covers. The next useful detail is this: A sentence like "We are glad you are here" costs nothing and signals that newcomers are expected, not tolerated.

      +

      Alex: The practical takeaway is this. 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.

      +

      Alex: Keep the teaching thread moving. Here is the plain-English version of CODE OF CONDUCT.md. A code of conduct sets the social contract for your project. Put another way, without one, "acceptable behavior" is whatever each participant assumes it is -- and those assumptions vary widely.

      +

      Alex: The practical takeaway is this. 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.

      +

      Jamie: Let's pause on SECURITY.md. What should a learner take away from it?

      +

      Alex: This is where SECURITY.md becomes real: see also: Appendix F: Git Security and Appendix P: Security Features for security best practices. That matters in practice: If someone discovers a vulnerability in your project, you do not want them to file a public issue.

      +

      Alex: The practical takeaway is this. 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.

      +
      +

      Alex: Keep the teaching thread moving. Keep the learner anchored in 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. This is the part to say slowly: Adding a LICENSE file is a one-time step that makes your project genuinely open source. A good GitHub workflow is like a well-run meeting: everyone knows the topic, the next action, and who has the floor.

      +

      Jamie: Let's pause on Finding these files on GitHub. What should a learner take away from it?

      +

      Alex: The reason Finding these files on GitHub matters is that navigate to any repository and click Insights then Community Standards. That gives the learner a simple foothold: GitHub shows a checklist of which community health files are present and links to add any that are missing.

      +

      Alex: Keep the teaching thread moving. Start with Learning Cards: Community Health Files. There is something to understand, something to try, and something that proves the try worked.

      +

      Alex: The practical takeaway is this. 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. 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.

      +
      +

      Jamie: How should someone choose between those options?

      +

      Alex: Here is the plain-English version of When to Use Different Communication Channels. GitHub Discussions are separate from Issues. Put another way, use Discussions for: "What do people think about X approach?" and Issues for: "The X button is broken.".

      +

      Alex: Use the comparison to make a decision, not to recite a table. The main contrasts are: PR comment means Feedback on a specific code change. PR review means Formal verdict (approve/request changes) with consolidated feedback. Discussion means Open-ended conversation, proposals, community Q&A.

      +

      Jamie: Let's pause on Try It: Rewrite One Comment. What should a learner take away from it?

      +

      Alex: This is where Try It: Rewrite One Comment becomes real: time: 2 minutes What you need: Just your brain. That matters in practice: Read this code review comment and rewrite it to be constructive. The workshop is closer to rehearsal than lecture. You hear the move, try the move, and then check what changed.

      +

      Alex: First, what you noticed. Then, why it matters. After that, what you suggest. Finally, why the suggestion helps. It is a checklist, but a meaningful one: every item creates evidence that the next step is safe.

      +

      Jamie: Before we leave Try It: Rewrite One Comment, what is the practical point?

      +

      Alex: First, encouragement. It is like walking a hallway with named doors: read the sign, enter the right room, then confirm where you landed.

      +

      Jamie: Let's pause on Contributing to Open Source. What should a learner take away from it?

      +

      Alex: Keep the learner anchored in Contributing to Open Source. This section was previously Appendix T. This is the part to say slowly: It is now part of the teaching narrative.

      +
      +

      Alex: Keep the teaching thread moving. The reason A Guide for First-Time Contributors matters is that you do not need to be a professional developer to contribute to open source. That gives the learner a simple foothold: documentation, accessibility improvements, and bug reports are among the most valuable contributions any project can receive.

      +

      Jamie: Let's pause on 1. What Is Open Source? What should a learner take away from it?

      +

      Alex: Start with 1. What Is Open Source?: Open source software is software whose source code is publicly available. The next useful detail is this: Anyone can read it, use it, and - in most cases - contribute to it.

      +

      Alex: The practical takeaway is this. 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.

      +

      Alex: Keep the teaching thread moving. Here is the plain-English version of 2. Who Can Contribute? Contributors come from all backgrounds, skill levels, and countries. Put another way, 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. It is like learning a transit route. The names of the stops matter because they tell you whether you are still going the right direction.

      +
      +

      Jamie: Let's pause on 3. What Makes a Good First Contribution? What should a learner take away from it?

      +

      Alex: Start with 3. What Makes a Good First Contribution? There is something to understand, something to try, and something that proves the try worked.

      +

      Alex: The practical takeaway is this. 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.

      +

      Alex: Keep the teaching thread moving. Keep the learner anchored in Signs a contribution is too large for a first attempt. A well-executed small contribution is far more valuable than a large contribution that cannot be merged because it is out of scope.

      +

      Alex: The practical takeaway is this. 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.

      +

      Jamie: Let's pause on 4. Finding Something to Work On. What should a learner take away from it?

      +

      Alex: The reason 4. Finding Something to Work On matters is that most open source projects label issues that are suitable for new contributors. That gives the learner a simple foothold: how to search: On any GitHub repository, go to Issues → filter by label.

      +
      +

      Alex: Keep the teaching thread moving. Start with Learning Cards: Finding Something to Work On. There is something to understand, something to try, and something that proves the try worked.

      +

      Alex: The practical takeaway is this. 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. 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.

      +

      Jamie: What is the pre-flight check here?

      +

      Alex: Here is the plain-English version of 5. Reading an Issue Before You Start. Before commenting "I'll take this" on an issue, ask yourself. Put another way, 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.

      +

      Alex: The practical takeaway is this. 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.

      +

      Jamie: Let's pause on Tool Cards: Fork, Clone, and Contribute. What should a learner take away from it?

      +

      Alex: Start with Tool Cards: Fork, Clone, and Contribute. There is something to understand, something to try, and something that proves the try worked.

      +

      Alex: First, click Fork on the repository page, then Create fork. Then, edit files directly in your fork's web interface. After that, click Contribute Open pull request to submit back to the original. Finally, fork the repo on github.com first. It is a checklist, but a meaningful one: every item creates evidence that the next step is safe.

      +

      Jamie: Before we leave Tool Cards: Fork, Clone, and Contribute, what is the practical point?

      +

      Alex: First, navigate to your fork and press. to open in the web editor. Then, edit, commit, and create a PR from the Source Control panel. After that, fork on github.com, then clone your fork: Ctrl+Shift+P Git: Clone. Finally, create a branch, make edits, commit and push. It is like walking a hallway with named doors: read the sign, enter the right room, then confirm where you landed.

      +

      Alex: Treat examples as spoken recipes, not decorations. You may hear something like 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. Read the command, understand what it changes, then run it only when the repository state matches the lesson.

      +
      +

      Jamie: Let's pause on The Basic Workflow. What should a learner take away from it?

      +

      Alex: Start with The Basic Workflow. There is something to understand, something to try, and something that proves the try worked.

      +

      Alex: First, fork the repository - creates your own copy on GitHub. Then, clone your fork to your computer (or open a Codespace - see Appendix N). After that, create a branch - name it something descriptive: fix/broken-link-setup-guide. Finally, make your change - edit the file, save, verify. It is like walking a hallway with named doors: read the sign, enter the right room, then confirm where you landed.

      +

      Jamie: Before we leave The Basic Workflow, what is the practical point?

      +

      Alex: First, commit with a clear message - "Fix broken link in setup-guide.md line 34". Then, push to your fork. After that, open a pull request from your branch to the original repository's default branch. Finally, respond to review feedback - maintainers may ask for changes; this is normal and not a rejection. The rhythm is simple: orient, act, verify, then continue.

      +

      Alex: Keep the teaching thread moving. The reason Writing a Good PR Description matters is that example: Fixed a broken link on line 34 of setup-guide.md. That gives the learner a simple foothold: the link pointed to /docs/old-setup which no longer exists. The interface gets friendlier when it stops being a wall of controls and starts being a set of named places.

      +

      Alex: The practical takeaway is this. What did you change? Why was the change needed? How did you verify it works?

      +

      Jamie: How should someone ask for help in a way that gets them unstuck faster?

      +

      Alex: Start with 7. Getting Help: It is always acceptable to ask a question on an issue or pull request. The next useful detail is this: 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.

      +

      Alex: The practical takeaway is this. 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.

      +
      +

      Alex: Keep the teaching thread moving. Here is the plain-English version of 8. After Your Contribution Is Merged. This matters for your GitHub profile. Put another way, 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.

      +

      Alex: The practical takeaway is this. 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.

      +

      Jamie: Let's pause on 9. Building a Contribution Habit. What should a learner take away from it?

      +

      Alex: This is where 9. Building a Contribution Habit becomes real: the hardest part of open source contribution is starting. That matters in practice: 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.

      +

      Alex: Keep the teaching thread moving. Keep the learner anchored in Practical habits. Challenge Time: Complete Challenge 8: The Culture Layer in the Challenge Hub, then advance to Chapter 09: Labels, Milestones and Projects. This is the part to say slowly: Next: Chapter 09: Labels, Milestones, and Projects Back: Chapter 07: Merge Conflicts Related appendices: Appendix M: Accessibility Standards Appendix F: Git Security Appendix O: Branch Protection. A good GitHub workflow is like a well-run meeting: everyone knows the topic, the next action, and who has the floor.

      +

      Alex: The practical takeaway is this. 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.

      +
      +

      Jamie: Let's pause on Part 1: The GitHub Pull Requests Extension. What should a learner take away from it?

      +

      Alex: The reason The GitHub Pull Requests Extension matters is that see also: Appendix G: VS Code Reference for the complete list of GitHub Pull Requests extension keyboard shortcuts.

      +

      Alex: Keep the teaching thread moving. Start with 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,. The next useful detail is this: Prerequisites: Working with Pull Requests, Git & Source Control in VS Code Mac keyboard shortcuts: Throughout this chapter, all Ctrl+ shortcuts use Cmd+ on Mac, and Alt+ shortcuts use Option+ on Mac.

      +

      Jamie: What belongs in the live room, and what can wait until after?

      +

      Alex: Here is the plain-English version of Workshop Recommendation (Chapter 15, Part 1). Chapter 15, Part 1 introduces the GitHub Pull Requests extension for managing PRs directly from VS Code.

      +

      Alex: The practical takeaway is this. There are 2 guided challenges. Automation check: none (extension installation and review state are account-local). The evidence is issue comment with confirmation of actions completed. The pattern is install, check out, review, comment.

      +
      +

      Jamie: Let's pause on Chapter 15, Part 1 Practice Set. What should a learner take away from it?

      +

      Alex: Start with Chapter 15, Part 1 Practice Set. There is something to understand, something to try, and something that proves the try worked.

      +

      Alex: First, install the GitHub Pull Requests extension - add the extension to VS Code and sign in with your GitHub account. Then, check out a PR and post a review comment - download a PR branch locally, read the diff, and post one constructive review comment. It is a checklist, but a meaningful one: every item creates evidence that the next step is safe.

      +

      Jamie: Let's pause on Practice 15.1 Step-by-Step: Install the Extension. What should a learner take away from it?

      +

      Alex: Keep the learner anchored in Practice 15.1 Step-by-Step: Install the Extension. Install the GitHub Pull Requests and Issues extension and authenticate with your GitHub account. This is the part to say slowly: VS Code desktop with your Learning Room repository open.

      +

      Alex: First, open the Extensions sidebar: Ctrl+Shift+X (Mac: Cmd+Shift+X). Then, your screen reader announces "Extensions: Marketplace." The search box has focus. After that, type GitHub Pull Requests in the search box and press Enter. Finally, navigate down the results list. Select GitHub Pull Requests (publisher: GitHub). It is like walking a hallway with named doors: read the sign, enter the right room, then confirm where you landed.

      +

      Jamie: Before we leave Practice 15.1 Step-by-Step: Install the Extension, what is the practical point?

      +

      Alex: First, activate the Install button. VS Code installs the extension and may show a notification. Then, after installation, VS Code prompts you to sign in. Activate Sign in to GitHub. After that, a browser window opens for GitHub OAuth. Approve the authorization and return to VS Code. Finally, verify: open the Explorer sidebar (Ctrl+Shift+E). You should now see a GitHub section in the sidebar showing Pull Requests and Issues. The rhythm is simple: orient, act, verify, then continue.

      +

      Jamie: Let's pause on Practice 15.2 Step-by-Step: Check Out a PR and Post a Comment. What should a learner take away from it?

      +

      Alex: The reason Practice 15.2 Step-by-Step: Check Out a PR and Post a Comment matters is that check out someone else's PR branch locally, read the diff in VS Code, and post one constructive review comment. That gives the learner a simple foothold: VS Code with the GitHub Pull Requests extension installed.

      +

      Alex: First, open the Command Palette: Ctrl+Shift+P (Mac: Cmd+Shift+P). Then, type GitHub Pull Requests: Focus on Pull Requests View and select it. The Pull Requests panel opens. After that, navigate the list of open PRs. Find one that is not yours (a classmate's PR from Chapter 6, 7, or 14). Finally, 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. The rhythm is simple: orient, act, verify, then continue.

      +

      Jamie: Before we leave Practice 15.2 Step-by-Step: Check Out a PR and Post a Comment, what is the practical point?

      +

      Alex: First, open the Command Palette again and run GitHub Pull Requests: Open Changed Files. This shows the list of files the PR changed. Then, open one changed file. VS Code opens the Diff Editor showing old content on the left and new content on the right. After that, 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). Finally, find one specific thing to comment on: a typo, an unclear sentence, a missing step, or something the author did well. Think of it as a rail line: each stop confirms you are still on the right route before the next one.

      +
      +

      Jamie: What should the learner prove to themselves after each small task?

      +

      Alex: Start with Completing Chapter 15, Part 1: Submit Your Evidence: Open your assigned setup or review practice issue and post a completion comment. The next useful detail is this: Close your Chapter 12 challenge issues when done.

      +

      Alex: Keep the teaching thread moving. Start with Expected Outcomes. There is something to understand, something to try, and something that proves the try worked.

      +

      Alex: The practical takeaway is this. 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.

      +

      Jamie: What is the teaching move inside If You Get Stuck?

      +

      Alex: This is where If You Get Stuck becomes real: continue learning: The GitHub Skills course Review Pull Requests practices approving, requesting changes, and using suggestions in an interactive format. That matters in practice: See Appendix Z for the full catalog.

      +

      Alex: First, extension does not install? Reload VS Code: Ctrl+Shift+P, then run Developer: Reload Window. Then, oAuth sign-in fails? Verify your GitHub account is active in the browser first, close VS Code, reopen, and retry. After that, pR list is empty? Switch to "All Open" view in the GitHub Pull Requests panel. Finally, checkout fails? Confirm you have write access to the repository. If not, use the read-only GitHub.com fallback. It is a checklist, but a meaningful one: every item creates evidence that the next step is safe.

      +

      Jamie: If someone only remembers one thing from If You Get Stuck, what should it be?

      +

      Alex: First, diff Editor is hard to navigate? Press F7 for the Accessible Diff Viewer mode, which is purpose-built for screen readers. Then, cannot find the Add Comment command? Use Command Palette and search for GitHub Pull Requests: Add Comment. After that, ask facilitator to help verify the GitHub PR panel and model one review comment. Finally, finished but not sure you did it right? Compare your work against the Challenge 11 reference solution. It is like walking a hallway with named doors: read the sign, enter the right room, then confirm where you landed.

      +
      +

      Alex: Keep the teaching thread moving. Keep the learner anchored in Learning Moment. Reviewing others' work refines your own standards and builds community trust. This is the part to say slowly: The comment you just wrote helps another student learn - and you learn by articulating what makes documentation clear.

      +

      Jamie: Before we leave Learning Pattern Used in This Chapter, what is the practical point?

      +

      Alex: First, install and configure the tool before starting the task. Then, practice on someone else's work first (reviewing is safer than authoring). After that, use accessibility tools (F7 Accessible Diff Viewer) to navigate efficiently. Finally, write specific, constructive feedback (not just "looks good"). The rhythm is simple: orient, act, verify, then continue.

      +

      Alex: Keep the teaching thread moving. Start with 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. Think of it like entering a new building: first you find the lobby, then the room, then the door you actually need.

      +
      +

      Jamie: Let's pause on Method 1: Extensions Sidebar. What should a learner take away from it?

      +

      Alex: Start with Method 1: Extensions Sidebar. There is something to understand, something to try, and something that proves the try worked.

      +

      Alex: First, open Extensions sidebar: Ctrl+Shift+X (Mac: Cmd+Shift+X). Then, type "GitHub Pull Requests" in the search box. After that, find "GitHub Pull Requests and Issues" (publisher: GitHub). Finally, navigate to the extension in the results list. Treat it like a recipe: do not add the next ingredient until the previous one is actually in the bowl.

      +

      Jamie: Before we leave Method 1: Extensions Sidebar, what is the practical point?

      +

      Alex: First, press Enter to open the extension detail page. Then, tab to "Install" button → press Enter. It is a checklist, but a meaningful one: every item creates evidence that the next step is safe.

      +

      Jamie: Let's pause on Method 2: Command Palette. What should a learner take away from it?

      +

      Alex: This is where Method 2: Command Palette becomes real: the Extensions sidebar is a tree view. That matters in practice: Use Up/Down Arrow to navigate, Enter to open an extension's detail page.

      +

      Alex: First, ctrl+Shift+P. Then, type "install extensions". After that, select "Extensions: Install Extensions". Finally, search for "GitHub Pull Requests". It is a checklist, but a meaningful one: every item creates evidence that the next step is safe.

      +

      Jamie: Before we leave Method 2: Command Palette, what is the practical point?

      +

      Alex: First, install "GitHub Pull Requests and Issues". It is like walking a hallway with named doors: read the sign, enter the right room, then confirm where you landed.

      +

      Jamie: Let's pause on Signing In to GitHub. What should a learner take away from it?

      +

      Alex: Keep the learner anchored in Signing In to GitHub. After installation, VS Code prompts you to sign in.

      +

      Alex: First, a notification appears: "Sign in to GitHub to use Pull Requests". Then, navigate to the notification (Alt+N / Mac: Option+N, or status bar navigation). After that, select "Sign in". Finally, VS Code opens your browser for GitHub OAuth authentication. It is like walking a hallway with named doors: read the sign, enter the right room, then confirm where you landed.

      +

      Jamie: Before we leave Signing In to GitHub, what is the practical point?

      +

      Alex: First, authorize VS Code in the browser. Then, return to VS Code - you're now signed in. The rhythm is simple: orient, act, verify, then continue.

      +
      +

      Alex: Keep the teaching thread moving. Start with Verify sign-in. There is something to understand, something to try, and something that proves the try worked.

      +

      Alex: The practical takeaway is this. 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.

      +

      Jamie: Let's pause on What the Extension Adds. What should a learner take away from it?

      +

      Alex: Start with What the Extension Adds. There is something to understand, something to try, and something that proves the try worked.

      +

      Alex: The practical takeaway is this. 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.

      +

      Alex: Keep the teaching thread moving. Start with Learning Cards: Installing the PR Extension. There is something to understand, something to try, and something that proves the try worked.

      +

      Alex: The practical takeaway is this. 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". 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.

      +
      +

      Jamie: Let's pause on Method 1: Activity Bar. What should a learner take away from it?

      +

      Alex: This is where Method 1: Activity Bar becomes real: click the GitHub logo icon in the Activity Bar (the vertical strip of icons on the far left). That matters in practice: The GitHub Pull Requests panel opens.

      +

      Alex: The practical takeaway is this. "Pull Requests". "Issues".

      +

      Alex: First, the Activity Bar is not always reachable by Tab from the editor. Then, use Ctrl+Shift+P (Mac: Cmd+Shift+P) → type "GitHub Pull Requests: View Pull Request" or "Focus on Pull Requests View" → press Enter. After that, alternatively press Ctrl+Shift+G (Mac: Cmd+Shift+G) to open Source Control, then Tab until you reach the Activity Bar icon strip. Finally, navigate to the repository on GitHub.com. It is a checklist, but a meaningful one: every item creates evidence that the next step is safe.

      +

      Jamie: Before we leave Method 1: Activity Bar, what is the practical point?

      +

      Alex: First, click the Pull requests tab. Then, click any PR title to view its conversation, commits, and changed files. After that, use the Files changed tab to review diffs. It is like walking a hallway with named doors: read the sign, enter the right room, then confirm where you landed.

      +

      Alex: Treat examples as spoken recipes, not decorations. You may hear something like 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". Read the command, understand what it changes, then run it only when the repository state matches the lesson.

      +

      Jamie: Let's pause on Method 2: Explorer Section. What should a learner take away from it?

      +

      Alex: Start with Method 2: Explorer Section. There is something to understand, something to try, and something that proves the try worked.

      +

      Alex: First, open Explorer: Ctrl+Shift+E (Mac: Cmd+Shift+E). Then, navigate with Arrow keys to find the "GitHub Pull Requests" section. After that, expand it with Right Arrow. It is like walking a hallway with named doors: read the sign, enter the right room, then confirm where you landed.

      +

      Jamie: Let's pause on Description. What should a learner take away from it?

      +

      Alex: The reason Description matters is that the GitHub Pull Requests panel has two top-level sections. That gives the learner a simple foothold: "My Pull Requests" contains four filters: Assigned to Me, Created by Me, Waiting for my Review, and All Open.

      +
      +

      Alex: Keep the teaching thread moving. Start with Screen reader announcement example: "Pull Request 42: Add Timeline Guide, opened by jeffb, 2 days ago, 3 files changed".

      +

      Jamie: Let's pause on By status. What should a learner take away from it?

      +

      Alex: Start with By status. There is something to understand, something to try, and something that proves the try worked.

      +

      Alex: The practical takeaway is this. "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.

      +

      Alex: Keep the teaching thread moving. This is where By repository becomes real: the tree organizes PRs by repository. The workshop is closer to rehearsal than lecture. You hear the move, try the move, and then check what changed.

      +
      +

      Jamie: Let's pause on Viewing PR Details. What should a learner take away from it?

      +

      Alex: Keep the learner anchored in Viewing PR Details. A PR detail view opens in the editor area showing.

      +

      Alex: The practical takeaway is this. 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).

      +

      Alex: First, navigate to a PR in the tree. Then, press Enter. It is like walking a hallway with named doors: read the sign, enter the right room, then confirm where you landed.

      +

      Alex: Keep the teaching thread moving. Start with Screen reader experience. There is something to understand, something to try, and something that proves the try worked.

      +

      Alex: The practical takeaway is this. 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.

      +

      Jamie: Let's pause on 3. Checking Out a Pull Request Branch. What should a learner take away from it?

      +

      Alex: Start with 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.

      +
      +

      Alex: Keep the teaching thread moving. Start with Why Check Out a PR. There is something to understand, something to try, and something that proves the try worked.

      +

      Alex: The practical takeaway is this. 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.

      +

      Jamie: Let's pause on Method 1: From the PR Detail View. What should a learner take away from it?

      +

      Alex: Start with Method 1: From the PR Detail View. There is something to understand, something to try, and something that proves the try worked.

      +

      Alex: The practical takeaway is this. Downloads the branch. Switches your local repository to that branch. Opens the changed files in the editor.

      +

      Alex: First, open a PR (see Section 2). Then, in the PR detail view, navigate to "Checkout" button. After that, press Enter. It is a checklist, but a meaningful one: every item creates evidence that the next step is safe.

      +

      Jamie: Let's pause on Method 2: From the PR Tree. What should a learner take away from it?

      +

      Alex: Start with Method 2: From the PR Tree. There is something to understand, something to try, and something that proves the try worked.

      +

      Alex: First, navigate to the PR in the GitHub Pull Requests tree. Then, press Shift+F10 (Mac: Ctrl+Return) to open context menu. After that, select "Checkout Pull Request". It is like walking a hallway with named doors: read the sign, enter the right room, then confirm where you landed.

      +
      +

      Jamie: Let's pause on Method 3: Command Palette. What should a learner take away from it?

      +

      Alex: The reason Method 3: Command Palette matters is that after checkout, the bottom-left status bar shows the branch name (example: "jeffb/add-timeline-guide"). That gives the learner a simple foothold: your local files now match that branch.

      +

      Alex: First, ctrl+Shift+P (Mac: Cmd+Shift+P). Then, type "GitHub Pull Requests: Checkout". After that, select "GitHub Pull Requests: Checkout Pull Request". Finally, choose the PR from the list. The rhythm is simple: orient, act, verify, then continue.

      +

      Jamie: Let's pause on Returning to Your Original Branch. What should a learner take away from it?

      +

      Alex: Start with Returning to Your Original Branch. There is something to understand, something to try, and something that proves the try worked.

      +

      Alex: First, ctrl+Shift+P (Mac: Cmd+Shift+P). Then, type "git checkout". After that, select "Git: Checkout to.". Finally, choose your original branch (usually main or your feature branch). Think of it as a rail line: each stop confirms you are still on the right route before the next one.

      +

      Jamie: Let's pause on Learning Cards: Checking Out a PR. What should a learner take away from it?

      +

      Alex: Start with Learning Cards: Checking Out a PR. There is something to understand, something to try, and something that proves the try worked.

      +

      Alex: The practical takeaway is this. 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. 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.

      +
      +

      Alex: Keep the teaching thread moving. This is where 4. Reviewing Pull Requests in VS Code becomes real: once you've checked out a PR (or opened it in the detail view), you can review its changes fully within VS Code.

      +

      Jamie: Let's pause on In the PR detail view. What should a learner take away from it?

      +

      Alex: Start with In the PR detail view. There is something to understand, something to try, and something that proves the try worked.

      +

      Alex: First, scroll down to "Files Changed" section. Then, each file is a link. After that, navigate with Arrow keys. Finally, press Enter on a file to open its diff view. It is like walking a hallway with named doors: read the sign, enter the right room, then confirm where you landed.

      +

      Alex: Keep the teaching thread moving. The reason Screen reader announcement matters is that "docs/11-vscode-interface.md, 42 additions, 3 deletions". The interface gets friendlier when it stops being a wall of controls and starts being a set of named places.

      +
      +

      Jamie: Let's pause on Understanding the Diff View. What should a learner take away from it?

      +

      Alex: Start with Understanding the Diff View: When you open a file from "Files Changed".

      +

      Alex: Keep the teaching thread moving. Start with Split view mode (default). There is something to understand, something to try, and something that proves the try worked.

      +

      Alex: The practical takeaway is this. Left side: original file (before changes). Right side: modified file (after changes). Changed lines highlighted (added = green, removed = red).

      +

      Jamie: Let's pause on Inline view mode. What should a learner take away from it?

      +

      Alex: Start with Inline view mode. There is something to understand, something to try, and something that proves the try worked.

      +

      Alex: The practical takeaway is this. Single editor. Removed lines shown with - prefix. Added lines shown with + prefix.

      +
      +

      Alex: Keep the teaching thread moving. Start with To toggle between views. There is something to understand, something to try, and something that proves the try worked.

      +

      Alex: The practical takeaway is this. Command Palette: Ctrl+Shift+P (Mac: Cmd+Shift+P) → "Diff: Toggle Inline View".

      +

      Jamie: Let's pause on Recommended workflow for screen reader users. What should a learner take away from it?

      +

      Alex: Start with Recommended workflow for screen reader users. There is something to understand, something to try, and something that proves the try worked.

      +

      Alex: The practical takeaway is this. Unchanged lines (for context). Removed lines (prefixed with -). Added lines (prefixed with +).

      +

      Alex: First, open a changed file from the PR detail view. Then, press F7 to jump to the first diff hunk. After that, press Alt+F2 (Mac: Option+F2) to open Accessible View. Finally, read the hunk content. The rhythm is simple: orient, act, verify, then continue.

      +

      Jamie: Before we leave Recommended workflow for screen reader users, what is the practical point?

      +

      Alex: First, press Escape to close Accessible View. Then, press F7 to jump to the next hunk. After that, repeat until all hunks reviewed. Think of it as a rail line: each stop confirms you are still on the right route before the next one.

      +

      Alex: Keep the teaching thread moving. Start with 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. The next useful detail is this: Previously, deleted code could only be read, not selected.

      +
      +

      Jamie: Let's pause on Flagging Issues During Review. What should a learner take away from it?

      +

      Alex: Here is the plain-English version of Flagging Issues During Review. Start Review saves your comments as a draft until you submit the full review (see Section 7).

      +

      Alex: First, navigate to the specific line in the diff. Then, press Shift+F10 (Mac: Ctrl+Return) for context menu. After that, select "Add Comment". Finally, type your comment in the input that appears. Treat it like a recipe: do not add the next ingredient until the previous one is actually in the bowl.

      +

      Jamie: Before we leave Flagging Issues During Review, what is the practical point?

      +

      Alex: First, choose "Single Comment" or "Start Review". It is a checklist, but a meaningful one: every item creates evidence that the next step is safe.

      +

      Alex: Keep the teaching thread moving. Start with Learning Cards: Reviewing Pull Requests in VS Code. There is something to understand, something to try, and something that proves the try worked.

      +

      Alex: The practical takeaway is this. 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. 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.

      +

      Jamie: Let's pause on Tool Cards: Create a Pull Request (from your editor). What should a learner take away from it?

      +

      Alex: Keep the learner anchored in Tool Cards: Create a Pull Request (from your editor). VS Code Desktop (primary for Day 2). This is the part to say slowly: After you've pushed commits to a feature branch, you can create a PR without leaving VS Code.

      +

      Alex: First, ctrl+Shift+P GitHub Pull Requests: Create Pull Request. Then, fill in the title, description, and base branch. After that, click Create. Finally, push your branch, then click the Compare & pull request banner on the repo page. It is like walking a hallway with named doors: read the sign, enter the right room, then confirm where you landed.

      +

      Jamie: Before we leave Tool Cards: Create a Pull Request (from your editor), what is the practical point?

      +

      Alex: First, fill in the form and click Create pull request. Then, after pushing, click Create Pull Request -- this opens gitub.com with the form pre-filled. The rhythm is simple: orient, act, verify, then continue.

      +

      Alex: Treat examples as spoken recipes, not decorations. You may hear something like git push -u origin your-branch; gh pr create --title "Title" --body "Description". Read the command, understand what it changes, then run it only when the repository state matches the lesson.

      +
      +

      Jamie: Let's pause on Prerequisites. What should a learner take away from it?

      +

      Alex: Start with Prerequisites. There is something to understand, something to try, and something that proves the try worked.

      +

      Alex: First, you've created a branch (see Git & Source Control: Branch Management). Then, you've made commits. After that, you've pushed the branch to GitHub (Ctrl+Shift+P / Mac: Cmd+Shift+P → "Git: Push"). The rhythm is simple: orient, act, verify, then continue.

      +

      Jamie: Let's pause on Method 1: Command Palette (Recommended). What should a learner take away from it?

      +

      Alex: Start with Method 1: Command Palette (Recommended). There is something to understand, something to try, and something that proves the try worked.

      +

      Alex: First, ctrl+Shift+P (Mac: Cmd+Shift+P). Then, type "GitHub Pull Requests: Create". After that, select "GitHub Pull Requests: Create Pull Request". Finally, a form opens in the editor. Think of it as a rail line: each stop confirms you are still on the right route before the next one.

      +

      Jamie: Let's pause on Method 2: Source Control Panel. What should a learner take away from it?

      +

      Alex: Start with Method 2: Source Control Panel. There is something to understand, something to try, and something that proves the try worked.

      +

      Alex: First, open Source Control: Ctrl+Shift+G (Mac: Cmd+Shift+G). Then, after pushing, a "Create Pull Request" button appears. After that, press Enter on that button. Treat it like a recipe: do not add the next ingredient until the previous one is actually in the bowl.

      +
      +

      Jamie: Let's pause on Method 3: GitHub Panel. What should a learner take away from it?

      +

      Alex: Start with Method 3: GitHub Panel. There is something to understand, something to try, and something that proves the try worked.

      +

      Alex: First, open GitHub view (Activity Bar → GitHub icon). Then, right-click your branch in the tree. After that, select "Create Pull Request". It is a checklist, but a meaningful one: every item creates evidence that the next step is safe.

      +

      Alex: Keep the teaching thread moving. Start with Title (required). There is something to understand, something to try, and something that proves the try worked.

      +

      Alex: The practical takeaway is this. Auto-filled with your most recent commit message. Edit to make it descriptive (example: "Add Timeline View documentation").

      +

      Jamie: Let's pause on Description (optional but recommended). What should a learner take away from it?

      +

      Alex: Start with Description (optional but recommended). There is something to understand, something to try, and something that proves the try worked.

      +

      Alex: The practical takeaway is this. 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.

      +
      +

      Alex: Keep the teaching thread moving. Start with Base branch (target). There is something to understand, something to try, and something that proves the try worked.

      +

      Alex: The practical takeaway is this. Usually main or develop. This is the branch your changes will merge into.

      +

      Jamie: Let's pause on Compare branch (source). What should a learner take away from it?

      +

      Alex: Start with Compare branch (source). There is something to understand, something to try, and something that proves the try worked.

      +

      Alex: The practical takeaway is this. Your feature branch (auto-selected). This is the branch with your changes.

      +

      Alex: Keep the teaching thread moving. Start with Reviewers (optional). There is something to understand, something to try, and something that proves the try worked.

      +

      Alex: The practical takeaway is this. Select people to review your PR. Navigate the list with Arrow keys.

      +
      +

      Jamie: Let's pause on Labels (optional). What should a learner take away from it?

      +

      Alex: Start with Labels (optional). There is something to understand, something to try, and something that proves the try worked.

      +

      Alex: The practical takeaway is this. Add labels like documentation, accessibility, good-first-issue.

      +

      Alex: Keep the teaching thread moving. Start with Milestone (optional). There is something to understand, something to try, and something that proves the try worked.

      +

      Alex: The practical takeaway is this. Link the PR to a project milestone.

      +

      Jamie: Let's pause on Draft PR checkbox. What should a learner take away from it?

      +

      Alex: Start with Draft PR checkbox. There is something to understand, something to try, and something that proves the try worked.

      +

      Alex: The practical takeaway is this. Check this if the PR is not ready for review yet. Unchecked = "Ready for review".

      +
      +

      Alex: Keep the teaching thread moving. Start with Screen reader navigation. There is something to understand, something to try, and something that proves the try worked.

      +

      Alex: The practical takeaway is this. All fields are standard form inputs. Tab to move between fields. Use Arrow keys in dropdowns (reviewers, labels, milestones).

      +

      Jamie: Let's pause on Submitting the PR. What should a learner take away from it?

      +

      Alex: This is where Submitting the PR becomes real: VS Code creates the PR on GitHub and shows a success message. That matters in practice: The PR link appears in the notification - click it to open the PR on GitHub, or open it in the GitHub Pull Requests panel.

      +

      Alex: First, review all fields. Then, tab to "Create" button. After that, press Enter. Finally, navigate to the repository on GitHub. It is a checklist, but a meaningful one: every item creates evidence that the next step is safe.

      +

      Jamie: Before we leave Submitting the PR, what is the practical point?

      +

      Alex: First, if you recently pushed, a yellow banner "Compare & pull request" appears - click it. Then, otherwise: click Pull requests tab, then New pull request, then select your branch. After that, fill in the title and description. Finally, click Create pull request. It is like walking a hallway with named doors: read the sign, enter the right room, then confirm where you landed.

      +

      Alex: Treat examples as spoken recipes, not decorations. You may hear something like 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. Read the command, understand what it changes, then run it only when the repository state matches the lesson.

      +

      Alex: Keep the teaching thread moving. Start with Learning Cards: Creating a Pull Request. There is something to understand, something to try, and something that proves the try worked.

      +

      Alex: The practical takeaway is this. 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. 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.

      +
      +

      Jamie: Let's pause on 6. Pull Request Description Templates. What should a learner take away from it?

      +

      Alex: The reason 6. Pull Request Description Templates matters is that many repositories include a PR template - a Markdown file that pre-fills the PR description with a checklist or structure.

      +

      Alex: Keep the teaching thread moving. Start with Where Templates Are Stored: When you create a PR in VS Code, the extension automatically loads the template into the description field.

      +

      Alex: The practical takeaway is this.github/pull request template.md (root).github/PULL REQUEST TEMPLATE.md.github/PULL REQUEST TEMPLATE/ (folder with multiple templates). docs/pull request template.md.

      +

      Jamie: Let's pause on Example PR Template. What should a learner take away from it?

      +

      Alex: Start with Example PR Template. There is something to understand, something to try, and something that proves the try worked.

      +

      Alex: Treat examples as spoken recipes, not decorations. You may hear something like 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,. Read the command, understand what it changes, then run it only when the repository state matches the lesson.

      +
      +

      Jamie: Let's pause on Screen reader workflow. What should a learner take away from it?

      +

      Alex: This is where Screen reader workflow becomes real: keyboard tip: Use Ctrl+F (Mac: Cmd+F) to jump to each <!-- placeholder, fill it in, then F3 to jump to the next one. The workshop is closer to rehearsal than lecture. You hear the move, try the move, and then check what changed.

      +

      Alex: First, create PR (Method 1-3 from Section 5). Then, the description field is pre-filled with the template. After that, navigate through the template with Arrow keys. Finally, replace each `` with your content. It is a checklist, but a meaningful one: every item creates evidence that the next step is safe.

      +

      Jamie: Before we leave Screen reader workflow, what is the practical point?

      +

      Alex: First, check checkboxes by typing x between the brackets: - [x]. It is like walking a hallway with named doors: read the sign, enter the right room, then confirm where you landed.

      +

      Jamie: Let's pause on 7. Commenting and Requesting Changes. What should a learner take away from it?

      +

      Alex: Start with 7. Commenting and Requesting Changes. There is something to understand, something to try, and something that proves the try worked.

      +

      Alex: The practical takeaway is this. Leave inline comments on specific lines. Request changes before the PR can be merged. Approve the PR. Submit general feedback.

      +

      Jamie: Let's pause on Adding an Inline Comment. What should a learner take away from it?

      +

      Alex: Start with Adding an Inline Comment. There is something to understand, something to try, and something that proves the try worked.

      +

      Alex: First, open a file from the PR's "Files Changed" list. Then, navigate to the line you want to comment on. After that, press Shift+F10 (Mac: Ctrl+Return) to open context menu. Finally, select "Add Comment". The rhythm is simple: orient, act, verify, then continue.

      +

      Jamie: Before we leave Adding an Inline Comment, what is the practical point?

      +

      Alex: First, type your comment. Then, choose "Add Single Comment" (posts immediately) or "Start Review" (saves as a draft). Think of it as a rail line: each stop confirms you are still on the right route before the next one.

      +
      +

      Jamie: Let's pause on Comment format tips. What should a learner take away from it?

      +

      Alex: Start with Comment format tips. There is something to understand, something to try, and something that proves the try worked.

      +

      Alex: The practical takeaway is this. Be specific: "This heading should be H3, not H2". Provide context: "Screen readers announce this as 'list with 1 item' - should be a paragraph instead". Suggest a fix: "Consider rewording to: 'Click the button to save'".

      +

      Jamie: Let's pause on If you have multiple comments to make, use "Start Review". What should a learner take away from it?

      +

      Alex: Start with If you have multiple comments to make, use "Start Review". There is something to understand, something to try, and something that proves the try worked.

      +

      Alex: First, add your first inline comment → select "Start Review". Then, continue adding comments to other lines. After that, all comments are saved as drafts (not visible to others yet). Treat it like a recipe: do not add the next ingredient until the previous one is actually in the bowl.

      +

      Jamie: Let's pause on Submitting Your Review. What should a learner take away from it?

      +

      Alex: This is where Submitting Your Review becomes real: the review type selector is a radio button group. That matters in practice: Use Arrow keys to choose, Enter to confirm.

      +

      Alex: The practical takeaway is this. Comment - general feedback, no approval decision. Approve - PR looks good, ready to merge. Request Changes - issues must be fixed before merging.

      +

      Alex: First, ctrl+Shift+P (Mac: Cmd+Shift+P). Then, type "GitHub Pull Requests: Submit Review". After that, select "GitHub Pull Requests: Finish Review". Finally, choose review type. It is a checklist, but a meaningful one: every item creates evidence that the next step is safe.

      +

      Jamie: Before we leave Submitting Your Review, what is the practical point?

      +

      Alex: First, optionally add a summary comment. Then, press Enter to submit. It is like walking a hallway with named doors: read the sign, enter the right room, then confirm where you landed.

      +
      +

      Jamie: Let's pause on What Happens After Submission. What should a learner take away from it?

      +

      Alex: Keep the learner anchored in What Happens After Submission. Web alternative (github.com) - reviewing. This is the part to say slowly: See Accessible Code Review for detailed screen reader steps.

      +

      Alex: The practical takeaway is this. All your draft comments post to GitHub. The PR author receives a notification. Your review status appears on the PR (Approved / Changes Requested / Commented). If you requested changes, the PR cannot merge until you approve it.

      +

      Alex: First, open the PR and click the Files changed tab. Then, read through each file's diff. After that, click the blue + button on any line to add an inline comment. Finally, choose Start a review to batch comments. It is like walking a hallway with named doors: read the sign, enter the right room, then confirm where you landed.

      +

      Jamie: Before we leave What Happens After Submission, what is the practical point?

      +

      Alex: First, click Review changes (top right) to select Comment / Approve / Request changes. Then, click Submit review. The rhythm is simple: orient, act, verify, then continue.

      +

      Alex: Treat examples as spoken recipes, not decorations. You may hear something like View the PR diff in your terminal; gh pr diff 42; Approve; gh pr review 42 --approve --body "Looks good."; Request changes; gh pr review 42 --request-changes --body "Heading hierarchy needs fixing."; Comment-only (no verdict); gh pr review 42 --comment --body. Read the command, understand what it changes, then run it only when the repository state matches the lesson.

      +

      Jamie: Let's pause on Learning Cards: Commenting and Requesting Changes. What should a learner take away from it?

      +

      Alex: Start with Learning Cards: Commenting and Requesting Changes. There is something to understand, something to try, and something that proves the try worked.

      +

      Alex: The practical takeaway is this. In a diff view, navigate to a line and press Shift+F10 for the context menu, then select "Add Comment" to leave inline feedback. Choose "Start Review" instead of "Single Comment" to batch multiple comments before submitting them all at once. When submitting a review, use Ctrl+Shift+P then "GitHub Pull Requests: Submit Review" and choose Approve, Request Changes, or Comment. Inline comments appear as expandable banners within the diff view -- look for the text input box that opens below the target line. The review submission dialog has radio buttons for Approve, Request Changes, and Comment with clear labels. Increase diff view font size with Ctrl+= so line numbers and change annotations are easier to read.

      +

      Alex: Keep the teaching thread moving. Start with 8. Merging Pull Requests: Who can merge: Repository maintainers, or contributors with write access. Think of it like entering a new building: first you find the lobby, then the room, then the door you actually need.

      +
      +

      Jamie: Let's pause on Prerequisites for Merging. What should a learner take away from it?

      +

      Alex: Here is the plain-English version of Prerequisites for Merging. Changing the base branch: If the PR was opened against the wrong base branch, you can change it from the PR detail view in VS Code. Put another way, scroll to the base branch field in the PR detail view and activate the dropdown to select a different target branch.

      +

      Alex: First, all required reviews are approved. Then, all CI checks pass (green checkmarks). After that, no merge conflicts exist. Finally, branch is up to date with base branch (main). Treat it like a recipe: do not add the next ingredient until the previous one is actually in the bowl.

      +

      Jamie: Let's pause on Method 1: PR Detail View. What should a learner take away from it?

      +

      Alex: Start with Method 1: PR Detail View. There is something to understand, something to try, and something that proves the try worked.

      +

      Alex: First, open the PR in VS Code. Then, scroll to the bottom of the PR detail view. After that, find "Merge Pull Request" button. Finally, press Enter. It is a checklist, but a meaningful one: every item creates evidence that the next step is safe.

      +

      Jamie: Before we leave Method 1: PR Detail View, what is the practical point?

      +

      Alex: First, choose merge type (see below). It is like walking a hallway with named doors: read the sign, enter the right room, then confirm where you landed.

      +

      Jamie: What is the teaching move inside Method 2: Command Palette?

      +

      Alex: Start with Method 2: Command Palette. There is something to understand, something to try, and something that proves the try worked.

      +

      Alex: First, ctrl+Shift+P (Mac: Cmd+Shift+P). Then, type "GitHub Pull Requests: Merge". After that, select "GitHub Pull Requests: Merge Pull Request". Finally, choose the PR from the list. It is like walking a hallway with named doors: read the sign, enter the right room, then confirm where you landed.

      +

      Jamie: If someone only remembers one thing from Method 2: Command Palette, what should it be?

      +

      Alex: First, select merge type. The rhythm is simple: orient, act, verify, then continue.

      +
      +

      Alex: Keep the teaching thread moving. The reason Merge Types matters is that the merge type selector is a dropdown or radio group. That gives the learner a simple foothold: navigate with Arrow keys, confirm with Enter. The interface gets friendlier when it stops being a wall of controls and starts being a set of named places.

      +

      Jamie: Let's pause on Which merge type to use. What should a learner take away from it?

      +

      Alex: Start with Which merge type to use. There is something to understand, something to try, and something that proves the try worked.

      +

      Alex: The practical takeaway is this. Check the repository's CONTRIBUTING.md for guidance. If unsure, use Merge Commit (the default and safest option).

      +

      Jamie: Let's pause on After Merging. What should a learner take away from it?

      +

      Alex: Start with After Merging. There is something to understand, something to try, and something that proves the try worked.

      +

      Alex: First, the PR closes automatically. Then, the feature branch can be deleted (VS Code prompts: "Delete branch?"). After that, recommended: switch back to main and pull the merged changes. Treat it like a recipe: do not add the next ingredient until the previous one is actually in the bowl.

      +
      +

      Jamie: Let's pause on Switching to main and pulling. What should a learner take away from it?

      +

      Alex: This is where Switching to main and pulling becomes real: (Mac users: use Cmd+Shift+P instead of Ctrl+Shift+P).

      +

      Alex: Treat examples as spoken recipes, not decorations. You may hear something like Ctrl+Shift+P → "Git: Checkout to." → select "main"; Ctrl+Shift+P → "Git: Pull". Read the command, understand what it changes, then run it only when the repository state matches the lesson.

      +

      Jamie: Let's pause on Deleting the Feature Branch. What should a learner take away from it?

      +

      Alex: Keep the learner anchored in Deleting the Feature Branch. After merging, the feature branch is no longer needed. This is the part to say slowly: Web alternative (github.com) - merging. A good GitHub workflow is like a well-run meeting: everyone knows the topic, the next action, and who has the floor.

      +

      Alex: First, ctrl+Shift+P (Mac: Cmd+Shift+P). Then, type "git delete branch". After that, select "Git: Delete Branch.". Finally, choose the merged branch. It is like walking a hallway with named doors: read the sign, enter the right room, then confirm where you landed.

      +

      Jamie: Before we leave Deleting the Feature Branch, what is the practical point?

      +

      Alex: First, open the PR's Conversation tab. Then, scroll to the merge button at the bottom. After that, click the dropdown arrow to choose a merge strategy (Squash, Rebase, or Merge commit). Finally, click Merge pull request, then Confirm merge. The rhythm is simple: orient, act, verify, then continue.

      +

      Alex: Treat examples as spoken recipes, not decorations. You may hear something like Merge with default strategy; gh pr merge 42; Squash and merge, then delete the branch; gh pr merge 42 --squash --delete-branch; Enable auto-merge (merges when checks pass); gh pr merge 42 --auto --squash. Read the command, understand what it changes, then run it only when the repository state matches the lesson.

      +

      Jamie: Let's pause on Learning Cards: Merging Pull Requests. What should a learner take away from it?

      +

      Alex: Start with Learning Cards: Merging Pull Requests. There is something to understand, something to try, and something that proves the try worked.

      +

      Alex: The practical takeaway is this. The merge type selector (Merge Commit, Squash, Rebase) is announced as a dropdown or radio group -- use Arrow keys to move between options and Enter to confirm; if unsure, choose Merge Commit (the default and safest option). After merging, VS Code prompts "Delete branch?" as a notification -- press Alt+N to focus the notification and Enter to confirm, then run Ctrl+Shift+P then "Git: Checkout to" and select main to return to your default branch. Confirm the merge succeeded by pressing F6 to reach the Status Bar and verifying it now reads main instead of the feature branch name. The merge button at the bottom of the PR detail view includes a dropdown arrow for selecting merge type -- at high zoom, widen the editor pane so the button label and dropdown are not truncated. After merging, the PR detail view header changes from "Open" (green badge) to "Merged" (purple badge) -- verify this colour/label change before deleting the branch. When switching back to main, the branch name in the bottom-left Status Bar updates immediately -- confirm it reads main before pulling new changes with Ctrl+Shift+P then "Git: Pull".

      +
      +

      Alex: Keep the teaching thread moving. Start with "No pull requests found": Issue: The GitHub Pull Requests panel is empty.

      +

      Jamie: Let's pause on Solutions. What should a learner take away from it?

      +

      Alex: Start with Solutions. There is something to understand, something to try, and something that proves the try worked.

      +

      Alex: First, verify you're signed in: Ctrl+Shift+P (Mac: Cmd+Shift+P) → "GitHub Pull Requests: Sign in". Then, check you have a folder open containing a Git repository. After that, refresh the panel: Ctrl+Shift+P (Mac: Cmd+Shift+P) → "GitHub Pull Requests: Refresh Pull Requests List". Treat it like a recipe: do not add the next ingredient until the previous one is actually in the bowl.

      +

      Jamie: Before we leave Solutions, what is the practical point?

      +

      Alex: First, verify you've pushed your branch: Ctrl+Shift+P (Mac: Cmd+Shift+P) → "Git: Push". Then, check you have write access to the repository. After that, ensure your branch is ahead of the base branch (has new commits). It is a checklist, but a meaningful one: every item creates evidence that the next step is safe.

      +
      +

      Jamie: Let's pause on "Authentication failed". What should a learner take away from it?

      +

      Alex: Keep the learner anchored in "Authentication failed". Issue: VS Code can't connect to GitHub.

      +

      Jamie: What is the teaching move inside Solutions?

      +

      Alex: First, sign out and sign back in: Ctrl+Shift+P (Mac: Cmd+Shift+P) → "GitHub Pull Requests: Sign out" → then sign in again. Then, check your GitHub Personal Access Token (see Appendix D: Git Authentication). After that, verify network connection. The rhythm is simple: orient, act, verify, then continue.

      +

      Jamie: Let's pause on Try It: Review a PR from VS Code. What should a learner take away from it?

      +

      Alex: Start with Try It: Review a PR from VS Code: Time: 3 minutes What you need: VS Code with GitHub Pull Requests extension installed and signed in. The next useful detail is this: You just reviewed a pull request entirely from VS Code.

      +

      Alex: First, open the PR view - Press Ctrl+Shift+P → type Pull Requests: Focus on GitHub Pull Requests View → Enter. Then, find a PR - Navigate the tree with arrow keys. Expand a PR to see its changed files. After that, open a diff - Press Enter on a changed file. The diff editor opens. Finally, use the Accessible Diff Viewer - Press F7 to jump to the first change. Your screen reader announces what was added or removed. Press F7 again to move to the next change. Think of it as a rail line: each stop confirms you are still on the right route before the next one.

      +

      Jamie: Before we leave Try It: Review a PR from VS Code, what is the practical point?

      +

      Alex: First, leave a comment - Position your cursor on a line you want to comment on, then press Ctrl+Shift+P → Pull Request: Add Comment on Current Diff Line. Type a brief, constructive comment and submit. Treat it like a recipe: do not add the next ingredient until the previous one is actually in the bowl.

      +
      +

      Alex: Keep the teaching thread moving. Here is the plain-English version of Conducting Pull Request Reviews with a Screen Reader. This guide is focused entirely on the reviewer experience - navigating diffs, reading changes, leaving comments, and submitting a review - using only your keyboard and screen reader. Put another way, for the full pull request lifecycle (opening PRs, merge options, conflict resolution), see Working with Pull Requests. It is like learning a transit route. The names of the stops matter because they tell you whether you are still going the right direction.

      +

      Jamie: What should feel predictable before the first live session starts?

      +

      Alex: This is where Workshop Recommendation (Chapter 15 / Challenge 12) becomes real: chapter 15 is the code review chapter focused on practicing constructive feedback. That matters in practice: It supports Challenge 12: Review Like a Pro.

      +

      Alex: The practical takeaway is this. There are 2 guided challenges. Automation check: none (review quality is subjective and human-focused). The evidence is issue comment with summary of review and feedback posted. The pattern is navigate diff, comment on specifics, submit verdict.

      +

      Jamie: Let's pause on Challenge 12 Practice Set. What should a learner take away from it?

      +

      Alex: Start with Challenge 12 Practice Set. There is something to understand, something to try, and something that proves the try worked.

      +

      Alex: First, review a practice PR and leave 2-3 inline comments - read the diff line by line, find specific items to comment on, and post constructive feedback. Then, submit a formal review verdict - complete your review by choosing approve, request changes, or comment only. It is like walking a hallway with named doors: read the sign, enter the right room, then confirm where you landed.

      +
      +

      Jamie: Let's pause on Practice 12.1 Step-by-Step: Review a PR and Leave Inline Comments. What should a learner take away from it?

      +

      Alex: The reason Practice 12.1 Step-by-Step: Review a PR and Leave Inline Comments matters is that navigate a PR diff using screen reader-friendly tools and post 2-3 specific, constructive inline comments. That gives the learner a simple foothold: GitHub.com (Files changed tab of a PR) or VS Code with the GitHub Pull Requests extension.

      +

      Alex: The practical takeaway is this. On GitHub.com: Use heading navigation to jump between files (H in NVDA). Each file header is a heading. Within a file, use arrow keys to move line by line. In VS Code: Press F7 to open the Accessible Diff Viewer (see Chapter 15, Part 1). Use F7/Shift+F7 to move between changes. Typos or grammar issues. Unclear headings or link text.

      +

      Alex: First, open your Learning Room repository on GitHub.com and navigate to the Pull requests tab. Then, find a classmate's open PR (from Chapter 6, 7, or 14). Open it. After that, activate the Files changed tab. This shows the diff - lines added in green, lines removed in red. Finally, navigate the diff. The rhythm is simple: orient, act, verify, then continue.

      +

      Jamie: Before we leave Practice 12.1 Step-by-Step: Review a PR and Leave Inline Comments, what is the practical point?

      +

      Alex: First, read through the changes carefully. Look. Then, to leave an inline comment on GitHub.com: activate the + button that appears to the left of a line number when you hover or Tab to it. (Screen reader users: this button may be announced as "Add a comment to this line.") Type your comment in the text box that. After that, post 2-3 inline comments. Each comment should be. Finally, examples of good inline comments. Think of it as a rail line: each stop confirms you are still on the right route before the next one.

      +

      Jamie: Let's pause on Practice 12.2 Step-by-Step: Submit a Formal Review Verdict. What should a learner take away from it?

      +

      Alex: Start with Practice 12.2 Step-by-Step: Submit a Formal Review Verdict: Complete your review by selecting a verdict that tells the author what action to take next. The next useful detail is this: GitHub.com (the same PR you reviewed in 14.1). Think of it like entering a new building: first you find the lobby, then the room, then the door you actually need.

      +

      Alex: The practical takeaway is this. Comment - general feedback, no explicit approval or rejection. Approve - you think the PR is ready to merge. Request changes - you found something that should be fixed before merging. If the PR has clear documentation with only minor suggestions, choose Approve.

      +

      Alex: First, after posting your inline comments, scroll to the top of the Files changed tab. Then, activate the Review changes button (at the top-right of the files changed area, or use heading navigation). After that, a dropdown opens with three options. Finally, choose the verdict that matches your review. Think of it as a rail line: each stop confirms you are still on the right route before the next one.

      +

      Jamie: Before we leave Practice 12.2 Step-by-Step: Submit a Formal Review Verdict, what is the practical point?

      +

      Alex: First, write a brief summary in the review body (1-2 sentences). Example: "Clear improvement to the shortcut table. Two minor suggestions for link text clarity.". Then, activate Submit review. Treat it like a recipe: do not add the next ingredient until the previous one is actually in the bowl.

      +

      Jamie: Why is the evidence prompt part of the teaching, not just grading?

      +

      Alex: Here is the plain-English version of Completing Challenge 12: Submit Your Evidence. Open your assigned Challenge 12 issue and post a completion comment. Put another way, close your Challenge 12 issue when done.

      +
      +

      Alex: The practical takeaway is this. Student can navigate PR diffs with a screen reader. Student can post inline comments on specific lines of a diff. Student can write constructive, specific feedback that helps the author improve. Student can submit a formal review verdict.

      +

      Jamie: Let's pause on If You Get Stuck. What should a learner take away from it?

      +

      Alex: Keep the learner anchored in If You Get Stuck. Continue learning: The GitHub Skills courses Review Pull Requests and Code Review with GitHub Copilot cover review workflows and AI-assisted code review. This is the part to say slowly: See Appendix Z for the full catalog.

      +

      Alex: First, files Changed tab will not open? Reload the PR page and retry. Make sure you are on the PR page, not the issue page. Then, cannot find the inline comment button? Tab through the line controls in the diff. The button may be announced as "Add a comment" or have a + label. If you cannot find it, use the "Review changes" button at the top to add a general comment instead. After that, not sure what to comment on? Focus on clarity: is every heading descriptive? Is every link meaningful? Are steps complete? Are keyboard shortcuts correct? Finally, review verdict button not working? Make sure you have at least one comment or have written summary text. Try reloading the page. It is like walking a hallway with named doors: read the sign, enter the right room, then confirm where you landed.

      +

      Jamie: Let's pause on If You Get Stuck. What should a learner take away from it?

      +

      Alex: First, submitting the review fails? Check that you are not in draft mode and have at least read access to the repo. Then, ask facilitator to model one inline comment and one verdict submission. After that, finished but not sure you did it right? Compare your work against the Challenge 12 reference solution. The rhythm is simple: orient, act, verify, then continue.

      +

      Alex: Keep the teaching thread moving. The reason Learning Moment matters is that specific, kind feedback helps authors improve and builds trust in the community. That gives the learner a simple foothold: every comment you write is practice for the professional code review you will do on real projects. The interface gets friendlier when it stops being a wall of controls and starts being a set of named places.

      +
      +

      Jamie: What is the teaching move inside Learning Pattern Used in This Chapter?

      +

      Alex: First, read the full diff before commenting (understand the author's intent first). Then, find specific items to comment on (lines, phrases, missing steps). After that, write comments that help, not just criticize (suggest improvements, note what works). Finally, choose a verdict that matches the substance of your feedback. Think of it as a rail line: each stop confirms you are still on the right route before the next one.

      +

      Jamie: If someone only remembers one thing from Learning Pattern Used in This Chapter, what should it be?

      +

      Alex: First, summarize your overall impression in 1-2 sentences. Treat it like a recipe: do not add the next ingredient until the previous one is actually in the bowl.

      +

      Alex: Keep the teaching thread moving. Here is the plain-English version of Before starting this chapter, verify you have completed. Estimated time for this chapter: 1 hour (including exercises).

      +

      Alex: The practical takeaway is this. [ ] Chapter 6: Working with Pull Requests - Understand PR structure, diffs, and comment workflows. [ ] Chapter 13: GitHub Copilot - VS Code installed and configured. [ ] Screen Reader Setup - NVDA, JAWS, or VoiceOver installed and ready to use. [ ] Access to at least one pull request to review (your own fork or a practice repo).

      +

      Jamie: Let's pause on Two Environments for Code Review. What should a learner take away from it?

      +

      Alex: This is where Two Environments for Code Review becomes real: you can review pull requests in two places - each with different strengths. That matters in practice: Both environments give you full keyboard and screen reader access.

      +
      +

      Jamie: Let's pause on About Learning Cards in This Chapter. What should a learner take away from it?

      +

      Alex: Keep the learner anchored in About Learning Cards in This Chapter. Each review step includes expandable learning cards for different interaction styles. This is the part to say slowly: Open the one that matches how you work. A good GitHub workflow is like a well-run meeting: everyone knows the topic, the next action, and who has the floor.

      +

      Alex: Treat examples as spoken recipes, not decorations. You may hear something like View the full PR diff in your terminal; gh pr diff 42; View PR details (description, status, checks); gh pr view 42; Checkout the PR branch locally for testing; gh pr checkout 42; Approve the PR; gh pr review 42 --approve --body "Heading hierarchy looks. Read the command, understand what it changes, then run it only when the repository state matches the lesson.

      +

      Jamie: Let's pause on Good News: Modern Interface is Default. What should a learner take away from it?

      +

      Alex: The reason Good News: Modern Interface is Default matters is that as of January 2026, GitHub's improved Files Changed experience is enabled by default. That gives the learner a simple foothold: the instructions below assume you have the modern interface (which you do).

      +

      Jamie: Let's pause on Step 1: Reach the Files Changed Tab. What should a learner take away from it?

      +

      Alex: Start with Step 1: Reach the Files Changed Tab: Click the Files changed tab at the top of the PR page. The next useful detail is this: The tab label shows the number of changed files (e.g., "Files changed 4").

      +

      Alex: First, the PR tabs (Conversation, Commits, Checks, Files changed) are across the top of the PR page. At high zoom they may wrap to multiple lines. Then, the Files changed tab includes a badge with the number of changed files. This badge uses text (not colour alone) so it is visible in all themes. After that, after clicking Files changed, the diff page loads. At high zoom, the file tree panel on the left may collapse automatically. Click the file tree toggle (a small panel icon) or press T to toggle it back. Finally, added lines use a green background; removed lines use red. In high contrast browser settings (Windows: Settings Accessibility Contrast themes), these colours map to strong border indicators. Think of it as a rail line: each stop confirms you are still on the right route before the next one.

      +

      Jamie: Before we leave Step 1: Reach the Files Changed Tab, what is the practical point?

      +

      Alex: First, use Ctrl++ to zoom the browser if the diff text is too small, and Ctrl+- to zoom out. Treat it like a recipe: do not add the next ingredient until the previous one is actually in the bowl.

      +

      Alex: Treat examples as spoken recipes, not decorations. You may hear something like Press D → navigate to "Pull request navigation tabs" landmark; Press → or Tab → find "Files changed" link → Enter. Read the command, understand what it changes, then run it only when the repository state matches the lesson.

      +
      +

      Jamie: Let's pause on Step 2: Use the File Tree to Orient Yourself. What should a learner take away from it?

      +

      Alex: Here is the plain-English version of Step 2: Use the File Tree to Orient Yourself. The file tree panel lists every changed file. Put another way, before reading any diff, scan this list to understand the scope of the PR.

      +

      Jamie: Let's pause on What to listen for / look for. What should a learner take away from it?

      +

      Alex: This is where What to listen for / look for becomes real: low vision users (zoom, high contrast). The workshop is closer to rehearsal than lecture. You hear the move, try the move, and then check what changed.

      +

      Alex: The practical takeaway is this. How many files changed? Which areas of the codebase are affected? Are there unexpected files (generated files, lock files, configuration changes)?

      +

      Alex: First, the file tree shows each filename with a colour-coded bar indicating lines added (green) and removed (red). In high contrast mode, these bars may be less visible - the +N / -N text badge next to each file is the reliable indicator. Then, at high zoom, long file paths truncate. Hover over a truncated name to see the full path in a tooltip. After that, if the file tree panel is too narrow at high zoom, drag its right edge to widen it, or toggle it off and use heading navigation (H key) to move between file diffs. It is a checklist, but a meaningful one: every item creates evidence that the next step is safe.

      +

      Jamie: Let's pause on Step 3: Navigate Between File Diffs. What should a learner take away from it?

      +

      Alex: Keep the learner anchored in Step 3: Navigate Between File Diffs. Each changed file in the main area is an h3 heading containing the filename. This is the part to say slowly: Scroll through the page or click a filename in the file tree on the left.

      +

      Alex: Treat examples as spoken recipes, not decorations. You may hear something like Press 3 to jump file-by-file through the diff; Listen for: "learning-room/docs/keyboard-shortcuts.md - collapsed" or "expanded"; Press Enter or Space to expand a collapsed file. Quick Nav H or VO+Cmd+H to jump file-by-file through the diff; Listen for: "learning-room/docs/keyboard-shortcuts.md - collapsed" or "expanded"; VO+Space to expand a collapsed file. Read the command, understand what it changes, then run it only when the repository state matches the lesson.

      -

      Jamie: Let's pause on Step 10: Merge Your Branch (Optional). What should a learner take away from it?

      -

      Alex: Start with Step 10: Merge Your Branch (Optional). There is something to understand, something to try, and something that proves the try worked.

      -

      Alex: The practical takeaway is this. Go to your fork on GitHub. You should see a "Compare & pull request" button. Click it. It shows the template is finalized and tested. If you continue working on this fork, the template is ready for everyone who clones it.

      -

      Alex: First, open an PR for your branch. Then, add a title: feat: add accessibility bug report template. After that, add a description: This template guides contributors to report accessibility issues with clear fields for screen reader type, browser, and WCAG criteria. Finally, click Create pull request. It is a checklist, but a meaningful one: every item creates evidence that the next step is safe.

      -

      Jamie: Before we leave Step 10: Merge Your Branch (Optional), what is the practical point?

      -

      Alex: First, review your PR (using skills from Chapter 14!). Then, if satisfied, click Merge pull request to merge it into your fork's main branch. It is like walking a hallway with named doors: read the sign, enter the right room, then confirm where you landed.

      -

      Jamie: Let's pause on Checkpoint. What should a learner take away from it?

      -

      Alex: Keep the learner anchored in Checkpoint. After completing Steps 1-9, verify.

      -

      Alex: First, you created a file named accessibility-bug.yml in.github/ISSUE TEMPLATE/. Then, the file contains valid YAML (no red squiggles in VS Code). After that, the template is visible when you click "New issue" in your fork. Finally, you tested it with your screen reader and noted any issues. It is like walking a hallway with named doors: read the sign, enter the right room, then confirm where you landed.

      -

      Alex: Keep the teaching thread moving. The reason Exercise C - Submit It Upstream matters is that your Mission: Contribute your tested template to the upstream community-access/accessibility-agents repository. That gives the learner a simple foothold: this is a real open source contribution! The interface gets friendlier when it stops being a wall of controls and starts being a set of named places.

      -

      Alex: The practical takeaway is this. 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.

      +

      Jamie: Let's pause on Step 4: Read a Diff. What should a learner take away from it?

      +

      Alex: The reason Step 4: Read a Diff matters is that low vision users (zoom, high contrast). That gives the learner a simple foothold: screen reader users - VoiceOver (macOS).

      +

      Alex: The practical takeaway is this. Green highlighted lines (with a +) = lines added. Red highlighted lines (with a -) = lines removed. Plain/white lines = unchanged context. Use Ctrl+F to search within the page for specific text in the diff.

      +

      Alex: First, colour is not the only indicator. Every added line has a + character in the gutter; every removed line has a -. These text characters are reliable regardless of colour settings. Then, at high zoom, long lines of code wrap. The +/- gutter character stays at the beginning of the first line, so look left to determine the change type. After that, use Ctrl+F (browser find) to search for specific text across the entire diff page. Finally, if the diff is split view (side by side), it may be very wide at high zoom. Switch to unified diff mode: click the gear icon in the Files Changed toolbar and select "Unified" - this shows old and new in a single column. The rhythm is simple: orient, act, verify, then continue.

      +

      Jamie: Before we leave Step 4: Read a Diff, what is the practical point?

      +

      Alex: First, high contrast themes in Windows (Settings Accessibility Contrast themes) make the +/- lines use bold border patterns instead of subtle colour shading. Think of it as a rail line: each stop confirms you are still on the right route before the next one.

      +

      Alex: Treat examples as spoken recipes, not decorations. You may hear something like Press T to jump to the diff table then Insert+Space (Focus Mode); Press Down Arrow to move through lines one at a time; Press Ctrl+Alt+Right Arrow to read across columns: line number, change type, code content. Press T to jump to the diff table then Insert+Z (Virtual PC Cursor off); Press Down Arrow to move through lines; Press Ctrl+Alt+Right Arrow for column-by-column reading. Read the command, understand what it changes, then run it only when the repository state matches the lesson.

      +

      Jamie: Let's pause on What each line announces / shows. What should a learner take away from it?

      +

      Alex: Start with What each line announces / shows: If the code on a line is very long, the screen reader will read the full line. The next useful detail is this: For minified or generated files, consider collapsing the file in the tree and skipping it.

      +

      Alex: The practical takeaway is this. Added lines: "+ [code content]" - or announced as "inserted". Removed lines: "- [code content]" - or announced as "deleted". Context lines: code without a + or -.

      +

      Jamie: Let's pause on Step 5: Place an Inline Comment. What should a learner take away from it?

      +

      Alex: Here is the plain-English version of Step 5: Place an Inline Comment. When you have a specific observation about a particular line, place an inline comment directly on it. Put another way, screen reader users (VoiceOver - macOS). It is like learning a transit route. The names of the stops matter because they tell you whether you are still going the right direction.

      +

      Alex: First, hover your mouse over a line in the diff - a blue + (comment) button appears on the left. Then, click it to open the inline comment box. After that, type your comment. Finally, click "Start a review" (not "Add single comment" - see note below). Treat it like a recipe: do not add the next ingredient until the previous one is actually in the bowl.

      -

      Jamie: Let's pause on Step 1: Verify Your Template is Ready. What should a learner take away from it?

      -

      Alex: Start with Step 1: Verify Your Template is Ready: Before submitting upstream, make sure your template is production-ready.

      -

      Alex: The practical takeaway is this. All fields display correctly. No broken formatting. Dropdowns work properly. Required fields are marked. The template is clean, no error messages. Every field is functional.

      -

      Alex: First, go to your fork on GitHub. Then, click Issues → New issue. After that, verify your template appears and is named "Accessibility Bug Report". Finally, open it and fill it out once more to confirm. Think of it as a rail line: each stop confirms you are still on the right route before the next one.

      -

      Jamie: Before we leave Step 1: Verify Your Template is Ready, what is the practical point?

      -

      Alex: First, don't submit this test issue - just close the tab. Treat it like a recipe: do not add the next ingredient until the previous one is actually in the bowl.

      -

      Jamie: Let's pause on Step 2: Create the Pull Request. What should a learner take away from it?

      -

      Alex: Start with Step 2: Create the Pull Request. There is something to understand, something to try, and something that proves the try worked.

      -

      Alex: The practical takeaway is this. Click the Code tab. Click the branches dropdown. Select your branch (feat/add-accessibility-template). Click "New pull request" to the right. Base: community-access/accessibility-agents / main (the upstream repo). Head: [your-username]/accessibility-agents / feat/add-accessibility-template (your fork/branch).

      -

      Alex: First, stay on your fork's GitHub page. Then, you should see a "Compare & pull request" button (or look for your feature branch). After that, if that button doesn't appear. Finally, a PR creation page opens showing. Treat it like a recipe: do not add the next ingredient until the previous one is actually in the bowl.

      -

      Jamie: Before we leave Step 2: Create the Pull Request, what is the practical point?

      -

      Alex: First, confirm this is correct - you're sending your branch to the upstream repository. It is a checklist, but a meaningful one: every item creates evidence that the next step is safe.

      -

      Jamie: What should happen before anyone copies and runs it?

      -

      Alex: This is where Step 3: Write Your PR Title and Description becomes real: write a clear description that explains what you're contributing.

      -

      Alex: Treat examples as spoken recipes, not decorations. You may hear something like 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. Read the command, understand what it changes, then run it only when the repository state matches the lesson.

      +

      Jamie: Let's pause on Placing a multi-line comment. What should a learner take away from it?

      +

      Alex: This is where Placing a multi-line comment becomes real: click and drag across multiple line numbers in the diff gutter to select a range. That matters in practice: A comment button appears for the selected range.

      +

      Jamie: Let's pause on Step 6: Read Existing Comments and Threads. What should a learner take away from it?

      +

      Alex: Keep the learner anchored in Step 6: Read Existing Comments and Threads. Inline comments from other reviewers appear as h3 headings within the diff table. This is the part to say slowly: Each thread shows: reviewer username, comment body, replies, a "Reply" link and resolution button.

      +

      Alex: Treat examples as spoken recipes, not decorations. You may hear something like Tab to the "Resolve conversation" button → Enter. Tab to the "Resolve conversation" button → VO+Space. Read the command, understand what it changes, then run it only when the repository state matches the lesson.

      +

      Jamie: Let's pause on Step 7: Submit Your Review. What should a learner take away from it?

      +

      Alex: The reason Step 7: Submit Your Review matters is that screen reader users (VoiceOver - macOS).

      +

      Alex: First, click the "Review changes" button (top-right of the Files Changed page or bottom of the PR). Then, a dialog opens with a summary text area and three radio buttons: Comment / Approve / Request changes. After that, optionally type an overall summary in the text area. Finally, select your verdict. The rhythm is simple: orient, act, verify, then continue.

      +

      Jamie: Before we leave Step 7: Submit Your Review, what is the practical point?

      +

      Alex: First, click "Submit review". Think of it as a rail line: each stop confirms you are still on the right route before the next one.

      -

      Jamie: Let's pause on What to do. What should a learner take away from it?

      -

      Alex: Start with What to do. There is something to understand, something to try, and something that proves the try worked.

      -

      Alex: The practical takeaway is this. 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?

      -

      Alex: First, copy the template above into the description field. Then, edit it with your actual testing experience. After that, keep it concise but thorough. It is like walking a hallway with named doors: read the sign, enter the right room, then confirm where you landed.

      -

      Jamie: Let's pause on Step 4: Review Your PR Before Submitting. What should a learner take away from it?

      -

      Alex: Start with Step 4: Review Your PR Before Submitting. There is something to understand, something to try, and something that proves the try worked.

      -

      Alex: The practical takeaway is this. Is the title clear about what you're adding? Does the description explain the value of this template? Are all checkmarks (``) and formatting visible?

      -

      Alex: First, scroll down and preview your PR description as it will appear. Then, using your screen reader, read through it. After that, make any corrections needed. Finally, do not submit yet - continue to Step 5. The rhythm is simple: orient, act, verify, then continue.

      -

      Jamie: Let's pause on Step 5: Submit the PR. What should a learner take away from it?

      -

      Alex: Start with Step 5: Submit the PR. There is something to understand, something to try, and something that proves the try worked.

      -

      Alex: The practical takeaway is this. 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. Your PR appears in the upstream repository's PR list. You see comments from maintainers (positive feedback = great sign!).

      -

      Alex: First, click the green "Create pull request" button. Then, your PR is now submitted to the upstream repository. After that, you see a confirmation page showing your new PR number (e.g., " 42"). Finally, GitHub may automatically assign reviewers or run CI checks. Think of it as a rail line: each stop confirms you are still on the right route before the next one.

      +

      Jamie: Let's pause on Step 8: Re-request Review (for Authors). What should a learner take away from it?

      +

      Alex: Start with Step 8: Re-request Review (for Authors): After you address review comments on your own PR. The next useful detail is this: Look in the right sidebar for the Reviewers section. Think of it like entering a new building: first you find the lobby, then the room, then the door you actually need.

      +

      Alex: Treat examples as spoken recipes, not decorations. You may hear something like Step 1: From your PR's Conversation tab, Quick Nav H or VO+Cmd+H to find the "Reviewers" heading in the sidebar; Step 2: Tab or Quick Nav B to find the re-request icon ("Re-request review") next to the reviewer's name; Step 3: VO+Space to activate - this. Read the command, understand what it changes, then run it only when the repository state matches the lesson.

      +

      Jamie: Let's pause on Learning Cards: Reviewing on GitHub.com. What should a learner take away from it?

      +

      Alex: Start with Learning Cards: Reviewing on GitHub.com. There is something to understand, something to try, and something that proves the try worked.

      +

      Alex: The practical takeaway is this. In the Files Changed tab, press T to jump to the diff table, then use Focus Mode (Insert+Space in NVDA, Insert+Z in JAWS) and Down Arrow to read line by line -- each added line starts with + and each removed line with -. To place an inline comment, navigate to the target line and press Tab or B to find the "Add a comment to this line" button; after typing your comment, choose "Start a review" (not "Add single comment") to batch all feedback into one notification. Submit your full review by pressing B repeatedly to find the "Review changes" button; the dialog contains a radio group (Comment / Approve / Request changes) navigable with Arrow keys, then Tab to "Submit review". Switch from split diff to unified diff (gear icon in the Files Changed toolbar then select "Unified") to show old and new code in a single column -- much easier to follow at high zoom than two side-by-side panes. The blue + comment button appears in the line gutter on hover; at high zoom it may be small -- use Ctrl++ to increase browser zoom and look just left of the line number column. The "Review changes" dialog uses clearly labeled radio buttons for the three verdict types; each label includes a brief description, and the currently selected option has a filled circle indicator visible in all themes.

      +

      Alex: Keep the teaching thread moving. This is where Reviewing in VS Code with the Accessible Diff Viewer becomes real: when you check out a branch locally, VS Code's diff editor offers the Accessible Diff Viewer - a purpose-built, line-by-line reading mode designed specifically for screen readers.

      +
      +

      Jamie: Let's pause on Opening a Diff in VS Code. What should a learner take away from it?

      +

      Alex: Keep the learner anchored in Opening a Diff in VS Code. If you have the GitHub Pull Requests extension. This is the part to say slowly: Without the extension, any git diff operation also opens the diff editor.

      +

      Alex: First, open the GitHub Pull Requests view (Explorer sidebar or Ctrl+Shift+P → "GitHub Pull Requests: View Pull Request"). Then, find the PR and open it - changed files appear in the file tree. After that, navigate to any file in the tree and press Enter to open its diff view. It is like walking a hallway with named doors: read the sign, enter the right room, then confirm where you landed.

      +

      Jamie: Let's pause on Learning Cards: VS Code Code Review. What should a learner take away from it?

      +

      Alex: The reason Learning Cards: VS Code Code Review matters is that low vision users (zoom, high contrast). That gives the learner a simple foothold: VS Code's diff editor works well at high zoom. The interface gets friendlier when it stops being a wall of controls and starts being a set of named places.

      +

      Alex: First, split view vs. inline: By default, VS Code shows diffs in a split (side-by-side) view. At high zoom this can be very cramped. Switch to inline mode: Ctrl+Shift+P then type "Toggle Inline View" in any diff editor. Inline mode shows old and new code in a single. Then, colour indicators: Added lines have a green gutter bar; removed lines have a red gutter bar. In high contrast themes, these use heavy solid borders that are visible even at extreme zoom levels. After that, change navigation: Press F7 to jump to the next change and Shift+F7 for the previous. Each change is highlighted with a visible focus box that moves with your position - much easier than scrolling at high zoom. Finally, minimap in diff view: The minimap (right edge) shows an overview of changes as coloured blocks. At high zoom the minimap may be too small to be useful - disable it via Settings if it adds visual noise. The rhythm is simple: orient, act, verify, then continue.

      +

      Jamie: Before we leave Learning Cards: VS Code Code Review, what is the practical point?

      +

      Alex: First, font size for diffs: Diff editors use your configured editor font size (editor.fontSize). Increase this in Settings (Ctrl+,) if the diff text is too small at your zoom level. Then, comment highlight: When you add a comment through the GitHub PR extension, the commented line gets a distinct background. In high contrast themes this is a solid colour band. Think of it as a rail line: each stop confirms you are still on the right route before the next one.

      +

      Jamie: Let's pause on Opening the PR for review. What should a learner take away from it?

      +

      Alex: Start with Opening the PR for review. There is something to understand, something to try, and something that proves the try worked.

      +

      Alex: First, press Ctrl+Shift+P, type "GitHub Pull Requests: View Pull Request". Then, the PR tree appears in the sidebar - navigate with Down Arrow. After that, each changed file is announced with its name and change summary. Finally, press Enter on a file to open its diff editor. Think of it as a rail line: each stop confirms you are still on the right route before the next one.

      +

      Jamie: Before we leave Opening the PR for review, what is the practical point?

      +

      Alex: First, the diff editor opens with the standard VS Code diff layout. Treat it like a recipe: do not add the next ingredient until the previous one is actually in the bowl.

      +
      +

      Jamie: Let's pause on Using the Accessible Diff Viewer. What should a learner take away from it?

      +

      Alex: Start with Using the Accessible Diff Viewer. There is something to understand, something to try, and something that proves the try worked.

      +

      Alex: First, in the diff editor, press F7 to open the Accessible Diff Viewer. Then, NVDA announces: "Changed lines X to Y in filename, Change 1 of N". After that, the viewer shows each change with "Removed:" and "Added:" labels. Finally, press F7 to move to the next change, Shift+F7 for previous. Treat it like a recipe: do not add the next ingredient until the previous one is actually in the bowl.

      +

      Jamie: Before we leave Using the Accessible Diff Viewer, what is the practical point?

      +

      Alex: First, press Escape when done to close the viewer. It is a checklist, but a meaningful one: every item creates evidence that the next step is safe.

      +

      Jamie: Let's pause on Placing a comment. What should a learner take away from it?

      +

      Alex: This is where Placing a comment becomes real: screen reader users (VoiceOver on macOS).

      +

      Alex: First, navigate to the line you want to comment on in the diff. Then, press Ctrl+Shift+P, type "GitHub Pull Requests: Add Comment". After that, a text area opens below the line - NVDA announces the input focus. Finally, type your comment. It is a checklist, but a meaningful one: every item creates evidence that the next step is safe.

      +

      Jamie: Before we leave Placing a comment, what is the practical point?

      +

      Alex: First, press Tab to the Submit button, then Enter. It is like walking a hallway with named doors: read the sign, enter the right room, then confirm where you landed.

      +

      Jamie: Let's pause on Opening the PR. What should a learner take away from it?

      +

      Alex: Start with Opening the PR. There is something to understand, something to try, and something that proves the try worked.

      +

      Alex: First, press Cmd+Shift+P, type "GitHub Pull Requests: View Pull Request". Then, navigate the PR tree with VO+Down Arrow. After that, press Return on a file to open its diff. It is like walking a hallway with named doors: read the sign, enter the right room, then confirm where you landed.

      +
      +

      Jamie: Let's pause on Accessible Diff Viewer. What should a learner take away from it?

      +

      Alex: Start with Accessible Diff Viewer. There is something to understand, something to try, and something that proves the try worked.

      +

      Alex: First, press F7 in the diff editor. Then, VoiceOver announces each change with clear "Removed" and "Added" labels. After that, navigate with F7/Shift+F7. Finally, press Escape to close. The rhythm is simple: orient, act, verify, then continue.

      +

      Jamie: Let's pause on Comment placement. What should a learner take away from it?

      +

      Alex: Start with Comment placement. There is something to understand, something to try, and something that proves the try worked.

      +

      Alex: First, press Cmd+Shift+P, type "GitHub Pull Requests: Add Comment". Then, vO+Shift+Down Arrow to interact with the comment text area. After that, type your comment. Finally, vO+Shift+Up Arrow to stop interacting, then Tab to Submit. Think of it as a rail line: each stop confirms you are still on the right route before the next one.

      +

      Jamie: Let's pause on Using the Accessible Diff Viewer (F7). What should a learner take away from it?

      +

      Alex: Here is the plain-English version of Using the Accessible Diff Viewer (F7). The Accessible Diff Viewer reads each change as a structured block. Put another way, this example is from a real Learning Room scenario: a contributor fixing the heading hierarchy in docs/keyboard-shortcuts.md by changing a level-4 heading to level-3, which is exactly what you look for when reviewing Challenge 2 PRs.

      +

      Alex: Treat examples as spoken recipes, not decorations. You may hear something like "Changed lines 14 to 14 in docs/keyboard-shortcuts.md; [Change 1 of 3]; Removed:; NVDA Single-Key Navigation; Added:; NVDA Single-Key Navigation". Read the command, understand what it changes, then run it only when the repository state matches the lesson.

      +
      +

      Alex: Keep the teaching thread moving. Start with Navigation. There is something to understand, something to try, and something that proves the try worked.

      +

      Alex: The practical takeaway is this. F7 - jump to next change (next hunk). Shift+F7 - jump to previous change. Alt+F2 - open VS Code's Accessible View for additional context on the current item. Escape - close the Accessible Diff Viewer.

      +

      Jamie: Let's pause on What makes this better than the raw diff editor. What should a learner take away from it?

      +

      Alex: Start with What makes this better than the raw diff editor. There is something to understand, something to try, and something that proves the try worked.

      +

      Alex: The practical takeaway is this. Each change is announced as a discrete unit with clear "Removed:" and "Added:" labels. You hear the change number of total changes ("Change 3 of 12"). No table navigation required - purpose-built for sequential listening. Works with all three major screen readers without any special configuration.

      +

      Alex: Keep the teaching thread moving. The reason Placing Comments in VS Code (GitHub PR Extension) matters is that from the diff editor with the GitHub PR extension. That gives the learner a simple foothold: comments placed in VS Code sync to GitHub - they appear in the PR's Files Changed tab and the author receives the same notification.

      +
      +

      Jamie: Let's pause on The Anatomy of a Useful Review Comment. What should a learner take away from it?

      +

      Alex: Start with The Anatomy of a Useful Review Comment: A comment that helps the author is.

      +

      Alex: First, specific - link to the exact line and name the pattern you see. Then, educational - say why something matters, not just what to change. After that, graduated - signal whether this is blocking, or a preference. Think of it as a rail line: each stop confirms you are still on the right route before the next one.

      +

      Alex: Keep the teaching thread moving. Here is the plain-English version of Blocking example (reviewing a PR for docs/keyboard-shortcuts.md). "The heading on line 34 uses (level 4) directly after (level 2), skipping heading level 3. Put another way, screen reader users who navigate by heading level will miss any content between those two levels. It is like learning a transit route. The names of the stops matter because they tell you whether you are still going the right direction.

      +

      Jamie: Let's pause on Non-blocking (nit) example (reviewing a PR for docs/welcome.md). What should a learner take away from it?

      +

      Alex: This is where Non-blocking (nit) example (reviewing a PR for docs/welcome.md) becomes real: "nit: The link text in the 'Getting Help' section reads 'click here for more information.' Screen reader users who navigate links out of context will hear only 'click here' with no destination. That matters in practice: Consider 'See the accessibility setup guide' instead.

      +
      +

      Alex: Keep the teaching thread moving. Keep the learner anchored in Question example (reviewing a PR for docs/setup-guide.md). "The PR description says this fixes broken links in the setup guide, but the link on line 12 still points to /docs/old-setup. This is the part to say slowly: Am I reading the diff correctly, or was this link intentionally left?

      +

      Jamie: Let's pause on Prefixes That Set Expectations. What should a learner take away from it?

      +

      Alex: The reason Prefixes That Set Expectations matters is that using shorthand prefixes helps authors parse many comments quickly.

      +

      Alex: Keep the teaching thread moving. Start with How Many Comments Is Too Many?: There is no hard limit, but quantity without prioritization is noise. The next useful detail is this: If you have 15 comments, make clear which 2-3 are blocking. Think of it like entering a new building: first you find the lobby, then the room, then the door you actually need.

      +
      +

      Jamie: Let's pause on "I want to verify the PR only changes what it claims". What should a learner take away from it?

      +

      Alex: Here is the plain-English version of "I want to verify the PR only changes what it claims". Example: A PR says "Challenge 2: Add NVDA shortcut" but the file tree shows changes to both docs/keyboard-shortcuts.md and docs/welcome.md.

      +

      Alex: Keep the teaching thread moving. This is where "I want to find all changes to one specific section" becomes real: example: A PR for Challenge 3 modified docs/welcome.md. That matters in practice: You want to verify the [TODO] in the "Who Can Contribute?" section was filled in correctly.

      +

      Jamie: Let's pause on Exercises. What should a learner take away from it?

      +

      Alex: Keep the learner anchored in Exercises. These exercises use the files in learning-room/docs/ in this repository. This is the part to say slowly: All examples involve documentation changes - no code required.

      +
      +

      Alex: Keep the teaching thread moving. The reason Exercise A - Complete a Web Review matters is that scenario: A contributor has submitted a pull request titled "Add screen reader tips to the setup guide." The PR modifies learning-room/docs/setup-guide.md. That gives the learner a simple foothold: your job is to review it before it merges. The interface gets friendlier when it stops being a wall of controls and starts being a set of named places.

      +

      Jamie: Let's pause on Step 1: Navigate to the Pull Request. What should a learner take away from it?

      +

      Alex: Start with Step 1: Navigate to the Pull Request: How to know you're in the right place.

      +

      Alex: The practical takeaway is this. The PR title is visible at the top. You see a description box with text about what this PR does. You see tabs labeled "Conversation," "Commits," "Files Changed". Use Ctrl+F to search the PR list for "screen reader tips". Or ask in the workshop Slack - someone can share the exact URL.

      +

      Alex: First, open GitHub in your browser and navigate to the workshop repository (github.com/[your-fork]/[workshop-repo] or community-access/accessibility-agents). Then, click the Pull Requests tab (top navigation). After that, look for a PR titled "Add screen reader tips to the setup guide" - click it to open. Finally, you should now see the PR page with sections: Conversation, Commits, Files Changed. Think of it as a rail line: each stop confirms you are still on the right route before the next one.

      +

      Jamie: Let's pause on Step 2: Read the PR Description. What should a learner take away from it?

      +

      Alex: Start with Step 2: Read the PR Description. There is something to understand, something to try, and something that proves the try worked.

      +

      Alex: The practical takeaway is this. Does the PR author explain what file changed? (should mention setup-guide.md). Does it explain why? (should mention "improve accessibility" or "add tips"). Is it clear enough that a reviewer can understand the goal without reading the diff? You can answer: "This PR adds [specific content] to [specific file] because [clear reason]". Example: "This PR adds screen reader usage tips to the setup guide because new users need accessibility guidance".

      +

      Alex: First, you are currently on the Conversation tab. Then, read the PR description (the text immediately under the PR title). After that, look for: "What does this PR change?" and "Why does it change it?". Finally, with screen reader: Navigate to the description with D (NVDA) or press Ctrl+Option+Up (VoiceOver) to find main landmarks, then read the content region. Treat it like a recipe: do not add the next ingredient until the previous one is actually in the bowl.

      +
      +

      Jamie: Let's pause on Step 3: Navigate to "Files Changed". What should a learner take away from it?

      +

      Alex: Start with Step 3: Navigate to "Files Changed". There is something to understand, something to try, and something that proves the try worked.

      +

      Alex: The practical takeaway is this. A section showing the file name setup-guide.md with a small badge showing "+20 −0" (20 lines added, 0 lines removed). Below it, the diff with removed lines (preceded by −) and added lines (preceded by +). Scroll up to see if there are other files. For this exercise, only setup-guide.md should be changed. If you see other files, confirm they are not modified (the badge should show "+0 −0" or no changes).

      +

      Alex: First, click the Files Changed tab (top of the PR page, to the right of "Commits"). Then, you are now viewing the diff. After that, with keyboard (all screen readers): Press T to jump to the diff table. The page focuses on the file comparison area. It is a checklist, but a meaningful one: every item creates evidence that the next step is safe.

      +

      Jamie: Let's pause on Step 4: Activate Focus Mode for Better Diff Reading. What should a learner take away from it?

      +

      Alex: Keep the learner anchored in Step 4: Activate Focus Mode for Better Diff Reading. With screen reader (once in Focus Mode). A good GitHub workflow is like a well-run meeting: everyone knows the topic, the next action, and who has the floor.

      +

      Alex: The practical takeaway is this. The page simplifies: sidebars disappear. Only the diff is visible - easier for screen reader navigation and less cognitive load. The diff is now the main content area. NVDA/JAWS: Press T to jump to the diff table. VoiceOver: Navigate with VO+Right Arrow to find the table/content region. Read through the changes: ↓ arrow moves to each line.

      +

      Alex: First, look for a button labeled "Focus Mode" or an icon (usually at the top right of the diff area). Then, with keyboard: Press F to toggle Focus Mode (may need to be in the diff area first). After that, with mouse: Click the Focus Mode button/icon. It is like walking a hallway with named doors: read the sign, enter the right room, then confirm where you landed.

      +

      Jamie: Let's pause on Step 5: Find the Heading Hierarchy Issue. What should a learner take away from it?

      +

      Alex: Start with Step 5: Find the Heading Hierarchy Issue. There is something to understand, something to try, and something that proves the try worked.

      +

      Alex: The practical takeaway is this. Screen reader users navigate documents by heading level: 1 → 2 → 3 → 4. A skip from to breaks that navigation. When a user presses "jump to heading level 3," they'll find none, wondering if content is missing. You found the line with that violates hierarchy. You can say the line number and what heading text appears there. You understand why this is an accessibility problem.

      +

      Alex: First, read through the entire diff line by line. Pay special attention to lines starting. Then, you are looking for: a line with (four hashes, heading level 4) that comes directly after a (two hashes, heading level 2). After that, when you find it, note the exact line number shown in the diff. The rhythm is simple: orient, act, verify, then continue.

      +
      +

      Jamie: Let's pause on Step 6: Place a Blocking Review Comment on the Heading. What should a learner take away from it?

      +

      Alex: Start with Step 6: Place a Blocking Review Comment on the Heading: If the comment button doesn't appear.

      +

      Alex: The practical takeaway is this. Your comment appears in the thread under that line. The PR author sees it and can make the fix. Make sure you're hovering over the line number area (left side of the line). Try refreshing the page and trying again. Or use the "Add a reply" field at the bottom of the PR and mention the line number manually.

      +

      Alex: First, find the diff line with the problematic heading. Then, hover your mouse over the line number on the left side of that line (or if using keyboard, navigate to that line in the table). After that, a button should appear (or press the Add Comment hotkey - usually C in GitHub). Finally, click it or press Enter to open a comment box. Think of it as a rail line: each stop confirms you are still on the right route before the next one.

      +

      Jamie: Before we leave Step 6: Place a Blocking Review Comment on the Heading, what is the practical point?

      +

      Alex: First, press Space, then explain. Then, click the Comment button (or press Ctrl+Enter for keyboard submit). Treat it like a recipe: do not add the next ingredient until the previous one is actually in the bowl.

      +

      Jamie: Let's pause on Step 7: Find the Link Text Issue. What should a learner take away from it?

      +

      Alex: Start with Step 7: Find the Link Text Issue. There is something to understand, something to try, and something that proves the try worked.

      +

      Alex: The practical takeaway is this. Screen reader users can ask their reader to "list all links on this page" - they hear only the link text. If the text is "click here," they have no context about where it goes. Descriptive link text is WCAG 2.4.4 (Link Purpose). You found a link with non-descriptive text. You can explain why "click here" is bad and what would be better.

      +

      Alex: First, continue reading the diff (from where you left off). Then, look for a line containing link text that reads "click here" or "click here for more information". After that, note the line number. Treat it like a recipe: do not add the next ingredient until the previous one is actually in the bowl.

      +

      Jamie: Let's pause on Step 8: Place a Comment on the Link. What should a learner take away from it?

      +

      Alex: This is where Step 8: Place a Comment on the Link becomes real: nit: means "nice-to-have improvement" (not blocking, but good to fix). The workshop is closer to rehearsal than lecture. You hear the move, try the move, and then check what changed.

      +

      Alex: First, find the line in the diff with the problematic link. Then, hover over the line number and click to open a comment box (or press C). After that, click Comment or press Ctrl+Enter. It is a checklist, but a meaningful one: every item creates evidence that the next step is safe.

      +
      +

      Jamie: Let's pause on Step 9: Submit Your Review. What should a learner take away from it?

      +

      Alex: Start with Step 9: Submit Your Review. There is something to understand, something to try, and something that proves the try worked.

      +

      Alex: The practical takeaway is this. Comment - provide feedback but don't block (for minor notes). Approve - the PR is ready to merge. Request changes - this PR cannot merge until changes are made. Your review is submitted. The PR author gets a notification. The PR shows your review with the two comments.

      +

      Alex: First, look for a button labeled "Review changes" (usually at the top right of the page or bottom of comments). Then, click it (or navigate with keyboard and press Enter). After that, a dialog appears with options. Finally, select "Request changes" (you found two things to fix). It is like walking a hallway with named doors: read the sign, enter the right room, then confirm where you landed.

      +

      Jamie: Before we leave Step 9: Submit Your Review, what is the practical point?

      +

      Alex: First, in the summary field, write: Found 2 accessibility issues that must be fixed before merging. Then, click "Submit review". The rhythm is simple: orient, act, verify, then continue.

      +

      Jamie: Let's pause on Reflect on This Exercise. What should a learner take away from it?

      +

      Alex: The reason Reflect on This Exercise matters is that keep your answers - you'll need them for Chapter 16's Accessibility Agents exercise to compare manual review with agent-assisted review.

      +

      Alex: First, did heading-level navigation help? When you were looking for the issue, was it easier to navigate by heading level (1-6) than to scan every line? Then, would you have caught this without the exercise prompt? If you were a real reviewer not specifically looking for heading issues, would the diff have been obvious? After that, why does screen reader navigation matter? In one sentence, explain why a screen reader user's ability to jump through heading levels is important for this document. The rhythm is simple: orient, act, verify, then continue.

      +

      Jamie: What stays the same when the tool changes?

      +

      Alex: Start with Exercise B - Use the VS Code Accessible Diff Viewer: Scenario: Review the same pull request from Exercise A, this time entirely in VS Code. The next useful detail is this: You'll compare the browser experience with the VS Code experience.

      +
      +

      Alex: Keep the teaching thread moving. Start with Prerequisites. There is something to understand, something to try, and something that proves the try worked.

      +

      Alex: The practical takeaway is this. VS Code must be installed on your machine. The GitHub Pull Requests extension must be installed (see Chapter 12 for installation). You must be signed into GitHub from VS Code (use Ctrl+Shift+P → "GitHub: Sign in").

      +

      Jamie: Let's pause on Step 1: Open the GitHub Pull Requests Extension. What should a learner take away from it?

      +

      Alex: Start with Step 1: Open the GitHub Pull Requests Extension. There is something to understand, something to try, and something that proves the try worked.

      +

      Alex: The practical takeaway is this. With mouse: Click the Extensions icon on the left sidebar (looks like four squares). The extension is listed as active. It mentions: "Review and manage GitHub pull requests and issues".

      +

      Alex: First, open VS Code. Then, with keyboard (all screen readers): Press Ctrl+Shift+X to open the Extensions sidebar. After that, search for "GitHub Pull Requests". Finally, if it's not installed, click Install. It is a checklist, but a meaningful one: every item creates evidence that the next step is safe.

      +

      Jamie: Before we leave Step 1: Open the GitHub Pull Requests Extension, what is the practical point?

      +

      Alex: First, if it is installed, click GitHub Pull Requests to view its details. It is like walking a hallway with named doors: read the sign, enter the right room, then confirm where you landed.

      +

      Jamie: Let's pause on Step 2: Open the Pull Requests Sidebar. What should a learner take away from it?

      +

      Alex: Start with Step 2: Open the Pull Requests Sidebar. There is something to understand, something to try, and something that proves the try worked.

      +

      Alex: The practical takeaway is this. With keyboard: The icon may not be keyboard-reachable directly; instead go to Step 3. VS Code opens a new editor tab for this PR. Below the PR title, you see a "Changes" section listing modified files. You should see setup-guide.md in the changes list. Use Ctrl+Shift+P → search GitHub Pull Requests: Open Pull Request. Paste the PR URL: https://github.com/[owner]/[repo]/pull/[number].

      +

      Alex: First, look for a GitHub-themed icon on the left sidebar (circle with octocat logo) - click it. Then, a sidebar appears showing open pull requests on repositories you have access to. After that, find the PR titled "Add screen reader tips to the setup guide" - it should appear in a list. Finally, click it to open. It is like walking a hallway with named doors: read the sign, enter the right room, then confirm where you landed.

      +
      +

      Jamie: Let's pause on Step 3: View the File Changes. What should a learner take away from it?

      +

      Alex: Start with Step 3: View the File Changes. There is something to understand, something to try, and something that proves the try worked.

      +

      Alex: The practical takeaway is this. A diff editor opens showing two columns. Left: the original file (before changes). Right: the new file (after changes). Different colors show added (green), removed (red), and modified (blue) lines. The file name appears at the top: setup-guide.md. NVDA/JAWS: The editor announces "Diff Editor - setup-guide.md".

      +

      Alex: First, in the Changes section, locate setup-guide.md. Then, click on the filename to open it. The rhythm is simple: orient, act, verify, then continue.

      +

      Jamie: Let's pause on Step 4: Access the Accessible Diff Viewer. What should a learner take away from it?

      +

      Alex: Start with Step 4: Access the Accessible Diff Viewer: If the Accessible Diff Viewer doesn't open. Think of it like entering a new building: first you find the lobby, then the room, then the door you actually need.

      +

      Alex: The practical takeaway is this. With mouse: Look for a button or menu option labeled "Accessible View" or "Open Accessible Diff". If no button is visible, try Alt+F2 (VS Code Accessible View toggle). A new panel opens at the bottom of VS Code. The panel announces each change one at a time. Changes appear in text format with labels: "Added: " and "Removed: ". The panel is read-only (you read the changes, you don't edit here).

      +

      Alex: First, with keyboard: Press F7 to open the Accessible Diff Viewer. Think of it as a rail line: each stop confirms you are still on the right route before the next one.

      +

      Jamie: Let's pause on Step 5: Listen to and Understand the First Change. What should a learner take away from it?

      +

      Alex: Start with Step 5: Listen to and Understand the First Change. There is something to understand, something to try, and something that proves the try worked.

      +

      Alex: The practical takeaway is this. NVDA/JAWS: The Accessible Diff Viewer announces "Removed:" and "Added:" labels, followed by the line content. VoiceOver: The announcement may be similar; listen for "removed" and "added" keywords.

      +

      Alex: First, the first change is automatically announced when you open the Accessible Diff Viewer. Then, let your screen reader read it completely - don't interrupt. After that, write down the exact text announced. Finally, press the Down arrow to move to the next change. Treat it like a recipe: do not add the next ingredient until the previous one is actually in the bowl.

      +
      +

      Jamie: Let's pause on Step 6: Find the Heading Hierarchy Issue. What should a learner take away from it?

      +

      Alex: Start with Step 6: Find the Heading Hierarchy Issue. There is something to understand, something to try, and something that proves the try worked.

      +

      Alex: The practical takeaway is this. Four hashes ( ) indicate a level 4 heading. In the diff, you're looking for it appearing after a level 2 heading ( ). This creates the hierarchy skip you caught in Exercise A. You found the explanation in the Accessible Diff Viewer's format. You can explain: "The added line with directly follows a, skipping level 3". The Accessible Diff Viewer made this pattern clearer than scanning raw + characters.

      +

      Alex: First, continue pressing Down arrow to move through changes. Then, listen carefully for a change involving headings (lines starting with ). After that, specifically, listen for: "Added: " (four hashes). Finally, when you hear this, stop and write it down. It is a checklist, but a meaningful one: every item creates evidence that the next step is safe.

      +

      Jamie: Let's pause on Step 7: Locate the Heading Line and Add an Inline Comment. What should a learner take away from it?

      +

      Alex: Start with Step 7: Locate the Heading Line and Add an Inline Comment. There is something to understand, something to try, and something that proves the try worked.

      +

      Alex: The practical takeaway is this. Use Ctrl+F to open Find. Search for to locate it quickly. Press Enter to jump to it. With keyboard: The comment button may appear on the current line; navigate to it and press Enter. A comment box opens. You can type your comment.

      +

      Alex: First, once you identified the problematic heading in the Accessible Diff Viewer, close the Accessible Diff Viewer (press F7 again or Alt+F2). Then, you're back in the regular Diff Editor. After that, find the line with the problematic heading. Finally, close Find (Escape). It is like walking a hallway with named doors: read the sign, enter the right room, then confirm where you landed.

      +

      Jamie: Before we leave Step 7: Locate the Heading Line and Add an Inline Comment, what is the practical point?

      +

      Alex: First, place your cursor on that line. Then, right-click and select "Add Comment" or press the Comment icon that appears on the left margin. The rhythm is simple: orient, act, verify, then continue.

      +

      Jamie: Let's pause on Step 8: Write Your Accessible Diff Comment. What should a learner take away from it?

      +

      Alex: The reason Step 8: Write Your Accessible Diff Comment matters is that why mention the Accessible Diff Viewer? The interface gets friendlier when it stops being a wall of controls and starts being a set of named places.

      +

      Alex: The practical takeaway is this. It shows that the tool itself helps you see the issue. It documents how you caught the problem (useful for learning).

      +

      Alex: First, in the comment box, type. Then, press Ctrl+Enter or click Comment to submit. The rhythm is simple: orient, act, verify, then continue.

      +
      +

      Jamie: Let's pause on Step 9: Create a GitHub Pull Request Comment. What should a learner take away from it?

      +

      Alex: Start with Step 9: Create a GitHub Pull Request Comment: Now you've reviewed the same PR in.

      +

      Alex: First, browser (Exercise A): You spot-checked line numbers manually. Then, VS Code (Exercise B): The Diff Editor plus Accessible Diff Viewer announced changes. After that, go to GitHub in your browser and open the same PR. Finally, scroll to the bottom and leave a comment in the Conversation tab. Think of it as a rail line: each stop confirms you are still on the right route before the next one.

      +

      Jamie: Before we leave Step 9: Create a GitHub Pull Request Comment, what is the practical point?

      +

      Alex: First, click Comment. Treat it like a recipe: do not add the next ingredient until the previous one is actually in the bowl.

      +

      Jamie: Before we leave Reflect on This Exercise, what is the practical point?

      +

      Alex: Here is the plain-English version of Reflect on This Exercise. After completing Steps 1-9, answer. Put another way, in Chapter 16, you'll compare these manual reviews with the @pr-review agent's suggested changes.

      +

      Alex: First, announcement clarity: Did the "Added:" and "Removed:" labels from the Accessible Diff Viewer help you follow changes faster than reading + and − prefixes in the browser? Then, navigation pattern: Which tool required less back-and-forth clicking/tabbing to understand each change? After that, when would you use each? In one sentence: describe a type of PR where you'd prefer to use each tool. Treat it like a recipe: do not add the next ingredient until the previous one is actually in the bowl.

      +

      Jamie: Let's pause on Exercise C - Compare and Reflect. What should a learner take away from it?

      +

      Alex: This is where Exercise C - Compare and Reflect becomes real: your Mission: Synthesize what you learned from the manual code reviews (Exercises A & B) and document your findings. That matters in practice: What You'll Learn: Which tools work best for different scenarios, and how your manual review skills prepare you to use AI agents effectively.

      +
      +

      Alex: Keep the teaching thread moving. Keep the learner anchored in Step 1: Gather Your Data. Before writing your reflection, collect all the information you gathered. This is the part to say slowly: Write these down (in a text editor, on paper, or mentally) - you'll reference them in Steps 2-4. A good GitHub workflow is like a well-run meeting: everyone knows the topic, the next action, and who has the floor.

      +

      Alex: The practical takeaway is this. Which line number had the heading hierarchy skip? Which line number had the link text issue? How many steps did it take to find each issue? Did you use screen reader commands or visual scanning more?

      +

      Jamie: Let's pause on Step 2: Navigate to the PR and Leave Your Reflection Comment. What should a learner take away from it?

      +

      Alex: Start with Step 2: Navigate to the PR and Leave Your Reflection Comment. There is something to understand, something to try, and something that proves the try worked.

      +

      Alex: The practical takeaway is this. A text editing area with formatting options (Bold, Italic, Link, etc.). A Comment button below the text area.

      +

      Alex: First, go to GitHub in your browser. Then, open the same PR ("Add screen reader tips to the setup guide"). After that, scroll to the Conversation tab. Finally, scroll all the way down to the comment box at the bottom (labeled "Leave a comment" or "Add a comment"). The rhythm is simple: orient, act, verify, then continue.

      +

      Jamie: Before we leave Step 2: Navigate to the PR and Leave Your Reflection Comment, what is the practical point?

      +

      Alex: First, click in the comment box. Think of it as a rail line: each stop confirms you are still on the right route before the next one.

      +

      Alex: Keep the teaching thread moving. Start with Step 3: Write Your Comparison: Type your response to these three questions. The next useful detail is this: Be specific - reference exact tools, steps, and what you discovered.

      +
      +

      Jamie: Let's pause on Step 4: Review Your Comment. What should a learner take away from it?

      +

      Alex: Start with Step 4: Review Your Comment. There is something to understand, something to try, and something that proves the try worked.

      +

      Alex: The practical takeaway is this. Is it clear which tool I preferred? Did I explain why with concrete examples? Am I describing the real-world impact accurately? Would someone else reading this understand how I caught the issue?

      +

      Alex: First, before submitting, re-read your comment using your screen reader or by reading aloud. Then, ask yourself. After that, make any corrections needed. Finally, do not submit yet - continue to Step 5. Treat it like a recipe: do not add the next ingredient until the previous one is actually in the bowl.

      +

      Jamie: Let's pause on Step 5: Submit Your Reflection. What should a learner take away from it?

      +

      Alex: Start with Step 5: Submit Your Reflection. There is something to understand, something to try, and something that proves the try worked.

      +

      Alex: The practical takeaway is this. Your comment is now visible on the PR. Other reviewers can see your comparison. You have completed the three-part exercise series. Your comment appears on the PR thread. It includes all three reflections. The PR author and other reviewers can see your thought process.

      +

      Alex: First, locate the Comment button at the bottom right of the comment box. Then, with keyboard: Press Tab until the Comment button is focused, then Enter. After that, with mouse: Click the Comment button. Finally, your comment is submitted and appears on the PR page. It is a checklist, but a meaningful one: every item creates evidence that the next step is safe.

      +

      Jamie: Let's pause on Step 6: Checkpoint - Validate Your Learning. What should a learner take away from it?

      +

      Alex: Keep the learner anchored in Step 6: Checkpoint - Validate Your Learning. Before moving forward, verify you understand. This is the part to say slowly: If you can answer all three, you're ready for the next chapter.

      +

      Alex: The practical takeaway is this. Expected answer: Something like "Screen readers let users navigate by heading level (pressing 3 jumps to H3), so skipping a level makes users think content is missing.". Expected answer: e.g., "Browser: finding context in discussions. VS Code: linear reading of changes.". Expected answer: Something like "Open the document in a browser, use screen reader heading navigation, and confirm I can reach all levels (H2, H3, H4).".

      +

      Alex: First, heading Hierarchy: Can you explain in one sentence why a → skip breaks screen reader navigation? Then, tool Strengths: For each tool you used, name one task it made easier. After that, real-World Testing: How would you test the heading issue in the published document (not the PR diff)? It is like walking a hallway with named doors: read the sign, enter the right room, then confirm where you landed.

      -

      Jamie: Let's pause on Step 6: Respond to Feedback. What should a learner take away from it?

      -

      Alex: Start with Step 6: Respond to Feedback. There is something to understand, something to try, and something that proves the try worked.

      -

      Alex: The practical takeaway is this. Go back to your fork in VS Code. Edit the accessibility-bug.yml file accordingly. Commit and push. Your changes automatically appear in the PR (linked to the branch). You can leave a polite comment: "Friendly ping - is there anything else needed from my end?".

      -

      Alex: First, read their feedback carefully using your screen reader. Then, understand what changes they're requesting (or what they're praising!). After that, if changes are needed. Finally, leave a reply comment on the PR. Treat it like a recipe: do not add the next ingredient until the previous one is actually in the bowl.

      -

      Jamie: Before we leave Step 6: Respond to Feedback, what is the practical point?

      -

      Alex: First, click Reply. It is a checklist, but a meaningful one: every item creates evidence that the next step is safe.

      -

      Alex: Treat examples as spoken recipes, not decorations. You may hear something like git add.github/ISSUE TEMPLATE/accessibility-bug.yml; git commit -m "Address feedback from maintainers: [brief description]"; git push origin feat/add-accessibility-template. Read the command, understand what it changes, then run it only when the repository state matches the lesson.

      -

      Jamie: Let's pause on Step 7: Celebrate Your Contribution. What should a learner take away from it?

      -

      Alex: This is where Step 7: Celebrate Your Contribution becomes real: -Write down: "I contributed [template name] to an open source project". The workshop is closer to rehearsal than lecture. You hear the move, try the move, and then check what changed.

      -

      Alex: The practical takeaway is this. Take a screenshot of your merged PR. This is valuable experience for your resume and for learning how open source collaboration works.

      -

      Alex: First, you'll see the PR status change to "Merged". Then, your template is now part of the community-access/accessibility-agents repository. After that, everyone who forks that repo will get your template. Finally, you can claim this as a real open source contribution. It is a checklist, but a meaningful one: every item creates evidence that the next step is safe.

      -

      Jamie: Before we leave Checkpoint, what is the practical point?

      -

      Alex: Keep the learner anchored in Checkpoint. After completing Steps 1-7, verify.

      -

      Alex: The practical takeaway is this. 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?

      -

      Alex: First, you created a PR to the upstream repository. Then, your PR includes a clear description of what you're contributing. After that, your template is the only change in the PR (one file). Finally, you addressed any feedback from maintainers. It is like walking a hallway with named doors: read the sign, enter the right room, then confirm where you landed.

      -

      Jamie: What is the teaching move inside Checkpoint?

      -

      Alex: First, your PR was merged (or is waiting for merge). The rhythm is simple: orient, act, verify, then continue.

      +

      Alex: Keep the teaching thread moving. The reason Using GitHub Copilot to Understand Code Changes matters is that reviewing code is about understanding what changed, why it changed, and whether the change is safe and correct. That gives the learner a simple foothold: GitHub Copilot can help you gather and understand information about code changes - especially when diffs are large, complex, or involve unfamiliar frameworks.

      +

      Jamie: Let's pause on When to Use Copilot During Code Review. What should a learner take away from it?

      +

      Alex: Start with When to Use Copilot During Code Review: Copilot is most useful for answering these questions.

      +

      Alex: First, "What does this code do?" - you're reading unfamiliar syntax or a framework you don't know well. Then, "Why might this change break something?" - you need to understand dependencies or side effects. After that, "Is this pattern safe?" - you want to verify that the approach follows best practices. Finally, "What would be a better way to write this?" - you're looking for alternatives to suggest. Think of it as a rail line: each stop confirms you are still on the right route before the next one.

      +

      Jamie: Before we leave When to Use Copilot During Code Review, what is the practical point?

      +

      Alex: First, "Does this match the PR's description?" - the change seems to do more (or less) than claimed. Treat it like a recipe: do not add the next ingredient until the previous one is actually in the bowl.

      +

      Jamie: Let's pause on In VS Code with an Open Diff. What should a learner take away from it?

      +

      Alex: Start with In VS Code with an Open Diff. There is something to understand, something to try, and something that proves the try worked.

      +

      Alex: First, open the PR using the GitHub Pull Requests extension (see Part 2). Then, open the diff for any file. After that, select a block of code that confuses you (highlight it). Finally, open Copilot Chat: Ctrl+Shift+I. Treat it like a recipe: do not add the next ingredient until the previous one is actually in the bowl.

      +

      Jamie: Before we leave In VS Code with an Open Diff, what is the practical point?

      +

      Alex: First, Copilot reads the selected code and answers in the chat. It is a checklist, but a meaningful one: every item creates evidence that the next step is safe.

      -

      Alex: Keep the teaching thread moving. The reason Exercise D - Design a Template for Your Own Project matters is that your Mission: Apply everything you've learned to design a template for a repository you own, maintain, or plan to create. That gives the learner a simple foothold: what You'll Learn: How to make design decisions about required vs.

      -

      Jamie: Let's pause on Part 1: Choose Your Project. What should a learner take away from it?

      -

      Alex: Start with Choose Your Project. There is something to understand, something to try, and something that proves the try worked.

      -

      Alex: The practical takeaway is this. 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. You have a specific project in mind (not generic). You can articulate why you care about it.

      -

      Alex: First, think of a repository you have a personal connection to. Then, write down the project name and briefly why chose it. Think of it as a rail line: each stop confirms you are still on the right route before the next one.

      -

      Jamie: Let's pause on Part 2: Identify Issue Patterns. What should a learner take away from it?

      -

      Alex: Here is the plain-English version of Identify Issue Patterns. Your task: Study the issues your project receives (or would receive) to understand what information is most valuable. Put another way, if your project doesn't exist yet or has no issues. It is like learning a transit route. The names of the stops matter because they tell you whether you are still going the right direction.

      -

      Alex: The practical takeaway is this. 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? Bug reports?

      -

      Alex: First, open your issue list in GitHub. Then, read the last 5-10 issues (or all open issues if fewer). After that, for each issue, ask yourself. Finally, write down 3-5 patterns. Treat it like a recipe: do not add the next ingredient until the previous one is actually in the bowl.

      -

      Jamie: Before we leave Part 2: Identify Issue Patterns, what is the practical point?

      -

      Alex: First, think about the type of issues you'd want to receive. Then, for each type, ask: "If someone reported this issue, what would I need to know?". After that, write down. It is a checklist, but a meaningful one: every item creates evidence that the next step is safe.

      +

      Jamie: Let's pause on On GitHub.com (Web Interface). What should a learner take away from it?

      +

      Alex: This is where On GitHub.com (Web Interface) becomes real: another option: Use the GitHub Copilot inline suggestions on GitHub.com.

      +

      Alex: The practical takeaway is this. Some GitHub PRs show Copilot insights directly in the diff (as of early 2026). If you see a lightbulb icon, click it to see Copilot's suggestion about that line.

      +

      Alex: First, open the PR's Files Changed tab. Then, focus on a line or section you want to understand better. After that, in VS Code Copilot Chat (not in the browser - Copilot Chat doesn't work directly in browser diffs yet). Finally, copy the confusing code, paste it into chat, and ask Copilot to explain. It is a checklist, but a meaningful one: every item creates evidence that the next step is safe.

      +

      Alex: Keep the teaching thread moving. Keep the learner anchored in Copilot Limitations During Review (Critical to Know). This is why manual review is essential: You have context (project history, team decisions, user impact) that Copilot does not. This is the part to say slowly: Use Copilot to understand, then use your judgment to decide.

      +

      Alex: The practical takeaway is this. See the whole project - it sees only what you show it (the selected diff, not the context of the entire codebase). Verify correctness - it can explain what code does, but not whether it's correct for your specific use case. Understand intent - it reads the code, not the author's mind or the PR description. Catch all risks - it can spot common patterns, but not edge cases unique to your project.

      +

      Jamie: Let's pause on Best Practices. What should a learner take away from it?

      +

      Alex: Start with Best Practices. There is something to understand, something to try, and something that proves the try worked.

      +

      Alex: First, read the diff manually first - you spot the big picture before asking Copilot details. Then, ask Copilot specific questions - not "review this code" but "does this regex handle Unicode?". After that, fact-check Copilot's answers - it can be confidently wrong, especially about frameworks or domains it has less training data. Finally, combine Copilot with manual analysis - ask Copilot to explain, then verify by checking the PR description or looking for related files. The rhythm is simple: orient, act, verify, then continue.

      +

      Jamie: Before we leave Best Practices, what is the practical point?

      +

      Alex: First, use Copilot to draft comments - type Draft a comment about [issue] for this PR and edit Copilot's suggestion to match your tone. Think of it as a rail line: each stop confirms you are still on the right route before the next one.

      -

      Jamie: Let's pause on Part 3: Design Your Required Fields. What should a learner take away from it?

      -

      Alex: This is where Design Your Required Fields becomes real: your task: List the fields you absolutely need to understand an issue. That matters in practice: Rule: Keep required fields minimal.

      -

      Alex: The practical takeaway is this. You have 2-4 required fields. Each has a clear reason (not arbitrary). You can explain to someone why each field is required.

      -

      Alex: First, create a table. Then, for each issue type from Part 2, add 2-4 required fields. After that, write down at least 2 required fields. It is a checklist, but a meaningful one: every item creates evidence that the next step is safe.

      -

      Jamie: Let's pause on Part 4: Design Your Optional Fields. What should a learner take away from it?

      -

      Alex: Keep the learner anchored in Design Your Optional Fields. Your task: Add optional fields that would be helpful but aren't blocking.

      -

      Alex: The practical takeaway is this. Information that's helpful but you could triage without it. Information that helps you prioritize or assign the issue. Information that provides missing context. Environment details (CPU, RAM, versions of dependencies). Screenshots or links. Workarounds the reporter has found.

      -

      Alex: First, brainstorm nice-to-have information. Then, example optional fields for a bug report. After that, write down at least 2 optional fields. Finally, for each field, decide. It is like walking a hallway with named doors: read the sign, enter the right room, then confirm where you landed.

      -

      Jamie: Let's pause on Part 5: Write Field Placeholders and Help Text. What should a learner take away from it?

      -

      Alex: The reason Write Field Placeholders and Help Text matters is that your task: For each field, write helpful placeholder or description text that guides the reporter. That gives the learner a simple foothold: for each required and optional field, draft.

      -

      Alex: The practical takeaway is this. 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.

      -

      Alex: First, field label (the visible name). Then, description (short help text). After that, placeholder (example of what to type, for input/textarea fields). The rhythm is simple: orient, act, verify, then continue.

      +

      Alex: Keep the teaching thread moving. Start with What Comes Next: Your manual code review skills - identifying heading issues, catching link text problems, understanding screen reader navigation, gathering information with Copilot - are the foundation for understanding automated review. The next useful detail is this: In Chapter 16 (Accessibility Agents), you'll meet a full team of agents designed to amplify these skills. Think of it like entering a new building: first you find the lobby, then the room, then the door you actually need.

      +

      Jamie: Let's pause on Part 4: The Reviewer's Craft. What should a learner take away from it?

      +

      Alex: Here is the plain-English version of The Reviewer's Craft. Parts 1 through 3 taught you the mechanics -- how to read diffs, leave comments, and use Copilot to understand unfamiliar code. Put another way, this part covers something equally important: how to think like a reviewer.

      +

      Alex: Keep the teaching thread moving. This is where What to Look for in a Review becomes real: every PR is different, but most reviews benefit from scanning across these five categories. That matters in practice: You do not need to check every category exhaustively on every PR.

      -

      Jamie: Let's pause on Part 6: Test Your Template Locally. What should a learner take away from it?

      -

      Alex: Start with Test Your Template Locally: Your task: Create a draft YAML template file and test it with your screen reader. Think of it like entering a new building: first you find the lobby, then the room, then the door you actually need.

      -

      Alex: The practical takeaway is this. Start with the frontmatter (name:, description:, title:, labels:). Add your fields in the body: section. Use appropriate field types (input, textarea, dropdown, checkboxes). Name it: [your-project-name]-template.yml. Save it to your desktop or a projects folder. Is the YAML syntax correct? (no red squiggles).

      -

      Alex: First, create a text file with your template in YAML format. Use Section 6 as a template. Then, save it locally (not yet in GitHub). After that, open it in VS Code and check. Finally, test the structure. Think of it as a rail line: each stop confirms you are still on the right route before the next one.

      -

      Jamie: Before we leave Part 6: Test Your Template Locally, what is the practical point?

      -

      Alex: First, with your screen reader. Treat it like a recipe: do not add the next ingredient until the previous one is actually in the bowl.

      -

      Jamie: Let's pause on Part 7: (Optional) Deploy to GitHub and Test with a Friend. What should a learner take away from it?

      -

      Alex: Here is the plain-English version of (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. Put another way, this is optional but powerful - real user testing is the best validation.

      -

      Alex: The practical takeaway is this. Create a test branch in a personal repo. Add your template file to.github/ISSUE TEMPLATE/. Push the branch. "Could you try filing an issue using this template?".

      -

      Alex: First, upload your template to a test repository. Then, ask a colleague or friend. After that, collect feedback. Finally, refine your template based on their feedback. Treat it like a recipe: do not add the next ingredient until the previous one is actually in the bowl.

      -

      Jamie: Let's pause on Part 8: Reflect on Your Template Design. What should a learner take away from it?

      -

      Alex: This is where Reflect on Your Template Design becomes real: your task: Document what you learned from this exercise.

      -

      Alex: The practical takeaway is this. 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.

      -

      Alex: First, decision-making: Which field did you debate including? Why did you finally decide yes or no? Then, trade-offs: You can't ask for everything without overwhelming reporters. What information did you choose not to ask for? Why? After that, iteration: If you had user feedback (from Part 7), what did you learn? Finally, real-world readiness: Would you actually deploy this template to a real project? It is a checklist, but a meaningful one: every item creates evidence that the next step is safe.

      +

      Jamie: Let's pause on The Three Review Actions. What should a learner take away from it?

      +

      Alex: Keep the learner anchored in The Three Review Actions. When you submit a review on GitHub, you choose one of three actions. This is the part to say slowly: Picking the right one matters because it signals your intent to the author and to anyone else watching the PR.

      +

      Alex: First, did you find a bug, security issue, or broken test? -- Request Changes. Then, does the code do something different from what the description says? -- Request Changes. After that, does everything work, with maybe a few style nits? -- Approve (mention the nits in a comment). Finally, do you have questions or optional suggestions? -- Comment. It is like walking a hallway with named doors: read the sign, enter the right room, then confirm where you landed.

      +

      Alex: Keep the teaching thread moving. The reason Writing Constructive Feedback matters is that the way you phrase feedback determines whether the author feels supported or attacked. That gives the learner a simple foothold: before pointing out problems, acknowledge something the author did well. The interface gets friendlier when it stops being a wall of controls and starts being a set of named places.

      +

      Jamie: Let's pause on The Reviewer's Checklist. What should a learner take away from it?

      +

      Alex: Start with The Reviewer's Checklist: Run through this list mentally (or copy it into your notes) for every PR you review.

      +

      Alex: The practical takeaway is this. [ ] I read the PR description before reading the code. [ ] The code does what the description says it does. [ ] The change does not include unrelated modifications. [ ] Variable and function names are clear. [ ] I checked for accessibility: labels, headings, keyboard reach, contrast. [ ] I verified no existing behavior is broken by the change.

      -

      Jamie: If someone only remembers one thing from Checkpoint, what should it be?

      -

      Alex: Keep the learner anchored in Checkpoint. After completing Parts 1-8, you have. This is the part to say slowly: You now understand the thinking that separates "a blank text box" from "structured, actionable contributions.".

      -

      Alex: The practical takeaway is this. Chosen a specific project to design. Identified issue patterns and common questions. Designed required fields (minimal, crucial information). Designed optional fields (helpful but not blocking).

      -

      Jamie: Let's pause on You've Completed the Template Exercises. What should a learner take away from it?

      -

      Alex: The reason You've Completed the Template Exercises matters is that 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. That gives the learner a simple foothold: the agent generates YAML; you decide what questions to ask. The interface gets friendlier when it stops being a wall of controls and starts being a set of named places.

      -

      Alex: First, understand templates from the user perspective (Exercise A). Then, can create and deploy templates yourself (Exercise B). After that, know how to contribute upstream (Exercise C). Finally, can design templates with real thinking behind them (Exercise D). The rhythm is simple: orient, act, verify, then continue.

      -

      Jamie: How should they picture the shape of the workshop?

      -

      Alex: Start with 10. Day 2 Amplifier: The Template Builder Agent: Everything you just learned - field types, YAML structure, accessibility testing - is core GitHub knowledge. The next useful detail is this: Now see how Accessibility Agents amplifies it.

      +

      Alex: Keep the teaching thread moving. Here is the plain-English version of Reviewing as a Learning Tool. Reviewing is not just a gate to keep bad code out. Put another way, it is one of the fastest ways to grow as a developer.

      +

      Jamie: Let's pause on Learning Cards: The Reviewer's Craft. What should a learner take away from it?

      +

      Alex: Start with Learning Cards: The Reviewer's Craft. There is something to understand, something to try, and something that proves the try worked.

      +

      Alex: The practical takeaway is this. Jump between changed hunks in a diff with Alt+F5 (next change) and Shift+Alt+F5 (previous change) to scan for scope creep efficiently. Use Alt+F2 (Accessible View) on a Copilot-generated review summary to read the full text with arrow keys before posting. When leaving feedback, mention specific line numbers ("Line 42 skips from h2 to h4") so the author can navigate directly with Ctrl+G. The three review actions (Approve, Request Changes, Comment) are shown as clearly labeled radio buttons in the review submission form. Use the reviewer checklist in this section as a mental framework -- copy it into your notes and check items off as you review each PR. The diff view uses green and red backgrounds for added/removed lines; pair with a High Contrast theme if these colors are hard to distinguish.

      +

      Alex: Keep the teaching thread moving. Keep the learner anchored in Day 2 Teaser: The Full Accessibility Agents Review Ecosystem. Chapter 16 shows you how to leverage 50+ specialized agents to make your reviews faster, more consistent, and more thorough - while staying in full control of what you post. A good GitHub workflow is like a well-run meeting: everyone knows the topic, the next action, and who has the floor.

      -

      Alex: Keep the teaching thread moving. Here is the plain-English version of In VS Code. Then you copy, paste to.github/ISSUE TEMPLATE/your-template.yml, commit, and done.

      -

      Jamie: Let's pause on Why It Matters. What should a learner take away from it?

      -

      Alex: This is where Why It Matters becomes real: the Template Builder does not teach you to design templates - Section 5 taught you that. That matters in practice: It automates the mechanical part: translating your decisions into working YAML.

      -

      Alex: Keep the teaching thread moving. Keep the learner anchored in Using the Template Builder. Next: Chapter 18: Fork and Contribute Back: Chapter 16: GitHub Copilot Related appendices: Appendix Q: GitHub Actions Appendix C: Markdown Reference. A good GitHub workflow is like a well-run meeting: everyone knows the topic, the next action, and who has the floor.

      +

      Jamie: What do we want them to notice before they start over?

      +

      Alex: The reason The Agents That Help With Code Review matters is that accessibility Review Agents (when code affects UI/UX).

      +

      Alex: The practical takeaway is this. @pr-review - Generates a full-draft PR review with line-numbered diff maps, risk assessment, before/after snapshots, and suggested inline comments. You edit and post it under your name. @pr-author-checklist - Before you even submit your PR, use this to verify you haven't missed setup steps, accessibility checks, or documentation. @insiders-a11y-tracker - Monitors your PR for accessibility-sensitive changes: WCAG violations, heading hierarchy issues, link text quality, keyboard navigation impacts. @developer-hub - Orchestrates explanations for unfamiliar code, patterns, or frameworks you're reviewing. @python-specialist - If your PR contains Python code, this agent explains patterns, spots accessibility issues, and suggests improvements. @wxpython-specialist - For desktop GUI code, helps verify accessible widget patterns and focus management.

      +

      Jamie: Let's pause on How It Works. What should a learner take away from it?

      +

      Alex: First, review manually first (you just did this with Exercises A, B, C). Then, run an agent - @pr-review review PR 14 generates a draft in seconds. After that, edit the agent's draft - you add context, remove noise, correct errors. Finally, post your review - it now has both AI efficiency and your human judgment. Think of it as a rail line: each stop confirms you are still on the right route before the next one.

      +

      Jamie: Before we leave How It Works, what is the practical point?

      +

      Alex: First, the agent tracks impact - @insiders-a11y-tracker monitors whether your accessibility feedback was addressed. Treat it like a recipe: do not add the next ingredient until the previous one is actually in the bowl.

      +

      Jamie: Let's pause on The Principle: Skill First, Agent Second. What should a learner take away from it?

      +

      Alex: Here is the plain-English version of The Principle: Skill First, Agent Second. Why do this manually before using agents? Put another way, manual reviews teach you what to look for.

      +

      Alex: The practical takeaway is this. You understand what the agent is doing (you did it manually). You evaluate the agent's output critically (you know what right looks like). You add judgment the agent lacks (context, intent, team decisions). You verify the agent didn't miss anything important.

      +
      +

      Jamie: Let's pause on A Real Example: The Flow. What should a learner take away from it?

      +

      Alex: This is where A Real Example: The Flow becomes real: manual Review (your work in part 1-2). That matters in practice: Agent-Assisted Review (what you'll do in Chapter 19). The workshop is closer to rehearsal than lecture. You hear the move, try the move, and then check what changed.

      +

      Alex: The practical takeaway is this. Read diff, identify heading hierarchy skip. Write comment explaining why it matters. Submit your verdict.

      +

      Alex: First, run: @pr-review review PR 14. Then, agent generates a draft review covering the heading skip, link text, and 5 other issues. After that, you read the draft and notice: "the agent's explanation of the heading skip is good, but it missed that the link text on line 23 is still vague. Let me add that.". Finally, you post the agent's review + your additions. It is a checklist, but a meaningful one: every item creates evidence that the next step is safe.

      +

      Jamie: Before we leave A Real Example: The Flow, what is the practical point?

      +

      Alex: First, next time you review a similar PR, the agent works faster because it learned from your feedback. It is like walking a hallway with named doors: read the sign, enter the right room, then confirm where you landed.

      Jamie: What is the final checkpoint?

      Alex: You should be able to point to the evidence, explain the action, and describe what you would do next if this were a real open source project. If you can teach the move back, you have learned it.

      @@ -18845,3776 +19051,3713 @@

      Transcript

      -

      Challenge 15: Meet the Agents

      -

      Exploring agent files, running agents carefully, and verifying AI output against manual skill.

      +

      Reference and Next Steps

      +

      55. Episode 20: Accessibility Standards Reference

      +

      WCAG 2.2, ARIA roles, and the PR accessibility checklist.

      +

      Based on: Appendix M: Accessibility Standards Reference

      +

      Audio and transcript are being regenerated for this episode.

      -Read Transcript - Challenge 15: Meet the Agents +Read Transcript - Episode 20: Accessibility Standards Reference

      Transcript

      -

      Alex: You are listening to Challenge Coach: Meet the Agents. I am Alex, and this is the calm walkthrough before the hands-on work.

      -

      Jamie: And I am Jamie. I will make sure we teach the skill instead of just reading the checklist aloud.

      +

      Alex: Welcome to Git Going with GitHub, episode 20: Accessibility Standards Reference. I am Alex. Today we are going to make Accessibility Standards Reference something you can explain, practice, and recover from when the interface surprises you.

      +

      Jamie: And I am Jamie. I will be the voice of the learner who is willing to ask, what is this for, where am I, and how do I know I did it right?

      -

      Alex: The focus is Exploring agent files, running agents carefully, and verifying AI output against manual skill. We will explain the concept, the action, the evidence, and the most common recovery path.

      -

      Jamie: So the learner needs the why, the move, and the checkpoint all in the same mental pocket.

      -

      Alex: That is the teaching shape: understand the concept, do the smallest real action, then verify the result before moving on.

      +

      Alex: The big idea today: WCAG 2.2, ARIA roles, and the PR accessibility checklist. We will name the concept, explain why it matters, practice the move, and point out the checks that tell you the work is real.

      +

      Jamie: So the episode should work even if someone has not read the chapter yet.

      +

      Alex: Exactly. The transcript has to stand on its own. It can point toward practice, but it should teach the concept right here in the conversation.

      -

      Jamie: What makes this practice feel low-stakes but still real?

      -

      Alex: Start with Challenge 15: Meet the Agents: What you will do: Explore the accessibility-agents repository, discover what agents are available, run one agent, and read one agent's.agent.md file to understand how it works.

      -

      Jamie: How would you walk the room through that step by step?

      -

      Alex: Start with Instructions. There is something to understand, something to try, and something that proves the try worked.

      -

      Alex: The practical anchors are these. Using a slash command in GitHub Copilot Chat. Invoking an agent through the VS Code command palette. Following the usage instructions in the agent's README. What is the agent's purpose? What are its responsibilities? What are its guardrails (things it should NOT do)?

      -

      Alex: First, discover -- Browse the accessibility-agents repository and find at least 3 different agents. Note their names and what they do. Then, run -- Choose one agent and try it out. This might mean. After that, read -- Open one agent's.agent.md file. Identify. Treat it like a recipe: do not add the next ingredient until the previous one is actually in the bowl.

      +

      Jamie: Okay, set the room for us. What are we walking into?

      +

      Alex: Start with WCAG, ARIA, and What They Mean for Your Contributions: This appendix gives you a working understanding of the accessibility standards that govern the web, GitHub's interface, and the projects you will contribute to. The next useful detail is this: You do not need to memorize these - use this as a lookup when a PR review mentions a specific standard or success criterion.

      +

      Alex: The next layer is this. Here is the plain-English version of 1. WCAG 2.2 - The Four Principles. WCAG (Web Content Accessibility Guidelines) is organized around four principles, often abbreviated POUR. Put another way, every WCAG success criterion belongs to one of these four principles. It is like learning a transit route. The names of the stops matter because they tell you whether you are still going the right direction.

      +

      Alex: A solid pull request habit is to separate three questions: what changed, why it changed, and what still needs review. That keeps the conversation useful instead of noisy.

      Jamie: What is the one idea that makes the next few steps less mysterious?

      -

      Alex: This is where What to look for in an.agent.md file becomes real: every agent file follows a pattern. That matters in practice: Its purpose is., its guardrails include.

      -

      Alex: That shows up in the workshop in a few specific ways. YAML frontmatter at the top: metadata like name, description, tools. Responsibilities section: what the agent is designed to do. Guardrails section: boundaries that keep the agent safe and focused.

      +

      Alex: Start with Learning Cards: WCAG Overview. There is something to understand, something to try, and something that proves the try worked.

      +

      Alex: That shows up in the workshop in a few specific ways. WCAG is organized around four principles: Perceivable, Operable, Understandable, Robust (POUR) -- use this mnemonic when reviewing any PR. Most projects target WCAG 2.2 AA -- when a reviewer cites a criterion number like 1.4.3, search the tables in Section 3 of this appendix. The WCAG Quick Reference (Section 10) is a filterable web page -- use your screen reader's find command to jump to any criterion number. The tables in this appendix use pipe-delimited Markdown -- increase your editor font size or use a Markdown preview for cleaner column alignment. WCAG 1.4.3 (contrast) and 1.4.11 (non-text contrast) are the criteria most relevant to your daily experience -- bookmark them. When checking contrast ratios, use the WebAIM Contrast Checker link in Section 10 with your browser zoom set to your preferred level.

      -

      Alex: Now bring the learner back to the room. Keep the learner anchored in Peer simulation check. Compare your agent discoveries with the peer-simulation issue or with a real buddy if you have access. This is the part to say slowly: Did you find different agents or different use cases?

      +

      Alex: Now bring the learner back to the room. Keep the learner anchored in 2. Conformance Levels: A, AA, AAA. Most open source projects, and GitHub itself, target WCAG 2.2 AA compliance. This is the part to say slowly: When you file an accessibility bug or review a PR, AA is the standard to reference.

      Jamie: What would you say to someone who is already bracing for this to be too much?

      -

      Alex: The reason Agent 1: accessibility-lead matters is that location.github/agents/accessibility-lead.agent.md. That gives the learner a simple foothold: purpose: Coordinates accessibility reviews across the team.

      +

      Alex: The reason 3. Key Success Criteria for Web Contributions matters is that these are the criteria you will most commonly encounter when contributing to web projects or reviewing GitHub interface changes.

      Alex: The useful habit is simple: orient first, act second, verify third. That pause before acting is part of the work.

      -

      Alex: That matters because of the next idea. Start with Agent 2: aria-specialist: Location.github/agents/aria-specialist.agent.md. The next useful detail is this: Purpose: Reviews ARIA (Accessible Rich Internet Applications) attributes in HTML and web components. Think of it like entering a new building: first you find the lobby, then the room, then the door you actually need.

      +

      Alex: That matters because of the next idea. Start with 4. ARIA - Roles, States, and Properties: WAI-ARIA (Accessible Rich Internet Applications) fills the gap between what HTML natively expresses and what complex interactive widgets require. Think of it like entering a new building: first you find the lobby, then the room, then the door you actually need.

      -

      Jamie: Okay, set the room for us. What are we walking into?

      -

      Alex: Here is the plain-English version of Agent 3: keyboard-navigator. Location.github/agents/keyboard-navigator.agent.md. Put another way, purpose: Ensures that all interactive elements are operable by keyboard.

      +

      Jamie: How would you walk the room through that step by step?

      +

      Alex: Start with Important rules. There is something to understand, something to try, and something that proves the try worked.

      +

      Alex: First, don't use ARIA if native HTML suffices. A is already a button - adding role="button" to a is only needed when HTML semantics cannot be used. Then, all interactive ARIA widgets must be keyboard operable. Adding role="button" means you must also handle Enter and Space keypresses in JavaScript. After that, aRIA only affects the accessibility tree. It does not add visual styling or behavior - it only changes what assistive technologies announce. Treat it like a recipe: do not add the next ingredient until the previous one is actually in the bowl.

      +

      Alex: This is where the talk moves from concept to action. This is where 5. ARIA Landmark Roles becomes real: landmarks let screen reader users jump directly to major sections of a page. That matters in practice: GitHub uses these extensively; screen reader users navigate between them with D (NVDA/JAWS) or the Rotor (VoiceOver).

      Alex: A solid navigation habit is to prove where you are before activating controls. Headings, landmarks, and the address bar are not trivia; they are your map.

      -

      Alex: This is where the talk moves from concept to action. This is where Example: Running an agent becomes real: what I asked: "@accessibility-lead review the heading structure of this file". That matters in practice: What it did: The lead agent delegated to the alt-text-headings specialist, which analyzed the heading levels and reported that the file skipped from H2 to H4.

      Jamie: Where do you want a learner to place their attention here?

      -

      Alex: Keep the learner anchored in Example: Reading agent instructions. Looking at the.agent.md file structure.

      -

      Alex: These are the details that keep the idea from floating away. YAML frontmatter: Contains the agent name, description, and tool restrictions. Responsibilities section: Lists what the agent is designed to do. Guardrails section: Lists what the agent should NOT do or cannot do reliably.

      +

      Alex: Keep the learner anchored in Live Region (status announcements). Use aria-live="assertive" only for urgent interruptions (errors). This is the part to say slowly: Use "polite" for non-urgent status updates.

      -

      Alex: Before the learner moves on. The reason What matters matters is that the learning objective is understanding that AI agents are configurable tools with defined boundaries. That gives the learner a simple foothold: if you examined at least one agent's instructions and can explain what it does and what it will not do, you completed this challenge. The interface gets friendlier when it stops being a wall of controls and starts being a set of named places.

      +

      Alex: Before the learner moves on. The reason Expandable Section matters is that when expanded: set aria-expanded="true" and remove the hidden attribute. The interface gets friendlier when it stops being a wall of controls and starts being a set of named places.

      Jamie: Give me the version that sounds like an instructor, not a manual.

      -

      Alex: Start with 55 AI Agents Across 3 Teams and 5 Platforms: Day 2, Block 3 Material Before you read this guide: Accessibility Agents is a growing open source ecosystem: 55 AI-powered agents organized into three teams (Accessibility, GitHub Workflow, and Developer Tools), running on five platforms (GitHub Copilot,. The next useful detail is this: This chapter introduces the full landscape.

      -

      Alex: Hold that next to this. Start with Core Prerequisites (Required for All Agents). There is something to understand, something to try, and something that proves the try worked.

      -

      Alex: For a learner, the useful signals are these. [ ] Chapter 0: Pre-Workshop Setup - Git, VS Code, and GitHub account. [ ] Chapter 16: GitHub Copilot - GitHub Copilot Chat installed and working. [ ] GitHub Copilot access (Copilot Free tier is enough for this workshop). [ ].github/agents/ folder exists in your repository (or will create custom agents).

      -

      Alex: A solid pull request habit is to separate three questions: what changed, why it changed, and what still needs review. That keeps the conversation useful instead of noisy.

      +

      Alex: Start with 7. How Standards Apply to GitHub Contributions: When you contribute to an open source project on GitHub, you will encounter accessibility in several contexts.

      +

      Alex: Hold that next to this. Here is the plain-English version of Filing an Accessibility Bug. Reference the specific WCAG criterion. Put another way, bad: "The button isn't accessible." Good: "The 'Subscribe' button has no visible focus indicator, failing WCAG 2.4.7 Focus Visible (Level AA).

      Jamie: If I am listening before the workshop starts, what should settle in my mind first?

      -

      Alex: This is where Agent Prerequisites (The "Skill First" Principle) becomes real: every agent automates a skill you should already know by hand. That matters in practice: Before using any agent, verify you have done the corresponding manual work.

      -

      Alex: That connects to another useful point. Keep the learner anchored in Workshop Recommendation (Chapter 19 / Challenge 15). Chapter 19 is the agent exploration and hands-on validation chapter - where students match agents to skills they already have and learn how to trust, evaluate, and improve AI-powered workflow automation. This is the part to say slowly: It supports Challenge 15: Meet the Agents. A good GitHub workflow is like a well-run meeting: everyone knows the topic, the next action, and who has the floor.

      -

      Alex: The parts worth keeping in working memory are these. There are 3 guided + 1-2 optional contribution challenges. Automation check: none (agent output requires human judgment before use). The evidence is issue comment showing agent output and your evaluation of it. The pattern is explore, validate, read internals, optionally contribute.

      +

      Alex: This is where Reviewing a PR for Accessibility becomes real: checklist for any PR that touches HTML or UI.

      +

      Alex: For a learner, the useful signals are these. Do new images have alt attributes? Do new interactive elements work with keyboard only? Do new form fields have associated elements? Are any new color-only indicators present? Does new dynamic content use aria-live if it updates without a page load?

      +

      Alex: That connects to another useful point. Keep the learner anchored in Writing Accessible Documentation. Documentation in Markdown is converted to HTML. A good GitHub workflow is like a well-run meeting: everyone knows the topic, the next action, and who has the floor.

      +

      Alex: The parts worth keeping in working memory are these. Use heading levels in order (don't skip from H1 to H3). Write descriptive link text (not "click here"). Add alt text to images. Use actual lists (- or 1.) rather than faking them with symbols.

      Jamie: What is the ordered workflow?

      -

      Alex: Start with Challenge 15 Set. There is something to understand, something to try, and something that proves the try worked.

      -

      Alex: First, agent Discovery Mapping - identify 3-5 agents that match skills you already have from Day 1. Then, agent Skill Validation - run one agent and evaluate its output against your manual experience. After that, agent Instructions Deep Dive - read one agent's source file and assess what it can and cannot do. Finally, improve an Existing Agent (optional hackathon) - find a gap in an agent's instructions and fix it via PR. The rhythm is simple: orient, act, verify, then continue.

      +

      Alex: Start with Manual Testing (catches the rest). There is something to understand, something to try, and something that proves the try worked.

      +

      Alex: First, keyboard-only navigation - unplug your mouse; can you do everything? Then, screen reader walkthrough - navigate the feature with NVDA, JAWS, or VoiceOver. After that, 200% zoom - does content reflow without horizontal scrolling? Finally, high contrast mode - Windows High Contrast or macOS Increase Contrast; are all elements still visible? The rhythm is simple: orient, act, verify, then continue.

      Jamie: Give me the sequence, because order matters here.

      -

      Alex: First, propose a New Agent (optional hackathon) - file an issue proposing an agent for an uncovered workflow. Think of it as a rail line: each stop confirms you are still on the right route before the next one.

      -
      -

      Jamie: What does the learner do first, second, and then after that?

      -

      Alex: Start with Challenge 15.1 Step-by-Step: Agent Discovery Mapping: Map your Day 1 manual skills to specific agents in the ecosystem so you know which agents you are ready to use. The next useful detail is this: GitHub.com - the accessibility-agents repository and your assigned Challenge 15 issue.

      -

      Alex: On the ground, that means a few things. @daily-briefing (maps to repository and issue awareness from Chapters 2-4). @issue-tracker (maps to Chapter 4 issue workflow). @pr-review (maps to Chapter 6 and Chapter 14 review workflow). Example: You filed issues manually (Ch 4) - you can use @issue-tracker.

      -

      Alex: First, fork the accessibility-agents repository on GitHub.com. Then, open the repository and navigate to Section 3 of the README (or this chapter's Section 3 below) to see the full list of 55 agents organized by team. After that, read through the agent names and descriptions. For each one, ask yourself: "Have I done this task manually during the workshop?". Finally, identify 3-5 agents that match workflows you already practiced. Think of it as a rail line: each stop confirms you are still on the right route before the next one.

      -

      Jamie: Turn that into a path someone can follow.

      -

      Alex: First, open your assigned Challenge 15 issue. Then, post a discovery mapping comment using this format. Treat it like a recipe: do not add the next ingredient until the previous one is actually in the bowl.

      -

      Jamie: Let's pause on Challenge 15.2 Step-by-Step: Agent Skill Validation. What should a learner take away from it?

      -

      Alex: Here is the plain-English version of Challenge 15.2 Step-by-Step: Agent Skill Validation. Run one agent, read its output, and evaluate whether it matches your manual experience. Put another way, VS Code with the accessibility-agents repository cloned and Copilot Chat open.

      -

      Alex: Here is what that changes in practice. @daily-briefing morning briefing. @issue-tracker find open issues labeled good-first-issue in accessibility-agents. @pr-review show open PRs in accessibility-agents.

      -

      Alex: First, clone your fork of accessibility-agents to VS Code (or open it in github.dev). Then, open Copilot Chat: Ctrl+Shift+I (Mac: Cmd+Shift+I). After that, choose one agent from your discovery list. If unsure, start with @daily-briefing or @issue-tracker. Finally, run it with a simple prompt. Treat it like a recipe: do not add the next ingredient until the previous one is actually in the bowl.

      -

      Jamie: Before we leave Challenge 15.2 Step-by-Step: Agent Skill Validation, what is the practical point?

      -

      Alex: First, read the agent's output carefully. Take a moment to think about what you expected. Then, open your assigned Challenge 15 issue and post an evaluation comment. It is a checklist, but a meaningful one: every item creates evidence that the next step is safe.

      -

      Jamie: Let's pause on Challenge 15.3 Step-by-Step: Agent Instructions Deep Dive. What should a learner take away from it?

      -

      Alex: This is where Challenge 15.3 Step-by-Step: Agent Instructions Deep Dive becomes real: read one agent's source file to understand what instructions it follows, what tools it can use, and what mistakes it could make. That matters in practice: VS Code or GitHub.com - reading files in the accessibility-agents repository. The workshop is closer to rehearsal than lecture. You hear the move, try the move, and then check what changed.

      -

      Alex: The room should hear these as checkpoints. What is this agent trying to do? (its purpose). What tools does it have access to? (tool permissions). What constraints or guardrails are in the instructions?

      -

      Alex: First, in the accessibility-agents repository, navigate to the.github/ folder (or wherever agent definition files are stored). Then, open one.agent.md or.prompt.md file for an agent you used or are curious about. After that, read the file and identify. Finally, think critically: could this agent make a mistake? What kind? It is a checklist, but a meaningful one: every item creates evidence that the next step is safe.

      -

      Jamie: Before we leave Challenge 15.3 Step-by-Step: Agent Instructions Deep Dive, what is the practical point?

      -

      Alex: First, open your assigned Challenge 15 issue and post your analysis. It is like walking a hallway with named doors: read the sign, enter the right room, then confirm where you landed.

      -
      -

      Jamie: Let's pause on Optional Extensions 15.4-15.5 (Hackathon). What should a learner take away from it?

      -

      Alex: Keep the learner anchored in Optional Extensions 15.4-15.5 (Hackathon). Extension 15.4: Improve an Existing Agent (45 min). This is the part to say slowly: Extension 15.5: Propose a New Agent (60 min).

      -

      Alex: That becomes easier when you listen for these cues. Find an agent whose instructions have a gap (use Section 6 suggestions or file an issue). Fork the repo, edit the agent's.agent.md file. Get a facilitator review. Open a PR with your improvement.

      -

      Alex: Another way to ground it. The reason Completing Challenge 15: Submit Your Evidence matters is that your evidence is the Challenge 15 issue comments for 15.1, 15.2, and 15.3. That gives the learner a simple foothold: for optional extensions, your PR or proposal issue is the evidence.

      -

      Jamie: Let's pause on Expected Outcomes. What should a learner take away from it?

      -

      Alex: Start with Expected Outcomes. There is something to understand, something to try, and something that proves the try worked.

      -

      Alex: A few details make that real. Student can map personal Day 1 skills to specific agents in the ecosystem. Student understands the Skill First, Agent Second principle and can articulate why agent output requires human judgment. Student can read agent instructions and evaluate what an agent can and cannot do. Student has used at least one agent and verified it against manual skills. (Optional) Student has contributed to the accessibility-agents ecosystem with a fix, improvement, or proposal.

      -
      -

      Jamie: Let's pause on If You Get Stuck. What should a learner take away from it?

      -

      Alex: Here is the plain-English version of If You Get Stuck. Continue learning: The GitHub Skills courses Build Applications with Copilot Agent Mode and Expand Your Team with Copilot explore agent-powered development workflows. Put another way, see Appendix Z for the full catalog. It is like learning a transit route. The names of the stops matter because they tell you whether you are still going the right direction.

      -

      Alex: First, cannot find an agent that matches your skills? Start with @daily-briefing or @issue-tracker - those build directly on Chapter 2-5 material. If you have not done those manual steps yet, go back to those chapters first. Then, agent output does not make sense? That is the right response. Paste the output in an issue comment along with your confusion. That is valuable feedback - the agent may need better instructions or guardrails. After that, cannot access the agents in Copilot Chat? Verify: Is Copilot Chat extension installed (not just base Copilot)? Are you signed in to GitHub in VS Code? Does.github/agents/ folder exist in your cloned repository? Finally, repository will not clone? Use the terminal: git clone https://github.com/[your-username]/accessibility-agents.git then open the folder in VS Code. Treat it like a recipe: do not add the next ingredient until the previous one is actually in the bowl.

      -

      Jamie: Before we leave If You Get Stuck, what is the practical point?

      -

      Alex: First, ask facilitator to show them what agent you wanted to run, what output you got, and what you expected. Then, finished but not sure you did it right? Compare your work against the Challenge 15 reference solution. It is a checklist, but a meaningful one: every item creates evidence that the next step is safe.

      -

      Jamie: Let's pause on Learning Moment. What should a learner take away from it?

      -

      Alex: This is where Learning Moment becomes real: the 55 agents exist because someone did the manual work first, then automated the repetitive parts. That matters in practice: As you explore agents, you are not just learning tools - you are learning what automation looks like when it is built on real expertise and real constraints.

      -

      Jamie: Let's pause on Learning Pattern Used in This Chapter. What should a learner take away from it?

      -

      Alex: Start with Learning Pattern Used in This Chapter. There is something to understand, something to try, and something that proves the try worked.

      -

      Alex: First, map your existing skills to available tools (discovery before action). Then, run one tool and evaluate its output critically (trust but verify). After that, read the source to understand capabilities and limits (internals matter). Finally, contribute improvements based on your evaluation (close the feedback loop). It is like walking a hallway with named doors: read the sign, enter the right room, then confirm where you landed.

      -
      -

      Jamie: Let's pause on Capstone: Share Your Feedback (The Most Important Task!). What should a learner take away from it?

      -

      Alex: The reason Capstone: Share Your Feedback (The Most Important Task!) matters is that you have now explored the full agent ecosystem, completed the workshop, and have valuable perspective on what worked, what confused you, and what we should improve for the next cohort. That gives the learner a simple foothold: your feedback directly shapes the future of this project.

      -

      Alex: Here is the practical turn. Start with Submit Workshop Feedback: Use the Workshop Feedback form to share. The next useful detail is this: Answer as much or as little as you're comfortable sharing. Think of it like entering a new building: first you find the lobby, then the room, then the door you actually need.

      -

      Alex: The practical takeaway is this. Which agents stood out? (Most useful or surprising). Which agents confused you? (What would make them better). Was the chapter progression logical? (Did earlier chapters prepare you for later ones). Accessibility experience (If applicable - did any assistive technology work/fail?).

      -

      Jamie: Let's pause on 1. The Principle: Skill First, Agent Second. What should a learner take away from it?

      -

      Alex: Here is the plain-English version of 1. The Principle: Skill First, Agent Second. Accessibility Agents is not a way to skip learning GitHub. Put another way, it is a way to amplify skills you have already built through deliberate practice.

      -

      Alex: The practical takeaway is this. Verify that the agent's output is correct. Catch when the agent misses context that only you have. Edit the agent's drafts into something worth posting under your name. Know when the agent is confidently wrong.

      +

      Alex: First, disable CSS - does the content still make sense in reading order? Think of it as a rail line: each stop confirms you are still on the right route before the next one.

      -

      Alex: Keep the thread going. This is where Every agent has a manual prerequisite. If you have not done the corresponding skill by hand, the agent is not ready for you yet - and you are not ready for it becomes real: this applies across all three teams and all 55 agents. That matters in practice: Before running any agent, the facilitator asks the same question.

      -

      Alex: The practical takeaway is this. GitHub Workflow agents automate repository navigation, issue triage, PR review, and contribution analytics - skills you practiced on Day 1. Accessibility agents automate WCAG auditing, contrast checking, keyboard navigation review, and document scanning - knowledge from your accessibility training and the standards in Appendix C. Developer Tools agents automate accessible coding patterns for Python, wxPython, and desktop applications - skills from your development experience.

      -

      Jamie: Let's pause on Learning Cards: Skill First, Agent Second. What should a learner take away from it?

      -

      Alex: Start with Learning Cards: Skill First, Agent Second. There is something to understand, something to try, and something that proves the try worked.

      -

      Alex: The practical takeaway is this. Before using any agent, verify you can do the task manually -- for @daily-briefing, confirm you can navigate Issues and PRs on GitHub.com with keyboard shortcuts (j/k to move, Enter to open). Agent output appears in Copilot Chat -- press Alt+F2 to open Accessible View and read the full response with arrow keys before acting on it. If an agent produces something you do not understand, stop and learn the manual skill first from the relevant chapter. Agent responses appear in the Copilot Chat panel -- drag the panel wider or use Alt+F2 (Accessible View) for a larger, cleaner reading pane. Each agent's instructions are in a.agent.md file you can open in VS Code and read at your preferred zoom level before invoking the agent. The agent ecosystem table in Section 3 uses standard Markdown tables that scale with your editor font size.

      -

      Alex: This is the part worth saying out loud. The reason Quick Install (One Command) matters is that accessibility Agents now ships with a one-liner installer that sets up all 55 agents for your platform. The interface gets friendlier when it stops being a wall of controls and starts being a set of named places.

      +

      Alex: Here is the practical turn. Start with Learning Cards: Testing Against Standards. There is something to understand, something to try, and something that proves the try worked.

      +

      Alex: On the ground, that means a few things. You are the manual test -- automated tools catch only 30-40% of issues; your screen reader walkthrough catches the rest. Install the axe DevTools browser extension (Section 8 table) and run it on any page; results are announced as a list of violations with WCAG criterion references. When doing a keyboard-only navigation test, press Tab repeatedly and listen -- every interactive element should announce its name and role. The 200% zoom test (item 3) mirrors your daily experience -- if content breaks at 200%, file a bug citing WCAG 1.4.4 Resize Text. Windows High Contrast mode test (item 4) is one click: Settings, Accessibility, Contrast themes -- switch and check that all UI elements remain visible. The WAVE browser extension overlays icons on the page showing errors and warnings -- zoom in to read the small annotation labels.

      +

      Jamie: Let's pause on 10. Official References. What should a learner take away from it?

      +

      Alex: Here is the plain-English version of 10. Official References. Next: Appendix N: Advanced Search Back: Appendix L: Agents Reference Teaching chapter: Chapter 08: Open Source Culture.

      -

      Jamie: What is the safe way to learn from that example?

      -

      Alex: Start with macOS / Linux. There is something to understand, something to try, and something that proves the try worked.

      -

      Alex: Treat examples as spoken recipes, not decorations. You may hear something like curl -fsSL https://raw.githubusercontent.com/Community-Access/accessibility-agents/main/install.sh bash. Read the command, understand what it changes, then run it only when the repository state matches the lesson.

      -

      Alex: The next layer is this. Here is the plain-English version of Windows (PowerShell). The installer detects which AI tools you have installed (VS Code with Copilot, Claude Code, Gemini CLI, Claude Desktop, Codex CLI) and configures the appropriate agent files for each platform. Put another way, to uninstall, run the corresponding uninstall script from the repository.

      -

      Jamie: Let's pause on Workshop Setup (Fork and Clone). What should a learner take away from it?

      -

      Alex: This is where Workshop Setup (Fork and Clone) becomes real: for the workshop, you will also fork and clone the repository so you can make contributions. That matters in practice: If Copilot Chat works, the agents work.

      -

      Alex: First, fork accessibility-agents to your GitHub account (you did this on Day 1 or Day 2 morning). Then, clone your fork. After that, open in VS Code: navigate to the folder and run code. (or File, then Open Folder). Finally, open Copilot Chat: Ctrl+Shift+I. It is a checklist, but a meaningful one: every item creates evidence that the next step is safe.

      -

      Jamie: Before we leave Workshop Setup (Fork and Clone), what is the practical point?

      -

      Alex: First, test: type @daily-briefing morning briefing and press Enter. It is like walking a hallway with named doors: read the sign, enter the right room, then confirm where you landed.

      -

      Alex: Treat examples as spoken recipes, not decorations. You may hear something like git clone https://github.com/[your-username]/accessibility-agents.git. Read the command, understand what it changes, then run it only when the repository state matches the lesson.

      +

      Jamie: What should people carry with them after this?

      +

      Alex: Carry the map. Know what page or tool you are in, know which action you are taking, and know what confirmation should follow. If the confirmation is missing, pause. That pause is not wasted time; it is professional judgment.

      +

      Jamie: That is a better way to say it than just follow the steps.

      +

      Alex: Right. Steps matter, but understanding wins. That is episode 20. Next in the series is episode 21, where we keep building the same contributor muscles.

      +
      +
      -

      Alex: Keep the teaching thread moving. Start with Prerequisites. There is something to understand, something to try, and something that proves the try worked.

      -

      Alex: The practical takeaway is this. GitHub Copilot Chat extension installed (see GitHub Copilot: Installation). Signed in to GitHub via VS Code. A workspace open containing.github/agents/ folder with.agent.md files.

      -

      Jamie: Let's pause on How Agents Are Discovered. What should a learner take away from it?

      -

      Alex: The reason How Agents Are Discovered matters is that when you type @ in Copilot Chat, VS Code scans. That gives the learner a simple foothold: the Accessibility Agents ecosystem installs agents appropriate to each platform.

      -

      Alex: First,.github/agents/.agent.md in your current workspace. Then, any agents installed globally on your machine. After that, agents defined by extensions. The rhythm is simple: orient, act, verify, then continue.

      -

      Alex: Keep the teaching thread moving. Start with Optional: Personalize Your Instance: Open preferences.md in VS Code and edit. The next useful detail is this: Commit preferences.md to your fork.

      +

      56. Episode 25: Releases, Tags, and Insights

      +

      Semantic versioning, GitHub Releases, and repository analytics.

      +

      Based on: Appendix S: Releases, Tags, and Insights

      +

      Audio and transcript are being regenerated for this episode.

      +
      +Read Transcript - Episode 25: Releases, Tags, and Insights + +

      Transcript

      +

      Alex: Welcome back to Git Going with GitHub. This is episode 25: Releases, Tags, and Insights. I am Alex, and today we are turning Releases, Tags, and Insights from a list of instructions into a working mental model.

      +

      Jamie: And I am Jamie. I will stop us whenever the instructions sound simple on paper but might feel different with a keyboard and screen reader.

      -

      Jamie: Let's pause on How Agents Travel with Your Repo. What should a learner take away from it?

      -

      Alex: Here is the plain-English version of How Agents Travel with Your Repo. When you fork accessibility-agents, the.github/agents/ folder comes with it.

      -

      Alex: The practical takeaway is this. Any collaborator who clones your fork gets all 55 agents automatically. You can customize agents for your specific project by editing the.agent.md files in your fork. Any project can have agents - create a.github/agents/ folder in any repository and add.agent.md files using the same pattern. The one-liner installer can also set up agents globally, so they are available in every workspace you open.

      -

      Alex: Keep the teaching thread moving. This is where Invoking Agents on GitHub.com becomes real: accessibility Agents agents run in VS Code. That matters in practice: But the same.agent.md files can also be invoked directly on GitHub.com - no VS Code, no local clone required. The workshop is closer to rehearsal than lecture. You hear the move, try the move, and then check what changed.

      -

      Jamie: Let's pause on Option 1: Copilot Chat with Task mode. What should a learner take away from it?

      -

      Alex: Keep the learner anchored in Option 1: Copilot Chat with Task mode. Screen reader users (NVDA / JAWS / VoiceOver).

      -

      Alex: First, open Copilot Chat on GitHub.com (icon in the top-right navigation bar). Then, click Task in the mode picker. After that, optionally click the agent picker to select a custom agent. Finally, type your request and click Send. It is like walking a hallway with named doors: read the sign, enter the right room, then confirm where you landed.

      -

      Jamie: Before we leave Option 1: Copilot Chat with Task mode, what is the practical point?

      -

      Alex: First, Copilot analyzes the task and can create a branch and open a PR automatically. Then, open Copilot Chat on GitHub.com (navigate to icon in top-right navigation → Enter). After that, the mode picker (Task vs Chat) is a set of radio buttons - navigate with Arrow keys to select "Task". Finally, the agent picker is a listbox - Up/Down Arrow to navigate, Enter to select. The rhythm is simple: orient, act, verify, then continue.

      +

      Alex: Semantic versioning, GitHub Releases, and repository analytics. That is the surface description. Underneath it, we are building judgment: where to focus, what to ignore, and how to verify the result.

      +

      Jamie: So we are not using the audio as a shortcut around learning. We are using it to make the learning easier to enter.

      +

      Alex: Yes. A good audio lesson gives someone enough context to try the work with confidence, even before they open the written material.

      -

      Jamie: Let's pause on Option 2: Assign an issue to Copilot. What should a learner take away from it?

      -

      Alex: The reason Option 2: Assign an issue to Copilot matters is that screen reader users (NVDA / JAWS / VoiceOver). That gives the learner a simple foothold: this is the bridge to Section 6 (The Cloud Extension).

      -

      Alex: First, open any issue (or create a new one describing the task). Then, in the Assignees sidebar section, click the gear icon. After that, in the dropdown, click Copilot as the assignee. Finally, a dialog opens - optionally provide additional instructions and select a custom agent. The rhythm is simple: orient, act, verify, then continue.

      -

      Jamie: Before we leave Option 2: Assign an issue to Copilot, what is the practical point?

      -

      Alex: First, click Assign to confirm. Then, open any issue in the repository. After that, press B to navigate to the Assignees gear button → Enter to open the popup. Finally, navigate the popup with Arrow keys → find "Copilot" → Enter to select. Think of it as a rail line: each stop confirms you are still on the right route before the next one.

      -

      Alex: A solid issue habit is to read the title, the body, and the timeline before acting. You are listening for the requested action, the missing evidence, and the person who needs a response.

      -

      Jamie: What should someone listen for when a lesson offers more than one tool path?

      -

      Alex: Start with Copilot on GitHub.com - Browser-Native Features: Beyond assigning Copilot to issues and using Task mode in Chat, GitHub.com now has several standalone Copilot features built directly into the web interface. The next useful detail is this: These work entirely in your browser - no VS Code, no local clone needed.

      -

      Alex: Keep the teaching thread moving. Here is the plain-English version of Copilot PR Summary. On any open pull request, GitHub adds a "Summarize" button in the PR description area. Put another way, selecting it generates a plain-language summary of what the PR changes, why, and what reviewers should focus on. It is like learning a transit route. The names of the stops matter because they tell you whether you are still going the right direction.

      +

      Jamie: Okay, set the room for us. What are we walking into?

      +

      Alex: Start with Understanding Versioned Releases and Repository Activity: Two things help you understand a repository's health and your place in it: releases (the versioned snapshots your contributions land in) and insights (the activity metrics that show how a project grows).

      +

      Jamie: How would you walk the room through that step by step?

      +

      Alex: Start with Releases and Tags. There is something to understand, something to try, and something that proves the try worked.

      +

      Alex: First, what Is a Release? Then, releases vs. Tags vs. Branches. After that, navigating Releases on GitHub. Finally, understanding Version Numbers. Treat it like a recipe: do not add the next ingredient until the previous one is actually in the bowl.

      +

      Jamie: What does the learner do first, second, and then after that?

      +

      Alex: First, reading Release Notes. Then, for Maintainers: Creating a Release. After that, draft and Pre-Release States. Finally, accessibility Agents: /draft-release. It is a checklist, but a meaningful one: every item creates evidence that the next step is safe.

      +

      Jamie: Turn that into a path someone can follow.

      +

      Alex: Start with Repository Insights. There is something to understand, something to try, and something that proves the try worked.

      +

      Alex: First, what Is the Insights Tab? Then, navigating to Insights. After that, pulse - Recent Activity Summary. Finally, contributors - Who Builds the Project. It is a checklist, but a meaningful one: every item creates evidence that the next step is safe.

      +

      Jamie: What is the ordered workflow?

      +

      Alex: First, traffic - Who Visits the Repo. Then, commits and Code Frequency. After that, dependency Graph. Finally, network and Forks. It is like walking a hallway with named doors: read the sign, enter the right room, then confirm where you landed.

      -

      Jamie: Let's pause on Copilot PR Review. What should a learner take away from it?

      -

      Alex: This is where Copilot PR Review becomes real: on open PRs you have write access to review, a "Review" button (or Copilot icon) appears in the Files changed tab. That matters in practice: Copilot generates inline review comments across the diff.

      -

      Alex: Keep the teaching thread moving. Keep the learner anchored in Copilot in Issues. On any issue page, Copilot adds sidebar buttons that appear once the page loads. This is the part to say slowly: Look in the right sidebar on any issue page for a Copilot section with "Explain" and "Suggest fix" buttons.

      -

      Alex: The practical takeaway is this. "Explain this issue" - generates a plain-language explanation of a complex technical issue. "Suggest fix" - proposes an approach to resolving the issue (opens a task/PR workflow).

      -

      Jamie: Let's pause on GitHub Models - Free AI Playground. What should a learner take away from it?

      -

      Alex: The reason GitHub Models - Free AI Playground matters is that github.com/marketplace/models is a free playground where you can test AI models (OpenAI GPT-4o, Meta Llama 3, Mistral, Phi-4 Mini, and others) directly in your browser. That gives the learner a simple foothold: why it matters for Accessibility Agents: When you build custom agents and prompts, you can test your system prompts and prompt templates in GitHub Models before adding them to your.prompt.md files - rapid iteration without burning API credits.

      -

      Alex: The practical takeaway is this. Send prompts to any listed model and compare responses side by side. Adjust parameters (temperature, max tokens) without any setup. Use the code sample generator to get API code for your chosen model. All free with a GitHub account (rate-limited for free tier).

      +

      Alex: Now bring the learner back to the room. Keep the learner anchored in 1. What Is a Release? A release is a named snapshot of a repository at a specific point in history, packaged and published for users. This is the part to say slowly: For software projects, a release typically includes.

      +

      Alex: For a learner, the useful signals are these. A version number (e.g., v2.1.0). Release notes explaining what changed. Links to download the compiled or packaged software (if applicable). Source code archives (automatically generated by GitHub).

      +

      Jamie: What would you say to someone who is already bracing for this to be too much?

      +

      Alex: The reason 2. Releases vs. Tags vs. Branches matters is that these three concepts are closely related.

      +

      Alex: A solid Git habit is to know which branch you are on, what changed, and what confirmation you expect before you run the next command.

      +

      Alex: That matters because of the next idea. Start with The relationship. There is something to understand, something to try, and something that proves the try worked.

      +

      Alex: On the ground, that means a few things. Every release is backed by a tag. A tag without a release is just a version marker in the git history. GitHub automatically creates a tag when you create a release.

      +

      Alex: The useful habit is simple: orient first, act second, verify third. That pause before acting is part of the work.

      -

      Alex: Keep the teaching thread moving. Start with Copilot-Drafted Release Notes: When creating a release (Releases tab → Draft a new release), GitHub provides a "Generate release notes" button. The next useful detail is this: It scans merged PRs since the last release and drafts categorized release notes automatically. Think of it like entering a new building: first you find the lobby, then the room, then the door you actually need.

      -

      Jamie: What is the pre-flight check here?

      -

      Alex: Start with Learning Cards: Setup and Configuration. There is something to understand, something to try, and something that proves the try worked.

      -

      Alex: The practical takeaway is this. Run the installer command in the VS Code terminal (Ctrl+) -- it announces progress as it copies agent files to.github/agents/`. After installation, press Ctrl+Shift+E to open the Explorer and navigate to.github/agents/ to verify agent files are present. Edit.github/agents/preferences.md to configure your username, repositories, and notification preferences -- it is a standard Markdown file. The installer creates files in.github/agents/ and.github/prompts/ -- verify in the Explorer sidebar that these folders appeared. Open preferences.md in the editor to set your configuration -- use Ctrl+= to zoom if the YAML frontmatter is hard to read. Agent files use.agent.md extension -- they appear alongside regular Markdown files in the Explorer but are distinguished by their extension.

      -

      Alex: Keep the teaching thread moving. This is where 3. The Ecosystem: 55 Agents, 3 Teams, 5 Platforms becomes real: accessibility Agents is an ecosystem of 55 specialized agents organized into three teams, each addressing a different dimension of accessible software development. That matters in practice: Browse all three teams below, then choose the agents that match your current skills and interests.

      +

      Jamie: Give me the sequence, because order matters here.

      +

      Alex: Start with Finding the Releases Page. There is something to understand, something to try, and something that proves the try worked.

      +

      Alex: First, look on the right sidebar for a "Releases" section showing the latest release. Then, activate "Releases" or the version link to go to the full releases page. After that, alternatively: navigate to github.com/owner/repo/releases. Treat it like a recipe: do not add the next ingredient until the previous one is actually in the bowl.

      +

      Alex: This is where the talk moves from concept to action. This is where The Releases List Page becomes real: each release appears as a section.

      +

      Alex: The room should hear these as checkpoints. The release title (usually the version number). A badge: "Latest" (most recent stable), "Pre-release", or nothing (older release). Publication date. The tag name. Release notes (the main body). Asset downloads (if included).

      +

      Jamie: What is the one idea that makes the next few steps less mysterious?

      +

      Alex: Start with Learning Cards: Navigating Releases. There is something to understand, something to try, and something that proves the try worked.

      +

      Alex: These are the details that keep the idea from floating away. On the repository home page, press H or 3 to find the "Releases" heading in the right sidebar, then K to the version link -- Enter opens the latest release directly. On the Releases list page, each release is a heading -- use 2 or 3 to jump between releases and arrow down to read the notes inline. The "Latest" badge appears next to the most recent stable release -- listen for it to distinguish stable releases from pre-releases or older versions. The Releases link on the repo home page sits in the right sidebar -- at high zoom the sidebar may collapse below the main content; scroll down to find it. Release notes use Markdown headings (Breaking Changes, New Features, Bug Fixes) -- zoom in and scan the bold section labels for quick triage. The green "Latest" badge next to the newest stable release is small -- zoom to 150%+ to spot it among the release list entries.

      -

      Jamie: Let's pause on Team 1: Accessibility (26 agents). What should a learner take away from it?

      -

      Alex: Keep the learner anchored in Team 1: Accessibility (26 agents). These agents audit, fix, and enforce accessibility across web, document, and mobile platforms.

      -

      Alex: Keep the teaching thread moving. The reason Team 2: GitHub Workflow (12 agents) matters is that these agents automate GitHub operations - issue triage, PR review, contribution analytics, and repository management. The interface gets friendlier when it stops being a wall of controls and starts being a set of named places.

      -

      Jamie: What stays the same when the tool changes?

      -

      Alex: Start with Team 3: Developer Tools (6 agents): These agents support accessible application development across desktop and cross-platform frameworks.

      +

      Alex: Before the learner moves on. The reason 4. Understanding Version Numbers matters is that most projects follow Semantic Versioning (semver): MAJOR.MINOR.PATCH. The interface gets friendlier when it stops being a wall of controls and starts being a set of named places.

      +

      Jamie: Give me the version that sounds like an instructor, not a manual.

      +

      Alex: Start with Examples: Pre-release suffixes (not part of semver core, but common).

      +

      Alex: A few details make that real. v2.0.0 → major release, breaking changes possible. v2.1.0 → new features added. v2.1.3 → three bug fixes since v2.1.0. v2.1.0-alpha.1 → early preview, may be unstable. v2.1.0-beta.2 → feature-complete but still testing. v2.1.0-rc.1 → release candidate, nearly final.

      +

      Jamie: What should happen before anyone copies and runs it?

      +

      Alex: Here is the plain-English version of 5. Reading Release Notes. Release notes document what changed. Put another way, high-quality release notes categorize changes.

      +

      Alex: Treat examples as spoken recipes, not decorations. You may hear something like What's New in v2.1.0; Breaking Changes; - The preferences.md format has changed - see the migration guide; New Features; - Added /project-status command ( 42, @alice); - Added /onboard-repo command ( 38, @bob); Bug Fixes; - Fixed keyboard navigation in the. Read the command, understand what it changes, then run it only when the repository state matches the lesson.

      -

      Alex: Keep the teaching thread moving. Here is the plain-English version of Beyond Agents: The Supporting Ecosystem. The 55 agents are backed by additional resources in the repository.

      -

      Jamie: Let's pause on Hook-Based Enforcement (Claude Code). What should a learner take away from it?

      -

      Alex: This is where Hook-Based Enforcement (Claude Code) becomes real: on Claude Code, Accessibility Agents includes a hook system that enforces accessibility standards automatically. That matters in practice: This means accessibility enforcement happens whether or not the developer remembers to ask for it.

      -

      Alex: First, proactive detection hook - scans every file edit for accessibility regressions before they are committed. Then, edit gate hook - blocks commits that introduce WCAG violations until they are fixed. After that, session marker hook - tracks which accessibility checks have run during the current session. It is a checklist, but a meaningful one: every item creates evidence that the next step is safe.

      -

      Alex: Keep the teaching thread moving. Keep the learner anchored in What Would You Build? This is the question that matters most. This is the part to say slowly: The 55 agents that exist today were built by contributors who saw a gap and filled it. A good GitHub workflow is like a well-run meeting: everyone knows the topic, the next action, and who has the floor.

      -

      Alex: The practical takeaway is this. "Why is there no agent for [framework] accessibility patterns?". "I spend 30 minutes on [task] every week - could an agent do the repetitive part?". "This agent is good but it misses [specific edge case] - I could improve those instructions". "Mobile native accessibility testing has no agent coverage yet - I could start one".

      +

      Jamie: If I am listening before the workshop starts, what should settle in my mind first?

      +

      Alex: This is where 6. For Maintainers: Creating a Release becomes real: this section is relevant if you become a maintainer or contribute to a project that asks you to prepare releases.

      +

      Jamie: Let's pause on Creating a Release from the GitHub UI. What should a learner take away from it?

      +

      Alex: Start with Creating a Release from the GitHub UI. There is something to understand, something to try, and something that proves the try worked.

      +

      Alex: First, navigate to github.com/owner/repo/releases/new. Then, choose a tag: Type a new version tag (e.g., v2.1.0) - GitHub will create it on publish, or select an existing tag if you already created one. After that, choose a target branch: The branch the tag will be applied to (usually main). Finally, release title: Usually the same as the tag (e.g., v2.1.0). It is like walking a hallway with named doors: read the sign, enter the right room, then confirm where you landed.

      +

      Jamie: Before we leave Creating a Release from the GitHub UI, what is the practical point?

      +

      Alex: First, release notes: Write manually, or click "Generate release notes" - GitHub auto-generates from merged PR titles since the last release. Then, assets: Optionally attach compiled binaries or other files. After that, pre-release toggle: Mark as pre-release if it's alpha/beta. Finally, draft toggle: Save as draft to prepare without publishing immediately. The rhythm is simple: orient, act, verify, then continue.

      +

      Jamie: Where do you want a learner to place their attention here?

      +

      Alex: The reason Using Accessibility Agents for Release Notes matters is that the /draft-release command generates structured release notes automatically from your merged PRs - much faster and more consistent than writing them manually.

      -

      Jamie: Let's pause on The contribution paths are. What should a learner take away from it?

      -

      Alex: The reason The contribution paths are matters is that see the Accessibility Agents CONTRIBUTING guide for detailed instructions on each path.

      -

      Alex: First, report an agent gap - file an issue describing what is missing and why it matters. Then, improve existing agent instructions - make an agent smarter about edge cases it misses. After that, add framework-specific patterns - teach agents about React, Vue, Angular, Svelte, or other framework accessibility patterns. Finally, fix installer issues - improve the one-liner scripts for different OS configurations. The rhythm is simple: orient, act, verify, then continue.

      -

      Jamie: Before we leave The contribution paths are, what is the practical point?

      -

      Alex: First, write documentation - help others understand how to use and contribute to agents. Think of it as a rail line: each stop confirms you are still on the right route before the next one.

      -

      Alex: Keep the teaching thread moving. Start with Roadmap: What Is Coming Next: Your contribution could be the next item that ships. The next useful detail is this: Every agent started as one person's idea and one pull request.

      -

      Alex: The practical takeaway is this. Mobile native agents - agents specialized for iOS (VoiceOver) and Android (TalkBack) native app accessibility. Anthropic Connectors listing - making agents discoverable through the Anthropic marketplace. veraPDF integration - automated PDF/UA validation for the PDF accessibility agent. Document remediation agents - agents that fix accessibility issues in documents, not just find them.

      -

      Jamie: Let's pause on Learning Cards: The Agent Ecosystem. What should a learner take away from it?

      -

      Alex: Start with Learning Cards: The Agent Ecosystem. There is something to understand, something to try, and something that proves the try worked.

      -

      Alex: The practical takeaway is this. The three team tables use standard Markdown table format -- navigate with T (NVDA/JAWS) to jump between tables, then Arrow keys to read cells. Agent names start with @ -- type @ followed by the agent name in Copilot Chat to invoke it (e.g., @daily-briefing). Use Ctrl+Shift+O (symbol outline) in any agent file to navigate between its YAML frontmatter sections (Purpose, Responsibilities, Guardrails). The agent tables are dense -- use Ctrl+= to increase font size or open the file in Markdown Preview (Ctrl+Shift+V) for cleaner rendering. Each team has a distinct table: Team 1 (Accessibility, 26 agents), Team 2 (GitHub Workflow, 15 agents), Team 3 (Developer Tools, 14 agents). Agent files in.github/agents/ have descriptive filenames that match the @agent-name -- browse them in the Explorer to find specific agents.

      +

      Alex: Here is the practical turn. Start with Learning Cards: Creating a Release. There is something to understand, something to try, and something that proves the try worked.

      +

      Alex: Here is what that changes in practice. The release creation form at github.com/owner/repo/releases/new has several fields -- Tab through them in order: tag selector (combobox), target branch, title input, release notes textarea, asset upload, pre-release checkbox, draft checkbox, and publish button. The tag selector is a combobox -- type a new version tag (e.g., v2.1.0) and the option to create it appears; arrow down and press Enter to select. The "Generate release notes" button auto-fills the textarea with merged PR titles -- after clicking it, arrow through the generated notes to verify accuracy before publishing. The release creation page uses a single-column form layout -- zoom in and the form fields stack vertically for easy scanning. The "Pre-release" and "Draft" checkboxes are at the bottom of the form, below the release notes editor -- scroll past the potentially long textarea to find them. The "Generate release notes" button is a small link-style button near the release notes textarea -- look for it above or beside the text area at high magnification.

      +

      Jamie: Let's pause on 7. Draft and Pre-Release States. What should a learner take away from it?

      +

      Alex: Here is the plain-English version of 7. Draft and Pre-Release States. Draft release: Saved but not published. Put another way, only visible to repository collaborators.

      +

      Alex: A solid pull request habit is to separate three questions: what changed, why it changed, and what still needs review. That keeps the conversation useful instead of noisy.

      +

      Alex: Keep the thread going. This is where 8. Accessibility Agents: /draft-release becomes real: the /draft-release command automates release note generation from your merged pull requests. The workshop is closer to rehearsal than lecture. You hear the move, try the move, and then check what changed.

      -

      Alex: Keep the teaching thread moving. This is where 4. Agents in Detail - Hands-On Reference becomes real: this section walks through several agents in depth so you can see how they work, what they produce, and how to evaluate their output. That matters in practice: These examples use GitHub Workflow agents because they build directly on Day 1 skills - but the same patterns apply to every agent in the ecosystem. The workshop is closer to rehearsal than lecture. You hear the move, try the move, and then check what changed.

      -

      Jamie: Let's pause on Two Types of Agents. What should a learner take away from it?

      -

      Alex: Keep the learner anchored in Two Types of Agents. Before diving in, it helps to know that custom agents fall into two categories - this distinction affects what tool permissions they need and what they can do. This is the part to say slowly: Informational agents search, analyze, and report.

      -

      Alex: Keep the teaching thread moving. The reason Agent 1: @daily-briefing - Morning Briefing matters is that file.github/agents/daily-briefing.agent.md. That gives the learner a simple foothold: before you run this agent: You should have manually navigated a repository's Issues tab, read your GitHub Notifications page, understood what a pull request waiting for review looks like, and know the difference between subscribed and participating.

      +

      Jamie: Let's pause on What it produces. What should a learner take away from it?

      +

      Alex: Start with What it produces. There is something to understand, something to try, and something that proves the try worked.

      +

      Alex: That becomes easier when you listen for these cues. Auto-categorized changes: Breaking Changes, Features, Bug Fixes, Dependencies. Each PR listed with number, title, and author. A full changelog link. Markdown formatted and ready to paste into GitHub's release editor.

      +

      Jamie: What should they understand before typing anything?

      +

      Alex: The reason Example output matters is that see also: The /release-prep command runs a complete pre-release checklist (milestone status, open PRs, CI health, security, and then generates release notes) - useful when preparing a release from scratch rather than just generating notes.

      +

      Alex: Treat examples as spoken recipes, not decorations. You may hear something like v2.1.0; New Features; - Add /project-status command ( 42, @alice); - Add /onboard-repo for first-time repo scanning ( 38, @bob); Bug Fixes; - Fix keyboard navigation in triage workflow ( 51, @charlie); - Correct screen reader announcement for merged PRs ( 48,. Read the command, understand what it changes, then run it only when the repository state matches the lesson.

      +

      Jamie: Let's pause on 9. What Is the Insights Tab? What should a learner take away from it?

      +

      Alex: Start with 9. What Is the Insights Tab?: The Insights tab shows quantitative activity data for a repository. The next useful detail is this: It is primarily read-only and chart-heavy - but all underlying data is also presented in tables that screen readers can navigate.

      -

      Jamie: Let's pause on What it does. What should a learner take away from it?

      -

      Alex: Start with What it does: Sweeps every repository you have access to and builds a prioritized dashboard.

      -

      Alex: The practical takeaway is this. Issues opened in the last 24 hours. Pull requests waiting for your review. CI failures on your branches. Security and Dependabot alerts. Community reactions to your recent comments.

      -

      Alex: Keep the teaching thread moving. Here is the plain-English version of Example commands. The briefing output uses heading level 2 for each section. Put another way, use H key (NVDA/JAWS virtual mode) or VO+Command+H (VoiceOver) to jump between: Open Issues, Review Requests, CI Status, Security Alerts, Community Activity. It is like learning a transit route. The names of the stops matter because they tell you whether you are still going the right direction.

      -

      Jamie: Let's pause on Agent 2: @issue-tracker - Issue Management. What should a learner take away from it?

      -

      Alex: This is where Agent 2: @issue-tracker - Issue Management becomes real: file.github/agents/issue-tracker.agent.md. That matters in practice: Before you run this agent: You should have filed at least one issue using the full manual process - writing a title, description, and reproduction steps; applying labels and a milestone; and reading at least five existing issues to understand what a.

      +

      Alex: This is the part worth saying out loud. Start with Who can see Insights. There is something to understand, something to try, and something that proves the try worked.

      +

      Alex: The practical anchors are these. Anyone can see Insights on a public repository. Private repository Insights require collaborator access.

      +

      Jamie: Let's pause on What Insights does NOT show. What should a learner take away from it?

      +

      Alex: Start with What Insights does NOT show. There is something to understand, something to try, and something that proves the try worked.

      +

      Alex: That shows up in the workshop in a few specific ways. Individual user data in detail (e.g., lines per commit per person). Real-time data (most views update daily or weekly). Code quality scores.

      +

      Jamie: Let's pause on 10. Navigating to Insights. What should a learner take away from it?

      +

      Alex: Start with 10. Navigating to Insights. There is something to understand, something to try, and something that proves the try worked.

      +

      Alex: First, navigate to the repository's main tab bar. Then, find and select the Insights tab. After that, the Insights sub-navigation has multiple views listed on the left (or top on smaller screens). It is like walking a hallway with named doors: read the sign, enter the right room, then confirm where you landed.

      -

      Alex: Keep the teaching thread moving. Keep the learner anchored in What it does. Finds, prioritizes, and helps you manage issues across all your repositories.

      -

      Alex: The practical takeaway is this. Cross-repository priority scoring with community sentiment. Batch-reply capability (draft replies to multiple issues at once). Saved search support. Release-awareness (flags issues that affect upcoming releases).

      -

      Jamie: How do we make tool choice feel like access, not pressure?

      -

      Alex: The reason Example commands matters is that the agent can draft a reply. That gives the learner a simple foothold: you review the tone against the Culture & Etiquette guide before posting.

      -

      Jamie: How do you keep commands from becoming magic words?

      -

      Alex: Start with Output example. There is something to understand, something to try, and something that proves the try worked.

      -

      Alex: Treat examples as spoken recipes, not decorations. You may hear something like Open Issues Labeled "good-first-issue"; High Priority; - 45 [accessibility-agents] Add NVDA-specific navigation tips (3 comments, opened 5 days ago); - Priority Score: 8/10 (high community interest, clear scope, no assignee); - Recommended for: First-time. Read the command, understand what it changes, then run it only when the repository state matches the lesson.

      +

      Jamie: Let's pause on 11. Pulse - Recent Activity Summary. What should a learner take away from it?

      +

      Alex: The reason 11. Pulse - Recent Activity Summary matters is that pulse is the Insights landing page. That gives the learner a simple foothold: it summarizes activity in a chosen time period (last 24 hours, 7 days, or 30 days).

      +

      Alex: The parts worth keeping in working memory are these. Open issues / Closed issues - net change in the time period. Open pull requests / Merged pull requests / Closed pull requests - with counts. Authors: N contributors pushed M commits to N branches. A list of merged PRs (each linked to the PR).

      +

      Alex: Another way to ground it. Start with What it tells you as a contributor. There is something to understand, something to try, and something that proves the try worked.

      +

      Alex: The practical takeaway is this. Is this project actively maintained? (Are PRs being merged regularly?). Is there a backlog? (Many open issues vs. few closures). Is the maintainer responsive? (Time between PR open and merge).

      +

      Jamie: Let's pause on Learning Cards: Pulse (Recent Activity Summary). What should a learner take away from it?

      +

      Alex: Start with Learning Cards: Pulse (Recent Activity Summary). There is something to understand, something to try, and something that proves the try worked.

      +

      Alex: The practical takeaway is this. Pulse is the Insights landing page -- after entering the Insights tab, you land here; use 2 to jump between section headings (Merged PRs, Opened Issues, etc.). Each section lists linked PR or issue titles -- press 3 to jump between individual items, or K to navigate the links directly. Use the time period selector (last 24 hours, 7 days, 30 days) at the top to scope the summary -- Tab to it and select with arrow keys. Pulse displays activity counts in large numbers at the top of the page -- zoom in to read the open/closed/merged totals. The merged PR and opened issue lists below the summary use standard link formatting -- increase font size to scan titles comfortably. The time period toggle (24h, 7d, 30d) sits near the top -- it can be small at default zoom; look for the underlined active period indicator.

      -

      Jamie: Let's pause on Agent 3: @pr-review - Pull Request Review. What should a learner take away from it?

      -

      Alex: Here is the plain-English version of Agent 3: @pr-review - Pull Request Review. File.github/agents/pr-review.agent.md. Put another way, before you run this agent: You should have manually reviewed at least one pull request diff in the GitHub browser interface - navigating the Files Changed tab with your screen reader, reading added and removed lines, leaving at least one inline comment, and.

      -

      Alex: Keep the teaching thread moving. This is where What it does becomes real: generates full review documents for pull requests.

      -

      Alex: The practical takeaway is this. Line-numbered diffs with change maps. Risk assessment (what could break, what is high-impact). Before-and-after snapshots. CI results and test coverage information. Suggested inline review comments with line number references.

      -

      Jamie: What is the common workflow underneath the different interfaces?

      -

      Alex: Keep the learner anchored in Example commands. Critical rule: Read the agent's review. This is the part to say slowly: The agent produces a starting point - it does not know the project's history, the contributor's background, or the community's implicit standards the way you do.

      +

      Alex: Hold that next to this. This is where 12. Contributors - Who Builds the Project becomes real: the Contributors view shows a bar chart of commits over time, with each contributor represented by a different color. That matters in practice: Below the chart is a sortable table.

      +

      Jamie: Let's pause on The table (accessible). What should a learner take away from it?

      +

      Alex: Start with The table (accessible). There is something to understand, something to try, and something that proves the try worked.

      +

      Alex: The practical takeaway is this. Username. Number of commits (with a link to filtered commit history). Additions (lines added). Deletions (lines removed). Sorted by total commits by default.

      +

      Alex: The next layer is this. Start with Why this matters as a new contributor. There is something to understand, something to try, and something that proves the try worked.

      +

      Alex: The practical takeaway is this. You can see how active top contributors are. After your first merged PR, your name appears here (with your commits). You can link to your section (github.com/owner/repo/graphs/contributors) as proof of contribution.

      -

      Jamie: What should happen before anyone copies and runs it?

      -

      Alex: Treat examples as spoken recipes, not decorations. You may hear something like PR Review: 14 - Improve screen reader navigation guide; Summary; This PR adds 3 new sections to the screen reader navigation guide and updates 2 existing sections with NVDA-specific keyboard shortcuts.; Files Changed: 1; Lines Added: 127; Lines Removed: 18. Read the command, understand what it changes, then run it only when the repository state matches the lesson.

      -

      Jamie: Let's pause on Agent 4: @analytics - Team Analytics. What should a learner take away from it?

      -

      Alex: Start with Agent 4: @analytics - Team Analytics: File.github/agents/analytics.agent.md. The next useful detail is this: Before you run this agent: You should have explored the Insights tab of at least one repository - looked at the contribution graph, understood what commit frequency means, and thought about what "high-churn files" implies for a project's stability.

      -

      Alex: Keep the teaching thread moving. Here is the plain-English version of What it does. Surfaces team contribution patterns, velocity metrics, and bottleneck detection.

      -

      Alex: The practical takeaway is this. Contribution velocity over time. Review turnaround time by reviewer. Code hotspot detection (files with the most churn). Workload distribution across contributors.

      +

      Jamie: Let's pause on Screen reader. What should a learner take away from it?

      +

      Alex: Start with Screen reader: The chart is a canvas graphic - not directly readable. The next useful detail is this: The table below it is fully accessible.

      +

      Alex: A solid navigation habit is to prove where you are before activating controls. Headings, landmarks, and the address bar are not trivia; they are your map.

      +

      Alex: That connects to another useful point. Start with Learning Cards: Contributors. There is something to understand, something to try, and something that proves the try worked.

      +

      Alex: The practical takeaway is this. The contributor chart is a canvas graphic that screen readers cannot access -- skip it and navigate to the data table below with T (next table) which contains the same information in accessible form. The table has sortable column headers (Commits, Additions, Deletions) -- Tab to a header and press Enter to sort; the table reloads with the new sort order. Each contributor's username is a link to their filtered commit list -- activate it to see every commit that person made to this repository. The bar chart uses color to distinguish contributors -- the table below provides the same data as text; zoom in on the table if the chart colors are hard to differentiate. Sorting by Commits (default) puts top contributors first -- at high zoom, the table may require horizontal scrolling to see the Additions and Deletions columns. After your first merged PR, your username appears in this table -- link to it (github.com/owner/repo/graphs/contributors) as proof of contribution in your portfolio.

      +

      Jamie: Let's pause on 13. Traffic - Who Visits the Repo. What should a learner take away from it?

      +

      Alex: This is where 13. Traffic - Who Visits the Repo becomes real: traffic shows who is viewing and cloning the repository. That matters in practice: Available only to repository owners and collaborators with push access.

      -

      Jamie: There are a lot of tools in play. How do we keep that from feeling like a contest?

      -

      Alex: This is where Example commands becomes real: accessibility use case: After Day 2's contribution wave, run @analytics team velocity in accessibility-agents today to see the hackathon's collective output. That matters in practice: A moment of real-time team celebration.

      -

      Alex: Keep the teaching thread moving. Keep the learner anchored in Agent 5: @insiders-a11y-tracker - Accessibility Change Monitoring. File.github/agents/insiders-a11y-tracker.agent.md. This is the part to say slowly: Before you run this agent: You should have filed at least one accessibility bug report using the workshop's issue template, applied a WCAG label to an issue, and manually reviewed a Markdown file for heading hierarchy - knowing what H1 means, what H2 means,. A good GitHub workflow is like a well-run meeting: everyone knows the topic, the next action, and who has the floor.

      -

      Jamie: Before we leave What it does, what is the practical point?

      -

      Alex: The reason What it does matters is that monitors accessibility-sensitive changes across configured repositories.

      -

      Alex: The practical takeaway is this. WCAG/ARIA cross-referenced change tracking. Flags changes to keyboard navigation, ARIA attributes, focus management, color usage. Monitors for heading hierarchy violations in Markdown. Tracks link text quality (flags bare URLs, non-descriptive labels).

      +

      Alex: Keep the teaching thread moving. Start with Why this matters. There is something to understand, something to try, and something that proves the try worked.

      +

      Alex: The practical takeaway is this. If the README is the most-viewed file, documentation improvements have high impact. If traffic spiked when a blog post linked the repo, that's a good signal for community growth.

      +

      Jamie: Let's pause on 14. Commits and Code Frequency. What should a learner take away from it?

      +

      Alex: The reason 14. Commits and Code Frequency matters is that commits shows commit frequency over the past year, by week. That gives the learner a simple foothold: code Frequency shows additions and deletions per week as an area chart.

      +

      Alex: The practical takeaway is this. Active development periods (many commits). Dormant periods (no commits) - a project with 6+ months of inactivity may be unmaintained. Release sprints (burst of commits before a release tag). Heavy refactoring.

      +

      Alex: Keep the teaching thread moving. Start with 15. Dependency Graph: Dependents - repositories that depend on this one - is the "used by" count you see on the right sidebar of popular packages.

      +

      Alex: The practical takeaway is this. What your project depends on (libraries, packages). What depends on your project (if others import your repo).

      -

      Alex: Keep the teaching thread moving. Start with Example commands: Day 2 workflow: Run this before submitting any PR. The next useful detail is this: If the agent flags an issue, fix it before requesting review - not after.

      -

      Jamie: Let's pause on Agent 6: @template-builder - Interactive Issue Template Wizard. What should a learner take away from it?

      -

      Alex: Here is the plain-English version of Agent 6: @template-builder - Interactive Issue Template Wizard. File.github/agents/template-builder.agent.md. Put another way, before you run this agent: You should have read Issue Templates thoroughly - understanding YAML field types, creating a template manually (Exercise B), and designing your own template (Exercise D).

      -

      Alex: Keep the teaching thread moving. This is where What it does becomes real: an interactive wizard that guides you through building GitHub issue templates step-by-step using VS Code's Ask Questions feature. That matters in practice: Instead of writing YAML syntax, answer simple questions and the agent generates production-ready templates. The workshop is closer to rehearsal than lecture. You hear the move, try the move, and then check what changed.

      +

      Jamie: Let's pause on Enabling/viewing. What should a learner take away from it?

      +

      Alex: Here is the plain-English version of Enabling/viewing. Why it matters for security: The dependency graph feeds Dependabot. Put another way, if a vulnerability is found in a library, Dependabot uses this graph to identify which repos use the affected version and opens automated PRs to update them.

      +

      Alex: The practical takeaway is this. Settings → Security & Analysis → Dependency graph → Enable. Navigate to Insights → Dependency graph.

      +

      Alex: Keep the teaching thread moving. This is where 16. Network and Forks becomes real: the Network view shows a graphical branch/fork network - who has forked the repo, what branches exist, and how they diverge. That matters in practice: The network graph is a canvas visualization not accessible to screen readers. The workshop is closer to rehearsal than lecture. You hear the move, try the move, and then check what changed.

      +

      Jamie: Let's pause on 17. Community Standards. What should a learner take away from it?

      +

      Alex: Keep the learner anchored in 17. Community Standards. The Community Standards view (found in the Insights sidebar or in the main repository homepage's "Recommended" sidebar section) shows a checklist of community health files. This is the part to say slowly: A fully green checklist signals a well-maintained project.

      -

      Jamie: How should a learner choose a tool without feeling judged by the choice?

      -

      Alex: Keep the learner anchored in Example commands. Manual YAML template creation takes 15-20 minutes and is error-prone. This is the part to say slowly: The Template Builder generates correct, tested templates in 2-3 minutes via guided questions.

      -

      Alex: Keep the teaching thread moving. The reason 5. Slash Commands and Prompts matters is that the repository includes 54+ slash commands defined as.prompt.md files in.github/prompts/. That gives the learner a simple foothold: type / in Copilot Chat to see the full command menu.

      -

      Jamie: How should they picture the shape of the workshop?

      -

      Alex: Start with Workshop Slash Command Quick Reference: The commands listed below are the ones most relevant to this workshop. The next useful detail is this: The full repository contains 54+ commands covering accessibility auditing, document scanning, framework-specific checks, and more.

      +

      Jamie: How do you keep commands from becoming magic words?

      +

      Alex: Start with Screen reader. There is something to understand, something to try, and something that proves the try worked.

      +

      Alex: Treat examples as spoken recipes, not decorations. You may hear something like H / 2 → "Community Standards" section heading; Tab → Each checklist item (links to add missing files). Read the command, understand what it changes, then run it only when the repository state matches the lesson.

      +

      Jamie: Let's pause on Comparing two releases (the Changelog). What should a learner take away from it?

      +

      Alex: Start with Comparing two releases (the Changelog): The compare URL (/compare/v1.0.0.v2.0.0) shows a diff of all commits and merged PRs between two tags.

      +

      Alex: Keep the teaching thread moving. Here is the plain-English version of Charts and graphs - general strategy. Most Insights charts are canvas or SVG visuals. Put another way, they announce as "image" or "graphic" to screen readers. It is like learning a transit route. The names of the stops matter because they tell you whether you are still going the right direction.

      -

      Alex: Keep the teaching thread moving. Here is the plain-English version of Reading Slash Command Definitions. Each /command corresponds to a.prompt.md file in.github/prompts/. Put another way, open any of them in VS Code to read what instructions it gives Copilot. It is like learning a transit route. The names of the stops matter because they tell you whether you are still going the right direction.

      -

      Jamie: Let's pause on Example: /a11y-update. What should a learner take away from it?

      -

      Alex: This is where Example: /a11y-update becomes real: file.github/prompts/a11y-update.prompt.md. That matters in practice: This is how you learn to write your own.

      -

      Alex: Keep the teaching thread moving. Start with Learning Cards: Slash Commands and Prompts. There is something to understand, something to try, and something that proves the try worked.

      -

      Alex: The practical takeaway is this. Type / in Copilot Chat to see all available slash commands -- your screen reader announces each command name as you arrow through the list. Slash commands are defined in.github/prompts/ as.prompt.md files -- open them in the Explorer to read what each command does before using it. Create your own command by copying an existing.prompt.md file, renaming it, and editing the instructions -- no code required. The / command menu appears as a dropdown list in Copilot Chat -- it scales with VS Code's font and zoom settings. Each command has a short description visible in the dropdown; use Ctrl+= to zoom if the text is too small. Open the.prompt.md file in the editor to read the full command definition at your preferred zoom level.

      +

      Jamie: Let's pause on 19. Accessibility Agents: /my-stats and /team-dashboard. What should a learner take away from it?

      +

      Alex: This is where 19. Accessibility Agents: /my-stats and /team-dashboard becomes real: instead of navigating GitHub's chart-heavy Insights UI, Accessibility Agents provides two commands that deliver the same data in text form directly in VS Code.

      +

      Alex: Keep the teaching thread moving. Keep the learner anchored in /my-stats. Shows your personal contribution statistics across all tracked repos.

      +

      Alex: The practical takeaway is this. PRs opened and merged. Issues filed and closed. Reviews conducted. Commits pushed. Compare to previous period.

      +

      Jamie: Let's pause on /team-dashboard. What should a learner take away from it?

      +

      Alex: The reason /team-dashboard matters is that shows team-wide activity across tracked repos - who contributed what, response times, review coverage. That gives the learner a simple foothold: next: Appendix T: Community and Social Back: Appendix R: Projects Deep Dive Teaching chapter: Chapter 08: Open Source Culture.

      +

      Alex: The practical takeaway is this. Per-person contribution summary. Review coverage (how many PRs got reviews). Open issues by assignee. CI health across team repos.

      -

      Jamie: Let's pause on 6. Contributing to the Ecosystem. What should a learner take away from it?

      -

      Alex: The reason 6. Contributing to the Ecosystem matters is that the 55 Accessibility Agents and 54+ slash commands are starting points. That gives the learner a simple foothold: the.agent.md format is open - you can create your own agents for any repeatable workflow, and contribute them back to the project.

      -

      Alex: Keep the teaching thread moving. Start with Two Types of Custom Agents: Informational agents - conversational; search, analyze, and present results. The next useful detail is this: Task-oriented agents - active; edit files, run commands, submit PRs. Think of it like entering a new building: first you find the lobby, then the room, then the door you actually need.

      -

      Alex: The practical takeaway is this. Perform GitHub searches with predefined scopes and filters. Present results in specific structured formats. Query GitHub API tools to answer questions. Execute external tools (linters, test suites, axe-core).

      -

      Jamie: Let's pause on Agent File Structure. What should a learner take away from it?

      -

      Alex: Here is the plain-English version of Agent File Structure. See also: Appendix L: Agents Reference has the complete agent.md format specification and examples. Put another way, every.agent.md file has two parts: YAML frontmatter (metadata) and a system prompt (markdown body).

      +

      Jamie: What should people carry with them after this?

      +

      Alex: Carry the map. Know what page or tool you are in, know which action you are taking, and know what confirmation should follow. If the confirmation is missing, pause. That pause is not wasted time; it is professional judgment.

      +

      Jamie: That is a better way to say it than just follow the steps.

      +

      Alex: Right. Steps matter, but understanding wins. That is episode 25. Next in the series is episode 26, where we keep building the same contributor muscles.

      +
      + +
      +

      57. Episode 28: Branch Protection and Rulesets

      +

      Required reviews, status checks, rulesets, and diagnosing blocked merges.

      +

      Based on: Appendix O: Branch Protection and Rulesets

      +

      Audio and transcript are being regenerated for this episode.

      +
      +Read Transcript - Episode 28: Branch Protection and Rulesets + +

      Transcript

      +

      Alex: Welcome to Git Going with GitHub, episode 28: Branch Protection and Rulesets. I am Alex. Today we are going to make Branch Protection and Rulesets something you can explain, practice, and recover from when the interface surprises you.

      +

      Jamie: And I am Jamie. I will be the voice of the learner who is willing to ask, what is this for, where am I, and how do I know I did it right?

      -

      Alex: Keep the teaching thread moving. This is where Frontmatter fields becomes real: restricting tool access is a security best practice - only grant what the agent actually needs.

      -

      Jamie: Let's pause on Example: Informational Agent - @insiders-a11y-tracker. What should a learner take away from it?

      -

      Alex: Keep the learner anchored in Example: Informational Agent - @insiders-a11y-tracker. This agent monitors VS Code Insiders releases for accessibility improvements. This is the part to say slowly: It searches the microsoft/vscode repository using predefined GitHub query syntax, so you never have to remember the exact filter parameters.

      -

      Jamie: Let's pause on Use it. What should a learner take away from it?

      -

      Alex: The reason Use it matters is that prerequisite: GitHub MCP server installed (github.com/github/github-mcp-server). The interface gets friendlier when it stops being a wall of controls and starts being a set of named places.

      -

      Alex: First, select @insiders-a11y-tracker from the agent picker. Then, ask: what shipped this month? or any keyboard navigation improvements in January? After that, the agent searches with repo:microsoft/vscode is:closed milestone:"[Month] [Year]" label:accessibility label:insiders-released and returns formatted results. The rhythm is simple: orient, act, verify, then continue.

      +

      Alex: The big idea today: Required reviews, status checks, rulesets, and diagnosing blocked merges. We will name the concept, explain why it matters, practice the move, and point out the checks that tell you the work is real.

      +

      Jamie: So the episode should work even if someone has not read the chapter yet.

      +

      Alex: Exactly. The transcript has to stand on its own. It can point toward practice, but it should teach the concept right here in the conversation.

      -

      Jamie: Let's pause on Example: Task-Oriented Agent - The Markdown Accessibility Assistant. What should a learner take away from it?

      -

      Alex: Start with Example: Task-Oriented Agent - The Markdown Accessibility Assistant: The GitHub Accessibility team published a complete walkthrough for building a Markdown Accessibility Assistant - a task-oriented agent that reviews Markdown files for accessibility issues and makes direct fixes. The next useful detail is this: This agent is the automated version of the accessibility review skills you built during Day 1.

      -

      Alex: The practical takeaway is this. Runs markdownlint-cli2 to catch structural problems (heading skips, bare URLs, missing blank lines). Reviews link text for descriptiveness. Flags missing or inadequate alt text and waits for your approval before changing it (alt text requires human judgment). Fixes heading hierarchy, list structure, and bare URL formatting directly.

      -

      Alex: Keep the teaching thread moving. Here is the plain-English version of Key Pattern: Tiered Decision-Making. This tiered approach - automate what can be objectively evaluated, flag what needs human judgment - is the right model for any accessibility agent. Put another way, it maximizes the agent's value while keeping humans in control of decisions that require context.

      -

      Jamie: Let's pause on Required Prerequisites for the Markdown Accessibility Assistant. What should a learner take away from it?

      -

      Alex: Start with Required Prerequisites for the Markdown Accessibility Assistant. There is something to understand, something to try, and something that proves the try worked.

      -

      Alex: The practical takeaway is this. GitHub MCP server installed and configured (github.com/github/github-mcp-server). Node.js installed (for npx markdownlint-cli2).

      +

      Jamie: Okay, set the room for us. What are we walking into?

      +

      Alex: Start with How Merging Rules Work and Why Your PR May Be Blocked: Who this is for: Contributors who have submitted a PR and are wondering why it cannot be merged yet, as well as workshop facilitators who configure branch protection for practice repositories.

      +

      Alex: A solid pull request habit is to separate three questions: what changed, why it changed, and what still needs review. That keeps the conversation useful instead of noisy.

      +

      Jamie: How would you walk the room through that step by step?

      +

      Alex: Start with Quick Navigation. There is something to understand, something to try, and something that proves the try worked.

      +

      Alex: First, what Branch Protection Does. Then, common Branch Protection Rules. After that, repository Rulesets - The Modern Approach. Finally, why Your PR Cannot Be Merged - Diagnosis Guide. Treat it like a recipe: do not add the next ingredient until the previous one is actually in the bowl.

      +

      Jamie: What does the learner do first, second, and then after that?

      +

      Alex: First, navigating the Merge Box with a Screen Reader. Then, status Checks - What They Are and What They Mean. After that, who Can Configure Branch Protection. Finally, workshop Repository Configuration Reference. It is a checklist, but a meaningful one: every item creates evidence that the next step is safe.

      +

      Alex: A solid navigation habit is to prove where you are before activating controls. Headings, landmarks, and the address bar are not trivia; they are your map.

      +

      Jamie: What is the one idea that makes the next few steps less mysterious?

      +

      Alex: This is where 1. What Branch Protection Does becomes real: a branch protection rule is a set of requirements that must be satisfied before a PR can be merged into a specific branch (typically main). That matters in practice: Think of branch protection as the quality gate for a repository's primary branch.

      +

      Alex: That shows up in the workshop in a few specific ways. Require that code is reviewed before it enters the default branch. Require that automated tests pass before merging. Prevent direct pushes to main without a PR. Ensure the branch is up-to-date before merging.

      -

      Jamie: Let's pause on From VS Code. What should a learner take away from it?

      -

      Alex: Start with From VS Code. There is something to understand, something to try, and something that proves the try worked.

      -

      Alex: First, open Copilot Chat (Ctrl+Shift+I / Cmd+Shift+I on macOS). Then, in the Chat input toolbar, select the Set Agent button. After that, select your custom agent from the agent picker. Finally, type your request - the agent executes in your local workspace. It is like walking a hallway with named doors: read the sign, enter the right room, then confirm where you landed.

      -

      Jamie: Let's pause on From GitHub.com (Task mode). What should a learner take away from it?

      -

      Alex: Start with From GitHub.com (Task mode). There is something to understand, something to try, and something that proves the try worked.

      -

      Alex: First, open Copilot Chat on GitHub.com. Then, select Task from the mode picker. After that, optionally select a custom agent from the agent picker. Finally, submit your request - the agent can create a PR automatically. The rhythm is simple: orient, act, verify, then continue.

      -

      Jamie: Let's pause on From an issue (Issue Assignment). What should a learner take away from it?

      -

      Alex: Start with From an issue (Issue Assignment). There is something to understand, something to try, and something that proves the try worked.

      -

      Alex: First, open any issue → Assignees → assign Copilot. Then, in the dialog, optionally select a custom agent. After that, select Assign - Copilot creates a branch, makes changes, and opens a PR. Think of it as a rail line: each stop confirms you are still on the right route before the next one.

      +

      Alex: Now bring the learner back to the room. Start with Learning Cards: What Branch Protection Does. There is something to understand, something to try, and something that proves the try worked.

      +

      Alex: For a learner, the useful signals are these. The merge box at the bottom of every PR page is where branch protection surfaces its requirements -- press End to jump to the bottom, then use H to find the merge heading. Each requirement is announced as a status line: "1 review required," "Some checks haven't completed yet," etc. -- listen for these before attempting to merge. If the Merge button says "disabled" or "grayed out," branch protection is blocking -- the status lines immediately above explain exactly what is needed. The merge box uses green (ready), yellow (pending), and red (blocked) indicators -- zoom in on the merge area to read the text labels next to each colored icon. The "Update branch" button appears as a secondary button above the merge button when your PR is behind main -- it can be easy to miss at high zoom. Required checks show checkmark or X icons that are small at default size -- browser zoom to 150%+ makes the pass/fail status easier to distinguish.

      +

      Jamie: What would you say to someone who is already bracing for this to be too much?

      +

      Alex: The reason Required Reviews matters is that the maintainer requires a minimum number of approving reviews before the PR can be merged. That gives the learner a simple foothold: example: "Require 1 approving review".

      +

      Alex: The parts worth keeping in working memory are these. Your PR shows a "1 review required" notice in the merge box. If a reviewer requests changes, their approval is revoked - you need at least one new approval after your latest push. After you push new commits, re-request review from the original reviewer.

      +

      Alex: That matters because of the next idea. Start with Required Status Checks: Automated workflows (GitHub Actions or third-party CI) must complete successfully before merging is allowed. Think of it like entering a new building: first you find the lobby, then the room, then the door you actually need.

      +

      Alex: The useful habit is simple: orient first, act second, verify third. That pause before acting is part of the work.

      -

      Jamie: What does someone need before they touch the keyboard?

      -

      Alex: Here is the plain-English version of Environment Setup for GitHub (Cloud Agents). When agents run on GitHub (not locally), they may need additional tools. Put another way, create a workflow file at.github/workflows/copilot-setup-steps.yml with a single job named copilot-setup-steps.

      -

      Jamie: Let's pause on To Create Your Own Agent. What should a learner take away from it?

      -

      Alex: Start with To Create Your Own Agent. There is something to understand, something to try, and something that proves the try worked.

      -

      Alex: First, create.github/agents/your-agent-name.agent.md. Then, write YAML frontmatter (name, description, tools). After that, write the system prompt - identity, capabilities, domain knowledge, behavioral rules, output format. Finally, save and reload VS Code (Ctrl+Shift+P → "Reload Window"). It is a checklist, but a meaningful one: every item creates evidence that the next step is safe.

      -

      Jamie: Before we leave To Create Your Own Agent, what is the practical point?

      -

      Alex: First, type @your-agent-name in Copilot Chat. It is like walking a hallway with named doors: read the sign, enter the right room, then confirm where you landed.

      -

      Jamie: What should the learner prove to themselves after each small task?

      -

      Alex: Keep the learner anchored in Exercise: Extend the Template Builder Agent. You've built templates manually (Chapters 15-16) and seen them in action. This is the part to say slowly: Now see how to harness AI to generate templates interactively, and learn to customize agents for your own projects.

      -

      Alex: The practical takeaway is this. Complete Chapters 15-16 (especially Exercise D - designing your own template). VS Code is installed and GitHub Copilot is active. You have forked accessibility-agents to your GitHub account. You have cloned your fork locally: git clone https://github.com/[your-username]/accessibility-agents.git.

      +

      Jamie: If I am listening before the workshop starts, what should settle in my mind first?

      +

      Alex: Here is the plain-English version of Example checks you may see. What "Required" means: The merge button is grayed out (or shows an error) until all required checks show a green checkmark. Put another way, a failing or pending check blocks the merge.

      +

      Alex: Here is what that changes in practice. ci / build - compiles the code. ci / test - runs the test suite. lint - code style checks. accessibility-check - automated accessibility scanning.

      +

      Alex: This is where the talk moves from concept to action. This is where Require Branches to Be Up to Date becomes real: before merging, your PR branch must include all changes from main. That matters in practice: This prevents merge conflicts from being introduced silently.

      +

      Alex: The room should hear these as checkpoints. The merge box shows: "This branch is out of date with the base branch". Button: "Update branch" - merges current main into your branch. Alternative: Rebase your branch (only if the maintainer permits rebase merges).

      +

      Alex: A solid Git habit is to know which branch you are on, what changed, and what confirmation you expect before you run the next command.

      +

      Jamie: Where do you want a learner to place their attention here?

      +

      Alex: Keep the learner anchored in Require Signed Commits. All commits in the PR must have a Verified badge (see Appendix D: Git Authentication). This is the part to say slowly: If your commits are unverified, the PR cannot be merged until you re-commit with signing enabled.

      -

      Jamie: Let's pause on Exercise 1: Generate a Template with the Agent. What should a learner take away from it?

      -

      Alex: The reason Exercise 1: Generate a Template with the Agent matters is that your Mission: Use the @template-builder agent to generate an accessibility bug report template interactively. That gives the learner a simple foothold: you'll experience the agent as an end-user and see what production-ready agent output looks like.

      -

      Alex: The practical takeaway is this. Left sidebar showing.github/, docs/, learning-room/, README.md, etc. The status bar at the bottom shows your current git branch (probably main). Alternative: Use menu: View → Copilot Chat. Copilot is now ready to receive instructions.

      -

      Alex: First, open VS Code. Then, file → Open Folder → select your locally cloned accessibility-agents folder. After that, the folder tree appears on the left showing the repository structure. Finally, verify you're in the right place: The folder name should be accessibility-agents at the top of the sidebar. The rhythm is simple: orient, act, verify, then continue.

      -

      Jamie: Before we leave Exercise 1: Generate a Template with the Agent, what is the practical point?

      -

      Alex: First, keyboard shortcut: Press Ctrl+Shift+I (Windows/Linux) or Cmd+Shift+I (macOS). Then, a chat panel opens on the right side of VS Code. After that, at the top, you see "Copilot Chat" and probably a text input at the bottom saying "Ask Copilot.". Finally, click in the chat input box (bottom of Copilot Chat panel). Think of it as a rail line: each stop confirms you are still on the right route before the next one.

      -

      Alex: Treat examples as spoken recipes, not decorations. You may hear something like Q: Template name?; A: Accessibility Bug Report; Q: What's it for?; A: Report screen reader and keyboard navigation issues; Q: First field name?; A: Screen Reader; Q: Field type?; A: dropdown; Q: Dropdown options? (comma-separated); A: NVDA, JAWS, VoiceOver,. Read the command, understand what it changes, then run it only when the repository state matches the lesson.

      -

      Jamie: Let's pause on Exercise 2: Extend the Agent for Your Project. What should a learner take away from it?

      -

      Alex: Start with Exercise 2: Extend the Agent for Your Project: Your Mission: Customize the Template Builder agent to recognize and guide a Security Vulnerability Report template. The next useful detail is this: This teaches you how to tailor agents for project-specific needs.

      -

      Alex: The practical takeaway is this. The file starts with YAML frontmatter (name, description, topics). Below that, sections like " How to Use", " Pre-Built Workflow". Search for the text "Pre-Built Workflow: Guided Accessibility Template".

      -

      Alex: First, in VS Code, navigate to.github/agents/. Then, file: template-builder.agent.md. After that, double-click to open it in the editor. Finally, you see the agent's instructions in Markdown format. Think of it as a rail line: each stop confirms you are still on the right route before the next one.

      -

      Jamie: Before we leave Exercise 2: Extend the Agent for Your Project, what is the practical point?

      -

      Alex: First, use Ctrl+F to open Find. Then, search for: Pre-Built Workflow. After that, press Enter to jump to the first match. Finally, you should land on the "Pre-Built Workflow: Guided Accessibility Template" section. Treat it like a recipe: do not add the next ingredient until the previous one is actually in the bowl.

      -

      Jamie: Let's pause on What you're adding. What should a learner take away from it?

      -

      Alex: Here is the plain-English version of What you're adding. If the agent doesn't recognize your new workflow. It is like learning a transit route. The names of the stops matter because they tell you whether you are still going the right direction.

      -

      Alex: The practical takeaway is this. A clear label for the new workflow. Instructions on how to invoke it. Pre-defined fields that make sense for security reports. Specific options for severity and vulnerability type. The agent recognizes your new workflow. Next time you invoke @template-builder with "create security template", it will follow your new guidance.

      -

      Alex: First, save the file: Ctrl+S. Then, you should see no error messages. After that, the agent file now includes your new Pre-Built Workflow. Finally, open Copilot Chat again: Ctrl+Shift+I. Treat it like a recipe: do not add the next ingredient until the previous one is actually in the bowl.

      -

      Jamie: Before we leave What you're adding, what is the practical point?

      -

      Alex: First, press Enter. Then, the agent should now ask vulnerability-specific questions. After that, commit your agent change. Finally, the extended agent is now in your fork. It is a checklist, but a meaningful one: every item creates evidence that the next step is safe.

      -

      Alex: Treat examples as spoken recipes, not decorations. You may hear something like git add.github/agents/template-builder.agent.md; git commit -m "feat: add security vulnerability template workflow to template-builder agent"; git push origin main. Read the command, understand what it changes, then run it only when the repository state matches the lesson.

      +

      Alex: Before the learner moves on. The reason Require Linear History matters is that only squash merges or rebase merges are permitted - no merge commits. That gives the learner a simple foothold: this keeps the commit history linear and readable. The interface gets friendlier when it stops being a wall of controls and starts being a set of named places.

      +

      Jamie: Give me the version that sounds like an instructor, not a manual.

      +

      Alex: Start with Lock Branch: A locked branch cannot receive any merges - it is effectively read-only. The next useful detail is this: This is sometimes used for archived repositories or during release freezes.

      +

      Alex: Hold that next to this. Here is the plain-English version of 3. Repository Rulesets - The Modern Approach. Repository Rulesets (introduced in late 2023) are the next generation of branch protection. Put another way, they extend branch protection rules.

      +

      Alex: The practical anchors are these. Organization-level rules - apply across all repos in an org from one place. Bypass lists - specific users or roles can be exempted from rules (e.g., release bots). Target multiple branches - one ruleset can target a pattern like release/ or v. Violation insights - audit log of when rules were bypassed and by whom.

      -

      Jamie: Let's pause on Exercise 3: Iterative Refinement with Agents. What should a learner take away from it?

      -

      Alex: This is where Exercise 3: Iterative Refinement with Agents becomes real: your Mission: Generate a template, then ask the agent to modify it incrementally. That matters in practice: This teaches you the iterative pattern that scales to all agent-assisted workflows.

      -

      Alex: The practical takeaway is this. Running a complete template generation (same as Exercise 1). The agent modifies the YAML it generated. The new checkbox appears in the YAML with proper formatting and indentation. It doesn't regenerate from scratch - just adds your change.

      -

      Alex: First, in Copilot Chat, type: @template-builder create a feature request template. Then, answer the agent's questions to build a feature request form. After that, let the agent generate the YAML. Finally, copy it to a file.github/ISSUE TEMPLATE/feature-request.yml. It is a checklist, but a meaningful one: every item creates evidence that the next step is safe.

      -

      Jamie: Before we leave Exercise 3: Iterative Refinement with Agents, what is the practical point?

      -

      Alex: First, once the template is generated, while still in the same chat conversation, ask. Then, the agent regenerates the YAML with your new checkbox added in the right place (usually as required field pre-validation). After that, follow up. Finally, the agent modifies the textarea field's attributes to enable code highlighting. It is like walking a hallway with named doors: read the sign, enter the right room, then confirm where you landed.

      -

      Jamie: Let's pause on What Comes Next. What should a learner take away from it?

      -

      Alex: Keep the learner anchored in What Comes Next. Your next step: explore the broader ecosystem. This is the part to say slowly: That is Accessibility Agents' promise: not to replace your thinking, but to amplify your skills across all 55 agents - and to grow through the contributions of everyone who uses it.

      -

      Alex: The practical takeaway is this. Browse the full agent list - which agents solve problems you face regularly? Try an Accessibility team agent: @contrast-master check this page or @alt-text-headings review this file. Try a Developer Tools agent: @python-specialist review this module for accessibility or @desktop-a11y-specialist audit this dialog. Think about what is missing: what agent would you build if you could?

      -

      Alex: First, generated a template using an agent (Exercise 1). Then, customized an agent for your domain (Exercise 2). After that, refined iteratively with agent help (Exercise 3). It is like walking a hallway with named doors: read the sign, enter the right room, then confirm where you landed.

      -

      Jamie: Let's pause on Learning Cards: Contributing to the Ecosystem. What should a learner take away from it?

      -

      Alex: Start with Learning Cards: Contributing to the Ecosystem. There is something to understand, something to try, and something that proves the try worked.

      -

      Alex: The practical takeaway is this. Agent.agent.md files use YAML frontmatter at the top (between --- delimiters) followed by Markdown body; in VS Code, use Ctrl+G to jump to line 1 and arrow through the frontmatter fields (name, description, tools) before reading the body instructions. When writing your own.agent.md, use VS Code's Outline view (Ctrl+Shift+O) to verify that your Markdown headings (Purpose, Capabilities, Responsibilities) are correctly nested -- malformed headings will not appear in the outline. Before submitting a PR with a new agent file, run the file through a YAML linter (install the YAML extension, or use yamllint from the terminal) -- frontmatter syntax errors silently break agent registration. YAML frontmatter fields are densely packed with colons and quotes; increase your editor font size or use a monospaced font with wide character spacing so name:, description:, and tools: are clearly distinct. The.agent.md files in the agents/ directory follow a consistent structure -- use the file explorer's icon theme or file nesting feature to visually group agent files separately from regular documentation. When reviewing existing agents for contribution ideas, use VS Code's split editor to place the agent file and the README side by side so you can cross-reference the agent's instructions with its documented capabilities.

      +

      Jamie: Let's pause on Rulesets vs. Branch Protection Rules. What should a learner take away from it?

      +

      Alex: This is where Rulesets vs. Branch Protection Rules becomes real: most repositories you encounter still use classic branch protection rules. That matters in practice: Rulesets will become more common as maintainers migrate.

      +

      Jamie: How do you keep commands from becoming magic words?

      +

      Alex: Keep the learner anchored in Finding and Reading Rulesets. If you want to understand why certain rules apply to a branch. This is the part to say slowly: Alternatively, PR merge box messages describe which rules are blocking - you don't need admin access to understand what's required. A good GitHub workflow is like a well-run meeting: everyone knows the topic, the next action, and who has the floor.

      +

      Alex: Treat examples as spoken recipes, not decorations. You may hear something like Repository → Insights tab → Rulesets (if you have access - contributors usually don't); Or: Repository → Settings → Rules → Rulesets (admin only). Read the command, understand what it changes, then run it only when the repository state matches the lesson.

      +

      Jamie: Let's pause on 4. Why Your PR Cannot Be Merged - Diagnosis Guide. What should a learner take away from it?

      +

      Alex: The reason 4. Why Your PR Cannot Be Merged - Diagnosis Guide matters is that when you open a PR and the merge button is grayed out or shows an error, the merge box tells you exactly what needs to happen.

      -

      Alex: Keep the teaching thread moving. Start with 7. The Bigger Picture: Teams, Orchestration, and Beyond VS Code: The 55 agents are not 55 independent tools. The next useful detail is this: They are organized into three teams that work together, and several orchestrator agents exist specifically to coordinate multi-agent workflows. Think of it like entering a new building: first you find the lobby, then the room, then the door you actually need.

      -

      Jamie: Let's pause on How the Three Teams Connect. What should a learner take away from it?

      -

      Alex: Here is the plain-English version of How the Three Teams Connect. In practice, a single task often spans multiple teams. Put another way, no single agent covers the entire workflow.

      -

      Alex: The practical takeaway is this. You ask @daily-briefing (GitHub Workflow) for your morning report. It flags a PR that changes ARIA attributes. You ask @pr-review (GitHub Workflow) to generate a structured review of that PR. The review notes potential accessibility impact. You invoke @aria-specialist (Accessibility) to deep-check the ARIA changes. It identifies a missing aria-expanded state on a disclosure widget. You fix the issue using patterns from @desktop-a11y-specialist (Developer Tools) if it is a desktop application, or directly in the HTML if it is a web project.

      -

      Alex: Keep the teaching thread moving. Start with Learning Cards: Teams and Orchestration. There is something to understand, something to try, and something that proves the try worked.

      -

      Alex: The practical takeaway is this. Orchestrator agents like @accessibility-lead coordinate multi-agent workflows -- invoke one and it delegates to specialists, announcing which agent it is calling. Multi-agent output appears in sequence in Copilot Chat -- press Alt+F2 after each response to read it in Accessible View before the next agent responds. The three teams are GitHub Workflow (what happened), Accessibility (is it correct), and Developer Tools (fix it) -- choose your entry point based on your current task. Orchestrator responses can be long -- use Accessible View (Alt+F2) or widen the Chat panel to read comfortably at high zoom. The workflow diagrams in this section are described in text -- no visual-only content is required to understand the agent coordination pattern. Each team's agents are listed in the tables in Section 3 -- refer back there to find the right specialist agent.

      +

      Alex: Here is the practical turn. Start with "X review required / X reviews required": What it means: The required number of approvals hasn't been reached yet.

      +

      Jamie: Turn that into a path someone can follow.

      +

      Alex: Start with What to do. There is something to understand, something to try, and something that proves the try worked.

      +

      Alex: First, request review from a codeowner or maintainer (right sidebar → Reviewers → request). Then, check if any reviews exist but requested changes - those count against you. After that, wait for the reviewer to submit their review. Finally, respond to requested changes by pushing new commits, then re-requesting review. Treat it like a recipe: do not add the next ingredient until the previous one is actually in the bowl.

      +

      Alex: Keep the thread going. This is where "Some checks haven't completed yet" or "Some checks were not successful" becomes real: what it means: A required status check is pending or failing. The workshop is closer to rehearsal than lecture. You hear the move, try the move, and then check what changed.

      -

      Jamie: Let's pause on Orchestrator Agents. What should a learner take away from it?

      -

      Alex: Keep the learner anchored in Orchestrator Agents. Four agents are specifically designed to coordinate others. This is the part to say slowly: You do not need to use orchestrators to get value from individual agents.

      -

      Alex: Keep the teaching thread moving. The reason High-Impact Agents to Try First matters is that rather than exploring all 55 agents at once, start with the ones that deliver immediate value based on Day 1 skills you already have. The interface gets friendlier when it stops being a wall of controls and starts being a set of named places.

      -

      Jamie: Let's pause on Slash Commands That Save the Most Time. What should a learner take away from it?

      -

      Alex: Start with Slash Commands That Save the Most Time: These commands work without invoking a full agent - type them directly in Copilot Chat. The next useful detail is this: The full list of 54+ commands is in Appendix L, and Episode 39 walks through all of them with examples.

      -

      Alex: The practical takeaway is this. /my-issues and /my-prs - Instant dashboard of your open work across all repos. /review-pr 14 - Full AI-generated review with inline suggestions, replacing manual line-by-line reading. /triage 22 - Label, priority, and assignment suggestions for any new issue. /daily-briefing - Morning snapshot of repository activity, PRs needing review, and stale issues.

      +

      Jamie: What is the ordered workflow?

      +

      Alex: Keep the learner anchored in What to do. If checks pass on main but fail on your PR: The issue is specific to your changes. This is the part to say slowly: If checks are stuck "in progress" for over 30 minutes: The workflow runner may have an issue - contact the maintainer.

      +

      Alex: First, scroll down to the merge box - expand "Show all checks". Then, find the failing check → click "Details" to see the full log. After that, fix the underlying issue (test failure, lint error, build error) in your branch. Finally, push new commits - checks re-run automatically. It is like walking a hallway with named doors: read the sign, enter the right room, then confirm where you landed.

      +

      Jamie: Give me the sequence, because order matters here.

      +

      Alex: First, wait for checks to complete (typically 1-5 minutes for most CI). The rhythm is simple: orient, act, verify, then continue.

      +

      Alex: Another way to ground it. The reason "This branch is out of date with the base branch" matters is that what it means: New commits were pushed to main after you created your PR branch. That gives the learner a simple foothold: the maintainer requires everything to be current.

      +

      Jamie: Let's pause on What to do. What should a learner take away from it?

      +

      Alex: A few details make that real. Click "Update branch" in the merge box - GitHub does a merge commit from main into your branch. Or locally: git fetch upstream && git rebase upstream/main then force-push (only if you are comfortable with rebase).

      -

      Alex: Keep the teaching thread moving. Here is the plain-English version of Running Agents Beyond VS Code. Accessibility Agents' agents run on your machine, in your editor, when you ask for them. Put another way, the same Markdown-authored pattern extends further.

      -

      Jamie: Let's pause on Scope 1: Your Editor (Accessibility Agents). What should a learner take away from it?

      -

      Alex: Start with Scope 1: Your Editor (Accessibility Agents). There is something to understand, something to try, and something that proves the try worked.

      -

      Alex: The practical takeaway is this. File lives in.github/agents/[name].agent.md in your workspace. Triggered by: You, when you type @[agent-name] in Copilot Chat. Runs on: Your machine, using your Copilot subscription. Reaches: Every repository your GitHub account has access to. Scale: All 55 agents available when the workspace is open.

      -

      Alex: Keep the teaching thread moving. Keep the learner anchored in Scope 2: Your Repository (Travels with Forks). When you fork accessibility-agents, all 55 agents come with it. This is the part to say slowly: You can edit them for your project's context. A good GitHub workflow is like a well-run meeting: everyone knows the topic, the next action, and who has the floor.

      -

      Alex: The practical takeaway is this. File lives in.github/agents/[name].agent.md in the repo. Triggered by: Any contributor who has Copilot and opens the repo as a VS Code workspace. Runs on: Their machine, using their Copilot subscription. Reaches: Their GitHub account's repositories.

      +

      Alex: This is the part worth saying out loud. Here is the plain-English version of "Commits must have verified signatures". What it means: Branch protection requires signed commits (see Appendix D: Git Authentication). It is like learning a transit route. The names of the stops matter because they tell you whether you are still going the right direction.

      +

      Jamie: Before we leave What to do, what is the practical point?

      +

      Alex: First, enable commit signing locally before making more commits. Then, for existing unsigned commits, you need to rebase-rewrite them - this is advanced; ask the maintainer if there is a workaround. It is a checklist, but a meaningful one: every item creates evidence that the next step is safe.

      +

      Alex: The next layer is this. Keep the learner anchored in "Merging is blocked". What it means: A ruleset or branch protection has explicitly blocked merging for a reason not covered by other messages. This is the part to say slowly: Check the PR for a pinned comment from the mergeable status check or a GitHub Actions check that posts a comment explaining the block.

      -

      Jamie: Let's pause on Scope 3: The Cloud (GitHub Agentic Workflows). What should a learner take away from it?

      -

      Alex: The reason Scope 3: The Cloud (GitHub Agentic Workflows) matters is that the workflow runs whether or not anyone is watching - when an issue is opened at 3am, the agentic response fires. That gives the learner a simple foothold: the link between Accessibility Agents and Agentic Workflows: Both use Markdown-authored instructions.

      -

      Alex: The practical takeaway is this. File lives in.github/workflows/[name].md (same folder as standard Actions YAML). Triggered by: Any GitHub event - issues: opened, pull request: created, schedule. Runs on: GitHub Actions infrastructure, serverlessly. Reaches: The repository where the workflow is defined.

      -

      Alex: Keep the teaching thread moving. Start with Go Deeper: For full documentation on every agent, all 54+ slash commands, customization formats, and troubleshooting, see Appendix L: Accessibility Agents Reference. The next useful detail is this: For the audio version, listen to Episode 39: Accessibility Agents - Complete Reference.

      -

      Jamie: Let's pause on Example: Auto-triage accessibility issues. What should a learner take away from it?

      -

      Alex: Here is the plain-English version of Example: Auto-triage accessibility issues. File.github/workflows/auto-triage-a11y.md. Put another way, this runs automatically on every new issue.

      +

      Jamie: Let's pause on Learning Cards: Why Your PR Cannot Be Merged. What should a learner take away from it?

      +

      Alex: Start with Learning Cards: Why Your PR Cannot Be Merged. There is something to understand, something to try, and something that proves the try worked.

      +

      Alex: On the ground, that means a few things. Navigate to the merge box (End key, then H key to find "Merge" heading) and read each status line with arrow keys -- the messages tell you exactly what action to take. When a check fails, Tab to the "Details" link next to the failing check name and press Enter to open the log -- use Ctrl+F to search for "error" or "failed". After pushing a fix, the checks re-run automatically -- return to the PR page and listen for the status to change from "pending" to "passed". Failed checks show a red X icon that can be tiny -- zoom to 150%+ and look for the word "failing" or "failed" next to each check name. The "Update branch" button (for out-of-date PRs) is a secondary action that blends in at low zoom -- look for it directly above the main merge button. The Details link next to each check opens a log page with monospace text -- increase your editor or browser font size before reading long CI logs.

      +

      Alex: That connects to another useful point. Start with 5. Navigating the Merge Box with a Screen Reader: The merge box lives at the bottom of every PR page. The next useful detail is this: With a screen reader, navigating to it efficiently is important. Think of it like entering a new building: first you find the lobby, then the room, then the door you actually need.

      +

      Jamie: Let's pause on Reading Check Details. What should a learner take away from it?

      +

      Alex: Here is the plain-English version of Reading Check Details. The check log is a text-heavy page in a pre-formatted block.

      -

      Alex: Keep the teaching thread moving. This is where 8. GitHub Desktop, GitHub CLI, and Copilot CLI becomes real: these tools are not required for this workshop, but are worth knowing as options for different workflows. The workshop is closer to rehearsal than lecture. You hear the move, try the move, and then check what changed.

      -

      Jamie: Let's pause on GitHub Desktop. What should a learner take away from it?

      -

      Alex: Keep the learner anchored in GitHub Desktop. A graphical Git application with an accessible interface. This is the part to say slowly: When to use: If command-line Git feels overwhelming, GitHub Desktop provides a GUI alternative.

      -

      Alex: The practical takeaway is this. Download: desktop.github.com. Useful for: Visual diff review, simpler branch management. Screen reader support: Partial - keyboard navigation works for core flows.

      -

      Alex: Keep the teaching thread moving. The reason GitHub CLI (gh) matters is that a command-line interface for GitHub operations.

      +

      Alex: Keep the teaching thread moving. This is where 6. Status Checks - What They Are and What They Mean becomes real: status checks come from two sources.

      +

      Jamie: Let's pause on GitHub Actions Status Checks. What should a learner take away from it?

      +

      Alex: Keep the learner anchored in GitHub Actions Status Checks. Defined in.github/workflows/.yml in the repository. This is the part to say slowly: Each job: in a workflow file becomes a status check.

      +

      Alex: Keep the teaching thread moving. The reason Third-Party Status Checks matters is that services like Netlify, Vercel, Codecov, and Snyk post status checks via the GitHub API. That gives the learner a simple foothold: the learner will recognize them by their app name prefix (e.g., netlify/deploy-preview - Deploy Preview ready). The interface gets friendlier when it stops being a wall of controls and starts being a set of named places.

      -

      Jamie: What should they understand before typing anything?

      -

      Alex: Start with Authenticate. There is something to understand, something to try, and something that proves the try worked.

      -

      Alex: Treat examples as spoken recipes, not decorations. You may hear something like gh auth login. Read the command, understand what it changes, then run it only when the repository state matches the lesson.

      -

      Jamie: Let's pause on Common commands. What should a learner take away from it?

      -

      Alex: Here is the plain-English version of Common commands. Screen reader advantage: gh output is plain text with no dynamic regions - more predictable than the browser for certain operations. It is like learning a transit route. The names of the stops matter because they tell you whether you are still going the right direction.

      -

      Alex: Treat examples as spoken recipes, not decorations. You may hear something like gh issue list List issues in current repo; gh issue view 42 Read issue 42; gh pr list List pull requests; gh pr view 14 Read PR 14; gh pr create Create a new PR interactively; gh pr merge 14 Merge PR 14; gh repo clone owner/repo Clone a repository; gh repo. Read the command, understand what it changes, then run it only when the repository state matches the lesson.

      -

      Jamie: Let's pause on GitHub Copilot CLI (gh copilot). What should a learner take away from it?

      -

      Alex: This is where GitHub Copilot CLI (gh copilot) becomes real: an extension that adds Copilot to the terminal.

      +

      Jamie: Let's pause on 7. Who Can Configure Branch Protection. What should a learner take away from it?

      +

      Alex: Start with 7. Who Can Configure Branch Protection: As a workshop participant, you are typically a contributor to the main community-access/accessibility-agents repo and an admin of your own fork. The next useful detail is this: On your fork, you can configure branch protection however you like - including disabling it entirely for practice purposes.

      +

      Alex: Keep the teaching thread moving. Here is the plain-English version of 8. Workshop Repository Configuration Reference. The community-access/accessibility-agents repository uses the following branch protection configuration on main. Put another way, your personal fork of accessibility-agents has no branch protection by default.

      +

      Jamie: Let's pause on Related Resources. What should a learner take away from it?

      +

      Alex: This is where Related Resources becomes real: next: Appendix P: Security Features Back: Appendix N: Advanced Search Teaching chapter: Chapter 08: Open Source Culture.

      +

      Alex: These are the details that keep the idea from floating away. Appendix D - Git Authentication and Commit Signing. Appendix Q - GitHub Actions Workflows. Appendix L - GitHub Security Features.

      -

      Jamie: Let's pause on Install. What should a learner take away from it?

      -

      Alex: Start with Install. There is something to understand, something to try, and something that proves the try worked.

      -

      Alex: Treat examples as spoken recipes, not decorations. You may hear something like gh extension install github/gh-copilot. Read the command, understand what it changes, then run it only when the repository state matches the lesson.

      -

      Jamie: Let's pause on Commands. What should a learner take away from it?

      -

      Alex: The reason Commands matters is that use case: When you know what you want to do but are unsure of the exact git command syntax.

      -

      Alex: Treat examples as spoken recipes, not decorations. You may hear something like Ask Copilot to explain a command; gh copilot explain "git rebase -i HEAD 3"; Ask Copilot to suggest a command; gh copilot suggest "undo my last commit but keep the changes"; Ask Copilot to write a shell script; gh copilot suggest "create a script that finds. Read the command, understand what it changes, then run it only when the repository state matches the lesson.

      -

      Jamie: Let's pause on Example session. What should a learner take away from it?

      -

      Alex: Start with Example session. There is something to understand, something to try, and something that proves the try worked.

      -

      Alex: Treat examples as spoken recipes, not decorations. You may hear something like $ gh copilot suggest "show me all commits from last week"; Suggestion: git log --since="1 week ago" --oneline; Run this command? (Y/n). Read the command, understand what it changes, then run it only when the repository state matches the lesson.

      +

      Jamie: What should people carry with them after this?

      +

      Alex: Carry the map. Know what page or tool you are in, know which action you are taking, and know what confirmation should follow. If the confirmation is missing, pause. That pause is not wasted time; it is professional judgment.

      +

      Jamie: That is a better way to say it than just follow the steps.

      +

      Alex: Right. Steps matter, but understanding wins. That is episode 28. Next in the series is episode 29, where we keep building the same contributor muscles.

      +
      +
      -

      Jamie: Let's pause on Learning Cards: GitHub Desktop, GitHub CLI, and Copilot CLI. What should a learner take away from it?

      -

      Alex: Start with Learning Cards: GitHub Desktop, GitHub CLI, and Copilot CLI. There is something to understand, something to try, and something that proves the try worked.

      -

      Alex: The practical takeaway is this. GitHub Desktop is a native application -- on Windows it uses UI Automation, not a browser DOM; your screen reader's object navigation (NVDA: Insert+Numpad) rather than browse mode is the correct approach for navigating its interface. GitHub CLI (gh) is entirely terminal-based; all output is plain text that your screen reader reads line by line -- pipe verbose output through head -20 or Select-Object -First 20 to avoid overwhelming your speech buffer. Copilot CLI (gh copilot suggest and gh copilot explain) presents interactive prompts in the terminal; listen for the "Run this command? (Y/n)" confirmation before pressing Enter to avoid executing unreviewed commands. GitHub Desktop inherits your Windows display scaling -- if text appears small, increase system-level scaling (Settings Display Scale) rather than looking for an in-app zoom option. Terminal output from gh and gh copilot uses your terminal's font and color settings; configure your terminal profile (Windows Terminal settings or iTerm2 preferences) with a high-contrast color scheme and large font for comfortable reading. Copilot CLI suggestions appear as plain text in the terminal, not in a styled panel -- they are easy to miss among other output; look for the indented suggestion block immediately after your prompt.

      -

      Alex: Keep the teaching thread moving. This is where "Agent not found" becomes real: issue: Typing @agent-name shows "No agent found.".

      -

      Jamie: Let's pause on Solutions. What should a learner take away from it?

      -

      Alex: Start with Solutions. There is something to understand, something to try, and something that proves the try worked.

      -

      Alex: First, verify.github/agents/[name].agent.md exists in your workspace. Then, reload VS Code window: Ctrl+Shift+P → "Reload Window". After that, check file naming: must end with.agent.md. Finally, verify YAML frontmatter is valid (no syntax errors). It is like walking a hallway with named doors: read the sign, enter the right room, then confirm where you landed.

      +

      58. Episode 29: GitHub Security Features

      +

      Dependabot, secret scanning, code scanning, and private security advisories.

      +

      Based on: Appendix P: GitHub Security Features

      + + +

      Download Episode 29 (MP3)

      +
      +Read Transcript - Episode 29: GitHub Security Features + +

      Transcript

      +

      Alex: Welcome back to Git Going with GitHub. This is episode 29: GitHub Security Features. I am Alex, and today we are turning GitHub Security Features from a list of instructions into a working mental model.

      +

      Jamie: And I am Jamie. I will stop us whenever the instructions sound simple on paper but might feel different with a keyboard and screen reader.

      -

      Alex: Keep the teaching thread moving. The reason Agent produces incorrect output matters is that issue: Agent's response is wrong or misses context. The interface gets friendlier when it stops being a wall of controls and starts being a set of named places.

      -

      Jamie: Before we leave Solutions, what is the practical point?

      -

      Alex: First, provide more context in your prompt: Be specific about what you need. Then, use @ mentions: Reference specific files or selections (@filename.md, selection). After that, check the agent's prerequisites: Did you do the manual work first? Finally, review the agent's instructions: Open.github/agents/[name].agent.md and read what it's supposed to do. Think of it as a rail line: each stop confirms you are still on the right route before the next one.

      -

      Alex: Keep the teaching thread moving. Here is the plain-English version of Slash command doesn't work. Issue: /command shows "Command not found.".

      +

      Alex: Dependabot, secret scanning, code scanning, and private security advisories. That is the surface description. Underneath it, we are building judgment: where to focus, what to ignore, and how to verify the result.

      +

      Jamie: So we are not using the audio as a shortcut around learning. We are using it to make the learning easier to enter.

      +

      Alex: Yes. A good audio lesson gives someone enough context to try the work with confidence, even before they open the written material.

      -

      Jamie: What is the teaching move inside Solutions?

      -

      Alex: This is where Solutions becomes real: next: Chapter 20: Build Your Agent Back: Chapter 18: Fork and Contribute Related appendices: Appendix L: Agents Reference Appendix K: Copilot Reference.

      -

      Alex: First, verify.github/prompts/[name].md exists. Then, reload window: Ctrl+Shift+P → "Reload Window". After that, check file naming: must be a.md file in.github/prompts/. Finally, try typing the full command name (autocomplete may be incomplete). It is a checklist, but a meaningful one: every item creates evidence that the next step is safe.

      -

      Alex: Keep the teaching thread moving. Keep the learner anchored in Complete Reference - Agents, Slash Commands, Instructions, Configuration Levels, and All File Formats. This is your comprehensive reference for Accessibility Agents and the full VS Code Copilot customization system. This is the part to say slowly: The ecosystem includes 55 agents across 3 teams and 5 platforms, plus 54+ slash commands, 17 skills, and 6 instruction files. A good GitHub workflow is like a well-run meeting: everyone knows the topic, the next action, and who has the floor.

      -

      Jamie: Let's pause on 1. The Full Agent Ecosystem. What should a learner take away from it?

      -

      Alex: The reason 1. The Full Agent Ecosystem matters is that accessibility Agents includes 55 agents organized into three specialized teams, available on five platforms.

      +

      Jamie: Okay, set the room for us. What are we walking into?

      +

      Alex: Start with Dependabot, Secret Scanning, Code Scanning, and Private Advisories: Who this is for: Anyone contributing to open source repositories needs to understand how GitHub protects code and what security alerts mean. The next useful detail is this: This appendix explains the GitHub Security and quality tab, how to interpret and respond to alerts, and how to responsibly report vulnerabilities - including in community-access/accessibility-agents.

      +

      Alex: A solid pull request habit is to separate three questions: what changed, why it changed, and what still needs review. That keeps the conversation useful instead of noisy.

      +

      Jamie: How would you walk the room through that step by step?

      +

      Alex: Start with Quick Navigation. There is something to understand, something to try, and something that proves the try worked.

      +

      Alex: First, the Security and quality tab - What It Contains. Then, dependabot - Automated Dependency Updates. After that, secret Scanning - Preventing Credential Leaks. Finally, code Scanning and CodeQL. Treat it like a recipe: do not add the next ingredient until the previous one is actually in the bowl.

      +

      Jamie: What does the learner do first, second, and then after that?

      +

      Alex: First, private Vulnerability Reporting. Then, the SECURITY.md File. After that, software Bill of Materials (SBOM). Finally, screen Reader Navigation of the Security and quality tab. It is a checklist, but a meaningful one: every item creates evidence that the next step is safe.

      +

      Alex: A solid navigation habit is to prove where you are before activating controls. Headings, landmarks, and the address bar are not trivia; they are your map.

      +

      Jamie: What is the one idea that makes the next few steps less mysterious?

      +

      Alex: This is where 1. The Security and quality tab - What It Contains becomes real: every GitHub repository has a Security and quality tab in its navigation bar. That matters in practice: What you see there depends on whether you are a contributor with elevated access or a public viewer.

      -

      Alex: Keep the teaching thread moving. Start with Learning Cards: Agent Ecosystem Overview. There is something to understand, something to try, and something that proves the try worked.

      -

      Alex: The practical takeaway is this. Invoke any agent by typing @agent-name in Copilot Chat (Ctrl+Shift+I) -- the autocomplete list is keyboard-navigable with arrow keys. The 55 agents are organized into 3 teams (Accessibility, GitHub Workflow, Developer Tools) -- use H in the team tables to jump between headings. Agent responses appear in the Chat panel; press Alt+F2 (Accessible View) for a structured, non-streaming version. The agent team tables use consistent columns (Agent, Type, What It Does) -- increase font size so the narrow "Type" column remains readable. Agents work in the Chat panel with your current theme and font settings -- no separate UI to configure. The five supported platforms (VS Code, Claude Code, Gemini CLI, Claude Desktop, Codex CLI) share the same agent logic with platform-specific formatting.

      -

      Jamie: Let's pause on 2. GitHub Workflow Agents - Quick Reference. What should a learner take away from it?

      -

      Alex: Here is the plain-English version of 2. GitHub Workflow Agents - Quick Reference. The GitHub Workflow team includes 12 agents that automate common repository operations. Put another way, these are good starting points if you have completed the Day 1 skills - but explore any agent in the ecosystem that matches your workflow.\n\nInvoke any agent by typing @agent-name in Copilot Chat (Ctrl+Shift+I).

      -

      Alex: Keep the teaching thread moving. This is where @daily-briefing - Morning Briefing becomes real: agent file.github/agents/daily-briefing.agent.md. The workshop is closer to rehearsal than lecture. You hear the move, try the move, and then check what changed.

      +

      Alex: Now bring the learner back to the room. Start with Public viewers see. There is something to understand, something to try, and something that proves the try worked.

      +

      Alex: For a learner, the useful signals are these. Security policy (if the repo has a SECURITY.md). The private vulnerability reporting form (if enabled by the maintainer).

      +

      Jamie: What would you say to someone who is already bracing for this to be too much?

      +

      Alex: Start with Contributors with write or admin access see. There is something to understand, something to try, and something that proves the try worked.

      +

      Alex: The parts worth keeping in working memory are these. Dependabot alerts. Secret scanning alerts. Code scanning alerts. Security advisories. The ability to manage security settings.

      +

      Alex: The useful habit is simple: orient first, act second, verify third. That pause before acting is part of the work.

      +

      Alex: That matters because of the next idea. Start with Learning Cards: The Security and quality tab. There is something to understand, something to try, and something that proves the try worked.

      +

      Alex: On the ground, that means a few things. Use G then S (GitHub keyboard shortcut) to jump directly to the Security and quality tab from any repo page -- much faster than Tab-navigating the full nav bar. The Security and quality tab content varies by your access level -- public viewers see only the security policy and vulnerability reporting form; contributors with write access see alerts. Dependabot alerts, secret scanning alerts, and code scanning alerts are each a separate link inside the Security and quality tab -- use K to navigate between them. The Security and quality tab link sits in the repository's top navigation bar alongside Code, Issues, PRs, and Actions -- zoom in if the tab labels are small. Alert severity badges (Critical, High, Medium, Low) use colored labels -- each badge also includes the severity word, so color is not the only indicator. If the Security and quality tab shows "No alerts," that is good news -- look for the green shield icon next to the tab name as confirmation.

      -

      Jamie: Let's pause on Output sections (H2 headings - navigate with H). What should a learner take away from it?

      -

      Alex: Start with Output sections (H2 headings - navigate with H). There is something to understand, something to try, and something that proves the try worked.

      -

      Alex: The practical takeaway is this. Needs Your Action. Pull Requests Waiting for Your Review. @Mentions Requiring Response. CI Failures on Your Branches. For Your Awareness. Issues Opened Since Yesterday.

      -

      Alex: Keep the teaching thread moving. The reason @issue-tracker - Issue Management matters is that agent file.github/agents/issue-tracker.agent.md. That gives the learner a simple foothold: the agent drafts replies.

      -

      Jamie: Let's pause on @pr-review - Pull Request Review. What should a learner take away from it?

      -

      Alex: Start with @pr-review - Pull Request Review: Agent file.github/agents/pr-review.agent.md.

      +

      Jamie: If I am listening before the workshop starts, what should settle in my mind first?

      +

      Alex: Here is the plain-English version of 2. Dependabot - Automated Dependency Updates. Dependabot is GitHub's automated dependency monitoring and update system.

      +

      Alex: This is where the talk moves from concept to action. This is where Dependabot Alerts becomes real: when a known security vulnerability (CVE - Common Vulnerability and Exposure) is discovered in a package your project depends on, GitHub creates a Dependabot alert.

      +

      Jamie: Turn that into a path someone can follow.

      +

      Alex: Start with What to do as a contributor when you see an alert. There is something to understand, something to try, and something that proves the try worked.

      +

      Alex: First, read the advisory to understand the vulnerability scope. Then, check whether the project actually uses the vulnerable code path. After that, the fix is almost always: update the dependency to the fixed version. Finally, dependabot Security Updates may have already opened a PR - check the PRs tab. It is like walking a hallway with named doors: read the sign, enter the right room, then confirm where you landed.

      -

      Alex: Keep the teaching thread moving. Here is the plain-English version of Output sections (H2/H3 headings). Critical rule: The agent produces a starting point. Put another way, read it, edit it, post it under your own name. It is like learning a transit route. The names of the stops matter because they tell you whether you are still going the right direction.

      -

      Alex: The practical takeaway is this. Risk Assessment (High / Medium / Low). Files Changed (per-file descriptions). Suggested Inline Comments (prefixed: nit:, question:, suggestion:, important:, blocking:, praise:). Questions for the Author.

      -

      Jamie: Let's pause on @analytics - Team Analytics. What should a learner take away from it?

      -

      Alex: This is where @analytics - Team Analytics becomes real: agent file.github/agents/analytics.agent.md.

      -

      Alex: Keep the teaching thread moving. Keep the learner anchored in @insiders-a11y-tracker - Accessibility Change Monitor. Agent file.github/agents/insiders-a11y-tracker.agent.md.

      +

      Alex: Before the learner moves on. The reason Dependabot Security Updates matters is that if enabled, Dependabot automatically opens a PR to update the vulnerable dependency. That gives the learner a simple foothold: as a contributor with access, reviewing and merging these Dependabot PRs is a high-value, low-risk way to contribute. The interface gets friendlier when it stops being a wall of controls and starts being a set of named places.

      +

      Jamie: Give me the version that sounds like an instructor, not a manual.

      +

      Alex: Start with Dependabot Version Updates: Beyond security fixes, Dependabot can be configured to open PRs keeping all dependencies at their latest versions (not just security fixes). The next useful detail is this: This is configured in.github/dependabot.yml.

      +

      Alex: Hold that next to this. Here is the plain-English version of 3. Secret Scanning - Preventing Credential Leaks. Secret scanning detects if you accidentally commit tokens, API keys, passwords, or other credentials to a repository.

      -

      Jamie: Let's pause on What it monitors. What should a learner take away from it?

      -

      Alex: The reason What it monitors matters is that risk levels: High (regression), Medium (degraded), Low (improvement opportunity).

      -

      Alex: Keep the teaching thread moving. Start with @template-builder - Issue Template Wizard: Agent file.github/agents/template-builder.agent.md. Think of it like entering a new building: first you find the lobby, then the room, then the door you actually need.

      -

      Jamie: Let's pause on Guided workflow phases. What should a learner take away from it?

      -

      Alex: Here is the plain-English version of Guided workflow phases. Supported field types: markdown, input, textarea, dropdown, checkboxes.

      -

      Alex: First, metadata: name, description, title prefix, auto-labels. Then, fields (one at a time): type → label → description → required → type-specific options. After that, review and output: complete YAML ready to save to.github/ISSUE TEMPLATE/. Treat it like a recipe: do not add the next ingredient until the previous one is actually in the bowl.

      +

      Jamie: Where do you want a learner to place their attention here?

      +

      Alex: This is where Push Protection (Real-Time Prevention) becomes real: push Protection intercepts a git push before it reaches GitHub and blocks it if it detects a known secret pattern.

      +

      Jamie: What is the ordered workflow?

      +

      Alex: Keep the learner anchored in What to do. Best practice: Use environment variables for secrets, never hardcode them. A good GitHub workflow is like a well-run meeting: everyone knows the topic, the next action, and who has the floor.

      +

      Alex: First, remove the secret from the file immediately. Then, rotate the exposed credential (GitHub will automatically revoke detected GitHub tokens). After that, if it was a false positive, you can bypass with justification - but investigate first. It is like walking a hallway with named doors: read the sign, enter the right room, then confirm where you landed.

      +

      Jamie: Let's pause on Secret Scanning Alerts. What should a learner take away from it?

      +

      Alex: The reason Secret Scanning Alerts matters is that for public repositories, GitHub scans all existing commits and creates alerts for any detected secrets. That gives the learner a simple foothold: these appear in Security → Secret scanning.

      -

      Alex: Keep the teaching thread moving. This is where 3. Slash Commands and Prompts becomes real: the repository includes 54+ slash commands. That matters in practice: Type / in Copilot Chat to open the command menu.

      -

      Jamie: Let's pause on 4. Customization Primitives - Decision Guide. What should a learner take away from it?

      -

      Alex: Keep the learner anchored in 4. Customization Primitives - Decision Guide. Before creating any file, choose the right primitive for the job. This is the part to say slowly: Each primitive is a different file type with a different purpose, scope, and trigger.

      -

      Alex: Keep the teaching thread moving. Start with Instructions vs Agent? There is something to understand, something to try, and something that proves the try worked.

      -

      Alex: The practical takeaway is this. Instructions guide behavior passively (always-on or file-scoped). Agents perform tasks actively (on-demand, tool-using).

      +

      Alex: Here is the practical turn. Start with Learning Cards: Secret Scanning. There is something to understand, something to try, and something that proves the try worked.

      +

      Alex: Here is what that changes in practice. If your git push is blocked with "GH013: Repository rule violations found," the terminal output lists the exact file, line number, and secret type -- read the error lines carefully. After removing the secret from your code, use environment variables instead (process.env.GITHUB TOKEN) -- your screen reader will confirm the variable name in the code. Secret scanning alerts appear under Security and quality tab, Secret scanning -- navigate with T to reach the alert table, then arrow keys to read each row. Push Protection error messages appear in your terminal with red text -- increase terminal font size to read the file path, line number, and secret type clearly. The secret scanning alert list in the Security and quality tab uses a table layout -- zoom in to read the Secret type and Location columns. Environment variable names in code (like process.env.GITHUB TOKEN) are easier to spot when syntax highlighting is enabled in your editor theme.

      +

      Jamie: Let's pause on 4. Code Scanning and CodeQL. What should a learner take away from it?

      +

      Alex: Here is the plain-English version of 4. Code Scanning and CodeQL. Code scanning uses static analysis to find security vulnerabilities in the code itself (not dependencies). Put another way, GitHub's built-in tool is CodeQL, which understands the code's logic and can detect.

      +

      Alex: The room should hear these as checkpoints. SQL injection risks. Cross-site scripting (XSS) vulnerabilities. Path traversal issues. Insecure cryptography usage.

      +

      Alex: Keep the thread going. This is where Reading a Code Scanning Alert becomes real: as a contributor: Code scanning alerts are excellent, well-scoped contribution opportunities. That matters in practice: Each alert shows you the exact file, line, and the data flow causing the issue. The workshop is closer to rehearsal than lecture. You hear the move, try the move, and then check what changed.

      -

      Jamie: Let's pause on Prompt vs Agent? What should a learner take away from it?

      -

      Alex: Start with Prompt vs Agent? There is something to understand, something to try, and something that proves the try worked.

      -

      Alex: The practical takeaway is this. Use a prompt for a single focused task you invoke explicitly. Use an agent when the task spans multiple steps, needs different tools, or should work as a subagent for other agents.

      -

      Alex: Keep the teaching thread moving. Start with Prompt vs Skill? There is something to understand, something to try, and something that proves the try worked.

      -

      Alex: The practical takeaway is this. Both appear as / slash commands. Use a prompt for one well-defined task. Use a skill when the workflow bundles scripts, templates, or reference docs alongside the instructions.

      -

      Jamie: Let's pause on Instructions vs Hooks? What should a learner take away from it?

      -

      Alex: Start with Instructions vs Hooks? There is something to understand, something to try, and something that proves the try worked.

      -

      Alex: The practical takeaway is this. Instructions guide the agent (non-deterministic). Hooks enforce behavior via shell commands at lifecycle events - they run regardless of what the agent was prompted to do.

      +

      Jamie: Let's pause on Where to Find Code Scanning Alerts. What should a learner take away from it?

      +

      Alex: Keep the learner anchored in Where to Find Code Scanning Alerts. Security and quality tab → Code scanning → filter by severity, rule, or file.

      +

      Alex: Another way to ground it. The reason 5. Private Vulnerability Reporting matters is that when you discover a security vulnerability in a project, never report it as a public issue. That gives the learner a simple foothold: a public issue immediately broadcasts the vulnerability to anyone who could exploit it.

      +

      Jamie: Give me the sequence, because order matters here.

      +

      Alex: Start with How to Submit a Private Report. There is something to understand, something to try, and something that proves the try worked.

      +

      Alex: A few details make that real. Severity: Your assessment. Affected versions: Which versions are vulnerable. CVSS score: Optional - the Common Vulnerability Scoring System rating.

      +

      Alex: First, navigate to the repository's Security and quality tab. Then, select "Report a vulnerability" (this button only appears if the maintainer has enabled private reporting). After that, fill in the form. Finally, submit - only the maintainers see your report. Think of it as a rail line: each stop confirms you are still on the right route before the next one.

      -

      Alex: Keep the teaching thread moving. Start with Learning Cards: Customization Primitives. There is something to understand, something to try, and something that proves the try worked.

      -

      Alex: The practical takeaway is this. The decision table maps each file type to its purpose -- navigate with T (next table) in browse mode, then arrow through rows. Key distinction: instructions are passive (always-on guidance), agents are active (on-demand task performers), hooks are deterministic (shell commands at lifecycle events). Use the "Choosing Between Primitives" Q&A pairs below the table to decide which file type fits your need. The 7-row decision table is the single most important reference here -- zoom in on the "When to Use" column for the clearest guidance. Each Q&A pair under "Choosing Between Primitives" is a short paragraph -- easy to scan at high magnification. Color-coded syntax in YAML frontmatter examples benefits from a high-contrast theme with distinct keyword colors.

      -

      Jamie: Let's pause on 5. Scope and Priority - All Levels. What should a learner take away from it?

      -

      Alex: The reason 5. Scope and Priority - All Levels matters is that every customization file exists at one of three scopes. That gives the learner a simple foothold: VS Code combines all matching files from all scopes and sends them to the model.

      -

      Jamie: Let's pause on Priority Order (highest wins in conflicts). What should a learner take away from it?

      -

      Alex: Start with Priority Order (highest wins in conflicts). There is something to understand, something to try, and something that proves the try worked.

      -

      Alex: First, personal / User-level - your profile instructions override everything. Then, workspace / Repository-level -.github/copilot-instructions.md, AGENTS.md,.github/agents/.agent.md. After that, organization-level - organization-defined custom instructions (lowest priority). Think of it as a rail line: each stop confirms you are still on the right route before the next one.

      +

      Jamie: Let's pause on The Responsible Disclosure Process. What should a learner take away from it?

      +

      Alex: Start with The Responsible Disclosure Process. There is something to understand, something to try, and something that proves the try worked.

      +

      Alex: First, maintainers acknowledge your report (typically within 1-7 days for active projects). Then, they may ask follow-up questions in the private advisory thread. After that, they develop and test a fix. Finally, they request a CVE (Common Vulnerability and Exposure) number from GitHub. Treat it like a recipe: do not add the next ingredient until the previous one is actually in the bowl.

      +

      Jamie: Before we leave The Responsible Disclosure Process, what is the practical point?

      +

      Alex: First, they publish a new release with the fix. Then, they publish a public security advisory - you may be credited as the reporter. After that, the CVE is published publicly (usually 90 days after report or after the fix is released). It is a checklist, but a meaningful one: every item creates evidence that the next step is safe.

      +

      Jamie: Let's pause on What If the Maintainer Doesn't Respond? What should a learner take away from it?

      +

      Alex: This is where What If the Maintainer Doesn't Respond? becomes real: if a maintainer doesn't respond within a reasonable time (30-90 days is the standard window).

      +

      Alex: First, send a follow-up in the private advisory thread. Then, contact GitHub directly if the issue is critical (GitHub can assist with coordinated disclosure). After that, follow the project's SECURITY.md for their stated disclosure policy. It is a checklist, but a meaningful one: every item creates evidence that the next step is safe.

      +

      Alex: The next layer is this. Keep the learner anchored in 6. The SECURITY.md File. A SECURITY.md file at the repository root defines the project's security policy. This is the part to say slowly: accessibility-agents's security policy: community-access/accessibility-agents has a SECURITY.md that points to GitHub's private advisory form.

      +

      Alex: These are the details that keep the idea from floating away. Supported versions: Which versions receive security patches. Reporting instructions: How to report a vulnerability (email, private advisory form, etc.). Response timeline: How quickly maintainers aim to respond. Disclosure policy: When the project will publish a fix publicly.

      -

      Jamie: Let's pause on User-Level File Locations (Personal, Cross-Workspace). What should a learner take away from it?

      -

      Alex: Here is the plain-English version of User-Level File Locations (Personal, Cross-Workspace). All of these files roam with your VS Code Settings Sync. Put another way, on this machine: C:\Users\jeffb\AppData\Roaming\Code - Insiders\User\prompts.

      -

      Alex: First, enable Settings Sync (Ctrl+Shift+P → "Settings Sync: Turn On"). Then, ctrl+Shift+P → "Settings Sync: Configure". After that, check "Prompts and Instructions". Treat it like a recipe: do not add the next ingredient until the previous one is actually in the bowl.

      -

      Alex: Keep the teaching thread moving. This is where How Multiple Files Are Combined becomes real: VS Code collects all matching instruction files from all scopes and includes them all in the chat context. That matters in practice: There is no single winner - all are combined. The workshop is closer to rehearsal than lecture. You hear the move, try the move, and then check what changed.

      -

      Jamie: Let's pause on 6. Always-On Instructions - All File Types. What should a learner take away from it?

      -

      Alex: Keep the learner anchored in 6. Always-On Instructions - All File Types. Always-on instructions are automatically included in every chat request. This is the part to say slowly: You never invoke them - Copilot simply follows them.

      +

      Jamie: Let's pause on Navigating to a Repository's SECURITY.md. What should a learner take away from it?

      +

      Alex: Start with Navigating to a Repository's SECURITY.md. There is something to understand, something to try, and something that proves the try worked.

      +

      Alex: First, security and quality tab → Policies section → "Security policy" link. Then, or directly: https://github.com/owner/repo/security/policy. The rhythm is simple: orient, act, verify, then continue.

      +

      Alex: Treat examples as spoken recipes, not decorations. You may hear something like Security and quality tab → H → "Policy" heading → Link: "Security policy" → Enter. Read the command, understand what it changes, then run it only when the repository state matches the lesson.

      +

      Alex: This is the part worth saying out loud. Start with 7. Software Bill of Materials (SBOM): An SBOM is a machine-readable inventory of every component (libraries, packages, dependencies) in a software project. The next useful detail is this: It is increasingly required by enterprise and government organizations for supply chain security compliance. Think of it like entering a new building: first you find the lobby, then the room, then the door you actually need.

      +

      Jamie: Let's pause on Exporting an SBOM from GitHub. What should a learner take away from it?

      +

      Alex: Start with Exporting an SBOM from GitHub. There is something to understand, something to try, and something that proves the try worked.

      +

      Alex: That becomes easier when you listen for these cues. Your organization requires SBOM documentation before adopting an open source dependency. You're auditing a project's complete dependency chain. You want to identify license compatibility for a commercial product.

      +

      Alex: First, navigate to the repository's Insights tab. Then, select "Dependency graph". After that, select "Export SBOM" button (top right of the Dependency graph page). Finally, GitHub generates a SPDX-format JSON file listing all dependencies with their versions and licenses. Treat it like a recipe: do not add the next ingredient until the previous one is actually in the bowl.

      -

      Alex: Keep the teaching thread moving. The reason Option A.github/copilot-instructions.md (Recommended) matters is that version-controlled and team-shared. That gives the learner a simple foothold: auto-generate with: Type /init in Copilot Chat - VS Code analyzes your workspace and generates a tailored copilot-instructions.md.

      -

      Jamie: Let's pause on Option B: AGENTS.md (Multi-Tool / Monorepo). What should a learner take away from it?

      -

      Alex: Start with Option B: AGENTS.md (Multi-Tool / Monorepo): Best for: Projects that use multiple AI tools (Copilot, Claude Code, Gemini CLI, etc.) where a single instruction file should work across all of them. The next useful detail is this: Also best for monorepos where different folders need different rules.

      -

      Alex: Keep the teaching thread moving. Here is the plain-English version of Nested (per subfolder - experimental). Enable nested file support: chat.useNestedAgentsMdFiles: true in VS Code settings. Put another way, file structure: Same as copilot-instructions.md - plain Markdown, no frontmatter. It is like learning a transit route. The names of the stops matter because they tell you whether you are still going the right direction.

      +

      Alex: That connects to another useful point. This is where 9. Security and Accessibility Agents becomes real: accessibility Agents' /security-dashboard slash command gives you a quick security overview without visiting the Security and quality tab in the browser.

      +

      Jamie: Let's pause on Sample output. What should a learner take away from it?

      +

      Alex: Keep the learner anchored in Sample output. Next: Appendix Q: GitHub Actions Back: Appendix O: Branch Protection Teaching chapter: Chapter 08: Open Source Culture.

      -

      Jamie: Let's pause on Option C: CLAUDE.md (Claude Code Compatibility). What should a learner take away from it?

      -

      Alex: This is where Option C: CLAUDE.md (Claude Code Compatibility) becomes real: best for: Teams that use Claude Code alongside VS Code. That matters in practice: VS Code recognizes all four locations when chat.useClaudeMdFile is enabled (default: on).

      -

      Alex: Keep the teaching thread moving. Keep the learner anchored in Option D: Settings-Based Instructions (Deprecated). Settings-based instructions may be removed in a future VS Code version. This is the part to say slowly: Use file-based instructions instead for new work.

      -

      Jamie: Let's pause on Organization-Level Instructions (GitHub Enterprise). What should a learner take away from it?

      -

      Alex: The reason Organization-Level Instructions (GitHub Enterprise) matters is that organization administrators can define custom instructions that apply to all repositories in the organization. That gives the learner a simple foothold: every team member gets these instructions automatically.

      +

      Jamie: What should people carry with them after this?

      +

      Alex: Carry the map. Know what page or tool you are in, know which action you are taking, and know what confirmation should follow. If the confirmation is missing, pause. That pause is not wasted time; it is professional judgment.

      +

      Jamie: That is a better way to say it than just follow the steps.

      +

      Alex: Right. Steps matter, but understanding wins. That is episode 29. Next in the series is episode 30, where we keep building the same contributor muscles.

      +
      +
      -

      Alex: Keep the teaching thread moving. Start with To enable discovery in VS Code: Organization instructions are the lowest priority - workspace and user instructions override them when they conflict. Think of it like entering a new building: first you find the lobby, then the room, then the door you actually need.

      -

      Jamie: Let's pause on 7. File-Based Instructions (.instructions.md). What should a learner take away from it?

      -

      Alex: Here is the plain-English version of 7. File-Based Instructions (.instructions.md). File-based instructions load conditionally - either when the files you are editing match a glob pattern, or when the agent determines the instruction is relevant to the current task. Put another way, use for: Language-specific rules, framework conventions, module-specific standards that only apply to part of the codebase.

      -

      Alex: Keep the teaching thread moving. This is where The applyTo Glob Pattern becomes real: applyTo specifies which files trigger automatic inclusion of these instructions. That matters in practice: When a file matching the pattern is part of the chat context, the instructions are included automatically.

      +

      59. Episode 30: VS Code Accessibility Reference

      +

      Complete accessibility settings, audio signals, diff viewer, and screen reader configs.

      +

      Based on: Appendix G: VS Code Accessibility Reference

      + + +

      Download Episode 30 (MP3)

      +
      +Read Transcript - Episode 30: VS Code Accessibility Reference + +

      Transcript

      +

      Alex: This is Git Going with GitHub, episode 30: VS Code Accessibility Reference. I am Alex. By the end of this episode, VS Code Accessibility Reference should feel less like a wall of GitHub words and more like a set of moves you can trust.

      +

      Jamie: And I am Jamie. I am here for the practical questions: what should I listen for, what can go wrong, and what is the next calm move?

      -

      Jamie: Let's pause on Writing Effective Instructions. What should a learner take away from it?

      -

      Alex: Keep the learner anchored in Writing Effective Instructions. Guidance from GitHub's accessibility team on writing instructions that Copilot actually follows. This is the part to say slowly: Share your instructions: The github/awesome-copilot repository collects community-contributed instructions files.

      -

      Alex: The practical takeaway is this. Use normative language. Write MUST, MUST NOT, SHOULD, SHOULD NOT, and MAY for rules. LLMs respond well to these terms because they reduce ambiguity -- the same words used in WCAG. Example: Keyboard shortcuts MUST NOT override browser or OS shortcuts. Use lists and checklists. Structured lists provide guardrails that keep Copilot on track. Format accessibility requirements as a checklist so no criterion is overlooked. Specify your versions and standards. This application MUST conform to WCAG 2.2 Level AA is more useful than a general reference to accessibility. Include your design system's component names and flag deprecated components explicitly: DeprecatedButton MUST NOT. Focus on what Copilot doesn't already know. Instructions should add net-new information -- your team's conventions, exceptions, and priorities -- not restate what Copilot was trained on.

      -

      Jamie: Let's pause on Command Palette method. What should a learner take away from it?

      -

      Alex: Start with Command Palette method. There is something to understand, something to try, and something that proves the try worked.

      -

      Alex: First, ctrl+Shift+P → "Chat: New Instructions File". Then, choose Workspace or User Profile scope. After that, enter filename. Finally, add applyTo and/or description frontmatter. The rhythm is simple: orient, act, verify, then continue.

      -

      Jamie: Before we leave Command Palette method, what is the practical point?

      -

      Alex: First, write instructions. Think of it as a rail line: each stop confirms you are still on the right route before the next one.

      -

      Jamie: Let's pause on Quick creation method. What should a learner take away from it?

      -

      Alex: Start with Quick creation method: Type /instructions in the Chat input to open the Configure Instructions menu.

      +

      Alex: Today we are working on this: Complete accessibility settings, audio signals, diff viewer, and screen reader configs. I want the learner to leave with a mental map, not just a remembered path through buttons.

      +

      Jamie: So the goal is understanding first, then action, then confirmation.

      +

      Alex: Right. We are building a rhythm: orient yourself, take one intentional action, then verify what changed before moving on.

      -

      Alex: Keep the teaching thread moving. Here is the plain-English version of Model Fallback Array. The first available model in the array is used. Put another way, useful for environments where not all models are licensed.

      -

      Jamie: Let's pause on [Section Header]. What should a learner take away from it?

      -

      Alex: This is where [Section Header] becomes real: [Describe the exact output structure here with placeholders].

      -

      Jamie: Let's pause on Creating Your Own Agent. What should a learner take away from it?

      -

      Alex: Keep the learner anchored in Creating Your Own Agent. Write keyword-rich descriptions. This is the part to say slowly: The description is how other agents decide whether to delegate to yours. A good GitHub workflow is like a well-run meeting: everyone knows the topic, the next action, and who has the floor.

      -

      Alex: First, copy an existing.agent.md from.github/agents/. Then, edit the frontmatter (name, description, tools). After that, write clear step-by-step instructions in the body. Finally, add an Output Format section showing the expected structure. It is like walking a hallway with named doors: read the sign, enter the right room, then confirm where you landed.

      -

      Jamie: Before we leave Creating Your Own Agent, what is the practical point?

      -

      Alex: First, add Constraints and Scope Boundaries sections. Then, save to.github/agents/your-agent-name.agent.md. After that, reload VS Code: Ctrl+Shift+P → "Reload Window". Finally, type @your-agent-name in Copilot Chat. The rhythm is simple: orient, act, verify, then continue.

      +

      Jamie: Okay, set the room for us. What are we walking into?

      +

      Alex: Start with Complete Technical Reference for Screen Reader Users: Purpose: This appendix provides comprehensive technical documentation for all VS Code accessibility features, settings, and keyboard shortcuts. The next useful detail is this: The main chapters cover essentials; this appendix is your complete reference manual.

      +

      Alex: A solid navigation habit is to prove where you are before activating controls. Headings, landmarks, and the address bar are not trivia; they are your map.

      +

      Alex: The next layer is this. Start with Learning Cards: VS Code Accessibility Reference Overview. There is something to understand, something to try, and something that proves the try worked.

      +

      Alex: The practical anchors are these. This appendix is your lookup manual -- use Ctrl+G (Go to Line) or Ctrl+Shift+O (Go to Symbol) to jump directly to a setting name. Every table is structured with headers; use T in browse mode to jump between tables, then arrow through rows. Bookmark this file in VS Code (Ctrl+K Ctrl+K) so you can return instantly when you need a setting path. Increase editor font size (Ctrl+=) before scanning the long settings tables -- column values are easier to compare at larger sizes. Use the Minimap (if sighted enough) or breadcrumbs bar to orient within this large reference file. High-contrast themes make the table grid lines and code spans easier to distinguish from body text.

      +

      Jamie: What is the one idea that makes the next few steps less mysterious?

      +

      Alex: This is where 1. Complete Accessibility Settings Reference becomes real: all settings can be accessed via Settings UI (Ctrl+,) or by editing settings.json directly (Ctrl+Shift+P → "Open User Settings JSON").

      -

      Jamie: Let's pause on Learning Cards.agent.md - Complete Format Reference. What should a learner take away from it?

      -

      Alex: Start with Learning Cards.agent.md - Complete Format Reference. There is something to understand, something to try, and something that proves the try worked.

      -

      Alex: The practical takeaway is this. YAML frontmatter is the first block in the file between --- delimiters -- arrow through it line by line to verify name, description, and tools fields; indentation matters. The name field in frontmatter is what you type after @ in Copilot Chat -- if the agent does not appear, check this field matches your invocation and reload VS Code (Ctrl+Shift+P then "Reload Window"). Use Chat Diagnostics (gear icon in Chat header then Diagnostics) to verify your agent loaded successfully -- it lists every agent found, with error details if frontmatter parsing failed. Agent files are small Markdown documents typically under 100 lines -- increase editor font size and use a theme with distinct YAML keyword colors so frontmatter fields stand out. The tools list in frontmatter uses array syntax (["read", "search"]) -- at high zoom, verify commas and quotes are correct since YAML is sensitive to formatting. The body template structure (Constraints, Behavior, Output Format, Scope Boundaries) uses headings -- use VS Code's Outline view (Ctrl+Shift+O) to navigate between sections.

      -

      Alex: Keep the teaching thread moving. Start with Complete Frontmatter Reference. There is something to understand, something to try, and something that proves the try worked.

      -

      Jamie: Let's pause on Tool Priority When Agent Is Also Specified. What should a learner take away from it?

      -

      Alex: Here is the plain-English version of Tool Priority When Agent Is Also Specified. When both the prompt and the referenced agent define tools, VS Code uses this priority.

      -

      Alex: First, tools listed in the prompt file's frontmatter (highest priority). Then, tools from the referenced custom agent. After that, default tools for the selected agent mode. Treat it like a recipe: do not add the next ingredient until the previous one is actually in the bowl.

      +

      Alex: Now bring the learner back to the room. Keep the learner anchored in 2. Audio Cues - All Options. Audio cues provide non-verbal feedback through sound. This is the part to say slowly: Each cue can be configured independently.

      +

      Jamie: What would you say to someone who is already bracing for this to be too much?

      +

      Alex: The reason Accessing Audio Cue Settings matters is that settings UI: Ctrl+, → search "audio cue". That gives the learner a simple foothold: settings.json: Edit directly (see Section 7).

      +

      Alex: The useful habit is simple: orient first, act second, verify third. That pause before acting is part of the work.

      +

      Jamie: Give me the sequence, because order matters here.

      +

      Alex: Start with Customizing Signal Sounds: Advanced feature: You can replace default sounds with custom audio files. Think of it like entering a new building: first you find the lobby, then the room, then the door you actually need.

      +

      Alex: First, ctrl+Shift+P → "Preferences: Open User Settings (JSON)". Then, add custom sound paths. Think of it as a rail line: each stop confirms you are still on the right route before the next one.

      -

      Alex: Keep the teaching thread moving. Start with Input Parameters. There is something to understand, something to try, and something that proves the try worked.

      -

      Alex: The practical takeaway is this. parameterName - internal identifier (no spaces). The text after the second: is shown to the user as a placeholder or tooltip. Multiple parameters are supported in one prompt file.

      -

      Jamie: Let's pause on Creating Your Own Slash Command. What should a learner take away from it?

      -

      Alex: Keep the learner anchored in Creating Your Own Slash Command. Both prompts and agent skills appear as / slash commands. This is the part to say slowly: The difference: prompts are single-task Markdown files; skills are folders with bundled scripts and references.

      -

      Alex: First, copy an existing.prompt.md from.github/prompts/. Then, edit frontmatter (name, description, tools). After that, write the task instructions in plain English. Finally, add ${input.} placeholders where the user must provide values. It is like walking a hallway with named doors: read the sign, enter the right room, then confirm where you landed.

      -

      Jamie: Before we leave Creating Your Own Slash Command, what is the practical point?

      -

      Alex: First, save to.github/prompts/your-command.prompt.md. Then, reload VS Code: Ctrl+Shift+P → "Reload Window". After that, type /your-command to invoke it. The rhythm is simple: orient, act, verify, then continue.

      -

      Alex: Keep the teaching thread moving. Start with Learning Cards: Prompts and Slash Commands. There is something to understand, something to try, and something that proves the try worked.

      -

      Alex: The practical takeaway is this. Type / in Copilot Chat to see all available slash commands -- the autocomplete list reads each command name and description aloud.prompt.md files use YAML frontmatter for metadata (name, description, tools) followed by plain Markdown instructions. Use ${input:variableName} placeholders in prompts to create interactive fill-in-the-blank commands that prompt the user at invocation. The slash command picker popup is themed to match your current VS Code theme -- ensure your theme has sufficient contrast for dropdown items.prompt.md files are small Markdown files that are easy to read and edit at high zoom -- typically under 50 lines. The YAML frontmatter block at the top is indentation-sensitive -- use VS Code's indentation guides or a linter to verify structure.

      +

      Jamie: If I am listening before the workshop starts, what should settle in my mind first?

      +

      Alex: Start with Sound file requirements. There is something to understand, something to try, and something that proves the try worked.

      +

      Alex: Here is what that changes in practice. Format: WAV, MP3, or OGG. Duration: Keep under 2 seconds. Volume: Normalize to avoid clipping.

      +

      Alex: This is where the talk moves from concept to action. This is where 3. Accessible Diff Viewer - Complete Guide becomes real: the Accessible Diff Viewer presents file diffs as a structured, line-by-line list instead of a visual side-by-side view.

      +

      Alex: A solid pull request habit is to separate three questions: what changed, why it changed, and what still needs review. That keeps the conversation useful instead of noisy.

      +

      Jamie: Where do you want a learner to place their attention here?

      +

      Alex: Start with When to Use Accessible Diff Viewer. There is something to understand, something to try, and something that proves the try worked.

      +

      Alex: These are the details that keep the idea from floating away. Reviewing pull request changes. Resolving merge conflicts. Comparing file versions (Timeline view). Reviewing Copilot-generated edits. Any time you need to understand what changed in a file.

      -

      Jamie: Let's pause on 10. Agent Skills (SKILL.md) - Complete Format Reference. What should a learner take away from it?

      -

      Alex: Start with 10. Agent Skills (SKILL.md) - Complete Format Reference: A Skill is a folder - not a single file. The next useful detail is this: The folder contains SKILL.md plus any scripts, templates, and reference documents the skill needs.

      -

      Jamie: Let's pause on Progressive Loading - How VS Code Loads Skills. What should a learner take away from it?

      -

      Alex: This is where Progressive Loading - How VS Code Loads Skills becomes real: move reference material to references/ folder files.

      -

      Alex: First, discovery ( 100 tokens): Reads name and description to decide if the skill is relevant. Then, instructions (<5000 tokens): Loads the full SKILL.md body when the skill is relevant. After that, resources: Additional files (scripts/, references/) only load when explicitly referenced from SKILL.md. It is a checklist, but a meaningful one: every item creates evidence that the next step is safe.

      +

      Alex: Before the learner moves on. The reason Top-level structure matters is that the Accessible Diff Viewer starts with a header showing the file path and change summary. That gives the learner a simple foothold: it then shows each hunk (changed section) in order. The interface gets friendlier when it stops being a wall of controls and starts being a set of named places.

      +

      Jamie: How would you walk the room through that step by step?

      +

      Alex: Start with NVDA/JAWS. There is something to understand, something to try, and something that proves the try worked.

      +

      Alex: First, open diff: Enter on file in Source Control, or F7 in an open diff. Then, alt+F2 to open Accessible Diff Viewer. After that, navigate with Up/Down Arrow (line by line). Finally, use H key to jump between hunks (each hunk has a heading). Think of it as a rail line: each stop confirms you are still on the right route before the next one.

      +

      Jamie: What does the learner do first, second, and then after that?

      +

      Alex: First, escape to close and return to editor. Treat it like a recipe: do not add the next ingredient until the previous one is actually in the bowl.

      +

      Jamie: Turn that into a path someone can follow.

      +

      Alex: Start with VoiceOver. There is something to understand, something to try, and something that proves the try worked.

      +

      Alex: First, vO+Arrow to navigate to diff file → VO+Space to open. Then, option+F2 for Accessible Diff Viewer. After that, vO+Arrow keys to navigate lines. Finally, vO+Command+H to jump between hunk headings. Treat it like a recipe: do not add the next ingredient until the previous one is actually in the bowl.

      +

      Jamie: What is the ordered workflow?

      +

      Alex: First, escape to close. It is a checklist, but a meaningful one: every item creates evidence that the next step is safe.

      -

      Alex: Keep the teaching thread moving. Keep the learner anchored in 11. Hooks (.json) - Lifecycle Automation. Hooks execute shell commands at specific points in an agent's lifecycle. This is the part to say slowly: They are deterministic - they run regardless of what the agent was prompted to do.

      -

      Jamie: Let's pause on File Locations. What should a learner take away from it?

      -

      Alex: The reason File Locations matters is that hooks from all locations are combined - workspace and user hooks do not override each other.

      -

      Jamie: Let's pause on Configuration Format. What should a learner take away from it?

      -

      Alex: Start with Configuration Format. There is something to understand, something to try, and something that proves the try worked.

      -

      Alex: Treat examples as spoken recipes, not decorations. You may hear something like {; "hooks": {; "PreToolUse": [; {; "type": "command",; "command": ".github/hooks/validate-before-edit.sh",; "timeout": 15; }; ],; "PostToolUse": [; {; "type": "command",; "command": "npx prettier --write",; "windows": "npx.cmd prettier --write",; "timeout". Read the command, understand what it changes, then run it only when the repository state matches the lesson.

      +

      Jamie: Give me the version that sounds like an instructor, not a manual.

      +

      Alex: This is where Understanding Context Lines becomes real: the diff shows 3 unchanged lines before and after each change for context. That matters in practice: These are announced as "Unchanged: [content]".

      +

      Jamie: How do you keep commands from becoming magic words?

      +

      Alex: Keep the learner anchored in Example. The unchanged lines help you understand where in the file the change occurred. A good GitHub workflow is like a well-run meeting: everyone knows the topic, the next action, and who has the floor.

      +

      Alex: Treat examples as spoken recipes, not decorations. You may hear something like Hunk 1 of 3 - lines 42-48; Unchanged: Screen Reader Setup; Unchanged:; - Removed: This guide covers NVDA only.; + Added: This guide covers NVDA, JAWS, and VoiceOver.; Unchanged:; Unchanged: Installing NVDA. Read the command, understand what it changes, then run it only when the repository state matches the lesson.

      +

      Jamie: Let's pause on Inline view (recommended for screen readers). What should a learner take away from it?

      +

      Alex: Start with Inline view (recommended for screen readers). There is something to understand, something to try, and something that proves the try worked.

      +

      Alex: The parts worth keeping in working memory are these. All changes in a single editor. Removed lines followed by added lines. Easier to navigate with screen reader reading commands.

      -

      Jamie: Let's pause on PreToolUse permission decisions. What should a learner take away from it?

      -

      Alex: Here is the plain-English version of PreToolUse permission decisions. Permission decisions: "allow" "ask" (prompt user) "deny" (block the tool call).

      -

      Alex: Keep the teaching thread moving. Start with Exit codes. There is something to understand, something to try, and something that proves the try worked.

      -

      Alex: The practical takeaway is this. 0 - success; agent continues. 2 - blocking error; agent stops. Other - non-blocking warning.

      -

      Jamie: Let's pause on Learning Cards: Hooks. What should a learner take away from it?

      -

      Alex: Start with Learning Cards: Hooks. There is something to understand, something to try, and something that proves the try worked.

      -

      Alex: The practical takeaway is this. Hooks are JSON files, not Markdown -- navigate them in the editor with arrow keys; each hook event (e.g., PreToolUse, PostToolUse) is a key in the "hooks" object. Hook output is returned as JSON on stdout -- the "continue" field (true/false) determines whether the agent proceeds; listen for the "stopReason" message if the hook blocks an action. The "permissionDecision" values (allow, ask, deny) control tool access -- ask triggers a confirmation dialog that your screen reader will announce as a standard VS Code dialog. JSON syntax requires careful attention to braces, brackets, and commas -- use VS Code's bracket pair colorization (editor.bracketPairColorization.enabled) and increase font size to verify structure. The hook events table maps each event name to when it fires -- zoom in on the "When It Fires" column to understand the lifecycle timing. Hook errors appear in the agent session output -- look for non-zero exit codes or "continue": false in the output pane.

      +

      Alex: Here is the practical turn. Start with Side-by-side view (default, visual). There is something to understand, something to try, and something that proves the try worked.

      +

      Alex: On the ground, that means a few things. Left panel: original file. Right panel: modified file. Requires navigating between panels.

      +

      Jamie: Let's pause on To switch to inline view. What should a learner take away from it?

      +

      Alex: Start with To switch to inline view. There is something to understand, something to try, and something that proves the try worked.

      +

      Alex: First, open Settings: Ctrl+,. Then, search: "diffEditor.renderSideBySide". After that, uncheck the box (or set to false in settings.json). Treat it like a recipe: do not add the next ingredient until the previous one is actually in the bowl.

      +

      Alex: Keep the thread going. Start with Learning Cards: Accessible Diff Viewer. There is something to understand, something to try, and something that proves the try worked.

      +

      Alex: The room should hear these as checkpoints. Press F7 in any diff editor to jump to the first changed hunk -- then F7 / Shift+F7 to move between hunks. Use Alt+F2 (Accessible View) to read the full diff in a structured, non-streaming pane with proper line prefixes. Switch to inline diff view (diffEditor.renderSideBySide: false) so all changes appear in one editor instead of two panels. Inline diff view places removed and added lines back-to-back with color-coded backgrounds -- increase font size for easier scanning. Enable accessibility.signals.diffLineInserted and diffLineDeleted for audio feedback as you arrow through changed lines. Zoom the diff editor independently with Ctrl+= if the surrounding UI is already at a comfortable size.

      -

      Alex: Keep the teaching thread moving. The reason 12. preferences.md - Accessibility Agents Personal Settings matters is that copy.github/agents/preferences.example.md to.github/agents/preferences.md. That gives the learner a simple foothold: the file is in.gitignore - your private settings stay only in your local fork. The interface gets friendlier when it stops being a wall of controls and starts being a set of named places.

      -

      Jamie: Let's pause on Full File Template. What should a learner take away from it?

      -

      Alex: Start with Full File Template. There is something to understand, something to try, and something that proves the try worked.

      -

      Alex: Treat examples as spoken recipes, not decorations. You may hear something like My Accessibility Agents Preferences; My GitHub Username; your-github-username; Repositories I Work On Most; - community-access/accessibility-agents; - your-org/your-repo; Preferred Output Format; screen-reader-optimized; Notification Priority; Accessibility. Read the command, understand what it changes, then run it only when the repository state matches the lesson.

      -

      Jamie: What is the judgment call here?

      -

      Alex: Start with Preferred Output Format Options. There is something to understand, something to try, and something that proves the try worked.

      -

      Alex: Use the comparison to make a decision, not to recite a table. The main contrasts are: "concise" means Bullet points and short summaries, minimal prose. "detailed" means Full context and more explanation in every response. "screen-reader-optimized" means Heading-heavy structure, no tables, explicit empty-state messages.

      +

      Jamie: Let's pause on Recommended NVDA settings. What should a learner take away from it?

      +

      Alex: Start with Recommended NVDA settings. There is something to understand, something to try, and something that proves the try worked.

      +

      Alex: That becomes easier when you listen for these cues. NVDA Menu → Preferences → Settings → Browse Mode. "Maximum length of text on a single line": 10000. "Automatic focus mode for focus changes": Checked. "Automatic focus mode for caret movement": Unchecked. "Report tooltips": Unchecked (reduces interruptions; use Alt+F2 instead). "Report notifications": Checked.

      +

      Alex: First, browse Mode settings. Then, object Presentation. After that, speech settings. Finally, input Composition. It is like walking a hallway with named doors: read the sign, enter the right room, then confirm where you landed.

      +

      Alex: Another way to ground it. Start with NVDA add-ons for VS Code. There is something to understand, something to try, and something that proves the try worked.

      +

      Alex: A few details make that real. Focus Highlight - shows focus location visually (helpful for sighted trainers). IndentNav - navigate by indentation level (useful for Python, YAML).

      +

      Jamie: Let's pause on Recommended JAWS settings. What should a learner take away from it?

      +

      Alex: Start with Recommended JAWS settings. There is something to understand, something to try, and something that proves the try worked.

      +

      Alex: That shows up in the workshop in a few specific ways. "Auto Forms Mode": Checked. "ARIA Live Region Verbosity": Polite or Assertive (depending on preference). "Report tooltip text": Unchecked (use Alt+F2 instead). "Punctuation Level": Most (for code). "Speak Long Lines Continuously": Yes. "Blank Line Announcement": Tone (less verbose than speech).

      +

      Alex: First, settings Center → HTML/PDF/Accessibility. Then, settings Center → Reading. After that, settings Center → Text Processing. Think of it as a rail line: each stop confirms you are still on the right route before the next one.

      -

      Jamie: Let's pause on Notification Priority Options. What should a learner take away from it?

      -

      Alex: This is where Notification Priority Options becomes real: the @daily-briefing agent reads this to sort its output sections.

      -

      Alex: Keep the teaching thread moving. Keep the learner anchored in Review Comment Tone Options. The @pr-review and @issue-tracker agents read this when drafting comments. A good GitHub workflow is like a well-run meeting: everyone knows the topic, the next action, and who has the floor.

      -

      Jamie: Let's pause on Accessibility Context Options. What should a learner take away from it?

      -

      Alex: The reason Accessibility Context Options matters is that tells agents which screen reader and browser you use so they can tailor output and recommendations.

      -

      Alex: Treat examples as spoken recipes, not decorations. You may hear something like I use NVDA with Chrome on Windows 11.; I use VoiceOver with Safari on macOS Sonoma.; I use JAWS with Firefox on Windows 10.; I use Narrator with Edge on Windows 11.; I use TalkBack on Android. Read the command, understand what it changes, then run it only when the repository state matches the lesson.

      +

      Alex: This is the part worth saying out loud. Here is the plain-English version of JAWS scripts for VS Code. Custom JAWS scripts exist for VS Code. Put another way, check: jaws-vscode-scripts (GitHub) for community-maintained scripts. It is like learning a transit route. The names of the stops matter because they tell you whether you are still going the right direction.

      +

      Jamie: Let's pause on Recommended VoiceOver Utility settings. What should a learner take away from it?

      +

      Alex: Start with Recommended VoiceOver Utility settings. There is something to understand, something to try, and something that proves the try worked.

      +

      Alex: For a learner, the useful signals are these. "Punctuation": All (for code and Markdown). "Capitalization": Speak cap (useful for acronyms and code). "Reading Units": Set to sentenceboundary for prose, word for code. "Content Changes": On (for live regions like Copilot Chat). "Status Messages": On. "Quick Nav": OFF when inside editor (use Left+Right Arrow to toggle).

      +

      Alex: First, verbosity → Text. Then, verbosity → Announcements. After that, navigation. It is a checklist, but a meaningful one: every item creates evidence that the next step is safe.

      +

      Alex: That connects to another useful point. Keep the learner anchored in Quick Nav navigation (when enabled). Quick Nav should be OFF when editing text (conflicts with text navigation).

      -

      Jamie: Let's pause on View All Loaded Customizations. What should a learner take away from it?

      -

      Alex: Start with View All Loaded Customizations: To see every instruction file, agent, prompt, and skill currently loaded and any errors. The next useful detail is this: This shows: which files were found, which were loaded, which have errors, and from which scope (user vs workspace vs organization).

      -

      Alex: First, in Copilot Chat, select the gear icon (Configure Chat) → Diagnostics. Then, or right-click in the Chat view → Diagnostics. Think of it as a rail line: each stop confirms you are still on the right route before the next one.

      -

      Jamie: Let's pause on Agent not found when typing @agent-name. What should a learner take away from it?

      -

      Alex: Start with Agent not found when typing @agent-name. There is something to understand, something to try, and something that proves the try worked.

      -

      Alex: First, verify.github/agents/[name].agent.md exists in your open workspace folder. Then, check that the YAML frontmatter has no syntax errors (missing quotes, wrong indentation). After that, ctrl+Shift+P → "Reload Window". Finally, check that the name field in the frontmatter matches what you are typing. Treat it like a recipe: do not add the next ingredient until the previous one is actually in the bowl.

      -

      Jamie: Let's pause on Instructions not being applied. What should a learner take away from it?

      -

      Alex: Start with Instructions not being applied. There is something to understand, something to try, and something that proves the try worked.

      -

      Alex: First, for.github/copilot-instructions.md: file must be at workspace root in the.github/ folder. Then, for.instructions.md: check that applyTo glob matches the file you are editing, and that chat.includeApplyingInstructions is true in VS Code settings. After that, for AGENTS.md: check that chat.useAgentsMdFile is true. Finally, use Diagnostics view (above) to verify the file was found and loaded. It is a checklist, but a meaningful one: every item creates evidence that the next step is safe.

      +

      Jamie: Let's pause on 5. Complete Keyboard Shortcuts. What should a learner take away from it?

      +

      Alex: The reason 5. Complete Keyboard Shortcuts matters is that for screen reader navigation shortcuts when using GitHub in a browser (NVDA, JAWS, VoiceOver), see Appendix B - Screen Reader Cheat Sheet.

      +

      Alex: That matters because of the next idea. Start with 6. Accessibility Signals Types and Customization: Accessibility signals are events that trigger announcements or audio cues. The next useful detail is this: Beyond audio cues, VS Code has verbal announcements for various events. Think of it like entering a new building: first you find the lobby, then the room, then the door you actually need.

      +

      Jamie: Let's pause on Announcement Verbosity Settings. What should a learner take away from it?

      +

      Alex: Here is the plain-English version of Announcement Verbosity Settings. Control how much information VS Code announces. Put another way, verbose: Announces full context and details minimal: Announces only essential information off: No automatic announcements (use Accessible View manually).

      -

      Jamie: Let's pause on Instructions file in wrong place. What should a learner take away from it?

      -

      Alex: Start with Instructions file in wrong place. There is something to understand, something to try, and something that proves the try worked.

      -

      Alex: The practical takeaway is this. Add custom locations: chat.instructionsFilesLocations setting accepts an array of additional folder paths.

      -

      Jamie: Let's pause on Slash command not appearing. What should a learner take away from it?

      -

      Alex: Start with Slash command not appearing. There is something to understand, something to try, and something that proves the try worked.

      -

      Alex: First, verify.github/prompts/[name].prompt.md exists. Then, ctrl+Shift+P → "Reload Window". After that, file must use.prompt.md extension (not just.md). The rhythm is simple: orient, act, verify, then continue.

      -

      Jamie: Let's pause on 14. Further Reading. What should a learner take away from it?

      -

      Alex: Start with 14. Further Reading: For the broader ecosystem - the community plugin marketplace, MCP server integrations, and running agents in the cloud via GitHub Actions - see Appendix K: GitHub Copilot and Agentic Reference.

      +

      Alex: Hold that next to this. This is where Custom Announcement Timing becomes real: control when and how often announcements occur.

      +

      Jamie: Let's pause on Signal Priorities. What should a learner take away from it?

      +

      Alex: Keep the learner anchored in Signal Priorities. When multiple signals occur simultaneously, VS Code prioritizes them. This is the part to say slowly: This prevents overlapping announcements.

      +

      Alex: First, errors (highest priority) - always announced. Then, warnings - announced after errors. After that, completions - announced if no errors/warnings. Finally, focus changes - announced last. It is like walking a hallway with named doors: read the sign, enter the right room, then confirm where you landed.

      +

      Alex: Keep the teaching thread moving. Start with Learning Cards: Accessibility Signals. There is something to understand, something to try, and something that proves the try worked.

      +

      Alex: The practical takeaway is this. Start with auto for most signals -- they play only when screen reader mode is active, keeping things quiet otherwise. The lineHasError and taskFailed signals are the highest-value audio cues; enable these first. Use accessibility.signals.volume (0-100) to balance signal volume against your screen reader speech. Audio cues supplement visual indicators you might miss -- enable lineHasWarning and lineHasError for sounds on the current line. The save and format signals confirm file operations completed without needing to check the status bar visually. Pair audio cues with high-contrast gutter icons for a dual-channel (sight + sound) feedback loop.

      -

      Alex: Keep the teaching thread moving. Here is the plain-English version of Official accessibility.github.com Guides. Next: Appendix M: Accessibility Standards Back: Appendix K: Copilot Reference Teaching chapter: Chapter 19: Accessibility Agents. It is like learning a transit route. The names of the stops matter because they tell you whether you are still going the right direction.

      +

      Jamie: Let's pause on 7. Settings.json Configuration Examples. What should a learner take away from it?

      +

      Alex: Start with 7. Settings.json Configuration Examples: The configuration examples below are JSON blocks you paste into your settings.json file. The next useful detail is this: To apply a complete set at once, consider using VS Code Profiles -- named configuration bundles that let you switch your entire setup instantly.

      +

      Alex: Keep the teaching thread moving. Here is the plain-English version of For users working heavily with GitHub Copilot. The github.copilot.enable object controls which file types get Copilot suggestions.

      +

      Jamie: Let's pause on Paste this into your settings.json for a balanced screen reader profile. What should a learner take away from it?

      +

      Alex: This is where Paste this into your settings.json for a balanced screen reader profile becomes real: next: Appendix H: GitHub Desktop Back: Appendix F: Git Security Teaching chapter: Chapter 11: VS Code Interface.

      -

      Jamie: What is the final checkpoint?

      -

      Alex: You should be able to point to the evidence, explain the action, and describe what you would do next if this were a real open source project. If you can teach the move back, you have learned it.

      -

      Jamie: And if they get stuck?

      -

      Alex: Read the latest message, not the loudest worry. Check the issue, the branch, the pull request, the status check, or the bot comment. Then ask for help with those facts in hand. That is how professionals collaborate.

      +

      Jamie: What should people carry with them after this?

      +

      Alex: Carry the map. Know what page or tool you are in, know which action you are taking, and know what confirmation should follow. If the confirmation is missing, pause. That pause is not wasted time; it is professional judgment.

      +

      Jamie: That is a better way to say it than just follow the steps.

      +

      Alex: Right. Steps matter, but understanding wins. That is episode 30. Next in the series is episode 31, where we keep building the same contributor muscles.

      -

      Challenge 16: Build Your Agent (Capstone)

      -

      Designing an agent, writing responsibilities and guardrails, and preparing a contribution.

      +

      60. Episode 31: GitHub Codespaces

      +

      Cloud dev environments, accessibility setup, and screen reader usage.

      +

      Based on: Appendix J: GitHub Codespaces

      + + +

      Download Episode 31 (MP3)

      -Read Transcript - Challenge 16: Build Your Agent (Capstone) +Read Transcript - Episode 31: GitHub Codespaces

      Transcript

      -

      Alex: Welcome to Challenge Coach: Build Your Agent (Capstone). I am Alex. Before you do the task, we are going to make the skill feel concrete enough to practice.

      -

      Jamie: And I am Jamie. I will keep asking what the learner should do, what evidence counts, and how to recover if the page does something unexpected.

      +

      Alex: Welcome to episode 31 of Git Going with GitHub: GitHub Codespaces. I am Alex, and today we are teaching this topic as a conversation you can carry into the workshop, not as a page you have to memorize.

      +

      Jamie: And I am Jamie. I will keep pulling the lesson back to real learners, real repositories, and the evidence that proves the work happened.

      -

      Alex: The skill focus is Designing an agent, writing responsibilities and guardrails, and preparing a contribution. This is rehearsal for real contribution, so the evidence matters because it proves the move happened.

      -

      Jamie: So the challenge has to leave the learner with both confidence and a trail of evidence.

      -

      Alex: Exactly. Evidence is not busywork. It is how a learner, a facilitator, and a future maintainer can understand what changed and why.

      +

      Alex: The lesson focus is Cloud dev environments, accessibility setup, and screen reader usage. We will treat every step as a teachable decision, because that is what makes the skill portable.

      +

      Jamie: So we should explain the why clearly enough that the steps make sense when the learner meets them later.

      +

      Alex: That is it. If a listener only has audio right now, they should still get the complete concept and know what evidence would prove success.

      -

      Jamie: What makes this practice feel low-stakes but still real?

      -

      Alex: Start with Challenge 16: Build Your Agent (Capstone): What you will do: This is the capstone project. The next useful detail is this: the learner will fork the accessibility-agents repository, write your own agent file, open a cross-fork pull request, and review a peer or facilitator-seeded agent.

      -

      Jamie: How would you walk the room through that step by step?

      -

      Alex: Start with Phase 1: Fork. There is something to understand, something to try, and something that proves the try worked.

      -

      Alex: First, go to the accessibility-agents repository. Then, select Fork to create your own copy. After that, clone your fork to your local machine. Treat it like a recipe: do not add the next ingredient until the previous one is actually in the bowl.

      -

      Jamie: What does the learner do first, second, and then after that?

      -

      Alex: Start with Phase 2: Branch. There is something to understand, something to try, and something that proves the try worked.

      -

      Alex: First, create a branch named agent/YOUR-USERNAME for your work. It is a checklist, but a meaningful one: every item creates evidence that the next step is safe.

      -

      Alex: A solid Git habit is to know which branch you are on, what changed, and what confirmation you expect before you run the next command.

      +

      Jamie: Okay, set the room for us. What are we walking into?

      +

      Alex: Start with Cloud Development Environments - Accessibility Guide: GitHub Codespaces gives you a full VS Code development environment in your browser or connected to your local VS Code, running on a cloud machine. The next useful detail is this: For screen reader users, this means a consistent, pre-configured environment with no local setup required.

      +

      Alex: The next layer is this. Here is the plain-English version of 1. What Is GitHub Codespaces? A Codespace is a cloud-hosted development environment. Put another way, when you open one, GitHub provisions a virtual machine, clones your repository into it, and connects it to a VS Code interface - either in your browser or via your local VS Code Desktop. It is like learning a transit route. The names of the stops matter because they tell you whether you are still going the right direction.

      +

      Jamie: What is the one idea that makes the next few steps less mysterious?

      +

      Alex: This is where Why this matters for accessibility becomes real: free tier: GitHub provides a monthly free allowance of Codespace hours for personal accounts. That matters in practice: Workshop usage typically falls well within the free tier.

      +

      Alex: That shows up in the workshop in a few specific ways. No local installation of tools, compilers, or language runtimes required. Your screen reader and OS settings stay on your machine; only the editor runs in the cloud. VS Code's full accessibility features (audio cues, screen reader optimized mode, diff viewer) are available. The environment is identical for every workshop participant - facilitators can reproduce issues reliably.

      -

      Jamie: Turn that into a path someone can follow.

      -

      Alex: Start with Phase 3: Write your agent. There is something to understand, something to try, and something that proves the try worked.

      -

      Alex: For a learner, the useful signals are these. Valid YAML frontmatter with name, description, and at least one tools entry. Responsibilities section -- 3-5 bullet points describing what your agent does. Guardrails section -- 2-3 bullet points describing what your agent should NOT do.

      -

      Alex: First, create a new file: agents/YOUR-AGENT-NAME.agent.md. Then, your agent file must. It is like walking a hallway with named doors: read the sign, enter the right room, then confirm where you landed.

      +

      Alex: Now bring the learner back to the room. Start with Learning Cards: Cloud Editors Overview. There is something to understand, something to try, and something that proves the try worked.

      +

      Alex: For a learner, the useful signals are these. Codespaces gives you a full VS Code interface with terminal access -- your screen reader and OS settings stay on your local machine. The browser-based editor activates screen reader optimized mode automatically if your OS signals a screen reader is running. Connect a Codespace to your local VS Code Desktop (via the Codespaces extension) for the most familiar screen reader experience. Settings Sync carries your font size, theme, and zoom preferences from local VS Code into Codespaces automatically. The browser-based editor supports Ctrl+= / Ctrl+- zoom just like desktop VS Code. Use a high-contrast VS Code theme -- it applies identically in the cloud editor.

      Jamie: What is the ordered workflow?

      -

      Alex: Start with Phase 4: Open a cross-fork PR. There is something to understand, something to try, and something that proves the try worked.

      -

      Alex: First, commit your agent file and push to your fork. Then, go to the original accessibility-agents repository. After that, open a pull request from your fork's branch to the original repo's main branch. Finally, write a PR description that explains your agent's purpose. The rhythm is simple: orient, act, verify, then continue.

      -

      Alex: A solid pull request habit is to separate three questions: what changed, why it changed, and what still needs review. That keeps the conversation useful instead of noisy.

      +

      Alex: Start with From a Repository Page. There is something to understand, something to try, and something that proves the try worked.

      +

      Alex: First, navigate to the repository on GitHub. Then, press the Code button (keyboard shortcut: there is no direct shortcut - Tab to the button). After that, in the panel that opens, choose the Codespaces tab. Finally, activate Create codespace on main (or your branch name). The rhythm is simple: orient, act, verify, then continue.

      Jamie: Give me the sequence, because order matters here.

      -

      Alex: Start with Phase 5: Peer review: Autograded: The autograder verifies that your agent file exists, has valid YAML frontmatter, and contains both responsibilities and guardrails sections. The next useful detail is this: I reviewed a peer or peer-simulation PR because. Think of it like entering a new building: first you find the lobby, then the room, then the door you actually need.

      -

      Alex: First, review a classmate's capstone PR if facilitator access is available. If not, review the peer-simulation PR and explain what you would look for in an agent PR. Then, check: Does their agent have responsibilities? Guardrails? Valid YAML? Think of it as a rail line: each stop confirms you are still on the right route before the next one.

      -
      -

      Jamie: Okay, set the room for us. What are we walking into?

      -

      Alex: Here is the plain-English version of Peer simulation check. Review a peer agent if access is available. Put another way, if not, use the peer-simulation PR to practice review language, then describe what you would check in an agent PR.

      +

      Alex: First, the Codespace opens in a new browser tab after provisioning (typically 30-60 seconds). Think of it as a rail line: each stop confirms you are still on the right route before the next one.

      Alex: The useful habit is simple: orient first, act second, verify third. That pause before acting is part of the work.

      -

      Alex: This is where the talk moves from concept to action. This is where Example agent file becomes real: file: community-agents/workshop-buddy.agent.md.

      -

      Jamie: What is the one idea that makes the next few steps less mysterious?

      -

      Alex: Keep the learner anchored in Alternate valid agents. Other examples students have built.

      -

      Alex: These are the details that keep the idea from floating away. An agent that reviews Markdown formatting. An agent that checks issue titles for clarity. An agent that recommends which Git command to use. An agent that explains error messages.

      -
      -

      Alex: Before the learner moves on. The reason What matters matters is that the learning objective is understanding that AI agents are defined by their responsibilities AND their guardrails. That gives the learner a simple foothold: if your agent file has valid YAML frontmatter, a clear purpose, and explicit boundaries, you completed this challenge. The interface gets friendlier when it stops being a wall of controls and starts being a set of named places.

      -

      Jamie: Let's pause on 1. The Capstone Challenge. What should a learner take away from it?

      -

      Alex: Start with 1. The Capstone Challenge: The capstone is Challenge 16 -- the final challenge of the workshop. The next useful detail is this: Your pull request goes to a real repository.

      -

      Alex: First, choose a mission for a new accessibility agent (or improve an existing one). Then, write an agent file with valid YAML frontmatter. After that, define clear responsibilities and guardrails. Finally, test the agent locally with GitHub Copilot. Think of it as a rail line: each stop confirms you are still on the right route before the next one.

      -

      Jamie: Before we leave 1. The Capstone Challenge, what is the practical point?

      -

      Alex: First, open a pull request from your fork to the upstream repository. Then, respond to peer review feedback. Treat it like a recipe: do not add the next ingredient until the previous one is actually in the bowl.

      -

      Alex: Hold that next to this. Start with What you need before starting. There is something to understand, something to try, and something that proves the try worked.

      -

      Alex: The practical anchors are these. [ ] You have forked and cloned the accessibility-agents repository (Chapter 18). [ ] You have a feature branch created: agents/your-username-agent-name. [ ] You understand how to push to your fork and open a PR (Chapter 18). [ ] You have GitHub Copilot or Copilot Free active (Chapter 16). [ ] You have explored the existing agents in Chapter 19.

      +

      Jamie: How would you walk the room through that step by step?

      +

      Alex: Start with From the Codespaces Dashboard. There is something to understand, something to try, and something that proves the try worked.

      +

      Alex: First, go to github.com/codespaces. Then, activate New codespace. After that, use the search field to find your repository. Finally, choose a branch, machine type, and region. Think of it as a rail line: each stop confirms you are still on the right route before the next one.

      +

      Jamie: What does the learner do first, second, and then after that?

      +

      Alex: First, activate Create codespace. Treat it like a recipe: do not add the next ingredient until the previous one is actually in the bowl.

      Jamie: If I am listening before the workshop starts, what should settle in my mind first?

      -

      Alex: This is where Time estimate becomes real: most students complete the capstone in 60 to 90 minutes. That matters in practice: The phases are designed so you can get a working agent in 30 minutes and spend the remaining time improving it.

      -

      Alex: That connects to another useful point. Keep the learner anchored in 2. Phase 1: Choose Your Agent's Mission. See also: Chapter 19: Accessibility Agents introduces the agent ecosystem and shows existing agents for inspiration. A good GitHub workflow is like a well-run meeting: everyone knows the topic, the next action, and who has the floor.

      -

      Jamie: Where do you want a learner to place their attention here?

      -

      Alex: The reason What makes a good agent mission matters is that a good agent solves a specific, recurring problem.

      -

      Alex: The parts worth keeping in working memory are these. What task do you repeat? Think about workflow steps from Day 1 and Day 2 that felt repetitive. What would a specialist know? An agent works best when it has deep knowledge of a focused area. What gap exists? Look at the existing agents in Chapter 19. Is there a workflow that no agent covers?

      +

      Alex: Here is the plain-English version of Machine Types. For workshop exercises, the default 2-core machine is sufficient.

      +

      Alex: This is where the talk moves from concept to action. This is where Browser (VS Code for the Web) becomes real: the Codespace opens directly in your browser as a fully functional VS Code interface.

      +

      Alex: The room should hear these as checkpoints. Works in Chrome, Edge, Firefox, and Safari. Screen reader support varies slightly by browser - Chrome and Edge have the most consistent behavior with NVDA and JAWS. No installation needed. Some VS Code extensions are not available in the browser version.

      +

      Jamie: Turn that into a path someone can follow.

      +

      Alex: Keep the learner anchored in Local VS Code Desktop. If you prefer your local VS Code setup with your extensions and settings. This is the part to say slowly: When connected via local VS Code, your screen reader interacts with your local VS Code installation - all your familiar settings apply.

      +

      Alex: First, install the GitHub Codespaces extension in VS Code. Then, sign in to GitHub in VS Code. After that, open the Command Palette (Ctrl+Shift+P / Cmd+Shift+P). Finally, run Codespaces: Connect to Codespace. It is like walking a hallway with named doors: read the sign, enter the right room, then confirm where you landed.

      +

      Jamie: Let's pause on Local VS Code Desktop. What should a learner take away from it?

      +

      Alex: First, select an existing Codespace or create a new one. The rhythm is simple: orient, act, verify, then continue.

      -

      Alex: Here is the practical turn. Start with Write your mission statement: Before writing any code, write a one-sentence mission statement. The next useful detail is this: "My agent helps [who] by [doing what] when [in what situation].".

      +

      Jamie: Let's pause on Screen Reader Optimized Mode. What should a learner take away from it?

      +

      Alex: The reason Screen Reader Optimized Mode matters is that when VS Code detects a screen reader, it automatically activates Screen Reader Optimized mode. That gives the learner a simple foothold: you can verify or toggle it manually. The interface gets friendlier when it stops being a wall of controls and starts being a set of named places.

      +

      Alex: That becomes easier when you listen for these cues. The editor reads content line by line instead of character by character. Diff views are rendered as accessible text comparisons. Inline suggestions from Copilot are announced on a keypress rather than automatically.

      +

      Alex: First, open the Command Palette (Ctrl+Shift+P). Then, search for Toggle Screen Reader Accessibility Mode. After that, press Enter to activate. The rhythm is simple: orient, act, verify, then continue.

      +

      Alex: A solid navigation habit is to prove where you are before activating controls. Headings, landmarks, and the address bar are not trivia; they are your map.

      Jamie: What would you say to someone who is already bracing for this to be too much?

      -

      Alex: Here is the plain-English version of 3. Phase 2: Write the Agent File. An agent file is a Markdown file with YAML frontmatter that defines the agent's identity, and a body that contains the agent's instructions. Put another way, agent files live in the.github/agents/ directory (for GitHub Copilot agents) or in team-specific directories in the accessibility-agents repository.

      -

      Alex: Keep the thread going. This is where File location and naming becomes real: example.github/agents/alt-text-validator.md. The workshop is closer to rehearsal than lecture. You hear the move, try the move, and then check what changed.

      +

      Alex: Start with Audio Cues: VS Code in Codespaces supports the same audio cues as the desktop version. The next useful detail is this: Enable audio cues via Settings → search for "audio cues" or run Help: List Audio Cues from the Command Palette.

      +

      Alex: Hold that next to this. Here is the plain-English version of Terminal Accessibility. The integrated terminal in a Codespace is a standard terminal.

      +

      Alex: The practical anchors are these. Screen readers read terminal output in NVDA and JAWS using their document/browse mode after output arrives. In NVDA: Switch to Browse Mode to read static terminal output, then back to Focus Mode to type. VS Code also has Accessible View (Alt+F2 when cursor is in the terminal) which renders terminal output in a navigable buffer.

      -

      Jamie: Let's pause on The agent file structure. What should a learner take away from it?

      -

      Alex: Start with The agent file structure. There is something to understand, something to try, and something that proves the try worked.

      -

      Alex: First, yAML frontmatter -- metadata between --- markers at the top of the file. Then, instructions body -- Markdown content that tells the agent how to behave. It is like walking a hallway with named doors: read the sign, enter the right room, then confirm where you landed.

      -

      Alex: Another way to ground it. The reason YAML frontmatter fields matters is that vague descriptions result in missed automatic routing. That gives the learner a simple foothold: weak: Helps with accessibility - Strong: Checks markdown files for accessibility issues, fixes descriptive links and heading hierarchy, and flags alt text for human review The more specific the description, the more reliably Copilot invokes the right agent for.

      +

      Jamie: Where do you want a learner to place their attention here?

      +

      Alex: Start with Learning Cards: Codespace Accessibility. There is something to understand, something to try, and something that proves the try worked.

      +

      Alex: The parts worth keeping in working memory are these. Screen Reader Optimized mode activates automatically -- verify with Command Palette Ctrl+Shift+P then "Toggle Screen Reader Accessibility Mode". Audio cues (error, warning, task completed, Copilot suggestion) work identically in Codespaces and desktop VS Code. In NVDA, switch to Browse Mode to read terminal output, then Focus Mode to type -- same pattern as local VS Code. All VS Code zoom and theme settings apply in the browser-based Codespace -- Ctrl+= increases editor font size. Audio cues for errors and Copilot suggestions supplement visual indicators you might miss at lower zoom levels. Chrome and Edge provide the most consistent rendering of the Codespace UI at high zoom and magnification levels.

      +

      Alex: That connects to another useful point. Keep the learner anchored in NVDA. No special NVDA profile is required for Codespaces in the browser. This is the part to say slowly: The same settings recommended in Appendix B apply. A good GitHub workflow is like a well-run meeting: everyone knows the topic, the next action, and who has the floor.

      +

      Alex: On the ground, that means a few things. Ensure Browse Mode is on for reading, Focus Mode for typing. Set maximum line length to 10000 in NVDA Settings → Browse Mode. In Chrome or Edge, NVDA's Browse Mode detection is generally reliable.

      Jamie: Give me the version that sounds like an instructor, not a manual.

      -

      Alex: Start with Writing the instructions body: The instructions body tells the agent how to behave. The next useful detail is this: Write it as if you are briefing a new team member on their first day.

      -

      Alex: A few details make that real. Start with identity. "You are a [role] focused on [area].". List responsibilities. What specific tasks does this agent handle? Set guardrails. What should the agent never do? What are its limits? Provide examples. Show what good output looks like.

      -
      -

      Alex: This is the part worth saying out loud. Start with Learning Cards: Writing the Agent File. There is something to understand, something to try, and something that proves the try worked.

      -

      Alex: That shows up in the workshop in a few specific ways. Create your agent file with Ctrl+N, then Ctrl+S and save to.github/agents/your-agent-name.md -- the Explorer navigates to the folder automatically. Use Ctrl+Shift+O to navigate between YAML frontmatter fields and Markdown headings (Responsibilities, Guardrails) in your agent file. The YAML frontmatter is between --- markers at the top -- your screen reader announces these as horizontal rules. Agent files are standard Markdown -- open Markdown Preview (Ctrl+Shift+V) side by side to verify formatting as you write. The YAML frontmatter at the top uses name: and description: fields -- keep these on separate lines for readability at high zoom. Use a consistent heading hierarchy ( for title, for sections) so the Outline view (Ctrl+Shift+O) shows a clean structure.

      -

      Jamie: Let's pause on 4. Phase 3: Define Responsibilities and Guardrails. What should a learner take away from it?

      -

      Alex: This is where 4. Phase 3: Define Responsibilities and Guardrails becomes real: responsibilities and guardrails are the most important parts of your agent's instructions. That matters in practice: The autograder checks that both sections exist.

      -

      Alex: The next layer is this. Keep the learner anchored in Writing responsibilities. Responsibilities define what the agent does. This is the part to say slowly: Each responsibility should describe one discrete action the agent can take.

      -

      Alex: On the ground, that means a few things. Scan HTML files for tags missing the alt attribute. Check that all elements have visible text or an aria-label. Verify heading levels do not skip (e.g., h1 to h3 without h2). Help with accessibility.

      +

      Alex: Start with JAWS. There is something to understand, something to try, and something that proves the try worked.

      +

      Alex: Here is what that changes in practice. Use Virtual Cursor for reading page content. Switch to PC Cursor (Insert+Z or Num Pad Plus) when inside the editor and writing code. JAWS works best with the Codespace in Chrome or Edge.

      -

      Jamie: Let's pause on Writing guardrails. What should a learner take away from it?

      -

      Alex: The reason Writing guardrails matters is that guardrails define what the agent must not do. That gives the learner a simple foothold: they prevent the agent from overstepping, giving harmful advice, or acting without permission.

      -

      Alex: Here is what that changes in practice. Never auto-fix code without asking the user first. Do not provide medical, legal, or financial advice when discussing accessibility compliance. Limit reviews to the files the user specifies -- do not scan the entire repository. If a finding is uncertain, say so explicitly rather than presenting it as definitive.

      -

      Alex: Now bring the learner back to the room. Start with Learning Cards: Responsibilities and Guardrails. There is something to understand, something to try, and something that proves the try worked.

      -

      Alex: The room should hear these as checkpoints. Use Responsibilities and Guardrails as exact heading names -- the autograder searches for these strings. Each responsibility should start with a verb (Scan, Check, Verify, Flag) -- this makes them concrete and testable. Guardrails should start with "Never" or "Do not" to set clear boundaries your screen reader identifies as restrictions when reviewing the file. Format responsibilities as a bulleted list (starting with -) for easy scanning at high zoom -- one responsibility per bullet. Keep each guardrail to a single line so it remains visible without horizontal scrolling at your zoom level. Use bold text for emphasis on critical guardrails (e.g., Never modify files without approval ) to improve visual scanning.

      -

      Jamie: Let's pause on 5. Phase 4: Test Your Agent Locally. What should a learner take away from it?

      -

      Alex: Here is the plain-English version of 5. Phase 4: Test Your Agent Locally. See also: Chapter 18: Fork and Contribute covers the fork-and-PR workflow you will use to submit your agent. Put another way, before opening a pull request, test your agent to verify it works.

      +

      Alex: Here is the practical turn. Start with VoiceOver (macOS). There is something to understand, something to try, and something that proves the try worked.

      +

      Alex: These are the details that keep the idea from floating away. Use Quick Nav (Left+Right arrows) for moving through the VS Code interface. The Rotor (VO+U) surfaces VS Code's landmark regions. If text in the editor is not reading fluently, ensure Screen Reader Optimized mode is active (see above).

      +

      Jamie: Let's pause on 6. Keyboard Shortcuts in Codespaces. What should a learner take away from it?

      +

      Alex: Here is the plain-English version of 6. Keyboard Shortcuts in Codespaces. Codespaces uses standard VS Code keyboard shortcuts. Put another way, the most important ones for workshop exercises.

      +

      Jamie: Let's pause on Stopping a Codespace. What should a learner take away from it?

      +

      Alex: This is where Stopping a Codespace becomes real: codespaces automatically stop after a period of inactivity (default: 30 minutes). That matters in practice: Stopped Codespaces retain your files and changes. The workshop is closer to rehearsal than lecture. You hear the move, try the move, and then check what changed.

      +

      Alex: First, go to github.com/codespaces. Then, find your Codespace in the list. After that, activate the … menu next to it. Finally, choose Stop codespace. It is a checklist, but a meaningful one: every item creates evidence that the next step is safe.

      -

      Jamie: Let's pause on Testing with GitHub Copilot Chat. What should a learner take away from it?

      -

      Alex: Start with Testing with GitHub Copilot Chat. There is something to understand, something to try, and something that proves the try worked.

      -

      Alex: That becomes easier when you listen for these cues. Understand its mission? Follow its responsibilities? Respect its guardrails?

      -

      Alex: First, open VS Code with the accessibility-agents repository. Then, ensure your agent file is saved in.github/agents/. After that, open GitHub Copilot Chat (Ctrl+Shift+I or Cmd+Shift+I). Finally, invoke your agent by name: @your-agent-name check this file for accessibility issues. It is a checklist, but a meaningful one: every item creates evidence that the next step is safe.

      -

      Jamie: Before we leave Testing with GitHub Copilot Chat, what is the practical point?

      -

      Alex: First, observe the response. Does the agent. It is like walking a hallway with named doors: read the sign, enter the right room, then confirm where you landed.

      -

      Jamie: Let's pause on Testing checklist. What should a learner take away from it?

      -

      Alex: Start with Testing checklist. There is something to understand, something to try, and something that proves the try worked.

      -

      Alex: The practical takeaway is this. [ ] The agent responds when invoked by name. [ ] The agent stays within its defined responsibilities. [ ] The agent does not violate any guardrails. [ ] The agent's output is useful and specific. [ ] The agent handles edge cases gracefully (empty files, no issues found).

      -

      Jamie: Let's pause on Iterating on your agent. What should a learner take away from it?

      -

      Alex: The reason Iterating on your agent matters is that if the agent does not behave as expected. That gives the learner a simple foothold: most students iterate 2-3 times before they are satisfied. The interface gets friendlier when it stops being a wall of controls and starts being a set of named places.

      -

      Alex: First, read its instructions carefully. Is anything ambiguous? Then, add more specific instructions or examples. After that, test again with the same prompt. Finally, repeat until the behavior matches your intent. The rhythm is simple: orient, act, verify, then continue.

      +

      Jamie: Let's pause on Deleting a Codespace. What should a learner take away from it?

      +

      Alex: Keep the learner anchored in Deleting a Codespace. Deleting a Codespace removes any uncommitted or unpushed changes permanently. This is the part to say slowly: Always commit and push your work before deleting.

      +

      Alex: First, go to github.com/codespaces. Then, activate the … menu next to the Codespace. After that, choose Delete. It is like walking a hallway with named doors: read the sign, enter the right room, then confirm where you landed.

      +

      Jamie: Let's pause on Resuming a Codespace. What should a learner take away from it?

      +

      Alex: Start with Resuming a Codespace. There is something to understand, something to try, and something that proves the try worked.

      +

      Alex: First, go to github.com/codespaces. Then, find your stopped Codespace. After that, activate Open in … to resume it in the browser or in VS Code Desktop. The rhythm is simple: orient, act, verify, then continue.

      +

      Jamie: Let's pause on 8. Dotfiles and Persistent Configuration. What should a learner take away from it?

      +

      Alex: Start with 8. Dotfiles and Persistent Configuration: If you have a repository named dotfiles on your GitHub account, Codespaces will automatically apply it when provisioning new environments. The next useful detail is this: To set up dotfiles: create a repository named dotfiles and add an install.sh script.

      +

      Alex: A few details make that real. Setting your preferred shell (bash, zsh, fish). Adding shell aliases and functions. Pre-installing command-line tools.

      -

      Jamie: Let's pause on Learning Cards: Testing Your Agent. What should a learner take away from it?

      -

      Alex: Start with Learning Cards: Testing Your Agent. There is something to understand, something to try, and something that proves the try worked.

      -

      Alex: The practical takeaway is this. Open Copilot Chat (Ctrl+Shift+I) and type @your-agent-name followed by a test prompt -- your screen reader announces the response as it streams. Press Alt+F2 after the response finishes to read the full output in Accessible View with arrow keys. If the agent does not respond as expected, edit the.agent.md file and ask again -- Copilot picks up changes immediately. Agent responses appear in the Copilot Chat panel -- widen the panel by dragging its left edge for better readability. Test with a simple prompt first (e.g., "review this file") and read the full response before trying complex requests. Use Accessible View (Alt+F2) to read responses at your preferred editor font size instead of the Chat panel's default.

      -

      Jamie: Let's pause on Tool Cards: Open Your Capstone PR. What should a learner take away from it?

      -

      Alex: Here is the plain-English version of Tool Cards: Open Your Capstone PR. VS Code Desktop (primary for Day 2).

      -

      Alex: First, push your branch: Ctrl+Shift+P Git: Push. Then, ctrl+Shift+P GitHub Pull Requests: Create Pull Request. After that, set base repo to Community-Access/accessibility-agents, fill in the title and description. Finally, navigate to your fork on GitHub. Treat it like a recipe: do not add the next ingredient until the previous one is actually in the bowl.

      -

      Jamie: Before we leave Tool Cards: Open Your Capstone PR, what is the practical point?

      -

      Alex: First, click Contribute Open pull request. Then, verify the base is Community-Access/accessibility-agents:main and the compare is your branch. It is a checklist, but a meaningful one: every item creates evidence that the next step is safe.

      -

      Alex: Treat examples as spoken recipes, not decorations. You may hear something like git push -u origin your-branch; gh pr create --repo Community-Access/accessibility-agents. Read the command, understand what it changes, then run it only when the repository state matches the lesson.

      -

      Jamie: Let's pause on Pre-PR checklist. What should a learner take away from it?

      -

      Alex: Start with Pre-PR checklist. There is something to understand, something to try, and something that proves the try worked.

      -

      Alex: The practical takeaway is this. [ ] Your agent file has valid YAML frontmatter (name and description fields). [ ] Your agent file has a Responsibilities section. [ ] Your agent file has a Guardrails section. [ ] The file is in the correct directory. [ ] You have committed and pushed to your fork.

      +

      Alex: This is the part worth saying out loud. Here is the plain-English version of 9. Codespaces vs GitHub.dev. For workshop exercises that involve running scripts or tests, use Codespaces. Put another way, for quickly browsing or editing a file, GitHub.dev is faster to open. It is like learning a transit route. The names of the stops matter because they tell you whether you are still going the right direction.

      +

      Jamie: Let's pause on Learning Cards: Choosing Your Cloud Editor. What should a learner take away from it?

      +

      Alex: Start with Learning Cards: Choosing Your Cloud Editor. There is something to understand, something to try, and something that proves the try worked.

      +

      Alex: The practical takeaway is this. GitHub.dev has no terminal -- choose Codespaces when you need to run commands, and github.dev for quick file edits. Both editors support screen reader mode, but Codespaces gives you the full terminal Accessible View (Alt+F2) that github.dev lacks. press the period key on any repo page for github.dev; use the Codespaces dashboard at github.com/codespaces for a full environment. GitHub.dev loads instantly with your synced VS Code theme -- good for quick high-contrast reading of source files. Codespaces takes 30-60 seconds to provision but gives you terminal, builds, and the same zoom/theme settings. Both editors scale with browser zoom (Ctrl+=) in addition to VS Code's own font-size settings.

      +

      Alex: That matters because of the next idea. Keep the learner anchored in The Codespace takes a long time to open. Provisioning a new Codespace can take up to 90 seconds. This is the part to say slowly: If it hangs beyond that, refresh the browser tab and try again.

      -

      Jamie: Let's pause on Open the PR. What should a learner take away from it?

      -

      Alex: Keep the learner anchored in Open the PR. Follow the pull request steps from Chapter 18, Step 7. A good GitHub workflow is like a well-run meeting: everyone knows the topic, the next action, and who has the floor.

      -

      Alex: The practical takeaway is this. Your mission statement from Phase 1. What the agent does (summary of responsibilities). Any design decisions you made. How you tested it.

      -

      Alex: First, push your branch: git push -u origin agents/your-username-agent-name. Then, go to the upstream repository on GitHub.com. After that, click the banner or go to Pull Requests and click New pull request, then compare across forks. Finally, select your fork and branch. It is like walking a hallway with named doors: read the sign, enter the right room, then confirm where you landed.

      -

      Jamie: Before we leave Open the PR, what is the practical point?

      -

      Alex: First, write a PR title: "Add [agent-name] accessibility agent". Then, in the PR body,. After that, create the pull request. The rhythm is simple: orient, act, verify, then continue.

      -

      Jamie: Let's pause on The autograder. What should a learner take away from it?

      -

      Alex: The reason The autograder matters is that the repository has an autograding workflow that runs on every pull request. That gives the learner a simple foothold: the autograder posts results as a comment on your PR.

      -

      Alex: That matters because of the next idea. Start with Learning Cards: Opening Your Pull Request. There is something to understand, something to try, and something that proves the try worked.

      -

      Alex: The practical takeaway is this. The autograder comment appears in the PR timeline -- navigate to Comments on GitHub.com with h (heading navigation) to find the results. Each autograder check is listed with a pass/fail status and point value -- listen for "10/10" or "0/15" to identify which checks need attention. If a check fails, read the failure message, fix the issue locally, commit, push, and the autograder re-runs automatically. The autograder results appear as a comment with a table showing checks, points, and pass/fail status -- zoom with Ctrl+= to read the details. Green checkmarks indicate passing checks; red X marks indicate failures -- pair with High Contrast theme for clearest visibility. Your PR description should include your mission statement, responsibilities summary, and testing notes.

      +

      Jamie: Let's pause on Screen reader stops reading after I switch to the terminal. What should a learner take away from it?

      +

      Alex: The reason Screen reader stops reading after I switch to the terminal matters is that switch to Browse Mode (NVDA: Insert+Space; JAWS: Insert+Z) to read the terminal output, then return to Focus Mode to type your next command.

      +

      Alex: Keep the thread going. Start with Audio cues are not working in the browser: Some browsers mute audio by default for new tabs. The next useful detail is this: Check your browser's site permissions to ensure audio is allowed for github.dev or the Codespace URL. Think of it like entering a new building: first you find the lobby, then the room, then the door you actually need.

      +

      Jamie: Let's pause on Extensions I rely on locally are not available. What should a learner take away from it?

      +

      Alex: Here is the plain-English version of Extensions I rely on locally are not available. Some extensions are not compatible with the browser-based VS Code. Put another way, connect to the Codespace via VS Code Desktop instead (see Section 3) to access your full extension library.

      -

      Jamie: Let's pause on 7. Phase 6: Respond to Review. What should a learner take away from it?

      -

      Alex: Here is the plain-English version of 7. Phase 6: Respond to Review. After the autograder passes, a peer reviewer (your buddy or another student) and a facilitator will review your agent.

      -

      Alex: Keep the teaching thread moving. Start with What reviewers look for. There is something to understand, something to try, and something that proves the try worked.

      -

      Alex: The practical takeaway is this. Clarity: Are the instructions easy to understand? Specificity: Are responsibilities concrete and actionable? Safety: Are guardrails sufficient to prevent harmful behavior? Usefulness: Would this agent actually help someone? Scope: Does the agent try to do too much or too little?

      -

      Jamie: Let's pause on Responding to feedback. What should a learner take away from it?

      -

      Alex: Keep the learner anchored in Responding to feedback. This is the same process from Chapter 18, Step 8.

      -

      Alex: First, read each review comment. Then, make changes locally. After that, commit and push. The PR updates automatically. Finally, reply to each comment explaining your changes. It is like walking a hallway with named doors: read the sign, enter the right room, then confirm where you landed.

      +

      Alex: Another way to ground it. This is where I accidentally deleted my Codespace before pushing becomes real: if the branch exists on GitHub, you can create a new Codespace from it. That matters in practice: Uncommitted changes in a deleted Codespace cannot be recovered.

      +

      Jamie: Let's pause on My changes are not showing in GitHub after committing. What should a learner take away from it?

      +

      Alex: Keep the learner anchored in My changes are not showing in GitHub after committing. You may have committed but not pushed. This is the part to say slowly: In the Source Control panel, look for the Sync Changes or Push button.

      +

      Alex: A solid Git habit is to know which branch you are on, what changed, and what confirmation you expect before you run the next command.

      -

      Alex: Keep the teaching thread moving. The reason When your PR is merged matters is that your agent is now part of the accessibility-agents ecosystem. That gives the learner a simple foothold: it is available to anyone who uses the repository.

      -

      Alex: The practical takeaway is this. You can navigate the fork workflow end to end. You can write clear, structured technical documentation. You understand accessibility concepts well enough to teach an AI agent about them. You can respond constructively to code review.

      -

      Jamie: Let's pause on 8. Capstone Rubric. What should a learner take away from it?

      -

      Alex: Start with 8. Capstone Rubric: The capstone is worth 60 autograded points plus peer review.

      -

      Alex: Keep the teaching thread moving. Here is the plain-English version of What "meets expectations" looks like. A capstone that meets expectations has. It is like learning a transit route. The names of the stops matter because they tell you whether you are still going the right direction.

      -

      Alex: The practical takeaway is this. A focused mission (not "help with accessibility" -- something specific). At least 3 concrete responsibilities. At least 3 meaningful guardrails. A PR description that explains the agent's purpose. All autograder checks passing.

      +

      Jamie: What should people carry with them after this?

      +

      Alex: Carry the map. Know what page or tool you are in, know which action you are taking, and know what confirmation should follow. If the confirmation is missing, pause. That pause is not wasted time; it is professional judgment.

      +

      Jamie: That is a better way to say it than just follow the steps.

      +

      Alex: Right. Steps matter, but understanding wins. That is episode 31. Next in the series is episode 32, where we keep building the same contributor muscles.

      +
      +
      -

      Jamie: Let's pause on What "exceeds expectations" looks like. What should a learner take away from it?

      -

      Alex: This is where What "exceeds expectations" looks like becomes real: a capstone that exceeds expectations also has.

      -

      Alex: The practical takeaway is this. Examples of expected input and output in the agent instructions. A section describing the agent's limitations. Evidence of testing (screenshots or transcripts in the PR description). Thoughtful responses to review feedback.

      -

      Alex: Keep the teaching thread moving. Keep the learner anchored in 9. Example Agents for Inspiration. These examples show the range of valid agent designs. This is the part to say slowly: Your agent does not need to be this long, but it should be this clear.

      -

      Jamie: Let's pause on Example 1: Heading Hierarchy Checker. What should a learner take away from it?

      -

      Alex: The reason Example 1: Heading Hierarchy Checker matters is that mission: Validates that HTML and Markdown documents follow a correct heading hierarchy (no skipped levels).

      -

      Alex: The practical takeaway is this. Scan files for heading elements (h1 through h6 in HTML, through in Markdown). Report any instance where a heading level is skipped (e.g., h2 followed by h4). Suggest the correct heading level for each violation. Check that there is exactly one h1 per page. Do not modify files -- only report findings. Do not change heading text, only heading levels.

      -

      Alex: A solid navigation habit is to prove where you are before activating controls. Headings, landmarks, and the address bar are not trivia; they are your map.

      +

      61. Episode 32: GitHub Mobile

      +

      VoiceOver and TalkBack guide for iOS and Android GitHub apps.

      +

      Based on: Appendix V: GitHub Mobile

      + + +

      Download Episode 32 (MP3)

      +
      +Read Transcript - Episode 32: GitHub Mobile + +

      Transcript

      +

      Alex: Welcome to Git Going with GitHub, episode 32: GitHub Mobile. I am Alex. Today we are going to make GitHub Mobile something you can explain, practice, and recover from when the interface surprises you.

      +

      Jamie: And I am Jamie. I will be the voice of the learner who is willing to ask, what is this for, where am I, and how do I know I did it right?

      -

      Alex: Keep the teaching thread moving. Start with Example 2: PR Description Quality Gate: Mission: Reviews pull request descriptions to ensure they contain enough context for reviewers. Think of it like entering a new building: first you find the lobby, then the room, then the door you actually need.

      -

      Alex: The practical takeaway is this. Check that the PR description is at least 50 characters. Verify the description references an issue with Closes XX or Fixes XX. Check for a summary of changes made. Verify the description explains why the change was made, not just what was changed. Never approve or block a PR based solely on description quality. Do not rewrite the description for the author -- suggest improvements.

      -

      Jamie: Let's pause on Example 3: Keyboard Navigation Auditor. What should a learner take away from it?

      -

      Alex: Here is the plain-English version of Example 3: Keyboard Navigation Auditor. Mission: Checks web components for keyboard accessibility compliance.

      -

      Alex: The practical takeaway is this. Verify all interactive elements are reachable via Tab key. Check that custom components have appropriate tabindex values. Validate that focus order follows visual layout. Detect keyboard traps (elements that receive focus but cannot release it via keyboard). Do not modify component code without user approval. Flag potential issues with confidence levels (certain, likely, possible).

      -

      Alex: Keep the teaching thread moving. This is where The universal safety net becomes real: if everything else fails, post this on your challenge issue. That matters in practice: I attempted Challenge 16 and here is what happened: What I tried: [specific actions] What I expected: [what should have happened] What actually happened: [error or unexpected result] What I learned: [even from failure, what do I understand now?].

      +

      Alex: The big idea today: VoiceOver and TalkBack guide for iOS and Android GitHub apps. We will name the concept, explain why it matters, practice the move, and point out the checks that tell you the work is real.

      +

      Jamie: So the episode should work even if someone has not read the chapter yet.

      +

      Alex: Exactly. The transcript has to stand on its own. It can point toward practice, but it should teach the concept right here in the conversation.

      -

      Jamie: Let's pause on 55 AI Agents Across 3 Teams and 5 Platforms. What should a learner take away from it?

      -

      Alex: Keep the learner anchored in 55 AI Agents Across 3 Teams and 5 Platforms. Day 2, Block 3 Material Before you read this guide: Accessibility Agents is a growing open source ecosystem: 55 AI-powered agents organized into three teams (Accessibility, GitHub Workflow, and Developer Tools), running on five platforms (GitHub Copilot,. This is the part to say slowly: This chapter introduces the full landscape.

      -

      Alex: Keep the teaching thread moving. Start with Core Prerequisites (Required for All Agents). There is something to understand, something to try, and something that proves the try worked.

      -

      Alex: The practical takeaway is this. [ ] Chapter 0: Pre-Workshop Setup - Git, VS Code, and GitHub account. [ ] Chapter 16: GitHub Copilot - GitHub Copilot Chat installed and working. [ ] GitHub Copilot access (Copilot Free tier is enough for this workshop). [ ].github/agents/ folder exists in your repository (or will create custom agents).

      -

      Jamie: Let's pause on Agent Prerequisites (The "Skill First" Principle). What should a learner take away from it?

      -

      Alex: Start with Agent Prerequisites (The "Skill First" Principle): Every agent automates a skill you should already know by hand. The next useful detail is this: Before using any agent, verify you have done the corresponding manual work.

      +

      Jamie: Okay, set the room for us. What are we walking into?

      +

      Alex: Start with Accessibility Guide for iOS and Android: GitHub Mobile brings issues, pull requests, notifications, and code review to your iPhone, iPad, or Android device. The next useful detail is this: This appendix covers setup, VoiceOver and TalkBack usage, and the tasks best suited to mobile.

      +

      Alex: The next layer is this. Start with Learning Cards: GitHub Mobile Overview. There is something to understand, something to try, and something that proves the try worked.

      +

      Alex: The practical anchors are these. GitHub Mobile supports VoiceOver (iOS) and TalkBack (Android) natively -- swipe right to move through elements, double-tap to activate. The app uses five bottom tabs (Home, Notifications, Explore, Pull Requests, Profile) -- swipe left or right along the bottom tab bar to switch between them. Use the VoiceOver Rotor (two-finger twist) set to Headings to jump between sections within an issue or PR description. GitHub Mobile supports dynamic text sizing on both iOS and Android -- increase your system font size and the app respects it. Dark mode is available in the app settings and follows your system preference -- use it to reduce glare on OLED screens. The simplified diff view in Files Changed shows additions and removals as text only, without the two-column table layout used on desktop.

      +

      Jamie: What is the one idea that makes the next few steps less mysterious?

      +

      Alex: This is where 1. Installing GitHub Mobile becomes real: after installing, sign in with your GitHub account. That matters in practice: Enable notifications when prompted - these are essential for staying on top of PR reviews and issue activity without constantly checking the web.

      -

      Alex: Keep the teaching thread moving. Here is the plain-English version of Workshop Recommendation (Chapter 19 / Challenge 15). Chapter 19 is the agent exploration and hands-on validation chapter - where students match agents to skills they already have and learn how to trust, evaluate, and improve AI-powered workflow automation. Put another way, it supports Challenge 15: Meet the Agents.

      -

      Alex: The practical takeaway is this. There are 3 guided + 1-2 optional contribution challenges. Automation check: none (agent output requires human judgment before use). The evidence is issue comment showing agent output and your evaluation of it. The pattern is explore, validate, read internals, optionally contribute.

      -

      Jamie: Let's pause on Challenge 15 Set. What should a learner take away from it?

      -

      Alex: Start with Challenge 15 Set. There is something to understand, something to try, and something that proves the try worked.

      -

      Alex: First, agent Discovery Mapping - identify 3-5 agents that match skills you already have from Day 1. Then, agent Skill Validation - run one agent and evaluate its output against your manual experience. After that, agent Instructions Deep Dive - read one agent's source file and assess what it can and cannot do. Finally, improve an Existing Agent (optional hackathon) - find a gap in an agent's instructions and fix it via PR. It is a checklist, but a meaningful one: every item creates evidence that the next step is safe.

      -

      Jamie: Before we leave Challenge 15 Set, what is the practical point?

      -

      Alex: First, propose a New Agent (optional hackathon) - file an issue proposing an agent for an uncovered workflow. It is like walking a hallway with named doors: read the sign, enter the right room, then confirm where you landed.

      -

      Jamie: Let's pause on Challenge 15.1 Step-by-Step: Agent Discovery Mapping. What should a learner take away from it?

      -

      Alex: Keep the learner anchored in Challenge 15.1 Step-by-Step: Agent Discovery Mapping. Map your Day 1 manual skills to specific agents in the ecosystem so you know which agents you are ready to use. This is the part to say slowly: GitHub.com - the accessibility-agents repository and your assigned Challenge 15 issue. A good GitHub workflow is like a well-run meeting: everyone knows the topic, the next action, and who has the floor.

      -

      Alex: The practical takeaway is this. @daily-briefing (maps to repository and issue awareness from Chapters 2-4). @issue-tracker (maps to Chapter 4 issue workflow). @pr-review (maps to Chapter 6 and Chapter 14 review workflow). Example: You filed issues manually (Ch 4) - you can use @issue-tracker.

      -

      Alex: First, fork the accessibility-agents repository on GitHub.com. Then, open the repository and navigate to Section 3 of the README (or this chapter's Section 3 below) to see the full list of 55 agents organized by team. After that, read through the agent names and descriptions. For each one, ask yourself: "Have I done this task manually during the workshop?". Finally, identify 3-5 agents that match workflows you already practiced. It is like walking a hallway with named doors: read the sign, enter the right room, then confirm where you landed.

      -

      Jamie: Before we leave Challenge 15.1 Step-by-Step: Agent Discovery Mapping, what is the practical point?

      -

      Alex: First, open your assigned Challenge 15 issue. Then, post a discovery mapping comment using this format. The rhythm is simple: orient, act, verify, then continue.

      +

      Alex: Now bring the learner back to the room. Keep the learner anchored in 2. Getting Around the App. GitHub Mobile is organized into five main tabs at the bottom of the screen. This is the part to say slowly: Navigate between tabs with a single tap (or swipe on iOS with VoiceOver active).

      +

      Jamie: What would you say to someone who is already bracing for this to be too much?

      +

      Alex: Start with Enabling VoiceOver. There is something to understand, something to try, and something that proves the try worked.

      +

      Alex: The parts worth keeping in working memory are these. Triple-click the side button (iPhone X and later) or triple-click the Home button to toggle VoiceOver. Or: Settings → Accessibility → VoiceOver → toggle on.

      +

      Alex: The useful habit is simple: orient first, act second, verify third. That pause before acting is part of the work.

      +

      Alex: That matters because of the next idea. Start with Rotor in GitHub Mobile: Open the Rotor by rotating two fingers on the screen as if turning a dial. The next useful detail is this: Useful rotor settings for GitHub Mobile. Think of it like entering a new building: first you find the lobby, then the room, then the door you actually need.

      +

      Alex: On the ground, that means a few things. Headings - jump between section headings on an issue or PR description. Links - navigate to linked issues, commits, or external URLs. Form Controls - jump to input fields when writing a comment. Actions - available actions for the focused element (assign, label, close).

      -

      Jamie: Let's pause on Challenge 15.2 Step-by-Step: Agent Skill Validation. What should a learner take away from it?

      -

      Alex: The reason Challenge 15.2 Step-by-Step: Agent Skill Validation matters is that run one agent, read its output, and evaluate whether it matches your manual experience. That gives the learner a simple foothold: VS Code with the accessibility-agents repository cloned and Copilot Chat open.

      -

      Alex: The practical takeaway is this. @daily-briefing morning briefing. @issue-tracker find open issues labeled good-first-issue in accessibility-agents. @pr-review show open PRs in accessibility-agents.

      -

      Alex: First, clone your fork of accessibility-agents to VS Code (or open it in github.dev). Then, open Copilot Chat: Ctrl+Shift+I (Mac: Cmd+Shift+I). After that, choose one agent from your discovery list. If unsure, start with @daily-briefing or @issue-tracker. Finally, run it with a simple prompt. The rhythm is simple: orient, act, verify, then continue.

      -

      Jamie: Before we leave Challenge 15.2 Step-by-Step: Agent Skill Validation, what is the practical point?

      -

      Alex: First, read the agent's output carefully. Take a moment to think about what you expected. Then, open your assigned Challenge 15 issue and post an evaluation comment. Think of it as a rail line: each stop confirms you are still on the right route before the next one.

      -

      Jamie: Let's pause on Challenge 15.3 Step-by-Step: Agent Instructions Deep Dive. What should a learner take away from it?

      -

      Alex: Start with Challenge 15.3 Step-by-Step: Agent Instructions Deep Dive: Read one agent's source file to understand what instructions it follows, what tools it can use, and what mistakes it could make. The next useful detail is this: VS Code or GitHub.com - reading files in the accessibility-agents repository.

      -

      Alex: The practical takeaway is this. What is this agent trying to do? (its purpose). What tools does it have access to? (tool permissions). What constraints or guardrails are in the instructions?

      -

      Alex: First, in the accessibility-agents repository, navigate to the.github/ folder (or wherever agent definition files are stored). Then, open one.agent.md or.prompt.md file for an agent you used or are curious about. After that, read the file and identify. Finally, think critically: could this agent make a mistake? What kind? Think of it as a rail line: each stop confirms you are still on the right route before the next one.

      -

      Jamie: Before we leave Challenge 15.3 Step-by-Step: Agent Instructions Deep Dive, what is the practical point?

      -

      Alex: First, open your assigned Challenge 15 issue and post your analysis. Treat it like a recipe: do not add the next ingredient until the previous one is actually in the bowl.

      -

      Jamie: Let's pause on Optional Extensions 15.4-15.5 (Hackathon). What should a learner take away from it?

      -

      Alex: Here is the plain-English version of Optional Extensions 15.4-15.5 (Hackathon). Extension 15.4: Improve an Existing Agent (45 min). Put another way, extension 15.5: Propose a New Agent (60 min).

      -

      Alex: The practical takeaway is this. Find an agent whose instructions have a gap (use Section 6 suggestions or file an issue). Fork the repo, edit the agent's.agent.md file. Get a facilitator review. Open a PR with your improvement.

      +

      Jamie: How would you walk the room through that step by step?

      +

      Alex: Start with Writing Comments with VoiceOver. There is something to understand, something to try, and something that proves the try worked.

      +

      Alex: First, navigate to the comment field (swipe to it or use Rotor → Form Controls). Then, double tap to activate and open the keyboard. After that, type your comment; VoiceOver announces each character. Finally, when done, swipe to the Comment button and double tap to submit. Treat it like a recipe: do not add the next ingredient until the previous one is actually in the bowl.

      +

      Alex: This is where the talk moves from concept to action. Start with Enabling TalkBack. There is something to understand, something to try, and something that proves the try worked.

      +

      Alex: The room should hear these as checkpoints. Settings → Accessibility → TalkBack → toggle on. Or: hold both volume keys for three seconds (if the shortcut is enabled).

      +

      Jamie: Where do you want a learner to place their attention here?

      +

      Alex: Keep the learner anchored in TalkBack Menu. Tap with three fingers (or swipe down then right) to open the TalkBack menu.

      +

      Alex: These are the details that keep the idea from floating away. Change the reading granularity (character, word, line, paragraph). Activate reading controls. Copy text.

      -

      Alex: Keep the teaching thread moving. This is where Completing Challenge 15: Submit Your Evidence becomes real: your evidence is the Challenge 15 issue comments for 15.1, 15.2, and 15.3. That matters in practice: For optional extensions, your PR or proposal issue is the evidence. The workshop is closer to rehearsal than lecture. You hear the move, try the move, and then check what changed.

      -

      Jamie: Let's pause on Expected Outcomes. What should a learner take away from it?

      -

      Alex: Start with Expected Outcomes. There is something to understand, something to try, and something that proves the try worked.

      -

      Alex: The practical takeaway is this. Student can map personal Day 1 skills to specific agents in the ecosystem. Student understands the Skill First, Agent Second principle and can articulate why agent output requires human judgment. Student can read agent instructions and evaluate what an agent can and cannot do. Student has used at least one agent and verified it against manual skills. (Optional) Student has contributed to the accessibility-agents ecosystem with a fix, improvement, or proposal.

      -

      Jamie: Let's pause on If You Get Stuck. What should a learner take away from it?

      -

      Alex: The reason If You Get Stuck matters is that continue learning: The GitHub Skills courses Build Applications with Copilot Agent Mode and Expand Your Team with Copilot explore agent-powered development workflows. That gives the learner a simple foothold: see Appendix Z for the full catalog.

      -

      Alex: First, cannot find an agent that matches your skills? Start with @daily-briefing or @issue-tracker - those build directly on Chapter 2-5 material. If you have not done those manual steps yet, go back to those chapters first. Then, agent output does not make sense? That is the right response. Paste the output in an issue comment along with your confusion. That is valuable feedback - the agent may need better instructions or guardrails. After that, cannot access the agents in Copilot Chat? Verify: Is Copilot Chat extension installed (not just base Copilot)? Are you signed in to GitHub in VS Code? Does.github/agents/ folder exist in your cloned repository? Finally, repository will not clone? Use the terminal: git clone https://github.com/[your-username]/accessibility-agents.git then open the folder in VS Code. The rhythm is simple: orient, act, verify, then continue.

      -

      Jamie: Before we leave If You Get Stuck, what is the practical point?

      -

      Alex: First, ask facilitator to show them what agent you wanted to run, what output you got, and what you expected. Then, finished but not sure you did it right? Compare your work against the Challenge 15 reference solution. Think of it as a rail line: each stop confirms you are still on the right route before the next one.

      +

      Jamie: What is the ordered workflow?

      +

      Alex: Start with Writing Comments with TalkBack. There is something to understand, something to try, and something that proves the try worked.

      +

      Alex: First, locate the comment field - TalkBack announces "Edit text, double tap to edit". Then, double tap to enter the field. After that, use the on-screen keyboard or dictation to type. Finally, locate the Comment button and double tap to submit. The rhythm is simple: orient, act, verify, then continue.

      +

      Jamie: Give me the version that sounds like an instructor, not a manual.

      +

      Alex: Start with 5. Working with Notifications: GitHub Mobile's Notifications tab is one of its strongest features for AT users - it surfaces all activity in a clean, linear list that is much easier to navigate than the GitHub web notifications page.

      +

      Alex: A solid project habit is to treat metadata as decision support. Labels, status, assignees, and notifications tell you what kind of attention the work needs.

      +

      Alex: Hold that next to this. Start with Learning Cards: Mobile Notifications. There is something to understand, something to try, and something that proves the try worked.

      +

      Alex: That shows up in the workshop in a few specific ways. The Notifications tab presents a linear list that is more accessible than the web version -- swipe right through items one by one to hear each notification's context. Filter controls are accessible form elements at the top -- navigate to the filter icon, activate it, then swipe through filter options (Type, Repository, Reason). Swipe actions (left to archive, right to mark done) work with VoiceOver custom actions -- use the VoiceOver Actions rotor item on each notification. Notifications are displayed as a vertical list with the repository name, notification type, and title on each row -- text is sized according to your system accessibility settings. The filter panel overlays on top of the list -- look for the funnel icon in the top-right corner of the Notifications tab. Unread notifications appear with a blue dot indicator on the left edge of each row.

      -

      Jamie: Let's pause on Learning Moment. What should a learner take away from it?

      -

      Alex: Start with Learning Moment: The 55 agents exist because someone did the manual work first, then automated the repetitive parts. The next useful detail is this: As you explore agents, you are not just learning tools - you are learning what automation looks like when it is built on real expertise and real constraints.

      -

      Jamie: Let's pause on Learning Pattern Used in This Chapter. What should a learner take away from it?

      -

      Alex: Start with Learning Pattern Used in This Chapter. There is something to understand, something to try, and something that proves the try worked.

      -

      Alex: First, map your existing skills to available tools (discovery before action). Then, run one tool and evaluate its output critically (trust but verify). After that, read the source to understand capabilities and limits (internals matter). Finally, contribute improvements based on your evaluation (close the feedback loop). Treat it like a recipe: do not add the next ingredient until the previous one is actually in the bowl.

      -

      Jamie: Let's pause on Capstone: Share Your Feedback (The Most Important Task!). What should a learner take away from it?

      -

      Alex: This is where Capstone: Share Your Feedback (The Most Important Task!) becomes real: you have now explored the full agent ecosystem, completed the workshop, and have valuable perspective on what worked, what confused you, and what we should improve for the next cohort. That matters in practice: Your feedback directly shapes the future of this project.

      +

      Jamie: If I am listening before the workshop starts, what should settle in my mind first?

      +

      Alex: Start with Inbox Management. There is something to understand, something to try, and something that proves the try worked.

      +

      Alex: For a learner, the useful signals are these. Swipe left on a notification to reveal quick actions: Mark as read, Archive, Unsubscribe. Swipe right to mark as done. Tap a notification to open the full issue or PR.

      +

      Alex: That connects to another useful point. Keep the learner anchored in Filtering Notifications. Use the filter icon at the top right to filter. This is the part to say slowly: With VoiceOver or TalkBack, the filter controls are accessible form elements. A good GitHub workflow is like a well-run meeting: everyone knows the topic, the next action, and who has the floor.

      +

      Alex: Here is what that changes in practice. Type (Issues, PRs, Releases, etc.). Repository. Reason (you were @mentioned, a review was requested, etc.).

      +

      Jamie: Let's pause on 6. Reviewing Pull Requests. What should a learner take away from it?

      +

      Alex: The reason 6. Reviewing Pull Requests matters is that mobile is well suited for quick PR reviews - approving straightforward changes, leaving a comment, or checking CI status while away from your desk.

      +

      Alex: A solid pull request habit is to separate three questions: what changed, why it changed, and what still needs review. That keeps the conversation useful instead of noisy.

      -

      Alex: Keep the teaching thread moving. Keep the learner anchored in Submit Workshop Feedback. Use the Workshop Feedback form to share. This is the part to say slowly: Answer as much or as little as you're comfortable sharing.

      -

      Alex: The practical takeaway is this. Which agents stood out? (Most useful or surprising). Which agents confused you? (What would make them better). Was the chapter progression logical? (Did earlier chapters prepare you for later ones). Accessibility experience (If applicable - did any assistive technology work/fail?).

      -

      Jamie: Let's pause on 1. The Principle: Skill First, Agent Second. What should a learner take away from it?

      -

      Alex: The reason 1. The Principle: Skill First, Agent Second matters is that accessibility Agents is not a way to skip learning GitHub. That gives the learner a simple foothold: it is a way to amplify skills you have already built through deliberate practice.

      -

      Alex: The practical takeaway is this. Verify that the agent's output is correct. Catch when the agent misses context that only you have. Edit the agent's drafts into something worth posting under your name. Know when the agent is confidently wrong.

      -

      Alex: Keep the teaching thread moving. Start with Every agent has a manual prerequisite. If you have not done the corresponding skill by hand, the agent is not ready for you yet - and you are not ready for it: This applies across all three teams and all 55 agents. The next useful detail is this: Before running any agent, the facilitator asks the same question. Think of it like entering a new building: first you find the lobby, then the room, then the door you actually need.

      -

      Alex: The practical takeaway is this. GitHub Workflow agents automate repository navigation, issue triage, PR review, and contribution analytics - skills you practiced on Day 1. Accessibility agents automate WCAG auditing, contrast checking, keyboard navigation review, and document scanning - knowledge from your accessibility training and the standards in Appendix C. Developer Tools agents automate accessible coding patterns for Python, wxPython, and desktop applications - skills from your development experience.

      +

      Alex: Here is the practical turn. Start with Navigating a PR: When you open a pull request, the screen is divided into sections. The next useful detail is this: VoiceOver and TalkBack announce these as headings.

      +

      Alex: That becomes easier when you listen for these cues. Description - the PR body with any images or checklists. Commits - individual commits in this PR. Files changed - a simplified diff view. Checks - CI/CD status.

      +

      Jamie: What does the learner do first, second, and then after that?

      +

      Alex: Start with Leaving a Review. There is something to understand, something to try, and something that proves the try worked.

      +

      Alex: First, scroll to or navigate to the Review changes button. Then, double tap to open the review panel. After that, choose Approve, Request changes, or Comment. Finally, add an optional comment in the text field. Treat it like a recipe: do not add the next ingredient until the previous one is actually in the bowl.

      +

      Jamie: Turn that into a path someone can follow.

      +

      Alex: First, activate Submit review. It is a checklist, but a meaningful one: every item creates evidence that the next step is safe.

      +

      Alex: Keep the thread going. This is where Viewing Diffs becomes real: the Files Changed tab shows a simplified diff - additions and removals are text-only (no table layout). That matters in practice: Each changed line is announced as "Added: [content]" or "Removed: [content]", which is generally more accessible than the web diff table on small screens. The workshop is closer to rehearsal than lecture. You hear the move, try the move, and then check what changed.

      -

      Jamie: Let's pause on Learning Cards: Skill First, Agent Second. What should a learner take away from it?

      -

      Alex: Start with Learning Cards: Skill First, Agent Second. There is something to understand, something to try, and something that proves the try worked.

      -

      Alex: The practical takeaway is this. Before using any agent, verify you can do the task manually -- for @daily-briefing, confirm you can navigate Issues and PRs on GitHub.com with keyboard shortcuts (j/k to move, Enter to open). Agent output appears in Copilot Chat -- press Alt+F2 to open Accessible View and read the full response with arrow keys before acting on it. If an agent produces something you do not understand, stop and learn the manual skill first from the relevant chapter. Agent responses appear in the Copilot Chat panel -- drag the panel wider or use Alt+F2 (Accessible View) for a larger, cleaner reading pane. Each agent's instructions are in a.agent.md file you can open in VS Code and read at your preferred zoom level before invoking the agent. The agent ecosystem table in Section 3 uses standard Markdown tables that scale with your editor font size.

      -

      Alex: Keep the teaching thread moving. This is where Quick Install (One Command) becomes real: accessibility Agents now ships with a one-liner installer that sets up all 55 agents for your platform.

      -

      Jamie: What should they understand before typing anything?

      -

      Alex: Start with macOS / Linux. There is something to understand, something to try, and something that proves the try worked.

      -

      Alex: Treat examples as spoken recipes, not decorations. You may hear something like curl -fsSL https://raw.githubusercontent.com/Community-Access/accessibility-agents/main/install.sh bash. Read the command, understand what it changes, then run it only when the repository state matches the lesson.

      +

      Jamie: Give me the sequence, because order matters here.

      +

      Alex: Start with Filing an Issue. There is something to understand, something to try, and something that proves the try worked.

      +

      Alex: First, navigate to the repository. Then, tap Issues → the + button or New Issue. After that, fill in the title and body. Finally, optionally assign labels, assignees, and milestone - each is a tappable field. It is like walking a hallway with named doors: read the sign, enter the right room, then confirm where you landed.

      +

      Jamie: Let's pause on Filing an Issue. What should a learner take away from it?

      +

      Alex: First, tap Submit. The rhythm is simple: orient, act, verify, then continue.

      +

      Alex: A solid issue habit is to read the title, the body, and the timeline before acting. You are listening for the requested action, the missing evidence, and the person who needs a response.

      +

      Alex: Another way to ground it. Start with Finding Your Issues. There is something to understand, something to try, and something that proves the try worked.

      +

      Alex: A few details make that real. Pull Requests tab → Created by you or Assigned to you filters. For issues: Home feed shows recent activity; or navigate to a specific repository → Issues → filter by Assignee, Label, or Author.

      +

      Jamie: What stays the same when the tool changes?

      +

      Alex: Start with 8. What Mobile Does Well vs. Desktop: Best use of GitHub Mobile: notification triage, quick approvals and comments, catching up on activity between sessions. The next useful detail is this: For writing substantial code, descriptions, or reviewing complex diffs, use the web or VS Code.

      -

      Alex: Keep the teaching thread moving. The reason Windows (PowerShell) matters is that the installer detects which AI tools you have installed (VS Code with Copilot, Claude Code, Gemini CLI, Claude Desktop, Codex CLI) and configures the appropriate agent files for each platform. That gives the learner a simple foothold: to uninstall, run the corresponding uninstall script from the repository. The interface gets friendlier when it stops being a wall of controls and starts being a set of named places.

      -

      Jamie: Let's pause on Workshop Setup (Fork and Clone). What should a learner take away from it?

      -

      Alex: Start with Workshop Setup (Fork and Clone): For the workshop, you will also fork and clone the repository so you can make contributions. The next useful detail is this: If Copilot Chat works, the agents work.

      -

      Alex: First, fork accessibility-agents to your GitHub account (you did this on Day 1 or Day 2 morning). Then, clone your fork. After that, open in VS Code: navigate to the folder and run code. (or File, then Open Folder). Finally, open Copilot Chat: Ctrl+Shift+I. Think of it as a rail line: each stop confirms you are still on the right route before the next one.

      -

      Jamie: Before we leave Workshop Setup (Fork and Clone), what is the practical point?

      -

      Alex: First, test: type @daily-briefing morning briefing and press Enter. Treat it like a recipe: do not add the next ingredient until the previous one is actually in the bowl.

      -

      Alex: Treat examples as spoken recipes, not decorations. You may hear something like git clone https://github.com/[your-username]/accessibility-agents.git. Read the command, understand what it changes, then run it only when the repository state matches the lesson.

      -

      Alex: Keep the teaching thread moving. Start with Prerequisites. There is something to understand, something to try, and something that proves the try worked.

      -

      Alex: The practical takeaway is this. GitHub Copilot Chat extension installed (see GitHub Copilot: Installation). Signed in to GitHub via VS Code. A workspace open containing.github/agents/ folder with.agent.md files.

      +

      Alex: This is the part worth saying out loud. Here is the plain-English version of VoiceOver skips some PR descriptions. Long PR descriptions with images, tables, or embedded videos may not read cleanly. Put another way, open the PR in Safari instead - tap the … menu → Open in Browser. It is like learning a transit route. The names of the stops matter because they tell you whether you are still going the right direction.

      +

      Jamie: Let's pause on TalkBack does not announce new notifications badge. What should a learner take away from it?

      +

      Alex: This is where TalkBack does not announce new notifications badge becomes real: the badge count on the Notifications tab updates live but may not be announced. That matters in practice: Navigate directly to the Notifications tab to get the current count read aloud.

      +

      Alex: Before the learner moves on. Keep the learner anchored in The keyboard covers the comment field. Usual iOS/Android behavior - scroll up slightly after the keyboard appears, or rotate to landscape mode to gain more visible space.

      +

      Alex: A solid navigation habit is to prove where you are before activating controls. Headings, landmarks, and the address bar are not trivia; they are your map.

      -

      Jamie: Let's pause on How Agents Are Discovered. What should a learner take away from it?

      -

      Alex: This is where How Agents Are Discovered becomes real: when you type @ in Copilot Chat, VS Code scans. That matters in practice: The Accessibility Agents ecosystem installs agents appropriate to each platform.

      -

      Alex: First,.github/agents/.agent.md in your current workspace. Then, any agents installed globally on your machine. After that, agents defined by extensions. It is a checklist, but a meaningful one: every item creates evidence that the next step is safe.

      -

      Alex: Keep the teaching thread moving. Keep the learner anchored in Optional: Personalize Your Instance. Open preferences.md in VS Code and edit. This is the part to say slowly: Commit preferences.md to your fork. A good GitHub workflow is like a well-run meeting: everyone knows the topic, the next action, and who has the floor.

      -

      Jamie: Let's pause on How Agents Travel with Your Repo. What should a learner take away from it?

      -

      Alex: The reason How Agents Travel with Your Repo matters is that when you fork accessibility-agents, the.github/agents/ folder comes with it.

      -

      Alex: The practical takeaway is this. Any collaborator who clones your fork gets all 55 agents automatically. You can customize agents for your specific project by editing the.agent.md files in your fork. Any project can have agents - create a.github/agents/ folder in any repository and add.agent.md files using the same pattern. The one-liner installer can also set up agents globally, so they are available in every workspace you open.

      +

      Jamie: Let's pause on Can't find the Submit button after writing a review. What should a learner take away from it?

      +

      Alex: The reason Can't find the Submit button after writing a review matters is that scroll down past the text field; buttons are below the keyboard dismiss area. That gives the learner a simple foothold: on iOS, tap elsewhere to dismiss the keyboard first, then scroll to Submit.

      +

      Alex: Keep the teaching thread moving. Start with GitHub Mobile crashes or freezes: If the problem persists, sign out and back in via Profile → Settings → Sign out. The next useful detail is this: Next: Appendix W: GitHub Pages Back: Appendix U: Discussions and Gists Teaching chapter: Chapter 05: Working with Issues. Think of it like entering a new building: first you find the lobby, then the room, then the door you actually need.

      -

      Alex: Keep the teaching thread moving. Start with Invoking Agents on GitHub.com: Accessibility Agents agents run in VS Code. The next useful detail is this: But the same.agent.md files can also be invoked directly on GitHub.com - no VS Code, no local clone required.

      -

      Jamie: Let's pause on Option 1: Copilot Chat with Task mode. What should a learner take away from it?

      -

      Alex: Here is the plain-English version of Option 1: Copilot Chat with Task mode. Screen reader users (NVDA / JAWS / VoiceOver).

      -

      Alex: First, open Copilot Chat on GitHub.com (icon in the top-right navigation bar). Then, click Task in the mode picker. After that, optionally click the agent picker to select a custom agent. Finally, type your request and click Send. Treat it like a recipe: do not add the next ingredient until the previous one is actually in the bowl.

      -

      Jamie: Before we leave Option 1: Copilot Chat with Task mode, what is the practical point?

      -

      Alex: First, Copilot analyzes the task and can create a branch and open a PR automatically. Then, open Copilot Chat on GitHub.com (navigate to icon in top-right navigation → Enter). After that, the mode picker (Task vs Chat) is a set of radio buttons - navigate with Arrow keys to select "Task". Finally, the agent picker is a listbox - Up/Down Arrow to navigate, Enter to select. It is a checklist, but a meaningful one: every item creates evidence that the next step is safe.

      -

      Jamie: Let's pause on Option 2: Assign an issue to Copilot. What should a learner take away from it?

      -

      Alex: This is where Option 2: Assign an issue to Copilot becomes real: screen reader users (NVDA / JAWS / VoiceOver). That matters in practice: This is the bridge to Section 6 (The Cloud Extension). The workshop is closer to rehearsal than lecture. You hear the move, try the move, and then check what changed.

      -

      Alex: First, open any issue (or create a new one describing the task). Then, in the Assignees sidebar section, click the gear icon. After that, in the dropdown, click Copilot as the assignee. Finally, a dialog opens - optionally provide additional instructions and select a custom agent. It is a checklist, but a meaningful one: every item creates evidence that the next step is safe.

      -

      Jamie: Before we leave Option 2: Assign an issue to Copilot, what is the practical point?

      -

      Alex: First, click Assign to confirm. Then, open any issue in the repository. After that, press B to navigate to the Assignees gear button → Enter to open the popup. Finally, navigate the popup with Arrow keys → find "Copilot" → Enter to select. It is like walking a hallway with named doors: read the sign, enter the right room, then confirm where you landed.

      -

      Alex: A solid issue habit is to read the title, the body, and the timeline before acting. You are listening for the requested action, the missing evidence, and the person who needs a response.

      +

      Jamie: What should people carry with them after this?

      +

      Alex: Carry the map. Know what page or tool you are in, know which action you are taking, and know what confirmation should follow. If the confirmation is missing, pause. That pause is not wasted time; it is professional judgment.

      +

      Jamie: That is a better way to say it than just follow the steps.

      +

      Alex: Right. Steps matter, but understanding wins. That is episode 32. Next in the series is episode 33, where we keep building the same contributor muscles.

      +
      +
      -

      Jamie: There are a lot of tools in play. How do we keep that from feeling like a contest?

      -

      Alex: Keep the learner anchored in Copilot on GitHub.com - Browser-Native Features. Beyond assigning Copilot to issues and using Task mode in Chat, GitHub.com now has several standalone Copilot features built directly into the web interface. This is the part to say slowly: These work entirely in your browser - no VS Code, no local clone needed.

      -

      Alex: Keep the teaching thread moving. The reason Copilot PR Summary matters is that on any open pull request, GitHub adds a "Summarize" button in the PR description area. That gives the learner a simple foothold: selecting it generates a plain-language summary of what the PR changes, why, and what reviewers should focus on.

      -

      Jamie: Let's pause on Copilot PR Review. What should a learner take away from it?

      -

      Alex: Start with Copilot PR Review: On open PRs you have write access to review, a "Review" button (or Copilot icon) appears in the Files changed tab. The next useful detail is this: Copilot generates inline review comments across the diff.

      +

      62. Episode 33: Publishing with GitHub Pages

      +

      Free static site hosting, custom domains, HTTPS, and accessibility.

      +

      Based on: Appendix W: Publishing with GitHub Pages

      + + +

      Download Episode 33 (MP3)

      +
      +Read Transcript - Episode 33: Publishing with GitHub Pages + +

      Transcript

      +

      Alex: Welcome back to Git Going with GitHub. This is episode 33: Publishing with GitHub Pages. I am Alex, and today we are turning Publishing with GitHub Pages from a list of instructions into a working mental model.

      +

      Jamie: And I am Jamie. I will stop us whenever the instructions sound simple on paper but might feel different with a keyboard and screen reader.

      -

      Alex: Keep the teaching thread moving. Here is the plain-English version of Copilot in Issues. On any issue page, Copilot adds sidebar buttons that appear once the page loads. Put another way, look in the right sidebar on any issue page for a Copilot section with "Explain" and "Suggest fix" buttons. It is like learning a transit route. The names of the stops matter because they tell you whether you are still going the right direction.

      -

      Alex: The practical takeaway is this. "Explain this issue" - generates a plain-language explanation of a complex technical issue. "Suggest fix" - proposes an approach to resolving the issue (opens a task/PR workflow).

      -

      Jamie: Let's pause on GitHub Models - Free AI Playground. What should a learner take away from it?

      -

      Alex: This is where GitHub Models - Free AI Playground becomes real: github.com/marketplace/models is a free playground where you can test AI models (OpenAI GPT-4o, Meta Llama 3, Mistral, Phi-4 Mini, and others) directly in your browser. That matters in practice: Why it matters for Accessibility Agents: When you build custom agents and prompts, you can test your system prompts and prompt templates in GitHub Models before adding them to your.prompt.md files - rapid iteration without burning API credits.

      -

      Alex: The practical takeaway is this. Send prompts to any listed model and compare responses side by side. Adjust parameters (temperature, max tokens) without any setup. Use the code sample generator to get API code for your chosen model. All free with a GitHub account (rate-limited for free tier).

      -

      Alex: Keep the teaching thread moving. Keep the learner anchored in Copilot-Drafted Release Notes. When creating a release (Releases tab → Draft a new release), GitHub provides a "Generate release notes" button. This is the part to say slowly: It scans merged PRs since the last release and drafts categorized release notes automatically.

      +

      Alex: Free static site hosting, custom domains, HTTPS, and accessibility. That is the surface description. Underneath it, we are building judgment: where to focus, what to ignore, and how to verify the result.

      +

      Jamie: So we are not using the audio as a shortcut around learning. We are using it to make the learning easier to enter.

      +

      Alex: Yes. A good audio lesson gives someone enough context to try the work with confidence, even before they open the written material.

      -

      Jamie: What does someone need before they touch the keyboard?

      -

      Alex: Start with Learning Cards: Setup and Configuration. There is something to understand, something to try, and something that proves the try worked.

      -

      Alex: The practical takeaway is this. Run the installer command in the VS Code terminal (Ctrl+) -- it announces progress as it copies agent files to.github/agents/`. After installation, press Ctrl+Shift+E to open the Explorer and navigate to.github/agents/ to verify agent files are present. Edit.github/agents/preferences.md to configure your username, repositories, and notification preferences -- it is a standard Markdown file. The installer creates files in.github/agents/ and.github/prompts/ -- verify in the Explorer sidebar that these folders appeared. Open preferences.md in the editor to set your configuration -- use Ctrl+= to zoom if the YAML frontmatter is hard to read. Agent files use.agent.md extension -- they appear alongside regular Markdown files in the Explorer but are distinguished by their extension.

      -

      Alex: Keep the teaching thread moving. Start with 3. The Ecosystem: 55 Agents, 3 Teams, 5 Platforms: Accessibility Agents is an ecosystem of 55 specialized agents organized into three teams, each addressing a different dimension of accessible software development. The next useful detail is this: Browse all three teams below, then choose the agents that match your current skills and interests. Think of it like entering a new building: first you find the lobby, then the room, then the door you actually need.

      -

      Jamie: Let's pause on Team 1: Accessibility (26 agents). What should a learner take away from it?

      -

      Alex: Here is the plain-English version of Team 1: Accessibility (26 agents). These agents audit, fix, and enforce accessibility across web, document, and mobile platforms.

      +

      Jamie: Okay, set the room for us. What are we walking into?

      +

      Alex: Start with How to Deploy a Static Website Directly from Your Repository: GitHub Pages lets you publish a static website straight from a GitHub repository - no server, no hosting bill, no deployment pipeline required for simple sites. The next useful detail is this: This appendix explains how to enable it, what it can publish, and how to ensure the published site meets the same accessibility standards as your source code.

      +

      Alex: The next layer is this. Start with Learning Cards: GitHub Pages Overview. There is something to understand, something to try, and something that proves the try worked.

      +

      Alex: The practical anchors are these. The Pages settings are under Settings (gear icon in repository navigation) then "Pages" in the left sidebar under the "Code and automation" group heading. Branch and folder selectors in the Pages settings are standard select elements -- navigate with arrow keys to choose your publishing source. After deployment, the published URL appears as a link at the top of the Pages settings page. GitHub Pages settings use the same layout as other repository settings -- look for the "Pages" link in the left sidebar after clicking Settings. The deployment status indicator shows a green checkmark for successful deployments and a red X for failures. Published sites inherit no special styling from GitHub -- ensure your site's CSS provides adequate contrast and font sizing.

      +

      Jamie: What is the one idea that makes the next few steps less mysterious?

      +

      Alex: This is where 1. What GitHub Pages Is becomes real: GitHub Pages is a static site hosting service built into GitHub. That matters in practice: It serves files directly from a branch or folder in your repository at a URL of the form.

      -

      Alex: Keep the teaching thread moving. This is where Team 2: GitHub Workflow (12 agents) becomes real: these agents automate GitHub operations - issue triage, PR review, contribution analytics, and repository management.

      -

      Jamie: What should someone listen for when a lesson offers more than one tool path?

      -

      Alex: Keep the learner anchored in Team 3: Developer Tools (6 agents). These agents support accessible application development across desktop and cross-platform frameworks.

      -

      Alex: Keep the teaching thread moving. The reason Beyond Agents: The Supporting Ecosystem matters is that the 55 agents are backed by additional resources in the repository. The interface gets friendlier when it stops being a wall of controls and starts being a set of named places.

      +

      Alex: Now bring the learner back to the room. Start with What it is good for. There is something to understand, something to try, and something that proves the try worked.

      +

      Alex: For a learner, the useful signals are these. Documentation sites. Workshop materials (like this project). Project landing pages. Personal portfolios. Simple blogs via Jekyll.

      +

      Jamie: What is the ordered workflow?

      +

      Alex: The reason Step-by-step (GitHub.com) matters is that GitHub will build and deploy within a minute or two. That gives the learner a simple foothold: the URL appears at the top of the Pages settings once the first deployment succeeds.

      +

      Alex: The parts worth keeping in working memory are these. Deploy from a branch - serve files directly from a branch/folder. GitHub Actions - use a workflow to build and deploy. Select the branch (e.g. main or master). Select the folder: / (root) or /docs.

      +

      Alex: First, go to the repository on GitHub.com. Then, click Settings (the gear icon in the top navigation). After that, in the left sidebar, scroll to Code and automation and click Pages. Finally, under Build and deployment, choose your publishing source. The rhythm is simple: orient, act, verify, then continue.

      +

      Jamie: Give me the sequence, because order matters here.

      +

      Alex: First, if using "Deploy from a branch". Then, click Save. Think of it as a rail line: each stop confirms you are still on the right route before the next one.

      +

      Alex: The useful habit is simple: orient first, act second, verify third. That pause before acting is part of the work.

      +

      Alex: That matters because of the next idea. Start with Screen reader navigation for the Pages settings page. There is something to understand, something to try, and something that proves the try worked.

      +

      Alex: On the ground, that means a few things. The Settings tab is a link in the repository's top navigation bar. It has the accessible name "Settings". The Pages option in the left sidebar is a link under the "Code and automation" group heading. The branch and folder dropdowns are standard elements - navigate with arrow keys.

      +

      Alex: A solid navigation habit is to prove where you are before activating controls. Headings, landmarks, and the address bar are not trivia; they are your map.

      -

      Jamie: Let's pause on Hook-Based Enforcement (Claude Code). What should a learner take away from it?

      -

      Alex: Start with Hook-Based Enforcement (Claude Code): On Claude Code, Accessibility Agents includes a hook system that enforces accessibility standards automatically. The next useful detail is this: This means accessibility enforcement happens whether or not the developer remembers to ask for it.

      -

      Alex: First, proactive detection hook - scans every file edit for accessibility regressions before they are committed. Then, edit gate hook - blocks commits that introduce WCAG violations until they are fixed. After that, session marker hook - tracks which accessibility checks have run during the current session. Think of it as a rail line: each stop confirms you are still on the right route before the next one.

      -

      Alex: Keep the teaching thread moving. Here is the plain-English version of What Would You Build? This is the question that matters most. Put another way, the 55 agents that exist today were built by contributors who saw a gap and filled it.

      -

      Alex: The practical takeaway is this. "Why is there no agent for [framework] accessibility patterns?". "I spend 30 minutes on [task] every week - could an agent do the repetitive part?". "This agent is good but it misses [specific edge case] - I could improve those instructions". "Mobile native accessibility testing has no agent coverage yet - I could start one".

      -

      Jamie: Let's pause on The contribution paths are. What should a learner take away from it?

      -

      Alex: This is where The contribution paths are becomes real: see the Accessibility Agents CONTRIBUTING guide for detailed instructions on each path.

      -

      Alex: First, report an agent gap - file an issue describing what is missing and why it matters. Then, improve existing agent instructions - make an agent smarter about edge cases it misses. After that, add framework-specific patterns - teach agents about React, Vue, Angular, Svelte, or other framework accessibility patterns. Finally, fix installer issues - improve the one-liner scripts for different OS configurations. It is a checklist, but a meaningful one: every item creates evidence that the next step is safe.

      -

      Jamie: Before we leave The contribution paths are, what is the practical point?

      -

      Alex: First, write documentation - help others understand how to use and contribute to agents. It is like walking a hallway with named doors: read the sign, enter the right room, then confirm where you landed.

      +

      Jamie: If I am listening before the workshop starts, what should settle in my mind first?

      +

      Alex: Here is the plain-English version of Deploy from a branch. GitHub reads files directly from a branch. Put another way, best practice: Use /docs to isolate the published content from source files, especially for projects with build pipelines where the output lives in a specific folder.

      +

      Alex: A solid Git habit is to know which branch you are on, what changed, and what confirmation you expect before you run the next command.

      +

      Jamie: What does the learner do first, second, and then after that?

      +

      Alex: This is where GitHub Actions becomes real: use a workflow (YAML file in.github/workflows/) to build your site before publishing. That matters in practice: A basic workflow for this project would.

      +

      Alex: The room should hear these as checkpoints. Your source is Markdown and you need a build step (e.g. this project's scripts/build-html.js). You are using a static site generator like Jekyll, Hugo, or Eleventy. You want to run accessibility tests in CI before publishing.

      +

      Alex: First, check out the repository. Then, run node scripts/build-html.js. After that, upload the html/ folder as the Pages artifact. It is a checklist, but a meaningful one: every item creates evidence that the next step is safe.

      +

      Jamie: Where do you want a learner to place their attention here?

      +

      Alex: Keep the learner anchored in 4. The html/ Folder in This Project. This project has a pre-built HTML mirror of all Markdown content in the html/ folder, generated by scripts/build-html.js. This is the part to say slowly: To publish this as a GitHub Pages site.

      +

      Alex: A solid pull request habit is to separate three questions: what changed, why it changed, and what still needs review. That keeps the conversation useful instead of noisy.

      -

      Alex: Keep the teaching thread moving. Keep the learner anchored in Roadmap: What Is Coming Next. Your contribution could be the next item that ships. This is the part to say slowly: Every agent started as one person's idea and one pull request. A good GitHub workflow is like a well-run meeting: everyone knows the topic, the next action, and who has the floor.

      -

      Alex: The practical takeaway is this. Mobile native agents - agents specialized for iOS (VoiceOver) and Android (TalkBack) native app accessibility. Anthropic Connectors listing - making agents discoverable through the Anthropic marketplace. veraPDF integration - automated PDF/UA validation for the PDF accessibility agent. Document remediation agents - agents that fix accessibility issues in documents, not just find them.

      -

      Jamie: Let's pause on Learning Cards: The Agent Ecosystem. What should a learner take away from it?

      -

      Alex: Start with Learning Cards: The Agent Ecosystem. There is something to understand, something to try, and something that proves the try worked.

      -

      Alex: The practical takeaway is this. The three team tables use standard Markdown table format -- navigate with T (NVDA/JAWS) to jump between tables, then Arrow keys to read cells. Agent names start with @ -- type @ followed by the agent name in Copilot Chat to invoke it (e.g., @daily-briefing). Use Ctrl+Shift+O (symbol outline) in any agent file to navigate between its YAML frontmatter sections (Purpose, Responsibilities, Guardrails). The agent tables are dense -- use Ctrl+= to increase font size or open the file in Markdown Preview (Ctrl+Shift+V) for cleaner rendering. Each team has a distinct table: Team 1 (Accessibility, 26 agents), Team 2 (GitHub Workflow, 15 agents), Team 3 (Developer Tools, 14 agents). Agent files in.github/agents/ have descriptive filenames that match the @agent-name -- browse them in the Explorer to find specific agents.

      -

      Alex: Keep the teaching thread moving. Start with 4. Agents in Detail - Hands-On Reference: This section walks through several agents in depth so you can see how they work, what they produce, and how to evaluate their output. The next useful detail is this: These examples use GitHub Workflow agents because they build directly on Day 1 skills - but the same patterns apply to every agent in the ecosystem.

      +

      Alex: Before the learner moves on. The reason Option A: Manual publishing from html/ folder matters is that because GitHub Pages only supports / (root) or /docs as folder sources, and this project's output is in html/, you have two options. The interface gets friendlier when it stops being a wall of controls and starts being a set of named places.

      +

      Jamie: What is the safe way to learn from that example?

      +

      Alex: Start with Option A1 - Copy html/ contents to docs/: Then set Pages source to branch master, folder /docs.

      +

      Alex: Treat examples as spoken recipes, not decorations. You may hear something like Copy the html/ output into docs/ for GitHub Pages; cp -r html/ docs/; git add docs/; git commit -m "Publish HTML output to docs/ for GitHub Pages"; git push. Read the command, understand what it changes, then run it only when the repository state matches the lesson.

      +

      Jamie: What should happen before anyone copies and runs it?

      +

      Alex: Here is the plain-English version of Option A2 - Rename html/ to docs/. If the project does not already use docs/ for Markdown sources, you could rename the output folder. Put another way, this project uses docs/ for Markdown source files, so this would conflict.

      +

      Alex: Treat examples as spoken recipes, not decorations. You may hear something like Update the build script output path first, then; git mv html/ docs/; git commit -m "Rename html/ to docs/ for GitHub Pages compatibility"; git push. Read the command, understand what it changes, then run it only when the repository state matches the lesson.

      -

      Jamie: Let's pause on Two Types of Agents. What should a learner take away from it?

      -

      Alex: Here is the plain-English version of Two Types of Agents. Before diving in, it helps to know that custom agents fall into two categories - this distinction affects what tool permissions they need and what they can do. Put another way, informational agents search, analyze, and report.

      -

      Alex: Keep the teaching thread moving. This is where Agent 1: @daily-briefing - Morning Briefing becomes real: file.github/agents/daily-briefing.agent.md. That matters in practice: Before you run this agent: You should have manually navigated a repository's Issues tab, read your GitHub Notifications page, understood what a pull request waiting for review looks like, and know the difference between subscribed and participating. The workshop is closer to rehearsal than lecture. You hear the move, try the move, and then check what changed.

      -

      Jamie: Let's pause on What it does. What should a learner take away from it?

      -

      Alex: Keep the learner anchored in What it does. Sweeps every repository you have access to and builds a prioritized dashboard.

      -

      Alex: The practical takeaway is this. Issues opened in the last 24 hours. Pull requests waiting for your review. CI failures on your branches. Security and Dependabot alerts. Community reactions to your recent comments.

      +

      Jamie: What would you say to someone who is already bracing for this to be too much?

      +

      Alex: This is where Option B: GitHub Actions workflow becomes real: this workflow triggers on every push to master, rebuilds the HTML, and deploys the html/ folder.

      +

      Alex: That connects to another useful point. Keep the learner anchored in 5. Custom Domains. GitHub Pages supports custom domains (e.g. This is the part to say slowly: learning.community-access.org instead of community-access.github.io/Learning-Room). A good GitHub workflow is like a well-run meeting: everyone knows the topic, the next action, and who has the floor.

      +

      Jamie: How would you walk the room through that step by step?

      +

      Alex: Start with Setting up a custom domain. There is something to understand, something to try, and something that proves the try worked.

      +

      Alex: First, in repository Settings → Pages, enter your domain in the Custom domain field and click Save. Then, GitHub creates a CNAME file in the repository root containing your domain name. After that, at your DNS provider, create the appropriate records. The rhythm is simple: orient, act, verify, then continue.

      -

      Alex: Keep the teaching thread moving. The reason Example commands matters is that the briefing output uses heading level 2 for each section. That gives the learner a simple foothold: use H key (NVDA/JAWS virtual mode) or VO+Command+H (VoiceOver) to jump between: Open Issues, Review Requests, CI Status, Security Alerts, Community Activity.

      -

      Jamie: Let's pause on Agent 2: @issue-tracker - Issue Management. What should a learner take away from it?

      -

      Alex: Start with Agent 2: @issue-tracker - Issue Management: File.github/agents/issue-tracker.agent.md. The next useful detail is this: Before you run this agent: You should have filed at least one issue using the full manual process - writing a title, description, and reproduction steps; applying labels and a milestone; and reading at least five existing issues to understand what a.

      -

      Alex: Keep the teaching thread moving. Here is the plain-English version of What it does. Finds, prioritizes, and helps you manage issues across all your repositories. It is like learning a transit route. The names of the stops matter because they tell you whether you are still going the right direction.

      -

      Alex: The practical takeaway is this. Cross-repository priority scoring with community sentiment. Batch-reply capability (draft replies to multiple issues at once). Saved search support. Release-awareness (flags issues that affect upcoming releases).

      +

      Alex: Here is the practical turn. Start with GitHub's current A record IPs for apex domains: DNS changes can take up to 48 hours to propagate. The next useful detail is this: GitHub Pages checks and verifies the domain automatically once DNS is configured.

      +

      Jamie: Give me the version that sounds like an instructor, not a manual.

      +

      Alex: Here is the plain-English version of Domain verification. To prevent domain takeover attacks, GitHub recommends verifying your custom domain in your account or organization settings (Settings → Pages → Add a domain). Put another way, this prevents others from claiming your domain for their GitHub Pages if you temporarily remove it.

      +

      Jamie: Turn that into a path someone can follow.

      +

      Alex: This is where 6. HTTPS and Security becomes real: GitHub Pages enforces HTTPS automatically for github.io subdomains. That matters in practice: Never store secrets, API keys, or private data in a GitHub Pages repository. The workshop is closer to rehearsal than lecture. You hear the move, try the move, and then check what changed.

      +

      Alex: First, after DNS propagates, check Enforce HTTPS in Pages settings. Then, GitHub Pages uses Let's Encrypt to provision a certificate automatically. After that, enforcing HTTPS redirects all HTTP traffic to HTTPS. It is a checklist, but a meaningful one: every item creates evidence that the next step is safe.

      -

      Jamie: How should a learner choose a tool without feeling judged by the choice?

      -

      Alex: This is where Example commands becomes real: the agent can draft a reply. That matters in practice: You review the tone against the Culture & Etiquette guide before posting.

      -

      Jamie: What should happen before anyone copies and runs it?

      -

      Alex: Start with Output example. There is something to understand, something to try, and something that proves the try worked.

      -

      Alex: Treat examples as spoken recipes, not decorations. You may hear something like Open Issues Labeled "good-first-issue"; High Priority; - 45 [accessibility-agents] Add NVDA-specific navigation tips (3 comments, opened 5 days ago); - Priority Score: 8/10 (high community interest, clear scope, no assignee); - Recommended for: First-time. Read the command, understand what it changes, then run it only when the repository state matches the lesson.

      -

      Jamie: Let's pause on Agent 3: @pr-review - Pull Request Review. What should a learner take away from it?

      -

      Alex: The reason Agent 3: @pr-review - Pull Request Review matters is that file.github/agents/pr-review.agent.md. That gives the learner a simple foothold: before you run this agent: You should have manually reviewed at least one pull request diff in the GitHub browser interface - navigating the Files Changed tab with your screen reader, reading added and removed lines, leaving at least one inline comment, and.

      +

      Jamie: Let's pause on 7. Accessibility Considerations for Published Sites. What should a learner take away from it?

      +

      Alex: Keep the learner anchored in 7. Accessibility Considerations for Published Sites. Publishing a site does not automatically make it accessible. This is the part to say slowly: Consider the following for the published HTML output.

      +

      Alex: Another way to ground it. Start with Learning Cards: Accessibility of Published Sites. There is something to understand, something to try, and something that proves the try worked.

      +

      Alex: That becomes easier when you listen for these cues. Verify that published HTML pages include a skip-to-content link as the first focusable element -- press Tab once after the page loads to check. Confirm the page has a descriptive title element and a single H1 heading -- these are announced first when the page opens. Test that all internal navigation links work and land on the correct heading or section. Run an automated contrast checker (axe, WAVE) on published pages after any CSS changes to confirm text remains readable. Test the published site at 200% browser zoom to verify layouts do not break or hide content. If the site uses a custom theme, verify it works in both forced-colors mode (Windows High Contrast) and standard mode.

      +

      Jamie: Let's pause on Navigation and landmarks. What should a learner take away from it?

      +

      Alex: Start with Navigation and landmarks: The HTML generated by scripts/build-html.js converts Markdown headings and structure to HTML.

      +

      Alex: A few details make that real. A landmark wrapping the primary content. Logical heading hierarchy (H1 → H2 → H3). A page that reflects the document topic.

      -

      Alex: Keep the teaching thread moving. Start with What it does: Generates full review documents for pull requests. Think of it like entering a new building: first you find the lobby, then the room, then the door you actually need.

      -

      Alex: The practical takeaway is this. Line-numbered diffs with change maps. Risk assessment (what could break, what is high-impact). Before-and-after snapshots. CI results and test coverage information. Suggested inline review comments with line number references.

      -

      Jamie: How do we make tool choice feel like access, not pressure?

      -

      Alex: Here is the plain-English version of Example commands. Critical rule: Read the agent's review. Put another way, the agent produces a starting point - it does not know the project's history, the contributor's background, or the community's implicit standards the way you do.

      -

      Jamie: How do you keep commands from becoming magic words?

      -

      Alex: Treat examples as spoken recipes, not decorations. You may hear something like PR Review: 14 - Improve screen reader navigation guide; Summary; This PR adds 3 new sections to the screen reader navigation guide and updates 2 existing sections with NVDA-specific keyboard shortcuts.; Files Changed: 1; Lines Added: 127; Lines Removed: 18. Read the command, understand what it changes, then run it only when the repository state matches the lesson.

      +

      Alex: This is the part worth saying out loud. Here is the plain-English version of Skip navigation. For sites with repeated navigation on every page, add a skip link as the first element in. It is like learning a transit route. The names of the stops matter because they tell you whether you are still going the right direction.

      +

      Jamie: Let's pause on Focus management for single-page navigation. What should a learner take away from it?

      +

      Alex: This is where Focus management for single-page navigation becomes real: if the site uses JavaScript to load content without full page reloads, manage focus explicitly when content changes. That matters in practice: Move focus to the new or a wrapper with tabindex="-1" after navigation.

      +

      Alex: Keep the thread going. Keep the learner anchored in Image alt text. All images in published pages should have appropriate alt attributes. This is the part to say slowly: Decorative images should use alt="" (empty, not missing) to be skipped by screen readers.

      -

      Jamie: Let's pause on Agent 4: @analytics - Team Analytics. What should a learner take away from it?

      -

      Alex: Keep the learner anchored in Agent 4: @analytics - Team Analytics. File.github/agents/analytics.agent.md. This is the part to say slowly: Before you run this agent: You should have explored the Insights tab of at least one repository - looked at the contribution graph, understood what commit frequency means, and thought about what "high-churn files" implies for a project's stability.

      -

      Alex: Keep the teaching thread moving. The reason What it does matters is that surfaces team contribution patterns, velocity metrics, and bottleneck detection. The interface gets friendlier when it stops being a wall of controls and starts being a set of named places.

      -

      Alex: The practical takeaway is this. Contribution velocity over time. Review turnaround time by reviewer. Code hotspot detection (files with the most churn). Workload distribution across contributors.

      -

      Jamie: What stays the same when the tool changes?

      -

      Alex: Start with Example commands: Accessibility use case: After Day 2's contribution wave, run @analytics team velocity in accessibility-agents today to see the hackathon's collective output. The next useful detail is this: A moment of real-time team celebration.

      +

      Jamie: Let's pause on Color contrast. What should a learner take away from it?

      +

      Alex: The reason Color contrast matters is that run the published pages through an automated checker (axe, WAVE) after changes to the stylesheet to verify contrast ratios remain compliant.

      +

      Alex: This is where the talk moves from concept to action. Start with Testing the published site: After deployment, test the live URL rather than only local files. The next useful detail is this: mixed content, broken relative links, missing files) only appear when served from a web server. Think of it like entering a new building: first you find the lobby, then the room, then the door you actually need.

      +

      Jamie: Let's pause on Recommended post-deployment checks. What should a learner take away from it?

      +

      Alex: Start with Recommended post-deployment checks. There is something to understand, something to try, and something that proves the try worked.

      +

      Alex: First, navigate all pages keyboard-only. Then, run axe DevTools on the index page and at least one content page. After that, verify no broken links with a link checker (e.g. W3C Link Checker). Finally, test with a screen reader announcement of the page title. Treat it like a recipe: do not add the next ingredient until the previous one is actually in the bowl.

      -

      Alex: Keep the teaching thread moving. Here is the plain-English version of Agent 5: @insiders-a11y-tracker - Accessibility Change Monitoring. File.github/agents/insiders-a11y-tracker.agent.md. Put another way, before you run this agent: You should have filed at least one accessibility bug report using the workshop's issue template, applied a WCAG label to an issue, and manually reviewed a Markdown file for heading hierarchy - knowing what H1 means, what H2 means,.

      -

      Jamie: Before we leave What it does, what is the practical point?

      -

      Alex: This is where What it does becomes real: monitors accessibility-sensitive changes across configured repositories.

      -

      Alex: The practical takeaway is this. WCAG/ARIA cross-referenced change tracking. Flags changes to keyboard navigation, ARIA attributes, focus management, color usage. Monitors for heading hierarchy violations in Markdown. Tracks link text quality (flags bare URLs, non-descriptive labels).

      -

      Alex: Keep the teaching thread moving. Keep the learner anchored in Example commands. Day 2 workflow: Run this before submitting any PR. This is the part to say slowly: If the agent flags an issue, fix it before requesting review - not after. A good GitHub workflow is like a well-run meeting: everyone knows the topic, the next action, and who has the floor.

      +

      Alex: Hold that next to this. This is where 8. GitHub Actions and Continuous Deployment becomes real: using the Actions workflow described in Section 4 means every push to master automatically rebuilds and redeploys the site.

      +

      Jamie: Let's pause on Adding automated accessibility checks to the workflow. What should a learner take away from it?

      +

      Alex: Keep the learner anchored in Adding automated accessibility checks to the workflow. Extend the workflow to fail the build if accessibility violations are found. This is the part to say slowly: This uses the axe-core CLI to scan the built index page.

      +

      Alex: Keep the teaching thread moving. Start with Site not updating after a push. There is something to understand, something to try, and something that proves the try worked.

      +

      Alex: That shows up in the workshop in a few specific ways. Check the Actions tab for a failed deploy workflow. Check Settings → Pages - the most recent deployment timestamp should match your push. Hard-refresh the browser (Ctrl+F5 / Cmd+Shift+R) to bypass the cache. DNS TTL caching can delay custom domain updates up to the TTL value (often 1 hour).

      -

      Jamie: Let's pause on Agent 6: @template-builder - Interactive Issue Template Wizard. What should a learner take away from it?

      -

      Alex: The reason Agent 6: @template-builder - Interactive Issue Template Wizard matters is that file.github/agents/template-builder.agent.md. That gives the learner a simple foothold: before you run this agent: You should have read Issue Templates thoroughly - understanding YAML field types, creating a template manually (Exercise B), and designing your own template (Exercise D).

      -

      Alex: Keep the teaching thread moving. Start with What it does: An interactive wizard that guides you through building GitHub issue templates step-by-step using VS Code's Ask Questions feature. The next useful detail is this: Instead of writing YAML syntax, answer simple questions and the agent generates production-ready templates.

      -

      Jamie: What is the common workflow underneath the different interfaces?

      -

      Alex: Here is the plain-English version of Example commands. Manual YAML template creation takes 15-20 minutes and is error-prone. Put another way, the Template Builder generates correct, tested templates in 2-3 minutes via guided questions.

      +

      Jamie: Let's pause on 404 on all pages except index. What should a learner take away from it?

      +

      Alex: Start with 404 on all pages except index: This usually indicates a base URL mismatch. The next useful detail is this: If your site is at https://user.github.io/my-repo/, all relative asset and link paths must account for the /my-repo/ path prefix.

      +

      Alex: Keep the teaching thread moving. Start with HTTPS certificate not provisioning. There is something to understand, something to try, and something that proves the try worked.

      +

      Alex: Here is what that changes in practice. Verify DNS records are correctly set. Ensure the domain is not proxied through a CDN (e.g. Cloudflare orange-cloud) - GitHub Pages needs to see the DNS record directly to provision the cert. Allow up to 24 hours after correct DNS propagation.

      +

      Jamie: Let's pause on Screen reader announces wrong page title. What should a learner take away from it?

      +

      Alex: This is where Screen reader announces wrong page title becomes real: the published element is set during the HTML build step. That matters in practice: Update the template in scripts/build-html.js to ensure each page has a unique, descriptive title.

      -

      Alex: Keep the teaching thread moving. This is where 5. Slash Commands and Prompts becomes real: the repository includes 54+ slash commands defined as.prompt.md files in.github/prompts/. That matters in practice: Type / in Copilot Chat to see the full command menu. The workshop is closer to rehearsal than lecture. You hear the move, try the move, and then check what changed.

      -

      Jamie: Where does the workshop stop being a tour and start becoming contribution?

      -

      Alex: Keep the learner anchored in Workshop Slash Command Quick Reference. The commands listed below are the ones most relevant to this workshop. This is the part to say slowly: The full repository contains 54+ commands covering accessibility auditing, document scanning, framework-specific checks, and more.

      -

      Alex: Keep the teaching thread moving. The reason Reading Slash Command Definitions matters is that each /command corresponds to a.prompt.md file in.github/prompts/. That gives the learner a simple foothold: open any of them in VS Code to read what instructions it gives Copilot.

      +

      Jamie: What should people carry with them after this?

      +

      Alex: Carry the map. Know what page or tool you are in, know which action you are taking, and know what confirmation should follow. If the confirmation is missing, pause. That pause is not wasted time; it is professional judgment.

      +

      Jamie: That is a better way to say it than just follow the steps.

      +

      Alex: Right. Steps matter, but understanding wins. That is episode 33. Next in the series is episode 34, where we keep building the same contributor muscles.

      +
      +
      -

      Jamie: Let's pause on Example: /a11y-update. What should a learner take away from it?

      -

      Alex: Start with Example: /a11y-update: File.github/prompts/a11y-update.prompt.md. The next useful detail is this: This is how you learn to write your own.

      -

      Alex: Keep the teaching thread moving. Start with Learning Cards: Slash Commands and Prompts. There is something to understand, something to try, and something that proves the try worked.

      -

      Alex: The practical takeaway is this. Type / in Copilot Chat to see all available slash commands -- your screen reader announces each command name as you arrow through the list. Slash commands are defined in.github/prompts/ as.prompt.md files -- open them in the Explorer to read what each command does before using it. Create your own command by copying an existing.prompt.md file, renaming it, and editing the instructions -- no code required. The / command menu appears as a dropdown list in Copilot Chat -- it scales with VS Code's font and zoom settings. Each command has a short description visible in the dropdown; use Ctrl+= to zoom if the text is too small. Open the.prompt.md file in the editor to read the full command definition at your preferred zoom level.

      -

      Jamie: Let's pause on 6. Contributing to the Ecosystem. What should a learner take away from it?

      -

      Alex: This is where 6. Contributing to the Ecosystem becomes real: the 55 Accessibility Agents and 54+ slash commands are starting points. That matters in practice: The.agent.md format is open - you can create your own agents for any repeatable workflow, and contribute them back to the project.

      +

      63. Episode 34: GitHub Actions and Workflows

      +

      Workflow YAML structure, CI/CD, automation, and the Actions marketplace.

      +

      Based on: Appendix Q: GitHub Actions and Workflows

      + + +

      Download Episode 34 (MP3)

      +
      +Read Transcript - Episode 34: GitHub Actions and Workflows + +

      Transcript

      +

      Alex: This is Git Going with GitHub, episode 34: GitHub Actions and Workflows. I am Alex. By the end of this episode, GitHub Actions and Workflows should feel less like a wall of GitHub words and more like a set of moves you can trust.

      +

      Jamie: And I am Jamie. I am here for the practical questions: what should I listen for, what can go wrong, and what is the next calm move?

      -

      Alex: Keep the teaching thread moving. Keep the learner anchored in Two Types of Custom Agents. Informational agents - conversational; search, analyze, and present results. This is the part to say slowly: Task-oriented agents - active; edit files, run commands, submit PRs.

      -

      Alex: The practical takeaway is this. Perform GitHub searches with predefined scopes and filters. Present results in specific structured formats. Query GitHub API tools to answer questions. Execute external tools (linters, test suites, axe-core).

      -

      Jamie: Let's pause on Agent File Structure. What should a learner take away from it?

      -

      Alex: The reason Agent File Structure matters is that see also: Appendix L: Agents Reference has the complete agent.md format specification and examples. That gives the learner a simple foothold: every.agent.md file has two parts: YAML frontmatter (metadata) and a system prompt (markdown body).

      -

      Alex: Keep the teaching thread moving. Start with Frontmatter fields: Restricting tool access is a security best practice - only grant what the agent actually needs. Think of it like entering a new building: first you find the lobby, then the room, then the door you actually need.

      +

      Alex: Today we are working on this: Workflow YAML structure, CI/CD, automation, and the Actions marketplace. I want the learner to leave with a mental map, not just a remembered path through buttons.

      +

      Jamie: So the goal is understanding first, then action, then confirmation.

      +

      Alex: Right. We are building a rhythm: orient yourself, take one intentional action, then verify what changed before moving on.

      -

      Jamie: Let's pause on Example: Informational Agent - @insiders-a11y-tracker. What should a learner take away from it?

      -

      Alex: Here is the plain-English version of Example: Informational Agent - @insiders-a11y-tracker. This agent monitors VS Code Insiders releases for accessibility improvements. Put another way, it searches the microsoft/vscode repository using predefined GitHub query syntax, so you never have to remember the exact filter parameters.

      -

      Jamie: Let's pause on Use it. What should a learner take away from it?

      -

      Alex: This is where Use it becomes real: prerequisite: GitHub MCP server installed (github.com/github/github-mcp-server).

      -

      Alex: First, select @insiders-a11y-tracker from the agent picker. Then, ask: what shipped this month? or any keyboard navigation improvements in January? After that, the agent searches with repo:microsoft/vscode is:closed milestone:"[Month] [Year]" label:accessibility label:insiders-released and returns formatted results. It is a checklist, but a meaningful one: every item creates evidence that the next step is safe.

      -

      Jamie: Let's pause on Example: Task-Oriented Agent - The Markdown Accessibility Assistant. What should a learner take away from it?

      -

      Alex: Keep the learner anchored in Example: Task-Oriented Agent - The Markdown Accessibility Assistant. The GitHub Accessibility team published a complete walkthrough for building a Markdown Accessibility Assistant - a task-oriented agent that reviews Markdown files for accessibility issues and makes direct fixes. This is the part to say slowly: This agent is the automated version of the accessibility review skills you built during Day 1.

      -

      Alex: The practical takeaway is this. Runs markdownlint-cli2 to catch structural problems (heading skips, bare URLs, missing blank lines). Reviews link text for descriptiveness. Flags missing or inadequate alt text and waits for your approval before changing it (alt text requires human judgment). Fixes heading hierarchy, list structure, and bare URL formatting directly.

      +

      Jamie: Okay, set the room for us. What are we walking into?

      +

      Alex: Start with Understanding Automation in Open Source Repositories: Why this matters for you: Every time you open a pull request on a real open source project, automated processes will run. The next useful detail is this: Understanding what they are, what they mean, and what to do when they fail is essential to being a confident contributor.

      +

      Alex: The next layer is this. Here is the plain-English version of 1. What Is GitHub Actions? GitHub Actions is GitHub's built-in automation system. Put another way, it lets repository maintainers define automated tasks that run in response to things that happen in the repository - like someone opening a pull request, pushing a commit, or filing an issue. It is like learning a transit route. The names of the stops matter because they tell you whether you are still going the right direction.

      +

      Jamie: What is the one idea that makes the next few steps less mysterious?

      +

      Alex: Start with Learning Cards: What Is GitHub Actions. There is something to understand, something to try, and something that proves the try worked.

      +

      Alex: That shows up in the workshop in a few specific ways. Workflow files live in.github/workflows/ -- use T (Go to file) on any repo page to search for.yml files in that directory. The Actions tab is in the repository navigation landmark -- press D (NVDA/JAWS) to jump between landmarks and find it. You do not need to write YAML to contribute -- your job is to read the status check results on your PR and fix any issues they flag. The Actions tab icon (a play-button triangle) sits in the repo's top navigation bar -- zoom in if the icon-only display is hard to read; the word "Actions" appears next to it. Workflow YAML files use indentation-sensitive syntax -- increase your editor font size and enable visible whitespace to distinguish nesting levels. Status check results on your PR use small colored icons (green checkmark, red X, yellow spinner) -- zoom to 150%+ to read the text labels beside them.

      -

      Alex: Keep the teaching thread moving. The reason Key Pattern: Tiered Decision-Making matters is that this tiered approach - automate what can be objectively evaluated, flag what needs human judgment - is the right model for any accessibility agent. That gives the learner a simple foothold: it maximizes the agent's value while keeping humans in control of decisions that require context. The interface gets friendlier when it stops being a wall of controls and starts being a set of named places.

      -

      Jamie: Let's pause on Required Prerequisites for the Markdown Accessibility Assistant. What should a learner take away from it?

      -

      Alex: Start with Required Prerequisites for the Markdown Accessibility Assistant. There is something to understand, something to try, and something that proves the try worked.

      -

      Alex: The practical takeaway is this. GitHub MCP server installed and configured (github.com/github/github-mcp-server). Node.js installed (for npx markdownlint-cli2).

      -

      Jamie: Let's pause on From VS Code. What should a learner take away from it?

      -

      Alex: Start with From VS Code. There is something to understand, something to try, and something that proves the try worked.

      -

      Alex: First, open Copilot Chat (Ctrl+Shift+I / Cmd+Shift+I on macOS). Then, in the Chat input toolbar, select the Set Agent button. After that, select your custom agent from the agent picker. Finally, type your request - the agent executes in your local workspace. Treat it like a recipe: do not add the next ingredient until the previous one is actually in the bowl.

      +

      Alex: Now bring the learner back to the room. Keep the learner anchored in 3. Where Workflows Live in a Repository. Workflow files live in a specific, mandatory location.

      +

      Jamie: What would you say to someone who is already bracing for this to be too much?

      +

      Alex: The reason Description matters is that workflow files live at your-repository/.github/workflows/. That gives the learner a simple foothold: example files include: ci.yml (runs tests on every push or PR), lint.yml (checks code style), a11y-scan.yml (accessibility scanning), and deploy.yml (deploys the site when code merges to main).

      +

      Alex: The parts worth keeping in working memory are these. On GitHub.com: The file browser shows it - use T (go to file) or navigate the file table with Ctrl+Alt+Arrow keys. In VS Code: It appears in the Explorer panel - enable "Show Hidden Files" if needed.

      +

      Alex: The useful habit is simple: orient first, act second, verify third. That pause before acting is part of the work.

      +

      Jamie: How do you keep commands from becoming magic words?

      +

      Alex: Start with 4. The Anatomy of a Workflow File: Here is a simple, real workflow file. The next useful detail is this: You do not need to write this, but you should be able to read it. Think of it like entering a new building: first you find the lobby, then the room, then the door you actually need.

      +

      Alex: Treat examples as spoken recipes, not decorations. You may hear something like.github/workflows/ci.yml; name: CI The display name shown in the Actions tab; on: What triggers this workflow; push:; branches: [main] Run when code is pushed to main; pull request: Run when a PR is opened or updated; branches: [main]; jobs:; test: The job. Read the command, understand what it changes, then run it only when the repository state matches the lesson.

      -

      Jamie: Let's pause on From GitHub.com (Task mode). What should a learner take away from it?

      -

      Alex: Start with From GitHub.com (Task mode). There is something to understand, something to try, and something that proves the try worked.

      -

      Alex: First, open Copilot Chat on GitHub.com. Then, select Task from the mode picker. After that, optionally select a custom agent from the agent picker. Finally, submit your request - the agent can create a PR automatically. It is a checklist, but a meaningful one: every item creates evidence that the next step is safe.

      -

      Jamie: Let's pause on From an issue (Issue Assignment). What should a learner take away from it?

      -

      Alex: Start with From an issue (Issue Assignment). There is something to understand, something to try, and something that proves the try worked.

      -

      Alex: First, open any issue → Assignees → assign Copilot. Then, in the dialog, optionally select a custom agent. After that, select Assign - Copilot creates a branch, makes changes, and opens a PR. It is like walking a hallway with named doors: read the sign, enter the right room, then confirm where you landed.

      -

      Jamie: What is the pre-flight check here?

      -

      Alex: The reason Environment Setup for GitHub (Cloud Agents) matters is that when agents run on GitHub (not locally), they may need additional tools. That gives the learner a simple foothold: create a workflow file at.github/workflows/copilot-setup-steps.yml with a single job named copilot-setup-steps.

      +

      Jamie: If I am listening before the workshop starts, what should settle in my mind first?

      +

      Alex: Here is the plain-English version of 5. What Triggers a Workflow. The most common triggers you will encounter as a contributor. Put another way, the most important one for you: pull request - this is what triggers checks on your PR.

      +

      Alex: This is where the talk moves from concept to action. This is where 6. Understanding Status Checks on Pull Requests becomes real: when you open a pull request on a repo that uses GitHub Actions, you will see a section near the bottom of the Conversation tab called checks or status checks.

      +

      Alex: A solid pull request habit is to separate three questions: what changed, why it changed, and what still needs review. That keeps the conversation useful instead of noisy.

      +

      Jamie: Turn that into a path someone can follow.

      +

      Alex: Start with NVDA / JAWS (browse mode). There is something to understand, something to try, and something that proves the try worked.

      +

      Alex: First, open the pull request Conversation tab. Then, navigate to the section heading for "checks" using H or 2. After that, each check result is announced as a link or button with its name and status. Finally, press Enter on a failed check to expand its details. It is like walking a hallway with named doors: read the sign, enter the right room, then confirm where you landed.

      -

      Jamie: Let's pause on To Create Your Own Agent. What should a learner take away from it?

      -

      Alex: Start with To Create Your Own Agent. There is something to understand, something to try, and something that proves the try worked.

      -

      Alex: First, create.github/agents/your-agent-name.agent.md. Then, write YAML frontmatter (name, description, tools). After that, write the system prompt - identity, capabilities, domain knowledge, behavioral rules, output format. Finally, save and reload VS Code (Ctrl+Shift+P → "Reload Window"). Think of it as a rail line: each stop confirms you are still on the right route before the next one.

      -

      Jamie: Before we leave To Create Your Own Agent, what is the practical point?

      -

      Alex: First, type @your-agent-name in Copilot Chat. Treat it like a recipe: do not add the next ingredient until the previous one is actually in the bowl.

      -

      Jamie: How do these exercises create confidence instead of pressure?

      -

      Alex: Here is the plain-English version of Exercise: Extend the Template Builder Agent. You've built templates manually (Chapters 15-16) and seen them in action. Put another way, now see how to harness AI to generate templates interactively, and learn to customize agents for your own projects.

      -

      Alex: The practical takeaway is this. Complete Chapters 15-16 (especially Exercise D - designing your own template). VS Code is installed and GitHub Copilot is active. You have forked accessibility-agents to your GitHub account. You have cloned your fork locally: git clone https://github.com/[your-username]/accessibility-agents.git.

      -

      Jamie: Let's pause on Exercise 1: Generate a Template with the Agent. What should a learner take away from it?

      -

      Alex: This is where Exercise 1: Generate a Template with the Agent becomes real: your Mission: Use the @template-builder agent to generate an accessibility bug report template interactively. That matters in practice: You'll experience the agent as an end-user and see what production-ready agent output looks like. The workshop is closer to rehearsal than lecture. You hear the move, try the move, and then check what changed.

      -

      Alex: The practical takeaway is this. Left sidebar showing.github/, docs/, learning-room/, README.md, etc. The status bar at the bottom shows your current git branch (probably main). Alternative: Use menu: View → Copilot Chat. Copilot is now ready to receive instructions.

      -

      Alex: First, open VS Code. Then, file → Open Folder → select your locally cloned accessibility-agents folder. After that, the folder tree appears on the left showing the repository structure. Finally, verify you're in the right place: The folder name should be accessibility-agents at the top of the sidebar. It is a checklist, but a meaningful one: every item creates evidence that the next step is safe.

      -

      Jamie: Before we leave Exercise 1: Generate a Template with the Agent, what is the practical point?

      -

      Alex: First, keyboard shortcut: Press Ctrl+Shift+I (Windows/Linux) or Cmd+Shift+I (macOS). Then, a chat panel opens on the right side of VS Code. After that, at the top, you see "Copilot Chat" and probably a text input at the bottom saying "Ask Copilot.". Finally, click in the chat input box (bottom of Copilot Chat panel). It is like walking a hallway with named doors: read the sign, enter the right room, then confirm where you landed.

      -

      Alex: Treat examples as spoken recipes, not decorations. You may hear something like Q: Template name?; A: Accessibility Bug Report; Q: What's it for?; A: Report screen reader and keyboard navigation issues; Q: First field name?; A: Screen Reader; Q: Field type?; A: dropdown; Q: Dropdown options? (comma-separated); A: NVDA, JAWS, VoiceOver,. Read the command, understand what it changes, then run it only when the repository state matches the lesson.

      +

      Jamie: What is the ordered workflow?

      +

      Alex: Start with VoiceOver (macOS, Safari). There is something to understand, something to try, and something that proves the try worked.

      +

      Alex: First, use VO+U to open the Rotor. Then, select "Headings" and navigate to the checks section. After that, use VO+Arrow to read through check results. Finally, activate a check link with VO+Space. The rhythm is simple: orient, act, verify, then continue.

      +

      Jamie: Give me the version that sounds like an instructor, not a manual.

      +

      Alex: Start with Required vs. non-required checks. There is something to understand, something to try, and something that proves the try worked.

      +

      Alex: A few details make that real. Required checks must pass before a PR can be merged. A maintainer configures which checks are required in Branch Protection Rules. Non-required checks are informational - a failure shown in grey/yellow usually won't block a merge. If you're not sure whether a check is required, look for the phrase "Required" next to the check name.

      +

      Alex: Hold that next to this. Start with Learning Cards: Understanding Status Checks. There is something to understand, something to try, and something that proves the try worked.

      +

      Alex: The practical anchors are these. Status checks live near the bottom of the PR Conversation tab -- press H or 2 to jump to the checks section heading, then arrow down through each result. Each check is announced with its name and status ("CI / test -- passed" or "lint -- failed") -- press Enter on a failing check to open its details. The word "Required" appears after required checks -- listen for it to distinguish must-pass checks from informational ones. Status icons use green (passed), red (failed), yellow (running), and grey (skipped) -- each icon also has a text label, so color is not the only indicator. At high zoom levels, the checks section may appear below the fold -- scroll past the PR description and comments to find it above the merge button. Click "Details" next to any check to open the full log -- the log page uses monospace text, so increase font size for readability.

      -

      Jamie: Let's pause on Exercise 2: Extend the Agent for Your Project. What should a learner take away from it?

      -

      Alex: Keep the learner anchored in Exercise 2: Extend the Agent for Your Project. Your Mission: Customize the Template Builder agent to recognize and guide a Security Vulnerability Report template. This is the part to say slowly: This teaches you how to tailor agents for project-specific needs.

      -

      Alex: The practical takeaway is this. The file starts with YAML frontmatter (name, description, topics). Below that, sections like " How to Use", " Pre-Built Workflow". Search for the text "Pre-Built Workflow: Guided Accessibility Template".

      -

      Alex: First, in VS Code, navigate to.github/agents/. Then, file: template-builder.agent.md. After that, double-click to open it in the editor. Finally, you see the agent's instructions in Markdown format. It is like walking a hallway with named doors: read the sign, enter the right room, then confirm where you landed.

      -

      Jamie: Before we leave Exercise 2: Extend the Agent for Your Project, what is the practical point?

      -

      Alex: First, use Ctrl+F to open Find. Then, search for: Pre-Built Workflow. After that, press Enter to jump to the first match. Finally, you should land on the "Pre-Built Workflow: Guided Accessibility Template" section. The rhythm is simple: orient, act, verify, then continue.

      -

      Jamie: Let's pause on What you're adding. What should a learner take away from it?

      -

      Alex: The reason What you're adding matters is that if the agent doesn't recognize your new workflow.

      -

      Alex: The practical takeaway is this. A clear label for the new workflow. Instructions on how to invoke it. Pre-defined fields that make sense for security reports. Specific options for severity and vulnerability type. The agent recognizes your new workflow. Next time you invoke @template-builder with "create security template", it will follow your new guidance.

      -

      Alex: First, save the file: Ctrl+S. Then, you should see no error messages. After that, the agent file now includes your new Pre-Built Workflow. Finally, open Copilot Chat again: Ctrl+Shift+I. The rhythm is simple: orient, act, verify, then continue.

      -

      Jamie: Before we leave What you're adding, what is the practical point?

      -

      Alex: First, press Enter. Then, the agent should now ask vulnerability-specific questions. After that, commit your agent change. Finally, the extended agent is now in your fork. Think of it as a rail line: each stop confirms you are still on the right route before the next one.

      -

      Alex: Treat examples as spoken recipes, not decorations. You may hear something like git add.github/agents/template-builder.agent.md; git commit -m "feat: add security vulnerability template workflow to template-builder agent"; git push origin main. Read the command, understand what it changes, then run it only when the repository state matches the lesson.

      -

      Jamie: Let's pause on Exercise 3: Iterative Refinement with Agents. What should a learner take away from it?

      -

      Alex: Start with Exercise 3: Iterative Refinement with Agents: Your Mission: Generate a template, then ask the agent to modify it incrementally. The next useful detail is this: This teaches you the iterative pattern that scales to all agent-assisted workflows.

      -

      Alex: The practical takeaway is this. Running a complete template generation (same as Exercise 1). The agent modifies the YAML it generated. The new checkbox appears in the YAML with proper formatting and indentation. It doesn't regenerate from scratch - just adds your change.

      -

      Alex: First, in Copilot Chat, type: @template-builder create a feature request template. Then, answer the agent's questions to build a feature request form. After that, let the agent generate the YAML. Finally, copy it to a file.github/ISSUE TEMPLATE/feature-request.yml. Think of it as a rail line: each stop confirms you are still on the right route before the next one.

      -

      Jamie: Before we leave Exercise 3: Iterative Refinement with Agents, what is the practical point?

      -

      Alex: First, once the template is generated, while still in the same chat conversation, ask. Then, the agent regenerates the YAML with your new checkbox added in the right place (usually as required field pre-validation). After that, follow up. Finally, the agent modifies the textarea field's attributes to enable code highlighting. Treat it like a recipe: do not add the next ingredient until the previous one is actually in the bowl.

      +

      Jamie: Where do you want a learner to place their attention here?

      +

      Alex: This is where 7. Reading the Actions Tab with a Screen Reader becomes real: the Actions tab of a repository shows the history of all workflow runs. That matters in practice: You can use it to see what ran, what failed, and why.

      +

      Alex: A solid navigation habit is to prove where you are before activating controls. Headings, landmarks, and the address bar are not trivia; they are your map.

      +

      Jamie: Give me the sequence, because order matters here.

      +

      Alex: Start with Getting to the Actions tab. There is something to understand, something to try, and something that proves the try worked.

      +

      Alex: First, open the repository. Then, navigate to the "Repository navigation" landmark (D on NVDA/JAWS). After that, find the "Actions" tab link and activate it (Enter). It is like walking a hallway with named doors: read the sign, enter the right room, then confirm where you landed.

      +

      Jamie: What is the safe way to learn from that example?

      +

      Alex: Start with Navigating workflow runs (NVDA/JAWS browse mode). There is something to understand, something to try, and something that proves the try worked.

      +

      Alex: Treat examples as spoken recipes, not decorations. You may hear something like Key Action; H Jump between section headings; 3 Jump between workflow run headings (they are h3); Tab Move between interactive elements (links, buttons); Enter Open a workflow run to see details. Read the command, understand what it changes, then run it only when the repository state matches the lesson.

      -

      Jamie: Let's pause on What Comes Next. What should a learner take away from it?

      -

      Alex: Here is the plain-English version of What Comes Next. Your next step: explore the broader ecosystem. Put another way, that is Accessibility Agents' promise: not to replace your thinking, but to amplify your skills across all 55 agents - and to grow through the contributions of everyone who uses it. It is like learning a transit route. The names of the stops matter because they tell you whether you are still going the right direction.

      -

      Alex: The practical takeaway is this. Browse the full agent list - which agents solve problems you face regularly? Try an Accessibility team agent: @contrast-master check this page or @alt-text-headings review this file. Try a Developer Tools agent: @python-specialist review this module for accessibility or @desktop-a11y-specialist audit this dialog. Think about what is missing: what agent would you build if you could?

      -

      Alex: First, generated a template using an agent (Exercise 1). Then, customized an agent for your domain (Exercise 2). After that, refined iteratively with agent help (Exercise 3). Treat it like a recipe: do not add the next ingredient until the previous one is actually in the bowl.

      -

      Jamie: Let's pause on Learning Cards: Contributing to the Ecosystem. What should a learner take away from it?

      -

      Alex: Start with Learning Cards: Contributing to the Ecosystem. There is something to understand, something to try, and something that proves the try worked.

      -

      Alex: The practical takeaway is this. Agent.agent.md files use YAML frontmatter at the top (between --- delimiters) followed by Markdown body; in VS Code, use Ctrl+G to jump to line 1 and arrow through the frontmatter fields (name, description, tools) before reading the body instructions. When writing your own.agent.md, use VS Code's Outline view (Ctrl+Shift+O) to verify that your Markdown headings (Purpose, Capabilities, Responsibilities) are correctly nested -- malformed headings will not appear in the outline. Before submitting a PR with a new agent file, run the file through a YAML linter (install the YAML extension, or use yamllint from the terminal) -- frontmatter syntax errors silently break agent registration. YAML frontmatter fields are densely packed with colons and quotes; increase your editor font size or use a monospaced font with wide character spacing so name:, description:, and tools: are clearly distinct. The.agent.md files in the agents/ directory follow a consistent structure -- use the file explorer's icon theme or file nesting feature to visually group agent files separately from regular documentation. When reviewing existing agents for contribution ideas, use VS Code's split editor to place the agent file and the README side by side so you can cross-reference the agent's instructions with its documented capabilities.

      -

      Alex: Keep the teaching thread moving. Keep the learner anchored in 7. The Bigger Picture: Teams, Orchestration, and Beyond VS Code. The 55 agents are not 55 independent tools. This is the part to say slowly: They are organized into three teams that work together, and several orchestrator agents exist specifically to coordinate multi-agent workflows.

      +

      Jamie: How would you walk the room through that step by step?

      +

      Alex: Start with Reading a run's details: When you open a workflow run, you see. The next useful detail is this: Use your screen reader's search (NVDA+Ctrl+F, JAWS: Insert+F, VO+F) to search for "error" or "failed" to jump directly to the problem.

      +

      Alex: On the ground, that means a few things. Job names listed on the left (or in a sidebar). Steps listed within each job. Green checkmarks (passed) or red X marks (failed) next to each step.

      +

      Alex: First, navigate to the failed step. Then, activate it to expand the log output. After that, the log is a large text area - switch to focus mode to read it. Finally, look for lines containing Error:, FAILED, exit code, or AssertionError. Think of it as a rail line: each stop confirms you are still on the right route before the next one.

      +

      Jamie: Let's pause on 8. Common Workflows You Will Encounter. What should a learner take away from it?

      +

      Alex: Here is the plain-English version of 8. Common Workflows You Will Encounter. As you contribute to open source repositories, you will see these types of workflows regularly.

      +

      Alex: Keep the thread going. This is where Continuous Integration (CI) becomes real: what it does: Runs the project's test suite automatically every time code changes. That matters in practice: What you see: A check called "CI", "Tests", "Build", or similar. The workshop is closer to rehearsal than lecture. You hear the move, try the move, and then check what changed.

      -

      Jamie: Let's pause on How the Three Teams Connect. What should a learner take away from it?

      -

      Alex: The reason How the Three Teams Connect matters is that in practice, a single task often spans multiple teams. That gives the learner a simple foothold: no single agent covers the entire workflow.

      -

      Alex: The practical takeaway is this. You ask @daily-briefing (GitHub Workflow) for your morning report. It flags a PR that changes ARIA attributes. You ask @pr-review (GitHub Workflow) to generate a structured review of that PR. The review notes potential accessibility impact. You invoke @aria-specialist (Accessibility) to deep-check the ARIA changes. It identifies a missing aria-expanded state on a disclosure widget. You fix the issue using patterns from @desktop-a11y-specialist (Developer Tools) if it is a desktop application, or directly in the HTML if it is a web project.

      -

      Alex: Keep the teaching thread moving. Start with Learning Cards: Teams and Orchestration. There is something to understand, something to try, and something that proves the try worked.

      -

      Alex: The practical takeaway is this. Orchestrator agents like @accessibility-lead coordinate multi-agent workflows -- invoke one and it delegates to specialists, announcing which agent it is calling. Multi-agent output appears in sequence in Copilot Chat -- press Alt+F2 after each response to read it in Accessible View before the next agent responds. The three teams are GitHub Workflow (what happened), Accessibility (is it correct), and Developer Tools (fix it) -- choose your entry point based on your current task. Orchestrator responses can be long -- use Accessible View (Alt+F2) or widen the Chat panel to read comfortably at high zoom. The workflow diagrams in this section are described in text -- no visual-only content is required to understand the agent coordination pattern. Each team's agents are listed in the tables in Section 3 -- refer back there to find the right specialist agent.

      -

      Jamie: Let's pause on Orchestrator Agents. What should a learner take away from it?

      -

      Alex: Here is the plain-English version of Orchestrator Agents. Four agents are specifically designed to coordinate others. Put another way, you do not need to use orchestrators to get value from individual agents.

      +

      Jamie: Let's pause on Linting / Code Style. What should a learner take away from it?

      +

      Alex: Keep the learner anchored in Linting / Code Style. What it does: Checks that code follows the project's formatting and style rules - things like indentation, line length, or consistent import ordering. This is the part to say slowly: What you see: A check called "Lint", "ESLint", "Prettier", "Flake8", or similar.

      +

      Alex: Another way to ground it. The reason Spelling / Documentation Checks matters is that what it does: Checks documentation files for spelling errors, broken links, or formatting issues. That gives the learner a simple foothold: what you see: A check called "Spell Check", "markdownlint", "Link Check", or similar.

      +

      Jamie: Let's pause on Accessibility Scanning. What should a learner take away from it?

      +

      Alex: Start with Accessibility Scanning: What it does: Runs automated accessibility checks against HTML output or component libraries to catch WCAG violations. The next useful detail is this: What you see: A check called "a11y", "Accessibility", "axe", "pa11y", or similar.

      -

      Alex: Keep the teaching thread moving. This is where High-Impact Agents to Try First becomes real: rather than exploring all 55 agents at once, start with the ones that deliver immediate value based on Day 1 skills you already have.

      -

      Jamie: Let's pause on Slash Commands That Save the Most Time. What should a learner take away from it?

      -

      Alex: Keep the learner anchored in Slash Commands That Save the Most Time. These commands work without invoking a full agent - type them directly in Copilot Chat. This is the part to say slowly: The full list of 54+ commands is in Appendix L, and Episode 39 walks through all of them with examples.

      -

      Alex: The practical takeaway is this. /my-issues and /my-prs - Instant dashboard of your open work across all repos. /review-pr 14 - Full AI-generated review with inline suggestions, replacing manual line-by-line reading. /triage 22 - Label, priority, and assignment suggestions for any new issue. /daily-briefing - Morning snapshot of repository activity, PRs needing review, and stale issues.

      -

      Alex: Keep the teaching thread moving. The reason Running Agents Beyond VS Code matters is that accessibility Agents' agents run on your machine, in your editor, when you ask for them. That gives the learner a simple foothold: the same Markdown-authored pattern extends further. The interface gets friendlier when it stops being a wall of controls and starts being a set of named places.

      +

      Alex: This is the part worth saying out loud. Here is the plain-English version of Security Scanning. What it does: Scans for known vulnerabilities in dependencies or exposed secrets. Put another way, what you see: A check called "CodeQL", "Dependabot", "Snyk", or similar. It is like learning a transit route. The names of the stops matter because they tell you whether you are still going the right direction.

      +

      Jamie: Let's pause on Deployment / Preview Builds. What should a learner take away from it?

      +

      Alex: This is where Deployment / Preview Builds becomes real: what it does: Builds and deploys a preview version of a website or app from your PR branch. That matters in practice: What you see: A bot comment on your PR with a preview URL, and a check called "Deploy", "Netlify", "Vercel", "GitHub Pages", or similar.

      +

      Alex: That connects to another useful point. Keep the learner anchored in Step 1: Don't panic. A failing check is information, not a judgment. This is the part to say slowly: It is the system telling you something specific needs attention.

      -

      Jamie: Let's pause on Scope 1: Your Editor (Accessibility Agents). What should a learner take away from it?

      -

      Alex: Start with Scope 1: Your Editor (Accessibility Agents). There is something to understand, something to try, and something that proves the try worked.

      -

      Alex: The practical takeaway is this. File lives in.github/agents/[name].agent.md in your workspace. Triggered by: You, when you type @[agent-name] in Copilot Chat. Runs on: Your machine, using your Copilot subscription. Reaches: Every repository your GitHub account has access to. Scale: All 55 agents available when the workspace is open.

      -

      Alex: Keep the teaching thread moving. Here is the plain-English version of Scope 2: Your Repository (Travels with Forks). When you fork accessibility-agents, all 55 agents come with it. Put another way, you can edit them for your project's context.

      -

      Alex: The practical takeaway is this. File lives in.github/agents/[name].agent.md in the repo. Triggered by: Any contributor who has Copilot and opens the repo as a VS Code workspace. Runs on: Their machine, using their Copilot subscription. Reaches: Their GitHub account's repositories.

      -

      Jamie: Let's pause on Scope 3: The Cloud (GitHub Agentic Workflows). What should a learner take away from it?

      -

      Alex: This is where Scope 3: The Cloud (GitHub Agentic Workflows) becomes real: the workflow runs whether or not anyone is watching - when an issue is opened at 3am, the agentic response fires. That matters in practice: The link between Accessibility Agents and Agentic Workflows: Both use Markdown-authored instructions.

      -

      Alex: The practical takeaway is this. File lives in.github/workflows/[name].md (same folder as standard Actions YAML). Triggered by: Any GitHub event - issues: opened, pull request: created, schedule. Runs on: GitHub Actions infrastructure, serverlessly. Reaches: The repository where the workflow is defined.

      +

      Jamie: What does the learner do first, second, and then after that?

      +

      Alex: Start with Step 2: Navigate to the failed check. There is something to understand, something to try, and something that proves the try worked.

      +

      Alex: First, scroll down to the checks section (press D to reach the "Checks" region if using a screen reader). Then, find the failing check (red X). After that, press Enter on "Details" (or the check name itself) to open the workflow run. The rhythm is simple: orient, act, verify, then continue.

      +

      Jamie: Let's pause on Step 3: Find the failing step. What should a learner take away from it?

      +

      Alex: Start with Step 3: Find the failing step. There is something to understand, something to try, and something that proves the try worked.

      +

      Alex: First, look for the step with the red X marker. Then, press Enter or Space to expand the log output. Think of it as a rail line: each stop confirms you are still on the right route before the next one.

      +

      Jamie: Let's pause on Step 4: Read the error message. What should a learner take away from it?

      +

      Alex: Start with Step 4: Read the error message. There is something to understand, something to try, and something that proves the try worked.

      +

      Alex: Here is what that changes in practice. Error: - describes what went wrong. FAILED or FAIL - test failure summary. File name and line number - where exactly the problem is. exit code 1 (or non-zero) - the command failed.

      -

      Alex: Keep the teaching thread moving. Keep the learner anchored in Go Deeper. For full documentation on every agent, all 54+ slash commands, customization formats, and troubleshooting, see Appendix L: Accessibility Agents Reference. This is the part to say slowly: For the audio version, listen to Episode 39: Accessibility Agents - Complete Reference. A good GitHub workflow is like a well-run meeting: everyone knows the topic, the next action, and who has the floor.

      -

      Jamie: Let's pause on Example: Auto-triage accessibility issues. What should a learner take away from it?

      -

      Alex: The reason Example: Auto-triage accessibility issues matters is that file.github/workflows/auto-triage-a11y.md. That gives the learner a simple foothold: this runs automatically on every new issue.

      -

      Alex: Keep the teaching thread moving. Start with 8. GitHub Desktop, GitHub CLI, and Copilot CLI: These tools are not required for this workshop, but are worth knowing as options for different workflows.

      +

      Alex: That matters because of the next idea. Start with Step 5: Fix the issue locally (or in the web editor). There is something to understand, something to try, and something that proves the try worked.

      +

      Alex: The room should hear these as checkpoints. Test failure: Understand what the test expects and whether your change broke something intentional. Lint failure: Run the project's format/lint command, or manually fix the flagged lines. Spell check failure: Fix the typo noted in the log. Accessibility failure: Fix the specific a11y violation described (missing alt text, contrast issue, etc.).

      +

      Alex: A solid issue habit is to read the title, the body, and the timeline before acting. You are listening for the requested action, the missing evidence, and the person who needs a response.

      +

      Jamie: Let's pause on Step 6: Commit and push the fix. What should a learner take away from it?

      +

      Alex: Start with Step 6: Commit and push the fix. There is something to understand, something to try, and something that proves the try worked.

      +

      Alex: These are the details that keep the idea from floating away. The workflow will automatically re-run when you push new commits to the branch. No need to close and re-open the PR.

      +

      Alex: A solid Git habit is to know which branch you are on, what changed, and what confirmation you expect before you run the next command.

      +

      Alex: Before the learner moves on. The reason Step 7: If you're stuck matters is that it is completely acceptable to comment on your PR. That gives the learner a simple foothold: "The CI check is failing on [step name]. The interface gets friendlier when it stops being a wall of controls and starts being a set of named places.

      -

      Jamie: Let's pause on GitHub Desktop. What should a learner take away from it?

      -

      Alex: Here is the plain-English version of GitHub Desktop. A graphical Git application with an accessible interface. Put another way, when to use: If command-line Git feels overwhelming, GitHub Desktop provides a GUI alternative.

      -

      Alex: The practical takeaway is this. Download: desktop.github.com. Useful for: Visual diff review, simpler branch management. Screen reader support: Partial - keyboard navigation works for core flows.

      -

      Alex: Keep the teaching thread moving. This is where GitHub CLI (gh) becomes real: a command-line interface for GitHub operations. The workshop is closer to rehearsal than lecture. You hear the move, try the move, and then check what changed.

      -

      Jamie: What is the safe way to learn from that example?

      -

      Alex: Start with Authenticate. There is something to understand, something to try, and something that proves the try worked.

      -

      Alex: Treat examples as spoken recipes, not decorations. You may hear something like gh auth login. Read the command, understand what it changes, then run it only when the repository state matches the lesson.

      +

      Jamie: Let's pause on Learning Cards: What To Do When a Check Fails. What should a learner take away from it?

      +

      Alex: Start with Learning Cards: What To Do When a Check Fails. There is something to understand, something to try, and something that proves the try worked.

      +

      Alex: For a learner, the useful signals are these. From the failing check's Details link, the log page has a sidebar listing job steps -- the failed step has focus or is announced as "failed"; expand it to read the error. Use your screen reader's find command (NVDA+Ctrl+F, JAWS: Insert+F) to search the log for "Error:" or "FAILED" -- this skips hundreds of passing log lines. After pushing a fix, return to the PR page -- checks re-run automatically and the status updates from red X to yellow spinner to green checkmark. CI log pages can be very long with small monospace text -- use Ctrl+F in your browser to search for "Error" or "FAIL" rather than scrolling through everything. The failing step is marked with a red X icon in the left sidebar of the log page -- zoom in to identify it, then click to expand only that step. If you cannot read the log comfortably, copy the error text and paste it into your editor at a larger font size.

      +

      Alex: Here is the practical turn. Here is the plain-English version of Why some workflows need your approval. If you are contributing to a repository for the first time, GitHub may hold your workflow runs for approval. Put another way, "Workflows aren't being run on this pull request.

      +

      Jamie: Let's pause on What you should never do. What should a learner take away from it?

      +

      Alex: Start with What you should never do. There is something to understand, something to try, and something that proves the try worked.

      +

      Alex: That becomes easier when you listen for these cues. Never change workflow files to bypass checks (e.g., deleting tests to make them pass). Never add secrets or credentials to workflow files or code. Never approve a workflow run on someone else's PR unless you have reviewed the code.

      -

      Jamie: Let's pause on Common commands. What should a learner take away from it?

      -

      Alex: The reason Common commands matters is that screen reader advantage: gh output is plain text with no dynamic regions - more predictable than the browser for certain operations.

      -

      Alex: Treat examples as spoken recipes, not decorations. You may hear something like gh issue list List issues in current repo; gh issue view 42 Read issue 42; gh pr list List pull requests; gh pr view 14 Read PR 14; gh pr create Create a new PR interactively; gh pr merge 14 Merge PR 14; gh repo clone owner/repo Clone a repository; gh repo. Read the command, understand what it changes, then run it only when the repository state matches the lesson.

      -

      Jamie: Let's pause on GitHub Copilot CLI (gh copilot). What should a learner take away from it?

      -

      Alex: Start with GitHub Copilot CLI (gh copilot): An extension that adds Copilot to the terminal.

      -

      Jamie: Let's pause on Install. What should a learner take away from it?

      -

      Alex: Start with Install. There is something to understand, something to try, and something that proves the try worked.

      -

      Alex: Treat examples as spoken recipes, not decorations. You may hear something like gh extension install github/gh-copilot. Read the command, understand what it changes, then run it only when the repository state matches the lesson.

      +

      Alex: Keep the teaching thread moving. Keep the learner anchored in Dependabot. Dependabot is an automated bot built into GitHub that creates pull requests to update outdated or vulnerable dependencies. This is the part to say slowly: the learner will see PRs in a repository from a user called dependabot[bot]. A good GitHub workflow is like a well-run meeting: everyone knows the topic, the next action, and who has the floor.

      +

      Jamie: Let's pause on 11. Accessibility-Focused Workflows. What should a learner take away from it?

      +

      Alex: The reason 11. Accessibility-Focused Workflows matters is that this is relevant to our event specifically. That gives the learner a simple foothold: the open source accessibility community actively uses GitHub Actions to automatically catch accessibility regressions - meaning, to ensure that new code does not introduce new accessibility barriers.

      +

      Alex: Keep the teaching thread moving. Start with GitHub's Accessibility Scanner Action: GitHub itself has open-sourced an AI-powered Accessibility Scanner that can be added to a repository. The next useful detail is this: It uses AI to find, file, and help fix accessibility bugs using GitHub Copilot.

      -

      Jamie: Let's pause on Commands. What should a learner take away from it?

      -

      Alex: This is where Commands becomes real: use case: When you know what you want to do but are unsure of the exact git command syntax.

      -

      Alex: Treat examples as spoken recipes, not decorations. You may hear something like Ask Copilot to explain a command; gh copilot explain "git rebase -i HEAD 3"; Ask Copilot to suggest a command; gh copilot suggest "undo my last commit but keep the changes"; Ask Copilot to write a shell script; gh copilot suggest "create a script that finds. Read the command, understand what it changes, then run it only when the repository state matches the lesson.

      -

      Jamie: Let's pause on Example session. What should a learner take away from it?

      -

      Alex: Start with Example session. There is something to understand, something to try, and something that proves the try worked.

      -

      Alex: Treat examples as spoken recipes, not decorations. You may hear something like $ gh copilot suggest "show me all commits from last week"; Suggestion: git log --since="1 week ago" --oneline; Run this command? (Y/n). Read the command, understand what it changes, then run it only when the repository state matches the lesson.

      -

      Jamie: Let's pause on Learning Cards: GitHub Desktop, GitHub CLI, and Copilot CLI. What should a learner take away from it?

      -

      Alex: Start with Learning Cards: GitHub Desktop, GitHub CLI, and Copilot CLI. There is something to understand, something to try, and something that proves the try worked.

      -

      Alex: The practical takeaway is this. GitHub Desktop is a native application -- on Windows it uses UI Automation, not a browser DOM; your screen reader's object navigation (NVDA: Insert+Numpad) rather than browse mode is the correct approach for navigating its interface. GitHub CLI (gh) is entirely terminal-based; all output is plain text that your screen reader reads line by line -- pipe verbose output through head -20 or Select-Object -First 20 to avoid overwhelming your speech buffer. Copilot CLI (gh copilot suggest and gh copilot explain) presents interactive prompts in the terminal; listen for the "Run this command? (Y/n)" confirmation before pressing Enter to avoid executing unreviewed commands. GitHub Desktop inherits your Windows display scaling -- if text appears small, increase system-level scaling (Settings Display Scale) rather than looking for an in-app zoom option. Terminal output from gh and gh copilot uses your terminal's font and color settings; configure your terminal profile (Windows Terminal settings or iTerm2 preferences) with a high-contrast color scheme and large font for comfortable reading. Copilot CLI suggestions appear as plain text in the terminal, not in a styled panel -- they are easy to miss among other output; look for the indented suggestion block immediately after your prompt.

      +

      Jamie: There are a lot of tools in play. How do we keep that from feeling like a contest?

      +

      Alex: Here is the plain-English version of What these tools catch (and what they do not). Automated tools catch approximately 30-40% of accessibility issues - things like missing alt attributes, insufficient color contrast ratios, or unlabeled form fields. Put another way, the remaining issues require human testing, especially with actual assistive technology like your screen reader.

      +

      Alex: Keep the teaching thread moving. This is where Preparing the Environment for GitHub-Hosted Agents becomes real: when custom agents run on GitHub.com - triggered by an issue assignment or a Copilot Chat task - they need any external tools pre-installed before they start working. That matters in practice: GitHub recognizes a special setup workflow for this: a workflow file with a single job named copilot-setup-steps. The workshop is closer to rehearsal than lecture. You hear the move, try the move, and then check what changed.

      +

      Jamie: Let's pause on Activity: Explore a Workflow in This Repository. What should a learner take away from it?

      +

      Alex: Keep the learner anchored in Activity: Explore a Workflow in This Repository. Practice navigating the Actions tab and reading a workflow file using your screen reader.

      -

      Alex: Keep the teaching thread moving. Start with "Agent not found": Issue: Typing @agent-name shows "No agent found.". Think of it like entering a new building: first you find the lobby, then the room, then the door you actually need.

      -

      Jamie: Let's pause on Solutions. What should a learner take away from it?

      -

      Alex: Start with Solutions. There is something to understand, something to try, and something that proves the try worked.

      -

      Alex: First, verify.github/agents/[name].agent.md exists in your workspace. Then, reload VS Code window: Ctrl+Shift+P → "Reload Window". After that, check file naming: must end with.agent.md. Finally, verify YAML frontmatter is valid (no syntax errors). Treat it like a recipe: do not add the next ingredient until the previous one is actually in the bowl.

      -

      Alex: Keep the teaching thread moving. This is where Agent produces incorrect output becomes real: issue: Agent's response is wrong or misses context.

      +

      Jamie: Let's pause on Steps. What should a learner take away from it?

      +

      Alex: Start with Steps. There is something to understand, something to try, and something that proves the try worked.

      +

      Alex: The practical takeaway is this. What event triggers it. What OS it runs on. How many steps it has. What the last step does.

      +

      Alex: First, navigate to your Learning Room repository on GitHub. Then, go to the Actions tab (in the Repository navigation landmark). After that, use 3 (NVDA/JAWS) or the Headings rotor (VoiceOver) to navigate the list of workflow runs. Finally, open the most recent run. The rhythm is simple: orient, act, verify, then continue.

      +

      Jamie: Before we leave Steps, what is the practical point?

      +

      Alex: First, find any failed step and expand its log. Then, navigate to the.github/workflows/ folder via the Code tab. After that, open a workflow.yml file. Finally, read through the file and identify. Think of it as a rail line: each stop confirms you are still on the right route before the next one.

      +

      Jamie: Let's pause on Discussion questions. What should a learner take away from it?

      +

      Alex: Start with Discussion questions. There is something to understand, something to try, and something that proves the try worked.

      +

      Alex: The practical takeaway is this. What would happen if you opened a PR and the "Accessibility Scan" check failed? Where would you look to find out what accessibility violation was detected? If you disagreed with a failing lint check, what would be the appropriate way to raise that with a maintainer?

      +

      Alex: Keep the teaching thread moving. Here is the plain-English version of 13. What We Are NOT Covering (And Where to Learn More). This workshop covers what you need as a contributor. Put another way, we are intentionally not diving into. It is like learning a transit route. The names of the stops matter because they tell you whether you are still going the right direction.

      +

      Alex: The practical takeaway is this. Writing workflow files from scratch. Setting up self-hosted runners. Creating custom Actions. Advanced workflow patterns (matrix builds, reusable workflows, environments).

      -

      Jamie: Before we leave Solutions, what is the practical point?

      -

      Alex: First, provide more context in your prompt: Be specific about what you need. Then, use @ mentions: Reference specific files or selections (@filename.md, selection). After that, check the agent's prerequisites: Did you do the manual work first? Finally, review the agent's instructions: Open.github/agents/[name].agent.md and read what it's supposed to do. It is like walking a hallway with named doors: read the sign, enter the right room, then confirm where you landed.

      -

      Alex: Keep the teaching thread moving. The reason Slash command doesn't work matters is that issue: /command shows "Command not found.". The interface gets friendlier when it stops being a wall of controls and starts being a set of named places.

      -

      Jamie: What is the teaching move inside Solutions?

      -

      Alex: Start with Solutions: Next: Chapter 20: Build Your Agent Back: Chapter 18: Fork and Contribute Related appendices: Appendix L: Agents Reference Appendix K: Copilot Reference.

      -

      Alex: First, verify.github/prompts/[name].md exists. Then, reload window: Ctrl+Shift+P → "Reload Window". After that, check file naming: must be a.md file in.github/prompts/. Finally, try typing the full command name (autocomplete may be incomplete). Think of it as a rail line: each stop confirms you are still on the right route before the next one.

      +

      Jamie: Let's pause on Summary. What should a learner take away from it?

      +

      Alex: This is where Summary becomes real: day 2 Bridge - From Actions to Agentic Workflows Understand standard YAML workflow files before engaging with agentic workflows. That matters in practice: GitHub Agentic Workflows are not a separate technology - they are the next layer on top of what you learned here.

      -

      Jamie: What is the final checkpoint?

      -

      Alex: You should be able to point to the evidence, explain the action, and describe what you would do next if this were a real open source project. If you can teach the move back, you have learned it.

      -

      Jamie: And if they get stuck?

      -

      Alex: Read the latest message, not the loudest worry. Check the issue, the branch, the pull request, the status check, or the bot comment. Then ask for help with those facts in hand. That is how professionals collaborate.

      +

      Jamie: What should people carry with them after this?

      +

      Alex: Carry the map. Know what page or tool you are in, know which action you are taking, and know what confirmation should follow. If the confirmation is missing, pause. That pause is not wasted time; it is professional judgment.

      +

      Jamie: That is a better way to say it than just follow the steps.

      +

      Alex: Right. Steps matter, but understanding wins. That is episode 34. Next in the series is episode 35, where we keep building the same contributor muscles.

      -

      Challenge bonus-a: Improve an Agent

      -

      Extending or improving an existing agent with a clear accessibility purpose.

      +

      64. Episode 35: Profile, Sponsors, and Wikis

      +

      Profile README, GitHub Sponsors, and repository Wikis.

      +

      Based on: Appendix T: Profile, Sponsors, and Wikis

      +

      Audio and transcript are being regenerated for this episode.

      -Read Transcript - Challenge bonus-a: Improve an Agent +Read Transcript - Episode 35: Profile, Sponsors, and Wikis

      Transcript

      -

      Alex: This is Challenge Coach for Improve an Agent. I am Alex, and we are going to teach the move before asking you to prove it.

      -

      Jamie: And I am Jamie. I will translate the challenge into the practical questions learners actually have while doing it.

      +

      Alex: Welcome to episode 35 of Git Going with GitHub: Profile, Sponsors, and Wikis. I am Alex, and today we are teaching this topic as a conversation you can carry into the workshop, not as a page you have to memorize.

      +

      Jamie: And I am Jamie. I will keep pulling the lesson back to real learners, real repositories, and the evidence that proves the work happened.

      -

      Alex: Extending or improving an existing agent with a clear accessibility purpose. That is the task layer. The teaching layer is understanding why the move belongs in a contributor workflow.

      -

      Jamie: So evidence is not just proof for the facilitator. It is part of how the learner understands the workflow.

      -

      Alex: Right. A good challenge produces something inspectable: a comment, issue, branch, commit, pull request, review, or clear note about what happened.

      +

      Alex: The lesson focus is Profile README, GitHub Sponsors, and repository Wikis. We will treat every step as a teachable decision, because that is what makes the skill portable.

      +

      Jamie: So we should explain the why clearly enough that the steps make sense when the learner meets them later.

      +

      Alex: That is it. If a listener only has audio right now, they should still get the complete concept and know what evidence would prove success.

      Jamie: Okay, set the room for us. What are we walking into?

      -

      Alex: Start with Bonus A: Improve an Existing Agent: For students who: Finish early and want to contribute more to the accessibility-agents ecosystem. The next useful detail is this: What you will do: Choose an existing agent in the accessibility-agents repository, identify something that could be better, and open a PR with your improvement.

      +

      Alex: Start with Building Your Community Presence on GitHub: This appendix covers three community-facing GitHub features: your profile README (how the world sees you), GitHub Sponsors (financially supporting the people whose work you depend on), and GitHub Wikis (community-editable documentation inside a repository).

      Alex: A solid pull request habit is to separate three questions: what changed, why it changed, and what still needs review. That keeps the conversation useful instead of noisy.

      -

      Jamie: How would you walk the room through that step by step?

      -

      Alex: Start with Instructions. There is something to understand, something to try, and something that proves the try worked.

      -

      Alex: The practical anchors are these. Add a missing guardrail. Clarify a responsibility that is vague. Fix a typo or improve the description. Add a new responsibility that fits the agent's purpose.

      -

      Alex: First, browse the agents in the accessibility-agents repository. Then, pick one that interests you and read its.agent.md file carefully. After that, identify an improvement. Ideas. Finally, make the change on your fork (you already forked this in Challenge 16). Treat it like a recipe: do not add the next ingredient until the previous one is actually in the bowl.

      -

      Jamie: What does the learner do first, second, and then after that?

      -

      Alex: First, open a pull request explaining what you improved and why. It is a checklist, but a meaningful one: every item creates evidence that the next step is safe.

      +

      Alex: The next layer is this. Start with Learning Cards: Profiles, Sponsors, and Wikis. There is something to understand, something to try, and something that proves the try worked.

      +

      Alex: The practical anchors are these. Your profile README is announced as regular page content when someone visits your profile -- use headings for structure so visitors can navigate with H. The Sponsor button on a profile or repo is a standard button element -- press B to cycle through buttons until you hear "Sponsor". Wiki pages are read in browse mode like any other GitHub Markdown page -- use heading navigation to jump between sections. Profile READMEs respect GitHub's dark and light themes -- test yours in both modes to confirm text remains readable. The Sponsor button uses a heart icon with a pink/magenta accent -- look near the repo name or profile photo area. Wiki sidebar navigation appears on the right side of the page with links to all wiki pages.

      Jamie: What is the one idea that makes the next few steps less mysterious?

      -

      Alex: Start with Improvement criteria. There is something to understand, something to try, and something that proves the try worked.

      -

      Alex: That shows up in the workshop in a few specific ways. Specific -- change one thing well, not many things vaguely. Justified -- explain WHY the change makes the agent better. Respectful -- the original author made choices for reasons. Improve, do not rewrite.

      +

      Alex: This is where The Special Profile README becomes real: GitHub has a hidden feature: if you create a repository named exactly your-username/your-username (e.g., janesmith/janesmith), the README in that repo appears on your GitHub profile page. That matters in practice: It's a custom introduction visible to anyone who visits your profile.

      -

      Alex: Now bring the learner back to the room. Keep the learner anchored in Example improvement. Target agent: aria-specialist.agent.md. This is the part to say slowly: What I changed: Added a new responsibility for checking aria-live regions in dynamic content.

      +

      Jamie: Turn that into a path someone can follow.

      +

      Alex: Start with Creating Your Profile README. There is something to understand, something to try, and something that proves the try worked.

      +

      Alex: First, create a new repository. Then, name it exactly your-username (match your GitHub username exactly, case-sensitive). After that, make it public. Finally, initialize with a README. It is like walking a hallway with named doors: read the sign, enter the right room, then confirm where you landed.

      +

      Jamie: What is the ordered workflow?

      +

      Alex: First, edit the README with whatever you want to show on your profile. The rhythm is simple: orient, act, verify, then continue.

      Jamie: What would you say to someone who is already bracing for this to be too much?

      -

      Alex: The reason What matters matters is that the learning objective is contributing to an existing project by understanding its conventions and making a targeted improvement. That gives the learner a simple foothold: if you identified a real gap and proposed a specific, well-reasoned change, you completed this bonus.

      +

      Alex: Start with What to include. There is something to understand, something to try, and something that proves the try worked.

      +

      Alex: The parts worth keeping in working memory are these. Introduction: Who you are, what you work on. Current focus: What projects or technologies you're learning. Skills: Languages, frameworks, tools (optional). How to reach you: Email, LinkedIn, personal site. Fun facts: Hobbies, interests (optional-keeps it human).

      Alex: The useful habit is simple: orient first, act second, verify third. That pause before acting is part of the work.

      -

      Alex: That matters because of the next idea. Start with 55 AI Agents Across 3 Teams and 5 Platforms: Day 2, Block 3 Material Before you read this guide: Accessibility Agents is a growing open source ecosystem: 55 AI-powered agents organized into three teams (Accessibility, GitHub Workflow, and Developer Tools), running on five platforms (GitHub Copilot,. The next useful detail is this: This chapter introduces the full landscape. Think of it like entering a new building: first you find the lobby, then the room, then the door you actually need.

      +

      Jamie: How do you keep commands from becoming magic words?

      +

      Alex: Start with Example profile README. There is something to understand, something to try, and something that proves the try worked.

      +

      Alex: Treat examples as spoken recipes, not decorations. You may hear something like Hi, I'm Jane Smith; I'm an accessibility advocate and open source contributor focused on making the web more inclusive.; Current focus; - Contributing to NVDA documentation; - Building accessible React components; - Learning TypeScript; Skills; - JavaScript,. Read the command, understand what it changes, then run it only when the repository state matches the lesson.

      Jamie: If I am listening before the workshop starts, what should settle in my mind first?

      -

      Alex: Start with Core Prerequisites (Required for All Agents). There is something to understand, something to try, and something that proves the try worked.

      -

      Alex: Here is what that changes in practice. [ ] Chapter 0: Pre-Workshop Setup - Git, VS Code, and GitHub account. [ ] Chapter 16: GitHub Copilot - GitHub Copilot Chat installed and working. [ ] GitHub Copilot access (Copilot Free tier is enough for this workshop). [ ].github/agents/ folder exists in your repository (or will create custom agents).

      -

      Alex: This is where the talk moves from concept to action. This is where Agent Prerequisites (The "Skill First" Principle) becomes real: every agent automates a skill you should already know by hand. That matters in practice: Before using any agent, verify you have done the corresponding manual work.

      -

      Jamie: Where does the workshop stop being a tour and start becoming contribution?

      -

      Alex: Keep the learner anchored in Workshop Recommendation (Chapter 19 / Challenge 15). Chapter 19 is the agent exploration and hands-on validation chapter - where students match agents to skills they already have and learn how to trust, evaluate, and improve AI-powered workflow automation. This is the part to say slowly: It supports Challenge 15: Meet the Agents.

      -

      Alex: These are the details that keep the idea from floating away. There are 3 guided + 1-2 optional contribution challenges. Automation check: none (agent output requires human judgment before use). The evidence is issue comment showing agent output and your evaluation of it. The pattern is explore, validate, read internals, optionally contribute.

      +

      Alex: Here is the plain-English version of Profile README Best Practices. Keep it concise - visitors skim, not read Update occasionally - a README from 2019 looks stale Be authentic - people connect with real humans, not buzzwords Include links - make it easy to learn more or get in touch. Put another way, avoid excessive badges - 50 skill badges is visual clutter and screen reader noise Skip auto-generated stats - "commits per day" widgets are often inaccessible Don't overthink it - a simple paragraph is better than nothing.

      +

      Alex: This is where the talk moves from concept to action. Start with Screen Reader Considerations. There is something to understand, something to try, and something that proves the try worked.

      +

      Alex: The room should hear these as checkpoints. Use headings ( ) for structure. Provide alt text for any images. Avoid ASCII art - screen readers read it character by character (annoying). Test your README with a screen reader before publishing.

      +

      Alex: A solid navigation habit is to prove where you are before activating controls. Headings, landmarks, and the address bar are not trivia; they are your map.

      +

      Jamie: Where do you want a learner to place their attention here?

      +

      Alex: Start with Pinned repositories (up to 6). There is something to understand, something to try, and something that proves the try worked.

      +

      Alex: These are the details that keep the idea from floating away. Highlight your best work on your profile. Navigate to your profile → Select "Customize your pins". Choose which repos appear first.

      -

      Jamie: What is the ordered workflow?

      -

      Alex: Start with Challenge 15 Set. There is something to understand, something to try, and something that proves the try worked.

      -

      Alex: First, agent Discovery Mapping - identify 3-5 agents that match skills you already have from Day 1. Then, agent Skill Validation - run one agent and evaluate its output against your manual experience. After that, agent Instructions Deep Dive - read one agent's source file and assess what it can and cannot do. Finally, improve an Existing Agent (optional hackathon) - find a gap in an agent's instructions and fix it via PR. The rhythm is simple: orient, act, verify, then continue.

      +

      Alex: Before the learner moves on. Start with Contribution graph. There is something to understand, something to try, and something that proves the try worked.

      +

      Alex: That becomes easier when you listen for these cues. Shows your GitHub activity over the past year. Green squares indicate days with commits, PRs, issues, etc. Cannot be customized but reflects consistent contribution.

      +

      Jamie: Give me the version that sounds like an instructor, not a manual.

      +

      Alex: Start with Status. There is something to understand, something to try, and something that proves the try worked.

      +

      Alex: A few details make that real. Set a temporary status message (e.g., "On vacation until March 15"). Navigate to your profile → Select the smile icon → Set status.

      +

      Alex: Hold that next to this. Here is the plain-English version of What Is GitHub Sponsors? GitHub Sponsors lets you financially support developers and projects you depend on.

      +
      +

      Jamie: Let's pause on How it works. What should a learner take away from it?

      +

      Alex: Start with How it works. There is something to understand, something to try, and something that proves the try worked.

      +

      Alex: That shows up in the workshop in a few specific ways. Developers/projects create a Sponsors profile. You choose a monthly sponsorship tier ($5, $10, $25/month, etc.). Your payment goes directly to the developer (GitHub takes no fees).

      +

      Alex: That connects to another useful point. Start with Why Sponsor? There is something to understand, something to try, and something that proves the try worked.

      +

      Alex: For a learner, the useful signals are these. Sustainability: Many open source maintainers volunteer their time. Sponsorships help them keep projects alive. Gratitude: If a project saved you hours of work, sponsorship is a way to say thanks. Priority support: Some maintainers offer sponsor-only Discord access, early releases, or prioritized bug fixes.

      Jamie: Give me the sequence, because order matters here.

      -

      Alex: First, propose a New Agent (optional hackathon) - file an issue proposing an agent for an uncovered workflow. Think of it as a rail line: each stop confirms you are still on the right route before the next one.

      -

      Jamie: Turn that into a path someone can follow.

      -

      Alex: Start with Challenge 15.1 Step-by-Step: Agent Discovery Mapping: Map your Day 1 manual skills to specific agents in the ecosystem so you know which agents you are ready to use. The next useful detail is this: GitHub.com - the accessibility-agents repository and your assigned Challenge 15 issue.

      -

      Alex: A few details make that real. @daily-briefing (maps to repository and issue awareness from Chapters 2-4). @issue-tracker (maps to Chapter 4 issue workflow). @pr-review (maps to Chapter 6 and Chapter 14 review workflow). Example: You filed issues manually (Ch 4) - you can use @issue-tracker.

      -

      Alex: First, fork the accessibility-agents repository on GitHub.com. Then, open the repository and navigate to Section 3 of the README (or this chapter's Section 3 below) to see the full list of 55 agents organized by team. After that, read through the agent names and descriptions. For each one, ask yourself: "Have I done this task manually during the workshop?". Finally, identify 3-5 agents that match workflows you already practiced. Think of it as a rail line: each stop confirms you are still on the right route before the next one.

      -

      Jamie: Let's pause on Challenge 15.1 Step-by-Step: Agent Discovery Mapping. What should a learner take away from it?

      -

      Alex: First, open your assigned Challenge 15 issue. Then, post a discovery mapping comment using this format. Treat it like a recipe: do not add the next ingredient until the previous one is actually in the bowl.

      -

      Jamie: Let's pause on Challenge 15.2 Step-by-Step: Agent Skill Validation. What should a learner take away from it?

      -

      Alex: Here is the plain-English version of Challenge 15.2 Step-by-Step: Agent Skill Validation. Run one agent, read its output, and evaluate whether it matches your manual experience. Put another way, VS Code with the accessibility-agents repository cloned and Copilot Chat open.

      -

      Alex: For a learner, the useful signals are these. @daily-briefing morning briefing. @issue-tracker find open issues labeled good-first-issue in accessibility-agents. @pr-review show open PRs in accessibility-agents.

      -

      Alex: First, clone your fork of accessibility-agents to VS Code (or open it in github.dev). Then, open Copilot Chat: Ctrl+Shift+I (Mac: Cmd+Shift+I). After that, choose one agent from your discovery list. If unsure, start with @daily-briefing or @issue-tracker. Finally, run it with a simple prompt. Treat it like a recipe: do not add the next ingredient until the previous one is actually in the bowl.

      -

      Jamie: Before we leave Challenge 15.2 Step-by-Step: Agent Skill Validation, what is the practical point?

      -

      Alex: First, read the agent's output carefully. Take a moment to think about what you expected. Then, open your assigned Challenge 15 issue and post an evaluation comment. It is a checklist, but a meaningful one: every item creates evidence that the next step is safe.

      +

      Alex: Start with How to Sponsor. There is something to understand, something to try, and something that proves the try worked.

      +

      Alex: First, navigate to a user or repository's GitHub page. Then, look for the "Sponsor" button (heart icon). After that, choose a tier or custom amount. Finally, select payment method (credit card or PayPal). The rhythm is simple: orient, act, verify, then continue.

      +

      Jamie: How would you walk the room through that step by step?

      +

      Alex: First, GitHub sends a receipt; your sponsorship appears on your profile (optionally publicly). Think of it as a rail line: each stop confirms you are still on the right route before the next one.

      -

      Jamie: Let's pause on Challenge 15.3 Step-by-Step: Agent Instructions Deep Dive. What should a learner take away from it?

      -

      Alex: This is where Challenge 15.3 Step-by-Step: Agent Instructions Deep Dive becomes real: read one agent's source file to understand what instructions it follows, what tools it can use, and what mistakes it could make. That matters in practice: VS Code or GitHub.com - reading files in the accessibility-agents repository.

      -

      Alex: The parts worth keeping in working memory are these. What is this agent trying to do? (its purpose). What tools does it have access to? (tool permissions). What constraints or guardrails are in the instructions?

      -

      Alex: First, in the accessibility-agents repository, navigate to the.github/ folder (or wherever agent definition files are stored). Then, open one.agent.md or.prompt.md file for an agent you used or are curious about. After that, read the file and identify. Finally, think critically: could this agent make a mistake? What kind? It is a checklist, but a meaningful one: every item creates evidence that the next step is safe.

      -

      Jamie: Before we leave Challenge 15.3 Step-by-Step: Agent Instructions Deep Dive, what is the practical point?

      -

      Alex: First, open your assigned Challenge 15 issue and post your analysis. It is like walking a hallway with named doors: read the sign, enter the right room, then confirm where you landed.

      -

      Alex: That connects to another useful point. Keep the learner anchored in Optional Extensions 15.4-15.5 (Hackathon). Extension 15.4: Improve an Existing Agent (45 min). This is the part to say slowly: Extension 15.5: Propose a New Agent (60 min). A good GitHub workflow is like a well-run meeting: everyone knows the topic, the next action, and who has the floor.

      -

      Alex: On the ground, that means a few things. Find an agent whose instructions have a gap (use Section 6 suggestions or file an issue). Fork the repo, edit the agent's.agent.md file. Get a facilitator review. Open a PR with your improvement.

      -

      Jamie: What should the learner prove to themselves after each small task?

      -

      Alex: The reason Completing Challenge 15: Submit Your Evidence matters is that your evidence is the Challenge 15 issue comments for 15.1, 15.2, and 15.3. That gives the learner a simple foothold: for optional extensions, your PR or proposal issue is the evidence.

      +

      Alex: Here is the practical turn. Start with Screen reader navigation. There is something to understand, something to try, and something that proves the try worked.

      +

      Alex: On the ground, that means a few things. The Sponsor button appears near the profile photo or repo name. Press B to cycle through buttons on the page until you hear "Sponsor".

      +

      Jamie: What does the learner do first, second, and then after that?

      +

      Alex: Here is the plain-English version of Can I Receive Sponsorships? If you maintain an open source project or contribute regularly. Put another way, many accessibility advocates successfully use Sponsors to fund their work improving assistive technology and inclusive design.

      +

      Alex: First, navigate to github.com/sponsors. Then, select "Join the waitlist" or "Set up sponsors". After that, connect a payment method (Stripe or bank account). Finally, create sponsor tiers with descriptions. Treat it like a recipe: do not add the next ingredient until the previous one is actually in the bowl.

      +

      Jamie: Let's pause on Can I Receive Sponsorships? What should a learner take away from it?

      +

      Alex: First, promote your Sponsors page to your audience. It is a checklist, but a meaningful one: every item creates evidence that the next step is safe.

      +

      Alex: Keep the thread going. This is where What Is a GitHub Wiki? becomes real: every repository can have a wiki - a space for documentation separate from the code. That matters in practice: It's lightweight and Markdown-based. The workshop is closer to rehearsal than lecture. You hear the move, try the move, and then check what changed.

      -

      Alex: Here is the practical turn. Start with Expected Outcomes. There is something to understand, something to try, and something that proves the try worked.

      -

      Alex: The room should hear these as checkpoints. Student can map personal Day 1 skills to specific agents in the ecosystem. Student understands the Skill First, Agent Second principle and can articulate why agent output requires human judgment. Student can read agent instructions and evaluate what an agent can and cannot do. Student has used at least one agent and verified it against manual skills. (Optional) Student has contributed to the accessibility-agents ecosystem with a fix, improvement, or proposal.

      -

      Jamie: Let's pause on If You Get Stuck. What should a learner take away from it?

      -

      Alex: Here is the plain-English version of If You Get Stuck. Continue learning: The GitHub Skills courses Build Applications with Copilot Agent Mode and Expand Your Team with Copilot explore agent-powered development workflows. Put another way, see Appendix Z for the full catalog.

      -

      Alex: First, cannot find an agent that matches your skills? Start with @daily-briefing or @issue-tracker - those build directly on Chapter 2-5 material. If you have not done those manual steps yet, go back to those chapters first. Then, agent output does not make sense? That is the right response. Paste the output in an issue comment along with your confusion. That is valuable feedback - the agent may need better instructions or guardrails. After that, cannot access the agents in Copilot Chat? Verify: Is Copilot Chat extension installed (not just base Copilot)? Are you signed in to GitHub in VS Code? Does.github/agents/ folder exist in your cloned repository? Finally, repository will not clone? Use the terminal: git clone https://github.com/[your-username]/accessibility-agents.git then open the folder in VS Code. Treat it like a recipe: do not add the next ingredient until the previous one is actually in the bowl.

      -

      Jamie: Before we leave If You Get Stuck, what is the practical point?

      -

      Alex: First, ask facilitator to show them what agent you wanted to run, what output you got, and what you expected. Then, finished but not sure you did it right? Compare your work against the Challenge 15 reference solution. It is a checklist, but a meaningful one: every item creates evidence that the next step is safe.

      -

      Alex: Keep the thread going. This is where Learning Moment becomes real: the 55 agents exist because someone did the manual work first, then automated the repetitive parts. That matters in practice: As you explore agents, you are not just learning tools - you are learning what automation looks like when it is built on real expertise and real constraints. The workshop is closer to rehearsal than lecture. You hear the move, try the move, and then check what changed.

      +

      Jamie: Let's pause on When to use a wiki. What should a learner take away from it?

      +

      Alex: Start with When to use a wiki. There is something to understand, something to try, and something that proves the try worked.

      +

      Alex: Here is what that changes in practice. Multi-page documentation (tutorials, guides, FAQs). Community-editable docs (wikis can be editable by anyone). Knowledge that doesn't belong in README (too long, too specific).

      +

      Alex: Another way to ground it. Start with When NOT to use a wiki. There is something to understand, something to try, and something that proves the try worked.

      +

      Alex: The practical takeaway is this. Your project already uses GitHub Pages or external docs. Documentation needs to be version-controlled with code (wikis are separate Git repos). You want full control (wikis are less customizable than Pages).

      +

      Jamie: Let's pause on Accessing a Repo's Wiki. What should a learner take away from it?

      +

      Alex: Start with Accessing a Repo's Wiki. There is something to understand, something to try, and something that proves the try worked.

      +

      Alex: First, navigate to the repository. Then, select the "Wiki" tab. After that, if no wiki exists, you'll see "Create the first page". Think of it as a rail line: each stop confirms you are still on the right route before the next one.

      +
      +

      Jamie: Let's pause on Creating Wiki Pages. What should a learner take away from it?

      +

      Alex: Here is the plain-English version of Creating Wiki Pages. Wiki pages automatically appear in a sidebar for navigation. It is like learning a transit route. The names of the stops matter because they tell you whether you are still going the right direction.

      +

      Alex: First, go to the Wiki tab. Then, select "New page". After that, add a title and content (Markdown). Finally, select "Save". Treat it like a recipe: do not add the next ingredient until the previous one is actually in the bowl.

      +

      Jamie: Let's pause on Wiki Accessibility. What should a learner take away from it?

      +

      Alex: This is where Wiki Accessibility becomes real: return to: Resources Appendix S - Organizations and Templates Appendix G - GitHub Discussions Appendix T - Contributing to Open Source Appendix A - Glossary.

      +

      Alex: The practical takeaway is this. GitHub's wiki editor is the same as the issue/PR comment editor. All Markdown features work (headings, lists, links, code blocks). Use proper heading hierarchy (, ) for screen reader navigation. Link between wiki pages: [[Page Title]]. Screen reader caveat: Wiki pages are a separate Git repository. Any changes pushed directly to the wiki's git remote are not tracked by the main repository's branch protection - meaning no PR review process applies. Treat wikis as community-editable.

      +

      Alex: Now bring the learner back to the room. Start with Learning Cards: Organizations and Templates. There is something to understand, something to try, and something that proves the try worked.

      +

      Alex: The practical takeaway is this. The "Use this template" button is near the "Code" button at the top of a template repository -- press B to navigate buttons until you hear it. Organization profiles list repositories and members under heading sections -- use H to jump between People, Repositories, and Projects. Repository visibility (Public, Private, Internal) is announced as a badge near the repository name heading. Template repositories show a green "Use this template" button prominently near the top -- it replaces or sits alongside the Fork button. Organization pages use the same layout as personal profiles but with team-oriented sections. Archived repositories display a yellow warning banner across the top of the page.

      +
      +

      Jamie: How should someone choose between those options?

      +

      Alex: The reason Template vs. Fork - Which One? matters is that these are two very different actions that both appear near the "Code" button. That gives the learner a simple foothold: GitHub Skills courses use "Use this template" - you start fresh with the course scaffold but your copy has no upstream connection.

      +

      Alex: Use the comparison to make a decision, not to recite a table. The main contrasts are: Use when. means What you get. Contributing back to the original project means Full git history; your changes can be PRed upstream. Use this template means Starting a new project based on the structure means Clean git history; no connection to the original repo.

      +

      Jamie: Let's pause on Creating a Template Repository. What should a learner take away from it?

      +

      Alex: Start with Creating a Template Repository: Maintainers can mark any repository as a template. Think of it like entering a new building: first you find the lobby, then the room, then the door you actually need.

      +

      Alex: First, navigate to the repository's Settings tab. Then, scroll to the "General" section → find the "Template repository" checkbox. After that, check it and save. Finally, the repository now shows a "Use this template" button instead of (or alongside) "Fork". Think of it as a rail line: each stop confirms you are still on the right route before the next one.

      +

      Jamie: Let's pause on Using a Template Repository. What should a learner take away from it?

      +

      Alex: Start with Using a Template Repository. There is something to understand, something to try, and something that proves the try worked.

      +

      Alex: First, navigate to the template repository. Then, select "Use this template" button (near the top, next to "Code"). After that, select "Create a new repository". Finally, name your new repository, choose visibility, and confirm. Treat it like a recipe: do not add the next ingredient until the previous one is actually in the bowl.

      +

      Jamie: Before we leave Using a Template Repository, what is the practical point?

      +

      Alex: First, GitHub creates a new repository with the template's files but no commit history. It is a checklist, but a meaningful one: every item creates evidence that the next step is safe.

      +
      +

      Jamie: What should happen before anyone copies and runs it?

      +

      Alex: Start with Screen reader path. There is something to understand, something to try, and something that proves the try worked.

      +

      Alex: Treat examples as spoken recipes, not decorations. You may hear something like B → navigate buttons → find "Use this template" → Enter; ↓ → "Create a new repository" from the dropdown → Enter. Read the command, understand what it changes, then run it only when the repository state matches the lesson.

      +

      Jamie: Let's pause on What Is an Organization? What should a learner take away from it?

      +

      Alex: Keep the learner anchored in What Is an Organization? A GitHub organization is an account that multiple people share. This is the part to say slowly: Instead of github.com/username/repo, organization repos live at github.com/org-name/repo.

      +

      Jamie: Let's pause on Joining an Organization. What should a learner take away from it?

      +

      Alex: The reason Joining an Organization matters is that maintainers can invite you to join. That gives the learner a simple foothold: you can also be a public contributor to an org repo without being a member - you fork the repo and submit PRs without needing an invitation. The interface gets friendlier when it stops being a wall of controls and starts being a set of named places.

      +

      Alex: First, you receive an email + GitHub notification. Then, navigate to github.com/settings/organizations to accept. After that, or click the link in the invitation email. The rhythm is simple: orient, act, verify, then continue.

      +
      +

      Jamie: Let's pause on Organization Membership Visibility. What should a learner take away from it?

      +

      Alex: Start with Organization Membership Visibility. There is something to understand, something to try, and something that proves the try worked.

      +

      Alex: The practical takeaway is this. By default, your org membership is private (only you and org owners can see it). You can set it to public in your organization membership settings. Public membership appears on your GitHub profile under "Organizations". For community-access: if you become a member, set your membership public to show your contribution publicly on your profile.

      +

      Alex: This is the part worth saying out loud. Here is the plain-English version of Teams Inside Organizations. Organizations can create teams (e.g., @community-access/accessibility-reviewers). Put another way, when you see a team mentioned in a PR or issue, that @mention notifies everyone on that team.

      +

      Jamie: Let's pause on Navigating an Organization Profile Page. What should a learner take away from it?

      +

      Alex: This is where Navigating an Organization Profile Page becomes real: organization-level Projects (like the community-access project board) appear in the org's Projects tab, not inside any single repository.

      +
      +

      Alex: That matters because of the next idea. Keep the learner anchored in Repository Settings - What Contributors Need to Know. You may not have Settings access to most repositories (that requires maintainer role). This is the part to say slowly: But knowing what's there helps you understand why a repository behaves the way it does. A good GitHub workflow is like a well-run meeting: everyone knows the topic, the next action, and who has the floor.

      +

      Jamie: Let's pause on Repository Visibility. What should a learner take away from it?

      +

      Alex: The reason Repository Visibility matters is that the repository's visibility label appears on its page. That gives the learner a simple foothold: screen readers: the visibility badge is usually near the repo name heading (H1).

      +

      Alex: Keep the teaching thread moving. Start with Archived Repositories: When a maintainer archives a repository, it becomes read-only. The next useful detail is this: If you find a repo you planned to contribute to is archived, look for a fork or successor project.

      +

      Alex: The practical takeaway is this. No new issues, PRs, or comments can be created. Existing content is fully preserved and viewable. The UI shows a yellow banner: "This repository has been archived by the owner.". Screen readers: NVDA/JAWS will read this banner when you navigate to the top of the page with Ctrl+Home.

      +
      +

      Jamie: Let's pause on Repository Topics. What should a learner take away from it?

      +

      Alex: Here is the plain-English version of Repository Topics. Topics are keyword tags on a repository (e.g., accessibility, screen-reader, open-source). Put another way, they appear as colored chips on the repository home page and improve discoverability in GitHub search.

      +

      Alex: The practical takeaway is this. As a contributor: Topics tell you what the project is about at a glance. As a maintainer: Add topics in Settings → General → Topics section to improve search ranking. Screen reader: Topics are links in the "About" sidebar section; use B (next button) or Links list to reach them.

      +

      Alex: Keep the teaching thread moving. This is where Default Branch Name becomes real: the default branch is the one all PRs target by default. That matters in practice: Modern projects use main; older projects may use master or another name. The workshop is closer to rehearsal than lecture. You hear the move, try the move, and then check what changed.

      +

      Alex: A solid Git habit is to know which branch you are on, what changed, and what confirmation you expect before you run the next command.

      +

      Jamie: Let's pause on GitHub Is More Than a Code Host -- It's a Community. What should a learner take away from it?

      +

      Alex: Keep the learner anchored in GitHub Is More Than a Code Host -- It's a Community. Who this is for: You have learned the basics of GitHub and want to know how to use it as a social platform -- discovering interesting projects, following developers whose work you admire, and building a presence in the open source community. This is the part to say slowly: This appendix covers the social layer of GitHub that most tutorials skip entirely.

      +
      +

      Alex: Keep the teaching thread moving. Start with Learning Cards: Social Features. There is something to understand, something to try, and something that proves the try worked.

      +

      Alex: The practical takeaway is this. The Star button is announced as "Star this repository" or "Unstar this repository" -- press B to find it in the repository header area. The Follow button on a user profile is announced as "Follow [username]" -- Tab forward from the avatar and bio to reach it. On the Explore and Trending pages, each repository entry is a heading with a link -- use H or 3 to jump between entries. Star and Watch buttons sit side by side in the repository header with distinct icons (star and eye) -- both show counts next to them. Your contribution graph uses green intensity to show activity levels -- enable high-contrast theme if the color differences are hard to distinguish. The Trending page lists repositories in a numbered vertical list with star counts and daily gain on the right side.

      +

      Jamie: Let's pause on What a star is. What should a learner take away from it?

      +

      Alex: Start with What a star is: A star is GitHub's version of a bookmark combined with a "like." When you star a repository.

      +

      Alex: The practical takeaway is this. It saves to your starred list at github.com/username?tab=stars -- easy to find later. It signals to the maintainer that their work is valued. It contributes to the project's star count, which helps others discover it. It may appear in your followers' feeds.

      +

      Alex: Keep the teaching thread moving. Here is the plain-English version of Why star count matters to projects. Star counts are a social proof signal -- developers browsing for tools often sort by stars to find well-regarded projects. Put another way, a project going from 10 stars to 1,000 stars can dramatically change how many contributors it attracts. It is like learning a transit route. The names of the stops matter because they tell you whether you are still going the right direction.

      -

      Jamie: Let's pause on Learning Pattern Used in This Chapter. What should a learner take away from it?

      -

      Alex: Start with Learning Pattern Used in This Chapter. There is something to understand, something to try, and something that proves the try worked.

      -

      Alex: First, map your existing skills to available tools (discovery before action). Then, run one tool and evaluate its output critically (trust but verify). After that, read the source to understand capabilities and limits (internals matter). Finally, contribute improvements based on your evaluation (close the feedback loop). It is like walking a hallway with named doors: read the sign, enter the right room, then confirm where you landed.

      -

      Alex: Another way to ground it. The reason Capstone: Share Your Feedback (The Most Important Task!) matters is that you have now explored the full agent ecosystem, completed the workshop, and have valuable perspective on what worked, what confused you, and what we should improve for the next cohort. That gives the learner a simple foothold: your feedback directly shapes the future of this project.

      -

      Jamie: How should they picture the shape of the workshop?

      -

      Alex: Start with Submit Workshop Feedback: Use the Workshop Feedback form to share. The next useful detail is this: Answer as much or as little as you're comfortable sharing.

      -

      Alex: That becomes easier when you listen for these cues. Which agents stood out? (Most useful or surprising). Which agents confused you? (What would make them better). Was the chapter progression logical? (Did earlier chapters prepare you for later ones). Accessibility experience (If applicable - did any assistive technology work/fail?).

      +

      Jamie: Let's pause on GitHub.com. What should a learner take away from it?

      +

      Alex: This is where GitHub.com becomes real: on any repository page, the Star button is in the top-right area of the repository header, next to Fork.

      +

      Alex: The practical takeaway is this. Click Star to star the repository -- the button changes to Starred with a filled star icon. Click the dropdown arrow next to Star to choose a List to organize it into (see Section 8). Click Starred to unstar.

      +

      Alex: Keep the teaching thread moving. Keep the learner anchored in Keyboard shortcut. On a repository page, press g then s to toggle the star.

      +

      Jamie: Let's pause on Screen reader navigation. What should a learner take away from it?

      +

      Alex: Start with Screen reader navigation. There is something to understand, something to try, and something that proves the try worked.

      +

      Alex: The practical takeaway is this. NVDA/JAWS: The Star button is in the page region after the repository title heading. Navigate by button (B) or Tab to find it. It's announced as "Star this repository" or "Unstar this repository.". VoiceOver: VO+Command+J to jump to buttons, or Tab through the header area. The button label changes between "Star" and "Starred.".

      -

      Alex: This is the part worth saying out loud. Here is the plain-English version of 1. The Principle: Skill First, Agent Second. Accessibility Agents is not a way to skip learning GitHub. Put another way, it is a way to amplify skills you have already built through deliberate practice. It is like learning a transit route. The names of the stops matter because they tell you whether you are still going the right direction.

      -

      Alex: The practical takeaway is this. Verify that the agent's output is correct. Catch when the agent misses context that only you have. Edit the agent's drafts into something worth posting under your name. Know when the agent is confidently wrong.

      -

      Jamie: Give me the version that sounds like an instructor, not a manual.

      -

      Alex: This is where Every agent has a manual prerequisite. If you have not done the corresponding skill by hand, the agent is not ready for you yet - and you are not ready for it becomes real: this applies across all three teams and all 55 agents. That matters in practice: Before running any agent, the facilitator asks the same question.

      -

      Alex: The practical takeaway is this. GitHub Workflow agents automate repository navigation, issue triage, PR review, and contribution analytics - skills you practiced on Day 1. Accessibility agents automate WCAG auditing, contrast checking, keyboard navigation review, and document scanning - knowledge from your accessibility training and the standards in Appendix C. Developer Tools agents automate accessible coding patterns for Python, wxPython, and desktop applications - skills from your development experience.

      -

      Alex: The next layer is this. Start with Learning Cards: Skill First, Agent Second. There is something to understand, something to try, and something that proves the try worked.

      -

      Alex: The practical takeaway is this. Before using any agent, verify you can do the task manually -- for @daily-briefing, confirm you can navigate Issues and PRs on GitHub.com with keyboard shortcuts (j/k to move, Enter to open). Agent output appears in Copilot Chat -- press Alt+F2 to open Accessible View and read the full response with arrow keys before acting on it. If an agent produces something you do not understand, stop and learn the manual skill first from the relevant chapter. Agent responses appear in the Copilot Chat panel -- drag the panel wider or use Alt+F2 (Accessible View) for a larger, cleaner reading pane. Each agent's instructions are in a.agent.md file you can open in VS Code and read at your preferred zoom level before invoking the agent. The agent ecosystem table in Section 3 uses standard Markdown tables that scale with your editor font size.

      +

      Jamie: What is the safe way to learn from that example?

      +

      Alex: Start with GitHub CLI. There is something to understand, something to try, and something that proves the try worked.

      +

      Alex: Treat examples as spoken recipes, not decorations. You may hear something like Star a repository; gh api user/starred/owner/repo --method PUT; Unstar a repository; gh api user/starred/owner/repo --method DELETE; List your starred repositories; gh api user/starred --jq '.[].full name'; Check if you've starred a repo; gh api. Read the command, understand what it changes, then run it only when the repository state matches the lesson.

      +

      Jamie: Let's pause on Viewing your stars. What should a learner take away from it?

      +

      Alex: Here is the plain-English version of Viewing your stars. Go to github.com/username?tab=stars -- or click your avatar → Your stars. Put another way, you'll see all your starred repositories sorted by most recently starred.

      +

      Alex: Keep the teaching thread moving. Start with Learning Cards: Stars. There is something to understand, something to try, and something that proves the try worked.

      +

      Alex: The practical takeaway is this. The Star button is in the repository header area -- press B to navigate buttons until you hear "Star this repository" (or "Unstar this repository" if already starred); press Enter to toggle. The keyboard shortcut g then s on any repository page toggles the star without needing to navigate to the button. Your starred repos are listed at github.com/username?tab=stars -- each entry is a heading with the repo name as a link; use H to jump between starred repos. The Star button shows a star icon with a count next to it in the repository header -- at high zoom, the button may wrap below the repo name; look for the star icon near Fork and Watch. When you star a repo, the button changes from an outline star to a filled star with the label "Starred" -- the visual change is subtle; confirm by re-reading the button text. The dropdown arrow next to Star lets you add the repo to a List -- look for a small triangle icon to the right of the Star button at high magnification.

      -

      Jamie: There are a lot of tools in play. How do we keep that from feeling like a contest?

      -

      Alex: The reason Quick Install (One Command) matters is that accessibility Agents now ships with a one-liner installer that sets up all 55 agents for your platform.

      -

      Jamie: How do you keep commands from becoming magic words?

      -

      Alex: Start with macOS / Linux. There is something to understand, something to try, and something that proves the try worked.

      -

      Alex: Treat examples as spoken recipes, not decorations. You may hear something like curl -fsSL https://raw.githubusercontent.com/Community-Access/accessibility-agents/main/install.sh bash. Read the command, understand what it changes, then run it only when the repository state matches the lesson.

      -

      Jamie: Where do you want a learner to place their attention here?

      -

      Alex: Here is the plain-English version of Windows (PowerShell). The installer detects which AI tools you have installed (VS Code with Copilot, Claude Code, Gemini CLI, Claude Desktop, Codex CLI) and configures the appropriate agent files for each platform. Put another way, to uninstall, run the corresponding uninstall script from the repository.

      +

      Jamie: Let's pause on What watching does. What should a learner take away from it?

      +

      Alex: Keep the learner anchored in What watching does. When you watch a repository, GitHub sends you notifications about activity in it -- new issues, pull requests, releases, and more. This is the part to say slowly: Unlike stars (which are passive bookmarks), watching is active -- you're opting into the conversation.

      +

      Alex: Keep the teaching thread moving. The reason Watch levels matters is that GitHub gives you granular control over how much you hear from a repo. The interface gets friendlier when it stops being a wall of controls and starts being a set of named places.

      +

      Jamie: Let's pause on How to watch a repository. What should a learner take away from it?

      +

      Alex: Start with How to watch a repository: On any repository page, the Watch button is next to the Star button in the header. The next useful detail is this: For most repositories you contribute to, "Participating and @mentions" is the right level -- you hear about threads you're in without inbox overload.

      +

      Alex: First, click Watch to open the dropdown. Then, choose your notification level. After that, the button updates to show your current setting. Think of it as a rail line: each stop confirms you are still on the right route before the next one.

      -

      Jamie: Let's pause on Workshop Setup (Fork and Clone). What should a learner take away from it?

      -

      Alex: This is where Workshop Setup (Fork and Clone) becomes real: for the workshop, you will also fork and clone the repository so you can make contributions. That matters in practice: If Copilot Chat works, the agents work.

      -

      Alex: First, fork accessibility-agents to your GitHub account (you did this on Day 1 or Day 2 morning). Then, clone your fork. After that, open in VS Code: navigate to the folder and run code. (or File, then Open Folder). Finally, open Copilot Chat: Ctrl+Shift+I. It is a checklist, but a meaningful one: every item creates evidence that the next step is safe.

      -

      Jamie: Before we leave Workshop Setup (Fork and Clone), what is the practical point?

      -

      Alex: First, test: type @daily-briefing morning briefing and press Enter. It is like walking a hallway with named doors: read the sign, enter the right room, then confirm where you landed.

      -

      Alex: Treat examples as spoken recipes, not decorations. You may hear something like git clone https://github.com/[your-username]/accessibility-agents.git. Read the command, understand what it changes, then run it only when the repository state matches the lesson.

      -

      Jamie: Let's pause on Prerequisites. What should a learner take away from it?

      -

      Alex: Start with Prerequisites. There is something to understand, something to try, and something that proves the try worked.

      -

      Alex: The practical takeaway is this. GitHub Copilot Chat extension installed (see GitHub Copilot: Installation). Signed in to GitHub via VS Code. A workspace open containing.github/agents/ folder with.agent.md files.

      -

      Jamie: Let's pause on How Agents Are Discovered. What should a learner take away from it?

      -

      Alex: The reason How Agents Are Discovered matters is that when you type @ in Copilot Chat, VS Code scans. That gives the learner a simple foothold: the Accessibility Agents ecosystem installs agents appropriate to each platform. The interface gets friendlier when it stops being a wall of controls and starts being a set of named places.

      -

      Alex: First,.github/agents/.agent.md in your current workspace. Then, any agents installed globally on your machine. After that, agents defined by extensions. The rhythm is simple: orient, act, verify, then continue.

      +

      Jamie: What should they understand before typing anything?

      +

      Alex: Treat examples as spoken recipes, not decorations. You may hear something like Watch a repository (all activity); gh api repos/owner/repo/subscription --method PUT --field subscribed=true; Watch releases only (requires GitHub.com -- not available via API alone); Use the web UI for granular watch levels; Ignore a repository; gh api. Read the command, understand what it changes, then run it only when the repository state matches the lesson.

      +

      Jamie: Let's pause on Learning Cards: Watching Repositories. What should a learner take away from it?

      +

      Alex: Start with Learning Cards: Watching Repositories. There is something to understand, something to try, and something that proves the try worked.

      +

      Alex: The practical takeaway is this. The Watch button is next to the Star button in the repository header -- press B to navigate buttons until you hear "Watch" or a watch level label; press Enter to open the dropdown. The watch level dropdown presents radio-style options (Not watching, Participating, All Activity, Releases only, Ignore) -- arrow through them and press Enter to select. "Participating and @mentions" is the recommended default for repos you contribute to -- it notifies you only for threads you are in or mentioned in, avoiding inbox overload. The Watch button shows an eye icon with a dropdown arrow and a count of watchers -- at high zoom, look for it immediately to the left of the Star button in the repository header. The dropdown menu lists five watch levels vertically with radio indicators -- the currently selected level has a filled radio dot or checkmark next to it. "Releases only" is the best choice for tools and dependencies you use but do not contribute to -- it sends one notification per release instead of every issue and PR.

      +

      Alex: Keep the teaching thread moving. Keep the learner anchored in What following does. When you follow a developer on GitHub. This is the part to say slowly: Following is one-way (like Twitter/X) -- they don't need to follow you back. A good GitHub workflow is like a well-run meeting: everyone knows the topic, the next action, and who has the floor.

      +

      Alex: The practical takeaway is this. Their public activity appears in your home feed. You see when they star a repository, create a new repo, or get a new follower. They receive a notification that you followed them. You appear in their followers list.

      -

      Jamie: Let's pause on Optional: Personalize Your Instance. What should a learner take away from it?

      -

      Alex: Start with Optional: Personalize Your Instance: Open preferences.md in VS Code and edit. The next useful detail is this: Commit preferences.md to your fork.

      -

      Alex: Before the learner moves on. Here is the plain-English version of How Agents Travel with Your Repo. When you fork accessibility-agents, the.github/agents/ folder comes with it.

      -

      Alex: The practical takeaway is this. Any collaborator who clones your fork gets all 55 agents automatically. You can customize agents for your specific project by editing the.agent.md files in your fork. Any project can have agents - create a.github/agents/ folder in any repository and add.agent.md files using the same pattern. The one-liner installer can also set up agents globally, so they are available in every workspace you open.

      -

      Jamie: Let's pause on Invoking Agents on GitHub.com. What should a learner take away from it?

      -

      Alex: This is where Invoking Agents on GitHub.com becomes real: accessibility Agents agents run in VS Code. That matters in practice: But the same.agent.md files can also be invoked directly on GitHub.com - no VS Code, no local clone required.

      +

      Jamie: Let's pause on Who to follow. What should a learner take away from it?

      +

      Alex: The reason Who to follow matters is that start with people whose work you already use.

      +

      Alex: The practical takeaway is this. Maintainers of tools and libraries you use daily. Authors of blog posts or talks that helped you learn. Developers in accessibility, open source, or your tech stack. Visiting the Contributors tab of a repository you love: github.com/owner/repo/graphs/contributors. Checking who opened issues or PRs you found valuable. Looking at who your existing follows follow.

      +

      Alex: Keep the teaching thread moving. Start with How to follow someone: On any user profile page (github.com/username), click the Follow button below their avatar. The next useful detail is this: To unfollow: click Following → it changes back to Follow.

      +

      Jamie: Before we leave Screen reader navigation, what is the practical point?

      +

      Alex: The practical takeaway is this. Navigate to the profile page. The Follow/Following button is near the top of the page, below the avatar and bio. NVDA/JAWS: press B to jump to buttons; the button is labelled "Follow [username]". VoiceOver: Tab to the button or use VO+Command+J.

      -

      Jamie: Let's pause on Option 1: Copilot Chat with Task mode. What should a learner take away from it?

      -

      Alex: Keep the learner anchored in Option 1: Copilot Chat with Task mode. Screen reader users (NVDA / JAWS / VoiceOver). A good GitHub workflow is like a well-run meeting: everyone knows the topic, the next action, and who has the floor.

      -

      Alex: First, open Copilot Chat on GitHub.com (icon in the top-right navigation bar). Then, click Task in the mode picker. After that, optionally click the agent picker to select a custom agent. Finally, type your request and click Send. It is like walking a hallway with named doors: read the sign, enter the right room, then confirm where you landed.

      -

      Jamie: Before we leave Option 1: Copilot Chat with Task mode, what is the practical point?

      -

      Alex: First, Copilot analyzes the task and can create a branch and open a PR automatically. Then, open Copilot Chat on GitHub.com (navigate to icon in top-right navigation → Enter). After that, the mode picker (Task vs Chat) is a set of radio buttons - navigate with Arrow keys to select "Task". Finally, the agent picker is a listbox - Up/Down Arrow to navigate, Enter to select. The rhythm is simple: orient, act, verify, then continue.

      -

      Jamie: Let's pause on Option 2: Assign an issue to Copilot. What should a learner take away from it?

      -

      Alex: The reason Option 2: Assign an issue to Copilot matters is that screen reader users (NVDA / JAWS / VoiceOver). That gives the learner a simple foothold: this is the bridge to Section 6 (The Cloud Extension).

      -

      Alex: First, open any issue (or create a new one describing the task). Then, in the Assignees sidebar section, click the gear icon. After that, in the dropdown, click Copilot as the assignee. Finally, a dialog opens - optionally provide additional instructions and select a custom agent. The rhythm is simple: orient, act, verify, then continue.

      -

      Jamie: Before we leave Option 2: Assign an issue to Copilot, what is the practical point?

      -

      Alex: First, click Assign to confirm. Then, open any issue in the repository. After that, press B to navigate to the Assignees gear button → Enter to open the popup. Finally, navigate the popup with Arrow keys → find "Copilot" → Enter to select. Think of it as a rail line: each stop confirms you are still on the right route before the next one.

      -

      Alex: A solid issue habit is to read the title, the body, and the timeline before acting. You are listening for the requested action, the missing evidence, and the person who needs a response.

      -

      Alex: Hold that next to this. Start with Copilot on GitHub.com - Browser-Native Features: Beyond assigning Copilot to issues and using Task mode in Chat, GitHub.com now has several standalone Copilot features built directly into the web interface. The next useful detail is this: These work entirely in your browser - no VS Code, no local clone needed.

      +

      Jamie: Let's pause on GitHub CLI. What should a learner take away from it?

      +

      Alex: Treat examples as spoken recipes, not decorations. You may hear something like Follow a user; gh api user/following/username --method PUT; Unfollow a user; gh api user/following/username --method DELETE; List who you're following; gh api user/following --jq '.[].login'; List your followers; gh api user/followers --jq '.[].login'; Check. Read the command, understand what it changes, then run it only when the repository state matches the lesson.

      +

      Jamie: Let's pause on Viewing someone's profile. What should a learner take away from it?

      +

      Alex: Keep the learner anchored in Viewing someone's profile. The contribution graph is a visual calendar that screen readers may announce as a table or grid. This is the part to say slowly: Navigate with arrow keys to read individual day entries -- each cell describes the date and number of contributions.

      +

      Alex: The practical takeaway is this. Pinned repositories -- the 6 repos they've chosen to highlight. Contribution graph -- a visual grid of their activity over the past year (green squares = more activity). Recent activity -- PRs opened, issues commented on, repos starred. Repositories -- all their public repos.

      +

      Alex: Keep the teaching thread moving. The reason 4. Your Home Feed -- What You See When You Log In matters is that when you go to github.com while logged in, your home feed shows activity from people and repositories you follow or watch.

      -

      Jamie: Let's pause on Copilot PR Summary. What should a learner take away from it?

      -

      Alex: Here is the plain-English version of Copilot PR Summary. On any open pull request, GitHub adds a "Summarize" button in the PR description area. Put another way, selecting it generates a plain-language summary of what the PR changes, why, and what reviewers should focus on.

      -

      Alex: Keep the teaching thread moving. This is where Copilot PR Review becomes real: on open PRs you have write access to review, a "Review" button (or Copilot icon) appears in the Files changed tab. That matters in practice: Copilot generates inline review comments across the diff. The workshop is closer to rehearsal than lecture. You hear the move, try the move, and then check what changed.

      -

      Jamie: Let's pause on Copilot in Issues. What should a learner take away from it?

      -

      Alex: Keep the learner anchored in Copilot in Issues. On any issue page, Copilot adds sidebar buttons that appear once the page loads. This is the part to say slowly: Look in the right sidebar on any issue page for a Copilot section with "Explain" and "Suggest fix" buttons.

      -

      Alex: The practical takeaway is this. "Explain this issue" - generates a plain-language explanation of a complex technical issue. "Suggest fix" - proposes an approach to resolving the issue (opens a task/PR workflow).

      +

      Jamie: Let's pause on What appears in your feed. What should a learner take away from it?

      +

      Alex: Start with What appears in your feed. There is something to understand, something to try, and something that proves the try worked.

      +

      Alex: The practical takeaway is this. Repositories starred by people you follow -- "Jane starred awesome-accessibility". New repositories created by people you follow. Releases from repositories you watch. Public activity from people you follow (PRs opened, issues commented on). "For you" recommendations -- GitHub suggests repos and people based on your activity.

      +

      Alex: Keep the teaching thread moving. Here is the plain-English version of Your feed is a discovery tool. One of the best ways to find new interesting projects is to follow a few active developers in your area of interest and watch what they star. Put another way, if 5 people you respect all starred the same new tool this week, it's probably worth a look. It is like learning a transit route. The names of the stops matter because they tell you whether you are still going the right direction.

      +

      Jamie: Let's pause on Customising your feed. What should a learner take away from it?

      +

      Alex: This is where Customising your feed becomes real: there's no fine-grained feed filter -- you control the feed by controlling who you follow and what you watch. That matters in practice: Unfollow noisy accounts, follow more focused ones.

      -

      Alex: Keep the teaching thread moving. The reason GitHub Models - Free AI Playground matters is that github.com/marketplace/models is a free playground where you can test AI models (OpenAI GPT-4o, Meta Llama 3, Mistral, Phi-4 Mini, and others) directly in your browser. That gives the learner a simple foothold: why it matters for Accessibility Agents: When you build custom agents and prompts, you can test your system prompts and prompt templates in GitHub Models before adding them to your.prompt.md files - rapid iteration without burning API credits.

      -

      Alex: The practical takeaway is this. Send prompts to any listed model and compare responses side by side. Adjust parameters (temperature, max tokens) without any setup. Use the code sample generator to get API code for your chosen model. All free with a GitHub account (rate-limited for free tier).

      -

      Jamie: Let's pause on Copilot-Drafted Release Notes. What should a learner take away from it?

      -

      Alex: Start with Copilot-Drafted Release Notes: When creating a release (Releases tab → Draft a new release), GitHub provides a "Generate release notes" button. The next useful detail is this: It scans merged PRs since the last release and drafts categorized release notes automatically.

      -

      Alex: Keep the teaching thread moving. Start with Learning Cards: Setup and Configuration. There is something to understand, something to try, and something that proves the try worked.

      -

      Alex: The practical takeaway is this. Run the installer command in the VS Code terminal (Ctrl+) -- it announces progress as it copies agent files to.github/agents/`. After installation, press Ctrl+Shift+E to open the Explorer and navigate to.github/agents/ to verify agent files are present. Edit.github/agents/preferences.md to configure your username, repositories, and notification preferences -- it is a standard Markdown file. The installer creates files in.github/agents/ and.github/prompts/ -- verify in the Explorer sidebar that these folders appeared. Open preferences.md in the editor to set your configuration -- use Ctrl+= to zoom if the YAML frontmatter is hard to read. Agent files use.agent.md extension -- they appear alongside regular Markdown files in the Explorer but are distinguished by their extension.

      +

      Alex: Keep the teaching thread moving. Keep the learner anchored in 5. GitHub Explore -- Discovering New Projects. GitHub Explore at github.com/explore is the discovery hub -- curated collections, trending repos, and personalised recommendations.

      +

      Jamie: Let's pause on What Explore shows. What should a learner take away from it?

      +

      Alex: Start with What Explore shows. There is something to understand, something to try, and something that proves the try worked.

      +

      Alex: The practical takeaway is this. Trending -- most-starred repos this week (see Section 6). Topics -- browse by subject area (see Section 7). Collections -- curated lists of thematically related repos (e.g., "Tools for Open Source", "Accessibility Projects"). "For you" personalised recommendations -- based on your stars, follows, and language preferences.

      +

      Jamie: Let's pause on Navigating Explore with a screen reader. What should a learner take away from it?

      +

      Alex: Start with Navigating Explore with a screen reader. There is something to understand, something to try, and something that proves the try worked.

      +

      Alex: First, go to github.com/explore. Then, the page uses landmark regions -- jump to main to skip navigation. After that, collections and trending repos are listed as article/heading groups. Finally, use heading navigation (H) to jump between sections. Think of it as a rail line: each stop confirms you are still on the right route before the next one.

      +

      Jamie: Before we leave Navigating Explore with a screen reader, what is the practical point?

      +

      Alex: First, each repo entry has a heading (repo name as a link), language badge, star count, and description. Treat it like a recipe: do not add the next ingredient until the previous one is actually in the bowl.

      -

      Jamie: Let's pause on 3. The Ecosystem: 55 Agents, 3 Teams, 5 Platforms. What should a learner take away from it?

      -

      Alex: This is where 3. The Ecosystem: 55 Agents, 3 Teams, 5 Platforms becomes real: accessibility Agents is an ecosystem of 55 specialized agents organized into three teams, each addressing a different dimension of accessible software development. That matters in practice: Browse all three teams below, then choose the agents that match your current skills and interests.

      -

      Alex: Keep the teaching thread moving. Keep the learner anchored in Team 1: Accessibility (26 agents). These agents audit, fix, and enforce accessibility across web, document, and mobile platforms.

      -

      Jamie: Let's pause on Team 2: GitHub Workflow (12 agents). What should a learner take away from it?

      -

      Alex: The reason Team 2: GitHub Workflow (12 agents) matters is that these agents automate GitHub operations - issue triage, PR review, contribution analytics, and repository management.

      +

      Jamie: Let's pause on 6. Trending -- What's Popular Right Now. What should a learner take away from it?

      +

      Alex: Here is the plain-English version of 6. Trending -- What's Popular Right Now. GitHub Trending at github.com/trending shows repositories gaining the most stars over a time period. Put another way, it's one of the best places to discover new tools before everyone else knows about them.

      +

      Alex: Keep the teaching thread moving. This is where Filtering trending becomes real: use the dropdowns at the top of the page to filter.

      +

      Jamie: Let's pause on Trending developers. What should a learner take away from it?

      +

      Alex: Keep the learner anchored in Trending developers. Switch to github.com/trending/developers to see which developers are gaining the most followers -- another great way to find people to follow.

      -

      Alex: Keep the teaching thread moving. Start with Team 3: Developer Tools (6 agents): These agents support accessible application development across desktop and cross-platform frameworks. Think of it like entering a new building: first you find the lobby, then the room, then the door you actually need.

      -

      Jamie: Let's pause on Beyond Agents: The Supporting Ecosystem. What should a learner take away from it?

      -

      Alex: Here is the plain-English version of Beyond Agents: The Supporting Ecosystem. The 55 agents are backed by additional resources in the repository.

      -

      Jamie: Let's pause on Hook-Based Enforcement (Claude Code). What should a learner take away from it?

      -

      Alex: This is where Hook-Based Enforcement (Claude Code) becomes real: on Claude Code, Accessibility Agents includes a hook system that enforces accessibility standards automatically. That matters in practice: This means accessibility enforcement happens whether or not the developer remembers to ask for it.

      -

      Alex: First, proactive detection hook - scans every file edit for accessibility regressions before they are committed. Then, edit gate hook - blocks commits that introduce WCAG violations until they are fixed. After that, session marker hook - tracks which accessibility checks have run during the current session. It is a checklist, but a meaningful one: every item creates evidence that the next step is safe.

      +

      Jamie: Before we leave GitHub CLI, what is the practical point?

      +

      Alex: Treat examples as spoken recipes, not decorations. You may hear something like Trending repos aren't in the official API, but you can get recently starred popular repos:; gh search repos --sort stars --order desc --limit 20 --language markdown; Trending in a specific language; gh search repos --sort stars --order desc --limit 20. Read the command, understand what it changes, then run it only when the repository state matches the lesson.

      +

      Jamie: Let's pause on 7. Topics -- Finding Projects by Category. What should a learner take away from it?

      +

      Alex: Start with 7. Topics -- Finding Projects by Category: Every repository can be tagged with topics -- keywords like accessibility, screen-reader, wcag, python, machine-learning. The next useful detail is this: Topics are how maintainers categorise their work so others can discover it.

      +

      Alex: Keep the teaching thread moving. Here is the plain-English version of Browsing topics. Click any topic tag on a repository page to see all repos tagged with that topic.

      -

      Jamie: Let's pause on What Would You Build? What should a learner take away from it?

      -

      Alex: Keep the learner anchored in What Would You Build? This is the question that matters most. This is the part to say slowly: The 55 agents that exist today were built by contributors who saw a gap and filled it.

      -

      Alex: The practical takeaway is this. "Why is there no agent for [framework] accessibility patterns?". "I spend 30 minutes on [task] every week - could an agent do the repetitive part?". "This agent is good but it misses [specific edge case] - I could improve those instructions". "Mobile native accessibility testing has no agent coverage yet - I could start one".

      -

      Jamie: Let's pause on The contribution paths are. What should a learner take away from it?

      -

      Alex: The reason The contribution paths are matters is that see the Accessibility Agents CONTRIBUTING guide for detailed instructions on each path. The interface gets friendlier when it stops being a wall of controls and starts being a set of named places.

      -

      Alex: First, report an agent gap - file an issue describing what is missing and why it matters. Then, improve existing agent instructions - make an agent smarter about edge cases it misses. After that, add framework-specific patterns - teach agents about React, Vue, Angular, Svelte, or other framework accessibility patterns. Finally, fix installer issues - improve the one-liner scripts for different OS configurations. The rhythm is simple: orient, act, verify, then continue.

      -

      Jamie: Before we leave The contribution paths are, what is the practical point?

      -

      Alex: First, write documentation - help others understand how to use and contribute to agents. Think of it as a rail line: each stop confirms you are still on the right route before the next one.

      -

      Jamie: Let's pause on Roadmap: What Is Coming Next. What should a learner take away from it?

      -

      Alex: Start with Roadmap: What Is Coming Next: Your contribution could be the next item that ships. The next useful detail is this: Every agent started as one person's idea and one pull request.

      -

      Alex: The practical takeaway is this. Mobile native agents - agents specialized for iOS (VoiceOver) and Android (TalkBack) native app accessibility. Anthropic Connectors listing - making agents discoverable through the Anthropic marketplace. veraPDF integration - automated PDF/UA validation for the PDF accessibility agent. Document remediation agents - agents that fix accessibility issues in documents, not just find them.

      +

      Jamie: What is the teaching move inside GitHub CLI?

      +

      Alex: Treat examples as spoken recipes, not decorations. You may hear something like Search for repos with a specific topic; gh search repos --topic accessibility --limit 20; gh search repos --topic screen-reader --stars " 50"; Add a topic to your own repository; gh api repos/owner/repo/topics --method PUT --field names[]="accessibility". Read the command, understand what it changes, then run it only when the repository state matches the lesson.

      +

      Alex: Keep the teaching thread moving. Keep the learner anchored in 8. GitHub Lists -- Organizing Your Stars. Lists let you group your starred repositories into named collections -- like playlists for code. This is the part to say slowly: Instead of one big pile of stars, you can have "Accessibility Tools," "Learning Resources," "Projects I Contribute To," etc. A good GitHub workflow is like a well-run meeting: everyone knows the topic, the next action, and who has the floor.

      +

      Jamie: Let's pause on Creating a list. What should a learner take away from it?

      +

      Alex: Start with Creating a list. There is something to understand, something to try, and something that proves the try worked.

      +

      Alex: First, go to your stars: github.com/username?tab=stars. Then, select "Create list" (top right of the stars page). After that, give it a name and optional description. Finally, select "Create". The rhythm is simple: orient, act, verify, then continue.

      +

      Jamie: Before we leave Creating a list, what is the practical point?

      +

      Alex: First, on a repo page, click the dropdown arrow next to the Star button. Then, select "Create a list" or add to an existing list. Think of it as a rail line: each stop confirms you are still on the right route before the next one.

      -

      Alex: Keep the teaching thread moving. Start with Learning Cards: The Agent Ecosystem. There is something to understand, something to try, and something that proves the try worked.

      -

      Alex: The practical takeaway is this. The three team tables use standard Markdown table format -- navigate with T (NVDA/JAWS) to jump between tables, then Arrow keys to read cells. Agent names start with @ -- type @ followed by the agent name in Copilot Chat to invoke it (e.g., @daily-briefing). Use Ctrl+Shift+O (symbol outline) in any agent file to navigate between its YAML frontmatter sections (Purpose, Responsibilities, Guardrails). The agent tables are dense -- use Ctrl+= to increase font size or open the file in Markdown Preview (Ctrl+Shift+V) for cleaner rendering. Each team has a distinct table: Team 1 (Accessibility, 26 agents), Team 2 (GitHub Workflow, 15 agents), Team 3 (Developer Tools, 14 agents). Agent files in.github/agents/ have descriptive filenames that match the @agent-name -- browse them in the Explorer to find specific agents.

      -

      Jamie: Let's pause on 4. Agents in Detail - Hands-On Reference. What should a learner take away from it?

      -

      Alex: This is where 4. Agents in Detail - Hands-On Reference becomes real: this section walks through several agents in depth so you can see how they work, what they produce, and how to evaluate their output. That matters in practice: These examples use GitHub Workflow agents because they build directly on Day 1 skills - but the same patterns apply to every agent in the ecosystem.

      -

      Alex: Keep the teaching thread moving. Keep the learner anchored in Two Types of Agents. Before diving in, it helps to know that custom agents fall into two categories - this distinction affects what tool permissions they need and what they can do. This is the part to say slowly: Informational agents search, analyze, and report. A good GitHub workflow is like a well-run meeting: everyone knows the topic, the next action, and who has the floor.

      +

      Alex: Keep the teaching thread moving. Start with Adding repos to lists. There is something to understand, something to try, and something that proves the try worked.

      +

      Alex: The practical takeaway is this. From any repo page: Star dropdown → check the list name. From your stars page: click the list icon on any starred repo row.

      +

      Jamie: Let's pause on Viewing and sharing lists. What should a learner take away from it?

      +

      Alex: Here is the plain-English version of Viewing and sharing lists. Your lists are public at github.com/username?tab=stars -- anyone can browse them. Put another way, this is useful for sharing curated resources with your community.

      +

      Jamie: If someone only remembers one thing from GitHub CLI, what should it be?

      +

      Alex: Treat examples as spoken recipes, not decorations. You may hear something like Lists are managed through the GitHub web interface only; You can view stars via CLI:; gh api user/starred --jq '.[] {name.full name, description.description}' head -20. Read the command, understand what it changes, then run it only when the repository state matches the lesson.

      -

      Jamie: Let's pause on Agent 1: @daily-briefing - Morning Briefing. What should a learner take away from it?

      -

      Alex: The reason Agent 1: @daily-briefing - Morning Briefing matters is that file.github/agents/daily-briefing.agent.md. That gives the learner a simple foothold: before you run this agent: You should have manually navigated a repository's Issues tab, read your GitHub Notifications page, understood what a pull request waiting for review looks like, and know the difference between subscribed and participating.

      -

      Alex: Keep the teaching thread moving. Start with What it does: Sweeps every repository you have access to and builds a prioritized dashboard.

      -

      Alex: The practical takeaway is this. Issues opened in the last 24 hours. Pull requests waiting for your review. CI failures on your branches. Security and Dependabot alerts. Community reactions to your recent comments.

      -

      Jamie: What stays the same when the tool changes?

      -

      Alex: Here is the plain-English version of Example commands. The briefing output uses heading level 2 for each section. Put another way, use H key (NVDA/JAWS virtual mode) or VO+Command+H (VoiceOver) to jump between: Open Issues, Review Requests, CI Status, Security Alerts, Community Activity.

      +

      Jamie: Let's pause on 9. Finding Accessible and Inclusive Projects. What should a learner take away from it?

      +

      Alex: Keep the learner anchored in 9. Finding Accessible and Inclusive Projects. If you're specifically looking for projects that welcome contributors with disabilities, or that focus on accessibility work, here are the best ways to find them.

      +

      Jamie: Let's pause on Search strategies. What should a learner take away from it?

      +

      Alex: Start with Search strategies. There is something to understand, something to try, and something that proves the try worked.

      +

      Alex: The practical takeaway is this. github.com/topics/accessibility. github.com/topics/wcag. github.com/topics/screen-reader.

      +

      Alex: Treat examples as spoken recipes, not decorations. You may hear something like Search for accessibility-focused repos; gh search repos "accessibility" --topic a11y --stars " 100"; Find repos with good first issues in accessibility; gh search issues "accessibility" --label "good first issue" --state open; Find issues tagged both. Read the command, understand what it changes, then run it only when the repository state matches the lesson.

      +

      Jamie: Let's pause on Organisations to follow. What should a learner take away from it?

      +

      Alex: Start with Organisations to follow: GitHub organisations are collections of repos grouped by a team or company. The next useful detail is this: You can follow an org to get notified of their public activity.

      +

      Alex: The practical takeaway is this. github.com/Community-Access -- the organisation behind this workshop. Search for org:github accessibility to find GitHub's own accessibility work. Many assistive technology companies have open source components on GitHub -- search for your AT provider.

      -

      Alex: Keep the teaching thread moving. This is where Agent 2: @issue-tracker - Issue Management becomes real: file.github/agents/issue-tracker.agent.md. That matters in practice: Before you run this agent: You should have filed at least one issue using the full manual process - writing a title, description, and reproduction steps; applying labels and a milestone; and reading at least five existing issues to understand what a. The workshop is closer to rehearsal than lecture. You hear the move, try the move, and then check what changed.

      -

      Jamie: Let's pause on What it does. What should a learner take away from it?

      -

      Alex: Keep the learner anchored in What it does. Finds, prioritizes, and helps you manage issues across all your repositories.

      -

      Alex: The practical takeaway is this. Cross-repository priority scoring with community sentiment. Batch-reply capability (draft replies to multiple issues at once). Saved search support. Release-awareness (flags issues that affect upcoming releases).

      -

      Alex: Keep the teaching thread moving. The reason Example commands matters is that the agent can draft a reply. That gives the learner a simple foothold: you review the tone against the Culture & Etiquette guide before posting.

      +

      Alex: Keep the teaching thread moving. Here is the plain-English version of Looking at who your community follows. If you follow someone doing accessibility work, browse their stars and their following list -- this is one of the fastest ways to discover the accessibility community on GitHub. It is like learning a transit route. The names of the stops matter because they tell you whether you are still going the right direction.

      +

      Jamie: Let's pause on 10. Building Your Own Presence. What should a learner take away from it?

      +

      Alex: This is where 10. Building Your Own Presence becomes real: being visible on GitHub matters when you want to collaborate with others, get hired, or establish yourself as a contributor.

      +

      Alex: Keep the teaching thread moving. Keep the learner anchored in Your contribution graph. The green grid on your profile shows your public contribution activity over the past year. This is the part to say slowly: Contributions to private repos only appear as grey squares unless the repo is made public later.

      +

      Alex: The practical takeaway is this. Push commits to a public repo. Open, comment on, or close issues or PRs in a public repo. Review a PR in a public repo.

      -

      Jamie: What should they understand before typing anything?

      -

      Alex: Start with Output example. There is something to understand, something to try, and something that proves the try worked.

      -

      Alex: Treat examples as spoken recipes, not decorations. You may hear something like Open Issues Labeled "good-first-issue"; High Priority; - 45 [accessibility-agents] Add NVDA-specific navigation tips (3 comments, opened 5 days ago); - Priority Score: 8/10 (high community interest, clear scope, no assignee); - Recommended for: First-time. Read the command, understand what it changes, then run it only when the repository state matches the lesson.

      -

      Alex: Keep the teaching thread moving. Here is the plain-English version of Agent 3: @pr-review - Pull Request Review. File.github/agents/pr-review.agent.md. Put another way, before you run this agent: You should have manually reviewed at least one pull request diff in the GitHub browser interface - navigating the Files Changed tab with your screen reader, reading added and removed lines, leaving at least one inline comment, and. It is like learning a transit route. The names of the stops matter because they tell you whether you are still going the right direction.

      -

      Jamie: Before we leave What it does, what is the practical point?

      -

      Alex: This is where What it does becomes real: generates full review documents for pull requests.

      -

      Alex: The practical takeaway is this. Line-numbered diffs with change maps. Risk assessment (what could break, what is high-impact). Before-and-after snapshots. CI results and test coverage information. Suggested inline review comments with line number references.

      +

      Jamie: Let's pause on Pinning repositories. What should a learner take away from it?

      +

      Alex: The reason Pinning repositories matters is that pin up to 6 repositories (your own or repos you've contributed to) on your profile.

      +

      Alex: First, go to your profile (github.com/username). Then, select "Customize your pins" above the pinned repos section. After that, check up to 6 repos to pin -- prioritise your best work and most active contributions. The rhythm is simple: orient, act, verify, then continue.

      +

      Alex: Keep the teaching thread moving. Start with Your profile README: Create a special repository named exactly the same as your username (github.com/username/username) and its README.md will appear at the top of your profile page. The next useful detail is this: This is your chance to introduce yourself, list your skills, and share what you're working on. Think of it like entering a new building: first you find the lobby, then the room, then the door you actually need.

      +

      Jamie: Let's pause on Activity tips. What should a learner take away from it?

      +

      Alex: Start with Activity tips. There is something to understand, something to try, and something that proves the try worked.

      +

      Alex: The practical takeaway is this. Comment thoughtfully on issues -- even "I can reproduce this on Windows 11 with NVDA" is a valued contribution that shows on your profile. Star generously -- it signals your interests and others see it in their feeds. Follow people in your area -- they often follow back, growing your network organically.

      -

      Alex: Keep the teaching thread moving. Keep the learner anchored in Example commands. Critical rule: Read the agent's review. This is the part to say slowly: The agent produces a starting point - it does not know the project's history, the contributor's background, or the community's implicit standards the way you do.

      -

      Jamie: What is the safe way to learn from that example?

      -

      Alex: Treat examples as spoken recipes, not decorations. You may hear something like PR Review: 14 - Improve screen reader navigation guide; Summary; This PR adds 3 new sections to the screen reader navigation guide and updates 2 existing sections with NVDA-specific keyboard shortcuts.; Files Changed: 1; Lines Added: 127; Lines Removed: 18. Read the command, understand what it changes, then run it only when the repository state matches the lesson.

      -

      Alex: Keep the teaching thread moving. Start with Agent 4: @analytics - Team Analytics: File.github/agents/analytics.agent.md. The next useful detail is this: Before you run this agent: You should have explored the Insights tab of at least one repository - looked at the contribution graph, understood what commit frequency means, and thought about what "high-churn files" implies for a project's stability. Think of it like entering a new building: first you find the lobby, then the room, then the door you actually need.

      +

      Jamie: Let's pause on 11. The GitHub CLI for Social Features. What should a learner take away from it?

      +

      Alex: Start with 11. The GitHub CLI for Social Features. There is something to understand, something to try, and something that proves the try worked.

      +

      Alex: Treat examples as spoken recipes, not decorations. You may hear something like --- Following ---; gh api user/following/username --method PUT Follow someone; gh api user/following/username --method DELETE Unfollow; gh api user/following --jq '.[].login' List who you follow; gh api user/followers --jq '.[].login' List your followers; ---. Read the command, understand what it changes, then run it only when the repository state matches the lesson.

      +

      Jamie: Let's pause on Following a user. What should a learner take away from it?

      +

      Alex: Start with Following a user. There is something to understand, something to try, and something that proves the try worked.

      +

      Alex: First, navigate to github.com/username. Then, press H to jump through headings to find the user's name at the top. After that, tab forward -- the Follow/Following button is within the first few interactive elements after the avatar/bio area. Finally, press Enter or Space to follow; the button label updates to "Following [username]". It is like walking a hallway with named doors: read the sign, enter the right room, then confirm where you landed.

      +

      Jamie: Let's pause on Starring a repository. What should a learner take away from it?

      +

      Alex: Start with Starring a repository. There is something to understand, something to try, and something that proves the try worked.

      +

      Alex: First, navigate to any repository page. Then, the Star button is in the repository header, near the Fork button. After that, press B (NVDA/JAWS) to navigate by button, or Tab through the header. Finally, the button is announced as "Star this repository" or "Unstar this repository". The rhythm is simple: orient, act, verify, then continue.

      +

      Jamie: Before we leave Starring a repository, what is the practical point?

      +

      Alex: First, after starring, the button label changes and a count updates. Think of it as a rail line: each stop confirms you are still on the right route before the next one.

      -

      Jamie: What is the teaching move inside What it does?

      -

      Alex: Here is the plain-English version of What it does. Surfaces team contribution patterns, velocity metrics, and bottleneck detection.

      -

      Alex: The practical takeaway is this. Contribution velocity over time. Review turnaround time by reviewer. Code hotspot detection (files with the most churn). Workload distribution across contributors.

      -

      Alex: Keep the teaching thread moving. This is where Example commands becomes real: accessibility use case: After Day 2's contribution wave, run @analytics team velocity in accessibility-agents today to see the hackathon's collective output. That matters in practice: A moment of real-time team celebration.

      -

      Jamie: Let's pause on Agent 5: @insiders-a11y-tracker - Accessibility Change Monitoring. What should a learner take away from it?

      -

      Alex: Keep the learner anchored in Agent 5: @insiders-a11y-tracker - Accessibility Change Monitoring. File.github/agents/insiders-a11y-tracker.agent.md. This is the part to say slowly: Before you run this agent: You should have filed at least one accessibility bug report using the workshop's issue template, applied a WCAG label to an issue, and manually reviewed a Markdown file for heading hierarchy - knowing what H1 means, what H2 means,.

      +

      Jamie: Let's pause on Browsing your stars. What should a learner take away from it?

      +

      Alex: Start with Browsing your stars. There is something to understand, something to try, and something that proves the try worked.

      +

      Alex: First, go to github.com/username?tab=stars. Then, jump to main landmark to skip navigation. After that, each starred repo is a heading (H3) with a link -- navigate with H or 3. Finally, below each heading: description text, language, star count, and list controls. Think of it as a rail line: each stop confirms you are still on the right route before the next one.

      +

      Jamie: Let's pause on Exploring topics. What should a learner take away from it?

      +

      Alex: Start with Exploring topics. There is something to understand, something to try, and something that proves the try worked.

      +

      Alex: First, go to github.com/topics/accessibility (or any topic). Then, jump to main landmark. After that, repos are listed as article regions with H3 headings. Finally, each entry has: repo name (link), owner, description, language, star count, and a Star button. Treat it like a recipe: do not add the next ingredient until the previous one is actually in the bowl.

      +

      Jamie: Let's pause on GitHub Explore and Trending. What should a learner take away from it?

      +

      Alex: This is where GitHub Explore and Trending becomes real: next: Appendix U: Discussions and Gists Back: Appendix S: Releases and Insights Teaching chapter: Chapter 08: Open Source Culture.

      +

      Alex: First, go to github.com/explore or github.com/trending. Then, use H to navigate between sections and repo entries. After that, trending page has language and time period filter dropdowns near the top -- Tab to find them. Finally, each trending repo row has: rank position, repo name (link), description, star count, and "Stars today" count. It is a checklist, but a meaningful one: every item creates evidence that the next step is safe.

      -

      Alex: Keep the teaching thread moving. The reason What it does matters is that monitors accessibility-sensitive changes across configured repositories. The interface gets friendlier when it stops being a wall of controls and starts being a set of named places.

      -

      Alex: The practical takeaway is this. WCAG/ARIA cross-referenced change tracking. Flags changes to keyboard navigation, ARIA attributes, focus management, color usage. Monitors for heading hierarchy violations in Markdown. Tracks link text quality (flags bare URLs, non-descriptive labels).

      -

      Jamie: What should someone listen for when a lesson offers more than one tool path?

      -

      Alex: Start with Example commands: Day 2 workflow: Run this before submitting any PR. The next useful detail is this: If the agent flags an issue, fix it before requesting review - not after.

      -

      Alex: Keep the teaching thread moving. Here is the plain-English version of Agent 6: @template-builder - Interactive Issue Template Wizard. File.github/agents/template-builder.agent.md. Put another way, before you run this agent: You should have read Issue Templates thoroughly - understanding YAML field types, creating a template manually (Exercise B), and designing your own template (Exercise D).

      +

      Jamie: What should people carry with them after this?

      +

      Alex: Carry the map. Know what page or tool you are in, know which action you are taking, and know what confirmation should follow. If the confirmation is missing, pause. That pause is not wasted time; it is professional judgment.

      +

      Jamie: That is a better way to say it than just follow the steps.

      +

      Alex: Right. Steps matter, but understanding wins. That is episode 35. Next in the series is episode 36, where we keep building the same contributor muscles.

      +
      + +
      +

      65. Episode 36: Organizations and Templates

      +

      GitHub Organizations, repository templates, visibility, and archiving.

      +

      Based on: Appendix T: Organizations and Templates

      +

      Audio and transcript are being regenerated for this episode.

      +
      +Read Transcript - Episode 36: Organizations and Templates + +

      Transcript

      +

      Alex: Welcome to Git Going with GitHub, episode 36: Organizations and Templates. I am Alex. Today we are going to make Organizations and Templates something you can explain, practice, and recover from when the interface surprises you.

      +

      Jamie: And I am Jamie. I will be the voice of the learner who is willing to ask, what is this for, where am I, and how do I know I did it right?

      -

      Jamie: If someone only remembers one thing from What it does, what should it be?

      -

      Alex: This is where What it does becomes real: an interactive wizard that guides you through building GitHub issue templates step-by-step using VS Code's Ask Questions feature. That matters in practice: Instead of writing YAML syntax, answer simple questions and the agent generates production-ready templates.

      -

      Alex: Keep the teaching thread moving. Keep the learner anchored in Example commands. Manual YAML template creation takes 15-20 minutes and is error-prone. This is the part to say slowly: The Template Builder generates correct, tested templates in 2-3 minutes via guided questions. A good GitHub workflow is like a well-run meeting: everyone knows the topic, the next action, and who has the floor.

      -

      Jamie: What is the common workflow underneath the different interfaces?

      -

      Alex: The reason 5. Slash Commands and Prompts matters is that the repository includes 54+ slash commands defined as.prompt.md files in.github/prompts/. That gives the learner a simple foothold: type / in Copilot Chat to see the full command menu.

      +

      Alex: The big idea today: GitHub Organizations, repository templates, visibility, and archiving. We will name the concept, explain why it matters, practice the move, and point out the checks that tell you the work is real.

      +

      Jamie: So the episode should work even if someone has not read the chapter yet.

      +

      Alex: Exactly. The transcript has to stand on its own. It can point toward practice, but it should teach the concept right here in the conversation.

      -

      Alex: Keep the teaching thread moving. Start with Workshop Slash Command Quick Reference: The commands listed below are the ones most relevant to this workshop. The next useful detail is this: The full repository contains 54+ commands covering accessibility auditing, document scanning, framework-specific checks, and more.

      -

      Jamie: How do we make tool choice feel like access, not pressure?

      -

      Alex: Here is the plain-English version of Reading Slash Command Definitions. Each /command corresponds to a.prompt.md file in.github/prompts/. Put another way, open any of them in VS Code to read what instructions it gives Copilot.

      -

      Alex: Keep the teaching thread moving. This is where Example: /a11y-update becomes real: file.github/prompts/a11y-update.prompt.md. That matters in practice: This is how you learn to write your own. The workshop is closer to rehearsal than lecture. You hear the move, try the move, and then check what changed.

      +

      Jamie: Okay, set the room for us. What are we walking into?

      +

      Alex: Start with Building Your Community Presence on GitHub: This appendix covers three community-facing GitHub features: your profile README (how the world sees you), GitHub Sponsors (financially supporting the people whose work you depend on), and GitHub Wikis (community-editable documentation inside a repository).

      +

      Alex: A solid pull request habit is to separate three questions: what changed, why it changed, and what still needs review. That keeps the conversation useful instead of noisy.

      +

      Alex: The next layer is this. Start with Learning Cards: Profiles, Sponsors, and Wikis. There is something to understand, something to try, and something that proves the try worked.

      +

      Alex: The practical anchors are these. Your profile README is announced as regular page content when someone visits your profile -- use headings for structure so visitors can navigate with H. The Sponsor button on a profile or repo is a standard button element -- press B to cycle through buttons until you hear "Sponsor". Wiki pages are read in browse mode like any other GitHub Markdown page -- use heading navigation to jump between sections. Profile READMEs respect GitHub's dark and light themes -- test yours in both modes to confirm text remains readable. The Sponsor button uses a heart icon with a pink/magenta accent -- look near the repo name or profile photo area. Wiki sidebar navigation appears on the right side of the page with links to all wiki pages.

      +

      Jamie: What is the one idea that makes the next few steps less mysterious?

      +

      Alex: This is where The Special Profile README becomes real: GitHub has a hidden feature: if you create a repository named exactly your-username/your-username (e.g., janesmith/janesmith), the README in that repo appears on your GitHub profile page. That matters in practice: It's a custom introduction visible to anyone who visits your profile.

      -

      Jamie: How should a learner choose a tool without feeling judged by the choice?

      -

      Alex: Start with Learning Cards: Slash Commands and Prompts. There is something to understand, something to try, and something that proves the try worked.

      -

      Alex: The practical takeaway is this. Type / in Copilot Chat to see all available slash commands -- your screen reader announces each command name as you arrow through the list. Slash commands are defined in.github/prompts/ as.prompt.md files -- open them in the Explorer to read what each command does before using it. Create your own command by copying an existing.prompt.md file, renaming it, and editing the instructions -- no code required. The / command menu appears as a dropdown list in Copilot Chat -- it scales with VS Code's font and zoom settings. Each command has a short description visible in the dropdown; use Ctrl+= to zoom if the text is too small. Open the.prompt.md file in the editor to read the full command definition at your preferred zoom level.

      -

      Alex: Keep the teaching thread moving. The reason 6. Contributing to the Ecosystem matters is that the 55 Accessibility Agents and 54+ slash commands are starting points. That gives the learner a simple foothold: the.agent.md format is open - you can create your own agents for any repeatable workflow, and contribute them back to the project.

      -

      Jamie: Let's pause on Two Types of Custom Agents. What should a learner take away from it?

      -

      Alex: Start with Two Types of Custom Agents: Informational agents - conversational; search, analyze, and present results. The next useful detail is this: Task-oriented agents - active; edit files, run commands, submit PRs.

      -

      Alex: The practical takeaway is this. Perform GitHub searches with predefined scopes and filters. Present results in specific structured formats. Query GitHub API tools to answer questions. Execute external tools (linters, test suites, axe-core).

      +

      Jamie: Turn that into a path someone can follow.

      +

      Alex: Start with Creating Your Profile README. There is something to understand, something to try, and something that proves the try worked.

      +

      Alex: First, create a new repository. Then, name it exactly your-username (match your GitHub username exactly, case-sensitive). After that, make it public. Finally, initialize with a README. It is like walking a hallway with named doors: read the sign, enter the right room, then confirm where you landed.

      +

      Jamie: What is the ordered workflow?

      +

      Alex: First, edit the README with whatever you want to show on your profile. The rhythm is simple: orient, act, verify, then continue.

      +

      Jamie: What would you say to someone who is already bracing for this to be too much?

      +

      Alex: Start with What to include. There is something to understand, something to try, and something that proves the try worked.

      +

      Alex: The parts worth keeping in working memory are these. Introduction: Who you are, what you work on. Current focus: What projects or technologies you're learning. Skills: Languages, frameworks, tools (optional). How to reach you: Email, LinkedIn, personal site. Fun facts: Hobbies, interests (optional-keeps it human).

      +

      Alex: The useful habit is simple: orient first, act second, verify third. That pause before acting is part of the work.

      +

      Jamie: How do you keep commands from becoming magic words?

      +

      Alex: Start with Example profile README. There is something to understand, something to try, and something that proves the try worked.

      +

      Alex: Treat examples as spoken recipes, not decorations. You may hear something like Hi, I'm Jane Smith; I'm an accessibility advocate and open source contributor focused on making the web more inclusive.; Current focus; - Contributing to NVDA documentation; - Building accessible React components; - Learning TypeScript; Skills; - JavaScript,. Read the command, understand what it changes, then run it only when the repository state matches the lesson.

      -

      Alex: Keep the teaching thread moving. Here is the plain-English version of Agent File Structure. See also: Appendix L: Agents Reference has the complete agent.md format specification and examples. Put another way, every.agent.md file has two parts: YAML frontmatter (metadata) and a system prompt (markdown body). It is like learning a transit route. The names of the stops matter because they tell you whether you are still going the right direction.

      -

      Jamie: Let's pause on Frontmatter fields. What should a learner take away from it?

      -

      Alex: This is where Frontmatter fields becomes real: restricting tool access is a security best practice - only grant what the agent actually needs.

      -

      Alex: Keep the teaching thread moving. Keep the learner anchored in Example: Informational Agent - @insiders-a11y-tracker. This agent monitors VS Code Insiders releases for accessibility improvements. This is the part to say slowly: It searches the microsoft/vscode repository using predefined GitHub query syntax, so you never have to remember the exact filter parameters.

      +

      Jamie: If I am listening before the workshop starts, what should settle in my mind first?

      +

      Alex: Here is the plain-English version of Profile README Best Practices. Keep it concise - visitors skim, not read Update occasionally - a README from 2019 looks stale Be authentic - people connect with real humans, not buzzwords Include links - make it easy to learn more or get in touch. Put another way, avoid excessive badges - 50 skill badges is visual clutter and screen reader noise Skip auto-generated stats - "commits per day" widgets are often inaccessible Don't overthink it - a simple paragraph is better than nothing.

      +

      Alex: This is where the talk moves from concept to action. Start with Screen Reader Considerations. There is something to understand, something to try, and something that proves the try worked.

      +

      Alex: The room should hear these as checkpoints. Use headings ( ) for structure. Provide alt text for any images. Avoid ASCII art - screen readers read it character by character (annoying). Test your README with a screen reader before publishing.

      +

      Alex: A solid navigation habit is to prove where you are before activating controls. Headings, landmarks, and the address bar are not trivia; they are your map.

      +

      Jamie: Where do you want a learner to place their attention here?

      +

      Alex: Start with Pinned repositories (up to 6). There is something to understand, something to try, and something that proves the try worked.

      +

      Alex: These are the details that keep the idea from floating away. Highlight your best work on your profile. Navigate to your profile → Select "Customize your pins". Choose which repos appear first.

      -

      Jamie: Let's pause on Use it. What should a learner take away from it?

      -

      Alex: The reason Use it matters is that prerequisite: GitHub MCP server installed (github.com/github/github-mcp-server).

      -

      Alex: First, select @insiders-a11y-tracker from the agent picker. Then, ask: what shipped this month? or any keyboard navigation improvements in January? After that, the agent searches with repo:microsoft/vscode is:closed milestone:"[Month] [Year]" label:accessibility label:insiders-released and returns formatted results. The rhythm is simple: orient, act, verify, then continue.

      -

      Alex: Keep the teaching thread moving. Start with Example: Task-Oriented Agent - The Markdown Accessibility Assistant: The GitHub Accessibility team published a complete walkthrough for building a Markdown Accessibility Assistant - a task-oriented agent that reviews Markdown files for accessibility issues and makes direct fixes. The next useful detail is this: This agent is the automated version of the accessibility review skills you built during Day 1. Think of it like entering a new building: first you find the lobby, then the room, then the door you actually need.

      -

      Alex: The practical takeaway is this. Runs markdownlint-cli2 to catch structural problems (heading skips, bare URLs, missing blank lines). Reviews link text for descriptiveness. Flags missing or inadequate alt text and waits for your approval before changing it (alt text requires human judgment). Fixes heading hierarchy, list structure, and bare URL formatting directly.

      -

      Jamie: Let's pause on Key Pattern: Tiered Decision-Making. What should a learner take away from it?

      -

      Alex: Here is the plain-English version of Key Pattern: Tiered Decision-Making. This tiered approach - automate what can be objectively evaluated, flag what needs human judgment - is the right model for any accessibility agent. Put another way, it maximizes the agent's value while keeping humans in control of decisions that require context.

      +

      Alex: Before the learner moves on. Start with Contribution graph. There is something to understand, something to try, and something that proves the try worked.

      +

      Alex: That becomes easier when you listen for these cues. Shows your GitHub activity over the past year. Green squares indicate days with commits, PRs, issues, etc. Cannot be customized but reflects consistent contribution.

      +

      Jamie: Give me the version that sounds like an instructor, not a manual.

      +

      Alex: Start with Status. There is something to understand, something to try, and something that proves the try worked.

      +

      Alex: A few details make that real. Set a temporary status message (e.g., "On vacation until March 15"). Navigate to your profile → Select the smile icon → Set status.

      +

      Alex: Hold that next to this. Here is the plain-English version of What Is GitHub Sponsors? GitHub Sponsors lets you financially support developers and projects you depend on.

      -

      Alex: Keep the teaching thread moving. Start with Required Prerequisites for the Markdown Accessibility Assistant. There is something to understand, something to try, and something that proves the try worked.

      -

      Alex: The practical takeaway is this. GitHub MCP server installed and configured (github.com/github/github-mcp-server). Node.js installed (for npx markdownlint-cli2).

      -

      Jamie: Let's pause on From VS Code. What should a learner take away from it?

      -

      Alex: Start with From VS Code. There is something to understand, something to try, and something that proves the try worked.

      -

      Alex: First, open Copilot Chat (Ctrl+Shift+I / Cmd+Shift+I on macOS). Then, in the Chat input toolbar, select the Set Agent button. After that, select your custom agent from the agent picker. Finally, type your request - the agent executes in your local workspace. It is like walking a hallway with named doors: read the sign, enter the right room, then confirm where you landed.

      -

      Jamie: Let's pause on From GitHub.com (Task mode). What should a learner take away from it?

      -

      Alex: Start with From GitHub.com (Task mode). There is something to understand, something to try, and something that proves the try worked.

      -

      Alex: First, open Copilot Chat on GitHub.com. Then, select Task from the mode picker. After that, optionally select a custom agent from the agent picker. Finally, submit your request - the agent can create a PR automatically. The rhythm is simple: orient, act, verify, then continue.

      +

      Jamie: Let's pause on How it works. What should a learner take away from it?

      +

      Alex: Start with How it works. There is something to understand, something to try, and something that proves the try worked.

      +

      Alex: That shows up in the workshop in a few specific ways. Developers/projects create a Sponsors profile. You choose a monthly sponsorship tier ($5, $10, $25/month, etc.). Your payment goes directly to the developer (GitHub takes no fees).

      +

      Alex: That connects to another useful point. Start with Why Sponsor? There is something to understand, something to try, and something that proves the try worked.

      +

      Alex: For a learner, the useful signals are these. Sustainability: Many open source maintainers volunteer their time. Sponsorships help them keep projects alive. Gratitude: If a project saved you hours of work, sponsorship is a way to say thanks. Priority support: Some maintainers offer sponsor-only Discord access, early releases, or prioritized bug fixes.

      +

      Jamie: Give me the sequence, because order matters here.

      +

      Alex: Start with How to Sponsor. There is something to understand, something to try, and something that proves the try worked.

      +

      Alex: First, navigate to a user or repository's GitHub page. Then, look for the "Sponsor" button (heart icon). After that, choose a tier or custom amount. Finally, select payment method (credit card or PayPal). The rhythm is simple: orient, act, verify, then continue.

      +

      Jamie: How would you walk the room through that step by step?

      +

      Alex: First, GitHub sends a receipt; your sponsorship appears on your profile (optionally publicly). Think of it as a rail line: each stop confirms you are still on the right route before the next one.

      -

      Jamie: Let's pause on From an issue (Issue Assignment). What should a learner take away from it?

      -

      Alex: Start with From an issue (Issue Assignment). There is something to understand, something to try, and something that proves the try worked.

      -

      Alex: First, open any issue → Assignees → assign Copilot. Then, in the dialog, optionally select a custom agent. After that, select Assign - Copilot creates a branch, makes changes, and opens a PR. Think of it as a rail line: each stop confirms you are still on the right route before the next one.

      -

      Alex: Keep the teaching thread moving. Here is the plain-English version of Environment Setup for GitHub (Cloud Agents). When agents run on GitHub (not locally), they may need additional tools. Put another way, create a workflow file at.github/workflows/copilot-setup-steps.yml with a single job named copilot-setup-steps.

      -

      Jamie: Let's pause on To Create Your Own Agent. What should a learner take away from it?

      -

      Alex: Start with To Create Your Own Agent. There is something to understand, something to try, and something that proves the try worked.

      -

      Alex: First, create.github/agents/your-agent-name.agent.md. Then, write YAML frontmatter (name, description, tools). After that, write the system prompt - identity, capabilities, domain knowledge, behavioral rules, output format. Finally, save and reload VS Code (Ctrl+Shift+P → "Reload Window"). It is a checklist, but a meaningful one: every item creates evidence that the next step is safe.

      -

      Jamie: Before we leave To Create Your Own Agent, what is the practical point?

      -

      Alex: First, type @your-agent-name in Copilot Chat. It is like walking a hallway with named doors: read the sign, enter the right room, then confirm where you landed.

      +

      Alex: Here is the practical turn. Start with Screen reader navigation. There is something to understand, something to try, and something that proves the try worked.

      +

      Alex: On the ground, that means a few things. The Sponsor button appears near the profile photo or repo name. Press B to cycle through buttons on the page until you hear "Sponsor".

      +

      Jamie: What does the learner do first, second, and then after that?

      +

      Alex: Here is the plain-English version of Can I Receive Sponsorships? If you maintain an open source project or contribute regularly. Put another way, many accessibility advocates successfully use Sponsors to fund their work improving assistive technology and inclusive design.

      +

      Alex: First, navigate to github.com/sponsors. Then, select "Join the waitlist" or "Set up sponsors". After that, connect a payment method (Stripe or bank account). Finally, create sponsor tiers with descriptions. Treat it like a recipe: do not add the next ingredient until the previous one is actually in the bowl.

      +

      Jamie: Let's pause on Can I Receive Sponsorships? What should a learner take away from it?

      +

      Alex: First, promote your Sponsors page to your audience. It is a checklist, but a meaningful one: every item creates evidence that the next step is safe.

      +

      Alex: Keep the thread going. This is where What Is a GitHub Wiki? becomes real: every repository can have a wiki - a space for documentation separate from the code. That matters in practice: It's lightweight and Markdown-based. The workshop is closer to rehearsal than lecture. You hear the move, try the move, and then check what changed.

      -

      Alex: Keep the teaching thread moving. Keep the learner anchored in Exercise: Extend the Template Builder Agent. You've built templates manually (Chapters 15-16) and seen them in action. This is the part to say slowly: Now see how to harness AI to generate templates interactively, and learn to customize agents for your own projects. A good GitHub workflow is like a well-run meeting: everyone knows the topic, the next action, and who has the floor.

      -

      Alex: The practical takeaway is this. Complete Chapters 15-16 (especially Exercise D - designing your own template). VS Code is installed and GitHub Copilot is active. You have forked accessibility-agents to your GitHub account. You have cloned your fork locally: git clone https://github.com/[your-username]/accessibility-agents.git.

      -

      Jamie: Let's pause on Exercise 1: Generate a Template with the Agent. What should a learner take away from it?

      -

      Alex: The reason Exercise 1: Generate a Template with the Agent matters is that your Mission: Use the @template-builder agent to generate an accessibility bug report template interactively. That gives the learner a simple foothold: you'll experience the agent as an end-user and see what production-ready agent output looks like.

      -

      Alex: The practical takeaway is this. Left sidebar showing.github/, docs/, learning-room/, README.md, etc. The status bar at the bottom shows your current git branch (probably main). Alternative: Use menu: View → Copilot Chat. Copilot is now ready to receive instructions.

      -

      Alex: First, open VS Code. Then, file → Open Folder → select your locally cloned accessibility-agents folder. After that, the folder tree appears on the left showing the repository structure. Finally, verify you're in the right place: The folder name should be accessibility-agents at the top of the sidebar. The rhythm is simple: orient, act, verify, then continue.

      -

      Jamie: Before we leave Exercise 1: Generate a Template with the Agent, what is the practical point?

      -

      Alex: First, keyboard shortcut: Press Ctrl+Shift+I (Windows/Linux) or Cmd+Shift+I (macOS). Then, a chat panel opens on the right side of VS Code. After that, at the top, you see "Copilot Chat" and probably a text input at the bottom saying "Ask Copilot.". Finally, click in the chat input box (bottom of Copilot Chat panel). Think of it as a rail line: each stop confirms you are still on the right route before the next one.

      -

      Alex: Treat examples as spoken recipes, not decorations. You may hear something like Q: Template name?; A: Accessibility Bug Report; Q: What's it for?; A: Report screen reader and keyboard navigation issues; Q: First field name?; A: Screen Reader; Q: Field type?; A: dropdown; Q: Dropdown options? (comma-separated); A: NVDA, JAWS, VoiceOver,. Read the command, understand what it changes, then run it only when the repository state matches the lesson.

      -

      Jamie: Let's pause on Exercise 2: Extend the Agent for Your Project. What should a learner take away from it?

      -

      Alex: Start with Exercise 2: Extend the Agent for Your Project: Your Mission: Customize the Template Builder agent to recognize and guide a Security Vulnerability Report template. The next useful detail is this: This teaches you how to tailor agents for project-specific needs.

      -

      Alex: The practical takeaway is this. The file starts with YAML frontmatter (name, description, topics). Below that, sections like " How to Use", " Pre-Built Workflow". Search for the text "Pre-Built Workflow: Guided Accessibility Template".

      -

      Alex: First, in VS Code, navigate to.github/agents/. Then, file: template-builder.agent.md. After that, double-click to open it in the editor. Finally, you see the agent's instructions in Markdown format. Think of it as a rail line: each stop confirms you are still on the right route before the next one.

      -

      Jamie: Before we leave Exercise 2: Extend the Agent for Your Project, what is the practical point?

      -

      Alex: First, use Ctrl+F to open Find. Then, search for: Pre-Built Workflow. After that, press Enter to jump to the first match. Finally, you should land on the "Pre-Built Workflow: Guided Accessibility Template" section. Treat it like a recipe: do not add the next ingredient until the previous one is actually in the bowl.

      +

      Jamie: Let's pause on When to use a wiki. What should a learner take away from it?

      +

      Alex: Start with When to use a wiki. There is something to understand, something to try, and something that proves the try worked.

      +

      Alex: Here is what that changes in practice. Multi-page documentation (tutorials, guides, FAQs). Community-editable docs (wikis can be editable by anyone). Knowledge that doesn't belong in README (too long, too specific).

      +

      Alex: Another way to ground it. Start with When NOT to use a wiki. There is something to understand, something to try, and something that proves the try worked.

      +

      Alex: The practical takeaway is this. Your project already uses GitHub Pages or external docs. Documentation needs to be version-controlled with code (wikis are separate Git repos). You want full control (wikis are less customizable than Pages).

      +

      Jamie: Let's pause on Accessing a Repo's Wiki. What should a learner take away from it?

      +

      Alex: Start with Accessing a Repo's Wiki. There is something to understand, something to try, and something that proves the try worked.

      +

      Alex: First, navigate to the repository. Then, select the "Wiki" tab. After that, if no wiki exists, you'll see "Create the first page". Think of it as a rail line: each stop confirms you are still on the right route before the next one.

      -

      Jamie: Let's pause on What you're adding. What should a learner take away from it?

      -

      Alex: Here is the plain-English version of What you're adding. If the agent doesn't recognize your new workflow.

      -

      Alex: The practical takeaway is this. A clear label for the new workflow. Instructions on how to invoke it. Pre-defined fields that make sense for security reports. Specific options for severity and vulnerability type. The agent recognizes your new workflow. Next time you invoke @template-builder with "create security template", it will follow your new guidance.

      -

      Alex: First, save the file: Ctrl+S. Then, you should see no error messages. After that, the agent file now includes your new Pre-Built Workflow. Finally, open Copilot Chat again: Ctrl+Shift+I. Treat it like a recipe: do not add the next ingredient until the previous one is actually in the bowl.

      -

      Jamie: Before we leave What you're adding, what is the practical point?

      -

      Alex: First, press Enter. Then, the agent should now ask vulnerability-specific questions. After that, commit your agent change. Finally, the extended agent is now in your fork. It is a checklist, but a meaningful one: every item creates evidence that the next step is safe.

      -

      Alex: Treat examples as spoken recipes, not decorations. You may hear something like git add.github/agents/template-builder.agent.md; git commit -m "feat: add security vulnerability template workflow to template-builder agent"; git push origin main. Read the command, understand what it changes, then run it only when the repository state matches the lesson.

      -

      Jamie: Let's pause on Exercise 3: Iterative Refinement with Agents. What should a learner take away from it?

      -

      Alex: This is where Exercise 3: Iterative Refinement with Agents becomes real: your Mission: Generate a template, then ask the agent to modify it incrementally. That matters in practice: This teaches you the iterative pattern that scales to all agent-assisted workflows. The workshop is closer to rehearsal than lecture. You hear the move, try the move, and then check what changed.

      -

      Alex: The practical takeaway is this. Running a complete template generation (same as Exercise 1). The agent modifies the YAML it generated. The new checkbox appears in the YAML with proper formatting and indentation. It doesn't regenerate from scratch - just adds your change.

      -

      Alex: First, in Copilot Chat, type: @template-builder create a feature request template. Then, answer the agent's questions to build a feature request form. After that, let the agent generate the YAML. Finally, copy it to a file.github/ISSUE TEMPLATE/feature-request.yml. It is a checklist, but a meaningful one: every item creates evidence that the next step is safe.

      -

      Jamie: Before we leave Exercise 3: Iterative Refinement with Agents, what is the practical point?

      -

      Alex: First, once the template is generated, while still in the same chat conversation, ask. Then, the agent regenerates the YAML with your new checkbox added in the right place (usually as required field pre-validation). After that, follow up. Finally, the agent modifies the textarea field's attributes to enable code highlighting. It is like walking a hallway with named doors: read the sign, enter the right room, then confirm where you landed.

      -

      Jamie: Let's pause on What Comes Next. What should a learner take away from it?

      -

      Alex: Keep the learner anchored in What Comes Next. Your next step: explore the broader ecosystem. This is the part to say slowly: That is Accessibility Agents' promise: not to replace your thinking, but to amplify your skills across all 55 agents - and to grow through the contributions of everyone who uses it.

      -

      Alex: The practical takeaway is this. Browse the full agent list - which agents solve problems you face regularly? Try an Accessibility team agent: @contrast-master check this page or @alt-text-headings review this file. Try a Developer Tools agent: @python-specialist review this module for accessibility or @desktop-a11y-specialist audit this dialog. Think about what is missing: what agent would you build if you could?

      -

      Alex: First, generated a template using an agent (Exercise 1). Then, customized an agent for your domain (Exercise 2). After that, refined iteratively with agent help (Exercise 3). It is like walking a hallway with named doors: read the sign, enter the right room, then confirm where you landed.

      +

      Jamie: Let's pause on Creating Wiki Pages. What should a learner take away from it?

      +

      Alex: Here is the plain-English version of Creating Wiki Pages. Wiki pages automatically appear in a sidebar for navigation. It is like learning a transit route. The names of the stops matter because they tell you whether you are still going the right direction.

      +

      Alex: First, go to the Wiki tab. Then, select "New page". After that, add a title and content (Markdown). Finally, select "Save". Treat it like a recipe: do not add the next ingredient until the previous one is actually in the bowl.

      +

      Jamie: Let's pause on Wiki Accessibility. What should a learner take away from it?

      +

      Alex: This is where Wiki Accessibility becomes real: return to: Resources Appendix S - Organizations and Templates Appendix G - GitHub Discussions Appendix T - Contributing to Open Source Appendix A - Glossary.

      +

      Alex: The practical takeaway is this. GitHub's wiki editor is the same as the issue/PR comment editor. All Markdown features work (headings, lists, links, code blocks). Use proper heading hierarchy (, ) for screen reader navigation. Link between wiki pages: [[Page Title]]. Screen reader caveat: Wiki pages are a separate Git repository. Any changes pushed directly to the wiki's git remote are not tracked by the main repository's branch protection - meaning no PR review process applies. Treat wikis as community-editable.

      +

      Alex: Now bring the learner back to the room. Start with Learning Cards: Organizations and Templates. There is something to understand, something to try, and something that proves the try worked.

      +

      Alex: The practical takeaway is this. The "Use this template" button is near the "Code" button at the top of a template repository -- press B to navigate buttons until you hear it. Organization profiles list repositories and members under heading sections -- use H to jump between People, Repositories, and Projects. Repository visibility (Public, Private, Internal) is announced as a badge near the repository name heading. Template repositories show a green "Use this template" button prominently near the top -- it replaces or sits alongside the Fork button. Organization pages use the same layout as personal profiles but with team-oriented sections. Archived repositories display a yellow warning banner across the top of the page.

      -

      Alex: Keep the teaching thread moving. Start with Learning Cards: Contributing to the Ecosystem. There is something to understand, something to try, and something that proves the try worked.

      -

      Alex: The practical takeaway is this. Agent.agent.md files use YAML frontmatter at the top (between --- delimiters) followed by Markdown body; in VS Code, use Ctrl+G to jump to line 1 and arrow through the frontmatter fields (name, description, tools) before reading the body instructions. When writing your own.agent.md, use VS Code's Outline view (Ctrl+Shift+O) to verify that your Markdown headings (Purpose, Capabilities, Responsibilities) are correctly nested -- malformed headings will not appear in the outline. Before submitting a PR with a new agent file, run the file through a YAML linter (install the YAML extension, or use yamllint from the terminal) -- frontmatter syntax errors silently break agent registration. YAML frontmatter fields are densely packed with colons and quotes; increase your editor font size or use a monospaced font with wide character spacing so name:, description:, and tools: are clearly distinct. The.agent.md files in the agents/ directory follow a consistent structure -- use the file explorer's icon theme or file nesting feature to visually group agent files separately from regular documentation. When reviewing existing agents for contribution ideas, use VS Code's split editor to place the agent file and the README side by side so you can cross-reference the agent's instructions with its documented capabilities.

      -

      Jamie: Let's pause on 7. The Bigger Picture: Teams, Orchestration, and Beyond VS Code. What should a learner take away from it?

      -

      Alex: Start with 7. The Bigger Picture: Teams, Orchestration, and Beyond VS Code: The 55 agents are not 55 independent tools. The next useful detail is this: They are organized into three teams that work together, and several orchestrator agents exist specifically to coordinate multi-agent workflows.

      -

      Alex: Keep the teaching thread moving. Here is the plain-English version of How the Three Teams Connect. In practice, a single task often spans multiple teams. Put another way, no single agent covers the entire workflow. It is like learning a transit route. The names of the stops matter because they tell you whether you are still going the right direction.

      -

      Alex: The practical takeaway is this. You ask @daily-briefing (GitHub Workflow) for your morning report. It flags a PR that changes ARIA attributes. You ask @pr-review (GitHub Workflow) to generate a structured review of that PR. The review notes potential accessibility impact. You invoke @aria-specialist (Accessibility) to deep-check the ARIA changes. It identifies a missing aria-expanded state on a disclosure widget. You fix the issue using patterns from @desktop-a11y-specialist (Developer Tools) if it is a desktop application, or directly in the HTML if it is a web project.

      +

      Jamie: How should someone choose between those options?

      +

      Alex: The reason Template vs. Fork - Which One? matters is that these are two very different actions that both appear near the "Code" button. That gives the learner a simple foothold: GitHub Skills courses use "Use this template" - you start fresh with the course scaffold but your copy has no upstream connection.

      +

      Alex: Use the comparison to make a decision, not to recite a table. The main contrasts are: Use when. means What you get. Contributing back to the original project means Full git history; your changes can be PRed upstream. Use this template means Starting a new project based on the structure means Clean git history; no connection to the original repo.

      +

      Jamie: Let's pause on Creating a Template Repository. What should a learner take away from it?

      +

      Alex: Start with Creating a Template Repository: Maintainers can mark any repository as a template. Think of it like entering a new building: first you find the lobby, then the room, then the door you actually need.

      +

      Alex: First, navigate to the repository's Settings tab. Then, scroll to the "General" section → find the "Template repository" checkbox. After that, check it and save. Finally, the repository now shows a "Use this template" button instead of (or alongside) "Fork". Think of it as a rail line: each stop confirms you are still on the right route before the next one.

      +

      Jamie: Let's pause on Using a Template Repository. What should a learner take away from it?

      +

      Alex: Start with Using a Template Repository. There is something to understand, something to try, and something that proves the try worked.

      +

      Alex: First, navigate to the template repository. Then, select "Use this template" button (near the top, next to "Code"). After that, select "Create a new repository". Finally, name your new repository, choose visibility, and confirm. Treat it like a recipe: do not add the next ingredient until the previous one is actually in the bowl.

      +

      Jamie: Before we leave Using a Template Repository, what is the practical point?

      +

      Alex: First, GitHub creates a new repository with the template's files but no commit history. It is a checklist, but a meaningful one: every item creates evidence that the next step is safe.

      -

      Jamie: Let's pause on Learning Cards: Teams and Orchestration. What should a learner take away from it?

      -

      Alex: Start with Learning Cards: Teams and Orchestration. There is something to understand, something to try, and something that proves the try worked.

      -

      Alex: The practical takeaway is this. Orchestrator agents like @accessibility-lead coordinate multi-agent workflows -- invoke one and it delegates to specialists, announcing which agent it is calling. Multi-agent output appears in sequence in Copilot Chat -- press Alt+F2 after each response to read it in Accessible View before the next agent responds. The three teams are GitHub Workflow (what happened), Accessibility (is it correct), and Developer Tools (fix it) -- choose your entry point based on your current task. Orchestrator responses can be long -- use Accessible View (Alt+F2) or widen the Chat panel to read comfortably at high zoom. The workflow diagrams in this section are described in text -- no visual-only content is required to understand the agent coordination pattern. Each team's agents are listed in the tables in Section 3 -- refer back there to find the right specialist agent.

      -

      Alex: Keep the teaching thread moving. Keep the learner anchored in Orchestrator Agents. Four agents are specifically designed to coordinate others. This is the part to say slowly: You do not need to use orchestrators to get value from individual agents.

      -

      Jamie: Let's pause on High-Impact Agents to Try First. What should a learner take away from it?

      -

      Alex: The reason High-Impact Agents to Try First matters is that rather than exploring all 55 agents at once, start with the ones that deliver immediate value based on Day 1 skills you already have.

      +

      Jamie: What should happen before anyone copies and runs it?

      +

      Alex: Start with Screen reader path. There is something to understand, something to try, and something that proves the try worked.

      +

      Alex: Treat examples as spoken recipes, not decorations. You may hear something like B → navigate buttons → find "Use this template" → Enter; ↓ → "Create a new repository" from the dropdown → Enter. Read the command, understand what it changes, then run it only when the repository state matches the lesson.

      +

      Jamie: Let's pause on What Is an Organization? What should a learner take away from it?

      +

      Alex: Keep the learner anchored in What Is an Organization? A GitHub organization is an account that multiple people share. This is the part to say slowly: Instead of github.com/username/repo, organization repos live at github.com/org-name/repo.

      +

      Jamie: Let's pause on Joining an Organization. What should a learner take away from it?

      +

      Alex: The reason Joining an Organization matters is that maintainers can invite you to join. That gives the learner a simple foothold: you can also be a public contributor to an org repo without being a member - you fork the repo and submit PRs without needing an invitation. The interface gets friendlier when it stops being a wall of controls and starts being a set of named places.

      +

      Alex: First, you receive an email + GitHub notification. Then, navigate to github.com/settings/organizations to accept. After that, or click the link in the invitation email. The rhythm is simple: orient, act, verify, then continue.

      -

      Alex: Keep the teaching thread moving. Start with Slash Commands That Save the Most Time: These commands work without invoking a full agent - type them directly in Copilot Chat. The next useful detail is this: The full list of 54+ commands is in Appendix L, and Episode 39 walks through all of them with examples. Think of it like entering a new building: first you find the lobby, then the room, then the door you actually need.

      -

      Alex: The practical takeaway is this. /my-issues and /my-prs - Instant dashboard of your open work across all repos. /review-pr 14 - Full AI-generated review with inline suggestions, replacing manual line-by-line reading. /triage 22 - Label, priority, and assignment suggestions for any new issue. /daily-briefing - Morning snapshot of repository activity, PRs needing review, and stale issues.

      -

      Jamie: Let's pause on Running Agents Beyond VS Code. What should a learner take away from it?

      -

      Alex: Here is the plain-English version of Running Agents Beyond VS Code. Accessibility Agents' agents run on your machine, in your editor, when you ask for them. Put another way, the same Markdown-authored pattern extends further.

      -

      Alex: Keep the teaching thread moving. Start with Scope 1: Your Editor (Accessibility Agents). There is something to understand, something to try, and something that proves the try worked.

      -

      Alex: The practical takeaway is this. File lives in.github/agents/[name].agent.md in your workspace. Triggered by: You, when you type @[agent-name] in Copilot Chat. Runs on: Your machine, using your Copilot subscription. Reaches: Every repository your GitHub account has access to. Scale: All 55 agents available when the workspace is open.

      +

      Jamie: Let's pause on Organization Membership Visibility. What should a learner take away from it?

      +

      Alex: Start with Organization Membership Visibility. There is something to understand, something to try, and something that proves the try worked.

      +

      Alex: The practical takeaway is this. By default, your org membership is private (only you and org owners can see it). You can set it to public in your organization membership settings. Public membership appears on your GitHub profile under "Organizations". For community-access: if you become a member, set your membership public to show your contribution publicly on your profile.

      +

      Alex: This is the part worth saying out loud. Here is the plain-English version of Teams Inside Organizations. Organizations can create teams (e.g., @community-access/accessibility-reviewers). Put another way, when you see a team mentioned in a PR or issue, that @mention notifies everyone on that team.

      +

      Jamie: Let's pause on Navigating an Organization Profile Page. What should a learner take away from it?

      +

      Alex: This is where Navigating an Organization Profile Page becomes real: organization-level Projects (like the community-access project board) appear in the org's Projects tab, not inside any single repository.

      -

      Jamie: Let's pause on Scope 2: Your Repository (Travels with Forks). What should a learner take away from it?

      -

      Alex: Keep the learner anchored in Scope 2: Your Repository (Travels with Forks). When you fork accessibility-agents, all 55 agents come with it. This is the part to say slowly: You can edit them for your project's context.

      -

      Alex: The practical takeaway is this. File lives in.github/agents/[name].agent.md in the repo. Triggered by: Any contributor who has Copilot and opens the repo as a VS Code workspace. Runs on: Their machine, using their Copilot subscription. Reaches: Their GitHub account's repositories.

      -

      Alex: Keep the teaching thread moving. The reason Scope 3: The Cloud (GitHub Agentic Workflows) matters is that the workflow runs whether or not anyone is watching - when an issue is opened at 3am, the agentic response fires. That gives the learner a simple foothold: the link between Accessibility Agents and Agentic Workflows: Both use Markdown-authored instructions. The interface gets friendlier when it stops being a wall of controls and starts being a set of named places.

      -

      Alex: The practical takeaway is this. File lives in.github/workflows/[name].md (same folder as standard Actions YAML). Triggered by: Any GitHub event - issues: opened, pull request: created, schedule. Runs on: GitHub Actions infrastructure, serverlessly. Reaches: The repository where the workflow is defined.

      -

      Jamie: Let's pause on Go Deeper. What should a learner take away from it?

      -

      Alex: Start with Go Deeper: For full documentation on every agent, all 54+ slash commands, customization formats, and troubleshooting, see Appendix L: Accessibility Agents Reference. The next useful detail is this: For the audio version, listen to Episode 39: Accessibility Agents - Complete Reference.

      +

      Alex: That matters because of the next idea. Keep the learner anchored in Repository Settings - What Contributors Need to Know. You may not have Settings access to most repositories (that requires maintainer role). This is the part to say slowly: But knowing what's there helps you understand why a repository behaves the way it does. A good GitHub workflow is like a well-run meeting: everyone knows the topic, the next action, and who has the floor.

      +

      Jamie: Let's pause on Repository Visibility. What should a learner take away from it?

      +

      Alex: The reason Repository Visibility matters is that the repository's visibility label appears on its page. That gives the learner a simple foothold: screen readers: the visibility badge is usually near the repo name heading (H1).

      +

      Alex: Keep the teaching thread moving. Start with Archived Repositories: When a maintainer archives a repository, it becomes read-only. The next useful detail is this: If you find a repo you planned to contribute to is archived, look for a fork or successor project.

      +

      Alex: The practical takeaway is this. No new issues, PRs, or comments can be created. Existing content is fully preserved and viewable. The UI shows a yellow banner: "This repository has been archived by the owner.". Screen readers: NVDA/JAWS will read this banner when you navigate to the top of the page with Ctrl+Home.

      -

      Alex: Keep the teaching thread moving. Here is the plain-English version of Example: Auto-triage accessibility issues. File.github/workflows/auto-triage-a11y.md. Put another way, this runs automatically on every new issue.

      -

      Jamie: Let's pause on 8. GitHub Desktop, GitHub CLI, and Copilot CLI. What should a learner take away from it?

      -

      Alex: This is where 8. GitHub Desktop, GitHub CLI, and Copilot CLI becomes real: these tools are not required for this workshop, but are worth knowing as options for different workflows.

      -

      Alex: Keep the teaching thread moving. Keep the learner anchored in GitHub Desktop. A graphical Git application with an accessible interface. This is the part to say slowly: When to use: If command-line Git feels overwhelming, GitHub Desktop provides a GUI alternative. A good GitHub workflow is like a well-run meeting: everyone knows the topic, the next action, and who has the floor.

      -

      Alex: The practical takeaway is this. Download: desktop.github.com. Useful for: Visual diff review, simpler branch management. Screen reader support: Partial - keyboard navigation works for core flows.

      +

      Jamie: Let's pause on Repository Topics. What should a learner take away from it?

      +

      Alex: Here is the plain-English version of Repository Topics. Topics are keyword tags on a repository (e.g., accessibility, screen-reader, open-source). Put another way, they appear as colored chips on the repository home page and improve discoverability in GitHub search.

      +

      Alex: The practical takeaway is this. As a contributor: Topics tell you what the project is about at a glance. As a maintainer: Add topics in Settings → General → Topics section to improve search ranking. Screen reader: Topics are links in the "About" sidebar section; use B (next button) or Links list to reach them.

      +

      Alex: Keep the teaching thread moving. This is where Default Branch Name becomes real: the default branch is the one all PRs target by default. That matters in practice: Modern projects use main; older projects may use master or another name. The workshop is closer to rehearsal than lecture. You hear the move, try the move, and then check what changed.

      +

      Alex: A solid Git habit is to know which branch you are on, what changed, and what confirmation you expect before you run the next command.

      +

      Jamie: Let's pause on GitHub Is More Than a Code Host -- It's a Community. What should a learner take away from it?

      +

      Alex: Keep the learner anchored in GitHub Is More Than a Code Host -- It's a Community. Who this is for: You have learned the basics of GitHub and want to know how to use it as a social platform -- discovering interesting projects, following developers whose work you admire, and building a presence in the open source community. This is the part to say slowly: This appendix covers the social layer of GitHub that most tutorials skip entirely.

      -

      Jamie: Let's pause on GitHub CLI (gh). What should a learner take away from it?

      -

      Alex: The reason GitHub CLI (gh) matters is that a command-line interface for GitHub operations.

      -

      Jamie: What should happen before anyone copies and runs it?

      -

      Alex: Start with Authenticate. There is something to understand, something to try, and something that proves the try worked.

      -

      Alex: Treat examples as spoken recipes, not decorations. You may hear something like gh auth login. Read the command, understand what it changes, then run it only when the repository state matches the lesson.

      -

      Jamie: Let's pause on Common commands. What should a learner take away from it?

      -

      Alex: Here is the plain-English version of Common commands. Screen reader advantage: gh output is plain text with no dynamic regions - more predictable than the browser for certain operations.

      -

      Alex: Treat examples as spoken recipes, not decorations. You may hear something like gh issue list List issues in current repo; gh issue view 42 Read issue 42; gh pr list List pull requests; gh pr view 14 Read PR 14; gh pr create Create a new PR interactively; gh pr merge 14 Merge PR 14; gh repo clone owner/repo Clone a repository; gh repo. Read the command, understand what it changes, then run it only when the repository state matches the lesson.

      +

      Alex: Keep the teaching thread moving. Start with Learning Cards: Social Features. There is something to understand, something to try, and something that proves the try worked.

      +

      Alex: The practical takeaway is this. The Star button is announced as "Star this repository" or "Unstar this repository" -- press B to find it in the repository header area. The Follow button on a user profile is announced as "Follow [username]" -- Tab forward from the avatar and bio to reach it. On the Explore and Trending pages, each repository entry is a heading with a link -- use H or 3 to jump between entries. Star and Watch buttons sit side by side in the repository header with distinct icons (star and eye) -- both show counts next to them. Your contribution graph uses green intensity to show activity levels -- enable high-contrast theme if the color differences are hard to distinguish. The Trending page lists repositories in a numbered vertical list with star counts and daily gain on the right side.

      +

      Jamie: Let's pause on What a star is. What should a learner take away from it?

      +

      Alex: Start with What a star is: A star is GitHub's version of a bookmark combined with a "like." When you star a repository.

      +

      Alex: The practical takeaway is this. It saves to your starred list at github.com/username?tab=stars -- easy to find later. It signals to the maintainer that their work is valued. It contributes to the project's star count, which helps others discover it. It may appear in your followers' feeds.

      +

      Alex: Keep the teaching thread moving. Here is the plain-English version of Why star count matters to projects. Star counts are a social proof signal -- developers browsing for tools often sort by stars to find well-regarded projects. Put another way, a project going from 10 stars to 1,000 stars can dramatically change how many contributors it attracts. It is like learning a transit route. The names of the stops matter because they tell you whether you are still going the right direction.

      -

      Alex: Keep the teaching thread moving. This is where GitHub Copilot CLI (gh copilot) becomes real: an extension that adds Copilot to the terminal. The workshop is closer to rehearsal than lecture. You hear the move, try the move, and then check what changed.

      -

      Jamie: Let's pause on Install. What should a learner take away from it?

      -

      Alex: Start with Install. There is something to understand, something to try, and something that proves the try worked.

      -

      Alex: Treat examples as spoken recipes, not decorations. You may hear something like gh extension install github/gh-copilot. Read the command, understand what it changes, then run it only when the repository state matches the lesson.

      -

      Jamie: Let's pause on Commands. What should a learner take away from it?

      -

      Alex: The reason Commands matters is that use case: When you know what you want to do but are unsure of the exact git command syntax.

      -

      Alex: Treat examples as spoken recipes, not decorations. You may hear something like Ask Copilot to explain a command; gh copilot explain "git rebase -i HEAD 3"; Ask Copilot to suggest a command; gh copilot suggest "undo my last commit but keep the changes"; Ask Copilot to write a shell script; gh copilot suggest "create a script that finds. Read the command, understand what it changes, then run it only when the repository state matches the lesson.

      +

      Jamie: Let's pause on GitHub.com. What should a learner take away from it?

      +

      Alex: This is where GitHub.com becomes real: on any repository page, the Star button is in the top-right area of the repository header, next to Fork.

      +

      Alex: The practical takeaway is this. Click Star to star the repository -- the button changes to Starred with a filled star icon. Click the dropdown arrow next to Star to choose a List to organize it into (see Section 8). Click Starred to unstar.

      +

      Alex: Keep the teaching thread moving. Keep the learner anchored in Keyboard shortcut. On a repository page, press g then s to toggle the star.

      +

      Jamie: Let's pause on Screen reader navigation. What should a learner take away from it?

      +

      Alex: Start with Screen reader navigation. There is something to understand, something to try, and something that proves the try worked.

      +

      Alex: The practical takeaway is this. NVDA/JAWS: The Star button is in the page region after the repository title heading. Navigate by button (B) or Tab to find it. It's announced as "Star this repository" or "Unstar this repository.". VoiceOver: VO+Command+J to jump to buttons, or Tab through the header area. The button label changes between "Star" and "Starred.".

      -

      Jamie: Let's pause on Example session. What should a learner take away from it?

      -

      Alex: Start with Example session. There is something to understand, something to try, and something that proves the try worked.

      -

      Alex: Treat examples as spoken recipes, not decorations. You may hear something like $ gh copilot suggest "show me all commits from last week"; Suggestion: git log --since="1 week ago" --oneline; Run this command? (Y/n). Read the command, understand what it changes, then run it only when the repository state matches the lesson.

      -

      Alex: Keep the teaching thread moving. Start with Learning Cards: GitHub Desktop, GitHub CLI, and Copilot CLI. There is something to understand, something to try, and something that proves the try worked.

      -

      Alex: The practical takeaway is this. GitHub Desktop is a native application -- on Windows it uses UI Automation, not a browser DOM; your screen reader's object navigation (NVDA: Insert+Numpad) rather than browse mode is the correct approach for navigating its interface. GitHub CLI (gh) is entirely terminal-based; all output is plain text that your screen reader reads line by line -- pipe verbose output through head -20 or Select-Object -First 20 to avoid overwhelming your speech buffer. Copilot CLI (gh copilot suggest and gh copilot explain) presents interactive prompts in the terminal; listen for the "Run this command? (Y/n)" confirmation before pressing Enter to avoid executing unreviewed commands. GitHub Desktop inherits your Windows display scaling -- if text appears small, increase system-level scaling (Settings Display Scale) rather than looking for an in-app zoom option. Terminal output from gh and gh copilot uses your terminal's font and color settings; configure your terminal profile (Windows Terminal settings or iTerm2 preferences) with a high-contrast color scheme and large font for comfortable reading. Copilot CLI suggestions appear as plain text in the terminal, not in a styled panel -- they are easy to miss among other output; look for the indented suggestion block immediately after your prompt.

      -

      Jamie: Let's pause on "Agent not found". What should a learner take away from it?

      -

      Alex: This is where "Agent not found" becomes real: issue: Typing @agent-name shows "No agent found.".

      +

      Jamie: What is the safe way to learn from that example?

      +

      Alex: Start with GitHub CLI. There is something to understand, something to try, and something that proves the try worked.

      +

      Alex: Treat examples as spoken recipes, not decorations. You may hear something like Star a repository; gh api user/starred/owner/repo --method PUT; Unstar a repository; gh api user/starred/owner/repo --method DELETE; List your starred repositories; gh api user/starred --jq '.[].full name'; Check if you've starred a repo; gh api. Read the command, understand what it changes, then run it only when the repository state matches the lesson.

      +

      Jamie: Let's pause on Viewing your stars. What should a learner take away from it?

      +

      Alex: Here is the plain-English version of Viewing your stars. Go to github.com/username?tab=stars -- or click your avatar → Your stars. Put another way, you'll see all your starred repositories sorted by most recently starred.

      +

      Alex: Keep the teaching thread moving. Start with Learning Cards: Stars. There is something to understand, something to try, and something that proves the try worked.

      +

      Alex: The practical takeaway is this. The Star button is in the repository header area -- press B to navigate buttons until you hear "Star this repository" (or "Unstar this repository" if already starred); press Enter to toggle. The keyboard shortcut g then s on any repository page toggles the star without needing to navigate to the button. Your starred repos are listed at github.com/username?tab=stars -- each entry is a heading with the repo name as a link; use H to jump between starred repos. The Star button shows a star icon with a count next to it in the repository header -- at high zoom, the button may wrap below the repo name; look for the star icon near Fork and Watch. When you star a repo, the button changes from an outline star to a filled star with the label "Starred" -- the visual change is subtle; confirm by re-reading the button text. The dropdown arrow next to Star lets you add the repo to a List -- look for a small triangle icon to the right of the Star button at high magnification.

      -

      Jamie: Let's pause on Solutions. What should a learner take away from it?

      -

      Alex: Start with Solutions. There is something to understand, something to try, and something that proves the try worked.

      -

      Alex: First, verify.github/agents/[name].agent.md exists in your workspace. Then, reload VS Code window: Ctrl+Shift+P → "Reload Window". After that, check file naming: must end with.agent.md. Finally, verify YAML frontmatter is valid (no syntax errors). It is like walking a hallway with named doors: read the sign, enter the right room, then confirm where you landed.

      -

      Jamie: Let's pause on Agent produces incorrect output. What should a learner take away from it?

      -

      Alex: The reason Agent produces incorrect output matters is that issue: Agent's response is wrong or misses context.

      -

      Jamie: Before we leave Solutions, what is the practical point?

      -

      Alex: First, provide more context in your prompt: Be specific about what you need. Then, use @ mentions: Reference specific files or selections (@filename.md, selection). After that, check the agent's prerequisites: Did you do the manual work first? Finally, review the agent's instructions: Open.github/agents/[name].agent.md and read what it's supposed to do. Think of it as a rail line: each stop confirms you are still on the right route before the next one.

      +

      Jamie: Let's pause on What watching does. What should a learner take away from it?

      +

      Alex: Keep the learner anchored in What watching does. When you watch a repository, GitHub sends you notifications about activity in it -- new issues, pull requests, releases, and more. This is the part to say slowly: Unlike stars (which are passive bookmarks), watching is active -- you're opting into the conversation.

      +

      Alex: Keep the teaching thread moving. The reason Watch levels matters is that GitHub gives you granular control over how much you hear from a repo. The interface gets friendlier when it stops being a wall of controls and starts being a set of named places.

      +

      Jamie: Let's pause on How to watch a repository. What should a learner take away from it?

      +

      Alex: Start with How to watch a repository: On any repository page, the Watch button is next to the Star button in the header. The next useful detail is this: For most repositories you contribute to, "Participating and @mentions" is the right level -- you hear about threads you're in without inbox overload.

      +

      Alex: First, click Watch to open the dropdown. Then, choose your notification level. After that, the button updates to show your current setting. Think of it as a rail line: each stop confirms you are still on the right route before the next one.

      -

      Jamie: Let's pause on Slash command doesn't work. What should a learner take away from it?

      -

      Alex: Here is the plain-English version of Slash command doesn't work. Issue: /command shows "Command not found.".

      -

      Jamie: What is the teaching move inside Solutions?

      -

      Alex: This is where Solutions becomes real: next: Chapter 20: Build Your Agent Back: Chapter 18: Fork and Contribute Related appendices: Appendix L: Agents Reference Appendix K: Copilot Reference.

      -

      Alex: First, verify.github/prompts/[name].md exists. Then, reload window: Ctrl+Shift+P → "Reload Window". After that, check file naming: must be a.md file in.github/prompts/. Finally, try typing the full command name (autocomplete may be incomplete). It is a checklist, but a meaningful one: every item creates evidence that the next step is safe.

      -

      Jamie: Let's pause on 1. The Capstone Challenge. What should a learner take away from it?

      -

      Alex: Keep the learner anchored in 1. The Capstone Challenge. The capstone is Challenge 16 -- the final challenge of the workshop. This is the part to say slowly: Your pull request goes to a real repository.

      -

      Alex: First, choose a mission for a new accessibility agent (or improve an existing one). Then, write an agent file with valid YAML frontmatter. After that, define clear responsibilities and guardrails. Finally, test the agent locally with GitHub Copilot. It is like walking a hallway with named doors: read the sign, enter the right room, then confirm where you landed.

      -

      Jamie: Before we leave 1. The Capstone Challenge, what is the practical point?

      -

      Alex: First, open a pull request from your fork to the upstream repository. Then, respond to peer review feedback. The rhythm is simple: orient, act, verify, then continue.

      +

      Jamie: What should they understand before typing anything?

      +

      Alex: Treat examples as spoken recipes, not decorations. You may hear something like Watch a repository (all activity); gh api repos/owner/repo/subscription --method PUT --field subscribed=true; Watch releases only (requires GitHub.com -- not available via API alone); Use the web UI for granular watch levels; Ignore a repository; gh api. Read the command, understand what it changes, then run it only when the repository state matches the lesson.

      +

      Jamie: Let's pause on Learning Cards: Watching Repositories. What should a learner take away from it?

      +

      Alex: Start with Learning Cards: Watching Repositories. There is something to understand, something to try, and something that proves the try worked.

      +

      Alex: The practical takeaway is this. The Watch button is next to the Star button in the repository header -- press B to navigate buttons until you hear "Watch" or a watch level label; press Enter to open the dropdown. The watch level dropdown presents radio-style options (Not watching, Participating, All Activity, Releases only, Ignore) -- arrow through them and press Enter to select. "Participating and @mentions" is the recommended default for repos you contribute to -- it notifies you only for threads you are in or mentioned in, avoiding inbox overload. The Watch button shows an eye icon with a dropdown arrow and a count of watchers -- at high zoom, look for it immediately to the left of the Star button in the repository header. The dropdown menu lists five watch levels vertically with radio indicators -- the currently selected level has a filled radio dot or checkmark next to it. "Releases only" is the best choice for tools and dependencies you use but do not contribute to -- it sends one notification per release instead of every issue and PR.

      +

      Alex: Keep the teaching thread moving. Keep the learner anchored in What following does. When you follow a developer on GitHub. This is the part to say slowly: Following is one-way (like Twitter/X) -- they don't need to follow you back. A good GitHub workflow is like a well-run meeting: everyone knows the topic, the next action, and who has the floor.

      +

      Alex: The practical takeaway is this. Their public activity appears in your home feed. You see when they star a repository, create a new repo, or get a new follower. They receive a notification that you followed them. You appear in their followers list.

      -

      Alex: Keep the teaching thread moving. Start with What you need before starting. There is something to understand, something to try, and something that proves the try worked.

      -

      Alex: The practical takeaway is this. [ ] You have forked and cloned the accessibility-agents repository (Chapter 18). [ ] You have a feature branch created: agents/your-username-agent-name. [ ] You understand how to push to your fork and open a PR (Chapter 18). [ ] You have GitHub Copilot or Copilot Free active (Chapter 16). [ ] You have explored the existing agents in Chapter 19.

      -

      Jamie: Let's pause on Time estimate. What should a learner take away from it?

      -

      Alex: Start with Time estimate: Most students complete the capstone in 60 to 90 minutes. The next useful detail is this: The phases are designed so you can get a working agent in 30 minutes and spend the remaining time improving it.

      -

      Alex: Keep the teaching thread moving. Here is the plain-English version of 2. Phase 1: Choose Your Agent's Mission. See also: Chapter 19: Accessibility Agents introduces the agent ecosystem and shows existing agents for inspiration.

      +

      Jamie: Let's pause on Who to follow. What should a learner take away from it?

      +

      Alex: The reason Who to follow matters is that start with people whose work you already use.

      +

      Alex: The practical takeaway is this. Maintainers of tools and libraries you use daily. Authors of blog posts or talks that helped you learn. Developers in accessibility, open source, or your tech stack. Visiting the Contributors tab of a repository you love: github.com/owner/repo/graphs/contributors. Checking who opened issues or PRs you found valuable. Looking at who your existing follows follow.

      +

      Alex: Keep the teaching thread moving. Start with How to follow someone: On any user profile page (github.com/username), click the Follow button below their avatar. The next useful detail is this: To unfollow: click Following → it changes back to Follow.

      +

      Jamie: Before we leave Screen reader navigation, what is the practical point?

      +

      Alex: The practical takeaway is this. Navigate to the profile page. The Follow/Following button is near the top of the page, below the avatar and bio. NVDA/JAWS: press B to jump to buttons; the button is labelled "Follow [username]". VoiceOver: Tab to the button or use VO+Command+J.

      -

      Jamie: Let's pause on What makes a good agent mission. What should a learner take away from it?

      -

      Alex: This is where What makes a good agent mission becomes real: a good agent solves a specific, recurring problem.

      -

      Alex: The practical takeaway is this. What task do you repeat? Think about workflow steps from Day 1 and Day 2 that felt repetitive. What would a specialist know? An agent works best when it has deep knowledge of a focused area. What gap exists? Look at the existing agents in Chapter 19. Is there a workflow that no agent covers?

      -

      Alex: Keep the teaching thread moving. Keep the learner anchored in Write your mission statement. Before writing any code, write a one-sentence mission statement. This is the part to say slowly: "My agent helps [who] by [doing what] when [in what situation].". A good GitHub workflow is like a well-run meeting: everyone knows the topic, the next action, and who has the floor.

      -

      Jamie: Let's pause on 3. Phase 2: Write the Agent File. What should a learner take away from it?

      -

      Alex: The reason 3. Phase 2: Write the Agent File matters is that an agent file is a Markdown file with YAML frontmatter that defines the agent's identity, and a body that contains the agent's instructions. That gives the learner a simple foothold: agent files live in the.github/agents/ directory (for GitHub Copilot agents) or in team-specific directories in the accessibility-agents repository.

      +

      Jamie: Let's pause on GitHub CLI. What should a learner take away from it?

      +

      Alex: Treat examples as spoken recipes, not decorations. You may hear something like Follow a user; gh api user/following/username --method PUT; Unfollow a user; gh api user/following/username --method DELETE; List who you're following; gh api user/following --jq '.[].login'; List your followers; gh api user/followers --jq '.[].login'; Check. Read the command, understand what it changes, then run it only when the repository state matches the lesson.

      +

      Jamie: Let's pause on Viewing someone's profile. What should a learner take away from it?

      +

      Alex: Keep the learner anchored in Viewing someone's profile. The contribution graph is a visual calendar that screen readers may announce as a table or grid. This is the part to say slowly: Navigate with arrow keys to read individual day entries -- each cell describes the date and number of contributions.

      +

      Alex: The practical takeaway is this. Pinned repositories -- the 6 repos they've chosen to highlight. Contribution graph -- a visual grid of their activity over the past year (green squares = more activity). Recent activity -- PRs opened, issues commented on, repos starred. Repositories -- all their public repos.

      +

      Alex: Keep the teaching thread moving. The reason 4. Your Home Feed -- What You See When You Log In matters is that when you go to github.com while logged in, your home feed shows activity from people and repositories you follow or watch.

      -

      Alex: Keep the teaching thread moving. Start with File location and naming: Example.github/agents/alt-text-validator.md.

      -

      Jamie: Let's pause on The agent file structure. What should a learner take away from it?

      -

      Alex: Start with The agent file structure. There is something to understand, something to try, and something that proves the try worked.

      -

      Alex: First, yAML frontmatter -- metadata between --- markers at the top of the file. Then, instructions body -- Markdown content that tells the agent how to behave. Treat it like a recipe: do not add the next ingredient until the previous one is actually in the bowl.

      -

      Alex: Keep the teaching thread moving. This is where YAML frontmatter fields becomes real: vague descriptions result in missed automatic routing. That matters in practice: Weak: Helps with accessibility - Strong: Checks markdown files for accessibility issues, fixes descriptive links and heading hierarchy, and flags alt text for human review The more specific the description, the more reliably Copilot invokes the right agent for. The workshop is closer to rehearsal than lecture. You hear the move, try the move, and then check what changed.

      +

      Jamie: Let's pause on What appears in your feed. What should a learner take away from it?

      +

      Alex: Start with What appears in your feed. There is something to understand, something to try, and something that proves the try worked.

      +

      Alex: The practical takeaway is this. Repositories starred by people you follow -- "Jane starred awesome-accessibility". New repositories created by people you follow. Releases from repositories you watch. Public activity from people you follow (PRs opened, issues commented on). "For you" recommendations -- GitHub suggests repos and people based on your activity.

      +

      Alex: Keep the teaching thread moving. Here is the plain-English version of Your feed is a discovery tool. One of the best ways to find new interesting projects is to follow a few active developers in your area of interest and watch what they star. Put another way, if 5 people you respect all starred the same new tool this week, it's probably worth a look. It is like learning a transit route. The names of the stops matter because they tell you whether you are still going the right direction.

      +

      Jamie: Let's pause on Customising your feed. What should a learner take away from it?

      +

      Alex: This is where Customising your feed becomes real: there's no fine-grained feed filter -- you control the feed by controlling who you follow and what you watch. That matters in practice: Unfollow noisy accounts, follow more focused ones.

      -

      Jamie: Let's pause on Writing the instructions body. What should a learner take away from it?

      -

      Alex: Keep the learner anchored in Writing the instructions body. The instructions body tells the agent how to behave. This is the part to say slowly: Write it as if you are briefing a new team member on their first day.

      -

      Alex: The practical takeaway is this. Start with identity. "You are a [role] focused on [area].". List responsibilities. What specific tasks does this agent handle? Set guardrails. What should the agent never do? What are its limits? Provide examples. Show what good output looks like.

      -

      Alex: Keep the teaching thread moving. Start with Learning Cards: Writing the Agent File. There is something to understand, something to try, and something that proves the try worked.

      -

      Alex: The practical takeaway is this. Create your agent file with Ctrl+N, then Ctrl+S and save to.github/agents/your-agent-name.md -- the Explorer navigates to the folder automatically. Use Ctrl+Shift+O to navigate between YAML frontmatter fields and Markdown headings (Responsibilities, Guardrails) in your agent file. The YAML frontmatter is between --- markers at the top -- your screen reader announces these as horizontal rules. Agent files are standard Markdown -- open Markdown Preview (Ctrl+Shift+V) side by side to verify formatting as you write. The YAML frontmatter at the top uses name: and description: fields -- keep these on separate lines for readability at high zoom. Use a consistent heading hierarchy ( for title, for sections) so the Outline view (Ctrl+Shift+O) shows a clean structure.

      -

      Jamie: Let's pause on 4. Phase 3: Define Responsibilities and Guardrails. What should a learner take away from it?

      -

      Alex: Start with 4. Phase 3: Define Responsibilities and Guardrails: Responsibilities and guardrails are the most important parts of your agent's instructions. The next useful detail is this: The autograder checks that both sections exist.

      +

      Alex: Keep the teaching thread moving. Keep the learner anchored in 5. GitHub Explore -- Discovering New Projects. GitHub Explore at github.com/explore is the discovery hub -- curated collections, trending repos, and personalised recommendations.

      +

      Jamie: Let's pause on What Explore shows. What should a learner take away from it?

      +

      Alex: Start with What Explore shows. There is something to understand, something to try, and something that proves the try worked.

      +

      Alex: The practical takeaway is this. Trending -- most-starred repos this week (see Section 6). Topics -- browse by subject area (see Section 7). Collections -- curated lists of thematically related repos (e.g., "Tools for Open Source", "Accessibility Projects"). "For you" personalised recommendations -- based on your stars, follows, and language preferences.

      +

      Jamie: Let's pause on Navigating Explore with a screen reader. What should a learner take away from it?

      +

      Alex: Start with Navigating Explore with a screen reader. There is something to understand, something to try, and something that proves the try worked.

      +

      Alex: First, go to github.com/explore. Then, the page uses landmark regions -- jump to main to skip navigation. After that, collections and trending repos are listed as article/heading groups. Finally, use heading navigation (H) to jump between sections. Think of it as a rail line: each stop confirms you are still on the right route before the next one.

      +

      Jamie: Before we leave Navigating Explore with a screen reader, what is the practical point?

      +

      Alex: First, each repo entry has a heading (repo name as a link), language badge, star count, and description. Treat it like a recipe: do not add the next ingredient until the previous one is actually in the bowl.

      -

      Alex: Keep the teaching thread moving. Here is the plain-English version of Writing responsibilities. Responsibilities define what the agent does. Put another way, each responsibility should describe one discrete action the agent can take. It is like learning a transit route. The names of the stops matter because they tell you whether you are still going the right direction.

      -

      Alex: The practical takeaway is this. Scan HTML files for tags missing the alt attribute. Check that all elements have visible text or an aria-label. Verify heading levels do not skip (e.g., h1 to h3 without h2). Help with accessibility.

      -

      Jamie: Let's pause on Writing guardrails. What should a learner take away from it?

      -

      Alex: This is where Writing guardrails becomes real: guardrails define what the agent must not do. That matters in practice: They prevent the agent from overstepping, giving harmful advice, or acting without permission.

      -

      Alex: The practical takeaway is this. Never auto-fix code without asking the user first. Do not provide medical, legal, or financial advice when discussing accessibility compliance. Limit reviews to the files the user specifies -- do not scan the entire repository. If a finding is uncertain, say so explicitly rather than presenting it as definitive.

      -

      Alex: Keep the teaching thread moving. Start with Learning Cards: Responsibilities and Guardrails. There is something to understand, something to try, and something that proves the try worked.

      -

      Alex: The practical takeaway is this. Use Responsibilities and Guardrails as exact heading names -- the autograder searches for these strings. Each responsibility should start with a verb (Scan, Check, Verify, Flag) -- this makes them concrete and testable. Guardrails should start with "Never" or "Do not" to set clear boundaries your screen reader identifies as restrictions when reviewing the file. Format responsibilities as a bulleted list (starting with -) for easy scanning at high zoom -- one responsibility per bullet. Keep each guardrail to a single line so it remains visible without horizontal scrolling at your zoom level. Use bold text for emphasis on critical guardrails (e.g., Never modify files without approval ) to improve visual scanning.

      +

      Jamie: Let's pause on 6. Trending -- What's Popular Right Now. What should a learner take away from it?

      +

      Alex: Here is the plain-English version of 6. Trending -- What's Popular Right Now. GitHub Trending at github.com/trending shows repositories gaining the most stars over a time period. Put another way, it's one of the best places to discover new tools before everyone else knows about them.

      +

      Alex: Keep the teaching thread moving. This is where Filtering trending becomes real: use the dropdowns at the top of the page to filter.

      +

      Jamie: Let's pause on Trending developers. What should a learner take away from it?

      +

      Alex: Keep the learner anchored in Trending developers. Switch to github.com/trending/developers to see which developers are gaining the most followers -- another great way to find people to follow.

      -

      Jamie: Let's pause on 5. Phase 4: Test Your Agent Locally. What should a learner take away from it?

      -

      Alex: The reason 5. Phase 4: Test Your Agent Locally matters is that see also: Chapter 18: Fork and Contribute covers the fork-and-PR workflow you will use to submit your agent. That gives the learner a simple foothold: before opening a pull request, test your agent to verify it works.

      -

      Jamie: Let's pause on Testing with GitHub Copilot Chat. What should a learner take away from it?

      -

      Alex: Start with Testing with GitHub Copilot Chat. There is something to understand, something to try, and something that proves the try worked.

      -

      Alex: The practical takeaway is this. Understand its mission? Follow its responsibilities? Respect its guardrails?

      -

      Alex: First, open VS Code with the accessibility-agents repository. Then, ensure your agent file is saved in.github/agents/. After that, open GitHub Copilot Chat (Ctrl+Shift+I or Cmd+Shift+I). Finally, invoke your agent by name: @your-agent-name check this file for accessibility issues. Think of it as a rail line: each stop confirms you are still on the right route before the next one.

      -

      Jamie: Before we leave Testing with GitHub Copilot Chat, what is the practical point?

      -

      Alex: First, observe the response. Does the agent. Treat it like a recipe: do not add the next ingredient until the previous one is actually in the bowl.

      -

      Jamie: Let's pause on Testing checklist. What should a learner take away from it?

      -

      Alex: Start with Testing checklist. There is something to understand, something to try, and something that proves the try worked.

      -

      Alex: The practical takeaway is this. [ ] The agent responds when invoked by name. [ ] The agent stays within its defined responsibilities. [ ] The agent does not violate any guardrails. [ ] The agent's output is useful and specific. [ ] The agent handles edge cases gracefully (empty files, no issues found).

      +

      Jamie: Before we leave GitHub CLI, what is the practical point?

      +

      Alex: Treat examples as spoken recipes, not decorations. You may hear something like Trending repos aren't in the official API, but you can get recently starred popular repos:; gh search repos --sort stars --order desc --limit 20 --language markdown; Trending in a specific language; gh search repos --sort stars --order desc --limit 20. Read the command, understand what it changes, then run it only when the repository state matches the lesson.

      +

      Jamie: Let's pause on 7. Topics -- Finding Projects by Category. What should a learner take away from it?

      +

      Alex: Start with 7. Topics -- Finding Projects by Category: Every repository can be tagged with topics -- keywords like accessibility, screen-reader, wcag, python, machine-learning. The next useful detail is this: Topics are how maintainers categorise their work so others can discover it.

      +

      Alex: Keep the teaching thread moving. Here is the plain-English version of Browsing topics. Click any topic tag on a repository page to see all repos tagged with that topic.

      -

      Jamie: Let's pause on Iterating on your agent. What should a learner take away from it?

      -

      Alex: This is where Iterating on your agent becomes real: if the agent does not behave as expected. That matters in practice: Most students iterate 2-3 times before they are satisfied.

      -

      Alex: First, read its instructions carefully. Is anything ambiguous? Then, add more specific instructions or examples. After that, test again with the same prompt. Finally, repeat until the behavior matches your intent. It is a checklist, but a meaningful one: every item creates evidence that the next step is safe.

      -

      Jamie: Let's pause on Learning Cards: Testing Your Agent. What should a learner take away from it?

      -

      Alex: Start with Learning Cards: Testing Your Agent. There is something to understand, something to try, and something that proves the try worked.

      -

      Alex: The practical takeaway is this. Open Copilot Chat (Ctrl+Shift+I) and type @your-agent-name followed by a test prompt -- your screen reader announces the response as it streams. Press Alt+F2 after the response finishes to read the full output in Accessible View with arrow keys. If the agent does not respond as expected, edit the.agent.md file and ask again -- Copilot picks up changes immediately. Agent responses appear in the Copilot Chat panel -- widen the panel by dragging its left edge for better readability. Test with a simple prompt first (e.g., "review this file") and read the full response before trying complex requests. Use Accessible View (Alt+F2) to read responses at your preferred editor font size instead of the Chat panel's default.

      -

      Jamie: Let's pause on Tool Cards: Open Your Capstone PR. What should a learner take away from it?

      -

      Alex: The reason Tool Cards: Open Your Capstone PR matters is that VS Code Desktop (primary for Day 2). The interface gets friendlier when it stops being a wall of controls and starts being a set of named places.

      -

      Alex: First, push your branch: Ctrl+Shift+P Git: Push. Then, ctrl+Shift+P GitHub Pull Requests: Create Pull Request. After that, set base repo to Community-Access/accessibility-agents, fill in the title and description. Finally, navigate to your fork on GitHub. The rhythm is simple: orient, act, verify, then continue.

      -

      Jamie: Before we leave Tool Cards: Open Your Capstone PR, what is the practical point?

      -

      Alex: First, click Contribute Open pull request. Then, verify the base is Community-Access/accessibility-agents:main and the compare is your branch. Think of it as a rail line: each stop confirms you are still on the right route before the next one.

      -

      Alex: Treat examples as spoken recipes, not decorations. You may hear something like git push -u origin your-branch; gh pr create --repo Community-Access/accessibility-agents. Read the command, understand what it changes, then run it only when the repository state matches the lesson.

      +

      Jamie: What is the teaching move inside GitHub CLI?

      +

      Alex: Treat examples as spoken recipes, not decorations. You may hear something like Search for repos with a specific topic; gh search repos --topic accessibility --limit 20; gh search repos --topic screen-reader --stars " 50"; Add a topic to your own repository; gh api repos/owner/repo/topics --method PUT --field names[]="accessibility". Read the command, understand what it changes, then run it only when the repository state matches the lesson.

      +

      Alex: Keep the teaching thread moving. Keep the learner anchored in 8. GitHub Lists -- Organizing Your Stars. Lists let you group your starred repositories into named collections -- like playlists for code. This is the part to say slowly: Instead of one big pile of stars, you can have "Accessibility Tools," "Learning Resources," "Projects I Contribute To," etc. A good GitHub workflow is like a well-run meeting: everyone knows the topic, the next action, and who has the floor.

      +

      Jamie: Let's pause on Creating a list. What should a learner take away from it?

      +

      Alex: Start with Creating a list. There is something to understand, something to try, and something that proves the try worked.

      +

      Alex: First, go to your stars: github.com/username?tab=stars. Then, select "Create list" (top right of the stars page). After that, give it a name and optional description. Finally, select "Create". The rhythm is simple: orient, act, verify, then continue.

      +

      Jamie: Before we leave Creating a list, what is the practical point?

      +

      Alex: First, on a repo page, click the dropdown arrow next to the Star button. Then, select "Create a list" or add to an existing list. Think of it as a rail line: each stop confirms you are still on the right route before the next one.

      -

      Jamie: Let's pause on Pre-PR checklist. What should a learner take away from it?

      -

      Alex: Start with Pre-PR checklist. There is something to understand, something to try, and something that proves the try worked.

      -

      Alex: The practical takeaway is this. [ ] Your agent file has valid YAML frontmatter (name and description fields). [ ] Your agent file has a Responsibilities section. [ ] Your agent file has a Guardrails section. [ ] The file is in the correct directory. [ ] You have committed and pushed to your fork.

      -

      Jamie: Let's pause on Open the PR. What should a learner take away from it?

      -

      Alex: Here is the plain-English version of Open the PR. Follow the pull request steps from Chapter 18, Step 7.

      -

      Alex: The practical takeaway is this. Your mission statement from Phase 1. What the agent does (summary of responsibilities). Any design decisions you made. How you tested it.

      -

      Alex: First, push your branch: git push -u origin agents/your-username-agent-name. Then, go to the upstream repository on GitHub.com. After that, click the banner or go to Pull Requests and click New pull request, then compare across forks. Finally, select your fork and branch. Treat it like a recipe: do not add the next ingredient until the previous one is actually in the bowl.

      -

      Jamie: Before we leave Open the PR, what is the practical point?

      -

      Alex: First, write a PR title: "Add [agent-name] accessibility agent". Then, in the PR body,. After that, create the pull request. It is a checklist, but a meaningful one: every item creates evidence that the next step is safe.

      -

      Jamie: Let's pause on The autograder. What should a learner take away from it?

      -

      Alex: This is where The autograder becomes real: the repository has an autograding workflow that runs on every pull request. That matters in practice: The autograder posts results as a comment on your PR.

      +

      Alex: Keep the teaching thread moving. Start with Adding repos to lists. There is something to understand, something to try, and something that proves the try worked.

      +

      Alex: The practical takeaway is this. From any repo page: Star dropdown → check the list name. From your stars page: click the list icon on any starred repo row.

      +

      Jamie: Let's pause on Viewing and sharing lists. What should a learner take away from it?

      +

      Alex: Here is the plain-English version of Viewing and sharing lists. Your lists are public at github.com/username?tab=stars -- anyone can browse them. Put another way, this is useful for sharing curated resources with your community.

      +

      Jamie: If someone only remembers one thing from GitHub CLI, what should it be?

      +

      Alex: Treat examples as spoken recipes, not decorations. You may hear something like Lists are managed through the GitHub web interface only; You can view stars via CLI:; gh api user/starred --jq '.[] {name.full name, description.description}' head -20. Read the command, understand what it changes, then run it only when the repository state matches the lesson.

      -

      Alex: Keep the teaching thread moving. Start with Learning Cards: Opening Your Pull Request. There is something to understand, something to try, and something that proves the try worked.

      -

      Alex: The practical takeaway is this. The autograder comment appears in the PR timeline -- navigate to Comments on GitHub.com with h (heading navigation) to find the results. Each autograder check is listed with a pass/fail status and point value -- listen for "10/10" or "0/15" to identify which checks need attention. If a check fails, read the failure message, fix the issue locally, commit, push, and the autograder re-runs automatically. The autograder results appear as a comment with a table showing checks, points, and pass/fail status -- zoom with Ctrl+= to read the details. Green checkmarks indicate passing checks; red X marks indicate failures -- pair with High Contrast theme for clearest visibility. Your PR description should include your mission statement, responsibilities summary, and testing notes.

      -

      Jamie: Let's pause on 7. Phase 6: Respond to Review. What should a learner take away from it?

      -

      Alex: The reason 7. Phase 6: Respond to Review matters is that after the autograder passes, a peer reviewer (your buddy or another student) and a facilitator will review your agent.

      -

      Alex: Keep the teaching thread moving. Start with What reviewers look for. There is something to understand, something to try, and something that proves the try worked.

      -

      Alex: The practical takeaway is this. Clarity: Are the instructions easy to understand? Specificity: Are responsibilities concrete and actionable? Safety: Are guardrails sufficient to prevent harmful behavior? Usefulness: Would this agent actually help someone? Scope: Does the agent try to do too much or too little?

      +

      Jamie: Let's pause on 9. Finding Accessible and Inclusive Projects. What should a learner take away from it?

      +

      Alex: Keep the learner anchored in 9. Finding Accessible and Inclusive Projects. If you're specifically looking for projects that welcome contributors with disabilities, or that focus on accessibility work, here are the best ways to find them.

      +

      Jamie: Let's pause on Search strategies. What should a learner take away from it?

      +

      Alex: Start with Search strategies. There is something to understand, something to try, and something that proves the try worked.

      +

      Alex: The practical takeaway is this. github.com/topics/accessibility. github.com/topics/wcag. github.com/topics/screen-reader.

      +

      Alex: Treat examples as spoken recipes, not decorations. You may hear something like Search for accessibility-focused repos; gh search repos "accessibility" --topic a11y --stars " 100"; Find repos with good first issues in accessibility; gh search issues "accessibility" --label "good first issue" --state open; Find issues tagged both. Read the command, understand what it changes, then run it only when the repository state matches the lesson.

      +

      Jamie: Let's pause on Organisations to follow. What should a learner take away from it?

      +

      Alex: Start with Organisations to follow: GitHub organisations are collections of repos grouped by a team or company. The next useful detail is this: You can follow an org to get notified of their public activity.

      +

      Alex: The practical takeaway is this. github.com/Community-Access -- the organisation behind this workshop. Search for org:github accessibility to find GitHub's own accessibility work. Many assistive technology companies have open source components on GitHub -- search for your AT provider.

      -

      Jamie: Let's pause on Responding to feedback. What should a learner take away from it?

      -

      Alex: Here is the plain-English version of Responding to feedback. This is the same process from Chapter 18, Step 8.

      -

      Alex: First, read each review comment. Then, make changes locally. After that, commit and push. The PR updates automatically. Finally, reply to each comment explaining your changes. Treat it like a recipe: do not add the next ingredient until the previous one is actually in the bowl.

      -

      Alex: Keep the teaching thread moving. This is where When your PR is merged becomes real: your agent is now part of the accessibility-agents ecosystem. That matters in practice: It is available to anyone who uses the repository. The workshop is closer to rehearsal than lecture. You hear the move, try the move, and then check what changed.

      -

      Alex: The practical takeaway is this. You can navigate the fork workflow end to end. You can write clear, structured technical documentation. You understand accessibility concepts well enough to teach an AI agent about them. You can respond constructively to code review.

      -

      Jamie: Let's pause on 8. Capstone Rubric. What should a learner take away from it?

      -

      Alex: Keep the learner anchored in 8. Capstone Rubric. The capstone is worth 60 autograded points plus peer review.

      +

      Alex: Keep the teaching thread moving. Here is the plain-English version of Looking at who your community follows. If you follow someone doing accessibility work, browse their stars and their following list -- this is one of the fastest ways to discover the accessibility community on GitHub. It is like learning a transit route. The names of the stops matter because they tell you whether you are still going the right direction.

      +

      Jamie: Let's pause on 10. Building Your Own Presence. What should a learner take away from it?

      +

      Alex: This is where 10. Building Your Own Presence becomes real: being visible on GitHub matters when you want to collaborate with others, get hired, or establish yourself as a contributor.

      +

      Alex: Keep the teaching thread moving. Keep the learner anchored in Your contribution graph. The green grid on your profile shows your public contribution activity over the past year. This is the part to say slowly: Contributions to private repos only appear as grey squares unless the repo is made public later.

      +

      Alex: The practical takeaway is this. Push commits to a public repo. Open, comment on, or close issues or PRs in a public repo. Review a PR in a public repo.

      -

      Alex: Keep the teaching thread moving. The reason What "meets expectations" looks like matters is that a capstone that meets expectations has.

      -

      Alex: The practical takeaway is this. A focused mission (not "help with accessibility" -- something specific). At least 3 concrete responsibilities. At least 3 meaningful guardrails. A PR description that explains the agent's purpose. All autograder checks passing.

      -

      Jamie: Let's pause on What "exceeds expectations" looks like. What should a learner take away from it?

      -

      Alex: Start with What "exceeds expectations" looks like: A capstone that exceeds expectations also has.

      -

      Alex: The practical takeaway is this. Examples of expected input and output in the agent instructions. A section describing the agent's limitations. Evidence of testing (screenshots or transcripts in the PR description). Thoughtful responses to review feedback.

      -

      Alex: Keep the teaching thread moving. Here is the plain-English version of 9. Example Agents for Inspiration. These examples show the range of valid agent designs. Put another way, your agent does not need to be this long, but it should be this clear. It is like learning a transit route. The names of the stops matter because they tell you whether you are still going the right direction.

      +

      Jamie: Let's pause on Pinning repositories. What should a learner take away from it?

      +

      Alex: The reason Pinning repositories matters is that pin up to 6 repositories (your own or repos you've contributed to) on your profile.

      +

      Alex: First, go to your profile (github.com/username). Then, select "Customize your pins" above the pinned repos section. After that, check up to 6 repos to pin -- prioritise your best work and most active contributions. The rhythm is simple: orient, act, verify, then continue.

      +

      Alex: Keep the teaching thread moving. Start with Your profile README: Create a special repository named exactly the same as your username (github.com/username/username) and its README.md will appear at the top of your profile page. The next useful detail is this: This is your chance to introduce yourself, list your skills, and share what you're working on. Think of it like entering a new building: first you find the lobby, then the room, then the door you actually need.

      +

      Jamie: Let's pause on Activity tips. What should a learner take away from it?

      +

      Alex: Start with Activity tips. There is something to understand, something to try, and something that proves the try worked.

      +

      Alex: The practical takeaway is this. Comment thoughtfully on issues -- even "I can reproduce this on Windows 11 with NVDA" is a valued contribution that shows on your profile. Star generously -- it signals your interests and others see it in their feeds. Follow people in your area -- they often follow back, growing your network organically.

      -

      Jamie: Let's pause on Example 1: Heading Hierarchy Checker. What should a learner take away from it?

      -

      Alex: This is where Example 1: Heading Hierarchy Checker becomes real: mission: Validates that HTML and Markdown documents follow a correct heading hierarchy (no skipped levels).

      -

      Alex: The practical takeaway is this. Scan files for heading elements (h1 through h6 in HTML, through in Markdown). Report any instance where a heading level is skipped (e.g., h2 followed by h4). Suggest the correct heading level for each violation. Check that there is exactly one h1 per page. Do not modify files -- only report findings. Do not change heading text, only heading levels.

      -

      Alex: A solid navigation habit is to prove where you are before activating controls. Headings, landmarks, and the address bar are not trivia; they are your map.

      -

      Alex: Keep the teaching thread moving. Keep the learner anchored in Example 2: PR Description Quality Gate. Mission: Reviews pull request descriptions to ensure they contain enough context for reviewers.

      -

      Alex: The practical takeaway is this. Check that the PR description is at least 50 characters. Verify the description references an issue with Closes XX or Fixes XX. Check for a summary of changes made. Verify the description explains why the change was made, not just what was changed. Never approve or block a PR based solely on description quality. Do not rewrite the description for the author -- suggest improvements.

      -

      Jamie: Let's pause on Example 3: Keyboard Navigation Auditor. What should a learner take away from it?

      -

      Alex: The reason Example 3: Keyboard Navigation Auditor matters is that mission: Checks web components for keyboard accessibility compliance.

      -

      Alex: The practical takeaway is this. Verify all interactive elements are reachable via Tab key. Check that custom components have appropriate tabindex values. Validate that focus order follows visual layout. Detect keyboard traps (elements that receive focus but cannot release it via keyboard). Do not modify component code without user approval. Flag potential issues with confidence levels (certain, likely, possible).

      +

      Jamie: Let's pause on 11. The GitHub CLI for Social Features. What should a learner take away from it?

      +

      Alex: Start with 11. The GitHub CLI for Social Features. There is something to understand, something to try, and something that proves the try worked.

      +

      Alex: Treat examples as spoken recipes, not decorations. You may hear something like --- Following ---; gh api user/following/username --method PUT Follow someone; gh api user/following/username --method DELETE Unfollow; gh api user/following --jq '.[].login' List who you follow; gh api user/followers --jq '.[].login' List your followers; ---. Read the command, understand what it changes, then run it only when the repository state matches the lesson.

      +

      Jamie: Let's pause on Following a user. What should a learner take away from it?

      +

      Alex: Start with Following a user. There is something to understand, something to try, and something that proves the try worked.

      +

      Alex: First, navigate to github.com/username. Then, press H to jump through headings to find the user's name at the top. After that, tab forward -- the Follow/Following button is within the first few interactive elements after the avatar/bio area. Finally, press Enter or Space to follow; the button label updates to "Following [username]". It is like walking a hallway with named doors: read the sign, enter the right room, then confirm where you landed.

      +

      Jamie: Let's pause on Starring a repository. What should a learner take away from it?

      +

      Alex: Start with Starring a repository. There is something to understand, something to try, and something that proves the try worked.

      +

      Alex: First, navigate to any repository page. Then, the Star button is in the repository header, near the Fork button. After that, press B (NVDA/JAWS) to navigate by button, or Tab through the header. Finally, the button is announced as "Star this repository" or "Unstar this repository". The rhythm is simple: orient, act, verify, then continue.

      +

      Jamie: Before we leave Starring a repository, what is the practical point?

      +

      Alex: First, after starring, the button label changes and a count updates. Think of it as a rail line: each stop confirms you are still on the right route before the next one.

      -

      Alex: Keep the teaching thread moving. Start with The universal safety net: If everything else fails, post this on your challenge issue. The next useful detail is this: I attempted Challenge 16 and here is what happened: What I tried: [specific actions] What I expected: [what should have happened] What actually happened: [error or unexpected result] What I learned: [even from failure, what do I understand now?]. Think of it like entering a new building: first you find the lobby, then the room, then the door you actually need.

      +

      Jamie: Let's pause on Browsing your stars. What should a learner take away from it?

      +

      Alex: Start with Browsing your stars. There is something to understand, something to try, and something that proves the try worked.

      +

      Alex: First, go to github.com/username?tab=stars. Then, jump to main landmark to skip navigation. After that, each starred repo is a heading (H3) with a link -- navigate with H or 3. Finally, below each heading: description text, language, star count, and list controls. Think of it as a rail line: each stop confirms you are still on the right route before the next one.

      +

      Jamie: Let's pause on Exploring topics. What should a learner take away from it?

      +

      Alex: Start with Exploring topics. There is something to understand, something to try, and something that proves the try worked.

      +

      Alex: First, go to github.com/topics/accessibility (or any topic). Then, jump to main landmark. After that, repos are listed as article regions with H3 headings. Finally, each entry has: repo name (link), owner, description, language, star count, and a Star button. Treat it like a recipe: do not add the next ingredient until the previous one is actually in the bowl.

      +

      Jamie: Let's pause on GitHub Explore and Trending. What should a learner take away from it?

      +

      Alex: This is where GitHub Explore and Trending becomes real: next: Appendix U: Discussions and Gists Back: Appendix S: Releases and Insights Teaching chapter: Chapter 08: Open Source Culture.

      +

      Alex: First, go to github.com/explore or github.com/trending. Then, use H to navigate between sections and repo entries. After that, trending page has language and time period filter dropdowns near the top -- Tab to find them. Finally, each trending repo row has: rank position, repo name (link), description, star count, and "Stars today" count. It is a checklist, but a meaningful one: every item creates evidence that the next step is safe.

      -

      Jamie: What is the final checkpoint?

      -

      Alex: You should be able to point to the evidence, explain the action, and describe what you would do next if this were a real open source project. If you can teach the move back, you have learned it.

      -

      Jamie: And if they get stuck?

      -

      Alex: Read the latest message, not the loudest worry. Check the issue, the branch, the pull request, the status check, or the bot comment. Then ask for help with those facts in hand. That is how professionals collaborate.

      +

      Jamie: What should people carry with them after this?

      +

      Alex: Carry the map. Know what page or tool you are in, know which action you are taking, and know what confirmation should follow. If the confirmation is missing, pause. That pause is not wasted time; it is professional judgment.

      +

      Jamie: That is a better way to say it than just follow the steps.

      +

      Alex: Right. Steps matter, but understanding wins. That is episode 36. Next in the series is episode 37, where we keep building the same contributor muscles.

      -

      Challenge bonus-b: Document Your Journey

      -

      Reflective documentation, portfolio language, and accessible Markdown.

      +

      66. Episode 37: Contributing to Open Source

      +

      Finding issues, scoping contributions, the fork-to-PR workflow, and building habits.

      +

      Based on: Chapter 8: Contributing to Open Source

      +

      Audio and transcript are being regenerated for this episode.

      -Read Transcript - Challenge bonus-b: Document Your Journey +Read Transcript - Episode 37: Contributing to Open Source

      Transcript

      -

      Alex: Welcome back to Challenge Coach. Today we are taking on Document Your Journey, one careful step at a time.

      -

      Jamie: And I am Jamie. I am listening for the confusing parts: where to start, what to submit, and how to tell whether it worked.

      -
      -

      Alex: In this challenge, the learner is practicing reflective documentation, portfolio language, and accessible Markdown. The point is not to rush. The point is to leave a clear trace of good work.

      -

      Jamie: So we should name what success sounds like before the learner starts clicking or typing.

      -

      Alex: Yes. When the checkpoint is clear, the learner can tell the difference between being stuck and simply not being finished yet.

      -
      -

      Jamie: Okay, set the room for us. What are we walking into?

      -

      Alex: Start with Bonus B: Document Your Journey: For students who: Enjoy writing and reflection. The next useful detail is this: What you will do: Write a structured reflection about your workshop experience, using proper Markdown formatting.

      -

      Jamie: How would you walk the room through that step by step?

      -

      Alex: Start with Instructions. There is something to understand, something to try, and something that proves the try worked.

      -

      Alex: First, create a new file on your branch: reflections/YOUR-USERNAME.md. Then, use this structure. After that, commit with a meaningful message and open a PR. Treat it like a recipe: do not add the next ingredient until the previous one is actually in the bowl.

      -

      Jamie: What is the one idea that makes the next few steps less mysterious?

      -

      Alex: This is where What matters becomes real: the learning objective is structured reflection using proper Markdown. That matters in practice: If you wrote a document with headings, paragraphs, and honest reflection, you completed this bonus.

      -
      -

      Alex: Now bring the learner back to the room. Keep the learner anchored in How to Be an Effective and Respectful Open Source Contributor. Technical skills get your code into a project. This is the part to say slowly: Communication skills keep you welcomed in the community.

      -

      Jamie: Where is the promise of the workshop, underneath all the logistics?

      -

      Alex: The reason Workshop Recommendation (Chapter 8) matters is that chapter 8 is a communication and culture chapter.

      -

      Alex: The parts worth keeping in working memory are these. There are 1 guided reflection (no bot grading). Automation check: none - communication quality is too subjective for fair automated scoring. The evidence is structured reflection comment on your assigned challenge issue. The pattern is read, reflect, commit to one behavior.

      -

      Alex: The useful habit is simple: orient first, act second, verify third. That pause before acting is part of the work.

      -

      Jamie: Give me the sequence, because order matters here.

      -

      Alex: Start with Chapter 8 Challenge Set. There is something to understand, something to try, and something that proves the try worked.

      -

      Alex: First, guided reflection - read the chapter, then post a short reflection comment committing to three specific collaboration behaviors. Think of it as a rail line: each stop confirms you are still on the right route before the next one.

      +

      Alex: Welcome back to Git Going with GitHub. This is episode 37: Contributing to Open Source. I am Alex, and today we are turning Contributing to Open Source from a list of instructions into a working mental model.

      +

      Jamie: And I am Jamie. I will stop us whenever the instructions sound simple on paper but might feel different with a keyboard and screen reader.

      +
      +

      Alex: Finding issues, scoping contributions, the fork-to-PR workflow, and building habits. That is the surface description. Underneath it, we are building judgment: where to focus, what to ignore, and how to verify the result.

      +

      Jamie: So we are not using the audio as a shortcut around learning. We are using it to make the learning easier to enter.

      +

      Alex: Yes. A good audio lesson gives someone enough context to try the work with confidence, even before they open the written material.

      +

      Jamie: Okay, set the room for us. What are we walking into?

      +

      Alex: Start with How to Be an Effective and Respectful Open Source Contributor: Technical skills get your code into a project. The next useful detail is this: Communication skills keep you welcomed in the community.

      +

      Alex: The next layer is this. Here is the plain-English version of Workshop Recommendation (Chapter 8). Chapter 8 is a communication and culture chapter. It is like learning a transit route. The names of the stops matter because they tell you whether you are still going the right direction.

      +

      Alex: The practical anchors are these. There are 1 guided reflection (no bot grading). Automation check: none - communication quality is too subjective for fair automated scoring. The evidence is structured reflection comment on your assigned challenge issue. The pattern is read, reflect, commit to one behavior.

      Jamie: What does the learner do first, second, and then after that?

      -

      Alex: Here is the plain-English version of Challenge 8.1 Step-by-Step: Guided Reflection. Identify three concrete communication behaviors you will practice during the rest of the workshop. Put another way, your assigned Chapter 8 challenge issue in your Learning Room repository on GitHub.com.

      -

      Alex: Here is what that changes in practice. 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.".

      -

      Alex: First, read through the chapter content below, paying attention to the sections on GitHub Flow, constructive feedback, and asking for help. Then, as you read, think about one situation from Day 1 where communication helped (or could have helped) you. After that, open your assigned Chapter 8 challenge issue (the one titled "Chapter 8.1: Guided Reflection (@yourname)"). Finally, scroll to the comment box at the bottom of the issue. Treat it like a recipe: do not add the next ingredient until the previous one is actually in the bowl.

      -

      Jamie: Turn that into a path someone can follow.

      -

      Alex: First, post a reflection comment using this format. Then, for each prompt, write one specific, actionable sentence - not a vague goal. After that, activate the Comment button (or press Ctrl+Enter). It is a checklist, but a meaningful one: every item creates evidence that the next step is safe.

      -

      Alex: This is where the talk moves from concept to action. This is where Completing Chapter 8: Submit Your Evidence becomes real: the reflection comment itself is your evidence. That matters in practice: The facilitator reviews your comment for specificity.

      -

      Jamie: Where do you want a learner to place their attention here?

      -

      Alex: Start with Expected Outcomes. There is something to understand, something to try, and something that proves the try worked.

      -

      Alex: These are the details that keep the idea from floating away. 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.

      +

      Alex: Start with Chapter 8 Challenge Set. There is something to understand, something to try, and something that proves the try worked.

      +

      Alex: First, guided reflection - read the chapter, then post a short reflection comment committing to three specific collaboration behaviors. It is a checklist, but a meaningful one: every item creates evidence that the next step is safe.

      +

      Jamie: Turn that into a path someone can follow.

      +

      Alex: Keep the learner anchored in Challenge 8.1 Step-by-Step: Guided Reflection. Identify three concrete communication behaviors you will practice during the rest of the workshop. This is the part to say slowly: your assigned Chapter 8 challenge issue in your Learning Room repository on GitHub.com.

      +

      Alex: For a learner, the useful signals are these. 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.".

      +

      Alex: First, read through the chapter content below, paying attention to the sections on GitHub Flow, constructive feedback, and asking for help. Then, as you read, think about one situation from Day 1 where communication helped (or could have helped) you. After that, open your assigned Chapter 8 challenge issue (the one titled "Chapter 8.1: Guided Reflection (@yourname)"). Finally, scroll to the comment box at the bottom of the issue. It is like walking a hallway with named doors: read the sign, enter the right room, then confirm where you landed.

      Jamie: What is the ordered workflow?

      +

      Alex: First, post a reflection comment using this format. Then, for each prompt, write one specific, actionable sentence - not a vague goal. After that, activate the Comment button (or press Ctrl+Enter). The rhythm is simple: orient, act, verify, then continue.

      +

      Jamie: What makes this practice feel low-stakes but still real?

      +

      Alex: The reason Completing Chapter 8: Submit Your Evidence matters is that the reflection comment itself is your evidence. That gives the learner a simple foothold: the facilitator reviews your comment for specificity.

      +

      Alex: The useful habit is simple: orient first, act second, verify third. That pause before acting is part of the work.

      +

      Alex: That matters because of the next idea. Start with Expected Outcomes. There is something to understand, something to try, and something that proves the try worked.

      +

      Alex: On the ground, that means a few things. 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.

      +
      +

      Jamie: How would you walk the room through that step by step?

      Alex: Start with If You Get Stuck. There is something to understand, something to try, and something that proves the try worked.

      -

      Alex: First, use one simple sentence per prompt - do not overthink it. Then, focus on one real behavior you can start doing today, not an abstract principle. After that, if writing feels hard, draft bullet points first in a text editor, then paste into the comment. Finally, look at the "Giving Feedback" and "Asking for Help" sections in this chapter for concrete examples. The rhythm is simple: orient, act, verify, then continue.

      -

      Jamie: Let's pause on If You Get Stuck. What should a learner take away from it?

      -

      Alex: First, ask facilitator for one example response and adapt it to your own words. Then, finished but not sure you did it right? Compare your work against the Challenge 8 reference solution. Think of it as a rail line: each stop confirms you are still on the right route before the next one.

      -

      Jamie: What would you say to someone who is already bracing for this to be too much?

      -

      Alex: Start with Learning Moment: Technical quality and communication quality work together. The next useful detail is this: Respectful, clear communication helps good code get merged faster.

      +

      Alex: First, use one simple sentence per prompt - do not overthink it. Then, focus on one real behavior you can start doing today, not an abstract principle. After that, if writing feels hard, draft bullet points first in a text editor, then paste into the comment. Finally, look at the "Giving Feedback" and "Asking for Help" sections in this chapter for concrete examples. Treat it like a recipe: do not add the next ingredient until the previous one is actually in the bowl.

      +

      Jamie: Give me the sequence, because order matters here.

      +

      Alex: First, ask facilitator for one example response and adapt it to your own words. Then, finished but not sure you did it right? Compare your work against the Challenge 8 reference solution. It is a checklist, but a meaningful one: every item creates evidence that the next step is safe.

      +

      Alex: This is where the talk moves from concept to action. This is where Learning Moment becomes real: technical quality and communication quality work together. That matters in practice: Respectful, clear communication helps good code get merged faster.

      Jamie: Let's pause on Learning Pattern Used in This Chapter. What should a learner take away from it?

      Alex: Start with Learning Pattern Used in This Chapter. There is something to understand, something to try, and something that proves the try worked.

      -

      Alex: First, read and absorb community norms (not just rules, but reasons). Then, reflect on personal experience (what worked, what was hard). After that, commit to specific behaviors in writing (public accountability). Finally, apply those behaviors in upcoming chapters (reviews, comments, PRs). Treat it like a recipe: do not add the next ingredient until the previous one is actually in the bowl.

      +

      Alex: First, read and absorb community norms (not just rules, but reasons). Then, reflect on personal experience (what worked, what was hard). After that, commit to specific behaviors in writing (public accountability). Finally, apply those behaviors in upcoming chapters (reviews, comments, PRs). It is like walking a hallway with named doors: read the sign, enter the right room, then confirm where you landed.

      -

      Jamie: If I am listening before the workshop starts, what should settle in my mind first?

      -

      Alex: This is where GitHub Flow - The Standard Contribution Workflow becomes real: before diving into communication norms, it helps to understand the workflow that gives all of those conversations their context. That matters in practice: GitHub Flow is the lightweight branching model recommended for open source contribution.

      -

      Alex: That connects to another useful point. Start with Why This Model Works. There is something to understand, something to try, and something that proves the try worked.

      -

      Alex: For a learner, the useful signals are these. 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.

      -

      Jamie: Give me the version that sounds like an instructor, not a manual.

      -

      Alex: The reason GitHub Flow vs Git Flow matters is that you may encounter "Git Flow" (sometimes written "GitFlow") in older projects or enterprise environments. That gives the learner a simple foothold: this section explains what Git Flow is, how it differs from GitHub Flow, and why this workshop teaches GitHub Flow.

      +

      Alex: Before the learner moves on. The reason GitHub Flow - The Standard Contribution Workflow matters is that before diving into communication norms, it helps to understand the workflow that gives all of those conversations their context. That gives the learner a simple foothold: GitHub Flow is the lightweight branching model recommended for open source contribution. The interface gets friendlier when it stops being a wall of controls and starts being a set of named places.

      +

      Jamie: What would you say to someone who is already bracing for this to be too much?

      +

      Alex: Start with Why This Model Works. There is something to understand, something to try, and something that proves the try worked.

      +

      Alex: A few details make that real. 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.

      +

      Alex: Hold that next to this. Here is the plain-English version of GitHub Flow vs Git Flow. You may encounter "Git Flow" (sometimes written "GitFlow") in older projects or enterprise environments. Put another way, this section explains what Git Flow is, how it differs from GitHub Flow, and why this workshop teaches GitHub Flow.

      Alex: A solid Git habit is to know which branch you are on, what changed, and what confirmation you expect before you run the next command.

      -

      Alex: Here is the practical turn. Start with What Git Flow Is: Git Flow is a branching model published by Vincent Driessen in 2010. The next useful detail is this: It was designed for teams that ship versioned releases on a schedule (desktop software, mobile apps, embedded systems).

      +

      Jamie: If I am listening before the workshop starts, what should settle in my mind first?

      +

      Alex: This is where What Git Flow Is becomes real: Git Flow is a branching model published by Vincent Driessen in 2010. That matters in practice: It was designed for teams that ship versioned releases on a schedule (desktop software, mobile apps, embedded systems).

      Jamie: Let's pause on How the Git Flow Cycle Works. What should a learner take away from it?

      Alex: Start with How the Git Flow Cycle Works. There is something to understand, something to try, and something that proves the try worked.

      -

      Alex: First, developers branch feature/my-feature off develop and work there. Then, completed features merge back into develop via pull request. After that, when develop has enough features for a release, a release/1.2.0 branch is created. Finally, the release branch gets final testing, bug fixes, and version number updates. Treat it like a recipe: do not add the next ingredient until the previous one is actually in the bowl.

      +

      Alex: First, developers branch feature/my-feature off develop and work there. Then, completed features merge back into develop via pull request. After that, when develop has enough features for a release, a release/1.2.0 branch is created. Finally, the release branch gets final testing, bug fixes, and version number updates. It is like walking a hallway with named doors: read the sign, enter the right room, then confirm where you landed.

      Jamie: Before we leave How the Git Flow Cycle Works, what is the practical point?

      -

      Alex: First, the release branch merges into main (tagged with the version) and back into develop. Then, if a critical bug is found in production, a hotfix/ branch is created from main, fixed, and merged into both main and develop. It is a checklist, but a meaningful one: every item creates evidence that the next step is safe.

      -

      Alex: Keep the thread going. This is where How GitHub Flow Differs becomes real: the following table compares GitHub Flow and Git Flow across key dimensions. The workshop is closer to rehearsal than lecture. You hear the move, try the move, and then check what changed.

      +

      Alex: First, the release branch merges into main (tagged with the version) and back into develop. Then, if a critical bug is found in production, a hotfix/ branch is created from main, fixed, and merged into both main and develop. The rhythm is simple: orient, act, verify, then continue.

      +

      Jamie: What is the one idea that makes the next few steps less mysterious?

      +

      Alex: The reason How GitHub Flow Differs matters is that the following table compares GitHub Flow and Git Flow across key dimensions.

      Alex: A solid pull request habit is to separate three questions: what changed, why it changed, and what still needs review. That keeps the conversation useful instead of noisy.

      -

      Jamie: Let's pause on When You Might See Git Flow. What should a learner take away from it?

      -

      Alex: Start with When You Might See Git Flow. There is something to understand, something to try, and something that proves the try worked.

      -

      Alex: That becomes easier when you listen for these cues. 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.

      -

      Alex: Another way to ground it. The reason Why This Workshop Uses GitHub Flow matters is that for open source contribution - especially at a hackathon or when contributing to web-based projects - GitHub Flow is what you want. That gives the learner a simple foothold: it is what GitHub itself uses and what most modern open source projects follow.

      -

      Jamie: Let's pause on The Unwritten Rule: One Thing Per Branch. What should a learner take away from it?

      -

      Alex: Start with The Unwritten Rule: One Thing Per Branch: A branch and its PR should do one thing. The next useful detail is this: If you are fixing a broken link and you notice a typo nearby, fix the typo in a separate branch and PR.

      +

      Alex: Here is the practical turn. Start with When You Might See Git Flow. There is something to understand, something to try, and something that proves the try worked.

      +

      Alex: Here is what that changes in practice. 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.

      +

      Jamie: What belongs in the live room, and what can wait until after?

      +

      Alex: Here is the plain-English version of 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. Put another way, it is what GitHub itself uses and what most modern open source projects follow.

      +

      Alex: Keep the thread going. This is where The Unwritten Rule: One Thing Per Branch becomes real: a branch and its PR should do one thing. That matters in practice: If you are fixing a broken link and you notice a typo nearby, fix the typo in a separate branch and PR. The workshop is closer to rehearsal than lecture. You hear the move, try the move, and then check what changed.

      -

      Alex: This is the part worth saying out loud. Start with Learning Cards: GitHub Flow. There is something to understand, something to try, and something that proves the try worked.

      -

      Alex: The practical anchors are these. 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). 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.

      -

      Jamie: Let's pause on Keeping Your Fork Up to Date. What should a learner take away from it?

      -

      Alex: This is where Keeping Your Fork Up to Date becomes real: when you fork a repository, you get a snapshot of the project at that moment. That matters in practice: The original repository (called "upstream") continues to evolve.

      -

      Alex: The next layer is this. Start with Why Sync Your Fork? There is something to understand, something to try, and something that proves the try worked.

      -

      Alex: On the ground, that means a few things. 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.

      +

      Jamie: Where do you want a learner to place their attention here?

      +

      Alex: Start with Learning Cards: GitHub Flow. There is something to understand, something to try, and something that proves the try worked.

      +

      Alex: These are the details that keep the idea from floating away. 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). 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.

      +

      Alex: Another way to ground it. The reason Keeping Your Fork Up to Date matters is that when you fork a repository, you get a snapshot of the project at that moment. That gives the learner a simple foothold: the original repository (called "upstream") continues to evolve.

      +

      Jamie: Give me the version that sounds like an instructor, not a manual.

      +

      Alex: Start with Why Sync Your Fork? There is something to understand, something to try, and something that proves the try worked.

      +

      Alex: That shows up in the workshop in a few specific ways. 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.

      Jamie: Let's pause on Method 1: GitHub Web Interface (Easiest). What should a learner take away from it?

      -

      Alex: The reason Method 1: GitHub Web Interface (Easiest) matters is that GitHub merges the upstream changes into your fork automatically. That gives the learner a simple foothold: screen reader users (NVDA / JAWS / VoiceOver).

      -

      Alex: First, navigate to your fork's main page: github.com/your-username/repo-name. Then, look for the sync indicator: "This branch is X commits behind upstream/main". After that, click the "Sync fork" button. Finally, click "Update branch". The rhythm is simple: orient, act, verify, then continue.

      +

      Alex: Here is the plain-English version of Method 1: GitHub Web Interface (Easiest). GitHub merges the upstream changes into your fork automatically. Put another way, screen reader users (NVDA / JAWS / VoiceOver). It is like learning a transit route. The names of the stops matter because they tell you whether you are still going the right direction.

      +

      Alex: First, navigate to your fork's main page: github.com/your-username/repo-name. Then, look for the sync indicator: "This branch is X commits behind upstream/main". After that, click the "Sync fork" button. Finally, click "Update branch". Treat it like a recipe: do not add the next ingredient until the previous one is actually in the bowl.

      Jamie: Before we leave Method 1: GitHub Web Interface (Easiest), what is the practical point?

      -

      Alex: First, the sync button appears in the landmark that contains the branch selector. Then, press D to cycle through landmarks until you reach that region. After that, press B to cycle buttons until you hear "Sync fork" → press Enter. Finally, a dialog or page update presents "Update branch" - activate it. Think of it as a rail line: each stop confirms you are still on the right route before the next one.

      -

      Alex: That matters because of the next idea. Start with Method 2: Git Command Line (VS Code Terminal): If you're working locally in VS Code. Think of it like entering a new building: first you find the lobby, then the room, then the door you actually need.

      -

      Jamie: What is the safe way to learn from that example?

      +

      Alex: First, the sync button appears in the landmark that contains the branch selector. Then, press D to cycle through landmarks until you reach that region. After that, press B to cycle buttons until you hear "Sync fork" → press Enter. Finally, a dialog or page update presents "Update branch" - activate it. It is a checklist, but a meaningful one: every item creates evidence that the next step is safe.

      +

      Jamie: What should someone listen for when a lesson offers more than one tool path?

      +

      Alex: This is where Method 2: Git Command Line (VS Code Terminal) becomes real: if you're working locally in VS Code.

      +

      Jamie: What should happen before anyone copies and runs it?

      Alex: Start with One-time setup - add the upstream remote. There is something to understand, something to try, and something that proves the try worked.

      Alex: Treat examples as spoken recipes, not decorations. You may hear something like git remote add upstream https://github.com/original-owner/repo-name.git; git remote -v Verify it was added. Read the command, understand what it changes, then run it only when the repository state matches the lesson.

      -

      Jamie: What should happen before anyone copies and runs it?

      +

      Jamie: What should they understand before typing anything?

      Alex: Start with Sync process. There is something to understand, something to try, and something that proves the try worked.

      Alex: Treat examples as spoken recipes, not decorations. You may hear something like 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. Read the command, understand what it changes, then run it only when the repository state matches the lesson.

      -

      Jamie: Let's pause on When to sync. What should a learner take away from it?

      -

      Alex: Start with When to sync. There is something to understand, something to try, and something that proves the try worked.

      -

      Alex: A few details make that real. 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).

      +

      Alex: Now bring the learner back to the room. Start with When to sync. There is something to understand, something to try, and something that proves the try worked.

      +

      Alex: The room should hear these as checkpoints. 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).

      Jamie: Let's pause on Method 3: GitHub Desktop. What should a learner take away from it?

      Alex: Start with Method 3: GitHub Desktop. There is something to understand, something to try, and something that proves the try worked.

      -

      Alex: First, open GitHub Desktop. Then, select Repository → Pull to get your fork's latest. After that, select Branch → Merge into Current Branch. Finally, choose upstream/main. The rhythm is simple: orient, act, verify, then continue.

      +

      Alex: First, open GitHub Desktop. Then, select Repository → Pull to get your fork's latest. After that, select Branch → Merge into Current Branch. Finally, choose upstream/main. Treat it like a recipe: do not add the next ingredient until the previous one is actually in the bowl.

      Jamie: Before we leave Method 3: GitHub Desktop, what is the practical point?

      -

      Alex: First, push the changes to your fork on GitHub. Think of it as a rail line: each stop confirms you are still on the right route before the next one.

      +

      Alex: First, push the changes to your fork on GitHub. It is a checklist, but a meaningful one: every item creates evidence that the next step is safe.

      -

      Jamie: Let's pause on Learning Cards: Keeping Your Fork Up to Date. What should a learner take away from it?

      -

      Alex: Start with Learning Cards: Keeping Your Fork Up to Date. There is something to understand, something to try, and something that proves the try worked.

      -

      Alex: That shows up in the workshop in a few specific ways. 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. 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.

      -

      Alex: Before the learner moves on. Here is the plain-English version of Writing Good Commit Messages. Every commit you make includes a message describing what changed. Put another way, good commit messages make project history understandable months or years later.

      -

      Jamie: Let's pause on The First Line (Required). What should a learner take away from it?

      -

      Alex: This is where The First Line (Required) becomes real: this is the commit summary that appears in logs and GitHub's commit list. That matters in practice: Think of it as an email subject line.

      -

      Alex: The room should hear these as checkpoints. fix: - bug fix. feat: - new feature. docs: - documentation only. style: - formatting, no code change.

      +

      Alex: This is the part worth saying out loud. Start with Learning Cards: Keeping Your Fork Up to Date. There is something to understand, something to try, and something that proves the try worked.

      +

      Alex: That becomes easier when you listen for these cues. 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. 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.

      +

      Jamie: Let's pause on Writing Good Commit Messages. What should a learner take away from it?

      +

      Alex: Keep the learner anchored in Writing Good Commit Messages. Every commit you make includes a message describing what changed. This is the part to say slowly: Good commit messages make project history understandable months or years later.

      +

      Alex: That connects to another useful point. The reason The First Line (Required) matters is that this is the commit summary that appears in logs and GitHub's commit list. That gives the learner a simple foothold: think of it as an email subject line. The interface gets friendlier when it stops being a wall of controls and starts being a set of named places.

      +

      Alex: The parts worth keeping in working memory are these. fix: - bug fix. feat: - new feature. docs: - documentation only. style: - formatting, no code change.

      -

      Jamie: How do you keep commands from becoming magic words?

      -

      Alex: Keep the learner anchored in The Body (Optional). If the summary isn't enough, add a body explaining. This is the part to say slowly: Leave a blank line between the summary and the body. A good GitHub workflow is like a well-run meeting: everyone knows the topic, the next action, and who has the floor.

      +

      Jamie: What is the safe way to learn from that example?

      +

      Alex: Start with The Body (Optional): If the summary isn't enough, add a body explaining. The next useful detail is this: Leave a blank line between the summary and the body.

      Alex: The practical takeaway is this. Why you made the change (more important than what). What trade-offs you considered. How the change affects behavior.

      Alex: Treat examples as spoken recipes, not decorations. You may hear something like 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. Read the command, understand what it changes, then run it only when the repository state matches the lesson.

      -

      Jamie: Let's pause on The Footer (Optional). What should a learner take away from it?

      -

      Alex: The reason The Footer (Optional) matters is that when the commit is merged, GitHub automatically closes linked issues.

      -

      Alex: Hold that next to this. Start with Atomic Commits: Each commit should represent one logical change. The next useful detail is this: Don't bundle unrelated fixes into a single commit.

      +

      Alex: Keep the teaching thread moving. Here is the plain-English version of The Footer (Optional). When the commit is merged, GitHub automatically closes linked issues.

      +

      Jamie: Let's pause on Atomic Commits. What should a learner take away from it?

      +

      Alex: This is where Atomic Commits becomes real: each commit should represent one logical change. That matters in practice: Don't bundle unrelated fixes into a single commit.

      -

      Jamie: Let's pause on Common mistakes to avoid. What should a learner take away from it?

      -

      Alex: Start with Common mistakes to avoid. There is something to understand, something to try, and something that proves the try worked.

      +

      Alex: Keep the teaching thread moving. Start with Common mistakes to avoid. There is something to understand, something to try, and something that proves the try worked.

      Alex: The practical takeaway is this. "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.

      -

      Jamie: What should they understand before typing anything?

      -

      Alex: This is where Good commit messages in practice becomes real: when you make a habit of writing good commit messages, you build trust. That matters in practice: Maintainers see that you care about the project's long-term health, not just your immediate contribution. The workshop is closer to rehearsal than lecture. You hear the move, try the move, and then check what changed.

      +

      Jamie: How do you keep commands from becoming magic words?

      +

      Alex: The reason Good commit messages in practice matters is that when you make a habit of writing good commit messages, you build trust. That gives the learner a simple foothold: maintainers see that you care about the project's long-term health, not just your immediate contribution.

      Alex: Treat examples as spoken recipes, not decorations. You may hear something like 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. Read the command, understand what it changes, then run it only when the repository state matches the lesson.

      -

      Jamie: Let's pause on Learning Cards: Writing Good Commit Messages. What should a learner take away from it?

      -

      Alex: Start with Learning Cards: Writing Good Commit Messages. There is something to understand, something to try, and something that proves the try worked.

      +

      Alex: Keep the teaching thread moving. Start with Learning Cards: Writing Good Commit Messages. There is something to understand, something to try, and something that proves the try worked.

      Alex: The practical takeaway is this. 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. 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.

      -

      Alex: Keep the teaching thread moving. The reason The Nature of Open Source Communication matters is that open source collaboration happens primarily in writing, asynchronously, in public. That gives the learner a simple foothold: understanding these three characteristics shapes everything about how we communicate.

      -

      Jamie: Let's pause on In writing. What should a learner take away from it?

      -

      Alex: Start with In writing. There is something to understand, something to try, and something that proves the try worked.

      +

      Jamie: Let's pause on The Nature of Open Source Communication. What should a learner take away from it?

      +

      Alex: Here is the plain-English version of The Nature of Open Source Communication. Open source collaboration happens primarily in writing, asynchronously, in public. Put another way, understanding these three characteristics shapes everything about how we communicate.

      +

      Alex: Keep the teaching thread moving. Start with In writing. There is something to understand, something to try, and something that proves the try worked.

      Alex: The practical takeaway is this. 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.".

      -

      Alex: Keep the teaching thread moving. Start with Asynchronously. There is something to understand, something to try, and something that proves the try worked.

      +

      Jamie: Let's pause on Asynchronously. What should a learner take away from it?

      +

      Alex: Start with Asynchronously. There is something to understand, something to try, and something that proves the try worked.

      Alex: The practical takeaway is this. 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.

      -

      Jamie: Let's pause on In public. What should a learner take away from it?

      -

      Alex: Start with In public. There is something to understand, something to try, and something that proves the try worked.

      +

      Alex: Keep the teaching thread moving. Start with In public. There is something to understand, something to try, and something that proves the try worked.

      Alex: The practical takeaway is this. 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.

      -

      Alex: Keep the teaching thread moving. Keep the learner anchored in The Anatomy of Helpful Feedback. Whether commenting on an issue, reviewing a PR, or responding to a question, effective feedback has a structure.

      -

      Jamie: Let's pause on 1. Acknowledge what's working. What should a learner take away from it?

      -

      Alex: The reason 1. Acknowledge what's working matters is that before identifying problems, name what is good. That gives the learner a simple foothold: this is not flattery - it is accuracy.

      +

      Jamie: What do you want them to do when the plan breaks?

      +

      Alex: Start with The Anatomy of Helpful Feedback: Whether commenting on an issue, reviewing a PR, or responding to a question, effective feedback has a structure.

      +

      Alex: Keep the teaching thread moving. Here is the plain-English version of 1. Acknowledge what's working. Before identifying problems, name what is good. Put another way, this is not flattery - it is accuracy. It is like learning a transit route. The names of the stops matter because they tell you whether you are still going the right direction.

      -

      Alex: Keep the teaching thread moving. Start with 2. Identify the specific concern: "This code is inaccessible." "This button has no accessible name - aria-label or visible text is needed for screen readers to announce its purpose.". Think of it like entering a new building: first you find the lobby, then the room, then the door you actually need.

      -

      Jamie: Let's pause on 3. Explain why it matters. What should a learner take away from it?

      -

      Alex: Here is the plain-English version of 3. Explain why it matters. Context turns a complaint into a lesson. Put another way, it also respects the contributor - they deserve to understand, not just comply.

      -

      Alex: Keep the teaching thread moving. This is where 4. Suggest a path forward (when you can) becomes real: if you have an idea for a solution, offer it as a suggestion, not a mandate. That matters in practice: "Something like aria-label='Close navigation menu' would work well here.

      +

      Jamie: Let's pause on 2. Identify the specific concern. What should a learner take away from it?

      +

      Alex: This is where 2. Identify the specific concern becomes real: "This code is inaccessible." "This button has no accessible name - aria-label or visible text is needed for screen readers to announce its purpose.".

      +

      Alex: Keep the teaching thread moving. Keep the learner anchored in 3. Explain why it matters. Context turns a complaint into a lesson. This is the part to say slowly: It also respects the contributor - they deserve to understand, not just comply.

      +

      Jamie: Let's pause on 4. Suggest a path forward (when you can). What should a learner take away from it?

      +

      Alex: The reason 4. Suggest a path forward (when you can) matters is that if you have an idea for a solution, offer it as a suggestion, not a mandate. That gives the learner a simple foothold: "Something like aria-label='Close navigation menu' would work well here.

      -

      Jamie: Let's pause on 5. Signal the weight of the concern. What should a learner take away from it?

      -

      Alex: Keep the learner anchored in 5. Signal the weight of the concern. Help contributors understand what is a blocker versus a preference.

      +

      Alex: Keep the teaching thread moving. Start with 5. Signal the weight of the concern: Help contributors understand what is a blocker versus a preference. Think of it like entering a new building: first you find the lobby, then the room, then the door you actually need.

      Alex: The practical takeaway is this. 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.

      -

      Alex: Keep the teaching thread moving. The reason Prefer "we" or describe the code, not the person matters is that "You made an error here." "There's an error here." or "This line does X but we need Y.". The interface gets friendlier when it stops being a wall of controls and starts being a set of named places.

      -

      Jamie: Let's pause on Use tentative language for uncertainty. What should a learner take away from it?

      -

      Alex: Start with 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?".

      +

      Jamie: Let's pause on Prefer "we" or describe the code, not the person. What should a learner take away from it?

      +

      Alex: Here is the plain-English version of 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.".

      +

      Alex: Keep the teaching thread moving. This is where Use tentative language for uncertainty becomes real: "This will crash on mobile." "I think this might cause issues on mobile - have you tested with a narrower viewport?".

      -

      Alex: Keep the teaching thread moving. Here is the plain-English version of Acknowledge cultural and language diversity. When reading someone's comment: Assume good intent unless there is clear evidence otherwise. Put another way, when writing: Choose plain words over clever ones.

      +

      Jamie: Let's pause on Acknowledge cultural and language diversity. What should a learner take away from it?

      +

      Alex: Keep the learner anchored in Acknowledge cultural and language diversity. When reading someone's comment: Assume good intent unless there is clear evidence otherwise. This is the part to say slowly: When writing: Choose plain words over clever ones.

      Alex: The practical takeaway is this. 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.

      -

      Jamie: Let's pause on Avoid urgency markers unless genuinely urgent. What should a learner take away from it?

      -

      Alex: This is where Avoid urgency markers unless genuinely urgent becomes real: "I need this fixed ASAP" "This is blocking our release scheduled for next Friday - is there capacity to look at it this week?".

      -

      Alex: Keep the teaching thread moving. Keep the learner anchored in Keep comments focused. Each comment should address one concern. This is the part to say slowly: If you have three issues, leave three comments - unless they are closely related. A good GitHub workflow is like a well-run meeting: everyone knows the topic, the next action, and who has the floor.

      +

      Alex: Keep the teaching thread moving. The reason Avoid urgency markers unless genuinely urgent matters is that "I need this fixed ASAP" "This is blocking our release scheduled for next Friday - is there capacity to look at it this week?". The interface gets friendlier when it stops being a wall of controls and starts being a set of named places.

      +

      Jamie: Let's pause on Keep comments focused. What should a learner take away from it?

      +

      Alex: Start with Keep comments focused: Each comment should address one concern. The next useful detail is this: If you have three issues, leave three comments - unless they are closely related.

      -

      Jamie: Let's pause on Don't leave comments unresolved. What should a learner take away from it?

      -

      Alex: The reason Don't leave comments unresolved matters is that if you asked a question and got an answer, respond. That gives the learner a simple foothold: "Thanks, that makes sense" or resolving the conversation thread signals that the thread is complete.

      -

      Alex: Keep the teaching thread moving. Start with Resolving conversations: On a PR, conversations (inline comment threads) can be "resolved" once addressed. The next useful detail is this: The author of the change and the reviewer can both resolve them.

      -

      Jamie: Let's pause on Do not "pile on". What should a learner take away from it?

      -

      Alex: Here is the plain-English version of 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. Put another way, a reaction on an existing comment is enough.

      +

      Alex: Keep the teaching thread moving. Here is the plain-English version of Don't leave comments unresolved. If you asked a question and got an answer, respond. Put another way, "Thanks, that makes sense" or resolving the conversation thread signals that the thread is complete.

      +

      Jamie: Let's pause on Resolving conversations. What should a learner take away from it?

      +

      Alex: This is where Resolving conversations becomes real: on a PR, conversations (inline comment threads) can be "resolved" once addressed. That matters in practice: The author of the change and the reviewer can both resolve them.

      +

      Alex: Keep the teaching thread moving. Keep the learner anchored in 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. This is the part to say slowly: A reaction on an existing comment is enough. A good GitHub workflow is like a well-run meeting: everyone knows the topic, the next action, and who has the floor.

      -

      Alex: Keep the teaching thread moving. This is where Reactions becomes real: GitHub reactions () are an efficient way to express agreement, appreciation, or concern without adding noise to a thread. The workshop is closer to rehearsal than lecture. You hear the move, try the move, and then check what changed.

      -

      Jamie: Let's pause on Saved Replies - Your Accessibility Win. What should a learner take away from it?

      -

      Alex: Keep the learner anchored in 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 the part to say slowly: This is a significant accessibility win for anyone who types the same comments repeatedly during triage, reviews, or issue management.

      -

      Alex: Keep the teaching thread moving. Start with Common uses. There is something to understand, something to try, and something that proves the try worked.

      +

      Jamie: Let's pause on Reactions. What should a learner take away from it?

      +

      Alex: The reason Reactions matters is that GitHub reactions () are an efficient way to express agreement, appreciation, or concern without adding noise to a thread.

      +

      Alex: Keep the teaching thread moving. Start with 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. The next useful detail is this: This is a significant accessibility win for anyone who types the same comments repeatedly during triage, reviews, or issue management.

      +

      Jamie: Let's pause on Common uses. What should a learner take away from it?

      +

      Alex: Start with Common uses. There is something to understand, something to try, and something that proves the try worked.

      Alex: The practical takeaway is this. "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.

      Jamie: Let's pause on Creating a Saved Reply. What should a learner take away from it?

      Alex: Start with Creating a Saved Reply. There is something to understand, something to try, and something that proves the try worked.

      -

      Alex: First, navigate to github.com/settings/replies. Then, activate "Add a saved reply". After that, give it a title (e.g., "Good first issue claim") - this is what you search. Finally, type the full reply text in the body (Markdown is supported). Think of it as a rail line: each stop confirms you are still on the right route before the next one.

      +

      Alex: First, navigate to github.com/settings/replies. Then, activate "Add a saved reply". After that, give it a title (e.g., "Good first issue claim") - this is what you search. Finally, type the full reply text in the body (Markdown is supported). It is a checklist, but a meaningful one: every item creates evidence that the next step is safe.

      Jamie: Let's pause on Using a Saved Reply in a comment. What should a learner take away from it?

      Alex: Start with Using a Saved Reply in a comment. There is something to understand, something to try, and something that proves the try worked.

      -

      Alex: First, navigate to any comment text area. Then, activate the Saved Replies button (the speech bubble icon in the comment toolbar, or press Ctrl+. if enabled). After that, a dropdown appears showing your saved replies - type to filter by title. Finally, select the reply - it inserts into the text area. Treat it like a recipe: do not add the next ingredient until the previous one is actually in the bowl.

      +

      Alex: First, navigate to any comment text area. Then, activate the Saved Replies button (the speech bubble icon in the comment toolbar, or press Ctrl+. if enabled). After that, a dropdown appears showing your saved replies - type to filter by title. Finally, select the reply - it inserts into the text area. It is like walking a hallway with named doors: read the sign, enter the right room, then confirm where you landed.

      Jamie: Before we leave Using a Saved Reply in a comment, what is the practical point?

      -

      Alex: First, edit as needed before submitting. It is a checklist, but a meaningful one: every item creates evidence that the next step is safe.

      -

      Jamie: Let's pause on Screen reader path. What should a learner take away from it?

      -

      Alex: This is where Screen reader path becomes real: limit: GitHub allows up to 100 saved replies per account.

      +

      Alex: First, edit as needed before submitting. The rhythm is simple: orient, act, verify, then continue.

      +

      Alex: Keep the teaching thread moving. The reason Screen reader path matters is that limit: GitHub allows up to 100 saved replies per account.

      Alex: A solid navigation habit is to prove where you are before activating controls. Headings, landmarks, and the address bar are not trivia; they are your map.

      -

      Alex: Keep the teaching thread moving. Start with Learning Cards: Commenting Etiquette. There is something to understand, something to try, and something that proves the try worked.

      +

      Jamie: Let's pause on Learning Cards: Commenting Etiquette. What should a learner take away from it?

      +

      Alex: Start with Learning Cards: Commenting Etiquette. There is something to understand, something to try, and something that proves the try worked.

      Alex: The practical takeaway is this. 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. 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.

      -

      Jamie: Let's pause on Review the code, not the person. What should a learner take away from it?

      -

      Alex: The reason Review the code, not the person matters is that "You clearly don't understand accessibility." "This implementation doesn't account for keyboard navigation - here's how to add it.".

      -

      Alex: Keep the teaching thread moving. Start with Don't gatekeep knowledge: If a contributor makes a mistake because they didn't know something, explain the concept. Think of it like entering a new building: first you find the lobby, then the room, then the door you actually need.

      +

      Alex: Keep the teaching thread moving. Here is the plain-English version of 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.". It is like learning a transit route. The names of the stops matter because they tell you whether you are still going the right direction.

      +

      Jamie: Let's pause on Don't gatekeep knowledge. What should a learner take away from it?

      +

      Alex: This is where Don't gatekeep knowledge becomes real: if a contributor makes a mistake because they didn't know something, explain the concept.

      -

      Jamie: Let's pause on Ask questions instead of making demands. What should a learner take away from it?

      -

      Alex: Here is the plain-English version of Ask questions instead of making demands. "Change this to use aria-label." "What do you think about using aria-label here instead? Put another way, screen readers would then announce the button's purpose directly.".

      -

      Alex: Keep the teaching thread moving. This is where Distinguish opinion from requirement becomes real: if something is your stylistic preference but NOT a bug or correctness issue, say so. That matters in practice: "The current implementation is correct.

      -

      Jamie: Let's pause on Approve explicitly. What should a learner take away from it?

      -

      Alex: Keep the learner anchored in 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!

      +

      Alex: Keep the teaching thread moving. Keep the learner anchored in Ask questions instead of making demands. "Change this to use aria-label." "What do you think about using aria-label here instead? This is the part to say slowly: Screen readers would then announce the button's purpose directly.".

      +

      Jamie: Let's pause on Distinguish opinion from requirement. What should a learner take away from it?

      +

      Alex: The reason Distinguish opinion from requirement matters is that if something is your stylistic preference but NOT a bug or correctness issue, say so. That gives the learner a simple foothold: "The current implementation is correct.

      +

      Alex: Keep the teaching thread moving. Start with 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! Think of it like entering a new building: first you find the lobby, then the room, then the door you actually need.

      -

      Alex: Keep the teaching thread moving. The reason Say thank you matters is that when someone takes time to review your work, acknowledge it - even if you disagree with some feedback. That gives the learner a simple foothold: "Thanks so much for the thorough review! The interface gets friendlier when it stops being a wall of controls and starts being a set of named places.

      -

      Jamie: Let's pause on Don't take feedback personally. What should a learner take away from it?

      -

      Alex: Start with Don't take feedback personally: Code review is about the code, not your worth as a person or developer. The next useful detail is this: Even the most senior contributors receive change requests.

      -

      Alex: Keep the teaching thread moving. Here is the plain-English version of Explain your choices. If you are keeping your implementation despite feedback, explain why. Put another way, "I considered aria-label here, but I went with a visually-hidden instead because it allows translators to localize the text more easily.

      +

      Jamie: Let's pause on Say thank you. What should a learner take away from it?

      +

      Alex: Here is the plain-English version of Say thank you. When someone takes time to review your work, acknowledge it - even if you disagree with some feedback. Put another way, "Thanks so much for the thorough review!

      +

      Alex: Keep the teaching thread moving. This is where Don't take feedback personally becomes real: code review is about the code, not your worth as a person or developer. That matters in practice: Even the most senior contributors receive change requests.

      +

      Jamie: Let's pause on Explain your choices. What should a learner take away from it?

      +

      Alex: Keep the learner anchored in Explain your choices. If you are keeping your implementation despite feedback, explain why. This is the part to say slowly: "I considered aria-label here, but I went with a visually-hidden instead because it allows translators to localize the text more easily.

      -

      Jamie: Let's pause on Surface blockers early. What should a learner take away from it?

      -

      Alex: This is where Surface blockers early becomes real: don't wait until you have finished a 500-line PR to mention that you weren't sure about the approach.

      -

      Alex: Keep the teaching thread moving. Keep the learner anchored in Inclusive Commenting for Accessibility Issues. When filing or discussing accessibility bugs, additional context helps. A good GitHub workflow is like a well-run meeting: everyone knows the topic, the next action, and who has the floor.

      +

      Alex: Keep the teaching thread moving. The reason Surface blockers early matters is that don't wait until you have finished a 500-line PR to mention that you weren't sure about the approach. The interface gets friendlier when it stops being a wall of controls and starts being a set of named places.

      +

      Jamie: Let's pause on Inclusive Commenting for Accessibility Issues. What should a learner take away from it?

      +

      Alex: Start with Inclusive Commenting for Accessibility Issues: When filing or discussing accessibility bugs, additional context helps.

      Alex: The practical takeaway is this. 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.

      Alex: A solid issue habit is to read the title, the body, and the timeline before acting. You are listening for the requested action, the missing evidence, and the person who needs a response.

      Jamie: Let's pause on The "Good First Issue" Social Contract. What should a learner take away from it?

      -

      Alex: The reason The "Good First Issue" Social Contract matters is that when a maintainer labels an issue good first issue, they are. That gives the learner a simple foothold: when you take a good first issue, your responsibilities.

      +

      Alex: Here is the plain-English version of The "Good First Issue" Social Contract. When a maintainer labels an issue good first issue, they are. Put another way, when you take a good first issue, your responsibilities.

      Alex: The practical takeaway is this. Investing time - good first issues require extra documentation and mentorship. Signaling welcome - they want to support a new contributor.

      -

      Alex: First, comment to claim it - "Hi, I'd like to work on this. Can I be assigned?". Then, wait for assignment - do not start until assigned; two people working in parallel wastes everyone's time. After that, 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?". Finally, 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?". The rhythm is simple: orient, act, verify, then continue.

      +

      Alex: First, comment to claim it - "Hi, I'd like to work on this. Can I be assigned?". Then, wait for assignment - do not start until assigned; two people working in parallel wastes everyone's time. After that, 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?". Finally, 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?". Treat it like a recipe: do not add the next ingredient until the previous one is actually in the bowl.

      Jamie: Before we leave The "Good First Issue" Social Contract, what is the practical point?

      -

      Alex: First, don't disappear - if you claim an issue, see it through or explicitly hand it back. Think of it as a rail line: each stop confirms you are still on the right route before the next one.

      +

      Alex: First, don't disappear - if you claim an issue, see it through or explicitly hand it back. It is a checklist, but a meaningful one: every item creates evidence that the next step is safe.

      Jamie: Let's pause on When you receive harsh feedback. What should a learner take away from it?

      Alex: Start with When you receive harsh feedback. There is something to understand, something to try, and something that proves the try worked.

      -

      Alex: First, take a breath before responding - there is no urgency; the thread will wait. Then, look for the valid concern underneath the harsh words. After that, respond to the concern, not the tone. Finally, if the behavior crosses into harassment, report it via the "." button on the comment → "Report". Think of it as a rail line: each stop confirms you are still on the right route before the next one.

      +

      Alex: First, take a breath before responding - there is no urgency; the thread will wait. Then, look for the valid concern underneath the harsh words. After that, respond to the concern, not the tone. Finally, if the behavior crosses into harassment, report it via the "." button on the comment → "Report". It is a checklist, but a meaningful one: every item creates evidence that the next step is safe.

      Jamie: Let's pause on When you disagree with a decision. What should a learner take away from it?

      Alex: Start with When you disagree with a decision. There is something to understand, something to try, and something that proves the try worked.

      -

      Alex: First, make your case once, clearly and with evidence. Then, accept that the maintainer has the final say in their project. After that, if you strongly disagree, you can fork the project and take it in a different direction - this is legitimate in open source. Treat it like a recipe: do not add the next ingredient until the previous one is actually in the bowl.

      +

      Alex: First, make your case once, clearly and with evidence. Then, accept that the maintainer has the final say in their project. After that, if you strongly disagree, you can fork the project and take it in a different direction - this is legitimate in open source. It is like walking a hallway with named doors: read the sign, enter the right room, then confirm where you landed.

      Jamie: Let's pause on When someone is rude to you. What should a learner take away from it?

      Alex: Start with When someone is rude to you. There is something to understand, something to try, and something that proves the try worked.

      -

      Alex: First, you do not have to engage. Then, 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.". After that, report via GitHub's reporting tools if the behavior is abusive. It is a checklist, but a meaningful one: every item creates evidence that the next step is safe.

      +

      Alex: First, you do not have to engage. Then, 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.". After that, report via GitHub's reporting tools if the behavior is abusive. The rhythm is simple: orient, act, verify, then continue.

      Jamie: Let's pause on When you accidentally caused offense. What should a learner take away from it?

      Alex: Start with When you accidentally caused offense. There is something to understand, something to try, and something that proves the try worked.

      -

      Alex: First, acknowledge it directly: "I can see how that came across as dismissive - that wasn't my intention.". Then, do not over-explain or defend excessively. After that, adjust going forward. It is like walking a hallway with named doors: read the sign, enter the right room, then confirm where you landed.

      -

      Alex: Keep the teaching thread moving. The reason Writing Your First README matters is that see also: Appendix W: GitHub Pages for publishing your README as a website. That gives the learner a simple foothold: a README is the front door of your project.

      -

      Jamie: Let's pause on What belongs in a README. What should a learner take away from it?

      -

      Alex: Start with What belongs in a README: Every README should answer these questions, roughly in this order. The next useful detail is this: 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.

      +

      Alex: First, acknowledge it directly: "I can see how that came across as dismissive - that wasn't my intention.". Then, do not over-explain or defend excessively. After that, adjust going forward. Think of it as a rail line: each stop confirms you are still on the right route before the next one.

      +

      Jamie: Let's pause on Writing Your First README. What should a learner take away from it?

      +

      Alex: Here is the plain-English version of Writing Your First README. See also: Appendix W: GitHub Pages for publishing your README as a website. Put another way, a README is the front door of your project.

      +

      Alex: Keep the teaching thread moving. This is where What belongs in a README becomes real: every README should answer these questions, roughly in this order. That matters in practice: 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. The workshop is closer to rehearsal than lecture. You hear the move, try the move, and then check what changed.

      -

      Alex: Keep the teaching thread moving. Here is the plain-English version of Accessibility in READMEs. Your README is a web page -- GitHub renders it as HTML. Put another way, that means the same accessibility rules apply. It is like learning a transit route. The names of the stops matter because they tell you whether you are still going the right direction.

      +

      Jamie: Let's pause on Accessibility in READMEs. What should a learner take away from it?

      +

      Alex: Keep the learner anchored in Accessibility in READMEs. Your README is a web page -- GitHub renders it as HTML. This is the part to say slowly: That means the same accessibility rules apply.

      Alex: The practical takeaway is this. Alt text for images and badges. A badge that says is invisible to screen readers. Write 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 -- not Click here.

      -

      Jamie: Let's pause on Good README vs. bad README. What should a learner take away from it?

      -

      Alex: This is where Good README vs. bad README becomes real: bad: A single paragraph that says "This is my project. That matters in practice: Run it with npm start." No headings, no license, no description of what the project does.

      -

      Alex: Keep the teaching thread moving. Start with Learning Cards: Writing Your First README. There is something to understand, something to try, and something that proves the try worked.

      +

      Alex: Keep the teaching thread moving. The reason Good README vs. bad README matters is that bad: A single paragraph that says "This is my project. That gives the learner a simple foothold: run it with npm start." No headings, no license, no description of what the project does.

      +

      Jamie: Let's pause on Learning Cards: Writing Your First README. What should a learner take away from it?

      +

      Alex: Start with Learning Cards: Writing Your First README. There is something to understand, something to try, and something that proves the try worked.

      Alex: The practical takeaway is this. 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: rather than an empty that reads as "image" with no context. Use real Markdown link text (installation guide) instead of bare URLs, so your screen reader announces the destination rather than spelling out a long URL. 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.

      -

      Jamie: Let's pause on Community Health Files. What should a learner take away from it?

      -

      Alex: The reason Community Health Files matters is that community health files tell contributors how your project operates before they write a single line of code. That gives the learner a simple foothold: 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.

      -

      Alex: Keep the teaching thread moving. Start with CONTRIBUTING.md: This file answers the question every newcomer asks: "How do I help?" A good CONTRIBUTING.md covers. The next useful detail is this: A sentence like "We are glad you are here" costs nothing and signals that newcomers are expected, not tolerated. Think of it like entering a new building: first you find the lobby, then the room, then the door you actually need.

      +

      Alex: Keep the teaching thread moving. Here is the plain-English version of Community Health Files. Community health files tell contributors how your project operates before they write a single line of code. Put another way, 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. It is like learning a transit route. The names of the stops matter because they tell you whether you are still going the right direction.

      +

      Jamie: Let's pause on CONTRIBUTING.md. What should a learner take away from it?

      +

      Alex: This is where CONTRIBUTING.md becomes real: this file answers the question every newcomer asks: "How do I help?" A good CONTRIBUTING.md covers. That matters in practice: A sentence like "We are glad you are here" costs nothing and signals that newcomers are expected, not tolerated.

      Alex: The practical takeaway is this. 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.

      -

      Jamie: Let's pause on CODE OF CONDUCT.md. What should a learner take away from it?

      -

      Alex: Here is the plain-English version of CODE OF CONDUCT.md. A code of conduct sets the social contract for your project. Put another way, without one, "acceptable behavior" is whatever each participant assumes it is -- and those assumptions vary widely.

      +

      Alex: Keep the teaching thread moving. Keep the learner anchored in CODE OF CONDUCT.md. A code of conduct sets the social contract for your project. This is the part to say slowly: Without one, "acceptable behavior" is whatever each participant assumes it is -- and those assumptions vary widely.

      Alex: The practical takeaway is this. 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.

      -

      Alex: Keep the teaching thread moving. This is where SECURITY.md becomes real: see also: Appendix F: Git Security and Appendix P: Security Features for security best practices. That matters in practice: If someone discovers a vulnerability in your project, you do not want them to file a public issue.

      +

      Jamie: Let's pause on SECURITY.md. What should a learner take away from it?

      +

      Alex: The reason SECURITY.md matters is that see also: Appendix F: Git Security and Appendix P: Security Features for security best practices. That gives the learner a simple foothold: if someone discovers a vulnerability in your project, you do not want them to file a public issue.

      Alex: The practical takeaway is this. 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.

      -

      Jamie: Let's pause on LICENSE. What should a learner take away from it?

      -

      Alex: Keep the learner anchored in 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. This is the part to say slowly: Adding a LICENSE file is a one-time step that makes your project genuinely open source.

      -

      Alex: Keep the teaching thread moving. The reason Finding these files on GitHub matters is that navigate to any repository and click Insights then Community Standards. That gives the learner a simple foothold: GitHub shows a checklist of which community health files are present and links to add any that are missing. The interface gets friendlier when it stops being a wall of controls and starts being a set of named places.

      +

      Alex: Keep the teaching thread moving. Start with 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. The next useful detail is this: Adding a LICENSE file is a one-time step that makes your project genuinely open source. Think of it like entering a new building: first you find the lobby, then the room, then the door you actually need.

      +

      Jamie: Let's pause on Finding these files on GitHub. What should a learner take away from it?

      +

      Alex: Here is the plain-English version of Finding these files on GitHub. Navigate to any repository and click Insights then Community Standards. Put another way, GitHub shows a checklist of which community health files are present and links to add any that are missing.

      -

      Jamie: Let's pause on Learning Cards: Community Health Files. What should a learner take away from it?

      -

      Alex: Start with Learning Cards: Community Health Files. There is something to understand, something to try, and something that proves the try worked.

      +

      Alex: Keep the teaching thread moving. Start with Learning Cards: Community Health Files. There is something to understand, something to try, and something that proves the try worked.

      Alex: The practical takeaway is this. 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. 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.

      -

      Jamie: What is the judgment call here?

      -

      Alex: Here is the plain-English version of When to Use Different Communication Channels. GitHub Discussions are separate from Issues. Put another way, use Discussions for: "What do people think about X approach?" and Issues for: "The X button is broken.".

      +

      Jamie: How should someone choose between those options?

      +

      Alex: Keep the learner anchored in When to Use Different Communication Channels. GitHub Discussions are separate from Issues. This is the part to say slowly: Use Discussions for: "What do people think about X approach?" and Issues for: "The X button is broken.".

      Alex: Use the comparison to make a decision, not to recite a table. The main contrasts are: PR comment means Feedback on a specific code change. PR review means Formal verdict (approve/request changes) with consolidated feedback. Discussion means Open-ended conversation, proposals, community Q&A.

      Jamie: Let's pause on Try It: Rewrite One Comment. What should a learner take away from it?

      -

      Alex: This is where Try It: Rewrite One Comment becomes real: time: 2 minutes What you need: Just your brain. That matters in practice: Read this code review comment and rewrite it to be constructive.

      -

      Alex: First, what you noticed. Then, why it matters. After that, what you suggest. Finally, why the suggestion helps. It is a checklist, but a meaningful one: every item creates evidence that the next step is safe.

      +

      Alex: The reason Try It: Rewrite One Comment matters is that time: 2 minutes What you need: Just your brain. That gives the learner a simple foothold: read this code review comment and rewrite it to be constructive. The interface gets friendlier when it stops being a wall of controls and starts being a set of named places.

      +

      Alex: First, what you noticed. Then, why it matters. After that, what you suggest. Finally, why the suggestion helps. The rhythm is simple: orient, act, verify, then continue.

      Jamie: Before we leave Try It: Rewrite One Comment, what is the practical point?

      -

      Alex: First, encouragement. It is like walking a hallway with named doors: read the sign, enter the right room, then confirm where you landed.

      +

      Alex: First, encouragement. Think of it as a rail line: each stop confirms you are still on the right route before the next one.

      -

      Alex: Keep the teaching thread moving. Keep the learner anchored in Contributing to Open Source. This section was previously Appendix T. This is the part to say slowly: It is now part of the teaching narrative. A good GitHub workflow is like a well-run meeting: everyone knows the topic, the next action, and who has the floor.

      -

      Jamie: Let's pause on A Guide for First-Time Contributors. What should a learner take away from it?

      -

      Alex: The reason A Guide for First-Time Contributors matters is that you do not need to be a professional developer to contribute to open source. That gives the learner a simple foothold: documentation, accessibility improvements, and bug reports are among the most valuable contributions any project can receive.

      -

      Alex: Keep the teaching thread moving. Start with 1. What Is Open Source?: Open source software is software whose source code is publicly available. The next useful detail is this: Anyone can read it, use it, and - in most cases - contribute to it.

      +

      Jamie: Let's pause on Contributing to Open Source. What should a learner take away from it?

      +

      Alex: Start with Contributing to Open Source: This section was previously Appendix T. The next useful detail is this: It is now part of the teaching narrative.

      +

      Alex: Keep the teaching thread moving. Here is the plain-English version of A Guide for First-Time Contributors. You do not need to be a professional developer to contribute to open source. Put another way, documentation, accessibility improvements, and bug reports are among the most valuable contributions any project can receive.

      +

      Jamie: Let's pause on 1. What Is Open Source? What should a learner take away from it?

      +

      Alex: This is where 1. What Is Open Source? becomes real: open source software is software whose source code is publicly available. That matters in practice: Anyone can read it, use it, and - in most cases - contribute to it.

      Alex: The practical takeaway is this. 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.

      -

      Jamie: Let's pause on 2. Who Can Contribute? What should a learner take away from it?

      -

      Alex: Here is the plain-English version of 2. Who Can Contribute? Contributors come from all backgrounds, skill levels, and countries. Put another way, 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.

      -

      Alex: Keep the teaching thread moving. Start with 3. What Makes a Good First Contribution? There is something to understand, something to try, and something that proves the try worked.

      +

      Alex: Keep the teaching thread moving. Keep the learner anchored in 2. Who Can Contribute? Contributors come from all backgrounds, skill levels, and countries. This is the part to say slowly: 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. A good GitHub workflow is like a well-run meeting: everyone knows the topic, the next action, and who has the floor.

      +

      Jamie: Let's pause on 3. What Makes a Good First Contribution? What should a learner take away from it?

      +

      Alex: Start with 3. What Makes a Good First Contribution? There is something to understand, something to try, and something that proves the try worked.

      Alex: The practical takeaway is this. 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.

      -

      Jamie: Let's pause on Signs a contribution is too large for a first attempt. What should a learner take away from it?

      -

      Alex: Keep the learner anchored in Signs a contribution is too large for a first attempt. A well-executed small contribution is far more valuable than a large contribution that cannot be merged because it is out of scope.

      +

      Alex: Keep the teaching thread moving. Start with Signs a contribution is too large for a first attempt: A well-executed small contribution is far more valuable than a large contribution that cannot be merged because it is out of scope.

      Alex: The practical takeaway is this. 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.

      -

      Alex: Keep the teaching thread moving. The reason 4. Finding Something to Work On matters is that most open source projects label issues that are suitable for new contributors. That gives the learner a simple foothold: how to search: On any GitHub repository, go to Issues → filter by label.

      -

      Jamie: Let's pause on Learning Cards: Finding Something to Work On. What should a learner take away from it?

      -

      Alex: Start with Learning Cards: Finding Something to Work On. There is something to understand, something to try, and something that proves the try worked.

      +

      Jamie: Let's pause on 4. Finding Something to Work On. What should a learner take away from it?

      +

      Alex: Here is the plain-English version of 4. Finding Something to Work On. Most open source projects label issues that are suitable for new contributors. Put another way, how to search: On any GitHub repository, go to Issues → filter by label.

      +

      Alex: Keep the teaching thread moving. Start with Learning Cards: Finding Something to Work On. There is something to understand, something to try, and something that proves the try worked.

      Alex: The practical takeaway is this. 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. 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.

      -

      Alex: Keep the teaching thread moving. Here is the plain-English version of 5. Reading an Issue Before You Start. Before commenting "I'll take this" on an issue, ask yourself. Put another way, 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. It is like learning a transit route. The names of the stops matter because they tell you whether you are still going the right direction.

      +

      Jamie: What is the pre-flight check here?

      +

      Alex: Keep the learner anchored in 5. Reading an Issue Before You Start. Before commenting "I'll take this" on an issue, ask yourself. This is the part to say slowly: 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.

      Alex: The practical takeaway is this. 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.

      Jamie: Let's pause on Tool Cards: Fork, Clone, and Contribute. What should a learner take away from it?

      Alex: Start with Tool Cards: Fork, Clone, and Contribute. There is something to understand, something to try, and something that proves the try worked.

      -

      Alex: First, click Fork on the repository page, then Create fork. Then, edit files directly in your fork's web interface. After that, click Contribute Open pull request to submit back to the original. Finally, fork the repo on github.com first. It is a checklist, but a meaningful one: every item creates evidence that the next step is safe.

      +

      Alex: First, click Fork on the repository page, then Create fork. Then, edit files directly in your fork's web interface. After that, click Contribute Open pull request to submit back to the original. Finally, fork the repo on github.com first. The rhythm is simple: orient, act, verify, then continue.

      Jamie: Before we leave Tool Cards: Fork, Clone, and Contribute, what is the practical point?

      -

      Alex: First, navigate to your fork and press. to open in the web editor. Then, edit, commit, and create a PR from the Source Control panel. After that, fork on github.com, then clone your fork: Ctrl+Shift+P Git: Clone. Finally, create a branch, make edits, commit and push. It is like walking a hallway with named doors: read the sign, enter the right room, then confirm where you landed.

      +

      Alex: First, navigate to your fork and press. to open in the web editor. Then, edit, commit, and create a PR from the Source Control panel. After that, fork on github.com, then clone your fork: Ctrl+Shift+P Git: Clone. Finally, create a branch, make edits, commit and push. Think of it as a rail line: each stop confirms you are still on the right route before the next one.

      Alex: Treat examples as spoken recipes, not decorations. You may hear something like 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. Read the command, understand what it changes, then run it only when the repository state matches the lesson.

      Jamie: Let's pause on The Basic Workflow. What should a learner take away from it?

      Alex: Start with The Basic Workflow. There is something to understand, something to try, and something that proves the try worked.

      -

      Alex: First, fork the repository - creates your own copy on GitHub. Then, clone your fork to your computer (or open a Codespace - see Appendix N). After that, create a branch - name it something descriptive: fix/broken-link-setup-guide. Finally, make your change - edit the file, save, verify. It is like walking a hallway with named doors: read the sign, enter the right room, then confirm where you landed.

      +

      Alex: First, fork the repository - creates your own copy on GitHub. Then, clone your fork to your computer (or open a Codespace - see Appendix N). After that, create a branch - name it something descriptive: fix/broken-link-setup-guide. Finally, make your change - edit the file, save, verify. Think of it as a rail line: each stop confirms you are still on the right route before the next one.

      Jamie: Before we leave The Basic Workflow, what is the practical point?

      -

      Alex: First, commit with a clear message - "Fix broken link in setup-guide.md line 34". Then, push to your fork. After that, open a pull request from your branch to the original repository's default branch. Finally, respond to review feedback - maintainers may ask for changes; this is normal and not a rejection. The rhythm is simple: orient, act, verify, then continue.

      -

      Jamie: Let's pause on Writing a Good PR Description. What should a learner take away from it?

      -

      Alex: The reason Writing a Good PR Description matters is that example: Fixed a broken link on line 34 of setup-guide.md. That gives the learner a simple foothold: the link pointed to /docs/old-setup which no longer exists.

      +

      Alex: First, commit with a clear message - "Fix broken link in setup-guide.md line 34". Then, push to your fork. After that, open a pull request from your branch to the original repository's default branch. Finally, respond to review feedback - maintainers may ask for changes; this is normal and not a rejection. Treat it like a recipe: do not add the next ingredient until the previous one is actually in the bowl.

      +

      Alex: Keep the teaching thread moving. Here is the plain-English version of Writing a Good PR Description. Example: Fixed a broken link on line 34 of setup-guide.md. Put another way, the link pointed to /docs/old-setup which no longer exists. It is like learning a transit route. The names of the stops matter because they tell you whether you are still going the right direction.

      Alex: The practical takeaway is this. What did you change? Why was the change needed? How did you verify it works?

      -

      Alex: Keep the teaching thread moving. Start with 7. Getting Help: It is always acceptable to ask a question on an issue or pull request. The next useful detail is this: 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. Think of it like entering a new building: first you find the lobby, then the room, then the door you actually need.

      +

      Jamie: How should someone ask for help in a way that gets them unstuck faster?

      +

      Alex: This is where 7. Getting Help becomes real: it is always acceptable to ask a question on an issue or pull request. That matters in practice: 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.

      Alex: The practical takeaway is this. 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.

      -

      Jamie: Let's pause on 8. After Your Contribution Is Merged. What should a learner take away from it?

      -

      Alex: Here is the plain-English version of 8. After Your Contribution Is Merged. This matters for your GitHub profile. Put another way, 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.

      +

      Alex: Keep the teaching thread moving. Keep the learner anchored in 8. After Your Contribution Is Merged. This matters for your GitHub profile. This is the part to say slowly: 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.

      Alex: The practical takeaway is this. 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.

      -

      Alex: Keep the teaching thread moving. This is where 9. Building a Contribution Habit becomes real: the hardest part of open source contribution is starting. That matters in practice: 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.

      +

      Jamie: Let's pause on 9. Building a Contribution Habit. What should a learner take away from it?

      +

      Alex: The reason 9. Building a Contribution Habit matters is that the hardest part of open source contribution is starting. That gives the learner a simple foothold: 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.

      -

      Jamie: Let's pause on Practical habits. What should a learner take away from it?

      -

      Alex: Keep the learner anchored in Practical habits. Challenge Time: Complete Challenge 8: The Culture Layer in the Challenge Hub, then advance to Chapter 09: Labels, Milestones and Projects. This is the part to say slowly: Next: Chapter 09: Labels, Milestones, and Projects Back: Chapter 07: Merge Conflicts Related appendices: Appendix M: Accessibility Standards Appendix F: Git Security Appendix O: Branch Protection.

      +

      Alex: Keep the teaching thread moving. Start with Practical habits: Challenge Time: Complete Challenge 8: The Culture Layer in the Challenge Hub, then advance to Chapter 09: Labels, Milestones and Projects. The next useful detail is this: Next: Chapter 09: Labels, Milestones, and Projects Back: Chapter 07: Merge Conflicts Related appendices: Appendix M: Accessibility Standards Appendix F: Git Security Appendix O: Branch Protection. Think of it like entering a new building: first you find the lobby, then the room, then the door you actually need.

      Alex: The practical takeaway is this. 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.

      -

      Alex: Keep the teaching thread moving. The reason From First Paragraph to Polished Repository - Everything You Need to Know matters is that whether you have never written a single line of Markdown or you already know the basics and want to master the GitHub-specific extensions, this guide takes you from zero to confident. That gives the learner a simple foothold: we start with what Markdown is and why it matters, walk through every foundational element with examples, and then cover the GitHub Flavored Markdown (GFM) features you will encounter in real repositories - alert blocks, Mermaid diagrams, math, footnotes, and. The interface gets friendlier when it stops being a wall of controls and starts being a set of named places.

      -

      Jamie: Let's pause on Part 1 - Markdown Foundations. What should a learner take away from it?

      -

      Alex: Start with Markdown Foundations. There is something to understand, something to try, and something that proves the try worked.

      -

      Alex: First, what Is Markdown? Then, where You Will Use Markdown in This Workshop. After that, how to Practice as You Read. Finally, paragraphs and Line Breaks. Think of it as a rail line: each stop confirms you are still on the right route before the next one.

      -

      Jamie: Before we leave Part 1 - Markdown Foundations, what is the practical point?

      -

      Alex: First, headings. Then, emphasis - Bold, Italic, and Bold Italic. After that, strikethrough. Finally, lists - Ordered and Unordered. Treat it like a recipe: do not add the next ingredient until the previous one is actually in the bowl.

      -
      -

      Jamie: Let's pause on Part 2 - GitHub Flavored Markdown (GFM). What should a learner take away from it?

      -

      Alex: Start with GitHub Flavored Markdown (GFM). There is something to understand, something to try, and something that proves the try worked.

      -

      Alex: First, what Is GitHub Flavored Markdown? Then, alert and Callout Blocks. After that, collapsible Sections with Details and Summary. Finally, task List Checkboxes. Treat it like a recipe: do not add the next ingredient until the previous one is actually in the bowl.

      -

      Jamie: Before we leave Part 2 - GitHub Flavored Markdown (GFM), what is the practical point?

      -

      Alex: First, syntax Highlighting in Fenced Code Blocks. Then, mermaid Diagrams. After that, math Expressions with LaTeX. Finally, footnotes. It is a checklist, but a meaningful one: every item creates evidence that the next step is safe.

      -

      Jamie: Let's pause on Part 3 - Putting It All Together. What should a learner take away from it?

      -

      Alex: Start with Putting It All Together. There is something to understand, something to try, and something that proves the try worked.

      -

      Alex: First, screen Reader Behavior Summary. Then, accessible Markdown Authoring Checklist. After that, common Mistakes and How to Fix Them. Finally, your First Real Markdown Document - Guided Exercise. It is a checklist, but a meaningful one: every item creates evidence that the next step is safe.

      -

      Jamie: Before we leave Part 3 - Putting It All Together, what is the practical point?

      -

      Alex: First, quick-Reference Card. It is like walking a hallway with named doors: read the sign, enter the right room, then confirm where you landed.

      -

      Alex: Keep the teaching thread moving. Start with Learning Cards: Using This Markdown Reference. There is something to understand, something to try, and something that proves the try worked.

      -

      Alex: The practical takeaway is this. Use heading navigation (H key) to jump between numbered sections -- each topic is an h2 heading. Every section shows raw Markdown first, then rendered output, then screen reader behavior notes. The Table of Contents at the top has anchor links -- activate any link to jump directly to that section. Code blocks show the raw Markdown to type -- increase zoom and the monospace font stays readable. Each section follows the same pattern: explanation, raw code, rendered result, and accessibility notes. Use Ctrl+F to search for a specific Markdown element (e.g., search "table" or "heading").

      -
      -

      Jamie: Let's pause on 1. What Is Markdown? What should a learner take away from it?

      -

      Alex: The reason 1. What Is Markdown? matters is that markdown is a lightweight way to format plain text so it renders as rich, structured content - headings, bold text, links, lists, code blocks, tables, and more. That gives the learner a simple foothold: you write in a plain text file using simple punctuation characters, and a Markdown processor converts those characters into formatted output.

      -

      Alex: Keep the teaching thread moving. Start with A brief history: John Gruber created Markdown in 2004 with the goal of making a format that is "as easy to read and write as plain text." Since then, Markdown has become the default writing format.

      -

      Alex: The practical takeaway is this. GitHub (README files, issues, pull requests, comments, wikis, discussions). Stack Overflow and many developer forums. Static site generators (Jekyll, Hugo, Gatsby). Note-taking apps (Obsidian, Notion, Bear). Documentation systems (MkDocs, Docusaurus, Read the Docs). Chat platforms (Slack, Discord, Microsoft Teams).

      -

      Jamie: Let's pause on Markdown versus HTML. What should a learner take away from it?

      -

      Alex: Here is the plain-English version of Markdown versus HTML. Markdown converts to HTML behind the scenes. Put another way, when you write bold, GitHub converts it to bold.

      -

      Alex: Keep the teaching thread moving. This is where What gets rendered and what stays raw becomes real: when you view a.md file on GitHub, GitHub renders it automatically. That matters in practice: When you edit that file, you see the raw Markdown. The workshop is closer to rehearsal than lecture. You hear the move, try the move, and then check what changed.

      -

      Jamie: Where does the workshop stop being a tour and start becoming contribution?

      -

      Alex: Keep the learner anchored in 2. Where You Will Use Markdown in This Workshop. Markdown is not just one tool in this workshop - it is the thread that connects everything you do. This is the part to say slowly: Here is every place you will write or read Markdown during the two days.

      -

      Alex: Keep the teaching thread moving. The reason Day 1 - GitHub Foundations (Browser) matters is that the following table lists every Day 1 activity where Markdown is used.

      -
      -

      Jamie: How should they picture the shape of the workshop?

      -

      Alex: Start with Day 2 - VS Code and Accessibility Agents: The following table lists every Day 2 activity where Markdown is used.

      -

      Alex: Keep the teaching thread moving. Here is the plain-English version of Learning Room connection. In the Learning Room repository, every challenge description, every welcome file, and every piece of documentation is Markdown. Put another way, when you fix a broken link in docs/welcome.md for Challenge 1, you are editing Markdown. It is like learning a transit route. The names of the stops matter because they tell you whether you are still going the right direction.

      -

      Jamie: Let's pause on 3. How to Practice as You Read. What should a learner take away from it?

      -

      Alex: This is where 3. How to Practice as You Read becomes real: the best way to learn Markdown is to type it yourself. That matters in practice: Here are three ways to practice as you read this guide.

      -
      -

      Jamie: Let's pause on Option 1 - GitHub Issue (recommended for Day 1). What should a learner take away from it?

      -

      Alex: Keep the learner anchored in Option 1 - GitHub Issue (recommended for Day 1). The Write and Preview tabs are announced as tab buttons. This is the part to say slowly: Press Enter on "Preview" to switch.

      -

      Alex: First, go to any repository where you have write access (the Learning Room works). Then, click New Issue. After that, type Markdown in the issue body. Finally, click the Preview tab to see the rendered result. It is like walking a hallway with named doors: read the sign, enter the right room, then confirm where you landed.

      -

      Jamie: Before we leave Option 1 - GitHub Issue (recommended for Day 1), what is the practical point?

      -

      Alex: First, switch back to Write to keep editing. Then, you do not need to submit the issue - the Preview tab is your sandbox. The rhythm is simple: orient, act, verify, then continue.

      -

      Jamie: Let's pause on Option 2 - Any.md file in VS Code (recommended for Day 2). What should a learner take away from it?

      -

      Alex: Start with Option 2 - Any.md file in VS Code (recommended for Day 2). There is something to understand, something to try, and something that proves the try worked.

      -

      Alex: First, create a new file: Ctrl+N, then save it as practice.md. Then, type your Markdown in the editor. After that, press Ctrl+Shift+V to open the rendered Markdown preview in a new tab. Finally, the preview updates live as you type. The rhythm is simple: orient, act, verify, then continue.

      -

      Jamie: Let's pause on Option 3 - GitHub Gist. What should a learner take away from it?

      -

      Alex: Start with Option 3 - GitHub Gist. There is something to understand, something to try, and something that proves the try worked.

      -

      Alex: First, go to gist.github.com. Then, name your file practice.md. After that, type Markdown in the content area. Finally, click Create secret gist (only you can see it). Think of it as a rail line: each stop confirms you are still on the right route before the next one.

      -

      Jamie: Before we leave Option 3 - GitHub Gist, what is the practical point?

      -

      Alex: First, view the rendered result. Treat it like a recipe: do not add the next ingredient until the previous one is actually in the bowl.

      -
      -

      Jamie: Let's pause on 4. Paragraphs and Line Breaks. What should a learner take away from it?

      -

      Alex: Here is the plain-English version of 4. Paragraphs and Line Breaks. This is the most fundamental element in Markdown, and it trips up almost everyone at first.

      -

      Alex: Keep the teaching thread moving. This is where Paragraphs becomes real: a paragraph is one or more lines of text separated by a blank line (an empty line with nothing on it). That matters in practice: If you do not leave a blank line between two blocks of text, Markdown treats them as one continuous paragraph.

      -

      Jamie: Let's pause on Line breaks within a paragraph. What should a learner take away from it?

      -

      Alex: Keep the learner anchored in Line breaks within a paragraph. Sometimes you want to go to a new line without starting a whole new paragraph - for example, in an address or a poem. This is the part to say slowly: To create a line break (a in HTML), end a line with two or more spaces and then press Enter.

      -
      -

      Alex: Keep the teaching thread moving. The reason Common mistake - no blank line between paragraphs matters is that what renders (wrong): Both lines merge into one paragraph. That gives the learner a simple foothold: fix: Add a blank line between them. The interface gets friendlier when it stops being a wall of controls and starts being a set of named places.

      -

      Jamie: Let's pause on 5. Headings. What should a learner take away from it?

      -

      Alex: Start with 5. Headings: Headings create the structure of your document. The next useful detail is this: They are how screen readers navigate, how tables of contents are built, and how readers scan for the section they need.

      -

      Alex: Keep the teaching thread moving. Here is the plain-English version of Syntax. Add one to six characters at the start of a line, followed by a space, then the heading text. Put another way, the number of characters determines the heading level.

      -
      -

      Jamie: Let's pause on Rules for accessible headings. What should a learner take away from it?

      -

      Alex: This is where Rules for accessible headings becomes real: screen readers let you navigate by heading level. That matters in practice: In NVDA and JAWS, pressing H moves to the next heading.

      -

      Alex: First, one H1 per document. The heading is your document title. Every document gets exactly one. Then, never skip levels. Go from to, never from to. Skipping levels breaks the document outline for screen reader users who navigate by heading. After that, make headings descriptive. A heading of "Section 3" tells a screen reader user nothing. A heading of "Creating Your First Pull Request" tells them exactly what the section covers. Finally, do not use bold as a heading substitute. Writing My Section on its own line looks like a heading visually, but it is not a heading in the document structure. Screen reader users navigating by heading (H key in Browse Mode) will never find it. It is a checklist, but a meaningful one: every item creates evidence that the next step is safe.

      -

      Alex: Keep the teaching thread moving. Keep the learner anchored in Alternative heading syntax (not recommended). Markdown also supports "setext" headings where you underline text with = or - characters. This is the part to say slowly: This only works for levels 1 and 2, and it is harder to scan visually in raw Markdown. A good GitHub workflow is like a well-run meeting: everyone knows the topic, the next action, and who has the floor.

      -

      Jamie: Let's pause on 6. Emphasis - Bold, Italic, and Bold Italic. What should a learner take away from it?

      -

      Alex: The reason 6. Emphasis - Bold, Italic, and Bold Italic matters is that emphasis changes how text is read by screen readers - it is not just visual. That gives the learner a simple foothold: when text is bold or italic, well-configured screen readers can announce emphasis changes, giving the listener additional context about importance.

      -
      -

      Alex: Keep the teaching thread moving. Start with Bold: Wrap text in two asterisks or two underscores on each side. The next useful detail is this: This is bold text using underscores.

      -

      Jamie: Let's pause on Italic. What should a learner take away from it?

      -

      Alex: Here is the plain-English version of Italic. Wrap text in one asterisk or one underscore on each side. Put another way, this is italic text using asterisks.

      -

      Alex: Keep the teaching thread moving. This is where Bold and italic combined becomes real: wrap text in three asterisks on each side. The workshop is closer to rehearsal than lecture. You hear the move, try the move, and then check what changed.

      -
      -

      Jamie: Can you translate that into plain choices?

      -

      Alex: Keep the learner anchored in When to use emphasis. The following table provides guidance on when to use each type of emphasis. This is the part to say slowly: NVDA can announce emphasis changes if the user enables "Report font attributes" (under Speech settings).

      -

      Alex: Use the comparison to make a decision, not to recite a table. The main contrasts are: Key terms, important warnings, UI element names means "Click the Submit button". Book or document titles, introducing new terms, gentle emphasis means "See the Contributing Guide for details". Bold italic means Extremely rare - critical warnings only means " Do not force push to the main branch ".

      -

      Alex: Keep the teaching thread moving. The reason Emphasis inside words matters is that underscores do not (in most Markdown processors including GitHub). That gives the learner a simple foothold: use asterisks when you need emphasis inside a word (rare, but it comes up in technical documentation).

      -

      Jamie: Let's pause on 7. Strikethrough. What should a learner take away from it?

      -

      Alex: Start with 7. Strikethrough: Strikethrough text shows deleted or outdated content with a line through it. The next useful detail is this: Wrap text in two tildes on each side.

      -
      -

      Alex: Keep the teaching thread moving. Here is the plain-English version of 8. Lists - Ordered and Unordered. Lists are one of the most common elements in GitHub documentation. Put another way, issue descriptions, PR checklists, README instructions, step-by-step guides - they all use lists. It is like learning a transit route. The names of the stops matter because they tell you whether you are still going the right direction.

      -

      Jamie: Let's pause on Unordered lists (bullet points). What should a learner take away from it?

      -

      Alex: This is where Unordered lists (bullet points) becomes real: start each line with a dash (-), asterisk ( ), or plus sign (+) followed by a space. That matters in practice: They are the most common convention on GitHub and visually distinct from the asterisks used for bold and italic.

      -

      Alex: The practical takeaway is this. First item. Second item. Third item.

      -

      Jamie: Let's pause on Ordered lists (numbered). What should a learner take away from it?

      -

      Alex: Keep the learner anchored in Ordered lists (numbered). Start each line with a number followed by a period and a space.

      -

      Alex: First, clone the repository. Then, create a new branch. After that, make your changes. Finally, open a pull request. It is like walking a hallway with named doors: read the sign, enter the right room, then confirm where you landed.

      -
      -

      Jamie: What do you want them to do when the plan breaks?

      -

      Alex: The reason A helpful trick - Markdown renumbers for you matters is that here is something that surprises most new users. That gives the learner a simple foothold: in Markdown, the actual numbers you type do not matter for the rendered output.

      -

      Alex: Keep the teaching thread moving. Start with Starting an ordered list at a specific number: If you need a list to start at a number other than 1, use that number for the first item. The next useful detail is this: All subsequent items are numbered sequentially from there. Think of it like entering a new building: first you find the lobby, then the room, then the door you actually need.

      -

      Jamie: Let's pause on 9. Nested Lists and Mixed Lists. What should a learner take away from it?

      -

      Alex: Here is the plain-English version of 9. Nested Lists and Mixed Lists. Lists can contain other lists, creating an indented hierarchy. Put another way, this is essential for complex instructions, outlines, and project structures.

      -
      -

      Jamie: Let's pause on Nesting unordered lists. What should a learner take away from it?

      -

      Alex: This is where Nesting unordered lists becomes real: indent the nested items by two or four spaces (GitHub accepts either, but four is most reliable).

      -

      Alex: The practical takeaway is this. Accessibility testing tools. Screen readers. NVDA (Windows, free). JAWS (Windows, commercial). VoiceOver (macOS and iOS, built-in). Browser extensions.

      -

      Alex: Treat examples as spoken recipes, not decorations. You may hear something like Accessibility testing tools; - Screen readers; - NVDA (Windows, free); - JAWS (Windows, commercial); - VoiceOver (macOS and iOS, built-in); - Browser extensions; - axe DevTools; - WAVE; - Documentation tools; - Markdown editors; - Static site generators. Read the command, understand what it changes, then run it only when the repository state matches the lesson.

      -

      Jamie: Let's pause on Nesting ordered lists. What should a learner take away from it?

      -

      Alex: Keep the learner anchored in Nesting ordered lists. The same indentation principle applies to numbered lists.

      -

      Alex: Keep the teaching thread moving. The reason Mixing ordered and unordered lists matters is that you can nest an unordered list inside an ordered list and vice versa. The interface gets friendlier when it stops being a wall of controls and starts being a set of named places.

      +

      Jamie: What should people carry with them after this?

      +

      Alex: Carry the map. Know what page or tool you are in, know which action you are taking, and know what confirmation should follow. If the confirmation is missing, pause. That pause is not wasted time; it is professional judgment.

      +

      Jamie: That is a better way to say it than just follow the steps.

      +

      Alex: Right. Steps matter, but understanding wins. That is episode 37. Next in the series is episode 38, where we keep building the same contributor muscles.

      +
      +
      -

      Jamie: Let's pause on Adding content inside list items. What should a learner take away from it?

      -

      Alex: Start with Adding content inside list items: List items can contain paragraphs, code blocks, and other elements. The next useful detail is this: Indent the content to align with the list item text (typically four spaces).

      -

      Alex: Treat examples as spoken recipes, not decorations. You may hear something like Clone the repository; Open your terminal and run the following command. Read the command, understand what it changes, then run it only when the repository state matches the lesson.

      -

      Alex: Keep the teaching thread moving. Here is the plain-English version of 10. Links. Links are how you connect documents, reference issues, point to external resources, and cite sources. Put another way, getting links right is critical for accessibility - links with bad text are one of the most common accessibility failures in documentation.

      -

      Jamie: Let's pause on Basic link syntax. What should a learner take away from it?

      -

      Alex: This is where Basic link syntax becomes real: wrap the visible link text in square brackets, followed immediately by the URL in parentheses.

      +

      67. Challenge bonus-b: Document Your Journey

      +

      Reflective documentation, portfolio language, and accessible Markdown.

      +

      Practice focus: Bonus

      +

      Audio and transcript are being regenerated for this episode.

      +
      +Read Transcript - Challenge bonus-b: Document Your Journey + +

      Transcript

      +

      Alex: Welcome back to Challenge Coach. Today we are taking on Document Your Journey, one careful step at a time.

      +

      Jamie: And I am Jamie. I am listening for the confusing parts: where to start, what to submit, and how to tell whether it worked.

      -

      Alex: Keep the teaching thread moving. Keep the learner anchored in Links with title text. Add a title in quotes after the URL. This is the part to say slowly: The title appears as a tooltip on hover. A good GitHub workflow is like a well-run meeting: everyone knows the topic, the next action, and who has the floor.

      -

      Jamie: Let's pause on Writing accessible link text. What should a learner take away from it?

      -

      Alex: The reason Writing accessible link text matters is that this is one of the most important accessibility skills in Markdown authoring. That gives the learner a simple foothold: screen reader users often navigate by pulling up a list of all links on a page (NVDA: NVDA+F7 then select Links; JAWS: Insert+F7).

      -

      Alex: Keep the teaching thread moving. Start with Reference-style links: For documents with many links, reference-style links keep the text readable by separating the URL from the prose. The next useful detail is this: You define the link target once at the bottom of the document.

      +

      Alex: In this challenge, the learner is practicing reflective documentation, portfolio language, and accessible Markdown. The point is not to rush. The point is to leave a clear trace of good work.

      +

      Jamie: So we should name what success sounds like before the learner starts clicking or typing.

      +

      Alex: Yes. When the checkpoint is clear, the learner can tell the difference between being stuck and simply not being finished yet.

      -

      Jamie: Let's pause on Relative links within a repository. What should a learner take away from it?

      -

      Alex: Here is the plain-English version of Relative links within a repository. When linking to other files in the same repository, use relative paths instead of full URLs. Put another way, this way, links work on any fork or branch.

      -

      Alex: Keep the teaching thread moving. This is where Email links becomes real: the angle brackets tell Markdown to create a mailto: link. The workshop is closer to rehearsal than lecture. You hear the move, try the move, and then check what changed.

      -

      Jamie: Let's pause on Autolinked URLs. What should a learner take away from it?

      -

      Alex: Keep the learner anchored in Autolinked URLs. GitHub automatically converts full URLs in your text into clickable links, but always prefer explicit descriptive links in prose. This is the part to say slowly: Bare URLs should only appear in reference sections or code examples.

      +

      Jamie: Okay, set the room for us. What are we walking into?

      +

      Alex: Start with Bonus B: Document Your Journey: For students who: Enjoy writing and reflection. The next useful detail is this: What you will do: Write a structured reflection about your workshop experience, using proper Markdown formatting.

      +

      Jamie: How would you walk the room through that step by step?

      +

      Alex: Start with Instructions. There is something to understand, something to try, and something that proves the try worked.

      +

      Alex: First, create a new file on your branch: reflections/YOUR-USERNAME.md. Then, use this structure. After that, commit with a meaningful message and open a PR. Treat it like a recipe: do not add the next ingredient until the previous one is actually in the bowl.

      +

      Jamie: What is the one idea that makes the next few steps less mysterious?

      +

      Alex: This is where What matters becomes real: the learning objective is structured reflection using proper Markdown. That matters in practice: If you wrote a document with headings, paragraphs, and honest reflection, you completed this bonus.

      -

      Alex: Keep the teaching thread moving. Start with Learning Cards: Links. There is something to understand, something to try, and something that proves the try worked.

      -

      Alex: The practical takeaway is this. Pull up a links list (NVDA: NVDA+F7 then Links tab; JAWS: Insert+F7) to audit your document -- every link must make sense without its surrounding sentence. Reference-style links ([text][ref]) produce identical HTML to inline links -- screen readers announce them the same way, so choose whichever keeps your source readable. Relative links to other repo files (e.g., Setup) work on any fork or branch -- prefer them over full URLs for internal documentation. Links render as blue underlined text by default -- if your GitHub theme reduces underline visibility, rely on the color difference or hover state to identify links. Long URLs in link text are hard to read at high zoom; always use descriptive text like Contributing Guide instead of pasting the raw URL. The title attribute (text in quotes after the URL) appears as a tooltip on hover -- useful at high magnification but do not put essential information only there.

      -

      Jamie: Let's pause on 11. Images. What should a learner take away from it?

      -

      Alex: Start with 11. Images: Images in Markdown use a syntax similar to links, with an exclamation mark (!) at the beginning.

      -

      Alex: Keep the teaching thread moving. Here is the plain-English version of Syntax. The text inside the square brackets is the alt text - the description that screen readers read aloud instead of displaying the image. Put another way, this is the single most important accessibility attribute for images. It is like learning a transit route. The names of the stops matter because they tell you whether you are still going the right direction.

      +

      Alex: Now bring the learner back to the room. Keep the learner anchored in How to Be an Effective and Respectful Open Source Contributor. Technical skills get your code into a project. This is the part to say slowly: Communication skills keep you welcomed in the community.

      +

      Jamie: Where is the promise of the workshop, underneath all the logistics?

      +

      Alex: The reason Workshop Recommendation (Chapter 8) matters is that chapter 8 is a communication and culture chapter.

      +

      Alex: The parts worth keeping in working memory are these. There are 1 guided reflection (no bot grading). Automation check: none - communication quality is too subjective for fair automated scoring. The evidence is structured reflection comment on your assigned challenge issue. The pattern is read, reflect, commit to one behavior.

      +

      Alex: The useful habit is simple: orient first, act second, verify third. That pause before acting is part of the work.

      +

      Jamie: Give me the sequence, because order matters here.

      +

      Alex: Start with Chapter 8 Challenge Set. There is something to understand, something to try, and something that proves the try worked.

      +

      Alex: First, guided reflection - read the chapter, then post a short reflection comment committing to three specific collaboration behaviors. Think of it as a rail line: each stop confirms you are still on the right route before the next one.

      -

      Jamie: Let's pause on Writing good alt text. What should a learner take away from it?

      -

      Alex: This is where Writing good alt text becomes real: the following table provides guidance on alt text for different types of images.

      -

      Alex: Keep the teaching thread moving. Keep the learner anchored in Image with a link. To make an image clickable, wrap the image syntax inside a link.

      -

      Jamie: Let's pause on When to use details blocks for complex images. What should a learner take away from it?

      -

      Alex: The reason When to use details blocks for complex images matters is that if an image contains complex information (like an architecture diagram or a data visualization), provide a full text description in a collapsible block. That gives the learner a simple foothold: screen readers announce images as "graphic" followed by the alt text.

      +

      Jamie: What does the learner do first, second, and then after that?

      +

      Alex: Here is the plain-English version of Challenge 8.1 Step-by-Step: Guided Reflection. Identify three concrete communication behaviors you will practice during the rest of the workshop. Put another way, your assigned Chapter 8 challenge issue in your Learning Room repository on GitHub.com.

      +

      Alex: Here is what that changes in practice. 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.".

      +

      Alex: First, read through the chapter content below, paying attention to the sections on GitHub Flow, constructive feedback, and asking for help. Then, as you read, think about one situation from Day 1 where communication helped (or could have helped) you. After that, open your assigned Chapter 8 challenge issue (the one titled "Chapter 8.1: Guided Reflection (@yourname)"). Finally, scroll to the comment box at the bottom of the issue. Treat it like a recipe: do not add the next ingredient until the previous one is actually in the bowl.

      +

      Jamie: Turn that into a path someone can follow.

      +

      Alex: First, post a reflection comment using this format. Then, for each prompt, write one specific, actionable sentence - not a vague goal. After that, activate the Comment button (or press Ctrl+Enter). It is a checklist, but a meaningful one: every item creates evidence that the next step is safe.

      +

      Alex: This is where the talk moves from concept to action. This is where Completing Chapter 8: Submit Your Evidence becomes real: the reflection comment itself is your evidence. That matters in practice: The facilitator reviews your comment for specificity.

      +

      Jamie: Where do you want a learner to place their attention here?

      +

      Alex: Start with Expected Outcomes. There is something to understand, something to try, and something that proves the try worked.

      +

      Alex: These are the details that keep the idea from floating away. 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.

      -

      Alex: Keep the teaching thread moving. Start with Learning Cards: Images. There is something to understand, something to try, and something that proves the try worked.

      -

      Alex: The practical takeaway is this. Alt text is read aloud as the only representation of the image -- write it to answer "what information does this image convey?" not just "what does it look like?". For decorative images, use empty alt text ( ) so the screen reader skips them entirely rather than announcing the filename. Complex images (architecture diagrams, charts) need a full text description in a block below the image -- expand it to read the complete information. Images render at their original size by default -- use browser or VS Code zoom to enlarge them, and ensure alt text is present in case the image becomes too pixelated. Screenshots with small text are the hardest images to read at high magnification -- request that contributors use cropped, focused screenshots instead of full-screen captures. The alt text is invisible in the rendered view but visible in the raw Markdown source -- switch to the source view to verify alt text exists on all images.

      -

      Jamie: Let's pause on 12. Blockquotes. What should a learner take away from it?

      -

      Alex: Here is the plain-English version of 12. Blockquotes. Blockquotes are used for callouts, important notes, cited text, and instructor guidance throughout this course. Put another way, start each line with a character followed by a space.

      -

      Alex: Keep the teaching thread moving. This is where Basic blockquote becomes real: it is used to highlight important information or to quote someone else's text.

      +

      Jamie: What is the ordered workflow?

      +

      Alex: Start with If You Get Stuck. There is something to understand, something to try, and something that proves the try worked.

      +

      Alex: First, use one simple sentence per prompt - do not overthink it. Then, focus on one real behavior you can start doing today, not an abstract principle. After that, if writing feels hard, draft bullet points first in a text editor, then paste into the comment. Finally, look at the "Giving Feedback" and "Asking for Help" sections in this chapter for concrete examples. The rhythm is simple: orient, act, verify, then continue.

      +

      Jamie: Let's pause on If You Get Stuck. What should a learner take away from it?

      +

      Alex: First, ask facilitator for one example response and adapt it to your own words. Then, finished but not sure you did it right? Compare your work against the Challenge 8 reference solution. Think of it as a rail line: each stop confirms you are still on the right route before the next one.

      +

      Jamie: What would you say to someone who is already bracing for this to be too much?

      +

      Alex: Start with Learning Moment: Technical quality and communication quality work together. The next useful detail is this: Respectful, clear communication helps good code get merged faster.

      +

      Jamie: Let's pause on Learning Pattern Used in This Chapter. What should a learner take away from it?

      +

      Alex: Start with Learning Pattern Used in This Chapter. There is something to understand, something to try, and something that proves the try worked.

      +

      Alex: First, read and absorb community norms (not just rules, but reasons). Then, reflect on personal experience (what worked, what was hard). After that, commit to specific behaviors in writing (public accountability). Finally, apply those behaviors in upcoming chapters (reviews, comments, PRs). Treat it like a recipe: do not add the next ingredient until the previous one is actually in the bowl.

      -

      Jamie: Let's pause on Multi-paragraph blockquotes. What should a learner take away from it?

      -

      Alex: Keep the learner anchored in Multi-paragraph blockquotes. Add a on the blank lines between paragraphs to keep them inside the blockquote.

      -

      Alex: Keep the teaching thread moving. The reason Blockquotes with other elements matters is that blockquotes can contain any Markdown element - headings, lists, code, bold, links. That gives the learner a simple foothold: screen readers announce the beginning and end of a blockquote. The interface gets friendlier when it stops being a wall of controls and starts being a set of named places.

      -

      Jamie: Zoom out for a second. What kind of journey is this?

      -

      Alex: Start with How we use blockquotes in this course: Throughout this workshop, blockquotes serve specific purposes.

      -

      Alex: The practical takeaway is this. Screen reader notes: Tips specific to assistive technology users. Learning Room connections: How the current topic connects to the practice repo. Important warnings: Critical information that could prevent errors. Instructor guidance: Notes from the facilitator about pacing or approach.

      +

      Jamie: If I am listening before the workshop starts, what should settle in my mind first?

      +

      Alex: This is where GitHub Flow - The Standard Contribution Workflow becomes real: before diving into communication norms, it helps to understand the workflow that gives all of those conversations their context. That matters in practice: GitHub Flow is the lightweight branching model recommended for open source contribution.

      +

      Alex: That connects to another useful point. Start with Why This Model Works. There is something to understand, something to try, and something that proves the try worked.

      +

      Alex: For a learner, the useful signals are these. 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.

      +

      Jamie: Give me the version that sounds like an instructor, not a manual.

      +

      Alex: The reason GitHub Flow vs Git Flow matters is that you may encounter "Git Flow" (sometimes written "GitFlow") in older projects or enterprise environments. That gives the learner a simple foothold: this section explains what Git Flow is, how it differs from GitHub Flow, and why this workshop teaches GitHub Flow.

      +

      Alex: A solid Git habit is to know which branch you are on, what changed, and what confirmation you expect before you run the next command.

      -

      Alex: Keep the teaching thread moving. Here is the plain-English version of 13. Inline Code and Code Blocks. Code formatting is essential on GitHub. Put another way, the learner will use it for command-line instructions, file names, configuration values, keyboard shortcuts, and actual source code.

      -

      Jamie: Let's pause on Inline code. What should a learner take away from it?

      -

      Alex: This is where Inline code becomes real: wrap text in single backticks ( `) to format it as code within a sentence. That matters in practice: Run git status to see which files have changed.

      -

      Alex: The practical takeaway is this. Command names: git clone, npm install. File names: README.md, CONTRIBUTING.md. Keyboard shortcuts: Ctrl+C, Alt+Tab. Variable or function names: userName, getElementById().

      -

      Alex: Treat examples as spoken recipes, not decorations. You may hear something like Run git status to see which files have changed.; The configuration file is package.json.; Press Ctrl+Shift+P to open the Command Palette. Read the command, understand what it changes, then run it only when the repository state matches the lesson.

      -

      Alex: Keep the teaching thread moving. Keep the learner anchored in Code blocks (fenced). For multi-line code, wrap it in triple backticks ( ` ) on their own lines. This is the part to say slowly: All formatting is preserved exactly. A good GitHub workflow is like a well-run meeting: everyone knows the topic, the next action, and who has the floor.

      +

      Alex: Here is the practical turn. Start with What Git Flow Is: Git Flow is a branching model published by Vincent Driessen in 2010. The next useful detail is this: It was designed for teams that ship versioned releases on a schedule (desktop software, mobile apps, embedded systems).

      +

      Jamie: Let's pause on How the Git Flow Cycle Works. What should a learner take away from it?

      +

      Alex: Start with How the Git Flow Cycle Works. There is something to understand, something to try, and something that proves the try worked.

      +

      Alex: First, developers branch feature/my-feature off develop and work there. Then, completed features merge back into develop via pull request. After that, when develop has enough features for a release, a release/1.2.0 branch is created. Finally, the release branch gets final testing, bug fixes, and version number updates. Treat it like a recipe: do not add the next ingredient until the previous one is actually in the bowl.

      +

      Jamie: Before we leave How the Git Flow Cycle Works, what is the practical point?

      +

      Alex: First, the release branch merges into main (tagged with the version) and back into develop. Then, if a critical bug is found in production, a hotfix/ branch is created from main, fixed, and merged into both main and develop. It is a checklist, but a meaningful one: every item creates evidence that the next step is safe.

      +

      Alex: Keep the thread going. This is where How GitHub Flow Differs becomes real: the following table compares GitHub Flow and Git Flow across key dimensions. The workshop is closer to rehearsal than lecture. You hear the move, try the move, and then check what changed.

      +

      Alex: A solid pull request habit is to separate three questions: what changed, why it changed, and what still needs review. That keeps the conversation useful instead of noisy.

      -

      Jamie: Let's pause on Code blocks with syntax highlighting. What should a learner take away from it?

      -

      Alex: The reason Code blocks with syntax highlighting matters is that add a language identifier right after the opening triple backticks to enable syntax highlighting. That gives the learner a simple foothold: def greet(name: str) - str: """Return a greeting for the given name.""" return f"Hello, {name}!

      -

      Alex: Keep the teaching thread moving. Start with Showing diffs in code blocks: The diff language identifier highlights additions and removals. The next useful detail is this: + new line that was added unchanged context line.

      -

      Alex: The practical takeaway is this. old line that was removed.

      -

      Jamie: Let's pause on Code blocks inside list items. What should a learner take away from it?

      -

      Alex: Here is the plain-English version of Code blocks inside list items. Indent the code block to align with the list item text.

      +

      Jamie: Let's pause on When You Might See Git Flow. What should a learner take away from it?

      +

      Alex: Start with When You Might See Git Flow. There is something to understand, something to try, and something that proves the try worked.

      +

      Alex: That becomes easier when you listen for these cues. 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.

      +

      Alex: Another way to ground it. The reason Why This Workshop Uses GitHub Flow matters is that for open source contribution - especially at a hackathon or when contributing to web-based projects - GitHub Flow is what you want. That gives the learner a simple foothold: it is what GitHub itself uses and what most modern open source projects follow.

      +

      Jamie: Let's pause on The Unwritten Rule: One Thing Per Branch. What should a learner take away from it?

      +

      Alex: Start with The Unwritten Rule: One Thing Per Branch: A branch and its PR should do one thing. The next useful detail is this: If you are fixing a broken link and you notice a typo nearby, fix the typo in a separate branch and PR.

      -

      Alex: Keep the teaching thread moving. This is where How to show literal backticks becomes real: if your code contains backticks, use more backticks for the fence. That matters in practice: Use four backticks to wrap content that contains triple backticks. The workshop is closer to rehearsal than lecture. You hear the move, try the move, and then check what changed.

      -

      Jamie: Let's pause on 14. Horizontal Rules. What should a learner take away from it?

      -

      Alex: Keep the learner anchored in 14. Horizontal Rules. A horizontal rule creates a thematic break between sections - a visual line across the page. This is the part to say slowly: Use three or more dashes, asterisks, or underscores on a line by themselves.

      -

      Alex: Keep the teaching thread moving. The reason 15. Escaping Special Characters matters is that many characters have special meaning in Markdown. That gives the learner a simple foothold: if you want to display them as literal characters instead, put a backslash () before them.

      +

      Alex: This is the part worth saying out loud. Start with Learning Cards: GitHub Flow. There is something to understand, something to try, and something that proves the try worked.

      +

      Alex: The practical anchors are these. 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). 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.

      +

      Jamie: Let's pause on Keeping Your Fork Up to Date. What should a learner take away from it?

      +

      Alex: This is where Keeping Your Fork Up to Date becomes real: when you fork a repository, you get a snapshot of the project at that moment. That matters in practice: The original repository (called "upstream") continues to evolve.

      +

      Alex: The next layer is this. Start with Why Sync Your Fork? There is something to understand, something to try, and something that proves the try worked.

      +

      Alex: On the ground, that means a few things. 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.

      -

      Jamie: Let's pause on Characters that can be escaped. What should a learner take away from it?

      -

      Alex: Start with Characters that can be escaped: The following table lists every character that can be escaped in Markdown.

      -

      Alex: Keep the teaching thread moving. Here is the plain-English version of Examples. This asterisk is literal: \ not bold\ This hash is literal: \ not a heading Show a pipe character: . It is like learning a transit route. The names of the stops matter because they tell you whether you are still going the right direction.

      -

      Jamie: Let's pause on 16. Tables. What should a learner take away from it?

      -

      Alex: This is where 16. Tables becomes real: tables organize data into rows and columns. That matters in practice: They are used extensively on GitHub for comparison charts, reference data, settings documentation, and checklists.

      +

      Jamie: Let's pause on Method 1: GitHub Web Interface (Easiest). What should a learner take away from it?

      +

      Alex: The reason Method 1: GitHub Web Interface (Easiest) matters is that GitHub merges the upstream changes into your fork automatically. That gives the learner a simple foothold: screen reader users (NVDA / JAWS / VoiceOver).

      +

      Alex: First, navigate to your fork's main page: github.com/your-username/repo-name. Then, look for the sync indicator: "This branch is X commits behind upstream/main". After that, click the "Sync fork" button. Finally, click "Update branch". The rhythm is simple: orient, act, verify, then continue.

      +

      Jamie: Before we leave Method 1: GitHub Web Interface (Easiest), what is the practical point?

      +

      Alex: First, the sync button appears in the landmark that contains the branch selector. Then, press D to cycle through landmarks until you reach that region. After that, press B to cycle buttons until you hear "Sync fork" → press Enter. Finally, a dialog or page update presents "Update branch" - activate it. Think of it as a rail line: each stop confirms you are still on the right route before the next one.

      +

      Alex: That matters because of the next idea. Start with Method 2: Git Command Line (VS Code Terminal): If you're working locally in VS Code. Think of it like entering a new building: first you find the lobby, then the room, then the door you actually need.

      +

      Jamie: What is the safe way to learn from that example?

      +

      Alex: Start with One-time setup - add the upstream remote. There is something to understand, something to try, and something that proves the try worked.

      +

      Alex: Treat examples as spoken recipes, not decorations. You may hear something like git remote add upstream https://github.com/original-owner/repo-name.git; git remote -v Verify it was added. Read the command, understand what it changes, then run it only when the repository state matches the lesson.

      -

      Jamie: Let's pause on Basic table syntax. What should a learner take away from it?

      -

      Alex: Start with Basic table syntax. There is something to understand, something to try, and something that proves the try worked.

      -

      Alex: Treat examples as spoken recipes, not decorations. You may hear something like Name Role Platform; --- --- ---; NVDA Screen reader Windows; JAWS Screen reader Windows; VoiceOver Screen reader macOS / iOS; TalkBack Screen reader Android. Read the command, understand what it changes, then run it only when the repository state matches the lesson.

      -

      Jamie: Let's pause on How table syntax works. What should a learner take away from it?

      -

      Alex: Start with How table syntax works. There is something to understand, something to try, and something that proves the try worked.

      -

      Alex: The practical takeaway is this. The first row is always the header row. The second row contains dashes (---) that separate the header from the data. You need at least three dashes per column. Each subsequent row is a data row. Columns are separated by pipe characters ( ). Leading and trailing pipes are optional but recommended for readability.

      -

      Alex: Keep the teaching thread moving. Start with Column alignment: Add colons (:) to the separator row to control text alignment. Think of it like entering a new building: first you find the lobby, then the room, then the door you actually need.

      -

      Alex: The practical takeaway is this.:--- = left aligned (default).:---: = center aligned. ---: = right aligned.

      +

      Jamie: What should happen before anyone copies and runs it?

      +

      Alex: Start with Sync process. There is something to understand, something to try, and something that proves the try worked.

      +

      Alex: Treat examples as spoken recipes, not decorations. You may hear something like 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. Read the command, understand what it changes, then run it only when the repository state matches the lesson.

      +

      Jamie: Let's pause on When to sync. What should a learner take away from it?

      +

      Alex: Start with When to sync. There is something to understand, something to try, and something that proves the try worked.

      +

      Alex: A few details make that real. 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).

      +

      Jamie: Let's pause on Method 3: GitHub Desktop. What should a learner take away from it?

      +

      Alex: Start with Method 3: GitHub Desktop. There is something to understand, something to try, and something that proves the try worked.

      +

      Alex: First, open GitHub Desktop. Then, select Repository → Pull to get your fork's latest. After that, select Branch → Merge into Current Branch. Finally, choose upstream/main. The rhythm is simple: orient, act, verify, then continue.

      +

      Jamie: Before we leave Method 3: GitHub Desktop, what is the practical point?

      +

      Alex: First, push the changes to your fork on GitHub. Think of it as a rail line: each stop confirms you are still on the right route before the next one.

      -

      Jamie: Let's pause on Formatting inside table cells. What should a learner take away from it?

      -

      Alex: Here is the plain-English version of Formatting inside table cells. You can use inline formatting within table cells.

      -

      Jamie: Let's pause on Accessibility considerations for tables. What should a learner take away from it?

      -

      Alex: This is where Accessibility considerations for tables becomes real: screen readers navigate tables with Ctrl+Alt+Arrow keys (NVDA and JAWS). That matters in practice: Ctrl+Alt+Right moves to the next column.

      -

      Alex: First, always include a description before the table. Add a one-sentence summary immediately above the table explaining what it contains. Screen reader users hear the table structure (rows and columns) but benefit from knowing what the table is about before entering. Then, keep tables simple. Tables with more than 5-6 columns become difficult to navigate with a screen reader. Consider splitting wide tables into multiple narrower tables. After that, use tables for data, not layout. If you are using a table just to arrange content side by side, use a list instead. Finally, make the header row descriptive. The header cell is announced before each data cell when navigating by column, so "Platform" is better than "Col 3". It is a checklist, but a meaningful one: every item creates evidence that the next step is safe.

      -

      Jamie: Let's pause on When not to use a table. What should a learner take away from it?

      -

      Alex: Keep the learner anchored in When not to use a table. If your "table" has only two columns where the first is a label and the second is a value, consider using a definition-style list or bold labels instead. This is the part to say slowly: This is often easier to read with a screen reader than a two-column table.

      +

      Jamie: Let's pause on Learning Cards: Keeping Your Fork Up to Date. What should a learner take away from it?

      +

      Alex: Start with Learning Cards: Keeping Your Fork Up to Date. There is something to understand, something to try, and something that proves the try worked.

      +

      Alex: That shows up in the workshop in a few specific ways. 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. 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.

      +

      Alex: Before the learner moves on. Here is the plain-English version of Writing Good Commit Messages. Every commit you make includes a message describing what changed. Put another way, good commit messages make project history understandable months or years later.

      +

      Jamie: Let's pause on The First Line (Required). What should a learner take away from it?

      +

      Alex: This is where The First Line (Required) becomes real: this is the commit summary that appears in logs and GitHub's commit list. That matters in practice: Think of it as an email subject line.

      +

      Alex: The room should hear these as checkpoints. fix: - bug fix. feat: - new feature. docs: - documentation only. style: - formatting, no code change.

      -

      Alex: Keep the teaching thread moving. Start with Learning Cards: Tables. There is something to understand, something to try, and something that proves the try worked.

      -

      Alex: The practical takeaway is this. Navigate tables with Ctrl+Alt+Arrow keys (NVDA/JAWS) -- Right moves to the next column, Down to the next row; the column header is announced each time you change columns. Enter table mode automatically when your screen reader encounters a table -- press T in browse mode to jump to the next table on the page. Before the table structure, listen for the description sentence the author should place above it -- this tells you what data the table contains before you enter cell-by-cell navigation. Wide tables (6+ columns) may require horizontal scrolling at high zoom -- if the table overflows, scroll right to see truncated columns or view the raw Markdown source instead. Column alignment (left, center, right) is controlled by colons in the separator row -- at high magnification, right-aligned numbers are easier to compare than left-aligned ones. If a table is hard to read at your zoom level, try narrowing the browser window -- GitHub will sometimes reflow content or add a horizontal scrollbar.

      -

      Jamie: Let's pause on Learning Cards: GitHub Flavored Markdown. What should a learner take away from it?

      -

      Alex: Start with Learning Cards: GitHub Flavored Markdown. There is something to understand, something to try, and something that proves the try worked.

      -

      Alex: The practical takeaway is this. GFM features (sections 17-27) work only on GitHub -- your screen reader behavior notes are in each section. Alert blocks (section 18) render as blockquotes with a type prefix -- listen for "Note," "Warning," etc. Task list checkboxes (section 20) are announced as "checkbox checked" or "checkbox not checked". Alert blocks use color-coded left borders (blue for Note, yellow for Warning, red for Caution) -- the text label also identifies the type. Mermaid diagrams (section 22) are visual only on GitHub -- the raw code block is always readable. Use GitHub's Preview tab when writing to confirm your GFM renders correctly before submitting.

      -

      Alex: Keep the teaching thread moving. Here is the plain-English version of 17. What Is GitHub Flavored Markdown? GitHub Flavored Markdown (GFM) is GitHub's own superset of standard Markdown. Put another way, it takes everything from the CommonMark specification (the modern standard for Markdown) and adds features specifically designed for software collaboration: tables, task lists, strikethrough, autolinked references, alert blocks, Mermaid diagrams, math.

      +

      Jamie: How do you keep commands from becoming magic words?

      +

      Alex: Keep the learner anchored in The Body (Optional). If the summary isn't enough, add a body explaining. This is the part to say slowly: Leave a blank line between the summary and the body. A good GitHub workflow is like a well-run meeting: everyone knows the topic, the next action, and who has the floor.

      +

      Alex: The practical takeaway is this. Why you made the change (more important than what). What trade-offs you considered. How the change affects behavior.

      +

      Alex: Treat examples as spoken recipes, not decorations. You may hear something like 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. Read the command, understand what it changes, then run it only when the repository state matches the lesson.

      +

      Jamie: Let's pause on The Footer (Optional). What should a learner take away from it?

      +

      Alex: The reason The Footer (Optional) matters is that when the commit is merged, GitHub automatically closes linked issues.

      +

      Alex: Hold that next to this. Start with Atomic Commits: Each commit should represent one logical change. The next useful detail is this: Don't bundle unrelated fixes into a single commit.

      -

      Jamie: Let's pause on Where GFM works. What should a learner take away from it?

      -

      Alex: This is where Where GFM works becomes real: the following table shows where GFM is supported.

      -

      Alex: Keep the teaching thread moving. Keep the learner anchored in 18. Alert and Callout Blocks. GitHub introduced alert blocks in 2023. This is the part to say slowly: They render as colored, bordered callout boxes - great for emphasizing warnings, tips, or critical information. A good GitHub workflow is like a well-run meeting: everyone knows the topic, the next action, and who has the floor.

      -

      Jamie: Let's pause on How to write them. What should a learner take away from it?

      -

      Alex: Start with How to write them. There is something to understand, something to try, and something that proves the try worked.

      -

      Alex: First, start a blockquote. Then, the first line must be exactly [!TYPE] where TYPE is one of: NOTE, TIP, IMPORTANT, WARNING, CAUTION. After that, all subsequent lines start with and a space, just like a regular blockquote. Finally, you can include any Markdown inside the alert: lists, code, links, bold. The rhythm is simple: orient, act, verify, then continue.

      +

      Jamie: Let's pause on Common mistakes to avoid. What should a learner take away from it?

      +

      Alex: Start with Common mistakes to avoid. There is something to understand, something to try, and something that proves the try worked.

      +

      Alex: The practical takeaway is this. "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.

      +

      Jamie: What should they understand before typing anything?

      +

      Alex: This is where Good commit messages in practice becomes real: when you make a habit of writing good commit messages, you build trust. That matters in practice: Maintainers see that you care about the project's long-term health, not just your immediate contribution. The workshop is closer to rehearsal than lecture. You hear the move, try the move, and then check what changed.

      +

      Alex: Treat examples as spoken recipes, not decorations. You may hear something like 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. Read the command, understand what it changes, then run it only when the repository state matches the lesson.

      +

      Jamie: Let's pause on Learning Cards: Writing Good Commit Messages. What should a learner take away from it?

      +

      Alex: Start with Learning Cards: Writing Good Commit Messages. There is something to understand, something to try, and something that proves the try worked.

      +

      Alex: The practical takeaway is this. 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. 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.

      -

      Alex: Keep the teaching thread moving. Start with Choosing the right alert type: The following table describes each alert type and when to use it.

      -

      Jamie: Let's pause on Screen Reader Behavior. What should a learner take away from it?

      -

      Alex: Here is the plain-English version of Screen Reader Behavior. Alert blocks render as elements with an SVG icon and a strong heading.

      -

      Alex: The practical takeaway is this. NVDA/JAWS: announces blockquote role, then reads the type label ("Note", "Warning") then the content. VoiceOver: reads the type as bold text then the content. The colored icon is decorative (aria-hidden); it does not add information beyond the type label.

      -

      Alex: Keep the teaching thread moving. This is where 19. Collapsible Sections with Details and Summary becomes real: the and HTML elements create collapsible sections. That matters in practice: They are one of the most useful tools for keeping long documents, issue reports, and PRs manageable - hiding optional content until the reader chooses to expand it. The workshop is closer to rehearsal than lecture. You hear the move, try the move, and then check what changed.

      +

      Alex: Keep the teaching thread moving. The reason The Nature of Open Source Communication matters is that open source collaboration happens primarily in writing, asynchronously, in public. That gives the learner a simple foothold: understanding these three characteristics shapes everything about how we communicate.

      +

      Jamie: Let's pause on In writing. What should a learner take away from it?

      +

      Alex: Start with In writing. There is something to understand, something to try, and something that proves the try worked.

      +

      Alex: The practical takeaway is this. 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.".

      +

      Alex: Keep the teaching thread moving. Start with Asynchronously. There is something to understand, something to try, and something that proves the try worked.

      +

      Alex: The practical takeaway is this. 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.

      -

      Jamie: Let's pause on Important formatting rules. What should a learner take away from it?

      -

      Alex: Start with Important formatting rules. There is something to understand, something to try, and something that proves the try worked.

      -

      Alex: First, blank line after. Put a blank line between the closing tag and your Markdown content. Without it, Markdown formatting inside may not render. Then, blank line before. Same principle at the end. After that, the text should be descriptive - it is the only thing visible when collapsed. It is like walking a hallway with named doors: read the sign, enter the right room, then confirm where you landed.

      -

      Alex: Keep the teaching thread moving. The reason Real-world uses in this workshop matters is that the following list describes common uses for collapsible sections.

      -

      Alex: The practical takeaway is this. Bug reports in issues: Collapse the full stack trace so the issue body stays readable. Long configuration blocks: Let readers expand the full YAML only if they need it. Exercise solutions: Collapse the answer so learners try the exercise first. Screen reader guidance blocks: Throughout this course, some sections collapse detailed assistive technology instructions so sighted users see a cleaner page while screen reader users can easily expand them. Meeting notes: Collapse detailed minutes while showing the summary.

      -

      Jamie: Let's pause on Details sections that start open. What should a learner take away from it?

      -

      Alex: Start with Details sections that start open: Add the open attribute to have the section expanded by default.

      -

      Alex: Treat examples as spoken recipes, not decorations. You may hear something like; Currently known issues; - Checkbox toggle requires Focus Mode in NVDA; - Alert blocks do not render in email notifications. Read the command, understand what it changes, then run it only when the repository state matches the lesson.

      +

      Jamie: Let's pause on In public. What should a learner take away from it?

      +

      Alex: Start with In public. There is something to understand, something to try, and something that proves the try worked.

      +

      Alex: The practical takeaway is this. 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.

      +

      Alex: Keep the teaching thread moving. Keep the learner anchored in The Anatomy of Helpful Feedback. Whether commenting on an issue, reviewing a PR, or responding to a question, effective feedback has a structure.

      +

      Jamie: Let's pause on 1. Acknowledge what's working. What should a learner take away from it?

      +

      Alex: The reason 1. Acknowledge what's working matters is that before identifying problems, name what is good. That gives the learner a simple foothold: this is not flattery - it is accuracy.

      -

      Alex: Keep the teaching thread moving. Here is the plain-English version of Screen Reader Behavior. The element renders as a disclosure widget. Put another way, after expanding: The content is immediately readable. It is like learning a transit route. The names of the stops matter because they tell you whether you are still going the right direction.

      -

      Alex: The practical takeaway is this. NVDA: announces "button collapsed" for the - press Enter or Space to expand. JAWS: announces "collapsed" - press Enter on the summary to expand. VoiceOver: announces "collapsed, button" - press VO+Space to activate.

      -

      Jamie: Let's pause on Learning Cards: Collapsible Sections. What should a learner take away from it?

      -

      Alex: Start with Learning Cards: Collapsible Sections. There is something to understand, something to try, and something that proves the try worked.

      -

      Alex: The practical takeaway is this. The element is announced as a button -- press Enter or Space to toggle between collapsed and expanded; listen for "collapsed" or "expanded" state announcements. After expanding, the content is immediately available -- arrow down to read it; no page reload or focus change occurs. Nested blocks (details inside details) work but add complexity -- each level is an independent toggle button; keep nesting to one level deep for predictable navigation. The summary text is the only visible element when collapsed -- it appears as a disclosure triangle ( ) with text; zoom in to ensure the triangle and text are both readable. Expanded content appears inline below the summary -- at high zoom it flows naturally with the rest of the page content. The open attribute forces a section to start expanded -- useful when the content is important enough that most readers should see it by default.

      -

      Alex: Keep the teaching thread moving. Keep the learner anchored in 20. Task List Checkboxes. Task lists in GitHub issues and PRs render as real interactive checkboxes. This is the part to say slowly: Anyone with write access to the repository can check and uncheck them directly in the rendered view without editing the Markdown.

      +

      Alex: Keep the teaching thread moving. Start with 2. Identify the specific concern: "This code is inaccessible." "This button has no accessible name - aria-label or visible text is needed for screen readers to announce its purpose.". Think of it like entering a new building: first you find the lobby, then the room, then the door you actually need.

      +

      Jamie: Let's pause on 3. Explain why it matters. What should a learner take away from it?

      +

      Alex: Here is the plain-English version of 3. Explain why it matters. Context turns a complaint into a lesson. Put another way, it also respects the contributor - they deserve to understand, not just comply.

      +

      Alex: Keep the teaching thread moving. This is where 4. Suggest a path forward (when you can) becomes real: if you have an idea for a solution, offer it as a suggestion, not a mandate. That matters in practice: "Something like aria-label='Close navigation menu' would work well here.

      -

      Jamie: Let's pause on Syntax. What should a learner take away from it?

      -

      Alex: Start with Syntax. There is something to understand, something to try, and something that proves the try worked.

      -

      Alex: Treat examples as spoken recipes, not decorations. You may hear something like [x] Color contrast verified (4.5:1 minimum for body text); - [x] Keyboard navigation tested; - [ ] Screen reader tested with NVDA; - [ ] Screen reader tested with JAWS; - [ ] Screen reader tested with VoiceOver; - [ ] Alt text provided for all images; - [ ]. Read the command, understand what it changes, then run it only when the repository state matches the lesson.

      -

      Jamie: Before we leave How to write them, what is the practical point?

      -

      Alex: First, start with a list item marker (-,, or +) and a space. Then, add [x] for a checked box or [ ] (with a space inside) for an unchecked box. After that, add a space, then the task description. Finally, the description should be meaningful - "Test NVDA" is better than "Item 3". Think of it as a rail line: each stop confirms you are still on the right route before the next one.

      -

      Jamie: Let's pause on What makes task lists special on GitHub. What should a learner take away from it?

      -

      Alex: Start with What makes task lists special on GitHub. There is something to understand, something to try, and something that proves the try worked.

      -

      Alex: The practical takeaway is this. Progress tracking: In issues, GitHub shows a progress bar: "2 of 7 tasks completed". Click to check: In the rendered view, users with triage or write permissions can click to toggle checkboxes without editing the comment. Linked issues: You can reference issues in a task: - [ ] Fix 42 - the task shows the issue title and its open/closed state. PR templates: Task lists in PR templates create checklists that authors fill out before requesting review.

      +

      Jamie: Let's pause on 5. Signal the weight of the concern. What should a learner take away from it?

      +

      Alex: Keep the learner anchored in 5. Signal the weight of the concern. Help contributors understand what is a blocker versus a preference.

      +

      Alex: The practical takeaway is this. 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.

      +

      Alex: Keep the teaching thread moving. The reason Prefer "we" or describe the code, not the person matters is that "You made an error here." "There's an error here." or "This line does X but we need Y.". The interface gets friendlier when it stops being a wall of controls and starts being a set of named places.

      +

      Jamie: Let's pause on Use tentative language for uncertainty. What should a learner take away from it?

      +

      Alex: Start with 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?".

      -

      Jamie: Let's pause on Example - pull request checklist. What should a learner take away from it?

      -

      Alex: Start with Example - pull request checklist. There is something to understand, something to try, and something that proves the try worked.

      -

      Alex: Treat examples as spoken recipes, not decorations. You may hear something like Pre-review checklist; - [x] Changes are limited to the files listed in the issue; - [x] All new images have descriptive alt text; - [ ] Screen reader tested the changes with NVDA; - [ ] No heading levels are skipped; - [ ] All links use descriptive text (not. Read the command, understand what it changes, then run it only when the repository state matches the lesson.

      -

      Jamie: Let's pause on Screen Reader Interaction. What should a learner take away from it?

      -

      Alex: Keep the learner anchored in Screen Reader Interaction. In Browse Mode, checkboxes are read as checkbox, not checked or checkbox, checked.

      -

      Alex: The practical takeaway is this. NVDA: Press NVDA+Space to enter Focus Mode, then Tab to find the checkbox, then Space to toggle it. JAWS: Tab to the checkbox, then Space to toggle. VoiceOver: VO+Space on the checkbox element.

      -

      Alex: Keep the teaching thread moving. The reason 21. Syntax Highlighting in Fenced Code Blocks matters is that we covered basic code blocks in Section 13. That gives the learner a simple foothold: this section covers the GitHub-specific syntax highlighting that makes code blocks more readable for sighted users. The interface gets friendlier when it stops being a wall of controls and starts being a set of named places.

      +

      Alex: Keep the teaching thread moving. Here is the plain-English version of Acknowledge cultural and language diversity. When reading someone's comment: Assume good intent unless there is clear evidence otherwise. Put another way, when writing: Choose plain words over clever ones.

      +

      Alex: The practical takeaway is this. 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.

      +

      Jamie: Let's pause on Avoid urgency markers unless genuinely urgent. What should a learner take away from it?

      +

      Alex: This is where Avoid urgency markers unless genuinely urgent becomes real: "I need this fixed ASAP" "This is blocking our release scheduled for next Friday - is there capacity to look at it this week?".

      +

      Alex: Keep the teaching thread moving. Keep the learner anchored in Keep comments focused. Each comment should address one concern. This is the part to say slowly: If you have three issues, leave three comments - unless they are closely related. A good GitHub workflow is like a well-run meeting: everyone knows the topic, the next action, and who has the floor.

      -

      Jamie: Let's pause on How it works. What should a learner take away from it?

      -

      Alex: Start with How it works: Add a language identifier right after the opening triple backticks. The next useful detail is this: GitHub uses Linguist to apply syntax highlighting with appropriate colors for keywords, strings, comments, and other language constructs.

      -

      Alex: Keep the teaching thread moving. Here is the plain-English version of Complete list of commonly used language identifiers. The following table lists the language identifiers you are most likely to use. Put another way, if no language is specified, the code block renders as plain monospaced text with no highlighting.

      -

      Jamie: Let's pause on Screen Reader Note. What should a learner take away from it?

      -

      Alex: This is where Screen Reader Note becomes real: syntax highlighting is visual only - screen readers read the code text without announcing color changes. That matters in practice: The code block itself is announced as a code region.

      +

      Jamie: Let's pause on Don't leave comments unresolved. What should a learner take away from it?

      +

      Alex: The reason Don't leave comments unresolved matters is that if you asked a question and got an answer, respond. That gives the learner a simple foothold: "Thanks, that makes sense" or resolving the conversation thread signals that the thread is complete.

      +

      Alex: Keep the teaching thread moving. Start with Resolving conversations: On a PR, conversations (inline comment threads) can be "resolved" once addressed. The next useful detail is this: The author of the change and the reviewer can both resolve them.

      +

      Jamie: Let's pause on Do not "pile on". What should a learner take away from it?

      +

      Alex: Here is the plain-English version of 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. Put another way, a reaction on an existing comment is enough.

      -

      Alex: Keep the teaching thread moving. Keep the learner anchored in 22. Mermaid Diagrams. GitHub renders Mermaid.js diagrams inline when you use a mermaid fenced code block. This is the part to say slowly: They are common in READMEs, PRs, and documentation to illustrate architecture, flows, and relationships. A good GitHub workflow is like a well-run meeting: everyone knows the topic, the next action, and who has the floor.

      -

      Jamie: Before we leave Syntax, what is the practical point?

      -

      Alex: The reason Syntax matters is that flowchart LR A[Fork repo] -- B[Clone locally] B -- C[Create branch] C -- D[Make changes] D -- E[Push branch] E -- F[Open PR] F -- G{Review passed?} G -- Yes -- H[Merge] G -- No -- D.

      -

      Alex: Keep the teaching thread moving. Start with Common diagram types: The following table lists the Mermaid diagram types you are most likely to encounter on GitHub.

      +

      Alex: Keep the teaching thread moving. This is where Reactions becomes real: GitHub reactions () are an efficient way to express agreement, appreciation, or concern without adding noise to a thread. The workshop is closer to rehearsal than lecture. You hear the move, try the move, and then check what changed.

      +

      Jamie: Let's pause on Saved Replies - Your Accessibility Win. What should a learner take away from it?

      +

      Alex: Keep the learner anchored in 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 the part to say slowly: This is a significant accessibility win for anyone who types the same comments repeatedly during triage, reviews, or issue management.

      +

      Alex: Keep the teaching thread moving. Start with Common uses. There is something to understand, something to try, and something that proves the try worked.

      +

      Alex: The practical takeaway is this. "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.

      -

      Jamie: Let's pause on Accessibility limitation - critical. What should a learner take away from it?

      -

      Alex: Here is the plain-English version of Accessibility limitation - critical. Mermaid diagrams render as SVG images. Put another way, GitHub does not auto-generate alt text for them.

      -

      Jamie: Let's pause on How to make Mermaid diagrams accessible. What should a learner take away from it?

      -

      Alex: This is where How to make Mermaid diagrams accessible becomes real: example - accessible Mermaid usage. That matters in practice: flowchart LR Fork -- Clone -- Branch -- Commit -- Push -- PR -- Review -- Merge. The workshop is closer to rehearsal than lecture. You hear the move, try the move, and then check what changed.

      -

      Alex: First, write a text description before the diagram that conveys all the same information. Then, optionally, duplicate the information as a numbered list or table. After that, consider wrapping the Mermaid source in a block if the text description is sufficient. It is a checklist, but a meaningful one: every item creates evidence that the next step is safe.

      -

      Jamie: Let's pause on 23. Math Expressions with LaTeX. What should a learner take away from it?

      -

      Alex: Keep the learner anchored in 23. Math Expressions with LaTeX. GitHub renders LaTeX math expressions using MathJax. This is the part to say slowly: This is common in data science, research, and algorithm documentation.

      +

      Jamie: Let's pause on Creating a Saved Reply. What should a learner take away from it?

      +

      Alex: Start with Creating a Saved Reply. There is something to understand, something to try, and something that proves the try worked.

      +

      Alex: First, navigate to github.com/settings/replies. Then, activate "Add a saved reply". After that, give it a title (e.g., "Good first issue claim") - this is what you search. Finally, type the full reply text in the body (Markdown is supported). Think of it as a rail line: each stop confirms you are still on the right route before the next one.

      +

      Jamie: Let's pause on Using a Saved Reply in a comment. What should a learner take away from it?

      +

      Alex: Start with Using a Saved Reply in a comment. There is something to understand, something to try, and something that proves the try worked.

      +

      Alex: First, navigate to any comment text area. Then, activate the Saved Replies button (the speech bubble icon in the comment toolbar, or press Ctrl+. if enabled). After that, a dropdown appears showing your saved replies - type to filter by title. Finally, select the reply - it inserts into the text area. Treat it like a recipe: do not add the next ingredient until the previous one is actually in the bowl.

      +

      Jamie: Before we leave Using a Saved Reply in a comment, what is the practical point?

      +

      Alex: First, edit as needed before submitting. It is a checklist, but a meaningful one: every item creates evidence that the next step is safe.

      +

      Jamie: Let's pause on Screen reader path. What should a learner take away from it?

      +

      Alex: This is where Screen reader path becomes real: limit: GitHub allows up to 100 saved replies per account.

      +

      Alex: A solid navigation habit is to prove where you are before activating controls. Headings, landmarks, and the address bar are not trivia; they are your map.

      +
      +

      Alex: Keep the teaching thread moving. Start with Learning Cards: Commenting Etiquette. There is something to understand, something to try, and something that proves the try worked.

      +

      Alex: The practical takeaway is this. 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. 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.

      +

      Jamie: Let's pause on Review the code, not the person. What should a learner take away from it?

      +

      Alex: The reason Review the code, not the person matters is that "You clearly don't understand accessibility." "This implementation doesn't account for keyboard navigation - here's how to add it.".

      +

      Alex: Keep the teaching thread moving. Start with Don't gatekeep knowledge: If a contributor makes a mistake because they didn't know something, explain the concept. Think of it like entering a new building: first you find the lobby, then the room, then the door you actually need.

      -

      Alex: Keep the teaching thread moving. The reason Inline math matters is that use single $ delimiters for math within a sentence. That gives the learner a simple foothold: renders as: The formula is $e = mc^2$ where $c$ is the speed of light.

      -

      Jamie: Let's pause on Block math. What should a learner take away from it?

      -

      Alex: Start with Block math: Use $$ delimiters for display-style (centered, larger) math on their own lines.

      -

      Alex: Keep the teaching thread moving. Here is the plain-English version of Common LaTeX patterns. The following table shows some LaTeX patterns you might encounter. It is like learning a transit route. The names of the stops matter because they tell you whether you are still going the right direction.

      +

      Jamie: Let's pause on Ask questions instead of making demands. What should a learner take away from it?

      +

      Alex: Here is the plain-English version of Ask questions instead of making demands. "Change this to use aria-label." "What do you think about using aria-label here instead? Put another way, screen readers would then announce the button's purpose directly.".

      +

      Alex: Keep the teaching thread moving. This is where Distinguish opinion from requirement becomes real: if something is your stylistic preference but NOT a bug or correctness issue, say so. That matters in practice: "The current implementation is correct.

      +

      Jamie: Let's pause on Approve explicitly. What should a learner take away from it?

      +

      Alex: Keep the learner anchored in 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!

      -

      Jamie: Before we leave Screen Reader Note, what is the practical point?

      -

      Alex: This is where Screen Reader Note becomes real: math expressions rendered by MathJax include aria-label attributes with the spoken form of the equation. That matters in practice: Screen readers should announce the math correctly, but accuracy varies.

      -

      Alex: The practical takeaway is this. NVDA with Firefox or Chrome: reads MathML fairly well. JAWS: reads the aria-label text. VoiceOver: reads the aria-label text.

      -

      Alex: Keep the teaching thread moving. Keep the learner anchored in 24. Footnotes. GitHub supports Markdown footnotes, which render as superscript numbers that link to references at the bottom of the document. This is the part to say slowly: They are useful for citations, additional context, and references that would interrupt the flow of the main text.

      -

      Jamie: Let's pause on How they work. What should a learner take away from it?

      -

      Alex: Start with How they work. There is something to understand, something to try, and something that proves the try worked.

      -

      Alex: First, in your text, add [^identifier] where you want the footnote reference to appear. Then, anywhere in the document (typically at the bottom), define the footnote with [^identifier]: Your footnote text. After that, GitHub renders the reference as a superscript number that links to the definition. Finally, the definition includes a back-link that returns to the reference location. The rhythm is simple: orient, act, verify, then continue.

      +

      Alex: Keep the teaching thread moving. The reason Say thank you matters is that when someone takes time to review your work, acknowledge it - even if you disagree with some feedback. That gives the learner a simple foothold: "Thanks so much for the thorough review! The interface gets friendlier when it stops being a wall of controls and starts being a set of named places.

      +

      Jamie: Let's pause on Don't take feedback personally. What should a learner take away from it?

      +

      Alex: Start with Don't take feedback personally: Code review is about the code, not your worth as a person or developer. The next useful detail is this: Even the most senior contributors receive change requests.

      +

      Alex: Keep the teaching thread moving. Here is the plain-English version of Explain your choices. If you are keeping your implementation despite feedback, explain why. Put another way, "I considered aria-label here, but I went with a visually-hidden instead because it allows translators to localize the text more easily.

      -

      Alex: Keep the teaching thread moving. Start with Footnote identifiers. There is something to understand, something to try, and something that proves the try worked.

      -

      Alex: The practical takeaway is this. You can use numbers: [^1], [^2], [^3]. You can use descriptive names: [^webaim-survey], [^wcag-reference]. Descriptive names make the raw Markdown more readable but render as sequential numbers.

      -

      Jamie: Let's pause on Multi-line footnotes. What should a learner take away from it?

      -

      Alex: Here is the plain-English version of Multi-line footnotes. Indent continuation lines with two spaces.

      -

      Alex: Keep the teaching thread moving. Start with Screen Reader Behavior. There is something to understand, something to try, and something that proves the try worked.

      -

      Alex: The practical takeaway is this. The footnote reference is a link ( element) announcing its number. NVDA: "superscript, 1, link". JAWS: "link, 1". VoiceOver: "link, footnote 1". The back-link at the definition reads "return to footnote reference". Activating the footnote link jumps focus to the definition; activating the back-link returns focus to the original location.

      +

      Jamie: Let's pause on Surface blockers early. What should a learner take away from it?

      +

      Alex: This is where Surface blockers early becomes real: don't wait until you have finished a 500-line PR to mention that you weren't sure about the approach.

      +

      Alex: Keep the teaching thread moving. Keep the learner anchored in Inclusive Commenting for Accessibility Issues. When filing or discussing accessibility bugs, additional context helps. A good GitHub workflow is like a well-run meeting: everyone knows the topic, the next action, and who has the floor.

      +

      Alex: The practical takeaway is this. 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.

      +

      Alex: A solid issue habit is to read the title, the body, and the timeline before acting. You are listening for the requested action, the missing evidence, and the person who needs a response.

      +

      Jamie: Let's pause on The "Good First Issue" Social Contract. What should a learner take away from it?

      +

      Alex: The reason The "Good First Issue" Social Contract matters is that when a maintainer labels an issue good first issue, they are. That gives the learner a simple foothold: when you take a good first issue, your responsibilities.

      +

      Alex: The practical takeaway is this. Investing time - good first issues require extra documentation and mentorship. Signaling welcome - they want to support a new contributor.

      +

      Alex: First, comment to claim it - "Hi, I'd like to work on this. Can I be assigned?". Then, wait for assignment - do not start until assigned; two people working in parallel wastes everyone's time. After that, 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?". Finally, 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?". The rhythm is simple: orient, act, verify, then continue.

      +

      Jamie: Before we leave The "Good First Issue" Social Contract, what is the practical point?

      +

      Alex: First, don't disappear - if you claim an issue, see it through or explicitly hand it back. Think of it as a rail line: each stop confirms you are still on the right route before the next one.

      -

      Jamie: Let's pause on 25. Linked Heading Anchors and Tables of Contents. What should a learner take away from it?

      -

      Alex: Keep the learner anchored in 25. Linked Heading Anchors and Tables of Contents. Every heading in a GitHub Markdown file automatically gets an anchor ID. This is the part to say slowly: You can link to any heading from anywhere - within the same document, from another file, or from an issue or PR.

      -

      Jamie: Let's pause on How GitHub generates anchor IDs. What should a learner take away from it?

      -

      Alex: The reason How GitHub generates anchor IDs matters is that GitHub converts the heading text to an anchor ID. That gives the learner a simple foothold: the following table shows example headings and their generated anchors. The interface gets friendlier when it stops being a wall of controls and starts being a set of named places.

      -

      Alex: First, converting to lowercase. Then, replacing spaces with hyphens. After that, removing most punctuation (except hyphens). Finally, removing leading and trailing whitespace. The rhythm is simple: orient, act, verify, then continue.

      -

      Jamie: Let's pause on Building a table of contents. What should a learner take away from it?

      -

      Alex: Start with Building a table of contents: You can build a manual table of contents using heading anchor links.

      +

      Jamie: Let's pause on When you receive harsh feedback. What should a learner take away from it?

      +

      Alex: Start with When you receive harsh feedback. There is something to understand, something to try, and something that proves the try worked.

      +

      Alex: First, take a breath before responding - there is no urgency; the thread will wait. Then, look for the valid concern underneath the harsh words. After that, respond to the concern, not the tone. Finally, if the behavior crosses into harassment, report it via the "." button on the comment → "Report". Think of it as a rail line: each stop confirms you are still on the right route before the next one.

      +

      Jamie: Let's pause on When you disagree with a decision. What should a learner take away from it?

      +

      Alex: Start with When you disagree with a decision. There is something to understand, something to try, and something that proves the try worked.

      +

      Alex: First, make your case once, clearly and with evidence. Then, accept that the maintainer has the final say in their project. After that, if you strongly disagree, you can fork the project and take it in a different direction - this is legitimate in open source. Treat it like a recipe: do not add the next ingredient until the previous one is actually in the bowl.

      +

      Jamie: Let's pause on When someone is rude to you. What should a learner take away from it?

      +

      Alex: Start with When someone is rude to you. There is something to understand, something to try, and something that proves the try worked.

      +

      Alex: First, you do not have to engage. Then, 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.". After that, report via GitHub's reporting tools if the behavior is abusive. It is a checklist, but a meaningful one: every item creates evidence that the next step is safe.

      -

      Alex: Keep the teaching thread moving. Here is the plain-English version of Duplicate headings. If a document has two headings with the same text, GitHub appends -1, -2, and so on to the duplicate anchors. Put another way, best practice: Avoid duplicate heading text.

      -

      Jamie: Let's pause on Finding the anchor for any heading. What should a learner take away from it?

      -

      Alex: Start with Finding the anchor for any heading. There is something to understand, something to try, and something that proves the try worked.

      -

      Alex: First, mouse users: On GitHub, hover over any heading - a chain link icon appears to the left. Click it to update the URL with the anchor. Then, screen reader users: Navigate to the heading, then Tab once. A link button appears. Activate it and the URL in the address bar updates to show the anchor. After that, keyboard (GitHub shortcut): There is no direct shortcut, but you can copy the heading text, convert it to the anchor format mentally, and type it in the URL. It is a checklist, but a meaningful one: every item creates evidence that the next step is safe.

      -

      Alex: Keep the teaching thread moving. Keep the learner anchored in 26. Autolinked References - Issues, PRs, Commits, and Users. One of GitHub's most powerful features is automatic linking. This is the part to say slowly: When you type certain patterns in any Markdown field on GitHub, they automatically become clickable links. A good GitHub workflow is like a well-run meeting: everyone knows the topic, the next action, and who has the floor.

      +

      Jamie: Let's pause on When you accidentally caused offense. What should a learner take away from it?

      +

      Alex: Start with When you accidentally caused offense. There is something to understand, something to try, and something that proves the try worked.

      +

      Alex: First, acknowledge it directly: "I can see how that came across as dismissive - that wasn't my intention.". Then, do not over-explain or defend excessively. After that, adjust going forward. It is like walking a hallway with named doors: read the sign, enter the right room, then confirm where you landed.

      +

      Alex: Keep the teaching thread moving. The reason Writing Your First README matters is that see also: Appendix W: GitHub Pages for publishing your README as a website. That gives the learner a simple foothold: a README is the front door of your project.

      +

      Jamie: Let's pause on What belongs in a README. What should a learner take away from it?

      +

      Alex: Start with What belongs in a README: Every README should answer these questions, roughly in this order. The next useful detail is this: 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.

      -

      Jamie: Let's pause on Issue and pull request references. What should a learner take away from it?

      -

      Alex: The reason Issue and pull request references matters is that the following table shows how to reference issues and pull requests.

      -

      Alex: Keep the teaching thread moving. Start with User and team mentions: The following table shows how to mention users and teams.

      -

      Jamie: Let's pause on Commit references. What should a learner take away from it?

      -

      Alex: Here is the plain-English version of Commit references. The following table shows how to reference specific commits.

      +

      Alex: Keep the teaching thread moving. Here is the plain-English version of Accessibility in READMEs. Your README is a web page -- GitHub renders it as HTML. Put another way, that means the same accessibility rules apply. It is like learning a transit route. The names of the stops matter because they tell you whether you are still going the right direction.

      +

      Alex: The practical takeaway is this. Alt text for images and badges. A badge that says is invisible to screen readers. Write 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 -- not Click here.

      +

      Jamie: Let's pause on Good README vs. bad README. What should a learner take away from it?

      +

      Alex: This is where Good README vs. bad README becomes real: bad: A single paragraph that says "This is my project. That matters in practice: Run it with npm start." No headings, no license, no description of what the project does.

      +

      Alex: Keep the teaching thread moving. Start with Learning Cards: Writing Your First README. There is something to understand, something to try, and something that proves the try worked.

      +

      Alex: The practical takeaway is this. 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: rather than an empty that reads as "image" with no context. Use real Markdown link text (installation guide) instead of bare URLs, so your screen reader announces the destination rather than spelling out a long URL. 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.

      -

      Alex: Keep the teaching thread moving. This is where Closing keywords in pull requests becomes real: when you include certain keywords followed by an issue reference in a PR description, merging the PR automatically closes the referenced issue. That matters in practice: All of these keywords work: close, closes, closed, fix, fixes, fixed, resolve, resolves, resolved. The workshop is closer to rehearsal than lecture. You hear the move, try the move, and then check what changed.

      -

      Jamie: Let's pause on URL autolinking. What should a learner take away from it?

      -

      Alex: Keep the learner anchored in URL autolinking. GitHub automatically converts full URLs into clickable links. This is the part to say slowly: Accessibility note: While autolinked URLs work, they create poor link text for screen readers (the entire URL is read character by character).

      -

      Alex: Keep the teaching thread moving. The reason 27. HTML in Markdown matters is that GitHub allows a subset of HTML in Markdown files. That gives the learner a simple foothold: this is useful for semantic elements that do not have Markdown equivalents, advanced layout needs, and accessibility improvements.

      +

      Jamie: Let's pause on Community Health Files. What should a learner take away from it?

      +

      Alex: The reason Community Health Files matters is that community health files tell contributors how your project operates before they write a single line of code. That gives the learner a simple foothold: 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.

      +

      Alex: Keep the teaching thread moving. Start with CONTRIBUTING.md: This file answers the question every newcomer asks: "How do I help?" A good CONTRIBUTING.md covers. The next useful detail is this: A sentence like "We are glad you are here" costs nothing and signals that newcomers are expected, not tolerated. Think of it like entering a new building: first you find the lobby, then the room, then the door you actually need.

      +

      Alex: The practical takeaway is this. 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.

      +

      Jamie: Let's pause on CODE OF CONDUCT.md. What should a learner take away from it?

      +

      Alex: Here is the plain-English version of CODE OF CONDUCT.md. A code of conduct sets the social contract for your project. Put another way, without one, "acceptable behavior" is whatever each participant assumes it is -- and those assumptions vary widely.

      +

      Alex: The practical takeaway is this. 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.

      -

      Jamie: Let's pause on Keyboard key visualization. What should a learner take away from it?

      -

      Alex: Start with Keyboard key visualization: The element renders text in a key-cap style box. The next useful detail is this: Press NVDA + Space to toggle Focus Mode.

      -

      Alex: Treat examples as spoken recipes, not decorations. You may hear something like Press Ctrl + C to copy.; Press NVDA + Space to toggle Focus Mode. Read the command, understand what it changes, then run it only when the repository state matches the lesson.

      -

      Alex: Keep the teaching thread moving. Here is the plain-English version of Hidden comments. Hidden comments are useful for notes to yourself or other contributors that should not be visible to readers. It is like learning a transit route. The names of the stops matter because they tell you whether you are still going the right direction.

      -

      Jamie: Let's pause on Allowed HTML elements on GitHub. What should a learner take away from it?

      -

      Alex: This is where Allowed HTML elements on GitHub becomes real: GitHub whitelists specific HTML elements for security. That matters in practice: The following table lists the most useful allowed elements.

      +

      Alex: Keep the teaching thread moving. This is where SECURITY.md becomes real: see also: Appendix F: Git Security and Appendix P: Security Features for security best practices. That matters in practice: If someone discovers a vulnerability in your project, you do not want them to file a public issue.

      +

      Alex: The practical takeaway is this. 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.

      +

      Jamie: Let's pause on LICENSE. What should a learner take away from it?

      +

      Alex: Keep the learner anchored in 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. This is the part to say slowly: Adding a LICENSE file is a one-time step that makes your project genuinely open source.

      +

      Alex: Keep the teaching thread moving. The reason Finding these files on GitHub matters is that navigate to any repository and click Insights then Community Standards. That gives the learner a simple foothold: GitHub shows a checklist of which community health files are present and links to add any that are missing. The interface gets friendlier when it stops being a wall of controls and starts being a set of named places.

      -

      Alex: Keep the teaching thread moving. Keep the learner anchored in Disallowed HTML on GitHub. GitHub strips these elements for security.

      -

      Alex: The practical takeaway is this. No JavaScript execution. No arbitrary CSS. No embedded content. No form elements (except task list checkboxes). No input fields. Event attributes like onclick, onload.

      -

      Jamie: Let's pause on 28. Screen Reader Behavior Summary. What should a learner take away from it?

      -

      Alex: The reason 28. Screen Reader Behavior Summary matters is that this table consolidates how every Markdown element behaves with screen readers. That gives the learner a simple foothold: use it as a quick reference when choosing how to format your content.

      -

      Alex: Keep the teaching thread moving. Start with 29. Accessible Markdown Authoring Checklist: Use this checklist every time you write a Markdown file, issue, or PR description. The next useful detail is this: It covers the accessibility requirements that make your content work for everyone. Think of it like entering a new building: first you find the lobby, then the room, then the door you actually need.

      +

      Jamie: Let's pause on Learning Cards: Community Health Files. What should a learner take away from it?

      +

      Alex: Start with Learning Cards: Community Health Files. There is something to understand, something to try, and something that proves the try worked.

      +

      Alex: The practical takeaway is this. 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. 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.

      +

      Jamie: What is the judgment call here?

      +

      Alex: Here is the plain-English version of When to Use Different Communication Channels. GitHub Discussions are separate from Issues. Put another way, use Discussions for: "What do people think about X approach?" and Issues for: "The X button is broken.".

      +

      Alex: Use the comparison to make a decision, not to recite a table. The main contrasts are: PR comment means Feedback on a specific code change. PR review means Formal verdict (approve/request changes) with consolidated feedback. Discussion means Open-ended conversation, proposals, community Q&A.

      +

      Jamie: Let's pause on Try It: Rewrite One Comment. What should a learner take away from it?

      +

      Alex: This is where Try It: Rewrite One Comment becomes real: time: 2 minutes What you need: Just your brain. That matters in practice: Read this code review comment and rewrite it to be constructive.

      +

      Alex: First, what you noticed. Then, why it matters. After that, what you suggest. Finally, why the suggestion helps. It is a checklist, but a meaningful one: every item creates evidence that the next step is safe.

      +

      Jamie: Before we leave Try It: Rewrite One Comment, what is the practical point?

      +

      Alex: First, encouragement. It is like walking a hallway with named doors: read the sign, enter the right room, then confirm where you landed.

      -

      Jamie: Let's pause on Structure. What should a learner take away from it?

      -

      Alex: Start with Structure. There is something to understand, something to try, and something that proves the try worked.

      -

      Alex: The practical takeaway is this. [ ] One H1 heading per document, used as the title. [ ] Heading levels never skip (no jumping from H2 to H4). [ ] Headings are descriptive (not "Section 1" or "Untitled"). [ ] Long documents have a table of contents with anchor links.

      -

      Alex: Keep the teaching thread moving. Start with Text and emphasis. There is something to understand, something to try, and something that proves the try worked.

      -

      Alex: The practical takeaway is this. [ ] Bold marks genuinely important content, not just visual styling. [ ] Bold text is not used as a substitute for headings. [ ] Strikethrough text has surrounding context explaining the change.

      -

      Jamie: Let's pause on Links. What should a learner take away from it?

      -

      Alex: Start with Links. There is something to understand, something to try, and something that proves the try worked.

      -

      Alex: The practical takeaway is this. [ ] Every link has descriptive text (never "click here," "here," "read more," or "link"). [ ] No bare URLs in prose (always use descriptive text). [ ] Multiple links on the same page have unique text if they point to different destinations. [ ] Relative links used for files within the same repository.

      +

      Alex: Keep the teaching thread moving. Keep the learner anchored in Contributing to Open Source. This section was previously Appendix T. This is the part to say slowly: It is now part of the teaching narrative. A good GitHub workflow is like a well-run meeting: everyone knows the topic, the next action, and who has the floor.

      +

      Jamie: Let's pause on A Guide for First-Time Contributors. What should a learner take away from it?

      +

      Alex: The reason A Guide for First-Time Contributors matters is that you do not need to be a professional developer to contribute to open source. That gives the learner a simple foothold: documentation, accessibility improvements, and bug reports are among the most valuable contributions any project can receive.

      +

      Alex: Keep the teaching thread moving. Start with 1. What Is Open Source?: Open source software is software whose source code is publicly available. The next useful detail is this: Anyone can read it, use it, and - in most cases - contribute to it.

      +

      Alex: The practical takeaway is this. 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.

      -

      Alex: Keep the teaching thread moving. Start with Images. There is something to understand, something to try, and something that proves the try worked.

      -

      Alex: The practical takeaway is this. [ ] Every informative image has descriptive alt text. [ ] Alt text is not a filename (screenshot.png) or generic (image, photo). [ ] Complex images (charts, diagrams) have a detailed text description in a block. [ ] Decorative images have empty alt text.

      -

      Jamie: Let's pause on Lists and tables. What should a learner take away from it?

      -

      Alex: Start with Lists and tables. There is something to understand, something to try, and something that proves the try worked.

      -

      Alex: The practical takeaway is this. [ ] Lists use the correct type: ordered for sequential steps, unordered for non-sequential items. [ ] Tables have a text description immediately before them. [ ] Tables have descriptive header cells. [ ] Tables have fewer than 7 columns (split wide tables). [ ] Tables are used for data, not layout.

      -

      Alex: Keep the teaching thread moving. Start with Code. There is something to understand, something to try, and something that proves the try worked.

      -

      Alex: The practical takeaway is this. [ ] Fenced code blocks have a language identifier. [ ] Inline code used for commands, file names, and values. [ ] Code examples are complete enough to understand without the visual highlighting.

      +

      Jamie: Let's pause on 2. Who Can Contribute? What should a learner take away from it?

      +

      Alex: Here is the plain-English version of 2. Who Can Contribute? Contributors come from all backgrounds, skill levels, and countries. Put another way, 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.

      +

      Alex: Keep the teaching thread moving. Start with 3. What Makes a Good First Contribution? There is something to understand, something to try, and something that proves the try worked.

      +

      Alex: The practical takeaway is this. 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.

      +

      Jamie: Let's pause on Signs a contribution is too large for a first attempt. What should a learner take away from it?

      +

      Alex: Keep the learner anchored in Signs a contribution is too large for a first attempt. A well-executed small contribution is far more valuable than a large contribution that cannot be merged because it is out of scope.

      +

      Alex: The practical takeaway is this. 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.

      -

      Jamie: Let's pause on GFM features. What should a learner take away from it?

      -

      Alex: Start with GFM features. There is something to understand, something to try, and something that proves the try worked.

      -

      Alex: The practical takeaway is this. [ ] Mermaid diagrams have a text equivalent. [ ] Alert block type matches the urgency of the content. [ ] summary text clearly describes what is inside. [ ] Task list items have descriptive labels. [ ] Complex math expressions have plain English descriptions.

      -

      Alex: Keep the teaching thread moving. Start with General. There is something to understand, something to try, and something that proves the try worked.

      -

      Alex: The practical takeaway is this. [ ] Color is never the only way information is conveyed. [ ] No information is communicated only through visual position or layout. [ ] Content makes sense when read linearly, top to bottom.

      -

      Jamie: Let's pause on 30. Common Mistakes and How to Fix Them. What should a learner take away from it?

      -

      Alex: The reason 30. Common Mistakes and How to Fix Them matters is that this section covers the errors we see most often in workshop participants' Markdown. That gives the learner a simple foothold: each one includes what goes wrong, why it matters, and how to fix it.

      +

      Alex: Keep the teaching thread moving. The reason 4. Finding Something to Work On matters is that most open source projects label issues that are suitable for new contributors. That gives the learner a simple foothold: how to search: On any GitHub repository, go to Issues → filter by label.

      +

      Jamie: Let's pause on Learning Cards: Finding Something to Work On. What should a learner take away from it?

      +

      Alex: Start with Learning Cards: Finding Something to Work On. There is something to understand, something to try, and something that proves the try worked.

      +

      Alex: The practical takeaway is this. 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. 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.

      +

      Alex: Keep the teaching thread moving. Here is the plain-English version of 5. Reading an Issue Before You Start. Before commenting "I'll take this" on an issue, ask yourself. Put another way, 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. It is like learning a transit route. The names of the stops matter because they tell you whether you are still going the right direction.

      +

      Alex: The practical takeaway is this. 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.

      -

      Alex: Keep the teaching thread moving. Start with Mistake 1 - Forgetting the blank line between paragraphs: What it produces: One merged paragraph. The next useful detail is this: Fix: Add a blank line between paragraphs.

      -

      Jamie: Let's pause on Mistake 2 - Skipping heading levels. What should a learner take away from it?

      -

      Alex: Here is the plain-English version of Mistake 2 - Skipping heading levels. Why it matters: Screen reader users navigating by heading level will miss entire sections. Put another way, jumping from H1 to H4 means H2 and H3 navigation finds nothing.

      -

      Alex: Keep the teaching thread moving. This is where Mistake 3 - Generic link text becomes real: why it matters: A screen reader user scanning the links list hears "here" - with no context about where the link goes. That matters in practice: Fix: For more information, read the GitHub Documentation. The workshop is closer to rehearsal than lecture. You hear the move, try the move, and then check what changed.

      +

      Jamie: Let's pause on Tool Cards: Fork, Clone, and Contribute. What should a learner take away from it?

      +

      Alex: Start with Tool Cards: Fork, Clone, and Contribute. There is something to understand, something to try, and something that proves the try worked.

      +

      Alex: First, click Fork on the repository page, then Create fork. Then, edit files directly in your fork's web interface. After that, click Contribute Open pull request to submit back to the original. Finally, fork the repo on github.com first. It is a checklist, but a meaningful one: every item creates evidence that the next step is safe.

      +

      Jamie: Before we leave Tool Cards: Fork, Clone, and Contribute, what is the practical point?

      +

      Alex: First, navigate to your fork and press. to open in the web editor. Then, edit, commit, and create a PR from the Source Control panel. After that, fork on github.com, then clone your fork: Ctrl+Shift+P Git: Clone. Finally, create a branch, make edits, commit and push. It is like walking a hallway with named doors: read the sign, enter the right room, then confirm where you landed.

      +

      Alex: Treat examples as spoken recipes, not decorations. You may hear something like 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. Read the command, understand what it changes, then run it only when the repository state matches the lesson.

      +

      Jamie: Let's pause on The Basic Workflow. What should a learner take away from it?

      +

      Alex: Start with The Basic Workflow. There is something to understand, something to try, and something that proves the try worked.

      +

      Alex: First, fork the repository - creates your own copy on GitHub. Then, clone your fork to your computer (or open a Codespace - see Appendix N). After that, create a branch - name it something descriptive: fix/broken-link-setup-guide. Finally, make your change - edit the file, save, verify. It is like walking a hallway with named doors: read the sign, enter the right room, then confirm where you landed.

      +

      Jamie: Before we leave The Basic Workflow, what is the practical point?

      +

      Alex: First, commit with a clear message - "Fix broken link in setup-guide.md line 34". Then, push to your fork. After that, open a pull request from your branch to the original repository's default branch. Finally, respond to review feedback - maintainers may ask for changes; this is normal and not a rejection. The rhythm is simple: orient, act, verify, then continue.

      +

      Jamie: Let's pause on Writing a Good PR Description. What should a learner take away from it?

      +

      Alex: The reason Writing a Good PR Description matters is that example: Fixed a broken link on line 34 of setup-guide.md. That gives the learner a simple foothold: the link pointed to /docs/old-setup which no longer exists.

      +

      Alex: The practical takeaway is this. What did you change? Why was the change needed? How did you verify it works?

      -

      Jamie: Let's pause on Mistake 4 - Missing alt text on images. What should a learner take away from it?

      -

      Alex: Keep the learner anchored in Mistake 4 - Missing alt text on images. Why it matters: Screen reader users have no idea what the image shows. This is the part to say slowly: Some screen readers announce the filename, which is not helpful.

      -

      Alex: Keep the teaching thread moving. The reason Mistake 5 - Using bold instead of headings matters is that why it matters: Visually, this looks like a heading. That gives the learner a simple foothold: but screen reader users navigating with H will never find it.

      -

      Jamie: What does someone need before they touch the keyboard?

      -

      Alex: Start with Mistake 6 - No description before a table: Why it matters: A screen reader user enters the table without knowing what data it contains. The next useful detail is this: They hear "table, 2 columns, 3 rows" but not what the table is about.

      +

      Alex: Keep the teaching thread moving. Start with 7. Getting Help: It is always acceptable to ask a question on an issue or pull request. The next useful detail is this: 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. Think of it like entering a new building: first you find the lobby, then the room, then the door you actually need.

      +

      Alex: The practical takeaway is this. 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.

      +

      Jamie: Let's pause on 8. After Your Contribution Is Merged. What should a learner take away from it?

      +

      Alex: Here is the plain-English version of 8. After Your Contribution Is Merged. This matters for your GitHub profile. Put another way, 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.

      +

      Alex: The practical takeaway is this. 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.

      +

      Alex: Keep the teaching thread moving. This is where 9. Building a Contribution Habit becomes real: the hardest part of open source contribution is starting. That matters in practice: 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.

      -

      Alex: Keep the teaching thread moving. Here is the plain-English version of Mistake 7 - Code block without a language identifier. Why it matters: Without the language identifier, sighted users lose the visual benefit of syntax highlighting, and tools that process Markdown lose metadata about the content. Put another way, fix: Always add the language: `python. It is like learning a transit route. The names of the stops matter because they tell you whether you are still going the right direction.

      -

      Jamie: Let's pause on Mistake 8 - Inconsistent list markers. What should a learner take away from it?

      -

      Alex: This is where Mistake 8 - Inconsistent list markers becomes real: why it matters: While most processors render this as one list, some treat different markers as separate lists, creating unexpected spacing and structure. That matters in practice: Fix: Pick one marker and use it consistently.

      -

      Alex: Keep the teaching thread moving. Keep the learner anchored in Mistake 9 - Mermaid diagram without a text equivalent. Why it matters: Screen reader users cannot access the visual diagram. This is the part to say slowly: They hear nothing or a generic SVG container message.

      +

      Jamie: Let's pause on Practical habits. What should a learner take away from it?

      +

      Alex: Keep the learner anchored in Practical habits. Challenge Time: Complete Challenge 8: The Culture Layer in the Challenge Hub, then advance to Chapter 09: Labels, Milestones and Projects. This is the part to say slowly: Next: Chapter 09: Labels, Milestones, and Projects Back: Chapter 07: Merge Conflicts Related appendices: Appendix M: Accessibility Standards Appendix F: Git Security Appendix O: Branch Protection.

      +

      Alex: The practical takeaway is this. 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.

      +

      Alex: Keep the teaching thread moving. The reason From First Paragraph to Polished Repository - Everything You Need to Know matters is that whether you have never written a single line of Markdown or you already know the basics and want to master the GitHub-specific extensions, this guide takes you from zero to confident. That gives the learner a simple foothold: we start with what Markdown is and why it matters, walk through every foundational element with examples, and then cover the GitHub Flavored Markdown (GFM) features you will encounter in real repositories - alert blocks, Mermaid diagrams, math, footnotes, and. The interface gets friendlier when it stops being a wall of controls and starts being a set of named places.

      +

      Jamie: Let's pause on Part 1 - Markdown Foundations. What should a learner take away from it?

      +

      Alex: Start with Markdown Foundations. There is something to understand, something to try, and something that proves the try worked.

      +

      Alex: First, what Is Markdown? Then, where You Will Use Markdown in This Workshop. After that, how to Practice as You Read. Finally, paragraphs and Line Breaks. Think of it as a rail line: each stop confirms you are still on the right route before the next one.

      +

      Jamie: Before we leave Part 1 - Markdown Foundations, what is the practical point?

      +

      Alex: First, headings. Then, emphasis - Bold, Italic, and Bold Italic. After that, strikethrough. Finally, lists - Ordered and Unordered. Treat it like a recipe: do not add the next ingredient until the previous one is actually in the bowl.

      -

      Jamie: Let's pause on Mistake 10 - Alert block with wrong type. What should a learner take away from it?

      -

      Alex: The reason Mistake 10 - Alert block with wrong type matters is that why it matters: CAUTION (red) implies irreversible harm. That gives the learner a simple foothold: a suggestion to try a different approach is, at most, a TIP (green) or a NOTE (blue).

      -

      Alex: Keep the teaching thread moving. Start with 31. Your First Real Markdown Document - Guided Exercise: In this exercise, you will create a Markdown document that uses most of the elements covered in this guide. The next useful detail is this: This is structured as a hands-on exercise that you can do during the workshop. Think of it like entering a new building: first you find the lobby, then the room, then the door you actually need.

      -

      Jamie: Let's pause on Setup. What should a learner take away from it?

      -

      Alex: Start with Setup. There is something to understand, something to try, and something that proves the try worked.

      -

      Alex: First, open any repository where you have write access. Then, click New Issue (or create a new.md file in VS Code). After that, you will write a mini profile document about yourself. Treat it like a recipe: do not add the next ingredient until the previous one is actually in the bowl.

      +

      Jamie: Let's pause on Part 2 - GitHub Flavored Markdown (GFM). What should a learner take away from it?

      +

      Alex: Start with GitHub Flavored Markdown (GFM). There is something to understand, something to try, and something that proves the try worked.

      +

      Alex: First, what Is GitHub Flavored Markdown? Then, alert and Callout Blocks. After that, collapsible Sections with Details and Summary. Finally, task List Checkboxes. Treat it like a recipe: do not add the next ingredient until the previous one is actually in the bowl.

      +

      Jamie: Before we leave Part 2 - GitHub Flavored Markdown (GFM), what is the practical point?

      +

      Alex: First, syntax Highlighting in Fenced Code Blocks. Then, mermaid Diagrams. After that, math Expressions with LaTeX. Finally, footnotes. It is a checklist, but a meaningful one: every item creates evidence that the next step is safe.

      +

      Jamie: Let's pause on Part 3 - Putting It All Together. What should a learner take away from it?

      +

      Alex: Start with Putting It All Together. There is something to understand, something to try, and something that proves the try worked.

      +

      Alex: First, screen Reader Behavior Summary. Then, accessible Markdown Authoring Checklist. After that, common Mistakes and How to Fix Them. Finally, your First Real Markdown Document - Guided Exercise. It is a checklist, but a meaningful one: every item creates evidence that the next step is safe.

      +

      Jamie: Before we leave Part 3 - Putting It All Together, what is the practical point?

      +

      Alex: First, quick-Reference Card. It is like walking a hallway with named doors: read the sign, enter the right room, then confirm where you landed.

      +

      Alex: Keep the teaching thread moving. Start with Learning Cards: Using This Markdown Reference. There is something to understand, something to try, and something that proves the try worked.

      +

      Alex: The practical takeaway is this. Use heading navigation (H key) to jump between numbered sections -- each topic is an h2 heading. Every section shows raw Markdown first, then rendered output, then screen reader behavior notes. The Table of Contents at the top has anchor links -- activate any link to jump directly to that section. Code blocks show the raw Markdown to type -- increase zoom and the monospace font stays readable. Each section follows the same pattern: explanation, raw code, rendered result, and accessibility notes. Use Ctrl+F to search for a specific Markdown element (e.g., search "table" or "heading").

      -

      Jamie: Let's pause on Step 1 - Add a heading and introduction. What should a learner take away from it?

      -

      Alex: This is where Step 1 - Add a heading and introduction becomes real: type the following, replacing the placeholder text with your own information. That matters in practice: Use the Preview tab (or Ctrl+Shift+V in VS Code) to verify the heading renders as a large title.

      -

      Alex: Treat examples as spoken recipes, not decorations. You may hear something like About Me; Hi! My name is [your name] and I am participating in the; GIT Going with GitHub workshop. Read the command, understand what it changes, then run it only when the repository state matches the lesson.

      -

      Jamie: Let's pause on Step 2 - Add a section with a list. What should a learner take away from it?

      -

      Alex: Keep the learner anchored in Step 2 - Add a section with a list. Verify the numbered list renders correctly.

      -

      Jamie: Let's pause on Step 3 - Add emphasis and inline code. What should a learner take away from it?

      -

      Alex: The reason Step 3 - Add emphasis and inline code matters is that check that bold, italic, and inline code all render as expected. The interface gets friendlier when it stops being a wall of controls and starts being a set of named places.

      -

      Alex: Treat examples as spoken recipes, not decorations. You may hear something like My Setup; I use NVDA on Windows with Firefox. My terminal is; PowerShell and I am learning git commands. Read the command, understand what it changes, then run it only when the repository state matches the lesson.

      +

      Jamie: Let's pause on 1. What Is Markdown? What should a learner take away from it?

      +

      Alex: The reason 1. What Is Markdown? matters is that markdown is a lightweight way to format plain text so it renders as rich, structured content - headings, bold text, links, lists, code blocks, tables, and more. That gives the learner a simple foothold: you write in a plain text file using simple punctuation characters, and a Markdown processor converts those characters into formatted output.

      +

      Alex: Keep the teaching thread moving. Start with A brief history: John Gruber created Markdown in 2004 with the goal of making a format that is "as easy to read and write as plain text." Since then, Markdown has become the default writing format.

      +

      Alex: The practical takeaway is this. GitHub (README files, issues, pull requests, comments, wikis, discussions). Stack Overflow and many developer forums. Static site generators (Jekyll, Hugo, Gatsby). Note-taking apps (Obsidian, Notion, Bear). Documentation systems (MkDocs, Docusaurus, Read the Docs). Chat platforms (Slack, Discord, Microsoft Teams).

      +

      Jamie: Let's pause on Markdown versus HTML. What should a learner take away from it?

      +

      Alex: Here is the plain-English version of Markdown versus HTML. Markdown converts to HTML behind the scenes. Put another way, when you write bold, GitHub converts it to bold.

      -

      Jamie: Let's pause on Step 5 - Add a table. What should a learner take away from it?

      -

      Alex: Start with Step 5 - Add a table. There is something to understand, something to try, and something that proves the try worked.

      -

      Alex: Treat examples as spoken recipes, not decorations. You may hear something like Tools I Use; The following table lists the tools I use daily.; Tool Purpose Platform; --- --- ---; NVDA Screen reader Windows; Firefox Web browser Windows; VS Code Code editor Windows. Read the command, understand what it changes, then run it only when the repository state matches the lesson.

      -

      Jamie: Let's pause on Step 7 - Add a collapsible section. What should a learner take away from it?

      -

      Alex: Start with Step 7 - Add a collapsible section. There is something to understand, something to try, and something that proves the try worked.

      -

      Alex: Treat examples as spoken recipes, not decorations. You may hear something like Additional Notes;; My accessibility testing experience; I have been using a screen reader for three years. I have tested; web applications with NVDA and I am learning how to contribute; accessibility bug reports to open source projects. Read the command, understand what it changes, then run it only when the repository state matches the lesson.

      -

      Jamie: Let's pause on You are done when. What should a learner take away from it?

      -

      Alex: This is where You are done when becomes real: you just wrote a Markdown document that uses headings, paragraphs, emphasis, inline code, links, blockquotes, tables, task lists, and collapsible sections. That matters in practice: Every one of these skills transfers directly to issues, pull requests, and documentation in this workshop.

      -

      Alex: The practical takeaway is this. Your document renders with a clear heading hierarchy (H1, H2). Bold and italic text render correctly. The numbered list shows sequential numbers. The link is clickable.

      +

      Alex: Keep the teaching thread moving. This is where What gets rendered and what stays raw becomes real: when you view a.md file on GitHub, GitHub renders it automatically. That matters in practice: When you edit that file, you see the raw Markdown. The workshop is closer to rehearsal than lecture. You hear the move, try the move, and then check what changed.

      +

      Jamie: Where does the workshop stop being a tour and start becoming contribution?

      +

      Alex: Keep the learner anchored in 2. Where You Will Use Markdown in This Workshop. Markdown is not just one tool in this workshop - it is the thread that connects everything you do. This is the part to say slowly: Here is every place you will write or read Markdown during the two days.

      +

      Alex: Keep the teaching thread moving. The reason Day 1 - GitHub Foundations (Browser) matters is that the following table lists every Day 1 activity where Markdown is used.

      -

      Alex: Keep the teaching thread moving. Start with Learning Cards: Quick-Reference Card. There is something to understand, something to try, and something that proves the try worked.

      -

      Alex: The practical takeaway is this. This card shows raw Markdown syntax in code blocks -- read each block to hear the exact characters to type. Keep this section bookmarked as a daily reference when writing issues, PRs, and comments. Each code block is labeled by format type (headings, lists, links, etc.) in the heading above it. The card uses large monospace code blocks -- increase zoom and each syntax example stays on one or two lines. Print this section or save it as a separate file for quick side-by-side reference while writing. Syntax characters (,, -, []) are visually distinct in the code font.

      -

      Jamie: Let's pause on 32. Quick-Reference Card. What should a learner take away from it?

      -

      Alex: The reason 32. Quick-Reference Card matters is that it shows the raw Markdown for every element covered in this guide.

      -

      Jamie: Let's pause on HTML in Markdown. What should a learner take away from it?

      -

      Alex: Start with HTML in Markdown. There is something to understand, something to try, and something that proves the try worked.

      -

      Alex: Treat examples as spoken recipes, not decorations. You may hear something like Press Ctrl + C to copy.; H 2 O; x 2; Line one Line two. Read the command, understand what it changes, then run it only when the repository state matches the lesson.

      +

      Jamie: How should they picture the shape of the workshop?

      +

      Alex: Start with Day 2 - VS Code and Accessibility Agents: The following table lists every Day 2 activity where Markdown is used.

      +

      Alex: Keep the teaching thread moving. Here is the plain-English version of Learning Room connection. In the Learning Room repository, every challenge description, every welcome file, and every piece of documentation is Markdown. Put another way, when you fix a broken link in docs/welcome.md for Challenge 1, you are editing Markdown. It is like learning a transit route. The names of the stops matter because they tell you whether you are still going the right direction.

      +

      Jamie: Let's pause on 3. How to Practice as You Read. What should a learner take away from it?

      +

      Alex: This is where 3. How to Practice as You Read becomes real: the best way to learn Markdown is to type it yourself. That matters in practice: Here are three ways to practice as you read this guide.

      +
      +

      Jamie: Let's pause on Option 1 - GitHub Issue (recommended for Day 1). What should a learner take away from it?

      +

      Alex: Keep the learner anchored in Option 1 - GitHub Issue (recommended for Day 1). The Write and Preview tabs are announced as tab buttons. This is the part to say slowly: Press Enter on "Preview" to switch.

      +

      Alex: First, go to any repository where you have write access (the Learning Room works). Then, click New Issue. After that, type Markdown in the issue body. Finally, click the Preview tab to see the rendered result. It is like walking a hallway with named doors: read the sign, enter the right room, then confirm where you landed.

      +

      Jamie: Before we leave Option 1 - GitHub Issue (recommended for Day 1), what is the practical point?

      +

      Alex: First, switch back to Write to keep editing. Then, you do not need to submit the issue - the Preview tab is your sandbox. The rhythm is simple: orient, act, verify, then continue.

      +

      Jamie: Let's pause on Option 2 - Any.md file in VS Code (recommended for Day 2). What should a learner take away from it?

      +

      Alex: Start with Option 2 - Any.md file in VS Code (recommended for Day 2). There is something to understand, something to try, and something that proves the try worked.

      +

      Alex: First, create a new file: Ctrl+N, then save it as practice.md. Then, type your Markdown in the editor. After that, press Ctrl+Shift+V to open the rendered Markdown preview in a new tab. Finally, the preview updates live as you type. The rhythm is simple: orient, act, verify, then continue.

      +

      Jamie: Let's pause on Option 3 - GitHub Gist. What should a learner take away from it?

      +

      Alex: Start with Option 3 - GitHub Gist. There is something to understand, something to try, and something that proves the try worked.

      +

      Alex: First, go to gist.github.com. Then, name your file practice.md. After that, type Markdown in the content area. Finally, click Create secret gist (only you can see it). Think of it as a rail line: each stop confirms you are still on the right route before the next one.

      +

      Jamie: Before we leave Option 3 - GitHub Gist, what is the practical point?

      +

      Alex: First, view the rendered result. Treat it like a recipe: do not add the next ingredient until the previous one is actually in the bowl.

      -

      Jamie: Let's pause on Mermaid diagram (with accessible text). What should a learner take away from it?

      -

      Alex: Here is the plain-English version of Mermaid diagram (with accessible text). Next: Appendix D: Git Authentication Back: Appendix B: Screen Reader Cheat Sheet Teaching chapter: Chapter 06: Working with Pull Requests.

      +

      Jamie: Let's pause on 4. Paragraphs and Line Breaks. What should a learner take away from it?

      +

      Alex: Here is the plain-English version of 4. Paragraphs and Line Breaks. This is the most fundamental element in Markdown, and it trips up almost everyone at first.

      +

      Alex: Keep the teaching thread moving. This is where Paragraphs becomes real: a paragraph is one or more lines of text separated by a blank line (an empty line with nothing on it). That matters in practice: If you do not leave a blank line between two blocks of text, Markdown treats them as one continuous paragraph.

      +

      Jamie: Let's pause on Line breaks within a paragraph. What should a learner take away from it?

      +

      Alex: Keep the learner anchored in Line breaks within a paragraph. Sometimes you want to go to a new line without starting a whole new paragraph - for example, in an address or a poem. This is the part to say slowly: To create a line break (a in HTML), end a line with two or more spaces and then press Enter.

      -

      Jamie: What is the final checkpoint?

      -

      Alex: You should be able to point to the evidence, explain the action, and describe what you would do next if this were a real open source project. If you can teach the move back, you have learned it.

      -

      Jamie: And if they get stuck?

      -

      Alex: Read the latest message, not the loudest worry. Check the issue, the branch, the pull request, the status check, or the bot comment. Then ask for help with those facts in hand. That is how professionals collaborate.

      -
      - +

      Alex: Keep the teaching thread moving. The reason Common mistake - no blank line between paragraphs matters is that what renders (wrong): Both lines merge into one paragraph. That gives the learner a simple foothold: fix: Add a blank line between them. The interface gets friendlier when it stops being a wall of controls and starts being a set of named places.

      +

      Jamie: Let's pause on 5. Headings. What should a learner take away from it?

      +

      Alex: Start with 5. Headings: Headings create the structure of your document. The next useful detail is this: They are how screen readers navigate, how tables of contents are built, and how readers scan for the section they need.

      +

      Alex: Keep the teaching thread moving. Here is the plain-English version of Syntax. Add one to six characters at the start of a line, followed by a space, then the heading text. Put another way, the number of characters determines the heading level.

      -

      Challenge bonus-c: Group Challenge

      -

      Collaborative contribution, division of work, and communication across a small team.

      -
      -Read Transcript - Challenge bonus-c: Group Challenge - -

      Transcript

      -

      Alex: You are listening to Challenge Coach: Group Challenge. I am Alex, and this is the calm walkthrough before the hands-on work.

      -

      Jamie: And I am Jamie. I will make sure we teach the skill instead of just reading the checklist aloud.

      +

      Jamie: Let's pause on Rules for accessible headings. What should a learner take away from it?

      +

      Alex: This is where Rules for accessible headings becomes real: screen readers let you navigate by heading level. That matters in practice: In NVDA and JAWS, pressing H moves to the next heading.

      +

      Alex: First, one H1 per document. The heading is your document title. Every document gets exactly one. Then, never skip levels. Go from to, never from to. Skipping levels breaks the document outline for screen reader users who navigate by heading. After that, make headings descriptive. A heading of "Section 3" tells a screen reader user nothing. A heading of "Creating Your First Pull Request" tells them exactly what the section covers. Finally, do not use bold as a heading substitute. Writing My Section on its own line looks like a heading visually, but it is not a heading in the document structure. Screen reader users navigating by heading (H key in Browse Mode) will never find it. It is a checklist, but a meaningful one: every item creates evidence that the next step is safe.

      +

      Alex: Keep the teaching thread moving. Keep the learner anchored in Alternative heading syntax (not recommended). Markdown also supports "setext" headings where you underline text with = or - characters. This is the part to say slowly: This only works for levels 1 and 2, and it is harder to scan visually in raw Markdown. A good GitHub workflow is like a well-run meeting: everyone knows the topic, the next action, and who has the floor.

      +

      Jamie: Let's pause on 6. Emphasis - Bold, Italic, and Bold Italic. What should a learner take away from it?

      +

      Alex: The reason 6. Emphasis - Bold, Italic, and Bold Italic matters is that emphasis changes how text is read by screen readers - it is not just visual. That gives the learner a simple foothold: when text is bold or italic, well-configured screen readers can announce emphasis changes, giving the listener additional context about importance.

      -

      Alex: The focus is Collaborative contribution, division of work, and communication across a small team. We will explain the concept, the action, the evidence, and the most common recovery path.

      -

      Jamie: So the learner needs the why, the move, and the checkpoint all in the same mental pocket.

      -

      Alex: That is the teaching shape: understand the concept, do the smallest real action, then verify the result before moving on.

      +

      Alex: Keep the teaching thread moving. Start with Bold: Wrap text in two asterisks or two underscores on each side. The next useful detail is this: This is bold text using underscores.

      +

      Jamie: Let's pause on Italic. What should a learner take away from it?

      +

      Alex: Here is the plain-English version of Italic. Wrap text in one asterisk or one underscore on each side. Put another way, this is italic text using asterisks.

      +

      Alex: Keep the teaching thread moving. This is where Bold and italic combined becomes real: wrap text in three asterisks on each side. The workshop is closer to rehearsal than lecture. You hear the move, try the move, and then check what changed.

      -

      Jamie: What makes this practice feel low-stakes but still real?

      -

      Alex: Start with Bonus C: Create a Group Challenge: For students who: Want to design exercises for future cohorts. The next useful detail is this: What you will do: Design a collaborative challenge that 3-5 students could work on together, then document it in the learning-room.

      -

      Jamie: How would you walk the room through that step by step?

      -

      Alex: Start with Instructions. There is something to understand, something to try, and something that proves the try worked.

      -

      Alex: The practical anchors are these. Title -- a catchy, descriptive name. Goal -- what students will learn or accomplish. Team size -- how many people (recommend 3-5). Time estimate -- how long it should take. Instructions -- step-by-step guide. Success criteria -- how do students know they are done?

      -

      Alex: First, think of a task that requires collaboration -- something one person cannot easily do alone. Then, create a file: docs/group-challenges/YOUR-USERNAME-challenge.md. After that, your challenge design must. Finally, commit, push, and open a PR. Treat it like a recipe: do not add the next ingredient until the previous one is actually in the bowl.

      -

      Jamie: What is the one idea that makes the next few steps less mysterious?

      -

      Alex: Start with Design criteria. There is something to understand, something to try, and something that proves the try worked.

      -

      Alex: That shows up in the workshop in a few specific ways. Require genuine collaboration (not just dividing work). Have clear success criteria. Are accessible to all participants. Can be completed within the workshop timeframe.

      +

      Jamie: Can you translate that into plain choices?

      +

      Alex: Keep the learner anchored in When to use emphasis. The following table provides guidance on when to use each type of emphasis. This is the part to say slowly: NVDA can announce emphasis changes if the user enables "Report font attributes" (under Speech settings).

      +

      Alex: Use the comparison to make a decision, not to recite a table. The main contrasts are: Key terms, important warnings, UI element names means "Click the Submit button". Book or document titles, introducing new terms, gentle emphasis means "See the Contributing Guide for details". Bold italic means Extremely rare - critical warnings only means " Do not force push to the main branch ".

      +

      Alex: Keep the teaching thread moving. The reason Emphasis inside words matters is that underscores do not (in most Markdown processors including GitHub). That gives the learner a simple foothold: use asterisks when you need emphasis inside a word (rare, but it comes up in technical documentation).

      +

      Jamie: Let's pause on 7. Strikethrough. What should a learner take away from it?

      +

      Alex: Start with 7. Strikethrough: Strikethrough text shows deleted or outdated content with a line through it. The next useful detail is this: Wrap text in two tildes on each side.

      -

      Alex: Now bring the learner back to the room. Keep the learner anchored in Challenge description. Students audit a sample web page for accessibility issues, relay-style. This is the part to say slowly: Each person has a different focus area.

      -

      Alex: For a learner, the useful signals are these. Student 1: Checks all images for meaningful alt text. Student 2: Reviews heading hierarchy (H1, H2, H3 order). Student 3: Tests every link for descriptive text (no "click here"). Student 4: Checks color contrast on text elements.

      -

      Jamie: What is the ordered workflow?

      -

      Alex: Start with How it works. There is something to understand, something to try, and something that proves the try worked.

      -

      Alex: First, the group forks a sample repository containing a deliberately imperfect HTML page. Then, each student creates a branch for their focus area. After that, each student files issues for the problems they find. Finally, the group discusses which fixes to prioritize. The rhythm is simple: orient, act, verify, then continue.

      -

      Jamie: Give me the sequence, because order matters here.

      -

      Alex: First, each student submits a PR fixing at least one issue. Then, the group reviews and merges each other's PRs. Think of it as a rail line: each stop confirms you are still on the right route before the next one.

      -

      Alex: The useful habit is simple: orient first, act second, verify third. That pause before acting is part of the work.

      -

      Alex: That matters because of the next idea. Start with Evidence: Each student posts: their issues filed, their PR, and one review they gave. Think of it like entering a new building: first you find the lobby, then the room, then the door you actually need.

      +

      Alex: Keep the teaching thread moving. Here is the plain-English version of 8. Lists - Ordered and Unordered. Lists are one of the most common elements in GitHub documentation. Put another way, issue descriptions, PR checklists, README instructions, step-by-step guides - they all use lists. It is like learning a transit route. The names of the stops matter because they tell you whether you are still going the right direction.

      +

      Jamie: Let's pause on Unordered lists (bullet points). What should a learner take away from it?

      +

      Alex: This is where Unordered lists (bullet points) becomes real: start each line with a dash (-), asterisk ( ), or plus sign (+) followed by a space. That matters in practice: They are the most common convention on GitHub and visually distinct from the asterisks used for bold and italic.

      +

      Alex: The practical takeaway is this. First item. Second item. Third item.

      +

      Jamie: Let's pause on Ordered lists (numbered). What should a learner take away from it?

      +

      Alex: Keep the learner anchored in Ordered lists (numbered). Start each line with a number followed by a period and a space.

      +

      Alex: First, clone the repository. Then, create a new branch. After that, make your changes. Finally, open a pull request. It is like walking a hallway with named doors: read the sign, enter the right room, then confirm where you landed.

      -

      Jamie: Okay, set the room for us. What are we walking into?

      -

      Alex: Start with Why this works for a group. There is something to understand, something to try, and something that proves the try worked.

      -

      Alex: Here is what that changes in practice. Every student has a defined role so no one is left out. The relay structure means students depend on each other (Student 3 cannot fix link text if Student 1 has not pushed their alt text fixes yet). The final product is a genuinely more accessible page.

      -

      Alex: This is where the talk moves from concept to action. This is where What matters becomes real: the learning objective is designing collaborative work that gives every participant a meaningful role. That matters in practice: If your challenge design includes clear roles, concrete deliverables, and a reason for people to work together (not just alongside each other), you completed this bonus.

      -

      Jamie: Where do you want a learner to place their attention here?

      -

      Alex: Keep the learner anchored in How to Be an Effective and Respectful Open Source Contributor. Technical skills get your code into a project. This is the part to say slowly: Communication skills keep you welcomed in the community.

      +

      Jamie: What do you want them to do when the plan breaks?

      +

      Alex: The reason A helpful trick - Markdown renumbers for you matters is that here is something that surprises most new users. That gives the learner a simple foothold: in Markdown, the actual numbers you type do not matter for the rendered output.

      +

      Alex: Keep the teaching thread moving. Start with Starting an ordered list at a specific number: If you need a list to start at a number other than 1, use that number for the first item. The next useful detail is this: All subsequent items are numbered sequentially from there. Think of it like entering a new building: first you find the lobby, then the room, then the door you actually need.

      +

      Jamie: Let's pause on 9. Nested Lists and Mixed Lists. What should a learner take away from it?

      +

      Alex: Here is the plain-English version of 9. Nested Lists and Mixed Lists. Lists can contain other lists, creating an indented hierarchy. Put another way, this is essential for complex instructions, outlines, and project structures.

      -

      Alex: Before the learner moves on. The reason Workshop Recommendation (Chapter 8) matters is that chapter 8 is a communication and culture chapter. The interface gets friendlier when it stops being a wall of controls and starts being a set of named places.

      -

      Alex: That becomes easier when you listen for these cues. There are 1 guided reflection (no bot grading). Automation check: none - communication quality is too subjective for fair automated scoring. The evidence is structured reflection comment on your assigned challenge issue. The pattern is read, reflect, commit to one behavior.

      -

      Jamie: What does the learner do first, second, and then after that?

      -

      Alex: Start with Chapter 8 Challenge Set. There is something to understand, something to try, and something that proves the try worked.

      -

      Alex: First, guided reflection - read the chapter, then post a short reflection comment committing to three specific collaboration behaviors. Think of it as a rail line: each stop confirms you are still on the right route before the next one.

      -

      Jamie: Turn that into a path someone can follow.

      -

      Alex: Here is the plain-English version of Challenge 8.1 Step-by-Step: Guided Reflection. Identify three concrete communication behaviors you will practice during the rest of the workshop. Put another way, your assigned Chapter 8 challenge issue in your Learning Room repository on GitHub.com.

      -

      Alex: The parts worth keeping in working memory are these. 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.".

      -

      Alex: First, read through the chapter content below, paying attention to the sections on GitHub Flow, constructive feedback, and asking for help. Then, as you read, think about one situation from Day 1 where communication helped (or could have helped) you. After that, open your assigned Chapter 8 challenge issue (the one titled "Chapter 8.1: Guided Reflection (@yourname)"). Finally, scroll to the comment box at the bottom of the issue. Treat it like a recipe: do not add the next ingredient until the previous one is actually in the bowl.

      -

      Jamie: Let's pause on Challenge 8.1 Step-by-Step: Guided Reflection. What should a learner take away from it?

      -

      Alex: First, post a reflection comment using this format. Then, for each prompt, write one specific, actionable sentence - not a vague goal. After that, activate the Comment button (or press Ctrl+Enter). It is a checklist, but a meaningful one: every item creates evidence that the next step is safe.

      +

      Jamie: Let's pause on Nesting unordered lists. What should a learner take away from it?

      +

      Alex: This is where Nesting unordered lists becomes real: indent the nested items by two or four spaces (GitHub accepts either, but four is most reliable).

      +

      Alex: The practical takeaway is this. Accessibility testing tools. Screen readers. NVDA (Windows, free). JAWS (Windows, commercial). VoiceOver (macOS and iOS, built-in). Browser extensions.

      +

      Alex: Treat examples as spoken recipes, not decorations. You may hear something like Accessibility testing tools; - Screen readers; - NVDA (Windows, free); - JAWS (Windows, commercial); - VoiceOver (macOS and iOS, built-in); - Browser extensions; - axe DevTools; - WAVE; - Documentation tools; - Markdown editors; - Static site generators. Read the command, understand what it changes, then run it only when the repository state matches the lesson.

      +

      Jamie: Let's pause on Nesting ordered lists. What should a learner take away from it?

      +

      Alex: Keep the learner anchored in Nesting ordered lists. The same indentation principle applies to numbered lists.

      +

      Alex: Keep the teaching thread moving. The reason Mixing ordered and unordered lists matters is that you can nest an unordered list inside an ordered list and vice versa. The interface gets friendlier when it stops being a wall of controls and starts being a set of named places.

      -

      Jamie: How do these exercises create confidence instead of pressure?

      -

      Alex: This is where Completing Chapter 8: Submit Your Evidence becomes real: the reflection comment itself is your evidence. That matters in practice: The facilitator reviews your comment for specificity.

      -

      Alex: That connects to another useful point. Start with Expected Outcomes. There is something to understand, something to try, and something that proves the try worked.

      -

      Alex: On the ground, that means a few things. 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.

      -

      Jamie: Let's pause on If You Get Stuck. What should a learner take away from it?

      -

      Alex: Start with If You Get Stuck. There is something to understand, something to try, and something that proves the try worked.

      -

      Alex: First, use one simple sentence per prompt - do not overthink it. Then, focus on one real behavior you can start doing today, not an abstract principle. After that, if writing feels hard, draft bullet points first in a text editor, then paste into the comment. Finally, look at the "Giving Feedback" and "Asking for Help" sections in this chapter for concrete examples. The rhythm is simple: orient, act, verify, then continue.

      -

      Jamie: Before we leave If You Get Stuck, what is the practical point?

      -

      Alex: First, ask facilitator for one example response and adapt it to your own words. Then, finished but not sure you did it right? Compare your work against the Challenge 8 reference solution. Think of it as a rail line: each stop confirms you are still on the right route before the next one.

      +

      Jamie: Let's pause on Adding content inside list items. What should a learner take away from it?

      +

      Alex: Start with Adding content inside list items: List items can contain paragraphs, code blocks, and other elements. The next useful detail is this: Indent the content to align with the list item text (typically four spaces).

      +

      Alex: Treat examples as spoken recipes, not decorations. You may hear something like Clone the repository; Open your terminal and run the following command. Read the command, understand what it changes, then run it only when the repository state matches the lesson.

      +

      Alex: Keep the teaching thread moving. Here is the plain-English version of 10. Links. Links are how you connect documents, reference issues, point to external resources, and cite sources. Put another way, getting links right is critical for accessibility - links with bad text are one of the most common accessibility failures in documentation.

      +

      Jamie: Let's pause on Basic link syntax. What should a learner take away from it?

      +

      Alex: This is where Basic link syntax becomes real: wrap the visible link text in square brackets, followed immediately by the URL in parentheses.

      -

      Alex: Here is the practical turn. Start with Learning Moment: Technical quality and communication quality work together. The next useful detail is this: Respectful, clear communication helps good code get merged faster.

      -

      Jamie: Let's pause on Learning Pattern Used in This Chapter. What should a learner take away from it?

      -

      Alex: Start with Learning Pattern Used in This Chapter. There is something to understand, something to try, and something that proves the try worked.

      -

      Alex: First, read and absorb community norms (not just rules, but reasons). Then, reflect on personal experience (what worked, what was hard). After that, commit to specific behaviors in writing (public accountability). Finally, apply those behaviors in upcoming chapters (reviews, comments, PRs). Treat it like a recipe: do not add the next ingredient until the previous one is actually in the bowl.

      -

      Alex: Keep the thread going. This is where GitHub Flow - The Standard Contribution Workflow becomes real: before diving into communication norms, it helps to understand the workflow that gives all of those conversations their context. That matters in practice: GitHub Flow is the lightweight branching model recommended for open source contribution. The workshop is closer to rehearsal than lecture. You hear the move, try the move, and then check what changed.

      +

      Alex: Keep the teaching thread moving. Keep the learner anchored in Links with title text. Add a title in quotes after the URL. This is the part to say slowly: The title appears as a tooltip on hover. A good GitHub workflow is like a well-run meeting: everyone knows the topic, the next action, and who has the floor.

      +

      Jamie: Let's pause on Writing accessible link text. What should a learner take away from it?

      +

      Alex: The reason Writing accessible link text matters is that this is one of the most important accessibility skills in Markdown authoring. That gives the learner a simple foothold: screen reader users often navigate by pulling up a list of all links on a page (NVDA: NVDA+F7 then select Links; JAWS: Insert+F7).

      +

      Alex: Keep the teaching thread moving. Start with Reference-style links: For documents with many links, reference-style links keep the text readable by separating the URL from the prose. The next useful detail is this: You define the link target once at the bottom of the document.

      -

      Jamie: If I am listening before the workshop starts, what should settle in my mind first?

      -

      Alex: Start with Why This Model Works. There is something to understand, something to try, and something that proves the try worked.

      -

      Alex: These are the details that keep the idea from floating away. 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.

      -

      Alex: Another way to ground it. The reason GitHub Flow vs Git Flow matters is that you may encounter "Git Flow" (sometimes written "GitFlow") in older projects or enterprise environments. That gives the learner a simple foothold: this section explains what Git Flow is, how it differs from GitHub Flow, and why this workshop teaches GitHub Flow.

      -

      Alex: A solid Git habit is to know which branch you are on, what changed, and what confirmation you expect before you run the next command.

      -

      Jamie: What would you say to someone who is already bracing for this to be too much?

      -

      Alex: Start with What Git Flow Is: Git Flow is a branching model published by Vincent Driessen in 2010. The next useful detail is this: It was designed for teams that ship versioned releases on a schedule (desktop software, mobile apps, embedded systems).

      +

      Jamie: Let's pause on Relative links within a repository. What should a learner take away from it?

      +

      Alex: Here is the plain-English version of Relative links within a repository. When linking to other files in the same repository, use relative paths instead of full URLs. Put another way, this way, links work on any fork or branch.

      +

      Alex: Keep the teaching thread moving. This is where Email links becomes real: the angle brackets tell Markdown to create a mailto: link. The workshop is closer to rehearsal than lecture. You hear the move, try the move, and then check what changed.

      +

      Jamie: Let's pause on Autolinked URLs. What should a learner take away from it?

      +

      Alex: Keep the learner anchored in Autolinked URLs. GitHub automatically converts full URLs in your text into clickable links, but always prefer explicit descriptive links in prose. This is the part to say slowly: Bare URLs should only appear in reference sections or code examples.

      -

      Jamie: Let's pause on How the Git Flow Cycle Works. What should a learner take away from it?

      -

      Alex: Start with How the Git Flow Cycle Works. There is something to understand, something to try, and something that proves the try worked.

      -

      Alex: First, developers branch feature/my-feature off develop and work there. Then, completed features merge back into develop via pull request. After that, when develop has enough features for a release, a release/1.2.0 branch is created. Finally, the release branch gets final testing, bug fixes, and version number updates. Treat it like a recipe: do not add the next ingredient until the previous one is actually in the bowl.

      -

      Jamie: Before we leave How the Git Flow Cycle Works, what is the practical point?

      -

      Alex: First, the release branch merges into main (tagged with the version) and back into develop. Then, if a critical bug is found in production, a hotfix/ branch is created from main, fixed, and merged into both main and develop. It is a checklist, but a meaningful one: every item creates evidence that the next step is safe.

      -

      Jamie: Give me the version that sounds like an instructor, not a manual.

      -

      Alex: This is where How GitHub Flow Differs becomes real: the following table compares GitHub Flow and Git Flow across key dimensions.

      -

      Alex: A solid pull request habit is to separate three questions: what changed, why it changed, and what still needs review. That keeps the conversation useful instead of noisy.

      -

      Alex: The next layer is this. Start with When You Might See Git Flow. There is something to understand, something to try, and something that proves the try worked.

      -

      Alex: The room should hear these as checkpoints. 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.

      +

      Alex: Keep the teaching thread moving. Start with Learning Cards: Links. There is something to understand, something to try, and something that proves the try worked.

      +

      Alex: The practical takeaway is this. Pull up a links list (NVDA: NVDA+F7 then Links tab; JAWS: Insert+F7) to audit your document -- every link must make sense without its surrounding sentence. Reference-style links ([text][ref]) produce identical HTML to inline links -- screen readers announce them the same way, so choose whichever keeps your source readable. Relative links to other repo files (e.g., Setup) work on any fork or branch -- prefer them over full URLs for internal documentation. Links render as blue underlined text by default -- if your GitHub theme reduces underline visibility, rely on the color difference or hover state to identify links. Long URLs in link text are hard to read at high zoom; always use descriptive text like Contributing Guide instead of pasting the raw URL. The title attribute (text in quotes after the URL) appears as a tooltip on hover -- useful at high magnification but do not put essential information only there.

      +

      Jamie: Let's pause on 11. Images. What should a learner take away from it?

      +

      Alex: Start with 11. Images: Images in Markdown use a syntax similar to links, with an exclamation mark (!) at the beginning.

      +

      Alex: Keep the teaching thread moving. Here is the plain-English version of Syntax. The text inside the square brackets is the alt text - the description that screen readers read aloud instead of displaying the image. Put another way, this is the single most important accessibility attribute for images. It is like learning a transit route. The names of the stops matter because they tell you whether you are still going the right direction.

      -

      Jamie: Where is the promise of the workshop, underneath all the logistics?

      -

      Alex: The reason Why This Workshop Uses GitHub Flow matters is that for open source contribution - especially at a hackathon or when contributing to web-based projects - GitHub Flow is what you want. That gives the learner a simple foothold: it is what GitHub itself uses and what most modern open source projects follow.

      -

      Alex: This is the part worth saying out loud. Start with The Unwritten Rule: One Thing Per Branch: A branch and its PR should do one thing. The next useful detail is this: If you are fixing a broken link and you notice a typo nearby, fix the typo in a separate branch and PR. Think of it like entering a new building: first you find the lobby, then the room, then the door you actually need.

      -

      Jamie: Let's pause on Learning Cards: GitHub Flow. What should a learner take away from it?

      -

      Alex: Start with Learning Cards: GitHub Flow. There is something to understand, something to try, and something that proves the try worked.

      -

      Alex: A few details make that real. 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). 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.

      +

      Jamie: Let's pause on Writing good alt text. What should a learner take away from it?

      +

      Alex: This is where Writing good alt text becomes real: the following table provides guidance on alt text for different types of images.

      +

      Alex: Keep the teaching thread moving. Keep the learner anchored in Image with a link. To make an image clickable, wrap the image syntax inside a link.

      +

      Jamie: Let's pause on When to use details blocks for complex images. What should a learner take away from it?

      +

      Alex: The reason When to use details blocks for complex images matters is that if an image contains complex information (like an architecture diagram or a data visualization), provide a full text description in a collapsible block. That gives the learner a simple foothold: screen readers announce images as "graphic" followed by the alt text.

      -

      Alex: Hold that next to this. This is where Keeping Your Fork Up to Date becomes real: when you fork a repository, you get a snapshot of the project at that moment. That matters in practice: The original repository (called "upstream") continues to evolve.

      -

      Jamie: Let's pause on Why Sync Your Fork? What should a learner take away from it?

      -

      Alex: Start with Why Sync Your Fork? There is something to understand, something to try, and something that proves the try worked.

      -

      Alex: The practical takeaway is this. 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.

      -

      Jamie: Let's pause on Method 1: GitHub Web Interface (Easiest). What should a learner take away from it?

      -

      Alex: The reason Method 1: GitHub Web Interface (Easiest) matters is that GitHub merges the upstream changes into your fork automatically. That gives the learner a simple foothold: screen reader users (NVDA / JAWS / VoiceOver). The interface gets friendlier when it stops being a wall of controls and starts being a set of named places.

      -

      Alex: First, navigate to your fork's main page: github.com/your-username/repo-name. Then, look for the sync indicator: "This branch is X commits behind upstream/main". After that, click the "Sync fork" button. Finally, click "Update branch". The rhythm is simple: orient, act, verify, then continue.

      -

      Jamie: Before we leave Method 1: GitHub Web Interface (Easiest), what is the practical point?

      -

      Alex: First, the sync button appears in the landmark that contains the branch selector. Then, press D to cycle through landmarks until you reach that region. After that, press B to cycle buttons until you hear "Sync fork" → press Enter. Finally, a dialog or page update presents "Update branch" - activate it. Think of it as a rail line: each stop confirms you are still on the right route before the next one.

      +

      Alex: Keep the teaching thread moving. Start with Learning Cards: Images. There is something to understand, something to try, and something that proves the try worked.

      +

      Alex: The practical takeaway is this. Alt text is read aloud as the only representation of the image -- write it to answer "what information does this image convey?" not just "what does it look like?". For decorative images, use empty alt text ( ) so the screen reader skips them entirely rather than announcing the filename. Complex images (architecture diagrams, charts) need a full text description in a block below the image -- expand it to read the complete information. Images render at their original size by default -- use browser or VS Code zoom to enlarge them, and ensure alt text is present in case the image becomes too pixelated. Screenshots with small text are the hardest images to read at high magnification -- request that contributors use cropped, focused screenshots instead of full-screen captures. The alt text is invisible in the rendered view but visible in the raw Markdown source -- switch to the source view to verify alt text exists on all images.

      +

      Jamie: Let's pause on 12. Blockquotes. What should a learner take away from it?

      +

      Alex: Here is the plain-English version of 12. Blockquotes. Blockquotes are used for callouts, important notes, cited text, and instructor guidance throughout this course. Put another way, start each line with a character followed by a space.

      +

      Alex: Keep the teaching thread moving. This is where Basic blockquote becomes real: it is used to highlight important information or to quote someone else's text.

      -

      Jamie: There are a lot of tools in play. How do we keep that from feeling like a contest?

      -

      Alex: Start with Method 2: Git Command Line (VS Code Terminal): If you're working locally in VS Code.

      -

      Jamie: What should happen before anyone copies and runs it?

      -

      Alex: Start with One-time setup - add the upstream remote. There is something to understand, something to try, and something that proves the try worked.

      -

      Alex: Treat examples as spoken recipes, not decorations. You may hear something like git remote add upstream https://github.com/original-owner/repo-name.git; git remote -v Verify it was added. Read the command, understand what it changes, then run it only when the repository state matches the lesson.

      -

      Jamie: What should they understand before typing anything?

      -

      Alex: Start with Sync process. There is something to understand, something to try, and something that proves the try worked.

      -

      Alex: Treat examples as spoken recipes, not decorations. You may hear something like 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. Read the command, understand what it changes, then run it only when the repository state matches the lesson.

      +

      Jamie: Let's pause on Multi-paragraph blockquotes. What should a learner take away from it?

      +

      Alex: Keep the learner anchored in Multi-paragraph blockquotes. Add a on the blank lines between paragraphs to keep them inside the blockquote.

      +

      Alex: Keep the teaching thread moving. The reason Blockquotes with other elements matters is that blockquotes can contain any Markdown element - headings, lists, code, bold, links. That gives the learner a simple foothold: screen readers announce the beginning and end of a blockquote. The interface gets friendlier when it stops being a wall of controls and starts being a set of named places.

      +

      Jamie: Zoom out for a second. What kind of journey is this?

      +

      Alex: Start with How we use blockquotes in this course: Throughout this workshop, blockquotes serve specific purposes.

      +

      Alex: The practical takeaway is this. Screen reader notes: Tips specific to assistive technology users. Learning Room connections: How the current topic connects to the practice repo. Important warnings: Critical information that could prevent errors. Instructor guidance: Notes from the facilitator about pacing or approach.

      -

      Alex: Keep the teaching thread moving. Start with When to sync. There is something to understand, something to try, and something that proves the try worked.

      -

      Alex: The practical takeaway is this. 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).

      -

      Jamie: Let's pause on Method 3: GitHub Desktop. What should a learner take away from it?

      -

      Alex: Start with Method 3: GitHub Desktop. There is something to understand, something to try, and something that proves the try worked.

      -

      Alex: First, open GitHub Desktop. Then, select Repository → Pull to get your fork's latest. After that, select Branch → Merge into Current Branch. Finally, choose upstream/main. The rhythm is simple: orient, act, verify, then continue.

      -

      Jamie: Before we leave Method 3: GitHub Desktop, what is the practical point?

      -

      Alex: First, push the changes to your fork on GitHub. Think of it as a rail line: each stop confirms you are still on the right route before the next one.

      -

      Alex: Keep the teaching thread moving. Start with Learning Cards: Keeping Your Fork Up to Date. There is something to understand, something to try, and something that proves the try worked.

      -

      Alex: The practical takeaway is this. 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. 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.

      +

      Alex: Keep the teaching thread moving. Here is the plain-English version of 13. Inline Code and Code Blocks. Code formatting is essential on GitHub. Put another way, the learner will use it for command-line instructions, file names, configuration values, keyboard shortcuts, and actual source code.

      +

      Jamie: Let's pause on Inline code. What should a learner take away from it?

      +

      Alex: This is where Inline code becomes real: wrap text in single backticks ( `) to format it as code within a sentence. That matters in practice: Run git status to see which files have changed.

      +

      Alex: The practical takeaway is this. Command names: git clone, npm install. File names: README.md, CONTRIBUTING.md. Keyboard shortcuts: Ctrl+C, Alt+Tab. Variable or function names: userName, getElementById().

      +

      Alex: Treat examples as spoken recipes, not decorations. You may hear something like Run git status to see which files have changed.; The configuration file is package.json.; Press Ctrl+Shift+P to open the Command Palette. Read the command, understand what it changes, then run it only when the repository state matches the lesson.

      +

      Alex: Keep the teaching thread moving. Keep the learner anchored in Code blocks (fenced). For multi-line code, wrap it in triple backticks ( ` ) on their own lines. This is the part to say slowly: All formatting is preserved exactly. A good GitHub workflow is like a well-run meeting: everyone knows the topic, the next action, and who has the floor.

      -

      Jamie: Let's pause on Writing Good Commit Messages. What should a learner take away from it?

      -

      Alex: Here is the plain-English version of Writing Good Commit Messages. Every commit you make includes a message describing what changed. Put another way, good commit messages make project history understandable months or years later.

      -

      Alex: Keep the teaching thread moving. This is where The First Line (Required) becomes real: this is the commit summary that appears in logs and GitHub's commit list. That matters in practice: Think of it as an email subject line. The workshop is closer to rehearsal than lecture. You hear the move, try the move, and then check what changed.

      -

      Alex: The practical takeaway is this. fix: - bug fix. feat: - new feature. docs: - documentation only. style: - formatting, no code change.

      -

      Jamie: What is the safe way to learn from that example?

      -

      Alex: Keep the learner anchored in The Body (Optional). If the summary isn't enough, add a body explaining. This is the part to say slowly: Leave a blank line between the summary and the body.

      -

      Alex: The practical takeaway is this. Why you made the change (more important than what). What trade-offs you considered. How the change affects behavior.

      -

      Alex: Treat examples as spoken recipes, not decorations. You may hear something like 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. Read the command, understand what it changes, then run it only when the repository state matches the lesson.

      +

      Jamie: Let's pause on Code blocks with syntax highlighting. What should a learner take away from it?

      +

      Alex: The reason Code blocks with syntax highlighting matters is that add a language identifier right after the opening triple backticks to enable syntax highlighting. That gives the learner a simple foothold: def greet(name: str) - str: """Return a greeting for the given name.""" return f"Hello, {name}!

      +

      Alex: Keep the teaching thread moving. Start with Showing diffs in code blocks: The diff language identifier highlights additions and removals. The next useful detail is this: + new line that was added unchanged context line.

      +

      Alex: The practical takeaway is this. old line that was removed.

      +

      Jamie: Let's pause on Code blocks inside list items. What should a learner take away from it?

      +

      Alex: Here is the plain-English version of Code blocks inside list items. Indent the code block to align with the list item text.

      -

      Alex: Keep the teaching thread moving. The reason The Footer (Optional) matters is that when the commit is merged, GitHub automatically closes linked issues.

      -

      Jamie: Let's pause on Atomic Commits. What should a learner take away from it?

      -

      Alex: Start with Atomic Commits: Each commit should represent one logical change. The next useful detail is this: Don't bundle unrelated fixes into a single commit.

      -

      Alex: Keep the teaching thread moving. Start with Common mistakes to avoid. There is something to understand, something to try, and something that proves the try worked.

      -

      Alex: The practical takeaway is this. "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.

      +

      Alex: Keep the teaching thread moving. This is where How to show literal backticks becomes real: if your code contains backticks, use more backticks for the fence. That matters in practice: Use four backticks to wrap content that contains triple backticks. The workshop is closer to rehearsal than lecture. You hear the move, try the move, and then check what changed.

      +

      Jamie: Let's pause on 14. Horizontal Rules. What should a learner take away from it?

      +

      Alex: Keep the learner anchored in 14. Horizontal Rules. A horizontal rule creates a thematic break between sections - a visual line across the page. This is the part to say slowly: Use three or more dashes, asterisks, or underscores on a line by themselves.

      +

      Alex: Keep the teaching thread moving. The reason 15. Escaping Special Characters matters is that many characters have special meaning in Markdown. That gives the learner a simple foothold: if you want to display them as literal characters instead, put a backslash () before them.

      -

      Jamie: How do you keep commands from becoming magic words?

      -

      Alex: This is where Good commit messages in practice becomes real: when you make a habit of writing good commit messages, you build trust. That matters in practice: Maintainers see that you care about the project's long-term health, not just your immediate contribution.

      -

      Alex: Treat examples as spoken recipes, not decorations. You may hear something like 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. Read the command, understand what it changes, then run it only when the repository state matches the lesson.

      -

      Alex: Keep the teaching thread moving. Start with Learning Cards: Writing Good Commit Messages. There is something to understand, something to try, and something that proves the try worked.

      -

      Alex: The practical takeaway is this. 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. 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.

      -

      Jamie: Let's pause on The Nature of Open Source Communication. What should a learner take away from it?

      -

      Alex: The reason The Nature of Open Source Communication matters is that open source collaboration happens primarily in writing, asynchronously, in public. That gives the learner a simple foothold: understanding these three characteristics shapes everything about how we communicate.

      +

      Jamie: Let's pause on Characters that can be escaped. What should a learner take away from it?

      +

      Alex: Start with Characters that can be escaped: The following table lists every character that can be escaped in Markdown.

      +

      Alex: Keep the teaching thread moving. Here is the plain-English version of Examples. This asterisk is literal: \ not bold\ This hash is literal: \ not a heading Show a pipe character: . It is like learning a transit route. The names of the stops matter because they tell you whether you are still going the right direction.

      +

      Jamie: Let's pause on 16. Tables. What should a learner take away from it?

      +

      Alex: This is where 16. Tables becomes real: tables organize data into rows and columns. That matters in practice: They are used extensively on GitHub for comparison charts, reference data, settings documentation, and checklists.

      -

      Alex: Keep the teaching thread moving. Start with In writing. There is something to understand, something to try, and something that proves the try worked.

      -

      Alex: The practical takeaway is this. 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.".

      -

      Jamie: Let's pause on Asynchronously. What should a learner take away from it?

      -

      Alex: Start with Asynchronously. There is something to understand, something to try, and something that proves the try worked.

      -

      Alex: The practical takeaway is this. 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.

      -

      Alex: Keep the teaching thread moving. Start with In public. There is something to understand, something to try, and something that proves the try worked.

      -

      Alex: The practical takeaway is this. 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.

      +

      Jamie: Let's pause on Basic table syntax. What should a learner take away from it?

      +

      Alex: Start with Basic table syntax. There is something to understand, something to try, and something that proves the try worked.

      +

      Alex: Treat examples as spoken recipes, not decorations. You may hear something like Name Role Platform; --- --- ---; NVDA Screen reader Windows; JAWS Screen reader Windows; VoiceOver Screen reader macOS / iOS; TalkBack Screen reader Android. Read the command, understand what it changes, then run it only when the repository state matches the lesson.

      +

      Jamie: Let's pause on How table syntax works. What should a learner take away from it?

      +

      Alex: Start with How table syntax works. There is something to understand, something to try, and something that proves the try worked.

      +

      Alex: The practical takeaway is this. The first row is always the header row. The second row contains dashes (---) that separate the header from the data. You need at least three dashes per column. Each subsequent row is a data row. Columns are separated by pipe characters ( ). Leading and trailing pipes are optional but recommended for readability.

      +

      Alex: Keep the teaching thread moving. Start with Column alignment: Add colons (:) to the separator row to control text alignment. Think of it like entering a new building: first you find the lobby, then the room, then the door you actually need.

      +

      Alex: The practical takeaway is this.:--- = left aligned (default).:---: = center aligned. ---: = right aligned.

      -

      Jamie: What do you want them to do when the plan breaks?

      -

      Alex: Keep the learner anchored in The Anatomy of Helpful Feedback. Whether commenting on an issue, reviewing a PR, or responding to a question, effective feedback has a structure.

      -

      Alex: Keep the teaching thread moving. The reason 1. Acknowledge what's working matters is that before identifying problems, name what is good. That gives the learner a simple foothold: this is not flattery - it is accuracy. The interface gets friendlier when it stops being a wall of controls and starts being a set of named places.

      -

      Jamie: Let's pause on 2. Identify the specific concern. What should a learner take away from it?

      -

      Alex: Start with 2. Identify the specific concern: "This code is inaccessible." "This button has no accessible name - aria-label or visible text is needed for screen readers to announce its purpose.".

      +

      Jamie: Let's pause on Formatting inside table cells. What should a learner take away from it?

      +

      Alex: Here is the plain-English version of Formatting inside table cells. You can use inline formatting within table cells.

      +

      Jamie: Let's pause on Accessibility considerations for tables. What should a learner take away from it?

      +

      Alex: This is where Accessibility considerations for tables becomes real: screen readers navigate tables with Ctrl+Alt+Arrow keys (NVDA and JAWS). That matters in practice: Ctrl+Alt+Right moves to the next column.

      +

      Alex: First, always include a description before the table. Add a one-sentence summary immediately above the table explaining what it contains. Screen reader users hear the table structure (rows and columns) but benefit from knowing what the table is about before entering. Then, keep tables simple. Tables with more than 5-6 columns become difficult to navigate with a screen reader. Consider splitting wide tables into multiple narrower tables. After that, use tables for data, not layout. If you are using a table just to arrange content side by side, use a list instead. Finally, make the header row descriptive. The header cell is announced before each data cell when navigating by column, so "Platform" is better than "Col 3". It is a checklist, but a meaningful one: every item creates evidence that the next step is safe.

      +

      Jamie: Let's pause on When not to use a table. What should a learner take away from it?

      +

      Alex: Keep the learner anchored in When not to use a table. If your "table" has only two columns where the first is a label and the second is a value, consider using a definition-style list or bold labels instead. This is the part to say slowly: This is often easier to read with a screen reader than a two-column table.

      -

      Alex: Keep the teaching thread moving. Here is the plain-English version of 3. Explain why it matters. Context turns a complaint into a lesson. Put another way, it also respects the contributor - they deserve to understand, not just comply.

      -

      Jamie: Let's pause on 4. Suggest a path forward (when you can). What should a learner take away from it?

      -

      Alex: This is where 4. Suggest a path forward (when you can) becomes real: if you have an idea for a solution, offer it as a suggestion, not a mandate. That matters in practice: "Something like aria-label='Close navigation menu' would work well here.

      -

      Alex: Keep the teaching thread moving. Keep the learner anchored in 5. Signal the weight of the concern. Help contributors understand what is a blocker versus a preference. A good GitHub workflow is like a well-run meeting: everyone knows the topic, the next action, and who has the floor.

      -

      Alex: The practical takeaway is this. 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.

      +

      Alex: Keep the teaching thread moving. Start with Learning Cards: Tables. There is something to understand, something to try, and something that proves the try worked.

      +

      Alex: The practical takeaway is this. Navigate tables with Ctrl+Alt+Arrow keys (NVDA/JAWS) -- Right moves to the next column, Down to the next row; the column header is announced each time you change columns. Enter table mode automatically when your screen reader encounters a table -- press T in browse mode to jump to the next table on the page. Before the table structure, listen for the description sentence the author should place above it -- this tells you what data the table contains before you enter cell-by-cell navigation. Wide tables (6+ columns) may require horizontal scrolling at high zoom -- if the table overflows, scroll right to see truncated columns or view the raw Markdown source instead. Column alignment (left, center, right) is controlled by colons in the separator row -- at high magnification, right-aligned numbers are easier to compare than left-aligned ones. If a table is hard to read at your zoom level, try narrowing the browser window -- GitHub will sometimes reflow content or add a horizontal scrollbar.

      +

      Jamie: Let's pause on Learning Cards: GitHub Flavored Markdown. What should a learner take away from it?

      +

      Alex: Start with Learning Cards: GitHub Flavored Markdown. There is something to understand, something to try, and something that proves the try worked.

      +

      Alex: The practical takeaway is this. GFM features (sections 17-27) work only on GitHub -- your screen reader behavior notes are in each section. Alert blocks (section 18) render as blockquotes with a type prefix -- listen for "Note," "Warning," etc. Task list checkboxes (section 20) are announced as "checkbox checked" or "checkbox not checked". Alert blocks use color-coded left borders (blue for Note, yellow for Warning, red for Caution) -- the text label also identifies the type. Mermaid diagrams (section 22) are visual only on GitHub -- the raw code block is always readable. Use GitHub's Preview tab when writing to confirm your GFM renders correctly before submitting.

      +

      Alex: Keep the teaching thread moving. Here is the plain-English version of 17. What Is GitHub Flavored Markdown? GitHub Flavored Markdown (GFM) is GitHub's own superset of standard Markdown. Put another way, it takes everything from the CommonMark specification (the modern standard for Markdown) and adds features specifically designed for software collaboration: tables, task lists, strikethrough, autolinked references, alert blocks, Mermaid diagrams, math.

      -

      Jamie: Let's pause on Prefer "we" or describe the code, not the person. What should a learner take away from it?

      -

      Alex: The reason Prefer "we" or describe the code, not the person matters is that "You made an error here." "There's an error here." or "This line does X but we need Y.".

      -

      Alex: Keep the teaching thread moving. Start with 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?".

      -

      Jamie: Let's pause on Acknowledge cultural and language diversity. What should a learner take away from it?

      -

      Alex: Here is the plain-English version of Acknowledge cultural and language diversity. When reading someone's comment: Assume good intent unless there is clear evidence otherwise. Put another way, when writing: Choose plain words over clever ones.

      -

      Alex: The practical takeaway is this. 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.

      +

      Jamie: Let's pause on Where GFM works. What should a learner take away from it?

      +

      Alex: This is where Where GFM works becomes real: the following table shows where GFM is supported.

      +

      Alex: Keep the teaching thread moving. Keep the learner anchored in 18. Alert and Callout Blocks. GitHub introduced alert blocks in 2023. This is the part to say slowly: They render as colored, bordered callout boxes - great for emphasizing warnings, tips, or critical information. A good GitHub workflow is like a well-run meeting: everyone knows the topic, the next action, and who has the floor.

      +

      Jamie: Let's pause on How to write them. What should a learner take away from it?

      +

      Alex: Start with How to write them. There is something to understand, something to try, and something that proves the try worked.

      +

      Alex: First, start a blockquote. Then, the first line must be exactly [!TYPE] where TYPE is one of: NOTE, TIP, IMPORTANT, WARNING, CAUTION. After that, all subsequent lines start with and a space, just like a regular blockquote. Finally, you can include any Markdown inside the alert: lists, code, links, bold. The rhythm is simple: orient, act, verify, then continue.

      -

      Alex: Keep the teaching thread moving. This is where Avoid urgency markers unless genuinely urgent becomes real: "I need this fixed ASAP" "This is blocking our release scheduled for next Friday - is there capacity to look at it this week?". The workshop is closer to rehearsal than lecture. You hear the move, try the move, and then check what changed.

      -

      Jamie: Let's pause on Keep comments focused. What should a learner take away from it?

      -

      Alex: Keep the learner anchored in Keep comments focused. Each comment should address one concern. This is the part to say slowly: If you have three issues, leave three comments - unless they are closely related.

      -

      Alex: Keep the teaching thread moving. The reason Don't leave comments unresolved matters is that if you asked a question and got an answer, respond. That gives the learner a simple foothold: "Thanks, that makes sense" or resolving the conversation thread signals that the thread is complete.

      +

      Alex: Keep the teaching thread moving. Start with Choosing the right alert type: The following table describes each alert type and when to use it.

      +

      Jamie: Let's pause on Screen Reader Behavior. What should a learner take away from it?

      +

      Alex: Here is the plain-English version of Screen Reader Behavior. Alert blocks render as elements with an SVG icon and a strong heading.

      +

      Alex: The practical takeaway is this. NVDA/JAWS: announces blockquote role, then reads the type label ("Note", "Warning") then the content. VoiceOver: reads the type as bold text then the content. The colored icon is decorative (aria-hidden); it does not add information beyond the type label.

      +

      Alex: Keep the teaching thread moving. This is where 19. Collapsible Sections with Details and Summary becomes real: the and HTML elements create collapsible sections. That matters in practice: They are one of the most useful tools for keeping long documents, issue reports, and PRs manageable - hiding optional content until the reader chooses to expand it. The workshop is closer to rehearsal than lecture. You hear the move, try the move, and then check what changed.

      -

      Jamie: Let's pause on Resolving conversations. What should a learner take away from it?

      -

      Alex: Start with Resolving conversations: On a PR, conversations (inline comment threads) can be "resolved" once addressed. The next useful detail is this: The author of the change and the reviewer can both resolve them.

      -

      Alex: Keep the teaching thread moving. Here is the plain-English version of 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. Put another way, a reaction on an existing comment is enough. It is like learning a transit route. The names of the stops matter because they tell you whether you are still going the right direction.

      -

      Jamie: Let's pause on Reactions. What should a learner take away from it?

      -

      Alex: This is where Reactions becomes real: GitHub reactions () are an efficient way to express agreement, appreciation, or concern without adding noise to a thread.

      +

      Jamie: Let's pause on Important formatting rules. What should a learner take away from it?

      +

      Alex: Start with Important formatting rules. There is something to understand, something to try, and something that proves the try worked.

      +

      Alex: First, blank line after. Put a blank line between the closing tag and your Markdown content. Without it, Markdown formatting inside may not render. Then, blank line before. Same principle at the end. After that, the text should be descriptive - it is the only thing visible when collapsed. It is like walking a hallway with named doors: read the sign, enter the right room, then confirm where you landed.

      +

      Alex: Keep the teaching thread moving. The reason Real-world uses in this workshop matters is that the following list describes common uses for collapsible sections.

      +

      Alex: The practical takeaway is this. Bug reports in issues: Collapse the full stack trace so the issue body stays readable. Long configuration blocks: Let readers expand the full YAML only if they need it. Exercise solutions: Collapse the answer so learners try the exercise first. Screen reader guidance blocks: Throughout this course, some sections collapse detailed assistive technology instructions so sighted users see a cleaner page while screen reader users can easily expand them. Meeting notes: Collapse detailed minutes while showing the summary.

      +

      Jamie: Let's pause on Details sections that start open. What should a learner take away from it?

      +

      Alex: Start with Details sections that start open: Add the open attribute to have the section expanded by default.

      +

      Alex: Treat examples as spoken recipes, not decorations. You may hear something like; Currently known issues; - Checkbox toggle requires Focus Mode in NVDA; - Alert blocks do not render in email notifications. Read the command, understand what it changes, then run it only when the repository state matches the lesson.

      -

      Alex: Keep the teaching thread moving. Keep the learner anchored in 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 the part to say slowly: This is a significant accessibility win for anyone who types the same comments repeatedly during triage, reviews, or issue management.

      -

      Jamie: Let's pause on Common uses. What should a learner take away from it?

      -

      Alex: Start with Common uses. There is something to understand, something to try, and something that proves the try worked.

      -

      Alex: The practical takeaway is this. "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.

      -

      Jamie: Let's pause on Creating a Saved Reply. What should a learner take away from it?

      -

      Alex: Start with Creating a Saved Reply. There is something to understand, something to try, and something that proves the try worked.

      -

      Alex: First, navigate to github.com/settings/replies. Then, activate "Add a saved reply". After that, give it a title (e.g., "Good first issue claim") - this is what you search. Finally, type the full reply text in the body (Markdown is supported). Think of it as a rail line: each stop confirms you are still on the right route before the next one.

      +

      Alex: Keep the teaching thread moving. Here is the plain-English version of Screen Reader Behavior. The element renders as a disclosure widget. Put another way, after expanding: The content is immediately readable. It is like learning a transit route. The names of the stops matter because they tell you whether you are still going the right direction.

      +

      Alex: The practical takeaway is this. NVDA: announces "button collapsed" for the - press Enter or Space to expand. JAWS: announces "collapsed" - press Enter on the summary to expand. VoiceOver: announces "collapsed, button" - press VO+Space to activate.

      +

      Jamie: Let's pause on Learning Cards: Collapsible Sections. What should a learner take away from it?

      +

      Alex: Start with Learning Cards: Collapsible Sections. There is something to understand, something to try, and something that proves the try worked.

      +

      Alex: The practical takeaway is this. The element is announced as a button -- press Enter or Space to toggle between collapsed and expanded; listen for "collapsed" or "expanded" state announcements. After expanding, the content is immediately available -- arrow down to read it; no page reload or focus change occurs. Nested blocks (details inside details) work but add complexity -- each level is an independent toggle button; keep nesting to one level deep for predictable navigation. The summary text is the only visible element when collapsed -- it appears as a disclosure triangle ( ) with text; zoom in to ensure the triangle and text are both readable. Expanded content appears inline below the summary -- at high zoom it flows naturally with the rest of the page content. The open attribute forces a section to start expanded -- useful when the content is important enough that most readers should see it by default.

      +

      Alex: Keep the teaching thread moving. Keep the learner anchored in 20. Task List Checkboxes. Task lists in GitHub issues and PRs render as real interactive checkboxes. This is the part to say slowly: Anyone with write access to the repository can check and uncheck them directly in the rendered view without editing the Markdown.

      -

      Jamie: Let's pause on Using a Saved Reply in a comment. What should a learner take away from it?

      -

      Alex: Start with Using a Saved Reply in a comment. There is something to understand, something to try, and something that proves the try worked.

      -

      Alex: First, navigate to any comment text area. Then, activate the Saved Replies button (the speech bubble icon in the comment toolbar, or press Ctrl+. if enabled). After that, a dropdown appears showing your saved replies - type to filter by title. Finally, select the reply - it inserts into the text area. Treat it like a recipe: do not add the next ingredient until the previous one is actually in the bowl.

      -

      Jamie: Before we leave Using a Saved Reply in a comment, what is the practical point?

      -

      Alex: First, edit as needed before submitting. It is a checklist, but a meaningful one: every item creates evidence that the next step is safe.

      -

      Alex: Keep the teaching thread moving. This is where Screen reader path becomes real: limit: GitHub allows up to 100 saved replies per account.

      -

      Alex: A solid navigation habit is to prove where you are before activating controls. Headings, landmarks, and the address bar are not trivia; they are your map.

      -

      Jamie: Let's pause on Learning Cards: Commenting Etiquette. What should a learner take away from it?

      -

      Alex: Start with Learning Cards: Commenting Etiquette. There is something to understand, something to try, and something that proves the try worked.

      -

      Alex: The practical takeaway is this. 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. 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.

      +

      Jamie: Let's pause on Syntax. What should a learner take away from it?

      +

      Alex: Start with Syntax. There is something to understand, something to try, and something that proves the try worked.

      +

      Alex: Treat examples as spoken recipes, not decorations. You may hear something like [x] Color contrast verified (4.5:1 minimum for body text); - [x] Keyboard navigation tested; - [ ] Screen reader tested with NVDA; - [ ] Screen reader tested with JAWS; - [ ] Screen reader tested with VoiceOver; - [ ] Alt text provided for all images; - [ ]. Read the command, understand what it changes, then run it only when the repository state matches the lesson.

      +

      Jamie: Before we leave How to write them, what is the practical point?

      +

      Alex: First, start with a list item marker (-,, or +) and a space. Then, add [x] for a checked box or [ ] (with a space inside) for an unchecked box. After that, add a space, then the task description. Finally, the description should be meaningful - "Test NVDA" is better than "Item 3". Think of it as a rail line: each stop confirms you are still on the right route before the next one.

      +

      Jamie: Let's pause on What makes task lists special on GitHub. What should a learner take away from it?

      +

      Alex: Start with What makes task lists special on GitHub. There is something to understand, something to try, and something that proves the try worked.

      +

      Alex: The practical takeaway is this. Progress tracking: In issues, GitHub shows a progress bar: "2 of 7 tasks completed". Click to check: In the rendered view, users with triage or write permissions can click to toggle checkboxes without editing the comment. Linked issues: You can reference issues in a task: - [ ] Fix 42 - the task shows the issue title and its open/closed state. PR templates: Task lists in PR templates create checklists that authors fill out before requesting review.

      -

      Alex: Keep the teaching thread moving. The reason Review the code, not the person matters is that "You clearly don't understand accessibility." "This implementation doesn't account for keyboard navigation - here's how to add it.". The interface gets friendlier when it stops being a wall of controls and starts being a set of named places.

      -

      Jamie: Let's pause on Don't gatekeep knowledge. What should a learner take away from it?

      -

      Alex: Start with Don't gatekeep knowledge: If a contributor makes a mistake because they didn't know something, explain the concept.

      -

      Alex: Keep the teaching thread moving. Here is the plain-English version of Ask questions instead of making demands. "Change this to use aria-label." "What do you think about using aria-label here instead? Put another way, screen readers would then announce the button's purpose directly.".

      +

      Jamie: Let's pause on Example - pull request checklist. What should a learner take away from it?

      +

      Alex: Start with Example - pull request checklist. There is something to understand, something to try, and something that proves the try worked.

      +

      Alex: Treat examples as spoken recipes, not decorations. You may hear something like Pre-review checklist; - [x] Changes are limited to the files listed in the issue; - [x] All new images have descriptive alt text; - [ ] Screen reader tested the changes with NVDA; - [ ] No heading levels are skipped; - [ ] All links use descriptive text (not. Read the command, understand what it changes, then run it only when the repository state matches the lesson.

      +

      Jamie: Let's pause on Screen Reader Interaction. What should a learner take away from it?

      +

      Alex: Keep the learner anchored in Screen Reader Interaction. In Browse Mode, checkboxes are read as checkbox, not checked or checkbox, checked.

      +

      Alex: The practical takeaway is this. NVDA: Press NVDA+Space to enter Focus Mode, then Tab to find the checkbox, then Space to toggle it. JAWS: Tab to the checkbox, then Space to toggle. VoiceOver: VO+Space on the checkbox element.

      +

      Alex: Keep the teaching thread moving. The reason 21. Syntax Highlighting in Fenced Code Blocks matters is that we covered basic code blocks in Section 13. That gives the learner a simple foothold: this section covers the GitHub-specific syntax highlighting that makes code blocks more readable for sighted users. The interface gets friendlier when it stops being a wall of controls and starts being a set of named places.

      -

      Jamie: Let's pause on Distinguish opinion from requirement. What should a learner take away from it?

      -

      Alex: This is where Distinguish opinion from requirement becomes real: if something is your stylistic preference but NOT a bug or correctness issue, say so. That matters in practice: "The current implementation is correct.

      -

      Alex: Keep the teaching thread moving. Keep the learner anchored in 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! A good GitHub workflow is like a well-run meeting: everyone knows the topic, the next action, and who has the floor.

      -

      Jamie: Let's pause on Say thank you. What should a learner take away from it?

      -

      Alex: The reason Say thank you matters is that when someone takes time to review your work, acknowledge it - even if you disagree with some feedback. That gives the learner a simple foothold: "Thanks so much for the thorough review!

      +

      Jamie: Let's pause on How it works. What should a learner take away from it?

      +

      Alex: Start with How it works: Add a language identifier right after the opening triple backticks. The next useful detail is this: GitHub uses Linguist to apply syntax highlighting with appropriate colors for keywords, strings, comments, and other language constructs.

      +

      Alex: Keep the teaching thread moving. Here is the plain-English version of Complete list of commonly used language identifiers. The following table lists the language identifiers you are most likely to use. Put another way, if no language is specified, the code block renders as plain monospaced text with no highlighting.

      +

      Jamie: Let's pause on Screen Reader Note. What should a learner take away from it?

      +

      Alex: This is where Screen Reader Note becomes real: syntax highlighting is visual only - screen readers read the code text without announcing color changes. That matters in practice: The code block itself is announced as a code region.

      -

      Alex: Keep the teaching thread moving. Start with Don't take feedback personally: Code review is about the code, not your worth as a person or developer. The next useful detail is this: Even the most senior contributors receive change requests.

      -

      Jamie: Let's pause on Explain your choices. What should a learner take away from it?

      -

      Alex: Here is the plain-English version of Explain your choices. If you are keeping your implementation despite feedback, explain why. Put another way, "I considered aria-label here, but I went with a visually-hidden instead because it allows translators to localize the text more easily.

      -

      Alex: Keep the teaching thread moving. This is where Surface blockers early becomes real: don't wait until you have finished a 500-line PR to mention that you weren't sure about the approach. The workshop is closer to rehearsal than lecture. You hear the move, try the move, and then check what changed.

      +

      Alex: Keep the teaching thread moving. Keep the learner anchored in 22. Mermaid Diagrams. GitHub renders Mermaid.js diagrams inline when you use a mermaid fenced code block. This is the part to say slowly: They are common in READMEs, PRs, and documentation to illustrate architecture, flows, and relationships. A good GitHub workflow is like a well-run meeting: everyone knows the topic, the next action, and who has the floor.

      +

      Jamie: Before we leave Syntax, what is the practical point?

      +

      Alex: The reason Syntax matters is that flowchart LR A[Fork repo] -- B[Clone locally] B -- C[Create branch] C -- D[Make changes] D -- E[Push branch] E -- F[Open PR] F -- G{Review passed?} G -- Yes -- H[Merge] G -- No -- D.

      +

      Alex: Keep the teaching thread moving. Start with Common diagram types: The following table lists the Mermaid diagram types you are most likely to encounter on GitHub.

      -

      Jamie: Let's pause on Inclusive Commenting for Accessibility Issues. What should a learner take away from it?

      -

      Alex: Keep the learner anchored in Inclusive Commenting for Accessibility Issues. When filing or discussing accessibility bugs, additional context helps.

      -

      Alex: The practical takeaway is this. 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.

      -

      Alex: A solid issue habit is to read the title, the body, and the timeline before acting. You are listening for the requested action, the missing evidence, and the person who needs a response.

      -

      Jamie: Let's pause on The "Good First Issue" Social Contract. What should a learner take away from it?

      -

      Alex: The reason The "Good First Issue" Social Contract matters is that when a maintainer labels an issue good first issue, they are. That gives the learner a simple foothold: when you take a good first issue, your responsibilities.

      -

      Alex: The practical takeaway is this. Investing time - good first issues require extra documentation and mentorship. Signaling welcome - they want to support a new contributor.

      -

      Alex: First, comment to claim it - "Hi, I'd like to work on this. Can I be assigned?". Then, wait for assignment - do not start until assigned; two people working in parallel wastes everyone's time. After that, 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?". Finally, 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?". The rhythm is simple: orient, act, verify, then continue.

      -

      Jamie: Before we leave The "Good First Issue" Social Contract, what is the practical point?

      -

      Alex: First, don't disappear - if you claim an issue, see it through or explicitly hand it back. Think of it as a rail line: each stop confirms you are still on the right route before the next one.

      -

      Jamie: Let's pause on When you receive harsh feedback. What should a learner take away from it?

      -

      Alex: Start with When you receive harsh feedback. There is something to understand, something to try, and something that proves the try worked.

      -

      Alex: First, take a breath before responding - there is no urgency; the thread will wait. Then, look for the valid concern underneath the harsh words. After that, respond to the concern, not the tone. Finally, if the behavior crosses into harassment, report it via the "." button on the comment → "Report". Think of it as a rail line: each stop confirms you are still on the right route before the next one.

      +

      Jamie: Let's pause on Accessibility limitation - critical. What should a learner take away from it?

      +

      Alex: Here is the plain-English version of Accessibility limitation - critical. Mermaid diagrams render as SVG images. Put another way, GitHub does not auto-generate alt text for them.

      +

      Jamie: Let's pause on How to make Mermaid diagrams accessible. What should a learner take away from it?

      +

      Alex: This is where How to make Mermaid diagrams accessible becomes real: example - accessible Mermaid usage. That matters in practice: flowchart LR Fork -- Clone -- Branch -- Commit -- Push -- PR -- Review -- Merge. The workshop is closer to rehearsal than lecture. You hear the move, try the move, and then check what changed.

      +

      Alex: First, write a text description before the diagram that conveys all the same information. Then, optionally, duplicate the information as a numbered list or table. After that, consider wrapping the Mermaid source in a block if the text description is sufficient. It is a checklist, but a meaningful one: every item creates evidence that the next step is safe.

      +

      Jamie: Let's pause on 23. Math Expressions with LaTeX. What should a learner take away from it?

      +

      Alex: Keep the learner anchored in 23. Math Expressions with LaTeX. GitHub renders LaTeX math expressions using MathJax. This is the part to say slowly: This is common in data science, research, and algorithm documentation.

      -

      Jamie: Let's pause on When you disagree with a decision. What should a learner take away from it?

      -

      Alex: Start with When you disagree with a decision. There is something to understand, something to try, and something that proves the try worked.

      -

      Alex: First, make your case once, clearly and with evidence. Then, accept that the maintainer has the final say in their project. After that, if you strongly disagree, you can fork the project and take it in a different direction - this is legitimate in open source. Treat it like a recipe: do not add the next ingredient until the previous one is actually in the bowl.

      -

      Jamie: Let's pause on When someone is rude to you. What should a learner take away from it?

      -

      Alex: Start with When someone is rude to you. There is something to understand, something to try, and something that proves the try worked.

      -

      Alex: First, you do not have to engage. Then, 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.". After that, report via GitHub's reporting tools if the behavior is abusive. It is a checklist, but a meaningful one: every item creates evidence that the next step is safe.

      -

      Jamie: Let's pause on When you accidentally caused offense. What should a learner take away from it?

      -

      Alex: Start with When you accidentally caused offense. There is something to understand, something to try, and something that proves the try worked.

      -

      Alex: First, acknowledge it directly: "I can see how that came across as dismissive - that wasn't my intention.". Then, do not over-explain or defend excessively. After that, adjust going forward. It is like walking a hallway with named doors: read the sign, enter the right room, then confirm where you landed.

      +

      Alex: Keep the teaching thread moving. The reason Inline math matters is that use single $ delimiters for math within a sentence. That gives the learner a simple foothold: renders as: The formula is $e = mc^2$ where $c$ is the speed of light.

      +

      Jamie: Let's pause on Block math. What should a learner take away from it?

      +

      Alex: Start with Block math: Use $$ delimiters for display-style (centered, larger) math on their own lines.

      +

      Alex: Keep the teaching thread moving. Here is the plain-English version of Common LaTeX patterns. The following table shows some LaTeX patterns you might encounter. It is like learning a transit route. The names of the stops matter because they tell you whether you are still going the right direction.

      -

      Jamie: Let's pause on Writing Your First README. What should a learner take away from it?

      -

      Alex: The reason Writing Your First README matters is that see also: Appendix W: GitHub Pages for publishing your README as a website. That gives the learner a simple foothold: a README is the front door of your project.

      -

      Alex: Keep the teaching thread moving. Start with What belongs in a README: Every README should answer these questions, roughly in this order. The next useful detail is this: 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. Think of it like entering a new building: first you find the lobby, then the room, then the door you actually need.

      -

      Jamie: Let's pause on Accessibility in READMEs. What should a learner take away from it?

      -

      Alex: Here is the plain-English version of Accessibility in READMEs. Your README is a web page -- GitHub renders it as HTML. Put another way, that means the same accessibility rules apply.

      -

      Alex: The practical takeaway is this. Alt text for images and badges. A badge that says is invisible to screen readers. Write 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 -- not Click here.

      +

      Jamie: Before we leave Screen Reader Note, what is the practical point?

      +

      Alex: This is where Screen Reader Note becomes real: math expressions rendered by MathJax include aria-label attributes with the spoken form of the equation. That matters in practice: Screen readers should announce the math correctly, but accuracy varies.

      +

      Alex: The practical takeaway is this. NVDA with Firefox or Chrome: reads MathML fairly well. JAWS: reads the aria-label text. VoiceOver: reads the aria-label text.

      +

      Alex: Keep the teaching thread moving. Keep the learner anchored in 24. Footnotes. GitHub supports Markdown footnotes, which render as superscript numbers that link to references at the bottom of the document. This is the part to say slowly: They are useful for citations, additional context, and references that would interrupt the flow of the main text.

      +

      Jamie: Let's pause on How they work. What should a learner take away from it?

      +

      Alex: Start with How they work. There is something to understand, something to try, and something that proves the try worked.

      +

      Alex: First, in your text, add [^identifier] where you want the footnote reference to appear. Then, anywhere in the document (typically at the bottom), define the footnote with [^identifier]: Your footnote text. After that, GitHub renders the reference as a superscript number that links to the definition. Finally, the definition includes a back-link that returns to the reference location. The rhythm is simple: orient, act, verify, then continue.

      -

      Alex: Keep the teaching thread moving. This is where Good README vs. bad README becomes real: bad: A single paragraph that says "This is my project. That matters in practice: Run it with npm start." No headings, no license, no description of what the project does.

      -

      Jamie: Let's pause on Learning Cards: Writing Your First README. What should a learner take away from it?

      -

      Alex: Start with Learning Cards: Writing Your First README. There is something to understand, something to try, and something that proves the try worked.

      -

      Alex: The practical takeaway is this. 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: rather than an empty that reads as "image" with no context. Use real Markdown link text (installation guide) instead of bare URLs, so your screen reader announces the destination rather than spelling out a long URL. 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.

      -

      Alex: Keep the teaching thread moving. The reason Community Health Files matters is that community health files tell contributors how your project operates before they write a single line of code. That gives the learner a simple foothold: 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. The interface gets friendlier when it stops being a wall of controls and starts being a set of named places.

      +

      Alex: Keep the teaching thread moving. Start with Footnote identifiers. There is something to understand, something to try, and something that proves the try worked.

      +

      Alex: The practical takeaway is this. You can use numbers: [^1], [^2], [^3]. You can use descriptive names: [^webaim-survey], [^wcag-reference]. Descriptive names make the raw Markdown more readable but render as sequential numbers.

      +

      Jamie: Let's pause on Multi-line footnotes. What should a learner take away from it?

      +

      Alex: Here is the plain-English version of Multi-line footnotes. Indent continuation lines with two spaces.

      +

      Alex: Keep the teaching thread moving. Start with Screen Reader Behavior. There is something to understand, something to try, and something that proves the try worked.

      +

      Alex: The practical takeaway is this. The footnote reference is a link ( element) announcing its number. NVDA: "superscript, 1, link". JAWS: "link, 1". VoiceOver: "link, footnote 1". The back-link at the definition reads "return to footnote reference". Activating the footnote link jumps focus to the definition; activating the back-link returns focus to the original location.

      -

      Jamie: Let's pause on CONTRIBUTING.md. What should a learner take away from it?

      -

      Alex: Start with CONTRIBUTING.md: This file answers the question every newcomer asks: "How do I help?" A good CONTRIBUTING.md covers. The next useful detail is this: A sentence like "We are glad you are here" costs nothing and signals that newcomers are expected, not tolerated.

      -

      Alex: The practical takeaway is this. 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.

      -

      Alex: Keep the teaching thread moving. Here is the plain-English version of CODE OF CONDUCT.md. A code of conduct sets the social contract for your project. Put another way, without one, "acceptable behavior" is whatever each participant assumes it is -- and those assumptions vary widely.

      -

      Alex: The practical takeaway is this. 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.

      -

      Jamie: Let's pause on SECURITY.md. What should a learner take away from it?

      -

      Alex: This is where SECURITY.md becomes real: see also: Appendix F: Git Security and Appendix P: Security Features for security best practices. That matters in practice: If someone discovers a vulnerability in your project, you do not want them to file a public issue.

      -

      Alex: The practical takeaway is this. 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.

      +

      Jamie: Let's pause on 25. Linked Heading Anchors and Tables of Contents. What should a learner take away from it?

      +

      Alex: Keep the learner anchored in 25. Linked Heading Anchors and Tables of Contents. Every heading in a GitHub Markdown file automatically gets an anchor ID. This is the part to say slowly: You can link to any heading from anywhere - within the same document, from another file, or from an issue or PR.

      +

      Jamie: Let's pause on How GitHub generates anchor IDs. What should a learner take away from it?

      +

      Alex: The reason How GitHub generates anchor IDs matters is that GitHub converts the heading text to an anchor ID. That gives the learner a simple foothold: the following table shows example headings and their generated anchors. The interface gets friendlier when it stops being a wall of controls and starts being a set of named places.

      +

      Alex: First, converting to lowercase. Then, replacing spaces with hyphens. After that, removing most punctuation (except hyphens). Finally, removing leading and trailing whitespace. The rhythm is simple: orient, act, verify, then continue.

      +

      Jamie: Let's pause on Building a table of contents. What should a learner take away from it?

      +

      Alex: Start with Building a table of contents: You can build a manual table of contents using heading anchor links.

      -

      Alex: Keep the teaching thread moving. Keep the learner anchored in 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. This is the part to say slowly: Adding a LICENSE file is a one-time step that makes your project genuinely open source. A good GitHub workflow is like a well-run meeting: everyone knows the topic, the next action, and who has the floor.

      -

      Jamie: Let's pause on Finding these files on GitHub. What should a learner take away from it?

      -

      Alex: The reason Finding these files on GitHub matters is that navigate to any repository and click Insights then Community Standards. That gives the learner a simple foothold: GitHub shows a checklist of which community health files are present and links to add any that are missing.

      -

      Alex: Keep the teaching thread moving. Start with Learning Cards: Community Health Files. There is something to understand, something to try, and something that proves the try worked.

      -

      Alex: The practical takeaway is this. 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. 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.

      +

      Alex: Keep the teaching thread moving. Here is the plain-English version of Duplicate headings. If a document has two headings with the same text, GitHub appends -1, -2, and so on to the duplicate anchors. Put another way, best practice: Avoid duplicate heading text.

      +

      Jamie: Let's pause on Finding the anchor for any heading. What should a learner take away from it?

      +

      Alex: Start with Finding the anchor for any heading. There is something to understand, something to try, and something that proves the try worked.

      +

      Alex: First, mouse users: On GitHub, hover over any heading - a chain link icon appears to the left. Click it to update the URL with the anchor. Then, screen reader users: Navigate to the heading, then Tab once. A link button appears. Activate it and the URL in the address bar updates to show the anchor. After that, keyboard (GitHub shortcut): There is no direct shortcut, but you can copy the heading text, convert it to the anchor format mentally, and type it in the URL. It is a checklist, but a meaningful one: every item creates evidence that the next step is safe.

      +

      Alex: Keep the teaching thread moving. Keep the learner anchored in 26. Autolinked References - Issues, PRs, Commits, and Users. One of GitHub's most powerful features is automatic linking. This is the part to say slowly: When you type certain patterns in any Markdown field on GitHub, they automatically become clickable links. A good GitHub workflow is like a well-run meeting: everyone knows the topic, the next action, and who has the floor.

      -

      Jamie: How should someone choose between those options?

      -

      Alex: Here is the plain-English version of When to Use Different Communication Channels. GitHub Discussions are separate from Issues. Put another way, use Discussions for: "What do people think about X approach?" and Issues for: "The X button is broken.".

      -

      Alex: Use the comparison to make a decision, not to recite a table. The main contrasts are: PR comment means Feedback on a specific code change. PR review means Formal verdict (approve/request changes) with consolidated feedback. Discussion means Open-ended conversation, proposals, community Q&A.

      -

      Jamie: Let's pause on Try It: Rewrite One Comment. What should a learner take away from it?

      -

      Alex: This is where Try It: Rewrite One Comment becomes real: time: 2 minutes What you need: Just your brain. That matters in practice: Read this code review comment and rewrite it to be constructive. The workshop is closer to rehearsal than lecture. You hear the move, try the move, and then check what changed.

      -

      Alex: First, what you noticed. Then, why it matters. After that, what you suggest. Finally, why the suggestion helps. It is a checklist, but a meaningful one: every item creates evidence that the next step is safe.

      -

      Jamie: Before we leave Try It: Rewrite One Comment, what is the practical point?

      -

      Alex: First, encouragement. It is like walking a hallway with named doors: read the sign, enter the right room, then confirm where you landed.

      -

      Jamie: Let's pause on Contributing to Open Source. What should a learner take away from it?

      -

      Alex: Keep the learner anchored in Contributing to Open Source. This section was previously Appendix T. This is the part to say slowly: It is now part of the teaching narrative.

      +

      Jamie: Let's pause on Issue and pull request references. What should a learner take away from it?

      +

      Alex: The reason Issue and pull request references matters is that the following table shows how to reference issues and pull requests.

      +

      Alex: Keep the teaching thread moving. Start with User and team mentions: The following table shows how to mention users and teams.

      +

      Jamie: Let's pause on Commit references. What should a learner take away from it?

      +

      Alex: Here is the plain-English version of Commit references. The following table shows how to reference specific commits.

      -

      Alex: Keep the teaching thread moving. The reason A Guide for First-Time Contributors matters is that you do not need to be a professional developer to contribute to open source. That gives the learner a simple foothold: documentation, accessibility improvements, and bug reports are among the most valuable contributions any project can receive.

      -

      Jamie: Let's pause on 1. What Is Open Source? What should a learner take away from it?

      -

      Alex: Start with 1. What Is Open Source?: Open source software is software whose source code is publicly available. The next useful detail is this: Anyone can read it, use it, and - in most cases - contribute to it.

      -

      Alex: The practical takeaway is this. 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.

      -

      Alex: Keep the teaching thread moving. Here is the plain-English version of 2. Who Can Contribute? Contributors come from all backgrounds, skill levels, and countries. Put another way, 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. It is like learning a transit route. The names of the stops matter because they tell you whether you are still going the right direction.

      +

      Alex: Keep the teaching thread moving. This is where Closing keywords in pull requests becomes real: when you include certain keywords followed by an issue reference in a PR description, merging the PR automatically closes the referenced issue. That matters in practice: All of these keywords work: close, closes, closed, fix, fixes, fixed, resolve, resolves, resolved. The workshop is closer to rehearsal than lecture. You hear the move, try the move, and then check what changed.

      +

      Jamie: Let's pause on URL autolinking. What should a learner take away from it?

      +

      Alex: Keep the learner anchored in URL autolinking. GitHub automatically converts full URLs into clickable links. This is the part to say slowly: Accessibility note: While autolinked URLs work, they create poor link text for screen readers (the entire URL is read character by character).

      +

      Alex: Keep the teaching thread moving. The reason 27. HTML in Markdown matters is that GitHub allows a subset of HTML in Markdown files. That gives the learner a simple foothold: this is useful for semantic elements that do not have Markdown equivalents, advanced layout needs, and accessibility improvements.

      -

      Jamie: Let's pause on 3. What Makes a Good First Contribution? What should a learner take away from it?

      -

      Alex: Start with 3. What Makes a Good First Contribution? There is something to understand, something to try, and something that proves the try worked.

      -

      Alex: The practical takeaway is this. 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.

      -

      Alex: Keep the teaching thread moving. Keep the learner anchored in Signs a contribution is too large for a first attempt. A well-executed small contribution is far more valuable than a large contribution that cannot be merged because it is out of scope.

      -

      Alex: The practical takeaway is this. 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.

      -

      Jamie: Let's pause on 4. Finding Something to Work On. What should a learner take away from it?

      -

      Alex: The reason 4. Finding Something to Work On matters is that most open source projects label issues that are suitable for new contributors. That gives the learner a simple foothold: how to search: On any GitHub repository, go to Issues → filter by label.

      +

      Jamie: Let's pause on Keyboard key visualization. What should a learner take away from it?

      +

      Alex: Start with Keyboard key visualization: The element renders text in a key-cap style box. The next useful detail is this: Press NVDA + Space to toggle Focus Mode.

      +

      Alex: Treat examples as spoken recipes, not decorations. You may hear something like Press Ctrl + C to copy.; Press NVDA + Space to toggle Focus Mode. Read the command, understand what it changes, then run it only when the repository state matches the lesson.

      +

      Alex: Keep the teaching thread moving. Here is the plain-English version of Hidden comments. Hidden comments are useful for notes to yourself or other contributors that should not be visible to readers. It is like learning a transit route. The names of the stops matter because they tell you whether you are still going the right direction.

      +

      Jamie: Let's pause on Allowed HTML elements on GitHub. What should a learner take away from it?

      +

      Alex: This is where Allowed HTML elements on GitHub becomes real: GitHub whitelists specific HTML elements for security. That matters in practice: The following table lists the most useful allowed elements.

      -

      Alex: Keep the teaching thread moving. Start with Learning Cards: Finding Something to Work On. There is something to understand, something to try, and something that proves the try worked.

      -

      Alex: The practical takeaway is this. 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. 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.

      -

      Jamie: What is the pre-flight check here?

      -

      Alex: Here is the plain-English version of 5. Reading an Issue Before You Start. Before commenting "I'll take this" on an issue, ask yourself. Put another way, 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.

      -

      Alex: The practical takeaway is this. 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.

      -

      Jamie: Let's pause on Tool Cards: Fork, Clone, and Contribute. What should a learner take away from it?

      -

      Alex: Start with Tool Cards: Fork, Clone, and Contribute. There is something to understand, something to try, and something that proves the try worked.

      -

      Alex: First, click Fork on the repository page, then Create fork. Then, edit files directly in your fork's web interface. After that, click Contribute Open pull request to submit back to the original. Finally, fork the repo on github.com first. It is a checklist, but a meaningful one: every item creates evidence that the next step is safe.

      -

      Jamie: Before we leave Tool Cards: Fork, Clone, and Contribute, what is the practical point?

      -

      Alex: First, navigate to your fork and press. to open in the web editor. Then, edit, commit, and create a PR from the Source Control panel. After that, fork on github.com, then clone your fork: Ctrl+Shift+P Git: Clone. Finally, create a branch, make edits, commit and push. It is like walking a hallway with named doors: read the sign, enter the right room, then confirm where you landed.

      -

      Alex: Treat examples as spoken recipes, not decorations. You may hear something like 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. Read the command, understand what it changes, then run it only when the repository state matches the lesson.

      +

      Alex: Keep the teaching thread moving. Keep the learner anchored in Disallowed HTML on GitHub. GitHub strips these elements for security.

      +

      Alex: The practical takeaway is this. No JavaScript execution. No arbitrary CSS. No embedded content. No form elements (except task list checkboxes). No input fields. Event attributes like onclick, onload.

      +

      Jamie: Let's pause on 28. Screen Reader Behavior Summary. What should a learner take away from it?

      +

      Alex: The reason 28. Screen Reader Behavior Summary matters is that this table consolidates how every Markdown element behaves with screen readers. That gives the learner a simple foothold: use it as a quick reference when choosing how to format your content.

      +

      Alex: Keep the teaching thread moving. Start with 29. Accessible Markdown Authoring Checklist: Use this checklist every time you write a Markdown file, issue, or PR description. The next useful detail is this: It covers the accessibility requirements that make your content work for everyone. Think of it like entering a new building: first you find the lobby, then the room, then the door you actually need.

      -

      Jamie: Let's pause on The Basic Workflow. What should a learner take away from it?

      -

      Alex: Start with The Basic Workflow. There is something to understand, something to try, and something that proves the try worked.

      -

      Alex: First, fork the repository - creates your own copy on GitHub. Then, clone your fork to your computer (or open a Codespace - see Appendix N). After that, create a branch - name it something descriptive: fix/broken-link-setup-guide. Finally, make your change - edit the file, save, verify. It is like walking a hallway with named doors: read the sign, enter the right room, then confirm where you landed.

      -

      Jamie: Before we leave The Basic Workflow, what is the practical point?

      -

      Alex: First, commit with a clear message - "Fix broken link in setup-guide.md line 34". Then, push to your fork. After that, open a pull request from your branch to the original repository's default branch. Finally, respond to review feedback - maintainers may ask for changes; this is normal and not a rejection. The rhythm is simple: orient, act, verify, then continue.

      -

      Alex: Keep the teaching thread moving. The reason Writing a Good PR Description matters is that example: Fixed a broken link on line 34 of setup-guide.md. That gives the learner a simple foothold: the link pointed to /docs/old-setup which no longer exists. The interface gets friendlier when it stops being a wall of controls and starts being a set of named places.

      -

      Alex: The practical takeaway is this. What did you change? Why was the change needed? How did you verify it works?

      -

      Jamie: How should someone ask for help in a way that gets them unstuck faster?

      -

      Alex: Start with 7. Getting Help: It is always acceptable to ask a question on an issue or pull request. The next useful detail is this: 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.

      -

      Alex: The practical takeaway is this. 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.

      +

      Jamie: Let's pause on Structure. What should a learner take away from it?

      +

      Alex: Start with Structure. There is something to understand, something to try, and something that proves the try worked.

      +

      Alex: The practical takeaway is this. [ ] One H1 heading per document, used as the title. [ ] Heading levels never skip (no jumping from H2 to H4). [ ] Headings are descriptive (not "Section 1" or "Untitled"). [ ] Long documents have a table of contents with anchor links.

      +

      Alex: Keep the teaching thread moving. Start with Text and emphasis. There is something to understand, something to try, and something that proves the try worked.

      +

      Alex: The practical takeaway is this. [ ] Bold marks genuinely important content, not just visual styling. [ ] Bold text is not used as a substitute for headings. [ ] Strikethrough text has surrounding context explaining the change.

      +

      Jamie: Let's pause on Links. What should a learner take away from it?

      +

      Alex: Start with Links. There is something to understand, something to try, and something that proves the try worked.

      +

      Alex: The practical takeaway is this. [ ] Every link has descriptive text (never "click here," "here," "read more," or "link"). [ ] No bare URLs in prose (always use descriptive text). [ ] Multiple links on the same page have unique text if they point to different destinations. [ ] Relative links used for files within the same repository.

      -

      Alex: Keep the teaching thread moving. Here is the plain-English version of 8. After Your Contribution Is Merged. This matters for your GitHub profile. Put another way, 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.

      -

      Alex: The practical takeaway is this. 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.

      -

      Jamie: Let's pause on 9. Building a Contribution Habit. What should a learner take away from it?

      -

      Alex: This is where 9. Building a Contribution Habit becomes real: the hardest part of open source contribution is starting. That matters in practice: 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.

      -

      Alex: Keep the teaching thread moving. Keep the learner anchored in Practical habits. Challenge Time: Complete Challenge 8: The Culture Layer in the Challenge Hub, then advance to Chapter 09: Labels, Milestones and Projects. This is the part to say slowly: Next: Chapter 09: Labels, Milestones, and Projects Back: Chapter 07: Merge Conflicts Related appendices: Appendix M: Accessibility Standards Appendix F: Git Security Appendix O: Branch Protection. A good GitHub workflow is like a well-run meeting: everyone knows the topic, the next action, and who has the floor.

      -

      Alex: The practical takeaway is this. 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.

      +

      Alex: Keep the teaching thread moving. Start with Images. There is something to understand, something to try, and something that proves the try worked.

      +

      Alex: The practical takeaway is this. [ ] Every informative image has descriptive alt text. [ ] Alt text is not a filename (screenshot.png) or generic (image, photo). [ ] Complex images (charts, diagrams) have a detailed text description in a block. [ ] Decorative images have empty alt text.

      +

      Jamie: Let's pause on Lists and tables. What should a learner take away from it?

      +

      Alex: Start with Lists and tables. There is something to understand, something to try, and something that proves the try worked.

      +

      Alex: The practical takeaway is this. [ ] Lists use the correct type: ordered for sequential steps, unordered for non-sequential items. [ ] Tables have a text description immediately before them. [ ] Tables have descriptive header cells. [ ] Tables have fewer than 7 columns (split wide tables). [ ] Tables are used for data, not layout.

      +

      Alex: Keep the teaching thread moving. Start with Code. There is something to understand, something to try, and something that proves the try worked.

      +

      Alex: The practical takeaway is this. [ ] Fenced code blocks have a language identifier. [ ] Inline code used for commands, file names, and values. [ ] Code examples are complete enough to understand without the visual highlighting.

      -

      Jamie: Let's pause on Part 1: The GitHub Pull Requests Extension. What should a learner take away from it?

      -

      Alex: The reason The GitHub Pull Requests Extension matters is that see also: Appendix G: VS Code Reference for the complete list of GitHub Pull Requests extension keyboard shortcuts.

      -

      Alex: Keep the teaching thread moving. Start with 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,. The next useful detail is this: Prerequisites: Working with Pull Requests, Git & Source Control in VS Code Mac keyboard shortcuts: Throughout this chapter, all Ctrl+ shortcuts use Cmd+ on Mac, and Alt+ shortcuts use Option+ on Mac.

      -

      Jamie: What belongs in the live room, and what can wait until after?

      -

      Alex: Here is the plain-English version of Workshop Recommendation (Chapter 15, Part 1). Chapter 15, Part 1 introduces the GitHub Pull Requests extension for managing PRs directly from VS Code.

      -

      Alex: The practical takeaway is this. There are 2 guided challenges. Automation check: none (extension installation and review state are account-local). The evidence is issue comment with confirmation of actions completed. The pattern is install, check out, review, comment.

      +

      Jamie: Let's pause on GFM features. What should a learner take away from it?

      +

      Alex: Start with GFM features. There is something to understand, something to try, and something that proves the try worked.

      +

      Alex: The practical takeaway is this. [ ] Mermaid diagrams have a text equivalent. [ ] Alert block type matches the urgency of the content. [ ] summary text clearly describes what is inside. [ ] Task list items have descriptive labels. [ ] Complex math expressions have plain English descriptions.

      +

      Alex: Keep the teaching thread moving. Start with General. There is something to understand, something to try, and something that proves the try worked.

      +

      Alex: The practical takeaway is this. [ ] Color is never the only way information is conveyed. [ ] No information is communicated only through visual position or layout. [ ] Content makes sense when read linearly, top to bottom.

      +

      Jamie: Let's pause on 30. Common Mistakes and How to Fix Them. What should a learner take away from it?

      +

      Alex: The reason 30. Common Mistakes and How to Fix Them matters is that this section covers the errors we see most often in workshop participants' Markdown. That gives the learner a simple foothold: each one includes what goes wrong, why it matters, and how to fix it.

      -

      Jamie: Let's pause on Chapter 15, Part 1 Practice Set. What should a learner take away from it?

      -

      Alex: Start with Chapter 15, Part 1 Practice Set. There is something to understand, something to try, and something that proves the try worked.

      -

      Alex: First, install the GitHub Pull Requests extension - add the extension to VS Code and sign in with your GitHub account. Then, check out a PR and post a review comment - download a PR branch locally, read the diff, and post one constructive review comment. It is a checklist, but a meaningful one: every item creates evidence that the next step is safe.

      -

      Jamie: Let's pause on Practice 15.1 Step-by-Step: Install the Extension. What should a learner take away from it?

      -

      Alex: Keep the learner anchored in Practice 15.1 Step-by-Step: Install the Extension. Install the GitHub Pull Requests and Issues extension and authenticate with your GitHub account. This is the part to say slowly: VS Code desktop with your Learning Room repository open.

      -

      Alex: First, open the Extensions sidebar: Ctrl+Shift+X (Mac: Cmd+Shift+X). Then, your screen reader announces "Extensions: Marketplace." The search box has focus. After that, type GitHub Pull Requests in the search box and press Enter. Finally, navigate down the results list. Select GitHub Pull Requests (publisher: GitHub). It is like walking a hallway with named doors: read the sign, enter the right room, then confirm where you landed.

      -

      Jamie: Before we leave Practice 15.1 Step-by-Step: Install the Extension, what is the practical point?

      -

      Alex: First, activate the Install button. VS Code installs the extension and may show a notification. Then, after installation, VS Code prompts you to sign in. Activate Sign in to GitHub. After that, a browser window opens for GitHub OAuth. Approve the authorization and return to VS Code. Finally, verify: open the Explorer sidebar (Ctrl+Shift+E). You should now see a GitHub section in the sidebar showing Pull Requests and Issues. The rhythm is simple: orient, act, verify, then continue.

      -

      Jamie: Let's pause on Practice 15.2 Step-by-Step: Check Out a PR and Post a Comment. What should a learner take away from it?

      -

      Alex: The reason Practice 15.2 Step-by-Step: Check Out a PR and Post a Comment matters is that check out someone else's PR branch locally, read the diff in VS Code, and post one constructive review comment. That gives the learner a simple foothold: VS Code with the GitHub Pull Requests extension installed.

      -

      Alex: First, open the Command Palette: Ctrl+Shift+P (Mac: Cmd+Shift+P). Then, type GitHub Pull Requests: Focus on Pull Requests View and select it. The Pull Requests panel opens. After that, navigate the list of open PRs. Find one that is not yours (a classmate's PR from Chapter 6, 7, or 14). Finally, 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. The rhythm is simple: orient, act, verify, then continue.

      -

      Jamie: Before we leave Practice 15.2 Step-by-Step: Check Out a PR and Post a Comment, what is the practical point?

      -

      Alex: First, open the Command Palette again and run GitHub Pull Requests: Open Changed Files. This shows the list of files the PR changed. Then, open one changed file. VS Code opens the Diff Editor showing old content on the left and new content on the right. After that, 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). Finally, find one specific thing to comment on: a typo, an unclear sentence, a missing step, or something the author did well. Think of it as a rail line: each stop confirms you are still on the right route before the next one.

      +

      Alex: Keep the teaching thread moving. Start with Mistake 1 - Forgetting the blank line between paragraphs: What it produces: One merged paragraph. The next useful detail is this: Fix: Add a blank line between paragraphs.

      +

      Jamie: Let's pause on Mistake 2 - Skipping heading levels. What should a learner take away from it?

      +

      Alex: Here is the plain-English version of Mistake 2 - Skipping heading levels. Why it matters: Screen reader users navigating by heading level will miss entire sections. Put another way, jumping from H1 to H4 means H2 and H3 navigation finds nothing.

      +

      Alex: Keep the teaching thread moving. This is where Mistake 3 - Generic link text becomes real: why it matters: A screen reader user scanning the links list hears "here" - with no context about where the link goes. That matters in practice: Fix: For more information, read the GitHub Documentation. The workshop is closer to rehearsal than lecture. You hear the move, try the move, and then check what changed.

      -

      Jamie: What should the learner prove to themselves after each small task?

      -

      Alex: Start with Completing Chapter 15, Part 1: Submit Your Evidence: Open your assigned setup or review practice issue and post a completion comment. The next useful detail is this: Close your Chapter 12 challenge issues when done.

      -

      Alex: Keep the teaching thread moving. Start with Expected Outcomes. There is something to understand, something to try, and something that proves the try worked.

      -

      Alex: The practical takeaway is this. 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.

      -

      Jamie: What is the teaching move inside If You Get Stuck?

      -

      Alex: This is where If You Get Stuck becomes real: continue learning: The GitHub Skills course Review Pull Requests practices approving, requesting changes, and using suggestions in an interactive format. That matters in practice: See Appendix Z for the full catalog.

      -

      Alex: First, extension does not install? Reload VS Code: Ctrl+Shift+P, then run Developer: Reload Window. Then, oAuth sign-in fails? Verify your GitHub account is active in the browser first, close VS Code, reopen, and retry. After that, pR list is empty? Switch to "All Open" view in the GitHub Pull Requests panel. Finally, checkout fails? Confirm you have write access to the repository. If not, use the read-only GitHub.com fallback. It is a checklist, but a meaningful one: every item creates evidence that the next step is safe.

      -

      Jamie: If someone only remembers one thing from If You Get Stuck, what should it be?

      -

      Alex: First, diff Editor is hard to navigate? Press F7 for the Accessible Diff Viewer mode, which is purpose-built for screen readers. Then, cannot find the Add Comment command? Use Command Palette and search for GitHub Pull Requests: Add Comment. After that, ask facilitator to help verify the GitHub PR panel and model one review comment. Finally, finished but not sure you did it right? Compare your work against the Challenge 11 reference solution. It is like walking a hallway with named doors: read the sign, enter the right room, then confirm where you landed.

      +

      Jamie: Let's pause on Mistake 4 - Missing alt text on images. What should a learner take away from it?

      +

      Alex: Keep the learner anchored in Mistake 4 - Missing alt text on images. Why it matters: Screen reader users have no idea what the image shows. This is the part to say slowly: Some screen readers announce the filename, which is not helpful.

      +

      Alex: Keep the teaching thread moving. The reason Mistake 5 - Using bold instead of headings matters is that why it matters: Visually, this looks like a heading. That gives the learner a simple foothold: but screen reader users navigating with H will never find it.

      +

      Jamie: What does someone need before they touch the keyboard?

      +

      Alex: Start with Mistake 6 - No description before a table: Why it matters: A screen reader user enters the table without knowing what data it contains. The next useful detail is this: They hear "table, 2 columns, 3 rows" but not what the table is about.

      -

      Alex: Keep the teaching thread moving. Keep the learner anchored in Learning Moment. Reviewing others' work refines your own standards and builds community trust. This is the part to say slowly: The comment you just wrote helps another student learn - and you learn by articulating what makes documentation clear.

      -

      Jamie: Before we leave Learning Pattern Used in This Chapter, what is the practical point?

      -

      Alex: First, install and configure the tool before starting the task. Then, practice on someone else's work first (reviewing is safer than authoring). After that, use accessibility tools (F7 Accessible Diff Viewer) to navigate efficiently. Finally, write specific, constructive feedback (not just "looks good"). The rhythm is simple: orient, act, verify, then continue.

      -

      Alex: Keep the teaching thread moving. Start with 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. Think of it like entering a new building: first you find the lobby, then the room, then the door you actually need.

      +

      Alex: Keep the teaching thread moving. Here is the plain-English version of Mistake 7 - Code block without a language identifier. Why it matters: Without the language identifier, sighted users lose the visual benefit of syntax highlighting, and tools that process Markdown lose metadata about the content. Put another way, fix: Always add the language: `python. It is like learning a transit route. The names of the stops matter because they tell you whether you are still going the right direction.

      +

      Jamie: Let's pause on Mistake 8 - Inconsistent list markers. What should a learner take away from it?

      +

      Alex: This is where Mistake 8 - Inconsistent list markers becomes real: why it matters: While most processors render this as one list, some treat different markers as separate lists, creating unexpected spacing and structure. That matters in practice: Fix: Pick one marker and use it consistently.

      +

      Alex: Keep the teaching thread moving. Keep the learner anchored in Mistake 9 - Mermaid diagram without a text equivalent. Why it matters: Screen reader users cannot access the visual diagram. This is the part to say slowly: They hear nothing or a generic SVG container message.

      -

      Jamie: Let's pause on Method 1: Extensions Sidebar. What should a learner take away from it?

      -

      Alex: Start with Method 1: Extensions Sidebar. There is something to understand, something to try, and something that proves the try worked.

      -

      Alex: First, open Extensions sidebar: Ctrl+Shift+X (Mac: Cmd+Shift+X). Then, type "GitHub Pull Requests" in the search box. After that, find "GitHub Pull Requests and Issues" (publisher: GitHub). Finally, navigate to the extension in the results list. Treat it like a recipe: do not add the next ingredient until the previous one is actually in the bowl.

      -

      Jamie: Before we leave Method 1: Extensions Sidebar, what is the practical point?

      -

      Alex: First, press Enter to open the extension detail page. Then, tab to "Install" button → press Enter. It is a checklist, but a meaningful one: every item creates evidence that the next step is safe.

      -

      Jamie: Let's pause on Method 2: Command Palette. What should a learner take away from it?

      -

      Alex: This is where Method 2: Command Palette becomes real: the Extensions sidebar is a tree view. That matters in practice: Use Up/Down Arrow to navigate, Enter to open an extension's detail page.

      -

      Alex: First, ctrl+Shift+P. Then, type "install extensions". After that, select "Extensions: Install Extensions". Finally, search for "GitHub Pull Requests". It is a checklist, but a meaningful one: every item creates evidence that the next step is safe.

      -

      Jamie: Before we leave Method 2: Command Palette, what is the practical point?

      -

      Alex: First, install "GitHub Pull Requests and Issues". It is like walking a hallway with named doors: read the sign, enter the right room, then confirm where you landed.

      -

      Jamie: Let's pause on Signing In to GitHub. What should a learner take away from it?

      -

      Alex: Keep the learner anchored in Signing In to GitHub. After installation, VS Code prompts you to sign in.

      -

      Alex: First, a notification appears: "Sign in to GitHub to use Pull Requests". Then, navigate to the notification (Alt+N / Mac: Option+N, or status bar navigation). After that, select "Sign in". Finally, VS Code opens your browser for GitHub OAuth authentication. It is like walking a hallway with named doors: read the sign, enter the right room, then confirm where you landed.

      -

      Jamie: Before we leave Signing In to GitHub, what is the practical point?

      -

      Alex: First, authorize VS Code in the browser. Then, return to VS Code - you're now signed in. The rhythm is simple: orient, act, verify, then continue.

      +

      Jamie: Let's pause on Mistake 10 - Alert block with wrong type. What should a learner take away from it?

      +

      Alex: The reason Mistake 10 - Alert block with wrong type matters is that why it matters: CAUTION (red) implies irreversible harm. That gives the learner a simple foothold: a suggestion to try a different approach is, at most, a TIP (green) or a NOTE (blue).

      +

      Alex: Keep the teaching thread moving. Start with 31. Your First Real Markdown Document - Guided Exercise: In this exercise, you will create a Markdown document that uses most of the elements covered in this guide. The next useful detail is this: This is structured as a hands-on exercise that you can do during the workshop. Think of it like entering a new building: first you find the lobby, then the room, then the door you actually need.

      +

      Jamie: Let's pause on Setup. What should a learner take away from it?

      +

      Alex: Start with Setup. There is something to understand, something to try, and something that proves the try worked.

      +

      Alex: First, open any repository where you have write access. Then, click New Issue (or create a new.md file in VS Code). After that, you will write a mini profile document about yourself. Treat it like a recipe: do not add the next ingredient until the previous one is actually in the bowl.

      -

      Alex: Keep the teaching thread moving. Start with Verify sign-in. There is something to understand, something to try, and something that proves the try worked.

      -

      Alex: The practical takeaway is this. 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.

      -

      Jamie: Let's pause on What the Extension Adds. What should a learner take away from it?

      -

      Alex: Start with What the Extension Adds. There is something to understand, something to try, and something that proves the try worked.

      -

      Alex: The practical takeaway is this. 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.

      -

      Alex: Keep the teaching thread moving. Start with Learning Cards: Installing the PR Extension. There is something to understand, something to try, and something that proves the try worked.

      -

      Alex: The practical takeaway is this. 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". 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.

      +

      Jamie: Let's pause on Step 1 - Add a heading and introduction. What should a learner take away from it?

      +

      Alex: This is where Step 1 - Add a heading and introduction becomes real: type the following, replacing the placeholder text with your own information. That matters in practice: Use the Preview tab (or Ctrl+Shift+V in VS Code) to verify the heading renders as a large title.

      +

      Alex: Treat examples as spoken recipes, not decorations. You may hear something like About Me; Hi! My name is [your name] and I am participating in the; GIT Going with GitHub workshop. Read the command, understand what it changes, then run it only when the repository state matches the lesson.

      +

      Jamie: Let's pause on Step 2 - Add a section with a list. What should a learner take away from it?

      +

      Alex: Keep the learner anchored in Step 2 - Add a section with a list. Verify the numbered list renders correctly.

      +

      Jamie: Let's pause on Step 3 - Add emphasis and inline code. What should a learner take away from it?

      +

      Alex: The reason Step 3 - Add emphasis and inline code matters is that check that bold, italic, and inline code all render as expected. The interface gets friendlier when it stops being a wall of controls and starts being a set of named places.

      +

      Alex: Treat examples as spoken recipes, not decorations. You may hear something like My Setup; I use NVDA on Windows with Firefox. My terminal is; PowerShell and I am learning git commands. Read the command, understand what it changes, then run it only when the repository state matches the lesson.

      -

      Jamie: Let's pause on Method 1: Activity Bar. What should a learner take away from it?

      -

      Alex: This is where Method 1: Activity Bar becomes real: click the GitHub logo icon in the Activity Bar (the vertical strip of icons on the far left). That matters in practice: The GitHub Pull Requests panel opens.

      -

      Alex: The practical takeaway is this. "Pull Requests". "Issues".

      -

      Alex: First, the Activity Bar is not always reachable by Tab from the editor. Then, use Ctrl+Shift+P (Mac: Cmd+Shift+P) → type "GitHub Pull Requests: View Pull Request" or "Focus on Pull Requests View" → press Enter. After that, alternatively press Ctrl+Shift+G (Mac: Cmd+Shift+G) to open Source Control, then Tab until you reach the Activity Bar icon strip. Finally, navigate to the repository on GitHub.com. It is a checklist, but a meaningful one: every item creates evidence that the next step is safe.

      -

      Jamie: Before we leave Method 1: Activity Bar, what is the practical point?

      -

      Alex: First, click the Pull requests tab. Then, click any PR title to view its conversation, commits, and changed files. After that, use the Files changed tab to review diffs. It is like walking a hallway with named doors: read the sign, enter the right room, then confirm where you landed.

      -

      Alex: Treat examples as spoken recipes, not decorations. You may hear something like 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". Read the command, understand what it changes, then run it only when the repository state matches the lesson.

      -

      Jamie: Let's pause on Method 2: Explorer Section. What should a learner take away from it?

      -

      Alex: Start with Method 2: Explorer Section. There is something to understand, something to try, and something that proves the try worked.

      -

      Alex: First, open Explorer: Ctrl+Shift+E (Mac: Cmd+Shift+E). Then, navigate with Arrow keys to find the "GitHub Pull Requests" section. After that, expand it with Right Arrow. It is like walking a hallway with named doors: read the sign, enter the right room, then confirm where you landed.

      -

      Jamie: Let's pause on Description. What should a learner take away from it?

      -

      Alex: The reason Description matters is that the GitHub Pull Requests panel has two top-level sections. That gives the learner a simple foothold: "My Pull Requests" contains four filters: Assigned to Me, Created by Me, Waiting for my Review, and All Open.

      +

      Jamie: Let's pause on Step 5 - Add a table. What should a learner take away from it?

      +

      Alex: Start with Step 5 - Add a table. There is something to understand, something to try, and something that proves the try worked.

      +

      Alex: Treat examples as spoken recipes, not decorations. You may hear something like Tools I Use; The following table lists the tools I use daily.; Tool Purpose Platform; --- --- ---; NVDA Screen reader Windows; Firefox Web browser Windows; VS Code Code editor Windows. Read the command, understand what it changes, then run it only when the repository state matches the lesson.

      +

      Jamie: Let's pause on Step 7 - Add a collapsible section. What should a learner take away from it?

      +

      Alex: Start with Step 7 - Add a collapsible section. There is something to understand, something to try, and something that proves the try worked.

      +

      Alex: Treat examples as spoken recipes, not decorations. You may hear something like Additional Notes;; My accessibility testing experience; I have been using a screen reader for three years. I have tested; web applications with NVDA and I am learning how to contribute; accessibility bug reports to open source projects. Read the command, understand what it changes, then run it only when the repository state matches the lesson.

      +

      Jamie: Let's pause on You are done when. What should a learner take away from it?

      +

      Alex: This is where You are done when becomes real: you just wrote a Markdown document that uses headings, paragraphs, emphasis, inline code, links, blockquotes, tables, task lists, and collapsible sections. That matters in practice: Every one of these skills transfers directly to issues, pull requests, and documentation in this workshop.

      +

      Alex: The practical takeaway is this. Your document renders with a clear heading hierarchy (H1, H2). Bold and italic text render correctly. The numbered list shows sequential numbers. The link is clickable.

      -

      Alex: Keep the teaching thread moving. Start with Screen reader announcement example: "Pull Request 42: Add Timeline Guide, opened by jeffb, 2 days ago, 3 files changed".

      -

      Jamie: Let's pause on By status. What should a learner take away from it?

      -

      Alex: Start with By status. There is something to understand, something to try, and something that proves the try worked.

      -

      Alex: The practical takeaway is this. "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.

      -

      Alex: Keep the teaching thread moving. This is where By repository becomes real: the tree organizes PRs by repository. The workshop is closer to rehearsal than lecture. You hear the move, try the move, and then check what changed.

      +

      Alex: Keep the teaching thread moving. Start with Learning Cards: Quick-Reference Card. There is something to understand, something to try, and something that proves the try worked.

      +

      Alex: The practical takeaway is this. This card shows raw Markdown syntax in code blocks -- read each block to hear the exact characters to type. Keep this section bookmarked as a daily reference when writing issues, PRs, and comments. Each code block is labeled by format type (headings, lists, links, etc.) in the heading above it. The card uses large monospace code blocks -- increase zoom and each syntax example stays on one or two lines. Print this section or save it as a separate file for quick side-by-side reference while writing. Syntax characters (,, -, []) are visually distinct in the code font.

      +

      Jamie: Let's pause on 32. Quick-Reference Card. What should a learner take away from it?

      +

      Alex: The reason 32. Quick-Reference Card matters is that it shows the raw Markdown for every element covered in this guide.

      +

      Jamie: Let's pause on HTML in Markdown. What should a learner take away from it?

      +

      Alex: Start with HTML in Markdown. There is something to understand, something to try, and something that proves the try worked.

      +

      Alex: Treat examples as spoken recipes, not decorations. You may hear something like Press Ctrl + C to copy.; H 2 O; x 2; Line one Line two. Read the command, understand what it changes, then run it only when the repository state matches the lesson.

      -

      Jamie: Let's pause on Viewing PR Details. What should a learner take away from it?

      -

      Alex: Keep the learner anchored in Viewing PR Details. A PR detail view opens in the editor area showing.

      -

      Alex: The practical takeaway is this. 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).

      -

      Alex: First, navigate to a PR in the tree. Then, press Enter. It is like walking a hallway with named doors: read the sign, enter the right room, then confirm where you landed.

      -

      Alex: Keep the teaching thread moving. Start with Screen reader experience. There is something to understand, something to try, and something that proves the try worked.

      -

      Alex: The practical takeaway is this. 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.

      -

      Jamie: Let's pause on 3. Checking Out a Pull Request Branch. What should a learner take away from it?

      -

      Alex: Start with 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.

      +

      Jamie: Let's pause on Mermaid diagram (with accessible text). What should a learner take away from it?

      +

      Alex: Here is the plain-English version of Mermaid diagram (with accessible text). Next: Appendix D: Git Authentication Back: Appendix B: Screen Reader Cheat Sheet Teaching chapter: Chapter 06: Working with Pull Requests.

      -

      Alex: Keep the teaching thread moving. Start with Why Check Out a PR. There is something to understand, something to try, and something that proves the try worked.

      -

      Alex: The practical takeaway is this. 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.

      -

      Jamie: Let's pause on Method 1: From the PR Detail View. What should a learner take away from it?

      -

      Alex: Start with Method 1: From the PR Detail View. There is something to understand, something to try, and something that proves the try worked.

      -

      Alex: The practical takeaway is this. Downloads the branch. Switches your local repository to that branch. Opens the changed files in the editor.

      -

      Alex: First, open a PR (see Section 2). Then, in the PR detail view, navigate to "Checkout" button. After that, press Enter. It is a checklist, but a meaningful one: every item creates evidence that the next step is safe.

      -

      Jamie: Let's pause on Method 2: From the PR Tree. What should a learner take away from it?

      -

      Alex: Start with Method 2: From the PR Tree. There is something to understand, something to try, and something that proves the try worked.

      -

      Alex: First, navigate to the PR in the GitHub Pull Requests tree. Then, press Shift+F10 (Mac: Ctrl+Return) to open context menu. After that, select "Checkout Pull Request". It is like walking a hallway with named doors: read the sign, enter the right room, then confirm where you landed.

      +

      Jamie: What is the final checkpoint?

      +

      Alex: You should be able to point to the evidence, explain the action, and describe what you would do next if this were a real open source project. If you can teach the move back, you have learned it.

      +

      Jamie: And if they get stuck?

      +

      Alex: Read the latest message, not the loudest worry. Check the issue, the branch, the pull request, the status check, or the bot comment. Then ask for help with those facts in hand. That is how professionals collaborate.

      +
      +
      -

      Jamie: Let's pause on Method 3: Command Palette. What should a learner take away from it?

      -

      Alex: The reason Method 3: Command Palette matters is that after checkout, the bottom-left status bar shows the branch name (example: "jeffb/add-timeline-guide"). That gives the learner a simple foothold: your local files now match that branch.

      -

      Alex: First, ctrl+Shift+P (Mac: Cmd+Shift+P). Then, type "GitHub Pull Requests: Checkout". After that, select "GitHub Pull Requests: Checkout Pull Request". Finally, choose the PR from the list. The rhythm is simple: orient, act, verify, then continue.

      -

      Jamie: Let's pause on Returning to Your Original Branch. What should a learner take away from it?

      -

      Alex: Start with Returning to Your Original Branch. There is something to understand, something to try, and something that proves the try worked.

      -

      Alex: First, ctrl+Shift+P (Mac: Cmd+Shift+P). Then, type "git checkout". After that, select "Git: Checkout to.". Finally, choose your original branch (usually main or your feature branch). Think of it as a rail line: each stop confirms you are still on the right route before the next one.

      -

      Jamie: Let's pause on Learning Cards: Checking Out a PR. What should a learner take away from it?

      -

      Alex: Start with Learning Cards: Checking Out a PR. There is something to understand, something to try, and something that proves the try worked.

      -

      Alex: The practical takeaway is this. 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. 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.

      + +

      Tools, references, communities, and continued learning paths.

      +

      Based on: Appendix X: Resources and Links

      +

      Audio and transcript are being regenerated for this episode.

      +
      +Read Transcript - Episode 38: Resources and Links + +

      Transcript

      +

      Alex: This is Git Going with GitHub, episode 38: Resources and Links. I am Alex. By the end of this episode, Resources and Links should feel less like a wall of GitHub words and more like a set of moves you can trust.

      +

      Jamie: And I am Jamie. I am here for the practical questions: what should I listen for, what can go wrong, and what is the next calm move?

      -

      Alex: Keep the teaching thread moving. This is where 4. Reviewing Pull Requests in VS Code becomes real: once you've checked out a PR (or opened it in the detail view), you can review its changes fully within VS Code.

      -

      Jamie: Let's pause on In the PR detail view. What should a learner take away from it?

      -

      Alex: Start with In the PR detail view. There is something to understand, something to try, and something that proves the try worked.

      -

      Alex: First, scroll down to "Files Changed" section. Then, each file is a link. After that, navigate with Arrow keys. Finally, press Enter on a file to open its diff view. It is like walking a hallway with named doors: read the sign, enter the right room, then confirm where you landed.

      -

      Alex: Keep the teaching thread moving. The reason Screen reader announcement matters is that "docs/11-vscode-interface.md, 42 additions, 3 deletions". The interface gets friendlier when it stops being a wall of controls and starts being a set of named places.

      +

      Alex: Today we are working on this: Tools, references, communities, and continued learning paths. I want the learner to leave with a mental map, not just a remembered path through buttons.

      +

      Jamie: So the goal is understanding first, then action, then confirmation.

      +

      Alex: Right. We are building a rhythm: orient yourself, take one intentional action, then verify what changed before moving on.

      -

      Jamie: Let's pause on Understanding the Diff View. What should a learner take away from it?

      -

      Alex: Start with Understanding the Diff View: When you open a file from "Files Changed".

      -

      Alex: Keep the teaching thread moving. Start with Split view mode (default). There is something to understand, something to try, and something that proves the try worked.

      -

      Alex: The practical takeaway is this. Left side: original file (before changes). Right side: modified file (after changes). Changed lines highlighted (added = green, removed = red).

      -

      Jamie: Let's pause on Inline view mode. What should a learner take away from it?

      -

      Alex: Start with Inline view mode. There is something to understand, something to try, and something that proves the try worked.

      -

      Alex: The practical takeaway is this. Single editor. Removed lines shown with - prefix. Added lines shown with + prefix.

      +

      Jamie: What does someone need before they touch the keyboard?

      +

      Alex: Start with Everything You Need - Before, During, and After the Workshop: Every link, tool, guide, and community resource from the two-day workshop in one place. The next useful detail is this: Bookmark this page in your fork so it travels with you.

      +

      Alex: The next layer is this. Start with Learning Cards: Navigating This Resource Guide. There is something to understand, something to try, and something that proves the try worked.

      +

      Alex: The practical anchors are these. This appendix is organized as 16 numbered sections with heading levels -- press H or 2 to jump between major sections in browse mode. Most sections contain tables of links -- navigate tables with T to jump to the next table, then use arrow keys to read rows and columns. Each resource link opens in the same tab by default -- use Ctrl+Enter (Windows) to open in a new tab and keep this reference page available. Tables in this appendix have a Resource/URL/Notes column structure -- widen your browser or zoom out slightly if columns overlap at high magnification. Link text is descriptive (resource names, not raw URLs) making it easier to scan the page visually. Bookmark this page in your browser for quick access -- it is the single-page reference for everything from the workshop.

      +

      Jamie: What is the one idea that makes the next few steps less mysterious?

      +

      Alex: This is where 1. The Central Project - Accessibility Agents becomes real: the project you forked, contributed to, and carry home.

      +

      Alex: A solid pull request habit is to separate three questions: what changed, why it changed, and what still needs review. That keeps the conversation useful instead of noisy.

      -

      Alex: Keep the teaching thread moving. Start with To toggle between views. There is something to understand, something to try, and something that proves the try worked.

      -

      Alex: The practical takeaway is this. Command Palette: Ctrl+Shift+P (Mac: Cmd+Shift+P) → "Diff: Toggle Inline View".

      -

      Jamie: Let's pause on Recommended workflow for screen reader users. What should a learner take away from it?

      -

      Alex: Start with Recommended workflow for screen reader users. There is something to understand, something to try, and something that proves the try worked.

      -

      Alex: The practical takeaway is this. Unchanged lines (for context). Removed lines (prefixed with -). Added lines (prefixed with +).

      -

      Alex: First, open a changed file from the PR detail view. Then, press F7 to jump to the first diff hunk. After that, press Alt+F2 (Mac: Option+F2) to open Accessible View. Finally, read the hunk content. The rhythm is simple: orient, act, verify, then continue.

      -

      Jamie: Before we leave Recommended workflow for screen reader users, what is the practical point?

      -

      Alex: First, press Escape to close Accessible View. Then, press F7 to jump to the next hunk. After that, repeat until all hunks reviewed. Think of it as a rail line: each stop confirms you are still on the right route before the next one.

      -

      Alex: Keep the teaching thread moving. Start with 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. The next useful detail is this: Previously, deleted code could only be read, not selected.

      +

      Alex: Now bring the learner back to the room. Keep the learner anchored in Your Personal Fork. After the workshop, your fork lives at.

      +

      Jamie: What is the ordered workflow?

      +

      Alex: Start with Quick access from VS Code. There is something to understand, something to try, and something that proves the try worked.

      +

      Alex: First, clone your fork: git clone https://github.com/[your-username]/accessibility-agents.git. Then, open in VS Code: cd accessibility-agents && code. After that, open Copilot Chat: Ctrl+Shift+I. The rhythm is simple: orient, act, verify, then continue.

      +

      Alex: The useful habit is simple: orient first, act second, verify third. That pause before acting is part of the work.

      +

      Jamie: Give me the sequence, because order matters here.

      +

      Alex: Start with Personalizing Your Fork. There is something to understand, something to try, and something that proves the try worked.

      +

      Alex: First, copy preferences.example.md to preferences.md in.github/agents/. Then, add your GitHub username, your most-used repositories, and your preferred output format. After that, commit the file - now the agents know who you are and what you work on. Think of it as a rail line: each stop confirms you are still on the right route before the next one.

      -

      Jamie: Let's pause on Flagging Issues During Review. What should a learner take away from it?

      -

      Alex: Here is the plain-English version of Flagging Issues During Review. Start Review saves your comments as a draft until you submit the full review (see Section 7).

      -

      Alex: First, navigate to the specific line in the diff. Then, press Shift+F10 (Mac: Ctrl+Return) for context menu. After that, select "Add Comment". Finally, type your comment in the input that appears. Treat it like a recipe: do not add the next ingredient until the previous one is actually in the bowl.

      -

      Jamie: Before we leave Flagging Issues During Review, what is the practical point?

      -

      Alex: First, choose "Single Comment" or "Start Review". It is a checklist, but a meaningful one: every item creates evidence that the next step is safe.

      -

      Alex: Keep the teaching thread moving. Start with Learning Cards: Reviewing Pull Requests in VS Code. There is something to understand, something to try, and something that proves the try worked.

      -

      Alex: The practical takeaway is this. 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. 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.

      -

      Jamie: Let's pause on Tool Cards: Create a Pull Request (from your editor). What should a learner take away from it?

      -

      Alex: Keep the learner anchored in Tool Cards: Create a Pull Request (from your editor). VS Code Desktop (primary for Day 2). This is the part to say slowly: After you've pushed commits to a feature branch, you can create a PR without leaving VS Code.

      -

      Alex: First, ctrl+Shift+P GitHub Pull Requests: Create Pull Request. Then, fill in the title, description, and base branch. After that, click Create. Finally, push your branch, then click the Compare & pull request banner on the repo page. It is like walking a hallway with named doors: read the sign, enter the right room, then confirm where you landed.

      -

      Jamie: Before we leave Tool Cards: Create a Pull Request (from your editor), what is the practical point?

      -

      Alex: First, fill in the form and click Create pull request. Then, after pushing, click Create Pull Request -- this opens gitub.com with the form pre-filled. The rhythm is simple: orient, act, verify, then continue.

      -

      Alex: Treat examples as spoken recipes, not decorations. You may hear something like git push -u origin your-branch; gh pr create --title "Title" --body "Description". Read the command, understand what it changes, then run it only when the repository state matches the lesson.

      +

      Jamie: Okay, set the room for us. What are we walking into?

      +

      Alex: Here is the plain-English version of 2. GitHub Accessibility Guides. Official guides from the GitHub Accessibility team. Put another way, these were the primary research sources for this workshop's documentation.

      +

      Alex: This is where the talk moves from concept to action. This is where 3. GitHub Skills Learning Modules becomes real: GitHub Skills is GitHub's free, self-paced interactive learning platform. That matters in practice: Every course runs entirely inside GitHub - no external site, no separate login, no video to watch.

      +

      Jamie: Turn that into a path someone can follow.

      +

      Alex: Keep the learner anchored in How GitHub Skills Works. Unlike a conventional course where you watch videos or read slides, GitHub Skills teaches through doing.

      +

      Alex: First, copy the course: Select "Start course" → "Use this template" → "Create a new repository." This copies the course scaffold to your own account. Then, mona activates: A GitHub Actions workflow automatically runs - within 20 seconds, Mona opens your first lesson as an Issue in your new repository. After that, read and act: The issue contains step-by-step instructions. You do the task (commit a file, open a PR, resolve a conflict) in the same repository. Finally, mona validates: Another GitHub Actions workflow detects what you did, checks if it's correct, and either advances you to the next step or gives you feedback to try again. It is like walking a hallway with named doors: read the sign, enter the right room, then confirm where you landed.

      +

      Jamie: How would you walk the room through that step by step?

      +

      Alex: First, repeat until done: All feedback arrives as issue comments and new issues. The course is complete when Mona closes the final issue with a success message. The rhythm is simple: orient, act, verify, then continue.

      -

      Jamie: Let's pause on Prerequisites. What should a learner take away from it?

      -

      Alex: Start with Prerequisites. There is something to understand, something to try, and something that proves the try worked.

      -

      Alex: First, you've created a branch (see Git & Source Control: Branch Management). Then, you've made commits. After that, you've pushed the branch to GitHub (Ctrl+Shift+P / Mac: Cmd+Shift+P → "Git: Push"). The rhythm is simple: orient, act, verify, then continue.

      -

      Jamie: Let's pause on Method 1: Command Palette (Recommended). What should a learner take away from it?

      -

      Alex: Start with Method 1: Command Palette (Recommended). There is something to understand, something to try, and something that proves the try worked.

      -

      Alex: First, ctrl+Shift+P (Mac: Cmd+Shift+P). Then, type "GitHub Pull Requests: Create". After that, select "GitHub Pull Requests: Create Pull Request". Finally, a form opens in the editor. Think of it as a rail line: each stop confirms you are still on the right route before the next one.

      -

      Jamie: Let's pause on Method 2: Source Control Panel. What should a learner take away from it?

      -

      Alex: Start with Method 2: Source Control Panel. There is something to understand, something to try, and something that proves the try worked.

      -

      Alex: First, open Source Control: Ctrl+Shift+G (Mac: Cmd+Shift+G). Then, after pushing, a "Create Pull Request" button appears. After that, press Enter on that button. Treat it like a recipe: do not add the next ingredient until the previous one is actually in the bowl.

      +

      Alex: Before the learner moves on. The reason Screen Reader Navigation of a GitHub Skills Course matters is that since everything happens in GitHub, the accessibility skills from this workshop apply directly. The interface gets friendlier when it stops being a wall of controls and starts being a set of named places.

      +

      Alex: A solid navigation habit is to prove where you are before activating controls. Headings, landmarks, and the address bar are not trivia; they are your map.

      +

      Jamie: How should they picture the shape of the workshop?

      +

      Alex: Start with After This Workshop - Your Learning Path: GitHub Skills courses are available 24/7 and are completely free. The next useful detail is this: Recommended order after this workshop.

      +

      Alex: Hold that next to this. Start with Learning Cards: Screen Reader Downloads and Setup. There is something to understand, something to try, and something that proves the try worked.

      +

      Alex: That shows up in the workshop in a few specific ways. NVDA (free, Windows): download from nvaccess.org -- after installing, toggle browse/focus mode with NVDA+Space and open the elements list with NVDA+F7. JAWS (Windows): download a trial from freedomscientific.com -- Virtual PC Cursor toggle is Insert+Z, elements list is Insert+F3. VoiceOver (macOS/iOS): built in, no download needed -- start with Cmd+F5 on Mac, or Settings then Accessibility then VoiceOver on iOS. NVDA and JAWS both support speech and braille output simultaneously if you use a refreshable braille display. VoiceOver on macOS integrates with Zoom (screen magnifier) -- enable both in System Settings then Accessibility for combined magnification and speech. Narrator on Windows is built in and requires no download -- launch with Win+Ctrl+Enter for a quick, lightweight screen reader experience.

      -

      Jamie: Let's pause on Method 3: GitHub Panel. What should a learner take away from it?

      -

      Alex: Start with Method 3: GitHub Panel. There is something to understand, something to try, and something that proves the try worked.

      -

      Alex: First, open GitHub view (Activity Bar → GitHub icon). Then, right-click your branch in the tree. After that, select "Create Pull Request". It is a checklist, but a meaningful one: every item creates evidence that the next step is safe.

      -

      Alex: Keep the teaching thread moving. Start with Title (required). There is something to understand, something to try, and something that proves the try worked.

      -

      Alex: The practical takeaway is this. Auto-filled with your most recent commit message. Edit to make it descriptive (example: "Add Timeline View documentation").

      -

      Jamie: Let's pause on Description (optional but recommended). What should a learner take away from it?

      -

      Alex: Start with Description (optional but recommended). There is something to understand, something to try, and something that proves the try worked.

      -

      Alex: The practical takeaway is this. 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.

      +

      Jamie: There are a lot of tools in play. How do we keep that from feeling like a contest?

      +

      Alex: Start with Key commands (quick reference). There is something to understand, something to try, and something that proves the try worked.

      +

      Alex: For a learner, the useful signals are these. Toggle browse/focus mode: NVDA+Space. Elements list: NVDA+F7. Next heading: H Next link: K Next button: B Next form field: F.

      +

      Alex: That connects to another useful point. Start with Key commands (quick reference). There is something to understand, something to try, and something that proves the try worked.

      +

      Alex: The parts worth keeping in working memory are these. Virtual PC Cursor on/off: Insert+Z. Elements list: Insert+F3. Next heading: H Next link: Tab or U Next button: B.

      +

      Jamie: What stays the same when the tool changes?

      +

      Alex: On the ground, that means a few things. Start/stop VoiceOver: Cmd+F5. VO modifier: Caps Lock or Ctrl+Option. Rotor: VO+U. Next heading: VO+Cmd+H.

      -

      Alex: Keep the teaching thread moving. Start with Base branch (target). There is something to understand, something to try, and something that proves the try worked.

      -

      Alex: The practical takeaway is this. Usually main or develop. This is the branch your changes will merge into.

      -

      Jamie: Let's pause on Compare branch (source). What should a learner take away from it?

      -

      Alex: Start with Compare branch (source). There is something to understand, something to try, and something that proves the try worked.

      -

      Alex: The practical takeaway is this. Your feature branch (auto-selected). This is the branch with your changes.

      -

      Alex: Keep the teaching thread moving. Start with Reviewers (optional). There is something to understand, something to try, and something that proves the try worked.

      -

      Alex: The practical takeaway is this. Select people to review your PR. Navigate the list with Arrow keys.

      +

      Jamie: What does the learner do first, second, and then after that?

      +

      Alex: Start with Install the GitHub PR extension quickly. There is something to understand, something to try, and something that proves the try worked.

      +

      Alex: First, open VS Code Extensions (Ctrl+Shift+X). Then, search: GitHub Pull Requests. After that, install: publisher is "GitHub". Think of it as a rail line: each stop confirms you are still on the right route before the next one.

      +

      Jamie: What would you say to someone who is already bracing for this to be too much?

      +

      Alex: Here is the plain-English version of 7. GitHub Agentic Workflows. GitHub Agentic Workflows are in technical preview as of February 2026. Put another way, access, feedback channels, and setup information.

      +

      Jamie: Let's pause on How Agentic Workflows connect to what you learned. What should a learner take away from it?

      +

      Alex: This is where How Agentic Workflows connect to what you learned becomes real: the only difference is where they run and how sophisticated their executor is. The workshop is closer to rehearsal than lecture. You hear the move, try the move, and then check what changed.

      +

      Alex: First, standard GitHub Actions (YAML workflows - triggers, jobs, steps). Then, accessibility Agents agents (.agent.md files - plain English instructions, Copilot Chat executor). After that, GitHub Agentic Workflows (.md files in.github/workflows/ - plain English instructions, cloud-based coding agent executor). It is a checklist, but a meaningful one: every item creates evidence that the next step is safe.

      -

      Jamie: Let's pause on Labels (optional). What should a learner take away from it?

      -

      Alex: Start with Labels (optional). There is something to understand, something to try, and something that proves the try worked.

      -

      Alex: The practical takeaway is this. Add labels like documentation, accessibility, good-first-issue.

      -

      Alex: Keep the teaching thread moving. Start with Milestone (optional). There is something to understand, something to try, and something that proves the try worked.

      -

      Alex: The practical takeaway is this. Link the PR to a project milestone.

      -

      Jamie: Let's pause on Draft PR checkbox. What should a learner take away from it?

      -

      Alex: Start with Draft PR checkbox. There is something to understand, something to try, and something that proves the try worked.

      -

      Alex: The practical takeaway is this. Check this if the PR is not ready for review yet. Unchecked = "Ready for review".

      +

      Jamie: If I am listening before the workshop starts, what should settle in my mind first?

      +

      Alex: Keep the learner anchored in 8. Spec-Driven Development - Spec Kit. The core idea: Write the intent of a feature before anyone builds it. This is the part to say slowly: The specification is a living document - AI uses it to plan tasks, contributors use it to stay aligned, the community uses it to evaluate whether the outcome matched the intention.

      +

      Alex: Another way to ground it. The reason Slash commands matters is that works with GitHub Copilot, Claude Code, and Gemini CLI.

      +

      Alex: That becomes easier when you listen for these cues. /specify - open a new specification session. /plan - convert a spec into a development plan. /tasks - break the plan into trackable tasks.

      +

      Jamie: What should they understand before typing anything?

      +

      Alex: Start with GitHub CLI (gh). There is something to understand, something to try, and something that proves the try worked.

      +

      Alex: Treat examples as spoken recipes, not decorations. You may hear something like Install; winget install GitHub.cli Windows; brew install gh macOS; Most useful commands for contributors; gh issue list List issues in current repo; gh issue view 42 Read issue 42; gh pr list List open PRs; gh pr view 14 Read PR 14; gh pr create Create a PR. Read the command, understand what it changes, then run it only when the repository state matches the lesson.

      -

      Alex: Keep the teaching thread moving. Start with Screen reader navigation. There is something to understand, something to try, and something that proves the try worked.

      -

      Alex: The practical takeaway is this. All fields are standard form inputs. Tab to move between fields. Use Arrow keys in dropdowns (reviewers, labels, milestones).

      -

      Jamie: Let's pause on Submitting the PR. What should a learner take away from it?

      -

      Alex: This is where Submitting the PR becomes real: VS Code creates the PR on GitHub and shows a success message. That matters in practice: The PR link appears in the notification - click it to open the PR on GitHub, or open it in the GitHub Pull Requests panel.

      -

      Alex: First, review all fields. Then, tab to "Create" button. After that, press Enter. Finally, navigate to the repository on GitHub. It is a checklist, but a meaningful one: every item creates evidence that the next step is safe.

      -

      Jamie: Before we leave Submitting the PR, what is the practical point?

      -

      Alex: First, if you recently pushed, a yellow banner "Compare & pull request" appears - click it. Then, otherwise: click Pull requests tab, then New pull request, then select your branch. After that, fill in the title and description. Finally, click Create pull request. It is like walking a hallway with named doors: read the sign, enter the right room, then confirm where you landed.

      -

      Alex: Treat examples as spoken recipes, not decorations. You may hear something like 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. Read the command, understand what it changes, then run it only when the repository state matches the lesson.

      -

      Alex: Keep the teaching thread moving. Start with Learning Cards: Creating a Pull Request. There is something to understand, something to try, and something that proves the try worked.

      -

      Alex: The practical takeaway is this. 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. 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.

      +

      Jamie: How do you keep commands from becoming magic words?

      +

      Alex: Start with Copilot in the CLI (gh copilot). There is something to understand, something to try, and something that proves the try worked.

      +

      Alex: Treat examples as spoken recipes, not decorations. You may hear something like Install the extension; gh extension install github/gh-copilot; Ask Copilot to explain a command; gh copilot explain "git rebase -i HEAD 3"; Ask Copilot to suggest a command; gh copilot suggest "undo my last commit but keep the changes staged". Read the command, understand what it changes, then run it only when the repository state matches the lesson.

      +

      Jamie: Give me the version that sounds like an instructor, not a manual.

      +

      Alex: This is where 10. GitHub Mobile Apps becomes real: GitHub's official mobile apps bring the full GitHub experience to your phone or tablet. That matters in practice: Perfect for reviewing PRs, triaging issues, and staying connected when away from your computer.

      +

      Alex: Here is the practical turn. Start with What You Can Do in GitHub Mobile. There is something to understand, something to try, and something that proves the try worked.

      +

      Alex: Here is what that changes in practice. Browse repositories - navigate code, read files, view commits. Manage issues - create, edit, comment, close, and label issues. Review pull requests - read diffs, leave comments, request changes, approve, merge. Manage notifications - triage your inbox on the go. Interact with GitHub Copilot - chat with Copilot Chat on mobile (as of Feb 2026). View GitHub Actions - monitor workflows and check build status.

      -

      Jamie: Let's pause on 6. Pull Request Description Templates. What should a learner take away from it?

      -

      Alex: The reason 6. Pull Request Description Templates matters is that many repositories include a PR template - a Markdown file that pre-fills the PR description with a checklist or structure.

      -

      Alex: Keep the teaching thread moving. Start with Where Templates Are Stored: When you create a PR in VS Code, the extension automatically loads the template into the description field.

      -

      Alex: The practical takeaway is this.github/pull request template.md (root).github/PULL REQUEST TEMPLATE.md.github/PULL REQUEST TEMPLATE/ (folder with multiple templates). docs/pull request template.md.

      -

      Jamie: Let's pause on Example PR Template. What should a learner take away from it?

      -

      Alex: Start with Example PR Template. There is something to understand, something to try, and something that proves the try worked.

      -

      Alex: Treat examples as spoken recipes, not decorations. You may hear something like 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,. Read the command, understand what it changes, then run it only when the repository state matches the lesson.

      +

      Jamie: Where do you want a learner to place their attention here?

      +

      Alex: The reason Accessibility Features matters is that pro tip: Enable push notifications for mentions and reviews so you can respond quickly when your input is needed.

      +

      Alex: The room should hear these as checkpoints. Native screen reader gestures (VoiceOver on iOS, TalkBack on Android). Dynamic text sizing. Dark mode / high contrast. Keyboard navigation (when using external keyboard with tablet).

      +

      Alex: That matters because of the next idea. Start with 11. GitHub Best Practices and Power Features: Essential tips and lesser-known features that make you a more effective contributor. Think of it like entering a new building: first you find the lobby, then the room, then the door you actually need.

      +

      Jamie: Let's pause on Saved Replies. What should a learner take away from it?

      +

      Alex: Here is the plain-English version of Saved Replies. Saved replies let you create reusable text templates for common responses.

      +

      Alex: These are the details that keep the idea from floating away. Thanking first-time contributors. Requesting more information with a friendly tone. Explaining common setup issues. Closing duplicate issues.

      -

      Jamie: Let's pause on Screen reader workflow. What should a learner take away from it?

      -

      Alex: This is where Screen reader workflow becomes real: keyboard tip: Use Ctrl+F (Mac: Cmd+F) to jump to each <!-- placeholder, fill it in, then F3 to jump to the next one. The workshop is closer to rehearsal than lecture. You hear the move, try the move, and then check what changed.

      -

      Alex: First, create PR (Method 1-3 from Section 5). Then, the description field is pre-filled with the template. After that, navigate through the template with Arrow keys. Finally, replace each `` with your content. It is a checklist, but a meaningful one: every item creates evidence that the next step is safe.

      -

      Jamie: Before we leave Screen reader workflow, what is the practical point?

      -

      Alex: First, check checkboxes by typing x between the brackets: - [x]. It is like walking a hallway with named doors: read the sign, enter the right room, then confirm where you landed.

      -

      Jamie: Let's pause on 7. Commenting and Requesting Changes. What should a learner take away from it?

      -

      Alex: Start with 7. Commenting and Requesting Changes. There is something to understand, something to try, and something that proves the try worked.

      -

      Alex: The practical takeaway is this. Leave inline comments on specific lines. Request changes before the PR can be merged. Approve the PR. Submit general feedback.

      -

      Jamie: Let's pause on Adding an Inline Comment. What should a learner take away from it?

      -

      Alex: Start with Adding an Inline Comment. There is something to understand, something to try, and something that proves the try worked.

      -

      Alex: First, open a file from the PR's "Files Changed" list. Then, navigate to the line you want to comment on. After that, press Shift+F10 (Mac: Ctrl+Return) to open context menu. Finally, select "Add Comment". The rhythm is simple: orient, act, verify, then continue.

      -

      Jamie: Before we leave Adding an Inline Comment, what is the practical point?

      -

      Alex: First, type your comment. Then, choose "Add Single Comment" (posts immediately) or "Start Review" (saves as a draft). Think of it as a rail line: each stop confirms you are still on the right route before the next one.

      +

      Jamie: Let's pause on How to set up. What should a learner take away from it?

      +

      Alex: Start with How to set up. There is something to understand, something to try, and something that proves the try worked.

      +

      Alex: First, go to github.com/settings/replies. Then, click "Add a saved reply". After that, give it a short label (e.g., "welcome-first-time"). Finally, write your template text (can include Markdown). It is a checklist, but a meaningful one: every item creates evidence that the next step is safe.

      +

      Jamie: Let's pause on How to use. What should a learner take away from it?

      +

      Alex: Start with How to use. There is something to understand, something to try, and something that proves the try worked.

      +

      Alex: A few details make that real. When writing any comment, press Ctrl+. (period) to open the saved replies menu. Select your saved reply. Edit as needed before posting.

      +

      Alex: This is the part worth saying out loud. The reason Pinned Issues matters is that pin important issues to the top of your repository's Issues tab. The interface gets friendlier when it stops being a wall of controls and starts being a set of named places.

      +

      Alex: The practical takeaway is this. FAQs and getting started guides. Known issues and workarounds. Roadmap and project status updates. Community guidelines.

      +

      Alex: A solid issue habit is to read the title, the body, and the timeline before acting. You are listening for the requested action, the missing evidence, and the person who needs a response.

      -

      Jamie: Let's pause on Comment format tips. What should a learner take away from it?

      -

      Alex: Start with Comment format tips. There is something to understand, something to try, and something that proves the try worked.

      -

      Alex: The practical takeaway is this. Be specific: "This heading should be H3, not H2". Provide context: "Screen readers announce this as 'list with 1 item' - should be a paragraph instead". Suggest a fix: "Consider rewording to: 'Click the button to save'".

      -

      Jamie: Let's pause on If you have multiple comments to make, use "Start Review". What should a learner take away from it?

      -

      Alex: Start with If you have multiple comments to make, use "Start Review". There is something to understand, something to try, and something that proves the try worked.

      -

      Alex: First, add your first inline comment → select "Start Review". Then, continue adding comments to other lines. After that, all comments are saved as drafts (not visible to others yet). Treat it like a recipe: do not add the next ingredient until the previous one is actually in the bowl.

      -

      Jamie: Let's pause on Submitting Your Review. What should a learner take away from it?

      -

      Alex: This is where Submitting Your Review becomes real: the review type selector is a radio button group. That matters in practice: Use Arrow keys to choose, Enter to confirm.

      -

      Alex: The practical takeaway is this. Comment - general feedback, no approval decision. Approve - PR looks good, ready to merge. Request Changes - issues must be fixed before merging.

      -

      Alex: First, ctrl+Shift+P (Mac: Cmd+Shift+P). Then, type "GitHub Pull Requests: Submit Review". After that, select "GitHub Pull Requests: Finish Review". Finally, choose review type. It is a checklist, but a meaningful one: every item creates evidence that the next step is safe.

      -

      Jamie: Before we leave Submitting Your Review, what is the practical point?

      -

      Alex: First, optionally add a summary comment. Then, press Enter to submit. It is like walking a hallway with named doors: read the sign, enter the right room, then confirm where you landed.

      +

      Jamie: Let's pause on How to pin an issue. What should a learner take away from it?

      +

      Alex: Start with How to pin an issue: You can pin up to 3 issues per repository. The next useful detail is this: Pinned issues are visible to everyone, even those who haven't starred or watched your repo.

      +

      Alex: First, open the issue you want to pin. Then, in the right sidebar, click the three-dot menu (⋯). After that, select "Pin issue". Finally, it now appears at the top of the Issues list. Think of it as a rail line: each stop confirms you are still on the right route before the next one.

      +

      Alex: Keep the thread going. Here is the plain-English version of Pinned Comments (New: Feb 2026). You can now pin a single comment within an issue thread to keep important information visible.

      +

      Alex: The practical takeaway is this. Workarounds or temporary solutions. Decisions made during discussion. Links to related issues or PRs. Status updates from maintainers.

      +

      Jamie: Let's pause on How to pin a comment. What should a learner take away from it?

      +

      Alex: This is where How to pin a comment becomes real: only repository collaborators can pin comments. That matters in practice: There can be only one pinned comment per issue.

      +

      Alex: First, find the comment you want to pin. Then, click the three-dot menu (⋯) on the comment. After that, select "Pin comment". It is a checklist, but a meaningful one: every item creates evidence that the next step is safe.

      -

      Jamie: Let's pause on What Happens After Submission. What should a learner take away from it?

      -

      Alex: Keep the learner anchored in What Happens After Submission. Web alternative (github.com) - reviewing. This is the part to say slowly: See Accessible Code Review for detailed screen reader steps.

      -

      Alex: The practical takeaway is this. All your draft comments post to GitHub. The PR author receives a notification. Your review status appears on the PR (Approved / Changes Requested / Commented). If you requested changes, the PR cannot merge until you approve it.

      -

      Alex: First, open the PR and click the Files changed tab. Then, read through each file's diff. After that, click the blue + button on any line to add an inline comment. Finally, choose Start a review to batch comments. It is like walking a hallway with named doors: read the sign, enter the right room, then confirm where you landed.

      -

      Jamie: Before we leave What Happens After Submission, what is the practical point?

      -

      Alex: First, click Review changes (top right) to select Comment / Approve / Request changes. Then, click Submit review. The rhythm is simple: orient, act, verify, then continue.

      -

      Alex: Treat examples as spoken recipes, not decorations. You may hear something like View the PR diff in your terminal; gh pr diff 42; Approve; gh pr review 42 --approve --body "Looks good."; Request changes; gh pr review 42 --request-changes --body "Heading hierarchy needs fixing."; Comment-only (no verdict); gh pr review 42 --comment --body. Read the command, understand what it changes, then run it only when the repository state matches the lesson.

      -

      Jamie: Let's pause on Learning Cards: Commenting and Requesting Changes. What should a learner take away from it?

      -

      Alex: Start with Learning Cards: Commenting and Requesting Changes. There is something to understand, something to try, and something that proves the try worked.

      -

      Alex: The practical takeaway is this. In a diff view, navigate to a line and press Shift+F10 for the context menu, then select "Add Comment" to leave inline feedback. Choose "Start Review" instead of "Single Comment" to batch multiple comments before submitting them all at once. When submitting a review, use Ctrl+Shift+P then "GitHub Pull Requests: Submit Review" and choose Approve, Request Changes, or Comment. Inline comments appear as expandable banners within the diff view -- look for the text input box that opens below the target line. The review submission dialog has radio buttons for Approve, Request Changes, and Comment with clear labels. Increase diff view font size with Ctrl+= so line numbers and change annotations are easier to read.

      -

      Alex: Keep the teaching thread moving. Start with 8. Merging Pull Requests: Who can merge: Repository maintainers, or contributors with write access. Think of it like entering a new building: first you find the lobby, then the room, then the door you actually need.

      +

      Alex: Keep the teaching thread moving. Keep the learner anchored in Linking to Specific Lines of Code. Share precise references to code by including line numbers in GitHub URLs. A good GitHub workflow is like a well-run meeting: everyone knows the topic, the next action, and who has the floor.

      +

      Jamie: Let's pause on Syntax. What should a learner take away from it?

      +

      Alex: Start with Syntax. There is something to understand, something to try, and something that proves the try worked.

      +

      Alex: The practical takeaway is this. Single line: github.com/owner/repo/blob/main/file.js L42. Line range: github.com/owner/repo/blob/main/file.js L42-L58.

      +

      Jamie: Let's pause on How to create these links. What should a learner take away from it?

      +

      Alex: Start with How to create these links: Line numbers are links announced as "Line 42 link" (or similar). The next useful detail is this: They're in the left margin of the code view.

      +

      Alex: First, navigate to a file on GitHub. Then, click the line number (in screen readers: navigate to the line and activate the number link). After that, hold Shift and click another line number to select a range. Finally, copy the URL from your browser - the line numbers are automatically included. Think of it as a rail line: each stop confirms you are still on the right route before the next one.

      -

      Jamie: Let's pause on Prerequisites for Merging. What should a learner take away from it?

      -

      Alex: Here is the plain-English version of Prerequisites for Merging. Changing the base branch: If the PR was opened against the wrong base branch, you can change it from the PR detail view in VS Code. Put another way, scroll to the base branch field in the PR detail view and activate the dropdown to select a different target branch.

      -

      Alex: First, all required reviews are approved. Then, all CI checks pass (green checkmarks). After that, no merge conflicts exist. Finally, branch is up to date with base branch (main). Treat it like a recipe: do not add the next ingredient until the previous one is actually in the bowl.

      -

      Jamie: Let's pause on Method 1: PR Detail View. What should a learner take away from it?

      -

      Alex: Start with Method 1: PR Detail View. There is something to understand, something to try, and something that proves the try worked.

      -

      Alex: First, open the PR in VS Code. Then, scroll to the bottom of the PR detail view. After that, find "Merge Pull Request" button. Finally, press Enter. It is a checklist, but a meaningful one: every item creates evidence that the next step is safe.

      -

      Jamie: Before we leave Method 1: PR Detail View, what is the practical point?

      -

      Alex: First, choose merge type (see below). It is like walking a hallway with named doors: read the sign, enter the right room, then confirm where you landed.

      -

      Jamie: What is the teaching move inside Method 2: Command Palette?

      -

      Alex: Start with Method 2: Command Palette. There is something to understand, something to try, and something that proves the try worked.

      -

      Alex: First, ctrl+Shift+P (Mac: Cmd+Shift+P). Then, type "GitHub Pull Requests: Merge". After that, select "GitHub Pull Requests: Merge Pull Request". Finally, choose the PR from the list. It is like walking a hallway with named doors: read the sign, enter the right room, then confirm where you landed.

      -

      Jamie: If someone only remembers one thing from Method 2: Command Palette, what should it be?

      -

      Alex: First, select merge type. The rhythm is simple: orient, act, verify, then continue.

      +

      Jamie: Let's pause on Permalinks - Stable Links That Never Break. What should a learner take away from it?

      +

      Alex: Here is the plain-English version of Permalinks - Stable Links That Never Break. When you link to code on GitHub using a branch name (main, develop), that link can break if the code changes or the file moves. Put another way, permalinks use the commit SHA instead of the branch name, creating a permanent snapshot link.

      +

      Jamie: Let's pause on How to create a permalink. What should a learner take away from it?

      +

      Alex: This is where How to create a permalink becomes real: shortcut: Y = "Yank permalink" (borrows from Vim terminology). The workshop is closer to rehearsal than lecture. You hear the move, try the move, and then check what changed.

      +

      Alex: First, view any file on GitHub. Then, press Y while viewing the file - the URL changes from /blob/main/file.js to /blob/a1b2c3d4./file.js. After that, copy the new URL - it now points to that specific commit. It is a checklist, but a meaningful one: every item creates evidence that the next step is safe.

      +

      Jamie: Let's pause on Converting Issues to Discussions. What should a learner take away from it?

      +

      Alex: Keep the learner anchored in Converting Issues to Discussions. Not every issue is a bug or feature request. This is the part to say slowly: Some are questions, proposals, or open-ended conversations.

      -

      Alex: Keep the teaching thread moving. The reason Merge Types matters is that the merge type selector is a dropdown or radio group. That gives the learner a simple foothold: navigate with Arrow keys, confirm with Enter. The interface gets friendlier when it stops being a wall of controls and starts being a set of named places.

      -

      Jamie: Let's pause on Which merge type to use. What should a learner take away from it?

      -

      Alex: Start with Which merge type to use. There is something to understand, something to try, and something that proves the try worked.

      -

      Alex: The practical takeaway is this. Check the repository's CONTRIBUTING.md for guidance. If unsure, use Merge Commit (the default and safest option).

      -

      Jamie: Let's pause on After Merging. What should a learner take away from it?

      -

      Alex: Start with After Merging. There is something to understand, something to try, and something that proves the try worked.

      -

      Alex: First, the PR closes automatically. Then, the feature branch can be deleted (VS Code prompts: "Delete branch?"). After that, recommended: switch back to main and pull the merged changes. Treat it like a recipe: do not add the next ingredient until the previous one is actually in the bowl.

      +

      Alex: Keep the teaching thread moving. Start with When to convert. There is something to understand, something to try, and something that proves the try worked.

      +

      Alex: The practical takeaway is this. Questions that don't require a code change ("How do I configure X?"). Proposals that need community feedback before becoming actionable. General discussion about the project's direction. Show-and-tell or community showcases.

      +

      Jamie: Let's pause on How to convert an issue to a discussion. What should a learner take away from it?

      +

      Alex: Start with How to convert an issue to a discussion: All comments and history are preserved. The next useful detail is this: The issue is closed and replaced with a link to the new discussion.

      +

      Alex: First, open the issue. Then, in the right sidebar, click "Convert to discussion". After that, select which discussion category it belongs in. Think of it as a rail line: each stop confirms you are still on the right route before the next one.

      +

      Alex: Keep the teaching thread moving. Here is the plain-English version of Team Mentions - Notify a Whole Group. In organizations, you can mention entire teams instead of individuals: @org-name/team-name. Put another way, example: @github/accessibility notifies everyone on GitHub's accessibility team. It is like learning a transit route. The names of the stops matter because they tell you whether you are still going the right direction.

      -

      Jamie: Let's pause on Switching to main and pulling. What should a learner take away from it?

      -

      Alex: This is where Switching to main and pulling becomes real: (Mac users: use Cmd+Shift+P instead of Ctrl+Shift+P).

      -

      Alex: Treat examples as spoken recipes, not decorations. You may hear something like Ctrl+Shift+P → "Git: Checkout to." → select "main"; Ctrl+Shift+P → "Git: Pull". Read the command, understand what it changes, then run it only when the repository state matches the lesson.

      -

      Jamie: Let's pause on Deleting the Feature Branch. What should a learner take away from it?

      -

      Alex: Keep the learner anchored in Deleting the Feature Branch. After merging, the feature branch is no longer needed. This is the part to say slowly: Web alternative (github.com) - merging. A good GitHub workflow is like a well-run meeting: everyone knows the topic, the next action, and who has the floor.

      -

      Alex: First, ctrl+Shift+P (Mac: Cmd+Shift+P). Then, type "git delete branch". After that, select "Git: Delete Branch.". Finally, choose the merged branch. It is like walking a hallway with named doors: read the sign, enter the right room, then confirm where you landed.

      -

      Jamie: Before we leave Deleting the Feature Branch, what is the practical point?

      -

      Alex: First, open the PR's Conversation tab. Then, scroll to the merge button at the bottom. After that, click the dropdown arrow to choose a merge strategy (Squash, Rebase, or Merge commit). Finally, click Merge pull request, then Confirm merge. The rhythm is simple: orient, act, verify, then continue.

      -

      Alex: Treat examples as spoken recipes, not decorations. You may hear something like Merge with default strategy; gh pr merge 42; Squash and merge, then delete the branch; gh pr merge 42 --squash --delete-branch; Enable auto-merge (merges when checks pass); gh pr merge 42 --auto --squash. Read the command, understand what it changes, then run it only when the repository state matches the lesson.

      -

      Jamie: Let's pause on Learning Cards: Merging Pull Requests. What should a learner take away from it?

      -

      Alex: Start with Learning Cards: Merging Pull Requests. There is something to understand, something to try, and something that proves the try worked.

      -

      Alex: The practical takeaway is this. The merge type selector (Merge Commit, Squash, Rebase) is announced as a dropdown or radio group -- use Arrow keys to move between options and Enter to confirm; if unsure, choose Merge Commit (the default and safest option). After merging, VS Code prompts "Delete branch?" as a notification -- press Alt+N to focus the notification and Enter to confirm, then run Ctrl+Shift+P then "Git: Checkout to" and select main to return to your default branch. Confirm the merge succeeded by pressing F6 to reach the Status Bar and verifying it now reads main instead of the feature branch name. The merge button at the bottom of the PR detail view includes a dropdown arrow for selecting merge type -- at high zoom, widen the editor pane so the button label and dropdown are not truncated. After merging, the PR detail view header changes from "Open" (green badge) to "Merged" (purple badge) -- verify this colour/label change before deleting the branch. When switching back to main, the branch name in the bottom-left Status Bar updates immediately -- confirm it reads main before pulling new changes with Ctrl+Shift+P then "Git: Pull".

      +

      Jamie: Let's pause on Why this matters. What should a learner take away from it?

      +

      Alex: This is where Why this matters becomes real: permission: You can only mention teams you have visibility to. That matters in practice: Public teams in public orgs can be mentioned by anyone.

      +

      Alex: The practical takeaway is this. You don't need to know who's on a team - just mention the team. Teams can subscribe to notifications as a group. CODEOWNERS files use team mentions for automatic reviewer assignment.

      +

      Alex: Keep the teaching thread moving. Keep the learner anchored in Collapsible Sections in Markdown. Keep long issue descriptions or PR descriptions scannable by hiding details in collapsible sections.

      +

      Jamie: Let's pause on Use for. What should a learner take away from it?

      +

      Alex: The reason Use for matters is that accessibility note: Collapsible sections are announced as "disclosure triangles" or "expandable" regions by most screen readers. That gives the learner a simple foothold: the summary text is always visible.

      +

      Alex: The practical takeaway is this. Long error messages or logs. Optional context that most readers don't need. Large screenshots or code samples. Step-by-step troubleshooting instructions.

      -

      Alex: Keep the teaching thread moving. Start with "No pull requests found": Issue: The GitHub Pull Requests panel is empty.

      -

      Jamie: Let's pause on Solutions. What should a learner take away from it?

      -

      Alex: Start with Solutions. There is something to understand, something to try, and something that proves the try worked.

      -

      Alex: First, verify you're signed in: Ctrl+Shift+P (Mac: Cmd+Shift+P) → "GitHub Pull Requests: Sign in". Then, check you have a folder open containing a Git repository. After that, refresh the panel: Ctrl+Shift+P (Mac: Cmd+Shift+P) → "GitHub Pull Requests: Refresh Pull Requests List". Treat it like a recipe: do not add the next ingredient until the previous one is actually in the bowl.

      -

      Jamie: Before we leave Solutions, what is the practical point?

      -

      Alex: First, verify you've pushed your branch: Ctrl+Shift+P (Mac: Cmd+Shift+P) → "Git: Push". Then, check you have write access to the repository. After that, ensure your branch is ahead of the base branch (has new commits). It is a checklist, but a meaningful one: every item creates evidence that the next step is safe.

      +

      Alex: Keep the teaching thread moving. Start with Co-Authored Commits: Credit multiple people for a single commit using the Co-authored-by trailer in your commit message. Think of it like entering a new building: first you find the lobby, then the room, then the door you actually need.

      +

      Alex: A solid Git habit is to know which branch you are on, what changed, and what confirmation you expect before you run the next command.

      +

      Jamie: Before we leave Why this matters, what is the practical point?

      +

      Alex: Here is the plain-English version of Why this matters. When viewing a commit with co-authors on GitHub, screen readers announce "Co-authored-by" in the commit details.

      +

      Alex: The practical takeaway is this. Pair programming - both people get credit in the Git history. Crediting someone who provided the solution but didn't write the code. GitHub recognizes these trailers and shows all co-authors on the commit.

      +

      Alex: Keep the teaching thread moving. This is where Understanding Watch, Star, and Fork becomes real: three ways to interact with a repository - each means something different.

      -

      Jamie: Let's pause on "Authentication failed". What should a learner take away from it?

      -

      Alex: Keep the learner anchored in "Authentication failed". Issue: VS Code can't connect to GitHub.

      -

      Jamie: What is the teaching move inside Solutions?

      -

      Alex: First, sign out and sign back in: Ctrl+Shift+P (Mac: Cmd+Shift+P) → "GitHub Pull Requests: Sign out" → then sign in again. Then, check your GitHub Personal Access Token (see Appendix D: Git Authentication). After that, verify network connection. The rhythm is simple: orient, act, verify, then continue.

      -

      Jamie: Let's pause on Try It: Review a PR from VS Code. What should a learner take away from it?

      -

      Alex: Start with Try It: Review a PR from VS Code: Time: 3 minutes What you need: VS Code with GitHub Pull Requests extension installed and signed in. The next useful detail is this: You just reviewed a pull request entirely from VS Code.

      -

      Alex: First, open the PR view - Press Ctrl+Shift+P → type Pull Requests: Focus on GitHub Pull Requests View → Enter. Then, find a PR - Navigate the tree with arrow keys. Expand a PR to see its changed files. After that, open a diff - Press Enter on a changed file. The diff editor opens. Finally, use the Accessible Diff Viewer - Press F7 to jump to the first change. Your screen reader announces what was added or removed. Press F7 again to move to the next change. Think of it as a rail line: each stop confirms you are still on the right route before the next one.

      -

      Jamie: Before we leave Try It: Review a PR from VS Code, what is the practical point?

      -

      Alex: First, leave a comment - Position your cursor on a line you want to comment on, then press Ctrl+Shift+P → Pull Request: Add Comment on Current Diff Line. Type a brief, constructive comment and submit. Treat it like a recipe: do not add the next ingredient until the previous one is actually in the bowl.

      +

      Jamie: Let's pause on Watch settings. What should a learner take away from it?

      +

      Alex: Keep the learner anchored in Watch settings. Pro tip: Star repos for discovery; Watch repos you actively contribute to.

      +

      Alex: The practical takeaway is this. All activity - every issue, PR, and discussion. Participating (default) - only threads you comment on or are @mentioned in. Releases only - just new releases. Ignore - unsubscribe completely.

      +

      Alex: Keep the teaching thread moving. The reason CODEOWNERS - Automatic Reviewer Assignment matters is that the CODEOWNERS file automatically requests reviews from specific people or teams when files in their area are changed. That gives the learner a simple foothold: location.github/CODEOWNERS in your repository. The interface gets friendlier when it stops being a wall of controls and starts being a set of named places.

      +

      Jamie: Let's pause on How it works. What should a learner take away from it?

      +

      Alex: Start with How it works. There is something to understand, something to try, and something that proves the try worked.

      +

      Alex: First, someone opens a PR that changes files in /docs/. Then, GitHub automatically requests a review from @org-name/docs-team. After that, the PR can't be merged until the required review is approved (if branch protection requires it). Think of it as a rail line: each stop confirms you are still on the right route before the next one.

      -

      Alex: Keep the teaching thread moving. Here is the plain-English version of Conducting Pull Request Reviews with a Screen Reader. This guide is focused entirely on the reviewer experience - navigating diffs, reading changes, leaving comments, and submitting a review - using only your keyboard and screen reader. Put another way, for the full pull request lifecycle (opening PRs, merge options, conflict resolution), see Working with Pull Requests. It is like learning a transit route. The names of the stops matter because they tell you whether you are still going the right direction.

      -

      Jamie: What should feel predictable before the first live session starts?

      -

      Alex: This is where Workshop Recommendation (Chapter 15 / Challenge 12) becomes real: chapter 15 is the code review chapter focused on practicing constructive feedback. That matters in practice: It supports Challenge 12: Review Like a Pro.

      -

      Alex: The practical takeaway is this. There are 2 guided challenges. Automation check: none (review quality is subjective and human-focused). The evidence is issue comment with summary of review and feedback posted. The pattern is navigate diff, comment on specifics, submit verdict.

      -

      Jamie: Let's pause on Challenge 12 Practice Set. What should a learner take away from it?

      -

      Alex: Start with Challenge 12 Practice Set. There is something to understand, something to try, and something that proves the try worked.

      -

      Alex: First, review a practice PR and leave 2-3 inline comments - read the diff line by line, find specific items to comment on, and post constructive feedback. Then, submit a formal review verdict - complete your review by choosing approve, request changes, or comment only. It is like walking a hallway with named doors: read the sign, enter the right room, then confirm where you landed.

      +

      Alex: Keep the teaching thread moving. Start with Use for. There is something to understand, something to try, and something that proves the try worked.

      +

      Alex: The practical takeaway is this. Ensuring domain experts review specialized code. Distributing review responsibilities. Preventing changes from being merged without appropriate oversight.

      +

      Jamie: Let's pause on GitHub Sponsors. What should a learner take away from it?

      +

      Alex: This is where GitHub Sponsors becomes real: support open source maintainers financially through GitHub Sponsors. That matters in practice: If a project you use has a "Sponsor" button, consider supporting them.

      +

      Alex: Keep the teaching thread moving. Start with How it works. There is something to understand, something to try, and something that proves the try worked.

      +

      Alex: The practical takeaway is this. Maintainers set up a Sponsors profile. You can sponsor with a monthly recurring amount or one-time payment. GitHub doesn't take a fee (as of 2026).

      +
      +

      Jamie: Let's pause on Why sponsor. What should a learner take away from it?

      +

      Alex: Start with Why sponsor. There is something to understand, something to try, and something that proves the try worked.

      +

      Alex: The practical takeaway is this. Open source maintainers often work for free in their spare time. Your sponsorship helps them dedicate more time to the project. Many maintainers offer perks to sponsors (early access, prioritized issues, etc.).

      +

      Jamie: Let's pause on How to sponsor. What should a learner take away from it?

      +

      Alex: Start with How to sponsor. There is something to understand, something to try, and something that proves the try worked.

      +

      Alex: First, visit a repository with a "Sponsor" button. Then, click the button. After that, choose a sponsorship tier. Finally, complete payment through GitHub Sponsors. Think of it as a rail line: each stop confirms you are still on the right route before the next one.

      +

      Jamie: Let's pause on Advanced Markdown Features. What should a learner take away from it?

      +

      Alex: Here is the plain-English version of Advanced Markdown Features. GitHub supports several powerful Markdown features beyond the basics.

      -

      Jamie: Let's pause on Practice 12.1 Step-by-Step: Review a PR and Leave Inline Comments. What should a learner take away from it?

      -

      Alex: The reason Practice 12.1 Step-by-Step: Review a PR and Leave Inline Comments matters is that navigate a PR diff using screen reader-friendly tools and post 2-3 specific, constructive inline comments. That gives the learner a simple foothold: GitHub.com (Files changed tab of a PR) or VS Code with the GitHub Pull Requests extension.

      -

      Alex: The practical takeaway is this. On GitHub.com: Use heading navigation to jump between files (H in NVDA). Each file header is a heading. Within a file, use arrow keys to move line by line. In VS Code: Press F7 to open the Accessible Diff Viewer (see Chapter 15, Part 1). Use F7/Shift+F7 to move between changes. Typos or grammar issues. Unclear headings or link text.

      -

      Alex: First, open your Learning Room repository on GitHub.com and navigate to the Pull requests tab. Then, find a classmate's open PR (from Chapter 6, 7, or 14). Open it. After that, activate the Files changed tab. This shows the diff - lines added in green, lines removed in red. Finally, navigate the diff. The rhythm is simple: orient, act, verify, then continue.

      -

      Jamie: Before we leave Practice 12.1 Step-by-Step: Review a PR and Leave Inline Comments, what is the practical point?

      -

      Alex: First, read through the changes carefully. Look. Then, to leave an inline comment on GitHub.com: activate the + button that appears to the left of a line number when you hover or Tab to it. (Screen reader users: this button may be announced as "Add a comment to this line.") Type your comment in the text box that. After that, post 2-3 inline comments. Each comment should be. Finally, examples of good inline comments. Think of it as a rail line: each stop confirms you are still on the right route before the next one.

      -

      Jamie: Let's pause on Practice 12.2 Step-by-Step: Submit a Formal Review Verdict. What should a learner take away from it?

      -

      Alex: Start with Practice 12.2 Step-by-Step: Submit a Formal Review Verdict: Complete your review by selecting a verdict that tells the author what action to take next. The next useful detail is this: GitHub.com (the same PR you reviewed in 14.1). Think of it like entering a new building: first you find the lobby, then the room, then the door you actually need.

      -

      Alex: The practical takeaway is this. Comment - general feedback, no explicit approval or rejection. Approve - you think the PR is ready to merge. Request changes - you found something that should be fixed before merging. If the PR has clear documentation with only minor suggestions, choose Approve.

      -

      Alex: First, after posting your inline comments, scroll to the top of the Files changed tab. Then, activate the Review changes button (at the top-right of the files changed area, or use heading navigation). After that, a dropdown opens with three options. Finally, choose the verdict that matches your review. Think of it as a rail line: each stop confirms you are still on the right route before the next one.

      -

      Jamie: Before we leave Practice 12.2 Step-by-Step: Submit a Formal Review Verdict, what is the practical point?

      -

      Alex: First, write a brief summary in the review body (1-2 sentences). Example: "Clear improvement to the shortcut table. Two minor suggestions for link text clarity.". Then, activate Submit review. Treat it like a recipe: do not add the next ingredient until the previous one is actually in the bowl.

      -

      Jamie: Why is the evidence prompt part of the teaching, not just grading?

      -

      Alex: Here is the plain-English version of Completing Challenge 12: Submit Your Evidence. Open your assigned Challenge 12 issue and post a completion comment. Put another way, close your Challenge 12 issue when done.

      +

      Alex: Keep the teaching thread moving. This is where Mermaid Diagrams becomes real: graph TD A[User opens issue] -- B{Is it a bug?} B -- Yes C[Label: bug] B -- No D[Label: enhancement]. The workshop is closer to rehearsal than lecture. You hear the move, try the move, and then check what changed.

      +

      Jamie: Let's pause on 12. Finding More Contributions. What should a learner take away from it?

      +

      Alex: Keep the learner anchored in 12. Finding More Contributions. After the workshop, use these resources to find your next open source contribution.

      +

      Alex: Keep the teaching thread moving. The reason 14b. Learning Pathways matters is that not sure where to start after the workshop?

      -

      Alex: The practical takeaway is this. Student can navigate PR diffs with a screen reader. Student can post inline comments on specific lines of a diff. Student can write constructive, specific feedback that helps the author improve. Student can submit a formal review verdict.

      -

      Jamie: Let's pause on If You Get Stuck. What should a learner take away from it?

      -

      Alex: Keep the learner anchored in If You Get Stuck. Continue learning: The GitHub Skills courses Review Pull Requests and Code Review with GitHub Copilot cover review workflows and AI-assisted code review. This is the part to say slowly: See Appendix Z for the full catalog.

      -

      Alex: First, files Changed tab will not open? Reload the PR page and retry. Make sure you are on the PR page, not the issue page. Then, cannot find the inline comment button? Tab through the line controls in the diff. The button may be announced as "Add a comment" or have a + label. If you cannot find it, use the "Review changes" button at the top to add a general comment instead. After that, not sure what to comment on? Focus on clarity: is every heading descriptive? Is every link meaningful? Are steps complete? Are keyboard shortcuts correct? Finally, review verdict button not working? Make sure you have at least one comment or have written summary text. Try reloading the page. It is like walking a hallway with named doors: read the sign, enter the right room, then confirm where you landed.

      -

      Jamie: Let's pause on If You Get Stuck. What should a learner take away from it?

      -

      Alex: First, submitting the review fails? Check that you are not in draft mode and have at least read access to the repo. Then, ask facilitator to model one inline comment and one verdict submission. After that, finished but not sure you did it right? Compare your work against the Challenge 12 reference solution. The rhythm is simple: orient, act, verify, then continue.

      -

      Alex: Keep the teaching thread moving. The reason Learning Moment matters is that specific, kind feedback helps authors improve and builds trust in the community. That gives the learner a simple foothold: every comment you write is practice for the professional code review you will do on real projects. The interface gets friendlier when it stops being a wall of controls and starts being a set of named places.

      +

      Jamie: What is the safe way to learn from that example?

      +

      Alex: Start with 16. Your Workshop Documentation - Offline Reference: Every guide from this workshop lives in your fork. The next useful detail is this: Clone your fork once and the complete documentation works offline - no internet required.

      +

      Alex: Treat examples as spoken recipes, not decorations. You may hear something like git clone https://github.com/[your-username]/accessibility-agents.git. Read the command, understand what it changes, then run it only when the repository state matches the lesson.

      +

      Alex: Keep the teaching thread moving. Here is the plain-English version of Quick Navigation. Next: Appendix Y: Workshop Materials Back: Appendix W: GitHub Pages Teaching chapter: All chapters. It is like learning a transit route. The names of the stops matter because they tell you whether you are still going the right direction.

      -

      Jamie: What is the teaching move inside Learning Pattern Used in This Chapter?

      -

      Alex: First, read the full diff before commenting (understand the author's intent first). Then, find specific items to comment on (lines, phrases, missing steps). After that, write comments that help, not just criticize (suggest improvements, note what works). Finally, choose a verdict that matches the substance of your feedback. Think of it as a rail line: each stop confirms you are still on the right route before the next one.

      -

      Jamie: If someone only remembers one thing from Learning Pattern Used in This Chapter, what should it be?

      -

      Alex: First, summarize your overall impression in 1-2 sentences. Treat it like a recipe: do not add the next ingredient until the previous one is actually in the bowl.

      -

      Alex: Keep the teaching thread moving. Here is the plain-English version of Before starting this chapter, verify you have completed. Estimated time for this chapter: 1 hour (including exercises).

      -

      Alex: The practical takeaway is this. [ ] Chapter 6: Working with Pull Requests - Understand PR structure, diffs, and comment workflows. [ ] Chapter 13: GitHub Copilot - VS Code installed and configured. [ ] Screen Reader Setup - NVDA, JAWS, or VoiceOver installed and ready to use. [ ] Access to at least one pull request to review (your own fork or a practice repo).

      -

      Jamie: Let's pause on Two Environments for Code Review. What should a learner take away from it?

      -

      Alex: This is where Two Environments for Code Review becomes real: you can review pull requests in two places - each with different strengths. That matters in practice: Both environments give you full keyboard and screen reader access.

      +

      Jamie: What should people carry with them after this?

      +

      Alex: Carry the map. Know what page or tool you are in, know which action you are taking, and know what confirmation should follow. If the confirmation is missing, pause. That pause is not wasted time; it is professional judgment.

      +

      Jamie: That is a better way to say it than just follow the steps.

      +

      Alex: Right. Steps matter, but understanding wins. That is episode 38. Next in the series is episode 39, where we keep building the same contributor muscles.

      +
      +
      -

      Jamie: Let's pause on About Learning Cards in This Chapter. What should a learner take away from it?

      -

      Alex: Keep the learner anchored in About Learning Cards in This Chapter. Each review step includes expandable learning cards for different interaction styles. This is the part to say slowly: Open the one that matches how you work. A good GitHub workflow is like a well-run meeting: everyone knows the topic, the next action, and who has the floor.

      -

      Alex: Treat examples as spoken recipes, not decorations. You may hear something like View the full PR diff in your terminal; gh pr diff 42; View PR details (description, status, checks); gh pr view 42; Checkout the PR branch locally for testing; gh pr checkout 42; Approve the PR; gh pr review 42 --approve --body "Heading hierarchy looks. Read the command, understand what it changes, then run it only when the repository state matches the lesson.

      -

      Jamie: Let's pause on Good News: Modern Interface is Default. What should a learner take away from it?

      -

      Alex: The reason Good News: Modern Interface is Default matters is that as of January 2026, GitHub's improved Files Changed experience is enabled by default. That gives the learner a simple foothold: the instructions below assume you have the modern interface (which you do).

      -

      Jamie: Let's pause on Step 1: Reach the Files Changed Tab. What should a learner take away from it?

      -

      Alex: Start with Step 1: Reach the Files Changed Tab: Click the Files changed tab at the top of the PR page. The next useful detail is this: The tab label shows the number of changed files (e.g., "Files changed 4").

      -

      Alex: First, the PR tabs (Conversation, Commits, Checks, Files changed) are across the top of the PR page. At high zoom they may wrap to multiple lines. Then, the Files changed tab includes a badge with the number of changed files. This badge uses text (not colour alone) so it is visible in all themes. After that, after clicking Files changed, the diff page loads. At high zoom, the file tree panel on the left may collapse automatically. Click the file tree toggle (a small panel icon) or press T to toggle it back. Finally, added lines use a green background; removed lines use red. In high contrast browser settings (Windows: Settings Accessibility Contrast themes), these colours map to strong border indicators. Think of it as a rail line: each stop confirms you are still on the right route before the next one.

      -

      Jamie: Before we leave Step 1: Reach the Files Changed Tab, what is the practical point?

      -

      Alex: First, use Ctrl++ to zoom the browser if the diff text is too small, and Ctrl+- to zoom out. Treat it like a recipe: do not add the next ingredient until the previous one is actually in the bowl.

      -

      Alex: Treat examples as spoken recipes, not decorations. You may hear something like Press D → navigate to "Pull request navigation tabs" landmark; Press → or Tab → find "Files changed" link → Enter. Read the command, understand what it changes, then run it only when the repository state matches the lesson.

      +

      69. Episode 42: Accessing Workshop Materials

      +

      Downloading the repository, reading offline, keeping updated, audio format.

      +

      Based on: Appendix Y: Accessing Workshop Materials

      +

      Audio and transcript are being regenerated for this episode.

      +
      +Read Transcript - Episode 42: Accessing Workshop Materials + +

      Transcript

      +

      Alex: This is Git Going with GitHub, episode 42: Accessing Workshop Materials. I am Alex. By the end of this episode, Accessing Workshop Materials should feel less like a wall of GitHub words and more like a set of moves you can trust.

      +

      Jamie: And I am Jamie. I am here for the practical questions: what should I listen for, what can go wrong, and what is the next calm move?

      -

      Jamie: Let's pause on Step 2: Use the File Tree to Orient Yourself. What should a learner take away from it?

      -

      Alex: Here is the plain-English version of Step 2: Use the File Tree to Orient Yourself. The file tree panel lists every changed file. Put another way, before reading any diff, scan this list to understand the scope of the PR.

      -

      Jamie: Let's pause on What to listen for / look for. What should a learner take away from it?

      -

      Alex: This is where What to listen for / look for becomes real: low vision users (zoom, high contrast). The workshop is closer to rehearsal than lecture. You hear the move, try the move, and then check what changed.

      -

      Alex: The practical takeaway is this. How many files changed? Which areas of the codebase are affected? Are there unexpected files (generated files, lock files, configuration changes)?

      -

      Alex: First, the file tree shows each filename with a colour-coded bar indicating lines added (green) and removed (red). In high contrast mode, these bars may be less visible - the +N / -N text badge next to each file is the reliable indicator. Then, at high zoom, long file paths truncate. Hover over a truncated name to see the full path in a tooltip. After that, if the file tree panel is too narrow at high zoom, drag its right edge to widen it, or toggle it off and use heading navigation (H key) to move between file diffs. It is a checklist, but a meaningful one: every item creates evidence that the next step is safe.

      -

      Jamie: Let's pause on Step 3: Navigate Between File Diffs. What should a learner take away from it?

      -

      Alex: Keep the learner anchored in Step 3: Navigate Between File Diffs. Each changed file in the main area is an h3 heading containing the filename. This is the part to say slowly: Scroll through the page or click a filename in the file tree on the left.

      -

      Alex: Treat examples as spoken recipes, not decorations. You may hear something like Press 3 to jump file-by-file through the diff; Listen for: "learning-room/docs/keyboard-shortcuts.md - collapsed" or "expanded"; Press Enter or Space to expand a collapsed file. Quick Nav H or VO+Cmd+H to jump file-by-file through the diff; Listen for: "learning-room/docs/keyboard-shortcuts.md - collapsed" or "expanded"; VO+Space to expand a collapsed file. Read the command, understand what it changes, then run it only when the repository state matches the lesson.

      +

      Alex: Today we are working on this: Downloading the repository, reading offline, keeping updated, audio format. I want the learner to leave with a mental map, not just a remembered path through buttons.

      +

      Jamie: So the goal is understanding first, then action, then confirmation.

      +

      Alex: Right. We are building a rhythm: orient yourself, take one intentional action, then verify what changed before moving on.

      -

      Jamie: Let's pause on Step 4: Read a Diff. What should a learner take away from it?

      -

      Alex: The reason Step 4: Read a Diff matters is that low vision users (zoom, high contrast). That gives the learner a simple foothold: screen reader users - VoiceOver (macOS).

      -

      Alex: The practical takeaway is this. Green highlighted lines (with a +) = lines added. Red highlighted lines (with a -) = lines removed. Plain/white lines = unchanged context. Use Ctrl+F to search within the page for specific text in the diff.

      -

      Alex: First, colour is not the only indicator. Every added line has a + character in the gutter; every removed line has a -. These text characters are reliable regardless of colour settings. Then, at high zoom, long lines of code wrap. The +/- gutter character stays at the beginning of the first line, so look left to determine the change type. After that, use Ctrl+F (browser find) to search for specific text across the entire diff page. Finally, if the diff is split view (side by side), it may be very wide at high zoom. Switch to unified diff mode: click the gear icon in the Files Changed toolbar and select "Unified" - this shows old and new in a single column. The rhythm is simple: orient, act, verify, then continue.

      -

      Jamie: Before we leave Step 4: Read a Diff, what is the practical point?

      -

      Alex: First, high contrast themes in Windows (Settings Accessibility Contrast themes) make the +/- lines use bold border patterns instead of subtle colour shading. Think of it as a rail line: each stop confirms you are still on the right route before the next one.

      -

      Alex: Treat examples as spoken recipes, not decorations. You may hear something like Press T to jump to the diff table then Insert+Space (Focus Mode); Press Down Arrow to move through lines one at a time; Press Ctrl+Alt+Right Arrow to read across columns: line number, change type, code content. Press T to jump to the diff table then Insert+Z (Virtual PC Cursor off); Press Down Arrow to move through lines; Press Ctrl+Alt+Right Arrow for column-by-column reading. Read the command, understand what it changes, then run it only when the repository state matches the lesson.

      -

      Jamie: Let's pause on What each line announces / shows. What should a learner take away from it?

      -

      Alex: Start with What each line announces / shows: If the code on a line is very long, the screen reader will read the full line. The next useful detail is this: For minified or generated files, consider collapsing the file in the tree and skipping it.

      -

      Alex: The practical takeaway is this. Added lines: "+ [code content]" - or announced as "inserted". Removed lines: "- [code content]" - or announced as "deleted". Context lines: code without a + or -.

      -

      Jamie: Let's pause on Step 5: Place an Inline Comment. What should a learner take away from it?

      -

      Alex: Here is the plain-English version of Step 5: Place an Inline Comment. When you have a specific observation about a particular line, place an inline comment directly on it. Put another way, screen reader users (VoiceOver - macOS). It is like learning a transit route. The names of the stops matter because they tell you whether you are still going the right direction.

      -

      Alex: First, hover your mouse over a line in the diff - a blue + (comment) button appears on the left. Then, click it to open the inline comment box. After that, type your comment. Finally, click "Start a review" (not "Add single comment" - see note below). Treat it like a recipe: do not add the next ingredient until the previous one is actually in the bowl.

      +

      Jamie: Okay, set the room for us. What are we walking into?

      +

      Alex: Start with How to Get, Read, and Keep These Documents: Why this appendix exists: The workshop content is available in multiple formats - Markdown source files, pre-built HTML pages, and a live GitHub Pages site. The next useful detail is this: This guide explains how to access each format, download materials for offline use, and keep your copy up to date.

      +

      Alex: The next layer is this. Start with Learning Cards: Accessing Workshop Materials. There is something to understand, something to try, and something that proves the try worked.

      +

      Alex: The practical anchors are these. The GitHub Pages site includes skip-to-content links and ARIA landmarks -- press D (NVDA) or R (JAWS) to jump to the main content landmark on any page. On GitHub.com, press T on the repository's main page to open the file finder -- type any filename to jump directly to it without navigating the file tree. After cloning the repository, open it in VS Code and use the Explorer panel (Ctrl+Shift+E) to browse the file tree with arrow keys. The HTML version in the html/ folder provides the most polished reading experience with styled, navigable pages that work offline in any browser. For reading Markdown source files, use VS Code's built-in preview (Ctrl+Shift+V) which renders headings, links, and code blocks in a formatted view. When downloading a ZIP from GitHub, the Code button and its dropdown appear near the top of the repository page -- look for the green button.

      +

      Jamie: What does the learner do first, second, and then after that?

      +

      Alex: This is where 1. Browsing Online (GitHub Pages) becomes real: if the facilitator has enabled GitHub Pages for this repository, the workshop materials are available as a website at a URL like. That matters in practice: Your facilitator will share the exact URL.

      +

      Alex: First, open the URL in your browser. Then, the landing page (index.html) is the workshop homepage - equivalent to the README. After that, use headings (H key in NVDA/JAWS browse mode) to navigate within any page. Finally, all internal links between chapters and appendices work - click any cross-reference to go directly to that page. It is a checklist, but a meaningful one: every item creates evidence that the next step is safe.

      +

      Jamie: Turn that into a path someone can follow.

      +

      Alex: First, bookmark the URL for quick access during the workshop. It is like walking a hallway with named doors: read the sign, enter the right room, then confirm where you landed.

      -

      Jamie: Let's pause on Placing a multi-line comment. What should a learner take away from it?

      -

      Alex: This is where Placing a multi-line comment becomes real: click and drag across multiple line numbers in the diff gutter to select a range. That matters in practice: A comment button appears for the selected range.

      -

      Jamie: Let's pause on Step 6: Read Existing Comments and Threads. What should a learner take away from it?

      -

      Alex: Keep the learner anchored in Step 6: Read Existing Comments and Threads. Inline comments from other reviewers appear as h3 headings within the diff table. This is the part to say slowly: Each thread shows: reviewer username, comment body, replies, a "Reply" link and resolution button.

      -

      Alex: Treat examples as spoken recipes, not decorations. You may hear something like Tab to the "Resolve conversation" button → Enter. Tab to the "Resolve conversation" button → VO+Space. Read the command, understand what it changes, then run it only when the repository state matches the lesson.

      -

      Jamie: Let's pause on Step 7: Submit Your Review. What should a learner take away from it?

      -

      Alex: The reason Step 7: Submit Your Review matters is that screen reader users (VoiceOver - macOS).

      -

      Alex: First, click the "Review changes" button (top-right of the Files Changed page or bottom of the PR). Then, a dialog opens with a summary text area and three radio buttons: Comment / Approve / Request changes. After that, optionally type an overall summary in the text area. Finally, select your verdict. The rhythm is simple: orient, act, verify, then continue.

      -

      Jamie: Before we leave Step 7: Submit Your Review, what is the practical point?

      -

      Alex: First, click "Submit review". Think of it as a rail line: each stop confirms you are still on the right route before the next one.

      +

      Jamie: What is the ordered workflow?

      +

      Alex: Keep the learner anchored in 2. Reading on GitHub.com. You can read every file directly on GitHub.com without downloading anything.

      +

      Alex: First, go to the repository page (your facilitator will share the link). Then, the README renders automatically as the repository homepage. After that, click into the docs/ folder to see all chapters and appendices. Finally, click any.md file - GitHub renders it as formatted text with headings, links, and code blocks. It is like walking a hallway with named doors: read the sign, enter the right room, then confirm where you landed.

      +

      Jamie: What would you say to someone who is already bracing for this to be too much?

      +

      Alex: Start with Navigating the repository with a screen reader. There is something to understand, something to try, and something that proves the try worked.

      +

      Alex: The parts worth keeping in working memory are these. File list: The repository file listing is a grid. Use T to jump to the file table, then arrow keys to navigate rows. File content: Once inside a file, GitHub renders the Markdown. Use H to navigate headings. Breadcrumbs: At the top of each file view, breadcrumb links show the path (e.g., Learning-Room / docs / 06-working-with-pull-requests.md). Use these to navigate back. Go to File shortcut: Press T on the repository's main page to open the file finder - type any filename to jump to it.

      +

      Alex: A solid navigation habit is to prove where you are before activating controls. Headings, landmarks, and the address bar are not trivia; they are your map.

      +

      Jamie: How do you keep commands from becoming magic words?

      +

      Alex: Start with Option A: Clone with Git (recommended): Cloning gives you a full copy of the repository that you can update later with git pull. The next useful detail is this: After cloning, every file (Markdown source, HTML output, scripts, learning-room materials) is on your computer. Think of it like entering a new building: first you find the lobby, then the room, then the door you actually need.

      +

      Alex: Treat examples as spoken recipes, not decorations. You may hear something like Clone the repository; git clone https://github.com/community-access/git-going-with-github.git; Move into the folder; cd Learning-Room. Read the command, understand what it changes, then run it only when the repository state matches the lesson.

      +

      Alex: A solid Git habit is to know which branch you are on, what changed, and what confirmation you expect before you run the next command.

      -

      Jamie: Let's pause on Step 8: Re-request Review (for Authors). What should a learner take away from it?

      -

      Alex: Start with Step 8: Re-request Review (for Authors): After you address review comments on your own PR. The next useful detail is this: Look in the right sidebar for the Reviewers section. Think of it like entering a new building: first you find the lobby, then the room, then the door you actually need.

      -

      Alex: Treat examples as spoken recipes, not decorations. You may hear something like Step 1: From your PR's Conversation tab, Quick Nav H or VO+Cmd+H to find the "Reviewers" heading in the sidebar; Step 2: Tab or Quick Nav B to find the re-request icon ("Re-request review") next to the reviewer's name; Step 3: VO+Space to activate - this. Read the command, understand what it changes, then run it only when the repository state matches the lesson.

      -

      Jamie: Let's pause on Learning Cards: Reviewing on GitHub.com. What should a learner take away from it?

      -

      Alex: Start with Learning Cards: Reviewing on GitHub.com. There is something to understand, something to try, and something that proves the try worked.

      -

      Alex: The practical takeaway is this. In the Files Changed tab, press T to jump to the diff table, then use Focus Mode (Insert+Space in NVDA, Insert+Z in JAWS) and Down Arrow to read line by line -- each added line starts with + and each removed line with -. To place an inline comment, navigate to the target line and press Tab or B to find the "Add a comment to this line" button; after typing your comment, choose "Start a review" (not "Add single comment") to batch all feedback into one notification. Submit your full review by pressing B repeatedly to find the "Review changes" button; the dialog contains a radio group (Comment / Approve / Request changes) navigable with Arrow keys, then Tab to "Submit review". Switch from split diff to unified diff (gear icon in the Files Changed toolbar then select "Unified") to show old and new code in a single column -- much easier to follow at high zoom than two side-by-side panes. The blue + comment button appears in the line gutter on hover; at high zoom it may be small -- use Ctrl++ to increase browser zoom and look just left of the line number column. The "Review changes" dialog uses clearly labeled radio buttons for the three verdict types; each label includes a brief description, and the currently selected option has a filled circle indicator visible in all themes.

      -

      Alex: Keep the teaching thread moving. This is where Reviewing in VS Code with the Accessible Diff Viewer becomes real: when you check out a branch locally, VS Code's diff editor offers the Accessible Diff Viewer - a purpose-built, line-by-line reading mode designed specifically for screen readers.

      +

      Jamie: How would you walk the room through that step by step?

      +

      Alex: Here is the plain-English version of Option B: Download ZIP (no Git required). If you do not have Git installed or prefer not to use the command line.

      +

      Alex: First, go to the repository page on GitHub.com. Then, press T to find the file finder, or navigate to the green Code button (it is a dropdown button near the top of the file listing). After that, activate the Code button - a dropdown menu opens. Finally, choose Download ZIP. Treat it like a recipe: do not add the next ingredient until the previous one is actually in the bowl.

      +

      Jamie: Give me the sequence, because order matters here.

      +

      Alex: First, save the file and extract it to a folder on your computer. It is a checklist, but a meaningful one: every item creates evidence that the next step is safe.

      +

      Alex: This is where the talk moves from concept to action. This is where Screen reader navigation for the Code dropdown becomes real: a ZIP download is a snapshot. That matters in practice: It does not update automatically - see Section 7 for how to get updates.

      +

      Alex: The room should hear these as checkpoints. The Code button is near the repository description, after the branch selector. In NVDA/JAWS browse mode, press B to jump between buttons until you reach "Code". Activate it with Enter or Space. The dropdown contains options including "Download ZIP" - arrow down to find it.

      +

      Jamie: What is the one idea that makes the next few steps less mysterious?

      +

      Alex: Keep the learner anchored in 4. Downloading Individual Files. To download a single file (for example, one chapter or the screen reader cheat sheet).

      +

      Alex: The useful habit is simple: orient first, act second, verify third. That pause before acting is part of the work.

      -

      Jamie: Let's pause on Opening a Diff in VS Code. What should a learner take away from it?

      -

      Alex: Keep the learner anchored in Opening a Diff in VS Code. If you have the GitHub Pull Requests extension. This is the part to say slowly: Without the extension, any git diff operation also opens the diff editor.

      -

      Alex: First, open the GitHub Pull Requests view (Explorer sidebar or Ctrl+Shift+P → "GitHub Pull Requests: View Pull Request"). Then, find the PR and open it - changed files appear in the file tree. After that, navigate to any file in the tree and press Enter to open its diff view. It is like walking a hallway with named doors: read the sign, enter the right room, then confirm where you landed.

      -

      Jamie: Let's pause on Learning Cards: VS Code Code Review. What should a learner take away from it?

      -

      Alex: The reason Learning Cards: VS Code Code Review matters is that low vision users (zoom, high contrast). That gives the learner a simple foothold: VS Code's diff editor works well at high zoom. The interface gets friendlier when it stops being a wall of controls and starts being a set of named places.

      -

      Alex: First, split view vs. inline: By default, VS Code shows diffs in a split (side-by-side) view. At high zoom this can be very cramped. Switch to inline mode: Ctrl+Shift+P then type "Toggle Inline View" in any diff editor. Inline mode shows old and new code in a single. Then, colour indicators: Added lines have a green gutter bar; removed lines have a red gutter bar. In high contrast themes, these use heavy solid borders that are visible even at extreme zoom levels. After that, change navigation: Press F7 to jump to the next change and Shift+F7 for the previous. Each change is highlighted with a visible focus box that moves with your position - much easier than scrolling at high zoom. Finally, minimap in diff view: The minimap (right edge) shows an overview of changes as coloured blocks. At high zoom the minimap may be too small to be useful - disable it via Settings if it adds visual noise. The rhythm is simple: orient, act, verify, then continue.

      -

      Jamie: Before we leave Learning Cards: VS Code Code Review, what is the practical point?

      -

      Alex: First, font size for diffs: Diff editors use your configured editor font size (editor.fontSize). Increase this in Settings (Ctrl+,) if the diff text is too small at your zoom level. Then, comment highlight: When you add a comment through the GitHub PR extension, the commented line gets a distinct background. In high contrast themes this is a solid colour band. Think of it as a rail line: each stop confirms you are still on the right route before the next one.

      -

      Jamie: Let's pause on Opening the PR for review. What should a learner take away from it?

      -

      Alex: Start with Opening the PR for review. There is something to understand, something to try, and something that proves the try worked.

      -

      Alex: First, press Ctrl+Shift+P, type "GitHub Pull Requests: View Pull Request". Then, the PR tree appears in the sidebar - navigate with Down Arrow. After that, each changed file is announced with its name and change summary. Finally, press Enter on a file to open its diff editor. Think of it as a rail line: each stop confirms you are still on the right route before the next one.

      -

      Jamie: Before we leave Opening the PR for review, what is the practical point?

      -

      Alex: First, the diff editor opens with the standard VS Code diff layout. Treat it like a recipe: do not add the next ingredient until the previous one is actually in the bowl.

      +

      Jamie: Let's pause on From GitHub.com. What should a learner take away from it?

      +

      Alex: The reason From GitHub.com matters is that for HTML files: Navigate to the html/ folder and download the.html version of any file using the same Raw → Save method. The interface gets friendlier when it stops being a wall of controls and starts being a set of named places.

      +

      Alex: First, navigate to the file in the repository. Then, click the Raw button (it appears above the file content, in the toolbar with "Preview", "Code", "Blame" buttons). After that, the browser shows the raw file content. Finally, press Ctrl+S (Windows/Linux) or Cmd+S (macOS) to save the page. The rhythm is simple: orient, act, verify, then continue.

      +

      Jamie: Give me the version that sounds like an instructor, not a manual.

      +

      Alex: Start with From a cloned repository: If you have already cloned the repo, every file is already on your computer. The next useful detail is this: Open the folder and copy whichever files you need.

      +

      Alex: Hold that next to this. Here is the plain-English version of 6. Offline Reading. Once you have downloaded or cloned the repository, you can read everything offline.

      -

      Jamie: Let's pause on Using the Accessible Diff Viewer. What should a learner take away from it?

      -

      Alex: Start with Using the Accessible Diff Viewer. There is something to understand, something to try, and something that proves the try worked.

      -

      Alex: First, in the diff editor, press F7 to open the Accessible Diff Viewer. Then, NVDA announces: "Changed lines X to Y in filename, Change 1 of N". After that, the viewer shows each change with "Removed:" and "Added:" labels. Finally, press F7 to move to the next change, Shift+F7 for previous. Treat it like a recipe: do not add the next ingredient until the previous one is actually in the bowl.

      -

      Jamie: Before we leave Using the Accessible Diff Viewer, what is the practical point?

      -

      Alex: First, press Escape when done to close the viewer. It is a checklist, but a meaningful one: every item creates evidence that the next step is safe.

      -

      Jamie: Let's pause on Placing a comment. What should a learner take away from it?

      -

      Alex: This is where Placing a comment becomes real: screen reader users (VoiceOver on macOS).

      -

      Alex: First, navigate to the line you want to comment on in the diff. Then, press Ctrl+Shift+P, type "GitHub Pull Requests: Add Comment". After that, a text area opens below the line - NVDA announces the input focus. Finally, type your comment. It is a checklist, but a meaningful one: every item creates evidence that the next step is safe.

      -

      Jamie: Before we leave Placing a comment, what is the practical point?

      -

      Alex: First, press Tab to the Submit button, then Enter. It is like walking a hallway with named doors: read the sign, enter the right room, then confirm where you landed.

      -

      Jamie: Let's pause on Opening the PR. What should a learner take away from it?

      -

      Alex: Start with Opening the PR. There is something to understand, something to try, and something that proves the try worked.

      -

      Alex: First, press Cmd+Shift+P, type "GitHub Pull Requests: View Pull Request". Then, navigate the PR tree with VO+Down Arrow. After that, press Return on a file to open its diff. It is like walking a hallway with named doors: read the sign, enter the right room, then confirm where you landed.

      +

      Jamie: If I am listening before the workshop starts, what should settle in my mind first?

      +

      Alex: This is where Reading Markdown files becomes real: they are plain text with lightweight formatting syntax. That matters in practice: VS Code renders Markdown with a preview panel (Ctrl+Shift+V).

      +

      Jamie: Let's pause on Reading HTML files. What should a learner take away from it?

      +

      Alex: Keep the learner anchored in Reading HTML files. The HTML files work the same offline as online. This is the part to say slowly: All ARIA landmarks, heading structure, and skip links are embedded in each file. A good GitHub workflow is like a well-run meeting: everyone knows the topic, the next action, and who has the floor.

      +

      Alex: First, open html/index.html in any web browser. Then, all internal links between pages work locally - no internet connection required. After that, navigate between chapters using the links at the bottom of each page. It is like walking a hallway with named doors: read the sign, enter the right room, then confirm where you landed.

      +

      Jamie: What is the pre-flight check here?

      +

      Alex: Start with Recommended offline reading setup. There is something to understand, something to try, and something that proves the try worked.

      +

      Alex: On the ground, that means a few things. VS Code with Markdown: Open the repo folder in VS Code, browse the Explorer, and read files directly in the editor. Use Ctrl+Shift+V to open the rendered preview. Browser with HTML: Open html/index.html and navigate from there - this gives the most polished reading experience.

      -

      Jamie: Let's pause on Accessible Diff Viewer. What should a learner take away from it?

      -

      Alex: Start with Accessible Diff Viewer. There is something to understand, something to try, and something that proves the try worked.

      -

      Alex: First, press F7 in the diff editor. Then, VoiceOver announces each change with clear "Removed" and "Added" labels. After that, navigate with F7/Shift+F7. Finally, press Escape to close. The rhythm is simple: orient, act, verify, then continue.

      -

      Jamie: Let's pause on Comment placement. What should a learner take away from it?

      -

      Alex: Start with Comment placement. There is something to understand, something to try, and something that proves the try worked.

      -

      Alex: First, press Cmd+Shift+P, type "GitHub Pull Requests: Add Comment". Then, vO+Shift+Down Arrow to interact with the comment text area. After that, type your comment. Finally, vO+Shift+Up Arrow to stop interacting, then Tab to Submit. Think of it as a rail line: each stop confirms you are still on the right route before the next one.

      -

      Jamie: Let's pause on Using the Accessible Diff Viewer (F7). What should a learner take away from it?

      -

      Alex: Here is the plain-English version of Using the Accessible Diff Viewer (F7). The Accessible Diff Viewer reads each change as a structured block. Put another way, this example is from a real Learning Room scenario: a contributor fixing the heading hierarchy in docs/keyboard-shortcuts.md by changing a level-4 heading to level-3, which is exactly what you look for when reviewing Challenge 2 PRs.

      -

      Alex: Treat examples as spoken recipes, not decorations. You may hear something like "Changed lines 14 to 14 in docs/keyboard-shortcuts.md; [Change 1 of 3]; Removed:; NVDA Single-Key Navigation; Added:; NVDA Single-Key Navigation". Read the command, understand what it changes, then run it only when the repository state matches the lesson.

      +

      Jamie: What should happen before anyone copies and runs it?

      +

      Alex: Start with If you cloned with Git: If you have not made local changes, this updates your copy cleanly. The next useful detail is this: If you have local edits, Git will attempt to merge - see Chapter 7 - Merge Conflicts if needed.

      +

      Alex: Treat examples as spoken recipes, not decorations. You may hear something like Navigate to your local copy; cd Learning-Room; Pull the latest changes; git pull. npm run build:html. Read the command, understand what it changes, then run it only when the repository state matches the lesson.

      +

      Jamie: Where do you want a learner to place their attention here?

      +

      Alex: Here is the plain-English version of If you downloaded a ZIP. Download a fresh ZIP from the repository and replace your local copy. Put another way, there is no incremental update for ZIP downloads.

      +

      Jamie: What decision is this helping them make?

      +

      Alex: Start with 8. Which Format Should I Use? There is something to understand, something to try, and something that proves the try worked.

      +

      Alex: Use the comparison to make a decision, not to recite a table. The main contrasts are: Reading during the workshop means GitHub Pages (online HTML) means No setup, always current, fully accessible. Offline reference means Local HTML (html/ folder) means Works in any browser, no internet needed, styled and navigable. Editing or contributing means Markdown (.md files) means The source format - edit these, then rebuild HTML.

      -

      Alex: Keep the teaching thread moving. Start with Navigation. There is something to understand, something to try, and something that proves the try worked.

      -

      Alex: The practical takeaway is this. F7 - jump to next change (next hunk). Shift+F7 - jump to previous change. Alt+F2 - open VS Code's Accessible View for additional context on the current item. Escape - close the Accessible Diff Viewer.

      -

      Jamie: Let's pause on What makes this better than the raw diff editor. What should a learner take away from it?

      -

      Alex: Start with What makes this better than the raw diff editor. There is something to understand, something to try, and something that proves the try worked.

      -

      Alex: The practical takeaway is this. Each change is announced as a discrete unit with clear "Removed:" and "Added:" labels. You hear the change number of total changes ("Change 3 of 12"). No table navigation required - purpose-built for sequential listening. Works with all three major screen readers without any special configuration.

      -

      Alex: Keep the teaching thread moving. The reason Placing Comments in VS Code (GitHub PR Extension) matters is that from the diff editor with the GitHub PR extension. That gives the learner a simple foothold: comments placed in VS Code sync to GitHub - they appear in the PR's Files Changed tab and the author receives the same notification.

      +

      Jamie: Let's pause on Learning Cards: Choosing the Right Format. What should a learner take away from it?

      +

      Alex: Keep the learner anchored in Learning Cards: Choosing the Right Format. Next: Appendix Z: GitHub Skills Back: Appendix X: Resources Teaching chapter: Chapter 00: Pre-Workshop Setup.

      +

      Alex: These are the details that keep the idea from floating away. For workshop use, the GitHub Pages HTML site is the most accessible option -- it includes skip links, landmarks, and proper heading structure in every page. For offline reference, the local HTML files in the html/ folder work identically to the online version with full navigation between pages. For contributing edits, work with the Markdown source files in docs/ using VS Code -- these are the canonical source that generates everything else. GitHub Pages and local HTML both support browser zoom to 200%+ without layout breakage -- use whichever gives you a better reading experience. VS Code's Markdown preview inherits your editor theme -- if you use a high-contrast theme, the preview will match. If viewing on GitHub.com, enable GitHub's dark theme (Settings then Appearance) for reduced eye strain during long reading sessions.

      -

      Jamie: Let's pause on The Anatomy of a Useful Review Comment. What should a learner take away from it?

      -

      Alex: Start with The Anatomy of a Useful Review Comment: A comment that helps the author is.

      -

      Alex: First, specific - link to the exact line and name the pattern you see. Then, educational - say why something matters, not just what to change. After that, graduated - signal whether this is blocking, or a preference. Think of it as a rail line: each stop confirms you are still on the right route before the next one.

      -

      Alex: Keep the teaching thread moving. Here is the plain-English version of Blocking example (reviewing a PR for docs/keyboard-shortcuts.md). "The heading on line 34 uses (level 4) directly after (level 2), skipping heading level 3. Put another way, screen reader users who navigate by heading level will miss any content between those two levels. It is like learning a transit route. The names of the stops matter because they tell you whether you are still going the right direction.

      -

      Jamie: Let's pause on Non-blocking (nit) example (reviewing a PR for docs/welcome.md). What should a learner take away from it?

      -

      Alex: This is where Non-blocking (nit) example (reviewing a PR for docs/welcome.md) becomes real: "nit: The link text in the 'Getting Help' section reads 'click here for more information.' Screen reader users who navigate links out of context will hear only 'click here' with no destination. That matters in practice: Consider 'See the accessibility setup guide' instead.

      +

      Jamie: What should people carry with them after this?

      +

      Alex: Carry the map. Know what page or tool you are in, know which action you are taking, and know what confirmation should follow. If the confirmation is missing, pause. That pause is not wasted time; it is professional judgment.

      +

      Jamie: That is a better way to say it than just follow the steps.

      +

      Alex: Right. Steps matter, but understanding wins. That is episode 42. Next in the series is episode 43, where we keep building the same contributor muscles.

      +
      +
      -

      Alex: Keep the teaching thread moving. Keep the learner anchored in Question example (reviewing a PR for docs/setup-guide.md). "The PR description says this fixes broken links in the setup guide, but the link on line 12 still points to /docs/old-setup. This is the part to say slowly: Am I reading the diff correctly, or was this link intentionally left?

      -

      Jamie: Let's pause on Prefixes That Set Expectations. What should a learner take away from it?

      -

      Alex: The reason Prefixes That Set Expectations matters is that using shorthand prefixes helps authors parse many comments quickly.

      -

      Alex: Keep the teaching thread moving. Start with How Many Comments Is Too Many?: There is no hard limit, but quantity without prioritization is noise. The next useful detail is this: If you have 15 comments, make clear which 2-3 are blocking. Think of it like entering a new building: first you find the lobby, then the room, then the door you actually need.

      +

      70. Episode 43: GitHub Skills - Complete Course Catalog

      +

      All 36 GitHub Skills modules organized into six learning paths.

      +

      Based on: Appendix Z: GitHub Skills - Complete Course Catalog

      +

      Audio and transcript are being regenerated for this episode.

      +
      +Read Transcript - Episode 43: GitHub Skills - Complete Course Catalog + +

      Transcript

      +

      Alex: Welcome to episode 43 of Git Going with GitHub: GitHub Skills - Complete Course Catalog. I am Alex, and today we are teaching this topic as a conversation you can carry into the workshop, not as a page you have to memorize.

      +

      Jamie: And I am Jamie. I will keep pulling the lesson back to real learners, real repositories, and the evidence that proves the work happened.

      -

      Jamie: Let's pause on "I want to verify the PR only changes what it claims". What should a learner take away from it?

      -

      Alex: Here is the plain-English version of "I want to verify the PR only changes what it claims". Example: A PR says "Challenge 2: Add NVDA shortcut" but the file tree shows changes to both docs/keyboard-shortcuts.md and docs/welcome.md.

      -

      Alex: Keep the teaching thread moving. This is where "I want to find all changes to one specific section" becomes real: example: A PR for Challenge 3 modified docs/welcome.md. That matters in practice: You want to verify the [TODO] in the "Who Can Contribute?" section was filled in correctly.

      -

      Jamie: Let's pause on Exercises. What should a learner take away from it?

      -

      Alex: Keep the learner anchored in Exercises. These exercises use the files in learning-room/docs/ in this repository. This is the part to say slowly: All examples involve documentation changes - no code required.

      +

      Alex: The lesson focus is All 36 GitHub Skills modules organized into six learning paths. We will treat every step as a teachable decision, because that is what makes the skill portable.

      +

      Jamie: So we should explain the why clearly enough that the steps make sense when the learner meets them later.

      +

      Alex: That is it. If a listener only has audio right now, they should still get the complete concept and know what evidence would prove success.

      -

      Alex: Keep the teaching thread moving. The reason Exercise A - Complete a Web Review matters is that scenario: A contributor has submitted a pull request titled "Add screen reader tips to the setup guide." The PR modifies learning-room/docs/setup-guide.md. That gives the learner a simple foothold: your job is to review it before it merges. The interface gets friendlier when it stops being a wall of controls and starts being a set of named places.

      -

      Jamie: Let's pause on Step 1: Navigate to the Pull Request. What should a learner take away from it?

      -

      Alex: Start with Step 1: Navigate to the Pull Request: How to know you're in the right place.

      -

      Alex: The practical takeaway is this. The PR title is visible at the top. You see a description box with text about what this PR does. You see tabs labeled "Conversation," "Commits," "Files Changed". Use Ctrl+F to search the PR list for "screen reader tips". Or ask in the workshop Slack - someone can share the exact URL.

      -

      Alex: First, open GitHub in your browser and navigate to the workshop repository (github.com/[your-fork]/[workshop-repo] or community-access/accessibility-agents). Then, click the Pull Requests tab (top navigation). After that, look for a PR titled "Add screen reader tips to the setup guide" - click it to open. Finally, you should now see the PR page with sections: Conversation, Commits, Files Changed. Think of it as a rail line: each stop confirms you are still on the right route before the next one.

      -

      Jamie: Let's pause on Step 2: Read the PR Description. What should a learner take away from it?

      -

      Alex: Start with Step 2: Read the PR Description. There is something to understand, something to try, and something that proves the try worked.

      -

      Alex: The practical takeaway is this. Does the PR author explain what file changed? (should mention setup-guide.md). Does it explain why? (should mention "improve accessibility" or "add tips"). Is it clear enough that a reviewer can understand the goal without reading the diff? You can answer: "This PR adds [specific content] to [specific file] because [clear reason]". Example: "This PR adds screen reader usage tips to the setup guide because new users need accessibility guidance".

      -

      Alex: First, you are currently on the Conversation tab. Then, read the PR description (the text immediately under the PR title). After that, look for: "What does this PR change?" and "Why does it change it?". Finally, with screen reader: Navigate to the description with D (NVDA) or press Ctrl+Option+Up (VoiceOver) to find main landmarks, then read the content region. Treat it like a recipe: do not add the next ingredient until the previous one is actually in the bowl.

      +

      Jamie: Okay, set the room for us. What are we walking into?

      +

      Alex: Start with Learning Cards: How GitHub Skills Works. There is something to understand, something to try, and something that proves the try worked.

      +

      Alex: A few details make that real. Every GitHub Skills course runs inside a standard GitHub repository -- the screen reader navigation skills from this workshop (heading nav, issue reading, PR workflows) apply directly. After copying a course with "Use this template," navigate to the Issues tab (G then I) and press H or 3 to find "Step 1:" -- this is where Mona's first lesson appears. Mona posts feedback as issue comments -- press 9 (NVDA/JAWS) to jump to the comments section and read her instructions. Course content appears as standard GitHub issues and comments -- your existing GitHub theme and font size settings apply automatically. Mona's step numbers appear as issue titles with "Step 1:", "Step 2:" prefixes -- scan the Issues list for these numbered titles to track your progress. Course completion is indicated when Mona closes the final issue with a success message -- look for the purple "Closed" badge.

      +

      Jamie: How would you walk the room through that step by step?

      +

      Alex: Here is the plain-English version of How GitHub Skills Works. Each course follows the same pattern. Put another way, all interaction happens through GitHub's standard interface. It is like learning a transit route. The names of the stops matter because they tell you whether you are still going the right direction.

      +

      Alex: First, navigate to the course URL and select "Start course". Then, GitHub copies the course repository to your account. After that, mona (GitHub's automated learning bot) opens an issue with Step 1 instructions within 20 seconds. Finally, you complete the task described in the issue (create a branch, edit a file, open a PR). Treat it like a recipe: do not add the next ingredient until the previous one is actually in the bowl.

      +

      Jamie: What does the learner do first, second, and then after that?

      +

      Alex: First, mona detects your action, validates it, and posts the next step as a comment or new issue. Then, repeat until Mona closes the final issue with a completion message. It is a checklist, but a meaningful one: every item creates evidence that the next step is safe.

      +

      Jamie: What should feel predictable before the first live session starts?

      +

      Alex: This is where Courses Used in This Workshop becomes real: these three modules are integrated into the Day 1 agenda. That matters in practice: You complete them during the workshop with facilitator guidance.

      +
      +

      Alex: Now bring the learner back to the room. Keep the learner anchored in Learning Paths. The remaining courses are organized into six learning paths. This is the part to say slowly: Each path builds on skills from this workshop and progresses from introductory to advanced.

      +

      Jamie: What would you say to someone who is already bracing for this to be too much?

      +

      Alex: Start with Learning Cards: Navigating Learning Paths. There is something to understand, something to try, and something that proves the try worked.

      +

      Alex: The parts worth keeping in working memory are these. The six learning paths below are organized as H3 headings with tables listing courses in recommended order -- press 3 to jump between paths, then T to enter each course table. Each course link is in the rightmost "Link" column of the table -- navigate to it with arrow keys after entering the table. Use the Personal Completion Checklist at the bottom of this appendix as a progress tracker -- copy it into a GitHub issue or personal notes file. Each learning path table has columns for Order, Module, Duration, Prerequisite, What You Learn, and Link -- widen your browser if columns appear truncated at high zoom. Course durations range from 30 minutes to 2 hours -- the Duration column helps you plan which courses fit your available time. The Quick Reference table near the bottom alphabetically lists all 36 courses for fast scanning when you know the course name.

      +

      Alex: The useful habit is simple: orient first, act second, verify third. That pause before acting is part of the work.

      +

      Alex: That matters because of the next idea. Start with Path 1: Git Fundamentals: Deepen your understanding of Git version control beyond what the workshop covered. The next useful detail is this: The following table lists Git fundamentals courses in recommended order. Think of it like entering a new building: first you find the lobby, then the room, then the door you actually need.

      +

      Alex: A solid Git habit is to know which branch you are on, what changed, and what confirmation you expect before you run the next command.

      -

      Jamie: Let's pause on Step 3: Navigate to "Files Changed". What should a learner take away from it?

      -

      Alex: Start with Step 3: Navigate to "Files Changed". There is something to understand, something to try, and something that proves the try worked.

      -

      Alex: The practical takeaway is this. A section showing the file name setup-guide.md with a small badge showing "+20 −0" (20 lines added, 0 lines removed). Below it, the diff with removed lines (preceded by −) and added lines (preceded by +). Scroll up to see if there are other files. For this exercise, only setup-guide.md should be changed. If you see other files, confirm they are not modified (the badge should show "+0 −0" or no changes).

      -

      Alex: First, click the Files Changed tab (top of the PR page, to the right of "Commits"). Then, you are now viewing the diff. After that, with keyboard (all screen readers): Press T to jump to the diff table. The page focuses on the file comparison area. It is a checklist, but a meaningful one: every item creates evidence that the next step is safe.

      -

      Jamie: Let's pause on Step 4: Activate Focus Mode for Better Diff Reading. What should a learner take away from it?

      -

      Alex: Keep the learner anchored in Step 4: Activate Focus Mode for Better Diff Reading. With screen reader (once in Focus Mode). A good GitHub workflow is like a well-run meeting: everyone knows the topic, the next action, and who has the floor.

      -

      Alex: The practical takeaway is this. The page simplifies: sidebars disappear. Only the diff is visible - easier for screen reader navigation and less cognitive load. The diff is now the main content area. NVDA/JAWS: Press T to jump to the diff table. VoiceOver: Navigate with VO+Right Arrow to find the table/content region. Read through the changes: ↓ arrow moves to each line.

      -

      Alex: First, look for a button labeled "Focus Mode" or an icon (usually at the top right of the diff area). Then, with keyboard: Press F to toggle Focus Mode (may need to be in the diff area first). After that, with mouse: Click the Focus Mode button/icon. It is like walking a hallway with named doors: read the sign, enter the right room, then confirm where you landed.

      -

      Jamie: Let's pause on Step 5: Find the Heading Hierarchy Issue. What should a learner take away from it?

      -

      Alex: Start with Step 5: Find the Heading Hierarchy Issue. There is something to understand, something to try, and something that proves the try worked.

      -

      Alex: The practical takeaway is this. Screen reader users navigate documents by heading level: 1 → 2 → 3 → 4. A skip from to breaks that navigation. When a user presses "jump to heading level 3," they'll find none, wondering if content is missing. You found the line with that violates hierarchy. You can say the line number and what heading text appears there. You understand why this is an accessibility problem.

      -

      Alex: First, read through the entire diff line by line. Pay special attention to lines starting. Then, you are looking for: a line with (four hashes, heading level 4) that comes directly after a (two hashes, heading level 2). After that, when you find it, note the exact line number shown in the diff. The rhythm is simple: orient, act, verify, then continue.

      +

      Jamie: If I am listening before the workshop starts, what should settle in my mind first?

      +

      Alex: Here is the plain-English version of Path 2: GitHub Collaboration. Learn the collaboration features that power open source projects and team workflows. Put another way, the following table lists GitHub collaboration courses in recommended order.

      +

      Alex: This is where the talk moves from concept to action. This is where Path 3: GitHub Actions and Automation becomes real: build automated workflows that test, build, and deploy your projects. That matters in practice: The following table lists GitHub Actions courses in recommended order.

      +

      Jamie: What is the one idea that makes the next few steps less mysterious?

      +

      Alex: Keep the learner anchored in Path 4: GitHub Copilot. Master AI-assisted development with GitHub Copilot across editors, CLI, and GitHub itself. This is the part to say slowly: The following table lists GitHub Copilot courses in recommended order.

      -

      Jamie: Let's pause on Step 6: Place a Blocking Review Comment on the Heading. What should a learner take away from it?

      -

      Alex: Start with Step 6: Place a Blocking Review Comment on the Heading: If the comment button doesn't appear.

      -

      Alex: The practical takeaway is this. Your comment appears in the thread under that line. The PR author sees it and can make the fix. Make sure you're hovering over the line number area (left side of the line). Try refreshing the page and trying again. Or use the "Add a reply" field at the bottom of the PR and mention the line number manually.

      -

      Alex: First, find the diff line with the problematic heading. Then, hover your mouse over the line number on the left side of that line (or if using keyboard, navigate to that line in the table). After that, a button should appear (or press the Add Comment hotkey - usually C in GitHub). Finally, click it or press Enter to open a comment box. Think of it as a rail line: each stop confirms you are still on the right route before the next one.

      -

      Jamie: Before we leave Step 6: Place a Blocking Review Comment on the Heading, what is the practical point?

      -

      Alex: First, press Space, then explain. Then, click the Comment button (or press Ctrl+Enter for keyboard submit). Treat it like a recipe: do not add the next ingredient until the previous one is actually in the bowl.

      -

      Jamie: Let's pause on Step 7: Find the Link Text Issue. What should a learner take away from it?

      -

      Alex: Start with Step 7: Find the Link Text Issue. There is something to understand, something to try, and something that proves the try worked.

      -

      Alex: The practical takeaway is this. Screen reader users can ask their reader to "list all links on this page" - they hear only the link text. If the text is "click here," they have no context about where it goes. Descriptive link text is WCAG 2.4.4 (Link Purpose). You found a link with non-descriptive text. You can explain why "click here" is bad and what would be better.

      -

      Alex: First, continue reading the diff (from where you left off). Then, look for a line containing link text that reads "click here" or "click here for more information". After that, note the line number. Treat it like a recipe: do not add the next ingredient until the previous one is actually in the bowl.

      -

      Jamie: Let's pause on Step 8: Place a Comment on the Link. What should a learner take away from it?

      -

      Alex: This is where Step 8: Place a Comment on the Link becomes real: nit: means "nice-to-have improvement" (not blocking, but good to fix). The workshop is closer to rehearsal than lecture. You hear the move, try the move, and then check what changed.

      -

      Alex: First, find the line in the diff with the problematic link. Then, hover over the line number and click to open a comment box (or press C). After that, click Comment or press Ctrl+Enter. It is a checklist, but a meaningful one: every item creates evidence that the next step is safe.

      +

      Alex: Before the learner moves on. The reason Path 5: Security matters is that learn to identify vulnerabilities, scan for secrets, and secure your supply chain. That gives the learner a simple foothold: the following table lists security courses in recommended order. The interface gets friendlier when it stops being a wall of controls and starts being a set of named places.

      +

      Jamie: Give me the version that sounds like an instructor, not a manual.

      +

      Alex: Start with Path 6: Cloud and Migration: Deploy to the cloud and migrate existing projects to GitHub. The next useful detail is this: The following table lists cloud and migration courses in recommended order.

      +

      Alex: Hold that next to this. Here is the plain-English version of Quick Reference - All 36 Courses. The following table alphabetically lists every GitHub Skills course with its category and link for quick lookup.

      -

      Jamie: Let's pause on Step 9: Submit Your Review. What should a learner take away from it?

      -

      Alex: Start with Step 9: Submit Your Review. There is something to understand, something to try, and something that proves the try worked.

      -

      Alex: The practical takeaway is this. Comment - provide feedback but don't block (for minor notes). Approve - the PR is ready to merge. Request changes - this PR cannot merge until changes are made. Your review is submitted. The PR author gets a notification. The PR shows your review with the two comments.

      -

      Alex: First, look for a button labeled "Review changes" (usually at the top right of the page or bottom of comments). Then, click it (or navigate with keyboard and press Enter). After that, a dialog appears with options. Finally, select "Request changes" (you found two things to fix). It is like walking a hallway with named doors: read the sign, enter the right room, then confirm where you landed.

      -

      Jamie: Before we leave Step 9: Submit Your Review, what is the practical point?

      -

      Alex: First, in the summary field, write: Found 2 accessibility issues that must be fixed before merging. Then, click "Submit review". The rhythm is simple: orient, act, verify, then continue.

      -

      Jamie: Let's pause on Reflect on This Exercise. What should a learner take away from it?

      -

      Alex: The reason Reflect on This Exercise matters is that keep your answers - you'll need them for Chapter 16's Accessibility Agents exercise to compare manual review with agent-assisted review.

      -

      Alex: First, did heading-level navigation help? When you were looking for the issue, was it easier to navigate by heading level (1-6) than to scan every line? Then, would you have caught this without the exercise prompt? If you were a real reviewer not specifically looking for heading issues, would the diff have been obvious? After that, why does screen reader navigation matter? In one sentence, explain why a screen reader user's ability to jump through heading levels is important for this document. The rhythm is simple: orient, act, verify, then continue.

      -

      Jamie: What stays the same when the tool changes?

      -

      Alex: Start with Exercise B - Use the VS Code Accessible Diff Viewer: Scenario: Review the same pull request from Exercise A, this time entirely in VS Code. The next useful detail is this: You'll compare the browser experience with the VS Code experience.

      +

      Jamie: How do the two days connect instead of feeling like separate courses?

      +

      Alex: This is where During the Workshop becomes real: three courses are woven into Day 1. That matters in practice: You set each one up during the block where it appears, work through Mona's steps alongside the learning room exercises, and finish before moving to the next block.

      +

      Jamie: Turn that into a path someone can follow.

      +

      Alex: Start with After the Workshop - Recommended Next Steps. There is something to understand, something to try, and something that proves the try worked.

      +

      Alex: For a learner, the useful signals are these. Want to contribute to open source? Start with Path 2 (Collaboration). Want to automate your workflow? Start with Path 3 (Actions). Want to code faster with AI? Start with Path 4 (Copilot). Want to secure your projects? Start with Path 5 (Security).

      +

      Alex: First, finish any incomplete workshop courses first. If Introduction to GitHub, Communicate Using Markdown, or Review Pull Requests are still in progress, complete them before starting new modules. Then, pick one path that matches your next goal. After that, work through one course at a time. Each course takes 30-60 minutes. Spreading them across multiple days helps with retention. Finally, use the workshop materials as reference. When a GitHub Skills course asks you to create a branch or open a PR, the chapter guides from this workshop describe the same operations with screen reader instructions. It is like walking a hallway with named doors: read the sign, enter the right room, then confirm where you landed.

      +

      Jamie: Where do you want a learner to place their attention here?

      +

      Alex: The reason Tracking Your Progress matters is that GitHub Skills does not have a central dashboard for tracking completions.

      +

      Alex: On the ground, that means a few things. GitHub profile: Completed courses appear as repositories in your account. Pin your favorites to your profile. Repository list: Filter your repositories by the "skills-" prefix to see all courses you have started. Mona's final message: When you finish a course, Mona posts a completion message in the final issue. Bookmark it. This checklist: Copy the list below into a personal note or issue to track which courses you have completed.

      +

      Alex: A solid pull request habit is to separate three questions: what changed, why it changed, and what still needs review. That keeps the conversation useful instead of noisy.

      -

      Alex: Keep the teaching thread moving. Start with Prerequisites. There is something to understand, something to try, and something that proves the try worked.

      -

      Alex: The practical takeaway is this. VS Code must be installed on your machine. The GitHub Pull Requests extension must be installed (see Chapter 12 for installation). You must be signed into GitHub from VS Code (use Ctrl+Shift+P → "GitHub: Sign in").

      -

      Jamie: Let's pause on Step 1: Open the GitHub Pull Requests Extension. What should a learner take away from it?

      -

      Alex: Start with Step 1: Open the GitHub Pull Requests Extension. There is something to understand, something to try, and something that proves the try worked.

      -

      Alex: The practical takeaway is this. With mouse: Click the Extensions icon on the left sidebar (looks like four squares). The extension is listed as active. It mentions: "Review and manage GitHub pull requests and issues".

      -

      Alex: First, open VS Code. Then, with keyboard (all screen readers): Press Ctrl+Shift+X to open the Extensions sidebar. After that, search for "GitHub Pull Requests". Finally, if it's not installed, click Install. It is a checklist, but a meaningful one: every item creates evidence that the next step is safe.

      -

      Jamie: Before we leave Step 1: Open the GitHub Pull Requests Extension, what is the practical point?

      -

      Alex: First, if it is installed, click GitHub Pull Requests to view its details. It is like walking a hallway with named doors: read the sign, enter the right room, then confirm where you landed.

      -

      Jamie: Let's pause on Step 2: Open the Pull Requests Sidebar. What should a learner take away from it?

      -

      Alex: Start with Step 2: Open the Pull Requests Sidebar. There is something to understand, something to try, and something that proves the try worked.

      -

      Alex: The practical takeaway is this. With keyboard: The icon may not be keyboard-reachable directly; instead go to Step 3. VS Code opens a new editor tab for this PR. Below the PR title, you see a "Changes" section listing modified files. You should see setup-guide.md in the changes list. Use Ctrl+Shift+P → search GitHub Pull Requests: Open Pull Request. Paste the PR URL: https://github.com/[owner]/[repo]/pull/[number].

      -

      Alex: First, look for a GitHub-themed icon on the left sidebar (circle with octocat logo) - click it. Then, a sidebar appears showing open pull requests on repositories you have access to. After that, find the PR titled "Add screen reader tips to the setup guide" - it should appear in a list. Finally, click it to open. It is like walking a hallway with named doors: read the sign, enter the right room, then confirm where you landed.

      +

      Alex: Here is the practical turn. Start with Personal Completion Checklist: Copy this list into your own notes to track progress.

      +

      Jamie: Let's pause on Additional Resources. What should a learner take away from it?

      +

      Alex: Here is the plain-English version of Additional Resources. Back: Appendix Y: Workshop Materials Teaching chapter: Chapter 00: Pre-Workshop Setup.

      +

      Alex: Here is what that changes in practice. GitHub Skills homepage - browse all courses with descriptions. GitHub Skills organization - view all course repositories directly. GitHub Skills Discussions - ask questions and share feedback with the GitHub Skills community.

      -

      Jamie: Let's pause on Step 3: View the File Changes. What should a learner take away from it?

      -

      Alex: Start with Step 3: View the File Changes. There is something to understand, something to try, and something that proves the try worked.

      -

      Alex: The practical takeaway is this. A diff editor opens showing two columns. Left: the original file (before changes). Right: the new file (after changes). Different colors show added (green), removed (red), and modified (blue) lines. The file name appears at the top: setup-guide.md. NVDA/JAWS: The editor announces "Diff Editor - setup-guide.md".

      -

      Alex: First, in the Changes section, locate setup-guide.md. Then, click on the filename to open it. The rhythm is simple: orient, act, verify, then continue.

      -

      Jamie: Let's pause on Step 4: Access the Accessible Diff Viewer. What should a learner take away from it?

      -

      Alex: Start with Step 4: Access the Accessible Diff Viewer: If the Accessible Diff Viewer doesn't open. Think of it like entering a new building: first you find the lobby, then the room, then the door you actually need.

      -

      Alex: The practical takeaway is this. With mouse: Look for a button or menu option labeled "Accessible View" or "Open Accessible Diff". If no button is visible, try Alt+F2 (VS Code Accessible View toggle). A new panel opens at the bottom of VS Code. The panel announces each change one at a time. Changes appear in text format with labels: "Added: " and "Removed: ". The panel is read-only (you read the changes, you don't edit here).

      -

      Alex: First, with keyboard: Press F7 to open the Accessible Diff Viewer. Think of it as a rail line: each stop confirms you are still on the right route before the next one.

      -

      Jamie: Let's pause on Step 5: Listen to and Understand the First Change. What should a learner take away from it?

      -

      Alex: Start with Step 5: Listen to and Understand the First Change. There is something to understand, something to try, and something that proves the try worked.

      -

      Alex: The practical takeaway is this. NVDA/JAWS: The Accessible Diff Viewer announces "Removed:" and "Added:" labels, followed by the line content. VoiceOver: The announcement may be similar; listen for "removed" and "added" keywords.

      -

      Alex: First, the first change is automatically announced when you open the Accessible Diff Viewer. Then, let your screen reader read it completely - don't interrupt. After that, write down the exact text announced. Finally, press the Down arrow to move to the next change. Treat it like a recipe: do not add the next ingredient until the previous one is actually in the bowl.

      +

      Jamie: What should people carry with them after this?

      +

      Alex: Carry the map. Know what page or tool you are in, know which action you are taking, and know what confirmation should follow. If the confirmation is missing, pause. That pause is not wasted time; it is professional judgment.

      +

      Jamie: That is a better way to say it than just follow the steps.

      +

      Alex: Right. Steps matter, but understanding wins. That is episode 43. Next in the series is episode 44, where we keep building the same contributor muscles.

      +
      +
      -

      Jamie: Let's pause on Step 6: Find the Heading Hierarchy Issue. What should a learner take away from it?

      -

      Alex: Start with Step 6: Find the Heading Hierarchy Issue. There is something to understand, something to try, and something that proves the try worked.

      -

      Alex: The practical takeaway is this. Four hashes ( ) indicate a level 4 heading. In the diff, you're looking for it appearing after a level 2 heading ( ). This creates the hierarchy skip you caught in Exercise A. You found the explanation in the Accessible Diff Viewer's format. You can explain: "The added line with directly follows a, skipping level 3". The Accessible Diff Viewer made this pattern clearer than scanning raw + characters.

      -

      Alex: First, continue pressing Down arrow to move through changes. Then, listen carefully for a change involving headings (lines starting with ). After that, specifically, listen for: "Added: " (four hashes). Finally, when you hear this, stop and write it down. It is a checklist, but a meaningful one: every item creates evidence that the next step is safe.

      -

      Jamie: Let's pause on Step 7: Locate the Heading Line and Add an Inline Comment. What should a learner take away from it?

      -

      Alex: Start with Step 7: Locate the Heading Line and Add an Inline Comment. There is something to understand, something to try, and something that proves the try worked.

      -

      Alex: The practical takeaway is this. Use Ctrl+F to open Find. Search for to locate it quickly. Press Enter to jump to it. With keyboard: The comment button may appear on the current line; navigate to it and press Enter. A comment box opens. You can type your comment.

      -

      Alex: First, once you identified the problematic heading in the Accessible Diff Viewer, close the Accessible Diff Viewer (press F7 again or Alt+F2). Then, you're back in the regular Diff Editor. After that, find the line with the problematic heading. Finally, close Find (Escape). It is like walking a hallway with named doors: read the sign, enter the right room, then confirm where you landed.

      -

      Jamie: Before we leave Step 7: Locate the Heading Line and Add an Inline Comment, what is the practical point?

      -

      Alex: First, place your cursor on that line. Then, right-click and select "Add Comment" or press the Comment icon that appears on the left margin. The rhythm is simple: orient, act, verify, then continue.

      -

      Jamie: Let's pause on Step 8: Write Your Accessible Diff Comment. What should a learner take away from it?

      -

      Alex: The reason Step 8: Write Your Accessible Diff Comment matters is that why mention the Accessible Diff Viewer? The interface gets friendlier when it stops being a wall of controls and starts being a set of named places.

      -

      Alex: The practical takeaway is this. It shows that the tool itself helps you see the issue. It documents how you caught the problem (useful for learning).

      -

      Alex: First, in the comment box, type. Then, press Ctrl+Enter or click Comment to submit. The rhythm is simple: orient, act, verify, then continue.

      +

      71. Episode 49: What Comes Next

      +

      How to continue learning, contributing, and building confidence after the workshop.

      +

      Based on: Chapter 21: What Comes Next

      +

      Audio and transcript are being regenerated for this episode.

      +
      +Read Transcript - Episode 49: What Comes Next + +

      Transcript

      +

      Alex: Welcome back to Git Going with GitHub. This is episode 49: What Comes Next. I am Alex, and today we are turning What Comes Next from a list of instructions into a working mental model.

      +

      Jamie: And I am Jamie. I will stop us whenever the instructions sound simple on paper but might feel different with a keyboard and screen reader.

      -

      Jamie: Let's pause on Step 9: Create a GitHub Pull Request Comment. What should a learner take away from it?

      -

      Alex: Start with Step 9: Create a GitHub Pull Request Comment: Now you've reviewed the same PR in.

      -

      Alex: First, browser (Exercise A): You spot-checked line numbers manually. Then, VS Code (Exercise B): The Diff Editor plus Accessible Diff Viewer announced changes. After that, go to GitHub in your browser and open the same PR. Finally, scroll to the bottom and leave a comment in the Conversation tab. Think of it as a rail line: each stop confirms you are still on the right route before the next one.

      -

      Jamie: Before we leave Step 9: Create a GitHub Pull Request Comment, what is the practical point?

      -

      Alex: First, click Comment. Treat it like a recipe: do not add the next ingredient until the previous one is actually in the bowl.

      -

      Jamie: Before we leave Reflect on This Exercise, what is the practical point?

      -

      Alex: Here is the plain-English version of Reflect on This Exercise. After completing Steps 1-9, answer. Put another way, in Chapter 16, you'll compare these manual reviews with the @pr-review agent's suggested changes.

      -

      Alex: First, announcement clarity: Did the "Added:" and "Removed:" labels from the Accessible Diff Viewer help you follow changes faster than reading + and − prefixes in the browser? Then, navigation pattern: Which tool required less back-and-forth clicking/tabbing to understand each change? After that, when would you use each? In one sentence: describe a type of PR where you'd prefer to use each tool. Treat it like a recipe: do not add the next ingredient until the previous one is actually in the bowl.

      -

      Jamie: Let's pause on Exercise C - Compare and Reflect. What should a learner take away from it?

      -

      Alex: This is where Exercise C - Compare and Reflect becomes real: your Mission: Synthesize what you learned from the manual code reviews (Exercises A & B) and document your findings. That matters in practice: What You'll Learn: Which tools work best for different scenarios, and how your manual review skills prepare you to use AI agents effectively.

      +

      Alex: How to continue learning, contributing, and building confidence after the workshop. That is the surface description. Underneath it, we are building judgment: where to focus, what to ignore, and how to verify the result.

      +

      Jamie: So we are not using the audio as a shortcut around learning. We are using it to make the learning easier to enter.

      +

      Alex: Yes. A good audio lesson gives someone enough context to try the work with confidence, even before they open the written material.

      -

      Alex: Keep the teaching thread moving. Keep the learner anchored in Step 1: Gather Your Data. Before writing your reflection, collect all the information you gathered. This is the part to say slowly: Write these down (in a text editor, on paper, or mentally) - you'll reference them in Steps 2-4. A good GitHub workflow is like a well-run meeting: everyone knows the topic, the next action, and who has the floor.

      -

      Alex: The practical takeaway is this. Which line number had the heading hierarchy skip? Which line number had the link text issue? How many steps did it take to find each issue? Did you use screen reader commands or visual scanning more?

      -

      Jamie: Let's pause on Step 2: Navigate to the PR and Leave Your Reflection Comment. What should a learner take away from it?

      -

      Alex: Start with Step 2: Navigate to the PR and Leave Your Reflection Comment. There is something to understand, something to try, and something that proves the try worked.

      -

      Alex: The practical takeaway is this. A text editing area with formatting options (Bold, Italic, Link, etc.). A Comment button below the text area.

      -

      Alex: First, go to GitHub in your browser. Then, open the same PR ("Add screen reader tips to the setup guide"). After that, scroll to the Conversation tab. Finally, scroll all the way down to the comment box at the bottom (labeled "Leave a comment" or "Add a comment"). The rhythm is simple: orient, act, verify, then continue.

      -

      Jamie: Before we leave Step 2: Navigate to the PR and Leave Your Reflection Comment, what is the practical point?

      -

      Alex: First, click in the comment box. Think of it as a rail line: each stop confirms you are still on the right route before the next one.

      -

      Alex: Keep the teaching thread moving. Start with Step 3: Write Your Comparison: Type your response to these three questions. The next useful detail is this: Be specific - reference exact tools, steps, and what you discovered.

      +

      Jamie: Okay, set the room for us. What are we walking into?

      +

      Alex: Start with 1. What You Built in Two Days: Take a moment to appreciate what you accomplished. The next useful detail is this: This is not a list of what you were taught -- it is a list of what you did.

      +

      Alex: The next layer is this. Start with Day 1: You Can Navigate This. There is something to understand, something to try, and something that proves the try worked.

      +

      Alex: The practical anchors are these. Created and configured a GitHub account with accessibility settings. Navigated repositories, files, and folders using your screen reader, keyboard, or preferred tools. Filed issues with descriptive titles, labels, and context. Created branches, edited files, and opened pull requests. Responded to bot feedback and passed automated checks. Resolved a merge conflict.

      +

      Jamie: What should feel predictable before the first live session starts?

      +

      Alex: Start with Day 2: You Can Build This. There is something to understand, something to try, and something that proves the try worked.

      +

      Alex: That shows up in the workshop in a few specific ways. Installed and configured VS Code with accessibility settings. Cloned a repository and worked with Git locally. Understood the mental model: working directory, staging area, repository. Created branches, staged changes, committed, and pushed from the command line. Explored GitHub Copilot: code suggestions, chat, and code review. Created an issue template.

      -

      Jamie: Let's pause on Step 4: Review Your Comment. What should a learner take away from it?

      -

      Alex: Start with Step 4: Review Your Comment. There is something to understand, something to try, and something that proves the try worked.

      -

      Alex: The practical takeaway is this. Is it clear which tool I preferred? Did I explain why with concrete examples? Am I describing the real-world impact accurately? Would someone else reading this understand how I caught the issue?

      -

      Alex: First, before submitting, re-read your comment using your screen reader or by reading aloud. Then, ask yourself. After that, make any corrections needed. Finally, do not submit yet - continue to Step 5. Treat it like a recipe: do not add the next ingredient until the previous one is actually in the bowl.

      -

      Jamie: Let's pause on Step 5: Submit Your Reflection. What should a learner take away from it?

      -

      Alex: Start with Step 5: Submit Your Reflection. There is something to understand, something to try, and something that proves the try worked.

      -

      Alex: The practical takeaway is this. Your comment is now visible on the PR. Other reviewers can see your comparison. You have completed the three-part exercise series. Your comment appears on the PR thread. It includes all three reflections. The PR author and other reviewers can see your thought process.

      -

      Alex: First, locate the Comment button at the bottom right of the comment box. Then, with keyboard: Press Tab until the Comment button is focused, then Enter. After that, with mouse: Click the Comment button. Finally, your comment is submitted and appears on the PR page. It is a checklist, but a meaningful one: every item creates evidence that the next step is safe.

      -

      Jamie: Let's pause on Step 6: Checkpoint - Validate Your Learning. What should a learner take away from it?

      -

      Alex: Keep the learner anchored in Step 6: Checkpoint - Validate Your Learning. Before moving forward, verify you understand. This is the part to say slowly: If you can answer all three, you're ready for the next chapter.

      -

      Alex: The practical takeaway is this. Expected answer: Something like "Screen readers let users navigate by heading level (pressing 3 jumps to H3), so skipping a level makes users think content is missing.". Expected answer: e.g., "Browser: finding context in discussions. VS Code: linear reading of changes.". Expected answer: Something like "Open the document in a browser, use screen reader heading navigation, and confirm I can reach all levels (H2, H3, H4).".

      -

      Alex: First, heading Hierarchy: Can you explain in one sentence why a → skip breaks screen reader navigation? Then, tool Strengths: For each tool you used, name one task it made easier. After that, real-World Testing: How would you test the heading issue in the published document (not the PR diff)? It is like walking a hallway with named doors: read the sign, enter the right room, then confirm where you landed.

      +

      Alex: Now bring the learner back to the room. Keep the learner anchored in The evidence. Your GitHub profile now contains real activity: issues filed, pull requests merged, code reviewed, and an agent contributed to an open source project.

      +

      Jamie: What would you say to someone who is already bracing for this to be too much?

      +

      Alex: The reason 2. Your New Skills Inventory matters is that the following table maps what you learned to where it applies beyond this workshop. That gives the learner a simple foothold: every skill transfers directly to real-world development.

      +

      Alex: The useful habit is simple: orient first, act second, verify third. That pause before acting is part of the work.

      +

      Alex: That matters because of the next idea. Start with Skills you may not have noticed. There is something to understand, something to try, and something that proves the try worked.

      +

      Alex: On the ground, that means a few things. Reading documentation: You navigated technical guides, followed step-by-step instructions, and troubleshot problems using written references. This is the most important developer skill. Asking for help effectively: You posted on issues with context, error messages, and what you tried. This is how experienced developers communicate. Learning tools by doing: You did not read a manual cover to cover. You tried things, hit problems, and figured them out. This is how real tool learning works.

      -

      Alex: Keep the teaching thread moving. The reason Using GitHub Copilot to Understand Code Changes matters is that reviewing code is about understanding what changed, why it changed, and whether the change is safe and correct. That gives the learner a simple foothold: GitHub Copilot can help you gather and understand information about code changes - especially when diffs are large, complex, or involve unfamiliar frameworks.

      -

      Jamie: Let's pause on When to Use Copilot During Code Review. What should a learner take away from it?

      -

      Alex: Start with When to Use Copilot During Code Review: Copilot is most useful for answering these questions.

      -

      Alex: First, "What does this code do?" - you're reading unfamiliar syntax or a framework you don't know well. Then, "Why might this change break something?" - you need to understand dependencies or side effects. After that, "Is this pattern safe?" - you want to verify that the approach follows best practices. Finally, "What would be a better way to write this?" - you're looking for alternatives to suggest. Think of it as a rail line: each stop confirms you are still on the right route before the next one.

      -

      Jamie: Before we leave When to Use Copilot During Code Review, what is the practical point?

      -

      Alex: First, "Does this match the PR's description?" - the change seems to do more (or less) than claimed. Treat it like a recipe: do not add the next ingredient until the previous one is actually in the bowl.

      -

      Jamie: Let's pause on In VS Code with an Open Diff. What should a learner take away from it?

      -

      Alex: Start with In VS Code with an Open Diff. There is something to understand, something to try, and something that proves the try worked.

      -

      Alex: First, open the PR using the GitHub Pull Requests extension (see Part 2). Then, open the diff for any file. After that, select a block of code that confuses you (highlight it). Finally, open Copilot Chat: Ctrl+Shift+I. Treat it like a recipe: do not add the next ingredient until the previous one is actually in the bowl.

      -

      Jamie: Before we leave In VS Code with an Open Diff, what is the practical point?

      -

      Alex: First, Copilot reads the selected code and answers in the chat. It is a checklist, but a meaningful one: every item creates evidence that the next step is safe.

      +

      Jamie: If I am listening before the workshop starts, what should settle in my mind first?

      +

      Alex: Here is the plain-English version of 3. Building Your Developer Portfolio. See also: Appendix X: Resources has links to every tool and resource mentioned in this course. Put another way, your GitHub profile is your portfolio.

      +

      Jamie: What does the learner do first, second, and then after that?

      +

      Alex: Start with Pin your best repositories. There is something to understand, something to try, and something that proves the try worked.

      +

      Alex: The room should hear these as checkpoints. Your fork of the accessibility-agents repository (shows open source contribution). Any personal projects you create after the workshop.

      +

      Alex: First, go to github.com/settings/profile. Then, scroll to "Pinned repositories.". After that, pin the repositories that show your best work. Consider. It is a checklist, but a meaningful one: every item creates evidence that the next step is safe.

      +

      Jamie: What is the one idea that makes the next few steps less mysterious?

      +

      Alex: Keep the learner anchored in Write a profile README. Your profile README is the first thing people see when they visit your GitHub profile. This is the part to say slowly: Create a repository with the same name as your username (e.g., your-username/your-username) and add a README.md.

      +

      Alex: A solid pull request habit is to separate three questions: what changed, why it changed, and what still needs review. That keeps the conversation useful instead of noisy.

      -

      Jamie: Let's pause on On GitHub.com (Web Interface). What should a learner take away from it?

      -

      Alex: This is where On GitHub.com (Web Interface) becomes real: another option: Use the GitHub Copilot inline suggestions on GitHub.com.

      -

      Alex: The practical takeaway is this. Some GitHub PRs show Copilot insights directly in the diff (as of early 2026). If you see a lightbulb icon, click it to see Copilot's suggestion about that line.

      -

      Alex: First, open the PR's Files Changed tab. Then, focus on a line or section you want to understand better. After that, in VS Code Copilot Chat (not in the browser - Copilot Chat doesn't work directly in browser diffs yet). Finally, copy the confusing code, paste it into chat, and ask Copilot to explain. It is a checklist, but a meaningful one: every item creates evidence that the next step is safe.

      -

      Alex: Keep the teaching thread moving. Keep the learner anchored in Copilot Limitations During Review (Critical to Know). This is why manual review is essential: You have context (project history, team decisions, user impact) that Copilot does not. This is the part to say slowly: Use Copilot to understand, then use your judgment to decide.

      -

      Alex: The practical takeaway is this. See the whole project - it sees only what you show it (the selected diff, not the context of the entire codebase). Verify correctness - it can explain what code does, but not whether it's correct for your specific use case. Understand intent - it reads the code, not the author's mind or the PR description. Catch all risks - it can spot common patterns, but not edge cases unique to your project.

      -

      Jamie: Let's pause on Best Practices. What should a learner take away from it?

      -

      Alex: Start with Best Practices. There is something to understand, something to try, and something that proves the try worked.

      -

      Alex: First, read the diff manually first - you spot the big picture before asking Copilot details. Then, ask Copilot specific questions - not "review this code" but "does this regex handle Unicode?". After that, fact-check Copilot's answers - it can be confidently wrong, especially about frameworks or domains it has less training data. Finally, combine Copilot with manual analysis - ask Copilot to explain, then verify by checking the PR description or looking for related files. The rhythm is simple: orient, act, verify, then continue.

      -

      Jamie: Before we leave Best Practices, what is the practical point?

      -

      Alex: First, use Copilot to draft comments - type Draft a comment about [issue] for this PR and edit Copilot's suggestion to match your tone. Think of it as a rail line: each stop confirms you are still on the right route before the next one.

      +

      Alex: Before the learner moves on. The reason Keep your contribution graph active matters is that the green squares on your GitHub profile show when you made contributions. That gives the learner a simple foothold: even small actions count: filing issues, opening PRs, making commits, and reviewing code. The interface gets friendlier when it stops being a wall of controls and starts being a set of named places.

      +

      Jamie: Give me the version that sounds like an instructor, not a manual.

      +

      Alex: Start with Learning Cards: Building Your Developer Portfolio. There is something to understand, something to try, and something that proves the try worked.

      +

      Alex: A few details make that real. Navigate to your profile settings at github.com/settings/profile -- the "Pinned repositories" section is a group of checkboxes; Tab through and press Space to pin or unpin. Your profile README repository must match your username exactly (case-sensitive) -- screen readers will read the rendered README as regular page content when visitors navigate your profile. The contribution graph is announced as a table or grid; arrow keys move between day cells, each announcing the date and contribution count. Pinned repositories appear as cards below your avatar -- at high zoom the 2x3 grid may reflow to a single column, which is easier to scan. The profile README renders with your current GitHub theme -- test yours in both light and dark modes to confirm text and images remain readable. Contribution graph squares use green intensity to show activity levels; enable high-contrast mode if the shading differences are hard to distinguish.

      +

      Alex: Hold that next to this. Here is the plain-English version of 4. Continued Learning Roadmap. See also: Appendix Z: GitHub Skills has the complete catalog of recommended GitHub Skills courses. Put another way, the workshop taught you the fundamentals.

      -

      Alex: Keep the teaching thread moving. Start with What Comes Next: Your manual code review skills - identifying heading issues, catching link text problems, understanding screen reader navigation, gathering information with Copilot - are the foundation for understanding automated review. The next useful detail is this: In Chapter 16 (Accessibility Agents), you'll meet a full team of agents designed to amplify these skills. Think of it like entering a new building: first you find the lobby, then the room, then the door you actually need.

      -

      Jamie: Let's pause on Part 4: The Reviewer's Craft. What should a learner take away from it?

      -

      Alex: Here is the plain-English version of The Reviewer's Craft. Parts 1 through 3 taught you the mechanics -- how to read diffs, leave comments, and use Copilot to understand unfamiliar code. Put another way, this part covers something equally important: how to think like a reviewer.

      -

      Alex: Keep the teaching thread moving. This is where What to Look for in a Review becomes real: every PR is different, but most reviews benefit from scanning across these five categories. That matters in practice: You do not need to check every category exhaustively on every PR.

      +

      Jamie: Where do you want a learner to place their attention here?

      +

      Alex: Start with Git and version control. There is something to understand, something to try, and something that proves the try worked.

      +

      Alex: For a learner, the useful signals are these. Pro Git book -- Free, comprehensive, and the official Git resource. Start with chapters 2 and 3. Appendix E: Advanced Git -- Rebasing, cherry-picking, stashing, and other techniques you will need eventually.

      +

      Alex: A solid Git habit is to know which branch you are on, what changed, and what confirmation you expect before you run the next command.

      +

      Alex: That connects to another useful point. Start with GitHub platform. There is something to understand, something to try, and something that proves the try worked.

      +

      Alex: The parts worth keeping in working memory are these. GitHub Docs -- The official documentation covers everything. Bookmark it. GitHub Skills -- Free, interactive courses that teach by doing (see Section 5 below). GitHub Blog -- Stay current with new features and best practices.

      +

      Jamie: What stays the same when the tool changes?

      +

      Alex: Start with VS Code. There is something to understand, something to try, and something that proves the try worked.

      +

      Alex: Here is what that changes in practice. VS Code documentation -- Complete reference for settings, keybindings, and extensions. VS Code accessibility documentation -- Deep dive into screen reader support, high contrast, and keyboard navigation.

      -

      Jamie: Let's pause on The Three Review Actions. What should a learner take away from it?

      -

      Alex: Keep the learner anchored in The Three Review Actions. When you submit a review on GitHub, you choose one of three actions. This is the part to say slowly: Picking the right one matters because it signals your intent to the author and to anyone else watching the PR.

      -

      Alex: First, did you find a bug, security issue, or broken test? -- Request Changes. Then, does the code do something different from what the description says? -- Request Changes. After that, does everything work, with maybe a few style nits? -- Approve (mention the nits in a comment). Finally, do you have questions or optional suggestions? -- Comment. It is like walking a hallway with named doors: read the sign, enter the right room, then confirm where you landed.

      -

      Alex: Keep the teaching thread moving. The reason Writing Constructive Feedback matters is that the way you phrase feedback determines whether the author feels supported or attacked. That gives the learner a simple foothold: before pointing out problems, acknowledge something the author did well. The interface gets friendlier when it stops being a wall of controls and starts being a set of named places.

      -

      Jamie: Let's pause on The Reviewer's Checklist. What should a learner take away from it?

      -

      Alex: Start with The Reviewer's Checklist: Run through this list mentally (or copy it into your notes) for every PR you review.

      -

      Alex: The practical takeaway is this. [ ] I read the PR description before reading the code. [ ] The code does what the description says it does. [ ] The change does not include unrelated modifications. [ ] Variable and function names are clear. [ ] I checked for accessibility: labels, headings, keyboard reach, contrast. [ ] I verified no existing behavior is broken by the change.

      +

      Alex: Here is the practical turn. Start with Accessibility. There is something to understand, something to try, and something that proves the try worked.

      +

      Alex: These are the details that keep the idea from floating away. Web Content Accessibility Guidelines (WCAG) 2.2 -- The quick reference version is the most practical. Appendix M: Accessibility Standards -- Workshop reference for WCAG criteria used in this course. WebAIM -- Practical accessibility resources, training, and tools. Deque University -- Free and paid courses on web accessibility.

      +

      Jamie: Let's pause on AI-assisted development. What should a learner take away from it?

      +

      Alex: Start with AI-assisted development. There is something to understand, something to try, and something that proves the try worked.

      +

      Alex: That becomes easier when you listen for these cues. GitHub Copilot documentation -- Official docs for Copilot features, configuration, and best practices. Appendix K: Copilot Reference -- Workshop quick-reference card. Appendix L: Agents Reference -- Full accessibility agents roster and command reference.

      +

      Alex: Keep the thread going. This is where 5. GitHub Skills Courses to Try Next becomes real: GitHub Skills offers free, interactive courses that run inside GitHub repositories. That matters in practice: Each course creates a repository in your account with step-by-step instructions and automated feedback -- the same model we used in this workshop. The workshop is closer to rehearsal than lecture. You hear the move, try the move, and then check what changed.

      -

      Alex: Keep the teaching thread moving. Here is the plain-English version of Reviewing as a Learning Tool. Reviewing is not just a gate to keep bad code out. Put another way, it is one of the fastest ways to grow as a developer.

      -

      Jamie: Let's pause on Learning Cards: The Reviewer's Craft. What should a learner take away from it?

      -

      Alex: Start with Learning Cards: The Reviewer's Craft. There is something to understand, something to try, and something that proves the try worked.

      -

      Alex: The practical takeaway is this. Jump between changed hunks in a diff with Alt+F5 (next change) and Shift+Alt+F5 (previous change) to scan for scope creep efficiently. Use Alt+F2 (Accessible View) on a Copilot-generated review summary to read the full text with arrow keys before posting. When leaving feedback, mention specific line numbers ("Line 42 skips from h2 to h4") so the author can navigate directly with Ctrl+G. The three review actions (Approve, Request Changes, Comment) are shown as clearly labeled radio buttons in the review submission form. Use the reviewer checklist in this section as a mental framework -- copy it into your notes and check items off as you review each PR. The diff view uses green and red backgrounds for added/removed lines; pair with a High Contrast theme if these colors are hard to distinguish.

      -

      Alex: Keep the teaching thread moving. Keep the learner anchored in Day 2 Teaser: The Full Accessibility Agents Review Ecosystem. Chapter 16 shows you how to leverage 50+ specialized agents to make your reviews faster, more consistent, and more thorough - while staying in full control of what you post. A good GitHub workflow is like a well-run meeting: everyone knows the topic, the next action, and who has the floor.

      +

      Jamie: Turn that into a path someone can follow.

      +

      Alex: Keep the learner anchored in How to start a course. Each course takes 15 to 60 minutes.

      +

      Alex: First, go to skills.github.com. Then, find a course and click its title. After that, click Start course (this creates a repository in your account). Finally, follow the instructions in the repository's README. It is like walking a hallway with named doors: read the sign, enter the right room, then confirm where you landed.

      +

      Alex: Another way to ground it. Start with Community Access. There is something to understand, something to try, and something that proves the try worked.

      +

      Alex: The practical takeaway is this. Community Access on GitHub -- The organization behind this workshop. Watch the repositories for updates. Workshop facilitators are available for questions after the event. Post on the learning-room repository or the git-going-with-github repository.

      +

      Jamie: Give me the sequence, because order matters here.

      +

      Alex: Start with Open source contribution: The capstone was your first contribution.

      +

      Alex: First, start with projects you use. If you use a tool or library and find a bug or missing documentation, that is your first issue. Then, look for "good first issue" labels. Many projects label issues that are suitable for new contributors. After that, documentation counts. Fixing typos, improving instructions, and adding examples are valuable contributions. Do not underestimate them. Finally, the fork workflow scales. The same fork, branch, commit, push, PR workflow from Chapter 18 works for every GitHub project. Think of it as a rail line: each stop confirms you are still on the right route before the next one.

      -

      Jamie: What do we want them to notice before they start over?

      -

      Alex: The reason The Agents That Help With Code Review matters is that accessibility Review Agents (when code affects UI/UX).

      -

      Alex: The practical takeaway is this. @pr-review - Generates a full-draft PR review with line-numbered diff maps, risk assessment, before/after snapshots, and suggested inline comments. You edit and post it under your name. @pr-author-checklist - Before you even submit your PR, use this to verify you haven't missed setup steps, accessibility checks, or documentation. @insiders-a11y-tracker - Monitors your PR for accessibility-sensitive changes: WCAG violations, heading hierarchy issues, link text quality, keyboard navigation impacts. @developer-hub - Orchestrates explanations for unfamiliar code, patterns, or frameworks you're reviewing. @python-specialist - If your PR contains Python code, this agent explains patterns, spots accessibility issues, and suggests improvements. @wxpython-specialist - For desktop GUI code, helps verify accessible widget patterns and focus management.

      -

      Jamie: Let's pause on How It Works. What should a learner take away from it?

      -

      Alex: First, review manually first (you just did this with Exercises A, B, C). Then, run an agent - @pr-review review PR 14 generates a draft in seconds. After that, edit the agent's draft - you add context, remove noise, correct errors. Finally, post your review - it now has both AI efficiency and your human judgment. Think of it as a rail line: each stop confirms you are still on the right route before the next one.

      -

      Jamie: Before we leave How It Works, what is the practical point?

      -

      Alex: First, the agent tracks impact - @insiders-a11y-tracker monitors whether your accessibility feedback was addressed. Treat it like a recipe: do not add the next ingredient until the previous one is actually in the bowl.

      -

      Jamie: Let's pause on The Principle: Skill First, Agent Second. What should a learner take away from it?

      -

      Alex: Here is the plain-English version of The Principle: Skill First, Agent Second. Why do this manually before using agents? Put another way, manual reviews teach you what to look for.

      -

      Alex: The practical takeaway is this. You understand what the agent is doing (you did it manually). You evaluate the agent's output critically (you know what right looks like). You add judgment the agent lacks (context, intent, team decisions). You verify the agent didn't miss anything important.

      +

      Alex: This is the part worth saying out loud. Start with Accessibility community. There is something to understand, something to try, and something that proves the try worked.

      +

      Alex: The practical takeaway is this. GitHub Accessibility documentation -- Official accessibility guides for GitHub's interface. WebAIM mailing list -- Active discussion forum for web accessibility practitioners. A11y Project -- Community-driven accessibility resources and checklist.

      +

      Jamie: How do the two days connect instead of feeling like separate courses?

      +

      Alex: This is where 7. Contributing Back to This Workshop becomes real: if you found something confusing, incorrect, or missing, you can fix it.

      +

      Jamie: What is the ordered workflow?

      +

      Alex: Keep the learner anchored in The contribution workflow. You have already practiced every step of this workflow.

      +

      Alex: First, fork the git-going-with-github repository. Then, clone your fork, create a branch, make your edit. After that, open a PR with a clear title and description. Finally, mention the chapter number and section in your PR. It is like walking a hallway with named doors: read the sign, enter the right room, then confirm where you landed.

      -

      Jamie: Let's pause on A Real Example: The Flow. What should a learner take away from it?

      -

      Alex: This is where A Real Example: The Flow becomes real: manual Review (your work in part 1-2). That matters in practice: Agent-Assisted Review (what you'll do in Chapter 19). The workshop is closer to rehearsal than lecture. You hear the move, try the move, and then check what changed.

      -

      Alex: The practical takeaway is this. Read diff, identify heading hierarchy skip. Write comment explaining why it matters. Submit your verdict.

      -

      Alex: First, run: @pr-review review PR 14. Then, agent generates a draft review covering the heading skip, link text, and 5 other issues. After that, you read the draft and notice: "the agent's explanation of the heading skip is good, but it missed that the link text on line 23 is still vague. Let me add that.". Finally, you post the agent's review + your additions. It is a checklist, but a meaningful one: every item creates evidence that the next step is safe.

      -

      Jamie: Before we leave A Real Example: The Flow, what is the practical point?

      -

      Alex: First, next time you review a similar PR, the agent works faster because it learned from your feedback. It is like walking a hallway with named doors: read the sign, enter the right room, then confirm where you landed.

      +

      Jamie: Where is the promise of the workshop, underneath all the logistics?

      +

      Alex: Start with Learning Cards: Contributing Back to This Workshop. There is something to understand, something to try, and something that proves the try worked.

      +

      Alex: The practical takeaway is this. The contribution workflow here is identical to Chapter 18 (Fork and Contribute) -- fork, clone, branch, edit, push, PR; use the same keyboard and screen reader patterns you already practiced. When filing an issue, include the chapter number and section heading in the title so maintainers can locate the problem with heading navigation. After opening a PR, listen for the automated check results in the PR timeline -- each check is announced as a link with its pass/fail status. The contribution types table above maps each kind of contribution to its workflow -- zoom in on the "How to do it" column for the quickest path. When editing documentation in your fork, use VS Code's Markdown Preview (Ctrl+Shift+V) at your preferred zoom level to verify formatting before pushing. PR descriptions render as Markdown on GitHub -- use headings and lists so reviewers can scan your changes at any zoom level.

      +

      Alex: This is where the talk moves from concept to action. Start with 8. Final Words: Now you have filed issues, opened pull requests, resolved conflicts, reviewed code, and contributed to a real open source project. The next useful detail is this: Every expert started exactly where you are standing. Think of it like entering a new building: first you find the lobby, then the room, then the door you actually need.

      -

      Jamie: What is the final checkpoint?

      -

      Alex: You should be able to point to the evidence, explain the action, and describe what you would do next if this were a real open source project. If you can teach the move back, you have learned it.

      -

      Jamie: And if they get stuck?

      -

      Alex: Read the latest message, not the loudest worry. Check the issue, the branch, the pull request, the status check, or the bot comment. Then ask for help with those facts in hand. That is how professionals collaborate.

      +

      Jamie: What should people carry with them after this?

      +

      Alex: Carry the map. Know what page or tool you are in, know which action you are taking, and know what confirmation should follow. If the confirmation is missing, pause. That pause is not wasted time; it is professional judgment.

      +

      Jamie: That is a better way to say it than just follow the steps.

      +

      Alex: Right. Steps matter, but understanding wins. That is episode 49. Next in the series is episode 50, where we keep building the same contributor muscles.

      -

      Challenge bonus-d: Notifications

      -

      Notification hygiene, mentions, subscriptions, and avoiding overload.

      +

      72. Episode 50: Advanced Git Operations

      +

      Cherry-pick, rebase, revert, reset, tags, bisect, clean, and other Git recovery tools.

      +

      Based on: Appendix E: Advanced Git Operations

      +

      Audio and transcript are being regenerated for this episode.

      -Read Transcript - Challenge bonus-d: Notifications +Read Transcript - Episode 50: Advanced Git Operations

      Transcript

      -

      Alex: Welcome to Challenge Coach: Notifications. I am Alex. Before you do the task, we are going to make the skill feel concrete enough to practice.

      -

      Jamie: And I am Jamie. I will keep asking what the learner should do, what evidence counts, and how to recover if the page does something unexpected.

      +

      Alex: This is Git Going with GitHub, episode 50: Advanced Git Operations. I am Alex. By the end of this episode, Advanced Git Operations should feel less like a wall of GitHub words and more like a set of moves you can trust.

      +

      Jamie: And I am Jamie. I am here for the practical questions: what should I listen for, what can go wrong, and what is the next calm move?

      -

      Alex: The skill focus is Notification hygiene, mentions, subscriptions, and avoiding overload. This is rehearsal for real contribution, so the evidence matters because it proves the move happened.

      -

      Jamie: So the challenge has to leave the learner with both confidence and a trail of evidence.

      -

      Alex: Exactly. Evidence is not busywork. It is how a learner, a facilitator, and a future maintainer can understand what changed and why.

      +

      Alex: Today we are working on this: Cherry-pick, rebase, revert, reset, tags, bisect, clean, and other Git recovery tools. I want the learner to leave with a mental map, not just a remembered path through buttons.

      +

      Jamie: So the goal is understanding first, then action, then confirmation.

      +

      Alex: Right. We are building a rhythm: orient yourself, take one intentional action, then verify what changed before moving on.

      Jamie: Okay, set the room for us. What are we walking into?

      -

      Alex: Start with Bonus D: Notification Mastery: For students who: Want to practice inbox management and notification configuration. The next useful detail is this: What you will do: Configure your GitHub notification settings for a productive workflow, then demonstrate your setup.

      -

      Alex: A solid project habit is to treat metadata as decision support. Labels, status, assignees, and notifications tell you what kind of attention the work needs.

      -

      Alex: The next layer is this. Here is the plain-English version of Notification configuration checklist. Go to github.com/settings/notifications and configure. It is like learning a transit route. The names of the stops matter because they tell you whether you are still going the right direction.

      -

      Alex: The practical anchors are these. [ ] Email notifications: Choose which events trigger emails. [ ] Web notifications: Configure the notification inbox on GitHub.com. [ ] Watching: Review which repositories you are watching and adjust. [ ] Custom routing: If you have multiple email addresses, set up routing rules. [ ] GitHub Mobile: If you use the mobile app, configure push notification preferences.

      -

      Jamie: What does the learner do first, second, and then after that?

      -

      Alex: This is where Demonstrate your setup becomes real: after configuring, answer these questions. That matters in practice: I am watching repositories because.

      -

      Alex: First, how will you know when someone requests your review? Then, how will you avoid being overwhelmed by notifications from busy repositories? After that, what is your strategy for the GitHub notification inbox (read all, triage, filter)? It is a checklist, but a meaningful one: every item creates evidence that the next step is safe.

      +

      Alex: Start with Going Deeper with Git: Who this is for: You have completed Chapter 11 (Git & Source Control) and feel comfortable with the basics -- cloning, branching, committing, pushing, and pulling. The next useful detail is this: This appendix covers the next tier of Git skills that come up constantly in real open source contribution: cherry-picking fixes across branches, cleaning up messy commit history before a PR, safely undoing mistakes, and understanding why your push sometimes.

      +

      Alex: A solid Git habit is to know which branch you are on, what changed, and what confirmation you expect before you run the next command.

      +

      Alex: The next layer is this. Start with Learning Cards: Using This Advanced Git Reference. There is something to understand, something to try, and something that proves the try worked.

      +

      Alex: The practical anchors are these. Each operation is a numbered h2 section with three sub-paths: VS Code, GitHub CLI, and Git CLI. Use H to jump between operations and 3 to jump between the tool-specific sub-headings within each. The Table of Contents above has anchor links -- activate any link to jump directly to that operation. Command examples are in labeled code blocks -- increase zoom and each command fits on one line. Every section follows the same structure: what it is, when to use it, then tool-specific steps. The Quick Reference table near the bottom gives a one-row-per-operation summary for fast lookup.

      +

      Jamie: What is the one idea that makes the next few steps less mysterious?

      +

      Alex: This is where 1. Cherry-Pick -- Grabbing a Specific Commit becomes real: what it is: Cherry-pick lets you take a single commit from any branch and apply it to your current branch. That matters in practice: Think of it like copy-pasting a specific change -- without bringing the entire branch along with it.

      +

      Alex: That shows up in the workshop in a few specific ways. You fixed a bug on a feature branch, but main also needs that fix right now. A teammate landed a commit on their branch and you need just that one change. You accidentally committed to the wrong branch and need to move that commit somewhere else.

      -

      Alex: Now bring the learner back to the room. Keep the learner anchored in Before: Default settings. With default settings, GitHub sends email notifications. This is the part to say slowly: Most people start ignoring all GitHub emails.

      -

      Alex: For a learner, the useful signals are these. Every issue and PR in every repository you watch. Every comment on any thread you have participated in. Every CI status update.

      -

      Jamie: What would you say to someone who is already bracing for this to be too much?

      -

      Alex: Start with Notification settings (github.com/settings/notifications). There is something to understand, something to try, and something that proves the try worked.

      -

      Alex: The parts worth keeping in working memory are these. Participating: Email ON, Web ON -- you want to know when someone replies to your conversations. Watching: Email OFF, Web ON -- browse these when you have time, not in your inbox. GitHub Actions: Email OFF for successful runs, Email ON for failed runs only.

      -

      Alex: That matters because of the next idea. Start with Repository watching. There is something to understand, something to try, and something that proves the try worked.

      -

      Alex: On the ground, that means a few things. Repositories you actively contribute to: Watch (all activity). Repositories you read occasionally: Custom (issues and PRs only). Repositories you finished with: Unwatch.

      +

      Alex: Now bring the learner back to the room. Keep the learner anchored in Finding the Commit SHA. Before cherry-picking, you need the commit's SHA (the unique ID for that commit).

      +

      Jamie: What is the ordered workflow?

      +

      Alex: Start with VS Code. There is something to understand, something to try, and something that proves the try worked.

      +

      Alex: First, open the Timeline panel: Click View → Open View → Timeline (or press Ctrl+Shift+P and type "Timeline"). Then, switch to the branch that has the commit you want, browse the Timeline, and copy the commit SHA shown in the details panel. The rhythm is simple: orient, act, verify, then continue.

      Alex: The useful habit is simple: orient first, act second, verify third. That pause before acting is part of the work.

      +

      Jamie: How do you keep commands from becoming magic words?

      +

      Alex: Start with Git CLI: The short SHA is the first 7 characters (a1b2c3d). Think of it like entering a new building: first you find the lobby, then the room, then the door you actually need.

      +

      Alex: Treat examples as spoken recipes, not decorations. You may hear something like See commits on another branch without switching to it; git log feature/bug-fix --oneline; Output:; a1b2c3d Fix null pointer error in auth module; e4f5g6h Add unit tests for login. Read the command, understand what it changes, then run it only when the repository state matches the lesson.

      -

      Jamie: If I am listening before the workshop starts, what should settle in my mind first?

      -

      Alex: Start with Custom routing (if you use multiple emails). There is something to understand, something to try, and something that proves the try worked.

      -

      Alex: Here is what that changes in practice. Route Community-Access organization notifications to your workshop email. Route personal project notifications to your personal email.

      -

      Alex: This is where the talk moves from concept to action. Start with Key decisions explained. There is something to understand, something to try, and something that proves the try worked.

      -

      Alex: The room should hear these as checkpoints. Why email off for watching: You can check the notification bell on github.com when you choose. Email notifications for watched repos create constant interruption for low-priority updates. Why Actions failures only: A green checkmark in the PR is enough. You only need an email when something breaks. Why unwatch finished repos: Your notification feed stays relevant to current work.

      -

      Jamie: What is the one idea that makes the next few steps less mysterious?

      -

      Alex: Keep the learner anchored in What matters. The learning objective is intentional notification management. This is the part to say slowly: If you changed at least one setting from the default and can explain why that change reduces noise while keeping you informed about what matters, you completed this bonus.

      -
      -

      Alex: Before the learner moves on. The reason Managing Your GitHub Notification Inbox matters is that see also: Appendix V: GitHub Mobile for managing notifications on your phone. That gives the learner a simple foothold: GitHub notifications are how GitHub tells you when something needs your attention. The interface gets friendlier when it stops being a wall of controls and starts being a set of named places.

      -

      Jamie: How should they picture the shape of the workshop?

      -

      Alex: Start with Workshop Recommendation (Chapter 10): For this workshop, Chapter 10 is a guided practice chapter, not a graded automation chapter.

      -

      Alex: A few details make that real. There are 1 guided walkthrough. Automation check: none - notification settings are account-level and cannot be validated by the Learning Room PR bot. The evidence is structured completion comment on your assigned challenge issue. The pattern is configure, filter, act.

      Jamie: How would you walk the room through that step by step?

      -

      Alex: Start with Chapter 10 Challenge Set. There is something to understand, something to try, and something that proves the try worked.

      -

      Alex: First, configure notifications and practice inbox management - set your watch level, use filters to find relevant notifications, and perform one inbox action. Treat it like a recipe: do not add the next ingredient until the previous one is actually in the bowl.

      +

      Alex: Start with VS Code (Command Palette). There is something to understand, something to try, and something that proves the try worked.

      +

      Alex: First, press Ctrl+Shift+P (or Cmd+Shift+P on macOS). Then, type "cherry" and select "Git: Cherry Pick.". After that, paste or type the commit SHA. Finally, press Enter -- VS Code applies the commit to your current branch. Treat it like a recipe: do not add the next ingredient until the previous one is actually in the bowl.

      +

      Jamie: What should happen before anyone copies and runs it?

      +

      Alex: This is where GitHub CLI becomes real: the GitHub CLI doesn't have a direct cherry-pick command (it's a local Git operation), but you can use it to find the SHA first.

      +

      Alex: Treat examples as spoken recipes, not decorations. You may hear something like List commits on a branch via gh to find the one you want; gh api repos/{owner}/{repo}/commits?sha=feature/bug-fix --jq '.[].sha,.[].commit.message' head -20; Then cherry-pick using git; git cherry-pick a1b2c3d. Read the command, understand what it changes, then run it only when the repository state matches the lesson.

      +

      Jamie: What should they understand before typing anything?

      +

      Alex: Start with Git CLI. There is something to understand, something to try, and something that proves the try worked.

      +

      Alex: Treat examples as spoken recipes, not decorations. You may hear something like Apply a single commit; git cherry-pick a1b2c3d; Apply a range of commits (from older to newer, exclusive of first); git cherry-pick a1b2c3d.e4f5g6h; Apply without automatically committing (lets you review changes first); git cherry-pick --no-commit a1b2c3d. Read the command, understand what it changes, then run it only when the repository state matches the lesson.

      -

      Jamie: Turn that into a path someone can follow.

      -

      Alex: This is where Challenge 10.1 Step-by-Step: Notification Inbox Walkthrough becomes real: set up a useful notification workflow so you can keep up with reviews, mentions, and assignments without inbox overload. That matters in practice: the GitHub.com notifications page and your Learning Room repository settings.

      -

      Alex: That shows up in the workshop in a few specific ways. Press M to mute the thread (you will not receive future updates),. Press E to mark done (removes it from inbox but you can still get future updates).

      -

      Alex: First, open your Learning Room repository on GitHub.com. Then, find the Watch button near the top-right of the repository page (next to Star and Fork). After that, 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. Finally, open the notifications inbox by navigating to https://github.com/notifications (or activate the bell icon in the GitHub header). It is a checklist, but a meaningful one: every item creates evidence that the next step is safe.

      -

      Jamie: What is the ordered workflow?

      -

      Alex: First, in the notification filters, activate the Review requested filter. This shows only notifications where someone has asked you to review their PR. Then, clear that filter and activate the Assigned filter. This shows notifications for issues and PRs assigned to you. After that, open one notification by activating its title link. Read it briefly, then navigate back to the inbox. Finally, perform one inbox action on a non-critical notification thread. It is like walking a hallway with named doors: read the sign, enter the right room, then confirm where you landed.

      -

      Alex: That connects to another useful point. Keep the learner anchored in Completing Chapter 10: Submit Your Evidence. Open your assigned Chapter 10 challenge issue and post a completion comment. This is the part to say slowly: Close your Chapter 10 challenge issue when done. A good GitHub workflow is like a well-run meeting: everyone knows the topic, the next action, and who has the floor.

      +

      Jamie: Give me the sequence, because order matters here.

      +

      Alex: The reason If There's a Conflict matters is that cherry-pick can hit conflicts just like a merge. That gives the learner a simple foothold: when a cherry-pick stops due to a conflict, run git status in the terminal -- it announces exactly which files need attention. The interface gets friendlier when it stops being a wall of controls and starts being a set of named places.

      +

      Alex: First, Git pauses and marks the conflicting files (same <<<<<<< HEAD markers as merge conflicts). Then, resolve the conflicts in VS Code's conflict editor (see Chapter 7: Merge Conflicts). After that, stage the resolved files. Finally, then either. The rhythm is simple: orient, act, verify, then continue.

      +

      Alex: Treat examples as spoken recipes, not decorations. You may hear something like Continue the cherry-pick after resolving; git cherry-pick --continue; Or cancel it entirely and go back to where you started; git cherry-pick --abort. Read the command, understand what it changes, then run it only when the repository state matches the lesson.

      +

      Jamie: What would you say to someone who is already bracing for this to be too much?

      +

      Alex: Start with 2. Interactive Rebase -- Cleaning Up Your History: What it is: Interactive rebase (git rebase -i) is like a time machine for your commits. The next useful detail is this: Before you open a PR, you can reorder commits, combine several small commits into one clean commit, rewrite commit messages, or remove commits that were just experiments.

      +

      Alex: A few details make that real. You made 8 "WIP" commits while working and want to combine them into 1 clean commit for your PR. You want to reword a commit message to better describe what changed. You accidentally committed a debug file and want to remove that commit entirely.

      +

      Jamie: What does the learner do first, second, and then after that?

      +

      Alex: Here is the plain-English version of VS Code. VS Code has basic rebase support via the Command Palette, but for full interactive rebase you'll want the terminal. Put another way, after that, git rebase -i will open the commit list in VS Code itself -- much more screen-reader-friendly.

      +

      Alex: First, open the Integrated Terminal: Ctrl+Backtick. Then, run the command below to rebase the last N commits (replace N with how many commits you want to edit). After that, your default editor opens with a list of your commits. If it opens in vim, type i to enter insert mode, make your edits, then press Esc followed by:wq to save. If you'd prefer VS Code as the editor. Treat it like a recipe: do not add the next ingredient until the previous one is actually in the bowl.

      +

      Alex: Treat examples as spoken recipes, not decorations. You may hear something like git rebase -i HEAD 3; This opens your last 3 commits for editing. git config --global core.editor "code --wait". Read the command, understand what it changes, then run it only when the repository state matches the lesson.

      +
      +

      Jamie: What is the safe way to learn from that example?

      +

      Alex: Start with Git CLI (Terminal). There is something to understand, something to try, and something that proves the try worked.

      +

      Alex: Treat examples as spoken recipes, not decorations. You may hear something like Rebase the last 3 commits; git rebase -i HEAD 3; Or rebase everything since you branched from main; git rebase -i main. Read the command, understand what it changes, then run it only when the repository state matches the lesson.

      +

      Alex: That connects to another useful point. Keep the learner anchored in The Commit List -- What You're Looking At. When the editor opens, you see something like this. This is the part to say slowly: Each line starts with a command word. A good GitHub workflow is like a well-run meeting: everyone knows the topic, the next action, and who has the floor.

      Jamie: Where do you want a learner to place their attention here?

      -

      Alex: Start with Expected Outcomes. There is something to understand, something to try, and something that proves the try worked.

      -

      Alex: These are the details that keep the idea from floating away. 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.

      +

      Alex: The reason Example: Squashing 3 Commits Into 1 matters is that Git opens a second editor for you to write the combined commit message. That gives the learner a simple foothold: write a clean summary and save -- done.

      -

      Jamie: Give me the sequence, because order matters here.

      -

      Alex: Start with If You Get Stuck. There is something to understand, something to try, and something that proves the try worked.

      -

      Alex: First, can't find the Watch button? It is near the top-right of the repository page, in the same row as Star and Fork. Then, 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. After that, 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. Finally, filters not showing results? Clear all filters first (click the X next to each active filter), then apply one filter at a time. Think of it as a rail line: each stop confirms you are still on the right route before the next one.

      -

      Jamie: Let's pause on If You Get Stuck. What should a learner take away from it?

      -

      Alex: First, ask facilitator to model one inbox action live, then repeat the steps yourself. Then, finished but not sure you did it right? Compare your work against the Challenge 9 reference solution. Treat it like a recipe: do not add the next ingredient until the previous one is actually in the bowl.

      +

      Alex: Here is the practical turn. Start with Example: Rewriting a Commit Message: Git opens the commit message for a1b2c3d for you to edit. The next useful detail is this: Write the new message, save -- done.

      +

      Jamie: Let's pause on If Something Goes Wrong. What should a learner take away from it?

      +

      Alex: Here is the plain-English version of If Something Goes Wrong. Run git rebase -i with VS Code as your editor (git config --global core.editor "code --wait") -- the commit list opens in a VS Code tab that your screen reader can navigate normally with arrow keys. Put another way, GitHub Copilot can help: Not sure how to word a squashed commit message?

      +

      Alex: Treat examples as spoken recipes, not decorations. You may hear something like Abort the rebase and go back to where you started; git rebase --abort; If you're mid-rebase and hit a conflict, resolve it then continue; git rebase --continue. Read the command, understand what it changes, then run it only when the repository state matches the lesson.

      +

      Alex: Keep the thread going. This is where 3. git reset -- Undoing at Different Depths becomes real: what it is: git reset moves the tip of your current branch backward to a previous commit. That matters in practice: The three modes (--soft, --mixed, --hard) control what happens to the changes that were in those commits. The workshop is closer to rehearsal than lecture. You hear the move, try the move, and then check what changed.

      +

      Alex: The room should hear these as checkpoints. You committed too early and want to add more changes to that commit. You staged the wrong files and want to unstage them. You want to completely throw away the last few commits and start fresh.

      +

      Alex: A solid pull request habit is to separate three questions: what changed, why it changed, and what still needs review. That keeps the conversation useful instead of noisy.

      +
      +

      Jamie: If I am listening before the workshop starts, what should settle in my mind first?

      +

      Alex: Keep the learner anchored in The Three Modes. Think of Git as having three layers: your working files (what you can see in the editor), the staging area (what git add puts there), and the commit history. This is the part to say slowly: It permanently discards your uncommitted changes.

      +

      Jamie: Turn that into a path someone can follow.

      +

      Alex: The reason Using the Source Control panel matters is that this is equivalent to git reset --soft HEAD 1 -- your changes come back as staged files, nothing is lost.

      +

      Alex: First, open Source Control: Ctrl+Shift+G. Then, click the "." (More Actions) menu at the top of the panel. After that, select "Commit → Undo Last Commit". The rhythm is simple: orient, act, verify, then continue.

      +

      Jamie: Let's pause on Using the Command Palette. What should a learner take away from it?

      +

      Alex: Start with Using the Command Palette. There is something to understand, something to try, and something that proves the try worked.

      +

      Alex: Treat examples as spoken recipes, not decorations. You may hear something like Ctrl+Shift+P → type "git undo" → select "Git: Undo Last Commit". Read the command, understand what it changes, then run it only when the repository state matches the lesson.

      +
      +

      Jamie: Let's pause on Git CLI. What should a learner take away from it?

      +

      Alex: Treat examples as spoken recipes, not decorations. You may hear something like Undo last commit -- keep changes staged (safest); git reset --soft HEAD 1; Undo last commit -- keep changes but unstage them; git reset --mixed HEAD 1; Undo last 3 commits -- keep all changes unstaged; git reset --mixed HEAD 3; Undo last commit -- DISCARD all. Read the command, understand what it changes, then run it only when the repository state matches the lesson.

      Jamie: Give me the version that sounds like an instructor, not a manual.

      -

      Alex: Here is the plain-English version of Learning Moment. Notification management protects focus. Put another way, you can stay responsive to your team without drowning in updates.

      -

      Jamie: Let's pause on Learning Pattern Used in This Chapter. What should a learner take away from it?

      -

      Alex: Start with Learning Pattern Used in This Chapter. There is something to understand, something to try, and something that proves the try worked.

      -

      Alex: First, configure settings proactively (watch level) before work generates noise. Then, use filters to find signal in noise (review requests, assignments). After that, take decisive action on each notification (mute, done, or respond). Finally, build a daily routine that keeps your inbox manageable. It is a checklist, but a meaningful one: every item creates evidence that the next step is safe.

      +

      Alex: This is where Unstaging a File (Without Undoing the Commit) becomes real: if you just want to remove a file from the staging area without touching commit history.

      +

      Alex: That matters because of the next idea. Keep the learner anchored in VS Code. In the Source Control panel, click the minus (--) icon next to a staged file, or right-click it and select "Unstage Changes".

      -

      Jamie: Let's pause on What Generates a Notification? What should a learner take away from it?

      -

      Alex: Keep the learner anchored in What Generates a Notification? GitHub sends you a notification when.

      -

      Alex: Another way to ground it. The reason Notification Subscription Levels matters is that for each repository, you choose how many notifications to receive.

      -

      Jamie: Let's pause on Changing your watch settings for a repo. What should a learner take away from it?

      -

      Alex: Start with Changing your watch settings for a repo: At the top of any repository page, find the Watch button (near Star and Fork). The next useful detail is this: Click it to open a dropdown with levels: Participating and @mentions, All Activity, Custom, and Ignore.

      -

      Alex: First, find the Watch button in the repo header (B to navigate buttons → find "Watch [N]" or "Unwatch" button). Then, press Enter to open the dropdown. After that, press ↑/↓ to navigate the subscription options. Finally, press Enter to select your preferred level. Think of it as a rail line: each stop confirms you are still on the right route before the next one.

      -

      Jamie: Before we leave Changing your watch settings for a repo, what is the practical point?

      -

      Alex: First, the button label updates to confirm your choice. Then, quick Nav B to find the Watch button in the repo header (listen for "Watch" or "Unwatch"). After that, vO+Space to open the dropdown. Finally, vO+Down or arrow keys to navigate subscription options. Treat it like a recipe: do not add the next ingredient until the previous one is actually in the bowl.

      +

      Jamie: Before we leave Git CLI, what is the practical point?

      +

      Alex: Treat examples as spoken recipes, not decorations. You may hear something like Unstage a specific file; git restore --staged docs/README.md; Unstage everything; git restore --staged. Read the command, understand what it changes, then run it only when the repository state matches the lesson.

      +

      Alex: This is where the talk moves from concept to action. Start with 4. git revert -- The Safe Undo for Shared Branches: What it is: git revert creates a new commit that undoes the changes from a previous commit. The next useful detail is this: Unlike git reset, it does not rewrite history -- it adds to it. Think of it like entering a new building: first you find the lobby, then the room, then the door you actually need.

      +

      Alex: On the ground, that means a few things. A commit made it to main and it broke something -- you need to roll it back without force-pushing. You want to undo a change but keep a record that the undo happened. You're working on a protected branch where force-push is disabled.

      +

      Jamie: Let's pause on VS Code. What should a learner take away from it?

      +

      Alex: First, open the Timeline panel and navigate to the commit you want to undo. Then, right-click the commit and select "Revert Commit". After that, VS Code creates a new commit with message Revert "your original message" -- review it and push. Treat it like a recipe: do not add the next ingredient until the previous one is actually in the bowl.

      -

      Jamie: Let's pause on Tool Cards: Manage Notifications. What should a learner take away from it?

      -

      Alex: Here is the plain-English version of Tool Cards: Manage Notifications. VS Code Desktop (GitHub Pull Requests extension). Put another way, GitHub Desktop: GitHub Desktop does not manage notifications. It is like learning a transit route. The names of the stops matter because they tell you whether you are still going the right direction.

      -

      Alex: First, go to github.com/notifications (or press G then N). Then, use E to mark done, I to mark read/unread, Shift+M to mute a thread. After that, the Notifications view in the GitHub sidebar shows items needing attention. Finally, click a notification to open the related issue or PR directly in VS Code. Treat it like a recipe: do not add the next ingredient until the previous one is actually in the bowl.

      -

      Alex: Treat examples as spoken recipes, not decorations. You may hear something like 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. 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. Read the command, understand what it changes, then run it only when the repository state matches the lesson.

      -

      Jamie: Let's pause on Navigating the notification list. What should a learner take away from it?

      -

      Alex: This is where Navigating the notification list becomes real: the inbox shows notifications grouped by date (Today, Yesterday, This week, Older). That matters in practice: Each row shows the repository, the issue or PR title, the event type, and the time.

      -

      Alex: First, d → main content landmark. Then, h to navigate group headings (Today / Yesterday / This week / Older). After that, tab through individual notifications - each row announces: repo name, issue/PR title, event type, time. Finally, enter to open the notification (goes to the issue/PR page). It is a checklist, but a meaningful one: every item creates evidence that the next step is safe.

      -

      Jamie: Before we leave Navigating the notification list, what is the practical point?

      -

      Alex: First, vO+U → Main → navigate to notification list. Then, vO+Down to move through notifications. After that, vO+Space to open a notification. It is like walking a hallway with named doors: read the sign, enter the right room, then confirm where you landed.

      -

      Alex: Here is the practical turn. Keep the learner anchored in What is announced per notification. "microsoft/vscode - Add keyboard shortcut for accessible view - @username mentioned you - 2 hours ago". This is the part to say slowly: Components: repo/org thread title event type timestamp.

      +

      Jamie: What is the teaching move inside Git CLI?

      +

      Alex: Treat examples as spoken recipes, not decorations. You may hear something like Revert a specific commit (opens editor to confirm the message); git revert a1b2c3d; Revert without opening the editor (uses default message); git revert --no-edit a1b2c3d; Stage the revert but don't commit yet (lets you edit the message manually); git revert. Read the command, understand what it changes, then run it only when the repository state matches the lesson.

      +

      Jamie: How should someone choose between those options?

      +

      Alex: Keep the learner anchored in When to Use revert vs reset. GitHub Copilot can help: Not sure whether to use reset or revert? This is the part to say slowly: Describe your situation to Copilot Chat: "I pushed a commit to main that broke the login page.

      +

      Alex: Use the comparison to make a decision, not to recite a table. The main contrasts are: Commit is only local (not pushed) means git reset -- cleaner, no extra commit. Commit is on a shared branch (main, dev) means git revert -- preserves history, safe for others. Branch has protection rules (no force push) means git revert -- the only option.

      +

      Alex: Another way to ground it. The reason 5. Tags -- Marking Important Moments matters is that what it is: A tag is a permanent label you attach to a specific commit -- usually to mark a release version like v1.0.0. That gives the learner a simple foothold: unlike a branch (which moves as you commit), a tag always points to the exact same commit forever. The interface gets friendlier when it stops being a wall of controls and starts being a set of named places.

      +

      Alex: That becomes easier when you listen for these cues. Releasing a new version of a project. Marking a stable checkpoint before starting a big refactor. Documenting when a major feature shipped.

      -

      Jamie: Let's pause on Learning Cards: The Notifications Inbox. What should a learner take away from it?

      -

      Alex: Start with Learning Cards: The Notifications Inbox. There is something to understand, something to try, and something that proves the try worked.

      -

      Alex: That becomes easier when you listen for these cues. 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. 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.

      -

      Alex: Keep the thread going. Start with Inbox Actions - Keyboard Shortcuts: These shortcuts work when a notification is focused in the inbox. The next useful detail is this: These are GitHub's own keyboard shortcuts. Think of it like entering a new building: first you find the lobby, then the room, then the door you actually need.

      -

      Alex: A solid navigation habit is to prove where you are before activating controls. Headings, landmarks, and the address bar are not trivia; they are your map.

      -

      Jamie: Let's pause on Filtering the Inbox. What should a learner take away from it?

      -

      Alex: Here is the plain-English version of Filtering the Inbox. The left sidebar has quick filters.

      +

      Jamie: Let's pause on VS Code (Command Palette). What should a learner take away from it?

      +

      Alex: Start with VS Code (Command Palette): Type the tag name (e.g., v1.2.0) and optionally a message.

      +

      Alex: Treat examples as spoken recipes, not decorations. You may hear something like Ctrl+Shift+P → type "git tag" → select "Git: Create Tag". Read the command, understand what it changes, then run it only when the repository state matches the lesson.

      +

      Jamie: Let's pause on GitHub CLI. What should a learner take away from it?

      +

      Alex: Start with GitHub CLI. There is something to understand, something to try, and something that proves the try worked.

      +

      Alex: Treat examples as spoken recipes, not decorations. You may hear something like Create a tag and push it to GitHub in one step (using the API); gh release create v1.2.0 --title "Version 1.2.0" --notes "Bug fixes and accessibility improvements"; This creates both a GitHub Release and the underlying tag. Read the command, understand what it changes, then run it only when the repository state matches the lesson.

      +

      Jamie: If someone only remembers one thing from Git CLI, what should it be?

      +

      Alex: Treat examples as spoken recipes, not decorations. You may hear something like Create a lightweight tag at the current commit; git tag v1.2.0; Create an annotated tag (recommended for releases); git tag -a v1.2.0 -m "Release version 1.2.0 - bug fixes and accessibility improvements"; Tag a specific past commit; git tag -a v1.1.5 a1b2c3d. Read the command, understand what it changes, then run it only when the repository state matches the lesson.

      -

      Jamie: Let's pause on Filtering by repository or organization. What should a learner take away from it?

      -

      Alex: This is where Filtering by repository or organization becomes real: at the top of the notification list there is a filter/search field. That matters in practice: Click the filter/search box at the top of the notification list and type a repository or organization name.

      -

      Alex: First, press F or E to reach the filter input. Then, focus Mode → type repo name or org name. After that, results filter in real time. Finally, press Esc to clear the filter. It is a checklist, but a meaningful one: every item creates evidence that the next step is safe.

      -

      Jamie: Before we leave Filtering by repository or organization, what is the practical point?

      -

      Alex: First, quick Nav F to reach the filter input. Then, vO+Shift+Down to interact → type repo or org name. After that, press Esc to clear the filter and VO+Shift+Up to stop interacting. It is like walking a hallway with named doors: read the sign, enter the right room, then confirm where you landed.

      -

      Jamie: Let's pause on The "mark all as done" workflow. What should a learner take away from it?

      -

      Alex: Keep the learner anchored in The "mark all as done" workflow. After a busy day or coming back from time away, clear your inbox methodically.

      -

      Alex: First, open Notifications inbox. Then, tab to "Mark all as done" button → Enter (clears everything at once). After that, then use the "Done" filter to retrieve any you want to revisit. It is like walking a hallway with named doors: read the sign, enter the right room, then confirm where you landed.

      -

      Jamie: Let's pause on Muting a noisy thread. What should a learner take away from it?

      -

      Alex: The reason Muting a noisy thread matters is that if a thread generates too many notifications. That gives the learner a simple foothold: screen reader users (NVDA / JAWS - Windows). The interface gets friendlier when it stops being a wall of controls and starts being a set of named places.

      -

      Alex: First, open the issue or PR page. Then, in the right sidebar, scroll to the Notifications section. After that, click Unsubscribe - you will stop receiving notifications from this thread. Finally, alternatively, from the inbox: hover over the notification row and click the mute icon (or the … menu). The rhythm is simple: orient, act, verify, then continue.

      -

      Jamie: Before we leave Muting a noisy thread, what is the practical point?

      -

      Alex: First, open the notification. Then, on the issue/PR page, navigate the sidebar to the Notifications section (H or D). After that, activate the Unsubscribe button. Finally, or from the inbox: focus the notification → press M to mute. Think of it as a rail line: each stop confirms you are still on the right route before the next one.

      +

      Jamie: Let's pause on Pushing Tags to GitHub. What should a learner take away from it?

      +

      Alex: Keep the learner anchored in Pushing Tags to GitHub. Tags are not pushed automatically when you run git push. A good GitHub workflow is like a well-run meeting: everyone knows the topic, the next action, and who has the floor.

      +

      Alex: Treat examples as spoken recipes, not decorations. You may hear something like Push a specific tag; git push origin v1.2.0; Push all local tags at once; git push origin --tags. Read the command, understand what it changes, then run it only when the repository state matches the lesson.

      +

      Jamie: Let's pause on Deleting a Tag. What should a learner take away from it?

      +

      Alex: Start with Deleting a Tag. There is something to understand, something to try, and something that proves the try worked.

      +

      Alex: Treat examples as spoken recipes, not decorations. You may hear something like Delete a local tag; git tag -d v1.2.0; Delete the tag on GitHub (remote); git push origin --delete v1.2.0. Read the command, understand what it changes, then run it only when the repository state matches the lesson.

      +

      Jamie: Let's pause on 6. Detached HEAD -- What It Is and How to Get Out. What should a learner take away from it?

      +

      Alex: Start with 6. Detached HEAD -- What It Is and How to Get Out: What it is: Normally, you're working on a branch -- Git tracks your commits and moves the branch forward as you commit. The next useful detail is this: A "detached HEAD" happens when you check out a specific commit SHA (or a tag) directly instead of a branch.

      +

      Alex: Treat examples as spoken recipes, not decorations. You may hear something like git checkout a1b2c3d Check out a specific commit; git checkout v1.0.0 Check out a tag. Read the command, understand what it changes, then run it only when the repository state matches the lesson.

      -

      Jamie: Let's pause on Dealing with @mentions you didn't expect. What should a learner take away from it?

      -

      Alex: Start with Dealing with @mentions you didn't expect: If you were @mentioned in an unfamiliar thread.

      -

      Alex: First, read the thread for context before responding. Then, 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. After that, unsubscribe after reading if you don't need to stay in the loop. Think of it as a rail line: each stop confirms you are still on the right route before the next one.

      -

      Alex: This is the part worth saying out loud. Start with Learning Cards: Managing Notifications at Scale. There is something to understand, something to try, and something that proves the try worked.

      -

      Alex: The practical takeaway is this. 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. 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.

      -

      Jamie: Let's pause on Notification Settings - Per Your Account. What should a learner take away from it?

      -

      Alex: This is where Notification Settings - Per Your Account becomes real: global notification preferences are at https://github.com/settings/notifications.

      +

      Jamie: Let's pause on If you just want to go back to your branch. What should a learner take away from it?

      +

      Alex: Start with If you just want to go back to your branch. There is something to understand, something to try, and something that proves the try worked.

      +

      Alex: Treat examples as spoken recipes, not decorations. You may hear something like git checkout main; or whatever branch you were on; git switch main. Read the command, understand what it changes, then run it only when the repository state matches the lesson.

      +

      Jamie: Let's pause on If you made commits in detached HEAD and want to keep them. What should a learner take away from it?

      +

      Alex: Start with If you made commits in detached HEAD and want to keep them. There is something to understand, something to try, and something that proves the try worked.

      +

      Alex: Treat examples as spoken recipes, not decorations. You may hear something like Create a new branch at the current (detached) position to save your work; git checkout -b my-experiment; Now you're on a real branch and those commits are safe. Read the command, understand what it changes, then run it only when the repository state matches the lesson.

      +

      Jamie: What stays the same when the tool changes?

      +

      Alex: Keep the learner anchored in VS Code. VS Code shows the current branch name in the bottom-left status bar. This is the part to say slowly: If you're in detached HEAD, it shows something like (HEAD detached at a1b2c3d) instead of a branch name.

      +
      +

      Alex: Before the learner moves on. The reason 7. Force Pushing Safely matters is that what it is: After you rebase or amend commits that have already been pushed, the remote branch has a different history than your local branch. That gives the learner a simple foothold: a regular git push will fail because Git sees them as diverged.

      +

      Jamie: Let's pause on --force-with-lease vs --force. What should a learner take away from it?

      +

      Alex: Start with --force-with-lease vs --force: Always use --force-with-lease instead of --force.

      +

      Alex: This is the part worth saying out loud. Start with When You'd Use It. There is something to understand, something to try, and something that proves the try worked.

      +

      Alex: For a learner, the useful signals are these. You rebased a feature branch to squash commits before a PR review. You amended the last commit with git commit --amend after already pushing. A reviewer asked you to rebase onto main and you've now done.

      +
      +

      Jamie: Before we leave VS Code, what is the practical point?

      +

      Alex: This is where VS Code becomes real: VS Code doesn't have a "force push" button in the UI -- this is intentional to prevent accidents.

      +

      Alex: Treat examples as spoken recipes, not decorations. You may hear something like Ctrl+Backtick → then type the command below. Read the command, understand what it changes, then run it only when the repository state matches the lesson.

      +

      Jamie: Before we leave GitHub CLI, what is the practical point?

      +

      Alex: Treat examples as spoken recipes, not decorations. You may hear something like Force push your current branch; gh repo sync This is for syncing FROM remote, not for force pushing; For force pushing, use git directly:; git push --force-with-lease origin your-branch-name. Read the command, understand what it changes, then run it only when the repository state matches the lesson.

      +

      Jamie: Let's pause on Git CLI. What should a learner take away from it?

      +

      Alex: Treat examples as spoken recipes, not decorations. You may hear something like Safe force push -- fails if someone else pushed since your last fetch; git push --force-with-lease origin feature/my-branch; Check what will happen before pushing; git push --force-with-lease --dry-run origin feature/my-branch; Unconditional force push (avoid. Read the command, understand what it changes, then run it only when the repository state matches the lesson.

      +
      +

      Jamie: Let's pause on The Typical Rebase + Force Push Workflow. What should a learner take away from it?

      +

      Alex: Start with The Typical Rebase + Force Push Workflow. There is something to understand, something to try, and something that proves the try worked.

      +

      Alex: Treat examples as spoken recipes, not decorations. You may hear something like You're on your feature branch -- rebase onto main to get latest changes; git fetch origin; git rebase origin/main; 2. Resolve any conflicts, then continue; git rebase --continue; 3. Force push your rebased branch (origin already has the old version); git push. Read the command, understand what it changes, then run it only when the repository state matches the lesson.

      +

      Jamie: Let's pause on 8. git bisect -- Finding the Commit That Broke Things. What should a learner take away from it?

      +

      Alex: Here is the plain-English version of 8. git bisect -- Finding the Commit That Broke Things. What it is: git bisect performs a binary search through your commit history to find exactly which commit introduced a bug. Put another way, instead of checking 100 commits one by one, Git cuts the search in half each time -- usually finding the culprit in 7-10 steps.

      +

      Alex: Here is what that changes in practice. "This was working last week, now it's broken -- what changed?". You need to find the exact commit so you can revert or fix it. A test that used to pass now fails and you don't know why.

      +

      Jamie: Let's pause on Starting a Bisect Session. What should a learner take away from it?

      +

      Alex: This is where Starting a Bisect Session becomes real: Git now checks out a commit in the middle of your history. That matters in practice: Test your code -- does the bug exist here?

      +

      Alex: Treat examples as spoken recipes, not decorations. You may hear something like Start bisect mode; git bisect start; 2. Mark the current commit as bad (broken); git bisect bad; 3. Mark a commit you know was good (working); Use a tag, SHA, or branch name from before the problem started; git bisect good v1.0.0; or; git bisect good a1b2c3d. If the bug IS present at this commit; git bisect bad; If the bug is NOT present at this commit; git bisect good. Read the command, understand what it changes, then run it only when the repository state matches the lesson.

      +
      +

      Jamie: Let's pause on Finishing. What should a learner take away from it?

      +

      Alex: Start with Finishing. There is something to understand, something to try, and something that proves the try worked.

      +

      Alex: Treat examples as spoken recipes, not decorations. You may hear something like End the bisect session and return to your original branch; git bisect reset. Read the command, understand what it changes, then run it only when the repository state matches the lesson.

      +

      Jamie: Let's pause on Automating Bisect with a Test Script. What should a learner take away from it?

      +

      Alex: The reason Automating Bisect with a Test Script matters is that if you have a test command that exits with code 0 on success and non-zero on failure, Git can run bisect automatically. That gives the learner a simple foothold: bisect output is plain text -- each step tells you exactly where it checked out and how many steps remain. The interface gets friendlier when it stops being a wall of controls and starts being a set of named places.

      +

      Alex: Treat examples as spoken recipes, not decorations. You may hear something like git bisect start; git bisect bad HEAD; git bisect good v1.0.0; Run automatically -- git runs your test script at each step; git bisect run npm test; or; git bisect run python -m pytest tests/test auth.py. Read the command, understand what it changes, then run it only when the repository state matches the lesson.

      +

      Jamie: Let's pause on 9. git clean -- Clearing Out Untracked Files. What should a learner take away from it?

      +

      Alex: Start with 9. git clean -- Clearing Out Untracked Files: What it is: git clean removes untracked files and directories from your working directory -- files that Git doesn't know about yet (not staged, not committed, not in.gitignore). The next useful detail is this: This is useful when you have build artifacts, generated files, or experimental files cluttering your project.

      +

      Alex: The parts worth keeping in working memory are these. After a build that left temporary files everywhere. You want a completely fresh state matching the last commit. Clearing out generated files before running a clean build.

      -

      Alex: Hold that next to this. Keep the learner anchored in Starring vs. Watching - What Is the Difference? New contributors often confuse these two. This is the part to say slowly: They appear next to each other on every repository page and do completely different things. A good GitHub workflow is like a well-run meeting: everyone knows the topic, the next action, and who has the floor.

      -

      Alex: A solid pull request habit is to separate three questions: what changed, why it changed, and what still needs review. That keeps the conversation useful instead of noisy.

      -

      Jamie: Let's pause on Starring a Repository. What should a learner take away from it?

      -

      Alex: The reason Starring a Repository matters is that starring is GitHub's equivalent of a bookmark + public endorsement. That gives the learner a simple foothold: the star count on a repository is a community signal of popularity.

      -

      Alex: Keep the teaching thread moving. Start with 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. The next useful detail is this: 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.

      +

      Jamie: Let's pause on Always Dry-Run First. What should a learner take away from it?

      +

      Alex: Start with Always Dry-Run First. There is something to understand, something to try, and something that proves the try worked.

      +

      Alex: Treat examples as spoken recipes, not decorations. You may hear something like See what WOULD be deleted without actually deleting anything; git clean -n; or equivalently; git clean --dry-run. Read the command, understand what it changes, then run it only when the repository state matches the lesson.

      +

      Jamie: What is the teaching move inside VS Code?

      +

      Alex: This is where VS Code becomes real: VS Code's Source Control panel shows untracked files in the "Changes" section. That matters in practice: For bulk removal, use the terminal (see Git CLI below).

      +

      Alex: First, open Source Control: Ctrl+Shift+G. Then, right-click an untracked file. After that, select "Discard Changes" -- this removes new untracked files. It is a checklist, but a meaningful one: every item creates evidence that the next step is safe.

      +

      Jamie: Let's pause on Git CLI. What should a learner take away from it?

      +

      Alex: Treat examples as spoken recipes, not decorations. You may hear something like Dry run -- see what would be removed; git clean -n; Remove untracked files (NOT directories); git clean -f; Remove untracked files AND directories; git clean -fd; Remove untracked files AND ignored files (be careful -- removes build artifacts AND things. Read the command, understand what it changes, then run it only when the repository state matches the lesson.

      -

      Jamie: Let's pause on How to silence a repository you accidentally over-subscribed to. What should a learner take away from it?

      -

      Alex: Here is the plain-English version of How to silence a repository you accidentally over-subscribed to. This immediately reduces notifications from that repository to only threads you personally participated in.

      -

      Alex: Keep the teaching thread moving. Start with Learning Cards: Starring vs. Watching. There is something to understand, something to try, and something that proves the try worked.

      -

      Alex: The practical takeaway is this. 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. 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.

      -

      Jamie: Let's pause on NVDA. What should a learner take away from it?

      -

      Alex: Start with NVDA. There is something to understand, something to try, and something that proves the try worked.

      -

      Alex: The practical takeaway is this. 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.

      +

      Jamie: Let's pause on 10. Branch Protection -- Why Your Push or Merge May Be Blocked. What should a learner take away from it?

      +

      Alex: The reason 10. Branch Protection -- Why Your Push or Merge May Be Blocked matters is that what it is: Branch protection rules are settings a repository administrator applies to specific branches (usually main or release branches). That gives the learner a simple foothold: they prevent direct pushes, require pull requests, require approvals before merging, and enforce status checks passing.

      +

      Jamie: Let's pause on The Correct Flow for Protected Branches. What should a learner take away from it?

      +

      Alex: Start with The Correct Flow for Protected Branches. There is something to understand, something to try, and something that proves the try worked.

      +

      Alex: Treat examples as spoken recipes, not decorations. You may hear something like Never push directly to main -- always work on a branch; git checkout -b feature/my-change; 2. Make your changes, commit them; git add.; git commit -m "Add screen reader support to navigation"; 3. Push your branch (not main); git push origin feature/my-change. Read the command, understand what it changes, then run it only when the repository state matches the lesson.

      +

      Jamie: Let's pause on Updating a Branch That's Out of Date. What should a learner take away from it?

      +

      Alex: Here is the plain-English version of Updating a Branch That's Out of Date. When GitHub says your branch is out of date with main.

      -

      Alex: Keep the teaching thread moving. Start with JAWS. There is something to understand, something to try, and something that proves the try worked.

      -

      Alex: The practical takeaway is this. 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.

      -

      Jamie: Let's pause on VoiceOver. What should a learner take away from it?

      -

      Alex: Start with VoiceOver. There is something to understand, something to try, and something that proves the try worked.

      -

      Alex: The practical takeaway is this. 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.

      -

      Alex: Keep the teaching thread moving. Here is the plain-English version of The GitHub Mobile App - A Reference Note. GitHub has an iOS and Android app that supports push notifications. Put another way, while the app itself is not covered as a primary tool in this workshop, it is worth knowing. It is like learning a transit route. The names of the stops matter because they tell you whether you are still going the right direction.

      -

      Alex: The practical takeaway is this. 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.

      +

      Jamie: If someone only remembers one thing from VS Code, what should it be?

      +

      Alex: First, open Source Control → Ctrl+Shift+P. Then, type "merge" → select "Git: Merge Branch.". After that, choose origin/main from the list. Finally, resolve any conflicts, then push again. It is a checklist, but a meaningful one: every item creates evidence that the next step is safe.

      +

      Jamie: Let's pause on Git CLI. What should a learner take away from it?

      +

      Alex: Treat examples as spoken recipes, not decorations. You may hear something like Option A: Merge main into your branch (creates a merge commit); git fetch origin; git merge origin/main; Option B: Rebase onto main (cleaner history, requires force push after); git fetch origin; git rebase origin/main; git push --force-with-lease origin. Read the command, understand what it changes, then run it only when the repository state matches the lesson.

      +

      Jamie: What is the teaching move inside GitHub CLI?

      +

      Alex: Treat examples as spoken recipes, not decorations. You may hear something like Update your PR branch from the GitHub UI via CLI; gh pr update-branch --rebase; or; gh pr update-branch uses merge by default. Read the command, understand what it changes, then run it only when the repository state matches the lesson.

      -

      Jamie: Let's pause on Try It: Tame Your Inbox. What should a learner take away from it?

      -

      Alex: This is where Try It: Tame Your Inbox becomes real: time: 2 minutes What you need: Browser, signed in to GitHub. That matters in practice: Go to github.com/notifications and practice.

      -

      Alex: First, scan your inbox - Press H and Tab to navigate through notifications. Each one shows the repo name, type (issue/PR), and title. Then, mark one as done - Find a notification you've already read. Press E to mark it as done. It disappears from the list. After that, 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. It is a checklist, but a meaningful one: every item creates evidence that the next step is safe.

      -

      Alex: Keep the teaching thread moving. Keep the learner anchored in What You Accomplished Today. Day 1 is complete -- and you did a lot. This is the part to say slowly: Here is every skill you practiced, mapped to the chapter where you learned it and the evidence you created along the way.

      -

      Jamie: Let's pause on If This Was Your First Time. What should a learner take away from it?

      -

      Alex: The reason If This Was Your First Time matters is that 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. That gives the learner a simple foothold: you navigated a complex platform, created real contributions, and collaborated with other people in a shared codebase.

      +

      Jamie: If someone only remembers one thing from GitHub CLI, what should it be?

      +

      Alex: Treat examples as spoken recipes, not decorations. You may hear something like View branch protection rules for main; gh api repos/{owner}/{repo}/branches/main/protection --jq '{; required reviews.required pull request reviews.required approving review count,; require status checks.required status checks.contexts,; enforce. Read the command, understand what it changes, then run it only when the repository state matches the lesson.

      +

      Alex: Hold that next to this. Here is the plain-English version of On GitHub.com. Navigate to Settings → Branches in the repository. Put another way, (You need admin access to see the full config; contributors can see the effect through blocked PRs and the merge box status.). It is like learning a transit route. The names of the stops matter because they tell you whether you are still going the right direction.

      +

      Jamie: Let's pause on Learning Cards: Quick Reference Table. What should a learner take away from it?

      +

      Alex: Start with Learning Cards: Quick Reference Table. There is something to understand, something to try, and something that proves the try worked.

      +

      Alex: These are the details that keep the idea from floating away. This table has four columns: Task, VS Code, Git CLI, and GitHub CLI -- column headers are announced on entry. Use Ctrl+Alt+Arrow keys to navigate cells; the Task column on the left identifies each row. Cells with a dash (--) mean that tool does not support the operation -- move right to try another column. At high zoom the table may scroll horizontally -- use Shift+scroll or arrow keys to see all four columns. The Task column is always the leftmost -- anchor your reading from there. Consider copying this table into a text file or spreadsheet for easier viewing at your preferred zoom.

      -

      Jamie: Let's pause on Confidence Check. What should a learner take away from it?

      -

      Alex: Start with Confidence Check: Before you close your laptop, take two minutes to answer these questions in your Chapter 10 challenge issue. The next useful detail is this: There are no wrong answers -- this is for you. Think of it like entering a new building: first you find the lobby, then the room, then the door you actually need.

      -

      Alex: First, which chapter felt the most natural to you? Which one do you want to revisit? Then, can you explain what a pull request does to someone who has never used GitHub? After that, if you saw a merge conflict right now, would you know where to start? Finally, what is one thing you want to try on GitHub this week that you did not get to today? Think of it as a rail line: each stop confirms you are still on the right route before the next one.

      -

      Jamie: What should the learner prove to themselves after each small task?

      -

      Alex: Here is the plain-English version of Your Challenge Progress. Look at how many challenge issues you completed today. Put another way, each one represents a skill you did not just read about -- you practiced it, posted evidence, and moved on.

      -

      Alex: Keep the teaching thread moving. Start with Learning Cards: What You Accomplished Today. There is something to understand, something to try, and something that proves the try worked.

      -

      Alex: The practical takeaway is this. 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. 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.

      +

      Alex: Keep the teaching thread moving. Keep the learner anchored in 11. Using GitHub Copilot for Git Operations. GitHub Copilot isn't just for writing code -- it's genuinely useful for Git operations, especially when you're doing something unfamiliar, hit a conflict, or need to understand what a command did. This is the part to say slowly: Here's how to use it across the advanced operations in this appendix.

      +

      Jamie: Let's pause on Resolving Merge Conflicts. What should a learner take away from it?

      +

      Alex: The reason Resolving Merge Conflicts matters is that when a cherry-pick, rebase, or branch merge stops due to a conflict, VS Code highlights the conflict regions. That gives the learner a simple foothold: place your cursor inside a conflict block and ask Copilot.

      +

      Alex: The practical takeaway is this. "Resolve this merge conflict. Keep meaningful changes from both sides.". "Explain what each side of this conflict is trying to do.". "Which version of this change should I keep, and why?".

      +

      Alex: Keep the teaching thread moving. Start with Writing Better Commit Messages: Copilot is excellent at turning "WIP: stuff" into a clear, conventional commit message. The next useful detail is this: Open Copilot Chat after staging your changes and try. Think of it like entering a new building: first you find the lobby, then the room, then the door you actually need.

      +

      Alex: The practical takeaway is this. "Write a conventional commit message for these changes." (Copilot can see open files). "I changed the navigation component to add keyboard focus indicators. Write a commit message.". "Here are my last 5 WIP commit messages: [paste them]. Write one clean message that summarizes all of them.".

      -

      Jamie: Where does the workshop stop being a tour and start becoming contribution?

      -

      Alex: Keep the learner anchored in What Day 2 Adds. See also: Chapter 11: VS Code Interface is where Day 2 begins -- have VS Code installed and ready. This is the part to say slowly: On Day 1, you worked entirely on GitHub.com.

      -

      Jamie: Let's pause on Between Days. What should a learner take away from it?

      -

      Alex: The reason Between Days matters is that if your workshop has a gap between Day 1 and Day 2, here are three optional things you can do to stay sharp. That gives the learner a simple foothold: GitHub Skills courses use bot-driven feedback inside pull requests. The interface gets friendlier when it stops being a wall of controls and starts being a set of named places.

      -

      Alex: First, explore your notification settings. Now that you understand how notifications work, visit github.com/settings/notifications and customize your email and web preferences. There is no wrong configuration -- just find what feels manageable. Then, 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. After that, try a GitHub Skills course. GitHub Skills 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 for the full list of recommended courses. The rhythm is simple: orient, act, verify, then continue.

      -

      Jamie: Let's pause on You Already Know More Than You Think. What should a learner take away from it?

      -

      Alex: Start with You Already Know More Than You Think: Think about where you started this morning. The next useful detail is this: 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.

      +

      Jamie: Let's pause on Understanding Confusing Git Output. What should a learner take away from it?

      +

      Alex: Here is the plain-English version of Understanding Confusing Git Output. Git's error messages and status output can be cryptic. Put another way, paste them directly into Copilot Chat.

      +

      Alex: The practical takeaway is this. "I got this git error message: [paste it]. What does it mean and how do I fix it?". "My git status output looks like this: [paste it]. What happened and what should I do next?". "I accidentally ran git reset --hard. What are my options for recovering my changes?".

      +

      Alex: Keep the teaching thread moving. This is where Choosing the Right Command becomes real: when you're not sure which git command to reach for, describe what you want to do.

      +

      Alex: The practical takeaway is this. "I committed a fix on my feature branch but main also needs it urgently. What's the right git command to use?" → Copilot will suggest cherry-pick. "I have 6 messy commits on my PR branch before I open the PR. How do I clean them up?" → Interactive rebase with squash. "I pushed a commit that broke CI and I need to undo it without force-pushing." → git revert. "My PR branch hasn't been updated from main in two weeks. How do I bring it up to date?" → fetch + rebase or merge.

      +

      Jamie: Let's pause on Debugging a Failing Bisect. What should a learner take away from it?

      +

      Alex: Keep the learner anchored in Debugging a Failing Bisect. When git bisect lands on a commit and you're not sure what to test.

      +

      Alex: The practical takeaway is this. "I'm running git bisect to find a bug. Git just checked out commit a1b2c3d. Here's the diff: [paste git show a1b2c3d]. What changed in this commit and what should I test?".

      -

      Jamie: What is the final checkpoint?

      -

      Alex: You should be able to point to the evidence, explain the action, and describe what you would do next if this were a real open source project. If you can teach the move back, you have learned it.

      -

      Jamie: And if they get stuck?

      -

      Alex: Read the latest message, not the loudest worry. Check the issue, the branch, the pull request, the status check, or the bot comment. Then ask for help with those facts in hand. That is how professionals collaborate.

      +

      Alex: Keep the teaching thread moving. The reason Getting Help With Branch Protection Errors matters is that paste the full error message from a rejected push into Copilot. The interface gets friendlier when it stops being a wall of controls and starts being a set of named places.

      +

      Alex: The practical takeaway is this. "I got this error when pushing to my repository: [paste error]. What does it mean and what do I do?". "My PR can't merge because of a required status check. Here's the check output: [paste it]. What's wrong?".

      +

      Jamie: Let's pause on GitHub Copilot CLI -- Git Command Suggestions. What should a learner take away from it?

      +

      Alex: Start with GitHub Copilot CLI -- Git Command Suggestions: If you have the GitHub CLI with Copilot extension installed, you can ask for git commands directly in the terminal. The next useful detail is this: Copilot CLI explains the command before running it and asks for confirmation -- great for learning while doing.

      +

      Alex: Treat examples as spoken recipes, not decorations. You may hear something like Ask Copilot to suggest a git command for what you want to do; gh copilot suggest "squash my last 4 commits into one"; gh copilot suggest "undo my last commit but keep the changes"; gh copilot suggest "find which commit broke the login tests". Read the command, understand what it changes, then run it only when the repository state matches the lesson.

      +
      +

      Jamie: What should people carry with them after this?

      +

      Alex: Carry the map. Know what page or tool you are in, know which action you are taking, and know what confirmation should follow. If the confirmation is missing, pause. That pause is not wasted time; it is professional judgment.

      +

      Jamie: That is a better way to say it than just follow the steps.

      +

      Alex: Right. Steps matter, but understanding wins. That is episode 50. Next in the series is episode 51, where we keep building the same contributor muscles.

      -

      Challenge bonus-e: Git History

      -

      Reading history, understanding commits over time, and using history as a learning tool.

      +

      73. Episode 51: Git Security for Contributors

      +

      Secrets, .gitignore, environment variables, push protection, and safe contributor habits.

      +

      Based on: Appendix F: Git Security for Contributors

      +

      Audio and transcript are being regenerated for this episode.

      -Read Transcript - Challenge bonus-e: Git History +Read Transcript - Episode 51: Git Security for Contributors

      Transcript

      -

      Alex: This is Challenge Coach for Git History. I am Alex, and we are going to teach the move before asking you to prove it.

      -

      Jamie: And I am Jamie. I will translate the challenge into the practical questions learners actually have while doing it.

      +

      Alex: Welcome to episode 51 of Git Going with GitHub: Git Security for Contributors. I am Alex, and today we are teaching this topic as a conversation you can carry into the workshop, not as a page you have to memorize.

      +

      Jamie: And I am Jamie. I will keep pulling the lesson back to real learners, real repositories, and the evidence that proves the work happened.

      -

      Alex: Reading history, understanding commits over time, and using history as a learning tool. That is the task layer. The teaching layer is understanding why the move belongs in a contributor workflow.

      -

      Jamie: So evidence is not just proof for the facilitator. It is part of how the learner understands the workflow.

      -

      Alex: Right. A good challenge produces something inspectable: a comment, issue, branch, commit, pull request, review, or clear note about what happened.

      +

      Alex: The lesson focus is Secrets,.gitignore, environment variables, push protection, and safe contributor habits. We will treat every step as a teachable decision, because that is what makes the skill portable.

      +

      Jamie: So we should explain the why clearly enough that the steps make sense when the learner meets them later.

      +

      Alex: That is it. If a listener only has audio right now, they should still get the complete concept and know what evidence would prove success.

      Jamie: Okay, set the room for us. What are we walking into?

      -

      Alex: Start with Bonus E: Explore Git History Visually: For students who: Want to see branching and merging as a visual timeline. The next useful detail is this: What you will do: Use GitHub Desktop (or the GitHub.com commit graph) to explore the learning-room's Git history as a visual timeline.

      -

      Alex: A solid Git habit is to know which branch you are on, what changed, and what confirmation you expect before you run the next command.

      -

      Jamie: How would you walk the room through that step by step?

      -

      Alex: Start with Instructions. There is something to understand, something to try, and something that proves the try worked.

      -

      Alex: The practical anchors are these. How branches appear as parallel lines. Where merges bring lines back together. Which commits are yours vs seeded peer-simulation commits.

      -

      Alex: First, open the learning-room repository in GitHub Desktop. Then, go to the History tab. After that, explore the commit timeline. Notice. Finally, go to the learning-room repository on GitHub.com. Treat it like a recipe: do not add the next ingredient until the previous one is actually in the bowl.

      -

      Jamie: What does the learner do first, second, and then after that?

      -

      Alex: First, select Insights Network to see the branch graph. Then, or select Commits on the Code tab to see the linear history. It is a checklist, but a meaningful one: every item creates evidence that the next step is safe.

      +

      Alex: Start with Keeping Secrets Out of Your Repository: Who this is for: Anyone committing code or documentation to a repository. The next useful detail is this: You don't need to be a security expert -- this appendix covers the practical habits that protect you and the projects you contribute to.

      +

      Alex: The next layer is this. Start with Learning Cards: Using This Security Reference. There is something to understand, something to try, and something that proves the try worked.

      +

      Alex: The practical anchors are these. Sections are ordered from understanding (section 1) to prevention (2-5) to recovery (6-7) to daily habits (8-9). Code blocks contain exact gitignore patterns and terminal commands -- switch to Focus Mode before copying. The Security Checklist (section 9) is a task list you can use before every push. Code examples for.gitignore patterns and terminal commands are in high-contrast code blocks. Warning callouts use bold text -- scan for bold to find the most critical safety notes. The Security Checklist at the bottom uses checkbox formatting for easy visual tracking.

      Jamie: What is the one idea that makes the next few steps less mysterious?

      -

      Alex: This is where What to observe becomes real: answer these questions as you explore.

      -

      Alex: That shows up in the workshop in a few specific ways. [ ] How many branches exist in the repository right now? [ ] Can you find your Challenge 5 commit in the history? [ ] Where does your learn/YOUR-USERNAME branch diverge from main? [ ] Can you find the merge commit from your Challenge 9 PR? [ ] What is the oldest commit in the repository?

      +

      Alex: This is where 1. Why This Matters -- What Happens When Secrets Leak becomes real: when a secret (API key, token, password, private key) is committed to a public GitHub repository -- even for a few seconds before you delete it -- it's effectively compromised. That matters in practice: Why "I'll just delete it right away" isn't enough.

      +

      Alex: That shows up in the workshop in a few specific ways. Bots scan GitHub continuously and harvest secrets within seconds of a push. The secret lives in your git history even after you delete the file. GitHub forks capture history -- once forked, you can't fully erase it. Search engines may index the content before you remove it.

      -

      Jamie: Turn that into a path someone can follow.

      -

      Alex: Start with Viewing commit history. There is something to understand, something to try, and something that proves the try worked.

      -

      Alex: First, navigate to any repository. Then, click the "X commits" link near the top (shows total commit count). After that, the history page shows each commit with author, date, message, and SHA. Finally, click any commit to see what changed (green lines added, red lines removed). It is like walking a hallway with named doors: read the sign, enter the right room, then confirm where you landed.

      -

      Jamie: What would you say to someone who is already bracing for this to be too much?

      -

      Alex: The reason What you see matters is that the commit history tells the story of a project.

      -

      Alex: The parts worth keeping in working memory are these. Chronological order: Most recent commits first. Author attribution: Every change has a name attached. Commit messages: Each entry explains what changed and (ideally) why. Diffs: Click any commit to see exactly which lines were added, removed, or modified.

      +

      Alex: Now bring the learner back to the room. Keep the learner anchored in 2. The.gitignore File -- Your First Line of Defense. A.gitignore file tells Git which files to never track. This is the part to say slowly: Files listed in.gitignore won't show up in git status, won't be staged by git add, and won't be committed.

      +

      Jamie: What should they understand before typing anything?

      +

      Alex: The reason Checking if a file is already tracked matters is that.gitignore only prevents untracked files from being added. That gives the learner a simple foothold: if Git is already tracking a file,.gitignore won't stop it from being committed in the future.

      +

      Alex: Treat examples as spoken recipes, not decorations. You may hear something like Check if a specific file is tracked; git ls-files.env; If it returns the filename, it's being tracked -- you need to untrack it; git rm --cached.env; Then add it to.gitignore and commit. Read the command, understand what it changes, then run it only when the repository state matches the lesson.

      Alex: The useful habit is simple: orient first, act second, verify third. That pause before acting is part of the work.

      -

      Jamie: Give me the sequence, because order matters here.

      -

      Alex: Start with Visual timeline. There is something to understand, something to try, and something that proves the try worked.

      -

      Alex: First, open the repository in GitHub Desktop. Then, click the "History" tab. After that, the left panel shows commits as a timeline. Finally, click any commit to see the diff in the right panel. Think of it as a rail line: each stop confirms you are still on the right route before the next one.

      -

      Jamie: What is the ordered workflow?

      -

      Alex: First, the branch visualization shows where branches diverged and merged. Treat it like a recipe: do not add the next ingredient until the previous one is actually in the bowl.

      +

      Jamie: How do you keep commands from becoming magic words?

      +

      Alex: Start with Global.gitignore -- apply to every repo on your machine: You can create a global.gitignore that applies to all repositories on your computer -- useful for OS-specific and editor-specific files you never want to commit anywhere. The next useful detail is this: Add your editor and OS files to /.gitignore global so you never have to add them to individual repos. Think of it like entering a new building: first you find the lobby, then the room, then the door you actually need.

      +

      Alex: Treat examples as spoken recipes, not decorations. You may hear something like Create a global gitignore file; touch /.gitignore global; Tell Git to use it; git config --global core.excludesfile /.gitignore global. Read the command, understand what it changes, then run it only when the repository state matches the lesson.

      -

      Jamie: If I am listening before the workshop starts, what should settle in my mind first?

      -

      Alex: Start with Key observations from exploring history. There is something to understand, something to try, and something that proves the try worked.

      -

      Alex: Here is what that changes in practice. Merge commits show where two branches came together -- they have two parent commits. The first commit in a repository is often called "initial commit" and creates the project structure. Commit frequency varies -- some days have many commits, others have none. This is normal.

      -

      Alex: This is where the talk moves from concept to action. This is where In VS Code becomes real: the "Timeline" view in the Explorer sidebar shows the history for the currently open file. That matters in practice: Each entry is a commit that changed that file.

      +

      Jamie: What is the safe way to learn from that example?

      +

      Alex: Here is the plain-English version of GitHub's.gitignore templates. When creating a new repository on GitHub, you can choose a.gitignore template for your language -- GitHub pre-fills it with the most common patterns for that ecosystem. Put another way, find all templates at github.com/github/gitignore.

      +

      Alex: Treat examples as spoken recipes, not decorations. You may hear something like Download a template (e.g., for Node.js); curl https://raw.githubusercontent.com/github/gitignore/main/Node.gitignore.gitignore. Read the command, understand what it changes, then run it only when the repository state matches the lesson.

      +

      Alex: This is where the talk moves from concept to action. This is where 3. Environment Variables -- The Right Way to Store Secrets becomes real: instead of hardcoding secrets in your files, store them in environment variables that live outside of your repository.

      Jamie: Where do you want a learner to place their attention here?

      -

      Alex: Keep the learner anchored in What matters. The learning objective is understanding that Git history is a navigable record of every change. This is the part to say slowly: If you explored the commit history, clicked into at least one commit to see its diff, and can describe what the history tells you about the project, you completed this bonus.

      +

      Alex: Keep the learner anchored in Using a.env file locally. A.env file stores your local environment variables. This is the part to say slowly: It's convenient and universally supported -- and it must be in your.gitignore.

      -

      Alex: Before the learner moves on. The reason 1. Why a Mental Model Matters matters is that on Day 1, you edited files on GitHub.com using the web editor. That gives the learner a simple foothold: GitHub handled Git for you behind the scenes -- creating commits, managing branches, and tracking changes. The interface gets friendlier when it stops being a wall of controls and starts being a set of named places.

      +

      Alex: Before the learner moves on. The reason Sharing secrets with your team safely matters is that never send secrets in Slack, email, or GitHub comments. The interface gets friendlier when it stops being a wall of controls and starts being a set of named places.

      +

      Alex: That becomes easier when you listen for these cues. GitHub Actions Secrets -- for CI/CD pipelines: Settings → Secrets and variables → Actions. A password manager with sharing (1Password Teams, Bitwarden) -- for team credentials. A secrets manager (AWS Secrets Manager, HashiCorp Vault) -- for production systems.

      +

      Jamie: What is the pre-flight check here?

      +

      Alex: Start with 4. Review Before You Commit: The most effective habit is simply reviewing what you're about to commit before you commit it.

      +

      Alex: A solid pull request habit is to separate three questions: what changed, why it changed, and what still needs review. That keeps the conversation useful instead of noisy.

      +

      Jamie: What should happen before anyone copies and runs it?

      +

      Alex: Start with git diff --staged -- see exactly what's going in. There is something to understand, something to try, and something that proves the try worked.

      +

      Alex: For a learner, the useful signals are these. Any hardcoded passwords, tokens, or API keys.env or credential files that snuck in. Any TODO comments that reference sensitive information.

      +

      Alex: Treat examples as spoken recipes, not decorations. You may hear something like Review all staged changes before committing; git diff --staged; Review a specific file; git diff --staged docs/config.md. Read the command, understand what it changes, then run it only when the repository state matches the lesson.

      +
      +

      Jamie: Let's pause on Avoid git add. blindly. What should a learner take away from it?

      +

      Alex: This is where Avoid git add. blindly becomes real: stages everything in your working directory -- including files you didn't mean to add. That matters in practice: git add -p (patch mode) walks you through each change chunk by chunk and asks whether to stage it.

      +

      Alex: Treat examples as spoken recipes, not decorations. You may hear something like Risky - stages everything without review; git add.; Better - stage specific files you know are clean; git add src/auth.js docs/README.md; Or stage interactively - review each file before adding; git add -p. Read the command, understand what it changes, then run it only when the repository state matches the lesson.

      +

      Alex: A solid Git habit is to know which branch you are on, what changed, and what confirmation you expect before you run the next command.

      +

      Jamie: Let's pause on Check what's staged before committing. What should a learner take away from it?

      +

      Alex: Keep the learner anchored in Check what's staged before committing. GitHub Copilot can help: After staging your changes, open Copilot Chat and ask: "Review my staged changes for any accidentally included secrets, API keys, or credentials." Paste the output of git diff --staged into the chat. A good GitHub workflow is like a well-run meeting: everyone knows the topic, the next action, and who has the floor.

      +

      Alex: Treat examples as spoken recipes, not decorations. You may hear something like See which files are staged (and which aren't); git status; See the full diff of staged changes; git diff --staged. Read the command, understand what it changes, then run it only when the repository state matches the lesson.

      +

      Jamie: What would you say to someone who is already bracing for this to be too much?

      +

      Alex: The reason 5. Pre-Commit Hooks -- Automated Secret Detection matters is that a pre-commit hook is a script that runs automatically every time you try to commit. That gives the learner a simple foothold: if the script detects a problem (like a potential secret), it blocks the commit and tells you what it found.

      +
      +

      Alex: Here is the practical turn. Start with Option A: detect-secrets (recommended, Python-based): detect-secrets scans for over 20 types of secrets and integrates well with existing repos. The next useful detail is this: After setup, any commit containing a potential secret is blocked with a clear message showing which file and line triggered the alert.

      Jamie: Give me the version that sounds like an instructor, not a manual.

      -

      Alex: Start with 2. The Three Areas: Working Directory, Staging Area, Repository: Git organizes your work into three areas. The next useful detail is this: Understanding these three areas is the single most important concept in this chapter.

      -

      Alex: Hold that next to this. Here is the plain-English version of Working directory. The working directory is the folder on your computer where the files live. Put another way, when you open a project in VS Code, everything you see in the file explorer is the working directory.

      +

      Alex: Here is the plain-English version of Option C: pre-commit framework (manages multiple hooks). The pre-commit framework lets you install and manage hooks from a YAML config file, making it easy to share hook config across your team. Put another way, pre-commit hooks live in.git/hooks/ and are local to your machine -- they're not committed to the repo automatically.

      +

      Alex: Keep the thread going. This is where Step 1: Rotate the secret immediately becomes real: before anything else -- go to wherever that secret is managed and revoke or rotate it. That matters in practice: It may already be compromised, so neutralizing it is more important than removing it from git history. The workshop is closer to rehearsal than lecture. You hear the move, try the move, and then check what changed.

      -

      Jamie: Let's pause on Staging area (also called the index). What should a learner take away from it?

      -

      Alex: This is where Staging area (also called the index) becomes real: the staging area is a holding zone. That matters in practice: When you are happy with a change in the working directory, you add it to the staging area.

      -

      Alex: That connects to another useful point. Keep the learner anchored in Repository (the.git folder). The repository is Git's permanent record. This is the part to say slowly: 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. A good GitHub workflow is like a well-run meeting: everyone knows the topic, the next action, and who has the floor.

      -

      Jamie: Let's pause on How the three areas connect. What should a learner take away from it?

      -

      Alex: The reason How the three areas connect matters is that many visual Git tutorials use diagrams with arrows to show this flow. That gives the learner a simple foothold: the text description above and the three-step sequence are the same information without requiring a visual representation.

      -

      Alex: First, edit files in the working directory. Then, stage the changes you want to keep (add to the staging area). After that, commit the staged changes (save to the repository). The rhythm is simple: orient, act, verify, then continue.

      +

      Jamie: Let's pause on Step 2: Was it pushed to a public repo? What should a learner take away from it?

      +

      Alex: Keep the learner anchored in Step 2: Was it pushed to a public repo? If it was pushed (remote has the secret). This is the part to say slowly: The secret is potentially already compromised -- assume it was harvested.

      +

      Alex: Treat examples as spoken recipes, not decorations. You may hear something like Undo the last commit, keep your changes staged (safest); git reset --soft HEAD 1; Now remove the secret from the file, re-add, and re-commit; (Edit the file to remove the secret); git add -p Review what you stage; git commit -m "Your original commit message. Read the command, understand what it changes, then run it only when the repository state matches the lesson.

      +

      Alex: Another way to ground it. The reason Step 3: Remove the secret from git history matters is that this only matters if the commit was pushed. That gives the learner a simple foothold: if it was local-only and you used git reset --soft above, you're done.

      +

      Jamie: Let's pause on Method A: git filter-repo (recommended -- built-in, modern). What should a learner take away from it?

      +

      Alex: Start with Method A: git filter-repo (recommended -- built-in, modern). There is something to understand, something to try, and something that proves the try worked.

      +

      Alex: Treat examples as spoken recipes, not decorations. You may hear something like Install git-filter-repo; pip install git-filter-repo; Remove a specific file from all history; git filter-repo --path secrets.json --invert-paths; Replace a specific string (the secret value) throughout all history; git filter-repo --replace-text REMOVED"). Read the command, understand what it changes, then run it only when the repository state matches the lesson.

      -

      Alex: Here is the practical turn. Start with An analogy: packing a box: Think of it like packing a box to mail. The next useful detail is this: 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).

      -

      Alex: On the ground, that means a few things. 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.

      -

      Jamie: Let's pause on Learning Cards: The Three Areas. What should a learner take away from it?

      -

      Alex: Start with Learning Cards: The Three Areas. There is something to understand, something to try, and something that proves the try worked.

      -

      Alex: The room should hear these as checkpoints. 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. 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.

      -

      Alex: Keep the thread going. This is where 3. What Is a Commit? becomes real: a commit is a snapshot of your project at a specific moment in time. That matters in practice: It is not a diff (a list of changes). The workshop is closer to rehearsal than lecture. You hear the move, try the move, and then check what changed.

      +

      Jamie: Let's pause on Step 4: Force push the cleaned history. What should a learner take away from it?

      +

      Alex: Here is the plain-English version of Step 4: Force push the cleaned history. After rewriting history, you must force push. Put another way, anyone who has cloned or pulled the repo will need to re-clone or rebase after a force push. It is like learning a transit route. The names of the stops matter because they tell you whether you are still going the right direction.

      +

      Alex: Treat examples as spoken recipes, not decorations. You may hear something like git push --force-with-lease origin main. Read the command, understand what it changes, then run it only when the repository state matches the lesson.

      +

      Jamie: If I am listening before the workshop starts, what should settle in my mind first?

      +

      Alex: This is where Step 5: Tell GitHub to rescan becomes real: after removing the secret from history, go to Security → Secret scanning in your repository and mark any open alerts as resolved.

      +

      Alex: That connects to another useful point. Keep the learner anchored in 7. GitHub's Built-In Push Protection. GitHub automatically scans pushes for known secret patterns before they reach the remote. This is the part to say slowly: If it detects a secret, the push is blocked.

      -

      Jamie: Let's pause on Commit IDs (hashes). What should a learner take away from it?

      -

      Alex: Keep the learner anchored in Commit IDs (hashes). Every commit gets a unique identifier -- a 40-character string called a SHA hash. This is the part to say slowly: In practice, you usually see only the first 7 characters: a1b2c3d.

      -

      Alex: Another way to ground it. The reason Commits are permanent (mostly) matters is that once a commit is made, it is part of the repository's history. That gives the learner a simple foothold: you can make new commits that undo the changes, but the original commit still exists in the timeline.

      -

      Jamie: Let's pause on Learning Cards: Commits. What should a learner take away from it?

      -

      Alex: Start with Learning Cards: Commits. There is something to understand, something to try, and something that proves the try worked.

      -

      Alex: A few details make that real. 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. 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.

      +

      Jamie: Let's pause on What push protection covers. What should a learner take away from it?

      +

      Alex: The reason What push protection covers matters is that GitHub knows the patterns for hundreds of secret types including.

      +

      Alex: The parts worth keeping in working memory are these. GitHub tokens (PATs, GitHub App tokens, OAuth tokens). AWS access keys. Azure credentials. Google Cloud keys. Stripe, Twilio, Slack, and dozens more API keys.

      +

      Jamie: Give me the sequence, because order matters here.

      +

      Alex: Start with If push protection blocks you. There is something to understand, something to try, and something that proves the try worked.

      +

      Alex: First, confirm it's actually a secret -- check the file and line mentioned. Then, if it's a real secret: Remove it from the file, amend your commit, and push again. After that, if it's a false positive: Use the bypass URL GitHub provides to push with an explanation. Think of it as a rail line: each stop confirms you are still on the right route before the next one.

      +

      Jamie: Let's pause on Checking your repo's push protection status. What should a learner take away from it?

      +

      Alex: Here is the plain-English version of Checking your repo's push protection status. As a contributor you can see push protection in action when a push is blocked. Put another way, maintainers configure it in Settings → Code security → Push protection.

      +
      +

      Jamie: Let's pause on Never store credentials in plaintext. What should a learner take away from it?

      +

      Alex: This is where Never store credentials in plaintext becomes real: do this instead - use the OS credential store. That matters in practice: With a credential helper set, Git asks for your credentials once and stores them securely in the OS keychain -- not in any file.

      +

      Alex: Treat examples as spoken recipes, not decorations. You may hear something like Storing a token in a plain text file; echo "ghp mytoken" /token.txt; Hardcoding in a script; export GITHUB TOKEN="ghp mytoken" in a.bashrc or.zshrc that's committed; In a git config; git config --global url."https://myusername:ghp mytoken@github.com".insteadOf. macOS -- use Keychain; git config --global credential.helper osxkeychain; Windows -- use Credential Manager (set automatically by Git for Windows); git config --global credential.helper wincred; Linux -- use the libsecret store (requires installation); git. Read the command, understand what it changes, then run it only when the repository state matches the lesson.

      +

      Jamie: Let's pause on Using a password manager. What should a learner take away from it?

      +

      Alex: Keep the learner anchored in Using a password manager. Store your GitHub PAT, SSH key passphrase, and other credentials in a password manager (1Password, Bitwarden, KeePass). This is the part to say slowly: Most support browser extensions, CLI access, and automatic lock after inactivity.

      +

      Jamie: Let's pause on Checking what credential helper is set. What should a learner take away from it?

      +

      Alex: The reason Checking what credential helper is set matters is that if this returns nothing, your credentials may be stored in plaintext. The interface gets friendlier when it stops being a wall of controls and starts being a set of named places.

      +

      Alex: Treat examples as spoken recipes, not decorations. You may hear something like git config --global credential.helper. Read the command, understand what it changes, then run it only when the repository state matches the lesson.

      +
      +

      Jamie: Let's pause on Learning Cards: Security Checklist. What should a learner take away from it?

      +

      Alex: Start with Learning Cards: Security Checklist. There is something to understand, something to try, and something that proves the try worked.

      +

      Alex: A few details make that real. The checklist below uses Markdown task list formatting -- each item is announced as "checkbox not checked". Items are grouped into three categories: Before Committing, Before Pushing, and Repository Setup. Read through the list once to learn the habits, then use it as a pre-push routine. Checkboxes create a clear visual pattern for scanning -- each line starts with a square box. Three groups are separated by h3 headings: Before Committing, Before Pushing, Repository Setup. Consider copying this checklist into a personal note and checking items off for each project.

      +

      Alex: This is the part worth saying out loud. Here is the plain-English version of 9. Security Checklist for Contributors. Use this before every push to a public repository.

      +

      Jamie: What does someone need before they touch the keyboard?

      +

      Alex: Start with Before committing. There is something to understand, something to try, and something that proves the try worked.

      +

      Alex: On the ground, that means a few things. [ ] I reviewed git diff --staged and didn't see any tokens, passwords, or keys. [ ] I used git add or git add -p rather than git add. [ ] Any.env files or credential files are listed in.gitignore. [ ] Config files with real values are in.gitignore; only example/template files are committed.

      +
      +

      Alex: Hold that next to this. Start with Before pushing. There is something to understand, something to try, and something that proves the try worked.

      +

      Alex: Here is what that changes in practice. [ ] git log --oneline -5 -- all commits look expected. [ ] No commits with messages like "remove secret" or "oops" that suggest a secret was added and removed (the secret is still in history).

      +

      Jamie: If setup starts to feel like a barrier, how should a learner think about it?

      +

      Alex: Start with Repository setup (one time). There is something to understand, something to try, and something that proves the try worked.

      +

      Alex: The room should hear these as checkpoints. [ ].gitignore includes.env,.key,.pem, and relevant patterns for your stack. [ ] Global.gitignore ( /.gitignore global) covers editor/OS files. [ ] Git credential helper is configured to use the OS keychain. [ ] (Optional) A pre-commit hook is installed to scan for secrets automatically.

      +

      Alex: That matters because of the next idea. Start with If you're a maintainer: See also: Appendix L: GitHub Security Features for the GitHub platform security tools (Dependabot, secret scanning alerts, code scanning). The next useful detail is this: Appendix D: Git Authentication for SSH keys, PATs, and commit signing.

      +

      Alex: These are the details that keep the idea from floating away. [ ] Branch protection is enabled on main with required reviews and status checks. [ ] Secret scanning is enabled (Settings → Code security → Secret scanning). [ ] Push protection is enabled for the repository. [ ] A SECURITY.md file exists with instructions for reporting vulnerabilities.

      +
      +

      Jamie: What should people carry with them after this?

      +

      Alex: Carry the map. Know what page or tool you are in, know which action you are taking, and know what confirmation should follow. If the confirmation is missing, pause. That pause is not wasted time; it is professional judgment.

      +

      Jamie: That is a better way to say it than just follow the steps.

      +

      Alex: Right. Steps matter, but understanding wins. That is episode 51. Next in the series is episode 52, where we keep building the same contributor muscles.

      +
      + +
      +

      74. Episode 52: GitHub Desktop

      +

      Using GitHub Desktop as an accessible alternative for cloning, branching, committing, and syncing.

      +

      Based on: Appendix H: GitHub Desktop

      +

      Audio and transcript are being regenerated for this episode.

      +
      +Read Transcript - Episode 52: GitHub Desktop + +

      Transcript

      +

      Alex: Welcome to Git Going with GitHub, episode 52: GitHub Desktop. I am Alex. Today we are going to make GitHub Desktop something you can explain, practice, and recover from when the interface surprises you.

      +

      Jamie: And I am Jamie. I will be the voice of the learner who is willing to ask, what is this for, where am I, and how do I know I did it right?

      -

      Alex: This is the part worth saying out loud. Here is the plain-English version of 4. What Is a Branch? See also: Chapter 14: Git in Practice shows how to create and switch branches hands-on in VS Code. Put another way, a branch is a name that points to a specific commit. It is like learning a transit route. The names of the stops matter because they tell you whether you are still going the right direction.

      -

      Jamie: Let's pause on The default branch: main. What should a learner take away from it?

      -

      Alex: This is where The default branch: main becomes real: every repository has a default branch, usually called main. That matters in practice: 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.

      -

      Alex: The next layer is this. Keep the learner anchored in Creating a branch. When you create a new branch, Git creates a new pointer that starts at the same commit you are currently on. This is the part to say slowly: Both branches point to the same commit.

      +

      Alex: The big idea today: Using GitHub Desktop as an accessible alternative for cloning, branching, committing, and syncing. We will name the concept, explain why it matters, practice the move, and point out the checks that tell you the work is real.

      +

      Jamie: So the episode should work even if someone has not read the chapter yet.

      +

      Alex: Exactly. The transcript has to stand on its own. It can point toward practice, but it should teach the concept right here in the conversation.

      -

      Jamie: Let's pause on Making commits on a branch. What should a learner take away from it?

      -

      Alex: The reason Making commits on a branch matters is that when you make a new commit while on the fix/typo branch, the fix/typo pointer moves forward to the new commit. That gives the learner a simple foothold: the main pointer stays where it was.

      -

      Alex: Now bring the learner back to the room. Start with HEAD: which branch are you on?: Git uses a special pointer called HEAD to track which branch you are currently working on. The next useful detail is this: When you switch branches (checkout), Git moves HEAD to point to the new branch and updates the files in your working directory to match. Think of it like entering a new building: first you find the lobby, then the room, then the door you actually need.

      -

      Jamie: Let's pause on Learning Cards: Branches. What should a learner take away from it?

      -

      Alex: Start with Learning Cards: Branches. There is something to understand, something to try, and something that proves the try worked.

      -

      Alex: These are the details that keep the idea from floating away. 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. 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.

      +

      Jamie: Okay, set the room for us. What are we walking into?

      +

      Alex: Start with A Visual Git Client for Every Workflow: Who this is for: You want a dedicated graphical Git application -- something separate from your code editor, with a clear visual interface for cloning, branching, committing, and managing pull requests. The next useful detail is this: GitHub Desktop is a great fit if you prefer working with a purpose-built Git GUI, or if VS Code's Source Control panel feels too embedded in the editor for your workflow.

      +

      Alex: A solid Git habit is to know which branch you are on, what changed, and what confirmation you expect before you run the next command.

      +

      Alex: The next layer is this. Here is the plain-English version of 1. What GitHub Desktop Does (and Doesn't Do). GitHub Desktop covers the everyday Git workflow that most contributors use on most days. It is like learning a transit route. The names of the stops matter because they tell you whether you are still going the right direction.

      +

      Jamie: What is the one idea that makes the next few steps less mysterious?

      +

      Alex: Start with What it supports. There is something to understand, something to try, and something that proves the try worked.

      +

      Alex: That shows up in the workshop in a few specific ways. Supported: Clone repositories from GitHub. Supported: Create, switch, and delete branches. Supported: Stage files (and individual lines/hunks within files). Supported: Write commit messages and commit. Supported: Push and pull from GitHub. Supported: Open pull requests (launches GitHub.com in your browser).

      -

      Alex: That matters because of the next idea. This is where 5. Local vs Remote becomes real: see also: Appendix D: Git Authentication covers how to set up credentials so push and pull work without password prompts. That matters in practice: So far, we have talked about one repository.

      -

      Jamie: Let's pause on The remote repository. What should a learner take away from it?

      -

      Alex: Keep the learner anchored in The remote repository. The remote repository is the one on GitHub.com. This is the part to say slowly: When you see a repository URL like github.com/Community-Access/git-going-with-github, that is the remote.

      -

      Alex: Keep the teaching thread moving. The reason The local repository matters is that the local repository is the copy on your computer. That gives the learner a simple foothold: when you run git clone, Git downloads the entire repository -- all files, all branches, all history -- to your machine. The interface gets friendlier when it stops being a wall of controls and starts being a set of named places.

      +

      Alex: Now bring the learner back to the room. Keep the learner anchored in What it does not support (use Git CLI or VS Code terminal instead). For these operations, open the repository in your terminal directly from GitHub Desktop -- Repository → Open in Terminal or Repository → Open in Command Prompt puts you in the right directory instantly.

      +

      Alex: For a learner, the useful signals are these. Not supported in the GitHub Desktop UI: Interactive rebase (git rebase -i). Not supported in the GitHub Desktop UI: git bisect. Not supported in the GitHub Desktop UI: git clean. Not supported in the GitHub Desktop UI: Creating annotated tags. Not supported in the GitHub Desktop UI: Commit signing (GPG/SSH).

      +

      Jamie: What should someone listen for when a lesson offers more than one tool path?

      +

      Alex: Start with Learning Cards: What GitHub Desktop Does. There is something to understand, something to try, and something that proves the try worked.

      +

      Alex: The parts worth keeping in working memory are these. GitHub Desktop handles cloning, branching, staging, committing, and pushing -- all accessible via keyboard and standard form controls. For operations Desktop does not support (rebase, bisect, clean), use Repository then Open in Terminal to land in the right directory instantly. All commit message fields are standard text inputs that screen readers announce as editable text. GitHub Desktop supports system-level zoom and high-contrast OS themes on both Windows and macOS. The diff panel uses green and red backgrounds for additions and deletions -- pair these with font size adjustments in your OS display settings. If the diff colors are hard to distinguish, open the same diff in VS Code via Repository then Open in VS Code for more theme options.

      +

      Alex: The useful habit is simple: orient first, act second, verify third. That pause before acting is part of the work.

      +

      Jamie: Give me the sequence, because order matters here.

      +

      Alex: Start with Windows. There is something to understand, something to try, and something that proves the try worked.

      +

      Alex: First, go to desktop.github.com. Then, select "Download for Windows". After that, run the installer -- it installs and launches automatically. Think of it as a rail line: each stop confirms you are still on the right route before the next one.

      -

      Jamie: Let's pause on The two-copy model. What should a learner take away from it?

      -

      Alex: Start with The two-copy model: The text diagram above shows two boxes side by side connected by arrows. The next useful detail is this: The left box is labeled "Your computer (local)" and contains working directory, staging area, and repository.

      -

      Alex: Keep the teaching thread moving. Start with Learning Cards: Local vs Remote. There is something to understand, something to try, and something that proves the try worked.

      -

      Alex: For a learner, the useful signals are these. 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. 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.

      -

      Jamie: Let's pause on 6. Push, Pull, and Fetch. What should a learner take away from it?

      -

      Alex: This is where 6. Push, Pull, and Fetch becomes real: these three operations keep your local and remote repositories synchronized.

      -

      Alex: A solid pull request habit is to separate three questions: what changed, why it changed, and what still needs review. That keeps the conversation useful instead of noisy.

      +

      Jamie: How would you walk the room through that step by step?

      +

      Alex: Here is the plain-English version of macOS. Linux: GitHub Desktop does not officially support Linux. Put another way, linux users should use VS Code's Source Control panel or the Git CLI.

      +

      Alex: First, go to desktop.github.com. Then, select "Download for macOS". After that, open the downloaded.zip, drag GitHub Desktop to your Applications folder. Treat it like a recipe: do not add the next ingredient until the previous one is actually in the bowl.

      +

      Alex: This is where the talk moves from concept to action. This is where 3. Signing In and Authentication becomes real: GitHub Desktop uses browser-based OAuth sign-in -- no tokens or SSH keys needed. That matters in practice: It handles authentication for you automatically.

      +

      Jamie: Turn that into a path someone can follow.

      +

      Alex: Keep the learner anchored in Sign in on first launch. GitHub Desktop stores your credentials securely in the system keychain. This is the part to say slowly: You won't be asked for a password again.

      +

      Alex: First, open GitHub Desktop. Then, select "Sign in to GitHub.com". After that, your browser opens to a GitHub authorization page -- sign in with your GitHub account. Finally, authorize GitHub Desktop when prompted. It is like walking a hallway with named doors: read the sign, enter the right room, then confirm where you landed.

      +

      Jamie: What is the ordered workflow?

      +

      Alex: First, switch back to GitHub Desktop -- you're signed in. The rhythm is simple: orient, act, verify, then continue.

      Jamie: How do you keep commands from becoming magic words?

      -

      Alex: Keep the learner anchored in Push: share your work. git push sends your local commits to the remote. This is the part to say slowly: After pushing, anyone who looks at the repository on GitHub.com will see your changes. A good GitHub workflow is like a well-run meeting: everyone knows the topic, the next action, and who has the floor.

      -

      Alex: Treat examples as spoken recipes, not decorations. You may hear something like git push origin fix/typo. git push -u origin fix/typo. Read the command, understand what it changes, then run it only when the repository state matches the lesson.

      -

      Jamie: What is the safe way to learn from that example?

      -

      Alex: The reason Pull: get other people's work matters is that git pull downloads new commits from the remote and immediately merges them into your current branch. That gives the learner a simple foothold: this is how you get changes that other people (or you on another computer) have pushed.

      -

      Alex: Treat examples as spoken recipes, not decorations. You may hear something like git pull origin main. Read the command, understand what it changes, then run it only when the repository state matches the lesson.

      -

      Jamie: What should happen before anyone copies and runs it?

      -

      Alex: Start with Fetch: check for updates without merging: git fetch downloads new commits from the remote but does not change your working directory or current branch. The next useful detail is this: It just updates your local knowledge of what the remote looks like.

      -

      Alex: Treat examples as spoken recipes, not decorations. You may hear something like git fetch origin. git log main.origin/main --oneline. Read the command, understand what it changes, then run it only when the repository state matches the lesson.

      -
      -

      Jamie: Let's pause on 7. Why Merge Conflicts Happen. What should a learner take away from it?

      -

      Alex: Here is the plain-English version of 7. Why Merge Conflicts Happen. A merge conflict happens when Git cannot automatically combine two sets of changes.

      -

      Alex: Keep the teaching thread moving. This is where When conflicts occur becomes real: conflicts happen when two branches modify the same lines in the same file. That matters in practice: Git knows how to merge changes to different files, and even different parts of the same file. The workshop is closer to rehearsal than lecture. You hear the move, try the move, and then check what changed.

      -

      Jamie: Let's pause on What a conflict looks like. What should a learner take away from it?

      -

      Alex: Keep the learner anchored in What a conflict looks like. When a conflict occurs, Git marks the conflicting section in the file with special markers.

      +

      Alex: The reason 4. The Interface at a Glance matters is that GitHub Desktop has three main areas. The interface gets friendlier when it stops being a wall of controls and starts being a set of named places.

      +

      Alex: Treat examples as spoken recipes, not decorations. You may hear something like ┌─────────────────────────────────────────────────────────┐; │ Toolbar: Current Repository ▾ Current Branch ▾ │; │ Fetch/Push button │; ├─────────────────┬───────────────────────────────────────┤; │ │ │; │ Left panel: │ Main area: │; │ Changes tab │ File diff. Read the command, understand what it changes, then run it only when the repository state matches the lesson.

      +

      Jamie: How do we make tool choice feel like access, not pressure?

      +

      Alex: Start with Learning Cards: The Desktop Interface. There is something to understand, something to try, and something that proves the try worked.

      +

      Alex: A few details make that real. Use Tab to move between the toolbar, file list, diff pane, and commit area -- each is a distinct focus region. The branch selector is a searchable dropdown: type to filter, Down Arrow to navigate, Enter to select. The commit button is announced as "Commit to [branch name]" -- press Enter to activate. The toolbar at the top stays fixed as you scroll -- repository name, branch, and sync button are always visible. Increase your OS display scaling to enlarge all panels proportionally without breaking the layout. The Changes and History tabs are side-by-side at the top of the left panel -- each tab label is clearly distinct.

      +

      Jamie: What does the learner do first, second, and then after that?

      +

      Alex: Here is the plain-English version of From GitHub.com. The easiest way is to go to the repository on GitHub.com and use the Code button.

      +

      Alex: First, on the repository page, activate Code → Open with GitHub Desktop. Then, GitHub Desktop opens with a dialog confirming the URL. After that, choose where to save the repository on your computer. Finally, select "Clone". Treat it like a recipe: do not add the next ingredient until the previous one is actually in the bowl.

      -

      Jamie: Let's pause on How to resolve a conflict. What should a learner take away from it?

      -

      Alex: The reason How to resolve a conflict matters is that the Day 1 connection: In Chapter 7, you resolved a merge conflict on GitHub.com using the web editor. That gives the learner a simple foothold: 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.

      -

      Alex: First, open the file with the conflict markers. Then, read both versions and decide which text to keep (or write a new version that combines both). After that, delete the conflict markers ( ). Finally, save the file. The rhythm is simple: orient, act, verify, then continue.

      -

      Jamie: Before we leave How to resolve a conflict, what is the practical point?

      -

      Alex: First, stage and commit the resolved file. Think of it as a rail line: each stop confirms you are still on the right route before the next one.

      -

      Jamie: Let's pause on Why conflicts are normal. What should a learner take away from it?

      -

      Alex: Start with Why conflicts are normal: They happen in every project where more than one person works at the same time. The next useful detail is this: The fact that Git stops and asks is a safety feature -- it prevents data loss by never silently choosing one version over another.

      -

      Alex: Keep the teaching thread moving. Start with Learning Cards: Merge Conflicts. There is something to understand, something to try, and something that proves the try worked.

      -

      Alex: That becomes easier when you listen for these cues. 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. 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.

      +

      Jamie: Let's pause on From inside GitHub Desktop. What should a learner take away from it?

      +

      Alex: Start with From inside GitHub Desktop. There is something to understand, something to try, and something that proves the try worked.

      +

      Alex: First, press Ctrl+Shift+O (Windows) or Cmd+Shift+O (macOS) -- "Clone a repository". Then, choose the GitHub.com tab to browse your own repositories, or the URL tab to paste any repo URL. After that, select or type the repository. Finally, choose a local path. It is a checklist, but a meaningful one: every item creates evidence that the next step is safe.

      +

      Jamie: Before we leave From inside GitHub Desktop, what is the practical point?

      +

      Alex: First, select "Clone". It is like walking a hallway with named doors: read the sign, enter the right room, then confirm where you landed.

      +

      Jamie: What is the safe way to learn from that example?

      +

      Alex: Start with GitHub CLI alternative. There is something to understand, something to try, and something that proves the try worked.

      +

      Alex: Treat examples as spoken recipes, not decorations. You may hear something like gh repo clone owner/repo-name; Then open it in GitHub Desktop:; github /path/to/repo. Read the command, understand what it changes, then run it only when the repository state matches the lesson.

      +

      Jamie: Let's pause on Create a new branch. What should a learner take away from it?

      +

      Alex: The reason Create a new branch matters is that GitHub Desktop switches to the new branch immediately.

      +

      Alex: First, click Current Branch in the toolbar (or press Ctrl+Shift+N / Cmd+Shift+N). Then, type a name for your new branch. After that, select "Create Branch". Finally, choose whether to base it on the current branch or another -- usually keep the default. The rhythm is simple: orient, act, verify, then continue.

      -

      Jamie: Let's pause on 8. The Git Timeline. What should a learner take away from it?

      -

      Alex: This is where 8. The Git Timeline becomes real: every commit has a parent pointer (except the very first commit). That matters in practice: This creates a chain -- a timeline of the project's history.

      -

      Alex: Keep the teaching thread moving. Keep the learner anchored in 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. This is the part to say slowly: 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.

      -

      Jamie: Let's pause on Branching creates parallel timelines. What should a learner take away from it?

      -

      Alex: The reason Branching creates parallel timelines matters is that when two branches diverge (both have commits that the other does not), the timeline splits into two parallel paths. That gives the learner a simple foothold: both branches share commits A and B (their common history).

      +

      Jamie: Let's pause on Switch to an existing branch. What should a learner take away from it?

      +

      Alex: Start with Switch to an existing branch. There is something to understand, something to try, and something that proves the try worked.

      +

      Alex: First, click Current Branch in the toolbar. Then, type to search or scroll through the branch list. After that, click the branch name -- GitHub Desktop switches and updates your files. Think of it as a rail line: each stop confirms you are still on the right route before the next one.

      +

      Jamie: Let's pause on Delete a branch. What should a learner take away from it?

      +

      Alex: Here is the plain-English version of Delete a branch. The branch selector is a dropdown that opens a searchable list. Put another way, screen readers announce the currently selected branch name in the toolbar.

      +

      Alex: First, click Current Branch in the toolbar. Then, right-click the branch you want to delete. After that, select "Delete.". Treat it like a recipe: do not add the next ingredient until the previous one is actually in the bowl.

      +

      Alex: Keep the thread going. This is where Reviewing your changes becomes real: when you edit files in your editor and save them, GitHub Desktop automatically detects the changes and shows them in the Changes tab on the left. The workshop is closer to rehearsal than lecture. You hear the move, try the move, and then check what changed.

      +

      Alex: The room should hear these as checkpoints. The left panel lists every changed file with a checkbox. The right panel shows the diff for the selected file -- red lines removed, green lines added.

      +

      Alex: A solid pull request habit is to separate three questions: what changed, why it changed, and what still needs review. That keeps the conversation useful instead of noisy.

      -

      Alex: Keep the teaching thread moving. Start with 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 next useful detail is this: The two timelines join back together. Think of it like entering a new building: first you find the lobby, then the room, then the door you actually need.

      -

      Jamie: Let's pause on 9. Putting It All Together. What should a learner take away from it?

      -

      Alex: Here is the plain-English version of 9. Putting It All Together. Here is the complete workflow that you will practice in Chapter 14, translated through the mental model. Put another way, everything in this table maps directly to the three areas (Section 2), the two copies (Section 5), and the timeline (Section 8).

      -

      Alex: Keep the teaching thread moving. This is where Quick mental model checklist becomes real: before running a Git command, ask yourself. That matters in practice: If you can answer these four questions, you can troubleshoot almost any Git situation.

      -

      Alex: The practical takeaway is this. 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?

      +

      Jamie: If I am listening before the workshop starts, what should settle in my mind first?

      +

      Alex: Keep the learner anchored in Staging files. Every file with a checked checkbox will be included in your next commit.

      +

      Alex: These are the details that keep the idea from floating away. Check all -- click the checkbox at the top of the list to stage everything. Uncheck a file to exclude it from the commit (it stays as an uncommitted change).

      +

      Jamie: Let's pause on Staging individual lines (hunks). What should a learner take away from it?

      +

      Alex: The reason Staging individual lines (hunks) matters is that if a file has multiple changes and you only want to commit some of them.

      +

      Alex: First, select the file in the Changes list. Then, in the diff view, right-click a line or block. After that, select "Stage Line" or "Stage Hunk" -- only those lines get included in the commit. The rhythm is simple: orient, act, verify, then continue.

      +

      Jamie: Let's pause on Writing your commit message. What should a learner take away from it?

      +

      Alex: Start with Writing your commit message: GitHub Copilot can help: Not sure what to write? The next useful detail is this: Open VS Code alongside GitHub Desktop, open Copilot Chat, and ask: "Write a commit message for these changes: [describe what you changed]." Or use the conventional commit format: feat:, fix:, docs:, refactor.

      +

      Alex: First, in the Summary field at the bottom, type a short commit message (under 72 characters is ideal). Then, optionally add a longer description in the Description field below it. After that, select "Commit to [branch name]" -- your changes are committed locally. Think of it as a rail line: each stop confirms you are still on the right route before the next one.

      -

      Jamie: What do you want them to do when the plan breaks?

      -

      Alex: Keep the learner anchored in 10. If You Get Stuck. Next: Chapter 14: Git in Practice Back: Chapter 12: VS Code Accessibility Related appendices: Appendix E: Advanced Git Appendix D: Git Authentication.

      -

      Alex: Keep the teaching thread moving. The reason Going Deeper with Git matters is that who this is for: You have completed Chapter 11 (Git & Source Control) and feel comfortable with the basics -- cloning, branching, committing, pushing, and pulling. That gives the learner a simple foothold: this appendix covers the next tier of Git skills that come up constantly in real open source contribution: cherry-picking fixes across branches, cleaning up messy commit history before a PR, safely undoing mistakes, and understanding why your push sometimes. The interface gets friendlier when it stops being a wall of controls and starts being a set of named places.

      -

      Jamie: Let's pause on Learning Cards: Using This Advanced Git Reference. What should a learner take away from it?

      -

      Alex: Start with Learning Cards: Using This Advanced Git Reference. There is something to understand, something to try, and something that proves the try worked.

      -

      Alex: The practical takeaway is this. Each operation is a numbered h2 section with three sub-paths: VS Code, GitHub CLI, and Git CLI. Use H to jump between operations and 3 to jump between the tool-specific sub-headings within each. The Table of Contents above has anchor links -- activate any link to jump directly to that operation. Command examples are in labeled code blocks -- increase zoom and each command fits on one line. Every section follows the same structure: what it is, when to use it, then tool-specific steps. The Quick Reference table near the bottom gives a one-row-per-operation summary for fast lookup.

      +

      Alex: This is the part worth saying out loud. Here is the plain-English version of 8. Push and Pull. After committing, your changes are saved locally but not yet on GitHub. Put another way, the Fetch/Push button in the top-right toolbar handles syncing. It is like learning a transit route. The names of the stops matter because they tell you whether you are still going the right direction.

      +

      Jamie: What would you say to someone who is already bracing for this to be too much?

      +

      Alex: This is where Pushing commits to GitHub becomes real: after committing, the button changes to "Push origin" with an upward arrow and the number of commits waiting.

      +

      Alex: On the ground, that means a few things. Click "Push origin" -- your commits go to GitHub.

      +

      Alex: That connects to another useful point. Keep the learner anchored in Pulling changes from GitHub. When collaborators have pushed new commits, the button shows "Pull origin" with a downward arrow.

      +

      Alex: Here is what that changes in practice. Click "Pull origin" -- GitHub Desktop downloads the new commits and updates your local branch.

      -

      Alex: Keep the teaching thread moving. Here is the plain-English version of 1. Cherry-Pick -- Grabbing a Specific Commit. What it is: Cherry-pick lets you take a single commit from any branch and apply it to your current branch. Put another way, think of it like copy-pasting a specific change -- without bringing the entire branch along with it.

      -

      Alex: The practical takeaway is this. You fixed a bug on a feature branch, but main also needs that fix right now. A teammate landed a commit on their branch and you need just that one change. You accidentally committed to the wrong branch and need to move that commit somewhere else.

      -

      Jamie: Let's pause on Finding the Commit SHA. What should a learner take away from it?

      -

      Alex: This is where Finding the Commit SHA becomes real: before cherry-picking, you need the commit's SHA (the unique ID for that commit).

      -

      Jamie: Let's pause on VS Code. What should a learner take away from it?

      -

      Alex: Start with VS Code. There is something to understand, something to try, and something that proves the try worked.

      -

      Alex: First, open the Timeline panel: Click View → Open View → Timeline (or press Ctrl+Shift+P and type "Timeline"). Then, switch to the branch that has the commit you want, browse the Timeline, and copy the commit SHA shown in the details panel. It is like walking a hallway with named doors: read the sign, enter the right room, then confirm where you landed.

      +

      Jamie: Where do you want a learner to place their attention here?

      +

      Alex: Start with Fetching (checking without pulling). There is something to understand, something to try, and something that proves the try worked.

      +

      Alex: That becomes easier when you listen for these cues. Click "Fetch origin" -- GitHub Desktop checks for new commits and shows you the count, but doesn't update your files yet. This is safe to do at any time -- it's read-only.

      +

      Jamie: Let's pause on 9. Syncing Your Fork. What should a learner take away from it?

      +

      Alex: Start with 9. Syncing Your Fork: If you forked a repository and the original upstream repo has new commits you want to bring in. Think of it like entering a new building: first you find the lobby, then the room, then the door you actually need.

      +

      Alex: First, go to Branch → Merge into current branch. Then, in the branch picker, switch to the "Other branches" tab. After that, select upstream/main (or upstream/master) -- the upstream remote's default branch. Finally, select "Create a merge commit". Think of it as a rail line: each stop confirms you are still on the right route before the next one.

      +

      Jamie: Before we leave 9. Syncing Your Fork, what is the practical point?

      +

      Alex: First, then push to your fork with "Push origin". Treat it like a recipe: do not add the next ingredient until the previous one is actually in the bowl.

      +

      Jamie: Let's pause on Setting up the upstream remote (if not already there). What should a learner take away from it?

      +

      Alex: Here is the plain-English version of Setting up the upstream remote (if not already there). GitHub Desktop adds the upstream remote automatically when you clone a fork from GitHub.com.

      +

      Alex: First, open the repository in terminal: Repository → Open in Terminal. Then, switch back to GitHub Desktop -- it will now see the upstream branches. Treat it like a recipe: do not add the next ingredient until the previous one is actually in the bowl.

      +

      Alex: Treat examples as spoken recipes, not decorations. You may hear something like git remote add upstream https://github.com/ORIGINAL-OWNER/ORIGINAL-REPO.git; git fetch upstream. Read the command, understand what it changes, then run it only when the repository state matches the lesson.

      -

      Jamie: What should they understand before typing anything?

      -

      Alex: The reason Git CLI matters is that the short SHA is the first 7 characters (a1b2c3d).

      -

      Alex: Treat examples as spoken recipes, not decorations. You may hear something like See commits on another branch without switching to it; git log feature/bug-fix --oneline; Output:; a1b2c3d Fix null pointer error in auth module; e4f5g6h Add unit tests for login. Read the command, understand what it changes, then run it only when the repository state matches the lesson.

      -

      Jamie: Let's pause on VS Code (Command Palette). What should a learner take away from it?

      -

      Alex: Start with VS Code (Command Palette). There is something to understand, something to try, and something that proves the try worked.

      -

      Alex: First, press Ctrl+Shift+P (or Cmd+Shift+P on macOS). Then, type "cherry" and select "Git: Cherry Pick.". After that, paste or type the commit SHA. Finally, press Enter -- VS Code applies the commit to your current branch. Think of it as a rail line: each stop confirms you are still on the right route before the next one.

      -

      Jamie: Let's pause on GitHub CLI. What should a learner take away from it?

      -

      Alex: Here is the plain-English version of GitHub CLI. The GitHub CLI doesn't have a direct cherry-pick command (it's a local Git operation), but you can use it to find the SHA first.

      -

      Alex: Treat examples as spoken recipes, not decorations. You may hear something like List commits on a branch via gh to find the one you want; gh api repos/{owner}/{repo}/commits?sha=feature/bug-fix --jq '.[].sha,.[].commit.message' head -20; Then cherry-pick using git; git cherry-pick a1b2c3d. Read the command, understand what it changes, then run it only when the repository state matches the lesson.

      +

      Alex: That matters because of the next idea. This is where 10. Resolving Merge Conflicts becomes real: when you pull from GitHub or merge a branch and there are conflicts, GitHub Desktop shows a dialog listing the conflicting files.

      +

      Jamie: Let's pause on Step by step. What should a learner take away from it?

      +

      Alex: Start with Step by step. There is something to understand, something to try, and something that proves the try worked.

      +

      Alex: The practical anchors are these. "Open in [your editor]" -- opens the file with conflict markers for manual editing. "Use mine" / "Use theirs" -- accept one entire side of the conflict without editing.

      +

      Alex: First, GitHub Desktop shows a "Resolve conflicts before merging" screen. Then, each conflicting file has two options next to it. After that, for simple conflicts (one side is clearly right), use "Use mine" or "Use theirs". Finally, for conflicts where you need to keep parts of both, select "Open in [editor]" and resolve manually. It is like walking a hallway with named doors: read the sign, enter the right room, then confirm where you landed.

      +

      Jamie: Let's pause on After resolving in your editor. What should a learner take away from it?

      +

      Alex: The reason After resolving in your editor matters is that GitHub Copilot can help: Open the conflicting file in VS Code alongside GitHub Desktop. That gives the learner a simple foothold: place your cursor inside a conflict region and open Copilot Chat (Ctrl+Shift+I): "Resolve this merge conflict -- keep meaningful changes from both sides." Copilot suggests a resolution; you review and save. The interface gets friendlier when it stops being a wall of controls and starts being a set of named places.

      +

      Alex: First, save the file. Then, switch back to GitHub Desktop -- the file moves from "Conflicting" to "Resolved". After that, once all conflicts are resolved, select "Continue merge". The rhythm is simple: orient, act, verify, then continue.

      -

      Jamie: Let's pause on Git CLI. What should a learner take away from it?

      -

      Alex: Start with Git CLI. There is something to understand, something to try, and something that proves the try worked.

      -

      Alex: Treat examples as spoken recipes, not decorations. You may hear something like Apply a single commit; git cherry-pick a1b2c3d; Apply a range of commits (from older to newer, exclusive of first); git cherry-pick a1b2c3d.e4f5g6h; Apply without automatically committing (lets you review changes first); git cherry-pick --no-commit a1b2c3d. Read the command, understand what it changes, then run it only when the repository state matches the lesson.

      -

      Jamie: Let's pause on If There's a Conflict. What should a learner take away from it?

      -

      Alex: Keep the learner anchored in If There's a Conflict. Cherry-pick can hit conflicts just like a merge. This is the part to say slowly: When a cherry-pick stops due to a conflict, run git status in the terminal -- it announces exactly which files need attention.

      -

      Alex: First, Git pauses and marks the conflicting files (same <<<<<<< HEAD markers as merge conflicts). Then, resolve the conflicts in VS Code's conflict editor (see Chapter 7: Merge Conflicts). After that, stage the resolved files. Finally, then either. It is like walking a hallway with named doors: read the sign, enter the right room, then confirm where you landed.

      -

      Alex: Treat examples as spoken recipes, not decorations. You may hear something like Continue the cherry-pick after resolving; git cherry-pick --continue; Or cancel it entirely and go back to where you started; git cherry-pick --abort. Read the command, understand what it changes, then run it only when the repository state matches the lesson.

      -

      Alex: Keep the teaching thread moving. The reason 2. Interactive Rebase -- Cleaning Up Your History matters is that what it is: Interactive rebase (git rebase -i) is like a time machine for your commits. That gives the learner a simple foothold: before you open a PR, you can reorder commits, combine several small commits into one clean commit, rewrite commit messages, or remove commits that were just experiments.

      -

      Alex: The practical takeaway is this. You made 8 "WIP" commits while working and want to combine them into 1 clean commit for your PR. You want to reword a commit message to better describe what changed. You accidentally committed a debug file and want to remove that commit entirely.

      +

      Jamie: Give me the version that sounds like an instructor, not a manual.

      +

      Alex: Start with 11. Viewing History: The History tab (next to the Changes tab in the left panel) shows every commit on the current branch.

      +

      Jamie: Let's pause on Navigating history. What should a learner take away from it?

      +

      Alex: Start with Navigating history. There is something to understand, something to try, and something that proves the try worked.

      +

      Alex: First, click the History tab. Then, each commit appears as a row: author avatar, commit message, author name, and timestamp. After that, click any commit to see the full diff on the right -- what changed in each file. Treat it like a recipe: do not add the next ingredient until the previous one is actually in the bowl.

      +

      Jamie: Let's pause on Filtering commits. What should a learner take away from it?

      +

      Alex: This is where Filtering commits becomes real: type in the search field above the commit list to filter by commit message, author, or SHA.

      -

      Jamie: Before we leave VS Code, what is the practical point?

      -

      Alex: Start with VS Code: VS Code has basic rebase support via the Command Palette, but for full interactive rebase you'll want the terminal. The next useful detail is this: After that, git rebase -i will open the commit list in VS Code itself -- much more screen-reader-friendly.

      -

      Alex: First, open the Integrated Terminal: Ctrl+Backtick. Then, run the command below to rebase the last N commits (replace N with how many commits you want to edit). After that, your default editor opens with a list of your commits. If it opens in vim, type i to enter insert mode, make your edits, then press Esc followed by:wq to save. If you'd prefer VS Code as the editor. Think of it as a rail line: each stop confirms you are still on the right route before the next one.

      -

      Alex: Treat examples as spoken recipes, not decorations. You may hear something like git rebase -i HEAD 3; This opens your last 3 commits for editing. git config --global core.editor "code --wait". Read the command, understand what it changes, then run it only when the repository state matches the lesson.

      -

      Jamie: Let's pause on Git CLI (Terminal). What should a learner take away from it?

      -

      Alex: Start with Git CLI (Terminal). There is something to understand, something to try, and something that proves the try worked.

      -

      Alex: Treat examples as spoken recipes, not decorations. You may hear something like Rebase the last 3 commits; git rebase -i HEAD 3; Or rebase everything since you branched from main; git rebase -i main. Read the command, understand what it changes, then run it only when the repository state matches the lesson.

      -

      Jamie: Let's pause on The Commit List -- What You're Looking At. What should a learner take away from it?

      -

      Alex: This is where The Commit List -- What You're Looking At becomes real: when the editor opens, you see something like this. That matters in practice: Each line starts with a command word.

      +

      Jamie: Let's pause on Viewing a specific file's history. What should a learner take away from it?

      +

      Alex: Start with Viewing a specific file's history. There is something to understand, something to try, and something that proves the try worked.

      +

      Alex: First, right-click any file in your project (via the Files panel in the diff area). Then, select "Show in History" -- the commit list filters to only commits that touched that file. It is like walking a hallway with named doors: read the sign, enter the right room, then confirm where you landed.

      +

      Jamie: Let's pause on Comparing branches. What should a learner take away from it?

      +

      Alex: Start with Comparing branches. There is something to understand, something to try, and something that proves the try worked.

      +

      Alex: First, click History. Then, in the branch comparison bar above the commit list, switch to another branch. After that, GitHub Desktop shows the commits that are different between your current branch and the selected branch. The rhythm is simple: orient, act, verify, then continue.

      +

      Alex: Here is the practical turn. Start with 12. Cherry-Pick in GitHub Desktop: Cherry-pick lets you take a commit from another branch and apply it to your current branch -- without merging the whole branch.

      -

      Alex: Keep the teaching thread moving. Keep the learner anchored in Example: Squashing 3 Commits Into 1. Git opens a second editor for you to write the combined commit message. This is the part to say slowly: Write a clean summary and save -- done.

      -

      Jamie: Let's pause on Example: Rewriting a Commit Message. What should a learner take away from it?

      -

      Alex: The reason Example: Rewriting a Commit Message matters is that Git opens the commit message for a1b2c3d for you to edit. That gives the learner a simple foothold: write the new message, save -- done.

      -

      Jamie: Let's pause on If Something Goes Wrong. What should a learner take away from it?

      -

      Alex: Start with If Something Goes Wrong: Run git rebase -i with VS Code as your editor (git config --global core.editor "code --wait") -- the commit list opens in a VS Code tab that your screen reader can navigate normally with arrow keys. The next useful detail is this: GitHub Copilot can help: Not sure how to word a squashed commit message? Think of it like entering a new building: first you find the lobby, then the room, then the door you actually need.

      -

      Alex: Treat examples as spoken recipes, not decorations. You may hear something like Abort the rebase and go back to where you started; git rebase --abort; If you're mid-rebase and hit a conflict, resolve it then continue; git rebase --continue. Read the command, understand what it changes, then run it only when the repository state matches the lesson.

      +

      Jamie: Let's pause on How to cherry-pick. What should a learner take away from it?

      +

      Alex: Start with How to cherry-pick. There is something to understand, something to try, and something that proves the try worked.

      +

      Alex: First, switch to the branch you want to copy the commit FROM (the source branch). Then, open the History tab. After that, find the commit you want to copy. Finally, right-click the commit. Treat it like a recipe: do not add the next ingredient until the previous one is actually in the bowl.

      +

      Jamie: Before we leave How to cherry-pick, what is the practical point?

      +

      Alex: First, select "Cherry-pick commit.". Then, choose the destination branch -- the branch you want to apply the commit TO. After that, GitHub Desktop applies the commit and switches to the destination branch. It is a checklist, but a meaningful one: every item creates evidence that the next step is safe.

      +

      Alex: Another way to ground it. This is where If there's a conflict becomes real: GitHub Desktop shows the conflict resolution screen (same as merging). That matters in practice: Resolve the conflicts in your editor, then switch back to GitHub Desktop to continue. The workshop is closer to rehearsal than lecture. You hear the move, try the move, and then check what changed.

      +

      Jamie: Let's pause on 13. Stashing Changes. What should a learner take away from it?

      +

      Alex: Keep the learner anchored in 13. Stashing Changes. Stash saves your uncommitted changes temporarily so you can switch branches or pull without committing half-finished work.

      -

      Jamie: Let's pause on 3. git reset -- Undoing at Different Depths. What should a learner take away from it?

      -

      Alex: Here is the plain-English version of 3. git reset -- Undoing at Different Depths. What it is: git reset moves the tip of your current branch backward to a previous commit. Put another way, the three modes (--soft, --mixed, --hard) control what happens to the changes that were in those commits.

      -

      Alex: The practical takeaway is this. You committed too early and want to add more changes to that commit. You staged the wrong files and want to unstage them. You want to completely throw away the last few commits and start fresh.

      -

      Alex: Keep the teaching thread moving. This is where The Three Modes becomes real: think of Git as having three layers: your working files (what you can see in the editor), the staging area (what git add puts there), and the commit history. That matters in practice: It permanently discards your uncommitted changes.

      -

      Jamie: Let's pause on Using the Source Control panel. What should a learner take away from it?

      -

      Alex: Keep the learner anchored in Using the Source Control panel. This is equivalent to git reset --soft HEAD 1 -- your changes come back as staged files, nothing is lost.

      -

      Alex: First, open Source Control: Ctrl+Shift+G. Then, click the "." (More Actions) menu at the top of the panel. After that, select "Commit → Undo Last Commit". It is like walking a hallway with named doors: read the sign, enter the right room, then confirm where you landed.

      +

      Jamie: Let's pause on Stash your changes. What should a learner take away from it?

      +

      Alex: Start with Stash your changes. There is something to understand, something to try, and something that proves the try worked.

      +

      Alex: First, go to Branch → Stash All Changes (or press Ctrl+Shift+H / Cmd+Shift+H). Then, your working directory reverts to the last commit. After that, you can now switch branches safely. The rhythm is simple: orient, act, verify, then continue.

      +

      Jamie: Let's pause on Restore your stash. What should a learner take away from it?

      +

      Alex: Start with Restore your stash: GitHub Desktop supports one stash at a time per branch. The next useful detail is this: For multiple stashes, use the Git CLI: git stash list, git stash apply stash@{1}.

      +

      Alex: First, switch back to the branch where you stashed. Then, go to Branch → Pop Stash. After that, your changes come back. Think of it as a rail line: each stop confirms you are still on the right route before the next one.

      +

      Alex: Before the learner moves on. Here is the plain-English version of Undo the last commit. Go to Edit → Undo Last Commit (or press Ctrl+Z / Cmd+Z right after committing). Put another way, this is equivalent to git reset --soft HEAD 1 -- your changes come back as staged files. It is like learning a transit route. The names of the stops matter because they tell you whether you are still going the right direction.

      -

      Jamie: Let's pause on Using the Command Palette. What should a learner take away from it?

      -

      Alex: Start with Using the Command Palette. There is something to understand, something to try, and something that proves the try worked.

      -

      Alex: Treat examples as spoken recipes, not decorations. You may hear something like Ctrl+Shift+P → type "git undo" → select "Git: Undo Last Commit". Read the command, understand what it changes, then run it only when the repository state matches the lesson.

      -

      Jamie: Before we leave Git CLI, what is the practical point?

      -

      Alex: Treat examples as spoken recipes, not decorations. You may hear something like Undo last commit -- keep changes staged (safest); git reset --soft HEAD 1; Undo last commit -- keep changes but unstage them; git reset --mixed HEAD 1; Undo last 3 commits -- keep all changes unstaged; git reset --mixed HEAD 3; Undo last commit -- DISCARD all. Read the command, understand what it changes, then run it only when the repository state matches the lesson.

      -

      Alex: Keep the teaching thread moving. Here is the plain-English version of Unstaging a File (Without Undoing the Commit). If you just want to remove a file from the staging area without touching commit history.

      +

      Jamie: Let's pause on Discard changes to a file. What should a learner take away from it?

      +

      Alex: This is where Discard changes to a file becomes real: warning: Discarding changes cannot be undone. That matters in practice: The changes are permanently deleted, not moved to trash.

      +

      Alex: First, right-click a file. Then, select "Discard Changes.". After that, confirm the dialog -- the file reverts to its last committed state. It is a checklist, but a meaningful one: every item creates evidence that the next step is safe.

      +

      Jamie: Let's pause on Discard all changes. What should a learner take away from it?

      +

      Alex: Start with Discard all changes. There is something to understand, something to try, and something that proves the try worked.

      +

      Alex: First, right-click anywhere in the Changes list. Then, select "Discard All Changes.". After that, confirm -- everything in your working directory reverts to the last commit. It is like walking a hallway with named doors: read the sign, enter the right room, then confirm where you landed.

      +

      Jamie: Let's pause on 15. Accessibility and Screen Reader Notes. What should a learner take away from it?

      +

      Alex: The reason 15. Accessibility and Screen Reader Notes matters is that GitHub Desktop has partial screen reader support. That gives the learner a simple foothold: core workflows work well with keyboard navigation; some visual-only elements (like avatar images and some icons) don't have text equivalents.

      +

      Alex: A solid navigation habit is to prove where you are before activating controls. Headings, landmarks, and the address bar are not trivia; they are your map.

      -

      Jamie: There are a lot of tools in play. How do we keep that from feeling like a contest?

      -

      Alex: This is where VS Code becomes real: in the Source Control panel, click the minus (--) icon next to a staged file, or right-click it and select "Unstage Changes".

      -

      Jamie: What is the teaching move inside Git CLI?

      -

      Alex: Treat examples as spoken recipes, not decorations. You may hear something like Unstage a specific file; git restore --staged docs/README.md; Unstage everything; git restore --staged. Read the command, understand what it changes, then run it only when the repository state matches the lesson.

      -

      Jamie: Let's pause on 4. git revert -- The Safe Undo for Shared Branches. What should a learner take away from it?

      -

      Alex: The reason 4. git revert -- The Safe Undo for Shared Branches matters is that what it is: git revert creates a new commit that undoes the changes from a previous commit. That gives the learner a simple foothold: unlike git reset, it does not rewrite history -- it adds to it.

      -

      Alex: The practical takeaway is this. A commit made it to main and it broke something -- you need to roll it back without force-pushing. You want to undo a change but keep a record that the undo happened. You're working on a protected branch where force-push is disabled.

      +

      Alex: Hold that next to this. Start with Windows -- NVDA / JAWS. There is something to understand, something to try, and something that proves the try worked.

      +

      Alex: The practical takeaway is this. Use Tab to move between panels; arrow keys within lists. The commit summary field is reached with Tab after the file list. Conflict dialogs are modal -- screen reader focus moves into the dialog automatically.

      +

      Jamie: Let's pause on macOS -- VoiceOver. What should a learner take away from it?

      +

      Alex: Start with macOS -- VoiceOver. There is something to understand, something to try, and something that proves the try worked.

      +

      Alex: The practical takeaway is this. Use Tab and VO+Arrow to navigate panels. The diff view can be explored with VO+Right through the lines. Branch selector opens a searchable popup -- type to filter, Down Arrow to navigate, Return to select.

      +

      Alex: Keep the teaching thread moving. This is where VS Code as a better accessible alternative becomes real: if screen reader navigation in GitHub Desktop is frustrating for a specific operation, VS Code's Source Control panel is often more accessible. That matters in practice: The two tools complement each other -- use whichever works best for the task at hand.

      -

      Jamie: What is the teaching move inside VS Code?

      -

      Alex: First, open the Timeline panel and navigate to the commit you want to undo. Then, right-click the commit and select "Revert Commit". After that, VS Code creates a new commit with message Revert "your original message" -- review it and push. Think of it as a rail line: each stop confirms you are still on the right route before the next one.

      -

      Jamie: If someone only remembers one thing from Git CLI, what should it be?

      -

      Alex: Treat examples as spoken recipes, not decorations. You may hear something like Revert a specific commit (opens editor to confirm the message); git revert a1b2c3d; Revert without opening the editor (uses default message); git revert --no-edit a1b2c3d; Stage the revert but don't commit yet (lets you edit the message manually); git revert. Read the command, understand what it changes, then run it only when the repository state matches the lesson.

      +

      Jamie: There are a lot of tools in play. How do we keep that from feeling like a contest?

      +

      Alex: Start with Learning Cards: Desktop Accessibility. There is something to understand, something to try, and something that proves the try worked.

      +

      Alex: The practical takeaway is this. Commit message fields, branch selector, and conflict resolution buttons are fully keyboard-accessible and announced. The diff panel has partial screen reader support -- for difficult diffs, switch to VS Code's Accessible Diff Viewer (F7 / Alt+F2). Use Shift+F10 on Windows to open context menus via keyboard when right-click actions are needed. File status icons (M, A, D) are small -- increase OS scaling or watch for the filename and status text that accompany them. The conflict resolution dialog uses labeled buttons ("Use mine", "Use theirs") that are easy to identify at any zoom level. If diff colors are indistinguishable at your contrast settings, open the same file in VS Code for richer theme support.

      Jamie: What decision is this helping them make?

      -

      Alex: This is where When to Use revert vs reset becomes real: GitHub Copilot can help: Not sure whether to use reset or revert? That matters in practice: Describe your situation to Copilot Chat: "I pushed a commit to main that broke the login page. The workshop is closer to rehearsal than lecture. You hear the move, try the move, and then check what changed.

      -

      Alex: Use the comparison to make a decision, not to recite a table. The main contrasts are: Commit is only local (not pushed) means git reset -- cleaner, no extra commit. Commit is on a shared branch (main, dev) means git revert -- preserves history, safe for others. Branch has protection rules (no force push) means git revert -- the only option.

      +

      Alex: The reason 16. GitHub Desktop vs VS Code vs Git CLI -- When to Use Each matters is that GitHub Desktop, VS Code, and the Git CLI all talk to the same Git repository. That gives the learner a simple foothold: you can switch between them freely -- use GitHub Desktop to stage and commit, then open the terminal for a git rebase -i. The interface gets friendlier when it stops being a wall of controls and starts being a set of named places.

      +

      Alex: Use the comparison to make a decision, not to recite a table. The main contrasts are: Situation means Best tool. You want a clean visual overview of changes before committing means GitHub Desktop. You want to stage individual lines or hunks means GitHub Desktop or VS Code.

      -

      Jamie: Let's pause on 5. Tags -- Marking Important Moments. What should a learner take away from it?

      -

      Alex: Keep the learner anchored in 5. Tags -- Marking Important Moments. What it is: A tag is a permanent label you attach to a specific commit -- usually to mark a release version like v1.0.0. This is the part to say slowly: Unlike a branch (which moves as you commit), a tag always points to the exact same commit forever.

      -

      Alex: The practical takeaway is this. Releasing a new version of a project. Marking a stable checkpoint before starting a big refactor. Documenting when a major feature shipped.

      -

      Jamie: Before we leave VS Code (Command Palette), what is the practical point?

      -

      Alex: The reason VS Code (Command Palette) matters is that type the tag name (e.g., v1.2.0) and optionally a message.

      -

      Alex: Treat examples as spoken recipes, not decorations. You may hear something like Ctrl+Shift+P → type "git tag" → select "Git: Create Tag". Read the command, understand what it changes, then run it only when the repository state matches the lesson.

      -

      Jamie: Before we leave GitHub CLI, what is the practical point?

      -

      Alex: Start with GitHub CLI. There is something to understand, something to try, and something that proves the try worked.

      -

      Alex: Treat examples as spoken recipes, not decorations. You may hear something like Create a tag and push it to GitHub in one step (using the API); gh release create v1.2.0 --title "Version 1.2.0" --notes "Bug fixes and accessibility improvements"; This creates both a GitHub Release and the underlying tag. Read the command, understand what it changes, then run it only when the repository state matches the lesson.

      +

      Jamie: What should people carry with them after this?

      +

      Alex: Carry the map. Know what page or tool you are in, know which action you are taking, and know what confirmation should follow. If the confirmation is missing, pause. That pause is not wasted time; it is professional judgment.

      +

      Jamie: That is a better way to say it than just follow the steps.

      +

      Alex: Right. Steps matter, but understanding wins. That is episode 52. Next in the series is episode 53, where we keep building the same contributor muscles.

      +
      +
      -

      Jamie: Let's pause on Git CLI. What should a learner take away from it?

      -

      Alex: Treat examples as spoken recipes, not decorations. You may hear something like Create a lightweight tag at the current commit; git tag v1.2.0; Create an annotated tag (recommended for releases); git tag -a v1.2.0 -m "Release version 1.2.0 - bug fixes and accessibility improvements"; Tag a specific past commit; git tag -a v1.1.5 a1b2c3d. Read the command, understand what it changes, then run it only when the repository state matches the lesson.

      -

      Jamie: Let's pause on Pushing Tags to GitHub. What should a learner take away from it?

      -

      Alex: This is where Pushing Tags to GitHub becomes real: tags are not pushed automatically when you run git push.

      -

      Alex: Treat examples as spoken recipes, not decorations. You may hear something like Push a specific tag; git push origin v1.2.0; Push all local tags at once; git push origin --tags. Read the command, understand what it changes, then run it only when the repository state matches the lesson.

      -

      Jamie: Let's pause on Deleting a Tag. What should a learner take away from it?

      -

      Alex: Start with Deleting a Tag. There is something to understand, something to try, and something that proves the try worked.

      -

      Alex: Treat examples as spoken recipes, not decorations. You may hear something like Delete a local tag; git tag -d v1.2.0; Delete the tag on GitHub (remote); git push origin --delete v1.2.0. Read the command, understand what it changes, then run it only when the repository state matches the lesson.

      +

      75. Episode 53: GitHub CLI Reference

      +

      Using the GitHub CLI for issues, pull requests, authentication, and automation-friendly workflows.

      +

      Based on: Appendix I: GitHub CLI Reference

      +

      Audio and transcript are being regenerated for this episode.

      +
      +Read Transcript - Episode 53: GitHub CLI Reference + +

      Transcript

      +

      Alex: Welcome back to Git Going with GitHub. This is episode 53: GitHub CLI Reference. I am Alex, and today we are turning GitHub CLI Reference from a list of instructions into a working mental model.

      +

      Jamie: And I am Jamie. I will stop us whenever the instructions sound simple on paper but might feel different with a keyboard and screen reader.

      -

      Jamie: Let's pause on 6. Detached HEAD -- What It Is and How to Get Out. What should a learner take away from it?

      -

      Alex: The reason 6. Detached HEAD -- What It Is and How to Get Out matters is that what it is: Normally, you're working on a branch -- Git tracks your commits and moves the branch forward as you commit. That gives the learner a simple foothold: a "detached HEAD" happens when you check out a specific commit SHA (or a tag) directly instead of a branch.

      -

      Alex: Treat examples as spoken recipes, not decorations. You may hear something like git checkout a1b2c3d Check out a specific commit; git checkout v1.0.0 Check out a tag. Read the command, understand what it changes, then run it only when the repository state matches the lesson.

      -

      Jamie: Let's pause on If you just want to go back to your branch. What should a learner take away from it?

      -

      Alex: Start with If you just want to go back to your branch. There is something to understand, something to try, and something that proves the try worked.

      -

      Alex: Treat examples as spoken recipes, not decorations. You may hear something like git checkout main; or whatever branch you were on; git switch main. Read the command, understand what it changes, then run it only when the repository state matches the lesson.

      -

      Jamie: Let's pause on If you made commits in detached HEAD and want to keep them. What should a learner take away from it?

      -

      Alex: Start with If you made commits in detached HEAD and want to keep them. There is something to understand, something to try, and something that proves the try worked.

      -

      Alex: Treat examples as spoken recipes, not decorations. You may hear something like Create a new branch at the current (detached) position to save your work; git checkout -b my-experiment; Now you're on a real branch and those commits are safe. Read the command, understand what it changes, then run it only when the repository state matches the lesson.

      +

      Alex: Using the GitHub CLI for issues, pull requests, authentication, and automation-friendly workflows. That is the surface description. Underneath it, we are building judgment: where to focus, what to ignore, and how to verify the result.

      +

      Jamie: So we are not using the audio as a shortcut around learning. We are using it to make the learning easier to enter.

      +

      Alex: Yes. A good audio lesson gives someone enough context to try the work with confidence, even before they open the written material.

      -

      Alex: Keep the teaching thread moving. This is where VS Code becomes real: VS Code shows the current branch name in the bottom-left status bar. That matters in practice: If you're in detached HEAD, it shows something like (HEAD detached at a1b2c3d) instead of a branch name.

      -

      Jamie: Let's pause on 7. Force Pushing Safely. What should a learner take away from it?

      -

      Alex: Keep the learner anchored in 7. Force Pushing Safely. What it is: After you rebase or amend commits that have already been pushed, the remote branch has a different history than your local branch. This is the part to say slowly: A regular git push will fail because Git sees them as diverged.

      -

      Alex: Keep the teaching thread moving. The reason --force-with-lease vs --force matters is that always use --force-with-lease instead of --force. The interface gets friendlier when it stops being a wall of controls and starts being a set of named places.

      +

      Jamie: Okay, set the room for us. What are we walking into?

      +

      Alex: Start with Your Terminal, Supercharged for GitHub: Who this is for: You want to manage GitHub -- issues, pull requests, repos, releases -- from your terminal without opening a browser. The next useful detail is this: The GitHub CLI (gh) gives you full access to GitHub from the command line, with clean plain-text output that works beautifully with screen readers.

      +

      Alex: The next layer is this. Here is the plain-English version of Windows. Or download the installer from cli.github.com. It is like learning a transit route. The names of the stops matter because they tell you whether you are still going the right direction.

      +

      Jamie: What is the safe way to learn from that example?

      +

      Alex: Start with Verify installation. There is something to understand, something to try, and something that proves the try worked.

      +

      Alex: Treat examples as spoken recipes, not decorations. You may hear something like gh --version. Read the command, understand what it changes, then run it only when the repository state matches the lesson.

      -

      Jamie: Let's pause on When You'd Use It. What should a learner take away from it?

      -

      Alex: Start with When You'd Use It. There is something to understand, something to try, and something that proves the try worked.

      -

      Alex: The practical takeaway is this. You rebased a feature branch to squash commits before a PR review. You amended the last commit with git commit --amend after already pushing. A reviewer asked you to rebase onto main and you've now done.

      -

      Jamie: If someone only remembers one thing from VS Code, what should it be?

      -

      Alex: Here is the plain-English version of VS Code. VS Code doesn't have a "force push" button in the UI -- this is intentional to prevent accidents.

      -

      Alex: Treat examples as spoken recipes, not decorations. You may hear something like Ctrl+Backtick → then type the command below. Read the command, understand what it changes, then run it only when the repository state matches the lesson.

      -

      Jamie: What is the teaching move inside GitHub CLI?

      -

      Alex: Treat examples as spoken recipes, not decorations. You may hear something like Force push your current branch; gh repo sync This is for syncing FROM remote, not for force pushing; For force pushing, use git directly:; git push --force-with-lease origin your-branch-name. Read the command, understand what it changes, then run it only when the repository state matches the lesson.

      +

      Jamie: What should happen before anyone copies and runs it?

      +

      Alex: Keep the learner anchored in Authenticating. After signing in, return to the terminal. This is the part to say slowly: gh auth login is an interactive prompt -- navigate with Arrow keys, confirm with Enter.

      +

      Alex: For a learner, the useful signals are these. Where do you use GitHub? → GitHub.com (or Enterprise). Preferred protocol? → HTTPS (or SSH). Authenticate with browser? → Yes -- your browser opens for OAuth sign-in.

      +

      Alex: Treat examples as spoken recipes, not decorations. You may hear something like gh auth login. Check your auth status at any time; gh auth status; Log out; gh auth logout; Refresh credentials / add new scopes; gh auth refresh. Read the command, understand what it changes, then run it only when the repository state matches the lesson.

      +

      Jamie: What does someone need before they touch the keyboard?

      +

      Alex: Start with Learning Cards: Getting Started with gh. There is something to understand, something to try, and something that proves the try worked.

      +

      Alex: The parts worth keeping in working memory are these. gh auth login uses plain-text arrow-key prompts -- every option is announced as you arrow through the list. After authentication, gh auth status confirms your login in a single readable line -- no browser needed. All gh output is plain text with no hidden elements, making it one of the most screen-reader-friendly GitHub interfaces. Increase your terminal font size before running gh commands -- all output scales with your terminal settings. Use a high-contrast terminal theme (light text on dark background, or vice versa) for comfortable reading of command output. gh output is plain text with no color-dependent meaning -- colors are supplementary labels, not the only indicator.

      +

      Alex: The useful habit is simple: orient first, act second, verify third. That pause before acting is part of the work.

      +

      Jamie: How do you keep commands from becoming magic words?

      +

      Alex: Start with 2. Repos -- Clone, Fork, Create, View. There is something to understand, something to try, and something that proves the try worked.

      +

      Alex: Treat examples as spoken recipes, not decorations. You may hear something like Clone a repository (automatically sets up the remote); gh repo clone owner/repo-name; Fork a repo and clone your fork in one step; gh repo fork owner/repo-name --clone; Fork without cloning (creates the fork on GitHub only); gh repo fork owner/repo-name. Read the command, understand what it changes, then run it only when the repository state matches the lesson.

      -

      Jamie: Let's pause on Git CLI. What should a learner take away from it?

      -

      Alex: Treat examples as spoken recipes, not decorations. You may hear something like Safe force push -- fails if someone else pushed since your last fetch; git push --force-with-lease origin feature/my-branch; Check what will happen before pushing; git push --force-with-lease --dry-run origin feature/my-branch; Unconditional force push (avoid. Read the command, understand what it changes, then run it only when the repository state matches the lesson.

      -

      Jamie: Let's pause on The Typical Rebase + Force Push Workflow. What should a learner take away from it?

      -

      Alex: Start with The Typical Rebase + Force Push Workflow. There is something to understand, something to try, and something that proves the try worked.

      -

      Alex: Treat examples as spoken recipes, not decorations. You may hear something like You're on your feature branch -- rebase onto main to get latest changes; git fetch origin; git rebase origin/main; 2. Resolve any conflicts, then continue; git rebase --continue; 3. Force push your rebased branch (origin already has the old version); git push. Read the command, understand what it changes, then run it only when the repository state matches the lesson.

      -

      Alex: Keep the teaching thread moving. Start with 8. git bisect -- Finding the Commit That Broke Things: What it is: git bisect performs a binary search through your commit history to find exactly which commit introduced a bug. The next useful detail is this: Instead of checking 100 commits one by one, Git cuts the search in half each time -- usually finding the culprit in 7-10 steps.

      -

      Alex: The practical takeaway is this. "This was working last week, now it's broken -- what changed?". You need to find the exact commit so you can revert or fix it. A test that used to pass now fails and you don't know why.

      +

      Jamie: What should they understand before typing anything?

      +

      Alex: Start with Creating issues. There is something to understand, something to try, and something that proves the try worked.

      +

      Alex: Treat examples as spoken recipes, not decorations. You may hear something like Create an issue interactively (opens a prompt for title, body, labels, etc.); gh issue create; Create with all details inline; gh issue create ; --title "Screen reader can't navigate the settings menu" ; --body "When using NVDA with Firefox, the Settings. Read the command, understand what it changes, then run it only when the repository state matches the lesson.

      +

      Alex: A solid issue habit is to read the title, the body, and the timeline before acting. You are listening for the requested action, the missing evidence, and the person who needs a response.

      +

      Jamie: Let's pause on Listing and filtering issues. What should a learner take away from it?

      +

      Alex: Start with Listing and filtering issues. There is something to understand, something to try, and something that proves the try worked.

      +

      Alex: Treat examples as spoken recipes, not decorations. You may hear something like List open issues (current repo); gh issue list; List issues with filters; gh issue list --label "accessibility"; gh issue list --label "good first issue"; gh issue list --assignee "@me"; gh issue list --state closed; gh issue list --limit 50; Search issues by. Read the command, understand what it changes, then run it only when the repository state matches the lesson.

      +

      Jamie: Let's pause on Viewing issues. What should a learner take away from it?

      +

      Alex: Keep the learner anchored in Viewing issues. gh issue view 42 outputs clean plain text -- title, metadata, and body all formatted without noise. This is the part to say slowly: Much faster than navigating a browser page with a screen reader.

      +

      Alex: Treat examples as spoken recipes, not decorations. You may hear something like View an issue (renders Markdown as plain text in the terminal); gh issue view 42; Open the issue in your browser; gh issue view 42 --web; View comments on an issue; gh issue view 42 --comments. Read the command, understand what it changes, then run it only when the repository state matches the lesson.

      -

      Jamie: Let's pause on Starting a Bisect Session. What should a learner take away from it?

      -

      Alex: Here is the plain-English version of Starting a Bisect Session. Git now checks out a commit in the middle of your history. Put another way, test your code -- does the bug exist here?

      -

      Alex: Treat examples as spoken recipes, not decorations. You may hear something like Start bisect mode; git bisect start; 2. Mark the current commit as bad (broken); git bisect bad; 3. Mark a commit you know was good (working); Use a tag, SHA, or branch name from before the problem started; git bisect good v1.0.0; or; git bisect good a1b2c3d. If the bug IS present at this commit; git bisect bad; If the bug is NOT present at this commit; git bisect good. Read the command, understand what it changes, then run it only when the repository state matches the lesson.

      -

      Jamie: Let's pause on Finishing. What should a learner take away from it?

      -

      Alex: Start with Finishing. There is something to understand, something to try, and something that proves the try worked.

      -

      Alex: Treat examples as spoken recipes, not decorations. You may hear something like End the bisect session and return to your original branch; git bisect reset. Read the command, understand what it changes, then run it only when the repository state matches the lesson.

      -

      Jamie: Let's pause on Automating Bisect with a Test Script. What should a learner take away from it?

      -

      Alex: Keep the learner anchored in Automating Bisect with a Test Script. If you have a test command that exits with code 0 on success and non-zero on failure, Git can run bisect automatically. This is the part to say slowly: Bisect output is plain text -- each step tells you exactly where it checked out and how many steps remain.

      -

      Alex: Treat examples as spoken recipes, not decorations. You may hear something like git bisect start; git bisect bad HEAD; git bisect good v1.0.0; Run automatically -- git runs your test script at each step; git bisect run npm test; or; git bisect run python -m pytest tests/test auth.py. Read the command, understand what it changes, then run it only when the repository state matches the lesson.

      +

      Jamie: Let's pause on Commenting and updating. What should a learner take away from it?

      +

      Alex: Start with Commenting and updating. There is something to understand, something to try, and something that proves the try worked.

      +

      Alex: Treat examples as spoken recipes, not decorations. You may hear something like Add a comment to an issue; gh issue comment 42 --body "I can reproduce this on Windows 11 with NVDA 2024.1."; Comment from a file; gh issue comment 42 --body-file./my-comment.md; Edit an issue (title, body, labels, assignees); gh issue edit 42 --title "Updated. Read the command, understand what it changes, then run it only when the repository state matches the lesson.

      +

      Jamie: Let's pause on Pinning and locking. What should a learner take away from it?

      +

      Alex: Start with Pinning and locking. There is something to understand, something to try, and something that proves the try worked.

      +

      Alex: Treat examples as spoken recipes, not decorations. You may hear something like Pin an issue (shows at top of the Issues tab); gh issue pin 42; Lock an issue (prevents new comments); gh issue lock 42 --reason "resolved". Read the command, understand what it changes, then run it only when the repository state matches the lesson.

      +

      Jamie: Let's pause on Creating a PR. What should a learner take away from it?

      +

      Alex: Start with Creating a PR. There is something to understand, something to try, and something that proves the try worked.

      +

      Alex: Treat examples as spoken recipes, not decorations. You may hear something like Create a PR interactively (prompts for title, body, base branch, etc.); gh pr create; Create with all details inline; gh pr create ; --title "Add keyboard navigation to settings menu" ; --body "Closes 42. Adds Tab/arrow key support to the settings dropdown.". Read the command, understand what it changes, then run it only when the repository state matches the lesson.

      +

      Alex: A solid pull request habit is to separate three questions: what changed, why it changed, and what still needs review. That keeps the conversation useful instead of noisy.

      -

      Alex: Keep the teaching thread moving. The reason 9. git clean -- Clearing Out Untracked Files matters is that what it is: git clean removes untracked files and directories from your working directory -- files that Git doesn't know about yet (not staged, not committed, not in.gitignore). That gives the learner a simple foothold: this is useful when you have build artifacts, generated files, or experimental files cluttering your project.

      -

      Alex: The practical takeaway is this. After a build that left temporary files everywhere. You want a completely fresh state matching the last commit. Clearing out generated files before running a clean build.

      -

      Jamie: Let's pause on Always Dry-Run First. What should a learner take away from it?

      -

      Alex: Start with Always Dry-Run First. There is something to understand, something to try, and something that proves the try worked.

      -

      Alex: Treat examples as spoken recipes, not decorations. You may hear something like See what WOULD be deleted without actually deleting anything; git clean -n; or equivalently; git clean --dry-run. Read the command, understand what it changes, then run it only when the repository state matches the lesson.

      -

      Jamie: Let's pause on VS Code. What should a learner take away from it?

      -

      Alex: Here is the plain-English version of VS Code. VS Code's Source Control panel shows untracked files in the "Changes" section. Put another way, for bulk removal, use the terminal (see Git CLI below). It is like learning a transit route. The names of the stops matter because they tell you whether you are still going the right direction.

      -

      Alex: First, open Source Control: Ctrl+Shift+G. Then, right-click an untracked file. After that, select "Discard Changes" -- this removes new untracked files. Treat it like a recipe: do not add the next ingredient until the previous one is actually in the bowl.

      +

      Jamie: Let's pause on Listing and viewing PRs. What should a learner take away from it?

      +

      Alex: Start with Listing and viewing PRs. There is something to understand, something to try, and something that proves the try worked.

      +

      Alex: Treat examples as spoken recipes, not decorations. You may hear something like List open PRs; gh pr list; List with filters; gh pr list --state closed; gh pr list --author "@me"; gh pr list --label "accessibility"; gh pr list --search "screen reader"; View a PR (title, description, status, checks); gh pr view 56; View the diff of a PR. Read the command, understand what it changes, then run it only when the repository state matches the lesson.

      +

      Jamie: Let's pause on Reviewing PRs. What should a learner take away from it?

      +

      Alex: Start with Reviewing PRs. There is something to understand, something to try, and something that proves the try worked.

      +

      Alex: Treat examples as spoken recipes, not decorations. You may hear something like Approve a PR; gh pr review 56 --approve; gh pr review 56 --approve --body "Tested with NVDA -- keyboard nav works perfectly. LGTM!"; Request changes; gh pr review 56 --request-changes --body "The focus indicator disappears on the last menu item."; Leave a. Read the command, understand what it changes, then run it only when the repository state matches the lesson.

      +

      Jamie: Let's pause on Checking CI status. What should a learner take away from it?

      +

      Alex: Start with Checking CI status. There is something to understand, something to try, and something that proves the try worked.

      +

      Alex: Treat examples as spoken recipes, not decorations. You may hear something like View all CI checks for a PR; gh pr checks 56; Watch checks update in real time (refreshes every 10s); gh pr checks 56 --watch; View checks for the current branch; gh pr checks. Read the command, understand what it changes, then run it only when the repository state matches the lesson.

      -

      Jamie: Let's pause on Git CLI. What should a learner take away from it?

      -

      Alex: Treat examples as spoken recipes, not decorations. You may hear something like Dry run -- see what would be removed; git clean -n; Remove untracked files (NOT directories); git clean -f; Remove untracked files AND directories; git clean -fd; Remove untracked files AND ignored files (be careful -- removes build artifacts AND things. Read the command, understand what it changes, then run it only when the repository state matches the lesson.

      -

      Alex: Keep the teaching thread moving. Keep the learner anchored in 10. Branch Protection -- Why Your Push or Merge May Be Blocked. What it is: Branch protection rules are settings a repository administrator applies to specific branches (usually main or release branches). This is the part to say slowly: They prevent direct pushes, require pull requests, require approvals before merging, and enforce status checks passing.

      -

      Jamie: Let's pause on The Correct Flow for Protected Branches. What should a learner take away from it?

      -

      Alex: Start with The Correct Flow for Protected Branches. There is something to understand, something to try, and something that proves the try worked.

      -

      Alex: Treat examples as spoken recipes, not decorations. You may hear something like Never push directly to main -- always work on a branch; git checkout -b feature/my-change; 2. Make your changes, commit them; git add.; git commit -m "Add screen reader support to navigation"; 3. Push your branch (not main); git push origin feature/my-change. Read the command, understand what it changes, then run it only when the repository state matches the lesson.

      +

      Jamie: Let's pause on Merging PRs. What should a learner take away from it?

      +

      Alex: Start with Merging PRs. There is something to understand, something to try, and something that proves the try worked.

      +

      Alex: Treat examples as spoken recipes, not decorations. You may hear something like Merge a PR (interactive -- prompts for merge strategy); gh pr merge 56; Merge with a specific strategy; gh pr merge 56 --merge Creates a merge commit; gh pr merge 56 --squash Squashes all commits into one; gh pr merge 56 --rebase Rebases commits onto base. Read the command, understand what it changes, then run it only when the repository state matches the lesson.

      +

      Jamie: Let's pause on Other PR operations. What should a learner take away from it?

      +

      Alex: Start with Other PR operations. There is something to understand, something to try, and something that proves the try worked.

      +

      Alex: Treat examples as spoken recipes, not decorations. You may hear something like Convert a draft PR to ready for review; gh pr ready 56; Mark a ready PR back as draft; gh pr ready 56 --undo; Update your PR branch with the latest from base (equivalent to "Update branch" button); gh pr update-branch 56; gh pr update-branch 56 --rebase; Close. Read the command, understand what it changes, then run it only when the repository state matches the lesson.

      +

      Jamie: Let's pause on 5. Releases -- Create, List, Upload. What should a learner take away from it?

      +

      Alex: This is where 5. Releases -- Create, List, Upload becomes real: see also: Appendix H: Releases, Tags, and Insights for the GitHub.com interface side of releases. The workshop is closer to rehearsal than lecture. You hear the move, try the move, and then check what changed.

      +

      Alex: Treat examples as spoken recipes, not decorations. You may hear something like Create a release interactively; gh release create v1.2.0; Create with all details; gh release create v1.2.0 ; --title "Version 1.2.0 -- Accessibility Improvements" ; --notes "- Fixed keyboard navigation in settings\n- Added ARIA labels to all form inputs". Read the command, understand what it changes, then run it only when the repository state matches the lesson.

      -

      Alex: Keep the teaching thread moving. Start with Updating a Branch That's Out of Date: When GitHub says your branch is out of date with main. Think of it like entering a new building: first you find the lobby, then the room, then the door you actually need.

      -

      Jamie: Let's pause on VS Code. What should a learner take away from it?

      -

      Alex: First, open Source Control → Ctrl+Shift+P. Then, type "merge" → select "Git: Merge Branch.". After that, choose origin/main from the list. Finally, resolve any conflicts, then push again. Treat it like a recipe: do not add the next ingredient until the previous one is actually in the bowl.

      -

      Jamie: Let's pause on Git CLI. What should a learner take away from it?

      -

      Alex: Treat examples as spoken recipes, not decorations. You may hear something like Option A: Merge main into your branch (creates a merge commit); git fetch origin; git merge origin/main; Option B: Rebase onto main (cleaner history, requires force push after); git fetch origin; git rebase origin/main; git push --force-with-lease origin. Read the command, understand what it changes, then run it only when the repository state matches the lesson.

      +

      Jamie: Let's pause on 6. Search -- Issues, PRs, Repos, Code. What should a learner take away from it?

      +

      Alex: Start with 6. Search -- Issues, PRs, Repos, Code. There is something to understand, something to try, and something that proves the try worked.

      +

      Alex: Treat examples as spoken recipes, not decorations. You may hear something like Search issues across all of GitHub; gh search issues "screen reader navigation" --label accessibility; gh search issues "keyboard shortcut" --repo owner/repo-name; gh search issues "help wanted" --language javascript --limit 20; Search pull requests; gh search. Read the command, understand what it changes, then run it only when the repository state matches the lesson.

      +

      Jamie: Let's pause on Labels. What should a learner take away from it?

      +

      Alex: Start with Labels. There is something to understand, something to try, and something that proves the try worked.

      +

      Alex: Treat examples as spoken recipes, not decorations. You may hear something like List labels in the current repo; gh label list; Create a label; gh label create "accessibility" --color "0075ca" --description "Accessibility improvements"; Clone labels from another repo (copies all their labels to yours); gh label clone owner/source-repo. Read the command, understand what it changes, then run it only when the repository state matches the lesson.

      +

      Alex: A solid project habit is to treat metadata as decision support. Labels, status, assignees, and notifications tell you what kind of attention the work needs.

      +

      Jamie: Let's pause on Milestones. What should a learner take away from it?

      +

      Alex: Start with Milestones. There is something to understand, something to try, and something that proves the try worked.

      +

      Alex: Treat examples as spoken recipes, not decorations. You may hear something like List milestones; gh api repos/{owner}/{repo}/milestones --jq '.[].title'; Create a milestone; gh api repos/{owner}/{repo}/milestones ; --method POST ; --field title="v2.0 Launch" ; --field description="All features for the v2.0 release" ; --field due. Read the command, understand what it changes, then run it only when the repository state matches the lesson.

      -

      Jamie: If someone only remembers one thing from GitHub CLI, what should it be?

      -

      Alex: Treat examples as spoken recipes, not decorations. You may hear something like Update your PR branch from the GitHub UI via CLI; gh pr update-branch --rebase; or; gh pr update-branch uses merge by default. Read the command, understand what it changes, then run it only when the repository state matches the lesson.

      -

      Jamie: Let's pause on GitHub CLI. What should a learner take away from it?

      -

      Alex: Treat examples as spoken recipes, not decorations. You may hear something like View branch protection rules for main; gh api repos/{owner}/{repo}/branches/main/protection --jq '{; required reviews.required pull request reviews.required approving review count,; require status checks.required status checks.contexts,; enforce. Read the command, understand what it changes, then run it only when the repository state matches the lesson.

      -

      Jamie: Let's pause on On GitHub.com. What should a learner take away from it?

      -

      Alex: Start with On GitHub.com: Navigate to Settings → Branches in the repository. The next useful detail is this: (You need admin access to see the full config; contributors can see the effect through blocked PRs and the merge box status.).

      +

      Alex: This is the part worth saying out loud. Here is the plain-English version of 8. Output Formatting -- JSON, jq, Templates. By default gh outputs human-readable text. Put another way, for scripting or custom display, you can get raw JSON and filter it. It is like learning a transit route. The names of the stops matter because they tell you whether you are still going the right direction.

      +

      Jamie: Let's pause on --json flag. What should a learner take away from it?

      +

      Alex: Start with --json flag. There is something to understand, something to try, and something that proves the try worked.

      +

      Alex: Treat examples as spoken recipes, not decorations. You may hear something like Get issue data as JSON; gh issue view 42 --json title,body,labels,state; Get PR data as JSON; gh pr view 56 --json title,number,state,mergeable,reviews; List issues as JSON; gh issue list --json number,title,labels,assignees. Read the command, understand what it changes, then run it only when the repository state matches the lesson.

      +

      Jamie: Let's pause on --jq flag (filter JSON inline). What should a learner take away from it?

      +

      Alex: Start with --jq flag (filter JSON inline). There is something to understand, something to try, and something that proves the try worked.

      +

      Alex: Treat examples as spoken recipes, not decorations. You may hear something like List just issue numbers and titles; gh issue list --json number,title --jq '.[] "(.number): (.title)"'; Get the names of all labels on an issue; gh issue view 42 --json labels --jq '.labels[].name'; Count open PRs; gh pr list --json number --jq 'length'. Read the command, understand what it changes, then run it only when the repository state matches the lesson.

      -

      Alex: Keep the teaching thread moving. Start with Learning Cards: Quick Reference Table. There is something to understand, something to try, and something that proves the try worked.

      -

      Alex: The practical takeaway is this. This table has four columns: Task, VS Code, Git CLI, and GitHub CLI -- column headers are announced on entry. Use Ctrl+Alt+Arrow keys to navigate cells; the Task column on the left identifies each row. Cells with a dash (--) mean that tool does not support the operation -- move right to try another column. At high zoom the table may scroll horizontally -- use Shift+scroll or arrow keys to see all four columns. The Task column is always the leftmost -- anchor your reading from there. Consider copying this table into a text file or spreadsheet for easier viewing at your preferred zoom.

      -

      Jamie: Let's pause on 11. Using GitHub Copilot for Git Operations. What should a learner take away from it?

      -

      Alex: This is where 11. Using GitHub Copilot for Git Operations becomes real: GitHub Copilot isn't just for writing code -- it's genuinely useful for Git operations, especially when you're doing something unfamiliar, hit a conflict, or need to understand what a command did. That matters in practice: Here's how to use it across the advanced operations in this appendix.

      -

      Alex: Keep the teaching thread moving. Keep the learner anchored in Resolving Merge Conflicts. When a cherry-pick, rebase, or branch merge stops due to a conflict, VS Code highlights the conflict regions. This is the part to say slowly: Place your cursor inside a conflict block and ask Copilot. A good GitHub workflow is like a well-run meeting: everyone knows the topic, the next action, and who has the floor.

      -

      Alex: The practical takeaway is this. "Resolve this merge conflict. Keep meaningful changes from both sides.". "Explain what each side of this conflict is trying to do.". "Which version of this change should I keep, and why?".

      +

      Jamie: Let's pause on --template flag (Go templates). What should a learner take away from it?

      +

      Alex: The reason --template flag (Go templates) matters is that --json with --jq produces clean, predictable output -- ideal for piping to a file or reading with a screen reader. That gives the learner a simple foothold: the default human-readable output is also clean, but JSON gives you precise control over what's announced.

      +

      Alex: Treat examples as spoken recipes, not decorations. You may hear something like Custom formatted output; gh issue list --template '{{range.}} {{.number}} {{.title}} ({{.state}}){{"\n"}}{{end}}'. Read the command, understand what it changes, then run it only when the repository state matches the lesson.

      +

      Alex: Now bring the learner back to the room. Start with Learning Cards: Output Formatting. There is something to understand, something to try, and something that proves the try worked.

      +

      Alex: On the ground, that means a few things. Use --json with --jq to extract exactly the fields you need -- this eliminates table formatting noise and reads as clean key-value pairs. Pipe long output to a file (gh issue list --json title issues.txt) and open it in VS Code for structured navigation with Alt+F2. Go templates (--template) let you define a single-line-per-item format that reads naturally with arrow keys. The default table output aligns columns with spaces -- increase terminal font size so columns stay readable. JSON output with --jq strips visual formatting and gives compact text that scales cleanly with any font size. Pipe output to VS Code (gh pr view 42 --json body --jq '.body' code -) to read it with your preferred editor theme and zoom.

      +

      Jamie: Let's pause on 9. Aliases -- Create Your Own Shortcuts. What should a learner take away from it?

      +

      Alex: Here is the plain-English version of 9. Aliases -- Create Your Own Shortcuts. Aliases let you create custom gh commands from long commands you run often.

      +

      Alex: Treat examples as spoken recipes, not decorations. You may hear something like Create an alias; gh alias set bugs 'issue list --label bug'; gh alias set my-prs 'pr list --author @me'; gh alias set review-ready 'pr list --label "ready for review"'; Use your alias; gh bugs; gh my-prs; gh review-ready; List all aliases; gh alias list. Read the command, understand what it changes, then run it only when the repository state matches the lesson.

      -

      Jamie: Let's pause on Writing Better Commit Messages. What should a learner take away from it?

      -

      Alex: The reason Writing Better Commit Messages matters is that Copilot is excellent at turning "WIP: stuff" into a clear, conventional commit message. That gives the learner a simple foothold: open Copilot Chat after staging your changes and try.

      -

      Alex: The practical takeaway is this. "Write a conventional commit message for these changes." (Copilot can see open files). "I changed the navigation component to add keyboard focus indicators. Write a commit message.". "Here are my last 5 WIP commit messages: [paste them]. Write one clean message that summarizes all of them.".

      -

      Alex: Keep the teaching thread moving. Start with Understanding Confusing Git Output: Git's error messages and status output can be cryptic. The next useful detail is this: Paste them directly into Copilot Chat.

      -

      Alex: The practical takeaway is this. "I got this git error message: [paste it]. What does it mean and how do I fix it?". "My git status output looks like this: [paste it]. What happened and what should I do next?". "I accidentally ran git reset --hard. What are my options for recovering my changes?".

      -

      Jamie: What stays the same when the tool changes?

      -

      Alex: Here is the plain-English version of Choosing the Right Command. When you're not sure which git command to reach for, describe what you want to do.

      -

      Alex: The practical takeaway is this. "I committed a fix on my feature branch but main also needs it urgently. What's the right git command to use?" → Copilot will suggest cherry-pick. "I have 6 messy commits on my PR branch before I open the PR. How do I clean them up?" → Interactive rebase with squash. "I pushed a commit that broke CI and I need to undo it without force-pushing." → git revert. "My PR branch hasn't been updated from main in two weeks. How do I bring it up to date?" → fetch + rebase or merge.

      +

      Jamie: Let's pause on Useful aliases to set up. What should a learner take away from it?

      +

      Alex: Start with Useful aliases to set up. There is something to understand, something to try, and something that proves the try worked.

      +

      Alex: Treat examples as spoken recipes, not decorations. You may hear something like Issues assigned to you; gh alias set mine 'issue list --assignee @me'; Your open PRs; gh alias set mypr 'pr list --author @me --state open'; Check CI on current branch's PR; gh alias set ci 'pr checks'; View current PR; gh alias set pr 'pr view'. Read the command, understand what it changes, then run it only when the repository state matches the lesson.

      +

      Jamie: Let's pause on 10. Extensions -- Adding New Commands. What should a learner take away from it?

      +

      Alex: Keep the learner anchored in 10. Extensions -- Adding New Commands. Extensions add new gh subcommands written by the community.

      +

      Alex: Treat examples as spoken recipes, not decorations. You may hear something like Browse available extensions; gh extension search; Install an extension; gh extension install owner/gh-extension-name; List installed extensions; gh extension list; Update all extensions; gh extension upgrade --all; Update a specific extension; gh extension. Read the command, understand what it changes, then run it only when the repository state matches the lesson.

      +

      Jamie: Let's pause on 11. Copilot in the CLI. What should a learner take away from it?

      +

      Alex: The reason 11. Copilot in the CLI matters is that install the Copilot extension once, then ask coding and git questions without leaving the terminal. That gives the learner a simple foothold: Copilot CLI shows the suggested command, explains what it does, and asks whether to run it - perfect for learning while doing. The interface gets friendlier when it stops being a wall of controls and starts being a set of named places.

      +

      Alex: Treat examples as spoken recipes, not decorations. You may hear something like Install (one time); gh extension install github/gh-copilot; Ask for a command suggestion; gh copilot suggest "squash my last 4 commits into one"; gh copilot suggest "find which commit introduced a bug in auth.js"; gh copilot suggest "create a pull request from. Read the command, understand what it changes, then run it only when the repository state matches the lesson.

      -

      Alex: Keep the teaching thread moving. This is where Debugging a Failing Bisect becomes real: when git bisect lands on a commit and you're not sure what to test. The workshop is closer to rehearsal than lecture. You hear the move, try the move, and then check what changed.

      -

      Alex: The practical takeaway is this. "I'm running git bisect to find a bug. Git just checked out commit a1b2c3d. Here's the diff: [paste git show a1b2c3d]. What changed in this commit and what should I test?".

      -

      Jamie: How should someone ask for help in a way that gets them unstuck faster?

      -

      Alex: Keep the learner anchored in Getting Help With Branch Protection Errors. Paste the full error message from a rejected push into Copilot.

      -

      Alex: The practical takeaway is this. "I got this error when pushing to my repository: [paste error]. What does it mean and what do I do?". "My PR can't merge because of a required status check. Here's the check output: [paste it]. What's wrong?".

      -

      Jamie: Let's pause on GitHub Copilot CLI -- Git Command Suggestions. What should a learner take away from it?

      -

      Alex: The reason GitHub Copilot CLI -- Git Command Suggestions matters is that if you have the GitHub CLI with Copilot extension installed, you can ask for git commands directly in the terminal. That gives the learner a simple foothold: Copilot CLI explains the command before running it and asks for confirmation -- great for learning while doing.

      -

      Alex: Treat examples as spoken recipes, not decorations. You may hear something like Ask Copilot to suggest a git command for what you want to do; gh copilot suggest "squash my last 4 commits into one"; gh copilot suggest "undo my last commit but keep the changes"; gh copilot suggest "find which commit broke the login tests". Read the command, understand what it changes, then run it only when the repository state matches the lesson.

      +

      Jamie: Let's pause on Auto model selection. What should a learner take away from it?

      +

      Alex: Start with Auto model selection: As of early 2026, gh copilot uses auto model selection by default - it picks the best available model for your request without you needing to specify one. The next useful detail is this: You can still request a specific model using the --model flag if you prefer.

      +

      Alex: Treat examples as spoken recipes, not decorations. You may hear something like Let Copilot choose automatically (default); gh copilot suggest "create a pull request from my current branch"; Request a specific model; gh copilot suggest --model gpt-5 "create a pull request from my current branch". Read the command, understand what it changes, then run it only when the repository state matches the lesson.

      +

      Jamie: Let's pause on Telemetry opt-out. What should a learner take away from it?

      +

      Alex: Here is the plain-English version of Telemetry opt-out. As of gh CLI 2.70 (April 2026), gh collects anonymized usage telemetry by default to improve the product. Put another way, or set the environment variable GH NO UPDATE NOTIFIER=1 to suppress update notifications only.

      +

      Alex: Treat examples as spoken recipes, not decorations. You may hear something like gh config set telemetry disabled. Read the command, understand what it changes, then run it only when the repository state matches the lesson.

      +

      Jamie: What is the one idea that makes the next few steps less mysterious?

      +

      Alex: This is where 12. Screen Reader Tips becomes real: the GitHub CLI is one of the most screen-reader-friendly ways to use GitHub. That matters in practice: Here's why and how to get the most out of it.

      +

      Alex: A solid navigation habit is to prove where you are before activating controls. Headings, landmarks, and the address bar are not trivia; they are your map.

      -

      Jamie: What is the final checkpoint?

      -

      Alex: You should be able to point to the evidence, explain the action, and describe what you would do next if this were a real open source project. If you can teach the move back, you have learned it.

      -

      Jamie: And if they get stuck?

      -

      Alex: Read the latest message, not the loudest worry. Check the issue, the branch, the pull request, the status check, or the bot comment. Then ask for help with those facts in hand. That is how professionals collaborate.

      +

      Alex: Hold that next to this. Start with Why the CLI works so well. There is something to understand, something to try, and something that proves the try worked.

      +

      Alex: Here is what that changes in practice. Plain text output -- no visual noise, no unlabelled buttons, no hidden dialogs. Predictable structure -- every command produces consistent output you can navigate with arrow keys. No focus traps -- you control when you read output; nothing streams unexpectedly. Keyboard-first by design -- everything is a command you type.

      +

      Jamie: Let's pause on Tips by task. What should a learner take away from it?

      +

      Alex: The reason Tips by task matters is that creating content without a browser.

      +

      Alex: Treat examples as spoken recipes, not decorations. You may hear something like Pipe output to less for page-by-page reading; gh issue view 42 less; Save to a file and open in your editor; gh pr view 56 pr-56.md; code pr-56.md. Limit results to a manageable number; gh issue list --limit 10; Combine with search to narrow down; gh issue list --search "keyboard" --limit 5. Read the command, understand what it changes, then run it only when the repository state matches the lesson.

      +

      Alex: That connects to another useful point. Start with NVDA / JAWS (Windows). There is something to understand, something to try, and something that proves the try worked.

      +

      Alex: The room should hear these as checkpoints. Run gh commands in Windows Terminal or the VS Code integrated terminal -- both work well with NVDA/JAWS. Use Insert+Down (NVDA) or Insert+F12 (JAWS) to read the current line of terminal output. For long output, use less and navigate with Space (next page) and b (back).

      +
      +

      Jamie: If I am listening before the workshop starts, what should settle in my mind first?

      +

      Alex: Start with VoiceOver (macOS). There is something to understand, something to try, and something that proves the try worked.

      +

      Alex: These are the details that keep the idea from floating away. Run gh in Terminal.app or VS Code integrated terminal. VO+Right moves through terminal output character by character; VO+Down line by line. Use Ctrl+C to stop a running command if output is too long.

      +

      Alex: Here is the practical turn. Start with Learning Cards: Screen Reader CLI Workflow. There is something to understand, something to try, and something that proves the try worked.

      +

      Alex: That becomes easier when you listen for these cues. gh is keyboard-first by design -- no focus traps, no streaming, no unlabelled buttons; everything is typed and read as plain text. Use Insert+Down (NVDA) or Insert+F12 (JAWS) to read the current line, and arrow keys to move through multi-line output. Write issue and PR bodies in a text file first, then use --body-file./issue.md to submit -- much easier than composing inline. Terminal output from gh has no icons or images -- all information is conveyed as text that scales with your terminal font. Use --limit 10 on list commands to keep output short enough to scan comfortably without scrolling. Run gh in the VS Code integrated terminal to benefit from VS Code's zoom, themes, and Accessible View (Alt+F2).

      +

      Jamie: Where do you want a learner to place their attention here?

      +

      Alex: Keep the learner anchored in Copilot. Next: Appendix J: Codespaces Back: Appendix H: GitHub Desktop Teaching chapter: Chapter 01: Choose Your Tools.

      +
      +

      Jamie: What should people carry with them after this?

      +

      Alex: Carry the map. Know what page or tool you are in, know which action you are taking, and know what confirmation should follow. If the confirmation is missing, pause. That pause is not wasted time; it is professional judgment.

      +

      Jamie: That is a better way to say it than just follow the steps.

      +

      Alex: Right. Steps matter, but understanding wins. That is episode 53. Next in the series is the next learning block, where we keep building the same contributor muscles.

      Production

      -

      These episodes are generated using Piper local neural text-to-speech with ONNX models. Each episode is produced from the workshop chapter content using episode-specific scripts that ensure concept coverage, accessible language, and screen reader-friendly descriptions.

      +

      These episodes are generated with local neural text-to-speech models. Each episode is produced from the workshop chapter content using episode-specific scripts that ensure concept coverage, accessible language, and screen reader-friendly descriptions.

      Source bundles and production documentation are in the podcasts/ directory.

      diff --git a/html/admin/REGISTER.html b/html/admin/REGISTER.html index 4e1dee2e..b6887551 100644 --- a/html/admin/REGISTER.html +++ b/html/admin/REGISTER.html @@ -59,7 +59,7 @@

      Student Opt-In

      -

      Back to Home | Discussion Forum | Pre-Workshop Setup Guide

      +

      Back to Home | Support Hub | Pre-Workshop Setup Guide

      Join the next GIT Going with GitHub cohort

      This page is a fast, self-serve opt-in workflow. Students can opt in directly from GitHub Pages with no instructor handoff required.

      @@ -114,13 +114,13 @@

      After you opt in

      1. Check your issue for the automated confirmation or waitlist comment.
      2. Complete the Pre-Workshop Setup Guide.
        3. -
      3. Introduce yourself in the Discussion Forum.
        4. +
      4. Introduce yourself in Support Hub Discussions.

      Need help?

      Questions or access issues are welcome.

      A Community Access initiative.

      diff --git a/html/admin/REGISTRATION-ADMIN.html b/html/admin/REGISTRATION-ADMIN.html index d2369ff7..1e7650a3 100644 --- a/html/admin/REGISTRATION-ADMIN.html +++ b/html/admin/REGISTRATION-ADMIN.html @@ -155,6 +155,10 @@

      Regenerating the CSV On Demand

      To rebuild the CSV from all current registration issues (e.g., right before the workshop):

      gh workflow run registration.yml -R community-access/git-going-with-github

      This triggers the workflow_dispatch event, which rebuilds the CSV from all registration issues and uploads a fresh artifact.

      +

      Resetting Support Environment (From Top)

      +

      If you need to rebuild the support environment from scratch, run:

      +
      scripts/classroom/Reset-SupportHubEnvironment.ps1
      +

      This restores support hub baseline settings, labels, and automation so registration help links and post-workshop support routing remain reliable.

      Registration Scenarios

      The workflow handles three scenarios when someone submits a registration issue:

      1. New Registration (Spots Available)

      diff --git a/html/admin/REGISTRATION-QUICKSTART.html b/html/admin/REGISTRATION-QUICKSTART.html index f81d5b61..4b7166ed 100644 --- a/html/admin/REGISTRATION-QUICKSTART.html +++ b/html/admin/REGISTRATION-QUICKSTART.html @@ -141,6 +141,9 @@

      Rollback (Immediate)

    • Clear repository variable CLASSROOM_ORG

      • The registration workflow will continue standard confirmation, capacity checks, and CSV export.

      +

      Full Support Reset (When Needed)

      +

      If support environment drift is detected, rebuild support hub baseline:

      +
      scripts/classroom/Reset-SupportHubEnvironment.ps1

      Day-Of Operations

      1. Keep REGISTRATION-ADMIN.md open.
        2. diff --git a/html/admin/SUPPORT_HUB_OPERATIONS.html b/html/admin/SUPPORT_HUB_OPERATIONS.html new file mode 100644 index 00000000..ef3b8054 --- /dev/null +++ b/html/admin/SUPPORT_HUB_OPERATIONS.html @@ -0,0 +1,171 @@ + + + + + + + Support Hub Operations - GIT Going with GitHub + + + + + + + + +
        +

        Support Hub Operations

        +

        This guide defines how we run the open, post-workshop support repository for GIT Going with GitHub.

        +

        Canonical Support Repository

        +
          +
        • Repository name: Community-Access/support
          • +
        • Repository URL: https://github.com/Community-Access/support
          • +
        • Repository visibility: Public
          • +
        • Primary purpose: post-workshop support, async Q&A, troubleshooting, and alumni collaboration
          • +
        +

        This repository does not replace curriculum source repositories. It routes support traffic away from curriculum maintenance and keeps student support visible and searchable.

        +

        Student Onboarding Model (Rich Path)

        +

        Use this onboarding flow for every new cohort:

        +
          +
        1. Share Support Hub URL in registration confirmation and Day 2 close-out.
          2. +
        2. Ask students to read pinned Start Here content in Discussions.
          3. +
        3. Ask students to post one introduction in Discussions and one support request using templates if blocked.
          4. +
        4. Point students to labels and categories so they can self-route requests.
          5. +
        +

        Onboarding success criteria:

        +
          +
        • Students can explain the difference between support issues and discussions.
          • +
        • Students can open a support issue with reproducible steps.
          • +
        • Students can find and follow a resolved discussion thread.
          • +
        +

        What Belongs In Support Hub

        +

        Use Support Hub for:

        +
          +
        • Student setup and access questions
          • +
        • Post-workshop troubleshooting questions
          • +
        • Accessibility workflow questions
          • +
        • Alumni sharing and follow-up help
          • +
        • Requests for clarification in workshop docs
          • +
        +

        Do not use Support Hub for:

        +
          +
        • Direct edits to workshop curriculum content
          • +
        • Template workflow code changes
          • +
        • Security disclosures
          • +
        +

        Routing:

        + + +

        Discussions categories

        +
          +
        • Q&A
          • +
        • Troubleshooting
          • +
        • Success Stories
          • +
        • Announcements
          • +
        • Office Hours
          • +
        +

        Labels

        +
          +
        • needs-triage
          • +
        • setup
          • +
        • classroom
          • +
        • accessibility
          • +
        • copilot
          • +
        • resolved
          • +
        • escalated
          • +
        +

        Response Standards

        +
          +
        • First response target: 24 to 48 hours
          • +
        • Triage cadence during active cohorts: daily
          • +
        • Triage cadence off-cycle: 3 times per week
          • +
        +

        Moderator Playbook

        +
          +
        1. Acknowledge the question and restate the goal.
          2. +
        2. Provide one clear next action.
          3. +
        3. Link to the exact workshop doc section when relevant.
          4. +
        4. Ask for diagnostics only if needed.
          5. +
        5. Mark resolved when the user confirms or the path is complete.
          6. +
        +

        Privacy And Safety Rules

        +
          +
        • Do not request personal data in public issues/discussions.
          • +
        • Never ask users to post tokens, secrets, or private repository URLs publicly.
          • +
        • For sensitive account problems, move to private facilitator contact.
          • +
        +

        Integration Checklist

        +
          +
        • REGISTER.md and registration workflow comments point to Support Hub.
          • +
        • Facilitator guides reference Support Hub as the alumni channel.
          • +
        • docs/21-next-steps.md points learners to Support Hub.
          • +
        • Go-live checklist includes Support Hub readiness.
          • +
        • Podcast scripts/transcripts reference Support Hub as the default help path.
          • +
        +

        Reset And Rebuild (From Scratch)

        +

        If the support environment drifts or needs a hard reset, run:

        +
        scripts/classroom/Reset-SupportHubEnvironment.ps1
        +

        This script re-applies repository baseline setup:

        +
          +
        • Repository existence and visibility
          • +
        • Issues and Discussions enabled
          • +
        • Support label taxonomy
          • +
        • Baseline support files and bot workflows
          • +
        + +
        + + + + diff --git a/html/admin/index.html b/html/admin/index.html index 46a50f7f..09644adf 100644 --- a/html/admin/index.html +++ b/html/admin/index.html @@ -70,11 +70,13 @@

        Quick Navigation

      2. FACILITATOR_OPERATIONS.md - Hour-by-hour procedures during workshop
      3. FACILITATOR_CLASSROOM_TROUBLESHOOTING.md - Problem-solving guide
      4. ../GO-LIVE-QA-GUIDE.md - Final release-readiness guide and end-to-end test checklist
        5. +
      5. LEARNING-ROOM-E2E-QA-RUNBOOK.md - Single step-by-step QA runbook from registration to full student completion (podcast excluded)

        6. Supporting Guides

        Student And Enrollment Management

        @@ -100,6 +102,8 @@

        Setup And Deployment

      6. ACCESSIBILITY_TESTING.md - Testing workshop for accessibility
      7. VALIDATION_AUDIT.md - Validating everything works
      8. classroom/README.md - Copy-paste classroom setup pack (assignments, autograding, seeding)
        9. +
      9. LEARNING-ROOM-E2E-QA-RUNBOOK.md - Full registration-through-challenges QA execution path for one operator
        10. +
      10. qa-readiness/README.md - Local unit-test readiness evidence pack (non-podcast)
      11. ../GO-LIVE-QA-GUIDE.md - Complete pre-cohort QA gate for content, workflows, Classroom, podcasts, and human testing
        12. diff --git a/html/admin/qa-bundle/GO-LIVE-QA-GUIDE.html b/html/admin/qa-bundle/GO-LIVE-QA-GUIDE.html new file mode 100644 index 00000000..4e6010d2 --- /dev/null +++ b/html/admin/qa-bundle/GO-LIVE-QA-GUIDE.html @@ -0,0 +1,477 @@ + + + + + + + Git Going with GitHub Go-Live QA Guide - GIT Going with GitHub + + + + + + + + +
        +

        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).
          • +
        • Support Hub is provisioned and publicly accessible at Community-Access/support.
          • +
        • Registration confirmation and help pathways route support requests to Support Hub issues/discussions.
          • +
        • Registration issue form template and labels are configured (workshop-registration.yml, registration, duplicate, waitlist).
          • +
        • 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.

        +
      + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + +
      AreaSource document
      Classroom deploymentclassroom/README.md
      Classroom copy-paste setup packadmin/classroom/README.md
      End-to-end operator runbook (registration to completion, podcast excluded)admin/LEARNING-ROOM-E2E-QA-RUNBOOK.md
      Human challenge walkthroughclassroom/HUMAN_TEST_MATRIX.md
      Facilitator operationsadmin/FACILITATOR_OPERATIONS.md
      Facilitator guideadmin/FACILITATOR_GUIDE.md
      Support hub operationsadmin/SUPPORT_HUB_OPERATIONS.md
      Student challenge hubdocs/CHALLENGES.md
      Podcast pipelinepodcasts/README.md
      Podcast regeneration runbookpodcasts/REGENERATION.md
      Post-workshop cleanupclassroom/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.

      +
      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.

      + +

      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/<username> 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.
        • +
      • 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.
        • +
      • Use private individual repositories.
        • +
      • Enable feedback pull requests.
        • +
      • Add every Day 1 autograding test from 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:
        • +
      +
      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.
        • +
      • Use private individual repositories.
        • +
      • Enable feedback pull requests.
        • +
      • Add every Day 2 autograding test from 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:
        • +
      +
      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 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, admin/README.md, and 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.

      + + + + + + + + + + + + + + + + + + + + + + + + + + + + +
      SeverityMeaningRelease action
      BlockerPrevents assignment creation, repository creation, challenge progression, PR validation, accessibility use, or student safetyFix before release
      HighCauses confusing instructions, broken links in required paths, wrong challenge evidence, or broken generated contentFix before release unless release owner approves exception
      MediumCauses friction but has a clear workaroundFix before or immediately after release
      LowTypo, minor wording, or non-blocking polishFix when practical
      +

      QA Evidence Log Template

      +

      Copy this template into a release issue or testing document.

      +
      ## 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.
        • +
      + +
      + + + + diff --git a/html/admin/qa-bundle/REGISTER.html b/html/admin/qa-bundle/REGISTER.html new file mode 100644 index 00000000..4ee4d706 --- /dev/null +++ b/html/admin/qa-bundle/REGISTER.html @@ -0,0 +1,120 @@ + + + + + + + Student Opt-In - GIT Going with GitHub + + + + + + + + +
      +

      Student Opt-In

      +

      Back to Home | Support Hub | Pre-Workshop Setup Guide

      +

      Join the next GIT Going with GitHub cohort

      +

      This page provides a fast, self-serve opt-in workflow for students.

      + + + + + + + + + + + + + + + + + + + + + + + +
      StatusOpen for student opt-in
      Current confirmed registrationsLoading...
      CostFree
      FormGitHub issue form with automated confirmation and waitlist handling
      +

      Quick opt-in workflow

      +
        +
      1. Sign in to your GitHub account.
        2. +
      2. Open the registration issue form.
        3. +
      3. Submit the form.
        4. +
      +
      +

      Start Student Opt-In Form

      +
      +

      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?

      + +

      A Community Access initiative.

      + +
      + + + + diff --git a/html/admin/qa-bundle/admin/LEARNING-ROOM-E2E-QA-RUNBOOK.html b/html/admin/qa-bundle/admin/LEARNING-ROOM-E2E-QA-RUNBOOK.html new file mode 100644 index 00000000..13c2ba9d --- /dev/null +++ b/html/admin/qa-bundle/admin/LEARNING-ROOM-E2E-QA-RUNBOOK.html @@ -0,0 +1,2234 @@ + + + + + + + Learning Room End-to-End QA Runbook (Registration to Student Completion) - GIT Going with GitHub + + + + + + + + +
      +

      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
      Support hub operationsSUPPORT_HUB_OPERATIONS.md
      +

      Required Accounts, Access, and Tools

      +

      Complete this section before Phase 1.

      +
        +
      • Facilitator admin account (accesswatch) with Owner access to both Community-Access and Community-Access-Classroom.
        • +
      • Dedicated non-admin test student account for acceptance and full challenge walkthrough. This must be a separate GitHub account that is not an owner or member of either organization.
        • +
      • Access to classroom.github.com while signed in as accesswatch.
        • +
      • Access to repository settings for Community-Access/git-going-with-github (secrets and variables).
        • +
      • Local clone of this repository with PowerShell available.
        • +
      • GitHub CLI (gh) installed and authenticated as accesswatch for optional verification commands.
        • +
      +

      Critical Precondition Gates (No-Go if any fail)

      +

      Complete all items below before any cohort launch actions.

      +
        +
      • Facilitator account accesswatch can access both organizations:
          +
        • Community-Access (the workshop and code repository organization)
          • +
        • Community-Access-Classroom (the GitHub Classroom organization where student repos are created)
          • +
        +
        • +
      • accesswatch has a verified email address on its GitHub account and can create and edit Classroom assignments at classroom.github.com.
        • +
      • Dedicated non-admin test student account exists and can accept invites.
        • +
      • gh auth status succeeds for accesswatch in local terminal.
        • +
      • Template repository exists and is set as template repo:
          +
        • Community-Access/learning-room-template
          • +
        +
        • +
      • Template repository Actions settings allow required automation behavior:
          +
        • Actions enabled
          • +
        • GITHUB_TOKEN default workflow permissions include write where required
          • +
        • Allow GitHub Actions to create and approve pull requests enabled
          • +
        +
        • +
      • Registration automation settings are correct when using registration-to-classroom handoff:
          +
        • Secret CLASSROOM_ORG_ADMIN_TOKEN is set in Community-Access/git-going-with-github
          • +
        • Variables CLASSROOM_ORG, CLASSROOM_DAY1_ASSIGNMENT_URL, CLASSROOM_DAY2_ASSIGNMENT_URL are set in Community-Access/git-going-with-github
          • +
        +
        • +
      • Registration entry configuration exists and is valid:
          +
        • Issue form template workshop-registration.yml exists
          • +
        • Required labels exist: registration, duplicate, waitlist
          • +
        +
        • +
      • Support hub is ready for student onboarding:
          +
        • Community-Access/support is public and reachable
          • +
        • Issues and Discussions are enabled
          • +
        • Support labels and templates are present
          • +
        +
        • +
      • While signed in as accesswatch, opening classroom.github.com shows the Community-Access-Classroom classroom organization.
        • +
      +

      If any precondition fails, stop and resolve before proceeding.

      +

      Exact Setup Steps for Keys, Permissions, Settings, and Template Currency

      +

      Use this section when you need literal setup steps (not only validation checks).

      +

      A. Confirm facilitator account and organization access

      +

      You are performing all steps below as accesswatch. If you are currently signed in to GitHub as a different account, sign out first and sign in as accesswatch before continuing.

      +
        +
      1. Go to github.com and confirm the top-right avatar shows accesswatch.
        2. +
      2. Open the avatar menu, then select Your organizations.
        3. +
      3. Confirm both of the following organizations appear in the list:
          +
        • Community-Access -- the main workshop repository organization
          • +
        • Community-Access-Classroom -- the GitHub Classroom organization where student repos are created
          • +
        • If either is missing, do not proceed. Contact the org owner to ensure accesswatch has Owner-level membership in both.
          • +
        +
        4. +
      4. Click into Community-Access and open the Settings tab. Confirm you can see the full settings sidebar (Members, Actions, Secrets, etc.). If Settings is not visible, accesswatch does not have Owner access and you cannot proceed.
        5. +
      5. Click into Community-Access-Classroom and open its Settings tab. Confirm the same.
        6. +
      6. Optional CLI verification from the local repository root:
        7. +
      +
      gh auth status -h github.com
+gh repo view Community-Access/git-going-with-github
+gh repo view Community-Access/learning-room-template
      +

      Expected output: each gh repo view command should return repository metadata without an error. If you see "Could not resolve to a Repository", accesswatch does not have the required access.

      +

      Why this matters:

      +
        +
      • All downstream setup steps operate against Community-Access/git-going-with-github and Community-Access-Classroom. If the account does not have Owner access to both, secrets, variables, and classroom automation cannot be configured.
        • +
      +

      A.1 Create GitHub Classroom assignments

      +

      Do this before section B. You need both assignment URLs in hand before you can fill in the repository variables.

      +

      You must be signed in to GitHub as accesswatch for the following steps.

      +
        +
      1. Go to classroom.github.com.
        2. +
      2. You will see a list of classrooms. Select the classroom named for this cohort that is linked to the Community-Access-Classroom organization. The organization name appears below the classroom name on the card.
          +
        • If no classroom exists yet, select New classroom, then choose Community-Access-Classroom as the organization. Name the classroom using the format Git Going - [Cohort Name] - [Month Year] (for example, Git Going - May 2026).
          • +
        +
        3. +
      3. Inside the classroom, select New assignment.
        4. +
      4. Create the Day 1 assignment:
          +
        • Title: You Belong Here
          • +
        • Individual or group: Individual
          • +
        • Repository visibility: Private
          • +
        • Template repository: Community-Access/learning-room-template (search for it by name in the template field)
          • +
        • Grant students admin access: No
          • +
        • Enable feedback pull requests: Yes
          • +
        • Paste the Day 1 assignment description from classroom/assignment-day1-you-belong-here.md
          • +
        • Add autograding from admin/classroom/autograding-setup.md -- Day 1 requires exactly 4 tests totaling 50 points
          • +
        • Select Create assignment
          • +
        +
        5. +
      5. After saving, the assignment page shows an invite link at the top labeled something like Invite link. It will be in the format https://classroom.github.com/a/<short-code>. Copy this full URL and paste it somewhere safe (for example, a scratch notepad). This is your CLASSROOM_DAY1_ASSIGNMENT_URL.
        6. +
      6. Repeat for the Day 2 assignment:
          +
        • Title: You Can Build This
          • +
        • Same base settings as Day 1
          • +
        • Paste description from classroom/assignment-day2-you-can-build-this.md
          • +
        • Add Day 2 autograding: exactly 6 tests totaling 75 points
          • +
        • Copy the resulting invite URL. This is your CLASSROOM_DAY2_ASSIGNMENT_URL.
          • +
        +
        7. +
      7. Keep both URLs available. You will paste them into repository variables in section B step 4.
        8. +
      +

      Why this matters:

      +
        +
      • The repository variables CLASSROOM_DAY1_ASSIGNMENT_URL and CLASSROOM_DAY2_ASSIGNMENT_URL cannot be filled in until the assignments exist and their invite URLs are known. The short code in the URL is unique to each assignment and is not predictable in advance.
        • +
      +

      B. Configure registration automation key and variables

      +

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

      +

      You must be signed in as accesswatch for all steps in this section.

      +

      Step B.1 -- Generate the personal access token (PAT)

      +

      The CLASSROOM_ORG_ADMIN_TOKEN secret must be a GitHub personal access token generated by accesswatch (or another Owner-level account for Community-Access-Classroom). This token is what allows the registration workflow to invite students to the Community-Access-Classroom organization automatically.

      +
        +
      1. While signed in as accesswatch, go to github.com/settings/tokens.
        2. +
      2. Select Generate new token, then select Generate new token (classic).
          +
        • Do not use fine-grained tokens for this purpose. The admin:org scope is only available on classic tokens.
          • +
        +
        3. +
      3. In the Note field enter a descriptive name such as Community-Access registration automation.
        4. +
      4. In the Expiration field, set a date that covers your cohort timeline plus a buffer (for example, 90 days).
        5. +
      5. Under Select scopes, check admin:org. This is the only scope required. It gives the token permission to list and create organization invitations for Community-Access-Classroom.
        6. +
      6. Scroll to the bottom and select Generate token.
        7. +
      7. GitHub will display the token exactly once immediately after generation. It begins with ghp_. Copy it now and paste it somewhere safe (a local scratch notepad, not a repository file). You will not be able to view it again.
        8. +
      8. Do not close the token page until you have completed section B.2 and confirmed the secret was saved.
        9. +
      +

      Step B.2 -- Add the token as a repository secret

      +
        +
      1. Go to github.com/Community-Access/git-going-with-github/settings/secrets/actions.
        2. +
      2. Select New repository secret.
        3. +
      3. In the Name field, enter exactly: CLASSROOM_ORG_ADMIN_TOKEN
          +
        • Capitalization and underscores must match exactly.
          • +
        +
        4. +
      4. In the Secret field, paste the token you copied in step B.1.
        5. +
      5. Select Add secret.
        6. +
      6. Re-open the secret entry and confirm the name shows CLASSROOM_ORG_ADMIN_TOKEN. GitHub does not display the value again, but confirming the name is correct is sufficient.
        7. +
      +

      Step B.3 -- Add the repository variables

      +
        +
      1. At the same settings page, select the Variables tab (next to Secrets).
        2. +

      2. Select New repository variable for each of the following. Add them one at a time.

        +

        Variable 1:

        +
          +
        • Name: CLASSROOM_ORG
          • +
        • Value: Community-Access-Classroom
          • +
        • This is the exact GitHub organization name where students are invited. The capitalization and hyphens must match exactly.
          • +
        +

        Variable 2:

        +
          +
        • Name: CLASSROOM_DAY1_ASSIGNMENT_URL
          • +
        • Value: paste the Day 1 invite URL you copied in section A.1 step 5 (format: https://classroom.github.com/a/<short-code>)
          • +
        +

        Variable 3:

        +
          +
        • Name: CLASSROOM_DAY2_ASSIGNMENT_URL
          • +
        • Value: paste the Day 2 invite URL you copied in section A.1 step 6 (format: https://classroom.github.com/a/<short-code>)
          • +
        +
        3. +

      3. After adding all three, re-open each variable entry and confirm:

        +
          +
        • The name is exactly as listed above (no typos, no extra characters).
          • +
        • The value has no leading or trailing spaces. Paste into a plain text editor first if you are unsure, and trim whitespace before re-pasting.
          • +
        +
        4. +
      4. Run one registration test and confirm welcome comment contains assignment links.
        5. +
      +

      Why this matters:

      +
        +
      • These values drive invite and assignment-link injection in registration responses. A single typo in the org name or a trailing space in a variable value will silently break automation without a clear error message.
        • +
      +

      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.

      +

      The fastest path is Initialize-WorkshopSetup.ps1, which sets the secret, all three variables, verifies labels, and runs template prep in a single command. See the setup script section below.

      +

      Using the setup script (recommended):

      +
      scripts/classroom/Initialize-WorkshopSetup.ps1 -AdminPAT ghp_yourTokenHere
      +

      The script will:

      +
        +
      • Prompt you if the PAT is missing or invalid
        • +
      • Resolve Day 1 and Day 2 assignment URLs automatically from the GitHub Classroom API (if assignments exist in the GIT Going with Github classroom)
        • +
      • Set CLASSROOM_ORG_ADMIN_TOKEN secret and all three variables in Community-Access/git-going-with-github
        • +
      • Verify all three required labels exist, creating any that are missing
        • +
      • Confirm read-back values have no leading or trailing spaces
        • +
      • Run Prepare-LearningRoomTemplate.ps1 and Test-LearningRoomTemplate.ps1 unless skipped
        • +
      +

      If running manually instead:

      +
        +
      1. Generate a classic PAT with admin:org scope at github.com/settings/tokens (see section B of the setup steps above for exact steps).
        2. +
      2. Go to github.com/Community-Access/git-going-with-github/settings/secrets/actions.
        3. +
      3. Create secret CLASSROOM_ORG_ADMIN_TOKEN with the PAT value.
        4. +
      4. On the Variables tab, create:
          +
        • CLASSROOM_ORG = Community-Access-Classroom
          • +
        • CLASSROOM_DAY1_ASSIGNMENT_URL = invite URL from assignment A.1 step 5
          • +
        • CLASSROOM_DAY2_ASSIGNMENT_URL = invite URL from assignment A.1 step 6
          • +
        +
        5. +
      5. Re-open each value and verify no leading or trailing spaces.
        6. +
      +

      Pass criteria:

      +
        +
      • Secret and variables are present with correct values.
        • +
      • Initialize-WorkshopSetup.ps1 reported no failures, or manual verification confirms all values.
        • +
      • Configuration aligns with REGISTRATION-ADMIN.md.
        • +
      +

      Step 0.3 Registration deployment smoke check

      +

      Goal: validate the deployed registration system and site are working before manual QA begins.

      +

      Use Test-RegistrationPage.ps1 to run this check. The script validates the Pages site, the REGISTER page, the issue form template, required labels, and workflow state. With -RunLiveTest it also submits a real test registration issue, waits for the workflow, and verifies the welcome comment.

      +

      Static checks only (site, config, labels, workflow state):

      +
      scripts/classroom/Test-RegistrationPage.ps1
      +

      Full live end-to-end test including issue submission:

      +
      scripts/classroom/Test-RegistrationPage.ps1 -RunLiveTest
      +

      What the script checks:

      +
        +
      1. HTTP GET to https://community-access.org/git-going-with-github/ returns 200.
        2. +
      2. HTTP GET to https://community-access.org/git-going-with-github/REGISTER returns 200 and contains expected content.
        3. +
      3. workshop-registration.yml exists in .github/ISSUE_TEMPLATE/.
        4. +
      4. Labels registration, duplicate, and waitlist exist.
        5. +
      5. registration.yml workflow is active and has a recent successful run.
        6. +
      6. (Live test only) Test issue is submitted, workflow completes, welcome comment posts with assignment links, registration label is applied.
        7. +
      +

      Cleanup limitation: the test issue is closed and locked by the script. It cannot be deleted via the GitHub API. If deletion is needed, a repository admin must delete it manually from the Issues tab after this run.

      +

      Pass criteria:

      +
        +
      • Test-RegistrationPage.ps1 exits with no failures.
        • +
      • Live test (if run) confirms workflow executes end to end.
        • +
      • Output comment and 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.
        • +
      • Support links point to Community-Access/support issues/discussions.
        • +
      +

      Step 1.1 Verify support hub onboarding path

      +
        +
      1. Open Community-Access/support and confirm Issues and Discussions are enabled.
        2. +
      2. Confirm pinned Start Here onboarding guidance exists in Discussions.
        3. +
      3. Open a test support issue using a template and confirm triage labels apply.
        4. +
      +

      Pass criteria:

      +
        +
      • Support hub is reachable and public.
        • +
      • Onboarding path is discoverable for students.
        • +
      • Template-driven support issue flow works.
        • +
      +

      Step 2. Configure registration automation for classroom handoff

      +

      If Initialize-WorkshopSetup.ps1 was run successfully in Phase 0, this step is already complete. Re-verify with:

      +
      gh secret list -R Community-Access/git-going-with-github
+gh variable list -R Community-Access/git-going-with-github
      +

      Expected output: CLASSROOM_ORG_ADMIN_TOKEN appears in secrets, and CLASSROOM_ORG, CLASSROOM_DAY1_ASSIGNMENT_URL, CLASSROOM_DAY2_ASSIGNMENT_URL appear in variables.

      +

      If any are missing, run Initialize-WorkshopSetup.ps1 again or follow the manual steps in section B of the setup instructions. For full reference, see REGISTRATION-QUICKSTART.md and REGISTRATION-ADMIN.md.

      +

      Pass criteria:

      +
        +
      • CLASSROOM_ORG_ADMIN_TOKEN secret is present.
        • +
      • All 3 variables are present with correct values and no leading or trailing spaces.
        • +
      +

      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

      +

      GitHub Classroom assignment creation has no write API. All classroom creation and assignment setup must be done through the browser at classroom.github.com while signed in as accesswatch.

      +

      Note: a classroom already exists for this repository (GIT Going with Github, classroom id 322783, linked to Community-Access-Classroom). Unless starting a completely new classroom, skip classroom creation and go directly to assignment creation in Steps 11 and 12.

      +

      If you do need a new classroom:

      +
        +
      1. Go to classroom.github.com as accesswatch.
        2. +
      2. Select New classroom and choose Community-Access-Classroom as the organization.
        3. +
      3. Name it Git Going - [Cohort Name] - [Month Year] (for example, Git Going - May 2026).
        4. +
      4. Import roster from classroom/roster-template.csv on the Roster tab.
        5. +
      5. Add accesswatch-student to the roster as the test student.
        6. +
      +

      To verify the existing classroom is accessible:

      +
      gh api /classrooms --jq '.[] | {id, name, url}'
      +

      Pass criteria:

      +
        +
      • Classroom exists in Community-Access-Classroom and is accessible to accesswatch.
        • +
      • Roster includes accesswatch-student (or the designated test student username).
        • +
      +

      Step 11. Create Day 1 assignment exactly

      +

      See section A.1 of the setup steps above for full navigation instructions.

      +

      Use classroom/assignment-day1-you-belong-here.md and admin/classroom/day1-assignment-copy-paste.md for the exact title, description, and autograding entries.

      +

      To check if the Day 1 assignment already exists:

      +
      gh api /classrooms/322783/assignments --jq '.[] | {id, title, invite_link}'
      +

      If the assignment exists and its invite_link is already in the CLASSROOM_DAY1_ASSIGNMENT_URL variable, skip to Step 12.

      +

      If creating from scratch:

      +
        +
      1. Go to classroom.github.com as accesswatch and open the GIT Going with Github classroom.
        2. +
      2. Select New assignment.
        3. +
      3. Title: You Belong Here (exact match required)
        4. +
      4. Type: Individual, Visibility: Private
        5. +
      5. Template: Community-Access/learning-room-template
        6. +
      6. Grant students admin access: No
        7. +
      7. Enable feedback pull requests: Yes
        8. +
      8. Paste description from classroom/assignment-day1-you-belong-here.md
        9. +
      9. Add autograding from admin/classroom/autograding-setup.md -- Day 1 requires exactly 4 tests totaling 50 points
        10. +
      10. Save and copy the invite URL from the assignment page
        11. +
      11. If Initialize-WorkshopSetup.ps1 has not been run yet, paste the URL into CLASSROOM_DAY1_ASSIGNMENT_URL. If it has been run, re-run it to pick up the new URL automatically.
        12. +
      +

      Pass criteria:

      +
        +
      • Day 1 assignment exists with title You Belong Here.
        • +
      • Test count is 4, total points is 50.
        • +
      • Feedback pull request is enabled.
        • +
      • CLASSROOM_DAY1_ASSIGNMENT_URL variable matches the assignment invite link.
        • +
      +

      Step 12. Create Day 2 assignment exactly

      +

      Same process as Step 11. Check first whether it already exists:

      +
      gh api /classrooms/322783/assignments --jq '.[] | {id, title, invite_link}'
      +

      If the assignment exists and its invite_link is already in CLASSROOM_DAY2_ASSIGNMENT_URL, skip ahead.

      +

      If creating from scratch:

      +
        +
      1. In the GIT Going with Github classroom, select New assignment.
        2. +
      2. Title: You Can Build This (exact match required)
        3. +
      3. Apply same base settings as Day 1 (individual, private, no admin access, feedback PR enabled)
        4. +
      4. Template: Community-Access/learning-room-template
        5. +
      5. Paste description from classroom/assignment-day2-you-can-build-this.md
        6. +
      6. Add Day 2 autograding from admin/classroom/autograding-setup.md -- 6 tests totaling 75 points
        7. +
      7. Save and copy the invite URL
        8. +
      8. Update CLASSROOM_DAY2_ASSIGNMENT_URL or re-run Initialize-WorkshopSetup.ps1 to pick it up automatically
        9. +
      +

      Pass criteria:

      +
        +
      • Day 2 assignment exists with title You Can Build This.
        • +
      • Test count is 6, total points is 75.
        • +
      • Feedback pull request is enabled.
        • +
      • CLASSROOM_DAY2_ASSIGNMENT_URL variable matches the assignment invite link.
        • +
      +

      Step 13. Connect assignment URLs back to registration automation

      +

      If Initialize-WorkshopSetup.ps1 was run after the assignments were created, the variables are already set. Verify with:

      +
      gh variable list -R Community-Access/git-going-with-github
      +

      If either URL variable is missing or stale, re-run the setup script. It will resolve URLs directly from the Classroom API:

      +
      scripts/classroom/Initialize-WorkshopSetup.ps1 -AdminPAT ghp_yourTokenHere -SkipTemplatePrepare -SkipTemplateValidate
      +

      Then re-run the registration live test to confirm both URLs appear in the welcome comment:

      +
      scripts/classroom/Test-RegistrationPage.ps1 -RunLiveTest
      +

      Pass criteria:

      +
        +
      • CLASSROOM_DAY1_ASSIGNMENT_URL and CLASSROOM_DAY2_ASSIGNMENT_URL are set and match assignment invite links.
        • +
      • Registration confirmation comment includes both assignment URLs.
        • +
      • Test-RegistrationPage.ps1 -RunLiveTest exits with no failures.
        • +
      +

      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

      +

      The test student account is accesswatch-student. GitHub Classroom generates repository names from the assignment slug and the student username. For the default assignment titles, the repository names will be:

      +
        +
      • Day 1: Community-Access-Classroom/you-belong-here-accesswatch-student
        • +
      • Day 2: Community-Access-Classroom/you-can-build-this-accesswatch-student
        • +
      +

      Confirm the exact repository names first:

      +
      gh repo list Community-Access-Classroom --json name --jq '.[].name' | Select-String accesswatch-student
      +

      Then seed (replace repository slugs with the confirmed names if different):

      +
      $day1 = 'Community-Access-Classroom/you-belong-here-accesswatch-student'
+$day2 = 'Community-Access-Classroom/you-can-build-this-accesswatch-student'
+
+scripts/classroom/Seed-LearningRoomChallenge.ps1 -Repository $day1 -Challenge 1 -Assignee accesswatch-student
+scripts/classroom/Seed-PeerSimulation.ps1 -Repository $day1 -StudentUsername accesswatch-student
+scripts/classroom/Seed-LearningRoomChallenge.ps1 -Repository $day2 -Challenge 10 -Assignee accesswatch-student
+scripts/classroom/Seed-PeerSimulation.ps1 -Repository $day2 -StudentUsername accesswatch-student
      +

      Alternatively, if Initialize-WorkshopSetup.ps1 is run after accesswatch-student has accepted both invites, it will detect the repos and seed them automatically.

      +

      Pass criteria:

      +
        +
      • Challenge 1 issue appears in Day 1 repo assigned to accesswatch-student.
        • +
      • Challenge 10 issue appears in Day 2 repo assigned to accesswatch-student.
        • +
      • 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.

      +

      Script Reference

      +

      The following scripts in scripts/classroom/ are used by this runbook. Run each with -? or read the .SYNOPSIS block for full parameter documentation.

      + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + +
      ScriptPurposeAutomated
      Initialize-WorkshopSetup.ps1Set PAT secret, variables, labels; sync and validate template; seed test student challengesAll steps except PAT generation (browser required)
      Archive-CohortData.ps1Export cohort issues, roster, and discussions to git-going-student-success; reset source repoExport and archive are automated; roster reset may require PR due branch rules
      Delete-RegistrationIssues.ps1Delete registration/duplicate/waitlist issues via GraphQL mutationFully automated when user has repo admin and repo token scope
      Delete-RegistrationIssues-v2.jsExperimental Playwright UI deleter for issue cleanupPartially automated; UI selector fragility makes this fallback-only
      Test-RegistrationPage.ps1Validate Pages site, REGISTER page, issue form, labels, workflow, and live registration flowAll steps; test issue cleanup is close+lock only (see below)
      Prepare-LearningRoomTemplate.ps1Sync learning-room/ source into Community-Access/learning-room-templateFully automated
      Test-LearningRoomTemplate.ps1Create smoke repo from template, validate file inventory and workflow dispatchFully automated
      Seed-LearningRoomChallenge.ps1Seed a specific challenge issue in a student repositoryFully automated
      Seed-PeerSimulation.ps1Seed peer simulation issues and PR in a student repositoryFully automated
      Restore-LearningRoomFiles.ps1Restore baseline files into a student repo via recovery branch and PRFully automated
      Invoke-LearningRoomEndToEndTest.ps1Full end-to-end scripted QA harnessFully automated
      Reset-SupportHubEnvironment.ps1Rebuild support hub repository labels, settings, and baseline support automationFully automated
      +

      GitHub API Limitations

      +

      The following actions cannot be performed via any GitHub API and require manual browser-based action. These are hard platform constraints, not gaps in the scripts.

      + + + + + + + + + + + + + + + + + + + + + + + + + + + + +
      ActionWhy it cannot be automatedManual path
      Creating a Classroom assignmentNo write endpoint exists in the GitHub Classroom REST API (confirmed: only GET endpoints are documented and available)classroom.github.com as accesswatch
      Deleting issues via REST APIGitHub REST API has no DELETE endpoint for issuesUse scripts/classroom/Delete-RegistrationIssues.ps1 (GraphQL mutation path), or UI fallback
      Deleting or moving discussionsGraphQL discussion mutations do not include delete or move operationsDiscussions tab in GitHub UI -> each thread -> "..." -> Delete
      Generating a personal access tokenPAT generation requires browser authentication by designgithub.com/settings/tokens as accesswatch
      +

      Pre-Cohort Cleanup Procedure

      +

      Run this procedure after each cohort completes, before starting QA for the next cohort.

      +

      Archive previous cohort data

      +
      # Replace the slug with the cohort being archived (format: YYYY-MM-description)
+scripts/classroom/Archive-CohortData.ps1 -CohortSlug 2026-03-march-cohort
      +

      What this does:

      +
        +
      1. Exports all registration/duplicate/waitlist issues (with comments) to JSON and CSV.
        2. +
      2. Exports the current student-roster.json.
        3. +
      3. Exports discussions to JSON.
        4. +
      4. Pushes the archive to Community-Access/git-going-student-success under admin/cohorts/<CohortSlug>/.
        5. +
      5. Closes and locks all registration issues in the source repository.
        6. +
      6. Resets student-roster.json to the blank template.
        7. +
      +

      Use -WhatIf to preview without making changes:

      +
      scripts/classroom/Archive-CohortData.ps1 -CohortSlug 2026-03-march-cohort -WhatIf
      +

      After the script completes, two manual cleanup steps are required (API limitation):

      +
        +
      1. Delete registration issues -- use the GraphQL cleanup script (recommended):
        2. +
      +
      scripts/classroom/Delete-RegistrationIssues.ps1
      +
        +
      1. Delete discussions -- discussions still require manual deletion: +https://github.com/Community-Access/git-going-with-github/discussions
        2. +
      +

      Archive destination: https://github.com/Community-Access/git-going-student-success/tree/main/admin/cohorts/<CohortSlug>/

      +

      Current Progress Snapshot (2026-05-08)

      +
        +
      • Registration issues archived to git-going-student-success.
        • +
      • Registration issues deleted from source repository (count now 0).
        • +
      • Discussions deleted from source repository (count now 0).
        • +
      • Learning Room template sync PR merged: Community-Access/learning-room-template#11.
        • +
      • Registration secret and variable values set for next cohort (CLASSROOM_ORG_ADMIN_TOKEN, CLASSROOM_ORG, CLASSROOM_DAY1_ASSIGNMENT_URL, CLASSROOM_DAY2_ASSIGNMENT_URL).
        • +
      • Day 1 and Day 2 classroom assignments created for next cohort.
        • +
      + +
      + + + + diff --git a/html/admin/qa-bundle/admin/REGISTRATION-ADMIN.html b/html/admin/qa-bundle/admin/REGISTRATION-ADMIN.html new file mode 100644 index 00000000..d2369ff7 --- /dev/null +++ b/html/admin/qa-bundle/admin/REGISTRATION-ADMIN.html @@ -0,0 +1,222 @@ + + + + + + + Registration Administration Guide - GIT Going with GitHub + + + + + + + + +
      +

      Registration Administration Guide

      +

      This document explains how the registration system works and how to manage it, including optional API-based classroom invitation automation.

      +

      If you just need implementation steps, start with REGISTRATION-QUICKSTART.md.

      +

      How Registration Tracking Works

      +

      Registration Count (Website)

      +

      The registration page at REGISTER.html queries the GitHub Search API in real time every time a visitor loads the page. It counts open issues with the registration label. No CSV or local data is involved.

      +

      Capacity Check (Workflow)

      +

      When someone submits a registration issue, the GitHub Actions workflow queries all issues labeled registration and counts unique GitHub usernames. If the count is at or above 75, the registrant is placed on the waitlist instead.

      +

      Optional Classroom API Automation

      +

      When configured, the registration workflow can also:

      +
        +
      • Check whether the registrant is already in the classroom organization
        • +
      • Send an organization invitation if needed
        • +
      • Include Day 1 and Day 2 GitHub Classroom assignment links in the welcome comment
        • +
      +

      Important: This does not bypass GitHub Classroom acceptance. Students still must click the assignment link and accept.

      +

      Full API Setup (Classroom Automation)

      +

      Use these steps to enable end-to-end registration plus classroom invitation flow.

      +

      1. Create an admin token for organization invites

      +

      Create a GitHub personal access token for a facilitator/admin account with permission to manage organization invitations.

      +

      Recommended minimum permissions:

      +
        +
      • Organization administration permissions sufficient to create invitations
        • +
      • Repository read access for this repository
        • +
      +

      Store this token securely. Do not commit it to the repository.

      +

      2. Add repository secret

      +

      In repository settings, add this secret:

      +
        +
      • CLASSROOM_ORG_ADMIN_TOKEN = token from Step 1
        • +
      +

      3. Add repository variables

      +

      In repository settings, add these variables:

      +
        +
      • CLASSROOM_ORG = your classroom org name (example: Community-Access-Classroom)
        • +
      • CLASSROOM_DAY1_ASSIGNMENT_URL = Day 1 Classroom invite URL
        • +
      • CLASSROOM_DAY2_ASSIGNMENT_URL = Day 2 Classroom invite URL
        • +
      +

      If you omit these variables/secrets, registration still works; only the classroom automation steps are skipped.

      +

      4. Confirm workflow behavior

      +

      After setup, successful non-duplicate registrations should produce:

      +
        +
      1. Standard registration confirmation logic (registration label and capacity handling)
        2. +
      2. Organization invite status handling:
          +
        • invited (new invite sent)
          • +
        • already-invited (pending invite exists)
          • +
        • already-member (user already in org)
          • +
        +
        3. +
      3. Welcome comment including classroom assignment links (if configured)
        4. +
      +

      5. End-to-end test checklist

      +

      Run this once before opening registration publicly:

      +
        +
      1. Submit a test registration issue from a non-member test account.
        2. +
      2. Verify an org invitation is sent.
        3. +
      3. Verify Day 1/Day 2 assignment links appear in the welcome comment.
        4. +
      4. Accept org invite from the test account.
        5. +
      5. Accept Day 1 assignment link from the test account.
        6. +
      6. Confirm private classroom repo is created.
        7. +
      7. Submit a second registration from the same account and confirm duplicate handling.
        8. +
      +

      6. Operational notes

      +
        +
      • The automation runs only when capacity is available and the registration is not a duplicate.
        • +
      • Waitlisted users are not invited automatically by this workflow.
        • +
      • Assignment acceptance remains student-driven in GitHub Classroom.
        • +
      +

      7. Rollback plan

      +

      If invitation automation causes issues:

      +
        +
      1. Remove CLASSROOM_ORG_ADMIN_TOKEN secret (fastest stop switch), or
        2. +
      2. Clear CLASSROOM_ORG variable.
        3. +
      +

      Registration confirmations and CSV export continue to function without classroom API steps.

      +

      CSV Export

      +

      The CSV is a convenience export for reviewing registrations in spreadsheet form. It is regenerated from scratch (from the issues) every time someone registers or when the workflow is manually triggered. The issues are the source of truth, not the CSV.

      +

      The CSV is uploaded as a workflow artifact (retained for 90 days) and is only accessible to repository collaborators. It is not committed to the repository.

      +

      Downloading the CSV

      +

      Using the GitHub CLI

      +

      Download the latest registration CSV:

      +
      gh run download --name registrations --dir ./registrations -R community-access/git-going-with-github
      +

      List recent workflow runs first to pick a specific one:

      +
      gh run list --workflow=registration.yml -R community-access/git-going-with-github
+gh run download <run-id> --name registrations --dir ./registrations -R community-access/git-going-with-github
      +

      Using the GitHub Web UI

      +
        +
      1. Go to the repository on GitHub
        2. +
      2. Click the Actions tab
        3. +
      3. Click a Registration - Welcome & CSV Export workflow run
        4. +
      4. Scroll down to the Artifacts section
        5. +
      5. Click registrations to download the CSV
        6. +
      +

      Regenerating the CSV On Demand

      +

      To rebuild the CSV from all current registration issues (e.g., right before the workshop):

      +
      gh workflow run registration.yml -R community-access/git-going-with-github
      +

      This triggers the workflow_dispatch event, which rebuilds the CSV from all registration issues and uploads a fresh artifact.

      +

      Registration Scenarios

      +

      The workflow handles three scenarios when someone submits a registration issue:

      +

      1. New Registration (Spots Available)

      +
        +
      • Posts a welcome comment confirming registration
        • +
      • Adds the registration label
        • +
      • Optionally sends a classroom organization invitation
        • +
      • Optionally includes Day 1 and Day 2 assignment links in the welcome comment
        • +
      • Exports updated CSV as a workflow artifact
        • +
      +

      2. Duplicate Registration

      +
        +
      • Detects the user already has a prior registration issue
        • +
      • Posts a friendly message pointing to their original issue
        • +
      • Labels the issue duplicate and closes it
        • +
      +

      3. Registration Full (75+ Registrants)

      +
        +
      • Posts a message explaining registration is full
        • +
      • Labels the issue waitlist (keeps it open for future notification)
        • +
      • The registration page automatically switches to waitlist mode via JavaScript
        • +
      +

      Labels Used

      + + + + + + + + + + + + + + + + + + + + + + + +
      LabelColorPurpose
      registrationDefaultApplied to confirmed registrations
      duplicateGray (#cfd3d7)Applied to duplicate registration attempts
      waitlistYellow (#FBCA04)Applied when capacity is full
      +

      Privacy Notes

      +
        +
      • The CSV contains personal information (names, emails) and is stored only as a workflow artifact, not in the repository
        • +
      • A previous version of the CSV was committed to git history at commit 559ca5f. It remains accessible through git history but is no longer present in the current branch
        • +
      • Registration issues themselves are publicly visible since this is a public repository
        • +
      • The .gitignore file excludes .github/data/ to prevent accidental commits of registration data
        • +
      • Private student-success exports and facilitator follow-up notes belong in the private Community-Access/git-going-student-success repository, not in this public curriculum repository
        • +
      • The classroom roster sync file (.github/data/student-roster.json) intentionally stores non-PII operational data only
        • +
      + +
      + + + + diff --git a/html/admin/qa-bundle/admin/REGISTRATION-QUICKSTART.html b/html/admin/qa-bundle/admin/REGISTRATION-QUICKSTART.html new file mode 100644 index 00000000..4b7166ed --- /dev/null +++ b/html/admin/qa-bundle/admin/REGISTRATION-QUICKSTART.html @@ -0,0 +1,168 @@ + + + + + + + Registration Automation Quickstart (Facilitator) - GIT Going with GitHub + + + + + + + + +
      +

      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.

      +

      5-Minute Setup

      +
        +
      1. Create an admin token from a facilitator account with organization invitation permissions.
        2. +
      2. In repository settings, add secret:
          +
        • CLASSROOM_ORG_ADMIN_TOKEN
          • +
        +
        3. +
      3. In repository settings, add variables:
          +
        • CLASSROOM_ORG
          • +
        • CLASSROOM_DAY1_ASSIGNMENT_URL
          • +
        • CLASSROOM_DAY2_ASSIGNMENT_URL
          • +
        +
        4. +
      4. Save all values.
        5. +
      5. Submit one test registration issue from a non-member test account.
        6. +
      +

      Copy/Paste Settings Template

      +

      Use this checklist while entering repository settings values.

      +

      Repository Secret

      + + + + + + + + + + + +
      NameValue to paste
      CLASSROOM_ORG_ADMIN_TOKENPASTE_ADMIN_TOKEN_HERE
      +

      Repository Variables

      + + + + + + + + + + + + + + + + + + + +
      NameValue to paste
      CLASSROOM_ORGCommunity-Access-Classroom
      CLASSROOM_DAY1_ASSIGNMENT_URLhttps://classroom.github.com/a/REPLACE_DAY1_ID
      CLASSROOM_DAY2_ASSIGNMENT_URLhttps://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. +
      2. Organization invite is sent (or detected as already pending/member).
        3. +
      3. Day 1 and Day 2 assignment links appear in the confirmation comment.
        4. +
      4. registration label is applied.
        5. +
      +

      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. +
      2. Clear repository variable CLASSROOM_ORG
        3. +
      +

      The registration workflow will continue standard confirmation, capacity checks, and CSV export.

      +

      Full Support Reset (When Needed)

      +

      If support environment drift is detected, rebuild support hub baseline:

      +
      scripts/classroom/Reset-SupportHubEnvironment.ps1
      +

      Day-Of Operations

      +
        +
      1. Keep REGISTRATION-ADMIN.md open.
        2. +
      2. Watch Actions runs for registration.yml after each new registration.
        3. +
      3. Spot-check one confirmation comment every few runs.
        4. +
      4. If failures appear, use rollback and continue manual classroom invite flow.
        5. +
      +

      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.
        • +
      + +
      + + + + diff --git a/html/admin/qa-bundle/admin/classroom/autograding-setup.html b/html/admin/qa-bundle/admin/classroom/autograding-setup.html new file mode 100644 index 00000000..5a228f30 --- /dev/null +++ b/html/admin/qa-bundle/admin/classroom/autograding-setup.html @@ -0,0 +1,258 @@ + + + + + + + Autograding Setup and Verification - GIT Going with GitHub + + + + + + + + +
      +

      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:
        • +
      +
      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:
        • +
      +
      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:
        • +
      +
      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:
        • +
      +
      ! 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:
        • +
      +
      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:
        • +
      +
      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:
        • +
      +
      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:
        • +
      +
      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:
        • +
      +
      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:
        • +
      +
      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. +
      2. Confirm test count:
          +
        • Day 1 has 4 tests
          • +
        • Day 2 has 6 tests
          • +
        +
        3. +
      3. Confirm point totals:
          +
        • Day 1 total = 50
          • +
        • Day 2 total = 75
          • +
        +
        4. +
      4. Use a test student account to accept each assignment.
        5. +
      5. Trigger one known pass on each assignment.
        6. +
      6. Trigger one known fail on each assignment and confirm feedback appears.
        7. +
      7. Confirm rerun passes after fix.
        8. +
      8. Capture one screenshot of pass and one of fail for facilitator reference.
        9. +
      +

      Fast Validation Scenarios

      +

      Day 1 quick checks

      +
        +
      • Pass check: open an issue, make a commit, open a PR with Closes #<issue-number>, 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. +
      2. Open PR checks and inspect the failing command output.
        3. +
      3. Verify required text is in the file body, not only in issue comments.
        4. +
      +

      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/html/admin/qa-bundle/admin/classroom/day1-assignment-copy-paste.html b/html/admin/qa-bundle/admin/classroom/day1-assignment-copy-paste.html new file mode 100644 index 00000000..b3cf6061 --- /dev/null +++ b/html/admin/qa-bundle/admin/classroom/day1-assignment-copy-paste.html @@ -0,0 +1,153 @@ + + + + + + + Day 1 Assignment Copy-Paste - GIT Going with GitHub + + + + + + + + +
      +

      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.

      +
      # 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/html/admin/qa-bundle/admin/classroom/day2-assignment-copy-paste.html b/html/admin/qa-bundle/admin/classroom/day2-assignment-copy-paste.html new file mode 100644 index 00000000..410ac3ee --- /dev/null +++ b/html/admin/qa-bundle/admin/classroom/day2-assignment-copy-paste.html @@ -0,0 +1,154 @@ + + + + + + + Day 2 Assignment Copy-Paste - GIT Going with GitHub + + + + + + + + +
      +

      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.

      +
      # 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/html/admin/qa-bundle/admin/classroom/index.html b/html/admin/qa-bundle/admin/classroom/index.html new file mode 100644 index 00000000..50f4841e --- /dev/null +++ b/html/admin/qa-bundle/admin/classroom/index.html @@ -0,0 +1,100 @@ + + + + + + + Classroom Copy-Paste Pack - GIT Going with GitHub + + + + + + + + +
      +

      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.
        • +
      + +
        +
      1. Create the Classroom and import roster from classroom/README.md.
        2. +
      2. Create Day 1 assignment and paste content from day1-assignment-copy-paste.md.
        3. +
      3. Configure Day 1 tests using autograding-setup.md.
        4. +
      4. Create Day 2 assignment and paste content from day2-assignment-copy-paste.md.
        5. +
      5. Configure Day 2 tests using autograding-setup.md.
        6. +
      6. After each student accepts, run seeding commands from seeding-ops.md.
        7. +
      7. Use live-facilitation-flow.md during setup day to execute the full flow without missing steps.
        8. +
      +

      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/html/admin/qa-bundle/admin/classroom/live-facilitation-flow.html b/html/admin/qa-bundle/admin/classroom/live-facilitation-flow.html new file mode 100644 index 00000000..3758d01b --- /dev/null +++ b/html/admin/qa-bundle/admin/classroom/live-facilitation-flow.html @@ -0,0 +1,150 @@ + + + + + + + Live Facilitation Flow Checklist - GIT Going with GitHub + + + + + + + + +
      +

      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

      +
      scripts/classroom/Seed-LearningRoomChallenge.ps1 -Repository Community-Access-Classroom/learning-room-studentname -Challenge 1 -Assignee studentname
      +

      Day 2 seeding

      +
      scripts/classroom/Seed-LearningRoomChallenge.ps1 -Repository Community-Access-Classroom/learning-room-studentname -Challenge 10 -Assignee studentname
      +

      Peer simulation seeding

      +
      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/html/admin/qa-bundle/admin/qa-readiness/UNIT-TEST-RESULTS-2026-05-08.html b/html/admin/qa-bundle/admin/qa-readiness/UNIT-TEST-RESULTS-2026-05-08.html new file mode 100644 index 00000000..525eacc7 --- /dev/null +++ b/html/admin/qa-bundle/admin/qa-readiness/UNIT-TEST-RESULTS-2026-05-08.html @@ -0,0 +1,172 @@ + + + + + + + Unit Test Results - 2026-05-08 (Non-Podcast Scope) - GIT Going with GitHub + + + + + + + + +
      +

      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:
        2. +
      +
        +
      • 16 core challenge templates
        • +
      • 5 bonus templates
        • +
      • Complete numbering/lettering coverage
        • +
      +
        +
      1. Challenge quality gates:
        2. +
      +
        +
      • Required evidence fields and troubleshooting guidance
        • +
      • Core and bonus template quality checks
        • +
      +
        +
      1. Classroom setup consistency:
        2. +
      +
        +
      • Assignment docs and autograding JSON integrity
        • +
      • Required scripts and template files present
        • +
      • Classroom README deployment section coverage
        • +
      +
        +
      1. Workflow configuration readiness:
        2. +
      +
        +
      • Concurrency settings in key workflows
        • +
      • Critical permissions in bot/progression workflows
        • +
      +
        +
      1. Registration readiness:
        2. +
      +
        +
      • Workflow logic includes registration, duplicate, and waitlist paths
        • +
      • Registration issue form template exists
        • +
      +
        +
      1. QA gate integrity:
        2. +
      +
        +
      • 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:
        2. +
      +
        +
      • Cause: expected wording did not match final runbook phrasing.
        • +
      • Fix: updated test to assert actual required phrasing in runbook.
        • +
      +
        +
      1. Registration template name assertion too strict:
        2. +
      +
        +
      • 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:

      + +

      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.

      + +
      + + + + diff --git a/html/admin/qa-bundle/admin/qa-readiness/index.html b/html/admin/qa-bundle/admin/qa-readiness/index.html new file mode 100644 index 00000000..be21914c --- /dev/null +++ b/html/admin/qa-bundle/admin/qa-readiness/index.html @@ -0,0 +1,118 @@ + + + + + + + QA Readiness Test Pack (Non-Podcast) - GIT Going with GitHub + + + + + + + + +
      +

      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:

      +
      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:

      + +

      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:

      + + +
      + + + + diff --git a/html/admin/qa-bundle/classroom/HUMAN_TEST_MATRIX.html b/html/admin/qa-bundle/classroom/HUMAN_TEST_MATRIX.html new file mode 100644 index 00000000..4277c853 --- /dev/null +++ b/html/admin/qa-bundle/classroom/HUMAN_TEST_MATRIX.html @@ -0,0 +1,312 @@ + + + + + + + Human Test Matrix for Learning Room Challenges - GIT Going with GitHub + + + + + + + + +
      +

      Human Test Matrix for Learning Room Challenges

      +

      Use this matrix before each cohort to verify that the Learning Room template behaves like a realistic collaborative GitHub project while still working inside private GitHub Classroom repositories.

      +

      Required Test Repositories

      +

      Create at least one disposable student repository from the current Community-Access/learning-room-template template. For full peer-access testing, create two disposable repositories and use two test student accounts.

      +

      Minimum smoke test:

      +
        +
      • learning-room-smoke-a
        • +
      +

      Full collaboration test:

      +
        +
      • learning-room-smoke-a
        • +
      • learning-room-smoke-b
        • +
      +

      Required Facilitator Setup

      +

      After the student repository exists, run:

      +
      scripts/classroom/Seed-LearningRoomChallenge.ps1 -Repository Community-Access/learning-room-smoke-a -Challenge 1 -Assignee test-student-a
+scripts/classroom/Seed-PeerSimulation.ps1 -Repository Community-Access/learning-room-smoke-a -StudentUsername test-student-a
      +

      For Day 2-only testing, seed Challenge 10 instead:

      +
      scripts/classroom/Seed-LearningRoomChallenge.ps1 -Repository Community-Access/learning-room-smoke-a -Challenge 10 -Assignee test-student-a
+scripts/classroom/Seed-PeerSimulation.ps1 -Repository Community-Access/learning-room-smoke-a -StudentUsername test-student-a
      +

      What The Peer Simulation Creates

      +

      Seed-PeerSimulation.ps1 creates realistic collaboration artifacts inside the student's private repo:

      +
        +
      • Peer Simulation: Welcome Link Needs Context issue
        • +
      • Peer Simulation: Review Request for Contribution Guidance issue
        • +
      • Peer Simulation: Improve contribution guidance pull request
        • +
      • docs/samples/peer-review-practice.md on branch peer-simulation/review-pr
        • +
      +

      Students can use these artifacts whenever a challenge asks them to comment, react, review, compare, or practice collaboration. If facilitators separately provision real buddy access, students may use the real buddy repository instead.

      +

      Day 1 Core Test

      +

      Complete these steps as a test student.

      +
        +

      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. +

      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. +

      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. +

      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. +

      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. +

      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. +

      7. Challenge 7: Survive a Merge Conflict

        +
          +
        • Run the facilitator conflict script after the student's PR exists:
          • +
        +
        8. +
      +
      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.
        • +
      +
        +

      1. 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.
          • +
        +
        2. +

      2. 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.
          • +
        +
        3. +
      +

      Day 2 Core Test

      +

      Seed Challenge 10 if continuing from Day 1 did not naturally reach it.

      +
        +

      1. 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.
          • +
        +
        2. +

      2. 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.
          • +
        +
        3. +

      3. 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.
          • +
        +
        4. +

      4. 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.
          • +
        +
        5. +

      5. 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.
          • +
        +
        6. +

      6. 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.
          • +
        +
        7. +

      7. 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.
          • +
        +
        8. +
      +

      Bonus Test

      +

      The five bonus challenges are optional and facilitator-reviewed.

      +
        +

      1. Bonus A: Improve an Existing Agent

        +
          +
        • Choose an existing agent.
          • +
        • Propose and submit a meaningful improvement.
          • +
        +
        2. +

      2. Bonus B: Document Your Journey

        +
          +
        • Write a reflection document.
          • +
        • Verify it is clear and accessible.
          • +
        +
        3. +

      3. 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.
          • +
        +
        4. +

      4. Bonus D: Notification Mastery

        +
          +
        • Configure notification settings.
          • +
        • Document the student's notification strategy.
          • +
        +
        5. +

      5. Bonus E: Explore Git History Visually

        +
          +
        • Use GitHub Desktop or GitHub.com history views.
          • +
        • Explain what changed over time.
          • +
        +
        6. +
      +

      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/html/admin/qa-bundle/classroom/assignment-day1-you-belong-here.html b/html/admin/qa-bundle/classroom/assignment-day1-you-belong-here.html new file mode 100644 index 00000000..b347dfa5 --- /dev/null +++ b/html/admin/qa-bundle/classroom/assignment-day1-you-belong-here.html @@ -0,0 +1,178 @@ + + + + + + + Assignment 1: You Belong Here - GIT Going with GitHub + + + + + + + + +
      + + +

      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.

      + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + +
      ChallengeWhat You DoChapter
      1. Find Your Way AroundExplore the repository structure and locate key filesChapter 3
      2. File Your First IssueCreate an issue describing something you noticedChapter 5
      3. Join the ConversationMention a teammate or bot using @mentionsChapter 5
      4. Branch OutCreate a feature branch for your workChapter 4
      5. Make Your MarkEdit a file and commit with a clear messageChapter 4
      6. Open Your First Pull RequestOpen a PR that references an issue with Closes #NChapter 6
      7. Survive a Merge ConflictUnderstand and fix conflict markersChapter 7
      8. The Culture LayerReflect on community norms and communicationChapter 8
      9. Merge DayGet your PR reviewed, approved, and mergedChapter 10
      +

      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 for what comes next.

      +

      Day 1 is your only day? Everything you learned today is complete and self-contained. See the Next Steps guide for how to continue your GitHub journey independently.

      +

      Bonus Challenges

      +

      If you finish early, check the Challenges page for bonus challenges A through E.

      + +
      + + + + diff --git a/html/admin/qa-bundle/classroom/assignment-day2-you-can-build-this.html b/html/admin/qa-bundle/classroom/assignment-day2-you-can-build-this.html new file mode 100644 index 00000000..8576358d --- /dev/null +++ b/html/admin/qa-bundle/classroom/assignment-day2-you-can-build-this.html @@ -0,0 +1,168 @@ + + + + + + + Assignment 2: You Can Build This - GIT Going with GitHub + + + + + + + + +
      + + +

      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 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.

      + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + +
      ChallengeWhat You DoChapter
      10. Go LocalClone, branch, edit, commit, and push using local GitChapter 14
      11. Open a Day 2 PROpen a PR from your locally-pushed branchChapter 15
      12. Review Like a ProReview a classmate's PR with specific, constructive feedbackChapter 15
      13. AI as Your CopilotUse Copilot to improve documentation and evaluate its outputChapter 16
      14. Template RemixCreate a custom YAML issue templateChapter 17
      15. Meet the AgentsExplore and run agents from the accessibility-agents repoChapter 19
      16. Build Your Agent (Capstone)Design and submit an original agent with responsibilities and guardrailsChapter 20
      +

      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 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 repository:

      +
        +
      1. Fork the repository to your account
        2. +
      2. Clone your fork locally
        3. +
      3. Create a branch for your work
        4. +
      4. Open a PR from your fork back to the original
        5. +
      +

      See Chapter 18 for the full fork workflow. If forking is new to you, Chapter 6: Working with Pull Requests covers the fundamentals.

      +

      Bonus Challenges

      +

      If you finish early, check the Challenges page for bonus challenges.

      + +
      + + + + diff --git a/html/admin/qa-bundle/classroom/grading-guide.html b/html/admin/qa-bundle/classroom/grading-guide.html new file mode 100644 index 00000000..24f9020a --- /dev/null +++ b/html/admin/qa-bundle/classroom/grading-guide.html @@ -0,0 +1,293 @@ + + + + + + + Facilitator Grading Guide - GIT Going with GitHub + + + + + + + + +
      +

      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 and 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)

      + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + +
      #ChallengeEvidenceComplete if...
      01Find Your Way AroundIssue comment listing findingsStudent explored multiple tabs and found key files
      02First Issue (auto)Open issueTitle is clear and body has context
      03Join the ConversationComment thread with @mentionAt least one substantive reply to the peer-simulation issue or a real buddy issue if access is provisioned
      04Branch OutBranch existsAny branch with any name exists
      05Make Your Mark (auto)Commit on branchFile was edited and commit message is descriptive
      06First PR (auto)Open or merged PRPR has title + description + Closes #N
      07Merge Conflict (auto)Clean file in PRNo conflict markers remain
      08CultureComment or issue body with reflectionShows genuine engagement with governance files
      09Merge DayMerged PRAt least one PR was reviewed and merged
      +

      Day 2 Challenges (10-16)

      + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + +
      #ChallengeEvidenceComplete if...
      10Go Local (auto)Branch pushed from local cloneGit log shows local commits
      11Day 2 PRPR from locally-pushed branchPR exists with description
      12Code ReviewReview comment on the peer-simulation PR or a real buddy PR if access is provisionedAt least one specific, constructive comment
      13CopilotEvidence of Copilot interactionShows both Copilot output AND student evaluation
      14Issue Template (auto)YAML file in .github/ISSUE_TEMPLATE/Has name and description fields
      15AgentsExploration notes in issue or PRExamined at least one agent's instructions
      16Capstone (auto)Agent file with PR to accessibility-agents, plus peer-simulation or real peer review evidenceHas frontmatter, responsibilities, guardrails
      +

      Bonus Challenges (A-E)

      + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + +
      #ChallengeEvidenceComplete if...
      AAccessibility AuditIssue or PR with findingsIdentified at least 2 real accessibility issues
      BMentor a PeerThread showing guidanceHelped another student resolve a challenge, or provided high-quality guidance on a peer-simulation issue if real peer access is unavailable
      CCross-Repo ContributionPR to accessibility-agents or git-going repoPR submitted to a repo outside the learning room
      DCustom WorkflowWorkflow file or documentationCreated or documented a reusable workflow
      EDocumentation ChampionDoc improvements in any repoImproved 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

      + + + + + + + + + + + + + + + + + + + + + + + + + + + +
      LevelDay 1 + Day 2 participantsDay 2 only participantsLabel
      Workshop Complete7 of 9 (Day 1) + 5 of 7 (Day 2)5 of 7 (Day 2)Participated fully
      Workshop Complete with Distinction9 of 9 + 7 of 77 of 7Completed all core challenges
      Workshop Complete with Honors9 of 9 + 7 of 7 + 2 bonus7 of 7 + 2 bonusExceeded 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/html/admin/qa-bundle/classroom/index.html b/html/admin/qa-bundle/classroom/index.html new file mode 100644 index 00000000..4c092733 --- /dev/null +++ b/html/admin/qa-bundle/classroom/index.html @@ -0,0 +1,704 @@ + + + + + + + Workshop Deployment Guide - GIT Going with GitHub + + + + + + + + +
      +

      Workshop Deployment Guide

      +
      +

      Single, end-to-end guide for deploying a new Git Going with GitHub workshop cohort. Covers everything from creating the classroom through post-workshop teardown. This is the only deployment document you need.

      +
      +
      +

      Before sharing invite links with students, complete the Go-Live QA Guide. It is the final release gate for content, workflows, Classroom setup, podcasts, accessibility, and human test coverage.

      +
      +
      +

      If you need one practical execution script from registration through full student challenge completion (podcast work excluded), use admin/LEARNING-ROOM-E2E-QA-RUNBOOK.md.

      +
      +
      +

      Before creating assignments, sync and validate the latest template deployment using scripts/classroom/Prepare-LearningRoomTemplate.ps1 and scripts/classroom/Test-LearningRoomTemplate.ps1.

      +
      +

      How the Workshop Works

      +

      Each student gets their own private repository created by GitHub Classroom from the learning-room-template. Inside that repo, three automation systems guide the student through all 21 challenges without facilitator intervention:

      +
        +
      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. +
      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. +
      3. Autograders -- automated tests that verify objective evidence of challenge completion (branch exists, conflict markers removed, template file valid, agent file structured correctly)
        4. +
      +

      No shared student repository. Students do not clone the template or configure permissions. The facilitator's deployment work is creating the classroom and two assignments in the GitHub Classroom web UI, then running the seeding scripts after each student repo is created.

      +

      Students only need a GitHub account. They do not need to create an organization, become members of Community-Access, or change GitHub Actions settings. Organization and repository workflow permissions are facilitator responsibilities.

      +

      Architecture

      +
      Community-Access/learning-room-template (template repo)
+    |
+    +--> GitHub Classroom creates one private repo per student
+    |       learning-room-student-a
+    |       learning-room-student-b
+    |       ...
+    |
+    +--> Each student repo contains:
+    |       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

      + + + + + + + + + + + + + + + + + + + + + +
      PathWho it is forAssignmentEntry point
      Day 1 + Day 2Participants starting from scratchAssignment 1 (Day 1) then Assignment 2 (Day 2)Day 1 Agenda
      Day 2 onlyParticipants with GitHub fundamentalsAssignment 2 onlyDay 2 Quick Start then Day 2 Agenda
      +

      Day-2-only participants skip Assignment 1 entirely. They verify readiness using the Day 2 Quick Start self-assessment, then accept only the Day 2 invite link.

      +

      What Is in This Directory

      + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + +
      FilePurpose
      assignment-day1-you-belong-here.mdAssignment description for Day 1 (paste into Classroom UI)
      assignment-day2-you-can-build-this.mdAssignment description for Day 2 (paste into Classroom UI)
      autograding-day1.jsonTest definitions for Day 1 autograder
      autograding-day2.jsonTest definitions for Day 2 autograder
      grading-guide.mdFacilitator rubric for all 21 challenges
      roster-template.csvStarter CSV for importing student roster
      student-progression.ymlReference copy of the progression bot workflow
      HUMAN_TEST_MATRIX.mdEnd-to-end human walkthrough for all 16 core and 5 bonus challenges
      teardown-checklist.mdPost-workshop cleanup steps
      ../GO-LIVE-QA-GUIDE.mdFinal release-readiness guide and checklist
      ../admin/LEARNING-ROOM-E2E-QA-RUNBOOK.mdSingle 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 and sign in with your facilitator account
        2. +
      2. Click New classroom
        3. +
      3. Select the Community-Access organization (if you do not see it, accept the GitHub Classroom invitation from your org admin)
        4. +
      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. +
      5. Skip the TA / co-teacher setup -- facilitators use organization-level permissions instead
        6. +
      6. Click Create classroom
        7. +
      +
      +

      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. +
      2. Go to Settings (gear icon) then Roster Management
        3. +
      3. Click Import from CSV
        4. +
      4. Upload a completed version of roster-template.csv:
        5. +
      +
      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:

      + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + +
      SettingValue
      TitleYou Belong Here
      TypeIndividual
      VisibilityPrivate (student repos visible only to the student and facilitators)
      Template repositoryCommunity-Access/learning-room-template
      Grant students admin accessNo
      Enable feedback pull requestsYes
      DeadlineEnd 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, copy everything below the HTML metadata comment, and paste it into the description field
        2. +
      2. Autograding tests: Open 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. +
      3. Click Create assignment -- this generates your Day 1 invite link
        4. +
      +

      What the student experiences (Day 1)

      +
        +
      1. Student clicks the invite link
        2. +
      2. GitHub Classroom creates their private repo (30-60 seconds)
        3. +
      3. Facilitator seeds Challenge 1 (Find Your Way Around) using student-progression.yml
        4. +
      4. Student completes the challenge, posts evidence, closes the issue
        5. +
      5. Progression Bot creates Challenge 2 issue with full instructions
        6. +
      6. Student repeats through Challenge 9 (Merge Day)
        7. +
      7. Aria provides real-time feedback on every PR along the way
        8. +
      8. Autograders validate Challenges 4, 5, 6, 7, and 9 automatically
        9. +
      +
      +

      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:

      + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + +
      SettingValue
      TitleYou Can Build This
      TypeIndividual
      VisibilityPrivate
      Template repositoryCommunity-Access/learning-room-template
      Grant students admin accessNo
      Enable feedback pull requestsYes
      DeadlineOne 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
        2. +
      2. Autograding tests: Use autograding-day2.json
        3. +
      3. Click Create assignment -- this generates your Day 2 invite link
        4. +
      +

      What the student experiences (Day 2)

      +
        +
      1. Student clicks the Day 2 invite link
        2. +
      2. GitHub Classroom creates a new private repo for Day 2
        3. +
      3. Facilitator seeds Challenge 10 (Go Local) using student-progression.yml
        4. +
      4. Student clones the repo, works locally, pushes, and closes the issue
        5. +
      5. Progression Bot unlocks Challenges 11 through 16 sequentially
        6. +
      6. Challenge 16 (Capstone) has the student fork the accessibility-agents repo and open a cross-fork PR
        7. +
      7. Bonus challenges (A through E) are available via issue templates for students who finish early
        8. +
      +
      + +

      Each assignment generates a unique invite URL.

      + +
        +
      1. Copy the Day 1 invite URL from the assignment page
        2. +
      2. In the git-going-with-github repository, open DAY1_AGENDA.md and replace the [INVITE_LINK] placeholder
        3. +
      3. Copy the Day 2 invite URL
        4. +
      4. Open DAY2_AGENDA.md and replace its [INVITE_LINK] placeholder
        5. +
      5. Optionally, email the invite links directly to students before the workshop
        6. +
      +

      What students see when they click

      +
        +
      1. GitHub shows a "Join classroom" page if they are not already on the roster
        2. +
      2. If on the roster, they see "Accept this assignment"
        3. +
      3. After accepting, GitHub creates their private repo within 30-60 seconds
        4. +
      4. The student's repository URL follows the pattern: github.com/Community-Access-Classroom/learning-room-[username]
        5. +
      + + + + + + + + + + + + + + + + + + + +
      Participant typeSend Day 1 linkSend Day 2 link
      Full workshop (Day 1 + Day 2)YesYes
      Day-2-onlyNoYes
      +
      +

      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:

      +
      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:

      +
      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:

      +
      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. +
      2. Open a PR
        3. +
      3. Go to the Actions tab and verify the autograding workflow ran
        4. +
      4. Check the workflow output -- each test should report pass or fail correctly
        5. +
      5. Try a change that should fail a check and verify it catches the problem
        6. +
      +

      Aria verification

      +
        +
      1. Open a PR without a Closes #XX reference
        2. +
      2. Verify Aria posts a comment asking for an issue link
        3. +
      3. Comment @aria-bot I have a merge conflict, can you explain this?
        4. +
      4. Verify the comment responder replies with guidance
        5. +
      +
      +

      Step 7: Day-of-Workshop Facilitation

      +

      Before students arrive

      +
        +
      • Verify the classroom dashboard loads at classroom.github.com
        • +
      • Have both invite links ready to share (on-screen, in chat, or printed on cards)
        • +
      • Open the grading-guide.md for reference during the day
        • +
      • Have the Challenge Hub 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:

      + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + +
      IssueWhat 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. +
      2. Go to the Pull Requests tab
        3. +
      3. Open the feedback PR (titled "Feedback")
        4. +
      4. Leave comments, encouragement, and guidance here
        5. +
      5. Students receive email notifications for your comments
        6. +
      +
      +

      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

      + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + +
      ChallengeTitleHow it completesAria validatesAutograded
      1Find Your Way AroundClose issue----
      2File Your First IssueClose issue----
      3Join the ConversationClose issue----
      4Branch OutClose issue--Yes (branch exists)
      5Make Your MarkClose issue--Yes (file edited)
      6Open Your First Pull RequestClose issueYes (PR structure)Yes (issue reference)
      7Survive a Merge ConflictClose issueYes (PR feedback)Yes (no conflict markers)
      8The Culture LayerClose issue----
      9Merge DayClose issueYes (merge)Yes (PR merged)
      +

      Day 2 (Assignment 2): Challenges 10-16 + Bonus

      + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + +
      ChallengeTitleHow it completesAria validatesAutograded
      10Go LocalClose issue--Yes (local commit)
      11Open a Day 2 PRClose issueYes (PR structure)Yes (local push)
      12Review Like a ProClose issue--Yes (review comment)
      13AI as Your CopilotClose issue----
      14Template RemixClose issue--Yes (YAML valid)
      15Meet the AgentsClose issue----
      16Build Your Agent (Capstone)Close issue--Yes (agent file)
      A-EBonus challengesClose issue----
      +

      Challenges that cannot be automated

      +

      Challenges 1, 2, 3, 8, 13, and 15 are evaluated manually using the 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 for complete post-workshop steps. The key actions:

      +
        +
      1. Export grades from the classroom dashboard
        2. +
      2. Archive the classroom in the Classroom UI (this preserves student repos as read-only portfolio pieces)
        3. +
      3. Review feedback and update facilitation notes for next cohort
        4. +
      +
      +

      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. +
      2. Scroll to Autograding
        3. +
      3. Add, edit, or remove individual tests
        4. +
      4. Changes apply to all future student pushes (not retroactively)
        5. +
      +

      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 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 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
        • +
      + + + +
      + + + + diff --git a/html/admin/qa-bundle/docs/00-pre-workshop-setup.html b/html/admin/qa-bundle/docs/00-pre-workshop-setup.html new file mode 100644 index 00000000..8801d597 --- /dev/null +++ b/html/admin/qa-bundle/docs/00-pre-workshop-setup.html @@ -0,0 +1,1108 @@ + + + + + + + Pre-Workshop Setup - GIT Going with GitHub + + + + + + + + +
      +

      Pre-Workshop Setup - GIT Going with GitHub

      +
      +

      Listen to Episode 1: Pre-Workshop Setup - 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 Y: Workshop Materials | Appendix Z: GitHub Skills +Authoritative sources: GitHub Docs: Create an account | GitHub Docs: Set up Git

      +
      +

      Everything You Need Before Day 1 Begins

      +
      +

      A Community Access workshop.

      +

      Please complete this guide at least one day before the workshop. If you run into any issues, use the support hub at Community-Access/support 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. 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
        2. +
      2. Step 1 - Create Your GitHub Account
        3. +
      3. Step 2 - Configure GitHub Accessibility Settings
        4. +
      4. Step 3 - Configure Your Profile
        5. +
      5. Step 4 - Check GitHub Feature Preview Settings
        6. +
      6. Step 5 - Set Up Your Screen Reader and Browser
        7. +
      7. Step 6 - Install Git and Visual Studio Code
        8. +
      8. Step 7 - Configure Git Identity
        9. +
      9. Step 8 - Install VS Code Extensions
        10. +
      10. Step 9 - Verification Checklist
        11. +
      11. Other GitHub Access Methods (Reference Only)
        12. +
      12. Getting Help Before the Event
        13. +
      +

      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 (Windows/Linux) or Xcode Command Line Tools (macOS)
        • +
      • Visual Studio Code (free) - download here (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 ReaderPlatformCostDownload
      NVDA (NonVisual Desktop Access)WindowsFreeDownload NVDA
      JAWS (Job Access With Speech)WindowsPaid (trial available)Download JAWS
      VoiceOvermacOS / iOSBuilt-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 covers SSH keys and personal access tokens in detail.

      +
      +

      If you already have a GitHub account, skip to Step 2.

      +
      +

      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
        2. +

      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. +

      3. The next field is "Create a password"

        +
          +
        • Choose a password of at least 8 characters (15+ recommended). Press Tab or Continue
          • +
        +
        4. +

      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. +

      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. +

      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. +
      7. Activate the Create account button
        8. +

      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. +
      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
        10. +
      +

      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 while signed in.
        2. +
      2. Under Two-factor authentication, choose Enable and follow the prompts.
        3. +
      3. Choose one of the second-factor methods (recommended order):
          +
        • GitHub Mobile app (recommended for this workshop): Install the free GitHub 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.
          • +
        +
        4. +
      +

      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. +
      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. +
      3. Approve the authorization request.
        4. +
      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.
        5. +
      +

      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 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.

      + +

      The fastest path for everyone: navigate directly to GitHub Accessibility Settings 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. +
      2. A dropdown menu appears - click Settings
        3. +
      3. On the Settings page, scroll the left sidebar and click Accessibility
        4. +
      +
      + +
      +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. +
      2. Press B repeatedly until you hear "Open user navigation menu, button" (top-right of the page) and press Enter
        3. +
      3. Navigate the menu with ↓ or K until you hear "Settings" and press Enter
        4. +
      4. On the Settings page, press D to move through landmark regions until you reach the left sidebar navigation
        5. +
      5. Press K or ↓ to navigate through sidebar links until you hear "Accessibility" and press Enter
        6. +
      +
      + +
      +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. +
      2. Press VO+Down Arrow to find "Settings" and press VO+Space
        3. +
      3. On Settings, press VO+U, go to Links, find "Accessibility" and press Enter
        4. +
      +
      + +

      Settings to configure

      +

      Work through each setting below. All are on the Accessibility settings page 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. +
      2. Press F or X to jump through form controls until you hear "Link previews" or "Hovercards"
        3. +
      3. If it is announced as checked or on, press Space to turn it off
        4. +
      4. The change saves automatically - no Submit button required
        5. +
      +
      + + +
      +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. +
      2. If it is announced as unchecked, press Space to enable it
        3. +
      3. The change saves automatically
        4. +
      +
      + +

      3. Character Key Shortcuts

      +
        +
      1. Find "Character key shortcuts"
        2. +
      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. +
      3. Leave at the default unless you have a reason to change it
        4. +
      +

      4. Set Your Theme (Appearance Settings)

      +

      Theme is on a separate page: GitHub Appearance Settings

      +
        +
      1. Navigate to that page
        2. +
      2. Find the "Theme mode" or "Theme" section
        3. +
      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. +
      4. Select your preferred theme and activate Save if prompted (some changes apply immediately)
        5. +
      +

      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
        2. +
      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
          • +
        +
        3. +
      + +

      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
        2. +
      2. Add a custom routing email if you want GitHub notifications to go to a different address than your account email
        3. +
      +

      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/ and accessibility.github.com/documentation/guide/pull-requests/

      +
      +
      +Visual / mouse users + +
        +
      1. Sign in to GitHub and go to any page
        2. +
      2. Click your profile picture (avatar) in the top-right corner
        3. +
      3. In the dropdown menu, click Feature preview
        4. +
      4. A panel opens on the right side of the screen listing available features
        5. +
      5. Click on New Issues Experience to expand its details
        6. +
      6. If an Enable button appears, click it. If you see Disable, the feature is already active - no action needed.
        7. +
      7. Return to the feature list and repeat for New Files Changed Experience
        8. +
      +
      + +
      +Screen reader users (NVDA / JAWS) + +

      NVDA or JAWS (Windows)

      +
        +
      1. Sign into GitHub and open any page
        2. +
      2. Switch to Browse Mode if not already active (NVDA+Space / JAWS virtual cursor)
        3. +
      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. +
      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. +
      5. Press Enter to activate it - a dropdown menu opens
        6. +
      6. Press ↓ or K to move through the menu items until you hear "Feature preview"
        7. +
      7. Press Enter to select it - the Feature Preview panel opens
        8. +
      8. Navigate through the list of features with ↓ or I (list item navigation)
        9. +
      9. When you reach "New Issues Experience", press Enter or Space to select it - its detail panel expands
        10. +
      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. +
      11. Go back and repeat steps 9-10 for "New Files Changed Experience"
        12. +
      12. Repeat again for "GitHub Command Palette" if it appears in the list
        13. +
      +
      + +
      +Screen reader users (VoiceOver on macOS) + +
        +
      1. Sign into GitHub and open any page
        2. +
      2. Press VO+U to open the Rotor and navigate to the Buttons list
        3. +
      3. Find "Open user navigation menu" and press Enter to activate it
        4. +
      4. Use VO+Down Arrow to navigate the dropdown until you hear "Feature preview"
        5. +
      5. Press VO+Space to activate it - the Feature Preview panel opens
        6. +
      6. Use VO+Down Arrow or VO+Right Arrow to navigate through the feature list
        7. +
      7. When you reach "New Issues Experience", press VO+Space to select it
        8. +
      8. Press Tab to move to the end of the feature detail section
        9. +
      9. If you hear "Enable", press VO+Space to activate it. If you hear "Disable", it is already on.
        10. +
      10. Repeat for "New Files Changed Experience"
        11. +
      11. Repeat for "GitHub Command Palette" if it appears in the list
        12. +
      +
      + +

      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

      + + + + + + + + + + + + + + + + + + + +
      FeatureWhat it improves for screen reader users
      New Issues ExperienceIssues list uses proper <ul> 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 ExperienceFiles 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 PalettePress 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
        2. +
      2. Run the installer - you can install to your computer or run portably
        3. +
      3. After launch, NVDA speaks "NVDA started" when running
        4. +
      +

      Configure NVDA for web browsing

      +
        +
      1. Open NVDA Menu (NVDA+N)
        2. +
      2. Go to Preferences → Settings → Browse Mode
        3. +
      3. Enable "Use screen layout" - this helps with GitHub's landmark navigation
        4. +
      4. Under Document Formatting, disable announcements you find too verbose
        5. +
      + +
        +
      • 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. +
      2. Ensure "Virtual cursor" is active for web browsing
        3. +
      3. In Chrome or Firefox, JAWS should automatically activate Virtual/Browse mode
        4. +
      + +
        +
      • 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. +
      2. Go to Web category → Web Rotor
        3. +
      3. Ensure these are checked: Headings, Landmarks, Links, Buttons, Form Controls, Tables
        4. +
      4. Recommended browser: Safari (best VoiceOver integration on macOS)
        5. +
      5. Firefox on macOS also has good VoiceOver support
        6. +
      +

      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

      + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + +
      BrowserWindowsmacOSNotes
      ChromeRecommendedGoodBest with NVDA and JAWS
      FirefoxRecommendedGoodExcellent accessibility support on all platforms
      EdgeAcceptableAcceptableChromium-based; works well
      SafariNot availableRecommendedBest 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 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
        2. +
      2. Run the installer - default options are correct for most users
        3. +
      3. On the "Adjusting your PATH environment" screen, keep the default: "Git from the command line and also from 3rd-party software"
        4. +
      4. Complete the installer and restart any open terminals
        5. +
      +

      Verify installation (Windows)

      +
        +
      1. Open PowerShell or Command Prompt
        2. +
      2. Type git --version and press Enter
        3. +
      3. You should see a version number such as git version 2.47.0.windows.2 - any version is fine
        4. +
      +

      macOS

      +

      Git is often already present via Xcode Command Line Tools. To check:

      +
        +
      1. Open Terminal (Cmd+Space → type "Terminal")
        2. +
      2. Type git --version and press Enter
        3. +
      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. +
      4. Alternatively, install directly from Git for macOS download page or via Homebrew: brew install git
        5. +
      +

      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
        2. +
      2. Select the download link for your operating system
        3. +
      3. Run the installer with default options
        4. +
      4. Launch VS Code when the installer finishes
        5. +
      +

      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. +
      2. Press Enter to accept, or Tab to the Enable button and press Space
        3. +
      +

      If VS Code did not prompt you automatically, enable it manually:

      +

      Option A - Keyboard shortcut

      +
        +
      1. Press Shift+Alt+F1
        2. +
      2. VS Code toggles Screen Reader Optimized mode immediately
        3. +
      +

      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. +
      2. Type: screen reader - the list filters as you type
        3. +
      3. Arrow down to "Accessibility: Toggle Screen Reader Accessibility Mode"
        4. +
      4. Press Enter
        5. +
      +

      How to confirm it is on

      +
        +
      1. Press Ctrl+Shift+P to open the Command Palette again
        2. +
      2. Type: screen reader optimized
        3. +
      3. If the status bar at the bottom of the window is accessible to you, it will read "Screen Reader Optimized"
        4. +
      4. Alternatively: go to File → Preferences → Settings (Ctrl+,), type screenReaderOptimized in the search box, and verify the checkbox is ticked
        5. +
      +

      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)

      + + + + + + + + + + + + + + + + + + + + + + + + + + + +
      ActionShortcut
      Open Command PaletteCtrl+Shift+P
      Open fileCtrl+P
      Open terminalCtrl+` (backtick)
      Focus Explorer panelCtrl+Shift+E
      Focus editorCtrl+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. +
      2. Open the integrated terminal:
          +
        • Menu: Terminal → New Terminal
          • +
        • Keyboard: Ctrl+` (Windows) or Cmd+` (Mac)
          • +
        +
        3. +
      3. Type the following commands, replacing with your information:
        4. +
      +
      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:

      +
      git config --global --list
      +

      You should see:

      +
      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.

      +

      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. +
      2. Make sure you are signed into GitHub in your web browser
        3. +
      3. Press Ctrl+Shift+I to open Agent mode
          +
        • Your screen reader should announce the chat input field
          • +
        +
        4. +
      4. Type: Hello and press Enter
        5. +
      5. VS Code will automatically sign you into GitHub Copilot using your browser session - no manual sign-in command is needed
        6. +
      6. A response will appear in the chat history above the input field
        7. +
      7. Navigate up with Shift+Tab or Up Arrow to read the response
        8. +
      +
      +

      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. +
      2. Type: GitHub Pull Requests
        3. +
      3. Press Tab to move into the results list
        4. +
      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
          • +
        +
        5. +
      +
      +

      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. +
      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
          • +
        +
        3. +
      +
      +

      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.

      +

      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):

      +
      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:

      +
      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. 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
        • +
      • 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.

      +
      # 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
        • +
      • Excellent for automation and scripting
        • +
      • Very accessible - terminal/command-line interfaces work well with screen readers
        • +
      • Full documentation: 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.

      +
      # Reference examples only
+gh copilot suggest "how do I undo my last commit"
+gh copilot explain "git rebase -i HEAD~3"
      + +

      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:

      + +

      If You Get Stuck

      + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + +
      ProblemWhat to do
      GitHub signup verification puzzle failsRefresh 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 arrivingCheck your spam folder. If using an authenticator app, verify the time on your phone is correct (auto-sync).
      Git not found after installingClose and reopen your terminal. On Windows, restart VS Code. Run git --version to confirm.
      VS Code does not detect screen readerPress Shift+Alt+F1 (Windows) or run "Toggle Screen Reader Mode" from the Command Palette.
      Copilot does not respond in Agent modeVerify you are signed in to GitHub in VS Code. Check that Copilot is enabled in your GitHub account settings.
      Cannot install VS Code extensionsCheck your internet connection. Try installing from the terminal: code --install-extension GitHub.vscode-pull-request-github.
      Everything elseFile a support issue at Community-Access/support/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 a setup support issue - Community-Access/support/issues - we will help you get set up
        2. +
      2. Join Support Hub Discussions - Community-Access/support/discussions - read pinned Start Here guidance and ask follow-up questions
        3. +
      3. Join the GitHub Accessibility Discussions - GitHub Community Accessibility Discussions - the community is helpful and welcoming
        4. +
      +

      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.

      +
      +
      +

      Next: Chapter 01: Choose Your Tools
      Back: Course Guide
      Related appendices: Appendix D: Git Authentication | Appendix Y: Workshop Materials

      + +
      + + + + diff --git a/html/admin/qa-bundle/docs/01-choose-your-tools.html b/html/admin/qa-bundle/docs/01-choose-your-tools.html new file mode 100644 index 00000000..6b7f0b26 --- /dev/null +++ b/html/admin/qa-bundle/docs/01-choose-your-tools.html @@ -0,0 +1,660 @@ + + + + + + + Choose Your Adventure: A Tool Tour - GIT Going with GitHub + + + + + + + + +
      +

      Choose Your Adventure: A Tool Tour

      +
      +

      Related appendices: Appendix G: VS Code Reference | Appendix H: GitHub Desktop | Appendix I: GitHub CLI | Appendix J: Codespaces +Authoritative sources: VS Code Docs: Setup | GitHub Desktop Docs | GitHub CLI 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
        2. +
      2. The Five Paths
        3. +
      3. Path 1: GitHub.com (Browser)
        4. +
      4. Path 2: github.dev (Browser-Based Editor)
        5. +
      5. Path 3: VS Code (Desktop)
        6. +
      6. Path 4: GitHub Desktop
        7. +
      7. Path 5: GitHub CLI
        8. +
      8. Which Path Should I Start With?
        9. +
      9. Your First Confidence Exercise
        10. +
      10. If You Get Stuck
        11. +
      +
      +

      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.

      + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + +
      PathWhat It IsNeeds Installation?Best For
      GitHub.comThe GitHub website in your browserNoIssues, pull requests, repository navigation, code review
      github.devA VS Code editor that runs inside your browserNoEditing files, multi-file changes, quick commits
      VS CodeA desktop code editor with Git built inYesFull development, extensions, terminal, Copilot
      GitHub DesktopA desktop Git client with a visual interfaceYesBranching, committing, and syncing without typing commands
      GitHub CLIA command-line tool called ghYesScripting, 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. 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:

      + + + + + + + + + + + + + + + + + + + + + + + + + + + +
      ActionHow to do it
      Jump to main contentS 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 headingsH key in browse mode
      Jump between landmarksD key in browse mode
      +
      +

      Screen reader tip: Chapter 2 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
        2. +
      2. Choose from Light, Dark, Light high contrast, or Dark high contrast
        3. +
      3. Or select "Sync with system" to follow your OS setting
        4. +
      +

      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

      + + + + + + + + + + + + + + + + + + + +
      MethodSteps
      From any repo pagePress the . (period) key on your keyboard
      From the URL barChange github.com to github.dev in the URL
      From a fileWhile 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. Installation is covered in Chapter 0, Step 6.

      +

      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 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:
        • +
      + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + +
      PanelShortcut (Windows/Linux)Shortcut (macOS)
      File ExplorerCtrl+Shift+ECmd+Shift+E
      Source ControlCtrl+Shift+GCmd+Shift+G
      TerminalCtrl+`Cmd+`
      Command PaletteCtrl+Shift+PCmd+Shift+P
      ExtensionsCtrl+Shift+XCmd+Shift+X
      Problems panelCtrl+Shift+MCmd+Shift+M
      +
      +

      Deep dive: Chapter 11 covers the VS Code interface in detail. Chapter 12 covers accessibility-specific configuration. Appendix G 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. See Appendix H 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 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 levelRecommended starting pathWhy
      New to GitHub, new to codingGitHub.com (browser)Everything happens in one window. No installs. Clear, labeled interface.
      Some web experience, want to edit filesGitHub.com + github.devUse the browser for navigation, press . to edit when needed.
      Already use VS CodeVS Code + GitHub.comEdit 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 pathDay 2 additionHow they work together
      GitHub.com onlyAdd VS CodeClone the repo, edit locally, push changes, review PRs in the browser
      GitHub.com + github.devAdd VS CodeTransition from browser editing to local editing with full tool support
      VS Code alreadyAdd 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.
        2. +
      2. The README is displayed below the file list on the repository's home page.
        3. +
      3. Screen reader users: press H to navigate headings. The README's first heading announces the repository name.
        4. +
      4. You are done when you can read the first paragraph of the README.
        5. +
      +

      Path 2: github.dev

      +
        +
      1. Go to github.dev/Community-Access/git-going-with-github.
        2. +
      2. The file explorer opens on the left. Press Ctrl+Shift+E (or Cmd+Shift+E) to focus it.
        3. +
      3. Navigate to README.md and press Enter to open it in a tab.
        4. +
      4. You are done when the file content appears in the editor.
        5. +
      +

      Path 3: VS Code (if set up)

      +
        +
      1. Open VS Code.
        2. +
      2. Open the command palette: Ctrl+Shift+P (or Cmd+Shift+P).
        3. +
      3. Type "Git: Clone" and press Enter.
        4. +
      4. Paste the URL: https://github.com/Community-Access/git-going-with-github.git
        5. +
      5. Choose a folder to clone into and wait for the download.
        6. +
      6. When it finishes, VS Code offers to open the repository. Accept.
        7. +
      7. Open the file explorer (Ctrl+Shift+E) and select README.md.
        8. +
      8. You are done when the file content appears in the editor.
        9. +
      +

      Path 4: GitHub Desktop

      +
        +
      1. Open GitHub Desktop.
        2. +
      2. Go to File, then Clone repository (or press Ctrl+Shift+O).
        3. +
      3. Paste the URL: https://github.com/Community-Access/git-going-with-github.git
        4. +
      4. Choose a local path and click Clone.
        5. +
      5. Once cloned, the repository appears in GitHub Desktop. Click "Open in Visual Studio Code" (or your preferred editor) to read the README.
        6. +
      +

      Path 5: GitHub CLI

      +
        +
      1. Open your terminal.
        2. +
      2. Run:
        3. +
      +
      gh repo clone Community-Access/git-going-with-github
+cd learning-room
      +
        +
      1. Open the README in your preferred way:
        2. +
      +
      cat README.md       # print to terminal
+code README.md      # open in VS Code
      +
        +
      1. You are done when you can read the first paragraph.
        2. +
      +

      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

      + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + +
      ProblemWhat to try
      Cannot sign in to GitHub.comVerify your email and password. Check Chapter 0, Step 1.
      github.dev does not openEnsure you are signed in to GitHub.com first. Some browsers block the redirect -- try Chrome or Firefox.
      VS Code is not installedFollow Chapter 0, Step 6.
      Git clone failsCheck your internet connection. Verify Git is installed: run git --version in a terminal. See Appendix D for authentication issues.
      Screen reader does not announce page contentEnsure browse mode is active (NVDA: press Escape; JAWS: press Num Pad Plus). Maximize the browser window.
      Not sure which path to chooseStart with GitHub.com in your browser. You can always add more tools later.
      GitHub Desktop cannot find the repoVerify 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.
      +
      +

      Next Step: Start your learning journey with Chapter 02: Understanding GitHub.

      +
      +
      +

      Next: Chapter 02: Understanding GitHub
      Back: Chapter 00: Pre-Workshop Setup
      Related appendices: Appendix H: GitHub Desktop | Appendix I: GitHub CLI | Appendix J: Codespaces

      + +
      + + + + diff --git a/html/admin/qa-bundle/docs/02-understanding-github.html b/html/admin/qa-bundle/docs/02-understanding-github.html new file mode 100644 index 00000000..3cbfe183 --- /dev/null +++ b/html/admin/qa-bundle/docs/02-understanding-github.html @@ -0,0 +1,875 @@ + + + + + + + Understanding GitHub's Web Structure - GIT Going with GitHub + + + + + + + + +
      +

      Understanding GitHub's Web Structure

      +
      +

      Listen to Episode 2: Understanding GitHub on the Web - 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 B: Screen Reader Cheat Sheet +Authoritative sources: GitHub Docs: About GitHub | GitHub Accessibility 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 and Chapter 04. Read this chapter first to build the mental model, then navigate repositories with confidence.

      +
      +
        +
      1. GitHub's Three-Level Structure
        2. +
      2. What Is Always on Every GitHub Page
        3. +
      3. How to Tell Where You Are
        4. +
      4. The Five Key Page Types
        5. +
      5. Visual Map of a Repository Page
        6. +
      6. Screen Reader Orientation Sequence
        7. +
      7. Landmark Structure by Page Type
        8. +
      8. GitHub's Heading Hierarchy in Practice
        9. +
      9. How GitHub's Layout Changes by Viewport
        10. +
      10. The Mental Model - Building Your Internal Map
        11. +
      +
      +

      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.

      +
          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):

      + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + +
      ElementWhat It IsHow to Reach It
      GitHub logo / home linkReturns to your personal feedFirst link in "Navigation Menu" landmark
      Search barGlobal search across all of GitHubS or / shortcut; or D → Navigation Menu → K to search
      Copilot iconQuick access to GitHub Copilot chatK navigation from search bar
      Pull RequestsYour PRs across all reposK navigation
      IssuesYour issues across all reposK navigation
      Notifications (bell)Your notification inboxG then N shortcut
      Profile avatarAccount menu, settings, sign outK 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 patternWhere you are
      github.comYour personal feed / home
      github.com/usernameA user profile page
      github.com/orgAn organization profile
      github.com/owner/repoRepository home page (Code tab)
      github.com/owner/repo/issuesIssues list
      github.com/owner/repo/issues/42A specific issue (number 42)
      github.com/owner/repo/pull/7A specific pull request (number 7)
      github.com/owner/repo/tree/main/docsA folder inside the repo
      github.com/owner/repo/blob/main/README.mdA specific file
      github.com/owner/repo/commit/a1b2c3dA specific commit
      github.com/settings/accessibilityYour accessibility settings
      github.com/notificationsYour 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 typeTitle format
      Repository homeowner/repo: Short description - GitHub
      Issues listIssues · owner/repo
      Specific issueIssue title · Issue #42 · owner/repo
      Pull requestPR title · Pull Request #7 · owner/repo
      Your notificationsNotifications - GitHub
      SettingsCategory - 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 hearYou are on
      owner/repo-nameRepository home page
      IssuesIssues list
      The issue titleIssue detail page
      The PR titlePull request detail page
      Your usernameYour profile page
      A settings category nameA 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 defines every term used in this course. Appendix B: Screen Reader Cheat Sheet 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. +
      2. Global nav bar (top strip) - GitHub logo, search box, bells/icons
        3. +
      3. Repo tabs (below global nav, visible only inside a repo) - Code, Issues, Pull Requests, etc.
        4. +
      4. H1 heading - tells you exactly what page you're on (repo name / "Issues" / issue title / PR title)
        5. +
      5. Main content area - file tree, issue list, PR diff, etc.
        6. +
      +

      That's your visual map. Click anything visible to navigate.

      +
      + +
      +Screen reader users (NVDA / JAWS) - 10-second orientation sequence + +
      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 + +
      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 MenuGlobal nav bar - logo, search, PRs, Issues, notifications, avatar
      Repository navigationCode, Issues, PRs, Actions, etc. tabs
      MainEverything below the tabs - file tree, README
      Repository files navigationThe rendered README specifically
      +

      Issues list page landmarks

      + + + + + + + + + + + + + + + + + + + + + + + + + + + +
      LandmarkContains
      Navigation MenuGlobal nav
      Repository navigationRepo tabs
      MainFilter bar + issue list
      Search Results ListThe actual list of issues
      PaginationNext/previous page buttons
      +

      Issue detail page landmarks

      + + + + + + + + + + + + + + + + + + + + + + + +
      LandmarkContains
      Navigation MenuGlobal nav
      Repository navigationRepo tabs
      MainIssue title, description, comments, sidebar
      Add a commentThe reply text area and Submit button
      +

      Pull request Conversation tab landmarks

      + + + + + + + + + + + + + + + + + + + + + + + + + + + +
      LandmarkContains
      Navigation MenuGlobal nav
      Repository navigationRepo tabs
      Pull request tabsConversation, Commits, Files changed tab links
      MainPR description, review threads, merge section
      Add a commentThe reply box
      +

      Pull request Files Changed tab landmarks

      + + + + + + + + + + + + + + + + + + + + + + + +
      LandmarkContains
      Navigation MenuGlobal nav
      Pull request tabsTab links
      MainFile 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

      +
      H1: owner/repo-name
+  H2: About (sidebar section)
+  H2: Releases
+  H2: (README sections - whatever the author wrote)
      +

      Issues list

      +
      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

      +
      H1: Issue title
+  H2: Description
+  H2: Activity
+    H3: Each comment header (author + timestamp)
      +

      Pull request detail - Conversation tab

      +
      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

      +
      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:

      +
      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. +
      2. Press D - hear the landmarks - know what rooms are available
        3. +
      3. Press NVDA+F7 - see the full outline - know what's in the room
        4. +
      +

      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 - 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. +
      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. +
      3. Press 2 - you jump to the first section heading. Press 2 again to scan the page structure.
        4. +
      4. Press H three times - you're moving through headings at any level. You're reading the outline.
        5. +
      +

      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

      + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + +
      ProblemWhat to do
      Screen reader says nothing when pressing 1Ensure 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 expectedGitHub 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 brokenSome GitHub features require JavaScript. Ensure your browser has JavaScript enabled and try refreshing with Ctrl+Shift+R.
      Cannot find the repository navigation tabsPress D until you hear "Repository navigation" then press K or Tab to find Code, Issues, Pull Requests tabs.
      Everything elsePost 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 rightCompare your work against the Challenge 1 reference solution. 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.

      +
      +
      +

      Next: Chapter 03: Navigating Repositories
      Back: Chapter 01: Choose Your Tools
      Related appendices: Appendix A: Glossary | Appendix B: Screen Reader Cheat Sheet

      + +
      + + + + diff --git a/html/admin/qa-bundle/docs/03-navigating-repositories.html b/html/admin/qa-bundle/docs/03-navigating-repositories.html new file mode 100644 index 00000000..fed3c7bc --- /dev/null +++ b/html/admin/qa-bundle/docs/03-navigating-repositories.html @@ -0,0 +1,976 @@ + + + + + + + Navigating Repositories - GIT Going with GitHub + + + + + + + + +
      +

      Navigating Repositories

      +
      +

      Listen to Episode 3: Navigating Repositories - 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 B: Screen Reader Cheat Sheet +Authoritative sources: GitHub Docs: About repositories | GitHub Accessibility Guide: Repositories

      +
      +

      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. 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. +
      2. Practice orientation (1, D, heading list).
        3. +
      3. Confirm readiness with a peer or facilitator.
        4. +
      4. Move to Chapter 4 for Learning Room orientation, then Chapter 5 for issue-based, traceable challenges.
        5. +
      +

      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.

      + + + + + + + + + + + + + + + + + + + + + + + + + + + + +
      CardWho it helpsWhat it covers
      Visual / mouseSighted users navigating with a mouse or trackpadClick targets, visual cues, layout orientation
      Low visionUsers with magnification, zoom, or high-contrast themesZoom-friendly navigation, locating controls at high magnification
      Screen reader (NVDA / JAWS)Screen reader users on WindowsKeystroke sequences, Focus and Browse mode, landmark navigation
      Screen reader (VoiceOver)Screen reader users on macOSVO 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. +
      2. First heading (1 key) will navigate to the repo name: "owner/repo-name"
        3. +
      3. The tab bar is a landmark labeled "Repository navigation"
        4. +
      +

      Orientation sequence (do this on every new repo)

      +
      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.

      +
      + +

      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. +
      2. Press K or Tab to navigate between the tab links
        3. +
      +
      + +
      +Screen reader users (VoiceOver) + +
        +
      1. VO+U → Landmarks rotor → navigate to "Repository navigation"
        2. +
      2. VO+Right to move through items in the landmark
        3. +
      +
      + +

      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 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. +
      2. Message - the most recent commit message that changed this file
        3. +
      3. Age - how long ago that commit happened
        4. +
      + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + +
      GoalKeys (NVDA/JAWS)Keys (VoiceOver)
      Move down one row (next file)Ctrl+Alt+↓VO+Shift+↓
      Move up one rowCtrl+Alt+↑VO+Shift+↑
      Move right one columnCtrl+Alt+→VO+Shift+→
      Move left one columnCtrl+Alt+←VO+Shift+←
      Open a file or folderEnter (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. +
      2. The branch button reads: “[branch-name] branch” (e.g., “main branch”)
        3. +
      3. Press Enter to open the dropdown
        4. +
      +
      + +
      +Screen reader users (VoiceOver) + +
        +
      1. Tab to the branch button (it will be labeled with the current branch name)
        2. +
      2. VO+Space to open
        3. +
      +
      + +

      Inside the branch dropdown

      +
      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. +
      2. Inside the dropdown, navigate to the tabs control at the top (reads as "Branches tab" and "Tags tab")
        3. +
      3. Use ←/→ to switch to the Tags tab
        4. +
      4. Tab to move to the tags list
        5. +
      5. Navigate with ↑/↓ and press Enter to select a tag
        6. +
      +

      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. +
      2. A popover opens showing HTTPS, SSH, and GitHub CLI tabs
        3. +
      3. Click the HTTPS tab (default) and click the copy icon next to the URL
        4. +
      4. Open your terminal, cd to where you want the folder, and run git clone <pasted-URL>
        5. +
      5. Alternatively, click Download ZIP to get a one-time archive without Git
        6. +
      +
      + +
      +Screen reader users + +
        +
      1. Press 1 or Shift+1 to navigate to the repository h1 heading
        2. +
      2. Press B to navigate to the next button - look for the “Code” button
        3. +
      3. Press Enter or Space to open the Code flyout panel
        4. +
      4. The flyout has tabs: HTTPS, SSH, GitHub CLI
        5. +
      5. Tab to the HTTPS tab or SSH tab according to your preference
        6. +
      6. Tab to the “Copy url to clipboard” button and press Enter
        7. +
      7. The URL is now in your clipboard - paste it into VS Code or your terminal
        8. +
      +

      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:

      +
      # 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

      +
      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 and authenticate with gh auth login. See Appendix D 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. +
      2. Copy the HTTPS URL.
        3. +
      3. You will paste this into your local tool of choice below.
        4. +
      +

      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. +
      2. Paste the HTTPS URL and choose a local folder.
        3. +
      3. Click Open when prompted.
        4. +
      +

      GitHub Desktop:

      +
        +
      1. File > Clone Repository (or Ctrl+Shift+O).
        2. +
      2. Paste the URL or select from your GitHub account list.
        3. +
      3. Choose a local path and click Clone.
        4. +
      +

      Git CLI (terminal):

      +
      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.

      + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + +
      DimensionForkCloneBranch
      What it createsA new repository on GitHub under your accountA local copy of a repository on your computerA named pointer to a line of commits within the same repository
      Where it livesOn GitHub (your account)On your local machineInside any repository (local or remote)
      Relationship to originalLinked (GitHub tracks the "parent" repo)Independent copy (but has origin remote pointing to GitHub)Part of the same repository
      When to use itContributing to a repo where you do not have write access (most open source)Working locally with Git and VS CodeCreating an isolated workspace for a feature, fix, or experiment
      How to contribute backOpen a pull request from your fork to the original (upstream) repoPush your branch to the remote, then open a PROpen a pull request from your branch to main
      Workshop usageNot 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.

      +

      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. +
      2. Continue pressing L until you find the Watch button (reads as “Watch this repository”)
        3. +
      3. Press Enter to open the subscription submenu
        4. +
      4. Press ↑/↓ to browse options: Participating, All Activity, Ignore, Custom
        5. +
      5. Press Enter to confirm
        6. +
      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.
        7. +
      +
      + +

      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. +
      2. Press I to navigate individual list items until you find “Fork your own copy”
        3. +
      3. Press Enter to start the fork workflow
        4. +
      4. The fork creation page lets you choose the owner and repository name
        5. +
      5. Tab to “Create fork” and press Enter
        6. +
      +
      + +

      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. +
      2. Press I to navigate individual list items until you find “Star this repository”
        3. +
      3. Press Enter or Space to star
        4. +
      4. The button text changes to “Unstar” on the next focus
        5. +
      +
      +

      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

      +
      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.

      + + + + + + + + + + + + + + + + + + + +
      GoalKeys
      Read the file content↓ to read line by line
      Jump to a specific lineOpen Raw view (R button), then use browser Ctrl+F
      View in Focus ModeNVDA+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. +
      2. Click the pencil icon (Edit file) in the top-right of the file content area
        3. +
      3. The file opens in a web editor - click in the content area and edit
        4. +
      4. When done, scroll down to “Commit changes”, type a commit message, and click the green Commit changes button
        5. +
      5. Choose “Commit directly to main” (or your branch) and confirm
        6. +
      +
      + +
      +Screen reader users + +
        +
      1. Open the file you want to edit
        2. +
      2. Press K to navigate links until you find the “Edit file” link (may be labeled with a pencil icon description)
        3. +
      3. Press Enter to activate the link - the page opens in edit mode with a code editor textarea
        4. +
      4. Switch to Focus Mode: press NVDA+Space (NVDA) or Insert+Z (JAWS)
        5. +
      5. Make your changes using standard text editing keys
        6. +
      6. When done, press Escape to exit the textarea
        7. +
      7. Press Shift+Tab to navigate backwards to the “Commit Changes” button
        8. +
      8. Press Enter to open the commit dialog
        9. +
      9. Type your commit message in the dialog, then Tab to the confirm button and press Enter
        10. +
      +
      +

      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.

      + +
        +
      1. From a file page, activate the "Blame" button
        2. +
      2. The page reloads in Blame view
        3. +
      3. The content is a table: left column = commit info (who, when, message), right column = the line of code
        4. +
      +
      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

      +
      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
        • +
      +
      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. +
      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. +
      3. Type the filename or partial path
        4. +
      4. Results appear as a dropdown - use ↓ to navigate, Enter to open
        5. +
      +

      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).

      + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + +
      ShortcutWhat it doesWhen you need it
      ?Show all shortcuts for this pageAny time - get the full context-specific list
      G CJump to the Code tabYou're on Issues or PRs and want the file tree
      G IJump to the Issues tabYou're browsing code and spot a bug to report
      G PJump to the Pull Requests tabYou want to review open PRs
      G AJump to Actions / workflow runsYou want to check CI status
      G GJump to DiscussionsYou want to participate in project conversations
      G WJump to WikiYou 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.

      +

      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
        • +
      + +

      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. +
      2. Look for a heading "About" in the sidebar
        3. +
      3. 2 or H to jump to that "About" heading
        4. +
      4. Then ↓ to read the description, URL, and topics
        5. +
      +

      Practical Scenarios

      +

      Scenario A: "I want to find out what this project does"

      +
        +
      1. Navigate to the repo URL
        2. +
      2. Press 1 - hear the repo name
        3. +
      3. ↓ - read the description (announced as a paragraph after the heading)
        4. +
      4. Navigate to README: D → "Repository files navigation" → H within the README
        5. +
      +

      Scenario B: "I want to find a good file to edit"

      +
        +
      1. Open the files table with T
        2. +
      2. Navigate rows with Ctrl+Alt+↓
        3. +
      3. Move right with Ctrl+Alt+→ to read the commit message (what's been changing recently)
        4. +
      4. When found, press Enter on the Name column to open the file
        5. +
      +

      Scenario C: "I want to know who has been working on this file recently"

      +
        +
      1. Open the file
        2. +
      2. Activate the "Blame" button (B from the Repository files navigation landmark)
        3. +
      3. Navigate the blame table to see authors
        4. +
      +

      Scenario D: "I want to understand what changed in the last release"

      +
        +
      1. Navigate to the sidebar "Releases" section (H or 2)
        2. +
      2. Activate the latest release link
        3. +
      3. Read the release notes (rendered Markdown with headings and lists)
        4. +
      +

      Scenario E: "I want to contribute - where do I start?"

      +
        +
      1. Navigate to the Code tab
        2. +
      2. Look for CONTRIBUTING.md in the files table
        3. +
      3. Open it and read the contributing guidelines
        4. +
      4. Then go to Issues tab and filter by good first issue
        5. +
      +

      If You Get Stuck

      + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + +
      ProblemWhat to do
      Clone fails with "authentication required"You need to sign in. See Appendix D for HTTPS authentication setup.
      Cannot find the Code button for cloningPress 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 openEnsure 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 expectBy 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 workThese require two separate key presses (G, release, then I or P), not simultaneous. Ensure Focus Mode is active first.
      Everything elsePost 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 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. +
      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. +
      3. Pull Requests tab - Press G then P. Are there any open PRs?
        4. +
      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. +
      5. Read the README - Press 1 to find the page title, then 2 to scan sections.
        6. +
      +

      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 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 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 to understand where we'll be practicing our new skills.

      +
      +
      +

      Next: Chapter 04: The Learning Room
      Back: Chapter 02: Understanding GitHub
      Related appendices: Appendix B: Screen Reader Cheat Sheet

      + +
      + + + + diff --git a/html/admin/qa-bundle/docs/04-the-learning-room.html b/html/admin/qa-bundle/docs/04-the-learning-room.html new file mode 100644 index 00000000..9bef42b6 --- /dev/null +++ b/html/admin/qa-bundle/docs/04-the-learning-room.html @@ -0,0 +1,1044 @@ + + + + + + + The Learning Room: Your Personal Practice Repository - GIT Going with GitHub + + + + + + + + +
      +

      The Learning Room: Your Personal Practice Repository

      +
      +

      Listen to Episode 4: The Learning Room - 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 C: Markdown Reference +Authoritative sources: GitHub Docs: About README files | GitHub Docs: 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 repository into the workshop classroom organization as <workshop-org>/learning-room-<your-username>. 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)
        • +
      • 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/<random-id>. If you do not have it, ask in chat or DM the facilitator.
        • +
      +
      + +
        +
      1. In the same browser where you are signed into GitHub, open the Day 1 assignment link the facilitator shared.
        2. +
      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. +
      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.
        4. +
      +

      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. +
      2. Activate the link or button next to your name.
        3. +
      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.
        4. +
      +

      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. +
      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. +
      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/<workshop-org>/learning-room-<your-username>.
        4. +
      +
      +

      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 <workshop-org>/learning-room-<your-username>.
        2. +
      2. Verify three things on this page:
          +
        • The repo name in the heading matches learning-room-<your-username>.
          • +
        • 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. +
      3. Bookmark this page. You will return here for every Day 1 challenge.
        4. +
      +

      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. +
      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. +
      3. Open Challenge 1. Read the issue body -- it tells you what to do, where to find evidence, and how to submit completion.
        4. +
      +
      +

      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. +
      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.
        3. +
      +
      +

      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 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. +
      2. Explain the flow: issue -> branch -> pull request -> review -> merge.
        3. +
      3. Identify where Aria bot feedback appears on a PR (the Conversation tab).
        4. +
      +

      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)

      + +

      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

      + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + +
      StepGitHub Skills (optional)Your Learning Room (required)
      1Create a branch in a Skills repoCreate a branch in your Learning Room
      2Open a PROpen a PR
      3Get instant bot feedback from MonaGet instant bot feedback from Aria
      4Mona verifies your stepAria validates structure; you self-merge or peer-review
      5Next Skills step unlockedClosing 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/<your-github-username> (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/<username> 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:

      +
      git checkout learn/<your-github-username>
      +
        +
      1. Create the branch on GitHub.com (Challenge 4) or locally with git checkout -b learn/<username> from main
        2. +
      2. Make your changes and commit them to the branch
        3. +
      3. Push the branch to GitHub if you created it locally
        4. +
      4. Open a pull request from learn/<username> -> main (Challenge 6)
        5. +
      +
      +

      Which branch do I use and when?

      + + + + + + + + + + + + + + + + + + + + + + + + + + + + +
      ChapterBranch needed?What to use
      Chapter 5 (Issues)NoWork happens in issue threads directly. No branch or file editing required.
      Chapter 6 (PRs, web editor)YesCreate learn/<username> from main (Challenge 4) and edit on it.
      Chapter 6 (PRs, local clone)Yes, create manuallygit checkout -b learn/<username> from main.
      Chapter 14+ (Local Git)YesReuse learn/<username>, or create additional fix/<short-description> branches from main for new work.
      +

      Summary: Chapter 5 needs no branch. Chapters 6-7 use the same learn/<username> 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/<username>), and press Enter when it appears
        • +
      • In VS Code's terminal, type git checkout learn/<your-github-username> (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/<username>, 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/<username> (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. +
      2. Type learn to filter, then select learn/<username>.
        3. +
      +

      github.dev (web editor):

      +
        +
      1. Click the branch name in the bottom-left status bar.
        2. +
      2. Select your learn/<username> branch from the list.
        3. +
      +

      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. +
      2. Select origin/learn/<username> from the branch list.
        3. +
      +

      GitHub Desktop:

      +
        +
      1. Click the Current Branch dropdown at the top.
        2. +
      2. Type learn to filter, then select learn/<username>.
        3. +
      +

      Git CLI (terminal):

      +
      git checkout learn/<username>
      +
      +

      The Practice Files: What You Will Work On

      +
      +

      See also: Appendix C: Markdown Reference 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:

      + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + +
      LevelChallengesRequirement
      Explorer (01-03)Scavenger hunt, first issue, join conversationGetting started
      Contributor (04-07)Branch out, make your mark, first PR, merge conflict3+ challenges
      Collaborator (08-09)Culture reflection, merge day7+ challenges
      Operator (10-11)Go local, Day 2 PR9+ challenges
      Reviewer (12-14)Code review, Copilot, issue template11+ challenges
      Agent Navigator (15-16)Agents, capstone14+ challenges
      Bonus (A-E)Accessibility audit, mentor, cross-repo, workflow, docsOptional
      +

      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. +
      2. Opens docs/welcome.md and edits the three [TODO] sections
        3. +
      3. Commits to a new branch: fix/studentA-issue12
        4. +

      4. Opens a pull request with description:

        +
        ## 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. +
      5. Submits the PR
        6. +
      +

      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. +
      2. They add each of you as a collaborator on the other's Learning Room repo.
        3. +
      3. Each of you receives a notification: "You have been added as a collaborator."
        4. +
      4. You can now read the other person's PRs, leave comments, request changes, and approve.
        5. +
      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.
        6. +
      +

      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. +
      2. Navigates to the PR in your Learning Room repo (they have collaborator access)
        3. +
      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. +
      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. +
      5. Submits review: Approve (or Request Changes if a [TODO] marker was missed)
        6. +
      +

      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. +
      2. Talks to the reviewer if something is unclear
        3. +
      3. Makes changes based on feedback
        4. +
      4. Pushes new commits to the same branch
        5. +
      5. Re-addresses the feedback
        6. +
      +

      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

      + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + +
      WhatWhereWho Sees It
      Your open PRsPull Requests tab in your repoYou, the facilitators, and any peers added as collaborators
      PR description & changesPR page in your repoSame as above
      Aria's bot feedbackPR commentsSame as above
      Peer review commentsPR commentsSame as above
      Reviewer assignmentsPR sidebar "Reviewers"Same as above
      Progression bot's next-challenge issueIssues tab in your repoSame as above
      Your review requests for someone else's PRYour notification inboxYou 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. +
      2. Shared Review Responsibility - You review each other's work
        3. +
      3. Collaborative Challenges - Optional group exercises
        4. +
      4. Peer Support - Tag each other with questions
        5. +
      +

      Example

      +
      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

      + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + +
      AspectGitHub Skills (Your Account)Your Learning Room (Classroom)
      RepoYour personal copy of a Skills repoYour private copy of learning-room-template
      BotMona (GitHub)Aria (PR validation) and the Student Progression bot
      ReviewerMona (auto)You (self-merge) or a peer paired by your facilitator
      VisibilityPrivate to you (unless you make it public)Private to you and the workshop organization
      PaceSelf-directedSelf-paced, anchored by the workshop schedule
      PurposeIndividual skill buildingEnd-to-end practice of the full real-world workflow
      FeedbackInstant, next-step onlyBot feedback on every push plus optional peer review
      CompletionBadge on your profileClosing the issue auto-creates the next challenge
      CommunityYou aloneYou, 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. +
      2. Click the Pull Requests tab
        3. +
      3. Click the Filters dropdown -> "Review requested" -> your username
        4. +
      4. Click any PR title to open it
        5. +
      +
      + +
      +Screen reader users (NVDA / JAWS) + +
      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) + +
      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) + +
      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) + +
      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. +
      2. Type your review comment
        3. +
      3. Click "Review Changes" (top-right of the Files Changed tab, or at the bottom of the PR page)
        4. +
      4. Select your review type: Comment / Approve / Request changes
        5. +
      5. Click "Submit review"
        6. +
      +
      + +
      +Screen reader users (NVDA / JAWS) + +
      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) + +
      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. +
      2. Read all comments and bot feedback
        3. +
      3. Click in the comment box to reply
        4. +
      4. Push your fixes to the same branch
        5. +
      5. Comment: "Updates pushed, ready for review"
        6. +
      +
      + +
      +Screen reader users (NVDA / JAWS) + +
      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) + +
      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

      + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + +
      ProblemWhat to do
      Cannot find your learn/<username> branchIf 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 branchMain is protected. You need to push to your learn/<username> branch: git checkout learn/<your-username> then push again.
      I want to see another student's PRAsk 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 markersVerify 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 mainDo not panic. See the failsafe instructions in Chapter 13 or ask a facilitator.
      Everything elsePost 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 rightCompare your work against the Challenge 4 reference solution. Any branch with any name is a success.
      I finished Challenge 5 but I am not sure I did it rightCompare your work against the Challenge 5 reference solution. 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 and complete Challenge 1: Find Your Way Around, then return for Chapter 05: Working with Issues.

      +
      +
      +

      Next: Chapter 05: Working with Issues
      Back: Chapter 03: Navigating Repositories
      Related appendices: Appendix A: Glossary

      + +
      + + + + diff --git a/html/admin/qa-bundle/docs/05-working-with-issues.html b/html/admin/qa-bundle/docs/05-working-with-issues.html new file mode 100644 index 00000000..1459676f --- /dev/null +++ b/html/admin/qa-bundle/docs/05-working-with-issues.html @@ -0,0 +1,1590 @@ + + + + + + + Working with Issues - GIT Going with GitHub + + + + + + + + +
      +

      Working with Issues

      +
      +

      Listen to Episode 5: Working with Issues - a conversational audio overview of this chapter. Listen before reading to preview the concepts, or after to reinforce what you learned.

      +
      +
      +

      Related appendices: Appendix N: Advanced Search | Appendix V: GitHub Mobile | Appendix B: Screen Reader Cheat Sheet +Authoritative sources: GitHub Docs: About issues | GitHub Accessibility Guide: Issues

      +
      +

      Filing, Managing, and Participating in GitHub Issues

      +
      +

      Issues are where open source collaboration begins. This guide covers everything from finding the right issue to file a perfect bug report - all with your keyboard and screen reader.

      +

      Official GitHub Accessibility Guide: GitHub publishes an NVDA-focused guide for working with issues using a screen reader at Using GitHub Issues with a Screen Reader. This chapter covers the same material with additional perspectives (VoiceOver, low vision, CLI) and workshop-specific challenges. Use the official guide as a companion reference.

      +

      Screen reader note - New Issues Experience: This guide uses GitHub's improved Issues experience, which provides better ARIA landmark structure and live-region announcements for screen readers. This feature may already be active for your account - it has been broadly rolled out and may no longer appear as a Feature Preview toggle at all.

      +

      To verify: Activate the User Menu button (top-right of any GitHub page) → activate "Feature preview" → scan the list for "New Issues Experience":

      +
        +
      • If listed and the toggle announces "Pressed" (or "Disable") - already enabled, no action needed
        • +
      • If listed but not Pressed (or "Enable") - activate the toggle to enable it
        • +
      • If not listed at all - the feature has graduated to the standard interface; it is active automatically
        • +
      +

      Full step-by-step instructions with per-screen-reader commands are in Pre-Workshop Setup, Step 4.

      +

      Browse vs Focus Mode (NVDA): Toggle between modes with NVDA+Space (NVDA key = Insert or Caps Lock). Use Browse Mode (the default) for reading lists, headings, and issue content. Switch to Focus Mode when typing in text fields and search boxes. Use NVDA+F7 at any time to open a list of all headings, links, form fields, buttons, and landmarks on the page - this is your orientation tool.

      +
      +

      Workshop Recommendation (Chapter 5 / Challenges 2-3)

      +

      Chapter 5 is the first issue-based challenge chapter with short, confidence-building tasks. It supports Challenge 2 (File Your First Issue) and Challenge 3 (Join the Conversation).

      +
        +
      • Challenge count: 2 core challenges plus one optional extension
        • +
      • Time per challenge: under 10 minutes
        • +
      • Evidence: issue comments and issue metadata
        • +
      • Pattern: claim -> act -> confirm
        • +
      +

      Chapter 5 Challenge Set

      +
        +
      1. Create your first issue - file a new issue with a clear title and description.
        2. +
      2. Comment and @mention - leave a comment on a classmate's issue and tag them with an @mention.
        3. +
      3. Optional extension: Add a sub-issue - break a larger issue into smaller, trackable pieces if your repository has sub-issues enabled.
        4. +
      +
      +

      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. +
      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. +
      3. Activate the New issue button.
        4. +
      4. If a template picker appears, select Open a blank issue (or choose a template if one fits).
        5. +
      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. +
      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. +
      7. Activate Submit new issue.
        8. +
      8. Copy the issue URL or note the issue number (for example, #150). You will reference this later.
        9. +
      +

      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. +
      2. Find an issue created by a classmate (look for issues from Challenge 4.1, or browse recent open issues).
        3. +
      3. Open the issue by activating its title link.
        4. +
      4. Read the issue description to understand what they reported.
        5. +
      5. Scroll to the comment box at the bottom of the issue.
        6. +
      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. +
      7. Activate the Comment button (or press Ctrl+Enter).
        8. +
      +

      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. +
      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. +
      3. Activate Add sub-issue and choose Create new sub-issue.
        4. +
      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. +
      5. Add a short description and activate Create.
        6. +
      6. The sub-issue now appears nested under the parent issue with a progress indicator.
        7. +
      +

      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:

      +
      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. +
      2. @mention not working? Make sure you type @ immediately followed by the username with no space.
        3. +
      3. Sub-issue option not visible? Ask a facilitator - the feature may need to be enabled for the repository.
        4. +
      4. Still stuck? Ask a facilitator for a direct issue link.
        5. +
      5. Finished but not sure you did it right? Compare your work against the Challenge 2 reference solution or the Challenge 3 reference solution.
        6. +
      +

      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. +
      2. Practice communication in public issue threads (@mention a peer).
        3. +
      3. Organize work into smaller pieces (sub-issues).
        4. +
      4. Leave clear evidence in the issue timeline.
        5. +
      5. Build momentum for file editing and PR work in Chapter 6.
        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.

      + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + +
      CardWho it helpsWhat it covers
      Visual / mouseSighted users navigating with a mouse or trackpadClick targets, visual cues, layout orientation
      Low visionUsers with magnification, zoom, or high-contrast themesZoom-friendly navigation, finding controls at high magnification, high contrast visibility
      NVDA / JAWS (Windows)Screen reader users on WindowsKeystroke sequences, Focus and Browse mode, landmark navigation
      VoiceOver (macOS)Screen reader users on macOSVO key sequences, rotor usage, interaction model
      CLI (gh)Terminal users on any platformGitHub 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.

      +

      Verify your clone is ready:

      +
      cd ~/Documents/learning-room   # or wherever you cloned it
+git status                      # should show "On branch main"
      +

      Common issue commands from your local terminal:

      +
      # 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.

      +
      + +

      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. +
      2. Press K or Tab to move through the tab links
        3. +
      3. Find "Issues" - it will be announced with the count: "Issues, 14 open"
        4. +
      4. Press Enter to open the Issues tab
        5. +
      +
      + +
      +Screen reader users (VoiceOver - macOS) + +
        +
      1. VO+U → Landmarks → navigate to "Repository navigation"
        2. +
      2. VO+Right or Quick Nav K to move through tab links
        3. +
      3. Find "Issues" - VoiceOver announces the count: "Issues 14"
        4. +
      4. VO+Space to activate the Issues tab
        5. +
      +
      + +
      +GitHub CLI (gh) alternative + +

      List open issues directly from your terminal:

      +
      gh issue list
      +

      Filter by label, assignee, or state:

      +
      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 and authenticate with gh auth login. See Appendix D 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. +
      2. Press 3 (h3) to navigate by issue titles - each issue title is an h3 link
        3. +
      3. Press I to move between list items if you want more detail per item
        4. +
      4. Press Enter on a title to open that issue
        5. +
      +
      + +
      +Screen reader users (VoiceOver) + +
        +
      1. VO+U → Landmarks → navigate to “Search Results List”
        2. +
      2. VO+Down to read through items
        3. +
      3. H (with Quick Nav on) or VO+U → Headings to jump by issue title
        4. +
      +
      + +

      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. +
      2. Switch to Focus Mode (NVDA+Space / Insert+Z) if not already in it
        3. +
      3. Type your filter or search query
        4. +
      4. Press Enter to apply
        5. +
      +

      Useful filter queries

      +
      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. +
      2. Press ←/→ to move between toolbar options (Label, Milestone, Assignee, Sort)
        3. +
      3. Press Enter to open the selected dropdown
        4. +
      4. Use ↑/↓ to navigate options in the dropdown
        5. +
      5. Press Enter or Space to select
        6. +
      6. Press Escape to close (filter applies immediately)
        7. +
      +
      + +
      +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. +
      2. VO+Left/Right to move between Label, Milestone, Assignee, Sort buttons
        3. +
      3. VO+Space to open the selected dropdown
        4. +
      4. VO+Down or arrow keys to navigate the dropdown options
        5. +
      5. VO+Space to select/deselect
        6. +
      6. Escape to close (filter applies immediately)
        7. +
      +
      + +
      +GitHub CLI (gh) alternative - filtering + +

      Filter issues by label, milestone, or assignee without navigating dropdown menus:

      +
      # 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:

      +
      [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

      + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + +
      GoalKey
      Hear the issue title1
      Jump to description2 (first h2 is usually "Description")
      Jump to Activity section2 → next h2 is "Activity"
      Navigate between comments3 (each comment is h3)
      Jump to comment boxD → "Add a comment" landmark
      Navigate labels/assigneesH or 3 in the sidebar
      +

      Reading the issue description

      +
        +
      1. Press 2 to reach the "Description" heading
        2. +
      2. Press ↓ to read the content line by line, OR
        3. +
      3. Use NVDA+↓ (NVDA say all) to have it read continuously
        4. +
      +
      +

      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 <code> elements with the text "code block" announced.

      +
      +GitHub CLI (gh) alternative - reading an issue + +

      View an issue's full content in your terminal:

      +
      # 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. +
      2. Click in the Leave a comment text area
        3. +
      3. Type your comment (Markdown is supported - use the toolbar buttons above the text for bold, italic, code, etc.)
        4. +
      4. Optionally click Preview to see how it will render
        5. +
      5. Click the green Comment button to post
        6. +
      +

      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. +
      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. +
      3. The Preview tab next to Write lets you check Markdown rendering before posting.
        4. +
      4. The green Comment button is full-width at high zoom and easy to target.
        5. +
      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. +
      6. In Windows High Contrast mode, the text area border and the Comment button use system colors for clear visibility.
        7. +
      +
      + +
      +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. +
      2. Enter Focus Mode: NVDA: Insert+Space | JAWS: Insert+Z
        3. +
      3. Type your comment (plain text or Markdown)
        4. +
      4. To preview: Tab to the Preview button, press Enter; then Tab back to Write to continue editing
        5. +
      5. Submit: press Ctrl+Enter from inside the text area, OR press Escape → Tab to the Comment button → Enter
        6. +
      +
      + +
      +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. +
      2. Interact with the text area: VO+Shift+Down
        3. +
      3. Type your comment (plain text or Markdown)
        4. +
      4. To preview: VO+Shift+Up to stop interacting, then Tab to the Preview button and VO+Space
        5. +
      5. Submit: press Cmd+Return from inside the text area, OR VO+Shift+Up → Tab to the Comment button → VO+Space
        6. +
      +
      + +
      +GitHub CLI (gh) alternative - commenting + +

      Leave a comment from your terminal:

      +
      # 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):

      + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + +
      ShortcutResult
      Ctrl+BBold text
      Ctrl+IItalic text
      Ctrl+ECode span
      Ctrl+KLink text dialog
      Ctrl+Shift+.> Blockquote
      Ctrl+Shift+L- Bullet list
      Ctrl+Shift+71. 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

      + + + + + + + + + + + + + + + + + + + +
      ShortcutAction
      ?Show all shortcuts for this page
      G IJump to the Issues tab from anywhere in the repo
      CCreate 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

      + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + +
      ShortcutAction
      MSet a milestone
      LApply a label
      ASet an assignee
      XLink a related issue from the same repository
      RQuote selected text in your reply (select text first)
      Ctrl+Shift+P (Win) or Cmd+Shift+P (Mac)Toggle Write and Preview tabs
      Ctrl+EnterSubmit 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.

      +
        +
      1. Navigate to your comment (3 to jump to comments)
        2. +
      2. Find the "..." (ellipsis) menu button near your comment
        3. +
      3. Press Enter on "Edit" from that menu
        4. +
      4. The comment turns into a text area - switch to Focus Mode
        5. +
      5. Make your changes
        6. +
      6. Tab to "Update comment" button → Enter
        7. +
      +

      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

      + +
      +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. +
      2. Press Enter
        3. +
      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
        4. +
      +
      + +
      +Screen reader users (VoiceOver - macOS) + +

      From the Issues list:

      +
        +
      1. Quick Nav B or VO+U → Buttons to find the "New issue" button
        2. +
      2. VO+Space to activate it
        3. +
      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
        4. +
      +
      + +

      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. +
      2. Focus Mode → type a clear, specific title
        3. +
      3. Good title: "Screen reader announces wrong element count on Issues list with 50+ items"
        4. +
      4. Bad title: "Bug with screen reader"
        5. +
      +

      Description / Body field

      +
        +
      1. Tab to the body text area
        2. +
      2. Focus Mode → type using the Markdown template provided
        3. +
      3. If no template, use this structure:
        4. +
      +
      ## 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 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. +
      2. Navigate to the sidebar - press H to find "Labels" heading
        3. +
      3. Press Enter on the Labels gear/button
        4. +
      4. Dropdown opens → ↑/↓ to navigate labels
        5. +
      5. Enter to select/deselect
        6. +
      6. Escape to close (selections save automatically)
        7. +
      +
      + +
      +Screen reader users (VoiceOver - macOS) + +
        +
      1. VO+Shift+Up to stop interacting with the text area
        2. +
      2. VO+U → Headings to find the "Labels" heading in the sidebar
        3. +
      3. VO+Space on the Labels gear/button to open the dropdown
        4. +
      4. VO+Down or arrow keys to navigate labels
        5. +
      5. VO+Space to select/deselect
        6. +
      6. Escape to close (selections save automatically)
        7. +
      +
      + +

      Submitting the issue

      +
        +
      1. Tab to "Submit new issue" button
        2. +
      2. Press Enter
        3. +
      +
      +GitHub CLI (gh) alternative - filing a new issue + +

      Create an issue from your terminal:

      +
      # 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. +
      2. Click New issue, choose a template or blank issue.
        3. +
      3. Fill in the title and description, then click Submit new issue.
        4. +
      +

      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. +
      2. Under Issues, click the + icon to create a new issue.
        3. +
      3. Fill in the title and body, then click Create.
        4. +
      +

      GitHub Desktop: +Not directly supported. Click Repository > View on GitHub to open the browser, then file the issue there.

      +

      Git CLI / GitHub CLI:

      +
      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:

      + + + + + + + + + + + + + + + + + + + + + + + + + + + +
      KeywordEffect on merge
      Closes #42Closes issue #42 when the PR merges
      Fixes #42Same - typically for bugs
      Resolves #42Same - general use
      refs #42Creates a reference without auto-closing
      cc @usernameNotifies 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:

      +
      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 caseExample
      Large feature broken downParent: "Redesign navigation"; Children: "Keyboard nav," "Screen reader nav," "Mobile nav"
      Epic trackingParent: "WCAG 2.1 AA compliance"; Children: one issue per failing criterion
      Release milestoneParent: "v2.0 release"; Children: every required PR/fix
      +

      Creating a Sub-Issue

      +

      From any open issue:

      +
      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

      +
      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

      + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + +
      FeatureTask list checkboxesSub-issues
      LocationIssue description (Markdown)Sidebar/section (structured data)
      Each item isText line + checkboxA full GitHub issue
      Tracked in ProjectsNo (checkbox only)Yes (each child tracks independently)
      Cross-repoNoYes
      Best forQuick checklists in one issueMulti-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. +
      2. Button approach: Tab to the "Close issue" button (at the bottom of the page, near the comment box) and press Enter
        3. +
      3. Optionally leave a closing comment first
        4. +
      +
      + +
      +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. +
      2. Button approach: Quick Nav B or Tab to find the "Close issue" button, then VO+Space
        3. +
      3. Optionally leave a closing comment first
        4. +
      +
      + +
      +GitHub CLI (gh) alternative - closing and reopening + +

      Close or reopen an issue from your terminal:

      +
      # 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. +
      2. Activate the gear/plus button
        3. +
      3. Type a username in the search field
        4. +
      4. Select from the dropdown
        5. +
      +
      +GitHub CLI (gh) alternative - assigning and labeling + +

      Manage assignments and labels from your terminal:

      +
      # 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. +
      2. Activate the gear button
        3. +
      3. Select/deselect labels from the dropdown
        4. +
      4. Press Escape to save
        5. +
      +

      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. +
      2. Filter by label: type is:open label:"good first issue" in the search
        3. +
      3. Read through issues until you find one in your area of interest
        4. +
      4. Comment on the issue: "Hi, I'd like to work on this. Can I be assigned?"
        5. +
      5. Wait for a maintainer to respond and assign you before starting work
        6. +
      +

      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. +
      2. OS and version - "Windows 11 22H2"
        3. +
      3. Browser and version - "Chrome 124.0.6367.82"
        4. +
      4. GitHub interface - "Modern experience (default since Jan 2026)" or "Classic experience (opted out)"
        5. +
      5. What was announced - quote the exact text your screen reader spoke
        6. +
      6. What should have been announced - describe the expected behavior
        7. +
      7. ARIA issue if known - e.g., "The button has no accessible name"
        8. +
      8. Steps to reproduce - numbered, step-by-step
        9. +
      9. Frequency - "This happens every time" vs "intermittent"
        10. +
      +

      Example of a well-filed accessibility issue

      +
      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 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.

      + + + + + + + + + + + + + + + + + + + + + + + + + + + +
      SectionWhat to write
      TitleFollow the formula: "When I [action], [unexpected result] instead of [expected result]"
      Steps to ReproduceNumbered list -- start from the earliest relevant step
      Expected BehaviorWhat should happen according to documentation or common sense
      Actual BehaviorWhat does happen -- include exact error messages or screenshots
      EnvironmentOS, 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. +
      2. Proposed solution -- Your best idea for fixing the problem. Be specific enough to discuss, but hold it loosely.
        3. +
      3. Alternatives considered -- Other approaches you thought about and why they fell short. This shows you have done your homework.
        4. +
      4. Who benefits -- Name the audience. "Screen reader users navigating large repositories" is more compelling than "everyone."
        5. +
      +

      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.

      + + + + + + + + + + + + + + + + + + + + + + + + + + + + +
      PrincipleBad exampleGood 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. +
      2. Press G then I to go to the Issues tab
        3. +
      3. Tab to the "New issue" button
        4. +
      4. Press Enter
        5. +
      +

      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.

      +
      +

      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. +
      2. Find and activate the "New issue" button (K to links, or Tab to it)
        3. +
      3. In the title field, type: "Introduce myself - [Your Name]"
        4. +
      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. +
      5. Press Ctrl+Enter to submit (or Tab to the Submit button and press Enter)
        6. +
      +

      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 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 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.

      +
      +
      +

      Next: Chapter 06: Working with Pull Requests
      Back: Chapter 04: The Learning Room
      Related appendices: Appendix N: Advanced Search | Appendix V: GitHub Mobile

      + +
      + + + + diff --git a/html/admin/qa-bundle/docs/06-working-with-pull-requests.html b/html/admin/qa-bundle/docs/06-working-with-pull-requests.html new file mode 100644 index 00000000..757a64f9 --- /dev/null +++ b/html/admin/qa-bundle/docs/06-working-with-pull-requests.html @@ -0,0 +1,1689 @@ + + + + + + + Working with Pull Requests - GIT Going with GitHub + + + + + + + + +
      +

      Working with Pull Requests

      +
      +

      Listen to Episode 6: Working with Pull Requests - a conversational audio overview of this chapter. Listen before reading to preview the concepts, or after to reinforce what you learned.

      +
      +
      +

      Related appendices: Appendix C: Markdown Reference | Appendix B: Screen Reader Cheat Sheet +Authoritative sources: GitHub Docs: About pull requests | GitHub Accessibility Guide: Pull Requests

      +
      +

      Creating, Reviewing, and Merging Pull Requests with a Screen Reader

      +
      +

      See also: Chapter 15: Code Review covers the full review workflow including multi-file diffs and suggested changes.

      +
      +
      +

      Pull requests are where your work becomes a contribution. This guide takes you through the full pull request workflow - from opening one to participating in review - using only your keyboard and screen reader.

      +

      Official GitHub Accessibility Guide: GitHub publishes an NVDA-focused guide for working with pull requests using a screen reader at Using GitHub Pull Requests with a Screen Reader. This chapter covers the same material with additional perspectives (VoiceOver, low vision, CLI) and workshop-specific challenges. Use the official guide as a companion reference.

      +

      Screen reader note - New Files Changed Experience: This guide uses GitHub's improved Files Changed experience, which adds proper ARIA landmark structure to the Files Changed tab, including the file tree and diff navigation. This feature may already be active for your account - it has been broadly rolled out and may no longer appear as a Feature Preview toggle at all.

      +

      To verify: Activate the User Menu button (top-right of any GitHub page) → activate "Feature preview" → scan the list for "New Files Changed Experience":

      +
        +
      • If listed and the toggle announces "Pressed" (or "Disable") - already enabled, no action needed
        • +
      • If listed but not Pressed (or "Enable") - activate the toggle to enable it
        • +
      • If not listed at all - the feature has graduated to the standard interface; it is active automatically
        • +
      +

      Full step-by-step instructions with per-screen-reader commands are in Pre-Workshop Setup, Step 4.

      +

      Browse vs Focus Mode (NVDA): Use Browse Mode (the default) for reading PR conversations, navigating headings, and reviewing diffs. Switch to Focus Mode (NVDA+Space) only when you need to type in comment boxes or search fields. Switch back to Browse Mode to resume navigation. Maximize your browser window for consistent landmark layout.

      +
      +

      Workshop Recommendation (Chapter 6)

      +

      Chapter 6 is the first PR-validated chapter where students convert issue work into merge-ready contributions.

      +
        +
      • Challenge count: 3
        • +
      • Time per challenge: under 10 minutes each
        • +
      • Evidence: PR metadata, bot checks, and merged issue linkage
        • +
      • Pattern: small change -> linked PR -> green checks
        • +
      +

      Chapter 6 Challenge Set

      +
        +
      1. Create one small branch change - edit a practice file on a new branch.
        2. +
      2. Open a linked PR - use the PR template and include Closes #XX.
        3. +
      3. Pass required checks - respond to bot feedback until all required checks pass.
        4. +
      +
      +

      Branch guidance for Chapter 6: This is the first chapter where you edit files and create branches. Use one of these two paths:

      +
        +
      • Web editor (recommended for beginners): When you edit a file on GitHub.com and click "Propose changes," GitHub creates a branch for you automatically. Name it fix/yourname-issueXX (for example, fix/maria-issue42).
        • +
      • Local Git (if you cloned in Block 0): Create a feature branch with git checkout -b fix/yourname-issueXX from main. See the "Local Git Alternative" section below for the full command sequence.
        • +
      +

      Do not reuse your learn/<username> branch for this short exercise unless your facilitator tells you to. Chapter 6 works best with a short-lived feature branch such as fix/yourname-issueXX, because it teaches the pull request loop without mixing multiple challenges on one branch.

      +
      +

      Challenge 6.1 Step-by-Step: Create One Small Branch Change

      +

      Goal: Edit one of the practice files and save your change on a new branch.

      +

      Where you are working: your Learning Room repository on GitHub.com, using the web editor.

      +

      Before you start: Open your assigned Chapter 6.1 challenge issue (the one titled "Chapter 6.1: Create One Small Branch Change (@yourname)"). The issue description tells you which file to edit and what to fix.

      +

      The Learning Room has three practice files with intentional problems. Your assigned issue points you to one of them:

      +

      The following table summarizes the practice files in the learning-room, what each file contains, and the type of issues to look for.

      + + + + + + + + + + + + + + + + + + + + + + + +
      FileWhat it containsWhat to fix
      docs/welcome.mdIntroduction to open source contributionThree [TODO] sections where content is missing
      docs/keyboard-shortcuts.mdScreen reader shortcut reference tablesIntentional errors in shortcut references
      docs/setup-guide.mdGetting-started instructionsBroken 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. +
      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. +
      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. +
      4. Keep your change small and focused. Edit only what the issue asks for.
        5. +
      +

      Proposing your changes (this creates your branch):

      +
        +
      1. After editing, activate the Commit changes button (green button above the editor).
        2. +
      2. A dialog appears. In the Branch name field, type: fix/yourname-issueXX (replace yourname with your GitHub username, and XX with the issue number).
        3. +
      3. Select Create a new branch for this commit and start a pull request.
        4. +
      4. Activate Propose changes.
        5. +
      +

      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. +
      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. +
      3. Verify the base branch is main and the compare branch is your fix/yourname-issueXX branch.
        4. +
      4. Activate the Create pull request button.
        5. +
      +

      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. +
      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. +
      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. +
      4. Repeat step 3 until all required checks show a green checkmark.
        5. +
      5. When all checks pass, request a review from a peer or the facilitator.
        6. +
      +

      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. +
      2. Check that changed files are only in learning-room/.
        3. +
      3. Open the bot validation comment and resolve one required check at a time.
        4. +
      4. If checks still fail, ask for peer or facilitator review with the exact error message.
        5. +
      5. Finished but not sure you did it right? Compare your work against the Challenge 6 reference solution.
        6. +
      +

      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.

      + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + +
      CardWho it helpsWhat it covers
      Visual / mouseSighted users navigating with a mouse or trackpadClick targets, visual cues, layout orientation
      Low visionUsers with magnification, zoom, or high-contrast themesZoom-friendly navigation, finding controls at high magnification, high contrast visibility
      NVDA / JAWS (Windows)Screen reader users on WindowsKeystroke sequences, Focus and Browse mode, landmark paths
      VoiceOver (macOS)Screen reader users on macOSVO key sequences, rotor usage, interaction model
      GitHub.com webAll users working in the browserBrowser-based workflows without local tools
      CLI (git / gh)Terminal users on any platformGit 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.

      +

      Step 1 - Sync and create a feature branch:

      +
      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:

      +
      code docs/welcome.md
      +

      Make your changes and save the file.

      +

      Step 3 - Stage, commit, and push:

      +
      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:

      +
      gh pr create --title "Complete TODO sections in welcome.md" \
+  --body "Closes #42" --base main
      +

      Or open interactively:

      +
      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.

      +
      + +
      +

      Global pull requests dashboard: GitHub now shows a global pull requests page at 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. +
      2. K to navigate tabs → "Pull requests, [N] open"
        3. +
      3. Enter to open
        4. +
      +
      + +
      +Screen reader users (VoiceOver - macOS) + +
        +
      1. VO+U → Landmarks → navigate to "Repository navigation"
        2. +
      2. Quick Nav K or VO+Right to navigate tabs → "Pull requests"
        3. +
      3. VO+Space to open
        4. +
      +
      + +

      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:

      +
      # 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 and authenticate with gh auth login. See Appendix D 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:

      +
      [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]
      + +

      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. +
      2. Press ← or → arrow keys to move between tab options
        3. +
      3. Press Enter to activate a tab
        4. +
      +
      + +
      +Screen reader users (VoiceOver) + +
        +
      1. VO+U → Landmarks → “Pull request navigation tabs”
        2. +
      2. VO+Right to move between tabs
        3. +
      3. VO+Space to activate
        4. +
      +
      + +

      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. +
      2. ↓ to read the description
        3. +
      3. Markdown renders as semantic HTML - headings, lists, code blocks are fully accessible
        4. +
      +

      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. +
      2. Press K to navigate links for individual check names
        3. +
      3. Press Enter on a check to see its details
        4. +
      +
      + +
      +Screen reader users (VoiceOver - macOS) + +
        +
      1. Quick Nav H or VO+Cmd+H to jump to the "Checks" or "Status checks" heading
        2. +
      2. Quick Nav K to navigate check name links
        3. +
      3. VO+Space on a check to see its details
        4. +
      +
      + +

      See GitHub Actions & Workflows 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:

      +
      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. +
      2. Tab to the end of the thread to find the "Resolve conversation" button
        3. +
      3. Press Enter to mark it resolved
        4. +
      4. The conversation collapses and shows as "Resolved"
        5. +
      +

      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

      +
      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. +
      2. Navigate between tab links (K or Tab) and activate "Checks"
        3. +
      3. Press D to jump to the "check suites" section - this moves focus to the collapsed details button of the first check
        4. +
      4. Press B or Tab to navigate between check buttons; each button is labeled with the check's name
        5. +
      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. +
      6. For a summary view: press D to navigate to the "check run summary" section
        7. +
      +
      + +
      +Screen reader users (VoiceOver - macOS) + +
        +
      1. VO+U -> Landmarks -> "Pull request tabs" -> activate "Checks"
        2. +
      2. VO+U -> Landmarks -> navigate to "check suites" section
        3. +
      3. VO+Right to move through check buttons, VO+Space to expand
        4. +
      4. For summary: VO+U -> Landmarks -> "check run summary"
        5. +
      +
      + +

      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. +
      2. ↑/↓ to navigate the file list
        3. +
      3. Enter to jump to that file's diff
        4. +
      +
      + +
      +Screen reader users (VoiceOver - macOS) + +
        +
      1. VO+U → Landmarks → navigate to "File tree" region
        2. +
      2. VO+Down to move through the file list
        3. +
      3. VO+Space to jump to that file's diff
        4. +
      +
      + +

      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
        • +
      + +
      +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. +
      2. Switch to Focus Mode: Insert+Space (NVDA) or Insert+Z (JAWS)
        3. +
      3. Ctrl+Alt+↓ to move down one row (next diff line), Ctrl+Alt+↑ to move up
        4. +
      4. Ctrl+Alt+→ to read across columns (line number | change type | content)
        5. +
      5. The screen reader reads: “+ Add accessible name to submit button”
        6. +
      6. Collapsed sections contain unchanged code. Focus the expand/disclosure control and activate it (Enter or Space) to reveal the hidden lines.
        7. +
      +
      +

      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. +
      2. VO+Shift+Down to enter the table
        3. +
      3. VO+Right/Left for columns, VO+Up/Down for rows
        4. +
      +
      + +

      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. +
      2. While focused on that line, a comment button appears - press Enter or Space to activate it
        3. +
      3. A comment box opens below the line
        4. +
      4. Focus Mode → type your comment
        5. +
      5. Tab to Add single comment button (instant comment) OR Start a review (to batch comments)
        6. +
      +

      Multi-line comment (Windows)

      +
        +
      1. Focus the first line you want to comment on
        2. +
      2. Press Shift+↓ to extend the selection to additional lines
        3. +
      3. A comment button appears - activate it
        4. +
      4. The comment applies to the full range of selected lines
        5. +
      +
      + +
      +Screen reader users (VoiceOver - macOS) + +
        +
      1. Navigate to the specific line in the diff (using the table navigation above)
        2. +
      2. While focused on that line, VO+Space on the comment button that appears
        3. +
      3. A comment box opens below the line
        4. +
      4. VO+Shift+Down to interact with the text area, then type your comment
        5. +
      5. VO+Shift+Up to stop interacting, then Tab to Add single comment and VO+Space
        6. +
      +

      Multi-line comment (macOS)

      +
        +
      1. Focus the first line and Shift+↓ to extend the selection
        2. +
      2. VO+Space on the comment button that appears
        3. +
      3. The comment applies to the full range of selected lines
        4. +
      +
      + +

      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. +
      2. Set base branch to main, compare branch to yours.
        3. +
      3. Fill in the title and description, then click Create pull request.
        4. +
      +

      github.dev (web editor):

      +
        +
      1. After committing changes, click the Source Control icon.
        2. +
      2. Click Create Pull Request in the Source Control panel header.
        3. +
      3. Fill in details and submit.
        4. +
      +

      VS Code Desktop (GitHub Pull Requests extension):

      +
        +
      1. Press Ctrl+Shift+P, type GitHub Pull Requests: Create Pull Request.
        2. +
      2. Select base and compare branches.
        3. +
      3. Fill in the title and description, then click Create.
        4. +
      +

      GitHub Desktop:

      +
        +
      1. After pushing your branch, click Create Pull Request in the banner or Branch > Create Pull Request.
        2. +
      2. This opens github.com with the PR form pre-filled.
        3. +
      +

      Git CLI / GitHub CLI:

      +
      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. +
      2. You named your branch and activated "Propose changes"
        3. +
      3. GitHub redirected you to the "Open a pull request" page
        4. +
      +

      From a fork or feature branch

      +
      +Visual / mouse users + +
        +
      1. Navigate to the repository on GitHub
        2. +
      2. If you recently pushed, a yellow banner “Compare & pull request” appears at the top - click it
        3. +
      3. If no banner appears: click the Pull requests tab → click the green New pull request button
        4. +
      4. Use the branch dropdowns to choose your base branch (what to merge into) and your compare branch (your changes)
        5. +
      5. Click Create pull request
        6. +
      +
      + +
      +Screen reader users (NVDA / JAWS - Windows) + +
        +
      1. Navigate to the repository
        2. +
      2. A "Compare & pull request" banner may appear (if you recently pushed) - activate it
        3. +
      3. OR: Navigate to Pull Requests tab → "New pull request"
        4. +
      4. Choose your base branch (what to merge into) and compare branch (your changes)
        5. +
      +
      + +
      +Screen reader users (VoiceOver - macOS) + +
        +
      1. Navigate to the repository
        2. +
      2. Check for a "Compare & pull request" banner - Quick Nav B to find and VO+Space to activate it
        3. +
      3. OR: navigate to Pull Requests tab (VO+U → Landmarks → Repository navigation) → Quick Nav B for "New pull request"
        4. +
      4. Use the branch dropdowns (VO+Space to open, arrow keys to select) to choose base and compare branches
        5. +
      +
      + +

      Filling out the PR form

      +

      Title field

      +
      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

      +
      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:

      +
      ## Summary
+
+What does this PR change and why?
+
+## Changes
+
+- Added `aria-label` to the search button
+- Fixed keyboard trap in the modal dialog
+- Replaced `<div>` with `<button>` for the dismiss control
+
+## Related Issues
+
+Closes #42
+
+## Testing
+
+- Tested with NVDA + Chrome on Windows 11
+- Tested with VoiceOver + Safari on macOS Sonoma
+- Keyboard-only navigation verified
+
+## Screenshots / recordings
+
+[Include if relevant - with descriptive alt text for any images]
      +
      +

      Learning Room example: In the Learning Room repository, a PR template is provided for you. Here is what a completed PR looks like for Challenge 3 (Complete Welcome Guide):

      +
      ## Description
+
+Completed three [TODO] sections in docs/welcome.md:
+- Added paragraph about contributors from all backgrounds
+- Added guidance on evaluating issues before starting
+- Added note about GitHub profile and portfolio impact
+
+## Related Issue
+
+Closes #12
+
+## Type of change
+
+- [x] Documentation update
+
+## Accessibility checklist
+
+- [x] Heading levels follow a logical hierarchy
+- [x] Link text is descriptive (no "click here")
+- [x] No images added (or alt text provided)
      +

      The Closes #12 line tells GitHub to automatically close issue 12 when this PR merges. The validation bot checks that this line is present and that your description is at least 50 characters long.

      +
      +

      Setting a Draft PR

      +

      If your work is not finished, open as a Draft:

      +
        +
      1. After filling in the form, find the dropdown arrow next to "Create pull request"
        2. +
      2. Select "Create draft pull request"
        3. +
      3. This signals to reviewers that it is not ready for formal review yet
        4. +
      +

      Draft Pull Requests - Full Lifecycle

      +

      A draft pull request is a PR explicitly marked as a work in progress. It is visible to the team, can receive comments, and runs CI - but is blocked from being merged until you mark it ready.

      +

      When to use a draft

      +
        +
      • You want to show your approach and get early feedback before finishing
        • +
      • You need CI to run but don't want accidental merges
        • +
      • You are working across multiple days and want your progress visible
        • +
      • You want to pair with a collaborator on the work
        • +
      +

      What a draft PR does differently

      +
        +
      • The merge button is disabled - even an authorized maintainer cannot merge a draft
        • +
      • The PR header shows a grey "Draft" badge instead of the green "Open" badge
        • +
      • Reviewers are not auto-notified (no review requests are sent until ready)
        • +
      • CI workflows still run normally
        • +
      +

      Mark a draft ready for review

      +
        +
      1. Open the PR
        2. +
      2. Navigate to the "Reviewers" sidebar or scroll to bottom of the Conversation tab
        3. +
      3. Find and activate the "Ready for review" button
        4. +
      4. The draft badge changes to "Open" and reviewers are notified
        5. +
      +

      Screen reader path

      +
      Scroll to bottom of Conversation tab
+→ B to navigate buttons
+→ "Ready for review" button → Enter
+→ Confirmation: PR status changes to Open
      +

      Convert an open PR to draft (after opening)

      +
        +
      1. In the right sidebar, find the "Reviewers" section
        2. +
      2. Look for the "Convert to draft" link (below the review status)
        3. +
      3. Confirm in the dialog - this removes merge eligibility until you mark it ready again
        4. +
      +
      +GitHub CLI (gh) alternative - draft PR lifecycle + +

      Manage draft PRs from your terminal:

      +
      # Create a draft PR
+gh pr create --draft --title "WIP: Add carousel keyboard nav"
+
+# Mark a draft ready for review
+gh pr ready 42
+
+# Check PR status (shows draft state)
+gh pr view 42
+
+# List only draft PRs
+gh pr list --draft
      +
      + +

      Learning Cards: Opening a Pull Request

      +
      +Screen reader users + +
        +
      • After editing a file on GitHub, the "Propose changes" form has a branch name field and a commit message field; press Tab to move between them
        • +
      • On the "Open a pull request" page, press F to jump to the Title field; Tab moves to the Description text area
        • +
      • Press Ctrl+Enter from inside the description text area to submit the PR without finding the Create button
        • +
      +
      + +
      +Low vision users + +
        +
      • The "Compare & pull request" yellow banner appears at the top of the repo after a recent push; at high zoom it may span the full width of the page
        • +
      • The branch comparison dropdowns (base and compare) use small text; zoom in on the area above the diff preview to read them
        • +
      • Draft PR: look for the dropdown arrow next to the green "Create pull request" button to switch to "Create draft pull request"
        • +
      +
      + +
      +Sighted users + +
        +
      • After pushing a branch, a yellow "Compare & pull request" banner appears at the top of the repository page; click it to pre-fill the PR form
        • +
      • The PR form shows a diff preview below the description field so you can verify your changes before submitting
        • +
      • The dropdown arrow next to "Create pull request" lets you switch to Draft mode; the button text changes to "Create draft pull request"
        • +
      +
      + +

      Requesting reviewers

      +

      From the sidebar Reviewers section:

      +
        +
      1. Navigate to "Reviewers" heading (3 or H)
        2. +
      2. Activate the gear button
        3. +
      3. Type a username in the search field
        4. +
      4. Select from the dropdown
        5. +
      5. Escape to save
        6. +
      +
      +

      Why some reviews are requested automatically: A file called CODEOWNERS in many repositories maps file paths to specific people or teams. When your PR touches a file covered by a CODEOWNERS rule, GitHub automatically adds those people as required reviewers - you'll see them appear in the Reviewers sidebar without you adding them. You cannot remove a CODEOWNERS-required reviewer. If a required reviewer hasn't responded, reach out to them directly or leave a comment on the PR.

      +
      +

      Submitting a Review

      +

      When you are asked to review a PR, you have three options:

      +
        +
      • Comment - leave feedback without a verdict; does not block merging
        • +
      • Approve - signal you are satisfied; often required before merge
        • +
      • Request changes - indicate changes must be addressed; blocks merge until resolved
        • +
      +

      Starting a review

      +

      On the Files Changed tab, when you add inline comments, choose "Start a review" instead of "Add single comment." This batches all your comments into one review submission.

      +

      Completing and submitting a review

      +

      After adding your inline comments via “Start a review,” you must submit the review to notify the PR author. The review is pending until you submit it.

      +
      +Visual / mouse users + +
        +
      1. Look for the Finish your review button in the top-right area of the Files Changed tab (it shows the number of pending comments)
        2. +
      2. Click it - a popover appears with a summary text area and three radio buttons: Comment, Approve, Request changes
        3. +
      3. Optionally type a summary comment
        4. +
      4. Select your verdict by clicking the radio button
        5. +
      5. Click Submit review
        6. +
      +
      + +
      +Low vision users (zoom, high contrast) + +

      The Finish your review button is in the top-right area of the Files Changed tab. It shows a badge with the number of pending comments. At high magnification:

      +
        +
      • The button may scroll off-screen to the right. Use horizontal scrolling or press Tab from the page top to cycle through focusable elements until you reach it.
        • +
      • When clicked, a popover appears with a summary text area and three radio buttons (Comment, Approve, Request changes). At 200%+ zoom, the popover may extend below the visible viewport. Scroll down within the popover to see the Submit review button.
        • +
      • The radio buttons are standard HTML radio buttons. In Windows High Contrast mode, the selected radio button uses the system highlight color.
        • +
      • Keyboard shortcut: If the button is hard to find visually, press Ctrl+Shift+Enter from within any review comment text area to open the submit review dialog directly.
        • +
      +
      + +
      +Screen reader users (NVDA / JAWS) + +
        +
      1. Press 1 to go to the h1 (PR title)
        2. +
      2. Press B (or Tab) to navigate to the “Submit review” button and activate it (Enter/Space)
        3. +
      3. A “Submit review” dialog/panel appears
        4. +
      4. Switch to Focus Mode (NVDA+Space) if prompted to type
        5. +
      5. Optionally type a summary comment in the “markdown value” textbox
        6. +
      6. Tab to the “Review Event” radio group
        7. +
      7. Use ↑/↓ to select one of:
          +
        • Comment - general feedback, does not block merge
          • +
        • Approve - you are satisfied; signals merge readiness
          • +
        • Request changes - must be addressed before merge
          • +
        +
        8. +
      8. Tab to the “Submit review” button and press Enter
        9. +
      +
      +
      +Screen reader users (VoiceOver - macOS) + +
        +
      1. Quick Nav H or VO+Cmd+H to navigate to the PR title (h1)
        2. +
      2. Quick Nav B or Tab to find the "Submit review" button → VO+Space
        3. +
      3. A "Submit review" dialog/panel appears
        4. +
      4. VO+Shift+Down to interact with the summary text area, type an optional comment
        5. +
      5. VO+Shift+Up to stop interacting, then Tab to the "Review Event" radio group
        6. +
      6. VO+Left/Right or arrow keys to select:
          +
        • Comment - general feedback, does not block merge
          • +
        • Approve - you are satisfied; signals merge readiness
          • +
        • Request changes - must be addressed before merge
          • +
        +
        7. +
      7. Tab to the "Submit review" button → VO+Space
        8. +
      +
      +> **Tip from accessibility.github.com:** If you submitted comments as "Add single comment" instead of "Start a review," each comment is already posted individually. The "Submit review" flow is only needed when you chose "Start a review" to batch comments together. + +
      +GitHub CLI (gh) alternative - reviewing a PR + +

      Review a pull request from your terminal:

      +
      # View the PR diff in your terminal
+gh pr diff 42
+
+# Approve a PR
+gh pr review 42 --approve
+
+# Approve with a comment
+gh pr review 42 --approve --body "Looks good - heading hierarchy is correct."
+
+# Request changes
+gh pr review 42 --request-changes --body "The alt text on line 34 needs to describe the image content."
+
+# Leave a comment-only review (no verdict)
+gh pr review 42 --comment --body "A few suggestions - see inline comments."
      +

      Note: gh pr diff outputs the full diff to your terminal, which a screen reader can read line by line. For inline comments on specific lines, use the web interface or VS Code.

      +
      + +

      GitHub shortcuts for pull requests

      +

      These are the GitHub built-in shortcuts for PR pages. Enable Focus Mode first (NVDA: NVDA+Space, JAWS: Insert+Z) before using single-key shortcuts.

      +

      On the PR list page

      + + + + + + + + + + + + + + + + + + + +
      ShortcutAction
      G PJump to the Pull Requests tab from anywhere in the repo
      CCreate a new pull request
      Ctrl+/ (Win) or Cmd+/ (Mac)Focus the PR search bar
      +

      Shortcut note: For G P, press G, release it, then press P (two sequential key presses, not simultaneous).

      +

      On an open pull request

      + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + +
      ShortcutAction
      ?Show all shortcuts for this page
      QRequest a reviewer
      MSet a milestone
      LApply a label
      ASet an assignee
      RQuote selected text in your reply
      Ctrl+Shift+PToggle Write and Preview tabs in the comment box
      Ctrl+EnterSubmit comment from inside the text area
      +

      On the Files Changed tab

      + + + + + + + + + + + + + + + + + + + + + + + +
      ShortcutAction
      TJump to the "Filter changed files" field
      COpen the commits dropdown to filter which commits are shown
      Ctrl+G (Win) or Cmd+G (Mac)Insert a code suggestion block around selected code
      Ctrl+Shift+Enter (Win) or Cmd+Shift+Enter (Mac)Submit a review comment
      +

      For the full shortcut system, see Screen Reader Cheat Sheet - GitHub Shortcuts section.

      +

      Learning Cards: Submitting a Review

      +

      Screen reader users:

      +
        +
      • The review verdict controls are inside a popover triggered by the "Finish your review" button; press 1 to return to the h1 (PR title), then B or Tab forward to find the button -- it is easy to miss because it is not a landmark
        • +
      • Inside the popover, Tab past the summary text area to reach a radio group labeled "Review Event"; use Up/Down Arrow to switch between Comment, Approve, and Request Changes
        • +
      • Shortcut: press Ctrl+Shift+Enter from any review comment text area to open the submit review dialog directly, bypassing the search for the button
        • +
      +

      Low-vision users:

      +
        +
      • The "Finish your review" button sits in the top-right corner of the Files Changed tab with a small badge showing your pending comment count; at 200%+ zoom it may scroll off-screen to the right
        • +
      • Inside the submit popover, the three radio buttons (Comment, Approve, Request changes) are small standard HTML radios; zoom in on the popover area or use Tab to step between them
        • +
      • After submitting, your review verdict appears as a colored banner in the Conversation timeline: green for Approve, red for Request Changes, grey for Comment
        • +
      +

      Sighted users:

      +
        +
      • Look for the green "Finish your review" button in the sticky header of the Files Changed tab; the badge shows how many comments are pending
        • +
      • The popover has a text area for an overall summary at the top and three radio buttons at the bottom: Comment, Approve, Request changes -- select one before clicking "Submit review"
        • +
      • If you added comments with "Add single comment" instead of "Start a review," those are already posted; the submit review flow only applies to batched review comments
        • +
      +

      Suggested Changes

      +

      A suggested change is a special form of inline review comment where the reviewer proposes exact replacement text. The PR author can apply the suggestion directly from GitHub - no copy-paste or separate commit needed.

      +

      As a reviewer - inserting a suggestion

      +
        +
      1. On the Files Changed tab, navigate to the line you want to propose a change for
        2. +
      2. Activate the line comment button for that line (the + that appears on hover, or Tab to navigate to it)
        3. +
      3. In the comment text area that opens, press Ctrl+G (Windows) or Cmd+G (Mac)
        4. +

      4. GitHub wraps a suggestion block around the current line content:

        +
        ```suggestion
+the current line content here
+```
        +
        5. +
      5. Edit the text inside the suggestion block to show your proposed change
        6. +
      6. Add context above the block if helpful: "This makes the alt text more descriptive:"
        7. +
      7. Submit as part of your review ("Start a review" → batch with other comments)
        8. +
      +

      Screen reader note: The suggestion block is plain Markdown text in the comment editor. Type it directly:

      +
      ```suggestion
+your proposed text here
+```text
+
      +

      (Three backticks, the word suggestion, Enter, your text, Enter, three backticks.)

      +

      As an author - applying a suggestion

      +
        +
      1. Open the PR Conversation or Files Changed tab
        2. +
      2. Navigate to the inline comment containing a suggestion (it shows a diff-style preview)
        3. +
      3. Find and activate the "Apply suggestion" button below the suggestion block
        4. +
      4. GitHub creates a commit automatically that applies the change - no file editing required
        5. +
      5. The conversation thread is marked as resolved
        6. +
      +

      Batching multiple suggestions into one commit

      +
        +
      1. For each suggestion you want to apply, activate "Add suggestion to batch" instead of "Apply suggestion"
        2. +
      2. After selecting all suggestions, activate the "Commit suggestions" button that appears at the top
        3. +
      3. GitHub applies all batched suggestions in a single commit
        4. +
      +

      When to use suggestions vs. comments

      +
        +
      • Use a suggestion when you know the exact text that would fix the issue
        • +
      • Use a plain comment when the change requires judgment from the author (e.g., "this alt text isn't descriptive - can you describe what the image shows?")
        • +
      +
        +
      1. After adding all your inline comments, navigate to the review summary button
        2. +
      2. On Files Changed tab: find the "Review changes" button (B to navigate buttons)
        3. +
      3. Press Enter to open the review dialog
        4. +
      4. A panel opens:
          +
        • A summary text area for overall comments
          • +
        • Radio buttons for Comment / Approve / Request changes
          • +
        +
        5. +
      5. Switch to Focus Mode → type your summary comment
        6. +
      6. Navigate to the radio buttons with arrow keys → select your verdict
        7. +
      7. Tab to "Submit review" button → Enter
        8. +
      +

      Learning Cards: Suggested Changes

      +

      Screen reader users:

      +
        +
      • To insert a suggestion block, press Ctrl+G (Windows) or Cmd+G (Mac) in the comment text area; the screen reader announces the inserted fence -- arrow down to edit the text between the backtick lines
        • +
      • Alternatively type the block manually: three backticks, the word suggestion, Enter, your replacement text, Enter, three backticks -- this avoids relying on the keyboard shortcut
        • +
      • As a PR author, navigate to a suggestion comment with 3, then Tab to the "Apply suggestion" button; GitHub commits the change automatically with no file editing required
        • +
      +

      Low-vision users:

      +
        +
      • Suggestion blocks render as a mini inline diff: the original line in red/pink background and your proposed replacement in green background; in high-contrast mode these use system diff colors
        • +
      • The "Apply suggestion" button is small and sits below the suggestion diff preview; zoom into the comment area to find it, or Tab from the suggestion text to reach it
        • +
      • When batching multiple suggestions, a floating "Commit suggestions" bar appears at the top of the page; at high zoom scroll up or press Home to find it
        • +
      +

      Sighted users:

      +
        +
      • In the comment box, press Ctrl+G / Cmd+G to wrap the current line in a suggestion block; edit the text inside to show your proposed replacement -- the preview tab renders it as an inline diff
        • +
      • As a PR author, each suggestion shows an "Apply suggestion" button and an "Add suggestion to batch" button; use batching to combine several suggestions into one clean commit
        • +
      • Applied suggestions auto-resolve the conversation thread and create a commit attributed to both the reviewer (author of the suggestion) and you (committer)
        • +
      +

      Understanding Merge Options (for Maintainers)

      +

      When a PR is approved and checks pass, a maintainer can merge it. The merge button section appears at the bottom of the Conversation tab.

      +
      
+Step 1: Navigate to the bottom of the Conversation tab
+Step 2: Find "Merge pull request" button (or similar)
+Step 3: A dropdown arrow next to the button offers strategy options:
+
+- Create a merge commit
+- Squash and merge
+- Rebase and merge
+Step 4: Choose strategy → activate the button
+Step 5: Confirm in the dialog that appears
+
      +
      +GitHub CLI (gh) alternative - merging a PR + +

      Merge a pull request from your terminal:

      +
      # Merge with default strategy (merge commit)
+gh pr merge 42
+
+# Squash and merge
+gh pr merge 42 --squash
+
+# Rebase and merge
+gh pr merge 42 --rebase
+
+# Delete the branch after merging
+gh pr merge 42 --squash --delete-branch
+
+# Enable auto-merge (merges when checks pass)
+gh pr merge 42 --auto --squash
      +
      + +

      After a PR is merged

      +
        +
      • The PR status badge changes to "Merged" (purple)
        • +
      • The source branch can be deleted - a "Delete branch" button appears
        • +
      • Any linked issues with Closes #N in the description are automatically closed
        • +
      +
      +

      Screen reader tip - deleting the branch after merge: Navigate to the "Add a comment" section (D), then press Shift+B to navigate backwards to the "Delete branch" button and activate it. This keeps your repository clean by removing the now-merged feature branch.

      +
      +

      Auto-Merge - Merging When You Can't Wait Around

      +

      Auto-merge lets you pre-authorize a PR to merge automatically the moment all branch protection requirements are satisfied - required reviews approved, all status checks passing, and the branch up to date.

      +

      This is especially useful when:

      +
        +
      • You've addressed all review comments and are waiting for CI to finish
        • +
      • A maintainer has approved the PR but a required check is still running
        • +
      • You're in a different time zone from the reviewers
        • +
      +

      Enabling Auto-Merge on Your PR

      +
      1. Open your PR → scroll to the merge box at the bottom
+2. Tab to the merge button dropdown arrow (next to "Merge pull request")
+3. Select "Enable auto-merge"
+4. Choose your merge strategy (squash, rebase, or merge commit)
+5. Confirm in the dialog - the merge box now shows "Auto-merge enabled"
      +

      Screen reader path

      +
      Conversation tab → End key → merge box region
+Tab → dropdown button (announced as "Select merge method" or similar)
+Enter → arrow keys through options → "Enable auto-merge" → Enter
+Dialog: Tab → confirm button → Enter
      +

      What happens next

      +
        +
      • The PR merge box changes to show "Auto-merge enabled - merge will happen automatically"
        • +
      • When the last required check passes (or last required review arrives), GitHub merges the PR silently
        • +
      • You receive a notification: "Your PR was automatically merged"
        • +
      • If a reviewer requests changes after auto-merge is enabled, auto-merge is automatically cancelled (a new approval is required before it re-enables)
        • +
      +

      Cancelling Auto-Merge

      +
      Merge box → Tab → "Disable auto-merge" button → Enter
      +
      +

      Note: Auto-merge is only available if the repository administrator has enabled it in Settings → General. Many open source repos have it on; some do not.

      +
      +

      Practical Scenarios

      +

      Scenario A: "I want to review an assigned PR"

      +

      Example: You are assigned to review a PR titled "Add missing NVDA shortcut to keyboard-shortcuts.md." The PR modifies docs/keyboard-shortcuts.md in the Learning Room repository and references Challenge 2.

      +
      1. Notifications → open the PR notification
+2. D → PR tabs → Files changed tab
+3. T → enter the first diff table → navigate lines with arrow keys
+4. Check: does the new shortcut appear in the correct NVDA table? Is the table formatting preserved?
+5. For each concern: activate the line comment button → type comment → Start a review
+6. D → PR tabs → Conversation → scroll to bottom
+7. B → "Review changes" button → type summary → select verdict → Submit review
      +

      Scenario B: "I want to respond to review feedback on my PR"

      +

      Example: Your PR for Challenge 3 (Complete Welcome Guide) received a review comment: "The [TODO] about evaluating issues is good, but the paragraph could mention checking if the issue is already assigned." The validation bot also flagged a link text issue.

      +
      1. Open your PR (Notifications → PR link, or find it in PR list)
+2. 3 to navigate review comments
+3. For the reviewer's comment: read it → Tab to "Reply" → Focus Mode → type "Good point - I will add a sentence about checking assignees. Pushing a fix now."
+4. For the bot's link text flag: fix the link in docs/welcome.md, commit, and push
+5. When all addressed: Tab to "Re-request review" button → Enter
      +

      Scenario C: "My PR has a merge conflict"

      +
      1. You will see a "This branch has conflicts that must be resolved" message near the bottom
+2. Tab to "Resolve conflicts" button → GitHub opens a web conflict editor
+3. The editor shows conflict markers - see Merge Conflicts guide (07-merge-conflicts.md)
+4. Edit the file to resolve → Mark as resolved → Commit merge
      +

      Common PR Mistakes to Avoid

      + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + +
      MistakeBetter Approach
      Opening a PR without an associated issueLink to or create an issue first; comment "I'd like to work on this"
      A vague title like "Fix things"Be specific: "Fix missing alt text on homepage hero image"
      Missing the PR template sectionsFill all sections - description, testing, related issues
      Pushing many unrelated changes in one PROne PR per logical change (smaller PRs get faster reviews)
      Not testing your own changesTest before requesting review
      Not responding to reviewer commentsAcknowledge all comments, even if you disagree
      +

      Writing PR Descriptions That Get Reviewed

      +
      +

      See also: Appendix C: Markdown Reference for formatting your PR description with headings, lists, and task lists.

      +
      +

      A pull request is only as useful as its description. Reviewers decide whether to pick up your PR -- and how carefully to read it -- based on what you write in that text box. A strong description saves everyone time, catches misunderstandings early, and makes the review conversation productive instead of confused.

      +

      This section walks you through what reviewers expect, how to structure your description, and the patterns that separate descriptions people actually read from descriptions people skip.

      +

      What Reviewers Look For

      +

      When a reviewer opens your PR, they are asking four questions before they ever look at the diff:

      +
        +
      1. Why does this change exist? -- What problem does it solve, or what goal does it advance?
        2. +
      2. What is the scope? -- Which files changed, and roughly how big is the change?
        3. +
      3. How was it tested? -- Did you verify that the change works, and how?
        4. +
      4. What should I pay attention to? -- Are there tricky parts, trade-offs, or areas where you want a second opinion?
        5. +
      +

      If your description answers all four, the reviewer can jump straight into the code with context. If it answers none, the reviewer has to reverse-engineer your intent from the diff -- and that slows everything down.

      +
      +

      Screen reader tip: When you write your description in the GitHub comment box, use Markdown headings (## or ###) to separate sections. Reviewers using screen readers can then press H to jump between sections instead of arrowing through a wall of text.

      +
      +

      The Closes #XX Pattern

      +

      GitHub recognizes special keywords in PR descriptions that automatically close linked issues when the PR merges. You do not need to close issues by hand -- just include the right keyword followed by the issue number.

      + + + + + + + + + + + + + + + + + + + + + + + +
      KeywordEffect When PR MergesWhen to Use
      Closes #12Closes issue #12The PR fully resolves the issue
      Fixes #12Closes issue #12The PR fixes a bug described in the issue
      Resolves #12Closes issue #12The PR resolves a discussion or question in the issue
      +

      All three keywords behave identically -- GitHub closes the linked issue on merge. The difference is purely semantic. Use whichever word best describes the relationship between your PR and the issue.

      +

      You can link multiple issues in one description:

      +
      Closes #12
+Closes #14
      +

      If your PR is related to an issue but does not fully resolve it, skip the keyword and write a plain reference instead: "Related to #12" or "See #12 for background." That creates a clickable link without triggering auto-close.

      +
      +

      Screen reader tip: After your PR merges, navigate to the linked issue. GitHub adds a cross-reference comment like "Closed by #25" that you can find by pressing 3 to jump between comments. This confirms the link worked.

      +
      +

      Before/After Structure

      +

      One of the most effective patterns for PR descriptions is showing the state before your change and the state after. This gives the reviewer an instant mental model of what changed without reading the diff line by line.

      +

      For text-based changes, use a simple two-part layout:

      +
      **Before:** The welcome page had a [TODO] placeholder where the
+introduction paragraph should be.
+
+**After:** The welcome page now has a three-sentence introduction
+that describes what the Learning Room is and who it is for.
      +

      For visual changes -- layout shifts, color updates, new UI elements -- describe what the reviewer would see. Since this curriculum prioritizes accessibility, write your before/after as text descriptions rather than relying solely on screenshots. A reviewer using a screen reader cannot see an image, but they can read "Before: the sidebar had no skip link. After: the sidebar has a skip link targeting the main content area."

      +

      If you do include screenshots, always add alt text that conveys the same information as the image. The screenshot is a convenience, not the only source of truth.

      +

      A PR Description Template

      +

      Here is a template you can copy into your PR descriptions. Not every section applies to every PR, but filling in even a few sentences per section makes a meaningful difference.

      +
      ## Summary
+
+One or two sentences describing what this PR does and why.
+
+## Changes Made
+
+- Bullet list of specific changes
+- One bullet per logical change
+- Reference filenames when helpful
+
+## Related Issues
+
+Closes #XX
+
+## Testing
+
+- How you verified the change works
+- Any edge cases you checked
+
+## Checklist
+
+- [ ] I tested my changes locally
+- [ ] I checked for accessibility (alt text, heading order, link text)
+- [ ] I linked the related issue
      +

      You will see a version of this template in the Learning Room's .github/PULL_REQUEST_TEMPLATE.md file. When a repository has a PR template, GitHub auto-fills the description box with it every time you open a new PR. You just fill in the blanks. See Chapter 5 for how issue templates work the same way.

      +

      Common Description Mistakes

      +

      Even experienced contributors make these mistakes. Knowing what to avoid is half the battle.

      + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + +
      MistakeWhy It HurtsBetter Version
      Empty descriptionReviewer has zero context; they may skip the PR entirelyWrite at least a Summary and Related Issues section
      "Fixed stuff" or "Updates"No one can tell what changed or why"Add missing alt text to three images on the setup page"
      Describing HOW but not WHYThe diff already shows how; the description should explain the motivation"The setup page had three images with empty alt attributes, which caused screen readers to announce 'image' with no context"
      Forgetting to link issuesThe reviewer cannot see what problem you are solving, and the issue stays open after mergeAdd Closes #XX or at minimum "Related to #XX"
      Pasting a massive paragraphHard to scan, especially with a screen readerUse Markdown headings and bullet lists to break it up
      +

      Good vs. Bad: Side by Side

      +

      Bad description:

      +
      fixed the file
      +

      That is the entire description. No context, no linked issue, no explanation of what file or what was wrong with it. A reviewer seeing this has to open the diff, figure out which file changed, read every line, and guess at the intent. Most reviewers will either skip this PR or leave a comment asking for more information -- which delays the merge.

      +

      Good description:

      +
      ## Summary
+
+Fill in the [TODO] introduction section on the welcome page so new
+visitors understand what the Learning Room is.
+
+## Changes Made
+
+- Replaced the [TODO] placeholder in docs/welcome.md with a
+  three-sentence introduction paragraph
+- Added a "What you will learn" bullet list below the introduction
+
+## Related Issues
+
+Closes #7
+
+## Testing
+
+- Opened docs/welcome.md in the VS Code preview and confirmed the
+  new text renders correctly
+- Checked heading order with the accessibility linter -- no warnings
+- Verified the [TODO] marker is completely removed
+
+## Checklist
+
+- [x] I tested my changes locally
+- [x] I checked for accessibility (alt text, heading order, link text)
+- [x] I linked the related issue
      +

      This version answers every question a reviewer has before they touch the diff. They know the file, the issue, the change, and the testing. The review conversation can focus on the content itself rather than on figuring out what the PR is about.

      +
      +

      Screen reader tip: When scanning a list of open PRs, the title and first line of the description are what you hear first. Front-load the most important information so you can triage PRs quickly using Arrow Down from the PR title.

      +
      +

      Learning Cards: Writing PR Descriptions That Get Reviewed

      +
      +Screen reader users + +
        +
      • Use Markdown headings (##) in your description (Summary, Changes, Related Issues, Testing) so reviewers can press H to jump between sections
        • +
      • Type Closes # followed by the issue number to auto-close the linked issue on merge; GitHub autocompletes when you type #
        • +
      • Press Ctrl+Shift+P in the description text area to toggle between Write and Preview modes; Preview renders your Markdown so you can check structure before submitting
        • +
      +
      + +
      +Low vision users + +
        +
      • Use the Preview tab to verify your Markdown renders correctly; headings, bullet lists, and code blocks are easier to proofread in rendered form
        • +
      • Keep bullet points short (one line each) so the description is scannable at high zoom without excessive horizontal scrolling
        • +
      • When including screenshots, add alt text in the Markdown image syntax: ![description](url) so every reader gets the same information
        • +
      +
      + +
      +Sighted users + +
        +
      • A well-structured description uses bold section headers and bullet lists; reviewers scan these visually to decide whether to dive into the diff
        • +
      • The Closes #XX link renders as a clickable cross-reference; GitHub adds a small icon showing the linked issue's state (open/closed)
        • +
      • Use the checklist syntax (- [ ] and - [x]) for your testing and accessibility checklist; these render as interactive checkboxes
        • +
      +
      + + +

      Try It: Read a Real Pull Request

      +

      Time: 3 minutes | What you need: Browser, signed in to GitHub

      +

      Go to the Learning Room repository's Pull Requests tab and find any open or recently closed PR:

      +
        +
      1. Navigate to Pull Requests (G then P in Focus Mode)
        2. +
      2. Open the first PR in the list (press Enter on its title)
        3. +
      3. Read the description - press 2 to jump to the first section heading, then arrow down to read. Look for: which file was changed (docs/welcome.md, docs/keyboard-shortcuts.md, or docs/setup-guide.md)? Which challenge was this PR solving? Does the description reference Closes #XX?
        4. +
      4. Check the conversation - press 3 to jump between comments. Read what the validation bot reported - did the bot find any accessibility issues like broken headings or non-descriptive links? How did the author respond?
        5. +
      5. Look at the diff - press D to the "Pull request tabs" landmark, then navigate to "Files changed" and press Enter. Press H to scan the changed file headings. If the PR touched docs/welcome.md, you should see + lines where the [TODO] sections were filled in. If it touched docs/keyboard-shortcuts.md, you should see new rows added to a shortcut table.
        6. +
      +

      You're done. You just read a complete PR - description, conversation, and code changes.

      +
      +

      What success feels like: You followed a PR from description to diff using only headings and landmarks. The next time you open a PR - yours or someone else's - you'll know exactly where everything is.

      +
      +
      +

      Day 2 Amplifier - Accessibility Agents: @pr-review

      +

      Review at least two pull requests manually before using any agent. A review generated by @pr-review is only as useful as your ability to read, edit, and challenge it. The agent writes a first draft - you supply the context, the history, and the final judgment that no diff can contain.

      +

      Once you have mastered manual pull request review:

      +
        +
      • In VS Code - @pr-review review PR #N generates line-numbered diffs with change maps, risk assessment, before/after snapshots, CI results, and suggested inline comments - a documented starting point for your own review, not a replacement for it
        • +
      • In your repo - Accessibility Agents' review capabilities work across every repository you have access to by default; fork accessibility-agents and those capabilities travel with your project from day one
        • +
      • In the cloud - GitHub Agentic Workflows can auto-generate PR descriptions, verify linked issues, and post accessibility impact summaries on a pull_request trigger - running the moment a PR is opened, whether or not anyone is watching
        • +
      +

      The agent documents the diff. You bring the context that no diff can contain.

      +
      +
      +

      Challenge Time: Go to the Challenge Hub and complete Challenges 4, 5, and 6 to open your first PR. Aria will guide you from there.

      +
      +
      +

      Next: Chapter 07: Merge Conflicts
      Back: Chapter 05: Working with Issues
      Related appendices: Appendix C: Markdown Reference | Appendix B: Screen Reader Cheat Sheet

      + +
      + + + + diff --git a/html/admin/qa-bundle/docs/07-merge-conflicts.html b/html/admin/qa-bundle/docs/07-merge-conflicts.html new file mode 100644 index 00000000..c26b3ee4 --- /dev/null +++ b/html/admin/qa-bundle/docs/07-merge-conflicts.html @@ -0,0 +1,834 @@ + + + + + + + Merge Conflicts - GIT Going with GitHub + + + + + + + + +
      +

      Merge Conflicts

      +
      +

      Listen to Episode 7: Merge Conflicts Are Not Scary - 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 G: VS Code Reference +Authoritative sources: GitHub Docs: Resolving merge conflicts | Git SCM: Basic Merge Conflicts

      +
      +

      Understanding, Preventing, and Resolving Conflicts

      +
      +

      Merge conflicts sound intimidating but are a normal, manageable part of collaborative development. This guide explains what conflicts are, how to read conflict markers, and how to resolve them - step by step.

      +
      +

      Workshop Recommendation (Chapter 7)

      +

      Chapter 7 uses one controlled practice challenge so students can learn conflict resolution without high-pressure scenarios.

      +
        +
      • Challenge count: 1
        • +
      • Time: under 10 minutes
        • +
      • Evidence: issue-linked PR and completion comment
        • +
      • Pattern: observe, resolve, verify
        • +
      +

      Chapter 7 Challenge Set

      +
        +
      1. Resolve conflict markers - identify and clean up conflict markers in a practice file, then open a linked PR.
        2. +
      +
      +

      Branch guidance for Chapter 7: Use a short-lived feature branch: fix/yourname-issueXX (for example, fix/maria-issue48). The same pattern you used in Chapter 6.

      +
      +

      Challenge 7.1 Step-by-Step: Resolve Conflict Markers

      +

      Goal: Identify the three types of conflict markers in a practice file, decide which content to keep, remove the markers, and submit a clean PR.

      +
      +

      Agentic strategy: Sometimes an AI agent will confidently generate code that conflicts with human-written code. Resolving merge conflicts is not just a hurdle for human teamwork; it is exactly how you supervise, correct, and collaborate safely with an AI.

      +
      +

      Where you are working: your Learning Room repository on GitHub.com (web editor) or in VS Code if you cloned locally.

      +

      Before you start: Open your assigned Chapter 7 challenge issue (the one titled "Chapter 7.1: Resolve Conflict Markers (@yourname)"). The issue description tells you which practice file contains the conflict markers.

      +

      Practice sample: learning-room/docs/samples/chapter-6-conflict-practice-sample.md

      +
        +
      1. Open the practice file specified in your challenge issue.
        2. +
      2. Search the file for <<<<<<<. This is the start marker - it shows where the conflict begins.
        3. +
      3. Read the content between <<<<<<< and =======. This is your version (the current branch).
        4. +
      4. Read the content between ======= and >>>>>>>. This is their version (the incoming branch).
        5. +
      5. Decide which content to keep:
          +
        • Keep only your version, or
          • +
        • Keep only their version, or
          • +
        • Combine both versions into one clean paragraph.
          • +
        +
        6. +
      6. Delete all three marker lines:
          +
        • The <<<<<<< HEAD line (or similar)
          • +
        • The ======= separator line
          • +
        • The >>>>>>> branch-name line
          • +
        +
        7. +
      7. Review the file to confirm no marker lines remain. Search for <<<<<<< again - there should be zero results.
        8. +
      8. Commit your changes on a branch named fix/yourname-issueXX.
        9. +
      9. Open a pull request with:
          +
        • Title: fix: resolve conflict markers in [filename]
          • +
        • Body: Include Closes #XX (your challenge issue number) and a 1-2 sentence description of which content you kept and why.
          • +
        +
        10. +
      +

      Screen reader tip: Use your screen reader's find command (Ctrl+F in browser, Ctrl+H in VS Code) to jump directly to <<<<<<<. The markers are plain text, so they are fully readable.

      +

      You are done when: Your PR passes bot validation checks and contains no remaining conflict markers.

      +

      Completing Chapter 7: Submit Your Evidence

      +

      When your PR is open and passing checks, post a comment on your assigned Chapter 7 challenge issue:

      +
      Chapter 7 completed:
+- Challenge 7.1: Opened PR #[number] resolving conflict markers in [filename]
+- Content decision: kept [your version / their version / combined both] because [reason]
      +

      Expected Outcomes

      +
        +
      • Student can identify the three conflict marker lines (<<<<<<<, =======, >>>>>>>) immediately.
        • +
      • Student can read both sides of a conflict and make an intentional content decision.
        • +
      • Student can remove all markers and submit a clean, issue-linked PR.
        • +
      +

      If You Get Stuck

      +
        +
      1. Can't find the markers? Use Ctrl+F and search for <<<<<<< - they are always in sets of three.
        2. +
      2. Not sure which side to keep? Read both versions aloud. Pick the one that is clearer, or combine them.
        3. +
      3. Accidentally deleted too much? Undo with Ctrl+Z and start the section over.
        4. +
      4. PR bot says content is wrong? Double-check that zero marker lines remain - search for <<<<<<<, =======, and >>>>>>>.
        5. +
      5. Ask facilitator to sanity-check your final content before opening the PR.
        6. +
      6. Finished but not sure you did it right? Compare your work against the Challenge 7 reference solution.
        7. +
      +

      Learning Moment

      +

      Merge conflicts are not failures. They are a normal collaboration checkpoint and a chance to make an intentional content decision. In real open source projects, conflicts happen whenever two people edit near the same lines. The skill is not avoiding them - it is resolving them calmly and clearly.

      +

      Learning Pattern Used in This Chapter

      +
        +
      1. Start with a controlled, safe conflict (practice file with known markers).
        2. +
      2. Learn to read the conflict structure (your version vs. their version).
        3. +
      3. Make a deliberate content decision (not just deleting randomly).
        4. +
      4. Submit clean evidence through the PR workflow.
        5. +
      5. Build confidence for real conflicts in future contributions.
        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.

      + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + +
      CardWho it helpsWhat it covers
      Visual / mouseSighted users navigating with a mouse or trackpadClick targets, visual cues, color-coded conflict regions
      Low visionUsers with magnification, zoom, or high-contrast themesZoom-friendly navigation, high contrast marker visibility, enlargement tips
      NVDA / JAWS (Windows)Screen reader users on WindowsKeystroke sequences, Focus and Browse mode, verbosity tips
      VoiceOver (macOS)Screen reader users on macOSVO key sequences, rotor navigation, interaction model
      CLI (git / gh)Terminal users on any platformGit and GitHub CLI commands for conflict detection and resolution
      +

      Local Git Alternative: Resolving Conflicts from Your Terminal

      +
      +If you cloned the learning-room in Block 0 and prefer resolving conflicts locally + +

      The GitHub web conflict editor works well and is the primary method taught in this chapter. If you cloned the Learning Room in Block 0 and prefer working in your terminal, here is how to resolve conflicts locally. This is the same workflow covered in depth in Chapter 11: Git and Source Control.

      +

      Step 1 - Sync main and merge into your branch:

      +
      cd ~/Documents/learning-room
+git checkout main
+git pull origin main
+git checkout your-branch-name
+git merge main
      +

      If there is a conflict, Git will report which files are affected and stop the merge.

      +

      Step 2 - Open the conflicted file:

      +
      code docs/welcome.md   # or your preferred editor
      +

      Look for the conflict markers:

      +
      <<<<<<< HEAD
+Your version of the content
+=======
+The incoming version from main
+>>>>>>> main
      +

      Step 3 - Resolve by editing:

      +
        +
      • Keep the version you want (or combine both)
        • +
      • Delete all three marker lines (<<<<<<<, =======, >>>>>>>)
        • +
      • Save the file
        • +
      +

      Step 4 - Mark resolved, commit, and push:

      +
      git add docs/welcome.md
+git commit -m "Resolve merge conflict in welcome.md"
+git push
      +

      Your PR on GitHub updates automatically with the resolved content. The same bot checks and human review process apply.

      +
      + + +

      What Is a Merge Conflict?

      +

      A merge conflict occurs when two people have both changed the same part of the same file in different ways, and Git cannot automatically decide which version is correct.

      +

      Git can merge changes automatically when they touch different parts of a file. Conflicts only happen when two changes overlap - for example:

      +
        +
      • Person A changed line 12 to say "Submit form"
        • +
      • Person B changed line 12 to say "Send message"
        • +
      • Git asks: which one do you want to keep?
        • +
      +

      Why Conflicts Happen

      +

      The most common causes:

      + + + + + + + + + + + + + + + + + + + + + + + +
      CauseExample
      Two people edited the same lineYou both fixed the same typo differently
      One person deleted a file but another edited itYou removed an old function; they fixed a bug in it
      Two people restructured the same sectionYou reorganized a list; they added items to it
      A long-running PR diverged from mainYour branch is weeks old and main has changed significantly
      +

      How to Prevent Conflicts (Prevention is Easier Than Resolution)

      +

      Avoiding conflicts in the first place saves time and reduces stress. Here are the most effective strategies:

      +

      1. Keep your branches short-lived

      +

      Work in small, focused chunks. A branch that lives for 3 days has far fewer conflicts than one that lives for 3 weeks.

      +
        +
      • Target: 1-3 days from branch to merge
        • +
      • If a feature takes longer, break it into smaller PRs
        • +
      +

      2. Sync with main frequently

      +

      The longer your branch diverges from main, the more likely conflicts become.

      +

      Best practice: Sync daily if main is active:

      +
      # From your feature branch
+git fetch origin
+git merge origin/main
+# Or: git rebase origin/main (if comfortable with rebasing)
      +

      GitHub web method: Use the "Update branch" button on your PR if it appears.

      +

      3. Communicate with your team

      +

      Let others know what files you're working on. Use issue comments:

      +
      +

      "Heads up: I'm working on the [TODO] sections in docs/welcome.md for Challenge 3. If you're also editing welcome.md, let's coordinate so we don't conflict."

      +
      +

      In the Learning Room, this is especially important because multiple students may claim challenges that touch the same file. Challenges 1 and 3 both modify docs/welcome.md - if two students work on both simultaneously without coordinating, a merge conflict will occur.

      +

      4. Avoid mass reformatting

      +

      Running a formatter on an entire file creates conflicts with anyone else editing that file. If you must:

      +
        +
      • Do it in a separate PR before functional changes
        • +
      • Announce it to the team
        • +
      • Merge it quickly so everyone can sync
        • +
      +

      5. Pull before you push

      +

      Always fetch and merge (or pull) before pushing your changes:

      +
      git pull origin main  # Sync your local main
+git checkout your-branch
+git merge main        # Merge main into your branch
+git push              # Now push
      +

      This catches conflicts locally where they're easier to resolve.

      +

      6. Work on separate files when possible

      +

      If multiple people are working simultaneously, divide tasks by files or modules rather than everyone touching the same code.

      +

      7. Keep PRs small

      +

      A 50-file PR will almost certainly conflict with something. A 5-file PR merges quickly and cleanly.

      +

      The most effective contributors make many small PRs rather than one giant one.

      +

      8. Use Draft PRs for early visibility

      +

      Open your PR as a draft while still working. Others can see what you're changing and avoid overlapping work. Convert to "Ready for review" when done.

      +

      Learning Cards: How to Prevent Conflicts

      +
      +Screen reader users + +
        +
      • Before starting work, run git pull origin main in VS Code's terminal (Ctrl+`) to sync your branch; this prevents conflicts from stale branches
        • +
      • On GitHub, check the PR's merge status section by pressing D toward the bottom of the Conversation tab; "This branch has conflicts" warns you before you waste review time
        • +
      • Use issue comments to announce which files you are editing; press D to the "Add a comment" landmark on the issue and type your coordination message
        • +
      +
      + +
      +Low vision users + +
        +
      • The "Update branch" button on a PR appears near the merge section at the bottom of the Conversation tab; it has a white-on-green style when available
        • +
      • When multiple students are editing the same file, GitHub shows a yellow conflict banner; zoom in on the merge area to check for it before requesting review
        • +
      • Draft PRs show a grey "Draft" badge in the PR list; opening drafts early gives teammates visibility into which files you are changing
        • +
      +
      + +
      +Sighted users + +
        +
      • Keep your PR small: a 5-file PR merges quickly and rarely conflicts; a 50-file PR almost certainly will
        • +
      • The "Update branch" button appears on PRs that are behind the base branch; click it to merge the latest changes from main into your branch
        • +
      • Draft PRs are shown with a grey "Draft" label in the PR list view; open them early so teammates can see your in-progress file changes
        • +
      +
      + + +

      Advanced Prevention: Understanding Fast-Forward Merges

      +

      When your branch is perfectly up to date with main and adds new commits on top, GitHub can do a "fast-forward" merge - main simply moves forward to your latest commit. No merge commit needed. No possibility of conflicts.

      +

      How to achieve this: Rebase your branch on main right before merging:

      +
      git checkout your-branch
+git fetch origin
+git rebase origin/main
+git push --force-with-lease  # See warning below about force pushing
      +

      Warning: Force pushing rewrites history. Only do this on branches you alone control (not shared branches). Never force push to main.

      +

      For more on force pushing and rebasing, see the Glossary.

      +

      When Conflicts Are Actually Good

      +

      Conflicts indicate that multiple people are actively improving the project. In a healthy, collaborative environment, occasional conflicts are normal and manageable.

      +

      If you never have conflicts, it might mean:

      +
        +
      • You're the only contributor (less review, less learning)
        • +
      • PRs are moving too slowly (stagnation)
        • +
      • People are avoiding working on important files (technical debt)
        • +
      +

      The goal isn't zero conflicts. The goal is catching them early, resolving them cleanly, and learning patterns that reduce future conflicts.

      +

      Spotting a Conflict on GitHub

      +

      Tool Cards: Resolve a Merge Conflict

      +

      github.com (browser):

      +
        +
      1. On the PR page, click Resolve conflicts if the button is available.
        2. +
      2. Edit the file in the web editor to remove conflict markers.
        3. +
      3. Click Mark as resolved, then Commit merge.
        4. +
      +

      github.dev (web editor):

      +
        +
      1. Open the PR's branch by pressing . on the repository page.
        2. +
      2. Open the conflicting file -- conflict markers are highlighted in the editor.
        3. +
      3. Edit to resolve, commit via Source Control panel.
        4. +
      +

      VS Code Desktop:

      +
        +
      1. Pull the latest changes: git pull origin main.
        2. +
      2. VS Code highlights conflicts with Accept Current / Accept Incoming / Accept Both buttons.
        3. +
      3. Click your choice, save, stage, and commit.
        4. +
      +

      GitHub Desktop:

      +
        +
      1. Branch > Update from main (or the merge prompt banner).
        2. +
      2. GitHub Desktop opens your editor with conflict markers highlighted.
        3. +
      3. Resolve in the editor, return to GitHub Desktop, and click Commit merge.
        4. +
      +

      Git CLI (terminal):

      +
      git merge main
+# Edit conflicting files to remove <<<<<<< / ======= / >>>>>>>
+git add resolved-file.md
+git commit -m "resolve merge conflict"
      +

      When a PR has a merge conflict, you will see this message on the Conversation tab, near the merge section:

      +
      +

      “This branch has conflicts that must be resolved”

      +
      +

      You will also see a “Resolve conflicts” button. If you cannot see it (it may require write access), contact the PR author.

      +
      +Visual / mouse users + +

      Scroll to the bottom of the Conversation tab. The conflict message appears as a yellow or orange banner above the merge button area. Click Resolve conflicts to open the web conflict editor.

      +
      + +
      +Low vision users (zoom, high contrast) + +

      The conflict banner sits near the bottom of the Conversation tab, above the merge button area. If your browser zoom is at 200% or higher, you may need to scroll past lengthy comment threads to reach it.

      +
        +
      • The banner uses a yellow or orange background. In Windows High Contrast mode, it renders with the system alert color so it remains visible.
        • +
      • The Resolve conflicts button is a standard link-style button. If it is hard to target at high zoom, use Tab to reach it after the merge status section and press Enter.
        • +
      • If the button does not appear, you may lack write access to the repository. Ask the PR author or a maintainer for help.
        • +
      +
      + +
      +Screen reader users (NVDA / JAWS - Windows) + +
        +
      1. Press D to reach the bottom of the Conversation tab
        2. +
      2. Navigate down with H or ↓ past the comment threads
        3. +
      3. Find the heading or region containing "This branch has conflicts"
        4. +
      4. Press B to find the Resolve conflicts button → Enter
        5. +
      +
      + +
      +Screen reader users (VoiceOver - macOS) + +
        +
      1. VO+U → Landmarks or VO+Down to move toward the bottom of the Conversation tab
        2. +
      2. Quick Nav H or VO+Cmd+H past comment headings until you reach the conflict notice
        3. +
      3. Quick Nav B to find the Resolve conflicts button → VO+Space
        4. +
      +
      + + +

      Conflict Markers - What They Mean

      +

      When conflict markers appear in a file, your editor is showing you both versions of the conflicted content so you can choose. The format is always:

      +
      <<<<<<< HEAD
+The content that is on YOUR current branch
+=======
+The content coming from the OTHER branch (or main)
+>>>>>>> branch-name-or-commit-hash
      +

      Breakdown

      +
        +
      • <<<<<<< HEAD - the start of YOUR version (HEAD = "the branch you are currently on")
        • +
      • ======= - the dividing line between the two versions
        • +
      • >>>>>>> branch-name - the end of the INCOMING version (from the branch being merged in)
        • +
      +

      Example in a real file

      +

      Original file (docs/keyboard-shortcuts.md) before conflict

      +
      | Insert+Space | Toggle between Browse Mode and Focus Mode |
      +

      After two students both added a shortcut to the same table row

      +
      <<<<<<< HEAD
+  Insert+Space -- Toggle between Browse Mode and Focus Mode
+  Insert+F5 -- List elements by type
+=======
+  Insert+Space -- Toggle between Browse Mode and Focus Mode
+  Insert+F7 -- Elements list (links, headings, form fields)
+>>>>>>> add-nvda-shortcut
      +

      Resolution options

      +
        +
      1. Keep your version: add only Insert+F5
        2. +
      2. Keep their version: add only Insert+F7
        3. +
      3. Keep both rows: add both shortcuts to the table (often the right answer when two students added different valid shortcuts)
        4. +
      +

      Learning Cards: Conflict Markers

      +
      +Screen reader users + +
        +
      • Conflict markers are three lines: <<<<<<< HEAD, =======, and >>>>>>> branch-name; your screen reader may spell out each <, =, and > character individually
        • +
      • Everything between <<<<<<< HEAD and ======= is YOUR version; everything between ======= and >>>>>>> is the INCOMING version
        • +
      • After resolving, search the file for <<<< using Ctrl+F to verify no markers remain; any leftover markers will break the file
        • +
      +
      + +
      +Low vision users + +
        +
      • In GitHub's conflict editor, each version is highlighted with a different background color (typically green for yours, blue for incoming); high-contrast themes use bolder system colors
        • +
      • The three marker lines (<<<, ===, >>>) span the full width of the editor; look for rows that contain only repeated symbols
        • +
      • After resolving, zoom in on the edited area and confirm the marker lines are completely deleted, not just partially removed
        • +
      +
      + +
      +Sighted users + +
        +
      • Conflict markers appear as three distinctive lines of repeated symbols: <<<<<<<, =======, and >>>>>>>; they visually bracket the two conflicting versions
        • +
      • The HEAD label after <<<<<<< means "your current branch"; the branch name after >>>>>>> identifies where the incoming change came from
        • +
      • After editing, delete all three marker lines plus the version you do not want; the remaining content should read naturally as valid code or Markdown
        • +
      +
      + + +

      Resolving Conflicts on GitHub (Web Editor)

      +

      GitHub has a built-in conflict editor that you can use without any local tools.

      +

      Step-by-step: GitHub Conflict Editor

      +
      +Visual / mouse users + +
        +
      1. Click Resolve conflicts on the PR Conversation tab
        2. +
      2. GitHub opens a full-page text editor showing each conflicted file
        3. +
      3. The conflict markers are highlighted - everything between <<<<<< and ======= is your version; between ======= and >>>>>>> is the incoming version
        4. +
      4. Edit the content directly: delete the lines you don’t want, including the three marker lines (<<<, ===, >>>)
        5. +
      5. When the file looks correct, click Mark as resolved (top-right of the file)
        6. +
      6. If there are multiple conflicted files, a file list on the left lets you jump between them
        7. +
      7. After all files are resolved, click Commit merge
        8. +
      +
      + +
      Low vision users (zoom, high contrast) + +
        +
      1. Open the conflict editor from the Resolve conflicts button on the PR Conversation tab.
        2. +
      2. GitHub opens a monospace text editor. At 200% zoom or higher, the editor scrolls horizontally. Use Shift+Scroll or horizontal scrollbar to navigate wide lines.
        3. +
      3. Conflict markers (<<<<<<<, =======, >>>>>>>) are displayed in highlighted bands. In high-contrast themes, the markers use distinct system colors for good visibility.
        4. +
      4. The file list panel (left side) may collapse at high zoom levels. Look for a toggle or hamburger icon in the top-left corner to reopen it.
        5. +
      5. Edit directly in the editor: delete unwanted lines, including all three marker lines.
        6. +
      6. Click Mark as resolved in the top-right. At high zoom, this button may require horizontal scrolling to find. You can also Tab to reach it.
        7. +
      7. After all files are resolved, click Commit merge.
        8. +
      +

      Tip: Increase your browser's minimum font size (Settings, Appearance, Font size) for a more comfortable editing experience in the conflict editor. This setting persists across GitHub pages.

      +
      + +
      Screen reader users (NVDA / JAWS - Windows) + +
        +
      1. Activate the Resolve conflicts button from the PR Conversation tab
        2. +
      2. GitHub opens the conflict editor - a full-page text editor
        3. +
      3. Navigate between conflicted files using the file list (press NVDA+F7 or VO+U to find the file navigation panel)
        4. +
      4. Switch to Focus Mode (NVDA+Space) to enter the text editor
        5. +
      5. Read the conflict markers line by line with ↓:
          +
        • <<<<<<< HEAD marks the start of your version
          • +
        • ======= is the dividing line
          • +
        • >>>>>>> branch-name marks the end of the incoming version
          • +
        +
        6. +
      6. Edit to keep the desired content - delete the conflict marker lines and the version you don't want
        7. +
      7. Tab to Mark as resolved button → Enter
        8. +
      8. Repeat for all conflicted files
        9. +
      9. Tab to Commit merge button → Enter
        10. +
      +
      + +
      +Screen reader users (VoiceOver - macOS) + +
        +
      1. Activate the Resolve conflicts button from the PR Conversation tab
        2. +
      2. GitHub opens the conflict editor - a full-page text editor
        3. +
      3. VO+U → navigate to the file navigation panel to switch between conflicted files
        4. +
      4. VO+Shift+Down to interact with the text editor
        5. +
      5. VO+Down to read the conflict markers line by line:
          +
        • <<<<<<< HEAD marks the start of your version
          • +
        • ======= is the dividing line
          • +
        • >>>>>>> branch-name marks the end of the incoming version
          • +
        +
        6. +
      6. Edit to keep the desired content - delete the conflict marker lines and the version you don't want
        7. +
      7. VO+Shift+Up to stop interacting, then Tab to Mark as resolved → VO+Space
        8. +
      8. Repeat for all conflicted files
        9. +
      9. Tab to Commit merge → VO+Space
        10. +
      +
      + +

      What it looks like in the editor

      +

      When the conflict editor opens, your screen reader will announce a text editor. In Focus Mode, navigate with arrow keys. The content reads:

      +
      <  <  <  <  <  <  <  H  E  A  D
+<button aria-label="Submit form">Submit</button>
+=  =  =  =  =  =  =
+<button type="submit">Send message</button>
+>  >  >  >  >  >  >  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 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, 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. +
      2. Press ↓ to navigate to a conflict marker (<<<<<<<)
        3. +
      3. The CodeLens links appear above - press Tab to reach them
        4. +
      4. Press Enter on your chosen action
        5. +
      5. Save the file (Ctrl+S)
        6. +
      6. Stage the resolved file: Ctrl+Shift+G → find the file → Stage changes
        7. +
      7. Commit the merge
        8. +
      +

      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. +
      2. VO+Down or arrow keys to navigate to a conflict marker (<<<<<<<)
        3. +
      3. The CodeLens links appear above - Tab to reach them
        4. +
      4. VO+Space on your chosen action
        5. +
      5. Save the file (Cmd+S)
        6. +
      6. Stage the resolved file: Cmd+Shift+G → find the file → Stage changes
        7. +
      7. Commit the merge
        8. +
      +

      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. +
      2. Tag the PR author or a maintainer with @username
        3. +
      +

      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. +
      2. Start a new branch from the latest main
        3. +
      3. Apply only your intended changes to the new branch
        4. +
      4. Open a new PR
        5. +
      +

      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:

      +
      CONFLICT (content): Merge conflict in src/index.html
+Automatic merge failed; fix conflicts and then commit the result.
      +

      And git status will show:

      +
      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:

      +
      # 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:

      +
      # 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

      +
      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:

      +
      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. +
      2. What does the other branch say? (The text between ======= and >>>>>>>)
        3. +
      3. Which version would you keep, and why?
        4. +
      +

      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 for Challenge 7: Survive a Merge Conflict. Follow the steps to resolve it, then move to Chapter 08: Open Source Culture.

      +
      +
      +

      Next: Chapter 08: Open Source Culture
      Back: Chapter 06: Working with Pull Requests
      Related appendices: Appendix E: Advanced Git

      + +
      + + + + diff --git a/html/admin/qa-bundle/docs/08-open-source-culture.html b/html/admin/qa-bundle/docs/08-open-source-culture.html new file mode 100644 index 00000000..2f05abef --- /dev/null +++ b/html/admin/qa-bundle/docs/08-open-source-culture.html @@ -0,0 +1,1197 @@ + + + + + + + Culture, Etiquette, and Community Standards - GIT Going with GitHub + + + + + + + + +
      +

      Culture, Etiquette, and Community Standards

      +
      +

      Listen to Episode 8: Open Source Culture and Etiquette - 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 F: Git Security | Appendix O: Branch Protection | Appendix W: GitHub Pages +Authoritative sources: GitHub Docs: Contributing to open source | Open Source Guides: 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.
        2. +
      +

      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. +
      2. As you read, think about one situation from Day 1 where communication helped (or could have helped) you.
        3. +
      3. Open your assigned Chapter 8 challenge issue (the one titled "Chapter 8.1: Guided Reflection (@yourname)").
        4. +
      4. Scroll to the comment box at the bottom of the issue.
        5. +
      5. Post a reflection comment using this format:
        6. +
      +
      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:
      +
        +
      1. 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."
          • +
        +
        2. +
      2. Activate the Comment button (or press Ctrl+Enter).
        3. +
      +

      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. +
      2. Focus on one real behavior you can start doing today, not an abstract principle.
        3. +
      3. If writing feels hard, draft bullet points first in a text editor, then paste into the comment.
        4. +
      4. Look at the "Giving Feedback" and "Asking for Help" sections in this chapter for concrete examples.
        5. +
      5. Ask facilitator for one example response and adapt it to your own words.
        6. +
      6. Finished but not sure you did it right? Compare your work against the Challenge 8 reference solution.
        7. +
      +

      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. +
      2. Reflect on personal experience (what worked, what was hard).
        3. +
      3. Commit to specific behaviors in writing (public accountability).
        4. +
      4. Apply those behaviors in upcoming chapters (reviews, comments, PRs).
        5. +
      +

      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

      +
      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.

      + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + +
      BranchLifetimePurpose
      main (or master)PermanentAlways reflects the latest production release. Only receives merges from release/ or hotfix/ branches.
      developPermanentIntegration branch where completed features accumulate. Represents the next planned release.
      feature/TemporaryBranched from develop. One branch per feature. Merged back into develop when complete. Deleted after merge.
      release/TemporaryBranched 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/TemporaryBranched 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. +
      2. Completed features merge back into develop via pull request.
        3. +
      3. When develop has enough features for a release, a release/1.2.0 branch is created.
        4. +
      4. The release branch gets final testing, bug fixes, and version number updates.
        5. +
      5. The release branch merges into main (tagged with the version) and back into develop.
        6. +
      6. If a critical bug is found in production, a hotfix/ branch is created from main, fixed, and merged into both main and develop.
        7. +
      +

      How GitHub Flow Differs

      +

      The following table compares GitHub Flow and Git Flow across key dimensions.

      + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + +
      DimensionGitHub FlowGit Flow
      Long-lived branchesmain onlymain and develop (plus temporary release/ and hotfix/)
      Feature workBranch off main, PR back to mainBranch off develop, PR back to develop
      ReleasesEvery merge to main is deployableExplicit release/ branches with version numbers
      HotfixesSame as any other PR to mainDedicated hotfix/ branch merged to both main and develop
      ComplexityLow - one rule: main is always deployableHigh - multiple branch types with specific merge targets
      Best forContinuous deployment, web apps, open sourceScheduled 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. +
      2. Look for the sync indicator: "This branch is X commits behind upstream/main"
        3. +
      3. Click the "Sync fork" button
        4. +
      4. Click "Update branch"
        5. +
      +

      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. +
      2. The sync button appears in the landmark that contains the branch selector
        3. +
      3. Press D to cycle through landmarks until you reach that region
        4. +
      4. Press B to cycle buttons until you hear "Sync fork" → press Enter
        5. +
      5. A dialog or page update presents "Update branch" - activate it
        6. +
      +
      + +

      Method 2: Git Command Line (VS Code Terminal)

      +

      If you're working locally in VS Code:

      +

      One-time setup - add the upstream remote

      +
      git remote add upstream https://github.com/original-owner/repo-name.git
+git remote -v  # Verify it was added
      +

      Sync process

      +
      # 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. +
      2. Select Repository → Pull to get your fork's latest
        3. +
      3. Select Branch → Merge into Current Branch
        4. +
      4. Choose upstream/main
        5. +
      5. Push the changes to your fork on GitHub
        6. +
      +

      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

      +
      <type>: <short summary in imperative mood>
+
+<optional body: more detailed explanation>
+
+<optional footer: references to issues>
      +

      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:

      +
      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.
      + +

      Link commits to issues or PRs:

      +
      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

      +
      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
      +
      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. +
      2. Activate "Add a saved reply"
        3. +
      3. Give it a title (e.g., "Good first issue claim") - this is what you search for
        4. +
      4. Type the full reply text in the body (Markdown is supported)
        5. +
      5. Save
        6. +
      +

      Using a Saved Reply in a comment

      +
        +
      1. Navigate to any comment text area
        2. +
      2. Activate the Saved Replies button (the speech bubble icon in the comment toolbar, or press Ctrl+. if enabled)
        3. +
      3. A dropdown appears showing your saved replies - type to filter by title
        4. +
      4. Select the reply - it inserts into the text area
        5. +
      5. Edit as needed before submitting
        6. +
      +

      Screen reader path

      +
      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 <span> 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. +
      2. Wait for assignment - do not start until assigned; two people working in parallel wastes everyone's time
        3. +
      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. +
      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. +
      5. Don't disappear - if you claim an issue, see it through or explicitly hand it back
        6. +
      +

      Handling Difficult Situations

      +

      When you receive harsh feedback

      +
        +
      1. Take a breath before responding - there is no urgency; the thread will wait
        2. +
      2. Look for the valid concern underneath the harsh words
        3. +
      3. Respond to the concern, not the tone
        4. +
      4. If the behavior crosses into harassment, report it via the "..." button on the comment → "Report"
        5. +
      +

      When you disagree with a decision

      +
        +
      1. Make your case once, clearly and with evidence
        2. +
      2. Accept that the maintainer has the final say in their project
        3. +
      3. If you strongly disagree, you can fork the project and take it in a different direction - this is legitimate in open source
        4. +
      +

      When someone is rude to you

      +
        +
      1. You do not have to engage
        2. +
      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. +
      3. Report via GitHub's reporting tools if the behavior is abusive
        4. +
      +

      When you accidentally caused offense

      +
        +
      1. Acknowledge it directly: "I can see how that came across as dismissive - that wasn't my intention."
        2. +
      2. Do not over-explain or defend excessively
        3. +
      3. Adjust going forward
        4. +
      +

      Writing Your First README

      +
      +

      See also: Appendix W: GitHub Pages 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:

      + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + +
      SectionWhat it answers
      Project nameWhat is this?
      DescriptionWhy does it exist? What problem does it solve?
      InstallationHow do I get it running on my machine?
      UsageHow do I use it once it is installed?
      ContributingHow can I help? (or link to CONTRIBUTING.md)
      LicenseWhat 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

      +
      # 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 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, 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 and Appendix P: Security Features 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 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

      + + + + + + + + + + + + + + + + + + + + + + + + + + + +
      ChannelUse For
      IssueBug reports, feature requests, questions about a specific problem
      PR commentFeedback on a specific code change
      PR reviewFormal verdict (approve/request changes) with consolidated feedback
      DiscussionOpen-ended conversation, proposals, community Q&A
      Email / directSensitive 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. +
      2. Why it matters
        3. +
      3. What you suggest
        4. +
      4. Why the suggestion helps
        5. +
      5. Encouragement
        6. +
      +

      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 +Back: Merge Conflicts +Related: Working with Issues | Working with Pull Requests

      +
      +

      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 - 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?
        2. +
      2. Who Can Contribute?
        3. +
      3. What Makes a Good First Contribution?
        4. +
      4. Finding Something to Work On
        5. +
      5. Reading an Issue Before You Start
        6. +
      6. Making Your Contribution
        7. +
      7. Getting Help
        8. +
      8. After Your Contribution Is Merged
        9. +
      9. Building a Contribution Habit
        10. +
      +

      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:

      + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + +
      LabelMeaning
      good first issueExplicitly recommended for first-time contributors
      first-timers-onlyReserved for people making their first contribution to this project
      help wantedMaintainers are actively looking for someone to pick this up
      beginner or easyLower complexity than average
      documentationNo coding required - writing or editing docs
      accessibilityDirectly 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. +
      2. Edit files directly in your fork's web interface.
        3. +
      3. Click Contribute > Open pull request to submit back to the original.
        4. +
      +

      github.dev (web editor):

      +
        +
      1. Fork the repo on github.com first.
        2. +
      2. Navigate to your fork and press . to open in the web editor.
        3. +
      3. Edit, commit, and create a PR from the Source Control panel.
        4. +
      +

      VS Code Desktop:

      +
        +
      1. Fork on github.com, then clone your fork: Ctrl+Shift+P > Git: Clone.
        2. +
      2. Create a branch, make edits, commit and push.
        3. +
      3. Use GitHub Pull Requests: Create Pull Request to submit.
        4. +
      +

      GitHub Desktop:

      +
        +
      1. File > Clone Repository, select your fork.
        2. +
      2. Create a branch via Branch > New Branch, make edits.
        3. +
      3. Push and click Create Pull Request (opens browser).
        4. +
      +

      Git CLI / GitHub CLI:

      +
      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. +
      2. Clone your fork to your computer (or open a Codespace - see Appendix N)
        3. +
      3. Create a branch - name it something descriptive: fix/broken-link-setup-guide
        4. +
      4. Make your change - edit the file, save, verify
        5. +
      5. Commit with a clear message - "Fix broken link in setup-guide.md line 34"
        6. +
      6. Push to your fork
        7. +
      7. Open a pull request from your branch to the original repository's default branch
        8. +
      8. Respond to review feedback - maintainers may ask for changes; this is normal and not a rejection
        9. +
      +

      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, then advance to Chapter 09: Labels, Milestones and Projects.

      +
      +
      +

      Next: Chapter 09: Labels, Milestones, and Projects
      Back: Chapter 07: Merge Conflicts
      Related appendices: Appendix M: Accessibility Standards | Appendix F: Git Security | Appendix O: Branch Protection

      + +
      + + + + diff --git a/html/admin/qa-bundle/docs/09-labels-milestones-projects.html b/html/admin/qa-bundle/docs/09-labels-milestones-projects.html new file mode 100644 index 00000000..70996453 --- /dev/null +++ b/html/admin/qa-bundle/docs/09-labels-milestones-projects.html @@ -0,0 +1,765 @@ + + + + + + + Labels, Milestones, and Projects - GIT Going with GitHub + + + + + + + + +
      +

      Labels, Milestones, and Projects

      +
      +

      Listen to Episode 9: Labels, Milestones, and Projects - 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 A: Glossary +Authoritative sources: GitHub Docs: About labels | GitHub Docs: About milestones | GitHub Docs: 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.
        2. +
      +

      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. +
      2. Find any open issue that does not already have labels applied (or pick one your facilitator assigns).
        3. +
      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. +
      4. Open your assigned Chapter 9 challenge issue (the one titled "Chapter 9.1: Triage Recommendation (@yourname)").
        5. +
      5. Scroll to the comment box and post a triage recommendation using this format:
        6. +
      +
      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]
      +
        +
      1. If you have write access to the repository, apply the recommended labels and milestone directly on the issue you triaged.
        2. +
      2. Activate the Comment button.
        3. +
      +

      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. +
      2. Milestone is unclear? Write none and explain why - that is a valid triage decision.
        3. +
      3. Project board is unknown? Write Needs Triage - that is the correct default.
        4. +
      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. +
      5. Ask facilitator to review your one-sentence reason before posting.
        6. +
      +

      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 covers labels, milestones, and contributor settings in an interactive, self-paced format. See Appendix Z for the full catalog.

      +
      +

      Learning Pattern Used in This Chapter

      +
        +
      1. Inspect an issue carefully before acting (read before you write).
        2. +
      2. Classify work using a consistent vocabulary (labels, milestones).
        3. +
      3. Explain your reasoning in writing (one-sentence justification).
        4. +
      4. Build triage instincts that transfer to any open source project.
        5. +
      +

      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

      + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + +
      LabelPurpose
      bugSomething isn't working as expected
      enhancementA new feature or improvement
      documentationChanges or additions to documentation only
      good first issueSuitable for first-time contributors
      help wantedMaintainers are actively seeking community help
      questionMore information is needed before action
      invalidThe issue doesn't meet the project's criteria
      wontfixThe project won't address this (by design or out of scope)
      duplicateAnother open issue covers the same topic
      accessibilityAccessibility-related issue or change
      needs triageNot 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. +
      2. Press K to find the "Labels" link (near the "Milestones" link in the toolbar)
        3. +
      3. Press Enter
        4. +
      +
      + +
      +Screen reader users (VoiceOver - macOS) + +
        +
      1. Navigate to the Issues tab
        2. +
      2. Quick Nav K to find the "Labels" link (near the "Milestones" link in the toolbar)
        3. +
      3. VO+Space to activate
        4. +
      +
      + +
      +GitHub CLI (gh) alternative - viewing labels + +

      List all labels in a repository from your terminal:

      +
      # 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. +
      2. In the right sidebar, click the gear icon next to Labels.
        3. +
      3. Select labels from the dropdown, then click outside to apply.
        4. +
      +

      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. +
      2. Click the label area to add or remove labels.
        3. +
      +

      GitHub Desktop: +Not directly supported. Use Repository > View on GitHub to manage labels in the browser.

      +

      Git CLI / GitHub CLI:

      +
      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. +
      2. Activate the Labels gear/edit button (B until you hear "Labels" button → Enter)
        3. +
      3. Dropdown opens showing all available labels: use ↑/↓ to navigate
        4. +
      4. Enter to select or deselect a label; type to filter (e.g., type "access" to find "accessibility")
        5. +
      5. Press Escape to close - selections save automatically
        6. +
      +
      + +
      +Screen reader users (VoiceOver - macOS) + +
        +
      1. VO+U → Headings or Quick Nav H to find the "Labels" heading in the sidebar
        2. +
      2. Quick Nav B to find the "Labels" gear/edit button → VO+Space
        3. +
      3. Dropdown opens: VO+Down or arrow keys to navigate labels
        4. +
      4. VO+Space to select or deselect; type to filter
        5. +
      5. Escape to close - selections save automatically
        6. +
      +
      + +
      +GitHub CLI (gh) alternative - applying labels + +

      Apply labels to issues or PRs from your terminal:

      +
      # 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:

      +
      # 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. +
      2. Tab to "New label" button → Enter
        3. +
      3. Fill in: Label name (F for form field), Color (use the color picker or hex code), Description
        4. +
      4. Tab to "Create label" button → Enter
        5. +
      +
      +GitHub CLI (gh) alternative - creating labels + +

      Create labels from your terminal:

      +
      # 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)
        • +
      + +

      From Issues tab:

      +
        +
      1. Press K to find the "Milestones" link → Enter
        2. +
      2. You see a list of milestones, each with its title, progress, and due date
        3. +
      +

      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. +
      2. Press Enter to open a milestone
        3. +
      3. The milestone detail page shows all issues and PRs belonging to it
        4. +
      4. Navigate the list with 3 (issue titles) or I (list items)
        5. +
      +

      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. +
      2. Activate the Milestone gear button
        3. +
      3. Select a milestone from the dropdown (↑/↓ → Enter)
        4. +
      4. Esc to close
        5. +
      +
      + +
      +Screen reader users (VoiceOver - macOS) + +
        +
      1. Quick Nav H or VO+Cmd+H to find the "Milestone" heading in the sidebar
        2. +
      2. Quick Nav B to find and activate the Milestone gear button (VO+Space)
        3. +
      3. Select a milestone from the dropdown (VO+Down or arrow keys → VO+Space)
        4. +
      4. Esc to close
        5. +
      +
      + +
      +GitHub CLI (gh) alternative - milestones + +

      Manage milestones from your terminal:

      +
      # 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:

      +
      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. +
      2. Tab to "New milestone" button → Enter
        3. +
      3. Fill in: Title, Description, Due date (optional)
        4. +
      4. Tab to "Create milestone" → Enter
        5. +
      +

      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

      + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + +
      SyntaxEffect
      #42Links to issue or PR #42 in the same repo
      owner/repo#42Links to issue #42 in a different repository
      a1b2c3dLinks to a specific commit by its SHA hash
      @usernameNotifies and links to a GitHub user's profile
      Closes #42Closes issue #42 when the PR merges
      Fixes #42Same as Closes - conventional for bugs
      Resolves #42Same as Closes - general use
      Refs #42Links 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. +
      2. Continue typing the issue number or title fragment
        3. +
      3. Use ↓ to navigate the dropdown → Enter to select
        4. +
      4. The #42 link is inserted automatically
        5. +
      +

      For @mentions:

      +
        +
      1. Type @ followed by a username
        2. +
      2. A dropdown of suggestions appears
        3. +
      3. ↓ to navigate → Enter to select
        4. +
      +

      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 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:

      + + + + + + + + + + + + + + + + + + + + + + + +
      LayoutDescriptionBest For
      TableSpreadsheet-style with custom fieldsTracking detailed status
      BoardKanban columns (Todo, In Progress, Done)Visual workflow
      RoadmapTimeline/Gantt viewPlanning across time
      +

      Finding a Project

      +

      From an organization page or repository:

      +
        +
      1. Navigate to the "Projects" tab
        2. +
      2. Press 3 to navigate project titles (they are h3 links)
        3. +
      3. Enter to open a project
        4. +
      +

      Navigating a Project - Table View

      +
      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

      +
      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. +
      2. Activate the Projects gear button
        3. +
      3. Select the project from the dropdown
        4. +
      +

      Or from within a project:

      +
        +
      1. Activate "Add item" button at the bottom of a column/table
        2. +
      2. Type # to search for existing issues
        3. +
      3. Select the issue → it's added to the project
        4. +
      +

      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

      +
      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

      +
      Name: Hackathon Day 1 Deliverables
+Due: [Day 1 date]
+Description: All contributions made during Day 1 of the Open Source AT Hackathon
      +

      Workflow

      +
      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
      + +

      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. +
      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.
        3. +
      +

      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 to finish Day 1.

      +
      +
      +

      Next: Chapter 10: Notifications and Day 1 Close
      Back: Chapter 08: Open Source Culture
      Related appendices: Appendix R: Projects Deep Dive

      + +
      + + + + diff --git a/html/admin/qa-bundle/docs/10-notifications-and-day-1-close.html b/html/admin/qa-bundle/docs/10-notifications-and-day-1-close.html new file mode 100644 index 00000000..efc58d80 --- /dev/null +++ b/html/admin/qa-bundle/docs/10-notifications-and-day-1-close.html @@ -0,0 +1,936 @@ + + + + + + + Notifications - GIT Going with GitHub + + + + + + + + +
      +

      Notifications

      +
      +

      Listen to Episode 10: Notifications and Mentions - a conversational audio overview of this chapter. Listen before reading to preview the concepts, or after to reinforce what you learned.

      +
      +
      +

      Related appendices: Appendix T: Community and Social | Appendix U: Discussions and Gists | Appendix V: GitHub Mobile +Authoritative sources: GitHub Docs: About notifications

      +
      +

      Managing Your GitHub Notification Inbox

      +
      +

      See also: Appendix V: GitHub Mobile for managing notifications on your phone.

      +
      +
      +

      GitHub notifications are how GitHub tells you when something needs your attention. This guide teaches you to keep the inbox useful - not overwhelming - using only your keyboard and screen reader.

      +
      +

      Workshop Recommendation (Chapter 10)

      +

      For this workshop, Chapter 10 is a guided practice chapter, not a graded automation chapter.

      +
        +
      • Challenge count: 1 guided walkthrough
        • +
      • Automation check: none - notification settings are account-level and cannot be validated by the Learning Room PR bot
        • +
      • Evidence: structured completion comment on your assigned challenge issue
        • +
      • Pattern: configure, filter, act
        • +
      +

      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.
        2. +
      +

      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. +
      2. Find the Watch button near the top-right of the repository page (next to Star and Fork).
        3. +
      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. +
      4. Open the notifications inbox by navigating to https://github.com/notifications (or activate the bell icon in the GitHub header).
        5. +
      5. In the notification filters, activate the Review requested filter. This shows only notifications where someone has asked you to review their PR.
        6. +
      6. Clear that filter and activate the Assigned filter. This shows notifications for issues and PRs assigned to you.
        7. +
      7. Open one notification by activating its title link. Read it briefly, then navigate back to the inbox.
        8. +
      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).
          • +
        +
        9. +
      +

      Screen reader tip: The notification list is a standard list of links. Each notification announces its title, repository, and reason (mention, review request, assignment). Use arrow keys to move between notifications and Enter to open one.

      +

      You are done when: You have changed your watch level, used two different filters, and performed one inbox action (mute or done).

      +

      Completing Chapter 10: Submit Your Evidence

      +

      Open your assigned Chapter 10 challenge issue and post a completion comment:

      +
      Chapter 10 completed:
+- Watch level set to: Participating and @mentions
+- Filters tested: Review requested, Assigned
+- Inbox action performed: [mute / mark done] on [thread description]
      +

      Close your Chapter 10 challenge issue when done.

      +

      Expected Outcomes

      +
        +
      • Student can configure repository watch levels to reduce noise.
        • +
      • Student can find review requests and assigned work quickly using filters.
        • +
      • Student can reduce notification noise with mute or done actions.
        • +
      +

      If You Get Stuck

      +
        +
      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. +
      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. +
      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. +
      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. +
      5. Ask facilitator to model one inbox action live, then repeat the steps yourself.
        6. +
      6. Finished but not sure you did it right? Compare your work against the Challenge 9 reference solution.
        7. +
      +

      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. +
      2. Use filters to find signal in noise (review requests, assignments).
        3. +
      3. Take decisive action on each notification (mute, done, or respond).
        4. +
      4. Build a daily routine that keeps your inbox manageable.
        5. +
      +

      What Generates a Notification?

      +

      GitHub sends you a notification when:

      + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + +
      EventYou are notified if...
      Someone @mentions you@your-username appears in any issue, PR, or discussion
      A PR is assigned to you for reviewYou are added as a reviewer
      An issue or PR is assigned to youYou are assigned
      There is activity on a thread you are subscribed toYou commented, were mentioned, or chose to subscribe
      A CI check fails on your PRActions sends a failure notification
      A release is publishedYou are watching the repo for all activity
      +

      Notification Subscription Levels

      +

      For each repository, you choose how many notifications to receive:

      + + + + + + + + + + + + + + + + + + + + + + + +
      LevelWhat You Receive
      Participating and @mentionsOnly notifications where you participated (commented, were assigned, @mentioned). Recommended for most repos.
      All ActivityEvery issue opened, every comment, every PR. Only use this for your own repos or very active contribution.
      IgnoreNo notifications from this repo at all.
      CustomFine-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. +
      2. Press Enter to open the dropdown
        3. +
      3. Press ↑/↓ to navigate the subscription options
        4. +
      4. Press Enter to select your preferred level
        5. +
      5. The button label updates to confirm your choice
        6. +
      +
      + +
      +Screen reader users (VoiceOver - macOS) + +
        +
      1. Quick Nav B to find the Watch button in the repo header (listen for "Watch" or "Unwatch")
        2. +
      2. VO+Space to open the dropdown
        3. +
      3. VO+Down or arrow keys to navigate subscription options
        4. +
      4. VO+Space to select your preferred level
        5. +
      5. The button label updates to confirm your choice
        6. +
      +
      + +

      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 (or press G then N).
        2. +
      2. Use E to mark done, I to mark read/unread, Shift+M to mute a thread.
        3. +
      +

      VS Code Desktop (GitHub Pull Requests extension):

      +
        +
      1. The Notifications view in the GitHub sidebar shows items needing attention.
        2. +
      2. Click a notification to open the related issue or PR directly in VS Code.
        3. +
      +

      GitHub Desktop: +GitHub Desktop does not manage notifications. Use the browser or CLI.

      +

      Git CLI / GitHub CLI:

      +
      # 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:

      +
      # 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

      +
      [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)
      + +
      +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. +
      2. H to navigate group headings (Today / Yesterday / This week / Older)
        3. +
      3. Tab through individual notifications - each row announces: repo name, issue/PR title, event type, time
        4. +
      4. Enter to open the notification (goes to the issue/PR page)
        5. +
      +
      + +
      +Screen reader users (VoiceOver) + +
        +
      1. VO+U → Main → navigate to notification list
        2. +
      2. VO+Down to move through notifications
        3. +
      3. VO+Space to open a notification
        4. +
      +
      + +

      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:

      + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + +
      ShortcutAction
      EMark as done (archive from inbox)
      Shift+IMark as read without opening
      Shift+UMark as unread
      MMute thread (no more notifications from this thread)
      SSave for later
      EnterOpen 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:

      + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + +
      FilterShows
      InboxAll active notifications (default)
      UnreadOnly unread notifications
      SavedNotifications you saved with S
      DoneArchived (marked done) notifications
      @MentionedOnly threads where you were directly @mentioned
      AssignedIssues and PRs assigned to you
      Review requestedPRs where your review is requested
      ParticipatingAll 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. +
      2. Focus Mode → type repo name or org name
        3. +
      3. Results filter in real time
        4. +
      4. Press Esc to clear the filter
        5. +
      +
      + +
      +Screen reader users (VoiceOver - macOS) + +
        +
      1. Quick Nav F to reach the filter input
        2. +
      2. VO+Shift+Down to interact → type repo or org name
        3. +
      3. Results filter in real time
        4. +
      4. Press Esc to clear the filter and VO+Shift+Up to stop interacting
        5. +
      +
      + + +

      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. +
      2. Tab to "Mark all as done" button → Enter (clears everything at once)
        3. +
      3. Then use the "Done" filter to retrieve any you want to revisit
        4. +
      +

      Muting a noisy thread

      +

      If a thread generates too many notifications:

      +
      +Visual / mouse users + +
        +
      1. Open the issue or PR page
        2. +
      2. In the right sidebar, scroll to the Notifications section
        3. +
      3. Click Unsubscribe - you will stop receiving notifications from this thread
        4. +
      4. Alternatively, from the inbox: hover over the notification row and click the mute icon (or the … menu)
        5. +
      +
      + +
      +Screen reader users (NVDA / JAWS - Windows) + +
        +
      1. Open the notification
        2. +
      2. On the issue/PR page, navigate the sidebar to the Notifications section (H or D)
        3. +
      3. Activate the Unsubscribe button
        4. +
      4. Or from the inbox: focus the notification → press M to mute
        5. +
      +
      + +
      +Screen reader users (VoiceOver - macOS) + +
        +
      1. Open the notification
        2. +
      2. On the issue/PR page, VO+U → Landmarks or Quick Nav H to find the Notifications section in the sidebar
        3. +
      3. Quick Nav B or Tab to find the Unsubscribe button → VO+Space
        4. +
      4. Or from the inbox: focus the notification and press M to mute
        5. +
      +
      + +

      Dealing with @mentions you didn't expect

      +

      If you were @mentioned in an unfamiliar thread:

      +
        +
      1. Read the thread for context before responding
        2. +
      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. +
      3. Unsubscribe after reading if you don't need to stay in the loop
        4. +
      +

      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:

      + + + + + + + + + + + + + + + + + + + + + + + +
      SettingRecommendation
      Email deliveryChoose Participating and @mentions unless you prefer email for everything
      GitHub MobileEnable only if you use GitHub Mobile - mobile notifications can duplicate desktop ones
      Watching"Participating and @mentions" unless you are an active maintainer
      Organization alertsEnable for orgs where you have responsibilities
      +

      Navigate this settings page:

      +
      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

      + + + + + + + + + + + + + + + + + + + + + + + + + + + +
      FeatureDescription
      What it doesBookmarks the repository to your Stars list at github.com/stars
      NotificationsNone. Starring never sends you any notifications
      VisibilityPublic - 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 pathOn 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

      + + + + + + + + + + + + + + + + + + + + + + + + + + + +
      FeatureDescription
      What it doesSubscribes you to notifications from that repository
      NotificationsSends notifications based on your chosen level (see below)
      VisibilityPrivate - other users cannot see what you're watching
      Use case"I need to stay informed about activity in this repo"
      Keyboard pathB → 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

      +
      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.

      + + + + + + + + + + + + + + + + + + + + + + + + +
      RepositoryRecommended Watch Level
      community-access/accessibility-agentsParticipating and @mentions - you contribute there, you only need to hear back when someone replies to you
      Your own forkAll Activity - this is your fork; know everything
      Very busy popular reposIgnore or Participating - do not watch for All Activity
      Repos you're evaluatingStar 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 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. +
      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. +
      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.
        4. +
      +

      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 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:

      + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + +
      ChapterSkillEvidence
      Chapter 00Created a GitHub account and configured accessibility settingsAccount exists, profile is visible
      Chapter 01Chose your editing environment and tested itTool preference noted in your challenge issue
      Chapter 02Understood what GitHub is, how repositories work, and what collaboration looks likeCompletion comment on challenge issue
      Chapter 03Navigated a real repository using keyboard and screen readerFound specific files and folders in the Learning Room
      Chapter 04Opened the Learning Room, found your challenge issues, and understood the workflowFirst structured comment posted
      Chapter 05Created, labeled, and commented on issuesIssue created with a descriptive title and body
      Chapter 06Created a branch, edited a file, and opened a pull requestMerged PR visible in the repository
      Chapter 07Recognized a merge conflict and resolved itConflict-free merge committed
      Chapter 08Read contributing guidelines, understood community norms, and practiced respectful communicationThoughtful comment on a peer's issue or PR
      Chapter 09Used labels, milestones, and project boards to organize workLabels applied, milestone progress visible
      Chapter 10Configured notification preferences and managed your inboxWatch 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. +
      2. Can you explain what a pull request does to someone who has never used GitHub?
        3. +
      3. If you saw a merge conflict right now, would you know where to start?
        4. +
      4. What is one thing you want to try on GitHub this week that you did not get to today?
        5. +
      +
      +

      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 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:

      + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + +
      ChaptersTopicWhat You Will Do
      Ch 11 -- Ch 12VS Code deep diveInstall and configure VS Code with full screen reader and accessibility support
      Ch 13 -- Ch 14Local GitClone repositories, commit locally, push and pull changes between your computer and GitHub
      Ch 15Code reviewReview pull requests with inline comments, suggestions, and approval workflows
      Ch 16GitHub CopilotUse AI-assisted coding with accessibility-first prompting techniques
      Ch 17Issue templatesCreate structured templates so every issue in your project starts with the right information
      Ch 18Fork workflowFork a repository, make changes, and submit a pull request back to the original project
      Ch 19Accessibility agentsBuild and use custom agents that automate accessibility checks and team workflows
      Ch 20CapstoneDesign, 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 and customize your email and web preferences. There is no wrong configuration -- just find what feels manageable.
        2. +
      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.
        3. +
      3. Try a GitHub Skills course. GitHub Skills 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 for the full list of recommended courses.
        4. +
      +
      +

      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 to prepare for Day 2.

      +
      +
      +

      Next: Chapter 11: VS Code Interface
      Back: Chapter 09: Labels, Milestones, and Projects
      Related appendices: Appendix T: Community and Social | Appendix U: Discussions and Gists

      + +
      + + + + diff --git a/html/admin/qa-bundle/docs/11-vscode-interface.html b/html/admin/qa-bundle/docs/11-vscode-interface.html new file mode 100644 index 00000000..a0f2bcce --- /dev/null +++ b/html/admin/qa-bundle/docs/11-vscode-interface.html @@ -0,0 +1,1400 @@ + + + + + + + VS Code: Interface and Setup - GIT Going with GitHub + + + + + + + + +
      +

      VS Code: Interface and Setup

      +
      +

      Listen to Episode 11: VS Code Setup and Accessibility - a conversational audio overview covering both this chapter and Chapter 12.

      +
      +
      +

      Related appendices: Appendix G: VS Code Reference | Appendix B: Screen Reader Cheat Sheet +Authoritative sources: VS Code Docs: User Interface | VS Code Docs: Accessibility

      +
      +

      Your Accessible Development Environment - The Foundation

      +
      +

      Day 2, Block 1 Material

      +

      This chapter covers the VS Code interface: launching VS Code, signing in to GitHub, verifying Copilot is active, configuring screen reader mode, and navigating the Activity Bar, Status Bar, menus, settings, and keyboard shortcuts.

      +

      For accessibility deep-dive topics (keyboard navigation, Problems panel, Terminal, Copilot Chat, Accessible Help/View/Diff, Accessibility Signals, and VS Code Speech), see Chapter 12: VS Code Accessibility Deep Dive.

      +

      Prerequisites: Complete Day 1 walkthrough of GitHub's browser interface before working through VS Code material.

      +
      +

      Workshop Recommendation (Chapter 11)

      +

      For this workshop, Chapter 11 is a guided setup chapter with a lightweight completion practice.

      +
        +
      • Challenge count: 1 guided walkthrough
        • +
      • Automation check: none - setup state is local/account-level and cannot be validated by the Learning Room PR bot
        • +
      • Evidence: structured completion comment on your assigned challenge issue
        • +
      • Pattern: open, configure, navigate, verify
        • +
      +

      Chapter 11 Practice Set

      +
        +
      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.
        2. +
      +

      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. +
      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. +
      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. +
      4. Open the Explorer panel with Ctrl+Shift+E (Mac: Cmd+Shift+E). Your screen reader should announce the file tree.
        5. +
      5. Navigate to and open README.md from the file tree. Use arrow keys to move through files and Enter to open.
        6. +
      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. +
      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. +
      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. +
      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.
        10. +
      +

      You are done when: You have successfully opened github.dev, enabled screen reader mode, signed in to GitHub, confirmed Copilot status, opened a file, viewed its outline, and run a command from the Command Palette.

      +

      Completing Chapter 11: Submit Your Evidence

      +

      Return to GitHub.com, open the assigned setup or Day 2 readiness issue, and post a completion comment:

      +
      Chapter 11 completed:
+- Opened github.dev: yes / no
+- Screen reader mode enabled: yes / no
+- Signed in to GitHub: yes / no
+- Copilot status checked: yes / no
+- Opened file in Explorer: yes / no
+- Opened outline/symbols: yes / no
+- Opened Command Palette: yes / no
      +

      If any step was "no," add a note explaining where you got stuck so the facilitator can help. Close the assigned setup or readiness issue when done.

      +

      Expected Outcomes

      +
        +
      • Student can launch and navigate github.dev or desktop VS Code.
        • +
      • Student can enable screen reader mode and hear navigation announcements.
        • +
      • Student has signed in to GitHub and can see their account status.
        • +
      • Student has verified GitHub Copilot is active (or knows it requires desktop VS Code).
        • +
      • Student can open core navigation surfaces (Explorer, Outline, Command Palette).
        • +
      • Student is ready for VS Code-based contribution chapters (6-16).
        • +
      +

      If You Get Stuck

      +
        +
      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. +
      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. +
      3. Explorer panel is empty? VS Code may still be loading the repository. Wait 5-10 seconds and press Ctrl+Shift+E again.
        4. +
      4. On Mac with VoiceOver, navigation feels wrong? Run Toggle Screen Reader Accessibility Mode from Command Palette. VoiceOver sometimes needs the explicit toggle.
        5. +
      5. Cannot find the Accounts button? Open Command Palette and type Accounts to manage sign-in from there.
        6. +
      6. Copilot not showing in the status bar? github.dev does not support Copilot - you need desktop VS Code or a Codespace.
        7. +
      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. +
      8. Ask facilitator for a side-by-side demo and repeat the same steps.
        9. +
      +

      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. +
      2. Sign in and verify your identity and tools are ready (Accounts, Copilot).
        3. +
      3. Configure accessibility before doing any work (screen reader mode first).
        4. +
      4. Verify each navigation surface works with your assistive technology.
        5. +
      5. Record what worked and what didn't (evidence comment).
        6. +
      +

      Table of Contents

      +
        +
      1. Why VS Code for Open Source Contribution
        2. +
      2. The Bridge: github.dev - VS Code in Your Browser
        3. +
      3. Screen Reader Mode in VS Code
        4. +
      4. The VS Code Interface Tour
        5. +
      5. The Accounts Button and GitHub Sign-In
        6. +
      6. Verifying GitHub Copilot Status
        7. +
      7. The Status Bar
        8. +
      8. The Menu Bar
        9. +
      9. Settings Sync +
        10. +
      10. The Settings Editor
        11. +
      11. The Keyboard Shortcuts Editor
        12. +
      12. Essential Keyboard Navigation and Find/Filter
        13. +
      13. The Problems Panel
        14. +
      14. The Terminal
        15. +
      15. Copilot Chat Window
        16. +
      16. Accessible Help, Accessible View, and Accessible Diff
        17. +
      17. Accessibility Signals
        18. +
      18. VS Code Speech - Voice Input and Output
        19. +
      19. Git Operations Inside VS Code
        20. +
      +
      +

      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:

      + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + +
      TaskBrowserVS Code
      Navigate a repositoryExcellentExplorer sidebar
      Read issues and PRsExcellentGitHub PR extension
      Comment on a PRExcellentGitHub PR extension
      Edit a fileWeb editorFull text editor with Copilot
      Review a diffFiles Changed tabThree-way merge view with navigation
      Get AI help while writingNot availableCopilot inline + Chat
      Run Accessibility AgentsNot availableCopilot Chat with agent files
      See errors in your contributionAfter pushReal-time as you type
      +

      For Markdown contributions (which is most of what 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. +
      2. The page transforms into VS Code
        3. +
      3. You are now editing in github.dev
        4. +
      4. The URL changes to github.dev/owner/repo
        5. +
      5. Screen reader mode works exactly as it does in desktop VS Code (toggle with Shift+Alt+F1)
        6. +
      +

      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. +
      2. In the dropdown, click Open with github.dev
        3. +
      +
      + +
      +Screen reader users (NVDA / JAWS / VoiceOver) + +
        +
      1. Navigate to the Code button (press B or Tab until you hear "Code, button" or similar)
        2. +
      2. Press Enter to open the dropdown menu
        3. +
      3. Press Down Arrow to reach "Open with github.dev"
        4. +
      4. Press Enter
        5. +
      +
      + + +

      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 and Appendix M)
        • +
      • 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. +
      2. Press Shift+Alt+F1 (Mac: Shift+Option+F1) to enable screen reader mode
        3. +
      3. VS Code announces "Screen reader optimized"
        4. +
      +

      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
        • +
      + +
        +
      • 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. +
      2. Press . (period key)
        3. +
      3. github.dev opens
        4. +
      4. Press Shift+Alt+F1 (Mac: Shift+Option+F1) to enable screen reader mode
        5. +
      5. Press Ctrl+Shift+E (Mac: Cmd+Shift+E) to open the Explorer
        6. +
      6. Navigate to README.md and press Enter
        7. +
      7. Press Ctrl+Home (Mac: Cmd+Up) to go to the top of the file
        8. +
      8. Press Ctrl+Shift+O (Mac: Cmd+Shift+O) to see the outline (all headings)
        9. +
      9. Close the tab when done
        10. +
      +

      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 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 - 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

      + + + + + + + + + + + + + + + + + + + +
      MethodSteps
      Keyboard shortcutShift+Alt+F1 (Windows) / Shift+Option+F1 (Mac)
      Command PaletteCtrl+Shift+P (Windows) / Cmd+Shift+P (Mac) then type "screen reader" then select "Toggle Screen Reader Accessibility Mode"
      Auto-detectionVS 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

      + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + +
      AreaNormal ModeScreen Reader Mode
      Suggestions listPopup overlayAnnounced via ARIA live region
      Diff navigationVisual highlightingAnnounces "Added" / "Removed" before line content
      Error indicatorsRed underlinesAnnounced on focus
      Inline decorationsDisplayed visuallySuppressed to reduce noise
      Tab completionVisual ghost textAnnounced 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. +
      2. Set "Maximum length of text on a single line" to 10000 (prevents truncation in long lines)
        3. +
      3. Under Object Presentation: set "Report tooltip delay" to off
        4. +
      4. Recommended: use NVDA + Google Chrome for the integrated browser panels
        5. +
      +

      JAWS-Specific Settings for VS Code

      +
        +
      1. JAWS should detect VS Code automatically and switch to PC Cursor mode for the editor
        2. +
      2. If the editor feels unresponsive, press Insert+Z to toggle virtual cursor off
        3. +
      3. For the integrated terminal: use Insert+Z to enter forms/PC mode, then interact with the terminal
        4. +
      +

      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. +
      2. In VoiceOver Utility: Verbosity then set "Punctuation" to "All" for reading code
        3. +
      3. Use Quick Nav OFF (Left+Right Arrow) when inside the editor - standard cursor navigation is more predictable
        4. +
      4. Use VO+Shift+Down to interact with the editor, VO+Shift+Up to stop interacting
        5. +
      +

      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

      +
      +----------------------------------------------------------+
+|  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.

      + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + +
      RegionKeyboard ShortcutWhat You Hear (Screen Reader)
      Activity Bar iconsCtrl+Shift+E / G / F / X / etc."Explorer", "Source Control", etc.
      Sidebar contentFollows activity bar selectionTree view or list content
      Editor areaCtrl+1 (first editor group)File name and cursor position
      PanelCtrl+Backtick (terminal) or Ctrl+Shift+M (problems)Panel name announcement
      Status BarF6 cycles through regionsStatus 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 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. +
      2. Press Enter to open the Accounts menu
        3. +
      3. Select "Sign in with GitHub to use GitHub Copilot" (or a similar prompt)
        4. +
      4. A browser window opens for GitHub OAuth authorization
        5. +
      5. Authorize VS Code, then return to the editor
        6. +
      6. Your screen reader announces your GitHub username in the Accounts button
        7. +
      +

      From the Command Palette

      +
        +
      1. Press Ctrl+Shift+P then type sign in
        2. +
      2. Select "GitHub: Sign In"
        3. +
      3. Complete the browser OAuth flow and return to VS Code
        4. +
      +

      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 StateMeaning
      Copilot icon (normal)Copilot is active and ready
      Copilot icon with warning triangleCopilot has a configuration issue
      Copilot icon with slash-throughCopilot is disabled for this file type
      No Copilot iconExtension not installed or not signed in
      +

      Command Palette Check

      +
        +
      1. Press Ctrl+Shift+P
        2. +
      2. Type GitHub Copilot: Status
        3. +
      3. The output shows whether Copilot is signed in, active, or has errors
        4. +
      +

      Quick Test

      +
        +
      1. Open any .md file in the editor
        2. +
      2. Start typing a sentence (for example, ## Getting Started with)
        3. +
      3. If Copilot is active, a gray ghost-text suggestion appears after a brief pause
        4. +
      4. Press Tab to accept or Escape to dismiss
        5. +
      +

      Troubleshooting Copilot

      + + + + + + + + + + + + + + + + + + + + + + + + + + + +
      ProblemSolution
      No Copilot icon in status barOn 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 warningOpen 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 suggestingCheck that Copilot is not disabled for the file type: Ctrl+Shift+P then GitHub Copilot: Toggle
      Works on desktop but not github.devExpected 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)

      + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + +
      ItemWhat It ShowsHow to Interact
      Git branchCurrent branch name (e.g., main)Click or press to switch branches
      Sync statusPending push/pull countClick to sync (push/pull)
      Errors and warningsError/warning count in workspaceClick opens Problems panel (Ctrl+Shift+M)
      Line and columnCursor position (e.g., Ln 42, Col 8)Click opens Go to Line (Ctrl+G)
      IndentationSpaces or tabs and countClick to change indent settings
      EncodingFile encoding (e.g., UTF-8)Click to change encoding
      End of lineLF or CRLFClick to change line endings
      Language modeFile type (e.g., Markdown)Click to change language
      Copilot statusGitHub Copilot stateClick for Copilot menu
      Notification bellUnread notificationsClick to view notifications
      + +
        +
      1. Press F6 until your screen reader announces the Status Bar
        2. +
      2. Use Tab to move between items from left to right
        3. +
      3. Press Enter on any item to activate it (open a picker, toggle a setting, etc.)
        4. +
      4. Press Escape to return to the editor
        5. +
      +

      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.

      + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + +
      MenuKey Contents
      FileNew File, Open Folder, Save, Auto Save, Preferences (Settings, Keyboard Shortcuts, Extensions)
      EditUndo, Redo, Cut, Copy, Paste, Find, Replace
      SelectionSelect All, Expand Selection, Add Cursor
      ViewExplorer, Search, Source Control, Extensions, Terminal, Problems, Command Palette, Appearance (zoom, sidebar, panel toggles)
      GoGo to File, Go to Symbol, Go to Line, Go to Definition, Back/Forward navigation
      RunStart Debugging, Run Without Debugging, Add Configuration
      TerminalNew Terminal, Split Terminal, Run Active File, Run Selected Text
      HelpWelcome, Documentation, Keyboard Shortcuts Reference, Accessibility Help
      +

      Accessing the Menu Bar

      + + + + + + + + + + + + + + + + + + + +
      MethodSteps
      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 PaletteCtrl+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

      + + + + + + + + + + + + + + + + + + + + + + + + + + + +
      CategoryExamples
      Settingseditor.fontSize, editor.accessibilitySupport, color theme, zoom level
      Keyboard ShortcutsAll custom keybindings
      ExtensionsInstalled extensions list
      UI StateSidebar position, panel visibility, recent files
      ProfilesNamed 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. +
      2. Sign in with your GitHub account (or Microsoft account)
        3. +
      3. Select which categories to sync (recommended: sync everything)
        4. +
      4. VS Code syncs immediately and on every subsequent change
        5. +
      +

      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

      + + + + + + + + + + + + + + + +
      MethodSteps
      Command PaletteCtrl+Shift+P then type Profiles: Create Profile
      Gear menuClick 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

      + + + + + + + + + + + + + + + + + + + +
      MethodSteps
      Command PaletteCtrl+Shift+P then type Profiles: Switch Profile
      Gear menuClick the gear icon then Profiles then select a profile name
      Status BarThe 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 NamePurposeKey Settings
      WorkshopAccessibility-optimized for this eventScreen reader mode on, accessibility signals enabled, minimap off, word wrap on (see the Recommended Workshop Profile settings in Section 17)
      PresentationLarge fonts for demos or shared screenseditor.fontSize: 24, terminal.integrated.fontSize: 20, window.zoomLevel: 2, High Contrast theme
      DefaultYour everyday development settingsWhatever you normally use
      +

      Exporting and Sharing Profiles

      +

      Profiles can be exported and shared:

      +
        +
      1. Ctrl+Shift+P then type Profiles: Export Profile
        2. +
      2. Choose what to include (settings, extensions, etc.)
        3. +
      3. Export as a GitHub gist (shareable link) or a local file
        4. +
      4. Share the link or file with others
        5. +
      +

      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

      + + + + + + + + + + + + + + + +
      MethodShortcut
      Graphical Settings UICtrl+, (Mac: Cmd+,)
      JSON Settings fileCtrl+Shift+P then type "Open User Settings (JSON)"
      + +

      The graphical Settings UI has a search box at the top. Type any keyword and the settings list filters instantly.

      +

      Special Search Filters

      + + + + + + + + + + + + + + + + + + + + + + + + + + + +
      FilterWhat It Shows
      @modifiedOnly settings you have changed from their defaults
      @tag:accessibilityAll accessibility-related settings
      @tag:advancedAdvanced, less commonly used settings
      @tag:experimentalExperimental features not yet enabled by default
      @ext:github.copilotSettings for the GitHub Copilot extension
      +

      Key Accessibility Settings to Configure

      +
      {
+  "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

      + + + + + + + + + + + + + + + + + + + +
      MethodShortcut
      Graphical editorCtrl+K Ctrl+S
      JSON editorCtrl+Shift+P then type "Open Keyboard Shortcuts (JSON)"
      From Menu BarFile 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. +
      2. Double-click the keybinding column (or press Enter on the row, then Enter again on the keybinding)
        3. +
      3. Press your desired key combination
        4. +
      4. Press Enter to confirm
        5. +
      +

      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
      Back: Chapter 10: Notifications and Day 1 Close
      Related appendices: Appendix G: VS Code Reference | Appendix B: Screen Reader Cheat Sheet

      + +
      + + + + diff --git a/html/admin/qa-bundle/docs/12-vscode-accessibility.html b/html/admin/qa-bundle/docs/12-vscode-accessibility.html new file mode 100644 index 00000000..58a4c79d --- /dev/null +++ b/html/admin/qa-bundle/docs/12-vscode-accessibility.html @@ -0,0 +1,1932 @@ + + + + + + + VS Code: Accessibility Deep Dive - GIT Going with GitHub + + + + + + + + +
      +

      VS Code: Accessibility Deep Dive

      +
      +

      Listen to Episode 11: VS Code Setup and Accessibility - a conversational audio overview covering both Chapter 11 and this chapter.

      +
      +
      +

      Related appendices: Appendix G: VS Code Reference | Appendix B: Screen Reader Cheat Sheet +Authoritative sources: VS Code Docs: Accessibility | GitHub Accessibility: GitHub Copilot in VS Code

      +
      +

      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.

      +
      +

      Table of Contents

      +
        +
      1. Essential Keyboard Navigation and Find/Filter
        2. +
      2. The Problems Panel
        3. +
      3. The Terminal
        4. +
      4. Copilot Chat Window
        5. +
      5. Accessible Help, Accessible View, and Accessible Diff
        6. +
      6. Accessibility Signals
        7. +
      7. VS Code Speech - Voice Input and Output
        8. +
      8. Markdown Authoring in VS Code
        9. +
      9. If You Get Stuck
        10. +
      +

      12. Essential Keyboard Navigation and Find/Filter

      +

      Panels and Areas

      +
      +

      Mac users: Substitute Cmd for Ctrl and Option for Alt in all shortcuts below.

      +
      + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + +
      AreaShortcut (Windows)What Gets Focus
      Explorer (file tree)Ctrl+Shift+EFolder/file list
      SearchCtrl+Shift+FSearch input
      Source Control (Git)Ctrl+Shift+GChanges list
      ExtensionsCtrl+Shift+XExtensions list
      TerminalCtrl+`Terminal input
      Copilot ChatCtrl+Shift+IChat input
      Command PaletteCtrl+Shift+PCommand search input
      EditorCtrl+1Active editor file
      Problems panelCtrl+Shift+MList of all errors and warnings
      +

      Within the Editor

      + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + +
      ActionShortcut
      Go to beginning of fileCtrl+Home
      Go to end of fileCtrl+End
      Go to line NCtrl+G then type line number
      Go to line and columnCtrl+G then type N:C (e.g., 10:5)
      Go to symbol (heading in Markdown)Ctrl+Shift+O
      Go to definitionF12
      Find in fileCtrl+F
      Next find resultF3
      Previous find resultShift+F3
      Next error or warningF8
      Previous error or warningShift+F8
      Open file by nameCtrl+P then type filename
      Toggle word wrapAlt+Z
      Toggle Tab focus modeCtrl+M (makes Tab move focus instead of indenting)
      Increase/decrease font sizeCtrl+= / Ctrl+-
      Breadcrumb navigationCtrl+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:

      + + + + + + + + + + + + + + + + + + + + + + + +
      ToggleShortcutWhat It Does
      Match CaseAlt+CLimits results to exact uppercase/lowercase
      Match Whole WordAlt+WMatches full words only, not substrings
      Use Regular ExpressionAlt+REnables 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:

      + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + +
      ActionHow
      Open global searchCtrl+Shift+F
      Search inputFocus lands here automatically - type your query
      Toggle case / word / regexAlt+C, Alt+W, Alt+R (same as Find)
      Include files filterTab to "files to include" field then type glob patterns
      Exclude files filterTab to "files to exclude" field then type glob patterns
      Collapse all resultsCtrl+Shift+J
      Open a resultNavigate the result tree with Up/Down Arrow then Enter to open
      +

      Glob pattern examples for this workshop

      +
      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. +
      2. Start typing a filename - a filter input appears at the bottom of the tree
        3. +
      3. The tree instantly narrows to matching files
        4. +
      4. Press Escape to clear the filter and restore full view
        5. +
      +

      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

      + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + +
      ActionKey
      Navigate itemsUp/Down Arrow
      Expand folderRight Arrow
      Collapse folderLeft Arrow
      Open fileEnter
      Rename fileF2
      Delete fileDelete
      New fileCtrl+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)
        • +
      + + + + + + + + + + + + + + + + + + + + + + + + + + + + +
      ActionShortcut
      Open Problems panelCtrl+Shift+M
      Next problem in editorF8
      Previous problem in editorShift+F8
      Filter problemsType in the filter box at the top of the panel
      Jump to problem sourceEnter 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

      + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + +
      ActionShortcut
      Toggle terminalCtrl+` (backtick)
      New terminalCtrl+Shift+`
      Split terminalCtrl+Shift+5
      Next terminalFocus terminal then Ctrl+PageDown
      Previous terminalFocus terminal then Ctrl+PageUp
      Kill terminalType 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

      + + + + + + + + + + + + + + + + + + + + + + + +
      FeatureHow to Access
      Accessible Help in terminalAlt+H while terminal is focused
      Navigate terminal output linesAlt+Ctrl+PageUp / Alt+Ctrl+PageDown
      Select terminal outputShift+Arrow keys while in the terminal
      Minimum contrast ratioSettings 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

      + + + + + + + + + + + + + + + + + + + + + + + +
      MethodShortcut
      Chat view (sidebar)Ctrl+Shift+I
      Inline chat (in editor)Ctrl+I
      Quick chat (floating)Ctrl+Shift+Alt+L
      Command PaletteCtrl+Shift+P then type Chat: Open
      +

      Chat Modes

      + + + + + + + + + + + + + + + + + + + +
      ModeWhat It Does
      AskQuestion-answer mode - explain code, answer questions, generate snippets
      EditMulti-file editing mode - Copilot proposes edits across your workspace
      AgentAutonomous 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
        • +
      +
      + + +

      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:

      + + + + + + + + + + + + + + + + + + + +
      ShortcutAction
      Alt+TJump directly from the question carousel back to the terminal
      TabNavigate carousel buttons (Confirm, Dismiss, Focus Terminal)
      EnterActivate 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 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

      + + + + + + + + + + + + + + + + + + + + + + + + + + + +
      ContextShortcut
      Inside the editorAlt+H
      Inside the terminalAlt+H
      Inside a diff viewAlt+H
      Inside Copilot ChatAlt+H
      Any VS Code widgetAlt+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

      +
      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

      + + + + + + + + + + + + + + + +
      ShortcutWhen to Use
      Alt+F2Open Accessible View for the currently focused element
      EscapeClose Accessible View and return to the editor
      +

      What Accessible View provides

      + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + +
      Content TypeWithout Accessible ViewWith Accessible View (Alt+F2)
      Copilot Chat responseFragmented - announced as tokens stream inFull complete response, read sequentially with Arrow keys
      Inline Copilot suggestionGhost text - may not be announcedAnnounced as "Suggestion: [full text]"
      Hover documentationPopup tooltip - announced only brieflyFull content, fully navigable with Arrow keys
      Error / warning detailsOn-focus message onlyFull error text, error code, and suggested fix
      Terminal outputMay be truncated by live region limitsFull output in review mode with scroll
      Notification bannersAnnounced once and dismissedPersistent readable content until you close it
      + +
        +
      1. Type your prompt in the Chat input
        2. +
      2. Wait for the response to finish (NVDA: live region announcements stop; JAWS: typing indicator disappears; VoiceOver: busy state clears)
        3. +
      3. Press Alt+F2 - Accessible View opens with the complete response
        4. +
      4. Navigate with Up/Down Arrow through the response
        5. +
      5. Press Escape to return to the chat input
        6. +
      + +
        +
      1. Navigate to a symbol or link with keyboard
        2. +
      2. Press Ctrl+K I to trigger hover programmatically (no mouse needed)
        3. +
      3. Press Alt+F2 to open Accessible View with the full hover content
        4. +
      4. Press Escape to dismiss
        5. +
      +

      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

      + + + + + + + + + + + + + + + + + + + +
      ShortcutWhat Happens
      F7Move to the next diff hunk (from within the diff editor)
      Shift+F7Move to the previous diff hunk
      Command PaletteCtrl+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:
        • +
      +
      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

      +
      +

      How Signals Work: The Dual-Channel Architecture

      +

      Every accessibility signal has two independent channels that you control separately:

      + + + + + + + + + + + + + + + + + + +
      ChannelWhat It DoesWho Benefits
      SoundPlays a short audio toneEveryone -- sighted users, low vision users, and screen reader users all benefit from audio feedback
      AnnouncementSends a status message that screen readers and braille displays announcePrimarily screen reader and braille users
      +

      Each channel accepts one of these values:

      + + + + + + + + + + + + + + + + + + + + + + + +
      ValueMeaning
      "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 SoundsOpens 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 AnnouncementsSame 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:

      + + + + + + + + + + + + + + + +
      SettingRangeDefaultPurpose
      accessibility.signalOptions.volume0 -- 10050Master volume for all accessibility signal sounds
      +

      Set this in Settings (Ctrl+,) by searching "signal volume" or add it to settings.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 KeyFires WhenSoundAnnouncement
      accessibility.signals.lineHasErrorCursor moves to a line containing an errorError tone"Error on Line"
      accessibility.signals.lineHasWarningCursor moves to a line containing a warningWarning tone (lower pitch)"Warning on Line"
      accessibility.signals.positionHasErrorCursor moves to the exact position of an errorError tone"Error"
      accessibility.signals.positionHasWarningCursor moves to the exact position of a warningWarning tone"Warning"
      accessibility.signals.lineHasFoldedAreaCursor moves to a line with a collapsed/folded regionFolded area tone"Folded"
      accessibility.signals.lineHasBreakpointCursor moves to a line with a breakpointBreak tone"Breakpoint"
      accessibility.signals.lineHasInlineSuggestionCursor moves to a line with a Copilot ghost text suggestionQuick fix tone--
      accessibility.signals.nextEditSuggestionNext Edit Suggestion appears on the lineNext edit tone"Next Edit Suggestion"
      accessibility.signals.noInlayHintsCursor is on a line with no inlay hintsError 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 KeyFires WhenSound
      accessibility.signals.diffLineInsertedCursor moves over an added (green) lineInserted tone (higher pitch)
      accessibility.signals.diffLineDeletedCursor moves over a removed (red) lineDeleted tone (lower pitch)
      accessibility.signals.diffLineModifiedCursor moves over a modified lineModified tone
      +

      These are critical for pull request review. You hear the type of change before reading the content.

      +

      Terminal Signals

      + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + +
      Setting KeyFires WhenSoundAnnouncement
      accessibility.signals.terminalBellTerminal sends a bell characterBell tone--
      accessibility.signals.terminalQuickFixTerminal detects a quick fix suggestionQuick fix tone"Quick Fix"
      accessibility.signals.terminalCommandSucceededA terminal command exits successfullyCommand succeeded tone--
      accessibility.signals.taskCompletedA VS Code Task finishes successfullyTask completed tone--
      accessibility.signals.taskFailedA VS Code Task exits with an errorTask 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 KeyFires WhenSoundAnnouncement
      accessibility.signals.chatRequestSentYou send a message to Copilot ChatRequest sent tone--
      accessibility.signals.chatResponsePendingCopilot is generating a response (loops)Progress tone--
      accessibility.signals.chatResponseReceivedCopilot finishes generatingOne of 4 random response tones--
      accessibility.signals.chatEditModifiedFileCopilot Edits modifies a file in your workspaceModified file tone--
      accessibility.signals.chatUserActionRequiredCopilot needs you to take an action (accept/reject)Action required tone--
      accessibility.signals.editsKeptYou accept Copilot's suggested editsEdits kept tone--
      accessibility.signals.editsUndoneYou reject/undo Copilot's suggested editsEdits 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 KeyFires WhenSoundAnnouncement
      accessibility.signals.onDebugBreakDebugger stops on a breakpointBreak tone"Breakpoint"
      +

      Editor Action Signals

      +

      These fire on user-triggered actions and use the "userGesture" value to distinguish manual saves from auto-saves:

      + + + + + + + + + + + + + + + + + + + + + + + +
      Setting KeyFires WhenSound
      accessibility.signals.saveFile is savedSave tone
      accessibility.signals.formatFile is formattedFormat tone
      accessibility.signals.clearTerminal or output is clearedClear tone
      +

      Set these to "userGesture" rather than "on" if auto-save is enabled, to avoid a sound on every keystroke pause:

      +
      {
+  "accessibility.signals.save": {
+    "sound": "userGesture",
+    "announcement": "off"
+  }
+}
      +

      Voice Signals

      + + + + + + + + + + + + + + + + + + +
      Setting KeyFires WhenSound
      accessibility.signals.voiceRecordingStartedVoice dictation beginsRecording started tone
      accessibility.signals.voiceRecordingStoppedVoice dictation endsRecording stopped tone
      +

      Code Action Signals

      + + + + + + + + + + + + + + + + + + +
      Setting KeyFires WhenSound
      accessibility.signals.codeActionTriggeredA code action (quick fix, refactor) is triggeredCode action triggered tone
      accessibility.signals.codeActionAppliedA code action is applied to the codeCode 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:

      + + + + + + + + + + + + + + + + + + + + + + + + + + + + +
      SettingDefaultPurpose
      accessibility.signalOptions.debouncePositionChangestrueEnable 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.

      + +

      Add this to your VS Code settings.json (Ctrl+Shift+P then "Preferences: Open User Settings (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. +
      2. Search for VS Code Speech
        3. +
      3. Find VS Code Speech (publisher: Microsoft, identifier: ms-vscode.vscode-speech)
        4. +
      4. Press Enter to open the extension detail page, then Tab to "Install" and press Enter
        5. +
      +

      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.

      + + + + + + + + + + + + + + + + + + + + + + + +
      ActionWindows/LinuxmacOS
      Start dictationCtrl+Alt+VCmd+Alt+V
      Stop dictationEscapeEscape
      Walky-talky modePress and hold Ctrl+Alt+V, speak, release to stopPress 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.

      + + + + + + + + + + + + + + + + + + + + + + + + + + + + +
      ActionWindows/LinuxmacOS
      Start voice chat (auto-selects best location)Ctrl+ICmd+I
      Start voice in Chat panel specificallyCommand Palette: "Chat: Voice Chat in Chat View"Same
      Start inline voice chatCommand Palette: "Chat: Inline Voice Chat"Same
      Start quick voice chatCommand 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:

      +
      {
+  "accessibility.voice.autoSynthesize": true
+}
      +

      When auto-synthesize is on:

      +
        +
      1. You speak a question using voice chat
        2. +
      2. Copilot responds in text
        3. +
      3. The response is automatically read aloud
        4. +
      4. To stop playback mid-sentence, press Escape or activate the stop icon
        5. +
      +

      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:

      +
      {
+  "accessibility.voice.keywordActivation": "chatInView"
+}
      + + + + + + + + + + + + + + + + + + + + + + + + + + + +
      Setting valueWhat 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:

      +
      {
+  "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

      + + + + + + + + + + + + + + + + + + + + + + + + + + + + +
      SettingDefaultPurpose
      accessibility.voice.speechLanguage"auto"Language for speech recognition and synthesis. "auto" uses your VS Code display language.
      accessibility.voice.speechTimeout1250Milliseconds of silence before auto-submitting a voice chat prompt. Set to 0 to disable auto-submit.
      accessibility.voice.autoSynthesizefalseAutomatically 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

      + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + +
      CommandDefault shortcutWhat it does
      Voice: Start Dictation in EditorCtrl+Alt+V (Mac: Cmd+Alt+V)Begin dictating text at the cursor
      Voice: Stop Dictation in EditorEscapeStop dictation
      Chat: Start Voice ChatCtrl+I (Mac: Cmd+I)Start voice input in the most appropriate chat location
      Chat: Voice Chat in Chat ViewNoneStart voice chat specifically in the Chat panel
      Chat: Inline Voice ChatNoneStart voice chat inline in the editor
      Chat: Quick Voice ChatNoneStart voice chat in the floating quick chat
      Chat: Stop Listening and SubmitNoneEnd voice input and submit the prompt
      Chat: Read AloudNoneRead a specific chat response using text-to-speech
      Chat: Stop Reading AloudEscapeStop 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:

      +
      [
+  {
+    "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

      + + + + + + + + + + + + + + + + + + + +
      PlatformArchitecture
      Windowsx64, ARM
      macOSx64 (Intel), ARM (Apple Silicon)
      Linuxx64, 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. +
      2. Search for markdownlint
        3. +
      3. Install the one by David Anson
        4. +
      +

      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:

      +
      {
+  "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), it can help with Markdown authoring directly in the editor.

      +
        +
      • Generate tables: Type a comment like <!-- table comparing Git commands --> 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

      + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + +
      ActionWindows / LinuxmacOS
      Toggle Markdown preview (full)Ctrl+Shift+VCmd+Shift+V
      Open preview to the sideCtrl+K VCmd+K V
      Go to heading (symbol)Ctrl+Shift+OCmd+Shift+O
      Open Problems panelCtrl+Shift+MCmd+Shift+M
      Toggle boldCtrl+BCmd+B
      Toggle italicCtrl+I (when text is selected)Cmd+I (when text is selected)
      Open inline chat (Copilot)Ctrl+I (when nothing is selected)Cmd+I
      Focus breadcrumbsCtrl+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 to the agent file you create in Chapter 20. Markdown is also how you write pull request descriptions (Chapter 6) 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

      + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + +
      ProblemWhat to do
      Screen Reader Mode not workingPress Shift+Alt+F1 or open Command Palette > "Toggle Screen Reader Mode". Restart VS Code if needed.
      Terminal does not announce outputPress Ctrl+Shift+A to open Accessible Terminal Buffer. Or use Accessible View (Shift+Alt+F2) while the terminal is focused.
      Copilot Chat not respondingVerify 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 errorsOpen 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 workThe 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 playingGo to Settings > search "accessibility signal" > verify the signals you want are set to "on" or "auto". Check your system audio volume.
      Everything elseOpen 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
      Back: Chapter 11: VS Code Interface
      Related appendices: Appendix G: VS Code Reference

      + +
      + + + + diff --git a/html/admin/qa-bundle/docs/13-how-git-works.html b/html/admin/qa-bundle/docs/13-how-git-works.html new file mode 100644 index 00000000..863c7844 --- /dev/null +++ b/html/admin/qa-bundle/docs/13-how-git-works.html @@ -0,0 +1,603 @@ + + + + + + + How Git Works: The Mental Model - GIT Going with GitHub + + + + + + + + +
      +

      How Git Works: The Mental Model

      +
      +

      Related appendices: Appendix E: Advanced Git | Appendix D: Git Authentication | Appendix F: Git Security +Authoritative sources: Git SCM: Git Basics | Git SCM: Branching in a Nutshell | GitHub Docs: 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 will make more sense after reading this.

      +
      +

      Table of Contents

      +
        +
      1. Why a Mental Model Matters
        2. +
      2. The Three Areas: Working Directory, Staging Area, Repository
        3. +
      3. What Is a Commit?
        4. +
      4. What Is a Branch?
        5. +
      5. Local vs Remote
        6. +
      6. Push, Pull, and Fetch
        7. +
      7. Why Merge Conflicts Happen
        8. +
      8. The Git Timeline
        9. +
      9. Putting It All Together
        10. +
      10. If You Get Stuck
        11. +
      +
      +
      +

      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). 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 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. +
      2. Stage the changes you want to keep (add to the staging area)
        3. +
      3. Commit the staged changes (save to the repository)
        4. +
      +

      In Git commands, this looks like:

      +
      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:

      + + + + + + + + + + + + + + + + + + + + + + + + + + + + +
      PartWhat it isExample
      SnapshotThe complete state of all staged filesAll the files as they were when you committed
      MessageA human-readable description of the change"Fix broken link in setup guide"
      AuthorWho made the commit (name and email)Jane Developer, jane@example.com
      Parent pointerWhich commit came before this oneA 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:

      +
      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 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.

      +
      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.

      +
        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 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

      + + + + + + + + + + + + + + + + + + + + + + + + + + + + +
      OperationDirectionWhat it does
      git cloneRemote to localCreates a new local copy of the entire remote repository
      git pushLocal to remoteSends your local commits to the remote repository
      git pullRemote to localDownloads new commits from the remote and merges them into your branch
      git fetchRemote to localDownloads new commits from the remote but does not merge them
      +

      The two-copy model

      +
      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.

      +
      git push origin fix/typo
      +

      If this is the first push for a new branch, use:

      +
      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.

      +
      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.

      +
      git fetch origin
      +

      After fetching, you can compare your branch with the remote's version:

      +
      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:

      +
      <<<<<<< HEAD
+This is the text from your current branch.
+=======
+This is the text from the branch you are merging in.
+>>>>>>> fix/typo
      + + + + + + + + + + + + + + + + + + + +
      MarkerMeaning
      <<<<<<< HEADStart of your current branch's version
      =======Divider between the two versions
      >>>>>>> fix/typoEnd of the incoming branch's version
      +

      How to resolve a conflict

      +
        +
      1. Open the file with the conflict markers
        2. +
      2. Read both versions and decide which text to keep (or write a new version that combines both)
        3. +
      3. Delete the conflict markers (<<<<<<<, =======, >>>>>>>)
        4. +
      4. Save the file
        5. +
      5. Stage and commit the resolved file
        6. +
      +
      +

      The Day 1 connection: In Chapter 7, 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.

      +
      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:

      +
                        +-- 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.

      +
                        +-- 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, translated through the mental model:

      + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + +
      StepWhat you doWhat Git does
      Clone the repogit clone URLCopies the entire remote repository to your computer
      Create a branchgit checkout -b fix/typoCreates a new pointer at your current commit and switches HEAD to it
      Edit a fileOpen and modify the fileGit detects the change in the working directory
      Stage the changegit add file.mdMoves the change from the working directory to the staging area
      Commitgit commit -m "Fix typo"Takes a snapshot of the staging area and stores it in the repository
      Pushgit push -u origin fix/typoSends your commit to the remote repository on GitHub
      Open a PROn GitHub.comProposes merging your branch into main
      MergePR merged on GitHub.comCreates a merge commit that joins your branch back into main
      Pullgit pull origin mainDownloads 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

      + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + +
      SituationWhat 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 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 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 and Stack Overflow both have clear explanations.
      +
      +

      Next: Chapter 14: Git in Practice
      Back: Chapter 12: VS Code Accessibility
      Related appendices: Appendix E: Advanced Git | Appendix D: Git Authentication

      + +
      + + + + diff --git a/html/admin/qa-bundle/docs/14-git-in-practice.html b/html/admin/qa-bundle/docs/14-git-in-practice.html new file mode 100644 index 00000000..48ef1c9d --- /dev/null +++ b/html/admin/qa-bundle/docs/14-git-in-practice.html @@ -0,0 +1,2089 @@ + + + + + + + Git & Source Control in VS Code - GIT Going with GitHub + + + + + + + + +
      +

      Git & Source Control in VS Code

      +
      +

      Listen to Episode 12: Git and Source Control in VS Code - 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 D: Git Authentication | Appendix H: GitHub Desktop +Authoritative sources: VS Code Docs: Source Control | GitHub Docs: 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, Working with Pull Requests, Merge Conflicts

      +

      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. +
      2. Create a branch and make one commit - check out (or create) your learn/<username> branch, edit a file, stage, write a clear commit message, and commit locally.
        3. +
      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.
        4. +
      +

      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/<workshop-org>/learning-room-<your-username>.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. +
      2. Open the Command Palette: Ctrl+Shift+P (Mac: Cmd+Shift+P).
        3. +
      3. Type git clone and select Git: Clone.
        4. +
      4. VS Code asks for a repository URL. Paste your Learning Room repo URL (it looks like https://github.com/<workshop-org>/learning-room-<your-username>.git). You can copy this from the green Code button on your repo's GitHub page.
        5. +
      5. Press Enter.
        6. +
      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. +
      7. VS Code clones the repository. When it finishes, a notification appears asking "Would you like to open the cloned repository?" Activate Open.
        8. +
      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.
        9. +
      +

      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/<username> branch). Run git branch -a in the terminal (Ctrl+`) to see all branches -- local and remote:

      +
      git branch -a
      +

      You will see output like:

      +
      * 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 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. +
      2. If your learn/<username> branch already exists on the remote (because you created it during Day 1), type git checkout and select Git: Checkout to..., then pick learn/<your-username>. If the branch does not exist yet, type git create branch and select Git: Create Branch... and enter learn/<your-username>.
        3. +
      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. +
      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. +
      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. +
      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. +
      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. +
      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. +
      9. Press Ctrl+Enter (Mac: Cmd+Enter) to commit. The staged changes disappear, which means your commit succeeded.
        10. +
      +

      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. +
      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. +
      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. +
      4. Open your browser and navigate to your Learning Room repository on GitHub.
        5. +
      5. GitHub usually shows a yellow banner: "yourname recently pushed to learn/yourname." Activate the Compare & pull request button in that banner.
        6. +
      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/<your-username> branch.
        7. +
      7. In the PR title, write a descriptive title (for example: "docs: improve welcome.md introduction").
        8. +
      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. +
      9. Activate the Create pull request button.
        10. +
      +

      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 <owner>/<repo>#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:

      +
      Challenge 10 completed:
+- Repository cloned: <my Learning Room repo>
+- Branch name: learn/<yourname>
+- 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. +
      2. Source Control panel is empty? You may not have saved your file yet. Press Ctrl+S to save, then check again.
        3. +
      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. +
      4. Branch name wrong? Open Command Palette, run Git: Rename Branch... to fix it before pushing.
        5. +
      5. Cannot find the "Compare & pull request" banner on GitHub? Navigate to Pull requests tab and create the PR manually (step 6 above).
        6. +
      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. +
      7. Ask facilitator to verify your clone location, branch name, and help with one push.
        8. +
      8. Finished but not sure you did it right? Compare your work against the Challenge 10 reference solution.
        9. +
      +
      +

      Continue learning: The GitHub Skills course Introduction to Git walks through commits, branches, and merges in an interactive, self-paced format. See Appendix Z 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. +
      2. Branch before editing (never work directly on main).
        3. +
      3. Make small, focused edits with clear commit messages.
        4. +
      4. Push and open a PR that links to an issue for traceability.
        5. +
      5. Verify each step before moving to the next.
        6. +
      +

      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.

      + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + +
      CardWho it is for
      Visual / mouse usersSighted users navigating with a mouse or trackpad
      Low vision usersUsers 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 interfaceBrowser-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
        2. +
      2. The Source Control Panel - Complete Walkthrough
        3. +
      3. Branch Management
        4. +
      4. Staging Changes - Files, Lines, and Chunks
        5. +
      5. Committing with Screen Readers
        6. +
      6. Push and Pull Operations
        7. +
      7. Discarding Changes
        8. +
      8. Timeline View - File History and Blame
        9. +
      9. Resolving Merge Conflicts in VS Code
        10. +
      10. Stash Management
        11. +
      11. Emergency Recovery - git reflog
        12. +
      12. Alternative Git Interfaces
        13. +
      +

      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.
        2. +
      +

      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.
        2. +
      +

      Git CLI (terminal):

      +
      git clone https://github.com/owner/repo.git && cd repo
      +

      GitHub CLI:

      +
      gh repo clone owner/repo && cd repo
      +

      Three ways to clone a repository

      + +
        +
      1. Open Command Palette: Ctrl+Shift+P (Mac: Cmd+Shift+P)
        2. +
      2. Type "git clone"
        3. +
      3. Select "Git: Clone"
        4. +
      4. Paste the repository URL (example: https://github.com/community-access/accessibility-agents.git)
        5. +
      5. Press Enter
        6. +
      6. Choose a local folder where the repository should be cloned
        7. +
      7. VS Code asks: "Would you like to open the cloned repository?" - select "Open"
        8. +
      +

      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. +
      2. The Start page appears
        3. +
      3. Navigate to "Clone Git Repository" button - press Enter
        4. +
      4. Paste repository URL → Enter
        5. +
      5. Choose destination folder
        6. +
      6. Open when prompted
        7. +
      +

      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. +
      2. Copy the HTTPS URL (recommended) or SSH URL
        3. +
      3. Open VS Code → Ctrl+Shift+P (Mac: Cmd+Shift+P) → "Git: Clone"
        4. +
      4. Paste URL → Enter
        5. +
      5. Choose destination → Open
        6. +
      +

      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. +
      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. +
      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. +
      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.
        5. +
      +
      + +
      +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. +
      2. Press . (period) to open github.dev - a browser-based VS Code editor
        3. +
      3. The full repository opens in an editor with file tree, search, and editing
        4. +
      4. Changes are committed directly to GitHub from the browser
        5. +
      +

      Alternatively, for quick edits:

      +
        +
      1. Navigate to any file on GitHub
        2. +
      2. Press E to open the file editor
        3. +
      3. Make changes and commit from the web editor
        4. +
      +

      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:

      +
      # 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 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. +
      2. Choose a destination folder and open when prompted
        3. +
      3. Navigate to the themes/ folder and pick a .json file (star-trek, hitchhikers, or star-wars)
        4. +
      4. Copy the chat.agent.thinking.phrases setting into your VS Code settings.json
        5. +
      5. Reload VS Code: Ctrl+Shift+P → "Developer: Reload Window"
        6. +
      6. Open Copilot Chat (Ctrl+Shift+I) and ask a question—watch your custom phrases appear!
        7. +
      +

      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. +
      2. Click any file to view it, then click the pencil icon (Edit) to modify it directly in the browser
        3. +
      3. GitHub automatically creates a branch and commit for your edit
        4. +
      4. When you save, GitHub prompts you to open a pull request
        5. +
      +

      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:

      +
      # 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. +

      2. Commit message input (multi-line text field)

        +
          +
        • Type your commit message here
          • +
        • Announced as "Source Control Input, edit, multi-line"
          • +
        +
        3. +

      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. +

      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. +

      5. Staged Changes section (collapsible tree)

        +
          +
        • Lists files staged for commit
          • +
        • Empty if nothing staged yet
          • +
        • Announced as "Staged Changes, expanded"
          • +
        +
        6. +

      6. Merge Changes section (appears only during a merge)

        +
          +
        • Lists files with conflicts
          • +
        • See Section 9 for conflict resolution workflow
          • +
        +
        7. +
      +

      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:

      + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + +
      LetterMeaning
      MModified - file exists and was changed
      AAdded - new file, not in Git yet
      DDeleted - file was removed
      RRenamed - file was moved or renamed
      UUntracked - file exists but Git is ignoring it
      CConflict - 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:

      + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + +
      ActionWhat It Does
      Open FileOpens the file in the editor (same as Enter)
      Open ChangesOpens side-by-side diff view (same as Enter)
      Stage ChangesMoves file from Changes → Staged Changes
      Unstage ChangesMoves file from Staged Changes → Changes
      Discard ChangesDangerous - deletes your local edits, restores file to last commit
      Stage Selected RangesStage only specific lines (see Section 4)
      Revert Selected RangesDiscard 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. +
      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. +
      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. +
      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. +
      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.
        6. +
      +
      + +
      +CLI equivalent: viewing Git status + +

      The Source Control panel shows the same information as these terminal commands:

      +
      # 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. +
      2. Source Control panel title bar
        3. +
      3. Command Palette: Ctrl+Shift+P (Mac: Cmd+Shift+P) → "Git: Show Git Output"
        4. +
      +

      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

      + +
        +
      1. Ctrl+Shift+P (Mac: Cmd+Shift+P)
        2. +
      2. Type "git create branch"
        3. +
      3. Select "Git: Create Branch..."
        4. +
      4. Type the new branch name (example: feature/improve-docs)
        5. +
      5. Press Enter
        6. +
      +

      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. +
      2. Type a new branch name in the search field
        3. +
      3. Click "Create branch: your-branch-name from main"
        4. +
      4. GitHub switches to the new branch immediately
        5. +
      5. Any file edits you make in the browser will be on this branch
        6. +
      +

      To switch between branches, click the branch dropdown and select the branch you want.

      +
      + +
      +Git CLI alternative - branch management + +

      Manage branches from your terminal:

      +
      # 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. +
      2. Type "git checkout"
        3. +
      3. Select "Git: Checkout to..."
        4. +
      4. A list of all branches appears
        5. +
      5. Up/Down Arrow to navigate
        6. +
      6. Enter to switch
        7. +
      +

      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. +
      2. Type "git delete branch"
        3. +
      3. Select "Git: Delete Branch..."
        4. +
      4. Choose the branch to delete from the list
        5. +
      5. Confirm
        6. +
      +

      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:

      +
      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. +
      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. +
      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.
        4. +
      +
      + +
      +Screen reader users (NVDA / JAWS on Windows) + +

      Creating a branch

      +
        +
      1. Press Ctrl+Shift+P to open the Command Palette
        2. +
      2. Type "git create branch" - NVDA/JAWS announces results as you type
        3. +
      3. Press Enter on "Git: Create Branch..."
        4. +
      4. The input focus moves to a text field - type your branch name (e.g., feature/add-docs)
        5. +
      5. Press Enter - VS Code creates and switches to the branch
        6. +
      6. NVDA/JAWS announces the new branch name in the status bar notification
        7. +
      +

      Switching branches

      +
        +
      1. Press Ctrl+Shift+P, type "git checkout"
        2. +
      2. Select "Git: Checkout to..."
        3. +
      3. A list of branches appears - navigate with Up/Down Arrow
        4. +
      4. Each item is announced as the branch name (e.g., "main", "feature/add-docs")
        5. +
      5. Press Enter to switch
        6. +
      6. VS Code reloads files for that branch - you hear a status bar update
        7. +
      +

      Deleting a branch

      +
        +
      1. Switch to a different branch first (you cannot delete the branch you are on)
        2. +
      2. Press Ctrl+Shift+P, type "git delete branch"
        3. +
      3. Select "Git: Delete Branch..."
        4. +
      4. Navigate the list to find the branch to delete, press Enter
        5. +
      +
      + +
      +Screen reader users (VoiceOver on macOS) + +

      Creating a branch

      +
        +
      1. Press Cmd+Shift+P to open the Command Palette
        2. +
      2. Type "git create branch" - VoiceOver announces filtered results
        3. +
      3. Press Return on "Git: Create Branch..."
        4. +
      4. Type the branch name in the input field
        5. +
      5. Press Return to create and switch
        6. +
      +

      Switching branches

      +
        +
      1. Press Cmd+Shift+P, type "git checkout"
        2. +
      2. Select "Git: Checkout to..."
        3. +
      3. Use VO+Down Arrow to navigate the branch list
        4. +
      4. Press Return to switch
        5. +
      +

      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. +
      2. Or use the Command Palette: Cmd+Shift+P then type "Git: Show Git Output" - the output pane includes the current branch
        3. +
      +
      + +
      +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. +
      2. Click or activate the dropdown
        3. +
      3. Type a new branch name in the search field
        4. +
      4. Click "Create branch: your-branch-name from main" when it appears
        5. +
      5. GitHub switches to the new branch immediately
        6. +
      6. Any file edits in the browser will be on this branch
        7. +
      +

      To switch between branches:

      +
        +
      1. Click the branch dropdown
        2. +
      2. Select the branch you want - the page reloads with that branch's files
        3. +
      +

      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. +
      2. Find the branch
        3. +
      3. Click the trash can icon next to it
        4. +
      +
      + +
      +CLI (git / gh) + +

      Manage branches from your terminal:

      +
      # 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:

      +
      # 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. +
      2. Commit those staged changes
        3. +
      +

      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. +
      2. Hover over a file in the "Changes" list - a + icon appears to its right
        3. +
      3. Click the + to stage that file
        4. +
      4. Or right-click a file → "Stage Changes"
        5. +
      +
      + +
      +Low vision users (zoom, high contrast) + +
        +
      1. Open Source Control: Ctrl+Shift+G (Mac: Cmd+Shift+G)
        2. +
      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. +
      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. +
      4. In high contrast themes, staged files show a distinct background or border in the Staged Changes section.
        5. +
      +
      + +
      +Screen reader users (NVDA / JAWS / VoiceOver) + +
        +
      1. Open Source Control: Ctrl+Shift+G (Mac: Cmd+Shift+G)
        2. +
      2. Navigate to the file in the "Changes" list
        3. +
      3. Press Ctrl+Enter (Mac: Cmd+Enter) to stage immediately
        4. +
      +

      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. +
      2. Navigate to the "Changes" section heading
        3. +
      3. Press Shift+F10 (Mac: Ctrl+Return) to open context menu on the section itself
        4. +
      4. Select "Stage All Changes"
        5. +
      +

      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. +
      2. Navigate to a file in "Changes"
        3. +
      3. Press Enter to open the diff view
        4. +
      4. The diff shows your changes side-by-side or inline
        5. +
      5. Navigate to a changed line (use Arrow keys or F7 for next hunk)
        6. +
      6. Press Shift+F10 (Mac: Ctrl+Return) to open context menu
        7. +
      7. Select "Stage Selected Lines"
        8. +
      +

      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. +
      2. Make your changes
        3. +
      3. Click "Commit changes" - GitHub creates the commit directly
        4. +
      4. Choose to commit to the current branch or create a new branch and PR
        5. +
      +

      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:

      +
      # 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. +
      2. Press Ctrl+Enter (Mac: Cmd+Enter) or Space
        3. +
      3. File moves back to "Changes"
        4. +
      +

      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. +
      2. Stage changes (see Section 4)
        3. +
      3. Focus the commit message input (usually Tab or Shift+Tab to reach it)
        4. +
      4. Type your commit message
        5. +
      5. Press Ctrl+Enter (Mac: Cmd+Enter) to commit
        6. +
      +

      Learning Cards: Committing

      +
      +Visual / mouse users + +
        +
      1. Open Source Control (Ctrl+Shift+G)
        2. +
      2. Stage your files (click the + icon next to each file, or click Stage All Changes above the Changes section header)
        3. +
      3. Click in the "Message" text area at the top of the Source Control panel
        4. +
      4. Type your commit message
        5. +
      5. Click the Commit button (checkmark icon) or press Ctrl+Enter
        6. +
      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
        7. +
      +
      + +
      +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. +
      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. +
      3. After committing, the Staged Changes section clears. The count next to the section heading drops to 0, confirming the commit was recorded.
        4. +
      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.
        5. +
      +
      + +

      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 for format guidance.

      +

      Quick reference

      +
      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:

      +
      # 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. +
      2. Look for the "Publish Branch" button (if this is a new branch) or "Sync Changes" button
        3. +
      3. Press Enter on that button
        4. +
      +

      Alternative: Command Palette

      +
        +
      1. Ctrl+Shift+P (Mac: Cmd+Shift+P)
        2. +
      2. Type "git push"
        3. +
      3. Select "Git: Push"
        4. +
      4. VS Code pushes your commits to GitHub
        5. +
      +

      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. +
      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. +
      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. +
      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.
        5. +
      +
      + +
      +Screen reader users (NVDA / JAWS on Windows) + +

      Pushing

      +
        +
      1. After committing, press Ctrl+Shift+P, type "git push", select "Git: Push"
        2. +
      2. NVDA/JAWS announces "Pushing..." in the status bar
        3. +
      3. On success, a notification appears: "Successfully pushed" - if using NVDA, check NVDA+N to read recent notifications
        4. +
      4. For a new branch (first push), use "Git: Publish Branch" instead - this sets up the upstream tracking
        5. +
      +

      Pulling

      +
        +
      1. Press Ctrl+Shift+P, type "git pull", select "Git: Pull"
        2. +
      2. NVDA/JAWS announces "Pulling..." then the status changes
        3. +
      3. If there are conflicts, the Source Control panel shows a "Merge Changes" section - navigate there with Ctrl+Shift+G then Down Arrow
        4. +
      +

      Checking sync status

      +
        +
      1. Press Ctrl+Shift+P, type "Git: Show Git Output"
        2. +
      2. The output pane opens with push/pull log messages in plain text
        3. +
      3. Use Up/Down Arrow to read line by line
        4. +
      +
      + +
      +Screen reader users (VoiceOver on macOS) + +

      Pushing

      +
        +
      1. Press Cmd+Shift+P, type "git push", select "Git: Push"
        2. +
      2. VoiceOver announces progress from the status bar
        3. +
      3. On success, a notification toast appears - press VO+F3 to read the latest notification
        4. +
      +

      Pulling

      +
        +
      1. Press Cmd+Shift+P, type "git pull", select "Git: Pull"
        2. +
      2. VoiceOver announces when the pull completes
        3. +
      3. If conflicts exist, navigate to Source Control (Cmd+Shift+G) and review the Merge Changes section
        4. +
      +
      + +

      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:

      +
      # 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)
        • +
      • 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. +
      2. Type "git pull"
        3. +
      3. Select "Git: Pull"
        4. +
      4. VS Code fetches and merges remote changes
        5. +
      +

      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. +
      2. On the repository page, look for the "This branch is N commits behind owner/repo:main" notice
        3. +
      3. Activate the "Sync fork" button next to it
        4. +
      4. GitHub automatically merges upstream changes into your fork's default branch
        5. +
      5. Then pull those changes to your local clone: Git: Pull from the Command Palette
        6. +
      +

      Screen reader path

      +
      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.

      +
      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

      +
      git remote add upstream https://github.com/community-access/accessibility-agents.git
      +

      Fetching and Merging Upstream Changes

      +

      Once your upstream remote is configured:

      +
      # 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

      +
      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 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. +
      2. Navigate to the file in "Changes"
        3. +
      3. Press Shift+F10 for context menu
        4. +
      4. Select "Discard Changes"
        5. +
      5. Confirm in the warning dialog (VS Code will ask "Are you sure?")
        6. +
      +

      All changes

      +
        +
      1. Ctrl+Shift+G
        2. +
      2. Navigate to the "Changes" section heading
        3. +
      3. Shift+F10 for context menu
        4. +
      4. Select "Discard All Changes"
        5. +
      5. Confirm (this affects every modified file)
        6. +
      +

      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. +
      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. +
      3. For "Discard All Changes", right-click the "Changes" section heading to get the context menu.
        4. +
      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").
        5. +
      +
      + +
      +Screen reader users (NVDA / JAWS on Windows) + +

      Single file

      +
        +
      1. Press Ctrl+Shift+G to open Source Control
        2. +
      2. Navigate to the file in the Changes section with Down Arrow
        3. +
      3. Press Shift+F10 to open the context menu
        4. +
      4. Navigate to "Discard Changes" with Down Arrow, press Enter
        5. +
      5. A confirmation dialog appears - NVDA announces "Are you sure you want to discard changes" or similar
        6. +
      6. Press Tab to navigate between "Discard" and "Cancel", press Enter on your choice
        7. +
      +

      All files

      +
        +
      1. Navigate to the "Changes" section heading (announced as "Changes, expanded, N items")
        2. +
      2. Press Shift+F10, select "Discard All Changes"
        3. +
      3. Confirm in the dialog
        4. +
      +
      + +
      +Screen reader users (VoiceOver on macOS) + +
        +
      1. Press Cmd+Shift+G to open Source Control
        2. +
      2. Use VO+Arrow keys to navigate to the file
        3. +
      3. Press VO+Shift+M to open the context menu (or Ctrl+Return)
        4. +
      4. Navigate to "Discard Changes", press VO+Space
        5. +
      5. In the confirmation dialog, use VO+Right Arrow to reach the buttons, VO+Space to activate
        6. +
      +
      + +
      +CLI (git / gh) + +

      Discard changes from your terminal:

      +
      # 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. +
      2. Ctrl+Shift+P (Mac: Cmd+Shift+P)
        3. +
      3. Type "Git: Delete"
        4. +
      4. Confirm the deletion
        5. +
      +

      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. +
      2. Select "Delete" to delete from your file system
        3. +
      3. The file appears in Source Control (Ctrl+Shift+G) under Changes with a "D" (deleted) status
        4. +
      4. Stage and commit the deletion to record it in Git
        5. +
      +

      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. +
      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. +
      3. Stage and commit as normal.
        4. +
      +
      + +
      +Screen reader users (NVDA / JAWS / VoiceOver) + +
        +
      1. Open the file you want to remove in the editor
        2. +
      2. Press Ctrl+Shift+P (Mac: Cmd+Shift+P), type "Git: Delete"
        3. +
      3. Select the command - the file is deleted and staged for removal
        4. +
      4. Navigate to Source Control (Ctrl+Shift+G) - the file is announced as "filename, Deleted" in the Staged Changes section
        5. +
      5. Write a commit message and press Ctrl+Enter to commit the removal
        6. +
      +

      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. +
      2. Click the three-dot menu ("...") in the file header
        3. +
      3. Select "Delete file"
        4. +
      4. Write a commit message describing why the file was removed
        5. +
      5. Choose to commit directly or open a PR
        6. +
      6. Click "Commit changes"
        7. +
      +

      For screen reader users on GitHub: press Tab to navigate to the file actions menu, then Enter to open it.

      +
      + +
      +CLI (git / gh) + +
      # 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. +
      2. At the bottom of the Explorer, there's a "Timeline" section
        3. +
      3. Tab or Arrow to navigate into Timeline
        4. +
      4. The list shows all commits affecting the currently open file
        5. +
      +

      Method 2: Command Palette

      +
        +
      1. Open a file in the editor
        2. +
      2. Ctrl+Shift+P
        3. +
      3. Type "timeline"
        4. +
      4. Select "View: Show Timeline"
        5. +
      +

      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. +
      2. Press Enter
        3. +
      3. A diff view opens showing what changed in that specific commit
        4. +
      +

      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. +
      2. Ctrl+Shift+P
        3. +
      3. Type "git blame"
        4. +
      4. Select "Git: Toggle Blame"
        5. +
      +

      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):

      + + + + + + + + + + + + + + + + + + +
      SettingDefaultWhat It Does
      git.blame.ignoreWhitespacefalseWhen true, whitespace-only changes (reformatting) are excluded from blame - useful when code was reformatted without logic changes
      git.blame.editorDecoration.disableHoverfalseWhen 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. +
      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. +
      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. +
      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.
        5. +
      +
      + +
      +Screen reader users (NVDA / JAWS on Windows) + +

      Opening Timeline

      +
        +
      1. Press Ctrl+Shift+E to open Explorer
        2. +
      2. Press Tab repeatedly or Down Arrow to navigate past the file tree to the "Timeline" section
        3. +
      3. Press Right Arrow to expand it if collapsed
        4. +
      4. Navigate commit entries with Up/Down Arrow
        5. +
      5. Each entry is announced as: "commit message, author, time" (e.g., "docs: add Timeline Guide, Jeff, 2 days ago")
        6. +
      6. Press Enter on any entry to open its diff view
        7. +
      +

      Reading a diff with screen reader

      +
        +
      1. In the diff view, press Alt+F2 to open the Accessible Diff Viewer
        2. +
      2. The Accessible Diff Viewer presents changes as a text list: each line shows + (added), - (removed), or unchanged
        3. +
      3. Navigate with Up/Down Arrow to read each line
        4. +
      4. Press Escape to close the Accessible Diff Viewer
        5. +
      +

      Git Blame

      +
        +
      1. Open a file, press Ctrl+Shift+P, type "Git: Toggle Blame"
        2. +
      2. Blame annotations appear inline - NVDA reads them when navigating lines
        3. +
      3. To reduce noise, disable blame (repeat the toggle command) and use Timeline instead
        4. +
      +
      + +
      +Screen reader users (VoiceOver on macOS) + +

      Opening Timeline

      +
        +
      1. Press Cmd+Shift+E to open Explorer
        2. +
      2. Use VO+Down Arrow to navigate below the file tree to the Timeline section
        3. +
      3. Press VO+Space to expand if collapsed
        4. +
      4. Navigate entries with VO+Down Arrow
        5. +
      5. Press VO+Space on a commit to open its diff
        6. +
      +

      Accessible Diff Viewer

      +
        +
      1. In any diff view, press Option+F2 to open the Accessible Diff Viewer
        2. +
      2. Read changes line by line with VO+Down Arrow
        3. +
      3. Press Escape to close
        4. +
      +
      + +
      +CLI (git / gh) - history and blame + +
      # 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:

      +
      # 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 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:

      +
      <<<<<<< 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. +

      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. +

      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. +

      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. +

      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
          • +
        +
        6. +
      +

      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. +
      2. Press F7 to jump to the first conflict hunk
        3. +
      3. Press Alt+F2 to open Accessible View
        4. +
      4. Read both versions clearly
        5. +
      5. Press Escape to return to editor
        6. +
      6. Manually edit to resolve
        7. +
      7. Press F7 to jump to the next conflict
        8. +
      8. Repeat until all conflicts resolved
        9. +
      +

      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. +
      2. Type "git abort"
        3. +
      3. Select "Git: Abort Merge"
        4. +
      +

      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. +
      2. Type "git stash"
        3. +
      3. Select "Git: Stash"
        4. +
      4. Optionally type a stash message (helps you remember what's in it)
        5. +
      +

      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. +
      2. Type "git stash list"
        3. +
      3. Select "Git: Show Stash"
        4. +
      +

      Alternative: Integrated Terminal

      +
      git stash list
      +

      Output looks like:

      +
      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. +
      2. Type "git stash apply"
        3. +
      3. Select "Git: Apply Latest Stash"
        4. +
      +

      Or to apply a specific stash

      +
        +
      1. Ctrl+Shift+P
        2. +
      2. Type "git stash pop"
        3. +
      3. Select "Git: Pop Stash..."
        4. +
      4. Choose which stash from the list
        5. +
      +

      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. +
      2. Type "git stash drop"
        3. +
      3. Select "Git: Drop Stash..."
        4. +
      4. Choose which stash to delete
        5. +
      +

      Learning Cards: Stash Management

      +
      +Visual / mouse users + +
        +
      1. Open Source Control: Ctrl+Shift+G
        2. +
      2. In the Source Control panel, there may be a "Stashes" section below Staged Changes (visible when stashes exist)
        3. +
      3. Click a stash to see what it contains
        4. +
      4. Right-click a stash to Apply, Pop, or Drop it
        5. +
      +

      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. +
      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. +
      3. After applying a stash, your files reappear in the Changes section of Source Control. Check the file count to confirm.
        4. +
      +
      + +
      +Screen reader users (NVDA / JAWS on Windows) + +

      Creating a stash

      +
        +
      1. Press Ctrl+Shift+P, type "git stash"
        2. +
      2. Select "Git: Stash" - NVDA announces the result
        3. +
      3. An input appears asking for a stash message - type something descriptive (e.g., "WIP: documentation changes for Timeline section")
        4. +
      4. Press Enter - your changes disappear from Source Control and are saved in the stash
        5. +
      5. NVDA announces the Source Control panel update (file counts drop to 0)
        6. +
      +

      Applying a stash

      +
        +
      1. Press Ctrl+Shift+P, type "git stash pop"
        2. +
      2. Select "Git: Pop Stash..."
        3. +
      3. A list of stashes appears - navigate with Up/Down Arrow
        4. +
      4. Each item is announced with the stash message you wrote
        5. +
      5. Press Enter to apply and delete the stash
        6. +
      6. Your changes reappear in the Changes section
        7. +
      +

      Viewing stashes

      +
        +
      1. Press Ctrl+Shift+P, type "git stash list"
        2. +
      2. Or in the terminal: type git stash list and read the output line by line
        3. +
      +
      + +
      +Screen reader users (VoiceOver on macOS) + +
        +
      1. Press Cmd+Shift+P, type "git stash"
        2. +
      2. Select "Git: Stash" and provide a message
        3. +
      3. Press Return
        4. +
      4. To apply: Cmd+Shift+P, type "git stash pop", select from the list with VO+Down Arrow, press Return
        5. +
      +
      + +
      +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. +
      2. Or use GitHub Codespaces (which runs a full VS Code environment in the browser and supports git stash in the terminal)
        3. +
      +
      + +
      +CLI (git / gh) - stash commands + +
      # 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

      + + + + + + + + + + + + + + + + + + + + + + + + + + + + +
      ScenarioWhat happenedReflog solution
      Deleted a branch by mistakegit branch -D feature/xFind the last commit SHA from reflog → recreate branch
      git reset --hard lost commitsMoved HEAD to older commitFind the SHA before the reset → reset back to it
      Rebase went wrongCommits appear lostFind pre-rebase HEAD → reset to it
      Accidentally force-pushedLocal history destroyedFind the SHA from reflog → restore
      +

      Reading the Reflog in VS Code Terminal

      +
      git reflog
      +

      Output looks like:

      +
      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: <SHA> HEAD@{N}: <what happened>

      +

      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

      +
      # 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

      +
      # 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 <SHA>
        • +
      • 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
        • +
      • 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

      +
      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 for more gh examples.

      +

      Git CLI (Terminal)

      +
        +
      • The standard Git command-line interface
        • +
      • Included with VS Code (integrated terminal: Ctrl+Backtick)
        • +
      +

      Common commands

      +
      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

      + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + +
      ActionShortcut
      Open Source ControlCtrl+Shift+G
      Stage fileCtrl+Enter (on file in Changes)
      Unstage fileCtrl+Enter (on file in Staged Changes)
      CommitCtrl+Enter (in message input)
      View file diffEnter (on file in Source Control)
      Next diff hunkF7
      Previous diff hunkShift+F7
      Open Accessible Diff ViewerAlt+F2 (in diff view)
      Accessible HelpAlt+H (in any panel)
      Open Timeline viewCtrl+Shift+E → navigate to Timeline section
      Integrated terminalCtrl+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. +
      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. +
      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. +
      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. +
      5. Commit - Tab to the message input, type feat: add new thinking phrase, press Ctrl+Enter.
        6. +
      6. Push - Press Ctrl+Shift+P → Git: Push.
        7. +
      +

      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
      Back: Chapter 13: How Git Works
      Related appendices: Appendix E: Advanced Git | Appendix D: Git Authentication

      + +
      + + + + diff --git a/html/admin/qa-bundle/docs/15-code-review.html b/html/admin/qa-bundle/docs/15-code-review.html new file mode 100644 index 00000000..49fd2c41 --- /dev/null +++ b/html/admin/qa-bundle/docs/15-code-review.html @@ -0,0 +1,2745 @@ + + + + + + + Code Review: PRs, Diffs, and Constructive Feedback - GIT Going with GitHub + + + + + + + + +
      +

      Code Review: PRs, Diffs, and Constructive Feedback

      +
      +

      Related appendices: Appendix G: VS Code Reference | Appendix C: Markdown Reference +Authoritative sources: GitHub Docs: Reviewing changes in pull requests | GitHub Accessibility Guide: Pull Request Reviews

      +
      +
      +

      Day 2, Block 2 Material

      +

      This chapter unifies PR management, accessible code review, and the reviewer's craft into one chapter. Part 1 covers the GitHub Pull Requests extension in VS Code. Part 2 covers accessible code review with diffs and inline comments. Part 3 adds the reviewer's judgment framework.

      +
      +
      +

      Part 1: The GitHub Pull Requests Extension

      +
      +

      See also: Appendix G: VS Code Reference for the complete list of GitHub Pull Requests extension keyboard shortcuts.

      +
      +
      +

      Listen to Episode 13: The GitHub Pull Requests Extension - a conversational audio overview of this chapter. Listen before reading to preview the concepts, or after to reinforce what you learned.

      +
      +

      Managing Pull Requests from VS Code

      +
      +

      Day 2, Block 2 Material

      +

      This guide covers the GitHub Pull Requests and Issues extension: viewing open PRs, checking out PR branches for local testing, reviewing PRs with screen reader-accessible tools, creating PRs directly from VS Code, using PR templates, and syncing PR status with GitHub.

      +

      Prerequisites: Working with Pull Requests, Git & Source Control in VS Code

      +

      Mac keyboard shortcuts: Throughout this chapter, all Ctrl+ shortcuts use Cmd+ on Mac, and Alt+ shortcuts use Option+ on Mac. For example: Ctrl+Shift+P → Cmd+Shift+P, Ctrl+Shift+G → Cmd+Shift+G, Alt+F2 → Option+F2. Context menus (Shift+F10 on Windows) use Ctrl+Return on Mac.

      +
      +

      Workshop Recommendation (Chapter 15, Part 1)

      +

      Chapter 15, Part 1 introduces the GitHub Pull Requests extension for managing PRs directly from VS Code.

      +
        +
      • Challenge count: 2 guided challenges
        • +
      • Automation check: none (extension installation and review state are account-local)
        • +
      • Evidence: issue comment with confirmation of actions completed
        • +
      • Pattern: install, check out, review, comment
        • +
      +

      Chapter 15, Part 1 Practice Set

      +
        +
      1. Install the GitHub Pull Requests extension - add the extension to VS Code and sign in with your GitHub account.
        2. +
      2. Check out a PR and post a review comment - download a PR branch locally, read the diff, and post one constructive review comment.
        3. +
      +

      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. +
      2. Your screen reader announces "Extensions: Marketplace." The search box has focus.
        3. +
      3. Type GitHub Pull Requests in the search box and press Enter.
        4. +
      4. Navigate down the results list. Select GitHub Pull Requests (publisher: GitHub).
        5. +
      5. Activate the Install button. VS Code installs the extension and may show a notification.
        6. +
      6. After installation, VS Code prompts you to sign in. Activate Sign in to GitHub.
        7. +
      7. A browser window opens for GitHub OAuth. Approve the authorization and return to VS Code.
        8. +
      8. Verify: open the Explorer sidebar (Ctrl+Shift+E). You should now see a GitHub section in the sidebar showing Pull Requests and Issues.
        9. +
      +

      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. +
      2. Type GitHub Pull Requests: Focus on Pull Requests View and select it. The Pull Requests panel opens.
        3. +
      3. Navigate the list of open PRs. Find one that is not yours (a classmate's PR from Chapter 6, 7, or 14).
        4. +
      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. +
      5. Open the Command Palette again and run GitHub Pull Requests: Open Changed Files. This shows the list of files the PR changed.
        6. +
      6. Open one changed file. VS Code opens the Diff Editor showing old content on the left and new content on the right.
        7. +
      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. +
      8. Find one specific thing to comment on: a typo, an unclear sentence, a missing step, or something the author did well.
        9. +
      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. +
      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.
        11. +
      +

      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:

      +
      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. +
      2. OAuth sign-in fails? Verify your GitHub account is active in the browser first, close VS Code, reopen, and retry.
        3. +
      3. PR list is empty? Switch to "All Open" view in the GitHub Pull Requests panel.
        4. +
      4. Checkout fails? Confirm you have write access to the repository. If not, use the read-only GitHub.com fallback.
        5. +
      5. Diff Editor is hard to navigate? Press F7 for the Accessible Diff Viewer mode, which is purpose-built for screen readers.
        6. +
      6. Cannot find the Add Comment command? Use Command Palette and search for GitHub Pull Requests: Add Comment.
        7. +
      7. Ask facilitator to help verify the GitHub PR panel and model one review comment.
        8. +
      8. Finished but not sure you did it right? Compare your work against the Challenge 11 reference solution.
        9. +
      +
      +

      Continue learning: The GitHub Skills course Review Pull Requests practices approving, requesting changes, and using suggestions in an interactive format. See Appendix Z 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. +
      2. Practice on someone else's work first (reviewing is safer than authoring).
        3. +
      3. Use accessibility tools (F7 Accessible Diff Viewer) to navigate efficiently.
        4. +
      4. Write specific, constructive feedback (not just "looks good").
        5. +
      +

      Table of Contents

      +
        +
      1. Installing the GitHub Pull Requests Extension
        2. +
      2. Viewing Pull Requests
        3. +
      3. Checking Out a Pull Request Branch
        4. +
      4. Reviewing Pull Requests in VS Code
        5. +
      5. Creating a Pull Request from VS Code
        6. +
      6. Pull Request Description Templates
        7. +
      7. Commenting and Requesting Changes
        8. +
      8. Merging Pull Requests
        9. +
      +

      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. +
      2. Type "GitHub Pull Requests" in the search box
        3. +
      3. Find "GitHub Pull Requests and Issues" (publisher: GitHub)
        4. +
      4. Navigate to the extension in the results list
        5. +
      5. Press Enter to open the extension detail page
        6. +
      6. Tab to "Install" button → press Enter
        7. +
      +

      Method 2: Command Palette

      +
        +
      1. Ctrl+Shift+P
        2. +
      2. Type "install extensions"
        3. +
      3. Select "Extensions: Install Extensions"
        4. +
      4. Search for "GitHub Pull Requests"
        5. +
      5. Install "GitHub Pull Requests and Issues"
        6. +
      +

      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. +
      2. Navigate to the notification (Alt+N / Mac: Option+N, or status bar navigation)
        3. +
      3. Select "Sign in"
        4. +
      4. VS Code opens your browser for GitHub OAuth authentication
        5. +
      5. Authorize VS Code in the browser
        6. +
      6. Return to VS Code - you're now signed in
        7. +
      +

      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. +
      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. +
      3. Alternatively press Ctrl+Shift+G (Mac: Cmd+Shift+G) to open Source Control, then Tab until you reach the Activity Bar icon strip
        4. +
      +

      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. +
      2. Click the Pull requests tab
        3. +
      3. Click any PR title to view its conversation, commits, and changed files
        4. +
      4. Use the Files changed tab to review diffs
        5. +
      +

      See Working with Pull Requests for the full web-based PR workflow.

      +
      + +
      +GitHub CLI (gh) alternative + +

      View PRs from your terminal:

      +
      # 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. +
      2. Navigate with Arrow keys to find the "GitHub Pull Requests" section
        3. +
      3. Expand it with Right Arrow
        4. +
      +

      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. +
      2. Press Enter
        3. +
      +

      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. +
      2. In the PR detail view, navigate to "Checkout" button
        3. +
      3. Press Enter
        4. +
      +

      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. +
      2. Press Shift+F10 (Mac: Ctrl+Return) to open context menu
        3. +
      3. Select "Checkout Pull Request"
        4. +
      +

      Method 3: Command Palette

      +
        +
      1. Ctrl+Shift+P (Mac: Cmd+Shift+P)
        2. +
      2. Type "GitHub Pull Requests: Checkout"
        3. +
      3. Select "GitHub Pull Requests: Checkout Pull Request"
        4. +
      4. Choose the PR from the list
        5. +
      +

      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. +
      2. Type "git checkout"
        3. +
      3. Select "Git: Checkout to..."
        4. +
      4. Choose your original branch (usually main or your feature branch)
        5. +
      +

      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. +
      2. Each file is a link
        3. +
      3. Navigate with Arrow keys
        4. +
      4. Press Enter on a file to open its diff view
        5. +
      +

      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

      + +
        +
      1. Open a changed file from the PR detail view
        2. +
      2. Press F7 to jump to the first diff hunk
        3. +
      3. Press Alt+F2 (Mac: Option+F2) to open Accessible View
        4. +
      4. Read the hunk content:
          +
        • Unchanged lines (for context)
          • +
        • Removed lines (prefixed with -)
          • +
        • Added lines (prefixed with +)
          • +
        +
        5. +
      5. Press Escape to close Accessible View
        6. +
      6. Press F7 to jump to the next hunk
        7. +
      7. Repeat until all hunks reviewed
        8. +
      +

      Example Accessible Diff output

      +
      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. +
      2. Press Shift+F10 (Mac: Ctrl+Return) for context menu
        3. +
      3. Select "Add Comment"
        4. +
      4. Type your comment in the input that appears
        5. +
      5. Choose "Single Comment" or "Start Review"
        6. +
      +

      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. +
      2. Fill in the title, description, and base branch.
        3. +
      3. Click Create.
        4. +
      +

      github.com (browser):

      +
        +
      1. Push your branch, then click the Compare & pull request banner on the repo page.
        2. +
      2. Fill in the form and click Create pull request.
        3. +
      +

      GitHub Desktop:

      +
        +
      1. After pushing, click Create Pull Request -- this opens gitub.com with the form pre-filled.
        2. +
      +

      Git CLI / GitHub CLI:

      +
      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)
        2. +
      2. You've made commits
        3. +
      3. You've pushed the branch to GitHub (Ctrl+Shift+P / Mac: Cmd+Shift+P → "Git: Push")
        4. +
      +

      Creating the PR

      + +
        +
      1. Ctrl+Shift+P (Mac: Cmd+Shift+P)
        2. +
      2. Type "GitHub Pull Requests: Create"
        3. +
      3. Select "GitHub Pull Requests: Create Pull Request"
        4. +
      4. A form opens in the editor
        5. +
      +

      Method 2: Source Control Panel

      +
        +
      1. Open Source Control: Ctrl+Shift+G (Mac: Cmd+Shift+G)
        2. +
      2. After pushing, a "Create Pull Request" button appears
        3. +
      3. Press Enter on that button
        4. +
      +

      Method 3: GitHub Panel

      +
        +
      1. Open GitHub view (Activity Bar → GitHub icon)
        2. +
      2. Right-click your branch in the tree
        3. +
      3. Select "Create Pull Request"
        4. +
      +

      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")
        • +
      + +
        +
      • 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. +
      2. Tab to "Create" button
        3. +
      3. Press Enter
        4. +
      +

      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. +
      2. If you recently pushed, a yellow banner "Compare & pull request" appears - click it
        3. +
      3. Otherwise: click Pull requests tab, then New pull request, then select your branch
        4. +
      4. Fill in the title and description
        5. +
      5. Click Create pull request
        6. +
      +

      See Working with Pull Requests - Opening a PR for detailed screen reader steps.

      +
      + +
      +GitHub CLI (gh) alternative - creating a PR + +
      # 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 <!-- comment --> 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

      +
      ## Description
+<!-- Briefly describe what this PR changes and why -->
+
+## Related Issue
+<!-- Link to the issue this PR fixes: Fixes #123 -->
+
+## Type of Change
+- [ ] Bug fix
+- [ ] New feature
+- [ ] Documentation update
+- [ ] Accessibility improvement
+
+## Testing
+<!-- How did you test these changes? -->
+
+## 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)
+<!-- Add screenshots or screen recordings -->
      +

      Filling Out a Template

      +

      Screen reader workflow

      +
        +
      1. Create PR (Method 1-3 from Section 5)
        2. +
      2. The description field is pre-filled with the template
        3. +
      3. Navigate through the template with Arrow keys
        4. +
      4. Replace each <!-- comment --> with your content
        5. +
      5. Check checkboxes by typing x between the brackets: - [x]
        6. +
      +

      Keyboard tip: Use Ctrl+F (Mac: Cmd+F) to jump to each <!-- placeholder, fill it in, then F3 to jump to the next one.

      +

      7. Commenting and Requesting Changes

      +

      When reviewing a PR, you can:

      +
        +
      • Leave inline comments on specific lines
        • +
      • Request changes before the PR can be merged
        • +
      • Approve the PR
        • +
      • Submit general feedback
        • +
      +

      Adding an Inline Comment

      +
        +
      1. Open a file from the PR's "Files Changed" list
        2. +
      2. Navigate to the line you want to comment on
        3. +
      3. Press Shift+F10 (Mac: Ctrl+Return) to open context menu
        4. +
      4. Select "Add Comment"
        5. +
      5. Type your comment
        6. +
      6. Choose "Add Single Comment" (posts immediately) or "Start Review" (saves as a draft)
        7. +
      +

      Comment format tips

      +
        +
      • Be specific: "This heading should be H3, not H2"
        • +
      • Provide context: "Screen readers announce this as 'list with 1 item' - should be a paragraph instead"
        • +
      • Suggest a fix: "Consider rewording to: 'Click the button to save'"
        • +
      +

      Starting a Review

      +

      If you have multiple comments to make, use "Start Review"

      +
        +
      1. Add your first inline comment → select "Start Review"
        2. +
      2. Continue adding comments to other lines
        3. +
      3. All comments are saved as drafts (not visible to others yet)
        4. +
      +

      Submitting Your Review

      +

      When you've reviewed all files:

      +
        +
      1. Ctrl+Shift+P (Mac: Cmd+Shift+P)
        2. +
      2. Type "GitHub Pull Requests: Submit Review"
        3. +
      3. Select "GitHub Pull Requests: Finish Review"
        4. +
      4. Choose review type:
          +
        • Comment - general feedback, no approval decision
          • +
        • Approve - PR looks good, ready to merge
          • +
        • Request Changes - issues must be fixed before merging
          • +
        +
        5. +
      5. Optionally add a summary comment
        6. +
      6. Press Enter to submit
        7. +
      +

      Screen reader note: The review type selector is a radio button group. Use Arrow keys to choose, Enter to confirm.

      +

      What Happens After Submission

      +
        +
      • All your draft comments post to GitHub
        • +
      • The PR author receives a notification
        • +
      • Your review status appears on the PR (Approved / Changes Requested / Commented)
        • +
      • If you requested changes, the PR cannot merge until you approve it
        • +
      +
      +Web alternative (github.com) - reviewing + +

      Review PRs directly on GitHub.com:

      +
        +
      1. Open the PR and click the Files changed tab
        2. +
      2. Read through each file's diff
        3. +
      3. Click the blue + button on any line to add an inline comment
        4. +
      4. Choose Start a review to batch comments
        5. +
      5. Click Review changes (top right) to select Comment / Approve / Request changes
        6. +
      6. Click Submit review
        7. +
      +

      See Accessible Code Review for detailed screen reader steps.

      +
      + +
      +GitHub CLI (gh) alternative - reviewing + +
      # View the PR diff in your terminal
+gh pr diff 42
+
+# Approve
+gh pr review 42 --approve --body "Looks good."
+
+# Request changes
+gh pr review 42 --request-changes --body "Heading hierarchy needs fixing."
+
+# Comment-only (no verdict)
+gh pr review 42 --comment --body "A few suggestions."
      +

      Note: For inline comments on specific lines, use the web interface or VS Code.

      +
      + +

      Learning Cards: Commenting and Requesting Changes

      +
      +Screen reader users + +
        +
      • In a diff view, navigate to a line and press Shift+F10 for the context menu, then select "Add Comment" to leave inline feedback
        • +
      • Choose "Start Review" instead of "Single Comment" to batch multiple comments before submitting them all at once
        • +
      • When submitting a review, use Ctrl+Shift+P then "GitHub Pull Requests: Submit Review" and choose Approve, Request Changes, or Comment
        • +
      +
      + +
      +Low vision users + +
        +
      • Inline comments appear as expandable banners within the diff view -- look for the text input box that opens below the target line
        • +
      • The review submission dialog has radio buttons for Approve, Request Changes, and Comment with clear labels
        • +
      • Increase diff view font size with Ctrl+= so line numbers and change annotations are easier to read
        • +
      +
      + +
      +Sighted users + +
        +
      • Hover over the line gutter in a diff view to see a blue + icon -- click it to start an inline comment on that line
        • +
      • A yellow banner appears for pending review comments; green for approved comments
        • +
      • The "Submit Review" button in the PR detail view shows the count of pending comments ready to send
        • +
      +
      + + +

      8. Merging Pull Requests

      +

      Who can merge: Repository maintainers, or contributors with write access.

      +

      Prerequisites for Merging

      +

      Before merging, verify:

      +
        +
      1. All required reviews are approved
        2. +
      2. All CI checks pass (green checkmarks)
        3. +
      3. No merge conflicts exist
        4. +
      4. Branch is up to date with base branch (main)
        5. +
      +

      Changing the base branch: If the PR was opened against the wrong base branch, you can change it from the PR detail view in VS Code. Scroll to the base branch field in the PR detail view and activate the dropdown to select a different target branch. This saves opening the PR on GitHub.com.

      +

      Converting to/from draft: You can also convert a ready PR back to a draft (or mark a draft as ready for review) directly from the PR detail view. Scroll to the Status section and use the context menu on the PR title or the "..." more actions button.

      +

      Merging from VS Code

      +

      Method 1: PR Detail View

      +
        +
      1. Open the PR in VS Code
        2. +
      2. Scroll to the bottom of the PR detail view
        3. +
      3. Find "Merge Pull Request" button
        4. +
      4. Press Enter
        5. +
      5. Choose merge type (see below)
        6. +
      6. Confirm
        7. +
      +

      Method 2: Command Palette

      +
        +
      1. Ctrl+Shift+P (Mac: Cmd+Shift+P)
        2. +
      2. Type "GitHub Pull Requests: Merge"
        3. +
      3. Select "GitHub Pull Requests: Merge Pull Request"
        4. +
      4. Choose the PR from the list
        5. +
      5. Select merge type
        6. +
      6. Confirm
        7. +
      +

      Merge Types

      + + + + + + + + + + + + + + + + + + + + + + + +
      TypeWhat It DoesWhen to Use
      Merge CommitCreates a merge commit preserving all branch commitsDefault for most projects; preserves full history
      Squash and MergeCombines all commits into one before mergingCleans up messy commit history; common for feature branches
      Rebase and MergeReplays commits onto base branch without a merge commitCreates linear history; requires clean commit messages
      +

      Screen reader note: The merge type selector is a dropdown or radio group. Navigate with Arrow keys, confirm with Enter.

      +

      Which merge type to use

      +
        +
      • Check the repository's CONTRIBUTING.md for guidance
        • +
      • If unsure, use Merge Commit (the default and safest option)
        • +
      +

      After Merging

      +
        +
      1. The PR closes automatically
        2. +
      2. The feature branch can be deleted (VS Code prompts: "Delete branch?")
        3. +
      3. Recommended: switch back to main and pull the merged changes
        4. +
      +

      Switching to main and pulling

      +
      Ctrl+Shift+P → "Git: Checkout to..." → select "main"
+Ctrl+Shift+P → "Git: Pull"
      +

      (Mac users: use Cmd+Shift+P instead of Ctrl+Shift+P)

      +

      Deleting the Feature Branch

      +

      After merging, the feature branch is no longer needed:

      +
        +
      1. Ctrl+Shift+P (Mac: Cmd+Shift+P)
        2. +
      2. Type "git delete branch"
        3. +
      3. Select "Git: Delete Branch..."
        4. +
      4. Choose the merged branch
        5. +
      +

      This deletes the branch locally. To delete it on GitHub too:

      +
      +Web alternative (github.com) - merging + +

      Merge a PR directly on GitHub.com:

      +
        +
      1. Open the PR's Conversation tab
        2. +
      2. Scroll to the merge button at the bottom
        3. +
      3. Click the dropdown arrow to choose a merge strategy (Squash, Rebase, or Merge commit)
        4. +
      4. Click Merge pull request, then Confirm merge
        5. +
      5. Click Delete branch to clean up
        6. +
      +
      + +
      +GitHub CLI (gh) alternative - merging + +
      # Merge with default strategy
+gh pr merge 42
+
+# Squash and merge, then delete the branch
+gh pr merge 42 --squash --delete-branch
+
+# Enable auto-merge (merges when checks pass)
+gh pr merge 42 --auto --squash
      +
      + +
        +
      1. Ctrl+Shift+P (Mac: Cmd+Shift+P)
        2. +
      2. Type "git push"
        3. +
      3. Select "Git: Push (delete remote branch)"
        4. +
      +

      Learning Cards: Merging Pull Requests

      +

      Screen reader users:

      +
        +
      • The merge type selector (Merge Commit, Squash, Rebase) is announced as a dropdown or radio group -- use Arrow keys to move between options and Enter to confirm; if unsure, choose Merge Commit (the default and safest option)
        • +
      • After merging, VS Code prompts "Delete branch?" as a notification -- press Alt+N to focus the notification and Enter to confirm, then run Ctrl+Shift+P then "Git: Checkout to" and select main to return to your default branch
        • +
      • Confirm the merge succeeded by pressing F6 to reach the Status Bar and verifying it now reads main instead of the feature branch name
        • +
      +

      Low-vision users:

      +
        +
      • The merge button at the bottom of the PR detail view includes a dropdown arrow for selecting merge type -- at high zoom, widen the editor pane so the button label and dropdown are not truncated
        • +
      • After merging, the PR detail view header changes from "Open" (green badge) to "Merged" (purple badge) -- verify this colour/label change before deleting the branch
        • +
      • When switching back to main, the branch name in the bottom-left Status Bar updates immediately -- confirm it reads main before pulling new changes with Ctrl+Shift+P then "Git: Pull"
        • +
      +

      Sighted users:

      +
        +
      • Click the dropdown arrow next to the green "Merge" button to choose between Merge Commit, Squash and Merge, or Rebase and Merge -- the dropdown shows a brief description of each strategy
        • +
      • After merging, a "Delete branch" prompt appears as a blue link in the PR detail view; click it to clean up locally, then check the PR on GitHub.com where a similar button deletes the remote branch
        • +
      • Pull merged changes immediately: click the sync icon in the Status Bar (circular arrows) or run Ctrl+Shift+P then "Git: Pull" to bring your local main up to date
        • +
      +

      Keyboard Shortcuts - GitHub Pull Requests Extension

      + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + +
      ActionWindowsMac
      Open GitHub viewActivity Bar → GitHub icon → EnterActivity Bar → GitHub icon → Enter
      Create Pull RequestCtrl+Shift+P → "GitHub Pull Requests: Create"Cmd+Shift+P → "GitHub Pull Requests: Create"
      Checkout PRCtrl+Shift+P → "GitHub Pull Requests: Checkout"Cmd+Shift+P → "GitHub Pull Requests: Checkout"
      Submit ReviewCtrl+Shift+P → "GitHub Pull Requests: Finish Review"Cmd+Shift+P → "GitHub Pull Requests: Finish Review"
      Merge PRCtrl+Shift+P → "GitHub Pull Requests: Merge"Cmd+Shift+P → "GitHub Pull Requests: Merge"
      Add inline commentShift+F10 (in diff view) → "Add Comment"Ctrl+Return (in diff view) → "Add Comment"
      Navigate diff hunksF7 (next), Shift+F7 (previous)F7 (next), Shift+F7 (previous)
      Accessible Diff ViewerAlt+F2 (in diff view)Option+F2 (in diff view)
      +

      Troubleshooting

      +

      "No pull requests found"

      +

      Issue: The GitHub Pull Requests panel is empty.

      +

      Solutions

      +
        +
      1. Verify you're signed in: Ctrl+Shift+P (Mac: Cmd+Shift+P) → "GitHub Pull Requests: Sign in"
        2. +
      2. Check you have a folder open containing a Git repository
        3. +
      3. Refresh the panel: Ctrl+Shift+P (Mac: Cmd+Shift+P) → "GitHub Pull Requests: Refresh Pull Requests List"
        4. +
      +

      "Could not create pull request"

      +

      Issue: PR creation fails.

      +

      Solutions

      +
        +
      1. Verify you've pushed your branch: Ctrl+Shift+P (Mac: Cmd+Shift+P) → "Git: Push"
        2. +
      2. Check you have write access to the repository
        3. +
      3. Ensure your branch is ahead of the base branch (has new commits)
        4. +
      +

      "Authentication failed"

      +

      Issue: VS Code can't connect to GitHub.

      +

      Solutions

      +
        +
      1. Sign out and sign back in: Ctrl+Shift+P (Mac: Cmd+Shift+P) → "GitHub Pull Requests: Sign out" → then sign in again
        2. +
      2. Check your GitHub Personal Access Token (see Appendix D: Git Authentication)
        3. +
      3. Verify network connection
        4. +
      +

      Try It: Review a PR from VS Code

      +

      Time: 3 minutes | What you need: VS Code with GitHub Pull Requests extension installed and signed in

      +
        +
      1. Open the PR view - Press Ctrl+Shift+P → type Pull Requests: Focus on GitHub Pull Requests View → Enter.
        2. +
      2. Find a PR - Navigate the tree with arrow keys. Expand a PR to see its changed files.
        3. +
      3. Open a diff - Press Enter on a changed file. The diff editor opens.
        4. +
      4. Use the Accessible Diff Viewer - Press F7 to jump to the first change. Your screen reader announces what was added or removed. Press F7 again to move to the next change.
        5. +
      5. Leave a comment - Position your cursor on a line you want to comment on, then press Ctrl+Shift+P → Pull Request: Add Comment on Current Diff Line. Type a brief, constructive comment and submit.
        6. +
      +

      You're done. You just reviewed a pull request entirely from VS Code.

      +
      +

      What success feels like: You read a diff, heard the changes announced by your screen reader, and left feedback - all without opening a browser. This is how many developers review code every day.

      +
      +

      Next: GitHub Copilot
      Back: Git & Source Control in VS Code
      Related: Working with Pull Requests | Issue Templates

      +
      +

      Part 2: Accessible Code Review

      +
      +

      Listen to Episode 15: Accessible Code Review - a conversational audio overview of this chapter. Listen before reading to preview the concepts, or after to reinforce what you learned.

      +
      +

      Conducting Pull Request Reviews with a Screen Reader

      +
      +

      This guide is focused entirely on the reviewer experience - navigating diffs, reading changes, leaving comments, and submitting a review - using only your keyboard and screen reader. For the full pull request lifecycle (opening PRs, merge options, conflict resolution), see Working with Pull Requests.

      +

      Learning Room connection: The exercises in this chapter use files from the Learning Room repository. You will review PRs that modify docs/keyboard-shortcuts.md (shortcut tables with intentional errors), docs/setup-guide.md (broken links and incomplete steps), and docs/welcome.md ([TODO] sections to complete). These are the same files you work on during the Day 1 contribution sprint.

      +
      +

      Workshop Recommendation (Chapter 15 / Challenge 12)

      +

      Chapter 15 is the code review chapter focused on practicing constructive feedback. It supports Challenge 12: Review Like a Pro.

      +
        +
      • Challenge count: 2 guided challenges
        • +
      • Automation check: none (review quality is subjective and human-focused)
        • +
      • Evidence: issue comment with summary of review and feedback posted
        • +
      • Pattern: navigate diff, comment on specifics, submit verdict
        • +
      +

      Challenge 12 Practice Set

      +
        +
      1. Review a practice PR and leave 2-3 inline comments - read the diff line by line, find specific items to comment on, and post constructive feedback.
        2. +
      2. Submit a formal review verdict - complete your review by choosing approve, request changes, or comment only.
        3. +
      +

      Practice 12.1 Step-by-Step: Review a PR and Leave Inline Comments

      +

      Goal: Navigate a PR diff using screen reader-friendly tools and post 2-3 specific, constructive inline comments.

      +

      Where you are working: GitHub.com (Files changed tab of a PR) or VS Code with the GitHub Pull Requests extension.

      +

      Estimated time: 15-20 minutes.

      +
        +
      1. Open your Learning Room repository on GitHub.com and navigate to the Pull requests tab.
        2. +
      2. Find a classmate's open PR (from Chapter 6, 7, or 14). Open it.
        3. +
      3. Activate the Files changed tab. This shows the diff - lines added in green, lines removed in red.
        4. +
      4. Navigate the diff:
          +
        • On GitHub.com: Use heading navigation to jump between files (H in NVDA). Each file header is a heading. Within a file, use arrow keys to move line by line.
          • +
        • In VS Code: Press F7 to open the Accessible Diff Viewer (see Chapter 15, Part 1). Use F7/Shift+F7 to move between changes.
          • +
        +
        5. +
      5. Read through the changes carefully. Look for:
          +
        • Typos or grammar issues
          • +
        • Unclear headings or link text
          • +
        • Missing steps in instructions
          • +
        • Accessibility concerns (missing alt text, unclear structure)
          • +
        • Things the author did well (note these too)
          • +
        +
        6. +
      6. To leave an inline comment on GitHub.com: activate the + button that appears to the left of a line number when you hover or Tab to it. (Screen reader users: this button may be announced as "Add a comment to this line.") Type your comment in the text box that opens.
        7. +
      7. Post 2-3 inline comments. Each comment should be:
          +
        • Specific: reference the exact line or phrase
          • +
        • Constructive: suggest an improvement or explain why something works well
          • +
        • Kind: frame suggestions as questions or "consider" statements
          • +
        +
        8. +
      8. Examples of good inline comments:
          +
        • "Line 12: 'Click here' should be more descriptive. Consider: 'Open the notification settings page'"
          • +
        • "Nice clear heading structure - the reader can scan this section quickly."
          • +
        • "Step 3 says 'do the thing' - could you add which menu or keyboard shortcut to use?"
          • +
        +
        9. +
      +

      Screen reader tip: On GitHub.com, the Files Changed tab uses a table-like layout. Each row is a line of the diff. The + button for commenting may not be visible until you Tab through the row controls. If you cannot find it, use the "Review changes" button at the top to add a general comment instead.

      +

      You are done when: You have posted 2-3 inline comments on a classmate's PR.

      +

      Practice 12.2 Step-by-Step: Submit a Formal Review Verdict

      +

      Goal: Complete your review by selecting a verdict that tells the author what action to take next.

      +

      Where you are working: GitHub.com (the same PR you reviewed in 14.1).

      +
        +
      1. After posting your inline comments, scroll to the top of the Files changed tab.
        2. +
      2. Activate the Review changes button (at the top-right of the files changed area, or use heading navigation).
        3. +
      3. A dropdown opens with three options:
          +
        • Comment - general feedback, no explicit approval or rejection
          • +
        • Approve - you think the PR is ready to merge
          • +
        • Request changes - you found something that should be fixed before merging
          • +
        +
        4. +
      4. Choose the verdict that matches your review:
          +
        • If the PR has clear documentation with only minor suggestions, choose Approve.
          • +
        • If you found issues that would confuse readers, choose Request changes and explain what needs fixing in the summary.
          • +
        • If you are unsure, choose Comment - this is always a safe option.
          • +
        +
        5. +
      5. Write a brief summary in the review body (1-2 sentences). Example: "Clear improvement to the shortcut table. Two minor suggestions for link text clarity."
        6. +
      6. Activate Submit review.
        7. +
      +

      You are done when: Your review verdict appears on the PR's conversation tab as a green (approved), red (changes requested), or gray (comment) review badge.

      +

      Completing Challenge 12: Submit Your Evidence

      +

      Open your assigned Challenge 12 issue and post a completion comment:

      +
      Challenge 12 completed:
+- PR reviewed: #[PR number]
+- Inline comments posted: [number, e.g., 3]
+- Review verdict: [Approve / Request Changes / Comment]
+- One thing I learned from reviewing: [one sentence]
      +

      Close your Challenge 12 issue when done.

      +

      Expected Outcomes

      +
        +
      • Student can navigate PR diffs with a screen reader.
        • +
      • Student can post inline comments on specific lines of a diff.
        • +
      • Student can write constructive, specific feedback that helps the author improve.
        • +
      • Student can submit a formal review verdict.
        • +
      +

      If You Get Stuck

      +
        +
      1. Files Changed tab will not open? Reload the PR page and retry. Make sure you are on the PR page, not the issue page.
        2. +
      2. Cannot find the inline comment button? Tab through the line controls in the diff. The button may be announced as "Add a comment" or have a + label. If you cannot find it, use the "Review changes" button at the top to add a general comment instead.
        3. +
      3. Not sure what to comment on? Focus on clarity: is every heading descriptive? Is every link meaningful? Are steps complete? Are keyboard shortcuts correct?
        4. +
      4. Review verdict button not working? Make sure you have at least one comment or have written summary text. Try reloading the page.
        5. +
      5. Submitting the review fails? Check that you are not in draft mode and have at least read access to the repo.
        6. +
      6. Ask facilitator to model one inline comment and one verdict submission.
        7. +
      7. Finished but not sure you did it right? Compare your work against the Challenge 12 reference solution.
        8. +
      +
      +

      Continue learning: The GitHub Skills courses Review Pull Requests and Code Review with GitHub Copilot cover review workflows and AI-assisted code review. See Appendix Z for the full catalog.

      +
      +

      Learning Moment

      +

      Constructive review is a gift. Specific, kind feedback helps authors improve and builds trust in the community. Every comment you write is practice for the professional code review you will do on real projects.

      +

      Learning Pattern Used in This Chapter

      +
        +
      1. Read the full diff before commenting (understand the author's intent first).
        2. +
      2. Find specific items to comment on (lines, phrases, missing steps).
        3. +
      3. Write comments that help, not just criticize (suggest improvements, note what works).
        4. +
      4. Choose a verdict that matches the substance of your feedback.
        5. +
      5. Summarize your overall impression in 1-2 sentences.
        6. +
      +

      Prerequisites Checklist

      +

      Before starting this chapter, verify you have completed

      +
        +
      • Chapter 6: Working with Pull Requests - Understand PR structure, diffs, and comment workflows
        • +
      • Chapter 13: GitHub Copilot - VS Code installed and configured
        • +
      • Screen Reader Setup - NVDA, JAWS, or VoiceOver installed and ready to use
        • +
      • Access to at least one pull request to review (your own fork or a practice repo)
        • +
      +

      Estimated time for this chapter: 1 hour (including exercises)

      +

      Two Environments for Code Review

      +

      You can review pull requests in two places - each with different strengths:

      + + + + + + + + + + + + + + + + + + +
      EnvironmentBest ForKey Accessibility Feature
      GitHub web (browser)Quick reviews, inline comments on any machineNew Files Changed Experience + keyboard navigation
      VS CodeDeep reviews, large diffs, local contextAccessible Diff Viewer (F7)
      +

      Both environments give you full keyboard and screen reader access. Your choice depends on context, not accessibility.

      +

      About Learning Cards in This Chapter

      +

      Each review step includes expandable learning cards for different interaction styles. Open the one that matches how you work:

      +

      The following table describes each learning card type and who it is for.

      + + + + + + + + + + + + + + + + + + + + + + + + + + + +
      CardWho it is for
      Visual / mouse usersSighted users navigating with a mouse or trackpad
      Low vision usersUsers working with zoom (200%+), magnification, high contrast themes, or large cursors
      Screen reader users (NVDA / JAWS)Windows users navigating with NVDA or JAWS
      Screen reader users (VoiceOver)macOS users navigating with VoiceOver
      CLI (gh)Terminal review commands - predictable text output
      +
      +GitHub CLI (gh) alternative - review from your terminal + +

      The GitHub CLI offers a third path for reviewing PRs - especially useful for reading diffs and submitting verdicts:

      +
      # View the full PR diff in your terminal
+gh pr diff 42
+
+# View PR details (description, status, checks)
+gh pr view 42
+
+# Checkout the PR branch locally for testing
+gh pr checkout 42
+
+# Approve the PR
+gh pr review 42 --approve --body "Heading hierarchy looks correct. LGTM."
+
+# Request changes
+gh pr review 42 --request-changes --body "The alt text on line 34 needs to describe the image."
+
+# Leave a comment-only review
+gh pr review 42 --comment --body "A few observations - see details below."
      +

      Best for: Quickly reading diffs, approving/rejecting PRs, and checking out branches for local testing. For inline comments on specific lines, use the web interface or VS Code.

      +
      + + +

      Part 1 - Reviewing on GitHub.com

      +

      Good News: Modern Interface is Default

      +

      As of January 2026, GitHub's improved Files Changed experience is enabled by default. The instructions below assume you have the modern interface (which you do).

      +

      If the interface seems different from what's described here, clear your browser cache and reload the page.

      +

      Step 1: Reach the Files Changed Tab

      +

      From any pull request page:

      +
      +Visual / mouse users + +

      Click the Files changed tab at the top of the PR page. The tab label shows the number of changed files (e.g., "Files changed 4").

      +
      + +
      +Low vision users (zoom, high contrast) + +
        +
      1. The PR tabs (Conversation, Commits, Checks, Files changed) are across the top of the PR page. At high zoom they may wrap to multiple lines.
        2. +
      2. The Files changed tab includes a badge with the number of changed files. This badge uses text (not colour alone) so it is visible in all themes.
        3. +
      3. After clicking Files changed, the diff page loads. At high zoom, the file tree panel on the left may collapse automatically. Click the file tree toggle (a small panel icon) or press T to toggle it back.
        4. +
      4. Added lines use a green background; removed lines use red. In high contrast browser settings (Windows: Settings > Accessibility > Contrast themes), these colours map to strong border indicators.
        5. +
      5. Use Ctrl++ to zoom the browser if the diff text is too small, and Ctrl+- to zoom out.
        6. +
      +
      + +
      +Screen reader users (NVDA / JAWS) + +
      Press D → navigate to "Pull request navigation tabs" landmark
+Press → or Tab → find "Files changed" link → Enter
      +

      The tab label announces the number of changed files: "Files changed, 4 files changed"

      +
      + +
      +Screen reader users (VoiceOver - macOS) + +
      VO+U → Landmarks → navigate to "Pull request navigation tabs"
+VO+Right or Quick Nav K → find "Files changed" link → VO+Space
      +

      VoiceOver announces the number of changed files: "Files changed, 4 files changed"

      +
      + + +

      Step 2: Use the File Tree to Orient Yourself

      +

      The file tree panel lists every changed file. Before reading any diff, scan this list to understand the scope of the PR.

      +
      +Visual / mouse users + +

      The file tree is the left panel on the Files Changed page. Each file shows its name and a +N / -N badge (lines added/removed). Click any filename to scroll directly to its diff.

      +
      + +
      +Screen reader users (NVDA / JAWS) + +
      Press D → navigate to "File tree" region
+Press ↓ to move through files
+Each file reads: "[filename] - [N additions, N deletions]"
+Press Enter on a file to scroll its diff into view
      +
      + +
      +Screen reader users (VoiceOver - macOS) + +
      VO+U → Landmarks → navigate to "File tree" region
+VO+Down to move through files
+Each file reads: "[filename] - [N additions, N deletions]"
+VO+Space on a file to scroll its diff into view
      +
      + +

      What to listen for / look for

      +
        +
      • How many files changed?
        • +
      • Which areas of the codebase are affected?
        • +
      • Are there unexpected files (generated files, lock files, configuration changes)?
        • +
      +
      +Low vision users (zoom, high contrast) + +
        +
      1. The file tree shows each filename with a colour-coded bar indicating lines added (green) and removed (red). In high contrast mode, these bars may be less visible - the +N / -N text badge next to each file is the reliable indicator.
        2. +
      2. At high zoom, long file paths truncate. Hover over a truncated name to see the full path in a tooltip.
        3. +
      3. If the file tree panel is too narrow at high zoom, drag its right edge to widen it, or toggle it off and use heading navigation (H key) to move between file diffs.
        4. +
      +
      + + +

      Step 3: Navigate Between File Diffs

      +

      Each changed file in the main area is an h3 heading containing the filename.

      +
      +Visual / mouse users + +

      Scroll through the page or click a filename in the file tree on the left. Collapsed files can be expanded by clicking the file header.

      +
      + +
      +Screen reader users (NVDA / JAWS) + +
      Press 3 to jump file-by-file through the diff
+Listen for: "learning-room/docs/keyboard-shortcuts.md - collapsed" or "expanded"
+Press Enter or Space to expand a collapsed file
      +

      If a diff is very long, the file tree is usually faster than pressing 3 repeatedly.

      +
      + +
      +Screen reader users (VoiceOver - macOS) + +
      Quick Nav H or VO+Cmd+H to jump file-by-file through the diff
+Listen for: "learning-room/docs/keyboard-shortcuts.md - collapsed" or "expanded"
+VO+Space to expand a collapsed file
      +

      If a diff is very long, the file tree is usually faster than using heading navigation.

      +
      + + +

      Step 4: Read a Diff

      +

      Each file's diff is a table. Every row is one line of code.

      +
      +Visual / mouse users + +
        +
      • Green highlighted lines (with a +) = lines added
        • +
      • Red highlighted lines (with a -) = lines removed
        • +
      • Plain/white lines = unchanged context
        • +
      • Use Ctrl+F to search within the page for specific text in the diff
        • +
      +
      + +
      +Low vision users (zoom, high contrast) + +
        +
      1. Colour is not the only indicator. Every added line has a + character in the gutter; every removed line has a -. These text characters are reliable regardless of colour settings.
        2. +
      2. At high zoom, long lines of code wrap. The +/- gutter character stays at the beginning of the first line, so look left to determine the change type.
        3. +
      3. Use Ctrl+F (browser find) to search for specific text across the entire diff page.
        4. +
      4. If the diff is split view (side by side), it may be very wide at high zoom. Switch to unified diff mode: click the gear icon in the Files Changed toolbar and select "Unified" - this shows old and new in a single column.
        5. +
      5. High contrast themes in Windows (Settings > Accessibility > Contrast themes) make the +/- lines use bold border patterns instead of subtle colour shading.
        6. +
      +
      + +
      +Screen reader users - NVDA + +
      Press T to jump to the diff table then Insert+Space (Focus Mode)
+Press Down Arrow to move through lines one at a time
+Press Ctrl+Alt+Right Arrow to read across columns: line number, change type, code content
      +
      + +
      +Screen reader users - JAWS + +
      Press T to jump to the diff table then Insert+Z (Virtual PC Cursor off)
+Press Down Arrow to move through lines
+Press Ctrl+Alt+Right Arrow for column-by-column reading
      +
      + +
      +Screen reader users - VoiceOver (macOS) + +
      Press T or VO+U then Tables then select the diff table
+VO+Shift+Down Arrow to enter the table
+VO+Right/Left to navigate columns, VO+Up/Down to navigate rows
      +
      + +

      What each line announces / shows

      +
        +
      • Added lines: "+ [code content]" - or announced as "inserted"
        • +
      • Removed lines: "- [code content]" - or announced as "deleted"
        • +
      • Context lines: code without a + or -
        • +
      +

      Tip: If the code on a line is very long, the screen reader will read the full line. For minified or generated files, consider collapsing the file in the tree and skipping it.

      +

      Step 5: Place an Inline Comment

      +

      When you have a specific observation about a particular line, place an inline comment directly on it.

      +
      +Visual / mouse users + +
        +
      1. Hover your mouse over a line in the diff - a blue + (comment) button appears on the left
        2. +
      2. Click it to open the inline comment box
        3. +
      3. Type your comment
        4. +
      4. Click "Start a review" (not "Add single comment" - see note below)
        5. +
      +
      + +
      +Screen reader users (NVDA / JAWS) + +
      Step 1: Navigate to the target line in the diff table (see Step 4)
+Step 2: While focused on that line, press Tab → look for a comment button
+Step 3: Alternatively: press B to navigate buttons → look for "Add a comment to this line"
+Step 4: Press Enter to open the inline comment box
+Step 5: Insert+Space (NVDA) or Insert+Z (JAWS) → switch to Focus Mode
+Step 6: Type your comment
+Step 7: Tab to "Start a review" button (not "Add single comment" - see note below)
+Step 8: Press Enter
      +
      + +
      +Screen reader users (VoiceOver - macOS) + +
      Step 1: Navigate to the target line in the diff table (see Step 4)
+Step 2: While focused on that line, Tab → look for a comment button
+Step 3: Alternatively: Quick Nav B → look for "Add a comment to this line"
+Step 4: VO+Space to open the inline comment box
+Step 5: VO+Shift+Down to interact with the text area
+Step 6: Type your comment
+Step 7: VO+Shift+Up to stop interacting → Tab to "Start a review" button
+Step 8: VO+Space
      +
      + +
      +

      Why "Start a review" instead of "Add single comment": A single comment posts immediately and sends a notification for each one. "Start a review" batches all your comments and sends one notification when you submit - far less disruptive for the author.

      +
      +

      Placing a multi-line comment

      +
      +Visual / mouse users + +

      Click and drag across multiple line numbers in the diff gutter to select a range. A comment button appears for the selected range.

      +
      + +
      +Screen reader users (NVDA / JAWS) + +
      Step 1: Navigate to the first line of the range
+Step 2: Press Shift+↓ to extend selection to additional lines
+Step 3: A comment button appears for the selected range
+Step 4: Proceed as above
      +
      + +
      +Screen reader users (VoiceOver - macOS) + +
      Step 1: Navigate to the first line of the range
+Step 2: Shift+↓ to extend selection to additional lines
+Step 3: A comment button appears for the selected range
+Step 4: VO+Space to activate, then proceed as above
      +
      + + +

      Step 6: Read Existing Comments and Threads

      +

      Inline comments from other reviewers appear as h3 headings within the diff table. Each thread shows: reviewer username, comment body, replies, a "Reply" link and resolution button.

      +
      +Visual / mouse users + +

      Comments appear inline within the diff as collapsible cards. Click "Reply…" to add to a thread. Click "Resolve conversation" to mark a thread done (requires write access).

      +
      + +
      +Screen reader users (NVDA / JAWS) + +

      Navigate them with 3 (jump to h3 headings in the diff).

      +

      To add to a thread:

      +
      Step 1: Navigate to the thread heading (3)
+Step 2: Tab to "Reply…" link
+Step 3: Enter → text area appears → Focus Mode → type reply
+Step 4: Ctrl+Enter to submit the reply
      +

      To mark a thread as resolved (if you have write access):

      +
      Tab to the "Resolve conversation" button → Enter
      +
      + +
      +Screen reader users (VoiceOver - macOS) + +

      Navigate with Quick Nav H or VO+Cmd+H (jump to headings in the diff).

      +

      To add to a thread:

      +
      Step 1: Quick Nav H to navigate to the thread heading
+Step 2: Tab to "Reply…" link
+Step 3: VO+Space → text area appears → VO+Shift+Down → type reply
+Step 4: Cmd+Return to submit the reply
      +

      To mark a thread as resolved (if you have write access):

      +
      Tab to the "Resolve conversation" button → VO+Space
      +
      + + +

      Step 7: Submit Your Review

      +

      After adding all inline comments:

      +
      +Visual / mouse users + +
        +
      1. Click the "Review changes" button (top-right of the Files Changed page or bottom of the PR)
        2. +
      2. A dialog opens with a summary text area and three radio buttons: Comment / Approve / Request changes
        3. +
      3. Optionally type an overall summary in the text area
        4. +
      4. Select your verdict
        5. +
      5. Click "Submit review"
        6. +
      +
      + +
      +Screen reader users (NVDA / JAWS) + +
      Step 1: Press D → navigate to "Pull request navigation tabs"
+Step 2: Press ← to return to the Conversation tab → Enter
+Step 3: Scroll to the bottom (End key, or ↓ repeatedly)
+Step 4: Alternatively: press B repeatedly → find "Review changes" button
+Step 5: Press Enter to open the review summary dialog
+Step 6: Focus Mode → type your overall comment
+Step 7: Tab to the radio button group → ↑/↓ to select a verdict
+Step 8: Tab to "Submit review" button → Enter
      +
      + +
      +Screen reader users (VoiceOver - macOS) + +
      Step 1: VO+U → Landmarks → navigate to "Pull request navigation tabs"
+Step 2: VO+Left to return to the Conversation tab → VO+Space
+Step 3: VO+End or VO+Down to reach the bottom of the page
+Step 4: Alternatively: Quick Nav B → find "Review changes" button
+Step 5: VO+Space to open the review summary dialog
+Step 6: VO+Shift+Down → type your overall comment
+Step 7: VO+Shift+Up → Tab to the radio button group → VO+Left/Right to select a verdict
+Step 8: Tab to "Submit review" button → VO+Space
      +
      + +

      Verdicts and their meaning

      + + + + + + + + + + + + + + + + + + + +
      VerdictWhen to use
      CommentYou have observations but no strong position; does not block merge
      ApproveYou've reviewed and are satisfied; signals readiness to merge
      Request changesChanges are needed before this should merge; blocks merge
      +

      Step 8: Re-request Review (for Authors)

      +

      After you address review comments on your own PR:

      +
      +Visual / mouse users + +

      Look in the right sidebar for the Reviewers section. Click the re-request icon (circular arrows) next to the reviewer's name to notify them that you've pushed changes.

      +
      + +
      +Screen reader users (NVDA / JAWS) + +
      Step 1: From your PR's Conversation tab, find the reviewer's name in the sidebar (3 → "Reviewers" heading)
+Step 2: Activate the refresh/re-request icon next to their name
+Step 3: This re-notifies the reviewer that you've made changes
      +
      + +
      +Screen reader users (VoiceOver - macOS) + +
      Step 1: From your PR's Conversation tab, Quick Nav H or VO+Cmd+H to find the "Reviewers" heading in the sidebar
+Step 2: Tab or Quick Nav B to find the re-request icon ("Re-request review") next to the reviewer's name
+Step 3: VO+Space to activate - this re-notifies the reviewer that you've made changes
      +
      + +

      Learning Cards: Reviewing on GitHub.com

      +

      Screen reader users:

      +
        +
      • In the Files Changed tab, press T to jump to the diff table, then use Focus Mode (Insert+Space in NVDA, Insert+Z in JAWS) and Down Arrow to read line by line -- each added line starts with + and each removed line with -
        • +
      • To place an inline comment, navigate to the target line and press Tab or B to find the "Add a comment to this line" button; after typing your comment, choose "Start a review" (not "Add single comment") to batch all feedback into one notification
        • +
      • Submit your full review by pressing B repeatedly to find the "Review changes" button; the dialog contains a radio group (Comment / Approve / Request changes) navigable with Arrow keys, then Tab to "Submit review"
        • +
      +

      Low-vision users:

      +
        +
      • Switch from split diff to unified diff (gear icon in the Files Changed toolbar then select "Unified") to show old and new code in a single column -- much easier to follow at high zoom than two side-by-side panes
        • +
      • The blue + comment button appears in the line gutter on hover; at high zoom it may be small -- use Ctrl++ to increase browser zoom and look just left of the line number column
        • +
      • The "Review changes" dialog uses clearly labeled radio buttons for the three verdict types; each label includes a brief description, and the currently selected option has a filled circle indicator visible in all themes
        • +
      +

      Sighted users:

      +
        +
      • Use the file tree on the left side of the Files Changed page to jump between files; each file shows a coloured bar indicating the ratio of additions (green) to deletions (red) so you can prioritize large changes
        • +
      • Hover on any line in the diff gutter to reveal the blue + icon for inline comments; click and drag across multiple line numbers to comment on a range of lines at once
        • +
      • After adding all inline comments, click the green "Review changes" button at the top right, write a summary sentence, select your verdict, and click "Submit review" to post everything in one batch
        • +
      +

      Part 2 - Reviewing in VS Code with the Accessible Diff Viewer

      +

      When you check out a branch locally, VS Code's diff editor offers the Accessible Diff Viewer - a purpose-built, line-by-line reading mode designed specifically for screen readers.

      +

      Opening a Diff in VS Code

      +

      If you have the GitHub Pull Requests extension:

      +
        +
      1. Open the GitHub Pull Requests view (Explorer sidebar or Ctrl+Shift+P → "GitHub Pull Requests: View Pull Request")
        2. +
      2. Find the PR and open it - changed files appear in the file tree
        3. +
      3. Navigate to any file in the tree and press Enter to open its diff view
        4. +
      +

      Without the extension, any git diff operation also opens the diff editor.

      +

      Learning Cards: VS Code Code Review

      +
      +Low vision users (zoom, high contrast) + +

      VS Code's diff editor works well at high zoom:

      +
        +
      1. Split view vs. inline: By default, VS Code shows diffs in a split (side-by-side) view. At high zoom this can be very cramped. Switch to inline mode: Ctrl+Shift+P then type "Toggle Inline View" in any diff editor. Inline mode shows old and new code in a single column.
        2. +
      2. Colour indicators: Added lines have a green gutter bar; removed lines have a red gutter bar. In high contrast themes, these use heavy solid borders that are visible even at extreme zoom levels.
        3. +
      3. Change navigation: Press F7 to jump to the next change and Shift+F7 for the previous. Each change is highlighted with a visible focus box that moves with your position - much easier than scrolling at high zoom.
        4. +
      4. Minimap in diff view: The minimap (right edge) shows an overview of changes as coloured blocks. At high zoom the minimap may be too small to be useful - disable it via Settings if it adds visual noise.
        5. +
      5. Font size for diffs: Diff editors use your configured editor font size (editor.fontSize). Increase this in Settings (Ctrl+,) if the diff text is too small at your zoom level.
        6. +
      6. Comment highlight: When you add a comment through the GitHub PR extension, the commented line gets a distinct background. In high contrast themes this is a solid colour band.
        7. +
      +
      + +
      +Screen reader users (NVDA / JAWS on Windows) + +

      Opening the PR for review

      +
        +
      1. Press Ctrl+Shift+P, type "GitHub Pull Requests: View Pull Request"
        2. +
      2. The PR tree appears in the sidebar - navigate with Down Arrow
        3. +
      3. Each changed file is announced with its name and change summary
        4. +
      4. Press Enter on a file to open its diff editor
        5. +
      5. The diff editor opens with the standard VS Code diff layout
        6. +
      +

      Using the Accessible Diff Viewer

      +
        +
      1. In the diff editor, press F7 to open the Accessible Diff Viewer
        2. +
      2. NVDA announces: "Changed lines X to Y in filename, Change 1 of N"
        3. +
      3. The viewer shows each change with "Removed:" and "Added:" labels
        4. +
      4. Press F7 to move to the next change, Shift+F7 for previous
        5. +
      5. Press Escape when done to close the viewer
        6. +
      +

      Placing a comment

      +
        +
      1. Navigate to the line you want to comment on in the diff
        2. +
      2. Press Ctrl+Shift+P, type "GitHub Pull Requests: Add Comment"
        3. +
      3. A text area opens below the line - NVDA announces the input focus
        4. +
      4. Type your comment
        5. +
      5. Press Tab to the Submit button, then Enter
        6. +
      +
      + +
      +Screen reader users (VoiceOver on macOS) + +

      Opening the PR

      +
        +
      1. Press Cmd+Shift+P, type "GitHub Pull Requests: View Pull Request"
        2. +
      2. Navigate the PR tree with VO+Down Arrow
        3. +
      3. Press Return on a file to open its diff
        4. +
      +

      Accessible Diff Viewer

      +
        +
      1. Press F7 in the diff editor
        2. +
      2. VoiceOver announces each change with clear "Removed" and "Added" labels
        3. +
      3. Navigate with F7/Shift+F7
        4. +
      4. Press Escape to close
        5. +
      +

      Comment placement

      +
        +
      1. Press Cmd+Shift+P, type "GitHub Pull Requests: Add Comment"
        2. +
      2. VO+Shift+Down Arrow to interact with the comment text area
        3. +
      3. Type your comment
        4. +
      4. VO+Shift+Up Arrow to stop interacting, then Tab to Submit
        5. +
      +
      + +

      Using the Accessible Diff Viewer (F7)

      +

      From any open diff editor:

      +
      Press F7 → Accessible Diff Viewer opens as a panel below the diff
      +

      The Accessible Diff Viewer reads each change as a structured block:

      +
      "Changed lines 14 to 14 in docs/keyboard-shortcuts.md
+[Change 1 of 3]
+
+Removed:
+    #### NVDA Single-Key Navigation
+
+Added:
+    ### NVDA Single-Key Navigation"
      +

      This example is from a real Learning Room scenario: a contributor fixing the heading hierarchy in docs/keyboard-shortcuts.md by changing a level-4 heading to level-3, which is exactly what you look for when reviewing Challenge 2 PRs.

      + +
        +
      • F7 - jump to next change (next hunk)
        • +
      • Shift+F7 - jump to previous change
        • +
      • Alt+F2 - open VS Code's Accessible View for additional context on the current item
        • +
      • Escape - close the Accessible Diff Viewer
        • +
      +

      What makes this better than the raw diff editor

      +
        +
      • Each change is announced as a discrete unit with clear "Removed:" and "Added:" labels
        • +
      • You hear the change number of total changes ("Change 3 of 12")
        • +
      • No table navigation required - purpose-built for sequential listening
        • +
      • Works with all three major screen readers without any special configuration
        • +
      +

      Placing Comments in VS Code (GitHub PR Extension)

      +

      From the diff editor with the GitHub PR extension:

      +
      Step 1: In the diff gutter, navigate to the line you want to comment on
+Step 2: Ctrl+Shift+P → "GitHub Pull Requests: Add Comment"
+Step 3: Or press Shift+F10 (Windows) or Control+Return (macOS) on the line → context menu → "GitHub Pull Requests: Add Comment"
+Step 4: A text area opens - type your comment
+Step 5: Submit from the inline UI
      +

      Comments placed in VS Code sync to GitHub - they appear in the PR's Files Changed tab and the author receives the same notification.

      +

      Code Review Structure and Content

      +

      The Anatomy of a Useful Review Comment

      +

      A comment that helps the author is:

      +
        +
      1. Specific - link to the exact line and name the pattern you see
        2. +
      2. Educational - say why something matters, not just what to change
        3. +
      3. Graduated - signal whether this is blocking, or a preference
        4. +
      +

      Blocking example (reviewing a PR for docs/keyboard-shortcuts.md)

      +
      +

      "The heading on line 34 uses #### (level 4) directly after ## (level 2), skipping heading level 3. Screen reader users who navigate by heading level will miss any content between those two levels. Please change #### to ### before this merges."

      +
      +

      Non-blocking (nit) example (reviewing a PR for docs/welcome.md)

      +
      +

      "nit: The link text in the 'Getting Help' section reads 'click here for more information.' Screen reader users who navigate links out of context will hear only 'click here' with no destination. Consider 'See the accessibility setup guide' instead. Not blocking."

      +
      +

      Question example (reviewing a PR for docs/setup-guide.md)

      +
      +

      "The PR description says this fixes broken links in the setup guide, but the link on line 12 still points to /docs/old-setup. Am I reading the diff correctly, or was this link intentionally left? Happy to re-review once I understand."

      +
      +

      Prefixes That Set Expectations

      +

      Using shorthand prefixes helps authors parse many comments quickly:

      + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + +
      PrefixMeaning
      nit:Non-blocking stylistic preference
      question:Genuine question; not blocking
      suggestion:Alternative to consider; take it or leave it
      important:Should be addressed; may block
      blocking:Must be addressed before merge
      praise:Positive callout - works well, good pattern
      +

      How Many Comments Is Too Many?

      +

      There is no hard limit, but quantity without prioritization is noise. If you have 15 comments, make clear which 2-3 are blocking. Authors can then focus energy on what matters most and address preferences in follow-up PRs.

      +

      Keyboard Reference

      +

      GitHub Web Review

      + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + +
      ActionKey
      Navigate to Files Changed tabD → PR tabs landmark → → → Enter
      Jump between file diffs3
      Navigate diff lines (NVDA/JAWS)Focus Mode + ↓
      Read across diff columnsCtrl+Alt+→
      Open inline comment boxLine focused → B → comment button
      Submit entire reviewD → Conversation → B → "Review changes"
      Navigate existing threads3
      Reply to a thread3 → thread → Tab → "Reply" → Enter
      +

      VS Code Accessible Diff Viewer

      + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + +
      ActionKey
      Open Accessible Diff ViewerF7
      Next change (hunk)F7
      Previous change (hunk)Shift+F7
      Open Accessible ViewAlt+F2
      Accessible Help (any widget)Alt+H
      Close Accessible Diff ViewerEscape
      +

      Common Review Scenarios

      +

      "I want to verify the PR only changes what it claims"

      +

      Example: A PR says "Challenge 2: Add NVDA shortcut" but the file tree shows changes to both docs/keyboard-shortcuts.md and docs/welcome.md.

      +
      1. File tree → count the files, read the names
+2. 3 → navigate each file heading → listen to the stats line (N additions, N deletions)
+3. For keyboard-shortcuts.md: T → Focus Mode → ↓ through lines → verify the new shortcut row
+4. For welcome.md: check if the change is related → if unrelated, leave a comment on the first line
      +

      "I want to find all changes to one specific section"

      +

      Example: A PR for Challenge 3 modified docs/welcome.md. You want to verify the [TODO] in the "Who Can Contribute?" section was filled in correctly.

      +
      1. In VS Code: open docs/welcome.md → Ctrl+G → jump to the "Who Can Contribute?" section
+2. F7 → Accessible Diff Viewer → listen for changes near that heading
+3. Or on GitHub: file tree → expand welcome.md → T → navigate the diff table to the [TODO] line
      +

      "I agreed but then the author made more changes - did anything new appear?"

      +
      1. Go to the Commits tab (D → PR tabs → "Commits" → Enter)
+2. 3 to navigate commits - find any commits after your last review
+3. Press `Enter` on the commit to see only what changed in that push (not the full diff)
      +

      "A reviewer left a comment I don't understand"

      +
      1. Read the full thread (3 → navigate to the thread heading)
+2. Tab to the "Reply" button
+3. Ask: "Can you clarify what change you're suggesting? I want to understand before I act on this."
+4. Or: reference a specific line in your reply using the line number
      +

      Exercises

      +

      These exercises use the files in learning-room/docs/ in this repository. All examples involve documentation changes - no code required.

      +

      Exercise A - Complete a Web Review

      +

      Scenario: A contributor has submitted a pull request titled "Add screen reader tips to the setup guide." The PR modifies learning-room/docs/setup-guide.md. Your job is to review it before it merges.

      +

      What You'll Learn: How to use screen reader heading navigation to spot accessibility issues in a GitHub PR diff.

      +

      Step 1: Navigate to the Pull Request

      +
      What to do
      +
        +
      1. Open GitHub in your browser and navigate to the workshop repository (github.com/[your-fork]/[workshop-repo] or community-access/accessibility-agents)
        2. +
      2. Click the Pull Requests tab (top navigation)
        3. +
      3. Look for a PR titled "Add screen reader tips to the setup guide" - click it to open
        4. +
      4. You should now see the PR page with sections: Conversation, Commits, Files Changed
        5. +
      +
      How to know you're in the right place
      +
        +
      • The PR title is visible at the top
        • +
      • You see a description box with text about what this PR does
        • +
      • You see tabs labeled "Conversation," "Commits," "Files Changed"
        • +
      +
      If you can't find the PR
      +
        +
      • Use Ctrl+F to search the PR list for "screen reader tips"
        • +
      • Or ask in the workshop Slack - someone can share the exact URL
        • +
      +

      Step 2: Read the PR Description

      +
      What to do
      +
        +
      1. You are currently on the Conversation tab
        2. +
      2. Read the PR description (the text immediately under the PR title)
        3. +
      3. Look for: "What does this PR change?" and "Why does it change it?"
        4. +
      4. With screen reader: Navigate to the description with D (NVDA) or press Ctrl+Option+Up (VoiceOver) to find main landmarks, then read the content region
        5. +
      +
      What to look for
      +
        +
      • Does the PR author explain what file changed? (should mention setup-guide.md)
        • +
      • Does it explain why? (should mention "improve accessibility" or "add tips")
        • +
      • Is it clear enough that a reviewer can understand the goal without reading the diff?
        • +
      +
      What success looks like
      +
        +
      • You can answer: "This PR adds [specific content] to [specific file] because [clear reason]"
        • +
      • Example: "This PR adds screen reader usage tips to the setup guide because new users need accessibility guidance"
        • +
      +

      Step 3: Navigate to "Files Changed"

      +
      What to do
      +
        +
      1. Click the Files Changed tab (top of the PR page, to the right of "Commits")
        2. +
      2. You are now viewing the diff
        3. +
      3. With keyboard (all screen readers): Press T to jump to the diff table. The page focuses on the file comparison area.
        4. +
      +
      What you should see
      +
        +
      • A section showing the file name setup-guide.md with a small badge showing "+20 −0" (20 lines added, 0 lines removed)
        • +
      • Below it, the diff with removed lines (preceded by −) and added lines (preceded by +)
        • +
      +
      If you see multiple files
      +
        +
      • Scroll up to see if there are other files. For this exercise, only setup-guide.md should be changed.
        • +
      • If you see other files, confirm they are not modified (the badge should show "+0 −0" or no changes)
        • +
      +

      Step 4: Activate Focus Mode for Better Diff Reading

      +
      What to do
      +
        +
      1. Look for a button labeled "Focus Mode" or an icon (usually at the top right of the diff area)
        2. +
      2. With keyboard: Press F to toggle Focus Mode (may need to be in the diff area first)
        3. +
      3. With mouse: Click the Focus Mode button/icon
        4. +
      +
      What happens in Focus Mode
      +
        +
      • The page simplifies: sidebars disappear
        • +
      • Only the diff is visible - easier for screen reader navigation and less cognitive load
        • +
      • The diff is now the main content area
        • +
      +
      With screen reader (once in Focus Mode)
      +
        +
      • NVDA/JAWS: Press T to jump to the diff table
        • +
      • VoiceOver: Navigate with VO+Right Arrow to find the table/content region
        • +
      • Read through the changes: ↓ arrow moves to each line
        • +
      +

      Step 5: Find the Heading Hierarchy Issue

      +
      What to do
      +
        +
      1. Read through the entire diff line by line. Pay special attention to lines starting with #
        2. +
      2. You are looking for: a line with #### (four hashes, heading level 4) that comes directly after a ## (two hashes, heading level 2)
        3. +
      3. When you find it, note the exact line number shown in the diff
        4. +
      +
      Example of what you're looking for
      +
        ## Setup Basics          ← Heading level 2
+  ...several lines...
+  #### Advanced Tips       ← Heading level 4 (skipped level 3!)
      +
      Why this matters
      +
        +
      • Screen reader users navigate documents by heading level: 1 → 2 → 3 → 4
        • +
      • A skip from ## to #### breaks that navigation
        • +
      • When a user presses "jump to heading level 3," they'll find none, wondering if content is missing
        • +
      +
      What success looks like
      +
        +
      • You found the line with #### that violates hierarchy
        • +
      • You can say the line number and what heading text appears there
        • +
      • You understand why this is an accessibility problem
        • +
      +

      Step 6: Place a Blocking Review Comment on the Heading

      +
      What to do
      +
        +
      1. Find the diff line with the problematic #### heading
        2. +
      2. Hover your mouse over the line number on the left side of that line (or if using keyboard, navigate to that line in the table)
        3. +
      3. A button should appear (or press the Add Comment hotkey - usually C in GitHub)
        4. +
      4. Click it or press Enter to open a comment box
        5. +
      +
      In the comment box
      +
        +
      1. Type: blocking: (tells reviewers this stops the PR from merging)
        2. +

      2. Press Space, then explain:

        +
        Heading hierarchy violation. This heading uses #### (level 4) directly
+after ## (level 2), skipping level 3. Screen reader users navigating
+by heading level will miss this section. Change to ### (level 3).
        +
        3. +
      3. Click the Comment button (or press Ctrl+Enter for keyboard submit)
        4. +
      +
      What happens next
      +
        +
      • Your comment appears in the thread under that line
        • +
      • The PR author sees it and can make the fix
        • +
      +
      If the comment button doesn't appear
      +
        +
      • Make sure you're hovering over the line number area (left side of the line)
        • +
      • Try refreshing the page and trying again
        • +
      • Or use the "Add a reply" field at the bottom of the PR and mention the line number manually
        • +
      +

      Step 7: Find the Link Text Issue

      +
      What to do
      +
        +
      1. Continue reading the diff (from where you left off)
        2. +
      2. Look for a line containing link text that reads "click here" or "click here for more information"
        3. +
      3. Note the line number
        4. +
      +
      Why this matters
      +
        +
      • Screen reader users can ask their reader to "list all links on this page" - they hear only the link text
        • +
      • If the text is "click here," they have no context about where it goes
        • +
      • Descriptive link text is WCAG 2.4.4 (Link Purpose)
        • +
      +
      What success looks like
      +
        +
      • You found a link with non-descriptive text
        • +
      • You can explain why "click here" is bad and what would be better
        • +
      + +
      What to do
      +
        +
      1. Find the line in the diff with the problematic link
        2. +
      2. Hover over the line number and click to open a comment box (or press C)
        3. +

      3. Type:

        +
        nit: Link text "click here" is not descriptive. Screen reader users
+who list links won't know the context. Suggest: "Read the accessibility
+checklist" or another descriptive phrase.
        +
        4. +
      4. Click Comment or press Ctrl+Enter
        5. +
      +

      Note: nit: means "nice-to-have improvement" (not blocking, but good to fix)

      +

      Step 9: Submit Your Review

      +
      What to do
      +
        +
      1. Look for a button labeled "Review changes" (usually at the top right of the page or bottom of comments)
        2. +
      2. Click it (or navigate with keyboard and press Enter)
        3. +
      3. A dialog appears with options:
          +
        • Comment - provide feedback but don't block (for minor notes)
          • +
        • Approve - the PR is ready to merge
          • +
        • Request changes - this PR cannot merge until changes are made
          • +
        +
        4. +
      +
      For this exercise
      +
        +
      1. Select "Request changes" (you found two things to fix)
        2. +
      2. In the summary field, write: Found 2 accessibility issues that must be fixed before merging.
        3. +
      3. Click "Submit review"
        4. +
      +
      What happens
      +
        +
      • Your review is submitted
        • +
      • The PR author gets a notification
        • +
      • The PR shows your review with the two comments
        • +
      • GitHub blocks merging until the author responds to or fixes the changes
        • +
      +
      What success looks like
      +
        +
      • You see your review appear on the PR page
        • +
      • It shows 2 comments you made
        • +
      • The PR status shows "Changes requested"
        • +
      +

      Reflect on This Exercise

      +

      After submitting, answer:

      +
        +
      1. Did heading-level navigation help? When you were looking for the #### issue, was it easier to navigate by heading level (1-6) than to scan every line?
        2. +
      2. Would you have caught this without the exercise prompt? If you were a real reviewer not specifically looking for heading issues, would the diff have been obvious?
        3. +
      3. Why does screen reader navigation matter? In one sentence, explain why a screen reader user's ability to jump through heading levels is important for this document.
        4. +
      +

      Keep your answers - you'll need them for Chapter 16's Accessibility Agents exercise to compare manual review with agent-assisted review.

      +

      Exercise B - Use the VS Code Accessible Diff Viewer

      +

      Scenario: Review the same pull request from Exercise A, this time entirely in VS Code. You'll compare the browser experience with the VS Code experience.

      +

      What You'll Learn: How the VS Code Accessible Diff Viewer announces changes differently than the browser diff, and when each environment is most useful.

      +

      Prerequisites

      +

      Before starting:

      +
        +
      • VS Code must be installed on your machine
        • +
      • The GitHub Pull Requests extension must be installed (see Chapter 12 for installation)
        • +
      • You must be signed into GitHub from VS Code (use Ctrl+Shift+P → "GitHub: Sign in")
        • +
      +

      Step 1: Open the GitHub Pull Requests Extension

      +
      What to do
      +
        +
      1. Open VS Code
        2. +
      2. With keyboard (all screen readers): Press Ctrl+Shift+X to open the Extensions sidebar
          +
        • With mouse: Click the Extensions icon on the left sidebar (looks like four squares)
          • +
        +
        3. +
      3. Search for "GitHub Pull Requests"
        4. +
      4. If it's not installed, click Install
        5. +
      5. If it is installed, click GitHub Pull Requests to view its details
        6. +
      +
      What you should see
      +
        +
      • The extension is listed as active
        • +
      • It mentions: "Review and manage GitHub pull requests and issues"
        • +
      +

      Step 2: Open the Pull Requests Sidebar

      +
      What to do
      +
        +
      1. Look for a GitHub-themed icon on the left sidebar (circle with octocat logo) - click it
          +
        • With keyboard: The icon may not be keyboard-reachable directly; instead go to Step 3
          • +
        +
        2. +
      2. A sidebar appears showing open pull requests on repositories you have access to
        3. +
      3. Find the PR titled "Add screen reader tips to the setup guide" - it should appear in a list
        4. +
      4. Click it to open
        5. +
      +
      What happens
      +
        +
      • VS Code opens a new editor tab for this PR
        • +
      • Below the PR title, you see a "Changes" section listing modified files
        • +
      • You should see setup-guide.md in the changes list
        • +
      +
      If you can't find the PR
      +
        +
      • Use Ctrl+Shift+P → search GitHub Pull Requests: Open Pull Request
        • +
      • Paste the PR URL: https://github.com/[owner]/[repo]/pull/[number]
        • +
      • Press Enter
        • +
      +

      Step 3: View the File Changes

      +
      What to do
      +
        +
      1. In the Changes section, locate setup-guide.md
        2. +
      2. Click on the filename to open it
        3. +
      +
      What happens
      +
        +
      • A diff editor opens showing two columns:
          +
        • Left: the original file (before changes)
          • +
        • Right: the new file (after changes)
          • +
        +
        • +
      • Different colors show added (green), removed (red), and modified (blue) lines
        • +
      • The file name appears at the top: setup-guide.md
        • +
      +
      With screen reader
      +
        +
      • NVDA/JAWS: The editor announces "Diff Editor - setup-guide.md"
        • +
      • Use Ctrl+Home to jump to the start of the diff
        • +
      • Use Ctrl+End to jump to the end
        • +
      +

      Step 4: Access the Accessible Diff Viewer

      +
      What to do
      +
        +
      1. With keyboard: Press F7 to open the Accessible Diff Viewer
          +
        • With mouse: Look for a button or menu option labeled "Accessible View" or "Open Accessible Diff"
          • +
        • If no button is visible, try Alt+F2 (VS Code Accessible View toggle)
          • +
        +
        2. +
      +
      What happens
      +
        +
      • A new panel opens at the bottom of VS Code
        • +
      • The panel announces each change one at a time
        • +
      • Changes appear in text format with labels: "Added: " and "Removed: "
        • +
      • The panel is read-only (you read the changes, you don't edit here)
        • +
      +
      If the Accessible Diff Viewer doesn't open
      +
        +
      • Make sure the diff editor is active (click in the diff area first)
        • +
      • Try Ctrl+Shift+P → search Open Accessible Diff
        • +
      • If available, select it
        • +
      +

      Step 5: Listen to and Understand the First Change

      +
      What to do
      +
        +
      1. The first change is automatically announced when you open the Accessible Diff Viewer
        2. +
      2. Let your screen reader read it completely - don't interrupt
        3. +

      3. Write down the exact text announced:

        +
        Removed: [write what the viewer said]
+Added: [write what the viewer said]
        +
        4. +
      4. Press the Down arrow to move to the next change
        5. +
      +
      What to expect (example)
      +
      Removed: ## Old Heading
+Added: ## New Heading with More Details
      +
      With screen reader
      +
        +
      • NVDA/JAWS: The Accessible Diff Viewer announces "Removed:" and "Added:" labels, followed by the line content
        • +
      • VoiceOver: The announcement may be similar; listen for "removed" and "added" keywords
        • +
      +

      Step 6: Find the Heading Hierarchy Issue

      +
      What to do
      +
        +
      1. Continue pressing Down arrow to move through changes
        2. +
      2. Listen carefully for a change involving headings (lines starting with #)
        3. +
      3. Specifically, listen for: "Added: ####" (four hashes)
        4. +

      4. When you hear this, stop and write it down:

        +
        Line number: [if available]
+Removed: [what was removed, if anything]
+Added: [the four-hash heading]
+Context: [is there a ## heading just before this?]
        +
        5. +
      +
      Why listen for this?
      +
        +
      • Four hashes (####) indicate a level 4 heading
        • +
      • In the diff, you're looking for it appearing after a level 2 heading (##)
        • +
      • This creates the hierarchy skip you caught in Exercise A
        • +
      +
      What success looks like
      +
        +
      • You found the explanation in the Accessible Diff Viewer's format
        • +
      • You can explain: "The added line with #### directly follows a ##, skipping level 3"
        • +
      • The Accessible Diff Viewer made this pattern clearer than scanning raw + characters
        • +
      +

      Step 7: Locate the Heading Line and Add an Inline Comment

      +
      What to do
      +
        +
      1. Once you identified the problematic heading in the Accessible Diff Viewer, close the Accessible Diff Viewer (press F7 again or Alt+F2)
        2. +
      2. You're back in the regular Diff Editor
        3. +
      3. Find the line with the problematic #### heading:
          +
        • Use Ctrl+F to open Find
          • +
        • Search for #### to locate it quickly
          • +
        • Press Enter to jump to it
          • +
        +
        4. +
      4. Close Find (Escape)
        5. +
      5. Place your cursor on that line
        6. +
      6. Right-click and select "Add Comment" or press the Comment icon that appears on the left margin
          +
        • With keyboard: The comment button may appear on the current line; navigate to it and press Enter
          • +
        +
        7. +
      +
      What happens
      +
        +
      • A comment box opens
        • +
      • You can type your comment
        • +
      +

      Step 8: Write Your Accessible Diff Comment

      +
      What to do
      +
        +

      1. In the comment box, type:

        +
        blocking: Heading hierarchy violation. The Accessible Diff Viewer
+clearly showed this #### heading appearing directly after ##, skipping
+level 3. Screen reader users navigating by heading level will miss this
+content. Change to ###.
        +
        2. +
      2. Press Ctrl+Enter or click Comment to submit
        3. +
      +
      Why mention the Accessible Diff Viewer?
      +
        +
      • It shows that the tool itself helps you see the issue
        • +
      • It documents how you caught the problem (useful for learning)
        • +
      +

      Step 9: Create a GitHub Pull Request Comment

      +
      Special Section: Comparing Tools
      +

      Now you've reviewed the same PR in:

      +
        +
      1. Browser (Exercise A): You spot-checked line numbers manually
        2. +
      2. VS Code (Exercise B): The Diff Editor plus Accessible Diff Viewer announced changes
        3. +
      +
      What to do
      +
        +
      1. Go to GitHub in your browser and open the same PR
        2. +
      2. Scroll to the bottom and leave a comment in the Conversation tab:
        3. +
      +
      I've now reviewed this PR in both the browser and VS Code. Here's
+what I found:
+
+**Browser review:** I had to manually navigate with heading commands
+and scan for the skip visually. Found 2 issues.
+
+**VS Code + Accessible Diff Viewer:** The Accessible Diff Viewer
+announced changes in a linear format, making it easier to follow
+the story of what changed without scanning back and forth.
+
+**My conclusion:** [Choose one]
+- The browser method was clearer for me
+- VS Code was clearer for me
+- Both have strengths; I'd use each for different purposes
+  - Browser best for: [specific reason]
+  - VS Code best for: [specific reason]
      +
        +
      1. Click Comment
        2. +
      +

      Reflect on This Exercise

      +

      After completing Steps 1-9, answer:

      +
        +
      1. Announcement clarity: Did the "Added:" and "Removed:" labels from the Accessible Diff Viewer help you follow changes faster than reading + and − prefixes in the browser?
        2. +
      2. Navigation pattern: Which tool required less back-and-forth clicking/tabbing to understand each change?
        3. +
      3. When would you use each? In one sentence: describe a type of PR where you'd prefer to use each tool.
        4. +
      +

      Record your answers. In Chapter 16, you'll compare these manual reviews with the @pr-review agent's suggested changes.

      +

      Exercise C - Compare and Reflect

      +

      Your Mission: Synthesize what you learned from the manual code reviews (Exercises A & B) and document your findings.

      +

      What You'll Learn: Which tools work best for different scenarios, and how your manual review skills prepare you to use AI agents effectively.

      +

      Step 1: Gather Your Data

      +

      Before writing your reflection, collect all the information you gathered:

      +
      From Exercise A (Browser Review)
      +
        +
      • Which line number had the heading hierarchy skip?
        • +
      • Which line number had the link text issue?
        • +
      • How many steps did it take to find each issue?
        • +
      • Did you use screen reader commands or visual scanning more?
        • +
      +
      From Exercise B (VS Code Review)
      +
        +
      • What did the Accessible Diff Viewer announce for the heading change?
        • +
      • Was the announcement clearer than the browser's + and − format?
        • +
      • Did you need to switch between the Accessible Diff Viewer and the regular editor?
        • +
      • How many steps to find the problem?
        • +
      +

      Write these down (in a text editor, on paper, or mentally) - you'll reference them in Steps 2-4.

      +

      Step 2: Navigate to the PR and Leave Your Reflection Comment

      +
      What to do
      +
        +
      1. Go to GitHub in your browser
        2. +
      2. Open the same PR ("Add screen reader tips to the setup guide")
        3. +
      3. Scroll to the Conversation tab
        4. +
      4. Scroll all the way down to the comment box at the bottom (labeled "Leave a comment" or "Add a comment")
        5. +
      5. Click in the comment box
        6. +
      +
      What you should see
      +
        +
      • A text editing area with formatting options (Bold, Italic, Link, etc.)
        • +
      • A Comment button below the text area
        • +
      +

      Step 3: Write Your Comparison

      +
      What to do
      +

      Type your response to these three questions. Be specific - reference exact tools, steps, and what you discovered:

      +
      Question 1: Environment Preference
      +
      After reviewing this PR in both environments, my preferred tool was:
+[Browser / VS Code / Both equally]
+
+Why: [1-2 sentences explaining your choice]
+
+Example: "I preferred VS Code because the Accessible Diff Viewer
+separated changes into 'Added:' and 'Removed:', making it obvious
+what the new content was. In the browser, I had to mentally filter
+the + and − characters."
      +
      Question 2: Strengths of Each Environment
      +
      Browser made this easier: [One specific task, e.g., "Finding the PR URL"]
+because [Why]
+
+VS Code made this easier: [One specific task, e.g., "Following the diff linearly"]
+because [Why]
+
+Example Browser: "Finding context about *why* the change was made,
+because all the discussion is in one place"
+
+Example VS Code: "The Accessible Diff Viewer announcing changes sequentially
+meant I didn't miss anything by accidentally scrolling past it"
      +
      Question 3: Real-World Impact
      +
      For someone reading the published document (not the diff), the heading
+skip matters because: [1-2 sentences]
+
+Example: "A screen reader user pressing the '3' key to navigate to level-3
+headings will find none, and might think the document skipped a section.
+This breaks the information hierarchy."
      +
      Full template to copy into the comment box
      +
      ## Code Review Reflection - Browser vs VS Code
+
+After reviewing this PR using both the browser and VS Code environments,
+here's what I found:
+
+### Environment Preference
+
+My preferred tool was: **[Browser / VS Code]**
+
+Why: [1-2 sentences]
+
+### Specific Strengths
+
+#### Browser made this easier
+- Task: [specific thing]
+- Why: [explanation]
+
+#### VS Code made this easier
+- Task: [specific thing]
+- Why: [explanation]
+
+### Real-World Impact
+
+The heading hierarchy skip in the published document matters because:
+[1-2 sentences about why screen reader users would be affected]
      +

      Step 4: Review Your Comment

      +
      What to do
      +
        +
      1. Before submitting, re-read your comment using your screen reader or by reading aloud
        2. +
      2. Ask yourself:
          +
        • Is it clear which tool I preferred?
          • +
        • Did I explain why with concrete examples?
          • +
        • Am I describing the real-world impact accurately?
          • +
        • Would someone else reading this understand how I caught the issue?
          • +
        +
        3. +
      3. Make any corrections needed
        4. +
      4. Do not submit yet - continue to Step 5
        5. +
      +

      Step 5: Submit Your Reflection

      +
      What to do
      +
        +
      1. Locate the Comment button at the bottom right of the comment box
        2. +
      2. With keyboard: Press Tab until the Comment button is focused, then Enter
        3. +
      3. With mouse: Click the Comment button
        4. +
      4. Your comment is submitted and appears on the PR page
        5. +
      +
      What happens
      +
        +
      • Your comment is now visible on the PR
        • +
      • Other reviewers can see your comparison
        • +
      • You have completed the three-part exercise series
        • +
      +
      What success looks like
      +
        +
      • Your comment appears on the PR thread
        • +
      • It includes all three reflections
        • +
      • The PR author and other reviewers can see your thought process
        • +
      +

      Step 6: Checkpoint - Validate Your Learning

      +

      Before moving forward, verify you understand:

      +
        +

      1. Heading Hierarchy: Can you explain in one sentence why a ## → #### skip breaks screen reader navigation?

        +
          +
        • Expected answer: Something like "Screen readers let users navigate by heading level (pressing 3 jumps to H3), so skipping a level makes users think content is missing."
          • +
        +
        2. +

      2. Tool Strengths: For each tool you used, name one task it made easier.

        +
          +
        • Expected answer: e.g., "Browser: finding context in discussions. VS Code: linear reading of changes."
          • +
        +
        3. +

      3. Real-World Testing: How would you test the heading issue in the published document (not the PR diff)?

        +
          +
        • Expected answer: Something like "Open the document in a browser, use screen reader heading navigation, and confirm I can reach all levels (H2, H3, H4)."
          • +
        +
        4. +
      +

      If you can answer all three, you're ready for the next chapter.

      +

      Part 3 - Using GitHub Copilot to Understand Code Changes

      +

      Reviewing code is about understanding what changed, why it changed, and whether the change is safe and correct. GitHub Copilot can help you gather and understand information about code changes - especially when diffs are large, complex, or involve unfamiliar frameworks.

      +

      When to Use Copilot During Code Review

      +

      Copilot is most useful for answering these questions:

      +
        +
      1. "What does this code do?" - you're reading unfamiliar syntax or a framework you don't know well
        2. +
      2. "Why might this change break something?" - you need to understand dependencies or side effects
        3. +
      3. "Is this pattern safe?" - you want to verify that the approach follows best practices
        4. +
      4. "What would be a better way to write this?" - you're looking for alternatives to suggest
        5. +
      5. "Does this match the PR's description?" - the change seems to do more (or less) than claimed
        6. +
      +

      How to Use Copilot During Review

      +

      In VS Code with an Open Diff

      +
        +
      1. Open the PR using the GitHub Pull Requests extension (see Part 2)
        2. +
      2. Open the diff for any file
        3. +
      3. Select a block of code that confuses you (highlight it)
        4. +
      4. Open Copilot Chat: Ctrl+Shift+I
        5. +
      5. Type: Explain what this code does or Why might this change affect [other file]?
        6. +
      6. Copilot reads the selected code and answers in the chat
        7. +
      +

      Example Exchange

      +
      You (selected code):
+  -  const oldParser = require('./old-parser.js');
+  +  const newParser = require('fast-parser');
+
+You ask Copilot:
+  "Why would switching from require('./old-parser.js') to require('fast-parser') be risky?"
+
+Copilot might respond:
+  "The modules have different APIs. If the code calls oldParser.parseXML()
+  and newParser doesn't have that method, the diff would break existing code.
+  Check if the call sites were also updated in this PR."
+
+You then:
+  - Search the diff for calls to parseXML() to verify they were updated
+  - Or leave a comment: "Did we confirm all oldParser.parseXML() calls were
+    updated to use the new parser's API?"
      +

      On GitHub.com (Web Interface)

      +
        +
      1. Open the PR's Files Changed tab
        2. +
      2. Focus on a line or section you want to understand better
        3. +
      3. In VS Code Copilot Chat (not in the browser - Copilot Chat doesn't work directly in browser diffs yet)
        4. +
      4. Copy the confusing code, paste it into chat, and ask Copilot to explain
        5. +
      +

      Another option: Use the GitHub Copilot inline suggestions on GitHub.com:

      +
        +
      • Some GitHub PRs show Copilot insights directly in the diff (as of early 2026)
        • +
      • If you see a lightbulb icon, click it to see Copilot's suggestion about that line
        • +
      +

      Copilot Limitations During Review (Critical to Know)

      +

      Copilot cannot:

      +
        +
      • See the whole project - it sees only what you show it (the selected diff, not the context of the entire codebase)
        • +
      • Verify correctness - it can explain what code does, but not whether it's correct for your specific use case
        • +
      • Understand intent - it reads the code, not the author's mind or the PR description
        • +
      • Catch all risks - it can spot common patterns, but not edge cases unique to your project
        • +
      +

      This is why manual review is essential: You have context (project history, team decisions, user impact) that Copilot does not. Use Copilot to understand, then use your judgment to decide.

      +

      Best Practices

      +
        +
      1. Read the diff manually first - you spot the big picture before asking Copilot details
        2. +
      2. Ask Copilot specific questions - not "review this code" but "does this regex handle Unicode?"
        3. +
      3. Fact-check Copilot's answers - it can be confidently wrong, especially about frameworks or domains it has less training data for
        4. +
      4. Combine Copilot with manual analysis - ask Copilot to explain, then verify by checking the PR description or looking for related files
        5. +
      5. Use Copilot to draft comments - type Draft a comment about [issue] for this PR and edit Copilot's suggestion to match your tone
        6. +
      +

      What Comes Next

      +

      Your manual code review skills - identifying heading issues, catching link text problems, understanding screen reader navigation, gathering information with Copilot - are the foundation for understanding automated review.

      +

      In Chapter 16 (Accessibility Agents), you'll meet a full team of agents designed to amplify these skills:

      +

      Part 4: The Reviewer's Craft

      +

      Parts 1 through 3 taught you the mechanics -- how to read diffs, leave comments, and use Copilot to understand unfamiliar code. This part covers something equally important: how to think like a reviewer. Good reviews are not about finding faults. They are about helping the author ship better work while learning something yourself.

      +

      What to Look for in a Review

      +

      Every PR is different, but most reviews benefit from scanning across these five categories:

      + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + +
      CategoryWhat you're checkingExample question
      ClarityReadable code, clear naming, consistent style"Would another contributor understand this variable name six months from now?"
      AccuracyThe code does what the PR description says it does"The description says this fixes the heading hierarchy -- does it actually change the heading level?"
      ScopeThe change stays within the PR's stated goal"This PR says it updates alt text, but it also refactors the navigation bar -- should that be a separate PR?"
      RegressionsThe change does not break existing behavior"This function used to return a list. Now it returns a single item. Will callers still work?"
      AccessibilityScreen reader support, keyboard navigation, WCAG basics"Does this new button have an accessible label? Can a keyboard-only user reach it?"
      +

      You do not need to check every category exhaustively on every PR. Skim the list, focus on whatever stands out, and flag anything you are unsure about as a question rather than a demand.

      +
      +

      Screen reader tip: When reading a diff in VS Code, you can jump between changed hunks with Alt+F5 (next change) and Shift+Alt+F5 (previous change). This helps you scan for scope creep -- changes that appear in files you did not expect.

      +
      +

      The Three Review Actions

      +

      When you submit a review on GitHub, you choose one of three actions. Picking the right one matters because it signals your intent to the author and to anyone else watching the PR.

      +

      Approve -- Use this when everything looks good, or when only trivial nits remain (typos, minor style preferences). An approval tells the author: "I've read this and I'm satisfied it can merge."

      +

      Request Changes -- Use this when something must be fixed before merge. Bugs, security issues, broken tests, accessibility regressions, or changes that do not match the PR's description all qualify. A request-changes review blocks the PR (in many team configurations) until you re-review.

      +

      Comment -- Use this when you have questions, suggestions, or discussion points that do not block the merge. Comments are for learning, brainstorming, and optional improvements. If you are not sure whether something is a blocker, use Comment and explain your uncertainty in the text.

      +

      Decision tree:

      +
        +
      1. Did you find a bug, security issue, or broken test? -- Request Changes
        2. +
      2. Does the code do something different from what the description says? -- Request Changes
        3. +
      3. Does everything work, with maybe a few style nits? -- Approve (mention the nits in a comment)
        4. +
      4. Do you have questions or optional suggestions? -- Comment
        5. +
      +

      Writing Constructive Feedback

      +

      The way you phrase feedback determines whether the author feels supported or attacked. A few principles go a long way:

      +

      Lead with what works. Before pointing out problems, acknowledge something the author did well. "The new heading structure looks great -- much easier to follow" takes five seconds to write and sets a collaborative tone.

      +

      Be specific about what to change. "This doesn't look right" is frustrating. "Line 42 uses an h4 immediately after an h2, which skips a heading level -- screen readers announce this as a navigation error" gives the author everything they need to fix it.

      +

      Explain why, not just what. "Change this to h3" is an instruction. "Change this to h3 because screen readers use heading levels to build a page outline, and skipping from h2 to h4 creates a gap in that outline" teaches the author something they will remember next time.

      +

      Offer alternatives, not just criticism. Instead of "this naming is confusing," try "consider renaming processData to parseUserInput -- it would make the function's purpose clearer at the call site."

      +

      Use soft language for suggestions, direct language for requirements. "Consider using a <button> here instead of a <div> -- it gives you keyboard support for free" is a suggestion. "This onclick handler on a <div> must be changed to a <button> or given role='button' and a keydown handler -- without that, keyboard users cannot activate it" is a requirement. Match your tone to the severity.

      +

      The Reviewer's Checklist

      +

      Run through this list mentally (or copy it into your notes) for every PR you review:

      +
        +
      • I read the PR description before reading the code
        • +
      • The code does what the description says it does
        • +
      • The change does not include unrelated modifications
        • +
      • Variable and function names are clear
        • +
      • I checked for accessibility: labels, headings, keyboard reach, contrast
        • +
      • I verified no existing behavior is broken by the change
        • +
      • I left at least one positive comment
        • +
      • I chose the right review action (Approve, Request Changes, or Comment)
        • +
      • My feedback explains why, not just what
        • +
      +

      Reviewing as a Learning Tool

      +

      Reviewing is not just a gate to keep bad code out. It is one of the fastest ways to grow as a developer.

      +

      Reading other people's code teaches you patterns. Every PR you review exposes you to a different way of solving a problem. Over time, you build a mental library of approaches -- some you will adopt, some you will avoid, all of which make you a stronger contributor. See Chapter 8 for more on learning through open source participation.

      +

      Giving feedback forces you to articulate your understanding. When you write "this heading skip will confuse screen reader users," you are not just helping the author -- you are reinforcing your own knowledge. If you struggle to explain why something is wrong, that struggle is a signal that you have more to learn about the topic. Follow that signal.

      +

      Reviewing builds trust. When you leave thoughtful, respectful reviews, authors start seeking your input. That trust turns into collaboration, mentorship, and eventually the kind of team culture where everyone improves together. See Chapter 6 for how PRs fit into collaborative workflows.

      +
      +

      Screen reader tip: After submitting a review, GitHub returns you to the PR's Conversation tab. Press h in GitHub's keyboard shortcuts to jump by heading and confirm your review appears in the timeline.

      +
      +

      Learning Cards: The Reviewer's Craft

      +
      +Screen reader users + +
        +
      • Jump between changed hunks in a diff with Alt+F5 (next change) and Shift+Alt+F5 (previous change) to scan for scope creep efficiently
        • +
      • Use Alt+F2 (Accessible View) on a Copilot-generated review summary to read the full text with arrow keys before posting
        • +
      • When leaving feedback, mention specific line numbers ("Line 42 skips from h2 to h4") so the author can navigate directly with Ctrl+G
        • +
      +
      + +
      +Low vision users + +
        +
      • The three review actions (Approve, Request Changes, Comment) are shown as clearly labeled radio buttons in the review submission form
        • +
      • Use the reviewer checklist in this section as a mental framework -- copy it into your notes and check items off as you review each PR
        • +
      • The diff view uses green and red backgrounds for added/removed lines; pair with a High Contrast theme if these colors are hard to distinguish
        • +
      +
      + +
      +Sighted users + +
        +
      • The Files Changed tab on GitHub.com shows a progress bar indicating how many files you have viewed -- aim for 100% before submitting
        • +
      • Green checkmarks next to file names mean you have already viewed that file; gray dots mean unreviewed
        • +
      • Use the "Viewed" checkbox on each file to track your progress through large PRs
        • +
      +
      + + +

      Day 2 Teaser: The Full Accessibility Agents Review Ecosystem

      +

      You now have the manual skills. Chapter 16 shows you how to leverage 50+ specialized agents to make your reviews faster, more consistent, and more thorough - while staying in full control of what you post.

      +

      The Agents That Help With Code Review

      +

      Pull Request Review Agents:

      +
        +
      • @pr-review - Generates a full-draft PR review with line-numbered diff maps, risk assessment, before/after snapshots, and suggested inline comments. You edit and post it under your name.
        • +
      • @pr-author-checklist - Before you even submit your PR, use this to verify you haven't missed setup steps, accessibility checks, or documentation
        • +
      • @insiders-a11y-tracker - Monitors your PR for accessibility-sensitive changes: WCAG violations, heading hierarchy issues, link text quality, keyboard navigation impacts
        • +
      +

      Code Understanding Agents:

      +
        +
      • @developer-hub - Orchestrates explanations for unfamiliar code, patterns, or frameworks you're reviewing
        • +
      • @python-specialist - If your PR contains Python code, this agent explains patterns, spots accessibility issues, and suggests improvements
        • +
      • @wxpython-specialist - For desktop GUI code, helps verify accessible widget patterns and focus management
        • +
      +

      Accessibility Review Agents (when code affects UI/UX):

      +
        +
      • @keyboard-navigator - Reviews changes to keyboard handling, tab order, focus management
        • +
      • @aria-specialist - Verifies ARIA attributes, roles, states in interactive components
        • +
      • @contrast-master - Checks color changes for WCAG AA contrast compliance
        • +
      • @alt-text-headings - Reviews changes to alt text, heading hierarchy, document structure
        • +
      +

      Comment & Communication Agents:

      +
        +
      • @text-quality-reviewer - Verifies alt text, aria-labels, and button names are descriptive and typo-free
        • +
      • @link-checker - Flags ambiguous link text like "click here" or "read more"
        • +
      +

      How It Works

      +
        +
      1. Review manually first (you just did this with Exercises A, B, C)
        2. +
      2. Run an agent - @pr-review review PR #14 generates a draft in seconds
        3. +
      3. Edit the agent's draft - you add context, remove noise, correct errors
        4. +
      4. Post your review - it now has both AI efficiency and your human judgment
        5. +
      5. The agent tracks impact - @insiders-a11y-tracker monitors whether your accessibility feedback was addressed
        6. +
      +

      The Principle: Skill First, Agent Second

      +

      Why do this manually before using agents? Because:

      +
        +
      • You understand what the agent is doing (you did it manually)
        • +
      • You evaluate the agent's output critically (you know what right looks like)
        • +
      • You add judgment the agent lacks (context, intent, team decisions)
        • +
      • You verify the agent didn't miss anything important
        • +
      +

      Manual reviews teach you what to look for. Agents help you look for it faster.

      +

      A Real Example: The Flow

      +

      Manual Review (your work in part 1-2):

      +
        +
      • Read diff, identify heading hierarchy skip
        • +
      • Write comment explaining why it matters
        • +
      • Submit your verdict
        • +
      +

      Agent-Assisted Review (what you'll do in Chapter 19):

      +
        +
      1. Run: @pr-review review PR #14
        2. +
      2. Agent generates a draft review covering the heading skip, link text, and 5 other issues
        3. +
      3. You read the draft and notice: "the agent's explanation of the heading skip is good, but it missed that the link text on line 23 is still vague. Let me add that."
        4. +
      4. You post the agent's review + your additions
        5. +
      5. Next time you review a similar PR, the agent works faster because it learned from your feedback
        6. +
      +

      Accessibility Agents are trained on 55 different agent patterns - each built by people who manually reviewed code first, saw repetitive patterns, and automated them. The agents you'll use in Chapter 16 exist because expert reviewers looked at 100+ PRs and said "this error comes up in nearly every PR - let me build an agent to catch it automatically."

      +

      Your manual skills + agent efficiency = leverage.

      +
      +

      What's coming later today (Chapter 19):

      +

      At the end of the day, Chapter 16 introduces the full 55-agent ecosystem - specialized agents for:

      +
        +
      • GitHub workflow automation (@daily-briefing, @issue-tracker, @analytics)
        • +
      • Web accessibility auditing (@web-accessibility-wizard, @contrast-master, @keyboard-navigator)
        • +
      • Document scanning (@word-accessibility, @pdf-accessibility, @markdown-a11y-assistant)
        • +
      • Framework-specific accessibility (@react-specialist, @vue-specialist, @wxpython-specialist)
        • +
      • And 35+ more, organized into three teams across five platforms
        • +
      +

      The ecosystem is designed to grow. Agents 56, 57, 58... will be built by contributors like you who saw a gap and filled it.

      +
      +
      +

      Next: Chapter 16: GitHub Copilot
      Back: Chapter 14: Git in Practice
      Related appendices: Appendix G: VS Code Reference

      + +
      + + + + diff --git a/html/admin/qa-bundle/docs/16-github-copilot.html b/html/admin/qa-bundle/docs/16-github-copilot.html new file mode 100644 index 00000000..00c4c569 --- /dev/null +++ b/html/admin/qa-bundle/docs/16-github-copilot.html @@ -0,0 +1,1901 @@ + + + + + + + GitHub Copilot - GIT Going with GitHub + + + + + + + + +
      +

      GitHub Copilot

      +
      +

      Listen to Episode 14: GitHub Copilot - a conversational audio overview of this chapter. Listen before reading to preview the concepts, or after to reinforce what you learned.

      +
      +
      +

      Related appendices: Appendix K: Copilot Reference | Appendix G: VS Code Reference +Authoritative sources: GitHub Docs: About GitHub Copilot | GitHub Accessibility: Copilot in VS Code | VS Code Docs: GitHub Copilot

      +
      +

      AI-Powered Code Assistance in VS Code

      +
      +

      Day 2, Block 2-3 Material

      +

      This guide covers GitHub Copilot: inline code suggestions, Copilot Chat (conversational assistance), custom instructions vs custom agents, effective prompting for non-code contributions, and using Accessible View to read AI-generated responses.

      +

      Official GitHub Accessibility Guides: GitHub publishes two developer guides and an NVDA-focused screen reader guide for Copilot:

      + +

      This chapter covers the same material with additional perspectives and workshop context. Use the official guides as companion references.

      +

      Prerequisites: VS Code Setup & Accessibility Basics, Git & Source Control in VS Code

      +

      Mac keyboard shortcuts: Throughout this chapter, all Ctrl+ shortcuts use Cmd+ on Mac, and Alt+ shortcuts use Option+ on Mac. Key equivalents: Ctrl+Shift+I → Cmd+Shift+I (Chat), Ctrl+I → Cmd+I (inline chat), Alt+F2 → Option+F2 (Accessible View), Ctrl+/ → Cmd+/ (insert suggestion). See the Keyboard Shortcuts Reference at the end of this chapter for the complete list.

      +
      +

      Workshop Recommendation (Chapter 16 / Challenge 13)

      +
      +

      Free to use: GitHub Copilot Free tier is included with all GitHub accounts at no cost. This workshop uses only the free tier. If you're on an organization with GitHub Enterprise, you may have Copilot Pro included; either way, you're covered.

      +

      Billing guidance for this workshop: GitHub Copilot plans and billing are changing. We will provide specific guidance at the workshop, as this is a continuing moving target and is subject to change as we approach the event. If you are unsure whether your account has Copilot access, check github.com/settings/copilot or ask a facilitator before the workshop begins.

      +
      +

      Chapter 16 introduces GitHub Copilot for AI-assisted documentation and writing. It supports Challenge 13: AI as Your Copilot.

      +
        +
      • Challenge count: 3 guided challenges
        • +
      • Automation check: none (tool configuration is account-local and account-specific)
        • +
      • Evidence: issue comment with checklist of completed actions
        • +
      • Pattern: install, prompt, apply, reflect
        • +
      +

      Challenge 13 Set

      +
        +
      1. Sign in to GitHub Copilot - authenticate with GitHub (VS Code 1.116+ has Copilot built in; no extension install needed).
        2. +
      2. Ask Copilot to explain a codebase - clone the sci-fi themes repo and use Copilot Chat to understand it.
        3. +
      3. Ask Copilot to create something new - prompt Copilot to generate a custom theme and apply it.
        4. +
      +

      Challenge 13.1 Step-by-Step: Sign In to Copilot

      +

      Goal: Sign in to GitHub Copilot and verify it responds to prompts.

      +

      Where you are working: VS Code desktop with your Learning Room repository open.

      +

      Estimated time: 3-5 minutes.

      +
      +

      VS Code 1.116 and later: GitHub Copilot is built into VS Code and no extension installation is needed. Skip steps 1-4 below if you are on VS Code 1.116 or later -- Copilot is already present. If VS Code prompts you to sign in on first launch, follow the browser OAuth flow and then proceed to step 5.

      +
      +
        +
      1. (Older VS Code only) Open the Extensions sidebar: Ctrl+Shift+X (Mac: Cmd+Shift+X).
        2. +
      2. (Older VS Code only) Type GitHub Copilot in the search box and press Enter.
        3. +
      3. (Older VS Code only) Find GitHub Copilot (publisher: GitHub) in the results. Activate Install.
        4. +
      4. (Older VS Code only) VS Code may also install GitHub Copilot Chat automatically. If not, search for it separately and install it.
        5. +
      5. Sign in when prompted: activate Sign in to GitHub and complete the OAuth flow in your browser.
        6. +
      6. Verify Copilot is active: open Copilot Chat with Ctrl+Shift+I (Mac: Cmd+Shift+I). Type Hello, are you working? and press Enter. Copilot should respond.
        7. +
      +

      Screen reader tip: The Copilot Chat panel opens as a sidebar. Your screen reader announces responses as they stream in. Press Alt+F2 (Accessible View) to read the full response in a plain text buffer if streaming is hard to follow.

      +

      You are done when: Copilot Chat responds to a test prompt.

      +

      Challenge 13.2 Step-by-Step: Explain a Codebase

      +

      Goal: Use Copilot Chat to understand an unfamiliar repository by asking targeted questions.

      +

      Where you are working: VS Code with the sci-fi themes repository cloned.

      +

      Estimated time: 10-15 minutes.

      +
        +
      1. Open the Command Palette: Ctrl+Shift+P (Mac: Cmd+Shift+P).
        2. +
      2. Run Git: Clone and paste: https://github.com/community-access/vscode-sci-fi-themes.git
        3. +
      3. Open the cloned repository when VS Code prompts.
        4. +
      4. Open Copilot Chat: Ctrl+Shift+I (Mac: Cmd+Shift+I).
        5. +
      5. Ask Copilot: "What does the chat.agent.thinking.phrases setting do in VS Code?"
        6. +
      6. Read the response. Use Alt+F2 (Accessible View) if needed to read the full text.
        7. +
      7. Ask a follow-up: "How do I apply one of these themes to my settings.json?"
        8. +
      8. Follow Copilot's instructions to apply one theme to your settings.json file.
        9. +
      +

      You are done when: You have asked Copilot at least two questions and applied one setting change.

      +

      Challenge 13.3 Step-by-Step: Create Something New

      +

      Goal: Use Copilot as a creative collaborator to generate a custom config and apply it.

      +

      Where you are working: VS Code with Copilot Chat open.

      +

      Estimated time: 10-15 minutes.

      +
        +
      1. Open Copilot Chat: Ctrl+Shift+I (Mac: Cmd+Shift+I).
        2. +
      2. Type a creative prompt: "Create a custom GitHub Copilot thinking phrases theme for [your favorite universe - Dune, Marvel, Studio Ghibli, Star Trek, etc.]"
        3. +
      3. Read Copilot's generated theme. It should include an array of themed phrases.
        4. +
      4. Copy the generated content: select all text in the Copilot response, then Ctrl+C (Mac: Cmd+C).
        5. +
      5. Open your settings.json: Command Palette, then Preferences: Open User Settings (JSON).
        6. +
      6. Paste the theme configuration into your settings.
        7. +
      7. Save with Ctrl+S and reload VS Code: Command Palette, then Developer: Reload Window.
        8. +
      8. Test your new theme by asking Copilot a question and watching the thinking phrases.
        9. +
      +

      Screen reader tip: Copilot Chat responses can be long. Use Alt+F2 (Accessible View) to read them in a plain text buffer where you can copy text more easily.

      +

      You are done when: Your personalized thinking phrases appear when Copilot is processing a response.

      +

      Completing Challenge 13: Submit Your Evidence

      +

      Open your assigned Challenge 13 issue and post a completion comment:

      +
      Chapter 13 completed:
+- Copilot installed and signed in: yes / no
+- Asked Copilot to explain a setting: yes / no
+- Applied a setting from Copilot's suggestion: yes / no
+- Created a custom theme: yes / no
+- My theme universe: [your choice]
      +

      Close your Challenge 13 issue when done.

      +

      Expected Outcomes

      +
        +
      • Student can install and authenticate GitHub Copilot Chat.
        • +
      • Student can ask Copilot effective questions about code and settings.
        • +
      • Student can use Copilot's output to customize their development environment.
        • +
      • Student understands Copilot as a tool to explain and create, not just autocomplete.
        • +
      +

      If You Get Stuck

      +
        +
      1. Extension installation fails? Reload VS Code: Ctrl+Shift+P, then Developer: Reload Window.
        2. +
      2. OAuth sign-in fails? Verify your GitHub account is active in the browser first, close VS Code and retry.
        3. +
      3. Chat panel does not open? Try Ctrl+Shift+I (Mac: Cmd+Shift+I). If still nothing, check that the Copilot Chat extension is installed (not just the base Copilot extension).
        4. +
      4. Copilot seems unresponsive? Click the model selector at the bottom of Chat panel and confirm you are signed in.
        5. +
      5. Cannot copy from Copilot response? Use Alt+F2 (Accessible View) to get the text in a copyable buffer.
        6. +
      6. Ask facilitator to verify Copilot is activated and show you one example prompt.
        7. +
      7. Finished but not sure you did it right? Compare your work against the Challenge 13 reference solution.
        8. +
      +
      +

      Continue learning: The GitHub Skills courses Getting Started with GitHub Copilot and Customize Your GitHub Copilot Experience cover Copilot setup, prompting, and personalization. See Appendix Z for the full catalog.

      +
      +

      Learning Moment

      +

      AI assistance amplifies clarity. Using Copilot as a brainstorming partner helps you write documentation that others can actually understand. The prompting skill you practiced here - asking specific questions, iterating on responses, applying results - transfers to every AI tool you will use in your career.

      +

      Learning Pattern Used in This Chapter

      +
        +
      1. Install the tool and verify it works before starting the task.
        2. +
      2. Use the tool to explore and understand (ask questions, read responses).
        3. +
      3. Use the tool to create something new (generate, customize, apply).
        4. +
      4. Reflect on when the tool helped and when your own judgment was better.
        5. +
      +

      About Learning Cards in This Chapter

      +

      Throughout this chapter, look for expandable "learning cards" that show how to accomplish each task from different perspectives. Not every section has every card - only the cards that add meaningful guidance for that topic are included.

      + + + + + + + + + + + + + + + + + + + + + + + + + + + +
      CardWho it helps
      Visual / mouseSighted users who primarily use a mouse or trackpad
      Low visionUsers who zoom to 200%+, use high contrast, or increase font sizes
      NVDA / JAWS (Windows)Screen reader users on Windows
      VoiceOver (macOS)Screen reader users on Mac
      CLIUsers who prefer the terminal with gh copilot commands
      +

      Table of Contents

      +
        +
      1. What is GitHub Copilot
        2. +
      2. Installing GitHub Copilot
        3. +
      3. Inline Suggestions - Ghost Text Completions
        4. +
      4. GitHub Copilot Chat - Conversational Assistance
        5. +
      5. Copilot Edits — Making Multi-File Changes
        6. +
      6. Agent Mode — Let Copilot Drive
        7. +
      7. Next Edit Suggestions
        8. +
      8. Copilot on GitHub.com
        9. +
      9. Effective Prompting for Documentation Work
        10. +
      10. Custom Instructions vs Custom Agents
        11. +
      11. Using Accessible View with Copilot Responses
        12. +
      12. Keyboard Shortcuts Reference
        13. +
      +

      1. What is GitHub Copilot

      +

      GitHub Copilot is an AI pair programmer that suggests code and text completions as you type. It can:

      +
        +
      • Complete lines of code or documentation
        • +
      • Generate entire functions or sections of text from comments
        • +
      • Answer questions about code in your workspace
        • +
      • Explain complex code in plain language
        • +
      • Draft documentation, issue responses, and commit messages
        • +
      • Search for files and symbols across your workspace
        • +
      +

      For this workshop: Copilot helps with Markdown documentation, issue triage, PR descriptions, and commit messages - not just code.

      +

      Copilot as a git co-author: Starting with VS Code 1.118, GitHub Copilot is automatically added as a co-author in your Git commit messages when Copilot assists with your work. You will see a Co-authored-by: GitHub Copilot <copilot@github.com> trailer appended to commits. This is on by default and can be disabled via Settings: search github.copilot.git.generateCommitMessage and set coAuthoredBy to off if you prefer not to include it.

      +

      Copilot Free tier: Available for all GitHub users. Provides access to inline suggestions and Copilot Chat with usage limits. No payment required for this workshop.

      +
      +

      Note on billing changes: GitHub Copilot plans and billing are actively evolving. We will provide specific guidance at the workshop. Check github.com/settings/copilot to verify your current access level before the event.

      +
      +

      Screen reader support: Copilot is fully accessible with screen readers. Suggestions are announced via ARIA live regions, and Accessible View provides complete access to Chat responses.

      +
      +

      Screen reader optimized mode: Press Shift+Alt+F1 (Mac: Shift+Option+F1) to toggle VS Code's screen reader optimized mode. This adjusts how Copilot suggestions are announced, disables ghost text that cannot be read by screen readers, and routes all suggestion content through Accessible View. If your screen reader is detected at startup, VS Code enables this mode automatically. You can also set it manually in Settings: editor.accessibilitySupport: "on".

      +
      +

      2. Installing GitHub Copilot

      +

      Installation Steps

      +
        +
      1. Open Extensions sidebar: Ctrl+Shift+X (Mac: Cmd+Shift+X)
        2. +
      2. Search for "GitHub Copilot Chat"
        3. +
      3. Find GitHub Copilot Chat (publisher: GitHub)
        4. +
      4. Press Enter to open the extension detail page
        5. +
      5. Tab to "Install" button → press Enter
        6. +
      6. Wait for installation to complete
        7. +
      +

      One extension, all features: GitHub Copilot Chat is now the single all-in-one extension. It provides inline code suggestions, the Chat panel (Ctrl+Shift+I / Mac: Cmd+Shift+I), inline chat (Ctrl+I / Mac: Cmd+I), and all agent features. The older separate "GitHub Copilot" extension has been deprecated.

      +

      Signing In

      +

      After installation:

      +
        +
      1. VS Code prompts: "Sign in to use GitHub Copilot"
        2. +
      2. Navigate to the notification or click the Copilot icon in the status bar
        3. +
      3. Select "Sign in to GitHub"
        4. +
      4. Your browser opens for GitHub authentication
        5. +
      5. Authorize the Copilot extension
        6. +
      6. Return to VS Code
        7. +
      +

      Verify activation

      +
        +
      • Bottom-right status bar shows Copilot icon (looks like ><)
        • +
      • Icon should be active (not grayed out)
        • +
      • If grayed out, click it to sign in
        • +
      +

      Checking Subscription Status

      +

      Command Palette

      +
        +
      1. Ctrl+Shift+P (Mac: Cmd+Shift+P)
        2. +
      2. Type "Copilot: Check Status"
        3. +
      3. Select it to see your subscription tier (Free, Pro, Enterprise)
        4. +
      +

      Free tier includes

      +
        +
      • Completions and multi-line suggestions
        • +
      • Copilot Chat
        • +
      • Limited monthly usage (usually sufficient for documentation work)
        • +
      +
      +

      Billing note: GitHub Copilot plan details are evolving. Facilitators will provide current guidance at the workshop. To check your access status now, visit github.com/settings/copilot.

      +
      +

      3. Inline Suggestions - Ghost Text Completions

      +

      Copilot suggests completions as you type, displayed as gray "ghost text" after your cursor. In screen reader mode, VS Code announces suggestions rather than showing them visually.

      +

      How Inline Suggestions Work

      +

      While typing

      +
        +
      1. Copilot analyzes your context (file content, cursor position, nearby files)
        2. +
      2. Generates a suggestion
        3. +
      3. Presents the suggestion
        4. +
      +
      +Visual / mouse users + +

      The suggestion appears as gray "ghost text" after your cursor - a preview of what Copilot thinks you want to type next. It's there but not inserted; press Tab to accept it or Escape to dismiss.

      +
      + +
      +Low vision users (zoom, high contrast, enlarged fonts) + +

      Ghost text is intentionally low-contrast (gray on white). At high zoom levels this can be nearly invisible.

      +
        +
      • Increase ghost text contrast: Open Settings (Ctrl+,), search editorGhostText, then customize editor.ghostText.foreground in your color theme to a darker shade such as #555555.
        • +
      • Use Accessible View instead: Press Alt+F2 when a suggestion appears. The suggestion text renders at your configured font size in a separate pane, making it far easier to read at 200%+ zoom.
        • +
      • Word-by-word acceptance (Ctrl+Right Arrow) lets you watch each word appear at full contrast before deciding whether to continue.
        • +
      • High Contrast themes do not automatically restyle ghost text. The color customization above is the most reliable fix.
        • +
      +
      + +
      +Screen reader users (NVDA / JAWS / VoiceOver) + +

      Suggestions are announced via ARIA live regions - ghost text is not visually meaningful to you so VS Code reads it instead:

      +
        +
      • NVDA/JAWS: "Suggestion available" (or reads the suggestion text, depending on verbosity settings)
        • +
      • VoiceOver: Announces suggestions in accessible form
        • +
      +

      Press Alt+F2 (Mac: Option+F2) to open the suggestion in Accessible View - this gives you the complete suggestion text in a static, fully readable panel without streaming.

      +
      + +

      Accepting Suggestions

      + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + +
      ActionWindows/LinuxMac
      Accept entire suggestionTabTab
      Reject suggestionEscapeEscape
      Accept one word at a timeCtrl+Right ArrowCmd+Right Arrow
      Show next alternative suggestionAlt+]Option+]
      Show previous alternative suggestionAlt+[Option+[
      Open full suggestion listCtrl+EnterCmd+Enter
      Open suggestion in Accessible ViewAlt+F2Option+F2
      Insert suggestion from Accessible View at cursorCtrl+/Cmd+/
      + +

      Pressing Ctrl+Enter opens a separate side-by-side tab showing up to 10 alternative suggestions. For screen reader users:

      +
        +
      • Switch to your screen reader's browse/virtual mode when the panel opens (NVDA: Insert+Space to toggle off Application mode; JAWS: this may happen automatically)
        • +
      • Use heading keys (H in NVDA/JAWS browse mode) to navigate between each suggestion -- each suggestion is announced as a heading
        • +
      • Each suggestion is followed by an Accept button -- navigate to it with Tab or B (button key) and press Enter to insert it at your cursor position
        • +
      • Press Escape or close the tab to dismiss without accepting
        • +
      +
      +

      Tip: Alt+F2 on a single suggestion is usually faster. Use Ctrl+Enter when you want to compare multiple alternatives before committing.

      +
      +

      Accepting word-by-word (Ctrl+Right Arrow / Mac: Cmd+Right Arrow) is particularly useful when

      +
        +
      • The suggestion starts correctly but you want to finish differently
        • +
      • You want to review the suggestion incrementally
        • +
      • You're learning and want to see how Copilot structures responses
        • +
      +

      Reading Suggestions with Screen Readers

      +
      +

      Visual users: If Copilot's ghost text is getting in the way, skip to "Disabling Inline Suggestions" below.

      +
      +
      +Screen reader users - tuning announcement verbosity + +

      If suggestions are announced too frequently or are intrusive

      +

      NVDA

      +
        +
      1. NVDA Menu → Preferences → Settings → Presentation
        2. +
      2. Find "Report dynamic content changes"
        3. +
      3. Reduce verbosity level or set specific delays
        4. +
      +

      JAWS

      +
        +
      1. Settings Center → HTML/PDF/Accessibility
        2. +
      2. Adjust "Auto Forms Mode" and "ARIA Live Region" settings
        3. +
      +

      VoiceOver

      +
        +
      1. VoiceOver Utility → Verbosity
        2. +
      2. Reduce "Announcements" level
        3. +
      +

      Alternative: Use Accessible View

      +

      Press Alt+F2 (Mac: Option+F2) when a suggestion appears to read it in the Accessible View (full text, no streaming).

      +
      + +

      Prompting Through Comments

      +

      Copilot reads inline comments as instructions. For Markdown files:

      +
      <!-- Write a step-by-step guide for screen reader users on how to create a GitHub issue -->
      +

      Type this comment, press Enter, and Copilot drafts content based on your instruction. You review, edit, and refine.

      +

      Example prompts for this workshop

      +
      <!-- Explain how to navigate the GitHub Issues list with NVDA -->
+
+<!-- Create a checklist for accessible Markdown documentation -->
+
+<!-- Write alt text for a screenshot showing the GitHub PR review interface -->
+
+<!-- Draft a commit message for fixing heading hierarchy in GUIDE.md -->
      +

      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 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):

      +
      gh extension install github/gh-copilot
      +

      Ask a general question:

      +
      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:

      +
      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.

      + + + + + + + + + + + + + + + + + + + + + + + + + + + + +
      ModeHow It WorksBest For
      Ask (default)Conversational Q&A - Copilot explains, suggests, and answers but does not edit files directlyQuestions, explanations, understanding unfamiliar code, reviewing content
      EditYou define a "working set" of files; Copilot proposes edits and shows a diff you approve or reject - nothing changes without your confirmationTargeted, multi-file changes where you want full control
      AgentCopilot works autonomously - it decides which files to open, reads and writes code, and runs terminal commands to complete the taskLarger tasks where you want Copilot to drive end-to-end
      PlanCopilot produces a step-by-step implementation plan before writing any code; you review and approve the plan firstComplex 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.

      +
      +
      +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. +

      2. Model selector dropdown

        +
          +
        • Choose which AI model to use (GPT-4, Claude, etc.)
          • +
        • Some models better for code, others for prose
          • +
        +
        3. +

      3. Conversation history

        +
          +
        • Shows your previous prompts and Copilot's responses
          • +
        • Navigate with Up/Down Arrow
          • +
        • Each message is a separate element
          • +
        +
        4. +

      4. Action buttons

        +
          +
        • "Clear Chat" - start a new conversation
          • +
        • "View in Editor" - open response in a new file
          • +
        +
        5. +
      +

      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)

      + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + +
      GoalExample Prompt
      Understand a fileExplain what @11-vscode-interface.md covers in plain language
      Improve documentationThis section is unclear. Rewrite it for a first-time contributor using a screen reader: [paste text]
      Check toneReview this PR description for tone. Is it clear, respectful, and helpful? Suggest improvements.
      Draft contentWrite a section on keyboard navigation in VS Code for screen reader users
      Explain an errorI got this error when trying to commit: [paste error]. What does it mean and how do I fix it?
      Generate alt textWrite alt text for this image: [describe what's in the image]
      Create checklistCreate an accessibility review checklist for Markdown documentation
      Review for accessibilityCheck this Markdown for accessibility issues: [paste content]
      +

      Using @ Mentions in Chat

      +

      @ symbols let you provide context to Copilot

      + + + + + + + + + + + + + + + + + + + + + + + + + + + +
      MentionWhat It Does
      @workspaceSearches your entire workspace for context
      @filename.mdReferences a specific file
      #fileLists files to select from
      #selectionReferences your currently selected text
      #terminalLastCommandReferences the last terminal command and output
      +

      Example prompts with context

      +
      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:

      + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + +
      CommandWhat It Does
      /explainExplains selected code or text
      /fixSuggests fixes for problems in selected code
      /testsGenerates tests (for code files)
      /helpShows all available commands
      /clearClears chat history
      /savePromptSaves the current chat conversation as a reusable .prompt.md file
      +

      Example

      +
        +
      1. Select a block of complex Markdown
        2. +
      2. Open Chat: Ctrl+Shift+I (Mac: Cmd+Shift+I)
        3. +
      3. Type /explain
        4. +
      4. Copilot explains the structure and purpose
        5. +
      +

      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. +
      2. Type copilot
        3. +
      3. Browse the list of available actions
        4. +
      +

      Useful built-in actions include:

      + + + + + + + + + + + + + + + + + + + + + + + + + + + +
      ActionWhat It Does
      Copilot: Explain ThisExplains the selected code or text
      Copilot: Generate DocsGenerates documentation for the selected code
      Copilot: Generate TestsCreates test cases for the selected code
      Copilot: Fix ThisSuggests a fix for the selected code
      Copilot: Review and CommentReviews 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. +
      2. At the bottom of the Chat panel, click the mode dropdown and select Edit
        3. +
      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. +
      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. +
      5. Press Enter — Copilot shows a diff of proposed changes in each file
        6. +
      6. Review the changes: use Accept or Reject on individual files, or Accept All / Reject All
        7. +
      +
      +

      Nothing changes until you accept. Copilot Edits shows you the full diff first. You are always in control.

      +
      + +
        +
      • 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 and Chapter 20: Build Your Agent 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. +
      2. Select Agent from the mode dropdown at the bottom of the Chat panel
        3. +
      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. +
      4. Copilot begins working — it shows each step it's taking and asks for approval before running terminal commands
        5. +
      5. Watch the progress in the Chat panel; review any proposed changes in the editor
        6. +
      +

      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 explanationAsk
      Make targeted changes to specific files you controlEdit
      Complete a multi-step task and let Copilot navigate the workspaceAgent
      Review and approve a plan before anything changesPlan
      +
      +

      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. +
      2. Search for nextEditSuggestions
        3. +
      3. Enable "GitHub Copilot: Next Edit Suggestions"
        4. +
      +

      Or add to your settings.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 — you must be signed in
        2. +
      2. Look for the Copilot icon (a circle with dot pattern) in the top navigation bar
        3. +
      3. Click it (or press ? then select Copilot from the command palette) to open the chat panel
        4. +
      4. Type your question and press Enter
        5. +
      +

      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. +
      2. In the PR form, look for the Copilot icon next to the description field
        3. +
      3. Click it — Copilot reads your commits and diff and writes a draft description
        4. +
      4. Review and edit the draft — it typically includes what changed and why
        5. +
      5. Submit the PR
        6. +
      +
      +

      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

      + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + +
      FeatureGitHub.comVS Code
      Chat (general questions)YesYes
      Repository / issue / PR contextYes, built inYes, via @github
      Inline code suggestionsNoYes
      Copilot Edits (multi-file)NoYes
      Agent modeNoYes
      PR description generationYesNo
      Code review commentsYes, for maintainersNo
      No install requiredYesRequires 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

      +
      Write about accessibility
      +

      Good prompt

      +
      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. +
      2. Clear topic: "navigate the VS Code Explorer sidebar"
        3. +
      3. Target audience: "screen reader users" who "never used VS Code"
        4. +
      4. Required details: "keyboard shortcuts for NVDA and JAWS"
        5. +
      5. Format guidance: "headings and bullet points"
        6. +
      +

      Prompting Patterns for This Workshop

      +

      Pattern 1: Contextual Rewrite

      +
      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

      +
      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

      +
      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

      +
      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

      +
      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

      +
      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).

      +

      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

      +
      # 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 for complete agent documentation.

      +

      Comparison Table

      + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + +
      FeatureCustom InstructionsCustom Agent
      When activeBackground - every interactionOn-demand - you type @agent-name
      Defined in.github/copilot-instructions.md.github/agents/[name].agent.md
      Tool accessStandard Copilot toolsCan restrict or grant specific permissions
      Best forBroad coding standards and preferencesFocused, repeatable, specialized tasks
      Requires invocationNo - always onYes - 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. +
      2. You invoke @insiders-a11y-tracker to scan recent changes
        3. +
      3. The agent finds a heading skip (H1 → H3)
        4. +
      4. You ask Copilot Chat to fix it: "Fix the heading hierarchy in this file"
        5. +
      5. Copilot's fix follows your custom instructions (uses semantic HTML, adds ARIA where needed)
        6. +
      +

      Both work together - instructions guide every response, agents automate specific workflows

      +

      Writing Accessibility-Focused Custom Instructions

      +
      +

      Source: accessibility.github.com/documentation/guide/copilot-instructions/

      +
      +

      Custom instructions can be set at three levels. Each level cascades to narrower scopes:

      + + + + + + + + + + + + + + + + + + + + + + + +
      LevelWhereEffect
      OrganizationCopilot organization settingsApplies to all repositories in the org
      Repository.github/copilot-instructions.mdOverrides org instructions; applies to one repo
      PersonalGitHub.com → Settings → Copilot → InstructionsYour 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:

      +
      ## 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:

      +
      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:

      +
      ## 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 <p>.
      +

      Reference and enforce your design system

      +

      Document which components to use and which are deprecated. Design systems evolve - keep instructions current:

      +
      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.

      + +

      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:

      +
      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 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
        • +
      • 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
        • +
      • Markdown Accessibility Review Guidelines - A practical guide for reviewing Markdown output for accessibility, useful as a reference when writing documentation-focused instructions: Markdown Accessibility
        • +
      +

      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
        • +
      + +

      Every time you ask Copilot something

      +
        +
      1. Type your prompt in Chat input
        2. +
      2. Press Ctrl+Enter (Mac: Cmd+Enter) to send
        3. +
      3. Press Alt+F2 (Mac: Option+F2) to open Accessible View - you can open it immediately after sending, before the response finishes
        4. +
      4. Follow along as the response streams in the Accessible View in real-time
        5. +
      5. Read or re-read any section with Arrow keys
        6. +
      6. Press Escape to close Accessible View and return to Chat
        7. +
      +
      +

      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. +
      2. Press Alt+F2 (Mac: Option+F2)
        3. +
      3. Accessible View shows: "Suggestion: [full text of the suggestion]"
        4. +
      4. Read it completely
        5. +
      5. To insert the suggestion at your cursor: press Ctrl+/ (Mac: Cmd+/)
        6. +
      6. To close without inserting: press Escape, then Tab to accept or Escape to reject
        7. +
      +

      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 <pre> 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

      + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + +
      ActionWindows/LinuxmacOS
      Accept suggestionTabTab
      Reject suggestionEscapeEscape
      Accept word-by-wordCtrl+Right ArrowCmd+Right Arrow
      Next suggestionAlt+]Option+]
      Previous suggestionAlt+[Option+[
      Open suggestions listCtrl+EnterCmd+Enter
      Open suggestion in Accessible ViewAlt+F2Option+F2
      Insert suggestion from Accessible ViewCtrl+/Cmd+/
      +

      Copilot Chat

      + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + +
      ActionWindows/LinuxmacOS
      Open Chat panelCtrl+Shift+ICmd+Shift+I
      Inline chat (in-file)Ctrl+ICmd+I
      Quick chat (floating)Ctrl+Shift+Alt+ICmd+Shift+Ctrl+I
      Send messageCtrl+EnterCmd+Enter
      Clear chatCtrl+LCmd+L
      +

      Accessibility

      + + + + + + + + + + + + + + + + + + + + + + + + + + + + +
      ActionWindows/LinuxmacOS
      Toggle screen reader optimized modeShift+Alt+F1Shift+Option+F1
      Open Accessible ViewAlt+F2Option+F2
      Open Accessible HelpAlt+HOption+H
      Close Accessible ViewEscapeEscape
      +

      VS Code General (Quick Reference)

      + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + +
      ActionWindows/LinuxmacOS
      Command PaletteCtrl+Shift+PCmd+Shift+P
      Go to fileCtrl+PCmd+P
      Find in fileCtrl+FCmd+F
      SettingsCtrl+,Cmd+,
      Source ControlCtrl+Shift+GCmd+Shift+G
      ExplorerCtrl+Shift+ECmd+Shift+E
      TerminalCtrl+BacktickCtrl+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.

      + + + + + + + + + + + + + + + + + + +
      ActionShortcutWhat 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

      +

      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:

      + +
      +

      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 modeWhat it looks likeWhy it happens
      Fabricated function namesresponse.getData() on an object that has no getData methodCopilot blends APIs from multiple libraries into one suggestion
      Incorrect ARIA attributesrole="textbox" on a <div> that acts as a buttonTraining data includes many inaccessible websites
      Outdated dependency versions"react": "^16.8" in a new projectTraining data includes older tutorials and starter templates
      Plausible-but-wrong logicA sort function that works for most inputs but fails on edge casesThe pattern matches what Copilot has seen, but the details are wrong
      Confidently incorrect explanationsChat says "this function is O(n)" when it is actually O(n squared)Copilot generates fluent text, not verified analysis
      Hallucinated URLsLinks to documentation pages or API endpoints that do not existCopilot 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. +
      2. Does it do what I asked? -- Read the code and confirm it matches your intent, not just your prompt.
        3. +
      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. +
      4. Does it match the project's conventions? -- Check naming, formatting, file organization, and error handling against the existing codebase.
        5. +
      5. Did I check any URLs or references it generated? -- Open every link, verify every package name, confirm every API endpoint.
        6. +
      6. Would this pass an accessibility review? -- Run it through the checks described below.
        7. +
      +
      +

      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 <img> tags with empty or missing alt attributes
        • +
      • Improper heading levels -- jumping from <h2> to <h4>, 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). 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 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 on building and evaluating your own agent, and Chapter 21 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. +
      2. Click the Copilot icon → verify "Completions enabled"
        3. +
      3. Check subscription status: Ctrl+Shift+P → "Copilot: Check Status"
        4. +
      4. Restart VS Code
        5. +
      5. Sign out and sign back in: Ctrl+Shift+P → "Copilot: Sign Out"
        6. +
      +

      Suggestions Are Too Frequent/Distracting

      +

      Issue: Constant interruptions from suggestions.

      +

      Solutions

      +
        +
      1. Use word-by-word acceptance: Ctrl+Right Arrow
        2. +
      2. Reduce screen reader verbosity (see Section 3)
        3. +
      3. Use Accessible View (Alt+F2) to review suggestions without live announcements
        4. +
      4. Disable inline suggestions temporarily: Copilot icon → "Disable Completions"
        5. +
      +

      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. +
      2. Check ARIA live region settings in your screen reader
        3. +
      3. Navigate manually to the response area with Tab or Arrow keys
        4. +
      4. Use Quick Chat (Ctrl+Shift+Alt+I) instead of panel chat
        5. +
      +

      "Copilot Subscription Required"

      +

      Issue: Extension installed but asks for subscription.

      +

      Solutions

      +
        +
      1. Sign in to GitHub: Copilot icon → "Sign in"
        2. +
      2. Verify GitHub account has Copilot access (free tier or paid)
        3. +
      3. Check github.com/settings/copilot for subscription status
        4. +
      4. Free tier users: ensure you haven't exceeded monthly limits
        5. +
      +

      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. +
      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. +
      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. +
      4. Try a follow-up - Type: Summarize that in 3 bullet points and press Enter. Copilot remembers the context from your first question.
        5. +
      +

      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
      Back: Chapter 15: Code Review
      Related appendices: Appendix K: Copilot Reference

      + +
      + + + + diff --git a/html/admin/qa-bundle/docs/17-issue-templates.html b/html/admin/qa-bundle/docs/17-issue-templates.html new file mode 100644 index 00000000..e4f4a7c5 --- /dev/null +++ b/html/admin/qa-bundle/docs/17-issue-templates.html @@ -0,0 +1,2403 @@ + + + + + + + Issue Templates - GIT Going with GitHub + + + + + + + + +
      +

      Issue Templates

      +
      +

      Listen to Episode 16: Issue Templates - 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 C: Markdown Reference | Appendix N: Advanced Search +Authoritative sources: GitHub Docs: About issue and PR templates | GitHub Docs: Configuring issue templates

      +
      +

      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, 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 - 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 - Optional but helpful for generating template variations
        • +
      • Chapter 10: Notifications - 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), 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. +
      2. Remix the registration template - adapt it for a new use case (bug report, event, research).
        3. +
      3. Create a Markdown template (optional) - build a Markdown-based template from scratch.
        4. +
      4. Test in the template chooser (optional) - verify your template appears and works.
        5. +
      +

      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 repository.

      +

      Estimated time: 10-15 minutes.

      +

      The Template: .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. +
      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. +
      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. +
      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. +
      5. Search the file for "accessible" - notice the description mentions that all fields work with screen readers. This is professional template thinking.
        6. +
      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.
        7. +
      +

      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:

      + +

      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. +
      2. Copy the registration template file to a new file: .github/ISSUE_TEMPLATE/my-template.yml
        3. +
      3. Change the name and description in the frontmatter to match your new context.
        4. +
      4. Change the title prefix (for example: [Bug Report]: or [Event]: ).
        5. +
      5. Change the labels to appropriate labels for your use case.
        6. +
      6. Replace each field's label, description, placeholder, and options to match your new context.
        7. +
      7. Decide which fields should be required: true and which can be optional.
        8. +
      8. Validate your YAML syntax: copy the file contents to yamllint.com and fix any errors.
        9. +
      9. Commit and push to your repository.
        10. +
      +

      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. +
      2. Add the Markdown template frontmatter at the top:
        3. +
      +
      ---
+name: "My Template Name"
+about: "Short description of when to use this template"
+title: "[PREFIX]: "
+labels: documentation
+---
      +
        +
      1. Note: Markdown templates use about instead of description (unlike YAML form templates).
        2. +
      2. Below the frontmatter, add 3-4 sections with HTML comment instructions:
        3. +
      +
      ## Problem
+<!-- Describe the problem you encountered. -->
+
+## Context
+<!-- What were you trying to do when you found this problem? -->
+
+## Solution Ideas
+<!-- Optional: any ideas for how to fix this? -->
      +
        +
      1. Commit and push.
        2. +
      +

      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. +
      2. Activate New Issue.
        3. +
      3. Verify your template appears in the template chooser.
        4. +
      4. Activate Get started on your template and file a test issue.
        5. +
      +

      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:

      +
      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 repository.
        2. +
      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. +
      3. YAML not parsing? Compare with the remix sample in learning-room/docs/samples/challenge-14-registration-remix-example.yml and check indentation.
        4. +
      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. +
      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. +
      6. Remix approach feels overwhelming? Start by changing just the field labels and descriptions. Do not change the structure yet.
        7. +
      7. Ask facilitator to review your template and suggest improvements.
        8. +
      8. Finished but not sure you did it right? Compare your work against the Challenge 14 reference solution.
        9. +
      +
      +

      Continue learning: The GitHub Skills course Introduction to Repository Management covers templates and contributor settings in an interactive format. See Appendix Z 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. +
      2. Remix by changing content while keeping structure (safe, fast iteration).
        3. +
      3. Create from scratch only after you understand the pattern (Markdown template).
        4. +
      4. Test the result in the real environment (template chooser).
        5. +
      +

      Table of Contents

      +
        +
      1. What Is an Issue Template?
        2. +
      2. How Templates Work on GitHub
        3. +
      3. Navigating the Template Picker
        4. +
      4. The Accessibility Agents Issue Templates
        5. +
      5. Creating a New Template - Step by Step
        6. +
      6. YAML Form-Based Templates
        7. +
      7. Building an Accessibility Bug Report Template
        8. +
      8. Pull Request Templates
        9. +
      9. Hands-On Activity
        10. +
      +

      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

      +
      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. +
      2. Click the New issue button
        3. +
      3. The template chooser page loads - templates appear as cards with a title, description, and "Get started" button
        4. +
      4. Click "Get started" on the template you want
        5. +
      5. The issue editor opens with that template's content pre-filled
        6. +
      +
      + +
      +Screen reader users - NVDA / JAWS (Windows) + +
        +
      1. Navigate to the Issues tab (press T from the repository tabs landmark)
        2. +
      2. Activate "New issue" button
        3. +
      3. The template chooser page loads
        4. +
      4. Each template appears as a list item or a link
        5. +
      5. Use Tab to move between templates
        6. +
      6. Each template shows: name, description, "Get started" button
        7. +
      7. Activate "Get started" on your chosen template
        8. +
      +
      + +
      +Screen reader users - VoiceOver (macOS) + +
        +
      1. Navigate to the Issues tab (VO+Right from the tab bar landmark)
        2. +
      2. VO+Space to activate "New issue"
        3. +
      3. The chooser page loads - templates appear as list items
        4. +
      4. VO+Right to move between templates
        5. +
      5. VO+Space on "Get started" for your chosen template
        6. +
      +
      + +

      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. +
      2. Click the .github folder in the file listing
        3. +
      3. Click ISSUE_TEMPLATE
        4. +
      4. You'll see the template files - click any to read it
        5. +
      +
      + +
      +Screen reader users (NVDA / JAWS / VoiceOver) + +
        +
      1. Open the Code tab
        2. +
      2. Use Ctrl+Alt+Down/Up (NVDA/JAWS) or VO+Arrow (VoiceOver) in the files table to reach the .github folder
        3. +
      3. Activate the folder
        4. +
      4. Activate ISSUE_TEMPLATE
        5. +
      5. You will see the template files listed
        6. +
      +
      + +

      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

      +
      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. +
      2. Choose a starter template or create a blank one.
        3. +
      3. Edit the template content and click Propose changes to commit.
        4. +
      +

      VS Code Desktop / github.dev:

      +
        +
      1. Create the file .github/ISSUE_TEMPLATE/your-template.md (or .yml for form-based).
        2. +
      2. Add YAML frontmatter (name, description, title, labels) and body content.
        3. +
      3. Commit and push.
        4. +
      +

      Git CLI / GitHub CLI:

      +
      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 covers how templates connect to automated workflows.

      +
      +

      Before creating a template, decide which format best suits your needs:

      + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + +
      FactorMarkdown TemplatesYAML Form Templates
      Best forSimple templates, freeform textStructured data collection, accessibility
      ComplexityVery simple to createMore complex, requires YAML knowledge
      Screen reader UXAnnounces as pre-filled text editorAnnounces each field with explicit labels
      ValidationNone - contributors can delete anythingCan mark fields as required, validate input
      FlexibilityFull Markdown formatting freedomLimited to defined field types
      Data consistencyVaries - contributors may skip sectionsHigh - dropdowns ensure consistent values
      Learning curveMinimalModerate
      MaintenanceEasy - just edit MarkdownMore 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:

      +
      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:

      +
      ## 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 <!-- like this --> 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:

      +
      name: Accessibility Bug (Markdown)
+about: Report an accessibility issue using the simple Markdown template
+title: '[A11Y] '
+labels: ['accessibility', 'needs-triage']
+assignees: ''
+
+<!--
+Thank you for reporting an accessibility issue. Please fill in all sections below.
+Screen reader and browser information is especially important for us to reproduce the issue.
+-->
+
+## Component Affected
+
+<!-- Which agent, slash command, or feature has the accessibility issue? -->
+
+- [ ] @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
+
+<!-- What should happen? What should your screen reader announce? -->
+
+
+
+## Actual Behavior
+
+<!-- What actually happens? What does your screen reader announce (or not announce)? -->
+
+
+
+## Steps to Reproduce
+
+1.
+2.
+3.
+4. Result:
+
+## WCAG Success Criterion (if known)
+
+<!-- Which WCAG guideline does this violate? Leave blank if unsure. -->
+
+- [ ] 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
+
+<!-- Screenshots (with alt text), links to related issues, workarounds, or suggested fixes -->
+
+
+
+## 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 on GitHub
        2. +
      2. Click the Settings tab
        3. +
      3. Scroll to the "Features" section → click the checkmark next to "Issues" → click "Set up templates"
        4. +
      4. Or navigate directly to .github/ISSUE_TEMPLATE/ in your fork → click the + button → "Create new file"
        5. +
      5. GitHub opens a template editor. Fill in the template name, about description, and body
        6. +
      6. GitHub auto-populates the filename - you can change it
        7. +
      7. Click "Propose changes" → create a PR to add the template
        8. +
      +
      + +
      +Screen reader users (NVDA / JAWS / VoiceOver) + +
        +
      1. Navigate to your fork of accessibility-agents on GitHub
        2. +
      2. Go to the Settings tab (press T from the tabs landmark, then navigate to "Settings")
        3. +
      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. +

      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. +
      5. GitHub auto-populates the filename based on your template name
        6. +
      6. "Propose changes" → create a PR to add the template
        7. +
      +
      + +

      Creating Markdown Templates: The VS Code Workflow

      +
        +
      1. Open your accessibility-agents fork in VS Code
        2. +
      2. Navigate in Explorer to .github/ISSUE_TEMPLATE/
        3. +
      3. Create a new file: Ctrl+N → save as your-template-name.md in that folder
        4. +
      4. Add frontmatter first (between --- delimiters), then the body
        5. +
      5. Commit and push: open Source Control (Ctrl+Shift+G) → stage → commit → push
        6. +
      +

      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:

      +
      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)
        • +
      +
      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.

      +
      - 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.

      +
      - 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.

      +
      - 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.

      +
      - 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. +
      2. Press Down Arrow or Alt+Down to expand the dropdown
        3. +
      3. Up/Down Arrow to navigate options
        4. +
      4. Screen reader announces each option
        5. +
      5. Enter or Space to select
        6. +
      +

      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.

      +
      - 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. +
      2. Each checkbox announced as "I searched for existing issues, checkbox, not checked, required"
        3. +
      3. Screen reader users can check each box with Space
        4. +
      +

      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

      + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + +
      TypeBest ForKey AttributesValidationsScreen Reader Announced As
      markdownInstructions, warnings, explanationsvalueNoneRegular text content
      inputVersion numbers, URLs, short textlabel, placeholderrequired"Edit text" or "Edit"
      textareaDescriptions, steps, code, long textlabel, placeholder, renderrequired"Multi-line edit" or "Text area"
      dropdownOS, browser, severity, bounded choiceslabel, options, multiplerequired"Combo box" or "Pop-up button"
      checkboxesVerification lists, multiple selectionslabel, options with per-item requiredPer-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.

      +

      Full Template

      +

      Save this as .github/ISSUE_TEMPLATE/accessibility-bug.yml in your fork:

      +
      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:

      +
      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:

      +
      ## Description
+<!-- What does this PR add or fix? Why? -->
+
+## Type of Change
+- [ ] New agent
+- [ ] New slash command
+- [ ] Bug fix
+- [ ] Documentation improvement
+- [ ] Accessibility improvement
+- [ ] Other (describe below)
+
+## How to Test
+<!-- How can a reviewer verify this works correctly? -->
+
+## Accessibility Considerations
+<!-- Does this change affect screen reader output? WCAG compliance?
+     Keyboard navigation? If yes, describe what was tested. -->
+
+## Related Issues
+<!-- Use "Closes #N" to auto-close the issue when this PR is merged -->
      +

      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 <!-- comment --> 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. +
      2. Navigate to the community-access/accessibility-agents repository (or your fork)
        3. +
      3. Click the Issues tab (top navigation, between Pull Requests and Discussions)
        4. +
      4. You should see a list of existing issues
        5. +
      +
      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
        2. +
      +
      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. +
      2. The page displays available templates as buttons or links
        3. +
      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. +
      4. Count the templates and read their descriptions aloud (or write them down):
          +
        • Template 1: [name] - [description]
          • +
        • Template 2: [name] - [description]
          • +
        • And so on...
          • +
        +
        5. +
      +
      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. +
      2. Click it (or press Enter if focused with keyboard)
        3. +
      +
      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. +
      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. +
      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. +
      4. Write down at least 3 fields and whether each is required:
          +
        • Field: [name] - Required? [Yes/No]
          • +
        +
        5. +
      +

      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. +
      2. For required fields marked with *: Fill them in completely
        3. +
      3. For optional fields: Choose at least one and fill it in (so you test optional fields)
        4. +
      4. Don't worry about filling in every field - the point is to test the form
        5. +
      +
      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. +
      2. Click it (or press the hotkey shown)
        3. +
      3. A preview pane appears showing how the issue will look when published
        4. +
      +
      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. +
      2. Locate the green "New issue" button (usually at the bottom of the form)
        3. +
      3. With keyboard: Press Tab until the button is focused, then Enter
        4. +
      4. With mouse: Click the button
        5. +
      5. The issue is submitted and you see the new issue page with your content
        6. +
      +
      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. +
      2. Screen Reader Accessibility: Were all field labels announced clearly? Did you encounter any accessibility barriers?
        3. +
      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. +
      4. Context Helpfulness: Did the placeholder text or help text under each field make you understand what information to provide?
        5. +
      +

      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 (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. +
      2. Navigate to a folder where you want to store the project:

        +
        cd ~/projects
        +

        (Or wherever you keep code projects)

        3. +
      3. Clone your fork:

        +
        git clone https://github.com/[YOUR-USERNAME]/accessibility-agents.git
        +

        Replace [YOUR-USERNAME] with your actual GitHub username

        4. +
      4. Wait for the clone to complete (should take 10-30 seconds)
        5. +

      5. Navigate into the folder:

        +
        cd accessibility-agents
        +
        6. +
      +
      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)
        • +
      +

      Step 2: Open Your Fork in VS Code

      +
      What to do
      +
        +

      1. From the terminal, while in your accessibility-agents folder, type:

        +
        code .
        +
        2. +
      2. Press Enter
        3. +
      3. VS Code opens with your fork loaded
        4. +
      +
      What you should see
      + +
      If code . doesn't work
      + +

      Step 3: Navigate to the Templates Folder

      +
      What to do
      +
        +
      1. In VS Code's file tree (left sidebar), expand the .github folder
        2. +
      2. Inside, find and expand the ISSUE_TEMPLATE folder
        3. +
      3. You should see existing template files (like bug-report-template.yml or similar)
        4. +
      +
      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. +
      2. Select New File
        3. +
      3. Name it: accessibility-bug.yml (exactly this name)
        4. +
      4. Press Enter
        5. +
      +
      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 in this curriculum
        2. +
      2. Find the complete YAML template code block (starting with name: and ending with the last field)
        3. +
      3. Select all the YAML code (use Ctrl+A on the webpage or manually select)
        4. +
      4. Copy it (Ctrl+C)
        5. +
      5. Go back to VS Code
        6. +
      6. Paste it into your new accessibility-bug.yml file (Ctrl+V)
        7. +
      +
      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. +
      2. Look at the bottom right of VS Code - you may see some notifications
        3. +
      3. Check if VS Code shows any red squiggly lines (indicating syntax errors)
        4. +
      +
      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. +
      2. Compare your file with Section 7's template - look for extra/missing spaces or colons
        3. +
      3. Make corrections and save again
        4. +
      +
      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. +
      2. You should be in the accessibility-agents folder already
        3. +

      3. Create a new branch for this change:

        +
        git checkout -b feat/add-accessibility-template
        +
        4. +

      4. Add the file to git:

        +
        git add .github/ISSUE_TEMPLATE/accessibility-bug.yml
        +
        5. +

      5. Commit with a message:

        +
        git commit -m "feat: add accessibility bug report template"
        +
        6. +

      6. Push to your fork:

        +
        git push origin feat/add-accessibility-template
        +
        7. +
      +
      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 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. +
      2. Go to your fork: https://github.com/[YOUR-USERNAME]/accessibility-agents
        3. +
      3. You should see a notification or purple bar saying "Compare & pull request" (your new branch)
        4. +
      4. But instead of opening a PR, click the Issues tab
        5. +
      5. Click New issue
        6. +
      6. You should now see your new template in the chooser: "Accessibility Bug Report"
        7. +
      7. Click it to open the form
        8. +
      +
      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. +
      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. +
      3. Answer:
          +
        • Did you encounter any accessibility barriers?
          • +
        • Would a screen reader user find this template easy to use?
          • +
        +
        4. +
      +

      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. +
      2. Add a title: feat: add accessibility bug report template
        3. +
      3. Add a description: This template guides contributors to report accessibility issues with clear fields for screen reader type, browser, and WCAG criteria.
        4. +
      4. Click Create pull request
        5. +
      5. Review your PR (using skills from Chapter 14!)
        6. +
      6. If satisfied, click Merge pull request to merge it into your fork's main branch
        7. +
      +
      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. +
      2. The file contains valid YAML (no red squiggles in VS Code)
        3. +
      3. The template is visible when you click "New issue" in your fork
        4. +
      4. You tested it with your screen reader and noted any issues
        5. +
      +

      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. +
      2. Click Issues → New issue
        3. +
      3. Verify your template appears and is named "Accessibility Bug Report"
        4. +
      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. +
      5. Don't submit this test issue - just close the tab
        6. +
      +
      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. +
      2. You should see a "Compare & pull request" button (or look for your feature branch)
        3. +
      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. +
      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. +
      5. Confirm this is correct - you're sending your branch to the upstream repository
        6. +
      +
      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
      +
      feat: add accessibility bug report template
      +
      Description
      +

      Write a clear description that explains what you're contributing:

      +
      ## 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. +
      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. +
      3. Keep it concise but thorough
        4. +
      +

      Step 4: Review Your PR Before Submitting

      +
      What to do
      +
        +
      1. Scroll down and preview your PR description as it will appear
        2. +
      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. +
      3. Make any corrections needed
        4. +
      4. Do not submit yet - continue to Step 5
        5. +
      +

      Step 5: Submit the PR

      +
      What to do
      +
        +
      1. Click the green "Create pull request" button
        2. +
      2. Your PR is now submitted to the upstream repository
        3. +
      3. You see a confirmation page showing your new PR number (e.g., "#42")
        4. +
      4. GitHub may automatically assign reviewers or run CI checks
        5. +
      +
      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. +
      2. Understand what changes they're requesting (or what they're praising!)
        3. +

      3. If changes are needed:

        +
          +
        • Go back to your fork in VS Code
          • +
        • Edit the accessibility-bug.yml file accordingly
          • +

        • Commit and push:

          +
          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. +

      4. Leave a reply comment on the PR:

        +
        Thanks for the feedback! I've made the changes you requested
+in commit [commit hash]. The template now includes [what you changed].
        +
        5. +
      5. Click Reply
        6. +
      +
      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. +
      2. Your template is now part of the community-access/accessibility-agents repository
        3. +
      3. Everyone who forks that repo will get your template
        4. +
      4. You can claim this as a real open source contribution
        5. +
      +
      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. +
      2. Your PR includes a clear description of what you're contributing
        3. +
      3. Your template is the only change in the PR (one file)
        4. +
      4. You addressed any feedback from maintainers
        5. +
      5. Your PR was merged (or is waiting for merge)
        6. +
      +
      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. +

      2. Write down the project name and briefly why chose it:

        +
        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]
        +
        3. +
      +
      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. +
      2. Read the last 5-10 issues (or all open issues if fewer)
        3. +

      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. +

      4. Write down 3-5 patterns:

        +
        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?]
        +
        5. +
      +
      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. +
      2. For each type, ask: "If someone reported this issue, what would I need to know?"
        3. +

      3. Write down:

        +
        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?"]
        +
        4. +
      +
      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. +

      2. For each issue type from Part 2, add 2-4 required fields:

        +

        Example for "Bug Report":

        + + + + + + + + + + + + + + + + + + + + + + + + + + + +
        FieldTypeWhy?Options
        Componentdropdown"I have 5 components; knowing which is affected saves triage time"Component A, B, C, D, E
        Steps to Reproducetextarea"I cannot fix what I cannot replicate"(free text)
        OSdropdown"Bugs are often OS-specific"Windows, macOS, Linux
        +
        3. +

      3. Write down at least 2 required fields:

        +
        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]
        +
        4. +
      +
      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. +

      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. +

      3. Write down at least 2 optional fields:

        +
        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. +

      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?
          • +
        +
        5. +
      +
      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. +
      2. Description (short help text)
        3. +
      3. Placeholder (example of what to type, for input/textarea fields)
        4. +
      +
      Examples
      +
      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
      +
      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. +

      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. +

      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. +

      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. +

      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?
          • +
        +
        6. +
      +
      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. +

      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. +

      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. +
      4. Refine your template based on their feedback
        5. +
      +

      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?

        +
        Field: [name]
+Debate: [why was this hard to decide?]
+Decision: [required / optional / removed]
+Reason: [what made you decide?]
        +
        2. +

      2. Trade-offs: You can't ask for everything without overwhelming reporters. What information did you choose not to ask for? Why?

        +
        Information I didn't include: [example]
+Why I chose not to ask: [explanation]
+Would I change this? [yes/no] + why
        +
        3. +

      3. Iteration: If you had user feedback (from Part 7), what did you learn?

        +
        Feedback: [what did your friend/colleague say?]
+Change you made: [how did you refine?]
+Why it helped: [what improved?]
        +
        4. +

      4. Real-world readiness: Would you actually deploy this template to a real project?

        +
        Readiness: Yes, I'm confident
+           Maybe, with more testing
+           No, I need to rethink some fields
+Next step: [what would you do next?]
        +
        5. +
      +
      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. +
      2. Can create and deploy templates yourself (Exercise B)
        3. +
      3. Know how to contribute upstream (Exercise C)
        4. +
      4. Can design templates with real thinking behind them (Exercise D)
        5. +
      +

      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

      +
      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

      + + + + + + + + + + + + + + + + + + + + + + + + + + + +
      ApproachTimeExpertiseError Rate
      Manual YAML15-20 minHigh (YAML syntax)Medium (typos, missing colons)
      Copy-Paste Example10-15 minMediumLow (if example is good)
      Agent-Guided2-3 minLow (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
      Back: Chapter 16: GitHub Copilot
      Related appendices: Appendix Q: GitHub Actions | Appendix C: Markdown Reference

      + +
      + + + + diff --git a/html/admin/qa-bundle/docs/18-fork-and-contribute.html b/html/admin/qa-bundle/docs/18-fork-and-contribute.html new file mode 100644 index 00000000..39292786 --- /dev/null +++ b/html/admin/qa-bundle/docs/18-fork-and-contribute.html @@ -0,0 +1,620 @@ + + + + + + + Fork and Contribute: The Open Source Workflow - GIT Going with GitHub + + + + + + + + +
      +

      Fork and Contribute: The Open Source Workflow

      +
      +

      Related appendices: Appendix E: Advanced Git | Appendix O: Branch Protection | Appendix D: Git Authentication +Authoritative sources: GitHub Docs: Fork a repo | GitHub Docs: Syncing a fork | Open Source Guides: How to Contribute

      +
      +
      +

      Day 2, Block 3 Material

      +

      This chapter teaches the complete fork-based contribution workflow from start to finish. You will fork a real repository, create a feature branch, make changes, push to your fork, and open a pull request against the upstream repository. This is the workflow used by millions of open source contributors every day, and it is the foundation for the capstone project in Chapter 20.

      +
      +

      Table of Contents

      +
        +
      1. What Is a Fork?
        2. +
      2. Fork vs Clone vs Branch
        3. +
      3. Step 1: Fork the Repository
        4. +
      4. Step 2: Clone Your Fork Locally
        5. +
      5. Step 3: Add the Upstream Remote
        6. +
      6. Step 4: Create a Feature Branch
        7. +
      7. Step 5: Make Your Changes
        8. +
      8. Step 6: Push to Your Fork
        9. +
      9. Step 7: Open a Pull Request
        10. +
      10. Step 8: Respond to Review Feedback
        11. +
      11. Keeping Your Fork in Sync
        12. +
      12. The Fork Workflow Checklist
        13. +
      13. If You Get Stuck
        14. +
      +
      +
      +

      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 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. +
      2. You make changes on your copy
        3. +
      3. You open a pull request asking the maintainers to merge your changes
        4. +
      +

      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.

      + + + + + + + + + + + + + + + + + + + + + + + + + + + +
      ConceptWhere it livesWhat it createsWhen to use it
      ForkGitHub.com (your account)A copy of the entire repository under your GitHub accountWhen you want to contribute to a repo you do not own
      CloneYour computerA local copy of any repository (yours or someone else's)When you want to work locally
      BranchInside any repository (local or remote)A named pointer to a specific commitWhen 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. +
      2. Clone your fork to your computer
        3. +
      3. Create a branch on your local clone for your specific change
        4. +
      4. Push the branch to your fork and open a PR to the upstream
        5. +
      +
      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. +
      2. Clone: click the green Code button > copy URL > paste into your local tool.
        3. +
      +

      VS Code Desktop:

      +
        +
      1. Fork on github.com first (browser required for forking).
        2. +
      2. Ctrl+Shift+P > Git: Clone > paste your fork's URL.
        3. +
      +

      GitHub Desktop:

      +
        +
      1. Fork on github.com first.
        2. +
      2. File > Clone Repository > select your fork from the GitHub.com tab.
        3. +
      +

      GitHub CLI (one command):

      +
      gh repo fork Community-Access/accessibility-agents --clone
+cd accessibility-agents
      +

      For this workshop, you will fork the Community-Access/accessibility-agents repository.

      +

      On GitHub.com

      +
        +
      1. Go to github.com/Community-Access/accessibility-agents.
        2. +
      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. +
      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. +
      4. Activate Create fork.
        5. +
      5. GitHub redirects you to your fork: github.com/your-username/accessibility-agents.
        6. +
      +

      You now have your own copy. The original repository at Community-Access/accessibility-agents is untouched.

      +

      Using GitHub CLI

      +
      gh repo fork Community-Access/accessibility-agents --clone=false
      +

      This creates the fork on GitHub without cloning it locally. We will clone in the next step.

      +
      +

      4. Step 2: Clone Your Fork Locally

      +

      Now download your fork to your computer so you can work on it.

      +

      Using VS Code

      +
        +
      1. Open VS Code.
        2. +
      2. Open the command palette: Ctrl+Shift+P (or Cmd+Shift+P).
        3. +
      3. Type "Git: Clone" and press Enter.
        4. +
      4. Paste your fork URL: https://github.com/your-username/accessibility-agents.git (replace your-username with your GitHub username).
        5. +
      5. Choose a folder (for example, Documents) and confirm.
        6. +
      6. When the clone finishes, VS Code offers to open the repository. Accept.
        7. +
      +

      Using the terminal

      +
      git clone https://github.com/your-username/accessibility-agents.git
+cd accessibility-agents
      +

      Using GitHub Desktop

      +
        +
      1. Open GitHub Desktop.
        2. +
      2. Go to File, then Clone repository.
        3. +
      3. Select the GitHub.com tab and find your-username/accessibility-agents.
        4. +
      4. Choose a local path and click Clone.
        5. +
      +

      Using GitHub CLI

      +
      gh repo clone your-username/accessibility-agents
+cd accessibility-agents
      +

      After cloning, your local repository has one remote called origin that points to your fork.

      +

      Learning Cards: Cloning Your Fork

      +
      +Screen reader users + +
        +
      • Use Ctrl+Shift+P then "Git: Clone" and paste your fork URL -- VS Code announces progress and opens the repository when done
        • +
      • After cloning, press Ctrl+Shift+E to open the Explorer and verify the file tree loaded correctly
        • +
      • Run git remote -v in the terminal (Ctrl+\``) to 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 for advanced remote and upstream management.

      +
      +

      Your clone knows about your fork (origin). It does not know about the original repository. You need to add it as a second remote called upstream.

      +

      Why this matters

      +

      Without the upstream remote, you cannot:

      +
        +
      • Pull new changes that other contributors make to the original repository
        • +
      • Keep your fork up to date
        • +
      • Verify your changes work with the latest code
        • +
      +

      Add the upstream remote

      +
      git remote add upstream https://github.com/Community-Access/accessibility-agents.git
      +

      Verify your remotes

      +
      git remote -v
      +

      You should see:

      +
      origin    https://github.com/your-username/accessibility-agents.git (fetch)
+origin    https://github.com/your-username/accessibility-agents.git (push)
+upstream  https://github.com/Community-Access/accessibility-agents.git (fetch)
+upstream  https://github.com/Community-Access/accessibility-agents.git (push)
      +

      Two remotes: origin (your fork) and upstream (the original).

      +
      +

      In VS Code: You can also add the remote using the command palette. Press Ctrl+Shift+P, type "Git: Add Remote," enter upstream as the name, and paste the upstream URL.

      +
      +
      +

      6. Step 4: Create a Feature Branch

      +

      Never work directly on the main branch of your fork. Always create a feature branch for each change. This keeps main clean and in sync with the upstream.

      +

      Create and switch to a new branch

      +
      git checkout -b agents/your-username-my-agent
      +

      The branch name agents/your-username-my-agent follows the workshop convention for Day 2 capstone branches. Replace your-username with your GitHub username and my-agent with a short name for your agent.

      +

      In VS Code

      +
        +
      1. Click the branch name in the bottom-left status bar (or press Ctrl+Shift+P and type "Git: Create Branch").
        2. +
      2. Type the branch name: agents/your-username-my-agent.
        3. +
      3. Press Enter. VS Code creates the branch and switches to it.
        4. +
      +

      In GitHub Desktop

      +
        +
      1. Click the Current Branch dropdown.
        2. +
      2. Click New Branch.
        3. +
      3. Type the branch name and click Create Branch.
        4. +
      +

      Verify you are on the new branch

      +
      git branch
      +

      The current branch has an asterisk (*) next to it.

      +
      +

      7. Step 5: Make Your Changes

      +

      Now you are on your feature branch and ready to work. For the capstone, you will create an agent file. For other contributions, you might edit documentation, fix a bug, or add a feature.

      +

      General principles for contributing

      +
        +
      • Keep changes focused. One branch, one purpose. If you want to make two unrelated changes, use two branches and two pull requests.
        • +
      • Follow the project's conventions. Look at existing files for patterns in naming, formatting, and structure.
        • +
      • Write meaningful commit messages. Describe what you changed and why. "Fix typo in README" is clear. "Update files" is not.
        • +
      +

      Stage and commit your changes

      +

      After editing:

      +
      git add your-file.md
+git commit -m "Add my-agent accessibility agent"
      +

      Or stage all changed files:

      +
      git add .
+git commit -m "Add my-agent accessibility agent"
      +

      In VS Code

      +
        +
      1. Open the Source Control panel: Ctrl+Shift+G (or Cmd+Shift+G).
        2. +
      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. +
      3. Type your commit message in the text field at the top.
        4. +
      4. Press Ctrl+Enter (or Cmd+Enter) to commit.
        5. +
      +

      Multiple commits are fine

      +

      You do not need to make all your changes in a single commit. In fact, smaller commits are better because they are easier to review and easier to revert if something goes wrong.

      +
      +

      8. Step 6: Push to Your Fork

      +

      Your commits are saved locally. Now push them to your fork on GitHub.

      +

      First push (new branch)

      +
      git push -u origin agents/your-username-my-agent
      +

      The -u flag sets up tracking so future pushes from this branch go to the right place automatically.

      +

      Subsequent pushes

      +
      git push
      +

      In VS Code

      +

      After committing, the Source Control panel shows a Sync Changes button (or a cloud icon with an up arrow). Click it to push.

      +

      Alternatively, use the command palette: Ctrl+Shift+P, type "Git: Push."

      +

      In GitHub Desktop

      +

      After committing, click the Push origin button in the top bar.

      +

      Verify on GitHub

      +

      After pushing, visit your fork on GitHub: github.com/your-username/accessibility-agents. You should see a banner saying "your-username-my-agent had recent pushes" with a Compare and pull request button.

      +
      +

      9. Step 7: Open a Pull Request

      +

      A pull request asks the upstream maintainers to merge your branch into their repository.

      +

      From the GitHub.com banner

      +
        +
      1. After pushing, GitHub shows a yellow banner on your fork with a Compare and pull request button. Click it.
        2. +
      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. +
      3. Write a descriptive title. Example: "Add document-contrast-checker agent."
        4. +
      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. +
      5. If the project has a PR template, fill in all the required sections.
        6. +
      6. Activate Create pull request.
        7. +
      +

      From the Pull Requests tab

      +
        +
      1. Go to the upstream repository: github.com/Community-Access/accessibility-agents.
        2. +
      2. Click the Pull requests tab.
        3. +
      3. Click New pull request.
        4. +
      4. Click compare across forks.
        5. +
      5. Set the head repository to your fork and the compare branch to your feature branch.
        6. +
      6. Click Create pull request and fill in the details.
        7. +
      +

      Using GitHub CLI

      +
      gh pr create --repo Community-Access/accessibility-agents --title "Add document-contrast-checker agent" --body "Description of what the agent does and why it is useful."
      +
      +

      Screen reader tip: The PR creation form is a standard web form. Navigate with Tab to move between fields. The title field and body field are <input> and <textarea> elements. The base and compare dropdowns use ARIA listbox patterns.

      +
      +

      Learning Cards: Opening a Pull Request

      +
      +Screen reader users + +
        +
      • The PR form has a title input and a body textarea -- Tab between them; your screen reader announces field labels
        • +
      • The base and compare branch dropdowns use ARIA listbox patterns -- press Down Arrow to open and select branches
        • +
      • After submitting, GitHub navigates to the new PR page; press h to jump by headings and find the "Files changed" section
        • +
      +
      + +
      +Low vision users + +
        +
      • The "Compare and pull request" yellow banner appears at the top of your fork page after pushing -- it is a large, visible button
        • +
      • Use browser zoom (Ctrl+=) to enlarge the PR creation form if the text inputs are too small
        • +
      • The base and head repository/branch selectors appear near the top of the form -- verify these before submitting
        • +
      +
      + +
      +Sighted users + +
        +
      • After pushing, look for the yellow "Compare and pull request" banner at the top of your fork's GitHub page
        • +
      • Verify the base repository and branch (upstream/main) and head repository (your fork) are correct in the dropdown selectors
        • +
      • The PR creation form preview tab shows how your Markdown description will render -- check it before submitting
        • +
      +
      + +
      +

      10. Step 8: Respond to Review Feedback

      +

      After you open a pull request, maintainers and peers will review your changes. They may:

      +
        +
      • Approve - your PR is ready to merge
        • +
      • Request changes - you need to update your PR
        • +
      • Comment - ask questions or suggest improvements without formally requesting changes
        • +
      +

      How to respond to requested changes

      +
        +
      1. Read each review comment carefully. Understand what the reviewer is asking.
        2. +
      2. Make the requested changes in your local clone.
        3. +
      3. Stage, commit, and push:
        4. +
      +
      git add modified-file.md
+git commit -m "Address review feedback: improve guardrails section"
+git push
      +
        +
      1. Your new commits automatically appear in the open pull request. The reviewer is notified.
        2. +
      2. Reply to each review comment explaining what you changed, or ask clarifying questions if the feedback is unclear.
        3. +
      +

      Review etiquette

      +
        +
      • Thank the reviewer. They spent time reading your code.
        • +
      • Address every comment. Even if you disagree, explain your reasoning.
        • +
      • Do not take feedback personally. Review is about the code, not about you.
        • +
      • Ask questions. If you do not understand a comment, ask. Reviewers expect questions from new contributors.
        • +
      +
      +

      The Day 1 connection: You practiced code review in Chapter 15. The same principles apply here, but now you are on the other side -- receiving feedback instead of giving it.

      +
      +
      +

      11. Keeping Your Fork in Sync

      +

      Over time, other people's changes get merged into the upstream repository. Your fork does not update automatically. You need to sync it.

      +

      Sync from the command line

      +
      # Make sure you are on main
+git checkout main
+
+# Download the latest changes from upstream
+git fetch upstream
+
+# Merge upstream changes into your local main
+git merge upstream/main
+
+# Push the updated main to your fork
+git push origin main
      +

      Sync from GitHub.com

      +
        +
      1. Go to your fork on GitHub.
        2. +
      2. If your fork is behind the upstream, GitHub shows a banner: "This branch is X commits behind Community-Access:main."
        3. +
      3. Click Sync fork, then Update branch.
        4. +
      +

      Sync from GitHub CLI

      +
      gh repo sync your-username/accessibility-agents
      +

      When to sync

      +
        +
      • Before starting new work: Always sync before creating a new feature branch. This ensures your branch starts from the latest code.
        • +
      • Before opening a PR: Sync and merge main into your feature branch to check for conflicts before asking for review.
        • +
      • Periodically: If you are working on a long-running branch, sync weekly to avoid large conflicts.
        • +
      +

      Learning Cards: Keeping Your Fork in Sync

      +
      +Screen reader users + +
        +
      • Run git fetch upstream then git merge upstream/main in the terminal -- listen for "Already up to date" or a merge summary announcing new commits
        • +
      • Use git status after syncing to confirm your local main is not behind the upstream
        • +
      • On GitHub.com, the "Sync fork" button is near the top of your fork page; press Tab to reach it and Enter to activate
        • +
      +
      + +
      +Low vision users + +
        +
      • On GitHub.com, the "Sync fork" button appears below the repository description with a dropdown showing how many commits behind you are
        • +
      • After syncing, the Status Bar in VS Code shows no up/down arrows next to the branch name, confirming you are in sync
        • +
      • If a merge conflict occurs during sync, VS Code highlights conflicts with colored backgrounds (green = yours, blue = upstream)
        • +
      +
      + +
      +Sighted users + +
        +
      • On GitHub.com, look for the "Sync fork" button below the green Code button -- it shows "N commits behind" if your fork is out of date
        • +
      • Click "Update branch" in the dropdown to sync your fork with one click
        • +
      • In VS Code, the sync icon (circular arrows) next to the branch name in the Status Bar performs fetch + merge in one action
        • +
      +
      + +
      +

      12. The Fork Workflow Checklist

      +

      Use this checklist every time you contribute to a repository you do not own:

      +
        +
      • Fork the repository on GitHub
        • +
      • Clone your fork locally
        • +
      • Add the upstream remote (git remote add upstream URL)
        • +
      • Create a feature branch (git checkout -b branch-name)
        • +
      • Make your changes, stage, and commit
        • +
      • Push your branch to your fork (git push -u origin branch-name)
        • +
      • Open a pull request from your fork to the upstream
        • +
      • Respond to review feedback with additional commits
        • +
      • After merge, sync your fork (git fetch upstream && git merge upstream/main)
        • +
      • Delete the feature branch (locally and on your fork)
        • +
      +

      Cleaning up after merge

      +

      After your PR is merged, delete the feature branch:

      +
      # Delete the local branch
+git checkout main
+git branch -d agents/your-username-my-agent
+
+# Delete the remote branch on your fork
+git push origin --delete agents/your-username-my-agent
      +

      GitHub also offers a "Delete branch" button on the merged PR page.

      +
      +

      13. If You Get Stuck

      + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + +
      ProblemWhat to do
      Fork button is grayed outYou may not be signed in. Sign in to GitHub.com first.
      Clone fails with permission errorMake sure you are cloning your fork (your-username/repo), not the upstream. You do not have write access to the upstream.
      git remote -v shows only originRun git remote add upstream URL from Section 5.
      Push fails with "permission denied"You are probably trying to push to the upstream instead of your fork. Check git remote -v and push to origin.
      PR shows conflicts with mainSync your fork (Section 11), merge main into your branch, resolve conflicts, push again.
      Reviewer requested changes but I do not understandReply to the review comment with a question. Reviewers expect questions from new contributors.
      "Repository not found" when cloningDouble-check the URL. Make sure the fork exists under your account.
      Accidentally committed to main instead of a branchCheck Appendix E for how to move commits to a new branch.
      I finished but I am not sure I did it rightCompare your work against the Challenge 15 reference solution (for agent discovery) or the Challenge 16 reference solution (for the capstone). Your version does not need to match exactly.
      +
      +

      Next: Chapter 19: Accessibility Agents
      Back: Chapter 17: Issue Templates
      Related appendices: Appendix E: Advanced Git | Appendix O: Branch Protection

      + +
      + + + + diff --git a/html/admin/qa-bundle/docs/19-accessibility-agents.html b/html/admin/qa-bundle/docs/19-accessibility-agents.html new file mode 100644 index 00000000..1d45b50f --- /dev/null +++ b/html/admin/qa-bundle/docs/19-accessibility-agents.html @@ -0,0 +1,2452 @@ + + + + + + + Accessibility Agents - GIT Going with GitHub + + + + + + + + +
      +

      Accessibility Agents

      +
      +

      Listen to Episode 17: Accessibility Agents - a conversational audio overview of this chapter. Listen before reading to preview the concepts, or after to reinforce what you learned.

      +
      +
      +

      Related appendices: Appendix L: Agents Reference | Appendix K: Copilot Reference +Authoritative sources: GitHub Docs: Using extensions with Copilot | VS Code Docs: Chat participants

      +
      +

      55 AI Agents Across 3 Teams and 5 Platforms

      +
      +

      Day 2, Block 3 Material

      +

      Before you read this guide:

      +

      Accessibility Agents is a growing open source ecosystem: 55 AI-powered agents organized into three teams (Accessibility, GitHub Workflow, and Developer Tools), running on five platforms (GitHub Copilot, Claude Code, Gemini CLI, Claude Desktop, and Codex CLI). This chapter introduces the full landscape. Explore the agents that match your interests and workflows - there is no fixed subset you are required to use.

      +

      The agents are only useful if you have already done the work manually. An agent that summarizes issues is useless to someone who has never read an issue. An agent that reviews a diff is useless to someone who has never read a diff. The agent does not teach you the skill - it multiplies a skill you already have.

      +

      Day 1 built those skills. This chapter shows how to amplify them with automation - and how you can contribute new agents, improve existing ones, and shape the project's future.

      +
      +

      Prerequisites Checklist

      +

      Before starting this chapter, verify you have completed

      +

      Core Prerequisites (Required for All Agents)

      +
        +
      • Chapter 0: Pre-Workshop Setup - Git, VS Code, and GitHub account
        • +
      • Chapter 16: GitHub Copilot - GitHub Copilot Chat installed and working
        • +
      • GitHub Copilot access (Copilot Free tier is enough for this workshop)
        • +
      • .github/agents/ folder exists in your repository (or will create custom agents)
        • +
      +

      Agent Prerequisites (The "Skill First" Principle)

      +

      Every agent automates a skill you should already know by hand. Before using any agent, verify you have done the corresponding manual work. This table maps common agent categories to the skills they require:

      + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + +
      Agent CategoryYou Must Have Done FirstReference
      GitHub Workflow agents (@daily-briefing, @issue-tracker, @pr-review, @analytics)Navigated repositories, filed issues, reviewed PRs, explored InsightsCh 2, Ch 4, Ch 6
      Accessibility monitoring (@insiders-a11y-tracker)Filed an accessibility bug, applied WCAG labels, checked heading hierarchyCh 4, Ch 15
      Template creation (@template-builder)Designed a template manually, tested field typesCh 15
      Web accessibility auditing (@web-accessibility-wizard, @contrast-master, @keyboard-navigator, etc.)Understand WCAG success criteria, tested pages with a screen readerAppendix C
      Document accessibility (@word-accessibility, @pdf-accessibility, etc.)Reviewed a document for accessibility issues manuallyAppendix C
      +

      This is not an exhaustive list - it illustrates the principle. Before running any agent, ask yourself: could I do this task manually right now? If the answer is no, learn the manual skill first.

      +

      Estimated time for this chapter: 1.5 hours (including exercises)

      +

      Workshop Recommendation (Chapter 19 / Challenge 15)

      +

      Chapter 19 is the agent exploration and hands-on validation chapter - where students match agents to skills they already have and learn how to trust, evaluate, and improve AI-powered workflow automation. It supports Challenge 15: Meet the Agents.

      +
        +
      • Challenge count: 3 guided + 1-2 optional contribution challenges
        • +
      • Automation check: none (agent output requires human judgment before use)
        • +
      • Evidence: issue comment showing agent output and your evaluation of it
        • +
      • Pattern: explore, validate, read internals, optionally contribute
        • +
      • Key principle: Skill First, Agent Second - every agent requires manual prerequisite skills
        • +
      +

      Challenge 15 Set

      +
        +
      1. Agent Discovery Mapping - identify 3-5 agents that match skills you already have from Day 1.
        2. +
      2. Agent Skill Validation - run one agent and evaluate its output against your manual experience.
        3. +
      3. Agent Instructions Deep Dive - read one agent's source file and assess what it can and cannot do.
        4. +
      4. Improve an Existing Agent (optional hackathon) - find a gap in an agent's instructions and fix it via PR.
        5. +
      5. Propose a New Agent (optional hackathon) - file an issue proposing an agent for an uncovered workflow.
        6. +
      +

      Challenge 15.1 Step-by-Step: Agent Discovery Mapping

      +

      Goal: Map your Day 1 manual skills to specific agents in the ecosystem so you know which agents you are ready to use.

      +

      Where you are working: GitHub.com - the accessibility-agents repository and your assigned Challenge 15 issue.

      +

      Estimated time: 20 minutes.

      +

      If 55 agents feels too broad, start with this beginner sequence:

      +
        +
      • @daily-briefing (maps to repository and issue awareness from Chapters 2-4)
        • +
      • @issue-tracker (maps to Chapter 4 issue workflow)
        • +
      • @pr-review (maps to Chapter 6 and Chapter 14 review workflow)
        • +
      +
        +
      1. Fork the accessibility-agents repository on GitHub.com.
        2. +
      2. Open the repository and navigate to Section 3 of the README (or this chapter's Section 3 below) to see the full list of 55 agents organized by team.
        3. +
      3. Read through the agent names and descriptions. For each one, ask yourself: "Have I done this task manually during the workshop?"
        4. +
      4. Identify 3-5 agents that match workflows you already practiced:
          +
        • Example: You filed issues manually (Ch 4) - you can use @issue-tracker
          • +
        • Example: You reviewed a PR with diffs (Ch 6/14) - you can use @pr-review
          • +
        • Example: You checked colors for contrast - you can use @contrast-master
          • +
        +
        5. +
      5. Open your assigned Challenge 15 issue.
        6. +
      6. Post a discovery mapping comment using this format:
        7. +
      +
      Challenge 15.1 - Agent Discovery Mapping:
+
+Agent 1: @[agent-name]
+I am ready because I have already: [specific skill from Day 1]
+
+Agent 2: @[agent-name]
+I am ready because I have already: [specific skill from Day 1]
+
+Agent 3: @[agent-name]
+I am ready because I have already: [specific skill from Day 1]
      +

      You are done when: Your discovery mapping comment is posted with at least 3 agent-to-skill matches.

      +

      Challenge 15.2 Step-by-Step: Agent Skill Validation

      +

      Goal: Run one agent, read its output, and evaluate whether it matches your manual experience.

      +

      Where you are working: VS Code with the accessibility-agents repository cloned and Copilot Chat open.

      +

      Estimated time: 30 minutes.

      +
        +
      1. Clone your fork of accessibility-agents to VS Code (or open it in github.dev).
        2. +
      2. Open Copilot Chat: Ctrl+Shift+I (Mac: Cmd+Shift+I).
        3. +
      3. Choose one agent from your discovery list. If unsure, start with @daily-briefing or @issue-tracker.
        4. +
      4. Run it with a simple prompt. Examples:
          +
        • @daily-briefing morning briefing
          • +
        • @issue-tracker find open issues labeled good-first-issue in accessibility-agents
          • +
        • @pr-review show open PRs in accessibility-agents
          • +
        +
        5. +
      5. Read the agent's output carefully. Take a moment to think about what you expected.
        6. +
      6. Open your assigned Challenge 15 issue and post an evaluation comment:
        7. +
      +
      Challenge 15.2 - Agent Validation:
+
+Agent used: @[agent-name]
+Prompt: [exact prompt you used]
+
+What did the agent output? (2-3 sentences)
+[your answer]
+
+Does this match what you expected from manual experience?
+[your answer]
+
+Did the agent miss anything important that you would catch?
+[your answer]
      +

      You are done when: Your evaluation comment is posted with all three questions answered.

      +

      Challenge 15.3 Step-by-Step: Agent Instructions Deep Dive

      +

      Goal: Read one agent's source file to understand what instructions it follows, what tools it can use, and what mistakes it could make.

      +

      Where you are working: VS Code or GitHub.com - reading files in the accessibility-agents repository.

      +

      Estimated time: 15 minutes.

      +
        +
      1. In the accessibility-agents repository, navigate to the .github/ folder (or wherever agent definition files are stored).
        2. +
      2. Open one .agent.md or .prompt.md file for an agent you used or are curious about.
        3. +
      3. Read the file and identify:
          +
        • What is this agent trying to do? (its purpose)
          • +
        • What tools does it have access to? (tool permissions)
          • +
        • What constraints or guardrails are in the instructions?
          • +
        +
        4. +
      4. Think critically: could this agent make a mistake? What kind?
        5. +
      5. Open your assigned Challenge 15 issue and post your analysis:
        6. +
      +
      Challenge 15.3 - Agent Internals:
+
+Agent file: [filename]
+Purpose: [one sentence]
+Tools available: [list]
+Guardrails: [what constraints are in the instructions]
+Could it make a mistake? [your answer and what kind]
      +

      You are done when: Your analysis comment is posted.

      +

      Optional Extensions 15.4-15.5 (Hackathon)

      +

      Extension 15.4: Improve an Existing Agent (45 min)

      +
        +
      • Find an agent whose instructions have a gap (use Section 6 suggestions or file an issue).
        • +
      • Fork the repo, edit the agent's .agent.md file.
        • +
      • Get a facilitator review.
        • +
      • Open a PR with your improvement.
        • +
      • Evidence: your merged PR.
        • +
      +

      Extension 15.5: Propose a New Agent (60 min)

      +
        +
      • Identify a workflow not yet covered by any of the 55 agents.
        • +
      • File an issue describing what the agent should do and why it matters.
        • +
      • Include 3 example prompts people would use.
        • +
      • Evidence: your issue with facilitator/maintainer discussion.
        • +
      +

      Completing Challenge 15: Submit Your Evidence

      +

      Your evidence is the Challenge 15 issue comments for 15.1, 15.2, and 15.3. For optional extensions, your PR or proposal issue is the evidence.

      +

      Expected Outcomes

      +
        +
      • Student can map personal Day 1 skills to specific agents in the ecosystem.
        • +
      • Student understands the Skill First, Agent Second principle and can articulate why agent output requires human judgment.
        • +
      • Student can read agent instructions and evaluate what an agent can and cannot do.
        • +
      • Student has used at least one agent and verified it against manual skills.
        • +
      • (Optional) Student has contributed to the accessibility-agents ecosystem with a fix, improvement, or proposal.
        • +
      +

      If You Get Stuck

      +
        +
      1. Cannot find an agent that matches your skills? Start with @daily-briefing or @issue-tracker - those build directly on Chapter 2-5 material. If you have not done those manual steps yet, go back to those chapters first.
        2. +
      2. Agent output does not make sense? That is the right response. Paste the output in an issue comment along with your confusion. That is valuable feedback - the agent may need better instructions or guardrails.
        3. +
      3. Cannot access the agents in Copilot Chat? Verify: Is Copilot Chat extension installed (not just base Copilot)? Are you signed in to GitHub in VS Code? Does .github/agents/ folder exist in your cloned repository?
        4. +
      4. Repository will not clone? Use the terminal: git clone https://github.com/[your-username]/accessibility-agents.git then open the folder in VS Code.
        5. +
      5. Ask facilitator to show them what agent you wanted to run, what output you got, and what you expected.
        6. +
      6. Finished but not sure you did it right? Compare your work against the Challenge 15 reference solution.
        7. +
      +
      +

      Continue learning: The GitHub Skills courses Build Applications with Copilot Agent Mode and Expand Your Team with Copilot explore agent-powered development workflows. See Appendix Z for the full catalog.

      +
      +

      Learning Moment

      +

      The 55 agents exist because someone did the manual work first, then automated the repetitive parts. As you explore agents, you are not just learning tools - you are learning what automation looks like when it is built on real expertise and real constraints. That is the foundation for contributing back: you already know the limits of automation because you have done the work by hand.

      +

      Learning Pattern Used in This Chapter

      +
        +
      1. Map your existing skills to available tools (discovery before action).
        2. +
      2. Run one tool and evaluate its output critically (trust but verify).
        3. +
      3. Read the source to understand capabilities and limits (internals matter).
        4. +
      4. Contribute improvements based on your evaluation (close the feedback loop).
        5. +
      +

      Capstone: Share Your Feedback (The Most Important Task!)

      +

      You have now explored the full agent ecosystem, completed the workshop, and have valuable perspective on what worked, what confused you, and what we should improve for the next cohort.

      +

      Your feedback directly shapes the future of this project. We read every response, discuss improvements, and act on suggestions.

      +

      Submit Workshop Feedback

      +

      File a Feedback Issue →

      +

      Use the Workshop Feedback form to share:

      +
        +
      • Which agents stood out? (Most useful or surprising)
        • +
      • Which agents confused you? (What would make them better)
        • +
      • Was the chapter progression logical? (Did earlier chapters prepare you for later ones)
        • +
      • Accessibility experience (If applicable - did any assistive technology work/fail?)
        • +
      • Best takeaway (What will you remember in 6 months)
        • +
      • What should we improve? (Honest feedback, not graded)
        • +
      • Anything else? (Facilitator appreciation, wild ideas, whatever matters to you)
        • +
      +

      Answer as much or as little as you're comfortable sharing. Even one thoughtful answer is valuable. This feedback becomes part of our workshop archive and roadmap for future cohorts.

      +

      Your honest perspective is how this project improves. Thank you for being part of building a more accessible technical future.

      +

      Table of Contents

      +
        +
      1. The Principle: Skill First, Agent Second
        2. +
      2. Setup and Configuration
        3. +
      3. The Ecosystem: 55 Agents, 3 Teams, 5 Platforms
        4. +
      4. Agents in Detail - Hands-On Reference
        5. +
      5. Slash Commands and Prompts
        6. +
      6. Contributing to the Ecosystem
        7. +
      7. The Bigger Picture: Teams, Orchestration, and Beyond VS Code
        8. +
      8. GitHub Desktop, GitHub CLI, and Copilot CLI
        9. +
      +

      1. The Principle: Skill First, Agent Second

      +

      Accessibility Agents is not a way to skip learning GitHub. It is a way to amplify skills you have already built through deliberate practice.

      +

      The ecosystem includes 55 agents across three specialized teams, running on five different AI platforms. That scale makes this principle critical: every agent automates a sequence of steps you should already know how to do manually. If you do not know those steps by hand, you cannot:

      +
        +
      • Verify that the agent's output is correct
        • +
      • Catch when the agent misses context that only you have
        • +
      • Edit the agent's drafts into something worth posting under your name
        • +
      • Know when the agent is confidently wrong
        • +
      +

      Every agent has a manual prerequisite. If you have not done the corresponding skill by hand, the agent is not ready for you yet - and you are not ready for it

      +

      This applies across all three teams and all 55 agents:

      +
        +
      • GitHub Workflow agents automate repository navigation, issue triage, PR review, and contribution analytics - skills you practiced on Day 1
        • +
      • Accessibility agents automate WCAG auditing, contrast checking, keyboard navigation review, and document scanning - knowledge from your accessibility training and the standards in Appendix C
        • +
      • Developer Tools agents automate accessible coding patterns for Python, wxPython, and desktop applications - skills from your development experience
        • +
      +

      Before running any agent, the facilitator asks the same question:

      +
      +

      "What would you do if you had to do this step manually right now?"

      +
      +

      That question is not rhetorical. Answer it before running the agent. If you cannot answer it, learn the manual skill first.

      +
      +

      Exploration prompt: As you browse the full agent ecosystem, identify which agents match workflows you already do by hand. Those are your starting points. On Day 2, you will also have the opportunity to contribute improvements, new patterns, or entirely new agents back to the project.

      +
      +

      Learning Cards: Skill First, Agent Second

      +
      +Screen reader users + +
        +
      • Before using any agent, verify you can do the task manually -- for @daily-briefing, confirm you can navigate Issues and PRs on GitHub.com with keyboard shortcuts (j/k to move, Enter to open)
        • +
      • Agent output appears in Copilot Chat -- press Alt+F2 to open Accessible View and read the full response with arrow keys before acting on it
        • +
      • If an agent produces something you do not understand, stop and learn the manual skill first from the relevant chapter
        • +
      +
      + +
      +Low vision users + +
        +
      • Agent responses appear in the Copilot Chat panel -- drag the panel wider or use Alt+F2 (Accessible View) for a larger, cleaner reading pane
        • +
      • Each agent's instructions are in a .agent.md file you can open in VS Code and read at your preferred zoom level before invoking the agent
        • +
      • The agent ecosystem table in Section 3 uses standard Markdown tables that scale with your editor font size
        • +
      +
      + +
      +Sighted users + +
        +
      • Each agent has a descriptive name prefixed with @ -- look for the agent file in .github/agents/ in the Explorer sidebar to read its full instructions before using it
        • +
      • Agent responses appear in the Copilot Chat panel on the right; code blocks have Copy and Insert buttons for quick use
        • +
      • The three-team organization (GitHub Workflow, Accessibility, Developer Tools) maps to different colored badge labels in the agent table
        • +
      +
      + + +

      2. Setup and Configuration

      +

      Quick Install (One Command)

      +

      Accessibility Agents now ships with a one-liner installer that sets up all 55 agents for your platform:

      +

      macOS / Linux

      +
      curl -fsSL https://raw.githubusercontent.com/Community-Access/accessibility-agents/main/install.sh | bash
      +

      Windows (PowerShell)

      +
      irm https://raw.githubusercontent.com/Community-Access/accessibility-agents/main/install.ps1 | iex
      +

      The installer detects which AI tools you have installed (VS Code with Copilot, Claude Code, Gemini CLI, Claude Desktop, Codex CLI) and configures the appropriate agent files for each platform. To uninstall, run the corresponding uninstall script from the repository.

      +

      Workshop Setup (Fork and Clone)

      +

      For the workshop, you will also fork and clone the repository so you can make contributions:

      +
        +
      1. Fork accessibility-agents to your GitHub account (you did this on Day 1 or Day 2 morning)
        2. +

      2. Clone your fork:

        +
        git clone https://github.com/[your-username]/accessibility-agents.git
        +
        3. +
      3. Open in VS Code: navigate to the folder and run code . (or File, then Open Folder)
        4. +
      4. Open Copilot Chat: Ctrl+Shift+I
        5. +
      5. Test: type @daily-briefing morning briefing and press Enter
        6. +
      +

      No API keys. No configuration files. The installer handles everything. If Copilot Chat works, the agents work.

      +

      Prerequisites

      +
        +
      • GitHub Copilot Chat extension installed (see GitHub Copilot: Installation)
        • +
      • Signed in to GitHub via VS Code
        • +
      • A workspace open containing .github/agents/ folder with .agent.md files
        • +
      +

      How Agents Are Discovered

      +

      When you type @ in Copilot Chat, VS Code scans:

      +
        +
      1. .github/agents/*.agent.md in your current workspace
        2. +
      2. Any agents installed globally on your machine
        3. +
      3. Agents defined by extensions
        4. +
      +

      The Accessibility Agents ecosystem installs agents appropriate to each platform:

      + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + +
      PlatformAgent FormatHow Agents Load
      GitHub Copilot (VS Code).github/agents/*.agent.mdAuto-discovered when workspace is open
      Claude CodePer-agent CLAUDE.md files + hook enforcementLoaded via .claude/ configuration
      Gemini CLIGemini skill filesLoaded via gemini configuration
      Claude DesktopMCP server integrationConfigured via Claude Desktop settings
      Codex CLICodex agent filesLoaded via codex configuration
      +

      For this workshop, we focus on GitHub Copilot in VS Code. The same 55 agent personalities are available on all five platforms.

      +

      Optional: Personalize Your Instance

      +

      Copy the example preferences file:

      +
      cp .github/agents/preferences.example.md .github/agents/preferences.md
      +

      Open preferences.md in VS Code and edit:

      +
      # My Accessibility Agents Preferences
+
+## My GitHub Username
+[your-username]
+
+## Repositories I Work On Most
+- [your-org]/[your-repo]
+- community-access/accessibility-agents
+
+## Preferred Output Format
+Long-form with sections and headings (screen reader optimized)
+
+## Notification Priority
+Accessibility issues first, then review requests, then CI failures
      +

      Commit preferences.md to your fork. Now the agents know who you are and what you care about most.

      +

      Note: preferences.md is in .gitignore in the upstream repo - your personal preferences will not be included if you submit a PR. They stay in your fork only.

      +

      How Agents Travel with Your Repo

      +

      When you fork accessibility-agents, the .github/agents/ folder comes with it. This means:

      +
        +
      • Any collaborator who clones your fork gets all 55 agents automatically
        • +
      • You can customize agents for your specific project by editing the .agent.md files in your fork
        • +
      • Any project can have agents - create a .github/agents/ folder in any repository and add .agent.md files using the same pattern
        • +
      • The one-liner installer can also set up agents globally, so they are available in every workspace you open
        • +
      +

      Invoking Agents on GitHub.com

      +

      Accessibility Agents agents run in VS Code. But the same .agent.md files can also be invoked directly on GitHub.com - no VS Code, no local clone required.

      +

      Option 1: Copilot Chat with Task mode

      +
      +Visual / mouse users + +
        +
      1. Open Copilot Chat on GitHub.com (icon in the top-right navigation bar)
        2. +
      2. Click Task in the mode picker
        3. +
      3. Optionally click the agent picker to select a custom agent
        4. +
      4. Type your request and click Send
        5. +
      5. Copilot analyzes the task and can create a branch and open a PR automatically
        6. +
      +
      + +
      +Screen reader users (NVDA / JAWS / VoiceOver) + +
        +
      1. Open Copilot Chat on GitHub.com (navigate to icon in top-right navigation → Enter)
        2. +
      2. The mode picker (Task vs Chat) is a set of radio buttons - navigate with Arrow keys to select "Task"
        3. +
      3. The agent picker is a listbox - Up/Down Arrow to navigate, Enter to select
        4. +
      4. Type your request in the chat input and press Enter
        5. +
      5. Copilot response appears in the chat thread; press H to navigate to the response heading
        6. +
      +
      + +

      Option 2: Assign an issue to Copilot

      +
      +Visual / mouse users + +
        +
      1. Open any issue (or create a new one describing the task)
        2. +
      2. In the Assignees sidebar section, click the gear icon
        3. +
      3. In the dropdown, click Copilot as the assignee
        4. +
      4. A dialog opens - optionally provide additional instructions and select a custom agent
        5. +
      5. Click Assign to confirm
        6. +
      +
      + +
      +Screen reader users (NVDA / JAWS / VoiceOver) + +
        +
      1. Open any issue in the repository
        2. +
      2. Press B to navigate to the Assignees gear button → Enter to open the popup
        3. +
      3. Navigate the popup with Arrow keys → find "Copilot" → Enter to select
        4. +
      4. A dialog opens with instruction text area and agent picker - fill as needed
        5. +
      5. Tab to the Assign button → Enter
        6. +
      +
      + +

      This is the bridge to Section 6 (The Cloud Extension). The same agent file, three execution contexts: your editor, GitHub.com interactively, and GitHub Actions on a schedule.

      +

      Copilot on GitHub.com - Browser-Native Features

      +

      Beyond assigning Copilot to issues and using Task mode in Chat, GitHub.com now has several standalone Copilot features built directly into the web interface. These work entirely in your browser - no VS Code, no local clone needed.

      +

      Copilot PR Summary

      +

      On any open pull request, GitHub adds a "Summarize" button in the PR description area. Selecting it generates a plain-language summary of what the PR changes, why, and what reviewers should focus on.

      +

      When to use it: Before doing a full accessible diff review (Chapter 14), read the Copilot summary first to orient yourself. This is especially helpful with large PRs.

      +
      +Visual / mouse users + +

      On any open PR page, look for a "Summarize" or "Copilot summary" button near the PR description area. Click it. The summary renders within a few seconds as a new section in the PR description.

      +
      + +
      +Screen reader users (NVDA / JAWS) + +
      On any PR page:
+B → navigate buttons → find "Summarize" or "Copilot summary" button → Enter
+Wait for the summary to render (usually 5-10 seconds)
+Copilot summary appears as a new blockquote or section above/below the description
+H or 2 → navigate to the summary heading to read it
      +
      + +

      Copilot PR Review

      +

      On open PRs you have write access to review, a "Review" button (or Copilot icon) appears in the Files changed tab. Copilot generates inline review comments across the diff.

      +

      When to use it: As a starting point for a code review. Always read the Copilot-generated comments critically before adopting them - Copilot can miss context that a human reviewer would catch.

      +

      Copilot in Issues

      +

      On any issue page, Copilot adds sidebar buttons that appear once the page loads:

      +
        +
      • "Explain this issue" - generates a plain-language explanation of a complex technical issue
        • +
      • "Suggest fix" - proposes an approach to resolving the issue (opens a task/PR workflow)
        • +
      +
      +Visual / mouse users + +

      Look in the right sidebar on any issue page for a Copilot section with "Explain" and "Suggest fix" buttons. Click the button you want; the response appears below it in the sidebar.

      +
      + +
      +Screen reader users (NVDA / JAWS) + +
      On any issue page:
+H or 2 → navigate to "Copilot" section heading in the sidebar
+B → activate "Explain" or "Suggest fix" button
+Copilot response appears below the button; use H to navigate to it
      +
      + +

      GitHub Models - Free AI Playground

      +

      github.com/marketplace/models is a free playground where you can test AI models (OpenAI GPT-4o, Meta Llama 3, Mistral, Phi-4 Mini, and others) directly in your browser.

      +
      What you can do
      +
        +
      • Send prompts to any listed model and compare responses side by side
        • +
      • Adjust parameters (temperature, max tokens) without any setup
        • +
      • Use the code sample generator to get API code for your chosen model
        • +
      • All free with a GitHub account (rate-limited for free tier)
        • +
      +

      Why it matters for Accessibility Agents: When you build custom agents and prompts, you can test your system prompts and prompt templates in GitHub Models before adding them to your .prompt.md files - rapid iteration without burning API credits.

      +
      +Visual / mouse users + +

      Navigate to github.com/marketplace/models. Browse model cards and click one to open the chat playground. Type in the prompt field and press Send. Results appear in the response area.

      +
      + +
      +Screen reader users (NVDA / JAWS) + +
      Navigate to https://github.com/marketplace/models
+H → "Models" h1, then model category headings
+Links → navigate to individual model cards
+Enter on a model card → opens the chat playground
+In the playground: E or F → navigate to the prompt textarea → NVDA+Space (Focus Mode) → type prompt → Enter to submit
+Response appears below the Send button; use H to find the response section heading
      +
      + +

      Copilot-Drafted Release Notes

      +

      When creating a release (Releases tab → Draft a new release), GitHub provides a "Generate release notes" button. It scans merged PRs since the last release and drafts categorized release notes automatically.

      +

      This directly connects to the /draft-release slash command in Accessibility Agents - use the browser button for one-click generation, or use the agent when you want to customize the structure and add narrative context.

      +

      Learning Cards: Setup and Configuration

      +
      +Screen reader users + +
        +
      • Run the installer command in the VS Code terminal (Ctrl+\``) -- it announces progress as it copies agent files to .github/agents/`
        • +
      • After installation, press Ctrl+Shift+E to open the Explorer and navigate to .github/agents/ to verify agent files are present
        • +
      • Edit .github/agents/preferences.md to configure your username, repositories, and notification preferences -- it is a standard Markdown file
        • +
      +
      + +
      +Low vision users + +
        +
      • The installer creates files in .github/agents/ and .github/prompts/ -- verify in the Explorer sidebar that these folders appeared
        • +
      • Open preferences.md in the editor to set your configuration -- use Ctrl+= to zoom if the YAML frontmatter is hard to read
        • +
      • Agent files use .agent.md extension -- they appear alongside regular Markdown files in the Explorer but are distinguished by their extension
        • +
      +
      + +
      +Sighted users + +
        +
      • After installation, two new folders appear in .github/: agents/ (55 .agent.md files) and prompts/ (54+ .prompt.md files)
        • +
      • Open preferences.md to customize your settings -- it controls which repositories agents query and how results are formatted
        • +
      • The agent files are readable Markdown documents -- open any one to see its instructions, responsibilities, and guardrails
        • +
      +
      + + +

      3. The Ecosystem: 55 Agents, 3 Teams, 5 Platforms

      +

      Accessibility Agents is an ecosystem of 55 specialized agents organized into three teams, each addressing a different dimension of accessible software development. Browse all three teams below, then choose the agents that match your current skills and interests.

      +

      Team 1: Accessibility (26 agents)

      +

      These agents audit, fix, and enforce accessibility across web, document, and mobile platforms.

      + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + +
      AgentWhat It Does
      @accessibility-leadOrchestrates multi-agent accessibility audits; delegates to specialists
      @aria-specialistARIA roles, states, properties, and widget patterns
      @modal-specialistDialog focus trapping, escape behavior, screen reader announcements
      @contrast-masterColor contrast ratios, focus indicators, visual presentation
      @keyboard-navigatorTab order, focus management, keyboard shortcuts, skip links
      @live-region-controllerLive region announcements, dynamic content updates, toast notifications
      @forms-specialistForm labels, error handling, validation, autocomplete, field grouping
      @alt-text-headingsAlt text quality, heading hierarchy, document outline, landmarks
      @tables-specialistTable markup, scope, caption, headers, sortable columns, ARIA grid
      @link-checkerLink text quality, ambiguous links, WCAG 2.4.4 and 2.4.9 compliance
      @web-accessibility-wizardFull guided WCAG audit with severity scoring and remediation tracking
      @testing-coachScreen reader testing guidance (NVDA, JAWS, VoiceOver), automated test setup
      @wcag-guideWCAG 2.2 AA reference, success criteria explanations, conformance guidance
      @word-accessibilityMicrosoft Word document accessibility auditing
      @excel-accessibilityMicrosoft Excel spreadsheet accessibility auditing
      @powerpoint-accessibilityMicrosoft PowerPoint presentation accessibility auditing
      @office-scan-configOffice document scan configuration and rule management
      @pdf-accessibilityPDF accessibility auditing (PDF/UA, tagged PDF structure)
      @pdf-scan-configPDF scan configuration and rule management
      @document-accessibility-wizardGuided document audit wizard (Word, Excel, PowerPoint, PDF)
      @cognitive-accessibilityCognitive accessibility patterns, plain language, reading level
      @mobile-accessibilityMobile accessibility (iOS VoiceOver, Android TalkBack)
      @design-system-auditorDesign system component accessibility review
      @markdown-a11y-assistantMarkdown accessibility (headings, links, alt text, tables, emoji)
      @epub-accessibilityePub/digital publication accessibility auditing
      @epub-scan-configePub scan configuration and rule management
      +

      Team 2: GitHub Workflow (12 agents)

      +

      These agents automate GitHub operations - issue triage, PR review, contribution analytics, and repository management.

      + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + +
      AgentWhat It Does
      @daily-briefingMorning situation report across all repositories
      @issue-trackerFind, prioritize, triage, and draft replies to issues
      @pr-reviewGenerate structured PR reviews with risk assessment
      @analyticsContribution velocity, review turnaround, code hotspots
      @insiders-a11y-trackerMonitor accessibility-sensitive changes in repositories
      @template-builderInteractive issue template wizard via Ask Questions
      @github-hubCentral hub for all GitHub operations
      @repo-adminRepository settings, branch protection, rulesets
      @team-managerTeam membership, permissions, and organization management
      @contributions-hubContribution tracking and contributor recognition
      @repo-managerMulti-repository operations and cross-repo workflows
      @nexusCross-agent orchestration and workflow coordination
      +

      Team 3: Developer Tools (6 agents)

      +

      These agents support accessible application development across desktop and cross-platform frameworks.

      + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + +
      AgentWhat It Does
      @developer-hubCentral hub for developer tool operations
      @python-specialistPython accessibility patterns and best practices
      @wxpython-specialistwxPython GUI accessibility implementation
      @desktop-a11y-specialistDesktop application accessibility (Windows, macOS, Linux)
      @desktop-a11y-testing-coachDesktop accessibility testing guidance and automation
      @a11y-tool-builderBuild custom accessibility testing tools and utilities
      +

      Beyond Agents: The Supporting Ecosystem

      +

      The 55 agents are backed by additional resources in the repository:

      + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + +
      ResourceCountPurpose
      Copilot prompts (.prompt.md)54+Single-task slash commands invoked with /command
      Copilot skills (SKILL.md)17Multi-step workflows with bundled scripts and reference files
      Copilot instructions (.instructions.md)6Always-on coding standards (accessibility, markdown, semantic HTML, ARIA)
      Claude Code hooks3Proactive detection, edit gate, session marker - enforcement without prompting
      Example violations20+Intentional accessibility issues in example/ for practice
      +

      Hook-Based Enforcement (Claude Code)

      +

      On Claude Code, Accessibility Agents includes a hook system that enforces accessibility standards automatically:

      +
        +
      1. Proactive detection hook - scans every file edit for accessibility regressions before they are committed
        2. +
      2. Edit gate hook - blocks commits that introduce WCAG violations until they are fixed
        3. +
      3. Session marker hook - tracks which accessibility checks have run during the current session
        4. +
      +

      This means accessibility enforcement happens whether or not the developer remembers to ask for it. The hooks run as part of the Claude Code lifecycle, not as an afterthought.

      +

      What Would You Build?

      +

      This is the question that matters most. The 55 agents that exist today were built by contributors who saw a gap and filled it. The ecosystem grows when someone asks:

      +
        +
      • "Why is there no agent for [framework] accessibility patterns?"
        • +
      • "I spend 30 minutes on [task] every week - could an agent do the repetitive part?"
        • +
      • "This agent is good but it misses [specific edge case] - I could improve those instructions"
        • +
      • "Mobile native accessibility testing has no agent coverage yet - I could start one"
        • +
      +

      The contribution paths are

      +
        +
      1. Report an agent gap - file an issue describing what is missing and why it matters
        2. +
      2. Improve existing agent instructions - make an agent smarter about edge cases it misses
        3. +
      3. Add framework-specific patterns - teach agents about React, Vue, Angular, Svelte, or other framework accessibility patterns
        4. +
      4. Fix installer issues - improve the one-liner scripts for different OS configurations
        5. +
      5. Write documentation - help others understand how to use and contribute to agents
        6. +
      +

      See the Accessibility Agents CONTRIBUTING guide for detailed instructions on each path.

      +

      Roadmap: What Is Coming Next

      +

      The project roadmap includes:

      +
        +
      • Mobile native agents - agents specialized for iOS (VoiceOver) and Android (TalkBack) native app accessibility
        • +
      • Anthropic Connectors listing - making agents discoverable through the Anthropic marketplace
        • +
      • veraPDF integration - automated PDF/UA validation for the PDF accessibility agent
        • +
      • Document remediation agents - agents that fix accessibility issues in documents, not just find them
        • +
      • WCAG AAA agent - a specialized agent for AAA-level conformance (currently, agents target AA)
        • +
      • Multi-language support - agent instructions in languages beyond English
        • +
      +

      Your contribution could be the next item that ships. Every agent started as one person's idea and one pull request.

      +

      Learning Cards: The Agent Ecosystem

      +
      +Screen reader users + +
        +
      • The three team tables use standard Markdown table format -- navigate with T (NVDA/JAWS) to jump between tables, then Arrow keys to read cells
        • +
      • Agent names start with @ -- type @ followed by the agent name in Copilot Chat to invoke it (e.g., @daily-briefing)
        • +
      • Use Ctrl+Shift+O (symbol outline) in any agent file to navigate between its YAML frontmatter sections (Purpose, Responsibilities, Guardrails)
        • +
      +
      + +
      +Low vision users + +
        +
      • The agent tables are dense -- use Ctrl+= to increase font size or open the file in Markdown Preview (Ctrl+Shift+V) for cleaner rendering
        • +
      • Each team has a distinct table: Team 1 (Accessibility, 26 agents), Team 2 (GitHub Workflow, 15 agents), Team 3 (Developer Tools, 14 agents)
        • +
      • Agent files in .github/agents/ have descriptive filenames that match the @agent-name -- browse them in the Explorer to find specific agents
        • +
      +
      + +
      +Sighted users + +
        +
      • Browse the tables to find agents matching your interests -- the "What It Does" column gives a one-line summary of each agent's purpose
        • +
      • Agent names are clickable in Copilot Chat after typing @ -- start typing to fuzzy-match available agents
        • +
      • The three teams are visually separated by headings: Accessibility, GitHub Workflow, and Developer Tools
        • +
      +
      + + +

      4. Agents in Detail - Hands-On Reference

      +

      This section walks through several agents in depth so you can see how they work, what they produce, and how to evaluate their output. These examples use GitHub Workflow agents because they build directly on Day 1 skills - but the same patterns apply to every agent in the ecosystem. After working through these examples, explore agents from any team that match your interests.

      +

      Open any agent file in VS Code to read its full instructions: .github/agents/[name].agent.md

      +

      Two Types of Agents

      +

      Before diving in, it helps to know that custom agents fall into two categories - this distinction affects what tool permissions they need and what they can do:

      +

      Informational agents search, analyze, and report. They respond in chat without modifying files. Examples: @daily-briefing, @issue-tracker, @analytics. These agents need only read and search tools (like github/search_issues, github/issue_read) - they are safer to trust with broad repository access and are simpler to build.

      +

      Task-oriented agents take action. They can read and edit files, run shell commands, create commits, and open pull requests. Examples: @pr-review, @insiders-a11y-tracker. These agents need a broader toolset (read, edit, execute, github/*) - and because they can make changes, their output always warrants human review before anything is posted or merged.

      +

      Many agents do both - they explain what they found (informational) and optionally make changes if you ask (task-oriented). The key question when you build your own is: does this agent need to change files, or only to report? Start informational. Expand to task-oriented only when the reporting alone is not enough.

      +

      Agent 1: @daily-briefing - Morning Briefing

      +

      Type: Informational

      +

      File: .github/agents/daily-briefing.agent.md

      +

      Before you run this agent: You should have manually navigated a repository's Issues tab, read your GitHub Notifications page, understood what a pull request waiting for review looks like, and know the difference between subscribed and participating notifications. If those steps are not familiar yet, return to Navigating Repositories and Notifications first. +The briefing output only makes sense when you already know what each section of it is describing.

      +

      What it does

      +

      Sweeps every repository you have access to and builds a prioritized dashboard:

      +
        +
      • Issues opened in the last 24 hours
        • +
      • Pull requests waiting for your review
        • +
      • CI failures on your branches
        • +
      • Security and Dependabot alerts
        • +
      • Community reactions to your recent comments
        • +
      +

      Example commands

      +
      @daily-briefing morning briefing
+
+@daily-briefing what needs my attention today in accessibility-agents?
+
+@daily-briefing summarize activity in community-access/accessibility-agents from the last week
      +

      Screen reader tip: The briefing output uses heading level 2 for each section. Use H key (NVDA/JAWS virtual mode) or VO+Command+H (VoiceOver) to jump between: Open Issues, Review Requests, CI Status, Security Alerts, Community Activity.

      +

      Output format

      +
      ## Issues Opened (Last 24 Hours)
+- #42 [accessibility-agents] Add Timeline View documentation (opened 3 hours ago)
+- #41 [accessibility-agents] Fix heading hierarchy in GUIDE.md (opened 18 hours ago)
+
+## Pull Requests Awaiting Your Review
+- #14 [accessibility-agents] Improve screen reader navigation guide (jeffb, 2 days old)
+
+## CI Failures on Your Branches
+- feature/add-timeline-guide - Tests failing on line 42 of timeline-test.md
+
+## Security Alerts
+- No new security alerts
+
+## Community Activity
+- Your comment on #38 received 3 reactions (×2, ×1)
      +

      Agent 2: @issue-tracker - Issue Management

      +

      Type: Both (Informational + Task-oriented)

      +

      File: .github/agents/issue-tracker.agent.md

      +

      Before you run this agent: You should have filed at least one issue using the full manual process - writing a title, description, and reproduction steps; applying labels and a milestone; and reading at least five existing issues to understand what a well-formed issue looks like. If you have not done this, the agent's priority scores and draft replies will mean nothing to you. +Return to Working with Issues and Labels, Milestones & Projects first.

      +

      What it does

      +

      Finds, prioritizes, and helps you manage issues across all your repositories:

      +
        +
      • Cross-repository priority scoring with community sentiment
        • +
      • Batch-reply capability (draft replies to multiple issues at once)
        • +
      • Saved search support
        • +
      • Release-awareness (flags issues that affect upcoming releases)
        • +
      +

      Example commands

      +
      @issue-tracker find open issues labeled good-first-issue
+
+@issue-tracker find accessibility issues across all my repos
+
+@issue-tracker is there a duplicate of issue #42 in accessibility-agents?
+
+@issue-tracker draft a reply to issue #15 acknowledging it and asking for more context
      +

      Important: The agent can draft a reply. You review the tone against the Culture & Etiquette guide before posting. Your name goes on it.

      +

      Output example

      +
      ## Open Issues Labeled "good-first-issue"
+
+### High Priority
+- #45 [accessibility-agents] Add NVDA-specific navigation tips (3 comments, opened 5 days ago)
+  - Priority Score: 8/10 (high community interest, clear scope, no assignee)
+  - Recommended for: First-time contributors familiar with screen readers
+
+### Medium Priority
+- #38 [accessibility-agents] Improve commit message examples (1 comment, opened 2 weeks ago)
+  - Priority Score: 5/10 (useful addition, low urgency)
+
+## Draft Reply for Issue #15
+
+Hi @contributor-name,
+
+Thanks for opening this issue. To help us reproduce the problem, could you provide:
+1. Which screen reader you're using (NVDA, JAWS, VoiceOver)
+2. The exact steps you took when the issue occurred
+3. What you expected to happen vs what actually happened
+
+This will help us diagnose the issue faster.
+
+- Draft by @issue-tracker (review before posting)
      +

      Agent 3: @pr-review - Pull Request Review

      +

      Type: Both (Informational + Task-oriented)

      +

      File: .github/agents/pr-review.agent.md

      +

      Before you run this agent: You should have manually reviewed at least one pull request diff in the GitHub browser interface - navigating the Files Changed tab with your screen reader, reading added and removed lines, leaving at least one inline comment, and submitting a review. The agent generates a review document; you need to know what a good review looks like in order to edit, improve, and take ownership of what it produces. +Return to Working with Pull Requests if this is not yet familiar.

      +

      What it does

      +

      Generates full review documents for pull requests:

      +
        +
      • Line-numbered diffs with change maps
        • +
      • Risk assessment (what could break, what is high-impact)
        • +
      • Before-and-after snapshots
        • +
      • CI results and test coverage information
        • +
      • Suggested inline review comments with line number references
        • +
      +

      Example commands

      +
      @pr-review review PR #14 in accessibility-agents
+
+@pr-review what is the risk level of PR #8?
+
+@pr-review generate inline comments for PR #14
+
+@pr-review summarize what changed in PR #14 in two sentences
      +

      Critical rule: Read the agent's review. Edit it. Make it yours. Post your edited version. The agent produces a starting point - it does not know the project's history, the contributor's background, or the community's implicit standards the way you do.

      +

      Output example

      +
      ## PR Review: #14 - Improve screen reader navigation guide
+
+### Summary
+This PR adds 3 new sections to the screen reader navigation guide and updates 2 existing sections with NVDA-specific keyboard shortcuts.
+
+**Files Changed:** 1
+**Lines Added:** 127
+**Lines Removed:** 18
+
+### Risk Assessment
+**Risk Level:** Low
+
+#### What Could Break
+- None identified - documentation-only change
+
+#### High-Impact Areas
+- Section 3 (Keyboard Navigation) - heavily referenced by other guides
+
+### Change Map
+
+#### docs/navigation-guide.md
+
+##### Lines 42-65: ADDED - NVDA Browse Mode shortcuts
++ New content explaining Browse Mode vs Focus Mode
++ Table of NVDA-specific shortcuts
++ Screen reader announcements examples
+
+##### Lines 88-92: MODIFIED - Updated heading hierarchy example
+- Old: Basic example with 2 levels
++ New: Comprehensive example with 3 levels and explanations
+
+##### Lines 120-145: ADDED - Common navigation mistakes section
++ Lists 5 common mistakes with solutions
+
+### Suggested Inline Comments
+
+**Line 48:** Consider adding a note that Browse Mode is called "Virtual Cursor" in JAWS
+**Line 127:** Typo - "anounced" should be "announced"
+**Line 143:** This mistake applies to VoiceOver too - expand to include VO+Arrow navigation
+
+### Recommendation
+#### Approve with Minor Changes
+
+This is a valuable addition to the guide. The three typos and one clarification request are minor. Once those are addressed, this is ready to merge.
+
+- Review generated by @pr-review (edit before posting)
      +

      Agent 4: @analytics - Team Analytics

      +

      Type: Informational

      +

      File: .github/agents/analytics.agent.md

      +

      Before you run this agent: You should have explored the Insights tab of at least one repository - looked at the contribution graph, understood what commit frequency means, and thought about what "high-churn files" implies for a project's stability. The analytics output describes patterns in data you should already be able to read manually. Return to Navigating Repositories if the Insights tab is unfamiliar.

      +

      What it does

      +

      Surfaces team contribution patterns, velocity metrics, and bottleneck detection:

      +
        +
      • Contribution velocity over time
        • +
      • Review turnaround time by reviewer
        • +
      • Code hotspot detection (files with the most churn)
        • +
      • Workload distribution across contributors
        • +
      +

      Example commands

      +
      @analytics team velocity in accessibility-agents this month
+
+@analytics who are the most active contributors to accessibility-agents?
+
+@analytics which files are changed most often in accessibility-agents?
+
+@analytics how long does PR review take on average in accessibility-agents?
      +

      Accessibility use case: After Day 2's contribution wave, run @analytics team velocity in accessibility-agents today to see the hackathon's collective output. A moment of real-time team celebration.

      +

      Output example

      +
      ## Team Velocity - accessibility-agents (January 2026)
+
+### Contribution Summary
+- **Total Commits:** 47
+- **Total PRs:** 12 (10 merged, 2 open)
+- **Contributors:** 8 (3 new this month)
+- **Average Commits per Day:** 1.5
+
+### Most Active Contributors
+1. **jeffb** - 18 commits, 5 PRs merged
+2. **alex-a11y** - 12 commits, 3 PRs merged
+3. **sara-docs** - 8 commits, 2 PRs merged
+
+### High-Churn Files (Most Frequently Changed)
+1. **docs/GUIDE.md** - 14 changes (documentation updates)
+2. **README.md** - 8 changes (feature additions, fixes)
+3. **.github/agents/pr-review.agent.md** - 6 changes (agent refinement)
+
+### PR Review Turnaround Time
+- **Average:** 18 hours
+- **Fastest:** 2 hours (PR #14)
+- **Slowest:** 72 hours (PR #8 - awaiting maintainer review)
+
+### Trends
+- Commit velocity up 40% compared to December 2025
+- New contributors joining at healthy rate (3 this month)
+- Review times improving (down from 24-hour average last month)
      +

      Agent 5: @insiders-a11y-tracker - Accessibility Change Monitoring

      +

      Type: Both (Informational + Task-oriented)

      +

      File: .github/agents/insiders-a11y-tracker.agent.md

      +

      Before you run this agent: You should have filed at least one accessibility bug report using the workshop's issue template, applied a WCAG label to an issue, and manually reviewed a Markdown file for heading hierarchy - knowing what H1 means, what H2 means, what H3 means, what a skip means, and why it matters to screen reader navigation. The tracker flags accessibility issues in your contributions; you need to understand the standard it is measuring against before you can act on its output. +Return to Issue Templates and Working with Issues if these are not yet familiar.

      +

      What it does

      +

      Monitors accessibility-sensitive changes across configured repositories:

      +
        +
      • WCAG/ARIA cross-referenced change tracking
        • +
      • Flags changes to keyboard navigation, ARIA attributes, focus management, color usage
        • +
      • Monitors for heading hierarchy violations in Markdown
        • +
      • Tracks link text quality (flags bare URLs, non-descriptive labels)
        • +
      +

      Example commands

      +
      @insiders-a11y-tracker check recent changes in accessibility-agents
+
+@insiders-a11y-tracker review my PR #14 for accessibility impact
+
+@insiders-a11y-tracker are there any accessibility regressions in the last 5 commits?
      +

      Day 2 workflow: Run this before submitting any PR. If the agent flags an issue, fix it before requesting review - not after.

      +

      Output example

      +
      ## Accessibility Changes - accessibility-agents (Last 5 Commits)
+
+### Issues Found: 2
+
+#### Issue 1: Heading Hierarchy Skip
+**File:** docs/11-vscode-basics.md
+**Commit:** a3f2b9c
+**Line:** 142
+
+**Problem:** H1 → H3 skip (missing H2)
+
+```markdown
+# VS Code Setup
+
+### Screen Reader Mode
+```text
+
+**WCAG Guideline:** 1.3.1 Info and Relationships (Level A)
+
+**Impact:** Screen reader users navigating by heading level will not find this section when jumping to H2 headings.
+
+**Suggested Fix:** Change `### Screen Reader Mode` to `## Screen Reader Mode`
+
+
+#### Issue 2: Non-Descriptive Link Text
+
+**File:** README.md
+**Commit:** b8e3c1d
+**Line:** 28
+
+**Problem:** Link text is "click here"
+
+```markdown
+For more information, [click here](https://example.com/guide).
+```text
+
+**WCAG Guideline:** 2.4.4 Link Purpose (Level A)
+
+**Impact:** Screen reader users navigating by links will hear "click here" with no context about the destination.
+
+**Suggested Fix:** Use descriptive link text: `Read the [complete setup guide](https://example.com/guide).`
+
+
+### Positive Changes: 1
+
+#### Improvement: ARIA Label Added
+
+**File:** docs/navigation-guide.md
+**Commit:** c7d4e2f
+**Line:** 89
+
+**Change:** Added `aria-label` to icon-only button example
+
+```markdown
+<button aria-label="Close dialog"></button>
+```text
+
+**WCAG Guideline:** 4.1.2 Name, Role, Value (Level A)
+
+**Impact:** Screen reader users can now understand the button's purpose without visible text.
+
+
+## Recommendations
+
+1. Fix heading hierarchy skip in docs/11-vscode-basics.md before merging PR #14
+2. Update link text in README.md (low priority - not in active workflow path)
+3. Continue using descriptive ARIA labels for icon-only controls (positive trend)
+
      +

      Agent 6: @template-builder - Interactive Issue Template Wizard

      +

      Type: Informational with guided output

      +

      File: .github/agents/template-builder.agent.md

      +

      Before you run this agent: You should have read Issue Templates thoroughly - understanding YAML field types, creating a template manually (Exercise B), and designing your own template (Exercise D). The Template Builder does not teach template design - it automates the YAML writing. You need to know what you want to ask for before the agent can guide you through the form structure.

      +

      What it does

      +

      An interactive wizard that guides you through building GitHub issue templates step-by-step using VS Code's Ask Questions feature. Instead of writing YAML syntax, answer simple questions and the agent generates production-ready templates.

      +

      Example workflow

      +
      
+You: @template-builder create accessibility bug template
+
+Agent: [Ask Questions interface]
+  Q: What's this template called?
+  → "Accessibility Bug Report"
+
+  Q: What's it for?
+  → "Report screen reader, keyboard, and assistive tech issues"
+
+  Q: Add a field (type, label, required?)
+  → Field 1: dropdown, "Screen Reader", yes
+     Options: NVDA, JAWS, VoiceOver, TalkBack, Other
+
+  → Field 2: textarea, "How to reproduce", required
+
+  → Field 3: textarea, "Expected vs actual", required
+
+  Q: Ready to generate?
+  → Yes
+
+Agent: [Syntax-highlighted YAML output]
+        Ready to copy and save to .github/ISSUE_TEMPLATE/
+
      +

      Example commands

      +
      
+@template-builder create accessibility template
+
+@template-builder design a security vulnerability template
+
+@template-builder build a feature request form
+
      +

      Why use it? Manual YAML template creation takes 15-20 minutes and is error-prone. The Template Builder generates correct, tested templates in 2-3 minutes via guided questions.

      +

      Advanced: After generating a template, you can ask: @template-builder reorder the fields or @template-builder add a checkbox field for version compatibility - the agent regenerates your YAML with the changes applied.

      +

      5. Slash Commands and Prompts

      +

      The repository includes 54+ slash commands defined as .prompt.md files in .github/prompts/. Type / in Copilot Chat to see the full command menu.

      +

      Most Useful for This Workshop

      + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + +
      CommandWhat It DoesExample Usage
      /my-issuesYour open issues with priority signals/my-issues
      /review-prAI-generated review with inline suggestions/review-pr #14
      /pr-commentDraft a response to a PR comment/pr-comment #14
      /a11y-updateLatest accessibility improvements with WCAG cross-references/a11y-update insiders
      /triageTriage a new issue with label and priority suggestions/triage #22
      /issue-replyDraft a reply to an issue thread/issue-reply #15
      /daily-briefingSame as @daily-briefing - your morning activity snapshot/daily-briefing
      /draft-releaseGenerate release notes from merged PRs/draft-release v2.0
      /my-prsYour open PRs with CI and review status/my-prs
      +

      Workshop Slash Command Quick Reference

      +

      The commands listed below are the ones most relevant to this workshop. The full repository contains 54+ commands covering accessibility auditing, document scanning, framework-specific checks, and more. See Appendix L for the complete list.

      +
      
+/address-comments     Address all open review comments on your PR
+/a11y-update          Latest accessibility improvements with WCAG cross-references
+/ci-status            CI/CD health dashboard across your repos
+/create-issue         Create a well-formed issue from a description
+/daily-briefing       Morning activity snapshot across all your repos
+/draft-release        Generate release notes from merged PRs
+/explain-code         Explain selected code in plain language
+/issue-reply          Draft a reply to an issue thread
+/manage-branches      List, compare, and clean up branches
+/manage-issue         Update labels, assignees, or status on an issue
+/merge-pr             Check merge readiness and merge a PR
+/my-issues            Your open issues with priority signals
+/my-prs               Your open PRs with CI and review status
+/my-stats             Your contribution stats across repos
+/notifications        Manage GitHub notifications without opening a browser
+/onboard-repo         First-time scan of a repo - health, quick wins, recommended actions
+/pr-author-checklist  Pre-merge checklist for PR authors
+/pr-comment           Draft a response to a PR comment
+/pr-report            Detailed PR analysis report
+/project-status       GitHub Projects board overview - columns, blocked, stale
+/react                Suggest or add a reaction to an issue or comment
+/refine-issue         Improve issue title, description, and labels
+/release-prep         Complete release preparation workflow
+/review-pr            AI-generated review with inline suggestions
+/security-dashboard   Dependabot alerts and vulnerability status
+/sprint-review        End-of-sprint summary with velocity and retrospective
+/team-dashboard       Team activity and contribution overview
+/triage               Triage a new issue with label and priority suggestions
+
      +

      Reading Slash Command Definitions

      +

      Each /command corresponds to a .prompt.md file in .github/prompts/. Open any of them in VS Code to read what instructions it gives Copilot.

      +

      Example: /a11y-update

      +

      File: .github/prompts/a11y-update.prompt.md

      +
      name: a11y-update
+description: "Get the latest accessibility improvements across all tracked repos -- with WCAG cross-references and ARIA pattern mapping"
+agent: insiders-a11y-tracker
+tools:
+  - github/*
+  - createFile
+  - createDirectory
+  - ask_questions
+
+Show me the latest accessibility improvements across tracked repositories.
+
+${input:scope:Optional: 'insiders', 'stable', 'both', a specific month, 'screen reader', search keywords, 'track owner/repo', or a specific repo name}
+
+## Behavior
+
+Load accessibility tracking configuration from `.github/agents/preferences.md`
+(repos, labels, channels). If no preferences exist, use defaults
+(microsoft/vscode with accessibility labels).
      +

      This is how you learn to write your own. Copy an existing file, edit the instructions, save it with a new name - you have just created a new slash command for your fork.

      +

      Learning Cards: Slash Commands and Prompts

      +
      +Screen reader users + +
        +
      • Type / in Copilot Chat to see all available slash commands -- your screen reader announces each command name as you arrow through the list
        • +
      • Slash commands are defined in .github/prompts/ as .prompt.md files -- open them in the Explorer to read what each command does before using it
        • +
      • Create your own command by copying an existing .prompt.md file, renaming it, and editing the instructions -- no code required
        • +
      +
      + +
      +Low vision users + +
        +
      • The / command menu appears as a dropdown list in Copilot Chat -- it scales with VS Code's font and zoom settings
        • +
      • Each command has a short description visible in the dropdown; use Ctrl+= to zoom if the text is too small
        • +
      • Open the .prompt.md file in the editor to read the full command definition at your preferred zoom level
        • +
      +
      + +
      +Sighted users + +
        +
      • Type / in Copilot Chat to see a categorized list of available commands -- scroll or type to filter
        • +
      • The command table in this section lists the most useful workshop commands with usage examples
        • +
      • Each .prompt.md file in .github/prompts/ corresponds to one slash command -- browse them in the Explorer to discover all available commands
        • +
      +
      + + +

      6. Contributing to the Ecosystem

      +

      The 55 Accessibility Agents and 54+ slash commands are starting points. The .agent.md format is open - you can create your own agents for any repeatable workflow, and contribute them back to the project.

      +
      +

      Think strategically about impact. Before you build, ask: "Who benefits from this agent, and how often?" An agent that saves 100 people five minutes each week has more impact than an agent that saves one person an hour once. The best contributions solve problems that many people share.

      +

      Source: accessibility.github.com/documentation/guide/getting-started-with-agents/

      +
      +

      Two Types of Custom Agents

      +

      Informational agents - conversational; search, analyze, and present results:

      +
        +
      • Perform GitHub searches with predefined scopes and filters
        • +
      • Present results in specific structured formats
        • +
      • Query GitHub API tools to answer questions
        • +
      +

      Task-oriented agents - active; edit files, run commands, submit PRs:

      +
        +
      • Execute external tools (linters, test suites, axe-core)
        • +
      • Make direct file edits based on findings
        • +
      • Create pull requests with proposed changes
        • +
      • Combine both: explain issues (informational) and fix them (task-oriented)
        • +
      +

      Agent File Structure

      +
      +

      See also: Appendix L: Agents Reference has the complete agent.md format specification and examples.

      +
      +

      Every .agent.md file has two parts: YAML frontmatter (metadata) and a system prompt (markdown body).

      +
      name: agent-name
+description: One-sentence description of what the agent does
+tools:
+  - github/search_issues
+  - github/issue_read
+
+## Purpose
+Brief explanation of when to use this agent
+
+## Your Capabilities
+- What the agent can find or do
+
+## Domain Knowledge
+Specific query patterns, filters, or product knowledge
+
+## Responsibilities
+Step-by-step behavioral rules
+
+## Response Guidelines
+How to format output
      +

      Frontmatter fields

      + + + + + + + + + + + + + + + + + + + + + + + +
      FieldRequiredDescription
      nameRecommendedHow the agent appears in the agent picker
      descriptionRecommendedShown in agent lists
      toolsOptionalRestricts tool access; omit to grant all tools
      +

      Restricting tool access is a security best practice - only grant what the agent actually needs:

      +
      # Informational agent - read-only GitHub tools only
+tools: ["github/search_issues", "github/issue_read"]
+
+# Task-oriented agent - file editing, shell execution, and GitHub API
+tools:
+  - read
+  - edit
+  - search
+  - execute
+  - github/*
      +

      Example: Informational Agent - @insiders-a11y-tracker

      +

      This agent monitors VS Code Insiders releases for accessibility improvements. It searches the microsoft/vscode repository using predefined GitHub query syntax, so you never have to remember the exact filter parameters.

      +

      Use it

      +
        +
      1. Select @insiders-a11y-tracker from the agent picker
        2. +
      2. Ask: what shipped this month? or any keyboard navigation improvements in January?
        3. +
      3. The agent searches with repo:microsoft/vscode is:closed milestone:"[Month] [Year]" label:accessibility label:insiders-released and returns formatted results
        4. +
      +

      Prerequisite: GitHub MCP server installed (github.com/github/github-mcp-server)

      +

      Example: Task-Oriented Agent - The Markdown Accessibility Assistant

      +

      The GitHub Accessibility team published a complete walkthrough for building a Markdown Accessibility Assistant - a task-oriented agent that reviews Markdown files for accessibility issues and makes direct fixes. It:

      +
        +
      • Runs markdownlint-cli2 to catch structural problems (heading skips, bare URLs, missing blank lines)
        • +
      • Reviews link text for descriptiveness
        • +
      • Flags missing or inadequate alt text and waits for your approval before changing it (alt text requires human judgment)
        • +
      • Fixes heading hierarchy, list structure, and bare URL formatting directly
        • +
      • Works both locally in VS Code (editing files) and on GitHub.com (reviewing PRs and committing fixes)
        • +
      +

      This agent is the automated version of the accessibility review skills you built during Day 1. The five principles it enforces are directly from GitHub's accessibility documentation.

      +

      To build it: Follow the step-by-step guide at accessibility.github.com/documentation/guide/getting-started-with-agents - the YAML frontmatter, each section of the system prompt, and the complete agent file are all shown.

      +

      Key Pattern: Tiered Decision-Making

      +

      From the guide:

      +
      For objective issues (link text, heading hierarchy, list structure):
+  → Agent makes the fix directly
+
+For subjective issues (alt text, plain language):
+  → Agent flags the issue, explains why it matters, suggests a fix,
+    and waits for human approval before making changes
      +

      This tiered approach - automate what can be objectively evaluated, flag what needs human judgment - is the right model for any accessibility agent. It maximizes the agent's value while keeping humans in control of decisions that require context.

      +

      Required Prerequisites for the Markdown Accessibility Assistant

      + +

      Invoking Custom Agents

      +

      From VS Code

      +
        +
      1. Open Copilot Chat (Ctrl+Shift+I / Cmd+Shift+I on macOS)
        2. +
      2. In the Chat input toolbar, select the Set Agent button
        3. +
      3. Select your custom agent from the agent picker
        4. +
      4. Type your request - the agent executes in your local workspace
        5. +
      +

      From GitHub.com (Task mode)

      +
        +
      1. Open Copilot Chat on GitHub.com
        2. +
      2. Select Task from the mode picker
        3. +
      3. Optionally select a custom agent from the agent picker
        4. +
      4. Submit your request - the agent can create a PR automatically
        5. +
      +

      From an issue (Issue Assignment)

      +
        +
      1. Open any issue → Assignees → assign Copilot
        2. +
      2. In the dialog, optionally select a custom agent
        3. +
      3. Select Assign - Copilot creates a branch, makes changes, and opens a PR
        4. +
      +

      Environment Setup for GitHub (Cloud Agents)

      +

      When agents run on GitHub (not locally), they may need additional tools. Create a workflow file at .github/workflows/copilot-setup-steps.yml with a single job named copilot-setup-steps. GitHub runs this before the agent starts:

      +
      name: Copilot Setup Steps
+on: workflow_dispatch
+jobs:
+  copilot-setup-steps:
+    runs-on: ubuntu-latest
+    steps:
+      - name: Install accessibility tools
+        run: npm install -g markdownlint-cli2 axe-cli
      +

      Windows users: If your project requires a Windows development environment for Copilot coding agent sessions, you can switch the runner from Ubuntu to Windows. See Switching Copilot to a Windows development environment for configuration details.

      +

      To Create Your Own Agent

      +
        +
      1. Create .github/agents/your-agent-name.agent.md
        2. +
      2. Write YAML frontmatter (name, description, tools)
        3. +
      3. Write the system prompt - identity, capabilities, domain knowledge, behavioral rules, output format
        4. +
      4. Save and reload VS Code (Ctrl+Shift+P → "Reload Window")
        5. +
      5. Type @your-agent-name in Copilot Chat
        6. +
      +

      Exercise: Extend the Template Builder Agent

      +

      You've built templates manually (Chapters 15-16) and seen them in action. Now see how to harness AI to generate templates interactively, and learn to customize agents for your own projects.

      +

      What You'll Learn: How agents work, how to interact with the @template-builder agent, and how to extend it for project-specific needs.

      +

      Prerequisites:

      +
        +
      • Complete Chapters 15-16 (especially Exercise D - designing your own template)
        • +
      • VS Code is installed and GitHub Copilot is active
        • +
      • You have forked accessibility-agents to your GitHub account
        • +
      • You have cloned your fork locally: git clone https://github.com/[your-username]/accessibility-agents.git
        • +
      +

      Exercise 1: Generate a Template with the Agent

      +

      Your Mission: Use the @template-builder agent to generate an accessibility bug report template interactively. You'll experience the agent as an end-user and see what production-ready agent output looks like.

      +

      Time estimate: 5-10 minutes

      +
      Step 1: Open Your Fork in VS Code
      +
      What to do
      +
        +
      1. Open VS Code
        2. +
      2. File → Open Folder → select your locally cloned accessibility-agents folder
        3. +
      3. The folder tree appears on the left showing the repository structure
        4. +
      4. Verify you're in the right place: The folder name should be accessibility-agents at the top of the sidebar
        5. +
      +
      What you should see
      +
        +
      • Left sidebar showing: .github/, docs/, learning-room/, README.md, etc.
        • +
      • The status bar at the bottom shows your current git branch (probably main)
        • +
      +
      Step 2: Open Copilot Chat
      +
      What to do
      +
        +
      1. Keyboard shortcut: Press Ctrl+Shift+I (Windows/Linux) or Cmd+Shift+I (macOS)
          +
        • Alternative: Use menu: View → Copilot Chat
          • +
        +
        2. +
      2. A chat panel opens on the right side of VS Code
        3. +
      3. At the top, you see "Copilot Chat" and probably a text input at the bottom saying "Ask Copilot..."
        4. +
      +
      What happens
      +
        +
      • Copilot is now ready to receive instructions
        • +
      • You have access to all agents in .github/agents/ (because you opened that folder)
        • +
      +
      If Copilot Chat doesn't open
      +
        +
      • Make sure GitHub Copilot Chat extension is installed (Extensions sidebar → search "GitHub Copilot Chat")
        • +
      • Make sure you're signed into GitHub (top right of VS Code)
        • +
      • Restart VS Code if neither of the above is the problem
        • +
      +
      Step 3: Invoke the Template Builder Agent
      +
      What to do
      +
        +
      1. Click in the chat input box (bottom of Copilot Chat panel)
        2. +
      2. Type: @template-builder (the @ prefix invokes an agent)
        3. +
      3. You should see suggestions appearing: a dropdown showing available agents
        4. +
      4. If @template-builder appears, click it or press Enter to select it
        5. +
      5. The input now shows: @template-builder
        6. +
      +
      What to do next
      +
        +
      1. Type: create accessibility template
        2. +
      2. Your full message should read: @template-builder create accessibility template
        3. +
      3. Press Enter to send
        4. +
      +
      What happens
      +
        +
      • The agent processes your request
        • +
      • It starts asking questions via VS Code's Ask Questions interface
        • +
      • A series of prompts appear asking you to define your template
        • +
      +
      Step 4: Answer the Agent's Questions
      +
      What to expect
      +

      The @template-builder agent will ask (via Ask Questions UI):

      +
        +
      1. "What's your template name?" (text input)
        2. +
      2. "What's this template for?" (text input)
        3. +
      3. "First field name?" (text input)
        4. +
      4. "Field type?" (dropdown: input, textarea, dropdown, checkboxes, markdown)
        5. +
      5. "Is this field required?" (yes/no toggle)
        6. +
      6. "More fields?" (yes/no)
        7. +
      7. [Repeat for each field you want]
        8. +
      +
      How to interact
      +
        +
      • For text inputs: Type your answer and press Tab or Enter to move to the next prompt
        • +
      • For dropdowns: Use ↑↓ Arrow keys to navigate options, Enter to select
        • +
      • For toggles: Press Space to switch between yes/no
        • +
      +
      Example responses
      +
      Q: Template name?
+A: Accessibility Bug Report
+
+Q: What's it for?
+A: Report screen reader and keyboard navigation issues
+
+Q: First field name?
+A: Screen Reader
+
+Q: Field type?
+A: dropdown
+
+Q: Dropdown options? (comma-separated)
+A: NVDA, JAWS, VoiceOver, TalkBack, Other
+
+Q: Required?
+A: Yes
+
+Q: Add another field?
+A: Yes
+
+Q: Second field name?
+A: Browser
+
+Q: Field type?
+A: dropdown
+
+Q: Options?
+A: Chrome, Firefox, Safari, Edge, Other
+
+Q: Required?
+A: Yes
+
+Q: Add another field?
+A: No
      +
      As you answer
      +
        +
      • Read each question carefully
        • +
      • Provide clear, brief answers
        • +
      • Don't worry about perfect wording - the agent will format it correctly
        • +
      +
      What success looks like
      +
        +
      • You've answered at least 3-4 fields
        • +
      • Each field has a name, type, and requirement status
        • +
      • The agent confirms: "Ready to generate your template? Yes/No"
        • +
      +
      Step 5: Generate and Review the Output
      +
      What to do
      +
        +
      1. When the agent asks "Ready to generate?", select Yes
        2. +
      2. The agent produces a complete YAML template in the chat
        3. +
      3. The template appears in a code block with syntax highlighting
        4. +
      4. The code block has buttons: Copy and Insert into File (or similar)
        5. +
      +
      What to look for
      +
        +
      • The template starts with name:, description:, title:, labels:
        • +
      • Under body:, each field appears with type:, id:, attributes:, validations:
        • +
      • Dropdown fields show options: with your specified choices
        • +
      • Required fields show required: true
        • +
      +
      Example output (truncated)
      +
      name: Accessibility Bug Report
+description: Report screen reader and keyboard navigation issues
+title: "[A11Y] "
+labels: ["accessibility"]
+
+body:
+  - type: dropdown
+    id: screen_reader
+    attributes:
+      label: Screen Reader
+      options:
+        - NVDA
+        - JAWS
+        - VoiceOver
+        - TalkBack
+        - Other
+    validations:
+      required: true
+
+  - type: dropdown
+    id: browser
+    attributes:
+      label: Browser
+      options:
+        - Chrome
+        - Firefox
+        - Safari
+        - Edge
+        - Other
+    validations:
+      required: true
      +
      Validate the output
      +
        +
      • Does the YAML syntax look correct? (colons, indentation, no red squiggles if VS Code is open)
        • +
      • Are all your fields present?
        • +
      • Are dropdowns showing the options you specified?
        • +
      • Are required fields marked as required: true?
        • +
      +
      If something looks wrong
      +
        +
      • Don't edit the YAML yet - just note what's off
        • +
      • You can ask the agent: "@template-builder fix the browser field, should be an input not a dropdown"
        • +
      • The agent regenerates with corrections
        • +
      +
      Step 6: Copy the Template
      +
      What to do
      +
        +
      1. In the code block, click the Copy button (usually top-right of the code block)
          +
        • Keyboard alternative: Select all the code (Ctrl+A while in code block), then Ctrl+C
          • +
        +
        2. +
      2. The template is copied to your clipboard
        3. +
      +
      Verify
      +
        +
      • A notification may appear: "Copied to clipboard"
        • +
      • The text is ready to paste
        • +
      +
      Step 7: Save the Template to Your Fork
      +
      What to do
      +
        +
      1. In VS Code, open the file explorer (left sidebar)
        2. +
      2. Navigate to: .github/ISSUE_TEMPLATE/
        3. +
      3. Right-click in the folder and select New File
        4. +
      4. Name it: my-a11y-template.yml (or [project]-template.yml)
        5. +
      5. A new file opens in the editor with an empty content area
        6. +
      6. Click and paste your copied YAML: Ctrl+V
        7. +
      7. Save the file: Ctrl+S
        8. +
      +
      What you should see
      +
        +
      • The YAML fills the file
        • +
      • Syntax highlighting colors the code
        • +
      • No red squiggles (if syntax is valid)
        • +
      • File is marked as "modified" (white dot on the tab)
        • +
      +
        +

      1. Commit and push to GitHub:

        +
        git add .github/ISSUE_TEMPLATE/my-a11y-template.yml
+git commit -m "feat: add accessibility template (agent-generated)"
+git push origin main
        +
        2. +
      +
      If there's a merge conflict
      +
        +
      • Ask your facilitator for help (unlikely at this point)
        • +
      +
      Step 8: Test the Template in Your Fork
      +
      What to do
      +
        +
      1. Go to your fork on GitHub in your browser
        2. +
      2. Click Issues tab
        3. +
      3. Click New issue → the template chooser appears
        4. +
      4. Your new template should appear: "Accessibility Bug Report"
        5. +
      5. Click it to open the form
        6. +
      6. Fill in a test issue (just to see the form work)
        7. +
      7. With screen reader: Navigate through the form and confirm:
          +
        • All labels are announced clearly
          • +
        • Dropdown options are readable
          • +
        • Required fields are marked
          • +
        +
        8. +
      +
      What success looks like
      +
        +
      • The template appears when you click "New issue"
        • +
      • All fields display and behave correctly
        • +
      • Dropdowns work as expected
        • +
      • Screen reader announces everything clearly
        • +
      +
      Checkpoint: Exercise 1 Complete
      +

      Verify you've accomplished:

      +
        +
      • Used @template-builder to generate a template via Ask Questions
        • +
      • Received a complete YAML template
        • +
      • Copied the template and saved it to .github/ISSUE_TEMPLATE/
        • +
      • Pushed it to GitHub
        • +
      • Tested it in your fork's issue form
        • +
      • Confirmed it's accessible with screen reader
        • +
      +
      What you learned
      +
        +
      • How AI agents can automate the mechanical parts of GitHub workflows
        • +
      • The interaction pattern: you describe, agent generates, you refine/deploy
        • +
      • That the agent's output still needs human review and testing
        • +
      +

      Exercise 2: Extend the Agent for Your Project

      +

      Your Mission: Customize the Template Builder agent to recognize and guide a Security Vulnerability Report template. This teaches you how to tailor agents for project-specific needs.

      +

      Time estimate: 10-15 minutes

      +
      Step 1: Open the Agent File
      +
      What to do
      +
        +
      1. In VS Code, navigate to .github/agents/
        2. +
      2. File: template-builder.agent.md
        3. +
      3. Double-click to open it in the editor
        4. +
      4. You see the agent's instructions in Markdown format
        5. +
      +
      What to notice
      +
        +
      • The file starts with YAML frontmatter (name, description, topics)
        • +
      • Below that, sections like "## How to Use", "## Pre-Built Workflow"
        • +
      • Search for the text "Pre-Built Workflow: Guided Accessibility Template"
        • +
      +
      Step 2: Find the Pre-Built Workflows Section
      +
      What to do
      +
        +
      1. Use Ctrl+F to open Find
        2. +
      2. Search for: Pre-Built Workflow
        3. +
      3. Press Enter to jump to the first match
        4. +
      4. You should land on the "Pre-Built Workflow: Guided Accessibility Template" section
        5. +
      5. This section explains how to invoke the agent with a specific behavior
        6. +
      +
      What to look for
      +
      ## Pre-Built Workflow: Guided Accessibility Template
+
+The agent includes a guided workflow for the most common case: building
+an accessibility bug report template.
+
+### Invoke with
+- `@template-builder` + "create accessibility template"
+- `/build-a11y-template`
+
+### Workflow
+The agent skips to Phase 2 but pre-populates it with ...
      +
      Step 3: Add a New Pre-Built Workflow
      +
      What to do
      +
        +
      1. Position your cursor at the end of the "Accessibility Template" section (before the next ## or ---)
        2. +
      2. Press Enter twice to create space
        3. +
      3. Type a new section for Security Vulnerability templates:
        4. +
      +
      ## Pre-Built Workflow: Guided Security Vulnerability Template
+
+Query the agent with: `@template-builder` + "create security template"
+
+### Workflow
+The agent guides you through vulnerability-specific fields:
+
+1. **Vulnerability Type** (dropdown)
+   - SQL Injection
+   - Cross-Site Scripting (XSS)
+   - Authentication bypass
+   - Privilege escalation
+   - Denial of Service
+   - Other
+
+2. **Severity** (dropdown)
+   - Critical (impacts availability/integrity/confidentiality)
+   - High (moderate impact, likely exploitable)
+   - Medium (limited impact or hard to exploit)
+   - Low (minimal impact)
+
+3. **Affected Versions** (input)
+   - Which versions of your software are vulnerable?
+
+4. **Impact Description** (textarea)
+   - What can an attacker do if they exploit this?
+
+5. **Proof of Concept** (textarea, optional)
+   - Can you demonstrate the vulnerability?
+
+6. **Requested Disclosure Timeline** (input, optional)
+   - When should you publish the fix?
+
+### Output
+A security vulnerability report template ready for your project's use.
      +

      What you're adding

      +
        +
      • A clear label for the new workflow
        • +
      • Instructions on how to invoke it
        • +
      • Pre-defined fields that make sense for security reports
        • +
      • Specific options for severity and vulnerability type
        • +
      +
      Step 4: Save the Updated Agent
      +
      What to do
      +
        +
      1. Save the file: Ctrl+S
        2. +
      2. You should see no error messages
        3. +
      3. The agent file now includes your new Pre-Built Workflow
        4. +
      +
      What happens
      +
        +
      • The agent recognizes your new workflow
        • +
      • Next time you invoke @template-builder with "create security template", it will follow your new guidance
        • +
      +
      Step 5: Test the Extended Agent
      +
      What to do
      +
        +
      1. Open Copilot Chat again: Ctrl+Shift+I
        2. +
      2. Type: @template-builder create security template
        3. +
      3. Press Enter
        4. +

      4. The agent should now ask vulnerability-specific questions:

        +
        Q: Template name?
+A: Security Vulnerability Report
+
+Q: What's it for?
+A: Report security vulnerabilities in a standardized format
+
+Q: First field?
+A: Vulnerability Type (dropdown)
+
+Q: Options?
+A: SQL Injection, XSS, Authentication Bypass, Privilege Escalation, DoS, Other
        +
        5. +
      +
      What success looks like
      +
        +
      • The agent recognizes "create security template"
        • +
      • It guides you through security-specific fields
        • +
      • The output is a different template than the accessibility one
        • +
      +
      If the agent doesn't recognize your new workflow
      +
        +
      • Make sure you saved the file
        • +
      • Try reloading VS Code: Ctrl+Shift+P → "Reload Window"
        • +
      • Try the agent invocation again
        • +
      +
      Step 6: Deploy Your Extended Agent
      +
      What to do
      +
        +

      1. Commit your agent change:

        +
        git add .github/agents/template-builder.agent.md
+git commit -m "feat: add security vulnerability template workflow to template-builder agent"
+git push origin main
        +
        2. +
      2. The extended agent is now in your fork
        3. +
      3. Anyone who forks your fork gets the security workflow too
        4. +
      +
      What success looks like
      +
        +
      • Your commit appears on GitHub
        • +
      • The agent file shows the new Pre-Built Workflow section
        • +
      • You can prove the template-builder agent is now customized for your project
        • +
      +
      Checkpoint: Exercise 2 Complete
      +

      Verify you've accomplished:

      +
        +
      • Located the agent file (template-builder.agent.md)
        • +
      • Found the Pre-Built Workflows section
        • +
      • Added a new Security Vulnerability workflow with specific fields
        • +
      • Tested the agent to confirm it recognizes your new workflow
        • +
      • Committed and pushed the changes
        • +
      +
      What you learned
      +
        +
      • How agents are just structured Markdown instructions
        • +
      • How to tailor agent behavior for specific domains (accessibility, security, etc.)
        • +
      • That you can extend agents without rewriting them completely
        • +
      +

      Exercise 3: Iterative Refinement with Agents

      +

      Your Mission: Generate a template, then ask the agent to modify it incrementally. This teaches you the iterative pattern that scales to all agent-assisted workflows.

      +

      Time estimate: 5-10 minutes

      +
      Step 1: Start Fresh
      +
      What to do
      +
        +
      1. In Copilot Chat, type: @template-builder create a feature request template
        2. +

      2. Answer the agent's questions to build a feature request form:

        +
        Name: Feature Request
+Purpose: Propose new functionality
+Fields:
+- Problem Statement (textarea, required)
+- Proposed Solution (textarea, required)
+- Version Interested (input, optional)
        +
        3. +
      3. Let the agent generate the YAML
        4. +
      4. Copy it to a file: .github/ISSUE_TEMPLATE/feature-request.yml
        5. +
      +
      What you're doing
      +
        +
      • Running a complete template generation (same as Exercise 1)
        • +
      +
      Step 2: Ask for a Modification
      +
      What to do
      +
        +

      1. Once the template is generated, while still in the same chat conversation, ask:

        +
        @template-builder add a checkbox field: "I have searched for existing feature requests"
        +
        2. +
      2. The agent regenerates the YAML with your new checkbox added in the right place (usually as required field pre-validation)
        3. +
      +
      What happens
      +
        +
      • The agent modifies the YAML it generated
        • +
      • The new checkbox appears in the YAML with proper formatting and indentation
        • +
      • It doesn't regenerate from scratch - just adds your change
        • +
      +
      Step 3: Request Another Refinement
      +
      What to do
      +
        +

      1. Follow up with:

        +
        @template-builder change "Proposed Solution" field to include markdown code block support
        +
        2. +
      2. The agent modifies the textarea field's attributes to enable code highlighting
        3. +
      +
      What changes
      +
        +
      • The field now includes render: "a11y friendly code rendering" or similar
        • +
      • The YAML structure is preserved; only the specific field is enhanced
        • +
      +
      Step 4: Observe the Iterative Pattern
      +
      What to reflect on
      +
        +
      1. You gave the agent one goal (generate a feature request template)
        2. +
      2. The agent produced complete output (full YAML)
        3. +
      3. You refined incrementally (add checkbox, enhance code support)
        4. +
      4. At each step, the agent understood context (which field, how to modify it)
        5. +
      5. You didn't start over - just evolved the template
        6. +
      +
      This is the pattern that scales
      +
        +
      • Template generation: "Create a template with these fields"
        • +
      • Code review: "Review this PR and flag accessibility issues"
        • +
      • Issue triage: "Summarize these 5 issues and suggest priorities"
        • +
      • Documentation: "Generate release notes from these commits"
        • +
      +

      Each one follows: describe → generate → refine → deploy.

      +
      Checkpoint: Exercise 3 Complete
      +

      Verify you've accomplished:

      +
        +
      • Generated a feature request template with the agent
        • +
      • Asked for a modification (add checkbox)
        • +
      • Requested further refinement (enhance field)
        • +
      • Observed how the agent maintains context across requests
        • +
      +
      What you learned
      +
        +
      • Agents work best with iterative dialogue, not one-shot requests
        • +
      • You can build complex outputs through successive refinements
        • +
      • The agent remembers context and can modify instead of regenerate
        • +
      • This pattern applies to any repeatable GitHub workflow
        • +
      +

      What Comes Next

      +

      You've now:

      +
        +
      1. Generated a template using an agent (Exercise 1)
        2. +
      2. Customized an agent for your domain (Exercise 2)
        3. +
      3. Refined iteratively with agent help (Exercise 3)
        4. +
      +

      Your next step: explore the broader ecosystem.

      +
        +
      • Browse the full agent list - which agents solve problems you face regularly?
        • +
      • Try an Accessibility team agent: @contrast-master check this page or @alt-text-headings review this file
        • +
      • Try a Developer Tools agent: @python-specialist review this module for accessibility or @desktop-a11y-specialist audit this dialog
        • +
      • Think about what is missing: what agent would you build if you could?
        • +
      • Pick any agent that interests you and run it - the pattern is always the same: manual skill first, agent second, you refine and decide
        • +
      +

      That is Accessibility Agents' promise: not to replace your thinking, but to amplify your skills across all 55 agents - and to grow through the contributions of everyone who uses it.

      +

      Learning Cards: Contributing to the Ecosystem

      +

      Screen reader users:

      +
        +
      • Agent .agent.md files use YAML frontmatter at the top (between --- delimiters) followed by Markdown body; in VS Code, use Ctrl+G to jump to line 1 and arrow through the frontmatter fields (name, description, tools) before reading the body instructions
        • +
      • When writing your own .agent.md, use VS Code's Outline view (Ctrl+Shift+O) to verify that your Markdown headings (Purpose, Capabilities, Responsibilities) are correctly nested -- malformed headings will not appear in the outline
        • +
      • Before submitting a PR with a new agent file, run the file through a YAML linter (install the YAML extension, or use yamllint from the terminal) -- frontmatter syntax errors silently break agent registration
        • +
      +

      Low-vision users:

      +
        +
      • YAML frontmatter fields are densely packed with colons and quotes; increase your editor font size or use a monospaced font with wide character spacing so name:, description:, and tools: are clearly distinct
        • +
      • The .agent.md files in the agents/ directory follow a consistent structure -- use the file explorer's icon theme or file nesting feature to visually group agent files separately from regular documentation
        • +
      • When reviewing existing agents for contribution ideas, use VS Code's split editor to place the agent file and the README side by side so you can cross-reference the agent's instructions with its documented capabilities
        • +
      +

      Sighted users:

      +
        +
      • Study 2-3 existing .agent.md files before writing your own -- the pattern of frontmatter (metadata) plus Markdown body (instructions) is consistent, and matching the style reduces review friction on your PR
        • +
      • The contribution workflow for agents follows the same fork-branch-PR pattern from Chapter 18; your agent file goes in the agents/ directory with a kebab-case filename matching the agent name
        • +
      • Use GitHub's file diff preview on your PR to verify the YAML frontmatter renders correctly -- GitHub highlights YAML syntax, making missing quotes or wrong indentation easy to spot
        • +
      +

      7. The Bigger Picture: Teams, Orchestration, and Beyond VS Code

      +

      The 55 agents are not 55 independent tools. They are organized into three teams that work together, and several orchestrator agents exist specifically to coordinate multi-agent workflows.

      +

      How the Three Teams Connect

      +

      In practice, a single task often spans multiple teams:

      +
        +
      • You ask @daily-briefing (GitHub Workflow) for your morning report. It flags a PR that changes ARIA attributes.
        • +
      • You ask @pr-review (GitHub Workflow) to generate a structured review of that PR. The review notes potential accessibility impact.
        • +
      • You invoke @aria-specialist (Accessibility) to deep-check the ARIA changes. It identifies a missing aria-expanded state on a disclosure widget.
        • +
      • You fix the issue using patterns from @desktop-a11y-specialist (Developer Tools) if it is a desktop application, or directly in the HTML if it is a web project.
        • +
      +

      No single agent covers the entire workflow. The teams complement each other: GitHub Workflow agents surface what happened, Accessibility agents evaluate whether it is correct, and Developer Tools agents help you implement the fix.

      +

      Learning Cards: Teams and Orchestration

      +
      +Screen reader users + +
        +
      • Orchestrator agents like @accessibility-lead coordinate multi-agent workflows -- invoke one and it delegates to specialists, announcing which agent it is calling
        • +
      • Multi-agent output appears in sequence in Copilot Chat -- press Alt+F2 after each response to read it in Accessible View before the next agent responds
        • +
      • The three teams are GitHub Workflow (what happened), Accessibility (is it correct), and Developer Tools (fix it) -- choose your entry point based on your current task
        • +
      +
      + +
      +Low vision users + +
        +
      • Orchestrator responses can be long -- use Accessible View (Alt+F2) or widen the Chat panel to read comfortably at high zoom
        • +
      • The workflow diagrams in this section are described in text -- no visual-only content is required to understand the agent coordination pattern
        • +
      • Each team's agents are listed in the tables in Section 3 -- refer back there to find the right specialist agent
        • +
      +
      + +
      +Sighted users + +
        +
      • The coordination pattern follows a pipeline: Workflow agent surfaces an issue, Accessibility agent evaluates it, Developer Tools agent fixes it
        • +
      • Orchestrator agents produce structured output with headings for each delegated agent's findings -- scan the headings for a quick overview
        • +
      • The four orchestrator agents (@accessibility-lead, @security-lead, @documentation-lead, @project-lead) each manage a different concern domain
        • +
      +
      + +

      Orchestrator Agents

      +

      Four agents are specifically designed to coordinate others:

      + + + + + + + + + + + + + + + + + + + + + + + + + + + + +
      AgentTeamWhat It Orchestrates
      @nexusGitHub WorkflowCross-agent coordination for complex, multi-step workflows
      @accessibility-leadAccessibilityDelegates multi-agent accessibility audits to specialist agents
      @web-accessibility-wizardAccessibilityGuided WCAG audit that invokes contrast, keyboard, forms, and other specialists
      @document-accessibility-wizardAccessibilityGuided document audit across Word, Excel, PowerPoint, and PDF
      +

      You do not need to use orchestrators to get value from individual agents. But when a task is complex enough to span multiple agents, orchestrators save you the work of manually chaining requests.

      +

      High-Impact Agents to Try First

      +

      Rather than exploring all 55 agents at once, start with the ones that deliver immediate value based on Day 1 skills you already have:

      + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + +
      If You Can AlreadyTry This AgentAnd This Command
      Read issues and write replies@issue-tracker/triage, /issue-reply
      Review a PR diff@pr-review/review-pr, /address-comments
      Check your contribution activity@analytics/my-stats, /sprint-review
      Write issue templates@template-builder/create-issue
      Track what changed overnight@daily-briefing/daily-briefing
      Scan a page for accessibility issues@web-accessibility-wizard/onboard-repo
      Check color contrast manually@contrast-master(invoke directly)
      Test keyboard navigation@keyboard-navigator(invoke directly)
      +

      Slash Commands That Save the Most Time

      +

      These commands work without invoking a full agent - type them directly in Copilot Chat:

      +
        +
      • /my-issues and /my-prs - Instant dashboard of your open work across all repos
        • +
      • /review-pr #14 - Full AI-generated review with inline suggestions, replacing manual line-by-line reading
        • +
      • /triage #22 - Label, priority, and assignment suggestions for any new issue
        • +
      • /daily-briefing - Morning snapshot of repository activity, PRs needing review, and stale issues
        • +
      • /a11y-update - Latest accessibility improvements with WCAG cross-references
        • +
      • /draft-release v2.0 - Generate release notes from merged PRs
        • +
      • /onboard-repo - First-time scan of a repo with health assessment and recommended actions
        • +
      +

      The full list of 54+ commands is in Appendix L, and Episode 39 walks through all of them with examples.

      +

      Running Agents Beyond VS Code

      +

      Accessibility Agents' agents run on your machine, in your editor, when you ask for them. That is one scope.

      +

      The same Markdown-authored pattern extends further:

      +

      Scope 1: Your Editor (Accessibility Agents)

      +
        +
      • File lives in: .github/agents/[name].agent.md in your workspace
        • +
      • Triggered by: You, when you type @[agent-name] in Copilot Chat
        • +
      • Runs on: Your machine, using your Copilot subscription
        • +
      • Reaches: Every repository your GitHub account has access to
        • +
      • Scale: All 55 agents available when the workspace is open
        • +
      +

      Scope 2: Your Repository (Travels with Forks)

      +
        +
      • File lives in: .github/agents/[name].agent.md in the repo
        • +
      • Triggered by: Any contributor who has Copilot and opens the repo as a VS Code workspace
        • +
      • Runs on: Their machine, using their Copilot subscription
        • +
      • Reaches: Their GitHub account's repositories
        • +
      +

      When you fork accessibility-agents, all 55 agents come with it. You can edit them for your project's context. You can add new ones. You can share them with every contributor who clones your fork.

      +

      Scope 3: The Cloud (GitHub Agentic Workflows)

      +
        +
      • File lives in: .github/workflows/[name].md (same folder as standard Actions YAML)
        • +
      • Triggered by: Any GitHub event - issues: opened, pull_request: created, schedule:
        • +
      • Runs on: GitHub Actions infrastructure, serverlessly
        • +
      • Reaches: The repository where the workflow is defined
        • +
      +

      No VS Code required. No local machine required. The workflow runs whether or not anyone is watching - when an issue is opened at 3am, the agentic response fires.

      +

      The link between Accessibility Agents and Agentic Workflows: Both use Markdown-authored instructions. Both define intent in plain language. Both travel with the repository. The Accessibility Agents pattern is a conceptual precursor to GitHub Agentic Workflows - understanding one makes the other immediately readable.

      +

      Go Deeper

      +

      For full documentation on every agent, all 54+ slash commands, customization formats, and troubleshooting, see Appendix L: Accessibility Agents Reference. For the audio version, listen to Episode 39: Accessibility Agents - Complete Reference.

      +

      Example: Auto-triage accessibility issues

      +

      File: .github/workflows/auto-triage-a11y.md

      +
      name: Auto-Triage Accessibility Issues
+on:
+  issues:
+    types: [opened]
+
+When an issue is opened with "accessibility" or "a11y" or "screen reader" in the title:
+
+1. Apply labels: `accessibility`, `needs-triage`
+2. Assign to the accessibility team
+3. Add a comment:
+
+> Thanks for filing this accessibility issue. Our team has been notified and will review it within 24 hours.
+>
+> To help us address this faster, please include:
+> - Which screen reader you're using (NVDA, JAWS, VoiceOver)
+> - Steps to reproduce the issue
+> - What you expected vs what actually happened
+>
+> - Auto-triage agent
+
+4. If the issue body already includes those details, remove the `needs-triage` label
      +

      This runs automatically on every new issue. No human intervention required.

      +

      8. GitHub Desktop, GitHub CLI, and Copilot CLI

      +

      These tools are not required for this workshop, but are worth knowing as options for different workflows.

      +

      GitHub Desktop

      +

      A graphical Git application with an accessible interface.

      +
        +
      • Download: desktop.github.com
        • +
      • Useful for: Visual diff review, simpler branch management
        • +
      • Screen reader support: Partial - keyboard navigation works for core flows
        • +
      +

      When to use: If command-line Git feels overwhelming, GitHub Desktop provides a GUI alternative.

      +

      GitHub CLI (gh)

      +

      A command-line interface for GitHub operations.

      +

      Install

      +
      winget install GitHub.cli       # Windows
+brew install gh                 # macOS
      +

      Authenticate

      +
      gh auth login
      +

      Common commands

      +
      gh issue list                   # List issues in current repo
+gh issue view 42                # Read issue #42
+gh pr list                      # List pull requests
+gh pr view 14                   # Read PR #14
+gh pr create                    # Create a new PR interactively
+gh pr merge 14                  # Merge PR #14
+gh repo clone owner/repo        # Clone a repository
+gh repo fork owner/repo         # Fork a repository
      +

      Screen reader advantage: gh output is plain text with no dynamic regions - more predictable than the browser for certain operations.

      +

      GitHub Copilot CLI (gh copilot)

      +

      An extension that adds Copilot to the terminal.

      +

      Install

      +
      gh extension install github/gh-copilot
      +

      Commands

      +
      # Ask Copilot to explain a command
+gh copilot explain "git rebase -i HEAD~3"
+
+# Ask Copilot to suggest a command
+gh copilot suggest "undo my last commit but keep the changes"
+
+# Ask Copilot to write a shell script
+gh copilot suggest "create a script that finds all Markdown files and checks for heading hierarchy"
      +

      Use case: When you know what you want to do but are unsure of the exact git command syntax.

      +

      Example session

      +
      $ gh copilot suggest "show me all commits from last week"
+
+Suggestion: git log --since="1 week ago" --oneline
+
+Run this command? (Y/n)
      +

      Learning Cards: GitHub Desktop, GitHub CLI, and Copilot CLI

      +

      Screen reader users:

      +
        +
      • GitHub Desktop is a native application -- on Windows it uses UI Automation, not a browser DOM; your screen reader's object navigation (NVDA: Insert+Numpad) rather than browse mode is the correct approach for navigating its interface
        • +
      • GitHub CLI (gh) is entirely terminal-based; all output is plain text that your screen reader reads line by line -- pipe verbose output through | head -20 or | Select-Object -First 20 to avoid overwhelming your speech buffer
        • +
      • Copilot CLI (gh copilot suggest and gh copilot explain) presents interactive prompts in the terminal; listen for the "Run this command? (Y/n)" confirmation before pressing Enter to avoid executing unreviewed commands
        • +
      +

      Low-vision users:

      +
        +
      • GitHub Desktop inherits your Windows display scaling -- if text appears small, increase system-level scaling (Settings > Display > Scale) rather than looking for an in-app zoom option
        • +
      • Terminal output from gh and gh copilot uses your terminal's font and color settings; configure your terminal profile (Windows Terminal settings or iTerm2 preferences) with a high-contrast color scheme and large font for comfortable reading
        • +
      • Copilot CLI suggestions appear as plain text in the terminal, not in a styled panel -- they are easy to miss among other output; look for the indented suggestion block immediately after your prompt
        • +
      +

      Sighted users:

      +
        +
      • GitHub Desktop provides a visual diff view, branch graph, and drag-and-drop staging that are unavailable in the CLI -- use Desktop when you want a spatial overview of complex changes
        • +
      • GitHub CLI is scriptable; combine gh issue list, gh pr list, and gh api with shell pipelines to build custom dashboards without leaving the terminal
        • +
      • Copilot CLI complements (not replaces) your Git knowledge -- use gh copilot explain when you encounter an unfamiliar Git command in documentation, and gh copilot suggest when you know what you want to do but not the exact syntax
        • +
      +

      Keyboard Shortcuts - Accessibility Agents Quick Reference

      + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + +
      ActionShortcut
      Open Copilot ChatCtrl+Shift+I
      Invoke agentType @agent-name in Chat
      Use slash commandType /command in Chat
      Accessible ViewAlt+F2
      Clear chat historyCtrl+L
      Command PaletteCtrl+Shift+P
      +

      Troubleshooting

      +

      "Agent not found"

      +

      Issue: Typing @agent-name shows "No agent found."

      +

      Solutions

      +
        +
      1. Verify .github/agents/[name].agent.md exists in your workspace
        2. +
      2. Reload VS Code window: Ctrl+Shift+P → "Reload Window"
        3. +
      3. Check file naming: must end with .agent.md
        4. +
      4. Verify YAML frontmatter is valid (no syntax errors)
        5. +
      +

      Agent produces incorrect output

      +

      Issue: Agent's response is wrong or misses context.

      +

      Solutions

      +
        +
      1. Provide more context in your prompt: Be specific about what you need
        2. +
      2. Use @ mentions: Reference specific files or selections (@filename.md, #selection)
        3. +
      3. Check the agent's prerequisites: Did you do the manual work first?
        4. +
      4. Review the agent's instructions: Open .github/agents/[name].agent.md and read what it's supposed to do
        5. +
      +

      Slash command doesn't work

      +

      Issue: /command shows "Command not found."

      +

      Solutions

      +
        +
      1. Verify .github/prompts/[name].md exists
        2. +
      2. Reload window: Ctrl+Shift+P → "Reload Window"
        3. +
      3. Check file naming: must be a .md file in .github/prompts/
        4. +
      4. Try typing the full command name (autocomplete may be incomplete)
        5. +
      +
      +

      Next: Chapter 20: Build Your Agent
      Back: Chapter 18: Fork and Contribute
      Related appendices: Appendix L: Agents Reference | Appendix K: Copilot Reference

      + +
      + + + + diff --git a/html/admin/qa-bundle/docs/20-build-your-agent.html b/html/admin/qa-bundle/docs/20-build-your-agent.html new file mode 100644 index 00000000..5cb81184 --- /dev/null +++ b/html/admin/qa-bundle/docs/20-build-your-agent.html @@ -0,0 +1,724 @@ + + + + + + + Build Your Agent: The Capstone Project - GIT Going with GitHub + + + + + + + + +
      +

      Build Your Agent: The Capstone Project

      +
      +

      Related appendices: Appendix L: Agents Reference | Appendix K: Copilot Reference | Appendix C: Markdown Reference +Authoritative sources: VS Code Docs: Chat participants | GitHub Docs: About GitHub Copilot agents

      +
      +
      +

      Day 2, Block 4 Material (Capstone)

      +

      Everything you have learned comes together here. You will design, build, and contribute an accessibility agent to the Community-Access/accessibility-agents repository. This is a real contribution to a real project -- your agent will join the roster of 55+ agents serving 3 accessibility teams across 5 platforms.

      +
      +

      Table of Contents

      +
        +
      1. The Capstone Challenge
        2. +
      2. Phase 1: Choose Your Agent's Mission
        3. +
      3. Phase 2: Write the Agent File
        4. +
      4. Phase 3: Define Responsibilities and Guardrails
        5. +
      5. Phase 4: Test Your Agent Locally
        6. +
      6. Phase 5: Open Your Pull Request
        7. +
      7. Phase 6: Respond to Review
        8. +
      8. Capstone Rubric
        9. +
      9. Example Agents for Inspiration
        10. +
      10. If You Get Stuck
        11. +
      +
      +
      +

      Challenge 16: Build Your Agent (Capstone). This is the culminating challenge of the workshop. You will fork, write, test, and contribute an accessibility agent.

      +
      +

      1. The Capstone Challenge

      +

      The capstone is Challenge 16 -- the final challenge of the workshop. You will:

      +
        +
      1. Choose a mission for a new accessibility agent (or improve an existing one)
        2. +
      2. Write an agent file with valid YAML frontmatter
        3. +
      3. Define clear responsibilities and guardrails
        4. +
      4. Test the agent locally with GitHub Copilot
        5. +
      5. Open a pull request from your fork to the upstream repository
        6. +
      6. Respond to peer review feedback
        7. +
      +

      This is not a simulation. Your pull request goes to a real repository. If your agent meets the quality bar, it will be merged and available to real users.

      +

      What you need before starting

      +
        +
      • You have forked and cloned the accessibility-agents repository (Chapter 18)
        • +
      • You have a feature branch created: agents/your-username-agent-name
        • +
      • You understand how to push to your fork and open a PR (Chapter 18)
        • +
      • You have GitHub Copilot or Copilot Free active (Chapter 16)
        • +
      • You have explored the existing agents in Chapter 19
        • +
      +

      Time estimate

      +

      Most students complete the capstone in 60 to 90 minutes. The phases are designed so you can get a working agent in 30 minutes and spend the remaining time improving it.

      +
      +

      2. Phase 1: Choose Your Agent's Mission

      +
      +

      See also: Chapter 19: Accessibility Agents introduces the agent ecosystem and shows existing agents for inspiration.

      +
      +

      What makes a good agent mission

      +

      A good agent solves a specific, recurring problem. It does not try to do everything. Consider these questions:

      +
        +
      • What task do you repeat? Think about workflow steps from Day 1 and Day 2 that felt repetitive.
        • +
      • What would a specialist know? An agent works best when it has deep knowledge of a focused area.
        • +
      • What gap exists? Look at the existing agents in Chapter 19. Is there a workflow that no agent covers?
        • +
      +

      Mission categories to consider

      + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + +
      CategoryExample missionsExisting agents in this space
      Accessibility auditingAudit color contrast in CSS variables, check form labels, validate heading hierarchycontrast-master, forms-specialist, alt-text-headings
      Document accessibilityCheck PDF reading order, audit Excel sheet names, validate Word heading structurepdf-accessibility, excel-accessibility, word-accessibility
      GitHub workflowSummarize notifications, track stale issues, generate release notesdaily-briefing, issue-tracker, analytics
      Developer toolsValidate agent files, lint markdown for accessibility, check keyboard navigationtesting-coach, link-checker, markdown-a11y-assistant
      EducationExplain a WCAG criterion, generate quiz questions, summarize a chapterwcag-guide
      +

      Write your mission statement

      +

      Before writing any code, write a one-sentence mission statement:

      +
      +

      "My agent helps [who] by [doing what] when [in what situation]."

      +
      +

      Example: "My agent helps documentation authors by checking that all images in a markdown file have meaningful alt text when they open a file for review."

      +

      Write this statement in your challenge issue comment so your buddy and facilitator can give early feedback.

      +
      +

      3. Phase 2: Write the Agent File

      +

      An agent file is a Markdown file with YAML frontmatter that defines the agent's identity, and a body that contains the agent's instructions. Agent files live in the .github/agents/ directory (for GitHub Copilot agents) or in team-specific directories in the accessibility-agents repository.

      +

      File location and naming

      +

      Create your agent file at:

      +
      .github/agents/your-agent-name.md
      +

      Use lowercase with hyphens. Example: .github/agents/alt-text-validator.md

      +

      The agent file structure

      +

      Every agent file has two parts:

      +
        +
      1. YAML frontmatter -- metadata between --- markers at the top of the file
        2. +
      2. Instructions body -- Markdown content that tells the agent how to behave
        3. +
      +

      Minimal agent file template

      +
      ---
+name: "Alt Text Validator"
+description: "Checks that all images in markdown files have meaningful, non-placeholder alt text."
+---
+
+# Alt Text Validator
+
+You are an accessibility specialist focused on image alt text quality in markdown documentation.
+
+## Responsibilities
+
+- Scan markdown files for images missing alt text
+- Identify placeholder alt text like "image", "screenshot", "photo", or empty strings
+- Suggest specific, descriptive alt text based on the image context
+- Flag decorative images that should use empty alt text (`alt=""`)
+
+## Guardrails
+
+- Never modify files without explicit user approval
+- Always explain why alt text needs improvement before suggesting a replacement
+- Do not generate alt text for images you cannot see -- ask the user to describe the image
+- Limit scope to the files the user asks about -- do not scan the entire repository unprompted
      +

      YAML frontmatter fields

      + + + + + + + + + + + + + + + + + + +
      FieldRequiredDescription
      nameYesDisplay name for the agent (title case, spaces allowed)
      descriptionYesOne-sentence description of what the agent does -- also drives automatic invocation: Copilot matches this text against your request and delegates to the agent without you selecting it manually
      +
      +

      Write a strong description. Vague descriptions result in missed automatic routing.

      +
        +
      • Weak: Helps with accessibility
        • +
      • Strong: Checks markdown files for accessibility issues, fixes descriptive links and heading hierarchy, and flags alt text for human review
        • +
      +

      The more specific the description, the more reliably Copilot invokes the right agent for the right task.

      +
      +

      Writing the instructions body

      +

      The instructions body tells the agent how to behave. Write it as if you are briefing a new team member on their first day:

      +
        +
      • Start with identity. "You are a [role] focused on [area]."
        • +
      • List responsibilities. What specific tasks does this agent handle?
        • +
      • Set guardrails. What should the agent never do? What are its limits?
        • +
      • Provide examples. Show what good output looks like.
        • +
      +
      +

      Screen reader note: The agent file is plain Markdown. There are no special tools needed to write it. Use any text editor.

      +
      +

      Learning Cards: Writing the Agent File

      +
      +Screen reader users + +
        +
      • Create your agent file with Ctrl+N, then Ctrl+S and save to .github/agents/your-agent-name.md -- the Explorer navigates to the folder automatically
        • +
      • Use Ctrl+Shift+O to navigate between YAML frontmatter fields and Markdown headings (Responsibilities, Guardrails) in your agent file
        • +
      • The YAML frontmatter is between --- markers at the top -- your screen reader announces these as horizontal rules
        • +
      +
      + +
      +Low vision users + +
        +
      • Agent files are standard Markdown -- open Markdown Preview (Ctrl+Shift+V) side by side to verify formatting as you write
        • +
      • The YAML frontmatter at the top uses name: and description: fields -- keep these on separate lines for readability at high zoom
        • +
      • Use a consistent heading hierarchy (# for title, ## for sections) so the Outline view (Ctrl+Shift+O) shows a clean structure
        • +
      +
      + +
      +Sighted users + +
        +
      • Agent files follow a standard pattern: YAML frontmatter at the top, then identity statement, responsibilities, guardrails, and examples
        • +
      • Use the Outline view (Ctrl+Shift+O) to see your agent file's structure at a glance and navigate between sections
        • +
      • Copy the template from this chapter as a starting point -- replace the placeholder content with your agent's specific instructions
        • +
      +
      + +
      +

      4. Phase 3: Define Responsibilities and Guardrails

      +

      Responsibilities and guardrails are the most important parts of your agent's instructions. The autograder checks that both sections exist.

      +

      Writing responsibilities

      +

      Responsibilities define what the agent does. Be specific and actionable:

      +

      Good responsibilities (specific):

      +
        +
      • Scan HTML files for <img> tags missing the alt attribute
        • +
      • Check that all <button> elements have visible text or an aria-label
        • +
      • Verify heading levels do not skip (e.g., h1 to h3 without h2)
        • +
      +

      Weak responsibilities (vague):

      +
        +
      • Help with accessibility
        • +
      • Check code
        • +
      • Find problems
        • +
      +

      Each responsibility should describe one discrete action the agent can take.

      +

      Writing guardrails

      +

      Guardrails define what the agent must not do. They prevent the agent from overstepping, giving harmful advice, or acting without permission:

      +

      Good guardrails:

      +
        +
      • Never auto-fix code without asking the user first
        • +
      • Do not provide medical, legal, or financial advice when discussing accessibility compliance
        • +
      • Limit reviews to the files the user specifies -- do not scan the entire repository
        • +
      • If a finding is uncertain, say so explicitly rather than presenting it as definitive
        • +
      • Do not remove existing accessibility attributes unless they are demonstrably incorrect
        • +
      +

      Why guardrails matter: An agent without guardrails will confidently do things it should not. A contrast checker that silently changes your CSS colors is dangerous. A document reviewer that deletes "unnecessary" alt text is destructive. Guardrails are how you make an agent safe.

      +

      Learning Cards: Responsibilities and Guardrails

      +
      +Screen reader users + +
        +
      • Use ## Responsibilities and ## Guardrails as exact heading names -- the autograder searches for these strings
        • +
      • Each responsibility should start with a verb (Scan, Check, Verify, Flag) -- this makes them concrete and testable
        • +
      • Guardrails should start with "Never" or "Do not" to set clear boundaries your screen reader identifies as restrictions when reviewing the file
        • +
      +
      + +
      +Low vision users + +
        +
      • Format responsibilities as a bulleted list (starting with -) for easy scanning at high zoom -- one responsibility per bullet
        • +
      • Keep each guardrail to a single line so it remains visible without horizontal scrolling at your zoom level
        • +
      • Use bold text for emphasis on critical guardrails (e.g., Never modify files without approval) to improve visual scanning
        • +
      +
      + +
      +Sighted users + +
        +
      • The autograder checks for "Responsibilities" and "Guardrails" headings -- use exactly these words as ## headings
        • +
      • Aim for 4-6 responsibilities and 3-5 guardrails -- too few makes the agent vague, too many makes it rigid
        • +
      • Compare your responsibilities against the example agents in Section 9 to calibrate specificity
        • +
      +
      + +
      +

      5. Phase 4: Test Your Agent Locally

      +
      +

      See also: Chapter 18: Fork and Contribute covers the fork-and-PR workflow you will use to submit your agent.

      +
      +

      Before opening a pull request, test your agent to verify it works.

      +

      Testing with GitHub Copilot Chat

      +
        +
      1. Open VS Code with the accessibility-agents repository.
        2. +
      2. Ensure your agent file is saved in .github/agents/.
        3. +
      3. Open GitHub Copilot Chat (Ctrl+Shift+I or Cmd+Shift+I).
        4. +
      4. Invoke your agent by name: @your-agent-name check this file for accessibility issues
        5. +
      5. Observe the response. Does the agent:
          +
        • Understand its mission?
          • +
        • Follow its responsibilities?
          • +
        • Respect its guardrails?
          • +
        +
        6. +
      +

      Testing checklist

      +
        +
      • The agent responds when invoked by name
        • +
      • The agent stays within its defined responsibilities
        • +
      • The agent does not violate any guardrails
        • +
      • The agent's output is useful and specific
        • +
      • The agent handles edge cases gracefully (empty files, no issues found)
        • +
      +

      Iterating on your agent

      +

      If the agent does not behave as expected:

      +
        +
      1. Read its instructions carefully. Is anything ambiguous?
        2. +
      2. Add more specific instructions or examples.
        3. +
      3. Test again with the same prompt.
        4. +
      4. Repeat until the behavior matches your intent.
        5. +
      +

      Most students iterate 2-3 times before they are satisfied.

      +

      Learning Cards: Testing Your Agent

      +
      +Screen reader users + +
        +
      • Open Copilot Chat (Ctrl+Shift+I) and type @your-agent-name followed by a test prompt -- your screen reader announces the response as it streams
        • +
      • Press Alt+F2 after the response finishes to read the full output in Accessible View with arrow keys
        • +
      • If the agent does not respond as expected, edit the .agent.md file and ask again -- Copilot picks up changes immediately
        • +
      +
      + +
      +Low vision users + +
        +
      • Agent responses appear in the Copilot Chat panel -- widen the panel by dragging its left edge for better readability
        • +
      • Test with a simple prompt first (e.g., "review this file") and read the full response before trying complex requests
        • +
      • Use Accessible View (Alt+F2) to read responses at your preferred editor font size instead of the Chat panel's default
        • +
      +
      + +
      +Sighted users + +
        +
      • Type @agent-name in Copilot Chat followed by your test prompt -- look for the agent name in the response header confirming it was invoked
        • +
      • Check that the response follows your Responsibilities section and does not violate any Guardrails
        • +
      • Iterate by editing the agent file and re-testing until the output matches your expectations
        • +
      +
      + +
      +

      6. Phase 5: Open Your Pull Request

      +

      Tool Cards: Open Your Capstone PR

      +

      VS Code Desktop (primary for Day 2):

      +
        +
      1. Push your branch: Ctrl+Shift+P > Git: Push.
        2. +
      2. Ctrl+Shift+P > GitHub Pull Requests: Create Pull Request.
        3. +
      3. Set base repo to Community-Access/accessibility-agents, fill in the title and description.
        4. +
      +

      github.com (browser):

      +
        +
      1. Navigate to your fork on GitHub.
        2. +
      2. Click Contribute > Open pull request.
        3. +
      3. Verify the base is Community-Access/accessibility-agents:main and the compare is your branch.
        4. +
      +

      GitHub CLI:

      +
      git push -u origin your-branch
+gh pr create --repo Community-Access/accessibility-agents
      +

      You have a working agent file. Now contribute it.

      +

      Pre-PR checklist

      +

      Before opening your PR, verify:

      +
        +
      • Your agent file has valid YAML frontmatter (name and description fields)
        • +
      • Your agent file has a Responsibilities section
        • +
      • Your agent file has a Guardrails section
        • +
      • The file is in the correct directory
        • +
      • You have committed and pushed to your fork
        • +
      +

      Open the PR

      +

      Follow the pull request steps from Chapter 18, Step 7:

      +
        +
      1. Push your branch: git push -u origin agents/your-username-agent-name
        2. +
      2. Go to the upstream repository on GitHub.com.
        3. +
      3. Click the banner or go to Pull Requests and click New pull request, then compare across forks.
        4. +
      4. Select your fork and branch.
        5. +
      5. Write a PR title: "Add [agent-name] accessibility agent"
        6. +
      6. In the PR body, include:
          +
        • Your mission statement from Phase 1
          • +
        • What the agent does (summary of responsibilities)
          • +
        • Any design decisions you made
          • +
        • How you tested it
          • +
        +
        7. +
      7. Create the pull request.
        8. +
      +

      The autograder

      +

      The repository has an autograding workflow that runs on every pull request. It checks:

      + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + +
      CheckWhat it verifiesPoints
      Agent file existsA .md file exists in the agents directory10
      YAML frontmatter is validThe file starts with ---, contains name and description, and ends with ---15
      Responsibilities sectionThe file contains a heading or section titled "Responsibilities"15
      Guardrails sectionThe file contains a heading or section titled "Guardrails"20
      Total60
      +

      The autograder posts results as a comment on your PR. If any checks fail, read the comment, fix the issue, commit, and push. The autograder re-runs automatically.

      +

      Learning Cards: Opening Your Pull Request

      +
      +Screen reader users + +
        +
      • The autograder comment appears in the PR timeline -- navigate to Comments on GitHub.com with h (heading navigation) to find the results
        • +
      • Each autograder check is listed with a pass/fail status and point value -- listen for "10/10" or "0/15" to identify which checks need attention
        • +
      • If a check fails, read the failure message, fix the issue locally, commit, push, and the autograder re-runs automatically
        • +
      +
      + +
      +Low vision users + +
        +
      • The autograder results appear as a comment with a table showing checks, points, and pass/fail status -- zoom with Ctrl+= to read the details
        • +
      • Green checkmarks indicate passing checks; red X marks indicate failures -- pair with High Contrast theme for clearest visibility
        • +
      • Your PR description should include your mission statement, responsibilities summary, and testing notes
        • +
      +
      + +
      +Sighted users + +
        +
      • The autograder comment on your PR shows a table with four checks and a total score out of 60
        • +
      • Green checkmarks = passing, red X = failing -- fix failures and push to trigger a re-run
        • +
      • Include your mission statement, agent summary, and test results in the PR description for reviewers
        • +
      +
      + +
      +

      7. Phase 6: Respond to Review

      +

      After the autograder passes, a peer reviewer (your buddy or another student) and a facilitator will review your agent.

      +

      What reviewers look for

      +
        +
      • Clarity: Are the instructions easy to understand?
        • +
      • Specificity: Are responsibilities concrete and actionable?
        • +
      • Safety: Are guardrails sufficient to prevent harmful behavior?
        • +
      • Usefulness: Would this agent actually help someone?
        • +
      • Scope: Does the agent try to do too much or too little?
        • +
      +

      Responding to feedback

      +

      This is the same process from Chapter 18, Step 8:

      +
        +
      1. Read each review comment.
        2. +
      2. Make changes locally.
        3. +
      3. Commit and push. The PR updates automatically.
        4. +
      4. Reply to each comment explaining your changes.
        5. +
      +

      When your PR is merged

      +

      Congratulations. Your agent is now part of the accessibility-agents ecosystem. It is available to anyone who uses the repository. This is a real open source contribution, and it demonstrates:

      +
        +
      • You can navigate the fork workflow end to end
        • +
      • You can write clear, structured technical documentation
        • +
      • You understand accessibility concepts well enough to teach an AI agent about them
        • +
      • You can respond constructively to code review
        • +
      +
      +

      8. Capstone Rubric

      +

      The capstone is worth 60 autograded points plus peer review. Here is the complete rubric:

      +

      Autograded (60 points)

      + + + + + + + + + + + + + + + + + + + + + + + + + + + + +
      CriterionPointsWhat the autograder checks
      Agent file exists10A Markdown file exists in the agents directory
      Valid YAML frontmatter15File has --- delimiters, name field, description field
      Responsibilities defined15A section with the heading "Responsibilities" exists and contains content
      Guardrails defined20A section with the heading "Guardrails" exists and contains content
      +

      Peer review (qualitative)

      + + + + + + + + + + + + + + + + + + + + + + + +
      CriterionWhat reviewers assess
      Mission clarityCan a reader understand what the agent does in 10 seconds?
      Instruction qualityAre instructions specific enough that the agent behaves consistently?
      Guardrail coverageDo the guardrails prevent the most obvious failure modes?
      Contribution standardsDoes the PR follow the project's conventions and include a good description?
      +

      What "meets expectations" looks like

      +

      A capstone that meets expectations has:

      +
        +
      • A focused mission (not "help with accessibility" -- something specific)
        • +
      • At least 3 concrete responsibilities
        • +
      • At least 3 meaningful guardrails
        • +
      • A PR description that explains the agent's purpose
        • +
      • All autograder checks passing
        • +
      +

      What "exceeds expectations" looks like

      +

      A capstone that exceeds expectations also has:

      +
        +
      • Examples of expected input and output in the agent instructions
        • +
      • A section describing the agent's limitations
        • +
      • Evidence of testing (screenshots or transcripts in the PR description)
        • +
      • Thoughtful responses to review feedback
        • +
      +
      +

      9. Example Agents for Inspiration

      +

      These examples show the range of valid agent designs. Your agent does not need to be this long, but it should be this clear.

      +

      Example 1: Heading Hierarchy Checker

      +

      Mission: Validates that HTML and Markdown documents follow a correct heading hierarchy (no skipped levels).

      +

      Responsibilities:

      +
        +
      • Scan files for heading elements (h1 through h6 in HTML, # through ###### in Markdown)
        • +
      • Report any instance where a heading level is skipped (e.g., h2 followed by h4)
        • +
      • Suggest the correct heading level for each violation
        • +
      • Check that there is exactly one h1 per page
        • +
      +

      Guardrails:

      +
        +
      • Do not modify files -- only report findings
        • +
      • Do not change heading text, only heading levels
        • +
      • If a heading structure decision is ambiguous, present both options and let the user decide
        • +
      +

      Example 2: PR Description Quality Gate

      +

      Mission: Reviews pull request descriptions to ensure they contain enough context for reviewers.

      +

      Responsibilities:

      +
        +
      • Check that the PR description is at least 50 characters
        • +
      • Verify the description references an issue with Closes #XX or Fixes #XX
        • +
      • Check for a summary of changes made
        • +
      • Verify the description explains why the change was made, not just what was changed
        • +
      +

      Guardrails:

      +
        +
      • Never approve or block a PR based solely on description quality
        • +
      • Do not rewrite the description for the author -- suggest improvements
        • +
      • Respect that different projects have different template requirements
        • +
      +

      Example 3: Keyboard Navigation Auditor

      +

      Mission: Checks web components for keyboard accessibility compliance.

      +

      Responsibilities:

      +
        +
      • Verify all interactive elements are reachable via Tab key
        • +
      • Check that custom components have appropriate tabindex values
        • +
      • Validate that focus order follows visual layout
        • +
      • Detect keyboard traps (elements that receive focus but cannot release it via keyboard)
        • +
      +

      Guardrails:

      +
        +
      • Do not modify component code without user approval
        • +
      • Flag potential issues with confidence levels (certain, likely, possible)
        • +
      • Acknowledge that some keyboard patterns depend on runtime behavior that cannot be verified from source code alone
        • +
      +
      +

      10. If You Get Stuck

      + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + +
      ProblemWhat to do
      Cannot think of an agent ideaLook at the existing agents in Chapter 19. What adjacent task is not covered?
      YAML frontmatter is invalidCheck that you have --- on its own line at the start and end. Verify name and description are quoted strings.
      Autograder says "Responsibilities section not found"Make sure you have a Markdown heading that says exactly ## Responsibilities.
      Autograder says "Guardrails section not found"Make sure you have a Markdown heading that says exactly ## Guardrails.
      Agent does not respond in Copilot ChatVerify the file is saved in .github/agents/ and has a .md extension. Restart Copilot Chat.
      Agent ignores its guardrailsAdd more explicit instructions. Instead of "be careful," say "Never do X under any circumstances."
      PR fails to open across forksVerify you are comparing your fork's branch against the upstream's main. See Chapter 18, Step 7.
      Reviewer feedback feels overwhelmingAddress one comment at a time. Start with the smallest change. Reply to each comment individually.
      I finished but I am not sure I did it rightCompare your work against the Challenge 16 reference solution. If your agent file has valid frontmatter, responsibilities, and guardrails, you succeeded.
      +

      The universal safety net

      +

      If everything else fails, post this on your challenge issue:

      +
      +

      I attempted Challenge 16 and here is what happened:

      +

      What I tried: [specific actions] +What I expected: [what should have happened] +What actually happened: [error or unexpected result] +What I learned: [even from failure, what do I understand now?]

      +
      +

      This is always accepted. A student who explains a failure thoughtfully has learned more than one who followed the happy path without thinking.

      +
      +

      Next: Chapter 21: Next Steps
      Back: Chapter 19: Accessibility Agents
      Related appendices: Appendix L: Agents Reference | Appendix K: Copilot Reference

      + +
      + + + + diff --git a/html/admin/qa-bundle/docs/21-next-steps.html b/html/admin/qa-bundle/docs/21-next-steps.html new file mode 100644 index 00000000..a777ac16 --- /dev/null +++ b/html/admin/qa-bundle/docs/21-next-steps.html @@ -0,0 +1,471 @@ + + + + + + + What Comes Next: Your Developer Journey - GIT Going with GitHub + + + + + + + + +
      +

      What Comes Next: Your Developer Journey

      +
      +

      Related appendices: Appendix X: Resources | Appendix Z: GitHub Skills | Appendix Y: Workshop Materials +Authoritative sources: GitHub Skills | GitHub Docs: Getting started

      +
      +
      +

      Day 2, Closing Material

      +

      Congratulations -- you have completed the Git Going with GitHub workshop. This chapter is your graduation guide: what you accomplished, where to go next, how to build your portfolio, and how to stay connected with the community.

      +
      +

      Table of Contents

      +
        +
      1. What You Built in Two Days
        2. +
      2. Your New Skills Inventory
        3. +
      3. Building Your Developer Portfolio
        4. +
      4. Continued Learning Roadmap
        5. +
      5. GitHub Skills Courses to Try Next
        6. +
      6. Staying Connected
        7. +
      7. Contributing Back to This Workshop
        8. +
      8. Final Words
        9. +
      +
      +

      1. What You Built in Two Days

      +

      Take a moment to appreciate what you accomplished. This is not a list of what you were taught -- it is a list of what you did.

      +

      Day 1: You Can Navigate This

      +
        +
      • Created and configured a GitHub account with accessibility settings
        • +
      • Navigated repositories, files, and folders using your screen reader, keyboard, or preferred tools
        • +
      • Filed issues with descriptive titles, labels, and context
        • +
      • Created branches, edited files, and opened pull requests
        • +
      • Responded to bot feedback and passed automated checks
        • +
      • Resolved a merge conflict
        • +
      • Reviewed someone else's code and gave constructive feedback
        • +
      • Explored labels, milestones, and project boards
        • +
      • Managed notifications
        • +
      +

      Day 2: You Can Build This

      +
        +
      • Installed and configured VS Code with accessibility settings
        • +
      • Cloned a repository and worked with Git locally
        • +
      • Understood the mental model: working directory, staging area, repository
        • +
      • Created branches, staged changes, committed, and pushed from the command line
        • +
      • Explored GitHub Copilot: code suggestions, chat, and code review
        • +
      • Created an issue template
        • +
      • Forked a repository and contributed using the open source workflow
        • +
      • Explored the accessibility agents ecosystem
        • +
      • Built and contributed your own accessibility agent (capstone)
        • +
      +

      The evidence

      +

      Your GitHub profile now contains real activity: issues filed, pull requests merged, code reviewed, and an agent contributed to an open source project. This is not a certificate. It is a commit history.

      +
      +

      2. Your New Skills Inventory

      +

      The following table maps what you learned to where it applies beyond this workshop. Every skill transfers directly to real-world development.

      + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + +
      SkillWhere you learned itWhere it applies
      Repository navigationChapters 2-3Every GitHub project, every job that uses GitHub
      Issue trackingChapter 5Bug reports, feature requests, project management
      Pull request workflowChapters 6, 15Code contribution at any company or open source project
      Merge conflict resolutionChapter 7Any team project with multiple contributors
      Git fundamentalsChapters 13-14Every software project that uses version control
      VS Code proficiencyChapters 11-12Daily development work in any language
      Code reviewChapter 15Peer review, quality assurance, team collaboration
      Fork workflowChapter 18Open source contribution, cross-team collaboration
      AI-assisted developmentChapters 16, 19-20GitHub Copilot, AI agents, and future AI tools
      Accessibility awarenessEntire workshopBuilding inclusive software, WCAG compliance
      +

      Skills you may not have noticed

      +
        +
      • Reading documentation: You navigated technical guides, followed step-by-step instructions, and troubleshot problems using written references. This is the most important developer skill.
        • +
      • Asking for help effectively: You posted on issues with context, error messages, and what you tried. This is how experienced developers communicate.
        • +
      • Learning tools by doing: You did not read a manual cover to cover. You tried things, hit problems, and figured them out. This is how real tool learning works.
        • +
      +
      +

      3. Building Your Developer Portfolio

      +
      +

      See also: Appendix X: Resources has links to every tool and resource mentioned in this course.

      +
      +

      Your GitHub profile is your portfolio. Here is how to make what you built visible.

      +

      Pin your best repositories

      +
        +
      1. Go to github.com/settings/profile.
        2. +
      2. Scroll to "Pinned repositories."
        3. +
      3. Pin the repositories that show your best work. Consider:
          +
        • Your fork of the accessibility-agents repository (shows open source contribution)
          • +
        • Any personal projects you create after the workshop
          • +
        +
        4. +
      +

      Write a profile README

      +

      Your profile README is the first thing people see when they visit your GitHub profile. Create a repository with the same name as your username (e.g., your-username/your-username) and add a README.md:

      +
      # Hi, I am [Your Name]
+
+I am a developer focused on [your interests].
+
+## Recent work
+
+- Contributed an accessibility agent to [Community-Access/accessibility-agents](https://github.com/Community-Access/accessibility-agents)
+- Completed the Git Going with GitHub workshop
+
+## What I am learning
+
+- [List technologies or topics you are exploring]
      +

      Keep your contribution graph active

      +

      The green squares on your GitHub profile show when you made contributions. Even small actions count: filing issues, opening PRs, making commits, and reviewing code. Consistency matters more than volume.

      +

      Learning Cards: Building Your Developer Portfolio

      +

      Screen reader users:

      +
        +
      • Navigate to your profile settings at github.com/settings/profile -- the "Pinned repositories" section is a group of checkboxes; Tab through and press Space to pin or unpin
        • +
      • Your profile README repository must match your username exactly (case-sensitive) -- screen readers will read the rendered README as regular page content when visitors navigate your profile
        • +
      • The contribution graph is announced as a table or grid; arrow keys move between day cells, each announcing the date and contribution count
        • +
      +

      Low-vision users:

      +
        +
      • Pinned repositories appear as cards below your avatar -- at high zoom the 2x3 grid may reflow to a single column, which is easier to scan
        • +
      • The profile README renders with your current GitHub theme -- test yours in both light and dark modes to confirm text and images remain readable
        • +
      • Contribution graph squares use green intensity to show activity levels; enable high-contrast mode if the shading differences are hard to distinguish
        • +
      +

      Sighted users:

      +
        +
      • Pinned repos appear in a 2x3 grid directly below your bio -- visitors see them immediately, so choose repos that showcase your best work
        • +
      • Your profile README renders above the pinned repos section -- keep it concise and scannable with headings and bullet points
        • +
      • The contribution graph shows a full year of activity; consistent small green squares look better to visitors than occasional intense bursts
        • +
      +
      +

      4. Continued Learning Roadmap

      +
      +

      See also: Appendix Z: GitHub Skills has the complete catalog of recommended GitHub Skills courses.

      +
      +

      The workshop taught you the fundamentals. Here is where to go deeper in each area.

      +

      Git and version control

      +
        +
      • Pro Git book -- Free, comprehensive, and the official Git resource. Start with chapters 2 and 3.
        • +
      • Appendix E: Advanced Git -- Rebasing, cherry-picking, stashing, and other techniques you will need eventually.
        • +
      +

      GitHub platform

      +
        +
      • GitHub Docs -- The official documentation covers everything. Bookmark it.
        • +
      • GitHub Skills -- Free, interactive courses that teach by doing (see Section 5 below).
        • +
      • GitHub Blog -- Stay current with new features and best practices.
        • +
      +

      VS Code

      + +

      Accessibility

      + +

      AI-assisted development

      + +

      Programming languages

      +

      Choose based on your interests:

      + + + + + + + + + + + + + + + + + + + + + + + + + + + + +
      InterestLanguage to learnWhere to start
      Web developmentHTML, CSS, JavaScriptMDN Web Docs
      Automation and scriptingPythonPython.org tutorial
      Desktop applicationsPython (with wxPython or Tkinter)wxPython documentation
      Mobile developmentSwift (iOS) or Kotlin (Android)Platform-specific developer docs
      +
      +

      5. GitHub Skills Courses to Try Next

      +

      GitHub Skills offers free, interactive courses that run inside GitHub repositories. Each course creates a repository in your account with step-by-step instructions and automated feedback -- the same model we used in this workshop.

      + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + +
      CourseWhat you will learnHow it connects to this workshop
      Introduction to GitHubRepository basics, branches, commits, PRsReview and reinforce Day 1 skills
      Communicate using MarkdownMarkdown syntax, formatting, links, imagesWrite better issues, PRs, and documentation
      Review pull requestsReview workflow, inline comments, suggestionsDeepen the code review skills from Chapter 15
      Resolve merge conflictsConflict detection, resolution strategiesPractice what you learned in Chapter 7
      Getting Started with GitHub CopilotCopilot suggestions, chat, and promptingExtend Chapter 16 with hands-on Copilot practice
      Code with CopilotMulti-file editing, code review with CopilotBuild on the AI-assisted workflow from Day 2
      +

      How to start a course

      +
        +
      1. Go to skills.github.com.
        2. +
      2. Find a course and click its title.
        3. +
      3. Click Start course (this creates a repository in your account).
        4. +
      4. Follow the instructions in the repository's README.
        5. +
      +

      Each course takes 15 to 60 minutes.

      +
      +

      6. Staying Connected

      +

      Community Access

      + +

      Open source contribution

      +

      The capstone was your first contribution. Here is how to make more:

      +
        +
      1. Start with projects you use. If you use a tool or library and find a bug or missing documentation, that is your first issue.
        2. +
      2. Look for "good first issue" labels. Many projects label issues that are suitable for new contributors.
        3. +
      3. Documentation counts. Fixing typos, improving instructions, and adding examples are valuable contributions. Do not underestimate them.
        4. +
      4. The fork workflow scales. The same fork, branch, commit, push, PR workflow from Chapter 18 works for every GitHub project.
        5. +
      +

      Accessibility community

      + +
      +

      7. Contributing Back to This Workshop

      +

      This workshop is open source. If you found something confusing, incorrect, or missing, you can fix it.

      +

      Types of contributions we value

      + + + + + + + + + + + + + + + + + + + + + + + + + + + +
      ContributionHow to do it
      Fix a typo or broken linkOpen a PR directly
      Clarify confusing instructionsFile an issue describing what confused you, then open a PR
      Add a screen reader tipFile an issue with the tip and the chapter it belongs in
      Report an accessibility barrierFile an issue with the heading "Accessibility barrier"
      Suggest a new topicFile an issue with the heading "Content suggestion"
      +

      The contribution workflow

      +
        +
      1. Fork the git-going-with-github repository.
        2. +
      2. Clone your fork, create a branch, make your edit.
        3. +
      3. Open a PR with a clear title and description.
        4. +
      4. Mention the chapter number and section in your PR.
        5. +
      +

      You have already practiced every step of this workflow. This is the real thing.

      +

      Learning Cards: Contributing Back to This Workshop

      +

      Screen reader users:

      +
        +
      • The contribution workflow here is identical to Chapter 18 (Fork and Contribute) -- fork, clone, branch, edit, push, PR; use the same keyboard and screen reader patterns you already practiced
        • +
      • When filing an issue, include the chapter number and section heading in the title so maintainers can locate the problem with heading navigation
        • +
      • After opening a PR, listen for the automated check results in the PR timeline -- each check is announced as a link with its pass/fail status
        • +
      +

      Low-vision users:

      +
        +
      • The contribution types table above maps each kind of contribution to its workflow -- zoom in on the "How to do it" column for the quickest path
        • +
      • When editing documentation in your fork, use VS Code's Markdown Preview (Ctrl+Shift+V) at your preferred zoom level to verify formatting before pushing
        • +
      • PR descriptions render as Markdown on GitHub -- use headings and lists so reviewers can scan your changes at any zoom level
        • +
      +

      Sighted users:

      +
        +
      • The simplest contribution is fixing a typo -- fork the repo, edit the file directly on GitHub.com, and open a PR in under two minutes
        • +
      • Reference the chapter number and section in your PR title (e.g., "Fix broken link in Ch07 Section 3") so maintainers can review quickly
        • +
      • Check the repository's open issues for items labeled "good first issue" or "help wanted" to find contributions the maintainers are actively seeking
        • +
      +
      +

      If You Get Stuck After the Workshop

      + + + + + + + + + + + + + + + + + + + + + + + + + + + +
      ProblemWhat to do
      Forgot how to do something from the workshopSearch the course guide by topic. Every major skill links to the chapter and appendix that covers it.
      Git error you have not seen beforeCopy the exact error text and search for it. Pro Git and Stack Overflow's git tag cover nearly every scenario.
      VS Code extension not workingCheck the extension's page in the marketplace for known issues. Try disabling and re-enabling it.
      Want to contribute but do not know where to startSearch for good first issue labels on projects that interest you. See Section 4: Continued Learning Roadmap.
      Need help from the communityPost in Support Hub Discussions or file a support issue.
      +

      8. Final Words

      +

      Two days ago, GitHub was new. Git was a mystery. The terminal was unfamiliar. Now you have filed issues, opened pull requests, resolved conflicts, reviewed code, and contributed to a real open source project.

      +

      The tools are yours now. The workflow is yours. The confidence is yours.

      +

      Every expert started exactly where you are standing. The difference between a beginner and an experienced developer is not talent -- it is reps. You just finished your first set.

      +

      Keep committing.

      +
      +

      Back: Chapter 20: Build Your Agent
      Related appendices: Appendix X: Resources | Appendix Z: GitHub Skills

      + +
      + + + + diff --git a/html/admin/qa-bundle/docs/CHALLENGES.html b/html/admin/qa-bundle/docs/CHALLENGES.html new file mode 100644 index 00000000..d719254f --- /dev/null +++ b/html/admin/qa-bundle/docs/CHALLENGES.html @@ -0,0 +1,379 @@ + + + + + + + Challenge Hub - GIT Going with GitHub + + + + + + + + +
      +

      Challenge Hub

      +

      Welcome to the Challenge Hub - your guide to all 16 core challenges and 5 bonus challenges.

      +

      The challenges are the practice path for the course. Each one asks you to do a small piece of real GitHub work, leave evidence of what you did, and then close the issue so the next challenge can open. The goal is not speed. The goal is to build a contributor rhythm you can trust: orient yourself, make the move, verify the result, and ask for help with clear facts when something feels off.

      +

      How Challenges Work

      +

      Start in your private Learning Room repository, not in the public curriculum repository. Open the Issues tab, find the challenge issue assigned to you, and read the issue body before acting. Each issue explains the task, the evidence prompt, and any buddy check or automated check that applies.

      +

      When a challenge asks for evidence, post it as a comment on that challenge issue. Evidence can be a link, a short reflection, the name of a branch, a pull request number, or a note about what you tried and what happened. After you post the evidence, close the challenge issue. The Student Progression Bot uses that closed issue as the signal to open the next challenge.

      +

      Every challenge below includes a reference solution. Treat those files as worked examples, not answer keys. Your exact branch name, issue number, wording, or file count may differ. What matters is whether you practiced the skill and can explain the result.

      +

      Day 1: You Belong Here (Challenges 1-9)

      +
      +Challenge 1: Find Your Way Around + +

      Chapters: Ch02-04 | Evidence: Comment

      +

      This first challenge is about orientation. Before you edit anything, you learn how a repository is organized: where the Code tab lives, where Issues live, how the file tree behaves, and how the README gives a project its front door.

      +

      What to do:

      +
        +
      • Find the Code tab and count the files or folders in the repository root
        • +
      • Open the Issues tab and identify at least one issue or confirm the tab exists
        • +
      • Navigate to docs/welcome.md and read the opening paragraph
        • +
      • Find the repository description and the rendered README
        • +
      +

      Evidence to post: Describe what you found and name one navigation shortcut or screen reader technique that helped.

      +

      Compare your result with the Challenge 1 solution reference when you want a second view of the same exploration path.

      +
      + +
      +Challenge 2: File Your First Issue + +

      Chapter: Ch05 | Evidence: Comment

      +

      Issues are how maintainers turn observations into trackable work. In this challenge, you find a small TODO in the Learning Room and write an issue that another person could understand without being in the room with you.

      +

      What to do:

      +
        +
      • Open docs/welcome.md and search for TODO
        • +
      • Create a new issue with a specific title
        • +
      • Explain what needs to change, where it is, and why the change would help
        • +
      +

      Evidence to post: Link to the issue you created and include one sentence about why your title is clear.

      +

      If you want to compare tone and structure, read the Challenge 2 solution reference.

      +
      + +
      +Challenge 3: Join the Conversation + +

      Chapter: Ch05 | Evidence: Comment

      +

      Open source is conversation as much as code. This challenge teaches you how to participate in an issue thread with an @mention, a reaction, and a comment that moves the work forward.

      +

      What to do:

      +
        +
      • Find your buddy's Challenge 2 issue or a facilitator-provided peer simulation issue
        • +
      • Leave a meaningful comment with an @mention
        • +
      • Add a reaction to the original issue or a helpful comment
        • +
      +

      Evidence to post: Link to your comment and describe what made it useful, kind, or specific.

      +

      The Challenge 3 solution reference shows one way to make a short comment feel genuinely collaborative.

      +
      + +
      +Challenge 4: Branch Out + +

      Chapter: Ch06 | Evidence: Comment

      +

      A branch is a safe workspace. It lets you try a change without rewriting the main version of the project. In this challenge, you create your own branch and confirm that you know where your work will happen.

      +

      What to do:

      +
        +
      • Find the branch selector on the Code tab
        • +
      • Create a branch named learn/YOUR-USERNAME from main
        • +
      • Confirm the branch selector now names your branch
        • +
      +

      Evidence to post: Write the branch name you created and how you confirmed you were on it.

      +

      Use the Challenge 4 solution reference if you want to check your branch mental model.

      +
      + +
      +Challenge 5: Make Your Mark + +

      Chapter: Ch06 | Evidence: Comment

      +

      This is your first small content change. You edit a file, replace a TODO with real text, and commit the change with a message that explains what happened.

      +

      What to do:

      +
        +
      • Switch to your learn/YOUR-USERNAME branch
        • +
      • Edit docs/welcome.md to replace the TODO with useful content
        • +
      • Write a commit message that explains the change in plain language
        • +
      +

      Evidence to post: Share your commit message and the file you edited.

      +

      For a worked example of a focused commit, compare with the Challenge 5 solution reference.

      +
      + +
      +Challenge 6: Open Your First Pull Request + +

      Chapter: Ch06 | Evidence: Comment

      +

      A pull request is the conversation around a proposed change. It lets others review your branch before it becomes part of main. This challenge connects your branch, your issue, and your explanation into one contribution.

      +

      What to do:

      +
        +
      • Go to Pull requests > New pull request
        • +
      • Set the base branch to main and the compare branch to learn/YOUR-USERNAME
        • +
      • Write a clear title and include Closes #XX in the description
        • +
      +

      Evidence to post: Link to the pull request and name the issue it closes.

      +

      The Challenge 6 solution reference shows how the title, body, and closing keyword work together.

      +
      + +
      +Challenge 7: Survive a Merge Conflict + +

      Chapter: Ch07 | Evidence: Comment | Autograded

      +

      Merge conflicts happen when Git cannot safely combine two edits by itself. The point of this challenge is to read the conflict markers calmly, choose the final wording, delete the marker lines, and prove the file is clean.

      +

      What to do:

      +
        +
      • Wait for the facilitator to trigger the conflict
        • +
      • Find the marker lines: <<<<<<<, =======, and >>>>>>>
        • +
      • Decide which content to keep, or combine both sides into one clear version
        • +
      • Delete all marker lines and commit the resolution
        • +
      +

      Evidence to post: Explain which content you kept and why. The autograder checks that no conflict markers remain.

      +

      The Challenge 7 solution reference is useful if the marker structure still feels unfamiliar.

      +
      + +
      +Challenge 8: The Culture Layer + +

      Chapter: Ch08 | Evidence: Comment

      +

      Technical work lands better when the communication is respectful and specific. This reflection challenge asks you to name the collaboration habits you want to practice before you move deeper into reviews and capstone work.

      +

      What to do:

      +
        +
      • Answer the reflection prompt in your challenge issue
        • +
      • Add or recommend a label for an open issue, if the issue asks for triage practice
        • +
      • Leave a comment explaining the reasoning behind your communication or triage choice
        • +
      +

      Evidence to post: Write three concrete collaboration behaviors you will use in the rest of the workshop.

      +

      The Challenge 8 solution reference gives examples of specific, actionable reflection language.

      +
      + +
      +Challenge 9: Merge Day + +

      Chapter: Ch10 | Evidence: Comment

      +

      Merge Day closes the Day 1 loop. You verify that your pull request is ready, merge it when approved, confirm the change landed on main, and notice how the linked issue closes.

      +

      What to do:

      +
        +
      • Verify your PR has no conflicts and a meaningful commit message
        • +
      • Merge your PR, or wait for a facilitator to approve and merge it
        • +
      • Confirm your changes appear on the main branch
        • +
      • Check that the linked issue closed automatically
        • +
      +

      Evidence to post: Share the merged PR link and the issue number that closed.

      +

      Before moving on, scan the Challenge 9 solution reference to make sure you caught both the merge and verification steps.

      +
      + +

      Day 2: You Can Build This (Challenges 10-16)

      +
      +Challenge 10: Go Local + +

      Chapters: Ch11-14 | Evidence: Comment | Autograded

      +

      Day 2 moves the same contribution workflow onto your computer. You clone your Learning Room repository, create a branch locally, edit a file, commit, and push the branch back to GitHub.

      +

      What to do:

      +
        +
      • Clone your Learning Room repository to your computer with VS Code, GitHub Desktop, or the command line
        • +
      • Create a branch named fix/YOUR-USERNAME
        • +
      • Edit a file in docs/
        • +
      • Commit and push the branch to GitHub
        • +
      +

      Evidence to post: Share your branch name and a short note about how you confirmed the push reached GitHub. The autograder verifies a commit on a non-default branch.

      +

      The Challenge 10 solution reference shows the local workflow as one complete loop.

      +
      + +
      +Challenge 11: Open a Day 2 PR + +

      Chapters: Ch14-15 | Evidence: Comment

      +

      This challenge proves that the pull request pattern is the same whether the edit started in the browser or on your computer. You push a local branch, open a PR, and explain the change for reviewers.

      +

      What to do:

      +
        +
      • Open a PR from fix/YOUR-USERNAME to main
        • +
      • Write a title and description that describe the change clearly
        • +
      • Notice the familiar shape: branch, compare, title, body, submit
        • +
      +

      Evidence to post: Link to the PR and identify what changed between the branch and main.

      +

      Use the Challenge 11 solution reference to compare the local-to-GitHub handoff.

      +
      + +
      +Challenge 12: Review Like a Pro + +

      Chapter: Ch15 | Evidence: Comment

      +

      Review is where a contribution becomes stronger. Your job is to read a classmate's pull request, leave comments that are specific and kind, and submit a review verdict that matches what you found.

      +

      What to do:

      +
        +
      • Open your buddy's PR or a facilitator-provided peer simulation PR
        • +
      • Go to Files changed and read the diff
        • +
      • Leave at least two inline comments: one naming something effective and one suggesting an improvement
        • +
      • Use Suggest changes for at least one comment, if the interface supports it
        • +
      • Submit your review with Approve, Request changes, or Comment
        • +
      +

      Evidence to post: Link to the review or describe where you left your comments.

      +

      The Challenge 12 solution reference models feedback that teaches without taking over the author's work.

      +
      + +
      +Challenge 13: AI as Your Copilot + +

      Chapter: Ch16 | Evidence: Comment

      +

      Copilot can help draft and improve, but you remain responsible for the final result. This challenge asks you to use Copilot as a collaborator, then evaluate what it suggested before accepting anything.

      +

      What to do:

      +
        +
      • Ask Copilot to improve a documentation file
        • +
      • Apply the trust, verify, reject framework to each suggestion
        • +
      • Keep notes on what you accepted, modified, and rejected
        • +
      +

      Evidence to post: Share the prompt you used and one example of a suggestion you changed or rejected.

      +

      The Challenge 13 solution reference shows how to document human judgment around AI output.

      +
      + +
      +Challenge 14: Template Remix + +

      Chapter: Ch17 | Evidence: Comment | Autograded

      +

      Issue templates help contributors give maintainers the information they need on the first try. In this challenge, you create a small YAML issue form and verify that it has the required fields.

      +

      What to do:

      +
        +
      • Study docs/samples/challenge-14-registration-remix-example.yml
        • +
      • Create a new YAML template in .github/ISSUE_TEMPLATE/
        • +
      • Include name, description, title, and at least one form field
        • +
      • Commit and push the template
        • +
      +

      Evidence to post: Link to the template change or PR. The autograder verifies that the YAML template exists and includes required metadata.

      +

      The Challenge 14 solution reference can help you check both syntax and contributor usefulness.

      +
      + +
      +Challenge 15: Meet the Agents + +

      Chapter: Ch19 | Evidence: Comment

      +

      Accessibility agents are not magic helpers. They are structured instructions, responsibilities, and guardrails. This challenge asks you to inspect real agents before you build or improve one.

      +

      What to do:

      + +

      Evidence to post: Name the agents you found and explain one guardrail that protects learners or users.

      +

      The Challenge 15 solution reference shows how to turn exploration into a useful agent note.

      +
      + +
      +Challenge 16: Build Your Agent (Capstone) + +

      Chapters: Ch18, Ch20 | Evidence: Comment | Autograded

      +

      The capstone is where you design a small agent of your own and prepare it as a contribution. The important part is not a flashy idea. The important part is a clear purpose, useful responsibilities, and boundaries that keep the agent safe and honest.

      +

      What to do:

      +
        +
      1. Fork the Community Access Accessibility Agents repository
        2. +
      2. Clone your fork and create a branch named agent/YOUR-USERNAME
        3. +
      3. Write an .agent.md file with YAML frontmatter, responsibilities, and guardrails
        4. +
      4. Push and open a cross-fork PR to the original repository
        5. +
      5. Review a classmate's capstone PR when one is available
        6. +
      +

      Use the agent file template and fork workflow checklist for structure.

      +

      Evidence to post: Link to your capstone PR or summarize the agent file you created. The autograder verifies required agent structure when the file is represented in the Learning Room.

      +

      The Challenge 16 solution reference shows a complete agent example with responsibilities and guardrails.

      +
      + +

      Bonus Challenges

      +

      Bonus challenges are optional. Use them when you finish the core path early or want more practice with contribution habits that transfer beyond this workshop.

      +
      +Bonus A: Improve an Existing Agent + +

      Choose an existing agent, identify a focused improvement, and open a PR that explains why the change matters.

      +

      Compare your plan with the Bonus A solution reference.

      +
      + +
      +Bonus B: Document Your Journey + +

      Write a structured reflection about what you learned, what surprised you, and what you want to keep practicing. Use accessible Markdown so another person can read it comfortably.

      +

      The Bonus B solution reference offers a reflection structure if you need a starting shape.

      +
      + +
      +Bonus C: Create a Group Challenge + +

      Design a collaborative challenge for 3-5 students. A good group challenge names the shared goal, the separate roles, the evidence, and how the group knows it is finished.

      +

      Review the Bonus C solution reference for one way to describe group work clearly.

      +
      + +
      +Bonus D: Notification Mastery + +

      Configure GitHub notifications so you can find mentions, reviews, and assignments without drowning in every update.

      +

      The Bonus D solution reference shows how to describe a personal notification strategy.

      +
      + +
      +Bonus E: Explore Git History Visually + +

      Use GitHub Desktop or GitHub.com to explore repository history. The goal is to explain what changed over time, not merely to find a graph or timeline.

      +

      The Bonus E solution reference walks through one history-reading approach.

      +
      + +

      Skills-Inspired Optional Scenarios

      +

      For advanced students who finish early, use the curated optional scenarios in Learning Room skills bonus scenarios.

      +

      These scenarios adapt selected GitHub Skills exercises into this workshop environment without changing the official 21-challenge progression.

      +

      If You Get Stuck

      +

      Every challenge issue includes an "If you get stuck" section with common problems and recovery paths. Start there, then use these supports:

      + +

      When you ask for help, include what you were trying to do, where you were in the repository, what happened, and what you expected. That gives your buddy, facilitator, or bot enough context to help you quickly.

      + +
      + + + + diff --git a/html/admin/qa-bundle/docs/appendix-a-glossary.html b/html/admin/qa-bundle/docs/appendix-a-glossary.html new file mode 100644 index 00000000..ac314727 --- /dev/null +++ b/html/admin/qa-bundle/docs/appendix-a-glossary.html @@ -0,0 +1,863 @@ + + + + + + + Appendix A: GitHub Concepts & Glossary - GIT Going with GitHub + + + + + + + + +
      +

      Appendix A: GitHub Concepts & Glossary

      +
      +

      Listen to Episode 18: Glossary of Terms - a conversational audio overview of this chapter. Listen before reading to preview the concepts, or after to reinforce what you learned.

      +
      +
      +

      Reference companion to: Chapter 02: Understanding GitHub | Also relevant: all chapters

      +

      Authoritative source: GitHub Docs: Glossary

      +
      +

      Every Term You Need for Open Source Contribution

      +
      +

      This glossary is your reference for the entire two-day workshop. When you hear a term you don't recognize - check here first. Terms are grouped by category and also sorted alphabetically at the end.

      +
      +

      Learning Cards: Navigating the Glossary

      +
      +Screen reader users + +
        +
      • Press H to jump between term headings (h3 level) within each category section
        • +
      • Use the Elements List (NVDA+F7 or Insert+F6) to see all terms at once and type a few letters to filter
        • +
      • Jump to "Alphabetical Quick Reference" at the bottom for a flat A-Z lookup table
        • +
      +
      + +
      +Low vision users + +
        +
      • Each term is a bold h3 heading -- increase zoom and scan headings to browse terms quickly
        • +
      • The alphabetical table at the bottom works well at high zoom since each row is self-contained
        • +
      • Use Ctrl+F in your browser to search for any term by name
        • +
      +
      + +
      +Sighted users + +
        +
      • Terms are grouped by category (Parts 1-6) -- scan the bold headings to find the right group
        • +
      • Scroll to the bottom for the alphabetical quick reference table if you know the term name
        • +
      • Use Ctrl+F to jump directly to any term on the page
        • +
      +
      + + +

      Part 1: The Building Blocks

      +

      Repository (Repo)

      +

      A repository is the container for an entire project. It holds all the project's files, folders, documentation, and the complete history of every change ever made. Think of it as a project folder that has a time machine built in - you can see every version of every file going back to the beginning.

      +

      A repository lives on GitHub at an address like: https://github.com/owner/repo-name

      +

      Related terms: remote repository (the one on GitHub), local repository (a copy on your computer), upstream (the original repo), fork (your personal copy)

      +

      Organization (Org)

      +

      An organization is a group account on GitHub that multiple people can belong to. Open source projects typically live inside an organization rather than under a personal account. For example: https://github.com/microsoft/vscode - here microsoft is the organization and vscode is the repository.

      +

      Fork

      +

      A fork is a personal copy of someone else's repository, living in your own GitHub account. When you fork a repo, you get all its files and history. Changes you make to your fork do not automatically affect the original. To propose your changes to the original project, you submit a pull request.

      +

      Why fork? You do not have write access to most open source repos. Forking lets you work freely and then propose changes.

      +

      Remote

      +

      A remote is a connection to a repository hosted elsewhere (usually on GitHub). Your local Git repository can have multiple remotes. The most common remotes are:

      +
        +
      • origin - your fork on GitHub
        • +
      • upstream - the original repository you forked from
        • +
      +

      When you run git push origin main, you're pushing your local main branch to the remote named origin.

      +

      To see your remotes

      +
      git remote -v
      +

      To add a remote

      +
      git remote add upstream https://github.com/original-owner/repo.git
      +

      Origin

      +

      origin is the default name Git gives to the remote repository you cloned from. When you clone your fork, origin points to your fork on GitHub.

      +

      Commands like git push and git pull default to using origin unless you specify otherwise.

      +

      .gitignore

      +

      .gitignore is a special file in the root of your repository that tells Git which files or folders to ignore - meaning Git will not track or commit them.

      +

      Why use .gitignore?

      +
        +
      • Prevent committing temporary files (.DS_Store, Thumbs.db)
        • +
      • Ignore build outputs (dist/, build/, node_modules/)
        • +
      • Keep secrets out of Git (.env files, API keys, credentials)
        • +
      • Avoid committing IDE-specific files (.vscode/, .idea/)
        • +
      +

      Example .gitignore

      +
      # Dependencies
+node_modules/
+vendor/
+
+# Environment variables
+.env
+.env.local
+
+# Build outputs
+dist/
+build/
+*.log
+
+# OS files
+.DS_Store
+Thumbs.db
+
+# IDE
+.vscode/
+.idea/
      +

      Important: .gitignore only ignores untracked files. If you already committed a file, you must remove it from Git's tracking first:

      +
      git rm --cached filename
      +

      Then add it to .gitignore and commit the change.

      +

      Clone

      +

      Cloning copies a repository from GitHub to your local computer so you can work with it in VS Code or your preferred editor. When you clone, you get all the files and the complete history.

      +
      git clone https://github.com/your-username/repo-name.git
      +

      Fork vs Clone: Fork = your copy on GitHub. Clone = a copy on your computer. You usually clone your fork.

      +

      Branch

      +

      A branch is a separate line of development inside a repository. The main branch (often called main or master) holds the stable, released version of the project. When you want to add a feature or fix a bug, you create a new branch so your work doesn't affect main until it's ready.

      +

      Think of branches like parallel timelines - each branch is its own version of the project that can evolve independently and be merged back together later.

      +

      Common branch names

      +
        +
      • main - the primary, stable branch
        • +
      • develop - integration branch (not all projects have this)
        • +
      • feature/my-new-thing - convention for feature branches
        • +
      • fix/broken-button - convention for bug fix branches
        • +
      • docs/update-readme - convention for documentation-only branches
        • +
      +

      Commit

      +

      A commit is a saved snapshot of your changes at a moment in time. Every commit has:

      +
        +
      • A message describing what changed and why
        • +
      • A unique SHA hash (a fingerprint like a1b2c3d)
        • +
      • The author and timestamp
        • +
      • The changes (additions and deletions to files)
        • +
      +

      Good commit messages are in the imperative mood: "Fix typo in README" not "Fixed typo" or "Fixing typo."

      +

      Example of a well-written commit message:

      +
      Fix broken link in accessibility guide
+
+The link to the NVDA download page was using an outdated URL.
+Updated to the current direct download page.
+
+Fixes #42
      +

      Diff

      +

      A diff (short for difference) shows what changed between two versions of a file. Lines that were added are shown in green (with a + prefix). Lines that were removed are shown in red (with a - prefix). Lines that are unchanged are shown in grey for context.

      +

      Reading diffs is one of the core skills for code review. When you view a Pull Request's "Files Changed" tab, you are reading a diff.

      +

      Part 2: Collaboration Workflow

      +

      Issue

      +

      An issue is a discussion item in a GitHub repository. Issues are used for:

      +
        +
      • Reporting bugs
        • +
      • Requesting features or improvements
        • +
      • Asking questions
        • +
      • Discussing ideas
        • +
      • Tracking work items
        • +
      +

      Every issue gets a sequential number (like #42) and can have labels, assignees, milestones, and comments. Issues are the starting point for most contributions - it's best practice to open or find an issue before making code changes.

      +

      Pull Request (PR)

      +

      A pull request is a proposal to merge changes from one branch into another. When you have finished working on your fork or feature branch, you open a PR to say "here is my work - please review it and consider merging it."

      +

      A PR shows:

      +
        +
      • Which branch you want to merge into which target branch
        • +
      • The diff (all changes you made)
        • +
      • A description of what you changed and why
        • +
      • Discussion threads and reviews from others
        • +
      +

      The name "pull request" means you are requesting that the maintainers pull your changes into their project.

      +

      Code Review

      +

      Code review is the process of one or more collaborators reading and providing feedback on a PR before it is merged. Reviewers can:

      +
        +
      • Comment - leave a note on a line (not a formal verdict)
        • +
      • Approve - signal that they are happy with the changes
        • +
      • Request Changes - indicate that specific things need to be addressed before merging
        • +
      +

      Good code reviews are kind, specific, and constructive.

      +

      Merge

      +

      Merging is combining changes from one branch into another. When a PR is approved, a maintainer merges it. There are three merge strategies:

      + + + + + + + + + + + + + + + + + + + + + + + +
      StrategyWhat It DoesWhen Used
      Merge commitCreates a new commit recording the mergeDefault on most projects
      Squash and mergeCombines all PR commits into one commitKeeping history clean
      Rebase and mergeReplays commits on top of target branchLinear history projects
      +

      Merge Conflict

      +

      A merge conflict happens when two branches have both changed the same part of the same file in different ways. Git doesn't know which version to keep, so it pauses and asks you to resolve it manually.

      +

      Conflict markers look like this in a file:

      +
      <<<<<<< HEAD
+The current content on your branch
+=======
+The incoming content from the other branch
+>>>>>>> feature/other-branch
      +

      You resolve a conflict by editing the file to have the correct final content, removing the conflict markers, and then committing.

      +

      See Merge Conflicts Guide for step-by-step instructions.

      +

      Upstream

      +

      Upstream refers to the original repository that you forked from. When the upstream project has new changes that you want to bring into your fork, you "sync" your fork with upstream.

      +
      Your Fork → upstream → Original Repo
+Your changes flow this way: Original Repo ← Pull Request ← Your Fork
      +

      Label

      +

      Labels are colored tags applied to issues and PRs to categorize them. Common labels:

      +
        +
      • bug - something isn't working
        • +
      • enhancement - new feature or request
        • +
      • documentation - documentation-only change
        • +
      • good first issue - good for newcomers (look for this when finding your first contribution!)
        • +
      • help wanted - maintainers want community help
        • +
      • accessibility - accessibility-related
        • +
      +

      Milestone

      +

      A milestone groups issues and PRs toward a goal or deadline. For example: "v2.0 Release" or "Hackathon Day 1." Milestones show progress as a percentage of closed versus open items.

      +

      Project (GitHub Projects)

      +

      A GitHub Project is a flexible board for tracking work. It can show issues and PRs in table view, board view (kanban), or roadmap view. Projects are especially useful for hackathon-style coordination.

      +

      Part 3: People and Roles

      +

      Maintainer

      +

      A maintainer is someone with write or admin access to a repository. Maintainers review PRs, triage issues, manage releases, and make decisions about the project's direction. Most open source projects have between one and five core maintainers.

      +

      Contributor

      +

      Anyone who contributes to an open source project is a contributor. Contributing includes code, documentation, design, testing, translation, issue triage, and community support. You do not need commit access to contribute.

      +

      Triage

      +

      Triaging issues means reviewing new issues to categorize them, add labels, assign them, close duplicates, and communicate with the reporter. Triage is an important contribution that doesn't require coding skills.

      +

      Collaborator

      +

      A collaborator is someone who has been explicitly granted write access to a repository. Collaborators can commit directly to the repo without forking (though good practice is still to use branches and PRs).

      +

      Part 4: Common Abbreviations and Slang

      +

      These abbreviations appear frequently in GitHub comments, PR descriptions, and commit messages:

      + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + +
      TermStands ForMeaning
      LGTMLooks Good To MeInformal approval - "I reviewed it and it looks correct"
      WIPWork In ProgressThis PR is not ready for review yet
      nitNitpickA minor, optional suggestion - "not a blocker"
      RFCRequest For CommentsSeeking broad feedback on an idea or approach
      PTALPlease Take A LookAsking someone to review something
      IMO / IMHOIn My (Humble) OpinionSoftening a suggestion
      AFAICTAs Far As I Can Tell"Based on what I can see..."
      TILToday I LearnedSharing a discovery
      FYIFor Your InformationSharing information, no action needed
      EOD / EOWEnd of Day / WeekDeadline
      Closes #42-When merged, this PR closes issue #42 (automatic linking)
      Fixes #42-Same as Closes - use when the PR fixes a bug
      Resolves #42-Same as Closes - general resolution
      Refs #42References #42Links to the issue without closing it
      cc @usernameCarbon copyNotifying someone without requiring their action
      /ccSame as ccAlternative form
      stale-An issue or PR with no recent activity
      WONTFIX-The project won't address this issue (it's not a bug, or by design)
      upstream-The original repo you forked from
      downstream-A fork or project that depends on this one
      breaking change-A change that will break existing functionality for users
      +

      Part 5: Technical GitHub Concepts

      + +

      HEAD is Git's way of saying "where you are right now." It's a pointer to the current commit on the current branch.

      +
        +
      • When you're on main, HEAD points to the latest commit on main
        • +
      • When you switch branches, HEAD moves to that branch
        • +
      • HEAD^ or HEAD~1 means "the commit before HEAD"
        • +
      +

      You'll see HEAD referenced in commands like:

      +
      git reset HEAD~1  # Undo the last commit
+git diff HEAD     # Show uncommitted changes
      +

      Detached HEAD

      +

      A "detached HEAD" occurs when you check out a specific commit instead of a branch. You're no longer "on" a branch - just looking at a snapshot in time.

      +

      Why it happens

      +
      git checkout a1b2c3d  # Checking out a commit directly
      +

      What this means

      +
        +
      • Any commits you make won't belong to any branch
        • +
      • If you switch branches, those commits become "orphaned"
        • +
      +

      How to fix it

      +

      If you made commits in detached HEAD state and want to keep them:

      +
      git branch new-branch-name  # Creates a branch from your current position
+git checkout new-branch-name
      +

      Screen reader note: Git will warn you verbosely when entering detached HEAD state. Read the guidance carefully.

      +

      Stash

      +

      git stash temporarily saves your uncommitted changes and reverts your working directory to a clean state. It's useful when you need to switch branches but aren't ready to commit.

      +

      Common workflow

      +
      # You're working on branch A
+git stash  # Save your changes temporarily
+git checkout main  # Switch to main
+# Do something on main..
+git checkout branch-a  # Switch back
+git stash pop  # Restore your changes
      +

      Stash commands

      +
        +
      • git stash - save changes
        • +
      • git stash list - see what's stashed
        • +
      • git stash pop - restore and remove from stash
        • +
      • git stash apply - restore but keep in stash
        • +
      • git stash drop - delete a stash
        • +
      +

      Use case: "I need to quickly switch branches to check something, but I'm in the middle of work I'm not ready to commit."

      +

      Rebase

      +

      Rebasing is an alternative to merging. Instead of creating a merge commit, rebase moves (replays) your commits on top of another branch.

      +

      Merge

      +
      main:    A---B---C
+               \
+feature:        D---E---F
+                         \
+result:  A---B---C-------M (merge commit)
      +

      Rebase

      +
      main:    A---B---C
+feature:             D'---E'---F' (commits "replayed" on top of C)
      +

      When to use rebase

      +
        +
      • Keep a linear project history
        • +
      • Clean up your branch before submitting a PR
        • +
      • Incorporate upstream changes into your feature branch
        • +
      +

      When NOT to rebase

      +
        +
      • Shared branches (never rebase main or public branches)
        • +
      • After pushing to GitHub (unless you're comfortable force pushing)
        • +
      +

      Basic rebase workflow

      +
      git checkout feature-branch
+git rebase main
+# Fix any conflicts
+git push --force-with-lease  # See Force Push below
      +

      Screen reader note: Rebase conflicts are resolved the same way as merge conflicts (edit file, remove markers, git add, git rebase --continue).

      +

      Cherry-Pick

      +

      Cherry-picking applies a single commit from one branch onto another. It's like copy-pasting a commit.

      +

      Use case: You made a bug fix on the wrong branch and want to apply it to main without merging the whole branch.

      +
      git checkout main
+git cherry-pick a1b2c3d  # Apply commit a1b2c3d to main
      +

      When to use

      +
        +
      • Extract a single fix from a larger feature branch
        • +
      • Backport a bug fix to an older release branch
        • +
      • Undo a commit on one branch but keep it on another
        • +
      +

      Warning: Cherry-picking duplicates commits (creates a new commit with the same changes). Avoid cherry-picking commits that are part of an active feature branch - it causes confusion.

      +

      Fetch vs Pull

      +

      git fetch downloads changes from a remote repository but doesn't merge them into your current branch. It updates your local copy of remote branches (like origin/main or upstream/main) without touching your working files.

      +
      git fetch origin  # Download updates from origin
      +

      git pull = git fetch + git merge. It downloads changes and immediately merges them into your current branch.

      +
      git pull origin main  # Fetch + merge origin/main into current branch
      +

      When to use fetch

      +
        +
      • You want to see what changed without committing to merging
        • +
      • You want to review changes before integrating them
        • +
      • You're syncing upstream and want to inspect first
        • +
      +

      When to use pull

      +
        +
      • You know you want the latest changes merged immediately
        • +
      • You're working alone on a branch
        • +
      +

      Best practice for collaboration: Use fetch first, review with git log origin/main, then decide to merge or rebase.

      +

      Force Push

      +

      Force pushing (git push --force or git push -f) overwrites the remote branch with your local version, replacing its history. This is dangerous because it can delete commits that others have based work on.

      +

      When force push is okay

      +
        +
      • Your own feature branch that no one else is working on
        • +
      • After rebasing to clean up history before merging a PR
        • +
      +

      When force push is NEVER okay

      +
        +
      • The main branch
        • +
      • Shared branches where others have based work on your commits
        • +
      • Public branches with collaborators
        • +
      +

      Safer alternative: --force-with-lease

      +
      git push --force-with-lease origin feature-branch
      +

      --force-with-lease only force pushes if no one else has pushed to the remote branch since you last fetched. If someone pushed changes, the command fails and warns you.

      +

      Why force push is needed after rebase

      +

      When you rebase, Git rewrites commit history. The remote branch and your local branch now have conflicting histories. A normal git push fails. Force pushing resolves this by saying "trust my version."

      +

      Rule of thumb: If you're not sure whether you need to force push, you probably shouldn't.

      +

      SHA / Hash

      +

      Every commit, file, and tree in Git is identified by a SHA hash - a 40-character string of letters and numbers (e.g., a1b2c3d4e5f6...). You will see shortened versions like a1b2c3d in the GitHub UI. These are unique fingerprints.

      +

      Tag / Release

      +

      A tag marks a specific commit as significant - usually a version release like v1.0.0. Tags are permanent references (unlike branches, which move with each new commit). GitHub Releases are built on top of tags and can include release notes and downloadable files.

      +

      Actions / Workflow / CI/CD

      +

      GitHub Actions is an automation platform built into GitHub. Workflows are automated scripts (written in YAML) that run in response to events - like a PR being opened or code being pushed. CI/CD stands for Continuous Integration / Continuous Deployment.

      +

      In practice: when you open a PR, you will often see automated checks run (tests, linting, accessibility checks). These are GitHub Actions. See GitHub Actions & Workflows for a full explanation.

      +

      Status Check

      +

      A status check is the result of an automated test or workflow run on a PR. Status checks show as:

      +
        +
      • Green checkmark - all checks passed
        • +
      • Red X - one or more checks failed
        • +
      • Yellow dot - checks are still running
        • +
      +

      Maintainers often require status checks to pass before merging.

      +

      Webhook

      +

      A webhook is an automated notification that GitHub sends to another service when something happens (a push, a PR opened, etc.). Webhooks power integrations with tools like Slack, project management systems, and CI services. As a contributor, you typically don't configure webhooks - they are set up by maintainers.

      +

      GitHub Discussions

      +

      Discussions are a threaded forum built into GitHub, separate from Issues. They are used for open-ended conversation, Q&A, and community announcements. Not all projects use Discussions - some prefer issues or external forums.

      +

      Profile

      +

      Your GitHub profile is your public identity. It shows your name, bio, location, repositories, contribution activity (the green squares), and pinned projects. Your profile URL is https://github.com/your-username.

      +

      GitHub Copilot

      +

      GitHub Copilot is an AI-powered coding assistant. It suggests code, documentation, and commit messages. In this workshop, we use Copilot to help write issue descriptions, PR descriptions, documentation, and code. See GitHub Copilot for the full walkthrough.

      +

      Part 6: Community Files

      +

      Every healthy open source project has these files in the root of the repository:

      + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + +
      FilePurpose
      README.mdProject overview, how to use it, how to contribute
      CONTRIBUTING.mdHow to contribute - setup, workflow, PR guidelines
      CODE_OF_CONDUCT.mdCommunity standards and expectations
      LICENSELegal terms for using the software
      SECURITY.mdHow to report security vulnerabilities responsibly
      CHANGELOG.mdHistory of notable changes by version
      .github/ISSUE_TEMPLATE/Templates for bug reports, feature requests, etc.
      .github/PULL_REQUEST_TEMPLATE.mdTemplate for PR descriptions
      +

      Learning Cards: Alphabetical Quick Reference

      +
      +Screen reader users + +
        +
      • Press T to jump to the table, then use Ctrl+Alt+Arrow keys to navigate rows and columns
        • +
      • Each row has two cells: Term and Definition -- column headers are announced on first entry
        • +
      • For longer definitions, the table keeps them concise; see the full entry above for details
        • +
      +
      + +
      +Low vision users + +
        +
      • This table is designed for quick lookups -- each row fits on a single line at most zoom levels
        • +
      • If the table wraps awkwardly, try reducing zoom slightly or switching to a wider window
        • +
      • Bold term names in the left column create a visible scan line
        • +
      +
      + +
      +Sighted users + +
        +
      • Scan the left column alphabetically to find your term quickly
        • +
      • Definitions here are one-liners -- look up the full entry in Parts 1-6 above for examples and commands
        • +
      • Use Ctrl+F and type the term name to jump directly to it
        • +
      +
      + + +

      Alphabetical Quick Reference

      + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + +
      TermDefinition
      .gitignoreFile specifying which files Git should ignore
      AssigneePerson responsible for an issue or PR
      Base branchThe branch a PR merges INTO
      BranchA parallel line of development
      Cherry-pickApply a specific commit from one branch to another
      CI/CDContinuous Integration / Continuous Deployment
      CloneCopy a repo to your local computer
      Code reviewReviewing PR changes before merging
      CodespacesCloud-based VS Code development environment
      CollaboratorSomeone with write access to a repo
      CommentDiscussion note on an issue, PR, or specific line
      CommitA saved snapshot of changes
      Compare branchThe branch a PR merges FROM
      ContributorAnyone who contributes to a project
      Default branchThe main branch (usually named "main")
      Detached HEADChecking out a specific commit instead of a branch
      DiffThe visual difference between two file versions
      DiscussionsThreaded forum space for Q&A and community conversation
      Draft PRA PR not yet ready for review
      Feature previewOpt-in GitHub UI experiments
      FetchDownload remote changes without merging
      Force pushOverwrite remote branch history (use with caution)
      ForkYour personal copy of another repo
      GitThe version control system GitHub is built on
      GitHub PagesFree static site hosting from a GitHub repository
      GistShareable code snippet or small file collection
      Hash / SHAUnique identifier for a commit or object
      HEADPointer to your current commit/branch
      IssueA discussion item (bug, feature, question)
      LabelColored tag for categorizing issues/PRs
      MaintainerPerson with repo write/admin access
      MergeCombining changes from one branch into another
      Merge conflictWhen two branches changed the same content differently
      MilestoneA goal grouping related issues/PRs
      OrganizationA group GitHub account
      OriginDefault name for the remote you cloned from (your fork)
      PRPull Request
      PullFetch changes and merge them (git pull)
      Pull RequestProposal to merge your changes
      READMEThe main project documentation file
      RebaseReplay commits on top of another branch
      ReleaseA versioned snapshot with notes and downloads
      RemoteA connection to a repository hosted elsewhere
      RepositoryA project container with all files and history
      ReviewFormal feedback on a PR (approve/comment/request changes)
      SHAUnique hash identifier
      Squash mergeCombining all PR commits into one
      StashTemporarily save uncommitted changes
      Status checkAutomated pass/fail result shown on a PR
      TagA permanent named reference to a specific commit
      TriageReviewing and categorizing new issues
      UpstreamThe original repo you forked from
      WikiMulti-page documentation space in a repository
      TagA permanent named reference to a specific commit
      TriageReviewing and categorizing new issues
      UpstreamThe original repo you forked from
      +
      +

      Next: Appendix B: Screen Reader Cheat Sheet
      Teaching chapter: Chapter 02: Understanding GitHub

      + +
      + + + + diff --git a/html/admin/qa-bundle/docs/appendix-b-screen-reader-cheatsheet.html b/html/admin/qa-bundle/docs/appendix-b-screen-reader-cheatsheet.html new file mode 100644 index 00000000..ffd0ed64 --- /dev/null +++ b/html/admin/qa-bundle/docs/appendix-b-screen-reader-cheatsheet.html @@ -0,0 +1,1659 @@ + + + + + + + Appendix B: Screen Reader Cheat Sheet - GIT Going with GitHub + + + + + + + + +
      +

      Appendix B: Screen Reader Cheat Sheet

      +
      +

      Listen to Episode 19: Screen Reader Cheat Sheet - a conversational audio overview of this chapter. Listen before reading to preview the concepts, or after to reinforce what you learned.

      +
      +
      +

      Reference companion to: Chapter 02: Understanding GitHub | Also relevant: Chapter 03, Chapter 11

      +

      Authoritative source: GitHub Docs: Keyboard shortcuts

      +
      +

      GitHub Navigation with NVDA, JAWS, and VoiceOver

      +
      +

      How to use this sheet: Keep it open in a second window or print it. Commands are organized by task so you can find what you need quickly while you work. All commands are keyboard-only - no mouse required.

      +
      +

      Learning Cards: Using This Cheat Sheet

      +
      +Screen reader users + +
        +
      • Use heading navigation (H key) to jump between task categories -- each section is an h2 heading
        • +
      • Open the Elements List (NVDA+F7 or Insert+F6) and switch to the Headings tab to see all sections at once
        • +
      • Tables list commands in the left column and actions in the right -- use Ctrl+Alt+Arrow keys to navigate
        • +
      +
      + +
      +Low vision users + +
        +
      • Keep this open in a second browser tab or print it for side-by-side reference while working
        • +
      • Command tables are compact -- increase zoom to 150-200% and the two-column layout stays readable
        • +
      • Key names are in backtick code formatting which gives them a distinct visual border
        • +
      +
      + +
      +Sighted users + +
        +
      • Sections are organized by task (navigation, typing, dropdowns, troubleshooting) -- scan the h2 headings
        • +
      • The "Per-Screen-Reader Command Reference" section groups everything by NVDA, JAWS, and VoiceOver
        • +
      • Bookmark this page -- it is the single fastest reference when you forget a key combination
        • +
      +
      + + +

      Screen Reader Mode Basics

      +

      Before navigating GitHub, understand the two fundamental modes that all screen readers use on the web:

      +

      Browse Mode (also called Virtual Cursor / Reading Mode)

      +

      This is your primary mode for reading and navigating pages. The screen reader intercepts keystrokes and uses them as navigation commands - for example, pressing H jumps to the next heading rather than typing the letter H.

      + + + + + + + + + + + + + + + + + + + +
      Screen ReaderHow to know you're in Browse Mode
      NVDALower-pitched sound when switching; NVDA says "browse mode"
      JAWSJAWS says "virtual cursor on"
      VoiceOverNo mode switching needed - VoiceOver uses the VO modifier keys
      +

      Focus Mode (also called Forms or Application Mode)

      +

      This mode is for typing and interacting with form fields, text areas, buttons, and interactive widgets. Your keystrokes go directly to the web page instead of being captured by the screen reader.

      + + + + + + + + + + + + + + + + + + + + + + + +
      Screen ReaderToggle Focus/Browse ModeWhen to use
      NVDANVDA+Space (Insert+Space or CapsLock+Space)Type in comment boxes, issue titles, PR descriptions
      JAWSJAWS+Z (Insert+Z) or automaticSame
      VoiceOverVO+Shift+Down to interact with an elementSame
      +
      +

      Rule of thumb: Browse mode to navigate, Focus mode to type.

      +
      +

      Quick Navigation Keys (Browse Mode)

      +

      These single-key shortcuts work in Browse Mode (NVDA and JAWS). VoiceOver users with Quick Nav enabled use the same keys.

      +

      Heading Navigation - Your Most-Used Tool

      +

      GitHub structures pages with headings. Jumping between headings is the fastest way to navigate.

      + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + +
      KeyActionVoiceOver
      HNext heading (any level)H (Quick Nav on)
      Shift+HPrevious headingShift+H
      1Next h1 (page title)1
      2Next h2 (section heading)2
      3Next h3 (issue/PR titles are h3)3
      4Next h4 (commit titles in PRs)4
      +

      Landmark Navigation - Jump Between Page Regions

      +

      Landmarks are named regions of a page (navigation, main content, sidebar, etc.). GitHub uses landmarks heavily.

      + + + + + + + + + + + + + + + + + + +
      KeyActionVoiceOver
      DNext landmark / regionVO+U → Landmarks rotor
      Shift+DPrevious landmarkSame, navigate backwards
      +

      GitHub landmarks you will encounter

      + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + +
      Landmark LabelWhat It Contains
      Navigation MenuYour avatar menu and global nav
      Repository navigationCode, Issues, PRs, Actions tabs
      MainThe primary page content
      Repository files navigationREADME display
      Pull requests listThe list of PRs
      Search Results ListIssues or PR list results
      Add a commentComment submission form
      PaginationNext/Previous page buttons
      + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + +
      KeyActionJAWS EquivalentVoiceOver
      KNext linkTab or UVO+U → Links rotor
      Shift+KPrevious linkShift+U-
      BNext buttonBVO+U → Buttons rotor
      Shift+BPrevious buttonShift+B-
      F or ENext edit/form fieldFVO+U → Form Controls
      TabNext interactive element (any type)TabTab
      Shift+TabPrevious interactive elementShift+TabShift+Tab
      Enter / SpaceActivate link or buttonSameVO+Space
      +

      List and Table Navigation

      + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + +
      KeyActionNotes
      LNext listUseful for spotting issue/PR lists
      INext list itemNavigate within a list
      TNext tableUse this for the files table in a repo
      Ctrl+Alt+→Move right in a table cellNavigate table columns
      Ctrl+Alt+←Move left in a table cell
      Ctrl+Alt+↓Move down in a table (next row)Navigate file list rows
      Ctrl+Alt+↑Move up in a table
      +

      The Elements List - Your Navigation Superpower

      +

      This is one of the most powerful tools for navigating complex pages. It opens a dialog listing all headings, links, buttons, form fields, or landmarks on the page.

      + + + + + + + + + + + + + + + + + + + + + + + +
      Screen ReaderOpen Elements ListWhat It Shows
      NVDANVDA+F7 (Insert+F7 or CapsLock+F7)Headings, Links, Form fields, Buttons, Landmarks (tabs within the dialog)
      JAWSInsert+F6 (headings) / Insert+F7 (links)Headings list / Links list
      VoiceOverVO+URotor - switch between Headings, Links, Landmarks, Form Controls
      +

      How to use it

      +
        +
      1. Press the keyboard shortcut above
        2. +
      2. Navigate between the tabs (Headings, Links, etc.) with Tab or arrow keys
        3. +
      3. Type to filter the list (e.g., type "new issue" to find the New Issue button)
        4. +
      4. Press Enter to jump to the item on the page
        5. +
      +

      Per-Screen-Reader Command Reference

      +

      A compact reference organized by screen reader. For task-based navigation guides (navigating a PR, leaving a comment, etc.), see the sections below.

      +

      NVDA (Windows)

      +

      Single-key navigation (Browse Mode)

      + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + +
      KeyMoves to
      H / Shift+HNext / previous heading
      1-6Next heading of that level
      KNext link
      BNext button
      F or ENext form field
      TNext table
      DNext landmark region
      LNext list
      INext list item
      +

      Mode switching and reading

      + + + + + + + + + + + + + + + + + + + + + + + + + + + +
      KeyAction
      Insert+SpaceToggle Browse / Focus Mode
      Insert+F7Elements list (headings, links, form fields, buttons)
      NVDA+↓Start reading from cursor (Say All)
      NVDA+↑Read current line
      CtrlStop reading
      +

      JAWS (Windows)

      +

      Single-key navigation (Virtual Cursor)

      + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + +
      KeyMoves to
      H / Shift+HNext / previous heading
      1-6Next heading of that level
      UNext unvisited link
      KNext link
      BNext button
      FNext form field
      TNext table
      RNext landmark region
      LNext list
      INext list item
      +

      Mode switching and reading

      + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + +
      KeyAction
      Insert+ZToggle Virtual PC Cursor (Browse / Focus)
      Num Pad PlusExit forms mode (open PC Cursor)
      Insert+F6Headings list
      Insert+F7Links list
      Insert+↓Start reading from cursor (Say All)
      Insert+↑Read current line
      CtrlStop reading
      +

      VoiceOver (macOS)

      +

      Activate VoiceOver: Cmd+F5. The VO modifier key is Control+Option (abbreviated VO).

      +

      Rotor navigation: Open with VO+U, use ←/→ to switch between element types (Headings, Links, Form Controls, Tables, Landmarks), and ↑/↓ to navigate within a type.

      + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + +
      CommandAction
      VO+UOpen Rotor
      VO+Right / VO+LeftMove forward / backward
      VO+SpaceActivate current element
      VO+Shift+DownInteract with element (enter Focus Mode)
      VO+Shift+UpStop interacting
      VO+AStart reading from cursor
      CtrlStop reading
      Cmd+F5Start / stop VoiceOver
      +

      Learning Cards: Task-Based Navigation

      +
      +Screen reader users + +
        +
      • The sections below are organized by GitHub page type -- jump to the page you are currently on
        • +
      • Each table shows Goal in the left column and Key Sequence in the right -- read left-to-right per row
        • +
      • Practice one page's commands at a time rather than memorizing everything at once
        • +
      +
      + +
      +Low vision users + +
        +
      • Each page section has a compact table -- at high zoom, the two-column layout reads naturally
        • +
      • Key sequences are shown in backtick formatting for clear visual distinction from descriptions
        • +
      • Open the matching GitHub page side by side and try each key sequence as you read
        • +
      +
      + +
      +Sighted users + +
        +
      • Find the section matching the GitHub page you are on (Repository, Issue, Pull Request, etc.)
        • +
      • Key sequences are listed in the order you would typically use them on that page
        • +
      • The Goal column tells you what happens -- scan it to find the action you need
        • +
      +
      + + + +

      Repository Main Page

      + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + +
      GoalKey Sequence
      Find the repo name and description1 - jumps to the h1 heading (the repo name)
      Jump to repo navigation tabsD to "Repository navigation" landmark
      Open the files tableT (next table)
      Navigate filesCtrl+Alt+Down Arrow for next row, Ctrl+Alt+Right Arrow for next column
      Open a fileEnter on the filename
      Find the Clone or Download buttonB (next button after the h1)
      Switch branchesB to find the branch button, then Enter
      Search for a fileF to reach the "go to file" field, then type filename
      +

      Issues List Page

      + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + +
      GoalKey Sequence
      Find the issue list1 then L (next list) or D to "Search Results List" landmark
      Navigate issue titles3 (issue titles are h3 headings)
      Navigate list itemsI (next list item within the search results list)
      Open an issueEnter on the issue title link
      Open in a new tabCtrl+Enter
      Search or filter issuesF to the edit field, type search query, then Enter
      Create a new issueTab from search field until "New issue" link
      Filter by labelTab to the filter toolbar buttons, Enter, then arrow keys in the dropdown
      +

      Issue Detail Page

      + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + +
      GoalKey Sequence
      Read the issue description2 to "Description" heading
      Read activity and comments2 to "Activity" heading, then Down Arrow to read
      Jump to the comment boxD to "Add a comment", then E to the edit field
      Type a commentSwitch to Focus mode (NVDA+Space), then type
      Submit the commentTab to the "Comment" button then Enter - or Ctrl+Enter from the text area
      Close the issueTab to the "Close" button, then Enter
      Navigate assignees and labels sidebar3 (sidebar items are h3 headings)
      +

      Pull Requests List Page

      + + + + + + + + + + + + + + + + + + + + + + + + + + + +
      GoalKey Sequence
      Find the PR listD to "Pull requests list" landmark
      Navigate PR titlesTab (no per-item heading semantics - tab through)
      Open a PREnter on the PR title
      Create a new pull requestK to the "New pull request" link
      Filter PRsF to the search field, then Enter
      +

      Pull Request Detail - Conversation Tab

      + + + + + + + + + + + + + + + + + + + + + + + + + + + +
      GoalKey Sequence
      Read PR description2 to the first h2 heading
      Navigate comment threads3 (comments are h3 headings)
      Open pull request tabsD to "Pull request tabs", then K to navigate links
      Add a commentD to "Add a comment", then E, then Focus mode, then type
      Submit reviewB to the "Submit review" button
      +

      Pull Request Detail - Commits Tab

      + + + + + + + + + + + + + + + + + + + + + + + +
      GoalKey Sequence
      Switch to Commits tabD to "Pull request navigation tabs", then Tab between tab controls, then Left or Right Arrow
      Navigate commits by date3 (date headings are h3)
      Navigate individual commits4 (commit names are h4) or I (list items)
      Open a commitEnter on the commit heading or link
      +

      Pull Request Detail - Files Changed Tab

      + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + +
      GoalKey Sequence
      Navigate to Files ChangedD to "Pull request navigation tabs", then Left or Right Arrow to "Files changed", then Enter
      Navigate file headingsH or 3
      Find a specific fileE to "Filter changed files" field, then type filename
      Navigate file tree2 to "file tree", then Up Arrow or Down Arrow
      Navigate diff linesNVDA+Space for Focus mode, then arrow keys in the diff table
      Read across a diff rowCtrl+Alt+Right Arrow (columns: line number, change type, content)
      Comment on a lineFocus the line, then Enter (activates comment mode)
      Multi-line commentFocus start line, then Shift+Down Arrow to extend, then Enter
      Submit review1 then B to "Submit review" button
      +

      Checking and Enabling Feature Previews

      +

      GitHub Feature Previews are opt-in UI improvements. For screen reader users, two are especially important: New Issues Experience and New Files Changed Experience. Both may already be active - or may have graduated out of Feature Preview entirely.

      +

      NVDA / JAWS (Browse Mode)

      + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + +
      GoalKey Sequence
      Open User MenuB repeatedly until "Open user navigation menu, button" → Enter
      Open Feature Preview panel↓ or K to "Feature preview" → Enter
      Navigate the feature list↓ or I (list items)
      Check if a feature is enabledToggle announces "Pressed" or "Disable" = enabled; "not Pressed" or "Enable" = disabled
      Enable a featureEnter or Space on the toggle when it is not Pressed
      Feature not listedFeature has graduated - active automatically, no action needed
      +

      VoiceOver (macOS)

      + + + + + + + + + + + + + + + + + + + + + + + +
      GoalKey Sequence
      Open User MenuVO+U → Buttons → "Open user navigation menu" → Enter
      Open Feature Preview panelVO+Down Arrow to "Feature preview" → VO+Space
      Check if a feature is enabledToggle announces "checked" = enabled; "unchecked" = disabled
      Enable a featureVO+Space on an unchecked toggle
      +
      +

      See Pre-Workshop Setup, Step 4 for full details on what each feature enables and why it matters for screen reader users.

      +
      +

      Typing and Submitting Content

      +

      Entering text in GitHub (Focus Mode required)

      +
        +
      1. Navigate to the text field using Browse Mode: F or E for edit fields, Tab for any interactive element
        2. +
      2. Switch to Focus Mode:
          +
        • NVDA: Insert+Space
          • +
        • JAWS: Insert+Z (or it switches automatically)
          • +
        • VoiceOver: VO+Shift+Down to interact with the text area
          • +
        +
        3. +
      3. Type your content
        4. +
      4. Return to Browse Mode when done typing:
          +
        • NVDA: Insert+Space
          • +
        • JAWS: Insert+Z
          • +
        • VoiceOver: VO+Shift+Up to stop interacting
          • +
        +
        5. +
      +

      Markdown formatting shortcuts in GitHub text areas

      +

      These work while in Focus Mode inside a GitHub text area:

      + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + +
      ShortcutEffect
      Ctrl+BBold
      Ctrl+IItalic
      Ctrl+EInline code
      Ctrl+K[Insert link]
      Ctrl+Shift+.> Blockquote
      Ctrl+Shift+LUnordered list
      Ctrl+Shift+7Ordered list
      + +

      GitHub uses popup flyout menus for labels, assignees, reviewers, and branch selection. Here is how to handle them:

      +
      Step 1: Navigate to the button (D for landmark, B for button, or Tab)
+Step 2: Activate the button (Enter or Space) - flyout opens
+Step 3: Type to filter results OR use ↑/↓ arrow keys to navigate
+Step 4: Select an item (Enter)
+Step 5: Close the flyout (Esc) - selections apply on close
      +

      VoiceOver users

      +
      Step 1: Navigate to the button with Tab or VO+Right
+Step 2: Activate with VO+Space
+Step 3: VO+Down to enter the flyout
+Step 4: VO+Right/Left to navigate items
+Step 5: VO+Space to select, Esc to close
      +

      GitHub Built-In Keyboard Shortcuts

      +

      GitHub has a dedicated keyboard shortcut system built into every page. These are completely separate from your screen reader's navigation keys - they are JavaScript-powered shortcuts that trigger GitHub actions directly without using the mouse.

      +

      Using GitHub shortcuts alongside a screen reader

      +

      The key issue: when your screen reader is in Browse Mode, it intercepts keystrokes before they reach the page. GitHub's shortcut system relies on the page receiving the keystroke directly. Here is how to unlock them:

      + + + + + + + + + + + + + + + + + + + +
      Screen ReaderHow to use GitHub shortcuts
      NVDAPress NVDA+Space to enter Focus Mode, use the shortcut, then NVDA+Space to return to Browse Mode
      JAWSPress Insert+Z to toggle Virtual Cursor off, use the shortcut, then Insert+Z to turn it back on
      VoiceOverGitHub shortcuts generally work without mode switching - VoiceOver handles this differently
      +

      Exceptions that always work in Browse Mode: ? (shows all shortcuts) and S// (focus the search bar) work at any time because they immediately move browser focus to an interactive element.

      +

      Practical sequence for G shortcuts

      +
      Step 1: Press NVDA+Space (or Insert+Z in JAWS) - enter Focus Mode
+Step 2: Press G, pause half a second
+Step 3: Press the second key (I, P, A, etc.)
+Step 4: Press NVDA+Space to return to Browse Mode on the new page
      +

      Discover shortcuts on any page - The ? Key

      +
      +

      Start here every time you're on an unfamiliar GitHub page. The ? key opens GitHub's built-in keyboard shortcut help dialog. It lists every shortcut for the exact page you are on - the set changes depending on whether you are on a repository, an issue, a PR, the notifications inbox, etc.

      +
      +

      Press ? (Shift+/) from any GitHub page when not inside a text field to open the shortcut dialog.

      +

      Reading the shortcut dialog with a screen reader

      +

      The dialog is a standard ARIA modal (role="dialog"). When it opens, browser focus moves inside it automatically.

      +
      NVDA
      +
      Step 1: Press Shift+/ to open the dialog → NVDA announces "dialog" and reads the title
+Step 2: Press NVDA+Space to enter Browse Mode inside the dialog
+Step 3: Press H to navigate between shortcut categories (they are h2 headings)
+Step 4: Press ↓ to read each shortcut row in the category
+Step 5: Press Escape or Tab to the Close button → Enter to close
      +
      JAWS
      +
      Step 1: Press Shift+/ → JAWS announces the dialog and its title
+Step 2: Use ↓ to read through the contents, or Ctrl+Home to start from the top
+Step 3: Use Tab to move between interactive elements (the Close button)
+Step 4: Press Escape to close
      +
      VoiceOver (macOS)
      +
      Step 1: Press Shift+/ → VoiceOver announces the dialog
+Step 2: Use VO+Right to move through the dialog contents
+Step 3: Use VO+Command+H to jump between heading categories
+Step 4: Press Escape or navigate to the Close button (VO+Space)
      +
      Key facts about the shortcut dialog
      +
        +
      • It is context-aware - the shortcuts shown change based on your current page
        • +
      • It is always current - GitHub automatically updates it when they add new shortcuts
        • +
      • The dialog is divided into sections: Site-wide, Source code browsing, Issues, Pull requests, Notifications, etc. - only sections relevant to the current page appear
        • +
      • You do not need to be in Focus Mode to open it - ? works from Browse Mode
        • +
      +

      Site-wide - work on every GitHub page

      + + + + + + + + + + + + + + + + + + + +
      ShortcutAction
      ?Show all keyboard shortcuts for the current page
      S or /Focus the search bar
      G then NGo to your Notifications
      +

      Repository navigation - on any repository page

      + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + +
      ShortcutActionScreen reader note
      G then CGo to the Code tabSafe - use Focus Mode first
      G then IGo to the Issues tabSafe - use Focus Mode first
      G then PGo to the Pull Requests tabSafe - use Focus Mode first
      G then AGo to the Actions tabSafe - use Focus Mode first
      G then WGo to the Wiki tabSafe - use Focus Mode first
      G then GGo to the Discussions tabSafe - use Focus Mode first
      . (period)Open repository in github.dev, same tabOpens VS Code in your browser
      > (Shift+Period)Open repository in github.dev, new tabPreserves your GitHub page - preferred
      TOpen file finder (Go to File)Conflicts with NVDA T = next table - use F to find the field instead
      +
      +

      Shortcut spotlight - . and >: These open github.dev, which is VS Code running inside your browser - same keyboard shortcuts, same screen reader mode. > opens a new tab so you keep your current GitHub page. This is the fastest way to start editing a file without installing anything.

      +
      +

      Source code browsing - viewing a file

      + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + +
      ShortcutActionScreen reader note
      TActivate the file finderConflicts with NVDA table nav - use F for the field instead
      LJump to a specific line numberConflicts with NVDA L = next list - use Focus Mode first
      WSwitch to a new branch or tag-
      YExpand URL to its permanent canonical formUseful for linking to a specific commit of a file - the URL never changes
      IShow or hide comments on diffs-
      AShow or hide annotations on diffs-
      BOpen blame view (who changed each line, and when)Conflicts with NVDA B = next button - use Focus Mode first
      +

      Issue and pull request lists

      +

      These shortcuts work on the Issues list page and the Pull Requests list page:

      + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + +
      ShortcutActionScreen reader note
      CCreate a new issueUse Focus Mode first
      Ctrl+/ (Win) or Cmd+/ (Mac)Focus the issues or PR search barWorks in Browse Mode - uses Ctrl
      UFilter by authorUse Focus Mode first
      LFilter by or edit labelsConflicts with NVDA L = next list - use Focus Mode
      MFilter by or edit milestonesUse Focus Mode first
      AFilter by or edit assigneeUse Focus Mode first
      O or EnterOpen the currently selected issue or PR-
      +

      Issue and pull request detail pages

      +

      When viewing an open issue or pull request:

      + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + +
      ShortcutAction
      QRequest a reviewer (pull requests only)
      MSet a milestone
      LApply a label
      ASet an assignee
      XLink an issue from the same repository
      Ctrl+Shift+P (Win) or Cmd+Shift+P (Mac)Toggle Write and Preview tabs in the comment editor
      RQuote selected text in your reply - select text first, then press R
      +
      +

      Tip for R - quote a specific part of a comment: In Browse Mode, select the text you want to quote by holding Shift and pressing arrow keys. Then press R - GitHub puts it directly into the comment box as a Markdown blockquote, with the author attributed. This is much faster than manually typing >.

      +
      +

      Comments - inside any text area (Focus Mode required)

      +

      These shortcuts work while typing in any GitHub comment or description field:

      + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + +
      ActionWindows / LinuxMac
      BoldCtrl+BCmd+B
      ItalicCtrl+ICmd+I
      Inline codeCtrl+ECmd+E
      Insert linkCtrl+KCmd+K
      Paste as Markdown link (over selected text)Ctrl+VCmd+V
      Paste HTML link as plain textCtrl+Shift+VCmd+Shift+V
      BlockquoteCtrl+Shift+.Cmd+Shift+.
      Ordered listCtrl+Shift+7Cmd+Shift+7
      Unordered listCtrl+Shift+8Cmd+Shift+8
      Toggle Write / PreviewCtrl+Shift+PCmd+Shift+P
      Insert a code suggestion blockCtrl+GCmd+G
      Submit commentCtrl+EnterCmd+Enter
      +
      +

      The most important one: Ctrl+Enter submits a comment from inside the text area - you do not have to Tab to the Submit button and press Enter. Your focus stays in context.

      +

      Insert suggestion (Ctrl+G): Select the code you want to suggest a change to (in the diff), then press Ctrl+G. GitHub wraps it in a ```suggestion block. The PR author can apply your exact change with one button press.

      +
      +

      Files Changed tab in pull requests

      + + + + + + + + + + + + + + + + + + + +
      ShortcutAction
      COpen the commits dropdown - filter which commits are shown in the diffs
      TMove focus to the "Filter changed files" search field
      Ctrl+Shift+Enter (Win) or Cmd+Shift+Enter (Mac)Submit a review comment
      +

      Notifications page

      +

      On your Notifications page (github.com/notifications):

      + + + + + + + + + + + + + + + + + + + + + + + +
      ShortcutAction
      EMark notification as done
      Shift+UMark as unread
      Shift+IMark as read
      Shift+MUnsubscribe from thread
      +

      GitHub Actions

      +

      On any Actions page in a repository:

      + + + + + + + + + + + + + + + + + + + + + + + + + + + +
      ShortcutAction
      G then FGo to the workflow file
      Shift+T or TToggle timestamps in logs
      Shift+F or FToggle full-screen log view
      EscExit full-screen log view
      Ctrl+Space (Win) or Cmd+Space (Mac)Get AI suggestions in the workflow editor
      +

      Projects (board and table view)

      + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + +
      ShortcutAction
      Ctrl+F or Cmd+FFocus the filter field
      EnterToggle edit mode for the focused cell
      EscCancel editing
      Shift+SpaceSelect item
      SpaceOpen selected item
      EArchive selected items
      Ctrl+Shift+\ or Cmd+Shift+\Open row actions menu
      +
      +

      Keep the official reference handy: github.com/keyboard-shortcuts - and press ? on any GitHub page for the context-specific subset.

      +
      +

      Common Navigation Patterns - Quick Reference

      +

      Print or bookmark this section:

      + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + +
      ActionKeys
      Switch browse or focus modeNVDA+Space or JAWS+Z
      Elements listNVDA+F7 / JAWS+F6 or F7 / VO+U
      Next heading (any level)H
      Next h3 (issue or PR title)3
      Next landmark or regionD
      Next linkK
      Next buttonB
      Next form fieldF or E
      Next list itemI
      Jump to file tableT then Ctrl+Alt+Arrow keys
      Activate itemEnter or Space
      Submit commentCtrl+Enter (in text area)
      Open dropdownEnter, then Up or Down Arrow, then Enter, then Escape
      +

      Troubleshooting Common Issues

      +

      "The page doesn't match the instructions"

      +
        +
      • Solution: Maximize your browser window. GitHub's layout changes at smaller widths, and landmarks/headings may appear in different positions. Full-screen or maximized window gives the most consistent experience.
        • +
      +

      "I'm hearing too much or navigating too slowly"

      +
        +
      • Disable hovercards in GitHub Accessibility Settings (see Pre-Workshop Setup)
        • +
      • Adjust your screen reader verbosity settings
        • +
      • Use NVDA+F7 / VO+U to get a filtered list rather than tabbing through everything
        • +
      • NVDA reads GitHub too slowly: In NVDA Settings → Browse Mode → increase "Maximum number of characters on one line" to 10000. This prevents NVDA from pausing to wrap long lines.
        • +
      +

      "I pressed H but it's typing the letter H"

      +
        +
      • You are in Focus Mode - press NVDA+Space (or JAWS+Z) to return to Browse Mode
        • +
      • In Browse Mode, H is a navigation key, not a typing key
        • +
      +

      "I can't find the comment box"

      +
        +
      • Use D to navigate to the "Add a comment" landmark
        • +
      • Then E or F to jump to the edit field
        • +
      • Switch to Focus Mode before typing
        • +
      +

      "The diff/code area is hard to navigate"

      +
        +
      • The Files Changed tab requires Focus Mode to navigate the diff table
        • +
      • Use NVDA+Space to enter Focus Mode, then use arrow keys
        • +
      • Use Ctrl+Alt+Arrow keys to move between table cells
        • +
      +

      Official Screen Reader Resources

      + +

      Keyboard Shortcuts in Other Appendices

      +

      This cheat sheet covers GitHub web navigation and screen reader commands. Additional keyboard shortcuts for specific tools are documented in:

      + + + + + + + + + + + + + + + + + + + + + + + +
      TopicLocation
      VS Code keyboard navigation and accessibilityAppendix M - VS Code Accessibility Reference
      GitHub Copilot Chat and inline suggestionsAppendix K - GitHub Copilot Reference
      VS Code setup and configuration shortcutsChapter 5 - VS Code Basics
      GitHub Copilot activation and model switchingChapter 13 - GitHub Copilot
      +

      Screen Reader Compatibility Notes

      +

      The commands in this cheat sheet have been written for and tested with the following screen readers:

      + + + + + + + + + + + + + + + + + + + + + + + + + + + +
      Screen ReaderPlatformVersion TestedNotes
      NVDAWindows2025.3.3+Free, open source. Primary screen reader for this workshop.
      JAWSWindows2026+Commercial. Trial available.
      VoiceOvermacOSBuilt into macOS Sonoma+No installation required.
      +

      If a command doesn't work as described

      +
        +
      1. Check that you are in the correct mode (Browse Mode vs. Focus Mode)
        2. +
      2. Verify your screen reader version - older versions may use different key assignments
        3. +
      3. Check GitHub's own shortcut dialog (? key) for the current page's shortcuts
        4. +
      4. See Troubleshooting above for common fixes
        5. +
      +
      +

      Next: Appendix C: Markdown Reference
      Back: Appendix A: Glossary
      Teaching chapter: Chapter 02: Understanding GitHub

      + +
      + + + + diff --git a/html/admin/qa-bundle/docs/appendix-c-markdown-reference.html b/html/admin/qa-bundle/docs/appendix-c-markdown-reference.html new file mode 100644 index 00000000..c7eed5f5 --- /dev/null +++ b/html/admin/qa-bundle/docs/appendix-c-markdown-reference.html @@ -0,0 +1,2552 @@ + + + + + + + Appendix C: Markdown and GitHub Flavored Markdown - Complete Guide - GIT Going with GitHub + + + + + + + + +
      +

      Appendix C: Markdown and GitHub Flavored Markdown - Complete Guide

      +
      +

      Listen to Episode 22: GitHub Flavored Markdown - a conversational audio overview of this chapter. Listen before reading to preview the concepts, or after to reinforce what you learned.

      +
      +
      +

      Reference companion to: Chapter 06: Working with Pull Requests | Also relevant: Chapter 12, Chapter 17

      +

      Authoritative source: GitHub Docs: Basic writing and formatting syntax

      +
      +

      From First Paragraph to Polished Repository - Everything You Need to Know

      +
      +

      Who this is for: Everyone. Whether you have never written a single line of Markdown or you already know the basics and want to master the GitHub-specific extensions, this guide takes you from zero to confident. We start with what Markdown is and why it matters, walk through every foundational element with examples, and then cover the GitHub Flavored Markdown (GFM) features you will encounter in real repositories - alert blocks, Mermaid diagrams, math, footnotes, and more.

      +

      Why this matters for this workshop: Every issue you file, every pull request you open, every README you read or write, every comment you post on GitHub uses Markdown. It is the language of collaboration on GitHub. Mastering it means your contributions look polished, your bug reports are clear, and your documentation is accessible to everyone - including screen reader users.

      +

      How to use this guide: Read it straight through if you are new to Markdown. If you already know the basics, use the navigation below to jump to the topic you need. Every section includes the raw Markdown you type, what it looks like when rendered, and screen reader behavior notes so you know exactly what assistive technology users will experience.

      +
      +

      Table of Contents

      +

      Part 1 - Markdown Foundations

      +
        +
      1. What Is Markdown?
        2. +
      2. Where You Will Use Markdown in This Workshop
        3. +
      3. How to Practice as You Read
        4. +
      4. Paragraphs and Line Breaks
        5. +
      5. Headings
        6. +
      6. Emphasis - Bold, Italic, and Bold Italic
        7. +
      7. Strikethrough
        8. +
      8. Lists - Ordered and Unordered
        9. +
      9. Nested Lists and Mixed Lists
        10. +
      10. Links
        11. +
      11. Images
        12. +
      12. Blockquotes
        13. +
      13. Inline Code and Code Blocks
        14. +
      14. Horizontal Rules
        15. +
      15. Escaping Special Characters
        16. +
      16. Tables
        17. +
      +

      Part 2 - GitHub Flavored Markdown (GFM)

      +
        +
      1. What Is GitHub Flavored Markdown?
        2. +
      2. Alert and Callout Blocks
        3. +
      3. Collapsible Sections with Details and Summary
        4. +
      4. Task List Checkboxes
        5. +
      5. Syntax Highlighting in Fenced Code Blocks
        6. +
      6. Mermaid Diagrams
        7. +
      7. Math Expressions with LaTeX
        8. +
      8. Footnotes
        9. +
      9. Linked Heading Anchors and Tables of Contents
        10. +
      10. Autolinked References - Issues, PRs, Commits, and Users
        11. +
      11. HTML in Markdown
        12. +
      +

      Part 3 - Putting It All Together

      +
        +
      1. Screen Reader Behavior Summary
        2. +
      2. Accessible Markdown Authoring Checklist
        3. +
      3. Common Mistakes and How to Fix Them
        4. +
      4. Your First Real Markdown Document - Guided Exercise
        5. +
      5. Quick-Reference Card
        6. +
      +

      Part 1 - Markdown Foundations

      +

      Learning Cards: Using This Markdown Reference

      +
      +Screen reader users + +
        +
      • Use heading navigation (H key) to jump between numbered sections -- each topic is an h2 heading
        • +
      • Every section shows raw Markdown first, then rendered output, then screen reader behavior notes
        • +
      • The Table of Contents at the top has anchor links -- activate any link to jump directly to that section
        • +
      +
      + +
      +Low vision users + +
        +
      • Code blocks show the raw Markdown to type -- increase zoom and the monospace font stays readable
        • +
      • Each section follows the same pattern: explanation, raw code, rendered result, and accessibility notes
        • +
      • Use Ctrl+F to search for a specific Markdown element (e.g., search "table" or "heading")
        • +
      +
      + +
      +Sighted users + +
        +
      • Sections are numbered 1-32 -- use the Table of Contents to jump to any topic
        • +
      • Raw Markdown is in grey code blocks; rendered output follows immediately after
        • +
      • Part 1 covers standard Markdown, Part 2 covers GitHub-specific extensions, Part 3 ties it together
        • +
      +
      + + +

      1. What Is Markdown?

      +

      Markdown is a lightweight way to format plain text so it renders as rich, structured content - headings, bold text, links, lists, code blocks, tables, and more. You write in a plain text file using simple punctuation characters, and a Markdown processor converts those characters into formatted output.

      +

      Here is the key idea: what you type is readable as plain text, and it is also readable as formatted content after rendering. You never lose meaning either way. A screen reader can read your raw Markdown file and understand it. A sighted user can read the rendered version on GitHub and understand it. Both experiences work.

      +

      A brief history

      +

      John Gruber created Markdown in 2004 with the goal of making a format that is "as easy to read and write as plain text." Since then, Markdown has become the default writing format for:

      +
        +
      • GitHub (README files, issues, pull requests, comments, wikis, discussions)
        • +
      • Stack Overflow and many developer forums
        • +
      • Static site generators (Jekyll, Hugo, Gatsby)
        • +
      • Note-taking apps (Obsidian, Notion, Bear)
        • +
      • Documentation systems (MkDocs, Docusaurus, Read the Docs)
        • +
      • Chat platforms (Slack, Discord, Microsoft Teams)
        • +
      +

      Markdown versus HTML

      +

      Markdown converts to HTML behind the scenes. When you write **bold**, GitHub converts it to <strong>bold</strong>. When you write # Heading, it becomes <h1>Heading</h1>. You get the benefits of structured HTML without needing to write angle brackets.

      +

      The following table compares common formatting in HTML versus Markdown.

      + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + +
      What you wantHTMLMarkdown
      Bold text<strong>bold</strong>**bold**
      Italic text<em>italic</em>*italic*
      A link<a href="url">text</a>[text](url)
      A heading<h2>Title</h2>## Title
      A bullet list<ul><li>item</li></ul>- item
      +

      Markdown is shorter, easier to type, and easier to read in its raw form. That is why it won.

      +

      What gets rendered and what stays raw

      +

      When you view a .md file on GitHub, GitHub renders it automatically. You see the formatted output. When you edit that file, you see the raw Markdown. When a screen reader reads a rendered Markdown file on GitHub, it navigates the HTML that Markdown produced - headings, links, lists, and all their semantic structure.

      +

      2. Where You Will Use Markdown in This Workshop

      +

      Markdown is not just one tool in this workshop - it is the thread that connects everything you do. Here is every place you will write or read Markdown during the two days.

      +

      Day 1 - GitHub Foundations (Browser)

      +

      The following table lists every Day 1 activity where Markdown is used.

      + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + +
      ActivityWhere Markdown appears
      Reading course materialsEvery chapter and appendix is a .md file
      Filing an issue (Chapter 4)The issue body is Markdown - you format your bug report with headings, lists, and code blocks
      Commenting on issuesEvery comment is Markdown
      Opening a pull request (Chapter 6)The PR description is Markdown - you reference issues, add checklists, and explain your changes
      Reviewing a pull requestReview comments are Markdown
      Reading the READMEThe first file you see in any repository is README.md
      +

      Day 2 - VS Code and Accessibility Agents

      +

      The following table lists every Day 2 activity where Markdown is used.

      + + + + + + + + + + + + + + + + + + + + + + + + + + + +
      ActivityWhere Markdown appears
      Editing files in VS CodeYou edit .md files directly with Markdown preview (Ctrl+Shift+V)
      Writing commit messagesWhile not full Markdown, commit messages follow similar plain-text conventions
      Using Copilot Chat (Chapter 16)Copilot returns responses formatted in Markdown
      Creating issue templates (Chapter 17)Templates use Markdown for the body content
      Agent commands and output (Chapter 19)Agent reports are rendered Markdown
      +

      Learning Room connection

      +

      In the Learning Room repository, every challenge description, every welcome file, and every piece of documentation is Markdown. When you fix a broken link in docs/welcome.md for Challenge 1, you are editing Markdown. When you add alt text to an image for an accessibility challenge, you are writing Markdown. The skill you build in this appendix is the skill you use in every challenge.

      +

      3. How to Practice as You Read

      +

      The best way to learn Markdown is to type it yourself. Here are three ways to practice as you read this guide.

      +

      Option 1 - GitHub Issue (recommended for Day 1)

      +
        +
      1. Go to any repository where you have write access (the Learning Room works)
        2. +
      2. Click New Issue
        3. +
      3. Type Markdown in the issue body
        4. +
      4. Click the Preview tab to see the rendered result
        5. +
      5. Switch back to Write to keep editing
        6. +
      6. You do not need to submit the issue - the Preview tab is your sandbox
        7. +
      +
      +

      Screen reader note: The Write and Preview tabs are announced as tab buttons. Press Enter on "Preview" to switch. NVDA announces the rendered content normally. Press Enter on "Write" to return to the edit field.

      +
      +

      Option 2 - Any .md file in VS Code (recommended for Day 2)

      +
        +
      1. Create a new file: Ctrl+N, then save it as practice.md
        2. +
      2. Type your Markdown in the editor
        3. +
      3. Press Ctrl+Shift+V to open the rendered Markdown preview in a new tab
        4. +
      4. The preview updates live as you type
        5. +
      +

      Option 3 - GitHub Gist

      +
        +
      1. Go to gist.github.com
        2. +
      2. Name your file practice.md
        3. +
      3. Type Markdown in the content area
        4. +
      4. Click Create secret gist (only you can see it)
        5. +
      5. View the rendered result
        6. +
      +

      4. Paragraphs and Line Breaks

      +

      This is the most fundamental element in Markdown, and it trips up almost everyone at first.

      +

      Paragraphs

      +

      A paragraph is one or more lines of text separated by a blank line (an empty line with nothing on it). If you do not leave a blank line between two blocks of text, Markdown treats them as one continuous paragraph.

      +

      What you type:

      +
      This is the first paragraph. It contains a complete thought
+and continues on the next line without a break.
+
+This is the second paragraph. The blank line above tells
+Markdown to start a new paragraph.
      +

      What renders:

      +

      This is the first paragraph. It contains a complete thought and continues on the next line without a break.

      +

      This is the second paragraph. The blank line above tells Markdown to start a new paragraph.

      +

      Line breaks within a paragraph

      +

      Sometimes you want to go to a new line without starting a whole new paragraph - for example, in an address or a poem. To create a line break (a <br> in HTML), end a line with two or more spaces and then press Enter. Alternatively, you can use a backslash (\) at the end of the line, or use an explicit <br> HTML tag.

      +

      What you type:

      +
      123 Main Street
+Springfield, IL 62701
+United States
      +

      (There are two spaces after "Street" and after "62701" - you cannot see them, but they are there.)

      +

      What renders:

      +

      123 Main Street +Springfield, IL 62701 +United States

      +
      +

      Screen reader note: Paragraphs are announced as separate blocks of text. Line breaks within a paragraph are read as continuous text with a brief pause. Screen readers do not announce "new paragraph" for a <br> - they just pause slightly.

      +
      +
      +

      Tip: The two-trailing-spaces method is invisible and easy to lose when editing. Many authors prefer the explicit <br> tag instead, because it is visible in the source:

      +
      +
      123 Main Street<br>
+Springfield, IL 62701<br>
+United States
      +

      Common mistake - no blank line between paragraphs

      +

      What you type (wrong):

      +
      First paragraph.
+Second paragraph.
      +

      What renders (wrong): Both lines merge into one paragraph:

      +

      First paragraph. Second paragraph.

      +

      Fix: Add a blank line between them.

      +

      5. Headings

      +

      Headings create the structure of your document. They are how screen readers navigate, how tables of contents are built, and how readers scan for the section they need.

      +

      Syntax

      +

      Add one to six # characters at the start of a line, followed by a space, then the heading text. The number of # characters determines the heading level.

      +

      What you type:

      +
      # Heading Level 1
+## Heading Level 2
+### Heading Level 3
+#### Heading Level 4
+##### Heading Level 5
+###### Heading Level 6
      +

      What these produce in HTML:

      + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + +
      MarkdownHTMLTypical use
      # Title<h1>Document title - one per document
      ## Section<h2>Major sections
      ### Subsection<h3>Subsections within a section
      #### Detail<h4>Detailed topics within a subsection
      ##### Fine detail<h5>Rarely used, very specific topics
      ###### Finest detail<h6>Almost never needed
      +

      Rules for accessible headings

      +
        +
      1. One H1 per document. The # heading is your document title. Every document gets exactly one
        2. +
      2. Never skip levels. Go from ## to ###, never from ## to ####. Skipping levels breaks the document outline for screen reader users who navigate by heading
        3. +
      3. Make headings descriptive. A heading of "Section 3" tells a screen reader user nothing. A heading of "Creating Your First Pull Request" tells them exactly what the section covers
        4. +
      4. Do not use bold as a heading substitute. Writing **My Section** on its own line looks like a heading visually, but it is not a heading in the document structure. Screen reader users navigating by heading (H key in Browse Mode) will never find it
        5. +
      +
      +

      Screen reader note: Screen readers let you navigate by heading level. In NVDA and JAWS, pressing H moves to the next heading. Pressing 1 through 6 moves to the next heading at that specific level. This is one of the most important navigation methods on any page - and it only works if the document uses real headings in the correct hierarchy.

      +
      + +

      Markdown also supports "setext" headings where you underline text with = or - characters:

      +
      Heading Level 1
+===============
+
+Heading Level 2
+---------------
      +

      This only works for levels 1 and 2, and it is harder to scan visually in raw Markdown. Stick with the # syntax - it is clearer, supports all six levels, and is what you will see in virtually every GitHub project.

      +

      6. Emphasis - Bold, Italic, and Bold Italic

      +

      Emphasis changes how text is read by screen readers - it is not just visual. When text is bold or italic, well-configured screen readers can announce emphasis changes, giving the listener additional context about importance.

      +

      Bold

      +

      Wrap text in two asterisks or two underscores on each side.

      +

      What you type:

      +
      This is **bold text** using asterisks.
+This is __bold text__ using underscores.
      +

      What renders:

      +

      This is bold text using asterisks. +This is bold text using underscores.

      +

      Best practice: Use asterisks (**). Underscores can cause problems in the middle of words (like file__name__here), while asterisks always work.

      +

      Italic

      +

      Wrap text in one asterisk or one underscore on each side.

      +

      What you type:

      +
      This is *italic text* using asterisks.
+This is _italic text_ using underscores.
      +

      What renders:

      +

      This is italic text using asterisks. +This is italic text using underscores.

      +

      Bold and italic combined

      +

      Wrap text in three asterisks on each side.

      +

      What you type:

      +
      This is ***bold and italic*** text.
      +

      What renders:

      +

      This is bold and italic text.

      +

      When to use emphasis

      +

      The following table provides guidance on when to use each type of emphasis.

      + + + + + + + + + + + + + + + + + + + + + + + +
      TypeWhen to useExample
      BoldKey terms, important warnings, UI element names"Click the Submit button"
      ItalicBook or document titles, introducing new terms, gentle emphasis"See the Contributing Guide for details"
      Bold italicExtremely rare - critical warnings only"Do not force push to the main branch"
      +
      +

      Screen reader note: NVDA can announce emphasis changes if the user enables "Report font attributes" (under Speech settings). JAWS can announce emphasis with "Say all font changes" enabled. VoiceOver announces emphasis by default on macOS. Even when emphasis is not announced, the HTML semantic structure (<strong> for bold, <em> for italic) is available to screen readers that choose to report it.

      +
      +

      Emphasis inside words

      +

      Asterisks work inside words. Underscores do not (in most Markdown processors including GitHub).

      +
      This**works**fine.
+This__does__not.
      +

      Renders as: Thisworksfine. This__does__not.

      +

      Use asterisks when you need emphasis inside a word (rare, but it comes up in technical documentation).

      +

      7. Strikethrough

      +

      Strikethrough text shows deleted or outdated content with a line through it. Wrap text in two tildes on each side.

      +

      What you type:

      +
      The meeting is ~~Tuesday~~ Wednesday at 3 PM.
+~~This feature has been removed.~~
      +

      What renders:

      +

      The meeting is Tuesday Wednesday at 3 PM. +This feature has been removed.

      +
      +

      Screen reader note: Screen reader behavior with strikethrough varies. NVDA with "Report font attributes" enabled will announce "strikethrough" before the text. JAWS may announce it as "deleted." VoiceOver does not announce strikethrough by default - the text is simply read. Because of this inconsistency, do not rely on strikethrough alone to convey meaning. Add context in the surrounding text: "The meeting was changed from Tuesday to Wednesday."

      +
      +
      +

      GitHub note: Strikethrough is part of the GitHub Flavored Markdown specification. It is not in standard Markdown or CommonMark.

      +
      +

      8. Lists - Ordered and Unordered

      +

      Lists are one of the most common elements in GitHub documentation. Issue descriptions, PR checklists, README instructions, step-by-step guides - they all use lists.

      +

      Unordered lists (bullet points)

      +

      Start each line with a dash (-), asterisk (*), or plus sign (+) followed by a space.

      +

      What you type:

      +
      - First item
+- Second item
+- Third item
      +

      What renders:

      +
        +
      • First item
        • +
      • Second item
        • +
      • Third item
        • +
      +

      Best practice: Use dashes (-). They are the most common convention on GitHub and visually distinct from the asterisks used for bold and italic.

      +
      +

      Important: Be consistent within a single list. Do not mix -, *, and + in the same list - some processors handle it inconsistently, and it makes the raw Markdown harder to read.

      +
      +

      Ordered lists (numbered)

      +

      Start each line with a number followed by a period and a space.

      +

      What you type:

      +
      1. Clone the repository
+2. Create a new branch
+3. Make your changes
+4. Open a pull request
      +

      What renders:

      +
        +
      1. Clone the repository
        2. +
      2. Create a new branch
        3. +
      3. Make your changes
        4. +
      4. Open a pull request
        5. +
      +

      A helpful trick - Markdown renumbers for you

      +

      Here is something that surprises most new users. In Markdown, the actual numbers you type do not matter for the rendered output. Markdown automatically numbers the list sequentially. This means you can use 1. for every item:

      +
      1. Clone the repository
+1. Create a new branch
+1. Make your changes
+1. Open a pull request
      +

      This still renders as 1, 2, 3, 4. The benefit is that when you insert a new step in the middle, you do not need to renumber everything. However, for readability of the raw Markdown, many authors prefer typing the correct numbers.

      +
      +

      Screen reader note: Screen readers announce list items with their position: "list, 4 items. 1. Clone the repository. 2. Create a new branch." and so on. The semantic list structure is preserved in the HTML output, so navigation commands like L (next list) and I (next list item) work correctly in NVDA and JAWS Browse Mode.

      +
      +

      Starting an ordered list at a specific number

      +

      If you need a list to start at a number other than 1, use that number for the first item. All subsequent items are numbered sequentially from there:

      +
      3. This is step three
+4. This is step four
+5. This is step five
      +

      9. Nested Lists and Mixed Lists

      +

      Lists can contain other lists, creating an indented hierarchy. This is essential for complex instructions, outlines, and project structures.

      +

      Nesting unordered lists

      +

      Indent the nested items by two or four spaces (GitHub accepts either, but four is most reliable).

      +

      What you type:

      +
      - Accessibility testing tools
+    - Screen readers
+        - NVDA (Windows, free)
+        - JAWS (Windows, commercial)
+        - VoiceOver (macOS and iOS, built-in)
+    - Browser extensions
+        - axe DevTools
+        - WAVE
+- Documentation tools
+    - Markdown editors
+    - Static site generators
      +

      What renders:

      +
        +
      • Accessibility testing tools
          +
        • Screen readers
            +
          • NVDA (Windows, free)
            • +
          • JAWS (Windows, commercial)
            • +
          • VoiceOver (macOS and iOS, built-in)
            • +
          +
          • +
        • Browser extensions
            +
          • axe DevTools
            • +
          • WAVE
            • +
          +
          • +
        +
        • +
      • Documentation tools
          +
        • Markdown editors
          • +
        • Static site generators
          • +
        +
        • +
      +

      Nesting ordered lists

      +

      The same indentation principle applies to numbered lists:

      +
      1. Set up your environment
+    1. Install Git
+    2. Create a GitHub account
+    3. Configure your screen reader
+2. Learn GitHub navigation
+    1. Understand the page structure
+    2. Master keyboard shortcuts
+    3. Practice with the Learning Room
      +

      Mixing ordered and unordered lists

      +

      You can nest an unordered list inside an ordered list and vice versa:

      +
      1. Before the workshop
+    - Create a GitHub account
+    - Install VS Code
+    - Test your screen reader
+2. During Day 1
+    - File your first issue
+    - Open your first pull request
+3. After the workshop
+    - Continue contributing
+    - Join community discussions
      +

      Adding content inside list items

      +

      List items can contain paragraphs, code blocks, and other elements. Indent the content to align with the list item text (typically four spaces):

      +
      1. Clone the repository
+
+    Open your terminal and run the following command:
+
+    ```bash
+    git clone https://github.com/community-access/accessibility-agents.git
+    ```
+
+    This downloads the entire repository to your computer.
+
+2. Create a new branch
+
+    ```bash
+    git checkout -b fix/broken-link
+    ```
      +
      +

      Screen reader note: Nested lists are announced with their nesting level. NVDA says "list, nesting level 2" when entering an inner list. This helps you understand the hierarchy by ear.

      +
      + +

      Links are how you connect documents, reference issues, point to external resources, and cite sources. Getting links right is critical for accessibility - links with bad text are one of the most common accessibility failures in documentation.

      + +

      Wrap the visible link text in square brackets, followed immediately by the URL in parentheses:

      +
      [GitHub Documentation](https://docs.github.com)
      +

      Renders as: GitHub Documentation

      +

      Links with title text

      +

      Add a title in quotes after the URL. The title appears as a tooltip on hover:

      +
      [GitHub Documentation](https://docs.github.com "Official GitHub docs and guides")
      +
      +

      Screen reader note: Link titles are not reliably announced by all screen readers. Do not put critical information only in the title text. The link text itself must be descriptive.

      +
      +

      Writing accessible link text

      +

      This is one of the most important accessibility skills in Markdown authoring. Screen reader users often navigate by pulling up a list of all links on a page (NVDA: NVDA+F7 then select Links; JAWS: Insert+F7). In this list, only the link text is shown - not the surrounding sentence. Every link must make sense on its own.

      +

      The following table contrasts bad and good link text with an explanation.

      + + + + + + + + + + + + + + + + + + + + + + + + + + + + +
      Bad (do not do this)Good (do this instead)Why
      Click here for the guideRead the Contributing Guide"here" means nothing out of context
      Read moreRead the full accessibility audit report"Read more" is ambiguous in a link list
      https://docs.github.comGitHub DocumentationScreen readers read the entire URL character by character
      LinkPre-Workshop Setup instructions"Link" tells you nothing about the destination
      + +

      For documents with many links, reference-style links keep the text readable by separating the URL from the prose. You define the link target once at the bottom of the document:

      +
      Check the [Contributing Guide][contributing] before submitting a PR.
+See also the [Code of Conduct][coc] for community standards.
+
+[contributing]: https://github.com/community-access/accessibility-agents/blob/main/CONTRIBUTING.md
+[coc]: https://github.com/community-access/accessibility-agents/blob/main/CODE_OF_CONDUCT.md
      +

      The reference labels ([contributing], [coc]) do not appear in the rendered output. Readers just see clean, clickable links.

      + +

      When linking to other files in the same repository, use relative paths instead of full URLs. This way, links work on any fork or branch:

      +
      See the [Pre-Workshop Setup](00-pre-workshop-setup.md) guide.
+Jump to the [Glossary](appendix-a-glossary.md#fork) entry for "fork."
+Return to the [course guide](course-guide.md).
      + +
      Contact us at <support@example.com>
      +

      The angle brackets tell Markdown to create a mailto: link: support@example.com

      +

      Autolinked URLs

      +

      GitHub automatically converts full URLs in your text into clickable links, but always prefer explicit descriptive links in prose. Bare URLs should only appear in reference sections or code examples.

      + +

      Screen reader users:

      +
        +
      • Pull up a links list (NVDA: NVDA+F7 then Links tab; JAWS: Insert+F7) to audit your document -- every link must make sense without its surrounding sentence
        • +
      • Reference-style links ([text][ref]) produce identical HTML to inline links -- screen readers announce them the same way, so choose whichever keeps your source readable
        • +
      • Relative links to other repo files (e.g., [Setup](00-pre-workshop-setup.md)) work on any fork or branch -- prefer them over full URLs for internal documentation
        • +
      +

      Low-vision users:

      +
        +
      • Links render as blue underlined text by default -- if your GitHub theme reduces underline visibility, rely on the color difference or hover state to identify links
        • +
      • Long URLs in link text are hard to read at high zoom; always use descriptive text like [Contributing Guide](url) instead of pasting the raw URL
        • +
      • The title attribute (text in quotes after the URL) appears as a tooltip on hover -- useful at high magnification but do not put essential information only there
        • +
      +

      Sighted users:

      +
        +
      • Scan for blue underlined text to identify all links in rendered Markdown -- bare URLs will also be clickable but look cluttered in prose
        • +
      • Reference-style links keep the prose clean by moving URLs to the bottom of the file -- look for [label]: url definitions at the end of the document
        • +
      • When reviewing a PR, check that no links use "click here" or "read more" as their visible text -- these fail accessibility audits and are unhelpful to all readers
        • +
      +

      11. Images

      +

      Images in Markdown use a syntax similar to links, with an exclamation mark (!) at the beginning.

      +

      Syntax

      +
      ![Description of what the image shows](path/to/image.png)
      +

      The text inside the square brackets is the alt text - the description that screen readers read aloud instead of displaying the image. This is the single most important accessibility attribute for images.

      +

      Writing good alt text

      +

      The following table provides guidance on alt text for different types of images.

      + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + +
      Image typeGood alt textBad alt text
      Screenshot of a form"GitHub new issue form with title field, body text area, and submit button""screenshot"
      Logo"Community Access logo""logo.png"
      Decorative dividerLeave alt text empty: ![](divider.png)"divider"
      Chart or graph"Bar chart showing screen reader usage: JAWS 40%, NVDA 35%, VoiceOver 15%, Other 10%""chart"
      Photo of a person"Jamie presenting at the accessibility workshop podium""photo"
      + +

      To make an image clickable, wrap the image syntax inside a link:

      +
      [![Community Access logo](logo.png)](https://community-access.org)
      +

      Image with a title

      +
      ![Screenshot of the GitHub issue creation form](issue-form.png "The new issue form on GitHub")
      +

      When to use details blocks for complex images

      +

      If an image contains complex information (like an architecture diagram or a data visualization), provide a full text description in a collapsible <details> block:

      +
      ![Architecture diagram showing the three-tier agent system](architecture.png)
+
+<details>
+<summary>Full description of the architecture diagram</summary>
+
+The architecture has three tiers:
+
+1. The GitHub Hub agent receives all user requests
+2. The Hub routes to specialist agents (issue-tracker, pr-review, analytics)
+3. Each specialist agent returns structured markdown reports
+
+</details>
      +
      +

      Screen reader note: Screen readers announce images as "graphic" followed by the alt text. If alt text is empty, the image is treated as decorative and skipped. If alt text is missing entirely (no square brackets), some screen readers will announce the filename, which is not helpful. Always include the square brackets, even if empty for decorative images.

      +
      +

      Learning Cards: Images

      +

      Screen reader users:

      +
        +
      • Alt text is read aloud as the only representation of the image -- write it to answer "what information does this image convey?" not just "what does it look like?"
        • +
      • For decorative images, use empty alt text (![](image.png)) so the screen reader skips them entirely rather than announcing the filename
        • +
      • Complex images (architecture diagrams, charts) need a full text description in a <details> block below the image -- expand it to read the complete information
        • +
      +

      Low-vision users:

      +
        +
      • Images render at their original size by default -- use browser or VS Code zoom to enlarge them, and ensure alt text is present in case the image becomes too pixelated
        • +
      • Screenshots with small text are the hardest images to read at high magnification -- request that contributors use cropped, focused screenshots instead of full-screen captures
        • +
      • The alt text is invisible in the rendered view but visible in the raw Markdown source -- switch to the source view to verify alt text exists on all images
        • +
      +

      Sighted users:

      +
        +
      • Alt text does not appear visually on the rendered page unless the image fails to load -- check alt text quality by viewing the raw Markdown or using a Markdown linter
        • +
      • Use the <details> pattern for complex images: display the image normally, then add a collapsible text description below for screen reader users and anyone who wants more detail
        • +
      • Linked images ([![alt](img)](url)) show a clickable image -- ensure the alt text describes both the image content and the link destination
        • +
      +

      12. Blockquotes

      +

      Blockquotes are used for callouts, important notes, cited text, and instructor guidance throughout this course. Start each line with a > character followed by a space.

      +

      Basic blockquote

      +

      What you type:

      +
      > This is a blockquote. It is used to highlight important information
+> or to quote someone else's text.
      +

      What renders:

      +
      +

      This is a blockquote. It is used to highlight important information or to quote someone else's text.

      +
      +

      Multi-paragraph blockquotes

      +

      Add a > on the blank lines between paragraphs to keep them inside the blockquote:

      +
      > This is the first paragraph of the blockquote.
+>
+> This is the second paragraph. The blank line with just ">" keeps
+> both paragraphs inside the same blockquote.
      +

      Nested blockquotes

      +
      > This is the outer blockquote.
+>
+> > This is a nested blockquote inside the first one.
+>
+> Back to the outer level.
      +

      Blockquotes with other elements

      +

      Blockquotes can contain any Markdown element - headings, lists, code, bold, links:

      +
      > **Important:** Before starting the exercise:
+>
+> 1. Make sure you are on the `main` branch
+> 2. Pull the latest changes: `git pull origin main`
+> 3. Read the [challenge description](challenges.md) first
+>
+> If you get stuck, ask in the issue thread.
      +
      +

      Screen reader note: Screen readers announce the beginning and end of a blockquote. NVDA says "block quote" when entering and "out of block quote" when leaving. Content inside is read normally. This means blockquotes are an excellent way to highlight important information for all users.

      +
      +

      How we use blockquotes in this course

      +

      Throughout this workshop, blockquotes serve specific purposes:

      +
        +
      • Screen reader notes: Tips specific to assistive technology users
        • +
      • Learning Room connections: How the current topic connects to the practice repo
        • +
      • Important warnings: Critical information that could prevent errors
        • +
      • Instructor guidance: Notes from the facilitator about pacing or approach
        • +
      +

      13. Inline Code and Code Blocks

      +

      Code formatting is essential on GitHub. You will use it for command-line instructions, file names, configuration values, keyboard shortcuts, and actual source code.

      +

      Inline code

      +

      Wrap text in single backticks (`) to format it as code within a sentence.

      +

      What you type:

      +
      Run `git status` to see which files have changed.
+The configuration file is `package.json`.
+Press `Ctrl+Shift+P` to open the Command Palette.
      +

      What renders:

      +

      Run git status to see which files have changed. +The configuration file is package.json. +Press Ctrl+Shift+P to open the Command Palette.

      +

      When to use inline code:

      +
        +
      • Command names: git clone, npm install
        • +
      • File names: README.md, CONTRIBUTING.md
        • +
      • Keyboard shortcuts: Ctrl+C, Alt+Tab
        • +
      • Variable or function names: userName, getElementById()
        • +
      • Configuration values: true, false, null
        • +
      • Branch names: main, feature/add-alt-text
        • +
      +

      Code blocks (fenced)

      +

      For multi-line code, wrap it in triple backticks (```) on their own lines:

      +

      What you type:

      +
      ```
+This is a code block.
+All formatting is preserved exactly.
+    Indentation stays.
+**Bold does not render** - it stays as plain text.
+```
      +

      Code blocks with syntax highlighting

      +

      Add a language identifier right after the opening triple backticks to enable syntax highlighting:

      +
      ```python
+def greet(name: str) -> str:
+    """Return a greeting for the given name."""
+    return f"Hello, {name}! Welcome to the workshop."
+```
      +
      def greet(name: str) -> str:
+    """Return a greeting for the given name."""
+    return f"Hello, {name}! Welcome to the workshop."
      +

      The following table lists language identifiers you will encounter most often in this workshop.

      + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + +
      LanguageIdentifierUsed for
      PythonpythonScripts, automation, Copilot examples
      Bash / Shellbash or shellTerminal commands, Git operations
      YAMLyamlGitHub Actions workflows, issue templates
      JSONjsonConfiguration files, API responses
      JavaScriptjavascript or jsWeb scripts, Node.js
      HTMLhtmlWeb page structure
      CSScssStyling
      MarkdownmarkdownMarkdown examples (yes, you can format Markdown inside Markdown)
      Plain texttext or plaintextWhen no highlighting is needed
      DiffdiffShowing code changes (additions in green, removals in red)
      +

      Showing diffs in code blocks

      +

      The diff language identifier highlights additions and removals:

      +
      ```diff
+- old line that was removed
++ new line that was added
+  unchanged context line
+```
      +
      - old line that was removed
++ new line that was added
+  unchanged context line
      +

      Code blocks inside list items

      +

      Indent the code block to align with the list item text:

      +
      1. Create a new branch:
+
+    ```bash
+    git checkout -b feature/my-change
+    ```
+
+2. Make your changes and stage them:
+
+    ```bash
+    git add .
+    ```
      +

      How to show literal backticks

      +

      If your code contains backticks, use more backticks for the fence:

      +
      ````markdown
+```python
+print("Hello")
+```
+````
      +

      Use four backticks to wrap content that contains triple backticks. Use five to wrap content that contains four. You get the idea.

      +
      +

      Screen reader note: Code blocks are announced as "code" regions. Screen readers read the content character by character when navigating with arrow keys, and as whole lines when navigating with Down Arrow. Syntax highlighting is visual only - it does not affect what screen readers announce. The code text is equally accessible whether highlighted or not.

      +
      +

      14. Horizontal Rules

      +

      A horizontal rule creates a thematic break between sections - a visual line across the page. Use three or more dashes, asterisks, or underscores on a line by themselves.

      +

      What you type (any of these work):

      +
      
+***
+
+___
      +

      Best practice: Use --- (three dashes). It is the most common convention and looks clean in raw Markdown. Always put a blank line before and after the rule.

      +
      +

      Screen reader note: Horizontal rules are announced as "separator" in NVDA, "horizontal separator" in JAWS, and "horizontal rule" in VoiceOver. They are useful as navigation landmarks - screen reader users can move between them, but do not overuse them. Headings are a better way to structure a document.

      +
      +

      15. Escaping Special Characters

      +

      Many characters have special meaning in Markdown. If you want to display them as literal characters instead, put a backslash (\) before them.

      +

      Characters that can be escaped

      +

      The following table lists every character that can be escaped in Markdown.

      + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + +
      CharacterNameMarkdown meaning
      \BackslashEscape character itself
      `BacktickInline code
      *AsteriskBold, italic, or list item
      _UnderscoreBold or italic
      {}Curly bracesUsed in some extensions
      []Square bracketsLink text
      ()ParenthesesLink URL
      #HashHeading
      +Plus signUnordered list
      -DashUnordered list or horizontal rule
      .PeriodOrdered list (after a number)
      !Exclamation markImage
      ``Pipe
      ~TildeStrikethrough
      +

      Examples

      +

      What you type:

      +
      This asterisk is literal: \*not bold\*
+This hash is literal: \# not a heading
+Show a pipe character: \|
      +

      What renders:

      +

      This asterisk is literal: *not bold* +This hash is literal: # not a heading +Show a pipe character: |

      +

      16. Tables

      +

      Tables organize data into rows and columns. They are used extensively on GitHub for comparison charts, reference data, settings documentation, and checklists.

      +

      Basic table syntax

      +
      | Name | Role | Platform |
+|---|---|---|
+| NVDA | Screen reader | Windows |
+| JAWS | Screen reader | Windows |
+| VoiceOver | Screen reader | macOS / iOS |
+| TalkBack | Screen reader | Android |
      +

      What renders:

      + + + + + + + + + + + + + + + + + + + + + + + + + + + + +
      NameRolePlatform
      NVDAScreen readerWindows
      JAWSScreen readerWindows
      VoiceOverScreen readermacOS / iOS
      TalkBackScreen readerAndroid
      +

      How table syntax works

      +
        +
      • The first row is always the header row
        • +
      • The second row contains dashes (---) that separate the header from the data. You need at least three dashes per column
        • +
      • Each subsequent row is a data row
        • +
      • Columns are separated by pipe characters (|)
        • +
      • Leading and trailing pipes are optional but recommended for readability
        • +
      +

      Column alignment

      +

      Add colons (:) to the separator row to control text alignment:

      +
      | Left aligned | Center aligned | Right aligned |
+|:---|:---:|---:|
+| Text | Text | Text |
+| Longer text here | Centered text | 42 |
      + + + + + + + + + + + + + + + + + + +
      Left alignedCenter alignedRight aligned
      TextTextText
      Longer text hereCentered text42
      +
        +
      • :--- = left aligned (default)
        • +
      • :---: = center aligned
        • +
      • ---: = right aligned
        • +
      +

      Formatting inside table cells

      +

      You can use inline formatting within table cells:

      +
      | Feature | Status | Notes |
+|---|---|---|
+| **Bold text** | `code` | Works [with links](url) too |
+| *Italic text* | ~~struck~~ | Use any inline formatting |
      +

      Accessibility considerations for tables

      +
        +
      1. Always include a description before the table. Add a one-sentence summary immediately above the table explaining what it contains. Screen reader users hear the table structure (rows and columns) but benefit from knowing what the table is about before entering it
        2. +
      2. Keep tables simple. Tables with more than 5-6 columns become difficult to navigate with a screen reader. Consider splitting wide tables into multiple narrower tables
        3. +
      3. Use tables for data, not layout. If you are using a table just to arrange content side by side, use a list instead
        4. +
      4. Make the header row descriptive. The header cell is announced before each data cell when navigating by column, so "Platform" is better than "Col 3"
        5. +
      +
      +

      Screen reader note: Screen readers navigate tables with Ctrl+Alt+Arrow keys (NVDA and JAWS). Ctrl+Alt+Right moves to the next column. Ctrl+Alt+Down moves to the next row. The column header is announced each time you move to a new column. Table mode is entered automatically when the screen reader encounters a table.

      +
      +

      When not to use a table

      +

      If your "table" has only two columns where the first is a label and the second is a value, consider using a definition-style list or bold labels instead:

      +
      **Name:** Community Access
+**Founded:** 2020
+**Mission:** Empowering blind and low vision technology professionals
      +

      This is often easier to read with a screen reader than a two-column table.

      +

      Learning Cards: Tables

      +

      Screen reader users:

      +
        +
      • Navigate tables with Ctrl+Alt+Arrow keys (NVDA/JAWS) -- Right moves to the next column, Down to the next row; the column header is announced each time you change columns
        • +
      • Enter table mode automatically when your screen reader encounters a table -- press T in browse mode to jump to the next table on the page
        • +
      • Before the table structure, listen for the description sentence the author should place above it -- this tells you what data the table contains before you enter cell-by-cell navigation
        • +
      +

      Low-vision users:

      +
        +
      • Wide tables (6+ columns) may require horizontal scrolling at high zoom -- if the table overflows, scroll right to see truncated columns or view the raw Markdown source instead
        • +
      • Column alignment (left, center, right) is controlled by colons in the separator row -- at high magnification, right-aligned numbers are easier to compare than left-aligned ones
        • +
      • If a table is hard to read at your zoom level, try narrowing the browser window -- GitHub will sometimes reflow content or add a horizontal scrollbar
        • +
      +

      Sighted users:

      +
        +
      • The header row is visually bold and separated by a line from data rows -- scan headers first to understand the table structure before reading data
        • +
      • Column alignment is subtle: left-aligned is default, centered and right-aligned text may not be obvious without comparing multiple cells
        • +
      • Consider whether your data truly needs a table -- if it is a simple label-value list, use bold labels (**Key:** value) instead for less visual complexity
        • +
      +

      Learning Cards: GitHub Flavored Markdown

      +
      +Screen reader users + +
        +
      • GFM features (sections 17-27) work only on GitHub -- your screen reader behavior notes are in each section
        • +
      • Alert blocks (section 18) render as blockquotes with a type prefix -- listen for "Note," "Warning," etc.
        • +
      • Task list checkboxes (section 20) are announced as "checkbox checked" or "checkbox not checked"
        • +
      +
      + +
      +Low vision users + +
        +
      • Alert blocks use color-coded left borders (blue for Note, yellow for Warning, red for Caution) -- the text label also identifies the type
        • +
      • Mermaid diagrams (section 22) are visual only on GitHub -- the raw code block is always readable
        • +
      • Use GitHub's Preview tab when writing to confirm your GFM renders correctly before submitting
        • +
      +
      + +
      +Sighted users + +
        +
      • GFM features have visual cues: colored alert blocks, rendered checkboxes, syntax-highlighted code
        • +
      • Mermaid diagrams render as interactive SVGs -- hover for tooltips on nodes
        • +
      • The autolinked references section (26) explains the shorthand (#123, @user) you see everywhere on GitHub
        • +
      +
      + + +

      Part 2 - GitHub Flavored Markdown (GFM)

      +

      17. What Is GitHub Flavored Markdown?

      +

      GitHub Flavored Markdown (GFM) is GitHub's own superset of standard Markdown. It takes everything from the CommonMark specification (the modern standard for Markdown) and adds features specifically designed for software collaboration: tables, task lists, strikethrough, autolinked references, alert blocks, Mermaid diagrams, math expressions, and footnotes.

      +

      Everything you learned in Part 1 works everywhere Markdown is supported. Everything in Part 2 is specific to GitHub (and some other platforms that have adopted GFM).

      +

      Where GFM works

      +

      The following table shows where GFM is supported.

      + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + +
      LocationGFM supportedNotes
      .md files in reposYesAny Markdown file rendered on GitHub
      Issue descriptionsYesFull GFM with autolinks
      Issue commentsYesFull GFM with autolinks
      Pull request descriptionsYesFull GFM with autolinks
      Pull request commentsYesFull GFM with autolinks
      Discussion postsYesFull GFM with autolinks
      Wiki pagesYesFull GFM
      GistsYesFull GFM
      Commit messagesPartialBasic formatting, autolinks - no Mermaid or math
      GitHub Pages (Jekyll)DependsJekyll has its own Markdown processor
      VS Code previewMostlySupports most GFM; Mermaid requires an extension
      +

      18. Alert and Callout Blocks

      +

      GitHub introduced alert blocks in 2023. They render as colored, bordered callout boxes - great for emphasizing warnings, tips, or critical information. You will see these throughout this course to highlight screen reader notes, important warnings, and tips.

      +

      Syntax

      +
      > [!NOTE]
+> Useful information that users should know, even when skimming.
+
+> [!TIP]
+> Helpful advice for doing something better or more easily.
+
+> [!IMPORTANT]
+> Key information users need to know to achieve their goal.
+
+> [!WARNING]
+> Urgent info that needs immediate attention to avoid problems.
+
+> [!CAUTION]
+> Advises about risks or negative outcomes of certain actions.
      +

      How to write them

      +
        +
      1. Start a blockquote with >
        2. +
      2. The first line must be exactly > [!TYPE] where TYPE is one of: NOTE, TIP, IMPORTANT, WARNING, CAUTION
        3. +
      3. All subsequent lines start with > and a space, just like a regular blockquote
        4. +
      4. You can include any Markdown inside the alert: lists, code, links, bold
        5. +
      +

      Choosing the right alert type

      +

      The following table describes each alert type and when to use it.

      + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + +
      TypeColorWhen to useExample
      NOTEBlueSupplementary information the reader should knowAdditional context about a feature
      TIPGreenBest practice or shortcut"Use Ctrl+Shift+P for faster access"
      IMPORTANTPurpleSomething the reader absolutely must knowRequired configuration step
      WARNINGYellowA potential problem or non-obvious risk"This changes are not reversible after merge"
      CAUTIONRedAn action that could cause irreversible harm"This deletes all branches and cannot be undone"
      +

      Multi-line alert with formatting

      +
      > [!WARNING]
+> **Do not skip the pre-workshop setup.**
+>
+> If you arrive without a configured environment, you will spend the first
+> hour catching up while others are working on challenges. Complete
+> [Chapter 0](00-pre-workshop-setup.md) before Day 1.
+>
+> Checklist:
+>
+> - Git installed
+> - GitHub account created
+> - Screen reader configured for GitHub
      +

      Screen Reader Behavior

      +

      Alert blocks render as <blockquote> elements with an SVG icon and a strong heading. Screen readers read:

      +
        +
      • NVDA/JAWS: announces blockquote role, then reads the type label ("Note", "Warning") then the content
        • +
      • VoiceOver: reads the type as bold text then the content
        • +
      • The colored icon is decorative (aria-hidden); it does not add information beyond the type label
        • +
      +

      19. Collapsible Sections with Details and Summary

      +

      The <details> and <summary> HTML elements create collapsible sections. They are one of the most useful tools for keeping long documents, issue reports, and PRs manageable - hiding optional content until the reader chooses to expand it.

      +

      Basic syntax

      +
      <details>
+<summary>Click to expand: Full error log</summary>
+
+Content that is hidden until the user expands this section.
+
+You can put **any Markdown** in here:
+
+- Lists
+- Code blocks
+- Links
+- Tables
+
+</details>
      +

      Important formatting rules

      +
        +
      1. Blank line after <summary>. Put a blank line between the closing </summary> tag and your Markdown content. Without it, Markdown formatting inside may not render
        2. +
      2. Blank line before </details>. Same principle at the end
        3. +
      3. The <summary> text should be descriptive - it is the only thing visible when collapsed
        4. +
      +

      Real-world uses in this workshop

      +

      The following list describes common uses for collapsible sections.

      +
        +
      • Bug reports in issues: Collapse the full stack trace so the issue body stays readable
        • +
      • Long configuration blocks: Let readers expand the full YAML only if they need it
        • +
      • Exercise solutions: Collapse the answer so learners try the exercise first
        • +
      • Screen reader guidance blocks: Throughout this course, some sections collapse detailed assistive technology instructions so sighted users see a cleaner page while screen reader users can easily expand them
        • +
      • Meeting notes: Collapse detailed minutes while showing the summary
        • +
      +

      Nesting details inside details

      +
      <details>
+<summary>Operating system instructions</summary>
+
+<details>
+<summary>Windows</summary>
+
+1. Open PowerShell
+2. Run `git --version`
+
+</details>
+
+<details>
+<summary>macOS</summary>
+
+1. Open Terminal
+2. Run `git --version`
+
+</details>
+
+</details>
      +

      Details sections that start open

      +

      Add the open attribute to have the section expanded by default:

      +
      <details open>
+<summary>Currently known issues</summary>
+
+- Checkbox toggle requires Focus Mode in NVDA
+- Alert blocks do not render in email notifications
+
+</details>
      +

      Screen Reader Behavior

      +

      The <details> element renders as a disclosure widget:

      +
        +
      • NVDA: announces "button collapsed" for the <summary> - press Enter or Space to expand
        • +
      • JAWS: announces "collapsed" - press Enter on the summary to expand
        • +
      • VoiceOver: announces "collapsed, button" - press VO+Space to activate
        • +
      +

      After expanding: The content is immediately readable. Screen readers announce "button expanded" for the summary. No page reload occurs.

      +

      Learning Cards: Collapsible Sections

      +

      Screen reader users:

      +
        +
      • The <summary> element is announced as a button -- press Enter or Space to toggle between collapsed and expanded; listen for "collapsed" or "expanded" state announcements
        • +
      • After expanding, the content is immediately available -- arrow down to read it; no page reload or focus change occurs
        • +
      • Nested <details> blocks (details inside details) work but add complexity -- each level is an independent toggle button; keep nesting to one level deep for predictable navigation
        • +
      +

      Low-vision users:

      +
        +
      • The summary text is the only visible element when collapsed -- it appears as a disclosure triangle (>) with text; zoom in to ensure the triangle and text are both readable
        • +
      • Expanded content appears inline below the summary -- at high zoom it flows naturally with the rest of the page content
        • +
      • The open attribute forces a section to start expanded -- useful when the content is important enough that most readers should see it by default
        • +
      +

      Sighted users:

      +
        +
      • Collapsed sections show a disclosure triangle (>) that rotates to point downward when expanded -- click the summary text or triangle to toggle
        • +
      • Use collapsible sections to keep long documents manageable: error logs, configuration blocks, and exercise solutions are good candidates for hiding behind a summary
        • +
      • Always write descriptive summary text ("Full error log from CI run" not just "Details") so readers know whether they need to expand the section
        • +
      +

      20. Task List Checkboxes

      +

      Task lists in GitHub issues and PRs render as real interactive checkboxes. Anyone with write access to the repository can check and uncheck them directly in the rendered view without editing the Markdown.

      +

      Syntax

      +
      - [x] Color contrast verified (4.5:1 minimum for body text)
+- [x] Keyboard navigation tested
+- [ ] Screen reader tested with NVDA
+- [ ] Screen reader tested with JAWS
+- [ ] Screen reader tested with VoiceOver
+- [ ] Alt text provided for all images
+- [ ] Focus indicators visible
      +

      How to write them

      +
        +
      1. Start with a list item marker (-, *, or +) and a space
        2. +
      2. Add [x] for a checked box or [ ] (with a space inside) for an unchecked box
        3. +
      3. Add a space, then the task description
        4. +
      4. The description should be meaningful - "Test NVDA" is better than "Item 3"
        5. +
      +

      What makes task lists special on GitHub

      +
        +
      • Progress tracking: In issues, GitHub shows a progress bar: "2 of 7 tasks completed"
        • +
      • Click to check: In the rendered view, users with triage or write permissions can click to toggle checkboxes without editing the comment
        • +
      • Linked issues: You can reference issues in a task: - [ ] Fix #42 - the task shows the issue title and its open/closed state
        • +
      • PR templates: Task lists in PR templates create checklists that authors fill out before requesting review
        • +
      +

      Example - pull request checklist

      +
      ## Pre-review checklist
+
+- [x] Changes are limited to the files listed in the issue
+- [x] All new images have descriptive alt text
+- [ ] Screen reader tested the changes with NVDA
+- [ ] No heading levels are skipped
+- [ ] All links use descriptive text (not "click here")
      +

      Screen Reader Interaction

      +

      In Browse Mode, checkboxes are read as checkbox, not checked or checkbox, checked.

      +

      To toggle a task list checkbox:

      +
        +
      • NVDA: Press NVDA+Space to enter Focus Mode, then Tab to find the checkbox, then Space to toggle it
        • +
      • JAWS: Tab to the checkbox, then Space to toggle
        • +
      • VoiceOver: VO+Space on the checkbox element
        • +
      +

      21. Syntax Highlighting in Fenced Code Blocks

      +

      We covered basic code blocks in Section 13. This section covers the GitHub-specific syntax highlighting that makes code blocks more readable for sighted users.

      +

      How it works

      +

      Add a language identifier right after the opening triple backticks. GitHub uses Linguist to apply syntax highlighting with appropriate colors for keywords, strings, comments, and other language constructs.

      +
      ```python
+def check_accessibility(element):
+    """Check if an element has proper ARIA attributes."""
+    if not element.get("aria-label") and not element.get("aria-labelledby"):
+        return "Missing accessible name"
+    return "Accessible"
+```
      +

      Complete list of commonly used language identifiers

      +

      The following table lists the language identifiers you are most likely to use.

      + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + +
      IdentifierLanguageExample use in this workshop
      pythonPythonScripts, automation, challenge code
      bash or shellBash/ShellTerminal commands, Git operations
      yaml or ymlYAMLGitHub Actions, issue templates
      jsonJSONConfiguration, API responses
      javascript or jsJavaScriptWeb scripts
      typescript or tsTypeScriptTyped JavaScript
      htmlHTMLWeb page structure
      cssCSSStyling
      markdown or mdMarkdownDocumenting Markdown syntax
      diffDiffCode change comparison
      text or plaintextNoneNo highlighting needed
      rubyRubyRuby scripts
      goGoGo programs
      rustRustRust programs
      javaJavaJava programs
      csharp or csC#.NET programs
      sqlSQLDatabase queries
      dockerfileDockerfileContainer configuration
      xmlXMLStructured data
      tomlTOMLConfiguration (Rust, Python)
      iniINIConfiguration files
      powershell or ps1PowerShellWindows automation
      +

      If no language is specified, the code block renders as plain monospaced text with no highlighting.

      +

      Screen Reader Note

      +

      Syntax highlighting is visual only - screen readers read the code text without announcing color changes. The code block itself is announced as a code region. This means the text content of well-written code is equally accessible whether highlighted or not. Variable names, function names, and comments are the real accessibility of code - not colors.

      +

      22. Mermaid Diagrams

      +

      GitHub renders Mermaid.js diagrams inline when you use a mermaid fenced code block. They are common in READMEs, PRs, and documentation to illustrate architecture, flows, and relationships.

      +

      Syntax

      +
      ```mermaid
+flowchart LR
+    A[Fork repo] --> B[Clone locally]
+    B --> C[Create branch]
+    C --> D[Make changes]
+    D --> E[Push branch]
+    E --> F[Open PR]
+    F --> G{Review passed?}
+    G -- Yes --> H[Merge]
+    G -- No --> D
+```
      +

      Common diagram types

      +

      The following table lists the Mermaid diagram types you are most likely to encounter on GitHub.

      + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + +
      TypeKeywordUse case
      Flowchartflowchart LR or flowchart TDProcess flows, decision trees
      Sequence diagramsequenceDiagramAPI calls, user interactions
      Entity-RelationshiperDiagramDatabase schemas
      Class diagramclassDiagramCode architecture
      Gantt chartganttProject schedules
      Git graphgitGraphBranch and merge visualization
      Pie chartpieData distribution
      +

      Accessibility limitation - critical

      +
      +

      Important: Mermaid diagrams render as SVG images. GitHub does not auto-generate alt text for them. Screen readers will typically either skip them entirely or announce generic SVG container information that is not useful.

      +
      +

      This means every Mermaid diagram is invisible to screen reader users unless you provide a text alternative.

      +

      How to make Mermaid diagrams accessible

      +

      Always follow this pattern:

      +
        +
      1. Write a text description before the diagram that conveys all the same information
        2. +
      2. Optionally, duplicate the information as a numbered list or table
        3. +
      3. Consider wrapping the Mermaid source in a <details> block if the text description is sufficient
        4. +
      +

      Example - accessible Mermaid usage:

      +
      The PR workflow follows these steps: fork the repository, clone
+your fork locally, create a feature branch, make your changes and commit,
+push the branch to your fork, open a pull request, address review feedback,
+and merge when approved.
+
+1. Fork the repository
+2. Clone your fork locally
+3. Create a feature branch
+4. Make your changes and commit
+5. Push the branch to your fork
+6. Open a pull request
+7. Address review feedback
+8. Merge when approved
+
+<details>
+<summary>Diagram source (Mermaid)</summary>
+
+```mermaid
+flowchart LR
+    Fork --> Clone --> Branch --> Commit --> Push --> PR --> Review --> Merge
+```
+
+</details>
      +

      This way, screen reader users get the full information from the text and numbered list. Sighted users can also expand the Mermaid diagram for a visual representation.

      +

      23. Math Expressions with LaTeX

      +

      GitHub renders LaTeX math expressions using MathJax. This is common in data science, research, and algorithm documentation.

      +

      Inline math

      +

      Use single $ delimiters for math within a sentence:

      +
      The formula is $e = mc^2$ where $c$ is the speed of light.
      +

      Renders as: The formula is $e = mc^2$ where $c$ is the speed of light.

      +

      Block math

      +

      Use $$ delimiters for display-style (centered, larger) math on their own lines:

      +
      $$
+\sum_{i=1}^{n} x_i = \frac{n(n+1)}{2}
+$$
      +

      Common LaTeX patterns

      +

      The following table shows some LaTeX patterns you might encounter.

      + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + +
      What you wantLaTeXRendered
      Superscript$x^2$$x^2$
      Subscript$x_i$$x_i$
      Fraction$\frac{a}{b}$$\frac{a}{b}$
      Square root$\sqrt{x}$$\sqrt{x}$
      Greek letter$\alpha, \beta, \gamma$$\alpha, \beta, \gamma$
      Summation$\sum_{i=1}^{n}$$\sum_{i=1}^{n}$
      Not equal$\neq$$\neq$
      Less or equal$\leq$$\leq$
      +

      Screen Reader Note

      +

      Math expressions rendered by MathJax include aria-label attributes with the spoken form of the equation. Screen readers should announce the math correctly, but accuracy varies:

      +
        +
      • NVDA with Firefox or Chrome: reads MathML fairly well
        • +
      • JAWS: reads the aria-label text
        • +
      • VoiceOver: reads the aria-label text
        • +
      +

      Best practice: If writing documentation for an accessibility-focused audience, supplement complex equations with a plain English description:

      +
      The sum of all values from 1 to n equals n times n+1 divided by 2:
+
+$$
+\sum_{i=1}^{n} x_i = \frac{n(n+1)}{2}
+$$
      +

      24. Footnotes

      +

      GitHub supports Markdown footnotes, which render as superscript numbers that link to references at the bottom of the document. They are useful for citations, additional context, and references that would interrupt the flow of the main text.

      +

      Syntax

      +
      This technique improves screen reader navigation significantly.[^1]
+You can also use named footnotes for clarity.[^accessibility-note]
+
+[^1]: Based on the WebAIM Screen Reader Survey, 2024.
+[^accessibility-note]: See WCAG 2.2 Success Criterion 2.4.3 for focus order requirements.
      +

      How they work

      +
        +
      1. In your text, add [^identifier] where you want the footnote reference to appear
        2. +
      2. Anywhere in the document (typically at the bottom), define the footnote with [^identifier]: Your footnote text
        3. +
      3. GitHub renders the reference as a superscript number that links to the definition
        4. +
      4. The definition includes a back-link that returns to the reference location
        5. +
      +

      Footnote identifiers

      +
        +
      • You can use numbers: [^1], [^2], [^3]
        • +
      • You can use descriptive names: [^webaim-survey], [^wcag-reference]
        • +
      • Descriptive names make the raw Markdown more readable but render as sequential numbers
        • +
      +

      Multi-line footnotes

      +

      Indent continuation lines with two spaces:

      +
      [^long-note]: This is a longer footnote that spans multiple paragraphs.
+
+  The second paragraph of the footnote is indented with two spaces.
+
+  You can even include code: `git status`
      +

      Screen Reader Behavior

      +
        +
      • The footnote reference is a link (<a> element) announcing its number
        • +
      • NVDA: "superscript, 1, link"
        • +
      • JAWS: "link, 1"
        • +
      • VoiceOver: "link, footnote 1"
        • +
      • The back-link at the definition reads "return to footnote reference"
        • +
      • Activating the footnote link jumps focus to the definition; activating the back-link returns focus to the original location
        • +
      +

      25. Linked Heading Anchors and Tables of Contents

      +

      Every heading in a GitHub Markdown file automatically gets an anchor ID. You can link to any heading from anywhere - within the same document, from another file, or from an issue or PR.

      +

      How GitHub generates anchor IDs

      +

      GitHub converts the heading text to an anchor ID by:

      +
        +
      1. Converting to lowercase
        2. +
      2. Replacing spaces with hyphens
        3. +
      3. Removing most punctuation (except hyphens)
        4. +
      4. Removing leading and trailing whitespace
        5. +
      +

      The following table shows example headings and their generated anchors.

      + + + + + + + + + + + + + + + + + + + + + + + + + + + +
      Heading textGenerated anchor
      # Introduction#introduction
      ## Getting Started#getting-started
      ### VS Code: Setup & Accessibility Basics#vs-code-setup--accessibility-basics
      ## 1. First Steps#1-first-steps
      ## What Is a PR?#what-is-a-pr
      +

      Linking to a heading in the same document

      +
      See the [Tables](#16-tables) section for details on formatting data.
+Return to the [Table of Contents](#table-of-contents).
      +

      Linking to a heading in another file

      +
      See the [Pre-Workshop Setup guide](00-pre-workshop-setup.md#step-1---create-a-github-account).
      +

      Building a table of contents

      +

      You can build a manual table of contents using heading anchor links:

      +
      ## Table of Contents
+
+1. [Introduction](#introduction)
+2. [Installation](#installation)
+3. [Configuration](#configuration)
+4. [Usage](#usage)
+5. [Contributing](#contributing)
      +

      Duplicate headings

      +

      If a document has two headings with the same text, GitHub appends -1, -2, and so on to the duplicate anchors:

      + + + + + + + + + + + + + + + + + + + +
      HeadingAnchor
      First ## Examples#examples
      Second ## Examples#examples-1
      Third ## Examples#examples-2
      +

      Best practice: Avoid duplicate heading text. Use descriptive, unique headings for each section.

      +

      Finding the anchor for any heading

      +
        +
      1. Mouse users: On GitHub, hover over any heading - a chain link icon appears to the left. Click it to update the URL with the anchor
        2. +
      2. Screen reader users: Navigate to the heading, then Tab once. A link button appears. Activate it and the URL in the address bar updates to show the anchor
        3. +
      3. Keyboard (GitHub shortcut): There is no direct shortcut, but you can copy the heading text, convert it to the anchor format mentally, and type it in the URL
        4. +
      +

      26. Autolinked References - Issues, PRs, Commits, and Users

      +

      One of GitHub's most powerful features is automatic linking. When you type certain patterns in any Markdown field on GitHub, they automatically become clickable links. This is how the entire GitHub collaboration workflow connects.

      +

      Issue and pull request references

      +

      The following table shows how to reference issues and pull requests.

      + + + + + + + + + + + + + + + + + + + + + + + +
      What you typeWhat it links toExample
      #42Issue or PR number 42 in the current repo"See #42 for details"
      GH-42Same as above (alternative syntax)"Fixed in GH-42"
      owner/repo#42Issue 42 in a different repo"Related: community-access/accessibility-agents#15"
      +

      User and team mentions

      +

      The following table shows how to mention users and teams.

      + + + + + + + + + + + + + + + + + + +
      What you typeWhat it doesExample
      @usernameMentions a user, sends them a notification"Thanks @johndoe for the review"
      @org/team-nameMentions an entire team"Cc @community-access/maintainers"
      +

      Commit references

      +

      The following table shows how to reference specific commits.

      + + + + + + + + + + + + + + + + + + +
      What you typeWhat it links toExample
      Full SHA: a1b2c3d4e5f6...Links to that commit (first 7+ chars)"Fixed in a1b2c3d"
      owner/repo@SHACommit in another repo"See community-access/accessibility-agents@a1b2c3d"
      +

      Closing keywords in pull requests

      +

      When you include certain keywords followed by an issue reference in a PR description, merging the PR automatically closes the referenced issue:

      +
      This PR adds alt text to all images in the documentation.
+
+Closes #42
+Fixes #43
+Resolves #44
      +

      All of these keywords work: close, closes, closed, fix, fixes, fixed, resolve, resolves, resolved. They are case-insensitive.

      +

      URL autolinking

      +

      GitHub automatically converts full URLs into clickable links:

      +
      Check out https://github.com/community-access/accessibility-agents for the project.
      +
      +

      Accessibility note: While autolinked URLs work, they create poor link text for screen readers (the entire URL is read character by character). In documentation and issue descriptions, always use descriptive link text instead: [Accessibility Agents repository](https://github.com/community-access/accessibility-agents).

      +
      +

      27. HTML in Markdown

      +

      GitHub allows a subset of HTML in Markdown files. This is useful for semantic elements that do not have Markdown equivalents, advanced layout needs, and accessibility improvements.

      +

      Keyboard key visualization

      +

      The <kbd> element renders text in a key-cap style box:

      +
      Press <kbd>Ctrl</kbd>+<kbd>C</kbd> to copy.
+Press <kbd>NVDA</kbd>+<kbd>Space</kbd> to toggle Focus Mode.
      +

      Press Ctrl+C to copy. +Press NVDA+Space to toggle Focus Mode.

      +

      Subscript and superscript

      +
      H<sub>2</sub>O is water.
+E = mc<sup>2</sup> is Einstein's equation.
      +

      H2O is water. +E = mc2 is Einstein's equation.

      +

      Centered content

      +
      <div align="center">
+  <img src="logo.png" alt="Community Access logo - a circle with the letters C and A interlinked" width="200">
+</div>
      +

      Line breaks

      +
      Line one<br>
+Line two on the next line, same paragraph.
      +

      Hidden comments

      +
      <!-- This comment will not appear in the rendered output -->
+<!-- TODO: Add screen reader testing results before publishing -->
      +

      Hidden comments are useful for notes to yourself or other contributors that should not be visible to readers.

      +

      Allowed HTML elements on GitHub

      +

      GitHub whitelists specific HTML elements for security. The following table lists the most useful allowed elements.

      + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + +
      ElementPurposeScreen reader behavior
      <details> / <summary>Collapsible sectionsAnnounced as disclosure widget
      <kbd>Keyboard keysAnnounced as "code" or the text content
      <sub> / <sup>Subscript / superscriptText read normally; some SRs announce position
      <br>Line breakBrief pause in reading
      <div>Generic containerNo announcement unless has role/aria
      <img>Image with attributesAlt text read
      <a>Link with attributesLink text read
      <table>, <th>, <td>Complex tableFull table navigation
      <!-- -->CommentNot read (invisible)
      +

      Disallowed HTML on GitHub

      +

      GitHub strips these elements for security:

      +
        +
      • <script> - No JavaScript execution
        • +
      • <style> - No arbitrary CSS
        • +
      • <iframe> - No embedded content
        • +
      • <form> - No form elements (except task list checkboxes)
        • +
      • <input> - No input fields
        • +
      • Event attributes like onclick, onload
        • +
      +

      Part 3 - Putting It All Together

      +

      28. Screen Reader Behavior Summary

      +

      This table consolidates how every Markdown element behaves with screen readers. Use it as a quick reference when choosing how to format your content.

      +

      The following table provides a summary of screen reader behavior for each Markdown and GFM element.

      + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + +
      ElementWhat screen readers announceAuthor responsibility
      ParagraphsRead as text blocks, pause between paragraphsUse blank lines between paragraphs
      HeadingsHeading level and text; navigable with H keyOne H1, no skipped levels, descriptive text
      Bold / italicMay announce emphasis (depends on settings)Use for meaning, not just visual styling
      StrikethroughMay announce "deleted" (inconsistent)Add text context, do not rely on visual alone
      Ordered lists"List, X items" then "1. item text"Use for sequential steps
      Unordered lists"List, X items" then "bullet, item text"Use for non-sequential items
      Links"Link, link text"Descriptive text that makes sense alone
      Images"Graphic, alt text"Always write meaningful alt text
      Blockquotes"Block quote" on enter, "out of block quote" on exitUse for callouts and important information
      Inline codeText read normally (may say "code")Use for commands, file names, values
      Code blocks"Code region" with text contentAdd language identifier; write clear code
      TablesRow/column navigation with headers announcedAdd description before table; keep simple
      Horizontal rules"Separator"Use sparingly; headings are better
      Alert blocksBlockquote with type labelChoose appropriate alert type
      Details/summary"Button, collapsed/expanded"Write clear summary text
      Task checkboxes"Checkbox, checked/not checked"Descriptive task labels
      Mermaid diagramsSVG may be skippedAlways provide text equivalent
      Math expressionsaria-label readSupplement complex math with plain English
      Footnotes"Link, footnote N"Use descriptive footnote text
      Heading anchorsHeadings navigable normallyUnique, descriptive heading text
      <kbd>"Code" or text contentUse for keyboard instructions
      +

      29. Accessible Markdown Authoring Checklist

      +

      Use this checklist every time you write a Markdown file, issue, or PR description. It covers the accessibility requirements that make your content work for everyone.

      +

      Structure

      +
        +
      • One H1 heading per document, used as the title
        • +
      • Heading levels never skip (no jumping from H2 to H4)
        • +
      • Headings are descriptive (not "Section 1" or "Untitled")
        • +
      • Long documents have a table of contents with anchor links
        • +
      +

      Text and emphasis

      +
        +
      • Bold marks genuinely important content, not just visual styling
        • +
      • Bold text is not used as a substitute for headings
        • +
      • Strikethrough text has surrounding context explaining the change
        • +
      + +
        +
      • Every link has descriptive text (never "click here," "here," "read more," or "link")
        • +
      • No bare URLs in prose (always use [descriptive text](url))
        • +
      • Multiple links on the same page have unique text if they point to different destinations
        • +
      • Relative links used for files within the same repository
        • +
      +

      Images

      +
        +
      • Every informative image has descriptive alt text
        • +
      • Alt text is not a filename (screenshot.png) or generic (image, photo)
        • +
      • Complex images (charts, diagrams) have a detailed text description in a <details> block
        • +
      • Decorative images have empty alt text: ![](image.png)
        • +
      +

      Lists and tables

      +
        +
      • Lists use the correct type: ordered for sequential steps, unordered for non-sequential items
        • +
      • Tables have a text description immediately before them
        • +
      • Tables have descriptive header cells
        • +
      • Tables have fewer than 7 columns (split wide tables)
        • +
      • Tables are used for data, not layout
        • +
      +

      Code

      +
        +
      • Fenced code blocks have a language identifier
        • +
      • Inline code used for commands, file names, and values
        • +
      • Code examples are complete enough to understand without the visual highlighting
        • +
      +

      GFM features

      +
        +
      • Mermaid diagrams have a text equivalent
        • +
      • Alert block type matches the urgency of the content
        • +
      • <details> summary text clearly describes what is inside
        • +
      • Task list items have descriptive labels
        • +
      • Complex math expressions have plain English descriptions
        • +
      +

      General

      +
        +
      • Color is never the only way information is conveyed
        • +
      • No information is communicated only through visual position or layout
        • +
      • Content makes sense when read linearly, top to bottom
        • +
      +

      30. Common Mistakes and How to Fix Them

      +

      This section covers the errors we see most often in workshop participants' Markdown. Each one includes what goes wrong, why it matters, and how to fix it.

      +

      Mistake 1 - Forgetting the blank line between paragraphs

      +

      What goes wrong:

      +
      This is paragraph one.
+This is paragraph two.
      +

      What it produces: One merged paragraph.

      +

      Fix: Add a blank line between paragraphs.

      +

      Mistake 2 - Skipping heading levels

      +

      What goes wrong:

      +
      # My Document
+
+#### Some Detail
      +

      Why it matters: Screen reader users navigating by heading level will miss entire sections. Jumping from H1 to H4 means H2 and H3 navigation finds nothing.

      +

      Fix: Use all levels in order: # then ## then ### then ####.

      +

      Mistake 3 - Generic link text

      +

      What goes wrong:

      +
      For more information, click [here](https://docs.github.com).
      +

      Why it matters: A screen reader user scanning the links list hears "here" - with no context about where the link goes.

      +

      Fix: For more information, read the [GitHub Documentation](https://docs.github.com).

      +

      Mistake 4 - Missing alt text on images

      +

      What goes wrong:

      +
      ![](screenshot.png)
      +

      Why it matters: Screen reader users have no idea what the image shows. Some screen readers announce the filename, which is not helpful.

      +

      Fix: Always add descriptive alt text: ![Screenshot of the GitHub issue creation form with the title field focused](screenshot.png)

      +

      Mistake 5 - Using bold instead of headings

      +

      What goes wrong:

      +
      **Getting Started**
+
+Here is how to get started with the project...
      +

      Why it matters: Visually, this looks like a heading. But screen reader users navigating with H will never find it. It is not in the document outline.

      +

      Fix: Use a real heading: ## Getting Started

      +

      Mistake 6 - No description before a table

      +

      What goes wrong:

      +
      | Name | Role |
+|---|---|
+| Alex | Facilitator |
+| Jamie | Co-host |
      +

      Why it matters: A screen reader user enters the table without knowing what data it contains. They hear "table, 2 columns, 3 rows" but not what the table is about.

      +

      Fix: Add a sentence before the table: "The following table lists the workshop team members and their roles."

      +

      Mistake 7 - Code block without a language identifier

      +

      What goes wrong:

      +
      ```
+def hello():
+    print("Hello!")
+```
      +

      Why it matters: Without the language identifier, sighted users lose the visual benefit of syntax highlighting, and tools that process Markdown lose metadata about the content.

      +

      Fix: Always add the language: ```python

      +

      Mistake 8 - Inconsistent list markers

      +

      What goes wrong:

      +
      - First item
+* Second item
++ Third item
      +

      Why it matters: While most processors render this as one list, some treat different markers as separate lists, creating unexpected spacing and structure.

      +

      Fix: Pick one marker and use it consistently. Use - for unordered lists.

      +

      Mistake 9 - Mermaid diagram without a text equivalent

      +

      What goes wrong:

      +
      ```mermaid
+flowchart LR
+    A --> B --> C --> D
+```
      +

      Why it matters: Screen reader users cannot access the visual diagram. They hear nothing or a generic SVG container message.

      +

      Fix: Add a complete text description before the diagram and consider wrapping the Mermaid block in <details>.

      +

      Mistake 10 - Alert block with wrong type

      +

      What goes wrong:

      +
      > [!CAUTION]
+> You might want to try a different approach.
      +

      Why it matters: CAUTION (red) implies irreversible harm. A suggestion to try a different approach is, at most, a TIP (green) or a NOTE (blue). Using the wrong severity trains readers to ignore warnings.

      +

      Fix: Match the alert type to the actual urgency. Use CAUTION only for actions that could cause real harm.

      +

      31. Your First Real Markdown Document - Guided Exercise

      +

      Let us put everything together. In this exercise, you will create a Markdown document that uses most of the elements covered in this guide. This is structured as a hands-on exercise that you can do during the workshop.

      +

      Setup

      +
        +
      1. Open any repository where you have write access
        2. +
      2. Click New Issue (or create a new .md file in VS Code)
        3. +
      3. You will write a mini profile document about yourself
        4. +
      +

      Step 1 - Add a heading and introduction

      +

      Type the following, replacing the placeholder text with your own information:

      +
      # About Me
+
+Hi! My name is [your name] and I am participating in the
+GIT Going with GitHub workshop.
      +

      Use the Preview tab (or Ctrl+Shift+V in VS Code) to verify the heading renders as a large title.

      +

      Step 2 - Add a section with a list

      +
      ## What I Want to Learn
+
+1. How to navigate GitHub with my screen reader
+2. How to file a useful bug report
+3. How to open my first pull request
+4. How to review someone else's code
      +

      Verify the numbered list renders correctly.

      +

      Step 3 - Add emphasis and inline code

      +
      ## My Setup
+
+I use **NVDA** on Windows with *Firefox*. My terminal is
+`PowerShell` and I am learning `git` commands.
      +

      Check that bold, italic, and inline code all render as expected.

      +

      Step 4 - Add a link and a blockquote

      +
      ## Favorite Resource
+
+My favorite learning resource so far is the
+[GitHub Skills courses](https://skills.github.com) because they
+are step-by-step and hands-on.
+
+> **Workshop tip:** Setting up your environment before Day 1 saves
+> at least an hour. See the [Pre-Workshop Setup](docs/00-pre-workshop-setup.md)
+> chapter.
      +

      Step 5 - Add a table

      +
      ## Tools I Use
+
+The following table lists the tools I use daily.
+
+| Tool | Purpose | Platform |
+|---|---|---|
+| NVDA | Screen reader | Windows |
+| Firefox | Web browser | Windows |
+| VS Code | Code editor | Windows |
      +

      Step 6 - Add a task list

      +
      ## My Workshop Checklist
+
+- [x] Created GitHub account
+- [x] Installed Git
+- [ ] Configured screen reader for GitHub
+- [ ] Completed the Pre-Workshop Setup chapter
+- [ ] Joined the GitHub Discussions channel
      +

      Step 7 - Add a collapsible section

      +
      ## Additional Notes
+
+<details>
+<summary>My accessibility testing experience</summary>
+
+I have been using a screen reader for three years. I have tested
+web applications with NVDA and I am learning how to contribute
+accessibility bug reports to open source projects.
+
+</details>
      +

      You are done when

      +
        +
      • Your document renders with a clear heading hierarchy (H1, H2)
        • +
      • Bold and italic text render correctly
        • +
      • The numbered list shows sequential numbers
        • +
      • The link is clickable
        • +
      • The table has visible column headers
        • +
      • The task list shows checkboxes
        • +
      • The details section collapses and expands
        • +
      +

      Congratulations. You just wrote a Markdown document that uses headings, paragraphs, emphasis, inline code, links, blockquotes, tables, task lists, and collapsible sections. Every one of these skills transfers directly to issues, pull requests, and documentation in this workshop.

      +

      Learning Cards: Quick-Reference Card

      +
      +Screen reader users + +
        +
      • This card shows raw Markdown syntax in code blocks -- read each block to hear the exact characters to type
        • +
      • Keep this section bookmarked as a daily reference when writing issues, PRs, and comments
        • +
      • Each code block is labeled by format type (headings, lists, links, etc.) in the heading above it
        • +
      +
      + +
      +Low vision users + +
        +
      • The card uses large monospace code blocks -- increase zoom and each syntax example stays on one or two lines
        • +
      • Print this section or save it as a separate file for quick side-by-side reference while writing
        • +
      • Syntax characters (*, #, -, []) are visually distinct in the code font
        • +
      +
      + +
      +Sighted users + +
        +
      • This is a one-page cheat sheet for all Markdown syntax covered in the guide
        • +
      • Scan the code blocks for the formatting you need -- copy the pattern and replace the placeholder text
        • +
      • Pin this section in a browser tab alongside your editing window
        • +
      +
      + + +

      32. Quick-Reference Card

      +

      Copy this card and keep it handy. It shows the raw Markdown for every element covered in this guide.

      +

      Basic formatting

      +
      **bold text**
+*italic text*
+***bold and italic***
+~~strikethrough~~
+`inline code`
      +

      Headings

      +
      # Heading 1
+## Heading 2
+### Heading 3
+#### Heading 4
      +

      Lists

      +
      - Unordered item
+- Another item
+    - Nested item
+
+1. First step
+2. Second step
+3. Third step
      + +
      [Link text](https://example.com)
+[Link with title](https://example.com "Title text")
+![Alt text describing the image](image.png)
      +

      Blockquotes

      +
      > This is a blockquote.
+>
+> It can span multiple paragraphs.
      +

      Code blocks

      +
      ```python
+print("Hello, world!")
+```
      +

      Tables

      +
      | Header 1 | Header 2 |
+|---|---|
+| Cell 1 | Cell 2 |
      +

      Horizontal rule

      +
      +

      Task lists

      +
      - [x] Completed task
+- [ ] Incomplete task
      +

      Alert blocks

      +
      > [!NOTE]
+> Informational callout.
+
+> [!TIP]
+> Helpful advice.
+
+> [!IMPORTANT]
+> Key information.
+
+> [!WARNING]
+> Potential problem.
+
+> [!CAUTION]
+> Irreversible action warning.
      +

      Collapsible sections

      +
      <details>
+<summary>Section title</summary>
+
+Hidden content goes here.
+
+</details>
      +

      Footnotes

      +
      Text with a footnote reference.[^1]
+
+[^1]: The footnote definition.
      + +
      [Jump to Installation](#installation)
+[Link to another file section](other-file.md#section-name)
      +

      Autolinked references

      +
      #42              (issue or PR in current repo)
+@username        (mention a user)
+owner/repo#42   (issue in another repo)
+Closes #42      (close issue when PR merges)
      +

      Math

      +
      Inline: $e = mc^2$
+
+Block:
+$$
+\sum_{i=1}^{n} x_i
+$$
      +

      HTML in Markdown

      +
      Press <kbd>Ctrl</kbd>+<kbd>C</kbd> to copy.
+H<sub>2</sub>O
+x<sup>2</sup>
+Line one<br>Line two
+<!-- Hidden comment -->
      +

      Mermaid diagram (with accessible text)

      +
      Description of the diagram in plain text here.
+
+<details>
+<summary>Visual diagram (Mermaid)</summary>
+
+```mermaid
+flowchart LR
+    A --> B --> C
+```
+
+</details>
      +
      +

      Next: Appendix D: Git Authentication
      Back: Appendix B: Screen Reader Cheat Sheet
      Teaching chapter: Chapter 06: Working with Pull Requests

      + +
      + + + + diff --git a/html/admin/qa-bundle/docs/appendix-d-git-authentication.html b/html/admin/qa-bundle/docs/appendix-d-git-authentication.html new file mode 100644 index 00000000..3a8c29d9 --- /dev/null +++ b/html/admin/qa-bundle/docs/appendix-d-git-authentication.html @@ -0,0 +1,374 @@ + + + + + + + Appendix D: Git Authentication - GIT Going with GitHub + + + + + + + + +
      +

      Appendix D: Git Authentication

      +
      +

      Listen to Episode 21: Git Authentication - a conversational audio overview of this chapter. Listen before reading to preview the concepts, or after to reinforce what you learned.

      +
      +
      +

      Reference companion to: Chapter 00: Pre-Workshop Setup | Also relevant: Chapter 14

      +

      Authoritative source: GitHub Docs: Authenticating with GitHub from Git

      +
      +

      SSH Keys & Personal Access Tokens

      +
      +

      Audience: This appendix is for contributors who need to configure Git authentication for push access. If you're working entirely through the GitHub web interface or GitHub Desktop, you can skip this. If you're using VS Code with Git command line, this becomes relevant when you want to push commits to your fork.

      +
      +

      Learning Cards: Using This Authentication Reference

      +
      +Screen reader users + +
        +
      • This appendix has two main paths: Personal Access Token (recommended) and SSH Keys -- jump to your chosen method via heading navigation
        • +
      • Step-by-step instructions are numbered lists -- your screen reader announces "1 of 8," etc. to track progress
        • +
      • The Troubleshooting section near the bottom covers the error messages you are most likely to encounter
        • +
      +
      + +
      +Low vision users + +
        +
      • Command-line examples are in code blocks with high contrast -- increase zoom to read them comfortably
        • +
      • Each method (PAT vs SSH) is a separate section with its own step-by-step flow
        • +
      • The "Do not" lists use bold text to highlight security warnings
        • +
      +
      + +
      +Sighted users + +
        +
      • Start at "Two Authentication Methods" for a pros/cons comparison, then follow the section for your choice
        • +
      • Code blocks show the exact commands to copy -- use the copy button in the top-right corner on GitHub
        • +
      • The Troubleshooting section at the bottom is organized by error message
        • +
      +
      + + +

      When You Need Authentication

      +

      GitHub requires authentication when you:

      +
        +
      • Push commits to a repository
        • +
      • Clone a private repository
        • +
      • Access organization repositories with specific permissions
        • +
      +

      You do not need authentication to:

      +
        +
      • Clone public repositories
        • +
      • View public repositories on GitHub.com
        • +
      • Read issues and pull requests
        • +
      +

      Two Authentication Methods

      +

      Personal Access Token (PAT)

      +

      A Personal Access Token is a password-like string you generate on GitHub and use instead of your account password when Git asks for credentials.

      +

      Pros

      +
        +
      • Works on all operating systems
        • +
      • Easy to set up for screen reader users (no command line required)
        • +
      • Can be scoped to specific permissions
        • +
      • Easy to revoke if compromised
        • +
      +

      Cons

      +
        +
      • You have to store it securely
        • +
      • Expires after a set time (you must regenerate)
        • +
      +

      SSH Keys

      +

      SSH uses public-key cryptography. You generate a key pair on your computer (public + private), upload the public key to GitHub, and Git uses the private key to prove your identity.

      +

      Pros

      +
        +
      • Once set up, works automatically (no password prompts)
        • +
      • More secure than tokens
        • +
      • Never expires
        • +
      +

      Cons

      +
        +
      • Requires command-line setup (less accessible for some screen reader users)
        • +
      • Slightly more complex initial configuration
        • +
      + +

      Why this method: It's screen reader accessible through the GitHub web interface, and you can complete it without command-line Git configuration.

      +

      Step 1: Generate the Token

      +
        +
      1. Navigate to github.com/settings/tokens
        2. +
      2. Select "Tokens (classic)" from the left sidebar
        3. +
      3. Activate "Generate new token" → Select "Generate new token (classic)"
        4. +
      4. Give it a descriptive name in the Note field: "Workshop Laptop Token"
        5. +
      5. Set expiration: 30 days or 60 days (recommended for temporary workshop use)
        6. +
      6. Select scopes:
          +
        • repo - Full control of private repositories (includes public repo access)
          • +
        • workflow - Update GitHub Actions workflows (if you'll work with Actions)
          • +
        +
        7. +
      7. Scroll down and activate "Generate token"
        8. +
      8. CRITICAL: Copy the token immediately - you cannot see it again
        9. +
      +

      Screen reader note: The token appears as a long string in a text field. Select all (Ctrl+A), copy (Ctrl+C), and paste it into a secure note or password manager.

      +

      Step 2: Store It Securely

      +

      Options

      +
        +
      • Password manager (1Password, Bitwarden, LastPass) - best option
        • +
      • Encrypted note in your operating system's secure notes
        • +
      • Plain text file in an encrypted folder (temporary only)
        • +
      +

      Do not

      +
        +
      • Paste it into a document you sync to cloud storage unencrypted
        • +
      • Email it to yourself
        • +
      • Save it in a public GitHub file
        • +
      +

      Step 3: Use It

      +

      The next time Git asks for your password (when you push, pull from a private repo, or clone a private repo):

      +
      Username: [your-github-username]
+Password: [paste-your-PAT-here]
      +

      Windows Git Credential Manager: Windows will remember this token automatically after your first use. You only paste it once.

      +

      macOS Keychain: macOS will offer to save it to Keychain. Select "Always Allow."

      +

      Linux: You can configure Git to cache credentials:

      +
      git config --global credential.helper cache
      +

      Setting Up SSH Keys (Alternative Method)

      +

      If you prefer SSH and are comfortable with terminal commands:

      +

      Step 1: Check If You Already Have a Key

      +
      ls -al ~/.ssh
      +

      Look for files named id_rsa.pub, id_ed25519.pub, or similar. If you see these, you already have a key.

      +

      Step 2: Generate a New SSH Key

      +
      ssh-keygen -t ed25519 -C "your-email@example.com"
      +

      When prompted:

      +
        +
      • Press Enter to accept the default file location
        • +
      • Enter a passphrase (optional but recommended)
        • +
      +

      Screen reader note: Git will print output showing where the key was saved. It generates two files: id_ed25519 (private) and id_ed25519.pub (public).

      +

      Step 3: Copy Your Public Key

      +

      Windows (PowerShell)

      +
      Get-Content ~/.ssh/id_ed25519.pub | Set-Clipboard
      +

      macOS

      +
      pbcopy < ~/.ssh/id_ed25519.pub
      +

      Linux

      +
      cat ~/.ssh/id_ed25519.pub
+# Manually select and copy the output
      +

      Step 4: Add to GitHub

      +
        +
      1. Navigate to github.com/settings/keys
        2. +
      2. Select "New SSH key"
        3. +
      3. Title: "Workshop Laptop SSH Key"
        4. +
      4. Key type: Authentication Key
        5. +
      5. Key: Paste your public key (should start with ssh-ed25519 or ssh-rsa)
        6. +
      6. Select "Add SSH key"
        7. +
      7. Confirm with your password or 2FA code
        8. +
      +

      Step 5: Test the Connection

      +
      ssh -T git@github.com
      +

      You should see: Hi username! You've successfully authenticated...

      +

      Step 6: Use SSH URLs

      +

      When cloning or adding remotes, use SSH URLs instead of HTTPS:

      +
      # SSH format
+git@github.com:owner/repo.git
+
+# Instead of HTTPS
+https://github.com/owner/repo.git
      +

      Switching Between HTTPS and SSH

      +

      If you cloned with HTTPS but want to use SSH (or vice versa), update the remote:

      +

      Check your current remote

      +
      git remote -v
      +

      Switch to SSH

      +
      git remote set-url origin git@github.com:your-username/repo.git
      +

      Switch to HTTPS

      +
      git remote set-url origin https://github.com/your-username/repo.git
      +

      Learning Cards: Troubleshooting Authentication

      +
      +Screen reader users + +
        +
      • Each troubleshooting entry starts with the error message in quotes as an h3 heading -- press 3 to jump between errors
        • +
      • Solutions include terminal commands in code blocks -- switch to Focus Mode before copying them
        • +
      • If your error is not listed here, search the GitHub Docs authentication troubleshooting page
        • +
      +
      + +
      +Low vision users + +
        +
      • Error messages are displayed as bold h3 headings for easy visual scanning
        • +
      • Solution steps are numbered and include code blocks you can copy directly
        • +
      • If terminal output is hard to read, paste commands into VS Code's integrated terminal which respects your theme settings
        • +
      +
      + +
      +Sighted users + +
        +
      • Scan the h3 headings to find your exact error message
        • +
      • Each solution starts with the most common fix first -- try that before the alternatives
        • +
      • The "Security Best Practices" section below is worth skimming after you resolve your issue
        • +
      +
      + + +

      Troubleshooting

      +

      "Authentication failed" when pushing

      +

      Problem: Your token expired or is incorrect.

      +

      Solution

      +
        +
      • Generate a new PAT
        • +
      • Clear your credential cache (Windows: Credential Manager; macOS: Keychain; Linux: git credential-cache exit)
        • +
      • Try pushing again - Git will ask for credentials
        • +
      +

      "Permission denied (publickey)"

      +

      Problem: SSH key not properly set up.

      +

      Solution

      +
        +
      • Verify your key is added to GitHub: github.com/settings/keys
        • +
      • Check SSH agent is running: ssh-add -l
        • +
      • Add your key to the agent: ssh-add ~/.ssh/id_ed25519
        • +
      +

      "Host key verification failed"

      +

      Problem: SSH doesn't recognize GitHub's host key.

      +

      Solution

      +
      ssh-keyscan github.com >> ~/.ssh/known_hosts
      +

      Security Best Practices

      +
        +
      1. Never share your private key or PAT - treat them like passwords
        2. +
      2. Use scoped PATs - only grant the minimum permissions needed
        3. +
      3. Set expiration dates on PATs - regenerate periodically
        4. +
      4. Use a passphrase on SSH keys - adds another layer of security
        5. +
      5. Revoke old tokens when you're done with a project or device
        6. +
      6. Don't commit tokens or keys to Git - use .gitignore for config files
        7. +
      +

      Commit Signing - Verified Badges and Vigilant Mode

      +

      When you push commits to GitHub, each commit shows a small badge: Verified or Unverified. This badge tells anyone viewing the commit history whether the commit was cryptographically signed - proving it came from you and was not tampered with.

      +

      Why It Matters

      +

      Open source maintainers increasingly require signed commits before merging. Some repositories enforce this with branch protection rules. If you contribute to accessibility-agents and your commits show "Unverified," a maintainer may ask you to sign them before the PR can be merged.

      +

      Two Methods for Signing Commits

      +

      SSH Signing (simpler - reuses your existing SSH key)

      +

      If you already have an SSH key set up for authentication, you can use it for signing too.

      +
      Step 1: Configure Git to use SSH for signing
      +
      git config --global gpg.format ssh
+git config --global user.signingkey ~/.ssh/id_ed25519.pub
+git config --global commit.gpgsign true
      +
      Step 2: Add your SSH key as a signing key on GitHub
      +
        +
      1. Navigate to github.com/settings/ssh
        2. +
      2. Select "New SSH key"
        3. +
      3. Change "Key type" to "Signing Key" (not Authentication Key)
        4. +
      4. Paste your public key and save
        5. +
      +

      Your commits now show the Verified badge in GitHub's commit history.

      +

      GPG Signing (traditional method)

      +
      Step 1: Generate a GPG key
      +
      gpg --full-generate-key
+# Choose: RSA and RSA, 4096 bits, never expires
+# Enter your GitHub email address when prompted
      +

      Step 2: Find your key ID

      +
      gpg --list-secret-keys --keyid-format=long
+# Output includes: sec   rsa4096/XXXXXXXXXXXXXXXX
+# The X's are your key ID
      +

      Step 3: Export the public key

      +
      gpg --armor --export YOUR_KEY_ID
+# Copies the block starting with -----BEGIN PGP PUBLIC KEY BLOCK-----
      +

      Step 4: Add to GitHub

      +
        +
      1. Navigate to github.com/settings/gpg-keys
        2. +
      2. Select "New GPG key" → paste the exported public key
        3. +
      +

      Step 5: Configure Git to sign all commits

      +
      git config --global user.signingkey YOUR_KEY_ID
+git config --global commit.gpgsign true
      +

      Vigilant Mode

      +

      GitHub has an optional setting called Vigilant Mode (in Settings → SSH and GPG Keys → Vigilant mode). When enabled, GitHub marks all commits from your account as "Unverified" unless they are signed - even commits that were previously shown without a badge.

      +

      Why some maintainers enable Vigilant Mode

      +
        +
      • It makes tampered or spoofed commits immediately obvious
        • +
      • It signals that the repository cares about commit provenance
        • +
      +

      What you see as a contributor

      +
        +
      • Every unsigned commit you push will show a yellow "Unverified" badge
        • +
      • This is a visual signal - commits can still be pushed, but maintainers may block the merge
        • +
      +

      To read verification badges with a screen reader

      +
        +
      • Navigate to the repository's commit history (Code tab → Commits link)
        • +
      • Each commit row contains either "Verified" or "Unverified" as a badge element
        • +
      • NVDA/JAWS: the badge is inside the commit row; use ↓ to read through each row and the badge text is read inline
        • +
      • VoiceOver: use VO+Right through the commit row; the badge is read as a button with the text "Verified" (clicking it shows the certificate)
        • +
      +

      Workshop recommendation: SSH signing is simpler to set up than GPG and reuses your existing key. If you have 10 minutes, configure it before Day 2 - every commit you push to accessibility-agents will show as Verified.

      +

      For This Workshop

      + +
        +
      1. Generate a Personal Access Token with 30-day expiration
        2. +
      2. Scope: repo and workflow
        3. +
      3. Store it in your password manager
        4. +
      4. Use it when VS Code or Git asks for a password
        5. +
      +

      SSH keys are great for long-term use, but PATs are faster to set up and more accessible for screen reader users during a time-constrained workshop.

      +
      +

      Next: Appendix E: Advanced Git
      Back: Appendix C: Markdown Reference
      Teaching chapter: Chapter 00: Pre-Workshop Setup

      + +
      + + + + diff --git a/html/admin/qa-bundle/docs/appendix-e-advanced-git.html b/html/admin/qa-bundle/docs/appendix-e-advanced-git.html new file mode 100644 index 00000000..745d3c4f --- /dev/null +++ b/html/admin/qa-bundle/docs/appendix-e-advanced-git.html @@ -0,0 +1,986 @@ + + + + + + + Appendix E: Advanced Git Operations - GIT Going with GitHub + + + + + + + + +
      +

      Appendix E: Advanced Git Operations

      +
      +

      Episode coming soon: Advanced Git Operations - a conversational audio overview of this appendix. Listen before reading to preview the concepts, or after to reinforce what you learned.

      +
      +
      +

      Reference companion to: Chapter 13: How Git Works | Also relevant: Chapter 14

      +

      Authoritative source: Pro Git Book

      +
      +

      Going Deeper with Git

      +
      +

      Who this is for: You have completed Chapter 11 (Git & Source Control) and feel comfortable with the basics — cloning, branching, committing, pushing, and pulling. This appendix covers the next tier of Git skills that come up constantly in real open source contribution: cherry-picking fixes across branches, cleaning up messy commit history before a PR, safely undoing mistakes, and understanding why your push sometimes gets blocked.

      +

      Every section shows three paths: VS Code, GitHub CLI (gh), and Git CLI. Use whichever fits your workflow — they all produce the same result.

      +
      +
      +

      Table of Contents

      +
        +
      1. Cherry-Pick — Grabbing a Specific Commit
        2. +
      2. Interactive Rebase — Cleaning Up Your History
        3. +
      3. git reset — Undoing at Different Depths
        4. +
      4. git revert — The Safe Undo for Shared Branches
        5. +
      5. Tags — Marking Important Moments
        6. +
      6. Detached HEAD — What It Is and How to Get Out
        7. +
      7. Force Pushing Safely
        8. +
      8. git bisect — Finding the Commit That Broke Things
        9. +
      9. git clean — Clearing Out Untracked Files
        10. +
      10. Branch Protection — Why Your Push or Merge May Be Blocked
        11. +
      11. Using GitHub Copilot for Git Operations
        12. +
      +

      Learning Cards: Using This Advanced Git Reference

      +
      +Screen reader users + +
        +
      • Each operation is a numbered h2 section with three sub-paths: VS Code, GitHub CLI, and Git CLI
        • +
      • Use H to jump between operations and 3 to jump between the tool-specific sub-headings within each
        • +
      • The Table of Contents above has anchor links -- activate any link to jump directly to that operation
        • +
      +
      + +
      +Low vision users + +
        +
      • Command examples are in labeled code blocks -- increase zoom and each command fits on one line
        • +
      • Every section follows the same structure: what it is, when to use it, then tool-specific steps
        • +
      • The Quick Reference table near the bottom gives a one-row-per-operation summary for fast lookup
        • +
      +
      + +
      +Sighted users + +
        +
      • Scan the Table of Contents to find the Git operation you need -- sections are ordered from most to least common
        • +
      • Each section has VS Code, CLI, and GitHub CLI paths shown side by side
        • +
      • Jump to the Quick Reference table at the bottom for a compact summary of all commands
        • +
      +
      + +
      +

      1. Cherry-Pick — Grabbing a Specific Commit

      +

      What it is: Cherry-pick lets you take a single commit from any branch and apply it to your current branch. Think of it like copy-pasting a specific change — without bringing the entire branch along with it.

      +

      When you'd use it:

      +
        +
      • You fixed a bug on a feature branch, but main also needs that fix right now
        • +
      • A teammate landed a commit on their branch and you need just that one change
        • +
      • You accidentally committed to the wrong branch and need to move that commit somewhere else
        • +
      +

      Finding the Commit SHA

      +

      Before cherry-picking, you need the commit's SHA (the unique ID for that commit).

      +

      VS Code

      +
        +
      1. Open the Timeline panel: Click View → Open View → Timeline (or press Ctrl+Shift+P and type "Timeline")
        2. +
      2. Switch to the branch that has the commit you want, browse the Timeline, and copy the commit SHA shown in the details panel
        3. +
      +

      Git CLI

      +
      # See commits on another branch without switching to it
+git log feature/bug-fix --oneline
+
+# Output:
+# a1b2c3d Fix null pointer error in auth module
+# e4f5g6h Add unit tests for login
      +

      The short SHA is the first 7 characters (a1b2c3d).

      +

      Applying the Cherry-Pick

      +

      VS Code (Command Palette)

      +
        +
      1. Press Ctrl+Shift+P (or Cmd+Shift+P on macOS)
        2. +
      2. Type "cherry" and select "Git: Cherry Pick..."
        3. +
      3. Paste or type the commit SHA
        4. +
      4. Press Enter — VS Code applies the commit to your current branch
        5. +
      +

      GitHub CLI

      +

      The GitHub CLI doesn't have a direct cherry-pick command (it's a local Git operation), but you can use it to find the SHA first:

      +
      # List commits on a branch via gh to find the one you want
+gh api repos/{owner}/{repo}/commits?sha=feature/bug-fix --jq '.[].sha, .[].commit.message' | head -20
+
+# Then cherry-pick using git
+git cherry-pick a1b2c3d
      +

      Git CLI

      +
      # Apply a single commit
+git cherry-pick a1b2c3d
+
+# Apply a range of commits (from older to newer, exclusive of first)
+git cherry-pick a1b2c3d..e4f5g6h
+
+# Apply without automatically committing (lets you review changes first)
+git cherry-pick --no-commit a1b2c3d
      +

      If There's a Conflict

      +

      Cherry-pick can hit conflicts just like a merge. When it does:

      +
        +
      1. Git pauses and marks the conflicting files (same <<<<<<< HEAD markers as merge conflicts)
        2. +
      2. Resolve the conflicts in VS Code's conflict editor (see Chapter 7: Merge Conflicts)
        3. +
      3. Stage the resolved files
        4. +
      4. Then either:
        5. +
      +
      # Continue the cherry-pick after resolving
+git cherry-pick --continue
+
+# Or cancel it entirely and go back to where you started
+git cherry-pick --abort
      +
      +

      Screen reader tip: When a cherry-pick stops due to a conflict, run git status in the terminal — it announces exactly which files need attention. The conflict markers are plain text and read naturally line by line.

      +
      +
      +

      GitHub Copilot can help: Before cherry-picking a commit you're not sure about, open Copilot Chat (Ctrl+Shift+I) and ask: "What does commit a1b2c3d do? Should I cherry-pick it onto my branch?" Paste the git show a1b2c3d output into the chat for context. After cherry-picking, if a conflict opens, Copilot can suggest a resolution — see Section 11 for prompts.

      +
      +
      +

      2. Interactive Rebase — Cleaning Up Your History

      +

      What it is: Interactive rebase (git rebase -i) is like a time machine for your commits. Before you open a PR, you can reorder commits, combine several small commits into one clean commit, rewrite commit messages, or remove commits that were just experiments.

      +

      When you'd use it:

      +
        +
      • You made 8 "WIP" commits while working and want to combine them into 1 clean commit for your PR
        • +
      • You want to reword a commit message to better describe what changed
        • +
      • You accidentally committed a debug file and want to remove that commit entirely
        • +
      +
      +

      Golden rule: Only rebase commits that have not been pushed to a shared branch yet. Rewriting public history creates problems for everyone who has pulled that branch. If you've already pushed, see Force Pushing Safely.

      +
      +

      Starting an Interactive Rebase

      +

      VS Code

      +

      VS Code has basic rebase support via the Command Palette, but for full interactive rebase you'll want the terminal:

      +
        +
      1. Open the Integrated Terminal: Ctrl+Backtick
        2. +
      2. Run the command below to rebase the last N commits (replace N with how many commits you want to edit)
        3. +
      +
      git rebase -i HEAD~3
+# This opens your last 3 commits for editing
      +
        +
      1. Your default editor opens with a list of your commits. If it opens in vim, type i to enter insert mode, make your edits, then press Esc followed by :wq to save. If you'd prefer VS Code as the editor:
        2. +
      +
      git config --global core.editor "code --wait"
      +

      After that, git rebase -i will open the commit list in VS Code itself — much more screen-reader-friendly.

      +

      Git CLI (Terminal)

      +
      # Rebase the last 3 commits
+git rebase -i HEAD~3
+
+# Or rebase everything since you branched from main
+git rebase -i main
      +

      The Commit List — What You're Looking At

      +

      When the editor opens, you see something like this:

      +
      pick a1b2c3d Add accessibility section to README
+pick e4f5g6h Fix typo in intro
+pick f7g8h9i Fix another typo in intro
      +

      Each line starts with a command word. Change the word to change what happens to that commit:

      + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + +
      CommandWhat it does
      pickKeep the commit as-is (default)
      squash (or s)Combine this commit into the one above it
      fixup (or f)Same as squash but discard this commit's message
      reword (or r)Keep the commit but edit the message
      drop (or d)Delete this commit entirely
      edit (or e)Pause here so you can amend the commit
      +

      Example: Squashing 3 Commits Into 1

      +

      Change the file to:

      +
      pick a1b2c3d Add accessibility section to README
+squash e4f5g6h Fix typo in intro
+squash f7g8h9i Fix another typo in intro
      +

      Save and close. Git opens a second editor for you to write the combined commit message. Write a clean summary and save — done. You now have one tidy commit instead of three.

      +

      Example: Rewriting a Commit Message

      +
      reword a1b2c3d Add accessibility section to README
+pick e4f5g6h Fix typo in intro
      +

      Save and close. Git opens the commit message for a1b2c3d for you to edit. Write the new message, save — done.

      +

      If Something Goes Wrong

      +
      # Abort the rebase and go back to where you started
+git rebase --abort
+
+# If you're mid-rebase and hit a conflict, resolve it then continue
+git rebase --continue
      +
      +

      Screen reader tip: Run git rebase -i with VS Code as your editor (git config --global core.editor "code --wait") — the commit list opens in a VS Code tab that your screen reader can navigate normally with arrow keys.

      +
      +
      +

      GitHub Copilot can help: Not sure how to word a squashed commit message? After combining your commits, open Copilot Chat and say: "I just squashed these commits into one: [paste your old messages]. Write a clear, concise commit message that describes all the changes." Copilot is also great at explaining what an interactive rebase file is asking you to do — paste the whole thing and ask: "What will happen when I save this rebase file?"

      +
      +
      +

      3. git reset — Undoing at Different Depths

      +

      What it is: git reset moves the tip of your current branch backward to a previous commit. The three modes (--soft, --mixed, --hard) control what happens to the changes that were in those commits.

      +

      When you'd use it:

      +
        +
      • You committed too early and want to add more changes to that commit
        • +
      • You staged the wrong files and want to unstage them
        • +
      • You want to completely throw away the last few commits and start fresh
        • +
      +

      The Three Modes

      +

      Think of Git as having three layers: your working files (what you can see in the editor), the staging area (what git add puts there), and the commit history.

      + + + + + + + + + + + + + + + + + + + + + + + + + + + +
      ModeWhat gets resetYour working filesYour staged changes
      --softCommit history onlyKeptKept (still staged)
      --mixed (default)History + stagingKeptUnstaged (back to working files)
      --hardEverythingDiscardedDiscarded
      +
      +

      --hard is the dangerous one. It permanently discards your uncommitted changes. If you're not sure, use --soft or --mixed - they never lose work. And if you do accidentally use --hard, check git reflog immediately (see Chapter 14, Section 10b).

      +
      +

      VS Code — Undoing the Last Commit

      +

      Using the Source Control panel

      +
        +
      1. Open Source Control: Ctrl+Shift+G
        2. +
      2. Click the "..." (More Actions) menu at the top of the panel
        3. +
      3. Select "Commit → Undo Last Commit"
        4. +
      +

      This is equivalent to git reset --soft HEAD~1 — your changes come back as staged files, nothing is lost.

      +

      Using the Command Palette

      +
      Ctrl+Shift+P → type "git undo" → select "Git: Undo Last Commit"
      +

      Git CLI

      +
      # Undo last commit — keep changes staged (safest)
+git reset --soft HEAD~1
+
+# Undo last commit — keep changes but unstage them
+git reset --mixed HEAD~1
+
+# Undo last 3 commits — keep all changes unstaged
+git reset --mixed HEAD~3
+
+# Undo last commit — DISCARD all changes (cannot be undone without reflog)
+git reset --hard HEAD~1
+
+# Reset to a specific commit SHA
+git reset --soft a1b2c3d
      +

      Unstaging a File (Without Undoing the Commit)

      +

      If you just want to remove a file from the staging area without touching commit history:

      +

      VS Code

      +

      In the Source Control panel, click the minus (–) icon next to a staged file, or right-click it and select "Unstage Changes".

      +

      Git CLI

      +
      # Unstage a specific file
+git restore --staged docs/README.md
+
+# Unstage everything
+git restore --staged .
      +
      +

      4. git revert — The Safe Undo for Shared Branches

      +

      What it is: git revert creates a new commit that undoes the changes from a previous commit. Unlike git reset, it does not rewrite history — it adds to it. This makes it the right choice when you need to undo something on a shared branch (like main) where other people may already have the history you'd be rewriting.

      +

      When you'd use it:

      +
        +
      • A commit made it to main and it broke something — you need to roll it back without force-pushing
        • +
      • You want to undo a change but keep a record that the undo happened
        • +
      • You're working on a protected branch where force-push is disabled
        • +
      +

      VS Code

      +
        +
      1. Open the Timeline panel and navigate to the commit you want to undo
        2. +
      2. Right-click the commit and select "Revert Commit"
        3. +
      3. VS Code creates a new commit with message Revert "your original message" — review it and push
        4. +
      +

      Git CLI

      +
      # Revert a specific commit (opens editor to confirm the message)
+git revert a1b2c3d
+
+# Revert without opening the editor (uses default message)
+git revert --no-edit a1b2c3d
+
+# Stage the revert but don't commit yet (lets you edit the message manually)
+git revert --no-commit a1b2c3d
+git commit -m "Revert: remove broken auth change, will revisit in #42"
+
+# Revert a merge commit (you must specify which parent to revert to)
+git revert -m 1 a1b2c3d
      +

      When to Use revert vs reset

      + + + + + + + + + + + + + + + + + + + + + + + +
      SituationUse
      Commit is only local (not pushed)git reset — cleaner, no extra commit
      Commit is on a shared branch (main, dev)git revert — preserves history, safe for others
      Branch has protection rules (no force push)git revert — the only option
      You want a clear audit trail of the undogit revert — the revert commit appears in history
      +
      +

      GitHub Copilot can help: Not sure whether to use reset or revert? Describe your situation to Copilot Chat: "I pushed a commit to main that broke the login page. Should I use git reset or git revert to undo it?" Copilot will explain the tradeoffs and give you the exact command to run.

      +
      +
      +

      5. Tags — Marking Important Moments

      +

      What it is: A tag is a permanent label you attach to a specific commit — usually to mark a release version like v1.0.0. Unlike a branch (which moves as you commit), a tag always points to the exact same commit forever.

      +

      When you'd use it:

      +
        +
      • Releasing a new version of a project
        • +
      • Marking a stable checkpoint before starting a big refactor
        • +
      • Documenting when a major feature shipped
        • +
      +
      +

      GitHub's Releases feature builds on tags. When you create a release on GitHub, you're creating a tag plus release notes and attached files. See Appendix H: Releases, Tags, and Insights for the GitHub web interface side of this.

      +
      +

      Types of Tags

      + + + + + + + + + + + + + + + +
      TypeWhat it is
      LightweightJust a pointer to a commit — like a bookmark
      AnnotatedIncludes a message, author, and date — recommended for releases
      +

      Creating a Tag

      +

      VS Code (Command Palette)

      +
      Ctrl+Shift+P → type "git tag" → select "Git: Create Tag"
      +

      Type the tag name (e.g., v1.2.0) and optionally a message. VS Code creates an annotated tag.

      +

      GitHub CLI

      +
      # Create a tag and push it to GitHub in one step (using the API)
+gh release create v1.2.0 --title "Version 1.2.0" --notes "Bug fixes and accessibility improvements"
+# This creates both a GitHub Release and the underlying tag
      +

      Git CLI

      +
      # Create a lightweight tag at the current commit
+git tag v1.2.0
+
+# Create an annotated tag (recommended for releases)
+git tag -a v1.2.0 -m "Release version 1.2.0 - bug fixes and accessibility improvements"
+
+# Tag a specific past commit
+git tag -a v1.1.5 a1b2c3d -m "Retroactive tag for 1.1.5"
+
+# List all tags
+git tag
+
+# List tags matching a pattern
+git tag -l "v1.*"
+
+# Show details of an annotated tag
+git show v1.2.0
      +

      Pushing Tags to GitHub

      +

      Tags are not pushed automatically when you run git push. You need to push them explicitly:

      +
      # Push a specific tag
+git push origin v1.2.0
+
+# Push all local tags at once
+git push origin --tags
      +

      Deleting a Tag

      +
      # Delete a local tag
+git tag -d v1.2.0
+
+# Delete the tag on GitHub (remote)
+git push origin --delete v1.2.0
      +
      +

      6. Detached HEAD — What It Is and How to Get Out

      +

      What it is: Normally, you're working on a branch — Git tracks your commits and moves the branch forward as you commit. A "detached HEAD" happens when you check out a specific commit SHA (or a tag) directly instead of a branch. You're no longer on any branch — you're floating at a specific point in history.

      +

      How you get into it:

      +
      git checkout a1b2c3d        # Check out a specific commit
+git checkout v1.0.0         # Check out a tag
      +

      Git warns you when this happens:

      +
      Note: switching to 'a1b2c3d'.
+
+You are in 'detached HEAD' state. You can look around, make experimental
+changes and commit them, but any commits you make in this state will not be
+associated with any branch...
      +

      Why it matters: Any commits you make in detached HEAD state are not attached to a branch. When you switch away, those commits become hard to find (and Git may eventually garbage-collect them).

      +

      Getting Out of Detached HEAD

      +

      If you just want to go back to your branch

      +
      git checkout main
+# or whatever branch you were on
+git switch main
      +

      If you made commits in detached HEAD and want to keep them

      +
      # Create a new branch at the current (detached) position to save your work
+git checkout -b my-experiment
+# Now you're on a real branch and those commits are safe
      +

      VS Code

      +

      VS Code shows the current branch name in the bottom-left status bar. If you're in detached HEAD, it shows something like (HEAD detached at a1b2c3d) instead of a branch name.

      +

      To return to a branch: Click that status bar area, or use Ctrl+Shift+P → "Git: Checkout to..." and pick a branch from the list.

      +
      +

      Screen reader tip: In VS Code, the branch indicator is in the status bar at the bottom of the window. NVDA/JAWS users: press Insert+End to read the status bar, or navigate there with Tab. VoiceOver users: VO+End. If it says "detached", check out a branch before committing anything new.

      +
      +
      +

      7. Force Pushing Safely

      +

      What it is: After you rebase or amend commits that have already been pushed, the remote branch has a different history than your local branch. A regular git push will fail because Git sees them as diverged. A force push overwrites the remote with your local version.

      +
      +

      Force pushing to main or a shared branch is almost always the wrong move. It rewrites history that other people may have pulled, causing them significant pain. Force pushing is appropriate mainly on your own feature branches — and even then, use the safer variant.

      +
      +

      --force-with-lease vs --force

      + + + + + + + + + + + + + + + +
      OptionWhat it does
      --forceOverwrites the remote unconditionally — even if someone else pushed since you last pulled
      --force-with-leaseOverwrites the remote only if no one else has pushed since your last fetch — safer
      +

      Always use --force-with-lease instead of --force.

      +

      When You'd Use It

      +
        +
      • You rebased a feature branch to squash commits before a PR review
        • +
      • You amended the last commit with git commit --amend after already pushing
        • +
      • A reviewer asked you to rebase onto main and you've now done so
        • +
      +

      VS Code

      +

      VS Code doesn't have a "force push" button in the UI — this is intentional to prevent accidents. Use the integrated terminal:

      +
      Ctrl+Backtick → then type the command below
      +

      GitHub CLI

      +
      # Force push your current branch
+gh repo sync   # This is for syncing FROM remote, not for force pushing
+
+# For force pushing, use git directly:
+git push --force-with-lease origin your-branch-name
      +

      Git CLI

      +
      # Safe force push — fails if someone else pushed since your last fetch
+git push --force-with-lease origin feature/my-branch
+
+# Check what will happen before pushing
+git push --force-with-lease --dry-run origin feature/my-branch
+
+# Unconditional force push (avoid unless you know exactly what you're doing)
+git push --force origin feature/my-branch
      +

      The Typical Rebase + Force Push Workflow

      +
      # 1. You're on your feature branch — rebase onto main to get latest changes
+git fetch origin
+git rebase origin/main
+
+# 2. Resolve any conflicts, then continue
+git rebase --continue
+
+# 3. Force push your rebased branch (origin already has the old version)
+git push --force-with-lease origin feature/my-branch
      +
      +

      8. git bisect — Finding the Commit That Broke Things

      +

      What it is: git bisect performs a binary search through your commit history to find exactly which commit introduced a bug. Instead of checking 100 commits one by one, Git cuts the search in half each time — usually finding the culprit in 7-10 steps.

      +

      When you'd use it:

      +
        +
      • "This was working last week, now it's broken — what changed?"
        • +
      • You need to find the exact commit so you can revert or fix it
        • +
      • A test that used to pass now fails and you don't know why
        • +
      +

      Starting a Bisect Session

      +
      # 1. Start bisect mode
+git bisect start
+
+# 2. Mark the current commit as bad (broken)
+git bisect bad
+
+# 3. Mark a commit you know was good (working)
+# Use a tag, SHA, or branch name from before the problem started
+git bisect good v1.0.0
+# or
+git bisect good a1b2c3d
      +

      Git now checks out a commit in the middle of your history. Test your code — does the bug exist here?

      +
      # If the bug IS present at this commit
+git bisect bad
+
+# If the bug is NOT present at this commit
+git bisect good
      +

      Git cuts the range in half again and checks out another commit. Repeat until Git prints:

      +
      a1b2c3d is the first bad commit
      +

      Finishing

      +
      # End the bisect session and return to your original branch
+git bisect reset
      +

      Automating Bisect with a Test Script

      +

      If you have a test command that exits with code 0 on success and non-zero on failure, Git can run bisect automatically:

      +
      git bisect start
+git bisect bad HEAD
+git bisect good v1.0.0
+
+# Run automatically — git runs your test script at each step
+git bisect run npm test
+# or
+git bisect run python -m pytest tests/test_auth.py
      +
      +

      Screen reader tip: Bisect output is plain text — each step tells you exactly where it checked out and how many steps remain. The terminal reads it cleanly line by line.

      +
      +
      +

      9. git clean — Clearing Out Untracked Files

      +

      What it is: git clean removes untracked files and directories from your working directory — files that Git doesn't know about yet (not staged, not committed, not in .gitignore). This is useful when you have build artifacts, generated files, or experimental files cluttering your project.

      +
      +

      git clean cannot be undone. The files it removes are permanently deleted — they're not moved to the trash or recoverable from git reflog. Always run with --dry-run first.

      +
      +

      When you'd use it:

      +
        +
      • After a build that left temporary files everywhere
        • +
      • You want a completely fresh state matching the last commit
        • +
      • Clearing out generated files before running a clean build
        • +
      +

      Always Dry-Run First

      +
      # See what WOULD be deleted without actually deleting anything
+git clean -n
+# or equivalently
+git clean --dry-run
      +

      VS Code

      +

      VS Code's Source Control panel shows untracked files in the "Changes" section. To remove them:

      +
        +
      1. Open Source Control: Ctrl+Shift+G
        2. +
      2. Right-click an untracked file
        3. +
      3. Select "Discard Changes" — this removes new untracked files
        4. +
      +

      For bulk removal, use the terminal (see Git CLI below).

      +

      Git CLI

      +
      # Dry run — see what would be removed
+git clean -n
+
+# Remove untracked files (NOT directories)
+git clean -f
+
+# Remove untracked files AND directories
+git clean -fd
+
+# Remove untracked files AND ignored files (be careful — removes build artifacts AND things in .gitignore)
+git clean -fx
+
+# Interactive mode — confirm each file before deleting
+git clean -i
      +

      What -n, -f, -d, -x Mean

      + + + + + + + + + + + + + + + + + + + + + + + + + + + +
      FlagMeaning
      -nDry run — show what would be removed
      -fForce — required to actually delete (safety measure)
      -dAlso remove untracked directories
      -xAlso remove files listed in .gitignore
      -iInteractive — confirm each deletion
      +
      +

      10. Branch Protection — Why Your Push or Merge May Be Blocked

      +

      What it is: Branch protection rules are settings a repository administrator applies to specific branches (usually main or release branches). They prevent direct pushes, require pull requests, require approvals before merging, and enforce status checks passing.

      +

      You don't configure these as a contributor — but you will encounter them, and understanding them helps you avoid frustration when your push or merge gets blocked.

      +

      Common Things That Block You (and Why)

      + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + +
      What happenedWhy it happenedWhat to do
      git push origin main fails with "remote: error: GH006"Direct push to main is blockedCreate a branch and open a PR instead
      Your PR has a "Merge" button but it's grayed outRequired approvals not met, or status checks failingRequest a review; wait for CI to pass
      PR says "Required review from code owners"A CODEOWNERS file routes reviews to specific peopleWait for or ping the code owner
      CI check is failingAn automated test or lint step failedFix the failing check and push again
      PR says "Branch is out of date"main moved forward after your PR openedUpdate your branch (merge or rebase from main)
      +

      The Correct Flow for Protected Branches

      +
      # 1. Never push directly to main — always work on a branch
+git checkout -b feature/my-change
+
+# 2. Make your changes, commit them
+git add .
+git commit -m "Add screen reader support to navigation"
+
+# 3. Push your branch (not main)
+git push origin feature/my-change
+
+# 4. Open a PR on GitHub — protection rules apply to the merge, not the push
+gh pr create --title "Add screen reader support to navigation" --body "Closes #42"
+
+# 5. Wait for reviews and CI checks to pass, then merge through the PR
      +

      Updating a Branch That's Out of Date

      +

      When GitHub says your branch is out of date with main:

      +

      VS Code

      +
        +
      1. Open Source Control → Ctrl+Shift+P
        2. +
      2. Type "merge" → select "Git: Merge Branch..."
        3. +
      3. Choose origin/main from the list
        4. +
      4. Resolve any conflicts, then push again
        5. +
      +

      Git CLI

      +
      # Option A: Merge main into your branch (creates a merge commit)
+git fetch origin
+git merge origin/main
+
+# Option B: Rebase onto main (cleaner history, requires force push after)
+git fetch origin
+git rebase origin/main
+git push --force-with-lease origin feature/my-change
      +

      GitHub CLI

      +
      # Update your PR branch from the GitHub UI via CLI
+gh pr update-branch --rebase
+# or
+gh pr update-branch  # uses merge by default
      +

      Checking What Protection Rules Are Active

      +

      GitHub CLI

      +
      # View branch protection rules for main
+gh api repos/{owner}/{repo}/branches/main/protection --jq '{
+  required_reviews: .required_pull_request_reviews.required_approving_review_count,
+  require_status_checks: .required_status_checks.contexts,
+  enforce_admins: .enforce_admins.enabled
+}'
      +

      On GitHub.com

      +

      Navigate to Settings → Branches in the repository. (You need admin access to see the full config; contributors can see the effect through blocked PRs and the merge box status.)

      +
      +

      For a deep dive on branch protection rules, rulesets, and diagnosing why your PR can't merge: See Appendix K: Branch Protection and Rulesets — it includes a full diagnosis guide, screen reader navigation of the merge box, and what each status check means.

      +
      +

      Learning Cards: Quick Reference Table

      +
      +Screen reader users + +
        +
      • This table has four columns: Task, VS Code, Git CLI, and GitHub CLI -- column headers are announced on entry
        • +
      • Use Ctrl+Alt+Arrow keys to navigate cells; the Task column on the left identifies each row
        • +
      • Cells with a dash (--) mean that tool does not support the operation -- move right to try another column
        • +
      +
      + +
      +Low vision users + +
        +
      • At high zoom the table may scroll horizontally -- use Shift+scroll or arrow keys to see all four columns
        • +
      • The Task column is always the leftmost -- anchor your reading from there
        • +
      • Consider copying this table into a text file or spreadsheet for easier viewing at your preferred zoom
        • +
      +
      + +
      +Sighted users + +
        +
      • This is a single-page summary of every advanced operation -- scan the Task column for what you need
        • +
      • The Git CLI column is always populated; VS Code and GitHub CLI columns show alternatives where available
        • +
      • Bookmark this table as your daily reference for less-common Git commands
        • +
      +
      + +
      +

      Quick Reference — Advanced Git Commands

      + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + +
      TaskVS CodeGit CLIGitHub CLI
      Cherry-pick a commitCtrl+Shift+P → "Cherry Pick"git cherry-pick <sha>Find SHA via gh, then git cherry-pick
      Squash commitsTerminal: git rebase -i HEAD~Ngit rebase -i HEAD~N—
      Undo last commit (keep changes)Source Control → "..." → "Undo Last Commit"git reset --soft HEAD~1—
      Safely undo a pushed commitTimeline → right-click → "Revert Commit"git revert <sha>—
      Create a release tagCtrl+Shift+P → "Create Tag"git tag -a v1.0.0 -m "..."gh release create v1.0.0
      Push tags to GitHub—git push origin --tags(included in gh release create)
      Exit detached HEADStatus bar → pick a branchgit switch main—
      Force push safelyTerminal (no UI button)git push --force-with-lease origin <branch>—
      Find bug-introducing commitTerminal: git bisect startgit bisect start/good/bad—
      Remove untracked filesSource Control → Discardgit clean -fd (dry run: -n)—
      Update PR branchSource Control → Merge Branchgit fetch && git rebase origin/maingh pr update-branch
      +
      +

      11. Using GitHub Copilot for Git Operations

      +

      GitHub Copilot isn't just for writing code — it's genuinely useful for Git operations, especially when you're doing something unfamiliar, hit a conflict, or need to understand what a command did. Here's how to use it across the advanced operations in this appendix.

      +
      +

      Opening Copilot Chat in VS Code: Press Ctrl+Shift+I (Windows/Linux) or Cmd+Option+I (macOS), or click the Copilot Chat icon in the sidebar. Screen reader users: the chat input is a text field — type your prompt and press Enter.

      +
      +

      Resolving Merge Conflicts

      +

      When a cherry-pick, rebase, or branch merge stops due to a conflict, VS Code highlights the conflict regions. Place your cursor inside a conflict block and ask Copilot:

      +
        +
      • "Resolve this merge conflict. Keep meaningful changes from both sides."
        • +
      • "Explain what each side of this conflict is trying to do."
        • +
      • "Which version of this change should I keep, and why?"
        • +
      +

      Copilot reads the conflict markers and suggests a resolution. You review it, accept or adjust, then stage the file and continue.

      +
      +

      Tip: If you have multiple conflict files, handle them one at a time — paste the conflicting block into Copilot Chat with context about what the file does. You'll get much better suggestions than if you just say "fix this."

      +
      +

      Writing Better Commit Messages

      +

      Copilot is excellent at turning "WIP: stuff" into a clear, conventional commit message.

      +

      Open Copilot Chat after staging your changes and try:

      +
        +
      • "Write a conventional commit message for these changes." (Copilot can see open files)
        • +
      • "I changed the navigation component to add keyboard focus indicators. Write a commit message."
        • +
      • "Here are my last 5 WIP commit messages: [paste them]. Write one clean message that summarizes all of them."
        • +
      +

      Conventional commit format (feat:, fix:, docs:, refactor:) is especially useful on open source projects — ask Copilot to use it.

      +

      Understanding Confusing Git Output

      +

      Git's error messages and status output can be cryptic. Paste them directly into Copilot Chat:

      +
      # Paste this kind of thing into Copilot and ask "what does this mean?"
+error: Your local changes to the following files would be overwritten by merge:
+    src/auth/login.js
+Please commit your changes or stash them before you merge.
      +
        +
      • "I got this git error message: [paste it]. What does it mean and how do I fix it?"
        • +
      • "My git status output looks like this: [paste it]. What happened and what should I do next?"
        • +
      • "I accidentally ran git reset --hard. What are my options for recovering my changes?"
        • +
      +

      Choosing the Right Command

      +

      When you're not sure which git command to reach for, describe what you want to do:

      +
        +
      • "I committed a fix on my feature branch but main also needs it urgently. What's the right git command to use?" → Copilot will suggest cherry-pick
        • +
      • "I have 6 messy commits on my PR branch before I open the PR. How do I clean them up?" → Interactive rebase with squash
        • +
      • "I pushed a commit that broke CI and I need to undo it without force-pushing." → git revert
        • +
      • "My PR branch hasn't been updated from main in two weeks. How do I bring it up to date?" → fetch + rebase or merge
        • +
      +

      Debugging a Failing Bisect

      +

      When git bisect lands on a commit and you're not sure what to test:

      +
        +
      • "I'm running git bisect to find a bug. Git just checked out commit a1b2c3d. Here's the diff: [paste git show a1b2c3d]. What changed in this commit and what should I test?"
        • +
      +

      Getting Help With Branch Protection Errors

      +

      Paste the full error message from a rejected push into Copilot:

      +
      remote: error: GH006: Protected branch update failed for refs/heads/main.
+remote: error: Required status check "CI / build" is failing.
      +
        +
      • "I got this error when pushing to my repository: [paste error]. What does it mean and what do I do?"
        • +
      • "My PR can't merge because of a required status check. Here's the check output: [paste it]. What's wrong?"
        • +
      +

      Copilot in the Terminal vs. Copilot Chat

      + + + + + + + + + + + + + + + + + + + + + + + + + + + +
      Use caseBest tool
      Explaining a git error or status messageCopilot Chat (paste the output)
      Writing a commit messageCopilot Chat
      Resolving a merge conflictCopilot Chat (with cursor in conflict block)
      Generating the right git commandCopilot Chat or GitHub Copilot CLI (gh copilot suggest)
      Autocompleting a long command you've startedCopilot inline (in terminal with shell integration)
      +

      GitHub Copilot CLI — Git Command Suggestions

      +

      If you have the GitHub CLI with Copilot extension installed, you can ask for git commands directly in the terminal:

      +
      # Ask Copilot to suggest a git command for what you want to do
+gh copilot suggest "squash my last 4 commits into one"
+gh copilot suggest "undo my last commit but keep the changes"
+gh copilot suggest "find which commit broke the login tests"
      +

      Copilot CLI explains the command before running it and asks for confirmation — great for learning while doing.

      +
      +

      See also: Chapter 16: GitHub Copilot for the full guide to Copilot Chat, inline suggestions, and effective prompting. Appendix K: Copilot Reference for the complete command and participant reference.

      +
      +
      +

      Next: Appendix F: Git Security
      Back: Appendix D: Git Authentication
      Teaching chapter: Chapter 13: How Git Works

      + +
      + + + + diff --git a/html/admin/qa-bundle/docs/appendix-f-git-security.html b/html/admin/qa-bundle/docs/appendix-f-git-security.html new file mode 100644 index 00000000..05a4cb56 --- /dev/null +++ b/html/admin/qa-bundle/docs/appendix-f-git-security.html @@ -0,0 +1,557 @@ + + + + + + + Appendix F: Git Security for Contributors - GIT Going with GitHub + + + + + + + + +
      +

      Appendix F: Git Security for Contributors

      +
      +

      Episode coming soon: Git Security for Contributors - a conversational audio overview of this appendix. Listen before reading to preview the concepts, or after to reinforce what you learned.

      +
      +
      +

      Reference companion to: Chapter 08: Open Source Culture | Also relevant: Chapter 14

      +

      Authoritative source: GitHub Docs: Code security

      +
      +

      Keeping Secrets Out of Your Repository

      +
      +

      Who this is for: Anyone committing code or documentation to a repository. You don't need to be a security expert — this appendix covers the practical habits that protect you and the projects you contribute to. Most security incidents in open source aren't caused by attacks; they're caused by accidents. A token committed by mistake, a password left in a config file, a .env file that slipped through.

      +

      The good news: a few simple habits prevent almost all of them.

      +
      +
      +

      Table of Contents

      +
        +
      1. Why This Matters — What Happens When Secrets Leak
        2. +
      2. The .gitignore File — Your First Line of Defense
        3. +
      3. Environment Variables — The Right Way to Store Secrets
        4. +
      4. Review Before You Commit
        5. +
      5. Pre-Commit Hooks — Automated Secret Detection
        6. +
      6. I Accidentally Committed a Secret — What Now?
        7. +
      7. GitHub's Built-In Push Protection
        8. +
      8. Secure Credential Storage
        9. +
      9. Security Checklist for Contributors
        10. +
      +

      Learning Cards: Using This Security Reference

      +
      +Screen reader users + +
        +
      • Sections are ordered from understanding (section 1) to prevention (2-5) to recovery (6-7) to daily habits (8-9)
        • +
      • Code blocks contain exact gitignore patterns and terminal commands -- switch to Focus Mode before copying
        • +
      • The Security Checklist (section 9) is a task list you can use before every push
        • +
      +
      + +
      +Low vision users + +
        +
      • Code examples for .gitignore patterns and terminal commands are in high-contrast code blocks
        • +
      • Warning callouts use bold text -- scan for bold to find the most critical safety notes
        • +
      • The Security Checklist at the bottom uses checkbox formatting for easy visual tracking
        • +
      +
      + +
      +Sighted users + +
        +
      • Read section 1 for motivation, then jump to the section matching your current need
        • +
      • The .gitignore templates in section 2 are copy-paste ready for most project types
        • +
      • Skip to the Security Checklist (section 9) for a pre-push routine you can follow every time
        • +
      +
      + +
      +

      1. Why This Matters — What Happens When Secrets Leak

      +

      When a secret (API key, token, password, private key) is committed to a public GitHub repository — even for a few seconds before you delete it — it's effectively compromised.

      +

      Why "I'll just delete it right away" isn't enough:

      +
        +
      • Bots scan GitHub continuously and harvest secrets within seconds of a push
        • +
      • The secret lives in your git history even after you delete the file
        • +
      • GitHub forks capture history — once forked, you can't fully erase it
        • +
      • Search engines may index the content before you remove it
        • +
      +

      Real-world consequences:

      +
        +
      • An AWS key leaked to a public repo can result in thousands of dollars of compute charges within hours
        • +
      • A GitHub PAT can be used to access private repositories, delete code, or impersonate you
        • +
      • A Stripe API key can be used to make fraudulent charges against your account
        • +
      +

      The good news: GitHub automatically revokes its own tokens (PATs, GitHub App tokens) when it detects them in a commit. But third-party services (AWS, Stripe, Twilio, etc.) require you to rotate the secret manually — and fast.

      +
      +

      2. The .gitignore File — Your First Line of Defense

      +

      A .gitignore file tells Git which files to never track. Files listed in .gitignore won't show up in git status, won't be staged by git add, and won't be committed.

      +

      What belongs in .gitignore

      +

      Secrets and credentials

      +
      # Environment files (contain API keys, database passwords, etc.)
+.env
+.env.local
+.env.*.local
+.env.development
+.env.production
+*.env
+
+# Key files
+*.pem
+*.key
+*.p12
+*.pfx
+id_rsa
+id_ed25519
+
+# Credential files
+credentials.json
+secrets.json
+config/secrets.yml
+.aws/credentials
      +

      Editor and OS clutter

      +
      # macOS
+.DS_Store
+.AppleDouble
+
+# Windows
+Thumbs.db
+desktop.ini
+
+# VS Code (optional — some teams commit these)
+.vscode/settings.json
+
+# JetBrains IDEs
+.idea/
      +

      Build output and dependencies

      +
      # Node
+node_modules/
+dist/
+build/
+
+# Python
+__pycache__/
+*.pyc
+.venv/
+venv/
+
+# General
+*.log
+*.tmp
+*.cache
      +

      Checking if a file is already tracked

      +

      .gitignore only prevents untracked files from being added. If Git is already tracking a file, .gitignore won't stop it from being committed in the future.

      +
      # Check if a specific file is tracked
+git ls-files .env
+
+# If it returns the filename, it's being tracked — you need to untrack it
+git rm --cached .env
+# Then add it to .gitignore and commit
      +

      Global .gitignore — apply to every repo on your machine

      +

      You can create a global .gitignore that applies to all repositories on your computer — useful for OS-specific and editor-specific files you never want to commit anywhere.

      +
      # Create a global gitignore file
+touch ~/.gitignore_global
+
+# Tell Git to use it
+git config --global core.excludesfile ~/.gitignore_global
      +

      Add your editor and OS files to ~/.gitignore_global so you never have to add them to individual repos.

      +

      GitHub's .gitignore templates

      +

      When creating a new repository on GitHub, you can choose a .gitignore template for your language — GitHub pre-fills it with the most common patterns for that ecosystem. Find all templates at github.com/github/gitignore.

      +

      For an existing project:

      +
      # Download a template (e.g., for Node.js)
+curl https://raw.githubusercontent.com/github/gitignore/main/Node.gitignore >> .gitignore
      +
      +

      3. Environment Variables — The Right Way to Store Secrets

      +

      Instead of hardcoding secrets in your files, store them in environment variables that live outside of your repository.

      +

      The pattern

      +
      # Never do this (hardcoded secret in code)
+API_KEY = "sk-abc123yoursecretkeyhere"
+
+# Do this instead (read from environment)
+API_KEY = os.environ.get("API_KEY")      # Python
+const apiKey = process.env.API_KEY;      // JavaScript
      +

      Using a .env file locally

      +

      A .env file stores your local environment variables. It's convenient and universally supported — and it must be in your .gitignore.

      +
      # .env (NEVER commit this file)
+GITHUB_TOKEN=ghp_yourtokenhere
+DATABASE_URL=postgres://user:password@localhost/mydb
+STRIPE_SECRET_KEY=sk_test_yourkeyhere
      +

      Load it in your code with a library like dotenv (JavaScript) or python-dotenv (Python). The .env file stays on your machine; the code that reads it goes into the repository.

      +

      Sharing secrets with your team safely

      +

      Never send secrets in Slack, email, or GitHub comments. Use:

      +
        +
      • GitHub Actions Secrets — for CI/CD pipelines: Settings → Secrets and variables → Actions
        • +
      • A password manager with sharing (1Password Teams, Bitwarden) — for team credentials
        • +
      • A secrets manager (AWS Secrets Manager, HashiCorp Vault) — for production systems
        • +
      +

      Example: Using GitHub Actions Secrets

      +
      # .github/workflows/deploy.yml
+jobs:
+  deploy:
+    runs-on: ubuntu-latest
+    steps:
+      - name: Deploy
+        env:
+          API_KEY: ${{ secrets.API_KEY }}   # Pulled from GitHub Secrets, never in code
+        run: ./deploy.sh
      +
      +

      4. Review Before You Commit

      +

      The most effective habit is simply reviewing what you're about to commit before you commit it.

      +

      git diff --staged — see exactly what's going in

      +
      # Review all staged changes before committing
+git diff --staged
+
+# Review a specific file
+git diff --staged docs/config.md
      +

      Read through the diff looking for:

      +
        +
      • Any hardcoded passwords, tokens, or API keys
        • +
      • .env or credential files that snuck in
        • +
      • Any TODO comments that reference sensitive information
        • +
      +

      Avoid git add . blindly

      +

      git add . stages everything in your working directory — including files you didn't mean to add.

      +
      # Risky - stages everything without review
+git add .
+
+# Better - stage specific files you know are clean
+git add src/auth.js docs/README.md
+
+# Or stage interactively - review each file before adding
+git add -p
      +

      git add -p (patch mode) walks you through each change chunk by chunk and asks whether to stage it. It's slower but gives you full control.

      +

      Check what's staged before committing

      +
      # See which files are staged (and which aren't)
+git status
+
+# See the full diff of staged changes
+git diff --staged
      +
      +

      GitHub Copilot can help: After staging your changes, open Copilot Chat and ask: "Review my staged changes for any accidentally included secrets, API keys, or credentials." Paste the output of git diff --staged into the chat.

      +
      +
      +

      5. Pre-Commit Hooks — Automated Secret Detection

      +

      A pre-commit hook is a script that runs automatically every time you try to commit. If the script detects a problem (like a potential secret), it blocks the commit and tells you what it found.

      +

      Think of it as a safety net that catches things you might have missed during review.

      + +

      detect-secrets scans for over 20 types of secrets and integrates well with existing repos.

      +
      # Install
+pip install detect-secrets
+
+# Create a baseline (scan your existing code — mark known non-secrets as safe)
+detect-secrets scan > .secrets.baseline
+
+# Install the pre-commit hook
+detect-secrets hook
+
+# Test it manually
+detect-secrets scan
      +

      After setup, any commit containing a potential secret is blocked with a clear message showing which file and line triggered the alert.

      +

      Option B: gitleaks (Go-based, zero dependencies)

      +
      # Install on macOS
+brew install gitleaks
+
+# Install on Windows
+winget install gitleaks
+
+# Scan your entire repo history for secrets
+gitleaks detect --source . --verbose
+
+# Scan staged changes only (what you're about to commit)
+gitleaks protect --staged
+
+# Add as a pre-commit hook manually
+# Add this to .git/hooks/pre-commit:
+gitleaks protect --staged -v
      +

      Option C: pre-commit framework (manages multiple hooks)

      +

      The pre-commit framework lets you install and manage hooks from a YAML config file, making it easy to share hook config across your team.

      +
      # Install
+pip install pre-commit
+
+# Create .pre-commit-config.yaml in your repo root:
      +
      # .pre-commit-config.yaml
+repos:
+  - repo: https://github.com/Yelp/detect-secrets
+    rev: v1.4.0
+    hooks:
+      - id: detect-secrets
+
+  - repo: https://github.com/gitleaks/gitleaks
+    rev: v8.18.0
+    hooks:
+      - id: gitleaks
      +
      # Install the hooks
+pre-commit install
+
+# Run manually against all files
+pre-commit run --all-files
      +
      +

      Note: Pre-commit hooks live in .git/hooks/ and are local to your machine — they're not committed to the repo automatically. To share hook config with your team, commit the .pre-commit-config.yaml file and ask everyone to run pre-commit install.

      +
      +
      +

      6. I Accidentally Committed a Secret — What Now?

      +

      Stay calm and act quickly. Follow these steps in order.

      +

      Step 1: Rotate the secret immediately

      +

      Before anything else — go to wherever that secret is managed and revoke or rotate it. It may already be compromised, so neutralizing it is more important than removing it from git history.

      + + + + + + + + + + + + + + + + + + + + + + + + + + + +
      Secret typeWhere to rotate
      GitHub PATgithub.com/settings/tokens → Delete and regenerate
      SSH keygithub.com/settings/keys → Delete and generate new
      AWS keyAWS IAM Console → Deactivate and create new
      Stripe keyStripe Dashboard → Developers → API Keys → Roll key
      Any other API keyCheck the service's dashboard for key management
      +

      GitHub automatically revokes its own tokens when secret scanning detects them. Other services do not.

      +

      Step 2: Was it pushed to a public repo?

      +

      If it was pushed (remote has the secret):

      +

      The secret is potentially already compromised — assume it was harvested. Rotation is critical. Then remove it from history:

      +

      If it was only committed locally (not pushed):

      +

      You can fix it cleanly before anyone sees it:

      +
      # Undo the last commit, keep your changes staged (safest)
+git reset --soft HEAD~1
+
+# Now remove the secret from the file, re-add, and re-commit
+# (Edit the file to remove the secret)
+git add -p   # Review what you stage
+git commit -m "Your original commit message without the secret"
      +

      Step 3: Remove the secret from git history

      +
      +

      This only matters if the commit was pushed. If it was local-only and you used git reset --soft above, you're done.

      +
      +

      Method A: git filter-repo (recommended — built-in, modern)

      +
      # Install git-filter-repo
+pip install git-filter-repo
+
+# Remove a specific file from all history
+git filter-repo --path secrets.json --invert-paths
+
+# Replace a specific string (the secret value) throughout all history
+git filter-repo --replace-text <(echo "ghp_actualtoken==>REMOVED")
      +

      Method B: BFG Repo-Cleaner (fast, Java-based)

      +
      # Download BFG
+# From https://rtyley.github.io/bfg-repo-cleaner/
+
+# Remove a file from all history
+java -jar bfg.jar --delete-files secrets.json
+
+# Replace secret strings
+# Create a file called passwords.txt with the secret on each line
+java -jar bfg.jar --replace-text passwords.txt
      +

      Step 4: Force push the cleaned history

      +

      After rewriting history, you must force push:

      +
      git push --force-with-lease origin main
      +
      +

      Coordinate with your team first. Anyone who has cloned or pulled the repo will need to re-clone or rebase after a force push. Send a heads-up before doing this on a shared repo.

      +
      +

      Step 5: Tell GitHub to rescan

      +

      After removing the secret from history, go to Security → Secret scanning in your repository and mark any open alerts as resolved.

      +

      Quick decision flowchart

      +
      Secret committed
+      │
+      ├─ Still local only (not pushed)?
+      │     └─ git reset --soft HEAD~1 -> remove secret -> recommit
+      │
+      └─ Already pushed?
+            ├─ Rotate the secret FIRST (assume compromised)
+            ├─ Remove from history with git filter-repo or BFG
+            └─ Force push + notify team
      +
      +

      7. GitHub's Built-In Push Protection

      +

      GitHub automatically scans pushes for known secret patterns before they reach the remote. If it detects a secret, the push is blocked.

      +
      remote: Push cannot contain secrets.
+remote:
+remote:   Secret detected: GitHub Personal Access Token
+remote:   File: config/settings.py, Line: 14
+remote:
+remote:   To bypass (if this is a false positive):
+remote:   https://github.com/owner/repo/security/secret-scanning/unblock-secret/TOKEN
      +

      What push protection covers

      +

      GitHub knows the patterns for hundreds of secret types including:

      +
        +
      • GitHub tokens (PATs, GitHub App tokens, OAuth tokens)
        • +
      • AWS access keys
        • +
      • Azure credentials
        • +
      • Google Cloud keys
        • +
      • Stripe, Twilio, Slack, and dozens more API keys
        • +
      +

      If push protection blocks you

      +
        +
      1. Confirm it's actually a secret — check the file and line mentioned
        2. +
      2. If it's a real secret: Remove it from the file, amend your commit, and push again
        3. +
      3. If it's a false positive: Use the bypass URL GitHub provides to push with an explanation
        4. +
      +

      Checking your repo's push protection status

      +

      As a contributor you can see push protection in action when a push is blocked. Maintainers configure it in Settings → Code security → Push protection.

      +
      +

      For full detail on GitHub's security scanning features: See Appendix L: GitHub Security Features.

      +
      +
      +

      8. Secure Credential Storage

      +

      Never store credentials in plaintext

      +

      Do not do these:

      +
      # Storing a token in a plain text file
+echo "ghp_mytoken" > ~/token.txt
+
+# Hardcoding in a script
+export GITHUB_TOKEN="ghp_mytoken"  # in a .bashrc or .zshrc that's committed
+
+# In a git config
+git config --global url."https://myusername:ghp_mytoken@github.com".insteadOf "https://github.com"
      +

      Do this instead - use the OS credential store:

      +
      # macOS — use Keychain
+git config --global credential.helper osxkeychain
+
+# Windows — use Credential Manager (set automatically by Git for Windows)
+git config --global credential.helper wincred
+
+# Linux — use the libsecret store (requires installation)
+git config --global credential.helper /usr/share/doc/git/contrib/credential/libsecret/git-credential-libsecret
      +

      With a credential helper set, Git asks for your credentials once and stores them securely in the OS keychain — not in any file.

      +

      Using a password manager

      +

      Store your GitHub PAT, SSH key passphrase, and other credentials in a password manager (1Password, Bitwarden, KeePass). Most support browser extensions, CLI access, and automatic lock after inactivity.

      +

      Checking what credential helper is set

      +
      git config --global credential.helper
      +

      If this returns nothing, your credentials may be stored in plaintext. Set a credential helper as above.

      +

      Learning Cards: Security Checklist

      +
      +Screen reader users + +
        +
      • The checklist below uses Markdown task list formatting -- each item is announced as "checkbox not checked"
        • +
      • Items are grouped into three categories: Before Committing, Before Pushing, and Repository Setup
        • +
      • Read through the list once to learn the habits, then use it as a pre-push routine
        • +
      +
      + +
      +Low vision users + +
        +
      • Checkboxes create a clear visual pattern for scanning -- each line starts with a square box
        • +
      • Three groups are separated by h3 headings: Before Committing, Before Pushing, Repository Setup
        • +
      • Consider copying this checklist into a personal note and checking items off for each project
        • +
      +
      + +
      +Sighted users + +
        +
      • This is a printable pre-push checklist -- bookmark it or copy it into your project's CONTRIBUTING.md
        • +
      • Three sections cover the complete workflow: staging, pushing, and one-time repository setup
        • +
      • The most critical items are the first two in "Before Committing" -- git diff review and selective git add
        • +
      +
      + +
      +

      9. Security Checklist for Contributors

      +

      Use this before every push to a public repository.

      +

      Before committing

      +
        +
      • I reviewed git diff --staged and didn't see any tokens, passwords, or keys
        • +
      • I used git add <specific files> or git add -p rather than git add .
        • +
      • Any .env files or credential files are listed in .gitignore
        • +
      • Config files with real values are in .gitignore; only example/template files are committed
        • +
      +

      Before pushing

      +
        +
      • git log --oneline -5 — all commits look expected
        • +
      • No commits with messages like "remove secret" or "oops" that suggest a secret was added and removed (the secret is still in history)
        • +
      +

      Repository setup (one time)

      +
        +
      • .gitignore includes .env, *.key, *.pem, and relevant patterns for your stack
        • +
      • Global .gitignore (~/.gitignore_global) covers editor/OS files
        • +
      • Git credential helper is configured to use the OS keychain
        • +
      • (Optional) A pre-commit hook is installed to scan for secrets automatically
        • +
      +

      If you're a maintainer

      +
        +
      • Branch protection is enabled on main with required reviews and status checks
        • +
      • Secret scanning is enabled (Settings → Code security → Secret scanning)
        • +
      • Push protection is enabled for the repository
        • +
      • A SECURITY.md file exists with instructions for reporting vulnerabilities
        • +
      +
      +

      See also: Appendix L: GitHub Security Features for the GitHub platform security tools (Dependabot, secret scanning alerts, code scanning). Appendix D: Git Authentication for SSH keys, PATs, and commit signing.

      +
      +
      +

      Next: Appendix G: VS Code Reference
      Back: Appendix E: Advanced Git
      Teaching chapter: Chapter 08: Open Source Culture

      + +
      + + + + diff --git a/html/admin/qa-bundle/docs/appendix-g-vscode-reference.html b/html/admin/qa-bundle/docs/appendix-g-vscode-reference.html new file mode 100644 index 00000000..8e12e7a8 --- /dev/null +++ b/html/admin/qa-bundle/docs/appendix-g-vscode-reference.html @@ -0,0 +1,1901 @@ + + + + + + + Appendix G: VS Code Accessibility Reference - GIT Going with GitHub + + + + + + + + +
      +

      Appendix G: VS Code Accessibility Reference

      +
      +

      Listen to Episode 30: VS Code Accessibility Reference - a conversational audio overview of this chapter. Listen before reading to preview the concepts, or after to reinforce what you learned.

      +
      +
      +

      Reference companion to: Chapter 11: VS Code Interface | Also relevant: Chapter 12

      +

      Authoritative source: VS Code Docs: Accessibility

      +
      +

      Complete Technical Reference for Screen Reader Users

      +
      +

      Purpose: This appendix provides comprehensive technical documentation for all VS Code accessibility features, settings, and keyboard shortcuts. The main chapters cover essentials; this appendix is your complete reference manual.

      +

      Referenced by: VS Code Setup & Accessibility Basics, GitHub Copilot

      +
      +

      Learning Cards: VS Code Accessibility Reference Overview

      +
      +Screen reader users + +
        +
      • This appendix is your lookup manual -- use Ctrl+G (Go to Line) or Ctrl+Shift+O (Go to Symbol) to jump directly to a setting name
        • +
      • Every table is structured with headers; use T in browse mode to jump between tables, then arrow through rows
        • +
      • Bookmark this file in VS Code (Ctrl+K Ctrl+K) so you can return instantly when you need a setting path
        • +
      +
      + +
      +Low vision users + +
        +
      • Increase editor font size (Ctrl+=) before scanning the long settings tables -- column values are easier to compare at larger sizes
        • +
      • Use the Minimap (if sighted enough) or breadcrumbs bar to orient within this large reference file
        • +
      • High-contrast themes make the table grid lines and code spans easier to distinguish from body text
        • +
      +
      + +
      +Sighted users + +
        +
      • The Table of Contents links jump directly to each section -- click any link to scroll there instantly
        • +
      • Use Ctrl+Shift+O to open the outline view and see all 7 sections as a navigable list
        • +
      • The settings tables use consistent columns (Setting Path, Values, Default, Description) -- scan the Default column to see what changes from your current setup
        • +
      +
      + + +

      Table of Contents

      +
        +
      1. Complete Accessibility Settings Reference
        2. +
      2. Audio Cues - All Options
        3. +
      3. Accessible Diff Viewer - Complete Guide
        4. +
      4. Screen Reader-Specific Configurations
        5. +
      5. Complete Keyboard Shortcuts
        6. +
      6. Accessibility Signals Types and Customization
        7. +
      7. Settings.json Configuration Examples
        8. +
      +

      1. Complete Accessibility Settings Reference

      +

      All settings can be accessed via Settings UI (Ctrl+,) or by editing settings.json directly (Ctrl+Shift+P → "Open User Settings JSON").

      +

      Core Accessibility Settings

      + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + +
      Setting PathValuesDefaultDescription
      editor.accessibilitySupportauto, on, offautoEnables screen reader optimizations. auto detects NVDA/JAWS/VoiceOver. Set to on to force.
      editor.accessibilityPageSizenumber (lines)10Number of lines to read when using Page Up/Down in screen reader mode
      editor.guides.bracketPairsbooleanfalseShows bracket pair guides. Disable for screen readers (visual only).
      editor.guides.bracketPairsHorizontalbooleanfalseShows horizontal bracket guides. Disable for screen readers.
      editor.guides.highlightActiveBracketPairbooleantrueHighlights matching brackets. Not announced by screen readers.
      editor.guides.highlightActiveIndentationbooleantrueHighlights active indentation. Visual only.
      editor.guides.indentationbooleantrueShows indentation guides. Not useful for screen readers.
      editor.hover.enabledbooleantrueEnables hover popups. Use Alt+F2 (Accessible View) to read hover content.
      editor.minimap.enabledbooleantrueShows visual minimap. Recommended: Set to false for screen readers.
      editor.occurrencesHighlightbooleantrueHighlights occurrences of selected text. Visual only.
      editor.renderWhitespacenone, boundary, selection, trailing, allselectionShows whitespace characters. Recommended: none for screen readers.
      editor.wordWrapoff, on, wordWrapColumn, boundedoffWraps long lines. Recommended: on for screen readers.
      workbench.editor.enablePreviewbooleantrueOpens files in preview mode (single tab). Set to false to always open in new tab.
      +

      Diff and Merge Settings

      + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + +
      Setting PathValuesDefaultDescription
      diffEditor.codeLensbooleanfalseShows CodeLens in diff view. Visual only.
      diffEditor.diffAlgorithmlegacy, advancedadvancedDiff calculation method. advanced produces better hunks for screen readers.
      diffEditor.ignoreTrimWhitespacebooleantrueIgnores whitespace changes in diffs. Recommended: true to reduce noise.
      diffEditor.renderSideBySidebooleantrueShows diffs side-by-side. Set to false for inline view (easier for screen readers).
      diffEditor.wordWrapoff, on, inheritinheritWord wrap in diff view. on recommended for long lines.
      merge-conflict.decorators.enabledbooleantrueShows merge conflict decorators. Use Accessible Diff instead (F7).
      +

      Terminal Settings

      + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + +
      Setting PathValuesDefaultDescription
      terminal.integrated.accessibleViewFocusesTerminalbooleantrueReturns focus to terminal after closing Accessible View.
      terminal.integrated.accessibleViewPreserveCursorPositionbooleanfalsePreserves cursor position when opening Accessible View.
      terminal.integrated.enableBellbooleanfalseEnables terminal bell sound. Recommended: true for audio feedback.
      terminal.integrated.screenReaderModeauto, on, offautoOptimizes terminal for screen readers.
      +

      Notification Settings

      + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + +
      Setting PathValuesDefaultDescription
      accessibility.verbosity.commentsbooleantrueAnnounces comment threads in code.
      accessibility.verbosity.diff-editorbooleantrueAnnounces diff editor context.
      accessibility.verbosity.editorbooleantrueAnnounces editor operations.
      accessibility.verbosity.hoverbooleantrueAnnounces hover content. Use Alt+F2 for full reading.
      accessibility.verbosity.inline-chatbooleantrueAnnounces inline chat responses.
      accessibility.verbosity.inline-completionsbooleantrueAnnounces Copilot suggestions.
      accessibility.verbosity.keybindings-editorbooleantrueAnnounces keybindings editor context.
      accessibility.verbosity.notebookbooleantrueAnnounces notebook cell operations.
      accessibility.verbosity.panel-chatbooleantrueAnnounces Copilot Chat panel responses.
      accessibility.verbosity.settings-editorbooleantrueAnnounces settings editor context.
      accessibility.verbosity.terminalbooleantrueAnnounces terminal operations.
      +

      2. Audio Cues - All Options

      +

      Audio cues provide non-verbal feedback through sound. Each cue can be configured independently.

      +

      Accessing Audio Cue Settings

      +

      Settings UI: Ctrl+, → search "audio cue"

      +

      Settings.json: Edit directly (see Section 7)

      +

      Audio Cue Values

      + + + + + + + + + + + + + + + + + + + +
      ValueBehavior
      autoPlay sound in screen reader mode only
      onAlways play sound
      offNever play sound
      +

      Complete Accessibility Signals List

      + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + +
      SettingWhen It PlaysRecommended
      accessibility.signals.clearWhen clearing the terminal or outputon
      accessibility.signals.chatRequestSentWhen sending a Copilot Chat prompton
      accessibility.signals.chatResponsePendingWhile Copilot is generating a responseauto
      accessibility.signals.chatResponseReceivedWhen Copilot finishes respondingon
      accessibility.signals.debugBreakpointWhen hitting a breakpoint in debuggeron
      accessibility.signals.diffLineDeletedWhen navigating over a deleted line in diffon
      accessibility.signals.diffLineInsertedWhen navigating over an added line in diffon
      accessibility.signals.diffLineModifiedWhen navigating over a modified line in diffon
      accessibility.signals.formatWhen auto-formatting completesauto
      accessibility.signals.lineHasBreakpointWhen cursor is on a line with a breakpointauto
      accessibility.signals.lineHasErrorWhen cursor is on a line with an erroron
      accessibility.signals.lineHasFoldedAreaWhen cursor is on a line with collapsed codeauto
      accessibility.signals.lineHasInlineSuggestionWhen an inline suggestion appearson
      accessibility.signals.lineHasWarningWhen cursor is on a line with a warningauto
      accessibility.signals.noInlayHintsWhen inlay hints are not availableoff
      accessibility.signals.notebookCellCompletedWhen a notebook cell finishes executingon
      accessibility.signals.notebookCellFailedWhen a notebook cell failson
      accessibility.signals.onDebugBreakWhen debugger pauses executionon
      accessibility.signals.saveWhen saving a fileauto
      accessibility.signals.taskCompletedWhen a terminal task completes successfullyon
      accessibility.signals.taskFailedWhen a terminal task failson
      accessibility.signals.terminalBellWhen terminal bell ringson
      accessibility.signals.terminalCommandFailedWhen a terminal command exits with erroron
      accessibility.signals.terminalQuickFixWhen a terminal quick fix is availableauto
      accessibility.signals.voiceRecordingStartedWhen voice input beginson
      accessibility.signals.voiceRecordingStoppedWhen voice input endson
      accessibility.signals.volumeVolume level (0-100)70
      +

      Customizing Signal Sounds

      +

      Advanced feature: You can replace default sounds with custom audio files.

      +
        +
      1. Ctrl+Shift+P → "Preferences: Open User Settings (JSON)"
        2. +
      2. Add custom sound paths:
        3. +
      +
      {
+  "accessibility.signals.lineHasError.sound": "file:///C:/Users/YourName/sounds/error.wav",
+  "accessibility.signals.taskCompleted.sound": "file:///C:/Users/YourName/sounds/success.wav",
+  "accessibility.signals.diffLineInserted.sound": "file:///C:/Users/YourName/sounds/added.wav"
+}
      +

      Sound file requirements

      +
        +
      • Format: WAV, MP3, or OGG
        • +
      • Duration: Keep under 2 seconds
        • +
      • Volume: Normalize to avoid clipping
        • +
      +

      3. Accessible Diff Viewer - Complete Guide

      +

      The Accessible Diff Viewer presents file diffs as a structured, line-by-line list instead of a visual side-by-side view.

      +

      When to Use Accessible Diff Viewer

      +
        +
      • Reviewing pull request changes
        • +
      • Resolving merge conflicts
        • +
      • Comparing file versions (Timeline view)
        • +
      • Reviewing Copilot-generated edits
        • +
      • Any time you need to understand what changed in a file
        • +
      +

      Opening Accessible Diff Viewer

      + + + + + + + + + + + + + + + + + + + +
      MethodSteps
      Keyboard (in diff editor)Press F7 to jump to first hunk, Alt+F2 to open Accessible View
      Command PaletteCtrl+Shift+P → "Open Accessible Diff Viewer"
      AutomaticSome contexts open it automatically in screen reader mode
      +

      Diff Viewer Structure

      +

      Top-level structure

      +
      Description
      +

      The Accessible Diff Viewer starts with a header showing the file path and change summary. It then shows each hunk (changed section) in order. Each hunk contains: the hunk location (line range), unchanged context lines, the modified, added, or removed lines with their prefix, and more context lines. After all hunks, a footer shows the totals for additions and deletions.

      +

      Line prefixes

      + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + +
      PrefixMeaningScreen Reader Announcement
      (no prefix)Unchanged line (context)"Unchanged: [line content]"
      +Added line"Added: [line content]" or "Line added: [content]"
      -Removed line"Removed: [line content]" or "Line removed: [content]"
      |~Modified line (original)"Modified from: [old content]"
      |+Modified line (new version)"Modified to: [new content]"
      + +

      Hunk = a block of related changes

      + + + + + + + + + + + + + + + + + + + + + + + +
      ActionKeyboard
      Jump to next hunkF7
      Jump to previous hunkShift+F7
      Jump to next changeF8 (in some contexts)
      Jump to previous changeShift+F8
      +

      Screen Reader-Specific Navigation

      +

      NVDA/JAWS

      +
        +
      1. Open diff: Enter on file in Source Control, or F7 in an open diff
        2. +
      2. Alt+F2 to open Accessible Diff Viewer
        3. +
      3. Navigate with Up/Down Arrow (line by line)
        4. +
      4. Use H key to jump between hunks (each hunk has a heading)
        5. +
      5. Escape to close and return to editor
        6. +
      +

      VoiceOver

      +
        +
      1. VO+Arrow to navigate to diff file → VO+Space to open
        2. +
      2. Option+F2 for Accessible Diff Viewer
        3. +
      3. VO+Arrow keys to navigate lines
        4. +
      4. VO+Command+H to jump between hunk headings
        5. +
      5. Escape to close
        6. +
      +

      Understanding Context Lines

      +

      The diff shows 3 unchanged lines before and after each change for context. These are announced as "Unchanged: [content]".

      +

      Example

      +
      Hunk 1 of 3 - lines 42-48
+
+  Unchanged: ## Screen Reader Setup
+  Unchanged:
+- Removed: This guide covers NVDA only.
++ Added: This guide covers NVDA, JAWS, and VoiceOver.
+  Unchanged:
+  Unchanged: ### Installing NVDA
      +

      The unchanged lines help you understand where in the file the change occurred.

      +

      Inline Diff View vs Side-by-Side

      + +
        +
      • All changes in a single editor
        • +
      • Removed lines followed by added lines
        • +
      • Easier to navigate with screen reader reading commands
        • +
      +

      Side-by-side view (default, visual)

      +
        +
      • Left panel: original file
        • +
      • Right panel: modified file
        • +
      • Requires navigating between panels
        • +
      +

      To switch to inline view

      +
        +
      1. Open Settings: Ctrl+,
        2. +
      2. Search: "diffEditor.renderSideBySide"
        3. +
      3. Uncheck the box (or set to false in settings.json)
        4. +
      +

      Learning Cards: Accessible Diff Viewer

      +
      +Screen reader users + +
        +
      • Press F7 in any diff editor to jump to the first changed hunk -- then F7 / Shift+F7 to move between hunks
        • +
      • Use Alt+F2 (Accessible View) to read the full diff in a structured, non-streaming pane with proper line prefixes
        • +
      • Switch to inline diff view (diffEditor.renderSideBySide: false) so all changes appear in one editor instead of two panels
        • +
      +
      + +
      +Low vision users + +
        +
      • Inline diff view places removed and added lines back-to-back with color-coded backgrounds -- increase font size for easier scanning
        • +
      • Enable accessibility.signals.diffLineInserted and diffLineDeleted for audio feedback as you arrow through changed lines
        • +
      • Zoom the diff editor independently with Ctrl+= if the surrounding UI is already at a comfortable size
        • +
      +
      + +
      +Sighted users + +
        +
      • Green-highlighted lines are additions; red-highlighted lines are deletions -- look for the + and - gutters on the left
        • +
      • Use the minimap sidebar to spot clusters of changes in a long diff without scrolling
        • +
      • Click the hunk arrows in the gutter to jump directly to the next block of changes
        • +
      +
      + + +

      4. Screen Reader-Specific Configurations

      +

      NVDA Configuration for VS Code

      + +
        +

      1. Browse Mode settings:

        +
          +
        • NVDA Menu → Preferences → Settings → Browse Mode
          • +
        • "Maximum length of text on a single line": 10000
          • +
        • "Automatic focus mode for focus changes": Checked
          • +
        • "Automatic focus mode for caret movement": Unchecked
          • +
        +
        2. +

      2. Object Presentation:

        +
          +
        • "Report tooltips": Unchecked (reduces interruptions; use Alt+F2 instead)
          • +
        • "Report notifications": Checked
          • +
        • "Report object descriptions": Checked
          • +
        +
        3. +

      3. Speech settings:

        +
          +
        • "Punctuation/symbol level": Some or Most (for code reading)
          • +
        • "Automatic language switching": Checked (useful for multilingual docs)
          • +
        +
        4. +

      4. Input Composition:

        +
          +
        • "Announce candidates during IME text composition": Checked
          • +
        +
        5. +
      +

      NVDA add-ons for VS Code

      +
        +
      • Focus Highlight - shows focus location visually (helpful for sighted trainers)
        • +
      • IndentNav - navigate by indentation level (useful for Python, YAML)
        • +
      +

      VS Code-specific NVDA commands

      + + + + + + + + + + + + + + + + + + + + + + + + + + + +
      ActionNVDA Command
      Read from cursorInsert+Down Arrow
      Read allInsert+Down Arrow (twice)
      Stop speechControl
      Say all in focus modeNVDA+Shift+Down Arrow
      Move to containing browse mode documentNVDA+Control+Space
      +

      JAWS Configuration for VS Code

      + +
        +

      1. Settings Center → HTML/PDF/Accessibility:

        +
          +
        • "Auto Forms Mode": Checked
          • +
        • "ARIA Live Region Verbosity": Polite or Assertive (depending on preference)
          • +
        • "Report tooltip text": Unchecked (use Alt+F2 instead)
          • +
        +
        2. +

      2. Settings Center → Reading:

        +
          +
        • "Punctuation Level": Most (for code)
          • +
        • "Speak Long Lines Continuously": Yes
          • +
        +
        3. +

      3. Settings Center → Text Processing:

        +
          +
        • "Blank Line Announcement": Tone (less verbose than speech)
          • +
        +
        4. +
      +

      JAWS scripts for VS Code

      +

      Custom JAWS scripts exist for VS Code. Check: jaws-vscode-scripts (GitHub) for community-maintained scripts.

      +

      VS Code-specific JAWS commands

      + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + +
      ActionJAWS Command
      Say current lineInsert+Up Arrow
      Read from cursorInsert+Page Down
      Read to endInsert+Page Down (twice)
      Toggle virtual cursorInsert+Z
      List linksInsert+F7
      List headingsInsert+F6
      +

      VoiceOver Configuration for VS Code (macOS)

      + +
        +

      1. Verbosity → Text:

        +
          +
        • "Punctuation": All (for code and Markdown)
          • +
        • "Capitalization": Speak cap (useful for acronyms and code)
          • +
        • "Reading Units": Set to sentenceboundary for prose, word for code
          • +
        +
        2. +

      2. Verbosity → Announcements:

        +
          +
        • "Content Changes": On (for live regions like Copilot Chat)
          • +
        • "Status Messages": On
          • +
        +
        3. +

      3. Navigation:

        +
          +
        • "Quick Nav": OFF when inside editor (use Left+Right Arrow to toggle)
          • +
        • "Auto-interact with elements": Off (manual control preferred)
          • +
        +
        4. +

      4. Sound:

        +
          +
        • "Enable positional audio": On (helps orient focus location)
          • +
        • "Mute sound effects": Off (audio cues are helpful)
          • +
        +
        5. +
      +

      VS Code-specific VoiceOver commands

      + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + +
      ActionVoiceOver Command
      Read from cursorVO+A
      Read allVO+Shift+Down Arrow (in text area)
      Stop readingControl
      Interact with elementVO+Shift+Down Arrow
      Stop interactingVO+Shift+Up Arrow
      Jump to headingVO+Command+H
      Open rotorVO+U
      Navigate rotorLeft/Right Arrow, then Up/Down Arrow
      +

      Quick Nav navigation (when enabled)

      + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + +
      CommandAction
      HNext heading
      Shift+HPrevious heading
      LNext link
      TNext table
      BNext button
      FNext form control
      +

      Note: Quick Nav should be OFF when editing text (conflicts with text navigation).

      +

      5. Complete Keyboard Shortcuts

      +
      +

      For screen reader navigation shortcuts when using GitHub in a browser (NVDA, JAWS, VoiceOver), see Appendix B - Screen Reader Cheat Sheet.

      +
      + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + +
      ActionWindows/LinuxmacOS
      Command PaletteCtrl+Shift+PCmd+Shift+P
      Quick Open (Go to File)Ctrl+PCmd+P
      SettingsCtrl+,Cmd+,
      Keyboard ShortcutsCtrl+K Ctrl+SCmd+K Cmd+S
      Toggle SidebarCtrl+BCmd+B
      Toggle Panel (terminal/output)Ctrl+JCmd+J
      Toggle Full ScreenF11Ctrl+Cmd+F
      Zen ModeCtrl+K ZCmd+K Z
      Close WindowCtrl+WCmd+W
      New WindowCtrl+Shift+NCmd+Shift+N
      + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + +
      ActionWindows/LinuxmacOS
      ExplorerCtrl+Shift+ECmd+Shift+E
      SearchCtrl+Shift+FCmd+Shift+F
      Source ControlCtrl+Shift+GCmd+Shift+G
      Run and DebugCtrl+Shift+DCmd+Shift+D
      ExtensionsCtrl+Shift+XCmd+Shift+X
      +

      Editor - File Operations

      + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + +
      ActionWindows/LinuxmacOS
      New FileCtrl+NCmd+N
      Open FileCtrl+OCmd+O
      SaveCtrl+SCmd+S
      Save AsCtrl+Shift+SCmd+Shift+S
      Save AllCtrl+K SCmd+Option+S
      Close EditorCtrl+WCmd+W
      Close All EditorsCtrl+K WCmd+K W
      Reopen Closed EditorCtrl+Shift+TCmd+Shift+T
      Switch Between EditorsCtrl+TabCtrl+Tab
      Focus First EditorCtrl+1Cmd+1
      Focus Second EditorCtrl+2Cmd+2
      Split EditorCtrl+\Cmd+\
      +

      Editor - Navigation

      + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + +
      ActionWindows/LinuxmacOS
      Go to LineCtrl+GCtrl+G
      Go to SymbolCtrl+Shift+OCmd+Shift+O
      Go to DefinitionF12F12
      Peek DefinitionAlt+F12Option+F12
      Go to ReferencesShift+F12Shift+F12
      Go Back (navigate history)Alt+LeftCtrl+-
      Go ForwardAlt+RightCtrl+Shift+-
      Scroll UpCtrl+UpCmd+Up
      Scroll DownCtrl+DownCmd+Down
      Move to Top of FileCtrl+HomeCmd+Home or Cmd+Up
      Move to Bottom of FileCtrl+EndCmd+End or Cmd+Down
      Move to Beginning of LineHomeCmd+Left
      Move to End of LineEndCmd+Right
      Expand SelectionShift+Alt+RightShift+Option+Right
      Shrink SelectionShift+Alt+LeftShift+Option+Left
      +

      Editor - Editing

      + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + +
      ActionWindows/LinuxmacOS
      Cut LineCtrl+XCmd+X
      Copy LineCtrl+CCmd+C
      PasteCtrl+VCmd+V
      UndoCtrl+ZCmd+Z
      RedoCtrl+Shift+Z or Ctrl+YCmd+Shift+Z
      Delete LineCtrl+Shift+KCmd+Shift+K
      Insert Line BelowCtrl+EnterCmd+Enter
      Insert Line AboveCtrl+Shift+EnterCmd+Shift+Enter
      Move Line UpAlt+UpOption+Up
      Move Line DownAlt+DownOption+Down
      Copy Line UpShift+Alt+UpShift+Option+Up
      Copy Line DownShift+Alt+DownShift+Option+Down
      Join LinesCtrl+JCmd+J
      Toggle Line CommentCtrl+/Cmd+/
      Toggle Block CommentShift+Alt+AShift+Option+A
      Format DocumentShift+Alt+FShift+Option+F
      Format SelectionCtrl+K Ctrl+FCmd+K Cmd+F
      +

      Editor - Find and Replace

      + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + +
      ActionWindows/LinuxmacOS
      FindCtrl+FCmd+F
      ReplaceCtrl+HCmd+H
      Find NextF3 or EnterCmd+G or Enter
      Find PreviousShift+F3Cmd+Shift+G
      Select All OccurrencesCtrl+Shift+LCmd+Shift+L
      Add Selection to Next Find MatchCtrl+DCmd+D
      Toggle Match CaseAlt+COption+C
      Toggle Whole WordAlt+WOption+W
      Toggle RegexAlt+ROption+R
      +

      Editor - Multi-Cursor

      + + + + + + + + + + + + + + + + + + + + + + + + + + + + +
      ActionWindows/LinuxmacOS
      Add Cursor AboveCtrl+Alt+UpCmd+Option+Up
      Add Cursor BelowCtrl+Alt+DownCmd+Option+Down
      Add Cursor to Line EndsShift+Alt+IShift+Option+I
      Undo Last Cursor OperationCtrl+UCmd+U
      +

      Terminal

      + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + +
      ActionWindows/LinuxmacOS
      Toggle TerminalCtrl+BacktickCtrl+Backtick
      Create New TerminalCtrl+Shift+BacktickCtrl+Shift+Backtick
      Focus TerminalCtrl+BacktickCtrl+Backtick
      Kill TerminalCtrl+Shift+K (in terminal)Cmd+Shift+K
      Scroll Up in TerminalCtrl+Shift+UpCmd+Shift+Up
      Scroll Down in TerminalCtrl+Shift+DownCmd+Shift+Down
      +

      Source Control (Git)

      + + + + + + + + + + + + + + + + + + + + + + + + + + + + +
      ActionWindows/LinuxmacOS
      Open Source ControlCtrl+Shift+GCmd+Shift+G
      Commit (in message field)Ctrl+EnterCmd+Enter
      Stage FileCtrl+Enter (on file)Cmd+Enter
      Refresh Source ControlCtrl+R (in SC panel)Cmd+R
      +

      Diff Viewer

      + + + + + + + + + + + + + + + + + + + + + + + +
      ActionWindows/LinuxmacOS
      Next Diff HunkF7F7
      Previous Diff HunkShift+F7Shift+F7
      Open Accessible Diff ViewerAlt+F2Option+F2
      +

      Copilot

      + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + +
      ActionWindows/LinuxmacOS
      Accept SuggestionTabTab
      Reject SuggestionEscapeEscape
      Accept WordCtrl+RightCmd+Right
      Next SuggestionAlt+]Option+]
      Previous SuggestionAlt+[Option+[
      Open Suggestions ListCtrl+EnterCmd+Enter
      Open Suggestion in Accessible ViewAlt+F2Option+F2
      Insert Suggestion from Accessible ViewCtrl+/Cmd+/
      Open Copilot ChatCtrl+Shift+ICmd+Shift+I
      Inline ChatCtrl+ICmd+I
      Quick ChatCtrl+Shift+Alt+ICmd+Shift+Ctrl+I
      +

      Accessibility Features

      + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + +
      ActionWindows/LinuxmacOS
      Toggle Screen Reader ModeShift+Alt+F1Shift+Option+F1
      Accessible HelpAlt+HOption+H
      Accessible ViewAlt+F2Option+F2
      Announce Cursor PositionCtrl+Alt+Shift+GCmd+Option+Shift+G
      Open Accessibility HelpCtrl+Shift+P → "Help: Accessibility Help"Same
      +

      Problems Panel

      + + + + + + + + + + + + + + + + + + + + + + + +
      ActionWindows/LinuxmacOS
      Show ProblemsCtrl+Shift+MCmd+Shift+M
      Go to Next Error/WarningF8F8
      Go to Previous Error/WarningShift+F8Shift+F8
      +

      Markdown Preview

      + + + + + + + + + + + + + + + + + + +
      ActionWindows/LinuxmacOS
      Toggle PreviewCtrl+Shift+VCmd+Shift+V
      Open Preview to SideCtrl+K VCmd+K V
      +

      6. Accessibility Signals Types and Customization

      +

      Accessibility signals are events that trigger announcements or audio cues. Beyond audio cues, VS Code has verbal announcements for various events.

      +

      Announcement Verbosity Settings

      +

      Control how much information VS Code announces:

      + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + +
      SettingValuesDefaultControls
      accessibility.verbosity.chatQuestionCarouseltrue, falsetrueARIA hint in the Agent mode question carousel telling you about Alt+T (Focus Terminal)
      accessibility.verbosity.diffEditorverbose, minimal, offverboseDiff viewer context announcements
      accessibility.verbosity.editorverbose, minimal, offverboseGeneral editor announcements
      accessibility.verbosity.hoververbose, minimal, offverboseHover popup announcements
      accessibility.verbosity.inlineCompletionsverbose, minimal, offverboseCopilot suggestion announcements
      accessibility.verbosity.keyboardShortcutstrue, falsetrueScreen reader navigation hint in the Keyboard Shortcuts search results
      accessibility.verbosity.terminalverbose, minimal, offverboseTerminal operation announcements
      +

      verbose: Announces full context and details
      minimal: Announces only essential information
      off: No automatic announcements (use Accessible View manually)

      +

      Custom Announcement Timing

      +

      Control when and how often announcements occur:

      + + + + + + + + + + + + + + + + + + + + + + + + + + + +
      SettingValuesDefaultDescription
      accessibility.signals.debouncePositionChangesnumber (ms)500Delay before announcing position changes (prevents spam during rapid navigation)
      accessibility.signals.onDidChangeFocusbooleantrueAnnounce focus changes
      accessibility.signals.onDidChangeModelContentbooleanfalseAnnounce content changes (very verbose)
      +

      Signal Priorities

      +

      When multiple signals occur simultaneously, VS Code prioritizes them:

      +
        +
      1. Errors (highest priority) - always announced
        2. +
      2. Warnings - announced after errors
        3. +
      3. Completions - announced if no errors/warnings
        4. +
      4. Focus changes - announced last
        5. +
      +

      This prevents overlapping announcements.

      +

      Learning Cards: Accessibility Signals

      +
      +Screen reader users + +
        +
      • Start with auto for most signals -- they play only when screen reader mode is active, keeping things quiet otherwise
        • +
      • The lineHasError and taskFailed signals are the highest-value audio cues; enable these first
        • +
      • Use accessibility.signals.volume (0-100) to balance signal volume against your screen reader speech
        • +
      +
      + +
      +Low vision users + +
        +
      • Audio cues supplement visual indicators you might miss -- enable lineHasWarning and lineHasError for sounds on the current line
        • +
      • The save and format signals confirm file operations completed without needing to check the status bar visually
        • +
      • Pair audio cues with high-contrast gutter icons for a dual-channel (sight + sound) feedback loop
        • +
      +
      + +
      +Sighted users + +
        +
      • Audio cues can speed up your workflow even with full vision -- the taskCompleted chime saves you from watching terminal output
        • +
      • Search "accessibility.signals" in Settings UI to see all toggles in one filtered view with checkboxes
        • +
      • Custom sound files (WAV/MP3, under 2 seconds) can replace defaults if you want distinctive tones per event
        • +
      +
      + + +

      7. Settings.json Configuration Examples

      +

      The configuration examples below are JSON blocks you paste into your settings.json file. To apply a complete set at once, consider using VS Code Profiles -- named configuration bundles that let you switch your entire setup instantly. See Chapter 11, Section 9: Profiles for how to create, switch, export, and share profiles.

      +

      Minimal Screen Reader Profile

      +

      For users who prefer minimal announcements and use Accessible View manually

      +
      {
+  "editor.accessibilitySupport": "on",
+  "editor.minimap.enabled": false,
+  "editor.renderWhitespace": "none",
+  "editor.wordWrap": "on",
+  "diffEditor.renderSideBySide": false,
+  "accessibility.verbosity.diffEditor": "minimal",
+  "accessibility.verbosity.editor": "minimal",
+  "accessibility.verbosity.hover": "minimal",
+  "accessibility.verbosity.inlineCompletions": "minimal",
+  "accessibility.signals.lineHasError": "on",
+  "accessibility.signals.taskCompleted": "on",
+  "accessibility.signals.taskFailed": "on"
+}
      +

      Maximum Feedback Profile

      +

      For users who want all audio and verbal announcements

      +
      {
+  "editor.accessibilitySupport": "on",
+  "editor.minimap.enabled": false,
+  "editor.renderWhitespace": "none",
+  "editor.wordWrap": "on",
+  "diffEditor.renderSideBySide": false,
+  "accessibility.verbosity.diffEditor": "verbose",
+  "accessibility.verbosity.editor": "verbose",
+  "accessibility.verbosity.hover": "verbose",
+  "accessibility.verbosity.inlineCompletions": "verbose",
+  "accessibility.verbosity.terminal": "verbose",
+  "accessibility.signals.lineHasError": "on",
+  "accessibility.signals.lineHasWarning": "on",
+  "accessibility.signals.taskCompleted": "on",
+  "accessibility.signals.taskFailed": "on",
+  "accessibility.signals.diffLineInserted": "on",
+  "accessibility.signals.diffLineDeleted": "on",
+  "accessibility.signals.chatResponseReceived": "on",
+  "accessibility.signals.chatResponsePending": "on",
+  "accessibility.signals.save": "on",
+  "accessibility.signals.clear": "on",
+  "accessibility.signals.format": "on",
+  "accessibility.signals.terminalBell": "on",
+  "accessibility.signals.terminalCommandFailed": "on",
+  "terminal.integrated.enableBell": true
+}
      +

      Copilot-Optimized Profile

      +

      For users working heavily with GitHub Copilot

      +
      {
+  "editor.accessibilitySupport": "on",
+  "editor.minimap.enabled": false,
+  "editor.wordWrap": "on",
+  "accessibility.verbosity.inlineCompletions": "minimal",
+  "accessibility.verbosity.panelChat": "minimal",
+  "accessibility.signals.lineHasInlineSuggestion": "on",
+  "accessibility.signals.chatResponsePending": "on",
+  "accessibility.signals.chatResponseReceived": "on",
+  "accessibility.signals.chatRequestSent": "on",
+  "github.copilot.enable": {
+    "*": true,
+    "yaml": true,
+    "plaintext": false,
+    "markdown": true
+  }
+}
      +

      Note: The github.copilot.enable object controls which file types get Copilot suggestions.

      +

      Git/Diff-Optimized Profile

      +

      For users doing heavy PR review and diff work

      +
      {
+  "editor.accessibilitySupport": "on",
+  "diffEditor.renderSideBySide": false,
+  "diffEditor.ignoreTrimWhitespace": true,
+  "diffEditor.wordWrap": "on",
+  "diffEditor.diffAlgorithm": "advanced",
+  "accessibility.verbosity.diffEditor": "verbose",
+  "accessibility.signals.diffLineInserted": "on",
+  "accessibility.signals.diffLineDeleted": "on",
+  "accessibility.signals.diffLineModified": "on",
+  "scm.diffDecorations": "gutter",
+  "scm.diffDecorationsGutterWidth": 2
+}
      +

      Performance-Optimized Profile

      +

      For users on slower machines or with large repositories

      +
      {
+  "editor.accessibilitySupport": "on",
+  "editor.minimap.enabled": false,
+  "editor.renderWhitespace": "none",
+  "editor.guides.indentation": false,
+  "editor.guides.bracketPairs": false,
+  "editor.occurrencesHighlight": false,
+  "editor.selectionHighlight": false,
+  "editor.hover.enabled": true,
+  "editor.hover.delay": 1000,
+  "files.exclude": {
+    "**/.git": true,
+    "**/.svn": true,
+    "**/.hg": true,
+    "**/CVS": true,
+    "**/.DS_Store": true,
+    "**/node_modules": true,
+    "**/.vscode": false
+  },
+  "search.exclude": {
+    "**/node_modules": true,
+    "**/bower_components": true,
+    "**/*.code-search": true
+  }
+}
      + +

      Paste this into your settings.json for a balanced screen reader profile

      +
      {
+  "editor.accessibilitySupport": "on",
+  "editor.minimap.enabled": false,
+  "editor.renderWhitespace": "none",
+  "editor.wordWrap": "on",
+  "diffEditor.renderSideBySide": false,
+  "diffEditor.ignoreTrimWhitespace": true,
+  "diffEditor.wordWrap": "on",
+  "accessibility.verbosity.diffEditor": "verbose",
+  "accessibility.verbosity.editor": "verbose",
+  "accessibility.verbosity.hover": "verbose",
+  "accessibility.verbosity.inlineCompletions": "minimal",
+  "accessibility.verbosity.panelChat": "minimal",
+  "accessibility.signals.lineHasError": "on",
+  "accessibility.signals.lineHasWarning": "auto",
+  "accessibility.signals.taskCompleted": "on",
+  "accessibility.signals.taskFailed": "on",
+  "accessibility.signals.diffLineInserted": "on",
+  "accessibility.signals.diffLineDeleted": "on",
+  "accessibility.signals.chatResponseReceived": "on",
+  "terminal.integrated.enableBell": true,
+  "workbench.editor.enablePreview": false
+}
      +
      +

      Next: Appendix H: GitHub Desktop
      Back: Appendix F: Git Security
      Teaching chapter: Chapter 11: VS Code Interface

      + +
      + + + + diff --git a/html/admin/qa-bundle/docs/appendix-h-github-desktop.html b/html/admin/qa-bundle/docs/appendix-h-github-desktop.html new file mode 100644 index 00000000..b2847142 --- /dev/null +++ b/html/admin/qa-bundle/docs/appendix-h-github-desktop.html @@ -0,0 +1,669 @@ + + + + + + + Appendix H: GitHub Desktop - GIT Going with GitHub + + + + + + + + +
      +

      Appendix H: GitHub Desktop

      +
      +

      Episode coming soon: GitHub Desktop - a conversational audio overview of this appendix. Listen before reading to preview the concepts, or after to reinforce what you learned.

      +
      +
      +

      Reference companion to: Chapter 01: Choose Your Tools | Also relevant: Chapter 14

      +

      Authoritative source: GitHub Desktop Docs

      +
      +

      A Visual Git Client for Every Workflow

      +
      +

      Who this is for: You want a dedicated graphical Git application — something separate from your code editor, with a clear visual interface for cloning, branching, committing, and managing pull requests. GitHub Desktop is a great fit if you prefer working with a purpose-built Git GUI, or if VS Code's Source Control panel feels too embedded in the editor for your workflow.

      +

      GitHub Desktop is free, open source, and made by GitHub. It works on Windows and macOS.

      +
      +
      +

      Table of Contents

      +
        +
      1. What GitHub Desktop Does (and Doesn't Do)
        2. +
      2. Installing GitHub Desktop
        3. +
      3. Signing In and Authentication
        4. +
      4. The Interface at a Glance
        5. +
      5. Cloning a Repository
        6. +
      6. Creating and Switching Branches
        7. +
      7. Staging and Committing Changes
        8. +
      8. Push and Pull
        9. +
      9. Syncing Your Fork
        10. +
      10. Resolving Merge Conflicts
        11. +
      11. Viewing History
        12. +
      12. Cherry-Pick in GitHub Desktop
        13. +
      13. Stashing Changes
        14. +
      14. Undoing Changes
        15. +
      15. Accessibility and Screen Reader Notes
        16. +
      16. GitHub Desktop vs VS Code vs Git CLI — When to Use Each
        17. +
      +
      +

      1. What GitHub Desktop Does (and Doesn't Do)

      +

      GitHub Desktop covers the everyday Git workflow that most contributors use on most days.

      +

      What it supports

      +
        +
      • Supported: Clone repositories from GitHub
        • +
      • Supported: Create, switch, and delete branches
        • +
      • Supported: Stage files (and individual lines/hunks within files)
        • +
      • Supported: Write commit messages and commit
        • +
      • Supported: Push and pull from GitHub
        • +
      • Supported: Open pull requests (launches GitHub.com in your browser)
        • +
      • Supported: Resolve merge conflicts with a visual editor
        • +
      • Supported: View commit history and diffs
        • +
      • Supported: Cherry-pick commits between branches
        • +
      • Supported: Stash and restore uncommitted changes
        • +
      • Supported: Undo commits and discard changes
        • +
      +

      What it does not support (use Git CLI or VS Code terminal instead)

      +
        +
      • Not supported in the GitHub Desktop UI: Interactive rebase (git rebase -i)
        • +
      • Not supported in the GitHub Desktop UI: git bisect
        • +
      • Not supported in the GitHub Desktop UI: git clean
        • +
      • Not supported in the GitHub Desktop UI: Creating annotated tags
        • +
      • Not supported in the GitHub Desktop UI: Commit signing (GPG/SSH)
        • +
      +

      For these operations, open the repository in your terminal directly from GitHub Desktop — Repository → Open in Terminal or Repository → Open in Command Prompt puts you in the right directory instantly.

      +

      Learning Cards: What GitHub Desktop Does

      +
      +Screen reader users + +
        +
      • GitHub Desktop handles cloning, branching, staging, committing, and pushing -- all accessible via keyboard and standard form controls
        • +
      • For operations Desktop does not support (rebase, bisect, clean), use Repository then Open in Terminal to land in the right directory instantly
        • +
      • All commit message fields are standard text inputs that screen readers announce as editable text
        • +
      +
      + +
      +Low vision users + +
        +
      • GitHub Desktop supports system-level zoom and high-contrast OS themes on both Windows and macOS
        • +
      • The diff panel uses green and red backgrounds for additions and deletions -- pair these with font size adjustments in your OS display settings
        • +
      • If the diff colors are hard to distinguish, open the same diff in VS Code via Repository then Open in VS Code for more theme options
        • +
      +
      + +
      +Sighted users + +
        +
      • The three-panel layout (toolbar, file list, diff view) gives you a visual snapshot of your repository state at a glance
        • +
      • Look for the badge count on the Fetch/Push button to see how many commits are waiting to push or pull
        • +
      • The check mark, plus, and minus icons next to filenames show modified, added, and deleted status instantly
        • +
      +
      + +
      +

      2. Installing GitHub Desktop

      +

      Windows

      +

      Option A: Winget (recommended)

      +
      winget install GitHub.GitHubDesktop
      +

      Option B: Direct download

      +
        +
      1. Go to desktop.github.com
        2. +
      2. Select "Download for Windows"
        3. +
      3. Run the installer — it installs and launches automatically
        4. +
      +

      macOS

      +

      Option A: Homebrew

      +
      brew install --cask github
      +

      Option B: Direct download

      +
        +
      1. Go to desktop.github.com
        2. +
      2. Select "Download for macOS"
        3. +
      3. Open the downloaded .zip, drag GitHub Desktop to your Applications folder
        4. +
      +
      +

      Linux: GitHub Desktop does not officially support Linux. Linux users should use VS Code's Source Control panel or the Git CLI.

      +
      +
      +

      3. Signing In and Authentication

      +

      GitHub Desktop uses browser-based OAuth sign-in — no tokens or SSH keys needed. It handles authentication for you automatically.

      +

      Sign in on first launch

      +
        +
      1. Open GitHub Desktop
        2. +
      2. Select "Sign in to GitHub.com"
        3. +
      3. Your browser opens to a GitHub authorization page — sign in with your GitHub account
        4. +
      4. Authorize GitHub Desktop when prompted
        5. +
      5. Switch back to GitHub Desktop — you're signed in
        6. +
      +

      That's it. GitHub Desktop stores your credentials securely in the system keychain. You won't be asked for a password again.

      +
      +

      If you use GitHub Enterprise or a GitHub organization: Select "Sign in to GitHub Enterprise Server" and enter your organization's server URL.

      +
      +
      +

      4. The Interface at a Glance

      +

      GitHub Desktop has three main areas:

      +
      ┌─────────────────────────────────────────────────────────┐
+│  Toolbar: Current Repository ▾  |  Current Branch ▾  |  │
+│                                    Fetch/Push button      │
+├─────────────────┬───────────────────────────────────────┤
+│                 │                                         │
+│  Left panel:    │  Main area:                            │
+│  Changes tab    │  File diff view                        │
+│  (staged /      │  (what changed in the selected file)   │
+│  unstaged)      │                                        │
+│                 │                                         │
+│  OR             │                                         │
+│                 │                                         │
+│  History tab    │  Commit detail / diff                  │
+│  (past commits) │                                        │
+│                 │                                         │
+├─────────────────┴───────────────────────────────────────┤
+│  Commit area: Summary field | Description | Commit button │
+└─────────────────────────────────────────────────────────┘
      +

      Key controls

      + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + +
      ElementWhat it does
      Current Repository (top left)Switch between your cloned repos
      Current Branch (top middle)Switch branches, create new branches
      Fetch/Push button (top right)Sync with GitHub (fetch, push, pull)
      Changes tabShows your uncommitted changes
      History tabShows your commit history
      Summary field (bottom left)Where you type your commit message
      Commit button (bottom left)Commits staged changes
      +

      Learning Cards: The Desktop Interface

      +
      +Screen reader users + +
        +
      • Use Tab to move between the toolbar, file list, diff pane, and commit area -- each is a distinct focus region
        • +
      • The branch selector is a searchable dropdown: type to filter, Down Arrow to navigate, Enter to select
        • +
      • The commit button is announced as "Commit to [branch name]" -- press Enter to activate
        • +
      +
      + +
      +Low vision users + +
        +
      • The toolbar at the top stays fixed as you scroll -- repository name, branch, and sync button are always visible
        • +
      • Increase your OS display scaling to enlarge all panels proportionally without breaking the layout
        • +
      • The Changes and History tabs are side-by-side at the top of the left panel -- each tab label is clearly distinct
        • +
      +
      + +
      +Sighted users + +
        +
      • The left panel toggles between Changes (uncommitted work) and History (past commits) -- click each tab to switch
        • +
      • The main diff area updates when you select a different file in the left panel
        • +
      • Look for the upward or downward arrow on the Fetch/Push button to see whether you need to push or pull
        • +
      +
      + +
      +

      5. Cloning a Repository

      +

      From GitHub.com

      +

      The easiest way is to go to the repository on GitHub.com and use the Code button:

      +
        +
      1. On the repository page, activate Code → Open with GitHub Desktop
        2. +
      2. GitHub Desktop opens with a dialog confirming the URL
        3. +
      3. Choose where to save the repository on your computer
        4. +
      4. Select "Clone"
        5. +
      +

      From inside GitHub Desktop

      +
        +
      1. Press Ctrl+Shift+O (Windows) or Cmd+Shift+O (macOS) — "Clone a repository"
        2. +
      2. Choose the GitHub.com tab to browse your own repositories, or the URL tab to paste any repo URL
        3. +
      3. Select or type the repository
        4. +
      4. Choose a local path
        5. +
      5. Select "Clone"
        6. +
      +

      GitHub CLI alternative

      +
      gh repo clone owner/repo-name
+# Then open it in GitHub Desktop:
+github /path/to/repo
      +
      +

      6. Creating and Switching Branches

      +

      Create a new branch

      +
        +
      1. Click Current Branch in the toolbar (or press Ctrl+Shift+N / Cmd+Shift+N)
        2. +
      2. Type a name for your new branch
        3. +
      3. Select "Create Branch"
        4. +
      4. Choose whether to base it on the current branch or another — usually keep the default
        5. +
      +

      GitHub Desktop switches to the new branch immediately.

      +

      Switch to an existing branch

      +
        +
      1. Click Current Branch in the toolbar
        2. +
      2. Type to search or scroll through the branch list
        3. +
      3. Click the branch name — GitHub Desktop switches and updates your files
        4. +
      +

      Delete a branch

      +
        +
      1. Click Current Branch in the toolbar
        2. +
      2. Right-click the branch you want to delete
        3. +
      3. Select "Delete..."
        4. +
      +
      +

      Screen reader tip: The branch selector is a dropdown that opens a searchable list. Screen readers announce the currently selected branch name in the toolbar. After switching, the branch name in the toolbar updates to confirm the switch.

      +
      +
      +

      7. Staging and Committing Changes

      +

      Reviewing your changes

      +

      When you edit files in your editor and save them, GitHub Desktop automatically detects the changes and shows them in the Changes tab on the left.

      +
        +
      • The left panel lists every changed file with a checkbox
        • +
      • The right panel shows the diff for the selected file — red lines removed, green lines added
        • +
      +

      Staging files

      +

      Every file with a checked checkbox will be included in your next commit.

      +
        +
      • Check all — click the checkbox at the top of the list to stage everything
        • +
      • Uncheck a file to exclude it from the commit (it stays as an uncommitted change)
        • +
      +

      Staging individual lines (hunks)

      +

      If a file has multiple changes and you only want to commit some of them:

      +
        +
      1. Select the file in the Changes list
        2. +
      2. In the diff view, right-click a line or block
        3. +
      3. Select "Stage Line" or "Stage Hunk" — only those lines get included in the commit
        4. +
      +

      Writing your commit message

      +
        +
      1. In the Summary field at the bottom, type a short commit message (under 72 characters is ideal)
        2. +
      2. Optionally add a longer description in the Description field below it
        3. +
      3. Select "Commit to [branch name]" — your changes are committed locally
        4. +
      +
      +

      GitHub Copilot can help: Not sure what to write? Open VS Code alongside GitHub Desktop, open Copilot Chat, and ask: "Write a commit message for these changes: [describe what you changed]." Or use the conventional commit format: feat:, fix:, docs:, refactor:.

      +
      +
      +

      Screen reader tip (Windows, NVDA/JAWS): The Summary and Description fields are standard text inputs — navigate to them with Tab and type normally. The commit button is announced as a button labelled "Commit to [branch name]."

      +
      +
      +

      8. Push and Pull

      +

      After committing, your changes are saved locally but not yet on GitHub. The Fetch/Push button in the top-right toolbar handles syncing.

      +

      Pushing commits to GitHub

      +

      After committing, the button changes to "Push origin" with an upward arrow and the number of commits waiting.

      +
        +
      • Click "Push origin" — your commits go to GitHub
        • +
      +

      Pulling changes from GitHub

      +

      When collaborators have pushed new commits, the button shows "Pull origin" with a downward arrow.

      +
        +
      • Click "Pull origin" — GitHub Desktop downloads the new commits and updates your local branch
        • +
      +

      Fetching (checking without pulling)

      +
        +
      • Click "Fetch origin" — GitHub Desktop checks for new commits and shows you the count, but doesn't update your files yet
        • +
      • This is safe to do at any time — it's read-only
        • +
      +

      Keyboard shortcuts

      + + + + + + + + + + + + + +
      ActionWindowsmacOS
      Push / Pull / FetchCtrl+PCmd+P
      +
      +

      9. Syncing Your Fork

      +

      If you forked a repository and the original upstream repo has new commits you want to bring in:

      +
        +
      1. Go to Branch → Merge into current branch...
        2. +
      2. In the branch picker, switch to the "Other branches" tab
        3. +
      3. Select upstream/main (or upstream/master) — the upstream remote's default branch
        4. +
      4. Select "Create a merge commit"
        5. +
      5. Then push to your fork with "Push origin"
        6. +
      +

      Setting up the upstream remote (if not already there)

      +

      GitHub Desktop adds the upstream remote automatically when you clone a fork from GitHub.com. If it's missing:

      +
        +
      1. Open the repository in terminal: Repository → Open in Terminal
        2. +
      2. Run:
        3. +
      +
      git remote add upstream https://github.com/ORIGINAL-OWNER/ORIGINAL-REPO.git
+git fetch upstream
      +
        +
      1. Switch back to GitHub Desktop — it will now see the upstream branches
        2. +
      +
      +

      10. Resolving Merge Conflicts

      +

      When you pull from GitHub or merge a branch and there are conflicts, GitHub Desktop shows a dialog listing the conflicting files.

      +

      Step by step

      +
        +
      1. GitHub Desktop shows a "Resolve conflicts before merging" screen
        2. +

      2. Each conflicting file has two options next to it:

        +
          +
        • "Open in [your editor]" — opens the file with conflict markers for manual editing
          • +
        • "Use mine" / "Use theirs" — accept one entire side of the conflict without editing
          • +
        +
        3. +
      3. For simple conflicts (one side is clearly right), use "Use mine" or "Use theirs"
        4. +
      4. For conflicts where you need to keep parts of both, select "Open in [editor]" and resolve manually
        5. +
      +

      After resolving in your editor

      +
        +
      1. Save the file
        2. +
      2. Switch back to GitHub Desktop — the file moves from "Conflicting" to "Resolved"
        3. +
      3. Once all conflicts are resolved, select "Continue merge"
        4. +
      +
      +

      GitHub Copilot can help: Open the conflicting file in VS Code alongside GitHub Desktop. Place your cursor inside a conflict region and open Copilot Chat (Ctrl+Shift+I): "Resolve this merge conflict — keep meaningful changes from both sides." Copilot suggests a resolution; you review and save.

      +
      +
      +

      Screen reader tip: The conflicts dialog lists files as a navigable list. Each file entry includes the action buttons ("Open in editor", "Use mine", "Use theirs"). Navigate with Tab between the file entries and buttons.

      +
      +
      +

      11. Viewing History

      +

      The History tab (next to the Changes tab in the left panel) shows every commit on the current branch.

      + +
        +
      1. Click the History tab
        2. +
      2. Each commit appears as a row: author avatar, commit message, author name, and timestamp
        3. +
      3. Click any commit to see the full diff on the right — what changed in each file
        4. +
      +

      Filtering commits

      +

      Type in the search field above the commit list to filter by commit message, author, or SHA.

      +

      Viewing a specific file's history

      +
        +
      1. Right-click any file in your project (via the Files panel in the diff area)
        2. +
      2. Select "Show in History" — the commit list filters to only commits that touched that file
        3. +
      +

      Comparing branches

      +
        +
      1. Click History
        2. +
      2. In the branch comparison bar above the commit list, switch to another branch
        3. +
      3. GitHub Desktop shows the commits that are different between your current branch and the selected branch
        4. +
      +
      +

      12. Cherry-Pick in GitHub Desktop

      +

      Cherry-pick lets you take a commit from another branch and apply it to your current branch — without merging the whole branch.

      +

      How to cherry-pick

      +
        +
      1. Switch to the branch you want to copy the commit FROM (the source branch)
        2. +
      2. Open the History tab
        3. +
      3. Find the commit you want to copy
        4. +
      4. Right-click the commit
        5. +
      5. Select "Cherry-pick commit..."
        6. +
      6. Choose the destination branch — the branch you want to apply the commit TO
        7. +
      7. GitHub Desktop applies the commit and switches to the destination branch
        8. +
      +

      If there's a conflict

      +

      GitHub Desktop shows the conflict resolution screen (same as merging). Resolve the conflicts in your editor, then switch back to GitHub Desktop to continue.

      +
      +

      GitHub Copilot can help: Before cherry-picking, open Copilot Chat and paste the commit diff: "What does this commit do? Is it safe to cherry-pick onto a branch that doesn't have the surrounding context?"

      +
      +
      +

      13. Stashing Changes

      +

      Stash saves your uncommitted changes temporarily so you can switch branches or pull without committing half-finished work.

      +

      Stash your changes

      +
        +
      1. Go to Branch → Stash All Changes (or press Ctrl+Shift+H / Cmd+Shift+H)
        2. +
      2. Your working directory reverts to the last commit
        3. +
      3. You can now switch branches safely
        4. +
      +

      Restore your stash

      +
        +
      1. Switch back to the branch where you stashed
        2. +
      2. Go to Branch → Pop Stash
        3. +
      3. Your changes come back
        4. +
      +
      +

      Note: GitHub Desktop supports one stash at a time per branch. For multiple stashes, use the Git CLI: git stash list, git stash apply stash@{1}. See Chapter 14, Section 10 for the full stash guide.

      +
      +
      +

      14. Undoing Changes

      +

      Undo the last commit

      +

      Go to Edit → Undo Last Commit (or press Ctrl+Z / Cmd+Z right after committing)

      +

      This is equivalent to git reset --soft HEAD~1 — your changes come back as staged files. Nothing is lost.

      +

      Discard changes to a file

      +

      In the Changes tab:

      +
        +
      1. Right-click a file
        2. +
      2. Select "Discard Changes..."
        3. +
      3. Confirm the dialog — the file reverts to its last committed state
        4. +
      +
      +

      Warning: Discarding changes cannot be undone. The changes are permanently deleted, not moved to trash.

      +
      +

      Discard all changes

      +
        +
      1. Right-click anywhere in the Changes list
        2. +
      2. Select "Discard All Changes..."
        3. +
      3. Confirm — everything in your working directory reverts to the last commit
        4. +
      +
      +

      15. Accessibility and Screen Reader Notes

      +

      GitHub Desktop has partial screen reader support. Core workflows work well with keyboard navigation; some visual-only elements (like avatar images and some icons) don't have text equivalents.

      +

      What works well

      + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + +
      FeatureAccessibility notes
      Commit message fieldsStandard text inputs, fully accessible
      Branch selectorSearchable dropdown, keyboard navigable
      File list (Changes/History)Arrow keys to navigate, checkboxes announceable
      Commit buttonLabelled with branch name, activatable with Enter
      Conflict resolution dialogButtons ("Use mine", "Use theirs") are labelled
      Keyboard shortcut accessMost operations have keyboard shortcuts
      +

      What has limitations

      + + + + + + + + + + + + + + + + + + + +
      FeatureLimitation
      Diff viewThe colored diff panel is partially accessible; individual lines may not be announced clearly on all platforms. Workaround: Open in VS Code for better diff navigation
      File iconsStatus icons (M for modified, A for added, D for deleted) may not always be announced — the filename is still readable
      Context menusRight-click context menus work via keyboard (Shift+F10 on Windows; Ctrl+Click on macOS)
      +

      Windows — NVDA / JAWS

      +
        +
      • Use Tab to move between panels; arrow keys within lists
        • +
      • The commit summary field is reached with Tab after the file list
        • +
      • Conflict dialogs are modal — screen reader focus moves into the dialog automatically
        • +
      +

      macOS — VoiceOver

      +
        +
      • Use Tab and VO+Arrow to navigate panels
        • +
      • The diff view can be explored with VO+Right through the lines
        • +
      • Branch selector opens a searchable popup — type to filter, Down Arrow to navigate, Return to select
        • +
      +

      VS Code as a better accessible alternative

      +

      If screen reader navigation in GitHub Desktop is frustrating for a specific operation, VS Code's Source Control panel is often more accessible. The two tools complement each other — use whichever works best for the task at hand.

      +

      Learning Cards: Desktop Accessibility

      +
      +Screen reader users + +
        +
      • Commit message fields, branch selector, and conflict resolution buttons are fully keyboard-accessible and announced
        • +
      • The diff panel has partial screen reader support -- for difficult diffs, switch to VS Code's Accessible Diff Viewer (F7 / Alt+F2)
        • +
      • Use Shift+F10 on Windows to open context menus via keyboard when right-click actions are needed
        • +
      +
      + +
      +Low vision users + +
        +
      • File status icons (M, A, D) are small -- increase OS scaling or watch for the filename and status text that accompany them
        • +
      • The conflict resolution dialog uses labeled buttons ("Use mine", "Use theirs") that are easy to identify at any zoom level
        • +
      • If diff colors are indistinguishable at your contrast settings, open the same file in VS Code for richer theme support
        • +
      +
      + +
      +Sighted users + +
        +
      • The colored diff highlights (green for added, red for removed) are visible in the main panel as soon as you click a file
        • +
      • Modal conflict dialogs appear front-and-center with clear action buttons -- no hunting required
        • +
      • Keyboard shortcuts like Ctrl+Shift+O (Clone) and Ctrl+Shift+N (New Branch) speed up common workflows visually
        • +
      +
      + +
      +

      16. GitHub Desktop vs VS Code vs Git CLI — When to Use Each

      + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + +
      SituationBest tool
      You want a clean visual overview of changes before committingGitHub Desktop
      You want to stage individual lines or hunksGitHub Desktop or VS Code
      You're doing complex operations (rebase, bisect, clean)Git CLI (terminal)
      You want the fastest screen-reader-friendly experienceGit CLI or VS Code terminal
      You want to open a PR or manage issues without leaving your toolVS Code (GitHub Pull Requests extension)
      You want to manage multiple repos at once with a visual switcherGitHub Desktop
      You're doing quick commits mid-coding sessionVS Code (Source Control panel — already open)
      +

      GitHub Desktop, VS Code, and the Git CLI all talk to the same Git repository. You can switch between them freely — use GitHub Desktop to stage and commit, then open the terminal for a git rebase -i. They don't conflict.

      +
      +

      Next: Appendix I: GitHub CLI Reference
      Back: Appendix G: VS Code Reference
      Teaching chapter: Chapter 01: Choose Your Tools

      + +
      + + + + diff --git a/html/admin/qa-bundle/docs/appendix-i-github-cli.html b/html/admin/qa-bundle/docs/appendix-i-github-cli.html new file mode 100644 index 00000000..c74c0001 --- /dev/null +++ b/html/admin/qa-bundle/docs/appendix-i-github-cli.html @@ -0,0 +1,866 @@ + + + + + + + Appendix I: GitHub CLI Reference - GIT Going with GitHub + + + + + + + + +
      +

      Appendix I: GitHub CLI Reference

      +
      +

      Episode coming soon: GitHub CLI Reference - a conversational audio overview of this appendix. Listen before reading to preview the concepts, or after to reinforce what you learned.

      +
      +
      +

      Reference companion to: Chapter 01: Choose Your Tools | Also relevant: Chapter 14

      +

      Authoritative source: GitHub CLI Manual

      +
      +

      Your Terminal, Supercharged for GitHub

      +
      +

      Who this is for: You want to manage GitHub — issues, pull requests, repos, releases — from your terminal without opening a browser. The GitHub CLI (gh) gives you full access to GitHub from the command line, with clean plain-text output that works beautifully with screen readers.

      +

      gh handles the GitHub side of things (issues, PRs, repos, releases). git handles the local version control side (commits, branches, history). You use both together.

      +
      +
      +

      Table of Contents

      +
        +
      1. Installing and Authenticating
        2. +
      2. Repos — Clone, Fork, Create, View
        3. +
      3. Issues — Create, List, View, Comment, Close
        4. +
      4. Pull Requests — Create, Review, Merge, Check
        5. +
      5. Releases — Create, List, Upload
        6. +
      6. Search — Issues, PRs, Repos, Code
        7. +
      7. Labels and Milestones
        8. +
      8. Output Formatting — JSON, jq, Templates
        9. +
      9. Aliases — Create Your Own Shortcuts
        10. +
      10. Extensions — Adding New Commands
        11. +
      11. Copilot in the CLI
        12. +
      12. Screen Reader Tips
        13. +
      13. Quick Reference Card
        14. +
      +
      +

      1. Installing and Authenticating

      +

      Installing

      +

      Windows

      +
      winget install GitHub.cli
      +

      Or download the installer from cli.github.com.

      +

      macOS

      +
      brew install gh
      +

      Linux (Debian/Ubuntu)

      +
      (type -p wget >/dev/null || (sudo apt update && sudo apt-get install wget -y)) \
+&& sudo mkdir -p -m 755 /etc/apt/keyrings \
+&& wget -qO- https://cli.github.com/packages/githubcli-archive-keyring.gpg | sudo tee /etc/apt/keyrings/githubcli-archive-keyring.gpg > /dev/null \
+&& sudo chmod go+r /etc/apt/keyrings/githubcli-archive-keyring.gpg \
+&& echo "deb [arch=$(dpkg --print-architecture) signed-by=/etc/apt/keyrings/githubcli-archive-keyring.gpg] https://cli.github.com/packages stable main" | sudo tee /etc/apt/sources.list.d/github-cli.list > /dev/null \
+&& sudo apt update \
+&& sudo apt install gh -y
      +

      Verify installation

      +
      gh --version
      +

      Authenticating

      +
      gh auth login
      +

      Follow the prompts:

      +
        +
      • Where do you use GitHub? → GitHub.com (or Enterprise)
        • +
      • Preferred protocol? → HTTPS (or SSH)
        • +
      • Authenticate with browser? → Yes — your browser opens for OAuth sign-in
        • +
      +

      After signing in, return to the terminal. You're done.

      +
      # Check your auth status at any time
+gh auth status
+
+# Log out
+gh auth logout
+
+# Refresh credentials / add new scopes
+gh auth refresh
      +
      +

      Screen reader tip: gh auth login is an interactive prompt — navigate with Arrow keys, confirm with Enter. All prompts are plain text and read naturally. The browser step opens automatically; switch back to the terminal when the browser confirms success.

      +
      +

      Learning Cards: Getting Started with gh

      +
      +Screen reader users + +
        +
      • gh auth login uses plain-text arrow-key prompts -- every option is announced as you arrow through the list
        • +
      • After authentication, gh auth status confirms your login in a single readable line -- no browser needed
        • +
      • All gh output is plain text with no hidden elements, making it one of the most screen-reader-friendly GitHub interfaces
        • +
      +
      + +
      +Low vision users + +
        +
      • Increase your terminal font size before running gh commands -- all output scales with your terminal settings
        • +
      • Use a high-contrast terminal theme (light text on dark background, or vice versa) for comfortable reading of command output
        • +
      • gh output is plain text with no color-dependent meaning -- colors are supplementary labels, not the only indicator
        • +
      +
      + +
      +Sighted users + +
        +
      • The interactive prompts use arrow-based selection with a highlight marker -- look for the > indicator next to your current choice
        • +
      • After gh auth login, the terminal prints a success confirmation with your username -- verify it matches your GitHub account
        • +
      • Install gh via winget or brew for the fastest setup; the binary is immediately available in your current terminal session
        • +
      +
      + +
      +

      2. Repos — Clone, Fork, Create, View

      +
      # Clone a repository (automatically sets up the remote)
+gh repo clone owner/repo-name
+
+# Fork a repo and clone your fork in one step
+gh repo fork owner/repo-name --clone
+
+# Fork without cloning (creates the fork on GitHub only)
+gh repo fork owner/repo-name
+
+# Create a brand new repository
+gh repo create my-new-project
+gh repo create my-new-project --public --description "My project description"
+gh repo create my-new-project --private
+
+# View a repository's details
+gh repo view
+gh repo view owner/repo-name
+
+# Open the repo in your browser
+gh repo view --web
+
+# List your repositories
+gh repo list
+gh repo list --limit 50
+
+# List repos for an org
+gh repo list my-org --limit 100
+
+# Archive a repository
+gh repo archive owner/repo-name
+
+# Delete a repository (careful!)
+gh repo delete owner/repo-name --confirm
+
+# Sync your fork with upstream
+gh repo sync
+gh repo sync --branch main
      +
      +

      3. Issues — Create, List, View, Comment, Close

      +

      Creating issues

      +
      # Create an issue interactively (opens a prompt for title, body, labels, etc.)
+gh issue create
+
+# Create with all details inline
+gh issue create \
+  --title "Screen reader can't navigate the settings menu" \
+  --body "When using NVDA with Firefox, the Settings menu items are not announced..." \
+  --label "bug,accessibility" \
+  --assignee "@me"
+
+# Create from a Markdown file (great for detailed bug reports)
+gh issue create --title "Accessibility audit findings" --body-file ./report.md
      +

      Listing and filtering issues

      +
      # List open issues (current repo)
+gh issue list
+
+# List issues with filters
+gh issue list --label "accessibility"
+gh issue list --label "good first issue"
+gh issue list --assignee "@me"
+gh issue list --state closed
+gh issue list --limit 50
+
+# Search issues by keyword
+gh issue list --search "screen reader"
+
+# List issues across all repos you watch
+gh issue list --repo owner/repo-name
      +

      Viewing issues

      +
      # View an issue (renders Markdown as plain text in the terminal)
+gh issue view 42
+
+# Open the issue in your browser
+gh issue view 42 --web
+
+# View comments on an issue
+gh issue view 42 --comments
      +
      +

      Screen reader tip: gh issue view 42 outputs clean plain text — title, metadata, and body all formatted without noise. Read line by line with Arrow keys. Much faster than navigating a browser page with a screen reader.

      +
      +

      Commenting and updating

      +
      # Add a comment to an issue
+gh issue comment 42 --body "I can reproduce this on Windows 11 with NVDA 2024.1."
+
+# Comment from a file
+gh issue comment 42 --body-file ./my-comment.md
+
+# Edit an issue (title, body, labels, assignees)
+gh issue edit 42 --title "Updated title"
+gh issue edit 42 --add-label "needs-reproduction"
+gh issue edit 42 --remove-label "bug"
+gh issue edit 42 --add-assignee username
+
+# Close an issue
+gh issue close 42
+gh issue close 42 --comment "Fixed in PR #56."
+gh issue close 42 --reason "not planned"
+
+# Reopen a closed issue
+gh issue reopen 42
      +

      Pinning and locking

      +
      # Pin an issue (shows at top of the Issues tab)
+gh issue pin 42
+
+# Lock an issue (prevents new comments)
+gh issue lock 42 --reason "resolved"
      +
      +

      4. Pull Requests — Create, Review, Merge, Check

      +

      Creating a PR

      +
      # Create a PR interactively (prompts for title, body, base branch, etc.)
+gh pr create
+
+# Create with all details inline
+gh pr create \
+  --title "Add keyboard navigation to settings menu" \
+  --body "Closes #42. Adds Tab/arrow key support to the settings dropdown." \
+  --base main \
+  --label "accessibility,enhancement"
+
+# Create as a draft
+gh pr create --draft
+
+# Create from a file
+gh pr create --title "Accessibility improvements" --body-file ./pr-description.md
+
+# Open the PR creation form in your browser
+gh pr create --web
      +

      Listing and viewing PRs

      +
      # List open PRs
+gh pr list
+
+# List with filters
+gh pr list --state closed
+gh pr list --author "@me"
+gh pr list --label "accessibility"
+gh pr list --search "screen reader"
+
+# View a PR (title, description, status, checks)
+gh pr view 56
+
+# View the diff of a PR
+gh pr diff 56
+
+# Open the PR in your browser
+gh pr view 56 --web
+
+# Check out a PR branch locally (to test it)
+gh pr checkout 56
      +

      Reviewing PRs

      +
      # Approve a PR
+gh pr review 56 --approve
+gh pr review 56 --approve --body "Tested with NVDA — keyboard nav works perfectly. LGTM!"
+
+# Request changes
+gh pr review 56 --request-changes --body "The focus indicator disappears on the last menu item."
+
+# Leave a comment review (no approval/rejection)
+gh pr review 56 --comment --body "A few observations — see inline comments."
      +

      Checking CI status

      +
      # View all CI checks for a PR
+gh pr checks 56
+
+# Watch checks update in real time (refreshes every 10s)
+gh pr checks 56 --watch
+
+# View checks for the current branch
+gh pr checks
      +

      Merging PRs

      +
      # Merge a PR (interactive — prompts for merge strategy)
+gh pr merge 56
+
+# Merge with a specific strategy
+gh pr merge 56 --merge          # Creates a merge commit
+gh pr merge 56 --squash         # Squashes all commits into one
+gh pr merge 56 --rebase         # Rebases commits onto base branch
+
+# Auto-merge when checks pass (great for PRs waiting on CI)
+gh pr merge 56 --auto --squash
+
+# Delete the branch after merging
+gh pr merge 56 --squash --delete-branch
      +

      Other PR operations

      +
      # Convert a draft PR to ready for review
+gh pr ready 56
+
+# Mark a ready PR back as draft
+gh pr ready 56 --undo
+
+# Update your PR branch with the latest from base (equivalent to "Update branch" button)
+gh pr update-branch 56
+gh pr update-branch 56 --rebase
+
+# Close a PR without merging
+gh pr close 56
+gh pr close 56 --comment "Superseded by #58."
+
+# Reopen a closed PR
+gh pr reopen 56
+
+# Add a comment to a PR
+gh pr comment 56 --body "Thanks for the thorough review! Addressing feedback now."
      +
      +

      5. Releases — Create, List, Upload

      +
      # Create a release interactively
+gh release create v1.2.0
+
+# Create with all details
+gh release create v1.2.0 \
+  --title "Version 1.2.0 — Accessibility Improvements" \
+  --notes "- Fixed keyboard navigation in settings\n- Added ARIA labels to all form inputs"
+
+# Create from a notes file
+gh release create v1.2.0 --notes-file ./CHANGELOG.md
+
+# Create a pre-release
+gh release create v1.2.0-beta.1 --prerelease
+
+# Create a draft release (not published yet)
+gh release create v1.2.0 --draft
+
+# Upload files to a release
+gh release upload v1.2.0 ./dist/app.zip ./dist/app.tar.gz
+
+# List releases
+gh release list
+
+# View a release
+gh release view v1.2.0
+
+# Download release assets
+gh release download v1.2.0
+gh release download v1.2.0 --pattern "*.zip"
+
+# Delete a release
+gh release delete v1.2.0
      +
      +

      See also: Appendix H: Releases, Tags, and Insights for the GitHub.com interface side of releases.

      +
      +
      +

      6. Search — Issues, PRs, Repos, Code

      +
      # Search issues across all of GitHub
+gh search issues "screen reader navigation" --label accessibility
+gh search issues "keyboard shortcut" --repo owner/repo-name
+gh search issues "help wanted" --language javascript --limit 20
+
+# Search pull requests
+gh search prs "accessibility fix" --state open
+gh search prs "WCAG" --author username
+
+# Search repositories
+gh search repos "accessible markdown editor" --language python --stars ">100"
+gh search repos "screen reader" --topic accessibility
+
+# Search code
+gh search code "aria-label" --repo owner/repo-name
+gh search code "git cherry-pick" --language markdown
      +
      +

      7. Labels and Milestones

      +

      Labels

      +
      # List labels in the current repo
+gh label list
+
+# Create a label
+gh label create "accessibility" --color "0075ca" --description "Accessibility improvements"
+
+# Clone labels from another repo (copies all their labels to yours)
+gh label clone owner/source-repo
+
+# Delete a label
+gh label delete "wontfix"
      +

      Milestones

      +
      # List milestones
+gh api repos/{owner}/{repo}/milestones --jq '.[].title'
+
+# Create a milestone
+gh api repos/{owner}/{repo}/milestones \
+  --method POST \
+  --field title="v2.0 Launch" \
+  --field description="All features for the v2.0 release" \
+  --field due_on="2026-06-01T00:00:00Z"
      +
      +

      8. Output Formatting — JSON, jq, Templates

      +

      By default gh outputs human-readable text. For scripting or custom display, you can get raw JSON and filter it.

      +

      --json flag

      +
      # Get issue data as JSON
+gh issue view 42 --json title,body,labels,state
+
+# Get PR data as JSON
+gh pr view 56 --json title,number,state,mergeable,reviews
+
+# List issues as JSON
+gh issue list --json number,title,labels,assignees
      +

      --jq flag (filter JSON inline)

      +
      # List just issue numbers and titles
+gh issue list --json number,title --jq '.[] | "\(.number): \(.title)"'
+
+# Get the names of all labels on an issue
+gh issue view 42 --json labels --jq '.labels[].name'
+
+# Count open PRs
+gh pr list --json number --jq 'length'
+
+# List reviewers who approved a PR
+gh pr view 56 --json reviews --jq '[.reviews[] | select(.state=="APPROVED") | .author.login] | unique'
      +

      --template flag (Go templates)

      +
      # Custom formatted output
+gh issue list --template '{{range .}}#{{.number}} {{.title}} ({{.state}}){{"\n"}}{{end}}'
      +
      +

      Screen reader tip: --json with --jq produces clean, predictable output — ideal for piping to a file or reading with a screen reader. The default human-readable output is also clean, but JSON gives you precise control over what's announced.

      +
      +

      Learning Cards: Output Formatting

      +
      +Screen reader users + +
        +
      • Use --json with --jq to extract exactly the fields you need -- this eliminates table formatting noise and reads as clean key-value pairs
        • +
      • Pipe long output to a file (gh issue list --json title > issues.txt) and open it in VS Code for structured navigation with Alt+F2
        • +
      • Go templates (--template) let you define a single-line-per-item format that reads naturally with arrow keys
        • +
      +
      + +
      +Low vision users + +
        +
      • The default table output aligns columns with spaces -- increase terminal font size so columns stay readable
        • +
      • JSON output with --jq strips visual formatting and gives compact text that scales cleanly with any font size
        • +
      • Pipe output to VS Code (gh pr view 42 --json body --jq '.body' | code -) to read it with your preferred editor theme and zoom
        • +
      +
      + +
      +Sighted users + +
        +
      • Default table output is already human-readable with aligned columns -- scan the header row to orient on each column
        • +
      • Use --web on any command to open the result in your browser if you prefer the GitHub web interface for detailed views
        • +
      • Chain | head -20 (macOS/Linux) or | Select-Object -First 20 (PowerShell) to preview long output before reading the full list
        • +
      +
      + +
      +

      9. Aliases — Create Your Own Shortcuts

      +

      Aliases let you create custom gh commands from long commands you run often.

      +
      # Create an alias
+gh alias set bugs 'issue list --label bug'
+gh alias set my-prs 'pr list --author @me'
+gh alias set review-ready 'pr list --label "ready for review"'
+
+# Use your alias
+gh bugs
+gh my-prs
+gh review-ready
+
+# List all aliases
+gh alias list
+
+# Delete an alias
+gh alias delete bugs
+
+# Create a shell alias (runs a shell command, not just gh commands)
+gh alias set --shell open-pr 'gh pr view $1 --web'
+gh open-pr 56   # opens PR #56 in the browser
      +

      Useful aliases to set up

      +
      # Issues assigned to you
+gh alias set mine 'issue list --assignee @me'
+
+# Your open PRs
+gh alias set mypr 'pr list --author @me --state open'
+
+# Check CI on current branch's PR
+gh alias set ci 'pr checks'
+
+# View current PR
+gh alias set pr 'pr view'
      +
      +

      10. Extensions — Adding New Commands

      +

      Extensions add new gh subcommands written by the community.

      +
      # Browse available extensions
+gh extension search
+
+# Install an extension
+gh extension install owner/gh-extension-name
+
+# List installed extensions
+gh extension list
+
+# Update all extensions
+gh extension upgrade --all
+
+# Update a specific extension
+gh extension upgrade owner/gh-extension-name
+
+# Remove an extension
+gh extension remove owner/gh-extension-name
      +

      Useful extensions

      + + + + + + + + + + + + + + + + + + + + + + + +
      ExtensionWhat it doesInstall
      github/gh-copilotAsk Copilot questions in the terminalgh extension install github/gh-copilot
      nicokosi/gh-notifyDesktop notifications for GitHub eventsgh extension install nicokosi/gh-notify
      mislav/gh-branchBetter branch switching with fuzzy searchgh extension install mislav/gh-branch
      +
      +

      11. Copilot in the CLI

      +

      Install the Copilot extension once, then ask coding and git questions without leaving the terminal.

      +
      # Install (one time)
+gh extension install github/gh-copilot
+
+# Ask for a command suggestion
+gh copilot suggest "squash my last 4 commits into one"
+gh copilot suggest "find which commit introduced a bug in auth.js"
+gh copilot suggest "create a pull request from my current branch"
+
+# Explain a command you don't recognize
+gh copilot explain "git rebase -i HEAD~3"
+gh copilot explain "git bisect start"
+gh copilot explain "find . -name '*.md' -mtime -7"
      +

      Copilot CLI shows the suggested command, explains what it does, and asks whether to run it - perfect for learning while doing.

      +

      Auto model selection

      +

      As of early 2026, gh copilot uses auto model selection by default - it picks the best available model for your request without you needing to specify one. You can still request a specific model using the --model flag if you prefer:

      +
      # Let Copilot choose automatically (default)
+gh copilot suggest "create a pull request from my current branch"
+
+# Request a specific model
+gh copilot suggest --model gpt-5 "create a pull request from my current branch"
      +

      Telemetry opt-out

      +

      As of gh CLI 2.70 (April 2026), gh collects anonymized usage telemetry by default to improve the product. To opt out:

      +
      gh config set telemetry disabled
      +

      Or set the environment variable GH_NO_UPDATE_NOTIFIER=1 to suppress update notifications only.

      +
      +

      See also: Appendix AA: Advanced Git Operations, Section 11 for more Copilot CLI examples with git operations.

      +
      +
      +

      12. Screen Reader Tips

      +

      The GitHub CLI is one of the most screen-reader-friendly ways to use GitHub. Here's why and how to get the most out of it.

      +

      Why the CLI works so well

      +
        +
      • Plain text output — no visual noise, no unlabelled buttons, no hidden dialogs
        • +
      • Predictable structure — every command produces consistent output you can navigate with arrow keys
        • +
      • No focus traps — you control when you read output; nothing streams unexpectedly
        • +
      • Keyboard-first by design — everything is a command you type
        • +
      +

      Tips by task

      +

      Reading issues and PRs:

      +
      # Pipe output to less for page-by-page reading
+gh issue view 42 | less
+
+# Save to a file and open in your editor
+gh pr view 56 > pr-56.md
+code pr-56.md
      +

      Navigating long lists:

      +
      # Limit results to a manageable number
+gh issue list --limit 10
+
+# Combine with search to narrow down
+gh issue list --search "keyboard" --limit 5
      +

      Getting just what you need:

      +
      # Get just the PR title
+gh pr view 56 --json title --jq '.title'
+
+# Get just the issue body
+gh issue view 42 --json body --jq '.body'
+
+# Get CI check status as a simple list
+gh pr checks 56 --json name,state --jq '.[] | "\(.state): \(.name)"'
      +

      Creating content without a browser:

      +
      # Write your issue body in a text file first (easier with a screen reader)
+# Then create the issue from the file
+gh issue create --title "Bug: focus lost after modal closes" --body-file ./issue.md
      +

      NVDA / JAWS (Windows)

      +
        +
      • Run gh commands in Windows Terminal or the VS Code integrated terminal — both work well with NVDA/JAWS
        • +
      • Use Insert+Down (NVDA) or Insert+F12 (JAWS) to read the current line of terminal output
        • +
      • For long output, use | less and navigate with Space (next page) and b (back)
        • +
      +

      VoiceOver (macOS)

      +
        +
      • Run gh in Terminal.app or VS Code integrated terminal
        • +
      • VO+Right moves through terminal output character by character; VO+Down line by line
        • +
      • Use Ctrl+C to stop a running command if output is too long
        • +
      +

      Learning Cards: Screen Reader CLI Workflow

      +
      +Screen reader users + +
        +
      • gh is keyboard-first by design -- no focus traps, no streaming, no unlabelled buttons; everything is typed and read as plain text
        • +
      • Use Insert+Down (NVDA) or Insert+F12 (JAWS) to read the current line, and arrow keys to move through multi-line output
        • +
      • Write issue and PR bodies in a text file first, then use --body-file ./issue.md to submit -- much easier than composing inline
        • +
      +
      + +
      +Low vision users + +
        +
      • Terminal output from gh has no icons or images -- all information is conveyed as text that scales with your terminal font
        • +
      • Use --limit 10 on list commands to keep output short enough to scan comfortably without scrolling
        • +
      • Run gh in the VS Code integrated terminal to benefit from VS Code's zoom, themes, and Accessible View (Alt+F2)
        • +
      +
      + +
      +Sighted users + +
        +
      • gh output uses subtle color coding (green for open, red for closed) -- these are supplementary; the text labels are always present
        • +
      • Use gh pr view --web or gh issue view --web to jump to the browser when you want the full visual GitHub interface
        • +
      • The gh pr checks command gives a quick pass/fail summary of CI checks without opening the browser
        • +
      +
      + +
      +

      13. Quick Reference Card

      +

      Authentication

      + + + + + + + + + + + + + + + + + + + +
      CommandWhat it does
      gh auth loginSign in to GitHub
      gh auth statusCheck login status
      gh auth logoutSign out
      +

      Repos

      + + + + + + + + + + + + + + + + + + + + + + + + + + + +
      CommandWhat it does
      gh repo clone owner/repoClone a repo
      gh repo fork owner/repo --cloneFork and clone
      gh repo create name --publicCreate a new repo
      gh repo viewView current repo info
      gh repo syncSync fork with upstream
      +

      Issues

      + + + + + + + + + + + + + + + + + + + + + + + + + + + +
      CommandWhat it does
      gh issue listList open issues
      gh issue view 42Read issue #42
      gh issue createCreate a new issue
      gh issue comment 42 --body "..."Add a comment
      gh issue close 42Close an issue
      +

      Pull Requests

      + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + +
      CommandWhat it does
      gh pr listList open PRs
      gh pr view 56Read PR #56
      gh pr createCreate a PR
      gh pr diff 56See the diff
      gh pr checks 56See CI status
      gh pr review 56 --approveApprove
      gh pr merge 56 --squashMerge (squash)
      gh pr checkout 56Check out locally
      gh pr update-branchUpdate from base
      +

      Releases

      + + + + + + + + + + + + + + + + + + + +
      CommandWhat it does
      gh release create v1.0.0Create a release
      gh release listList releases
      gh release download v1.0.0Download assets
      +

      Copilot

      + + + + + + + + + + + + + + + +
      CommandWhat it does
      gh copilot suggest "..."Get a command suggestion
      gh copilot explain "..."Explain a command
      +
      +

      Next: Appendix J: Codespaces
      Back: Appendix H: GitHub Desktop
      Teaching chapter: Chapter 01: Choose Your Tools

      + +
      + + + + diff --git a/html/admin/qa-bundle/docs/appendix-j-cloud-editors.html b/html/admin/qa-bundle/docs/appendix-j-cloud-editors.html new file mode 100644 index 00000000..1b86b9c1 --- /dev/null +++ b/html/admin/qa-bundle/docs/appendix-j-cloud-editors.html @@ -0,0 +1,526 @@ + + + + + + + Appendix J: GitHub Codespaces - GIT Going with GitHub + + + + + + + + +
      +

      Appendix J: GitHub Codespaces

      +
      +

      Listen to Episode 31: GitHub Codespaces - a conversational audio overview of this chapter. Listen before reading to preview the concepts, or after to reinforce what you learned.

      +
      +
      +

      Reference companion to: Chapter 01: Choose Your Tools | Also relevant: Chapter 11

      +

      Authoritative source: GitHub Docs: Codespaces

      +
      +

      Cloud Development Environments - Accessibility Guide

      +
      +

      GitHub Codespaces gives you a full VS Code development environment in your browser or connected to your local VS Code, running on a cloud machine. For screen reader users, this means a consistent, pre-configured environment with no local setup required.

      +
      +

      Table of Contents

      +
        +
      1. What Is GitHub Codespaces?
        2. +
      2. Creating a Codespace
        3. +
      3. Codespace Environments
        4. +
      4. Accessibility in Codespaces
        5. +
      5. Screen Reader Configuration
        6. +
      6. Keyboard Shortcuts in Codespaces
        7. +
      7. Managing Your Codespaces
        8. +
      8. Dotfiles and Persistent Configuration
        9. +
      9. Codespaces vs GitHub.dev
        10. +
      10. Common Issues and Workarounds
        11. +
      +

      1. What Is GitHub Codespaces?

      +

      A Codespace is a cloud-hosted development environment. When you open one, GitHub provisions a virtual machine, clones your repository into it, and connects it to a VS Code interface - either in your browser or via your local VS Code Desktop.

      +

      Why this matters for accessibility

      +
        +
      • No local installation of tools, compilers, or language runtimes required
        • +
      • Your screen reader and OS settings stay on your machine; only the editor runs in the cloud
        • +
      • VS Code's full accessibility features (audio cues, screen reader optimized mode, diff viewer) are available
        • +
      • The environment is identical for every workshop participant - facilitators can reproduce issues reliably
        • +
      +

      Free tier: GitHub provides a monthly free allowance of Codespace hours for personal accounts. Workshop usage typically falls well within the free tier.

      +

      Learning Cards: Cloud Editors Overview

      +
      +Screen reader users + +
        +
      • Codespaces gives you a full VS Code interface with terminal access -- your screen reader and OS settings stay on your local machine
        • +
      • The browser-based editor activates screen reader optimized mode automatically if your OS signals a screen reader is running
        • +
      • Connect a Codespace to your local VS Code Desktop (via the Codespaces extension) for the most familiar screen reader experience
        • +
      +
      + +
      +Low vision users + +
        +
      • Settings Sync carries your font size, theme, and zoom preferences from local VS Code into Codespaces automatically
        • +
      • The browser-based editor supports Ctrl+= / Ctrl+- zoom just like desktop VS Code
        • +
      • Use a high-contrast VS Code theme -- it applies identically in the cloud editor
        • +
      +
      + +
      +Sighted users + +
        +
      • Press . on any GitHub repository page to open it instantly in github.dev (browser editor, no terminal)
        • +
      • Codespaces provisions a full VM with terminal -- use it when you need to run code, not just edit
        • +
      • The default 2-core machine is sufficient for workshop exercises; upgrade only for heavy builds
        • +
      +
      + + +

      2. Creating a Codespace

      +

      From a Repository Page

      +
        +
      1. Navigate to the repository on GitHub
        2. +
      2. Press the Code button (keyboard shortcut: there is no direct shortcut - Tab to the button)
        3. +
      3. In the panel that opens, choose the Codespaces tab
        4. +
      4. Activate Create codespace on main (or your branch name)
        5. +
      5. The Codespace opens in a new browser tab after provisioning (typically 30-60 seconds)
        6. +
      +

      From the Codespaces Dashboard

      +
        +
      1. Go to github.com/codespaces
        2. +
      2. Activate New codespace
        3. +
      3. Use the search field to find your repository
        4. +
      4. Choose a branch, machine type, and region
        5. +
      5. Activate Create codespace
        6. +
      +

      Machine Types

      + + + + + + + + + + + + + + + + + + + + + + + + + + + +
      TypeCPURAMBest for
      2-core2 vCPU8 GBGeneral development, documentation
      4-core4 vCPU16 GBBuilds, tests, moderate workloads
      8-core8 vCPU32 GBHeavy builds, multiple services
      +

      For workshop exercises, the default 2-core machine is sufficient.

      +

      3. Codespace Environments

      +

      Browser (VS Code for the Web)

      +

      The Codespace opens directly in your browser as a fully functional VS Code interface.

      +
        +
      • Works in Chrome, Edge, Firefox, and Safari
        • +
      • Screen reader support varies slightly by browser - Chrome and Edge have the most consistent behavior with NVDA and JAWS
        • +
      • No installation needed
        • +
      • Some VS Code extensions are not available in the browser version
        • +
      +

      Local VS Code Desktop

      +

      If you prefer your local VS Code setup with your extensions and settings:

      +
        +
      1. Install the GitHub Codespaces extension in VS Code
        2. +
      2. Sign in to GitHub in VS Code
        3. +
      3. Open the Command Palette (Ctrl+Shift+P / Cmd+Shift+P)
        4. +
      4. Run Codespaces: Connect to Codespace
        5. +
      5. Select an existing Codespace or create a new one
        6. +
      +

      When connected via local VS Code, your screen reader interacts with your local VS Code installation - all your familiar settings apply.

      +

      4. Accessibility in Codespaces

      +

      Screen Reader Optimized Mode

      +

      When VS Code detects a screen reader, it automatically activates Screen Reader Optimized mode. You can verify or toggle it manually:

      +
        +
      1. Open the Command Palette (Ctrl+Shift+P)
        2. +
      2. Search for Toggle Screen Reader Accessibility Mode
        3. +
      3. Press Enter to activate
        4. +
      +

      In this mode:

      +
        +
      • The editor reads content line by line instead of character by character
        • +
      • Diff views are rendered as accessible text comparisons
        • +
      • Inline suggestions from Copilot are announced on a keypress rather than automatically
        • +
      +

      Audio Cues

      +

      VS Code in Codespaces supports the same audio cues as the desktop version:

      + + + + + + + + + + + + + + + + + + + + + + + + + + + +
      EventDefault Audio Cue
      Error on current lineTone
      Warning on current lineTone
      Breakpoint hitTone
      Task completedChime
      Copilot suggestion availableTone
      +

      Enable audio cues via Settings → search for "audio cues" or run Help: List Audio Cues from the Command Palette.

      +

      Terminal Accessibility

      +

      The integrated terminal in a Codespace is a standard terminal:

      +
        +
      • Screen readers read terminal output in NVDA and JAWS using their document/browse mode after output arrives
        • +
      • In NVDA: Switch to Browse Mode to read static terminal output, then back to Focus Mode to type
        • +
      • VS Code also has Accessible View (Alt+F2 when cursor is in the terminal) which renders terminal output in a navigable buffer
        • +
      +

      Learning Cards: Codespace Accessibility

      +
      +Screen reader users + +
        +
      • Screen Reader Optimized mode activates automatically -- verify with Command Palette Ctrl+Shift+P then "Toggle Screen Reader Accessibility Mode"
        • +
      • Audio cues (error, warning, task completed, Copilot suggestion) work identically in Codespaces and desktop VS Code
        • +
      • In NVDA, switch to Browse Mode to read terminal output, then Focus Mode to type -- same pattern as local VS Code
        • +
      +
      + +
      +Low vision users + +
        +
      • All VS Code zoom and theme settings apply in the browser-based Codespace -- Ctrl+= increases editor font size
        • +
      • Audio cues for errors and Copilot suggestions supplement visual indicators you might miss at lower zoom levels
        • +
      • Chrome and Edge provide the most consistent rendering of the Codespace UI at high zoom and magnification levels
        • +
      +
      + +
      +Sighted users + +
        +
      • The Codespace browser tab looks and feels like desktop VS Code -- same layout, same panels, same shortcuts
        • +
      • Look for the green "Codespaces" badge in the bottom-left corner to confirm you are connected to a cloud environment
        • +
      • If an extension is unavailable in the browser, connect the Codespace to local VS Code Desktop for full extension support
        • +
      +
      + + +

      5. Screen Reader Configuration

      +

      NVDA

      +

      No special NVDA profile is required for Codespaces in the browser. The same settings recommended in Appendix B apply:

      +
        +
      • Ensure Browse Mode is on for reading, Focus Mode for typing
        • +
      • Set maximum line length to 10000 in NVDA Settings → Browse Mode
        • +
      • In Chrome or Edge, NVDA's Browse Mode detection is generally reliable
        • +
      +

      JAWS

      +
        +
      • Use Virtual Cursor for reading page content
        • +
      • Switch to PC Cursor (Insert+Z or Num Pad Plus) when inside the editor and writing code
        • +
      • JAWS works best with the Codespace in Chrome or Edge
        • +
      +

      VoiceOver (macOS)

      +
        +
      • Use Quick Nav (Left+Right arrows) for moving through the VS Code interface
        • +
      • The Rotor (VO+U) surfaces VS Code's landmark regions
        • +
      • If text in the editor is not reading fluently, ensure Screen Reader Optimized mode is active (see above)
        • +
      +

      6. Keyboard Shortcuts in Codespaces

      +

      Codespaces uses standard VS Code keyboard shortcuts. The most important ones for workshop exercises:

      + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + +
      ShortcutAction
      Ctrl+Shift+PCommand Palette
      Ctrl+PQuick Open (search files by name)
      Ctrl+`Toggle integrated terminal
      Ctrl+Shift+EExplorer panel
      Ctrl+Shift+GSource Control panel
      Ctrl+Shift+XExtensions panel
      Ctrl+BToggle sidebar
      +

      Editor

      + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + +
      ShortcutAction
      Ctrl+Shift+KDelete line
      Alt+↑ / Alt+↓Move line up/down
      Ctrl+/Toggle line comment
      Ctrl+GGo to line number
      F8Next error or warning
      Shift+F8Previous error or warning
      Alt+F2Accessible View (terminal, notifications, Copilot output)
      +

      Source Control

      + + + + + + + + + + + + + + + +
      ShortcutAction
      Ctrl+Shift+GOpen Source Control panel
      Ctrl+EnterCommit (when focus is on message field)
      +

      7. Managing Your Codespaces

      +

      Stopping a Codespace

      +

      Codespaces automatically stop after a period of inactivity (default: 30 minutes). To stop manually:

      +
        +
      1. Go to github.com/codespaces
        2. +
      2. Find your Codespace in the list
        3. +
      3. Activate the … menu next to it
        4. +
      4. Choose Stop codespace
        5. +
      +

      Stopped Codespaces retain your files and changes. They do not use compute hours while stopped.

      +

      Deleting a Codespace

      +
        +
      1. Go to github.com/codespaces
        2. +
      2. Activate the … menu next to the Codespace
        3. +
      3. Choose Delete
        4. +
      +
      +

      Note: Deleting a Codespace removes any uncommitted or unpushed changes permanently. Always commit and push your work before deleting.

      +
      +

      Resuming a Codespace

      +
        +
      1. Go to github.com/codespaces
        2. +
      2. Find your stopped Codespace
        3. +
      3. Activate Open in … to resume it in the browser or in VS Code Desktop
        4. +
      +

      8. Dotfiles and Persistent Configuration

      +

      If you have a repository named dotfiles on your GitHub account, Codespaces will automatically apply it when provisioning new environments. This is useful for:

      +
        +
      • Setting your preferred shell (bash, zsh, fish)
        • +
      • Adding shell aliases and functions
        • +
      • Pre-installing command-line tools
        • +
      +

      To set up dotfiles: create a repository named dotfiles and add an install.sh script. Codespaces will run it automatically.

      +

      VS Code settings (themes, font size, keybindings) can be synchronized to Codespaces via Settings Sync (sign in with your GitHub account in VS Code settings).

      +

      9. Codespaces vs GitHub.dev

      + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + +
      FeatureGitHub CodespacesGitHub.dev
      Accessgithub.com/codespaces or press . then choose CodespacesPress . on any repository
      TerminalYes - full terminalNo terminal
      ExtensionsMost VS Code extensionsWeb-compatible extensions only
      Run codeYesNo
      CostFree tier, then usage-basedFree
      Screen reader supportFull VS Code + terminalFull VS Code (no terminal)
      Best forActive development, running testsQuick edits, reading code
      +

      For workshop exercises that involve running scripts or tests, use Codespaces. For quickly browsing or editing a file, GitHub.dev is faster to open.

      +

      Learning Cards: Choosing Your Cloud Editor

      +
      +Screen reader users + +
        +
      • GitHub.dev has no terminal -- choose Codespaces when you need to run commands, and github.dev for quick file edits
        • +
      • Both editors support screen reader mode, but Codespaces gives you the full terminal Accessible View (Alt+F2) that github.dev lacks
        • +
      • Press . on any repo page for github.dev; use the Codespaces dashboard at github.com/codespaces for a full environment
        • +
      +
      + +
      +Low vision users + +
        +
      • GitHub.dev loads instantly with your synced VS Code theme -- good for quick high-contrast reading of source files
        • +
      • Codespaces takes 30-60 seconds to provision but gives you terminal, builds, and the same zoom/theme settings
        • +
      • Both editors scale with browser zoom (Ctrl+=) in addition to VS Code's own font-size settings
        • +
      +
      + +
      +Sighted users + +
        +
      • Use github.dev (press .) for quick drive-by edits -- it opens immediately with no provisioning wait
        • +
      • Use Codespaces when you need to run scripts, install dependencies, or test your changes before committing
        • +
      • The comparison table above summarizes every difference -- refer back to it when deciding which to open
        • +
      +
      + + +

      10. Common Issues and Workarounds

      +

      The Codespace takes a long time to open

      +

      Provisioning a new Codespace can take up to 90 seconds. If it hangs beyond that, refresh the browser tab and try again. Resuming an existing Codespace is much faster (5-10 seconds).

      +

      Screen reader stops reading after I switch to the terminal

      +

      Switch to Browse Mode (NVDA: Insert+Space; JAWS: Insert+Z) to read the terminal output, then return to Focus Mode to type your next command.

      +

      Audio cues are not working in the browser

      +

      Some browsers mute audio by default for new tabs. Check your browser's site permissions to ensure audio is allowed for github.dev or the Codespace URL.

      +

      Extensions I rely on locally are not available

      +

      Some extensions are not compatible with the browser-based VS Code. Connect to the Codespace via VS Code Desktop instead (see Section 3) to access your full extension library.

      +

      I accidentally deleted my Codespace before pushing

      +

      If the branch exists on GitHub, you can create a new Codespace from it. Uncommitted changes in a deleted Codespace cannot be recovered.

      +

      My changes are not showing in GitHub after committing

      +

      You may have committed but not pushed. In the Source Control panel, look for the Sync Changes or Push button. Run git push in the terminal if needed.

      +
      +

      Next: Appendix K: Copilot Reference
      Back: Appendix I: GitHub CLI Reference
      Teaching chapter: Chapter 01: Choose Your Tools

      + +
      + + + + diff --git a/html/admin/qa-bundle/docs/appendix-k-copilot-reference.html b/html/admin/qa-bundle/docs/appendix-k-copilot-reference.html new file mode 100644 index 00000000..5f393788 --- /dev/null +++ b/html/admin/qa-bundle/docs/appendix-k-copilot-reference.html @@ -0,0 +1,2335 @@ + + + + + + + Appendix K: Copilot Reference - GIT Going with GitHub + + + + + + + + +
      +

      Appendix K: Copilot Reference

      +
      +

      Reference companion to: Chapter 16: GitHub Copilot

      +

      Authoritative source: GitHub Docs: Copilot

      +
      +
      +

      This appendix consolidates Copilot reference tables (formerly Appendix W) and Copilot model information (formerly Appendix X) into one complete reference.

      +
      +
      +

      Copilot Reference Tables

      +
      +

      Listen to Episode 40: GitHub Copilot - Complete Reference - a conversational audio overview of this chapter. Listen before reading to preview the concepts, or after to reinforce what you learned.

      +
      +

      Keyboard Shortcuts, Chat, Screen Reader Workflow, Plugin Ecosystem, and GitHub Agentic Workflows

      +
      +

      Quick-reference card for GitHub Copilot in VS Code and the broader agentic ecosystem - plugins, MCP servers, and cloud-based automation. For the Copilot lesson, see Chapter 16: GitHub Copilot. For Accessibility Agents specifically, see Appendix L: Accessibility Agents Reference.

      +
      +

      Table of Contents

      +
        +
      1. Keyboard Shortcuts
        2. +
      2. Chat Participants
        3. +
      3. Chat Slash Commands
        4. +
      4. Chat Modes
        5. +
      5. Custom Instructions - All Levels
        6. +
      6. Accessible View Workflow
        7. +
      7. Configuration Scope Reference
        8. +
      8. Instruction Priority and Conflicts
        9. +
      9. All File Types Quick Reference
        10. +
      10. VS Code Settings Reference
        11. +
      11. Diagnostics and Troubleshooting
        12. +
      12. Screen Reader Workflow - Official Guide
        13. +
      13. awesome-copilot - Plugin Ecosystem
        14. +
      14. GitHub Agentic Workflows - Agents in the Cloud
        15. +
      +

      1. Keyboard Shortcuts

      +

      Inline Suggestions (Ghost Text)

      + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + +
      ActionWindows / LinuxmacOS
      Accept entire suggestionTabTab
      Reject suggestionEscapeEscape
      Accept one word at a timeCtrl+Right ArrowCmd+Right Arrow
      Show next alternative suggestionAlt+]Option+]
      Show previous alternative suggestionAlt+[Option+[
      Open full suggestion listCtrl+EnterCmd+Enter
      Open suggestion in Accessible ViewAlt+F2Option+F2
      Insert suggestion from Accessible View at cursorCtrl+/Cmd+/
      +

      Word-by-word acceptance (Ctrl+Right Arrow) is recommended for screen reader users - it lets you review the suggestion incrementally before committing to it.

      +

      Accessible View workflow for screen reader users: Press Alt+F2 when a suggestion appears to hear the full text without streaming noise, then press Ctrl+/ to insert it directly from the Accessible View without closing the panel first.

      +

      Copilot Chat

      + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + +
      ActionWindows / LinuxmacOS
      Open Chat panelCtrl+Shift+ICmd+Shift+I
      Open inline chat (in-file, at cursor)Ctrl+ICmd+I
      Open Quick Chat (floating dialog)Ctrl+Shift+Alt+ICmd+Shift+Ctrl+I
      Send messageCtrl+EnterCmd+Enter
      Clear chat historyCtrl+LCmd+L
      +

      Accessibility

      + + + + + + + + + + + + + + + + + + + + + + + +
      ActionWindows / LinuxmacOS
      Open Accessible ViewAlt+F2Option+F2
      Open Accessible HelpAlt+HOption+H
      Close Accessible ViewEscapeEscape
      +

      Use Accessible View (Alt+F2) every time Copilot responds. It provides the complete response in a readable pane - no streaming, no live region noise, proper heading structure.

      +

      2. Chat Participants

      +

      Type these in the Copilot Chat input to give Copilot context from a specific source.

      +

      @ Participants - Scope Context

      + + + + + + + + + + + + + + + + + + + +
      ParticipantWhat It Does
      @workspaceSearches your entire VS Code workspace for relevant context
      @githubAccesses GitHub.com data - search issues, PRs, code across the platform
      @terminalProvides context from the VS Code integrated terminal
      +

      Example prompts

      +
      @workspace find all places where heading hierarchy is documented
+
+@github search community-access/accessibility-agents for issues labeled accessibility
+
+@terminal what did the last command output mean?
      +

      # Variables - Specific Context

      + + + + + + + + + + + + + + + + + + + + + + + +
      VariableWhat It Attaches
      #fileOpens a file picker - attach any file from your workspace
      #selectionAttaches your currently selected text
      #codebaseSearches the full codebase for relevant snippets
      #terminalLastCommandAttaches the last terminal command and its output
      +

      Example prompts

      +
      Review #selection for heading hierarchy violations
+
+Explain what #file does (then pick a file from the picker)
+
+What does this error mean? #terminalLastCommand
+
+Search #codebase for all screen reader navigation instructions
      +

      3. Chat Slash Commands

      +

      Type / in Copilot Chat to see the available built-in commands.

      + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + +
      CommandWhat It DoesExample
      /explainExplains the selected code or text in plain languageSelect a complex block → /explain
      /fixSuggests fixes for problems in the selected codeSelect broken code → /fix
      /testsGenerates unit tests for the selected function (code files)Select a function → /tests
      /docGenerates documentation (JSDoc, docstring) for parsed codeSelect a function → /doc
      /newScaffolds a new file or project structure/new React component for notifications
      /helpShows all available Copilot commands and participants/help
      /clearClears the current chat history/clear
      +

      Workspace management slash commands

      + + + + + + + + + + + + + + + + + + +
      CommandWhat It DoesExample
      /initAnalyzes your workspace and auto-generates a .github/copilot-instructions.md tailored to your project/init
      /savePromptSaves the current chat conversation as a reusable .prompt.md slash command fileAfter a useful exchange, type /savePrompt
      +

      Note: These are Copilot's built-in chat slash commands. Accessibility Agents adds 28 additional workspace-level slash commands from .github/prompts/ - see Appendix L for the full list.

      +

      Using Slash Commands for Documentation Work

      +
      Select a section of Markdown → /explain
+→ Copilot explains the purpose and structure of that section
+
+Select a complex code example → /explain
+→ Copilot explains what the code does in plain language
+
+Select a broken YAML template → /fix
+→ Copilot suggests what is wrong and how to correct it
      +

      4. Chat Modes

      +

      Copilot Chat has four modes. Select the current mode from the dropdown at the bottom of the Chat input area.

      + + + + + + + + + + + + + + + + + + + + + + + + + + + + +
      ModeWhat It DoesBest For
      AskConversational Q&A. Copilot explains, suggests, and answers but does not directly edit files.Questions, explanations, discussion, exploring ideas
      EditYou define a working set of files; Copilot proposes edits as a diff that you approve or reject.Targeted, controlled multi-file edits
      AgentCopilot works autonomously - it decides which files to touch, reads/writes code, runs terminal commands.Larger end-to-end tasks
      PlanCopilot writes an implementation plan first; no code is written until you approve the plan. (Public preview)Complex features where you want to validate the approach first
      +

      Screen reader note: The mode selector is in the Chat panel toolbar at the bottom. Tab through the bottom of the Chat view to find it. The current mode name is its accessible label. Press Space or Enter to open the dropdown.

      +

      Model selection is a separate control, also at the bottom of the Chat input. See Appendix X: AI Models Reference for a complete guide to choosing models.

      +

      Learning Cards: Chat Participants, Commands, and Modes

      +
      +Screen reader users + +
        +
      • Type @ in Chat to scope context (@workspace, @terminal, @github) -- the autocomplete list is keyboard-navigable with arrow keys
        • +
      • Type / for slash commands (/explain, /fix, /tests) -- each is announced with its description as you arrow through
        • +
      • The mode selector is at the bottom of the Chat panel toolbar; Tab to it, then Space or Enter to open the dropdown
        • +
      +
      + +
      +Low vision users + +
        +
      • Chat responses appear in the panel with syntax highlighting -- increase the Chat panel font size via editor.fontSize in settings
        • +
      • The @ and / trigger characters are small but the autocomplete popup that follows is large and themed to your current color scheme
        • +
      • Use Ask mode for reading explanations, Agent mode for controlled multi-file changes and autonomous tasks (Edit mode is being deprecated into Agent mode as of VS Code 1.118)
        • +
      +
      + +
      +Sighted users + +
        +
      • The @ participant picker and / command picker both show inline descriptions -- scan them visually to discover available options
        • +
      • The mode dropdown at the bottom of Chat shows the current mode name; the icon changes shape per mode for quick visual identification
        • +
      • Code blocks in Chat responses have a "Copy" and "Insert at Cursor" button in the top-right corner of each block
        • +
      +
      + + +

      5. Custom Instructions - All Levels

      +

      GitHub Copilot supports multiple ways to provide custom instructions. They differ by scope, priority, trigger mechanism, and which tools recognize them. This section documents every supported approach.

      +

      4A. Always-On Instructions - .github/copilot-instructions.md

      +

      What it is: The primary VS Code Copilot instruction file. Content is automatically included in every chat request and inline suggestion context - you never need to invoke it.

      +

      When to use: Project-wide conventions everyone on the team should follow: coding standards, documentation style, commit message format, tone, accessibility requirements.

      +

      Location: .github/copilot-instructions.md (fixed path; workspace-level only)

      +

      Format: Plain Markdown - no frontmatter, no special syntax required.

      +
      # Copilot Instructions for accessibility-agents
+
+## Accessibility Standards
+- Include semantic HTML elements in generated markup
+- Never use color as the only indicator of meaning
+- Ensure all interactive elements are keyboard accessible
+
+## Documentation Style
+- Write for screen reader users first
+- Use active voice and imperative mood
+- Never skip heading levels (H1 → H2 → H3 only)
+
+## Commit Message Format
+- Conventional commits: `type(scope): description`
+- Types: feat, fix, docs, style, refactor, test, chore
+- Reference issues: "Fixes #123"
+
+## Code Quality
+- Prefer explicit over implicit
+- Write self-documenting code; add comments only where logic is non-obvious
+- Error handling must be intentional - no silent catch blocks
      +

      Auto-generate with /init

      +
        +
      1. Open Copilot Chat
        2. +
      2. Type /init
        3. +
      3. VS Code analyzes your workspace and generates a tailored copilot-instructions.md
        4. +
      4. Review and edit the result before committing
        5. +
      +

      4B. Always-On Instructions - AGENTS.md (Multi-Tool / Monorepo)

      +

      What it is: An open standard instruction file recognized by multiple AI tools - GitHub Copilot, Claude Code, Gemini CLI, and others. Use this instead of copilot-instructions.md when you want one instruction file that works across all AI coding assistants.

      +

      When to use: Multi-tool teams, or when you want monorepo-level granularity where different subdirectories have different rules.

      +

      Location: AGENTS.md at the workspace root. For monorepos, also supported nested in subdirectories (closest file to the current directory wins).

      +
      repo-root/
+  AGENTS.md               ← applies everywhere
+  frontend/
+    AGENTS.md             ← overrides root for frontend/ and below
+  backend/
+    AGENTS.md             ← overrides root for backend/ and below
      +

      Enable nested files: In VS Code settings, set chat.useNestedAgentsMdFiles: true.

      +

      Enable/disable AGENTS.md: Set chat.useAgentsMdFile: true (default: on).

      +

      Format: Identical to copilot-instructions.md - plain Markdown, no frontmatter.

      +

      Rule: Choose either copilot-instructions.md OR AGENTS.md for your project - not both.

      +

      4C. Always-On Instructions - CLAUDE.md (Cross-Tool Compatibility)

      +

      What it is: Instructions file originally from Claude Code that VS Code Copilot also recognizes. Useful when your team uses both.

      +

      When to use: Mixed AI tool environments where Claude Code and VS Code Copilot are both used. Uses the same format as the other always-on files.

      +

      Supported locations

      + + + + + + + + + + + + + + + + + + + + + + + + + + + + +
      FileScopeCommitted?
      CLAUDE.md (workspace root)All requests in workspaceYes
      .claude/CLAUDE.mdAll requests in workspaceYes
      CLAUDE.local.md (workspace root)All requests; local onlyNo - gitignored
      ~/.claude/CLAUDE.mdAll workspaces; user-levelPersonal
      +

      Enable/disable: Set chat.useClaudeMdFile: true (default: on).

      +

      Claude Rules format (for .claude/rules/ and ~/.claude/rules/):

      +

      Use .instructions.md files under .claude/rules/ using paths: instead of applyTo: for glob matching:

      +
      description: "Python coding standards"
+paths: ["**/*.py"]
+
+Follow PEP 8. Use type hints on all function signatures.
+Write docstrings for all public functions and classes.
      +

      4D. Conditional / Scoped Instructions - .instructions.md

      +

      What it is: Instructions that apply only when specific file types or folders are involved in the chat. More targeted than always-on instructions.

      +

      When to use: Language-specific rules (Python style, TypeScript patterns), framework conventions, folder-specific standards (docs/, tests/, src/api/).

      +

      Locations

      + + + + + + + + + + + + + + + + + + + +
      ScopeLocation
      Workspace.github/instructions/*.instructions.md
      Additional workspace foldersConfigure with chat.instructionsFilesLocations
      User / PersonalVS Code profile folder *.instructions.md
      +

      Frontmatter

      +
      name: "Display Name"          # Optional - shown in UI and diagnostics; defaults to filename
+description: "Use when..."    # Optional - enables on-demand matching; make keyword-rich
+applyTo: "**/*.py"            # Optional glob - auto-attach when matching files are in context
      +

      applyTo glob patterns

      +
      applyTo: "**"                            # Always included (careful - applies to everything)
+applyTo: "**/*.py"                       # All Python files
+applyTo: "**/*.{ts,tsx}"                 # TypeScript and TSX
+applyTo: "docs/**"                       # Everything under docs/
+applyTo: ["src/**", "lib/**"]            # Multiple patterns - OR logic
+applyTo: "**/*.test.{js,ts}"            # Test files only
+applyTo: ".github/ISSUE_TEMPLATE/**"    # Issue template files only
      +

      How files are triggered

      + + + + + + + + + + + + + + + + + + + +
      Discovery ModeHow It Works
      Automatic (via applyTo)Instruction loads automatically when a matching file is in the chat context
      On-demand (via description)Agent detects from the description that this instruction is relevant to the task
      ManualUser selects "Add Context → Instructions" in the Chat panel
      +

      Example - test file conventions

      +
      name: "Test File Standards"
+description: "Use when writing, generating, or reviewing test files. Covers test structure, naming, and coverage expectations."
+applyTo: "**/*.test.{js,ts}"
+
+# Test Standards
+
+- Use `describe`/`it` structure (not `test()` directly)
+- Test names must describe behavior: "returns null when input is empty" not "test case 1"
+- Each `it` tests exactly one behavior
+- Include at least one edge case and one error case per function
+- Avoid snapshot tests for logic; use explicit assertions
+- Mock external dependencies; do not test third-party libraries
      +

      Create an instructions file

      +
        +
      • Ctrl+Shift+P → "Chat: New Instructions File" → choose scope (Workspace or User)
        • +
      • Or create the file manually in .github/instructions/
        • +
      +

      4E. Organization-Level Instructions (GitHub Enterprise and Teams)

      +

      What it is: Organization administrators define custom instructions that apply to all repositories in the organization. Every team member automatically gets these instructions added to their Copilot context.

      +

      Priority: Lowest - workspace and user instructions both override these. However, they are additive - they are appended to, not replacing, other instructions.

      +

      Requirements

      +
        +
      • GitHub Enterprise or Teams plan with Copilot enabled
        • +
      • Admin configures instructions in organization settings on GitHub.com
        • +
      • Each user must enable discovery in VS Code:
        • +
      +
      // User settings.json
+{
+  "github.copilot.chat.organizationInstructions.enabled": true
+}
      +

      Use for: Organization-wide coding standards, security policies, legal disclaimers (open source license obligations), toolchain conventions.

      +

      4F. Settings-Based Instructions (Deprecated - Use Files Instead)

      +
      +

      Note: These settings-based instructions are deprecated and may be removed in a future VS Code release. For new work, use copilot-instructions.md or .instructions.md files.

      +
      +

      VS Code settings can inject instructions for specific task types:

      +
      // settings.json (workspace .vscode/settings.json or user settings)
+{
+  "github.copilot.chat.codeGeneration.instructions": [
+    { "text": "Always add JSDoc comments to exported functions." },
+    { "file": ".github/instructions/code-style.instructions.md" }
+  ],
+  "github.copilot.chat.testGeneration.instructions": [
+    { "text": "Use describe/it structure. Include edge cases." }
+  ],
+  "github.copilot.chat.reviewSelection.instructions": [
+    { "text": "Check for WCAG 2.2 Level AA compliance in HTML markup." }
+  ],
+  "github.copilot.chat.commitMessageGeneration.instructions": [
+    { "text": "Use conventional commits: type(scope): description" }
+  ]
+}
      +

      Each setting accepts an array of { text: "..." } (inline) or { file: "relative/path.md" } (from file).

      +

      4G. Comparison - When to Use Each Approach

      + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + +
      ApproachScopeAlways-on?Multi-tool?Best For
      copilot-instructions.mdWorkspaceYesVS Code onlyPrimary project instructions
      AGENTS.mdWorkspace + monorepoYesAll AI toolsMulti-tool teams or large monorepos
      CLAUDE.mdWorkspace + userYesCopilot + ClaudeClaude Code compatibility
      .instructions.mdWorkspace or userConditionalVS Code onlyScoped rules for file types
      Organization settingAll repos in orgYesGitHub CopilotOrg-wide policy
      Settings-basedWorkspace or userPer-taskVS Code onlyDeprecated - avoid for new work
      +

      Learning Cards: Custom Instructions

      +

      Screen reader users:

      +
        +
      • The three-level scope hierarchy (Organization, Workspace, User) means instructions can come from multiple places -- use Chat Diagnostics (gear icon in Chat header) to list every loaded instruction file and its source
        • +
      • .github/copilot-instructions.md is always-on and requires no frontmatter -- just write plain Markdown; screen readers read the source file like any other Markdown document
        • +
      • .instructions.md files use YAML frontmatter with applyTo globs -- the frontmatter is the first few lines between --- delimiters; arrow through carefully to verify syntax
        • +
      +

      Low-vision users:

      +
        +
      • The Diagnostics panel (Chat gear, then Diagnostics) lists loaded files in a scrollable pane -- increase font size in VS Code settings if the file paths are hard to read
        • +
      • YAML frontmatter is indentation-sensitive -- enable VS Code's indentation guides (editor.guides.indentation) and use a high-contrast theme so the guide lines are visible
        • +
      • The /init command auto-generates copilot-instructions.md from your workspace -- review the generated file in your editor at your preferred zoom before committing
        • +
      +

      Sighted users:

      +
        +
      • The comparison table above maps each instruction type to its scope, always-on status, and multi-tool compatibility -- scan the "Best For" column to choose the right approach
        • +
      • Look in .github/instructions/ for scoped instruction files and .github/copilot-instructions.md for always-on instructions -- both are plain Markdown files you can edit directly
        • +
      • Use the applyTo glob pattern in .instructions.md frontmatter to limit when instructions activate -- "**/*.py" for Python-only rules, "docs/**" for documentation-only rules
        • +
      +

      6. Accessible View Workflow

      +

      Copilot Chat responses stream in token by token, which can fragment screen reader announcements. Accessible View (Alt+F2) gives you a complete, static, properly structured version of the response.

      +

      Recommended Workflow - Every Copilot Interaction

      +
      1. Open Copilot Chat: Ctrl+Shift+I
+2. Type your prompt
+3. Press Ctrl+Enter to send
+4. Press Alt+F2 to open Accessible View (open immediately - no need to wait)
+5. Follow as the response streams in the Accessible View in real-time
+6. Read or re-read any part with Arrow keys at your own pace
+7. Press Escape to close Accessible View
      +
      +

      VS Code December 2025: The Accessible View now streams dynamically. You can open it immediately after sending a prompt and follow the response as it arrives - no need to wait for the response to finish before pressing Alt+F2.

      +
      +

      Why Accessible View Is Better for Screen Reader Users

      + + + + + + + + + + + + + + + + + + + + + + + + + + + +
      Without Accessible ViewWith Accessible View (Alt+F2)
      Responses announced in fragments as tokens arriveFull, complete response in one readable pane
      Live region updates may interrupt or overlapNo streaming, no live region noise
      Difficult to re-read specific sectionsNavigate with Up/Down Arrow at your own pace
      Context can be lost in streamingFull context preserved from start to finish
      Code blocks may run togetherCode blocks formatted as <pre> elements, line-by-line
      +

      Screen Reader Navigation in Accessible View

      +

      NVDA / JAWS

      +
        +
      • Up/Down Arrow - read line by line
        • +
      • Ctrl+Home - jump to start
        • +
      • H - navigate by headings (if response has sections)
        • +
      • Escape - close Accessible View, return to Chat
        • +
      +

      VoiceOver

      +
        +
      • VO+Shift+Down - interact with the Accessible View content
        • +
      • Down Arrow - read line by line
        • +
      • VO+Escape - stop interacting
        • +
      • Escape - close Accessible View
        • +
      +

      Accessible View for Inline Suggestions

      +

      When a multi-line ghost text suggestion appears in the editor:

      +
      1. Do not accept immediately
+2. Press Alt+F2
+3. Accessible View shows: "Suggestion: [full text]"
+4. Read the complete suggestion at your own pace
+5. Press Escape to close
+6. Press Tab to accept, or Escape to reject
      +

      This is especially important for multi-line suggestions where ghost text is hard to review incrementally.

      +

      Accessible View for Code Blocks

      +
        +
      • Code blocks appear inside <pre> elements in Accessible View
        • +
      • Screen readers announce "code block" or "pre-formatted text" at the start
        • +
      • Each line is on its own line (not run together)
        • +
      • Indentation is preserved
        • +
      +

      Learning Cards: Accessible View Workflow

      +
      +Screen reader users + +
        +
      • Press Alt+F2 immediately after sending a prompt -- Accessible View now streams dynamically so you can follow along in real time
        • +
      • Navigate Chat responses with Up/Down Arrow; headings, code blocks, and lists are structurally intact in the view
        • +
      • For inline suggestions, press Alt+F2 to read the full ghost text, then Ctrl+/ to insert it directly from the Accessible View
        • +
      +
      + +
      +Low vision users + +
        +
      • Accessible View renders Chat responses as a static, scrollable pane -- easier to read at high zoom than the streaming Chat panel
        • +
      • Code blocks in Accessible View preserve indentation and syntax -- pair with a high-contrast theme for maximum readability
        • +
      • Ctrl+Home jumps to the start of the response; Ctrl+End to the end -- useful for long multi-section outputs
        • +
      +
      + +
      +Sighted users + +
        +
      • Even with full vision, Accessible View (Alt+F2) is useful for reviewing long Copilot responses without streaming distraction
        • +
      • Code blocks are rendered as <pre> elements with line breaks preserved -- easy to scan and compare against your editor
        • +
      • Press Escape to close Accessible View and return focus to the Chat input for your next prompt
        • +
      +
      + + +

      7. Configuration Scope Reference

      +

      Every Copilot customization file lives at one of three scopes. VS Code combines all matching files from all scopes - it is additive, not winner-takes-all.

      +

      Workspace (Repository) - Team-Shared

      +

      Files committed to your repository. Everyone who clones the repo gets them.

      + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + +
      File TypeLocation
      Always-on instructions.github/copilot-instructions.md
      Always-on (multi-tool)AGENTS.md (root), <folder>/AGENTS.md (nested)
      Always-on (Claude compat)CLAUDE.md, .claude/CLAUDE.md
      Local only (not committed)CLAUDE.local.md, .claude/settings.local.json
      Scoped instructions.github/instructions/*.instructions.md
      Claude rules (scoped).claude/rules/*.instructions.md
      Custom agents.github/agents/*.agent.md
      Prompts / slash commands.github/prompts/*.prompt.md
      Agent skills.github/skills/<name>/SKILL.md
      Hooks (team-shared).github/hooks/*.json
      Claude hooks/settings.claude/settings.json
      Personal preferences.github/agents/preferences.md (gitignored)
      +

      User / Personal - Follows You Across Workspaces

      +

      Files in your VS Code profile folder. Syncs with Settings Sync. Available in every workspace you open.

      +

      Path on Windows: C:\Users\<you>\AppData\Roaming\Code - Insiders\User\prompts\ +Path on macOS: ~/Library/Application Support/Code - Insiders/User/prompts/

      + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + +
      File TypeLocation
      Instructions<profile>/prompts/*.instructions.md
      Agents<profile>/prompts/*.agent.md
      Prompts<profile>/prompts/*.prompt.md
      Claude instructions~/.claude/CLAUDE.md
      Claude rules~/.claude/rules/*.instructions.md
      Claude settings~/.claude/settings.json
      Agent skills~/.copilot/skills/<name>/, ~/.agents/skills/<name>/, ~/.claude/skills/<name>/
      +

      Organization - GitHub-Configured (Enterprise/Teams)

      +

      Configured by administrators in GitHub organization settings. Automatically applied to all organization members.

      +
        +
      • Enable discovery: github.copilot.chat.organizationInstructions.enabled: true
        • +
      • Lowest priority - workspace and user instructions override when there is a conflict
        • +
      +

      8. Instruction Priority and Conflicts

      +

      When multiple instruction sources give conflicting guidance, VS Code uses this priority order:

      +
      1. Personal / User-level    - HIGHEST - overrides all others
+2. Workspace / Repository   - middle priority
+3. Organization-level       - LOWEST - overridden by workspace and user
      +

      Important: This priority applies to conflicts. All non-conflicting instructions from all scopes are combined and sent together. More instructions is not a problem - Copilot handles them additively.

      +

      How Instructions Are Combined

      +

      Say you have:

      +
        +
      • Organization: "Use British English spellings"
        • +
      • Workspace: "Use TypeScript strict mode"
        • +
      • User: "Use British English spellings - but use Z spellings (organize, not organise) for technical terms"
        • +
      +

      Result: Copilot follows TypeScript strict mode (from workspace), British English (from org), AND the Z-spelling override (from user, which overrides the org instruction on that specific point).

      +

      Priority Within the Same Scope

      +

      Within a single scope (e.g., workspace), all matching instructions files are combined with no inherent priority. If two workspace-level .instructions.md files contradict each other, the behavior is undefined - avoid conflicting workspace instructions.

      +

      9. All File Types Quick Reference

      + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + +
      PurposeFile Name PatternLocationHow It Activates
      Always-on instructionscopilot-instructions.md.github/Automatic - every request
      Always-on (multi-tool)AGENTS.mdRepo root or subfoldersAutomatic - every request
      Always-on (Claude compat)CLAUDE.mdRepo root, .claude/, ~/.claude/Automatic - every request
      Scoped instructions*.instructions.md.github/instructions/, profile folderAuto (via applyTo) or on-demand
      Claude scoped rules*.instructions.md.claude/rules/, ~/.claude/rules/Auto (via paths:) or on-demand
      Custom agents*.agent.md.github/agents/, profile folder@agent-name in Chat
      Prompt / slash command*.prompt.md.github/prompts/, profile folder/command-name in Chat
      Agent skillSKILL.md in named folder.github/skills/<name>/, profile folder/skill-name or auto on-demand
      Lifecycle hook*.json.github/hooks/, .claude/settings*.jsonAutomatic at lifecycle events
      Personal preferencespreferences.md.github/agents/ (gitignored)Read by agents when mentioned
      +

      Create any new customization file

      +

      Ctrl+Shift+P → "Chat: New Instructions File" (or "New Prompt File", "New Agent File")

      +

      10. VS Code Settings Reference

      +

      All Copilot customization-related settings. Set in VS Code Settings (Ctrl+,) or settings.json.

      +

      Core Instruction Settings

      + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + +
      SettingDefaultDescription
      chat.instructionsFilesLocations-Array of additional folder paths to search for *.instructions.md files
      chat.useAgentsMdFiletrueEnable/disable AGENTS.md recognition
      chat.useClaudeMdFiletrueEnable/disable CLAUDE.md/CLAUDE.local.md recognition
      chat.useNestedAgentsMdFilesfalseEnable subfolder AGENTS.md hierarchy for monorepos
      chat.includeApplyingInstructionstrueApply instructions files whose applyTo pattern matches current files
      chat.includeReferencedInstructionstrueApply instruction files referenced via Markdown links in chat
      chat.restoreLastPanelSessiontrueRestore the previous chat session when VS Code starts; set to false to always start with an empty Chat
      chat.useAgentSkillsfalseEnable Agent Skills (experimental) - allows .github/skills/<name>/SKILL.md bundles to be discovered and invoked
      +

      Organization Instructions

      + + + + + + + + + + + + + +
      SettingDefaultDescription
      github.copilot.chat.organizationInstructions.enabledfalseEnable discovery of organization-level custom instructions
      +

      Deprecated Task-Specific Instructions

      +
      +

      Prefer file-based instructions over these settings for new work.

      +
      + + + + + + + + + + + + + + + + + + + + + + + +
      SettingWhat It Augments
      github.copilot.chat.codeGeneration.instructionsAll code generation
      github.copilot.chat.testGeneration.instructionsTest file generation
      github.copilot.chat.reviewSelection.instructionsCode review via Chat
      github.copilot.chat.commitMessageGeneration.instructionsGit commit messages
      +

      Each accepts an array with items: { "text": "..." } (inline) or { "file": "relative/path" } (from file).

      +

      Settings Sync

      +

      To sync your personal prompts, instructions, and agents across devices:

      +
        +
      1. Ctrl+Shift+P → "Settings Sync: Turn On"
        2. +
      2. Ctrl+Shift+P → "Settings Sync: Configure"
        3. +
      3. Check "Prompts and Instructions"
        4. +
      +

      Your personal *.instructions.md, *.agent.md, and *.prompt.md files will sync to all signed-in VS Code instances.

      +

      11. Diagnostics and Troubleshooting

      +

      View All Loaded Customizations

      +

      To see which instruction files, agents, prompts, and skills are currently loaded - and check for errors:

      +
        +
      1. Configure Chat Gear: Click the gear () icon in the Copilot Chat header → "Diagnostics"
        2. +
      2. Right-click method: Right-click in the Chat view → "Diagnostics"
        3. +
      +

      The Diagnostics panel shows:

      +
        +
      • All agents found and whether they loaded successfully
        • +
      • All prompt/instruction files and their source (workspace vs user vs organization)
        • +
      • All skills and their discovery status
        • +
      • Any parse errors or invalid frontmatter
        • +
      +

      Common Issues

      +

      copilot-instructions.md not being followed

      +
        +
      1. Confirm the file is at exactly .github/copilot-instructions.md (relative to workspace root)
        2. +
      2. Check the file is plain Markdown with no frontmatter syntax errors
        3. +
      3. Open Diagnostics to confirm it appears in the loaded files list
        4. +
      4. Some instructions work better with specific phrasing; use imperative mood ("Always use...")
        5. +
      +

      .instructions.md file not loading automatically

      +
        +
      1. Verify chat.includeApplyingInstructions is not set to false
        2. +
      2. Check the applyTo glob - test with "**" temporarily to confirm the file loads at all
        3. +
      3. Confirm the file is in .github/instructions/ or a folder listed in chat.instructionsFilesLocations
        4. +
      4. File extension must be .instructions.md exactly - not .md, not .instruction.md
        5. +
      +

      Custom agent (@agent-name) not appearing

      +
        +
      1. File must be named <agent-name>.agent.md and placed in .github/agents/
        2. +
      2. Check YAML frontmatter for syntax errors - use a YAML validator
        3. +
      3. Confirm user-invocable is not set to false (which hides it from the picker)
        4. +
      4. Run Ctrl+Shift+P → "Reload Window" after any changes to agent files
        5. +
      +

      Slash command (/command) not appearing

      +
        +
      1. File must be at .github/prompts/<command-name>.prompt.md
        2. +
      2. Extension must be .prompt.md exactly
        3. +
      3. Reload VS Code: Ctrl+Shift+P → "Reload Window"
        4. +
      +

      Instructions from different files conflicting

      +
        +
      1. Open Diagnostics to see all loaded instruction files
        2. +
      2. Remove or edit conflicting instructions - they are not automatically de-duplicated
        3. +
      3. User-level instructions override workspace instructions for the same topic
        4. +
      +

      chat.instructionsFilesLocations not working

      +
        +
      • Path must be a folder path, not a file path
        • +
      • Use forward slashes or escaped backslashes
        • +
      • Relative paths are relative to the workspace root
        • +
      +

      Quick Reference Card

      +

      Opening Copilot

      + + + + + + + + + + + + + + + + + + + + + + + +
      WhatWindows / LinuxmacOS
      Chat panelCtrl+Shift+ICmd+Shift+I
      Inline chat (in file)Ctrl+ICmd+I
      Quick Chat (floating)Ctrl+Shift+Alt+ICmd+Shift+Ctrl+I
      +

      Reading Copilot Responses

      + + + + + + + + + + + + + + + + + + + +
      WhatHow
      Complete response (streams live in Accessible View)Alt+F2 - open anytime, including while response is still generating
      Close Accessible ViewEscape
      Read current inline suggestionAlt+F2 while ghost text is showing
      +

      Accepting/Rejecting Suggestions

      + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + +
      WhatWindows / LinuxmacOS
      AcceptTabTab
      RejectEscapeEscape
      Accept word by word (recommended)Ctrl+Right ArrowCmd+Right Arrow
      Next suggestionAlt+]Option+]
      Previous suggestionAlt+[Option+[
      Open full suggestion listCtrl+EnterCmd+Enter
      Open suggestion in Accessible ViewAlt+F2Option+F2
      Insert from Accessible View at cursorCtrl+/Cmd+/
      +

      Instructions Management

      + + + + + + + + + + + + + + + + + + + + + + + + + + + +
      WhatHow
      Auto-generate instructions from workspaceType /init in Chat
      New instructions fileCtrl+Shift+P → "Chat: New Instructions File"
      New prompt/slash command fileCtrl+Shift+P → "Chat: New Prompt File"
      Configure instructionsCtrl+Shift+P → "Chat: Configure Instructions"
      View all loaded files and errorsChat gear → Diagnostics
      +

      12. Screen Reader Workflow - Official Guide

      +
      +

      Source: accessibility.github.com/documentation/guide/github-copilot-vsc/

      +

      Contributors: @mlama007, zersiax | Community: GitHub Accessibility Discussions

      +
      +

      Prerequisites

      +
        +
      • VS Code with GitHub Copilot Chat extension installed
        • +
      • A GitHub account with Copilot access (Free tier or paid)
        • +
      • A screen reader (NVDA recommended for this guide)
        • +
      +

      Step 1: Enable VS Code Screen Reader Mode

      +
        +
      1. Press Shift+Alt+F1 to toggle Screen Reader Accessibility Mode
        2. +
      2. Or use Command Palette: Ctrl+Shift+P → "Toggle Screen Reader Accessibility Mode"
        3. +
      3. VS Code announces: "Screen Reader Accessibility Mode enabled"
        4. +
      +

      When Screen Reader Mode is on, VS Code changes how it announces suggestions (full text instead of streaming), adjusts live regions, and enables accessible navigation patterns throughout the editor.

      + +
        +
      1. Open Settings: Ctrl+,
        2. +
      2. Search "accessibility signals"
        3. +
      3. Enable the Copilot-specific signals:
        4. +
      + + + + + + + + + + + + + + + + + + + + + + + +
      Signal SettingWhat It Signals
      accessibility.signals.lineHasInlineSuggestionA suggestion is available on the current line
      accessibility.signals.chatRequestSentYour prompt has been sent
      accessibility.signals.chatResponsePendingCopilot is generating a response
      accessibility.signals.chatResponseReceivedResponse is complete and ready to read
      +

      Recommended JSON config for Copilot accessibility signals:

      +
      {
+  "accessibility.signals.lineHasInlineSuggestion": "on",
+  "accessibility.signals.chatRequestSent": "on",
+  "accessibility.signals.chatResponsePending": "auto",
+  "accessibility.signals.chatResponseReceived": "on"
+}
      +

      Step 3: Official Shortcut Table (from accessibility.github.com)

      +

      This is the complete table of Copilot screen reader shortcuts as published by the GitHub Accessibility team:

      + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + +
      ActionShortcut
      Accept Inline SuggestionTab
      Dismiss Inline SuggestionEscape
      Show next suggestion in Suggestions PanelAlt+]
      Show previous suggestion in Suggestions PanelAlt+[
      Open GitHub Copilot Suggestions (loads ~10 suggestions side by side)Ctrl+Enter
      Opens suggestion in Accessible View panelAlt+F2
      Inserts suggestion from Accessible View at cursorCtrl+/
      Opens Inline Chat (in-file, at cursor)Ctrl+I
      Opens dedicated Chat viewCtrl+Shift+I
      + +

      The screen reader-optimized workflow for every inline suggestion

      +
      1. Type your code or documentation
+2. Copilot generates a suggestion (audio cue sounds if enabled)
+3. DO NOT press Tab immediately
+4. Press Alt+F2 - Accessible View opens with the full suggestion text
+5. Read the suggestion at your own pace with Arrow keys
+6. Decision:
+   a. Insert it: Press Ctrl+/ - suggestion is inserted at cursor position
+   b. Skip it: Press Escape to close Accessible View, then Escape again to dismiss
+   c. See alternatives: Close Accessible View, press Alt+] for next suggestion
      +

      This workflow avoids the streaming announcement problem (where suggestions are read out in fragments as tokens arrive) and gives you full, uninterrupted access to the suggestion text before committing.

      + +
      1. Open Chat: Ctrl+Shift+I
+2. Type your prompt, press Ctrl+Enter to send
+3. Press Alt+F2 - Accessible View opens immediately; the response streams live into it
+4. Navigate with Arrow keys - no streaming noise, follow along in real-time
+5. Headings, code blocks, and lists are fully structured
+6. Press Escape to close - focus returns to Chat input
      +

      Reading the Suggestions Panel (Ctrl+Enter)

      +

      Pressing Ctrl+Enter opens a Suggestions Panel - a separate editor tab that shows up to 10 alternative suggestions simultaneously. This is useful when the default suggestion isn't quite right and you want to compare options.

      +
      1. Ctrl+Enter - opens "GitHub Copilot" editor tab
+2. Screen Reader Mode is active: navigate with Browse Mode
+3. H key to navigate headings (each suggestion may be under a heading)
+4. Press Alt+F2 on a focused suggestion to read it in Accessible View
+5. Tab to "Accept" button for a suggestion you want to use
+6. Close the tab when done (Ctrl+W)
      +

      Resources

      + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + +
      ResourceURL
      VS Code Copilot Cheat Sheetcode.visualstudio.com/docs/copilot/reference/copilot-vscode-features
      VS Code Accessibility Featurescode.visualstudio.com/docs/editor/accessibility
      GitHub Accessibility Discussionsgithub.com/orgs/community/discussions/categories/accessibility
      Official screen reader guideaccessibility.github.com/documentation/guide/github-copilot-vsc/
      Optimizing Copilot with custom instructions (accessibility)accessibility.github.com/documentation/guide/copilot-instructions/
      Getting started with custom agents for accessibilityaccessibility.github.com/documentation/guide/getting-started-with-agents/
      +

      Learning Cards: Screen Reader Copilot Workflow

      +
      +Screen reader users + +
        +
      • The golden rule: never accept a suggestion with Tab before reviewing it -- press Alt+F2 first, read it, then Ctrl+/ to insert
        • +
      • Enable the four Copilot audio signals (inline suggestion, request sent, response pending, response received) for non-verbal status awareness
        • +
      • Ctrl+Enter opens a Suggestions Panel with up to 10 alternatives -- navigate with H for headings, then Tab to the Accept button
        • +
      +
      + +
      +Low vision users + +
        +
      • Inline ghost text is typically rendered in a muted color -- if hard to see, rely on the lineHasInlineSuggestion audio signal instead
        • +
      • The Suggestions Panel (Ctrl+Enter) shows alternatives in a full editor tab at your current font size and theme
        • +
      • Chat responses are easier to read in Accessible View than in the streaming panel, especially at high zoom
        • +
      +
      + +
      +Sighted users + +
        +
      • Ghost text appears in gray after your cursor -- press Tab to accept, Escape to dismiss, or Alt+] / Alt+[ for alternatives
        • +
      • The Chat panel shows response progress with a typing indicator; the Accessible View shows the same content without animation
        • +
      • Use the Resources table above to bookmark the official accessibility guides for Copilot configuration and agent setup
        • +
      +
      + + +

      13. awesome-copilot - Plugin Ecosystem

      +

      awesome-copilot is a GitHub repository (github/awesome-copilot) - not a VS Code Marketplace extension. It is GitHub's curated ecosystem of Copilot plugins, prompts, instructions, agents, skills, and hooks that can be shared and discovered by anyone.

      +
      +

      Stars: 21.6k | Forks: 2.5k | Contributors: 247+ | Repository: github.com/github/awesome-copilot

      +
      +

      Repository Structure

      + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + +
      DirectoryContents
      prompts/Community-contributed .prompt.md slash command files
      instructions/Community-contributed .instructions.md guidance files
      agents/Community-contributed .agent.md agent definitions
      plugins/Community-contributed plugin packages (MCP and CLI)
      skills/Community-contributed SKILL.md bundles
      hooks/Community-contributed lifecycle hook .json configs
      cookbook/Worked examples and usage patterns
      +

      LLM discovery: https://github.github.io/awesome-copilot/llms.txt - a machine-readable index of all available resources.

      +

      The /plugin Command - Browse and Install from Chat

      +

      The easiest way to explore awesome-copilot from VS Code:

      +
        +
      1. Open Copilot Chat (Ctrl+Shift+I)
        2. +
      2. Type /plugin and press Enter
        3. +
      3. Copilot Chat opens an interactive plugin marketplace browser
        4. +
      4. Browse plugins by category, read descriptions, and install with a single command
        5. +
      +

      Key plugins available via /plugin

      + + + + + + + + + + + + + + + + + + + +
      PluginWhat It Does
      Awesome CopilotThe meta-plugin - browse and install any resource from the full ecosystem
      Copilot SDKOfficial SDK for C#, Go, Node.js, and Python development patterns
      Partners20+ partner agents from Azure, JetBrains, MongoDB, and others
      +

      CLI Plugin Installation

      +

      From any terminal with GitHub CLI (gh) installed:

      +
      # Browse the marketplace
+gh copilot plugin marketplace list
+
+# Add the awesome-copilot collection
+gh copilot plugin marketplace add github/awesome-copilot
+
+# Install a specific plugin
+gh copilot plugin install @awesome-copilot/accessibility-toolkit
+
+# List what you have installed
+gh copilot plugin list
      +

      MCP Server Integration (Docker required)

      +

      awesome-copilot also ships as an MCP (Model Context Protocol) Server - a Docker-based tool server that extends Copilot with additional capabilities beyond file-based customizations.

      +

      Install in VS Code by clicking the button at https://aka.ms/awesome-copilot/mcp/vscode, or add manually to settings.json:

      +
      {
+  "mcp": {
+    "servers": {
+      "awesome-copilot": {
+        "type": "stdio",
+        "command": "docker",
+        "args": [
+          "run", "-i", "--rm",
+          "ghcr.io/github/awesome-copilot-mcp:latest"
+        ]
+      }
+    }
+  }
+}
      +

      Also available for: VS Code Insiders and Visual Studio.

      +
      +

      Screen reader note: The install buttons on the awesome-copilot page are standard links. Navigate with K in Browse Mode to find them. Each is labeled with the target IDE.

      +
      +

      awesome-copilot vs. Accessibility Agents

      + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + +
      FeatureAccessibility Agents (.github/agents/)awesome-copilot
      ScopeYour repo and forkCommunity-wide ecosystem
      DistributionClone the repo; agents travel with itPlugin marketplace - install on demand
      CustomizationEdit .agent.md files directlyUse as-is or fork and modify
      StorageYour version-controlled repositoryGitHub-hosted public repository
      Best forProject-specific workflowsReusable templates and cross-project tools
      +

      14. GitHub Agentic Workflows - Agents in the Cloud

      +
      +

      Status: Technical Preview - GitHub Agentic Workflows entered technical preview on February 13, 2026. As of May 2026 the feature remains in active development and preview; changes to the API and workflow format are ongoing. Use with careful human supervision. See the official documentation and source repository (open source, MIT).

      +

      Workshop note: Facilitators will confirm current availability and any breaking changes at the workshop.

      +
      +

      GitHub Agentic Workflows run AI coding agents as part of GitHub Actions pipelines - no VS Code, no local setup required. The key differentiator: you write automation goals in plain Markdown, and the gh aw CLI compiles them into standard GitHub Actions workflows. The AI agent interprets your natural language description and executes the task.

      +

      What This Enables

      + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + +
      Workflow CategoryTriggerExample
      Issue & PR Managementissues: openedAuto-triage, label, and assign new issues
      Continuous Documentationpush to mainKeep README and docs in sync with code changes
      Metrics & Analyticsschedule: dailyDaily status report posted as a new issue
      Quality & Testingpull_requestCI failure analysis posted as PR comment
      Continuous Improvementschedule: weeklyAutomated refactoring and code simplification PRs
      Multi-Repositoryworkflow_dispatchSync features and track changes across repos
      +

      Browse 50+ community-built workflows at Peli's Agent Factory.

      +

      How It Works

      +

      The gh aw CLI (a gh extension) compiles .md workflow files into .lock.yml GitHub Actions workflows:

      +
      .github/workflows/daily-report.md  ← you write this (Markdown + frontmatter)
+        ↓  gh aw compile
+.github/workflows/daily-report.lock.yml  ← generated, runs as standard GitHub Actions
      +

      The AI agent (GitHub Copilot, Claude, or OpenAI Codex) reads your repository context and the natural language instructions, then performs the task using the GitHub MCP Server and other available tools.

      +

      Workflow Format - Markdown with Frontmatter

      +

      Unlike standard GitHub Actions (YAML), agentic workflows are Markdown files:

      +
      on:
+  schedule: daily
+permissions:
+  contents: read
+  issues: read
+  pull-requests: read
+safe-outputs:
+  create-issue:
+    title-prefix: "[team-status] "
+    labels: [report, daily-status]
+    close-older-issues: true
+
+## Daily Issues Report
+
+Create an upbeat daily status report for the team as a GitHub issue.
+
+## What to include
+
+- Recent repository activity (issues, PRs, discussions, releases, code changes)
+- Progress tracking, goal reminders and highlights
+- Project status and recommendations
+- Actionable next steps for maintainers
      +

      The body is natural language - describe what you want the AI agent to do. The frontmatter controls triggers, permissions, and what write operations are allowed.

      +

      Key Frontmatter Properties

      + + + + + + + + + + + + + + + + + + + + + + + + + + + +
      PropertyPurpose
      on: schedule: dailyRuns once per day (also: weekly, cron expressions, issues: opened, pull_request)
      on: issue_comment: createdTrigger from a comment command in an issue or PR
      on: workflow_dispatchManual run via the Actions tab "Run workflow" button
      permissions:Read-only scopes by default - only request what you need
      safe-outputs:Pre-approved write operations (e.g., create-issue, pr-comment) - the security guardrail
      +

      Security Model - "Safe Outputs"

      +

      Workflows run read-only by default with sandboxed execution, network isolation, and SHA-pinned dependencies. Write operations require explicit declaration in safe-outputs - a set of pre-approved, sanitized GitHub operations. There is no arbitrary filesystem or API write access.

      +

      This means: the AI agent cannot push code, delete branches, or modify arbitrary files unless you explicitly declare those safe-outputs and they are on the approved list.

      +

      Supported AI Engines

      + + + + + + + + + + + + + + + + + + + + + + + +
      EngineNotes
      GitHub Copilot CLIDefault engine
      Claude (Anthropic)Alternative engine
      OpenAI CodexAlternative engine
      Custom agentsBring your own coding agent
      +

      Getting Started with gh aw

      +
      # Install the CLI extension
+gh extension install github/gh-aw
+
+# Create a new workflow interactively (from github.com or VS Code also works)
+gh aw create
+
+# Compile your Markdown workflow to a GitHub Actions .lock.yml
+gh aw compile .github/workflows/daily-report.md
+
+# Commit both the .md and .lock.yml files - GitHub Actions runs the .lock.yml
      +

      Monitoring Agentic Workflow Runs

      +
        +
      1. Navigate to the Actions tab of your repository (D → Repository navigation → K to Actions)
        2. +
      2. Find the workflow by name (h3 headings, navigate with 3)
        3. +
      3. Press Enter to open a specific run
        4. +
      4. Expand job steps to read the agent output log and any safe-outputs created
        5. +
      +

      Resources

      + + + + + + + + + + + + + + + + + + + + + + + + + + + +
      ResourceURL
      Official documentationgithub.github.com/gh-aw/
      Source repository (open source)github.com/github/gh-aw
      Peli's Agent Factory (50+ examples)github.github.com/gh-aw/blog/2026-01-12-welcome-to-pelis-agent-factory/
      Community feedback & discussiongithub.com/orgs/community/discussions/186451
      Changelog announcement (Feb 13, 2026)github.blog/changelog/2026-02-13-github-agentic-workflows-are-now-in-technical-preview
      +
      +

      Relationship to Accessibility Agents: Accessibility Agents agents (.agent.md files) are designed for interactive use inside VS Code. GitHub Agentic Workflows are a separate, cloud-native system that uses its own Markdown workflow format and the gh aw CLI - they are complementary tools, not the same mechanism. See Appendix L for the full Accessibility Agents reference.

      +
      +

      Learning Cards: GitHub Agentic Workflows

      +

      Screen reader users:

      +
        +
      • Agentic workflow runs appear in the Actions tab of your repository -- navigate to Actions with T (tab bar), then use heading navigation (3) to jump between workflow run entries
        • +
      • Workflow files are Markdown (.md) not YAML -- the frontmatter at the top controls triggers and permissions; the body is natural language instructions the AI agent reads
        • +
      • The safe-outputs frontmatter property lists every write operation the agent is allowed to perform -- review this section carefully since it is the security boundary
        • +
      +

      Low-vision users:

      +
        +
      • The Actions tab lists workflow runs with status icons (green check, red X, yellow circle) -- at high zoom, also look for the text status label next to each run name
        • +
      • Workflow .md files use the same Markdown rendering as any other file in the repo -- edit them in VS Code with your preferred font size and theme
        • +
      • The gh aw compile command generates a .lock.yml file alongside your .md file -- both appear in the file explorer; the .lock.yml is auto-generated and should not be edited manually
        • +
      +

      Sighted users:

      +
        +
      • Browse 50+ community workflows at Peli's Agent Factory to find templates matching your use case -- each example includes the full .md source you can copy
        • +
      • The workflow format table at the top of this section maps trigger types to use cases -- scan the "Example" column for the pattern closest to your need
        • +
      • Unlike VS Code agent files, agentic workflows run in the cloud via GitHub Actions -- no local VS Code session is required; results appear as issues, PR comments, or other GitHub artifacts
        • +
      +

      Chapter: GitHub Copilot +Related: Appendix L: Accessibility Agents Reference | Appendix G: VS Code Accessibility Reference | Appendix K: AI Models Reference

      +
      +

      Copilot Models

      +
      +

      Listen to Episode 41: Copilot AI Models - a conversational audio overview of this chapter. Listen before reading to preview the concepts, or after to reinforce what you learned.

      +
      + + +

      1. Overview

      +

      GitHub Copilot offers access to AI models from multiple providers including OpenAI, Anthropic, Google, and xAI. The model you choose affects response quality, speed, and premium request consumption. Different models excel at different tasks - understanding these trade-offs helps you get better results.

      +

      Models are updated frequently. This appendix reflects the model landscape as of April 2026. For the latest additions and retirements, see the GitHub Copilot changelog and GitHub's official supported models documentation.

      +
      +

      Workshop note: GitHub Copilot plans, billing, and model availability are changing. We will provide specific guidance at the workshop. Check github.com/settings/copilot to verify your current access.

      +
      +

      2. How to Choose a Model

      +

      GitHub Docs organizes models by task. Match your task to the right model to get the best results without unnecessary premium request cost.

      +

      General-Purpose Coding and Writing

      +

      For everyday tasks - code completions, explanations, refactoring, writing documentation.

      + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + +
      ModelProviderStrengthsCost
      GPT-4.1OpenAIFast, accurate code completions and explanations. Reliable default for most tasks.Free
      GPT-5 miniOpenAIReliable for most coding and writing tasks. Fast and accurate across languages and frameworks. Also supports image input.Free
      GPT-5.1-CodexOpenAIHigher-quality code on complex engineering tasks like features, tests, debugging, refactors, and reviews - without requiring lengthy prompts.1×
      Grok Code Fast 1xAISpecialized for coding. Performs well on code generation and debugging across multiple languages.0.25×
      Raptor miniOpenAI (fine-tuned)Specialized for fast, accurate inline suggestions and explanations. Optimized for completions.Free
      +

      Fast Help with Simple or Repetitive Tasks

      +

      For quick answers, boilerplate generation, renaming, or lightweight explanations where speed matters.

      + + + + + + + + + + + + + + + + + + + + + + + + + + + +
      ModelProviderStrengthsCost
      Claude Haiku 4.5AnthropicBalances fast responses with quality output. Ideal for small tasks and lightweight code explanations.0.33×
      Gemini 3 FlashGoogleFast, reliable answers to lightweight coding questions.0.33×
      GPT-5.1-Codex-MiniOpenAIFast reasoning variant; quick answers on coding tasks.0.33×
      +

      Deep Reasoning and Debugging

      +

      For complex problems, architecture decisions, multi-file analysis, tricky bugs, and understanding unfamiliar codebases.

      + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + +
      ModelProviderStrengthsCost
      GPT-5 miniOpenAIDeep reasoning with faster responses. Ideal for interactive sessions and step-by-step code analysis.Free
      GPT-5.2OpenAIGreat at complex reasoning, code analysis, and technical decision-making.1×
      GPT-5.5OpenAILatest OpenAI reasoning model. Generally available as of April 24, 2026. Strong on complex coding tasks and long-context reasoning.1×
      Claude Sonnet 4 / 4.5 / 4.6AnthropicMore reliable completions and smarter reasoning under pressure. Performance and practicality balanced for coding workflows; strong at complex problem-solving.1×
      Claude Opus 4.6AnthropicAnthropic's most powerful model. Best for the most demanding complex problem-solving challenges and sophisticated reasoning.3×
      Gemini 2.5 ProGoogleComplex code generation, debugging, and research workflows.1×
      Gemini 3 ProGoogleAdvanced reasoning across long contexts and scientific or technical analysis. Supports vision/image input.1×
      GoldeneyeOpenAI (fine-tuned)Complex problem-solving and sophisticated reasoning. Available for code completions and Copilot Free users only.1×
      +

      Agentic Software Development

      +

      For autonomous coding tasks in Agent mode - when Copilot writes code, runs terminal commands, and iterates without step-by-step guidance from you.

      + + + + + + + + + + + + + + + + + + + + + + + + + + + +
      ModelProviderStrengthsCost
      GPT-5.1-Codex-MaxOpenAIBest for agentic tasks. Recommended when using Copilot in Agent mode.1×
      GPT-5.2-CodexOpenAIBest for agentic tasks. Strong autonomous reasoning and multi-step execution.1×
      GPT-5.3-CodexOpenAINewest Codex variant. Powerful agentic capabilities.1×
      +

      Working with Visuals

      +

      For tasks that involve images, screenshots, diagrams, or UI mockups - paste an image directly into the chat input.

      + + + + + + + + + + + + + + + + + + + +
      ModelSupports Images
      GPT-5 miniYes
      Claude Sonnet 4 / 4.5 / 4.6Yes
      Gemini 3 ProYes
      +

      3. Complete Model Reference

      + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + +
      ModelStatusProviderPlansMultiplier
      GPT-4.1GAOpenAIFree, Pro, Pro+, Business, Enterprise0 (free)
      GPT-5 miniGAOpenAIFree, Pro, Pro+, Business, Enterprise0 (free)
      Raptor miniPreviewOpenAI (fine-tuned)Free, Pro0 (free)
      GoldeneyeGAOpenAI (fine-tuned)All plans (completions only)1×
      Grok Code Fast 1GAxAIPro, Pro+, Business, Enterprise0.25×
      Claude Haiku 4.5GAAnthropicPro, Pro+, Business, Enterprise0.33×
      Gemini 3 FlashGAGooglePro, Pro+, Business, Enterprise0.33×
      GPT-5.1-Codex-MiniGAOpenAIPro, Pro+, Business, Enterprise0.33×
      GPT-5.1-CodexGAOpenAIPro, Pro+, Business, Enterprise1×
      GPT-5.1-Codex-MaxGAOpenAIPro, Pro+, Business, Enterprise1×
      GPT-5.1GAOpenAIPro, Pro+, Business, Enterprise1×
      GPT-5.2GAOpenAIPro, Pro+, Business, Enterprise1×
      GPT-5.2-CodexGAOpenAIPro, Pro+, Business, Enterprise1×
      GPT-5.3-CodexGAOpenAIPro, Pro+, Business, Enterprise1×
      GPT-5.5GAOpenAIPro, Pro+, Business, Enterprise1×
      Claude Sonnet 4GAAnthropicPro, Pro+, Business, Enterprise1×
      Claude Sonnet 4.5GAAnthropicPro, Pro+, Business, Enterprise1×
      Claude Sonnet 4.6GAAnthropicPro, Pro+, Business, Enterprise1×
      Gemini 2.5 ProGAGooglePro, Pro+, Business, Enterprise1×
      Gemini 3 ProPreviewGooglePro, Pro+, Business, Enterprise1×
      Claude Opus 4.5PreviewAnthropicPro+, Business, Enterprise3×
      Claude Opus 4.6GAAnthropicPro+, Business, Enterprise3×
      +
      +

      Note: Model availability changes frequently. Check GitHub's supported models page for the current list. Facilitators will provide current guidance at the workshop.

      +
      +

      4. Model Availability by Plan

      + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + +
      PlanFree Models IncludedPaid Models AvailableMonthly Premium Requests
      Copilot FreeGPT-4.1, GPT-5 mini, Raptor miniNone50 (monthly)
      Copilot ProAll 0× modelsMost (Pro+ models excluded)300 (monthly)
      Copilot Pro+All 0× modelsAll modelsUnlimited
      Copilot BusinessAll 0× modelsMost300 per user (monthly)
      Copilot EnterpriseAll 0× modelsAll modelsUnlimited
      +
      +

      Billing is changing. GitHub Copilot plan details and billing models are actively evolving. Facilitators will provide current guidance at the workshop. Check github.com/settings/copilot to see your current plan and usage.

      +
      +

      5. Premium Requests and Cost Multipliers

      + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + +
      MultiplierImpactExample Models
      0 (free)Never consumes premium requestsGPT-4.1, GPT-5 mini, Raptor mini
      0.25×Very low costGrok Code Fast 1
      0.33×Low costClaude Haiku 4.5, Gemini 3 Flash, GPT-5.1-Codex-Mini
      1×StandardClaude Sonnet 4/4.5/4.6, GPT-5.1-Codex, GPT-5.2, Gemini 2.5 Pro, Codex variants
      3×High costClaude Opus 4.5, Claude Opus 4.6
      +

      Tips for managing premium request usage

      +
        +
      • Use GPT-4.1 or GPT-5 mini (both free) for everyday questions, quick explanations, and simple completions - they're fast and capable
        • +
      • Upgrade to Claude Sonnet or GPT-5.2 (1×) only when the task genuinely requires deeper reasoning
        • +
      • Save Claude Opus (3×) for the most demanding analyses - architecture decisions, complex debugging, sophisticated design review
        • +
      • Use Auto mode (see below) and let Copilot allocate model selection intelligently
        • +
      +

      6. Switching Models in VS Code

      +

      In the Chat Panel

      +
        +
      1. Open the Chat panel (Ctrl+Shift+I / Cmd+Shift+I)
        2. +
      2. At the bottom of the chat input area, you'll see the current model name as a button (e.g., "Auto" or "Claude Sonnet 4.6")
        3. +
      3. Activate the model picker button - this opens a dropdown list of available models
        4. +
      4. Arrow through the list and press Enter to select a model
        5. +
      5. For screen reader users: the chat input will announce the newly selected model after switching
        6. +
      +

      In an Inline Chat Session

      +
        +
      1. Open Inline Chat (Ctrl+I / Cmd+I)
        2. +
      2. The model picker appears in the inline chat toolbar
        3. +
      3. Same interaction: activate the model button to switch
        4. +
      +

      Keyboard Note for Screen Readers

      +

      In the Chat panel, the model picker button is near the bottom of the chat view. If you're having trouble locating it:

      +
        +
      • Tab through the bottom toolbar of the chat panel
        • +
      • Listen for the model name announced - it appears between the "Attach" button and the send button
        • +
      • Press Space or Enter to open the picker
        • +
      +

      7. Auto Model Selection

      +

      Auto mode (the default) lets Copilot choose the best model based on the type of request. It became generally available on December 10, 2025.

      +

      How Auto works

      +
        +
      • For simple questions, Copilot routes to a faster, lighter model
        • +
      • For complex code generation or debugging, Copilot upgrades to a more capable model automatically
        • +
      • For agent tasks, Copilot selects an appropriate Codex model
        • +
      • You can see which model was used after each response
        • +
      +

      When to override Auto

      +
        +
      • You specifically need a model with certain capabilities (e.g., vision input with Claude Sonnet 4)
        • +
      • You're managing premium request quotas and want to control costs
        • +
      • You've found a particular model gives better results for your specific workflow or domain
        • +
      • You're doing agentic work and want to explicitly select an agent-optimized Codex model (check current availability in the model picker)
        • +
      +

      To switch back to Auto from a specific model, re-open the model picker and select Auto at the top of the list.

      +

      8. Models Retiring Soon

      +

      GitHub regularly updates the model roster. Older model versions are retired when newer equivalents are available. When a model is retired, Copilot stops sending requests to it and falls back to newer alternatives.

      +

      Already retired (as of April 2026)

      +
        +
      • Claude Sonnet 3.5, Claude Sonnet 3.7
        • +
      • Gemini 2.0 Flash
        • +
      • o1-mini, o3, o3-mini, o4-mini
        • +
      • Claude Opus 4.1
        • +
      • GPT-5 (base), GPT-5-Codex
        • +
      • GPT-5.3-Codex (removed from Student plan model picker, April 2026)
        • +
      +

      To stay current, watch the GitHub Copilot changelog - model additions and retirements are announced there.

      + +
      +

      Next: Appendix L: Agents Reference
      Back: Appendix J: Codespaces
      Teaching chapter: Chapter 16: GitHub Copilot

      + +
      + + + + diff --git a/html/admin/qa-bundle/docs/appendix-l-agents-reference.html b/html/admin/qa-bundle/docs/appendix-l-agents-reference.html new file mode 100644 index 00000000..711761f9 --- /dev/null +++ b/html/admin/qa-bundle/docs/appendix-l-agents-reference.html @@ -0,0 +1,2086 @@ + + + + + + + Appendix L: Accessibility Agents Reference - GIT Going with GitHub + + + + + + + + +
      +

      Appendix L: Accessibility Agents Reference

      +
      +

      Listen to Episode 39: Accessibility Agents - Complete Reference - a conversational audio overview of this chapter. Listen before reading to preview the concepts, or after to reinforce what you learned.

      +
      +
      +

      Reference companion to: Chapter 19: Accessibility Agents | Also relevant: Chapter 20

      +

      Authoritative source: GitHub Docs: Building Copilot extensions

      +
      +

      Complete Reference - Agents, Slash Commands, Instructions, Configuration Levels, and All File Formats

      +
      +

      This is your comprehensive reference for Accessibility Agents and the full VS Code Copilot customization system. The ecosystem includes 55 agents across 3 teams and 5 platforms, plus 54+ slash commands, 17 skills, and 6 instruction files. For the lesson, see Chapter 19: Accessibility Agents. For Copilot keyboard shortcuts and Chat features, see Appendix K: GitHub Copilot Reference.

      +
      +

      Table of Contents

      +
        +
      1. The Full Agent Ecosystem
        2. +
      2. GitHub Workflow Agents - Quick Reference
        3. +
      3. Slash Commands and Prompts
        4. +
      4. Customization Primitives - Decision Guide
        5. +
      5. Scope and Priority - All Levels
        6. +
      6. Always-On Instructions - All File Types
        7. +
      7. File-Based Instructions (.instructions.md)
        8. +
      8. .agent.md - Complete Format Reference
        9. +
      9. .prompt.md - Complete Format Reference
        10. +
      10. Agent Skills (SKILL.md) - Complete Format Reference
        11. +
      11. Hooks (.json) - Lifecycle Automation
        12. +
      12. preferences.md - Accessibility Agents Personal Settings
        13. +
      13. Diagnostics and Troubleshooting
        14. +
      14. Further Reading
        15. +
      +

      1. The Full Agent Ecosystem

      +

      Accessibility Agents includes 55 agents organized into three specialized teams, available on five platforms.

      +

      Platforms

      + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + +
      PlatformAgent FormatInstallation
      GitHub Copilot (VS Code).github/agents/*.agent.mdFork repo or run installer
      Claude CodePer-agent CLAUDE.md + hook enforcementOne-liner installer auto-detects
      Gemini CLIGemini skill filesOne-liner installer auto-detects
      Claude DesktopMCP server integrationOne-liner installer auto-detects
      Codex CLICodex agent filesOne-liner installer auto-detects
      +

      Team 1: Accessibility (26 agents)

      + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + +
      AgentTypeWhat It Does
      @accessibility-leadOrchestratorDelegates multi-agent accessibility audits to specialist agents
      @aria-specialistTaskARIA roles, states, properties, widget patterns (modals, tabs, comboboxes)
      @modal-specialistTaskDialog focus trapping, escape behavior, screen reader overlay announcements
      @contrast-masterTaskColor contrast ratios, focus indicators, dark mode, visual presentation
      @keyboard-navigatorTaskTab order, focus management, keyboard shortcuts, skip links, focus traps
      @live-region-controllerTaskLive region announcements, dynamic content, toasts, loading states
      @forms-specialistTaskForm labels, error handling, validation, autocomplete, field grouping
      @alt-text-headingsTaskAlt text quality, heading hierarchy, document outline, landmark structure
      @tables-specialistTaskTable markup, scope, caption, headers, sortable columns, ARIA grid
      @link-checkerInformationalLink text quality, ambiguous links, WCAG 2.4.4 and 2.4.9 compliance
      @web-accessibility-wizardOrchestratorFull guided WCAG audit - severity scoring, remediation tracking, action plan
      @testing-coachInformationalNVDA/JAWS/VoiceOver testing guidance, automated test setup (axe-core, Playwright)
      @wcag-guideInformationalWCAG 2.2 AA reference, success criteria explanations, conformance levels
      @word-accessibilityTaskMicrosoft Word document accessibility auditing and remediation
      @excel-accessibilityTaskMicrosoft Excel spreadsheet accessibility auditing and remediation
      @powerpoint-accessibilityTaskMicrosoft PowerPoint presentation accessibility auditing
      @office-scan-configInformationalOffice document scan configuration and rule management
      @pdf-accessibilityTaskPDF accessibility auditing (PDF/UA, tagged PDF structure)
      @pdf-scan-configInformationalPDF scan configuration and rule management
      @document-accessibility-wizardOrchestratorGuided document audit wizard for Word, Excel, PowerPoint, and PDF
      @cognitive-accessibilityInformationalCognitive accessibility, plain language, reading level, content clarity
      @mobile-accessibilityTaskiOS VoiceOver and Android TalkBack native app accessibility
      @design-system-auditorTaskDesign system component accessibility review and pattern library audit
      @markdown-a11y-assistantTaskMarkdown headings, links, alt text, tables, emoji, structure enforcement
      @epub-accessibilityTaskePub and digital publication accessibility auditing
      @epub-scan-configInformationalePub scan configuration and rule management
      +

      Team 2: GitHub Workflow (12 agents)

      + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + +
      AgentTypeWhat It Does
      @daily-briefingInformationalMorning situation report - issues, PRs, CI, security, community activity
      @issue-trackerBothFind, prioritize, triage, draft replies to issues across repositories
      @pr-reviewBothStructured PR reviews with risk assessment, change maps, inline suggestions
      @analyticsInformationalContribution velocity, review turnaround, code hotspots, workload distribution
      @insiders-a11y-trackerBothMonitor accessibility-sensitive changes - WCAG/ARIA, headings, links, keyboard
      @template-builderGuidedInteractive issue template wizard via VS Code Ask Questions
      @github-hubBothCentral hub for all GitHub operations and repository management
      @repo-adminTaskRepository settings, branch protection rules, and rulesets
      @team-managerTaskTeam membership, permissions, organization management
      @contributions-hubInformationalContribution tracking, contributor recognition, community metrics
      @repo-managerTaskMulti-repository operations and cross-repo workflow coordination
      @nexusOrchestratorCross-agent orchestration - coordinates multiple agents for complex workflows
      +

      Team 3: Developer Tools (6 agents)

      + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + +
      AgentTypeWhat It Does
      @developer-hubBothCentral hub for developer tool operations and project scaffolding
      @python-specialistTaskPython accessibility patterns, Django/Flask a11y, best practices
      @wxpython-specialistTaskwxPython GUI accessibility - keyboard, focus, screen reader support
      @desktop-a11y-specialistTaskDesktop application accessibility across Windows, macOS, and Linux
      @desktop-a11y-testing-coachInformationalDesktop accessibility testing guidance and automation setup
      @a11y-tool-builderTaskBuild custom accessibility testing tools, linters, and CI checks
      +

      Supporting Resources

      + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + +
      ResourceCountLocation
      Copilot prompts54+.github/prompts/*.prompt.md
      Copilot skills17.github/skills/*/SKILL.md
      Copilot instructions6.github/instructions/*.instructions.md
      Claude Code hooks3.claude/hooks/
      Example violations20+example/ directory
      +

      Learning Cards: Agent Ecosystem Overview

      +
      +Screen reader users + +
        +
      • Invoke any agent by typing @agent-name in Copilot Chat (Ctrl+Shift+I) -- the autocomplete list is keyboard-navigable with arrow keys
        • +
      • The 55 agents are organized into 3 teams (Accessibility, GitHub Workflow, Developer Tools) -- use H in the team tables to jump between headings
        • +
      • Agent responses appear in the Chat panel; press Alt+F2 (Accessible View) for a structured, non-streaming version
        • +
      +
      + +
      +Low vision users + +
        +
      • The agent team tables use consistent columns (Agent, Type, What It Does) -- increase font size so the narrow "Type" column remains readable
        • +
      • Agents work in the Chat panel with your current theme and font settings -- no separate UI to configure
        • +
      • The five supported platforms (VS Code, Claude Code, Gemini CLI, Claude Desktop, Codex CLI) share the same agent logic with platform-specific formatting
        • +
      +
      + +
      +Sighted users + +
        +
      • Skim the three team tables to find the agent closest to your task -- orchestrators coordinate specialists, task agents do focused work
        • +
      • The Supporting Resources table at the bottom shows file counts and locations for prompts, skills, instructions, and hooks
        • +
      • Bookmark this section as your directory of all 55 agents; the later sections document the file formats behind them
        • +
      +
      + + +

      2. GitHub Workflow Agents - Quick Reference

      +

      The GitHub Workflow team includes 12 agents that automate common repository operations. These are good starting points if you have completed the Day 1 skills - but explore any agent in the ecosystem that matches your workflow.\n\nInvoke any agent by typing @agent-name in Copilot Chat (Ctrl+Shift+I).

      +

      @daily-briefing - Morning Briefing

      +

      Agent file: .github/agents/daily-briefing.agent.md

      + + + + + + + + + + + + + + + + + + + +
      Example CommandWhat It Does
      @daily-briefing morning briefingFull prioritized situation report
      @daily-briefing what needs my attention today in accessibility-agents?Repo-scoped briefing
      @daily-briefing summarize activity from the last weekWeekly digest
      +

      Output sections (H2 headings - navigate with H)

      +
        +
      • Needs Your Action
          +
        • Pull Requests Waiting for Your Review
          • +
        • @Mentions Requiring Response
          • +
        • CI Failures on Your Branches
          • +
        +
        • +
      • For Your Awareness
          +
        • Issues Opened Since Yesterday
          • +
        • Your PRs With New Activity
          • +
        • Security and Dependabot Alerts
          • +
        +
        • +
      • All Clear (confirms checked but empty categories)
        • +
      +

      @issue-tracker - Issue Management

      +

      Agent file: .github/agents/issue-tracker.agent.md

      + + + + + + + + + + + + + + + + + + + + + + + +
      Example CommandWhat It Does
      @issue-tracker find open issues labeled good-first-issueFiltered issue search
      @issue-tracker find accessibility issues across all my reposCross-repo search
      @issue-tracker is there a duplicate of issue #42?Duplicate check
      @issue-tracker draft a reply to issue #15Draft a response (you review before posting)
      +

      Important: The agent drafts replies. You post. Always review tone against the Culture & Etiquette guide.

      +

      @pr-review - Pull Request Review

      +

      Agent file: .github/agents/pr-review.agent.md

      + + + + + + + + + + + + + + + + + + + + + + + +
      Example CommandWhat It Does
      @pr-review review PR #14Full review document
      @pr-review what is the risk level of PR #8?Risk assessment only
      @pr-review generate inline comments for PR #14Line-level suggestions only
      @pr-review summarize PR #14 in two sentencesQuick summary
      +

      Output sections (H2/H3 headings)

      +
        +
      • Summary
        • +
      • Risk Assessment (High / Medium / Low)
        • +
      • Files Changed (per-file descriptions)
        • +
      • Suggested Inline Comments (prefixed: nit:, question:, suggestion:, important:, blocking:, praise:)
        • +
      • Questions for the Author
        • +
      • What Looks Good
        • +
      • Review Verdict Recommendation
        • +
      +

      Critical rule: The agent produces a starting point. Read it, edit it, post it under your own name.

      +

      @analytics - Team Analytics

      +

      Agent file: .github/agents/analytics.agent.md

      + + + + + + + + + + + + + + + + + + + + + + + +
      Example CommandWhat It Does
      @analytics team velocity in accessibility-agents this monthContribution pace
      @analytics who are the most active contributors?Top contributors by commits and reviews
      @analytics which files are changed most often?Code hotspot detection
      @analytics how long does PR review take on average?Review turnaround time
      +

      @insiders-a11y-tracker - Accessibility Change Monitor

      +

      Agent file: .github/agents/insiders-a11y-tracker.agent.md

      + + + + + + + + + + + + + + + + + + + +
      Example CommandWhat It Does
      @insiders-a11y-tracker check recent changesScan last commits for a11y impact
      @insiders-a11y-tracker review my PR #14 for accessibility impactPR-scoped accessibility review
      @insiders-a11y-tracker are there any accessibility regressions in the last 5 commits?Regression scan
      +

      What it monitors

      + + + + + + + + + + + + + + + + + + + + + + + +
      AreaWhat It Checks
      Markdown / docsHeading hierarchy skips, non-descriptive link text, missing image alt text, table structure
      HTML / JSXARIA attribute changes, tabIndex, outline: none, display: none on focused elements
      JavaScriptonMouseDown without keyboard equivalent, onMouseEnter/onMouseLeave without keyboard parallel
      Semantic HTML<div>/<span> used for interactive elements instead of <button>, <a>, <input>
      +

      Risk levels: High (regression), Medium (degraded), Low (improvement opportunity)

      +

      @template-builder - Issue Template Wizard

      +

      Agent file: .github/agents/template-builder.agent.md

      + + + + + + + + + + + + + + + + + + + + + + + +
      Example CommandWhat It Does
      @template-builder create accessibility templateGuided a11y bug report template
      @template-builder create security templateGuided security vulnerability template
      @template-builder build a feature request formGeneral feature request template
      @template-builder reorder the fieldsModify existing generated YAML
      +

      Guided workflow phases

      +
        +
      1. Metadata: name, description, title prefix, auto-labels
        2. +
      2. Fields (one at a time): type → label → description → required → type-specific options
        3. +
      3. Review and output: complete YAML ready to save to .github/ISSUE_TEMPLATE/
        4. +
      +

      Supported field types: markdown, input, textarea, dropdown, checkboxes

      +

      3. Slash Commands and Prompts

      +

      The repository includes 54+ slash commands. Type / in Copilot Chat to open the command menu. Each command corresponds to a .prompt.md file in .github/prompts/.

      +

      Workshop Quick Reference

      + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + +
      CommandWhat It Does
      /address-commentsAddress all open review comments on your PR
      /a11y-updateLatest accessibility improvements with WCAG cross-references
      /ci-statusCI/CD health dashboard across your repos
      /create-issueCreate a well-formed issue from a description
      /daily-briefingMorning activity snapshot across all your repos
      /draft-releaseGenerate release notes from merged PRs
      /explain-codeExplain selected code in plain language
      /issue-replyDraft a reply to an issue thread
      /manage-branchesList, compare, and clean up branches
      /manage-issueUpdate labels, assignees, or status on an issue
      /merge-prCheck merge readiness and merge a PR
      /my-issuesYour open issues with priority signals
      /my-prsYour open PRs with CI and review status
      /my-statsYour contribution stats across repos
      /notificationsManage GitHub notifications without opening a browser
      /onboard-repoFirst-time scan of a repo - health, quick wins, recommended actions
      /pr-author-checklistPre-merge checklist for PR authors
      /pr-commentDraft a response to a PR comment
      /pr-reportDetailed PR analysis report
      /project-statusGitHub Projects board overview - columns, blocked, stale
      /reactSuggest or add a reaction to an issue or comment
      /refine-issueImprove issue title, description, and labels
      /release-prepComplete release preparation workflow
      /review-prAI-generated review with inline suggestions
      /security-dashboardDependabot alerts and vulnerability status
      /sprint-reviewEnd-of-sprint summary with velocity and retrospective
      /team-dashboardTeam activity and contribution overview
      /triageTriage a new issue with label and priority suggestions
      +

      Most Useful During the Workshop

      + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + +
      CommandExample Usage
      /my-issues/my-issues - see all your open issues with priority signals
      /review-pr/review-pr #14 - AI-generated review with inline suggestions
      /triage/triage #22 - get label and priority suggestions for a new issue
      /issue-reply/issue-reply #15 - draft a reply to an issue thread
      /a11y-update/a11y-update insiders - latest a11y improvements with WCAG refs
      /daily-briefing/daily-briefing - same output as @daily-briefing
      /draft-release/draft-release v2.0 - generate release notes from merged PRs
      +

      4. Customization Primitives - Decision Guide

      +

      Before creating any file, choose the right primitive for the job. Each primitive is a different file type with a different purpose, scope, and trigger.

      + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + +
      PrimitiveFile TypeWhen to Use
      Always-on instructionscopilot-instructions.md, AGENTS.md, CLAUDE.mdStandards that apply to every request - coding conventions, project context, tone
      File-based instructions*.instructions.mdRules that only apply to specific file types or folders - Python style, test conventions, docs standards
      Prompts / Slash Commands*.prompt.mdSingle repeatable task invoked with /command - scaffolding, triage, PR prep
      Agent SkillsSKILL.md in a named folderMulti-step workflow with bundled scripts and reference files - testing, deployment, auditing
      Custom Agents*.agent.mdSpecialized persona with tool restrictions - orchestrates tasks, can invoke subagents
      Hooks*.jsonDeterministic lifecycle automation - block dangerous commands, run formatters, enforce policy
      Personal Preferencespreferences.mdAccessibility Agents fork-local personal settings - repos, output format, timezone
      +

      Choosing Between Primitives

      +

      Instructions vs Agent?

      +
        +
      • Instructions guide behavior passively (always-on or file-scoped). Agents perform tasks actively (on-demand, tool-using).
        • +
      +

      Prompt vs Agent?

      +
        +
      • Use a prompt for a single focused task you invoke explicitly. Use an agent when the task spans multiple steps, needs different tools, or should work as a subagent for other agents.
        • +
      +

      Prompt vs Skill?

      +
        +
      • Both appear as / slash commands. Use a prompt for one well-defined task. Use a skill when the workflow bundles scripts, templates, or reference docs alongside the instructions.
        • +
      +

      Instructions vs Hooks?

      +
        +
      • Instructions guide the agent (non-deterministic). Hooks enforce behavior via shell commands at lifecycle events - they run regardless of what the agent was prompted to do.
        • +
      +

      Learning Cards: Customization Primitives

      +
      +Screen reader users + +
        +
      • The decision table maps each file type to its purpose -- navigate with T (next table) in browse mode, then arrow through rows
        • +
      • Key distinction: instructions are passive (always-on guidance), agents are active (on-demand task performers), hooks are deterministic (shell commands at lifecycle events)
        • +
      • Use the "Choosing Between Primitives" Q&A pairs below the table to decide which file type fits your need
        • +
      +
      + +
      +Low vision users + +
        +
      • The 7-row decision table is the single most important reference here -- zoom in on the "When to Use" column for the clearest guidance
        • +
      • Each Q&A pair under "Choosing Between Primitives" is a short paragraph -- easy to scan at high magnification
        • +
      • Color-coded syntax in YAML frontmatter examples benefits from a high-contrast theme with distinct keyword colors
        • +
      +
      + +
      +Sighted users + +
        +
      • Scan the decision table visually to match your use case to the right primitive -- the "When to Use" column gives one-sentence guidance
        • +
      • The Q&A comparisons (Instructions vs Agent, Prompt vs Skill, etc.) appear as bold subheadings -- skim them to resolve common ambiguities
        • +
      • If in doubt, start with a .prompt.md file for a focused task; graduate to .agent.md only when you need multi-step tool orchestration
        • +
      +
      + + +

      5. Scope and Priority - All Levels

      +

      Every customization file exists at one of three scopes. VS Code combines all matching files from all scopes and sends them to the model.

      +

      The Three Scopes

      + + + + + + + + + + + + + + + + + + + + + + + +
      ScopeWhere Files LiveWho Shares It
      User / PersonalVS Code profile folderYou only - follows Settings Sync across devices
      Workspace.github/ and related folders in the repoEveryone who clones the repo
      OrganizationGitHub organization settings (Enterprise/Team)Everyone in the org
      +

      Priority Order (highest wins in conflicts)

      +
        +
      1. Personal / User-level - your profile instructions override everything
        2. +
      2. Workspace / Repository-level - .github/copilot-instructions.md, AGENTS.md, .github/agents/*.agent.md
        3. +
      3. Organization-level - organization-defined custom instructions (lowest priority)
        4. +
      +

      User-Level File Locations (Personal, Cross-Workspace)

      +

      All of these files roam with your VS Code Settings Sync.

      + + + + + + + + + + + + + + + + + + + + + + + +
      File TypeLocation on WindowsLocation on macOS/Linux
      Instructions%APPDATA%\Code - Insiders\User\prompts\*.instructions.md~/Library/Application Support/Code - Insiders/User/prompts/
      PromptsSame folder - *.prompt.mdSame folder
      AgentsSame folder - *.agent.mdSame folder
      +
      +

      On this machine: C:\Users\jeffb\AppData\Roaming\Code - Insiders\User\prompts\

      +
      +

      To sync user instructions/prompts/agents across devices:

      +
        +
      1. Enable Settings Sync (Ctrl+Shift+P → "Settings Sync: Turn On")
        2. +
      2. Ctrl+Shift+P → "Settings Sync: Configure"
        3. +
      3. Check "Prompts and Instructions"
        4. +
      +

      Workspace-Level File Locations (Repo-Shared)

      + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + +
      File TypeDefault LocationOverride Setting
      Always-on instructions.github/copilot-instructions.md- (fixed path)
      Always-on (multi-tool)AGENTS.md (root) or nested per subfolderchat.useAgentsMdFile to enable/disable
      Always-on (Claude compat)CLAUDE.md, .claude/CLAUDE.md, CLAUDE.local.md (local only)chat.useClaudeMdFile to enable/disable
      File-based instructions.github/instructions/*.instructions.mdchat.instructionsFilesLocations
      Claude-format instructions.claude/rules/*.instructions.md-
      Agents.github/agents/*.agent.md-
      Prompts.github/prompts/*.prompt.md-
      Skills.github/skills/<name>/SKILL.md-
      Hooks.github/hooks/*.json-
      Personal preferences.github/agents/preferences.md (gitignored)-
      +

      How Multiple Files Are Combined

      +

      VS Code collects all matching instruction files from all scopes and includes them all in the chat context. There is no single winner - all are combined. Priority only resolves conflicts between contradictory instructions.

      +

      6. Always-On Instructions - All File Types

      +

      Always-on instructions are automatically included in every chat request. You never invoke them - Copilot simply follows them.

      + +

      Best for: Most projects. Cross-editor compatible. Version-controlled and team-shared.

      +
      .github/
+  copilot-instructions.md   ← lives here
      +

      File structure: Plain Markdown. No frontmatter required.

      +
      # 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
+- Never use color as the only indicator of meaning
+
+## Documentation Style
+- Write for screen reader users first
+- Use active voice: "Press Ctrl+G" not "You can press Ctrl+G"
+- Never skip heading levels (H1 → H2 → H3, never H1 → H3)
+
+## Commit Message Format
+- Conventional commits: `type: description`
+- Types: feat, fix, docs, style, refactor, test, chore
+- Reference issues at end: "Fixes #123"
+
+## Tone
+- Direct, friendly, professional
+- Assume readers are competent but new to this specific tool
      +

      Auto-generate with: Type /init in Copilot Chat - VS Code analyzes your workspace and generates a tailored copilot-instructions.md.

      +

      Option B: AGENTS.md (Multi-Tool / Monorepo)

      +

      Best for: Projects that use multiple AI tools (Copilot, Claude Code, Gemini CLI, etc.) where a single instruction file should work across all of them. Also best for monorepos where different folders need different rules.

      +

      Root-level (applies everywhere)

      +
      AGENTS.md           ← root of workspace
      +

      Nested (per subfolder - experimental)

      +
      AGENTS.md                  ← root defaults
+frontend/AGENTS.md         ← frontend-specific rules (overrides root for frontend/)
+backend/AGENTS.md          ← backend-specific rules (overrides root for backend/)
      +

      Enable nested file support: chat.useNestedAgentsMdFiles: true in VS Code settings.

      +

      File structure: Same as copilot-instructions.md - plain Markdown, no frontmatter.

      +

      Cross-tool compatibility: AGENTS.md is an open standard. GitHub Copilot, Claude Code, Gemini CLI, and other AI tools all recognize it. Use it instead of copilot-instructions.md when you work with multiple AI tools.

      +

      Rule: Use either AGENTS.md or copilot-instructions.md - not both.

      +

      Option C: CLAUDE.md (Claude Code Compatibility)

      +

      Best for: Teams that use Claude Code alongside VS Code. One file, recognized by both.

      + + + + + + + + + + + + + + + + + + + + + + + +
      LocationScope
      CLAUDE.md (workspace root)Workspace - shared via git
      .claude/CLAUDE.mdWorkspace - shared via git
      CLAUDE.local.md (workspace root)Workspace - local only, not committed
      ~/.claude/CLAUDE.mdUser-level - personal, all workspaces
      +

      VS Code recognizes all four locations when chat.useClaudeMdFile is enabled (default: on).

      +

      For .claude/rules/*.instructions.md files using the Claude Rules format, use paths instead of applyTo for glob matching:

      +
      description: "Python coding standards"
+paths: ["**/*.py", "src/**"]
+Follow PEP 8. Use type hints. Write docstrings for public functions.
      +

      Option D: Settings-Based Instructions (Deprecated)

      +
      +

      Note: Settings-based instructions may be removed in a future VS Code version. Use file-based instructions instead for new work.

      +
      +

      For specialized scenarios, VS Code settings accept inline instructions or file references:

      +
      // .vscode/settings.json or user settings.json
+{
+  "github.copilot.chat.codeGeneration.instructions": [
+    { "text": "Always add error handling for async functions." },
+    { "file": ".github/instructions/code-style.instructions.md" }
+  ],
+  "github.copilot.chat.testGeneration.instructions": [
+    { "text": "Always use describe/it test structure." },
+    { "text": "Include at least one edge case per function." }
+  ],
+  "github.copilot.chat.reviewSelection.instructions": [
+    { "text": "Check for WCAG 2.2 Level AA compliance in all markup." }
+  ],
+  "github.copilot.chat.commitMessageGeneration.instructions": [
+    { "text": "Use conventional commits format: type(scope): description" }
+  ]
+}
      +

      Each entry is an array of objects with either text (inline instruction) or file (path to an instructions file relative to workspace root).

      +

      Organization-Level Instructions (GitHub Enterprise)

      +

      Organization administrators can define custom instructions that apply to all repositories in the organization. Every team member gets these instructions automatically.

      +

      To enable discovery in VS Code

      +
      // User settings.json
+{
+  "github.copilot.chat.organizationInstructions.enabled": true
+}
      +

      Organization instructions are the lowest priority - workspace and user instructions override them when they conflict.

      +

      7. File-Based Instructions (.instructions.md)

      +

      File-based instructions load conditionally - either when the files you are editing match a glob pattern, or when the agent determines the instruction is relevant to the current task.

      +

      Use for: Language-specific rules, framework conventions, module-specific standards that only apply to part of the codebase.

      +

      File Locations

      + + + + + + + + + + + + + + + + + + + +
      ScopeLocation
      Workspace.github/instructions/*.instructions.md
      Additional workspace foldersConfigure with chat.instructionsFilesLocations setting
      User / PersonalVS Code profile prompts folder (*.instructions.md)
      +

      Frontmatter Fields

      +
      name: "Display Name"           # Optional - defaults to filename; shown in UI
+description: "Use when..."     # Optional - enables on-demand discovery; be keyword-rich
+applyTo: "**/*.py"             # Optional - glob pattern(s) for automatic application
      +

      The applyTo Glob Pattern

      +

      applyTo specifies which files trigger automatic inclusion of these instructions. When a file matching the pattern is part of the chat context, the instructions are included automatically.

      +
      applyTo: "**"                          # ALWAYS included (use carefully - applies everywhere)
+applyTo: "**/*.py"                     # All Python files
+applyTo: "**/*.{ts,tsx}"               # TypeScript and TSX files
+applyTo: "docs/**"                     # Everything under docs/
+applyTo: ["src/**", "lib/**"]          # Multiple patterns (OR - either match triggers inclusion)
+applyTo: src/**, lib/**                # Same without array syntax
+applyTo: "**/*.test.{js,ts}"          # Only test files
+applyTo: ".github/ISSUE_TEMPLATE/**"  # Only issue template files
      +

      If applyTo is omitted: The instruction is NOT applied automatically. It can still be added manually via the Chat context menu, or picked up by the agent if the description semantically matches the current task.

      +

      Discovery Modes

      + + + + + + + + + + + + + + + + + + + + + + + +
      ModeTriggerWhen to Use
      Automatic (applyTo set)When matching files are in the chat contextLanguage rules, framework patterns, folder-specific standards
      On-demand (description set, no applyTo)Agent detects task relevance from description keywordsMigration guides, refactoring rules, API design patterns
      ManualUser selects "Add Context → Instructions" in ChatAd-hoc attachment for one-off situations
      +

      Example: Accessibility-Specific Instructions

      +
      name: "Accessible Markdown Standards"
+description: "Use when writing, editing, or reviewing Markdown documentation. Covers heading hierarchy, link text, alt text, and table structure."
+applyTo: "**/*.md"
+
+# Markdown Accessibility Standards
+
+- Never skip heading levels (H1 → H2 → H3; H1 → H3 is a WCAG 1.3.1 violation)
+- Use descriptive link text: never "click here", "read more", or bare URLs
+- Every informational image must have alt text describing what it conveys
+- Every decorative image must use empty alt: `![](image.png)` or `alt=""`
+- Tables must have header rows using `|---|` Markdown syntax
+- Ordered lists (`1.`) only for genuinely sequential steps; use unordered (`-`) otherwise
      +

      Example: YAML Issue Template Instructions

      +
      name: "Issue Template YAML"
+description: "Use when writing or reviewing GitHub issue templates in YAML format"
+applyTo: ".github/ISSUE_TEMPLATE/**/*.{yml,yaml}"
+
+# Issue Template YAML Standards
+
+- Every field must have a non-empty `label`
+- Dropdowns must list at least 2 options
+- Use `required: true` only for fields that truly block triage without them
+- Prefer `textarea` for free-form text; use `input` only for short identifiers
+- Every template must have a `name`, `description`, and `title` prefix
      +

      Creating an Instructions File

      +

      Command Palette method

      +

      Writing Effective Instructions

      +

      Guidance from GitHub's accessibility team on writing instructions that Copilot actually follows:

      +

      Do:

      +
        +
      • Use normative language. Write MUST, MUST NOT, SHOULD, SHOULD NOT, and MAY for rules. LLMs respond well to these terms because they reduce ambiguity -- the same words used in WCAG. Example: Keyboard shortcuts MUST NOT override browser or OS shortcuts.
        • +
      • Use lists and checklists. Structured lists provide guardrails that keep Copilot on track. Format accessibility requirements as a checklist so no criterion is overlooked.
        • +
      • Specify your versions and standards. This application MUST conform to WCAG 2.2 Level AA is more useful than a general reference to accessibility. Include your design system's component names and flag deprecated components explicitly: DeprecatedButton MUST NOT be used; use NewAccessibleButton instead.
        • +
      • Focus on what Copilot doesn't already know. Instructions should add net-new information -- your team's conventions, exceptions, and priorities -- not restate what Copilot was trained on.
        • +
      • Keep instructions concise. Overly long instructions reduce model performance. Summarize the most important rules rather than listing every possible case.
        • +
      +

      Don't:

      +
        +
      • Don't paste full guidelines. Copilot is already trained on WCAG, ARIA, and HTML standards. Copying large sections of a spec into instructions wastes context and rarely improves output. Focus on your team's specific deviations and priorities instead.
        • +
      • Don't reference external links. By design, Copilot does not fetch URLs in custom instructions (a deliberate privacy and security protection). A link is useful as a human reference but has no effect on Copilot's behavior. Write the relevant rules directly into the instructions text.
        • +
      • Don't reference private repositories. Copilot cannot access private repo content from within another repository's instructions. Write the guidance inline.
        • +
      • Use role-based prompting carefully. Assigning a persona (You are the lead accessibility expert...) can be effective, but any persona can carry assumptions from training data. If you use role prompting, be specific about skills and responsibilities, stay neutral, and use professional functional language.
        • +
      +

      Share your instructions: The github/awesome-copilot repository collects community-contributed instructions files. Before submitting, review your file to confirm it contains no sensitive or confidential information.

      +

      Creating an Instructions File

      +

      Command Palette method

      +
        +
      1. Ctrl+Shift+P → "Chat: New Instructions File"
        2. +
      2. Choose Workspace or User Profile scope
        3. +
      3. Enter filename
        4. +
      4. Add applyTo and/or description frontmatter
        5. +
      5. Write instructions
        6. +
      +

      Quick creation method

      +

      Type /instructions in the Chat input to open the Configure Instructions menu.

      +

      8. .agent.md - Complete Format Reference

      +

      File Locations

      + + + + + + + + + + + + + + + +
      ScopeLocation
      Workspace.github/agents/*.agent.md
      User / PersonalVS Code profile folder *.agent.md
      +

      Complete Frontmatter Reference

      +
      name: "agent-name"                        # Required - what you type after @ in Chat
+description: "Use when..."               # Required - triggers subagent delegation; keyword-rich
+tools: ["read", "search", "githubRepo"]  # Optional - tools this agent can use; omit = defaults; [] = none
+model: "Claude Sonnet 4.5 (copilot)"     # Optional - specific model to use
+agent: "ask"                              # Optional - agent mode: ask | agent | plan | or custom name
+argument-hint: "Repo or PR ref..."       # Optional - hint shown in chat input when agent is selected
+agents: ["SubagentA", "SubagentB"]       # Optional - restrict which subagents this agent can invoke (omit = all allowed)
+user-invocable: true                      # Optional - show in agent picker (default: true); false = subagent only
+disable-model-invocation: false          # Optional - prevent other agents from invoking this as subagent (default: false)
+handoffs: ["AgentB", "AgentC"]           # Optional - agents this agent can hand off to
      +

      Model Fallback Array

      +
      model: ["Claude Sonnet 4.5 (copilot)", "GPT-5 (copilot)"]
      +

      The first available model in the array is used. Useful for environments where not all models are licensed.

      +

      Invocation Control

      + + + + + + + + + + + + + + + + + + + + + + + + + + + + +
      SettingDefaultEffect
      user-invocable: trueDefaultAgent appears in @ picker; users can invoke it directly
      user-invocable: false-Hidden from picker; only callable as a subagent from another agent
      disable-model-invocation: falseDefaultOther agents can delegate to this agent based on description matching
      disable-model-invocation: true-This agent cannot be invoked as a subagent; user-invoked only
      +

      All Tool Names

      +

      Built-in aliases

      + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + +
      AliasWhat It Provides
      readRead files in the local workspace
      editEdit files in the local workspace
      searchSearch files and text in the workspace
      executeRun shell commands in the terminal
      agentInvoke custom agents as subagents
      webFetch URLs and search the web
      todoManage task lists
      +

      Specific tools (reference by exact name)

      + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + +
      ToolWhat It Provides
      githubRepoGitHub API - search issues, PRs, code
      fetchHTTP fetch - read external URLs
      createFileCreate new files in the workspace
      createDirectoryCreate new directories
      editFilesEdit multiple files
      readFileRead specific file contents
      codebaseSearch and read the codebase semantically
      ask_questionsVS Code Ask Questions UI (interactive wizard prompts)
      github/*All GitHub MCP tools (wildcard)
      <server>/*All tools from a named MCP server
      +

      Tool combinations by use case

      +
      # Read-only research (safest)
+tools: ["read", "search", "githubRepo"]
+
+# Documentation / file generation
+tools: ["read", "edit", "createFile", "createDirectory"]
+
+# Full GitHub workflow
+tools: ["github/*", "read", "edit", "createFile"]
+
+# Terminal access (use carefully)
+tools: ["execute", "read", "edit"]
+
+# Conversational only (no file access)
+tools: []
+
+# Interactive wizard
+tools: ["ask_questions", "createFile"]
      +

      Body Structure Template

      +
      name: my-agent
+description: "Use when [specific task/trigger]. Handles [clear purpose]."
+tools: ["read", "search"]
+user-invocable: true
+
+You are a specialist at [specific role]. Your job is to [clear purpose].
+
+## Constraints
+- DO NOT [thing this agent should never do]
+- DO NOT post anything without human review
+- ONLY [the one thing this agent does]
+
+## Behavior
+
+### [Task Name]
+When asked to [task]:
+1. [Step one]
+2. [Step two]
+3. [Step three]
+
+## Output Format
+
      +

      [Section Header]

      +

      [Describe the exact output structure here with placeholders]

      +
      
+## Accessibility Requirements
+- Use heading level 2 for the document title, level 3 for sections
+- Never use tables for lists - ordered or unordered lists are more predictable for screen reader navigation
+- Always include "empty state" messages - never omit a section silently
+
+## Scope Boundaries
+- You [do X]. You do NOT [do Y].
+- The human reviews all output before acting on it.
      +

      Creating Your Own Agent

      +
        +
      1. Copy an existing .agent.md from .github/agents/
        2. +
      2. Edit the frontmatter (name, description, tools)
        3. +
      3. Write clear step-by-step instructions in the body
        4. +
      4. Add an Output Format section showing the expected structure
        5. +
      5. Add Constraints and Scope Boundaries sections
        6. +
      6. Save to .github/agents/your-agent-name.agent.md
        7. +
      7. Reload VS Code: Ctrl+Shift+P → "Reload Window"
        8. +
      8. Type @your-agent-name in Copilot Chat
        9. +
      +

      Tip: Write keyword-rich descriptions. The description is how other agents decide whether to delegate to yours. "A helpful agent" will never get delegated to. "Use when auditing Markdown files for accessibility violations (missing alt text, heading skips, bare URLs)" will.

      +

      Learning Cards: .agent.md - Complete Format Reference

      +

      Screen reader users:

      +
        +
      • YAML frontmatter is the first block in the file between --- delimiters -- arrow through it line by line to verify name, description, and tools fields; indentation matters
        • +
      • The name field in frontmatter is what you type after @ in Copilot Chat -- if the agent does not appear, check this field matches your invocation and reload VS Code (Ctrl+Shift+P then "Reload Window")
        • +
      • Use Chat Diagnostics (gear icon in Chat header then Diagnostics) to verify your agent loaded successfully -- it lists every agent found, with error details if frontmatter parsing failed
        • +
      +

      Low-vision users:

      +
        +
      • Agent files are small Markdown documents typically under 100 lines -- increase editor font size and use a theme with distinct YAML keyword colors so frontmatter fields stand out
        • +
      • The tools list in frontmatter uses array syntax (["read", "search"]) -- at high zoom, verify commas and quotes are correct since YAML is sensitive to formatting
        • +
      • The body template structure (Constraints, Behavior, Output Format, Scope Boundaries) uses ## headings -- use VS Code's Outline view (Ctrl+Shift+O) to navigate between sections
        • +
      +

      Sighted users:

      +
        +
      • Copy an existing .agent.md from .github/agents/ as a starting template -- the frontmatter structure is identical across all agents; just change the name, description, and tool list
        • +
      • The tool combinations table in this section shows common patterns by use case -- scan the comments (e.g., "Read-only research", "Full GitHub workflow") to find the right tool set
        • +
      • The invocation control table explains user-invocable and disable-model-invocation flags -- set user-invocable: false to create helper agents that only other agents can call
        • +
      +

      9. .prompt.md - Complete Format Reference

      +

      File Locations

      + + + + + + + + + + + + + + + +
      ScopeLocation
      Workspace.github/prompts/*.prompt.md
      User / PersonalVS Code profile folder *.prompt.md
      +

      Complete Frontmatter Reference

      +
      name: "command-name"                    # Optional - defaults to filename; the /command name
+description: "One-sentence description" # Optional - shown in slash command picker
+argument-hint: "PR ref or repo name"   # Optional - hint in chat input when command is selected
+agent: "agent"                          # Optional - agent mode: ask | agent | plan | or custom @agent-name
+model: "GPT-5 (copilot)"               # Optional - override model for this command
+tools: ["github/*", "createFile"]       # Optional - tools this command can use
      +

      Model Fallback

      +
      model: ["GPT-5 (copilot)", "Claude Sonnet 4.5 (copilot)"]
      +

      Tool Priority When Agent Is Also Specified

      +

      When both the prompt and the referenced agent define tools, VS Code uses this priority:

      +
        +
      1. Tools listed in the prompt file's frontmatter (highest priority)
        2. +
      2. Tools from the referenced custom agent
        3. +
      3. Default tools for the selected agent mode
        4. +
      +

      Input Parameters

      +
      ${input:parameterName:Prompt text shown to the user}
      +
        +
      • parameterName - internal identifier (no spaces)
        • +
      • The text after the second : is shown to the user as a placeholder or tooltip
        • +
      • Multiple parameters are supported in one prompt file
        • +
      +
      ${input:repo:Target repository - e.g. owner/repo or leave blank for current workspace}
+${input:scope:Optional filter: label name, date range, or org:orgname}
      +

      Body - Referencing Tools and Files

      +
      Use #tool:<tool-name> to explicitly invoke a tool:
+
+Fetch issue #42 with #tool:mcp_github_github_issue_read.
+
+Reference workspace files with Markdown links:
+See the configuration in [preferences.md](.github/agents/preferences.md).
      +

      Example - Accessibility Update Command

      +
      name: a11y-update
+description: "Get latest accessibility improvements with WCAG cross-references"
+agent: insiders-a11y-tracker
+tools: ["github/*", "createFile", "ask_questions"]
+
+Show the latest accessibility improvements across tracked repositories.
+
+${input:scope:Optional: 'insiders', 'stable', a repo name, a month, or a WCAG criterion}
+
+## Behavior
+Load repo list from `.github/agents/preferences.md`. Group results by: Screen Reader,
+Keyboard Navigation, Visual/Contrast, Audio/Motion, Cognitive.
+
+For each finding include:
+- WCAG success criterion (e.g., "WCAG 2.4.3 Focus Order (Level A)")
+- ARIA design pattern if applicable
+- Impact level: Critical / Major / Minor
+- Assistive technologies affected
      +

      Creating Your Own Slash Command

      +
        +
      1. Copy an existing .prompt.md from .github/prompts/
        2. +
      2. Edit frontmatter (name, description, tools)
        3. +
      3. Write the task instructions in plain English
        4. +
      4. Add ${input:...} placeholders where the user must provide values
        5. +
      5. Save to .github/prompts/your-command.prompt.md
        6. +
      6. Reload VS Code: Ctrl+Shift+P → "Reload Window"
        7. +
      7. Type /your-command to invoke it
        8. +
      +

      Both prompts and agent skills appear as / slash commands. The difference: prompts are single-task Markdown files; skills are folders with bundled scripts and references.

      +

      Learning Cards: Prompts and Slash Commands

      +
      +Screen reader users + +
        +
      • Type / in Copilot Chat to see all available slash commands -- the autocomplete list reads each command name and description aloud
        • +
      • .prompt.md files use YAML frontmatter for metadata (name, description, tools) followed by plain Markdown instructions
        • +
      • Use ${input:variableName} placeholders in prompts to create interactive fill-in-the-blank commands that prompt the user at invocation
        • +
      +
      + +
      +Low vision users + +
        +
      • The slash command picker popup is themed to match your current VS Code theme -- ensure your theme has sufficient contrast for dropdown items
        • +
      • .prompt.md files are small Markdown files that are easy to read and edit at high zoom -- typically under 50 lines
        • +
      • The YAML frontmatter block at the top is indentation-sensitive -- use VS Code's indentation guides or a linter to verify structure
        • +
      +
      + +
      +Sighted users + +
        +
      • The / picker shows a scrollable list of commands grouped by source -- built-in commands appear first, then workspace prompts
        • +
      • Look at the .github/prompts/ folder in the Explorer to see all custom slash commands defined in the project
        • +
      • Copy an existing .prompt.md file as a template when creating new commands -- the frontmatter structure is the same for all prompts
        • +
      +
      + + +

      10. Agent Skills (SKILL.md) - Complete Format Reference

      +

      A Skill is a folder - not a single file. The folder contains SKILL.md plus any scripts, templates, and reference documents the skill needs.

      +

      Folder Structure

      +
      .github/skills/
+  my-skill/
+    SKILL.md              ← Required; name must match folder name
+    scripts/
+      run-audit.sh        ← Referenced from SKILL.md
+    references/
+      wcag-criteria.md    ← Reference doc loaded when needed
+    assets/
+      template.yml        ← Boilerplate files
      +

      File Locations

      + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + +
      ScopeLocation
      Workspace.github/skills/<name>/SKILL.md
      Workspace (alternate).agents/skills/<name>/SKILL.md
      Workspace (Claude compat).claude/skills/<name>/SKILL.md
      User / Personal~/.copilot/skills/<name>/SKILL.md
      User (alternate)~/.agents/skills/<name>/SKILL.md
      User (Claude compat)~/.claude/skills/<name>/SKILL.md
      +

      Complete Frontmatter Reference

      +
      name: skill-name                      # Required - 1-64 chars; lowercase alphanumeric + hyphens; must match folder name
+description: "Use when..."           # Required - keyword-rich trigger phrases for on-demand discovery
+argument-hint: "Optional input..."   # Optional - hint shown when skill is selected as slash command
+user-invocable: true                  # Optional - appear as slash command (default: true)
+disable-model-invocation: false       # Optional - prevent automatic loading by agents (default: false)
      +

      Slash Command Behavior

      + + + + + + + + + + + + + + + + + + + + + + + + + + + + +
      user-invocabledisable-model-invocationResult
      true (default)false (default)Appears as /command AND auto-loads
      falsefalseDoes NOT appear as /command; auto-loads only
      truetrueAppears as /command; does NOT auto-load
      falsetrueNeither /command nor auto-load
      +

      Progressive Loading - How VS Code Loads Skills

      +
        +
      1. Discovery (~100 tokens): Reads name and description to decide if the skill is relevant
        2. +
      2. Instructions (<5000 tokens): Loads the full SKILL.md body when the skill is relevant
        3. +
      3. Resources: Additional files (scripts/, references/) only load when explicitly referenced from SKILL.md
        4. +
      +

      Keep SKILL.md under 500 lines. Move reference material to references/ folder files.

      +

      SKILL.md Body Template

      +
      name: a11y-audit
+description: "Audit Markdown files for accessibility violations. Use for heading hierarchy, link text quality, alt text, and WCAG compliance checks."
+
+# Accessibility Audit Skill
+
+## When to Use
+- Before opening a PR that modifies Markdown documentation
+- When asked to check accessibility compliance of docs
+- After generating new documentation content
+- During content review for WCAG 1.3.1, 2.4.4, 1.1.1
+
+## Procedure
+
+1. Run the audit script: [audit.sh](./scripts/audit.sh)
+2. Review output for heading hierarchy violations (H1→H3 skips)
+3. Check all links - flag bare URLs and non-descriptive text
+4. Verify alt text on all images
+5. Review the [WCAG reference](./references/wcag-quick-ref.md) for remediation guidance
+6. Report findings by risk level: High | Medium | Low
+
+## Output Format
+- High risk: potential regressions (inaccessible content where it was accessible before)
+- Medium risk: degraded accessibility
+- Low risk: improvement opportunities
+- Include WCAG criterion for each finding
      +

      11. Hooks (.json) - Lifecycle Automation

      +

      Hooks execute shell commands at specific points in an agent's lifecycle. They are deterministic - they run regardless of what the agent was prompted to do.

      +

      Use hooks for enforcement, not guidance. For behavior you want to enforce - blocking commands, auto-running formatters, requiring approval - use hooks. For behavior you want to encourage - coding standards, tone, output format - use instructions.

      +

      File Locations

      + + + + + + + + + + + + + + + + + + + + + + + + + + + + +
      ScopeLocationCommitted?
      Workspace (team-shared).github/hooks/*.jsonYes
      Workspace (local).claude/settings.local.jsonNo (gitignored)
      Workspace.claude/settings.jsonYes
      User / Personal~/.claude/settings.jsonPersonal only
      +

      Hooks from all locations are combined - workspace and user hooks do not override each other.

      +

      Hook Events

      + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + +
      EventWhen It Fires
      SessionStartFirst prompt of a new agent session
      UserPromptSubmitUser submits any prompt
      PreToolUseImmediately before any tool is invoked
      PostToolUseAfter successful tool invocation
      PreCompactBefore context compaction
      SubagentStartWhen a subagent begins
      SubagentStopWhen a subagent ends
      StopWhen the agent session ends
      +

      Configuration Format

      +
      {
+  "hooks": {
+    "PreToolUse": [
+      {
+        "type": "command",
+        "command": ".github/hooks/validate-before-edit.sh",
+        "timeout": 15
+      }
+    ],
+    "PostToolUse": [
+      {
+        "type": "command",
+        "command": "npx prettier --write",
+        "windows": "npx.cmd prettier --write",
+        "timeout": 30
+      }
+    ]
+  }
+}
      +

      Hook Command Fields

      + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + +
      FieldRequiredDescription
      typeYesMust be "command"
      commandYesShell command to run (default for all platforms)
      windowsNoWindows-specific override
      linuxNoLinux-specific override
      osxNomacOS-specific override
      cwdNoWorking directory for the command
      envNoEnvironment variable overrides
      timeoutNoMax seconds before killing the process
      +

      Input/Output Contract

      +

      Hooks receive JSON on stdin. They can return JSON on stdout:

      +
      {
+  "continue": true,
+  "stopReason": "optional message if blocking",
+  "systemMessage": "optional context injected into the agent session"
+}
      +

      PreToolUse permission decisions

      +
      {
+  "hookSpecificOutput": {
+    "hookEventName": "PreToolUse",
+    "permissionDecision": "allow",
+    "permissionDecisionReason": "Safe read-only operation"
+  }
+}
      +

      Permission decisions: "allow" | "ask" (prompt user) | "deny" (block the tool call)

      +

      Exit codes

      +
        +
      • 0 - success; agent continues
        • +
      • 2 - blocking error; agent stops
        • +
      • Other - non-blocking warning
        • +
      +

      Learning Cards: Hooks

      +

      Screen reader users:

      +
        +
      • Hooks are JSON files, not Markdown -- navigate them in the editor with arrow keys; each hook event (e.g., PreToolUse, PostToolUse) is a key in the "hooks" object
        • +
      • Hook output is returned as JSON on stdout -- the "continue" field (true/false) determines whether the agent proceeds; listen for the "stopReason" message if the hook blocks an action
        • +
      • The "permissionDecision" values (allow, ask, deny) control tool access -- ask triggers a confirmation dialog that your screen reader will announce as a standard VS Code dialog
        • +
      +

      Low-vision users:

      +
        +
      • JSON syntax requires careful attention to braces, brackets, and commas -- use VS Code's bracket pair colorization (editor.bracketPairColorization.enabled) and increase font size to verify structure
        • +
      • The hook events table maps each event name to when it fires -- zoom in on the "When It Fires" column to understand the lifecycle timing
        • +
      • Hook errors appear in the agent session output -- look for non-zero exit codes or "continue": false in the output pane
        • +
      +

      Sighted users:

      +
        +
      • The hook events table lists 8 lifecycle events -- PreToolUse and PostToolUse are the most commonly used for validation and formatting enforcement
        • +
      • The configuration format example shows the JSON structure with command, timeout, and platform-specific overrides -- copy this template and modify the command paths for your project
        • +
      • Hooks from workspace (.github/hooks/) and user (~/.claude/settings.json) locations are combined, not overridden -- check both locations if a hook is firing unexpectedly
        • +
      +

      12. preferences.md - Accessibility Agents Personal Settings

      +

      Copy .github/agents/preferences.example.md to .github/agents/preferences.md. The file is in .gitignore - your private settings stay only in your local fork.

      +

      Full File Template

      +
      # My Accessibility Agents Preferences
+
+## My GitHub Username
+your-github-username
+
+## Repositories I Work On Most
+- community-access/accessibility-agents
+- your-org/your-repo
+
+## Preferred Output Format
+screen-reader-optimized
+
+## Notification Priority
+Accessibility issues first, then review requests assigned to me, then CI failures,
+then security alerts, then general activity.
+
+## Review Comment Tone
+Direct but constructive. Always explain the "why". Assume good intent from authors.
+Warm and encouraging for first-time contributors.
+
+## Time Zone
+America/New_York
+
+## Accessibility Context
+I use NVDA with Chrome on Windows 11.
      +

      Preferred Output Format Options

      + + + + + + + + + + + + + + + + + + + +
      ValueWhat It Does
      "concise"Bullet points and short summaries, minimal prose
      "detailed"Full context and more explanation in every response
      "screen-reader-optimized"Heading-heavy structure, no tables, explicit empty-state messages
      +

      Notification Priority Options

      +

      The @daily-briefing agent reads this to sort its output sections. Examples:

      +
      Accessibility issues first, then review requests assigned to me, then CI failures, then general activity.
      +
      Review requests first. CI failures second. Security alerts third. Everything else as a digest at the end.
      +

      Review Comment Tone Options

      +

      The @pr-review and @issue-tracker agents read this when drafting comments:

      +
      Direct but constructive. Always explain the "why" behind a suggestion. Assume good intent from authors.
      +
      Friendly and encouraging for first-time contributors.
+More direct and concise for established contributors.
      +

      Accessibility Context Options

      +

      Tells agents which screen reader and browser you use so they can tailor output and recommendations:

      +
      I use NVDA with Chrome on Windows 11.
+I use VoiceOver with Safari on macOS Sonoma.
+I use JAWS with Firefox on Windows 10.
+I use Narrator with Edge on Windows 11.
+I use TalkBack on Android.
      +

      13. Diagnostics and Troubleshooting

      +

      View All Loaded Customizations

      +

      To see every instruction file, agent, prompt, and skill currently loaded and any errors:

      +
        +
      1. In Copilot Chat, select the gear icon (Configure Chat) → Diagnostics
        2. +
      2. Or right-click in the Chat view → Diagnostics
        3. +
      +

      This shows: which files were found, which were loaded, which have errors, and from which scope (user vs workspace vs organization).

      +

      Common Issues

      +

      Agent not found when typing @agent-name

      +
        +
      1. Verify .github/agents/[name].agent.md exists in your open workspace folder
        2. +
      2. Check that the YAML frontmatter has no syntax errors (missing quotes, wrong indentation)
        3. +
      3. Ctrl+Shift+P → "Reload Window"
        4. +
      4. Check that the name field in the frontmatter matches what you are typing
        5. +
      +

      Instructions not being applied

      +
        +
      1. For .github/copilot-instructions.md: file must be at workspace root in the .github/ folder
        2. +
      2. For *.instructions.md: check that applyTo glob matches the file you are editing, and that chat.includeApplyingInstructions is true in VS Code settings
        3. +
      3. For AGENTS.md: check that chat.useAgentsMdFile is true
        4. +
      4. Use Diagnostics view (above) to verify the file was found and loaded
        5. +
      +

      Instructions file in wrong place

      +
        +
      • Add custom locations: chat.instructionsFilesLocations setting accepts an array of additional folder paths
        • +
      +

      Slash command not appearing

      +
        +
      1. Verify .github/prompts/[name].prompt.md exists
        2. +
      2. Ctrl+Shift+P → "Reload Window"
        3. +
      3. File must use .prompt.md extension (not just .md)
        4. +
      +

      Accessibility Agents Keyboard Shortcuts

      + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + +
      ActionShortcut
      Open Copilot ChatCtrl+Shift+I
      Invoke an agentType @agent-name in Chat
      Use a slash commandType /command-name in Chat
      Open Accessible View (Chat response or inline suggestion)Alt+F2
      Insert inline suggestion from Accessible View at cursorCtrl+/
      Clear chat historyCtrl+L
      Reload VS Code windowCtrl+Shift+P → "Reload Window"
      New instructions fileCtrl+Shift+P → "Chat: New Instructions File"
      Configure instructionsCtrl+Shift+P → "Chat: Configure Instructions"
      View diagnosticsConfigure Chat gear → Diagnostics
      +

      14. Further Reading

      +

      For the broader ecosystem - the community plugin marketplace, MCP server integrations, and running agents in the cloud via GitHub Actions - see Appendix K: GitHub Copilot and Agentic Reference.

      +

      Official accessibility.github.com Guides

      + + + + + + + + + + + + + + + + + + + +
      GuideURL
      Getting started with custom agents for accessibilityaccessibility.github.com/documentation/guide/getting-started-with-agents/
      Optimizing Copilot with custom instructions (accessibility)accessibility.github.com/documentation/guide/copilot-instructions/
      GitHub Copilot for VS Code screen reader guideaccessibility.github.com/documentation/guide/github-copilot-vsc/
      +
      +

      Next: Appendix M: Accessibility Standards
      Back: Appendix K: Copilot Reference
      Teaching chapter: Chapter 19: Accessibility Agents

      + +
      + + + + diff --git a/html/admin/qa-bundle/docs/appendix-m-accessibility-standards.html b/html/admin/qa-bundle/docs/appendix-m-accessibility-standards.html new file mode 100644 index 00000000..5fccf61d --- /dev/null +++ b/html/admin/qa-bundle/docs/appendix-m-accessibility-standards.html @@ -0,0 +1,656 @@ + + + + + + + Appendix M: Accessibility Standards Reference - GIT Going with GitHub + + + + + + + + +
      +

      Appendix M: Accessibility Standards Reference

      +
      +

      Listen to Episode 20: Accessibility Standards Reference - a conversational audio overview of this chapter. Listen before reading to preview the concepts, or after to reinforce what you learned.

      +
      +
      +

      Reference companion to: Chapter 08: Open Source Culture | Also relevant: Chapter 12

      +

      Authoritative source: W3C WCAG 2.2 | WAI-ARIA 1.2

      +
      +

      WCAG, ARIA, and What They Mean for Your Contributions

      +
      +

      This appendix gives you a working understanding of the accessibility standards that govern the web, GitHub's interface, and the projects you will contribute to. You do not need to memorize these - use this as a lookup when a PR review mentions a specific standard or success criterion.

      +
      +

      Table of Contents

      +
        +
      1. WCAG 2.2 - The Four Principles
        2. +
      2. Conformance Levels: A, AA, AAA
        3. +
      3. Key Success Criteria for Web Contributions
        4. +
      4. ARIA - Roles, States, and Properties
        5. +
      5. ARIA Landmark Roles
        6. +
      6. Common ARIA Patterns
        7. +
      7. How Standards Apply to GitHub Contributions
        8. +
      8. Testing Against Standards
        9. +
      9. Quick Reference: What to Check in a PR
        10. +
      10. Official References
        11. +
      +

      1. WCAG 2.2 - The Four Principles

      +

      WCAG (Web Content Accessibility Guidelines) is organized around four principles, often abbreviated POUR:

      + + + + + + + + + + + + + + + + + + + + + + + + + + + + +
      PrincipleMeaningExample Failure
      PerceivableInformation must be presentable to users in ways they can perceiveAn image with no alt text - a screen reader user gets nothing
      OperableUI components and navigation must be operableA button that only works on hover - keyboard users cannot activate it
      UnderstandableInformation and operation must be understandableAn error message that says "Invalid input" with no explanation of what is wrong
      RobustContent must be robust enough to be interpreted by assistive technologiesCustom JavaScript widgets with no ARIA roles - screen readers cannot determine what they are
      +

      Every WCAG success criterion belongs to one of these four principles.

      +

      Learning Cards: WCAG Overview

      +
      +Screen reader users + +
        +
      • WCAG is organized around four principles: Perceivable, Operable, Understandable, Robust (POUR) — use this mnemonic when reviewing any PR
        • +
      • Most projects target WCAG 2.2 AA — when a reviewer cites a criterion number like 1.4.3, search the tables in Section 3 of this appendix
        • +
      • The WCAG Quick Reference (Section 10) is a filterable web page — use your screen reader's find command to jump to any criterion number
        • +
      +
      + +
      +Low vision users + +
        +
      • The tables in this appendix use pipe-delimited Markdown — increase your editor font size or use a Markdown preview for cleaner column alignment
        • +
      • WCAG 1.4.3 (contrast) and 1.4.11 (non-text contrast) are the criteria most relevant to your daily experience — bookmark them
        • +
      • When checking contrast ratios, use the WebAIM Contrast Checker link in Section 10 with your browser zoom set to your preferred level
        • +
      +
      + +
      +Sighted users + +
        +
      • The POUR table in this section is your one-glance cheat sheet — scan the Example Failure column to see what each principle looks like when violated
        • +
      • Conformance level badges (A, AA, AAA) appear in the Level column of the Section 3 tables — AA rows are your primary targets
        • +
      • Bookmark the ARIA Authoring Practices Guide link in Section 10 for live interactive pattern demos
        • +
      +
      + + +

      2. Conformance Levels: A, AA, AAA

      + + + + + + + + + + + + + + + + + + + + + + + +
      LevelRequirementWho targets this
      AMinimum accessibility - the baseline that removes the most severe barriersRequired by most accessibility laws
      AAEnhanced accessibility - removes significant barriersRequired by WCAG 2.2 compliance targets, most government and enterprise standards, GitHub's own accessibility commitment
      AAAHighest level - removes remaining barriers for the most niche casesNot universally required; applied where feasible
      +

      Most open source projects, and GitHub itself, target WCAG 2.2 AA compliance. When you file an accessibility bug or review a PR, AA is the standard to reference.

      +

      3. Key Success Criteria for Web Contributions

      +

      These are the criteria you will most commonly encounter when contributing to web projects or reviewing GitHub interface changes.

      +

      Perceivable

      + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + +
      CriterionLevelWhat It Requires
      1.1.1 Non-text ContentAAll images, icons, and non-text content have a text alternative (alt attribute, aria-label, etc.)
      1.3.1 Info and RelationshipsAStructure conveyed visually (headings, lists, tables) is also conveyed programmatically
      1.3.2 Meaningful SequenceAReading order makes sense when CSS is removed
      1.3.3 Sensory CharacteristicsAInstructions do not rely solely on shape, color, or position ("click the green button" fails this)
      1.4.1 Use of ColorAColor is not the only means of conveying information
      1.4.3 Contrast (Minimum)AAText has at least 4.5:1 contrast ratio against its background (3:1 for large text)
      1.4.4 Resize TextAAText can be resized up to 200% without loss of content or function
      1.4.10 ReflowAAContent reflows at 400% zoom without horizontal scrolling
      1.4.11 Non-text ContrastAAUI components and graphical objects have at least 3:1 contrast
      +

      Operable

      + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + +
      CriterionLevelWhat It Requires
      2.1.1 KeyboardAAll functionality is available via keyboard
      2.1.2 No Keyboard TrapAKeyboard focus can always be moved away from any component
      2.4.1 Bypass BlocksAA mechanism to skip repeated navigation (skip link)
      2.4.2 Page TitledAPages have descriptive titles
      2.4.3 Focus OrderAFocus follows a logical sequence
      2.4.4 Link PurposeALink text describes the destination ("Read more about issues" not just "Read more")
      2.4.6 Headings and LabelsAAHeadings and labels describe their topic or purpose
      2.4.7 Focus VisibleAAKeyboard focus indicator is visible
      2.4.11 Focus AppearanceAA (2.2 new)Focus indicator meets minimum size and contrast
      2.5.3 Label in NameAFor controls with visible labels, the accessible name contains the visible text
      +

      Understandable

      + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + +
      CriterionLevelWhat It Requires
      3.1.1 Language of PageAThe default language is identified in the HTML (lang attribute)
      3.2.1 On FocusAReceiving focus does not trigger unexpected context changes
      3.2.2 On InputAChanging a setting does not cause unexpected changes unless the user is warned
      3.3.1 Error IdentificationAInput errors are identified and described in text
      3.3.2 Labels or InstructionsALabels or instructions are provided when user input is required
      3.3.3 Error SuggestionAAWhen an error is detected, suggestions for correction are provided
      +

      Robust

      + + + + + + + + + + + + + + + + + + + + + + + +
      CriterionLevelWhat It Requires
      4.1.1 ParsingAHTML/markup does not have errors that break AT interpretation
      4.1.2 Name, Role, ValueAAll UI components have accessible names, roles, and states that can be programmatically determined
      4.1.3 Status MessagesAAStatus messages (e.g. "item added to cart") are announced without receiving focus
      +

      4. ARIA - Roles, States, and Properties

      +

      WAI-ARIA (Accessible Rich Internet Applications) fills the gap between what HTML natively expresses and what complex interactive widgets require.

      +

      Three categories

      + + + + + + + + + + + + + + + + + + + + + + + +
      CategoryPurposeExamples
      RolesWhat the element isrole="button", role="dialog", role="tab"
      StatesCurrent condition (can change)aria-expanded="false", aria-checked="true", aria-disabled="true"
      PropertiesStable characteristicsaria-label="Close dialog", aria-required="true", aria-describedby="hint-text"
      +

      Important rules

      +
        +
      1. Don't use ARIA if native HTML suffices. A <button> is already a button - adding role="button" to a <div> is only needed when HTML semantics cannot be used.
        2. +
      2. All interactive ARIA widgets must be keyboard operable. Adding role="button" means you must also handle Enter and Space keypresses in JavaScript.
        3. +
      3. ARIA only affects the accessibility tree. It does not add visual styling or behavior - it only changes what assistive technologies announce.
        4. +
      +

      5. ARIA Landmark Roles

      +

      Landmarks let screen reader users jump directly to major sections of a page. GitHub uses these extensively; screen reader users navigate between them with D (NVDA/JAWS) or the Rotor (VoiceOver).

      + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + +
      RoleHTML EquivalentPurpose
      banner<header>Site-wide header
      navigation<nav>Navigation links
      main<main>Primary page content
      complementary<aside>Supporting content
      contentinfo<footer>Footer with copyright, links
      search<search>Search functionality
      form<form> (with accessible name)A significant form region
      region<section> (with accessible name)A generic landmark with a label
      +

      When multiple landmarks of the same type appear on a page, each should have a unique aria-label so screen readers can distinguish them. GitHub's Issues list page, for example, has multiple navigation regions each with distinct labels.

      +

      6. Common ARIA Patterns

      +

      Accessible Button (when <button> cannot be used)

      +
      <div role="button" tabindex="0" aria-pressed="false" onclick="toggle()" onkeydown="handleKey(event)">
+  Toggle
+</div>
      +

      Accessible Form Field with Error

      +
      <label for="username">Username</label>
+<input id="username" type="text" aria-describedby="username-error" aria-invalid="true">
+<span id="username-error" role="alert">Username cannot be empty</span>
      +

      Live Region (status announcements)

      +
      <div aria-live="polite" aria-atomic="true">
+  <!-- Content inserted here is announced automatically -->
+  3 results found
+</div>
      +

      Use aria-live="assertive" only for urgent interruptions (errors). Use "polite" for non-urgent status updates.

      +

      Expandable Section

      +
      <button aria-expanded="false" aria-controls="details-panel">
+  Show details
+</button>
+<div id="details-panel" hidden>
+  ...content...
+</div>
      +

      When expanded: set aria-expanded="true" and remove the hidden attribute.

      +

      7. How Standards Apply to GitHub Contributions

      +

      When you contribute to an open source project on GitHub, you will encounter accessibility in several contexts:

      +

      Filing an Accessibility Bug

      +

      Reference the specific WCAG criterion. This makes the bug actionable:

      +
      +

      Bad: "The button isn't accessible."
      Good: "The 'Subscribe' button has no visible focus indicator, failing WCAG 2.4.7 Focus Visible (Level AA). When navigating by keyboard, there is no visual indication of where focus is."

      +
      +

      Reviewing a PR for Accessibility

      +

      Checklist for any PR that touches HTML or UI:

      +
        +
      • Do new images have alt attributes?
        • +
      • Do new interactive elements work with keyboard only?
        • +
      • Do new form fields have associated <label> elements?
        • +
      • Are any new color-only indicators present?
        • +
      • Does new dynamic content use aria-live if it updates without a page load?
        • +
      +

      Writing Accessible Documentation

      +

      Documentation in Markdown is converted to HTML. Accessible Markdown:

      +
        +
      • Use heading levels in order (don't skip from H1 to H3)
        • +
      • Write descriptive link text (not "click here")
        • +
      • Add alt text to images: ![Bar chart showing 40% improvement in task completion](chart.png)
        • +
      • Use actual lists (- or 1.) rather than faking them with symbols
        • +
      +

      8. Testing Against Standards

      +

      Automated Tools (catch ~30-40% of issues)

      + + + + + + + + + + + + + + + + + + + + + + + +
      ToolUse
      axe DevToolsBrowser extension - run on any page, get WCAG violations with criterion references
      WAVEBrowser extension or web service - visual overlay showing issues
      LighthouseBuilt into Chrome DevTools - accessibility audit with scores
      IBM Equal Access CheckerEnterprise-grade browser extension
      +

      Manual Testing (catches the rest)

      +
        +
      1. Keyboard-only navigation - unplug your mouse; can you do everything?
        2. +
      2. Screen reader walkthrough - navigate the feature with NVDA, JAWS, or VoiceOver
        3. +
      3. 200% zoom - does content reflow without horizontal scrolling?
        4. +
      4. High contrast mode - Windows High Contrast or macOS Increase Contrast; are all elements still visible?
        5. +
      5. Disable CSS - does the content still make sense in reading order?
        6. +
      +

      Learning Cards: Testing Against Standards

      +
      +Screen reader users + +
        +
      • You are the manual test — automated tools catch only 30-40% of issues; your screen reader walkthrough catches the rest
        • +
      • Install the axe DevTools browser extension (Section 8 table) and run it on any page; results are announced as a list of violations with WCAG criterion references
        • +
      • When doing a keyboard-only navigation test, press Tab repeatedly and listen — every interactive element should announce its name and role
        • +
      +
      + +
      +Low vision users + +
        +
      • The 200% zoom test (item 3) mirrors your daily experience — if content breaks at 200%, file a bug citing WCAG 1.4.4 Resize Text
        • +
      • Windows High Contrast mode test (item 4) is one click: Settings, Accessibility, Contrast themes — switch and check that all UI elements remain visible
        • +
      • The WAVE browser extension overlays icons on the page showing errors and warnings — zoom in to read the small annotation labels
        • +
      +
      + +
      +Sighted users + +
        +
      • The Lighthouse accessibility audit (Chrome DevTools, Ctrl+Shift+I, Lighthouse tab) gives a 0-100 score — aim for 90+ on any page you contribute to
        • +
      • For the keyboard-only test, unplug your mouse and try completing every action — watch for the blue focus ring moving logically through the page
        • +
      • The automated vs. manual split (30-40% / 60-70%) means green CI checks do not guarantee accessibility — always pair tool output with a quick manual review
        • +
      +
      + + +

      9. Quick Reference: What to Check in a PR

      + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + +
      CheckWCAG Criterion
      New images have alt text1.1.1
      Heading levels are in order1.3.1
      Links have descriptive text2.4.4
      Interactive elements are keyboard accessible2.1.1
      Focus is visible on all interactive elements2.4.7
      Form fields have labels1.3.1, 3.3.2
      Error messages are descriptive3.3.1, 3.3.3
      Color is not the only indicator1.4.1
      Dynamic content updates use aria-live4.1.3
      New UI components have name, role, value4.1.2
      +

      10. Official References

      + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + +
      ResourceURL
      WCAG 2.2 Full Specificationw3.org/TR/WCAG22
      WCAG 2.2 Quick Referencew3.org/WAI/WCAG22/quickref
      Understanding WCAG 2.2w3.org/WAI/WCAG22/Understanding
      WAI-ARIA 1.2 Specificationw3.org/TR/wai-aria-1.2
      ARIA Authoring Practices Guidew3.org/WAI/ARIA/apg
      WebAIM Contrast Checkerwebaim.org/resources/contrastchecker
      MDN Accessibilitydeveloper.mozilla.org/en-US/docs/Web/Accessibility
      GitHub Accessibilityaccessibility.github.com
      +
      +

      Next: Appendix N: Advanced Search
      Back: Appendix L: Agents Reference
      Teaching chapter: Chapter 08: Open Source Culture

      + +
      + + + + diff --git a/html/admin/qa-bundle/docs/appendix-n-advanced-search.html b/html/admin/qa-bundle/docs/appendix-n-advanced-search.html new file mode 100644 index 00000000..905cb6ba --- /dev/null +++ b/html/admin/qa-bundle/docs/appendix-n-advanced-search.html @@ -0,0 +1,494 @@ + + + + + + + Appendix N: GitHub Advanced Search - GIT Going with GitHub + + + + + + + + +
      +

      Appendix N: GitHub Advanced Search

      +
      +

      Listen to Episode 27: Advanced Search - a conversational audio overview of this chapter. Listen before reading to preview the concepts, or after to reinforce what you learned.

      +
      +
      +

      Reference companion to: Chapter 05: Working with Issues | Also relevant: Chapter 09

      +

      Authoritative source: GitHub Docs: Searching on GitHub

      +
      +

      Finding Anything Across All of GitHub

      +
      +

      GitHub's search engine is powerful and underused. For screen reader users in particular, using the search bar with precise query syntax is often faster and more accessible than navigating filter dropdowns and checkbox menus. This reference covers the query language so you can filter anything from the keyboard.

      +
      +

      Table of Contents

      +
        +
      1. The Search Interface
        2. +
      2. Search Scopes
        3. +
      3. The Core Query Language
        4. +
      4. Searching Issues and Pull Requests
        5. +
      5. Searching Code
        6. +
      6. Searching Commits
        7. +
      7. Searching Repositories
        8. +
      8. Searching Users and Organizations
        9. +
      9. Practical Queries for This Workshop
        10. +
      10. Saving and Reusing Searches
        11. +
      +

      1. The Search Interface

      +

      GitHub's search is accessible from nearly any page:

      +
        +
      • Global search bar: At the top of every GitHub page - keyboard shortcut / to focus it from anywhere (press /, then type)
        • +
      • Issues/PRs list: Each tab has its own search bar pre-scoped to that repository
        • +
      • Advanced Search UI: github.com/search/advanced - a form with individual fields for each filter. Accessible but verbose; query syntax below is faster.
        • +
      + +
      / → Focus the global search bar (works on most GitHub pages)
+Type your query → Enter
+→ Results page opens, grouped by type (Code, Issues, PRs, Repositories, etc.)
      +

      Learning Cards: The Search Interface

      +
      +Screen reader users + +
        +
      • Press / on any GitHub page to jump straight to the global search bar — no Tab hunting required
        • +
      • After pressing Enter on a query, results are grouped by type under headings (Code, Issues, PRs, Repositories) — use H to jump between groups
        • +
      • Query syntax typed directly in the search bar is often faster and more accessible than the Advanced Search form at github.com/search/advanced
        • +
      +
      + +
      +Low vision users + +
        +
      • The search bar sits at the very top of every GitHub page — if you lose it at high zoom, press / to refocus instantly
        • +
      • Search results use bold text for matched terms — increase browser zoom to make the highlighted keywords easier to spot
        • +
      • Pin the Advanced Search page (github.com/search/advanced) as a bookmark for days when you prefer large labeled form fields over compact query syntax
        • +
      +
      + +
      +Sighted users + +
        +
      • Look for the search bar in the top navigation bar — it shows a / hint icon on the right to remind you of the keyboard shortcut
        • +
      • After submitting a query, use the left sidebar type filters (Code, Issues, PRs, etc.) to narrow results visually
        • +
      • GitHub highlights matched keywords in yellow within search results — scan for those highlights to evaluate relevance quickly
        • +
      +
      + + +

      2. Search Scopes

      +

      By default, GitHub searches across all of GitHub. Scope modifiers restrict results:

      + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + +
      ModifierScope
      repo:owner/nameOne specific repository
      org:orgnameAll repos in an organization
      user:usernameAll repos owned by a user
      in:titleOnly matches in the title field
      in:bodyOnly matches in the body field
      in:commentsOnly matches in comments
      +

      Example: repo:community-access/accessibility-agents in:title keyboard finds issues/PRs whose titles mention "keyboard" in the accessibility-agents repo.

      +

      3. The Core Query Language

      +

      Boolean Logic

      + + + + + + + + + + + + + + + + + + + + + + + + + + + +
      SyntaxMeaning
      word1 word2Both words (implicit AND)
      word1 OR word2Either word
      "exact phrase"Exact phrase match
      -wordExclude this word
      -label:bugExclude items with this label
      +

      Common Qualifiers

      + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + +
      QualifierMeaning
      is:openOpen items only
      is:closedClosed items only
      is:mergedMerged PRs only
      is:unmergedOpen or closed but not merged PRs
      is:issueIssues only
      is:prPull requests only
      is:draftDraft pull requests only
      label:nameItems with this label
      no:labelItems with no labels
      assignee:@meAssigned to you
      assignee:usernameAssigned to a specific user
      author:@meCreated by you
      author:usernameCreated by a specific user
      mentions:usernameMentions a specific user
      involves:@meYou are author, assignee, mentioned, or commented
      milestone:"Milestone Name"In a specific milestone
      no:milestoneNot in any milestone
      no:assigneeNot assigned to anyone
      comments:>5More than 5 comments
      reactions:>10More than 10 reactions
      +

      Date Qualifiers

      + + + + + + + + + + + + + + + + + + + + + + + + + + + +
      QualifierMeaning
      created:>2025-01-01Created after a date
      created:<2025-01-01Created before a date
      created:2025-01-01..2025-03-31Created in a date range
      updated:>2025-06-01Updated after a date
      closed:>2025-06-01Closed after a date
      +

      4. Searching Issues and Pull Requests

      +

      Going to the Issues search directly

      +

      GitHub's issue/PR search is at github.com/issues (your issues) or github.com/pulls (your PRs). The search bar there is pre-scoped to "repos you have access to involving you."

      +

      Practical queries

      +

      Find all unassigned, open accessibility issues across an org

      +
      org:community-access is:issue is:open label:accessibility no:assignee
      +

      Find good first issues in any language

      +
      is:issue is:open label:"good first issue" no:assignee
      +

      Find good first issues in a specific language

      +
      is:issue is:open label:"good first issue" language:python no:assignee
      +

      Find all PRs you need to review

      +
      is:pr is:open review-requested:@me
      +

      Find all open PRs where you were mentioned

      +
      is:pr is:open mentions:@me
      +

      Find your open issues across all repos

      +
      is:issue is:open author:@me
      +

      Find issues that are stale (open, not updated in 6+ months)

      +
      is:issue is:open repo:owner/name updated:<2024-08-01
      +

      Learning Cards: Searching Issues and Pull Requests

      +
      +Screen reader users + +
        +
      • The is:pr is:open review-requested:@me query is your daily go-to — it lists every PR waiting for your review without navigating the Pulls tab
        • +
      • Combine assignee:@me with is:open to get your personal task list announced as a simple results list
        • +
      • Use in:title or in:body qualifiers to avoid noisy matches buried in long comment threads
        • +
      +
      + +
      +Low vision users + +
        +
      • Bookmark the URL after running a search — the full query is encoded in the address bar so you can reuse it without retyping
        • +
      • The Issues search page (github.com/issues) pre-scopes to your repos — at high zoom this single-column list is easier to scan than a full global search
        • +
      • Results show labels as colored badges next to each title — zoom in or hover to read the label text if the color alone is hard to distinguish
        • +
      +
      + +
      +Sighted users + +
        +
      • The left sidebar on the search results page lets you toggle between Issues and PRs with one click — use it to refine without editing your query
        • +
      • Look for the green (open), purple (merged), or red (closed) state icons next to each result for quick visual triage
        • +
      • Star or bookmark the "good first issue" query from Section 4 — it is the fastest way to find your next contribution
        • +
      +
      + + +

      5. Searching Code

      +

      Code search operates differently from issue search. As of 2024, GitHub uses an improved code search engine (sometimes called "code search v2") with better indexing.

      + +
      repo:owner/name language:javascript aria-label
      +

      Find uses of a function across a repo

      +
      repo:owner/name symbol:handleKeyDown
      +

      Find a pattern across all repos in an org

      +
      org:community-access aria-hidden="true"
      +

      Code search qualifiers

      + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + +
      QualifierMeaning
      language:pythonFilter by programming language
      path:src/Only files under this path
      filename:config.ymlOnly files with this name
      extension:mdOnly files with this extension
      symbol:functionNameSearch for a specific symbol/function name
      content:"exact string"Exact string match in file content
      +

      6. Searching Commits

      +

      Find commits with a keyword in the message

      +
      repo:owner/name fix keyboard navigation
      +

      Find commits by a specific author

      +
      repo:owner/name author:username
      +

      Find commits in a date range

      +
      repo:owner/name committer-date:2025-01-01..2025-03-31
      +

      Find commits that touched a specific file

      +
      repo:owner/name path:docs/README.md
      +

      7. Searching Repositories

      +

      Find accessible repos by topic

      +
      topic:accessibility stars:>50 is:public
      +

      Find repos with a specific language, sorted by stars

      +
      language:typescript topic:screen-reader sort:stars-desc
      +

      Repository qualifiers

      + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + +
      QualifierMeaning
      stars:>100More than 100 stars
      forks:>10More than 10 forks
      is:publicPublic repos only
      is:privatePrivate repos only (requires access)
      topic:topicnameRepos tagged with this topic
      license:mitRepos with an MIT license
      size:<1000Repos smaller than 1000 KB
      pushed:>2025-01-01Repos with recent activity
      +

      8. Searching Users and Organizations

      +

      Find users

      +
      type:user location:Seattle followers:>100
      +

      Find organizations

      +
      type:org topic:accessibility
      +

      9. Practical Queries for This Workshop

      +

      Bookmark these for use during the hackathon:

      +

      Find open contributions you can make right now in accessibility-agents

      +
      repo:community-access/accessibility-agents is:issue is:open label:"good first issue" no:assignee
      +

      Check whether your issue is already filed

      +
      repo:community-access/accessibility-agents is:issue keyboard navigation
      + +
      repo:community-access/accessibility-agents is:issue label:accessibility is:open
      +

      See all your merged PRs (proof of contribution)

      +
      is:pr is:merged author:@me
      +

      Find recent discussions about a topic

      +
      repo:community-access/accessibility-agents in:discussions screen reader
      +

      10. Saving and Reusing Searches

      +

      GitHub does not have a built-in saved-search feature, but you can:

      +
        +
      1. Bookmark the URL - every search result page has the query in the URL. Bookmark it in your browser for instant re-run.
        2. +
      2. Pin in notifications - if you're watching a repo, set up notification filters
        3. +
      3. Accessibility Agents - use /my-issues and /my-prs for your personal saved-search equivalents without leaving VS Code
        4. +
      +

      Example bookmarkable URL

      +
      https://github.com/issues?q=is%3Aissue+is%3Aopen+assignee%3A%40me
      +
      +

      Next: Appendix O: Branch Protection
      Back: Appendix M: Accessibility Standards
      Teaching chapter: Chapter 05: Working with Issues

      + +
      + + + + diff --git a/html/admin/qa-bundle/docs/appendix-o-branch-protection.html b/html/admin/qa-bundle/docs/appendix-o-branch-protection.html new file mode 100644 index 00000000..4305b040 --- /dev/null +++ b/html/admin/qa-bundle/docs/appendix-o-branch-protection.html @@ -0,0 +1,469 @@ + + + + + + + Appendix O: Branch Protection Rules and Repository Rulesets - GIT Going with GitHub + + + + + + + + +
      +

      Appendix O: Branch Protection Rules and Repository Rulesets

      +
      +

      Listen to Episode 28: Branch Protection and Rulesets - a conversational audio overview of this chapter. Listen before reading to preview the concepts, or after to reinforce what you learned.

      +
      +
      +

      Reference companion to: Chapter 08: Open Source Culture | Also relevant: Chapter 14

      +

      Authoritative source: GitHub Docs: Protected branches

      +
      +

      How Merging Rules Work and Why Your PR May Be Blocked

      +
      +

      Who this is for: Contributors who have submitted a PR and are wondering why it cannot be merged yet, as well as workshop facilitators who configure branch protection for practice repositories.

      +
      +

      Quick Navigation

      +
        +
      1. What Branch Protection Does
        2. +
      2. Common Branch Protection Rules
        3. +
      3. Repository Rulesets - The Modern Approach
        4. +
      4. Why Your PR Cannot Be Merged - Diagnosis Guide
        5. +
      5. Navigating the Merge Box with a Screen Reader
        6. +
      6. Status Checks - What They Are and What They Mean
        7. +
      7. Who Can Configure Branch Protection
        8. +
      8. Workshop Repository Configuration Reference
        9. +
      +

      1. What Branch Protection Does

      +

      A branch protection rule is a set of requirements that must be satisfied before a PR can be merged into a specific branch (typically main). Branch protection exists to:

      +
        +
      • Require that code is reviewed before it enters the default branch
        • +
      • Require that automated tests pass before merging
        • +
      • Prevent direct pushes to main without a PR
        • +
      • Ensure the branch is up-to-date before merging
        • +
      • Require commits to be signed (GPG or SSH signatures)
        • +
      +

      Think of branch protection as the quality gate for a repository's primary branch.

      +

      Learning Cards: What Branch Protection Does

      +
      +Screen reader users + +
        +
      • The merge box at the bottom of every PR page is where branch protection surfaces its requirements — press End to jump to the bottom, then use H to find the merge heading
        • +
      • Each requirement is announced as a status line: "1 review required," "Some checks haven't completed yet," etc. — listen for these before attempting to merge
        • +
      • If the Merge button says "disabled" or "grayed out," branch protection is blocking — the status lines immediately above explain exactly what is needed
        • +
      +
      + +
      +Low vision users + +
        +
      • The merge box uses green (ready), yellow (pending), and red (blocked) indicators — zoom in on the merge area to read the text labels next to each colored icon
        • +
      • The "Update branch" button appears as a secondary button above the merge button when your PR is behind main — it can be easy to miss at high zoom
        • +
      • Required checks show checkmark or X icons that are small at default size — browser zoom to 150%+ makes the pass/fail status easier to distinguish
        • +
      +
      + +
      +Sighted users + +
        +
      • Look at the bottom of the PR Conversation tab for the merge box — a green "Merge pull request" button means all requirements are met; grey means something is blocking
        • +
      • The list of requirements appears as a vertical checklist above the merge button — each item shows a green checkmark, yellow spinner, or red X
        • +
      • Click "Show all checks" to expand the full list of status checks if only a summary is visible
        • +
      +
      + + +

      2. Common Branch Protection Rules

      +

      Required Reviews

      +

      The most common rule. The maintainer requires a minimum number of approving reviews before the PR can be merged.

      +

      Example: "Require 1 approving review"

      +

      What this means for you:

      +
        +
      • Your PR shows a "1 review required" notice in the merge box
        • +
      • If a reviewer requests changes, their approval is revoked - you need at least one new approval after your latest push
        • +
      • After you push new commits, re-request review from the original reviewer
        • +
      +

      Dismiss stale reviews: Some repos have this enabled - whenever you push a new commit, all existing approvals are automatically withdrawn and you need a fresh review. This prevents sneaking in bad code after approval.

      +

      Required Status Checks

      +

      Automated workflows (GitHub Actions or third-party CI) must complete successfully before merging is allowed.

      +

      Example checks you may see

      +
        +
      • ci / build - compiles the code
        • +
      • ci / test - runs the test suite
        • +
      • lint - code style checks
        • +
      • accessibility-check - automated accessibility scanning
        • +
      • CodeQL - security analysis
        • +
      • netlify/deploy-preview - preview deployment must succeed
        • +
      +

      What "Required" means: The merge button is grayed out (or shows an error) until all required checks show a green checkmark. A failing or pending check blocks the merge.

      +

      Require Branches to Be Up to Date

      +

      Before merging, your PR branch must include all changes from main. This prevents merge conflicts from being introduced silently.

      +

      If your PR is behind main:

      +
        +
      • The merge box shows: "This branch is out of date with the base branch"
        • +
      • Button: "Update branch" - merges current main into your branch
        • +
      • Alternative: Rebase your branch (only if the maintainer permits rebase merges)
        • +
      +

      Require Signed Commits

      +

      All commits in the PR must have a Verified badge (see Appendix D: Git Authentication). If your commits are unverified, the PR cannot be merged until you re-commit with signing enabled.

      +

      Require Linear History

      +

      Only squash merges or rebase merges are permitted - no merge commits. This keeps the commit history linear and readable.

      +

      If you see: "This repository requires a linear history" - the maintainer will squash or rebase merge your PR, not create a merge commit.

      +

      Lock Branch

      +

      A locked branch cannot receive any merges - it is effectively read-only. This is sometimes used for archived repositories or during release freezes.

      +

      3. Repository Rulesets - The Modern Approach

      +

      Repository Rulesets (introduced in late 2023) are the next generation of branch protection. They extend branch protection rules with:

      +
        +
      • Organization-level rules - apply across all repos in an org from one place
        • +
      • Bypass lists - specific users or roles can be exempted from rules (e.g., release bots)
        • +
      • Target multiple branches - one ruleset can target a pattern like release/* or v*
        • +
      • Violation insights - audit log of when rules were bypassed and by whom
        • +
      • Rule enforcement - Active (enforced), Evaluate (only log violations, don't block), Disabled
        • +
      +

      Rulesets vs. Branch Protection Rules

      + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + +
      FeatureBranch Protection RulesRepository Rulesets
      ScopeSingle branch, single repoPatterns, multi-branch, cross-org
      BypassNo bypass capabilityConfigurable bypass list
      Enforcement modesActive onlyActive, Evaluate, Disabled
      Organization-levelNoYes (org rulesets)
      StatusClassic (still supported)Current/modern approach
      +

      Most repositories you encounter still use classic branch protection rules. Rulesets will become more common as maintainers migrate.

      +

      Finding and Reading Rulesets

      +

      If you want to understand why certain rules apply to a branch:

      +
      Repository → Insights tab → Rulesets (if you have access - contributors usually don't)
+Or: Repository → Settings → Rules → Rulesets (admin only)
      +

      Alternatively, PR merge box messages describe which rules are blocking - you don't need admin access to understand what's required.

      +

      4. Why Your PR Cannot Be Merged - Diagnosis Guide

      +

      When you open a PR and the merge button is grayed out or shows an error, the merge box tells you exactly what needs to happen. Here is how to read it.

      +

      "X review required / X reviews required"

      +

      What it means: The required number of approvals hasn't been reached yet.

      +

      What to do

      +
        +
      1. Request review from a codeowner or maintainer (right sidebar → Reviewers → request)
        2. +
      2. Check if any reviews exist but requested changes - those count against you
        3. +
      3. Wait for the reviewer to submit their review
        4. +
      4. Respond to requested changes by pushing new commits, then re-requesting review
        5. +
      +

      "Some checks haven't completed yet" or "Some checks were not successful"

      +

      What it means: A required status check is pending or failing.

      +

      What to do

      +
        +
      1. Scroll down to the merge box - expand "Show all checks"
        2. +
      2. Find the failing check → click "Details" to see the full log
        3. +
      3. Fix the underlying issue (test failure, lint error, build error) in your branch
        4. +
      4. Push new commits - checks re-run automatically
        5. +
      5. Wait for checks to complete (typically 1-5 minutes for most CI)
        6. +
      +

      If checks pass on main but fail on your PR: The issue is specific to your changes. Read the check log carefully.

      +

      If checks are stuck "in progress" for over 30 minutes: The workflow runner may have an issue - contact the maintainer.

      +

      "This branch is out of date with the base branch"

      +

      What it means: New commits were pushed to main after you created your PR branch. The maintainer requires everything to be current.

      +

      What to do

      +
        +
      • Click "Update branch" in the merge box - GitHub does a merge commit from main into your branch
        • +
      • Or locally: git fetch upstream && git rebase upstream/main then force-push (only if you are comfortable with rebase)
        • +
      +

      "Commits must have verified signatures"

      +

      What it means: Branch protection requires signed commits (see Appendix D: Git Authentication).

      +

      What to do

      +
        +
      1. Enable commit signing locally before making more commits
        2. +
      2. For existing unsigned commits, you need to rebase-rewrite them - this is advanced; ask the maintainer if there is a workaround
        3. +
      +

      "Merging is blocked"

      +

      What it means: A ruleset or branch protection has explicitly blocked merging for a reason not covered by other messages. Check the PR for a pinned comment from the mergeable status check or a GitHub Actions check that posts a comment explaining the block.

      +

      Learning Cards: Why Your PR Cannot Be Merged

      +
      +Screen reader users + +
        +
      • Navigate to the merge box (End key, then H key to find "Merge" heading) and read each status line with arrow keys — the messages tell you exactly what action to take
        • +
      • When a check fails, Tab to the "Details" link next to the failing check name and press Enter to open the log — use Ctrl+F to search for "error" or "failed"
        • +
      • After pushing a fix, the checks re-run automatically — return to the PR page and listen for the status to change from "pending" to "passed"
        • +
      +
      + +
      +Low vision users + +
        +
      • Failed checks show a red X icon that can be tiny — zoom to 150%+ and look for the word "failing" or "failed" next to each check name
        • +
      • The "Update branch" button (for out-of-date PRs) is a secondary action that blends in at low zoom — look for it directly above the main merge button
        • +
      • The Details link next to each check opens a log page with monospace text — increase your editor or browser font size before reading long CI logs
        • +
      +
      + +
      +Sighted users + +
        +
      • Scroll to the bottom of the PR page and scan the checklist in the merge box — red X items are blocking, yellow spinners are still running, green checks are done
        • +
      • Click the "Details" link next to any red X to see the full error log — the failing step is highlighted with a red icon in the left sidebar
        • +
      • If "This branch is out of date," click the blue "Update branch" button and wait for checks to re-run before merging
        • +
      +
      + + +

      5. Navigating the Merge Box with a Screen Reader

      +

      The merge box lives at the bottom of every PR page. With a screen reader, navigating to it efficiently is important.

      +

      Reaching the Merge Box

      +
      PR page → End key (jump to bottom of page)
+Or: B key (NVDA Browse Mode) → navigate buttons → look for "Merge pull request" button
+Or: H key → navigate to "Merge" heading area
      +

      Reading the Merge Box Status

      +
      From the merge box area:
+H → section heading ("Merging is blocked" or "This branch has no conflicts")
+↓ → first status message
+↓/Tab → each requirement listed (required reviews, required checks, etc.)
      +

      NVDA specific path

      +
      NVDA+F7 → Elements list → Filter by type: Headings
+Find "Merge" related heading → move focus to that section
+Then ↓ through the section content
      +

      JAWS specific path

      +
      H → navigate to merge section
+Then ↓ key → read each item in the requirements list
      +

      Checking Status Checks

      +
      Merge box area → Tab → "Show all checks" link or button → Enter
+Expands to show: each check name, its status (passed/failed/pending), "Details" link
+Tab through each check → "Details" link → Enter to open the check log
      +

      Reading Check Details

      +

      The check log is a text-heavy page in a pre-formatted block.

      +
      Check log page: H → "Summary" heading → ↓ to read summary
+To read the full log: F → form controls → step dropdown (if multi-step)
+Or: Tab → each step accordion → Enter to expand → ↓ to read log lines
+Log content is usually in a scrollable region: ↓ key scrolls through lines
      +

      6. Status Checks - What They Are and What They Mean

      +

      Status checks come from two sources:

      +

      GitHub Actions Status Checks

      +

      Defined in .github/workflows/*.yml in the repository. Each job: in a workflow file becomes a status check. Example:

      +
      # .github/workflows/ci.yml
+jobs:
+  test:           ← this creates the "test" status check
+    runs-on: ubuntu-latest
+    steps:
+      - name: Run tests
+        run: npm test
      +

      Third-Party Status Checks

      +

      Services like Netlify, Vercel, Codecov, and Snyk post status checks via the GitHub API. You will recognize them by their app name prefix (e.g., netlify/deploy-preview - Deploy Preview ready).

      +

      Status Check States

      + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + +
      IconStateMeaning
      Yellow circlePendingRunning now or queued
      Green checkmarkSuccessPassed, no issues
      Red XFailureFailed - PR cannot be merged until fixed
      Red circleErrorUnexpected error in the check runner (not your code's fault)
      Grey circleSkippedNot relevant for this PR (conditional run)
      NeutralNeutralInformational - does not block merge
      +

      7. Who Can Configure Branch Protection

      + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + +
      RoleCan view requirementsCan modify requirements
      Public viewerNo (only via PR merge box)No
      ContributorPR merge box onlyNo
      TriagePR merge box onlyNo
      WriteSettings → Rules (read-only in most cases)No
      MaintainYesPartial
      AdminYesYes - full control
      Org adminYesYes - including org-level rulesets
      +

      As a workshop participant, you are typically a contributor to the main community-access/accessibility-agents repo and an admin of your own fork. On your fork, you can configure branch protection however you like - including disabling it entirely for practice purposes.

      +

      8. Workshop Repository Configuration Reference

      +

      The community-access/accessibility-agents repository uses the following branch protection configuration on main:

      + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + +
      RuleSetting
      Required reviews1 approving review
      Dismiss stale reviewsYes - new commits require re-review
      Require status checksci / build and ci / test
      Up-to-date requirementYes
      Signed commitsNo (to reduce friction for workshop participants)
      Restrict direct pushesYes - all changes must come through PRs
      +

      Workshop tip: Your personal fork of accessibility-agents has no branch protection by default. If you want to practice the full "review before merge" workflow with a partner, you can add branch protection to your fork:

      +
      Your fork → Settings → Branches → Add branch protection rule
+Branch name pattern: main
+Check: Require a pull request before merging
+Check: Require approvals → 1
+Save changes
      +

      Then practice opening a PR on your fork and requesting your workshop partner's review.

      + + +
      +

      Next: Appendix P: Security Features
      Back: Appendix N: Advanced Search
      Teaching chapter: Chapter 08: Open Source Culture

      + +
      + + + + diff --git a/html/admin/qa-bundle/docs/appendix-p-security-features.html b/html/admin/qa-bundle/docs/appendix-p-security-features.html new file mode 100644 index 00000000..97911393 --- /dev/null +++ b/html/admin/qa-bundle/docs/appendix-p-security-features.html @@ -0,0 +1,417 @@ + + + + + + + Appendix P: GitHub Security Features - GIT Going with GitHub + + + + + + + + +
      +

      Appendix P: GitHub Security Features

      +
      +

      Listen to Episode 29: GitHub Security Features - a conversational audio overview of this chapter. Listen before reading to preview the concepts, or after to reinforce what you learned.

      +
      +
      +

      Reference companion to: Chapter 08: Open Source Culture | Also relevant: Chapter 17

      +

      Authoritative source: GitHub Docs: Code security

      +
      +

      Dependabot, Secret Scanning, Code Scanning, and Private Advisories

      +
      +

      Who this is for: Anyone contributing to open source repositories needs to understand how GitHub protects code and what security alerts mean. This appendix explains the GitHub Security and quality tab, how to interpret and respond to alerts, and how to responsibly report vulnerabilities - including in community-access/accessibility-agents.

      +
      +

      Quick Navigation

      +
        +
      1. The Security and quality tab - What It Contains
        2. +
      2. Dependabot - Automated Dependency Updates
        3. +
      3. Secret Scanning - Preventing Credential Leaks
        4. +
      4. Code Scanning and CodeQL
        5. +
      5. Private Vulnerability Reporting
        6. +
      6. The SECURITY.md File
        7. +
      7. Software Bill of Materials (SBOM)
        8. +
      8. Screen Reader Navigation of the Security and quality tab
        9. +
      9. Security and Accessibility Agents
        10. +
      +

      1. The Security and quality tab - What It Contains

      +

      Every GitHub repository has a Security and quality tab in its navigation bar. What you see there depends on whether you are a contributor with elevated access or a public viewer.

      +

      Public viewers see

      +
        +
      • Security policy (if the repo has a SECURITY.md)
        • +
      • The private vulnerability reporting form (if enabled by the maintainer)
        • +
      +

      Contributors with write or admin access see

      +
        +
      • Dependabot alerts
        • +
      • Secret scanning alerts
        • +
      • Code scanning alerts
        • +
      • Security advisories
        • +
      • The ability to manage security settings
        • +
      +

      Screen Reader Path to the Security and quality tab

      +
      On any repository page:
+Tab navigation → secondary nav region → "Security" link → Enter
+Or: G then S (GitHub keyboard shortcut - enable Focus Mode first)
      +

      Learning Cards: The Security and quality tab

      +
      +Screen reader users + +
        +
      • Use G then S (GitHub keyboard shortcut) to jump directly to the Security and quality tab from any repo page — much faster than Tab-navigating the full nav bar
        • +
      • The Security and quality tab content varies by your access level — public viewers see only the security policy and vulnerability reporting form; contributors with write access see alerts
        • +
      • Dependabot alerts, secret scanning alerts, and code scanning alerts are each a separate link inside the Security and quality tab — use K to navigate between them
        • +
      +
      + +
      +Low vision users + +
        +
      • The Security and quality tab link sits in the repository's top navigation bar alongside Code, Issues, PRs, and Actions — zoom in if the tab labels are small
        • +
      • Alert severity badges (Critical, High, Medium, Low) use colored labels — each badge also includes the severity word, so color is not the only indicator
        • +
      • If the Security and quality tab shows "No alerts," that is good news — look for the green shield icon next to the tab name as confirmation
        • +
      +
      + +
      +Sighted users + +
        +
      • Find the Security and quality tab in the repository navigation bar — it shows a shield icon and may display a count badge if alerts exist
        • +
      • Inside the Security and quality tab, the left sidebar lists Dependabot, Secret scanning, and Code scanning as separate pages — click each to see its alert list
        • +
      • A green shield on the repo home page (or no security count badge) means zero open security alerts
        • +
      +
      + + +

      2. Dependabot - Automated Dependency Updates

      +

      Dependabot is GitHub's automated dependency monitoring and update system. It does two things:

      +

      Dependabot Alerts

      +

      When a known security vulnerability (CVE - Common Vulnerability and Exposure) is discovered in a package your project depends on, GitHub creates a Dependabot alert.

      +

      Alert severity levels

      + + + + + + + + + + + + + + + + + + + + + + + + + + + + +
      LevelCVSS Score RangeWhat it means
      Critical9.0-10.0Exploit likely, wide impact - fix immediately
      High7.0-8.9Significant risk - fix this sprint
      Medium4.0-6.9Some risk with specific conditions - schedule fix
      Low0.1-3.9Low likelihood of exploitation - fix when convenient
      +

      What a dependency alert looks like

      +
      Alert: Dependabot alert #5
+Severity: High
+Package: lodash (npm)
+Vulnerable version: < 4.17.21
+Fixed version: 4.17.21
+Advisory: GHSA-35jh-r3h4-6jhm
+Description: Prototype pollution vulnerability allows an attacker to
+modify Object.prototype leading to denial of service or remote code execution.
      +

      What to do as a contributor when you see an alert

      +
        +
      1. Read the advisory to understand the vulnerability scope
        2. +
      2. Check whether the project actually uses the vulnerable code path
        3. +
      3. The fix is almost always: update the dependency to the fixed version
        4. +
      4. Dependabot Security Updates may have already opened a PR - check the PRs tab
        5. +
      +

      Dependabot Security Updates

      +

      If enabled, Dependabot automatically opens a PR to update the vulnerable dependency. The PR will look like:

      +
      Title: Bump lodash from 4.17.20 to 4.17.21
+Author: dependabot[bot]
+Description: Bumps lodash from 4.17.20 to 4.17.21.
+  - Release notes
+  - Changelog
+  - Commits (linked)
      +

      As a contributor with access, reviewing and merging these Dependabot PRs is a high-value, low-risk way to contribute.

      +

      Dependabot Version Updates

      +

      Beyond security fixes, Dependabot can be configured to open PRs keeping all dependencies at their latest versions (not just security fixes). This is configured in .github/dependabot.yml.

      +

      Example dependabot.yml

      +
      version: 2
+updates:
+  - package-ecosystem: "npm"
+    directory: "/"
+    schedule:
+      interval: "weekly"
+    open-pull-requests-limit: 5
      +

      3. Secret Scanning - Preventing Credential Leaks

      +

      Secret scanning detects if you accidentally commit tokens, API keys, passwords, or other credentials to a repository.

      +

      Push Protection (Real-Time Prevention)

      +

      Push Protection intercepts a git push before it reaches GitHub and blocks it if it detects a known secret pattern.

      +

      If your push is blocked:

      +
      remote: error: GH013: Repository rule violations found for refs/heads/main.
+remote: Push cannot contain secrets
+remote:
+remote: - commit: abc123 in file: config.js
+remote:   secret: GitHub Personal Access Token
+remote:   location: line 5
      +

      What to do

      +
        +
      1. Remove the secret from the file immediately
        2. +
      2. Rotate the exposed credential (GitHub will automatically revoke detected GitHub tokens)
        3. +
      3. If it was a false positive, you can bypass with justification - but investigate first
        4. +
      +

      Best practice: Use environment variables for secrets, never hardcode them. Example:

      +
      // BAD - never do this
+const token = "ghp_xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx";
+
+// GOOD
+const token = process.env.GITHUB_TOKEN;
      +

      Secret Scanning Alerts

      +

      For public repositories, GitHub scans all existing commits and creates alerts for any detected secrets. These appear in Security → Secret scanning.

      +

      Priority action: If you find a secret scanning alert in a project you contribute to - especially a token or API key - treat it as urgent. The credential may have been exposed for a long time.

      +

      Learning Cards: Secret Scanning

      +
      +Screen reader users + +
        +
      • If your git push is blocked with "GH013: Repository rule violations found," the terminal output lists the exact file, line number, and secret type — read the error lines carefully
        • +
      • After removing the secret from your code, use environment variables instead (process.env.GITHUB_TOKEN) — your screen reader will confirm the variable name in the code
        • +
      • Secret scanning alerts appear under Security and quality tab, Secret scanning — navigate with T to reach the alert table, then arrow keys to read each row
        • +
      +
      + +
      +Low vision users + +
        +
      • Push Protection error messages appear in your terminal with red text — increase terminal font size to read the file path, line number, and secret type clearly
        • +
      • The secret scanning alert list in the Security and quality tab uses a table layout — zoom in to read the Secret type and Location columns
        • +
      • Environment variable names in code (like process.env.GITHUB_TOKEN) are easier to spot when syntax highlighting is enabled in your editor theme
        • +
      +
      + +
      +Sighted users + +
        +
      • Push Protection errors show a red banner in your terminal with the exact commit, file, and line containing the secret — look for the "secret:" label
        • +
      • In the Security and quality tab, secret scanning alerts are listed with a yellow or red severity icon — click any alert to see the exposed credential's location and revocation status
        • +
      • The code examples in this section show the BAD vs. GOOD pattern — never hardcode tokens; always use environment variables as shown
        • +
      +
      + + +

      4. Code Scanning and CodeQL

      +

      Code scanning uses static analysis to find security vulnerabilities in the code itself (not dependencies). GitHub's built-in tool is CodeQL, which understands the code's logic and can detect:

      +
        +
      • SQL injection risks
        • +
      • Cross-site scripting (XSS) vulnerabilities
        • +
      • Path traversal issues
        • +
      • Insecure cryptography usage
        • +
      • Authentication bypasses
        • +
      • Command injection risks
        • +
      +

      Reading a Code Scanning Alert

      +
      Alert: Uncontrolled format string
+Rule: py/tainted-format-string
+Severity: High
+File: src/utils/logger.py
+Line: 47
+
+Details:
+  logging.info(user_input)  ← user_input flows unsanitized into format string
+
+  Flow:
+  1. User input enters at: request.args.get('message') [line 12]
+  2. Passed to: logger.info(message) [line 47]
+  3. Risk: format string injection if message contains %s, %d patterns
      +

      As a contributor: Code scanning alerts are excellent, well-scoped contribution opportunities. Each alert shows you the exact file, line, and the data flow causing the issue. Fixing it is often a one-line change.

      +

      Where to Find Code Scanning Alerts

      +

      Security and quality tab → Code scanning → filter by severity, rule, or file.

      +

      5. Private Vulnerability Reporting

      +

      When you discover a security vulnerability in a project, never report it as a public issue. A public issue immediately broadcasts the vulnerability to anyone who could exploit it.

      +

      GitHub provides Private Vulnerability Reporting - a disclosure form that sends your report only to the repository's security team, not to the public.

      +

      How to Submit a Private Report

      +
        +
      1. Navigate to the repository's Security and quality tab
        2. +
      2. Select "Report a vulnerability" (this button only appears if the maintainer has enabled private reporting)
        3. +
      3. Fill in the form:
          +
        • Title: Short description of the vulnerability
          • +
        • Description: Detailed explanation, how to reproduce it, and impact
          • +
        • Severity: Your assessment
          • +
        • Affected versions: Which versions are vulnerable
          • +
        • CVSS score: Optional - the Common Vulnerability Scoring System rating
          • +
        +
        4. +
      4. Submit - only the maintainers see your report
        5. +
      +

      The Responsible Disclosure Process

      +

      After you submit:

      +
        +
      1. Maintainers acknowledge your report (typically within 1-7 days for active projects)
        2. +
      2. They may ask follow-up questions in the private advisory thread
        3. +
      3. They develop and test a fix
        4. +
      4. They request a CVE (Common Vulnerability and Exposure) number from GitHub
        5. +
      5. They publish a new release with the fix
        6. +
      6. They publish a public security advisory - you may be credited as the reporter
        7. +
      7. The CVE is published publicly (usually 90 days after report or after the fix is released)
        8. +
      +

      What If the Maintainer Doesn't Respond?

      +

      If a maintainer doesn't respond within a reasonable time (30-90 days is the standard window):

      +
        +
      1. Send a follow-up in the private advisory thread
        2. +
      2. Contact GitHub directly if the issue is critical (GitHub can assist with coordinated disclosure)
        3. +
      3. Follow the project's SECURITY.md for their stated disclosure policy
        4. +
      +

      6. The SECURITY.md File

      +

      A SECURITY.md file at the repository root defines the project's security policy. It typically contains:

      +
        +
      • Supported versions: Which versions receive security patches
        • +
      • Reporting instructions: How to report a vulnerability (email, private advisory form, etc.)
        • +
      • Response timeline: How quickly maintainers aim to respond
        • +
      • Disclosure policy: When the project will publish a fix publicly
        • +
      +

      accessibility-agents's security policy: community-access/accessibility-agents has a SECURITY.md that points to GitHub's private advisory form. If you find a security issue in accessibility-agents - even a potential one - use the private advisory form rather than opening a public issue.

      + +

      From the repository:

      +
        +
      1. Security and quality tab → Policies section → "Security policy" link
        2. +
      2. Or directly: https://github.com/owner/repo/security/policy
        3. +
      +

      Screen reader path:

      +
      Security and quality tab → H → "Policy" heading → Link: "Security policy" → Enter
      +

      7. Software Bill of Materials (SBOM)

      +

      An SBOM is a machine-readable inventory of every component (libraries, packages, dependencies) in a software project. It is increasingly required by enterprise and government organizations for supply chain security compliance.

      +

      Exporting an SBOM from GitHub

      +
        +
      1. Navigate to the repository's Insights tab
        2. +
      2. Select "Dependency graph"
        3. +
      3. Select "Export SBOM" button (top right of the Dependency graph page)
        4. +
      4. GitHub generates a SPDX-format JSON file listing all dependencies with their versions and licenses
        5. +
      +

      This export is useful when:

      +
        +
      • Your organization requires SBOM documentation before adopting an open source dependency
        • +
      • You're auditing a project's complete dependency chain
        • +
      • You want to identify license compatibility for a commercial product
        • +
      +

      8. Screen Reader Navigation of the Security and quality tab

      +

      Reaching the Security and quality tab

      +
      From any repo page:
+Secondary navigation landmark → Tab through: Code, Issues, PRs, Actions, Projects, Wiki, Security
+Or: Focus Mode → G then S (GitHub shortcut)
      + +
      Security and quality tab → select "Dependabot alerts" link
+Alert list is a table: T (NVDA/JAWS Browse Mode) → navigate rows
+Each row: Tab to expand → Enter to open full alert details
+Inside an alert:
+  H → navigate: Alert title, Package details, Description, References headings
+  2 → jump between major sections
+  Links → navigate to the GHSA advisory, the vulnerable package, the Dependabot PR
      + +
      Security and quality tab → select "Code scanning" link
+Alert list: T to find the table → ↑/↓ to navigate rows
+Open an alert: Enter
+Inside the alert:
+  H → Alert title, Description, Code flow, Steps headings
+  Links → navigate to the specific file and line
+  The code flow section shows the path from source to sink:
+  Navigate with ↓ through the flow steps
      +

      The Private Vulnerability Reporting Form

      +
      Security and quality tab → "Report a vulnerability" button → Enter
+Form fields: F or E → cycle through: Title, Description, Severity (select), Versions, CVSS
+Describe field: NVDA+Space → Focus Mode → type → NVDA+Space to leave
+Submit: Tab → "Submit report" button → Enter
      +

      9. Security and Accessibility Agents

      +

      Accessibility Agents' /security-dashboard slash command gives you a quick security overview without visiting the Security and quality tab in the browser:

      +
      /security-dashboard
      +

      Sample output

      +
      ## Security Dashboard - community-access/accessibility-agents
+
+### Dependabot Alerts
+- 0 Critical
+- 1 High: actions/cache < 3.3.2 (fixed: 3.3.3)
+- 2 Medium: misc dependency updates available
+
+### Secret Scanning
+- No active alerts
+
+### Code Scanning
+- Last scan: 2 days ago - 0 new alerts
+
+### Dependabot PRs Open
+- #47: Bump actions/cache from 3.3.1 to 3.3.3
+  "Review and merge to resolve the High severity alert"
+
+### Recommendation
+Action needed: Review PR #47 (5 minutes - single file change)
      +
      +

      Next: Appendix Q: GitHub Actions
      Back: Appendix O: Branch Protection
      Teaching chapter: Chapter 08: Open Source Culture

      + +
      + + + + diff --git a/html/admin/qa-bundle/docs/appendix-q-actions-workflows.html b/html/admin/qa-bundle/docs/appendix-q-actions-workflows.html new file mode 100644 index 00000000..6254dcb3 --- /dev/null +++ b/html/admin/qa-bundle/docs/appendix-q-actions-workflows.html @@ -0,0 +1,721 @@ + + + + + + + Appendix Q: GitHub Actions and Workflows - GIT Going with GitHub + + + + + + + + +
      +

      Appendix Q: GitHub Actions and Workflows

      +
      +

      Listen to Episode 34: GitHub Actions and Workflows - a conversational audio overview of this chapter. Listen before reading to preview the concepts, or after to reinforce what you learned.

      +
      +
      +

      Reference companion to: Chapter 17: Issue Templates | Also relevant: Chapter 19

      +

      Authoritative source: GitHub Docs: Understanding Actions

      +
      +

      Understanding Automation in Open Source Repositories

      +
      +

      Why this matters for you: Every time you open a pull request on a real open source project, automated processes will run. Understanding what they are, what they mean, and what to do when they fail is essential to being a confident contributor.

      +
      +

      Table of Contents

      +
        +
      1. What Is GitHub Actions?
        2. +
      2. Key Vocabulary
        3. +
      3. Where Workflows Live in a Repository
        4. +
      4. The Anatomy of a Workflow File
        5. +
      5. What Triggers a Workflow
        6. +
      6. Understanding Status Checks on Pull Requests
        7. +
      7. Reading the Actions Tab with a Screen Reader
        8. +
      8. Common Workflows You Will Encounter
        9. +
      9. What To Do When a Check Fails
        10. +
      10. Workflow Permissions and Security
        11. +
      11. Accessibility-Focused Workflows
        12. +
      12. Hands-On Activity
        13. +
      13. What We Are NOT Covering (And Where to Learn More)
        14. +
      +

      1. What Is GitHub Actions?

      +

      GitHub Actions is GitHub's built-in automation system. It lets repository maintainers define automated tasks that run in response to things that happen in the repository - like someone opening a pull request, pushing a commit, or filing an issue.

      +

      Think of it as a robot assistant that every repository can optionally configure. That robot watches for specific events and then automatically runs jobs: testing code, checking spelling, scanning for accessibility issues, building documentation, deploying a website, and more.

      +

      As a contributor, you do not need to write workflows. But you will see their results on nearly every pull request you open, and you need to understand what those results mean.

      +

      Learning Cards: What Is GitHub Actions

      +
      +Screen reader users + +
        +
      • Workflow files live in .github/workflows/ — use T (Go to file) on any repo page to search for .yml files in that directory
        • +
      • The Actions tab is in the repository navigation landmark — press D (NVDA/JAWS) to jump between landmarks and find it
        • +
      • You do not need to write YAML to contribute — your job is to read the status check results on your PR and fix any issues they flag
        • +
      +
      + +
      +Low vision users + +
        +
      • The Actions tab icon (a play-button triangle) sits in the repo's top navigation bar — zoom in if the icon-only display is hard to read; the word "Actions" appears next to it
        • +
      • Workflow YAML files use indentation-sensitive syntax — increase your editor font size and enable visible whitespace to distinguish nesting levels
        • +
      • Status check results on your PR use small colored icons (green checkmark, red X, yellow spinner) — zoom to 150%+ to read the text labels beside them
        • +
      +
      + +
      +Sighted users + +
        +
      • Find the Actions tab in the repository's top navigation bar between Projects and Security — a play-button icon marks it
        • +
      • Workflow files are YAML files in .github/workflows/ — open any one in the Code tab to see the triggers (on:) and job steps
        • +
      • On your PR, scroll to the checks section near the merge box to see green checkmarks (passed), red X marks (failed), or yellow spinners (running)
        • +
      +
      + + +

      2. Key Vocabulary

      + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + +
      TermWhat It Means
      WorkflowA complete automated process defined in a YAML file. A repo can have many workflows.
      JobA group of steps that run together, usually on the same machine. A workflow can have multiple jobs.
      StepA single task within a job - running a command, calling an action, etc.
      ActionA reusable unit of automation. Like a plugin. Many are shared publicly on GitHub Marketplace.
      RunnerThe machine (virtual server) that executes a job. GitHub provides free runners.
      Trigger / EventThe thing that causes a workflow to start - a push, a PR, a schedule, etc.
      Status checkThe pass/fail result of a workflow shown on a pull request.
      ArtifactA file produced by a workflow (a build output, a test report, etc.) that can be downloaded.
      SecretAn encrypted variable stored in a repo's settings - used in workflows without exposing sensitive values.
      YAMLThe file format used to write workflow files. Indentation matters.
      on:The YAML key that defines what triggers a workflow.
      runs-on:The YAML key that specifies the runner OS (ubuntu-latest, windows-latest, macos-latest).
      +

      3. Where Workflows Live in a Repository

      +

      Workflow files live in a specific, mandatory location:

      +

      Description

      +

      Workflow files live at your-repository/.github/workflows/. Example files include: ci.yml (runs tests on every push or PR), lint.yml (checks code style), a11y-scan.yml (accessibility scanning), and deploy.yml (deploys the site when code merges to main).

      +

      The .github/ folder is hidden by convention (starts with a dot). To find it:

      +
        +
      • On GitHub.com: The file browser shows it - use T (go to file) or navigate the file table with Ctrl+Alt+Arrow keys
        • +
      • In VS Code: It appears in the Explorer panel - enable "Show Hidden Files" if needed
        • +
      +
      +

      Screen reader tip: The .github folder reads as "dot github." The workflows folder is inside it. File names ending in .yml are YAML workflow files.

      +
      +

      4. The Anatomy of a Workflow File

      +

      Here is a simple, real workflow file. You do not need to write this, but you should be able to read it:

      +
      # .github/workflows/ci.yml
+
+name: CI                          # The display name shown in the Actions tab
+
+on:                               # What triggers this workflow
+  push:
+    branches: [main]              # Run when code is pushed to main
+  pull_request:                   # Run when a PR is opened or updated
+    branches: [main]
+
+jobs:
+  test:                           # The job name (shown in status checks)
+    runs-on: ubuntu-latest        # What operating system to use
+    steps:
+      - name: Check out code
+        uses: actions/checkout@v4 # A reusable action - downloads your repo code
+
+      - name: Set up Node.js
+        uses: actions/setup-node@v4
+        with:
+          node-version: '20'
+
+      - name: Install dependencies
+        run: npm install          # A shell command
+
+      - name: Run tests
+        run: npm test             # Another shell command
      +

      Reading this: The workflow named "CI" runs when code is pushed to main or a PR targets main. It creates one job called test that runs on Linux. That job checks out the code, installs Node.js, installs dependencies, and runs the test suite.

      +

      If npm test exits with an error, the job fails, and that failure shows up as a red on your pull request.

      +

      5. What Triggers a Workflow

      +

      The most common triggers you will encounter as a contributor:

      + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + +
      TriggerWhat Causes It
      pushAny commit pushed to a branch
      pull_requestA PR is opened, updated, synchronized, or reopened
      pull_request_reviewA review is submitted on a PR
      issue_commentA comment is posted on an issue or PR
      scheduleA recurring timer (like a cron job) - e.g., every Monday at 9am
      workflow_dispatchA manual trigger - someone activates a button in the Actions tab
      releaseWhen a new release is published
      merge_groupWhen a PR enters a merge queue
      +

      The most important one for you: pull_request - this is what triggers checks on your PR.

      +

      6. Understanding Status Checks on Pull Requests

      +

      When you open a pull request on a repo that uses GitHub Actions, you will see a section near the bottom of the Conversation tab called checks or status checks.

      +

      What the status indicators mean

      + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + +
      SymbolColorMeaningWhat to do
      Spinning circleYellow/OrangeChecks are running - waitWait for them to complete
      CheckmarkGreenAll required checks passedGood - you may be able to merge
      X (cross)RedOne or more checks failedDo not merge - read the failure
      Slashed circleGreyCheck was skippedUsually fine - skipped by design
      YellowNon-blocking warningReview but may not block merge
      + +

      NVDA / JAWS (browse mode)

      +
        +
      1. Open the pull request Conversation tab
        2. +
      2. Navigate to the section heading for "checks" using H or 2
        3. +
      3. Each check result is announced as a link or button with its name and status
        4. +
      4. Press Enter on a failed check to expand its details
        5. +
      +

      VoiceOver (macOS, Safari)

      +
        +
      1. Use VO+U to open the Rotor
        2. +
      2. Select "Headings" and navigate to the checks section
        3. +
      3. Use VO+Arrow to read through check results
        4. +
      4. Activate a check link with VO+Space
        5. +
      +

      Required vs. non-required checks

      +
        +
      • Required checks must pass before a PR can be merged. A maintainer configures which checks are required in Branch Protection Rules.
        • +
      • Non-required checks are informational - a failure shown in grey/yellow usually won't block a merge.
        • +
      • If you're not sure whether a check is required, look for the phrase "Required" next to the check name.
        • +
      +

      Learning Cards: Understanding Status Checks

      +
      +Screen reader users + +
        +
      • Status checks live near the bottom of the PR Conversation tab — press H or 2 to jump to the checks section heading, then arrow down through each result
        • +
      • Each check is announced with its name and status ("CI / test — passed" or "lint — failed") — press Enter on a failing check to open its details
        • +
      • The word "Required" appears after required checks — listen for it to distinguish must-pass checks from informational ones
        • +
      +
      + +
      +Low vision users + +
        +
      • Status icons use green (passed), red (failed), yellow (running), and grey (skipped) — each icon also has a text label, so color is not the only indicator
        • +
      • At high zoom levels, the checks section may appear below the fold — scroll past the PR description and comments to find it above the merge button
        • +
      • Click "Details" next to any check to open the full log — the log page uses monospace text, so increase font size for readability
        • +
      +
      + +
      +Sighted users + +
        +
      • Look for the checks section between the last comment and the merge button on the PR page — it shows a vertical list of check names with colored status icons
        • +
      • Green checkmark = passed, red X = failed, yellow spinner = running, grey slash = skipped — scan for red X items first
        • +
      • "Required" checks have a label badge — these must all pass before the merge button turns green
        • +
      +
      + + +

      7. Reading the Actions Tab with a Screen Reader

      +

      The Actions tab of a repository shows the history of all workflow runs. You can use it to see what ran, what failed, and why.

      +

      Getting to the Actions tab

      +
        +
      1. Open the repository
        2. +
      2. Navigate to the "Repository navigation" landmark (D on NVDA/JAWS)
        3. +
      3. Find the "Actions" tab link and activate it (Enter)
        4. +
      + +
      Key          Action
+H            Jump between section headings
+3            Jump between workflow run headings (they are h3)
+Tab          Move between interactive elements (links, buttons)
+Enter        Open a workflow run to see details
      + +
      Key                  Action
+VO+U → Headings      Open rotor and navigate by heading
+VO+Right/Left        Read next/previous item
+VO+Space             Activate a link or button
      +

      Reading a run's details

      +

      When you open a workflow run, you see:

      +
        +
      • Job names listed on the left (or in a sidebar)
        • +
      • Steps listed within each job
        • +
      • Green checkmarks (passed) or red X marks (failed) next to each step
        • +
      +

      To find out why a step failed:

      +
        +
      1. Navigate to the failed step
        2. +
      2. Activate it to expand the log output
        3. +
      3. The log is a large text area - switch to focus mode to read it
        4. +
      4. Look for lines containing Error:, FAILED, exit code, or AssertionError
        5. +
      +
      +

      Tip: Log output can be very long. Use your screen reader's search (NVDA+Ctrl+F, JAWS: Insert+F, VO+F) to search for "error" or "failed" to jump directly to the problem.

      +
      +

      8. Common Workflows You Will Encounter

      +

      As you contribute to open source repositories, you will see these types of workflows regularly:

      +

      Continuous Integration (CI)

      +

      What it does: Runs the project's test suite automatically every time code changes.

      +

      What you see: A check called "CI", "Tests", "Build", or similar.

      +

      If it fails: Your code change may have broken one or more tests. Read the error message in the job log, or ask the maintainer if it is a pre-existing failure.

      +

      Linting / Code Style

      +

      What it does: Checks that code follows the project's formatting and style rules - things like indentation, line length, or consistent import ordering.

      +

      What you see: A check called "Lint", "ESLint", "Prettier", "Flake8", or similar.

      +

      If it fails: Usually means a formatting rule was violated. The log will tell you exactly which file and line. Many projects include a command to auto-fix this (e.g., npm run lint:fix).

      +

      Spelling / Documentation Checks

      +

      What it does: Checks documentation files for spelling errors, broken links, or formatting issues.

      +

      What you see: A check called "Spell Check", "markdownlint", "Link Check", or similar.

      +

      If it fails: There is a typo or formatting issue in a doc file. Very common on documentation-only contributions.

      +

      Accessibility Scanning

      +

      What it does: Runs automated accessibility checks against HTML output or component libraries to catch WCAG violations.

      +

      What you see: A check called "a11y", "Accessibility", "axe", "pa11y", or similar.

      +

      If it fails: An accessibility problem was introduced. The log will describe the failing rule (e.g., "Image missing alt text", "Color contrast insufficient"). This is extremely valuable information and exactly the kind of thing this community cares about.

      +

      Security Scanning

      +

      What it does: Scans for known vulnerabilities in dependencies or exposed secrets.

      +

      What you see: A check called "CodeQL", "Dependabot", "Snyk", or similar.

      +

      If it fails: A security issue was detected - inform the maintainer and do not merge.

      +

      Deployment / Preview Builds

      +

      What it does: Builds and deploys a preview version of a website or app from your PR branch.

      +

      What you see: A bot comment on your PR with a preview URL, and a check called "Deploy", "Netlify", "Vercel", "GitHub Pages", or similar.

      +

      What it gives you: A live preview of what the site will look like with your changes - very useful for visual review and for accessibility testing with your screen reader on the actual rendered output.

      +

      9. What To Do When a Check Fails

      +

      This happens to every contributor. It is normal. Here is your step-by-step process:

      +

      Step 1: Don't panic

      +

      A failing check is information, not a judgment. It is the system telling you something specific needs attention.

      +

      Step 2: Navigate to the failed check

      +

      From your PR's Conversation tab:

      +
        +
      1. Scroll down to the checks section (press D to reach the "Checks" region if using a screen reader)
        2. +
      2. Find the failing check (red X)
        3. +
      3. Press Enter on "Details" (or the check name itself) to open the workflow run
        4. +
      +

      Step 3: Find the failing step

      +

      In the workflow run:

      +
        +
      1. Look for the step with the red X marker
        2. +
      2. Press Enter or Space to expand the log output
        3. +
      +

      Step 4: Read the error message

      +

      Look for:

      +
        +
      • Error: - describes what went wrong
        • +
      • FAILED or FAIL - test failure summary
        • +
      • File name and line number - where exactly the problem is
        • +
      • exit code 1 (or non-zero) - the command failed
        • +
      +

      Step 5: Fix the issue locally (or in the web editor)

      +

      Common fixes:

      +
        +
      • Test failure: Understand what the test expects and whether your change broke something intentional
        • +
      • Lint failure: Run the project's format/lint command, or manually fix the flagged lines
        • +
      • Spell check failure: Fix the typo noted in the log
        • +
      • Accessibility failure: Fix the specific a11y violation described (missing alt text, contrast issue, etc.)
        • +
      +

      Step 6: Commit and push the fix

      +
        +
      • The workflow will automatically re-run when you push new commits to the branch
        • +
      • No need to close and re-open the PR
        • +
      +

      Step 7: If you're stuck

      +

      It is completely acceptable to comment on your PR:

      +
      +

      "The CI check is failing on [step name]. I've read the error log and I'm not sure how to fix [specific issue]. Could a maintainer point me in the right direction?"

      +
      +

      Asking for help is not weakness. It is collaboration.

      +

      Learning Cards: What To Do When a Check Fails

      +
      +Screen reader users + +
        +
      • From the failing check's Details link, the log page has a sidebar listing job steps — the failed step has focus or is announced as "failed"; expand it to read the error
        • +
      • Use your screen reader's find command (NVDA+Ctrl+F, JAWS: Insert+F) to search the log for "Error:" or "FAILED" — this skips hundreds of passing log lines
        • +
      • After pushing a fix, return to the PR page — checks re-run automatically and the status updates from red X to yellow spinner to green checkmark
        • +
      +
      + +
      +Low vision users + +
        +
      • CI log pages can be very long with small monospace text — use Ctrl+F in your browser to search for "Error" or "FAIL" rather than scrolling through everything
        • +
      • The failing step is marked with a red X icon in the left sidebar of the log page — zoom in to identify it, then click to expand only that step
        • +
      • If you cannot read the log comfortably, copy the error text and paste it into your editor at a larger font size
        • +
      +
      + +
      +Sighted users + +
        +
      • On the workflow run page, the left sidebar shows all job steps — the failing step has a red X icon; click it to jump directly to the error output
        • +
      • Error messages are usually highlighted in red within the log output — scan for red text and the phrases "Error:", "FAILED", or "exit code 1"
        • +
      • After pushing a fix, watch for the yellow spinner on the PR page to confirm that checks are re-running
        • +
      +
      + +

      10. Workflow Permissions and Security

      +

      Why some workflows need your approval

      +

      If you are contributing to a repository for the first time, GitHub may hold your workflow runs for approval. You will see a message like:

      +
      +

      "Workflows aren't being run on this pull request. A maintainer must approve this."

      +
      +

      This is a security feature - it prevents malicious code from running on the maintainer's infrastructure before they have reviewed it. Do not be alarmed. Simply add a comment like:

      +
      +

      "Ready for review. Could a maintainer approve the workflow runs?"

      +
      +

      What you should never do

      +
        +
      • Never change workflow files to bypass checks (e.g., deleting tests to make them pass)
        • +
      • Never add secrets or credentials to workflow files or code
        • +
      • Never approve a workflow run on someone else's PR unless you have reviewed the code
        • +
      +

      Dependabot

      +

      Dependabot is an automated bot built into GitHub that creates pull requests to update outdated or vulnerable dependencies. You will see PRs in a repository from a user called dependabot[bot]. These are automated, not from a person. Maintainers typically review and merge these. As a contributor, you usually don't need to interact with them, but it is good to know they exist.

      +

      11. Accessibility-Focused Workflows

      +

      This is relevant to our event specifically. The open source accessibility community actively uses GitHub Actions to automatically catch accessibility regressions - meaning, to ensure that new code does not introduce new accessibility barriers.

      +

      GitHub's Accessibility Scanner Action

      +

      GitHub itself has open-sourced an AI-powered Accessibility Scanner that can be added to a repository. It uses AI to find, file, and help fix accessibility bugs using GitHub Copilot.

      +

      A basic workflow using it looks like this:

      +
      name: Accessibility Scan
+
+on:
+  pull_request:
+    branches: [main]
+
+jobs:
+  a11y:
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@v4
+      - name: Run Accessibility Scanner
+        uses: github/accessibility-scanner@v1
+        with:
+          github-token: ${{ secrets.GITHUB_TOKEN }}
      +

      Common tools used in a11y workflows

      + + + + + + + + + + + + + + + + + + + + + + + + + + + +
      ToolWhat It Checks
      axe-coreWCAG violations in HTML/rendered pages
      pa11yAutomated accessibility testing against URLs
      jest-axeaxe checks inside unit tests
      Lighthouse CIAccessibility + performance scoring
      IBM Equal Access CheckerWCAG 2.1 / 2.2 compliance checking
      +

      What these tools catch (and what they do not)

      +

      Automated tools catch approximately 30-40% of accessibility issues - things like missing alt attributes, insufficient color contrast ratios, or unlabeled form fields. The remaining issues require human testing, especially with actual assistive technology like your screen reader.

      +

      This is precisely why manual testing by people who use screen readers is so valuable and irreplaceable.

      +

      Preparing the Environment for GitHub-Hosted Agents

      +

      When custom agents run on GitHub.com - triggered by an issue assignment or a Copilot Chat task - they need any external tools pre-installed before they start working. GitHub recognizes a special setup workflow for this: a workflow file with a single job named copilot-setup-steps.

      +

      Location: .github/workflows/copilot-setup-steps.yml

      +
      name: Copilot Setup Steps
+
+on: workflow_dispatch
+
+jobs:
+  copilot-setup-steps:
+    runs-on: ubuntu-latest
+    steps:
+      - name: Setup Node.js
+        uses: actions/setup-node@v4
+        with:
+          node-version: '20'
+
+      - name: Install accessibility testing tools
+        run: npm install -g @axe-core/cli markdownlint-cli2
      +

      What this does: Before a Copilot coding agent begins working, GitHub runs this job to prepare the environment. Without it, an agent that needs markdownlint-cli2 (for the Markdown Accessibility Assistant) or @axe-core/cli (for WCAG scanning) will fail because those tools are not present.

      +

      The job name copilot-setup-steps is required - GitHub won't recognize any other name for agent environment preparation.

      +

      Connection to Section 13 of the VS Code guide: This is the infrastructure that enables Scope 3 (cloud execution) of the three-layer Accessibility Agents model. The same agent you run in VS Code with @markdown-accessibility-assistant can run on GitHub.com automatically - but only if the environment is prepared with this workflow.

      +

      12. Hands-On Activity

      +

      Activity: Explore a Workflow in This Repository

      +
      +

      Goal: Practice navigating the Actions tab and reading a workflow file using your screen reader.

      +
      +

      Steps

      +
        +
      1. Navigate to your Learning Room repository on GitHub
        2. +
      2. Go to the Actions tab (in the Repository navigation landmark)
        3. +
      3. Use 3 (NVDA/JAWS) or the Headings rotor (VoiceOver) to navigate the list of workflow runs
        4. +
      4. Open the most recent run
        5. +
      5. Find any failed step and expand its log
        6. +
      6. Navigate to the .github/workflows/ folder via the Code tab
        7. +
      7. Open a workflow .yml file
        8. +
      8. Read through the file and identify:
          +
        • What event triggers it
          • +
        • What OS it runs on
          • +
        • How many steps it has
          • +
        • What the last step does
          • +
        +
        9. +
      +

      Discussion questions

      +
        +
      • What would happen if you opened a PR and the "Accessibility Scan" check failed?
        • +
      • Where would you look to find out what accessibility violation was detected?
        • +
      • If you disagreed with a failing lint check, what would be the appropriate way to raise that with a maintainer?
        • +
      +

      13. What We Are NOT Covering (And Where to Learn More)

      +

      GitHub Actions is a deep topic. This workshop covers what you need as a contributor. We are intentionally not diving into:

      +
        +
      • Writing workflow files from scratch
        • +
      • Setting up self-hosted runners
        • +
      • Creating custom Actions
        • +
      • Advanced workflow patterns (matrix builds, reusable workflows, environments)
        • +
      • Secrets management and OIDC authentication
        • +
      +

      When you are ready to go deeper, these are the best places to start:

      + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + +
      ResourceLink
      GitHub Actions DocumentationGitHub Actions docs
      GitHub Skills: Hello GitHub ActionsHello GitHub Actions course
      GitHub Skills: Continuous IntegrationContinuous Integration course
      GitHub Marketplace (Actions)GitHub Marketplace for Actions
      GitHub Accessibility ScannerAccessibility Scanner action
      GitHub Actions Accessibility Conformance ReportAccessibility conformance report
      +

      Summary

      + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + +
      ConceptKey Takeaway
      Workflows live in .github/workflows/YAML files that define automation
      Triggers fire workflowspush, pull_request, schedule are the most common
      Status checks appear on your PRGreen checkmark, Red X, Yellow circle = pass, fail, running
      Required checks must passConfigured by maintainers - blocks merging if failing
      Failing checks are normalRead the log, fix the issue, push again
      a11y workflows catch ~30-40% of issuesHuman screen reader testing catches the rest
      First-time contributors may need approvalA security feature - ask a maintainer politely
      +
      +

      Day 2 Bridge - From Actions to Agentic Workflows

      +

      Understand standard YAML workflow files before engaging with agentic workflows. GitHub Agentic Workflows are not a separate technology - they are the next layer on top of what you learned here. They share the same trigger model, the same permissions system, and the same .github/workflows/ directory. You cannot evaluate whether an agentic workflow is safe or correct unless you can already read a standard one.

      +

      The three layers, in sequence - each builds on the one before it:

      +
        +
      1. Standard GitHub Actions - YAML files in .github/workflows/; define triggers and structured shell steps; what you mastered in this guide
        2. +
      2. Accessibility Agents in VS Code - .agent.md files in .github/agents/; define behavior in plain English; GitHub Copilot Chat executes them on demand in your editor - same .github/ folder, plain text, no YAML required
        3. +
      3. GitHub Agentic Workflows in the cloud - .md files in .github/workflows/; define intent in plain Markdown frontmatter; a coding agent (Copilot CLI, Claude Code, OpenAI Codex) executes them inside GitHub Actions on any trigger - no VS Code, no local setup required
        4. +
      +

      All three live in .github/. All three are plain text. All three run on your behalf. The only difference is where they run and how sophisticated their executor is.

      +

      You cannot skip a layer. Each one only makes sense because you understand the one before it.

      +
      +
      +

      Next: Appendix R: Projects Deep Dive
      Back: Appendix P: Security Features
      Teaching chapter: Chapter 17: Issue Templates

      + +
      + + + + diff --git a/html/admin/qa-bundle/docs/appendix-r-projects-deep-dive.html b/html/admin/qa-bundle/docs/appendix-r-projects-deep-dive.html new file mode 100644 index 00000000..0be189b3 --- /dev/null +++ b/html/admin/qa-bundle/docs/appendix-r-projects-deep-dive.html @@ -0,0 +1,538 @@ + + + + + + + Appendix R: GitHub Projects Deep Dive - GIT Going with GitHub + + + + + + + + +
      +

      Appendix R: GitHub Projects Deep Dive

      +
      +

      Listen to Episode 26: GitHub Projects Deep Dive - a conversational audio overview of this chapter. Listen before reading to preview the concepts, or after to reinforce what you learned.

      +
      +
      +

      Reference companion to: Chapter 09: Labels, Milestones, and Projects

      +

      Authoritative source: GitHub Docs: About Projects

      +
      +

      Boards, Tables, Roadmaps, Automations, and Accessible Navigation

      +
      +

      GitHub Projects is GitHub's built-in project management system. It connects issues and pull requests from one or more repositories into a living, filterable view that your whole team can see and act on. This appendix covers everything beyond the basics introduced in Chapter 9: Labels, Milestones, and Projects.

      +
      +

      Table of Contents

      +
        +
      1. Projects v2: What Changed
        2. +
      2. Creating a Project
        3. +
      3. The Three Layouts in Depth
        4. +
      4. Custom Fields
        5. +
      5. Adding and Managing Items
        6. +
      6. Built-In Automations
        7. +
      7. Iterations (Sprints)
        8. +
      8. Views and Filters
        9. +
      9. Cross-Repository Projects
        10. +
      10. Screen Reader Navigation Reference
        11. +
      11. Accessibility Agents: /project-status
        12. +
      12. Exercises
        13. +
      +

      1. Projects v2: What Changed

      +

      GitHub has two generations of project tooling. The current generation - called Projects (v2) - is what you'll find on any repository or organization page today.

      +

      Layouts: Classic v1 offered Kanban board only. V2 offers Board, Table, and Roadmap.

      +

      Custom fields: Classic v1 had none. V2 supports Text, Number, Date, Single Select, and Iteration fields.

      +

      Automations: Classic v1 had no built-in automations. V2 has native GitHub Actions integration.

      +

      Cross-repo support: Classic v1 did not support cross-repository tracking. V2 does.

      +

      Filtering: Classic v1 had limited filtering. V2 supports full field, label, assignee, and status queries.

      +

      API: Classic v1 had a limited API. V2 has full GraphQL support.

      +

      If you see "Projects (Beta)" references in older documentation, those referred to the early rollout of v2. It is now stable and the default.

      +

      2. Creating a Project

      +

      Projects can be created at the organization level (shared across all repos in an org) or at the repository level (scoped to one repo).

      +

      Create from an Organization

      +
        +
      1. Navigate to your organization page (github.com/your-org)
        2. +
      2. Select the Projects tab
        3. +
      3. Activate "New project" button
        4. +
      4. Choose a template (blank table, blank board, feature release, etc.) or start empty
        5. +
      5. Give the project a name and select "Create project"
        6. +
      +

      Create from a Repository

      +
        +
      1. Navigate to any repository
        2. +
      2. Select the Projects tab
        3. +
      3. Activate "Link a project" or "New project"
        4. +
      4. Follow the same template/name flow
        5. +
      +

      Screen Reader: Project Creation

      +
      1. Navigate to org or repo Projects tab
+   → Tab to the green "New project" button → Enter
+2. Template modal opens
+   → Arrow keys to browse template cards
+   → Enter to select a template
+3. Name field: type your project name
+4. "Create project" button: Tab → Enter
+5. You land on the new empty project
      +

      Learning Cards: Creating a Project

      +
      +Screen reader users + +
        +
      • The "New project" button is on the Projects tab of any org or repo page — Tab to it and press Enter to open the template modal
        • +
      • Template cards in the modal are navigable with arrow keys — each template announces its name and description; press Enter on your choice
        • +
      • After creation, you land on an empty project — Tab to the "+ Add item" button at the bottom to start adding issues
        • +
      +
      + +
      +Low vision users + +
        +
      • The green "New project" button on the Projects tab is high-contrast and easy to spot even at high zoom
        • +
      • Template cards in the creation modal are displayed as a grid — zoom in to read the titles and descriptions before selecting one
        • +
      • After the project is created, the empty Table view has a "+ Add item" row at the bottom — it can scroll off screen at high zoom, so scroll down to find it
        • +
      +
      + +
      +Sighted users + +
        +
      • Navigate to the Projects tab on your org or repo page and click the green "New project" button in the upper right
        • +
      • The template picker shows visual cards for common project types (blank table, blank board, feature release) — hover to preview each layout
        • +
      • After creating, you land on an empty project with a prominent "+ Add item" prompt at the bottom of the table or board
        • +
      +
      + + +

      3. The Three Layouts in Depth

      +

      Table View

      +

      The default layout. A spreadsheet-style grid where each row is an issue, PR, or draft item. Columns are fields (Title, Status, Assignee, Labels, Priority, custom fields you create).

      +

      What it's best for: Bulk editing, sorting, filtering, seeing many items at once with their field values.

      +

      Keyboard navigation

      +
      T                     → Jump to table
+↑/↓                   → Move between rows
+←/→                   → Move between columns
+Enter                 → Open item detail panel (right sidebar)
+Escape                → Close detail panel
+Space (on a cell)     → Edit that cell's value
+F2 (on title cell)    → Edit title inline
      +

      Screen reader output per row

      +
      +

      "Fix keyboard trap in modal dialog | Status: In Progress | Assignee: alice | Priority: High | Labels: bug, accessibility"

      +
      +

      Board View

      +

      Kanban-style columns. Each column represents a status value. Cards can be dragged between columns (or updated via keyboard by editing the Status field).

      +

      What it's best for: Visual workflow tracking, seeing WIP (work in progress), standup-style status reviews.

      +

      Screen reader note: Drag-and-drop is not keyboard accessible. Change a card's column by opening it and editing the Status field instead.

      +

      Keyboard navigation

      +
      Tab                   → Move between columns and cards
+Enter (on a card)     → Open item detail panel
+B                     → Jump to board regions (if heading navigation)
+Within a card:
+  Enter               → Open panel
+  Space               → Toggle selection (for bulk moves)
      +

      Change a card's column without dragging

      +
        +
      1. Enter to open the card
        2. +
      2. Navigate to the Status field in the right panel
        3. +
      3. Activate the Status dropdown
        4. +
      4. Select the new column value
        5. +
      5. Escape to close
        6. +
      +

      Roadmap View

      +

      A horizontal timeline. Items appear as bars spanning their start/due dates. Iterations and milestones can be visualized against real calendar time.

      +

      What it's best for: Release planning, sprint capacity planning, communicating timelines to stakeholders.

      +

      Screen reader note: Roadmap is chart-based. The underlying data is still fully accessible via the Table view - treat Roadmap as a visual summary, and use Table for all editing.

      +

      Setting dates

      +
        +
      • Add a Date custom field (e.g., "Start Date", "Due Date") or use a Milestone field
        • +
      • Items without dates appear in the ungrouped section
        • +
      +

      Learning Cards: The Three Layouts

      +
      +Screen reader users + +
        +
      • Table view is the most accessible layout — navigate with arrow keys (up/down for rows, left/right for columns) and press Enter to open an item's detail panel
        • +
      • Board view drag-and-drop is not keyboard accessible — change a card's column by opening it (Enter), navigating to the Status field, and selecting a new value from the dropdown
        • +
      • Roadmap view is chart-based and not directly readable — use Table view for all data access and editing, then switch to Roadmap only for visual context if needed
        • +
      +
      + +
      +Low vision users + +
        +
      • Table view works best at high zoom because it is a standard grid — Board view columns can overflow horizontally and require scrolling
        • +
      • Board view cards show title, labels, and assignee — zoom in on individual cards to read the small label badges and avatar icons
        • +
      • Roadmap view uses horizontal bars on a calendar timeline — the bars can be narrow at default zoom; increase zoom or switch to Table for the same date data in text form
        • +
      +
      + +
      +Sighted users + +
        +
      • Switch between layouts using the view tabs at the top of the project — Table (grid icon), Board (columns icon), and Roadmap (timeline icon)
        • +
      • Board view shows Kanban columns — drag cards between columns to change status, or click a card to open its detail panel
        • +
      • Roadmap view displays items as horizontal bars on a calendar — look for the date fields (Start Date, Due Date) to position items on the timeline
        • +
      +
      + + +

      4. Custom Fields

      +

      This is one of Projects v2's most powerful features. You can add fields beyond the GitHub defaults (Title, Assignee, Labels, Milestone, Repository).

      +

      Field Types

      +

      Text: Free-form notes for things like acceptance criteria or design links.

      +

      Number: Numeric values such as story points or estimates (for example, "Points: 3").

      +

      Date: Deadlines or start dates (for example, "Due: 2025-06-15").

      +

      Single select: A dropdown with predefined options, useful for priority, size, or type fields (for example, Priority: P0, P1, or P2).

      +

      Iteration: Sprint or cycle tracking. See Section 7 for details.

      +

      Creating a Custom Field

      +

      From any project view:

      +
        +
      1. In Table view, scroll right to the + button at the end of the column header row
        2. +
      2. Activate the + button
        3. +
      3. Select a field type
        4. +
      4. Name the field and configure options (for select fields, type each option, press Enter to add more)
        5. +
      5. Confirm - the field appears as a new column
        6. +
      +

      Screen reader path

      +
      Tab to "+" column header button → Enter
+→ Field type menu opens → ↑/↓ to choose type → Enter
+→ Name field: type field name
+→ For "Single select": type option names, Tab/Enter between options
+→ "Save" button → Enter
      +

      Editing a Field Value on an Item

      +
        +
      1. In Table view, navigate to the cell where the field intersects the row
        2. +
      2. Enter or Space to activate the editor
        3. +
      3. Type value (text/number) or select from dropdown (single select)
        4. +
      4. Enter or Tab to confirm
        5. +
      +

      5. Adding and Managing Items

      +

      Add an Existing Issue or PR

      +

      From any project view:

      +
        +
      1. Activate the "+ Add item" button at the bottom of a table/column
        2. +
      2. Type # to trigger the issue/PR search
        3. +
      3. Type a keyword or issue number
        4. +
      4. Select the item - it's added to the project
        5. +
      5. The issue/PR is now tracked in the project; it still lives in its repository
        6. +
      +

      Tip: The issue itself will now show which projects it belongs to in its sidebar.

      +

      Add a Draft Issue

      +

      Draft issues live only inside the project (not in any repository) until you promote them.

      +
        +
      1. Activate "+ Add item"
        2. +
      2. Type the title directly (no #)
        3. +
      3. Press Enter - a draft row appears
        4. +
      4. Open the draft → "Convert to issue" button → select the repository
        5. +
      +

      When to use drafts: Capturing ideas during planning before you're ready to commit them to a repo.

      +

      Promote a Draft to an Issue

      +
        +
      1. Open the draft item (Enter on the row)
        2. +
      2. Activate "Convert to issue" in the panel
        3. +
      3. Select the target repository from the dropdown
        4. +
      4. Confirm - the draft becomes a real issue in that repo
        5. +
      +

      Bulk Edit Items

      +

      In Table view:

      +
        +
      1. Check the checkbox on each row (first column, Space to toggle)
        2. +
      2. A bulk action bar appears at the top
        3. +
      3. Options: change Status, assign label, change assignee, archive, delete
        4. +
      +

      6. Built-In Automations

      +

      Projects v2 has native automation rules - no GitHub Actions YAML required.

      +

      Accessing Automations

      +

      From a project:

      +
        +
      1. Select the ... menu (project overflow) in the top-right
        2. +
      2. Select "Workflows"
        3. +
      3. You'll see a list of built-in automation rules you can enable/disable
        4. +
      +

      Available Built-In Workflows

      +

      Item added to project: When an item is manually added, its Status is set to a value you choose.

      +

      Item reopened: When an issue or pull request is reopened, its Status changes back (for example, to "In Progress").

      +

      Item closed: When an issue or pull request is closed, its Status is automatically set to "Done."

      +

      Pull request merged: When a pull request is merged, its Status is set to "Done."

      +

      Auto-add to project: Items matching a filter (by label, type, or repository) are automatically added to the project.

      +

      Setting Up Auto-Add

      +

      This is the most powerful workflow for maintainers:

      +
        +
      1. In Workflows, select "Auto-add to project"
        2. +
      2. Toggle it On
        3. +
      3. Configure the filter: e.g., label:accessibility is:issue adds any new issue with the accessibility label automatically
        4. +
      4. Save
        5. +
      +

      Now any matching issue in linked repos is added to your project the moment it's filed - no manual triage step required.

      +

      GitHub Actions Integration

      +

      For more complex automations, Projects v2 has a full GraphQL API and works with GitHub Actions. Example use cases:

      +
        +
      • Auto-assign items based on repository when added
        • +
      • Set due dates based on linked milestone
        • +
      • Send Slack notifications when high-priority items are added
        • +
      +

      See Appendix Q: GitHub Actions and Workflows for the foundation, and the GitHub documentation on automating projects for advanced patterns.

      +

      7. Iterations (Sprints)

      +

      An iteration field lets you group work into time-boxed cycles - sprints, weeks, or any cadence you choose.

      +

      Creating an Iteration Field

      +
        +
      1. Add a new field (the + column button in Table view)
        2. +
      2. Select "Iteration" as the field type
        3. +
      3. Name it (e.g., "Sprint")
        4. +
      4. Set the iteration duration (1 week, 2 weeks, custom)
        5. +
      5. GitHub automatically generates current and upcoming iterations
        6. +
      +

      Using Iterations

      +
        +
      • Each item can be assigned to an iteration via the Iteration field
        • +
      • In Board view, you can group by iteration to see a sprint board
        • +
      • In Roadmap view, iterations appear as blocks on the timeline
        • +
      • Burndown: No built-in burndown chart, but the Insights charts (see below) can show progress
        • +
      +

      Iteration Insights

      +

      From any project:

      +
        +
      1. Select the Insights tab (the bar chart icon)
        2. +
      2. Select "Current iteration"
        3. +
      3. See: items by status, completion rate, items added vs closed over time
        4. +
      +

      8. Views and Filters

      +

      A view is a saved configuration of layout + filters + grouping + sort. You can have many views on one project, each showing a different slice of the data.

      +

      Creating a View

      +
        +
      1. Activate the "+ New view" button in the view tab bar
        2. +
      2. Choose layout (Table, Board, Roadmap)
        3. +
      3. Configure filters, grouping, sort
        4. +
      4. The view saves automatically with a default name - rename by clicking/activating the tab label
        5. +
      +

      Filter Syntax

      +

      The filter bar accepts a query language similar to GitHub's issue search:

      +

      status:In Progress shows only items with that Status value.

      +

      assignee:@me shows only items assigned to you.

      +

      label:accessibility shows items with the accessibility label.

      +

      milestone:"v2.0" shows items in a specific milestone.

      +

      no:assignee shows items with no assignee.

      +

      is:pr shows only pull requests. is:issue shows only issues.

      +

      repo:owner/name shows items from a specific repository, useful in cross-repo projects.

      +

      You can combine filters: assignee:@me status:"In Progress" shows your in-progress work.

      +

      Grouping

      +

      In Table or Board view, you can group rows:

      +
        +
      1. Select "Group by" in the view configuration menu
        2. +
      2. Choose any field: Status, Assignee, Priority, Iteration, Label, Repository
        3. +
      3. Items are collapsible into group sections
        4. +
      +

      Sorting

      +

      Multiple sort levels are supported. Primary sort → secondary sort:

      +
        +
      • Priority ascending, then due date ascending
        • +
      +

      9. Cross-Repository Projects

      +

      A single project can track issues and PRs from multiple repositories - including repos in different organizations (if you have access).

      +

      Add a Repository to a Project

      +
        +
      1. In project settings (the ... overflow menu → "Settings")
        2. +
      2. Select "Manage access" → "Add repository"
        3. +
      3. Search and select additional repositories
        4. +
      4. Items from those repos can now be added to the project
        5. +
      +

      Using the Repository Field

      +

      When a project spans multiple repos, the "Repository" field lets you see - and filter by - which repo each item belongs to:

      +
      Filter: repo:community-access/accessibility-agents
+→ Show only accessibility-agents issues in this cross-repo project
      +

      Common use case: An organization project tracking all accessibility bugs across every repo, labeled accessibility, with Auto-add enabled.

      +

      10. Screen Reader Navigation Reference

      +

      Project Home Page (list of projects)

      +
      3 → Jump to project titles (they are h3 links)
+Enter → Open a project
      +

      Inside a Project - General

      +
      Tab → Move between interactive elements (view tabs, filters, fields, buttons)
+F6 → Cycle between major panels (header, view tabs, content area)
+/ → Focus the filter bar (if supported; otherwise Tab to reach it)
      +

      Table View

      +
      T or Region → Jump to the table data region
+↑/↓ → Navigate rows
+←/→ → Navigate columns within a row
+Enter → Open item detail panel
+Space → Toggle row selection
+Escape → Close detail panel or cancel edit
+F2 → Edit a title cell if focused
      +

      NVDA note: Use Browse mode (NVDA+Space to toggle) to read all cell content, then App mode (NVDA+Space again) for interactive editing. NVDA announces cell content as you navigate with arrow keys.

      +

      JAWS note: Use JAWS cursor (JAWS+P) to read grid cell content. For interactive editing, press Enter to enter application mode in the table.

      +

      VoiceOver note: Use VO+Shift+↓ to interact with the table. VO+←/→ moves between cells. Press VO+Space to activate a cell for editing.

      +

      Board View

      +
      Tab → Move between cards and column headers
+Enter (on card) → Open detail panel
+The "Status" field in the panel → Change the card's column
      +

      Detail Panel (right sidebar, any view)

      +
      Tab → Move between fields
+Enter/Space → Activate a field editor
+Select dropdowns → ↑/↓ to navigate options, Enter to select
+Escape → Close the dropdown or the panel
      +

      Filter Bar

      +
      Click/Tab to filter bar → type query → Enter to apply
+Backspace → Remove last filter token
+Escape → Clear focus from filter bar
      +

      11. Accessibility Agents: /project-status

      +

      The /project-status command from Accessibility Agents gives you a live project board overview directly in VS Code Copilot Chat, without opening a browser.

      +

      What It Shows

      +
      /project-status community-access/accessibility-agents
      +
        +
      • Items per column (Todo, In Progress, Done, etc.) with assignees and average age
        • +
      • Blocked items (labeled "blocked" or flagged with a field value)
        • +
      • Stale items - in the same column for 7+ days with no activity
        • +
      • Unassigned items in active columns
        • +
      • Team member workload (anyone with 5+ items in progress)
        • +
      • Sprint/iteration progress if an Iteration field is configured
        • +
      +

      Example Output

      +

      GitHub Project: Accessibility Agents Roadmap (3 active views)

      +

      Column Breakdown:

      + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + +
      ColumnItemsAssigneesAvg AgeStale (7d+)
      To Do8@alice (3), @bob (2)5 days1
      In Progress4@charlie (2)3 days0
      In Review2--2 days0
      Done23------
      +

      Attention Items:

      +
        +
      • Stale: "Update screen reader navigation guide" - In Review for 9 days, no activity
        • +
      • Unassigned: "Triage accessibility bug backlog" in In Progress
        • +
      +

      After the overview: "Want to see a specific column or check a team member's workload?"

      +

      When to Use It

      +
        +
      • During standup: quick status snapshot without leaving VS Code
        • +
      • Before filing a new issue: see if it's already tracked
        • +
      • During sprint planning: identify stale and blocked items before the next cycle
        • +
      • After a weekend: catch up on what moved while you were away
        • +
      +

      12. Exercises

      +

      Exercise 1: Create a Personal Tracking Project

      +
        +
      1. Create a new project at the organization level: name it "My Workshop Contributions"
        2. +
      2. Add the Board layout
        3. +
      3. Add a custom Priority field with options: P0, P1, P2
        4. +
      4. Add your fork of accessibility-agents as a linked repository
        5. +
      5. Add any open issue you've filed to the project
        6. +
      +

      Exercise 2: Set Up Automation

      +
        +
      1. In your project's Workflows, enable "Item closed" → Status: Done
        2. +
      2. File a test issue in your fork
        3. +
      3. Close that issue
        4. +
      4. Verify it moved to "Done" automatically in the project board
        5. +
      +

      Exercise 3: Create a Sprint View

      +
        +
      1. Add an Iteration field named "Sprint" with 2-week iterations
        2. +
      2. Assign your existing project items to the current sprint
        3. +
      3. Switch to Roadmap view - observe the items on the timeline
        4. +
      4. Check Insights to see the current iteration burndown
        5. +
      +

      Exercise 4: Cross-Repo Project (Advanced)

      +
        +
      1. Create a cross-repo project connected to two of your repositories
        2. +
      2. Add the Repository field to the Table view
        3. +
      3. Create a view filtered to is:issue label:accessibility
        4. +
      4. Set up Auto-add: any issue with the accessibility label in those repos goes to this project automatically
        5. +
      +
      +

      From Chapter 9: For the introductory coverage of Labels, Milestones, and Projects including screen reader basics for getting started, see Chapter 9: Labels, Milestones, and Projects.

      +
      +
      +

      Next: Appendix S: Releases and Insights
      Back: Appendix Q: GitHub Actions
      Teaching chapter: Chapter 09: Labels, Milestones, and Projects

      + +
      + + + + diff --git a/html/admin/qa-bundle/docs/appendix-s-releases-tags-insights.html b/html/admin/qa-bundle/docs/appendix-s-releases-tags-insights.html new file mode 100644 index 00000000..fb61aa8f --- /dev/null +++ b/html/admin/qa-bundle/docs/appendix-s-releases-tags-insights.html @@ -0,0 +1,645 @@ + + + + + + + Appendix S: Releases, Tags, and Repository Insights - GIT Going with GitHub + + + + + + + + +
      +

      Appendix S: Releases, Tags, and Repository Insights

      +
      +

      Listen to Episode 25: Releases, Tags, and Insights - a conversational audio overview of this chapter. Listen before reading to preview the concepts, or after to reinforce what you learned.

      +
      +
      +

      Reference companion to: Chapter 08: Open Source Culture

      +

      Authoritative source: GitHub Docs: About releases

      +
      +

      Understanding Versioned Releases and Repository Activity

      +
      +

      Two things help you understand a repository's health and your place in it: releases (the versioned snapshots your contributions land in) and insights (the activity metrics that show how a project grows). This appendix covers both.

      +
      +

      Table of Contents

      +

      Part 1 - Releases and Tags

      +
        +
      1. What Is a Release?
        2. +
      2. Releases vs. Tags vs. Branches
        3. +
      3. Navigating Releases on GitHub
        4. +
      4. Understanding Version Numbers
        5. +
      5. Reading Release Notes
        6. +
      6. For Maintainers: Creating a Release
        7. +
      7. Draft and Pre-Release States
        8. +
      8. Accessibility Agents: /draft-release
        9. +
      +

      Part 2 - Repository Insights

      +
        +
      1. What Is the Insights Tab?
        2. +
      2. Navigating to Insights
        3. +
      3. Pulse - Recent Activity Summary
        4. +
      4. Contributors - Who Builds the Project
        5. +
      5. Traffic - Who Visits the Repo
        6. +
      6. Commits and Code Frequency
        7. +
      7. Dependency Graph
        8. +
      8. Network and Forks
        9. +
      9. Community Standards
        10. +
      10. Screen Reader Navigation Reference
        11. +
      11. Accessibility Agents: /my-stats and /team-dashboard
        12. +
      +

      Part 1 - Releases and Tags

      +

      1. What Is a Release?

      +

      A release is a named snapshot of a repository at a specific point in history, packaged and published for users.

      +

      For software projects, a release typically includes:

      +
        +
      • A version number (e.g., v2.1.0)
        • +
      • Release notes explaining what changed
        • +
      • Links to download the compiled or packaged software (if applicable)
        • +
      • Source code archives (automatically generated by GitHub)
        • +
      +

      For documentation-only or non-software projects, releases are often used to mark stable checkpoints or versions of a document.

      +

      When your PR gets merged: Your change becomes part of the code on the default branch. It will be included in the next release whenever the maintainer decides to publish one - this might be days, weeks, or months away depending on the project's release cadence.

      +

      2. Releases vs. Tags vs. Branches

      +

      These three concepts are closely related:

      + + + + + + + + + + + + + + + + + + + + + + + +
      ConceptWhat It IsLives
      BranchA movable pointer to the latest commit on a line of workPermanently moves as commits are added
      TagA fixed pointer to a single specific commitNever moves - always points to the same commit
      ReleaseA tag + release notes + optional downloadable assets published on GitHubBased on a tag
      +

      The relationship

      +
        +
      • Every release is backed by a tag
        • +
      • A tag without a release is just a version marker in the git history
        • +
      • GitHub automatically creates a tag when you create a release
        • +
      +

      3. Navigating Releases on GitHub

      +

      Finding the Releases Page

      +

      From any repository page:

      +
        +
      1. Look on the right sidebar for a "Releases" section showing the latest release
        2. +
      2. Activate "Releases" or the version link to go to the full releases page
        3. +
      3. Alternatively: navigate to github.com/owner/repo/releases
        4. +
      +

      Screen reader path

      +
      On the repository home page:
+→ H or 3 to find "Releases" heading in the right sidebar
+→ Tab to the latest release link → Enter
+→ Or: Tab to "N Releases" count link → Enter → Opens full releases list
      +

      The Releases List Page

      +

      Each release appears as a section with:

      +
        +
      • The release title (usually the version number)
        • +
      • A badge: "Latest" (most recent stable), "Pre-release", or nothing (older release)
        • +
      • Publication date
        • +
      • The tag name
        • +
      • Release notes (the main body)
        • +
      • Asset downloads (if included)
        • +
      • Source code download links (always present - auto-generated zip/tar.gz)
        • +
      + +
      2 → Jump between release title headings
+K → Navigate links (download assets, compare, tag links)
+↓ → Read release notes
      +

      Learning Cards: Navigating Releases

      +
      +Screen reader users + +
        +
      • On the repository home page, press H or 3 to find the "Releases" heading in the right sidebar, then K to the version link — Enter opens the latest release directly
        • +
      • On the Releases list page, each release is a heading — use 2 or 3 to jump between releases and arrow down to read the notes inline
        • +
      • The "Latest" badge appears next to the most recent stable release — listen for it to distinguish stable releases from pre-releases or older versions
        • +
      +
      + +
      +Low vision users + +
        +
      • The Releases link on the repo home page sits in the right sidebar — at high zoom the sidebar may collapse below the main content; scroll down to find it
        • +
      • Release notes use Markdown headings (Breaking Changes, New Features, Bug Fixes) — zoom in and scan the bold section labels for quick triage
        • +
      • The green "Latest" badge next to the newest stable release is small — zoom to 150%+ to spot it among the release list entries
        • +
      +
      + +
      +Sighted users + +
        +
      • On the repository home page, look at the right sidebar for the Releases section showing the latest version number and a link to all releases
        • +
      • On the Releases list page, each release card shows a title, date, tag, and a "Latest" badge on the most recent stable version
        • +
      • Scroll through release notes to see categorized change lists — look for the "Full Changelog" link at the bottom to see every merged PR between two versions
        • +
      +
      + + +

      4. Understanding Version Numbers

      +

      Most projects follow Semantic Versioning (semver): MAJOR.MINOR.PATCH

      + + + + + + + + + + + + + + + + + + + + + + + +
      PartWhen It ChangesMeaning
      MAJOR (e.g., 2.x.x)Breaking changesExisting behavior changed in an incompatible way; users may need to update their code
      MINOR (e.g., x.1.x)New features, backward-compatibleNew functionality added; existing code still works
      PATCH (e.g., x.x.1)Bug fixesSomething was broken and is now fixed
      +

      Examples

      +
        +
      • v2.0.0 → major release, breaking changes possible
        • +
      • v2.1.0 → new features added
        • +
      • v2.1.3 → three bug fixes since v2.1.0
        • +
      +

      Pre-release suffixes (not part of semver core, but common):

      +
        +
      • v2.1.0-alpha.1 → early preview, may be unstable
        • +
      • v2.1.0-beta.2 → feature-complete but still testing
        • +
      • v2.1.0-rc.1 → release candidate, nearly final
        • +
      +

      Your contribution's journey

      +
      PR opened → PR reviewed → PR merged → default branch updated
+                                              ↓
+                                   Next release prepared
+                                              ↓
+                          Tag created → Release published → v2.1.1
      +

      5. Reading Release Notes

      +

      Release notes document what changed. High-quality release notes categorize changes:

      +
      ## What's New in v2.1.0
+
+### Breaking Changes
+- The `preferences.md` format has changed - see the migration guide
+
+### New Features
+- Added `/project-status` command (#42, @alice)
+- Added `/onboard-repo` command (#38, @bob)
+
+### Bug Fixes
+- Fixed keyboard navigation in the triage workflow (#51, @charlie)
+- Screen reader announcement now correct for merged PRs (#48, @alice)
+
+### Dependencies
+- Updated github-mcp-server to v3.0.1
+
+**Full Changelog:** https://github.com/owner/repo/compare/v2.0.0...v2.1.0
      +

      The "Full Changelog" link at the bottom of many release notes goes to a comparison view showing every merged PR between two tags. This is where you'll see your PR listed by name, with your username credited.

      +

      6. For Maintainers: Creating a Release

      +

      This section is relevant if you become a maintainer or contribute to a project that asks you to prepare releases.

      +

      Creating a Release from the GitHub UI

      +
        +
      1. Navigate to github.com/owner/repo/releases/new
        2. +
      2. Choose a tag: Type a new version tag (e.g., v2.1.0) - GitHub will create it on publish, or select an existing tag if you already created one
        3. +
      3. Choose a target branch: The branch the tag will be applied to (usually main)
        4. +
      4. Release title: Usually the same as the tag (e.g., v2.1.0)
        5. +
      5. Release notes: Write manually, or click "Generate release notes" - GitHub auto-generates from merged PR titles since the last release
        6. +
      6. Assets: Optionally attach compiled binaries or other files
        7. +
      7. Pre-release toggle: Mark as pre-release if it's alpha/beta
        8. +
      8. Draft toggle: Save as draft to prepare without publishing immediately
        9. +
      9. Publish release
        10. +
      +

      Using Accessibility Agents for Release Notes

      +

      The /draft-release command generates structured release notes automatically from your merged PRs - much faster and more consistent than writing them manually. See Section 8.

      +

      Learning Cards: Creating a Release

      +

      Screen reader users:

      +
        +
      • The release creation form at github.com/owner/repo/releases/new has several fields -- Tab through them in order: tag selector (combobox), target branch, title input, release notes textarea, asset upload, pre-release checkbox, draft checkbox, and publish button
        • +
      • The tag selector is a combobox -- type a new version tag (e.g., v2.1.0) and the option to create it appears; arrow down and press Enter to select
        • +
      • The "Generate release notes" button auto-fills the textarea with merged PR titles -- after clicking it, arrow through the generated notes to verify accuracy before publishing
        • +
      +

      Low-vision users:

      +
        +
      • The release creation page uses a single-column form layout -- zoom in and the form fields stack vertically for easy scanning
        • +
      • The "Pre-release" and "Draft" checkboxes are at the bottom of the form, below the release notes editor -- scroll past the potentially long textarea to find them
        • +
      • The "Generate release notes" button is a small link-style button near the release notes textarea -- look for it above or beside the text area at high magnification
        • +
      +

      Sighted users:

      +
        +
      • The tag selector dropdown shows existing tags and a text input for creating new ones -- type v to filter for version tags
        • +
      • Click "Generate release notes" to auto-populate from merged PRs since the last release -- review and manually categorize the entries (Breaking Changes, Features, Bug Fixes) for a polished result
        • +
      • The Assets section at the bottom accepts drag-and-drop file uploads for binaries, installers, or compiled packages
        • +
      +

      7. Draft and Pre-Release States

      +

      Draft release: Saved but not published. Only visible to repository collaborators. Use drafts to prepare release notes in advance.

      +

      Pre-release: Published and visible, but not marked "Latest." Users who look for the latest stable version won't be directed to it automatically. Use for alpha/beta/RC versions.

      +

      Latest release: The most recent non-pre-release, non-draft release. This is what GitHub highlights in the sidebar and what github.com/owner/repo/releases/latest redirects to.

      +

      8. Accessibility Agents: /draft-release

      +

      The /draft-release command automates release note generation from your merged pull requests.

      +

      Usage

      +
      /draft-release v2.1.0
+/draft-release owner/repo v2.1.0
      +

      What it produces

      +
        +
      • Auto-categorized changes: Breaking Changes, Features, Bug Fixes, Dependencies
        • +
      • Each PR listed with number, title, and author
        • +
      • A full changelog link
        • +
      • Markdown formatted and ready to paste into GitHub's release editor
        • +
      +

      Example output

      +
      ## v2.1.0
+
+### New Features
+- Add `/project-status` command (#42, @alice)
+- Add `/onboard-repo` for first-time repo scanning (#38, @bob)
+
+### Bug Fixes
+- Fix keyboard navigation in triage workflow (#51, @charlie)
+- Correct screen reader announcement for merged PRs (#48, @alice)
+
+### Dependencies
+- Update github-mcp-server to v3.0.1 (#55)
+
+**Full Changelog:** https://github.com/community-access/accessibility-agents/compare/v2.0.0...v2.1.0
      +
      +

      See also: The /release-prep command runs a complete pre-release checklist (milestone status, open PRs, CI health, security, and then generates release notes) - useful when preparing a release from scratch rather than just generating notes.

      +
      +

      Part 2 - Repository Insights

      +

      9. What Is the Insights Tab?

      +

      The Insights tab shows quantitative activity data for a repository. It is primarily read-only and chart-heavy - but all underlying data is also presented in tables that screen readers can navigate.

      +

      Who can see Insights

      +
        +
      • Anyone can see Insights on a public repository
        • +
      • Private repository Insights require collaborator access
        • +
      +

      What Insights does NOT show

      +
        +
      • Individual user data in detail (e.g., lines per commit per person)
        • +
      • Real-time data (most views update daily or weekly)
        • +
      • Code quality scores
        • +
      +

      10. Navigating to Insights

      +

      From any repository:

      +
        +
      1. Navigate to the repository's main tab bar
        2. +
      2. Find and select the Insights tab
        3. +
      3. The Insights sub-navigation has multiple views listed on the left (or top on smaller screens)
        4. +
      +

      Screen reader path

      +
      T → navigate the repository tab bar
+→ "Insights" link → Enter
+→ Left sidebar has sub-navigation: Pulse, Contributors, Traffic, Commits, etc.
+→ K to navigate sidebar links → Enter to open each view
      +

      11. Pulse - Recent Activity Summary

      +

      Pulse is the Insights landing page. It summarizes activity in a chosen time period (last 24 hours, 7 days, or 30 days):

      +
        +
      • Open issues / Closed issues - net change in the time period
        • +
      • Open pull requests / Merged pull requests / Closed pull requests - with counts
        • +
      • Authors: N contributors pushed M commits to N branches
        • +
      • A list of merged PRs (each linked to the PR)
        • +
      • A list of proposed PRs (open)
        • +
      • A list of opened and closed issues
        • +
      +

      What it tells you as a contributor

      +
        +
      • Is this project actively maintained? (Are PRs being merged regularly?)
        • +
      • Is there a backlog? (Many open issues vs. few closures)
        • +
      • Is the maintainer responsive? (Time between PR open and merge)
        • +
      +

      Screen reader navigation

      +
      2 → Section headings: "Merged pull requests", "Proposed pull requests", "Closed issues", etc.
+3 → Individual PR/issue title links within each section
+K → Navigate all links
      +

      Learning Cards: Pulse (Recent Activity Summary)

      +
      +Screen reader users + +
        +
      • Pulse is the Insights landing page — after entering the Insights tab, you land here; use 2 to jump between section headings (Merged PRs, Opened Issues, etc.)
        • +
      • Each section lists linked PR or issue titles — press 3 to jump between individual items, or K to navigate the links directly
        • +
      • Use the time period selector (last 24 hours, 7 days, 30 days) at the top to scope the summary — Tab to it and select with arrow keys
        • +
      +
      + +
      +Low vision users + +
        +
      • Pulse displays activity counts in large numbers at the top of the page — zoom in to read the open/closed/merged totals
        • +
      • The merged PR and opened issue lists below the summary use standard link formatting — increase font size to scan titles comfortably
        • +
      • The time period toggle (24h, 7d, 30d) sits near the top — it can be small at default zoom; look for the underlined active period indicator
        • +
      +
      + +
      +Sighted users + +
        +
      • Pulse shows a dashboard-style summary at the top with counts for issues opened/closed and PRs opened/merged/closed in the chosen time period
        • +
      • Below the summary, merged PRs and proposed PRs are listed as clickable links — scan titles to see recent activity at a glance
        • +
      • Use the time period selector (24 hours, 7 days, 30 days) at the top right to adjust the window — 7 days is the default and most useful for weekly check-ins
        • +
      +
      + + +

      12. Contributors - Who Builds the Project

      +

      The Contributors view shows a bar chart of commits over time, with each contributor represented by a different color. Below the chart is a sortable table.

      +

      The table (accessible)

      +
        +
      • Username
        • +
      • Number of commits (with a link to filtered commit history)
        • +
      • Additions (lines added)
        • +
      • Deletions (lines removed)
        • +
      • Sorted by total commits by default
        • +
      +

      Why this matters as a new contributor

      +
        +
      • You can see how active top contributors are
        • +
      • After your first merged PR, your name appears here (with your commits)
        • +
      • You can link to your section (github.com/owner/repo/graphs/contributors) as proof of contribution
        • +
      +

      Screen reader

      +

      The chart is a canvas graphic - not directly readable. The table below it is fully accessible. Navigate with T to reach the table, then Tab for sorting controls.

      +
      T → Contributors table
+Tab → Column headers (click to sort: Commits, Additions, Deletions)
+↓ → Navigate rows (each contributor is a row)
+K → Links to each contributor's filtered commit list
      +

      Learning Cards: Contributors

      +

      Screen reader users:

      +
        +
      • The contributor chart is a canvas graphic that screen readers cannot access -- skip it and navigate to the data table below with T (next table) which contains the same information in accessible form
        • +
      • The table has sortable column headers (Commits, Additions, Deletions) -- Tab to a header and press Enter to sort; the table reloads with the new sort order
        • +
      • Each contributor's username is a link to their filtered commit list -- activate it to see every commit that person made to this repository
        • +
      +

      Low-vision users:

      +
        +
      • The bar chart uses color to distinguish contributors -- the table below provides the same data as text; zoom in on the table if the chart colors are hard to differentiate
        • +
      • Sorting by Commits (default) puts top contributors first -- at high zoom, the table may require horizontal scrolling to see the Additions and Deletions columns
        • +
      • After your first merged PR, your username appears in this table -- link to it (github.com/owner/repo/graphs/contributors) as proof of contribution in your portfolio
        • +
      +

      Sighted users:

      +
        +
      • The color-coded bar chart at the top shows commit frequency over time -- each contributor is a different color in the stacked bars
        • +
      • The table below the chart is sortable by column -- click Commits, Additions, or Deletions to reorder and quickly find the most active contributors
        • +
      • Your name appears here after your first merged PR -- bookmark the URL to reference your contribution history when building your developer portfolio
        • +
      +

      13. Traffic - Who Visits the Repo

      +

      Traffic shows who is viewing and cloning the repository. Available only to repository owners and collaborators with push access.

      +

      Metrics

      + + + + + + + + + + + + + + + + + + + + + + + +
      ViewWhat It Shows
      VisitorsUnique visitors and total page views over 14 days
      Git clonesNumber of times the repo was cloned (git clone, not forks)
      Referring sitesWhere traffic comes from (Google, Hacker News, direct, etc.)
      Popular contentWhich files and pages in the repo get the most views
      +

      Why this matters

      +
        +
      • If the README is the most-viewed file, documentation improvements have high impact
        • +
      • If traffic spiked when a blog post linked the repo, that's a good signal for community growth
        • +
      +

      14. Commits and Code Frequency

      +

      Commits shows commit frequency over the past year, by week. Useful for identifying:

      +
        +
      • Active development periods (many commits)
        • +
      • Dormant periods (no commits) - a project with 6+ months of inactivity may be unmaintained
        • +
      • Release sprints (burst of commits before a release tag)
        • +
      +

      Code Frequency shows additions and deletions per week as an area chart. A healthy codebase has more additions than deletions until it matures, then stabilizes.

      +

      Churn (high deletions alongside high additions) can indicate:

      +
        +
      • Heavy refactoring
        • +
      • Ongoing maintenance of large files
        • +
      • Active cleanup of technical debt
        • +
      +

      Screen reader note for both views: The charts are visual canvas elements. For a text-based view of commit history, use the Commits tab on the main repository page instead.

      +

      15. Dependency Graph

      +

      The Dependency Graph shows:

      +
        +
      • What your project depends on (libraries, packages)
        • +
      • What depends on your project (if others import your repo)
        • +
      +

      Dependents - repositories that depend on this one - is the "used by" count you see on the right sidebar of popular packages.

      +

      Enabling/viewing

      +
        +
      • Settings → Security & Analysis → Dependency graph → Enable
        • +
      • Navigate to Insights → Dependency graph
        • +
      +

      Why it matters for security: The dependency graph feeds Dependabot. If a vulnerability is found in a library, Dependabot uses this graph to identify which repos use the affected version and opens automated PRs to update them. See Appendix L: GitHub Security Features for more on Dependabot.

      +

      16. Network and Forks

      +

      The Network view shows a graphical branch/fork network - who has forked the repo, what branches exist, and how they diverge.

      +

      Screen reader note: The network graph is a canvas visualization not accessible to screen readers. The underlying fork list is accessible separately at github.com/owner/repo/forks.

      +

      The forks list (at /forks) is a simple table of who forked the repo - navigable with standard table navigation.

      +

      17. Community Standards

      +

      The Community Standards view (found in the Insights sidebar or in the main repository homepage's "Recommended" sidebar section) shows a checklist of community health files:

      + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + +
      FilePurposeStatus
      DescriptionOne-line repo summaryPresent or Missing
      READMEProject overviewPresent or Missing
      Code of ConductCommunity behavior standardsPresent or Missing
      Contributing guideHow to contributePresent or Missing
      LicenseUsage rightsPresent or Missing
      Issue templatesStructured issue formsPresent or Missing
      Pull request templatePR checklistPresent or Missing
      Security policyHow to report vulnerabilitiesPresent or Missing
      +

      A fully green checklist signals a well-maintained project. For accessibility-agents contributors, adding a missing community health file is always a welcome good first issue contribution.

      +

      Screen reader

      +
      H / 2 → "Community Standards" section heading
+Tab → Each checklist item (links to add missing files)
      +

      18. Screen Reader Navigation Reference

      +

      Releases Pages

      +

      Repository home page (finding releases)

      +
      Right sidebar:
+→ H or 3 to find "Releases" heading
+→ K to the version link (e.g., "v2.1.0") → Enter opens that release
+→ K to the "N releases" count link → Enter opens full list
      +

      Releases list page

      +
      2         → Major section headings
+3         → Individual release title headings (each release is an h2 or h3)
+K         → Navigate links (assets, tag, compare)
+↓         → Read release notes inline
      +

      Individual release page

      +
      H / 2     → Section headings within release notes
+I         → List items (change entries)
+K         → Links (PRs referenced, comparison link, asset downloads)
      +

      Comparing two releases (the Changelog)

      +

      The compare URL (/compare/v1.0.0...v2.0.0) shows a diff of all commits and merged PRs between two tags:

      +
      3         → Individual commit or PR headings
+I         → Commit list items
      +

      Insights Pages

      +

      Insights tab bar (sub-navigation)

      +
      Insights left sidebar:
+K → Navigate sidebar links: Pulse, Contributors, Traffic, Commits, Code frequency, Dependency graph, Network, Forks, Community
+Enter → Open that Insights view
      +

      Charts and graphs - general strategy

      +

      Most Insights charts are canvas or SVG visuals. They announce as "image" or "graphic" to screen readers. Skip the chart and use the data table or list below it, which contains the same information in accessible form.

      +
      T → Jump to data tables
+H → Section headings
+I → List items (in Pulse views)
      +

      Pulse view

      +
      2 → "Merged pull requests", "Opened issues", etc. sections
+3 → Individual PR/issue titles
+K → Links to each item
      +

      19. Accessibility Agents: /my-stats and /team-dashboard

      +

      Instead of navigating GitHub's chart-heavy Insights UI, Accessibility Agents provides two commands that deliver the same data in text form directly in VS Code.

      +

      /my-stats

      +

      Shows your personal contribution statistics across all tracked repos:

      +
      /my-stats
+/my-stats last 30 days
+/my-stats org:community-access
      +

      Output includes:

      +
        +
      • PRs opened and merged
        • +
      • Issues filed and closed
        • +
      • Reviews conducted
        • +
      • Commits pushed
        • +
      • Compare to previous period
        • +
      +

      /team-dashboard

      +

      Shows team-wide activity across tracked repos - who contributed what, response times, review coverage:

      +
      /team-dashboard
+/team-dashboard org:community-access
+/team-dashboard sprint
      +

      Output includes:

      +
        +
      • Per-person contribution summary
        • +
      • Review coverage (how many PRs got reviews)
        • +
      • Open issues by assignee
        • +
      • CI health across team repos
        • +
      +
      +

      Next: Appendix T: Community and Social
      Back: Appendix R: Projects Deep Dive
      Teaching chapter: Chapter 08: Open Source Culture

      + +
      + + + + diff --git a/html/admin/qa-bundle/docs/appendix-t-community-and-social.html b/html/admin/qa-bundle/docs/appendix-t-community-and-social.html new file mode 100644 index 00000000..5747b1f0 --- /dev/null +++ b/html/admin/qa-bundle/docs/appendix-t-community-and-social.html @@ -0,0 +1,965 @@ + + + + + + + Appendix T: Community and Social - GIT Going with GitHub + + + + + + + + +
      +

      Appendix T: Community and Social

      +
      +

      Reference companion to: Chapter 08: Open Source Culture | Also relevant: Chapter 10

      +

      Authoritative source: GitHub Docs: About organizations | GitHub Docs: Sponsors

      +
      +
      +

      This appendix consolidates three related reference topics: GitHub profiles, sponsors, and wikis (formerly Appendix R), GitHub organizations and templates (formerly Appendix S), and GitHub social features (formerly Appendix AE).

      +
      +
      +

      GitHub Profiles, Sponsors, and Wikis

      +
      +

      Listen to Episode 35: Profile, Sponsors, and Wikis - a conversational audio overview of this chapter. Listen before reading to preview the concepts, or after to reinforce what you learned.

      +
      +

      Building Your Community Presence on GitHub

      +
      +

      This appendix covers three community-facing GitHub features: your profile README (how the world sees you), GitHub Sponsors (financially supporting the people whose work you depend on), and GitHub Wikis (community-editable documentation inside a repository).

      +
      +

      Learning Cards: Profiles, Sponsors, and Wikis

      +
      +Screen reader users + +
        +
      • Your profile README is announced as regular page content when someone visits your profile -- use ## headings for structure so visitors can navigate with H
        • +
      • The Sponsor button on a profile or repo is a standard button element -- press B to cycle through buttons until you hear "Sponsor"
        • +
      • Wiki pages are read in browse mode like any other GitHub Markdown page -- use heading navigation to jump between sections
        • +
      +
      + +
      +Low vision users + +
        +
      • Profile READMEs respect GitHub's dark and light themes -- test yours in both modes to confirm text remains readable
        • +
      • The Sponsor button uses a heart icon with a pink/magenta accent -- look near the repo name or profile photo area
        • +
      • Wiki sidebar navigation appears on the right side of the page with links to all wiki pages
        • +
      +
      + +
      +Sighted users + +
        +
      • Your profile README appears directly below your avatar and bio -- visitors see it immediately on your profile page
        • +
      • The Sponsor heart icon is near the top of a profile or repository page, next to the Star and Watch buttons
        • +
      • Wiki pages have an auto-generated sidebar listing all pages -- click any page title to navigate directly
        • +
      +
      + + +

      Profile Customization

      +

      The Special Profile README

      +

      GitHub has a hidden feature: if you create a repository named exactly your-username/your-username (e.g., janesmith/janesmith), the README in that repo appears on your GitHub profile page.

      +

      This is your profile README. It's a custom introduction visible to anyone who visits your profile.

      +

      Creating Your Profile README

      +
        +
      1. Create a new repository
        2. +
      2. Name it exactly your-username (match your GitHub username exactly, case-sensitive)
        3. +
      3. Make it public
        4. +
      4. Initialize with a README
        5. +
      5. Edit the README with whatever you want to show on your profile
        6. +
      +

      What to include

      +
        +
      • Introduction: Who you are, what you work on
        • +
      • Current focus: What projects or technologies you're learning
        • +
      • Skills: Languages, frameworks, tools (optional)
        • +
      • How to reach you: Email, LinkedIn, personal site
        • +
      • Fun facts: Hobbies, interests (optional-keeps it human)
        • +
      +

      Example profile README

      +
      # Hi, I'm Jane Smith
+
+I'm an accessibility advocate and open source contributor focused on making the web more inclusive.
+
+## Current focus
+- Contributing to NVDA documentation
+- Building accessible React components
+- Learning TypeScript
+
+## Skills
+- JavaScript, Python, HTML/CSS
+- Screen reader testing (NVDA, JAWS, VoiceOver)
+- Git, GitHub, GitHub Actions
+
+## Get in touch
+- Email: jane@example.com
+- LinkedIn: [linkedin.com/in/janesmith](https://linkedin.com/in/janesmith)
+
+## Fun fact
+I've been using screen readers for 8 years and believe accessible design is better design for everyone.
      +

      Profile README Best Practices

      +

      Keep it concise - visitors skim, not read
      Update occasionally - a README from 2019 looks stale
      Be authentic - people connect with real humans, not buzzwords
      Include links - make it easy to learn more or get in touch

      +

      Avoid excessive badges - 50 skill badges is visual clutter and screen reader noise
      Skip auto-generated stats - "commits per day" widgets are often inaccessible
      Don't overthink it - a simple paragraph is better than nothing

      +

      Screen Reader Considerations

      +
        +
      • Use headings (##) for structure
        • +
      • Provide alt text for any images: ![Description of image](url)
        • +
      • Avoid ASCII art - screen readers read it character by character (annoying)
        • +
      • Test your README with a screen reader before publishing
        • +
      +

      Other Profile Customizations

      +

      Pinned repositories (up to 6)

      +
        +
      • Highlight your best work on your profile
        • +
      • Navigate to your profile → Select "Customize your pins"
        • +
      • Choose which repos appear first
        • +
      +

      Contribution graph

      +
        +
      • Shows your GitHub activity over the past year
        • +
      • Green squares indicate days with commits, PRs, issues, etc.
        • +
      • Cannot be customized but reflects consistent contribution
        • +
      +

      Status

      +
        +
      • Set a temporary status message (e.g., "On vacation until March 15")
        • +
      • Navigate to your profile → Select the smile icon → Set status
        • +
      +

      GitHub Sponsors (Supporting Open Source)

      +

      What Is GitHub Sponsors?

      +

      GitHub Sponsors lets you financially support developers and projects you depend on. It's like Patreon for open source.

      +

      How it works

      +
        +
      • Developers/projects create a Sponsors profile
        • +
      • You choose a monthly sponsorship tier ($5, $10, $25/month, etc.)
        • +
      • Your payment goes directly to the developer (GitHub takes no fees)
        • +
      +

      Why Sponsor?

      +
        +
      • Sustainability: Many open source maintainers volunteer their time. Sponsorships help them keep projects alive.
        • +
      • Gratitude: If a project saved you hours of work, sponsorship is a way to say thanks.
        • +
      • Priority support: Some maintainers offer sponsor-only Discord access, early releases, or prioritized bug fixes.
        • +
      +

      How to Sponsor

      +
        +
      1. Navigate to a user or repository's GitHub page
        2. +
      2. Look for the "Sponsor" button (heart icon)
        3. +
      3. Choose a tier or custom amount
        4. +
      4. Select payment method (credit card or PayPal)
        5. +
      5. GitHub sends a receipt; your sponsorship appears on your profile (optionally publicly)
        6. +
      +

      Screen reader navigation

      +
        +
      • The Sponsor button appears near the profile photo or repo name
        • +
      • Press B to cycle through buttons on the page until you hear "Sponsor"
        • +
      +

      Can I Receive Sponsorships?

      +

      Yes! If you maintain an open source project or contribute regularly:

      +
        +
      1. Navigate to github.com/sponsors
        2. +
      2. Select "Join the waitlist" or "Set up sponsors"
        3. +
      3. Connect a payment method (Stripe or bank account)
        4. +
      4. Create sponsor tiers with descriptions
        5. +
      5. Promote your Sponsors page to your audience
        6. +
      +

      Many accessibility advocates successfully use Sponsors to fund their work improving assistive technology and inclusive design.

      +

      GitHub Wikis

      +

      What Is a GitHub Wiki?

      +

      Every repository can have a wiki - a space for documentation separate from the code. It's lightweight and Markdown-based.

      +

      When to use a wiki

      +
        +
      • Multi-page documentation (tutorials, guides, FAQs)
        • +
      • Community-editable docs (wikis can be editable by anyone)
        • +
      • Knowledge that doesn't belong in README (too long, too specific)
        • +
      +

      When NOT to use a wiki

      +
        +
      • Your project already uses GitHub Pages or external docs
        • +
      • Documentation needs to be version-controlled with code (wikis are separate Git repos)
        • +
      • You want full control (wikis are less customizable than Pages)
        • +
      +

      Accessing a Repo's Wiki

      +
        +
      1. Navigate to the repository
        2. +
      2. Select the "Wiki" tab
        3. +
      3. If no wiki exists, you'll see "Create the first page"
        4. +
      +

      Creating Wiki Pages

      +
        +
      1. Go to the Wiki tab
        2. +
      2. Select "New page"
        3. +
      3. Add a title and content (Markdown)
        4. +
      4. Select "Save"
        5. +
      +

      Wiki pages automatically appear in a sidebar for navigation.

      +

      Wiki Accessibility

      +
        +
      • GitHub's wiki editor is the same as the issue/PR comment editor
        • +
      • All Markdown features work (headings, lists, links, code blocks)
        • +
      • Use proper heading hierarchy (##, ###) for screen reader navigation
        • +
      • Link between wiki pages: [[Page Title]]
        • +
      • Screen reader caveat: Wiki pages are a separate Git repository. Any changes pushed directly to the wiki's git remote are not tracked by the main repository's branch protection - meaning no PR review process applies. Treat wikis as community-editable supplementary docs, not your primary critical documentation source.
        • +
      +

      Return to: Resources | Appendix S - Organizations and Templates | Appendix G - GitHub Discussions | Appendix T - Contributing to Open Source | Appendix A - Glossary

      +
      +

      GitHub Organizations and Templates

      +
      +

      Listen to Episode 36: Organizations and Templates - a conversational audio overview of this chapter. Listen before reading to preview the concepts, or after to reinforce what you learned.

      +
      +

      A Contributor's Guide to GitHub's Structural Features

      +
      +

      This appendix covers three features that shape how repositories and communities are organized on GitHub: repository templates (how new projects are bootstrapped), GitHub organizations (the account type behind most open source projects and companies), and repository settings (the configuration that governs visibility, archiving, and other behavior contributors encounter in the wild).

      +
      +

      Learning Cards: Organizations and Templates

      +
      +Screen reader users + +
        +
      • The "Use this template" button is near the "Code" button at the top of a template repository -- press B to navigate buttons until you hear it
        • +
      • Organization profiles list repositories and members under heading sections -- use H to jump between People, Repositories, and Projects
        • +
      • Repository visibility (Public, Private, Internal) is announced as a badge near the repository name heading
        • +
      +
      + +
      +Low vision users + +
        +
      • Template repositories show a green "Use this template" button prominently near the top -- it replaces or sits alongside the Fork button
        • +
      • Organization pages use the same layout as personal profiles but with team-oriented sections
        • +
      • Archived repositories display a yellow warning banner across the top of the page
        • +
      +
      + +
      +Sighted users + +
        +
      • Template repos display "Use this template" as a green button near the Code button -- do not confuse it with Fork, which keeps upstream history
        • +
      • Organization profiles show member avatars in a grid and repositories in a searchable list below
        • +
      • Look for the visibility label (Public/Private) as a small badge next to the repository name
        • +
      +
      + + +

      Repository Templates

      +

      Template vs. Fork - Which One?

      +

      These are two very different actions that both appear near the "Code" button:

      + + + + + + + + + + + + + + + + + + +
      ActionUse when...What you get
      ForkContributing back to the original projectFull git history; your changes can be PRed upstream
      Use this templateStarting a new project based on the structureClean git history; no connection to the original repo
      +

      GitHub Skills courses use "Use this template" - you start fresh with the course scaffold but your copy has no upstream connection.

      +

      accessibility-agents could serve as a template if you want to build your own agent suite starting from its structure without forking.

      +

      Creating a Template Repository

      +

      Maintainers can mark any repository as a template:

      +
        +
      1. Navigate to the repository's Settings tab
        2. +
      2. Scroll to the "General" section → find the "Template repository" checkbox
        3. +
      3. Check it and save
        4. +
      4. The repository now shows a "Use this template" button instead of (or alongside) "Fork"
        5. +
      +

      Using a Template Repository

      +
        +
      1. Navigate to the template repository
        2. +
      2. Select "Use this template" button (near the top, next to "Code")
        3. +
      3. Select "Create a new repository"
        4. +
      4. Name your new repository, choose visibility, and confirm
        5. +
      5. GitHub creates a new repository with the template's files but no commit history
        6. +
      +

      Screen reader path

      +
      B → navigate buttons → find "Use this template" → Enter
+↓ → "Create a new repository" from the dropdown → Enter
      +

      GitHub Organizations - A Contributor's View

      +

      What Is an Organization?

      +

      A GitHub organization is an account that multiple people share. Instead of github.com/username/repo, organization repos live at github.com/org-name/repo. The workshop's central project lives at github.com/community-access/accessibility-agents - community-access is an organization.

      + + + + + + + + + + + + + + + + + + + + + + + +
      Personal AccountOrganization Account
      Owned by one personShared by a team or community
      Single-person reposRepos are shared assets
      Your profile at github.com/usernameOrg profile at github.com/org-name
      You are the only adminHas owners, members, and optional teams
      +

      Joining an Organization

      +

      Maintainers can invite you to join. When invited:

      +
        +
      1. You receive an email + GitHub notification
        2. +
      2. Navigate to github.com/settings/organizations to accept
        3. +
      3. Or click the link in the invitation email
        4. +
      +

      You can also be a public contributor to an org repo without being a member - you fork the repo and submit PRs without needing an invitation.

      +

      Organization Membership Visibility

      +
        +
      • By default, your org membership is private (only you and org owners can see it)
        • +
      • You can set it to public in your organization membership settings
        • +
      • Public membership appears on your GitHub profile under "Organizations"
        • +
      • For community-access: if you become a member, set your membership public to show your contribution publicly on your profile
        • +
      +

      Teams Inside Organizations

      +

      Organizations can create teams (e.g., @community-access/accessibility-reviewers). When you see a team mentioned in a PR or issue, that @mention notifies everyone on that team. As a contributor, you don't need to create teams - just understand why you see them.

      +

      Navigating an Organization Profile Page

      +

      At github.com/community-access:

      +
      H → headings: org name, People, Repositories, Projects sections
+1 → jumps to the org name heading
+Links → navigate to individual repositories, members, and projects
      +

      Organization-level Projects (like the community-access project board) appear in the org's Projects tab, not inside any single repository.

      +

      Repository Settings - What Contributors Need to Know

      +

      You may not have Settings access to most repositories (that requires maintainer role). But knowing what's there helps you understand why a repository behaves the way it does.

      +

      Repository Visibility

      + + + + + + + + + + + + + + + + + + + +
      SettingWhat it means for contributors
      PublicAnyone can view and fork; you don't need an account to read it
      PrivateOnly invited users can see or contribute
      Internal (org only)Visible to all org members; cannot be forked outside the org
      +

      The repository's visibility label appears on its page. Screen readers: the visibility badge is usually near the repo name heading (H1).

      +

      Archived Repositories

      +

      When a maintainer archives a repository, it becomes read-only:

      +
        +
      • No new issues, PRs, or comments can be created
        • +
      • Existing content is fully preserved and viewable
        • +
      • The UI shows a yellow banner: "This repository has been archived by the owner."
        • +
      • Screen readers: NVDA/JAWS will read this banner when you navigate to the top of the page with Ctrl+Home
        • +
      +

      If you find a repo you planned to contribute to is archived, look for a fork or successor project.

      +

      Repository Topics

      +

      Topics are keyword tags on a repository (e.g., accessibility, screen-reader, open-source). They appear as colored chips on the repository home page and improve discoverability in GitHub search.

      +
        +
      • As a contributor: Topics tell you what the project is about at a glance
        • +
      • As a maintainer: Add topics in Settings → General → Topics section to improve search ranking
        • +
      • Screen reader: Topics are links in the "About" sidebar section; use B (next button) or Links list to reach them
        • +
      +

      Default Branch Name

      +

      The default branch is the one all PRs target by default. Modern projects use main; older projects may use master or another name. When you clone and create a branch, you always branch from the repository's default branch.

      +

      The default branch name appears in the branch selector at the top of the Code tab.

      +

      Return to: Resources | Appendix R - GitHub Profile, Sponsors, and Wikis | Appendix A - Glossary

      +
      +

      GitHub Social Features

      +
      +

      Episode coming soon: GitHub Social - a conversational audio overview of this appendix. Listen before reading to preview the concepts, or after to reinforce what you learned.

      +
      +

      GitHub Is More Than a Code Host — It's a Community

      +
      +

      Who this is for: You have learned the basics of GitHub and want to know how to use it as a social platform — discovering interesting projects, following developers whose work you admire, and building a presence in the open source community. This appendix covers the social layer of GitHub that most tutorials skip entirely.

      +
      +

      GitHub has over 100 million developers on it. The social features — stars, follows, Explore, Topics, trending repos — are how you find the interesting ones, stay connected to projects you care about, and make yourself visible to the community.

      +

      Learning Cards: Social Features

      +
      +Screen reader users + +
        +
      • The Star button is announced as "Star this repository" or "Unstar this repository" -- press B to find it in the repository header area
        • +
      • The Follow button on a user profile is announced as "Follow [username]" -- Tab forward from the avatar and bio to reach it
        • +
      • On the Explore and Trending pages, each repository entry is a heading with a link -- use H or 3 to jump between entries
        • +
      +
      + +
      +Low vision users + +
        +
      • Star and Watch buttons sit side by side in the repository header with distinct icons (star and eye) -- both show counts next to them
        • +
      • Your contribution graph uses green intensity to show activity levels -- enable high-contrast theme if the color differences are hard to distinguish
        • +
      • The Trending page lists repositories in a numbered vertical list with star counts and daily gain on the right side
        • +
      +
      + +
      +Sighted users + +
        +
      • The Star button (star icon) and Watch button (eye icon) are in the top-right header of every repository page, next to Fork
        • +
      • Your home feed at github.com shows activity from people you follow and repos you watch -- curate it by adjusting who you follow
        • +
      • GitHub Lists let you organize starred repos into named collections visible at your profile's Stars tab -- use the dropdown arrow next to Star to add to a list
        • +
      +
      + +
      +

      Table of Contents

      +
        +
      1. Stars — Bookmarking and Signaling Projects You Love
        2. +
      2. Watching Repositories — Staying in the Loop
        3. +
      3. Following People — Building Your Developer Network
        4. +
      4. Your Home Feed — What You See When You Log In
        5. +
      5. GitHub Explore — Discovering New Projects
        6. +
      6. Trending — What's Popular Right Now
        7. +
      7. Topics — Finding Projects by Category
        8. +
      8. GitHub Lists — Organizing Your Stars
        9. +
      9. Finding Accessible and Inclusive Projects
        10. +
      10. Building Your Own Presence
        11. +
      11. The GitHub CLI for Social Features
        12. +
      12. Screen Reader Navigation Guide
        13. +
      +
      +

      1. Stars — Bookmarking and Signaling Projects You Love

      +

      What a star is

      +

      A star is GitHub's version of a bookmark combined with a "like." When you star a repository:

      +
        +
      • It saves to your starred list at github.com/username?tab=stars — easy to find later
        • +
      • It signals to the maintainer that their work is valued
        • +
      • It contributes to the project's star count, which helps others discover it
        • +
      • It may appear in your followers' feeds
        • +
      +

      Why star count matters to projects

      +

      Star counts are a social proof signal — developers browsing for tools often sort by stars to find well-regarded projects. A project going from 10 stars to 1,000 stars can dramatically change how many contributors it attracts. Your star genuinely matters.

      +

      How to star a repository

      +

      GitHub.com

      +

      On any repository page, the Star button is in the top-right area of the repository header, next to Fork.

      +
        +
      • Click Star to star the repository — the button changes to Starred with a filled star icon
        • +
      • Click the dropdown arrow next to Star to choose a List to organize it into (see Section 8)
        • +
      • Click Starred to unstar
        • +
      +

      Keyboard shortcut

      +

      On a repository page, press g then s to toggle the star.

      +

      Screen reader navigation

      +
        +
      • NVDA/JAWS: The Star button is in the page region after the repository title heading. Navigate by button (B) or Tab to find it. It's announced as "Star this repository" or "Unstar this repository."
        • +
      • VoiceOver: VO+Command+J to jump to buttons, or Tab through the header area. The button label changes between "Star" and "Starred."
        • +
      +

      GitHub CLI

      +
      # Star a repository
+gh api user/starred/owner/repo --method PUT
+
+# Unstar a repository
+gh api user/starred/owner/repo --method DELETE
+
+# List your starred repositories
+gh api user/starred --jq '.[].full_name'
+
+# Check if you've starred a repo
+gh api user/starred/owner/repo --silent && echo "Starred" || echo "Not starred"
      +

      Viewing your stars

      +

      Go to github.com/username?tab=stars — or click your avatar → Your stars.

      +

      You'll see all your starred repositories sorted by most recently starred. Use the search box to filter by name, and the language filter to narrow by programming language.

      +

      Learning Cards: Stars

      +

      Screen reader users:

      +
        +
      • The Star button is in the repository header area -- press B to navigate buttons until you hear "Star this repository" (or "Unstar this repository" if already starred); press Enter to toggle
        • +
      • The keyboard shortcut g then s on any repository page toggles the star without needing to navigate to the button
        • +
      • Your starred repos are listed at github.com/username?tab=stars -- each entry is a heading with the repo name as a link; use H to jump between starred repos
        • +
      +

      Low-vision users:

      +
        +
      • The Star button shows a star icon with a count next to it in the repository header -- at high zoom, the button may wrap below the repo name; look for the star icon near Fork and Watch
        • +
      • When you star a repo, the button changes from an outline star to a filled star with the label "Starred" -- the visual change is subtle; confirm by re-reading the button text
        • +
      • The dropdown arrow next to Star lets you add the repo to a List -- look for a small triangle icon to the right of the Star button at high magnification
        • +
      +

      Sighted users:

      +
        +
      • The Star button is in the top-right header of every repository page, between Watch and Fork -- the count next to it shows total stars
        • +
      • Click the dropdown arrow next to Star to add the repo to a named List (like playlists for repos) -- this keeps your stars organized instead of one long pile
        • +
      • Your stars page at github.com/username?tab=stars is public -- curate it as a "recommended tools" list for your community
        • +
      +
      +

      2. Watching Repositories — Staying in the Loop

      +

      What watching does

      +

      When you watch a repository, GitHub sends you notifications about activity in it — new issues, pull requests, releases, and more. Unlike stars (which are passive bookmarks), watching is active — you're opting into the conversation.

      +

      Watch levels

      +

      GitHub gives you granular control over how much you hear from a repo:

      + + + + + + + + + + + + + + + + + + + + + + + + + + + +
      LevelWhat you receive
      Not watchingOnly notified if you're mentioned or have participated
      Participating and @mentionsNotified for threads you're in or @mentioned in (default for repos you contribute to)
      All ActivityEvery issue, PR, comment, and release — for very active repos this can be noisy
      Releases onlyOnly new releases — great for tools you use and want to know when they update
      IgnoreNever notified, even if mentioned (useful for very noisy forks)
      +

      How to watch a repository

      +

      On any repository page, the Watch button is next to the Star button in the header.

      +
        +
      1. Click Watch to open the dropdown
        2. +
      2. Choose your notification level
        3. +
      3. The button updates to show your current setting
        4. +
      +
      +

      Tip: For most repositories you contribute to, "Participating and @mentions" is the right level — you hear about threads you're in without inbox overload. Use "Releases only" for dependencies and tools you use but don't contribute to.

      +
      +

      GitHub CLI

      +
      # Watch a repository (all activity)
+gh api repos/owner/repo/subscription --method PUT --field subscribed=true
+
+# Watch releases only (requires GitHub.com — not available via API alone)
+# Use the web UI for granular watch levels
+
+# Ignore a repository
+gh api repos/owner/repo/subscription --method PUT --field ignored=true
+
+# List repositories you're watching
+gh api user/subscriptions --jq '.[].full_name'
+
+# Stop watching a repository
+gh api repos/owner/repo/subscription --method DELETE
      +

      Learning Cards: Watching Repositories

      +

      Screen reader users:

      +
        +
      • The Watch button is next to the Star button in the repository header -- press B to navigate buttons until you hear "Watch" or a watch level label; press Enter to open the dropdown
        • +
      • The watch level dropdown presents radio-style options (Not watching, Participating, All Activity, Releases only, Ignore) -- arrow through them and press Enter to select
        • +
      • "Participating and @mentions" is the recommended default for repos you contribute to -- it notifies you only for threads you are in or mentioned in, avoiding inbox overload
        • +
      +

      Low-vision users:

      +
        +
      • The Watch button shows an eye icon with a dropdown arrow and a count of watchers -- at high zoom, look for it immediately to the left of the Star button in the repository header
        • +
      • The dropdown menu lists five watch levels vertically with radio indicators -- the currently selected level has a filled radio dot or checkmark next to it
        • +
      • "Releases only" is the best choice for tools and dependencies you use but do not contribute to -- it sends one notification per release instead of every issue and PR
        • +
      +

      Sighted users:

      +
        +
      • The Watch button (eye icon) is in the header next to Star and Fork -- click it to open a dropdown with five notification levels
        • +
      • "Participating and @mentions" (the default for repos you contribute to) gives you relevant notifications without noise -- upgrade to "All Activity" only for small, focused repos
        • +
      • The watcher count next to the button shows how many people are watching -- a high watcher count on a repo signals an active, engaged community
        • +
      +
      +

      3. Following People — Building Your Developer Network

      +

      What following does

      +

      When you follow a developer on GitHub:

      +
        +
      • Their public activity appears in your home feed
        • +
      • You see when they star a repository, create a new repo, or get a new follower
        • +
      • They receive a notification that you followed them
        • +
      • You appear in their followers list
        • +
      +

      Following is one-way (like Twitter/X) — they don't need to follow you back.

      +

      Who to follow

      +

      Start with people whose work you already use:

      +
        +
      • Maintainers of tools and libraries you use daily
        • +
      • Authors of blog posts or talks that helped you learn
        • +
      • Developers in accessibility, open source, or your tech stack
        • +
      +

      Find them by:

      +
        +
      • Visiting the Contributors tab of a repository you love: github.com/owner/repo/graphs/contributors
        • +
      • Checking who opened issues or PRs you found valuable
        • +
      • Looking at who your existing follows follow
        • +
      +

      How to follow someone

      +

      On any user profile page (github.com/username), click the Follow button below their avatar. The button changes to Following.

      +

      To unfollow: click Following → it changes back to Follow.

      +

      Screen reader navigation

      +
        +
      • Navigate to the profile page
        • +
      • The Follow/Following button is near the top of the page, below the avatar and bio
        • +
      • NVDA/JAWS: press B to jump to buttons; the button is labelled "Follow [username]"
        • +
      • VoiceOver: Tab to the button or use VO+Command+J
        • +
      +

      GitHub CLI

      +
      # Follow a user
+gh api user/following/username --method PUT
+
+# Unfollow a user
+gh api user/following/username --method DELETE
+
+# List who you're following
+gh api user/following --jq '.[].login'
+
+# List your followers
+gh api user/followers --jq '.[].login'
+
+# Check if you follow a specific person
+gh api user/following/username --silent && echo "Following" || echo "Not following"
+
+# See who a user follows (useful for discovering new people)
+gh api users/username/following --jq '.[].login'
      +

      Viewing someone's profile

      +

      A GitHub profile shows:

      +
        +
      • Pinned repositories — the 6 repos they've chosen to highlight
        • +
      • Contribution graph — a visual grid of their activity over the past year (green squares = more activity)
        • +
      • Recent activity — PRs opened, issues commented on, repos starred
        • +
      • Repositories — all their public repos
        • +
      • Stars — repos they've starred (great for discovery)
        • +
      • Followers / Following counts
        • +
      +
      +

      Screen reader tip: The contribution graph is a visual calendar that screen readers may announce as a table or grid. Navigate with arrow keys to read individual day entries — each cell describes the date and number of contributions.

      +
      +
      +

      4. Your Home Feed — What You See When You Log In

      +

      When you go to github.com while logged in, your home feed shows activity from people and repositories you follow or watch.

      +

      What appears in your feed

      +
        +
      • Repositories starred by people you follow — "Jane starred awesome-accessibility"
        • +
      • New repositories created by people you follow
        • +
      • Releases from repositories you watch
        • +
      • Public activity from people you follow (PRs opened, issues commented on)
        • +
      • "For you" recommendations — GitHub suggests repos and people based on your activity
        • +
      +

      Your feed is a discovery tool

      +

      One of the best ways to find new interesting projects is to follow a few active developers in your area of interest and watch what they star. If 5 people you respect all starred the same new tool this week, it's probably worth a look.

      +

      Customising your feed

      +

      There's no fine-grained feed filter — you control the feed by controlling who you follow and what you watch. Unfollow noisy accounts, follow more focused ones.

      +
      +

      5. GitHub Explore — Discovering New Projects

      +

      GitHub Explore at github.com/explore is the discovery hub — curated collections, trending repos, and personalised recommendations.

      +

      What Explore shows

      +
        +
      • Trending — most-starred repos this week (see Section 6)
        • +
      • Topics — browse by subject area (see Section 7)
        • +
      • Collections — curated lists of thematically related repos (e.g., "Tools for Open Source", "Accessibility Projects")
        • +
      • "For you" personalised recommendations — based on your stars, follows, and language preferences
        • +
      + +
        +
      1. Go to github.com/explore
        2. +
      2. The page uses landmark regions — jump to main to skip navigation
        3. +
      3. Collections and trending repos are listed as article/heading groups
        4. +
      4. Use heading navigation (H) to jump between sections
        5. +
      5. Each repo entry has a heading (repo name as a link), language badge, star count, and description
        6. +
      +
      +

      6. Trending — What's Popular Right Now

      +

      GitHub Trending at github.com/trending shows repositories gaining the most stars over a time period. It's one of the best places to discover new tools before everyone else knows about them.

      + +

      Use the dropdowns at the top of the page to filter by:

      + + + + + + + + + + + + + + + +
      FilterOptions
      LanguageAny programming language, or "All languages"
      Time periodToday, This week, This month
      + +

      Switch to github.com/trending/developers to see which developers are gaining the most followers — another great way to find people to follow.

      +

      GitHub CLI

      +
      # Trending repos aren't in the official API, but you can get recently starred popular repos:
+gh search repos --sort stars --order desc --limit 20 --language markdown
+
+# Trending in a specific language
+gh search repos --sort stars --order desc --limit 20 --language python
      +
      +

      7. Topics — Finding Projects by Category

      +

      Every repository can be tagged with topics — keywords like accessibility, screen-reader, wcag, python, machine-learning. Topics are how maintainers categorise their work so others can discover it.

      +

      Browsing topics

      +

      Click any topic tag on a repository page to see all repos tagged with that topic. Or go directly:

      +
      https://github.com/topics/accessibility
+https://github.com/topics/screen-reader
+https://github.com/topics/good-first-issue
      +

      Useful topics for this community

      + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + +
      TopicWhat you'll find
      accessibilityTools, frameworks, and guides focused on a11y
      screen-readerProjects specifically for screen reader users
      wcagWCAG compliance tools and resources
      a11yShort form of accessibility — many projects use this
      good-first-issueProjects that welcome newcomers
      help-wantedProjects actively looking for contributors
      open-sourceGeneral open source projects
      assistive-technologyAT tools and resources
      +

      GitHub CLI

      +
      # Search for repos with a specific topic
+gh search repos --topic accessibility --limit 20
+gh search repos --topic screen-reader --stars ">50"
+
+# Add a topic to your own repository
+gh api repos/owner/repo/topics --method PUT --field names[]="accessibility" --field names[]="screen-reader"
      +
      +

      8. GitHub Lists — Organizing Your Stars

      +

      Lists let you group your starred repositories into named collections — like playlists for code. Instead of one big pile of stars, you can have "Accessibility Tools," "Learning Resources," "Projects I Contribute To," etc.

      +

      Creating a list

      +
        +
      1. Go to your stars: github.com/username?tab=stars
        2. +
      2. Select "Create list" (top right of the stars page)
        3. +
      3. Give it a name and optional description
        4. +
      4. Select "Create"
        5. +
      +

      Or create a list while starring:

      +
        +
      1. On a repo page, click the dropdown arrow next to the Star button
        2. +
      2. Select "Create a list" or add to an existing list
        3. +
      +

      Adding repos to lists

      +
        +
      • From any repo page: Star dropdown → check the list name
        • +
      • From your stars page: click the list icon on any starred repo row
        • +
      +

      Viewing and sharing lists

      +

      Your lists are public at github.com/username?tab=stars — anyone can browse them. This is useful for sharing curated resources with your community.

      +

      GitHub CLI

      +
      # Lists are managed through the GitHub web interface only
+# You can view stars via CLI:
+gh api user/starred --jq '.[] | {name: .full_name, description: .description}' | head -20
      +
      +

      9. Finding Accessible and Inclusive Projects

      +

      If you're specifically looking for projects that welcome contributors with disabilities, or that focus on accessibility work, here are the best ways to find them.

      +

      Search strategies

      +
      # Search for accessibility-focused repos
+gh search repos "accessibility" --topic a11y --stars ">100"
+
+# Find repos with good first issues in accessibility
+gh search issues "accessibility" --label "good first issue" --state open
+
+# Find issues tagged both "accessibility" and "help wanted"
+gh search issues --label "accessibility" --label "help wanted" --state open
      +

      On GitHub.com:

      + +

      Organisations to follow

      +

      GitHub organisations are collections of repos grouped by a team or company. You can follow an org to get notified of their public activity.

      +

      Notable accessibility-focused organisations on GitHub:

      +
        +
      • github.com/Community-Access — the organisation behind this workshop
        • +
      • Search for org:github accessibility to find GitHub's own accessibility work
        • +
      • Many assistive technology companies have open source components on GitHub — search for your AT provider
        • +
      +

      Looking at who your community follows

      +

      If you follow someone doing accessibility work, browse their stars and their following list — this is one of the fastest ways to discover the accessibility community on GitHub.

      +
      +

      10. Building Your Own Presence

      +

      Being visible on GitHub matters when you want to collaborate with others, get hired, or establish yourself as a contributor.

      +

      Your contribution graph

      +

      The green grid on your profile shows your public contribution activity over the past year. Contributions count when you:

      +
        +
      • Push commits to a public repo
        • +
      • Open, comment on, or close issues or PRs in a public repo
        • +
      • Review a PR in a public repo
        • +
      +
      +

      Note: Contributions to private repos only appear as grey squares unless the repo is made public later. Commits only count if they're made with the email address associated with your GitHub account.

      +
      +

      Pinning repositories

      +

      Pin up to 6 repositories (your own or repos you've contributed to) on your profile:

      +
        +
      1. Go to your profile (github.com/username)
        2. +
      2. Select "Customize your pins" above the pinned repos section
        3. +
      3. Check up to 6 repos to pin — prioritise your best work and most active contributions
        4. +
      +

      Your profile README

      +

      Create a special repository named exactly the same as your username (github.com/username/username) and its README.md will appear at the top of your profile page. This is your chance to introduce yourself, list your skills, and share what you're working on.

      +

      See Appendix R: Profile, Sponsors, and Wikis for a full guide on building a great profile README.

      +

      Activity tips

      +
        +
      • Comment thoughtfully on issues — even "I can reproduce this on Windows 11 with NVDA" is a valued contribution that shows on your profile
        • +
      • Star generously — it signals your interests and others see it in their feeds
        • +
      • Follow people in your area — they often follow back, growing your network organically
        • +
      +
      +

      11. The GitHub CLI for Social Features

      +
      # --- Following ---
+gh api user/following/username --method PUT        # Follow someone
+gh api user/following/username --method DELETE     # Unfollow
+gh api user/following --jq '.[].login'             # List who you follow
+gh api user/followers --jq '.[].login'             # List your followers
+
+# --- Stars ---
+gh api user/starred/owner/repo --method PUT        # Star a repo
+gh api user/starred/owner/repo --method DELETE     # Unstar a repo
+gh api user/starred --jq '.[].full_name'           # List your stars
+
+# --- Discovery ---
+gh search repos --topic accessibility --limit 20   # Browse by topic
+gh search repos --sort stars --order desc --limit 20   # Popular repos
+gh search users "accessibility developer" --limit 10   # Find people
+
+# --- Watching ---
+gh api repos/owner/repo/subscription \
+  --method PUT --field subscribed=true             # Watch a repo
+gh api user/subscriptions --jq '.[].full_name'     # List watched repos
      +
      +

      12. Screen Reader Navigation Guide

      +

      Following a user

      +
        +
      1. Navigate to github.com/username
        2. +
      2. Press H to jump through headings to find the user's name at the top
        3. +
      3. Tab forward — the Follow/Following button is within the first few interactive elements after the avatar/bio area
        4. +
      4. Press Enter or Space to follow; the button label updates to "Following [username]"
        5. +
      +

      Starring a repository

      +
        +
      1. Navigate to any repository page
        2. +
      2. The Star button is in the repository header, near the Fork button
        3. +
      3. Press B (NVDA/JAWS) to navigate by button, or Tab through the header
        4. +
      4. The button is announced as "Star this repository" or "Unstar this repository"
        5. +
      5. After starring, the button label changes and a count updates
        6. +
      +

      Browsing your stars

      +
        +
      1. Go to github.com/username?tab=stars
        2. +
      2. Jump to main landmark to skip navigation
        3. +
      3. Each starred repo is a heading (H3) with a link — navigate with H or 3
        4. +
      4. Below each heading: description text, language, star count, and list controls
        5. +
      +

      Exploring topics

      +
        +
      1. Go to github.com/topics/accessibility (or any topic)
        2. +
      2. Jump to main landmark
        3. +
      3. Repos are listed as article regions with H3 headings
        4. +
      4. Each entry has: repo name (link), owner, description, language, star count, and a Star button
        5. +
      + +
        +
      1. Go to github.com/explore or github.com/trending
        2. +
      2. Use H to navigate between sections and repo entries
        3. +
      3. Trending page has language and time period filter dropdowns near the top — Tab to find them
        4. +
      4. Each trending repo row has: rank position, repo name (link), description, star count, and "Stars today" count
        5. +
      +
      +

      Next: Appendix U: Discussions and Gists
      Back: Appendix S: Releases and Insights
      Teaching chapter: Chapter 08: Open Source Culture

      + +
      + + + + diff --git a/html/admin/qa-bundle/docs/appendix-u-discussions-and-gists.html b/html/admin/qa-bundle/docs/appendix-u-discussions-and-gists.html new file mode 100644 index 00000000..22522fd2 --- /dev/null +++ b/html/admin/qa-bundle/docs/appendix-u-discussions-and-gists.html @@ -0,0 +1,652 @@ + + + + + + + Appendix U: Discussions and Gists - GIT Going with GitHub + + + + + + + + +
      +

      Appendix U: Discussions and Gists

      +
      +

      Reference companion to: Chapter 08: Open Source Culture | Also relevant: Chapter 10

      +

      Authoritative source: GitHub Docs: About discussions

      +
      +
      +

      This appendix consolidates two related community content features: GitHub Discussions (formerly Appendix G) and GitHub Gists (formerly Appendix F).

      +
      +
      +

      GitHub Discussions

      +
      +

      Listen to Episode 24: GitHub Discussions - a conversational audio overview of this chapter. Listen before reading to preview the concepts, or after to reinforce what you learned.

      +
      +

      Forum-Style Conversations Beyond Issues and Pull Requests

      +
      +

      GitHub Discussions is a built-in community forum for repositories and organizations. It's where open-ended conversations live - questions, ideas, announcements, polls, and community Q&A - separate from the action-oriented world of issues and pull requests.

      +
      + +

      For ongoing support after the workshop, use:

      + +

      Suggested first steps for students:

      +
        +
      1. Read the pinned Start Here resources in Discussions.
        2. +
      2. Search existing discussions before opening a new support thread.
        3. +
      3. Use issue templates for setup blockers or accessibility blockers so maintainers can help faster.
        4. +
      +

      Learning Cards: GitHub Discussions

      +
      +Screen reader users + +
        +
      • The Discussions tab is in the repository's main navigation bar alongside Code, Issues, and Pull Requests -- press T to navigate tab items or K to find the "Discussions" link
        • +
      • Inside a discussion, replies are article elements -- in NVDA press A to jump between replies; in JAWS use A as well
        • +
      • The reply editor uses the same behavior as issue comments -- enter Focus Mode to type, then press Ctrl+Enter to submit
        • +
      +
      + +
      +Low vision users + +
        +
      • Discussion categories appear as a sidebar panel on the left or right depending on viewport width -- look for the category list with item counts
        • +
      • Answered discussions in the Q&A category display a green "Answered" badge next to the title, with the accepted answer pinned to the top
        • +
      • Polls show percentage bars next to each option after you vote -- the bars use color fill to indicate proportion
        • +
      +
      + +
      +Sighted users + +
        +
      • Discussions are organized by category with colored labels -- the sidebar shows all categories and pinned items
        • +
      • In Q&A threads, look for the green checkmark on the accepted answer pinned above the regular reply timeline
        • +
      • Use the upvote button (thumbs up) on replies instead of posting "+1" comments -- maintainers often sort by upvotes
        • +
      +
      + + +

      Table of Contents

      +
        +
      1. Discussions vs. Issues: When to Use Which
        2. +
      2. Navigating to Discussions
        3. +
      3. Discussion Categories
        4. +
      4. Creating a Discussion
        5. +
      5. Participating in Discussions
        6. +
      6. Marking an Answer
        7. +
      7. Polls
        8. +
      8. Screen Reader Navigation Reference
        9. +
      9. Organization-Level Discussions
        10. +
      10. Accessibility Agents: What's Different Here
        11. +
      +

      1. Discussions vs. Issues: When to Use Which

      +

      Not every conversation belongs in an issue. GitHub Discussions exists for the conversations that don't fit:

      + + + + + + + + + + + + + + + + + + + + + + + + + + + +
      Use Issues WhenUse Discussions When
      You found a bugYou have a question about how something works
      You want to request a specific featureYou want to brainstorm ideas before filing a feature request
      There is actionable work to be doneYou want community input before deciding what work to do
      You need to track progress (labels, assign, close)You want to have an open conversation without resolving it
      The answer is "fixed" or "won't fix"The conversation might not have one right answer
      +

      The signal for maintainers: A question in an issue is noisier - it implies something needs to be done. The same question in Discussions doesn't trigger workflow automation and doesn't inflate the issue count.

      +

      Common Discussions categories you'll encounter

      +
        +
      • Q&A - Support questions and answers (one answer can be marked correct)
        • +
      • Ideas - Feature brainstorming before a formal feature request
        • +
      • Announcements - Maintainer posts about releases, breaking changes, roadmaps
        • +
      • General - Everything else
        • +
      • Show and Tell - Community members showing what they built
        • +
      +

      2. Navigating to Discussions

      +

      From a Repository

      +
        +
      1. Navigate to the repository
        2. +
      2. There is a Discussions tab in the main navigation (alongside Code, Issues, Pull Requests, Actions, Projects)
        3. +
      3. Press T to navigate tab items, or K to navigate links and find "Discussions"
        4. +
      4. Press Enter to open
        5. +
      +

      If the tab is missing: Discussions is an opt-in feature. The repository maintainer must enable it in Settings. Not all repositories use it.

      +

      From an Organization

      +

      Large organizations can have organization-level Discussions separate from any individual repository:

      +
        +
      1. Navigate to the organization page
        2. +
      2. Look for the Discussions tab at the organization level
        3. +
      3. These are community-wide conversations, not repo-specific
        4. +
      +

      3. Discussion Categories

      +

      The Discussions home page is organized by category. Each category is a section with its own heading.

      + +
      3 → Jump to category headings
+K → Navigate discussion titles within a category
+Enter → Open a discussion
      +

      The side panel (left or right depending on view width) shows

      +
        +
      • All categories with item counts
        • +
      • Pin/announcements section at top
        • +
      • Most active discussions
        • +
      • Tags (if the repo uses them)
        • +
      +

      4. Creating a Discussion

      +
        +
      1. From the Discussions tab, activate "New discussion" button
        2. +
      2. Select a category (required - affects which fields appear)
        3. +
      3. Fill in:
          +
        • Title - Clear and searchable. "How do I use the daily-briefing agent?" not "Help"
          • +
        • Body - Use Markdown. Same editor as issues
          • +
        • For Q&A category: phrase the title as a question
          • +
        +
        4. +
      4. Activate "Start discussion"
        5. +
      +

      Screen reader path

      +
      Tab to "New discussion" button → Enter
+→ Category list: ↑/↓ to select category → Enter
+→ Title field: type title
+→ Tab to body: Focus Mode → type or paste content
+→ Tab to "Start discussion" button → Enter
      +

      Before posting a question: Search existing discussions first. Use the search bar at the top of the Discussions page or GitHub's global search with repo:owner/name in:discussions.

      +

      Learning Cards: Creating a Discussion

      +

      Screen reader users:

      +
        +
      • Tab to the "New discussion" button from the Discussions tab, then press Enter -- the form loads with a category selector first; arrow through categories and press Enter to select
        • +
      • The title field comes after the category selector -- type a clear, searchable title; for Q&A category, phrase it as a question so it reads naturally in search results
        • +
      • The body editor is the same as the issue comment editor -- enter Focus Mode to type, use Markdown formatting, and press Ctrl+Enter to submit the discussion
        • +
      +

      Low-vision users:

      +
        +
      • The category selector appears as a list or grid of labeled options -- each category has a name and description; zoom in to read the descriptions and pick the right one
        • +
      • The title and body fields stack vertically in a single-column layout -- the form is the same width as the main content area, making it easy to scan at high zoom
        • +
      • After creating a discussion, a green success banner appears at the top -- scroll up if you do not see confirmation at your current zoom position
        • +
      +

      Sighted users:

      +
        +
      • Categories appear as clickable cards or a list when creating a new discussion -- choose Q&A for questions (allows marking an answer), Ideas for brainstorming, General for everything else
        • +
      • The "New discussion" button is prominently placed at the top-right of the Discussions tab -- the form layout is nearly identical to the new issue form
        • +
      • Search existing discussions before posting -- use the search bar at the top of the Discussions page to avoid duplicate questions
        • +
      +

      5. Participating in Discussions

      +

      Reading a Discussion

      +

      A discussion page is structured similarly to an issue:

      +
        +
      • The original post at the top
        • +
      • Replies in chronological order
        • +
      • An "Answered" reply pinned to the top (Q&A category only)
        • +
      • A reply editor at the bottom
        • +
      + +
      H → Jump between the original post heading and reply headings
+3 → Navigate individual reply headings
+↓ → Read through content
      +

      Replying to a Discussion

      +
        +
      1. Navigate to the bottom of the page (or use the "Reply" button on a specific comment)
        2. +
      2. The reply text area behaves identically to issue comments
        3. +
      3. Focus Mode → type your reply
        4. +
      4. Ctrl+Enter to submit
        5. +
      +

      Replying to a Specific Comment (Nested Reply)

      +

      Each comment has a Reply button below it:

      +
      Tab to "Reply" button on the specific comment → Enter
+→ Nested text area opens under that comment
+→ Focus Mode → type → Ctrl+Enter
      +

      Upvoting

      +

      Instead of leaving "+1" comments, use the thumbs-up reaction on the original post or replies. Many maintainers sort discussion responses by upvotes to prioritize most-needed answers.

      +

      6. Marking an Answer

      +

      In the Q&A category, one reply can be marked as the accepted answer. This is similar to Stack Overflow's "accepted answer" mechanic.

      +

      Only the discussion author and repository maintainers can mark an answer.

      +

      To mark an answer (as the discussion author)

      +
        +
      1. Navigate to the reply you want to mark as the answer
        2. +
      2. Look for the "Mark as answer" button below the reply
        3. +
      3. Activate it - the reply is pinned to the top and the discussion shows a green "Answered" badge
        4. +
      +

      Why it matters: Marked answers make Q&A discussions into searchable documentation. Anyone who searches for the same question later immediately sees the correct answer without reading the whole thread.

      +

      To unmark an answer: Activate "Unmark as answer" on the same reply.

      +

      7. Polls

      +

      Some discussion categories support embedded polls. A poll lets you gather structured vote data from the community.

      +

      Creating a poll

      +
        +
      1. When creating a discussion, look for the "Add a poll" option below the body editor
        2. +
      2. Type each poll option (up to 8 options)
        3. +
      3. Set poll duration (optional)
        4. +
      4. Submit the discussion - the poll appears inline
        5. +
      +

      Voting in a poll

      +
      Navigate to the poll section
+→ Radio buttons or checkboxes for each option
+→ Space/Enter to vote
+→ "Vote" button → Enter
      +

      Poll results: After voting, percentages appear next to each option. Screen readers announce the count and percentage per option.

      +

      8. Screen Reader Navigation Reference

      +

      Discussions List

      +
      T                     → Navigate tab bar to reach "Discussions" tab
+H / 2                 → Category section headings
+3                     → Individual discussion titles (h3 links)
+K                     → Navigate all links (discussions, categories, pagination)
+Enter                 → Open a discussion
+/                     → Focus the search bar (if supported)
      +

      Inside a Discussion

      +
      H                     → Original post heading and top-level reply headings
+3                     → Individual replies
+↓                     → Read body content
+Tab                   → Move to interactive elements (reply buttons, reactions, mark as answer)
+Ctrl+Enter            → Submit a reply (when in text area)
      +

      NVDA note

      +
        +
      • Browse mode (NVDA+Space) to read the discussion
        • +
      • Enter application mode for the reply editor
        • +
      • Discussion replies are <article> elements - NVDA announces "article" as you navigate with H
        • +
      +

      JAWS note

      +
        +
      • A key navigates <article> elements - useful for jumping between replies
        • +
      • Use Forms Mode for the reply editor
        • +
      +

      VoiceOver note

      +
        +
      • VO+Right to read through content
        • +
      • VO+Command+L to list all links (useful for navigating many replies quickly)
        • +
      • VO+Space on the reply field to enter interaction mode
        • +
      +

      9. Organization-Level Discussions

      +

      Some organizations enable Discussions at the organization level, separate from any repository. These work identically to repository discussions but span the whole organization.

      +

      Common uses:

      +
        +
      • Org-wide announcements
        • +
      • Community introductions ("Introduce yourself" pinned thread)
        • +
      • Cross-repo feature brainstorming
        • +
      • Community spotlights and events
        • +
      +

      Find them at github.com/ORGANIZATION/discussions.

      +

      10. Accessibility Agents: What's Different Here

      +

      Accessibility Agents prompts currently operate on issues, PRs, and code - not directly on Discussions. If you want to respond to a discussion using Accessibility Agents:

      +
        +
      1. Copy the discussion URL or content
        2. +
      2. Use /issue-reply with the content pasted in: the agent will draft a thoughtful, accessible response
        3. +
      3. Paste the result back into the discussion reply editor
        4. +
      +

      This works well for first-response drafts on Q&A threads or community questions in your area of expertise.

      +

      Return to: Resources | Glossary

      +
      +

      GitHub Gists

      +
      +

      Listen to Episode 23: GitHub Gists - a conversational audio overview of this chapter. Listen before reading to preview the concepts, or after to reinforce what you learned.

      +
      +

      Shareable Code Snippets and Notes

      +
      +

      Gists are a simple way to share code snippets, notes, or small files without creating a full repository. Think of them as lightweight, version-controlled pastebins.

      +
      +

      Learning Cards: GitHub Gists

      +
      +Screen reader users + +
        +
      • On the Gist creation page at gist.github.com, press D to jump to the main landmark, then F to navigate form fields: Description, Filename, Content, and Visibility buttons
        • +
      • Your Gists page lists each gist as an H2 heading with its description -- press 2 or H to jump between gists
        • +
      • Gists are full Git repositories -- you can clone them with git clone and edit locally using your usual screen reader workflow in VS Code
        • +
      +
      + +
      +Low vision users + +
        +
      • Gist pages use syntax highlighting matching GitHub's current theme -- switch between light and dark mode for comfortable reading
        • +
      • Public and secret gists look identical on the page; the only difference is the URL visibility -- check the "Create secret gist" or "Create public gist" button label before submitting
        • +
      • The revision history link appears at the top of any gist -- click "Revisions" to see a diff view of every edit
        • +
      +
      + +
      +Sighted users + +
        +
      • Gists live at gist.github.com, separate from regular repositories -- each gist shows a syntax-highlighted code block with filename tabs at the top
        • +
      • The visibility selector is a split button at the bottom of the editor -- the dropdown arrow reveals "Create secret gist" vs "Create public gist"
        • +
      • You can add multiple files to one gist using the "Add file" button below the first editor pane
        • +
      +
      + + +

      What Is a Gist?

      +

      A Gist is a Git repository that holds a single file or a small collection of files. Every Gist:

      +
        +
      • Has its own URL (e.g., gist.github.com/username/a1b2c3d4)
        • +
      • Is version-controlled (you can see edit history)
        • +
      • Can be public (anyone can see) or secret (only people with the link can see)
        • +
      • Supports Markdown rendering
        • +
      • Can be embedded in web pages
        • +
      • Can be cloned, forked, and starred just like repos
        • +
      +

      Secret does not mean private. Anyone with the URL can view a secret Gist. It's just not listed publicly on your profile.

      +

      When to Use a Gist vs a Repository

      + + + + + + + + + + + + + + + + + + + + + + + + + + + +
      Use a Gist When...Use a Repository When...
      Sharing a single code snippetBuilding a full project
      Posting configuration examplesCollaborating with multiple people
      Quick notes or documentationNeed issues, PRs, or project management
      Sharing logs or error messagesWant CI/CD and automated checks
      Small utility scriptsNeed multiple branches
      +

      Creating a Gist

      +

      Via GitHub Web Interface

      +
        +
      1. Navigate to gist.github.com
        2. +
      2. Gist description: A short title (e.g., "NVDA configuration for GitHub")
        3. +
      3. Filename: Name your file with extension (e.g., nvda-config.txt, script.py, notes.md)
        4. +
      4. Content: Paste or type your code/text
        5. +
      5. Visibility:
          +
        • Select "Create public gist" for openly shareable content
          • +
        • Select "Create secret gist" for link-only sharing
          • +
        +
        6. +
      6. The Gist is created with a unique URL you can share
        7. +
      +

      Screen reader navigation

      +
        +
      • D to cycle landmarks to "Main"
        • +
      • F to navigate form fields
        • +
      • Tab through: Description → Filename → Content textbox → Visibility buttons
        • +
      +

      Adding Multiple Files to a Gist

      +

      You can add multiple files to a single Gist:

      +
        +
      1. After typing the first filename and content, select "Add file" (button below the editor)
        2. +
      2. Repeat for each additional file
        3. +
      3. Create the Gist
        4. +
      +

      Use case: Share related config files together (e.g., .vscode/settings.json + .vscode/keybindings.json)

      +

      Learning Cards: Creating a Gist

      +

      Screen reader users:

      +
        +
      • On the Gist creation page at gist.github.com, press D to jump to the main landmark, then F to navigate form fields in order: Description, Filename, Content textarea, and visibility buttons
        • +
      • The visibility selector is a split button -- the main button creates a public gist; Tab to the dropdown arrow next to it and press Enter to reveal the "Create secret gist" option
        • +
      • Each filename field has a corresponding content textarea directly below it -- after filling one file, Tab to the "Add file" button to add another file to the same gist
        • +
      +

      Low-vision users:

      +
        +
      • The Gist editor uses the same syntax highlighting as regular GitHub files -- your current theme applies; increase font size in browser zoom for comfortable editing
        • +
      • The split button for public vs. secret visibility is at the bottom of the form -- the two options look nearly identical; read the button label carefully ("Create public gist" vs. "Create secret gist") before clicking
        • +
      • The "Add file" button appears below the first file editor as a small text link -- zoom in to find it; each additional file gets its own filename field and content textarea
        • +
      +

      Sighted users:

      +
        +
      • The Gist creation form has three main fields stacked vertically: description at the top, then filename, then a large code editor -- fill all three before choosing visibility
        • +
      • The visibility split button at the bottom-right has a dropdown arrow -- click the arrow to choose between public and secret; the default (larger) button creates a public gist
        • +
      • Add multiple files to a single gist using the "Add file" link below the editor -- multi-file gists are useful for sharing related configurations or code snippets together
        • +
      +

      Editing a Gist

      +
        +
      1. Navigate to your Gist's URL
        2. +
      2. Select "Edit" (button in the top-right)
        3. +
      3. Make your changes
        4. +
      4. Select "Update public gist" or "Update secret gist"
        5. +
      +

      Every edit creates a new revision. Click "Revisions" to see the full edit history.

      +

      Embedding a Gist

      +

      You can embed Gists in web pages, blog posts, or documentation:

      +
      <script src="https://gist.github.com/username/gist-id.js"></script>
      +

      GitHub renders it as a formatted code block with syntax highlighting and a link back to the Gist.

      +

      Accessibility note: Embedded Gists are <iframe> elements. Screen readers will announce them as "frame" and allow navigation into the content.

      +

      Cloning a Gist

      +

      Every Gist is a Git repository. You can clone it:

      +
      git clone https://gist.github.com/username/gist-id.git
      +

      Make changes locally, commit, and push just like a normal repo.

      +

      Forking a Gist

      +

      You can fork someone else's Gist to create your own copy:

      +
        +
      1. View the Gist
        2. +
      2. Select "Fork" in the top-right
        3. +
      3. GitHub creates a new Gist under your account
        4. +
      +

      Use case: Someone shares a useful script, you fork it, and customize it for your needs.

      +

      Finding Your Gists

      +

      Your Gists page: gist.github.com/your-username

      +

      All your public and secret Gists are listed here. You can:

      +
        +
      • Search your Gists by filename or content
        • +
      • Star Gists you want to reference later
        • +
      • Delete old Gists
        • +
      +

      Screen reader navigation

      +
        +
      • Each Gist appears as a heading (H2) with its description
        • +
      • Press 2 or H to jump between Gists
        • +
      • Each Gist has links: "Edit," "Delete," "Star," "Embed"
        • +
      +

      Discovering Public Gists

      +

      Browse trending Gists: gist.github.com/discover

      +

      See popular Gists by language. Great for finding:

      +
        +
      • Useful scripts and utilities
        • +
      • Configuration examples
        • +
      • Code snippets for learning
        • +
      +

      Gist Comments

      +

      Public Gists support comments. Anyone with a GitHub account can leave a comment, making Gists useful for:

      +
        +
      • Asking questions about a snippet
        • +
      • Suggesting improvements
        • +
      • Discussing implementation details
        • +
      +

      To add a comment

      +
        +
      1. Scroll to the bottom of the Gist page
        2. +
      2. F to navigate form fields → Find the comment textarea
        3. +
      3. Type your comment (Markdown supported)
        4. +
      4. Ctrl+Enter or activate "Comment" button
        5. +
      +

      Security and Privacy

      +

      Public Gists

      +
        +
      • Appear on your profile
        • +
      • Are indexed by search engines
        • +
      • Anyone can view, fork, and comment
        • +
      +

      Secret Gists

      +
        +
      • Do not appear on your profile
        • +
      • Are not indexed by search engines
        • +
      • Anyone with the URL can view
        • +
      • Still version-controlled and can be starred
        • +
      +

      Never put sensitive data in Gists

      +
        +
      • Passwords or API keys
        • +
      • Personal identifying information
        • +
      • Proprietary code you don't have permission to share
        • +
      +

      If you accidentally post sensitive data:

      +
        +
      1. Delete the Gist immediately
        2. +
      2. Revoke/regenerate any exposed credentials
        3. +
      3. Remember: Forks and clones may still exist
        4. +
      +

      Example Use Cases

      +

      1. Sharing Screen Reader Config

      +
      Filename: nvda-github-config.txt
+Content:
+# NVDA Settings for GitHub Web Navigation
+- Browse Mode: Use screen layout (enabled)
+- Verbosity: Most punctuation
+- Rate: 65%
+- Keyboard shortcuts: Use standard GitHub shortcuts (G+I, G+P, etc.)
      +

      Share the Gist URL with other screen reader users.

      +

      2. Quick Markdown Note

      +
      Filename: workshop-notes.md
+Content:
+# Workshop Day 1 Notes
+- GitHub Flow: branch → commit → PR → review → merge
+- Keyboard shortcuts: G+I (issues), G+P (PRs), / (search)
+- Always link PRs to issues with "Closes #N"
      +

      Reference it later or share with workshop participants.

      +

      3. Code Snippet for a StackOverflow Answer

      +

      When answering questions, paste your code as a Gist and link to it. Readers get syntax highlighting, version history, and the ability to fork your solution.

      +

      Gists vs GitHub Repositories - Quick Comparison

      + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + +
      FeatureGistRepository
      IssuesNoYes
      Pull RequestsNoYes
      GitHub ActionsNoYes
      ProjectsNoYes
      Multiple branchesNoYes
      Revisions/historyYesYes
      ForkableYesYes
      EmbeddableYesNo
      CommentsYesYes (on issues/PRs)
      +

      Deleting a Gist

      +
        +
      1. Navigate to the Gist
        2. +
      2. Select "Edit"
        3. +
      3. Select "Delete" (top-right, after Edit button)
        4. +
      4. Confirm deletion
        5. +
      +
      +

      Next: Appendix V: GitHub Mobile
      Back: Appendix T: Community and Social
      Teaching chapter: Chapter 08: Open Source Culture

      + +
      + + + + diff --git a/html/admin/qa-bundle/docs/appendix-v-github-mobile.html b/html/admin/qa-bundle/docs/appendix-v-github-mobile.html new file mode 100644 index 00000000..c9709f3f --- /dev/null +++ b/html/admin/qa-bundle/docs/appendix-v-github-mobile.html @@ -0,0 +1,440 @@ + + + + + + + Appendix V: GitHub Mobile - GIT Going with GitHub + + + + + + + + +
      +

      Appendix V: GitHub Mobile

      +
      +

      Listen to Episode 32: GitHub Mobile - a conversational audio overview of this chapter. Listen before reading to preview the concepts, or after to reinforce what you learned.

      +
      +
      +

      Reference companion to: Chapter 05: Working with Issues | Also relevant: Chapter 10

      +

      Authoritative source: GitHub Docs: GitHub Mobile

      +
      +

      Accessibility Guide for iOS and Android

      +
      +

      GitHub Mobile brings issues, pull requests, notifications, and code review to your iPhone, iPad, or Android device. This appendix covers setup, VoiceOver and TalkBack usage, and the tasks best suited to mobile.

      +
      +

      Learning Cards: GitHub Mobile Overview

      +
      +Screen reader users + +
        +
      • GitHub Mobile supports VoiceOver (iOS) and TalkBack (Android) natively -- swipe right to move through elements, double-tap to activate
        • +
      • The app uses five bottom tabs (Home, Notifications, Explore, Pull Requests, Profile) -- swipe left or right along the bottom tab bar to switch between them
        • +
      • Use the VoiceOver Rotor (two-finger twist) set to Headings to jump between sections within an issue or PR description
        • +
      +
      + +
      +Low vision users + +
        +
      • GitHub Mobile supports dynamic text sizing on both iOS and Android -- increase your system font size and the app respects it
        • +
      • Dark mode is available in the app settings and follows your system preference -- use it to reduce glare on OLED screens
        • +
      • The simplified diff view in Files Changed shows additions and removals as text only, without the two-column table layout used on desktop
        • +
      +
      + +
      +Sighted users + +
        +
      • The five-tab navigation bar at the bottom of the screen (Home, Notifications, Explore, Pull Requests, Profile) is your primary way around the app
        • +
      • Notification badges appear as red dots on the Notifications tab -- swipe left on individual notifications for quick actions (read, archive, unsubscribe)
        • +
      • Pull request diffs use a simplified single-column view optimized for small screens -- additions appear in green, removals in red
        • +
      +
      + + +

      Table of Contents

      +
        +
      1. Installing GitHub Mobile
        2. +
      2. Getting Around the App
        3. +
      3. VoiceOver on iOS
        4. +
      4. TalkBack on Android
        5. +
      5. Working with Notifications
        6. +
      6. Reviewing Pull Requests
        7. +
      7. Working with Issues
        8. +
      8. What Mobile Does Well vs. Desktop
        9. +
      9. Common Issues and Workarounds
        10. +
      +

      1. Installing GitHub Mobile

      + + + + + + + + + + + + + + + +
      PlatformDownload
      iOS (iPhone / iPad)App Store - GitHub
      AndroidGoogle Play - GitHub
      +

      After installing, sign in with your GitHub account. Enable notifications when prompted - these are essential for staying on top of PR reviews and issue activity without constantly checking the web.

      +

      2. Getting Around the App

      +

      GitHub Mobile is organized into five main tabs at the bottom of the screen:

      + + + + + + + + + + + + + + + + + + + + + + + + + + + +
      TabContents
      HomePersonalized feed of activity across your repositories
      NotificationsAll @mentions, review requests, issue updates
      ExploreDiscover repositories and trending projects
      Pull RequestsPRs assigned to you, created by you, or awaiting your review
      ProfileYour profile, repositories, stars, and settings
      +

      Navigate between tabs with a single tap (or swipe on iOS with VoiceOver active).

      +

      3. VoiceOver on iOS

      +

      Enabling VoiceOver

      +
        +
      • Triple-click the side button (iPhone X and later) or triple-click the Home button to toggle VoiceOver
        • +
      • Or: Settings → Accessibility → VoiceOver → toggle on
        • +
      +

      Basic Gestures in GitHub Mobile

      + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + +
      GestureAction
      Swipe rightMove to the next element
      Swipe leftMove to the previous element
      Double tapActivate the focused element
      Two-finger swipe upRead from the top
      Two-finger tapPause/resume speech
      Three-finger swipe left/rightMove between screens
      Scrub (two-finger Z motion)Go back
      +

      Rotor in GitHub Mobile

      +

      Open the Rotor by rotating two fingers on the screen as if turning a dial. Useful rotor settings for GitHub Mobile:

      +
        +
      • Headings - jump between section headings on an issue or PR description
        • +
      • Links - navigate to linked issues, commits, or external URLs
        • +
      • Form Controls - jump to input fields when writing a comment
        • +
      • Actions - available actions for the focused element (assign, label, close)
        • +
      +

      Writing Comments with VoiceOver

      +
        +
      1. Navigate to the comment field (swipe to it or use Rotor → Form Controls)
        2. +
      2. Double tap to activate and open the keyboard
        3. +
      3. Type your comment; VoiceOver announces each character
        4. +
      4. When done, swipe to the Comment button and double tap to submit
        5. +
      +

      4. TalkBack on Android

      +

      Enabling TalkBack

      +
        +
      • Settings → Accessibility → TalkBack → toggle on
        • +
      • Or: hold both volume keys for three seconds (if the shortcut is enabled)
        • +
      +

      Basic Gestures in GitHub Mobile

      + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + +
      GestureAction
      Swipe rightMove to next element
      Swipe leftMove to previous element
      Double tapActivate the focused element
      Swipe up then downScroll down
      Swipe down then upScroll up
      Swipe right then leftGo back
      Two-finger swipe downRead from top
      +

      TalkBack Menu

      +

      Tap with three fingers (or swipe down then right) to open the TalkBack menu. From here you can:

      +
        +
      • Change the reading granularity (character, word, line, paragraph)
        • +
      • Activate reading controls
        • +
      • Copy text
        • +
      +

      Writing Comments with TalkBack

      +
        +
      1. Locate the comment field - TalkBack announces "Edit text, double tap to edit"
        2. +
      2. Double tap to enter the field
        3. +
      3. Use the on-screen keyboard or dictation to type
        4. +
      4. Locate the Comment button and double tap to submit
        5. +
      +

      5. Working with Notifications

      +

      GitHub Mobile's Notifications tab is one of its strongest features for AT users - it surfaces all activity in a clean, linear list that is much easier to navigate than the GitHub web notifications page.

      +

      Learning Cards: Mobile Notifications

      +
      +Screen reader users + +
        +
      • The Notifications tab presents a linear list that is more accessible than the web version -- swipe right through items one by one to hear each notification's context
        • +
      • Filter controls are accessible form elements at the top -- navigate to the filter icon, activate it, then swipe through filter options (Type, Repository, Reason)
        • +
      • Swipe actions (left to archive, right to mark done) work with VoiceOver custom actions -- use the VoiceOver Actions rotor item on each notification
        • +
      +
      + +
      +Low vision users + +
        +
      • Notifications are displayed as a vertical list with the repository name, notification type, and title on each row -- text is sized according to your system accessibility settings
        • +
      • The filter panel overlays on top of the list -- look for the funnel icon in the top-right corner of the Notifications tab
        • +
      • Unread notifications appear with a blue dot indicator on the left edge of each row
        • +
      +
      + +
      +Sighted users + +
        +
      • The Notifications tab shows all activity in a chronological list -- unread items have a blue dot on the left
        • +
      • Swipe left on any notification to reveal quick-action buttons: Mark as Read, Archive, and Unsubscribe
        • +
      • Use the filter icon (top right) to narrow by notification type, repository, or reason (mentioned, review requested, assigned)
        • +
      +
      + +

      Inbox Management

      +
        +
      • Swipe left on a notification to reveal quick actions: Mark as read, Archive, Unsubscribe
        • +
      • Swipe right to mark as done
        • +
      • Tap a notification to open the full issue or PR
        • +
      +

      Filtering Notifications

      +

      Use the filter icon at the top right to filter by:

      +
        +
      • Type (Issues, PRs, Releases, etc.)
        • +
      • Repository
        • +
      • Reason (you were @mentioned, a review was requested, etc.)
        • +
      +

      With VoiceOver or TalkBack, the filter controls are accessible form elements. Open the filter panel, navigate to each option, and activate to toggle it.

      +

      6. Reviewing Pull Requests

      +

      Mobile is well suited for quick PR reviews - approving straightforward changes, leaving a comment, or checking CI status while away from your desk.

      + +

      When you open a pull request, the screen is divided into sections:

      +
        +
      • Description - the PR body with any images or checklists
        • +
      • Commits - individual commits in this PR
        • +
      • Files changed - a simplified diff view
        • +
      • Checks - CI/CD status
        • +
      +

      VoiceOver and TalkBack announce these as headings. Use heading navigation (Rotor on iOS, swipe granularity on Android) to jump between sections.

      +

      Leaving a Review

      +
        +
      1. Scroll to or navigate to the Review changes button
        2. +
      2. Double tap to open the review panel
        3. +
      3. Choose Approve, Request changes, or Comment
        4. +
      4. Add an optional comment in the text field
        5. +
      5. Activate Submit review
        6. +
      +

      Viewing Diffs

      +

      The Files Changed tab shows a simplified diff - additions and removals are text-only (no table layout). Each changed line is announced as "Added: [content]" or "Removed: [content]", which is generally more accessible than the web diff table on small screens.

      +

      7. Working with Issues

      +

      Filing an Issue

      +
        +
      1. Navigate to the repository
        2. +
      2. Tap Issues → the + button or New Issue
        3. +
      3. Fill in the title and body
        4. +
      4. Optionally assign labels, assignees, and milestone - each is a tappable field
        5. +
      5. Tap Submit
        6. +
      +

      Finding Your Issues

      +
        +
      • Pull Requests tab → Created by you or Assigned to you filters
        • +
      • For issues: Home feed shows recent activity; or navigate to a specific repository → Issues → filter by Assignee, Label, or Author
        • +
      +

      8. What Mobile Does Well vs. Desktop

      + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + +
      TaskMobileDesktop
      Triage notificationsExcellent - linear list, swipe actionsGood
      Quick review / approve a PRGoodGood
      Writing long PR descriptionsFair - small keyboardBetter
      Reviewing large diffsFair - simplified viewBetter
      Filing a simple issueGoodGood
      Complex issue templatesFairBetter
      Managing labels and milestonesGoodGood
      Reading codeFair - no syntax highlightingBetter
      Running Codespace / editing codeNot supportedSupported
      +

      Best use of GitHub Mobile: notification triage, quick approvals and comments, catching up on activity between sessions. For writing substantial code, descriptions, or reviewing complex diffs, use the web or VS Code.

      +

      9. Common Issues and Workarounds

      +

      VoiceOver skips some PR descriptions

      +

      Long PR descriptions with images, tables, or embedded videos may not read cleanly. Open the PR in Safari instead - tap the … menu → Open in Browser.

      +

      TalkBack does not announce new notifications badge

      +

      The badge count on the Notifications tab updates live but may not be announced. Navigate directly to the Notifications tab to get the current count read aloud.

      +

      The keyboard covers the comment field

      +

      Usual iOS/Android behavior - scroll up slightly after the keyboard appears, or rotate to landscape mode to gain more visible space.

      +

      Can't find the Submit button after writing a review

      +

      Scroll down past the text field; buttons are below the keyboard dismiss area. On iOS, tap elsewhere to dismiss the keyboard first, then scroll to Submit.

      +

      GitHub Mobile crashes or freezes

      +

      Force close the app and reopen. If the problem persists, sign out and back in via Profile → Settings → Sign out.

      +
      +

      Next: Appendix W: GitHub Pages
      Back: Appendix U: Discussions and Gists
      Teaching chapter: Chapter 05: Working with Issues

      + +
      + + + + diff --git a/html/admin/qa-bundle/docs/appendix-w-github-pages.html b/html/admin/qa-bundle/docs/appendix-w-github-pages.html new file mode 100644 index 00000000..3c257845 --- /dev/null +++ b/html/admin/qa-bundle/docs/appendix-w-github-pages.html @@ -0,0 +1,450 @@ + + + + + + + Appendix W: Publishing with GitHub Pages - GIT Going with GitHub + + + + + + + + +
      +

      Appendix W: Publishing with GitHub Pages

      +
      +

      Listen to Episode 33: Publishing with GitHub Pages - a conversational audio overview of this chapter. Listen before reading to preview the concepts, or after to reinforce what you learned.

      +
      +
      +

      Reference companion to: Chapter 08: Open Source Culture | Also relevant: Chapter 21

      +

      Authoritative source: GitHub Docs: About Pages

      +
      +

      How to Deploy a Static Website Directly from Your Repository

      +
      +

      GitHub Pages lets you publish a static website straight from a GitHub repository - no server, no hosting bill, no deployment pipeline required for simple sites. This appendix explains how to enable it, what it can publish, and how to ensure the published site meets the same accessibility standards as your source code.

      +
      +

      Learning Cards: GitHub Pages Overview

      +
      +Screen reader users + +
        +
      • The Pages settings are under Settings (gear icon in repository navigation) then "Pages" in the left sidebar under the "Code and automation" group heading
        • +
      • Branch and folder selectors in the Pages settings are standard select elements -- navigate with arrow keys to choose your publishing source
        • +
      • After deployment, the published URL appears as a link at the top of the Pages settings page
        • +
      +
      + +
      +Low vision users + +
        +
      • GitHub Pages settings use the same layout as other repository settings -- look for the "Pages" link in the left sidebar after clicking Settings
        • +
      • The deployment status indicator shows a green checkmark for successful deployments and a red X for failures
        • +
      • Published sites inherit no special styling from GitHub -- ensure your site's CSS provides adequate contrast and font sizing
        • +
      +
      + +
      +Sighted users + +
        +
      • Find Pages settings via the repository's Settings tab, then "Pages" in the left sidebar under "Code and automation"
        • +
      • The publishing source selector lets you choose a branch and folder (/ root or /docs) -- select your combination and click Save
        • +
      • After a successful deployment, a green banner with your site URL appears at the top of the Pages settings
        • +
      +
      + + +

      Table of Contents

      +
        +
      1. What GitHub Pages Is
        2. +
      2. Enabling GitHub Pages for a Repository
        3. +
      3. Publishing Sources
        4. +
      4. The html/ Folder in This Project
        5. +
      5. Custom Domains
        6. +
      6. HTTPS and Security
        7. +
      7. Accessibility Considerations for Published Sites
        8. +
      8. GitHub Actions and Continuous Deployment
        9. +
      9. Limitations
        10. +
      10. Troubleshooting
        11. +
      +

      1. What GitHub Pages Is

      +

      GitHub Pages is a static site hosting service built into GitHub. It serves files directly from a branch or folder in your repository at a URL of the form:

      +
      https://<username>.github.io/<repository-name>/
      +

      For organization accounts and user profile repositories (<username>/<username>.github.io), the URL becomes:

      +
      https://<username>.github.io/
      +

      What "static" means: GitHub Pages only serves files as-is - HTML, CSS, JavaScript, images, PDFs. It does not run server-side code (no PHP, no Python, no Node.js request handlers). If you need a database or dynamic server logic, you need a different host.

      +

      What it is good for

      +
        +
      • Documentation sites
        • +
      • Workshop materials (like this project)
        • +
      • Project landing pages
        • +
      • Personal portfolios
        • +
      • Simple blogs via Jekyll
        • +
      +

      2. Enabling GitHub Pages for a Repository

      +

      Step-by-step (GitHub.com)

      +
        +
      1. Go to the repository on GitHub.com
        2. +
      2. Click Settings (the gear icon in the top navigation)
        3. +
      3. In the left sidebar, scroll to Code and automation and click Pages
        4. +
      4. Under Build and deployment, choose your publishing source:
          +
        • Deploy from a branch - serve files directly from a branch/folder
          • +
        • GitHub Actions - use a workflow to build and deploy
          • +
        +
        5. +
      5. If using "Deploy from a branch":
          +
        • Select the branch (e.g. main or master)
          • +
        • Select the folder: / (root) or /docs
          • +
        +
        6. +
      6. Click Save
        7. +
      +

      GitHub will build and deploy within a minute or two. The URL appears at the top of the Pages settings once the first deployment succeeds.

      +

      Screen reader navigation for the Pages settings page

      +
        +
      • The Settings tab is a link in the repository's top navigation bar. It has the accessible name "Settings"
        • +
      • The Pages option in the left sidebar is a link under the "Code and automation" group heading
        • +
      • The branch and folder dropdowns are standard <select> elements - navigate with arrow keys
        • +
      +

      3. Publishing Sources

      +

      Deploy from a branch

      +

      The simplest option. GitHub reads files directly from a branch.

      + + + + + + + + + + + + + + + +
      Folder optionWhat it serves
      / (root)Serves the entire repository root
      /docsServes only the docs/ folder - useful when your repository also contains source code
      +

      Best practice: Use /docs to isolate the published content from source files, especially for projects with build pipelines where the output lives in a specific folder.

      +

      GitHub Actions

      +

      Use a workflow (YAML file in .github/workflows/) to build your site before publishing. This is required when:

      +
        +
      • Your source is Markdown and you need a build step (e.g. this project's scripts/build-html.js)
        • +
      • You are using a static site generator like Jekyll, Hugo, or Eleventy
        • +
      • You want to run accessibility tests in CI before publishing
        • +
      +

      A basic workflow for this project would:

      +
        +
      1. Check out the repository
        2. +
      2. Run node scripts/build-html.js
        3. +
      3. Upload the html/ folder as the Pages artifact
        4. +
      +

      4. The html/ Folder in This Project

      +

      This project has a pre-built HTML mirror of all Markdown content in the html/ folder, generated by scripts/build-html.js. To publish this as a GitHub Pages site:

      +

      Option A: Manual publishing from html/ folder

      +

      Because GitHub Pages only supports / (root) or /docs as folder sources, and this project's output is in html/, you have two options:

      +

      Option A1 - Copy html/ contents to docs/

      +
      # Copy the html/ output into docs/ for GitHub Pages
+cp -r html/* docs/
+git add docs/
+git commit -m "Publish HTML output to docs/ for GitHub Pages"
+git push
      +

      Then set Pages source to branch master, folder /docs.

      +

      Option A2 - Rename html/ to docs/

      +

      If the project does not already use docs/ for Markdown sources, you could rename the output folder:

      +
      # Update the build script output path first, then
+git mv html/ docs/
+git commit -m "Rename html/ to docs/ for GitHub Pages compatibility"
+git push
      +

      Note: This project uses docs/ for Markdown source files, so this would conflict. Option A1 or the Actions approach below is safer.

      +

      Option B: GitHub Actions workflow

      +

      Create .github/workflows/pages.yml:

      +
      name: Deploy to GitHub Pages
+
+on:
+  push:
+    branches: [master]
+
+permissions:
+  contents: read
+  pages: write
+  id-token: write
+
+concurrency:
+  group: "pages"
+  cancel-in-progress: false
+
+jobs:
+  build:
+    runs-on: ubuntu-latest
+    steps:
+      - name: Checkout
+        uses: actions/checkout@v4
+
+      - name: Set up Node.js
+        uses: actions/setup-node@v4
+        with:
+          node-version: '20'
+
+      - name: Install dependencies
+        run: npm install
+
+      - name: Build HTML
+        run: node scripts/build-html.js
+
+      - name: Upload Pages artifact
+        uses: actions/upload-pages-artifact@v3
+        with:
+          path: html/
+
+  deploy:
+    needs: build
+    runs-on: ubuntu-latest
+    environment:
+      name: github-pages
+      url: ${{ steps.deployment.outputs.page_url }}
+    steps:
+      - name: Deploy to GitHub Pages
+        id: deployment
+        uses: actions/deploy-pages@v4
      +

      This workflow triggers on every push to master, rebuilds the HTML, and deploys the html/ folder.

      +

      5. Custom Domains

      +

      GitHub Pages supports custom domains (e.g. learning.community-access.org instead of community-access.github.io/Learning-Room).

      +

      Setting up a custom domain

      +
        +
      1. In repository Settings → Pages, enter your domain in the Custom domain field and click Save
        2. +
      2. GitHub creates a CNAME file in the repository root containing your domain name
        3. +
      3. At your DNS provider, create the appropriate records:
        4. +
      + + + + + + + + + + + + + + + + + + +
      Domain typeDNS record typeValue
      Subdomain (e.g. learning.community-access.org)CNAMEcommunity-access.github.io
      Apex domain (e.g. community-access.org)A records (×4)GitHub's IP addresses (see below)
      +

      GitHub's current A record IPs for apex domains

      +
      185.199.108.153
+185.199.109.153
+185.199.110.153
+185.199.111.153
      +

      DNS changes can take up to 48 hours to propagate. GitHub Pages checks and verifies the domain automatically once DNS is configured.

      +

      Domain verification

      +

      To prevent domain takeover attacks, GitHub recommends verifying your custom domain in your account or organization settings (Settings → Pages → Add a domain). This prevents others from claiming your domain for their GitHub Pages if you temporarily remove it.

      +

      6. HTTPS and Security

      +

      GitHub Pages enforces HTTPS automatically for github.io subdomains. For custom domains:

      +
        +
      1. After DNS propagates, check Enforce HTTPS in Pages settings
        2. +
      2. GitHub Pages uses Let's Encrypt to provision a certificate automatically
        3. +
      3. Enforcing HTTPS redirects all HTTP traffic to HTTPS
        4. +
      +

      Important: Never store secrets, API keys, or private data in a GitHub Pages repository. The repository content is public (on public repositories) and is served as-is. Even deleted files remain in git history.

      +

      7. Accessibility Considerations for Published Sites

      +

      Publishing a site does not automatically make it accessible. Consider the following for the published HTML output:

      +

      Learning Cards: Accessibility of Published Sites

      +
      +Screen reader users + +
        +
      • Verify that published HTML pages include a skip-to-content link as the first focusable element -- press Tab once after the page loads to check
        • +
      • Confirm the page has a descriptive title element and a single H1 heading -- these are announced first when the page opens
        • +
      • Test that all internal navigation links work and land on the correct heading or section
        • +
      +
      + +
      +Low vision users + +
        +
      • Run an automated contrast checker (axe, WAVE) on published pages after any CSS changes to confirm text remains readable
        • +
      • Test the published site at 200% browser zoom to verify layouts do not break or hide content
        • +
      • If the site uses a custom theme, verify it works in both forced-colors mode (Windows High Contrast) and standard mode
        • +
      +
      + +
      +Sighted users + +
        +
      • Check that the page has clear visual heading hierarchy -- headings should be visually distinct and match the HTML heading levels (H1, H2, H3)
        • +
      • Verify all images have visible alt text or are clearly decorative -- missing alt attributes leave broken-image icons with no context
        • +
      • Test keyboard navigation through the entire page by pressing Tab repeatedly to ensure focus is visible and flows logically
        • +
      +
      + + +

      The HTML generated by scripts/build-html.js converts Markdown headings and structure to HTML. Verify the output includes:

      +
        +
      • A <main> landmark wrapping the primary content
        • +
      • Logical heading hierarchy (H1 → H2 → H3)
        • +
      • A page <title> that reflects the document topic
        • +
      +

      Skip navigation

      +

      For sites with repeated navigation on every page, add a skip link as the first element in <body>:

      +
      <a class="skip-link" href="#main-content">Skip to main content</a>
      +

      With CSS to show it only on focus:

      +
      .skip-link {
+  position: absolute;
+  top: -40px;
+  left: 0;
+}
+.skip-link:focus {
+  top: 0;
+}
      +

      Focus management for single-page navigation

      +

      If the site uses JavaScript to load content without full page reloads, manage focus explicitly when content changes. Move focus to the new <h1> or a wrapper with tabindex="-1" after navigation.

      +

      Image alt text

      +

      All images in published pages should have appropriate alt attributes. Decorative images should use alt="" (empty, not missing) to be skipped by screen readers.

      +

      Color contrast

      +

      Run the published pages through an automated checker (axe, WAVE) after changes to the stylesheet to verify contrast ratios remain compliant.

      +

      Testing the published site

      +

      After deployment, test the live URL rather than only local files. Some issues (e.g. mixed content, broken relative links, missing files) only appear when served from a web server.

      +

      Recommended post-deployment checks

      +
        +
      1. Navigate all pages keyboard-only
        2. +
      2. Run axe DevTools on the index page and at least one content page
        3. +
      3. Verify no broken links with a link checker (e.g. W3C Link Checker)
        4. +
      4. Test with a screen reader announcement of the page title and <h1>
        5. +
      +

      8. GitHub Actions and Continuous Deployment

      +

      Using the Actions workflow described in Section 4 means every push to master automatically rebuilds and redeploys the site.

      +

      Adding automated accessibility checks to the workflow

      +

      Extend the workflow to fail the build if accessibility violations are found:

      +
            - name: Install axe CLI
+        run: npm install -g @axe-core/cli
+
+      - name: Run accessibility check
+        run: axe html/index.html --exit
      +

      This uses the axe-core CLI to scan the built index page. The --exit flag causes the step to fail if violations are found, blocking the deployment.

      +

      For more comprehensive checking, scan multiple pages:

      +
            - name: Run accessibility checks
+        run: |
+          for file in html/docs/*.html; do
+            axe "$file" --exit
+          done
      +

      9. Limitations

      + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + +
      LimitationDetail
      Repository sizeGitHub Pages sites should be under 1 GB
      BandwidthSoft limit of 100 GB per month
      Build timeJekyll builds must complete within 10 minutes
      No server-side codeNo PHP, Python, Ruby on Rails, Node.js handlers
      No .htaccessApache-style redirects are not supported; use _redirects for some static hosts
      Public repositoriesFor free accounts, GitHub Pages requires the repository to be public
      Private PagesAvailable on GitHub Enterprise plans only
      +

      10. Troubleshooting

      +

      Site not updating after a push

      +
        +
      • Check the Actions tab for a failed deploy workflow
        • +
      • Check Settings → Pages - the most recent deployment timestamp should match your push
        • +
      • Hard-refresh the browser (Ctrl+F5 / Cmd+Shift+R) to bypass the cache
        • +
      • DNS TTL caching can delay custom domain updates up to the TTL value (often 1 hour)
        • +
      +

      404 on all pages except index

      +

      This usually indicates a base URL mismatch. If your site is at https://user.github.io/my-repo/, all relative asset and link paths must account for the /my-repo/ path prefix. Check that the HTML output uses relative paths (./styles/main.css) rather than root-relative paths (/styles/main.css).

      +

      HTTPS certificate not provisioning

      +
        +
      • Verify DNS records are correctly set
        • +
      • Ensure the domain is not proxied through a CDN (e.g. Cloudflare orange-cloud) - GitHub Pages needs to see the DNS record directly to provision the cert
        • +
      • Allow up to 24 hours after correct DNS propagation
        • +
      +

      Screen reader announces wrong page title

      +

      The published <title> element is set during the HTML build step. Update the template in scripts/build-html.js to ensure each page has a unique, descriptive title.

      +
      +

      Next: Appendix X: Resources
      Back: Appendix V: GitHub Mobile
      Teaching chapter: Chapter 08: Open Source Culture

      + +
      + + + + diff --git a/html/admin/qa-bundle/docs/appendix-x-resources.html b/html/admin/qa-bundle/docs/appendix-x-resources.html new file mode 100644 index 00000000..5054fcc2 --- /dev/null +++ b/html/admin/qa-bundle/docs/appendix-x-resources.html @@ -0,0 +1,1521 @@ + + + + + + + Appendix X: Resources - GIT Going with GitHub + + + + + + + + +
      +

      Appendix X: Resources

      +
      +

      Listen to Episode 38: Resources and Links - a conversational audio overview of this chapter. Listen before reading to preview the concepts, or after to reinforce what you learned.

      +
      +
      +

      Reference companion to: All chapters | Master resource index for the entire curriculum

      +
      +

      Everything You Need - Before, During, and After the Workshop

      +
      +

      This is your permanent reference. Every link, tool, guide, and community resource from the two-day workshop in one place. Bookmark this page in your fork so it travels with you.

      +
      +

      Learning Cards: Navigating This Resource Guide

      +
      +Screen reader users + +
        +
      • This appendix is organized as 16 numbered sections with heading levels -- press H or 2 to jump between major sections in browse mode
        • +
      • Most sections contain tables of links -- navigate tables with T to jump to the next table, then use arrow keys to read rows and columns
        • +
      • Each resource link opens in the same tab by default -- use Ctrl+Enter (Windows) to open in a new tab and keep this reference page available
        • +
      +
      + +
      +Low vision users + +
        +
      • Tables in this appendix have a Resource/URL/Notes column structure -- widen your browser or zoom out slightly if columns overlap at high magnification
        • +
      • Link text is descriptive (resource names, not raw URLs) making it easier to scan the page visually
        • +
      • Bookmark this page in your browser for quick access -- it is the single-page reference for everything from the workshop
        • +
      +
      + +
      +Sighted users + +
        +
      • Use the Table of Contents at the top to jump directly to any of the 16 resource categories
        • +
      • Each section uses a consistent table layout: Resource name (left), URL (middle), Notes (right)
        • +
      • The GitHub keyboard shortcuts section (14) is worth bookmarking separately -- press ? on any GitHub page for a shortcuts overlay
        • +
      +
      + + +

      Table of Contents

      +
        +
      1. The Central Project - Accessibility Agents
        2. +
      2. GitHub Accessibility Guides
        3. +
      3. GitHub Skills Learning Modules
        4. +
      4. Screen Reader Downloads and Documentation
        5. +
      5. VS Code Resources
        6. +
      6. GitHub Copilot Resources
        7. +
      7. GitHub Agentic Workflows
        8. +
      8. Spec-Driven Development - Spec Kit
        9. +
      9. GitHub CLI, Desktop, and Copilot CLI
        10. +
      10. GitHub Mobile Apps
        11. +
      11. GitHub Best Practices and Power Features
        12. +
      12. Finding More Contributions
        13. +
      13. Accessibility Standards and References
        14. +
      14. GitHub Keyboard Shortcuts
        15. +
      15. Community and Support
        16. +
      16. Your Workshop Documentation - Offline Reference
        17. +
      +

      1. The Central Project - Accessibility Agents

      +

      The project you forked, contributed to, and carry home.

      + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + +
      ResourceURLNotes
      Accessibility Agents - Main Repogithub.com/community-access/accessibility-agentsThe upstream - your contributions go here
      Getting Started Guideaccessibility-agents/Documentation/GETTING-STARTED.mdYour first hour with the agents
      Full Reference Guideaccessibility-agents/Documentation/GUIDE.mdComplete agent and command reference
      Setup Guideaccessibility-agents/SETUP.mdConfiguration and preferences
      Contributing Guideaccessibility-agents/CONTRIBUTING.mdHow to submit improvements
      Security Policyaccessibility-agents/SECURITY.mdResponsible disclosure instructions
      MIT Licenseaccessibility-agents/LICENSEFork it, use it, make it yours
      +

      Your Personal Fork

      +

      After the workshop, your fork lives at:

      +
      https://github.com/[your-username]/accessibility-agents
      +

      Quick access from VS Code

      +
        +
      1. Clone your fork: git clone https://github.com/[your-username]/accessibility-agents.git
        2. +
      2. Open in VS Code: cd accessibility-agents && code .
        3. +
      3. Open Copilot Chat: Ctrl+Shift+I
        4. +
      4. Type: @daily-briefing morning briefing
        5. +
      +

      Personalizing Your Fork

      +
        +
      1. Copy preferences.example.md to preferences.md in .github/agents/
        2. +
      2. Add your GitHub username, your most-used repositories, and your preferred output format
        3. +
      3. Commit the file - now the agents know who you are and what you work on
        4. +
      +

      2. GitHub Accessibility Guides

      +

      Official guides from the GitHub Accessibility team. These were the primary research sources for this workshop's documentation.

      + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + +
      GuideURLWhen to Use
      GitHub Repos - Screen Reader Guideaccessibility.github.com/documentation/guide/reposNavigating repositories, file trees, branches
      GitHub Issues - Screen Reader Guideaccessibility.github.com/documentation/guide/issuesFiling, reading, commenting on issues
      GitHub Pull Requests - Screen Reader Guideaccessibility.github.com/documentation/guide/pull-requestsReading diffs, reviewing, merging
      GitHub Copilot in VS Code - Screen Reader Guideaccessibility.github.com/documentation/guide/github-copilot-vscUsing Copilot with NVDA, JAWS, VoiceOver
      Custom Instructions - Screen Reader Guideaccessibility.github.com/documentation/guide/custom-instructionsConfiguring Copilot's behavior for your workflow
      Getting Started with Custom Agents for Accessibilityaccessibility.github.com/documentation/guide/getting-started-with-agentsWhat agents are, custom agents vs custom instructions, informational vs task-oriented agents, step-by-step walkthroughs for building both types
      Accessibility Settings Overviewdocs.github.com/en/get-started/accessibilityHovercard settings, motion reduction, color modes
      +

      3. GitHub Skills Learning Modules

      +

      GitHub Skills is GitHub's free, self-paced interactive learning platform. Every course runs entirely inside GitHub - no external site, no separate login, no video to watch. Each course uses the template-copy pattern: you copy the course repository to your account, and Mona (GitHub's official education bot) activates and teaches you entirely through issues and pull requests.

      +

      How GitHub Skills Works

      +

      Unlike a conventional course where you watch videos or read slides, GitHub Skills teaches through doing:

      +
        +
      1. Copy the course: Select "Start course" → "Use this template" → "Create a new repository." This copies the course scaffold to your own account.
        2. +
      2. Mona activates: A GitHub Actions workflow automatically runs - within 20 seconds, Mona opens your first lesson as an Issue in your new repository.
        3. +
      3. Read and act: The issue contains step-by-step instructions. You do the task (commit a file, open a PR, resolve a conflict) in the same repository.
        4. +
      4. Mona validates: Another GitHub Actions workflow detects what you did, checks if it's correct, and either advances you to the next step or gives you feedback to try again.
        5. +
      5. Repeat until done: All feedback arrives as issue comments and new issues. The course is complete when Mona closes the final issue with a success message.
        6. +
      +

      Screen Reader Navigation of a GitHub Skills Course

      +

      Since everything happens in GitHub, the accessibility skills from this workshop apply directly:

      +
      Starting a course:
+  Navigate to the module URL
+  B → "Start course" button → Enter
+  B → "Use this template" → Enter
+  B → "Create a new repository" → Enter
+  Fill in repo name → Tab → "Create repository" → Enter
+
+Following lessons:
+  Navigate to your new repo's Issues tab (G then I)
+  H or 3 → find "Step 1:" issue heading → Enter to open it
+  Read instructions with ↓ in Browse Mode
+  Complete the task described → commit / PR / edit as instructed
+  Wait ~20 seconds → Mona posts a follow-up comment or opens the next issue
+  9 (NVDA/JAWS) → navigate to comments to read Mona's feedback
      +

      After This Workshop - Your Learning Path

      +

      GitHub Skills courses are available 24/7 and are completely free. Recommended order after this workshop:

      + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + +
      ModuleURLDurationPrerequisiteWhat You Learn
      Introduction to GitHubgithub.com/skills/introduction-to-github< 1 hourNoneBranches, commits, pull requests, merge
      Communicate Using Markdowngithub.com/skills/communicate-using-markdown< 1 hourIntroduction to GitHubHeadings, emphasis, images, code blocks, task lists, tables
      Review Pull Requestsgithub.com/skills/review-pull-requests< 30 minIntroduction to GitHubAssign reviewers, leave comments, suggest changes, apply suggestions, approve, merge
      Resolve Merge Conflictsgithub.com/skills/resolve-merge-conflicts< 30 minIntroduction to GitHubWhy conflicts happen, reading conflict markers, resolving in the web editor
      Hello GitHub Actionsgithub.com/skills/hello-github-actions< 30 minIntroduction to GitHubWorkflow files, triggers, jobs, run steps, merge
      Write JavaScript Actionsgithub.com/skills/write-javascript-actions< 1 hourHello GitHub ActionsCustom action metadata (action.yml), writing steps, composing workflows
      +

      Relationship to this workshop: The introduction and PR courses reinforce everything you practiced here. The GitHub Actions course is the foundation for understanding the CI/CD workflows that run inside accessibility-agents.

      +

      4. Screen Reader Downloads and Documentation

      +

      Learning Cards: Screen Reader Downloads and Setup

      +
      +Screen reader users + +
        +
      • NVDA (free, Windows): download from nvaccess.org -- after installing, toggle browse/focus mode with NVDA+Space and open the elements list with NVDA+F7
        • +
      • JAWS (Windows): download a trial from freedomscientific.com -- Virtual PC Cursor toggle is Insert+Z, elements list is Insert+F3
        • +
      • VoiceOver (macOS/iOS): built in, no download needed -- start with Cmd+F5 on Mac, or Settings then Accessibility then VoiceOver on iOS
        • +
      +
      + +
      +Low vision users + +
        +
      • NVDA and JAWS both support speech and braille output simultaneously if you use a refreshable braille display
        • +
      • VoiceOver on macOS integrates with Zoom (screen magnifier) -- enable both in System Settings then Accessibility for combined magnification and speech
        • +
      • Narrator on Windows is built in and requires no download -- launch with Win+Ctrl+Enter for a quick, lightweight screen reader experience
        • +
      +
      + +
      +Sighted users + +
        +
      • NVDA is free and the most common screen reader for testing on Windows -- install it to verify your content is accessible
        • +
      • VoiceOver is built into every Mac and iPhone -- toggle it with Cmd+F5 (Mac) to quickly test how your pages sound
        • +
      • The key commands listed in this section (H for headings, B for buttons, K for links) work in all major screen readers and are essential for understanding how AT users navigate
        • +
      +
      + +

      NVDA (Windows)

      + + + + + + + + + + + + + + + + + + + + + + + +
      ResourceURL
      Download NVDA (free)NVDA download page
      NVDA User GuideNVDA User Guide
      NVDA Add-onsNVDA Add-on Store
      NVDA CommunityNVDA Community site
      +

      Key commands (quick reference)

      +
        +
      • Toggle browse/focus mode: NVDA+Space
        • +
      • Elements list: NVDA+F7
        • +
      • Next heading: H | Next link: K | Next button: B | Next form field: F
        • +
      +

      JAWS (Windows)

      + + + + + + + + + + + + + + + + + + + +
      ResourceURL
      Download JAWS (trial available)freedomscientific.com/products/software/jaws
      JAWS Getting Startedfreedomscientific.com/training/jaws/getting-started
      JAWS Keyboard Referencefreedomscientific.com/training/jaws/keyboard-shortcuts
      +

      Key commands (quick reference)

      +
        +
      • Virtual PC Cursor on/off: Insert+Z
        • +
      • Elements list: Insert+F3
        • +
      • Next heading: H | Next link: Tab or U | Next button: B
        • +
      +

      VoiceOver (macOS / iOS - built in)

      + + + + + + + + + + + + + + + + + + + +
      ResourceURL
      VoiceOver User Guide (macOS)support.apple.com/guide/voiceover/welcome/mac
      VoiceOver Getting Started (macOS)apple.com/accessibility/mac/vision
      Enable VoiceOverCmd+F5 (macOS) or Settings → Accessibility → VoiceOver (iOS)
      +

      Key commands (quick reference)

      +
        +
      • Start/stop VoiceOver: Cmd+F5
        • +
      • VO modifier: Caps Lock or Ctrl+Option
        • +
      • Rotor: VO+U
        • +
      • Next heading: VO+Cmd+H
        • +
      +

      Other Screen Readers (Reference)

      + + + + + + + + + + + + + + + + + + + + + + + +
      Screen ReaderPlatformURL
      NarratorWindows (built in)Win+Ctrl+Enter to launch - no download required
      OrcaLinux (GNOME)wiki.gnome.org/Projects/Orca
      TalkBackAndroid (built in)Settings → Accessibility → TalkBack
      +

      5. VS Code Resources

      + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + +
      ResourceURLNotes
      Download VS Codecode.visualstudio.comFree - Windows, macOS, Linux
      VS Code Accessibility Docscode.visualstudio.com/docs/editor/accessibilityScreen reader mode, audio cues, accessible view
      VS Code Keyboard Shortcuts (Windows)aka.ms/vscode-keyboard-windowsFull reference PDF
      VS Code Keyboard Shortcuts (macOS)aka.ms/vscode-keyboard-macFull reference PDF
      GitHub Pull Requests Extensionmarketplace.visualstudio.com/items?itemName=GitHub.vscode-pull-request-githubReview and manage PRs from VS Code
      GitLensmarketplace.visualstudio.com/items?itemName=eamodio.gitlensEnhanced git history, blame, and branch visualization
      YAML Supportmarketplace.visualstudio.com/items?itemName=redhat.vscode-yamlYAML validation - useful for issue templates
      +

      Install the GitHub PR extension quickly

      +
        +
      1. Open VS Code Extensions (Ctrl+Shift+X)
        2. +
      2. Search: GitHub Pull Requests
        3. +
      3. Install: publisher is "GitHub"
        4. +
      +

      6. GitHub Copilot Resources

      + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + +
      ResourceURLNotes
      GitHub Copilot (Free tier)github.com/features/copilotFree for individuals - no credit card required
      Copilot Documentationdocs.github.com/copilotFull reference
      Copilot in VS Codedocs.github.com/en/copilot/using-github-copilot/getting-started-with-github-copilotSetup guide
      Copilot Extensions Marketplacegithub.com/marketplace?type=apps&copilot_app=trueExtensions that add capabilities to Copilot Chat
      Custom Instructions for Copilotdocs.github.com/en/copilot/customizing-copilot/adding-custom-instructions-for-github-copilotTeach Copilot your preferences and project context
      Copilot Coding Agent - Customize Environmentdocs.github.com/en/copilot/how-tos/use-copilot-agents/coding-agent/customize-the-agent-environmentSwitch coding agent to Windows dev environment
      Copilot in VS Code - A11y Guideaccessibility.github.com/documentation/guide/github-copilot-vscScreen reader-optimized usage
      +

      7. GitHub Agentic Workflows

      +

      GitHub Agentic Workflows are in technical preview as of February 2026. Access, feedback channels, and setup information:

      + + + + + + + + + + + + + + + + + + + + + + + + + + + + +
      ResourceURLNotes
      Agentic Workflows Blog Postgithub.blog/ai-and-ml/automate-repository-tasks-with-github-agentic-workflowsThe announcement - explains the full model
      gh-aw CLI Extensiongh extension install github/gh-awInstall via GitHub CLI
      Technical Preview Feedbackgh.io/aw-tp-community-feedbackCommunity discussion for the preview
      GitHub Next Discordgh.io/next-discordReal-time discussion with the GitHub Next team
      +

      How Agentic Workflows connect to what you learned

      +

      During the workshop, you learned:

      +
        +
      1. Standard GitHub Actions (YAML workflows - triggers, jobs, steps)
        2. +
      2. Accessibility Agents agents (.agent.md files - plain English instructions, Copilot Chat executor)
        3. +
      3. GitHub Agentic Workflows (.md files in .github/workflows/ - plain English instructions, cloud-based coding agent executor)
        4. +
      +

      All three live in .github/. All three are plain text. The only difference is where they run and how sophisticated their executor is.

      +

      8. Spec-Driven Development - Spec Kit

      + + + + + + + + + + + + + + + + + + +
      ResourceURLNotes
      Spec Kit - GitHub Repogithub.com/github/spec-kitOpen source, MIT license
      Spec Kit Blog Postgithub.blog/ai-and-ml/generative-ai/spec-driven-development-with-ai-get-started-with-a-new-open-source-toolkitFull explanation of the methodology
      +

      The core idea: Write the intent of a feature before anyone builds it. The specification is a living document - AI uses it to plan tasks, contributors use it to stay aligned, the community uses it to evaluate whether the outcome matched the intention.

      +

      Quick start

      +
      uvx --from git+https://github.com/github/spec-kit.git specify init YOUR_PROJECT_NAME
      +

      Slash commands

      +
        +
      • /specify - open a new specification session
        • +
      • /plan - convert a spec into a development plan
        • +
      • /tasks - break the plan into trackable tasks
        • +
      +

      Works with GitHub Copilot, Claude Code, and Gemini CLI.

      +

      9. GitHub CLI, Desktop, and Copilot CLI

      +

      GitHub CLI (gh)

      + + + + + + + + + + + + + + + + + + + +
      ResourceURL
      Downloadcli.github.com
      Documentationcli.github.com/manual
      Authentication guidedocs.github.com/en/github-cli/github-cli/quickstart
      +
      # Install
+winget install GitHub.cli     # Windows
+brew install gh               # macOS
+
+# Most useful commands for contributors
+gh issue list                 # List issues in current repo
+gh issue view 42              # Read issue #42
+gh pr list                    # List open PRs
+gh pr view 14                 # Read PR #14
+gh pr create                  # Create a PR interactively
+gh pr merge 14                # Merge PR #14
+gh repo fork                  # Fork the current repo
+gh repo clone owner/repo      # Clone a repository
      +

      Copilot in the CLI (gh copilot)

      +
      # Install the extension
+gh extension install github/gh-copilot
+
+# Ask Copilot to explain a command
+gh copilot explain "git rebase -i HEAD~3"
+
+# Ask Copilot to suggest a command
+gh copilot suggest "undo my last commit but keep the changes staged"
      +

      GitHub Desktop

      + + + + + + + + + + + + + + + +
      ResourceURL
      Downloaddesktop.github.com
      Keyboard shortcutsdocs.github.com/en/desktop/installing-and-authenticating-to-github-desktop/keyboard-shortcuts-in-github-desktop
      +

      10. GitHub Mobile Apps

      +

      GitHub's official mobile apps bring the full GitHub experience to your phone or tablet. Perfect for reviewing PRs, triaging issues, and staying connected when away from your computer.

      + + + + + + + + + + + + + + + + + + +
      PlatformDownloadScreen Reader Support
      iOSapps.apple.com/app/github/id1477376905VoiceOver supported
      Androidplay.google.com/store/apps/details?id=com.github.androidTalkBack supported
      +

      What You Can Do in GitHub Mobile

      +
        +
      • Browse repositories - navigate code, read files, view commits
        • +
      • Manage issues - create, edit, comment, close, and label issues
        • +
      • Review pull requests - read diffs, leave comments, request changes, approve, merge
        • +
      • Manage notifications - triage your inbox on the go
        • +
      • Interact with GitHub Copilot - chat with Copilot Chat on mobile (as of Feb 2026)
        • +
      • View GitHub Actions - monitor workflows and check build status
        • +
      • Manage Discussions - participate in community conversations
        • +
      +

      Accessibility Features

      +

      Both apps support:

      +
        +
      • Native screen reader gestures (VoiceOver on iOS, TalkBack on Android)
        • +
      • Dynamic text sizing
        • +
      • Dark mode / high contrast
        • +
      • Keyboard navigation (when using external keyboard with tablet)
        • +
      +

      Pro tip: Enable push notifications for mentions and reviews so you can respond quickly when your input is needed.

      +

      11. GitHub Best Practices and Power Features

      +

      Essential tips and lesser-known features that make you a more effective contributor.

      +

      Saved Replies

      +

      Saved replies let you create reusable text templates for common responses. Perfect for:

      +
        +
      • Thanking first-time contributors
        • +
      • Requesting more information with a friendly tone
        • +
      • Explaining common setup issues
        • +
      • Closing duplicate issues
        • +
      +

      How to set up

      +
        +
      1. Go to github.com/settings/replies
        2. +
      2. Click "Add a saved reply"
        3. +
      3. Give it a short label (e.g., "welcome-first-time")
        4. +
      4. Write your template text (can include Markdown)
        5. +
      5. Save
        6. +
      +

      How to use

      +
        +
      • When writing any comment, press Ctrl+. (period) to open the saved replies menu
        • +
      • Select your saved reply
        • +
      • Edit as needed before posting
        • +
      +

      Pinned Issues

      +

      Pin important issues to the top of your repository's Issues tab. Perfect for:

      +
        +
      • FAQs and getting started guides
        • +
      • Known issues and workarounds
        • +
      • Roadmap and project status updates
        • +
      • Community guidelines
        • +
      +

      How to pin an issue

      +
        +
      1. Open the issue you want to pin
        2. +
      2. In the right sidebar, click the three-dot menu (⋯)
        3. +
      3. Select "Pin issue"
        4. +
      4. It now appears at the top of the Issues list
        5. +
      +

      You can pin up to 3 issues per repository. Pinned issues are visible to everyone, even those who haven't starred or watched your repo.

      +

      Pinned Comments (New: Feb 2026)

      +

      You can now pin a single comment within an issue thread to keep important information visible. Perfect for:

      +
        +
      • Workarounds or temporary solutions
        • +
      • Decisions made during discussion
        • +
      • Links to related issues or PRs
        • +
      • Status updates from maintainers
        • +
      +

      How to pin a comment

      +
        +
      1. Find the comment you want to pin
        2. +
      2. Click the three-dot menu (⋯) on the comment
        3. +
      3. Select "Pin comment"
        4. +
      +

      Only repository collaborators can pin comments. There can be only one pinned comment per issue.

      +

      Linking to Specific Lines of Code

      +

      Share precise references to code by including line numbers in GitHub URLs.

      +

      Syntax

      +
        +
      • Single line: github.com/owner/repo/blob/main/file.js#L42
        • +
      • Line range: github.com/owner/repo/blob/main/file.js#L42-L58
        • +
      + +
        +
      1. Navigate to a file on GitHub
        2. +
      2. Click the line number (in screen readers: navigate to the line and activate the number link)
        3. +
      3. Hold Shift and click another line number to select a range
        4. +
      4. Copy the URL from your browser - the line numbers are automatically included
        5. +
      +

      Screen reader tip: Line numbers are links announced as "Line 42 link" (or similar). They're in the left margin of the code view.

      +

      Permalinks - Stable Links That Never Break

      +

      When you link to code on GitHub using a branch name (main, develop), that link can break if the code changes or the file moves. Permalinks use the commit SHA instead of the branch name, creating a permanent snapshot link.

      +

      Why this matters: When you file a bug report or reference code in a discussion, you want the link to show exactly what you were looking at - not what the code looks like weeks later after someone refactored it.

      + +
        +
      1. View any file on GitHub
        2. +
      2. Press Y while viewing the file - the URL changes from /blob/main/file.js to /blob/a1b2c3d4.../file.js
        3. +
      3. Copy the new URL - it now points to that specific commit
        4. +
      +

      Shortcut: Y = "Yank permalink" (borrows from Vim terminology)

      +

      Converting Issues to Discussions

      +

      Not every issue is a bug or feature request. Some are questions, proposals, or open-ended conversations. GitHub Discussions provide a better home for these.

      +

      When to convert

      +
        +
      • Questions that don't require a code change ("How do I configure X?")
        • +
      • Proposals that need community feedback before becoming actionable
        • +
      • General discussion about the project's direction
        • +
      • Show-and-tell or community showcases
        • +
      +

      How to convert an issue to a discussion

      +
        +
      1. Open the issue
        2. +
      2. In the right sidebar, click "Convert to discussion"
        3. +
      3. Select which discussion category it belongs in
        4. +
      4. Confirm
        5. +
      +

      All comments and history are preserved. The issue is closed and replaced with a link to the new discussion.

      +

      Team Mentions - Notify a Whole Group

      +

      In organizations, you can mention entire teams instead of individuals: @org-name/team-name

      +

      Example: @github/accessibility notifies everyone on GitHub's accessibility team.

      +

      Why this matters

      +
        +
      • You don't need to know who's on a team - just mention the team
        • +
      • Teams can subscribe to notifications as a group
        • +
      • CODEOWNERS files use team mentions for automatic reviewer assignment
        • +
      +

      Permission: You can only mention teams you have visibility to. Public teams in public orgs can be mentioned by anyone.

      +

      Collapsible Sections in Markdown

      +

      Keep long issue descriptions or PR descriptions scannable by hiding details in collapsible sections.

      +

      Syntax

      +
      <details>
+<summary>Click to expand: Full error stack trace</summary>
+
+(Your detailed content here - code blocks, lists, anything)
+
+</details>
      +

      Use for

      +
        +
      • Long error messages or logs
        • +
      • Optional context that most readers don't need
        • +
      • Large screenshots or code samples
        • +
      • Step-by-step troubleshooting instructions
        • +
      +

      Accessibility note: Collapsible sections are announced as "disclosure triangles" or "expandable" regions by most screen readers. The summary text is always visible.

      +

      Co-Authored Commits

      +

      Credit multiple people for a single commit using the Co-authored-by trailer in your commit message.

      +

      Syntax

      +
      Fix keyboard navigation in modal dialog
+
+This addresses the issue where focus was lost when the modal closed.
+
+Co-authored-by: Alex Chen <alex@example.com>
+Co-authored-by: Jordan Smith <jordan@example.com>
      +

      Why this matters

      +
        +
      • Pair programming - both people get credit in the Git history
        • +
      • Crediting someone who provided the solution but didn't write the code
        • +
      • GitHub recognizes these trailers and shows all co-authors on the commit
        • +
      +

      Screen reader tip: When viewing a commit with co-authors on GitHub, screen readers announce "Co-authored-by" in the commit details.

      +

      Understanding Watch, Star, and Fork

      +

      Three ways to interact with a repository - each means something different:

      + + + + + + + + + + + + + + + + + + + + + + + +
      ActionWhat It DoesWhen to Use
      WatchSubscribe to notifications for activityYou want to stay updated on issues, PRs, and releases
      StarBookmark a repoYou want to save it for later or show appreciation
      ForkCreate your own copy of the repoYou want to contribute changes or use it as a starting point
      +

      Watch settings

      +
        +
      • All activity - every issue, PR, and discussion
        • +
      • Participating (default) - only threads you comment on or are @mentioned in
        • +
      • Releases only - just new releases
        • +
      • Ignore - unsubscribe completely
        • +
      +

      Pro tip: Star repos for discovery; Watch repos you actively contribute to.

      +

      CODEOWNERS - Automatic Reviewer Assignment

      +

      The CODEOWNERS file automatically requests reviews from specific people or teams when files in their area are changed.

      +

      Location: .github/CODEOWNERS in your repository

      +

      Syntax

      +
      # Documentation team reviews all docs changes
+/docs/ @org-name/docs-team
+
+# Accessibility specialist reviews UI changes
+/src/components/ @username
+
+# Security team reviews authentication code
+/src/auth/ @org-name/security-team
+
+# Default owner for everything else
+* @project-lead
      +

      How it works

      +
        +
      1. Someone opens a PR that changes files in /docs/
        2. +
      2. GitHub automatically requests a review from @org-name/docs-team
        3. +
      3. The PR can't be merged until the required review is approved (if branch protection requires it)
        4. +
      +

      Use for

      +
        +
      • Ensuring domain experts review specialized code
        • +
      • Distributing review responsibilities
        • +
      • Preventing changes from being merged without appropriate oversight
        • +
      +

      GitHub Sponsors

      +

      Support open source maintainers financially through GitHub Sponsors. If a project you use has a "Sponsor" button, consider supporting them.

      +

      How it works

      +
        +
      • Maintainers set up a Sponsors profile
        • +
      • You can sponsor with a monthly recurring amount or one-time payment
        • +
      • GitHub doesn't take a fee (as of 2026)
        • +
      +

      Why sponsor

      +
        +
      • Open source maintainers often work for free in their spare time
        • +
      • Your sponsorship helps them dedicate more time to the project
        • +
      • Many maintainers offer perks to sponsors (early access, prioritized issues, etc.)
        • +
      +

      How to sponsor

      +
        +
      1. Visit a repository with a "Sponsor" button
        2. +
      2. Click the button
        3. +
      3. Choose a sponsorship tier
        4. +
      4. Complete payment through GitHub Sponsors
        5. +
      +

      Advanced Markdown Features

      +

      GitHub supports several powerful Markdown features beyond the basics:

      +

      Task Lists

      +
      - [x] Completed task
+- [ ] Pending task
+- [ ] Another pending task
      +

      Tables with alignment

      +
      | Left-aligned | Center-aligned | Right-aligned |
+|:-------------|:--------------:|--------------:|
+| Text         | Text           | Text          |
      +

      Mermaid Diagrams

      +
      ```mermaid
+graph TD
+    A[User opens issue] --> B{Is it a bug?}
+    B -->|Yes| C[Label: bug]
+    B -->|No| D[Label: enhancement]
+```text
      +

      Math Expressions (LaTeX)

      +
      Inline math: $E = mc^2$
+
+Block math:
+$$
+\sum_{i=1}^{n} i = \frac{n(n+1)}{2}
+$$
      +

      Footnotes

      +
      Here is a statement that needs citation[^1].
+
+[^1]: Source: Documentation link
      +

      Alerts (Callout blocks)

      +
      > [!NOTE]
+> Useful information that users should know
+
+> [!WARNING]
+> Critical content requiring immediate attention
+
+> [!TIP]
+> Helpful advice for better outcomes
      +

      12. Finding More Contributions

      +

      After the workshop, use these resources to find your next open source contribution.

      + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + +
      ResourceURLWhat It Does
      Good First IssueGood First IssueCurated list of beginner-friendly issues across popular open source projects
      Up For GrabsUp For GrabsProjects that explicitly welcome new contributors
      GitHub ExploreGitHub ExploreDiscover trending repos, topics, and collections
      Accessibility on GitHubSearch: topic:accessibility is:publicPublic repositories tagged with the accessibility topic
      AT on GitHubSearch: topic:assistive-technology is:publicPublic repositories tagged with assistive-technology
      Filter by labelIn any repo: Issues → Label → good first issueWorks on every public repository
      +

      GitHub search queries to bookmark

      +
      is:open is:issue label:good-first-issue topic:accessibility
+is:open is:issue label:help-wanted topic:screen-reader
+is:open is:issue label:accessibility no:assignee
      +

      13. Accessibility Standards and References

      + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + +
      ResourceURLNotes
      WCAG 2.2 (Full Standard)WCAG 2.2 specificationThe complete Web Content Accessibility Guidelines
      WCAG Quick ReferenceWCAG 2.2 Quick ReferenceFiltered, searchable version - much more practical
      ARIA Authoring Practices GuideARIA Authoring Practices GuideWhen and how to use ARIA roles and attributes
      WebAIM Screen Reader SurveyWebAIM Screen Reader SurveyReal-world data on how screen reader users work
      The A11y ProjectThe A11y ProjectCommunity-driven accessibility checklist and resources
      Deque University (free content)Deque UniversityFree accessibility rules reference
      MDN Accessibility GuideMDN Accessibility GuideWeb accessibility fundamentals
      +

      Accessibility Testing Tools

      + + + + + + + + + + + + + + + + + + + + + + + + + + + + +
      ToolURLNotes
      WebAIM Contrast CheckerWebAIM Contrast CheckerCheck text/background color contrast against WCAG AA/AAA
      WAVE Browser ExtensionWAVE Browser ExtensionHighlights accessibility issues on any webpage - Chrome, Firefox, Edge
      Axe DevToolsAxe DevToolsFinds WCAG violations with severity levels
      LighthouseIn Chrome DevTools (F12 → Lighthouse tab)Built-in auditing for accessibility, performance, and SEO
      +

      Interactive Git Learning

      + + + + + + + + + + + + + + + + + + + + + + + + + + + + +
      ResourceURLNotes
      Learn Git BranchingLearn Git BranchingGamified, step-by-step challenges - branching, merging, rebasing
      Visualizing GitVisualizing GitInteractive visual playground for branches and commits
      Pro Git Book (free)Pro Git BookComplete reference - free online
      Git Cheat SheetGitHub Git Cheat Sheet (PDF)Quick command reference PDF
      +

      14. GitHub Keyboard Shortcuts

      + + + + + + + + + + + + + + + + + + +
      ResourceURLNotes
      Full Keyboard Shortcuts ReferenceGitHub Keyboard Shortcuts documentationEvery shortcut on every page
      Press ? on any GitHub page-Opens the keyboard shortcuts overlay for that specific page
      +

      The most important shortcuts to memorize

      + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + +
      ShortcutWhat It Does
      ?Open keyboard shortcuts help for current page
      G I (press G then I)Go to Issues tab
      G PGo to Pull Requests tab
      G AGo to Actions tab
      G CGo to Code tab
      /Focus the search bar
      CCreate a new issue (on Issues list page)
      EArchive notification (on Notifications page)
      Shift+IMark notification as read
      MMute thread (on Notifications page)
      +

      14b. Learning Pathways

      +

      Not sure where to start after the workshop? Use these suggested paths.

      +

      By Role

      + + + + + + + + + + + + + + + + + + + + + + + + + + + + +
      RoleStart HereThen
      New contributor00-pre-workshop-setup.mdIssues → Pull Requests → Merge Conflicts
      Maintainer09-labels-milestones-projects.mdIssue templates → Branch protection → Notifications
      Accessibility advocate15-code-review.mdScreen reader cheat sheet → Appendix C (Standards)
      FacilitatorFACILITATOR.mdDay 1 and Day 2 agendas → FAQ
      +

      By Time Available

      + + + + + + + + + + + + + + + + + + + + + + + +
      TimeSuggested Path
      30 minPre-workshop setup → Understanding GitHub's web structure
      1 hourAdd: Working with Issues
      2 hoursAdd: Pull Requests + Navigating Repositories
      4+ hoursAll core chapters → pick one advanced appendix topic
      +

      15. Community and Support

      +

      GitHub Accessibility

      + + + + + + + + + + + + + + + + + + + +
      ResourceURL
      GitHub Accessibility Community DiscussionsGitHub Community Accessibility Discussions
      GitHub Accessibility FeedbackGitHub Accessibility Feedback Discussions
      GitHub Accessibility Team (public presence)GitHub Accessibility site
      +

      Accessibility Agents Community

      + + + + + + + + + + + + + + + + + + + +
      ResourceURL
      Accessibility Agents Issues (bug reports, ideas)Accessibility Agents Issues
      Accessibility Agents DiscussionsAccessibility Agents Discussions
      Security concernsjeff@jeffbishop.com (do not open public issues for vulnerabilities)
      +

      Open Source Accessibility Community

      + + + + + + + + + + + + + + + + + + + +
      ResourceURL
      A11y SlackA11y Slack community (invite: A11y Slack invite page)
      A11y Weekly NewsletterA11y Weekly Newsletter
      Inclusive Design Research CentreInclusive Design Research Centre
      +

      16. Your Workshop Documentation - Offline Reference

      +

      Every guide from this workshop lives in your fork. Clone your fork once and the complete documentation works offline - no internet required.

      +
      git clone https://github.com/[your-username]/accessibility-agents.git
      +

      The documentation set is in the docs/ folder of this learning repository (separate from the accessibility-agents fork). If your workshop facilitator shared a repository link for the learning materials, clone that too.

      +

      Quick Navigation

      + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + +
      TopicFile
      Pre-workshop setupdocs/00-pre-workshop-setup.md
      Understanding GitHub's Web Structuredocs/02-understanding-github.md
      Navigating repositoriesdocs/03-navigating-repositories.md
      The Learning Roomdocs/04-the-learning-room.md
      Working with issuesdocs/05-working-with-issues.md
      Working with pull requestsdocs/06-working-with-pull-requests.md
      Merge conflictsdocs/07-merge-conflicts.md
      Culture and etiquettedocs/08-open-source-culture.md
      Labels, milestones, projectsdocs/09-labels-milestones-projects.md
      Notificationsdocs/10-notifications-and-day-1-close.md
      Day 1 agendaDAY1_AGENDA.md
      Day 2 agendaDAY2_AGENDA.md
      VS Code: Setup & Accessibility Basicsdocs/11-vscode-interface.md
      VS Code: Git & Source Controldocs/14-git-in-practice.md
      VS Code: GitHub Pull Requests Extensiondocs/15-code-review.md
      VS Code: GitHub Copilotdocs/16-github-copilot.md
      Accessible Code Reviewdocs/15-code-review.md
      Issue Templatesdocs/17-issue-templates.md
      VS Code: Accessibility Agentsdocs/19-accessibility-agents.md
      Resources (this file)docs/appendix-x-resources.md
      Appendix A: GitHub Concepts Glossarydocs/appendix-a-glossary.md
      Appendix B: Screen Reader Cheat Sheetdocs/appendix-b-screen-reader-cheatsheet.md
      Appendix C: Accessibility Standards Referencedocs/appendix-m-accessibility-standards.md
      Appendix D: Git Authenticationdocs/appendix-d-git-authentication.md
      Appendix E: GitHub Flavored Markdowndocs/appendix-c-markdown-reference.md
      Appendix F: GitHub Gistsdocs/appendix-u-discussions-and-gists.md
      Appendix G: GitHub Discussionsdocs/appendix-u-discussions-and-gists.md
      Appendix H: Releases, Tags, and Repository Insightsdocs/appendix-s-releases-tags-insights.md
      Appendix I: GitHub Projects Deep Divedocs/appendix-r-projects-deep-dive.md
      Appendix J: GitHub Advanced Searchdocs/appendix-n-advanced-search.md
      Appendix K: Branch Protection Rules and Repository Rulesetsdocs/appendix-o-branch-protection.md
      Appendix L: GitHub Security Featuresdocs/appendix-p-security-features.md
      Appendix M: VS Code Accessibility Referencedocs/appendix-g-vscode-reference.md
      Appendix N: GitHub Codespacesdocs/appendix-j-cloud-editors.md
      Appendix O: GitHub Mobiledocs/appendix-v-github-mobile.md
      Appendix P: Publishing with GitHub Pagesdocs/appendix-w-github-pages.md
      Appendix Q: GitHub Actions and Workflowsdocs/appendix-q-actions-workflows.md
      Appendix R: GitHub Profile, Sponsors, and Wikisdocs/appendix-t-community-and-social.md
      Appendix S: Organizations, Templates, and Repository Settingsdocs/appendix-t-community-and-social.md
      Appendix T: Contributing to Open Sourcedocs/08-open-source-culture.md
      Appendix U: Resources (this file)docs/appendix-x-resources.md
      Appendix V: Accessibility Agents Referencedocs/appendix-l-agents-reference.md
      Appendix W: GitHub Copilot Referencedocs/appendix-k-copilot-reference.md
      Appendix X: GitHub Copilot AI Modelsdocs/appendix-k-copilot-reference.md
      +
      +

      Next: Appendix Y: Workshop Materials
      Back: Appendix W: GitHub Pages
      Teaching chapter: All chapters

      + +
      + + + + diff --git a/html/admin/qa-bundle/docs/appendix-y-workshop-materials.html b/html/admin/qa-bundle/docs/appendix-y-workshop-materials.html new file mode 100644 index 00000000..882fa803 --- /dev/null +++ b/html/admin/qa-bundle/docs/appendix-y-workshop-materials.html @@ -0,0 +1,342 @@ + + + + + + + Appendix Y: Accessing and Downloading Workshop Materials - GIT Going with GitHub + + + + + + + + +
      +

      Appendix Y: Accessing and Downloading Workshop Materials

      +
      +

      Listen to Episode 42: Accessing Workshop Materials - a conversational audio overview of this chapter. Listen before reading to preview the concepts, or after to reinforce what you learned.

      +
      +
      +

      Reference companion to: Chapter 00: Pre-Workshop Setup

      +

      Authoritative source: Community-Access/git-going-with-github

      +
      +

      How to Get, Read, and Keep These Documents

      +
      +

      Why this appendix exists: The workshop content is available in multiple formats - Markdown source files, pre-built HTML pages, and a live GitHub Pages site. This guide explains how to access each format, download materials for offline use, and keep your copy up to date.

      +
      +

      Learning Cards: Accessing Workshop Materials

      +
      +Screen reader users + +
        +
      • The GitHub Pages site includes skip-to-content links and ARIA landmarks -- press D (NVDA) or R (JAWS) to jump to the main content landmark on any page
        • +
      • On GitHub.com, press T on the repository's main page to open the file finder -- type any filename to jump directly to it without navigating the file tree
        • +
      • After cloning the repository, open it in VS Code and use the Explorer panel (Ctrl+Shift+E) to browse the file tree with arrow keys
        • +
      +
      + +
      +Low vision users + +
        +
      • The HTML version in the html/ folder provides the most polished reading experience with styled, navigable pages that work offline in any browser
        • +
      • For reading Markdown source files, use VS Code's built-in preview (Ctrl+Shift+V) which renders headings, links, and code blocks in a formatted view
        • +
      • When downloading a ZIP from GitHub, the Code button and its dropdown appear near the top of the repository page -- look for the green button
        • +
      +
      + +
      +Sighted users + +
        +
      • Three ways to access materials: GitHub Pages site (online, styled), GitHub.com (browse rendered Markdown), or local clone (offline, editable)
        • +
      • The repository's docs/ folder contains all Markdown source files; the html/ folder contains pre-built HTML versions of every page
        • +
      • Use git clone for a full copy you can update with git pull -- ZIP downloads are snapshots that do not update automatically
        • +
      +
      + + +

      Table of Contents

      +
        +
      1. Browsing Online (GitHub Pages)
        2. +
      2. Reading on GitHub.com
        3. +
      3. Downloading Everything
        4. +
      4. Downloading Individual Files
        5. +
      5. What's in Each Folder
        6. +
      6. Offline Reading
        7. +
      7. Keeping Your Copy Updated
        8. +
      8. Which Format Should I Use?
        9. +
      +

      1. Browsing Online (GitHub Pages)

      +

      If the facilitator has enabled GitHub Pages for this repository, the workshop materials are available as a website at a URL like:

      +
      https://<organization>.github.io/Learning-Room/
      +

      Your facilitator will share the exact URL. Once you have it:

      +
        +
      1. Open the URL in your browser
        2. +
      2. The landing page (index.html) is the workshop homepage - equivalent to the README
        3. +
      3. Use headings (H key in NVDA/JAWS browse mode) to navigate within any page
        4. +
      4. All internal links between chapters and appendices work - click any cross-reference to go directly to that page
        5. +
      5. Bookmark the URL for quick access during the workshop
        6. +
      +

      Screen reader tip: The HTML pages include skip-to-content links, breadcrumb navigation, and ARIA landmarks. Press D (NVDA) or R (JAWS) to jump to the main landmark on any page.

      +

      For details on how GitHub Pages works, see Appendix P - Publishing with GitHub Pages.

      +

      2. Reading on GitHub.com

      +

      You can read every file directly on GitHub.com without downloading anything:

      +
        +
      1. Go to the repository page (your facilitator will share the link)
        2. +
      2. The README renders automatically as the repository homepage
        3. +
      3. Click into the docs/ folder to see all chapters and appendices
        4. +
      4. Click any .md file - GitHub renders it as formatted text with headings, links, and code blocks
        5. +
      + +
        +
      • File list: The repository file listing is a grid. Use T to jump to the file table, then arrow keys to navigate rows
        • +
      • File content: Once inside a file, GitHub renders the Markdown. Use H to navigate headings
        • +
      • Breadcrumbs: At the top of each file view, breadcrumb links show the path (e.g., Learning-Room / docs / 06-working-with-pull-requests.md). Use these to navigate back
        • +
      • Go to File shortcut: Press T on the repository's main page to open the file finder - type any filename to jump to it
        • +
      +

      3. Downloading Everything

      + +

      Cloning gives you a full copy of the repository that you can update later with git pull:

      +
      # Clone the repository
+git clone https://github.com/community-access/git-going-with-github.git
+
+# Move into the folder
+cd Learning-Room
      +

      After cloning, every file (Markdown source, HTML output, scripts, learning-room materials) is on your computer.

      +

      Screen reader tip: After cloning, open the folder in VS Code (code .) and use the Explorer panel (Ctrl+Shift+E) to browse the file tree. Press Enter on any file to open it in the editor.

      +

      Option B: Download ZIP (no Git required)

      +

      If you do not have Git installed or prefer not to use the command line:

      +
        +
      1. Go to the repository page on GitHub.com
        2. +
      2. Press T to find the file finder, or navigate to the green Code button (it is a dropdown button near the top of the file listing)
        3. +
      3. Activate the Code button - a dropdown menu opens
        4. +
      4. Choose Download ZIP
        5. +
      5. Save the file and extract it to a folder on your computer
        6. +
      +

      Screen reader navigation for the Code dropdown

      +
        +
      • The Code button is near the repository description, after the branch selector
        • +
      • In NVDA/JAWS browse mode, press B to jump between buttons until you reach "Code"
        • +
      • Activate it with Enter or Space
        • +
      • The dropdown contains options including "Download ZIP" - arrow down to find it
        • +
      +

      Note: A ZIP download is a snapshot. It does not update automatically - see Section 7 for how to get updates.

      +

      4. Downloading Individual Files

      +

      To download a single file (for example, one chapter or the screen reader cheat sheet):

      +

      From GitHub.com

      +
        +
      1. Navigate to the file in the repository
        2. +
      2. Click the Raw button (it appears above the file content, in the toolbar with "Preview", "Code", "Blame" buttons)
        3. +
      3. The browser shows the raw file content
        4. +
      4. Press Ctrl+S (Windows/Linux) or Cmd+S (macOS) to save the page
        5. +
      +

      For HTML files: Navigate to the html/ folder and download the .html version of any file using the same Raw → Save method.

      +

      From a cloned repository

      +

      If you have already cloned the repo, every file is already on your computer. Open the folder and copy whichever files you need.

      +

      5. What's in Each Folder

      + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + +
      FolderContentsFormat
      docs/All 17 chapters (00-16) and 31 appendices (A-Z, AA-AE)Markdown (.md)
      html/Pre-built HTML versions of every Markdown fileHTML (.html)
      html/docs/HTML versions of all chapters and appendicesHTML (.html)
      learning-room/Practice repository files: challenges, group exercises, setup guidesMarkdown (.md)
      html/learning-room/HTML versions of learning-room documentsHTML (.html)
      .github/Issue templates, PR template, Copilot agents, slash commandsYAML and Markdown
      scripts/Build script that converts Markdown to HTMLJavaScript
      Root (/)README, agendas, facilitator guide, contributing guide, and other project filesMarkdown (.md)
      +

      6. Offline Reading

      +

      Once you have downloaded or cloned the repository, you can read everything offline:

      +

      Reading Markdown files

      +

      Open .md files in any text editor. They are plain text with lightweight formatting syntax. VS Code renders Markdown with a preview panel (Ctrl+Shift+V).

      +

      Reading HTML files

      +
        +
      1. Open html/index.html in any web browser
        2. +
      2. All internal links between pages work locally - no internet connection required
        3. +
      3. Navigate between chapters using the links at the bottom of each page
        4. +
      +

      Screen reader tip: The HTML files work the same offline as online. All ARIA landmarks, heading structure, and skip links are embedded in each file.

      + +
        +
      • VS Code with Markdown: Open the repo folder in VS Code, browse the Explorer, and read files directly in the editor. Use Ctrl+Shift+V to open the rendered preview
        • +
      • Browser with HTML: Open html/index.html and navigate from there - this gives the most polished reading experience
        • +
      +

      7. Keeping Your Copy Updated

      +

      If you cloned with Git

      +
      # Navigate to your local copy
+cd Learning-Room
+
+# Pull the latest changes
+git pull
      +

      If you have not made local changes, this updates your copy cleanly. If you have local edits, Git will attempt to merge - see Chapter 7 - Merge Conflicts if needed.

      +

      After pulling, rebuild the HTML to ensure it matches:

      +
      npm run build:html
      +

      If you downloaded a ZIP

      +

      Download a fresh ZIP from the repository and replace your local copy. There is no incremental update for ZIP downloads.

      +

      8. Which Format Should I Use?

      + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + +
      NeedBest formatWhy
      Reading during the workshopGitHub Pages (online HTML)No setup, always current, fully accessible
      Offline referenceLocal HTML (html/ folder)Works in any browser, no internet needed, styled and navigable
      Editing or contributingMarkdown (.md files)The source format - edit these, then rebuild HTML
      Quick lookup of one sectionGitHub.comNavigate directly in the browser, no download
      Archiving a copyZIP download or Git cloneFull snapshot of all materials
      Staying updated long-termGit cloneOne-command updates with git pull
      +

      Learning Cards: Choosing the Right Format

      +
      +Screen reader users + +
        +
      • For workshop use, the GitHub Pages HTML site is the most accessible option -- it includes skip links, landmarks, and proper heading structure in every page
        • +
      • For offline reference, the local HTML files in the html/ folder work identically to the online version with full navigation between pages
        • +
      • For contributing edits, work with the Markdown source files in docs/ using VS Code -- these are the canonical source that generates everything else
        • +
      +
      + +
      +Low vision users + +
        +
      • GitHub Pages and local HTML both support browser zoom to 200%+ without layout breakage -- use whichever gives you a better reading experience
        • +
      • VS Code's Markdown preview inherits your editor theme -- if you use a high-contrast theme, the preview will match
        • +
      • If viewing on GitHub.com, enable GitHub's dark theme (Settings then Appearance) for reduced eye strain during long reading sessions
        • +
      +
      + +
      +Sighted users + +
        +
      • Use the GitHub Pages site during the workshop for the most polished, hyperlinked reading experience with no setup required
        • +
      • Clone the repository for a permanent offline copy -- the html/index.html file serves as a local homepage linking to all content
        • +
      • The Markdown source in docs/ is what you edit to contribute improvements -- changes are rebuilt to HTML automatically via the GitHub Actions workflow
        • +
      +
      + +
      +

      Next: Appendix Z: GitHub Skills
      Back: Appendix X: Resources
      Teaching chapter: Chapter 00: Pre-Workshop Setup

      + +
      + + + + diff --git a/html/admin/qa-bundle/docs/appendix-z-github-skills.html b/html/admin/qa-bundle/docs/appendix-z-github-skills.html new file mode 100644 index 00000000..d0e3f621 --- /dev/null +++ b/html/admin/qa-bundle/docs/appendix-z-github-skills.html @@ -0,0 +1,823 @@ + + + + + + + Appendix Z: GitHub Skills - Complete Course Catalog - GIT Going with GitHub + + + + + + + + +
      +

      Appendix Z: GitHub Skills - Complete Course Catalog

      +
      +

      Listen to Episode 43: GitHub Skills - Complete Course Catalog - a conversational audio overview of this chapter. Listen before reading to preview the concepts, or after to reinforce what you learned.

      +
      +
      +

      Reference companion to: Chapter 00: Pre-Workshop Setup | Also relevant: Chapter 21

      +

      Authoritative source: GitHub Skills

      +
      +

      GitHub Skills is GitHub's free, self-paced interactive learning platform. Every course runs entirely inside GitHub - no external site, no separate login, no video. You copy a course repository to your own account, and an automated bot named Mona teaches you through real issues and pull requests.

      +

      This appendix catalogs every available GitHub Skills module, organized into learning paths that build on the skills you practiced in this workshop. Use it as a roadmap for continued learning after Day 2.

      +

      Learning Cards: How GitHub Skills Works

      +
      +Screen reader users + +
        +
      • Every GitHub Skills course runs inside a standard GitHub repository -- the screen reader navigation skills from this workshop (heading nav, issue reading, PR workflows) apply directly
        • +
      • After copying a course with "Use this template," navigate to the Issues tab (G then I) and press H or 3 to find "Step 1:" -- this is where Mona's first lesson appears
        • +
      • Mona posts feedback as issue comments -- press 9 (NVDA/JAWS) to jump to the comments section and read her instructions
        • +
      +
      + +
      +Low vision users + +
        +
      • Course content appears as standard GitHub issues and comments -- your existing GitHub theme and font size settings apply automatically
        • +
      • Mona's step numbers appear as issue titles with "Step 1:", "Step 2:" prefixes -- scan the Issues list for these numbered titles to track your progress
        • +
      • Course completion is indicated when Mona closes the final issue with a success message -- look for the purple "Closed" badge
        • +
      +
      + +
      +Sighted users + +
        +
      • Start any course by clicking "Start course" on the module page, then "Use this template" then "Create a new repository" -- Mona activates within 20 seconds
        • +
      • Each step appears as a new issue or comment in your copied repository -- follow the instructions, complete the task, and Mona advances you automatically
        • +
      • Track progress by watching the Issues tab -- open issues are pending steps, closed issues are completed steps
        • +
      +
      + + +

      How GitHub Skills Works

      +

      Each course follows the same pattern:

      +
        +
      1. Navigate to the course URL and select "Start course"
        2. +
      2. GitHub copies the course repository to your account
        3. +
      3. Mona (GitHub's automated learning bot) opens an issue with Step 1 instructions within 20 seconds
        4. +
      4. You complete the task described in the issue (create a branch, edit a file, open a PR)
        5. +
      5. Mona detects your action, validates it, and posts the next step as a comment or new issue
        6. +
      6. Repeat until Mona closes the final issue with a completion message
        7. +
      +

      All interaction happens through GitHub's standard interface. The screen reader navigation skills from this workshop - heading navigation, landmark jumping, issue and PR workflows - apply directly.

      +

      For detailed screen reader navigation instructions, see Appendix U Section 3 (GitHub Skills).

      +

      Courses Used in This Workshop

      +

      These three modules are integrated into the Day 1 agenda. You complete them during the workshop with facilitator guidance.

      +

      The following table lists the three GitHub Skills modules used during Day 1, with their workshop block and what each teaches.

      + + + + + + + + + + + + + + + + + + + + + + + + + + + +
      ModuleWorkshop BlockWhat Mona TeachesLink
      Introduction to GitHubDay 1, Blocks 1-3Branches, commits, pull requests, mergeStart course
      Communicate Using MarkdownDay 1, Block 3Headings, emphasis, links, code blocks, task lists, tablesStart course
      Review Pull RequestsDay 1, Block 4Assign reviewers, leave comments, suggest changes, approve, mergeStart course
      +

      If you did not finish these during the workshop, complete them first before moving to the paths below.

      +

      Learning Paths

      +

      The remaining courses are organized into six learning paths. Each path builds on skills from this workshop and progresses from introductory to advanced. You do not need to complete every path - choose the ones that match your goals.

      +

      Learning Cards: Navigating Learning Paths

      +
      +Screen reader users + +
        +
      • The six learning paths below are organized as H3 headings with tables listing courses in recommended order -- press 3 to jump between paths, then T to enter each course table
        • +
      • Each course link is in the rightmost "Link" column of the table -- navigate to it with arrow keys after entering the table
        • +
      • Use the Personal Completion Checklist at the bottom of this appendix as a progress tracker -- copy it into a GitHub issue or personal notes file
        • +
      +
      + +
      +Low vision users + +
        +
      • Each learning path table has columns for Order, Module, Duration, Prerequisite, What You Learn, and Link -- widen your browser if columns appear truncated at high zoom
        • +
      • Course durations range from 30 minutes to 2 hours -- the Duration column helps you plan which courses fit your available time
        • +
      • The Quick Reference table near the bottom alphabetically lists all 36 courses for fast scanning when you know the course name
        • +
      +
      + +
      +Sighted users + +
        +
      • Six paths organize 33 post-workshop courses by topic: Git, Collaboration, Actions, Copilot, Security, and Cloud
        • +
      • Each path is sequenced from introductory to advanced -- start at Order 1 in any path and work down
        • +
      • The Quick Reference section at the bottom lists all 36 courses alphabetically with category labels and direct "Start course" links
        • +
      +
      + +

      Path 1: Git Fundamentals

      +

      Deepen your understanding of Git version control beyond what the workshop covered.

      +

      The following table lists Git fundamentals courses in recommended order.

      + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + +
      OrderModuleDurationPrerequisiteWhat You LearnLink
      1Introduction to GitLess than 1 hourNoneGit CLI and VS Code - branches, commits, and merges using command lineStart course
      2Resolve Merge ConflictsLess than 30 minIntroduction to GitHubWhy conflicts happen, reading conflict markers, resolving in the web editorStart course
      3Change Commit HistoryLess than 1 hourIntroduction to GitAmend commits, interactive rebase, squash, and reorder historyStart course
      +

      Workshop connection: Day 1, Block 5 introduced merge conflicts in the learning room. Path 1 gives you deep practice with Git's conflict resolution and history tools.

      +

      Path 2: GitHub Collaboration

      +

      Learn the collaboration features that power open source projects and team workflows.

      +

      The following table lists GitHub collaboration courses in recommended order.

      + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + +
      OrderModuleDurationPrerequisiteWhat You LearnLink
      1Introduction to Repository ManagementLess than 1 hourIntroduction to GitHubBranch protection, issue templates, labels, milestones, and contributor-friendly settingsStart course
      2Connect the DotsLess than 30 minIntroduction to GitHubCross-referencing issues and PRs, linking work across your repositoryStart course
      3GitHub PagesLess than 1 hourIntroduction to GitHubDeploy a site from your repository using GitHub PagesStart course
      4Release-Based WorkflowLess than 1 hourIntroduction to GitHubCreate releases, tag versions, and manage a release-based workflowStart course
      +

      Workshop connection: Day 1, Block 6 covered labels, milestones, and notifications. Path 2 extends those skills into full repository management and publishing.

      +

      Path 3: GitHub Actions and Automation

      +

      Build automated workflows that test, build, and deploy your projects.

      +

      The following table lists GitHub Actions courses in recommended order.

      + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + +
      OrderModuleDurationPrerequisiteWhat You LearnLink
      1Hello GitHub ActionsLess than 30 minIntroduction to GitHubWorkflow files, triggers, jobs, steps, and your first automated runStart course
      2Test with ActionsLess than 1 hourHello GitHub ActionsContinuous integration (CI) - run tests automatically on every push and PRStart course
      3Reusable WorkflowsLess than 1 hourHello GitHub ActionsCreate shared workflows, call them from other repos, use matrix strategiesStart course
      4Write JavaScript ActionsLess than 1 hourHello GitHub ActionsBuild custom actions with JavaScript - action.yml metadata, inputs, outputsStart course
      5Publish Docker ImagesLess than 1 hourHello GitHub ActionsBuild Docker containers and publish to GitHub Packages using ActionsStart course
      6Deploy to AzureLess than 1 hourHello GitHub ActionsCreate deployment workflows for Azure using GitHub ActionsStart course
      7AI in ActionsLess than 1 hourHello GitHub ActionsIntegrate AI models from GitHub Models into your Actions workflowsStart course
      8Create AI-Powered ActionsLess than 1 hourWrite JavaScript ActionsBuild intelligent JavaScript-based Actions that use GitHub ModelsStart course
      +

      Workshop connection: Day 2 introduced GitHub Actions through the accessibility agents workflows. Path 3 teaches you to build your own automation from scratch.

      +

      Path 4: GitHub Copilot

      +

      Master AI-assisted development with GitHub Copilot across editors, CLI, and GitHub itself.

      +

      The following table lists GitHub Copilot courses in recommended order.

      + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + +
      OrderModuleDurationPrerequisiteWhat You LearnLink
      1Getting Started with GitHub CopilotLess than 1 hourNoneCode completion, Copilot Chat, debugging assistance, and your first AI-assisted projectStart course
      2Build Applications with Copilot Agent ModeLess than 1 hourGetting Started with CopilotUse Copilot's agent mode to build multi-file applications from natural languageStart course
      3Copilot Code ReviewLess than 30 minGetting Started with CopilotUse Copilot to review pull requests, catch quality issues, and improve code before mergingStart course
      4Customize Your GitHub Copilot ExperienceLess than 1 hourGetting Started with CopilotCustom instructions, prompt files, and chat modes for your specific workflowsStart course
      5Expand Your Team with CopilotLess than 1 hourGetting Started with CopilotCopilot coding agent - assign issues directly to Copilot on GitHub, no editor neededStart course
      6Integrate MCP with CopilotLess than 1 hourCustomize Your Copilot ExperienceConnect MCP servers to Copilot for external tool access and custom capabilitiesStart course
      7Scale Institutional Knowledge Using Copilot SpacesLess than 1 hourGetting Started with CopilotOrganize project knowledge into Copilot Spaces for team-wide context sharingStart course
      8Create Applications with the Copilot CLILess than 1 hourGetting Started with CopilotUse Copilot in the terminal to manage issues and build applications from the command lineStart course
      9Your First Extension for GitHub CopilotLess than 1 hourGetting Started with CopilotBuild a Copilot extension that teaches Copilot about your industry, terminology, and processesStart course
      10Modernize Your Legacy Code with GitHub CopilotLess than 2 hoursBuild Applications with Agent ModeUse Copilot to modernize a legacy COBOL accounting system to Node.jsStart course
      +

      Workshop connection: Day 2, Blocks 2-4 used Copilot for contributions and code review. Path 4 expands from basic chat to agent mode, MCP integration, CLI usage, and extension building.

      +

      Path 5: Security

      +

      Learn to identify vulnerabilities, scan for secrets, and secure your supply chain.

      +

      The following table lists security courses in recommended order.

      + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + +
      OrderModuleDurationPrerequisiteWhat You LearnLink
      1Secure Code Game1-2 hoursBasic coding knowledgeFind and fix real security vulnerabilities in an interactive, gamified formatStart course
      2Introduction to Secret ScanningLess than 30 minIntroduction to GitHubEnable secret scanning, detect leaked credentials, and prevent secrets from being committedStart course
      3Secure Repository Supply ChainLess than 1 hourIntroduction to GitHubUnderstand dependencies, find vulnerabilities with Dependabot, and patch themStart course
      4Introduction to CodeQLLess than 1 hourIntroduction to GitHubEnable code scanning with CodeQL to find security issues automaticallyStart course
      5Configure CodeQL Language MatrixLess than 30 minIntroduction to CodeQLSimplify code scanning workflows with CodeQL language matrices for multi-language reposStart course
      +

      Workshop connection: Appendix L covers GitHub security features conceptually. Path 5 gives you hands-on practice enabling and using each one.

      +

      Path 6: Cloud and Migration

      +

      Deploy to the cloud and migrate existing projects to GitHub.

      +

      The following table lists cloud and migration courses in recommended order.

      + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + +
      OrderModuleDurationPrerequisiteWhat You LearnLink
      1Code with CodespacesLess than 1 hourIntroduction to GitHubCreate and configure cloud development environments with GitHub CodespacesStart course
      2Migrate ADO RepositoryLess than 1 hourIntroduction to GitCreate a sample Azure DevOps project and migrate it to GitHub using the CLIStart course
      3Idea to App with SparkLess than 1 hourNoneTurn ideas into web applications by describing them in natural language - no coding requiredStart course
      +

      Workshop connection: Appendix N covers Codespaces conceptually. Path 6, course 1 gives you the hands-on setup experience.

      +

      Quick Reference - All 36 Courses

      +

      The following table alphabetically lists every GitHub Skills course with its category and link for quick lookup.

      + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + +
      ModuleCategoryLink
      AI in ActionsActionsStart course
      Build Applications with Copilot Agent ModeCopilotStart course
      Change Commit HistoryGitStart course
      Code with CodespacesCloudStart course
      Communicate Using MarkdownWorkshopStart course
      Configure CodeQL Language MatrixSecurityStart course
      Connect the DotsCollaborationStart course
      Copilot Code ReviewCopilotStart course
      Create AI-Powered ActionsActionsStart course
      Create Applications with the Copilot CLICopilotStart course
      Customize Your GitHub Copilot ExperienceCopilotStart course
      Deploy to AzureActionsStart course
      Expand Your Team with CopilotCopilotStart course
      Getting Started with GitHub CopilotCopilotStart course
      GitHub PagesCollaborationStart course
      Hello GitHub ActionsActionsStart course
      Idea to App with SparkCloudStart course
      Integrate MCP with CopilotCopilotStart course
      Introduction to CodeQLSecurityStart course
      Introduction to GitGitStart course
      Introduction to GitHubWorkshopStart course
      Introduction to Repository ManagementCollaborationStart course
      Introduction to Secret ScanningSecurityStart course
      Migrate ADO RepositoryCloudStart course
      Modernize Your Legacy Code with GitHub CopilotCopilotStart course
      Publish Docker ImagesActionsStart course
      Release-Based WorkflowCollaborationStart course
      Resolve Merge ConflictsGitStart course
      Reusable WorkflowsActionsStart course
      Review Pull RequestsWorkshopStart course
      Scale Institutional Knowledge Using Copilot SpacesCopilotStart course
      Secure Code GameSecurityStart course
      Secure Repository Supply ChainSecurityStart course
      Test with ActionsActionsStart course
      Write JavaScript ActionsActionsStart course
      Your First Extension for GitHub CopilotCopilotStart course
      +

      Integrating GitHub Skills into Your Learning Journey

      +

      During the Workshop

      +

      Three courses are woven into Day 1. You set each one up during the block where it appears, work through Mona's steps alongside the learning room exercises, and finish before moving to the next block. No preparation is required beyond having a GitHub account.

      +

      After the Workshop - Recommended Next Steps

      +
        +
      1. Finish any incomplete workshop courses first. If Introduction to GitHub, Communicate Using Markdown, or Review Pull Requests are still in progress, complete them before starting new modules.
        2. +

      2. Pick one path that matches your next goal:

        +
          +
        • Want to contribute to open source? Start with Path 2 (Collaboration).
          • +
        • Want to automate your workflow? Start with Path 3 (Actions).
          • +
        • Want to code faster with AI? Start with Path 4 (Copilot).
          • +
        • Want to secure your projects? Start with Path 5 (Security).
          • +
        +
        3. +
      3. Work through one course at a time. Each course takes 30-60 minutes. Spreading them across multiple days helps with retention.
        4. +
      4. Use the workshop materials as reference. When a GitHub Skills course asks you to create a branch or open a PR, the chapter guides from this workshop describe the same operations with screen reader instructions.
        5. +
      +

      Tracking Your Progress

      +

      GitHub Skills does not have a central dashboard for tracking completions. Use these strategies instead:

      +
        +
      • GitHub profile: Completed courses appear as repositories in your account. Pin your favorites to your profile.
        • +
      • Repository list: Filter your repositories by the "skills-" prefix to see all courses you have started.
        • +
      • Mona's final message: When you finish a course, Mona posts a completion message in the final issue. Bookmark it.
        • +
      • This checklist: Copy the list below into a personal note or issue to track which courses you have completed.
        • +
      +

      Personal Completion Checklist

      +

      Copy this list into your own notes to track progress:

      +
      Workshop Courses
+- [ ] Introduction to GitHub
+- [ ] Communicate Using Markdown
+- [ ] Review Pull Requests
+
+Path 1: Git Fundamentals
+- [ ] Introduction to Git
+- [ ] Resolve Merge Conflicts
+- [ ] Change Commit History
+
+Path 2: GitHub Collaboration
+- [ ] Introduction to Repository Management
+- [ ] Connect the Dots
+- [ ] GitHub Pages
+- [ ] Release-Based Workflow
+
+Path 3: GitHub Actions and Automation
+- [ ] Hello GitHub Actions
+- [ ] Test with Actions
+- [ ] Reusable Workflows
+- [ ] Write JavaScript Actions
+- [ ] Publish Docker Images
+- [ ] Deploy to Azure
+- [ ] AI in Actions
+- [ ] Create AI-Powered Actions
+
+Path 4: GitHub Copilot
+- [ ] Getting Started with GitHub Copilot
+- [ ] Build Applications with Copilot Agent Mode
+- [ ] Copilot Code Review
+- [ ] Customize Your GitHub Copilot Experience
+- [ ] Expand Your Team with Copilot
+- [ ] Integrate MCP with Copilot
+- [ ] Scale Institutional Knowledge Using Copilot Spaces
+- [ ] Create Applications with the Copilot CLI
+- [ ] Your First Extension for GitHub Copilot
+- [ ] Modernize Your Legacy Code with GitHub Copilot
+
+Path 5: Security
+- [ ] Secure Code Game
+- [ ] Introduction to Secret Scanning
+- [ ] Secure Repository Supply Chain
+- [ ] Introduction to CodeQL
+- [ ] Configure CodeQL Language Matrix
+
+Path 6: Cloud and Migration
+- [ ] Code with Codespaces
+- [ ] Migrate ADO Repository
+- [ ] Idea to App with Spark
      +

      Additional Resources

      + +
      +

      Back: Appendix Y: Workshop Materials
      Teaching chapter: Chapter 00: Pre-Workshop Setup

      + +
      + + + + diff --git a/html/admin/qa-bundle/docs/course-guide.html b/html/admin/qa-bundle/docs/course-guide.html new file mode 100644 index 00000000..b0e0a176 --- /dev/null +++ b/html/admin/qa-bundle/docs/course-guide.html @@ -0,0 +1,669 @@ + + + + + + + Course Guide - GIT Going with GitHub + + + + + + + + +
      +

      Course Guide

      +
      +

      Listen to Episode 0: Welcome to Git Going with GitHub - a conversational audio overview of this chapter. Listen before reading to preview the concepts, or after to reinforce what you learned.

      +
      +

      GitHub Learning Room - Your Complete Workshop Companion

      +
      +

      Welcome. You are about to begin a two-day journey into open source collaboration using GitHub, VS Code, and GitHub Copilot - all designed for screen reader and keyboard-only navigation. This guide is your starting point and table of contents for everything in this workshop.

      +

      Note: Workshop content is being actively refined for the May 2026 cohort. Students should expect updates to materials leading up to and during the course.

      +
      +

      How This Course Works

      +

      This is a two-day workshop built around one idea: you will make real contributions to a real open source project. Not simulated. Not pretend. Real.

      +

      Live Agenda and Self-Paced Curriculum

      +

      The live hackathon agenda is intentionally smaller than the full curriculum. Live sessions prioritize the core contribution path, while the complete chapter set remains available for self-paced preparation, catch-up, remote participation, and post-event continuation.

      +
        +
      • Live core: The facilitator chooses the minimum path needed for participants to make and understand a real contribution.
        • +
      • Async follow-up: Chapters and challenges not covered live can be completed after the session using the Learning Room, solutions, podcasts, and Slack channel.
        • +
      • Remote participation: Remote cohorts should use the same checkpoints and evidence prompts, with written instructions available before each live block.
        • +
      +

      The Two Days

      +

      Day 1 - GitHub Foundations (Browser)

      +

      You learn GitHub's web interface using only your keyboard and screen reader. The live Day 1 core path gets you through repository navigation, issues, branches, commits, and a first pull request. Review practice, merge conflicts, labels, notifications, and culture exercises remain available as stretch or async follow-up.

      +

      Day 2 - VS Code + Accessibility Agents (Desktop)

      +

      You move to Visual Studio Code, learn GitHub Copilot, and activate the Accessibility Agents ecosystem - 55 AI agents across 3 teams and 5 platforms that amplify every skill you built on Day 1. The live Day 2 core path prepares you to make a real contribution, and the async continuation path gives you time to polish and submit it well.

      +

      The Journey Arc

      +
      Day 1 - Learn the skill in the browser
+  Navigate → Issue → Pull Request → Review → Merge
+
+     ↓  (bridge: press . on any GitHub repo - VS Code opens in your browser)
+
+github.dev - VS Code on the web, no install needed
+  Same keyboard shortcuts · Same screen reader mode · Edit files · Open PRs
+
+     ↓  (you've earned the desktop - now it makes sense)
+
+Day 2 - Deepen with VS Code + Accessibility Agents
+  VS Code basics → Copilot inline → Copilot Chat
+  @daily-briefing → @issue-tracker → @pr-review → @analytics → prepare upstream
      +

      The key principle: Learn the manual skill first, then see how it is automated. The agents only make sense when you already understand what they are doing.

      +

      Before You Begin

      +

      Start with Get Going with GitHub if you want the most guided path. It explains how GitHub Classroom creates your private Learning Room repository, how Challenge 1 appears, how evidence prompts work, and how to choose between browser, github.dev, VS Code, GitHub Desktop, and command-line paths.

      +

      Complete everything in Chapter 00: Pre-Workshop Setup before Day 1. This chapter walks you through:

      +
        +
      • Creating a GitHub account
        • +
      • Installing Git
        • +
      • Setting up VS Code (optional for Day 1, required for Day 2)
        • +
      • Configuring your screen reader for GitHub
        • +
      • Verifying everything works
        • +
      +

      Time needed: About 30 minutes.

      +

      Companion Audio Series

      +

      Every chapter and appendix has a companion podcast episode - a conversational two-host overview that previews or reviews the key concepts. Listen before reading a chapter to know what to expect, or after to reinforce what you learned.

      + +

      Day 1: GitHub Foundations

      +

      These chapters are designed to be read and practiced in order. Each builds on the one before it.

      + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + +
      #ChapterWhat You Will LearnTime
      StartGet Going with GitHubGitHub Classroom onboarding, Learning Room first steps, support, and tool choice15 min
      00Pre-Workshop SetupInstall and configure everything before Day 130 min
      01Choose Your Adventure: A Tool TourExplore the 5 tool environments before you start30 min
      02Understanding GitHub's Web StructureHow GitHub is organized - page types, headings, landmarks, screen reader orientation1 hr
      03Navigating RepositoriesExplore any repo using your screen reader - tabs, files, commits, branches45 min
      04The Learning RoomYour shared practice environment - challenges, PR workflow, bot feedback, peer review30 min
      05Working with IssuesFile, search, filter, comment on, and manage issues1 hr
      06Working with Pull RequestsCreate, review, comment on, and merge pull requests1 hr
      07Merge ConflictsUnderstand why conflicts happen and how to resolve them1 hr
      08Open Source Culture and ContributingCommunication, tone, reviews, inclusive language, your first contribution30 min
      09Labels, Milestones and ProjectsOrganize and cross-reference work45 min
      10Notifications and Day 1 CloseManage your inbox, @mentions, and subscriptions; recap Day 130 min
      +

      Day 1 self-paced total: ~8 hours. The live Day 1 agenda covers the core path in a shorter Pacific-time event day and treats later challenges as stretch or async follow-up.

      +

      Day 2: VS Code + Accessibility Agents

      +

      Day 2 moves you from the browser to the desktop. Every skill maps directly to what you learned on Day 1.

      + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + +
      #ChapterWhat You Will LearnTime
      11VS Code: Interface and SetupLaunch VS Code, sign in, screen reader mode, Activity Bar, Settings, shortcuts45 min
      12VS Code: Accessibility Deep DiveKeyboard navigation, Problems panel, Terminal, Copilot Chat, Accessible Help/View/Diff, Signals, Speech45 min
      13How Git Works: The Mental ModelCommits, branches, local vs remote, push/pull/fetch, why conflicts happen30 min
      14Git in PracticeClone, branch, stage, commit, push, merge - all from VS Code1 hr
      15Code Review: PRs, Diffs, and FeedbackPR extension, accessible diffs, inline comments, the reviewer's craft1.5 hrs
      16GitHub CopilotInline suggestions, Copilot Chat, effective prompting, custom instructions1 hr
      17Issue TemplatesCreate and customize GitHub issue templates with YAML1 hr
      18Fork and ContributeThe complete fork-based open source contribution workflow45 min
      19Accessibility Agents55 agents across 3 teams, 54+ slash commands, contributing to the ecosystem1 hr
      20Build Your Agent: CapstoneDesign, build, and contribute a real accessibility agent1.5 hrs
      21What Comes NextGraduation, portfolio, continued learning, community30 min
      +

      Day 2 self-paced total: ~10 hours. The live Day 2 agenda focuses on VS Code, Git, Copilot, agent discovery, and supported contribution work; deeper capstone material can continue asynchronously.

      +

      Appendices - Reference Material

      +

      Open these at any time during the workshop. They are not part of the chapter sequence - use them when you need them.

      +

      Always Open (Bookmark These)

      + + + + + + + + + + + + + + + + + + +
      AppendixDocumentWhat It Covers
      AGlossaryEvery term, concept, and piece of jargon explained
      BScreen Reader Cheat SheetNVDA, JAWS, and VoiceOver navigation commands plus GitHub keyboard shortcuts
      +

      Core Reference (C-D)

      + + + + + + + + + + + + + + + + + + +
      AppendixDocumentWhat It Covers
      CMarkdown and GitHub Flavored MarkdownComplete guide from basics through GFM - headings, lists, links, tables, alerts, Mermaid, math, footnotes
      DGit AuthenticationSSH keys, Personal Access Tokens, credential storage, commit signing
      +

      Git Deep Dive (E-F)

      + + + + + + + + + + + + + + + + + + +
      AppendixDocumentWhat It Covers
      EAdvanced Git OperationsCherry-pick, interactive rebase, reset, revert, tags, detached HEAD, force push, bisect, git clean
      FGit Security for Contributors.gitignore deep dive, env variables, pre-commit hooks, secrets recovery, push protection
      +

      VS Code and Copilot (G-L)

      + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + +
      AppendixDocumentWhat It Covers
      GVS Code Accessibility ReferenceAll accessibility settings, audio signals, diff viewer, screen reader configs
      HGitHub DesktopVisual Git client - clone, branch, stage, commit, push, cherry-pick, conflict resolution
      IGitHub CLI ReferenceInstalling, auth, repos, issues, PRs, releases, search, aliases, extensions, Copilot CLI
      JCloud Editors (Codespaces and github.dev)Cloud development environments, accessibility setup, screen reader usage
      KCopilot ReferenceFeatures, chat participants, slash commands, MCP servers, model comparison
      LAccessibility Agents Reference55 agents, 3 teams, 5 platforms, slash commands, workspace configuration
      +

      GitHub Platform (M-S)

      + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + +
      AppendixDocumentWhat It Covers
      MAccessibility Standards ReferenceWCAG 2.2, ARIA roles and patterns, PR accessibility checklist
      NAdvanced SearchComplete query language reference for issues, PRs, code, and repos
      OBranch Protection and RulesetsRequired reviews, status checks, diagnosing blocked PRs
      PSecurity FeaturesDependabot, secret scanning, code scanning, private advisories
      QGitHub Actions and WorkflowsAutomation, CI/CD, agentic workflows
      RGitHub Projects Deep DiveBoards, tables, roadmaps, custom fields, cross-repo projects
      SReleases, Tags, and InsightsVersioned releases, semver, pulse, contributors, traffic
      +

      Community and Continuing (T-Z)

      + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + +
      AppendixDocumentWhat It Covers
      TCommunity and SocialProfiles, sponsors, wikis, organizations, templates, stars, following, topics
      UDiscussions and GistsForum-style conversations, Q&A, polls, code snippets, sharing
      VGitHub MobileVoiceOver and TalkBack guide for iOS and Android
      WPublishing with GitHub PagesDeploy a static site from your repository
      XResourcesEvery link, tool, and reference from this event
      YAccessing Workshop MaterialsHow to download, read offline, and keep updated
      ZGitHub Skills - Complete Course CatalogAll 36 modules in six learning paths with links and prerequisites
      +

      Exercises at a Glance

      +

      The workshop includes structured exercises across the curriculum. Every exercise is designed to be completed in 1-5 minutes, is impossible to fail, and follows the same pattern: Try It -> You're done when -> What success feels like.

      +
      +

      Note: Exercise details will be updated as chapter content is finalized in Phases 2-5. The exercises below reflect the new chapter numbers.

      +
      + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + +
      ChapterExerciseWhat You Do
      Ch 0260-Second OrientationPress 1, D, 2, H on a repo page - prove you can navigate by ear
      Ch 03Five-Tab TourVisit Code, Issues, PRs, file finder, and README on a real repo
      Ch 04Individual ChallengesProgressive challenges in the Learning Room
      Ch 04Group ChallengesCollaborative exercises in the Learning Room
      Ch 05File Your First IssueCreate an introduction issue in the Learning Room
      Ch 06Read a Real PRNavigate a PR's description, conversation, and diff
      Ch 07Read a ConflictRead merge conflict markers and identify both versions
      Ch 08Rewrite One CommentTransform a dismissive review comment into constructive feedback
      Ch 09Label and LinkAdd a label to an issue and create a cross-reference
      Ch 10Tame Your InboxMark a notification as done and configure watch settings
      Ch 14Clone, Branch, CommitComplete the full Git cycle: clone, branch, edit, stage, commit, push
      Ch 15Review a PR from VS CodeOpen a diff, use Accessible Diff Viewer (F7), leave a comment
      Ch 16First Copilot ConversationAsk Copilot Chat a question about your repo and read the response
      Ch 17Use an Issue TemplateUse an existing issue template in Accessibility Agents
      Ch 17Create a TemplateCreate an accessibility bug report template locally
      Ch 17Submit UpstreamSubmit your template upstream via a real PR
      Ch 19Agent ExercisesGenerate, extend, and iterate with accessibility agents
      Ch 20CapstoneDesign, build, and contribute an accessibility agent
      +

      Getting Help

      +

      If you get stuck at any point during the workshop, these resources are always available:

      + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + +
      ResourceWhat It IsWhen to Use It
      FAQAnswers to common questionsWhen you have a question about the workshop, GitHub, or screen readers
      TroubleshootingStep-by-step solutions to common problemsWhen something is not working
      Quick ReferenceCondensed shortcuts and commandsWhen you need a keyboard shortcut or command fast
      GlossaryTerm definitionsWhen you encounter an unfamiliar word
      Screen Reader Cheat SheetNavigation commandsWhen you need a screen reader shortcut
      ResourcesExternal links and documentationWhen you want to learn more about a topic
      +

      Still stuck? Open a support issue at https://github.com/Community-Access/support/issues describing what you tried, what happened, and what you expected. Include your screen reader and operating system.

      +

      Workshop at a Glance

      + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + +
      AspectDay 1Day 2
      FocusGitHub web interfaceVS Code + Accessibility Agents
      ToolsBrowser, screen readerVS Code, Copilot, Accessibility Agents
      Chapters00-10 (11 chapters)11-21 (11 chapters)
      SkillsNavigate, Issue, PR, Review, MergeGit, Copilot, Agents, Fork, Capstone
      OutcomeYou can use GitHub independentlyYou have a real contribution path and review process
      Time~8 hours~10 hours
      +

      Ready to begin? Start with Chapter 00: Pre-Workshop Setup.

      +

      Last updated: May 2026

      + +
      + + + + diff --git a/html/admin/qa-bundle/docs/get-going.html b/html/admin/qa-bundle/docs/get-going.html new file mode 100644 index 00000000..6eba071d --- /dev/null +++ b/html/admin/qa-bundle/docs/get-going.html @@ -0,0 +1,181 @@ + + + + + + + Get Going with GitHub - GIT Going with GitHub + + + + + + + + +
      +

      Get Going with GitHub

      +
      +

      Start here if you are new, unsure, or joining from a workshop link. This guide walks you from "I have the link" to "I know where I am, what to do next, and how to ask for help." You do not need to know Git, GitHub, VS Code, or the command line before you begin.

      +
      +

      What This Guide Does

      +

      This workshop is designed so you are never left guessing what comes next. You will have:

      +
        +
      • A GitHub Classroom assignment link from the facilitator
        • +
      • Your own private Learning Room repository
        • +
      • Challenge issues that tell you exactly what to do
        • +
      • Evidence prompts that tell you what to post when you finish
        • +
      • Aria bot feedback on pull requests
        • +
      • Reference solutions you can compare against after you try
        • +
      • Multiple tool paths, so you can work in the browser, VS Code, GitHub Desktop, or the command line when appropriate
        • +
      +

      The goal is not to rush. The goal is to build confidence one checkable step at a time.

      +

      Step 1 - Know Your Starting Place

      +

      Before Day 1 starts, complete Chapter 00: Pre-Workshop Setup. That chapter helps you create or verify your GitHub account, configure accessibility settings, choose a browser, install Git and VS Code, and confirm your screen reader setup.

      +

      If you cannot finish every setup step before the workshop, tell a facilitator early. Setup problems are normal, and the workshop is designed with time and support for recovery.

      +

      Step 2 - Accept the GitHub Classroom Assignment

      +

      At the start of Day 1, the facilitator gives you a GitHub Classroom assignment link. It usually starts with https://classroom.github.com/a/.

      +
        +
      1. Open the assignment link in the browser where you are signed in to GitHub.
        2. +
      2. If GitHub asks you to authorize GitHub Classroom, activate Authorize GitHub Classroom.
        3. +
      3. If you are asked to choose your name from a roster, find your name and select it. If your name is missing, use the skip option and tell the facilitator.
        4. +
      4. Activate Accept this assignment.
        5. +
      5. Wait while GitHub Classroom creates your private repository.
        6. +
      6. Refresh the page until the repository link appears.
        7. +
      7. Open the repository link and bookmark it.
        8. +
      +

      Your repository name usually looks like learning-room-your-username. This is your personal practice space for the workshop.

      +

      Step 3 - Understand the Learning Room

      +

      The Learning Room is a private repository created from a template. Everyone starts from the same materials, but your work belongs to you.

      +

      You can safely practice there because:

      +
        +
      • You have your own issues, branches, commits, and pull requests
        • +
      • Other students do not see your work unless the facilitator intentionally pairs you
        • +
      • Mistakes are expected and recoverable
        • +
      • Bot feedback is educational, not punitive
        • +
      • Challenge issues unlock in sequence so you always know the next step
        • +
      +

      Think of the Learning Room as a guided practice studio. It is real GitHub, but the room is set up so you can learn without fear of damaging a public project.

      +

      Step 4 - Find Challenge 1

      +

      After your Learning Room repository is created, the Student Progression Bot creates your first challenge issue.

      +
        +
      1. Open your Learning Room repository.
        2. +
      2. Navigate to the Issues tab. On GitHub, the keyboard shortcut is G then I.
        3. +
      3. Find an issue titled Challenge 1: Find Your Way Around.
        4. +
      4. Open the issue and read the body from top to bottom.
        5. +
      5. Follow the checklist in the issue.
        6. +
      6. Post your evidence in the evidence field or as the requested comment.
        7. +
      7. Close the challenge issue when the instructions tell you to close it.
        8. +
      +

      When you close a challenge issue, the next challenge opens. You do not need to hunt through the whole curriculum to know what is next.

      +

      Step 5 - Choose the Tool That Fits the Moment

      +

      There is no single correct way to use GitHub. The workshop teaches the workflow first, then offers tool paths.

      +

      Use this plain-language guide to decide where to start:

      +
        +
      • GitHub.com in the browser: Best for Day 1, issues, pull requests, repository navigation, and reviews.
        • +
      • github.dev: Best when you want a VS Code-style editor in the browser without installing anything. Press the period key from many repository pages to open it.
        • +
      • VS Code desktop: Best for Day 2, local Git, Copilot, extensions, and deeper editing work.
        • +
      • GitHub Desktop: Best if you want a desktop Git workflow without typing Git commands.
        • +
      • GitHub CLI: Best if you prefer terminal workflows or want automation later.
        • +
      +

      You are not behind if you use one tool longer than someone else. The important skill is understanding the contribution workflow: issue, branch, change, commit, pull request, review, and merge.

      +

      Step 6 - What to Listen For with a Screen Reader

      +

      When you feel lost, listen for structure before you take action.

      +

      Useful signals include:

      +
        +
      • Page title
        • +
      • Repository name heading
        • +
      • Landmark names such as main content or repository navigation
        • +
      • Tab names such as Code, Issues, and Pull requests
        • +
      • Issue title
        • +
      • Pull request title
        • +
      • Branch name
        • +
      • Button name
        • +
      • Field label
        • +
      • Bot comment or check result
        • +
      +

      If you are not sure where you are, pause and navigate by headings or landmarks. Finding your position is part of the workflow, not a failure.

      +

      Step 7 - Use the Support Built into the Course

      +

      You have several safety nets.

      +
        +
      • Every challenge issue includes instructions and evidence prompts.
        • +
      • Every chapter has an If You Get Stuck section.
        • +
      • Every challenge has a reference solution in the solutions folder.
        • +
      • Aria posts feedback on pull requests.
        • +
      • The Student Progression Bot opens the next challenge when you finish the current one.
        • +
      • Facilitators and peers are part of the learning system.
        • +
      +

      If something does not work, do not start over silently. Read the latest bot message, check the challenge issue, and ask for help with the link to the page where you are stuck.

      +

      Step 8 - Your First Success Check

      +

      You are ready to continue when you can say these four things:

      +
        +
      1. I can open my Learning Room repository.
        2. +
      2. I can find the Issues tab.
        3. +
      3. I can open Challenge 1.
        4. +
      4. I know where to post my evidence and how to ask for help.
        5. +
      +

      That is enough. You do not need to understand every GitHub feature before you begin. The workshop will guide you one step at a time.

      +

      Where to Go Next

      +

      Use this order if you want the gentlest path:

      +
        +
      1. Chapter 00: Pre-Workshop Setup
        2. +
      2. Chapter 01: Choose Your Tools
        3. +
      3. Chapter 02: Understanding GitHub
        4. +
      4. Chapter 03: Navigating Repositories
        5. +
      5. Chapter 04: The Learning Room
        6. +
      6. Your Challenge 1: Find Your Way Around issue in your Learning Room repository
        7. +
      +

      You belong here. We will keep the path explicit, and we will keep giving you the next step.

      + +
      + + + + diff --git a/html/admin/qa-bundle/docs/solutions/solution-01-scavenger-hunt.html b/html/admin/qa-bundle/docs/solutions/solution-01-scavenger-hunt.html new file mode 100644 index 00000000..ddd33617 --- /dev/null +++ b/html/admin/qa-bundle/docs/solutions/solution-01-scavenger-hunt.html @@ -0,0 +1,101 @@ + + + + + + + Solution Reference: Challenge 1 -- Find Your Way Around - GIT Going with GitHub + + + + + + + + +
      +

      Solution Reference: Challenge 1 -- Find Your Way Around

      +

      This is one way the scavenger hunt could look. Your exact findings will vary depending on when you completed the challenge. If you found the key elements, you succeeded.

      +

      Expected findings

      +

      Code tab

      +
        +
      • The root of the repository contains files like README.md, docs/, and .github/
        • +
      • The file count varies as the repository evolves -- any reasonable count is correct
        • +
      +

      Issues tab

      +
        +
      • You should have found at least one open issue
        • +
      • If no issues were open, noting that the tab exists is sufficient
        • +
      +

      docs/welcome.md

      +
        +
      • The first paragraph introduces the learning room and what students will do
        • +
      • You may have noticed TODO comments -- those are intentionally left for Challenge 2
        • +
      +

      Repository description and README

      +
        +
      • The description appears at the top of the Code tab, below the repository name
        • +
      • The README renders automatically below the file list
        • +
      +

      Alternate approaches

      +
        +
      • github.com: Click each tab in the top navigation bar
        • +
      • github.dev: Press . on any repo page to open the web editor, then use the Explorer sidebar
        • +
      • VS Code with GitHub extension: Use the GitHub Repositories extension to browse remotely
        • +
      • GitHub CLI: gh repo view Community-Access/git-going-with-github --web opens the repo in a browser
        • +
      +

      What matters

      +

      The learning objective is familiarity with repository navigation, not memorizing exact file counts. If you explored the tabs and found the key files, you completed this challenge.

      + +
      + + + + diff --git a/html/admin/qa-bundle/docs/solutions/solution-02-first-issue.html b/html/admin/qa-bundle/docs/solutions/solution-02-first-issue.html new file mode 100644 index 00000000..f704e392 --- /dev/null +++ b/html/admin/qa-bundle/docs/solutions/solution-02-first-issue.html @@ -0,0 +1,98 @@ + + + + + + + Solution Reference: Challenge 2 -- File Your First Issue - GIT Going with GitHub + + + + + + + + +
      +

      Solution Reference: Challenge 2 -- File Your First Issue

      +

      This shows two example issues. Yours will look different and that is fine.

      +

      Example 1: Bug report style

      +

      Title: TODO in welcome.md: missing workshop schedule link

      +

      Body:

      +
      +

      In docs/welcome.md, line 15, there is a TODO comment that says "add link to workshop schedule." This placeholder should be replaced with an actual link so students can find the schedule.

      +

      Steps to find it:

      +
        +
      1. Open docs/welcome.md
        2. +
      2. Search for "TODO"
        3. +
      3. The comment is on line 15
        4. +
      +
      +

      Example 2: Feature request style

      +

      Title: Add accessibility tips section to welcome.md

      +

      Body:

      +
      +

      The welcome document covers what students will do but does not mention accessibility features. A short section pointing students to screen reader shortcuts and keyboard navigation would help everyone start on equal footing.

      +

      Suggested location: After the "What you will learn" section.

      +
      +

      What makes a good issue

      +
        +
      • Clear title: Someone scanning the issue list can understand the topic without opening it
        • +
      • Enough context: Another person could find and understand the problem from your description alone
        • +
      • Reproducible location: File name and line number (if relevant) so the fix is easy to find
        • +
      +

      Alternate approaches

      +

      Both bug reports and feature suggestions are valid for this challenge. The key is writing clearly enough that a stranger could act on your issue.

      + +
      + + + + diff --git a/html/admin/qa-bundle/docs/solutions/solution-03-conversation.html b/html/admin/qa-bundle/docs/solutions/solution-03-conversation.html new file mode 100644 index 00000000..5eb87046 --- /dev/null +++ b/html/admin/qa-bundle/docs/solutions/solution-03-conversation.html @@ -0,0 +1,96 @@ + + + + + + + Solution Reference: Challenge 3 -- Join the Conversation - GIT Going with GitHub + + + + + + + + +
      +

      Solution Reference: Challenge 3 -- Join the Conversation

      +

      This shows an example comment thread. Your conversation will be different.

      +

      Example exchange

      +

      Your comment (on a buddy's issue)

      +
      +

      Good catch on the missing link in welcome.md! I found the same TODO on line 15.

      +

      @maria-student Have you also noticed the TODO on line 28? That one mentions a "resources" section that does not exist yet. We could address both in the same PR.

      +
      +

      Buddy's reply

      +
      +

      @your-username Thanks for pointing that out! I had not scrolled that far. Let me update my issue description to cover both TODOs.

      +
      +

      What makes a good comment

      +
        +
      • Specific reference: Mention what you are responding to (line numbers, file names)
        • +
      • Constructive tone: Add information or ask questions rather than just agreeing
        • +
      • @mention: Tag the person you are talking to so they get notified
        • +
      • Actionable: Your comment helps move the conversation forward
        • +
      +

      Alternate approaches

      +
        +
      • Comment on an issue someone else filed
        • +
      • Reply to a comment on your own issue
        • +
      • Ask a clarifying question about someone else's proposed change
        • +
      +

      What matters

      +

      The learning objective is participating in asynchronous collaboration. A single thoughtful comment with an @mention is sufficient evidence.

      + +
      + + + + diff --git a/html/admin/qa-bundle/docs/solutions/solution-04-branch-out.html b/html/admin/qa-bundle/docs/solutions/solution-04-branch-out.html new file mode 100644 index 00000000..fbdac7ea --- /dev/null +++ b/html/admin/qa-bundle/docs/solutions/solution-04-branch-out.html @@ -0,0 +1,103 @@ + + + + + + + Solution Reference: Challenge 4 -- Branch Out - GIT Going with GitHub + + + + + + + + +
      +

      Solution Reference: Challenge 4 -- Branch Out

      +

      This shows how to create a branch from each tool. You only needed to use one.

      +

      On github.com

      +
        +
      1. Go to the repository's Code tab
        2. +
      2. Click the branch dropdown (it says "main")
        3. +
      3. Type a new branch name like fix/welcome-todo
        4. +
      4. Click "Create branch: fix/welcome-todo from main"
        5. +
      +

      The branch now exists on GitHub. You can switch to it using the same dropdown.

      +

      In VS Code (with Git)

      +
      git checkout -b fix/welcome-todo
      +

      Or use the Source Control sidebar: click the branch name in the bottom-left status bar, then select "Create new branch."

      +

      In GitHub Desktop

      +
        +
      1. Click the Current Branch dropdown
        2. +
      2. Click "New Branch"
        3. +
      3. Enter the name fix/welcome-todo
        4. +
      4. Confirm it is based on main
        5. +
      +

      With GitHub CLI

      +
      gh repo clone <workshop-org>/learning-room-<your-username>
+cd learning-room
+git checkout -b fix/welcome-todo
      +

      Branch naming

      +

      Good branch names are short and descriptive:

      +
        +
      • fix/welcome-todo -- fixing a TODO in welcome.md
        • +
      • feature/add-schedule-link -- adding a new link
        • +
      • docs/update-readme -- documentation change
        • +
      +

      All of these are valid. The convention type/description is common but not required.

      +

      What matters

      +

      The learning objective is understanding that branches let you work in isolation without affecting main. If you created any branch with any name, you completed this challenge.

      + +
      + + + + diff --git a/html/admin/qa-bundle/docs/solutions/solution-05-make-your-mark.html b/html/admin/qa-bundle/docs/solutions/solution-05-make-your-mark.html new file mode 100644 index 00000000..b352af8b --- /dev/null +++ b/html/admin/qa-bundle/docs/solutions/solution-05-make-your-mark.html @@ -0,0 +1,101 @@ + + + + + + + Solution Reference: Challenge 5 -- Make Your Mark - GIT Going with GitHub + + + + + + + + +
      +

      Solution Reference: Challenge 5 -- Make Your Mark

      +

      This shows an example edit and commit. Your changes will be different.

      +

      Example edit

      +

      File: docs/welcome.md

      +

      Before (line 15):

      +
      <!-- TODO: add link to workshop schedule -->
      +

      After:

      +
      See the [workshop schedule](https://github.com/Community-Access/git-going-with-github/blob/main/admin/DAY1_AGENDA.md) for session times.
      +

      Example commit message

      +
      docs: replace TODO with workshop schedule link
+
+Resolves the placeholder on line 15 of welcome.md by adding
+a link to the schedule file.
      +

      What makes a good commit message

      +
        +
      • First line: Short summary (50 characters or less is ideal), starts with the type of change
        • +
      • Blank line: Separates summary from body
        • +
      • Body (optional): Explains what changed and why
        • +
      +

      Simpler alternatives that are also fine

      +
      Fix TODO in welcome.md
      +
      Add schedule link to welcome page
      +

      Both are clear and descriptive. The more structured format is a convention, not a requirement.

      +

      Alternate approaches

      +
        +
      • github.com: Click the pencil icon on the file, make the edit, fill in the commit message at the bottom
        • +
      • github.dev: Press . to open the editor, edit the file, use the Source Control sidebar to commit
        • +
      • VS Code: Edit locally, stage with git add, commit with git commit
        • +
      • GitHub Desktop: Edit in your preferred editor, return to Desktop, write the message, click Commit
        • +
      +

      What matters

      +

      The learning objective is making a meaningful change and describing it in a commit message. Any clear edit with any descriptive message is a success.

      + +
      + + + + diff --git a/html/admin/qa-bundle/docs/solutions/solution-06-first-pr.html b/html/admin/qa-bundle/docs/solutions/solution-06-first-pr.html new file mode 100644 index 00000000..1fa7bd1b --- /dev/null +++ b/html/admin/qa-bundle/docs/solutions/solution-06-first-pr.html @@ -0,0 +1,110 @@ + + + + + + + Solution Reference: Challenge 6 -- Your First Pull Request - GIT Going with GitHub + + + + + + + + +
      +

      Solution Reference: Challenge 6 -- Your First Pull Request

      +

      This shows what a complete pull request looks like.

      +

      Example PR

      +

      Title: Fix TODO: add workshop schedule link to welcome.md

      +

      Body:

      +
      ## What this changes
+
+Replaces the TODO placeholder on line 15 of `docs/welcome.md` with an actual
+link to the workshop schedule.
+
+## Why
+
+Students need a working link to find session times. The TODO was a known gap
+filed in issue #3.
+
+Closes #3
      +

      Key elements

      +

      Title

      +
        +
      • Describes the change clearly: someone reading just the title understands what happened
        • +
      • Short enough to scan in a list
        • +
      +

      Body

      +
        +
      • What: Summarizes the change
        • +
      • Why: Explains the motivation
        • +
      • Closes #N: Links to the issue this PR resolves -- GitHub automatically closes the issue when the PR merges
        • +
      +

      Linked issue

      +

      The Closes #3 line creates a two-way link. The issue shows "referenced by PR #5" and the PR shows "Closes #3." When the PR merges, issue #3 closes automatically.

      +

      Passing checks

      +

      If the repository has automated checks (the PR validation bot), a green checkmark appears. If checks fail, read the bot's feedback comment for specific guidance.

      +

      Alternate linking syntax

      +

      All of these work identically:

      +
        +
      • Closes #3
        • +
      • Fixes #3
        • +
      • Resolves #3
        • +
      +

      What matters

      +

      The learning objective is connecting a change (PR) to a reason (issue) through GitHub's linking system. If your PR has a clear title, a description, and references an issue number, you completed this challenge.

      + +
      + + + + diff --git a/html/admin/qa-bundle/docs/solutions/solution-07-merge-conflict.html b/html/admin/qa-bundle/docs/solutions/solution-07-merge-conflict.html new file mode 100644 index 00000000..b585e3ad --- /dev/null +++ b/html/admin/qa-bundle/docs/solutions/solution-07-merge-conflict.html @@ -0,0 +1,118 @@ + + + + + + + Solution Reference: Challenge 7 -- Resolve a Merge Conflict - GIT Going with GitHub + + + + + + + + +
      +

      Solution Reference: Challenge 7 -- Resolve a Merge Conflict

      +

      This shows what conflict markers look like and how to resolve them.

      +

      What conflict markers look like

      +

      When Git cannot automatically merge two changes to the same lines, it inserts markers:

      +
      <<<<<<< HEAD
+Welcome to the Learning Room! This is the main branch version.
+=======
+Welcome to the Learning Room! This is my improved version with more detail.
+>>>>>>> fix/welcome-update
      +

      The three sections

      +
        +
      • Between <<<<<<< HEAD and =======: The version on the branch you are merging INTO (usually main)
        • +
      • Between ======= and >>>>>>>: The version on YOUR branch
        • +
      • The marker lines themselves: Must be deleted -- they are not content
        • +
      +

      Example resolution

      +

      Before (with conflict markers):

      +
      <<<<<<< HEAD
+Welcome to the Learning Room! This is the main branch version.
+=======
+Welcome to the Learning Room! This is my improved version with more detail.
+>>>>>>> fix/welcome-update
      +

      After (resolved):

      +
      Welcome to the Learning Room! This is my improved version with more detail.
      +

      Decision process

      +

      You chose one of three options:

      +
        +
      1. Keep yours: Delete the HEAD section and all markers, keep your changes
        2. +
      2. Keep theirs: Delete your section and all markers, keep the HEAD version
        3. +
      3. Combine both: Write new text that incorporates ideas from both versions, delete all markers
        4. +
      +

      All three are valid. The choice depends on which version is better for the project.

      +

      On github.com

      +

      GitHub offers a conflict editor directly in the browser:

      +
        +
      1. Click "Resolve conflicts" on the PR page
        2. +
      2. The editor highlights conflicting sections
        3. +
      3. Edit the file to remove markers and keep the content you want
        4. +
      4. Click "Mark as resolved" then "Commit merge"
        5. +
      +

      In VS Code

      +

      VS Code highlights conflicts and offers clickable options above each conflict:

      +
        +
      • "Accept Current Change" (HEAD version)
        • +
      • "Accept Incoming Change" (your version)
        • +
      • "Accept Both Changes" (keeps both, you edit after)
        • +
      +

      What matters

      +

      The learning objective is understanding that conflicts are normal and resolvable. If you removed all conflict markers and the file makes sense, you completed this challenge.

      + +
      + + + + diff --git a/html/admin/qa-bundle/docs/solutions/solution-08-culture.html b/html/admin/qa-bundle/docs/solutions/solution-08-culture.html new file mode 100644 index 00000000..7849b026 --- /dev/null +++ b/html/admin/qa-bundle/docs/solutions/solution-08-culture.html @@ -0,0 +1,92 @@ + + + + + + + Solution Reference: Challenge 8 -- Open Source Culture - GIT Going with GitHub + + + + + + + + +
      +

      Solution Reference: Challenge 8 -- Open Source Culture

      +

      This shows example reflection and triage output. Your response will be personal and different.

      +

      Example reflection comment

      +
      +

      Reading the CODE_OF_CONDUCT.md and CONTRIBUTING.md files helped me understand that open source projects are communities, not just code. The contributing guide made it clear that you do not need to be an expert to participate -- filing a good issue is a contribution.

      +

      One thing I had not considered: accessibility is not just about the product. The way we write issues, name branches, and structure documentation affects whether people with disabilities can participate in the development process itself.

      +
      +

      Example triage recommendation

      +

      If your challenge asked you to evaluate an issue and recommend a label:

      +
      +

      Issue: "The welcome page loads slowly on mobile"

      +

      Recommended label: bug

      +

      Justification: This describes unexpected behavior (slow loading) that affects the user experience. It is not a feature request because the page is supposed to load quickly. The bug label helps maintainers prioritize fixes.

      +

      Additional label suggestion: accessibility -- slow loading disproportionately affects users on assistive technology where each reload is more disruptive.

      +
      +

      Alternate approaches

      +
        +
      • Focus on CODE_OF_CONDUCT.md and what it means for inclusive collaboration
        • +
      • Focus on CONTRIBUTING.md and what you learned about the contribution process
        • +
      • Compare this project's guidelines to another open source project you have seen
        • +
      +

      What matters

      +

      The learning objective is understanding that open source has cultural norms, not just technical ones. Any thoughtful reflection that shows engagement with the governance and contribution documents is a success.

      + +
      + + + + diff --git a/html/admin/qa-bundle/docs/solutions/solution-09-merge-day.html b/html/admin/qa-bundle/docs/solutions/solution-09-merge-day.html new file mode 100644 index 00000000..9cde86dc --- /dev/null +++ b/html/admin/qa-bundle/docs/solutions/solution-09-merge-day.html @@ -0,0 +1,101 @@ + + + + + + + Solution Reference: Challenge 9 -- Merge Day - GIT Going with GitHub + + + + + + + + +
      +

      Solution Reference: Challenge 9 -- Merge Day

      +

      This shows what a successful Day 1 completion looks like.

      +

      What happens at merge

      +

      When your PR from Challenge 6 (or a later challenge) is approved and merged:

      +
        +
      1. The "Merge pull request" button turns green
        2. +
      2. After clicking it, your branch's commits appear on main
        3. +
      3. The linked issue (from Closes #N) automatically closes
        4. +
      4. The PR status changes to "Merged" with a purple icon
        5. +
      +

      Example evidence

      +

      Your Day 1 recap evidence might include:

      +
      +

      What I merged: PR #5 which fixed the TODO in welcome.md (linked to issue #3)

      +

      What I learned today:

      +
        +
      • Repositories have a navigable structure with tabs for code, issues, and PRs
        • +
      • Issues document problems; PRs propose solutions
        • +
      • Branches let you work without affecting main
        • +
      • Merge conflicts happen when two people change the same lines -- they are normal and fixable
        • +
      • Open source projects have community guidelines that shape how people collaborate
        • +
      +

      What surprised me: How much of open source is communication (issues, PR descriptions, comments) rather than just writing code.

      +
      +

      Alternate approaches

      +
        +
      • Post your recap as a comment on your challenge issue
        • +
      • Share a summary in the workshop discussion channel
        • +
      • Write a short reflection in a new file on your branch
        • +
      +

      What matters

      +

      The learning objective is completing the Day 1 loop: issue to branch to commit to PR to merge. If you merged at least one PR and can articulate what you learned, you completed this challenge.

      + +
      + + + + diff --git a/html/admin/qa-bundle/docs/solutions/solution-10-go-local.html b/html/admin/qa-bundle/docs/solutions/solution-10-go-local.html new file mode 100644 index 00000000..6f18600c --- /dev/null +++ b/html/admin/qa-bundle/docs/solutions/solution-10-go-local.html @@ -0,0 +1,119 @@ + + + + + + + Solution Reference: Challenge 10 -- Go Local - GIT Going with GitHub + + + + + + + + +
      +

      Solution Reference: Challenge 10 -- Go Local

      +

      This shows the local Git workflow from clone through push.

      +

      Terminal/CLI approach

      +
      # Clone the repository
+git clone https://github.com/<workshop-org>/learning-room-<your-username>.git
+cd learning-room
+
+# Create a branch
+git checkout -b fix/local-edit
+
+# Make an edit (any text editor works)
+# For example, fix a typo or add content to docs/welcome.md
+
+# Stage the change
+git add docs/welcome.md
+
+# Commit with a descriptive message
+git commit -m "docs: fix typo in welcome page"
+
+# Push the branch to GitHub
+git push -u origin fix/local-edit
      +

      VS Code approach

      +
        +
      1. Open the Command Palette (Ctrl+Shift+P or Cmd+Shift+P)
        2. +
      2. Run "Git: Clone" and paste the repository URL
        3. +
      3. Open the cloned folder
        4. +
      4. Click the branch name in the bottom-left status bar, create a new branch
        5. +
      5. Edit a file
        6. +
      6. Open the Source Control sidebar (Ctrl+Shift+G)
        7. +
      7. Stage changes with the + icon, type a commit message, click the checkmark
        8. +
      8. Click "Publish Branch" or use the sync button
        9. +
      +

      GitHub Desktop approach

      +
        +
      1. File, Clone Repository, paste the URL
        2. +
      2. Current Branch dropdown, New Branch
        3. +
      3. Open the file in your editor and make a change
        4. +
      4. Return to GitHub Desktop -- it shows the diff
        5. +
      5. Write a commit message at the bottom-left, click "Commit"
        6. +
      6. Click "Publish branch" to push
        7. +
      +

      Verifying success

      +

      After pushing, go to github.com and you should see:

      +
        +
      • A banner saying "fix/local-edit had recent pushes" with a "Compare & pull request" button
        • +
      • Your branch in the branch dropdown
        • +
      • Your commit in the branch's commit history
        • +
      +

      What matters

      +

      The learning objective is executing the full local workflow: clone, branch, edit, commit, push. The specific change you made does not matter. If your branch appeared on GitHub with your commit, you succeeded.

      + +
      + + + + diff --git a/html/admin/qa-bundle/docs/solutions/solution-11-day2-pr.html b/html/admin/qa-bundle/docs/solutions/solution-11-day2-pr.html new file mode 100644 index 00000000..97a9b339 --- /dev/null +++ b/html/admin/qa-bundle/docs/solutions/solution-11-day2-pr.html @@ -0,0 +1,125 @@ + + + + + + + Solution Reference: Challenge 11 -- Day 2 Pull Request - GIT Going with GitHub + + + + + + + + +
      +

      Solution Reference: Challenge 11 -- Day 2 Pull Request

      +

      This shows a PR created from a locally-pushed branch.

      +

      Example PR

      +

      Title: docs: improve welcome page formatting and fix broken link

      +

      Body:

      +
      ## Changes
+
+- Fixed the broken link to the schedule on line 22
+- Added a "Getting Help" section after the introduction
+- Cleaned up inconsistent heading levels
+
+## How I made these changes
+
+I cloned the repo locally (Challenge 10), created a branch called
+`fix/welcome-improvements`, made the edits in VS Code, committed,
+and pushed. This PR is the result.
+
+Closes #8
+
+## Pattern recognition
+
+Compared to my Day 1 PR (Challenge 6), this one:
+- Started from a local clone instead of the GitHub web editor
+- Had multiple commits instead of just one
+- Required a `git push` step that Day 1 did not need
      +

      What is different from Day 1

      + + + + + + + + + + + + + + + + + + + + + + + + + + + +
      Day 1 PR (Challenge 6)Day 2 PR (Challenge 11)
      Edited on github.com or github.devEdited locally in VS Code, Desktop, or terminal
      Single commit created through the web UIOne or more commits created with git commit
      Branch created on GitHubBranch created locally with git checkout -b
      No push needed (already on GitHub)Required git push to send branch to GitHub
      PR created from the web promptPR created from the web prompt or gh pr create
      +

      What matters

      +

      The learning objective is recognizing the similarities and differences between web-based and local Git workflows. Both end with a PR. If you created a PR from a locally-pushed branch and noted what changed compared to Day 1, you completed this challenge.

      + +
      + + + + diff --git a/html/admin/qa-bundle/docs/solutions/solution-12-review.html b/html/admin/qa-bundle/docs/solutions/solution-12-review.html new file mode 100644 index 00000000..b6ab9115 --- /dev/null +++ b/html/admin/qa-bundle/docs/solutions/solution-12-review.html @@ -0,0 +1,99 @@ + + + + + + + Solution Reference: Challenge 12 -- Code Review - GIT Going with GitHub + + + + + + + + +
      +

      Solution Reference: Challenge 12 -- Code Review

      +

      This shows what a complete code review looks like.

      +

      Example review on a buddy's PR

      +

      Inline comment (on a specific line)

      +
      +

      Line 18 of docs/welcome.md:

      +

      This heading says "## getting started" but the other headings in the file use title case ("## What You Will Learn"). Consider changing it to "## Getting Started" for consistency.

      +
      +

      Suggestion (using GitHub's suggestion feature)

      +
      ## Getting Started
      +

      Using the suggestion feature lets the PR author accept the change with one click, which creates a commit automatically.

      +

      Review verdict

      +
      +

      Changes requested

      +

      Good work overall. The content additions are helpful and well-written. Two things to address before merging:

      +
        +
      1. Heading capitalization inconsistency (see inline comment on line 18)
        2. +
      2. The new link on line 25 points to http:// instead of https:// -- please update for security
        3. +
      +

      Once those are fixed, this is ready to merge.

      +
      +

      Types of review comments

      +
        +
      • Praise: "This section reads really clearly" -- positive feedback encourages good practices
        • +
      • Question: "What happens if the user does not have a GitHub account yet?" -- surfaces assumptions
        • +
      • Suggestion: Use the suggestion block to propose specific text changes
        • +
      • Required change: "The YAML frontmatter is missing the description field, which is required"
        • +
      +

      What matters

      +

      The learning objective is providing constructive feedback on someone else's work. If you left at least one specific, helpful comment on a buddy's PR, you completed this challenge. The quality of feedback matters more than the quantity.

      + +
      + + + + diff --git a/html/admin/qa-bundle/docs/solutions/solution-13-copilot.html b/html/admin/qa-bundle/docs/solutions/solution-13-copilot.html new file mode 100644 index 00000000..0785edb0 --- /dev/null +++ b/html/admin/qa-bundle/docs/solutions/solution-13-copilot.html @@ -0,0 +1,100 @@ + + + + + + + Solution Reference: Challenge 13 -- Copilot as Collaborator - GIT Going with GitHub + + + + + + + + +
      +

      Solution Reference: Challenge 13 -- Copilot as Collaborator

      +

      This shows an example Copilot interaction and critical evaluation.

      +

      Example interaction transcript

      +

      Prompt to Copilot:

      +
      +

      Review the alt text in docs/welcome.md and suggest improvements for screen reader users.

      +
      +

      Copilot response (example):

      +
      +

      The image on line 42 has alt="screenshot" which is not descriptive. A better alternative would be: alt="Learning Room repository page showing the Code tab with a list of files including README.md, docs folder, and .github folder".

      +
      +

      Before and after

      +

      Before:

      +
      ![screenshot](images/repo-overview.png)
      +

      After (improved with Copilot's help):

      +
      ![Learning Room repository Code tab showing file list with README.md, docs folder, and .github folder](images/repo-overview.png)
      +

      Critical evaluation notes

      +

      Not everything Copilot suggests is correct. Here is how to evaluate:

      +
      +

      What Copilot got right: The suggestion to be more descriptive than "screenshot" is correct. Screen reader users need to understand what the image communicates, not just that it exists.

      +

      What I adjusted: Copilot's suggested alt text was 30 words. I shortened it to 18 words while keeping the key information. Alt text should be concise.

      +

      What Copilot missed: It did not flag that the image might be decorative (meaning alt="" would be appropriate). I checked -- it is informational, so descriptive alt text is correct.

      +
      +

      Alternate approaches

      +
        +
      • Ask Copilot to improve documentation clarity, then evaluate whether the suggestions make sense
        • +
      • Ask Copilot to check Markdown formatting, then verify its corrections
        • +
      • Ask Copilot to suggest commit messages, then refine them
        • +
      +

      What matters

      +

      The learning objective is using AI as a collaborator while maintaining your own judgment. If you used Copilot, evaluated its output critically, and made an improvement based on that evaluation, you completed this challenge.

      + +
      + + + + diff --git a/html/admin/qa-bundle/docs/solutions/solution-14-template.html b/html/admin/qa-bundle/docs/solutions/solution-14-template.html new file mode 100644 index 00000000..ff2b3adf --- /dev/null +++ b/html/admin/qa-bundle/docs/solutions/solution-14-template.html @@ -0,0 +1,183 @@ + + + + + + + Solution Reference: Challenge 14 -- Design an Issue Template - GIT Going with GitHub + + + + + + + + +
      +

      Solution Reference: Challenge 14 -- Design an Issue Template

      +

      This shows a completed custom YAML issue template with annotations.

      +

      Example template

      +

      File: .github/ISSUE_TEMPLATE/accessibility-report.yml

      +
      # The name appears in the template chooser when someone clicks "New Issue"
+name: Accessibility Report
+# The description appears below the name in the chooser
+description: Report an accessibility barrier in workshop materials
+# Labels are automatically applied to issues created from this template
+labels: ["accessibility", "bug"]
+# The title field pre-fills the issue title with a pattern
+title: "[A11y]: "
+# The body defines the form fields
+body:
+  # A description field adds context that is not an input
+  - type: markdown
+    attributes:
+      value: |
+        Thank you for reporting an accessibility barrier.
+        Your feedback helps us make the workshop inclusive for everyone.
+
+  # A text input for a short answer
+  - type: input
+    id: location
+    attributes:
+      label: Where did you encounter the barrier?
+      description: File name, URL, or description of where the problem is
+      placeholder: "Example: docs/welcome.md line 15"
+    validations:
+      required: true
+
+  # A textarea for a longer description
+  - type: textarea
+    id: description
+    attributes:
+      label: Describe the barrier
+      description: What happened? What did you expect to happen?
+    validations:
+      required: true
+
+  # A dropdown for assistive technology
+  - type: dropdown
+    id: assistive-tech
+    attributes:
+      label: Assistive technology (if applicable)
+      options:
+        - Screen reader (NVDA)
+        - Screen reader (JAWS)
+        - Screen reader (VoiceOver)
+        - Screen magnifier
+        - Voice control
+        - Switch access
+        - Keyboard only
+        - Other
+        - Not applicable
+    validations:
+      required: false
+
+  # A dropdown for severity
+  - type: dropdown
+    id: severity
+    attributes:
+      label: How much does this affect your ability to participate?
+      options:
+        - Blocked (cannot continue)
+        - Difficult (can work around it)
+        - Minor (cosmetic or preference)
+    validations:
+      required: true
      +

      What each field type does

      + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + +
      TypePurposeWhen to use
      markdownDisplays text that is not an input fieldInstructions, context, legal notices
      inputSingle-line text fieldShort answers like file names, URLs, versions
      textareaMulti-line text fieldDescriptions, steps to reproduce, long answers
      dropdownSelection from predefined optionsCategories, severity levels, yes/no questions
      checkboxesMultiple selection checkboxesChecklists, acknowledgments, multi-select categories
      +

      Alternate valid templates

      +

      Any topic works for this challenge. Other examples:

      +
        +
      • A bug report template for the workshop
        • +
      • A feature request template for new workshop topics
        • +
      • A feedback template for session evaluations
        • +
      • A question template for asking for help
        • +
      +

      What matters

      +

      The learning objective is understanding structured issue templates as a way to guide contributors. If your YAML file has a name, description, and at least one body field, you completed this challenge.

      + +
      + + + + diff --git a/html/admin/qa-bundle/docs/solutions/solution-15-agents.html b/html/admin/qa-bundle/docs/solutions/solution-15-agents.html new file mode 100644 index 00000000..5fa5cc2d --- /dev/null +++ b/html/admin/qa-bundle/docs/solutions/solution-15-agents.html @@ -0,0 +1,97 @@ + + + + + + + Solution Reference: Challenge 15 -- Discover Accessibility Agents - GIT Going with GitHub + + + + + + + + +
      +

      Solution Reference: Challenge 15 -- Discover Accessibility Agents

      +

      This shows example agent discovery notes.

      +

      Example: Three agents examined

      +

      Agent 1: accessibility-lead

      +

      Location: .github/agents/accessibility-lead.agent.md

      +

      Purpose: Coordinates accessibility reviews across the team. Acts as an orchestrator that delegates to specialist agents.

      +

      Key observation: This agent does not do the accessibility checking itself -- it routes requests to the right specialist (ARIA, keyboard, contrast, etc.). This is a design pattern called orchestration.

      +

      Agent 2: aria-specialist

      +

      Location: .github/agents/aria-specialist.agent.md

      +

      Purpose: Reviews ARIA (Accessible Rich Internet Applications) attributes in HTML and web components. Checks that interactive elements have correct roles, states, and properties.

      +

      Key observation: The agent instructions reference specific ARIA patterns from the W3C specification. Custom agents can encode domain expertise.

      +

      Agent 3: keyboard-navigator

      +

      Location: .github/agents/keyboard-navigator.agent.md

      +

      Purpose: Ensures that all interactive elements are operable by keyboard. Checks tab order, focus management, and keyboard shortcuts.

      +

      Key observation: The guardrails section says it cannot test actual keyboard behavior -- it can only review code. Testing still requires a human with a keyboard.

      +

      Example: Running an agent

      +

      What I asked: "@accessibility-lead review the heading structure of this file"

      +

      What it did: The lead agent delegated to the alt-text-headings specialist, which analyzed the heading levels and reported that the file skipped from H2 to H4.

      +

      What I learned: Agents can chain together. The lead interpreted my request and chose the right specialist. I did not need to know which agent handles headings.

      +

      Example: Reading agent instructions

      +

      Looking at the .agent.md file structure:

      +
        +
      • YAML frontmatter: Contains the agent name, description, and tool restrictions
        • +
      • Responsibilities section: Lists what the agent is designed to do
        • +
      • Guardrails section: Lists what the agent should NOT do or cannot do reliably
        • +
      +

      What matters

      +

      The learning objective is understanding that AI agents are configurable tools with defined boundaries. If you examined at least one agent's instructions and can explain what it does and what it will not do, you completed this challenge.

      + +
      + + + + diff --git a/html/admin/qa-bundle/docs/solutions/solution-16-capstone.html b/html/admin/qa-bundle/docs/solutions/solution-16-capstone.html new file mode 100644 index 00000000..adf205b6 --- /dev/null +++ b/html/admin/qa-bundle/docs/solutions/solution-16-capstone.html @@ -0,0 +1,146 @@ + + + + + + + Solution Reference: Challenge 16 -- Build Your Own Agent (Capstone) - GIT Going with GitHub + + + + + + + + +
      +

      Solution Reference: Challenge 16 -- Build Your Own Agent (Capstone)

      +

      This shows a complete agent file with annotations.

      +

      Example agent file

      +

      File: community-agents/workshop-buddy.agent.md

      +
      ---
+# YAML frontmatter -- metadata about the agent
+name: Workshop Buddy
+description: A friendly guide that helps students navigate the Git Going with GitHub workshop
+tools: []
+---
+
+# Workshop Buddy
+
+## Responsibilities
+
+<!-- This section defines what the agent is designed to do -->
+
+- Answer questions about workshop challenges and point students to the right chapter
+- Explain Git and GitHub concepts in beginner-friendly language
+- Suggest next steps when a student is stuck on a challenge
+- Remind students about accessibility best practices in their contributions
+
+## Guardrails
+
+<!-- This section defines what the agent should NOT do -->
+
+- Do not complete challenges for the student -- guide, do not solve
+- Do not make changes to repository files directly
+- Do not provide answers to challenge evidence prompts
+- Do not access external services or APIs
+- If asked about topics outside the workshop scope, say so honestly and suggest other resources
+
+## Example interactions
+
+**Student asks:** "I am stuck on Challenge 7. What are conflict markers?"
+
+**Agent responds:** Conflict markers are lines Git adds when it cannot automatically
+merge two changes. They look like `<<<<<<< HEAD`, `=======`, and `>>>>>>>`. You need
+to decide which version to keep and delete the marker lines. See Chapter 7 for a
+walkthrough.
+
+**Student asks:** "Write my PR description for me."
+
+**Agent responds:** I cannot write your PR description because that is the evidence
+for Challenge 6. But I can help you think about what to include. What did you change,
+and why? Start with those two sentences and you have a strong description.
      +

      PR description for the capstone

      +
      ## New agent: Workshop Buddy
+
+This agent helps students navigate the Git Going with GitHub workshop by answering
+questions about challenges, explaining Git concepts, and suggesting next steps.
+
+### Design decisions
+
+- **Guide, do not solve:** The guardrails prevent the agent from completing challenges,
+  because the learning happens in the doing
+- **Scoped to the workshop:** The agent is honest about its boundaries rather than
+  guessing at topics it was not designed for
+- **Accessibility aware:** Reminders about inclusive contribution practices are part
+  of the agent's responsibilities
+
+### Checklist
+
+- [x] YAML frontmatter with name and description
+- [x] Responsibilities section
+- [x] Guardrails section
+- [x] Example interactions showing both helpfulness and boundaries
      +

      Alternate valid agents

      +

      Any agent concept works. Other examples students have built:

      +
        +
      • An agent that reviews Markdown formatting
        • +
      • An agent that checks issue titles for clarity
        • +
      • An agent that recommends which Git command to use
        • +
      • An agent that explains error messages
        • +
      +

      What matters

      +

      The learning objective is understanding that AI agents are defined by their responsibilities AND their guardrails. If your agent file has valid YAML frontmatter, a clear purpose, and explicit boundaries, you completed this challenge. The creativity of the concept is a bonus, not a requirement.

      + +
      + + + + diff --git a/html/admin/qa-bundle/docs/solutions/solution-bonus-a.html b/html/admin/qa-bundle/docs/solutions/solution-bonus-a.html new file mode 100644 index 00000000..0ca86921 --- /dev/null +++ b/html/admin/qa-bundle/docs/solutions/solution-bonus-a.html @@ -0,0 +1,88 @@ + + + + + + + Solution Reference: Bonus A -- Improve an Agent - GIT Going with GitHub + + + + + + + + +
      +

      Solution Reference: Bonus A -- Improve an Agent

      +

      This shows an example improvement PR for an existing accessibility agent.

      +

      Example improvement

      +

      Target agent: aria-specialist.agent.md

      +

      What I changed: Added a new responsibility for checking aria-live regions in dynamic content. The existing agent covered static ARIA roles but did not mention live regions, which are critical for screen reader users interacting with content that updates without a page reload.

      +

      Before (responsibilities excerpt):

      +
      - Check that interactive elements have correct ARIA roles
+- Verify that ARIA states match the visual state of components
      +

      After (with addition):

      +
      - Check that interactive elements have correct ARIA roles
+- Verify that ARIA states match the visual state of components
+- Review aria-live regions for appropriate politeness levels (polite vs assertive) on dynamic content updates
      +

      PR description:

      +
      +

      Adds live region checking to the ARIA specialist agent's responsibilities.

      +

      Dynamic content updates (search results, notifications, form validation messages) need aria-live attributes so screen readers announce changes. The agent currently checks static ARIA attributes but not live regions. This addition closes that gap.

      +
      +

      What matters

      +

      The learning objective is contributing to an existing project by understanding its conventions and making a targeted improvement. If you identified a real gap and proposed a specific, well-reasoned change, you completed this bonus.

      + +
      + + + + diff --git a/html/admin/qa-bundle/docs/solutions/solution-bonus-b.html b/html/admin/qa-bundle/docs/solutions/solution-bonus-b.html new file mode 100644 index 00000000..70b0773e --- /dev/null +++ b/html/admin/qa-bundle/docs/solutions/solution-bonus-b.html @@ -0,0 +1,116 @@ + + + + + + + Solution Reference: Bonus B -- Document Your Journey - GIT Going with GitHub + + + + + + + + +
      +

      Solution Reference: Bonus B -- Document Your Journey

      +

      This shows an example reflection document.

      +

      Example journey reflection

      +
      # My Git Going with GitHub Journey
+
+## Before the workshop
+
+I had never used Git or GitHub. I thought "version control" was saving files
+as `report-final.docx`, `report-final-v2.docx`, `report-ACTUALLY-final.docx`.
+
+## Day 1: You Belong Here
+
+The scavenger hunt (Challenge 1) made the GitHub interface feel less intimidating.
+I learned that a repository is organized like a folder with special powers --
+it tracks every change anyone makes.
+
+Filing my first issue (Challenge 2) surprised me. I expected issues to be
+complaints, but they are really conversations about improvements. Writing a
+clear title forced me to clarify my thinking before I started typing.
+
+The merge conflict (Challenge 7) was the moment everything clicked. Seeing
+the conflict markers and understanding that Git was asking ME to make a human
+decision -- not failing or breaking -- changed how I think about collaboration.
+
+## Day 2: You Can Build This
+
+Going local (Challenge 10) felt powerful. Having the files on my machine and
+using the terminal made me feel like a real developer, even though all I did
+was fix a typo.
+
+The code review (Challenge 12) taught me that feedback is a skill. My first
+attempt at reviewing was just "looks good" on everything. After reading the
+chapter, I went back and left a specific suggestion that my buddy actually
+used. That felt collaborative in a way I had not expected.
+
+## What I will do next
+
+- Contribute to an accessibility project on GitHub
+- Set up Git on my personal laptop
+- Explore GitHub Skills for more practice
+
+## One sentence summary
+
+I came in thinking Git was too technical for me and left knowing it is a
+communication tool that anyone can learn.
      +

      What matters

      +

      The learning objective is structured reflection using proper Markdown. If you wrote a document with headings, paragraphs, and honest reflection, you completed this bonus.

      + +
      + + + + diff --git a/html/admin/qa-bundle/docs/solutions/solution-bonus-c.html b/html/admin/qa-bundle/docs/solutions/solution-bonus-c.html new file mode 100644 index 00000000..f42c33be --- /dev/null +++ b/html/admin/qa-bundle/docs/solutions/solution-bonus-c.html @@ -0,0 +1,101 @@ + + + + + + + Solution Reference: Bonus C -- Create a Group Challenge - GIT Going with GitHub + + + + + + + + +
      +

      Solution Reference: Bonus C -- Create a Group Challenge

      +

      This shows an example group challenge design.

      +

      Example: Accessibility Audit Relay

      +

      Designed for: 3-5 students

      +

      Challenge description

      +

      Students audit a sample web page for accessibility issues, relay-style. Each person has a different focus area:

      +
        +
      • Student 1: Checks all images for meaningful alt text
        • +
      • Student 2: Reviews heading hierarchy (H1, H2, H3 order)
        • +
      • Student 3: Tests every link for descriptive text (no "click here")
        • +
      • Student 4: Checks color contrast on text elements
        • +
      • Student 5 (if present): Reviews keyboard navigation order
        • +
      +

      How it works

      +
        +
      1. The group forks a sample repository containing a deliberately imperfect HTML page
        2. +
      2. Each student creates a branch for their focus area
        3. +
      3. Each student files issues for the problems they find
        4. +
      4. The group discusses which fixes to prioritize
        5. +
      5. Each student submits a PR fixing at least one issue
        6. +
      6. The group reviews and merges each other's PRs
        7. +
      +

      Evidence

      +

      Each student posts: their issues filed, their PR, and one review they gave.

      +

      Why this works for a group

      +
        +
      • Every student has a defined role so no one is left out
        • +
      • The relay structure means students depend on each other (Student 3 cannot fix link text if Student 1 has not pushed their alt text fixes yet)
        • +
      • The final product is a genuinely more accessible page
        • +
      +

      What matters

      +

      The learning objective is designing collaborative work that gives every participant a meaningful role. If your challenge design includes clear roles, concrete deliverables, and a reason for people to work together (not just alongside each other), you completed this bonus.

      + +
      + + + + diff --git a/html/admin/qa-bundle/docs/solutions/solution-bonus-d.html b/html/admin/qa-bundle/docs/solutions/solution-bonus-d.html new file mode 100644 index 00000000..407ca4dd --- /dev/null +++ b/html/admin/qa-bundle/docs/solutions/solution-bonus-d.html @@ -0,0 +1,105 @@ + + + + + + + Solution Reference: Bonus D -- Notification Mastery - GIT Going with GitHub + + + + + + + + +
      +

      Solution Reference: Bonus D -- Notification Mastery

      +

      This shows a configured notification setup with before/after.

      +

      Before: Default settings

      +

      With default settings, GitHub sends email notifications for:

      +
        +
      • Every issue and PR in every repository you watch
        • +
      • Every comment on any thread you have participated in
        • +
      • Every CI status update
        • +
      +

      This quickly becomes overwhelming. Most people start ignoring all GitHub emails.

      +

      After: Configured settings

      +

      Notification settings (github.com/settings/notifications)

      +
        +
      • Participating: Email ON, Web ON -- you want to know when someone replies to your conversations
        • +
      • Watching: Email OFF, Web ON -- browse these when you have time, not in your inbox
        • +
      • GitHub Actions: Email OFF for successful runs, Email ON for failed runs only
        • +
      +

      Repository watching

      +
        +
      • Repositories you actively contribute to: Watch (all activity)
        • +
      • Repositories you read occasionally: Custom (issues and PRs only)
        • +
      • Repositories you finished with: Unwatch
        • +
      +

      Custom routing (if you use multiple emails)

      +
        +
      • Route Community-Access organization notifications to your workshop email
        • +
      • Route personal project notifications to your personal email
        • +
      +

      Key decisions explained

      +
        +
      • Why email off for watching: You can check the notification bell on github.com when you choose. Email notifications for watched repos create constant interruption for low-priority updates.
        • +
      • Why Actions failures only: A green checkmark in the PR is enough. You only need an email when something breaks.
        • +
      • Why unwatch finished repos: Your notification feed stays relevant to current work.
        • +
      +

      What matters

      +

      The learning objective is intentional notification management. If you changed at least one setting from the default and can explain why that change reduces noise while keeping you informed about what matters, you completed this bonus.

      + +
      + + + + diff --git a/html/admin/qa-bundle/docs/solutions/solution-bonus-e.html b/html/admin/qa-bundle/docs/solutions/solution-bonus-e.html new file mode 100644 index 00000000..87e0131c --- /dev/null +++ b/html/admin/qa-bundle/docs/solutions/solution-bonus-e.html @@ -0,0 +1,106 @@ + + + + + + + Solution Reference: Bonus E -- Explore Git History Visually - GIT Going with GitHub + + + + + + + + +
      +

      Solution Reference: Bonus E -- Explore Git History Visually

      +

      This shows a visual history exploration.

      +

      On github.com

      +

      Viewing commit history

      +
        +
      1. Navigate to any repository
        2. +
      2. Click the "X commits" link near the top (shows total commit count)
        3. +
      3. The history page shows each commit with author, date, message, and SHA
        4. +
      4. Click any commit to see what changed (green lines added, red lines removed)
        5. +
      +

      What you see

      +

      The commit history tells the story of a project:

      +
        +
      • Chronological order: Most recent commits first
        • +
      • Author attribution: Every change has a name attached
        • +
      • Commit messages: Each entry explains what changed and (ideally) why
        • +
      • Diffs: Click any commit to see exactly which lines were added, removed, or modified
        • +
      +

      In GitHub Desktop

      +

      Visual timeline

      +
        +
      1. Open the repository in GitHub Desktop
        2. +
      2. Click the "History" tab
        3. +
      3. The left panel shows commits as a timeline
        4. +
      4. Click any commit to see the diff in the right panel
        5. +
      5. The branch visualization shows where branches diverged and merged
        6. +
      +

      Key observations from exploring history

      +
        +
      • Merge commits show where two branches came together -- they have two parent commits
        • +
      • The first commit in a repository is often called "initial commit" and creates the project structure
        • +
      • Commit frequency varies -- some days have many commits, others have none. This is normal.
        • +
      +

      In VS Code

      +

      The "Timeline" view in the Explorer sidebar shows the history for the currently open file. Each entry is a commit that changed that file. This is useful for understanding how a specific file evolved.

      +

      What matters

      +

      The learning objective is understanding that Git history is a navigable record of every change. If you explored the commit history, clicked into at least one commit to see its diff, and can describe what the history tells you about the project, you completed this bonus.

      + +
      + + + + diff --git a/html/admin/qa-bundle/docs/student-onboarding.html b/html/admin/qa-bundle/docs/student-onboarding.html new file mode 100644 index 00000000..91da72fa --- /dev/null +++ b/html/admin/qa-bundle/docs/student-onboarding.html @@ -0,0 +1,145 @@ + + + + + + + Student Onboarding: Git Going with GitHub - GIT Going with GitHub + + + + + + + + +
      +

      Student Onboarding: Git Going with GitHub

      +

      Welcome to Git Going with GitHub, a two-day Community Access workshop for blind and low-vision learners who want practical, confidence-building GitHub skills.

      +

      This page is the short version of what to do before the workshop and what to expect when we begin. The detailed setup guide is still the source of truth: Pre-Workshop Setup.

      +

      Course Dates

      +

      The workshop is scheduled for May 21-22, 2026.

      +

      Each day includes guided instruction, hands-on practice, breaks, and time for questions. You do not need to be fast. You do need to be willing to try, ask questions, and keep going when GitHub feels unfamiliar.

      +

      Complete Before Day 1

      +

      Please complete these steps before the first session:

      +
        +
      1. Create or confirm your GitHub account.
        2. +
      2. Verify your GitHub email address.
        3. +
      3. Enable two-factor authentication if possible.
        4. +
      4. Configure GitHub accessibility settings, especially disabling hovercards.
        5. +
      5. Install Visual Studio Code.
        6. +
      6. Install Git.
        7. +
      7. Sign in to GitHub in your browser.
        8. +
      8. Confirm GitHub Copilot is available in VS Code.
        9. +
      9. Review the full Pre-Workshop Setup checklist.
        10. +
      +

      If any step blocks you, tell us before the workshop. Setup problems are normal, and we would rather help early than spend Day 1 troubleshooting silently.

      +

      Do Not Claim A Repository Yet

      +

      You do not need to accept a GitHub Classroom assignment before Day 1.

      +

      At the beginning of the workshop, the facilitator will share a GitHub Classroom assignment link in the meeting chat. That link creates your private Learning Room repository. We will walk through the process together.

      +

      Preview the steps in The Learning Room: Accept Your Classroom Assignment and Open Your Repo.

      +

      What Your Learning Room Is

      +

      Your Learning Room is a private GitHub repository created from the Community-Access/learning-room-template template. It is your practice space for the workshop.

      +

      You do not clone or work directly in the template repository. GitHub Classroom makes a private copy for you, and that private copy is the repository you use during the workshop.

      +

      Inside that repository you will find:

      +
        +
      • Challenge issues that guide your work one step at a time
        • +
      • Practice documents with intentional problems to fix
        • +
      • GitHub Actions that check your work
        • +
      • Aria, the workshop bot that gives feedback on pull requests
        • +
      • Reference files for branches, pull requests, merge conflicts, Copilot, and agents
        • +
      +

      Other students cannot see your private Learning Room repository. Facilitators can see it through GitHub Classroom so they can help when you get stuck.

      +

      You do not need a GitHub organization, owner access, or repository settings access. The facilitators configure the template, Classroom assignment, and GitHub Actions permissions before the workshop. Your job is to accept the assignment link, work in the repository it creates for you, and ask for help if a permission prompt appears.

      +

      How The Challenge Flow Works

      +

      The workshop uses a guided progression:

      +
        +
      1. Open the current challenge issue.
        2. +
      2. Read the goal and steps.
        3. +
      3. Complete the task in GitHub or VS Code.
        4. +
      4. Add evidence as an issue comment.
        5. +
      5. Close the issue when you are done.
        6. +
      6. The progression bot opens the next challenge.
        7. +
      +

      Some challenges ask you to open a pull request. When you do, Aria reviews the pull request structure, checks links and accessibility basics, and explains what to fix. This mirrors a real open source workflow: create a branch, make a focused change, open a pull request, get feedback, revise, and merge.

      +

      GitHub Skills Modules

      +

      We also recommend GitHub Skills modules because they use the same issue-and-bot learning pattern as the workshop.

      +

      The three most useful modules for this course are:

      + +

      You do not need to finish these before Day 1. We will reference them during the course, and they are excellent follow-up practice afterward. The full catalog is in Appendix Z: GitHub Skills.

      +

      What To Keep Nearby

      +

      During the workshop, keep these pages open or bookmarked:

      + +

      Getting Help

      +

      If something does not work:

      +
        +
      1. Say so in the workshop chat.
        2. +
      2. Mention what screen reader, browser, and operating system you are using.
        3. +
      3. Share the link to the page or repository where you are stuck, if you can.
        4. +
      4. Ask for a facilitator or peer to walk with you.
        5. +
      +

      This workshop is designed around real GitHub workflows. Real workflows include mistakes, confusing screens, failing checks, and revisions. That is not failure. That is the work.

      + +
      + + + + diff --git a/html/admin/qa-bundle/index.html b/html/admin/qa-bundle/index.html new file mode 100644 index 00000000..de6995c6 --- /dev/null +++ b/html/admin/qa-bundle/index.html @@ -0,0 +1,104 @@ + + + + + + + QA Bundle (Grab-and-Go) - GIT Going with GitHub + + + + + + + + +
      +

      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
        2. +
      2. GO-LIVE-QA-GUIDE.md
        3. +
      3. admin/qa-readiness/UNIT-TEST-RESULTS-2026-05-08.md
        4. +
      +

      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

      + +

      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/html/admin/qa-bundle/learning-room/index.html b/html/admin/qa-bundle/learning-room/index.html new file mode 100644 index 00000000..d7a60019 --- /dev/null +++ b/html/admin/qa-bundle/learning-room/index.html @@ -0,0 +1,178 @@ + + + + + + + Welcome to the Learning Room - GIT Going with GitHub + + + + + + + + +
      +

      Welcome to the Learning Room

      +

      This repository is your private Learning Room for the Git Going with GitHub workshop. GitHub Classroom created it from the Learning Room template so you can practice the full contribution workflow safely. In this repository you will:

      +
        +
      • File your first issue
        • +
      • Leave your first comment
        • +
      • Open your first pull request
        • +
      • Review a peer's pull request when facilitators pair you for review
        • +
      +

      Everything in this repository is designed for learning. The files in docs/ have intentional issues that you will find and fix during the workshop contribution sprint.

      +

      What Is in This Repository

      + + + + + + + + + + + + + + + + + + + +
      Folder / FilePurpose
      docs/welcome.mdIntroduction to contributing (has some sections to complete)
      docs/keyboard-shortcuts.mdKeyboard shortcut reference (has some errors to find and fix)
      docs/setup-guide.mdSetup instructions (has some broken links and gaps)
      +

      How to Contribute

      +
        +
      1. Open the canonical challenge list: ../docs/CHALLENGES.md
        2. +
      2. Find your assigned issue (Issues tab -> filter by "Assignee: me" or search your username in the issue title)
        3. +
      3. Claim the issue with a comment: I'd like to try this!
        4. +
      4. Read the issue description - it tells you which file to edit and what to fix
        5. +
      5. Click the file -> the edit pencil button -> make your change
        6. +
      6. Commit to a new branch with a descriptive name: fix/[your-name]-[issue-number]
        7. +
      7. Open a pull request using the PR template and include Closes #XX
        8. +
      8. Wait for the bot (~30 seconds) - it will check your changes and provide feedback
        9. +
      9. Read bot feedback carefully - it explains any issues and links to resources
        10. +
      10. Make changes if needed based on feedback
        11. +
      11. Request a review from your assigned peer reviewer
        12. +
      12. Respond to review feedback and make final improvements
        13. +
      13. Merge when approved (the issue closes automatically)
        14. +
      14. Add a final issue comment with what you learned and your merged PR link
        15. +
      +

      See the workshop documentation for full step-by-step guidance.

      +

      About the Automation Bot

      +

      When you open a pull request, an automated bot will:

      +
        +
      • Check your changes against quality standards
        • +
      • Validate accessibility (heading hierarchy, link text, alt text, broken links)
        • +
      • Provide educational feedback explaining why things matter
        • +
      • Link to resources for learning more
        • +
      • Apply labels to help facilitators prioritize reviews
        • +
      +

      The bot is not a substitute for peer review! It provides instant technical feedback so your human reviewers can focus on higher-level improvements, creative suggestions, and encouragement.

      +

      How to Interact with the Bot

      +

      Reading Bot Comments:

      +
        +
      • Bot posts ONE comment that updates as you make changes
        • +
      • Use headings to navigate (Required Checks, Suggestions, Accessibility Analysis, Resources)
        • +
      • Each issue includes file/line numbers and how to fix it
        • +
      +

      Getting Help from the Bot: +Comment on your PR with keywords:

      +
        +
      • @bot help - Get help information
        • +
      • Mention "merge conflict" - Get conflict resolution guide
        • +
      • Mention "request review" - Get instructions for requesting human review
        • +
      +

      When You Disagree: +The bot isn't always right! If you believe feedback is incorrect:

      +
        +
      1. Comment explaining your reasoning
        2. +
      2. Request human review
        3. +
      3. Facilitators can override bot checks
        4. +
      +

      Read the Student Guide →

      +

      Skills & Progression

      +

      As you complete challenges, you'll:

      +
        +
      • Track progress through skill levels (Explorer, Contributor, Collaborator, Operator, Reviewer, Agent Navigator)
        • +
      • Unlock new challenges when you reach milestones
        • +
      • Earn badges for specific achievements (Branch Builder, PR Pioneer, Conflict Resolver, and more)
        • +
      • Celebrate milestones (first challenge, Day 1 complete, all challenges complete)
        • +
      +

      View Available Challenges → +Follow the Full Course Roadmap →

      +

      Stuck? Use Guided References

      + +

      Use these references after you attempt the challenge yourself. They are designed to unblock you, not replace your own practice.

      +

      Study Groups

      +

      You may be assigned to a study group for collaborative learning. Groups:

      +
        +
      • Work through challenges together
        • +
      • Review each other's PRs
        • +
      • Share resources and tips
        • +
      • Support each other's learning
        • +
      +

      If assigned to a group, you'll receive an issue thread for communication.

      +

      Code of Conduct

      +

      All participants and contributors are expected to follow our Code of Conduct. This is a welcoming, accessible space.

      +

      Questions?

      +

      Open an issue! Use the "Feature or Improvement Request" template if you have a suggestion, or the "Accessibility Bug Report" template if you find an accessibility issue.

      + +
      + + + + diff --git a/html/admin/qa-readiness/UNIT-TEST-RESULTS-2026-05-08.html b/html/admin/qa-readiness/UNIT-TEST-RESULTS-2026-05-08.html new file mode 100644 index 00000000..525eacc7 --- /dev/null +++ b/html/admin/qa-readiness/UNIT-TEST-RESULTS-2026-05-08.html @@ -0,0 +1,172 @@ + + + + + + + Unit Test Results - 2026-05-08 (Non-Podcast Scope) - GIT Going with GitHub + + + + + + + + +
      +

      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:
        2. +
      +
        +
      • 16 core challenge templates
        • +
      • 5 bonus templates
        • +
      • Complete numbering/lettering coverage
        • +
      +
        +
      1. Challenge quality gates:
        2. +
      +
        +
      • Required evidence fields and troubleshooting guidance
        • +
      • Core and bonus template quality checks
        • +
      +
        +
      1. Classroom setup consistency:
        2. +
      +
        +
      • Assignment docs and autograding JSON integrity
        • +
      • Required scripts and template files present
        • +
      • Classroom README deployment section coverage
        • +
      +
        +
      1. Workflow configuration readiness:
        2. +
      +
        +
      • Concurrency settings in key workflows
        • +
      • Critical permissions in bot/progression workflows
        • +
      +
        +
      1. Registration readiness:
        2. +
      +
        +
      • Workflow logic includes registration, duplicate, and waitlist paths
        • +
      • Registration issue form template exists
        • +
      +
        +
      1. QA gate integrity:
        2. +
      +
        +
      • 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:
        2. +
      +
        +
      • Cause: expected wording did not match final runbook phrasing.
        • +
      • Fix: updated test to assert actual required phrasing in runbook.
        • +
      +
        +
      1. Registration template name assertion too strict:
        2. +
      +
        +
      • 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:

      + +

      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.

      + +
      + + + + diff --git a/html/admin/qa-readiness/index.html b/html/admin/qa-readiness/index.html new file mode 100644 index 00000000..be21914c --- /dev/null +++ b/html/admin/qa-readiness/index.html @@ -0,0 +1,118 @@ + + + + + + + QA Readiness Test Pack (Non-Podcast) - GIT Going with GitHub + + + + + + + + +
      +

      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:

      +
      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:

      + +

      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:

      + + +
      + + + + diff --git a/html/classroom/index.html b/html/classroom/index.html index 0e23fed0..76d217da 100644 --- a/html/classroom/index.html +++ b/html/classroom/index.html @@ -65,6 +65,12 @@

      Workshop Deployment Guide

      Before sharing invite links with students, complete the Go-Live QA Guide. It is the final release gate for content, workflows, Classroom setup, podcasts, accessibility, and human test coverage.

      +
      +

      If you need one practical execution script from registration through full student challenge completion (podcast work excluded), use admin/LEARNING-ROOM-E2E-QA-RUNBOOK.md.

      +
      +
      +

      Before creating assignments, sync and validate the latest template deployment using scripts/classroom/Prepare-LearningRoomTemplate.ps1 and scripts/classroom/Test-LearningRoomTemplate.ps1.

      +

      How the Workshop Works

      Each student gets their own private repository created by GitHub Classroom from the learning-room-template. Inside that repo, three automation systems guide the student through all 21 challenges without facilitator intervention:

        @@ -169,6 +175,10 @@

        What Is in This Directory

        ../GO-LIVE-QA-GUIDE.md Final release-readiness guide and checklist + +../admin/LEARNING-ROOM-E2E-QA-RUNBOOK.md +Single operator runbook from registration to student completion (podcast excluded) +

        Prerequisites

        @@ -632,6 +642,7 @@

        Post-Workshop

      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
        4. +
      4. Route ongoing learner support to Community-Access/support

      Customization Options

      @@ -682,6 +693,7 @@
    • Challenge Hub -- all 21 challenges with instructions
    • Solutions Directory -- reference solutions for facilitator use
    • Grading Guide -- per-challenge rubric and completion levels
      • +
    • Support Hub Operations -- operating model for async support after the workshop
    diff --git a/html/docs/00-pre-workshop-setup.html b/html/docs/00-pre-workshop-setup.html index 8388dfa7..c4e48e01 100644 --- a/html/docs/00-pre-workshop-setup.html +++ b/html/docs/00-pre-workshop-setup.html @@ -58,7 +58,9 @@
    -

    Pre-Workshop Setup - GIT Going with GitHub

    +

    Table: Screen reader options for workshop setup

    +

    Table: Accessibility improvements for screen reader users

    +

    Pre-Workshop Setup - GIT Going with GitHub

    Listen to Episode 1: Pre-Workshop Setup - a conversational audio overview of this chapter. Listen before reading to preview the concepts, or after to reinforce what you learned.

    @@ -69,7 +71,7 @@

    Pre-Workshop Setup - GIT Goi

    Everything You Need Before Day 1 Begins

    A Community Access workshop.

    -

    Please complete this guide at least one day before the workshop. If you run into any issues, file an issue so we can help - we want Day 1 to start with everyone ready to go, not troubleshooting.

    +

    Please complete this guide at least one day before the workshop. If you run into any issues, use the support hub at Community-Access/support 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. 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

    @@ -274,7 +276,7 @@

    Authenticati

    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.

    +

    If you run into any authentication issues before the workshop, open a support issue at Community-Access/support/issues or contact the workshop organizers directly.

    Learning Cards: Create Your GitHub Account

    Screen reader users @@ -1081,14 +1083,14 @@

    If You Get Stuck

    Everything else -File an issue at community-access/git-going-with-github describing what step you are on and what happened. We will help. +File a support issue at Community-Access/support/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 - we will help you get set up
      2. -
    2. File an issue in this repository - describe exactly what step you are on and what is not working
      3. +
    3. File a setup support issue - Community-Access/support/issues - we will help you get set up
      4. +
    4. Join Support Hub Discussions - Community-Access/support/discussions - read pinned Start Here guidance and ask follow-up questions
    5. Join the GitHub Accessibility Discussions - GitHub Community Accessibility Discussions - 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.

    diff --git a/html/docs/21-next-steps.html b/html/docs/21-next-steps.html index 6fd59f16..a777ac16 100644 --- a/html/docs/21-next-steps.html +++ b/html/docs/21-next-steps.html @@ -348,7 +348,7 @@

    6. Staying Connected

    Community Access

    • Community Access on GitHub -- The organization behind this workshop. Watch the repositories for updates.
      • -
    • Workshop facilitators are available for questions after the event. Post on the learning-room repository or the git-going-with-github repository.
      • +
    • For post-workshop questions, troubleshooting, and alumni conversation, use the open support hub: Community-Access/support.

    Open source contribution

    The capstone was your first contribution. Here is how to make more:

    @@ -450,7 +450,7 @@

    If You Get Stuck After the Workshop Need help from the community -Post in GitHub Community Accessibility Discussions or file an issue in the workshop repo. +Post in Support Hub Discussions or file a support issue.

    8. Final Words

    diff --git a/html/docs/appendix-u-discussions-and-gists.html b/html/docs/appendix-u-discussions-and-gists.html index 97fce34a..22522fd2 100644 --- a/html/docs/appendix-u-discussions-and-gists.html +++ b/html/docs/appendix-u-discussions-and-gists.html @@ -75,6 +75,19 @@

    Forum-Style C

    GitHub Discussions is a built-in community forum for repositories and organizations. It's where open-ended conversations live - questions, ideas, announcements, polls, and community Q&A - separate from the action-oriented world of issues and pull requests.

    +

    +

    For ongoing support after the workshop, use:

    + +

    Suggested first steps for students:

    +
      +
    1. Read the pinned Start Here resources in Discussions.
      2. +
    2. Search existing discussions before opening a new support thread.
      3. +
    3. Use issue templates for setup blockers or accessibility blockers so maintainers can help faster.
      4. +

    Learning Cards: GitHub Discussions

    Screen reader users diff --git a/html/docs/course-guide.html b/html/docs/course-guide.html index 7a058c38..b0e0a176 100644 --- a/html/docs/course-guide.html +++ b/html/docs/course-guide.html @@ -615,7 +615,7 @@

    Getting Help

    When you want to learn more about a topic -

    Still stuck? Open an issue on this repository describing what you tried, what happened, and what you expected. Include your screen reader and operating system.

    +

    Still stuck? Open a support issue at https://github.com/Community-Access/support/issues describing what you tried, what happened, and what you expected. Include your screen reader and operating system.

    Workshop at a Glance

    diff --git a/html/learning-room/index.html b/html/learning-room/index.html index d7a60019..4fcbc2f7 100644 --- a/html/learning-room/index.html +++ b/html/learning-room/index.html @@ -58,7 +58,9 @@
    -

    Welcome to the Learning Room

    +

    Table: Learning Room folder and file purposes +Table: Host voice and character mapping for VibeVoice podcast

    +

    Welcome to the Learning Room

    This repository is your private Learning Room for the Git Going with GitHub workshop. GitHub Classroom created it from the Learning Room template so you can practice the full contribution workflow safely. In this repository you will:

    • File your first issue
      • diff --git a/html/podcasts/REGENERATION.html b/html/podcasts/REGENERATION.html index 24483143..1e7680b5 100644 --- a/html/podcasts/REGENERATION.html +++ b/html/podcasts/REGENERATION.html @@ -61,14 +61,14 @@

      Podcast Regeneration Runbook

      This runbook explains how to rebuild the Git Going with GitHub podcast series after curriculum changes. Use it when chapters, appendices, agendas, or challenges change enough that the existing transcripts no longer match the source material.

      Current Strategy

      -

      The podcast pipeline has two distinct content layers.

      +

      The podcast pipeline has two content layers that are published as one listening path.

      1. Companion episodes for chapters and appendices These are conversational overviews. They help learners preview or review concepts before reading the full material.
      2. Challenge teaching episodes These should teach the challenge in a guided, classroom style. They should explain the skill, model the learner's thinking, describe what success sounds like with a screen reader, and clarify what evidence the learner submits.
      -

      The chapter and appendix episodes can stay broader and conceptual. The challenge episodes should be more tactical and should follow the Learning Room progression.

      +

      The chapter and appendix episodes can stay broader and conceptual. The challenge episodes should be more tactical and should follow the Learning Room progression. The final public order is controlled by podcasts/listening-order.json, which places each challenge near the chapters that prepare learners for it.

      The refreshed companion catalog currently contains 54 episodes. The Challenge Coach layer currently has 21 generated source bundles: 16 core challenges plus 5 bonus challenges.

      Style Standard

      Keep the Alex and Jamie format. The banter is part of the accessibility design because it makes dense technical material easier to process.

      @@ -131,8 +131,8 @@

      Regeneration Workflow

  • Generate audio:

    -
    python -m podcasts.tts.generate_episode ep00-welcome
-python -m podcasts.tts.generate_all --start 0 --end 10
    +
    python -m podcasts.tts.generate_all_kokoro --start 0 --end 0 --force --audio-format mp3
+python -m podcasts.tts.generate_all_kokoro --start 0 --end 10 --audio-format mp3

  • Update the podcast page and RSS feed:

    npm run build:podcast-site
@@ -204,7 +204,7 @@ 
    Challenge Episode Strategy
    
 
  • 16 core challenge episodes, one per challenge
    • 
 
  • 5 bonus challenge episodes, one per bonus challenge
    • 
 
-
    Target length should be 5-8 minutes each. These can be more practical than the chapter episodes and should be released as a separate "Challenge Coach" section on the podcast page.
    
+
    Target length should be 5-8 minutes each. These can be more practical than the chapter episodes and should be interleaved with the companion lessons on the podcast page and in RSS.
    
 
    Transcript Source of Truth
    
 
    Use this hierarchy:
    
 
      
diff --git a/html/podcasts/index.html b/html/podcasts/index.html
index ebbf4e73..bc9ec6ce 100644
--- a/html/podcasts/index.html
+++ b/html/podcasts/index.html
@@ -58,8 +58,11 @@
     
   
   
      
-    
      Podcast Audio Pipeline
      
-
      This directory contains the complete pipeline for producing the Git Going with GitHub companion audio series: 54 companion episodes of two-host conversational content designed for blind and low-vision developers, plus generated source bundles for 21 Challenge Coach episodes.
      
+    
      Table: Host voice and character mapping for VibeVoice podcast
      
+
      Table: Podcast build and validation commands
      
+
      Table: Podcast bundle generation steps and costs
      
+
      Podcast Audio Pipeline
      
+
      This directory contains the complete pipeline for producing the Git Going with GitHub audio series: 54 companion episodes of two-host conversational content designed for blind and low-vision developers, plus 21 Challenge Coach episodes placed near the chapters they support.
      
 
      Pipeline Overview
      
 
      build-bundles.js     Generate source bundles from chapter content
         |
@@ -70,16 +73,18 @@ 
      Pipeline Overview
      
   scripts/*.txt      Conversational scripts with [ALEX]/[JAMIE]/[PAUSE] markers
         |
         v
-  tts/               Local Piper neural TTS (ONNX models, pronunciation lexicon)
+  tts/               Local neural TTS (ONNX models, pronunciation lexicon)
         |
         v
       audio/*.(wav|mp3)  Final episode files (gitignored - hosted on GitHub Releases)
         |
         v
 generate-site.js     Build PODCASTS.md player page and RSS feed from manifest
      
-
      Audio is generated locally using Piper neural text-to-speech. No cloud APIs, no API keys, no billing. Runs entirely on your machine.
      
-
      Use the podcasts/tts/ pipeline as the current audio path. The older podcasts/generate_all_episodes_with_piper.py script uses a different model layout and is not the active build path.
      
+
      Audio is generated locally using ONNX text-to-speech models. No cloud APIs, no API keys, no billing. Runs entirely on your machine.
      
+
      Use the Kokoro batch generator as the production audio path. The Piper generator remains available as npm run build:podcast-audio:piper for fallback or comparison.
      
+
      podcasts/listening-order.json controls the public listening path. It interleaves companion lessons, Challenge Coach episodes, and reference episodes so podcast apps and the generated player page present the workshop as one end-to-end experience.
      
 
      Final episode output format is configurable through podcasts/tts/voice-config.ini (episode_audio_format = wav|mp3|both). MP3 generation requires ffmpeg on your PATH.
      
+
      After all MP3 files and segment manifests are generated, run the metadata pass to add ID3 tags, embed the source script, and derive smart chapter markers for each episode. The metadata pass defaults to a dry run so it can verify the full 75-file set before touching audio.
      
 
      Directory Structure
      
 
      podcasts/
   README.md             This guide
@@ -97,25 +102,30 @@ 
      Directory Structure
      
       audio/                Episode WAV/MP3 files after generation (not in git)
   tts/                  Python TTS package
     __init__.py         Package init
-    generate_episode.py Single episode generator
-    generate_all.py     Batch generator for all episodes
-    download_samples.py Voice sample downloader
+    generate_episode.py Legacy Piper single episode generator
+    generate_all.py     Legacy Piper batch generator
+    generate_all_kokoro.py Kokoro batch generator for all episodes
+    download_kokoro_samples.py Kokoro model downloader
+    download_samples.py Legacy Piper voice sample downloader
     lexicon.txt         Pronunciation dictionary for technical terms
-    models/             Piper ONNX voice models
+    models/             Kokoro and legacy Piper ONNX voice models
     samples/            Voice sample WAVs
      
 
      Prerequisites
      
 
        
 
      • Python 3.10 or later
        • 
-
      • Piper TTS: pip install piper-tts
        • 
+
      • Kokoro TTS: pip install kokoro-onnx soundfile numpy
        • 
+
      • FFmpeg on your PATH for MP3 conversion
        • 
+
      • Mutagen for MP3 ID3 metadata: pip install mutagen
        • 
 
      • Node.js 18 or later (for bundle/site generation only)
        • 
 
      
 
      For full regeneration guidance after curriculum changes, see Podcast Regeneration Runbook.
      
 
      Quick Start
      
-
      1. Install Piper
      
-
      pip install piper-tts
      
+
      1. Install Kokoro and metadata tooling
      
+
      pip install kokoro-onnx soundfile numpy
+pip install mutagen
      
 
      2. Download voice models (if not already present)
      
-
      python -m podcasts.tts.download_samples
      
-
      This downloads en_US Piper ONNX models to podcasts/tts/models/.
      
+
      python -m podcasts.tts.download_kokoro_samples --english-high-quality-only
      
+
      This downloads the Kokoro ONNX model and voices file to podcasts/tts/models/.
      
 
      3. Validate the catalog and generate fresh local bundles
      
 
      npm run validate:podcasts
 npm run build:podcast-bundles
@@ -124,13 +134,13 @@ 
      3. Validate the
 
      podcasts/bundles/*.md files are generated prompt packets. They are intentionally ignored by git and should be regenerated when needed.
 podcasts/challenge-bundles/*.md files are the same kind of generated prompt packet, but scoped to individual Challenge Coach episodes.
      
 
      4. Generate all episodes
      
-
      python -m podcasts.tts.generate_all
      
+
      python -m podcasts.tts.generate_all_kokoro --audio-format mp3
      
 
      This batch command processes the full committed script set: all ep*.txt companion episodes plus all cc-*.txt Challenge Coach and bonus episodes.
      
 
      Or generate a single episode:
      
-
      python -m podcasts.tts.generate_episode ep00-welcome
-python -m podcasts.tts.generate_episode ep05-pull-requests
      
+
      python -m podcasts.tts.generate_all_kokoro --start 0 --end 0 --force --audio-format mp3
+python -m podcasts.tts.generate_all_kokoro --start 5 --end 5 --force --audio-format mp3
      
 
      Or a range:
      
-
      python -m podcasts.tts.generate_all --start 0 --end 10
      
+
      python -m podcasts.tts.generate_all_kokoro --start 0 --end 10 --audio-format mp3
      
 
      5. Build player page and RSS feed
      
 
      npm run build:podcast-site
      
 
      Voice Configuration
      
@@ -139,40 +149,39 @@ 
      Voice Configuration
    • - + - + - +
    HostPiper ModelKokoro Voice Character Description
    Alexen_US-ryan-higham_liam Lead host, experienced, warm Male, polished delivery with stronger presence
    Jamieen_US-lessac-highaf_jessica Co-host, curious, energetic Female, clear and natural delivery
    -

    26 en_US voice models are included. Listen to samples in podcasts/tts/samples/ to try different voices.

    -

    To change voices, edit the MALE_MODEL and FEMALE_MODEL paths in podcasts/tts/generate_episode.py.

    +

    Listen to samples in podcasts/tts/samples/ to try different voices.

    +

    To change voices, pass --male-voice and --female-voice to python -m podcasts.tts.generate_all_kokoro.

    Pitch can be configured independently per host in podcasts/tts/voice-config.ini:

    male_pitch_semitones = -1.0
 female_pitch_semitones = 0.8

    For backwards compatibility, pitch_semitones is still accepted and applies the same shift to both voices.

    Pronunciation Lexicon

    -

    The file podcasts/tts/lexicon.txt contains pronunciation overrides for technical terms, acronyms, and jargon. The lexicon is applied as text substitution before Piper synthesizes each segment.

    +

    The file podcasts/tts/lexicon.txt contains pronunciation overrides for technical terms, acronyms, and jargon. The lexicon is applied as text substitution before Kokoro synthesizes each segment.

    Format: one entry per line, tab-separated WORD<tab>REPLACEMENT. Lines starting with # are comments.

    Example entries:

    WCAG    W-Cag
 NVDA    N V D A
 GitHub  Git Hub
 JSON    Jason
    -

    Add new entries when Piper mispronounces a word. The lexicon is loaded once per run and uses word-boundary matching so entries like GUI do not affect words like "guidelines".

    -

    Piper uses espeak-ng for phonemization. For precise control, you can also use espeak-ng phoneme syntax directly in the script text: [[...]] for inline phoneme overrides.

    +

    Add new entries when Kokoro mispronounces a word. The lexicon is loaded once per run and uses word-boundary matching so entries like GUI do not affect words like "guidelines".

    Manifest Status Flow

    Each episode in manifest.json progresses through these statuses:

    bundle-ready  -->  script-ready  -->  audio-ready  -->  published
@@ -207,7 +216,15 @@ 
    All npm Scripts
    
 
 
 npm run build:podcast-audio
-Generate audio for all companion, Challenge Coach, and bonus scripts with local Piper TTS
+Generate MP3 audio for all companion, Challenge Coach, and bonus scripts with local Kokoro TTS
+
+
+npm run build:podcast-audio:piper
+Generate audio with the legacy local Piper TTS path
+
+
+npm run build:podcast-audio:kokoro
+Generate MP3 audio with the Kokoro TTS path
 
 
 npm run build:podcast-transcripts-and-audio
@@ -218,6 +235,14 @@ 
    All npm Scripts
    
 Build player page and RSS feed
 
 
+npm run podcast:metadata:check
+Dry-run validation that all 75 MP3s and matching scripts are present before tagging
+
+
+npm run podcast:metadata:write
+Write ID3 metadata, embed episode scripts and smart chapters, write chapter JSON sidecars, and touch all 75 MP3 files
+
+
 npm run build:podcasts
 Bundles + site
 
@@ -229,10 +254,13 @@ 
    All npm Scripts
    
 
    Publishing Audio
    
 
    Audio files are hosted on GitHub Releases (not in the repository, they are gitignored).
    
 
      
-
    1. Generate all audio: python -m podcasts.tts.generate_all
      2. 
+
    2. Generate all audio as MP3 files: npm run build:podcast-audio
      3. 
+
    3. Confirm all expected MP3 files exist: npm run podcast:metadata:check
      4. 
+
    4. Write ID3 tags, embed the source script, derive smart chapter markers, and touch each MP3: npm run podcast:metadata:write
      5. 
+
    5. Build the podcast page and RSS feed: npm run build:podcast-site
      6. 
 
    6. Create a GitHub Release tagged podcasts
      7. 
-
    7. Upload the WAV files from podcasts/audio/ as release assets
      8. 
-
    8. The RSS feed already points to release asset URLs
      9. 
+
    9. Upload the MP3 files from podcasts/audio/ or the selected voice output folder as release assets
      10. 
+
    10. The RSS feed points to release asset URLs, links chapter JSON sidecars, and embeds clean script text in each item
      11. 
 
    11. Update manifest status to published and rebuild the site
      12. 
 
    
 
    Updating Episodes
    
@@ -243,22 +271,40 @@ 
    Updating Episodes
    
 
  • npm run build:podcast-challenge-bundles to regenerate local challenge bundles
    • 
 
  • npm run generate:podcast-transcripts to replace old scripts with fresh reviewable drafts
    • 
 
  • Review and edit the scripts in podcasts/scripts/
    • 
-
  • python -m podcasts.tts.generate_episode <slug> to regenerate audio
    • 
+
  • python -m podcasts.tts.generate_all_kokoro --start <number> --end <number> --force --audio-format mp3 to regenerate audio
    • 
+
  • npm run podcast:metadata:check to verify the complete MP3 set before tagging
    • 
+
  • npm run podcast:metadata:write to refresh ID3 tags, smart chapters, chapter JSON, and touch every generated MP3
    • 
 
  • npm run build:podcast-site to update the player page and RSS feed
    • 
 
  • Upload new audio to the GitHub Release
    • 
 
  • Commit reviewed scripts, metadata, generated site/feed files, and source changes
    • 
 
+
    MP3 Metadata, Embedded Scripts, and Chapters
    
+
    The metadata tool writes the following ID3 fields to each MP3:
    
+
      
+
    • Title: episode or challenge title
      • 
+
    • Artist, album artist, and publisher: Community Access
      • 
+
    • Album: Git Going with GitHub - Audio Series
      • 
+
    • Author website: Community Access website
      • 
+
    • Description: episode description or challenge focus
      • 
+
    • Episode script: the matching podcasts/scripts/*.txt source embedded as both a custom text frame and an unsynchronized lyrics frame
      • 
+
    • Smart chapters: ID3 chapter frames derived from podcasts/audio/segments/<episode>/manifest.json
      • 
+
    • Chapter sidecars: Podcasting 2.0 JSON files in podcasts/chapters/, linked from RSS as podcast:chapters
      • 
+
    
+
    Chapter markers are pause-aware. The tool starts with the opening segment, prefers natural boundaries after [PAUSE], avoids very short chapters, and forces a new marker when a section grows too long. Chapter titles are generated from the next spoken segment with small heuristics for questions, "big idea" openings, practice anchors, and why-it-matters sections.
    
+
    Run the dry-run check first:
    
+
    npm run podcast:metadata:check
    
+
    Only after all 75 MP3 files and segment manifests exist, write tags, chapters, and refresh file modification times:
    
+
    npm run podcast:metadata:write
    
+
    If you are testing a partial batch intentionally, call the tool directly with --allow-missing and an explicit audio directory. Do not use that option for the final publishing pass.
    
 
    Troubleshooting
    
-
    Piper command not found
    
-
    Ensure Piper TTS is installed:
    
-
    pip install piper-tts
-python -m piper --help
    
+
    Kokoro dependencies missing
    
+
    Ensure Kokoro and audio dependencies are installed:
    
+
    pip install kokoro-onnx soundfile numpy
    
 
    Model not found
    
 
    Download models first:
    
+
    python -m podcasts.tts.download_kokoro_samples --english-high-quality-only
    
+
    The legacy Piper model downloader is still available for fallback runs:
    
 
    python -m podcasts.tts.download_samples
    
-
    Or download specific models manually:
    
-
    python -m piper.download_voices en_US-ryan-high --download-dir podcasts/tts/models
-python -m piper.download_voices en_US-lessac-high --download-dir podcasts/tts/models
    
 
    Mispronounced word
    
 
    Add an entry to podcasts/tts/lexicon.txt with the correct pronunciation and regenerate the episode.
    
 
    Script quality issues
    
@@ -271,8 +317,8 @@ 
    Script quality issues

Audio sounds robotic or unnatural

    -
  • Try a different Piper voice model from podcasts/tts/models/
    • -
  • Adjust LENGTH_SCALE in podcasts/tts/generate_episode.py for slower or faster delivery
    • +
  • Try different Kokoro voices with --male-voice and --female-voice
    • +
  • Adjust the generator options in podcasts/tts/generate_all_kokoro.py for spacing and chunking
  • Add pronunciation fixes to podcasts/tts/lexicon.txt

Cost Summary

@@ -296,7 +342,7 @@

Cost Summary

Audio synthesis -Local Piper TTS +Local Kokoro TTS Free diff --git a/html/podcasts/tts/index.html b/html/podcasts/tts/index.html index 5cb2563d..3f793b97 100644 --- a/html/podcasts/tts/index.html +++ b/html/podcasts/tts/index.html @@ -58,7 +58,8 @@
-

TTS Setup: Piper and Kokoro

+

Table: TTS pipeline outcomes and provided commands

+

TTS Setup: Piper and Kokoro

This runbook documents the end-to-end local setup for the workshop TTS toolchain.

For full GitHub Classroom deployment, use classroom/README.md. That guide covers classroom creation, assignments, invite links, seeding, testing, and teardown.

What this runbook covers

diff --git a/html/search-index.json b/html/search-index.json index 9ffd477e..480aad9d 100644 --- a/html/search-index.json +++ b/html/search-index.json @@ -15,13 +15,13 @@ "id": "SECURITY.html", "title": "Security Policy", "url": "SECURITY.html", - "body": "Security Policy Supported Versions This repository contains educational curriculum and documentation only - no production software, application servers, or APIs. There are no versioned software releases to patch. Content Supported Curriculum documentation (docs/) Current main branch GitHub Actions workflows (.github/workflows/) Current main branch Build scripts (scripts/) Current main branch AI agent prompts (.github/prompts/, .github/agents/) Current main branch Reporting a Vulnerability Please do not report security vulnerabilities as public GitHub Issues. Public issues are visible to everyone, including people who might exploit the vulnerability before it is fixed. Preferred Method - Private Vulnerability Reporting This repository has Private Vulnerability Reporting enabled. To submit a report: Navigate to the Security tab of this repository Select "Report a vulnerability" Fill in the form with: A clear title describing the issue A detailed description of the vulnerability and its potential impact Steps to reproduce (if applicable) Your suggested fix (optional but appreciated) Submit - only the maintainers will see your report What to Report Even though this is an educational repository, the following are genuine security concerns: Malicious content injected into curriculum files - documentation that contains links to phishing sites, malware downloads, or misleading instructions GitHub Actions workflow vulnerabilities - script injection risks in .github/workflows/ , insecure use of GITHUB_TOKEN , or pull-request-triggered workflows that execute untrusted code Hardcoded credentials - any real tokens, passwords, or API keys accidentally committed to any file Supply chain risks - compromised npm dependencies used by the build system Prompt injection in agent files - AI agent prompts ( .prompt.md , .agent.md ) that could manipulate an LLM to produce harmful output What Is Out of Scope Theoretical attacks with no realistic exploitation path Vulnerabilities in GitHub's own infrastructure (report those to GitHub directly at the GitHub Security page ) Broken links or outdated documentation (open a regular issue for those) Response Timeline Milestone Target Acknowledge receipt Within 3 business days Initial assessment Within 7 business days Fix deployed (if confirmed) Within 30 days for critical/high; 90 days for medium/low Public disclosure After fix is deployed, or coordinated with reporter Scope and Impact This curriculum is designed to teach GitHub to workshop participants. The primary security risks are: Documentation accuracy - incorrect instructions that could cause participants to configure their systems insecurely Workflow integrity - GitHub Actions that run on pull requests from forks require careful scoping to prevent privilege escalation Dependency security - the build system uses Node.js packages that must be kept up to date Credit Security researchers who responsibly disclose valid vulnerabilities will be credited in the repository's release notes (unless they prefer to remain anonymous). For general questions about the curriculum, open a regular issue. For security concerns, use private reporting above." + "body": "Security Policy Supported Versions This repository contains educational curriculum and documentation only - no production software, application servers, or APIs. There are no versioned software releases to patch. Table: Supported content types and their source Content Supported Curriculum documentation (docs/) Current main branch GitHub Actions workflows (.github/workflows/) Current main branch Build scripts (scripts/) Current main branch AI agent prompts (.github/prompts/, .github/agents/) Current main branch Reporting a Vulnerability Please do not report security vulnerabilities as public GitHub Issues. Public issues are visible to everyone, including people who might exploit the vulnerability before it is fixed. Preferred Method - Private Vulnerability Reporting This repository has Private Vulnerability Reporting enabled. To submit a report: Navigate to the Security tab of this repository Select "Report a vulnerability" Fill in the form with: A clear title describing the issue A detailed description of the vulnerability and its potential impact Steps to reproduce (if applicable) Your suggested fix (optional but appreciated) Submit - only the maintainers will see your report What to Report Even though this is an educational repository, the following are genuine security concerns: Malicious content injected into curriculum files - documentation that contains links to phishing sites, malware downloads, or misleading instructions GitHub Actions workflow vulnerabilities - script injection risks in .github/workflows/ , insecure use of GITHUB_TOKEN , or pull-request-triggered workflows that execute untrusted code Hardcoded credentials - any real tokens, passwords, or API keys accidentally committed to any file Supply chain risks - compromised npm dependencies used by the build system Prompt injection in agent files - AI agent prompts ( .prompt.md , .agent.md ) that could manipulate an LLM to produce harmful output What Is Out of Scope Theoretical attacks with no realistic exploitation path Vulnerabilities in GitHub's own infrastructure (report those to GitHub directly at the GitHub Security page ) Broken links or outdated documentation (open a regular issue for those) Response Timeline Milestone Target Acknowledge receipt Within 3 business days Initial assessment Within 7 business days Fix deployed (if confirmed) Within 30 days for critical/high; 90 days for medium/low Public disclosure After fix is deployed, or coordinated with reporter Scope and Impact This curriculum is designed to teach GitHub to workshop participants. The primary security risks are: Documentation accuracy - incorrect instructions that could cause participants to configure their systems insecurely Workflow integrity - GitHub Actions that run on pull requests from forks require careful scoping to prevent privilege escalation Dependency security - the build system uses Node.js packages that must be kept up to date Credit Security researchers who responsibly disclose valid vulnerabilities will be credited in the repository's release notes (unless they prefer to remain anonymous). For general questions about the curriculum, open a regular issue. For security concerns, use private reporting above." }, { "id": "docs/00-pre-workshop-setup.html", "title": "Pre-Workshop Setup - GIT Going with GitHub", "url": "docs/00-pre-workshop-setup.html", - "body": "Pre-Workshop Setup - GIT Going with GitHub Listen to Episode 1: Pre-Workshop Setup - 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 Y: Workshop Materials | Appendix Z: GitHub Skills Authoritative sources: GitHub Docs: Create an account | GitHub Docs: Set up Git Everything You Need Before Day 1 Begins A Community Access workshop. Please complete this guide at least one day before the workshop. If you run into any issues, file an issue 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 . 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 What You Will Need Step 1 - Create Your GitHub Account Step 2 - Configure GitHub Accessibility Settings Step 3 - Configure Your Profile Step 4 - Check GitHub Feature Preview Settings Step 5 - Set Up Your Screen Reader and Browser Step 6 - Install Git and Visual Studio Code Step 7 - Configure Git Identity Step 8 - Install VS Code Extensions Step 9 - Verification Checklist Other GitHub Access Methods (Reference Only) 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 (Windows/Linux) or Xcode Command Line Tools (macOS) Visual Studio Code (free) - download here (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 JAWS (Job Access With Speech) Windows Paid (trial available) Download 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 covers SSH keys and personal access tokens in detail. If you already have a GitHub account, skip to Step 2 . 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 Open your browser and navigate to the GitHub signup page The page loads with focus on the first field: "Enter your email address" Type your email address and press Tab or activate Continue The next field is "Create a password" Choose a password of at least 8 characters (15+ recommended). Press Tab or Continue 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 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 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 Activate the Create account button 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 You w" + "body": "Table: Screen reader options for workshop setup Table: Accessibility improvements for screen reader users Pre-Workshop Setup - GIT Going with GitHub Listen to Episode 1: Pre-Workshop Setup - 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 Y: Workshop Materials | Appendix Z: GitHub Skills Authoritative sources: GitHub Docs: Create an account | GitHub Docs: Set up Git Everything You Need Before Day 1 Begins A Community Access workshop. Please complete this guide at least one day before the workshop. If you run into any issues, use the support hub at Community-Access/support 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 . 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 What You Will Need Step 1 - Create Your GitHub Account Step 2 - Configure GitHub Accessibility Settings Step 3 - Configure Your Profile Step 4 - Check GitHub Feature Preview Settings Step 5 - Set Up Your Screen Reader and Browser Step 6 - Install Git and Visual Studio Code Step 7 - Configure Git Identity Step 8 - Install VS Code Extensions Step 9 - Verification Checklist Other GitHub Access Methods (Reference Only) 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 (Windows/Linux) or Xcode Command Line Tools (macOS) Visual Studio Code (free) - download here (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 JAWS (Job Access With Speech) Windows Paid (trial available) Download 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 covers SSH keys and personal access tokens in detail. If you already have a GitHub account, skip to Step 2 . 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 Open your browser and navigate to the GitHub signup page The page loads with focus on the first field: "Enter your email address" Type your email address and press Tab or activate Continue The next field is "Create a password" Choose a password of at least 8 characters (15+ recommended). Press Tab or Continue 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 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 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 Activate the Create account button GitHub sends a launch code (a short numeric code) to your email inbox Check your email, c" }, { "id": "docs/01-choose-your-tools.html", @@ -273,7 +273,7 @@ "id": "docs/appendix-u-discussions-and-gists.html", "title": "Appendix U: Discussions and Gists", "url": "docs/appendix-u-discussions-and-gists.html", - "body": "Appendix U: Discussions and Gists Reference companion to: Chapter 08: Open Source Culture | Also relevant: Chapter 10 Authoritative source: GitHub Docs: About discussions This appendix consolidates two related community content features: GitHub Discussions (formerly Appendix G) and GitHub Gists (formerly Appendix F). GitHub Discussions Listen to Episode 24: GitHub Discussions - a conversational audio overview of this chapter. Listen before reading to preview the concepts, or after to reinforce what you learned. Forum-Style Conversations Beyond Issues and Pull Requests GitHub Discussions is a built-in community forum for repositories and organizations. It's where open-ended conversations live - questions, ideas, announcements, polls, and community Q&A - separate from the action-oriented world of issues and pull requests. Learning Cards: GitHub Discussions Screen reader users The Discussions tab is in the repository's main navigation bar alongside Code, Issues, and Pull Requests -- press T to navigate tab items or K to find the "Discussions" link Inside a discussion, replies are article elements -- in NVDA press A to jump between replies; in JAWS use A as well The reply editor uses the same behavior as issue comments -- enter Focus Mode to type, then press Ctrl+Enter to submit Low vision users Discussion categories appear as a sidebar panel on the left or right depending on viewport width -- look for the category list with item counts Answered discussions in the Q&A category display a green "Answered" badge next to the title, with the accepted answer pinned to the top Polls show percentage bars next to each option after you vote -- the bars use color fill to indicate proportion Sighted users Discussions are organized by category with colored labels -- the sidebar shows all categories and pinned items In Q&A threads, look for the green checkmark on the accepted answer pinned above the regular reply timeline Use the upvote button (thumbs up) on replies instead of posting "+1" comments -- maintainers often sort by upvotes Table of Contents Discussions vs. Issues: When to Use Which Navigating to Discussions Discussion Categories Creating a Discussion Participating in Discussions Marking an Answer Polls Screen Reader Navigation Reference Organization-Level Discussions Accessibility Agents: What's Different Here 1. Discussions vs. Issues: When to Use Which Not every conversation belongs in an issue. GitHub Discussions exists for the conversations that don't fit: Use Issues When Use Discussions When You found a bug You have a question about how something works You want to request a specific feature You want to brainstorm ideas before filing a feature request There is actionable work to be done You want community input before deciding what work to do You need to track progress (labels, assign, close) You want to have an open conversation without resolving it The answer is "fixed" or "won't fix" The conversation might not have one right answer The signal for maintainers: A question in an issue is noisier - it implies something needs to be done. The same question in Discussions doesn't trigger workflow automation and doesn't inflate the issue count. Common Discussions categories you'll encounter Q&A - Support questions and answers (one answer can be marked correct) Ideas - Feature brainstorming before a formal feature request Announcements - Maintainer posts about releases, breaking changes, roadmaps General - Everything else Show and Tell - Community members showing what they built 2. Navigating to Discussions From a Repository Navigate to the repository There is a Discussions tab in the main navigation (alongside Code, Issues, Pull Requests, Actions, Projects) Press T to navigate tab items, or K to navigate links and find "Discussions" Press Enter to open If the tab is missing: Discussions is an opt-in feature. The repository maintainer must enable it in Settings. Not all repositories use it. From an Organization Large organizations can have organization-level Discussions separate from any individual repository: Navigate to the organization page Look for the Discussions tab at the organization level These are community-wide conversations, not repo-specific 3. Discussion Categories The Discussions home page is organized by category. Each category is a section with its own heading. Navigating categories 3 → Jump to category headings K → Navigate discussion titles within a category Enter → Open a discussion The side panel (left or right depending on view width) shows All categories with item counts Pin/announcements section at top Most active discussions Tags (if the repo uses them) 4. Creating a Discussion From the Discussions tab, activate "New discussion" button Select a category (required - affects which fields appear) Fill in: Title - Clear and searchable. "How do I use the daily-briefing agent" + "body": "Appendix U: Discussions and Gists Reference companion to: Chapter 08: Open Source Culture | Also relevant: Chapter 10 Authoritative source: GitHub Docs: About discussions This appendix consolidates two related community content features: GitHub Discussions (formerly Appendix G) and GitHub Gists (formerly Appendix F). GitHub Discussions Listen to Episode 24: GitHub Discussions - a conversational audio overview of this chapter. Listen before reading to preview the concepts, or after to reinforce what you learned. Forum-Style Conversations Beyond Issues and Pull Requests GitHub Discussions is a built-in community forum for repositories and organizations. It's where open-ended conversations live - questions, ideas, announcements, polls, and community Q&A - separate from the action-oriented world of issues and pull requests. Support Hub Onboarding (Recommended For Workshop Alumni) For ongoing support after the workshop, use: Support hub home: Community-Access/support Q&A and community discussion: Support Hub Discussions Trackable support requests: Support Hub Issues Suggested first steps for students: Read the pinned Start Here resources in Discussions. Search existing discussions before opening a new support thread. Use issue templates for setup blockers or accessibility blockers so maintainers can help faster. Learning Cards: GitHub Discussions Screen reader users The Discussions tab is in the repository's main navigation bar alongside Code, Issues, and Pull Requests -- press T to navigate tab items or K to find the "Discussions" link Inside a discussion, replies are article elements -- in NVDA press A to jump between replies; in JAWS use A as well The reply editor uses the same behavior as issue comments -- enter Focus Mode to type, then press Ctrl+Enter to submit Low vision users Discussion categories appear as a sidebar panel on the left or right depending on viewport width -- look for the category list with item counts Answered discussions in the Q&A category display a green "Answered" badge next to the title, with the accepted answer pinned to the top Polls show percentage bars next to each option after you vote -- the bars use color fill to indicate proportion Sighted users Discussions are organized by category with colored labels -- the sidebar shows all categories and pinned items In Q&A threads, look for the green checkmark on the accepted answer pinned above the regular reply timeline Use the upvote button (thumbs up) on replies instead of posting "+1" comments -- maintainers often sort by upvotes Table of Contents Discussions vs. Issues: When to Use Which Navigating to Discussions Discussion Categories Creating a Discussion Participating in Discussions Marking an Answer Polls Screen Reader Navigation Reference Organization-Level Discussions Accessibility Agents: What's Different Here 1. Discussions vs. Issues: When to Use Which Not every conversation belongs in an issue. GitHub Discussions exists for the conversations that don't fit: Use Issues When Use Discussions When You found a bug You have a question about how something works You want to request a specific feature You want to brainstorm ideas before filing a feature request There is actionable work to be done You want community input before deciding what work to do You need to track progress (labels, assign, close) You want to have an open conversation without resolving it The answer is "fixed" or "won't fix" The conversation might not have one right answer The signal for maintainers: A question in an issue is noisier - it implies something needs to be done. The same question in Discussions doesn't trigger workflow automation and doesn't inflate the issue count. Common Discussions categories you'll encounter Q&A - Support questions and answers (one answer can be marked correct) Ideas - Feature brainstorming before a formal feature request Announcements - Maintainer posts about releases, breaking changes, roadmaps General - Everything else Show and Tell - Community members showing what they built 2. Navigating to Discussions From a Repository Navigate to the repository There is a Discussions tab in the main navigation (alongside Code, Issues, Pull Requests, Actions, Projects) Press T to navigate tab items, or K to navigate links and find "Discussions" Press Enter to open If the tab is missing: Discussions is an opt-in feature. The repository maintainer must enable it in Settings. Not all repositories use it. From an Organization Large organizations can have organization-level Discussions separate from any individual repository: Navigate to the organization page Look for the Discussions tab at the organization level These are community-wide conversations, not repo-specific 3. Discussion Categories The Discussions home page is organized by category. Each category is a section with its own heading. Navigating categories 3 →" }, { "id": "docs/appendix-v-github-mobile.html", @@ -513,19 +513,19 @@ "id": "podcasts/tts/index.html", "title": "TTS Setup: Piper and Kokoro", "url": "podcasts/tts/index.html", - "body": "TTS Setup: Piper and Kokoro This runbook documents the end-to-end local setup for the workshop TTS toolchain. For full GitHub Classroom deployment, use classroom/README.md . That guide covers classroom creation, assignments, invite links, seeding, testing, and teardown. What this runbook covers It covers the following setup outcomes. Outcome Provided by Install Piper CLI/runtime python -m pip install piper-tts Download Piper en_US voices and WAV samples python -m podcasts.tts.download_samples Install Kokoro ONNX runtime python -m pip install kokoro-onnx Download Kokoro model files python -m podcasts.tts.download_kokoro_samples Generate Kokoro WAV samples for all voices python -m podcasts.tts.download_kokoro_samples Generate Kokoro English high-quality voice samples only python -m podcasts.tts.download_kokoro_samples --english-high-quality-only Install requirements From repository root: python -m pip install --upgrade pip python -m pip install piper -tts kokoro -onnx soundfile numpy One-command setup via npm scripts From repository root: npm run tts:setup -all This runs Piper sample download plus Kokoro model and sample generation. Piper setup and samples Download all en_US Piper voices and synthesize one WAV sample per voice: python -m podcasts.tts.download_samples Generate one specific Piper voice sample: python -m podcasts.tts.download_samples --voice en_US -ryan-high Piper files are written here: Models: podcasts/tts/models/ Samples: podcasts/tts/samples/ Log file: podcasts/logs/piper_samples.log Kokoro setup and samples Generate samples for all Kokoro voices: python -m podcasts.tts.download_kokoro_samples Generate only English high-quality voices: python -m podcasts.tts.download_kokoro_samples --english-high-quality-only Generate one specific Kokoro voice: python -m podcasts.tts.download_kokoro_samples --voice af_sarah Kokoro files are written here: Model files: podcasts/tts/models/kokoro-v1.0.onnx and podcasts/tts/models/voices-v1.0.bin All-voice samples: podcasts/tts/samples/kokoro/all/ English high-quality samples: podcasts/tts/samples/kokoro/english-high-quality/ Voice catalogs: podcasts/logs/kokoro_voices_all.txt and podcasts/logs/kokoro_voices_english_high_quality.txt Notes Large model and sample artifacts are ignored by git via .gitignore ( podcasts/tts/models/ and podcasts/tts/samples/ ). Kokoro does not publish low/medium/high voice tiers like Piper. In this repository, English voices are treated as the high-quality English set for practical testing." + "body": "Table: TTS pipeline outcomes and provided commands TTS Setup: Piper and Kokoro This runbook documents the end-to-end local setup for the workshop TTS toolchain. For full GitHub Classroom deployment, use classroom/README.md . That guide covers classroom creation, assignments, invite links, seeding, testing, and teardown. What this runbook covers It covers the following setup outcomes. Outcome Provided by Install Piper CLI/runtime python -m pip install piper-tts Download Piper en_US voices and WAV samples python -m podcasts.tts.download_samples Install Kokoro ONNX runtime python -m pip install kokoro-onnx Download Kokoro model files python -m podcasts.tts.download_kokoro_samples Generate Kokoro WAV samples for all voices python -m podcasts.tts.download_kokoro_samples Generate Kokoro English high-quality voice samples only python -m podcasts.tts.download_kokoro_samples --english-high-quality-only Install requirements From repository root: python -m pip install --upgrade pip python -m pip install piper -tts kokoro -onnx soundfile numpy One-command setup via npm scripts From repository root: npm run tts:setup -all This runs Piper sample download plus Kokoro model and sample generation. Piper setup and samples Download all en_US Piper voices and synthesize one WAV sample per voice: python -m podcasts.tts.download_samples Generate one specific Piper voice sample: python -m podcasts.tts.download_samples --voice en_US -ryan-high Piper files are written here: Models: podcasts/tts/models/ Samples: podcasts/tts/samples/ Log file: podcasts/logs/piper_samples.log Kokoro setup and samples Generate samples for all Kokoro voices: python -m podcasts.tts.download_kokoro_samples Generate only English high-quality voices: python -m podcasts.tts.download_kokoro_samples --english-high-quality-only Generate one specific Kokoro voice: python -m podcasts.tts.download_kokoro_samples --voice af_sarah Kokoro files are written here: Model files: podcasts/tts/models/kokoro-v1.0.onnx and podcasts/tts/models/voices-v1.0.bin All-voice samples: podcasts/tts/samples/kokoro/all/ English high-quality samples: podcasts/tts/samples/kokoro/english-high-quality/ Voice catalogs: podcasts/logs/kokoro_voices_all.txt and podcasts/logs/kokoro_voices_english_high_quality.txt Notes Large model and sample artifacts are ignored by git via .gitignore ( podcasts/tts/models/ and podcasts/tts/samples/ ). Kokoro does not publish low/medium/high voice tiers like Piper. In this repository, English voices are treated as the high-quality English set for practical testing." }, { "id": "podcasts/index.html", "title": "Podcast Audio Pipeline", "url": "podcasts/index.html", - "body": "Podcast Audio Pipeline This directory contains the complete pipeline for producing the Git Going with GitHub companion audio series: 54 companion episodes of two-host conversational content designed for blind and low-vision developers, plus generated source bundles for 21 Challenge Coach episodes. Pipeline Overview build-bundles.js Generate source bundles from chapter content | v bundles/*.md One bundle per episode (production prompt + source material) | v scripts/*.txt Conversational scripts with [ALEX]/[JAMIE]/[PAUSE] markers | v tts/ Local Piper neural TTS (ONNX models, pronunciation lexicon) | v audio/*.(wav| mp3 ) Final episode files (gitignored - hosted on GitHub Releases) | v generate-site.js Build PODCASTS.md player page and RSS feed from manifest Audio is generated locally using Piper neural text-to-speech. No cloud APIs, no API keys, no billing. Runs entirely on your machine. Use the podcasts/tts/ pipeline as the current audio path. The older podcasts/generate_all_episodes_with_piper.py script uses a different model layout and is not the active build path. Final episode output format is configurable through podcasts/tts/voice-config.ini ( episode_audio_format = wav|mp3|both ). MP3 generation requires ffmpeg on your PATH. Directory Structure podcasts/ README .md This guide build-bundles .js Generates source bundles + manifest .json build-challenge-bundles .js Generates Challenge Coach source bundles generate-draft-transcripts .js Generates reviewable Alex/Jamie transcript scripts generate-site .js Generates PODCASTS .md and feed .xml from manifest .json manifest .json Episode manifest (metadata, status tracking) feed .xml RSS 2.0 podcast feed (auto-generated) bundles/ Generated episode source bundles (gitignored) challenge-bundles/ Generated challenge coach source bundles (gitignored) scripts/ Two-host scripts (committed, reviewable) audio/ Episode WAV/MP3 files after generation (not in git) tts/ Python TTS package __init__ .py Package init generate_episode .py Single episode generator generate_all .py Batch generator for all episodes download_samples .py Voice sample downloader lexicon .txt Pronunciation dictionary for technical terms models/ Piper ONNX voice models samples/ Voice sample WAVs Prerequisites Python 3.10 or later Piper TTS: pip install piper-tts Node.js 18 or later (for bundle/site generation only) For full regeneration guidance after curriculum changes, see Podcast Regeneration Runbook . Quick Start 1. Install Piper pip install piper-tts 2. Download voice models (if not already present) python -m podcasts.tts.download_samples This downloads en_US Piper ONNX models to podcasts/tts/models/ . 3. Validate the catalog and generate fresh local bundles npm run validate:podcasts npm run build:podcast-bundles npm run build:podcast-challenge-bundles npm run generate:podcast-transcripts podcasts/bundles/*.md files are generated prompt packets. They are intentionally ignored by git and should be regenerated when needed. podcasts/challenge-bundles/*.md files are the same kind of generated prompt packet, but scoped to individual Challenge Coach episodes. 4. Generate all episodes python -m podcasts.tts.generate_all This batch command processes the full committed script set: all ep*.txt companion episodes plus all cc-*.txt Challenge Coach and bonus episodes. Or generate a single episode: python -m podcasts.tts.generate_episode ep00-welcome python -m podcasts.tts.generate_episode ep05-pull-requests Or a range: python -m podcasts.tts.generate_all --start 0 --end 10 5. Build player page and RSS feed npm run build:podcast-site Voice Configuration The default voices are: Host Piper Model Character Description Alex en_US-ryan-high Lead host, experienced, warm Male, polished delivery with stronger presence Jamie en_US-lessac-high Co-host, curious, energetic Female, clear and natural delivery 26 en_US voice models are included. Listen to samples in podcasts/tts/samples/ to try different voices. To change voices, edit the MALE_MODEL and FEMALE_MODEL paths in podcasts/tts/generate_episode.py . Pitch can be configured independently per host in podcasts/tts/voice-config.ini : male_pitch_semitones = - 1.0 female_pitch_semitones = 0.8 For backwards compatibility, pitch_semitones is still accepted and applies the same shift to both voices. Pronunciation Lexicon The file podcasts/tts/lexicon.txt contains pronunciation overrides for technical terms, acronyms, and jargon. The lexicon is applied as text substitution before Piper synthesizes each segment. Format: one entry per line, tab-separated WORD<tab>REPLACEMENT . Lines starting with # are comments. Example entries: WCAG W - Cag NVDA N V D A GitHub Git Hub JSON Jason Add new entries when Piper mispronounces a word. The lexicon is loaded once per run and uses word-boundary matching so entries like GUI do not affect words like "guidelines". Piper uses espeak-ng for phonemization. For precise control, you can also use espeak-ng phoneme syntax directl" + "body": "Table: Host voice and character mapping for VibeVoice podcast Table: Podcast build and validation commands Table: Podcast bundle generation steps and costs Podcast Audio Pipeline This directory contains the complete pipeline for producing the Git Going with GitHub audio series: 54 companion episodes of two-host conversational content designed for blind and low-vision developers, plus 21 Challenge Coach episodes placed near the chapters they support. Pipeline Overview build-bundles.js Generate source bundles from chapter content | v bundles/*.md One bundle per episode (production prompt + source material) | v scripts/*.txt Conversational scripts with [ALEX]/[JAMIE]/[PAUSE] markers | v tts/ Local neural TTS (ONNX models, pronunciation lexicon) | v audio/*.(wav| mp3 ) Final episode files (gitignored - hosted on GitHub Releases) | v generate-site.js Build PODCASTS.md player page and RSS feed from manifest Audio is generated locally using ONNX text-to-speech models. No cloud APIs, no API keys, no billing. Runs entirely on your machine. Use the Kokoro batch generator as the production audio path. The Piper generator remains available as npm run build:podcast-audio:piper for fallback or comparison. podcasts/listening-order.json controls the public listening path. It interleaves companion lessons, Challenge Coach episodes, and reference episodes so podcast apps and the generated player page present the workshop as one end-to-end experience. Final episode output format is configurable through podcasts/tts/voice-config.ini ( episode_audio_format = wav|mp3|both ). MP3 generation requires ffmpeg on your PATH. After all MP3 files and segment manifests are generated, run the metadata pass to add ID3 tags, embed the source script, and derive smart chapter markers for each episode. The metadata pass defaults to a dry run so it can verify the full 75-file set before touching audio. Directory Structure podcasts/ README .md This guide build-bundles .js Generates source bundles + manifest .json build-challenge-bundles .js Generates Challenge Coach source bundles generate-draft-transcripts .js Generates reviewable Alex/Jamie transcript scripts generate-site .js Generates PODCASTS .md and feed .xml from manifest .json manifest .json Episode manifest (metadata, status tracking) feed .xml RSS 2.0 podcast feed (auto-generated) bundles/ Generated episode source bundles (gitignored) challenge-bundles/ Generated challenge coach source bundles (gitignored) scripts/ Two-host scripts (committed, reviewable) audio/ Episode WAV/MP3 files after generation (not in git) tts/ Python TTS package __init__ .py Package init generate_episode .py Legacy Piper single episode generator generate_all .py Legacy Piper batch generator generate_all_kokoro .py Kokoro batch generator for all episodes download_kokoro_samples .py Kokoro model downloader download_samples .py Legacy Piper voice sample downloader lexicon .txt Pronunciation dictionary for technical terms models/ Kokoro and legacy Piper ONNX voice models samples/ Voice sample WAVs Prerequisites Python 3.10 or later Kokoro TTS: pip install kokoro-onnx soundfile numpy FFmpeg on your PATH for MP3 conversion Mutagen for MP3 ID3 metadata: pip install mutagen Node.js 18 or later (for bundle/site generation only) For full regeneration guidance after curriculum changes, see Podcast Regeneration Runbook . Quick Start 1. Install Kokoro and metadata tooling pip install kokoro-onnx soundfile numpy pip install mutagen 2. Download voice models (if not already present) python -m podcasts.tts.download_kokoro_samples --english-high-quality-only This downloads the Kokoro ONNX model and voices file to podcasts/tts/models/ . 3. Validate the catalog and generate fresh local bundles npm run validate:podcasts npm run build:podcast-bundles npm run build:podcast-challenge-bundles npm run generate:podcast-transcripts podcasts/bundles/*.md files are generated prompt packets. They are intentionally ignored by git and should be regenerated when needed. podcasts/challenge-bundles/*.md files are the same kind of generated prompt packet, but scoped to individual Challenge Coach episodes. 4. Generate all episodes python -m podcasts.tts.generate_all_kokoro --audio-format mp3 This batch command processes the full committed script set: all ep*.txt companion episodes plus all cc-*.txt Challenge Coach and bonus episodes. Or generate a single episode: python -m podcasts.tts.generate_all_kokoro --start 0 --end 0 --force --audio-format mp3 python -m podcasts.tts.generate_all_kokoro --start 5 --end 5 --force --audio-format mp3 Or a range: python -m podcasts.tts.generate_all_kokoro --start 0 --end 10 --audio-format mp3 5. Build player page and RSS feed npm run build:podcast-site Voice Configuration The default voices are: Host Kokoro Voice Character Description Alex am_liam Lead host, experienced, warm Male, polished delivery with stronger presence Jamie af_jessica Co-host, curious, energetic Female, clear and natural delivery Listen to sam" }, { "id": "podcasts/REGENERATION.html", "title": "Podcast Regeneration Runbook", "url": "podcasts/REGENERATION.html", - "body": "Podcast Regeneration Runbook This runbook explains how to rebuild the Git Going with GitHub podcast series after curriculum changes. Use it when chapters, appendices, agendas, or challenges change enough that the existing transcripts no longer match the source material. Current Strategy The podcast pipeline has two distinct content layers. Companion episodes for chapters and appendices These are conversational overviews. They help learners preview or review concepts before reading the full material. Challenge teaching episodes These should teach the challenge in a guided, classroom style. They should explain the skill, model the learner's thinking, describe what success sounds like with a screen reader, and clarify what evidence the learner submits. The chapter and appendix episodes can stay broader and conceptual. The challenge episodes should be more tactical and should follow the Learning Room progression. The refreshed companion catalog currently contains 54 episodes. The Challenge Coach layer currently has 21 generated source bundles: 16 core challenges plus 5 bonus challenges. Style Standard Keep the Alex and Jamie format. The banter is part of the accessibility design because it makes dense technical material easier to process. Alex: Warm expert guide. Explains concepts clearly, corrects misconceptions gently, and connects each task to real open source practice. Jamie: Curious co-host. Asks the questions a learner may hesitate to ask, restates the mental model, adds gentle humor, and names moments that feel confusing. Tone: Conversational, kind, practical, and lightly playful. Avoid: Stage directions, music cues, markdown tables in scripts, visual-only language, and jokes that pull attention away from the task. Every generated script must use only these markers on their own lines: [ALEX] [JAMIE] [PAUSE] New Machine Setup Run these commands from the repository root. The following commands install the required Node and Python dependencies for bundle generation, site generation, and local Piper TTS audio generation. npm install python -m pip install --upgrade pip python -m pip install piper -tts python -m podcasts.tts.download_samples Confirm the local tools work: npm run validate:podcasts npm run build:podcast -bundles npm run build:podcast -challenge-bundles npm run generate:podcast -transcripts python -m podcasts.tts.generate_episode ep00 -welcome npm run build:podcast -site Notes for a new machine: podcasts/tts/models/ and podcasts/tts/samples/ are intentionally ignored by git and must be downloaded locally. podcasts/audio/ is intentionally ignored by git because audio files are published as GitHub Release assets. podcasts/bundles/*.md is intentionally ignored by git because chapter and appendix bundles are generated working files. podcasts/challenge-bundles/*.md is intentionally ignored by git because Challenge Coach bundles are generated working files. If python -m piper --help fails, Piper is not installed in the active Python environment. Regeneration Workflow Use this workflow after major content changes. Validate the catalog: npm run validate:podcasts Treat missing source files as blockers. Treat uncovered chapter or appendix warnings as planning work: either add episodes or intentionally leave those files out. Regenerate source bundles: npm run build:podcast -bundles npm run build:podcast -challenge-bundles Bundles are local source packets for transcript generation. They combine production prompts, concept checklists, issue templates, solution references, and source content. They should not be committed. Generate fresh draft scripts in podcasts/scripts/ . npm run generate:podcast -transcripts This removes old .txt scripts and old *-segments.json transcript files, then creates fresh companion and Challenge Coach draft transcripts from the current catalog metadata, source headings, issue templates, solution references, and challenge mappings. Review scripts manually before audio. Use the matching bundle as source context when editing. The output script is the committed transcript source of truth. Check for: Current schedule and event model Current challenge names and evidence requirements Alex/Jamie speaker balance No stale repository model language No overpromising live completion No visual-only instructions Pronounceable technical terms Generate audio: python -m podcasts.tts.generate_episode ep00 -welcome python -m podcasts.tts.generate_all --start 0 --end 10 Update the podcast page and RSS feed: npm run build:podcast -site npm run build:html Upload audio files from podcasts/audio/ to the GitHub Release tagged podcasts . Validate the repository: npm run validate:podcasts npm run test:automation git diff --check -- . ':(exclude)html/**' Challenge Episode Strategy Yes, every challenge should have teaching coverage. The challenge episodes should not merely read issue text aloud. They should coach the learner through the skill. Recommended structure for each challenge episode: Set t" + "body": "Podcast Regeneration Runbook This runbook explains how to rebuild the Git Going with GitHub podcast series after curriculum changes. Use it when chapters, appendices, agendas, or challenges change enough that the existing transcripts no longer match the source material. Current Strategy The podcast pipeline has two content layers that are published as one listening path. Companion episodes for chapters and appendices These are conversational overviews. They help learners preview or review concepts before reading the full material. Challenge teaching episodes These should teach the challenge in a guided, classroom style. They should explain the skill, model the learner's thinking, describe what success sounds like with a screen reader, and clarify what evidence the learner submits. The chapter and appendix episodes can stay broader and conceptual. The challenge episodes should be more tactical and should follow the Learning Room progression. The final public order is controlled by podcasts/listening-order.json , which places each challenge near the chapters that prepare learners for it. The refreshed companion catalog currently contains 54 episodes. The Challenge Coach layer currently has 21 generated source bundles: 16 core challenges plus 5 bonus challenges. Style Standard Keep the Alex and Jamie format. The banter is part of the accessibility design because it makes dense technical material easier to process. Alex: Warm expert guide. Explains concepts clearly, corrects misconceptions gently, and connects each task to real open source practice. Jamie: Curious co-host. Asks the questions a learner may hesitate to ask, restates the mental model, adds gentle humor, and names moments that feel confusing. Tone: Conversational, kind, practical, and lightly playful. Avoid: Stage directions, music cues, markdown tables in scripts, visual-only language, and jokes that pull attention away from the task. Every generated script must use only these markers on their own lines: [ALEX] [JAMIE] [PAUSE] New Machine Setup Run these commands from the repository root. The following commands install the required Node and Python dependencies for bundle generation, site generation, and local Piper TTS audio generation. npm install python -m pip install --upgrade pip python -m pip install piper -tts python -m podcasts.tts.download_samples Confirm the local tools work: npm run validate:podcasts npm run build:podcast -bundles npm run build:podcast -challenge-bundles npm run generate:podcast -transcripts python -m podcasts.tts.generate_episode ep00 -welcome npm run build:podcast -site Notes for a new machine: podcasts/tts/models/ and podcasts/tts/samples/ are intentionally ignored by git and must be downloaded locally. podcasts/audio/ is intentionally ignored by git because audio files are published as GitHub Release assets. podcasts/bundles/*.md is intentionally ignored by git because chapter and appendix bundles are generated working files. podcasts/challenge-bundles/*.md is intentionally ignored by git because Challenge Coach bundles are generated working files. If python -m piper --help fails, Piper is not installed in the active Python environment. Regeneration Workflow Use this workflow after major content changes. Validate the catalog: npm run validate:podcasts Treat missing source files as blockers. Treat uncovered chapter or appendix warnings as planning work: either add episodes or intentionally leave those files out. Regenerate source bundles: npm run build:podcast -bundles npm run build:podcast -challenge-bundles Bundles are local source packets for transcript generation. They combine production prompts, concept checklists, issue templates, solution references, and source content. They should not be committed. Generate fresh draft scripts in podcasts/scripts/ . npm run generate:podcast -transcripts This removes old .txt scripts and old *-segments.json transcript files, then creates fresh companion and Challenge Coach draft transcripts from the current catalog metadata, source headings, issue templates, solution references, and challenge mappings. Review scripts manually before audio. Use the matching bundle as source context when editing. The output script is the committed transcript source of truth. Check for: Current schedule and event model Current challenge names and evidence requirements Alex/Jamie speaker balance No stale repository model language No overpromising live completion No visual-only instructions Pronounceable technical terms Generate audio: python -m podcasts.tts.generate_all_kokoro --start 0 --end 0 --force --audio-format mp3 python -m podcasts.tts.generate_all_kokoro --start 0 --end 10 --audio-format mp3 Update the podcast page and RSS feed: npm run build:podcast -site npm run build:html Upload audio files from podcasts/audio/ to the GitHub Release tagged podcasts . Validate the repository: npm run validate:podcasts npm run test:automation git diff --check -- . ':(exclude)html/**' Challen" }, { "id": "learning-room/docs/keyboard-shortcuts.html", @@ -591,7 +591,7 @@ "id": "learning-room/index.html", "title": "Welcome to the Learning Room", "url": "learning-room/index.html", - "body": "Welcome to the Learning Room This repository is your private Learning Room for the Git Going with GitHub workshop. GitHub Classroom created it from the Learning Room template so you can practice the full contribution workflow safely. In this repository you will: File your first issue Leave your first comment Open your first pull request Review a peer's pull request when facilitators pair you for review Everything in this repository is designed for learning. The files in docs/ have intentional issues that you will find and fix during the workshop contribution sprint. What Is in This Repository Folder / File Purpose docs/welcome.md Introduction to contributing (has some sections to complete) docs/keyboard-shortcuts.md Keyboard shortcut reference (has some errors to find and fix) docs/setup-guide.md Setup instructions (has some broken links and gaps) How to Contribute Open the canonical challenge list: ../docs/CHALLENGES.md Find your assigned issue (Issues tab -> filter by "Assignee: me" or search your username in the issue title) Claim the issue with a comment: I'd like to try this! Read the issue description - it tells you which file to edit and what to fix Click the file -> the edit pencil button -> make your change Commit to a new branch with a descriptive name: fix/[your-name]-[issue-number] Open a pull request using the PR template and include Closes #XX Wait for the bot (~30 seconds) - it will check your changes and provide feedback Read bot feedback carefully - it explains any issues and links to resources Make changes if needed based on feedback Request a review from your assigned peer reviewer Respond to review feedback and make final improvements Merge when approved (the issue closes automatically) Add a final issue comment with what you learned and your merged PR link See the workshop documentation for full step-by-step guidance. About the Automation Bot When you open a pull request, an automated bot will: Check your changes against quality standards Validate accessibility (heading hierarchy, link text, alt text, broken links) Provide educational feedback explaining why things matter Link to resources for learning more Apply labels to help facilitators prioritize reviews The bot is not a substitute for peer review! It provides instant technical feedback so your human reviewers can focus on higher-level improvements, creative suggestions, and encouragement. How to Interact with the Bot Reading Bot Comments: Bot posts ONE comment that updates as you make changes Use headings to navigate (Required Checks, Suggestions, Accessibility Analysis, Resources) Each issue includes file/line numbers and how to fix it Getting Help from the Bot: Comment on your PR with keywords: @bot help - Get help information Mention "merge conflict" - Get conflict resolution guide Mention "request review" - Get instructions for requesting human review When You Disagree: The bot isn't always right! If you believe feedback is incorrect: Comment explaining your reasoning Request human review Facilitators can override bot checks Read the Student Guide → Skills & Progression As you complete challenges, you'll: Track progress through skill levels (Explorer, Contributor, Collaborator, Operator, Reviewer, Agent Navigator) Unlock new challenges when you reach milestones Earn badges for specific achievements (Branch Builder, PR Pioneer, Conflict Resolver, and more) Celebrate milestones (first challenge, Day 1 complete, all challenges complete) View Available Challenges → Follow the Full Course Roadmap → Stuck? Use Guided References Solutions Index - challenge-by-challenge worked examples Challenge Hub bonus challenges - optional advanced practice adapted from GitHub Skills Use these references after you attempt the challenge yourself. They are designed to unblock you, not replace your own practice. Study Groups You may be assigned to a study group for collaborative learning. Groups: Work through challenges together Review each other's PRs Share resources and tips Support each other's learning If assigned to a group, you'll receive an issue thread for communication. Code of Conduct All participants and contributors are expected to follow our Code of Conduct . This is a welcoming, accessible space. Questions? Open an issue! Use the "Feature or Improvement Request" template if you have a suggestion, or the "Accessibility Bug Report" template if you find an accessibility issue." + "body": "Table: Learning Room folder and file purposes Table: Host voice and character mapping for VibeVoice podcast Welcome to the Learning Room This repository is your private Learning Room for the Git Going with GitHub workshop. GitHub Classroom created it from the Learning Room template so you can practice the full contribution workflow safely. In this repository you will: File your first issue Leave your first comment Open your first pull request Review a peer's pull request when facilitators pair you for review Everything in this repository is designed for learning. The files in docs/ have intentional issues that you will find and fix during the workshop contribution sprint. What Is in This Repository Folder / File Purpose docs/welcome.md Introduction to contributing (has some sections to complete) docs/keyboard-shortcuts.md Keyboard shortcut reference (has some errors to find and fix) docs/setup-guide.md Setup instructions (has some broken links and gaps) How to Contribute Open the canonical challenge list: ../docs/CHALLENGES.md Find your assigned issue (Issues tab -> filter by "Assignee: me" or search your username in the issue title) Claim the issue with a comment: I'd like to try this! Read the issue description - it tells you which file to edit and what to fix Click the file -> the edit pencil button -> make your change Commit to a new branch with a descriptive name: fix/[your-name]-[issue-number] Open a pull request using the PR template and include Closes #XX Wait for the bot (~30 seconds) - it will check your changes and provide feedback Read bot feedback carefully - it explains any issues and links to resources Make changes if needed based on feedback Request a review from your assigned peer reviewer Respond to review feedback and make final improvements Merge when approved (the issue closes automatically) Add a final issue comment with what you learned and your merged PR link See the workshop documentation for full step-by-step guidance. About the Automation Bot When you open a pull request, an automated bot will: Check your changes against quality standards Validate accessibility (heading hierarchy, link text, alt text, broken links) Provide educational feedback explaining why things matter Link to resources for learning more Apply labels to help facilitators prioritize reviews The bot is not a substitute for peer review! It provides instant technical feedback so your human reviewers can focus on higher-level improvements, creative suggestions, and encouragement. How to Interact with the Bot Reading Bot Comments: Bot posts ONE comment that updates as you make changes Use headings to navigate (Required Checks, Suggestions, Accessibility Analysis, Resources) Each issue includes file/line numbers and how to fix it Getting Help from the Bot: Comment on your PR with keywords: @bot help - Get help information Mention "merge conflict" - Get conflict resolution guide Mention "request review" - Get instructions for requesting human review When You Disagree: The bot isn't always right! If you believe feedback is incorrect: Comment explaining your reasoning Request human review Facilitators can override bot checks Read the Student Guide → Skills & Progression As you complete challenges, you'll: Track progress through skill levels (Explorer, Contributor, Collaborator, Operator, Reviewer, Agent Navigator) Unlock new challenges when you reach milestones Earn badges for specific achievements (Branch Builder, PR Pioneer, Conflict Resolver, and more) Celebrate milestones (first challenge, Day 1 complete, all challenges complete) View Available Challenges → Follow the Full Course Roadmap → Stuck? Use Guided References Solutions Index - challenge-by-challenge worked examples Challenge Hub bonus challenges - optional advanced practice adapted from GitHub Skills Use these references after you attempt the challenge yourself. They are designed to unblock you, not replace your own practice. Study Groups You may be assigned to a study group for collaborative learning. Groups: Work through challenges together Review each other's PRs Share resources and tips Support each other's learning If assigned to a group, you'll receive an issue thread for communication. Code of Conduct All participants and contributors are expected to follow our Code of Conduct . This is a welcoming, accessible space. Questions? Open an issue! Use the "Feature or Improvement Request" template if you have a suggestion, or the "Accessibility Bug Report" template if you find an accessibility issue." }, { "id": "scripts/vibevoice/index.html", @@ -603,7 +603,7 @@ "id": "admin/REGISTRATION-ADMIN.html", "title": "Registration Administration Guide", "url": "admin/REGISTRATION-ADMIN.html", - "body": "Registration Administration Guide This document explains how the registration system works and how to manage it, including optional API-based classroom invitation automation. If you just need implementation steps, start with REGISTRATION-QUICKSTART.md . How Registration Tracking Works Registration Count (Website) The registration page at REGISTER.html queries the GitHub Search API in real time every time a visitor loads the page. It counts open issues with the registration label. No CSV or local data is involved. Capacity Check (Workflow) When someone submits a registration issue, the GitHub Actions workflow queries all issues labeled registration and counts unique GitHub usernames. If the count is at or above 75, the registrant is placed on the waitlist instead. Optional Classroom API Automation When configured, the registration workflow can also: Check whether the registrant is already in the classroom organization Send an organization invitation if needed Include Day 1 and Day 2 GitHub Classroom assignment links in the welcome comment Important: This does not bypass GitHub Classroom acceptance. Students still must click the assignment link and accept. Full API Setup (Classroom Automation) Use these steps to enable end-to-end registration plus classroom invitation flow. 1. Create an admin token for organization invites Create a GitHub personal access token for a facilitator/admin account with permission to manage organization invitations. Recommended minimum permissions: Organization administration permissions sufficient to create invitations Repository read access for this repository Store this token securely. Do not commit it to the repository. 2. Add repository secret In repository settings, add this secret: CLASSROOM_ORG_ADMIN_TOKEN = token from Step 1 3. Add repository variables In repository settings, add these variables: CLASSROOM_ORG = your classroom org name (example: Community-Access-Classroom ) CLASSROOM_DAY1_ASSIGNMENT_URL = Day 1 Classroom invite URL CLASSROOM_DAY2_ASSIGNMENT_URL = Day 2 Classroom invite URL If you omit these variables/secrets, registration still works; only the classroom automation steps are skipped. 4. Confirm workflow behavior After setup, successful non-duplicate registrations should produce: Standard registration confirmation logic (registration label and capacity handling) Organization invite status handling: invited (new invite sent) already-invited (pending invite exists) already-member (user already in org) Welcome comment including classroom assignment links (if configured) 5. End-to-end test checklist Run this once before opening registration publicly: Submit a test registration issue from a non-member test account. Verify an org invitation is sent. Verify Day 1/Day 2 assignment links appear in the welcome comment. Accept org invite from the test account. Accept Day 1 assignment link from the test account. Confirm private classroom repo is created. Submit a second registration from the same account and confirm duplicate handling. 6. Operational notes The automation runs only when capacity is available and the registration is not a duplicate. Waitlisted users are not invited automatically by this workflow. Assignment acceptance remains student-driven in GitHub Classroom. 7. Rollback plan If invitation automation causes issues: Remove CLASSROOM_ORG_ADMIN_TOKEN secret (fastest stop switch), or Clear CLASSROOM_ORG variable. Registration confirmations and CSV export continue to function without classroom API steps. CSV Export The CSV is a convenience export for reviewing registrations in spreadsheet form. It is regenerated from scratch (from the issues) every time someone registers or when the workflow is manually triggered. The issues are the source of truth, not the CSV. The CSV is uploaded as a workflow artifact (retained for 90 days) and is only accessible to repository collaborators. It is not committed to the repository. Downloading the CSV Using the GitHub CLI Download the latest registration CSV: gh run download --name registrations --dir ./registrations -R community -access /git -going-with-github List recent workflow runs first to pick a specific one: gh run list --workflow =registration.yml -R community -access /git -going-with-github gh run download <run -id > --name registrations --dir ./registrations -R community -access /git -going-with-github Using the GitHub Web UI Go to the repository on GitHub Click the Actions tab Click a Registration - Welcome & CSV Export workflow run Scroll down to the Artifacts section Click registrations to download the CSV Regenerating the CSV On Demand To rebuild the CSV from all current registration issues (e.g., right before the workshop): gh workflow run registration.yml -R community -access /git -going-with-github This triggers the workflow_dispatch event, which rebuilds the CSV from all registration issues and uploads a fresh artifact. Registration Scenarios The workflow handles three scenarios when someone subm" + "body": "Registration Administration Guide This document explains how the registration system works and how to manage it, including optional API-based classroom invitation automation. If you just need implementation steps, start with REGISTRATION-QUICKSTART.md . How Registration Tracking Works Registration Count (Website) The registration page at REGISTER.html queries the GitHub Search API in real time every time a visitor loads the page. It counts open issues with the registration label. No CSV or local data is involved. Capacity Check (Workflow) When someone submits a registration issue, the GitHub Actions workflow queries all issues labeled registration and counts unique GitHub usernames. If the count is at or above 75, the registrant is placed on the waitlist instead. Optional Classroom API Automation When configured, the registration workflow can also: Check whether the registrant is already in the classroom organization Send an organization invitation if needed Include Day 1 and Day 2 GitHub Classroom assignment links in the welcome comment Important: This does not bypass GitHub Classroom acceptance. Students still must click the assignment link and accept. Full API Setup (Classroom Automation) Use these steps to enable end-to-end registration plus classroom invitation flow. 1. Create an admin token for organization invites Create a GitHub personal access token for a facilitator/admin account with permission to manage organization invitations. Recommended minimum permissions: Organization administration permissions sufficient to create invitations Repository read access for this repository Store this token securely. Do not commit it to the repository. 2. Add repository secret In repository settings, add this secret: CLASSROOM_ORG_ADMIN_TOKEN = token from Step 1 3. Add repository variables In repository settings, add these variables: CLASSROOM_ORG = your classroom org name (example: Community-Access-Classroom ) CLASSROOM_DAY1_ASSIGNMENT_URL = Day 1 Classroom invite URL CLASSROOM_DAY2_ASSIGNMENT_URL = Day 2 Classroom invite URL If you omit these variables/secrets, registration still works; only the classroom automation steps are skipped. 4. Confirm workflow behavior After setup, successful non-duplicate registrations should produce: Standard registration confirmation logic (registration label and capacity handling) Organization invite status handling: invited (new invite sent) already-invited (pending invite exists) already-member (user already in org) Welcome comment including classroom assignment links (if configured) 5. End-to-end test checklist Run this once before opening registration publicly: Submit a test registration issue from a non-member test account. Verify an org invitation is sent. Verify Day 1/Day 2 assignment links appear in the welcome comment. Accept org invite from the test account. Accept Day 1 assignment link from the test account. Confirm private classroom repo is created. Submit a second registration from the same account and confirm duplicate handling. 6. Operational notes The automation runs only when capacity is available and the registration is not a duplicate. Waitlisted users are not invited automatically by this workflow. Assignment acceptance remains student-driven in GitHub Classroom. 7. Rollback plan If invitation automation causes issues: Remove CLASSROOM_ORG_ADMIN_TOKEN secret (fastest stop switch), or Clear CLASSROOM_ORG variable. Registration confirmations and CSV export continue to function without classroom API steps. CSV Export The CSV is a convenience export for reviewing registrations in spreadsheet form. It is regenerated from scratch (from the issues) every time someone registers or when the workflow is manually triggered. The issues are the source of truth, not the CSV. The CSV is uploaded as a workflow artifact (retained for 90 days) and is only accessible to repository collaborators. It is not committed to the repository. Downloading the CSV Using the GitHub CLI Download the latest registration CSV: gh run download --name registrations --dir ./registrations -R community -access /git -going-with-github List recent workflow runs first to pick a specific one: gh run list --workflow =registration.yml -R community -access /git -going-with-github gh run download <run -id > --name registrations --dir ./registrations -R community -access /git -going-with-github Using the GitHub Web UI Go to the repository on GitHub Click the Actions tab Click a Registration - Welcome & CSV Export workflow run Scroll down to the Artifacts section Click registrations to download the CSV Regenerating the CSV On Demand To rebuild the CSV from all current registration issues (e.g., right before the workshop): gh workflow run registration.yml -R community -access /git -going-with-github This triggers the workflow_dispatch event, which rebuilds the CSV from all registration issues and uploads a fresh artifact. Resetting Support Environment (From Top) If you need to rebuild the support e" }, { "id": "admin/STUDENT_MANAGEMENT.html", @@ -621,7 +621,7 @@ "id": "admin/ANNOUNCEMENT.html", "title": "GIT Going with GitHub", "url": "admin/ANNOUNCEMENT.html", - "body": "GIT Going with GitHub License: CC BY 4.0 | View Site | Full Curriculum | Discussion Forum You Belong in Open Source. Let Us Show You the Door. Note: Workshop content is being actively refined before the workshop. Students should expect updates to materials leading up to and during the course. A Two-Day Workshop by Community Access Sponsored by Community Access in partnership with GitHub . Detail Information Dates May 21, 2026 & May 22, 2026 Time 9:00 AM - 5:00 PM Pacific (both days) Location GitHub headquarters in San Francisco, with remote-ready materials for future cohorts Cost Free Facilitators Jeff Bishop and Michael Babcock Presented by Community Access In partnership with GitHub Registration is now closed. Thank you to everyone who registered - let the learning begin! Want to join a future cohort? Use the Student Opt-In page . It feeds directly into our automated registration and waitlist workflow. Join the conversation! Have a question before the workshop? Want to connect with other participants? Head to our Discussion Forum - introduce yourself, ask questions, and start building your network before Day 1. Already registered? Complete the Pre-Workshop Setup Guide before the workshop. It walks you through every step - GitHub account, screen reader configuration, VS Code , and GitHub Copilot - with instructions for NVDA, JAWS, and VoiceOver. Get set up early so Day 1 starts with learning, not troubleshooting. What Is This? This is a two-day, hands-on workshop where blind and low vision participants learn to navigate, contribute to, and build real open source projects on GitHub - using a screen reader, a keyboard, and nothing else. No mouse. No sighted assistance. No pretending. By the end of Day 2, you will have practiced the workflow used to contribute to live, public open source projects. Some participants will ship during the event; others will leave with a branch, pull request path, and clear next steps to finish after the live session. This workshop exists because open source software powers the world - and the people who use assistive technology every day deserve to be the ones shaping it. Not just filing complaints. Building. Reviewing. Shipping. Powered by Accessibility Agents On Day 2, you will work with Accessibility Agents - a real, MIT-licensed open source project with 55 AI agents across 3 teams and 5 platforms, built for accessible software development, project management, and community collaboration. Daily briefings, issue triage, PR review, accessibility monitoring, analytics - all driven by AI, all designed for screen reader users. You will fork it, understand it, improve it, and personalize it. The live workshop prepares you to contribute, and the continuation path gives you time to polish your work before it is reviewed. Who Should Attend? This workshop is designed for: Blind and low vision individuals who want to learn GitHub and open source contribution Screen reader users ( NVDA , JAWS , or VoiceOver ) at any skill level People who have never used GitHub before - no prior experience required Developers who use assistive technology and want to sharpen their open source workflow Anyone curious about accessible development - sighted participants are welcome; all content is fully keyboard-navigable You do not need to know how to write code. Seriously. Documentation improvements, accessibility bug reports, issue filing, and code reviews are all real, valued contributions. Some of the most impactful open source work never touches a line of code. What You Will Walk Away With By the end of this workshop, you will have: Filed real issues on a real GitHub repository Opened, reviewed, and merged real pull requests Your name permanently in the commit history of a public accessibility project Hands-on instruction in basic Visual Studio Code usage as it relates to GitHub - navigation, source control, extensions, and screen reader configuration A working VS Code setup with GitHub Copilot and 55 AI agents configured The confidence to navigate any GitHub repository with your screen reader A network of peers who understand the intersection of accessibility and open source These are not hypothetical outcomes. Every participant ships something real. The Two-Day Journey Day 1 - GitHub Foundations (Browser + Screen Reader) Your screen reader and keyboard are the only tools you need. Everything happens in the browser. Block What Happens Welcome and Setup Check Introductions, verify everyone's screen reader and browser are ready Screen Reader Orientation to GitHub Navigate GitHub pages using headings, landmarks, and keyboard shortcuts Navigating Repositories Explore a real repository - files, branches, commits, contributors Working with Issues Search, file, comment on, and triage issues using Markdown Understanding Pull Requests Read diffs, write inline review comments, approve and merge Your First Contribution Sprint Make a real contribution in your private Learning Room repository - with automa" + "body": "GIT Going with GitHub License: CC BY 4.0 | View Site | Full Curriculum | Support Hub You Belong in Open Source. Let Us Show You the Door. Note: Workshop content is being actively refined before the workshop. Students should expect updates to materials leading up to and during the course. A Two-Day Workshop by Community Access Sponsored by Community Access in partnership with GitHub . Detail Information Dates May 21, 2026 & May 22, 2026 Time 9:00 AM - 5:00 PM Pacific (both days) Location GitHub headquarters in San Francisco, with remote-ready materials for future cohorts Cost Free Facilitators Jeff Bishop and Michael Babcock Presented by Community Access In partnership with GitHub Registration is now closed. Thank you to everyone who registered - let the learning begin! Want to join a future cohort? Use the Student Opt-In page . It feeds directly into our automated registration and waitlist workflow. Join the conversation! Have a question before the workshop? Want to connect with other participants? Head to our Support Hub Discussions - introduce yourself, ask questions, and start building your network before Day 1. Already registered? Complete the Pre-Workshop Setup Guide before the workshop. It walks you through every step - GitHub account, screen reader configuration, VS Code , and GitHub Copilot - with instructions for NVDA, JAWS, and VoiceOver. Get set up early so Day 1 starts with learning, not troubleshooting. What Is This? This is a two-day, hands-on workshop where blind and low vision participants learn to navigate, contribute to, and build real open source projects on GitHub - using a screen reader, a keyboard, and nothing else. No mouse. No sighted assistance. No pretending. By the end of Day 2, you will have practiced the workflow used to contribute to live, public open source projects. Some participants will ship during the event; others will leave with a branch, pull request path, and clear next steps to finish after the live session. This workshop exists because open source software powers the world - and the people who use assistive technology every day deserve to be the ones shaping it. Not just filing complaints. Building. Reviewing. Shipping. Powered by Accessibility Agents On Day 2, you will work with Accessibility Agents - a real, MIT-licensed open source project with 55 AI agents across 3 teams and 5 platforms, built for accessible software development, project management, and community collaboration. Daily briefings, issue triage, PR review, accessibility monitoring, analytics - all driven by AI, all designed for screen reader users. You will fork it, understand it, improve it, and personalize it. The live workshop prepares you to contribute, and the continuation path gives you time to polish your work before it is reviewed. Who Should Attend? This workshop is designed for: Blind and low vision individuals who want to learn GitHub and open source contribution Screen reader users ( NVDA , JAWS , or VoiceOver ) at any skill level People who have never used GitHub before - no prior experience required Developers who use assistive technology and want to sharpen their open source workflow Anyone curious about accessible development - sighted participants are welcome; all content is fully keyboard-navigable You do not need to know how to write code. Seriously. Documentation improvements, accessibility bug reports, issue filing, and code reviews are all real, valued contributions. Some of the most impactful open source work never touches a line of code. What You Will Walk Away With By the end of this workshop, you will have: Filed real issues on a real GitHub repository Opened, reviewed, and merged real pull requests Your name permanently in the commit history of a public accessibility project Hands-on instruction in basic Visual Studio Code usage as it relates to GitHub - navigation, source control, extensions, and screen reader configuration A working VS Code setup with GitHub Copilot and 55 AI agents configured The confidence to navigate any GitHub repository with your screen reader A network of peers who understand the intersection of accessibility and open source These are not hypothetical outcomes. Every participant ships something real. The Two-Day Journey Day 1 - GitHub Foundations (Browser + Screen Reader) Your screen reader and keyboard are the only tools you need. Everything happens in the browser. Block What Happens Welcome and Setup Check Introductions, verify everyone's screen reader and browser are ready Screen Reader Orientation to GitHub Navigate GitHub pages using headings, landmarks, and keyboard shortcuts Navigating Repositories Explore a real repository - files, branches, commits, contributors Working with Issues Search, file, comment on, and triage issues using Markdown Understanding Pull Requests Read diffs, write inline review comments, approve and merge Your First Contribution Sprint Make a real contribution in your private Learning Room repository - with auto" }, { "id": "admin/COHORT_PROVISIONING.html", @@ -681,7 +681,7 @@ "id": "admin/PODCASTS.html", "title": "Podcasts", "url": "admin/PODCASTS.html", - "body": "Podcasts Git Going with GitHub - Audio Series Listen to companion audio episodes for every chapter and appendix in this workshop. Each episode is a standalone teaching conversation between hosts Alex and Jamie, written so learners can understand the concepts even before opening the chapter. Every episode includes a full transcript below the player. Subscribe: Add the podcast RSS feed to your preferred podcast app - Apple Podcasts, Spotify, Overcast, or any RSS reader. Transcripts: Every episode includes a complete, readable transcript. Expand the "Read Transcript" section below any episode to follow along or search the conversation. How to Use These Episodes Before a chapter: Listen to build the mental model before diving into the exercises. After a chapter: Listen to reinforce the concepts and catch anything you missed. On the go: Episodes are 8-18 minutes each. Listen during commutes, walks, or breaks. Day 1: GitHub Foundations Episode 0: Welcome to Git Going with GitHub A tour of the workshop structure, the two-day arc, and what you will accomplish. Based on: Course Guide Audio and transcript are being regenerated for this episode. Read Transcript - Episode 0: Welcome to Git Going with GitHub Transcript Alex: Welcome to Git Going with GitHub, episode 0: Welcome to Git Going with GitHub. I am Alex. Today we are going to make the shape of the workshop something you can explain, practice, and recover from when the interface surprises you. Jamie: And I am Jamie. I will be the voice of the learner who is willing to ask, what is this for, where am I, and how do I know I did it right? Alex: The big idea today: A tour of the workshop structure, the two-day arc, and what you will accomplish. We will name the concept, explain why it matters, practice the move, and point out the checks that tell you the work is real. Jamie: So the episode should work even if someone has not read the chapter yet. Alex: Exactly. The transcript has to stand on its own. It can point toward practice, but it should teach the concept right here in the conversation. Jamie: How should they picture the shape of the workshop? Alex: Start with GitHub Learning Room - Your Complete Workshop Companion: the learner is about to begin a two-day journey into open source collaboration using GitHub, VS Code, and GitHub Copilot - all designed for screen reader and keyboard-only navigation. The next useful detail is this: This guide is your starting point and table of contents for everything in this workshop. Alex: The next layer is this. Here is the plain-English version of How This Course Works. This is a two-day workshop built around one idea: you will make real contributions to a real open source project. It is like learning a transit route. The names of the stops matter because they tell you whether you are still going the right direction. Jamie: What should feel predictable before the first live session starts? Alex: This is where Live Agenda and Self-Paced Curriculum becomes real: the live hackathon agenda is intentionally smaller than the full curriculum. That matters in practice: Live sessions prioritize the core contribution path, while the complete chapter set remains available for self-paced preparation, catch-up, remote participation, and post-event continuation. Alex: That shows up in the workshop in a few specific ways. Live core: The facilitator chooses the minimum path needed for participants to make and understand a real contribution. Async follow-up: Chapters and challenges not covered live can be completed after the session using the Learning Room, solutions, podcasts, and Slack channel. Remote participation: Remote cohorts should use the same checkpoints and evidence prompts, with written instructions available before each live block. Alex: Now bring the learner back to the room. Keep the learner anchored in Day 1 - GitHub Foundations (Browser). You learn GitHub's web interface using only your keyboard and screen reader. This is the part to say slowly: The live Day 1 core path gets you through repository navigation, issues, branches, commits, and a first pull request. Jamie: Where is the promise of the workshop, underneath all the logistics? Alex: The reason Day 2 - VS Code + Accessibility Agents (Desktop) matters is that you move to Visual Studio Code, learn GitHub Copilot, and activate the Accessibility Agents ecosystem - 55 AI agents across 3 teams and 5 platforms that amplify every skill you built on Day 1. That gives the learner a simple foothold: the live Day 2 core path prepares you to make a real contribution, and the async continuation path gives you time to polish and submit it well. Alex: The useful habit is simple: orient first, act second, verify third. That pause before acting is part of the work. Alex: That matters because of the next idea. Start with The Journey Arc: The key principle: Learn the manual skill first, then see how it is automated. The next useful detail is this: The agents only make sense w" + "body": "Podcasts Git Going with GitHub - Audio Series Listen to the workshop as one end-to-end path. Companion lessons, Challenge Coach episodes, and reference material are interleaved so learners can hear the concept, practice it, and then keep moving through the course. Every episode includes a full transcript below the player. Subscribe: Add the podcast RSS feed to your preferred podcast app - Apple Podcasts, Spotify, Overcast, or any RSS reader. Transcripts: Every episode includes a complete, readable transcript. Expand the "Read Transcript" section below any episode to follow along or search the conversation. How to Use These Episodes Follow the path: Listen in order when you want the full workshop experience. Practice in place: Challenge Coach episodes appear near the chapters that prepare you for that task. Use references when needed: Appendix and reference episodes are placed near the moments where they help most. Start Here 1. Episode 0: Welcome to Git Going with GitHub A tour of the workshop structure, the two-day arc, and what you will accomplish. Based on: Course Guide Your browser does not support the audio element. Download Episode 0 (MP3) Download Episode 0 (MP3) Read Transcript - Episode 0: Welcome to Git Going with GitHub Transcript Alex: Welcome to Git Going with GitHub, episode 0: Welcome to Git Going with GitHub. I am Alex. Today we are going to make the shape of the workshop something you can explain, practice, and recover from when the interface surprises you. Jamie: And I am Jamie. I will be the voice of the learner who is willing to ask, what is this for, where am I, and how do I know I did it right? Alex: The big idea today: A tour of the workshop structure, the two-day arc, and what you will accomplish. We will name the concept, explain why it matters, practice the move, and point out the checks that tell you the work is real. Jamie: So the episode should work even if someone has not read the chapter yet. Alex: Exactly. The transcript has to stand on its own. It can point toward practice, but it should teach the concept right here in the conversation. Jamie: How should they picture the shape of the workshop? Alex: Start with GitHub Learning Room - Your Complete Workshop Companion: the learner is about to begin a two-day journey into open source collaboration using GitHub, VS Code, and GitHub Copilot - all designed for screen reader and keyboard-only navigation. The next useful detail is this: This guide is your starting point and table of contents for everything in this workshop. Alex: The next layer is this. Here is the plain-English version of How This Course Works. This is a two-day workshop built around one idea: you will make real contributions to a real open source project. It is like learning a transit route. The names of the stops matter because they tell you whether you are still going the right direction. Jamie: What should feel predictable before the first live session starts? Alex: This is where Live Agenda and Self-Paced Curriculum becomes real: the live hackathon agenda is intentionally smaller than the full curriculum. That matters in practice: Live sessions prioritize the core contribution path, while the complete chapter set remains available for self-paced preparation, catch-up, remote participation, and post-event continuation. Alex: That shows up in the workshop in a few specific ways. Live core: The facilitator chooses the minimum path needed for participants to make and understand a real contribution. Async follow-up: Chapters and challenges not covered live can be completed after the session using the Learning Room, solutions, podcasts, and Slack channel. Remote participation: Remote cohorts should use the same checkpoints and evidence prompts, with written instructions available before each live block. Alex: Now bring the learner back to the room. Keep the learner anchored in Day 1 - GitHub Foundations (Browser). You learn GitHub's web interface using only your keyboard and screen reader. This is the part to say slowly: The live Day 1 core path gets you through repository navigation, issues, branches, commits, and a first pull request. Jamie: Where is the promise of the workshop, underneath all the logistics? Alex: The reason Day 2 - VS Code + Accessibility Agents (Desktop) matters is that you move to Visual Studio Code, learn GitHub Copilot, and activate the Accessibility Agents ecosystem - 55 AI agents across 3 teams and 5 platforms that amplify every skill you built on Day 1. That gives the learner a simple foothold: the live Day 2 core path prepares you to make a real contribution, and the async continuation path gives you time to polish and submit it well. Alex: The useful habit is simple: orient first, act second, verify third. That pause before acting is part of the work. Alex: That matters because of the next idea. Start with The Journey Arc: The key principle: Learn the manual skill first, then see how it is automated. The next useful detail i" }, { "id": "admin/PROGRESS_TRACKER.html", @@ -699,7 +699,7 @@ "id": "admin/REGISTER.html", "title": "Student Opt-In", "url": "admin/REGISTER.html", - "body": "Student Opt-In Back to Home | Discussion Forum | Pre-Workshop Setup Guide Join the next GIT Going with GitHub cohort This page is a fast, self-serve opt-in workflow. Students can opt in directly from GitHub Pages with no instructor handoff required. Status Open for student opt-in Current confirmed registrations Loading... Cost Free Format Current workshop is in person; future cohorts may include remote participation Quick opt-in workflow Sign in to your GitHub account . Open the registration issue form: Start Student Opt-In Form Submit the form with your details. What happens automatically after you submit The workflow confirms your registration if capacity is available. Duplicate submissions are detected and handled automatically. If capacity is full, your issue is automatically placed on the waitlist. Your GitHub username is captured automatically from your account. Important notes This repository is public. Your submitted registration issue is publicly visible. If you are not signed in, GitHub will ask you to sign in before you can submit the form. The issue title is pre-filled and should stay as provided. After you opt in Check your issue for the automated confirmation or waitlist comment. Complete the Pre-Workshop Setup Guide . Introduce yourself in the Discussion Forum . Need help? Questions or access issues are welcome. File an issue Join the Discussion Forum A Community Access initiative." + "body": "Student Opt-In Back to Home | Support Hub | Pre-Workshop Setup Guide Join the next GIT Going with GitHub cohort This page is a fast, self-serve opt-in workflow. Students can opt in directly from GitHub Pages with no instructor handoff required. Status Open for student opt-in Current confirmed registrations Loading... Cost Free Format Current workshop is in person; future cohorts may include remote participation Quick opt-in workflow Sign in to your GitHub account . Open the registration issue form: Start Student Opt-In Form Submit the form with your details. What happens automatically after you submit The workflow confirms your registration if capacity is available. Duplicate submissions are detected and handled automatically. If capacity is full, your issue is automatically placed on the waitlist. Your GitHub username is captured automatically from your account. Important notes This repository is public. Your submitted registration issue is publicly visible. If you are not signed in, GitHub will ask you to sign in before you can submit the form. The issue title is pre-filled and should stay as provided. After you opt in Check your issue for the automated confirmation or waitlist comment. Complete the Pre-Workshop Setup Guide . Introduce yourself in Support Hub Discussions . Need help? Questions or access issues are welcome. File a support issue Join Support Hub Discussions A Community Access initiative." }, { "id": "admin/STUDENT_ONBOARDING_EMAIL.html", @@ -741,7 +741,7 @@ "id": "admin/index.html", "title": "Admin & Facilitator Resources", "url": "admin/index.html", - "body": "Admin & Facilitator Resources This folder contains all administrative and facilitator documentation for running GitHub Classroom workshops. Facilitator Resources Start here if you're running a workshop: Quick Navigation FACILITATOR_RESOURCES.md - Navigation hub for all facilitator guides FACILITATOR_GUIDE.md - Complete workshop bible (setup through post-workshop) FACILITATOR_OPERATIONS.md - Hour-by-hour procedures during workshop FACILITATOR_CLASSROOM_TROUBLESHOOTING.md - Problem-solving guide ../GO-LIVE-QA-GUIDE.md - Final release-readiness guide and end-to-end test checklist Supporting Guides FACILITATOR_CHALLENGES.md - Managing the challenge system FACILITATOR_ASSESSMENT.md - Assessment and grading rubric Student And Enrollment Management STUDENT_MANAGEMENT.md - Managing student rosters, enrollments, tracking REGISTRATION-ADMIN.md - Registration process administration and API classroom automation setup REGISTRATION-QUICKSTART.md - 5-minute facilitator setup for registration + classroom API automation STUDENT_ONBOARDING_EMAIL.md - Template email for student onboarding Workshop Planning And Organization DAY1_AGENDA.md - Day 1 schedule and agenda DAY2_AGENDA.md - Day 2 schedule and agenda DAY2_QUICK_START.md - Quick start guide for Day 2 QUICK_REFERENCE.md - Quick reference card for facilitators PROGRESS_TRACKER.md - Tracking student progress Setup And Deployment COHORT_PROVISIONING.md - Setting up a new cohort ACCESSIBILITY_TESTING.md - Testing workshop for accessibility VALIDATION_AUDIT.md - Validating everything works classroom/README.md - Copy-paste classroom setup pack (assignments, autograding, seeding) ../GO-LIVE-QA-GUIDE.md - Complete pre-cohort QA gate for content, workflows, Classroom, podcasts, and human testing Communications ANNOUNCEMENT.md - Workshop announcement templates FAQ.md - Frequently asked questions Reference And Support TROUBLESHOOTING.md - General troubleshooting reference REGISTER.md - Student registration information GITHUB_PROPOSAL.md - GitHub partnership/proposal documentation PODCASTS.md - Podcast episode notes and references Typical Workflow Planning Phase (Weeks 1-2 Before) COHORT_PROVISIONING.md - Set up the cohort FACILITATOR_GUIDE.md - GitHub Classroom setup ANNOUNCEMENT.md - Create student announcements STUDENT_MANAGEMENT.md - Prepare roster Pre-Workshop (48 Hours Before) FACILITATOR_GUIDE.md - Complete checklist ACCESSIBILITY_TESTING.md - Test with screen readers FACILITATOR_OPERATIONS.md - Setup workstation During Workshop FACILITATOR_OPERATIONS.md - Follow hour-by-hour procedures FACILITATOR_CLASSROOM_TROUBLESHOOTING.md - Reference when needed PROGRESS_TRACKER.md - Track student progress Post-Workshop FACILITATOR_GUIDE.md - Follow-up tasks Update this documentation with lessons learned Reading Order Recommendations For First-Time Facilitators Start: FACILITATOR_RESOURCES.md Then: FACILITATOR_GUIDE.md (full read) Then: FACILITATOR_OPERATIONS.md (full read) Reference: FACILITATOR_CLASSROOM_TROUBLESHOOTING.md For Returning Facilitators Quick reference: QUICK_REFERENCE.md Review: FACILITATOR_GUIDE.md checklist Keep open: FACILITATOR_OPERATIONS.md during workshop For Admin/Coordinators COHORT_PROVISIONING.md - Setup cohorts STUDENT_MANAGEMENT.md - Manage rosters PROGRESS_TRACKER.md - Monitor progress ACCESSIBILITY_TESTING.md - Ensure quality Key Resources By Topic GitHub Classroom FACILITATOR_GUIDE.md - Complete setup COHORT_PROVISIONING.md - Provisioning classroom/README.md - Fast copy-paste setup pack Accessibility ACCESSIBILITY_TESTING.md - Testing procedures FACILITATOR_GUIDE.md - Accessibility philosophy (throughout) Student Communication ANNOUNCEMENT.md - Announcement templates STUDENT_ONBOARDING_EMAIL.md - Onboarding email FAQ.md - FAQs to share Troubleshooting FACILITATOR_CLASSROOM_TROUBLESHOOTING.md - GitHub-specific issues TROUBLESHOOTING.md - General troubleshooting Assessment FACILITATOR_ASSESSMENT.md - Grading rubric PROGRESS_TRACKER.md - Progress tracking Document Index Document Purpose For Whom FACILITATOR_RESOURCES.md Navigation hub Facilitators (start here!) FACILITATOR_GUIDE.md Complete workshop guide New facilitators FACILITATOR_OPERATIONS.md Hour-by-hour procedures Active facilitators FACILITATOR_CLASSROOM_TROUBLESHOOTING.md Problem-solving All facilitators FACILITATOR_CHALLENGES.md Challenge management Experienced facilitators FACILITATOR_ASSESSMENT.md Grading rubric Facilitators doing assessment COHORT_PROVISIONING.md Setup checklist Admin/coordinators STUDENT_MANAGEMENT.md Roster management Admin/coordinators PROGRESS_TRACKER.md Student tracking Facilitators, coordinators ACCESSIBILITY_TESTING.md A11y testing QA/admin DAY1_AGENDA.md Day 1 schedule Everyone DAY2_AGENDA.md Day 2 schedule Everyone QUICK_REFERENCE.md Quick reference card Facilitators (print this) FAQ.md Frequently asked questions Students (and facilitators) ANNOUNCEMENT.md Announcement templates Admin TROUBLESHOOTING.md General troubleshooting Everyone Related Folders ../classroom" + "body": "Admin & Facilitator Resources This folder contains all administrative and facilitator documentation for running GitHub Classroom workshops. Facilitator Resources Start here if you're running a workshop: Quick Navigation FACILITATOR_RESOURCES.md - Navigation hub for all facilitator guides FACILITATOR_GUIDE.md - Complete workshop bible (setup through post-workshop) FACILITATOR_OPERATIONS.md - Hour-by-hour procedures during workshop FACILITATOR_CLASSROOM_TROUBLESHOOTING.md - Problem-solving guide ../GO-LIVE-QA-GUIDE.md - Final release-readiness guide and end-to-end test checklist 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 - Managing the challenge system FACILITATOR_ASSESSMENT.md - Assessment and grading rubric SUPPORT_HUB_OPERATIONS.md - Post-workshop support hub governance and triage model Student And Enrollment Management STUDENT_MANAGEMENT.md - Managing student rosters, enrollments, tracking REGISTRATION-ADMIN.md - Registration process administration and API classroom automation setup REGISTRATION-QUICKSTART.md - 5-minute facilitator setup for registration + classroom API automation STUDENT_ONBOARDING_EMAIL.md - Template email for student onboarding Workshop Planning And Organization DAY1_AGENDA.md - Day 1 schedule and agenda DAY2_AGENDA.md - Day 2 schedule and agenda DAY2_QUICK_START.md - Quick start guide for Day 2 QUICK_REFERENCE.md - Quick reference card for facilitators PROGRESS_TRACKER.md - Tracking student progress Setup And Deployment COHORT_PROVISIONING.md - Setting up a new cohort ACCESSIBILITY_TESTING.md - Testing workshop for accessibility VALIDATION_AUDIT.md - Validating everything works classroom/README.md - Copy-paste classroom setup pack (assignments, autograding, seeding) LEARNING-ROOM-E2E-QA-RUNBOOK.md - Full registration-through-challenges QA execution path for one operator qa-readiness/README.md - Local unit-test readiness evidence pack (non-podcast) ../GO-LIVE-QA-GUIDE.md - Complete pre-cohort QA gate for content, workflows, Classroom, podcasts, and human testing Communications ANNOUNCEMENT.md - Workshop announcement templates FAQ.md - Frequently asked questions Reference And Support TROUBLESHOOTING.md - General troubleshooting reference REGISTER.md - Student registration information GITHUB_PROPOSAL.md - GitHub partnership/proposal documentation PODCASTS.md - Podcast episode notes and references Typical Workflow Planning Phase (Weeks 1-2 Before) COHORT_PROVISIONING.md - Set up the cohort FACILITATOR_GUIDE.md - GitHub Classroom setup ANNOUNCEMENT.md - Create student announcements STUDENT_MANAGEMENT.md - Prepare roster Pre-Workshop (48 Hours Before) FACILITATOR_GUIDE.md - Complete checklist ACCESSIBILITY_TESTING.md - Test with screen readers FACILITATOR_OPERATIONS.md - Setup workstation During Workshop FACILITATOR_OPERATIONS.md - Follow hour-by-hour procedures FACILITATOR_CLASSROOM_TROUBLESHOOTING.md - Reference when needed PROGRESS_TRACKER.md - Track student progress Post-Workshop FACILITATOR_GUIDE.md - Follow-up tasks Update this documentation with lessons learned Reading Order Recommendations For First-Time Facilitators Start: FACILITATOR_RESOURCES.md Then: FACILITATOR_GUIDE.md (full read) Then: FACILITATOR_OPERATIONS.md (full read) Reference: FACILITATOR_CLASSROOM_TROUBLESHOOTING.md For Returning Facilitators Quick reference: QUICK_REFERENCE.md Review: FACILITATOR_GUIDE.md checklist Keep open: FACILITATOR_OPERATIONS.md during workshop For Admin/Coordinators COHORT_PROVISIONING.md - Setup cohorts STUDENT_MANAGEMENT.md - Manage rosters PROGRESS_TRACKER.md - Monitor progress ACCESSIBILITY_TESTING.md - Ensure quality Key Resources By Topic GitHub Classroom FACILITATOR_GUIDE.md - Complete setup COHORT_PROVISIONING.md - Provisioning classroom/README.md - Fast copy-paste setup pack Accessibility ACCESSIBILITY_TESTING.md - Testing procedures FACILITATOR_GUIDE.md - Accessibility philosophy (throughout) Student Communication ANNOUNCEMENT.md - Announcement templates STUDENT_ONBOARDING_EMAIL.md - Onboarding email FAQ.md - FAQs to share Troubleshooting FACILITATOR_CLASSROOM_TROUBLESHOOTING.md - GitHub-specific issues TROUBLESHOOTING.md - General troubleshooting Assessment FACILITATOR_ASSESSMENT.md - Grading rubric PROGRESS_TRACKER.md - Progress tracking Document Index Document Purpose For Whom FACILITATOR_RESOURCES.md Navigation hub Facilitators (start here!) FACILITATOR_GUIDE.md Complete workshop guide New facilitators FACILITATOR_OPERATIONS.md Hour-by-hour procedures Active facilitators FACILITATOR_CLASSROOM_TROUBLESHOOTING.md Problem-solving All facilitators FACILITATOR_CHALLENGES.md Challenge management Experienced facilitators FACILITATOR_ASSESSMENT.md Grading rubric Facilitators doing assessment COHORT_PROVISIONING.md Setup checklist Admin/coordinators STUDENT_MANAGEMENT.md Roster management Admin/coordinators PROGRESS_TRACKER.md Student tracking Facilitat" }, { "id": "admin/classroom admin access.html", @@ -789,7 +789,583 @@ "id": "admin/REGISTRATION-QUICKSTART.html", "title": "Registration Automation Quickstart (Facilitator)", "url": "admin/REGISTRATION-QUICKSTART.html", - "body": "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 . 5-Minute Setup Create an admin token from a facilitator account with organization invitation permissions. In repository settings, add secret: CLASSROOM_ORG_ADMIN_TOKEN In repository settings, add variables: CLASSROOM_ORG CLASSROOM_DAY1_ASSIGNMENT_URL CLASSROOM_DAY2_ASSIGNMENT_URL Save all values. 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: Registration confirmation comment is posted. Organization invite is sent (or detected as already pending/member). Day 1 and Day 2 assignment links appear in the confirmation comment. 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: Remove repository secret CLASSROOM_ORG_ADMIN_TOKEN , or Clear repository variable CLASSROOM_ORG The registration workflow will continue standard confirmation, capacity checks, and CSV export. Day-Of Operations Keep REGISTRATION-ADMIN.md open. Watch Actions runs for registration.yml after each new registration. Spot-check one confirmation comment every few runs. 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." + "body": "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 . 5-Minute Setup Create an admin token from a facilitator account with organization invitation permissions. In repository settings, add secret: CLASSROOM_ORG_ADMIN_TOKEN In repository settings, add variables: CLASSROOM_ORG CLASSROOM_DAY1_ASSIGNMENT_URL CLASSROOM_DAY2_ASSIGNMENT_URL Save all values. 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: Registration confirmation comment is posted. Organization invite is sent (or detected as already pending/member). Day 1 and Day 2 assignment links appear in the confirmation comment. 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: Remove repository secret CLASSROOM_ORG_ADMIN_TOKEN , or Clear repository variable CLASSROOM_ORG The registration workflow will continue standard confirmation, capacity checks, and CSV export. Full Support Reset (When Needed) If support environment drift is detected, rebuild support hub baseline: scripts/classroom/ Reset-SupportHubEnvironment .ps1 Day-Of Operations Keep REGISTRATION-ADMIN.md open. Watch Actions runs for registration.yml after each new registration. Spot-check one confirmation comment every few runs. 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." + }, + { + "id": "admin/LEARNING-ROOM-E2E-QA-RUNBOOK.html", + "title": "Learning Room End-to-End QA Runbook (Registration to Student Completion)", + "url": "admin/LEARNING-ROOM-E2E-QA-RUNBOOK.html", + "body": "Learning Room End-to-End QA Runbook (Registration to Student Completion) Use this runbook when you want one operational checklist that covers the full workflow: Registration intake and validation. GitHub Classroom deployment and assignment setup. Test account acceptance and repository seeding. Full student walkthrough of every challenge path. Release sign-off evidence for go-live. This runbook intentionally excludes podcast validation work. Everything else is in scope: registration flow, classroom deployment, assignment configuration, template readiness, student progression, PR validation, content validation, skills progression, autograder behavior, challenge completion tracking, and chapter-by-chapter curriculum review. Scope and Audience This runbook is for facilitators, QA leads, and admins who need to verify the complete workshop flow from administrator setup to student completion. Scope Boundaries In scope: Registration workflow behavior and classroom invitation handoff. Classroom assignment creation and autograding configuration. Learning Room automation workflows and facilitator scripts. Full curriculum walkthrough (chapters and appendices). Student challenge journey (1-16) and bonus challenge tracking (A-E). QA evidence capture, defect logging, and release sign-off. Out of scope: Podcast generation, podcast validation, and RSS audio feed checks. Canonical Source Files Used by This Runbook Table: Source files consolidated by this runbook Area Source file Registration entry page REGISTER.md Registration automation admin REGISTRATION-ADMIN.md Registration automation quickstart REGISTRATION-QUICKSTART.md Registration workflow logic .github/workflows/registration.yml Classroom deployment classroom/README.md Assignment copy and autograding setup admin/classroom/README.md Human challenge walkthrough classroom/HUMAN_TEST_MATRIX.md Challenge definitions docs/CHALLENGES.md Student starting path docs/get-going.md Grading criteria classroom/grading-guide.md Release gate baseline GO-LIVE-QA-GUIDE.md Support hub operations SUPPORT_HUB_OPERATIONS.md Table: QA validation checkpoints for registration and classroom automation Table: Student journey checkpoints and expected artifacts Table: Label color and purpose for registration automation Table: Screen reader options for workshop setup Table: Accessibility improvements for screen reader users Required Accounts, Access, and Tools Complete this section before Phase 1. Facilitator admin account ( accesswatch ) with Owner access to both Community-Access and Community-Access-Classroom . Dedicated non-admin test student account for acceptance and full challenge walkthrough. This must be a separate GitHub account that is not an owner or member of either organization. Access to classroom.github.com while signed in as accesswatch . Access to repository settings for Community-Access/git-going-with-github (secrets and variables). Local clone of this repository with PowerShell available. GitHub CLI ( gh ) installed and authenticated as accesswatch for optional verification commands. Critical Precondition Gates (No-Go if any fail) Complete all items below before any cohort launch actions. Facilitator account accesswatch can access both organizations: Community-Access (the workshop and code repository organization) Community-Access-Classroom (the GitHub Classroom organization where student repos are created) accesswatch has a verified email address on its GitHub account and can create and edit Classroom assignments at classroom.github.com . Dedicated non-admin test student account exists and can accept invites. gh auth status succeeds for accesswatch in local terminal. Template repository exists and is set as template repo: Community-Access/learning-room-template Template repository Actions settings allow required automation behavior: Actions enabled GITHUB_TOKEN default workflow permissions include write where required Allow GitHub Actions to create and approve pull requests enabled Registration automation settings are correct when using registration-to-classroom handoff: Secret CLASSROOM_ORG_ADMIN_TOKEN is set in Community-Access/git-going-with-github Variables CLASSROOM_ORG , CLASSROOM_DAY1_ASSIGNMENT_URL , CLASSROOM_DAY2_ASSIGNMENT_URL are set in Community-Access/git-going-with-github Registration entry configuration exists and is valid: Issue form template workshop-registration.yml exists Required labels exist: registration , duplicate , waitlist While signed in as accesswatch , opening classroom.github.com shows the Community-Access-Classroom classroom organization. If any precondition fails, stop and resolve before proceeding. Exact Setup Steps for Keys, Permissions, Settings, and Template Currency Use this section when you need literal setup steps (not only validation checks). A. Confirm facilitator account and organization access You are performing all steps below as accesswatch . If you are currently signed in to GitHub as a different account, sign out first and sign i" + }, + { + "id": "admin/qa-readiness/index.html", + "title": "QA Readiness Test Pack (Non-Podcast)", + "url": "admin/qa-readiness/index.html", + "body": "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: 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 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 GO-LIVE-QA-GUIDE.md" + }, + { + "id": "admin/qa-readiness/UNIT-TEST-RESULTS-2026-05-08.html", + "title": "Unit Test Results - 2026-05-08 (Non-Podcast Scope)", + "url": "admin/qa-readiness/UNIT-TEST-RESULTS-2026-05-08.html", + "body": "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 Challenge inventory and numbering consistency: 16 core challenge templates 5 bonus templates Complete numbering/lettering coverage Challenge quality gates: Required evidence fields and troubleshooting guidance Core and bonus template quality checks Classroom setup consistency: Assignment docs and autograding JSON integrity Required scripts and template files present Classroom README deployment section coverage Workflow configuration readiness: Concurrency settings in key workflows Critical permissions in bot/progression workflows Registration readiness: Workflow logic includes registration, duplicate, and waitlist paths Registration issue form template exists 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 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. 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 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." + }, + { + "id": "admin/qa-bundle/admin/LEARNING-ROOM-E2E-QA-RUNBOOK.html", + "title": "Learning Room End-to-End QA Runbook (Registration to Student Completion)", + "url": "admin/qa-bundle/admin/LEARNING-ROOM-E2E-QA-RUNBOOK.html", + "body": "Learning Room End-to-End QA Runbook (Registration to Student Completion) Use this runbook when you want one operational checklist that covers the full workflow: Registration intake and validation. GitHub Classroom deployment and assignment setup. Test account acceptance and repository seeding. Full student walkthrough of every challenge path. Release sign-off evidence for go-live. This runbook intentionally excludes podcast validation work. Everything else is in scope: registration flow, classroom deployment, assignment configuration, template readiness, student progression, PR validation, content validation, skills progression, autograder behavior, challenge completion tracking, and chapter-by-chapter curriculum review. Scope and Audience This runbook is for facilitators, QA leads, and admins who need to verify the complete workshop flow from administrator setup to student completion. Scope Boundaries In scope: Registration workflow behavior and classroom invitation handoff. Classroom assignment creation and autograding configuration. Learning Room automation workflows and facilitator scripts. Full curriculum walkthrough (chapters and appendices). Student challenge journey (1-16) and bonus challenge tracking (A-E). QA evidence capture, defect logging, and release sign-off. Out of scope: Podcast generation, podcast validation, and RSS audio feed checks. Canonical Source Files Used by This Runbook The following table lists the source files this runbook consolidates. Area Source file Registration entry page REGISTER.md Registration automation admin REGISTRATION-ADMIN.md Registration automation quickstart REGISTRATION-QUICKSTART.md Registration workflow logic .github/workflows/registration.yml Classroom deployment classroom/README.md Assignment copy and autograding setup admin/classroom/README.md Human challenge walkthrough classroom/HUMAN_TEST_MATRIX.md Challenge definitions docs/CHALLENGES.md Student starting path docs/get-going.md Grading criteria classroom/grading-guide.md Release gate baseline GO-LIVE-QA-GUIDE.md Support hub operations SUPPORT_HUB_OPERATIONS.md Required Accounts, Access, and Tools Complete this section before Phase 1. Facilitator admin account ( accesswatch ) with Owner access to both Community-Access and Community-Access-Classroom . Dedicated non-admin test student account for acceptance and full challenge walkthrough. This must be a separate GitHub account that is not an owner or member of either organization. Access to classroom.github.com while signed in as accesswatch . Access to repository settings for Community-Access/git-going-with-github (secrets and variables). Local clone of this repository with PowerShell available. GitHub CLI ( gh ) installed and authenticated as accesswatch for optional verification commands. Critical Precondition Gates (No-Go if any fail) Complete all items below before any cohort launch actions. Facilitator account accesswatch can access both organizations: Community-Access (the workshop and code repository organization) Community-Access-Classroom (the GitHub Classroom organization where student repos are created) accesswatch has a verified email address on its GitHub account and can create and edit Classroom assignments at classroom.github.com . Dedicated non-admin test student account exists and can accept invites. gh auth status succeeds for accesswatch in local terminal. Template repository exists and is set as template repo: Community-Access/learning-room-template Template repository Actions settings allow required automation behavior: Actions enabled GITHUB_TOKEN default workflow permissions include write where required Allow GitHub Actions to create and approve pull requests enabled Registration automation settings are correct when using registration-to-classroom handoff: Secret CLASSROOM_ORG_ADMIN_TOKEN is set in Community-Access/git-going-with-github Variables CLASSROOM_ORG , CLASSROOM_DAY1_ASSIGNMENT_URL , CLASSROOM_DAY2_ASSIGNMENT_URL are set in Community-Access/git-going-with-github Registration entry configuration exists and is valid: Issue form template workshop-registration.yml exists Required labels exist: registration , duplicate , waitlist Support hub is ready for student onboarding: Community-Access/support is public and reachable Issues and Discussions are enabled Support labels and templates are present While signed in as accesswatch , opening classroom.github.com shows the Community-Access-Classroom classroom organization. If any precondition fails, stop and resolve before proceeding. Exact Setup Steps for Keys, Permissions, Settings, and Template Currency Use this section when you need literal setup steps (not only validation checks). A. Confirm facilitator account and organization access You are performing all steps below as accesswatch . If you are currently signed in to GitHub as a different account, sign out first and sign in as accesswatch before continuing. Go to github.com and confirm the top-right avatar shows " + }, + { + "id": "admin/qa-bundle/admin/REGISTRATION-QUICKSTART.html", + "title": "Registration Automation Quickstart (Facilitator)", + "url": "admin/qa-bundle/admin/REGISTRATION-QUICKSTART.html", + "body": "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 . 5-Minute Setup Create an admin token from a facilitator account with organization invitation permissions. In repository settings, add secret: CLASSROOM_ORG_ADMIN_TOKEN In repository settings, add variables: CLASSROOM_ORG CLASSROOM_DAY1_ASSIGNMENT_URL CLASSROOM_DAY2_ASSIGNMENT_URL Save all values. 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: Registration confirmation comment is posted. Organization invite is sent (or detected as already pending/member). Day 1 and Day 2 assignment links appear in the confirmation comment. 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: Remove repository secret CLASSROOM_ORG_ADMIN_TOKEN , or Clear repository variable CLASSROOM_ORG The registration workflow will continue standard confirmation, capacity checks, and CSV export. Full Support Reset (When Needed) If support environment drift is detected, rebuild support hub baseline: scripts/classroom/ Reset-SupportHubEnvironment .ps1 Day-Of Operations Keep REGISTRATION-ADMIN.md open. Watch Actions runs for registration.yml after each new registration. Spot-check one confirmation comment every few runs. 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." + }, + { + "id": "admin/qa-bundle/admin/REGISTRATION-ADMIN.html", + "title": "Registration Administration Guide", + "url": "admin/qa-bundle/admin/REGISTRATION-ADMIN.html", + "body": "Registration Administration Guide This document explains how the registration system works and how to manage it, including optional API-based classroom invitation automation. If you just need implementation steps, start with REGISTRATION-QUICKSTART.md . How Registration Tracking Works Registration Count (Website) The registration page at REGISTER.html queries the GitHub Search API in real time every time a visitor loads the page. It counts open issues with the registration label. No CSV or local data is involved. Capacity Check (Workflow) When someone submits a registration issue, the GitHub Actions workflow queries all issues labeled registration and counts unique GitHub usernames. If the count is at or above 75, the registrant is placed on the waitlist instead. Optional Classroom API Automation When configured, the registration workflow can also: Check whether the registrant is already in the classroom organization Send an organization invitation if needed Include Day 1 and Day 2 GitHub Classroom assignment links in the welcome comment Important: This does not bypass GitHub Classroom acceptance. Students still must click the assignment link and accept. Full API Setup (Classroom Automation) Use these steps to enable end-to-end registration plus classroom invitation flow. 1. Create an admin token for organization invites Create a GitHub personal access token for a facilitator/admin account with permission to manage organization invitations. Recommended minimum permissions: Organization administration permissions sufficient to create invitations Repository read access for this repository Store this token securely. Do not commit it to the repository. 2. Add repository secret In repository settings, add this secret: CLASSROOM_ORG_ADMIN_TOKEN = token from Step 1 3. Add repository variables In repository settings, add these variables: CLASSROOM_ORG = your classroom org name (example: Community-Access-Classroom ) CLASSROOM_DAY1_ASSIGNMENT_URL = Day 1 Classroom invite URL CLASSROOM_DAY2_ASSIGNMENT_URL = Day 2 Classroom invite URL If you omit these variables/secrets, registration still works; only the classroom automation steps are skipped. 4. Confirm workflow behavior After setup, successful non-duplicate registrations should produce: Standard registration confirmation logic (registration label and capacity handling) Organization invite status handling: invited (new invite sent) already-invited (pending invite exists) already-member (user already in org) Welcome comment including classroom assignment links (if configured) 5. End-to-end test checklist Run this once before opening registration publicly: Submit a test registration issue from a non-member test account. Verify an org invitation is sent. Verify Day 1/Day 2 assignment links appear in the welcome comment. Accept org invite from the test account. Accept Day 1 assignment link from the test account. Confirm private classroom repo is created. Submit a second registration from the same account and confirm duplicate handling. 6. Operational notes The automation runs only when capacity is available and the registration is not a duplicate. Waitlisted users are not invited automatically by this workflow. Assignment acceptance remains student-driven in GitHub Classroom. 7. Rollback plan If invitation automation causes issues: Remove CLASSROOM_ORG_ADMIN_TOKEN secret (fastest stop switch), or Clear CLASSROOM_ORG variable. Registration confirmations and CSV export continue to function without classroom API steps. CSV Export The CSV is a convenience export for reviewing registrations in spreadsheet form. It is regenerated from scratch (from the issues) every time someone registers or when the workflow is manually triggered. The issues are the source of truth, not the CSV. The CSV is uploaded as a workflow artifact (retained for 90 days) and is only accessible to repository collaborators. It is not committed to the repository. Downloading the CSV Using the GitHub CLI Download the latest registration CSV: gh run download --name registrations --dir ./registrations -R community -access /git -going-with-github List recent workflow runs first to pick a specific one: gh run list --workflow =registration.yml -R community -access /git -going-with-github gh run download <run -id > --name registrations --dir ./registrations -R community -access /git -going-with-github Using the GitHub Web UI Go to the repository on GitHub Click the Actions tab Click a Registration - Welcome & CSV Export workflow run Scroll down to the Artifacts section Click registrations to download the CSV Regenerating the CSV On Demand To rebuild the CSV from all current registration issues (e.g., right before the workshop): gh workflow run registration.yml -R community -access /git -going-with-github This triggers the workflow_dispatch event, which rebuilds the CSV from all registration issues and uploads a fresh artifact. Registration Scenarios The workflow handles three scenarios when someone subm" + }, + { + "id": "admin/qa-bundle/admin/classroom/index.html", + "title": "Classroom Copy-Paste Pack", + "url": "admin/qa-bundle/admin/classroom/index.html", + "body": "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 Create the Classroom and import roster from classroom/README.md . Create Day 1 assignment and paste content from day1-assignment-copy-paste.md . Configure Day 1 tests using autograding-setup.md . Create Day 2 assignment and paste content from day2-assignment-copy-paste.md . Configure Day 2 tests using autograding-setup.md . After each student accepts, run seeding commands from seeding-ops.md . 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." + }, + { + "id": "admin/qa-bundle/admin/classroom/autograding-setup.html", + "title": "Autograding Setup and Verification", + "url": "admin/qa-bundle/admin/classroom/autograding-setup.html", + "body": "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: 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: 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: 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: ! 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: 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: 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: 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: 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: 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: 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 Add all tests and save assignment. Confirm test count: Day 1 has 4 tests Day 2 has 6 tests Confirm point totals: Day 1 total = 50 Day 2 total = 75 Use a test student account to accept each assignment. Trigger one known pass on each assignment. Trigger one known fail on each assignment and confirm feedback appears. Confirm rerun passes after fix. 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 #<issue-number> , 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 Confirm student pushed a new commit to the same PR branch. Open PR checks and inspect the failing command output. 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 . Cha" + }, + { + "id": "admin/qa-bundle/admin/classroom/live-facilitation-flow.html", + "title": "Live Facilitation Flow Checklist", + "url": "admin/qa-bundle/admin/classroom/live-facilitation-flow.html", + "body": "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 scripts/classroom/Seed -LearningRoomChallenge .ps1 -Repository Community -Access-Classroom /learning -room-studentname -Challenge 1 -Assignee studentname Day 2 seeding scripts/classroom/Seed -LearningRoomChallenge .ps1 -Repository Community -Access-Classroom /learning -room-studentname -Challenge 10 -Assignee studentname Peer simulation seeding 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." + }, + { + "id": "admin/qa-bundle/admin/classroom/day1-assignment-copy-paste.html", + "title": "Day 1 Assignment Copy-Paste", + "url": "admin/qa-bundle/admin/classroom/day1-assignment-copy-paste.html", + "body": "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. # 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" + }, + { + "id": "admin/qa-bundle/admin/classroom/day2-assignment-copy-paste.html", + "title": "Day 2 Assignment Copy-Paste", + "url": "admin/qa-bundle/admin/classroom/day2-assignment-copy-paste.html", + "body": "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. # 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. " + }, + { + "id": "admin/qa-bundle/admin/qa-readiness/index.html", + "title": "QA Readiness Test Pack (Non-Podcast)", + "url": "admin/qa-bundle/admin/qa-readiness/index.html", + "body": "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: 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 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 GO-LIVE-QA-GUIDE.md" + }, + { + "id": "admin/qa-bundle/admin/qa-readiness/UNIT-TEST-RESULTS-2026-05-08.html", + "title": "Unit Test Results - 2026-05-08 (Non-Podcast Scope)", + "url": "admin/qa-bundle/admin/qa-readiness/UNIT-TEST-RESULTS-2026-05-08.html", + "body": "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 Challenge inventory and numbering consistency: 16 core challenge templates 5 bonus templates Complete numbering/lettering coverage Challenge quality gates: Required evidence fields and troubleshooting guidance Core and bonus template quality checks Classroom setup consistency: Assignment docs and autograding JSON integrity Required scripts and template files present Classroom README deployment section coverage Workflow configuration readiness: Concurrency settings in key workflows Critical permissions in bot/progression workflows Registration readiness: Workflow logic includes registration, duplicate, and waitlist paths Registration issue form template exists 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 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. 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 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." + }, + { + "id": "admin/qa-bundle/GO-LIVE-QA-GUIDE.html", + "title": "Git Going with GitHub Go-Live QA Guide", + "url": "admin/qa-bundle/GO-LIVE-QA-GUIDE.html", + "body": "Git Going with GitHub Go-Live QA Guide Use this guide before a cohort is opened to learners. It is the release gate for curriculum content, GitHub Classroom deployment, Learning Room automation, 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). Support Hub is provisioned and publicly accessible at Community-Access/support . Registration confirmation and help pathways route support requests to Support Hub issues/discussions. Registration issue form template and labels are configured ( workshop-registration.yml , registration , duplicate , waitlist ). 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 copy-paste setup pack admin/classroom/README.md End-to-end operator runbook (registration to completion, podcast excluded) admin/LEARNING-ROOM-E2E-QA-RUNBOOK.md Human challenge walkthrough classroom/HUMAN_TEST_MATRIX.md Facilitator operations admin/FACILITATOR_OPERATIONS.md Facilitator guide admin/FACILITATOR_GUIDE.md Support hub operations admin/SUPPORT_HUB_OPERATIONS.md Student challenge hub docs/CHALLENGES.md Podcast pipeline podcasts/README.md Podcast regeneration runbook podcasts/REGENERATION.md Post-workshop cleanup 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. 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-mark" + }, + { + "id": "admin/qa-bundle/REGISTER.html", + "title": "Student Opt-In", + "url": "admin/qa-bundle/REGISTER.html", + "body": "Student Opt-In Back to Home | Support Hub | Pre-Workshop Setup Guide 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 Sign in to your GitHub account . Open the registration issue form. Submit the form. Start Student Opt-In Form 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 a support issue Join Support Hub Discussions A Community Access initiative." + }, + { + "id": "admin/qa-bundle/classroom/index.html", + "title": "Workshop Deployment Guide", + "url": "admin/qa-bundle/classroom/index.html", + "body": "Workshop Deployment Guide Single, end-to-end guide for deploying a new Git Going with GitHub workshop cohort. Covers everything from creating the classroom through post-workshop teardown. This is the only deployment document you need. Before sharing invite links with students, complete the Go-Live QA Guide . It is the final release gate for content, workflows, Classroom setup, podcasts, accessibility, and human test coverage. If you need one practical execution script from registration through full student challenge completion (podcast work excluded), use admin/LEARNING-ROOM-E2E-QA-RUNBOOK.md . Before creating assignments, sync and validate the latest template deployment using scripts/classroom/Prepare-LearningRoomTemplate.ps1 and scripts/classroom/Test-LearningRoomTemplate.ps1 . How the Workshop Works Each student gets their own private repository created by GitHub Classroom from the learning-room-template . Inside that repo, three automation systems guide the student through all 21 challenges without facilitator intervention: 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 Student Progression Bot -- creates the first challenge when triggered by a facilitator script, then creates the next challenge issue whenever a student closes the current challenge issue Autograders -- automated tests that verify objective evidence of challenge completion (branch exists, conflict markers removed, template file valid, agent file structured correctly) No shared student repository. Students do not clone the template or configure permissions. The facilitator's deployment work is creating the classroom and two assignments in the GitHub Classroom web UI, then running the seeding scripts after each student repo is created. Students only need a GitHub account. They do not need to create an organization, become members of Community-Access , or change GitHub Actions settings. Organization and repository workflow permissions are facilitator responsibilities. Architecture Community-Access/learning-room-template (template repo) | +--> GitHub Classroom creates one private repo per student | learning-room-student-a | learning-room-student-b | ... | +--> Each student repo contains: | 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 Day 2 only Participants with GitHub fundamentals Assignment 2 only Day 2 Quick Start then Day 2 Agenda Day-2-only participants skip Assignment 1 entirely. They verify readiness using the Day 2 Quick Start self-assessment, then accept only the Day 2 invite link. What Is in This Directory File Purpose assignment-day1-you-belong-here.md Assignment description for Day 1 (paste into Classroom UI) assignment-day2-you-can-build-this.md Assignment description for Day 2 (paste into Classroom UI) autograding-day1.json Test definitions for Day 1 autograder autograding-day2.json Test definitions for Day 2 autograder grading-guide.md Facilitator rubric for all 21 challenges roster-template.csv Starter CSV for importing student roster student-progression.yml Reference copy of the progression bot workflow HUMAN_TEST_MATRIX.md End-to-end human walkthrough for all 16 core and 5 bonus challenges teardown-checklist.md Post-workshop cleanup steps ../GO-LIVE-QA-GUIDE.md Final release-readiness guide and checklist ../admin/LEARNING-ROOM-E2E-QA-RUNBOOK.md Single operator runbook from registration to student completion (podcast excluded) Prerequisites Before starting, confirm the following: You have Owner or Admin access to the Community-Access GitHub organization Your facilitator GitHub account has a verified email address The Community-Access/learning-room-template repository exists and is public (or the classroom org has read access) The template repo has GitHub Actions enabled with Read and write permissions for GITHUB_TOKEN (Settings > Actions > General) -- 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 separ" + }, + { + "id": "admin/qa-bundle/classroom/HUMAN_TEST_MATRIX.html", + "title": "Human Test Matrix for Learning Room Challenges", + "url": "admin/qa-bundle/classroom/HUMAN_TEST_MATRIX.html", + "body": "Human Test Matrix for Learning Room Challenges Use this matrix before each cohort to verify that the Learning Room template behaves like a realistic collaborative GitHub project while still working inside private GitHub Classroom repositories. Required Test Repositories Create at least one disposable student repository from the current Community-Access/learning-room-template template. For full peer-access testing, create two disposable repositories and use two test student accounts. Minimum smoke test: learning-room-smoke-a Full collaboration test: learning-room-smoke-a learning-room-smoke-b Required Facilitator Setup After the student repository exists, run: scripts/classroom/Seed -LearningRoomChallenge .ps1 -Repository Community -Access /learning -room-smoke-a -Challenge 1 -Assignee test-student -a scripts/classroom/Seed -PeerSimulation .ps1 -Repository Community -Access /learning -room-smoke-a -StudentUsername test-student -a For Day 2-only testing, seed Challenge 10 instead: scripts/classroom/Seed -LearningRoomChallenge .ps1 -Repository Community -Access /learning -room-smoke-a -Challenge 10 -Assignee test-student -a scripts/classroom/Seed -PeerSimulation .ps1 -Repository Community -Access /learning -room-smoke-a -StudentUsername test-student -a What The Peer Simulation Creates Seed-PeerSimulation.ps1 creates realistic collaboration artifacts inside the student's private repo: Peer Simulation: Welcome Link Needs Context issue Peer Simulation: Review Request for Contribution Guidance issue Peer Simulation: Improve contribution guidance pull request docs/samples/peer-review-practice.md on branch peer-simulation/review-pr Students can use these artifacts whenever a challenge asks them to comment, react, review, compare, or practice collaboration. If facilitators separately provision real buddy access, students may use the real buddy repository instead. Day 1 Core Test Complete these steps as a test student. Challenge 1: Find Your Way Around Verify Challenge 1 issue exists. Complete the scavenger hunt. Comment evidence. Comment or react on the peer-simulation issue. Close Challenge 1. Verify Challenge 2 appears. Challenge 2: File Your First Issue Find a TODO in docs/welcome.md . Create a new issue with a clear title and description. Comment evidence on Challenge 2. Comment on the peer-simulation issue title/description. Close Challenge 2. Verify Challenge 3 appears. Challenge 3: Join the Conversation Comment on Peer Simulation: Welcome Link Needs Context . Include @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. Challenge 4: Branch Out Create learn/test-student-a or equivalent feature branch. Compare with the peer-simulation PR branch name. Comment evidence. Close Challenge 4. Verify Challenge 5 appears. Challenge 5: Make Your Mark Edit the first TODO in docs/welcome.md on the feature branch. Commit with a descriptive message. Compare with the peer-simulation PR title or commit message. Comment evidence. Close Challenge 5. Verify Challenge 6 appears. Challenge 6: Open Your First Pull Request Open a PR from the feature branch to main . Include Closes #N for the Challenge 6 issue or the issue being solved. Verify Aria posts PR feedback. Comment on the peer-simulation PR. Close Challenge 6 when ready. Verify Challenge 7 appears. Challenge 7: Survive a Merge Conflict Run the facilitator conflict script after the student's PR exists: scripts/classroom/ Start-MergeConflictChallenge .ps1 -Repository Community -Access /learning -room-smoke-a -StudentBranch learn/ test-student -a Verify the student's PR reports a conflict. Resolve the conflict. Verify the Challenge 7 conflict-marker workflow succeeds. Close Challenge 7. Verify Challenge 8 appears. Challenge 8: The Culture Layer Read governance/community files. Use the peer-simulation issue for label/triage discussion. Comment reflection evidence. Close Challenge 8. Verify Challenge 9 appears. Challenge 9: Merge Day Verify the PR has been reviewed and can merge. Merge the PR or have the facilitator merge it. Leave wrap-up feedback on the peer-simulation issue or PR. Close Challenge 9. Day 2 Core Test Seed Challenge 10 if continuing from Day 1 did not naturally reach it. Challenge 10: Go Local Clone the repo locally. Create a branch. Edit, commit, and push. Verify the local commit workflow succeeds. Close Challenge 10. Verify Challenge 11 appears. Challenge 11: Open a Day 2 PR Open a PR from the locally pushed branch. Verify Aria feedback appears. Review the peer-simulation PR title and description. Close Challenge 11. Verify Challenge 12 appears. Challenge 12: Review Like a Pro Review the peer-simulation PR. Leave at least two specific comments if GitHub allows inline comments. Submit a review verdict if available. Comment evidence. Close Challenge 12. Verify Challenge 13 appears. Challenge 13: AI as Your Copilot Use Copilot to improve docs/samples" + }, + { + "id": "admin/qa-bundle/classroom/grading-guide.html", + "title": "Facilitator Grading Guide", + "url": "admin/qa-bundle/classroom/grading-guide.html", + "body": "Facilitator Grading Guide How to evaluate student work across the 16 core challenges and 5 bonus challenges. Grading Philosophy This is a learning workshop, not a competitive course. The grading system measures participation and engagement, not perfection. Completion, not correctness: If a student attempted the challenge and produced evidence, they completed it Effort over elegance: A messy first attempt that shows learning is better than a polished copy-paste Partial credit always: Any progress counts. No student should feel like they failed. Automated Checks 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 and 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." + }, + { + "id": "admin/qa-bundle/classroom/assignment-day1-you-belong-here.html", + "title": "Assignment 1: You Belong Here", + "url": "admin/qa-bundle/classroom/assignment-day1-you-belong-here.html", + "body": "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 2. File Your First Issue Create an issue describing something you noticed Chapter 5 3. Join the Conversation Mention a teammate or bot using @mentions Chapter 5 4. Branch Out Create a feature branch for your work Chapter 4 5. Make Your Mark Edit a file and commit with a clear message Chapter 4 6. Open Your First Pull Request Open a PR that references an issue with Closes #N Chapter 6 7. Survive a Merge Conflict Understand and fix conflict markers Chapter 7 8. The Culture Layer Reflect on community norms and communication Chapter 8 9. Merge Day Get your PR reviewed, approved, and merged Chapter 10 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 for what comes next. Day 1 is your only day? Everything you learned today is complete and self-contained. See the Next Steps guide for how to continue your GitHub journey independently. Bonus Challenges If you finish early, check the Challenges page for bonus challenges A through E." + }, + { + "id": "admin/qa-bundle/classroom/assignment-day2-you-can-build-this.html", + "title": "Assignment 2: You Can Build This", + "url": "admin/qa-bundle/classroom/assignment-day2-you-can-build-this.html", + "body": "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 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 11. Open a Day 2 PR Open a PR from your locally-pushed branch Chapter 15 12. Review Like a Pro Review a classmate's PR with specific, constructive feedback Chapter 15 13. AI as Your Copilot Use Copilot to improve documentation and evaluate its output Chapter 16 14. Template Remix Create a custom YAML issue template Chapter 17 15. Meet the Agents Explore and run agents from the accessibility-agents repo Chapter 19 16. Build Your Agent (Capstone) Design and submit an original agent with responsibilities and guardrails Chapter 20 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 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 repository: Fork the repository to your account Clone your fork locally Create a branch for your work Open a PR from your fork back to the original See Chapter 18 for the full fork workflow. If forking is new to you, Chapter 6: Working with Pull Requests covers the fundamentals. Bonus Challenges If you finish early, check the Challenges page for bonus challenges." + }, + { + "id": "admin/qa-bundle/docs/CHALLENGES.html", + "title": "Challenge Hub", + "url": "admin/qa-bundle/docs/CHALLENGES.html", + "body": "Challenge Hub Welcome to the Challenge Hub - your guide to all 16 core challenges and 5 bonus challenges. The challenges are the practice path for the course. Each one asks you to do a small piece of real GitHub work, leave evidence of what you did, and then close the issue so the next challenge can open. The goal is not speed. The goal is to build a contributor rhythm you can trust: orient yourself, make the move, verify the result, and ask for help with clear facts when something feels off. How Challenges Work Start in your private Learning Room repository, not in the public curriculum repository. Open the Issues tab, find the challenge issue assigned to you, and read the issue body before acting. Each issue explains the task, the evidence prompt, and any buddy check or automated check that applies. When a challenge asks for evidence, post it as a comment on that challenge issue. Evidence can be a link, a short reflection, the name of a branch, a pull request number, or a note about what you tried and what happened. After you post the evidence, close the challenge issue. The Student Progression Bot uses that closed issue as the signal to open the next challenge. Every challenge below includes a reference solution. Treat those files as worked examples, not answer keys. Your exact branch name, issue number, wording, or file count may differ. What matters is whether you practiced the skill and can explain the result. Day 1: You Belong Here (Challenges 1-9) Challenge 1: Find Your Way Around Chapters: Ch02-04 | Evidence: Comment This first challenge is about orientation. Before you edit anything, you learn how a repository is organized: where the Code tab lives, where Issues live, how the file tree behaves, and how the README gives a project its front door. What to do: Find the Code tab and count the files or folders in the repository root Open the Issues tab and identify at least one issue or confirm the tab exists Navigate to docs/welcome.md and read the opening paragraph Find the repository description and the rendered README Evidence to post: Describe what you found and name one navigation shortcut or screen reader technique that helped. Compare your result with the Challenge 1 solution reference when you want a second view of the same exploration path. Challenge 2: File Your First Issue Chapter: Ch05 | Evidence: Comment Issues are how maintainers turn observations into trackable work. In this challenge, you find a small TODO in the Learning Room and write an issue that another person could understand without being in the room with you. What to do: Open docs/welcome.md and search for TODO Create a new issue with a specific title Explain what needs to change, where it is, and why the change would help Evidence to post: Link to the issue you created and include one sentence about why your title is clear. If you want to compare tone and structure, read the Challenge 2 solution reference . Challenge 3: Join the Conversation Chapter: Ch05 | Evidence: Comment Open source is conversation as much as code. This challenge teaches you how to participate in an issue thread with an @mention, a reaction, and a comment that moves the work forward. What to do: Find your buddy's Challenge 2 issue or a facilitator-provided peer simulation issue Leave a meaningful comment with an @mention Add a reaction to the original issue or a helpful comment Evidence to post: Link to your comment and describe what made it useful, kind, or specific. The Challenge 3 solution reference shows one way to make a short comment feel genuinely collaborative. Challenge 4: Branch Out Chapter: Ch06 | Evidence: Comment A branch is a safe workspace. It lets you try a change without rewriting the main version of the project. In this challenge, you create your own branch and confirm that you know where your work will happen. What to do: Find the branch selector on the Code tab Create a branch named learn/YOUR-USERNAME from main Confirm the branch selector now names your branch Evidence to post: Write the branch name you created and how you confirmed you were on it. Use the Challenge 4 solution reference if you want to check your branch mental model. Challenge 5: Make Your Mark Chapter: Ch06 | Evidence: Comment This is your first small content change. You edit a file, replace a TODO with real text, and commit the change with a message that explains what happened. What to do: Switch to your learn/YOUR-USERNAME branch Edit docs/welcome.md to replace the TODO with useful content Write a commit message that explains the change in plain language Evidence to post: Share your commit message and the file you edited. For a worked example of a focused commit, compare with the Challenge 5 solution reference . Challenge 6: Open Your First Pull Request Chapter: Ch06 | Evidence: Comment A pull request is the conversation around a proposed change. It lets others review your branch before it becomes part of main . This challenge connects your branch, your issue, and" + }, + { + "id": "admin/qa-bundle/docs/get-going.html", + "title": "Get Going with GitHub", + "url": "admin/qa-bundle/docs/get-going.html", + "body": "Get Going with GitHub Start here if you are new, unsure, or joining from a workshop link. This guide walks you from "I have the link" to "I know where I am, what to do next, and how to ask for help." You do not need to know Git, GitHub, VS Code, or the command line before you begin. What This Guide Does This workshop is designed so you are never left guessing what comes next. You will have: A GitHub Classroom assignment link from the facilitator Your own private Learning Room repository Challenge issues that tell you exactly what to do Evidence prompts that tell you what to post when you finish Aria bot feedback on pull requests Reference solutions you can compare against after you try Multiple tool paths, so you can work in the browser, VS Code, GitHub Desktop, or the command line when appropriate The goal is not to rush. The goal is to build confidence one checkable step at a time. Step 1 - Know Your Starting Place Before Day 1 starts, complete Chapter 00: Pre-Workshop Setup . That chapter helps you create or verify your GitHub account, configure accessibility settings, choose a browser, install Git and VS Code, and confirm your screen reader setup. If you cannot finish every setup step before the workshop, tell a facilitator early. Setup problems are normal, and the workshop is designed with time and support for recovery. Step 2 - Accept the GitHub Classroom Assignment At the start of Day 1, the facilitator gives you a GitHub Classroom assignment link. It usually starts with https://classroom.github.com/a/ . Open the assignment link in the browser where you are signed in to GitHub. If GitHub asks you to authorize GitHub Classroom, activate Authorize GitHub Classroom . If you are asked to choose your name from a roster, find your name and select it. If your name is missing, use the skip option and tell the facilitator. Activate Accept this assignment . Wait while GitHub Classroom creates your private repository. Refresh the page until the repository link appears. Open the repository link and bookmark it. Your repository name usually looks like learning-room-your-username . This is your personal practice space for the workshop. Step 3 - Understand the Learning Room The Learning Room is a private repository created from a template. Everyone starts from the same materials, but your work belongs to you. You can safely practice there because: You have your own issues, branches, commits, and pull requests Other students do not see your work unless the facilitator intentionally pairs you Mistakes are expected and recoverable Bot feedback is educational, not punitive Challenge issues unlock in sequence so you always know the next step Think of the Learning Room as a guided practice studio. It is real GitHub, but the room is set up so you can learn without fear of damaging a public project. Step 4 - Find Challenge 1 After your Learning Room repository is created, the Student Progression Bot creates your first challenge issue. Open your Learning Room repository. Navigate to the Issues tab. On GitHub, the keyboard shortcut is G then I . Find an issue titled Challenge 1: Find Your Way Around . Open the issue and read the body from top to bottom. Follow the checklist in the issue. Post your evidence in the evidence field or as the requested comment. Close the challenge issue when the instructions tell you to close it. When you close a challenge issue, the next challenge opens. You do not need to hunt through the whole curriculum to know what is next. Step 5 - Choose the Tool That Fits the Moment There is no single correct way to use GitHub. The workshop teaches the workflow first, then offers tool paths. Use this plain-language guide to decide where to start: GitHub.com in the browser: Best for Day 1, issues, pull requests, repository navigation, and reviews. github.dev: Best when you want a VS Code-style editor in the browser without installing anything. Press the period key from many repository pages to open it. VS Code desktop: Best for Day 2, local Git, Copilot, extensions, and deeper editing work. GitHub Desktop: Best if you want a desktop Git workflow without typing Git commands. GitHub CLI: Best if you prefer terminal workflows or want automation later. You are not behind if you use one tool longer than someone else. The important skill is understanding the contribution workflow: issue, branch, change, commit, pull request, review, and merge. Step 6 - What to Listen For with a Screen Reader When you feel lost, listen for structure before you take action. Useful signals include: Page title Repository name heading Landmark names such as main content or repository navigation Tab names such as Code, Issues, and Pull requests Issue title Pull request title Branch name Button name Field label Bot comment or check result If you are not sure where you are, pause and navigate by headings or landmarks. Finding your position is part of the workflow, not a failure. Step 7 - Use the Support Built into th" + }, + { + "id": "admin/qa-bundle/docs/student-onboarding.html", + "title": "Student Onboarding: Git Going with GitHub", + "url": "admin/qa-bundle/docs/student-onboarding.html", + "body": "Student Onboarding: Git Going with GitHub Welcome to Git Going with GitHub , a two-day Community Access workshop for blind and low-vision learners who want practical, confidence-building GitHub skills. This page is the short version of what to do before the workshop and what to expect when we begin. The detailed setup guide is still the source of truth: Pre-Workshop Setup . Course Dates The workshop is scheduled for May 21-22, 2026 . Each day includes guided instruction, hands-on practice, breaks, and time for questions. You do not need to be fast. You do need to be willing to try, ask questions, and keep going when GitHub feels unfamiliar. Complete Before Day 1 Please complete these steps before the first session: Create or confirm your GitHub account. Verify your GitHub email address. Enable two-factor authentication if possible. Configure GitHub accessibility settings, especially disabling hovercards. Install Visual Studio Code. Install Git. Sign in to GitHub in your browser. Confirm GitHub Copilot is available in VS Code. Review the full Pre-Workshop Setup checklist. If any step blocks you, tell us before the workshop. Setup problems are normal, and we would rather help early than spend Day 1 troubleshooting silently. Do Not Claim A Repository Yet You do not need to accept a GitHub Classroom assignment before Day 1. At the beginning of the workshop, the facilitator will share a GitHub Classroom assignment link in the meeting chat. That link creates your private Learning Room repository. We will walk through the process together. Preview the steps in The Learning Room: Accept Your Classroom Assignment and Open Your Repo . What Your Learning Room Is Your Learning Room is a private GitHub repository created from the Community-Access/learning-room-template template. It is your practice space for the workshop. You do not clone or work directly in the template repository. GitHub Classroom makes a private copy for you, and that private copy is the repository you use during the workshop. Inside that repository you will find: Challenge issues that guide your work one step at a time Practice documents with intentional problems to fix GitHub Actions that check your work Aria, the workshop bot that gives feedback on pull requests Reference files for branches, pull requests, merge conflicts, Copilot, and agents Other students cannot see your private Learning Room repository. Facilitators can see it through GitHub Classroom so they can help when you get stuck. You do not need a GitHub organization, owner access, or repository settings access. The facilitators configure the template, Classroom assignment, and GitHub Actions permissions before the workshop. Your job is to accept the assignment link, work in the repository it creates for you, and ask for help if a permission prompt appears. How The Challenge Flow Works The workshop uses a guided progression: Open the current challenge issue. Read the goal and steps. Complete the task in GitHub or VS Code. Add evidence as an issue comment. Close the issue when you are done. The progression bot opens the next challenge. Some challenges ask you to open a pull request. When you do, Aria reviews the pull request structure, checks links and accessibility basics, and explains what to fix. This mirrors a real open source workflow: create a branch, make a focused change, open a pull request, get feedback, revise, and merge. GitHub Skills Modules We also recommend GitHub Skills modules because they use the same issue-and-bot learning pattern as the workshop. The three most useful modules for this course are: Introduction to GitHub Communicate Using Markdown Review Pull Requests You do not need to finish these before Day 1. We will reference them during the course, and they are excellent follow-up practice afterward. The full catalog is in Appendix Z: GitHub Skills . What To Keep Nearby During the workshop, keep these pages open or bookmarked: Pre-Workshop Setup The Learning Room Screen Reader Cheatsheet Markdown Reference Git Authentication GitHub Skills Catalog Getting Help If something does not work: Say so in the workshop chat. Mention what screen reader, browser, and operating system you are using. Share the link to the page or repository where you are stuck, if you can. Ask for a facilitator or peer to walk with you. This workshop is designed around real GitHub workflows. Real workflows include mistakes, confusing screens, failing checks, and revisions. That is not failure. That is the work." + }, + { + "id": "admin/qa-bundle/docs/solutions/solution-01-scavenger-hunt.html", + "title": "Solution Reference: Challenge 1 -- Find Your Way Around", + "url": "admin/qa-bundle/docs/solutions/solution-01-scavenger-hunt.html", + "body": "Solution Reference: Challenge 1 -- Find Your Way Around This is one way the scavenger hunt could look. Your exact findings will vary depending on when you completed the challenge. If you found the key elements, you succeeded. Expected findings Code tab The root of the repository contains files like README.md , docs/ , and .github/ The file count varies as the repository evolves -- any reasonable count is correct Issues tab You should have found at least one open issue If no issues were open, noting that the tab exists is sufficient docs/welcome.md The first paragraph introduces the learning room and what students will do You may have noticed TODO comments -- those are intentionally left for Challenge 2 Repository description and README The description appears at the top of the Code tab, below the repository name The README renders automatically below the file list Alternate approaches github.com: Click each tab in the top navigation bar github.dev: Press . on any repo page to open the web editor, then use the Explorer sidebar VS Code with GitHub extension: Use the GitHub Repositories extension to browse remotely GitHub CLI: gh repo view Community-Access/git-going-with-github --web opens the repo in a browser What matters The learning objective is familiarity with repository navigation, not memorizing exact file counts. If you explored the tabs and found the key files, you completed this challenge." + }, + { + "id": "admin/qa-bundle/docs/solutions/solution-02-first-issue.html", + "title": "Solution Reference: Challenge 2 -- File Your First Issue", + "url": "admin/qa-bundle/docs/solutions/solution-02-first-issue.html", + "body": "Solution Reference: Challenge 2 -- File Your First Issue This shows two example issues. Yours will look different and that is fine. Example 1: Bug report style Title: TODO in welcome.md: missing workshop schedule link Body: In docs/welcome.md , line 15, there is a TODO comment that says "add link to workshop schedule." This placeholder should be replaced with an actual link so students can find the schedule. Steps to find it: Open docs/welcome.md Search for "TODO" The comment is on line 15 Example 2: Feature request style Title: Add accessibility tips section to welcome.md Body: The welcome document covers what students will do but does not mention accessibility features. A short section pointing students to screen reader shortcuts and keyboard navigation would help everyone start on equal footing. Suggested location: After the "What you will learn" section. What makes a good issue Clear title: Someone scanning the issue list can understand the topic without opening it Enough context: Another person could find and understand the problem from your description alone Reproducible location: File name and line number (if relevant) so the fix is easy to find Alternate approaches Both bug reports and feature suggestions are valid for this challenge. The key is writing clearly enough that a stranger could act on your issue." + }, + { + "id": "admin/qa-bundle/docs/solutions/solution-03-conversation.html", + "title": "Solution Reference: Challenge 3 -- Join the Conversation", + "url": "admin/qa-bundle/docs/solutions/solution-03-conversation.html", + "body": "Solution Reference: Challenge 3 -- Join the Conversation This shows an example comment thread. Your conversation will be different. Example exchange Your comment (on a buddy's issue) Good catch on the missing link in welcome.md! I found the same TODO on line 15. @maria-student Have you also noticed the TODO on line 28? That one mentions a "resources" section that does not exist yet. We could address both in the same PR. Buddy's reply @your-username Thanks for pointing that out! I had not scrolled that far. Let me update my issue description to cover both TODOs. What makes a good comment Specific reference: Mention what you are responding to (line numbers, file names) Constructive tone: Add information or ask questions rather than just agreeing @mention: Tag the person you are talking to so they get notified Actionable: Your comment helps move the conversation forward Alternate approaches Comment on an issue someone else filed Reply to a comment on your own issue Ask a clarifying question about someone else's proposed change What matters The learning objective is participating in asynchronous collaboration. A single thoughtful comment with an @mention is sufficient evidence." + }, + { + "id": "admin/qa-bundle/docs/solutions/solution-04-branch-out.html", + "title": "Solution Reference: Challenge 4 -- Branch Out", + "url": "admin/qa-bundle/docs/solutions/solution-04-branch-out.html", + "body": "Solution Reference: Challenge 4 -- Branch Out This shows how to create a branch from each tool. You only needed to use one. On github.com Go to the repository's Code tab Click the branch dropdown (it says "main") Type a new branch name like fix/welcome-todo Click "Create branch: fix/welcome-todo from main" The branch now exists on GitHub. You can switch to it using the same dropdown. In VS Code (with Git) git checkout - b fix/welcome-todo Or use the Source Control sidebar: click the branch name in the bottom-left status bar, then select "Create new branch." In GitHub Desktop Click the Current Branch dropdown Click "New Branch" Enter the name fix/welcome-todo Confirm it is based on main With GitHub CLI gh repo clone <workshop-org>/learning-room-<your-username> cd learning-room git checkout -b fix/welcome-todo Branch naming Good branch names are short and descriptive: fix/welcome-todo -- fixing a TODO in welcome.md feature/add-schedule-link -- adding a new link docs/update-readme -- documentation change All of these are valid. The convention type/description is common but not required. What matters The learning objective is understanding that branches let you work in isolation without affecting main. If you created any branch with any name, you completed this challenge." + }, + { + "id": "admin/qa-bundle/docs/solutions/solution-05-make-your-mark.html", + "title": "Solution Reference: Challenge 5 -- Make Your Mark", + "url": "admin/qa-bundle/docs/solutions/solution-05-make-your-mark.html", + "body": "Solution Reference: Challenge 5 -- Make Your Mark This shows an example edit and commit. Your changes will be different. Example edit File: docs/welcome.md Before (line 15): <!-- TODO: add link to workshop schedule --> After: See the [ workshop schedule ]( https://github.com/Community-Access/git-going-with-github/blob/main/admin/DAY1_AGENDA.md ) for session times. Example commit message docs: replace TODO with workshop schedule link Resolves the placeholder on line 15 of welcome . md by adding a link to the schedule file . What makes a good commit message First line: Short summary (50 characters or less is ideal), starts with the type of change Blank line: Separates summary from body Body (optional): Explains what changed and why Simpler alternatives that are also fine Fix TODO in welcome. md Add schedule link to welcome page Both are clear and descriptive. The more structured format is a convention, not a requirement. Alternate approaches github.com: Click the pencil icon on the file, make the edit, fill in the commit message at the bottom github.dev: Press . to open the editor, edit the file, use the Source Control sidebar to commit VS Code: Edit locally, stage with git add , commit with git commit GitHub Desktop: Edit in your preferred editor, return to Desktop, write the message, click Commit What matters The learning objective is making a meaningful change and describing it in a commit message. Any clear edit with any descriptive message is a success." + }, + { + "id": "admin/qa-bundle/docs/solutions/solution-06-first-pr.html", + "title": "Solution Reference: Challenge 6 -- Your First Pull Request", + "url": "admin/qa-bundle/docs/solutions/solution-06-first-pr.html", + "body": "Solution Reference: Challenge 6 -- Your First Pull Request This shows what a complete pull request looks like. Example PR Title: Fix TODO: add workshop schedule link to welcome.md Body: ## What this changes Replaces the TODO placeholder on line 15 of `docs/welcome.md` with an actual link to the workshop schedule. ## Why Students need a working link to find session times. The TODO was a known gap filed in issue #3. Closes #3 Key elements Title Describes the change clearly: someone reading just the title understands what happened Short enough to scan in a list Body What: Summarizes the change Why: Explains the motivation Closes #N: Links to the issue this PR resolves -- GitHub automatically closes the issue when the PR merges Linked issue The Closes #3 line creates a two-way link. The issue shows "referenced by PR #5" and the PR shows "Closes #3." When the PR merges, issue #3 closes automatically. Passing checks If the repository has automated checks (the PR validation bot), a green checkmark appears. If checks fail, read the bot's feedback comment for specific guidance. Alternate linking syntax All of these work identically: Closes #3 Fixes #3 Resolves #3 What matters The learning objective is connecting a change (PR) to a reason (issue) through GitHub's linking system. If your PR has a clear title, a description, and references an issue number, you completed this challenge." + }, + { + "id": "admin/qa-bundle/docs/solutions/solution-07-merge-conflict.html", + "title": "Solution Reference: Challenge 7 -- Resolve a Merge Conflict", + "url": "admin/qa-bundle/docs/solutions/solution-07-merge-conflict.html", + "body": "Solution Reference: Challenge 7 -- Resolve a Merge Conflict This shows what conflict markers look like and how to resolve them. What conflict markers look like When Git cannot automatically merge two changes to the same lines, it inserts markers: <<<<<<< HEAD Welcome to the Learning Room! This is the main branch version. ======= Welcome to the Learning Room! This is my improved version with more detail. >>>>>>> fix/welcome-update The three sections Between <<<<<<< HEAD and ======= : The version on the branch you are merging INTO (usually main) Between ======= and >>>>>>> : The version on YOUR branch The marker lines themselves : Must be deleted -- they are not content Example resolution Before (with conflict markers): <<<<<<< HEAD Welcome to the Learning Room! This is the main branch version. ======= Welcome to the Learning Room! This is my improved version with more detail. >>>>>>> fix/welcome-update After (resolved): Welcome to the Learning Room! This is my improved version with more detail. Decision process You chose one of three options: Keep yours: Delete the HEAD section and all markers, keep your changes Keep theirs: Delete your section and all markers, keep the HEAD version Combine both: Write new text that incorporates ideas from both versions, delete all markers All three are valid. The choice depends on which version is better for the project. On github.com GitHub offers a conflict editor directly in the browser: Click "Resolve conflicts" on the PR page The editor highlights conflicting sections Edit the file to remove markers and keep the content you want Click "Mark as resolved" then "Commit merge" In VS Code VS Code highlights conflicts and offers clickable options above each conflict: "Accept Current Change" (HEAD version) "Accept Incoming Change" (your version) "Accept Both Changes" (keeps both, you edit after) What matters The learning objective is understanding that conflicts are normal and resolvable. If you removed all conflict markers and the file makes sense, you completed this challenge." + }, + { + "id": "admin/qa-bundle/docs/solutions/solution-08-culture.html", + "title": "Solution Reference: Challenge 8 -- Open Source Culture", + "url": "admin/qa-bundle/docs/solutions/solution-08-culture.html", + "body": "Solution Reference: Challenge 8 -- Open Source Culture This shows example reflection and triage output. Your response will be personal and different. Example reflection comment Reading the CODE_OF_CONDUCT.md and CONTRIBUTING.md files helped me understand that open source projects are communities, not just code. The contributing guide made it clear that you do not need to be an expert to participate -- filing a good issue is a contribution. One thing I had not considered: accessibility is not just about the product. The way we write issues, name branches, and structure documentation affects whether people with disabilities can participate in the development process itself. Example triage recommendation If your challenge asked you to evaluate an issue and recommend a label: Issue: "The welcome page loads slowly on mobile" Recommended label: bug Justification: This describes unexpected behavior (slow loading) that affects the user experience. It is not a feature request because the page is supposed to load quickly. The bug label helps maintainers prioritize fixes. Additional label suggestion: accessibility -- slow loading disproportionately affects users on assistive technology where each reload is more disruptive. Alternate approaches Focus on CODE_OF_CONDUCT.md and what it means for inclusive collaboration Focus on CONTRIBUTING.md and what you learned about the contribution process Compare this project's guidelines to another open source project you have seen What matters The learning objective is understanding that open source has cultural norms, not just technical ones. Any thoughtful reflection that shows engagement with the governance and contribution documents is a success." + }, + { + "id": "admin/qa-bundle/docs/solutions/solution-09-merge-day.html", + "title": "Solution Reference: Challenge 9 -- Merge Day", + "url": "admin/qa-bundle/docs/solutions/solution-09-merge-day.html", + "body": "Solution Reference: Challenge 9 -- Merge Day This shows what a successful Day 1 completion looks like. What happens at merge When your PR from Challenge 6 (or a later challenge) is approved and merged: The "Merge pull request" button turns green After clicking it, your branch's commits appear on main The linked issue (from Closes #N ) automatically closes The PR status changes to "Merged" with a purple icon Example evidence Your Day 1 recap evidence might include: What I merged: PR #5 which fixed the TODO in welcome.md (linked to issue #3) What I learned today: Repositories have a navigable structure with tabs for code, issues, and PRs Issues document problems; PRs propose solutions Branches let you work without affecting main Merge conflicts happen when two people change the same lines -- they are normal and fixable Open source projects have community guidelines that shape how people collaborate What surprised me: How much of open source is communication (issues, PR descriptions, comments) rather than just writing code. Alternate approaches Post your recap as a comment on your challenge issue Share a summary in the workshop discussion channel Write a short reflection in a new file on your branch What matters The learning objective is completing the Day 1 loop: issue to branch to commit to PR to merge. If you merged at least one PR and can articulate what you learned, you completed this challenge." + }, + { + "id": "admin/qa-bundle/docs/solutions/solution-10-go-local.html", + "title": "Solution Reference: Challenge 10 -- Go Local", + "url": "admin/qa-bundle/docs/solutions/solution-10-go-local.html", + "body": "Solution Reference: Challenge 10 -- Go Local This shows the local Git workflow from clone through push. Terminal/CLI approach # Clone the repository git clone https://github.com/<workshop-org>/learning-room-<your-username>.git cd learning-room # Create a branch git checkout -b fix/local-edit # Make an edit (any text editor works) # For example, fix a typo or add content to docs/welcome.md # Stage the change git add docs/welcome.md # Commit with a descriptive message git commit -m "docs: fix typo in welcome page" # Push the branch to GitHub git push -u origin fix/local-edit VS Code approach Open the Command Palette (Ctrl+Shift+P or Cmd+Shift+P) Run "Git: Clone" and paste the repository URL Open the cloned folder Click the branch name in the bottom-left status bar, create a new branch Edit a file Open the Source Control sidebar (Ctrl+Shift+G) Stage changes with the + icon, type a commit message, click the checkmark Click "Publish Branch" or use the sync button GitHub Desktop approach File, Clone Repository, paste the URL Current Branch dropdown, New Branch Open the file in your editor and make a change Return to GitHub Desktop -- it shows the diff Write a commit message at the bottom-left, click "Commit" Click "Publish branch" to push Verifying success After pushing, go to github.com and you should see: A banner saying "fix/local-edit had recent pushes" with a "Compare & pull request" button Your branch in the branch dropdown Your commit in the branch's commit history What matters The learning objective is executing the full local workflow: clone, branch, edit, commit, push. The specific change you made does not matter. If your branch appeared on GitHub with your commit, you succeeded." + }, + { + "id": "admin/qa-bundle/docs/solutions/solution-11-day2-pr.html", + "title": "Solution Reference: Challenge 11 -- Day 2 Pull Request", + "url": "admin/qa-bundle/docs/solutions/solution-11-day2-pr.html", + "body": "Solution Reference: Challenge 11 -- Day 2 Pull Request This shows a PR created from a locally-pushed branch. Example PR Title: docs: improve welcome page formatting and fix broken link Body: ## Changes - Fixed the broken link to the schedule on line 22 - Added a "Getting Help" section after the introduction - Cleaned up inconsistent heading levels ## How I made these changes I cloned the repo locally (Challenge 10), created a branch called `fix/welcome-improvements` , made the edits in VS Code, committed, and pushed. This PR is the result. Closes #8 ## Pattern recognition Compared to my Day 1 PR (Challenge 6), this one: - Started from a local clone instead of the GitHub web editor - Had multiple commits instead of just one - Required a `git push` step that Day 1 did not need What is different from Day 1 Day 1 PR (Challenge 6) Day 2 PR (Challenge 11) Edited on github.com or github.dev Edited locally in VS Code, Desktop, or terminal Single commit created through the web UI One or more commits created with git commit Branch created on GitHub Branch created locally with git checkout -b No push needed (already on GitHub) Required git push to send branch to GitHub PR created from the web prompt PR created from the web prompt or gh pr create What matters The learning objective is recognizing the similarities and differences between web-based and local Git workflows. Both end with a PR. If you created a PR from a locally-pushed branch and noted what changed compared to Day 1, you completed this challenge." + }, + { + "id": "admin/qa-bundle/docs/solutions/solution-12-review.html", + "title": "Solution Reference: Challenge 12 -- Code Review", + "url": "admin/qa-bundle/docs/solutions/solution-12-review.html", + "body": "Solution Reference: Challenge 12 -- Code Review This shows what a complete code review looks like. Example review on a buddy's PR Inline comment (on a specific line) Line 18 of docs/welcome.md: This heading says "## getting started" but the other headings in the file use title case ("## What You Will Learn"). Consider changing it to "## Getting Started" for consistency. Suggestion (using GitHub's suggestion feature) ## Getting Started Using the suggestion feature lets the PR author accept the change with one click, which creates a commit automatically. Review verdict Changes requested Good work overall. The content additions are helpful and well-written. Two things to address before merging: Heading capitalization inconsistency (see inline comment on line 18) The new link on line 25 points to http:// instead of https:// -- please update for security Once those are fixed, this is ready to merge. Types of review comments Praise: "This section reads really clearly" -- positive feedback encourages good practices Question: "What happens if the user does not have a GitHub account yet?" -- surfaces assumptions Suggestion: Use the suggestion block to propose specific text changes Required change: "The YAML frontmatter is missing the description field, which is required" What matters The learning objective is providing constructive feedback on someone else's work. If you left at least one specific, helpful comment on a buddy's PR, you completed this challenge. The quality of feedback matters more than the quantity." + }, + { + "id": "admin/qa-bundle/docs/solutions/solution-13-copilot.html", + "title": "Solution Reference: Challenge 13 -- Copilot as Collaborator", + "url": "admin/qa-bundle/docs/solutions/solution-13-copilot.html", + "body": "Solution Reference: Challenge 13 -- Copilot as Collaborator This shows an example Copilot interaction and critical evaluation. Example interaction transcript Prompt to Copilot: Review the alt text in docs/welcome.md and suggest improvements for screen reader users. Copilot response (example): The image on line 42 has alt="screenshot" which is not descriptive. A better alternative would be: alt="Learning Room repository page showing the Code tab with a list of files including README.md, docs folder, and .github folder" . Before and after Before: ![ screenshot ]( images/repo-overview.png ) After (improved with Copilot's help): ![ Learning Room repository Code tab showing file list with README.md, docs folder, and .github folder ]( images/repo-overview.png ) Critical evaluation notes Not everything Copilot suggests is correct. Here is how to evaluate: What Copilot got right: The suggestion to be more descriptive than "screenshot" is correct. Screen reader users need to understand what the image communicates, not just that it exists. What I adjusted: Copilot's suggested alt text was 30 words. I shortened it to 18 words while keeping the key information. Alt text should be concise. What Copilot missed: It did not flag that the image might be decorative (meaning alt="" would be appropriate). I checked -- it is informational, so descriptive alt text is correct. Alternate approaches Ask Copilot to improve documentation clarity, then evaluate whether the suggestions make sense Ask Copilot to check Markdown formatting, then verify its corrections Ask Copilot to suggest commit messages, then refine them What matters The learning objective is using AI as a collaborator while maintaining your own judgment. If you used Copilot, evaluated its output critically, and made an improvement based on that evaluation, you completed this challenge." + }, + { + "id": "admin/qa-bundle/docs/solutions/solution-14-template.html", + "title": "Solution Reference: Challenge 14 -- Design an Issue Template", + "url": "admin/qa-bundle/docs/solutions/solution-14-template.html", + "body": "Solution Reference: Challenge 14 -- Design an Issue Template This shows a completed custom YAML issue template with annotations. Example template File: .github/ISSUE_TEMPLATE/accessibility-report.yml # The name appears in the template chooser when someone clicks "New Issue" name: Accessibility Report # The description appears below the name in the chooser description: Report an accessibility barrier in workshop materials # Labels are automatically applied to issues created from this template labels: [ "accessibility" , "bug" ] # The title field pre-fills the issue title with a pattern title: "[A11y]: " # The body defines the form fields body: # A description field adds context that is not an input - type: markdown attributes: value: | Thank you for reporting an accessibility barrier. Your feedback helps us make the workshop inclusive for everyone. # A text input for a short answer - type: input id: location attributes: label: Where did you encounter the barrier? description: File name, URL, or description of where the problem is placeholder: "Example: docs/welcome.md line 15" validations: required: true # A textarea for a longer description - type: textarea id: description attributes: label: Describe the barrier description: What happened? What did you expect to happen? validations: required: true # A dropdown for assistive technology - type: dropdown id: assistive-tech attributes: label: Assistive technology (if applicable) options: - Screen reader (NVDA) - Screen reader (JAWS) - Screen reader (VoiceOver) - Screen magnifier - Voice control - Switch access - Keyboard only - Other - Not applicable validations: required: false # A dropdown for severity - type: dropdown id: severity attributes: label: How much does this affect your ability to participate? options: - Blocked (cannot continue) - Difficult (can work around it) - Minor (cosmetic or preference) validations: required: true What each field type does Type Purpose When to use markdown Displays text that is not an input field Instructions, context, legal notices input Single-line text field Short answers like file names, URLs, versions textarea Multi-line text field Descriptions, steps to reproduce, long answers dropdown Selection from predefined options Categories, severity levels, yes/no questions checkboxes Multiple selection checkboxes Checklists, acknowledgments, multi-select categories Alternate valid templates Any topic works for this challenge. Other examples: A bug report template for the workshop A feature request template for new workshop topics A feedback template for session evaluations A question template for asking for help What matters The learning objective is understanding structured issue templates as a way to guide contributors. If your YAML file has a name , description , and at least one body field, you completed this challenge." + }, + { + "id": "admin/qa-bundle/docs/solutions/solution-15-agents.html", + "title": "Solution Reference: Challenge 15 -- Discover Accessibility Agents", + "url": "admin/qa-bundle/docs/solutions/solution-15-agents.html", + "body": "Solution Reference: Challenge 15 -- Discover Accessibility Agents This shows example agent discovery notes. Example: Three agents examined Agent 1: accessibility-lead Location: .github/agents/accessibility-lead.agent.md Purpose: Coordinates accessibility reviews across the team. Acts as an orchestrator that delegates to specialist agents. Key observation: This agent does not do the accessibility checking itself -- it routes requests to the right specialist (ARIA, keyboard, contrast, etc.). This is a design pattern called orchestration. Agent 2: aria-specialist Location: .github/agents/aria-specialist.agent.md Purpose: Reviews ARIA (Accessible Rich Internet Applications) attributes in HTML and web components. Checks that interactive elements have correct roles, states, and properties. Key observation: The agent instructions reference specific ARIA patterns from the W3C specification. Custom agents can encode domain expertise. Agent 3: keyboard-navigator Location: .github/agents/keyboard-navigator.agent.md Purpose: Ensures that all interactive elements are operable by keyboard. Checks tab order, focus management, and keyboard shortcuts. Key observation: The guardrails section says it cannot test actual keyboard behavior -- it can only review code. Testing still requires a human with a keyboard. Example: Running an agent What I asked: "@accessibility-lead review the heading structure of this file" What it did: The lead agent delegated to the alt-text-headings specialist, which analyzed the heading levels and reported that the file skipped from H2 to H4. What I learned: Agents can chain together. The lead interpreted my request and chose the right specialist. I did not need to know which agent handles headings. Example: Reading agent instructions Looking at the .agent.md file structure: YAML frontmatter: Contains the agent name, description, and tool restrictions Responsibilities section: Lists what the agent is designed to do Guardrails section: Lists what the agent should NOT do or cannot do reliably What matters The learning objective is understanding that AI agents are configurable tools with defined boundaries. If you examined at least one agent's instructions and can explain what it does and what it will not do, you completed this challenge." + }, + { + "id": "admin/qa-bundle/docs/solutions/solution-16-capstone.html", + "title": "Solution Reference: Challenge 16 -- Build Your Own Agent (Capstone)", + "url": "admin/qa-bundle/docs/solutions/solution-16-capstone.html", + "body": "Solution Reference: Challenge 16 -- Build Your Own Agent (Capstone) This shows a complete agent file with annotations. Example agent file File: community-agents/workshop-buddy.agent.md --- # YAML frontmatter -- metadata about the agent name: Workshop Buddy description: A friendly guide that helps students navigate the Git Going with GitHub workshop tools: [] --- # Workshop Buddy ## Responsibilities <!-- This section defines what the agent is designed to do --> - Answer questions about workshop challenges and point students to the right chapter - Explain Git and GitHub concepts in beginner-friendly language - Suggest next steps when a student is stuck on a challenge - Remind students about accessibility best practices in their contributions ## Guardrails <!-- This section defines what the agent should NOT do --> - Do not complete challenges for the student -- guide, do not solve - Do not make changes to repository files directly - Do not provide answers to challenge evidence prompts - Do not access external services or APIs - If asked about topics outside the workshop scope, say so honestly and suggest other resources ## Example interactions **Student asks:** "I am stuck on Challenge 7. What are conflict markers?" **Agent responds:** Conflict markers are lines Git adds when it cannot automatically merge two changes. They look like `<<<<<<< HEAD` , `=======` , and `>>>>>>>` . You need to decide which version to keep and delete the marker lines. See Chapter 7 for a walkthrough. **Student asks:** "Write my PR description for me." **Agent responds:** I cannot write your PR description because that is the evidence for Challenge 6. But I can help you think about what to include. What did you change, and why? Start with those two sentences and you have a strong description. PR description for the capstone ## New agent: Workshop Buddy This agent helps students navigate the Git Going with GitHub workshop by answering questions about challenges, explaining Git concepts, and suggesting next steps. ### Design decisions - **Guide, do not solve:** The guardrails prevent the agent from completing challenges, because the learning happens in the doing - **Scoped to the workshop:** The agent is honest about its boundaries rather than guessing at topics it was not designed for - **Accessibility aware:** Reminders about inclusive contribution practices are part of the agent's responsibilities ### Checklist - [x] YAML frontmatter with name and description - [x] Responsibilities section - [x] Guardrails section - [x] Example interactions showing both helpfulness and boundaries Alternate valid agents Any agent concept works. Other examples students have built: An agent that reviews Markdown formatting An agent that checks issue titles for clarity An agent that recommends which Git command to use An agent that explains error messages What matters The learning objective is understanding that AI agents are defined by their responsibilities AND their guardrails. If your agent file has valid YAML frontmatter, a clear purpose, and explicit boundaries, you completed this challenge. The creativity of the concept is a bonus, not a requirement." + }, + { + "id": "admin/qa-bundle/docs/solutions/solution-bonus-a.html", + "title": "Solution Reference: Bonus A -- Improve an Agent", + "url": "admin/qa-bundle/docs/solutions/solution-bonus-a.html", + "body": "Solution Reference: Bonus A -- Improve an Agent This shows an example improvement PR for an existing accessibility agent. Example improvement Target agent: aria-specialist.agent.md What I changed: Added a new responsibility for checking aria-live regions in dynamic content. The existing agent covered static ARIA roles but did not mention live regions, which are critical for screen reader users interacting with content that updates without a page reload. Before (responsibilities excerpt): - Check that interactive elements have correct ARIA roles - Verify that ARIA states match the visual state of components After (with addition): - Check that interactive elements have correct ARIA roles - Verify that ARIA states match the visual state of components - Review aria-live regions for appropriate politeness levels (polite vs assertive) on dynamic content updates PR description: Adds live region checking to the ARIA specialist agent's responsibilities. Dynamic content updates (search results, notifications, form validation messages) need aria-live attributes so screen readers announce changes. The agent currently checks static ARIA attributes but not live regions. This addition closes that gap. What matters The learning objective is contributing to an existing project by understanding its conventions and making a targeted improvement. If you identified a real gap and proposed a specific, well-reasoned change, you completed this bonus." + }, + { + "id": "admin/qa-bundle/docs/solutions/solution-bonus-b.html", + "title": "Solution Reference: Bonus B -- Document Your Journey", + "url": "admin/qa-bundle/docs/solutions/solution-bonus-b.html", + "body": "Solution Reference: Bonus B -- Document Your Journey This shows an example reflection document. Example journey reflection # My Git Going with GitHub Journey ## Before the workshop I had never used Git or GitHub. I thought "version control" was saving files as `report-final.docx` , `report-final-v2.docx` , `report-ACTUALLY-final.docx` . ## Day 1: You Belong Here The scavenger hunt (Challenge 1) made the GitHub interface feel less intimidating. I learned that a repository is organized like a folder with special powers -- it tracks every change anyone makes. Filing my first issue (Challenge 2) surprised me. I expected issues to be complaints, but they are really conversations about improvements. Writing a clear title forced me to clarify my thinking before I started typing. The merge conflict (Challenge 7) was the moment everything clicked. Seeing the conflict markers and understanding that Git was asking ME to make a human decision -- not failing or breaking -- changed how I think about collaboration. ## Day 2: You Can Build This Going local (Challenge 10) felt powerful. Having the files on my machine and using the terminal made me feel like a real developer, even though all I did was fix a typo. The code review (Challenge 12) taught me that feedback is a skill. My first attempt at reviewing was just "looks good" on everything. After reading the chapter, I went back and left a specific suggestion that my buddy actually used. That felt collaborative in a way I had not expected. ## What I will do next - Contribute to an accessibility project on GitHub - Set up Git on my personal laptop - Explore GitHub Skills for more practice ## One sentence summary I came in thinking Git was too technical for me and left knowing it is a communication tool that anyone can learn. What matters The learning objective is structured reflection using proper Markdown. If you wrote a document with headings, paragraphs, and honest reflection, you completed this bonus." + }, + { + "id": "admin/qa-bundle/docs/solutions/solution-bonus-c.html", + "title": "Solution Reference: Bonus C -- Create a Group Challenge", + "url": "admin/qa-bundle/docs/solutions/solution-bonus-c.html", + "body": "Solution Reference: Bonus C -- Create a Group Challenge This shows an example group challenge design. Example: Accessibility Audit Relay Designed for: 3-5 students Challenge description Students audit a sample web page for accessibility issues, relay-style. Each person has a different focus area: Student 1: Checks all images for meaningful alt text Student 2: Reviews heading hierarchy (H1, H2, H3 order) Student 3: Tests every link for descriptive text (no "click here") Student 4: Checks color contrast on text elements Student 5 (if present): Reviews keyboard navigation order How it works The group forks a sample repository containing a deliberately imperfect HTML page Each student creates a branch for their focus area Each student files issues for the problems they find The group discusses which fixes to prioritize Each student submits a PR fixing at least one issue The group reviews and merges each other's PRs Evidence Each student posts: their issues filed, their PR, and one review they gave. Why this works for a group Every student has a defined role so no one is left out The relay structure means students depend on each other (Student 3 cannot fix link text if Student 1 has not pushed their alt text fixes yet) The final product is a genuinely more accessible page What matters The learning objective is designing collaborative work that gives every participant a meaningful role. If your challenge design includes clear roles, concrete deliverables, and a reason for people to work together (not just alongside each other), you completed this bonus." + }, + { + "id": "admin/qa-bundle/docs/solutions/solution-bonus-d.html", + "title": "Solution Reference: Bonus D -- Notification Mastery", + "url": "admin/qa-bundle/docs/solutions/solution-bonus-d.html", + "body": "Solution Reference: Bonus D -- Notification Mastery This shows a configured notification setup with before/after. Before: Default settings With default settings, GitHub sends email notifications for: Every issue and PR in every repository you watch Every comment on any thread you have participated in Every CI status update This quickly becomes overwhelming. Most people start ignoring all GitHub emails. After: Configured settings Notification settings (github.com/settings/notifications) Participating: Email ON, Web ON -- you want to know when someone replies to your conversations Watching: Email OFF, Web ON -- browse these when you have time, not in your inbox GitHub Actions: Email OFF for successful runs, Email ON for failed runs only Repository watching Repositories you actively contribute to: Watch (all activity) Repositories you read occasionally: Custom (issues and PRs only) Repositories you finished with: Unwatch Custom routing (if you use multiple emails) Route Community-Access organization notifications to your workshop email Route personal project notifications to your personal email Key decisions explained Why email off for watching: You can check the notification bell on github.com when you choose. Email notifications for watched repos create constant interruption for low-priority updates. Why Actions failures only: A green checkmark in the PR is enough. You only need an email when something breaks. Why unwatch finished repos: Your notification feed stays relevant to current work. What matters The learning objective is intentional notification management. If you changed at least one setting from the default and can explain why that change reduces noise while keeping you informed about what matters, you completed this bonus." + }, + { + "id": "admin/qa-bundle/docs/solutions/solution-bonus-e.html", + "title": "Solution Reference: Bonus E -- Explore Git History Visually", + "url": "admin/qa-bundle/docs/solutions/solution-bonus-e.html", + "body": "Solution Reference: Bonus E -- Explore Git History Visually This shows a visual history exploration. On github.com Viewing commit history Navigate to any repository Click the "X commits" link near the top (shows total commit count) The history page shows each commit with author, date, message, and SHA Click any commit to see what changed (green lines added, red lines removed) What you see The commit history tells the story of a project: Chronological order: Most recent commits first Author attribution: Every change has a name attached Commit messages: Each entry explains what changed and (ideally) why Diffs: Click any commit to see exactly which lines were added, removed, or modified In GitHub Desktop Visual timeline Open the repository in GitHub Desktop Click the "History" tab The left panel shows commits as a timeline Click any commit to see the diff in the right panel The branch visualization shows where branches diverged and merged Key observations from exploring history Merge commits show where two branches came together -- they have two parent commits The first commit in a repository is often called "initial commit" and creates the project structure Commit frequency varies -- some days have many commits, others have none. This is normal. In VS Code The "Timeline" view in the Explorer sidebar shows the history for the currently open file. Each entry is a commit that changed that file. This is useful for understanding how a specific file evolved. What matters The learning objective is understanding that Git history is a navigable record of every change. If you explored the commit history, clicked into at least one commit to see its diff, and can describe what the history tells you about the project, you completed this bonus." + }, + { + "id": "admin/qa-bundle/docs/00-pre-workshop-setup.html", + "title": "Pre-Workshop Setup - GIT Going with GitHub", + "url": "admin/qa-bundle/docs/00-pre-workshop-setup.html", + "body": "Pre-Workshop Setup - GIT Going with GitHub Listen to Episode 1: Pre-Workshop Setup - 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 Y: Workshop Materials | Appendix Z: GitHub Skills Authoritative sources: GitHub Docs: Create an account | GitHub Docs: Set up Git Everything You Need Before Day 1 Begins A Community Access workshop. Please complete this guide at least one day before the workshop. If you run into any issues, use the support hub at Community-Access/support 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 . 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 What You Will Need Step 1 - Create Your GitHub Account Step 2 - Configure GitHub Accessibility Settings Step 3 - Configure Your Profile Step 4 - Check GitHub Feature Preview Settings Step 5 - Set Up Your Screen Reader and Browser Step 6 - Install Git and Visual Studio Code Step 7 - Configure Git Identity Step 8 - Install VS Code Extensions Step 9 - Verification Checklist Other GitHub Access Methods (Reference Only) 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 (Windows/Linux) or Xcode Command Line Tools (macOS) Visual Studio Code (free) - download here (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 JAWS (Job Access With Speech) Windows Paid (trial available) Download 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 covers SSH keys and personal access tokens in detail. If you already have a GitHub account, skip to Step 2 . 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 Open your browser and navigate to the GitHub signup page The page loads with focus on the first field: "Enter your email address" Type your email address and press Tab or activate Continue The next field is "Create a password" Choose a password of at least 8 characters (15+ recommended). Press Tab or Continue 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 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 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 Activate the Create account button 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 w" + }, + { + "id": "admin/qa-bundle/docs/01-choose-your-tools.html", + "title": "Choose Your Adventure: A Tool Tour", + "url": "admin/qa-bundle/docs/01-choose-your-tools.html", + "body": "Choose Your Adventure: A Tool Tour Related appendices: Appendix G: VS Code Reference | Appendix H: GitHub Desktop | Appendix I: GitHub CLI | Appendix J: Codespaces Authoritative sources: VS Code Docs: Setup | GitHub Desktop Docs | GitHub CLI 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 Why This Matters The Five Paths Path 1: GitHub.com (Browser) Path 2: github.dev (Browser-Based Editor) Path 3: VS Code (Desktop) Path 4: GitHub Desktop Path 5: GitHub CLI Which Path Should I Start With? Your First Confidence Exercise 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 . 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 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: Go to github.com/settings/appearance Choose from Light, Dark, Light high contrast, or Dark high contrast 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 rep" + }, + { + "id": "admin/qa-bundle/docs/02-understanding-github.html", + "title": "Understanding GitHub's Web Structure", + "url": "admin/qa-bundle/docs/02-understanding-github.html", + "body": "Understanding GitHub's Web Structure Listen to Episode 2: Understanding GitHub on the Web - 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 B: Screen Reader Cheat Sheet Authoritative sources: GitHub Docs: About GitHub | GitHub Accessibility 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 and Chapter 04 . Read this chapter first to build the mental model, then navigate repositories with confidence. GitHub's Three-Level Structure What Is Always on Every GitHub Page How to Tell Where You Are The Five Key Page Types Visual Map of a Repository Page Screen Reader Orientation Sequence Landmark Structure by Page Type GitHub's Heading Hierarchy in Practice How GitHub's Layout Changes by Viewport 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. 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 shrin" + }, + { + "id": "admin/qa-bundle/docs/03-navigating-repositories.html", + "title": "Navigating Repositories", + "url": "admin/qa-bundle/docs/03-navigating-repositories.html", + "body": "Navigating Repositories Listen to Episode 3: Navigating Repositories - 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 B: Screen Reader Cheat Sheet Authoritative sources: GitHub Docs: About repositories | GitHub Accessibility Guide: Repositories 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 . 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: Learn the page structure (heading, landmarks, tabs). Practice orientation ( 1 , D , heading list). Confirm readiness with a peer or facilitator. 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: The page title is announced with the format: owner/repo-name: Short description - GitHub First heading ( 1 key) will navigate to the repo name: "owner/repo-name" The tab bar is a landmark labeled "Repository navigation" Orientation sequence (do this on every new repo) 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 t" + }, + { + "id": "admin/qa-bundle/docs/04-the-learning-room.html", + "title": "The Learning Room: Your Personal Practice Repository", + "url": "admin/qa-bundle/docs/04-the-learning-room.html", + "body": "The Learning Room: Your Personal Practice Repository Listen to Episode 4: The Learning Room - 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 C: Markdown Reference Authoritative sources: GitHub Docs: About README files | GitHub Docs: 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 repository into the workshop classroom organization as <workshop-org>/learning-room-<your-username> . 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 ) 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/<random-id> . If you do not have it, ask in chat or DM the facilitator. 1. Open the assignment link In the same browser where you are signed into GitHub, open the Day 1 assignment link the facilitator shared. 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"). 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. 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. Activate the link or button next to your name. 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 You now see a screen with a button that says Accept this assignment (or just Accept the assignment ). Activate it. 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. 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/<workshop-org>/learning-room-<your-userna" + }, + { + "id": "admin/qa-bundle/docs/05-working-with-issues.html", + "title": "Working with Issues", + "url": "admin/qa-bundle/docs/05-working-with-issues.html", + "body": "Working with Issues Listen to Episode 5: Working with Issues - a conversational audio overview of this chapter. Listen before reading to preview the concepts, or after to reinforce what you learned. Related appendices: Appendix N: Advanced Search | Appendix V: GitHub Mobile | Appendix B: Screen Reader Cheat Sheet Authoritative sources: GitHub Docs: About issues | GitHub Accessibility Guide: Issues Filing, Managing, and Participating in GitHub Issues Issues are where open source collaboration begins. This guide covers everything from finding the right issue to file a perfect bug report - all with your keyboard and screen reader. Official GitHub Accessibility Guide: GitHub publishes an NVDA-focused guide for working with issues using a screen reader at Using GitHub Issues with a Screen Reader . This chapter covers the same material with additional perspectives (VoiceOver, low vision, CLI) and workshop-specific challenges. Use the official guide as a companion reference. Screen reader note - New Issues Experience: This guide uses GitHub's improved Issues experience, which provides better ARIA landmark structure and live-region announcements for screen readers. This feature may already be active for your account - it has been broadly rolled out and may no longer appear as a Feature Preview toggle at all. To verify: Activate the User Menu button (top-right of any GitHub page) → activate "Feature preview" → scan the list for "New Issues Experience" : If listed and the toggle announces "Pressed" (or "Disable" ) - already enabled, no action needed If listed but not Pressed (or "Enable" ) - activate the toggle to enable it If not listed at all - the feature has graduated to the standard interface; it is active automatically Full step-by-step instructions with per-screen-reader commands are in Pre-Workshop Setup, Step 4 . Browse vs Focus Mode (NVDA): Toggle between modes with NVDA+Space (NVDA key = Insert or Caps Lock ). Use Browse Mode (the default) for reading lists, headings, and issue content. Switch to Focus Mode when typing in text fields and search boxes. Use NVDA+F7 at any time to open a list of all headings, links, form fields, buttons, and landmarks on the page - this is your orientation tool. Workshop Recommendation (Chapter 5 / Challenges 2-3) Chapter 5 is the first issue-based challenge chapter with short, confidence-building tasks. It supports Challenge 2 (File Your First Issue) and Challenge 3 (Join the Conversation). Challenge count: 2 core challenges plus one optional extension Time per challenge: under 10 minutes Evidence: issue comments and issue metadata Pattern: claim -> act -> confirm Chapter 5 Challenge Set Create your first issue - file a new issue with a clear title and description. Comment and @mention - leave a comment on a classmate's issue and tag them with an @mention. Optional extension: Add a sub-issue - break a larger issue into smaller, trackable pieces if your repository has sub-issues enabled. Branch guidance for Chapter 5: Chapter 5 focuses on issue skills. You do NOT need to create a branch or edit any files for these challenges. All your work happens in GitHub issue threads. File editing and branches start in Chapter 6. How completion works: When you finish the issue challenges, post evidence in your assigned challenge issues with links to the issue you created and the comment you posted. The facilitator reviews your issue activity directly. No pull request is required for Chapter 5. Challenge 2 Step-by-Step: Create Your First Issue Goal: File a new issue in your Learning Room repository with a specific title and a meaningful description. Agentic strategy: Issues are the prompts that wake up AI. A clear issue for a human is also a prompt for an agent. For this challenge, log an issue describing an accessibility problem or chore you wish an AI agent could fix for you. Where you are working: the Issues tab of your Learning Room repository on GitHub.com. Open your Learning Room repository in your browser. Navigate to the Issues tab (press G then I to jump there with keyboard shortcuts, or find the "Issues" link in the repository navigation). Activate the New issue button. If a template picker appears, select Open a blank issue (or choose a template if one fits). In the Title field, type a clear, specific title (at least 12 characters). Examples: "Agent Request: Add missing contributor background paragraph in welcome.md" "Keyboard shortcuts table has incorrect NVDA modifier key" "Setup guide link to accessibility settings is broken" 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. Activate Submit new issue . Copy the issue URL or note the issue number (for example, #150 ). You will reference this l" + }, + { + "id": "admin/qa-bundle/docs/06-working-with-pull-requests.html", + "title": "Working with Pull Requests", + "url": "admin/qa-bundle/docs/06-working-with-pull-requests.html", + "body": "Working with Pull Requests Listen to Episode 6: Working with Pull Requests - a conversational audio overview of this chapter. Listen before reading to preview the concepts, or after to reinforce what you learned. Related appendices: Appendix C: Markdown Reference | Appendix B: Screen Reader Cheat Sheet Authoritative sources: GitHub Docs: About pull requests | GitHub Accessibility Guide: Pull Requests Creating, Reviewing, and Merging Pull Requests with a Screen Reader See also: Chapter 15: Code Review covers the full review workflow including multi-file diffs and suggested changes. Pull requests are where your work becomes a contribution. This guide takes you through the full pull request workflow - from opening one to participating in review - using only your keyboard and screen reader. Official GitHub Accessibility Guide: GitHub publishes an NVDA-focused guide for working with pull requests using a screen reader at Using GitHub Pull Requests with a Screen Reader . This chapter covers the same material with additional perspectives (VoiceOver, low vision, CLI) and workshop-specific challenges. Use the official guide as a companion reference. Screen reader note - New Files Changed Experience: This guide uses GitHub's improved Files Changed experience, which adds proper ARIA landmark structure to the Files Changed tab, including the file tree and diff navigation. This feature may already be active for your account - it has been broadly rolled out and may no longer appear as a Feature Preview toggle at all. To verify: Activate the User Menu button (top-right of any GitHub page) → activate "Feature preview" → scan the list for "New Files Changed Experience" : If listed and the toggle announces "Pressed" (or "Disable" ) - already enabled, no action needed If listed but not Pressed (or "Enable" ) - activate the toggle to enable it If not listed at all - the feature has graduated to the standard interface; it is active automatically Full step-by-step instructions with per-screen-reader commands are in Pre-Workshop Setup, Step 4 . Browse vs Focus Mode (NVDA): Use Browse Mode (the default) for reading PR conversations, navigating headings, and reviewing diffs. Switch to Focus Mode ( NVDA+Space ) only when you need to type in comment boxes or search fields. Switch back to Browse Mode to resume navigation. Maximize your browser window for consistent landmark layout. Workshop Recommendation (Chapter 6) Chapter 6 is the first PR-validated chapter where students convert issue work into merge-ready contributions. Challenge count: 3 Time per challenge: under 10 minutes each Evidence: PR metadata, bot checks, and merged issue linkage Pattern: small change -> linked PR -> green checks Chapter 6 Challenge Set Create one small branch change - edit a practice file on a new branch. Open a linked PR - use the PR template and include Closes #XX . Pass required checks - respond to bot feedback until all required checks pass. Branch guidance for Chapter 6: This is the first chapter where you edit files and create branches. Use one of these two paths: Web editor (recommended for beginners): When you edit a file on GitHub.com and click "Propose changes," GitHub creates a branch for you automatically. Name it fix/yourname-issueXX (for example, fix/maria-issue42 ). Local Git (if you cloned in Block 0): Create a feature branch with git checkout -b fix/yourname-issueXX from main . See the "Local Git Alternative" section below for the full command sequence. Do not reuse your learn/<username> branch for this short exercise unless your facilitator tells you to. Chapter 6 works best with a short-lived feature branch such as fix/yourname-issueXX , because it teaches the pull request loop without mixing multiple challenges on one branch. Challenge 6.1 Step-by-Step: Create One Small Branch Change Goal: Edit one of the practice files and save your change on a new branch. Where you are working: your Learning Room repository on GitHub.com, using the web editor. Before you start: Open your assigned Chapter 6.1 challenge issue (the one titled "Chapter 6.1: Create One Small Branch Change (@yourname)"). The issue description tells you which file to edit and what to fix. The Learning Room has three practice files with intentional problems. Your assigned issue points you to one of them: The following table summarizes the practice files in the learning-room, what each file contains, and the type of issues to look for. File What it contains 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: In your Learning Room repository, navigate to the file specified in your issue. Use the file t" + }, + { + "id": "admin/qa-bundle/docs/07-merge-conflicts.html", + "title": "Merge Conflicts", + "url": "admin/qa-bundle/docs/07-merge-conflicts.html", + "body": "Merge Conflicts Listen to Episode 7: Merge Conflicts Are Not Scary - 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 G: VS Code Reference Authoritative sources: GitHub Docs: Resolving merge conflicts | Git SCM: Basic Merge Conflicts Understanding, Preventing, and Resolving Conflicts Merge conflicts sound intimidating but are a normal, manageable part of collaborative development. This guide explains what conflicts are, how to read conflict markers, and how to resolve them - step by step. Workshop Recommendation (Chapter 7) Chapter 7 uses one controlled practice challenge so students can learn conflict resolution without high-pressure scenarios. Challenge count: 1 Time: under 10 minutes Evidence: issue-linked PR and completion comment Pattern: observe, resolve, verify Chapter 7 Challenge Set Resolve conflict markers - identify and clean up conflict markers in a practice file, then open a linked PR. Branch guidance for Chapter 7: Use a short-lived feature branch: fix/yourname-issueXX (for example, fix/maria-issue48 ). The same pattern you used in Chapter 6. Challenge 7.1 Step-by-Step: Resolve Conflict Markers Goal: Identify the three types of conflict markers in a practice file, decide which content to keep, remove the markers, and submit a clean PR. Agentic strategy: Sometimes an AI agent will confidently generate code that conflicts with human-written code. Resolving merge conflicts is not just a hurdle for human teamwork; it is exactly how you supervise, correct, and collaborate safely with an AI. Where you are working: your Learning Room repository on GitHub.com (web editor) or in VS Code if you cloned locally. Before you start: Open your assigned Chapter 7 challenge issue (the one titled "Chapter 7.1: Resolve Conflict Markers (@yourname)"). The issue description tells you which practice file contains the conflict markers. Practice sample: learning-room/docs/samples/chapter-6-conflict-practice-sample.md Open the practice file specified in your challenge issue. Search the file for <<<<<<< . This is the start marker - it shows where the conflict begins. Read the content between <<<<<<< and ======= . This is your version (the current branch). Read the content between ======= and >>>>>>> . This is their version (the incoming branch). Decide which content to keep: Keep only your version, or Keep only their version, or Combine both versions into one clean paragraph. Delete all three marker lines: The <<<<<<< HEAD line (or similar) The ======= separator line The >>>>>>> branch-name line Review the file to confirm no marker lines remain. Search for <<<<<<< again - there should be zero results. Commit your changes on a branch named fix/yourname-issueXX . Open a pull request with: Title: fix: resolve conflict markers in [filename] Body: Include Closes #XX (your challenge issue number) and a 1-2 sentence description of which content you kept and why. Screen reader tip: Use your screen reader's find command ( Ctrl+F in browser, Ctrl+H in VS Code) to jump directly to <<<<<<< . The markers are plain text, so they are fully readable. You are done when: Your PR passes bot validation checks and contains no remaining conflict markers. Completing Chapter 7: Submit Your Evidence When your PR is open and passing checks, post a comment on your assigned Chapter 7 challenge issue: Chapter 7 completed: - Challenge 7.1: Opened PR #[number] resolving conflict markers in [filename] - Content decision: kept [your version / their version / combined both] because [reason] Expected Outcomes Student can identify the three conflict marker lines ( <<<<<<< , ======= , >>>>>>> ) immediately. Student can read both sides of a conflict and make an intentional content decision. Student can remove all markers and submit a clean, issue-linked PR. If You Get Stuck Can't find the markers? Use Ctrl+F and search for <<<<<<< - they are always in sets of three. Not sure which side to keep? Read both versions aloud. Pick the one that is clearer, or combine them. Accidentally deleted too much? Undo with Ctrl+Z and start the section over. PR bot says content is wrong? Double-check that zero marker lines remain - search for <<<<<<< , ======= , and >>>>>>> . Ask facilitator to sanity-check your final content before opening the PR. Finished but not sure you did it right? Compare your work against the Challenge 7 reference solution . Learning Moment Merge conflicts are not failures. They are a normal collaboration checkpoint and a chance to make an intentional content decision. In real open source projects, conflicts happen whenever two people edit near " + }, + { + "id": "admin/qa-bundle/docs/08-open-source-culture.html", + "title": "Culture, Etiquette, and Community Standards", + "url": "admin/qa-bundle/docs/08-open-source-culture.html", + "body": "Culture, Etiquette, and Community Standards Listen to Episode 8: Open Source Culture and Etiquette - 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 F: Git Security | Appendix O: Branch Protection | Appendix W: GitHub Pages Authoritative sources: GitHub Docs: Contributing to open source | Open Source Guides: 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 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. Read through the chapter content below, paying attention to the sections on GitHub Flow, constructive feedback, and asking for help. As you read, think about one situation from Day 1 where communication helped (or could have helped) you. Open your assigned Chapter 8 challenge issue (the one titled "Chapter 8.1: Guided Reflection (@yourname)"). Scroll to the comment box at the bottom of the issue. Post a reflection comment using this format: 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: 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." 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 Use one simple sentence per prompt - do not overthink it. Focus on one real behavior you can start doing today, not an abstract principle. If writing feels hard, draft bullet points first in a text editor, then paste into the comment. Look at the "Giving Feedback" and "Asking for Help" sections in this chapter for concrete examples. Ask facilitator for one example response and adapt it to your own words. Finished but not sure you did it right? Compare your work against the Challenge 8 reference solution . 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 Read and absorb community norms (not just rules, but reasons). Reflect on personal experience (what worked, what was hard). Commit to specific behaviors in writing (public accountability). 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 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 └" + }, + { + "id": "admin/qa-bundle/docs/09-labels-milestones-projects.html", + "title": "Labels, Milestones, and Projects", + "url": "admin/qa-bundle/docs/09-labels-milestones-projects.html", + "body": "Labels, Milestones, and Projects Listen to Episode 9: Labels, Milestones, and Projects - 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 A: Glossary Authoritative sources: GitHub Docs: About labels | GitHub Docs: About milestones | GitHub Docs: 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 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. Open the Issues tab in your Learning Room repository. Find any open issue that does not already have labels applied (or pick one your facilitator assigns). 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? Open your assigned Chapter 9 challenge issue (the one titled "Chapter 9.1: Triage Recommendation (@yourname)"). Scroll to the comment box and post a triage recommendation using this format: 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] If you have write access to the repository, apply the recommended labels and milestone directly on the issue you triaged. 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 Not sure which label to pick? Start with just one: documentation , bug , or accessibility . You can always add more. Milestone is unclear? Write none and explain why - that is a valid triage decision. Project board is unknown? Write Needs Triage - that is the correct default. 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"). 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 covers labels, milestones, and contributor settings in an interactive, self-paced format. See Appendix Z for the full catalog. Learning Pattern Used in This Chapter Inspect an issue carefully before acting (read before you write). Classify work using a consistent vocabulary (labels, milestones). Explain your reasoning in writing (one-sentence justification). 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," + }, + { + "id": "admin/qa-bundle/docs/10-notifications-and-day-1-close.html", + "title": "Notifications", + "url": "admin/qa-bundle/docs/10-notifications-and-day-1-close.html", + "body": "Notifications Listen to Episode 10: Notifications and Mentions - a conversational audio overview of this chapter. Listen before reading to preview the concepts, or after to reinforce what you learned. Related appendices: Appendix T: Community and Social | Appendix U: Discussions and Gists | Appendix V: GitHub Mobile Authoritative sources: GitHub Docs: About notifications Managing Your GitHub Notification Inbox See also: Appendix V: GitHub Mobile for managing notifications on your phone. GitHub notifications are how GitHub tells you when something needs your attention. This guide teaches you to keep the inbox useful - not overwhelming - using only your keyboard and screen reader. Workshop Recommendation (Chapter 10) For this workshop, Chapter 10 is a guided practice chapter , not a graded automation chapter. Challenge count: 1 guided walkthrough Automation check: none - notification settings are account-level and cannot be validated by the Learning Room PR bot Evidence: structured completion comment on your assigned challenge issue Pattern: configure, filter, act Chapter 10 Challenge Set Configure notifications and practice inbox management - set your watch level, use filters to find relevant notifications, and perform one inbox action. Challenge 10.1 Step-by-Step: Notification Inbox Walkthrough Goal: Set up a useful notification workflow so you can keep up with reviews, mentions, and assignments without inbox overload. Where you are working: the GitHub.com notifications page and your Learning Room repository settings. Estimated time: 5-8 minutes. Open your Learning Room repository on GitHub.com. Find the Watch button near the top-right of the repository page (next to Star and Fork). Activate the Watch dropdown and select Participating and @mentions . This means you only get notified when someone @mentions you or you are directly participating in a thread. Open the notifications inbox by navigating to https://github.com/notifications (or activate the bell icon in the GitHub header). In the notification filters, activate the Review requested filter. This shows only notifications where someone has asked you to review their PR. Clear that filter and activate the Assigned filter. This shows notifications for issues and PRs assigned to you. Open one notification by activating its title link. Read it briefly, then navigate back to the inbox. Perform one inbox action on a non-critical notification thread: Press M to mute the thread (you will not receive future updates), or Press E to mark done (removes it from inbox but you can still get future updates). Screen reader tip: The notification list is a standard list of links. Each notification announces its title, repository, and reason (mention, review request, assignment). Use arrow keys to move between notifications and Enter to open one. You are done when: You have changed your watch level, used two different filters, and performed one inbox action (mute or done). Completing Chapter 10: Submit Your Evidence Open your assigned Chapter 10 challenge issue and post a completion comment: Chapter 10 completed: - Watch level set to: Participating and @mentions - Filters tested: Review requested, Assigned - Inbox action performed: [mute / mark done] on [thread description] Close your Chapter 10 challenge issue when done. Expected Outcomes Student can configure repository watch levels to reduce noise. Student can find review requests and assigned work quickly using filters. Student can reduce notification noise with mute or done actions. If You Get Stuck Can't find the Watch button? It is near the top-right of the repository page, in the same row as Star and Fork. Notification inbox is empty? You may not have any notifications yet - that is fine. Switch to the Done tab and practice the mute/done action flow on an older notification. 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. Filters not showing results? Clear all filters first (click the X next to each active filter), then apply one filter at a time. Ask facilitator to model one inbox action live, then repeat the steps yourself. Finished but not sure you did it right? Compare your work against the Challenge 9 reference solution . 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 Configure settings proactively (watch level) before work generates noise. Use filters to find signal in noise (review requests, assignments). Take decisive action on each notification (mute, done, or respond). 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 y" + }, + { + "id": "admin/qa-bundle/docs/11-vscode-interface.html", + "title": "VS Code: Interface and Setup", + "url": "admin/qa-bundle/docs/11-vscode-interface.html", + "body": "VS Code: Interface and Setup Listen to Episode 11: VS Code Setup and Accessibility - a conversational audio overview covering both this chapter and Chapter 12 . Related appendices: Appendix G: VS Code Reference | Appendix B: Screen Reader Cheat Sheet Authoritative sources: VS Code Docs: User Interface | VS Code Docs: Accessibility Your Accessible Development Environment - The Foundation Day 2, Block 1 Material This chapter covers the VS Code interface: launching VS Code, signing in to GitHub, verifying Copilot is active, configuring screen reader mode, and navigating the Activity Bar, Status Bar, menus, settings, and keyboard shortcuts. For accessibility deep-dive topics (keyboard navigation, Problems panel, Terminal, Copilot Chat, Accessible Help/View/Diff, Accessibility Signals, and VS Code Speech), see Chapter 12: VS Code Accessibility Deep Dive . Prerequisites: Complete Day 1 walkthrough of GitHub's browser interface before working through VS Code material. Workshop Recommendation (Chapter 11) For this workshop, Chapter 11 is a guided setup chapter with a lightweight completion practice. Challenge count: 1 guided walkthrough Automation check: none - setup state is local/account-level and cannot be validated by the Learning Room PR bot Evidence: structured completion comment on your assigned challenge issue Pattern: open, configure, navigate, verify Chapter 11 Practice Set VS Code accessibility baseline - open VS Code (github.dev or desktop), enable screen reader mode, sign in to GitHub, verify Copilot status, and navigate core surfaces. Practice 11.1 Step-by-Step: VS Code Accessibility Baseline Goal: Confirm you can access VS Code (github.dev or desktop), enable screen reader support, sign in to GitHub, check Copilot status, and perform core navigation. Where you are working: github.dev (VS Code in the browser) or desktop VS Code if you installed it in Block 0. Estimated time: 10-15 minutes. Open your Learning Room repository on GitHub.com. Press . (the period key) on your keyboard. This launches github.dev - a full VS Code editor running in your browser. Wait a few seconds for it to load. Enable screen reader mode: Windows (NVDA/JAWS): Press Shift+Alt+F1 . You should hear an announcement confirming screen reader mode is on. Mac (VoiceOver): Screen reader mode is usually already optimized. If navigation feels wrong, open Command Palette ( Cmd+Shift+P ) and run Toggle Screen Reader Accessibility Mode . Open the Explorer panel with Ctrl+Shift+E (Mac: Cmd+Shift+E ). Your screen reader should announce the file tree. Navigate to and open README.md from the file tree. Use arrow keys to move through files and Enter to open. Open the outline/symbols view with Ctrl+Shift+O (Mac: Cmd+Shift+O ). This shows all headings and sections in the current file - a key navigation tool for screen reader users. Open the Command Palette with Ctrl+Shift+P (Mac: Cmd+Shift+P ). Type any command name (for example, Toggle Word Wrap ) and press Enter to run it. Press Escape to close without running. Check the Accounts button in the Activity Bar (bottom-left of the sidebar). If you are signed in, your screen reader announces your GitHub username. If not, activate it and sign in with GitHub. Check the Status Bar at the bottom of the window. Tab or arrow through it to find GitHub Copilot status. If Copilot is active, you hear an indicator showing it is ready. You are done when: You have successfully opened github.dev, enabled screen reader mode, signed in to GitHub, confirmed Copilot status, opened a file, viewed its outline, and run a command from the Command Palette. Completing Chapter 11: Submit Your Evidence Return to GitHub.com, open the assigned setup or Day 2 readiness issue, and post a completion comment: Chapter 11 completed: - Opened github.dev: yes / no - Screen reader mode enabled: yes / no - Signed in to GitHub: yes / no - Copilot status checked: yes / no - Opened file in Explorer: yes / no - Opened outline/symbols: yes / no - Opened Command Palette: yes / no If any step was "no," add a note explaining where you got stuck so the facilitator can help. Close the assigned setup or readiness issue when done. Expected Outcomes Student can launch and navigate github.dev or desktop VS Code. Student can enable screen reader mode and hear navigation announcements. Student has signed in to GitHub and can see their account status. Student has verified GitHub Copilot is active (or knows it requires desktop VS Code). Student can open core navigation surfaces (Explorer, Outline, Command Palette). Student is ready for VS Code-based contribution chapters (6-16). If You Get Stuck Nothing happens when you press . ? Make sure you are on the repository's main page (not inside an issue or PR). The . shortcut only works on repository code pages. Screen reader mode toggle did not announce anything? Open Command Palette ( Ctrl+Shift+P ) and type Screen Reader to find the toggle manually. Explorer panel is empty? VS Code may stil" + }, + { + "id": "admin/qa-bundle/docs/12-vscode-accessibility.html", + "title": "VS Code: Accessibility Deep Dive", + "url": "admin/qa-bundle/docs/12-vscode-accessibility.html", + "body": "VS Code: Accessibility Deep Dive Listen to Episode 11: VS Code Setup and Accessibility - a conversational audio overview covering both Chapter 11 and this chapter. Related appendices: Appendix G: VS Code Reference | Appendix B: Screen Reader Cheat Sheet Authoritative sources: VS Code Docs: Accessibility | GitHub Accessibility: GitHub Copilot in VS Code 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 . Table of Contents Essential Keyboard Navigation and Find/Filter The Problems Panel The Terminal Copilot Chat Window Accessible Help, Accessible View, and Accessible Diff Accessibility Signals VS Code Speech - Voice Input and Output Markdown Authoring in VS Code 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 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: Focus the Explorer ( Ctrl+Shift+E ) Start typing a filename - a filter input appears at the bottom of the tree The tree instantly narrows to matching files 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 " + }, + { + "id": "admin/qa-bundle/docs/13-how-git-works.html", + "title": "How Git Works: The Mental Model", + "url": "admin/qa-bundle/docs/13-how-git-works.html", + "body": "How Git Works: The Mental Model Related appendices: Appendix E: Advanced Git | Appendix D: Git Authentication | Appendix F: Git Security Authoritative sources: Git SCM: Git Basics | Git SCM: Branching in a Nutshell | GitHub Docs: 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 will make more sense after reading this. Table of Contents Why a Mental Model Matters The Three Areas: Working Directory, Staging Area, Repository What Is a Commit? What Is a Branch? Local vs Remote Push, Pull, and Fetch Why Merge Conflicts Happen The Git Timeline Putting It All Together 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 ). 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 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: Edit files in the working directory Stage the changes you want to keep (add to the staging area) Commit the staged changes (save to the repository) In Git commands, this looks like: 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 a" + }, + { + "id": "admin/qa-bundle/docs/14-git-in-practice.html", + "title": "Git & Source Control in VS Code", + "url": "admin/qa-bundle/docs/14-git-in-practice.html", + "body": "Git & Source Control in VS Code Listen to Episode 12: Git and Source Control in VS Code - 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 D: Git Authentication | Appendix H: GitHub Desktop Authoritative sources: VS Code Docs: Source Control | GitHub Docs: 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 , Working with Pull Requests , Merge Conflicts 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 Clone your Learning Room repository - clone your private Learning Room repo to your local machine using VS Code. Create a branch and make one commit - check out (or create) your learn/<username> branch, edit a file, stage, write a clear commit message, and commit locally. 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/<workshop-org>/learning-room-<your-username>.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. Open VS Code. If no folder is open, you should see the Welcome tab. Open the Command Palette: Ctrl+Shift+P (Mac: Cmd+Shift+P ). Type git clone and select Git: Clone . VS Code asks for a repository URL. Paste your Learning Room repo URL (it looks like https://github.com/<workshop-org>/learning-room-<your-username>.git ). You can copy this from the green Code button on your repo's GitHub page. Press Enter . 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 . VS Code clones the repository. When it finishes, a notification appears asking "Would you like to open the cloned repository?" Activate Open . 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/<username> branch). Run git branch -a in the terminal ( Ctrl+` ) to see all branches -- local and remote: git branch -a You will see output like: * 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" + }, + { + "id": "admin/qa-bundle/docs/15-code-review.html", + "title": "Code Review: PRs, Diffs, and Constructive Feedback", + "url": "admin/qa-bundle/docs/15-code-review.html", + "body": "Code Review: PRs, Diffs, and Constructive Feedback Related appendices: Appendix G: VS Code Reference | Appendix C: Markdown Reference Authoritative sources: GitHub Docs: Reviewing changes in pull requests | GitHub Accessibility Guide: Pull Request Reviews Day 2, Block 2 Material This chapter unifies PR management, accessible code review, and the reviewer's craft into one chapter. Part 1 covers the GitHub Pull Requests extension in VS Code. Part 2 covers accessible code review with diffs and inline comments. Part 3 adds the reviewer's judgment framework. Part 1: The GitHub Pull Requests Extension See also: Appendix G: VS Code Reference for the complete list of GitHub Pull Requests extension keyboard shortcuts. Listen to Episode 13: The GitHub Pull Requests Extension - a conversational audio overview of this chapter. Listen before reading to preview the concepts, or after to reinforce what you learned. Managing Pull Requests from VS Code Day 2, Block 2 Material This guide covers the GitHub Pull Requests and Issues extension: viewing open PRs, checking out PR branches for local testing, reviewing PRs with screen reader-accessible tools, creating PRs directly from VS Code, using PR templates, and syncing PR status with GitHub. Prerequisites: Working with Pull Requests , Git & Source Control in VS Code Mac keyboard shortcuts: Throughout this chapter, all Ctrl+ shortcuts use Cmd+ on Mac, and Alt+ shortcuts use Option+ on Mac. For example: Ctrl+Shift+P → Cmd+Shift+P , Ctrl+Shift+G → Cmd+Shift+G , Alt+F2 → Option+F2 . Context menus ( Shift+F10 on Windows) use Ctrl+Return on Mac. Workshop Recommendation (Chapter 15, Part 1) Chapter 15, Part 1 introduces the GitHub Pull Requests extension for managing PRs directly from VS Code. Challenge count: 2 guided challenges Automation check: none (extension installation and review state are account-local) Evidence: issue comment with confirmation of actions completed Pattern: install, check out, review, comment Chapter 15, Part 1 Practice Set Install the GitHub Pull Requests extension - add the extension to VS Code and sign in with your GitHub account. Check out a PR and post a review comment - download a PR branch locally, read the diff, and post one constructive review comment. Practice 15.1 Step-by-Step: Install the Extension Goal: Install the GitHub Pull Requests and Issues extension and authenticate with your GitHub account. Where you are working: VS Code desktop with your Learning Room repository open. Estimated time: 3-5 minutes. Open the Extensions sidebar: Ctrl+Shift+X (Mac: Cmd+Shift+X ). Your screen reader announces "Extensions: Marketplace." The search box has focus. Type GitHub Pull Requests in the search box and press Enter . Navigate down the results list. Select GitHub Pull Requests (publisher: GitHub). Activate the Install button. VS Code installs the extension and may show a notification. After installation, VS Code prompts you to sign in. Activate Sign in to GitHub . A browser window opens for GitHub OAuth. Approve the authorization and return to VS Code. Verify: open the Explorer sidebar ( Ctrl+Shift+E ). You should now see a GitHub section in the sidebar showing Pull Requests and Issues. Screen reader tip: After step 5, if the install notification disappears before you can read it, open Command Palette ( Ctrl+Shift+P ) and run Notifications: Focus Notification Toast . You are done when: The GitHub section appears in your Explorer sidebar and shows pull requests from your Learning Room repository. Practice 15.2 Step-by-Step: Check Out a PR and Post a Comment Goal: Check out someone else's PR branch locally, read the diff in VS Code, and post one constructive review comment. Where you are working: VS Code with the GitHub Pull Requests extension installed. Estimated time: 10-15 minutes. Open the Command Palette: Ctrl+Shift+P (Mac: Cmd+Shift+P ). Type GitHub Pull Requests: Focus on Pull Requests View and select it. The Pull Requests panel opens. Navigate the list of open PRs. Find one that is not yours (a classmate's PR from Chapter 6, 7, or 14). With the PR focused, press Enter or activate Checkout from the context menu ( Shift+F10 on Windows). VS Code switches to that PR's branch. Open the Command Palette again and run GitHub Pull Requests: Open Changed Files . This shows the list of files the PR changed. Open one changed file. VS Code opens the Diff Editor showing old content on the left and new content on the right. Navigate the diff with the Accessible Diff Viewer : press F7 to move to the next change, Shift+F7 for the previous change. Your screen reader announces each change (added lines, removed lines). Find one specific thing to comment on: a typo, an unclear sentence, a missing step, or something the author did well. To add an inline comment: position your cursor on the line you want to comment on, then open Command Palette and run GitHub Pull Requests: Add Comment . Type your constructive comment and activate Add Com" + }, + { + "id": "admin/qa-bundle/docs/16-github-copilot.html", + "title": "GitHub Copilot", + "url": "admin/qa-bundle/docs/16-github-copilot.html", + "body": "GitHub Copilot Listen to Episode 14: GitHub Copilot - a conversational audio overview of this chapter. Listen before reading to preview the concepts, or after to reinforce what you learned. Related appendices: Appendix K: Copilot Reference | Appendix G: VS Code Reference Authoritative sources: GitHub Docs: About GitHub Copilot | GitHub Accessibility: Copilot in VS Code | VS Code Docs: GitHub Copilot AI-Powered Code Assistance in VS Code Day 2, Block 2-3 Material This guide covers GitHub Copilot: inline code suggestions, Copilot Chat (conversational assistance), custom instructions vs custom agents, effective prompting for non-code contributions, and using Accessible View to read AI-generated responses. Official GitHub Accessibility Guides: GitHub publishes two developer guides and an NVDA-focused screen reader guide for Copilot: Using GitHub Copilot in Visual Studio Code with a Screen Reader - NVDA-specific setup, audio cues, inline suggestions, inline chat, chat view, and built-in actions Optimizing GitHub Copilot for Accessibility with Custom Instructions - writing effective custom instructions at org, repo, and personal levels Getting Started with GitHub Copilot Custom Agents for Accessibility - creating and invoking custom agents in VS Code and on GitHub.com This chapter covers the same material with additional perspectives and workshop context. Use the official guides as companion references. Prerequisites: VS Code Setup & Accessibility Basics , Git & Source Control in VS Code Mac keyboard shortcuts: Throughout this chapter, all Ctrl+ shortcuts use Cmd+ on Mac, and Alt+ shortcuts use Option+ on Mac. Key equivalents: Ctrl+Shift+I → Cmd+Shift+I (Chat), Ctrl+I → Cmd+I (inline chat), Alt+F2 → Option+F2 (Accessible View), Ctrl+/ → Cmd+/ (insert suggestion). See the Keyboard Shortcuts Reference at the end of this chapter for the complete list. Workshop Recommendation (Chapter 16 / Challenge 13) Free to use: GitHub Copilot Free tier is included with all GitHub accounts at no cost. This workshop uses only the free tier. If you're on an organization with GitHub Enterprise, you may have Copilot Pro included; either way, you're covered. Billing guidance for this workshop: GitHub Copilot plans and billing are changing. We will provide specific guidance at the workshop, as this is a continuing moving target and is subject to change as we approach the event. If you are unsure whether your account has Copilot access, check github.com/settings/copilot or ask a facilitator before the workshop begins. Chapter 16 introduces GitHub Copilot for AI-assisted documentation and writing. It supports Challenge 13: AI as Your Copilot. Challenge count: 3 guided challenges Automation check: none (tool configuration is account-local and account-specific) Evidence: issue comment with checklist of completed actions Pattern: install, prompt, apply, reflect Challenge 13 Set Sign in to GitHub Copilot - authenticate with GitHub (VS Code 1.116+ has Copilot built in; no extension install needed). Ask Copilot to explain a codebase - clone the sci-fi themes repo and use Copilot Chat to understand it. Ask Copilot to create something new - prompt Copilot to generate a custom theme and apply it. Challenge 13.1 Step-by-Step: Sign In to Copilot Goal: Sign in to GitHub Copilot and verify it responds to prompts. Where you are working: VS Code desktop with your Learning Room repository open. Estimated time: 3-5 minutes. VS Code 1.116 and later: GitHub Copilot is built into VS Code and no extension installation is needed. Skip steps 1-4 below if you are on VS Code 1.116 or later -- Copilot is already present. If VS Code prompts you to sign in on first launch, follow the browser OAuth flow and then proceed to step 5. (Older VS Code only) Open the Extensions sidebar: Ctrl+Shift+X (Mac: Cmd+Shift+X ). (Older VS Code only) Type GitHub Copilot in the search box and press Enter . (Older VS Code only) Find GitHub Copilot (publisher: GitHub) in the results. Activate Install . (Older VS Code only) VS Code may also install GitHub Copilot Chat automatically. If not, search for it separately and install it. Sign in when prompted: activate Sign in to GitHub and complete the OAuth flow in your browser. Verify Copilot is active: open Copilot Chat with Ctrl+Shift+I (Mac: Cmd+Shift+I ). Type Hello, are you working? and press Enter . Copilot should respond. Screen reader tip: The Copilot Chat panel opens as a sidebar. Your screen reader announces responses as they stream in. Press Alt+F2 (Accessible View) to read the full response in a plain text buffer if streaming is hard to follow. You are done when: Copilot Chat responds to a test prompt. Challenge 13.2 Step-by-Step: Explain a Codebase Goal: Use Copilot Chat to understand an unfamiliar repository by asking targeted questions. Where you are working: VS Code with the sci-fi themes repository cloned. Estimated time: 10-15 minutes. Open the Command Palette: Ctrl+Shift+P (Mac: Cmd+Shift+P ). Run Git: Clo" + }, + { + "id": "admin/qa-bundle/docs/17-issue-templates.html", + "title": "Issue Templates", + "url": "admin/qa-bundle/docs/17-issue-templates.html", + "body": "Issue Templates Listen to Episode 16: Issue Templates - 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 C: Markdown Reference | Appendix N: Advanced Search Authoritative sources: GitHub Docs: About issue and PR templates | GitHub Docs: Configuring issue templates 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 , 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 - 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 - Optional but helpful for generating template variations Chapter 10: Notifications - 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) , 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 Analyze the registration template - understand how the template you already filled out works. Remix the registration template - adapt it for a new use case (bug report, event, research). Create a Markdown template (optional) - build a Markdown-based template from scratch. 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 repository. Estimated time: 10-15 minutes. The Template: .github/ISSUE_TEMPLATE/workshop-registration.yml - This is the form you filled out to register. It is a real, production template. Open the template file on GitHub.com (use the link above). 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 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) 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 Search the file for "accessible" - notice the description mentions that all fields work with screen readers. This is professional template thinking. 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 Remix sample: learning-room/docs/sample" + }, + { + "id": "admin/qa-bundle/docs/18-fork-and-contribute.html", + "title": "Fork and Contribute: The Open Source Workflow", + "url": "admin/qa-bundle/docs/18-fork-and-contribute.html", + "body": "Fork and Contribute: The Open Source Workflow Related appendices: Appendix E: Advanced Git | Appendix O: Branch Protection | Appendix D: Git Authentication Authoritative sources: GitHub Docs: Fork a repo | GitHub Docs: Syncing a fork | Open Source Guides: How to Contribute Day 2, Block 3 Material This chapter teaches the complete fork-based contribution workflow from start to finish. You will fork a real repository, create a feature branch, make changes, push to your fork, and open a pull request against the upstream repository. This is the workflow used by millions of open source contributors every day, and it is the foundation for the capstone project in Chapter 20 . Table of Contents What Is a Fork? Fork vs Clone vs Branch Step 1: Fork the Repository Step 2: Clone Your Fork Locally Step 3: Add the Upstream Remote Step 4: Create a Feature Branch Step 5: Make Your Changes Step 6: Push to Your Fork Step 7: Open a Pull Request Step 8: Respond to Review Feedback Keeping Your Fork in Sync The Fork Workflow Checklist 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 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: You fork the project (creates your copy) You make changes on your copy 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: Fork the upstream repository to create your copy on GitHub Clone your fork to your computer Create a branch on your local clone for your specific change Push the branch to your fork and open a PR to the upstream Upstream repo (GitHub) Your fork (GitHub) Your computer (local) +-------------------+ +-------------------+ +-------------------+ | Community-Access/ | fork | your-username/ | clone| | | accessibility- | ----> | accessibility- | ---> | accessibility- | | agents | | agents | | agents | +-------------------+ +-------------------+ +-------------------+ ^ ^ | | | | +--- PR (fork to upstream) +--- git push | edit, stage, commit Screen reader note: The text diagram above shows three boxes arranged left to right. The upstream repo on GitHub is on the left. Your fork on GitHub is in the middle. Your local computer is on the right. A fork arrow goes from left to middle. A clone arrow goes from middle to right. Editing happens on the right. Git push goes from right to middle. A PR goes from middle to left. Learning Cards: Fork vs Clone vs Branch Screen reader users Run git remote -v in the terminal to hear your configured remotes -- origin is your fork, upstream is the original repository The Status Bar in VS Code shows the current branch name -- press F6 to navigate there and confirm you are on a feature branch, not main Use Ctrl+Shift+P then "Git: Checkout to" to switch between branches; your screen reader announces each branch name in the picker Low vision users Your fork URL includes your username (e.g., github.com/your-name/repo ) making it visually distinct from the upstream URL In VS Code, the branch name in the bottom-left Status Bar confirms which branch you are working on -- zoom with Ctrl+= if it is too small The Source Control panel heading shows the repository name to help you verify you are working in the correct clone Sighted users On GitHub.com, forked repos show a "forked from" label under the reposito" + }, + { + "id": "admin/qa-bundle/docs/19-accessibility-agents.html", + "title": "Accessibility Agents", + "url": "admin/qa-bundle/docs/19-accessibility-agents.html", + "body": "Accessibility Agents Listen to Episode 17: Accessibility Agents - a conversational audio overview of this chapter. Listen before reading to preview the concepts, or after to reinforce what you learned. Related appendices: Appendix L: Agents Reference | Appendix K: Copilot Reference Authoritative sources: GitHub Docs: Using extensions with Copilot | VS Code Docs: Chat participants 55 AI Agents Across 3 Teams and 5 Platforms Day 2, Block 3 Material Before you read this guide: Accessibility Agents is a growing open source ecosystem: 55 AI-powered agents organized into three teams (Accessibility, GitHub Workflow, and Developer Tools), running on five platforms (GitHub Copilot, Claude Code, Gemini CLI, Claude Desktop, and Codex CLI). This chapter introduces the full landscape. Explore the agents that match your interests and workflows - there is no fixed subset you are required to use. The agents are only useful if you have already done the work manually. An agent that summarizes issues is useless to someone who has never read an issue. An agent that reviews a diff is useless to someone who has never read a diff. The agent does not teach you the skill - it multiplies a skill you already have. Day 1 built those skills. This chapter shows how to amplify them with automation - and how you can contribute new agents, improve existing ones, and shape the project's future. Prerequisites Checklist Before starting this chapter, verify you have completed Core Prerequisites (Required for All Agents) Chapter 0: Pre-Workshop Setup - Git, VS Code, and GitHub account Chapter 16: GitHub Copilot - GitHub Copilot Chat installed and working GitHub Copilot access (Copilot Free tier is enough for this workshop) .github/agents/ folder exists in your repository (or will create custom agents) Agent Prerequisites (The "Skill First" Principle) Every agent automates a skill you should already know by hand. Before using any agent, verify you have done the corresponding manual work. This table maps common agent categories to the skills they require: Agent Category You Must Have Done First Reference GitHub Workflow agents ( @daily-briefing , @issue-tracker , @pr-review , @analytics ) Navigated repositories, filed issues, reviewed PRs, explored Insights Ch 2 , Ch 4 , Ch 6 Accessibility monitoring ( @insiders-a11y-tracker ) Filed an accessibility bug, applied WCAG labels, checked heading hierarchy Ch 4 , Ch 15 Template creation ( @template-builder ) Designed a template manually, tested field types Ch 15 Web accessibility auditing ( @web-accessibility-wizard , @contrast-master , @keyboard-navigator , etc.) Understand WCAG success criteria, tested pages with a screen reader Appendix C Document accessibility ( @word-accessibility , @pdf-accessibility , etc.) Reviewed a document for accessibility issues manually Appendix C This is not an exhaustive list - it illustrates the principle. Before running any agent, ask yourself: could I do this task manually right now? If the answer is no, learn the manual skill first. Estimated time for this chapter: 1.5 hours (including exercises) Workshop Recommendation (Chapter 19 / Challenge 15) Chapter 19 is the agent exploration and hands-on validation chapter - where students match agents to skills they already have and learn how to trust, evaluate, and improve AI-powered workflow automation. It supports Challenge 15: Meet the Agents. Challenge count: 3 guided + 1-2 optional contribution challenges Automation check: none (agent output requires human judgment before use) Evidence: issue comment showing agent output and your evaluation of it Pattern: explore, validate, read internals, optionally contribute Key principle: Skill First, Agent Second - every agent requires manual prerequisite skills Challenge 15 Set Agent Discovery Mapping - identify 3-5 agents that match skills you already have from Day 1. Agent Skill Validation - run one agent and evaluate its output against your manual experience. Agent Instructions Deep Dive - read one agent's source file and assess what it can and cannot do. Improve an Existing Agent (optional hackathon) - find a gap in an agent's instructions and fix it via PR. Propose a New Agent (optional hackathon) - file an issue proposing an agent for an uncovered workflow. Challenge 15.1 Step-by-Step: Agent Discovery Mapping Goal: Map your Day 1 manual skills to specific agents in the ecosystem so you know which agents you are ready to use. Where you are working: GitHub.com - the accessibility-agents repository and your assigned Challenge 15 issue. Estimated time: 20 minutes. If 55 agents feels too broad, start with this beginner sequence: @daily-briefing (maps to repository and issue awareness from Chapters 2-4) @issue-tracker (maps to Chapter 4 issue workflow) @pr-review (maps to Chapter 6 and Chapter 14 review workflow) Fork the accessibility-agents repository on GitHub.com. Open the repository and navigate to Section 3 of the README (or this chapter's Section" + }, + { + "id": "admin/qa-bundle/docs/20-build-your-agent.html", + "title": "Build Your Agent: The Capstone Project", + "url": "admin/qa-bundle/docs/20-build-your-agent.html", + "body": "Build Your Agent: The Capstone Project Related appendices: Appendix L: Agents Reference | Appendix K: Copilot Reference | Appendix C: Markdown Reference Authoritative sources: VS Code Docs: Chat participants | GitHub Docs: About GitHub Copilot agents Day 2, Block 4 Material (Capstone) Everything you have learned comes together here. You will design, build, and contribute an accessibility agent to the Community-Access/accessibility-agents repository. This is a real contribution to a real project -- your agent will join the roster of 55+ agents serving 3 accessibility teams across 5 platforms. Table of Contents The Capstone Challenge Phase 1: Choose Your Agent's Mission Phase 2: Write the Agent File Phase 3: Define Responsibilities and Guardrails Phase 4: Test Your Agent Locally Phase 5: Open Your Pull Request Phase 6: Respond to Review Capstone Rubric Example Agents for Inspiration If You Get Stuck Challenge 16: Build Your Agent (Capstone). This is the culminating challenge of the workshop. You will fork, write, test, and contribute an accessibility agent. 1. The Capstone Challenge The capstone is Challenge 16 -- the final challenge of the workshop. You will: Choose a mission for a new accessibility agent (or improve an existing one) Write an agent file with valid YAML frontmatter Define clear responsibilities and guardrails Test the agent locally with GitHub Copilot Open a pull request from your fork to the upstream repository Respond to peer review feedback This is not a simulation. Your pull request goes to a real repository. If your agent meets the quality bar, it will be merged and available to real users. What you need before starting You have forked and cloned the accessibility-agents repository ( Chapter 18 ) You have a feature branch created: agents/your-username-agent-name You understand how to push to your fork and open a PR ( Chapter 18 ) You have GitHub Copilot or Copilot Free active ( Chapter 16 ) You have explored the existing agents in Chapter 19 Time estimate Most students complete the capstone in 60 to 90 minutes. The phases are designed so you can get a working agent in 30 minutes and spend the remaining time improving it. 2. Phase 1: Choose Your Agent's Mission See also: Chapter 19: Accessibility Agents introduces the agent ecosystem and shows existing agents for inspiration. What makes a good agent mission A good agent solves a specific, recurring problem. It does not try to do everything. Consider these questions: What task do you repeat? Think about workflow steps from Day 1 and Day 2 that felt repetitive. What would a specialist know? An agent works best when it has deep knowledge of a focused area. What gap exists? Look at the existing agents in Chapter 19 . Is there a workflow that no agent covers? Mission categories to consider Category Example missions Existing agents in this space Accessibility auditing Audit color contrast in CSS variables, check form labels, validate heading hierarchy contrast-master, forms-specialist, alt-text-headings Document accessibility Check PDF reading order, audit Excel sheet names, validate Word heading structure pdf-accessibility, excel-accessibility, word-accessibility GitHub workflow Summarize notifications, track stale issues, generate release notes daily-briefing, issue-tracker, analytics Developer tools Validate agent files, lint markdown for accessibility, check keyboard navigation testing-coach, link-checker, markdown-a11y-assistant Education Explain a WCAG criterion, generate quiz questions, summarize a chapter wcag-guide Write your mission statement Before writing any code, write a one-sentence mission statement: "My agent helps [who] by [doing what] when [in what situation]." Example: "My agent helps documentation authors by checking that all images in a markdown file have meaningful alt text when they open a file for review." Write this statement in your challenge issue comment so your buddy and facilitator can give early feedback. 3. Phase 2: Write the Agent File An agent file is a Markdown file with YAML frontmatter that defines the agent's identity, and a body that contains the agent's instructions. Agent files live in the .github/agents/ directory (for GitHub Copilot agents) or in team-specific directories in the accessibility-agents repository. File location and naming Create your agent file at: .github/agents/your-agent-name.md Use lowercase with hyphens. Example: .github/agents/alt-text-validator.md The agent file structure Every agent file has two parts: YAML frontmatter -- metadata between --- markers at the top of the file Instructions body -- Markdown content that tells the agent how to behave Minimal agent file template --- name: "Alt Text Validator" description: "Checks that all images in markdown files have meaningful, non-placeholder alt text." --- # Alt Text Validator You are an accessibility specialist focused on image alt text quality in markdown documentation. ## Re" + }, + { + "id": "admin/qa-bundle/docs/21-next-steps.html", + "title": "What Comes Next: Your Developer Journey", + "url": "admin/qa-bundle/docs/21-next-steps.html", + "body": "What Comes Next: Your Developer Journey Related appendices: Appendix X: Resources | Appendix Z: GitHub Skills | Appendix Y: Workshop Materials Authoritative sources: GitHub Skills | GitHub Docs: Getting started Day 2, Closing Material Congratulations -- you have completed the Git Going with GitHub workshop. This chapter is your graduation guide: what you accomplished, where to go next, how to build your portfolio, and how to stay connected with the community. Table of Contents What You Built in Two Days Your New Skills Inventory Building Your Developer Portfolio Continued Learning Roadmap GitHub Skills Courses to Try Next Staying Connected Contributing Back to This Workshop Final Words 1. What You Built in Two Days Take a moment to appreciate what you accomplished. This is not a list of what you were taught -- it is a list of what you did. Day 1: You Can Navigate This Created and configured a GitHub account with accessibility settings Navigated repositories, files, and folders using your screen reader, keyboard, or preferred tools Filed issues with descriptive titles, labels, and context Created branches, edited files, and opened pull requests Responded to bot feedback and passed automated checks Resolved a merge conflict Reviewed someone else's code and gave constructive feedback Explored labels, milestones, and project boards Managed notifications Day 2: You Can Build This Installed and configured VS Code with accessibility settings Cloned a repository and worked with Git locally Understood the mental model: working directory, staging area, repository Created branches, staged changes, committed, and pushed from the command line Explored GitHub Copilot: code suggestions, chat, and code review Created an issue template Forked a repository and contributed using the open source workflow Explored the accessibility agents ecosystem Built and contributed your own accessibility agent (capstone) The evidence Your GitHub profile now contains real activity: issues filed, pull requests merged, code reviewed, and an agent contributed to an open source project. This is not a certificate. It is a commit history. 2. Your New Skills Inventory The following table maps what you learned to where it applies beyond this workshop. Every skill transfers directly to real-world development. Skill Where you learned it Where it applies Repository navigation Chapters 2-3 Every GitHub project, every job that uses GitHub Issue tracking Chapter 5 Bug reports, feature requests, project management Pull request workflow Chapters 6, 15 Code contribution at any company or open source project Merge conflict resolution Chapter 7 Any team project with multiple contributors Git fundamentals Chapters 13-14 Every software project that uses version control VS Code proficiency Chapters 11-12 Daily development work in any language Code review Chapter 15 Peer review, quality assurance, team collaboration Fork workflow Chapter 18 Open source contribution, cross-team collaboration AI-assisted development Chapters 16, 19-20 GitHub Copilot, AI agents, and future AI tools Accessibility awareness Entire workshop Building inclusive software, WCAG compliance Skills you may not have noticed Reading documentation: You navigated technical guides, followed step-by-step instructions, and troubleshot problems using written references. This is the most important developer skill. Asking for help effectively: You posted on issues with context, error messages, and what you tried. This is how experienced developers communicate. Learning tools by doing: You did not read a manual cover to cover. You tried things, hit problems, and figured them out. This is how real tool learning works. 3. Building Your Developer Portfolio See also: Appendix X: Resources has links to every tool and resource mentioned in this course. Your GitHub profile is your portfolio. Here is how to make what you built visible. Pin your best repositories Go to github.com/settings/profile . Scroll to "Pinned repositories." Pin the repositories that show your best work. Consider: Your fork of the accessibility-agents repository (shows open source contribution) Any personal projects you create after the workshop Write a profile README Your profile README is the first thing people see when they visit your GitHub profile. Create a repository with the same name as your username (e.g., your-username/your-username ) and add a README.md : # Hi, I am [Your Name] I am a developer focused on [your interests]. ## Recent work - Contributed an accessibility agent to [ Community-Access/accessibility-agents ]( https://github.com/Community-Access/accessibility-agents ) - Completed the Git Going with GitHub workshop ## What I am learning - [List technologies or topics you are exploring] Keep your contribution graph active The green squares on your GitHub profile show when you made contributions. Even small actions count: filing issues, opening PRs, making commits, and reviewing code. Consistency matters more" + }, + { + "id": "admin/qa-bundle/docs/appendix-a-glossary.html", + "title": "Appendix A: GitHub Concepts & Glossary", + "url": "admin/qa-bundle/docs/appendix-a-glossary.html", + "body": "Appendix A: GitHub Concepts & Glossary Listen to Episode 18: Glossary of Terms - a conversational audio overview of this chapter. Listen before reading to preview the concepts, or after to reinforce what you learned. Reference companion to: Chapter 02: Understanding GitHub | Also relevant: all chapters Authoritative source: GitHub Docs: Glossary Every Term You Need for Open Source Contribution This glossary is your reference for the entire two-day workshop. When you hear a term you don't recognize - check here first. Terms are grouped by category and also sorted alphabetically at the end. Learning Cards: Navigating the Glossary Screen reader users Press H to jump between term headings (h3 level) within each category section Use the Elements List (NVDA+F7 or Insert+F6) to see all terms at once and type a few letters to filter Jump to "Alphabetical Quick Reference" at the bottom for a flat A-Z lookup table Low vision users Each term is a bold h3 heading -- increase zoom and scan headings to browse terms quickly The alphabetical table at the bottom works well at high zoom since each row is self-contained Use Ctrl+F in your browser to search for any term by name Sighted users Terms are grouped by category (Parts 1-6) -- scan the bold headings to find the right group Scroll to the bottom for the alphabetical quick reference table if you know the term name Use Ctrl+F to jump directly to any term on the page Part 1: The Building Blocks Repository (Repo) A repository is the container for an entire project. It holds all the project's files, folders, documentation, and the complete history of every change ever made. Think of it as a project folder that has a time machine built in - you can see every version of every file going back to the beginning. A repository lives on GitHub at an address like: https://github.com/owner/repo-name Related terms: remote repository (the one on GitHub), local repository (a copy on your computer), upstream (the original repo), fork (your personal copy) Organization (Org) An organization is a group account on GitHub that multiple people can belong to. Open source projects typically live inside an organization rather than under a personal account. For example: https://github.com/microsoft/vscode - here microsoft is the organization and vscode is the repository. Fork A fork is a personal copy of someone else's repository, living in your own GitHub account. When you fork a repo, you get all its files and history. Changes you make to your fork do not automatically affect the original. To propose your changes to the original project, you submit a pull request. Why fork? You do not have write access to most open source repos. Forking lets you work freely and then propose changes. Remote A remote is a connection to a repository hosted elsewhere (usually on GitHub). Your local Git repository can have multiple remotes. The most common remotes are: origin - your fork on GitHub upstream - the original repository you forked from When you run git push origin main , you're pushing your local main branch to the remote named origin . To see your remotes git remote -v To add a remote git remote add upstream https://github.com/original-owner/repo.git Origin origin is the default name Git gives to the remote repository you cloned from. When you clone your fork, origin points to your fork on GitHub. Commands like git push and git pull default to using origin unless you specify otherwise. .gitignore .gitignore is a special file in the root of your repository that tells Git which files or folders to ignore - meaning Git will not track or commit them. Why use .gitignore? Prevent committing temporary files ( .DS_Store , Thumbs.db ) Ignore build outputs ( dist/ , build/ , node_modules/ ) Keep secrets out of Git ( .env files, API keys, credentials) Avoid committing IDE-specific files ( .vscode/ , .idea/ ) Example .gitignore # Dependencies node_modules/ vendor/ # Environment variables .env .env.local # Build outputs dist/ build/ *.log # OS files .DS_Store Thumbs.db # IDE .vscode/ .idea/ Important: .gitignore only ignores untracked files. If you already committed a file, you must remove it from Git's tracking first: git rm --cached filename Then add it to .gitignore and commit the change. Clone Cloning copies a repository from GitHub to your local computer so you can work with it in VS Code or your preferred editor. When you clone, you get all the files and the complete history. git clone https://github.com/your-username/repo-name.git Fork vs Clone: Fork = your copy on GitHub. Clone = a copy on your computer. You usually clone your fork. Branch A branch is a separate line of development inside a repository. The main branch (often called main or master ) holds the stable, released version of the project. When you want to add a feature or fix a bug, you create a new branch so your work doesn't affect main until it's ready. Think of branches like parallel timelines - each bran" + }, + { + "id": "admin/qa-bundle/docs/appendix-b-screen-reader-cheatsheet.html", + "title": "Appendix B: Screen Reader Cheat Sheet", + "url": "admin/qa-bundle/docs/appendix-b-screen-reader-cheatsheet.html", + "body": "Appendix B: Screen Reader Cheat Sheet Listen to Episode 19: Screen Reader Cheat Sheet - a conversational audio overview of this chapter. Listen before reading to preview the concepts, or after to reinforce what you learned. Reference companion to: Chapter 02: Understanding GitHub | Also relevant: Chapter 03 , Chapter 11 Authoritative source: GitHub Docs: Keyboard shortcuts GitHub Navigation with NVDA, JAWS, and VoiceOver How to use this sheet: Keep it open in a second window or print it. Commands are organized by task so you can find what you need quickly while you work. All commands are keyboard-only - no mouse required. Learning Cards: Using This Cheat Sheet Screen reader users Use heading navigation (H key) to jump between task categories -- each section is an h2 heading Open the Elements List (NVDA+F7 or Insert+F6) and switch to the Headings tab to see all sections at once Tables list commands in the left column and actions in the right -- use Ctrl+Alt+Arrow keys to navigate Low vision users Keep this open in a second browser tab or print it for side-by-side reference while working Command tables are compact -- increase zoom to 150-200% and the two-column layout stays readable Key names are in backtick code formatting which gives them a distinct visual border Sighted users Sections are organized by task (navigation, typing, dropdowns, troubleshooting) -- scan the h2 headings The "Per-Screen-Reader Command Reference" section groups everything by NVDA, JAWS, and VoiceOver Bookmark this page -- it is the single fastest reference when you forget a key combination Screen Reader Mode Basics Before navigating GitHub, understand the two fundamental modes that all screen readers use on the web: Browse Mode (also called Virtual Cursor / Reading Mode) This is your primary mode for reading and navigating pages. The screen reader intercepts keystrokes and uses them as navigation commands - for example, pressing H jumps to the next heading rather than typing the letter H. Screen Reader How to know you're in Browse Mode NVDA Lower-pitched sound when switching; NVDA says "browse mode" JAWS JAWS says "virtual cursor on" VoiceOver No mode switching needed - VoiceOver uses the VO modifier keys Focus Mode (also called Forms or Application Mode) This mode is for typing and interacting with form fields, text areas, buttons, and interactive widgets. Your keystrokes go directly to the web page instead of being captured by the screen reader. Screen Reader Toggle Focus/Browse Mode When to use NVDA NVDA+Space (Insert+Space or CapsLock+Space) Type in comment boxes, issue titles, PR descriptions JAWS JAWS+Z (Insert+Z) or automatic Same VoiceOver VO+Shift+Down to interact with an element Same Rule of thumb: Browse mode to navigate, Focus mode to type. Quick Navigation Keys (Browse Mode) These single-key shortcuts work in Browse Mode (NVDA and JAWS). VoiceOver users with Quick Nav enabled use the same keys. Heading Navigation - Your Most-Used Tool GitHub structures pages with headings. Jumping between headings is the fastest way to navigate. Key Action VoiceOver H Next heading (any level) H (Quick Nav on) Shift+H Previous heading Shift+H 1 Next h1 (page title) 1 2 Next h2 (section heading) 2 3 Next h3 (issue/PR titles are h3) 3 4 Next h4 (commit titles in PRs) 4 Landmark Navigation - Jump Between Page Regions Landmarks are named regions of a page (navigation, main content, sidebar, etc.). GitHub uses landmarks heavily. Key Action VoiceOver D Next landmark / region VO+U → Landmarks rotor Shift+D Previous landmark Same, navigate backwards GitHub landmarks you will encounter Landmark Label What It Contains Navigation Menu Your avatar menu and global nav Repository navigation Code, Issues, PRs, Actions tabs Main The primary page content Repository files navigation README display Pull requests list The list of PRs Search Results List Issues or PR list results Add a comment Comment submission form Pagination Next/Previous page buttons Link, Button, and Form Navigation Key Action JAWS Equivalent VoiceOver K Next link Tab or U VO+U → Links rotor Shift+K Previous link Shift+U - B Next button B VO+U → Buttons rotor Shift+B Previous button Shift+B - F or E Next edit/form field F VO+U → Form Controls Tab Next interactive element (any type) Tab Tab Shift+Tab Previous interactive element Shift+Tab Shift+Tab Enter / Space Activate link or button Same VO+Space List and Table Navigation Key Action Notes L Next list Useful for spotting issue/PR lists I Next list item Navigate within a list T Next table Use this for the files table in a repo Ctrl+Alt+→ Move right in a table cell Navigate table columns Ctrl+Alt+← Move left in a table cell Ctrl+Alt+↓ Move down in a table (next row) Navigate file list rows Ctrl+Alt+↑ Move up in a table The Elements List - Your Navigation Superpower This is one of the most powerful tools for navigating complex pages. It opens a dialog listing all headings, links, buttons, form fields, or l" + }, + { + "id": "admin/qa-bundle/docs/appendix-c-markdown-reference.html", + "title": "Appendix C: Markdown and GitHub Flavored Markdown - Complete Guide", + "url": "admin/qa-bundle/docs/appendix-c-markdown-reference.html", + "body": "Appendix C: Markdown and GitHub Flavored Markdown - Complete Guide Listen to Episode 22: GitHub Flavored Markdown - a conversational audio overview of this chapter. Listen before reading to preview the concepts, or after to reinforce what you learned. Reference companion to: Chapter 06: Working with Pull Requests | Also relevant: Chapter 12 , Chapter 17 Authoritative source: GitHub Docs: Basic writing and formatting syntax From First Paragraph to Polished Repository - Everything You Need to Know Who this is for: Everyone. Whether you have never written a single line of Markdown or you already know the basics and want to master the GitHub-specific extensions, this guide takes you from zero to confident. We start with what Markdown is and why it matters, walk through every foundational element with examples, and then cover the GitHub Flavored Markdown (GFM) features you will encounter in real repositories - alert blocks, Mermaid diagrams, math, footnotes, and more. Why this matters for this workshop: Every issue you file, every pull request you open, every README you read or write, every comment you post on GitHub uses Markdown. It is the language of collaboration on GitHub. Mastering it means your contributions look polished, your bug reports are clear, and your documentation is accessible to everyone - including screen reader users. How to use this guide: Read it straight through if you are new to Markdown. If you already know the basics, use the navigation below to jump to the topic you need. Every section includes the raw Markdown you type, what it looks like when rendered, and screen reader behavior notes so you know exactly what assistive technology users will experience. Table of Contents Part 1 - Markdown Foundations What Is Markdown? Where You Will Use Markdown in This Workshop How to Practice as You Read Paragraphs and Line Breaks Headings Emphasis - Bold, Italic, and Bold Italic Strikethrough Lists - Ordered and Unordered Nested Lists and Mixed Lists Links Images Blockquotes Inline Code and Code Blocks Horizontal Rules Escaping Special Characters Tables Part 2 - GitHub Flavored Markdown (GFM) What Is GitHub Flavored Markdown? Alert and Callout Blocks Collapsible Sections with Details and Summary Task List Checkboxes Syntax Highlighting in Fenced Code Blocks Mermaid Diagrams Math Expressions with LaTeX Footnotes Linked Heading Anchors and Tables of Contents Autolinked References - Issues, PRs, Commits, and Users HTML in Markdown Part 3 - Putting It All Together Screen Reader Behavior Summary Accessible Markdown Authoring Checklist Common Mistakes and How to Fix Them Your First Real Markdown Document - Guided Exercise Quick-Reference Card Part 1 - Markdown Foundations Learning Cards: Using This Markdown Reference Screen reader users Use heading navigation (H key) to jump between numbered sections -- each topic is an h2 heading Every section shows raw Markdown first, then rendered output, then screen reader behavior notes The Table of Contents at the top has anchor links -- activate any link to jump directly to that section Low vision users Code blocks show the raw Markdown to type -- increase zoom and the monospace font stays readable Each section follows the same pattern: explanation, raw code, rendered result, and accessibility notes Use Ctrl+F to search for a specific Markdown element (e.g., search "table" or "heading") Sighted users Sections are numbered 1-32 -- use the Table of Contents to jump to any topic Raw Markdown is in grey code blocks; rendered output follows immediately after Part 1 covers standard Markdown, Part 2 covers GitHub-specific extensions, Part 3 ties it together 1. What Is Markdown? Markdown is a lightweight way to format plain text so it renders as rich, structured content - headings, bold text, links, lists, code blocks, tables, and more. You write in a plain text file using simple punctuation characters, and a Markdown processor converts those characters into formatted output. Here is the key idea: what you type is readable as plain text, and it is also readable as formatted content after rendering. You never lose meaning either way. A screen reader can read your raw Markdown file and understand it. A sighted user can read the rendered version on GitHub and understand it. Both experiences work. A brief history John Gruber created Markdown in 2004 with the goal of making a format that is "as easy to read and write as plain text." Since then, Markdown has become the default writing format for: GitHub (README files, issues, pull requests, comments, wikis, discussions) Stack Overflow and many developer forums Static site generators (Jekyll, Hugo, Gatsby) Note-taking apps (Obsidian, Notion, Bear) Documentation systems (MkDocs, Docusaurus, Read the Docs) Chat platforms (Slack, Discord, Microsoft Teams) Markdown versus HTML Markdown converts to HTML behind the scenes. When you write **bold** , GitHub converts it to <strong>bold</strong> ." + }, + { + "id": "admin/qa-bundle/docs/appendix-d-git-authentication.html", + "title": "Appendix D: Git Authentication", + "url": "admin/qa-bundle/docs/appendix-d-git-authentication.html", + "body": "Appendix D: Git Authentication Listen to Episode 21: Git Authentication - a conversational audio overview of this chapter. Listen before reading to preview the concepts, or after to reinforce what you learned. Reference companion to: Chapter 00: Pre-Workshop Setup | Also relevant: Chapter 14 Authoritative source: GitHub Docs: Authenticating with GitHub from Git SSH Keys & Personal Access Tokens Audience: This appendix is for contributors who need to configure Git authentication for push access. If you're working entirely through the GitHub web interface or GitHub Desktop, you can skip this. If you're using VS Code with Git command line, this becomes relevant when you want to push commits to your fork. Learning Cards: Using This Authentication Reference Screen reader users This appendix has two main paths: Personal Access Token (recommended) and SSH Keys -- jump to your chosen method via heading navigation Step-by-step instructions are numbered lists -- your screen reader announces "1 of 8," etc. to track progress The Troubleshooting section near the bottom covers the error messages you are most likely to encounter Low vision users Command-line examples are in code blocks with high contrast -- increase zoom to read them comfortably Each method (PAT vs SSH) is a separate section with its own step-by-step flow The "Do not" lists use bold text to highlight security warnings Sighted users Start at "Two Authentication Methods" for a pros/cons comparison, then follow the section for your choice Code blocks show the exact commands to copy -- use the copy button in the top-right corner on GitHub The Troubleshooting section at the bottom is organized by error message When You Need Authentication GitHub requires authentication when you: Push commits to a repository Clone a private repository Access organization repositories with specific permissions You do not need authentication to: Clone public repositories View public repositories on GitHub.com Read issues and pull requests Two Authentication Methods Personal Access Token (PAT) A Personal Access Token is a password-like string you generate on GitHub and use instead of your account password when Git asks for credentials. Pros Works on all operating systems Easy to set up for screen reader users (no command line required) Can be scoped to specific permissions Easy to revoke if compromised Cons You have to store it securely Expires after a set time (you must regenerate) SSH Keys SSH uses public-key cryptography. You generate a key pair on your computer (public + private), upload the public key to GitHub, and Git uses the private key to prove your identity. Pros Once set up, works automatically (no password prompts) More secure than tokens Never expires Cons Requires command-line setup (less accessible for some screen reader users) Slightly more complex initial configuration Creating a Personal Access Token (Recommended for This Workshop) Why this method: It's screen reader accessible through the GitHub web interface, and you can complete it without command-line Git configuration. Step 1: Generate the Token Navigate to github.com/settings/tokens Select "Tokens (classic)" from the left sidebar Activate "Generate new token" → Select "Generate new token (classic)" Give it a descriptive name in the Note field: "Workshop Laptop Token" Set expiration: 30 days or 60 days (recommended for temporary workshop use) Select scopes: repo - Full control of private repositories (includes public repo access) workflow - Update GitHub Actions workflows (if you'll work with Actions) Scroll down and activate "Generate token" CRITICAL: Copy the token immediately - you cannot see it again Screen reader note: The token appears as a long string in a text field. Select all ( Ctrl+A ), copy ( Ctrl+C ), and paste it into a secure note or password manager. Step 2: Store It Securely Options Password manager (1Password, Bitwarden, LastPass) - best option Encrypted note in your operating system's secure notes Plain text file in an encrypted folder (temporary only) Do not Paste it into a document you sync to cloud storage unencrypted Email it to yourself Save it in a public GitHub file Step 3: Use It The next time Git asks for your password (when you push, pull from a private repo, or clone a private repo): Username: [your-github-username] Password: [paste-your-PAT-here] Windows Git Credential Manager: Windows will remember this token automatically after your first use. You only paste it once. macOS Keychain: macOS will offer to save it to Keychain. Select "Always Allow." Linux: You can configure Git to cache credentials: git config --global credential.helper cache Setting Up SSH Keys (Alternative Method) If you prefer SSH and are comfortable with terminal commands: Step 1: Check If You Already Have a Key ls -al ~/.ssh Look for files named id_rsa.pub , id_ed25519.pub , or similar. If you s" + }, + { + "id": "admin/qa-bundle/docs/appendix-e-advanced-git.html", + "title": "Appendix E: Advanced Git Operations", + "url": "admin/qa-bundle/docs/appendix-e-advanced-git.html", + "body": "Appendix E: Advanced Git Operations Episode coming soon: Advanced Git Operations - a conversational audio overview of this appendix. Listen before reading to preview the concepts, or after to reinforce what you learned. Reference companion to: Chapter 13: How Git Works | Also relevant: Chapter 14 Authoritative source: Pro Git Book Going Deeper with Git Who this is for: You have completed Chapter 11 (Git & Source Control) and feel comfortable with the basics — cloning, branching, committing, pushing, and pulling. This appendix covers the next tier of Git skills that come up constantly in real open source contribution: cherry-picking fixes across branches, cleaning up messy commit history before a PR, safely undoing mistakes, and understanding why your push sometimes gets blocked. Every section shows three paths: VS Code , GitHub CLI ( gh ) , and Git CLI . Use whichever fits your workflow — they all produce the same result. Table of Contents Cherry-Pick — Grabbing a Specific Commit Interactive Rebase — Cleaning Up Your History git reset — Undoing at Different Depths git revert — The Safe Undo for Shared Branches Tags — Marking Important Moments Detached HEAD — What It Is and How to Get Out Force Pushing Safely git bisect — Finding the Commit That Broke Things git clean — Clearing Out Untracked Files Branch Protection — Why Your Push or Merge May Be Blocked Using GitHub Copilot for Git Operations Learning Cards: Using This Advanced Git Reference Screen reader users Each operation is a numbered h2 section with three sub-paths: VS Code, GitHub CLI, and Git CLI Use H to jump between operations and 3 to jump between the tool-specific sub-headings within each The Table of Contents above has anchor links -- activate any link to jump directly to that operation Low vision users Command examples are in labeled code blocks -- increase zoom and each command fits on one line Every section follows the same structure: what it is, when to use it, then tool-specific steps The Quick Reference table near the bottom gives a one-row-per-operation summary for fast lookup Sighted users Scan the Table of Contents to find the Git operation you need -- sections are ordered from most to least common Each section has VS Code, CLI, and GitHub CLI paths shown side by side Jump to the Quick Reference table at the bottom for a compact summary of all commands 1. Cherry-Pick — Grabbing a Specific Commit What it is: Cherry-pick lets you take a single commit from any branch and apply it to your current branch. Think of it like copy-pasting a specific change — without bringing the entire branch along with it. When you'd use it: You fixed a bug on a feature branch, but main also needs that fix right now A teammate landed a commit on their branch and you need just that one change You accidentally committed to the wrong branch and need to move that commit somewhere else Finding the Commit SHA Before cherry-picking, you need the commit's SHA (the unique ID for that commit). VS Code Open the Timeline panel: Click View → Open View → Timeline (or press Ctrl+Shift+P and type "Timeline") Switch to the branch that has the commit you want, browse the Timeline, and copy the commit SHA shown in the details panel Git CLI # See commits on another branch without switching to it git log feature/bug-fix --oneline # Output: # a1b2c3d Fix null pointer error in auth module # e4f5g6h Add unit tests for login The short SHA is the first 7 characters ( a1b2c3d ). Applying the Cherry-Pick VS Code (Command Palette) Press Ctrl+Shift+P (or Cmd+Shift+P on macOS) Type "cherry" and select "Git: Cherry Pick..." Paste or type the commit SHA Press Enter — VS Code applies the commit to your current branch GitHub CLI The GitHub CLI doesn't have a direct cherry-pick command (it's a local Git operation), but you can use it to find the SHA first: # List commits on a branch via gh to find the one you want gh api repos/{owner}/{repo}/commits?sha=feature/bug-fix --jq '.[].sha, .[].commit.message' | head -20 # Then cherry-pick using git git cherry-pick a1b2c3d Git CLI # Apply a single commit git cherry-pick a1b2c3d # Apply a range of commits (from older to newer, exclusive of first) git cherry-pick a1b2c3d..e4f5g6h # Apply without automatically committing (lets you review changes first) git cherry-pick --no-commit a1b2c3d If There's a Conflict Cherry-pick can hit conflicts just like a merge. When it does: Git pauses and marks the conflicting files (same <<<<<<< HEAD markers as merge conflicts) Resolve the conflicts in VS Code's conflict editor (see Chapter 7: Merge Conflicts ) Stage the resolved files Then either: # Continue the cherry-pick after resolving git cherry-pick -- continue # Or cancel it entirely and go back to where you started git cherry-pick --abort Screen reader tip: When a cherry-pick stops due to a conflict, run git status in the terminal — it announces exactly which files need attent" + }, + { + "id": "admin/qa-bundle/docs/appendix-f-git-security.html", + "title": "Appendix F: Git Security for Contributors", + "url": "admin/qa-bundle/docs/appendix-f-git-security.html", + "body": "Appendix F: Git Security for Contributors Episode coming soon: Git Security for Contributors - a conversational audio overview of this appendix. Listen before reading to preview the concepts, or after to reinforce what you learned. Reference companion to: Chapter 08: Open Source Culture | Also relevant: Chapter 14 Authoritative source: GitHub Docs: Code security Keeping Secrets Out of Your Repository Who this is for: Anyone committing code or documentation to a repository. You don't need to be a security expert — this appendix covers the practical habits that protect you and the projects you contribute to. Most security incidents in open source aren't caused by attacks; they're caused by accidents. A token committed by mistake, a password left in a config file, a .env file that slipped through. The good news: a few simple habits prevent almost all of them. Table of Contents Why This Matters — What Happens When Secrets Leak The .gitignore File — Your First Line of Defense Environment Variables — The Right Way to Store Secrets Review Before You Commit Pre-Commit Hooks — Automated Secret Detection I Accidentally Committed a Secret — What Now? GitHub's Built-In Push Protection Secure Credential Storage Security Checklist for Contributors Learning Cards: Using This Security Reference Screen reader users Sections are ordered from understanding (section 1) to prevention (2-5) to recovery (6-7) to daily habits (8-9) Code blocks contain exact gitignore patterns and terminal commands -- switch to Focus Mode before copying The Security Checklist (section 9) is a task list you can use before every push Low vision users Code examples for .gitignore patterns and terminal commands are in high-contrast code blocks Warning callouts use bold text -- scan for bold to find the most critical safety notes The Security Checklist at the bottom uses checkbox formatting for easy visual tracking Sighted users Read section 1 for motivation, then jump to the section matching your current need The .gitignore templates in section 2 are copy-paste ready for most project types Skip to the Security Checklist (section 9) for a pre-push routine you can follow every time 1. Why This Matters — What Happens When Secrets Leak When a secret (API key, token, password, private key) is committed to a public GitHub repository — even for a few seconds before you delete it — it's effectively compromised. Why "I'll just delete it right away" isn't enough: Bots scan GitHub continuously and harvest secrets within seconds of a push The secret lives in your git history even after you delete the file GitHub forks capture history — once forked, you can't fully erase it Search engines may index the content before you remove it Real-world consequences: An AWS key leaked to a public repo can result in thousands of dollars of compute charges within hours A GitHub PAT can be used to access private repositories, delete code, or impersonate you A Stripe API key can be used to make fraudulent charges against your account The good news: GitHub automatically revokes its own tokens (PATs, GitHub App tokens) when it detects them in a commit. But third-party services (AWS, Stripe, Twilio, etc.) require you to rotate the secret manually — and fast. 2. The .gitignore File — Your First Line of Defense A .gitignore file tells Git which files to never track. Files listed in .gitignore won't show up in git status , won't be staged by git add , and won't be committed. What belongs in .gitignore Secrets and credentials # Environment files (contain API keys, database passwords, etc.) .env .env.local .env. * .local .env.development .env.production * .env # Key files * .pem * .key * .p12 * .pfx id_rsa id_ed25519 # Credential files credentials.json secrets.json config/secrets.yml .aws/credentials Editor and OS clutter # macOS .DS_Store .AppleDouble # Windows Thumbs.db desktop.ini # VS Code (optional — some teams commit these) .vscode/settings.json # JetBrains IDEs .idea/ Build output and dependencies # Node node_modules / dist / build / # Python __pycache__ / * .pyc .venv / venv / # General * .log * .tmp * .cache Checking if a file is already tracked .gitignore only prevents untracked files from being added. If Git is already tracking a file, .gitignore won't stop it from being committed in the future. # Check if a specific file is tracked git ls-files . env # If it returns the filename, it's being tracked — you need to untrack it git rm --cached . env # Then add it to .gitignore and commit Global .gitignore — apply to every repo on your machine You can create a global .gitignore that applies to all repositories on your computer — useful for OS-specific and editor-specific files you never want to commit anywhere. # Create a global gitignore file touch ~/.gitignore_global # Tell Git to use it git config --global core.excludesfile ~/.gitignore_global Add your editor and OS files to ~/.gitignore_global so you never have to ad" + }, + { + "id": "admin/qa-bundle/docs/appendix-g-vscode-reference.html", + "title": "Appendix G: VS Code Accessibility Reference", + "url": "admin/qa-bundle/docs/appendix-g-vscode-reference.html", + "body": "Appendix G: VS Code Accessibility Reference Listen to Episode 30: VS Code Accessibility Reference - a conversational audio overview of this chapter. Listen before reading to preview the concepts, or after to reinforce what you learned. Reference companion to: Chapter 11: VS Code Interface | Also relevant: Chapter 12 Authoritative source: VS Code Docs: Accessibility Complete Technical Reference for Screen Reader Users Purpose: This appendix provides comprehensive technical documentation for all VS Code accessibility features, settings, and keyboard shortcuts. The main chapters cover essentials; this appendix is your complete reference manual. Referenced by: VS Code Setup & Accessibility Basics , GitHub Copilot Learning Cards: VS Code Accessibility Reference Overview Screen reader users This appendix is your lookup manual -- use Ctrl+G (Go to Line) or Ctrl+Shift+O (Go to Symbol) to jump directly to a setting name Every table is structured with headers; use T in browse mode to jump between tables, then arrow through rows Bookmark this file in VS Code ( Ctrl+K Ctrl+K ) so you can return instantly when you need a setting path Low vision users Increase editor font size ( Ctrl+= ) before scanning the long settings tables -- column values are easier to compare at larger sizes Use the Minimap (if sighted enough) or breadcrumbs bar to orient within this large reference file High-contrast themes make the table grid lines and code spans easier to distinguish from body text Sighted users The Table of Contents links jump directly to each section -- click any link to scroll there instantly Use Ctrl+Shift+O to open the outline view and see all 7 sections as a navigable list The settings tables use consistent columns (Setting Path, Values, Default, Description) -- scan the Default column to see what changes from your current setup Table of Contents Complete Accessibility Settings Reference Audio Cues - All Options Accessible Diff Viewer - Complete Guide Screen Reader-Specific Configurations Complete Keyboard Shortcuts Accessibility Signals Types and Customization Settings.json Configuration Examples 1. Complete Accessibility Settings Reference All settings can be accessed via Settings UI ( Ctrl+, ) or by editing settings.json directly ( Ctrl+Shift+P → "Open User Settings JSON"). Core Accessibility Settings Setting Path Values Default Description editor.accessibilitySupport auto , on , off auto Enables screen reader optimizations. auto detects NVDA/JAWS/VoiceOver. Set to on to force. editor.accessibilityPageSize number (lines) 10 Number of lines to read when using Page Up/Down in screen reader mode editor.guides.bracketPairs boolean false Shows bracket pair guides. Disable for screen readers (visual only). editor.guides.bracketPairsHorizontal boolean false Shows horizontal bracket guides. Disable for screen readers. editor.guides.highlightActiveBracketPair boolean true Highlights matching brackets. Not announced by screen readers. editor.guides.highlightActiveIndentation boolean true Highlights active indentation. Visual only. editor.guides.indentation boolean true Shows indentation guides. Not useful for screen readers. editor.hover.enabled boolean true Enables hover popups. Use Alt+F2 (Accessible View) to read hover content. editor.minimap.enabled boolean true Shows visual minimap. Recommended: Set to false for screen readers. editor.occurrencesHighlight boolean true Highlights occurrences of selected text. Visual only. editor.renderWhitespace none , boundary , selection , trailing , all selection Shows whitespace characters. Recommended: none for screen readers. editor.wordWrap off , on , wordWrapColumn , bounded off Wraps long lines. Recommended: on for screen readers. workbench.editor.enablePreview boolean true Opens files in preview mode (single tab). Set to false to always open in new tab. Diff and Merge Settings Setting Path Values Default Description diffEditor.codeLens boolean false Shows CodeLens in diff view. Visual only. diffEditor.diffAlgorithm legacy , advanced advanced Diff calculation method. advanced produces better hunks for screen readers. diffEditor.ignoreTrimWhitespace boolean true Ignores whitespace changes in diffs. Recommended: true to reduce noise. diffEditor.renderSideBySide boolean true Shows diffs side-by-side. Set to false for inline view (easier for screen readers). diffEditor.wordWrap off , on , inherit inherit Word wrap in diff view. on recommended for long lines. merge-conflict.decorators.enabled boolean true Shows merge conflict decorators. Use Accessible Diff instead ( F7 ). Terminal Settings Setting Path Values Default Description terminal.integrated.accessibleViewFocusesTerminal boolean true Returns focus to terminal after closing Accessible View. terminal.integrated.accessibleViewPreserveCursorPosition boolean false Preserves cursor position when opening Accessible View. terminal.integrated.enableBell boolean false Enables terminal bell sound. Recommended: true for audio f" + }, + { + "id": "admin/qa-bundle/docs/appendix-h-github-desktop.html", + "title": "Appendix H: GitHub Desktop", + "url": "admin/qa-bundle/docs/appendix-h-github-desktop.html", + "body": "Appendix H: GitHub Desktop Episode coming soon: GitHub Desktop - a conversational audio overview of this appendix. Listen before reading to preview the concepts, or after to reinforce what you learned. Reference companion to: Chapter 01: Choose Your Tools | Also relevant: Chapter 14 Authoritative source: GitHub Desktop Docs A Visual Git Client for Every Workflow Who this is for: You want a dedicated graphical Git application — something separate from your code editor, with a clear visual interface for cloning, branching, committing, and managing pull requests. GitHub Desktop is a great fit if you prefer working with a purpose-built Git GUI, or if VS Code's Source Control panel feels too embedded in the editor for your workflow. GitHub Desktop is free, open source, and made by GitHub. It works on Windows and macOS. Table of Contents What GitHub Desktop Does (and Doesn't Do) Installing GitHub Desktop Signing In and Authentication The Interface at a Glance Cloning a Repository Creating and Switching Branches Staging and Committing Changes Push and Pull Syncing Your Fork Resolving Merge Conflicts Viewing History Cherry-Pick in GitHub Desktop Stashing Changes Undoing Changes Accessibility and Screen Reader Notes GitHub Desktop vs VS Code vs Git CLI — When to Use Each 1. What GitHub Desktop Does (and Doesn't Do) GitHub Desktop covers the everyday Git workflow that most contributors use on most days. What it supports Supported: Clone repositories from GitHub Supported: Create, switch, and delete branches Supported: Stage files (and individual lines/hunks within files) Supported: Write commit messages and commit Supported: Push and pull from GitHub Supported: Open pull requests (launches GitHub.com in your browser) Supported: Resolve merge conflicts with a visual editor Supported: View commit history and diffs Supported: Cherry-pick commits between branches Supported: Stash and restore uncommitted changes Supported: Undo commits and discard changes What it does not support (use Git CLI or VS Code terminal instead) Not supported in the GitHub Desktop UI: Interactive rebase ( git rebase -i ) Not supported in the GitHub Desktop UI: git bisect Not supported in the GitHub Desktop UI: git clean Not supported in the GitHub Desktop UI: Creating annotated tags Not supported in the GitHub Desktop UI: Commit signing (GPG/SSH) For these operations, open the repository in your terminal directly from GitHub Desktop — Repository → Open in Terminal or Repository → Open in Command Prompt puts you in the right directory instantly. Learning Cards: What GitHub Desktop Does Screen reader users GitHub Desktop handles cloning, branching, staging, committing, and pushing -- all accessible via keyboard and standard form controls For operations Desktop does not support (rebase, bisect, clean), use Repository then Open in Terminal to land in the right directory instantly All commit message fields are standard text inputs that screen readers announce as editable text Low vision users GitHub Desktop supports system-level zoom and high-contrast OS themes on both Windows and macOS The diff panel uses green and red backgrounds for additions and deletions -- pair these with font size adjustments in your OS display settings If the diff colors are hard to distinguish, open the same diff in VS Code via Repository then Open in VS Code for more theme options Sighted users The three-panel layout (toolbar, file list, diff view) gives you a visual snapshot of your repository state at a glance Look for the badge count on the Fetch/Push button to see how many commits are waiting to push or pull The check mark, plus, and minus icons next to filenames show modified, added, and deleted status instantly 2. Installing GitHub Desktop Windows Option A: Winget (recommended) winget install GitHub.GitHubDesktop Option B: Direct download Go to desktop.github.com Select "Download for Windows" Run the installer — it installs and launches automatically macOS Option A: Homebrew brew install --cask github Option B: Direct download Go to desktop.github.com Select "Download for macOS" Open the downloaded .zip , drag GitHub Desktop to your Applications folder Linux: GitHub Desktop does not officially support Linux. Linux users should use VS Code's Source Control panel or the Git CLI. 3. Signing In and Authentication GitHub Desktop uses browser-based OAuth sign-in — no tokens or SSH keys needed. It handles authentication for you automatically. Sign in on first launch Open GitHub Desktop Select "Sign in to GitHub.com" Your browser opens to a GitHub authorization page — sign in with your GitHub account Authorize GitHub Desktop when prompted Switch back to GitHub Desktop — you're signed in That's it. GitHub Desktop stores your credentials securely in the system keychain. You won't be asked for a password again. If you use GitHub Enterprise or a GitHub organization: Select "Sign in to GitHub Enterprise Server" and" + }, + { + "id": "admin/qa-bundle/docs/appendix-i-github-cli.html", + "title": "Appendix I: GitHub CLI Reference", + "url": "admin/qa-bundle/docs/appendix-i-github-cli.html", + "body": "Appendix I: GitHub CLI Reference Episode coming soon: GitHub CLI Reference - a conversational audio overview of this appendix. Listen before reading to preview the concepts, or after to reinforce what you learned. Reference companion to: Chapter 01: Choose Your Tools | Also relevant: Chapter 14 Authoritative source: GitHub CLI Manual Your Terminal, Supercharged for GitHub Who this is for: You want to manage GitHub — issues, pull requests, repos, releases — from your terminal without opening a browser. The GitHub CLI ( gh ) gives you full access to GitHub from the command line, with clean plain-text output that works beautifully with screen readers. gh handles the GitHub side of things (issues, PRs, repos, releases). git handles the local version control side (commits, branches, history). You use both together. Table of Contents Installing and Authenticating Repos — Clone, Fork, Create, View Issues — Create, List, View, Comment, Close Pull Requests — Create, Review, Merge, Check Releases — Create, List, Upload Search — Issues, PRs, Repos, Code Labels and Milestones Output Formatting — JSON, jq, Templates Aliases — Create Your Own Shortcuts Extensions — Adding New Commands Copilot in the CLI Screen Reader Tips Quick Reference Card 1. Installing and Authenticating Installing Windows winget install GitHub.cli Or download the installer from cli.github.com . macOS brew install gh Linux (Debian/Ubuntu) ( type -p wget >/dev/null || ( sudo apt update && sudo apt-get install wget -y)) \\ && sudo mkdir -p -m 755 /etc/apt/keyrings \\ && wget -qO- https://cli.github.com/packages/githubcli-archive-keyring.gpg | sudo tee /etc/apt/keyrings/githubcli-archive-keyring.gpg > /dev/null \\ && sudo chmod go+r /etc/apt/keyrings/githubcli-archive-keyring.gpg \\ && echo "deb [arch= $(dpkg --print-architecture) signed-by=/etc/apt/keyrings/githubcli-archive-keyring.gpg] https://cli.github.com/packages stable main" | sudo tee /etc/apt/sources.list.d/github-cli.list > /dev/null \\ && sudo apt update \\ && sudo apt install gh -y Verify installation gh --version Authenticating gh auth login Follow the prompts: Where do you use GitHub? → GitHub.com (or Enterprise) Preferred protocol? → HTTPS (or SSH) Authenticate with browser? → Yes — your browser opens for OAuth sign-in After signing in, return to the terminal. You're done. # Check your auth status at any time gh auth status # Log out gh auth logout # Refresh credentials / add new scopes gh auth refresh Screen reader tip: gh auth login is an interactive prompt — navigate with Arrow keys, confirm with Enter . All prompts are plain text and read naturally. The browser step opens automatically; switch back to the terminal when the browser confirms success. Learning Cards: Getting Started with gh Screen reader users gh auth login uses plain-text arrow-key prompts -- every option is announced as you arrow through the list After authentication, gh auth status confirms your login in a single readable line -- no browser needed All gh output is plain text with no hidden elements, making it one of the most screen-reader-friendly GitHub interfaces Low vision users Increase your terminal font size before running gh commands -- all output scales with your terminal settings Use a high-contrast terminal theme (light text on dark background, or vice versa) for comfortable reading of command output gh output is plain text with no color-dependent meaning -- colors are supplementary labels, not the only indicator Sighted users The interactive prompts use arrow-based selection with a highlight marker -- look for the > indicator next to your current choice After gh auth login , the terminal prints a success confirmation with your username -- verify it matches your GitHub account Install gh via winget or brew for the fastest setup; the binary is immediately available in your current terminal session 2. Repos — Clone, Fork, Create, View # Clone a repository (automatically sets up the remote) gh repo clone owner/repo-name # Fork a repo and clone your fork in one step gh repo fork owner/repo-name -- clone # Fork without cloning (creates the fork on GitHub only) gh repo fork owner/repo-name # Create a brand new repository gh repo create my-new-project gh repo create my-new-project --public --description "My project description" gh repo create my-new-project --private # View a repository's details gh repo view gh repo view owner/repo-name # Open the repo in your browser gh repo view --web # List your repositories gh repo list gh repo list -- limit 50 # List repos for an org gh repo list my-org -- limit 100 # Archive a repository gh repo archive owner/repo-name # Delete a repository (careful!) gh repo delete owner/repo-name --confirm # Sync your fork with upstream gh repo sync gh repo sync --branch main 3. Issues — Create, List, View, Comment, Close Creating issues # Create an issue interactively (opens a prompt for title, bod" + }, + { + "id": "admin/qa-bundle/docs/appendix-j-cloud-editors.html", + "title": "Appendix J: GitHub Codespaces", + "url": "admin/qa-bundle/docs/appendix-j-cloud-editors.html", + "body": "Appendix J: GitHub Codespaces Listen to Episode 31: GitHub Codespaces - a conversational audio overview of this chapter. Listen before reading to preview the concepts, or after to reinforce what you learned. Reference companion to: Chapter 01: Choose Your Tools | Also relevant: Chapter 11 Authoritative source: GitHub Docs: Codespaces Cloud Development Environments - Accessibility Guide GitHub Codespaces gives you a full VS Code development environment in your browser or connected to your local VS Code, running on a cloud machine. For screen reader users, this means a consistent, pre-configured environment with no local setup required. Table of Contents What Is GitHub Codespaces? Creating a Codespace Codespace Environments Accessibility in Codespaces Screen Reader Configuration Keyboard Shortcuts in Codespaces Managing Your Codespaces Dotfiles and Persistent Configuration Codespaces vs GitHub.dev Common Issues and Workarounds 1. What Is GitHub Codespaces? A Codespace is a cloud-hosted development environment. When you open one, GitHub provisions a virtual machine, clones your repository into it, and connects it to a VS Code interface - either in your browser or via your local VS Code Desktop. Why this matters for accessibility No local installation of tools, compilers, or language runtimes required Your screen reader and OS settings stay on your machine; only the editor runs in the cloud VS Code's full accessibility features (audio cues, screen reader optimized mode, diff viewer) are available The environment is identical for every workshop participant - facilitators can reproduce issues reliably Free tier: GitHub provides a monthly free allowance of Codespace hours for personal accounts. Workshop usage typically falls well within the free tier. Learning Cards: Cloud Editors Overview Screen reader users Codespaces gives you a full VS Code interface with terminal access -- your screen reader and OS settings stay on your local machine The browser-based editor activates screen reader optimized mode automatically if your OS signals a screen reader is running Connect a Codespace to your local VS Code Desktop (via the Codespaces extension) for the most familiar screen reader experience Low vision users Settings Sync carries your font size, theme, and zoom preferences from local VS Code into Codespaces automatically The browser-based editor supports Ctrl+= / Ctrl+- zoom just like desktop VS Code Use a high-contrast VS Code theme -- it applies identically in the cloud editor Sighted users Press . on any GitHub repository page to open it instantly in github.dev (browser editor, no terminal) Codespaces provisions a full VM with terminal -- use it when you need to run code, not just edit The default 2-core machine is sufficient for workshop exercises; upgrade only for heavy builds 2. Creating a Codespace From a Repository Page Navigate to the repository on GitHub Press the Code button (keyboard shortcut: there is no direct shortcut - Tab to the button) In the panel that opens, choose the Codespaces tab Activate Create codespace on main (or your branch name) The Codespace opens in a new browser tab after provisioning (typically 30-60 seconds) From the Codespaces Dashboard Go to github.com/codespaces Activate New codespace Use the search field to find your repository Choose a branch, machine type, and region Activate Create codespace Machine Types Type CPU RAM Best for 2-core 2 vCPU 8 GB General development, documentation 4-core 4 vCPU 16 GB Builds, tests, moderate workloads 8-core 8 vCPU 32 GB Heavy builds, multiple services For workshop exercises, the default 2-core machine is sufficient. 3. Codespace Environments Browser (VS Code for the Web) The Codespace opens directly in your browser as a fully functional VS Code interface. Works in Chrome, Edge, Firefox, and Safari Screen reader support varies slightly by browser - Chrome and Edge have the most consistent behavior with NVDA and JAWS No installation needed Some VS Code extensions are not available in the browser version Local VS Code Desktop If you prefer your local VS Code setup with your extensions and settings: Install the GitHub Codespaces extension in VS Code Sign in to GitHub in VS Code Open the Command Palette ( Ctrl+Shift+P / Cmd+Shift+P ) Run Codespaces: Connect to Codespace Select an existing Codespace or create a new one When connected via local VS Code, your screen reader interacts with your local VS Code installation - all your familiar settings apply. 4. Accessibility in Codespaces Screen Reader Optimized Mode When VS Code detects a screen reader, it automatically activates Screen Reader Optimized mode. You can verify or toggle it manually: Open the Command Palette ( Ctrl+Shift+P ) Search for Toggle Screen Reader Accessibility Mode Press Enter to activate In this mode: The editor reads content line by line instead of character by character Diff views are rendered as accessible text comparisons Inline suggestions from Copilot are announced on a key" + }, + { + "id": "admin/qa-bundle/docs/appendix-k-copilot-reference.html", + "title": "Appendix K: Copilot Reference", + "url": "admin/qa-bundle/docs/appendix-k-copilot-reference.html", + "body": "Appendix K: Copilot Reference Reference companion to: Chapter 16: GitHub Copilot Authoritative source: GitHub Docs: Copilot This appendix consolidates Copilot reference tables (formerly Appendix W) and Copilot model information (formerly Appendix X) into one complete reference. Copilot Reference Tables Listen to Episode 40: GitHub Copilot - Complete Reference - a conversational audio overview of this chapter. Listen before reading to preview the concepts, or after to reinforce what you learned. Keyboard Shortcuts, Chat, Screen Reader Workflow, Plugin Ecosystem, and GitHub Agentic Workflows Quick-reference card for GitHub Copilot in VS Code and the broader agentic ecosystem - plugins, MCP servers, and cloud-based automation. For the Copilot lesson, see Chapter 16: GitHub Copilot . For Accessibility Agents specifically, see Appendix L: Accessibility Agents Reference . Table of Contents Keyboard Shortcuts Chat Participants Chat Slash Commands Chat Modes Custom Instructions - All Levels Accessible View Workflow Configuration Scope Reference Instruction Priority and Conflicts All File Types Quick Reference VS Code Settings Reference Diagnostics and Troubleshooting Screen Reader Workflow - Official Guide awesome-copilot - Plugin Ecosystem GitHub Agentic Workflows - Agents in the Cloud 1. Keyboard Shortcuts Inline Suggestions (Ghost Text) Action Windows / Linux macOS Accept entire suggestion Tab Tab Reject suggestion Escape Escape Accept one word at a time Ctrl+Right Arrow Cmd+Right Arrow Show next alternative suggestion Alt+] Option+] Show previous alternative suggestion Alt+[ Option+[ Open full suggestion list Ctrl+Enter Cmd+Enter Open suggestion in Accessible View Alt+F2 Option+F2 Insert suggestion from Accessible View at cursor Ctrl+/ Cmd+/ Word-by-word acceptance ( Ctrl+Right Arrow ) is recommended for screen reader users - it lets you review the suggestion incrementally before committing to it. Accessible View workflow for screen reader users: Press Alt+F2 when a suggestion appears to hear the full text without streaming noise, then press Ctrl+/ to insert it directly from the Accessible View without closing the panel first. Copilot Chat Action Windows / Linux macOS Open Chat panel Ctrl+Shift+I Cmd+Shift+I Open inline chat (in-file, at cursor) Ctrl+I Cmd+I Open Quick Chat (floating dialog) Ctrl+Shift+Alt+I Cmd+Shift+Ctrl+I Send message Ctrl+Enter Cmd+Enter Clear chat history Ctrl+L Cmd+L Accessibility Action Windows / Linux macOS Open Accessible View Alt+F2 Option+F2 Open Accessible Help Alt+H Option+H Close Accessible View Escape Escape Use Accessible View ( Alt+F2 ) every time Copilot responds. It provides the complete response in a readable pane - no streaming, no live region noise, proper heading structure. 2. Chat Participants Type these in the Copilot Chat input to give Copilot context from a specific source. @ Participants - Scope Context Participant What It Does @workspace Searches your entire VS Code workspace for relevant context @github Accesses GitHub.com data - search issues, PRs, code across the platform @terminal Provides context from the VS Code integrated terminal Example prompts @workspace find all places where heading hierarchy is documented @github search community-access/accessibility-agents for issues labeled accessibility @terminal what did the last command output mean? # Variables - Specific Context Variable What It Attaches #file Opens a file picker - attach any file from your workspace #selection Attaches your currently selected text #codebase Searches the full codebase for relevant snippets #terminalLastCommand Attaches the last terminal command and its output Example prompts Review #selection for heading hierarchy violations Explain what #file does (then pick a file from the picker) What does this error mean? #terminalLastCommand Search #codebase for all screen reader navigation instructions 3. Chat Slash Commands Type / in Copilot Chat to see the available built-in commands. Command What It Does Example /explain Explains the selected code or text in plain language Select a complex block → /explain /fix Suggests fixes for problems in the selected code Select broken code → /fix /tests Generates unit tests for the selected function (code files) Select a function → /tests /doc Generates documentation (JSDoc, docstring) for parsed code Select a function → /doc /new Scaffolds a new file or project structure /new React component for notifications /help Shows all available Copilot commands and participants /help /clear Clears the current chat history /clear Workspace management slash commands Command What It Does Example /init Analyzes your workspace and auto-generates a .github/copilot-instructions.md tailored to your project /init /savePrompt Saves the current chat conversation as a reusable .prompt.md slash command file After a useful exchange, type /savePrompt Note: These are Copilot's built-in chat slash commands. Accessibility Agents adds 28 additional workspace-level slash comm" + }, + { + "id": "admin/qa-bundle/docs/appendix-l-agents-reference.html", + "title": "Appendix L: Accessibility Agents Reference", + "url": "admin/qa-bundle/docs/appendix-l-agents-reference.html", + "body": "Appendix L: Accessibility Agents Reference Listen to Episode 39: Accessibility Agents - Complete Reference - a conversational audio overview of this chapter. Listen before reading to preview the concepts, or after to reinforce what you learned. Reference companion to: Chapter 19: Accessibility Agents | Also relevant: Chapter 20 Authoritative source: GitHub Docs: Building Copilot extensions Complete Reference - Agents, Slash Commands, Instructions, Configuration Levels, and All File Formats This is your comprehensive reference for Accessibility Agents and the full VS Code Copilot customization system. The ecosystem includes 55 agents across 3 teams and 5 platforms , plus 54+ slash commands, 17 skills, and 6 instruction files. For the lesson, see Chapter 19: Accessibility Agents . For Copilot keyboard shortcuts and Chat features, see Appendix K: GitHub Copilot Reference . Table of Contents The Full Agent Ecosystem GitHub Workflow Agents - Quick Reference Slash Commands and Prompts Customization Primitives - Decision Guide Scope and Priority - All Levels Always-On Instructions - All File Types File-Based Instructions (.instructions.md) .agent.md - Complete Format Reference .prompt.md - Complete Format Reference Agent Skills (SKILL.md) - Complete Format Reference Hooks (.json) - Lifecycle Automation preferences.md - Accessibility Agents Personal Settings Diagnostics and Troubleshooting Further Reading 1. The Full Agent Ecosystem Accessibility Agents includes 55 agents organized into three specialized teams, available on five platforms. Platforms Platform Agent Format Installation GitHub Copilot (VS Code) .github/agents/*.agent.md Fork repo or run installer Claude Code Per-agent CLAUDE.md + hook enforcement One-liner installer auto-detects Gemini CLI Gemini skill files One-liner installer auto-detects Claude Desktop MCP server integration One-liner installer auto-detects Codex CLI Codex agent files One-liner installer auto-detects Team 1: Accessibility (26 agents) Agent Type What It Does @accessibility-lead Orchestrator Delegates multi-agent accessibility audits to specialist agents @aria-specialist Task ARIA roles, states, properties, widget patterns (modals, tabs, comboboxes) @modal-specialist Task Dialog focus trapping, escape behavior, screen reader overlay announcements @contrast-master Task Color contrast ratios, focus indicators, dark mode, visual presentation @keyboard-navigator Task Tab order, focus management, keyboard shortcuts, skip links, focus traps @live-region-controller Task Live region announcements, dynamic content, toasts, loading states @forms-specialist Task Form labels, error handling, validation, autocomplete, field grouping @alt-text-headings Task Alt text quality, heading hierarchy, document outline, landmark structure @tables-specialist Task Table markup, scope, caption, headers, sortable columns, ARIA grid @link-checker Informational Link text quality, ambiguous links, WCAG 2.4.4 and 2.4.9 compliance @web-accessibility-wizard Orchestrator Full guided WCAG audit - severity scoring, remediation tracking, action plan @testing-coach Informational NVDA/JAWS/VoiceOver testing guidance, automated test setup (axe-core, Playwright) @wcag-guide Informational WCAG 2.2 AA reference, success criteria explanations, conformance levels @word-accessibility Task Microsoft Word document accessibility auditing and remediation @excel-accessibility Task Microsoft Excel spreadsheet accessibility auditing and remediation @powerpoint-accessibility Task Microsoft PowerPoint presentation accessibility auditing @office-scan-config Informational Office document scan configuration and rule management @pdf-accessibility Task PDF accessibility auditing (PDF/UA, tagged PDF structure) @pdf-scan-config Informational PDF scan configuration and rule management @document-accessibility-wizard Orchestrator Guided document audit wizard for Word, Excel, PowerPoint, and PDF @cognitive-accessibility Informational Cognitive accessibility, plain language, reading level, content clarity @mobile-accessibility Task iOS VoiceOver and Android TalkBack native app accessibility @design-system-auditor Task Design system component accessibility review and pattern library audit @markdown-a11y-assistant Task Markdown headings, links, alt text, tables, emoji, structure enforcement @epub-accessibility Task ePub and digital publication accessibility auditing @epub-scan-config Informational ePub scan configuration and rule management Team 2: GitHub Workflow (12 agents) Agent Type What It Does @daily-briefing Informational Morning situation report - issues, PRs, CI, security, community activity @issue-tracker Both Find, prioritize, triage, draft replies to issues across repositories @pr-review Both Structured PR reviews with risk assessment, change maps, inline suggestions @analytics Informational Contribution velocity, review turnaround, code hotspots, workload distribution @insiders-a11y-tracker Both Monitor accessibility-sensitive changes - W" + }, + { + "id": "admin/qa-bundle/docs/appendix-m-accessibility-standards.html", + "title": "Appendix M: Accessibility Standards Reference", + "url": "admin/qa-bundle/docs/appendix-m-accessibility-standards.html", + "body": "Appendix M: Accessibility Standards Reference Listen to Episode 20: Accessibility Standards Reference - a conversational audio overview of this chapter. Listen before reading to preview the concepts, or after to reinforce what you learned. Reference companion to: Chapter 08: Open Source Culture | Also relevant: Chapter 12 Authoritative source: W3C WCAG 2.2 | WAI-ARIA 1.2 WCAG, ARIA, and What They Mean for Your Contributions This appendix gives you a working understanding of the accessibility standards that govern the web, GitHub's interface, and the projects you will contribute to. You do not need to memorize these - use this as a lookup when a PR review mentions a specific standard or success criterion. Table of Contents WCAG 2.2 - The Four Principles Conformance Levels: A, AA, AAA Key Success Criteria for Web Contributions ARIA - Roles, States, and Properties ARIA Landmark Roles Common ARIA Patterns How Standards Apply to GitHub Contributions Testing Against Standards Quick Reference: What to Check in a PR Official References 1. WCAG 2.2 - The Four Principles WCAG (Web Content Accessibility Guidelines) is organized around four principles, often abbreviated POUR : Principle Meaning Example Failure Perceivable Information must be presentable to users in ways they can perceive An image with no alt text - a screen reader user gets nothing Operable UI components and navigation must be operable A button that only works on hover - keyboard users cannot activate it Understandable Information and operation must be understandable An error message that says "Invalid input" with no explanation of what is wrong Robust Content must be robust enough to be interpreted by assistive technologies Custom JavaScript widgets with no ARIA roles - screen readers cannot determine what they are Every WCAG success criterion belongs to one of these four principles. Learning Cards: WCAG Overview Screen reader users WCAG is organized around four principles: Perceivable, Operable, Understandable, Robust (POUR) — use this mnemonic when reviewing any PR Most projects target WCAG 2.2 AA — when a reviewer cites a criterion number like 1.4.3, search the tables in Section 3 of this appendix The WCAG Quick Reference (Section 10) is a filterable web page — use your screen reader's find command to jump to any criterion number Low vision users The tables in this appendix use pipe-delimited Markdown — increase your editor font size or use a Markdown preview for cleaner column alignment WCAG 1.4.3 (contrast) and 1.4.11 (non-text contrast) are the criteria most relevant to your daily experience — bookmark them When checking contrast ratios, use the WebAIM Contrast Checker link in Section 10 with your browser zoom set to your preferred level Sighted users The POUR table in this section is your one-glance cheat sheet — scan the Example Failure column to see what each principle looks like when violated Conformance level badges (A, AA, AAA) appear in the Level column of the Section 3 tables — AA rows are your primary targets Bookmark the ARIA Authoring Practices Guide link in Section 10 for live interactive pattern demos 2. Conformance Levels: A, AA, AAA Level Requirement Who targets this A Minimum accessibility - the baseline that removes the most severe barriers Required by most accessibility laws AA Enhanced accessibility - removes significant barriers Required by WCAG 2.2 compliance targets, most government and enterprise standards, GitHub's own accessibility commitment AAA Highest level - removes remaining barriers for the most niche cases Not universally required; applied where feasible Most open source projects, and GitHub itself, target WCAG 2.2 AA compliance. When you file an accessibility bug or review a PR, AA is the standard to reference. 3. Key Success Criteria for Web Contributions These are the criteria you will most commonly encounter when contributing to web projects or reviewing GitHub interface changes. Perceivable Criterion Level What It Requires 1.1.1 Non-text Content A All images, icons, and non-text content have a text alternative ( alt attribute, aria-label , etc.) 1.3.1 Info and Relationships A Structure conveyed visually (headings, lists, tables) is also conveyed programmatically 1.3.2 Meaningful Sequence A Reading order makes sense when CSS is removed 1.3.3 Sensory Characteristics A Instructions do not rely solely on shape, color, or position ("click the green button" fails this) 1.4.1 Use of Color A Color is not the only means of conveying information 1.4.3 Contrast (Minimum) AA Text has at least 4.5:1 contrast ratio against its background (3:1 for large text) 1.4.4 Resize Text AA Text can be resized up to 200% without loss of content or function 1.4.10 Reflow AA Content reflows at 400% zoom without horizontal scrolling 1.4.11 Non-text Contrast AA UI components and graphical objects have at least 3:1 contrast Operable Criterion Level What It Requires 2.1.1 Keyboard A All functionality is avail" + }, + { + "id": "admin/qa-bundle/docs/appendix-n-advanced-search.html", + "title": "Appendix N: GitHub Advanced Search", + "url": "admin/qa-bundle/docs/appendix-n-advanced-search.html", + "body": "Appendix N: GitHub Advanced Search Listen to Episode 27: Advanced Search - a conversational audio overview of this chapter. Listen before reading to preview the concepts, or after to reinforce what you learned. Reference companion to: Chapter 05: Working with Issues | Also relevant: Chapter 09 Authoritative source: GitHub Docs: Searching on GitHub Finding Anything Across All of GitHub GitHub's search engine is powerful and underused. For screen reader users in particular, using the search bar with precise query syntax is often faster and more accessible than navigating filter dropdowns and checkbox menus. This reference covers the query language so you can filter anything from the keyboard. Table of Contents The Search Interface Search Scopes The Core Query Language Searching Issues and Pull Requests Searching Code Searching Commits Searching Repositories Searching Users and Organizations Practical Queries for This Workshop Saving and Reusing Searches 1. The Search Interface GitHub's search is accessible from nearly any page: Global search bar: At the top of every GitHub page - keyboard shortcut / to focus it from anywhere (press / , then type) Issues/PRs list: Each tab has its own search bar pre-scoped to that repository Advanced Search UI: github.com/search/advanced - a form with individual fields for each filter. Accessible but verbose; query syntax below is faster. Keyboard to global search / → Focus the global search bar (works on most GitHub pages) Type your query → Enter → Results page opens, grouped by type (Code, Issues, PRs, Repositories, etc.) Learning Cards: The Search Interface Screen reader users Press / on any GitHub page to jump straight to the global search bar — no Tab hunting required After pressing Enter on a query, results are grouped by type under headings (Code, Issues, PRs, Repositories) — use H to jump between groups Query syntax typed directly in the search bar is often faster and more accessible than the Advanced Search form at github.com/search/advanced Low vision users The search bar sits at the very top of every GitHub page — if you lose it at high zoom, press / to refocus instantly Search results use bold text for matched terms — increase browser zoom to make the highlighted keywords easier to spot Pin the Advanced Search page (github.com/search/advanced) as a bookmark for days when you prefer large labeled form fields over compact query syntax Sighted users Look for the search bar in the top navigation bar — it shows a / hint icon on the right to remind you of the keyboard shortcut After submitting a query, use the left sidebar type filters (Code, Issues, PRs, etc.) to narrow results visually GitHub highlights matched keywords in yellow within search results — scan for those highlights to evaluate relevance quickly 2. Search Scopes By default, GitHub searches across all of GitHub. Scope modifiers restrict results: Modifier Scope repo:owner/name One specific repository org:orgname All repos in an organization user:username All repos owned by a user in:title Only matches in the title field in:body Only matches in the body field in:comments Only matches in comments Example: repo:community-access/accessibility-agents in:title keyboard finds issues/PRs whose titles mention "keyboard" in the accessibility-agents repo. 3. The Core Query Language Boolean Logic Syntax Meaning word1 word2 Both words (implicit AND) word1 OR word2 Either word "exact phrase" Exact phrase match -word Exclude this word -label:bug Exclude items with this label Common Qualifiers Qualifier Meaning is:open Open items only is:closed Closed items only is:merged Merged PRs only is:unmerged Open or closed but not merged PRs is:issue Issues only is:pr Pull requests only is:draft Draft pull requests only label:name Items with this label no:label Items with no labels assignee:@me Assigned to you assignee:username Assigned to a specific user author:@me Created by you author:username Created by a specific user mentions:username Mentions a specific user involves:@me You are author, assignee, mentioned, or commented milestone:"Milestone Name" In a specific milestone no:milestone Not in any milestone no:assignee Not assigned to anyone comments:>5 More than 5 comments reactions:>10 More than 10 reactions Date Qualifiers Qualifier Meaning created:>2025-01-01 Created after a date created:<2025-01-01 Created before a date created:2025-01-01..2025-03-31 Created in a date range updated:>2025-06-01 Updated after a date closed:>2025-06-01 Closed after a date 4. Searching Issues and Pull Requests Going to the Issues search directly GitHub's issue/PR search is at github.com/issues (your issues) or github.com/pulls (your PRs). The search bar there is pre-scoped to "repos you have access to involving you." Practical queries Find all unassigned, open accessibility issues across an org org:community-access is:issue is:open label:accessibility no:assignee Find good fir" + }, + { + "id": "admin/qa-bundle/docs/appendix-o-branch-protection.html", + "title": "Appendix O: Branch Protection Rules and Repository Rulesets", + "url": "admin/qa-bundle/docs/appendix-o-branch-protection.html", + "body": "Appendix O: Branch Protection Rules and Repository Rulesets Listen to Episode 28: Branch Protection and Rulesets - a conversational audio overview of this chapter. Listen before reading to preview the concepts, or after to reinforce what you learned. Reference companion to: Chapter 08: Open Source Culture | Also relevant: Chapter 14 Authoritative source: GitHub Docs: Protected branches How Merging Rules Work and Why Your PR May Be Blocked Who this is for: Contributors who have submitted a PR and are wondering why it cannot be merged yet, as well as workshop facilitators who configure branch protection for practice repositories. Quick Navigation What Branch Protection Does Common Branch Protection Rules Repository Rulesets - The Modern Approach Why Your PR Cannot Be Merged - Diagnosis Guide Navigating the Merge Box with a Screen Reader Status Checks - What They Are and What They Mean Who Can Configure Branch Protection Workshop Repository Configuration Reference 1. What Branch Protection Does A branch protection rule is a set of requirements that must be satisfied before a PR can be merged into a specific branch (typically main ). Branch protection exists to: Require that code is reviewed before it enters the default branch Require that automated tests pass before merging Prevent direct pushes to main without a PR Ensure the branch is up-to-date before merging Require commits to be signed (GPG or SSH signatures) Think of branch protection as the quality gate for a repository's primary branch. Learning Cards: What Branch Protection Does Screen reader users The merge box at the bottom of every PR page is where branch protection surfaces its requirements — press End to jump to the bottom, then use H to find the merge heading Each requirement is announced as a status line: "1 review required," "Some checks haven't completed yet," etc. — listen for these before attempting to merge If the Merge button says "disabled" or "grayed out," branch protection is blocking — the status lines immediately above explain exactly what is needed Low vision users The merge box uses green (ready), yellow (pending), and red (blocked) indicators — zoom in on the merge area to read the text labels next to each colored icon The "Update branch" button appears as a secondary button above the merge button when your PR is behind main — it can be easy to miss at high zoom Required checks show checkmark or X icons that are small at default size — browser zoom to 150%+ makes the pass/fail status easier to distinguish Sighted users Look at the bottom of the PR Conversation tab for the merge box — a green "Merge pull request" button means all requirements are met; grey means something is blocking The list of requirements appears as a vertical checklist above the merge button — each item shows a green checkmark, yellow spinner, or red X Click "Show all checks" to expand the full list of status checks if only a summary is visible 2. Common Branch Protection Rules Required Reviews The most common rule. The maintainer requires a minimum number of approving reviews before the PR can be merged. Example: "Require 1 approving review" What this means for you: Your PR shows a "1 review required" notice in the merge box If a reviewer requests changes, their approval is revoked - you need at least one new approval after your latest push After you push new commits, re-request review from the original reviewer Dismiss stale reviews: Some repos have this enabled - whenever you push a new commit, all existing approvals are automatically withdrawn and you need a fresh review. This prevents sneaking in bad code after approval. Required Status Checks Automated workflows (GitHub Actions or third-party CI) must complete successfully before merging is allowed. Example checks you may see ci / build - compiles the code ci / test - runs the test suite lint - code style checks accessibility-check - automated accessibility scanning CodeQL - security analysis netlify/deploy-preview - preview deployment must succeed What "Required" means: The merge button is grayed out (or shows an error) until all required checks show a green checkmark. A failing or pending check blocks the merge. Require Branches to Be Up to Date Before merging, your PR branch must include all changes from main . This prevents merge conflicts from being introduced silently. If your PR is behind main : The merge box shows: "This branch is out of date with the base branch" Button: "Update branch" - merges current main into your branch Alternative: Rebase your branch (only if the maintainer permits rebase merges) Require Signed Commits All commits in the PR must have a Verified badge (see Appendix D: Git Authentication ). If your commits are unverified, the PR cannot be merged until you re-commit with signing enabled. Require Linear History Only squash merges or rebase merges are p" + }, + { + "id": "admin/qa-bundle/docs/appendix-p-security-features.html", + "title": "Appendix P: GitHub Security Features", + "url": "admin/qa-bundle/docs/appendix-p-security-features.html", + "body": "Appendix P: GitHub Security Features Listen to Episode 29: GitHub Security Features - a conversational audio overview of this chapter. Listen before reading to preview the concepts, or after to reinforce what you learned. Reference companion to: Chapter 08: Open Source Culture | Also relevant: Chapter 17 Authoritative source: GitHub Docs: Code security Dependabot, Secret Scanning, Code Scanning, and Private Advisories Who this is for: Anyone contributing to open source repositories needs to understand how GitHub protects code and what security alerts mean. This appendix explains the GitHub Security and quality tab, how to interpret and respond to alerts, and how to responsibly report vulnerabilities - including in community-access/accessibility-agents . Quick Navigation The Security and quality tab - What It Contains Dependabot - Automated Dependency Updates Secret Scanning - Preventing Credential Leaks Code Scanning and CodeQL Private Vulnerability Reporting The SECURITY.md File Software Bill of Materials (SBOM) Screen Reader Navigation of the Security and quality tab Security and Accessibility Agents 1. The Security and quality tab - What It Contains Every GitHub repository has a Security and quality tab in its navigation bar. What you see there depends on whether you are a contributor with elevated access or a public viewer. Public viewers see Security policy (if the repo has a SECURITY.md ) The private vulnerability reporting form (if enabled by the maintainer) Contributors with write or admin access see Dependabot alerts Secret scanning alerts Code scanning alerts Security advisories The ability to manage security settings Screen Reader Path to the Security and quality tab On any repository page: Tab navigation → secondary nav region → "Security" link → Enter Or: G then S (GitHub keyboard shortcut - enable Focus Mode first) Learning Cards: The Security and quality tab Screen reader users Use G then S (GitHub keyboard shortcut) to jump directly to the Security and quality tab from any repo page — much faster than Tab-navigating the full nav bar The Security and quality tab content varies by your access level — public viewers see only the security policy and vulnerability reporting form; contributors with write access see alerts Dependabot alerts, secret scanning alerts, and code scanning alerts are each a separate link inside the Security and quality tab — use K to navigate between them Low vision users The Security and quality tab link sits in the repository's top navigation bar alongside Code, Issues, PRs, and Actions — zoom in if the tab labels are small Alert severity badges (Critical, High, Medium, Low) use colored labels — each badge also includes the severity word, so color is not the only indicator If the Security and quality tab shows "No alerts," that is good news — look for the green shield icon next to the tab name as confirmation Sighted users Find the Security and quality tab in the repository navigation bar — it shows a shield icon and may display a count badge if alerts exist Inside the Security and quality tab, the left sidebar lists Dependabot, Secret scanning, and Code scanning as separate pages — click each to see its alert list A green shield on the repo home page (or no security count badge) means zero open security alerts 2. Dependabot - Automated Dependency Updates Dependabot is GitHub's automated dependency monitoring and update system. It does two things: Dependabot Alerts When a known security vulnerability (CVE - Common Vulnerability and Exposure) is discovered in a package your project depends on, GitHub creates a Dependabot alert . Alert severity levels Level CVSS Score Range What it means Critical 9.0-10.0 Exploit likely, wide impact - fix immediately High 7.0-8.9 Significant risk - fix this sprint Medium 4.0-6.9 Some risk with specific conditions - schedule fix Low 0.1-3.9 Low likelihood of exploitation - fix when convenient What a dependency alert looks like Alert: Dependabot alert #5 Severity: High Package: lodash (npm) Vulnerable version: < 4.17.21 Fixed version: 4.17.21 Advisory: GHSA-35jh-r3h4-6jhm Description: Prototype pollution vulnerability allows an attacker to modify Object.prototype leading to denial of service or remote code execution. What to do as a contributor when you see an alert Read the advisory to understand the vulnerability scope Check whether the project actually uses the vulnerable code path The fix is almost always: update the dependency to the fixed version Dependabot Security Updates may have already opened a PR - check the PRs tab Dependabot Security Updates If enabled, Dependabot automatically opens a PR to update the vulnerable dependency. The PR will look like: Title: Bump lodash from 4.17.20 to 4.17.21 Author: dependabot[bot] Description: Bumps lodash from 4.17.20 to 4.17.21. - Release notes - Changelog - Commits (linked) As a contributor with access, reviewing and merging these Dependabot PRs is a high-value" + }, + { + "id": "admin/qa-bundle/docs/appendix-q-actions-workflows.html", + "title": "Appendix Q: GitHub Actions and Workflows", + "url": "admin/qa-bundle/docs/appendix-q-actions-workflows.html", + "body": "Appendix Q: GitHub Actions and Workflows Listen to Episode 34: GitHub Actions and Workflows - a conversational audio overview of this chapter. Listen before reading to preview the concepts, or after to reinforce what you learned. Reference companion to: Chapter 17: Issue Templates | Also relevant: Chapter 19 Authoritative source: GitHub Docs: Understanding Actions Understanding Automation in Open Source Repositories Why this matters for you: Every time you open a pull request on a real open source project, automated processes will run. Understanding what they are, what they mean, and what to do when they fail is essential to being a confident contributor. Table of Contents What Is GitHub Actions? Key Vocabulary Where Workflows Live in a Repository The Anatomy of a Workflow File What Triggers a Workflow Understanding Status Checks on Pull Requests Reading the Actions Tab with a Screen Reader Common Workflows You Will Encounter What To Do When a Check Fails Workflow Permissions and Security Accessibility-Focused Workflows Hands-On Activity What We Are NOT Covering (And Where to Learn More) 1. What Is GitHub Actions? GitHub Actions is GitHub's built-in automation system. It lets repository maintainers define automated tasks that run in response to things that happen in the repository - like someone opening a pull request, pushing a commit, or filing an issue. Think of it as a robot assistant that every repository can optionally configure. That robot watches for specific events and then automatically runs jobs: testing code, checking spelling, scanning for accessibility issues, building documentation, deploying a website, and more. As a contributor, you do not need to write workflows. But you will see their results on nearly every pull request you open, and you need to understand what those results mean. Learning Cards: What Is GitHub Actions Screen reader users Workflow files live in .github/workflows/ — use T (Go to file) on any repo page to search for .yml files in that directory The Actions tab is in the repository navigation landmark — press D (NVDA/JAWS) to jump between landmarks and find it You do not need to write YAML to contribute — your job is to read the status check results on your PR and fix any issues they flag Low vision users The Actions tab icon (a play-button triangle) sits in the repo's top navigation bar — zoom in if the icon-only display is hard to read; the word "Actions" appears next to it Workflow YAML files use indentation-sensitive syntax — increase your editor font size and enable visible whitespace to distinguish nesting levels Status check results on your PR use small colored icons (green checkmark, red X, yellow spinner) — zoom to 150%+ to read the text labels beside them Sighted users Find the Actions tab in the repository's top navigation bar between Projects and Security — a play-button icon marks it Workflow files are YAML files in .github/workflows/ — open any one in the Code tab to see the triggers ( on: ) and job steps On your PR, scroll to the checks section near the merge box to see green checkmarks (passed), red X marks (failed), or yellow spinners (running) 2. Key Vocabulary Term What It Means Workflow A complete automated process defined in a YAML file. A repo can have many workflows. Job A group of steps that run together, usually on the same machine. A workflow can have multiple jobs. Step A single task within a job - running a command, calling an action, etc. Action A reusable unit of automation. Like a plugin. Many are shared publicly on GitHub Marketplace . Runner The machine (virtual server) that executes a job. GitHub provides free runners. Trigger / Event The thing that causes a workflow to start - a push, a PR, a schedule, etc. Status check The pass/fail result of a workflow shown on a pull request. Artifact A file produced by a workflow (a build output, a test report, etc.) that can be downloaded. Secret An encrypted variable stored in a repo's settings - used in workflows without exposing sensitive values. YAML The file format used to write workflow files. Indentation matters. on: The YAML key that defines what triggers a workflow. runs-on: The YAML key that specifies the runner OS ( ubuntu-latest , windows-latest , macos-latest ). 3. Where Workflows Live in a Repository Workflow files live in a specific, mandatory location: Description Workflow files live at your-repository/.github/workflows/. Example files include: ci.yml (runs tests on every push or PR), lint.yml (checks code style), a11y-scan.yml (accessibility scanning), and deploy.yml (deploys the site when code merges to main). The .github/ folder is hidden by convention (starts with a dot). To find it: On GitHub.com: The file browser shows it - use T (go to file) or navigate the file table with Ctrl+Alt+Arrow keys In VS Code: It appears in the Explorer panel - enable "Show Hidden Files" if needed Screen reader tip: The .github folder reads as "dot github."" + }, + { + "id": "admin/qa-bundle/docs/appendix-r-projects-deep-dive.html", + "title": "Appendix R: GitHub Projects Deep Dive", + "url": "admin/qa-bundle/docs/appendix-r-projects-deep-dive.html", + "body": "Appendix R: GitHub Projects Deep Dive Listen to Episode 26: GitHub Projects Deep Dive - a conversational audio overview of this chapter. Listen before reading to preview the concepts, or after to reinforce what you learned. Reference companion to: Chapter 09: Labels, Milestones, and Projects Authoritative source: GitHub Docs: About Projects Boards, Tables, Roadmaps, Automations, and Accessible Navigation GitHub Projects is GitHub's built-in project management system. It connects issues and pull requests from one or more repositories into a living, filterable view that your whole team can see and act on. This appendix covers everything beyond the basics introduced in Chapter 9: Labels, Milestones, and Projects . Table of Contents Projects v2: What Changed Creating a Project The Three Layouts in Depth Custom Fields Adding and Managing Items Built-In Automations Iterations (Sprints) Views and Filters Cross-Repository Projects Screen Reader Navigation Reference Accessibility Agents: /project-status Exercises 1. Projects v2: What Changed GitHub has two generations of project tooling. The current generation - called Projects (v2) - is what you'll find on any repository or organization page today. Layouts: Classic v1 offered Kanban board only. V2 offers Board, Table, and Roadmap. Custom fields: Classic v1 had none. V2 supports Text, Number, Date, Single Select, and Iteration fields. Automations: Classic v1 had no built-in automations. V2 has native GitHub Actions integration. Cross-repo support: Classic v1 did not support cross-repository tracking. V2 does. Filtering: Classic v1 had limited filtering. V2 supports full field, label, assignee, and status queries. API: Classic v1 had a limited API. V2 has full GraphQL support. If you see "Projects (Beta)" references in older documentation, those referred to the early rollout of v2. It is now stable and the default. 2. Creating a Project Projects can be created at the organization level (shared across all repos in an org) or at the repository level (scoped to one repo). Create from an Organization Navigate to your organization page ( github.com/your-org ) Select the Projects tab Activate "New project" button Choose a template (blank table, blank board, feature release, etc.) or start empty Give the project a name and select "Create project" Create from a Repository Navigate to any repository Select the Projects tab Activate "Link a project" or "New project" Follow the same template/name flow Screen Reader: Project Creation 1. Navigate to org or repo Projects tab → Tab to the green "New project" button → Enter 2. Template modal opens → Arrow keys to browse template cards → Enter to select a template 3. Name field: type your project name 4. "Create project" button: Tab → Enter 5. You land on the new empty project Learning Cards: Creating a Project Screen reader users The "New project" button is on the Projects tab of any org or repo page — Tab to it and press Enter to open the template modal Template cards in the modal are navigable with arrow keys — each template announces its name and description; press Enter on your choice After creation, you land on an empty project — Tab to the "+ Add item" button at the bottom to start adding issues Low vision users The green "New project" button on the Projects tab is high-contrast and easy to spot even at high zoom Template cards in the creation modal are displayed as a grid — zoom in to read the titles and descriptions before selecting one After the project is created, the empty Table view has a "+ Add item" row at the bottom — it can scroll off screen at high zoom, so scroll down to find it Sighted users Navigate to the Projects tab on your org or repo page and click the green "New project" button in the upper right The template picker shows visual cards for common project types (blank table, blank board, feature release) — hover to preview each layout After creating, you land on an empty project with a prominent "+ Add item" prompt at the bottom of the table or board 3. The Three Layouts in Depth Table View The default layout. A spreadsheet-style grid where each row is an issue, PR, or draft item. Columns are fields (Title, Status, Assignee, Labels, Priority, custom fields you create). What it's best for: Bulk editing, sorting, filtering, seeing many items at once with their field values. Keyboard navigation T → Jump to table ↑/↓ → Move between rows ←/→ → Move between columns Enter → Open item detail panel (right sidebar) Escape → Close detail panel Space (on a cell) → Edit that cell's value F2 (on title cell) → Edit title inline Screen reader output per row "Fix keyboard trap in modal dialog | Status: In Progress | Assignee: alice | Priority: High | Labels: bug, accessibility" Board View Kanban-style columns. Each column represents a status value. Cards can be dragged be" + }, + { + "id": "admin/qa-bundle/docs/appendix-s-releases-tags-insights.html", + "title": "Appendix S: Releases, Tags, and Repository Insights", + "url": "admin/qa-bundle/docs/appendix-s-releases-tags-insights.html", + "body": "Appendix S: Releases, Tags, and Repository Insights Listen to Episode 25: Releases, Tags, and Insights - a conversational audio overview of this chapter. Listen before reading to preview the concepts, or after to reinforce what you learned. Reference companion to: Chapter 08: Open Source Culture Authoritative source: GitHub Docs: About releases Understanding Versioned Releases and Repository Activity Two things help you understand a repository's health and your place in it: releases (the versioned snapshots your contributions land in) and insights (the activity metrics that show how a project grows). This appendix covers both. Table of Contents Part 1 - Releases and Tags What Is a Release? Releases vs. Tags vs. Branches Navigating Releases on GitHub Understanding Version Numbers Reading Release Notes For Maintainers: Creating a Release Draft and Pre-Release States Accessibility Agents: /draft-release Part 2 - Repository Insights What Is the Insights Tab? Navigating to Insights Pulse - Recent Activity Summary Contributors - Who Builds the Project Traffic - Who Visits the Repo Commits and Code Frequency Dependency Graph Network and Forks Community Standards Screen Reader Navigation Reference Accessibility Agents: /my-stats and /team-dashboard Part 1 - Releases and Tags 1. What Is a Release? A release is a named snapshot of a repository at a specific point in history, packaged and published for users. For software projects, a release typically includes: A version number (e.g., v2.1.0 ) Release notes explaining what changed Links to download the compiled or packaged software (if applicable) Source code archives (automatically generated by GitHub) For documentation-only or non-software projects, releases are often used to mark stable checkpoints or versions of a document. When your PR gets merged: Your change becomes part of the code on the default branch. It will be included in the next release whenever the maintainer decides to publish one - this might be days, weeks, or months away depending on the project's release cadence. 2. Releases vs. Tags vs. Branches These three concepts are closely related: Concept What It Is Lives Branch A movable pointer to the latest commit on a line of work Permanently moves as commits are added Tag A fixed pointer to a single specific commit Never moves - always points to the same commit Release A tag + release notes + optional downloadable assets published on GitHub Based on a tag The relationship Every release is backed by a tag A tag without a release is just a version marker in the git history GitHub automatically creates a tag when you create a release 3. Navigating Releases on GitHub Finding the Releases Page From any repository page: Look on the right sidebar for a "Releases" section showing the latest release Activate "Releases" or the version link to go to the full releases page Alternatively: navigate to github.com/owner/repo/releases Screen reader path On the repository home page: → H or 3 to find "Releases" heading in the right sidebar → Tab to the latest release link → Enter → Or: Tab to "N Releases" count link → Enter → Opens full releases list The Releases List Page Each release appears as a section with: The release title (usually the version number) A badge: "Latest" (most recent stable), "Pre-release", or nothing (older release) Publication date The tag name Release notes (the main body) Asset downloads (if included) Source code download links (always present - auto-generated zip/tar.gz) Navigation 2 → Jump between release title headings K → Navigate links (download assets, compare, tag links) ↓ → Read release notes Learning Cards: Navigating Releases Screen reader users On the repository home page, press H or 3 to find the "Releases" heading in the right sidebar, then K to the version link — Enter opens the latest release directly On the Releases list page, each release is a heading — use 2 or 3 to jump between releases and arrow down to read the notes inline The "Latest" badge appears next to the most recent stable release — listen for it to distinguish stable releases from pre-releases or older versions Low vision users The Releases link on the repo home page sits in the right sidebar — at high zoom the sidebar may collapse below the main content; scroll down to find it Release notes use Markdown headings (Breaking Changes, New Features, Bug Fixes) — zoom in and scan the bold section labels for quick triage The green "Latest" badge next to the newest stable release is small — zoom to 150%+ to spot it among the release list entries Sighted users On the repository home page, look at the right sidebar for the Releases section showing the latest version number and a link to all releases On the Releases list page, each release card shows a title, date, tag, and a "Latest" badge on the most recent stable version Scroll through release notes to see categorize" + }, + { + "id": "admin/qa-bundle/docs/appendix-t-community-and-social.html", + "title": "Appendix T: Community and Social", + "url": "admin/qa-bundle/docs/appendix-t-community-and-social.html", + "body": "Appendix T: Community and Social Reference companion to: Chapter 08: Open Source Culture | Also relevant: Chapter 10 Authoritative source: GitHub Docs: About organizations | GitHub Docs: Sponsors This appendix consolidates three related reference topics: GitHub profiles, sponsors, and wikis (formerly Appendix R), GitHub organizations and templates (formerly Appendix S), and GitHub social features (formerly Appendix AE). GitHub Profiles, Sponsors, and Wikis Listen to Episode 35: Profile, Sponsors, and Wikis - a conversational audio overview of this chapter. Listen before reading to preview the concepts, or after to reinforce what you learned. Building Your Community Presence on GitHub This appendix covers three community-facing GitHub features: your profile README (how the world sees you), GitHub Sponsors (financially supporting the people whose work you depend on), and GitHub Wikis (community-editable documentation inside a repository). Learning Cards: Profiles, Sponsors, and Wikis Screen reader users Your profile README is announced as regular page content when someone visits your profile -- use ## headings for structure so visitors can navigate with H The Sponsor button on a profile or repo is a standard button element -- press B to cycle through buttons until you hear "Sponsor" Wiki pages are read in browse mode like any other GitHub Markdown page -- use heading navigation to jump between sections Low vision users Profile READMEs respect GitHub's dark and light themes -- test yours in both modes to confirm text remains readable The Sponsor button uses a heart icon with a pink/magenta accent -- look near the repo name or profile photo area Wiki sidebar navigation appears on the right side of the page with links to all wiki pages Sighted users Your profile README appears directly below your avatar and bio -- visitors see it immediately on your profile page The Sponsor heart icon is near the top of a profile or repository page, next to the Star and Watch buttons Wiki pages have an auto-generated sidebar listing all pages -- click any page title to navigate directly Profile Customization The Special Profile README GitHub has a hidden feature: if you create a repository named exactly your-username/your-username (e.g., janesmith/janesmith ), the README in that repo appears on your GitHub profile page. This is your profile README. It's a custom introduction visible to anyone who visits your profile. Creating Your Profile README Create a new repository Name it exactly your-username (match your GitHub username exactly, case-sensitive) Make it public Initialize with a README Edit the README with whatever you want to show on your profile What to include Introduction: Who you are, what you work on Current focus: What projects or technologies you're learning Skills: Languages, frameworks, tools (optional) How to reach you: Email, LinkedIn, personal site Fun facts: Hobbies, interests (optional-keeps it human) Example profile README # Hi, I'm Jane Smith I'm an accessibility advocate and open source contributor focused on making the web more inclusive. ## Current focus - Contributing to NVDA documentation - Building accessible React components - Learning TypeScript ## Skills - JavaScript, Python, HTML/CSS - Screen reader testing (NVDA, JAWS, VoiceOver) - Git, GitHub, GitHub Actions ## Get in touch - Email: jane@example.com - LinkedIn: [ linkedin.com/in/janesmith ]( https://linkedin.com/in/janesmith ) ## Fun fact I've been using screen readers for 8 years and believe accessible design is better design for everyone. Profile README Best Practices Keep it concise - visitors skim, not read Update occasionally - a README from 2019 looks stale Be authentic - people connect with real humans, not buzzwords Include links - make it easy to learn more or get in touch Avoid excessive badges - 50 skill badges is visual clutter and screen reader noise Skip auto-generated stats - "commits per day" widgets are often inaccessible Don't overthink it - a simple paragraph is better than nothing Screen Reader Considerations Use headings ( ## ) for structure Provide alt text for any images: ![Description of image](url) Avoid ASCII art - screen readers read it character by character (annoying) Test your README with a screen reader before publishing Other Profile Customizations Pinned repositories (up to 6) Highlight your best work on your profile Navigate to your profile → Select "Customize your pins" Choose which repos appear first Contribution graph Shows your GitHub activity over the past year Green squares indicate days with commits, PRs, issues, etc. Cannot be customized but reflects consistent contribution Status Set a temporary status message (e.g., "On vacation until March 15") Navigate to your profile → Select the smile icon → Set status GitHub Sponsors (Supporting Open Source) What Is GitHub Sponsors? GitHub Sponsors lets you financially support developers and pro" + }, + { + "id": "admin/qa-bundle/docs/appendix-u-discussions-and-gists.html", + "title": "Appendix U: Discussions and Gists", + "url": "admin/qa-bundle/docs/appendix-u-discussions-and-gists.html", + "body": "Appendix U: Discussions and Gists Reference companion to: Chapter 08: Open Source Culture | Also relevant: Chapter 10 Authoritative source: GitHub Docs: About discussions This appendix consolidates two related community content features: GitHub Discussions (formerly Appendix G) and GitHub Gists (formerly Appendix F). GitHub Discussions Listen to Episode 24: GitHub Discussions - a conversational audio overview of this chapter. Listen before reading to preview the concepts, or after to reinforce what you learned. Forum-Style Conversations Beyond Issues and Pull Requests GitHub Discussions is a built-in community forum for repositories and organizations. It's where open-ended conversations live - questions, ideas, announcements, polls, and community Q&A - separate from the action-oriented world of issues and pull requests. Support Hub Onboarding (Recommended For Workshop Alumni) For ongoing support after the workshop, use: Support hub home: Community-Access/support Q&A and community discussion: Support Hub Discussions Trackable support requests: Support Hub Issues Suggested first steps for students: Read the pinned Start Here resources in Discussions. Search existing discussions before opening a new support thread. Use issue templates for setup blockers or accessibility blockers so maintainers can help faster. Learning Cards: GitHub Discussions Screen reader users The Discussions tab is in the repository's main navigation bar alongside Code, Issues, and Pull Requests -- press T to navigate tab items or K to find the "Discussions" link Inside a discussion, replies are article elements -- in NVDA press A to jump between replies; in JAWS use A as well The reply editor uses the same behavior as issue comments -- enter Focus Mode to type, then press Ctrl+Enter to submit Low vision users Discussion categories appear as a sidebar panel on the left or right depending on viewport width -- look for the category list with item counts Answered discussions in the Q&A category display a green "Answered" badge next to the title, with the accepted answer pinned to the top Polls show percentage bars next to each option after you vote -- the bars use color fill to indicate proportion Sighted users Discussions are organized by category with colored labels -- the sidebar shows all categories and pinned items In Q&A threads, look for the green checkmark on the accepted answer pinned above the regular reply timeline Use the upvote button (thumbs up) on replies instead of posting "+1" comments -- maintainers often sort by upvotes Table of Contents Discussions vs. Issues: When to Use Which Navigating to Discussions Discussion Categories Creating a Discussion Participating in Discussions Marking an Answer Polls Screen Reader Navigation Reference Organization-Level Discussions Accessibility Agents: What's Different Here 1. Discussions vs. Issues: When to Use Which Not every conversation belongs in an issue. GitHub Discussions exists for the conversations that don't fit: Use Issues When Use Discussions When You found a bug You have a question about how something works You want to request a specific feature You want to brainstorm ideas before filing a feature request There is actionable work to be done You want community input before deciding what work to do You need to track progress (labels, assign, close) You want to have an open conversation without resolving it The answer is "fixed" or "won't fix" The conversation might not have one right answer The signal for maintainers: A question in an issue is noisier - it implies something needs to be done. The same question in Discussions doesn't trigger workflow automation and doesn't inflate the issue count. Common Discussions categories you'll encounter Q&A - Support questions and answers (one answer can be marked correct) Ideas - Feature brainstorming before a formal feature request Announcements - Maintainer posts about releases, breaking changes, roadmaps General - Everything else Show and Tell - Community members showing what they built 2. Navigating to Discussions From a Repository Navigate to the repository There is a Discussions tab in the main navigation (alongside Code, Issues, Pull Requests, Actions, Projects) Press T to navigate tab items, or K to navigate links and find "Discussions" Press Enter to open If the tab is missing: Discussions is an opt-in feature. The repository maintainer must enable it in Settings. Not all repositories use it. From an Organization Large organizations can have organization-level Discussions separate from any individual repository: Navigate to the organization page Look for the Discussions tab at the organization level These are community-wide conversations, not repo-specific 3. Discussion Categories The Discussions home page is organized by category. Each category is a section with its own heading. Navigating categories 3 →" + }, + { + "id": "admin/qa-bundle/docs/appendix-v-github-mobile.html", + "title": "Appendix V: GitHub Mobile", + "url": "admin/qa-bundle/docs/appendix-v-github-mobile.html", + "body": "Appendix V: GitHub Mobile Listen to Episode 32: GitHub Mobile - a conversational audio overview of this chapter. Listen before reading to preview the concepts, or after to reinforce what you learned. Reference companion to: Chapter 05: Working with Issues | Also relevant: Chapter 10 Authoritative source: GitHub Docs: GitHub Mobile Accessibility Guide for iOS and Android GitHub Mobile brings issues, pull requests, notifications, and code review to your iPhone, iPad, or Android device. This appendix covers setup, VoiceOver and TalkBack usage, and the tasks best suited to mobile. Learning Cards: GitHub Mobile Overview Screen reader users GitHub Mobile supports VoiceOver (iOS) and TalkBack (Android) natively -- swipe right to move through elements, double-tap to activate The app uses five bottom tabs (Home, Notifications, Explore, Pull Requests, Profile) -- swipe left or right along the bottom tab bar to switch between them Use the VoiceOver Rotor (two-finger twist) set to Headings to jump between sections within an issue or PR description Low vision users GitHub Mobile supports dynamic text sizing on both iOS and Android -- increase your system font size and the app respects it Dark mode is available in the app settings and follows your system preference -- use it to reduce glare on OLED screens The simplified diff view in Files Changed shows additions and removals as text only, without the two-column table layout used on desktop Sighted users The five-tab navigation bar at the bottom of the screen (Home, Notifications, Explore, Pull Requests, Profile) is your primary way around the app Notification badges appear as red dots on the Notifications tab -- swipe left on individual notifications for quick actions (read, archive, unsubscribe) Pull request diffs use a simplified single-column view optimized for small screens -- additions appear in green, removals in red Table of Contents Installing GitHub Mobile Getting Around the App VoiceOver on iOS TalkBack on Android Working with Notifications Reviewing Pull Requests Working with Issues What Mobile Does Well vs. Desktop Common Issues and Workarounds 1. Installing GitHub Mobile Platform Download iOS (iPhone / iPad) App Store - GitHub Android Google Play - GitHub After installing, sign in with your GitHub account. Enable notifications when prompted - these are essential for staying on top of PR reviews and issue activity without constantly checking the web. 2. Getting Around the App GitHub Mobile is organized into five main tabs at the bottom of the screen: Tab Contents Home Personalized feed of activity across your repositories Notifications All @mentions, review requests, issue updates Explore Discover repositories and trending projects Pull Requests PRs assigned to you, created by you, or awaiting your review Profile Your profile, repositories, stars, and settings Navigate between tabs with a single tap (or swipe on iOS with VoiceOver active). 3. VoiceOver on iOS Enabling VoiceOver Triple-click the side button (iPhone X and later) or triple-click the Home button to toggle VoiceOver Or: Settings → Accessibility → VoiceOver → toggle on Basic Gestures in GitHub Mobile Gesture Action Swipe right Move to the next element Swipe left Move to the previous element Double tap Activate the focused element Two-finger swipe up Read from the top Two-finger tap Pause/resume speech Three-finger swipe left/right Move between screens Scrub (two-finger Z motion) Go back Rotor in GitHub Mobile Open the Rotor by rotating two fingers on the screen as if turning a dial. Useful rotor settings for GitHub Mobile: Headings - jump between section headings on an issue or PR description Links - navigate to linked issues, commits, or external URLs Form Controls - jump to input fields when writing a comment Actions - available actions for the focused element (assign, label, close) Writing Comments with VoiceOver Navigate to the comment field (swipe to it or use Rotor → Form Controls) Double tap to activate and open the keyboard Type your comment; VoiceOver announces each character When done, swipe to the Comment button and double tap to submit 4. TalkBack on Android Enabling TalkBack Settings → Accessibility → TalkBack → toggle on Or: hold both volume keys for three seconds (if the shortcut is enabled) Basic Gestures in GitHub Mobile Gesture Action Swipe right Move to next element Swipe left Move to previous element Double tap Activate the focused element Swipe up then down Scroll down Swipe down then up Scroll up Swipe right then left Go back Two-finger swipe down Read from top TalkBack Menu Tap with three fingers (or swipe down then right) to open the TalkBack menu. From here you can: Change the reading granularity (character, word, line, paragraph) Activate reading controls Copy text Writing Comments with TalkBack Locate the comment field - TalkBack announces "Edit text, double tap to edit" Double tap to enter the field Use the on-screen keyboard or dictation to type Locate the Co" + }, + { + "id": "admin/qa-bundle/docs/appendix-w-github-pages.html", + "title": "Appendix W: Publishing with GitHub Pages", + "url": "admin/qa-bundle/docs/appendix-w-github-pages.html", + "body": "Appendix W: Publishing with GitHub Pages Listen to Episode 33: Publishing with GitHub Pages - a conversational audio overview of this chapter. Listen before reading to preview the concepts, or after to reinforce what you learned. Reference companion to: Chapter 08: Open Source Culture | Also relevant: Chapter 21 Authoritative source: GitHub Docs: About Pages How to Deploy a Static Website Directly from Your Repository GitHub Pages lets you publish a static website straight from a GitHub repository - no server, no hosting bill, no deployment pipeline required for simple sites. This appendix explains how to enable it, what it can publish, and how to ensure the published site meets the same accessibility standards as your source code. Learning Cards: GitHub Pages Overview Screen reader users The Pages settings are under Settings (gear icon in repository navigation) then "Pages" in the left sidebar under the "Code and automation" group heading Branch and folder selectors in the Pages settings are standard select elements -- navigate with arrow keys to choose your publishing source After deployment, the published URL appears as a link at the top of the Pages settings page Low vision users GitHub Pages settings use the same layout as other repository settings -- look for the "Pages" link in the left sidebar after clicking Settings The deployment status indicator shows a green checkmark for successful deployments and a red X for failures Published sites inherit no special styling from GitHub -- ensure your site's CSS provides adequate contrast and font sizing Sighted users Find Pages settings via the repository's Settings tab, then "Pages" in the left sidebar under "Code and automation" The publishing source selector lets you choose a branch and folder ( / root or /docs ) -- select your combination and click Save After a successful deployment, a green banner with your site URL appears at the top of the Pages settings Table of Contents What GitHub Pages Is Enabling GitHub Pages for a Repository Publishing Sources The html/ Folder in This Project Custom Domains HTTPS and Security Accessibility Considerations for Published Sites GitHub Actions and Continuous Deployment Limitations Troubleshooting 1. What GitHub Pages Is GitHub Pages is a static site hosting service built into GitHub. It serves files directly from a branch or folder in your repository at a URL of the form: https://<username>.github.io/<repository-name>/ For organization accounts and user profile repositories ( <username>/<username>.github.io ), the URL becomes: https://<username>.github.io/ What "static" means: GitHub Pages only serves files as-is - HTML, CSS, JavaScript, images, PDFs. It does not run server-side code (no PHP, no Python, no Node.js request handlers). If you need a database or dynamic server logic, you need a different host. What it is good for Documentation sites Workshop materials (like this project) Project landing pages Personal portfolios Simple blogs via Jekyll 2. Enabling GitHub Pages for a Repository Step-by-step (GitHub.com) Go to the repository on GitHub.com Click Settings (the gear icon in the top navigation) In the left sidebar, scroll to Code and automation and click Pages Under Build and deployment , choose your publishing source: Deploy from a branch - serve files directly from a branch/folder GitHub Actions - use a workflow to build and deploy If using "Deploy from a branch": Select the branch (e.g. main or master ) Select the folder: / (root) or /docs Click Save GitHub will build and deploy within a minute or two. The URL appears at the top of the Pages settings once the first deployment succeeds. Screen reader navigation for the Pages settings page The Settings tab is a link in the repository's top navigation bar. It has the accessible name "Settings" The Pages option in the left sidebar is a link under the "Code and automation" group heading The branch and folder dropdowns are standard <select> elements - navigate with arrow keys 3. Publishing Sources Deploy from a branch The simplest option. GitHub reads files directly from a branch. Folder option What it serves / (root) Serves the entire repository root /docs Serves only the docs/ folder - useful when your repository also contains source code Best practice: Use /docs to isolate the published content from source files, especially for projects with build pipelines where the output lives in a specific folder. GitHub Actions Use a workflow (YAML file in .github/workflows/ ) to build your site before publishing. This is required when: Your source is Markdown and you need a build step (e.g. this project's scripts/build-html.js ) You are using a static site generator like Jekyll, Hugo, or Eleventy You want to run accessibility tests in CI before publishing A basic workflow for this project would: Check out the repository Run node sc" + }, + { + "id": "admin/qa-bundle/docs/appendix-x-resources.html", + "title": "Appendix X: Resources", + "url": "admin/qa-bundle/docs/appendix-x-resources.html", + "body": "Appendix X: Resources Listen to Episode 38: Resources and Links - a conversational audio overview of this chapter. Listen before reading to preview the concepts, or after to reinforce what you learned. Reference companion to: All chapters | Master resource index for the entire curriculum Everything You Need - Before, During, and After the Workshop This is your permanent reference. Every link, tool, guide, and community resource from the two-day workshop in one place. Bookmark this page in your fork so it travels with you. Learning Cards: Navigating This Resource Guide Screen reader users This appendix is organized as 16 numbered sections with heading levels -- press H or 2 to jump between major sections in browse mode Most sections contain tables of links -- navigate tables with T to jump to the next table, then use arrow keys to read rows and columns Each resource link opens in the same tab by default -- use Ctrl+Enter (Windows) to open in a new tab and keep this reference page available Low vision users Tables in this appendix have a Resource/URL/Notes column structure -- widen your browser or zoom out slightly if columns overlap at high magnification Link text is descriptive (resource names, not raw URLs) making it easier to scan the page visually Bookmark this page in your browser for quick access -- it is the single-page reference for everything from the workshop Sighted users Use the Table of Contents at the top to jump directly to any of the 16 resource categories Each section uses a consistent table layout: Resource name (left), URL (middle), Notes (right) The GitHub keyboard shortcuts section (14) is worth bookmarking separately -- press ? on any GitHub page for a shortcuts overlay Table of Contents The Central Project - Accessibility Agents GitHub Accessibility Guides GitHub Skills Learning Modules Screen Reader Downloads and Documentation VS Code Resources GitHub Copilot Resources GitHub Agentic Workflows Spec-Driven Development - Spec Kit GitHub CLI, Desktop, and Copilot CLI GitHub Mobile Apps GitHub Best Practices and Power Features Finding More Contributions Accessibility Standards and References GitHub Keyboard Shortcuts Community and Support Your Workshop Documentation - Offline Reference 1. The Central Project - Accessibility Agents The project you forked, contributed to, and carry home. Resource URL Notes Accessibility Agents - Main Repo github.com/community-access/accessibility-agents The upstream - your contributions go here Getting Started Guide accessibility-agents/Documentation/GETTING-STARTED.md Your first hour with the agents Full Reference Guide accessibility-agents/Documentation/GUIDE.md Complete agent and command reference Setup Guide accessibility-agents/SETUP.md Configuration and preferences Contributing Guide accessibility-agents/CONTRIBUTING.md How to submit improvements Security Policy accessibility-agents/SECURITY.md Responsible disclosure instructions MIT License accessibility-agents/LICENSE Fork it, use it, make it yours Your Personal Fork After the workshop, your fork lives at: https://github.com/[your-username]/accessibility-agents Quick access from VS Code Clone your fork: git clone https://github.com/[your-username]/accessibility-agents.git Open in VS Code: cd accessibility-agents && code . Open Copilot Chat: Ctrl+Shift+I Type: @daily-briefing morning briefing Personalizing Your Fork Copy preferences.example.md to preferences.md in .github/agents/ Add your GitHub username, your most-used repositories, and your preferred output format Commit the file - now the agents know who you are and what you work on 2. GitHub Accessibility Guides Official guides from the GitHub Accessibility team. These were the primary research sources for this workshop's documentation. Guide URL When to Use GitHub Repos - Screen Reader Guide accessibility.github.com/documentation/guide/repos Navigating repositories, file trees, branches GitHub Issues - Screen Reader Guide accessibility.github.com/documentation/guide/issues Filing, reading, commenting on issues GitHub Pull Requests - Screen Reader Guide accessibility.github.com/documentation/guide/pull-requests Reading diffs, reviewing, merging GitHub Copilot in VS Code - Screen Reader Guide accessibility.github.com/documentation/guide/github-copilot-vsc Using Copilot with NVDA, JAWS, VoiceOver Custom Instructions - Screen Reader Guide accessibility.github.com/documentation/guide/custom-instructions Configuring Copilot's behavior for your workflow Getting Started with Custom Agents for Accessibility accessibility.github.com/documentation/guide/getting-started-with-agents What agents are, custom agents vs custom instructions, informational vs task-oriented agents, step-by-step walkthroughs for building both types Accessibility Settings Overview docs.github.com/en/get-started/accessibility Hovercard settings, motion reduction, color modes 3. GitHub Skills Learning Modules GitHub Skills is GitHub's free, self-paced interactive le" + }, + { + "id": "admin/qa-bundle/docs/appendix-y-workshop-materials.html", + "title": "Appendix Y: Accessing and Downloading Workshop Materials", + "url": "admin/qa-bundle/docs/appendix-y-workshop-materials.html", + "body": "Appendix Y: Accessing and Downloading Workshop Materials Listen to Episode 42: Accessing Workshop Materials - a conversational audio overview of this chapter. Listen before reading to preview the concepts, or after to reinforce what you learned. Reference companion to: Chapter 00: Pre-Workshop Setup Authoritative source: Community-Access/git-going-with-github How to Get, Read, and Keep These Documents Why this appendix exists: The workshop content is available in multiple formats - Markdown source files, pre-built HTML pages, and a live GitHub Pages site. This guide explains how to access each format, download materials for offline use, and keep your copy up to date. Learning Cards: Accessing Workshop Materials Screen reader users The GitHub Pages site includes skip-to-content links and ARIA landmarks -- press D (NVDA) or R (JAWS) to jump to the main content landmark on any page On GitHub.com, press T on the repository's main page to open the file finder -- type any filename to jump directly to it without navigating the file tree After cloning the repository, open it in VS Code and use the Explorer panel ( Ctrl+Shift+E ) to browse the file tree with arrow keys Low vision users The HTML version in the html/ folder provides the most polished reading experience with styled, navigable pages that work offline in any browser For reading Markdown source files, use VS Code's built-in preview ( Ctrl+Shift+V ) which renders headings, links, and code blocks in a formatted view When downloading a ZIP from GitHub, the Code button and its dropdown appear near the top of the repository page -- look for the green button Sighted users Three ways to access materials: GitHub Pages site (online, styled), GitHub.com (browse rendered Markdown), or local clone (offline, editable) The repository's docs/ folder contains all Markdown source files; the html/ folder contains pre-built HTML versions of every page Use git clone for a full copy you can update with git pull -- ZIP downloads are snapshots that do not update automatically Table of Contents Browsing Online (GitHub Pages) Reading on GitHub.com Downloading Everything Downloading Individual Files What's in Each Folder Offline Reading Keeping Your Copy Updated Which Format Should I Use? 1. Browsing Online (GitHub Pages) If the facilitator has enabled GitHub Pages for this repository, the workshop materials are available as a website at a URL like: https://<organization>.github.io/Learning-Room/ Your facilitator will share the exact URL. Once you have it: Open the URL in your browser The landing page ( index.html ) is the workshop homepage - equivalent to the README Use headings ( H key in NVDA/JAWS browse mode) to navigate within any page All internal links between chapters and appendices work - click any cross-reference to go directly to that page Bookmark the URL for quick access during the workshop Screen reader tip: The HTML pages include skip-to-content links, breadcrumb navigation, and ARIA landmarks. Press D (NVDA) or R (JAWS) to jump to the main landmark on any page. For details on how GitHub Pages works, see Appendix P - Publishing with GitHub Pages . 2. Reading on GitHub.com You can read every file directly on GitHub.com without downloading anything: Go to the repository page (your facilitator will share the link) The README renders automatically as the repository homepage Click into the docs/ folder to see all chapters and appendices Click any .md file - GitHub renders it as formatted text with headings, links, and code blocks Navigating the repository with a screen reader File list: The repository file listing is a grid. Use T to jump to the file table, then arrow keys to navigate rows File content: Once inside a file, GitHub renders the Markdown. Use H to navigate headings Breadcrumbs: At the top of each file view, breadcrumb links show the path (e.g., Learning-Room / docs / 06-working-with-pull-requests.md ). Use these to navigate back Go to File shortcut: Press T on the repository's main page to open the file finder - type any filename to jump to it 3. Downloading Everything Option A: Clone with Git (recommended) Cloning gives you a full copy of the repository that you can update later with git pull : # Clone the repository git clone https://github.com/community-access/git-going-with-github.git # Move into the folder cd Learning-Room After cloning, every file (Markdown source, HTML output, scripts, learning-room materials) is on your computer. Screen reader tip: After cloning, open the folder in VS Code ( code . ) and use the Explorer panel ( Ctrl+Shift+E ) to browse the file tree. Press Enter on any file to open it in the editor. Option B: Download ZIP (no Git required) If you do not have Git installed or prefer not to use the command line: Go to the repository page on GitHub.com Press T to find the file finder, or navigate to the green Code button (it is a dropdown button near the top of the file listing) Activate the Code button - a dr" + }, + { + "id": "admin/qa-bundle/docs/appendix-z-github-skills.html", + "title": "Appendix Z: GitHub Skills - Complete Course Catalog", + "url": "admin/qa-bundle/docs/appendix-z-github-skills.html", + "body": "Appendix Z: GitHub Skills - Complete Course Catalog Listen to Episode 43: GitHub Skills - Complete Course Catalog - a conversational audio overview of this chapter. Listen before reading to preview the concepts, or after to reinforce what you learned. Reference companion to: Chapter 00: Pre-Workshop Setup | Also relevant: Chapter 21 Authoritative source: GitHub Skills GitHub Skills is GitHub's free, self-paced interactive learning platform. Every course runs entirely inside GitHub - no external site, no separate login, no video. You copy a course repository to your own account, and an automated bot named Mona teaches you through real issues and pull requests. This appendix catalogs every available GitHub Skills module, organized into learning paths that build on the skills you practiced in this workshop. Use it as a roadmap for continued learning after Day 2. Learning Cards: How GitHub Skills Works Screen reader users Every GitHub Skills course runs inside a standard GitHub repository -- the screen reader navigation skills from this workshop (heading nav, issue reading, PR workflows) apply directly After copying a course with "Use this template," navigate to the Issues tab ( G then I ) and press H or 3 to find "Step 1:" -- this is where Mona's first lesson appears Mona posts feedback as issue comments -- press 9 (NVDA/JAWS) to jump to the comments section and read her instructions Low vision users Course content appears as standard GitHub issues and comments -- your existing GitHub theme and font size settings apply automatically Mona's step numbers appear as issue titles with "Step 1:", "Step 2:" prefixes -- scan the Issues list for these numbered titles to track your progress Course completion is indicated when Mona closes the final issue with a success message -- look for the purple "Closed" badge Sighted users Start any course by clicking "Start course" on the module page, then "Use this template" then "Create a new repository" -- Mona activates within 20 seconds Each step appears as a new issue or comment in your copied repository -- follow the instructions, complete the task, and Mona advances you automatically Track progress by watching the Issues tab -- open issues are pending steps, closed issues are completed steps How GitHub Skills Works Each course follows the same pattern: Navigate to the course URL and select "Start course" GitHub copies the course repository to your account Mona (GitHub's automated learning bot) opens an issue with Step 1 instructions within 20 seconds You complete the task described in the issue (create a branch, edit a file, open a PR) Mona detects your action, validates it, and posts the next step as a comment or new issue Repeat until Mona closes the final issue with a completion message All interaction happens through GitHub's standard interface. The screen reader navigation skills from this workshop - heading navigation, landmark jumping, issue and PR workflows - apply directly. For detailed screen reader navigation instructions, see Appendix U Section 3 (GitHub Skills) . Courses Used in This Workshop These three modules are integrated into the Day 1 agenda. You complete them during the workshop with facilitator guidance. The following table lists the three GitHub Skills modules used during Day 1, with their workshop block and what each teaches. Module Workshop Block What Mona Teaches Link Introduction to GitHub Day 1, Blocks 1-3 Branches, commits, pull requests, merge Start course Communicate Using Markdown Day 1, Block 3 Headings, emphasis, links, code blocks, task lists, tables Start course Review Pull Requests Day 1, Block 4 Assign reviewers, leave comments, suggest changes, approve, merge Start course If you did not finish these during the workshop, complete them first before moving to the paths below. Learning Paths The remaining courses are organized into six learning paths. Each path builds on skills from this workshop and progresses from introductory to advanced. You do not need to complete every path - choose the ones that match your goals. Learning Cards: Navigating Learning Paths Screen reader users The six learning paths below are organized as H3 headings with tables listing courses in recommended order -- press 3 to jump between paths, then T to enter each course table Each course link is in the rightmost "Link" column of the table -- navigate to it with arrow keys after entering the table Use the Personal Completion Checklist at the bottom of this appendix as a progress tracker -- copy it into a GitHub issue or personal notes file Low vision users Each learning path table has columns for Order, Module, Duration, Prerequisite, What You Learn, and Link -- widen your browser if columns appear truncated at high zoom Course durations range from 30 minutes to 2 hours -- the Duration column helps you plan which courses fit your available time T" + }, + { + "id": "admin/qa-bundle/docs/course-guide.html", + "title": "Course Guide", + "url": "admin/qa-bundle/docs/course-guide.html", + "body": "Course Guide Listen to Episode 0: Welcome to Git Going with GitHub - a conversational audio overview of this chapter. Listen before reading to preview the concepts, or after to reinforce what you learned. GitHub Learning Room - Your Complete Workshop Companion Welcome. You are about to begin a two-day journey into open source collaboration using GitHub, VS Code, and GitHub Copilot - all designed for screen reader and keyboard-only navigation. This guide is your starting point and table of contents for everything in this workshop. Note: Workshop content is being actively refined for the May 2026 cohort. Students should expect updates to materials leading up to and during the course. How This Course Works This is a two-day workshop built around one idea: you will make real contributions to a real open source project. Not simulated. Not pretend. Real. Live Agenda and Self-Paced Curriculum The live hackathon agenda is intentionally smaller than the full curriculum. Live sessions prioritize the core contribution path, while the complete chapter set remains available for self-paced preparation, catch-up, remote participation, and post-event continuation. Live core: The facilitator chooses the minimum path needed for participants to make and understand a real contribution. Async follow-up: Chapters and challenges not covered live can be completed after the session using the Learning Room, solutions, podcasts, and Slack channel. Remote participation: Remote cohorts should use the same checkpoints and evidence prompts, with written instructions available before each live block. The Two Days Day 1 - GitHub Foundations (Browser) You learn GitHub's web interface using only your keyboard and screen reader. The live Day 1 core path gets you through repository navigation, issues, branches, commits, and a first pull request. Review practice, merge conflicts, labels, notifications, and culture exercises remain available as stretch or async follow-up. Day 2 - VS Code + Accessibility Agents (Desktop) You move to Visual Studio Code, learn GitHub Copilot, and activate the Accessibility Agents ecosystem - 55 AI agents across 3 teams and 5 platforms that amplify every skill you built on Day 1. The live Day 2 core path prepares you to make a real contribution, and the async continuation path gives you time to polish and submit it well. The Journey Arc Day 1 - Learn the skill in the browser Navigate → Issue → Pull Request → Review → Merge ↓ (bridge: press . on any GitHub repo - VS Code opens in your browser) github.dev - VS Code on the web, no install needed Same keyboard shortcuts · Same screen reader mode · Edit files · Open PRs ↓ (you've earned the desktop - now it makes sense) Day 2 - Deepen with VS Code + Accessibility Agents VS Code basics → Copilot inline → Copilot Chat @daily-briefing → @issue-tracker → @pr-review → @analytics → prepare upstream The key principle: Learn the manual skill first, then see how it is automated. The agents only make sense when you already understand what they are doing. Before You Begin Start with Get Going with GitHub if you want the most guided path. It explains how GitHub Classroom creates your private Learning Room repository, how Challenge 1 appears, how evidence prompts work, and how to choose between browser, github.dev, VS Code, GitHub Desktop, and command-line paths. Complete everything in Chapter 00: Pre-Workshop Setup before Day 1. This chapter walks you through: Creating a GitHub account Installing Git Setting up VS Code (optional for Day 1, required for Day 2) Configuring your screen reader for GitHub Verifying everything works Time needed: About 30 minutes. Companion Audio Series Every chapter and appendix has a companion podcast episode - a conversational two-host overview that previews or reviews the key concepts. Listen before reading a chapter to know what to expect, or after to reinforce what you learned. Browse the podcast episodes with HTML5 audio players Subscribe via RSS in your preferred podcast app Episodes are 8-18 minutes each - perfect for commutes, walks, or screen reader breaks Day 1: GitHub Foundations These chapters are designed to be read and practiced in order. Each builds on the one before it. # Chapter What You Will Learn Time Start Get Going with GitHub GitHub Classroom onboarding, Learning Room first steps, support, and tool choice 15 min 00 Pre-Workshop Setup Install and configure everything before Day 1 30 min 01 Choose Your Adventure: A Tool Tour Explore the 5 tool environments before you start 30 min 02 Understanding GitHub's Web Structure How GitHub is organized - page types, headings, landmarks, screen reader orientation 1 hr 03 Navigating Repositories Explore any repo using your screen reader - tabs, files, commits, branches 45 min 04 The Learning Room Your shared practice environment - challenges, PR workflow, bot feedback, peer review 30 min 05 Working with Issues File, search, filter, comment on, and manage issues 1 hr 06 Working with P" + }, + { + "id": "admin/qa-bundle/learning-room/index.html", + "title": "Welcome to the Learning Room", + "url": "admin/qa-bundle/learning-room/index.html", + "body": "Welcome to the Learning Room This repository is your private Learning Room for the Git Going with GitHub workshop. GitHub Classroom created it from the Learning Room template so you can practice the full contribution workflow safely. In this repository you will: File your first issue Leave your first comment Open your first pull request Review a peer's pull request when facilitators pair you for review Everything in this repository is designed for learning. The files in docs/ have intentional issues that you will find and fix during the workshop contribution sprint. What Is in This Repository Folder / File Purpose docs/welcome.md Introduction to contributing (has some sections to complete) docs/keyboard-shortcuts.md Keyboard shortcut reference (has some errors to find and fix) docs/setup-guide.md Setup instructions (has some broken links and gaps) How to Contribute Open the canonical challenge list: ../docs/CHALLENGES.md Find your assigned issue (Issues tab -> filter by "Assignee: me" or search your username in the issue title) Claim the issue with a comment: I'd like to try this! Read the issue description - it tells you which file to edit and what to fix Click the file -> the edit pencil button -> make your change Commit to a new branch with a descriptive name: fix/[your-name]-[issue-number] Open a pull request using the PR template and include Closes #XX Wait for the bot (~30 seconds) - it will check your changes and provide feedback Read bot feedback carefully - it explains any issues and links to resources Make changes if needed based on feedback Request a review from your assigned peer reviewer Respond to review feedback and make final improvements Merge when approved (the issue closes automatically) Add a final issue comment with what you learned and your merged PR link See the workshop documentation for full step-by-step guidance. About the Automation Bot When you open a pull request, an automated bot will: Check your changes against quality standards Validate accessibility (heading hierarchy, link text, alt text, broken links) Provide educational feedback explaining why things matter Link to resources for learning more Apply labels to help facilitators prioritize reviews The bot is not a substitute for peer review! It provides instant technical feedback so your human reviewers can focus on higher-level improvements, creative suggestions, and encouragement. How to Interact with the Bot Reading Bot Comments: Bot posts ONE comment that updates as you make changes Use headings to navigate (Required Checks, Suggestions, Accessibility Analysis, Resources) Each issue includes file/line numbers and how to fix it Getting Help from the Bot: Comment on your PR with keywords: @bot help - Get help information Mention "merge conflict" - Get conflict resolution guide Mention "request review" - Get instructions for requesting human review When You Disagree: The bot isn't always right! If you believe feedback is incorrect: Comment explaining your reasoning Request human review Facilitators can override bot checks Read the Student Guide → Skills & Progression As you complete challenges, you'll: Track progress through skill levels (Explorer, Contributor, Collaborator, Operator, Reviewer, Agent Navigator) Unlock new challenges when you reach milestones Earn badges for specific achievements (Branch Builder, PR Pioneer, Conflict Resolver, and more) Celebrate milestones (first challenge, Day 1 complete, all challenges complete) View Available Challenges → Follow the Full Course Roadmap → Stuck? Use Guided References Solutions Index - challenge-by-challenge worked examples Challenge Hub bonus challenges - optional advanced practice adapted from GitHub Skills Use these references after you attempt the challenge yourself. They are designed to unblock you, not replace your own practice. Study Groups You may be assigned to a study group for collaborative learning. Groups: Work through challenges together Review each other's PRs Share resources and tips Support each other's learning If assigned to a group, you'll receive an issue thread for communication. Code of Conduct All participants and contributors are expected to follow our Code of Conduct . This is a welcoming, accessible space. Questions? Open an issue! Use the "Feature or Improvement Request" template if you have a suggestion, or the "Accessibility Bug Report" template if you find an accessibility issue." + }, + { + "id": "admin/qa-bundle/index.html", + "title": "QA Bundle (Grab-and-Go)", + "url": "admin/qa-bundle/index.html", + "body": "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 admin/LEARNING-ROOM-E2E-QA-RUNBOOK.md GO-LIVE-QA-GUIDE.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 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." + }, + { + "id": "admin/SUPPORT_HUB_OPERATIONS.html", + "title": "Support Hub Operations", + "url": "admin/SUPPORT_HUB_OPERATIONS.html", + "body": "Support Hub Operations This guide defines how we run the open, post-workshop support repository for GIT Going with GitHub. Canonical Support Repository Repository name: Community-Access/support Repository URL: https://github.com/Community-Access/support Repository visibility: Public Primary purpose: post-workshop support, async Q&A, troubleshooting, and alumni collaboration This repository does not replace curriculum source repositories. It routes support traffic away from curriculum maintenance and keeps student support visible and searchable. Student Onboarding Model (Rich Path) Use this onboarding flow for every new cohort: Share Support Hub URL in registration confirmation and Day 2 close-out. Ask students to read pinned Start Here content in Discussions. Ask students to post one introduction in Discussions and one support request using templates if blocked. Point students to labels and categories so they can self-route requests. Onboarding success criteria: Students can explain the difference between support issues and discussions. Students can open a support issue with reproducible steps. Students can find and follow a resolved discussion thread. What Belongs In Support Hub Use Support Hub for: Student setup and access questions Post-workshop troubleshooting questions Accessibility workflow questions Alumni sharing and follow-up help Requests for clarification in workshop docs Do not use Support Hub for: Direct edits to workshop curriculum content Template workflow code changes Security disclosures Routing: Curriculum and content changes: https://github.com/Community-Access/git-going-with-github Learning Room template changes: https://github.com/Community-Access/learning-room-template Security reports: follow ../SECURITY.md Recommended Support Taxonomy Discussions categories Q&A Troubleshooting Success Stories Announcements Office Hours Labels needs-triage setup classroom accessibility copilot resolved escalated Response Standards First response target: 24 to 48 hours Triage cadence during active cohorts: daily Triage cadence off-cycle: 3 times per week Moderator Playbook Acknowledge the question and restate the goal. Provide one clear next action. Link to the exact workshop doc section when relevant. Ask for diagnostics only if needed. Mark resolved when the user confirms or the path is complete. Privacy And Safety Rules Do not request personal data in public issues/discussions. Never ask users to post tokens, secrets, or private repository URLs publicly. For sensitive account problems, move to private facilitator contact. Integration Checklist REGISTER.md and registration workflow comments point to Support Hub. Facilitator guides reference Support Hub as the alumni channel. docs/21-next-steps.md points learners to Support Hub. Go-live checklist includes Support Hub readiness. Podcast scripts/transcripts reference Support Hub as the default help path. Reset And Rebuild (From Scratch) If the support environment drifts or needs a hard reset, run: scripts/classroom/ Reset-SupportHubEnvironment .ps1 This script re-applies repository baseline setup: Repository existence and visibility Issues and Discussions enabled Support label taxonomy Baseline support files and bot workflows" }, { "id": "COMING_SOON.html", @@ -801,13 +1377,13 @@ "id": "CONTRIBUTING.html", "title": "Contributing to This Workshop Repository", "url": "CONTRIBUTING.html", - "body": "Contributing to This Workshop Repository Thank you for helping improve this workshop. Whether you are a participant who found a typo, someone who wants to add a new exercise, or an educator adapting these materials for your own community - your contribution is meaningful and welcome. This guide covers contributing to this workshop learning repository . For contributing to Accessibility Agents itself (the project you work on during Day 2), see Accessibility Agents' CONTRIBUTING.md . Table of Contents Who This Is For What Kinds of Contributions Are Welcome Before You Start - Fork and Clone Contribution Workflow - Step by Step Writing and Style Guidelines Accessibility Requirements HTML Documentation Build System Screen Reader Guidance for Commands in This Document Submitting Your Pull Request What Happens After You Submit Questions and Discussion 1. Who This Is For Workshop participants: You have already completed the contribution workflow during the workshop. This repository is an excellent first contribution target for applying what you practiced. Educators and facilitators: You are welcome to fork the entire repository and adapt the materials for your own workshop program. Attribution is required under the CC BY 4.0 license - please include a credit line and link to the original repository. Accessibility practitioners: If you have domain expertise in a particular screen reader or assistive technology and notice something that is incorrect or incomplete, please open an issue or submit a correction. Your expertise is exactly what this documentation needs. People who find bugs: A broken link, a command that has stopped working, an exercise that cannot be completed - all of these are legitimate bugs. Open an issue the same way you would for any software project. 2. What Kinds of Contributions Are Welcome Documentation Improvements Corrections: Wrong keyboard shortcut, screen reader command that has changed, broken external link, outdated UI description Clarity: A step that was confusing, an assumption that left someone behind, a paragraph that should be two Gaps: A common question that the documentation does not answer, an exercise step that was skipped New content: An additional exercise, a section about a tool or workflow not yet covered, a translation Issues and Bug Reports A command in the workshop exercises that does not work as described A screen reader behavior that differs from what the documentation says A broken link or missing image An exercise that assumes knowledge introduced later in the workshop Workshop Materials New exercises that reinforce a concept Facilitator notes based on running a session Timing adjustments based on real session experience Alternative approaches for participants on different operating systems What We Are Not Looking For Right Now Rewriting the complete voice or structure of the workshop - if you have large-scale ideas, open a discussion first Adding content about tools or platforms not currently mentioned in the workshop Automated link-checking or content generation without human review 3. Before You Start - Fork and Clone You learned this workflow during the workshop. Here it is again as a reference. Account security Security: We strongly recommend enabling Two-Factor Authentication (2FA) on your GitHub account. If you cannot enable 2FA, add an SSH key or create a Personal Access Token (PAT) with repo scope before contributing. If you need help, contact the workshop organizers. Fork the Repository Navigate to the workshop repository on GitHub Activate the Fork button (top right of the repository page) Select your account as the fork destination Wait for the fork to complete - you will be redirected to your copy Screen reader users: NVDA / JAWS: Navigate by button ( B ) to find "Fork" VoiceOver: VO+Right Arrow to find "Fork" button, VO+Space to activate Clone Your Fork git clone https://github.com/[your-username]/[workshop-repo-name].git cd [workshop-repo-name] Add the Upstream Remote This keeps your fork synchronized with the original repository: git remote add upstream https://github.com/[original-owner]/[workshop-repo-name].git Verify both remotes are configured: git remote -v Expected output: origin https://github.com/ [ your-username ]/[workshop-repo-name].git (fetch) origin https://github.com/ [ your-username ]/[workshop-repo-name].git (push) upstream https://github.com/ [ original-owner ]/[workshop-repo-name].git (fetch) upstream https://github.com/ [ original-owner ]/[workshop-repo-name].git (push) 4. Contribution Workflow - Step by Step This is the same workflow you practiced during the workshop, applied to a real contribution. Step 1 - Sync with Upstream Always start from a current copy of the main branch: git checkout main git fetch upstream git merge upstream/main git push origin main Step 2 - Create a Focused Branch One issue or topic per branch. Branch names should describe the change: git checkout -b fix-nvda-shortcut-section-05 git" + "body": "Table: Keyboard shortcut for focusing search in different screen readers Contributing to This Workshop Repository Thank you for helping improve this workshop. Whether you are a participant who found a typo, someone who wants to add a new exercise, or an educator adapting these materials for your own community - your contribution is meaningful and welcome. This guide covers contributing to this workshop learning repository . For contributing to Accessibility Agents itself (the project you work on during Day 2), see Accessibility Agents' CONTRIBUTING.md . Table of Contents Who This Is For What Kinds of Contributions Are Welcome Before You Start - Fork and Clone Contribution Workflow - Step by Step Writing and Style Guidelines Accessibility Requirements HTML Documentation Build System Screen Reader Guidance for Commands in This Document Submitting Your Pull Request What Happens After You Submit Questions and Discussion 1. Who This Is For Workshop participants: You have already completed the contribution workflow during the workshop. This repository is an excellent first contribution target for applying what you practiced. Educators and facilitators: You are welcome to fork the entire repository and adapt the materials for your own workshop program. Attribution is required under the CC BY 4.0 license - please include a credit line and link to the original repository. Accessibility practitioners: If you have domain expertise in a particular screen reader or assistive technology and notice something that is incorrect or incomplete, please open an issue or submit a correction. Your expertise is exactly what this documentation needs. People who find bugs: A broken link, a command that has stopped working, an exercise that cannot be completed - all of these are legitimate bugs. Open an issue the same way you would for any software project. 2. What Kinds of Contributions Are Welcome Documentation Improvements Corrections: Wrong keyboard shortcut, screen reader command that has changed, broken external link, outdated UI description Clarity: A step that was confusing, an assumption that left someone behind, a paragraph that should be two Gaps: A common question that the documentation does not answer, an exercise step that was skipped New content: An additional exercise, a section about a tool or workflow not yet covered, a translation Issues and Bug Reports A command in the workshop exercises that does not work as described A screen reader behavior that differs from what the documentation says A broken link or missing image An exercise that assumes knowledge introduced later in the workshop Workshop Materials New exercises that reinforce a concept Facilitator notes based on running a session Timing adjustments based on real session experience Alternative approaches for participants on different operating systems What We Are Not Looking For Right Now Rewriting the complete voice or structure of the workshop - if you have large-scale ideas, open a discussion first Adding content about tools or platforms not currently mentioned in the workshop Automated link-checking or content generation without human review 3. Before You Start - Fork and Clone You learned this workflow during the workshop. Here it is again as a reference. Account security Security: We strongly recommend enabling Two-Factor Authentication (2FA) on your GitHub account. If you cannot enable 2FA, add an SSH key or create a Personal Access Token (PAT) with repo scope before contributing. If you need help, contact the workshop organizers. Fork the Repository Navigate to the workshop repository on GitHub Activate the Fork button (top right of the repository page) Select your account as the fork destination Wait for the fork to complete - you will be redirected to your copy Screen reader users: NVDA / JAWS: Navigate by button ( B ) to find "Fork" VoiceOver: VO+Right Arrow to find "Fork" button, VO+Space to activate Clone Your Fork git clone https://github.com/[your-username]/[workshop-repo-name].git cd [workshop-repo-name] Add the Upstream Remote This keeps your fork synchronized with the original repository: git remote add upstream https://github.com/[original-owner]/[workshop-repo-name].git Verify both remotes are configured: git remote -v Expected output: origin https://github.com/ [ your-username ]/[workshop-repo-name].git (fetch) origin https://github.com/ [ your-username ]/[workshop-repo-name].git (push) upstream https://github.com/ [ original-owner ]/[workshop-repo-name].git (fetch) upstream https://github.com/ [ original-owner ]/[workshop-repo-name].git (push) 4. Contribution Workflow - Step by Step This is the same workflow you practiced during the workshop, applied to a real contribution. Step 1 - Sync with Upstream Always start from a current copy of the main branch: git checkout main git fetch upstream git merge upstream/main git push origin main Step 2 - Create a Focused Branch One issue or topic per branch. Branch names sho" }, { "id": "README.html", "title": "GIT Going with GitHub", "url": "README.html", - "body": "GIT Going with GitHub License: CC BY 4.0 | Site | Discussions A Workshop by Community Access Welcome. This repository is your complete guide and companion for the two-day GIT Going with GitHub workshop. Every document here is written to be read with or without a screen reader. All steps are keyboard-accessible. You belong here. About Community Access: Community Access is a community of blind and low vision technology professionals. Visit community-access.org to learn more. Detail Information Workshop site community-access.org/git-going-with-github Registration Student opt-in and waitlist workflow Discussions Join the conversation Support File an issue Dates May 21, 2026 & May 22, 2026 Facilitators Jeff Bishop and Michael Babcock The Central Project: Accessibility Agents This workshop is built around a real, live open source project: Accessibility Agents - 55 AI agents across 3 teams and 5 platforms for accessible, agentic repository management. It was built by your facilitator Jeff Bishop and is MIT-licensed. You will fork it, understand it, contribute to it, and personalize it. The live workshop prepares you to make a real contribution, and the async continuation path gives you time to polish and submit it well. Accessibility Agents does not replace what you learn on Day 1. It amplifies it. The agents only make sense when you already understand the skills they automate. That is why Day 1 comes first - and why every guide in this repository shows you the manual path before it shows you the agent path. What Is This Event? During this two-day workshop, you will learn how to confidently navigate and contribute to open source projects on GitHub using: A screen reader (NVDA on Windows, JAWS on Windows, or VoiceOver on macOS) Keyboard-only navigation - no mouse required GitHub Copilot (Day 2) - AI-assisted writing and coding in the browser and in VS Code By the end of this event, you will have practiced real contribution workflows in a real repository. Some participants will ship during the live event; others will leave with a branch, a pull request path, and clear next steps to finish asynchronously. Who Is This For? This event is designed for: People new to GitHub who use assistive technology Developers who use screen readers and want to contribute to open source Anyone who is curious about accessible development workflows Sighted participants are welcome - all content is keyboard-navigable for everyone You do not need to know how to code to participate and contribute meaningfully. Documentation improvements, issue filing, accessibility bug reports, and code reviews are all valuable contributions. Two-Day Overview Day Focus What You Will Do Day 1 GitHub Foundations Set up your environment, learn GitHub navigation with your screen reader, file your first issue, open your first pull request Day 2 VS Code + Accessibility Agents Bridge from the browser to github.dev (VS Code in your browser - no install needed), then step into Visual Studio Code on the desktop, learn VS Code basics, use GitHub Copilot, activate the Accessibility Agents ecosystem (55 agents, 3 teams, 5 platforms), see agentic workflows in the cloud, and prepare a real upstream contribution path The Journey Arc This is not a two-day course with two separate syllabi. It is one arc. Day 1 - Learn the skill in the browser Navigate → Issue → Pull Request → Review → Merge ↓ (bridge: press . on any GitHub repo - VS Code opens right in your browser) github.dev - VS Code on the web, no install needed Same keyboard shortcuts · Same screen reader mode · Edit files · Open PRs What it cannot do : no terminal, no Copilot agents, no local extensions ↓ (you've earned the desktop - now it makes sense) Day 2 - Deepen with VS Code + Accessibility Agents Learn VS Code basics → Copilot inline → Copilot Chat @daily-briefing → @issue-tracker → @ pr -review → @analytics → prepare upstream Every skill you build on Day 1 maps directly to an Accessibility Agents command on Day 2. The agent is not a shortcut - it is a multiplier. You have to understand what it is doing to know when it is wrong. By the end of the Day 2 core path, you will have: A fork of accessibility-agents with your personalized preferences A branch or pull request path for a real open source contribution Clear next steps to get your contribution reviewed and merged A working set of 55 AI agents across 3 teams that travel with your fork to any repository you apply them to How to Read These Docs All documentation lives in the docs/ folder. If you are new, start with Get Going with GitHub . It explains the GitHub Classroom assignment link, your private Learning Room repository, the first challenge issue, how evidence works, and how to choose the tool path that fits you. Facilitators preparing a cohort should use the Go-Live QA Guide as the release gate before sharing Classroom invite links. Your Challenges 16 challenges guide you through the workshop, plus 5 bonus challenges for those who finish early." + "body": "GIT Going with GitHub License: CC BY 4.0 | Site | Discussions A Workshop by Community Access Welcome. This repository is your complete guide and companion for the two-day GIT Going with GitHub workshop. Every document here is written to be read with or without a screen reader. All steps are keyboard-accessible. You belong here. About Community Access: Community Access is a community of blind and low vision technology professionals. Visit community-access.org to learn more. Detail Information Workshop site community-access.org/git-going-with-github Registration Student opt-in and waitlist workflow Discussions Join the conversation Support hub Community-Access/support Curriculum issues File an issue in this repository Dates May 21, 2026 & May 22, 2026 Facilitators Jeff Bishop and Michael Babcock The Central Project: Accessibility Agents This workshop is built around a real, live open source project: Accessibility Agents - 55 AI agents across 3 teams and 5 platforms for accessible, agentic repository management. It was built by your facilitator Jeff Bishop and is MIT-licensed. You will fork it, understand it, contribute to it, and personalize it. The live workshop prepares you to make a real contribution, and the async continuation path gives you time to polish and submit it well. Accessibility Agents does not replace what you learn on Day 1. It amplifies it. The agents only make sense when you already understand the skills they automate. That is why Day 1 comes first - and why every guide in this repository shows you the manual path before it shows you the agent path. What Is This Event? During this two-day workshop, you will learn how to confidently navigate and contribute to open source projects on GitHub using: A screen reader (NVDA on Windows, JAWS on Windows, or VoiceOver on macOS) Keyboard-only navigation - no mouse required GitHub Copilot (Day 2) - AI-assisted writing and coding in the browser and in VS Code By the end of this event, you will have practiced real contribution workflows in a real repository. Some participants will ship during the live event; others will leave with a branch, a pull request path, and clear next steps to finish asynchronously. Who Is This For? This event is designed for: People new to GitHub who use assistive technology Developers who use screen readers and want to contribute to open source Anyone who is curious about accessible development workflows Sighted participants are welcome - all content is keyboard-navigable for everyone You do not need to know how to code to participate and contribute meaningfully. Documentation improvements, issue filing, accessibility bug reports, and code reviews are all valuable contributions. Two-Day Overview Day Focus What You Will Do Day 1 GitHub Foundations Set up your environment, learn GitHub navigation with your screen reader, file your first issue, open your first pull request Day 2 VS Code + Accessibility Agents Bridge from the browser to github.dev (VS Code in your browser - no install needed), then step into Visual Studio Code on the desktop, learn VS Code basics, use GitHub Copilot, activate the Accessibility Agents ecosystem (55 agents, 3 teams, 5 platforms), see agentic workflows in the cloud, and prepare a real upstream contribution path The Journey Arc This is not a two-day course with two separate syllabi. It is one arc. Day 1 - Learn the skill in the browser Navigate → Issue → Pull Request → Review → Merge ↓ (bridge: press . on any GitHub repo - VS Code opens right in your browser) github.dev - VS Code on the web, no install needed Same keyboard shortcuts · Same screen reader mode · Edit files · Open PRs What it cannot do : no terminal, no Copilot agents, no local extensions ↓ (you've earned the desktop - now it makes sense) Day 2 - Deepen with VS Code + Accessibility Agents Learn VS Code basics → Copilot inline → Copilot Chat @daily-briefing → @issue-tracker → @ pr -review → @analytics → prepare upstream Every skill you build on Day 1 maps directly to an Accessibility Agents command on Day 2. The agent is not a shortcut - it is a multiplier. You have to understand what it is doing to know when it is wrong. By the end of the Day 2 core path, you will have: A fork of accessibility-agents with your personalized preferences A branch or pull request path for a real open source contribution Clear next steps to get your contribution reviewed and merged A working set of 55 AI agents across 3 teams that travel with your fork to any repository you apply them to How to Read These Docs All documentation lives in the docs/ folder. If you are new, start with Get Going with GitHub . It explains the GitHub Classroom assignment link, your private Learning Room repository, the first challenge issue, how evidence works, and how to choose the tool path that fits you. Facilitators preparing a cohort should use the Go-Live QA Guide as the release gate before sharing Classroom invite links. Post-Workshop Support After the " }, { "id": "REPOSITORY_SECURITY.html", @@ -825,7 +1401,7 @@ "id": "classroom/index.html", "title": "Workshop Deployment Guide", "url": "classroom/index.html", - "body": "Workshop Deployment Guide Single, end-to-end guide for deploying a new Git Going with GitHub workshop cohort. Covers everything from creating the classroom through post-workshop teardown. This is the only deployment document you need. Before sharing invite links with students, complete the Go-Live QA Guide . It is the final release gate for content, workflows, Classroom setup, podcasts, accessibility, and human test coverage. 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: 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 Student Progression Bot -- creates the first challenge when triggered by a facilitator script, then creates the next challenge issue whenever a student closes the current challenge issue Autograders -- automated tests that verify objective evidence of challenge completion (branch exists, conflict markers removed, template file valid, agent file structured correctly) No shared student repository. Students do not clone the template or configure permissions. The facilitator's deployment work is creating the classroom and two assignments in the GitHub Classroom web UI, then running the seeding scripts after each student repo is created. Students only need a GitHub account. They do not need to create an organization, become members of Community-Access , or change GitHub Actions settings. Organization and repository workflow permissions are facilitator responsibilities. Architecture Community-Access/learning-room-template (template repo) | +--> GitHub Classroom creates one private repo per student | learning-room-student-a | learning-room-student-b | ... | +--> Each student repo contains: | 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 Day 2 only Participants with GitHub fundamentals Assignment 2 only Day 2 Quick Start then Day 2 Agenda Day-2-only participants skip Assignment 1 entirely. They verify readiness using the Day 2 Quick Start self-assessment, then accept only the Day 2 invite link. What Is in This Directory File Purpose assignment-day1-you-belong-here.md Assignment description for Day 1 (paste into Classroom UI) assignment-day2-you-can-build-this.md Assignment description for Day 2 (paste into Classroom UI) autograding-day1.json Test definitions for Day 1 autograder autograding-day2.json Test definitions for Day 2 autograder grading-guide.md Facilitator rubric for all 21 challenges roster-template.csv Starter CSV for importing student roster student-progression.yml Reference copy of the progression bot workflow HUMAN_TEST_MATRIX.md End-to-end human walkthrough for all 16 core and 5 bonus challenges teardown-checklist.md Post-workshop cleanup steps ../GO-LIVE-QA-GUIDE.md Final release-readiness guide and checklist 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 " + "body": "Workshop Deployment Guide Single, end-to-end guide for deploying a new Git Going with GitHub workshop cohort. Covers everything from creating the classroom through post-workshop teardown. This is the only deployment document you need. Before sharing invite links with students, complete the Go-Live QA Guide . It is the final release gate for content, workflows, Classroom setup, podcasts, accessibility, and human test coverage. If you need one practical execution script from registration through full student challenge completion (podcast work excluded), use admin/LEARNING-ROOM-E2E-QA-RUNBOOK.md . Before creating assignments, sync and validate the latest template deployment using scripts/classroom/Prepare-LearningRoomTemplate.ps1 and scripts/classroom/Test-LearningRoomTemplate.ps1 . How the Workshop Works Each student gets their own private repository created by GitHub Classroom from the learning-room-template . Inside that repo, three automation systems guide the student through all 21 challenges without facilitator intervention: 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 Student Progression Bot -- creates the first challenge when triggered by a facilitator script, then creates the next challenge issue whenever a student closes the current challenge issue Autograders -- automated tests that verify objective evidence of challenge completion (branch exists, conflict markers removed, template file valid, agent file structured correctly) No shared student repository. Students do not clone the template or configure permissions. The facilitator's deployment work is creating the classroom and two assignments in the GitHub Classroom web UI, then running the seeding scripts after each student repo is created. Students only need a GitHub account. They do not need to create an organization, become members of Community-Access , or change GitHub Actions settings. Organization and repository workflow permissions are facilitator responsibilities. Architecture Community-Access/learning-room-template (template repo) | +--> GitHub Classroom creates one private repo per student | learning-room-student-a | learning-room-student-b | ... | +--> Each student repo contains: | 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 Day 2 only Participants with GitHub fundamentals Assignment 2 only Day 2 Quick Start then Day 2 Agenda Day-2-only participants skip Assignment 1 entirely. They verify readiness using the Day 2 Quick Start self-assessment, then accept only the Day 2 invite link. What Is in This Directory File Purpose assignment-day1-you-belong-here.md Assignment description for Day 1 (paste into Classroom UI) assignment-day2-you-can-build-this.md Assignment description for Day 2 (paste into Classroom UI) autograding-day1.json Test definitions for Day 1 autograder autograding-day2.json Test definitions for Day 2 autograder grading-guide.md Facilitator rubric for all 21 challenges roster-template.csv Starter CSV for importing student roster student-progression.yml Reference copy of the progression bot workflow HUMAN_TEST_MATRIX.md End-to-end human walkthrough for all 16 core and 5 bonus challenges teardown-checklist.md Post-workshop cleanup steps ../GO-LIVE-QA-GUIDE.md Final release-readiness guide and checklist ../admin/LEARNING-ROOM-E2E-QA-RUNBOOK.md Single operator runbook from registration to student completion (podcast excluded) Prerequisites Before starting, confirm the following: You have Owner or Admin access to the Community-Access GitHub organization Your facilitator GitHub account has a verified email address The Community-Access/learning-room-template repository exists and is public (or the classroom org has read access) The template repo has GitHub Actions enabled with Read and write permissions for GITHUB_TOKEN (Settings > Actions > General) -- 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 separ" }, { "id": "classroom/assignment-day1-you-belong-here.html", @@ -873,12 +1449,13 @@ "id": "REGISTER.html", "title": "Student Opt-In", "url": "REGISTER.html", - "body": "Student Opt-In Back to Home | Discussion Forum | Pre-Workshop Setup Guide 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 Sign in to your GitHub account . Open the registration issue form. Submit the form. Start Student Opt-In Form 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 Join the Discussion Forum A Community Access initiative." + "body": "Student Opt-In Back to Home | Support Hub | Pre-Workshop Setup Guide 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 Sign in to your GitHub account . Open the registration issue form. Submit the form. Start Student Opt-In Form 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 a support issue Join Support Hub Discussions A Community Access initiative." }, { "id": "GO-LIVE-QA-GUIDE.html", "title": "Git Going with GitHub Go-Live QA Guide", "url": "GO-LIVE-QA-GUIDE.html", - "body": "Git Going with GitHub Go-Live QA Guide Use this guide before a cohort is opened to learners. It is the release gate for curriculum content, GitHub Classroom deployment, Learning Room automation, 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. 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. 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 copy-paste setup pack admin/classroom/README.md Human challenge walkthrough classroom/HUMAN_TEST_MATRIX.md Facilitator operations admin/FACILITATOR_OPERATIONS.md Facilitator guide admin/FACILITATOR_GUIDE.md Student challenge hub docs/CHALLENGES.md Podcast pipeline podcasts/README.md Podcast regeneration runbook podcasts/REGENERATION.md Post-workshop cleanup 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. 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 , BUILD.md , REGISTER.md , CONTRIBUTING.md , SECURITY.md , REPOSITORY_SECURITY.md . Student onboarding: docs/get-going.md , docs/course-guide.md , and docs/student-onboarding.md . Core chapters: docs/00-pre-workshop-setup.md through docs/21-next-steps.md . Appendices: docs/appendix-a-glossary.md through docs/appendix-z-github-skills.md . Challenge hub: docs/CHALLENGES.md . Challenge solutions: all files in docs/solutions . Learning Room template docs: all Markdown files under learning-room . 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 and admin/classroom . Classroom setup artifacts: all Markdown, JSON, CSV, and YAML files under classroom . Podcast docs, scripts, manifests, transcripts, and generated site metadata under podcasts . 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 di" + "body": "Git Going with GitHub Go-Live QA Guide Use this guide before a cohort is opened to learners. It is the release gate for curriculum content, GitHub Classroom deployment, Learning Room automation, podcast materials, accessibility, and human test coverage. For end-to-end execution details, use admin/LEARNING-ROOM-E2E-QA-RUNBOOK.md as the operator procedure. This guide is the release gate summary; the runbook is the required execution playbook. The goal is simple: a facilitator should be able to create a classroom, seed test repositories, complete every challenge path, validate every generated artifact, and know exactly what remains before students arrive. 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). Support Hub is provisioned and publicly accessible at Community-Access/support . Registration confirmation and help pathways route support requests to Support Hub issues/discussions. Registration issue form template and labels are configured ( workshop-registration.yml , registration , duplicate , waitlist ). 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. Runbook Phase 8 required checklist is complete in admin/LEARNING-ROOM-E2E-QA-RUNBOOK.md . Student recovery Level 2 restore test is completed and evidenced with branch and PR links. All in-scope automation workflows and facilitator scripts were validated with expected behavior and evidence. Local non-podcast readiness evidence is recorded in admin/qa-readiness . 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. Support channel links point to deprecated destinations and not to support . 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 copy-paste setup pack admin/classroom/README.md End-to-end operator runbook (registration to completion, podcast excluded) admin/LEARNING-ROOM-E2E-QA-RUNBOOK.md Human challenge walkthrough classroom/HUMAN_TEST_MATRIX.md Facilitator operations admin/FACILITATOR_OPERATIONS.md Facilitator guide admin/FACILITATOR_GUIDE.md Support hub operations admin/SUPPORT_HUB_OPERATIONS.md Student challenge hub docs/CHALLENGES.md Podcast pipeline podcasts/README.md Podcast regeneration runbook podcasts/REGENERATION.md Post-workshop cleanup 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" } ] + diff --git a/learning-room/.github/DEPLOYMENT_VALIDATION.md b/learning-room/.github/DEPLOYMENT_VALIDATION.md index 764527ce..4f9e5e34 100644 --- a/learning-room/.github/DEPLOYMENT_VALIDATION.md +++ b/learning-room/.github/DEPLOYMENT_VALIDATION.md @@ -1,3 +1,9 @@ + +**Table: Workflow status and triggers for deployment validation** + +**Table: Error handling scenarios in deployment validation** + +**Table: Metrics for deployment validation and student experience** # Learning Room Automation - Deployment Validation Checklist ## Complete Setup Verification diff --git a/learning-room/.github/FACILITATOR_GUIDE.md b/learning-room/.github/FACILITATOR_GUIDE.md index 747b1a23..9e15b7d7 100644 --- a/learning-room/.github/FACILITATOR_GUIDE.md +++ b/learning-room/.github/FACILITATOR_GUIDE.md @@ -1,3 +1,5 @@ + +**Table: Common facilitator questions and responses** # Learning Room Automation - Facilitator Quick Reference ## What Students See diff --git a/learning-room/.github/IMPLEMENTATION_GUIDE.md b/learning-room/.github/IMPLEMENTATION_GUIDE.md index 4657ac89..c7f17f12 100644 --- a/learning-room/.github/IMPLEMENTATION_GUIDE.md +++ b/learning-room/.github/IMPLEMENTATION_GUIDE.md @@ -1,3 +1,7 @@ + +**Table: Learning Room workflow automation and triggers** + +**Table: Key documentation files for Learning Room automation** # Learning Room Template: Implementation Guide > **For full workshop deployment instructions, see diff --git a/learning-room/.github/SETUP_AND_MAINTENANCE.md b/learning-room/.github/SETUP_AND_MAINTENANCE.md index 06be5314..b3c5515c 100644 --- a/learning-room/.github/SETUP_AND_MAINTENANCE.md +++ b/learning-room/.github/SETUP_AND_MAINTENANCE.md @@ -1,3 +1,7 @@ + +**Table: Workflow automation in the Learning Room** + +**Table: Troubleshooting common issues in Learning Room automation** # Learning Room Automation Setup & Maintenance Guide ## Overview diff --git a/learning-room/.github/STUDENT_GUIDE.md b/learning-room/.github/STUDENT_GUIDE.md index 0fe8f47e..4a8203bf 100644 --- a/learning-room/.github/STUDENT_GUIDE.md +++ b/learning-room/.github/STUDENT_GUIDE.md @@ -1,3 +1,5 @@ + +**Table: What the bot does and how it helps students** # How the Learning Room Automation Works - Student Guide ## What Is This Automation? diff --git a/learning-room/README.md b/learning-room/README.md index 085cdee8..f180f949 100644 --- a/learning-room/README.md +++ b/learning-room/README.md @@ -1,3 +1,6 @@ + +**Table: Learning Room folder and file purposes** +**Table: Host voice and character mapping for VibeVoice podcast** # Welcome to the Learning Room This repository is your private Learning Room for the Git Going with GitHub workshop. GitHub Classroom created it from the Learning Room template so you can practice the full contribution workflow safely. In this repository you will: diff --git a/package-lock.json b/package-lock.json index 784113d9..99a0bbf6 100644 --- a/package-lock.json +++ b/package-lock.json @@ -8,6 +8,9 @@ "name": "git-going-with-github", "version": "1.0.0", "license": "CC-BY-4.0", + "dependencies": { + "playwright": "^1.59.1" + }, "devDependencies": { "chokidar": "^3.5.3", "github-markdown-css": "^5.5.1", @@ -234,6 +237,50 @@ "url": "https://github.com/sponsors/jonschlinkert" } }, + "node_modules/playwright": { + "version": "1.59.1", + "resolved": "https://registry.npmjs.org/playwright/-/playwright-1.59.1.tgz", + "integrity": "sha512-C8oWjPR3F81yljW9o5OxcWzfh6avkVwDD2VYdwIGqTkl+OGFISgypqzfu7dOe4QNLL2aqcWBmI3PMtLIK233lw==", + "license": "Apache-2.0", + "dependencies": { + "playwright-core": "1.59.1" + }, + "bin": { + "playwright": "cli.js" + }, + "engines": { + "node": ">=18" + }, + "optionalDependencies": { + "fsevents": "2.3.2" + } + }, + "node_modules/playwright-core": { + "version": "1.59.1", + "resolved": "https://registry.npmjs.org/playwright-core/-/playwright-core-1.59.1.tgz", + "integrity": "sha512-HBV/RJg81z5BiiZ9yPzIiClYV/QMsDCKUyogwH9p3MCP6IYjUFu/MActgYAvK0oWyV9NlwM3GLBjADyWgydVyg==", + "license": "Apache-2.0", + "bin": { + "playwright-core": "cli.js" + }, + "engines": { + "node": ">=18" + } + }, + "node_modules/playwright/node_modules/fsevents": { + "version": "2.3.2", + "resolved": "https://registry.npmjs.org/fsevents/-/fsevents-2.3.2.tgz", + "integrity": "sha512-xiqMQR4xAeHTuB9uWm+fFRcIOgKBMiOBP+eXiyT7jsgVCq1bkVygt00oASowB7EdtpOHaaPgKt812P9ab+DDKA==", + "hasInstallScript": true, + "license": "MIT", + "optional": true, + "os": [ + "darwin" + ], + "engines": { + "node": "^8.16.0 || ^10.6.0 || >=11.0.0" + } + }, "node_modules/readdirp": { "version": "3.6.0", "resolved": "https://registry.npmjs.org/readdirp/-/readdirp-3.6.0.tgz", diff --git a/package.json b/package.json index ff197623..0bd8e0d9 100644 --- a/package.json +++ b/package.json @@ -47,5 +47,8 @@ "highlight.js": "^11.9.0", "lunr": "^2.3.9", "marked": "^11.2.0" + }, + "dependencies": { + "playwright": "^1.59.1" } -} \ No newline at end of file +} diff --git a/podcasts/README.md b/podcasts/README.md index 1e5f5097..b7d7379c 100644 --- a/podcasts/README.md +++ b/podcasts/README.md @@ -1,3 +1,9 @@ + +**Table: Host voice and character mapping for VibeVoice podcast** + +**Table: Podcast build and validation commands** + +**Table: Podcast bundle generation steps and costs** # Podcast Audio Pipeline This directory contains the complete pipeline for producing the Git Going with GitHub audio series: 54 companion episodes of two-host conversational content designed for blind and low-vision developers, plus 21 Challenge Coach episodes placed near the chapters they support. diff --git a/podcasts/feed.xml b/podcasts/feed.xml index 2f96a03a..ddd584c9 100644 --- a/podcasts/feed.xml +++ b/podcasts/feed.xml @@ -66,7 +66,7 @@

Alex: Hold that next to this. Here is the plain-English version of Exercises at a Glance. The workshop includes structured exercises across the curriculum. Put another way, every exercise is designed to be completed in 1-5 minutes, is impossible to fail, and follows the same pattern: Try It - You're done when - What success feels like.

Jamie: What do you want them to do when the plan breaks?

-

Alex: This is where Getting Help becomes real: if you get stuck at any point during the workshop, these resources are always available. That matters in practice: Open an issue on this repository describing what you tried, what happened, and what you expected.

+

Alex: This is where Getting Help becomes real: if you get stuck at any point during the workshop, these resources are always available. That matters in practice: Use the support hub at https://github.com/Community-Access/support and open a support issue describing what you tried, what happened, and what you expected.

Alex: That connects to another useful point. Keep the learner anchored in Workshop at a Glance. Start with Chapter 00: Pre-Workshop Setup. A good GitHub workflow is like a well-run meeting: everyone knows the topic, the next action, and who has the floor.

Jamie: What is the one idea that makes the next few steps less mysterious?

Alex: The reason What This Guide Does matters is that this workshop is designed so you are never left guessing what comes next. That gives the learner a simple foothold: the goal is to build confidence one checkable step at a time.

@@ -207,7 +207,7 @@ Hold that next to this. Here is the plain-English version of Exercises at a Glan What do you want them to do when the plan breaks? [ALEX] -This is where Getting Help becomes real: if you get stuck at any point during the workshop, these resources are always available. That matters in practice: Open an issue on this repository describing what you tried, what happened, and what you expected. +This is where Getting Help becomes real: if you get stuck at any point during the workshop, these resources are always available. That matters in practice: Use the support hub at https://github.com/Community-Access/support and open a support issue describing what you tried, what happened, and what you expected. [ALEX] That connects to another useful point. Keep the learner anchored in Workshop at a Glance. Start with Chapter 00: Pre-Workshop Setup. A good GitHub workflow is like a well-run meeting: everyone knows the topic, the next action, and who has the floor. @@ -392,7 +392,7 @@ Alex: Hold that next to this. Here is the plain-English version of Exercises at Jamie: What do you want them to do when the plan breaks? -Alex: This is where Getting Help becomes real: if you get stuck at any point during the workshop, these resources are always available. That matters in practice: Open an issue on this repository describing what you tried, what happened, and what you expected. +Alex: This is where Getting Help becomes real: if you get stuck at any point during the workshop, these resources are always available. That matters in practice: Use the support hub at https://github.com/Community-Access/support and open a support issue describing what you tried, what happened, and what you expected. Alex: That connects to another useful point. Keep the learner anchored in Workshop at a Glance. Start with Chapter 00: Pre-Workshop Setup. A good GitHub workflow is like a well-run meeting: everyone knows the topic, the next action, and who has the floor. diff --git a/podcasts/scripts/appendices/ep23-github-gists.txt b/podcasts/scripts/appendices/ep23-github-gists.txt index 350303b9..66d9ef4e 100644 --- a/podcasts/scripts/appendices/ep23-github-gists.txt +++ b/podcasts/scripts/appendices/ep23-github-gists.txt @@ -32,6 +32,9 @@ The next layer is this. Start with Learning Cards: GitHub Discussions. There is [ALEX] The practical anchors are these. The Discussions tab is in the repository's main navigation bar alongside Code, Issues, and Pull Requests -- press T to navigate tab items or K to find the "Discussions" link. Inside a discussion, replies are article elements -- in NVDA press A to jump between replies; in JAWS use A as well. The reply editor uses the same behavior as issue comments -- enter Focus Mode to type, then press Ctrl+Enter to submit. Discussion categories appear as a sidebar panel on the left or right depending on viewport width -- look for the category list with item counts. Answered discussions in the Q&A category display a green "Answered" badge next to the title, with the accepted answer pinned to the top. Polls show percentage bars next to each option after you vote -- the bars use color fill to indicate proportion. +[ALEX] +For this workshop ecosystem, use Community-Access/support as the primary support forum. Start in Discussions for Q&A and use Issues when you need tracked troubleshooting. + [JAMIE] Can you translate that into plain choices? diff --git a/podcasts/scripts/challenges/cc-03-join-the-conversation.txt b/podcasts/scripts/challenges/cc-03-join-the-conversation.txt index e0594aa2..c8016576 100644 --- a/podcasts/scripts/challenges/cc-03-join-the-conversation.txt +++ b/podcasts/scripts/challenges/cc-03-join-the-conversation.txt @@ -1611,6 +1611,9 @@ How should someone ask for help in a way that gets them unstuck faster? [ALEX] Here is the plain-English version of 7. Getting Help. It is always acceptable to ask a question on an issue or pull request. Put another way, 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. +[ALEX] +For workshop and alumni help, route support requests to Community-Access/support first, then escalate to repository-specific issues only when the support team asks you to. + [ALEX] The practical takeaway is this. 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. diff --git a/podcasts/scripts/chapters/ep00-welcome.txt b/podcasts/scripts/chapters/ep00-welcome.txt index fb1e3018..15601649 100644 --- a/podcasts/scripts/chapters/ep00-welcome.txt +++ b/podcasts/scripts/chapters/ep00-welcome.txt @@ -95,7 +95,7 @@ Hold that next to this. Here is the plain-English version of Exercises at a Glan What do you want them to do when the plan breaks? [ALEX] -This is where Getting Help becomes real: if you get stuck at any point during the workshop, these resources are always available. That matters in practice: Open an issue on this repository describing what you tried, what happened, and what you expected. +This is where Getting Help becomes real: if you get stuck at any point during the workshop, these resources are always available. That matters in practice: Use the support hub at https://github.com/Community-Access/support and open a support issue describing what you tried, what happened, and what you expected. [ALEX] That connects to another useful point. Keep the learner anchored in Workshop at a Glance. Start with Chapter 00: Pre-Workshop Setup. A good GitHub workflow is like a well-run meeting: everyone knows the topic, the next action, and who has the floor. @@ -178,6 +178,9 @@ This is the part worth saying out loud. Here is the plain-English version of Ste [ALEX] The practical anchors are these. Every challenge issue includes instructions and evidence prompts. Every chapter has an If You Get Stuck section. Every challenge has a reference solution in the solutions folder. Aria posts feedback on pull requests. +[ALEX] +Add this onboarding habit early: open Support Hub Discussions, read the pinned Start Here guidance, then introduce yourself so maintainers and peers can support you faster. + [JAMIE] Give me the sequence, because order matters here. diff --git a/podcasts/scripts/chapters/ep01-pre-workshop-setup.txt b/podcasts/scripts/chapters/ep01-pre-workshop-setup.txt index 6695c469..47867fe3 100644 --- a/podcasts/scripts/chapters/ep01-pre-workshop-setup.txt +++ b/podcasts/scripts/chapters/ep01-pre-workshop-setup.txt @@ -21,7 +21,7 @@ Yes. A good audio lesson gives someone enough context to try the work with confi What does someone need before they touch the keyboard? [ALEX] -Start with Everything You Need Before Day 1 Begins: Please complete this guide at least one day before the workshop. The next useful detail is this: If you run into any issues, file an issue so we can help - we want Day 1 to start with everyone ready to go, not troubleshooting. +Start with Everything You Need Before Day 1 Begins: Please complete this guide at least one day before the workshop. The next useful detail is this: If you run into any issues, use the support hub so we can help - we want Day 1 to start with everyone ready to go, not troubleshooting. [ALEX] The next layer is this. Start with Hardware. There is something to understand, something to try, and something that proves the try worked. @@ -748,7 +748,7 @@ Let's pause on Getting Help Before the Event. What should a learner take away fr Start with Getting Help Before the Event: If you cannot complete any step in this guide before the workshop. The next useful detail is this: Every setup issue we can solve before Day 1 means more time for learning on the day. [ALEX] -First, file an issue - community-access/git-going-with-github - we will help you get set up. Then, file an issue in this repository - describe exactly what step you are on and what is not working. After that, join the GitHub Accessibility Discussions - GitHub Community Accessibility Discussions - the community is helpful and welcoming. Think of it as a rail line: each stop confirms you are still on the right route before the next one. +First, open a setup support issue in Community-Access/support/issues so maintainers can triage quickly. Then, join Community-Access/support/discussions and read the pinned Start Here guidance before posting follow-up questions. After that, if you need broader platform input, join GitHub Community Accessibility Discussions. Think of it as a rail line: each stop confirms you are still on the right route before the next one. [PAUSE] diff --git a/podcasts/transcripts/appendices/ep23-github-gists-segments.json b/podcasts/transcripts/appendices/ep23-github-gists-segments.json index e202ad4e..1955f891 100644 --- a/podcasts/transcripts/appendices/ep23-github-gists-segments.json +++ b/podcasts/transcripts/appendices/ep23-github-gists-segments.json @@ -69,7 +69,7 @@ }, { "speaker": "ALEX", - "text": "For a learner, the useful signals are these. Q&A - Support questions and answers (one answer can be marked correct). Ideas - Feature brainstorming before a formal feature request. Announcements - Maintainer posts about releases, breaking changes, roadmaps. General - Everything else. Show and Tell - Community members showing what they built." + "text": "For a learner, the useful signals are these. Q&A - Support questions and answers (one answer can be marked correct). Ideas - Feature brainstorming before a formal feature request. Announcements - Maintainer posts about releases, breaking changes, roadmaps. General - Everything else. Show and Tell - Community members showing what they built. For this workshop ecosystem, use Community-Access/support as the primary support forum." }, { "speaker": "JAMIE", diff --git a/podcasts/transcripts/challenges/cc-03-join-the-conversation-segments.json b/podcasts/transcripts/challenges/cc-03-join-the-conversation-segments.json index d6318cbc..e6e56af0 100644 --- a/podcasts/transcripts/challenges/cc-03-join-the-conversation-segments.json +++ b/podcasts/transcripts/challenges/cc-03-join-the-conversation-segments.json @@ -2233,7 +2233,7 @@ }, { "speaker": "ALEX", - "text": "Here is the plain-English version of 7. Getting Help. It is always acceptable to ask a question on an issue or pull request. Put another way, 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." + "text": "Here is the plain-English version of 7. Getting Help. It is always acceptable to ask a question on an issue or pull request. Put another way, 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. For workshop and alumni help, route support requests to Community-Access/support first." }, { "speaker": "ALEX", diff --git a/podcasts/transcripts/chapters/ep00-welcome-segments.json b/podcasts/transcripts/chapters/ep00-welcome-segments.json index 75d05bad..b53f3c4f 100644 --- a/podcasts/transcripts/chapters/ep00-welcome-segments.json +++ b/podcasts/transcripts/chapters/ep00-welcome-segments.json @@ -137,7 +137,7 @@ }, { "speaker": "ALEX", - "text": "This is where Getting Help becomes real: if you get stuck at any point during the workshop, these resources are always available. That matters in practice: Open an issue on this repository describing what you tried, what happened, and what you expected." + "text": "This is where Getting Help becomes real: if you get stuck at any point during the workshop, these resources are always available. That matters in practice: Use the support hub at https://github.com/Community-Access/support and open a support issue describing what you tried, what happened, and what you expected." }, { "speaker": "ALEX", diff --git a/podcasts/transcripts/chapters/ep01-pre-workshop-setup-segments.json b/podcasts/transcripts/chapters/ep01-pre-workshop-setup-segments.json index 4aa48071..48e8c2c1 100644 --- a/podcasts/transcripts/chapters/ep01-pre-workshop-setup-segments.json +++ b/podcasts/transcripts/chapters/ep01-pre-workshop-setup-segments.json @@ -1037,7 +1037,7 @@ }, { "speaker": "ALEX", - "text": "First, file an issue - community-access/git-going-with-github - we will help you get set up. Then, file an issue in this repository - describe exactly what step you are on and what is not working. After that, join the GitHub Accessibility Discussions - GitHub Community Accessibility Discussions - the community is helpful and welcoming. Think of it as a rail line: each stop confirms you are still on the right route before the next one." + "text": "First, open a setup support issue in Community-Access/support/issues so maintainers can triage quickly. Then, join Community-Access/support/discussions and read the pinned Start Here guidance before posting follow-up questions. After that, if you need broader platform input, join GitHub Community Accessibility Discussions. Think of it as a rail line: each stop confirms you are still on the right route before the next one." }, { "speaker": "PAUSE", diff --git a/podcasts/tts/README.md b/podcasts/tts/README.md index e816f025..41f81a41 100644 --- a/podcasts/tts/README.md +++ b/podcasts/tts/README.md @@ -1,3 +1,5 @@ + +**Table: TTS pipeline outcomes and provided commands** # TTS Setup: Piper and Kokoro This runbook documents the end-to-end local setup for the workshop TTS toolchain. diff --git a/scripts/classroom/Archive-CohortData.ps1 b/scripts/classroom/Archive-CohortData.ps1 new file mode 100644 index 00000000..a1a24a3a --- /dev/null +++ b/scripts/classroom/Archive-CohortData.ps1 @@ -0,0 +1,394 @@ +<# +.SYNOPSIS + Archives cohort student data from Community-Access/git-going-with-github to + Community-Access/git-going-student-success, then resets the source repository + to a clean state for the next cohort. + +.DESCRIPTION + Performs the following in order: + + 1. EXPORT -- Fetches all registration/duplicate/waitlist issues with their comments + and saves them as JSON and CSV to a local staging folder. + 2. EXPORT -- Exports the current student-roster.json to the archive. + 3. EXPORT -- Exports all GitHub Discussions to JSON (see LIMITATIONS). + 4. COMMIT ARCHIVE -- Pushes the staged archive folder to git-going-student-success + under admin/cohorts//. + 5. RESET ISSUES -- Closes and locks all open/closed registration issues in the + source repository (see LIMITATIONS -- issues cannot be deleted via API). + 6. RESET ROSTER -- Resets .github/data/student-roster.json to its blank template + state via a direct commit to main. + + LIMITATIONS (GitHub API hard constraints): + - Issues cannot be deleted via the GitHub REST API. They are closed and locked. + A facilitator must manually delete them from the GitHub UI if deletion is required. + Path: github.com/Community-Access/git-going-with-github/issues -> filter by label + -> open each -> delete via the "..." menu (requires admin on the repository). + - Discussions cannot be moved or deleted via any public API (GraphQL mutations for + discussion management are not available). They are exported to the archive as JSON + only. A facilitator must manually delete them from the Discussions tab in the UI. + - This script does not touch any files tracked in source control other than + student-roster.json. + +.PARAMETER CohortSlug + Short identifier for the cohort being archived, used as the folder name in the + student-success repository. Format: YYYY-MM-description + Example: 2026-03-march-cohort + +.PARAMETER SourceRepo + Source repository slug. Defaults to Community-Access/git-going-with-github. + +.PARAMETER SuccessRepo + Archive destination repository slug. Defaults to Community-Access/git-going-student-success. + +.PARAMETER StagingPath + Local folder for staging archive files before pushing. Defaults to a temp directory. + Deleted after push unless -KeepStaging is specified. + +.PARAMETER KeepStaging + Keep the local staging folder after the archive push completes. + +.PARAMETER WhatIf + Show what would be done without making any changes to GitHub. + +.EXAMPLE + # Archive March 2026 cohort + .\Archive-CohortData.ps1 -CohortSlug 2026-03-march-cohort + +.EXAMPLE + # Preview without making changes + .\Archive-CohortData.ps1 -CohortSlug 2026-05-may-cohort -WhatIf +#> + +[CmdletBinding(SupportsShouldProcess)] +param( + [Parameter(Mandatory = $true)] + [ValidatePattern('^\d{4}-\d{2}-[a-z0-9-]+$')] + [string]$CohortSlug, + + [string]$SourceRepo = 'Community-Access/git-going-with-github', + + [string]$SuccessRepo = 'Community-Access/git-going-student-success', + + [string]$StagingPath = '', + + [switch]$KeepStaging +) + +$ErrorActionPreference = 'Stop' + +function Write-Step { param([string]$m) Write-Host "`n==> $m" -ForegroundColor Cyan } +function Write-Pass { param([string]$m) Write-Host " [PASS] $m" -ForegroundColor Green } +function Write-Warn { param([string]$m) Write-Host " [WARN] $m" -ForegroundColor Yellow } +function Write-Info { param([string]$m) Write-Host " $m" -ForegroundColor Gray } +function Write-Fail { param([string]$m) Write-Host " [FAIL] $m" -ForegroundColor Red } + +# --------------------------------------------------------------------------- +# 0. Preflight +# --------------------------------------------------------------------------- +Write-Step "Preflight checks" + +gh auth status -h github.com 2>&1 | ForEach-Object { Write-Info $_ } +if ($LASTEXITCODE -ne 0) { throw "GitHub CLI not authenticated. Run: gh auth login" } + +$currentUser = (gh api /user --jq '.login' 2>&1).Trim() +Write-Info "Authenticated as: $currentUser" + +# Confirm both repos exist and are accessible +foreach ($r in @($SourceRepo, $SuccessRepo)) { + gh api "repos/$r" --jq '.full_name' 2>&1 | Out-Null + if ($LASTEXITCODE -ne 0) { throw "Cannot access repository: $r" } + Write-Pass "Accessible: $r" +} + +# Set up staging folder +if (-not $StagingPath) { + $StagingPath = Join-Path ([IO.Path]::GetTempPath()) "cohort-archive-$CohortSlug-$(Get-Random)" +} +New-Item -ItemType Directory -Path $StagingPath -Force | Out-Null +Write-Info "Staging path: $StagingPath" + +$archiveDestPath = "admin/cohorts/$CohortSlug" +$issueExportFile = Join-Path $StagingPath "registration-issues.json" +$issueCsvFile = Join-Path $StagingPath "registration-issues.csv" +$rosterFile = Join-Path $StagingPath "student-roster.json" +$discussionFile = Join-Path $StagingPath "discussions.json" +$manifestFile = Join-Path $StagingPath "ARCHIVE-MANIFEST.md" + +# --------------------------------------------------------------------------- +# 1. Export registration issues +# --------------------------------------------------------------------------- +Write-Step "Exporting registration/duplicate/waitlist issues from $SourceRepo" + +$issueLabels = @('registration', 'duplicate', 'waitlist') +$allIssues = @() + +foreach ($label in $issueLabels) { + Write-Info "Fetching issues with label: $label" + $batch = gh issue list -R $SourceRepo --label $label --state all --limit 500 ` + --json number,title,state,createdAt,closedAt,author,labels,body,comments 2>&1 | ConvertFrom-Json + if ($batch) { $allIssues += $batch } +} + +# Deduplicate by issue number +$allIssues = $allIssues | Sort-Object number -Unique +Write-Info "Total issues to archive: $($allIssues.Count)" + +if ($PSCmdlet.ShouldProcess($issueExportFile, "Write issue export JSON")) { + $allIssues | ConvertTo-Json -Depth 10 | Set-Content -Path $issueExportFile -Encoding UTF8 + Write-Pass "Written: registration-issues.json ($($allIssues.Count) issues)" +} + +# CSV with key fields only (no comments, no PII beyond GitHub username) +if ($PSCmdlet.ShouldProcess($issueCsvFile, "Write issue CSV")) { + $allIssues | ForEach-Object { + [PSCustomObject]@{ + number = $_.number + title = $_.title + state = $_.state + labels = ($_.labels | ForEach-Object { $_.name }) -join ';' + author = $_.author.login + createdAt = $_.createdAt + closedAt = $_.closedAt + } + } | Export-Csv -Path $issueCsvFile -NoTypeInformation -Encoding UTF8 + Write-Pass "Written: registration-issues.csv" +} + +# --------------------------------------------------------------------------- +# 2. Export student roster +# --------------------------------------------------------------------------- +Write-Step "Exporting student-roster.json from $SourceRepo" + +$rosterRaw = gh api "repos/$SourceRepo/contents/.github/data/student-roster.json" 2>&1 | ConvertFrom-Json +if ($rosterRaw.content) { + $rosterContent = [System.Text.Encoding]::UTF8.GetString([System.Convert]::FromBase64String(($rosterRaw.content -replace '\s',''))) + if ($PSCmdlet.ShouldProcess($rosterFile, "Write roster export")) { + Set-Content -Path $rosterFile -Value $rosterContent -Encoding UTF8 + Write-Pass "Written: student-roster.json" + } +} else { + Write-Warn "student-roster.json not found or empty in source repo -- skipping" +} + +# --------------------------------------------------------------------------- +# 3. Export discussions +# --------------------------------------------------------------------------- +Write-Step "Exporting discussions from $SourceRepo (read-only export -- cannot delete via API)" + +$owner = $SourceRepo.Split('/')[0] +$repoName = $SourceRepo.Split('/')[1] + +# Create GraphQL query payload +$graphqlPayload = @{ + query = @' +query { + repository(owner: "OWNER", name: "REPO") { + discussions(first: 100) { + totalCount + nodes { + id + number + title + createdAt + author { login } + category { name } + body + comments(first: 50) { + nodes { + author { login } + body + createdAt + } + } + } + } + } +} +'@ -replace 'OWNER', $owner -replace 'REPO', $repoName +} + +$queryJson = $graphqlPayload | ConvertTo-Json -Depth 10 +$discussions = @() + +try { + $discussionResult = $queryJson | gh api graphql --input - 2>&1 + if ($LASTEXITCODE -eq 0) { + $parsed = $discussionResult | ConvertFrom-Json + if ($parsed.data.repository.discussions.nodes) { + $discussions = $parsed.data.repository.discussions.nodes + } + } else { + Write-Warn "GraphQL request failed. Skipping discussions export." + } +} catch { + Write-Warn "Exception querying discussions: $($_.Exception.Message). Skipping discussions export." +} +Write-Info "Found $($discussions.Count) discussions" + +if ($PSCmdlet.ShouldProcess($discussionFile, "Write discussion export")) { + $discussions | ConvertTo-Json -Depth 10 | Set-Content -Path $discussionFile -Encoding UTF8 + Write-Pass "Written: discussions.json ($($discussions.Count) discussions)" +} + +if ($discussions.Count -gt 0) { + Write-Warn "MANUAL ACTION REQUIRED: Discussions cannot be deleted via the GitHub API." + Write-Warn "After verifying this archive, manually delete each discussion at:" + Write-Warn " https://github.com/$SourceRepo/discussions" + foreach ($d in $discussions) { + Write-Warn " #$($d.number) -- $($d.title)" + } +} + +# --------------------------------------------------------------------------- +# 4. Write archive manifest +# --------------------------------------------------------------------------- +$manifestContent = @" +# Cohort Archive: $CohortSlug + +Archived: $(Get-Date -Format 'yyyy-MM-dd HH:mm:ss UTC' -AsUTC) +Archived by: $currentUser +Source: $SourceRepo +Destination: $SuccessRepo/$archiveDestPath + +## Contents + +| File | Description | +|---|---| +| registration-issues.json | Full issue export with comments ($($allIssues.Count) issues) | +| registration-issues.csv | Summary CSV (number, title, state, labels, author, dates) | +| student-roster.json | Roster snapshot from .github/data/student-roster.json | +| discussions.json | Discussions export ($($discussions.Count) threads, read-only -- see note below) | + +## Post-Archive Manual Actions Required + +Issues cannot be deleted via the GitHub REST API. They have been closed and locked +by this script. To fully delete them, a repository admin must delete each one from: + https://github.com/$SourceRepo/issues?q=label%3Aregistration + +Discussions cannot be moved or deleted via any public GitHub API. They must be manually +deleted by a repository admin at: + https://github.com/$SourceRepo/discussions + +"@ + +Set-Content -Path $manifestFile -Value $manifestContent -Encoding UTF8 +Write-Pass "Written: ARCHIVE-MANIFEST.md" + +# --------------------------------------------------------------------------- +# 5. Push archive to git-going-student-success +# --------------------------------------------------------------------------- +Write-Step "Pushing archive to $SuccessRepo under $archiveDestPath" + +$successClone = Join-Path ([IO.Path]::GetTempPath()) "success-clone-$(Get-Random)" +if ($PSCmdlet.ShouldProcess($SuccessRepo, "Clone and push archive")) { + gh repo clone $SuccessRepo $successClone 2>&1 | Out-Null + $destFolder = Join-Path $successClone $archiveDestPath + New-Item -ItemType Directory -Path $destFolder -Force | Out-Null + + Copy-Item -Path (Join-Path $StagingPath '*') -Destination $destFolder -Force + + Push-Location $successClone + try { + git add . 2>&1 | Out-Null + $commitMsg = "archive: $CohortSlug cohort data ($($allIssues.Count) issues, $($discussions.Count) discussions)" + git commit -m $commitMsg 2>&1 | Out-Null + git push 2>&1 | Out-Null + Write-Pass "Archive pushed to $SuccessRepo/$archiveDestPath" + } finally { + Pop-Location + Remove-Item $successClone -Recurse -Force -ErrorAction SilentlyContinue + } +} else { + Write-Info "[WhatIf] Would push: $StagingPath -> $SuccessRepo/$archiveDestPath" +} + +# --------------------------------------------------------------------------- +# 6. Close and lock registration issues in source repo +# --------------------------------------------------------------------------- +Write-Step "Closing and locking registration issues in $SourceRepo" + +$openIssues = $allIssues | Where-Object { $_.state -eq 'OPEN' } +Write-Info "Open issues to close: $($openIssues.Count)" +Write-Info "All issues to lock: $($allIssues.Count)" +Write-Warn "Issues CANNOT be deleted via the GitHub API -- they will be closed and locked only." +Write-Warn "To delete them, a repo admin must do so manually from the GitHub UI." + +foreach ($issue in $openIssues) { + if ($PSCmdlet.ShouldProcess("#$($issue.number)", "Close issue")) { + gh issue close $issue.number -R $SourceRepo --comment "Archived to $SuccessRepo/$archiveDestPath during $CohortSlug cohort reset." 2>&1 | Out-Null + Write-Info " Closed #$($issue.number): $($issue.title)" + } +} + +foreach ($issue in $allIssues) { + if ($PSCmdlet.ShouldProcess("#$($issue.number)", "Lock issue")) { + gh api -X PUT "repos/$SourceRepo/issues/$($issue.number)/lock" -f lock_reason=resolved 2>&1 | Out-Null + } +} +Write-Pass "All $($allIssues.Count) issues closed and locked" + +# --------------------------------------------------------------------------- +# 7. Reset student-roster.json +# --------------------------------------------------------------------------- +Write-Step "Resetting student-roster.json to blank template state" + +$blankRoster = @{ + cohort = "[COHORT_NAME]" + cohortStartDate = "[YYYY-MM-DD]" + cohortEndDate = "[YYYY-MM-DD]" + facilitators = @("facilitator-username") + students = @(@{ + username = "student-github-username" + joinedDate = "YYYY-MM-DD" + mergedPRs = 0 + currentLevel = "beginner" + interests = @() + timezone = "" + }) +} | ConvertTo-Json -Depth 5 + +if ($PSCmdlet.ShouldProcess(".github/data/student-roster.json", "Reset to blank template")) { + $currentSha = (gh api "repos/$SourceRepo/contents/.github/data/student-roster.json" 2>&1 | ConvertFrom-Json).sha + $encodedContent = [System.Convert]::ToBase64String([System.Text.Encoding]::UTF8.GetBytes($blankRoster)) + + $body = @{ + message = "chore: reset student-roster.json for $CohortSlug cohort archive" + content = $encodedContent + sha = $currentSha + } | ConvertTo-Json + + $body | gh api -X PUT "repos/$SourceRepo/contents/.github/data/student-roster.json" --input - 2>&1 | Out-Null + if ($LASTEXITCODE -eq 0) { + Write-Pass "student-roster.json reset to blank template" + } else { + Write-Fail "Failed to reset student-roster.json" + } +} else { + Write-Info "[WhatIf] Would reset .github/data/student-roster.json" +} + +# --------------------------------------------------------------------------- +# Cleanup staging +# --------------------------------------------------------------------------- +if (-not $KeepStaging) { + Remove-Item $StagingPath -Recurse -Force -ErrorAction SilentlyContinue + Write-Info "Staging folder removed" +} else { + Write-Info "Staging folder kept at: $StagingPath" +} + +# --------------------------------------------------------------------------- +# Summary +# --------------------------------------------------------------------------- +Write-Host "`n=============================" -ForegroundColor White +Write-Host "Cohort archive complete: $CohortSlug" -ForegroundColor Green +Write-Host "" +Write-Host "Archive location: https://github.com/$SuccessRepo/tree/main/$archiveDestPath" -ForegroundColor Cyan +Write-Host "" +Write-Host "MANUAL ACTIONS STILL REQUIRED:" -ForegroundColor Yellow +Write-Host " 1. Delete registration issues (cannot be done via API):" -ForegroundColor Yellow +Write-Host " https://github.com/$SourceRepo/issues?q=label%3Aregistration" -ForegroundColor Yellow +if ($discussions.Count -gt 0) { + Write-Host " 2. Delete $($discussions.Count) discussion thread(s) (cannot be done via API):" -ForegroundColor Yellow + Write-Host " https://github.com/$SourceRepo/discussions" -ForegroundColor Yellow +} diff --git a/scripts/classroom/Delete-RegistrationIssues-v2.js b/scripts/classroom/Delete-RegistrationIssues-v2.js new file mode 100644 index 00000000..6f4cb2bb --- /dev/null +++ b/scripts/classroom/Delete-RegistrationIssues-v2.js @@ -0,0 +1,220 @@ +const { chromium } = require('playwright'); +const { execSync } = require('child_process'); + +/** + * Playwright script to delete locked registration issues via the GitHub UI + * + * Usage: + * node scripts/classroom/Delete-RegistrationIssues-v2.js [--headless] + */ + +const REPO = 'Community-Access/git-going-with-github'; +const ISSUES_URL = `https://github.com/${REPO}/issues?q=label%3Aregistration`; +const HEADLESS = process.argv.includes('--headless'); +const MAX_ARG_INDEX = process.argv.indexOf('--max'); +const MAX_TO_DELETE = MAX_ARG_INDEX > -1 && process.argv[MAX_ARG_INDEX + 1] + ? Number.parseInt(process.argv[MAX_ARG_INDEX + 1], 10) + : null; + +let browser; +let page; +let deletedCount = 0; +let failedCount = 0; + +function log(msg, level = 'info') { + const prefix = { + info: ' ', + pass: ' [PASS] ', + fail: ' [FAIL] ', + warn: ' [WARN] ', + step: '\n==> ' + }[level] || ' '; + console.log(`${prefix}${msg}`); +} + +async function authenticate() { + log('Getting GitHub auth context', 'step'); + try { + const token = execSync('gh auth token', { encoding: 'utf-8' }).trim(); + log('GitHub authentication ready', 'pass'); + return token; + } catch (err) { + throw new Error('GitHub CLI not authenticated. Run: gh auth login'); + } +} + +async function deleteIssue(issueNum) { + try { + log(`Deleting issue #${issueNum}...`); + + const issueUrl = `https://github.com/${REPO}/issues/${issueNum}`; + await page.goto(issueUrl, { waitUntil: 'domcontentloaded', timeout: 15000 }); + + // Wait a moment for dynamic content + await page.waitForTimeout(1000); + + // Look for the actions button (three dots) on the issue + // GitHub usually has this in the top right or in an actions menu + const detailsMenu = await page.locator('details-menu, details > summary').first(); + + // Try clicking on various elements that might open the menu + const actionButtons = [ + 'button[aria-label="Show options"]', + 'button[aria-label="Show more"]', + 'button:has-text("...")', + 'details > summary' + ]; + + let clicked = false; + for (const selector of actionButtons) { + const btn = await page.locator(selector).first(); + if (await btn.isVisible()) { + await btn.click(); + await page.waitForTimeout(500); + clicked = true; + break; + } + } + + if (!clicked) { + log(`No action menu found for #${issueNum}`, 'warn'); + failedCount++; + return false; + } + + // Look for delete option in the menu + const deleteOption = await page.locator('button, a, [role="menuitem"]').filter({ + hasText: /delete|Delete/i + }).first(); + + if (await deleteOption.isVisible()) { + await deleteOption.click(); + await page.waitForTimeout(800); + + // Handle confirmation dialog + const confirmButton = await page.locator('button').filter({ + hasText: /delete|Delete/ + }).filter({ hasText: /confirm/i }).first(); + + if (await confirmButton.isVisible()) { + await confirmButton.click(); + await page.waitForTimeout(1500); + log(`Deleted #${issueNum}`, 'pass'); + deletedCount++; + return true; + } else { + // Try any button that says delete as confirmation + const anyDelete = await page.locator('button').filter({ + hasText: /^Delete$/i + }).first(); + if (await anyDelete.isVisible()) { + await anyDelete.click(); + await page.waitForTimeout(1500); + log(`Deleted #${issueNum}`, 'pass'); + deletedCount++; + return true; + } + } + } + + log(`Could not find delete option for #${issueNum}`, 'warn'); + failedCount++; + return false; + } catch (err) { + log(`Error deleting #${issueNum}: ${err.message}`, 'fail'); + failedCount++; + return false; + } +} + +async function main() { + try { + log('GitHub Issue Deletion via Playwright', 'step'); + log(`Repository: ${REPO}`); + log(`Mode: ${HEADLESS ? 'headless' : 'headed (visible in browser)'}`); + + await authenticate(); + + log('Launching Chromium browser...', 'step'); + browser = await chromium.launch({ headless: HEADLESS }); + page = await browser.newPage(); + + await page.setViewportSize({ width: 1280, height: 720 }); + + log('Navigating to issues page...', 'step'); + log(`URL: ${ISSUES_URL}`); + await page.goto(ISSUES_URL, { waitUntil: 'domcontentloaded', timeout: 30000 }); + await page.waitForTimeout(2000); + + log('Scanning for issue links...', 'step'); + const issueLinks = await page.locator(`a[href*="/${REPO}/issues/"]`).all(); + const issueNumbers = new Set(); + + for (const link of issueLinks) { + try { + const href = await link.getAttribute('href'); + const match = href.match(/\/issues\/(\d+)/); + if (match) { + issueNumbers.add(parseInt(match[1], 10)); + } + } catch (e) { + // Skip + } + } + + let issues = Array.from(issueNumbers).sort((a, b) => a - b); + + if (Number.isInteger(MAX_TO_DELETE) && MAX_TO_DELETE > 0) { + issues = issues.slice(0, MAX_TO_DELETE); + log(`Limiting deletion to first ${MAX_TO_DELETE} issue(s) due to --max`, 'warn'); + } + + log(`Found ${issues.length} issue(s) with registration label`, 'pass'); + + if (issues.length === 0) { + log('No issues found to delete.', 'warn'); + return; + } + + console.log('\nIssues to delete:'); + issues.slice(0, 20).forEach(num => console.log(` #${num}`)); + if (issues.length > 20) { + console.log(` ... and ${issues.length - 20} more`); + } + console.log(`\nTotal: ${issues.length} issues\n`); + + log('Starting deletion sequence (browser will be visible)', 'step'); + log('This will take a few minutes. Press Ctrl+C to stop.\n'); + + for (let i = 0; i < issues.length; i++) { + const issueNum = issues[i]; + process.stdout.write(`[${i + 1}/${issues.length}] `); + await deleteIssue(issueNum); + + // Rate limit throttle + await page.waitForTimeout(800); + } + + log('Deletion sequence complete', 'step'); + log(`Successfully deleted: ${deletedCount}`, deletedCount > 0 ? 'pass' : 'warn'); + log(`Failed: ${failedCount}`, failedCount > 0 ? 'fail' : 'pass'); + + } catch (err) { + log(`Fatal error: ${err.message}`, 'fail'); + console.error(err); + process.exit(1); + } finally { + if (browser) { + await browser.close(); + } + } +} + +process.on('SIGINT', async () => { + console.log('\n\nStopping gracefully...'); + if (browser) await browser.close(); + log(`Deleted ${deletedCount} issues before stopping`, 'info'); + process.exit(0); +}); + +main(); diff --git a/scripts/classroom/Delete-RegistrationIssues.js b/scripts/classroom/Delete-RegistrationIssues.js new file mode 100644 index 00000000..0c987432 --- /dev/null +++ b/scripts/classroom/Delete-RegistrationIssues.js @@ -0,0 +1,221 @@ +const { chromium } = require('playwright'); +const fs = require('fs'); +const path = require('path'); + +/** + * Playwright script to delete locked registration issues via the GitHub UI + * + * Usage: + * node scripts/classroom/Delete-RegistrationIssues.js [--headless] + * + * Options: + * --headless Run in headless mode (default: headed for visibility) + * + * This script: + * 1. Opens the GitHub issues page filtered by registration label + * 2. Finds all locked issues with the registration label + * 3. Opens each issue + * 4. Clicks the delete button (via "..." menu) + * 5. Confirms deletion + * 6. Repeats until all issues are deleted + * + * Prerequisites: + * - GitHub CLI must be authenticated (script reads token from gh auth token) + * - You must have admin access to the repository + * - Node.js 16+ and Playwright must be installed + */ + +const REPO = 'Community-Access/git-going-with-github'; +const ISSUES_URL = `https://github.com/${REPO}/issues?q=label%3Aregistration`; +const HEADLESS = process.argv.includes('--headless'); + +let browser; +let page; +let deletedCount = 0; +let failedCount = 0; +const failedIssues = []; + +async function log(msg, level = 'info') { + const timestamp = new Date().toLocaleTimeString(); + const prefix = { + info: ' ', + pass: ' [PASS] ', + fail: ' [FAIL] ', + warn: ' [WARN] ', + step: '\n==> ' + }[level] || ' '; + console.log(`${prefix}${msg}`); +} + +async function getIssueNumbers() { + // Wait for the issues table to load + await page.waitForSelector('[role="row"]', { timeout: 10000 }); + + // Get all issue links + const issueLinks = await page.locator('a[href*="/issues/"]').all(); + const issueNumbers = []; + + for (const link of issueLinks) { + const href = await link.getAttribute('href'); + const match = href.match(/\/issues\/(\d+)$/); + if (match) { + const num = parseInt(match[1], 10); + if (!issueNumbers.includes(num)) { + issueNumbers.push(num); + } + } + } + + return issueNumbers.sort((a, b) => a - b); +} + +async function deleteIssue(issueNum) { + try { + log(`Deleting issue #${issueNum}...`); + + // Navigate to the issue + const issueUrl = `https://github.com/${REPO}/issues/${issueNum}`; + await page.goto(issueUrl, { waitUntil: 'networkidle' }); + + // Wait for the page to load + await page.waitForSelector('button[aria-label="Show options"]', { timeout: 5000 }).catch(() => null); + + // Click the "..." (options) button - try multiple selectors + let optionsButton = await page.locator('button[aria-label="Show options"]').first(); + if (!(await optionsButton.isVisible())) { + optionsButton = await page.locator('details-menu button').first(); + } + + if (await optionsButton.isVisible()) { + await optionsButton.click(); + await page.waitForTimeout(500); + + // Look for delete button - it might be in a dropdown menu + const deleteButton = await page.locator('text=/delete|Delete/i').first(); + + if (await deleteButton.isVisible()) { + await deleteButton.click(); + await page.waitForTimeout(500); + + // Confirm the deletion - there might be a confirmation dialog + const confirmButton = await page.locator('button:has-text("Delete")').first(); + if (await confirmButton.isVisible()) { + await confirmButton.click(); + await page.waitForTimeout(1000); + } + + log(`Deleted #${issueNum}`, 'pass'); + deletedCount++; + return true; + } + } + + // Fallback: try to find delete in a different location + const moreButton = await page.locator('summary:has-text("...")').first(); + if (await moreButton.isVisible()) { + await moreButton.click(); + await page.waitForTimeout(500); + + const deleteOpt = await page.locator('button, a').filter({ hasText: /[Dd]elete/ }).first(); + if (await deleteOpt.isVisible()) { + await deleteOpt.click(); + await page.waitForTimeout(500); + + const confirmBtn = await page.locator('button[type="submit"]:has-text("Delete")').first(); + if (await confirmBtn.isVisible()) { + await confirmBtn.click(); + await page.waitForTimeout(1000); + log(`Deleted #${issueNum}`, 'pass'); + deletedCount++; + return true; + } + } + } + + log(`Could not find delete button for #${issueNum}`, 'warn'); + failedCount++; + failedIssues.push(issueNum); + return false; + } catch (err) { + log(`Error deleting #${issueNum}: ${err.message}`, 'fail'); + failedCount++; + failedIssues.push(issueNum); + return false; + } +} + +async function main() { + try { + log('GitHub Issue Deletion via Playwright', 'step'); + log(`Repository: ${REPO}`); + log(`Mode: ${HEADLESS ? 'headless' : 'headed (visible)'}`); + + log('Launching browser...', 'step'); + browser = await chromium.launch({ headless: HEADLESS }); + page = await browser.newPage(); + + // Set viewport for better visibility + await page.setViewportSize({ width: 1280, height: 720 }); + + log('Navigating to issues page...', 'step'); + await page.goto(ISSUES_URL, { waitUntil: 'networkidle' }); + + log('Fetching issue numbers...', 'step'); + const issueNumbers = await getIssueNumbers(); + log(`Found ${issueNumbers.length} issue(s) with registration label`, 'pass'); + + if (issueNumbers.length === 0) { + log('No issues found. Exiting.', 'warn'); + return; + } + + // Show confirmation + console.log('\nIssues to delete:'); + issueNumbers.forEach(num => console.log(` #${num}`)); + console.log(`\nTotal: ${issueNumbers.length} issues`); + console.log('\nStarting deletion process. Browser window will be visible.'); + console.log('Press Ctrl+C to stop at any time.\n'); + + // Deletion loop + log('Starting deletion loop', 'step'); + for (let i = 0; i < issueNumbers.length; i++) { + const issueNum = issueNumbers[i]; + log(`${i + 1}/${issueNumbers.length}`, 'info'); + await deleteIssue(issueNum); + + // Throttle to avoid rate limiting + await page.waitForTimeout(1000); + } + + // Summary + log('Deletion complete', 'step'); + log(`Successful: ${deletedCount}`, 'pass'); + log(`Failed: ${failedCount}`, failedCount > 0 ? 'fail' : 'pass'); + + if (failedIssues.length > 0) { + log('Failed issues:', 'warn'); + failedIssues.forEach(num => console.log(` #${num}`)); + } + + } catch (err) { + log(`Fatal error: ${err.message}`, 'fail'); + console.error(err); + process.exit(1); + } finally { + if (browser) { + await browser.close(); + } + } +} + +// Handle Ctrl+C gracefully +process.on('SIGINT', async () => { + console.log('\n\nInterrupted. Cleaning up...'); + if (browser) { + await browser.close(); + } + log(`Deleted ${deletedCount} issues before stopping`, 'info'); + process.exit(0); +}); + +main(); diff --git a/scripts/classroom/Delete-RegistrationIssues.ps1 b/scripts/classroom/Delete-RegistrationIssues.ps1 new file mode 100644 index 00000000..e17a463c --- /dev/null +++ b/scripts/classroom/Delete-RegistrationIssues.ps1 @@ -0,0 +1,158 @@ +<# +.SYNOPSIS + Deletes locked registration issues using the GitHub GraphQL deleteIssue mutation. + +.DESCRIPTION + Fetches all issues with registration/duplicate/waitlist labels and deletes them + using the GraphQL API (which supports issue deletion, unlike the REST API). + + Prerequisites: + - GitHub CLI must be authenticated with a token that has 'repo' scope + - User must have admin permissions on the repository + + The script batches deletions to avoid rate limiting and provides progress updates. + +.PARAMETER Repo + Repository to clean. Defaults to Community-Access/git-going-with-github. + +.PARAMETER Labels + Issue labels to delete. Defaults to registration, duplicate, waitlist. + +.EXAMPLE + # Delete all registration issues + .\Delete-RegistrationIssues.ps1 +#> + +[CmdletBinding()] +param( + [string]$Repo = 'Community-Access/git-going-with-github', + + [string[]]$Labels = @('registration', 'duplicate', 'waitlist'), + + [int]$MaxToDelete = 0 +) + +$ErrorActionPreference = 'Stop' + +function Write-Step { param([string]$m) Write-Host "`n==> $m" -ForegroundColor Cyan } +function Write-Pass { param([string]$m) Write-Host " [PASS] $m" -ForegroundColor Green } +function Write-Fail { param([string]$m) Write-Host " [FAIL] $m" -ForegroundColor Red } +function Write-Info { param([string]$m) Write-Host " $m" -ForegroundColor Gray } + +# --------------------------------------------------------------------------- +# Preflight +# --------------------------------------------------------------------------- +Write-Step "Preflight checks" + +gh auth status -h github.com 2>&1 | ForEach-Object { Write-Info $_ } +if ($LASTEXITCODE -ne 0) { throw "GitHub CLI not authenticated" } + +$currentUser = (gh api /user --jq '.login' 2>&1).Trim() +Write-Info "Authenticated as: $currentUser" + +# Confirm repo access +gh api "repos/$Repo" --jq '.full_name' 2>&1 | Out-Null +if ($LASTEXITCODE -ne 0) { throw "Cannot access repository: $Repo" } +Write-Pass "Repository accessible: $Repo" + +# --------------------------------------------------------------------------- +# Fetch all issues with target labels +# --------------------------------------------------------------------------- +Write-Step "Fetching issues with labels: $($Labels -join ', ')" + +$allIssues = @() + +# Build label filter query +foreach ($label in $Labels) { + Write-Info "Fetching issues labeled: $label" + + # Use the issues endpoint with state=all to get closed and open issues + # The endpoint returns paginated results, so we need to fetch all pages + $url = "repos/$Repo/issues?state=all&labels=$label&per_page=100" + $pageNum = 1 + + do { + $pageUrl = "$url&page=$pageNum" + $batch = gh api $pageUrl 2>&1 | ConvertFrom-Json + + if ($LASTEXITCODE -eq 0 -and $batch -and @($batch).Count -gt 0) { + $allIssues += $batch + Write-Info " Found $(@($batch).Count) issue(s) on page $pageNum" + $pageNum++ + } else { + break + } + } while (@($batch).Count -eq 100) +} + +$allIssues = $allIssues | Sort-Object -Property number -Unique + +if ($MaxToDelete -gt 0) { + $allIssues = @($allIssues | Select-Object -First $MaxToDelete) + Write-Info "MaxToDelete applied: processing first $MaxToDelete issue(s) only" +} + +Write-Pass "Total issues to delete: $($allIssues.Count)" + +if ($allIssues.Count -eq 0) { + Write-Info "No issues found. Exiting." + exit 0 +} + +# Display summary +$allIssues | ForEach-Object { Write-Info " #$($_.number) -- $($_.title)" } + +# --------------------------------------------------------------------------- +# Confirm deletion +# --------------------------------------------------------------------------- +Write-Host "" +$confirm = Read-Host "Delete $($allIssues.Count) issue(s)? Type 'yes' to confirm" +if ($confirm -ne 'yes') { + Write-Info "Cancelled." + exit 0 +} + +# --------------------------------------------------------------------------- +# Delete issues via GraphQL +# --------------------------------------------------------------------------- +Write-Step "Deleting issues via GraphQL API" + +$successCount = 0 +$failCount = 0 + +foreach ($issue in $allIssues) { + Write-Info "Deleting #$($issue.number)..." + + $mutation = 'mutation($id:ID!){ deleteIssue(input:{issueId:$id}){ clientMutationId } }' + $result = gh api graphql -f query="$mutation" -F id="$($issue.node_id)" 2>&1 + if ($LASTEXITCODE -eq 0) { + $parsed = $result | ConvertFrom-Json + if ($parsed.data.deleteIssue) { + Write-Pass " Deleted #$($issue.number)" + $successCount++ + } else { + Write-Fail " Failed to delete #$($issue.number): $($parsed.errors[0].message)" + $failCount++ + } + } else { + Write-Fail " API error for #$($issue.number): $result" + $failCount++ + } + + # Rate limit throttle + Start-Sleep -Milliseconds 500 +} + +# --------------------------------------------------------------------------- +# Summary +# --------------------------------------------------------------------------- +Write-Host "`n=============================" -ForegroundColor White +Write-Host "Deletion complete." -ForegroundColor Green +Write-Host " Successful: $successCount" -ForegroundColor Green +Write-Host " Failed: $failCount" -ForegroundColor $(if ($failCount -gt 0) { 'Red' } else { 'Green' }) + +if ($failCount -gt 0) { + Write-Host "" + Write-Host "Some issues failed to delete. Check the output above for details." -ForegroundColor Red + exit 1 +} diff --git a/scripts/classroom/Initialize-WorkshopSetup.ps1 b/scripts/classroom/Initialize-WorkshopSetup.ps1 new file mode 100644 index 00000000..396f8c6e --- /dev/null +++ b/scripts/classroom/Initialize-WorkshopSetup.ps1 @@ -0,0 +1,370 @@ +<# +.SYNOPSIS + Automates all configurable workshop setup steps for Community-Access/git-going-with-github. + +.DESCRIPTION + Runs every setup action that does not require a browser: + - Sets CLASSROOM_ORG_ADMIN_TOKEN repository secret + - Sets CLASSROOM_ORG, CLASSROOM_DAY1_ASSIGNMENT_URL, CLASSROOM_DAY2_ASSIGNMENT_URL variables + - Verifies required labels exist (registration, duplicate, waitlist) + - Syncs learning-room source into Community-Access/learning-room-template + - Validates the template with a smoke repository + - Optionally seeds challenges for the test student account + + One step MUST be completed manually before running this script: + 1. Generate a classic PAT at https://github.com/settings/tokens with the admin:org scope. + Pass the token value to -AdminPAT. + + Optionally, create Day 1 and Day 2 assignments at https://classroom.github.com before + running this script. If the assignments already exist, the script will resolve their invite + URLs automatically from the GitHub Classroom API and no URL parameters are needed. + If assignments do not exist yet, the script will tell you what to create and exit cleanly. + +.PARAMETER AdminPAT + The classic GitHub personal access token with admin:org scope generated by accesswatch. + This will be stored as the CLASSROOM_ORG_ADMIN_TOKEN repository secret. + Do not commit this value anywhere. + +.PARAMETER Day1AssignmentUrl + Optional. The GitHub Classroom invite URL for the Day 1 assignment (You Belong Here). + Format: https://classroom.github.com/a/ + If omitted, the script will attempt to resolve it automatically from the Classroom API + by matching an assignment titled 'You Belong Here'. + +.PARAMETER Day2AssignmentUrl + Optional. The GitHub Classroom invite URL for the Day 2 assignment (You Can Build This). + Format: https://classroom.github.com/a/ + If omitted, the script will attempt to resolve it automatically from the Classroom API + by matching an assignment titled 'You Can Build This'. + +.PARAMETER Repo + Repository slug to configure. Defaults to Community-Access/git-going-with-github. + +.PARAMETER ClassroomOrg + The GitHub Classroom organization name. Defaults to Community-Access-Classroom. + +.PARAMETER TestStudentUsername + GitHub username of the test student account. Defaults to accesswatch-student. + When provided, the script offers to seed Day 1 and Day 2 challenges after + test student repos are confirmed to exist. + +.PARAMETER SkipTemplatePrepare + Skip the Prepare-LearningRoomTemplate.ps1 step. Use when you know the template is + already current and want to run only configuration steps. + +.PARAMETER SkipTemplateValidate + Skip the Test-LearningRoomTemplate.ps1 smoke validation step. + +.PARAMETER SkipSeed + Skip the challenge seeding step even when test student repos exist. + +.EXAMPLE + # Minimal -- assignment URLs resolved automatically from Classroom API + .\Initialize-WorkshopSetup.ps1 -AdminPAT ghp_yourTokenHere + +.EXAMPLE + # Provide URLs explicitly (e.g. if auto-resolution title matching fails) + .\Initialize-WorkshopSetup.ps1 ` + -AdminPAT ghp_yourTokenHere ` + -Day1AssignmentUrl https://classroom.github.com/a/abc123 ` + -Day2AssignmentUrl https://classroom.github.com/a/def456 + +.EXAMPLE + # Skip template steps (already up to date) + .\Initialize-WorkshopSetup.ps1 ` + -AdminPAT ghp_yourTokenHere ` + -SkipTemplatePrepare -SkipTemplateValidate +#> + +[CmdletBinding(SupportsShouldProcess)] +param( + [Parameter(Mandatory = $true)] + [ValidatePattern('^ghp_[A-Za-z0-9]+$')] + [string]$AdminPAT, + + [ValidatePattern('^https://classroom\.github\.com/a/[A-Za-z0-9_-]+$')] + [string]$Day1AssignmentUrl, + + [ValidatePattern('^https://classroom\.github\.com/a/[A-Za-z0-9_-]+$')] + [string]$Day2AssignmentUrl, + + [string]$Repo = 'Community-Access/git-going-with-github', + + [string]$ClassroomOrg = 'Community-Access-Classroom', + + [string]$TestStudentUsername = 'accesswatch-student', + + [switch]$SkipTemplatePrepare, + + [switch]$SkipTemplateValidate, + + [switch]$SkipSeed +) + +$ErrorActionPreference = 'Stop' +$scriptRoot = $PSScriptRoot + +function Write-Step { + param([string]$Message) + Write-Host "`n==> $Message" -ForegroundColor Cyan +} + +function Write-Pass { + param([string]$Message) + Write-Host " [PASS] $Message" -ForegroundColor Green +} + +function Write-Fail { + param([string]$Message) + Write-Host " [FAIL] $Message" -ForegroundColor Red +} + +function Write-Info { + param([string]$Message) + Write-Host " $Message" -ForegroundColor Gray +} + +$failures = [System.Collections.Generic.List[string]]::new() + +# --------------------------------------------------------------------------- +# Step 0: Confirm gh CLI and auth +# --------------------------------------------------------------------------- +Write-Step "Confirming GitHub CLI authentication" +gh auth status -h github.com 2>&1 | ForEach-Object { Write-Info $_ } +if ($LASTEXITCODE -ne 0) { + throw "GitHub CLI is not authenticated. Run: gh auth login -h github.com" +} + +$currentUser = (gh api /user --jq '.login' 2>&1).Trim() +Write-Info "Authenticated as: $currentUser" + +# --------------------------------------------------------------------------- +# Step 0.1: Resolve assignment URLs from Classroom API if not supplied +# --------------------------------------------------------------------------- +Write-Step "Resolving classroom assignment URLs" + +$classroomId = $null +$classrooms = gh api /classrooms --jq '.[]' 2>&1 | ConvertFrom-Json -ErrorAction SilentlyContinue +if (-not $classrooms) { + Write-Info "No classrooms found via API or API returned an error." +} else { + foreach ($c in @($classrooms)) { + if ($c.url -match $ClassroomOrg -or $c.organization.login -eq $ClassroomOrg) { + $classroomId = $c.id + Write-Info "Found classroom: '$($c.name)' (id: $classroomId) linked to $ClassroomOrg" + break + } + } +} + +if ($classroomId) { + $assignments = gh api "/classrooms/$classroomId/assignments" 2>&1 | ConvertFrom-Json -ErrorAction SilentlyContinue + if ($assignments -and @($assignments).Count -gt 0) { + Write-Info "Found $(@($assignments).Count) assignment(s) in classroom:" + foreach ($a in @($assignments)) { + Write-Info " - '$($a.title)' => $($a.invite_link)" + } + + if (-not $Day1AssignmentUrl) { + $day1Match = @($assignments) | Where-Object { $_.title -match 'You Belong Here|Day.?1' } | Select-Object -First 1 + if ($day1Match) { + $Day1AssignmentUrl = $day1Match.invite_link + Write-Pass "Day 1 URL resolved from API: $Day1AssignmentUrl" + } else { + Write-Info "Could not auto-match Day 1 assignment by title. Provide -Day1AssignmentUrl manually." + Write-Info "Available titles: $((@($assignments) | ForEach-Object { $_.title }) -join ', ')" + } + } else { + Write-Info "Day 1 URL provided via parameter: $Day1AssignmentUrl" + } + + if (-not $Day2AssignmentUrl) { + $day2Match = @($assignments) | Where-Object { $_.title -match 'You Can Build This|Day.?2' } | Select-Object -First 1 + if ($day2Match) { + $Day2AssignmentUrl = $day2Match.invite_link + Write-Pass "Day 2 URL resolved from API: $Day2AssignmentUrl" + } else { + Write-Info "Could not auto-match Day 2 assignment by title. Provide -Day2AssignmentUrl manually." + Write-Info "Available titles: $((@($assignments) | ForEach-Object { $_.title }) -join ', ')" + } + } else { + Write-Info "Day 2 URL provided via parameter: $Day2AssignmentUrl" + } + } else { + Write-Info "No assignments found in classroom yet. You must create them manually at:" + Write-Info " https://classroom.github.com" + Write-Info "Then re-run this script, or pass -Day1AssignmentUrl and -Day2AssignmentUrl." + } +} else { + Write-Info "Could not find a classroom linked to '$ClassroomOrg' via the API." + Write-Info "Classrooms available: $(if ($classrooms) { (@($classrooms) | ForEach-Object { $_.name }) -join ', ' } else { 'none' })" +} + +if (-not $Day1AssignmentUrl -or -not $Day2AssignmentUrl) { + Write-Fail "One or both assignment URLs could not be resolved. Cannot set variables without them." + Write-Host "" + Write-Host "Create the missing assignments at https://classroom.github.com using classroom id $classroomId," -ForegroundColor Yellow + Write-Host "then re-run this script. Assignment names expected:" -ForegroundColor Yellow + Write-Host " Day 1: 'You Belong Here'" -ForegroundColor Yellow + Write-Host " Day 2: 'You Can Build This'" -ForegroundColor Yellow + exit 1 +} + + +# --------------------------------------------------------------------------- +Write-Step "Setting CLASSROOM_ORG_ADMIN_TOKEN secret on $Repo" +$AdminPAT | gh secret set CLASSROOM_ORG_ADMIN_TOKEN -R $Repo --body - +if ($LASTEXITCODE -eq 0) { + Write-Pass "CLASSROOM_ORG_ADMIN_TOKEN set" +} else { + Write-Fail "Failed to set CLASSROOM_ORG_ADMIN_TOKEN" + $failures.Add("CLASSROOM_ORG_ADMIN_TOKEN secret") +} + +# --------------------------------------------------------------------------- +# Step 2: Set repository variables +# --------------------------------------------------------------------------- +Write-Step "Setting repository variables on $Repo" + +$variablesToSet = @( + @{ Name = 'CLASSROOM_ORG'; Value = $ClassroomOrg }, + @{ Name = 'CLASSROOM_DAY1_ASSIGNMENT_URL'; Value = $Day1AssignmentUrl }, + @{ Name = 'CLASSROOM_DAY2_ASSIGNMENT_URL'; Value = $Day2AssignmentUrl } +) + +foreach ($v in $variablesToSet) { + gh variable set $v.Name --body $v.Value -R $Repo + if ($LASTEXITCODE -eq 0) { + Write-Pass "$($v.Name) = $($v.Value)" + } else { + Write-Fail "Failed to set $($v.Name)" + $failures.Add($v.Name) + } +} + +# --------------------------------------------------------------------------- +# Step 3: Verify required labels +# --------------------------------------------------------------------------- +Write-Step "Verifying required labels on $Repo" + +$requiredLabels = @('registration', 'duplicate', 'waitlist') +$existingLabels = gh label list -R $Repo --json name --jq '.[].name' 2>&1 +foreach ($label in $requiredLabels) { + if ($existingLabels -contains $label) { + Write-Pass "Label '$label' exists" + } else { + Write-Fail "Label '$label' is missing -- creating it" + gh label create $label -R $Repo --color '#ededed' --description "Workshop label: $label" + if ($LASTEXITCODE -eq 0) { + Write-Pass "Label '$label' created" + } else { + $failures.Add("label: $label") + } + } +} + +# --------------------------------------------------------------------------- +# Step 4: Verify confirmed variable values by re-reading them +# --------------------------------------------------------------------------- +Write-Step "Re-reading variables to confirm values have no leading/trailing spaces" + +foreach ($v in $variablesToSet) { + $readBack = (gh variable get $v.Name -R $Repo 2>&1).Trim() + if ($readBack -eq $v.Value) { + Write-Pass "$($v.Name) confirmed: $readBack" + } else { + Write-Fail "$($v.Name) mismatch: expected '$($v.Value)', got '$readBack'" + $failures.Add("$($v.Name) value mismatch on read-back") + } +} + +# --------------------------------------------------------------------------- +# Step 5: Template preparation +# --------------------------------------------------------------------------- +if (-not $SkipTemplatePrepare) { + Write-Step "Syncing learning-room source into Community-Access/learning-room-template" + Write-Info "Running Prepare-LearningRoomTemplate.ps1..." + & "$scriptRoot\Prepare-LearningRoomTemplate.ps1" -Owner 'Community-Access' -TemplateRepo 'learning-room-template' + if ($LASTEXITCODE -eq 0) { + Write-Pass "Template preparation complete" + } else { + Write-Fail "Template preparation reported errors -- review output above" + $failures.Add("Prepare-LearningRoomTemplate") + } +} else { + Write-Info "Skipping template preparation (-SkipTemplatePrepare)" +} + +# --------------------------------------------------------------------------- +# Step 6: Template smoke validation +# --------------------------------------------------------------------------- +if (-not $SkipTemplateValidate) { + Write-Step "Running template smoke validation against Community-Access/learning-room-template" + Write-Info "Running Test-LearningRoomTemplate.ps1..." + & "$scriptRoot\Test-LearningRoomTemplate.ps1" -Owner 'Community-Access' -TemplateRepo 'learning-room-template' + if ($LASTEXITCODE -eq 0) { + Write-Pass "Template smoke validation complete" + } else { + Write-Fail "Template smoke validation reported errors -- review output above" + $failures.Add("Test-LearningRoomTemplate") + } +} else { + Write-Info "Skipping template smoke validation (-SkipTemplateValidate)" +} + +# --------------------------------------------------------------------------- +# Step 7: Seed challenges for test student (if repos exist) +# --------------------------------------------------------------------------- +if (-not $SkipSeed -and $TestStudentUsername) { + Write-Step "Checking for test student repositories to seed" + + $day1Repo = "$ClassroomOrg/you-belong-here-$TestStudentUsername" + $day2Repo = "$ClassroomOrg/you-can-build-this-$TestStudentUsername" + + $day1Exists = (gh api "repos/$day1Repo" --jq '.name' 2>&1) -notmatch 'Not Found' + $day2Exists = (gh api "repos/$day2Repo" --jq '.name' 2>&1) -notmatch 'Not Found' + + if ($day1Exists) { + Write-Info "Day 1 repo found: $day1Repo -- seeding Challenge 1" + & "$scriptRoot\Seed-LearningRoomChallenge.ps1" -Repository $day1Repo -Challenge 1 -Assignee $TestStudentUsername + & "$scriptRoot\Seed-PeerSimulation.ps1" -Repository $day1Repo -StudentUsername $TestStudentUsername + } else { + Write-Info "Day 1 test repo ($day1Repo) not found -- skipping seed." + Write-Info "Have $TestStudentUsername accept the Day 1 invite URL first:" + Write-Info " $Day1AssignmentUrl" + Write-Info "Then re-run with: .\Initialize-WorkshopSetup.ps1 ... (or run Seed-LearningRoomChallenge.ps1 directly)" + } + + if ($day2Exists) { + Write-Info "Day 2 repo found: $day2Repo -- seeding Challenge 10" + & "$scriptRoot\Seed-LearningRoomChallenge.ps1" -Repository $day2Repo -Challenge 10 -Assignee $TestStudentUsername + & "$scriptRoot\Seed-PeerSimulation.ps1" -Repository $day2Repo -StudentUsername $TestStudentUsername + } else { + Write-Info "Day 2 test repo ($day2Repo) not found -- skipping seed." + Write-Info "Have $TestStudentUsername accept the Day 2 invite URL first:" + Write-Info " $Day2AssignmentUrl" + } +} else { + Write-Info "Skipping seed step" +} + +# --------------------------------------------------------------------------- +# Summary +# --------------------------------------------------------------------------- +Write-Host "`n=============================" -ForegroundColor White +if ($failures.Count -eq 0) { + Write-Host "Setup complete. No failures." -ForegroundColor Green + Write-Host "" + Write-Host "What still requires manual action:" -ForegroundColor Yellow + Write-Host " 1. Confirm registration workflow is enabled in Actions tab:" -ForegroundColor Yellow + Write-Host " https://github.com/$Repo/actions" -ForegroundColor Yellow + Write-Host " 2. Submit one test registration issue from $TestStudentUsername to confirm end-to-end flow." -ForegroundColor Yellow +} else { + Write-Host "Setup completed with $($failures.Count) failure(s):" -ForegroundColor Red + foreach ($f in $failures) { + Write-Host " - $f" -ForegroundColor Red + } + Write-Host "" + Write-Host "Resolve failures before proceeding to registration testing." -ForegroundColor Red + exit 1 +} diff --git a/scripts/classroom/Invoke-LearningRoomEndToEndTest.ps1 b/scripts/classroom/Invoke-LearningRoomEndToEndTest.ps1 index 54be43c4..e91dcc8b 100644 --- a/scripts/classroom/Invoke-LearningRoomEndToEndTest.ps1 +++ b/scripts/classroom/Invoke-LearningRoomEndToEndTest.ps1 @@ -36,6 +36,11 @@ param( ) $ErrorActionPreference = 'Stop' +# Prevent PowerShell from converting native stderr output into terminating errors. +# Git and gh often emit progress text on stderr even when commands succeed. +if (Get-Variable -Name PSNativeCommandUseErrorActionPreference -ErrorAction SilentlyContinue) { + $PSNativeCommandUseErrorActionPreference = $false +} $script:Results = [System.Collections.Generic.List[object]]::new() $script:CreatedRepository = $false @@ -149,7 +154,10 @@ function Invoke-CheckedCommand { # Generic command execution with special transient-retry support for gh commands. for ($attempt = 1; $attempt -le $Retries; $attempt++) { if ($FilePath -eq 'gh') { + $oldErrorActionPreference = $ErrorActionPreference + $ErrorActionPreference = 'Continue' $output = & gh @Arguments 2>&1 + $ErrorActionPreference = $oldErrorActionPreference $exitCode = $LASTEXITCODE $text = ($output | Out-String).Trim() @@ -191,7 +199,10 @@ function Invoke-GhJson { ) for ($attempt = 1; $attempt -le $Retries; $attempt++) { + $oldErrorActionPreference = $ErrorActionPreference + $ErrorActionPreference = 'Continue' $output = & gh @Arguments 2>&1 + $ErrorActionPreference = $oldErrorActionPreference $exitCode = $LASTEXITCODE $text = ($output | Out-String).Trim() diff --git a/scripts/classroom/Prepare-LearningRoomTemplate.ps1 b/scripts/classroom/Prepare-LearningRoomTemplate.ps1 index 4adb3c0a..24a3f4a2 100644 --- a/scripts/classroom/Prepare-LearningRoomTemplate.ps1 +++ b/scripts/classroom/Prepare-LearningRoomTemplate.ps1 @@ -2,13 +2,20 @@ param( [string]$Owner = 'Community-Access', [string]$TemplateRepo = 'learning-room-template', - [string]$SourcePath = (Join-Path $PSScriptRoot '..\..\learning-room'), + [string]$SourcePath = '', [string]$BranchName = '', - [switch]$NoPush + [switch]$NoPush, + [switch]$SkipSourceValidation ) $ErrorActionPreference = 'Stop' +$scriptDir = if ($PSScriptRoot) { $PSScriptRoot } else { Split-Path -Parent $MyInvocation.MyCommand.Path } + +if (-not $SourcePath) { + $SourcePath = Join-Path $scriptDir '..\..\learning-room' +} + function Invoke-CheckedCommand { param([string]$FilePath, [string[]]$Arguments) & $FilePath @Arguments @@ -25,6 +32,19 @@ if (-not $BranchName) { $BranchName = 'sync/learning-room-template-' + (Get-Date -Format 'yyyyMMddHHmmss') } +if (-not $SkipSourceValidation) { + $validatorPath = Join-Path $scriptDir 'Validate-LearningRoomTemplateSource.ps1' + if (-not (Test-Path -LiteralPath $validatorPath -PathType Leaf)) { + throw "Source validator script was not found: $validatorPath" + } + + Write-Host "Validating Learning Room source before sync..." + & $validatorPath -SourcePath $source.Path +} +else { + Write-Warning "SkipSourceValidation was set. Proceeding without source sanity checks." +} + Write-Host "Checking GitHub CLI authentication..." Invoke-CheckedCommand gh @('auth', 'status', '-h', 'github.com') @@ -56,6 +76,22 @@ try { Push-Location $clonePath try { + $gitEmail = (git config user.email 2>$null) + $gitName = (git config user.name 2>$null) + if (-not $gitEmail -or -not $gitName) { + $login = (& gh api /user --jq '.login' 2>$null) + if (-not $login) { + $login = 'github-actions' + } + $fallbackEmail = "$login@users.noreply.github.com" + if (-not $gitName) { + Invoke-CheckedCommand git @('config', 'user.name', $login) + } + if (-not $gitEmail) { + Invoke-CheckedCommand git @('config', 'user.email', $fallbackEmail) + } + } + Invoke-CheckedCommand git @('add', '-A') $status = git status --short if (-not $status) { @@ -73,8 +109,14 @@ try { Invoke-CheckedCommand git @('commit', '-m', 'chore: sync learning room template') Invoke-CheckedCommand git @('push', '--force', '-u', 'origin', "HEAD:$BranchName") - $existingPr = & gh pr view $BranchName -R $fullRepo --json url --jq .url 2>$null - if ($LASTEXITCODE -eq 0 -and $existingPr) { + $existingPr = $null + try { + $existingPr = & gh pr view $BranchName -R $fullRepo --json url --jq .url 2>$null + } + catch { + $existingPr = $null + } + if ($existingPr) { Write-Host "Updated existing pull request: $existingPr" } else { @@ -99,75 +141,3 @@ finally { } Write-Host "Learning Room template is synced and ready." -[CmdletBinding(SupportsShouldProcess)] -param( - [string]$Owner = 'Community-Access', - [string]$TemplateRepo = 'learning-room-template', - [string]$SourcePath = (Join-Path $PSScriptRoot '..\..\learning-room'), - [switch]$NoPush -) - -$ErrorActionPreference = 'Stop' - -function Invoke-CheckedCommand { - param([string]$FilePath, [string[]]$Arguments) - & $FilePath @Arguments - if ($LASTEXITCODE -ne 0) { - throw "Command failed: $FilePath $($Arguments -join ' ')" - } -} - -$fullRepo = "$Owner/$TemplateRepo" -$source = Resolve-Path $SourcePath -$workRoot = Join-Path ([IO.Path]::GetTempPath()) ("learning-room-template-sync-" + [guid]::NewGuid()) -$clonePath = Join-Path $workRoot $TemplateRepo - -Write-Host "Checking GitHub CLI authentication..." -Invoke-CheckedCommand gh @('auth', 'status', '-h', 'github.com') - -Write-Host "Ensuring template repository settings..." -Invoke-CheckedCommand gh @('repo', 'edit', $fullRepo, '--enable-issues=true', '--enable-wiki=false', '--template') -Invoke-CheckedCommand gh @('api', "repos/$fullRepo/actions/permissions/workflow", '-X', 'PUT', '-f', 'default_workflow_permissions=write', '-F', 'can_approve_pull_request_reviews=true') - -New-Item -ItemType Directory -Path $workRoot | Out-Null -try { - Write-Host "Cloning $fullRepo..." - Invoke-CheckedCommand gh @('repo', 'clone', $fullRepo, $clonePath, '--', '--depth', '1') - - Write-Host "Replacing template contents from $source..." - Get-ChildItem -LiteralPath $clonePath -Force | Where-Object { $_.Name -ne '.git' } | Remove-Item -Recurse -Force - Get-ChildItem -LiteralPath $source -Force | Where-Object { $_.Name -notin @('.git', 'node_modules') } | ForEach-Object { - Copy-Item -LiteralPath $_.FullName -Destination (Join-Path $clonePath $_.Name) -Recurse -Force - } - - Push-Location $clonePath - try { - Invoke-CheckedCommand git @('add', '-A') - $status = git status --short - if (-not $status) { - Write-Host "No template changes to commit." - return - } - - Write-Host "Template changes detected:" - $status | ForEach-Object { Write-Host $_ } - - if ($NoPush) { - Write-Host "NoPush was set. Leaving changes uncommitted in $clonePath for inspection." - return - } - - Invoke-CheckedCommand git @('commit', '-m', 'chore: sync learning room template') - Invoke-CheckedCommand git @('push', 'origin', 'HEAD:main') - } - finally { - Pop-Location - } -} -finally { - if (-not $NoPush -and (Test-Path $workRoot)) { - Remove-Item -LiteralPath $workRoot -Recurse -Force - } -} - -Write-Host "Learning Room template is synced and ready." diff --git a/scripts/classroom/Reset-SupportHubEnvironment.ps1 b/scripts/classroom/Reset-SupportHubEnvironment.ps1 new file mode 100644 index 00000000..77963fa9 --- /dev/null +++ b/scripts/classroom/Reset-SupportHubEnvironment.ps1 @@ -0,0 +1,200 @@ +<# +.SYNOPSIS + Rebuilds the Git Going support environment from scratch in GitHub. + +.DESCRIPTION + This script provisions and/or repairs the support repository + `Community-Access/support` to a known-good baseline. + + Actions performed: + 1. Ensures the repository exists (creates it if missing) + 2. Enables Issues and Discussions + 3. Applies support labels + 4. Applies baseline support files (README, CONTRIBUTING, templates, workflows) + + Use this script when the support environment must be reset quickly between cohorts + or after accidental repository drift. + +.PARAMETER Owner + GitHub owner/org for the support repository. + +.PARAMETER RepoName + Support repository name. + +.PARAMETER Public + Create repository as public when auto-creating. + +.EXAMPLE + .\scripts\classroom\Reset-SupportHubEnvironment.ps1 +#> + +[CmdletBinding(SupportsShouldProcess)] +param( + [string]$Owner = 'Community-Access', + [string]$RepoName = 'support', + [switch]$Public +) + +$ErrorActionPreference = 'Stop' + +function Invoke-CheckedCommand { + param([string]$FilePath, [string[]]$Arguments) + & $FilePath @Arguments + if ($LASTEXITCODE -ne 0) { + throw "Command failed: $FilePath $($Arguments -join ' ')" + } +} + +$fullRepo = "$Owner/$RepoName" +$isPublic = $Public.IsPresent -or $true + +Write-Host "Resetting support environment for $fullRepo" +Invoke-CheckedCommand gh @('auth', 'status', '-h', 'github.com') + +$repoExists = $true +try { + & gh repo view $fullRepo 1>$null 2>$null + if ($LASTEXITCODE -ne 0) { + $repoExists = $false + } +} +catch { + $repoExists = $false +} + +if (-not $repoExists) { + $visibilityArg = if ($isPublic) { '--public' } else { '--private' } + Write-Host "Repository not found. Creating $fullRepo ..." + Invoke-CheckedCommand gh @( + 'repo', 'create', $fullRepo, + $visibilityArg, + '--description', 'Open support hub for GIT Going with GitHub alumni questions, troubleshooting, and async community help', + '--clone=false' + ) +} + +Write-Host 'Ensuring Issues and Discussions are enabled...' +Invoke-CheckedCommand gh @('repo', 'edit', $fullRepo, '--enable-issues=true', '--enable-discussions=true') + +$labels = @( + @{ Name='needs-triage'; Color='FBCA04'; Description='New issue awaiting first maintainer response' }, + @{ Name='setup'; Color='0052CC'; Description='Environment setup and installation support' }, + @{ Name='classroom'; Color='5319E7'; Description='GitHub Classroom and assignment flow support' }, + @{ Name='accessibility'; Color='0E8A16'; Description='Screen reader, keyboard, and accessibility support' }, + @{ Name='copilot'; Color='1D76DB'; Description='GitHub Copilot and AI-assisted workflow support' }, + @{ Name='good-first-answer'; Color='0E8A16'; Description='Great issue for community responders' }, + @{ Name='office-hours'; Color='B60205'; Description='Candidate topic for live office hours' }, + @{ Name='escalated'; Color='D93F0B'; Description='Needs maintainer escalation' }, + @{ Name='resolved'; Color='C2E0C6'; Description='Issue has been resolved' } +) + +Write-Host 'Applying support labels...' +foreach ($label in $labels) { + & gh label create $label.Name -R $fullRepo --color $label.Color --description $label.Description --force 1>$null 2>$null + if ($LASTEXITCODE -ne 0) { + throw "Failed to apply label: $($label.Name)" + } +} + +$scriptDir = if ($PSScriptRoot) { $PSScriptRoot } else { Split-Path -Parent $MyInvocation.MyCommand.Path } +$workRoot = Join-Path ([IO.Path]::GetTempPath()) ("support-hub-reset-" + [guid]::NewGuid()) +$clonePath = Join-Path $workRoot $RepoName + +New-Item -ItemType Directory -Path $workRoot | Out-Null +try { + Invoke-CheckedCommand gh @('repo', 'clone', $fullRepo, $clonePath) + + Push-Location $clonePath + try { + New-Item -ItemType Directory -Path '.github/ISSUE_TEMPLATE' -Force | Out-Null + New-Item -ItemType Directory -Path '.github/workflows' -Force | Out-Null + + $readme = @" + # Community Access Support Hub + + Open support hub for GIT Going with GitHub learners, alumni, and contributors. + + ## Start Here + + - Read the pinned Discussions welcome thread and posting guidance. + - Open an issue if you are blocked and need tracked troubleshooting. + - Use Discussions for Q&A, study groups, and follow-up learning. + - Search first, then post with clear reproduction details and expected behavior. + + ## Linked Repositories + + - Curriculum and workshop source: https://github.com/Community-Access/git-going-with-github + - Accessibility Agents project: https://github.com/Community-Access/accessibility-agents + - Support issues: https://github.com/Community-Access/support/issues + - Support discussions: https://github.com/Community-Access/support/discussions + "@ + [IO.File]::WriteAllText((Join-Path $clonePath 'README.md'), $readme, [Text.UTF8Encoding]::new($false)) + + $contrib = @" + # Contributing To Community Access Support + +Use this repository for support operations, troubleshooting, and learner Q&A. +Route curriculum source changes to Community-Access/git-going-with-github. + Route Accessibility Agents feature/code changes to Community-Access/accessibility-agents. +"@ + [IO.File]::WriteAllText((Join-Path $clonePath 'CONTRIBUTING.md'), $contrib, [Text.UTF8Encoding]::new($false)) + + $issueConfig = @" +blank_issues_enabled: true +contact_links: + - name: Support Hub Discussions (Q&A) + url: https://github.com/Community-Access/support/discussions + about: Use Discussions for async mentoring and community Q&A. +"@ + [IO.File]::WriteAllText((Join-Path $clonePath '.github/ISSUE_TEMPLATE/config.yml'), $issueConfig, [Text.UTF8Encoding]::new($false)) + + $firstResponse = @" +name: First Response Assistant + +on: + issues: + types: [opened] + +permissions: + issues: write + +jobs: + first-response: + runs-on: ubuntu-latest + steps: + - 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: `Thanks for opening this request. A maintainer will review it within 24 to 48 hours.` + }); +"@ + [IO.File]::WriteAllText((Join-Path $clonePath '.github/workflows/first-response.yml'), $firstResponse, [Text.UTF8Encoding]::new($false)) + + Invoke-CheckedCommand git @('config', 'user.name', 'accesswatch') + Invoke-CheckedCommand git @('config', 'user.email', 'accesswatch@users.noreply.github.com') + Invoke-CheckedCommand git @('add', '-A') + + $status = git status --short + if ($status) { + Invoke-CheckedCommand git @('commit', '-m', 'chore: reset support hub baseline') + Invoke-CheckedCommand git @('push', 'origin', 'HEAD:main') + } + else { + Write-Host 'Support repository already matched baseline content.' + } + } + finally { + Pop-Location + } +} +finally { + if (Test-Path $workRoot) { + Remove-Item -LiteralPath $workRoot -Recurse -Force + } +} + +Write-Host 'Support environment reset complete.' diff --git a/scripts/classroom/Test-LearningRoomTemplate.ps1 b/scripts/classroom/Test-LearningRoomTemplate.ps1 index b2d361e5..8ebc6d63 100644 --- a/scripts/classroom/Test-LearningRoomTemplate.ps1 +++ b/scripts/classroom/Test-LearningRoomTemplate.ps1 @@ -16,6 +16,38 @@ function Invoke-CheckedCommand { } } +function Wait-ForRepositoryContent { + param( + [string]$Repository, + [int]$MaxAttempts = 12, + [int]$DelaySeconds = 5 + ) + + for ($attempt = 1; $attempt -le $MaxAttempts; $attempt++) { + $isReady = $false + try { + & gh api "repos/$Repository/contents/.github/workflows/student-progression.yml" 1>$null 2>$null + if ($LASTEXITCODE -eq 0) { + $isReady = $true + } + } + catch { + $isReady = $false + } + + if ($isReady) { + return + } + + if ($attempt -lt $MaxAttempts) { + Write-Host "Template contents not ready yet (attempt $attempt/$MaxAttempts). Retrying in $DelaySeconds seconds..." + Start-Sleep -Seconds $DelaySeconds + } + } + + throw "Repository content did not become available in time for $Repository." +} + $template = "$Owner/$TemplateRepo" $smoke = "$Owner/$SmokeRepo" @@ -23,6 +55,9 @@ Write-Host "Creating smoke-test repository $smoke from $template..." Invoke-CheckedCommand gh @('repo', 'create', $smoke, '--private', '--template', $template) try { + Write-Host "Waiting for template content to materialize in smoke repository..." + Wait-ForRepositoryContent -Repository $smoke + Write-Host "Checking expected template files..." Invoke-CheckedCommand gh @('api', "repos/$smoke/contents/.github/workflows/student-progression.yml") Invoke-CheckedCommand gh @('api', "repos/$smoke/contents/.github/ISSUE_TEMPLATE/challenge-01-find-your-way.yml") @@ -37,6 +72,10 @@ try { finally { if (-not $KeepSmokeRepo) { Write-Host "Deleting smoke-test repository $smoke..." - Invoke-CheckedCommand gh @('repo', 'delete', $smoke, '--yes') + & gh repo delete $smoke --yes + if ($LASTEXITCODE -ne 0) { + Write-Warning "Could not delete smoke repository automatically. This does not invalidate smoke validation." + Write-Warning "Delete manually when convenient: gh repo delete $smoke --yes" + } } } diff --git a/scripts/classroom/Test-RegistrationPage.ps1 b/scripts/classroom/Test-RegistrationPage.ps1 new file mode 100644 index 00000000..2c56b12a --- /dev/null +++ b/scripts/classroom/Test-RegistrationPage.ps1 @@ -0,0 +1,323 @@ +<# +.SYNOPSIS + Validates that the workshop registration page is deployed and the registration + workflow functions end to end. Closes and locks the test issue after verification. + +.DESCRIPTION + Performs the following checks: + + 1. SITE CHECK -- HTTP GET to the deployed Pages site homepage. + 2. REGISTER PAGE CHECK -- HTTP GET to the /REGISTER page and verifies expected content. + 3. ISSUE FORM CHECK -- Confirms workshop-registration.yml exists in the repository. + 4. LABELS CHECK -- Confirms registration, duplicate, and waitlist labels exist. + 5. WORKFLOW CHECK -- Confirms registration.yml is enabled and has a recent success. + 6. LIVE TEST (optional) -- Submits a test registration issue as a configured test + account, waits for the workflow to complete, inspects the welcome comment, + then closes and locks the test issue. + + LIMITATIONS (GitHub API hard constraints): + - Test issues submitted during live testing cannot be deleted via the GitHub REST API. + The script closes and locks the issue. A repository admin must delete it manually if + desired at: https://github.com/Community-Access/git-going-with-github/issues + - This script cannot test the org-invite step of registration unless the test account + is not already a member of Community-Access-Classroom. + +.PARAMETER Repo + Repository to validate. Defaults to Community-Access/git-going-with-github. + +.PARAMETER SiteBaseUrl + Base URL for the deployed GitHub Pages site. + Defaults to https://community-access.org/git-going-with-github + +.PARAMETER RunLiveTest + Submit a live test registration issue and verify the workflow output. + Requires -TestIssueTitle to be unique enough not to match existing issues. + +.PARAMETER TestIssueTitle + Title prefix for the test registration issue. + Defaults to "[REGISTER] QA Test - Do Not Process" + +.PARAMETER WorkflowTimeoutSeconds + Seconds to wait for the registration workflow to complete during live test. + Defaults to 120. + +.EXAMPLE + # Site and config checks only (no live issue submission) + .\Test-RegistrationPage.ps1 + +.EXAMPLE + # Full live test including issue submission and workflow verification + .\Test-RegistrationPage.ps1 -RunLiveTest + +.EXAMPLE + # Full live test with custom timeout + .\Test-RegistrationPage.ps1 -RunLiveTest -WorkflowTimeoutSeconds 180 +#> + +[CmdletBinding()] +param( + [string]$Repo = 'Community-Access/git-going-with-github', + + [string]$SiteBaseUrl = 'https://community-access.org/git-going-with-github', + + [switch]$RunLiveTest, + + [string]$TestIssueTitle = '[REGISTER] QA Test - Do Not Process', + + [int]$WorkflowTimeoutSeconds = 120 +) + +$ErrorActionPreference = 'Stop' + +function Write-Step { param([string]$m) Write-Host "`n==> $m" -ForegroundColor Cyan } +function Write-Pass { param([string]$m) Write-Host " [PASS] $m" -ForegroundColor Green } +function Write-Fail { param([string]$m) Write-Host " [FAIL] $m" -ForegroundColor Red } +function Write-Warn { param([string]$m) Write-Host " [WARN] $m" -ForegroundColor Yellow } +function Write-Info { param([string]$m) Write-Host " $m" -ForegroundColor Gray } + +$failures = [System.Collections.Generic.List[string]]::new() +$warnings = [System.Collections.Generic.List[string]]::new() + +# --------------------------------------------------------------------------- +# 0. Auth check +# --------------------------------------------------------------------------- +Write-Step "GitHub CLI authentication" +gh auth status -h github.com 2>&1 | ForEach-Object { Write-Info $_ } +if ($LASTEXITCODE -ne 0) { throw "GitHub CLI not authenticated. Run: gh auth login" } + +$currentUser = (gh api /user --jq '.login' 2>&1).Trim() +Write-Info "Authenticated as: $currentUser" + +# --------------------------------------------------------------------------- +# 1. Site homepage check +# --------------------------------------------------------------------------- +Write-Step "Checking Pages site homepage: $SiteBaseUrl" + +try { + $resp = Invoke-WebRequest -Uri $SiteBaseUrl -UseBasicParsing -MaximumRedirection 5 -TimeoutSec 15 + if ($resp.StatusCode -eq 200) { + Write-Pass "Site homepage responded HTTP $($resp.StatusCode)" + } else { + Write-Warn "Site homepage returned HTTP $($resp.StatusCode)" + $warnings.Add("Site homepage HTTP $($resp.StatusCode)") + } +} catch { + Write-Warn "Site homepage request failed: $($_.Exception.Message)" + $warnings.Add("Site homepage unreachable: $($_.Exception.Message)") +} + +# --------------------------------------------------------------------------- +# 2. REGISTER page check +# --------------------------------------------------------------------------- +$registerUrl = "$SiteBaseUrl/REGISTER" +Write-Step "Checking REGISTER page: $registerUrl" + +try { + $regResp = Invoke-WebRequest -Uri $registerUrl -UseBasicParsing -MaximumRedirection 5 -TimeoutSec 15 + if ($regResp.StatusCode -eq 200) { + Write-Pass "REGISTER page responded HTTP $($regResp.StatusCode)" + + # Check for key content markers in the rendered page + $body = $regResp.Content + if ($body -match 'register|registration|Register') { + Write-Pass "REGISTER page contains expected registration content" + } else { + Write-Warn "REGISTER page loaded but expected content markers not found" + $warnings.Add("REGISTER page content markers not found") + } + + if ($body -match 'classroom\.github\.com|github\.com/Community-Access') { + Write-Pass "REGISTER page contains expected GitHub links" + } else { + Write-Warn "REGISTER page loaded but GitHub assignment/classroom links not detected" + $warnings.Add("REGISTER page GitHub links not detected") + } + } else { + Write-Fail "REGISTER page returned HTTP $($regResp.StatusCode)" + $failures.Add("REGISTER page HTTP $($regResp.StatusCode)") + } +} catch { + Write-Fail "REGISTER page request failed: $($_.Exception.Message)" + $failures.Add("REGISTER page unreachable: $($_.Exception.Message)") +} + +# --------------------------------------------------------------------------- +# 3. Issue form template check +# --------------------------------------------------------------------------- +Write-Step "Checking workshop-registration.yml issue form template" + +$formExists = gh api "repos/$Repo/contents/.github/ISSUE_TEMPLATE/workshop-registration.yml" --jq '.name' 2>&1 +if ($LASTEXITCODE -eq 0 -and $formExists -match 'workshop-registration') { + Write-Pass "workshop-registration.yml exists in .github/ISSUE_TEMPLATE/" +} else { + Write-Fail "workshop-registration.yml not found" + $failures.Add("workshop-registration.yml missing") +} + +# --------------------------------------------------------------------------- +# 4. Labels check +# --------------------------------------------------------------------------- +Write-Step "Checking required labels" + +$existingLabels = gh label list -R $Repo --json name --jq '[.[].name]' 2>&1 | ConvertFrom-Json +$requiredLabels = @('registration', 'duplicate', 'waitlist') + +foreach ($label in $requiredLabels) { + if ($existingLabels -contains $label) { + Write-Pass "Label '$label' exists" + } else { + Write-Fail "Label '$label' missing" + $failures.Add("Label '$label' missing") + } +} + +# --------------------------------------------------------------------------- +# 5. Workflow check +# --------------------------------------------------------------------------- +Write-Step "Checking registration workflow state and recent run history" + +$workflows = gh workflow list -R $Repo --json name,state,id 2>&1 | ConvertFrom-Json +$workflow = @($workflows) | Where-Object { $_.name -eq 'Registration - Welcome & CSV Export' } | Select-Object -First 1 +if ($workflow -and $workflow.state -eq 'active') { + Write-Pass "Registration workflow is active (id: $($workflow.id))" +} else { + Write-Fail "Registration workflow not found or not active" + $failures.Add("Registration workflow inactive or missing") +} + +$recentRuns = gh run list -R $Repo --workflow "registration.yml" --limit 5 --json status,conclusion,createdAt 2>&1 | ConvertFrom-Json +if ($recentRuns -and @($recentRuns).Count -gt 0) { + $lastRun = @($recentRuns)[0] + Write-Info "Most recent run: status=$($lastRun.status) conclusion=$($lastRun.conclusion) created=$($lastRun.createdAt)" + if ($lastRun.conclusion -eq 'success') { + Write-Pass "Most recent registration workflow run succeeded" + } else { + Write-Warn "Most recent registration run conclusion: $($lastRun.conclusion)" + $warnings.Add("Most recent registration run not successful: $($lastRun.conclusion)") + } +} else { + Write-Warn "No previous registration workflow runs found" + $warnings.Add("No registration workflow run history") +} + +# --------------------------------------------------------------------------- +# 6. Live test (optional) +# --------------------------------------------------------------------------- +if ($RunLiveTest) { + Write-Step "LIVE TEST: Submitting test registration issue" + Write-Warn "LIMITATION: Test issues cannot be deleted via the GitHub API." + Write-Warn "This script will close and lock the test issue after verification." + Write-Warn "To delete it permanently, use the GitHub UI after this run." + + $testBody = @" +**Name**: QA Test Account +**Pronouns**: they/them +**Time Zone**: UTC +**Assistive Tech**: None - this is an automated QA test issue. Do not process. +**Experience**: Automated test submission from Test-RegistrationPage.ps1 +**Goals**: Verify registration workflow end to end +"@ + + Write-Info "Creating test issue: $TestIssueTitle" + $issueUrl = gh issue create -R $Repo ` + --title $TestIssueTitle ` + --body $testBody ` + --label registration ` + 2>&1 + + if ($LASTEXITCODE -ne 0) { + Write-Fail "Failed to create test issue" + $failures.Add("Live test: issue creation failed") + } else { + $issueNumber = ($issueUrl -split '/')[-1] + Write-Pass "Test issue created: #$issueNumber ($issueUrl)" + + # Wait for workflow to trigger and complete + Write-Info "Waiting up to $WorkflowTimeoutSeconds seconds for registration workflow..." + $elapsed = 0 + $pollInterval = 10 + $workflowCompleted = $false + + while ($elapsed -lt $WorkflowTimeoutSeconds) { + Start-Sleep -Seconds $pollInterval + $elapsed += $pollInterval + + $runs = gh run list -R $Repo --workflow "registration.yml" --limit 3 --json status,conclusion,createdAt,databaseId 2>&1 | ConvertFrom-Json + $recentRun = @($runs) | Where-Object { $_.status -eq 'completed' } | Select-Object -First 1 + + if ($recentRun -and ([datetime]$recentRun.createdAt) -gt (Get-Date).AddSeconds(-($WorkflowTimeoutSeconds))) { + Write-Pass "Registration workflow completed: conclusion=$($recentRun.conclusion)" + $workflowCompleted = $true + if ($recentRun.conclusion -ne 'success') { + Write-Fail "Registration workflow conclusion: $($recentRun.conclusion)" + $failures.Add("Live test: workflow conclusion $($recentRun.conclusion)") + } + break + } + + Write-Info " ...waiting ($elapsed/$WorkflowTimeoutSeconds s)" + } + + if (-not $workflowCompleted) { + Write-Warn "Workflow did not complete within $WorkflowTimeoutSeconds seconds. Check Actions tab manually." + $warnings.Add("Live test: workflow timeout after $WorkflowTimeoutSeconds s") + } + + # Check for welcome comment on the issue + Write-Info "Checking for welcome comment on #$issueNumber..." + Start-Sleep -Seconds 5 + $comments = gh issue view $issueNumber -R $Repo --json comments --jq '.comments' 2>&1 | ConvertFrom-Json + if ($comments -and @($comments).Count -gt 0) { + Write-Pass "Welcome comment posted ($(@($comments).Count) comment(s) found)" + $firstComment = @($comments)[0] + Write-Info " First comment preview: $($firstComment.body.Substring(0, [Math]::Min(120, $firstComment.body.Length)))..." + + # Check for assignment links + if ($firstComment.body -match 'classroom\.github\.com') { + Write-Pass "Welcome comment contains classroom assignment link" + } else { + Write-Warn "Welcome comment does not contain classroom.github.com link (variables may not be set)" + $warnings.Add("Live test: welcome comment missing assignment links") + } + } else { + Write-Fail "No comment found on test issue #$issueNumber" + $failures.Add("Live test: no welcome comment posted") + } + + # Check labels + $issueLabels = gh issue view $issueNumber -R $Repo --json labels --jq '[.labels[].name]' 2>&1 | ConvertFrom-Json + if ($issueLabels -contains 'registration') { + Write-Pass "registration label applied to test issue" + } else { + Write-Fail "registration label not applied to test issue -- labels found: $($issueLabels -join ', ')" + $failures.Add("Live test: registration label not applied") + } + + # Cleanup: close and lock test issue + Write-Info "Closing and locking test issue #$issueNumber..." + gh issue close $issueNumber -R $Repo --comment "QA test issue. Closed by Test-RegistrationPage.ps1 after successful verification." 2>&1 | Out-Null + gh api -X PUT "repos/$Repo/issues/$issueNumber/lock" -f lock_reason=resolved 2>&1 | Out-Null + Write-Pass "Test issue #$issueNumber closed and locked" + Write-Warn "Issue #$issueNumber cannot be deleted via API. Delete it manually if needed:" + Write-Warn " https://github.com/$Repo/issues/$issueNumber" + } +} + +# --------------------------------------------------------------------------- +# Summary +# --------------------------------------------------------------------------- +Write-Host "`n=============================" -ForegroundColor White + +if ($failures.Count -eq 0 -and $warnings.Count -eq 0) { + Write-Host "All checks passed." -ForegroundColor Green +} elseif ($failures.Count -eq 0) { + Write-Host "All checks passed with $($warnings.Count) warning(s):" -ForegroundColor Yellow + foreach ($w in $warnings) { Write-Host " - $w" -ForegroundColor Yellow } +} else { + Write-Host "$($failures.Count) failure(s), $($warnings.Count) warning(s):" -ForegroundColor Red + foreach ($f in $failures) { Write-Host " [FAIL] $f" -ForegroundColor Red } + foreach ($w in $warnings) { Write-Host " [WARN] $w" -ForegroundColor Yellow } + Write-Host "" + Write-Host "Resolve failures before proceeding to cohort launch." -ForegroundColor Red + exit 1 +} diff --git a/scripts/classroom/Validate-LearningRoomTemplateSource.ps1 b/scripts/classroom/Validate-LearningRoomTemplateSource.ps1 new file mode 100644 index 00000000..8ce3b884 --- /dev/null +++ b/scripts/classroom/Validate-LearningRoomTemplateSource.ps1 @@ -0,0 +1,98 @@ +[CmdletBinding()] +param( + [string]$SourcePath = '', + [switch]$Quiet +) + +$ErrorActionPreference = 'Stop' + +function Write-Status { + param([string]$Message) + if (-not $Quiet) { Write-Host $Message } +} + +function Fail { + param([string]$Message) + Write-Error $Message + exit 1 +} + +if (-not $SourcePath) { + $scriptDir = if ($PSScriptRoot) { $PSScriptRoot } else { Split-Path -Parent $MyInvocation.MyCommand.Path } + $SourcePath = Join-Path $scriptDir '..\..\learning-room' +} + +$source = Resolve-Path $SourcePath -ErrorAction Stop +Write-Status "Validating Learning Room template source at $source" + +$requiredFiles = @( + '.github/workflows/student-progression.yml', + '.github/workflows/pr-validation-bot.yml', + '.github/scripts/challenge-progression.js', + '.github/ISSUE_TEMPLATE/challenge-01-find-your-way.yml', + 'docs/welcome.md', + 'package.json' +) + +foreach ($relativePath in $requiredFiles) { + $fullPath = Join-Path $source $relativePath + if (-not (Test-Path -LiteralPath $fullPath -PathType Leaf)) { + Fail "Required file is missing from learning-room source: $relativePath" + } +} + +$coreTemplates = Get-ChildItem -LiteralPath (Join-Path $source '.github/ISSUE_TEMPLATE') -Filter 'challenge-*.yml' -ErrorAction Stop +$bonusTemplates = Get-ChildItem -LiteralPath (Join-Path $source '.github/ISSUE_TEMPLATE') -Filter 'bonus-*.yml' -ErrorAction Stop +if ($coreTemplates.Count -ne 16) { + Fail "Expected 16 core challenge templates, found $($coreTemplates.Count)." +} +if ($bonusTemplates.Count -ne 5) { + Fail "Expected 5 bonus templates, found $($bonusTemplates.Count)." +} + +$forbiddenFilePatterns = @('*.log', '*.tmp', '*.bak', '*.orig') +$forbiddenFiles = @() +foreach ($pattern in $forbiddenFilePatterns) { + $forbiddenFiles += Get-ChildItem -LiteralPath $source -Recurse -File -Filter $pattern -ErrorAction SilentlyContinue +} +$forbiddenFiles += Get-ChildItem -LiteralPath $source -Recurse -File -Force -ErrorAction SilentlyContinue | + Where-Object { $_.Name -in @('.DS_Store', 'Thumbs.db') } + +if ($forbiddenFiles.Count -gt 0) { + $examples = ($forbiddenFiles | Select-Object -First 10 | ForEach-Object { + $_.FullName.Substring($source.Path.Length).TrimStart('\\', '/') + }) -join ', ' + Fail "Forbidden generated artifacts found in learning-room source: $examples" +} + +$scanFiles = Get-ChildItem -LiteralPath $source -Recurse -File -ErrorAction Stop | + Where-Object { + $_.Extension -in @('.md', '.yml', '.yaml', '.json', '.js', '.ts', '.txt', '.html') + } + +$forbiddenContentChecks = @( + @{ Name = 'Fine-grained/classic PAT token'; Pattern = 'ghp_[A-Za-z0-9]{20,}' }, + @{ Name = 'GitHub OAuth token'; Pattern = 'gho_[A-Za-z0-9]{20,}' }, + @{ Name = 'E2E disposable repository slug'; Pattern = 'learning-room-e2e-[0-9]{14}' }, + @{ Name = 'Smoke repository slug'; Pattern = 'learning-room-smoke-test-[0-9]{14}' } +) + +$violations = [System.Collections.Generic.List[string]]::new() +foreach ($file in $scanFiles) { + $content = Get-Content -LiteralPath $file.FullName -Raw -ErrorAction SilentlyContinue + if ($null -eq $content) { continue } + + foreach ($check in $forbiddenContentChecks) { + if ($content -match $check.Pattern) { + $relative = $file.FullName.Substring($source.Path.Length).TrimStart('\\', '/') + $violations.Add("$relative => $($check.Name)") + } + } +} + +if ($violations.Count -gt 0) { + $examples = ($violations | Select-Object -First 10) -join '; ' + Fail "Forbidden content markers found in learning-room source: $examples" +} + +Write-Status 'Learning Room template source validation passed.'